Compatibility surface has zero headroom, which blocks every decomposition of a pinned file

[lamemustafa]

The measurement

On origin/master (b854369b):

MAX_SURFACE_FILES     = 217   (tools/bridge-tally-compatibility/src/lib.rs:46)
RESERVED_SURFACE_FILES = 15   (:23)
surface.files.len()   = 217
headroom              = 0

validate_shape rejects a surface above MAX_SURFACE_FILES, so any PR that adds a pinned file fails the gate until the cap is raised. #406 already raised it once today to make room for dependency-security-scheduled.yml, and that consumed the last of the slack.

Why this blocks more than it looks like

Thirteen of the fourteen largest production files are pinned:

lines	file
6486	bridge-tally-protocol/src/lib.rs	PINNED
5919	db/tally_mirror.rs	PINNED
5441	tally/runtime.rs	PINNED
4684	commands.rs	PINNED
3872	tally/connection.rs	PINNED
3669	sync/snapshot.rs	PINNED
2740	bridge-tally-compatibility/src/lib.rs	PINNED
2569	sync/reconciliation.rs	PINNED
2488	agent_import.rs	PINNED
2481	agent_lab_import.rs	unpinned
2444	source_draft/catalog.rs	PINNED
2333	bridge-tally-core/src/master_binding.rs	PINNED
2278	bridge-tally-core/src/book_presence.rs	PINNED
2144	tally/connector.rs	PINNED

Decomposing any of them adds files. Adding files needs headroom. There is none.

The part that is a hole rather than an inconvenience

When a pinned file is split, the extracted part is unpinned by default and nothing warns you. The parent's hash changes, scripts/reseal.sh succeeds, --verify passes — and the moved code is now outside the sealed surface. Coverage shrinks by exactly what was extracted, silently, with every check green.

That is not hypothetical. #395 moved 8,465 lines out of two pinned files (tally_mirror.rs → tally_mirror_tests.rs, snapshot.rs → snapshot_tests.rs) and neither extracted file is pinned today. It happens to be consistent with the existing norm — 59 of 63 *_tests.rs in the tree are unpinned — so nothing was lost that the surface was meaningfully protecting. But nobody decided that; it fell out of the mechanics. The same move applied to production code would quietly move real protocol logic out of the seal.

What this issue is asking for

Two decisions, both the owner's:

1. How much headroom should the cap carry, and should the cap track the count automatically rather than being raised by hand each time it binds? The current assertion MAX - len <= RESERVED protects against an inflated cap, so raising it is deliberately friction-ful — which is defensible, but it means routine refactoring now competes with that friction.
2. Should splitting a pinned file be required to pin the parts? If yes, the tooling should refuse a decomposition that drops coverage, rather than leaving it to whoever remembers. A check comparing "paths pinned before" against "paths pinned after, plus files whose content moved" would catch it.

Not asking to remove the cap

The cap is doing real work and the reserve assertion is a sensible guard against it drifting upward unnoticed. The problem is only that it currently sits exactly on the boundary, so the next legitimate change pays for it.

Found while scoping the large-file decomposition work; recording rather than working around it.

[lamemustafa]

The hole is wider than "extraction leaves the child unpinned". It has already arrived without anyone splitting anything.

Raised by bridge-97 from their own lane and verified here against origin/master:

src-tauri/src/agent_import.rs is pinned. Every one of its six direct child modules is not:

lines	file
641	agent_import_post.rs	unpinned
402	agent_import_cash_bank.rs	unpinned
187	agent_import_persistence.rs	unpinned
71	agent_import_schema.rs	unpinned
35	agent_import_identity.rs	unpinned
0	agent_import_desktop_journal.rs	unpinned

1,336 lines of collaborators outside the seal, under a sealed parent.

agent_import_cash_bank.rs is the sharpest case: it holds LegRequirement and the rules deciding which side the cash/bank ledger must sit on for Payment versus Receipt versus Contra, including the guard against a Contra being filed into the Payment register — which its own comment notes Tally "accepts without complaint". So the module that renders the qualified write shape is sealed and the module that decides it is not. agent_import_post.rs is the other one worth an explicit decision, being the posting path.

Some of these exclusions may well be deliberate. The manifest cannot say which, because it records paths and not reasons. That is the actual problem: the seal's boundary is currently an accident of history rather than something anyone can review, and the file-count cap makes correcting it compete with routine work.

