Skip to content

Commit b1cc79e

Browse files
committed
fix(eager-closure): a tolerated split may only add new files; shrinkage cannot fund an eager edge
Maintainer review on #3298: the two-fact tolerance (containment + flat weight) never checked WHERE the added modules came from, so a PR could statically import a heavy merge-base module that sat outside the closure and pay for it by deleting top-level statements elsewhere in the same closure. Both facts still held; real growth passed. The tolerance is now three facts, all read from the graphs plus the merge-base tree: containment, added-module NOVELTY (every head-closure module the base closure did not evaluate is absent from the merge-base tree at its rename-canonicalized path -- checked at the BASE path for a rename's head, so re-naming a closure-external module into the closure is still pre-existing code newly made eager), and flat weight. classifyGrowth requires all three and prints one reason per failed fact. Planted, in the maintainer's exact shape: the split fixture plus a committed pre-existing-heavy.ts pulled in by part-c, weight offset by merging the hub's two remaining declarations -- containment holds, weight flat 3->3, novelty false, verdict names shrinkage-funding. Unit-level pair for the fact itself, and rename-canonicalized novelty pinned with and without the rename map against a colliding tree. Mutation: dropping the novelty conjunct fails exactly the two planted novelty tests and nothing else. ADR 0027 (status, rules, decision, alternatives: the first draft is now a named refuted alternative) and ADR 0028 step 3 state the three facts; the residue paragraph drops the 'true of any closure' claim.
1 parent bdf8876 commit b1cc79e

6 files changed

Lines changed: 201 additions & 68 deletions

‎docs/adr/0027-descriptor-root-vs-eager-closure-budget.md‎

Lines changed: 36 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,10 @@
44

