Skip to content

Commit ee47b59

Browse files
committed
refactor(contracts): one file per command family, one name per request
Addresses review on #1435. contracts/client-api.ts was 1,064 LOC and grouped session, app, interaction, replay, observability and recording contracts together, so it answered no one question and crossed the >1,000-LOC architecture-debt tripwire in AGENTS.md:124. Split it into 14 domain-family files by the command families that already exist (client-connection, client-device-view, client-session, client-lease, client-app, client-capture, client-target, client-gesture, client-selector-read, client-replay, client-observability, client-settings, client-system, client-request); the four Metro client shapes went into the existing contracts/metro.ts so one file answers the Metro question. Largest resulting file is 137 LOC. client/client-types.ts re-exports one wildcard per family, so the published import path is unchanged. Published surface verified unchanged against main two ways: the exported-name set of all 11 published entrypoints is identical (70 names), and every declaration in the built index.d.ts is byte-identical after normalization -- 0 names added, 0 shapes changed. index.d.ts got smaller (1,726 -> 1,682 lines): 10 declarations main duplicated into it now resolve through a shared chunk. Also, from re-examining the two findings the review flagged as blind spots: - CommandRequest was a third name for "a request" that no consumer needed. Every core/command-descriptor/ use read only command/positionals/flags, in two spellings (the full type and a Pick of it). Replaced by contracts/dispatched-command.ts DispatchedCommand -- those three fields and nothing else, with command/positionals Picked from the wire type so they cannot drift. daemon/types.ts DaemonRequest now extends the wire shape directly. Two request shapes again, at two ranks. - The 7 remaining R6 inversions each get a mechanical reason rather than an appeal to an ADR: the 4 AgentDeviceClient edges are a real zone-level cycle (client-types.ts imports ProjectedNavigationCommandClient from commands/), and no narrower port exists (26 call sites across 13 namespaces); the 2 DaemonCommandDescriptor edges are unavoidable because that shape is stated in terms of the server-private DaemonRequest; the 1 DaemonCommandRoute edge is unavoidable because the type is computed from the daemon's handler table. Cleanups found on the way: three doc comments this branch had orphaned from their declarations (SettleCommandOptions, RecordControlOptions, ReloadMetroResult -- the last had drifted onto an unrelated type it misdescribed) are reattached; intra-contracts imports normalized from '../contracts/x.ts' to './x.ts', which is what the duplicate-import lint caught; and stale references to the deleted file removed from the docs. Co-Authored-By: Claude Opus 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Bfu8HofkhybiAm5LECfqur
1 parent fffd3cd commit ee47b59

68 files changed

Lines changed: 1436 additions & 1303 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/dependency-graph-findings.md‎

Lines changed: 50 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,7 @@ type-only inversions, R7 pins SessionState field ownership, and the shared selec
8383
| Keystone moved to `contracts/` | Unblocked |
8484
|---|---|
8585
| `DaemonBatchStep` (was `core/batch.ts`, typed via `DaemonRequest['runtime']`) | `CommandFlags` |
86-
| `CommandFlags` (was `core/dispatch-context.ts`) | `SessionAction`, `CommandRequest` |
86+
| `CommandFlags` (was `core/dispatch-context.ts`) | `SessionAction`, `DispatchedCommand` |
8787
| `TargetAnnotationV1` shape (was `replay/target-identity.ts`) | `SessionAction` |
8888
| `ScrollInputDirection`, Metro result payloads | `ScrollOptions`, `MetroPrepareResult`/`MetroReloadResult` |
8989

@@ -93,23 +93,46 @@ was written `DaemonRequest['runtime']`, pulling the whole daemon request type in
9393
declaration pinning ~80 public API shapes above it. Neither looked like a keystone from the graph;
9494
both were found by asking "what does the target itself import, and what rank is that?"
9595

