fix: reconcile Maestro runtime with merged contracts

Author: thymikee

src/compat/maestro/__tests__/runtime-target-policy.test.ts

@@ -14,14 +14,9 @@ test('typed Maestro text selectors match visible text and state without expressi
   ]).nodes[0]!;
 
   expect(
-    matchesMaestroTypedSelector(
-      node,
-      { text: '^Subtotal.*', enabled: true, selected: true },
-    ),
+    matchesMaestroTypedSelector(node, { text: '^Subtotal.*', enabled: true, selected: true }),
   ).toBe(true);
-  expect(matchesMaestroTypedSelector(node, { text: 'Subtotal', selected: false })).toBe(
-    false,
-  );
+  expect(matchesMaestroTypedSelector(node, { text: 'Subtotal', selected: false })).toBe(false);
 });
 
 test('typed Maestro id and label selectors keep their primary field semantics', () => {

src/compat/maestro/__tests__/runtime-target-ranking.test.ts

@@ -19,13 +19,7 @@ test('target ranking promotes actionable controls over matching static text', ()
   ]);
 
   expect(
-    selectMaestroSnapshotMatch(
-      snapshot.nodes,
-      snapshot.nodes,
-      undefined,
-      'Save',
-      IOS_TAB_FRAME,
-    ),
+    selectMaestroSnapshotMatch(snapshot.nodes, snapshot.nodes, undefined, 'Save', IOS_TAB_FRAME),
   ).toMatchObject({ node: { index: 2 } });
 });
 

