test(structure): per-package eager-closure budgets — the ADR-0019 loading-shape probe (#1739) - #1965
Conversation
Size Report
npm unpacked components
Startup median (7 runs, lower is better):
Top changed chunks: no changes in the largest emitted chunks. Top changed packed filesNo changed packed files. |
|
Not ready at
Please derive façade roots from manifest ownership, add predecessor-chain diagnostics, and reseed post-#1969 with minimal headroom. |
… reseed tight Review findings on #1965: 1. Discovery scanned only `packages/*/src/facades/*.ts`, which omits every package that publishes its entry surface straight from the manifest — including all six `packages/platform-*/src/index.ts` façades, the exact subject of ADR-0019's implementation-laziness rule. Discovery now derives from `readWorkspacePackages(...).exportTargets` and then adds `/src/facades/` files, reusing the R11 helper rather than reimplementing it so the two gates cannot disagree about what an entry surface is. The table grows from 14 façades + 2 hubs to 95 entry surfaces + 8 hubs. 2. Budgets carried a few files of slack each. They are now exact ratchets with no headroom, matching how the repo pins R9/R10 and test-file size: growth is allowed, it just has to be a visible number change in the diff of the PR that causes it. Every budget is reseeded from post-#1969 measurement. 3. Violations printed a flat sorted set, which named the offender but not the route. `eagerClosureGraphOf` records each file's discoverer, so failures now print the transitive chain entry -> ... -> offender. `eagerClosureOf` keeps its contract and is expressed in terms of the new walk; per-file edges are memoized, which also cuts the existing pins' runtime (cli closure test 2336ms -> ~550ms). The platform-package façades evaluate exactly one module each — themselves — so their budget of 1 is the tightest statement of "metadata-eager, implementation-lazy" the walker can make.
0352dba to
55d4846
Compare
|
All three addressed in 1. Discovery now derives from manifest ownershipYou were right that this was a correctness gap and not just a wording problem. The omission was worse than "incomplete": all six What they measure is the payoff — each platform façade evaluates exactly one module: itself. Metadata inline, contract imports all Table grew 14 façades + 2 hubs → 95 entry surfaces + 8 hubs. 2. Budgets reseeded post-#1969, with zero headroomReseeded from measurement on Your point about slack not being neutral is the reason: the regression class is a single static import dragging a subtree in, #1969 measured it at 5–12% of suite import work per instance, and "a few files" of spare room silently absorbs the small end of exactly that. Growth is still fine — it just has to show up as a number change in the diff of the PR causing it.
I also added the five hubs #1969 moved off the wide façades ( 3. Edge chains, not offender setsAdded Breadth-first, so each chain is the shortest route to that file. I also memoized per-file edges while I was in there, since ~100 entries share most of their subtrees. Side benefit: Planted red, re-runReplaced the lazy The third is the composition root picking up the blast radius through its own chain — the cascade a flat offender set wouldn't have explained, which is a fair argument for your finding 3. Sabotage reverted; diff is three files. One thing I did not doLeft CI green (27/27). |
|
Not ready at |
|
The primary static-import planted red is credible and CI is green, but the generalized gate still has four correctness holes:
Please add planted-red/non-vacuity tests for these failure modes and correct the PR text that currently claims exactness and shared R11 discovery. |
… reseed tight Review findings on #1965: 1. Discovery scanned only `packages/*/src/facades/*.ts`, which omits every package that publishes its entry surface straight from the manifest — including all six `packages/platform-*/src/index.ts` façades, the exact subject of ADR-0019's implementation-laziness rule. Discovery now derives from `readWorkspacePackages(...).exportTargets` and then adds `/src/facades/` files, reusing the R11 helper rather than reimplementing it so the two gates cannot disagree about what an entry surface is. The table grows from 14 façades + 2 hubs to 95 entry surfaces + 8 hubs. 2. Budgets carried a few files of slack each. They are now exact ratchets with no headroom, matching how the repo pins R9/R10 and test-file size: growth is allowed, it just has to be a visible number change in the diff of the PR that causes it. Every budget is reseeded from post-#1969 measurement. 3. Violations printed a flat sorted set, which named the offender but not the route. `eagerClosureGraphOf` records each file's discoverer, so failures now print the transitive chain entry -> ... -> offender. `eagerClosureOf` keeps its contract and is expressed in terms of the new walk; per-file edges are memoized, which also cuts the existing pins' runtime (cli closure test 2336ms -> ~550ms). The platform-package façades evaluate exactly one module each — themselves — so their budget of 1 is the tightest statement of "metadata-eager, implementation-lazy" the walker can make.
…le-owner Second review pass on #1965 found four holes, two of which were places the PR text claimed a property the code did not have. 1. Rows were documented as exact ratchets but asserted with `<=`, so a shrink silently became headroom a later regression could grow back into. The comparison is now equality, in a pure `classifyBudget` with a separate message for each direction ("lower its pin to N in this PR so the ratchet keeps the gain"), matching test-file-size-ratchet.ts and the R9/R10 pins. 2. An over-pin failure printed a chain per evaluated module — 361 of them for src/cli.ts. It now prints a bounded attribution: the entry's heaviest direct edges (capped at 4) with a couple of representative deep routes each, ranked so a newly added import sorts first. The comment states plainly that this attributes by shortest import route and does NOT diff against a recorded baseline; naming a true delta would mean checking in ~1,500 module paths and rewriting them on every contracts refactor. 3. Discovery reimplemented a one-level `src/facades` scan while canonical R11 discovery is recursive, so a nested façade file could be covered by R11 and silently missing here. `facadeEntryFiles` is now a single exported owner in package-boundaries.ts that both R11's façade gate and this table consume. 4. Rows were converted to Sets before any uniqueness check, so a duplicate was unobservable. The table is now two `Record<string, number>` literals keyed by path, making an in-record duplicate a TypeScript error (ts1117); the only remaining case — one path in both records — is asserted on the array. Each of the four holes gets a test that fails when the rule is broken, since a tree that happens to satisfy its pins cannot distinguish a correct rule from a vacuous one. Writing those found a real bug in the duplicate check itself (`Set.add` returns the Set, so the filter never matched). Pins reseeded on 04e4c23.
55d4846 to
6d337d2
Compare
|
All four fixed in 1. "Exact ratchet" is now actually equalityIt was Now Pulling the rule into a pure function is what makes it testable in its failing direction, which matters here: over the real tree, 2. Bounded attribution instead of a chain dumpYou're right that 361 chains for One place I did not follow the direction, and want your call. You asked me to persist per-row module identity so the failure can name the newly added modules. I didn't, and the docstring says so in those words rather than implying a delta it can't compute. The reason: naming a true delta means checking in ~1,500 module paths (that's the sum of all 103 closures) and rewriting them on every contracts refactor — a second source of truth with real churn, right after #1969 moved 259 imports. What I shipped attributes by shortest import route instead, which lands on the same answer for the common case (a new import on the entry is a new edge, so its whole subtree is attributed to it and it sorts first) and degrades to "this top-level edge contains the growth" for a regression deep inside an existing subtree. If you'd rather have the exact delta and accept the baseline file, say so and I'll add it — the walker already produces the data, it's a 3. One discovery owner, and it's the recursive one
R11's façade test is 13/13 green on the shared function, and the full layering suite is 181/181. 4. Duplicates are now unwritable, not merely unassertedThe table is two The one duplicate still expressible is the same path in both records, and that's asserted on the array before any Planted red for each of the fourAdded a failing-direction test per hole, since "a hole no test can fail" was your objection:
Each was observed red, then reverted. The nested-façade one runs against a fixture tree in a temp dir, so it holds even though the real repo has no nested façade today. Worth flagging: writing #4's sabotage found a bug in my own check — I had Also
Validation
CI: one |
|
CI is green — 28/28. The For the record, the new gate in CI: 206 tests, 1595 ms for the whole file, no slow-test gate output. |
|
Not ready at
Exact-head CI is 28/28 green and package growth is 0 B. |
… reseed tight Review findings on #1965: 1. Discovery scanned only `packages/*/src/facades/*.ts`, which omits every package that publishes its entry surface straight from the manifest — including all six `packages/platform-*/src/index.ts` façades, the exact subject of ADR-0019's implementation-laziness rule. Discovery now derives from `readWorkspacePackages(...).exportTargets` and then adds `/src/facades/` files, reusing the R11 helper rather than reimplementing it so the two gates cannot disagree about what an entry surface is. The table grows from 14 façades + 2 hubs to 95 entry surfaces + 8 hubs. 2. Budgets carried a few files of slack each. They are now exact ratchets with no headroom, matching how the repo pins R9/R10 and test-file size: growth is allowed, it just has to be a visible number change in the diff of the PR that causes it. Every budget is reseeded from post-#1969 measurement. 3. Violations printed a flat sorted set, which named the offender but not the route. `eagerClosureGraphOf` records each file's discoverer, so failures now print the transitive chain entry -> ... -> offender. `eagerClosureOf` keeps its contract and is expressed in terms of the new walk; per-file edges are memoized, which also cuts the existing pins' runtime (cli closure test 2336ms -> ~550ms). The platform-package façades evaluate exactly one module each — themselves — so their budget of 1 is the tightest statement of "metadata-eager, implementation-lazy" the walker can make.
…le-owner Second review pass on #1965 found four holes, two of which were places the PR text claimed a property the code did not have. 1. Rows were documented as exact ratchets but asserted with `<=`, so a shrink silently became headroom a later regression could grow back into. The comparison is now equality, in a pure `classifyBudget` with a separate message for each direction ("lower its pin to N in this PR so the ratchet keeps the gain"), matching test-file-size-ratchet.ts and the R9/R10 pins. 2. An over-pin failure printed a chain per evaluated module — 361 of them for src/cli.ts. It now prints a bounded attribution: the entry's heaviest direct edges (capped at 4) with a couple of representative deep routes each, ranked so a newly added import sorts first. The comment states plainly that this attributes by shortest import route and does NOT diff against a recorded baseline; naming a true delta would mean checking in ~1,500 module paths and rewriting them on every contracts refactor. 3. Discovery reimplemented a one-level `src/facades` scan while canonical R11 discovery is recursive, so a nested façade file could be covered by R11 and silently missing here. `facadeEntryFiles` is now a single exported owner in package-boundaries.ts that both R11's façade gate and this table consume. 4. Rows were converted to Sets before any uniqueness check, so a duplicate was unobservable. The table is now two `Record<string, number>` literals keyed by path, making an in-record duplicate a TypeScript error (ts1117); the only remaining case — one path in both records — is asserted on the array. Each of the four holes gets a test that fails when the rule is broken, since a tree that happens to satisfy its pins cannot distinguish a correct rule from a vacuous one. Writing those found a real bug in the duplicate check itself (`Set.add` returns the Set, so the filter never matched). Pins reseeded on 04e4c23.
…atform diagnostics Two findings from the third #1965 review. 1. R11 REGRESSION, introduced by the previous commit in this PR. Extracting one recursive facade-discovery owner was right, but it was implemented as a raw filesystem walk, which silently changed R11 from tracked-source discovery (listSourceFiles) to "whatever is on disk". A layering gate describes committed state, so an uncommitted scratch facade under a scanned path must be invisible; instead it could fail both R11 and the budget gate on a contributor's working directory. Worse, the test asserted the new behaviour, pinning the regression in place. The tracked-source enumerator now lives in a leaf module, scripts/layering/tracked-sources.ts, that both check.ts and package-boundaries.ts consume (check.ts imports package-boundaries.ts, so the dependency cannot run the other way). facadeEntryFiles reads listTrackedProductionSources, keeping the single recursive owner while restoring tracked-only scope. The temp-dir test is replaced by a real git fixture following platform-package-repository.test.ts: a tracked nested facade that must be discovered, plus untracked siblings — one beside it and one beside the nested file — that must not be. Reverting to the filesystem walk turns it red. 2. Only the numeric-pressure diagnostic was bounded; the platform-implementation assertion still emitted every offender with a full chain, so one eager platform subtree buried the single import that caused it under hundreds of lines. Both diagnostics now share one renderer that groups targets by the entry's own import they arrived through, caps edges and routes, and states the omitted counts. A wide planted-red fixture (300 offenders under one owning edge plus extra edges) proves the cap engages rather than assuming it. src/cli.ts reseeded 361 -> 362 for drift from the rebase onto 7aaa559.
6d337d2 to
7815272
Compare
|
Both fixed in 1. This was an R11 regression I introduced, not a new-gate nitStating that plainly because the framing matters: extracting one recursive discovery owner was the right move, but I implemented it as a raw The fix keeps the single owner and feeds it tracked paths.
The temp-dir test is gone, replaced by a real git fixture following
Planted red: reverting R11 is green on the shared function ( 2. Platform-implementation diagnostics now share the bounded rendererYou're right that bounding only the numeric side was half a fix. Both diagnostics now go through one Previously that was 18 offenders × a full chain each; on a wider subtree it would have been hundreds. The wide fixture you asked for: 300 offenders under one owning edge, plus extra edges to force the group tail. It asserts the omitted counts appear ( One thing the fixture taught me: my first version chained the 300 modules linearly, and Also
Validation
|
|
CI green — 28/28. One On the check you'd expect to be slow to report: In CI: 207 tests in the budget file, 1477 ms for the whole file, no slow-test gate output. |
|
Request changes: the tracked-only discovery fix is incomplete for manifest-derived entry surfaces. |
ADR-0019 requires platform-package façades to stay implementation-lazy and is explicit that a startup threshold alone is not a substitute for preserving the loading shape. #1950 built the AST-level walker (eager-import-closure.fixtures.ts) and proved the planted-red procedure on one file (session-teardown.ts's android-helper denylist); this generalizes it into a data-driven budget table so any workspace-package façade -- or a designated hub module -- can get an eager-closure ceiling without a bespoke test. Seeds a budget for every packages/*/src/facades/*.ts file (discovered the same way package-boundaries.test.ts discovers façades, not hand-listed) from its measured current closure size, plus a platform-implementation denylist for façades whose contract is implementation-neutral vocabulary. Also demonstrates the mechanism on two designated hub modules (cli.ts, session-teardown.ts) alongside their existing, more specific ad hoc pins. Closes #1960
… reseed tight Review findings on #1965: 1. Discovery scanned only `packages/*/src/facades/*.ts`, which omits every package that publishes its entry surface straight from the manifest — including all six `packages/platform-*/src/index.ts` façades, the exact subject of ADR-0019's implementation-laziness rule. Discovery now derives from `readWorkspacePackages(...).exportTargets` and then adds `/src/facades/` files, reusing the R11 helper rather than reimplementing it so the two gates cannot disagree about what an entry surface is. The table grows from 14 façades + 2 hubs to 95 entry surfaces + 8 hubs. 2. Budgets carried a few files of slack each. They are now exact ratchets with no headroom, matching how the repo pins R9/R10 and test-file size: growth is allowed, it just has to be a visible number change in the diff of the PR that causes it. Every budget is reseeded from post-#1969 measurement. 3. Violations printed a flat sorted set, which named the offender but not the route. `eagerClosureGraphOf` records each file's discoverer, so failures now print the transitive chain entry -> ... -> offender. `eagerClosureOf` keeps its contract and is expressed in terms of the new walk; per-file edges are memoized, which also cuts the existing pins' runtime (cli closure test 2336ms -> ~550ms). The platform-package façades evaluate exactly one module each — themselves — so their budget of 1 is the tightest statement of "metadata-eager, implementation-lazy" the walker can make.
…le-owner Second review pass on #1965 found four holes, two of which were places the PR text claimed a property the code did not have. 1. Rows were documented as exact ratchets but asserted with `<=`, so a shrink silently became headroom a later regression could grow back into. The comparison is now equality, in a pure `classifyBudget` with a separate message for each direction ("lower its pin to N in this PR so the ratchet keeps the gain"), matching test-file-size-ratchet.ts and the R9/R10 pins. 2. An over-pin failure printed a chain per evaluated module — 361 of them for src/cli.ts. It now prints a bounded attribution: the entry's heaviest direct edges (capped at 4) with a couple of representative deep routes each, ranked so a newly added import sorts first. The comment states plainly that this attributes by shortest import route and does NOT diff against a recorded baseline; naming a true delta would mean checking in ~1,500 module paths and rewriting them on every contracts refactor. 3. Discovery reimplemented a one-level `src/facades` scan while canonical R11 discovery is recursive, so a nested façade file could be covered by R11 and silently missing here. `facadeEntryFiles` is now a single exported owner in package-boundaries.ts that both R11's façade gate and this table consume. 4. Rows were converted to Sets before any uniqueness check, so a duplicate was unobservable. The table is now two `Record<string, number>` literals keyed by path, making an in-record duplicate a TypeScript error (ts1117); the only remaining case — one path in both records — is asserted on the array. Each of the four holes gets a test that fails when the rule is broken, since a tree that happens to satisfy its pins cannot distinguish a correct rule from a vacuous one. Writing those found a real bug in the duplicate check itself (`Set.add` returns the Set, so the filter never matched). Pins reseeded on 04e4c23.
…atform diagnostics Two findings from the third #1965 review. 1. R11 REGRESSION, introduced by the previous commit in this PR. Extracting one recursive facade-discovery owner was right, but it was implemented as a raw filesystem walk, which silently changed R11 from tracked-source discovery (listSourceFiles) to "whatever is on disk". A layering gate describes committed state, so an uncommitted scratch facade under a scanned path must be invisible; instead it could fail both R11 and the budget gate on a contributor's working directory. Worse, the test asserted the new behaviour, pinning the regression in place. The tracked-source enumerator now lives in a leaf module, scripts/layering/tracked-sources.ts, that both check.ts and package-boundaries.ts consume (check.ts imports package-boundaries.ts, so the dependency cannot run the other way). facadeEntryFiles reads listTrackedProductionSources, keeping the single recursive owner while restoring tracked-only scope. The temp-dir test is replaced by a real git fixture following platform-package-repository.test.ts: a tracked nested facade that must be discovered, plus untracked siblings — one beside it and one beside the nested file — that must not be. Reverting to the filesystem walk turns it red. 2. Only the numeric-pressure diagnostic was bounded; the platform-implementation assertion still emitted every offender with a full chain, so one eager platform subtree buried the single import that caused it under hundreds of lines. Both diagnostics now share one renderer that groups targets by the entry's own import they arrived through, caps edges and routes, and states the omitted counts. A wide planted-red fixture (300 offenders under one owning edge plus extra edges) proves the cap engages rather than assuming it. src/cli.ts reseeded 361 -> 362 for drift from the rebase onto 7aaa559.
7815272 to
ccc1e0e
Compare
The previous commit intersected the `src/facades/` walk with tracked sources but left manifest-derived entry surfaces bypassing that intersection entirely — the same bug class, on the path it did not close. Two distinct leaks: 1. `readWorkspacePackages` enumerated `packages/` with `readdirSync`, so an uncommitted scratch package contributed a name, export targets, and dependency edges to every R11 rule built on it, not just to facade discovery. Closed at the source: it now reads tracked manifests via `listTrackedPackageManifests`, mirroring how R13's `readTrackedPlatformPackageDeclarations` has always enumerated its own. 2. A TRACKED manifest can still name an uncommitted target in its working-tree content, which the trailing `existsSync` admitted. `facadeEntryFiles` now intersects manifest-derived targets with the tracked production set as well, so every path it returns is committed whatever its origin. Three fixtures, each verified failing before the fix and passing after: - `readWorkspacePackages reads tracked manifests only` (in R11's own suite, since leak 1 affects every rule that reads packages, not only this gate) — red when manifest enumeration reverts to `readdirSync`. - `an untracked PACKAGE contributes no entry surface` — red when both fixes are reverted. - `a dirty manifest naming an UNTRACKED target contributes no entry surface` — red when the target intersection is dropped. The shared git fixture builder is factored out of the existing discovery test so all four use one committed baseline. Pins reseeded on 8d280a2: six new contracts entry surfaces from #1993, which the exhaustiveness gate caught on its own, plus dispatch 100 -> 94 and platform-runtime 31 -> 36.
|
Fixed in Leak 1 — untracked package directory, closed at the source
export function readWorkspacePackages(repoRoot: string): WorkspacePackage[] {
for (const manifestFile of listTrackedPackageManifests(repoRoot).sort()) { … }
I checked the blast radius before widening it: Leak 2 — tracked manifest, uncommitted targetRestricting manifests doesn't close this one: the manifest file is committed, the working-tree edit names a target that isn't, and const tracked = new Set(listTrackedProductionSources(repoRoot));
for (const pkg of readWorkspacePackages(repoRoot)) {
for (const target of pkg.exportTargets.values()) {
if (tracked.has(target)) found.add(target);
}
}Every path the function returns is committed, whatever produced it. Fixtures — verified red before the fix, not assumedWriting these was worth it, because the first version of the untracked-package fixture passed against the un-fixed
Each was observed failing on the exact assertion, then restored. The R11 one asserts on package names, so it covers the dependency-edge exposure too, not just export targets. The git fixture builder is factored out so all four discovery tests share one committed baseline. R11's own behaviour after the changeConfirmed, per your note — Pins reseeded on 8d280a2The exhaustiveness gate caught #1993's six new contracts entry surfaces by itself, which is the mechanism working as intended: Also Validation
One flake worth naming so it isn't mistaken for this change: (Noting #1990 is stacked behind this — happy to land as soon as you're satisfied.) |
|
Clean at Deterministic CI is green; Android and iOS smoke are still running. Code review is ready for human. |
thymikee
added
the
ready-for-human
|
1 participant
Summary
ADR-0019's "Implementation-laziness" section requires platform-package façades to stay implementation-lazy and is explicit that a startup threshold alone is not a substitute for preserving the loading shape: "the tracking issue owns the exact probe and planted-red procedure." #1950 built the AST-level walker (
eager-import-closure.fixtures.ts); #1959/#1969 fixed two more instances of the regression class by hand. This PR generalizes the proof into a data-driven budget table so every workspace-package entry surface — and any designated hub module — gets an eager-closure ceiling without a bespoke test file.Three files:
src/__tests__/eager-closure-budgets.ts— the data module: the budget table, the platform-implementation patterns, manifest-derived entry discovery, and the import-chain formatter.src/__tests__/eager-closure-budgets.test.ts— iterates the table and asserts.src/__tests__/eager-import-closure.fixtures.ts— gainseagerClosureGraphOf(predecessor-recording BFS) and per-file edge memoization;eagerClosureOfkeeps its contract and is expressed in terms of it.Discovery has one owner, shared with R11
facadeEntryFiles(repoRoot)lives inscripts/layering/package-boundaries.ts, and both R11's façade gate and this budget table call it — it is one function, not two implementations of the same rule. It takes each package'spackage.jsonexportstargets, then adds every production source under asrc/facades/directory, walking recursively so a nested façade file cannot be covered by one gate and missed by the other.(The first version of this PR claimed to share R11's discovery while actually carrying its own one-level
readdir. That scan missed nested façade files, and missed every manifest-only entry surface — including all six platform façades. It is now genuinely one owner, and R11's façade test is green on it.)This matters concretely: the six
packages/platform-*/src/index.tsfaçades — the exact subject of ADR-0019's implementation-laziness rule — have nofacades/directory at all. A directory-only scan omits them, and the gate would claim to prove the loading shape while never looking at it. A dedicated non-vacuity test asserts all six are discovered.Each platform façade evaluates exactly one module: itself. Its metadata is inline, its contract imports are
import type(erased), and every implementation loads behind a function-scopedawait import. A budget of1is the tightest possible statement of "metadata-eager and implementation-lazy", and a single static value import would destroy it while every other gate stayed green — R3/R13 govern import direction, never evaluation weight.Pins are exact ratchets, asserted with equality
Every pin equals the measured closure size on
04e4c23b9, asserted with equality, not<=. Growing fails, and shrinking also fails until the row is lowered in the same PR — which is what "only ever ratchets down" requires, and what<=does not give: under<=, the moment an entry legitimately shrinks the unchanged row silently becomes headroom for the next regression. No slack in either direction. This matches how the repo pins R9 type-cycle size, R10 writer/owner counts, and test-file line counts — "existing pins only shrink; a new pin requires measured justification" (docs/agents/testing.md). Slack is not neutral for this gate: the regression it catches is a single static import dragging a subtree in, measured by #1969 at 5–12% of suite import work each, and a ceiling carrying "a few files" of spare room silently absorbs the small end of exactly that. Growth stays allowed — it just has to be a visible number change in the diff of the PR that causes it.103 rows: 95 package entry surfaces + 8 designated hubs. The table is two
Record<string, number>literals keyed by entry path, so a duplicate row inside either is a TypeScript error (TS1117) rather than something a laterSetconversion would swallow. Notable values — platform-{apple,android,harmonyos,vega,linux,web}1each;contracts/facades/platform.ts42;contracts/facades/interaction.ts25; most granularized contracts entries1–5;maestro104;src/cli.ts361;src/platform-runtime.ts31(the ADR-0019 composition root);src/daemon/session-teardown.ts89. The hub set includes the five #1969 moved off the wide façades (dispatch,capabilities,registry,platform-execution-entry,register-builtins).Violations name a bounded offending route
eagerClosureGraphOfrecords which file first pulled each module in. A failure prints the entry's heaviest direct edges — ranked by how many modules enter through each, capped at 4 edges and 2 representative routes apiece — so a newly added import is the first thing on screen instead of one chain per evaluated module (which would be 361 lines atsrc/cli.tsscale):What it does not do is diff against a recorded baseline: this gate persists each entry's module count, not its module identity, so it attributes by shortest import route rather than naming which modules are new. For the common case — a new import on the entry itself — that edge is new, its whole subtree is attributed to it, and it sorts first. For a regression deep inside an already-large subtree it names the top-level edge containing the growth. Storing a true delta would mean checking in ~1,500 module paths and rewriting them on every contracts refactor; the docstring states this trade explicitly rather than implying precision the data does not support.
The walk is breadth-first, so every printed chain is the shortest route to that file. Memoizing per-file edges also cut the existing pins' runtime (
cli-startup-import-closure2336ms → ~550ms).Every rule has a failing-direction test
A real tree that satisfies its pins cannot distinguish a correct rule from a vacuous one, so each rule the gate rests on carries its own planted-red test: the equality ratchet (sabotage:
===→<=), the bounded attribution (cap 4 → 999), recursive discovery (recursive → one-level, against a temp fixture tree with a nested façade), and row uniqueness (same path in both records; plus TS1117 for a duplicate key within one). All four were observed red and reverted.Per the lane rule
Planted-red proof (reverted before commit)
Replaced the lazy
await import('./runtime.ts')inpackages/platform-apple/src/index.tswith a static namespace import — the flagship regression this gate exists to catch. Three tests fired:The third is the composition root picking up the blast radius through its own chain — the cascade a flat offender set would not have explained. Sabotage reverted; the diff contains only the three intended files.
On #1969
#1969 is merged and this branch is rebased on it. Its
contracts-entry-closure.test.tsis left in place: both of its tests state properties this table cannot (a specific hub must not reach two named façades; no source file value-imports them — a whole-tree scan, not an entry walk). The five hubs it names are now also budgeted here, so they carry both the specific pin and the general ceiling.Validation
pnpm vitest run --project unit-coreon the new file — 206/206 passing in ~700ms.pnpm typecheck— clean.pnpm check:layering— 181/181 passing (R11's façade gate now runs on the sharedfacadeEntryFiles); R11 reports 95 exported subpaths.pnpm check:fallow— no issues in the changed files.pnpm check:affected --run— all runnable checks passed.Closes #1960