build: couple the grpcio-tools floor to the committed protobuf gencode

[jonathanstokes]

The trap

ADR-0001 says the generated bindings and the protobuf pin are one unit. Nothing enforced it.

grpcio-tools carries its own copy of protoc, so whichever version is installed is what decides the gencode written into pyquadcortex/protocol/proto/*_pb2.py. The committed bindings are stamped 7.35.1. The dev extra's floor was grpcio-tools>=1.68, and resolved at its lowest that gives 1.82.1, whose protoc emits 7.35.0.

So running scripts/compile_protos.sh after a clean pip install -e ".[dev]" could quietly move the bindings one patch backwards, and nothing anywhere would say so. The protobuf runtime validates runtime >= gencode and nothing else, so older bindings import cleanly and pass the entire suite while pyproject.toml keeps claiming a pin the tree no longer matches.

The failure is quiet in the direction that matters. A gencode that is too NEW is a hard ImportError for every user and gets caught immediately. A gencode that is too OLD looks exactly like success.

It gets worse than one patch outside a clean resolve. A venv that picked up grpcio-tools some other way, or the script's fallback to a system protoc, is bounded by nothing at all - grpcio-tools 1.68.0 emits gencode 5.28.1, seven minors back.

What the versions actually are

The floor is not derivable from package metadata, and the two version lines do not track each other. Each of these was installed and run, and the stamp it writes was read:

grpcio-tools	libprotoc	gencode it emits	what its metadata declares
1.68.0 (the old floor)	28.1	5.28.1	protobuf>=5.26.1,<6
1.81.1	33.5	6.33.5	protobuf>=6.33.5,<7
1.82.0	35.0	7.35.0	protobuf>=6.33.5,<8
1.82.1	35.0	7.35.0	protobuf>=7.35.1,<8
1.83.0 (latest)	35.1	7.35.1	protobuf>=7.35.1,<8

Look at 1.82.1. It declares a protobuf floor of 7.35.1 and still emits gencode 7.35.0. The declared dependency is a runtime floor, not the gencode stamp, and reading it as the mapping gets the wrong answer by one patch - which is exactly enough to walk the pin backwards. Ask the compiler, never the metadata.

Two corrections to the report that started this, since both change what the fix has to be:

• grpcio-tools 1.83.0 does not emit gencode 5.29.3. It emits 7.35.1, which is why the venv on this machine was never actually wrong. The hole was in the floor, which allowed versions nobody had checked.
• 1.68.0 was not reachable through the documented install. It requires protobuf<6, which the project's own protobuf>=7.35.1,<8 rules out, so the resolver cannot land on it. The reachable exposure was 1.82.1 at one patch. The hole is real either way, and the reachable case is the better argument for closing it.

What changed

The floor. grpcio-tools>=1.68 becomes grpcio-tools>=1.83.0, the oldest release whose protoc emits gencode 7.35.1, with the reason written next to it in pyproject.toml. 1.83.0 is the current latest (released 2026-07-23; wheels for cp310 through cp314 on Linux, macOS and Windows), so the floor is the newest release. That is not a problem to route around: this is a dev-only extra, and the floor has to move with the gencode anyway.

A gate at regeneration. scripts/compile_protos.sh now generates into a temporary directory, compares the gencode it produced against the bindings already in the tree, and refuses to install anything older. On refusal it writes nothing, so the tree is exactly as it was, and the message names both versions and how to fix it. Because the gate reads generator OUTPUT rather than a package version, it covers the system-protoc fallback too.

A check in CI. tests/test_packaging.py asserts three things about the committed state, offline and with no toolchain: all bindings carry one gencode, the pin's floor equals that gencode, and the pin's ceiling is one major above it.

Why both, and not one

They catch different routes and neither covers the other.

The script is the only guard that can stop the downgrade before it reaches the tree, and it is where the mistake is actually made, so it is the right place for the explanation. But it never runs in CI, so it cannot police what lands on main, and it only sees gencode that arrives through the script.

The test is the only guard that runs on every PR, needs no protoc, and holds for gencode that arrived any other way - a hand edit, an IDE-run protoc, a pin bumped without regenerating. But it fires after the files are already overwritten, and it cannot say "your generator is too old" because the offline suite has no generator to ask.

Recorded as ADR-0008, with the rejected options.

Two things the ADR is explicit about, because both are easy to overread:

• The pin floor and the committed gencode must be equal, not merely compatible. A floor above the gencode still imports for everybody, which is precisely why it needs catching.
• What CI proves is the bindings-to-pin half. Nothing machine-checks the grpcio-tools floor itself - judging a floor means running that generator, and the offline suite has none. A future gencode bump that updates the bindings and the pin but forgets the floor leaves CI green until the next regeneration, where the script catches it and names the stale floor as the cause. That residual exposure is a delay, not a silent pass.

Test plan

• 514 passed, 1 skipped on the offline suite, in a fresh worktree venv built from the new dev extra (uv venv && uv pip install -e ".[dev]", resolving to grpcio-tools 1.83.0 / protobuf 7.35.1)
• The three new tests were each made to fail on purpose by temporarily editing the committed stamps: one file at 7.35.0 (mismatched generators), both at 7.35.0 (floor above gencode), both at 8.36.0 (floor below gencode, and a ceiling left behind a major). Every message named the problem and what to move. Bindings restored with git checkout after each
• scripts/compile_protos.sh against grpcio-tools 1.83.0: byte-identical to what is committed, tree clean
• Against 1.82.1 (7.35.0, one patch back) and 1.68.0 (5.28.1): refused, exit 1, git status on the bindings directory empty in both cases
• Against a tree whose bindings carry no version stamp at all: refused. This one had to be fixed first - see below
• older_than checked against 8 cases, including unequal component counts (7.35 vs 7.35.1) and two-digit fields (7.9.0 vs 7.35.1, 10.0.0 vs 9.9.9)
• The resolver claims above were checked with uv pip compile --resolution lowest-direct on the old constraint set, and by trying to install 1.68.0 alongside the project's own protobuf pin

The bindings are not regenerated here. They are byte-identical to main. Regenerating is its own change with its own pin bump, per ADR-0001 and CLAUDE.md.

Reviewer notes

Seven findings across a pre-PR self-review and a triage pass. Six fixed, in c927428 and b26572a; both commits are worth reading on their own. The two that mattered:

1. The gate could fail open on the case it should trust least. gencode_of returned an empty string both for "file is missing" and for "file carries no version stamp", and the loop read them as one: nothing to compare, skip. Bindings from a pre-stamp protoc have no stamp line at all, so that path would have waved in any generator. Reproduced before fixing: with both stamps stripped, a 7.35.0 generator wrote over 7.35.1 bindings and exited 0. Missing and unstamped are separate answers now, and unstamped refuses.
2. The gate could also fail open on a SIGPIPE race. Both version helpers piped into head -1, and under set -o pipefail a producer that takes SIGPIPE when head exits early fails the whole pipeline; inside $(...) that returns an empty string, which the comparison reads as "not older". Both helpers are single awk processes now, with no pipe to race.

Also fixed: the ADR's overstated magnitude and its "proved in CI" claim (both above); protobuf\b in the test matching protobuf-stubs; a bare "No such file or directory" when protoc writes nothing; and messages saying "committed" while comparing against the working tree.

Not fixed, deliberately: _bound mis-parses pin shapes it does not expect (<=, ~=, environment markers). Every one of them fails the assert rather than passing it, and the message prints the pin string it parsed, so the misdirection is one line deep. ADR-0001 fixes the shape of this pin; handling others is speculative generality.