Skip to content

Commit 3fdbfe0

Browse files
committed
refactor(contracts): declare the public API vocabulary below its consumers
The layering gate's largest remaining cluster was 28 type-only inversions from a single edge: `commands/` declaring itself in terms of `client/client-types.ts`. R2 forbids the reverse import, so a shape both surfaces need has to sit below both. The command/device vocabulary — connection config, the device and session views, and every per-command Options/Result — now lives in `contracts/client-api.ts`; `client/client-types.ts` keeps the `AgentDeviceClient` facade and re-exports the rest through one wildcard. R6 total: 42 -> 18. No new inversion in any pair. The published surface is unchanged, and that is verified rather than asserted: the built `index.d.ts` exports the same 216 type names as main, byte-identical. Eight shapes deliberately did NOT move, because each is stated in terms of a HIGHER-ranked zone: `ScrollOptions` (ScrollInputDirection, commands/), the four navigation Options plus `AgentDeviceCommandClient` (navigation-projection, commands/), and the two Metro result aliases (metro/). Declaring those in contracts/ would trade 28 commands->client edges for contracts->commands and contracts->metro ones — the foundation depending on the layers above it, worse in kind even though fewer in number. This is measured, not assumed: moving the whole file to contracts/ first took the gate from 42 to 48, which is how the floor was found. Two keystone moves made the other 84 movable: - `RemoteConnectionProfileFields` joined its sibling `CloudProviderProfileFields` in contracts/remote-config-fields.ts. It was the root of the base chain (AgentDeviceClientConfig -> AgentDeviceRequestOverrides -> DeviceCommandBaseOptions -> every per-command Options), so one rank-4 declaration was pinning ~80 shapes up with it. - `DaemonBatchStep` moved to contracts/batch-step.ts. Its `runtime` field was written `DaemonRequest['runtime']`, dragging the whole daemon request type in to say `SessionRuntimeHints` — the same type, three zones lower. `CompanionTunnelScope`/`MetroBridgeScope` also moved to contracts/, since the vocabulary needs the scope shape and it sat next to client-local env-var names. Six pass-through re-exports in client-types.ts are suppressed per-name with the reason inline: they exist only to publish contracts/kernel types through the package entrypoint wildcard, every internal consumer imports them from the declaring module, so "no consumer" is correct and not actionable — deleting them would remove names from the public types. `pnpm check` green, 4488 unit tests. Findings doc records the sequencing for the last 5: the upstream declarations have to come down before the shapes that need them can. Co-Authored-By: Claude Opus 5 <[email protected]> Claude-Session: https://claude.ai/code/session_01Bfu8HofkhybiAm5LECfqur
1 parent 56b72c5 commit 3fdbfe0

51 files changed

Lines changed: 1363 additions & 1141 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: 38 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -45,15 +45,41 @@ type-only inversions, R7 pins SessionState field ownership, and the shared selec
4545

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