55
Accepted (2026-10-07, #2469). The conflict below is resolved in favor of allowing
66
**byte-neutral (statement-neutral) re-homing**: the eager-closure budget's NO-GROWTH rule now
7-
tolerates exactly the split shape — the head closure still evaluates every merge-base module and
8-
the closure's total module-scope statement count does not grow. The rule lives in
9-
`scripts/__tests__/closure-growth-rule.ts`, planted in both directions by
7+
tolerates exactly the split shape — the head closure still evaluates every merge-base module,
8+
every module it newly evaluates is new to the merge-base tree (or a rename), and the closure's
9+
total module-scope statement count does not grow. The rule lives in
10+
`scripts/__tests__/closure-growth-rule.ts`, planted in every failing direction by
1011
`scripts/__tests__/closure-growth-rule.test.ts`. The hard ADR-0019 checks (façade exactness, no
1112
platform implementation before binding) are untouched: the tolerance relaxes the module-count
1213
proxy, never the loading property.
@@ -33,8 +34,9 @@ the file must be divided, the other says the division must not be visible to any
3334
## Rules at a glance, resolved
3435

3536
- A hub split is allowed when it is statement-neutral: every merge-base module stays in every
36-
affected closure, and total module-scope statements do not grow. The gate enforces this; an
37-
unexplained count growth still fails with no approval path, as before.
37+
affected closure, every newly evaluated module is new to the merge-base tree (or a rename), and
38+
total module-scope statements do not grow. The gate enforces this; an unexplained count growth
39+
still fails with no approval path, as before.
3840
- Do not add an approved-growth row, a baseline entry, or a suppression to pass the gate. That is
3941
the allowlist `AGENTS.md` forbids; the split tolerance is a rule, not a waiver — it decides from
4042
the two graphs, and nothing is hand-entered per split.
@@ -79,29 +81,37 @@ debt rule's proxy disagree at exactly this shape.
7981
## Decision
8082

8183
May a byte-neutral re-homing of a hub module's contents into new modules raise the eager module
82-
count of the entry surfaces that reach it? **Yes — exactly when it is a split**, decided by two
83-
facts computed from the two closure graphs, not by an entered number:
84+
count of the entry surfaces that reach it? **Yes — exactly when it is a split**, decided by three
85+
facts computed from the two closure graphs and the merge-base tree, not by an entered number:
8486

8587
1. **Containment:** the head closure evaluates every module the merge-base closure evaluated
86-
(renames canonicalized), so the growth is purely additive.
87-
2. **Flat weight:** the closure's total top-level statement count — wiring lines excluded, so
88+
(renames canonicalized), so nothing was dropped or swapped.
89+
2. **Added-module novelty:** every module the head closure evaluates that the base closure did
90+
not is absent from the merge-base tree at its rename-canonicalized path. A module the tree
91+
already had, sitting outside the closure, becoming eager — under its own name or a renamed
92+
one — is a new edge, not re-homed code; and without this fact, weight deleted elsewhere in
93+
the closure would fund it.
94+
3. **Flat weight:** the closure's total top-level statement count — wiring lines excluded, so
8895
re-homing is invisible to it — does not exceed the merge-base closure's.
8996

90-
This is issue #2469's candidate 4 (structure ∧ weight), implemented as the minimal slice: each
91-
half alone is refutable — containment without weight accepts a "split" that smuggles a new heavy
92-
edge; weight without containment accepts dropping a merge-base module behind an equal-sized
93-
replacement — and together they admit healthy extraction while refusing any growth in the
94-
closure's module-scope statement weight. Statements were chosen over bytes because formatting and
95-
comment churn move bytes while statements track the thing being preserved: module-scope
96-
declarations and calls. The guarantee is exactly **flat statement weight over a preserved
97-
closure**, not equality of eager behavior: a split that REPLACES an existing statement with a
98-
more expensive top-level call moves no count and no weight, so it passes — nothing
97+
This is issue #2469's candidate 4 (structure ∧ weight), with the structure half implemented as
98+
containment + novelty rather than candidate 2's importer-set shape. Any subset is refutable —
99+
containment without novelty accepts pulling a pre-existing module in at flat weight, novelty
100+
without containment accepts dropping a merge-base module, weight without the other two accepts
101+
unrelated shrinkage paying for a smuggled edge — and the three together admit healthy extraction
102+
while refusing any growth in the closure's module-scope statement weight. Statements were chosen
103+
over bytes because formatting and comment churn move bytes while statements track the thing being
104+
preserved: module-scope declarations and calls. The guarantee is exactly **newly evaluated
105+
modules are new files, and total statement weight is flat over a preserved closure**, not
106+
equality of eager behavior: a split that REPLACES an existing statement with a more expensive
107+
top-level call inside an existing file moves no count and no weight, so it passes — nothing
99108
count-based, in modules or statements, can see a like-for-like replacement. That residue is
100-
bounded by what the tolerance cannot hide: the head still evaluates only merge-base modules plus
101-
what they pull in, the hard ADR-0019 checks (façade exactness, no platform implementation before
102-
binding) stay count- and pattern-based under it, and the added-module listing every failure
103-
prints is what a reviewer reads. The planted tests in
104-
`scripts/__tests__/closure-growth-rule.test.ts` pin the acceptance pair in both directions.
109+
bounded by what the tolerance cannot hide: every module the head newly evaluates is a file the
110+
merge-base tree did not have (so it cannot smuggle pre-existing implementation into eager scope),
111+
the hard ADR-0019 checks (façade exactness, no platform implementation before binding) stay
112+
count- and pattern-based under it, and the added-module listing every failure prints is what a
113+
reviewer reads. The planted tests in `scripts/__tests__/closure-growth-rule.test.ts` pin all
114+
three failing directions.
105115

106116
Maintenance cost of an ordinary extraction under this rule: zero configuration edits. No row,
107117
baseline, or number is touched per split — the merge-base comparison recomputes everything. (The
@@ -118,6 +128,9 @@ shippable, so an oversized hub is addressable debt rather than accepted state.
118128
retirement — maintenance the chosen rule does not.
119129
- **Structure alone (#2469 candidate 2):** refuted by the planted smuggle test — a "new" module can
120130
carry a new heavy edge, so containment proves nothing about eager work.
131+
- **Containment + weight without added-module novelty (the rule's first draft on #3298):** refuted
132+
by the planted pre-existing-heavy test — deleting statements elsewhere in the closure funds a
133+
static edge to a merge-base module that sat outside it, which is real growth, not a split.
121134
- **Weight alone (#2469 candidate 1):** refuted by the planted drop test — a swap can keep the
122135
statement total flat while quietly making the closure evaluate different modules.
123136
- **Leave the array in place:** the status quo, not a resolution — it leaves the size debt unowned and

‎docs/adr/0028-capability-family-cell-vocabulary.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -71,9 +71,9 @@ family rather than arguing from the shape:
7171
recurring eight-package commits.
7272
3. Report eager-closure deltas per entry surface. `scripts/__tests__/eager-closure-budgets.ts` has no
7373
growth-approval path; [ADR 0027](0027-descriptor-root-vs-eager-closure-budget.md) tolerates
74-
module-count growth only when the head closure preserves every merge-base module and its total
75-
module-scope weight does not grow. A row table is a **new eager value**: it passes only by
76-
satisfying both conditions — preserving the base closure and keeping total weight no greater —
74+
module-count growth only when the head closure preserves every merge-base module, every newly
75+
evaluated module is new to the merge-base tree (or a rename), and total module-scope weight does
76+
not grow. A row table is a **new eager value**: it passes only by satisfying all three conditions;
7777
otherwise the gate stays red and this ADR should be withdrawn rather than granted an exception.
7878

7979
If the fan-out does not visibly shrink, close this as rejected and leave the two authored lists in

‎docs/adr/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@
2828
| [0024 Screen Recording — One Coordinator, Two Facts (Proposed)](0024-screen-recording-provable-signal.md) | `record start`/`stop` lifecycle, the export-exists / recorder-stopped split, backend stop-and-collect contract, recovery through the coordinator, the ADR 0019 §5 amendment and the failed-finish cleanup fix |
2929
| [0025 Foldable Apple Panels — Capture the Lit Panel](0025-foldable-apple-panels.md) | iPhone Duo outer/inner panels, CoreDevice display info as the only screen authority, why `simctl`'s implicit display default captures a black panel, derived (never asserted) pose, and why no pose-control command exists |
3030
| [0026 Scroll Clip Authority — Ownership Is the Parent Edge](0026-scroll-clip-authority.md) | iOS scroll indicators and the visible band, why ownership is read from the parent edge instead of an ancestor walk, what may remove a node from an interactive snapshot, and ejection dispositions |
31-
| [0027 Descriptor Root Size vs Eager-Closure Budget](0027-descriptor-root-vs-eager-closure-budget.md) | accepted: the eager-closure budget tolerates a statement-neutral hub split (containment + flat top-level-statement weight) and nothing else; splitting `packages/command-registry/src/registry.ts` is unblocked |
31+
| [0027 Descriptor Root Size vs Eager-Closure Budget](0027-descriptor-root-vs-eager-closure-budget.md) | accepted: the eager-closure budget tolerates a statement-neutral hub split only (containment + added-module novelty + flat top-level-statement weight) and nothing else; splitting `packages/command-registry/src/registry.ts` is unblocked |
3232
| [0028 Capability-Family Cell Vocabulary — One Runtime Source (Proposed)](0028-capability-family-cell-vocabulary.md) | adding a capability operation family, `UnavailablePlatformRuntimeFacts` / `UNAVAILABLE_CELLS`, `INTERACTOR_OPERATIONS`, and why an eight-package fan-out recurs |
3333
| [0029 Daemon Policy](0029-daemon-policy.md) | `AGENT_DEVICE_DAEMON_POLICY`, confining a daemon's commands, devices, or device shutdown, and where operator rules are enforced for batch/replay steps |
3434
| [0030 Process Lock Exclusion](0030-process-lock-exclusion.md) | process-lock publication/reclaim/release, retained mutation guards, and the single-protocol upgrade boundary |

0 commit comments

Comments
 (0)