src/compat/maestro/daemon-runtime-port-support.ts

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import type { NormalizedGestureInput } from '../../contracts/gesture-normalization.ts';
+import type { GestureSemanticInput } from '../../contracts/gesture-plan-types.ts';
 import type { CommandFlags } from '../../core/dispatch.ts';
 import type {
   DaemonInvokeFn,
@@ -68,7 +68,7 @@ export function launchArgumentValues(
 }
 
 export function publicGestureRequest(
-  input: NormalizedGestureInput,
+  input: GestureSemanticInput,
   context: MaestroRuntimeOperationContext,
 ): { command: 'gesture' | 'swipe'; input: Record<string, unknown> } {
   const endpoints = endpointGesture(input);
@@ -210,7 +210,7 @@ function daemonResponseError(response: Extract<DaemonResponse, { ok: false }>):
   return new AppError(error.code, error.message, Object.keys(details).length ? details : undefined);
 }
 
-function endpointGesture(input: NormalizedGestureInput): Record<string, unknown> | undefined {
+function endpointGesture(input: GestureSemanticInput): Record<string, unknown> | undefined {
   if (input.intent === 'fling' && 'from' in input) return { from: input.from, to: input.to };
   if (input.intent === 'pan' && !('preset' in input)) {
     return {

src/compat/maestro/runtime-port-geometry.ts

@@ -1,10 +1,7 @@
 import { AppError } from '../../kernel/errors.ts';
-import {
-  normalizePublicSwipeMotion,
-  type NormalizedGestureInput,
-} from '../../contracts/gesture-normalization.ts';
-import { clampToRange } from '../../contracts/scroll-gesture.ts';
-import { buildInPageSwipeGesturePlan } from '../../contracts/scroll-gesture.ts';
+import { normalizePublicSwipeMotion } from '../../contracts/gesture-normalization.ts';
+import type { GestureSemanticInput } from '../../contracts/gesture-plan-types.ts';
+import { buildInPageSwipeGesturePlan, clampToRange } from '../../contracts/scroll-gesture.ts';
 import { pointInsideRect } from '../../utils/rect-center.ts';
 import type { MaestroRuntimeRequest } from './engine-types.ts';
 import type { MaestroCoordinate, MaestroDirection, MaestroSwipeGesture } from './program-ir.ts';
@@ -109,14 +106,14 @@ function normalizedSwipeFromEndpoints(
   start: { x: number; y: number },
   end: { x: number; y: number },
   durationMs: number | undefined,
-): NormalizedGestureInput {
+): GestureSemanticInput {
   return normalizePublicSwipeMotion({ from: start, to: end, durationMs }).gesture;
 }
 
 function normalizedScreenHorizontalSwipe(
   direction: Extract<MaestroDirection, 'left' | 'right'>,
   durationMs: number | undefined,
-): NormalizedGestureInput {
+): GestureSemanticInput {
   const preset = direction;
   return durationMs === undefined
     ? { intent: 'fling', preset }
@@ -128,7 +125,7 @@ function normalizedScreenVerticalSwipe(
   start: { x: number; y: number },
   end: { x: number; y: number },
   durationMs: number | undefined,
-): NormalizedGestureInput {
+): GestureSemanticInput {
   if (durationMs !== undefined) return normalizedSwipeFromEndpoints(start, end, durationMs);
   return {
     intent: 'fling',

src/compat/maestro/runtime-port-types.ts

@@ -1,4 +1,4 @@
-import type { NormalizedGestureInput } from '../../contracts/gesture-normalization.ts';
+import type { GestureSemanticInput } from '../../contracts/gesture-plan-types.ts';
 import type { Point, Rect } from '../../kernel/snapshot.ts';
 import type {
   MaestroDirection,
@@ -63,7 +63,7 @@ export type MaestroSwipeOperation = {
   /** The authored Maestro coordinate space and target mode, preserved for policy and diagnostics. */
   readonly authored: MaestroSwipeGesture;
   /** The normalized contract consumed by the shared input runtime. */
-  readonly gesture: NormalizedGestureInput;
+  readonly gesture: GestureSemanticInput;
   readonly target?: MaestroTargetResolution;
   readonly viewport?: Rect;
 };
@@ -117,7 +117,7 @@ export type MaestroRuntimeOperations = {
     readonly delay?: number;
   }>;
   readonly longPressOn: MaestroRuntimeOperation<{ readonly target: MaestroInputTarget }>;
-  readonly gesture: MaestroRuntimeOperation<NormalizedGestureInput>;
+  readonly gesture: MaestroRuntimeOperation<GestureSemanticInput>;
   readonly inputText: MaestroRuntimeOperation<{ readonly text: string; readonly label?: string }>;
   readonly eraseText: MaestroRuntimeOperation<{ readonly charactersToErase?: number }>;
   readonly pasteText: MaestroRuntimeOperation<{ readonly text: string }>;

src/daemon/handlers/__tests__/session-replay-vars.test.ts

@@ -1889,10 +1889,11 @@ test('runReplayScriptFile propagates Maestro runFlow.when runtime errors', async
     assert.equal(response.error.code, 'REPLAY_DIVERGENCE');
     assert.match(response.error.message, /fetch failed/);
     const divergence = response.error.details?.divergence as
-      | { cause: { code: string; message: string } }
+      | { cause: { code: string; message: string }; repairHint: string }
       | undefined;
     assert.equal(divergence?.cause.code, 'UNKNOWN');
     assert.match(divergence?.cause.message ?? '', /fetch failed/);
+    assert.equal(divergence?.repairHint, 'manual');
   }
 });
 

src/daemon/handlers/session-replay-maestro-failure.ts

@@ -18,7 +18,9 @@ import {
   buildDivergenceScreen,
   captureDivergenceObservation,
   collectReplayDivergenceSuggestions,
+  toReplayRepairHintCapture,
 } from './session-replay-divergence.ts';
+import { computeReplayRepairHint } from './session-replay-repair-hint.ts';
 import {
   buildReplayDivergenceFailureResponseFromDescriptor,
   hoistReplayFailureCauseDiagnosticMeta,
@@ -104,6 +106,11 @@ export async function buildTypedMaestroFailureResponse(params: {
           planDigest: plan.digest,
           reason: resume.reason,
         },
+    repairHint: computeReplayRepairHint({
+      kind: 'action-failure',
+      targetEvidence: diagnosticAction.targetEvidence,
+      capture: toReplayRepairHintCapture(observation),
+    }),
   };
   const bounded = boundReplayDivergenceForSession({
     sessionStore,
@@ -125,10 +132,7 @@ export async function buildTypedMaestroFailureResponse(params: {
   });
 }
 
-function diagnosticActionForEvent(
-  event: MaestroEngineEvent,
-  req: DaemonRequest,
-): SessionAction {
+function diagnosticActionForEvent(event: MaestroEngineEvent, req: DaemonRequest): SessionAction {
   const progress = formatMaestroCommandProgress(event.command);
   const command = diagnosticCommand(event.command.kind);
   return {
@@ -158,9 +162,7 @@ function safeProgressPositionals(command: string, value: string | undefined): st
   return [value];
 }
 
-function collectExpandedScrubVars(
-  values: Readonly<Record<string, string>>,
-): ReplayVarScrubEntry[] {
+function collectExpandedScrubVars(values: Readonly<Record<string, string>>): ReplayVarScrubEntry[] {
   return Object.entries(values)
     .filter(([, value]) => value.length > 0)
     .map(([name, value]) => ({ name, value }))

src/daemon/handlers/session-replay-runtime.ts

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import path from 'node:path';
 import { parseReplayInput } from '../../compat/replay-input.ts';
 import { asAppError } from '../../kernel/errors.ts';
 import type { DaemonInvokeFn, DaemonRequest, DaemonResponse, SessionAction } from '../types.ts';