96-
`DaemonRequest` also split into the three shapes it had been conflating:
97-
98-
- `kernel/contracts.ts` — the **wire** shape, `flags?: Record<string, unknown>`, because a process
99-
boundary cannot enforce a flag vocabulary;
100-
- `contracts/command-request.ts` `CommandRequest` — the wire shape with `flags` typed. What a command
101-
surface needs to reason about a request without knowing which server runs it;
102-
- `daemon/types.ts` `DaemonRequest` — that plus `internal?: DaemonRequestInternal`, carrying
103-
`SessionState` callbacks and the admitted lease. Server-private, and why it cannot move down.
104-
105-
`core/command-descriptor/` had been importing the third to read `command`, `positionals` and `flags`.
106-
107-
**The remaining 7 are positions, not debt.** 4 are `AgentDeviceClient` used as an opaque handle;
108-
the facade is built from `commands/`'s own `NAVIGATION_COMMAND_PROJECTIONS`, so this is a genuine
109-
zone-level cycle and breaking it means deciding where that registry belongs. 3 are the ADR 0003
110-
daemon descriptor, whose `DaemonCommandRoute` is `keyof typeof DAEMON_ROUTE_HANDLERS` — derived from
111-
what the server implements, so moving it down would mean re-declaring route names plus a gate to
112-
prove the handler map still covers them. Both are argued at `TYPE_INVERSION_BASELINE`.
96+
`DaemonRequest` had been conflating a request with the command that request dispatches. There are
97+
still only two request shapes — and that is the point, because a third would be a third name for the
98+
same thing:
99+
100+
- `kernel/contracts.ts` `DaemonRequest` — the **wire** shape, `flags?: Record<string, unknown>`,
101+
because a process boundary cannot enforce a flag vocabulary;
102+
- `daemon/types.ts` `DaemonRequest` — the wire shape with `token`/`session` required, `flags`
103+
narrowed to `CommandFlags`, and `internal?: DaemonRequestInternal` carrying `SessionState`
104+
callbacks and the admitted lease. Server-private, and why it cannot move down.
105+
106+
`core/command-descriptor/` had been importing the second to read `command`, `positionals` and
107+
`flags` — reaching up two ranks for three fields. It now takes
108+
`contracts/dispatched-command.ts` `DispatchedCommand`, which is those three fields and nothing else,
109+
with `command`/`positionals` `Pick`ed from the wire so they cannot drift from it. Every descriptor
110+
resolver already read only those three, in two spellings (the full type and a `Pick` of it); one
111+
narrow name replaced both.
112+
113+
**The remaining 7 are positions, not debt** — each for a mechanical reason, not an appeal to an ADR:
114+
115+
- **4 × `AgentDeviceClient`** (`commands/command-contract.ts`, `commands/command-surface.ts`,
116+
`commands/family/types.ts`, `mcp/command-tools.ts`). The facade cannot move below `commands/`
117+
because it is *built from* the command surface: `client/client-types.ts` imports
118+
`ProjectedNavigationCommandClient` from `commands/system/navigation-projection.ts`. That is a real
119+
zone-level type cycle, and breaking it means deciding where the projection registry belongs — a
120+
design call, not a file move. A narrower port does not exist either: 4 files *name* the facade,
121+
but 26 call sites use methods across 13 of its namespaces, so any port would re-declare it.
122+
- **2 × `DaemonCommandDescriptor`** (`core/command-descriptor/derive.ts`, `.../types.ts`). It is
123+
*stated in terms of* the server-private `daemon/types.ts` `DaemonRequest` —
124+
`refFrameEffect?: (req: DaemonRequest) => RefFrameEffect`,
125+
`allowSessionlessDefaultDevice?: (req: DaemonRequest) => boolean` — so it cannot be declared below
126+
the daemon. Having `core/` re-declare a parallel 13-field shape instead would trade one erased
127+
edge for a second source of truth.
128+
- **1 × `DaemonCommandRoute`** (`commands/command-explain.ts`). It is
129+
`keyof typeof DAEMON_ROUTE_HANDLERS` — *computed from* the daemon's handler table, so it cannot
130+
exist below that table. `command-explain.ts` uses it to key an exhaustive
131+
`Record<DaemonCommandRoute, string>` of owner files; a hand-written union in `contracts/` would
132+
drop exactly that exhaustiveness.
133+
134+
All three are argued at `TYPE_INVERSION_BASELINE` in `scripts/layering/check.ts`, next to the
135+
numbers they explain.
113136

114137
## 0b. The biggest structural finding is not an inversion
115138

