[Deep-Sixed]

Builds on #28, which is now merged. This carries forward the ref-transaction boundary from #10, rebuilt on #18's content-governance hook.

Problem

On main, pre-receive uses up approvals and saves that to the store before Git moves the ref. Two things can then go wrong:

• Approval wasted: Git can still refuse the update after pre-receive (another hook, a lost ref lock, receive.denyNonFastForwards), but the approval is already spent.
• Stale authority: a claim release, takeover or handoff that happens in that window lets a push land on authority that no longer holds.

Changes

• pre-receive checks but spends nothing. docs: state the minimum Git version (2.17) #18's checks are unchanged. It now records each validated ref update in ref_updates (migration 006_ref_updates.sql), together with its changed paths and governed operations.
• Transaction hook, prepared stage. A managed reference-transaction hook re-checks every recorded update while Git holds the ref locks and can still abort. Approvals are used up only here, and any failure aborts the update.
  • It re-checks using the paths pre-receive recorded. If one push updates two refs that share a new commit, the first ref's update makes that commit known before the second ref is checked. Recomputing the paths then would find nothing to govern.
• committed / aborted stages record the outcome. An abort after prepared makes the used-up approvals usable again, unless a newer live approval now exists for the same operation.
• Fail closed:
  • Only transactions without an agent identity (maintenance run inside the hub) pass through.
  • An identified transaction without a fresh validation from pre-receive is rejected, and so is one arriving while the store is missing.
  • HEAD, which Git lists alongside the ref it points to, is left to that ref's own line.
• Hook installation. Pre-receive refuses pushes if the transaction hook is missing, modified or not executable. hook install writes both hooks, inspects both paths before writing either, and requires Git 2.28.
• doctor settles updates stuck in prepared by reading the ref itself. At the new value means committed; still at the old value means aborted, and --repair restores the approvals. If the ref has moved elsewhere or is still locked, it's reported for manual inspection, never guessed.
• Follow-up to Verify the full schema contract and harden commit and CLI inputs #28's review: the schema-contract check now compares SQL as a sequence of tokens. Keyword case, whitespace and comments no longer make an object look altered; quoted literals and identifiers still have to match exactly. This addresses Codex's P2 finding on Verify the full schema contract and harden commit and CLI inputs #28, which arrived after Verify the full schema contract and harden commit and CLI inputs #28 had merged.

Notes for reviewers

• Git minimum: the documented minimum rises from 2.17 to 2.28 for hub push enforcement, since that's the first release with the reference-transaction hook. The local model still needs only 2.17.
• Upgrading an existing hub: re-run quorumgit hook install --repo <name>. Until then, pushes are rejected with a message saying the transaction hook is missing.
• Interaction with Measure claim scopes against the mainline, not every ref #29: Measure claim scopes against the mainline, not every ref #29 splits the changed paths into two lists, paths for protected paths and scope_paths for claim scopes. Whichever of Measure claim scopes against the mainline, not every ref #29 and this PR merges second must record both lists in pre-receive and replay both at prepared. A worked example is the "Merge Measure claim scopes against the mainline, not every ref #29 …" commit on claude/fervent-darwin-65ds9y.

Tests

tests/test_transaction_boundary.py has 26 tests.

• 21 are carried from Bind push authorization to Git's ref transaction; scope enforcement and full schema contract #10 and adapted to docs: state the minimum Git version (2.17) #18's hook.
• 2 new ones cover content governance:
  • a push needing an out_of_scope_push approval keeps it when a later hook refuses the update, then uses it on a successful retry;
  • a push updating two refs that share a commit still uses up its out-of-scope approval. If prepared recomputes the paths instead, this test fails and the push lands ungoverned.
• 3 are ported from the handover comment below, written by a session that rebuilt this boundary on Bind push authorization to Git's ref transaction; scope enforcement and full schema contract #10's branch:
  • a force push refused by receive.denyNonFastForwards keeps its approval. This test fails on current main, where the approval is used up and the branch doesn't move;
  • an update needing two approvals uses up both at prepared and restores both on abort;
  • a non-atomic push of main and a claimed branch still matches its approved out-of-scope operation.

tests/test_hardening.py gains tests for the token-based schema comparison: formatting-only differences are accepted, a changed literal is still rejected.

Validation

• pytest tests -q: 225 passed
• pyright: 0 errors
• ruff check (the pinned 0.16.9): no findings

🤖 Generated with Claude Code

https://claude.ai/code/session_01Q8BpCkArA34hB1aSyVcnZp

[Deep-Sixed]

This is a handover from another session. I didn't see that #10 had been closed, and rebuilt the same transaction boundary on #10's branch. It ended up close to this PR's design: migration 006, paths recorded in pre-receive and replayed at prepared, and several approvals per update. That work is redundant now, but it contains three regression cases this PR's tests/test_transaction_boundary.py doesn't seem to cover, plus a follow-up for #29.

All of it is at 44a6b5f on claude/fervent-darwin-65ds9y, in tests/test_transaction_boundary.py (bottom section). My merge commits sit on top of your 4edf457, which is unchanged.

Tests worth porting

1. test_approval_survives_a_non_fast_forward_git_denies_by_config: the hub sets receive.denyNonFastForwards=true, which git init --shared also turns on. Git checks it after pre-receive, so an approved force-push is refused at that point. The approval must stay approved, and the retry must use it. On main today, the approval is consumed and the branch doesn't move.
2. test_every_approval_of_one_update_is_consumed_and_restored_together: a push to protected main that also edits a protected path needs two approvals. Both must be consumed at prepared and both restored on aborted. In my version the approvals were linked in a ref_update_approvals table; with your approval_ids column, the assertion that counts linked rows would check that array instead.
3. test_prepared_uses_the_paths_pre_receive_derived: a non-atomic push of main (approved) and a claimed work/x whose commits include main's new commit. Git commits main first, so recomputing paths at work/x's prepared stage shrinks its out-of-scope set. The approved hash then no longer matches and Git aborts a fully approved push. I confirmed the test fails when prepared recomputes paths. Your test_prepared_checks_the_paths_pre_receive_derived may already cover this; if it does, ignore this one.

Follow-up once #29 merges
#29 splits the changed paths in two: paths, measured against every ref, for protected paths; and scope_paths, measured against the branch's previous value plus the default branch and protected refs, for claim scopes. It adds a scope_paths argument to governed_operations. This PR's pre-receive would need to record scope_paths too, and prepared would need to replay both lists. The merge commit "Merge #29 …" in the same range shows one way to do it.

---

Generated by Claude Code