Skip to content

Commit 4e9192d

Browse files
committed
docs(adr): reject cell vocabulary inversion without coordination savings
1 parent 144bd59 commit 4e9192d

3 files changed

Lines changed: 115 additions & 85 deletions

File tree

Lines changed: 34 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -1,97 +1,47 @@
1-
# ADR 0028: Capability-Family Cell Vocabulary — One Runtime Source (Proposed)
1+
# ADR 0028: Capability-Family Cell Vocabulary — Retain Compile-Checked Declarations
22

33
## Status
44

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.
1010

11-
## Why now, and what the numbers said
11+
## Decision and reason
1212

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.
1716

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.
2122

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.
2326

24-
The duplicate is **cell vocabulary**, not behavior.
25-
A new operation family currently requires these `@agent-device/contracts` edits:
27+
## Retained constraints
2628

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.
3334

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.
3839

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
4441

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.
4646

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).

‎docs/adr/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@
2929
| [0025 Foldable Apple Panels — Capture the Lit Panel](0025-foldable-apple-panels.md) | iPhone Duo outer/inner panels, the screen authority (CoreDevice display info in the default set, the guest panel read in a scoped set), black-panel capture from `simctl`'s implicit display default, derived (never asserted) pose, `fold` pose control with guest hinge and scoped-set panel readback, and the Android emulator posture amendment |
3030
| [0026 Scroll Clip Authority — Ownership Is the Parent Edge](0026-scroll-clip-authority.md) | iOS scroll indicators and the visible band, parent-edge ownership instead of ancestor traversal, permitted node removal from interactive snapshots, and ejection dispositions |
3131
| [0027 Descriptor Root Size vs Eager-Closure Budget](0027-descriptor-root-vs-eager-closure-budget.md) | accepted: the eager-closure budget permits only a statement-neutral hub split (containment + added-module novelty + flat top-level-statement weight); `packages/command-registry/src/registry.ts` may be split |
32-
| [0028 Capability-Family Cell Vocabulary — One Runtime Source (Proposed)](0028-capability-family-cell-vocabulary.md) | capability operation family additions, `UnavailablePlatformRuntimeFacts` / `UNAVAILABLE_CELLS`, `INTERACTOR_OPERATIONS`, and the reason for repeated changes across eight packages |
32+
| [0028 Capability-Family Cell Vocabulary — Retain Compile-Checked Declarations](0028-capability-family-cell-vocabulary.md) | rejected single-source cell table; retained explicit input contract, exhaustive owner facts, optional-cell fallback, and lifecycle authority |
3333
| [0029 Daemon Policy](0029-daemon-policy.md) | `AGENT_DEVICE_DAEMON_POLICY`, limits on daemon 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`, macOS app sessions without XCTest Automation Mode, the accessibility-only pointer action rule, and the ghost cursor |
Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Capability cell vocabulary: bounded retain evidence
2+
3+
The [decision in #4056](https://github.com/callstack/agent-device/issues/4056#issuecomment-6499398178) retains the compile-checked duplicate declarations.
4+
The experiment did not reduce file or package coordination.
5+
This record supports the rejection of proposed [ADR 0028](../adr/0028-capability-family-cell-vocabulary.md).
6+
It does not establish that a whole capability addition was replayed.
7+
8+
## Source identity and comparison
9+
10+
The audit examined the last 200 overall commits at `144bd59890277fd4717995588ad817597c9d6552` (2026-10-17 through 2026-10-29).
11+
The disposable experiment used `be22676ace3f6a11d23af23a45c588a474e514be`.
12+
`platform-runtime-unavailable.ts` is identical at both source commits.
13+
14+
The prototype changed only that module's input type, local table and comment.
15+
It replaced 34 authored input properties and the compile-exhaustive key table with one table containing `required` or `optional` values.
16+
Two key-remapped mapped types derived the input contract.
17+
Patch inspection confirmed the same 34 keys in order: 26 required and eight optional.
18+
The runtime functions, fact projection, lifecycle authority and existing optional-cell `network` fallback were untouched.
19+
20+
A controlled comparison removed and reintroduced only the `systemButton` cell vocabulary.
21+
The intermediate pre-addition fixtures were incomplete measurement inputs, not release baselines.
22+
23+
| Scope | Existing | Inverted prototype |
24+
| --- | --- | --- |
25+
| Cell vocabulary re-addition | Two declarations; one file, one package | One row; one file, one package |
26+
| Adoption diff | Baseline | 49 added, 77 deleted lines; net −28 in one file |
27+
| Discovered eager entries | 427 | 427, with identical members, counts and weights |
28+
29+
The prototype removed one authored declaration and saved zero files or packages for this cell.
30+
It also removed the `settings` contract comment without relocation.
31+
The explicit owner-facing input shape became an intersection of mapped types.
32+
The table's required/optional values were not read at runtime.
33+
These costs do not justify adoption without a coordination benefit.
34+
35+
## Historical context
36+
37+
The following whole-commit counts include tests, documentation and backend changes.
38+
They are not measurements of the local vocabulary substitution.
39+
40+
| Commit | Scope | Whole-commit files / packages | Unavailable-cell change |
41+
| --- | --- | --- | --- |
42+
| `c41dc3a6e33c5ef65d36ea5c0685571a35412e9d` | Hardware button; inside the audited window | 65 / 10 | None; used `systemButton` |
43+
| `fc596209325dbf1175def58263f4554def91fa00` | Action Button; before family consolidation and outside the window | 76 / 12 | Two vocabulary declarations in one file |
44+
| `62a1ff1235` | Telephony; outside the window | 64 / 13 | Two vocabulary lines in one file |
45+
| `e8da1e10d6` | Fold; outside the window | 84 / 11 | Two vocabulary lines in one file |
46+
47+
The helper changed once in the audited window, in `f6fc99fbc9`, for an `unlock` projection.
48+
There were no cell-key additions in that window.
49+
A per-cell fact projection remains necessary after the proposed inversion.
50+
Owner availability facts and the other operation declarations also remain necessary under ADR 0019.
51+
The historical fan-out does not show that the duplicate key list caused the cross-package edits.
52+
53+
## Checks and limits
54+
55+
The disposable checkout had its own frozen install and baseline build.
56+
Before and after the prototype, `pnpm typecheck` and the two existing unavailable-facts smoke tests passed.
57+
The compile probe checked mutual assignability against a copied baseline type.
58+
It was not mutation-tested.
59+
Mutual assignability does not prove optional-key membership; the separate patch comparison supplied that observation.
60+
The two runtime tests exercise a few facts and do not prove backend behavior.
61+
62+
All 427 entry ids had identical closure membership, counts and module-scope weight before and after.
63+
Total weight was 124,989 in each arm.
64+
The helper appeared only in its own entry (28 modules, weight 460) and root platform runtime (41 modules, weight 648).
65+
The named-baseline growth comparison had no findings.
66+
This result is expected for a substitution with no added import, module or top-level statement.
67+
It supplies loading evidence, not an ergonomic benefit.
68+
69+
`pnpm check:layering` passed on the prototype.
70+
The eager-closure and closure-growth suites passed 872 tests.
71+
Their actual gate merge base was `144bd59890277fd4717995588ad817597c9d6552`; the explicit before/after comparison used `be22676ace3f6a11d23af23a45c588a474e514be`.
72+
Build and declaration emission were not rerun after the prototype.
73+
Lint, format, Fallow and affected validation were not run on it.
74+
The prototype was removed with its disposable checkout; the reviewed source stayed clean.
75+
76+
This is a bounded cell-level surrogate.
77+
ADR 0028's literal next-capability-family experiment was not performed.
78+
No whole-feature after-state, backend behavior change, eight-package saving or coordination gain is claimed.
79+
The proposal is rejected as a solution to the measured fan-out.
80+
A different vocabulary design needs its own representative evidence.

0 commit comments

Comments
 (0)