fix(ci): install and audit the committed dependency graph (#678)

[willhea]

Closes #678.

What changed

Nineteen one-word edits across three workflows, plus one regression guard.

• All eight uv sync steps (seven in ci.yml, one in corpus-parity.yml) use uv sync --locked.
• The security job's export uses uv export --locked in place of --frozen.
• All ten project-context uv run invocations use uv run --locked.

Untouched, because none of them reads the project lockfile or accepts the flag: uv python install (9), uvx pip-audit (1). update-examples.yml invokes no uv at all.

No separate uv lock --check step, per the issue: it fires on exactly the condition these commands already fail on, in exactly the runs where they already fail.

Why

When pyproject.toml and uv.lock disagreed, the test jobs and the required vulnerability audit operated on different dependency graphs, and nothing detected the mismatch. uv sync re-resolved and rewrote uv.lock inside the runner, so the tests ran against a graph that was never committed. uv export --frozen read the stale committed lockfile without checking it, so pip-audit certified a set that did not contain the new dependency.

--locked is the sibling flag that asserts rather than assumes: "Assert that the uv.lock will remain unchanged."

Why every command, and not just the install step

Corrected after review. An earlier revision argued that uv run --locked was what stood between a stale lockfile and develop. It is not. if: ${{ !cancelled() }} lets the later steps execute after a failed uv sync --locked; it does not erase that failure, so the job and the required test aggregator are red either way.

What locking every uv run actually buys is narrower and still worth having: without it, those steps still run — resolving and rewriting an uncommitted graph inside the runner, and testing against it, before anyone reads the red — and the failure is attributed to the wrong command. Defence-in-depth and correct attribution, not the merge block.

The underlying fact is that uv run is a second install path, not merely a runner; uv's docs are explicit that the project "is locked and synced before invoking the requested command."

Reproduced against uv 0.12.10 on a tree declaring a production dependency uv.lock did not contain, hashing the lockfile after each command:

command	exit	uv.lock
uv sync --locked	1	unchanged, 63d820f0…
uv export --locked	2	unchanged, 63d820f0…
uv run --locked python -c …	2	unchanged, 63d820f0…
uv run python -c … --locked	0	rewritten, 7ed9be75…
uv --project . run python -c …	0	rewritten, 7ed9be75…
uv --trusted-host example.com run python -c …	0	rewritten, 7ed9be75…

With the lockfile updated alongside the declaration, all three locked commands succeed and the new package appears in the audited export, so the fix does not block ordinary dependency work.

The guard

The rule is one sentence:

Every workflow command that can resolve the project dependency graph — uv sync, uv export, uv run — must be spelled uv <subcommand> --locked …: subcommand directly after uv, flag directly after the subcommand.

It reads no job order, no step order, no if: condition and no continue-on-error.

Two review rounds shaped this, and both findings were real. The table above is the record:

1. The first implementation searched the command text for --locked. Everything after uv run's child command belongs to that child, so uv run python -c '…' --locked passes the flag to python — the reproduction printed child got: ['--locked'] — while uv rewrites the lockfile. A substring search called that safe.
2. The replacement tokenised, but enumerated the six global options that consume a following token so it could locate the subcommand. That list cannot be complete: --trusted-host is accepted by uv and appears nowhere in uv --help. The parser skipped the option but not example.com, read that value as the subcommand, and returned "not a uv command". setup-uv installs an unpinned uv, so the list would have drifted regardless.

So the list is gone. A uv command whose first argument is an option is now reported as unasserted whenever a resolving subcommand appears anywhere in it, rather than parsed. Enforcing the canonical shape needs no knowledge of option arity and fails closed on exactly the case it cannot read.

The fail-closed branch is deliberately narrow — it requires a resolving subcommand to be present — so unrelated uv commands are left alone. Parser verdicts across every spelling in play:

verdict	command
('run', False)	uv --trusted-host example.com run python -c 'print(1)'
('run', False)	uv --project . run pytest -v
('run', False)	uv run python -c 'print(1)' --locked
('run', True)	uv run --locked pytest -v
('sync', True)	uv sync --locked
('export', True)	uv export --locked --format requirements-txt -o r.txt
None	uv --version
None	uv python install 3.12
None	uvx pip-audit -r r.txt
None	uv build --wheel

The canonical requirement is stricter than uv's own parser, which would also accept --locked later among uv's options. Deliberately: it is the one position that cannot silently belong to a child command, and #672 is this repository's record of what a convention admitting unchecked variation costs.

Tests

The live invariant, plus two parameterised controls.

Negative — each is a way to resolve an uncommitted graph while looking correct:

id	why it is unsafe
bare-sync	re-resolves and rewrites
frozen-export	reads the lockfile without checking it
bare-run	resolves despite the locked sync before it
locked-after-child-command	flag goes to the child; uv never sees it
global-option-before-subcommand	invisible to an adjacency pattern
undocumented-global-option	--trusted-host, absent from uv --help

Positive — commands that resolve nothing and must not be swept up by the fail-closed branch: uv --version, uv python install, uvx pip-audit, uv build. Without these, widening the branch to "any uv -" would go unnoticed.

No positive control for the canonical spelling itself: the live workflows supply it, since all nineteen resolving commands carry the flag, so a rule that rejected everything would redden there.

Verification

Each mutation applied to a real workflow file, test run, failure observed, file restored. Live guard red, 31 others green, every time:

mutation	note
uv --trusted-host example.com run --locked pytest …	carries a correct --locked that uv would honour; reported anyway because the spelling cannot be verified
--locked removed from a uv sync
the export's --locked back to --frozen
--locked removed from a uv run

No pre-existing test fires on any of them.

Local gates. tests/test_ci_workflow.py 32 passed; fast suite 2085 passed / 4 skipped / 15 xfailed; ruff check and ruff format --check clean; packaging gate 7 passed — confirming --locked on the dev-environment commands does not interfere with the uv build / uv pip install the gate performs internally.

Caveat: measured in a worktree lacking the gitignored fetched corpus, which reports 4 skips where the main checkout reports 1. None relate to this change.

Scope of the guard

.github/workflows only. The uv run lines in AGENTS.md and CONTRIBUTING.md are documentation for a developer's own machine, where a rewritten lockfile appears in git status rather than silently inside a runner.

Out of scope

Pinning the setup-uv action to a SHA, or pinning an exact uv version. Current Astral guidance recommends both, and the --trusted-host finding is a reminder that an unpinned uv can change under the workflows — but that is repository-wide work rather than part of this issue and belongs in its own change.

Not covered

• Whether any merged pull request has previously shipped a pyproject.toml change without its lock update. Not searched.
• Runtime cost of the assertion in CI. Expected negligible, since it is a comparison against a graph uv resolves anyway, but not measured as such.
• dependabot.yml interaction. Dependabot's uv updates normally carry the lock change, so its pull requests are probably not an exposed path; not checked.