@sublang/playbook 6.0.0 → 8.0.0

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;

package/src/xstate-runtime.js

@@ -268,6 +268,25 @@ function capturedSessionStore(descriptors) {
         restore: method('restore'),
     });
 }
+function capturedRoleBindings(descriptors) {
+    const captured = snapshotJsonValue(capturedDataValue(descriptors, 'roleBindings', 'playbook session roleBindings'), 'playbook session roleBindings');
+    if (!isRecord(captured)) {
+        throw new TypeError('playbook session roleBindings must be an object');
+    }
+    const bindings = {};
+    for (const [roleId, value] of Object.entries(captured)) {
+        requireNonEmptyString(roleId, 'playbook session roleBindings role id');
+        if (!isRecord(value)) {
+            throw new TypeError(`playbook session roleBindings.${roleId} must be an object`);
+        }
+        rejectUnknownKeys(value, ['playerId', 'promptIdentity'], `playbook session roleBindings.${roleId}`);
+        defineEnumerableDataProperty(bindings, roleId, Object.freeze({
+            playerId: requireNonEmptyString(value.playerId, `playbook session roleBindings.${roleId}.playerId`),
+            promptIdentity: requireNonEmptyString(value.promptIdentity, `playbook session roleBindings.${roleId}.promptIdentity`),
+        }));
+    }
+    return Object.freeze(bindings);
+}
 /** Validate session causality and detach its immutable identity from the host. */
 export function snapshotPlaybookSession(session) {
     if (!isRecord(session)) {
@@ -287,6 +306,7 @@ export function snapshotPlaybookSession(session) {
     const hasParentSessionId = Object.prototype.hasOwnProperty.call(sessionDescriptors, 'parentSessionId');
     const hasParentCallId = Object.prototype.hasOwnProperty.call(sessionDescriptors, 'parentCallId');
     const hasPlayerSessions = Object.prototype.hasOwnProperty.call(sessionDescriptors, 'playerSessions');
+    const hasRoleBindings = Object.prototype.hasOwnProperty.call(sessionDescriptors, 'roleBindings');
     let parentSessionId;
     let parentCallId;
     if (depth === 0) {
@@ -320,6 +340,9 @@ export function snapshotPlaybookSession(session) {
     const playerSessions = hasPlayerSessions
         ? capturedSessionStore(sessionDescriptors)
         : undefined;
+    const roleBindings = hasRoleBindings
+        ? capturedRoleBindings(sessionDescriptors)
+        : undefined;
     return Object.freeze({
         sessionId,
         playbookId,
@@ -327,6 +350,7 @@ export function snapshotPlaybookSession(session) {
         ...(parentSessionId === undefined ? {} : { parentSessionId }),
         ...(parentCallId === undefined ? {} : { parentCallId }),
         depth,
+        ...(roleBindings === undefined ? {} : { roleBindings }),
         ...(playerSessions === undefined ? {} : { playerSessions }),
         ports,
     });
@@ -526,61 +550,153 @@ const SNAPSHOT_SEQUENCE_KEYS = [
     'playerCall',
     'playbookCall',
 ];
-// DR-014 §1: validate and detach a host-supplied runtime snapshot before
-// restore touches any state. Rejects a schema-version or playbook-id
-// mismatch with a path-named error.
-export function assertPlaybookRuntimeSnapshot(value, expectedPlaybookId) {
-    if (!isRecord(value)) {
+function snapshotSuspendedCall(value, path = 'runtime snapshot suspendedCall') {
+    const captured = snapshotJsonValue(value, path);
+    if (!isRecord(captured)) {
+        throw new TypeError(`${path} must be an object`);
+    }
+    rejectUnknownKeys(captured, ['callId', 'stateId', 'playbookId', 'text', 'childSessionId', 'turnId'], path);
+    const call = {
+        callId: requireNonEmptyString(captured.callId, `${path}.callId`),
+        stateId: requireNonEmptyString(captured.stateId, `${path}.stateId`),
+        playbookId: requireNonEmptyString(captured.playbookId, `${path}.playbookId`),
+        text: requireNonEmptyString(captured.text, `${path}.text`),
+        childSessionId: requireNonEmptyString(captured.childSessionId, `${path}.childSessionId`),
+    };
+    if (own(captured, 'turnId')) {
+        if (!Number.isSafeInteger(captured.turnId) ||
+            captured.turnId <= 0) {
+            throw new TypeError(`${path}.turnId must be a positive integer`);
+        }
+        call.turnId = captured.turnId;
+    }
+    return Object.freeze(call);
+}
+// DR-014 §1 / DR-031 §5 / DR-032: validate and detach a host-supplied
+// schema-3 runtime snapshot before restore touches any state. A suspended
+// call is rejected unless the restore path explicitly promises to seed and
+// claim it; older schemas are rejected rather than guessing role identity.
+export function assertPlaybookRuntimeSnapshot(value, expectedPlaybookId, options = {}) {
+    const snapshot = snapshotJsonValue(value, 'runtime snapshot');
+    if (!isRecord(snapshot)) {
         throw new TypeError('runtime snapshot must be an object');
     }
-    if (value.schemaVersion !== 1) {
-        throw new TypeError(`runtime snapshot schemaVersion ${String(value.schemaVersion)} is not supported (expected 1)`);
+    const capturedOptions = snapshotJsonValue(options, 'runtime snapshot validation options');
+    if (!isRecord(capturedOptions)) {
+        throw new TypeError('runtime snapshot validation options must be an object');
+    }
+    rejectUnknownKeys(capturedOptions, ['allowSuspendedCall'], 'runtime snapshot validation options');
+    if (capturedOptions.allowSuspendedCall !== undefined &&
+        typeof capturedOptions.allowSuspendedCall !== 'boolean') {
+        throw new TypeError('runtime snapshot validation options.allowSuspendedCall must be boolean');
+    }
+    const allowSuspendedCall = capturedOptions.allowSuspendedCall ?? false;
+    if (snapshot.schemaVersion !== 3) {
+        throw new TypeError(`runtime snapshot schemaVersion ${String(snapshot.schemaVersion)} is not supported (expected 3)`);
+    }
+    rejectUnknownKeys(snapshot, [
+        'schemaVersion',
+        'playbookId',
+        'machine',
+        'roleResumeTokens',
+        'sequences',
+        'state',
+        'pendingBossQuestions',
+        'suspendedCall',
+    ], 'runtime snapshot');
+    let suspendedCall;
+    if (own(snapshot, 'suspendedCall')) {
+        suspendedCall = snapshotSuspendedCall(snapshot.suspendedCall);
+        if (!allowSuspendedCall) {
+            throw new TypeError('runtime snapshot suspendedCall requires a restore path that explicitly allows it');
+        }
     }
-    const playbookId = requireNonEmptyString(value.playbookId, 'runtime snapshot playbookId');
+    const playbookId = requireNonEmptyString(snapshot.playbookId, 'runtime snapshot playbookId');
     if (playbookId !== expectedPlaybookId) {
         throw new TypeError(`runtime snapshot playbookId ${playbookId} does not match runtime playbook ${expectedPlaybookId}`);
     }
-    if (!isRecord(value.machine)) {
+    if (!isRecord(snapshot.machine)) {
         throw new TypeError('runtime snapshot machine must be an object');
     }
-    const machine = snapshotJsonValue(value.machine, 'runtime snapshot machine');
-    if (!isRecord(value.playerResumeTokens)) {
-        throw new TypeError('runtime snapshot playerResumeTokens must be an object');
+    const machine = snapshot.machine;
+    if (!isRecord(snapshot.roleResumeTokens)) {
+        throw new TypeError('runtime snapshot roleResumeTokens must be an object');
     }
-    const playerResumeTokens = {};
-    for (const [playerId, token] of Object.entries(value.playerResumeTokens)) {
-        defineEnumerableDataProperty(playerResumeTokens, playerId, requireNonEmptyString(token, `runtime snapshot playerResumeTokens.${playerId}`));
+    const roleResumeTokens = {};
+    for (const [roleId, token] of Object.entries(snapshot.roleResumeTokens)) {
+        defineEnumerableDataProperty(roleResumeTokens, requireNonEmptyString(roleId, 'runtime snapshot roleResumeTokens role id'), requireNonEmptyString(token, `runtime snapshot roleResumeTokens.${roleId}`));
     }
-    if (!isRecord(value.sequences)) {
+    if (!isRecord(snapshot.sequences)) {
         throw new TypeError('runtime snapshot sequences must be an object');
     }
+    rejectUnknownKeys(snapshot.sequences, [...SNAPSHOT_SEQUENCE_KEYS, 'captainCall'], 'runtime snapshot sequences');
     const sequences = {};
     for (const key of SNAPSHOT_SEQUENCE_KEYS) {
-        const sequence = value.sequences[key];
+        const sequence = snapshot.sequences[key];
         if (!Number.isSafeInteger(sequence) || sequence < 0) {
             throw new TypeError(`runtime snapshot sequences.${key} must be a non-negative integer`);
         }
         sequences[key] = sequence;
     }
-    const captainCall = value.sequences.captainCall;
+    const captainCall = snapshot.sequences.captainCall;
     if (captainCall !== undefined) {
         if (!Number.isSafeInteger(captainCall) || captainCall < 0) {
             throw new TypeError('runtime snapshot sequences.captainCall must be a non-negative integer');
         }
         sequences.captainCall = captainCall;
     }
-    validateState(value.state, 'runtime snapshot state');
-    const state = snapshotJsonValue(value.state, 'runtime snapshot state');
-    if (!Array.isArray(value.pendingBossQuestions)) {
+    validateState(snapshot.state, 'runtime snapshot state');
+    const state = snapshot.state;
+    if (state.tags.includes(SUSPENDED_TAG) && suspendedCall === undefined) {
+        throw new TypeError(`runtime snapshot state tagged ${SUSPENDED_TAG} requires suspendedCall`);
+    }
+    if (suspendedCall) {
+        if (sequences.playbookCall === 0) {
+            throw new TypeError('runtime snapshot suspendedCall requires sequences.playbookCall greater than zero');
+        }
+        if (suspendedCall.turnId !== undefined &&
+            suspendedCall.turnId > sequences.turn) {
+            throw new TypeError('runtime snapshot suspendedCall.turnId must not exceed sequences.turn');
+        }
+        if (state.status !== 'active' || !state.quiescent) {
+            throw new TypeError('runtime snapshot suspendedCall requires an active quiescent state');
+        }
+        if (!state.tags.includes(SUSPENDED_TAG)) {
+            throw new TypeError(`runtime snapshot suspendedCall requires state tag ${SUSPENDED_TAG}`);
+        }
+        if (!state.activeStateIds.includes(suspendedCall.stateId)) {
+            throw new TypeError('runtime snapshot suspendedCall.stateId must be active in snapshot state');
+        }
+    }
+    if (!Array.isArray(snapshot.pendingBossQuestions)) {
         throw new TypeError('runtime snapshot pendingBossQuestions must be an array');
     }
-    const pendingBossQuestions = value.pendingBossQuestions.map((entry, index) => {
+    const pendingBossQuestions = snapshot.pendingBossQuestions.map((entry, index) => {
         const path = `runtime snapshot pendingBossQuestions[${index}]`;
         if (!isRecord(entry))
             throw new TypeError(`${path} must be an object`);
+        rejectUnknownKeys(entry, ['questionId', 'asker', 'question', 'sourceItem'], path);
+        if (!isRecord(entry.asker)) {
+            throw new TypeError(`${path}.asker must be an object`);
+        }
+        let asker;
+        if (entry.asker.kind === 'captain') {
+            rejectUnknownKeys(entry.asker, ['kind'], `${path}.asker`);
+            asker = Object.freeze({ kind: 'captain' });
+        }
+        else if (entry.asker.kind === 'role') {
+            rejectUnknownKeys(entry.asker, ['kind', 'roleId'], `${path}.asker`);
+            asker = Object.freeze({
+                kind: 'role',
+                roleId: requireNonEmptyString(entry.asker.roleId, `${path}.asker.roleId`),
+            });
+        }
+        else {
+            throw new TypeError(`${path}.asker.kind must be "captain" or "role"`);
+        }
         const question = {
             questionId: requireNonEmptyString(entry.questionId, `${path}.questionId`),
-            player: requireNonEmptyString(entry.player, `${path}.player`),
+            asker,
             question: requireNonEmptyString(entry.question, `${path}.question`),
             ...(entry.sourceItem === undefined
                 ? {}
@@ -590,14 +706,18 @@ export function assertPlaybookRuntimeSnapshot(value, expectedPlaybookId) {
         };
         return Object.freeze(question);
     });
-    return Object.freeze({
-        schemaVersion: 1,
+    const fields = {
         playbookId,
         machine,
-        playerResumeTokens: Object.freeze(playerResumeTokens),
+        roleResumeTokens: Object.freeze(roleResumeTokens),
         sequences: Object.freeze(sequences),
         state,
         pendingBossQuestions: Object.freeze(pendingBossQuestions),
+    };
+    return Object.freeze({
+        schemaVersion: 3,
+        ...fields,
+        ...(suspendedCall === undefined ? {} : { suspendedCall }),
     });
 }
 export class NestedPlaybookCallError extends Error {
@@ -689,6 +809,9 @@ export function validatePlayerResult(value, path = 'player result') {
     rejectUnknownKeys(result, ['status', 'resumeToken', 'finalText', 'error'], path);
     validateRunStatus(result.status, `${path}.status`);
     validateOptionalString(result, 'resumeToken', path);
+    if (result.resumeToken !== undefined) {
+        requireNonEmptyString(result.resumeToken, `${path}.resumeToken`);
+    }
     validateOptionalString(result, 'finalText', path);
     validateOptionalString(result, 'error', path);
     return result;
@@ -821,6 +944,7 @@ function outputOrThrow(result) {
 }
 export function createNestedPlaybookBridge(options) {
     let current;
+    let restoreMode;
     let disposed = false;
     const usedCallIds = new Set();
     const pendingListeners = new Set();
@@ -853,10 +977,29 @@ export function createNestedPlaybookBridge(options) {
             childSessionId: active.childSessionId,
         }
         : undefined;
-    const clear = (active) => {
+    const suspendedIdentity = (active) => active?.phase === 'suspended' && active.childSessionId
+        ? Object.freeze({
+            callId: active.callId,
+            stateId: active.input.stateId,
+            playbookId: active.input.playbookId,
+            text: active.input.text,
+            childSessionId: active.childSessionId,
+            ...(active.turnId === undefined ? {} : { turnId: active.turnId }),
+        })
+        : undefined;
+    const failRestoreMode = (mode, error) => {
+        mode.state = 'failed';
+        mode.error = error;
+        reportControlPlaneError(error);
+    };
+    const detachAbortListener = (active) => {
         if (active.abortListener) {
             active.signal.removeEventListener('abort', active.abortListener);
+            active.abortListener = undefined;
         }
+    };
+    const clear = (active) => {
+        detachAbortListener(active);
         if (current === active)
             current = undefined;
     };
@@ -972,23 +1115,171 @@ export function createNestedPlaybookBridge(options) {
             throw error;
         }
     };
+    const rollbackRestoredCall = (mode, error) => {
+        const active = mode.active;
+        mode.state = 'failed';
+        mode.error = error;
+        mode.active = undefined;
+        if (!active)
+            return undefined;
+        active.phase = 'settling';
+        active.restoreRolledBack = true;
+        clear(active);
+        usedCallIds.delete(active.callId);
+        active.deferred.reject(error);
+        return active;
+    };
+    const publishSuspendedCall = (active) => {
+        if (active.phase !== 'suspended') {
+            throw new Error(`playbook call ${active.callId} is not suspended`);
+        }
+        const abortListener = () => {
+            if (active.phase !== 'suspended')
+                return;
+            const result = resultFromThrown(active.input.playbookId, active.childSessionId, active.signal.reason ?? new Error('Nested playbook invocation aborted'), true);
+            void settlePending(active, result).catch((error) => {
+                reportBackgroundError(error);
+            });
+        };
+        active.abortListener = abortListener;
+        active.signal.addEventListener('abort', abortListener, { once: true });
+        const pendingCall = pendingIdentity(active);
+        if (!pendingCall) {
+            throw new Error('suspended call identity was not recorded');
+        }
+        for (const listener of pendingListeners) {
+            try {
+                listener(pendingCall);
+            }
+            catch (error) {
+                reportBackgroundError(error);
+            }
+        }
+        if (active.signal.aborted)
+            abortListener();
+    };
+    const waitOnSuspendedCall = async (active) => {
+        publishSuspendedCall(active);
+        return await active.deferred.promise;
+    };
     const actorLogic = fromPromise(async ({ input, signal: invocationSignal }) => {
         if (disposed) {
             rejectControlPlane(new Error('nested playbook bridge is disposed'));
         }
+        const normalizedInput = (() => {
+            try {
+                return {
+                    stateId: requireNonEmptyString(input.stateId, 'playbook input stateId'),
+                    playbookId: requireNonEmptyString(input.playbookId, 'playbook input playbookId'),
+                    text: requireNonEmptyString(input.text, 'playbook input text'),
+                };
+            }
+            catch (error) {
+                const mode = restoreMode;
+                if (mode) {
+                    if (mode.state === 'claimed') {
+                        rollbackRestoredCall(mode, error);
+                        reportControlPlaneError(error);
+                    }
+                    else
+                        failRestoreMode(mode, error);
+                    throw error;
+                }
+                return rejectControlPlane(error);
+            }
+        })();
+        const mode = restoreMode;
+        if (mode) {
+            if (mode.state !== 'armed') {
+                const callId = mode.call?.callId ?? 'without a descriptor';
+                const error = new Error(mode.state === 'claimed'
+                    ? `restored playbook call ${callId} was claimed more than once`
+                    : `restored playbook call ${callId} is no longer claimable`);
+                if (mode.state === 'claimed')
+                    rollbackRestoredCall(mode, error);
+                else
+                    mode.error ??= error;
+                reportControlPlaneError(error);
+                throw error;
+            }
+            const seed = mode.call;
+            if (!seed) {
+                const error = new Error('restored machine invoked a nested playbook without a suspendedCall descriptor');
+                failRestoreMode(mode, error);
+                throw error;
+            }
+            for (const field of ['stateId', 'playbookId', 'text']) {
+                if (normalizedInput[field] !== seed[field]) {
+                    const error = new Error(`restored playbook call ${seed.callId} ${field} does not match its persisted input`);
+                    failRestoreMode(mode, error);
+                    throw error;
+                }
+            }
+            if (usedCallIds.has(seed.callId)) {
+                const error = new Error(`restored duplicate playbook call id ${seed.callId}`);
+                failRestoreMode(mode, error);
+                throw error;
+            }
+            const controller = new AbortController();
+            let callSignal;
+            try {
+                callSignal = combineAbortSignals(invocationSignal, options.getBoundarySignal?.(), controller.signal);
+            }
+            catch (error) {
+                failRestoreMode(mode, error);
+                throw error;
+            }
+            const active = {
+                callId: seed.callId,
+                input: normalizedInput,
+                ...(seed.turnId === undefined
+                    ? {}
+                    : { turnId: seed.turnId }),
+                deferred: deferred(),
+                finished: deferred(),
+                controller,
+                signal: callSignal,
+                phase: 'restoring',
+                childSessionId: seed.childSessionId,
+            };
+            usedCallIds.add(active.callId);
+            current = active;
+            mode.state = 'claimed';
+            mode.active = active;
+            const restoreAbortListener = () => {
+                if (restoreMode !== mode ||
+                    mode.state !== 'claimed' ||
+                    mode.active !== active ||
+                    active.phase !== 'restoring') {
+                    return;
+                }
+                rollbackRestoredCall(mode, active.signal.reason ??
+                    new Error('Restored nested playbook invocation aborted'));
+            };
+            active.abortListener = restoreAbortListener;
+            active.signal.addEventListener('abort', restoreAbortListener, {
+                once: true,
+            });
+            if (active.signal.aborted)
+                restoreAbortListener();
+            try {
+                return await active.deferred.promise;
+            }
+            catch (error) {
+                if (!active.restoreRolledBack)
+                    active.runError = error;
+                throw error;
+            }
+            finally {
+                active.finished.resolve(undefined);
+            }
+        }
         if (current) {
             rejectControlPlane(new Error(`playbook call ${current.callId} is already outstanding`));
         }
-        const [normalizedInput, callId] = (() => {
+        const callId = (() => {
             try {
-                return [
-                    {
-                        stateId: requireNonEmptyString(input.stateId, 'playbook input stateId'),
-                        playbookId: requireNonEmptyString(input.playbookId, 'playbook input playbookId'),
-                        text: requireNonEmptyString(input.text, 'playbook input text'),
-                    },
-                    requireNonEmptyString(options.nextCallId(), 'allocated playbook call id'),
-                ];
+                return requireNonEmptyString(options.nextCallId(), 'allocated playbook call id');
             }
             catch (error) {
                 return rejectControlPlane(error);
@@ -1119,32 +1410,7 @@ export function createNestedPlaybookBridge(options) {
             }
             active.phase = 'suspended';
             active.childSessionId = start.childSessionId;
-            const abortListener = () => {
-                if (active.phase !== 'suspended')
-                    return;
-                const result = resultFromThrown(active.input.playbookId, active.childSessionId, active.signal.reason ??
-                    new Error('Nested playbook invocation aborted'), true);
-                void settlePending(active, result).catch((error) => {
-                    reportBackgroundError(error);
-                });
-            };
-            active.abortListener = abortListener;
-            active.signal.addEventListener('abort', abortListener, { once: true });
-            const pendingCall = pendingIdentity(active);
-            if (!pendingCall) {
-                throw new Error('suspended call identity was not recorded');
-            }
-            for (const listener of pendingListeners) {
-                try {
-                    listener(pendingCall);
-                }
-                catch (error) {
-                    reportBackgroundError(error);
-                }
-            }
-            if (active.signal.aborted)
-                abortListener();
-            return await active.deferred.promise;
+            return await waitOnSuspendedCall(active);
         }
         catch (error) {
             active.runError = error;
@@ -1155,6 +1421,16 @@ export function createNestedPlaybookBridge(options) {
         }
     });
     const abortPending = async (error = new Error('Nested playbook call aborted')) => {
+        const mode = restoreMode;
+        if (mode) {
+            restoreMode = undefined;
+            const restored = mode.state === 'claimed'
+                ? rollbackRestoredCall(mode, error)
+                : undefined;
+            if (restored)
+                await restored.finished.promise;
+            return;
+        }
         const active = current;
         if (!active)
             return;
@@ -1182,6 +1458,70 @@ export function createNestedPlaybookBridge(options) {
     return {
         actorLogic,
         getPendingCall: () => pendingIdentity(current),
+        getSuspendedCall: () => suspendedIdentity(current),
+        prepareRestore(call) {
+            // Capture the complete host-owned descriptor before observing or
+            // mutating bridge state, so a rejected preparation cannot leave state.
+            const captured = call === undefined
+                ? undefined
+                : snapshotSuspendedCall(call, 'restored playbook call');
+            if (disposed) {
+                rejectControlPlane(new Error('nested playbook bridge is disposed'));
+            }
+            if (current) {
+                rejectControlPlane(new Error(`playbook call ${current.callId} is already outstanding`));
+            }
+            if (restoreMode) {
+                rejectControlPlane(new Error('nested playbook bridge restore is already prepared'));
+            }
+            if (captured && usedCallIds.has(captured.callId)) {
+                rejectControlPlane(new Error(`restored duplicate playbook call id ${captured.callId}`));
+            }
+            restoreMode = {
+                ...(captured === undefined ? {} : { call: captured }),
+                state: 'armed',
+            };
+        },
+        confirmRestore() {
+            const mode = restoreMode;
+            if (!mode) {
+                throw new Error('nested playbook bridge restore is not prepared');
+            }
+            if (mode.state === 'failed') {
+                restoreMode = undefined;
+                throw mode.error;
+            }
+            if (mode.call === undefined) {
+                restoreMode = undefined;
+                return;
+            }
+            if (mode.state !== 'claimed' || !mode.active) {
+                const error = new Error(`restored playbook call ${mode.call.callId} was not claimed by actor startup`);
+                restoreMode = undefined;
+                reportControlPlaneError(error);
+                throw error;
+            }
+            const active = mode.active;
+            if (active.signal.aborted) {
+                const error = active.signal.reason ??
+                    new Error('Restored nested playbook invocation aborted');
+                rollbackRestoredCall(mode, error);
+                restoreMode = undefined;
+                throw error;
+            }
+            try {
+                detachAbortListener(active);
+                active.phase = 'suspended';
+                restoreMode = undefined;
+                publishSuspendedCall(active);
+            }
+            catch (error) {
+                rollbackRestoredCall(mode, error);
+                restoreMode = undefined;
+                reportControlPlaneError(error);
+                throw error;
+            }
+        },
         subscribePendingCall(listener) {
             if (disposed)
                 return () => undefined;
@@ -1237,6 +1577,7 @@ export function createNestedPlaybookBridge(options) {
                 }
             }
             finally {
+                restoreMode = undefined;
                 pendingListeners.clear();
             }
         },