Skip to content

Commit 8ccec5b

Browse files
thymikeeclaude
andauthored
docs(adr): retain the current layering engine (ADR 0032) (#3286)
* chore(layering): add boundary-engine spike harness Measures dependency-cruiser 18.5 and fallow 3.32 against the custom layering edge model for R2, R4, R5, R6, R77, R78, R14 and R71: edge-set diff, planted-violation parity, and runtime. Not a gate; ADR 0032 owns its deletion. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * docs(adr): keep the custom layering edge model (ADR 0032) Records the #3278 boundary-tool spike: neither dependency-cruiser nor fallow boundaries reaches parity for the eight plain graph rules, and either would add a second import graph beside the one ~20 other rules consume. Includes the four comparison tables and revisit triggers. Closes #3278 Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(layering): make the boundary-engine spike reproducible - Refuse to run unless the production roots hold exactly the tracked tree: the engines read the disk, the custom rules read tracked files. - Exclude test modules, helpers included, from R4 (start, first hop and via nodes) and R5/R6 through one TEST_PATH pattern. - Report engine stderr, exit status and signal when output is not JSON. - Record plants in a manifest before touching the tree; restore on exit, error and SIGINT/SIGTERM/SIGHUP, and at the next start after SIGKILL. - Median of five runs, and measure every runtime the ADR reports. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * docs(adr): re-measure ADR 0032 on the reproducible harness Runtime table and fallow's marginal cost now come from the harness run; custom messages cite check.ts report() instead of ADR 0010; the index entry says the ADR evaluates a replacement rather than performing one. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * fix(layering): never restore over files edited since a spike plant The plant manifest outlives a killed run, so restoring it blindly could overwrite a tracked file edited in between. Record each touched file's content before and after planting; restore only when every file still holds one of the two, and otherwise stop without touching anything. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * docs(adr): anchor ADR 0032 to the commit its tables were measured at Status names d9959f5, where the harness produced the tables (its production tree is 7dda0c2's); the Measured section separates what the harness emits from the line counts of the deletion table; runtimes are re-measured there, and fallow's marginal cost is stated as within noise. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * docs(adr): pin ADR 0032 to d9959f5 and drop the spike harness The harness imports internal symbols from six layering modules, and no gate typechecks or fallow-scans scripts/layering/, so a rename would break it silently. It now lives only at d9959f5, where every number in the ADR was produced; the Measured and Deletion sections retrieve it with git show. Numbers the pinned run did not emit are removed or stated as file counts at that commit. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * docs(adr): name the spine symbols the pinned harness reads At d9959f5 the harness derives R5/R6 from model.ts's RANKED_ZONES and zoneRank, not TARGET_DAG_RANK, and writes the other rules' paths inline (R77's from RUNNER_SUBTREE) rather than reading the rule tables. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> * docs(adr): narrow ADR 0032 to one replaceable import model Adopt the maintainer's decision statement. Graph-based checks share one normalized import model whose implementation stays replaceable; list its actual consumers and the facts they need instead of tying it to the AST rules. Separate the semantic blockers (missed dynamic imports, orphan files) from migration costs (formatting, config comments, a path check for filesystem-placement rules), retarget the revisit triggers, and link the parser-gap follow-up #3293. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]> --------- Co-authored-by: Claude Opus 5.5 (1M context) <[email protected]>
1 parent 0c1ebb3 commit 8ccec5b

2 files changed

Lines changed: 172 additions & 0 deletions

File tree

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
# ADR 0032: Layering Graph Engine — Retain the Current Engine
2+
3+
## Status
4+
5+
Accepted (2026-10-07). Spike for #3278 (umbrella #3276). Every measurement is pinned to `d9959f510`,
6+
whose production tree is `7dda0c2bf`'s; the harness lives only at that commit
7+
([Deletion](#deletion)). No rule moves.
8+
9+
## Rules at a glance
10+
11+
- R2, R4, R5, R6, R77, R78, R14 and R71 stay on the current engine. Neither dependency-cruiser 18.5
12+
nor fallow 3.32 replaces them.
13+
- Graph-based checks share one normalized import model, today built by `parseImports` and
14+
`resolveImportEdges`. Do not enforce a subset of them from a second, disagreeing import graph.
15+
- The model's implementation remains replaceable. Besides these eight rules, it must supply
16+
resolved edges with value, type-only and dynamic kinds to R9/R10, R19, R73–R76 and
17+
`scripts/depgraph/`; named symbols and the binding residue of dynamic imports to R76; and raw
18+
specifier sites to R11 and R13. Eleven other registry entries read source ASTs or text only, and
19+
one reads paths only.
20+
- Fix the demonstrated parser gap in #3293: `parseImports` misses TypeScript `import('x').T` type
21+
positions (9 file pairs). It already parses an OXC AST for dynamic imports but scans static
22+
imports with regexes; read both from that AST, `TSImportType` included, keeping symbol and
23+
edge-kind semantics, rather than adding a second extractor.
24+
- Do not upgrade fallow to 3.x for `boundaries`; revisit on a [trigger](#revisit-triggers).
25+
26+
## Measured
27+
28+
The edge-set, parity, clean-tree and runtime numbers are the output of the spike harness run at
29+
`d9959f510`. Retrieve it with `git show d9959f510:scripts/layering/boundary-engine-spike.ts`, after
30+
`git fetch origin pull/3286/head` if the commit is not local; usage is in its header. It derives
31+
both engines' R5 and R6 rules from `model.ts`'s `RANKED_ZONES` and `zoneRank`, writes the other
32+
rules' paths inline (R77's from `RUNNER_SUBTREE`), runs only on exactly the tracked production tree
33+
(1,837 files, 41 zones), and gives recorded R6 and R78 edges to each engine's known-violations
34+
baseline. The deletion table and the `.fallowrc.json` field count are counts of files at the same
35+
commit.
36+
37+
### Edge-set diff against `resolveImportEdges`
38+
39+
| | custom | dependency-cruiser 18.5 | fallow 3.32 |
40+
| --- | --- | --- | --- |
41+
| file pairs | 9,775 | 9,784 | 9,784 |
42+
| custom pairs missing | — | 0 | 0 |
43+
| extra pairs | — | 9 | the same 9 |
44+
| kind disagreement | — | 46 pairs | 0 on value vs type |
45+
| dynamic kind | yes | yes, 46 pairs mislabelled | not represented |
46+
47+
The 9 extra pairs are `import('./x').T` type positions custom misses; both engines are right.
48+
49+
The umbrella's 3.1.1 cross-check missed 88 dynamic and type-only edges; 18.5 misses none but
50+
mislabels 46 pairs (33 dynamic → type, 8 dynamic+type → type, 5 dynamic+value → value): its
51+
hardcoded `getDependencyUniqueKey` dedupes on `(specifier, moduleSystem, type-only flag)`, so
52+
`typeof import('./x').f` and `await import('./x')` keep whichever comes first.
53+
54+
fallow's value-versus-type split matches custom on every pair, with no dynamic kind. Its boundary
55+
check follows `export type *` barrels to the declaring module: the import
56+
`src/commands/cli-runner.ts → src/agent-device-client.ts` counts as `commands → client`, one more R6
57+
finding. Clean tree: custom 0, depcruise 10 (3 R6 survivors, 7 recorded R78 edges), fallow 11.
58+
59+
### Planted-violation parity
60+
61+
`pass` rows are the closest negative custom admits; ✗ is a missed `flag` or a flagged `pass`.
62+
63+
| Plant | Expect | custom | depcruise | fallow |
64+
| --- | --- | --- | --- | --- |
65+
| R2 daemon value-imports commands | flag | ✓ | ✓ | ✓ generic |
66+
| R2 core type-imports commands | flag | ✓ | ✓ | ✓ generic |
67+
| R2 commands imports commands/schema | flag | ✓ | ✓ | ✓ generic |
68+
| R4 value cycle | flag | ✓ | ✓ | ✓ |
69+
| R4 type-only cycle | pass | ✓ | ✓ | ✓ |
70+
| R4 cycle closed by a lazy `import()` | pass | ✓ | ✓ | ✓ |
71+
| R5 core value-imports cli | flag | ✓ | ✓ | ✓ generic |
72+
| R5 static re-export after an `import()` type | flag | ✓ | ✓ | ✓ generic |
73+
| R5 core lazy-imports cli | pass | ✓ | ✓ | ✗ flagged |
74+
| R6 new type-only inversion pair | flag | ✓ | ✓ | ✓ generic |
75+
| R77 named import, reachable module | flag | ✓ | ✓ | ✓ |
76+
| R77 re-export, reachable module | flag | ✓ | ✓ | ✓ |
77+
| R77 lazy `import()`, reachable module | flag | ✓ | ✓ | ✗ |
78+
| R77 named import, orphan module | flag | ✓ | ✓ | ✗ |
79+
| R77 runner test file | flag | ✓ | ✓ | ✓ |
80+
| R77 lazy `import()` after an `import()` type | flag | ✓ | ✗ | ✗ |
81+
| R77 type-only import | pass | ✓ | ✓ | ✓ |
82+
| R78 client value-imports daemon | flag | ✓ | ✓ | ✓ generic |
83+
| R78 unrecorded client type import | flag | ✓ | ✓ | ✓ generic |
84+
| R78 recorded edge removed (stale) | flag | ✓ | exit 0 | ✓ exit 1 |
85+
| R14 orphan `.ts` under `src/utils` | flag | ✓ | ✓ | ✓ generic |
86+
| R14 non-TS file under `src/utils` | flag | ✓ | ✗ | ✗ |
87+
| R71 file under `src/replay` | flag | ✓ | ✓ | ✓ generic |
88+
89+
Custom prints `file:line`, rule id and hint (`report()` in `scripts/layering/check.ts`); depcruise
90+
the rule name and an authored comment, without a line. "Generic" means a fallow zone pair
91+
(`core → cli`) and a docs link, with no rule id or hint; R14 and R71 surface as "matches no zone".
92+
fallow's R77 rule pack carries an id, message and line. On the stale row, depcruise reports
93+
`summary.baselineStale: 1` and exits 0; fallow's `--fail-on-stale-baseline` exits 1.
94+
95+
### Runtime
96+
97+
Medians of 5 runs after a warm-up, on a shared host (load average 9–17):
98+
99+
| | custom | depcruise | fallow |
100+
| --- | --- | --- | --- |
101+
| graph build | 0.74 s, shared and kept | 1.66 s (tsc), 1.56 s (swc) | 3.04 s standalone |
102+
| the eight rules | 0.10 s | included | included |
103+
| marginal CI cost | 0.10 s | +1.6 s, a second graph | none measurable in the repo's dead-code run (3.23 → 3.13 s) |
104+
105+
### Lines deletable
106+
107+
Rule plus test lines a full migration would delete. The resolver and the R4/R5/R6 pair helpers that
108+
`scripts/depgraph/` reads stay either way.
109+
110+
| Rule | Code deleted | Lines | depcruise parity | fallow parity |
111+
| --- | --- | --- | --- | --- |
112+
| R2 | `zone-policy.ts`, `commands-schema-boundary.ts`, `checkLayeringRules` | 302 | full | generic message |
113+
| R4 | `checkCycles` | 22 | full | full; also scans tests |
114+
| R5 | `checkBackEdges`, `collectBackEdges`, model tests | 90 | full | flags lazy seams |
115+
| R6 | `type-inversion-ratchet.ts`, `typeInversionCounts` | 166 | exact-edge baseline | exact-edge baseline |
116+
| R77 | `apple-runner-host-port-policy.ts` | 141 | masking miss | misses `import()`, orphans |
117+
| R78 | `daemon-client-entry.ts` | 260 | stale needs a wrapper | generic message |
118+
| R14, R71 | `retired-paths-policy.ts` | 218 | TS only (R14 gap) | TS only, generic |
119+
| shared | registry, imports, success line in `check.ts` | ≈25 | | |
120+
121+
About 1,224 lines, half of them tests; a migration adds a generator like the harness's
122+
`depcruiseConfig` and helpers (122 lines at `d9959f510`). An exact-edge R6 baseline also changes
123+
policy: it rejects swapping one inversion for another within a pair, which the per-pair count
124+
ratchet admits.
125+
126+
## Decision
127+
128+
Retain the current engine because the evaluated replacements do not provide sufficient semantic
129+
parity and net simplification. Graph-based checks share one normalized import model; its
130+
implementation remains replaceable. Continue replacing generic algorithms and compiler-enforceable
131+
rules with maintained tools. Fix the demonstrated parser gap.
132+
133+
The semantic blockers are the correctness gaps in the parity table:
134+
135+
- **dependency-cruiser** deduplicates a file's dependencies on a key that omits the dynamic and
136+
`import()`-type kinds. That mislabels 46 pairs and lets a lazy `import()` hide behind an
137+
`import()` type of the same target, the R77 miss.
138+
- **fallow** has no dynamic-import kind, so it flags the lazy seams R5 admits and misses R77's
139+
`import()`. Its rule packs skip files no entry point reaches, so it also misses an orphan runner
140+
module.
141+
142+
Simplification is limited. dependency-cruiser matches custom on R2, R4, R5 and R71, where migration
143+
would delete about 430 lines. The shared model stays for its other consumers, so the gate would read
144+
two import graphs that disagree.
145+
146+
The rest are migration costs, which would not decide the question on their own:
147+
148+
- dependency-cruiser needs `typescript@<7` or `@swc/core` beside TypeScript 7 (+1.6 s), and a
149+
wrapper that fails on `summary.baselineStale`. Its diagnostics carry no line.
150+
- fallow 3.x rejects the 73 `comment` fields in `.fallowrc.json`, and its boundary findings carry no
151+
rule id or hint. It adds no measurable time and has the best stale gate.
152+
- R14 and R71 are filesystem-placement policies. A non-TS path under `src/utils` needs a path check
153+
with either engine; that is not a failure of an import engine.
154+
155+
## Revisit triggers
156+
157+
- dependency-cruiser keys deduplication on the dependency type.
158+
- fallow boundaries gain a dynamic-import kind, and its rule packs cover files no entry point
159+
reaches.
160+
- An engine can supply the shared import model above to the existing consumers with less total
161+
machinery than `parseImports` and `resolveImportEdges`. The source-only AST checks do not have to
162+
change first.
163+
164+
## Deletion
165+
166+
The harness is not in the tree. It imports internal symbols from six layering modules (`check.ts`,
167+
`model.ts`, `package-boundaries.ts`, `ratchet-reference.ts`, `apple-runner-host-port-policy.ts`,
168+
`tracked-sources.ts`), and no gate would keep it compiling: `tsconfig.json` does not include
169+
`scripts/layering/`, and fallow ignores it. The change that evaluates a revisit trigger retrieves
170+
the harness from `d9959f510`, ports it to the internals of its own tree, re-runs it, updates the
171+
tables here, and deletes any migrated rule's code listed in the deletion table.

‎docs/adr/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@
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 |
3535
| [0031 macOS Native App Backend](0031-macos-native-app-backend.md) | `AGENT_DEVICE_MACOS_APP_BACKEND`, driving macOS app sessions without XCTest Automation Mode, why pointer actions are accessibility actions only, and the ghost cursor |
36+
| [0032 Layering Graph Engine](0032-layering-graph-engine.md) | evaluating replacement of `scripts/layering/` graph rules with dependency-cruiser or fallow `boundaries`, why graph-based layering checks share one replaceable import model, the measured edge-set and parity gaps, and the revisit triggers |
3637

3738
ADRs record *why*; the registries and gates they describe are the living source of truth — when
3839
prose and a registry disagree, the registry wins and the ADR needs a follow-up.

0 commit comments

Comments
 (0)