fix(ios): serve a simulator recording whose recorder died with its daemon (#2736)

* fix(ios): serve a simulator recording whose recorder died with its daemon

A simctl reattach answered `missing` as soon as the recorder process was gone,
which is the ordinary state after daemon loss, so a retried `record stop` threw
`resource-missing` forever even with the recorder's video on disk. The simctl
descriptor now carries the caller-facing export coordinates, so a proven-gone
recorder whose file still passes the container sniff reattaches as a handle that
runs the same stop-and-export sequence the live recording would have run, and
discloses the touch overlay whose events did not survive the daemon.

A manifest written without those coordinates is answered exactly as it was
before, because it cannot name an export it never recorded.

* fix(ios): resume a recovered simulator export from what the first stop journaled

A recorder that died with its daemon proved nothing about the export its file can
still become, and neither did a manifest whose stop had already collected a copy or
journaled a finalization. Reattach decided from the recorder's own path alone, so a
retry after those steps found no file there and reported a loss the manifest
contradicted. It now asks what a resumed stop would still have to read, which the
shared stop sequence answers from the checkpoints the first attempt wrote.

The coordinates a recovered export needs are the caller-facing keys of the live
snapshot, so the facet is a Pick of it, encoded and restored by spread, and validated
by the recording-facts validator Android's descriptor already needed — moved to
capture-kit so both backends answer with the same strictness. A recovered handle
refuses an overlay whose gesture events died with the daemon instead of running the
overlay pass with nothing to burn in and then reporting it unavailable.

* chore(gates): declare the capture-kit recording-facts subpath in the boundary enumeration

Author: thymikee

packages/capture-kit/package.json

@@ -166,6 +166,10 @@
       "types": "./src/recording/artifact.fixtures.ts",
       "default": "./src/recording/artifact.fixtures.ts"
     },
