@sublang/playbook 16.0.0 → 17.0.0

package/src/xstate-playbook-runtime.ts

@@ -66,6 +66,8 @@ import type {
   PlaybookEffectLogicalOperation,
   PlaybookFailureCause,
   PlaybookPendingBossQuestion,
+  PlaybookPendingCall,
+  PlaybookStepRecord,
   PlaybookPorts,
   PlaybookRepositoryReceipt,
   PlaybookRunResult,
@@ -544,6 +546,11 @@ interface XStateRepositoryCohortResult<T> {
 }
 
 export interface XStateRepositoryCapability {
+  observe?(): Promise<PlaybookRepositoryReceipt['baseline']>;
+  acquire?(options: { readonly signal: AbortSignal }): Promise<{
+    assertOwner(): Promise<void>;
+    release(): Promise<void>;
+  }>;
   runExclusive<T>(options: {
     readonly signal: AbortSignal;
     readonly effectBoundary: XStateEffectBoundarySeed;
@@ -950,14 +957,7 @@ interface XStatePlaybookRuntimeSpecBase<TOptions> {
   entryEvent?: {
     type: string;
     textField: string;
-    /**
-     * DR-034: the FSM context member this machine's entry action copies the
-     * exact Boss text into. Where it is named, the failure-state retry
-     * builds its payload from that member of the live snapshot instead of
-     * from the process-local recorded event, so the action derives the same
-     * before and after `restore`. Absent: the recorded event stays the
-     * source and the action lives only as long as the process.
-     */
+    /** @deprecated Step checkpoints now carry the accepted input directly. */
     contextField?: string;
   };
   /**
@@ -1831,6 +1831,7 @@ function buildGovernedJudgePrompt(
     '```',
     '',
     'Pick exactly one declared `guard` and reply with exactly that outcome\'s reply shape below: `guard` plus its semantic-owned fields and nothing else.',
+    'If no declared outcome matches the player output, instead reply exactly {"blocked":"explain the missing outcome or contradictory requirements"}. Never force a match or invent a guard. A blocked reply pauses the playbook for Boss; it is not completion.',
     'A field listed as runtime-supplied is owned by presentation, effect, or runtime evidence; the runtime fills it itself, and a reply that includes one is structurally invalid.',
     '',
   ];
@@ -1979,6 +1980,7 @@ interface PlayerBridgeSpec {
   adjudication: PlayerAdjudicationSpec;
   resumableStateIds: ReadonlySet<string>;
   allowsCorrectiveReplay?: (result: PlayerResult) => boolean;
+  run?: (input: PlaybookPlayerInput, signal: AbortSignal, execute: () => Promise<PlaybookActorOutput>) => Promise<PlaybookActorOutput>;
 }
 
 export function createPlayerBridge(
@@ -1988,8 +1990,7 @@ export function createPlayerBridge(
   boundary?: RuntimeBoundaryCalls,
   onControlPlaneError?: (error: unknown) => void,
 ): PromiseActorLogic<PlaybookActorOutput, PlaybookPlayerInput> {
-  return fromPromise<PlaybookActorOutput, PlaybookPlayerInput>(
-    async ({ input, signal }) => {
+  const execute = async ({ input, signal }: { input: PlaybookPlayerInput; signal: AbortSignal }): Promise<PlaybookActorOutput> => {
       const activeSignal = combineAbortSignals(signal, getActiveSignal?.());
       let roleId: string;
       let prompt: string;
@@ -2079,8 +2080,9 @@ export function createPlayerBridge(
         }
         throw error;
       }
-    },
-  );
+    };
+  return fromPromise<PlaybookActorOutput, PlaybookPlayerInput>((args) => spec.run
+    ? spec.run(args.input, args.signal, () => execute(args)) : execute(args));
 }
 
 // ---------------------------------------------------------------------------
@@ -3224,11 +3226,12 @@ function makeDefaultStatusesForState(
       }
       return [
         ...statuses,
-        { message: `${askerLabel(pending.asker)} asks: ${pending.question}` },
+        { message: `${askerLabel(pending.asker)} asks: ${pending.question}`, data: { kind: 'boss-question' } },
         {
           message:
             `◆ awaiting Boss reply · ${pending.resumeStateId} · ` +
             `${askerLabel(pending.asker)} · ${pending.sourceItem}`,
+          data: { kind: 'boss-question' },
         },
       ];
     }
@@ -4106,11 +4109,13 @@ export function createXStatePlaybookRuntime<
           statuses.push(
             {
               message: `${askerLabel(pending.asker)} asks: ${pending.question}`,
+              data: { kind: 'boss-question' },
             },
             {
               message:
                 `◆ awaiting Boss reply · ${pending.resumeStateId} · ` +
                 `${askerLabel(pending.asker)} · ${pending.sourceItem}`,
+              data: { kind: 'boss-question' },
             },
           );
         }
@@ -4210,6 +4215,7 @@ export function createXStatePlaybookRuntime<
         `${label} current host effect ledger`,
       );
     let effectLedgerMirror = currentEffectLedger();
+    let recoveryCheckpoint: PlaybookRuntimeSnapshot['recoveryCheckpoint'];
     let retainedEffectSourceSessionId: string | undefined;
     let retainedEffectReconciliation:
       | PlaybookRuntimeSnapshot['retainedEffectReconciliation']
@@ -4363,12 +4369,6 @@ export function createXStatePlaybookRuntime<
     let playbookCallSequence = 0;
     let captainCallSequence = 0;
     let applyCallSequence = 0;
-    // DR-029: the last event a public Boss boundary sent into the
-    // machine — classified, deterministic entry, or Boss reply — kept with
-    // its recorded payload so a failure-state retry action can replay the
-    // event that drove the run into `failed`. Process-local: the durable
-    // runtime snapshot does not persist it (PBRT-50).
-    let lastBossEvent: EventObject | undefined;
     // DR-029: process-local at-most-once `apply` execution — the accepted receipt
     // recorded for each idempotency key, returned verbatim on a repeated
     // key. A key whose call settled `rejected` or threw before reaching
@@ -4605,7 +4605,7 @@ export function createXStatePlaybookRuntime<
     function boundaryExcludesEffect(boundary: PlaybookEffectBoundary): boolean {
       return (
         boundary.logicalOperationId === undefined &&
-        boundary.physicalReceipt?.classification === 'unchanged'
+        (boundary.physicalReceipt?.classification === 'unchanged' || boundary.restored !== undefined)
       );
     }
 
@@ -4677,7 +4677,7 @@ export function createXStatePlaybookRuntime<
               ({ sequence }) =>
                 sequence > reconstructedGovernedPrefixSequence!,
             );
-      if (candidate === undefined || candidate.sourceStateId !== state.stateId) {
+      if (candidate === undefined || candidate.restored !== undefined || candidate.sourceStateId !== state.stateId) {
         return;
       }
       const persisted = persistedBoundaryReconciliation(candidate, ledger);
@@ -6341,6 +6341,401 @@ export function createXStatePlaybookRuntime<
       );
     }
 
+    let acceptedStepResult: PlaybookRuntimeSnapshot['recoveryCheckpoint'];
+    let requiredRecoveryBaseline: PlaybookRepositoryReceipt['baseline'] | undefined;
+
+    function captureRecoveryCheckpoint(stateId: string, prompt: string, boundaryPrefix?: number): void {
+      if (requiredRecoveryBaseline !== undefined) return;
+      // Capture after the entry emissions drain: the invocation is now a
+      // real active child in XState's persisted snapshot, before host work.
+      const id = recoveryCheckpoint?.stateId === stateId ? recoveryCheckpoint.id : undefined;
+      recoveryCheckpoint = undefined;
+      if (!actor || currentState().stateId !== stateId) return;
+      try {
+        const current = currentEffectLedger();
+        recoveryCheckpoint = deepFreeze({
+          stateId,
+          prompt,
+          ...(id === undefined ? {} : { id }),
+          machine: detachPersistedMachineSnapshot(actor.getPersistedSnapshot()),
+          boundaryPrefix: boundaryPrefix ?? current.boundaries.length,
+        });
+      } catch {
+        // An in-memory-only context is still executable; it simply cannot
+        // promise a durable step retry. Keep the legacy control behavior.
+      }
+    }
+
+    function stepReplayIsSafe(): boolean {
+      if (!recoveryCheckpoint || hasUnresolvedReconciliation()) return false;
+      const current = currentEffectLedger();
+      return current.boundaries
+        .slice(recoveryCheckpoint.boundaryPrefix)
+        .every(
+          (boundary) =>
+            runtimeBoundaryIsOwned(boundary) &&
+            boundary.logicalOperationId === undefined &&
+            (boundary.physicalReceipt?.classification === 'unchanged' || boundary.restored !== undefined),
+        );
+    }
+
+    function repairableReadOnlyBoundary(): PlaybookEffectBoundary | undefined {
+      if (!recoveryCheckpoint || !repositoryCapability?.observe || !repositoryCapability.acquire ||
+          retainedEffectReconciliationRequired || deferredReconciliationOperationId !== undefined) return undefined;
+      const suffix = currentEffectLedger().boundaries.slice(recoveryCheckpoint.boundaryPrefix);
+      if (suffix.length !== 1) return undefined;
+      const saved = suffix[0]!;
+      if (!runtimeBoundaryIsOwned(saved) || saved.restored !== undefined ||
+          saved.sourceStateId !== recoveryCheckpoint.stateId || saved.cohortId !== undefined ||
+          saved.logicalOperationId !== undefined || saved.dispositions.some((item) => item !== 'unchanged') ||
+          saved.physicalReceipt === undefined || saved.after?.head !== saved.baseline.head ||
+          saved.physicalReceipt.classification === 'unchanged' ||
+          [...unresolvedSemanticBoundaryIds].some((id) => id !== saved.boundaryId)) return undefined;
+      return saved;
+    }
+
+    async function confirmReadOnlyRestoration(saved: PlaybookEffectBoundary, signal: AbortSignal): Promise<void> {
+      const claim = await repositoryCapability!.acquire!({ signal });
+      try {
+        await claim.assertOwner();
+        const restored = snapshotJsonValue(await repositoryCapability!.observe!()) as unknown as PlaybookRepositoryReceipt['baseline'];
+        if (!isDeepStrictEqual(restored, saved.baseline)) {
+          throw new Error(`${label} preparation has not restored the stopped step's repository; it remains paused`);
+        }
+        signal.throwIfAborted();
+        effectLedgerMirror = assertPlaybookEffectLedger(await effectLedgerCapability!.writeAhead([
+          { kind: 'replace-boundaries', replacements: [{ expected: saved, next: { ...saved, restored } }] },
+        ]));
+        if (!isDeepStrictEqual(effectLedgerMirror.boundaries.find(({ boundaryId }) => boundaryId === saved.boundaryId)?.restored, restored)) {
+          throw new Error(`${label} repository restoration was not durably acknowledged`);
+        }
+        refreshUnresolvedSemanticReconciliation(effectLedgerMirror);
+      } finally { await claim.release(); }
+    }
+
+    // A completed commit with saved presentation needs only the missing
+    // tool-free judgment. Never repeat the player to recover that evidence.
+    function recoverableJudgment(): PlaybookEffectBoundary | undefined {
+      if (
+        !recoveryCheckpoint || recoveryCheckpoint.result !== undefined || recoveryCheckpoint.delivered ||
+        retainedEffectReconciliationRequired ||
+        deferredReconciliationOperationId !== undefined
+      )
+        return undefined;
+      const suffix = currentEffectLedger().boundaries.slice(
+        recoveryCheckpoint.boundaryPrefix,
+      );
+      if (suffix.length !== 1) return undefined;
+      const saved = suffix[0]!;
+      if (
+        !runtimeBoundaryIsOwned(saved) ||
+        saved.sourceStateId !== recoveryCheckpoint.stateId ||
+        saved.logicalOperationId !== undefined ||
+        saved.correctionBudget.spent ||
+        saved.physicalReceipt?.classification !== 'one-descendant-commit' ||
+        !saved.finalText?.trim() ||
+        governedOutcomesForBoundary(saved) === undefined ||
+        (saved.semanticCandidate !== undefined &&
+          persistedBoundaryReconciliation(saved, currentEffectLedger())
+            ?.reconciliation.status !== 'resolved') ||
+        [...unresolvedSemanticBoundaryIds].some((id) => id !== saved.boundaryId)
+      )
+        return undefined;
+      return saved;
+    }
+
+    async function recoverJudgment(
+      saved: PlaybookEffectBoundary,
+      signal: AbortSignal,
+    ): Promise<void> {
+      const checkpoint = recoveryCheckpoint!;
+      const persisted = checkpoint.machine as unknown as {
+        children: Record<string, { snapshot: { input: PlaybookPlayerInput } }>;
+      };
+      const input = Object.values(persisted.children)[0]!;
+      const actorInput = input.snapshot.input;
+      const outcomes = governedOutcomesForBoundary(saved)!;
+      const candidate =
+        saved.semanticCandidate ??
+        parseGovernedSemanticCandidate(
+          await boundary.callJudge(
+            'player-output-adjudication',
+            saved.sourceStateId,
+            buildGovernedJudgePrompt(actorInput, saved.finalText!, outcomes),
+            signal,
+          ),
+        );
+      const result = reconcilePlaybookSemanticEvidence({
+        outcomes,
+        semanticCandidate: candidate,
+        finalText: saved.finalText,
+        receipt: saved.physicalReceipt,
+      });
+      signal.throwIfAborted();
+      const next = {
+        ...saved,
+        semanticCandidate: snapshotJsonValue(result.evidence.semanticCandidate),
+      };
+      const acknowledged = assertPlaybookEffectLedger(
+        await effectLedgerCapability!.writeAhead([
+          {
+            kind: 'replace-boundaries',
+            replacements: [{ expected: saved, next }],
+          },
+        ]),
+      );
+      if (
+        !isDeepStrictEqual(
+          acknowledged.boundaries.find((b) => b.boundaryId === saved.boundaryId),
+          next,
+        )
+      ) {
+        throw new Error(
+          `${label} recovered judgment was not acknowledged exactly`,
+        );
+      }
+      effectLedgerMirror = acknowledged;
+      refreshUnresolvedSemanticReconciliation(acknowledged);
+      if (result.status !== 'resolved') {
+        const error = attachPlaybookFailureCause(new Error(
+          result.status === 'unresolved' && 'reason' in result.cause.evidence && result.cause.evidence.reason
+            ? String(result.cause.evidence.reason)
+            : `${label} saved result could not be reconciled; the playbook remains parked`,
+        ), result.status === 'unresolved' ? result.cause : runtimeDefectCause('Saved result still needs a Boss answer'));
+        const paused = detachPersistedMachineSnapshot(actor!.getPersistedSnapshot()) as Record<string, JsonValue>;
+        stopActor();
+        actor = buildActor(runtimePorts!, {
+          ...paused, context: { ...(paused.context as Record<string, JsonValue>), lastError: snapshotJsonValue(normalizeErrorFull(error)) },
+        });
+        suppressInspectionEmissions = false;
+        actor.start();
+        throw error;
+      }
+      await resumeCheckpoint({ ...checkpoint, result: snapshotJsonValue(result.output) });
+    }
+
+    async function resumeCheckpoint(checkpoint: NonNullable<PlaybookRuntimeSnapshot['recoveryCheckpoint']>): Promise<void> {
+      acceptedStepResult = checkpoint;
+      try {
+        stopActor();
+        actor = buildActor(runtimePorts!, checkpoint.machine);
+        suppressInspectionEmissions = false;
+        actor.start();
+        await waitForPlaybookQuiescence(actor, { pendingCalls: nestedBridge });
+      } finally { acceptedStepResult = undefined; }
+    }
+
+    function exportRuntimeSnapshot(checkpoint?: { interrupted?: true; child?: PlaybookPendingCall }): PlaybookRuntimeSnapshot | undefined {
+        if (!actor || !session || disposed || disposalPromise !== undefined) {
+          return undefined;
+        }
+        if (activeSignal !== undefined && checkpoint === undefined) return undefined;
+        if (deferredSettlementClosure !== undefined) return undefined;
+        const pendingCall = checkpoint?.child ?? nestedBridge.getPendingCall();
+        const bridgeSuspendedCall = checkpoint?.child ? nestedBridge.checkpointCall(checkpoint.child) : nestedBridge.getSuspendedCall();
+        if ((pendingCall === undefined) !== (bridgeSuspendedCall === undefined)) {
+          return undefined;
+        }
+        let suspendedCall: typeof bridgeSuspendedCall;
+        if (bridgeSuspendedCall !== undefined) {
+          if (
+            pendingCall?.callId !== bridgeSuspendedCall.callId ||
+            pendingCall?.playbookId !== bridgeSuspendedCall.playbookId ||
+            pendingCall?.childSessionId !== bridgeSuspendedCall.childSessionId
+          ) {
+            return undefined;
+          }
+          if (!playbookCallTurnIds.has(bridgeSuspendedCall.callId)) {
+            return undefined;
+          }
+          const turnId = playbookCallTurnIds.get(bridgeSuspendedCall.callId);
+          if (
+            bridgeSuspendedCall.turnId !== undefined &&
+            bridgeSuspendedCall.turnId !== turnId
+          ) {
+            return undefined;
+          }
+          suspendedCall = {
+            ...bridgeSuspendedCall,
+            ...(turnId === undefined ? {} : { turnId }),
+            ...(hasGovernedPlayerStates
+              ? {
+                  effectBoundaryPrefixSequence:
+                    playbookCallEffectPrefixes.get(
+                      bridgeSuspendedCall.callId,
+                    ) ?? null,
+                }
+              : {}),
+          };
+        }
+        const interrupted = checkpoint?.interrupted && recoveryCheckpoint && machine.root.states.failed;
+        const state = interrupted
+          ? normalizePlaybookSnapshot(machine.resolveState({ value: 'failed', context: {} }))
+          : checkpoint?.child ? normalizePlaybookSnapshot(actor.getSnapshot(), { pendingCall }) : currentState();
+        if (state.status !== 'active' || !state.quiescent) return undefined;
+        const context = (actor.getSnapshot() as { context?: unknown })
+          .context as Record<string, unknown>;
+        // DR-063 §2: the failed state's `lastError` is persisted as every live
+        // surface publishes it, completed from the runtime's own cause slot, so
+        // a thrown value that refused the cause still explains itself after a
+        // restart.
+        const machineSnapshot = detachPersistedMachineSnapshot(
+          interrupted ? { ...recoveryCheckpoint!.machine as object, value: 'failed', children: {} } : actor.getPersistedSnapshot(),
+          state.stateId === 'failed'
+            ? { lastError: interrupted ? { name: 'InterruptedStep', message: 'The process stopped during this step. Review the recorded work before choosing how to continue.', cause: runtimeDefectCause('The process stopped during this step. Review the recorded work before choosing how to continue.') } : failedStateError(context ?? {}) }
+            : {},
+        );
+        effectLedgerMirror = currentEffectLedger();
+        refreshRetainedEffectReconciliation(effectLedgerMirror);
+        syncDeferredReconciliationOverlay();
+        refreshUnresolvedSemanticReconciliation(effectLedgerMirror);
+        const pendingQuestions = !hasUnresolvedReconciliation()
+          ? pendingBossQuestionsFor(state, context ?? {})
+          : [];
+        const interruptedPrefix = interrupted ? activeEffectLedgerPrefixSequence : undefined;
+        const interruptedAttempts = new Set(effectLedgerMirror.boundaries.filter(({ sequence }) => interruptedPrefix !== undefined && sequence > interruptedPrefix).map(({ attemptId }) => attemptId));
+        const failedEffectAttempt = interrupted && interruptedPrefix !== undefined && interruptedAttempts.size <= 1
+          ? { boundaryPrefix: interruptedPrefix, attemptId: interruptedAttempts.values().next().value ?? null }
+          :
+          hasGovernedPlayerStates &&
+          !interrupted && state.stateId === 'failed' &&
+          failedAttemptMatchesCurrentLedger(effectLedgerMirror)
+            ? {
+                boundaryPrefix: failedEffectBoundaryPrefix!,
+                attemptId: failedGovernedAttemptId ?? null,
+              }
+            : undefined;
+        return {
+          schemaVersion: 4,
+          playbookId: session.playbookId,
+          machine: machineSnapshot,
+          roleResumeTokens: snapshotRoleResumeTokens(),
+          sequences: {
+            trace: traceSequence,
+            turn: turnSequence,
+            judgeCall: judgeCallSequence,
+            playerCall: playerCallSequence,
+            playbookCall: playbookCallSequence,
+            ...(declaredActors.has('captain')
+              ? { captainCall: captainCallSequence }
+              : {}),
+          },
+          state,
+          pendingBossQuestions: pendingQuestions.map((pending) => ({
+            questionId: pending.questionId,
+            asker: pending.asker,
+            question: pending.question,
+            sourceItem: pending.sourceItem,
+          })),
+          effectLedger: effectLedgerMirror,
+          ...(retainedEffectSourceSessionId === undefined
+            ? {}
+            : { retainedEffectSourceSessionId }),
+          ...(retainedEffectReconciliation === undefined
+            ? {}
+            : { retainedEffectReconciliation }),
+          ...(failedEffectAttempt === undefined
+            ? {}
+            : { failedEffectAttempt }),
+          ...((state.stateId === 'failed' || pendingQuestions.length > 0) && recoveryCheckpoint !== undefined
+            ? { recoveryCheckpoint } : {}),
+          ...(suspendedCall === undefined ? {} : { suspendedCall }),
+        };
+    }
+
+    async function runJournalledStep(
+      kind: PlaybookStepRecord['kind'],
+      input: PlaybookPlayerInput | PlaybookCaptainInput | PlaybookScriptInput,
+      signal: AbortSignal,
+      execute: () => Promise<PlaybookActorOutput>,
+    ): Promise<PlaybookActorOutput> {
+      const saved = acceptedStepResult;
+      let output: PlaybookActorOutput;
+      if (saved?.stateId === input.stateId && saved.result !== undefined) {
+        acceptedStepResult = undefined;
+        recoveryCheckpoint = saved;
+        output = snapshotJsonValue(saved.result) as PlaybookActorOutput;
+      } else {
+        const record = savedPorts?.recordStep;
+        await drainEmissions();
+        signal.throwIfAborted();
+        try {
+          captureRecoveryCheckpoint(input.stateId, 'command' in input ? input.command : 'role' in input ? composeBoundPlayerPrompt(input) : composeCaptainPrompt(input));
+        } catch (error) {
+          if (!isAbortFailure(error, signal)) controlPlaneError ??= error;
+          throw error;
+        }
+        if (record) {
+          const id = randomUUID();
+          if (recoveryCheckpoint) recoveryCheckpoint = { ...recoveryCheckpoint, id };
+          const step = { id, kind, stateId: input.stateId };
+          await record(step, exportRuntimeSnapshot({ interrupted: true }));
+          signal.throwIfAborted();
+          const result = snapshotJsonValue(await execute());
+          // Keep the known output if its save loses acknowledgement. A drained
+          // failure can then preserve it without treating the call as unexecuted.
+          if (recoveryCheckpoint?.id === id) recoveryCheckpoint = { ...recoveryCheckpoint, result };
+          await record({ ...step, result });
+          output = result as PlaybookActorOutput;
+        } else {
+          output = await execute();
+        }
+      }
+      if (recoveryCheckpoint?.stateId === input.stateId) {
+        const { result: _result, ...start } = recoveryCheckpoint;
+        recoveryCheckpoint = { ...start, delivered: true };
+      }
+      return output;
+    }
+
+    function validateRecoveryCheckpoint(
+      checkpoint: PlaybookRuntimeSnapshot['recoveryCheckpoint'],
+    ): void {
+      if (!checkpoint) return;
+      const node = machine.root.states[checkpoint.stateId];
+      const persisted = checkpoint.machine as Record<string, JsonValue>;
+      const children = persisted.children;
+      if (
+        !node ||
+        node.invoke.length !== 1 ||
+        !['player', 'captain', 'script'].includes(String(node.invoke[0]!.src)) ||
+        !isPlainObject(children) ||
+        Object.keys(children).length !== 1
+      ) {
+        throw new TypeError(
+          `${label} recovery checkpoint does not name one current invocation`,
+        );
+      }
+      const child = children[node.invoke[0]!.id] as
+        Record<string, JsonValue> | undefined;
+      if (
+        !child ||
+        child.src !== node.invoke[0]!.src ||
+        !isPlainObject(child.snapshot) ||
+        child.snapshot.status !== 'active' ||
+        !isPlainObject(child.snapshot.input) ||
+        child.snapshot.input.stateId !== checkpoint.stateId
+      ) {
+        throw new TypeError(
+          `${label} recovery checkpoint invocation is incompatible`,
+        );
+      }
+      if (checkpoint.result !== undefined) {
+        const output = checkpoint.result;
+        const input = child.snapshot.input;
+        if (!isPlainObject(output) || typeof output.guard !== 'string' ||
+            !isPlainObject(input.result) || !Object.hasOwn(input.result, output.guard) ||
+            (node.invoke[0]!.src === 'script' &&
+              (!Number.isInteger(output.exitStatus) || Object.keys(output).sort().join(',') !== 'exitStatus,guard' ||
+                output.guard !== Object.keys(input.result)[output.exitStatus === 0 ? 0 : Math.min(1, Object.keys(input.result).length - 1)]))) {
+          throw new TypeError(`${label} saved step result is incompatible with its invocation`);
+        }
+        for (const field of extractFields(String(input.result[output.guard]))) {
+          if (output[field] === undefined || output[field] === null) throw new TypeError(`${label} saved step result is missing ${field}`);
+        }
+      }
+    }
+
     function captureEffectLedgerPrefixSequence(): number | undefined {
       if (!hasGovernedPlayerStates) return undefined;
       try {
@@ -7153,14 +7548,23 @@ export function createXStatePlaybookRuntime<
               // captured it under this exclusive claim. A host that supplies
               // none states no pre-existing change, exactly as an empty
               // baseline projection does.
-              operation: (context) =>
-                runTracedPlayerCall(
+              operation: async (context) => {
+                if (requiredRecoveryBaseline !== undefined) {
+                  if (!isDeepStrictEqual(snapshotJsonValue(context.baseline), requiredRecoveryBaseline)) {
+                    throw new Error(`${label} repository changed after preparation; the stopped step remains paused`);
+                  }
+                  requiredRecoveryBaseline = undefined;
+                  captureRecoveryCheckpoint(input.stateId, freshPrompt,
+                    currentEffectLedger().boundaries.findIndex(({ boundaryId }) => boundaryId === effectBoundary.boundaryId));
+                }
+                return runTracedPlayerCall(
                   selectedResume,
                   effectAuthorizedPreExistingBlock(
                     effectBoundary,
                     context?.baseline,
                   ),
-                ),
+                );
+              },
               completeEffectBoundary: completionEvidenceFor(
                 input,
                 roleId,
@@ -7454,6 +7858,7 @@ export function createXStatePlaybookRuntime<
     ): PromiseActorLogic<PlaybookActorOutput, PlaybookPlayerInput> {
       return createPlayerBridge(
         {
+          run: (input, signal, execute) => runJournalledStep('player', input, signal, execute),
           resolveRoleId: requireRoleId,
           validateInput: (input) =>
             assertGovernedPlayerInput(
@@ -7487,7 +7892,7 @@ export function createXStatePlaybookRuntime<
       PlaybookCaptainInput
     > {
       return fromPromise<PlaybookActorOutput, PlaybookCaptainInput>(
-        async ({ input, signal }) => {
+        ({ input, signal }) => runJournalledStep('captain', input, signal, async () => {
           const active = combineAbortSignals(signal, activeSignal);
           try {
             await drainEmissions();
@@ -7564,7 +7969,7 @@ export function createXStatePlaybookRuntime<
             }
             throw error;
           }
-        },
+        }),
       );
     }
 
@@ -7578,7 +7983,7 @@ export function createXStatePlaybookRuntime<
       PlaybookScriptInput
     > {
       return fromPromise<PlaybookActorOutput, PlaybookScriptInput>(
-        async ({ input, signal }) => {
+        ({ input, signal }) => runJournalledStep('script', input, signal, async () => {
           await drainEmissions();
           const active = combineAbortSignals(signal, activeSignal);
           const guards = Object.keys(input.result);
@@ -7767,7 +8172,7 @@ export function createXStatePlaybookRuntime<
               if (killTimer !== undefined) clearTimeout(killTimer);
             }
           }
-        },
+        }),
       );
     }
 
@@ -8169,6 +8574,10 @@ export function createXStatePlaybookRuntime<
               latchRuntimeError(error);
             }
             if (state.stateId === 'failed') {
+              if (previousState?.stateId !== 'failed' &&
+                  previousState?.stateId !== recoveryCheckpoint?.stateId) {
+                recoveryCheckpoint = undefined;
+              }
               if (
                 previousState?.stateId !== 'failed' ||
                 activeGovernedBoundarySeen
@@ -8453,7 +8862,7 @@ export function createXStatePlaybookRuntime<
       activeDeferredContinuation = undefined;
       deferInspectionEmissions = false;
       deferredInspectionEmissions = [];
-      lastBossEvent = undefined;
+      recoveryCheckpoint = undefined;
       suppressInspectionEmissions = false;
       initialized = false;
       traceSequence = 0;
@@ -8475,6 +8884,9 @@ export function createXStatePlaybookRuntime<
       event?: EventObject;
       deferredRestoreOperationId?: string;
       unresolvedEffectAction?: 'reconcile' | 'abandon';
+      retryStep?: true;
+      retryJudgment?: PlaybookEffectBoundary;
+      restoreReadOnly?: PlaybookEffectBoundary;
     }
 
     function snapshotCan(snapshot: unknown, event: EventObject): boolean {
@@ -8486,78 +8898,24 @@ export function createXStatePlaybookRuntime<
       );
     }
 
-    // DR-034: where the artifact names the FSM context member its entry
-    // action copies the exact Boss text into, that member of the live
-    // snapshot is the retry payload's source. The persisted machine snapshot
-    // carries it, so the candidate derives identically in the process that
-    // exported the snapshot and in one that restored it, and a failure
-    // reached after a Boss reply — whose recorded event the failure state
-    // refuses — is recoverable too. Naming the member is the artifact's
-    // statement that it holds the entry text: a same-named member is never
-    // assumed, since inferring one would turn any matching context member
-    // into a replay payload without its author saying so.
-    // Declared and absent or empty excludes the candidate rather than
-    // falling back to the record, which would make the action depend on the
-    // process again — the very thing this source exists to end.
-    function retryEventFrom(snapshot: unknown): EventObject | undefined {
-      const entryEvent = spec.entryEvent;
-      if (entryEvent?.contextField === undefined) return lastBossEvent;
-      const context = (snapshot as { context?: unknown } | null)?.context;
-      const text = isPlainObject(context)
-        ? context[entryEvent.contextField]
-        : undefined;
-      if (typeof text !== 'string' || text.trim() === '') return undefined;
-      return { type: entryEvent.type, [entryEvent.textField]: text };
-    }
-
-    // The failure-state retry entry replays the recorded last classified
-    // event with its recorded payload, or the entry event the declared
-    // context member above sources. A candidate whose event the live
-    // snapshot does not accept — or whose payload the runtime can source
-    // from neither — is excluded rather than completed with invented text.
-    // The caller has already applied the PBRT-71 replay fence.
-    function retryActionFor(
-      snapshot: unknown,
-      stateId: string | undefined,
-    ): DerivedControlAction | undefined {
-      if (stateId !== 'failed') return undefined;
-      const retryEvent = retryEventFrom(snapshot);
-      if (retryEvent === undefined) return undefined;
-      if (!snapshotCan(snapshot, retryEvent)) return undefined;
-      // A recorded explicit-state-jump event names the exact state its
-      // replay re-enters: the root BOSS_INTERRUPT shape is a guarded
-      // multi-arm list keyed on `targetId`, so the first configured arm
-      // may label a different state than the one the recorded event
-      // actually resumes.
-      const recordedTargetId =
-        retryEvent.type === JUMP_EVENT_TYPE
-          ? (retryEvent as { targetId?: unknown }).targetId
-          : undefined;
-      const target =
-        typeof recordedTargetId === 'string' &&
-        recordedTargetId.trim().length > 0
-          ? recordedTargetId
-          : firstTransitionTarget(machine, stateId, retryEvent.type);
-      // PBRT-52: a label is written from a source state description, never
-      // from an identifier. Falling back to the target id — or, with no
-      // resolvable target, to the FSM event type — makes the label *be* the
-      // internal name, which defeats the substitution the label exists for
-      // and puts a machine identifier into Boss-facing text
-      // (CAPPLAY-5). A candidate whose label can only be an id is excluded
-      // exactly like one whose payload cannot be sourced.
-      const description =
-        (target === undefined ? undefined : stateDescriptions.get(target)) ??
-        stateDescriptions.get(stateId);
-      if (description === undefined) return undefined;
+    function retryActionFor(stateId: string | undefined): DerivedControlAction | undefined {
+      if (stateId !== 'failed' || !recoveryCheckpoint) return undefined;
+      const description = stateDescriptions.get(recoveryCheckpoint.stateId);
+      const savedResult = recoveryCheckpoint.result !== undefined;
+      const safe = savedResult
+        ? !hasUnresolvedReconciliation() && currentEffectLedger().boundaries.slice(recoveryCheckpoint.boundaryPrefix)
+          .every((boundary) => runtimeBoundaryIsOwned(boundary) && boundary.sourceStateId === recoveryCheckpoint!.stateId)
+        : stepReplayIsSafe();
+      if (description === undefined || !safe) return undefined;
+      const entry = spec.entryEvent;
+      const target = entry && firstTransitionTarget(machine, stateId, entry.type);
       return {
         action: {
-          id: `retry:${retryEvent.type}`,
-          label: `Retry: ${description}`,
-          // DR-063 §3: retrying a failed call is `ready` — the runtime cannot
-          // see whether the Boss changed the outside world since it failed.
+          id: target === recoveryCheckpoint.stateId ? `retry:${entry!.type}` : 'retry:step',
+          label: `${savedResult ? 'Continue from saved result' : 'Retry'}: ${description}`,
           standing: 'ready',
         },
-        event: retryEvent,
+        retryStep: true,
       };
     }
 
@@ -8614,6 +8972,18 @@ export function createXStatePlaybookRuntime<
         return [];
       }
       const derived: DerivedControlAction[] = [];
+      const repairable = state.stateId === 'failed' ? repairableReadOnlyBoundary() : undefined;
+      if (repairable !== undefined) derived.push({
+        action: { id: 'retry:restored-step', label: 'Restore the repository and retry the read-only step', standing: 'ready' },
+        retryStep: true,
+        restoreReadOnly: repairable,
+      });
+      const judgment = state.stateId === 'failed' ? recoverableJudgment() : undefined;
+        if (judgment !== undefined) derived.push({
+          action: { id: 'retry:adjudication', label: 'Retry assessment of the saved result', standing: 'ready' },
+          retryJudgment: judgment,
+        });
+      if (judgment !== undefined && !hasUnresolvedReconciliation()) return derived;
       if (hasUnresolvedReconciliation()) {
         const operation =
           deferredReconciliationOperationId === undefined
@@ -8650,17 +9020,13 @@ export function createXStatePlaybookRuntime<
         );
         return derived;
       }
-      // PBRT-71 / DR-040 §4: out of the failure state, a jump restarts the
-      // failed attempt's work exactly as the retry does, so one fence gates
-      // both. Unless every governed boundary of that attempt carries a
-      // complete `unchanged` receipt, neither is advertised — and `apply`,
-      // which revalidates against this list, accepts neither — so no
-      // control can replay a player call whose effect may already exist.
+      const retry = retryActionFor(state.stateId);
+      if (retry !== undefined) derived.push(retry);
+      // A jump can repeat earlier work, unlike checkpoint retry. Its whole
+      // failed attempt must therefore still pass the replay fence.
       if (state.stateId === 'failed' && !failedAttemptAllowsReplay()) {
         return derived;
       }
-      const retry = retryActionFor(snapshot, state.stateId);
-      if (retry !== undefined) derived.push(retry);
       // Jump entries: resumable targets whose explicit-state-jump event the
       // live snapshot accepts (state guards included), sent with the
       // advertised target id and optional textual fields omitted.
@@ -8792,6 +9158,7 @@ export function createXStatePlaybookRuntime<
         boundSession.playbookId,
         { allowSuspendedCall: true },
       );
+      validateRecoveryCheckpoint(boundSnapshot.recoveryCheckpoint);
       if (
         kind === 'adopt' &&
         effectLedgerCapability !== undefined &&
@@ -8899,6 +9266,7 @@ export function createXStatePlaybookRuntime<
       initInFlight = initialization;
       const initTask = (async () => {
         session = boundSession;
+        recoveryCheckpoint = boundSnapshot.recoveryCheckpoint;
         syncDeferredReconciliationOverlay();
         refreshUnresolvedSemanticReconciliation(effectLedgerMirror);
         prepareReconstructedGovernedDelivery(
@@ -9133,6 +9501,7 @@ export function createXStatePlaybookRuntime<
       signal: AbortSignal,
       turnId: number,
       classificationLine?: string,
+      onAccepted?: () => void,
     ): Promise<'continued' | 'unresolved'> {
       if (repositoryCapability === undefined) {
         throw new Error(
@@ -9183,6 +9552,7 @@ export function createXStatePlaybookRuntime<
               effectBoundary.roleId, boundPlayerId,
             );
             continuationStarted = true;
+            onAccepted?.();
             actor!.send(event);
             // The host has durably started this boundary and the FSM has
             // moved: publish the buffered classification line and the
@@ -9519,114 +9889,7 @@ export function createXStatePlaybookRuntime<
       // Defined only at a safe capture point — initialized, not disposing
       // or disposed, no active public boundary, and the actor quiescent with
       // status `active`.
-      exportSnapshot(): PlaybookRuntimeSnapshot | undefined {
-        if (!actor || !session || disposed || disposalPromise !== undefined) {
-          return undefined;
-        }
-        if (activeSignal !== undefined) return undefined;
-        if (deferredSettlementClosure !== undefined) return undefined;
-        const pendingCall = nestedBridge.getPendingCall();
-        const bridgeSuspendedCall = nestedBridge.getSuspendedCall();
-        if ((pendingCall === undefined) !== (bridgeSuspendedCall === undefined)) {
-          return undefined;
-        }
-        let suspendedCall: typeof bridgeSuspendedCall;
-        if (bridgeSuspendedCall !== undefined) {
-          if (
-            pendingCall?.callId !== bridgeSuspendedCall.callId ||
-            pendingCall?.playbookId !== bridgeSuspendedCall.playbookId ||
-            pendingCall?.childSessionId !== bridgeSuspendedCall.childSessionId
-          ) {
-            return undefined;
-          }
-          if (!playbookCallTurnIds.has(bridgeSuspendedCall.callId)) {
-            return undefined;
-          }
-          const turnId = playbookCallTurnIds.get(bridgeSuspendedCall.callId);
-          if (
-            bridgeSuspendedCall.turnId !== undefined &&
-            bridgeSuspendedCall.turnId !== turnId
-          ) {
-            return undefined;
-          }
-          suspendedCall = {
-            ...bridgeSuspendedCall,
-            ...(turnId === undefined ? {} : { turnId }),
-            ...(hasGovernedPlayerStates
-              ? {
-                  effectBoundaryPrefixSequence:
-                    playbookCallEffectPrefixes.get(
-                      bridgeSuspendedCall.callId,
-                    ) ?? null,
-                }
-              : {}),
-          };
-        }
-        const state = currentState();
-        if (state.status !== 'active' || !state.quiescent) return undefined;
-        const context = (actor.getSnapshot() as { context?: unknown })
-          .context as Record<string, unknown>;
-        // DR-063 §2: the failed state's `lastError` is persisted as every live
-        // surface publishes it, completed from the runtime's own cause slot, so
-        // a thrown value that refused the cause still explains itself after a
-        // restart.
-        const machineSnapshot = detachPersistedMachineSnapshot(
-          actor.getPersistedSnapshot(),
-          state.stateId === 'failed'
-            ? { lastError: failedStateError(context ?? {}) }
-            : {},
-        );
-        effectLedgerMirror = currentEffectLedger();
-        refreshRetainedEffectReconciliation(effectLedgerMirror);
-        syncDeferredReconciliationOverlay();
-        refreshUnresolvedSemanticReconciliation(effectLedgerMirror);
-        const pendingQuestions = !hasUnresolvedReconciliation()
-          ? pendingBossQuestionsFor(state, context ?? {})
-          : [];
-        const failedEffectAttempt =
-          hasGovernedPlayerStates &&
-          state.stateId === 'failed' &&
-          failedAttemptMatchesCurrentLedger(effectLedgerMirror)
-            ? {
-                boundaryPrefix: failedEffectBoundaryPrefix!,
-                attemptId: failedGovernedAttemptId ?? null,
-              }
-            : undefined;
-        return {
-          schemaVersion: 4,
-          playbookId: session.playbookId,
-          machine: machineSnapshot,
-          roleResumeTokens: snapshotRoleResumeTokens(),
-          sequences: {
-            trace: traceSequence,
-            turn: turnSequence,
-            judgeCall: judgeCallSequence,
-            playerCall: playerCallSequence,
-            playbookCall: playbookCallSequence,
-            ...(declaredActors.has('captain')
-              ? { captainCall: captainCallSequence }
-              : {}),
-          },
-          state,
-          pendingBossQuestions: pendingQuestions.map((pending) => ({
-            questionId: pending.questionId,
-            asker: pending.asker,
-            question: pending.question,
-            sourceItem: pending.sourceItem,
-          })),
-          effectLedger: effectLedgerMirror,
-          ...(retainedEffectSourceSessionId === undefined
-            ? {}
-            : { retainedEffectSourceSessionId }),
-          ...(retainedEffectReconciliation === undefined
-            ? {}
-            : { retainedEffectReconciliation }),
-          ...(failedEffectAttempt === undefined
-            ? {}
-            : { failedEffectAttempt }),
-          ...(suspendedCall === undefined ? {} : { suspendedCall }),
-        };
-      },
+      exportSnapshot: (checkpoint?: { child?: PlaybookPendingCall }) => exportRuntimeSnapshot(checkpoint?.child ? { child: checkpoint.child } : undefined),
 
       // DR-014 §1 / PBRT-45: alternative to `init` that rehydrates an
       // exported snapshot under the same immutable session identity.
@@ -9697,6 +9960,31 @@ export function createXStatePlaybookRuntime<
           !hasUnresolvedReconciliation()
             ? stateDescriptionFor(state)
             : undefined;
+        const actions = deriveControlActions(snapshot).map(({ action }) => action);
+        const retry = actions.find(({ id, standing }) =>
+          id.startsWith('retry:') &&
+          (standing ?? 'ready') === 'ready');
+        const stoppedBoundary = recoveryCheckpoint === undefined ? undefined :
+          currentEffectLedger().boundaries.slice(recoveryCheckpoint.boundaryPrefix)
+            .filter((boundary) => runtimeBoundaryIsOwned(boundary) && boundary.sourceStateId === recoveryCheckpoint!.stateId).at(-1);
+        const recovery = recoveryCheckpoint === undefined ||
+          (pendingQuestions.length === 0 && retry === undefined) ? undefined : {
+            prompt: recoveryCheckpoint.prompt,
+            ...(stoppedBoundary === undefined ? {} : { evidence: snapshotJsonValue({
+              declaredResults: stoppedBoundary.sourceOutcomeSchema,
+              ...(stoppedBoundary.finalText === undefined ? {} : { savedPlayerText: stoppedBoundary.finalText }),
+              ...(stoppedBoundary.semanticCandidate === undefined ? {} : { selectedResult: stoppedBoundary.semanticCandidate }),
+              ...(stoppedBoundary.physicalReceipt === undefined ? {} : { repositoryReceipt: stoppedBoundary.physicalReceipt }),
+            }) }),
+            ...(repairableReadOnlyBoundary() === undefined ? {} : {
+              preparation: `This read-only step changed the repository. Restore its exact original HEAD and visible files before retrying; do not accept its saved result. Preserve user work. You may put generated outputs aside and prevent their return using local environment or ignore settings. Original observation: ${JSON.stringify(repairableReadOnlyBoundary()!.baseline)}. Observed after the failed step: ${JSON.stringify(repairableReadOnlyBoundary()!.after)}.`,
+            }),
+            ...(stateDescriptions.get(recoveryCheckpoint.stateId) === undefined ? {} :
+              { description: stateDescriptions.get(recoveryCheckpoint.stateId)! }),
+            continuation: pendingQuestions.length === 0
+              ? { kind: 'runtime' as const, actionId: retry!.id }
+              : { kind: 'reply' as const },
+          };
         return deepFreeze({
           state,
           ...(stateDescription === undefined ? {} : { stateDescription }),
@@ -9710,7 +9998,8 @@ export function createXStatePlaybookRuntime<
             sourceItem: pending.sourceItem,
           })),
           ...(lastError !== undefined ? { lastError } : {}),
-          actions: deriveControlActions(snapshot).map(({ action }) => action),
+          actions,
+          ...(recovery === undefined ? {} : { recovery }),
         });
       },
 
@@ -9911,7 +10200,10 @@ export function createXStatePlaybookRuntime<
               accepted = true;
               try {
                 let run: PlaybookRunResult;
-                if (candidate.unresolvedEffectAction === 'abandon') {
+                if (candidate.retryJudgment !== undefined) {
+                  await recoverJudgment(candidate.retryJudgment, signal);
+                  run = runResultFor(settledOutcome(signal));
+                } else if (candidate.unresolvedEffectAction === 'abandon') {
                   signal.throwIfAborted();
                   run = runResultFor('unresolved-effect');
                 } else if (
@@ -9934,6 +10226,19 @@ export function createXStatePlaybookRuntime<
                       ? 'no-action'
                       : 'quiescent',
                   );
+                } else if (candidate.retryStep) {
+                  if (candidate.restoreReadOnly !== undefined) {
+                    await confirmReadOnlyRestoration(candidate.restoreReadOnly, signal);
+                  }
+                  const checkpoint = recoveryCheckpoint!;
+                  requiredRecoveryBaseline = currentEffectLedger().boundaries
+                    .slice(checkpoint.boundaryPrefix).find(({ restored }) => restored !== undefined)?.restored;
+                  try {
+                    await resumeCheckpoint(checkpoint);
+                  } finally {
+                    requiredRecoveryBaseline = undefined;
+                  }
+                  run = runResultFor(settledOutcome(signal));
                 } else {
                   actor.send(candidate.event!);
                   await waitForPlaybookQuiescence(actor, {
@@ -9946,6 +10251,7 @@ export function createXStatePlaybookRuntime<
                   run.outcome === 'failed' || run.outcome === 'aborted'
                     ? {
                         disposition: 'failed',
+                        run,
                         error:
                           ('error' in run ? run.error : undefined) ??
                           normalizeError(
@@ -10059,9 +10365,11 @@ export function createXStatePlaybookRuntime<
       async handleBossInput({
         text,
         signal,
+        onAccepted,
       }: {
         text: string;
         signal: AbortSignal;
+        onAccepted?: () => void;
       }): Promise<PlaybookRunResult> {
         if (!actor || !savedPorts) {
           throw new Error(
@@ -10207,16 +10515,9 @@ export function createXStatePlaybookRuntime<
                   signal,
                   turnId,
                   statusLine,
+                  onAccepted,
                 );
                 if (continuation === 'continued') {
-                  try {
-                    lastBossEvent = snapshotJsonValue(
-                      event,
-                      'recorded Boss event',
-                    ) as unknown as EventObject;
-                  } catch {
-                    lastBossEvent = undefined;
-                  }
                   if (controlPlaneError !== undefined) {
                     throw controlPlaneError;
                   }
@@ -10226,7 +10527,6 @@ export function createXStatePlaybookRuntime<
                       : 'no-action',
                   );
                 } else {
-                  lastBossEvent = undefined;
                   result = runResultFor('no-action');
                 }
                 handledDeferred = true;
@@ -10239,7 +10539,6 @@ export function createXStatePlaybookRuntime<
                   deferredOperation.operationId,
                   signal,
                 );
-                lastBossEvent = undefined;
                 result = runResultFor('no-action');
                 handledDeferred = true;
               }
@@ -10268,18 +10567,7 @@ export function createXStatePlaybookRuntime<
                 suppressInspectionEmissions = false;
                 actor.start();
               }
-              // DR-029: keep the classified event with its recorded payload
-              // as the retry-replay source. Recording is sanitizing, not
-              // load-bearing: an override classifier's non-JSON-safe event is
-              // simply not recorded, and the turn proceeds unchanged.
-              try {
-                lastBossEvent = snapshotJsonValue(
-                  event,
-                  'recorded Boss event',
-                ) as unknown as EventObject;
-              } catch {
-                lastBossEvent = undefined;
-              }
+              onAccepted?.();
               actor.send(event);
               await waitForPlaybookQuiescence(actor, {
                 pendingCalls: nestedBridge,
@@ -10587,7 +10875,6 @@ export function createXStatePlaybookRuntime<
             failedGovernedAttemptId = undefined;
             controlPlaneError = undefined;
             emissionFailure = undefined;
-            lastBossEvent = undefined;
             retainedEffectSourceSessionId = undefined;
             retainedEffectReconciliation = undefined;
             retainedEffectReconciliationRequired = false;