On the mechanism, bridge-97 confirmed it from the tool contract rather than by testing, and it is conclusive: rehash-surface rehashes the paths listed in the manifest, and --verify reseals into a scratch copy and diffs over that same list. Neither command has any notion of "a file that should be pinned and is not". So an unpinned collaborator is not a check that fails — it is a check that was never asked.

This widens decision 2 in the original post. Rather than only "should splitting a pinned file be required to pin the parts", the question is whether the surface should assert anything about a pinned file's neighbours — for example, that a pinned file's mod children are pinned or carry a recorded exemption, the way .cargo/audit.toml records per-crate reachability and a review date instead of a bare ignore.

Conventions written up in docs/module-decomposition.md (PR to follow); both instances are listed there so the next person decomposing a module does not rediscover them.

[lamemustafa]

Correcting my own framing. I was about to raise the cap and stopped after reading the constant's own documentation, which argues against exactly that.

RESERVED_SURFACE_FILES is documented as "Capacity deliberately reserved for one small cohesive surface change", and the rationale on MAX_SURFACE_FILES says the reserve "covers a small cohesive feature (source, tests, docs and manifest) but makes further unreviewed additions an explicit compatibility-surface decision" — closing with "one file for one named reason — not headroom."

So "zero headroom" is not the design failing. It is the design working. The cap has been raised four times, each with its reason recorded in the comment, and the comment notes the first three were "by branches that did not see each other" — which is precisely the drift the friction exists to prevent. Restoring a general 15-slot buffer would convert a deliberate control into the thing it was written to refuse.

So decision 1 in my original post is withdrawn. The right pattern is the one #406 already followed: a decomposition raises the cap by its own count, in its own PR, with its own named reason, and pins what it adds. That is more friction than routine refactoring usually carries, and on this repository that is the point — the surface is an evidence boundary, not a file list.

What remains, and it is the part worth keeping open, is the silent-shrink hole, which this same comment makes a stronger case for than I did:

"a merge that keeps a raise but loses its pin would pass the gate with behavior silently outside the evidence boundary, which is the failure this constant exists to make loud."

The authors already identified the adjacent case — a raise surviving a merge while its pin does not. The extraction case is the same failure arriving by a different route: split a pinned file and the extracted code leaves the evidence boundary with no raise, no pin, and nothing loud at all. rehash-surface hashes the paths the manifest lists; an extracted file is not one, so it is never examined. Not a check that fails — a check nobody asked.

And agent_import.rs's six unpinned children show the boundary can drift without any split at all.

Revised ask, narrower than the original: one decision, not two — should the surface assert anything about a pinned file's neighbours? Either that a pinned file's mod children are pinned, or that each exclusion carries a recorded reason, the way .cargo/audit.toml records per-crate reachability and a review date rather than a bare ignore. That would make the boundary reviewable without weakening the cap.

