refactor(contracts): declare shared vocabulary below its consumers, ratchet what remains

[thymikee]

Scope disclosure

This is an intentional architecture-wide type-boundary and layering refactor spanning 93 files.
The breadth is the point, not an accident of tooling: a shared shape declared one rank too high pins
every shape stated in terms of it, so fixing one keystone necessarily touches every consumer that
named it. Nothing here changes runtime behaviour — the changes are declaration moves, import
rewrites, and new gate rules. Reviewing it as a whole-tree boundary change rather than file-by-file
is the intended reading; §"Four keystones" and §"One file per command family" are where the actual
decisions are.

The published package surface is unchanged, verified two independent ways against main (see
Validation).

Summary

Type-only spine inversions (R6): 61 → 7, and every one of the 7 that remains is a deliberate
architectural position with a mechanical reason written at the baseline — not an appeal to an ADR
and not leftover debt. Adds R9, a growth-only ratchet on the largest type-level import cycle —
the one structural problem R6 never measured.

Rebased onto f19864e (#1410). The merged two-sources check works across the merge: the depgraph
report now computes 7 and TYPE_INVERSION_BASELINE is 7, so scripts/depgraph/model.test.ts passes
without special handling.

	before	after
type-only spine inversions	61 across 6 pairs	7 across 4
replay → daemon-server	6	0
largest type-level cycle	107 (main)	102, now ratcheted
largest contracts file	1,064 LOC	137

Four keystones, each pinning a much larger set

The pattern repeated, and neither of the first two looked like a keystone from the graph. Both were
found by asking what does the target itself import, and what rank is that?

Moved to contracts/	Unblocked
DaemonBatchStep — its runtime field was written DaemonRequest['runtime'], dragging the whole daemon request type in to say SessionRuntimeHints, the same type three zones lower	CommandFlags
CommandFlags — one rank-2 declaration pinning ~80 public API shapes above it	SessionAction, DispatchedCommand
TargetAnnotationV1 shape — ADR 0012 target evidence, written by 8 daemon modules, read by commands/; the parsing and classification logic stays in replay/	SessionAction
ScrollInputDirection, Metro prepare/reload payloads	ScrollOptions, MetroPrepareResult/MetroReloadResult

SessionAction freed replay/ entirely — 6 inversions to 0. The daemon still owns the recording;
only the shape moved.

One file per command family

(Added in response to review.) The vocabulary's first landing place was a single
contracts/client-api.ts at 1,064 LOC, which grouped session, app, interaction, replay,
observability and recording contracts together. That answered no one question and crossed the
>1,000 LOC is architecture debt tripwire at AGENTS.md:124 — it relocated the whole-file context
cost rather than removing it.

Split by the command/domain families that already exist in the tree, one file each:

file	LOC	answers
client-app.ts	137	app install, deploy, open, close, inventory
client-gesture.ts	132	the gesture and text-entry commands
client-request.ts	110	the internal request envelope a client call projects into
client-system.ts	98	wait, alert, keyboard, clipboard, doctor, viewport
client-connection.ts	94	how a client reaches a daemon and selects a device
client-device-view.ts	84	what a device and an open session look like to a client
client-capture.ts	79	snapshot, screenshot and diff capture
client-replay.ts	77	replay and batch execution
client-settings.ts	65	device settings and permission grants
client-observability.ts	62	perf, logs, events, network, audio, recording
client-selector-read.ts	55	the read commands that resolve a selector (get / is / find)
client-lease.ts	53	device lease allocation and cloud artifacts
client-session.ts	36	session lifecycle and script publication
client-target.ts	35	how a client names the element an interaction acts on

The four Metro client shapes went into the existing contracts/metro.ts rather than a 15th file,
so one file answers the Metro question. client/client-types.ts re-exports one wildcard per family,
so every consumer's import path is unchanged.

DispatchedCommand — two request shapes, not three

An earlier revision of this PR introduced contracts/command-request.ts CommandRequest, and I
flagged the third name for one concept as a real cost. Re-examining it, no consumer wanted a third
request: every core/command-descriptor/ use read only command, positionals and flags, in
two spellings (the full type, and Pick<CommandRequest, 'command' | 'positionals' | 'flags'> — both
in the same file). So the honest contract is not a request at all:

• kernel/contracts.ts DaemonRequest — the wire shape, flags?: Record<string, unknown>,
  because a process boundary cannot enforce a flag vocabulary.
• daemon/types.ts DaemonRequest — the wire shape with token/session required, flags narrowed
  to CommandFlags, and internal?: DaemonRequestInternal carrying SessionState callbacks and the
  admitted lease. Server-private, and why it cannot move down.
• contracts/dispatched-command.ts DispatchedCommand — not a request: the command a request
  dispatches. Those three fields and nothing else, with command/positionals Picked from the wire
  type so they cannot drift from it.

core/command-descriptor/ had been importing the daemon's version to read three fields — reaching up
two ranks, and depending on the server's private extension to get a command name. One narrow name
replaced both spellings and the now-redundant RecordingEffectRequest alias.

The 7 remaining inversions, argued mechanically

Restated from "position, trust the ADR" to a reason you can check:

• 4 × AgentDeviceClient — client/client-types.ts imports ProjectedNavigationCommandClient
  from commands/system/navigation-projection.ts, so this is a real zone-level type cycle, not a
  misplaced declaration. Breaking it means deciding where the projection registry belongs. A narrower
  port doesn't exist either — 4 files name the facade, but 26 call sites use methods across 13 of
  its namespaces, so a port spanning them is the facade.
• 2 × DaemonCommandDescriptor — that shape is stated in terms of the server-private
  daemon/types.ts DaemonRequest (refFrameEffect, allowSessionlessDefaultDevice,
  skipSessionlessProviderDevice are all (req: DaemonRequest) => …), so it cannot be declared below
  the daemon. Having core/ re-declare a parallel 13-field shape would trade one erased edge for a
  second source of truth.
• 1 × DaemonCommandRoute — it is keyof typeof DAEMON_ROUTE_HANDLERS, computed from the
  daemon's handler table, so it cannot exist below that table. commands/command-explain.ts uses it
  to key an exhaustive Record<DaemonCommandRoute, string> of owner files; a hand-written union in
  contracts/ would drop exactly that exhaustiveness.

What's left underneath is the real question: does NAVIGATION_COMMAND_PROJECTIONS belong in
commands/? That's a design decision about the command surface, deliberately not pre-decided here.

R9 — type-cycle growth

Cycle size by edge kind on this branch:

edges considered	largest SCC
value only	1 — no cycles, which is what R4 enforces
value + type-only	102
value + dynamic	1

At runtime the module graph is a clean DAG. The 102-file cluster is purely type-level: no file in it
has a self-contained slice, which is the largest single obstacle to reading a subsystem in isolation —
and a real cost for agents loading context. Growth-only on purpose: reducing 102 is a refactor, not a
file move, so a hard equality would turn every unrelated improvement into a baseline edit. A shrunk
tree is reported in the success line rather than failing.

One thing worth knowing about how this landed. An earlier revision baselined 87, measured against
the older main. After rebasing, the real figure was 102 and R9 fired on its own stale baseline. That
looked like a regression and wasn't: attribution showed main at 107 and this branch reducing it to
102. The rule caught a genuine number change on its first outing — I just had to check which side
moved before reacting. Baseline is now set at what this branch achieves.

The refactor itself is deliberately not attempted; hubs are runtime-contract.ts,
commands/runtime-types.ts, backend.ts, commands/runtime-common.ts.

Validation

pnpm check green — lint, typecheck, R1–R9, depgraph:test, production exports, MCP metadata, build,
bundle owner files, Fallow, 4535 unit tests.

Published surface unchanged, verified two independent ways against main:

1. The exported-name set of all 11 published entrypoints is identical — 70 names, no additions
   and no removals. (This is the right check; counting declarations in the built .d.ts is a weaker
   proxy because it also counts inlined internals.)
2. Every declaration in the built index.d.ts is identical after whitespace normalization — 0 names
   added, 0 shapes changed (compared by parsing both with oxc-parser, not by grep).

index.d.ts in fact got smaller — 1,726 → 1,682 lines — because 10 declarations main
duplicated into it (the Metro option/result shapes, ScrollInputDirection) now resolve through a
shared chunk once the vocabulary sits below both its consumers. Five of those 10 were unreferenced on
main: dead weight in the shipped types.

Verified by injection rather than assertion, each reverted after:

• R9 rejects a single type-only import that closes a loop (102 → 108).
• The first attempt at the vocabulary move — putting the whole file in contracts/ — took the gate
  from 42 to 48, which is how the floor was found. Recorded in
  docs/dependency-graph-findings.md so the next person doesn't repeat it.

Three doc comments this branch had orphaned from their declarations are reattached — the
ReloadMetroResult one had drifted onto an unrelated type it actively misdescribed. Found by scanning
every branch-touched file for comment blocks not followed by a declaration, which is worth doing after
any move of this size.

No device evidence. These are declaration moves and types are erased, but SessionAction and
DispatchedCommand sit on the replay and dispatch paths, so a live replay run is the residual risk
and I can't perform it here.

---

Generated by Claude Code

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.87 MB	1.87 MB	+3 B
JS gzip	598.4 kB	598.4 kB	-5 B
npm tarball	713.2 kB	714.0 kB	+778 B
npm unpacked	2.49 MB	2.50 MB	+2.2 kB

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	24.3 ms	25.1 ms	+0.8 ms
CLI --help	51.2 ms	51.5 ms	+0.4 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/recording-export-quality.js	0 B	-20 B
dist/src/runtime.js	+5 B	+8 B
dist/src/context.js	0 B	+6 B
dist/src/interaction.js	-1 B	+6 B
dist/src/internal/daemon.js	+2 B	-5 B

[thymikee]

Code semantics and exact-head CI are clean, but this is not ready yet: src/contracts/client-api.ts is 1,064 LOC and groups unrelated session, app, interaction, replay, observability, and recording contracts. That crosses the repo’s >1,000 LOC architecture-debt tripwire and merely relocates the old whole-file context cost. Split the vocabulary by existing command/domain families (with the public boundary re-exporting them), then add the required disclosure that this is an intentional 79-file architecture-wide type-boundary/layering refactor. No live replay run is a disclosed residual, not a blocker for erased type moves.

[thymikee]

Both addressed in 1c0f359, plus two things that came out of re-checking the blind spots.

The split. contracts/client-api.ts is gone, replaced by 14 files along the command/domain families that already exist in the tree. Largest is client-app.ts at 137 LOC; the full table is in the PR body. The four Metro client shapes went into the existing contracts/metro.ts rather than a 15th file, so one file answers the Metro question. client/client-types.ts re-exports one wildcard per family, so no consumer's import path changed.

The disclosure is now the first section of the PR body, stating plainly that this is an intentional architecture-wide type-boundary/layering refactor and why the breadth is inherent to the change rather than incidental. One correction to the number: it's 93 files, not 79 — the split itself touched 68, since every consumer that imported from client-api.ts needed its import rewritten.

Verification the split changed nothing published, done two independent ways against main (built both trees, compared):

1. The exported-name set of all 11 published entrypoints is identical — 70 names, no additions, no removals.
2. Every declaration in the built index.d.ts parsed with oxc-parser and compared: 0 names added, 0 shapes changed.

That second check turned up something worth knowing: index.d.ts got smaller, 1,726 → 1,682 lines. Ten declarations main duplicated into it (the Metro option/result shapes, ScrollInputDirection) now resolve through a shared chunk, because the vocabulary finally sits below both its consumers. Five of those ten were unreferenced on main — dead weight in the shipped types.

---

Two things from re-examining the findings I'd flagged as my own blind spots, since you didn't ask for either and both turned out to be real:

CommandRequest was the wrong shape, not just a third name. I'd flagged the third name for "a request" as a cost. Checking the consumers: every core/command-descriptor/ use read only command, positionals and flags — in two spellings, the full type and Pick<CommandRequest, 'command' | 'positionals' | 'flags'>, both in the same file. So the honest contract isn't a request at all. It's now contracts/dispatched-command.ts DispatchedCommand — those three fields, with command/positionals Picked from the wire type so they can't drift — and daemon/types.ts DaemonRequest extends the wire shape directly. Back to two request shapes at two ranks, one narrow name replacing both spellings plus a redundant alias.

The 7 remaining R6 inversions now have mechanical reasons rather than appeals to ADRs, which is what you should be able to check:

• 4 × AgentDeviceClient — client/client-types.ts imports ProjectedNavigationCommandClient from commands/system/navigation-projection.ts. That's a real zone-level type cycle, not a misplaced declaration.
• 2 × DaemonCommandDescriptor — the shape is stated in terms of the server-private DaemonRequest (refFrameEffect, allowSessionlessDefaultDevice, skipSessionlessProviderDevice are all (req: DaemonRequest) => …), so it cannot be declared below the daemon.
• 1 × DaemonCommandRoute — it's keyof typeof DAEMON_ROUTE_HANDLERS, computed from the daemon's handler table, so it can't exist below that table.

Also worth flagging as a defect of my own earlier commits on this branch: scanning every branch-touched file for comment blocks not followed by a declaration found three doc comments the moves had orphaned. The ReloadMetroResult one had drifted onto ProxyBridgeRequestOptions, an unrelated type it actively misdescribed. All three are reattached. That scan is worth running after any move of this size.

pnpm check green: lint, typecheck, R1–R9 (930 files, R6 = 7, R7 = 42 fields, R9 = 102), depgraph:test, production exports, MCP metadata, build, bundle owner files, Fallow, 4535 unit tests. No live replay run remains the disclosed residual.

---

Generated by Claude Code

[thymikee]

Rebased onto a798976 (current main) and re-ran. Everything passes except one test, and that one fails on main too — it is not from this PR:

FAIL scripts/__tests__/help-conformance-topic-coverage.test.ts
  > every help topic has a benchmark case or an explicit waiver
  + [ 'ios-system-ui' ]
  - []

Verified by checking out origin/main clean in a separate worktree and running that file alone — byte-identical failure. Two commits landed on main in an order that left the gate unsatisfied: #1411 added the topic-coverage gate, then #1395 added the ios-system-ui help topic without the bench case or waiver the gate requires.

I'm not fixing it here. The gate's contract is that a waiver names why the topic isn't benchmarked yet — that's a content judgement about #1395's iOS SpringBoard/widget guidance, and folding it into a 93-file type-boundary refactor would put an unrelated docs decision inside this diff. The fix is one line in scripts/__tests__/help-conformance-topic-coverage.test.ts, either a WAIVED_TOPICS entry or docs: [..., 'ios-system-ui'] on a case in scripts/help-conformance-cases.mjs.

Everything else on the current base is green: 4548 passed, 4 skipped, 1 failed (the inherited one). Layering guard OK across 931 source files — R6 = 7, R7 = 42 fields all classified, R8 clean, R9 = 102. Lint, typecheck, depgraph:test, production exports, MCP metadata, build and bundle-owner-files all pass.

I'll re-run once main is green.

---

Generated by Claude Code

[thymikee]

Re-review of the latest head is clean on code quality. The prior client-api.ts maintainability finding is resolved: the public vocabulary is split into focused command/domain files (largest 137 LOC), client-types.ts preserves the public re-export surface, and DispatchedCommand narrows core to the three fields it actually consumes while the daemon keeps its private request refinement. Exact-head Typecheck, Layering, Fallow, Integration, and platform smoke checks pass. I am not applying ready-for-human because Coverage is still failing on the inherited ios-system-ui help-conformance coverage gap; that failure is outside this PR’s delta but remains a ship blocker until the base fix lands/rebase makes the exact head green.

[thymikee]

Rebased onto e8b779c (#1392) and pushed as ee47b59. The ios-system-ui blocker is gone — and main fixed it the better way: #1392 added a real benchmark case (ios-system-ui-widget-flow, with matchers for the SpringBoard bind, coordinate-longpress edit mode, post-longpress snapshot refresh and return-to-app) rather than a WAIVED_TOPICS entry. That's the outcome I'd have wanted and specifically didn't want to pre-empt from inside this PR.

pnpm check fully green on the new base — 4554 passed, 4 skipped, 0 failed, 516 test files. Layering guard OK across 932 source files: R6 = 7, R8 clean, R9 = 102.

Two things worth calling out from the rebase, since #1392 touched files this PR also depends on:

R7 moved with it, correctly. #1392's session-close.ts refactor removed a SessionState field and updated scripts/layering/session-state.ts, so the gate now reports 41 fields rather than 42. This PR's exhaustive-parity assertion — the one added after your earlier review found the owner table covered only 27 of 42 fields with nothing checking it — agrees with main's updated table with no edit needed. That's the check doing its job across a merge rather than needing to be re-baselined.

daemon/types.ts was changed on both sides and the merge is clean. #1392 edited that file while this PR rewrote DaemonRequest to extend the wire shape directly. Rebase resolved without conflict and typecheck passes.

Re-verified every published-surface claim against the new base, not carried over from the old measurement:

• Exported-name set across all 11 published entrypoints: 70 names, zero diffs vs e8b779c.
• Declaration-level comparison of every entrypoint's built .d.ts (parsed with oxc-parser): zero shape differences.
• index.d.ts still 1,726 → 1,682 lines, the same 44-line reduction from the 10 declarations that no longer need duplicating.

Nothing left on my side. Coverage should be green on this head.

---

Generated by Claude Code

[thymikee]

Re-review at head ee47b59: clean readiness verdict. The rebase preserves the reviewed patches, the prior Coverage blocker is resolved, the PR is mergeable/CLEAN, and all 24 reported checks are successful, including Coverage, Integration Tests, Affected-check Selector, No test-only DI seams, Layering Guard, Fallow, typecheck, lint, and platform smokes. No code findings remain. Marked ready-for-human.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-07-27 15:23 UTC