|
1 | | -# ADR 0028: Capability-Family Cell Vocabulary — One Runtime Source (Proposed) |
| 1 | +# ADR 0028: Capability-Family Cell Vocabulary — Retain Compile-Checked Declarations |
2 | 2 |
|
3 | 3 | ## Status |
4 | 4 |
|
5 | | -Proposed (2026-09-23). |
6 | | -This ADR proposes to invert one vocabulary. |
7 | | -Then a new capability family needs a single declaration, not a coordinated edit across a type, a table, and every runtime owner. |
8 | | -It decides **no** defaulting behavior, and it does not weaken any ADR 0019 rule. |
9 | | -Ship only after the measurement below shows that the fan-out actually decreases. |
| 5 | +Rejected (2026-10-29). |
| 6 | +The proposed single-source cell table is rejected as a solution to cross-owner capability fan-out. |
| 7 | +Retain the authored input properties and the compile-checked `UNAVAILABLE_CELLS` table. |
| 8 | +[The bounded measurement](../evidence/capability-cell-vocabulary-2026-10-29.md) found no file or package saving. |
| 9 | +It was a cell-level surrogate, not the proposed next-family experiment or a whole-feature replay. |
10 | 10 |
|
11 | | -## Why now, and what the numbers said |
| 11 | +## Decision and reason |
12 | 12 |
|
13 | | -Of the last 200 commits, 8 affected at least eight packages. |
14 | | -They used only five distinct package combinations. |
15 | | -One combination recurred four times. |
16 | | -Each change propagated one capability through every runtime owner: `action-button`, `fold`, or preferred text size. |
| 13 | +`platform-runtime-unavailable.ts` declares input properties and repeats their keys in a value table. |
| 14 | +The `satisfies` check makes key disagreement a compile error. |
| 15 | +This duplicate is a maintenance cost, not a soundness defect. |
17 | 16 |
|
18 | | -Within `@agent-device/contracts`, `platform-runtime-unavailable.ts` changed 9 times but had only 6 importers. |
19 | | -It was the most-changed file in the repository that almost nothing imports. |
20 | | -This pattern shows a declaration site that pays a coordination cost, not a behavioral hotspot. |
| 17 | +A local runtime table can derive the input type and remove one authored key declaration. |
| 18 | +Both declarations already occupy the same file and package. |
| 19 | +The measured substitution therefore did not reduce the coordination boundary. |
| 20 | +It also replaced the explicit input contract with required/optional metadata and mapped types. |
| 21 | +Unchanged eager closures do not establish a coordination or quality benefit. |
21 | 22 |
|
22 | | -## What is actually duplicated |
| 23 | +The proposal required a visible reduction in fan-out before acceptance. |
| 24 | +Its closing rule required rejection if that reduction did not occur. |
| 25 | +The bounded result does not justify adoption. |
23 | 26 |
|
24 | | -The duplicate is **cell vocabulary**, not behavior. |
25 | | -A new operation family currently requires these `@agent-device/contracts` edits: |
| 27 | +## Retained constraints |
26 | 28 |
|
27 | | -1. The family's `xxx-runtime.ts` fact builder |
28 | | -2. A type property in `UnavailablePlatformRuntimeFacts` (`platform-runtime-unavailable.ts`) |
29 | | -3. The same keys in that file's `UNAVAILABLE_CELLS`, a `{ cell: true } satisfies Record<UnavailableCellKey, true>` value |
30 | | -4. `PlatformRuntimeOperations` |
31 | | -5. `runtime-operation-names.ts` |
32 | | -6. One `INTERACTOR_OPERATIONS` row |
| 29 | +[ADR 0019](0019-request-bound-platform-runtime.md), section 2, retains exhaustive owner facts for the exact device shape. |
| 30 | +A cell-key declaration must not derive an owner's availability answer. |
| 31 | +A missing required cell remains a bug. |
| 32 | +The existing optional cells retain their `network` fallback in `freezeUnavailableFacts`. |
| 33 | +This decision adds no default behavior or cross-family default denial set. |
33 | 34 |
|
34 | | -Items 2 and 3 duplicate one list because runtime cannot enumerate type keys. |
35 | | -`satisfies` makes disagreement a compile error. |
36 | | -This is a maintenance cost, not a soundness defect. |
37 | | -A runtime row table would own the values and derive the type. |
| 35 | +Lifecycle retains separate authority. |
| 36 | +`platform-runtime-unavailable.ts` does not assign lifecycle semantics. |
| 37 | +No generator or vocabulary move is introduced. |
| 38 | +[ADR 0027](0027-descriptor-root-vs-eager-closure-budget.md) still governs any future eager-closure change. |
38 | 39 |
|
39 | | -The repository already uses this inversion in `interactor-operation-catalog.ts`. |
40 | | -`INTERACTOR_OPERATIONS` replaced three declarations: a name tuple, local binder map, and provider binder map. |
41 | | -The binding axis has one source. |
42 | | -The facts axis does not. |
43 | | -The proposal should copy this existing design and not invent a new one. |
| 40 | +## Consequences |
44 | 41 |
|
45 | | -## Rules at a glance |
| 42 | +Keep the explicit input contract and the exhaustive key table synchronized. |
| 43 | +A future proposal needs evidence that duplicate vocabulary causes an avoidable file or owner edit. |
| 44 | +Family-level cells can already accommodate new operations without a new cell key. |
| 45 | +Rejecting this table does not reject every future vocabulary design. |
46 | 46 |
|
47 | | -This ADR proposes these rules: |
48 | | - |
49 | | -- One runtime row per capability family owns its cell key. |
50 | | - The table derives the cell-key type instead of a separately maintained type. |
51 | | -- Each runtime owner still reports exhaustive facts for its exact device shape under [ADR 0019](0019-request-bound-platform-runtime.md), section 2. |
52 | | - Derivation may enumerate cells. |
53 | | - It must not derive an owner's answer for a cell. |
54 | | -- There is no cross-family default denial set. |
55 | | - If an owner does not state a cell, that omission is a bug, not an unsupported result. |
56 | | -- Lifecycle retains separate authority. |
57 | | - `platform-runtime-unavailable.ts` exists "for provider ownership gaps" and never assigns lifecycle semantics. |
58 | | - Lifecycle stays out of the table. |
59 | | - |
60 | | -## Explicitly not proposed |
61 | | - |
62 | | -This proposal excludes these changes: |
63 | | - |
64 | | -- **Inherited default-deny baseline.** ADR 0019 requires exhaustive per-shape facts and forbids platform-package cross-family defaults. |
65 | | - Thus, the current enumeration of about 35 cells in an owner, such as `packages/platform-linux/src/runtime.ts`, is intentional. |
66 | | - Removal needs an ADR that supersedes those two rules on the merits. |
67 | | - A table that quietly reimplements them is not sufficient. |
68 | | -- **Vocabulary outside `@agent-device/contracts`.** It already occupies the lowest ranked zone. |
69 | | - The `depgraph` README's 42→48 example applies. |
70 | | - Moving vocabulary downward worsened the gate because its imports pointed upward. |
71 | | -- **New generator.** The existing catalog uses a hand-written row array with derived views. |
72 | | - |
73 | | -## Measurement required before acceptance |
74 | | - |
75 | | -This ADR exists to stop an eight-package fan-out. |
76 | | -Before you introduce any inversion, measure a real family. |
77 | | -Do not argue from the shape alone: |
78 | | - |
79 | | -1. Select the next capability family. |
80 | | - Introduce only the single-source cell vocabulary, items 2-3 above. |
81 | | -2. Report the change in files touched for that family. |
82 | | - Compare it with the recorded baseline of the four recurring eight-package commits. |
83 | | -3. Report eager-closure differences for each entry surface. |
84 | | - |
85 | | -`scripts/__tests__/eager-closure-budgets.ts` has no growth-approval mechanism. |
86 | | -[ADR 0027](0027-descriptor-root-vs-eager-closure-budget.md) permits module-count growth only under all three conditions: |
87 | | - |
88 | | -- The head closure preserves every merge-base module. |
89 | | -- Each newly evaluated module is new to the merge-base tree or is a rename. |
90 | | -- Total module-scope weight does not increase. |
91 | | - |
92 | | -A row table is a **new eager value**. |
93 | | -It must satisfy all three conditions to pass. |
94 | | -If it does not satisfy them, the gate stays red. |
95 | | -In that case, this ADR should be withdrawn, and it should not get an exception. |
96 | | -If the fan-out does not visibly decrease, close this ADR as rejected and retain both authored lists. |
97 | | -A compile-checked duplicate is a legitimate resting state. |
| 47 | +Decision history: The 2026-09-23 proposal was rejected after [the bounded retain decision in #4056](https://github.com/callstack/agent-device/issues/4056#issuecomment-6499398178). |
0 commit comments