Repository navigation
gates: let the eager-closure budget tolerate a module split without admitting new eager work #2469
Description
Activity
This deserves priority in the architecture-quality umbrella #3276. Two current developments strengthen the case:
- ADR 0027 records a byte-faithful command-registry split blocked by the same no-growth rule, while repository policy requires oversized files to split.
- Merged perf(daemon): lazy-load Maestro in request binding; budget the daemon entry #3284 adds
src/daemon.tsto the hub budget, extending the scope where a healthy extraction can fail. Its Maestro optimization is useful; the blanket module-count constraint is the separate design question.
Please retain the existing split-versus-new-heavy-edge acceptance pair and use it to choose the smallest solution. In particular, distinguish the hard ADR-0019 loading constraints from module count as a proxy. Existing checks that prevent premature platform implementation loading should remain hard checks. Avoid solving this with a general source-equivalence/split-inference framework or forcing artificial
import()seams merely to keep counts flat.For the design comparison, include the maintenance cost of ordinary extraction, not just gate runtime: how many source, configuration, and approval edits does the next split require? Bytes/statements are also proxies and need adversarial evidence; equal total size alone does not prove equal eager behavior.
Resolve ADR 0027 as part of the chosen policy so the file-size and eager-loading instructions stop giving contradictory directions. This is a request to prioritize the existing issue, not to bypass the current guard or add an unreviewed allowance.
Resolved in #3298 (implementation + planted tests + first consumer in one stack).
Rule chosen: candidate 4 (structure ∧ weight), minimal slice. NO-GROWTH tolerates module-count growth for exactly one shape, computed from the two closure graphs — nothing hand-entered:
- Containment: the head closure still evaluates every merge-base module (renames canonicalized), so growth is purely additive.
- Flat weight: the closure's total top-level-statement count — wiring (
import,export … from) excluded — does not grow.
Each half alone is refutable and both directions are planted in tests: containment without weight accepts a split smuggling a module-scope call into a new heavy edge; weight without containment accepts a flat-size swap that drops a merge-base module. Together they admit the #2423 extraction and refuse both. Statements over bytes: formatting/comment churn moves bytes; statements track module-scope evaluation work, the thing being preserved. Candidate 3 (approval rows) stays refuted — an allowlist on the one invariant deliberately given no approval path, plus a hand-edited row per split. Under the chosen rule an ordinary extraction costs zero configuration edits.
Per the umbrella constraint: no inference framework — one comparison of two numbers plus a subset fact in a 98-line module (
scripts/__tests__/closure-growth-rule.ts). The hard ADR-0019 checks (façade exactness, no platform implementation before binding) are untouched; the tolerance relaxes the count proxy only. A tolerated split must keep containment, so it cannot smuggle an eager edge that drops anything.First consumer: the #2423 extraction itself —
runner-cache-metadata.tssplits intorunner-phase-budget.ts+runner-toolchain-probe.ts. All seven entries this issue names pass with containment at flat weight (e.g. app-lifecycle-facade 117→119 modules, weight 1952→1952; runner/index.ts 13→15, 399→399), with zero approval rows.docs/adr/0027is resolved to Accepted in the same PR, which also unblocks the byte-faithful descriptor-root split recorded there (+11, statement-neutral).Gate evidence (
pnpm check:affected --run, head5e96a8785): all runnable checks passed; 470 files / 4359 tests, layering, fallow clean, xctest-selection 0 unreachable.- added a commit that references this issue
on Oct 8, 2026
Purpose
Decide how the eager-closure gate (
scripts/__tests__/eager-closure-budgets.ts) should treat a module split, so that extracting a large module inside a gated closure stops being impossible without weakening the property the gate protects.Current behavior
Every entry that exists at the merge-base is held to NO GROWTH of its eager import closure, counted in modules. There is no approval path for growth of an existing entry (
APPROVED_OVER_CEILINGcovers first-introduced entries only). A module that is in a gated closure therefore cannot be split: one module becoming N modules is +N−1 for every entry that evaluates it.Measured on PR #2423 at
b21efb0: extractingpackages/platform-apple/src/runner/runner-cache-metadata.ts(621 lines) intorunner-phase-budget.ts+runner-toolchain-probe.tsgrows seven entries by two each: app-lifecycle-facade 120→122, app-resolution-facade 61→63, doctor-facade 101→103, perf-facade 60→62, physical-device-facade 47→49, runner-operations-facade 100→102,runner/index.ts13→15. The review on #2423 asked for exactly that extraction for ownership clarity, and it had to be deferred.What the gate protects
The ADR-0019 loading shape: a façade must not evaluate implementation it does not need at import time. The module count is a proxy for eager work. A split does not add eager work when the new modules together evaluate what the old one did, but it does add modules, so the proxy reads it as growth.
Design question
Choose a rule that admits healthy extraction without admitting new eager work. Candidates, none proven:
APPROVED_GROWTH), naming the issue, the reason, and the expected delta, retired automatically once the merge-base carries the new shape. Same mechanism as the existing ceiling rows; costs a hand-edited row per split.Deliverable
A short design note choosing one, with the walker change and the test that plants (a) a pure split and (b) a split that smuggles a new heavy edge, showing the first passes and the second fails. Then re-run the #2423 extraction as the first consumer.
Non-goals
Loosening no-growth for anything other than splits; changing category ceilings.