@sublang/playbook 5.0.0 → 7.0.0

package/src/xstate-playbook-runtime.ts

@@ -150,6 +150,12 @@ export interface ScheduledStatus {
   data?: JsonValue;
 }
 
+/** Boss-facing identity for one FSM state whose invoked actor is `player`. */
+export interface XStatePlayerStateStatus {
+  player: string;
+  label: string;
+}
+
 export interface XStateBossEventFieldSpec {
   /** The judge supplies routing data; the runtime supplies exact Boss text. */
   source: 'judge' | 'text';
@@ -391,8 +397,10 @@ export interface XStatePlaybookRuntimeSpec<TOptions> {
    * recoverable FSM-result failures instead.
    */
   captainStrategy?: XStateCaptainStrategy<TOptions>;
-  /** Status line emitted after classification names an event. Default: none. */
+  /** Status line emitted after classification; canonical metadata defaults to the event type, legacy artifacts to none. */
   classificationStatus?: (event: EventObject) => string | undefined;
+  /** Complete FSM-derived Boss-facing metadata for every `player` state; its presence selects the canonical status profile. */
+  playerStates?: Readonly<Record<string, XStatePlayerStateStatus>>;
   /** Map a player-invoking state's input to the host player id. Default: lowercased player name. */
   resolvePlayerId?: (input: PlaybookPlayerInput, options: TOptions) => string;
   /** Compose the player prompt. Default: continuation blocks + `<field>` placeholder substitution. */
@@ -421,7 +429,7 @@ export interface XStatePlaybookRuntimeSpec<TOptions> {
   controlContextFields?: readonly string[];
   /** States that may suspend for a Boss reply. Default: targets of the FSM's `awaitBossReply` BOSS_REPLY transitions. */
   resumableStateIds?: ReadonlySet<string>;
-  /** Human status lines for a root transition. Default: entry lines with question/failure surfacing. */
+  /** Human status lines for a root transition. Default: guard, declared-player, question, and failure lines. */
   statusesForState?: (
     state: PlaybookState,
     context: Record<string, unknown>,
@@ -1055,6 +1063,60 @@ function collectInvokeSources(machine: AnyStateMachine): ReadonlySet<string> {
   return sources;
 }
 
+function collectPlayerStatePlayers(
+  machine: AnyStateMachine,
+): ReadonlyMap<string, string> {
+  const players = new Map<string, string>();
+  const visit = (stateDef: unknown, stateKey: string): void => {
+    if (!isPlainObject(stateDef)) return;
+    const invoke = stateDef.invoke;
+    const invokes = Array.isArray(invoke) ? invoke : invoke ? [invoke] : [];
+    if (
+      invokes.some(
+        (entry) =>
+          isPlainObject(entry) && entry.src === 'player',
+      )
+    ) {
+      const playbookMeta = isPlainObject(stateDef.meta)
+        ? stateDef.meta.playbook
+        : undefined;
+      const stateId =
+        isPlainObject(playbookMeta) &&
+        typeof playbookMeta.stateId === 'string'
+          ? playbookMeta.stateId
+          : typeof stateDef.id === 'string'
+            ? stateDef.id
+            : stateKey;
+      if (stateId.trim().length === 0) {
+        throw new TypeError(
+          'player state metadata must use a non-empty state id',
+        );
+      }
+      const player = isPlainObject(playbookMeta)
+        ? playbookMeta.player
+        : undefined;
+      if (typeof player !== 'string' || player.trim().length === 0) {
+        throw new TypeError(
+          `player state ${stateId} meta.playbook.player must be a non-empty string`,
+        );
+      }
+      players.set(stateId, player);
+    }
+    if (isPlainObject(stateDef.states)) {
+      for (const [childKey, child] of Object.entries(stateDef.states)) {
+        visit(child, childKey);
+      }
+    }
+  };
+  const config = (machine as unknown as { config?: unknown }).config;
+  if (isPlainObject(config) && isPlainObject(config.states)) {
+    for (const [stateKey, stateDef] of Object.entries(config.states)) {
+      visit(stateDef, stateKey);
+    }
+  }
+  return players;
+}
+
 function transitionTargets(transition: unknown): string[] {
   const arms = Array.isArray(transition) ? transition : [transition];
   const targets: string[] = [];
@@ -1206,7 +1268,70 @@ function makeDefaultNormalizeTransitionEvent(
   };
 }
 
-function defaultStatusesForState(
+function snapshotPlayerStateStatuses(
+  value: Readonly<Record<string, XStatePlayerStateStatus>> | undefined,
+  label: string,
+  machine: AnyStateMachine,
+  stateDescriptions: ReadonlyMap<string, string>,
+): ReadonlyMap<string, XStatePlayerStateStatus> {
+  if (value === undefined) return new Map();
+  if (!isPlainObject(value)) {
+    throw new TypeError(`${label} playerStates must be an object`);
+  }
+  const declared = collectPlayerStatePlayers(machine);
+  const statuses = new Map<string, XStatePlayerStateStatus>();
+  for (const [stateId, candidate] of Object.entries(value)) {
+    if (!declared.has(stateId)) {
+      throw new TypeError(
+        `${label} playerStates.${stateId} does not name a player state`,
+      );
+    }
+    if (
+      !isPlainObject(candidate) ||
+      typeof candidate.player !== 'string' ||
+      candidate.player.trim().length === 0 ||
+      typeof candidate.label !== 'string' ||
+      candidate.label.trim().length === 0
+    ) {
+      throw new TypeError(
+        `${label} playerStates.${stateId} must carry non-empty player and label strings`,
+      );
+    }
+    const expectedLabel = stateDescriptions.get(stateId);
+    if (candidate.label !== expectedLabel) {
+      throw new TypeError(
+        `${label} playerStates.${stateId}.label must equal its FSM description`,
+      );
+    }
+    if (candidate.player !== declared.get(stateId)) {
+      throw new TypeError(
+        `${label} playerStates.${stateId}.player must equal its FSM player`,
+      );
+    }
+    statuses.set(stateId, {
+      player: candidate.player,
+      label: candidate.label,
+    });
+  }
+  for (const stateId of declared.keys()) {
+    if (!statuses.has(stateId)) {
+      throw new TypeError(
+        `${label} playerStates must declare player state ${stateId}`,
+      );
+    }
+  }
+  return statuses;
+}
+
+function settlingGuard(event: unknown): string | undefined {
+  if (!isPlainObject(event) || !isPlainObject(event.output)) return undefined;
+  const guard = event.output.guard;
+  return typeof guard === 'string' && guard.trim().length > 0
+    ? guard
+    : undefined;
+}
+
+function legacyStatusesForState(
   state: PlaybookState,
   context: Record<string, unknown>,
 ): ScheduledStatus[] {
@@ -1214,11 +1339,14 @@ function defaultStatusesForState(
   if (stateId === undefined || SUPPRESSED_ENTRY_STATES.has(stateId)) return [];
   if (stateId === 'awaitBossReply') {
     const pending = pendingBossQuestionFromContext(context);
-    const message =
-      pending === undefined
-        ? 'Awaiting Boss reply.'
-        : `${pending.player} asks: ${pending.question}`;
-    return [{ message }];
+    return [
+      {
+        message:
+          pending === undefined
+            ? 'Awaiting Boss reply.'
+            : `${pending.player} asks: ${pending.question}`,
+      },
+    ];
   }
   if (stateId === 'failed') {
     const lastError = normalizeErrorFull(context.lastError);
@@ -1234,6 +1362,60 @@ function defaultStatusesForState(
   return [{ message: `Entered ${stateId}.` }];
 }
 
+function makeDefaultStatusesForState(
+  playerStates: ReadonlyMap<string, XStatePlayerStateStatus>,
+): NonNullable<XStatePlaybookRuntimeSpec<unknown>['statusesForState']> {
+  return (state, context, event): ScheduledStatus[] => {
+    const statuses: ScheduledStatus[] = [];
+    const guard = settlingGuard(event);
+    if (guard !== undefined) statuses.push({ message: `→ ${guard}` });
+
+    const stateId = state.stateId;
+    if (stateId === undefined || SUPPRESSED_ENTRY_STATES.has(stateId)) {
+      return statuses;
+    }
+    if (stateId === 'awaitBossReply') {
+      const pending = pendingBossQuestionFromContext(context);
+      if (pending === undefined) {
+        return [...statuses, { message: 'Awaiting Boss reply.' }];
+      }
+      return [
+        ...statuses,
+        { message: `${pending.player} asks: ${pending.question}` },
+        {
+          message:
+            `◆ awaiting Boss reply · ${pending.resumeStateId} · ` +
+            `${pending.player} · ${pending.sourceItem}`,
+        },
+      ];
+    }
+    if (stateId === 'failed') {
+      const lastError = normalizeErrorCompact(context.lastError);
+      return [
+        ...statuses,
+        {
+          message: '◆ workflow failed; awaiting Boss recovery.',
+          ...(lastError === undefined
+            ? {}
+            : {
+                data: snapshotJsonValue(
+                  { lastError },
+                  'failed status data',
+                ),
+              }),
+        },
+      ];
+    }
+    const playerState = playerStates.get(stateId);
+    if (playerState !== undefined) {
+      statuses.push({
+        message: `⤷ ${playerState.player}: ${playerState.label}`,
+      });
+    }
+    return statuses;
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Default parked-state classifier (slc/link.md §Boss-event mapping): the
 // runtime-owned textual fields are never requested from the judge; only the
@@ -1675,6 +1857,13 @@ export function createXStatePlaybookRuntime<TOptions>(
   // DR-029: source state descriptions label the control actions the
   // runtime advertises through `describe()`.
   const stateDescriptions = stateDescriptionsFromMachine(machine);
+  const hasCanonicalStatusProfile = spec.playerStates !== undefined;
+  const playerStates = snapshotPlayerStateStatuses(
+    spec.playerStates,
+    label,
+    machine,
+    stateDescriptions,
+  );
   // PBRT-52: the artifact's own ControlView context projection. Nothing is
   // exported by default, so an FSM context member — including one added
   // after this artifact was linked — is private until named here. The two
@@ -1728,7 +1917,16 @@ export function createXStatePlaybookRuntime<TOptions>(
   const normalizeTransitionEvent =
     spec.normalizeTransitionEvent ??
     makeDefaultNormalizeTransitionEvent(spec.transitionEventFields ?? []);
-  const statusesForState = spec.statusesForState ?? defaultStatusesForState;
+  const statusesForState =
+    spec.statusesForState ??
+    (hasCanonicalStatusProfile
+      ? makeDefaultStatusesForState(playerStates)
+      : legacyStatusesForState);
+  const classificationStatus =
+    spec.classificationStatus ??
+    (hasCanonicalStatusProfile
+      ? (event: EventObject) => event.type
+      : () => undefined);
   const machineInput =
     spec.machineInput ?? ((options: TOptions) => options as unknown);
   const scriptCwd =
@@ -1770,8 +1968,8 @@ export function createXStatePlaybookRuntime<TOptions>(
     // 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 schema-1
-    // parked snapshot does not persist it (PBRT-50: no schema bump).
+    // 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
@@ -1793,6 +1991,71 @@ export function createXStatePlaybookRuntime<TOptions>(
     // imperative boundaries await their queued work directly.
     let emissionFailure: unknown;
 
+    function selectPlayerResume(playerId: string): string | false {
+      const selected = session?.playerSessions
+        ? session.playerSessions.select(playerId)
+        : playerResumeTokens.get(playerId) ?? false;
+      if (
+        selected !== false &&
+        (typeof selected !== 'string' || selected.trim().length === 0)
+      ) {
+        throw new TypeError(
+          `player session store returned an invalid resume token for ${playerId}`,
+        );
+      }
+      return selected;
+    }
+
+    function updatePlayerResume(
+      playerId: string,
+      resumeToken: string | undefined,
+    ): void {
+      if (session?.playerSessions) {
+        session.playerSessions.update(playerId, resumeToken);
+      } else if (resumeToken !== undefined && resumeToken.trim().length > 0) {
+        playerResumeTokens.set(playerId, resumeToken);
+      } else {
+        playerResumeTokens.delete(playerId);
+      }
+    }
+
+    function snapshotPlayerResumeTokens(): Record<string, string> {
+      const raw = session?.playerSessions
+        ? session.playerSessions.snapshot()
+        : Object.fromEntries(playerResumeTokens);
+      if (!isPlainObject(raw)) {
+        throw new TypeError('player session store snapshot must be an object');
+      }
+      const detached: Record<string, string> = {};
+      for (const [playerId, token] of Object.entries(raw)) {
+        if (playerId.trim().length === 0) {
+          throw new TypeError(
+            'player session store snapshot player ids must be non-empty',
+          );
+        }
+        if (typeof token !== 'string' || token.trim().length === 0) {
+          throw new TypeError(
+            `player session store snapshot token for ${playerId} must be a non-empty string`,
+          );
+        }
+        detached[playerId] = token;
+      }
+      return detached;
+    }
+
+    function restorePlayerResumeTokens(
+      tokens: Readonly<Record<string, string>>,
+    ): void {
+      if (session?.playerSessions) {
+        session.playerSessions.restore(tokens);
+        return;
+      }
+      playerResumeTokens.clear();
+      for (const [playerId, token] of Object.entries(tokens)) {
+        playerResumeTokens.set(playerId, token);
+      }
+    }
+
     function enqueueEmission(fn: () => Promise<void>): Promise<void> {
       const queued = emissionQueue.add(fn).then(() => undefined);
       activeEmissionCalls.add(queued);
@@ -2001,9 +2264,16 @@ export function createXStatePlaybookRuntime<TOptions>(
         // State-entry telemetry/status must precede the call they describe.
         await drainEmissions();
         const turnId = activeTurnId;
-        const callId = `player-${++playerCallSequence}`;
         const stateId = input.stateId;
-        const resume = playerResumeTokens.get(playerId) ?? false;
+        let resume: string | false;
+        try {
+          signal.throwIfAborted();
+          resume = selectPlayerResume(playerId);
+        } catch (error) {
+          if (!signal.aborted) controlPlaneError ??= error;
+          throw error;
+        }
+        const callId = `player-${++playerCallSequence}`;
         const identity = {
           purpose: 'captain' as const,
           ...stateIdentity(stateId),
@@ -2095,13 +2365,26 @@ export function createXStatePlaybookRuntime<TOptions>(
             throw error;
           }
 
-          if (
-            typeof result.resumeToken === 'string' &&
-            result.resumeToken.trim().length > 0
-          ) {
-            playerResumeTokens.set(playerId, result.resumeToken);
-          } else {
-            playerResumeTokens.delete(playerId);
+          try {
+            updatePlayerResume(
+              playerId,
+              typeof result.resumeToken === 'string' &&
+                result.resumeToken.trim().length > 0
+                ? result.resumeToken
+                : undefined,
+            );
+          } catch (error) {
+            if (!signal.aborted) controlPlaneError ??= error;
+            try {
+              await emitTrace(
+                'player.call.finished',
+                { ...identity, status: 'error', error: normalizeError(error) },
+                position,
+              );
+            } catch {
+              // The continuation-store failure remains authoritative.
+            }
+            throw error;
           }
 
           await emitTrace(
@@ -3077,16 +3360,45 @@ export function createXStatePlaybookRuntime<TOptions>(
         }
       },
 
-      // DR-014 §1 / PBRT-45: JSON-safe capture of a parked session.
+      // DR-014 §1 / DR-031 §5 / PBRT-45: JSON-safe capture of a parked
+      // session, including one already-started suspended nested call.
       // Defined only at a safe capture point — initialized, not disposing
-      // or disposed, no active public boundary, no pending nested call,
-      // and the actor quiescent with status `active`.
+      // 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 (nestedBridge.getPendingCall()) 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 }),
+          };
+        }
         const state = currentState();
         if (state.status !== 'active' || !state.quiescent) return undefined;
         const machineSnapshot = detachPersistedMachineSnapshot(
@@ -3096,10 +3408,10 @@ export function createXStatePlaybookRuntime<TOptions>(
           .context as Record<string, unknown>;
         const pending = pendingBossQuestionFromContext(context ?? {});
         return {
-          schemaVersion: 1,
+          schemaVersion: 2,
           playbookId: session.playbookId,
           machine: machineSnapshot,
-          playerResumeTokens: Object.fromEntries(playerResumeTokens),
+          playerResumeTokens: snapshotPlayerResumeTokens(),
           sequences: {
             trace: traceSequence,
             turn: turnSequence,
@@ -3122,6 +3434,7 @@ export function createXStatePlaybookRuntime<TOptions>(
                     sourceItem: pending.sourceItem,
                   },
                 ],
+          ...(suspendedCall === undefined ? {} : { suspendedCall }),
         };
       },
 
@@ -3141,7 +3454,16 @@ export function createXStatePlaybookRuntime<TOptions>(
         const boundSnapshot = assertPlaybookRuntimeSnapshot(
           snapshot,
           boundSession.playbookId,
+          { allowSuspendedCall: true },
         );
+        const suspendedCall =
+          boundSnapshot.schemaVersion === 2
+            ? boundSnapshot.suspendedCall
+            : undefined;
+        let priorExternalPlayerTokens:
+          | Readonly<Record<string, string>>
+          | undefined;
+        let externalStoreRestoreAttempted = false;
         initialized = true;
         let finishInitialization!: () => void;
         const initialization = new Promise<void>((resolve) => {
@@ -3163,35 +3485,79 @@ export function createXStatePlaybookRuntime<TOptions>(
             // Every Captain call already consumed at least one trace number,
             // so the global trace counter is a collision-safe id floor.
             boundSnapshot.sequences.trace;
-          // The schema-1 snapshot carries no apply counter (PBRT-50: no
-          // schema bump); every apply boundary consumed trace numbers, so
-          // the persisted trace counter is a collision-safe id floor here
-          // too, keeping `apply-<n>` call ids unique across restore.
+          // The runtime snapshot carries no apply counter (PBRT-50); every
+          // apply boundary consumed trace numbers, so the persisted trace
+          // counter is a collision-safe id floor here too, keeping
+          // `apply-<n>` call ids unique across restore.
           applyCallSequence = boundSnapshot.sequences.trace;
-          playerResumeTokens.clear();
-          for (const [playerId, token] of Object.entries(
-            boundSnapshot.playerResumeTokens,
-          )) {
-            playerResumeTokens.set(playerId, token);
+          if (boundSession.playerSessions) {
+            priorExternalPlayerTokens = snapshotPlayerResumeTokens();
+            externalStoreRestoreAttempted = true;
+          }
+          restorePlayerResumeTokens(boundSnapshot.playerResumeTokens);
+          nestedBridge.prepareRestore(suspendedCall);
+          if (suspendedCall !== undefined) {
+            playbookCallTurnIds.set(
+              suspendedCall.callId,
+              suspendedCall.turnId,
+            );
           }
           suppressInspectionEmissions = true;
           actor = buildActor(runtimePorts, boundSnapshot.machine);
           actor.start();
-          const restoredState = currentState();
+          if (controlPlaneError !== undefined) throw controlPlaneError;
+          const restoredState = normalizePlaybookSnapshot(
+            actor.getSnapshot(),
+            suspendedCall === undefined
+              ? {}
+              : {
+                  pendingCall: {
+                    callId: suspendedCall.callId,
+                    playbookId: suspendedCall.playbookId,
+                    childSessionId: suspendedCall.childSessionId,
+                  },
+                },
+          );
           if (restoredState.status !== 'active') {
             throw new Error(
               `createPlaybookRuntime.restore: restored actor status is ${restoredState.status}, expected active`,
             );
           }
-          suppressInspectionEmissions = false;
+          if (
+            stableJson(restoredState, 'restored runtime state') !==
+            stableJson(boundSnapshot.state, 'runtime snapshot state')
+          ) {
+            throw new Error(
+              'createPlaybookRuntime.restore: restored actor state does not match snapshot state',
+            );
+          }
           priorState = restoredState;
           await drainEmissions();
+          suppressInspectionEmissions = false;
+          // Final fallible step: after this publication the authoritative
+          // child has rejoined ordinary resume/abort ownership, so no later
+          // restore validation may trigger failed-start rollback.
+          nestedBridge.confirmRestore();
         })();
         try {
           await initTask;
         } catch (error) {
-          await cleanupFailedStart(error, { emitDisposal: false });
-          throw error;
+          let failure = error;
+          if (
+            externalStoreRestoreAttempted &&
+            priorExternalPlayerTokens !== undefined
+          ) {
+            try {
+              boundSession.playerSessions!.restore(priorExternalPlayerTokens);
+            } catch (rollbackError) {
+              failure = new AggregateError(
+                [error, rollbackError],
+                'createPlaybookRuntime.restore and player continuation rollback failed',
+              );
+            }
+          }
+          await cleanupFailedStart(failure, { emitDisposal: false });
+          throw failure;
         } finally {
           finishInitialization();
           if (initInFlight === initialization) initInFlight = undefined;
@@ -3607,7 +3973,7 @@ export function createXStatePlaybookRuntime<TOptions>(
           } else {
             // 2. Optional Captain-pane classification line: the bare FSM
             //    event type, emitted before the FSM advances.
-            const statusLine = spec.classificationStatus?.(event);
+            const statusLine = classificationStatus(event);
             if (statusLine !== undefined) {
               await runtimePorts!.emitStatus(statusLine);
             }
@@ -3806,7 +4172,12 @@ export function createXStatePlaybookRuntime<TOptions>(
               }
             }
           } finally {
-            playerResumeTokens.clear();
+            // A composing host owns the shared store for the complete root
+            // engagement tree. Child disposal must not erase a token its
+            // caller will resume. The private fallback remains runtime-owned.
+            if (session?.playerSessions === undefined) {
+              playerResumeTokens.clear();
+            }
             activePlayerIds.clear();
             playbookCallTurnIds.clear();
             activeEmissionCalls.clear();

package/src/xstate-runtime.d.ts

@@ -1,5 +1,5 @@
 import { type AnyActorRef, type PromiseActorLogic, type SnapshotFrom } from 'xstate';
-import type { CaptainResult, JsonValue, NormalizedError, PlaybookCallRequest, PlaybookCallResult, PlaybookCallStart, PlaybookPendingCall, PlaybookRuntimeSnapshot, PlaybookSession, PlaybookState, PlayerResult } from './runtime.js';
+import type { CaptainResult, JsonValue, NormalizedError, PlaybookCallRequest, PlaybookCallResult, PlaybookCallStart, PlaybookPendingCall, PlaybookRuntimeSnapshot, PlaybookSession, PlaybookState, PlaybookSuspendedCall, PlayerResult } from './runtime.js';
 export * from './xstate-playbook-runtime.js';
 /**
  * Compose invocation-lifetime and imperative-boundary cancellation without
@@ -31,7 +31,15 @@ export interface SnapshotNormalizationOptions {
 }
 export declare function normalizePlaybookSnapshot(snapshot: unknown, options?: SnapshotNormalizationOptions): PlaybookState;
 export declare function detachPersistedMachineSnapshot(persisted: unknown): JsonValue;
-export declare function assertPlaybookRuntimeSnapshot(value: unknown, expectedPlaybookId: string): PlaybookRuntimeSnapshot;
+export interface PlaybookRuntimeSnapshotValidationOptions {
+    /**
+     * Opt in only when the restore path will prepare and confirm the suspended
+     * call transaction. The default is fail-closed so a legacy restore cannot
+     * reopen or ignore it.
+     */
+    allowSuspendedCall?: boolean;
+}
+export declare function assertPlaybookRuntimeSnapshot(value: unknown, expectedPlaybookId: string, options?: PlaybookRuntimeSnapshotValidationOptions): PlaybookRuntimeSnapshot;
 export interface NestedPlaybookInput {
     stateId: string;
     playbookId: string;
@@ -68,6 +76,15 @@ export interface PendingCallObserver {
 }
 export interface NestedPlaybookBridge<TInput extends NestedPlaybookInput = NestedPlaybookInput> extends PendingCallObserver {
     actorLogic: PromiseActorLogic<JsonValue | undefined, TInput>;
+    /** Arm fail-closed actor startup for a snapshot with zero or one nested call. */
+    prepareRestore(call?: PlaybookSuspendedCall): void;
+    /**
+     * Commit restore startup after the persisted machine recreated exactly the
+     * expected zero or one nested invocation.
+     */
+    confirmRestore(): void;
+    /** Complete durable identity; undefined until a normal or restored call suspends. */
+    getSuspendedCall(): PlaybookSuspendedCall | undefined;
     resume(input: {
         callId: string;
         result: PlaybookCallResult;