|
| 1 | +# ADR 0027: Descriptor Root Size vs Eager-Closure Budget (Proposed) |
| 2 | + |
| 3 | +## Status |
| 4 | + |
| 5 | +Proposed (2026-09-23). This ADR **decides nothing**. It records a conflict between two invariants |
| 6 | +that are both enforced and both correct, and states the one question a repo owner must answer before |
| 7 | +either invariant can be relied on for module placement. Until then, follow both: do not split the |
| 8 | +descriptor root, and do not add an approval path to the budget gate to let the split through. |
| 9 | + |
| 10 | +## The conflict |
| 11 | + |
| 12 | +[ADR 0008](0008-command-descriptor-registry.md) makes `packages/command-registry/src/registry.ts` |
| 13 | +the single **synchronous** descriptor root. `RAW_COMMAND_DESCRIPTORS` and every derived view — the |
| 14 | +`Command` literal union, the catalog name sets, the `name`-keyed policy maps, batch policy — are |
| 15 | +module-scope values, and consumers reach them through **value** imports. |
| 16 | + |
| 17 | +`AGENTS.md` states that files past 1,000 lines are architecture debt and must be split before adding |
| 18 | +behavior. The descriptor root is past that line. |
| 19 | + |
| 20 | +`scripts/__tests__/eager-closure-budgets.ts` (the ADR 0019 loading-shape probe) measures each |
| 21 | +published entry surface's eager **module count** against the committed merge-base and forbids any |
| 22 | +increase. It has no approval path for growth by design; `APPROVED_OVER_CEILING` applies only to |
| 23 | +first-introduced entries against `NEW_ENTRY_CEILINGS`. |
| 24 | + |
| 25 | +Splitting a hub module necessarily adds static value edges beneath it, so every entry surface that |
| 26 | +reaches it grows by the number of new modules. The two rules have no shared approval path: one says |
| 27 | +the file must be divided, the other says the division must not be visible to any importer. |
| 28 | + |
| 29 | +## Rules at a glance, while unresolved |
| 30 | + |
| 31 | +- Do not split `registry.ts`. The budget gate is the binding constraint and has no waiver. |
| 32 | +- Do not add an approved-growth row, a baseline entry, or a suppression to pass it. That is the |
| 33 | + allowlist `AGENTS.md` forbids. |
| 34 | +- Do not make registry construction asynchronous to dodge the walker. ADR 0008's synchronous root is |
| 35 | + load-bearing for compile-time totality. |
| 36 | +- Closure-neutral edits inside the descriptor root are still welcome: relocating guards beside the |
| 37 | + union they constrain, correcting stale claims, and moving non-eager content out are fine so long as |
| 38 | + every measured entry surface is unchanged. |
| 39 | + |
| 40 | +## Measured |
| 41 | + |
| 42 | +Splitting `RAW_COMMAND_DESCRIPTORS` into eleven family modules plus a shared trait module, byte-faithful |
| 43 | +(80 descriptors, 79 byte-identical including comments), grew **every** entry surface reaching the root |
| 44 | +by exactly **+11** modules. Route for all rows: |
| 45 | +`… → catalog.ts → registry.ts → descriptor-traits.ts + descriptors/*.ts`. |
| 46 | + |
| 47 | +| entry surface | merge-base | split | |
| 48 | +| --- | --- | --- | |
| 49 | +| `src/cli.ts` | 295 | 306 | |
| 50 | +| `packages/session-journal/src/session-event-log.ts` | 92 | 103 | |
| 51 | +| `packages/session-journal/src/session-event-action.ts` | 87 | 98 | |
| 52 | +| `packages/session-journal/src/session-event-action-presentation.ts` | 83 | 94 | |
| 53 | +| `packages/command-registry/src/batch.ts` | 80 | 91 | |
| 54 | +| `packages/session-journal/src/session-event-request.ts` | 75 | 86 | |
| 55 | +| `packages/command-registry/src/batch-policy.ts` | 74 | 85 | |
| 56 | +| `packages/command-registry/src/planned-operations.ts` | 74 | 85 | |
| 57 | +| `packages/command-registry/src/catalog.ts` | 73 | 84 | |
| 58 | +| `packages/command-registry/src/owner-files.ts` | 73 | 84 | |
| 59 | +| `packages/command-registry/src/registry.ts` | 72 | 83 | |
| 60 | + |
| 61 | +Two facts make this unavoidable rather than incidental: |
| 62 | + |
| 63 | +- Extracting only the shared trait module — the smallest possible decomposition — costs **+1** on the |
| 64 | + same eleven surfaces. There is no decomposition of this hub that passes. |
| 65 | +- The walker erases type-only edges, so narrowing consumer imports cannot absorb the cost. These |
| 66 | + consumers need the derived values, not the types. |
| 67 | + |
| 68 | +The cost is genuinely a *count*, not weight: the same bytes are evaluated either way. That is what |
| 69 | +makes the conflict worth deciding rather than absorbing silently, because the gate's proxy and the |
| 70 | +debt rule's proxy disagree at exactly this shape. |
| 71 | + |
| 72 | +## Decision required |
| 73 | + |
| 74 | +May a byte-neutral re-homing of a hub module's contents into new modules raise the eager module count |
| 75 | +of the entry surfaces that reach it — or must a hub module's contents stay inside the file its |
| 76 | +consumers already evaluate? |
| 77 | + |
| 78 | +Answering "the count may rise" needs a bounded, auditable growth allowance on an invariant that |
| 79 | +currently refuses one. Answering "contents stay put" needs `AGENTS.md`'s 1,000-line rule to name the |
| 80 | +exception for a hub whose consumers evaluate it as one unit, so the size is treated as accepted and |
| 81 | +measured rather than as unaddressed debt. Either answer is fine; leaving it unstated means the next |
| 82 | +agent at this file discovers the conflict from a red gate and picks one silently. |
| 83 | + |
| 84 | +## Alternatives considered and refuted |
| 85 | + |
| 86 | +- **Approved-growth row mirroring `APPROVED_OVER_CEILING` (issue, reason, owner):** refuted pending the |
| 87 | + decision above. It would be auditable, but it is an allowlist on the one invariant deliberately |
| 88 | + given no approval path, and `AGENTS.md` forbids adding one to obtain a pass. |
| 89 | +- **Leave the array in place:** the status quo, not a resolution — it leaves the size debt unowned and |
| 90 | + the conflict undocumented. |
| 91 | +- **Function-scoped `await import` per family:** passes the gate by making registry construction |
| 92 | + asynchronous, which removes the compile-time totality and literal-union guarantees ADR 0008 depends |
| 93 | + on. Trading a measured proxy cost for a lost correctness guarantee is the wrong direction. |
| 94 | +- **Reduce descriptor verbosity instead of splitting the file:** legitimate and unexplored, but it |
| 95 | + changes the declaration vocabulary for all ~80 commands, which is a larger change than the split |
| 96 | + and needs its own decision. |
| 97 | + |
| 98 | +## Recovery |
| 99 | + |
| 100 | +A complete, byte-faithful split of the descriptor array exists on |
| 101 | +`refactor/collocation-registry-family-split` (`40bf719a8b`, split commit `ad3aaa520e`) and is pushed. |
| 102 | +It is kept rather than deleted so that answering the question above does not require redoing the |
| 103 | +mechanical work; 80 descriptors, 79 byte-identical including comments. |
0 commit comments