Skip to content

Commit 0f7a41b

Browse files
committed
fix: reconcile divergence ref selection with #1257 ADR-0014 partial ref frame
Rebase reconciliation. #1257 (ADR-0014 session ref-frame lifetime) landed on main and changed captureDivergenceObservation to activate a PARTIAL ref frame (markSessionPartialRefsIssued) authorizing exactly the divergence screen's emitted refs — computing that "digestBodies" set with its own document-order, non-covered-only filter. My #1264 change made buildReplayDivergenceScreenRefs emit a DIFFERENT set (ranked, occlusion-fallback, meaningful-filtered), so the authorized frame would no longer match the shown screen: in the mass-covered fallback the screen surfaces covered refs that #1257's non-covered-only frame filter excluded, leaving the agent a ref the screen advertised but the frame rejects. Extract selectDivergenceScreenRefNodes as the single source of truth for which nodes screen.refs publishes and in what order. Both the rendered digest (buildReplayDivergenceScreenRefs) and the partial-frame authorization (captureDivergenceObservation -> markSessionPartialRefsIssued) derive from it, so the frame authorizes exactly the emitted set — preserving BOTH #1257's ADR-0014 intent and #1264's ranking/occlusion intent. Also refresh the captureDivergenceObservation doc to the partial-frame sequence. Test: assert the partial ref frame scope (session.refFrameScope) equals the emitted screen.refs set in the mass-covered fallback (covered refs included) — verified to fail on #1257's original non-covered-only digestBodies. Refs #1264 #1257
1 parent 76b0fbd commit 0f7a41b

2 files changed

Lines changed: 98 additions & 23 deletions

File tree

‎src/daemon/handlers/__tests__/session-replay-divergence.test.ts‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -828,6 +828,62 @@ test('buildReplayFailureDivergence: a mass-covered app with no actionable overla
828828
expect(screen.refs.some((ref) => ref.label === 'Field A')).toBe(true);
829829
});
830830

831+
// #1257 + #1264 reconciliation: the ADR-0014 partial ref frame the divergence
832+
// capture activates (`markSessionPartialRefsIssued`) must authorize EXACTLY the
833+
// refs the `screen.refs` digest renders — both now derive from the shared
834+
// `selectDivergenceScreenRefNodes`. This is load-bearing in the mass-covered
835+
// fallback: the screen surfaces COVERED refs, which #1257's original
836+
// non-covered-only `digestBodies` filter would have EXCLUDED from the frame —
837+
// leaving the agent a ref the screen advertised but the frame rejects. Assert
838+
// the frame scope equals the emitted screen ref set (covered refs included).
839+
test('buildReplayFailureDivergence: the partial ref frame authorizes exactly the emitted screen.refs, including mass-covered fallback refs (#1257 + #1264)', async () => {
840+
const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-device-replay-divergence-frame-'));
841+
const sessionStore = new SessionStore(path.join(root, 'sessions'));
842+
const sessionName = 'default';
843+
const appBundleId = 'com.callstack.agentdevicelab';
844+
sessionStore.set(sessionName, makeAndroidSession(sessionName, { appBundleId }));
845+
846+
mockDispatchCommand.mockReset();
847+
mockDispatchCommand.mockResolvedValue({
848+
nodes: bareScrimMassCoveringApp(appBundleId),
849+
truncated: false,
850+
backend: 'android',
851+
});
852+
853+
const action = {
854+
ts: 0,
855+
command: 'press',
856+
positionals: ['label="Field A"'],
857+
flags: {},
858+
result: { selectorChain: ['label="Field A"'] },
859+
};
860+
const divergence = await buildReplayFailureDivergence({
861+
error: { code: 'COMMAND_FAILED', message: 'not hittable' },
862+
action,
863+
index: 0,
864+
sourcePath: path.join(root, 'flow.ad'),
865+
sourceLine: 1,
866+
session: sessionStore.get(sessionName),
867+
sessionName,
868+
sessionStore,
869+
logPath: path.join(root, 'daemon.log'),
870+
responseLevel: 'default',
871+
planActions: [action],
872+
planDigest: 'test-plan-digest',
873+
});
874+
875+
const screen = divergence.screen as Extract<typeof divergence.screen, { state: 'available' }>;
876+
const screenRefBodies = new Set(screen.refs.map((ref) => ref.ref));
877+
expect(screenRefBodies.size).toBeGreaterThan(0);
878+
879+
// The partial ref frame the capture activated authorizes exactly the emitted
880+
// screen refs — no more (no over-pin surface), no less (every advertised ref
881+
// is usable), even though every one of them is a `covered` node here.
882+
const stored = sessionStore.get(sessionName);
883+
expect(stored?.refFrameState).toBe('active');
884+
expect(stored?.refFrameScope).toEqual(screenRefBodies);
885+
});
886+
831887
// #1264 (capture parity, point 1): the divergence capture must go through the
832888
// SAME `captureSnapshot` wrapper as a plain `snapshot`, so it inherits Android
833889
// freshness + post-action retry. Otherwise a divergence could consume the first

‎src/daemon/handlers/session-replay-divergence.ts‎

Lines changed: 42 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -198,8 +198,10 @@ export function toReplayRepairHintCapture(
198198
}
199199