48-
**28 + 1 edges → `client/client-types.ts`** (1236 lines). The file does three jobs: the public
49-
Node-client facade (`AgentDeviceClient`, config, transport), the per-command `*Options`/`*Result`
50-
vocabulary that `commands/`, `contracts/` and `mcp/` all need, and a re-export hub for 24
51-
`contracts/` types. Only the first is client-owned. The fix is the pattern the file already uses
52-
for those 24 re-exports: declare the command I/O vocabulary in `contracts/` and re-export it here,
53-
so the public surface stays byte-identical. Note the coupling is mutual — client-types imports
54-
`commands/interaction/runtime/gestures.ts` and `commands/system/navigation-projection.ts` — which
55-
is what closes the 5-node type cycle in §4. This is also the deferred "Node client result types"
56-
work `CONTEXT.md` already tracks.
48+
**28 + 1 edges → `client/client-types.ts`** — *done, mostly.* Now 5 edges. The vocabulary moved to
49+
`contracts/client-api.ts`, with `client/client-types.ts` keeping the `AgentDeviceClient` facade and
50+
re-exporting the rest through one wildcard, so the published `.d.ts` surface is byte-identical
51+
(verified by diffing the built `index.d.ts` name set against `main`: 216 names, no change).
52+
53+
The mutual coupling this section already warned about is what set the floor. Eight shapes could NOT
54+
move down, because each is stated in terms of a HIGHER-ranked zone:
55+
56+
| Shape(s) | Blocked by |
57+
|---|---|
58+
| `ScrollOptions` | `ScrollInputDirection` (`commands/interaction/runtime/gestures.ts`) |
59+
| `BackCommandOptions`, `OrientationCommandOptions`, `AppSwitcherCommandOptions`, `TvRemoteCommandOptions`, `AgentDeviceCommandClient` | `NavigationCommandOptions` / `ProjectedNavigationCommandClient` (`commands/system/navigation-projection.ts`) |
60+
| `MetroPrepareResult`, `MetroReloadResult` | `PrepareMetroRuntimeResult` / `ReloadMetroResult` (`metro/client-metro.ts`) |
61+
62+
Declaring those in `contracts/` would have traded 28 `commands -> client` inversions for
63+
`contracts -> commands` and `contracts -> metro` ones — the foundation depending on the layers above
64+
it, which is worse in kind even though it is fewer edges. Measured, not assumed: the first attempt
65+
put the whole file in `contracts/` and the gate went from 42 to **48**.
66+
67+
Two keystone moves made the other 84 shapes movable, and both are worth noting as a pattern:
68+
69+
- `RemoteConnectionProfileFields` joined its sibling `CloudProviderProfileFields` in
70+
`contracts/remote-config-fields.ts`. It was the root of the base chain
71+
(`AgentDeviceClientConfig` → `AgentDeviceRequestOverrides` → `DeviceCommandBaseOptions` → every
72+
per-command `*Options`), so one rank-4 declaration was pinning ~80 shapes up with it.
73+
- `DaemonBatchStep` moved to `contracts/batch-step.ts`. Its `runtime` field was written as
74+
`DaemonRequest['runtime']`, which dragged the whole daemon request type in to say
75+
`SessionRuntimeHints` — the same type, three zones lower.
76+
77+
**Remaining `commands -> client` (5) needs the upstream declarations to come down first**: move
78+
`ScrollInputDirection` and the navigation-projection types out of `commands/`, and the Metro
79+
prepare/reload result payloads out of `metro/`. Each is small; the sequencing is the point. The
80+
`mcp -> client` edge is different in kind — it is the `AgentDeviceClient` facade itself, i.e. the
81+
question of whether a command surface should know the client type. That is a design decision, not a
82+
misplaced declaration.
5783

