@sublang/playbook 5.0.0 → 6.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 =
@@ -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(
@@ -3099,7 +3382,7 @@ export function createXStatePlaybookRuntime<TOptions>(
           schemaVersion: 1,
           playbookId: session.playbookId,
           machine: machineSnapshot,
-          playerResumeTokens: Object.fromEntries(playerResumeTokens),
+          playerResumeTokens: snapshotPlayerResumeTokens(),
           sequences: {
             trace: traceSequence,
             turn: turnSequence,
@@ -3142,6 +3425,10 @@ export function createXStatePlaybookRuntime<TOptions>(
           snapshot,
           boundSession.playbookId,
         );
+        let priorExternalPlayerTokens:
+          | Readonly<Record<string, string>>
+          | undefined;
+        let externalStoreRestoreAttempted = false;
         initialized = true;
         let finishInitialization!: () => void;
         const initialization = new Promise<void>((resolve) => {
@@ -3168,12 +3455,11 @@ export function createXStatePlaybookRuntime<TOptions>(
           // 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);
           suppressInspectionEmissions = true;
           actor = buildActor(runtimePorts, boundSnapshot.machine);
           actor.start();
@@ -3190,8 +3476,22 @@ export function createXStatePlaybookRuntime<TOptions>(
         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 +3907,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 +4106,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.js

@@ -248,6 +248,26 @@ function capturedPort(descriptors, name) {
     }
     return value;
 }
+function capturedSessionStore(descriptors) {
+    const captured = capturedDataValue(descriptors, 'playerSessions', 'playbook session playerSessions');
+    if (!isRecord(captured)) {
+        throw new TypeError('playbook session playerSessions must be an object');
+    }
+    const storeDescriptors = Object.getOwnPropertyDescriptors(captured);
+    const method = (name) => {
+        const value = capturedDataValue(storeDescriptors, name, `playbook session playerSessions.${name}`);
+        if (typeof value !== 'function') {
+            throw new TypeError(`playbook session playerSessions.${name} must be a function`);
+        }
+        return value;
+    };
+    return Object.freeze({
+        select: method('select'),
+        update: method('update'),
+        snapshot: method('snapshot'),
+        restore: method('restore'),
+    });
+}
 /** Validate session causality and detach its immutable identity from the host. */
 export function snapshotPlaybookSession(session) {
     if (!isRecord(session)) {
@@ -266,6 +286,7 @@ export function snapshotPlaybookSession(session) {
     const capturedParentCallId = capturedDataValue(sessionDescriptors, 'parentCallId', 'playbook session parentCallId', false);
     const hasParentSessionId = Object.prototype.hasOwnProperty.call(sessionDescriptors, 'parentSessionId');
     const hasParentCallId = Object.prototype.hasOwnProperty.call(sessionDescriptors, 'parentCallId');
+    const hasPlayerSessions = Object.prototype.hasOwnProperty.call(sessionDescriptors, 'playerSessions');
     let parentSessionId;
     let parentCallId;
     if (depth === 0) {
@@ -296,6 +317,9 @@ export function snapshotPlaybookSession(session) {
         emitStatus: capturedPort(portDescriptors, 'emitStatus'),
         emitTelemetry: capturedPort(portDescriptors, 'emitTelemetry'),
     });
+    const playerSessions = hasPlayerSessions
+        ? capturedSessionStore(sessionDescriptors)
+        : undefined;
     return Object.freeze({
         sessionId,
         playbookId,
@@ -303,6 +327,7 @@ export function snapshotPlaybookSession(session) {
         ...(parentSessionId === undefined ? {} : { parentSessionId }),
         ...(parentCallId === undefined ? {} : { parentCallId }),
         depth,
+        ...(playerSessions === undefined ? {} : { playerSessions }),
         ports,
     });
 }

package/src/xstate-runtime.ts

@@ -342,6 +342,49 @@ function capturedPort<K extends keyof PlaybookSession['ports']>(
   return value as PlaybookSession['ports'][K];
 }
 
+function capturedSessionStore(
+  descriptors: PropertyDescriptorMap,
+): PlaybookSession['playerSessions'] {
+  const captured = capturedDataValue(
+    descriptors,
+    'playerSessions',
+    'playbook session playerSessions',
+  );
+  if (!isRecord(captured)) {
+    throw new TypeError('playbook session playerSessions must be an object');
+  }
+  const storeDescriptors = Object.getOwnPropertyDescriptors(captured);
+  const method = (
+    name: keyof NonNullable<PlaybookSession['playerSessions']>,
+  ): ((...args: never[]) => unknown) => {
+    const value = capturedDataValue(
+      storeDescriptors,
+      name,
+      `playbook session playerSessions.${name}`,
+    );
+    if (typeof value !== 'function') {
+      throw new TypeError(
+        `playbook session playerSessions.${name} must be a function`,
+      );
+    }
+    return value as (...args: never[]) => unknown;
+  };
+  return Object.freeze({
+    select: method('select') as NonNullable<
+      PlaybookSession['playerSessions']
+    >['select'],
+    update: method('update') as NonNullable<
+      PlaybookSession['playerSessions']
+    >['update'],
+    snapshot: method('snapshot') as NonNullable<
+      PlaybookSession['playerSessions']
+    >['snapshot'],
+    restore: method('restore') as NonNullable<
+      PlaybookSession['playerSessions']
+    >['restore'],
+  });
+}
+
 /** Validate session causality and detach its immutable identity from the host. */
 export function snapshotPlaybookSession(
   session: PlaybookSession,
@@ -405,6 +448,10 @@ export function snapshotPlaybookSession(
     sessionDescriptors,
     'parentCallId',
   );
+  const hasPlayerSessions = Object.prototype.hasOwnProperty.call(
+    sessionDescriptors,
+    'playerSessions',
+  );
   let parentSessionId: string | undefined;
   let parentCallId: string | undefined;
   if (depth === 0) {
@@ -450,6 +497,9 @@ export function snapshotPlaybookSession(
     emitStatus: capturedPort(portDescriptors, 'emitStatus'),
     emitTelemetry: capturedPort(portDescriptors, 'emitTelemetry'),
   });
+  const playerSessions = hasPlayerSessions
+    ? capturedSessionStore(sessionDescriptors)
+    : undefined;
   return Object.freeze({
     sessionId,
     playbookId,
@@ -457,6 +507,7 @@ export function snapshotPlaybookSession(
     ...(parentSessionId === undefined ? {} : { parentSessionId }),
     ...(parentCallId === undefined ? {} : { parentCallId }),
     depth,
+    ...(playerSessions === undefined ? {} : { playerSessions }),
     ports,
   });
 }