fix(ios): preserve snapshot fallback lineage

Author: thymikee

packages/capture-kit/src/ios-snapshot-planning.ts

@@ -190,6 +190,8 @@ function residueIdentity(residue: IosAcquisitionResidue): string {
         expected: residue.expected,
         observed: residue.observed,
       });
+    case 'unknown-generation':
+      return JSON.stringify({ kind: residue.kind, captureId: residue.captureId });
     case 'unavailable-fact':
       return JSON.stringify({ kind: residue.kind, fact: residue.fact });
     case 'fallback-source':

packages/contracts/src/ios-snapshot.ts

@@ -142,6 +142,10 @@ export type IosAcquisitionResidue =
       expected?: IosSnapshotGeneration;
       observed?: IosSnapshotGeneration;
     }>
+  | Readonly<{
+      kind: 'unknown-generation';
+      captureId: string;
+    }>
   | Readonly<{
       kind: 'unavailable-fact';
       fact: IosSnapshotFact;

packages/platform-apple/src/snapshot-route.test.ts

@@ -1,5 +1,6 @@
 import { expect, test, vi } from 'vitest';
 import type { DeviceInfo } from '@agent-device/kernel/device';
+import { areIosSnapshotComparisonIdentitiesEqual } from '@agent-device/capture-kit/ios-snapshot-planning';
 import { platformRuntimeHostFixture } from './runtime.fixtures.ts';
 import { createAppleSnapshotRoute } from './snapshot-route.ts';
 import type { SimulatorSnapshotSource, SnapshotSourceOutcome } from './snapshot-source-facade.ts';
@@ -81,7 +82,7 @@ test('typed bridge failure falls back once and disables retries for that app gen
 test('a new app generation re-enables the bridge', async () => {
   const source = sourceReturning({
     stage: 'failed',
-    failure: { kind: 'stale-target', code: 'target-generation-changed' },
+    failure: { kind: 'transport-failure', code: 'bridge-disconnected' },
   });
   const resolveTarget = vi
     .fn()
@@ -101,6 +102,27 @@ test('a new app generation re-enables the bridge', async () => {
   expect(source.acquire).toHaveBeenCalledTimes(2);
 });
 
+test('stale bridge acquisition resolves the current generation before XCTest fallback', async () => {
+  const currentTarget = { ...target, pid: 84, generation: '84:launch-b' };
+  const source = sourceReturning({
+    stage: 'failed',
+    failure: { kind: 'stale-target', code: 'target-generation-changed' },
+  });
+  const resolveTarget = vi.fn().mockResolvedValueOnce(target).mockResolvedValueOnce(currentTarget);
+  const route = createAppleSnapshotRoute(platformRuntimeHostFixture(), {
+    source,
+    resolveTarget,
+  });
+
+  const result = await route.capture(ios, input, signal(), async () => runnerResult());
+
+  expect(resolveTarget).toHaveBeenCalledTimes(2);
+  expect(result.comparisonIdentity?.lineage).toEqual({
+    targetId: currentTarget.targetId,
+    generation: currentTarget.generation,
+  });
+});
+
 test('target-resolution fallback remains incomparable with a bridge publication', async () => {
   const source = sourceReturning(bridgeAcquisition());
   const fallback = vi.fn(async () => runnerResult());
@@ -117,8 +139,29 @@ test('target-resolution fallback remains incomparable with a bridge publication'
   expect(result.comparisonIdentity).toMatchObject({
     producer: 'apple-runner',
     lineage: { targetId: target.targetId },
-    residue: [{ kind: 'fallback-source', producer: 'apple-runner' }],
+    residue: [
+      { kind: 'unknown-generation', captureId: expect.any(String) },
+      { kind: 'fallback-source', producer: 'apple-runner' },
+    ],
+  });
+});
+
+test('two target-resolution fallbacks cannot share comparison identity', async () => {
+  const route = createAppleSnapshotRoute(platformRuntimeHostFixture(), {
+    source: sourceReturning(bridgeAcquisition()),
+    resolveTarget: vi.fn(async () => {
+      throw new Error('launch job unavailable');
+    }),
   });
+
+  const first = await route.capture(ios, input, signal(), async () => runnerResult());
+  const second = await route.capture(ios, input, signal(), async () => runnerResult());
+
+  expect(first.comparisonIdentity).toBeDefined();
+  expect(second.comparisonIdentity).toBeDefined();
+  expect(
+    areIosSnapshotComparisonIdentitiesEqual(first.comparisonIdentity!, second.comparisonIdentity!),
+  ).toBe(false);
 });
 
 test('runtime shutdown closes the process-owned bridge source', async () => {

packages/platform-apple/src/snapshot-route.ts

@@ -1,10 +1,12 @@
+import { randomUUID } from 'node:crypto';
 import type { PlatformRuntimeHost } from '@agent-device/contracts/platform-runtime-operations';
 import type {
   CaptureSnapshotInput,
   SnapshotResult,
   SnapshotRuntimeAcquiredResult,
 } from '@agent-device/contracts/snapshot-runtime';
 import type {
+  IosAcquisitionResidue,
   IosSnapshotComparisonIdentity,
   IosSnapshotLineage,
 } from '@agent-device/contracts/ios-snapshot';
@@ -55,13 +57,15 @@ export function createAppleSnapshotRoute(
       try {
         target = await resolveTarget(device, input.options!.appBundleId!, signal);
       } catch (error) {
+        signal.throwIfAborted();
         emitRouteDiagnostic('target-resolution-failed', device, undefined, error);
         return await runFallback(
           input,
           fallback,
           { targetId: `${device.id}:${input.options!.appBundleId!}` },
           requestFor(input),
           'target-resolution-failed',
+          [unknownGenerationResidue()],
         );
       }
       rebaselineGeneration(target, latestGeneration, disabledGenerations);
@@ -84,10 +88,19 @@ export function createAppleSnapshotRoute(
             ...outcome.failure.details,
           });
         }
+        const fallbackIdentity = await resolveFailureFallbackIdentity(
+          outcome.failure,
+          target,
+          device,
+          input.options!.appBundleId!,
+          signal,
+          resolveTarget,
+        );
         return await fallbackAfterFailure(
           input,
           fallback,
           target,
+          fallbackIdentity,
           request,
           outcome.failure,
           disabledGenerations,
@@ -108,6 +121,7 @@ export function createAppleSnapshotRoute(
           input,
           fallback,
           target,
+          { lineage: target, residue: [] },
           request,
           { kind: 'malformed-tree', code: 'presentation-invariant' },
           disabledGenerations,
@@ -132,15 +146,29 @@ function isEligible(device: DeviceInfo, input: CaptureSnapshotInput): boolean {
 async function fallbackAfterFailure(
   input: CaptureSnapshotInput,
   fallback: SnapshotFallback,
-  target: SimulatorSnapshotTarget,
+  failedTarget: SimulatorSnapshotTarget,
+  identity: FallbackIdentity,
   request: ReturnType<typeof createIosSnapshotRequest>,
   failure: SnapshotSourceFailure,
   disabledGenerations: Set<string>,
   cause?: unknown,
 ): Promise<SnapshotResult> {
-  disabledGenerations.add(generationKey(target));
-  emitRouteDiagnostic(failure.code, { id: target.udid }, target.generation, cause, failure.details);
-  return await runFallback(input, fallback, target, request, failure.code);
+  disabledGenerations.add(generationKey(failedTarget));
+  emitRouteDiagnostic(
+    failure.code,
+    { id: failedTarget.udid },
+    failedTarget.generation,
+    cause,
+    failure.details,
+  );
+  return await runFallback(
+    input,
+    fallback,
+    identity.lineage,
+    request,
+    failure.code,
+    identity.residue,
+  );
 }
 
 async function runFallback(
@@ -149,23 +177,64 @@ async function runFallback(
   lineage: IosSnapshotLineage,
   request: ReturnType<typeof createIosSnapshotRequest>,
   reason: string,
+  residue: readonly IosAcquisitionResidue[] = [],
 ): Promise<SnapshotResult> {
   const result = await fallback(input);
   const comparisonIdentity: IosSnapshotComparisonIdentity = Object.freeze({
     producer: 'apple-runner',
     intent: request.acquisitionIntent,
-    lineage: Object.freeze({ ...lineage }),
+    lineage: Object.freeze({
+      ...(lineage.targetId ? { targetId: lineage.targetId } : {}),
+      ...(lineage.generation ? { generation: lineage.generation } : {}),
+    }),
     presentationKey: buildIosSnapshotPresentationKey(request),
-    residue: Object.freeze([{ kind: 'fallback-source', producer: 'apple-runner' } as const]),
+    residue: Object.freeze([
+      ...residue,
+      { kind: 'fallback-source', producer: 'apple-runner' } as const,
+    ]),
   });
-  const warning = `Simulator AX snapshot unavailable (${reason}); used XCTest for this app generation.`;
+  const generation = lineage.generation ? 'this app generation' : 'an unverified app generation';
+  const warning = `Simulator AX snapshot unavailable (${reason}); used XCTest for ${generation}.`;
   return {
     ...result,
     comparisonIdentity,
     warnings: [...(result.warnings ?? []), warning],
   };
 }
 
+type FallbackIdentity = Readonly<{
+  lineage: IosSnapshotLineage;
+  residue: readonly IosAcquisitionResidue[];
+}>;
+
+async function resolveFailureFallbackIdentity(
+  failure: SnapshotSourceFailure,
+  target: SimulatorSnapshotTarget,
+  device: DeviceInfo,
+  appBundleId: string,
+  signal: AbortSignal,
+  resolveTarget: typeof resolveSimulatorSnapshotTarget,
+): Promise<FallbackIdentity> {
+  if (failure.kind !== 'stale-target') return { lineage: target, residue: [] };
+  try {
+    return {
+      lineage: await resolveTarget(device, appBundleId, signal),
+      residue: [],
+    };
+  } catch (error) {
+    signal.throwIfAborted();
+    emitRouteDiagnostic('fallback-target-resolution-failed', device, undefined, error);
+    return {
+      lineage: { targetId: target.targetId },
+      residue: [unknownGenerationResidue()],
+    };
+  }
+}
+
+function unknownGenerationResidue(): IosAcquisitionResidue {
+  return { kind: 'unknown-generation', captureId: randomUUID() };
+}
+
 function requestFor(input: CaptureSnapshotInput) {
   return createIosSnapshotRequest({
     raw: input.options?.raw,

test/integration/ios-simulator-e2e/live-snapshot-depth-frontier.ts

@@ -6,6 +6,8 @@ import { type LiveContext, runStep, verifyBehavior } from './live-harness.ts';
 
 const VISIBLE_DEPTH_DEEP_LINK = 'agent-device-test-app:///snapshot-depth';
 const CHILD_ID = 'visible-depth-projected-child';
+const MISSING_HITTABILITY_WARNING =
+  'iOS snapshot acquisition does not provide hittability evidence; regular snapshots omit unverified hittability while raw snapshots preserve supplied facts.';
 
 type SnapshotNode = {
   depth?: unknown;
@@ -32,7 +34,7 @@ export async function assertRegularVisibleDepthFrontier(context: LiveContext): P
     '--depth',
     '1',
   ]);
-  assertSnapshotBackend(regular, 'regular depth-1 snapshot');
+  assertSimulatorBridgeSnapshot(regular, 'regular depth-1 snapshot');
   const regularNodes = snapshotNodes(regular);
   const regularRoot = requireRoot(regularNodes, 'regular depth-1 snapshot');
   const projectedChild = requireIdentifier(regularNodes, CHILD_ID, 'regular depth-1 snapshot');
@@ -55,7 +57,7 @@ export async function assertRegularVisibleDepthFrontier(context: LiveContext): P
     'snapshot',
     '--raw',
   ]);
-  assertSnapshotBackend(rawFull, 'full raw visible-depth snapshot');
+  assertSimulatorBridgeSnapshot(rawFull, 'full raw visible-depth snapshot');
   const rawFullNodes = snapshotNodes(rawFull);
   const rawChild = requireIdentifier(rawFullNodes, CHILD_ID, 'full raw visible-depth snapshot');
   assert.ok(
@@ -69,7 +71,7 @@ export async function assertRegularVisibleDepthFrontier(context: LiveContext): P
     '--depth',
     '1',
   ]);
-  assertSnapshotBackend(rawDepthOne, 'raw depth-1 visible-depth snapshot');
+  assertSimulatorBridgeSnapshot(rawDepthOne, 'raw depth-1 visible-depth snapshot');
   const rawDepthOneNodes = snapshotNodes(rawDepthOne);
   assert.equal(
     rawDepthOneNodes.some((node) => node.identifier === CHILD_ID),
@@ -127,10 +129,14 @@ function numericDepth(node: SnapshotNode): number {
   return node.depth as number;
 }
 
-function assertSnapshotBackend(result: { json?: any }, description: string): void {
+function assertSimulatorBridgeSnapshot(result: { json?: any }, description: string): void {
   assert.equal(
     result.json?.data?.snapshotQuality?.backend,
-    'tree',
-    `${description} must exercise the recursive tree backend: ${JSON.stringify(result)}`,
+    undefined,
+    `${description} must not carry XCTest tree quality metadata: ${JSON.stringify(result)}`,
+  );
+  assert.ok(
+    result.json?.data?.warnings?.includes(MISSING_HITTABILITY_WARNING),
+    `${description} must disclose the Simulator AX bridge evidence gap: ${JSON.stringify(result)}`,
   );
 }