5884
**5 + 1 edges → `daemon/daemon-command-registry.ts` and `daemon/types.ts`.** `core`'s descriptor
5985
registry composes the ADR 0003 daemon facet, whose shape the daemon declares. ADR 0003's
@@ -218,8 +244,9 @@ Still duplicated across zones, each needing the same treatment: `fill requires t
218244

219245
1. **Move the 10 outward-facing `daemon/types.ts` types into `contracts/`** (§2). Mechanical, and
220246
it clears most of §1's second cluster.
221-
2. **Split `client/client-types.ts`** (§1). Largest remaining inversion cluster, closes the 5-node
222-
type cycle, and it is already-tracked deferred work.
247+
2. ~~**Split `client/client-types.ts`** (§1).~~ Done — 42 → 18 total inversions. The follow-up is
248+
the upstream moves that unblock the last 5 (§1): `ScrollInputDirection` and the
249+
navigation-projection types out of `commands/`, Metro result payloads out of `metro/`.
223250
3. **Retire platform branches into plugin facets** (§5b), highest-count files first.
224251
4. **Share the remaining duplicated validators** (§6), following the `checkIsArgs` shape.
225252
5. Optional: give `daemon/handlers/` the directory structure its filenames already imply (§5).

‎scripts/layering/check.ts‎

Lines changed: 15 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -189,27 +189,29 @@ function checkBackEdges(edges: readonly ResolvedImportEdge[]): Violation[] {
189189

190190
// R6 ratchet: type-only spine inversions, per zone pair. R5 cannot see these (a
191191
// type-only import is free at runtime), but "zone A is declared in terms of zone B"
192-
// is still a boundary claim, and ranking type edges surfaced 61 of them. Two clusters
193-
// remain, each needing its own change rather than a file move:
192+
// is still a boundary claim, and ranking type edges surfaced 61 of them. Down to 18
193+
// after the public API vocabulary moved to contracts/client-api.ts. What remains:
194194
//
195-
// commands/contracts/mcp the per-command Options/Result vocabulary, plus the client
196-
// -> client facade itself, are declared inside the 1.2k-line public
197-
// Node-client surface (client/client-types.ts) instead of in
198-
// contracts/, where the 24 types it already re-exports live.
195+
// commands -> client (5) the eight vocabulary shapes that could NOT move down,
196+
// because each is stated in terms of a HIGHER zone:
197+
// `commands/` (navigation projection, ScrollInputDirection)
198+
// or `metro/` (prepare/reload results). Moving them needs
199+
// those upstream declarations to come down first.
200+
// mcp -> client (1) the AgentDeviceClient facade itself — a real design
201+
// question (should a command surface know the client
202+
// type?), not a declaration in the wrong place.
199203
// core/commands -> daemon-server the ADR 0003 daemon facet: core's descriptor registry
200-
// composes a shape the daemon owns. The daemon keeps the
204+
// (6) composes a shape the daemon owns. The daemon keeps the
201205
// VALUES; only the shape needs to move below core.
202-
// replay -> daemon-server `SessionAction`, the recorded-action shape replay reads and
203-
// writes. It belongs in contracts/, but it references
204-
// `CommandFlags` (core) which references `DaemonBatchStep`
205-
// (core), so it moves as a chain of three, not one file.
206+
// replay -> daemon-server (6) `SessionAction`, the recorded-action shape replay reads
207+
// and writes. It belongs in contracts/, but it references
208+
// `CommandFlags` (core), so it moves as a chain.
206209
//
207210
// The counts may only go DOWN. Fixing edges without lowering the number fails too, so the
208211
// baseline cannot quietly stop describing the tree.
209212
const TYPE_INVERSION_BASELINE: Readonly<Record<string, number>> = {
210-
'commands -> client': 28,
213+
'commands -> client': 5,
211214
'commands -> daemon-server': 1,
212-
'contracts -> client': 1,
213215
'core -> daemon-server': 5,
214216
'mcp -> client': 1,
215217
'replay -> daemon-server': 6,

‎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 '../client/client-types.ts';
16+
import type { SettingsUpdateOptions } from '../contracts/client-api.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: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -34,8 +34,6 @@ import {
3434
import { readScreenshotResultData } from './utils/screenshot-result.ts';
3535
import { isRecord } from './utils/parsing.ts';
3636
import type {
37-
AgentDeviceCommandClient,
38-
AgentDeviceClient,
3937
AgentDeviceClientConfig,
4038
AgentDeviceDaemonTransport,
4139
AppCloseOptions,
@@ -52,16 +50,20 @@ import type {
5250
Lease,
5351
MaterializationReleaseOptions,
5452
MetroPrepareOptions,
55-
MetroPrepareResult,
5653
PanOptions,
5754
FlingOptions,
58-
RotateCommandResult,
5955
SwipeGestureOptions,
6056
PinchOptions,
6157
RotateGestureOptions,
6258
SessionSaveScriptOptions,
6359
SessionSaveScriptResult,
6460
TransformGestureOptions,
61+
} from './contracts/client-api.ts';
62+
import type {
63+
AgentDeviceCommandClient,
64+
AgentDeviceClient,
65+
MetroPrepareResult,
66+
RotateCommandResult,
6567
} from './client/client-types.ts';
6668
import type { OrientationCommandResult } from './contracts/navigation.ts';
6769
import type { CommandResult } from './core/command-descriptor/command-result.ts';

‎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 './client/client-types.ts';
10+
import type { BatchStep } from './contracts/client-api.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 '../client/client-types.ts';
1+
import type { BatchStep } from '../contracts/client-api.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 '../../client/client-types.ts';
24+
import type { BatchStep } from '../../contracts/client-api.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-companion-tunnel-contract.ts‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -17,13 +17,13 @@ export const ENV_COMPANION_TUNNEL_UNREGISTER_PATH = 'AGENT_DEVICE_COMPANION_TUNN
1717
export const ENV_COMPANION_TUNNEL_DEVICE_PORT = 'AGENT_DEVICE_COMPANION_TUNNEL_DEVICE_PORT';
1818
export const ENV_COMPANION_TUNNEL_SESSION = 'AGENT_DEVICE_COMPANION_TUNNEL_SESSION';
1919

20-
export type CompanionTunnelScope = {
21-
tenantId: string;
22-
runId: string;
23-
leaseId: string;
24-
};
25-
26-
export type MetroBridgeScope = CompanionTunnelScope;
20+
// The scope SHAPE is declared in contracts/ so zones that only need the shape do not have to
21+
// declare themselves in terms of client/. Re-exported here for this module's existing consumers.
22+
export type {
23+
CompanionTunnelScope,
24+
MetroBridgeScope,
25+
} from '../contracts/companion-tunnel-scope.ts';
26+
import type { CompanionTunnelScope } from '../contracts/companion-tunnel-scope.ts';
2727

2828
export class MissingCompanionEnvError extends Error {
2929
override name = 'MissingCompanionEnvError';

‎src/client/client-normalizers.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ import type {
1919
InternalRequestOptions,
2020
MaterializationReleaseResult,
2121
StartupPerfSample,
22-
} from './client-types.ts';
22+
} from '../contracts/client-api.ts';
2323
import type { TargetShutdownResult } from '../contracts/target-shutdown-contract.ts';
2424
import {
2525
asRecord,

0 commit comments

Comments
 (0)