@sublang/playbook 6.0.0 → 7.0.0

package/src/xstate-runtime.js

@@ -526,58 +526,135 @@ 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: validate and detach a host-supplied runtime
+// snapshot before restore touches any state. A suspended schema-2 call is
+// rejected unless the restore path explicitly promises to seed and claim it.
+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 !== 1 && snapshot.schemaVersion !== 2) {
+        throw new TypeError(`runtime snapshot schemaVersion ${String(snapshot.schemaVersion)} is not supported (expected 1 or 2)`);
+    }
+    const schemaVersion = snapshot.schemaVersion;
+    rejectUnknownKeys(snapshot, [
+        'schemaVersion',
+        'playbookId',
+        'machine',
+        'playerResumeTokens',
+        'sequences',
+        'state',
+        'pendingBossQuestions',
+        'suspendedCall',
+    ], 'runtime snapshot');
+    if (schemaVersion === 1 && own(snapshot, 'suspendedCall')) {
+        throw new TypeError('runtime snapshot schemaVersion 1 must not carry suspendedCall');
+    }
+    let suspendedCall;
+    if (schemaVersion === 2 && 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)) {
+    const machine = snapshot.machine;
+    if (!isRecord(snapshot.playerResumeTokens)) {
         throw new TypeError('runtime snapshot playerResumeTokens must be an object');
     }
     const playerResumeTokens = {};
-    for (const [playerId, token] of Object.entries(value.playerResumeTokens)) {
+    for (const [playerId, token] of Object.entries(snapshot.playerResumeTokens)) {
         defineEnumerableDataProperty(playerResumeTokens, playerId, requireNonEmptyString(token, `runtime snapshot playerResumeTokens.${playerId}`));
     }
-    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 schemaVersion 2 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', 'player', 'question', 'sourceItem'], path);
         const question = {
             questionId: requireNonEmptyString(entry.questionId, `${path}.questionId`),
             player: requireNonEmptyString(entry.player, `${path}.player`),
@@ -590,14 +667,21 @@ export function assertPlaybookRuntimeSnapshot(value, expectedPlaybookId) {
         };
         return Object.freeze(question);
     });
-    return Object.freeze({
-        schemaVersion: 1,
+    const fields = {
         playbookId,
         machine,
         playerResumeTokens: Object.freeze(playerResumeTokens),
         sequences: Object.freeze(sequences),
         state,
         pendingBossQuestions: Object.freeze(pendingBossQuestions),
+    };
+    if (schemaVersion === 1) {
+        return Object.freeze({ schemaVersion: 1, ...fields });
+    }
+    return Object.freeze({
+        schemaVersion: 2,
+        ...fields,
+        ...(suspendedCall === undefined ? {} : { suspendedCall }),
     });
 }
 export class NestedPlaybookCallError extends Error {
@@ -821,6 +905,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 +938,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 +1076,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 +1371,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 +1382,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 +1419,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 +1538,7 @@ export function createNestedPlaybookBridge(options) {
                 }
             }
             finally {
+                restoreMode = undefined;
                 pendingListeners.clear();
             }
         },