From a49a0b11493239533e541e6cf1cc210dfda9e24a Mon Sep 17 00:00:00 2001 From: t Date: Wed, 16 Sep 2026 14:33:55 +0530 Subject: [PATCH 1/3] Bring the decomposition guide in line with #416 and #434 The guide's worked example was the gap #434 closed: it listed seven unpinned collaborators of agent_import.rs, five of which are now pinned. It said "218 of 218", which #434 made 232, and that there is no capacity "by design" -- not what the history shows. RESERVED_SURFACE_FILES was introduced in #223 with the cap at exactly count + 15; exact-count raises are a convention since #260. In the slack period #246 added eight pins without touching the cap, which is what the convention now prevents. Its first rule, "Splitting a pinned file means pinning every file it splits into", contradicts the #416 decision to report rather than require: pin the parts that decide what Bridge posts or lets leave the machine, each with a named reason. It now names the two production collaborators still unpinned and why. One, agent_desktop_journal_review.rs, was missed by the #416 measurement itself -- declared `pub(crate) mod`, which the regex behind that measurement did not match -- and is recorded here as orchestration that delegates review, post and reconcile to the pinned agent_desktop_journal.rs. Documentation only. Co-Authored-By: Claude Opus 5 --- docs/module-decomposition.md | 77 ++++++++++++++++-------------------- 1 file changed, 35 insertions(+), 42 deletions(-) diff --git a/docs/module-decomposition.md b/docs/module-decomposition.md index 07dc5378..49304212 100644 --- a/docs/module-decomposition.md +++ b/docs/module-decomposition.md @@ -26,54 +26,47 @@ is a check nobody asked. So: -> **Splitting a pinned file means pinning every file it splits into.** +> **Splitting a pinned file means pinning every part that decides what Bridge +> posts or lets leave the machine** -- each with its own named reason beside +> `MAX_SURFACE_FILES`. And the companion rule, because the same hazard arrives without anyone splitting anything: > **A pinned file's collaborators are pinned or explicitly exempted.** -Nothing asserts this today, and the boundary shows it. `agent_import.rs` is -pinned and has **eight** non-test child modules. **One** is pinned — -`agent_desktop_journal.rs`, and only because it sits on the hard-coded -`REQUIRED_SURFACE_FILES` list, not because it is a child. The other seven are -**1,859 lines outside the seal**: - -| lines | module | -|---:|---| -| 641 | `agent_import_post.rs` — the posting path | -| 402 | `agent_import_cash_bank.rs` | -| 310 | `agent_import_ledger.rs` | -| 213 | `agent_desktop_journal_review.rs` | -| 187 | `agent_import_persistence.rs` | -| 71 | `agent_import_schema.rs` | -| 35 | `agent_import_identity.rs` | - -`agent_import_cash_bank.rs` is the sharpest: it holds `LegRequirement` and the -rules deciding which side the cash/bank ledger sits on for Payment versus Receipt -versus Contra, including the guard against a Contra being filed into the Payment -register — a mistake 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. Some of those exclusions may be deliberate. The -manifest cannot tell you which, because it records paths and not reasons — and -that is the actual problem: the seal's boundary is currently an accident of -history rather than a decision anyone can review. - -That needs capacity in `MAX_SURFACE_FILES`, and there is none by design — 218 of -218. - -**Do not read that as a shortage to be fixed.** `RESERVED_SURFACE_FILES` is -documented as capacity for *"one small cohesive surface change"*, and the cap's -own rationale says it *"makes further unreviewed additions an explicit -compatibility-surface decision"*, closing with *"one file for one named reason — -not headroom."* The cap has been raised five times, each reason recorded in the -comment, and three of those raises came from branches that could not see each -other. The friction is the control. - -So a decomposition of a pinned file **travels with its own cap raise**, in its own -PR, naming its own reason and pinning what it adds — the pattern #406 followed. -Use `scripts/reseal.sh --pins-changed`, the documented inversion for when the pin +Before bridge#416 nothing recorded either, and the boundary showed it. +`agent_import.rs` was pinned while `agent_import_post.rs` (the posting path), +`agent_import_ledger.rs` (whether a batch was dispatched), +`agent_import_cash_bank.rs` (which ledgers may sit on a Payment, Receipt or +Contra's cash/bank side) and `agent_import_persistence.rs` were not -- so the +module that *renders* the qualified write shape was sealed and the modules that +*decide* it were not. #434 pinned those, together with the other admission and +egress files found the same way, and recorded beside `MAX_SURFACE_FILES` both +the reason for each pin and which kinds of file were left out on purpose. That +paragraph is the exemption record; add to it rather than leaving a collaborator +silently unpinned. + +Two production collaborators of `agent_import.rs` remain unpinned, both +deliberately: `agent_import_schema.rs` states the contract Bridge *publishes* to +the model rather than deciding what it admits (see #416); +`agent_desktop_journal_review.rs` is the desktop file picker, a 5 MB +selection cap and the refusal-to-message mapping, delegating review, post and +reconcile to the pinned `agent_desktop_journal.rs`. + +**The gate will not tell you when a split leaves code unsealed.** A moved +module's parent changes hash, the reseal succeeds, and the extracted file is +outside the seal with every check green. Check the new files against the rule +above yourself. + +**Capacity is not free, and that is deliberate.** `MAX_SURFACE_FILES` is set to +the exact pin count (232 of 232 after #434), so any branch adding a pin raises +it, in the same PR, with a named reason. That has been the convention since +#260; it is not how the reserve was first designed. `RESERVED_SURFACE_FILES` +(15) was introduced in #223 with the cap at exactly count + 15, and in that +slack period #246 added eight pins without touching the cap. The exact-count +convention is what now puts a reason beside the constant for every pin. Use +`scripts/reseal.sh --pins-changed`, the documented inversion for when the pin *list* changes rather than only the hashes. Budget for that when planning. Splitting a 6,000-line module four ways is four From 6f0636d6bbf285e5775551ad5012eb747be403bf Mon Sep 17 00:00:00 2001 From: t Date: Wed, 16 Sep 2026 14:38:34 +0530 Subject: [PATCH 2/3] Say which convention dates from which PR, and what the schema can and cannot widen Fact-check found two sentences broader than the history. Exact-count raises date from #260, but a named reason beside the constant only from #278 (210 to 211); #260, #271 and #276 changed the number alone, and most of the 232 pins have no individual reason. And agent_import_schema.rs does run as build_import_xml's argument check, so it is described as what it is -- one that cannot widen admission, since agent_import.rs re-checks the bounds -- rather than as not deciding admission at all. Co-Authored-By: Claude Opus 5 --- docs/module-decomposition.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/module-decomposition.md b/docs/module-decomposition.md index 49304212..62c7cdec 100644 --- a/docs/module-decomposition.md +++ b/docs/module-decomposition.md @@ -48,8 +48,9 @@ paragraph is the exemption record; add to it rather than leaving a collaborator silently unpinned. Two production collaborators of `agent_import.rs` remain unpinned, both -deliberately: `agent_import_schema.rs` states the contract Bridge *publishes* to -the model rather than deciding what it admits (see #416); +deliberately: `agent_import_schema.rs` is the argument schema for +`build_import_xml`, and loosening it cannot widen what is admitted, because +the pinned `agent_import.rs` re-checks those bounds (see #416); `agent_desktop_journal_review.rs` is the desktop file picker, a 5 MB selection cap and the refusal-to-message mapping, delegating review, post and reconcile to the pinned `agent_desktop_journal.rs`. @@ -61,11 +62,13 @@ above yourself. **Capacity is not free, and that is deliberate.** `MAX_SURFACE_FILES` is set to the exact pin count (232 of 232 after #434), so any branch adding a pin raises -it, in the same PR, with a named reason. That has been the convention since -#260; it is not how the reserve was first designed. `RESERVED_SURFACE_FILES` +it in the same PR. Setting the cap to the exact count has been the convention +since #260, and recording a named reason beside the constant for each raise +since #278; neither is how the reserve was first designed. `RESERVED_SURFACE_FILES` (15) was introduced in #223 with the cap at exactly count + 15, and in that -slack period #246 added eight pins without touching the cap. The exact-count -convention is what now puts a reason beside the constant for every pin. Use +slack period #246 added eight pins without touching the cap. With no slack, a +new pin cannot land without an edit to the constant, which is where its reason +now goes. Use `scripts/reseal.sh --pins-changed`, the documented inversion for when the pin *list* changes rather than only the hashes. From edba8b1c00ec18e2097fd51f78ae9fe6b9a887d4 Mon Sep 17 00:00:00 2001 From: t Date: Wed, 16 Sep 2026 14:39:44 +0530 Subject: [PATCH 3/3] Drop the pin count from the guide, which each raise would stale #438 raises the cap to 238; the number belongs to the constant, not the prose. Co-Authored-By: Claude Opus 5 --- docs/module-decomposition.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/module-decomposition.md b/docs/module-decomposition.md index 62c7cdec..20d5cd9a 100644 --- a/docs/module-decomposition.md +++ b/docs/module-decomposition.md @@ -61,7 +61,7 @@ outside the seal with every check green. Check the new files against the rule above yourself. **Capacity is not free, and that is deliberate.** `MAX_SURFACE_FILES` is set to -the exact pin count (232 of 232 after #434), so any branch adding a pin raises +the exact pin count, so any branch adding a pin raises it in the same PR. Setting the cap to the exact count has been the convention since #260, and recording a named reason beside the constant for each raise since #278; neither is how the reserve was first designed. `RESERVED_SURFACE_FILES`