Skip to content

Commit efd2108

Browse files
authored
docs(adr): retire the parity-gate claim, state press-shape refusal, record the descriptor-root block (#2808)
* docs(adr): retire the parity-gate claim, state press-shape refusal, record the descriptor-root block ADR 0008 still promises a class of check that no longer exists. The parity test its migration rule required lost its second operand as each hand table was inverted out (#907, #908, #909, #1084, #1137); the retirement is recorded in Status and the present-tense claims are corrected, while the migration rule itself is left intact because it was followed. ADR 0019 gains the rule that a shape of an operation is not an operation and gets no fact cell, which is what a per-shape refusal on the owning leaf mechanic rests on. ADR 0027 records, without deciding, the conflict that makes the descriptor root unshippably splitable: ADR 0008's synchronous hub and the ADR-0019 eager-closure module-count budget have no shared approval path. Measured: any decomposition of the root, even the smallest, grows eleven entry surfaces. * docs(adr): propose one runtime source for the capability-family cell vocabulary Adding an operation family edits the cell key twice in one file: once as a property of UnavailablePlatformRuntimeFacts and again as a value in UNAVAILABLE_CELLS, which cannot be derived from the type. satisfies makes drift a compile error, so this is a maintenance tax rather than a soundness hole -- but it is why a file with fan-in 6 churned 9 times in 200 commits, and why one capability still fans out across eight packages. Proposes the inversion the repo already proved on the binding axis (INTERACTOR_OPERATIONS) for the facts axis, and states what it deliberately does not grant: no default-deny baseline, because ADR 0019 requires exhaustive per-shape facts and forbids cross-family defaults in a platform package. Gated on a measurement and on eager-closure neutrality, with withdrawal as an acceptable outcome. * docs(adr): point ADR 0027 at the pushed, recoverable descriptor split
1 parent 12d3f5a commit efd2108

5 files changed

Lines changed: 210 additions & 2 deletions

‎docs/adr/0008-command-descriptor-registry.md‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,15 @@ Accepted
99
> preferred runtime use joined with leaf/device/provider-specific runtime facts; inventory commands
1010
> declare inventory use instead of fabricating a device binding. The descriptor's other derived
1111
> projections remain accepted.
12+
>
13+
> **Parity gate retired (2026-09).** The migration rule below — assert each derived table
14+
> byte-for-byte against its hand-authored table before deleting the hand table — was followed, and
15+
> completing it removed the gate's second operand. Each hand table went away as its projection was
16+
> inverted out: #907 daemon routes, #908 capability matrix, #909 batch allowlist, #1084
17+
> daemon-client timeout lists, #1137 MCP exposure list. No parity test exists. Do not add one or
18+
> look for one; the totality invariants are now carried by compile-time guards
19+
> (`CommandOwnerFileClaimsAreComplete`) and by literal pin-set tests that compare a name set rather
20+
> than two tables.
1221
1322
## Context
1423

@@ -32,7 +41,7 @@ model must preserve. This ADR is that model.
3241
## Decision
3342

3443
Introduce one `CommandDescriptor` per command that **composes facets owned by their domains** and from which
35-
every consumer table is **derived** by pure, parity-tested projection:
44+
every consumer table is **derived** by pure projection:
3645

3746
- The descriptor composes catalog identity, command-family surface projection hooks
3847
(`src/commands/**` remains the owner of CLI schema/reader and executable surface metadata), a
@@ -95,4 +104,4 @@ modules must move those contracts before their client methods can stop returning
95104
`CommandRequestResult`.
96105

97106
This ADR owns the decision and its constraints; the roadmap that prototyped it has been retired, with
98-
the delivered end-state enforced by the descriptor projections and parity gates below.
107+
the delivered end-state enforced by the descriptor projections below.

‎docs/adr/0019-request-bound-platform-runtime.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,12 @@ a narrow neutral typed service, not diagnostics alone. Host diagnostics, daemon-
1212
cleanup, and managed host tooling share the execution category because none binds a request-scoped
1313
device runtime; their domain services remain separate rather than forming a generic host grab bag.
1414

15+
Amendment proposed 2026-09-23 alongside the web press-shape refusal: it states in section 3 that a
16+
modifier on an admitted operation is not a second operation and therefore has no fact cell, which is
17+
what a per-shape refusal on the owning leaf mechanic rests on. Without that sentence the next
18+
contributor reasonably reaches for a per-shape fact key, which the operation-facts mapped type cannot
19+
express.
20+
1521
Amendment proposed 2026-09-14 by [ADR 0024](./0024-screen-recording-provable-signal.md) for the
1622
`screen-recording` kind only; see the note at the head of section 5. It takes effect when ADR 0024
1723
is accepted.
@@ -268,6 +274,15 @@ stubs that throw `unsupported` after binding. Runtime-use keys identify individu
268274
operations, not whole facet namespaces, so selecting one operation does not expose undeclared sibling
269275
operations from the same facet.
270276

277+
**A shape of an operation is not an operation and gets no fact cell.** Runtime facts speak per
278+
semantic operation; a modifier applied to an admitted operation — a press that is double, held, or
279+
repeated — is not a second operation and must not be given a fact key, because the facts map is a
280+
mapped type over operation names and a phantom operation satisfies neither the required nor the
281+
preferred runtime-use shape. Such a shape is refused by the owning leaf mechanic being absent, with a
282+
typed reason and a hint, at the point the shape is requested. Absence of a whole admitted
283+
operation's member remains an ownership bug and fails closed with its own typed reason; it is never
284+
the mechanism that expresses an unsupported shape.
285+
271286
`RequestExecutionScope.bindDevice(device, use)` is the trust choke point. It:
272287

273288
1. resolves the exact local or provider runtime owner;
Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
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.
Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# ADR 0028: Capability-Family Cell Vocabulary — One Runtime Source (Proposed)
2+
3+
## Status
4+
5+
Proposed (2026-09-23). Proposes inverting one vocabulary so adding a capability family is a single
6+
declaration instead of a coordinated edit across a type, a table, and every runtime owner. It decides
7+
**no** defaulting behavior, and it does not weaken any ADR 0019 rule. Ship only after the measurement
8+
below shows the fan-out actually shrinks.
9+
10+
## Why now, and what the numbers said
11+
12+
Over the last 200 commits, 8 commits touched eight or more packages, across only five distinct
13+
package combinations — and one of those combinations recurred four times. Each was one capability
14+
(`action-button`, `fold`, preferred text size) propagating through every runtime owner. Within
15+
`@agent-device/contracts`, `platform-runtime-unavailable.ts` churned 9 times with fan-in of only 6:
16+
the most-changed file in the repo that almost nothing imports. That signature is a declaration site
17+
paying a coordination tax, not a behavioral hotspot.
18+
19+
## What is actually duplicated
20+
21+
Not the behavior — the **cell vocabulary**. Adding one operation family currently means editing, in
22+
`@agent-device/contracts`:
23+
24+
1. the family's own `xxx-runtime.ts` fact builder,
25+
2. `UnavailablePlatformRuntimeFacts` (`platform-runtime-unavailable.ts`) — a type property,
26+
3. `UNAVAILABLE_CELLS` in the same file — a `{ cell: true } satisfies Record<UnavailableCellKey, true>`
27+
value listing the same keys again, because a type's key set cannot be enumerated at runtime,
28+
4. `PlatformRuntimeOperations`,
29+
5. `runtime-operation-names.ts`,
30+
6. one row in `INTERACTOR_OPERATIONS`.
31+
32+
(2) and (3) are the same list written twice. `satisfies` makes drift a compile error, so this is **not**
33+
a soundness hole — it is a maintenance tax paid on every family. A runtime row table would make the
34+
value authoritative and the type derived from it.
35+
36+
The repo has already done exactly this inversion once, and should copy it rather than invent:
37+
`interactor-operation-catalog.ts` replaced "three parallel declarations — a name tuple, a local binder
38+
map, and a provider binder map" with `INTERACTOR_OPERATIONS`, one row per operation. The binding axis
39+
is single-sourced. The **facts** axis is not.
40+
41+
## Rules at a glance
42+
43+
- One runtime row per capability family is the authority for its cell key; the cell-key type is
44+
derived from that table, not maintained beside it.
45+
- A runtime owner still reports **exhaustive** facts for its exact device shape
46+
([ADR 0019](0019-request-bound-platform-runtime.md), section 3). Deriving the *list of cells* is
47+
allowed; deriving an owner's *answer* for a cell is not.
48+
- No cross-family default denial set. An owner that does not state a cell is a bug, not an
49+
unsupported result.
50+
- Lifecycle keeps its own authority. `platform-runtime-unavailable.ts` exists "for provider ownership
51+
gaps" and never assigns lifecycle semantics; that stays out of the table.
52+
53+
## Explicitly not proposed
54+
55+
- **A default-deny baseline owners inherit.** ADR 0019 requires exhaustive per-shape facts and forbids
56+
cross-family defaults in a platform package, so the current ~35-cell enumeration in an owner such as
57+
`packages/platform-linux/src/runtime.ts` is intentional. Removing it needs an ADR that supersedes
58+
those two rules on the merits, not a table that quietly reimplements them.
59+
- **Moving the vocabulary out of `@agent-device/contracts`.** It already lives at the lowest ranked
60+
zone; the `depgraph` README's 42→48 lesson applies — moving a vocabulary file down made the gate
61+
worse because the vocabulary itself imports upward.
62+
- **A new generator.** The catalog precedent is a hand-written row array with derived views.
63+
64+
## Measurement required before acceptance
65+
66+
This ADR exists to stop an eight-package fan-out. Before landing any inversion, measure on a real
67+
family rather than arguing from the shape:
68+
69+
1. Pick the next capability family. Land only the single-source cell vocabulary (steps 2-3 above).
70+
2. Report the change in files-touched for that family against the recorded baseline of the four
71+
recurring eight-package commits.
72+
3. Report eager-closure deltas per entry surface. `scripts/__tests__/eager-closure-budgets.ts` has no
73+
growth-approval path, and [ADR 0027](0027-descriptor-root-vs-eager-closure-budget.md) shows a
74+
byte-neutral re-home can be unshippable here. A row table is a **new eager value**; if it costs
75+
closure slots, it is blocked on the same ground and this ADR should be withdrawn rather than
76+
granted an exception.
77+
78+
If the fan-out does not visibly shrink, close this as rejected and leave the two authored lists in
79+
place — a compile-checked duplicate is a legitimate resting state.

‎docs/adr/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,8 @@
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 (Proposed)](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 (Proposed)](0027-descriptor-root-vs-eager-closure-budget.md) | splitting `packages/command-registry/src/registry.ts`, the ADR-0019 eager-closure module-count budget, and why a byte-neutral hub split is currently unshippable |
32+
| [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 |
3133

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

0 commit comments

Comments
 (0)