Skip to content

Commit 0e7df74

Browse files
authored
refactor(capture-kit): lift the iOS snapshot route into the capture-kit router (#4308)
* refactor(capture-kit): lift the iOS snapshot route core into a platform-neutral router Move the route core and its refusal policy from platform-apple into capture-kit/src/snapshot-router, and bind the local guest bridge and the runner-served bridge to it. Delete the Apple route core. A channel now declares servesDevice, awaitsDiscovery and one refresh path: only the runner channel, whose ordinary resolution returns an unverified cache, declares refreshTarget; the stale-target fallback calls refreshTarget ?? resolveTarget. * docs: point the route references at the capture-kit snapshot router * chore(gates): forbid platform and provider imports in the snapshot router Declare the snapshot-router executable policy with every platform, provider, apple-runner and tv-cdp package as a forbidden target. Pin it with a real-tree check, a coverage check over the platform-* and provider-* packages, and a positive control for static and dynamic imports. Pin the two new capture-kit exports in the R11 manifest check. * fix(capture-kit): always force rediscovery after stale-target evidence Every snapshot source channel now declares a required refreshTarget and a required resolutionVerifiesIdentity. The stale-target fallback always calls refreshTarget, so the local channel no longer republishes its cached generation after the bridge reported a newer one. Only a channel whose resolution returns an unverified cache (the runner) refreshes before it trusts a disabled circuit, so the local channel keeps main's cost on that path. The local resolver drops its 'refresh' flag for a separate refreshTarget, as the runner bridge has. The runner bridge now returns its own channel declaration, which removes the three hand copies in the runner tests. * refactor(apple): import moved snapshot source declarations from capture-kit The snapshot-source types and errors modules re-exported the failure types and SnapshotSourceError after they moved to the capture-kit snapshot source channel. Their importers now name the owner, the re-exports are gone, and the snapshot-source facade no longer carries the moved types (its fallow exemption drops SnapshotSourceFailureKind). The route tests share one simctl read stub, which keeps the file under its line limit after the new stale-target case. * refactor(capture-kit): hand the snapshot router its presenter, not a host The router reads one host behavior, the iOS acquisition presenter. It now takes that function, so the SnapshotRouterHost shape and the { snapshot: { presentIosAcquisition } } wrapper at the runner binding and in its tests are gone. * test(layering): read router boundary packages from tracked manifests The positive control enumerated package directories from the working tree, so an untracked scratch package could fail it. It now reads the tracked manifests, as the other layering scans do, and also covers the apple-runner and tv-cdp targets the policy forbids. * test(apple): keep the snapshot-target compile proof in the lifecycle fixtures The rebase onto main put lifecycle.test.ts one line over the 1000-line lint limit. The compile-time SnapshotSourceTarget proof is not a lifecycle test, so it moves to the fixtures, which are type-checked the same way.
1 parent 3ad2164 commit 0e7df74

40 files changed

Lines changed: 1284 additions & 1126 deletions

‎.fallowrc.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -325,9 +325,9 @@
325325
"exports": ["*"]
326326
},
327327
{
328-
// Apple Simulator snapshot acquisition is a private package facet consumed by downstream runtime work; Fallow cannot see external consumers through the workspace exports map. Only the shared failure/limits/request-target types report without an exemption; the factory and its source interface resolve through the package boundary.
328+
// Apple Simulator snapshot acquisition is a private package facet consumed by downstream runtime work; Fallow cannot see external consumers through the workspace exports map. Only the shared limits/request-target types report without an exemption; the factory and its source interface resolve through the package boundary.
329329
"file": "packages/platform-apple/src/snapshot-source-facade.ts",
330-
"exports": ["SnapshotSourceFailureKind", "SnapshotSourceLimits", "SnapshotSourceTarget"]
330+
"exports": ["SnapshotSourceLimits", "SnapshotSourceTarget"]
331331
},
332332
{
333333
// The native wire vocabulary is exported only so the parity test can pin the Objective-C literals; it is not part of the snapshot-source package facet.

‎contracts/fixtures/ios-snapshot-bridge-refusals.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"description": "Every refusal code the snapshot bridge emits, with the scope the route gives it. A capture-scoped refusal speaks for one capture and keeps the app generation on the bridge; generation-scoped codes retire the generation, and runner-session-scoped codes retire the runner bridge. Emitters: the Objective-C reader (apple/snapshot-bridge), the runner-served bridge (RunnerSnapshotBridge.m, RunnerTests+SnapshotBridge.swift), and the TypeScript snapshot source (packages/platform-apple/src/snapshot-source, runner-snapshot-bridge.ts). The TypeScript policy packages/platform-apple/src/snapshot-route-failure-policy.ts mirrors this table. test/repo-guards/snapshot-bridge-refusals.test.ts fails when an emitted code is missing here, when a code here is emitted nowhere, or when the policy disagrees. Classify a new code here by an explicit decision; an unlisted code fails the guard.",
2+
"description": "Every refusal code the snapshot bridge emits, with the scope the route gives it. A capture-scoped refusal speaks for one capture and keeps the app generation on the bridge; generation-scoped codes retire the generation, and runner-session-scoped codes retire the runner bridge. Emitters: the Objective-C reader (apple/snapshot-bridge), the runner-served bridge (RunnerSnapshotBridge.m, RunnerTests+SnapshotBridge.swift), and the TypeScript snapshot source (packages/platform-apple/src/snapshot-source, runner-snapshot-bridge.ts). The TypeScript policy packages/capture-kit/src/snapshot-router/refusal-policy.ts mirrors this table. test/repo-guards/snapshot-bridge-refusals.test.ts fails when an emitted code is missing here, when a code here is emitted nowhere, or when the policy disagrees. Classify a new code here by an explicit decision; an unlisted code fails the guard.",
33
"captureScoped": [
44
{
55
"code": "window-coordinate-space-unresolved",

‎docs/adr/0023-end-state-hop-trace.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -179,11 +179,11 @@ Each name below has a `-runtime.ts` suffix under `packages/contracts/src/`:
179179

180180
## `snapshot` / iOS Simulator: HTTP entry → AX bridge `socket.write` (primary) / runner `fetch` (fallback)
181181

182-
The route branches at `packages/platform-apple/src/snapshot-route.ts` through `route.capture`, `isEligible`, and the per-generation circuit breaker.
182+
The route branches at `packages/capture-kit/src/snapshot-router/router.ts` through `capture`, `routeEligibility`, and the per-generation circuit breaker.
183183
The in-simulator AX bridge is primary.
184184
The XCTest runner is fallback under any of these conditions:
185185

186-
- `isEligible` returns false.
186+
- `routeEligibility` does not return `bridge`.
187187
- AX acquisition fails.
188188
- Single-flight target discovery has not settled within this capture's `TARGET_DISCOVERY_WAIT_MS` wait in `snapshot-target.ts`.
189189

@@ -226,7 +226,7 @@ The clear has no effect on iOS.
226226
| 22 | `packages/platform-apple/src/index.ts` | `loadRuntime` pairs the plugin with the runtime module | pass-through | KEEP — declared ADR §2 `loadRuntime` boundary |
227227
| 23 | `packages/platform-apple/src/runtime.ts` | `bind` → `bindAppleSnapshotRuntime` | orchestration | KEEP — Apple runtime owner |
228228
| 24 | `packages/platform-apple/src/runtime-snapshot.ts` | `bindAppleSnapshotRuntime` wires the AX and fallback closures | orchestration | KEEP — AX/runner wiring (tests pin it) |
229-
| 25 | `packages/platform-apple/src/snapshot-route.ts` | `createAppleSnapshotRoute`; `isEligible` + circuit breaker | policy | KEEP — AX/runner route + breaker (the fork) |
229+
| 25 | `packages/capture-kit/src/snapshot-router/router.ts` | `createSnapshotRouter`; `routeEligibility` + circuit breaker | policy | KEEP — AX/runner route + breaker (the fork) |
230230
| 26 | `src/runtime.ts` | `createAgentDevice`: the bound runtime object | orchestration | KEEP — agent device facade |
231231
| 27 | `src/commands/index.ts` | `bindCommands` binds the command catalog | orchestration | KEEP — command catalog boundary |
232232
| 28 | `src/commands/runtime-types.ts` | `bindRuntimeCommands` wraps the runtime into closures | pass-through | REMOVABLE — thin closure wrapper; depth lives in the commands |

‎docs/adr/0038-snapshot-capture-source-routing.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
Accepted.
66
This record owns snapshot source routing for every platform and provider.
77
It amends [ADR 0004](0004-ios-snapshot-backend-strategy.md), which keeps the iOS acquisition, presentation, geometry, and system-surface contracts.
8-
The router does not exist yet. [#4205](https://github.com/callstack/agent-device/issues/4205) holds the migration plan and its guards.
8+
The router is in `packages/capture-kit/src/snapshot-router/`. [#4205](https://github.com/callstack/agent-device/issues/4205) holds the remaining migration plan and its guards.
99

1010
## Context
1111

@@ -77,4 +77,4 @@ A future app-only source needs window-ownership evidence that is tied to its rea
7777

7878
- Provenance types move from kernel to contracts, and both iOS sources bind to the router.
7979
- Readers, decoding, discovery, process checks, native budgets, geometry, and lifecycle stay platform-specific.
80-
- Open gaps: the router, the identity-stamp helper, and the producer registry do not exist yet. The runner-session scope is pending [#4256](https://github.com/callstack/agent-device/pull/4256).
80+
- Open gaps: the identity-stamp helper and the producer registry do not exist yet.

‎packages/capture-kit/package.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -338,6 +338,14 @@
338338
"types": "./src/snapshot-rect-projection.ts",
339339
"default": "./src/snapshot-rect-projection.ts"
340340
},
341+
"./snapshot-router": {
342+
"types": "./src/snapshot-router/router.ts",
343+
"default": "./src/snapshot-router/router.ts"
344+
},
345+
"./snapshot-source-channel": {
346+
"types": "./src/snapshot-router/source-channel.ts",
347+
"default": "./src/snapshot-router/source-channel.ts"
348+
},
341349
"./snapshot-state": {
342350
"types": "./src/snapshot-state.ts",
343351
"default": "./src/snapshot-state.ts"

packages/platform-apple/src/snapshot-route-failure-policy.test.ts renamed to packages/capture-kit/src/snapshot-router/refusal-policy.test.ts

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ import fs from 'node:fs';
22
import path from 'node:path';
33
import { describe, expect, test } from 'vitest';
44
import { IOS_SYSTEM_SURFACE_HOSTS } from '@agent-device/contracts/ios-system-surface';
5-
import { bridgeFailureDisposition } from './snapshot-route-failure-policy.ts';
5+
import { bridgeFailureDisposition } from './refusal-policy.ts';
66

77
// Each expectation below is written out, never read back from the production table: a test that
88
// derived the scope from the same table could not detect the table entry moving.
@@ -131,7 +131,7 @@ const fixture = JSON.parse(
131131
fs.readFileSync(
132132
path.resolve(
133133
import.meta.dirname,
134-
'../../../contracts/fixtures/ios-snapshot-bridge-refusals.json',
134+
'../../../../contracts/fixtures/ios-snapshot-bridge-refusals.json',
135135
),
136136
'utf8',
137137
),

packages/platform-apple/src/snapshot-route-failure-policy.ts renamed to packages/capture-kit/src/snapshot-router/refusal-policy.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ import {
22
IOS_SYSTEM_SURFACE_HOSTS,
33
type IosSystemSurfaceHost,
44
} from '@agent-device/contracts/ios-system-surface';
5-
import type { SnapshotSourceFailure } from './snapshot-source-facade.ts';
5+
import type { SnapshotSourceFailure } from './source-channel.ts';
66

77
/**
88
* What the screen showed when a capture-scoped bridge refusal fired: a preparation still running

0 commit comments

Comments
 (0)