The conventions document (#417) has been corrected to match: it no longer implies headroom should exist, and states the per-decomposition raise as the pattern.

[lamemustafa]

The hole is bigger than this issue records, and its shape argues for a different decision than "how much headroom".

Measurement

Every unpinned file whose declaring module is pinned, split by kind:

	files	lines
test children (*_tests.rs / cfg(test))	17	17,285
production children	33	14,674

The test half matches the norm already noted here (59 of 63 *_tests.rs unpinned) and I am not arguing with it. The agent_import.rs figure from the comment above reproduces exactly: 1,336 lines over five production children.

Line count is the wrong axis

The criterion MAX_SURFACE_FILES actually states is "a file that decides what Bridge admits", and for the workflow raise, "what Bridge is allowed to do to its own repository while nobody is watching." Judged against that rather than size, the 33 split 21 meet it, 12 do not — and the split does not track line count at all. The single largest file in the set, agent_lab.rs (1,342 lines), is one of the clearest exclusions.

Excluded because they cannot decide anything in a shipped build (3,979 lines): agent_lab.rs, jsonex.rs, jsonex_request.rs, india_tax_observation.rs — all behind non-default features. bridge-tally-protocol declares default = [], src-tauri forwards none of them, and CI's own step for these is named "Test disabled protocol evidence features". Also excluded: client_groups.rs and its migration (operator filing labels; a label never selects a book), gst/mod.rs (dead — commands.rs:2885 hard-errors before constructing it), and four module declarations totalling 79 lines.

The closest exclusion call was agent_import_schema.rs: it looks like the admission contract, but the shared walker enforces only top-level required/additionalProperties and the array bounds, and every bound it states is re-enforced at the typed boundary in the pinned agent_import.rs. It changes what Bridge publishes to the model, not what it admits.

The 21 that meet it, by what they decide

Admission into a customer's book (9): approved_import.rs (the consent decision itself — result.success() is what makes the dialog binding, and the exact-button match is what stops Escape approving), agent_import_post.rs (the only POST path, and the dispatched guard that stops one approved batch posting twice), agent_company.rs (matches.len() != 1 — the sole company-identity gate, consumed by every read tool and by import), agent_import_cash_bank.rs (the money/non-money reserved-group tables), group_ancestry.rs (the shared ancestry walk beneath all of the above), agent_import_identity.rs (derives the REMOTEID the pre-existing-identity refusal depends on), agent_import_persistence.rs (blocks admission over an interrupted publication), runtime_control.rs (the retry classifier that actually honours SINGLE_ATTEMPT — widen it and an ambiguous import response is re-sent), endpoint_coordination.rs (the cross-process dispatch lease taken immediately before the POST).

Egress and the receipts attesting it (5): documents.rs and axal.rs (origin allowlists for customer data; axal.rs also sets Policy::none() so credentials are not forwarded through a redirect), agent_protocol.rs (persists the egress receipt before the stdout write), agent_egress.rs (the append-with-rollback and the partial-row refusal), agent_delivery.rs (what the receipt hashes — hash a different string and every receipt attests something else).

Figures reported to a CA (5): agent_movement.rs, agent_outstandings.rs (the ageing buckets and the receivable/payable split), agent_movement_math.rs (closing = opening + debit + credit, and the partial state), agent_change_parse.rs and agent_changes.rs (whether a caller may advance its cursor past unread rows).

Borderline (2): agent_receipt_fields.rs (the only place "record the key path, never the value" is executed), observability.rs (the count-bucketing privacy reduction).

The part I would actually put in front of a decision

The pinned set already contains the sibling of nearly every one of these. Verified against the manifest:

pinned	unpinned
tally/runtime.rs	tally/runtime_control.rs — honours its SINGLE_ATTEMPT
agent_import.rs	agent_import_post.rs — holds the POST and its idempotency guard
agent_catalog.rs (argument admission)	agent_company.rs (company-identity admission)
agent_ledgers.rs	agent_movement.rs
agent_vouchers.rs	agent_outstandings.rs
agent_trial_balance.rs	agent_movement_math.rs
native_outstandings/compute.rs	group_ancestry.rs — every caller pinned, the walk itself not

That is the finding. The boundary is not a considered line that happens to be tight; in these seven pairs it is an artifact of which file existed when a cap was last raised. master_binding.rs was pinned for precisely the reason that applies to agent_company.rs, and the reasoning did not transfer because nothing carried it.

What I am not doing

Not proposing a cap number. The constant says "one file for one named reason — not headroom", and I was about to raise it once before and stopped for that reason. Twenty-one named reasons is not the same as headroom, but whether they are twenty-one good reasons is the owner's call, and the tiers above exist so the list can be cut from the bottom.

Not building the refusal. A check that refuses a decomposition which drops coverage forces every split to pin its parts, which requires capacity — so it presupposes the answer to question 1 and cannot be built neutrally. A report-only version does not: it would print what moved out of the seal on each reseal, and would have made #395's 8,465 extracted lines visible at the time rather than in this issue afterwards. I can build that against either answer, if wanted.

Provenance

I verified independently: the feature gates and that no shipped build enables them; the cited lines in agent_company.rs and approved_import.rs; and all seven rows of the asymmetry table. The per-file reasoning for the remaining 19 is from a focused read I commissioned and spot-checked rather than re-derived line by line — treat Tier 1 as firm and Tiers 3-4 as the part to argue with.

[lamemustafa]

Correction to my measurement above. I posted "33 production children, 14,674 lines" of pinned modules. That undercounted, and the cause is worth recording because it is the same failure the rest of this issue is about.

The measurement used a regex that matched #[path = "…"] pub mod but not #[path = "…"] pub(crate) mod. Two production modules declared that way were missed:

lines	module	parent	status now
310	agent_import_ledger.rs	agent_import.rs	pinned in #434 — review caught it before merge
213	agent_desktop_journal_review.rs	agent_import.rs	unpinned — orchestration only; see below

Recomputed with the rustc-faithful module graph from #436 (which reproduces rustc's compiled file counts on three crates), at b092fb83, the base #434 was measured against: 34 production children, 15,162 lines; test-only 18 files, 22,300 lines. The test-only figure also moved, partly because the tree changed between the two commits, so I'm not attributing that whole gap to the regex.

agent_desktop_journal_review.rs does not meet the #434 criterion as I read it: it holds the desktop file picker, a 5 MB selection cap and the mapping from refusal codes to operator messages, and delegates review, post and reconcile to the pinned agent_desktop_journal.rs. #437 records it as a deliberate exclusion rather than leaving it silently unassessed.

Also correcting a number I gave in discussion today: the PR that added eight pins during the 15-slot slack period was #246, not #235, and its commit message does describe sealing a report surface — so "no reason recorded anywhere" was more than I had measured. What holds is that it added eight pins without touching the cap.

[lamemustafa]

Correcting my correction. A fact-check of the comment above found its stated cause wrong, though its numbers reproduce exactly.

• agent_import_ledger.rs is declared #[path] pub(super) mod ledger, not pub(crate).
• The regex I blamed (matching pub mod but not pub(crate) mod) would also have missed agent_protocol.rs, declared #[path] pub(super) mod — which the original measurement did count. So that regex cannot be the whole explanation, and I cannot reconstruct the real one from the thread. Cause: not established.

What does reconcile exactly is the production figure: 14,674 + 310 (agent_import_ledger.rs) + 213 (agent_desktop_journal_review.rs) − 35 (agent_import_identity.rs, pinned by #308 thirty minutes after the original measurement) = 15,162. The comment above attributed tree drift only to the test-only figure; it applies to the production figure too.

The two files named as missed, and the 34 / 15,162 and 18 / 22,300 figures at b092fb83, stand.

[lamemustafa]

Both decisions this issue asked for are made and implemented.

1. How much headroom, and how the cap moves. No generic headroom. The cap stays at the exact pin count, and each pin gets a named reason beside MAX_SURFACE_FILES saying what the file holds.

• Seal the admission and egress files by name #434: 14 admission and egress files, 218 → 232, plus src-tauri/tests/admission_and_egress_files_stay_pinned.rs. The gate can't see a dropped pin; this guard can, and its measured failure is recorded in the PR.
• Seal five read-path files and the egress receipt's field walker #438 (angry-curie): 5 read-path files plus the egress receipt's field walker, 232 → 238, guarded the same way.
• Headroom was argued out on the history. The reserve was designed as 15 real slots in chore: seal accounting compatibility surface #223. During that slack period feat(tally): expose native Trial Balance through MCP #246 added eight pins without touching the cap. Exact-count caps (feat(desktop): remember checked endpoint hint #260) and named reasons for each raise (Pin the agent ledger reads into the compatibility surface #278) came later. Real coverage loss (dropped pins, unsealed extractions) passes the gate at any cap, so more slack wouldn't have addressed it.

2. Must splitting a pinned file pin its parts? Report, don't refuse.

• Report pins a branch drops and modules it leaves unsealed, without refusing either #436: scripts/surface_coverage_report.py runs after each reseal. It lists dropped pins and modules newly left unpinned directly under a pinned module, and it says plainly what it does not catch. Its module graph matches rustc's compiled file sets for every crate here.
• Bring the decomposition guide in line with #416 and #434 #437: docs/module-decomposition.md now says to pin the parts of a split that decide what Bridge posts or lets leave the machine, each with a named reason.

Recorded exclusions. The "Not pinned, and deliberately" paragraph beside the constant lists what was left out and why: feature-gated files, operator labels, declaration-only modules, observability.rs (not called by anything a user runs), agent_import_schema.rs and agent_desktop_journal_review.rs.

Corrections made along the way are in the comments above. They include the undercounted first measurement (34 production children, not 33) and reasons that review narrowed before they merged.

Closing as done. Open a new issue for any future boundary change, citing the rule beside the constant.