@sublang/playbook 5.0.0 → 7.0.0

package/src/xstate-playbook-runtime.js

@@ -589,6 +589,48 @@ function collectInvokeSources(machine) {
     visit(machine.config);
     return sources;
 }
+function collectPlayerStatePlayers(machine) {
+    const players = new Map();
+    const visit = (stateDef, stateKey) => {
+        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.config;
+    if (isPlainObject(config) && isPlainObject(config.states)) {
+        for (const [stateKey, stateDef] of Object.entries(config.states)) {
+            visit(stateDef, stateKey);
+        }
+    }
+    return players;
+}
 function transitionTargets(transition) {
     const arms = Array.isArray(transition) ? transition : [transition];
     const targets = [];
@@ -732,16 +774,65 @@ function makeDefaultNormalizeTransitionEvent(transitionEventFields) {
         return snapshotJsonValue(out, 'FSM event');
     };
 }
-function defaultStatusesForState(state, context) {
+function snapshotPlayerStateStatuses(value, label, machine, stateDescriptions) {
+    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();
+    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) {
+    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, context) {
     const stateId = state.stateId;
     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);
@@ -756,6 +847,53 @@ function defaultStatusesForState(state, context) {
     }
     return [{ message: `Entered ${stateId}.` }];
 }
+function makeDefaultStatusesForState(playerStates) {
+    return (state, context, event) => {
+        const statuses = [];
+        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;
+    };
+}
 function classifierState(snapshotOrState) {
     if (snapshotOrState !== null &&
         typeof snapshotOrState === 'object' &&
@@ -1061,6 +1199,8 @@ export function createXStatePlaybookRuntime(machine, spec) {
     // 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
@@ -1100,7 +1240,14 @@ export function createXStatePlaybookRuntime(machine, spec) {
     const classifyBossText = spec.classifyBossText ?? derivedClassifyBossText;
     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) => event.type
+            : () => undefined);
     const machineInput = spec.machineInput ?? ((options) => options);
     const scriptCwd = spec.scriptCwd ??
         ((options) => {
@@ -1138,8 +1285,8 @@ export function createXStatePlaybookRuntime(machine, spec) {
         // 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;
         // DR-029: process-local at-most-once `apply` execution — the accepted receipt
         // recorded for each idempotency key, returned verbatim on a repeated
@@ -1159,6 +1306,56 @@ export function createXStatePlaybookRuntime(machine, spec) {
         // Inspection callbacks enqueue a complete ordered batch synchronously;
         // imperative boundaries await their queued work directly.
         let emissionFailure;
+        function selectPlayerResume(playerId) {
+            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, resumeToken) {
+            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() {
+            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 = {};
+            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) {
+            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) {
             const queued = emissionQueue.add(fn).then(() => undefined);
             activeEmissionCalls.add(queued);
@@ -1315,9 +1512,18 @@ export function createXStatePlaybookRuntime(machine, spec) {
                 // 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;
+                try {
+                    signal.throwIfAborted();
+                    resume = selectPlayerResume(playerId);
+                }
+                catch (error) {
+                    if (!signal.aborted)
+                        controlPlaneError ??= error;
+                    throw error;
+                }
+                const callId = `player-${++playerCallSequence}`;
                 const identity = {
                     purpose: 'captain',
                     ...stateIdentity(stateId),
@@ -1382,12 +1588,22 @@ export function createXStatePlaybookRuntime(machine, spec) {
                         }
                         throw error;
                     }
-                    if (typeof result.resumeToken === 'string' &&
-                        result.resumeToken.trim().length > 0) {
-                        playerResumeTokens.set(playerId, result.resumeToken);
+                    try {
+                        updatePlayerResume(playerId, typeof result.resumeToken === 'string' &&
+                            result.resumeToken.trim().length > 0
+                            ? result.resumeToken
+                            : undefined);
                     }
-                    else {
-                        playerResumeTokens.delete(playerId);
+                    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('player.call.finished', {
                         ...identity,
@@ -2208,18 +2424,42 @@ export function createXStatePlaybookRuntime(machine, spec) {
                         initInFlight = undefined;
                 }
             },
-            // 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() {
                 if (!actor || !session || disposed || disposalPromise !== undefined) {
                     return undefined;
                 }
                 if (activeSignal !== undefined)
                     return undefined;
-                if (nestedBridge.getPendingCall())
+                const pendingCall = nestedBridge.getPendingCall();
+                const bridgeSuspendedCall = nestedBridge.getSuspendedCall();
+                if ((pendingCall === undefined) !== (bridgeSuspendedCall === undefined)) {
                     return undefined;
+                }
+                let suspendedCall;
+                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;
@@ -2228,10 +2468,10 @@ export function createXStatePlaybookRuntime(machine, spec) {
                     .context;
                 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,
@@ -2253,6 +2493,7 @@ export function createXStatePlaybookRuntime(machine, spec) {
                                 sourceItem: pending.sourceItem,
                             },
                         ],
+                    ...(suspendedCall === undefined ? {} : { suspendedCall }),
                 };
             },
             // DR-014 §1 / PBRT-45: alternative to `init` that rehydrates an
@@ -2265,7 +2506,12 @@ export function createXStatePlaybookRuntime(machine, spec) {
                     throw new Error('createPlaybookRuntime.restore: already initialized');
                 }
                 const boundSession = snapshotPlaybookSession(nextSession);
-                const boundSnapshot = assertPlaybookRuntimeSnapshot(snapshot, boundSession.playbookId);
+                const boundSnapshot = assertPlaybookRuntimeSnapshot(snapshot, boundSession.playbookId, { allowSuspendedCall: true });
+                const suspendedCall = boundSnapshot.schemaVersion === 2
+                    ? boundSnapshot.suspendedCall
+                    : undefined;
+                let priorExternalPlayerTokens;
+                let externalStoreRestoreAttempted = false;
                 initialized = true;
                 let finishInitialization;
                 const initialization = new Promise((resolve) => {
@@ -2287,32 +2533,65 @@ export function createXStatePlaybookRuntime(machine, spec) {
                             // 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();
@@ -2662,7 +2941,7 @@ export function createXStatePlaybookRuntime(machine, spec) {
                     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);
                         }
@@ -2843,7 +3122,12 @@ export function createXStatePlaybookRuntime(machine, spec) {
                         }
                     }
                     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();