refactor(contracts): design spike — cut ADR-0019 declaration fan-out without weakening exact-owner facts (#1739)

[thymikee]

Outcome

A recommendation, with a worked example on one pending Wave 5 descriptor, for reducing the
per-unit declaration fan-out that #1739 identifies as its own parallelism constraint — without
weakening exact-owner classification.

Deliberately scoped as a spike, not a repo-wide change.

The measured problem

Co-change analysis of the last 200 commits on main (2026-08-10 → 2026-08-23, HEAD d1fc80f):

• src/core/command-descriptor/registry.ts changed in 26 commits; in 16 of those 26 it moved
  together with each of platform-{apple,android,web,harmonyos}/src/runtime.ts, and 15/26 with
  scripts/layering/runtime-command-cutover-table.ts.
• Ten commits touch all six platform-*/src/runtime.ts in lockstep.
• 15 of the 17 commits touching packages/contracts/src/platform-runtime-operations.ts touch
  four or more runtime owners.

The shape of one unit, measured on #1925 (focus — a single operation, focusPoint):

The change	focus-runtime.ts
Forced: contracts	platform-runtime-operations.ts, platform-runtime-unavailable.ts, facades/platform.ts
Forced: 8 runtime owners	platform-{apple,android,web,harmonyos,linux,vega}, provider-{limrun,webdriver}
Forced: gates & fixtures	runtime-command-cutover-table.ts, registry.ts, capabilities.ts, parity.test.ts, + 5 shared fixtures

40 files, 855 insertions. Comparable: #1935 (type) 64 files, #1877 (get) 75 files. With 13 Wave 5
interaction descriptors, 9 Wave 6 named units and 8 residue still ahead, that is roughly 30 more
repetitions.

This is the measured basis for #1739's own scheduling constraint: "every unit touches registry.ts,
runtime-command-cutover-table.ts, contracts/platform-runtime-operations.ts and each
platform-*/src/runtime.ts, so two in flight collide on the same four files."

Constraint the design must preserve

An earlier version of this analysis proposed defaulting the newer interaction cells (focus,
typeText, elementText) through freezeUnavailableFacts' existing orNetwork path. That is
wrong and this issue exists partly to record why, so it is not re-proposed:

• docs/agents/adr-0019-unit.md requires each platform package to report exact-owner facts, with
  provider ownership failing closed — missing behavior never falls through to a local owner.
• packages/contracts/src/platform-runtime-unavailable.ts records (refactor: tighten viewport runtime facts #1873) that capture cells are
  stated by their owner and never inherited from the transport gap.

Defaulting an interaction cell to network would erase a real distinction — provider is reachable,
but this interaction is unsupported — and let a missing classification read as a transport failure.
The required/optional split is the policy, not an oversight.

So the goal is narrow:

Reduce the declaration fan-out without weakening exact-owner classification.

Directions worth evaluating

None of these are proven by the churn evidence; the spike is to choose among them.

• operation-family builders;
• exhaustive composed records;
• generated owner skeletons.

Fold in: the fixture fan-out

Five modules each restate the runtime operation surface and move with the same units:

Fixture	Lines	Commits
src/daemon/handlers/__tests__/session-command-harness.ts	283	18
src/daemon/handlers/__tests__/session-capabilities.fixtures.ts	162	12
src/daemon/__tests__/test-device-runtime-gateway.ts	190	12
src/daemon/handlers/__tests__/interaction-get-runtime-fixture.ts	176	—
src/__tests__/test-utils/runtime-operation-facts.ts	53	—

Derive construction, not expectations. A fixture catalog generated wholesale from the production
catalog is tautological: if production omits an operation and the expected fixtures inherit that
omission, both sides stay green. The safe shape is to centralize valid runtime-fact construction,
keep parity and denominator assertions independent of it, keep focused owner-specific overrides, and
ensure an omission still fails compilation or a completeness gate.

Deliverable

A recommendation plus a worked example on one pending Wave 5 descriptor — enough for #1739 to decide
whether to adopt it before the remaining interaction units, not a landed repo-wide refactor.

Related

• refactor(daemon): platform-free daemon — broader migration waves (successor to #1696) #1739 (canonical tracker), test(structure): per-package eager-closure budgets — the ADR-0019 loading-shape probe (#1739) #1960 (per-package eager-closure budgets), refactor: tighten viewport runtime facts #1873 (capture cells stated
  by their owner).

[thymikee]

#1987 (Wave 5 touch cluster — click, press, fill, longpress, hover) is better evidence than anything this issue was filed on, and it weakens the framing above. Correcting it rather than leaving the stale version to drive a spike.

The spine is fixed-cost per PR, not per command

Composition of #1987's 83 files / 4,769 changed lines:

Bucket	Files	Lines	Share
Declaration spine (the 6 anchors)	6	217	4.6%
Runtime owners (runtime.ts × 6)	6	128	2.7%
Contracts (other)	7	452	9.5%
Owner impl (other)	3	40	0.8%
Gates / scripts	1	1	—
Tests & fixtures	40	2,155	45.2%
src implementation	15	1,742	36.5%
Other	5	34	0.7%

All six anchors were touched, exactly as this issue predicted —
platform-runtime-operations.ts, platform-runtime-unavailable.ts, facades/platform.ts,
registry.ts, capabilities.ts, runtime-command-cutover-table.ts — plus all six runtime owners.

But five commands cost the same six-anchor edit that one command cost. #1925 (focus, one
operation) touched the same six. So spine + owners here is 12 files and 345 lines — 7% of the
diff — against 82% for tests and real implementation.

That means the original framing in this issue is wrong in one respect: I measured file counts per
unit (40 / 64 / 75) and inferred that the declaration surface was the dominant tax. In line terms it
is not, and batching a cluster amortizes it — #1987 already demonstrates the mitigation without any
new machinery.

What survives

The contention claim, which is the one #1739 actually makes:

every unit touches registry.ts, runtime-command-cutover-table.ts,
contracts/platform-runtime-operations.ts and each platform-*/src/runtime.ts, so two in flight
collide on the same four files.

That is a concurrency constraint, not a volume one, and #1987 does not remove it — it sidesteps it
by making the unit bigger. Two clusters in flight would still collide on the same six anchors.

So the question worth spiking narrows to: can two migration units proceed concurrently without
colliding on the declaration spine, while keeping exact-owner facts and fail-closed provider
ownership? Reducing per-unit ceremony is no longer the goal; the ceremony is already small and
amortizable. If the answer is "batch by cluster and accept serialization", that is a legitimate
answer and this issue should close as resolved-by-practice.

Denominator, re-derived

On main at 7aaa559, evaluated from the registry rather than a hand list: 32 legacy, 26
device-runtime, 17 none, 1 inventory — unchanged from #1739's last checkpoint, because #1987
is still open. It drops to 27 legacy when #1987 merges.

Wave 5 is not complete at that point: its canonical list is 15 descriptors, focus (#1925) and
type (#1935) landed, #1987 takes five, leaving eight — gesture, scroll, swipe, back,
home, orientation, tv-remote, keyboard.

The fixture bucket (45% of this diff) remains the largest single cost and is the part of this issue
I would still keep, with the caveat already recorded above: derive construction, not expectations.

---

Generated by Claude Code

[thymikee]

Status re-derived at 957a672 (2026-08-24). Everything below the previous comment's 7aaa559 checkpoint moved today, and the movement answers the narrowed question.

Wave 5 is complete

All three remaining clusters merged after the previous comment was posted:

PR	Descriptors	Merged (UTC)
#1955	back home orientation tv-remote keyboard	08:40
#1987	click press fill longpress hover	12:54
#1952	gesture swipe scroll	13:54

With focus (#1925) and type (#1935), all 15 Wave 5 descriptors are device-runtime. The registry at 957a672 evaluates to 19 legacy, 39 device-runtime, 17 none, 1 inventory (was 32/26/17/1 at the last checkpoint). The 19: perf+trace (Wave 2, blocked on #1370), the 9 Wave 6 named units, and the 8 residue descriptors.

Consequence for the deliverable as written: "a worked example on one pending Wave 5 descriptor" is no longer possible — there are none. Any worked example would now target a Wave 6 named unit.

The narrowed question was answered by practice

The open question — can two migration units proceed concurrently without colliding on the declaration spine? — got a live trial: #1955, #1987, and #1952 were in flight simultaneously (created 08-21/08-22), every one touched the same anchor set, and they merged within five hours by serializing at the end. #1952's base is #1987's merge commit; its PR records the rebase and a full affected-gate re-run on the rebuilt head. Cost per unit: one rebase plus revalidation. No new machinery.

Spine share stayed the minor cost, confirming #1987's accounting across all three:

PR	Spine + owners (lines)	Total diff (lines)	Share
#1987	345	4,769	7%
#1955	872	7,853	11%
#1952	729	4,373	17%

Two anchors are also shrinking on their own: src/core/capabilities.ts lost 98 net lines across the three merges as buckets deleted, and #1990 retired the facade closure test for a lint rule plus budget rows.

So the answer is the one this issue said would be legitimate: batch by cluster and accept serialization. It was exercised three-wide in one day without weakening exact-owner facts, and per-unit ceremony needed no reduction. On the declaration-spine half, this issue is resolved by practice.

What survives: the fixture fan-out, now measurably worse

All five modules churned in each of the three merges and grew again in one day:

Fixture	Was	Now
session-command-harness.ts	283	308
session-capabilities.fixtures.ts	162	187
test-device-runtime-gateway.ts	190	248
interaction-get-runtime-fixture.ts	176	286
runtime-operation-facts.ts	53	78

864 → 1,107 lines (+28%), and the test/fixture bucket was already 45% of #1987's diff. This is the one part of the issue with remaining value, unchanged in shape: derive construction, not expectations — centralize valid runtime-fact construction, keep parity and denominator assertions independent, keep an omission failing a completeness gate.

Recommendation

Close the spike's original question as resolved-by-practice, and either (a) close this issue outright, folding the fixture-construction item into #1739's Wave 6 planning, or (b) retitle/rescope it to the fixture-construction consolidation alone, with the worked example on the first Wave 6 named unit. The declaration fan-out no longer needs a design.

---

Generated by Claude Code

[thymikee]

Closing as resolved-by-practice per the status above: Wave 5 completed with three cluster units in flight concurrently, serialized only at merge, and the declaration spine measured a minor, amortized share of each diff (7–17%) with two anchors already shrinking on their own. No fan-out design is needed.

The one surviving item — centralizing runtime-fact construction for the five fixture modules (derive construction, not expectations; keep parity/denominator assertions independent; an omission must still fail a gate) — is recorded on #1739 as Wave 6 planning input rather than kept open here.

---

Generated by Claude Code