Skip to content

Commit 7b8b463

Browse files
committed
refactor(snapshot): gate the backend name, and stop pinning vocabulary order
The annotation reader was one predicate plus a blanket cast. `backend` names the recovery strategy in the warning line, so it goes through a declared map keyed against the kernel union now, and capture-kit lost both of its `as` casts on the way: the strategy is gated on the capability table it already imports, the reason code on an exhaustive map over its union. A full projection in contracts was tried and the repo's own gates refuse it — fallow reports a 4-group, 104-line clone family against capture-kit's normalizer, on top of the eager-closure gate that already forbids a shared reader. The re-read stays in the shape `readTargetActivation` in the same file uses: check the two names that decide presentation, forward what this module published, and pin the pair payload-by-payload from capture-kit's test. Order pinning drops out. The fixture is compared as a set on both sides, the stamping test asserts each case's own raw value, and the unread 28-line capture builder and its import are gone.
1 parent eba368c commit 7b8b463

7 files changed

Lines changed: 140 additions & 99 deletions

File tree

‎apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+SnapshotQualityStateTests.swift‎

Lines changed: 16 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
11
import XCTest
2-
import AgentDeviceSnapshotPresentation
32

43
#if AGENT_DEVICE_RUNNER_UNIT_TESTS
54
extension RunnerTests {
@@ -24,55 +23,30 @@ extension RunnerTests {
2423
return try JSONDecoder().decode([String].self, from: Data(contentsOf: fixtureURL))
2524
}
2625

27-
private func wireTestCapture() -> SnapshotBackendCapture {
28-
SnapshotBackendCapture(
29-
payload: DataPayload(
30-
nodes: [
31-
SnapshotPresentation.singleElementRead(
32-
RawAXNode(
33-
index: 0,
34-
type: "Application",
35-
label: "App",
36-
identifier: nil,
37-
value: nil,
38-
rect: SnapshotRect(.zero),
39-
enabled: true,
40-
focused: nil,
41-
selected: nil,
42-
hittable: true,
43-
depth: 0,
44-
parentIndex: nil,
45-
hiddenContentAbove: nil,
46-
hiddenContentBelow: nil
47-
)
48-
)
49-
],
50-
truncated: false
51-
),
52-
effectiveDepth: nil
53-
)
54-
}
55-
5626
/// The one claim of this file: the runner's closed enum and the shared TypeScript table name the
57-
/// same states in the same order. The kernel's `SNAPSHOT_QUALITY_STATES` is pinned to it too, so
58-
/// the two runtimes cannot drift into a verdict the host drops along with its disclosure.
27+
/// same states. The kernel's `SNAPSHOT_QUALITY_STATES` is pinned to it too, so the two runtimes
28+
/// cannot drift into a verdict the host drops along with its disclosure. Compared as a set: the
29+
/// names are the contract, and a reordering of `allCases` cannot produce a wrong verdict.
5930
func testSnapshotQualityStatesMatchSharedWireFixture() throws {
6031
XCTAssertEqual(
61-
try loadSnapshotQualityStatesFixture(),
62-
SnapshotQualityState.allCases.map(\.rawValue),
32+
Set(try loadSnapshotQualityStatesFixture()),
33+
Set(SnapshotQualityState.allCases.map(\.rawValue)),
6334
"update the fixture and the kernel tuple together with the enum"
6435
)
6536
}
6637

6738
/// What the daemon receives for each state, taken from the production stamping path rather than a
68-
/// hand-built verdict: the wire string is the fixture's, so a change of representation — an
69-
/// `Int` backing, a nested object, a renamed case — goes red here on the actual payload.
70-
func testStampedVerdictEncodesTheFixtureStateString() throws {
71-
let fixture = try loadSnapshotQualityStatesFixture()
72-
XCTAssertEqual(fixture.count, SnapshotQualityState.allCases.count)
73-
for (index, state) in SnapshotQualityState.allCases.enumerated() {
39+
/// hand-built verdict: the wire string is the case's own raw value, so a change of
40+
/// representation — an `Int` backing, a nested object — goes red here on the actual payload, and
41+
/// a renamed raw value goes red in the fixture test above.
42+
func testStampedVerdictEncodesTheCaseRawValue() throws {
43+
let capture = SnapshotBackendCapture(
44+
payload: DataPayload(nodes: [], truncated: false),
45+
effectiveDepth: nil
46+
)
47+
for state in SnapshotQualityState.allCases {
7448
let payload = stampedSnapshotPayload(
75-
wireTestCapture(),
49+
capture,
7650
backend: .recursiveTree,
7751
state: state,
7852
reason: nil
@@ -81,7 +55,7 @@ extension RunnerTests {
8155
StampedWireVerdict.self,
8256
from: JSONEncoder().encode(payload)
8357
)
84-
XCTAssertEqual(wire.snapshotQuality.state, fixture[index], state.rawValue)
58+
XCTAssertEqual(wire.snapshotQuality.state, state.rawValue)
8559
}
8660
}
8761

‎packages/capture-kit/src/snapshot-quality-verdict.test.ts‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import { test } from 'vitest';
22
import assert from 'node:assert/strict';
33

4+
import { readSerializedSnapshotCaptureAnnotations } from '@agent-device/contracts/capture';
45
import { SNAPSHOT_QUALITY_STATES } from '@agent-device/kernel/snapshot';
56
import {
67
isSparseSnapshotQualityVerdict,
@@ -115,3 +116,42 @@ test('preferredSnapshotBackendForVerdict pins only private-ax captures', () => {
115116
);
116117
assert.equal(preferredSnapshotBackendForVerdict(undefined), undefined);
117118
});
119+
120+
/**
121+
* Two readings of one verdict exist on purpose: this module normalizes an untrusted runner payload,
122+
* while contracts re-publishes what this repo published and normalizes nothing (the eager-closure
123+
* gate forbids either reaching a shared module, and the duplication gate refuses a second
124+
* normalization). They must still agree on which payloads are a verdict at all: a name one version
125+
* cannot speak is verdict-absent on both sides of the daemon boundary.
126+
*/
127+
const VERDICT_PAYLOADS: unknown[] = [
128+
{ state: 'sparse', backend: 'private-ax' },
129+
{ state: 'healthy', backend: 'tree', reason: 'ok', reasonCode: 'requested-backend' },
130+
{ state: 'recovered', backend: 'queries', reason: 42, effectiveDepth: '56' },
131+
{ state: 'sparse', backend: 'tree', collapsedLeafIndexes: [3, 'four'] },
132+
{ state: 'sparse', backend: 'tree', customActions: { read: 12 } },
133+
{ state: 'sparse', backend: 'tree', customActions: { read: 12, candidates: 19 } },
134+
{ state: 'sparse', backend: 'tree', timing: { acquisitionMs: 12.5 } },
135+
{ state: 'sparse', backend: 'tree', timing: { acquisitionMs: 12.5, presentationMs: 34.75 } },
136+
{ state: 'sparse', backend: 'tree', reasonCode: 'future-code' },
137+
{ state: 'degraded', backend: 'tree' },
138+
{ state: 'sparse', backend: 'uiautomator' },
139+
{ state: 'constructor', backend: 'constructor' },
140+
{ backend: 'tree' },
141+
{ state: 'sparse' },
142+
null,
143+
'verdict',
144+
];
145+
146+
test('the contracts re-read calls a verdict a verdict on every payload', () => {
147+
for (const payload of VERDICT_PAYLOADS) {
148+
const reRead = readSerializedSnapshotCaptureAnnotations({
149+
snapshotQuality: payload,
150+
}).snapshotQuality;
151+
assert.equal(
152+
reRead === undefined,
153+
readSnapshotQualityVerdict(payload) === undefined,
154+
JSON.stringify(payload),
155+
);
156+
}
157+
});

‎packages/capture-kit/src/snapshot-quality-verdict.ts‎

Lines changed: 28 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -2,64 +2,57 @@ import type { SnapshotQualityState, SnapshotQualityVerdict } from '@agent-device
22
import { SNAPSHOT_QUALITY_BACKEND_CAPABILITIES } from './snapshot-quality-backend-capabilities.ts';
33

44
/**
5-
* Every declared state, keyed against the kernel union so this map cannot fall behind it: a state
6-
* added there without a key here is a compile error, where a set literal merely typed as the union
7-
* stays green and this reader drops the verdict as verdict-absent.
5+
* The verdict names this version can speak, each keyed against its kernel union so a map cannot
6+
* fall behind it: a name added there without a key here is a compile error, where a set literal
7+
* merely typed as the union stays green and this reader drops the verdict as verdict-absent. These
8+
* readers hold the maps rather than importing the kernel's, because this module's eager closure is
9+
* frozen at its merge-base size. The strategies need no map: `SNAPSHOT_QUALITY_BACKEND_CAPABILITIES`
10+
* is the accepted set, keyed by the same names.
811
*/
9-
const snapshotQualityStatesAreTheVocabulary: Record<SnapshotQualityState, true> = {
12+
const DECLARED_STATES: Record<SnapshotQualityState, true> = {
1013
healthy: true,
1114
recovered: true,
1215
sparse: true,
1316
};
1417

15-
function isSnapshotQualityState(value: unknown): value is SnapshotQualityState {
16-
return typeof value === 'string' && Object.hasOwn(snapshotQualityStatesAreTheVocabulary, value);
17-
}
18+
const DECLARED_REASON_CODES: Record<NonNullable<SnapshotQualityVerdict['reasonCode']>, true> = {
19+
'ax-rejected': true,
20+
'sparse-tree': true,
21+
budget: true,
22+
'no-nodes': true,
23+
'capture-failed': true,
24+
'presentation-failed': true,
25+
deferred: true,
26+
'requested-backend': true,
27+
};
1828

19-
const SNAPSHOT_QUALITY_BACKENDS = new Set<SnapshotQualityVerdict['backend']>(
20-
Object.keys(SNAPSHOT_QUALITY_BACKEND_CAPABILITIES) as SnapshotQualityVerdict['backend'][],
21-
);
22-
const SNAPSHOT_QUALITY_REASON_CODES = new Set<NonNullable<SnapshotQualityVerdict['reasonCode']>>([
23-
'ax-rejected',
24-
'sparse-tree',
25-
'budget',
26-
'no-nodes',
27-
'capture-failed',
28-
'presentation-failed',
29-
'deferred',
30-
'requested-backend',
31-
]);
29+
function isDeclared<Key extends string, Value>(
30+
vocabulary: Record<Key, Value>,
31+
value: unknown,
32+
): value is Key {
33+
return typeof value === 'string' && Object.hasOwn(vocabulary, value);
34+
}
3235

3336
export function readSnapshotQualityVerdict(value: unknown): SnapshotQualityVerdict | undefined {
3437
if (!value || typeof value !== 'object') return undefined;
3538
const raw = value as Record<string, unknown>;
3639
// Validate the load-bearing union fields: an object with an unknown state/backend is not a
3740
// verdict this version understands, so it falls through as verdict-absent and the legacy
3841
// node-shape detectors run instead of being silently suppressed by a malformed payload.
39-
const state = raw.state;
40-
if (!isSnapshotQualityState(state)) {
41-
return undefined;
42-
}
4342
if (
44-
typeof raw.backend !== 'string' ||
45-
!SNAPSHOT_QUALITY_BACKENDS.has(raw.backend as SnapshotQualityVerdict['backend'])
43+
!isDeclared(DECLARED_STATES, raw.state) ||
44+
!isDeclared(SNAPSHOT_QUALITY_BACKEND_CAPABILITIES, raw.backend)
4645
) {
4746
return undefined;
4847
}
4948
const timing = readSnapshotQualityTiming(raw.timing);
5049
return {
51-
state,
52-
backend: raw.backend as SnapshotQualityVerdict['backend'],
50+
state: raw.state,
51+
backend: raw.backend,
5352
reason: typeof raw.reason === 'string' ? raw.reason : undefined,
5453
// An unknown reasonCode is dropped, not rejected: a forward-version runner that adds one
5554
// still yields a usable verdict (only the budget-specific wording is keyed off it).
56-
reasonCode:
57-
typeof raw.reasonCode === 'string' &&
58-
SNAPSHOT_QUALITY_REASON_CODES.has(
59-
raw.reasonCode as NonNullable<SnapshotQualityVerdict['reasonCode']>,
60-
)
61-
? (raw.reasonCode as SnapshotQualityVerdict['reasonCode'])
62-
: undefined,
55+
reasonCode: isDeclared(DECLARED_REASON_CODES, raw.reasonCode) ? raw.reasonCode : undefined,
6356
customActions: readCustomActionCoverage(raw.customActions),
6457
effectiveDepth: typeof raw.effectiveDepth === 'number' ? raw.effectiveDepth : undefined,
6558
collapsedLeafIndexes: Array.isArray(raw.collapsedLeafIndexes)

‎packages/contracts/src/snapshot-capture-annotations.test.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,3 +73,17 @@ test('a state outside the declared vocabulary drops the serialized verdict', ()
7373
assert.equal(annotations.snapshotQuality, undefined, JSON.stringify(state));
7474
}
7575
});
76+
77+
/**
78+
* `backend` names the recovery strategy in the user-facing warning line, so it goes through the
79+
* declared strategies too: a strategy this version cannot name is not a verdict it can present. The
80+
* optional fields are forwarded as published (see the reader); normalizing them is capture-kit.
81+
*/
82+
test('an undeclared backend drops the serialized verdict', () => {
83+
for (const backend of ['uiautomator', 'tree ', 'Tree', 'constructor', '', 42, null, undefined]) {
84+
const annotations = readSerializedSnapshotCaptureAnnotations({
85+
snapshotQuality: { state: 'sparse', backend },
86+
});
87+
assert.equal(annotations.snapshotQuality, undefined, JSON.stringify(backend));
88+
}
89+
});

‎packages/contracts/src/snapshot-capture-annotations.ts‎

Lines changed: 32 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,30 @@
11
import type {
22
IosTargetActivation,
3+
SnapshotCaptureBackend,
34
SnapshotQualityState,
45
SnapshotQualityVerdict,
56
} from '@agent-device/kernel/snapshot';
67
import type { AndroidSnapshotBackendMetadata } from './snapshot-types.ts';
78

89
/**
9-
* Every declared state, keyed against the kernel union so this map cannot fall behind it: a state
10-
* added there without a key here is a compile error, where a cast or a set literal merely typed as
11-
* the union stays green and a runner's verdict is dropped as verdict-absent. This reader holds the
12-
* map rather than importing the kernel's, because `facades/capture.ts` pins its eager module
13-
* closure and `kernel/snapshot.ts` is not in it.
10+
* The two verdict names this host has to be able to speak: `state` decides whether a capture reads
11+
* as degraded, and `backend` names the recovery strategy in the warning line. Each map is keyed
12+
* against its kernel union, so a name added there without a key here is a compile error, where a set
13+
* literal merely typed as the union stays green and a runner's verdict is dropped as
14+
* verdict-absent. The maps live here rather than behind a kernel import because
15+
* `facades/capture.ts` pins its eager module closure and `kernel/snapshot.ts` is not in it.
1416
*/
15-
const snapshotQualityStatesAreTheVocabulary: Record<SnapshotQualityState, true> = {
17+
const DECLARED_STATES: Record<SnapshotQualityState, true> = {
1618
healthy: true,
1719
recovered: true,
1820
sparse: true,
1921
};
22+
const DECLARED_BACKENDS: Record<SnapshotCaptureBackend, true> = {
23+
tree: true,
24+
queries: true,
25+
'private-ax': true,
26+
'android-helper': true,
27+
};
2028

2129
export type SnapshotCaptureAnalysis = {
2230
rawNodeCount: number;
@@ -105,18 +113,30 @@ function readTargetActivation(value: unknown): IosTargetActivation | undefined {
105113
: undefined;
106114
}
107115

116+
/**
117+
* Re-read of a fact this module published, in the shape `readTargetActivation` above also uses: the
118+
* two names that decide presentation are checked, and the verdict is forwarded as published. Reading
119+
* an untrusted runner payload is capture-kit's `readSnapshotQualityVerdict`, which normalizes every
120+
* field; this one cannot share that code (the eager-closure gate freezes both readers' module
121+
* closures, and the duplication gate refuses a second normalization), so the pair is pinned together
122+
* by `snapshot-quality-verdict.test.ts`. What stays guaranteed here is the part only this boundary
123+
* can check: a name this version cannot speak reads as verdict-absent, so a version-skewed runner
124+
* cannot hand the host a degradation it would present under a state or strategy nobody declared.
125+
*/
108126
function readSnapshotQualityVerdict(value: unknown): SnapshotQualityVerdict | undefined {
109127
if (!value || typeof value !== 'object') return undefined;
110128
const raw = value as Record<string, unknown>;
111-
// `state` decides whether a capture reads as degraded, so it goes through the declared
112-
// vocabulary instead of a cast: this reader sees whatever a runner or an older daemon put on the
113-
// wire, and a state it cannot name must read as verdict-absent.
114-
if (!isSnapshotQualityState(raw.state) || typeof raw.backend !== 'string') return undefined;
129+
if (!isDeclared(DECLARED_STATES, raw.state) || !isDeclared(DECLARED_BACKENDS, raw.backend)) {
130+
return undefined;
131+
}
115132
return raw as SnapshotQualityVerdict;
116133
}
117134

118-
function isSnapshotQualityState(value: unknown): value is SnapshotQualityState {
119-
return typeof value === 'string' && Object.hasOwn(snapshotQualityStatesAreTheVocabulary, value);
135+
function isDeclared<Key extends string, Value>(
136+
vocabulary: Record<Key, Value>,
137+
value: unknown,
138+
): value is Key {
139+
return typeof value === 'string' && Object.hasOwn(vocabulary, value);
120140
}
121141

122142
function readObject(value: unknown): Record<string, unknown> | undefined {

‎packages/kernel/src/snapshot-quality-states.test.ts‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,12 +20,13 @@ function readSnapshotQualityStatesFixture(): string[] {
2020

2121
/**
2222
* The tuple's own claim, stated on `SNAPSHOT_QUALITY_STATES`: the fixture is its wire vocabulary,
23-
* and the runner's `SnapshotQualityState.allCases` is pinned to the same file by a unit test.
23+
* and the runner's `SnapshotQualityState.allCases` is pinned to the same file by a unit test. As a
24+
* set: the names are the contract, and a reordering breaks no verdict anywhere.
2425
*/
2526
test('the declared verdict states are the shared wire vocabulary', () => {
2627
assert.deepEqual(
27-
readSnapshotQualityStatesFixture(),
28-
[...SNAPSHOT_QUALITY_STATES],
28+
new Set(readSnapshotQualityStatesFixture()),
29+
new Set(SNAPSHOT_QUALITY_STATES),
2930
'update the fixture and the Swift enum together with the tuple',
3031
);
3132
});

‎packages/kernel/src/snapshot.ts‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@
44
*
55
* Defined here (the foundational snapshot type module) rather than in
66
* capture-kit's snapshot-quality-verdict.ts so SnapshotNode can reference it without a cyclic
7-
* import; that module owns reading a verdict off the wire, and the vocabularies below are the
8-
* states and strategies it admits.
7+
* import. Ownership splits three ways: this module owns the vocabularies below, capture-kit parses
8+
* an untrusted runner payload into them, and contracts re-hydrates a verdict this repo published.
99
*/
1010
/**
1111
* Which capture STRATEGY produced a snapshot, within one platform's plan —
@@ -28,11 +28,10 @@ export type SnapshotQualityTiming = {
2828
* The verdict states a capture plan may stamp. This tuple is the ONE declaration of that
2929
* vocabulary, and `SnapshotQualityVerdict['state']` is its projection; readers hold exhaustive maps
3030
* over the union rather than importing this module, because the eager-closure gate freezes their
31-
* loading shape. Its order is the order of
32-
* `contracts/fixtures/ios-snapshot-quality-states.json`, which this module and the Apple runner's
33-
* `SnapshotQualityState.allCases` are pinned to positionally, so a state one side renames or adds
34-
* without the other goes red there instead of arriving as a verdict the host cannot name — which
35-
* reads as verdict-absent and drops the disclosure with it.
31+
* loading shape. This tuple and the Apple runner's `SnapshotQualityState.allCases` are each pinned
32+
* to `contracts/fixtures/ios-snapshot-quality-states.json` as a set, so a state one side renames,
33+
* adds, or deletes without the other goes red there instead of arriving as a verdict the host
34+
* cannot name — which reads as verdict-absent and drops the disclosure with it.
3635
*/
3736
export const SNAPSHOT_QUALITY_STATES = ['healthy', 'recovered', 'sparse'] as const;
3837

0 commit comments

Comments
 (0)