@@ -164,10 +187,15 @@ the one that was always the real question — whether `NAVIGATION_COMMAND_PROJEC
164187

165188
`TYPE_INVERSION_BASELINE` in `scripts/layering/check.ts` holds both, with the reasoning inline.
166189

167-
**28 + 1 edges → `client/client-types.ts`** — *done, mostly.* Now 5 edges. The vocabulary moved to
168-
`contracts/client-api.ts`, with `client/client-types.ts` keeping the `AgentDeviceClient` facade and
169-
re-exporting the rest through one wildcard, so the published `.d.ts` surface is byte-identical
170-
(verified by diffing the built `index.d.ts` name set against `main`: 216 names, no change).
190+
**28 + 1 edges → `client/client-types.ts`** — *done, mostly.* Now 5 edges. The vocabulary moved into
191+
the `contracts/client-*.ts` family files — one file per command/domain family, largest 137 LOC —
192+
with `client/client-types.ts` keeping the `AgentDeviceClient` facade and re-exporting the rest
193+
through one wildcard per family. The published surface is unchanged, verified two ways against
194+
`main`: the exported-name set of all 11 published entrypoints is identical (70 names), and every
195+
declaration in the built `index.d.ts` is byte-identical after normalization (0 names added, 0 shapes
196+
changed). `index.d.ts` in fact got *smaller* — 1,726 → 1,682 lines — because 10 declarations that
197+
`main` duplicated into it (the Metro option/result shapes, `ScrollInputDirection`) now resolve
198+
through a shared chunk once the vocabulary sits below both its consumers.
171199

172200
The mutual coupling this section already warned about is what set the floor. Eight shapes could NOT
173201
move down, because each is stated in terms of a HIGHER-ranked zone:

‎scripts/layering/check.ts‎

Lines changed: 15 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -206,16 +206,22 @@ function checkBackEdges(edges: readonly ResolvedImportEdge[]): Violation[] {
206206
// a design call, not a file move. R5 is zero here: nothing imports
207207
// the client at runtime, only its type.
208208
//
209-
// core/commands -> daemon-server (3) `DaemonCommandDescriptor` and `DaemonCommandRoute`.
210-
// `DaemonCommandRoute` is `keyof typeof DAEMON_ROUTE_HANDLERS` and
211-
// the descriptor resolves `refFrameEffect` against the daemon's own
212-
// request type, so the shape is derived from what the server
213-
// actually implements. Moving it down would mean re-declaring the
214-
// route names in contracts plus a gate to prove the handler map
215-
// still covers them: more coupling to remove a dependency. ADR
216-
// 0003/0008 own this boundary deliberately.
209+
// core -> daemon-server (2) `DaemonCommandDescriptor`, which is STATED IN TERMS OF the daemon's
210+
// own server-private `DaemonRequest` (`refFrameEffect`,
211+
// `allowSessionlessDefaultDevice`, `skipSessionlessProviderDevice`
212+
// are all `(req: DaemonRequest) => …`). It therefore cannot be
213+
// declared below the daemon, and having core/ re-declare a parallel
214+
// 13-field shape would trade one erased edge for a second source of
215+
// truth. Zones that only need to CLASSIFY a command take
216+
// `contracts/dispatched-command.ts` instead. ADR 0003/0008.
217217
//
218-
// The counts may only go DOWN. Fixing edges without lowering the number fails too, so the baseline
218+
// commands -> daemon-server (1) `DaemonCommandRoute` = `keyof typeof DAEMON_ROUTE_HANDLERS`, so
219+
// it is COMPUTED FROM the daemon's handler table and cannot exist
220+
// below it. `commands/command-explain.ts` uses it to key an
221+
// exhaustive `Record<DaemonCommandRoute, string>` of owner files; a
222+
// hand-written union in contracts/ would drop that exhaustiveness.
223+
//
224+
// See docs/dependency-graph-findings.md §0 for the long form. The counts may only go DOWN. Fixing edges without lowering the number fails too, so the baseline
219225
// cannot quietly stop describing the tree.
220226
//
221227
// Exported so scripts/depgraph can assert its own graph build reproduces it — see the

‎src/__tests__/cli-client-commands.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ import type {
1313
MetroPrepareOptions,
1414
MetroReloadOptions,
1515
} from '../agent-device-client.ts';
16-
import type { SettingsUpdateOptions } from '../contracts/client-api.ts';
16+
import type { SettingsUpdateOptions } from '../contracts/client-settings.ts';
1717
import { AppError } from '../kernel/errors.ts';
1818
import { resolveCliOptions } from '../cli/resolve-cli-options.ts';
1919

‎src/agent-device-client.ts‎

Lines changed: 19 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -34,31 +34,39 @@ import {
3434
import { readScreenshotResultData } from './utils/screenshot-result.ts';
3535
import { isRecord } from './utils/parsing.ts';
3636
import type {
37-
AgentDeviceClientConfig,
38-
AgentDeviceDaemonTransport,
3937
AppCloseOptions,
4038
AppDeployOptions,
41-
AppInstallOptions,
4239
AppInstallFromSourceOptions,
40+
AppInstallOptions,
4341
AppListOptions,
4442
AppOpenOptions,
43+
MaterializationReleaseOptions,
44+
} from './contracts/client-app.ts';
45+
import type {
4546
CaptureScreenshotOptions,
4647
CaptureScreenshotResult,
4748
CaptureSnapshotOptions,
4849
CaptureSnapshotResult,
49-
InternalRequestOptions,
50-
Lease,
51-
MaterializationReleaseOptions,
52-
MetroPrepareOptions,
53-
PanOptions,
50+
} from './contracts/client-capture.ts';
51+
import type {
52+
AgentDeviceClientConfig,
53+
AgentDeviceDaemonTransport,
54+
} from './contracts/client-connection.ts';
55+
import type {
5456
FlingOptions,
55-
SwipeGestureOptions,
57+
PanOptions,
5658
PinchOptions,
5759
RotateGestureOptions,
60+
SwipeGestureOptions,
61+
TransformGestureOptions,
62+
} from './contracts/client-gesture.ts';
63+
import type { Lease } from './contracts/client-lease.ts';
64+
import type { InternalRequestOptions } from './contracts/client-request.ts';
65+
import type {
5866
SessionSaveScriptOptions,
5967
SessionSaveScriptResult,
60-
TransformGestureOptions,
61-
} from './contracts/client-api.ts';
68+
} from './contracts/client-session.ts';
69+
import type { MetroPrepareOptions } from './contracts/metro.ts';
6270
import type {
6371
AgentDeviceCommandClient,
6472
AgentDeviceClient,

‎src/cli.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ import { readVersion } from './utils/version.ts';
77
import { pathToFileURL } from 'node:url';
88
import { sendToDaemon } from './daemon/client/daemon-client.ts';
99
import fs from 'node:fs';
10-
import type { BatchStep } from './contracts/client-api.ts';
10+
import type { BatchStep } from './contracts/client-replay.ts';
1111
import type { ReplayTestReporterRuntime } from './replay/test/reporting.ts';
1212
import {
1313
createAgentDeviceClient,

‎src/cli/batch-steps.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import type { BatchStep } from '../contracts/client-api.ts';
1+
import type { BatchStep } from '../contracts/client-replay.ts';
22
import { type SessionRuntimeHints } from '../kernel/contracts.ts';
33
import { parseBatchStepRuntime } from '../contracts/batch-contract.ts';
44
import { readInputFromCli } from '../commands/cli-grammar.ts';

‎src/cli/commands/connection-runtime.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ import {
2121
type RemoteConnectionRequestMetadata,
2222
} from '../../remote/remote-connection-state.ts';
2323
import { profileToCliFlags } from '../remote-config-flags.ts';
24-
import type { BatchStep } from '../../contracts/client-api.ts';
24+
import type { BatchStep } from '../../contracts/client-replay.ts';
2525
import { AppError } from '../../kernel/errors.ts';
2626
import type { LeaseBackend, SessionRuntimeHints } from '../../kernel/contracts.ts';
2727
import type { CliFlags } from '../../contracts/cli-flags.ts';

‎src/client/client-normalizers.ts‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,15 +11,17 @@ import {
1111
} from '../kernel/device.ts';
1212
import { leaseScopeFromOptions, leaseScopeToRequestMeta } from '../core/lease-scope.ts';
1313
import type {
14-
AgentDeviceDevice,
15-
AgentDeviceSession,
16-
AgentDeviceSessionDevice,
1714
AppDeployResult,
1815
AppInstallFromSourceResult,
19-
InternalRequestOptions,
2016
MaterializationReleaseResult,
17+
} from '../contracts/client-app.ts';
18+
import type {
19+
AgentDeviceDevice,
20+
AgentDeviceSession,
21+
AgentDeviceSessionDevice,
2122
StartupPerfSample,
22-
} from '../contracts/client-api.ts';
23+
} from '../contracts/client-device-view.ts';
24+
import type { InternalRequestOptions } from '../contracts/client-request.ts';
2325
import type { TargetShutdownResult } from '../contracts/target-shutdown-contract.ts';
2426
import {
2527
asRecord,

0 commit comments

Comments
 (0)