Skip to content

Commit 3b6bbd2

Browse files
committed
refactor(ios): delete the unused snapshot plan interface
`planIosSnapshot`, `IosSnapshotPlan`, the `plan` member of `IosSnapshotEngine` and `createIosSnapshotEngine` had no production caller: production reaches presentation through `publishIosSnapshot` / `presentIosSnapshot` directly, and the barrel re-export was all that kept the factory alive for fallow. Deleting the plan takes the last reader of most of `IOS_SNAPSHOT_PRODUCER_CAPABILITIES` with it. The table was typed over all four producers while only the two provider producers ever consumed its residue-shaping fields, and it had already drifted: it declared `simulator-ax-bridge` with `hittabilityEvidence: 'available'` while the bridge adapter emits `unavailable-fact: hittability` on every capture. Rather than correct the value, the table is now keyed on `IosProviderAcquisitionProducer`, so a producer that builds its own facts cannot declare one at all. Truncation is the one capability the runner and the bridge still need answered, so it moves to a table of its own over all four producers, read through `iosSnapshotTruncationEvidence`. Both keep `'available'`, which is what the adapter and the runner payload actually prove.
1 parent be62249 commit 3b6bbd2

12 files changed

Lines changed: 156 additions & 291 deletions

File tree

‎packages/capture-kit/src/ios-snapshot-acquisition.ts‎

Lines changed: 54 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,83 +1,87 @@
11
import type { SnapshotRuntimeAcquiredResult } from '@agent-device/contracts/interactor-types';
22
import type {
33
IosAcquisitionResidue,
4+
IosProviderAcquisitionCapabilities,
45
IosProviderAcquisitionProducer,
5-
IosSnapshotProducer,
6-
IosSnapshotProducerCapabilities,
6+
IosSnapshotEvidenceAvailability,
77
IosSnapshotLineage,
8+
IosSnapshotProducer,
89
IosViewportEvidence,
910
} from '@agent-device/contracts/ios-snapshot';
1011
import { normalizeType } from '@agent-device/contracts/snapshot';
1112
import { isPositiveFiniteRect } from '@agent-device/kernel/rect';
1213
import type { RawSnapshotNode, Rect } from '@agent-device/kernel/snapshot';
1314