200200
/**
201-
* The single post-failure capture, blessed via the standard ref-issuing
202-
* sequence (setSessionSnapshot -> markSessionSnapshotRefsIssued -> store).
201+
* The single post-failure capture, blessed via the ADR-0014 partial ref-issuing
202+
* sequence (setSessionSnapshot -> markSessionPartialRefsIssued -> store): a
203+
* divergence screen publishes only its bounded ref set, so it activates a
204+
* PARTIAL frame authorizing exactly those bodies, not a complete namespace.
203205
* Sparse captures do not write back (selector-capture reliability contract),
204206
* so a sparse verdict degrades the whole observation.
205207
*
@@ -251,19 +253,17 @@ export async function captureDivergenceObservation(params: {
251253
};
252254
}
253255
setSessionSnapshot(session, snapshot);
254-
// ADR 0014: the divergence screen digest publishes only its capped,
255-
// non-covered, non-chrome refs — the same set `buildReplayDivergenceScreenRefs`
256-
// renders. Activate a PARTIAL frame authorizing exactly those bodies.
257-
const chromeRefs = collectSettleChromeRefs(snapshot.nodes, session.appBundleId);
258-
const digestBodies = snapshot.nodes
259-
.filter(
260-
(node) =>
261-
node.ref !== undefined &&
262-
node.interactionBlocked !== 'covered' &&
263-
!chromeRefs.has(node.ref),
264-
)
265-
.slice(0, SCREEN_REF_CAPTURE_LIMIT)
266-
.map((node) => node.ref as string);
256+
// ADR 0014 (#1257) + #1264: the divergence screen publishes exactly the
257+
// ranked, occlusion-resolved, capped ref set `screen.refs` renders. Activate
258+
// a PARTIAL frame authorizing precisely THOSE bodies — derived from the same
259+
// `selectDivergenceScreenRefNodes` the digest uses, so the frame never
260+
// authorizes a ref the screen hides (over-pin risk) nor rejects one the
261+
// screen advertised (e.g. the mass-covered fallback surfaces covered refs
262+
// that the old non-covered-only filter would have excluded here).
263+
const digestBodies = selectDivergenceScreenRefNodes(
264+
snapshot.nodes,
265+
session.appBundleId,
266+
).nodes.map((node) => node.ref as string);
267267
markSessionPartialRefsIssued(session, digestBodies);
268268
sessionStore.set(sessionName, session);
269269
return {
@@ -372,14 +372,20 @@ function isForeignOverlayDismissTarget(
372372
);
373373
}
374374

375-
function buildReplayDivergenceScreenRefs(
375+
/**
376+
* The single source of truth for which nodes a divergence `screen.refs`
377+
* publishes, and in what order. Both the rendered `screen.refs` digest
378+
* (`buildReplayDivergenceScreenRefs`) AND the ADR-0014 partial ref frame the
379+
* capture authorizes (`captureDivergenceObservation` →
380+
* `markSessionPartialRefsIssued`) derive from THIS function, so the authorized
381+
* ref set is exactly the set the agent is shown — never a superset it can pin
382+
* refs outside of, nor a subset that rejects a ref the screen advertised.
383+
* Returns the capped node list plus whether ranking overflowed the cap.
384+
*/
385+
function selectDivergenceScreenRefNodes(
376386
nodes: SnapshotNode[],
377-
sanitize: DivergenceFieldSanitizer,
378387
appBundleId: string | undefined,
379-
): {
380-
refs: ReplayDivergenceScreenRef[];
381-
truncated: boolean;
382-
} {
388+
): { nodes: SnapshotNode[]; truncated: boolean } {
383389
// Keyboard/IME chrome must not consume the ref budget: it reuses the exact
384390
// structural classifier `--settle`'s tail already relies on (#1198/#1200)
385391
// rather than a second keyboard/IME node-type list.
@@ -411,7 +417,20 @@ function buildReplayDivergenceScreenRefs(
411417
...pool.filter((node) => isForeignOverlayDismissTarget(node, appBundleId)),
412418
...pool.filter((node) => !isForeignOverlayDismissTarget(node, appBundleId)),
413419
];
414-
const refs = ranked.slice(0, SCREEN_REF_CAPTURE_LIMIT).map((node) => {
420+
const selected = ranked.slice(0, SCREEN_REF_CAPTURE_LIMIT);
421+
return { nodes: selected, truncated: ranked.length > selected.length };
422+
}
423+
424+
function buildReplayDivergenceScreenRefs(
425+
nodes: SnapshotNode[],
426+
sanitize: DivergenceFieldSanitizer,
427+
appBundleId: string | undefined,
428+
): {
429+
refs: ReplayDivergenceScreenRef[];
430+
truncated: boolean;
431+
} {
432+
const { nodes: selected, truncated } = selectDivergenceScreenRefNodes(nodes, appBundleId);
433+
const refs = selected.map((node) => {
415434
const role = formatRole(node.type ?? 'Element');
416435
const label = displayLabel(node, role);
417436
return {
@@ -420,7 +439,7 @@ function buildReplayDivergenceScreenRefs(
420439
...(label ? { label: sanitize(label) } : {}),
421440
};
422441
});
423-
return { refs, truncated: ranked.length > refs.length };
442+
return { refs, truncated };
424443
}
425444

426445
const BASIS_RANK: Record<ReplayDivergenceSuggestionBasis, number> = {

0 commit comments

Comments
 (0)