+    "./recording-facts": {
+      "types": "./src/recording/recording-facts.ts",
+      "default": "./src/recording/recording-facts.ts"
+    },
     "./recording-mp4-fixtures": {
       "types": "./src/recording/mp4.fixtures.ts",
       "default": "./src/recording/mp4.fixtures.ts"

packages/capture-kit/src/recording/recording-facts.test.ts

@@ -0,0 +1,47 @@
+import assert from 'node:assert/strict';
+import { test } from 'vitest';
+import { RECORDING_FACTS_KEYS, recordingFactsAreValid } from './recording-facts.ts';
+
+const FACTS = Object.freeze({
+  scope: 'device',
+  showTouches: true,
+  recordOnlySession: false,
+});
+
+function facet(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+  return { ...FACTS, ...overrides };
+}
+
+test('accepts the facts a caller asked for, with or without the optional ones', () => {
+  assert.equal(recordingFactsAreValid(facet()), true);
+  assert.equal(
+    recordingFactsAreValid(
+      facet({ activeSessionApp: { bundleId: 'com.example.app', name: 'Example' } }),
+    ),
+    true,
+  );
+  assert.equal(recordingFactsAreValid(facet({ exportQuality: 'high' })), true);
+});
+
+test('refuses a facet whose recording facts no start could have produced', () => {
+  assert.equal(recordingFactsAreValid(facet({ scope: 'window' })), false);
+  assert.equal(recordingFactsAreValid(facet({ showTouches: 'yes' })), false);
+  assert.equal(recordingFactsAreValid(facet({ recordOnlySession: 1 })), false);
+  assert.equal(recordingFactsAreValid({ ...FACTS, showTouches: undefined }), false);
+});
+
+test('refuses an optional fact that is present but unreadable rather than dropping it', () => {
+  assert.equal(recordingFactsAreValid(facet({ exportQuality: 'ultra' })), false);
+  assert.equal(recordingFactsAreValid(facet({ activeSessionApp: { bundleId: '' } })), false);
+  assert.equal(recordingFactsAreValid(facet({ activeSessionApp: { name: 'Example' } })), false);
+  assert.equal(recordingFactsAreValid(facet({ activeSessionApp: 'com.example.app' })), false);
+  assert.equal(
+    recordingFactsAreValid(facet({ activeSessionApp: { bundleId: 'a', name: '' } })),
+    false,
+  );
+});
+
+test('names every key of the facet it validates', () => {
+  const declared = Object.keys({ ...FACTS, activeSessionApp: undefined, exportQuality: undefined });
+  assert.deepEqual([...RECORDING_FACTS_KEYS].sort(), declared.sort());
+});

packages/capture-kit/src/recording/recording-facts.ts

@@ -0,0 +1,56 @@
+import {
+  isRecordingExportQuality,
+  isRecordingScope,
+  type RecordingAppIdentity,
+  type RecordingExportQuality,
+  type RecordingScope,
+} from '@agent-device/contracts/recording';
+import { isRecord } from '@agent-device/kernel/record';
+
+/**
+ * What a durable recording keeps about what its caller asked for, apart from where its files live
+ * (ADR 0024 2.3). Every backend's descriptor carries these facts because the export it owes the
+ * caller is described by them, so one validator decides whether a manifest's copy can be trusted
+ * rather than each backend inventing its own strictness.
+ */
+export type RecordingFacts = Readonly<{
+  scope: RecordingScope;
+  showTouches: boolean;
+  recordOnlySession: boolean;
+  activeSessionApp?: RecordingAppIdentity;
+  exportQuality?: RecordingExportQuality;
+}>;
+
+/** The keys of {@link RecordingFacts}, so a backend carries the facet without naming it twice. */
+export const RECORDING_FACTS_KEYS = [
+  'scope',
+  'showTouches',
+  'recordOnlySession',
+  'activeSessionApp',
+  'exportQuality',
+] as const satisfies readonly (keyof RecordingFacts)[];
+
+/**
+ * Whether a durable value carries whole recording facts. One unreadable field refuses the whole
+ * facet: a resumed stop that trusted half an overlay request would serve a video the caller never
+ * asked for, which is the failure an unreadable descriptor is supposed to prevent.
+ */
+export function recordingFactsAreValid(value: Record<string, unknown>): value is RecordingFacts {
+  return (
+    isRecordingScope(value.scope) &&
+    typeof value.showTouches === 'boolean' &&
+    typeof value.recordOnlySession === 'boolean' &&
+    (value.exportQuality === undefined || isRecordingExportQuality(value.exportQuality)) &&
+    isOptionalAppIdentity(value.activeSessionApp)
+  );
+}
+
+function isOptionalAppIdentity(value: unknown): value is RecordingAppIdentity | undefined {
+  if (value === undefined) return true;
+  if (!isRecord(value) || !isNonemptyText(value.bundleId)) return false;
+  return value.name === undefined || isNonemptyText(value.name);
+}
+
+function isNonemptyText(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0;
+}

packages/capture-kit/src/recording/stop-sequence.ts

@@ -15,6 +15,13 @@ import { readStopCheckpoints, writeStopCheckpoint } from './stop-checkpoints.ts'
 /** Where a recorder writes when its file must stay separate from the export (ADR 0024 2.3). */
 export { collectedRecordingPath, nativeRecordingPath } from './artifact-paths.ts';
 
+/**
+ * What an earlier attempt of this stop journaled. A backend deciding whether a lost recording is still
+ * recoverable reads the same checkpoints this sequence resumes from, so the two cannot disagree about
+ * what a retry would still have to do.
+ */
+export { readStopCheckpoints } from './stop-checkpoints.ts';
+
 /** What a backend learned while asking its recorder to stop (ADR 0024 2.2). */
 export type RecorderStop = Readonly<{
   observation: StopObservation;

packages/platform-android/src/recording/manifest-validation.ts

@@ -1,4 +1,5 @@
 import { isNativePathDisposition } from '@agent-device/contracts/recording-native-path';
+import { recordingFactsAreValid } from '@agent-device/capture-kit/recording-facts';
 import { isStopObservation } from '@agent-device/contracts/recording-stop-observation';
 import type {
   ScreenRecordingChunk,
@@ -53,20 +54,11 @@ function descriptorIdentityIsValid(value: Record<string, unknown>): boolean {
 }
 
 function descriptorRecordingIsValid(value: Record<string, unknown>): boolean {
-  return (
-    (value.clientOutputPath === undefined || typeof value.clientOutputPath === 'string') &&
-    isScope(value.scope) &&
-    typeof value.showTouches === 'boolean' &&
-    typeof value.recordOnlySession === 'boolean'
-  );
+  return isOptionalText(value.clientOutputPath) && recordingFactsAreValid(value);
 }
 
 function descriptorOptionsAreValid(value: Record<string, unknown>): boolean {
-  return (
-    isTransportMode(value.transportMode) &&
-    isOptionalQuality(value.exportQuality) &&
-    isOptionalApp(value.activeSessionApp)
-  );
+  return isTransportMode(value.transportMode);
 }
 
 function manifestIdentityIsValid(candidate: Partial<NativeManifest>): boolean {
@@ -84,17 +76,13 @@ function manifestIdentityIsValid(candidate: Partial<NativeManifest>): boolean {
 function manifestRecordingIsValid(candidate: Partial<NativeManifest>): boolean {
   return (
     typeof candidate.outputPath === 'string' &&
-    (candidate.clientOutputPath === undefined || typeof candidate.clientOutputPath === 'string') &&
-    isScope(candidate.scope) &&
-    typeof candidate.showTouches === 'boolean' &&
-    typeof candidate.recordOnlySession === 'boolean'
+    isOptionalText(candidate.clientOutputPath) &&
+    recordingFactsAreValid(candidate)
   );
 }
 
 function manifestOptionsAreValid(candidate: Partial<NativeManifest>): boolean {
   return (
-    isOptionalApp(candidate.activeSessionApp) &&
-    isOptionalQuality(candidate.exportQuality) &&
     isTransportMode(candidate.transportMode) &&
     (candidate.pendingRemotePath === undefined ||
       isNativeRecordingPath(candidate.pendingRemotePath))
@@ -153,12 +141,7 @@ function completionIdentityIsValid(candidate: Partial<ScreenRecordingCompletion>
 }
 
 function completionRecordingIsValid(candidate: Partial<ScreenRecordingCompletion>): boolean {
-  return (
-    isScope(candidate.scope) &&
-    typeof candidate.showTouches === 'boolean' &&
-    typeof candidate.recordOnlySession === 'boolean' &&
-    isOptionalApp(candidate.activeSessionApp)
-  );
+  return recordingFactsAreValid(candidate);
 }
 
 function isValidCompletionChunk(chunk: ScreenRecordingChunk, index: number): boolean {
@@ -229,25 +212,12 @@ function isObject(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null;
 }
 
-function isScope(value: unknown): value is 'app' | 'device' | 'system' {
-  return value === 'app' || value === 'device' || value === 'system';
-}
-
 function isTransportMode(value: unknown): value is AndroidRecordingDescriptor['transportMode'] {
   return value === 'local' || value === 'transport-composed';
 }
 
-function isOptionalQuality(value: unknown): boolean {
-  return value === undefined || value === 'medium' || value === 'high';
-}
-
-function isOptionalApp(value: unknown): boolean {
-  return (
-    value === undefined ||
-    (isObject(value) &&
-      typeof value.bundleId === 'string' &&
-      (value.name === undefined || typeof value.name === 'string'))
-  );
+function isOptionalText(value: unknown): value is string | undefined {
+  return value === undefined || typeof value === 'string';
 }
 
 function isNativeRecordingPath(value: unknown): value is string {

packages/platform-apple/src/recording/completion.ts

@@ -63,6 +63,10 @@ export async function completeAppleRecording(params: {
  * Turns the copy a stop collected into the export, and answers what became of the recorder's own
  * file (ADR 0024 2.3). The recorder's file is never finalized in place: the overlay and the telemetry
  * land on the export, and the recorder's file is retired only once that export exists.
+ *
+ * `overlayUnavailable` names a reason the caller was promised an overlay this export cannot carry,
+ * which is refused on the way in and disclosed on the way out rather than attempted with nothing to
+ * burn in and then apologised for.
  */
 export async function finalizeAppleRecordingFromCollected(
   params: Readonly<{
@@ -72,6 +76,7 @@ export async function finalizeAppleRecordingFromCollected(
     collectedPath: string;
     exportPath: string;
     nativePath: string;
+    overlayUnavailable?: string;
   }>,
 ): Promise<ScreenRecordingFinalization> {
   const { host, snapshot, targetLabel, collectedPath, exportPath, nativePath } = params;
@@ -80,13 +85,14 @@ export async function finalizeAppleRecordingFromCollected(
   if (snapshot.invalidatedReason && !snapshot.showTouches) {
     throw new Error(`recording invalidated: ${snapshot.invalidatedReason}`);
   }
+  const overlayUnavailability = params.overlayUnavailable ?? snapshot.invalidatedReason;
   let finalization: Awaited<ReturnType<typeof host.screenRecording.finalize.complete>>;
   try {
     await host.screenRecording.outputs.copy({ from: collectedPath, to: exportPath });
     finalization = await asAppErrorAsync(() =>
       host.screenRecording.finalize.complete({
         outputPath: exportPath,
-        showTouches: snapshot.invalidatedReason ? false : snapshot.showTouches,
+        showTouches: overlayUnavailability === undefined && snapshot.showTouches,
         gestureEvents: snapshot.gestureEvents,
         exportQuality: snapshot.exportQuality ?? 'medium',
         targetLabel,
@@ -99,9 +105,9 @@ export async function finalizeAppleRecordingFromCollected(
   }
   return {
     ...finalization,
-    ...(snapshot.invalidatedReason
-      ? { overlayWarning: `overlay unavailable: ${snapshot.invalidatedReason}` }
-      : {}),
+    ...(overlayUnavailability === undefined
+      ? {}
+      : { overlayWarning: `overlay unavailable: ${overlayUnavailability}` }),
     nativePathDisposition:
       (await host.screenRecording.outputs.remove(nativePath)) === 'removed'
         ? 'retired'