14-
const ACQUIRED_PRODUCER_CAPABILITY_DEFAULTS = {
15-
stage: 'acquired',
16-
acquisitionDepth: {
17-
rawTraversal: { kind: 'incomplete' },
18-
regularPresented: { kind: 'incomplete' },
19-
},
20-
scopeCompleteness: 'incomplete',
21-
interactiveQueryCompleteness: 'incomplete',
22-
viewportEvidence: 'available',
23-
hittabilityEvidence: 'unavailable',
24-
truncationEvidence: 'unavailable',
25-
} as const;
26-
27-
const IOS_SNAPSHOT_PRODUCER_CAPABILITY_VALUES = {
28-
'apple-runner': {
29-
producer: 'apple-runner',
30-
stage: 'presented',
31-
acquisitionDepth: {
32-
rawTraversal: { kind: 'not-applicable' },
33-
regularPresented: { kind: 'not-applicable' },
34-
},
35-
scopeCompleteness: 'complete',
36-
interactiveQueryCompleteness: 'complete',
37-
viewportEvidence: 'available',
38-
hittabilityEvidence: 'available',
39-
truncationEvidence: 'available',
40-
},
41-
'simulator-ax-bridge': {
42-
...ACQUIRED_PRODUCER_CAPABILITY_DEFAULTS,
43-
producer: 'simulator-ax-bridge',
15+
/**
16+
* The facts a *provider* acquisition leaves unproven, keyed only by the producers whose residue
17+
* this module derives.
18+
*
19+
* `apple-runner` and `simulator-ax-bridge` are absent by construction, not by omission: each
20+
* builds its own residue at the source (the bridge adapter emits `unavailable-fact: hittability`
21+
* on every capture; the runner presents and reports its own facts), so a row here would be a
22+
* declaration with no reader — which is how the table came to claim the bridge had hittability
23+
* evidence while every bridge-served `snapshot -i` printed the opposite (#2199). Keying the
24+
* record on {@link IosProviderAcquisitionProducer} makes that claim not compile.
25+
*/
26+
const IOS_PROVIDER_ACQUISITION_CAPABILITY_VALUES = {
27+
'appium-source': {
28+
producer: 'appium-source',
4429
acquisitionDepth: {
45-
rawTraversal: { kind: 'complete' },
30+
rawTraversal: { kind: 'incomplete' },
4631
regularPresented: { kind: 'incomplete' },
4732
},
48-
hittabilityEvidence: 'available',
49-
truncationEvidence: 'available',
50-
},
51-
'appium-source': {
52-
...ACQUIRED_PRODUCER_CAPABILITY_DEFAULTS,
53-
producer: 'appium-source',
33+
hittabilityEvidence: 'unavailable',
5434
},
5535
'limrun-ios-tree': {
56-
...ACQUIRED_PRODUCER_CAPABILITY_DEFAULTS,
5736
producer: 'limrun-ios-tree',
37+
acquisitionDepth: {
38+
rawTraversal: { kind: 'incomplete' },
39+
regularPresented: { kind: 'incomplete' },
40+
},
41+
hittabilityEvidence: 'unavailable',
5842
},
59-
} as const satisfies Record<IosSnapshotProducer, IosSnapshotProducerCapabilities>;
43+
} as const satisfies Record<IosProviderAcquisitionProducer, IosProviderAcquisitionCapabilities>;
6044

61-
export const IOS_SNAPSHOT_PRODUCER_CAPABILITIES: Readonly<
62-
Record<IosSnapshotProducer, IosSnapshotProducerCapabilities>
63-
> = Object.freeze(IOS_SNAPSHOT_PRODUCER_CAPABILITY_VALUES);
45+
/**
46+
* Whether a producer observes truncation at all, for every iOS producer.
47+
*
48+
* This is the one capability the runner and the bridge genuinely need declared: a capture that
49+
* reported nothing about truncation is only "not truncated" when its producer would have noticed
50+
* (#2188 invariant 5), and `snapshotTruncationForResult` has to answer that for all four. It is a
51+
* table of its own rather than a column of the provider capabilities so that each producer states
52+
* this fact exactly once, in the only place that asks.
53+
*
54+
* The runner payload carries a required `truncated` boolean, and the bridge adapter rejects an
55+
* envelope without one and turns a true into a `truncated` residue — so both observe it.
56+
*/
57+
const IOS_SNAPSHOT_TRUNCATION_EVIDENCE = {
58+
'apple-runner': 'available',
59+
'simulator-ax-bridge': 'available',
60+
'appium-source': 'unavailable',
61+
'limrun-ios-tree': 'unavailable',
62+
} as const satisfies Record<IosSnapshotProducer, IosSnapshotEvidenceAvailability>;
63+
64+
export function iosSnapshotTruncationEvidence(
65+
producer: IosSnapshotProducer,
66+
): IosSnapshotEvidenceAvailability {
67+
return IOS_SNAPSHOT_TRUNCATION_EVIDENCE[producer];
68+
}
6469

6570
function deriveIosSnapshotAcquisitionResidue(
66-
producer: IosSnapshotProducerCapabilities,
71+
producer: IosProviderAcquisitionCapabilities,
6772
viewport: IosViewportEvidence,
6873
): readonly IosAcquisitionResidue[] {
6974
const residue: IosAcquisitionResidue[] = [];
7075
if (producer.hittabilityEvidence === 'unavailable') {
7176
residue.push({ kind: 'unavailable-fact', fact: 'hittability' });
7277
}
7378
if (
74-
producer.stage === 'acquired' &&
75-
(producer.acquisitionDepth.rawTraversal.kind === 'incomplete' ||
76-
producer.acquisitionDepth.regularPresented.kind === 'incomplete')
79+
producer.acquisitionDepth.rawTraversal.kind === 'incomplete' ||
80+
producer.acquisitionDepth.regularPresented.kind === 'incomplete'
7781
) {
7882
residue.push({ kind: 'unavailable-fact', fact: 'acquisition-depth' });
7983
}
80-
if (producer.truncationEvidence === 'unavailable') {
84+
if (iosSnapshotTruncationEvidence(producer.producer) === 'unavailable') {
8185
residue.push({ kind: 'unavailable-fact', fact: 'truncation' });
8286
}
8387
if (viewport.kind === 'missing') {
@@ -94,7 +98,7 @@ export function createIosSnapshotAcquisition(
9498
lineage: IosSnapshotLineage;
9599
}>,
96100
): SnapshotRuntimeAcquiredResult {
97-
const producer = IOS_SNAPSHOT_PRODUCER_CAPABILITIES[input.producer];
101+
const producer = IOS_PROVIDER_ACQUISITION_CAPABILITY_VALUES[input.producer];
98102
return {
99103
stage: 'acquired',
100104
acquisition: {

‎packages/capture-kit/src/ios-snapshot-engine/engine.test.ts‎

Lines changed: 16 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import assert from 'node:assert/strict';
22
import { test } from 'vitest';
33
import type {
44
IosSnapshotAcquisition,
5+
IosSnapshotEngine,
56
IosSnapshotInput,
67
IosSnapshotRequest,
78
IosSnapshotValidationFacts,
@@ -13,7 +14,6 @@ import {
1314
} from '@agent-device/capture-kit/ios-snapshot-planning';
1415
import { toIosSnapshotEngineErrorDetails } from './types.ts';
1516
import {
16-
createIosSnapshotEngine,
1717
IosSnapshotEngineError,
1818
presentIosInteractiveSnapshot,
1919
presentIosSnapshot,
@@ -340,15 +340,26 @@ test('interactive compaction stays available through the engine boundary', () =>
340340
);
341341
});
342342

343-
test('the configured engine keeps its fold policy and exposes the contract operations', () => {
344-
const engine = createIosSnapshotEngine({ foldPolicy: 'plain-viewport' });
343+
/**
344+
* `IosSnapshotEngine` has one operation because presentation happens once (#2188 invariant 2).
345+
* Pinning `publishIosSnapshot` to it keeps the contract a description of the export production
346+
* actually calls, rather than a shape only a factory ever satisfied (#2199).
347+
*/
348+
test('publishing satisfies the whole engine contract under an explicit fold policy', () => {
349+
const engine: IosSnapshotEngine = {
350+
publish: (input, request) =>
351+
publishIosSnapshot(input, request, { foldPolicy: 'plain-viewport' }),
352+
};
345353
const request = createIosSnapshotRequest();
346354
const presented = presentIosSnapshot(acquiredInput(request, nestedNodes()), request, {
347355
foldPolicy: 'plain-viewport',
348356
});
349357

350-
assert.equal(typeof engine.plan, 'function');
351-
assert.equal(typeof engine.publish, 'function');
358+
assert.deepEqual(Object.keys(engine), ['publish']);
359+
assert.equal(
360+
engine.publish(acquiredInput(request, nestedNodes()), request).payload.nodes.length,
361+
presented.nodes.length,
362+
);
352363
assert.equal(presented.stats.sourceNodeCount, nestedNodes().length);
353364
});
354365

‎packages/capture-kit/src/ios-snapshot-engine/engine.ts‎

Lines changed: 0 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,9 @@ import {
22
buildIosSnapshotComparisonIdentity,
33
buildIosSnapshotPresentationKey,
44
deriveIosCaptureHint,
5-
planIosSnapshot,
65
} from '../ios-snapshot-planning.ts';
76
import type {
87
IosSnapshotAcquisition,
9-
IosSnapshotEngine,
108
IosSnapshotInput,
119
IosSnapshotPublication,
1210
IosSnapshotRequest,
@@ -27,14 +25,6 @@ import { IosSnapshotEngineError } from './types.ts';
2725

2826
const DEFAULT_FOLD_POLICY: IosSnapshotFoldPolicy = 'cursor-projected';
2927

30-
export function createIosSnapshotEngine(options: IosSnapshotEngineOptions = {}): IosSnapshotEngine {
31-
const foldPolicy = options.foldPolicy ?? DEFAULT_FOLD_POLICY;
32-
return Object.freeze({
33-
plan: planIosSnapshot,
34-
publish: (input, request) => publishIosSnapshot(input, request, { foldPolicy }),
35-
});
36-
}
37-
3828
export function publishIosSnapshot(
3929
input: IosSnapshotInput,
4030
request: IosSnapshotRequest,

‎packages/capture-kit/src/ios-snapshot-engine/index.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
export { createIosSnapshotEngine, presentIosSnapshot, publishIosSnapshot } from './engine.ts';
1+
export { presentIosSnapshot, publishIosSnapshot } from './engine.ts';
22
export { presentIosRunnerSnapshot } from './runner-presentation.ts';
33
export {
44
buildIosInteractiveSnapshotPresentation,

0 commit comments

Comments
 (0)