@sublang/playbook 4.0.0 → 6.0.0

package/src/xstate-playbook-runtime.ts

@@ -41,6 +41,9 @@ import type {
   CaptainResult,
   JsonValue,
   PlaybookCallResult,
+  PlaybookControlAction,
+  PlaybookControlReceipt,
+  PlaybookControlView,
   PlaybookPorts,
   PlaybookRunResult,
   PlaybookRuntime,
@@ -124,14 +127,35 @@ export interface RuntimeBoundaryCalls {
     input: PlaybookCaptainInput,
     prompt: string,
     signal: AbortSignal,
+    callOptions?: XStateCaptainCallOptions,
   ): Promise<CaptainResult>;
 }
 
+/**
+ * Presentation selection for one traced direct-Captain call
+ * (slc/link.md §Captain adjudication). `'visible'` (the default) is the
+ * workflow form: the port receives `{ visibility: 'visible', resume: false }`
+ * and the trace pair carries both members. `'hidden'` is the controller form
+ * (DR-029): the port receives `{ visibility: 'hidden', resume: false }`
+ * while the host's session-Captain wrapper owns the actual durable-conversation
+ * resume selection, so the trace pair carries `visibility: 'hidden'` and no
+ * `resume` member — the pinned token never enters runtime telemetry.
+ */
+export interface XStateCaptainCallOptions {
+  visibility?: 'visible' | 'hidden';
+}
+
 export interface ScheduledStatus {
   message: string;
   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';
@@ -177,6 +201,37 @@ function isFsmResultFailure(error: unknown): boolean {
   );
 }
 
+// ---------------------------------------------------------------------------
+// DR-028: both call boundaries treat an `ok` result whose `finalText` is
+// missing, empty, or whitespace-only under one empty predicate, and that
+// shape earns exactly one corrective re-ask — the same composed call
+// re-issued once through the same boundary — before a second such result
+// follows the existing failure path. The retry marker distinguishes the
+// re-askable empty-`ok` Captain failure from the never-retried non-`ok`
+// statuses; it is applied only when the failure's finish trace emitted
+// cleanly, because a rejecting finish sink is a control-plane error whose
+// turn gets no corrective re-ask (PBRT-47).
+// ---------------------------------------------------------------------------
+
+function isEmptyFinalText(finalText: string | undefined): boolean {
+  return finalText === undefined || finalText.trim().length === 0;
+}
+
+const emptyOkRetryFailures = new WeakSet<object>();
+
+function markEmptyOkRetryFailure(error: Error): Error {
+  emptyOkRetryFailures.add(error);
+  return error;
+}
+
+function isEmptyOkRetryFailure(error: unknown): boolean {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    emptyOkRetryFailures.has(error as object)
+  );
+}
+
 // ---------------------------------------------------------------------------
 // DR-022: the engine's compatibility self-report. A linked thin module
 // records the values current at link time in `spec.compat`; the factory
@@ -248,6 +303,53 @@ function assertRuntimeCompat(
 // to preserve their existing observable behavior exactly.
 // ---------------------------------------------------------------------------
 
+/**
+ * One direct-Captain actor invocation handed to a spec's `captainStrategy`
+ * (slc/link.md §Captain adjudication, controller form). The engine owns
+ * signal combination, emission draining, trace pairing, the shared
+ * Captain/judge lane, and control-plane latching; the strategy owns the
+ * playbook-specific call pipeline — e.g. the controller's hidden decision
+ * call, `{ action, … }` control-JSON validation with its single corrective
+ * re-ask, and controller-port submission.
+ */
+export interface XStateCaptainStrategyRun<TOptions> {
+  input: PlaybookCaptainInput;
+  /** The prompt composed by the spec's Captain composer for `input`. */
+  prompt: string;
+  /** Combined invocation-lifetime + active-boundary abort signal. */
+  signal: AbortSignal;
+  /** The immutable validated runtime options. */
+  options: TOptions;
+  /** The bound immutable playbook session identity. */
+  session: PlaybookSession;
+  /**
+   * One traced Captain call through the shared serialized lane; every call —
+   * initial or corrective — emits its own paired `captain.call.started` /
+   * `captain.call.finished` boundary. Throws the boundary's authoritative
+   * failure for non-`ok` and empty-`ok` results exactly as the default
+   * pipeline does.
+   */
+  callCaptain(
+    prompt: string,
+    callOptions?: XStateCaptainCallOptions,
+  ): Promise<CaptainResult>;
+  /**
+   * DR-028: true when `error` is the boundary's re-askable empty-`ok`
+   * marker; the strategy may re-issue the same composed call exactly once.
+   */
+  isEmptyOkRetry(error: unknown): boolean;
+  /**
+   * Mark `error` as a recoverable FSM-result failure: it travels the invoked
+   * actor's XState `onError` path without being latched as a control-plane
+   * error, so the machine's authored recovery arms can route it.
+   */
+  recoverableFailure<E extends Error>(error: E): E;
+}
+
+export type XStateCaptainStrategy<TOptions> = (
+  run: XStateCaptainStrategyRun<TOptions>,
+) => Promise<PlaybookActorOutput>;
+
 export interface XStatePlaybookRuntimeSpec<TOptions> {
   /** Diagnostic label used in internal invariant errors. Default 'playbook'. */
   label?: string;
@@ -276,16 +378,29 @@ export interface XStatePlaybookRuntimeSpec<TOptions> {
    * the XState machine alone.
    */
   bossEvents?: readonly XStateBossEventSpec[];
-  /** Boss-input classifier override; default: generic parked-state classifier. */
+  /** Boss-input classifier override; default: generic parked-state classifier. Receives the bound validated options last so a fully deterministic controller mapping can consult host-supplied option members (slc/link.md §Boss-event mapping). */
   classifyBossText?: (
     text: string,
     ports: PlaybookPorts,
     signal: AbortSignal,
     snapshotOrState: unknown,
     boundary?: RuntimeBoundaryCalls,
+    options?: TOptions,
   ) => Promise<EventObject | undefined>;
-  /** Status line emitted after classification names an event. Default: none. */
+  /**
+   * Direct-Captain actor strategy override (slc/link.md §Captain
+   * adjudication, controller form): replaces the default visible-call +
+   * hidden-judge pipeline for every `captain` state of this machine. The
+   * engine still composes the prompt, combines signals, traces each call as
+   * its own pair, and latches control-plane errors; failures the strategy
+   * marks with `recoverableFailure` travel the actor's `onError` path as
+   * recoverable FSM-result failures instead.
+   */
+  captainStrategy?: XStateCaptainStrategy<TOptions>;
+  /** 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. */
@@ -300,9 +415,21 @@ export interface XStatePlaybookRuntimeSpec<TOptions> {
   extractRequiredFields?: (description: string) => string[];
   /** Required fields carried verbatim from the player's finalText instead of judge JSON. Default: none. */
   verbatimPayloadFields?: ReadonlySet<string>;
+  /**
+   * DR-029 / PBRT-52: the runtime-authored ControlView context
+   * projection — the exact FSM context members `describe()` may expose,
+   * in the order the view lists them. Only this artifact knows which of
+   * its context members are safe and relevant for a controller prompt, so
+   * the engine exports what is named here and nothing else: a member the
+   * artifact has not named stays private, and a member added to the FSM
+   * later stays private until someone names it. Absent or empty: the view
+   * carries no context at all. `pendingBossQuestion` and `lastError` are
+   * surfaced first-class by the view and shall not be named here.
+   */
+  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>,
@@ -730,8 +857,10 @@ function validateBossReplyOutput(
 // ---------------------------------------------------------------------------
 // Delegated-player actor bridge. One PromiseActorLogic the machine invokes
 // from every player-invoking state: resolve the playerId, compose the prompt,
-// await callPlayer, adjudicate the finalText. A non-`ok` result or missing
-// finalText throws so XState routes via onError to the FSM's failure sink.
+// await callPlayer, adjudicate the finalText. An `ok` result with a missing,
+// empty, or whitespace-only finalText earns exactly one corrective re-ask of
+// the same composed call (DR-028); a non-`ok` result, or a second such empty
+// result, throws so XState routes via onError to the FSM's failure sink.
 //
 // `getActiveSignal` flows the Boss's public-boundary signal into the host
 // port calls — fromPromise hands the bridge XState's actor-scoped signal,
@@ -757,17 +886,40 @@ export function createPlayerBridge(
       const activeSignal = combineAbortSignals(signal, getActiveSignal?.());
       const playerId = spec.resolvePlayerId(input);
       const prompt = spec.composePlayerPrompt(input);
-      const result = boundary
-        ? await boundary.callPlayer(input, playerId, prompt, activeSignal)
-        : await ports.callPlayer(playerId, prompt, activeSignal, {
-            resume: false,
-          });
+      const callPlayer = (resume: string | false) =>
+        boundary
+          ? boundary.callPlayer(input, playerId, prompt, activeSignal)
+          : ports.callPlayer(playerId, prompt, activeSignal, { resume });
+      let result = await callPlayer(false);
+      if (result.status === 'ok' && isEmptyFinalText(result.finalText)) {
+        // An abort that lands between the empty first result and the
+        // corrective call ends the turn as ordinary abort settlement with
+        // no second host call — aborts are never retried (DR-028 via
+        // DR-025's transport exclusion) — matching the direct-Captain
+        // boundary, whose queued corrective call re-checks the signal
+        // before starting.
+        activeSignal.throwIfAborted();
+        // DR-028: exactly one corrective re-ask of the same composed call
+        // through the same path, traced by the boundary as its own
+        // player-call pair. The traced boundary re-reads its token map
+        // (PBRT-38), so the corrective call continues the player session
+        // when the first result carried a resume token and starts fresh
+        // when it cleared one; the portless verification path mirrors that
+        // by carrying the first result's token.
+        result = await callPlayer(
+          typeof result.resumeToken === 'string' &&
+            result.resumeToken.trim().length > 0
+            ? result.resumeToken
+            : false,
+        );
+      }
       if (result.status !== 'ok') {
         throw new Error(
           result.error ?? `captainBridge: callPlayer status "${result.status}"`,
         );
       }
-      if (result.finalText === undefined) {
+      const finalText = result.finalText ?? '';
+      if (isEmptyFinalText(finalText)) {
         throw new Error(
           'captainBridge: callPlayer returned status=ok with no finalText',
         );
@@ -776,7 +928,7 @@ export function createPlayerBridge(
         const output = await adjudicatePlayerOutput(
           spec.adjudication,
           input,
-          result.finalText,
+          finalText,
           ports,
           activeSignal,
           boundary,
@@ -911,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[] = [];
@@ -941,6 +1147,98 @@ export function resumableStateIdsFromMachine(
   return new Set(transitionTargets(bossReply));
 }
 
+// ---------------------------------------------------------------------------
+// DR-029 control surface: the FSM's explicit-state-jump event and the
+// source state descriptions that label runtime-advertised actions.
+// ---------------------------------------------------------------------------
+
+/** The FSM's explicit-state-jump event type (slc/link.md §Boss-event mapping). */
+const JUMP_EVENT_TYPE = 'BOSS_INTERRUPT';
+
+/**
+ * Source state descriptions by state key, node id, and `meta.playbook`
+ * state id, read from `machine.config`. Control actions are labeled from
+ * these descriptions (DR-029); a state without one has no entry.
+ */
+export function stateDescriptionsFromMachine(
+  machine: AnyStateMachine,
+): ReadonlyMap<string, string> {
+  const descriptions = new Map<string, string>();
+  const record = (key: unknown, description: string): void => {
+    if (typeof key !== 'string' || key.length === 0) return;
+    if (!descriptions.has(key)) descriptions.set(key, description);
+  };
+  const visit = (key: string, stateDef: unknown): void => {
+    if (!isPlainObject(stateDef)) return;
+    const playbook = isPlainObject(stateDef.meta)
+      ? (stateDef.meta as Record<string, unknown>).playbook
+      : undefined;
+    const description =
+      isPlainObject(playbook) && typeof playbook.description === 'string'
+        ? playbook.description
+        : typeof stateDef.description === 'string'
+          ? stateDef.description
+          : undefined;
+    if (description !== undefined && description.length > 0) {
+      record(key, description);
+      record(stateDef.id, description);
+      if (isPlainObject(playbook)) record(playbook.stateId, description);
+    }
+    if (isPlainObject(stateDef.states)) {
+      for (const [childKey, child] of Object.entries(stateDef.states)) {
+        visit(childKey, child);
+      }
+    }
+  };
+  const config = (machine as unknown as { config?: unknown }).config;
+  if (isPlainObject(config) && isPlainObject(config.states)) {
+    for (const [key, stateDef] of Object.entries(config.states)) {
+      visit(key, stateDef);
+    }
+  }
+  return descriptions;
+}
+
+/**
+ * First configured target of `eventType` from the state with `stateId`,
+ * falling back to the machine root's own transitions. Used only to pick the
+ * source description that labels a retry action, and only for events that
+ * carry no recorded `targetId`: a guarded multi-arm list keyed on the
+ * event's `targetId` (the root `BOSS_INTERRUPT` shape) resumes the recorded
+ * target, not the first configured arm, so the recorded event outranks this
+ * fallback.
+ */
+function firstTransitionTarget(
+  machine: AnyStateMachine,
+  stateId: string | undefined,
+  eventType: string,
+): string | undefined {
+  const config = (machine as unknown as { config?: unknown }).config;
+  if (!isPlainObject(config)) return undefined;
+  const candidates: unknown[] = [];
+  if (stateId !== undefined && isPlainObject(config.states)) {
+    const state = config.states[stateId];
+    if (isPlainObject(state) && isPlainObject(state.on)) {
+      candidates.push(state.on[eventType]);
+    }
+  }
+  if (isPlainObject(config.on)) candidates.push(config.on[eventType]);
+  for (const candidate of candidates) {
+    if (candidate === undefined) continue;
+    const targets = transitionTargets(candidate);
+    if (targets.length > 0) return targets[0];
+  }
+  return undefined;
+}
+
+function deepFreeze<T>(value: T): T {
+  if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const member of Object.values(value)) deepFreeze(member);
+  }
+  return value;
+}
+
 // ---------------------------------------------------------------------------
 // Default transition/status derivation.
 // ---------------------------------------------------------------------------
@@ -970,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[] {
@@ -978,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);
@@ -998,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
@@ -1399,6 +1817,16 @@ interface TracePosition {
   callId?: string;
 }
 
+function machineDeclaresParallelState(machine: AnyStateMachine): boolean {
+  const visit = (stateDef: unknown): boolean => {
+    if (!isPlainObject(stateDef)) return false;
+    if (stateDef.type === 'parallel') return true;
+    if (!isPlainObject(stateDef.states)) return false;
+    return Object.values(stateDef.states).some(visit);
+  };
+  return visit((machine as unknown as { config?: unknown }).config);
+}
+
 /**
  * Build a `PlaybookRuntimeFactory` that interprets the given FSM artifact
  * under the slc/link.md contract. The factory provides every actor kind the
@@ -1406,8 +1834,9 @@ interface TracePosition {
  * (literal and dynamic) — and implements the full runtime lifecycle including
  * the optional parked-session snapshot capability (DR-014).
  *
- * Scope: single-region root machines (each snapshot exposes exactly one
- * playbook state id). Parallel-region FSMs keep their own linked runtimes.
+ * Scope: machines that declare no parallel state (each snapshot exposes
+ * exactly one playbook state id). Parallel-region FSMs keep their own linked
+ * runtimes.
  */
 export function createXStatePlaybookRuntime<TOptions>(
   machine: AnyStateMachine,
@@ -1417,9 +1846,40 @@ export function createXStatePlaybookRuntime<TOptions>(
   // DR-022 / PBRT-50: reject an incompatible artifact declaration before any
   // machine interpretation, against this loaded engine's own self-report.
   assertRuntimeCompat(spec.compat, label);
+  if (machineDeclaresParallelState(machine)) {
+    throw new Error(
+      `${label} uses a parallel state; the shared runtime supports only single-region FSMs`,
+    );
+  }
   const declaredActors = collectInvokeSources(machine);
   const resumableStateIds =
     spec.resumableStateIds ?? resumableStateIdsFromMachine(machine);
+  // 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
+  // members the view surfaces first-class are rejected at construction
+  // rather than silently ignored, so an artifact cannot believe it is
+  // exporting them through this list.
+  const controlContextFields: readonly string[] = spec.controlContextFields
+    ? [...spec.controlContextFields]
+    : [];
+  for (const field of controlContextFields) {
+    if (field === 'pendingBossQuestion' || field === 'lastError') {
+      throw new Error(
+        `${label} controlContextFields must not name ${field}: the control view surfaces it first-class`,
+      );
+    }
+  }
   const resolvePlayerIdSpec = spec.resolvePlayerId;
   const composePlayerPrompt =
     spec.composePlayerPrompt ??
@@ -1451,11 +1911,22 @@ export function createXStatePlaybookRuntime<TOptions>(
     spec.entryEvent,
     spec.bossEvents ?? [],
   );
-  const classifyBossText = spec.classifyBossText ?? derivedClassifyBossText;
+  const classifyBossText: NonNullable<
+    XStatePlaybookRuntimeSpec<TOptions>['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: EventObject) => event.type
+      : () => undefined);
   const machineInput =
     spec.machineInput ?? ((options: TOptions) => options as unknown);
   const scriptCwd =
@@ -1493,6 +1964,19 @@ export function createXStatePlaybookRuntime<TOptions>(
     let playerCallSequence = 0;
     let playbookCallSequence = 0;
     let captainCallSequence = 0;
+    let applyCallSequence = 0;
+    // 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).
+    let lastBossEvent: EventObject | undefined;
+    // DR-029: process-local at-most-once `apply` execution — the accepted receipt
+    // recorded for each idempotency key, returned verbatim on a repeated
+    // key. A key whose call settled `rejected` or threw before reaching
+    // acceptance records nothing, so a later call with that key may still
+    // execute.
+    const appliedReceipts = new Map<string, PlaybookControlReceipt>();
     const playerResumeTokens = new Map<string, string>();
     const activePlayerIds = new Set<string>();
     const playbookCallTurnIds = new Map<string, number | undefined>();
@@ -1507,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);
@@ -1672,13 +2221,22 @@ export function createXStatePlaybookRuntime<TOptions>(
       startedType:
         | 'player.call.started'
         | 'judge.call.started'
-        | 'captain.call.started',
+        | 'captain.call.started'
+        | 'apply.started',
       finishedType:
         | 'player.call.finished'
         | 'judge.call.finished'
-        | 'captain.call.finished',
+        | 'captain.call.finished'
+        | 'apply.finished',
       identity: Record<string, unknown>,
       position: TracePosition,
+      // Base payload of the best-effort finish emitted when the start sink
+      // rejects; it defaults to the payload the start carried, which the
+      // player, judge, and captain pairs take as-is. The apply pair cannot:
+      // its finish carries the receipt disposition and none of the
+      // start-only fields, so it passes its own canonical pre-acceptance
+      // base (slc/link.md §Playbook trace).
+      finishIdentity: Record<string, unknown> = identity,
     ): Promise<void> {
       try {
         await emitTrace(startedType, identity, position);
@@ -1687,7 +2245,11 @@ export function createXStatePlaybookRuntime<TOptions>(
         try {
           await emitTrace(
             finishedType,
-            { ...identity, status: 'error', error: normalizeError(error) },
+            {
+              ...finishIdentity,
+              status: 'error',
+              error: normalizeError(error),
+            },
             position,
           );
         } catch {
@@ -1702,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),
@@ -1745,6 +2314,11 @@ export function createXStatePlaybookRuntime<TOptions>(
 
           let rawResult: unknown;
           try {
+            // An abort may land while the awaited started emission drains
+            // (e.g. fired from the trace sink itself); the host call must
+            // never start after abort, so settle the already-started pair
+            // as `aborted` through the catch below.
+            signal.throwIfAborted();
             rawResult = await requireHostPorts().callPlayer(
               playerId,
               prompt,
@@ -1791,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(
@@ -1846,6 +2433,11 @@ export function createXStatePlaybookRuntime<TOptions>(
           );
           let reply: unknown;
           try {
+            // An abort may land while the awaited started emission drains
+            // (e.g. fired from the trace sink itself); the host call must
+            // never start after abort, so settle the already-started pair
+            // as `aborted` through the catch below.
+            signal.throwIfAborted();
             reply = await requireHostPorts().callJudge(prompt, signal);
             signal.throwIfAborted();
           } catch (error) {
@@ -1889,18 +2481,23 @@ export function createXStatePlaybookRuntime<TOptions>(
         }) as Promise<string>;
       },
 
-      async callCaptain(input, prompt, signal): Promise<CaptainResult> {
+      async callCaptain(input, prompt, signal, callOptions): Promise<CaptainResult> {
         return judgeQueue.add(async () => {
           signal.throwIfAborted();
           await drainEmissions();
           signal.throwIfAborted();
           const turnId = activeTurnId;
           const callId = `captain-${++captainCallSequence}`;
+          const visibility = callOptions?.visibility ?? 'visible';
           const identity = {
             ...stateIdentity(input.stateId),
             sourceItem: input.sourceItem,
-            visibility: 'visible' as const,
-            resume: false as const,
+            visibility,
+            // The visible workflow form owns its `resume: false` selection;
+            // a hidden controller call's durable-conversation resume
+            // selection is host-owned (DR-029), so its trace pair carries
+            // no resume member and no token.
+            ...(visibility === 'visible' ? { resume: false as const } : {}),
             ...(input.allowedTools === undefined
               ? {}
               : { allowedTools: [...input.allowedTools] }),
@@ -1918,8 +2515,13 @@ export function createXStatePlaybookRuntime<TOptions>(
           );
           let rawResult: unknown;
           try {
+            // An abort may land while the awaited started emission drains
+            // (e.g. fired from the trace sink itself); the host call must
+            // never start after abort, so settle the already-started pair
+            // as `aborted` through the catch below.
+            signal.throwIfAborted();
             rawResult = await requireHostPorts().callCaptain(prompt, signal, {
-              visibility: 'visible',
+              visibility,
               resume: false,
               ...(input.allowedTools !== undefined
                 ? { allowedTools: input.allowedTools }
@@ -1956,6 +2558,7 @@ export function createXStatePlaybookRuntime<TOptions>(
           // authoritative for the actor's error path even when the required
           // finish emission fails or a coincident boundary abort lands.
           let resultFailure: Error | undefined;
+          let emptyOkRetry = false;
           if (result.status !== 'ok') {
             resultFailure = markFsmResultFailure(
               new Error(
@@ -1963,12 +2566,13 @@ export function createXStatePlaybookRuntime<TOptions>(
                   `captainActor: callCaptain status "${result.status}"`,
               ),
             );
-          } else if (result.finalText === undefined || result.finalText === '') {
+          } else if (isEmptyFinalText(result.finalText)) {
             resultFailure = markFsmResultFailure(
               new Error(
                 'captainActor: callCaptain returned status=ok with no finalText',
               ),
             );
+            emptyOkRetry = true;
           }
           try {
             await emitTrace(
@@ -1990,12 +2594,17 @@ export function createXStatePlaybookRuntime<TOptions>(
           } catch (error) {
             // Keep the finish-sink failure in the emission queue for public
             // cleanup evidence, but do not replace an authoritative result
-            // failure on the invoked actor's XState onError path.
+            // failure on the invoked actor's XState onError path. A failure
+            // thrown here is never marked re-askable: a rejecting finish
+            // sink stays a control-plane error with no corrective re-ask
+            // (PBRT-47).
             if (resultFailure !== undefined) throw resultFailure;
             throw error;
           }
           if (resultFailure !== undefined) {
-            throw resultFailure;
+            throw emptyOkRetry
+              ? markEmptyOkRetryFailure(resultFailure)
+              : resultFailure;
           }
           return result;
         }) as Promise<CaptainResult>;
@@ -2041,19 +2650,53 @@ export function createXStatePlaybookRuntime<TOptions>(
           try {
             await drainEmissions();
             const prompt = composeCaptainPrompt(input);
-            const result = await boundary.callCaptain!(input, prompt, active);
+            if (spec.captainStrategy !== undefined) {
+              // Controller form (slc/link.md §Captain adjudication): the
+              // spec's strategy owns the call pipeline; the engine still
+              // owns tracing, the shared lane, signal combination, and the
+              // control-plane latch in the catch below.
+              const output = await spec.captainStrategy({
+                input,
+                prompt,
+                signal: active,
+                options: boundOptions,
+                session: requireSession(),
+                callCaptain: (callPrompt, callOptions) =>
+                  boundary.callCaptain!(input, callPrompt, active, callOptions),
+                isEmptyOkRetry: isEmptyOkRetryFailure,
+                recoverableFailure: <E extends Error>(error: E): E => {
+                  markFsmResultFailure(error);
+                  return error;
+                },
+              });
+              validateBossReplyOutput(input, output, resumableStateIds);
+              return output;
+            }
+            let result: CaptainResult;
+            try {
+              result = await boundary.callCaptain!(input, prompt, active);
+            } catch (error) {
+              if (!isEmptyOkRetryFailure(error)) throw error;
+              // DR-028: exactly one corrective re-ask of the same composed
+              // call through the same boundary, traced as its own
+              // started/finished pair, its result read under the unchanged
+              // rules — a second empty `ok` result throws from the boundary
+              // exactly as the first did, with no further re-ask.
+              result = await boundary.callCaptain!(input, prompt, active);
+            }
             // The boundary owns result validation (PBRT-47) and throws the
             // authoritative failure itself, so a returned result is always
             // `ok` with visible text. Assert that invariant rather than
             // restating the failure semantics, which would drift.
-            if (result.status !== 'ok' || !result.finalText) {
+            const finalText = result.finalText ?? '';
+            if (result.status !== 'ok' || isEmptyFinalText(finalText)) {
               throw new Error(
                 'captainActor: boundary returned an unvalidated Captain result',
               );
             }
             const judgePrompt = defaultBuildCaptainJudgePrompt(
               input,
-              result.finalText,
+              finalText,
             );
             const raw = await boundary.callJudge(
               'captain-output-adjudication',
@@ -2064,7 +2707,7 @@ export function createXStatePlaybookRuntime<TOptions>(
             const output = adjudicateCaptainOutput(
               extractFields,
               input,
-              result.finalText,
+              finalText,
               raw,
             );
             validateBossReplyOutput(input, output, resumableStateIds);
@@ -2284,6 +2927,20 @@ export function createXStatePlaybookRuntime<TOptions>(
       else emissionFailure ??= error;
     }
 
+    // PBRT-6: the single seam that stops this runtime's actor. Stopping a
+    // still-running actor fires one more `@xstate.snapshot` for the
+    // *unchanged* state value with `status: 'stopped'`, which the inspect
+    // callback cannot distinguish from a state entry — unsuppressed it
+    // re-emits the parked state's statuses and a phantom self-loop
+    // transition. Suppression is a property of stopping, not a rule each
+    // caller must remember, so every stop goes through here; a caller that
+    // builds a replacement actor clears the flag before starting it.
+    function stopActor(): void {
+      if (!actor) return;
+      suppressInspectionEmissions = true;
+      actor.stop();
+    }
+
     function buildActor(
       ports: PlaybookPorts,
       machineSnapshot?: JsonValue,
@@ -2434,9 +3091,8 @@ export function createXStatePlaybookRuntime<TOptions>(
           // A state that cannot even normalize has no disposal descriptor.
         }
       }
-      suppressInspectionEmissions = true;
       try {
-        actor?.stop();
+        stopActor();
       } catch {
         // Preserve the original startup failure.
       }
@@ -2473,6 +3129,7 @@ export function createXStatePlaybookRuntime<TOptions>(
       activeEmissionCalls.clear();
       emissionQueue.clear();
       judgeQueue.clear();
+      appliedReceipts.clear();
       actor = undefined;
       session = undefined;
       savedPorts = undefined;
@@ -2482,6 +3139,7 @@ export function createXStatePlaybookRuntime<TOptions>(
       controlPlaneError = undefined;
       emissionFailure = undefined;
       priorState = undefined;
+      lastBossEvent = undefined;
       suppressInspectionEmissions = false;
       initialized = false;
       traceSequence = 0;
@@ -2490,6 +3148,183 @@ export function createXStatePlaybookRuntime<TOptions>(
       playerCallSequence = 0;
       playbookCallSequence = 0;
       captainCallSequence = 0;
+      applyCallSequence = 0;
+    }
+
+    // -----------------------------------------------------------------
+    // DR-029 control surface: action derivation shared by `describe`
+    // and by `apply`'s live revalidation.
+    // -----------------------------------------------------------------
+
+    interface DerivedControlAction {
+      action: PlaybookControlAction;
+      event: EventObject;
+    }
+
+    function snapshotCan(snapshot: unknown, event: EventObject): boolean {
+      const can = (snapshot as { can?: unknown } | null)?.can;
+      return (
+        typeof can === 'function' &&
+        (can as (candidate: EventObject) => boolean).call(snapshot, event) ===
+          true
+      );
+    }
+
+    // The failure-state retry entry replays the recorded last classified
+    // event with its recorded payload. A candidate whose event the live
+    // snapshot does not accept — or whose payload the runtime never
+    // recorded — is excluded rather than completed with invented text.
+    function retryActionFor(
+      snapshot: unknown,
+      stateId: string | undefined,
+    ): DerivedControlAction | undefined {
+      if (stateId !== 'failed' || lastBossEvent === undefined) {
+        return undefined;
+      }
+      if (!snapshotCan(snapshot, lastBossEvent)) return undefined;
+      // A recorded explicit-state-jump event names the exact state its
+      // replay re-enters: the root BOSS_INTERRUPT shape is a guarded
+      // multi-arm list keyed on `targetId`, so the first configured arm
+      // may label a different state than the one the recorded event
+      // actually resumes.
+      const recordedTargetId =
+        lastBossEvent.type === JUMP_EVENT_TYPE
+          ? (lastBossEvent as { targetId?: unknown }).targetId
+          : undefined;
+      const target =
+        typeof recordedTargetId === 'string' &&
+        recordedTargetId.trim().length > 0
+          ? recordedTargetId
+          : firstTransitionTarget(machine, stateId, lastBossEvent.type);
+      // PBRT-52: a label is written from a source state description, never
+      // from an identifier. Falling back to the target id — or, with no
+      // resolvable target, to the FSM event type — makes the label *be* the
+      // internal name, which defeats the substitution the label exists for
+      // and puts a machine identifier into Boss-facing text
+      // (CAPPLAY-5). A candidate whose label can only be an id is excluded
+      // exactly like one whose payload cannot be sourced.
+      const description =
+        (target === undefined ? undefined : stateDescriptions.get(target)) ??
+        stateDescriptions.get(stateId);
+      if (description === undefined) return undefined;
+      return {
+        action: {
+          id: `retry:${lastBossEvent.type}`,
+          label: `Retry: ${description}`,
+        },
+        event: lastBossEvent,
+      };
+    }
+
+    function deriveControlActions(snapshot: unknown): DerivedControlAction[] {
+      // Actions derive only at the safe point the parked snapshot also
+      // uses — quiescent actor with status `active` and no pending nested
+      // call. Anywhere else the view still describes the state while
+      // advertising nothing.
+      let state: PlaybookState;
+      try {
+        state = normalizePlaybookSnapshot(snapshot, {
+          pendingCall: nestedBridge.getPendingCall(),
+        });
+      } catch {
+        return [];
+      }
+      if (
+        state.status !== 'active' ||
+        !state.quiescent ||
+        nestedBridge.getPendingCall()
+      ) {
+        return [];
+      }
+      const derived: DerivedControlAction[] = [];
+      const retry = retryActionFor(snapshot, state.stateId);
+      if (retry !== undefined) derived.push(retry);
+      // Jump entries: resumable targets whose explicit-state-jump event the
+      // live snapshot accepts (state guards included), sent with the
+      // advertised target id and optional textual fields omitted.
+      for (const targetId of [...resumableStateIds].sort()) {
+        const event = { type: JUMP_EVENT_TYPE, targetId } as EventObject;
+        if (!snapshotCan(snapshot, event)) continue;
+        // PBRT-52: no published description for the target, no Boss-appropriate
+        // label. A jump cannot borrow another state's meaning without naming
+        // the wrong state, so the entry is not advertised at all rather than
+        // labeled with its own target id.
+        const description = stateDescriptions.get(targetId);
+        if (description === undefined) continue;
+        derived.push({
+          action: {
+            id: `jump:${targetId}`,
+            label: `Resume from: ${description}`,
+          },
+          event,
+        });
+      }
+      return derived;
+    }
+
+    // PBRT-52: the control view's context is the artifact's declared
+    // projection, not a serialization of whatever the FSM happens to hold.
+    // Only the runtime knows which of its context members are safe and
+    // relevant for a controller prompt — an allow-by-default export cannot
+    // keep player output, resolved player identities, or option values out
+    // of a prompt whose host is required to exclude them
+    // (CAPTAIN-9) — so nothing is exported unless
+    // `controlContextFields` names it, in the order it names them. Each
+    // named member is still sanitized: raw `Error` values are normalized
+    // and a value that cannot be made JSON-safe is dropped, never thrown,
+    // since `describe` must stay side-effect free and total.
+    function projectControlContext(
+      context: Record<string, unknown>,
+    ): JsonValue | undefined {
+      const projected: Record<string, JsonValue> = {};
+      for (const key of controlContextFields) {
+        const value = context[key];
+        if (value === undefined) continue;
+        try {
+          projected[key] = snapshotJsonValue(
+            value instanceof Error ? normalizeError(value) : value,
+            `control context ${key}`,
+          );
+        } catch {
+          // Declared but not JSON-safe — dropped.
+        }
+      }
+      return Object.keys(projected).length === 0 ? undefined : projected;
+    }
+
+    // PBRT-52: the view's Boss-facing state description — the meaning of the
+    // state the runtime is in, written by the artifact's own source, from the
+    // same descriptions its action labels are written from. A control view is
+    // the only grounding a controller host has for a status answer, and an
+    // internal state id is not Boss-appropriate text
+    // (CAPPLAY-5), so the runtime publishes the meaning
+    // rather than leaving the host to substitute the identifier for it. A
+    // state whose source declares no description publishes none: an id is
+    // never promoted into a description by default.
+    function stateDescriptionFor(state: PlaybookState): string | undefined {
+      const keys = [
+        ...(state.stateId === undefined ? [] : [state.stateId]),
+        ...(typeof state.value === 'string' ? [state.value] : []),
+        ...state.activeStateIds,
+      ];
+      for (const key of keys) {
+        const description = stateDescriptions.get(key);
+        if (description !== undefined) return description;
+      }
+      return undefined;
+    }
+
+    function receiptTracePayload(
+      receipt: PlaybookControlReceipt,
+    ): Record<string, unknown> {
+      return {
+        disposition: receipt.disposition,
+        ...(receipt.disposition === 'rejected'
+          ? { reason: receipt.reason }
+          : {}),
+        ...(receipt.disposition === 'failed' ? { error: receipt.error } : {}),
+        ...(receipt.disposition === 'executed' ? { run: receipt.run } : {}),
+      };
     }
 
     const runtime = {
@@ -2547,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,
@@ -2590,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) => {
@@ -2611,12 +3450,16 @@ export function createXStatePlaybookRuntime<TOptions>(
             // Every Captain call already consumed at least one trace number,
             // so the global trace counter is a collision-safe id floor.
             boundSnapshot.sequences.trace;
-          playerResumeTokens.clear();
-          for (const [playerId, token] of Object.entries(
-            boundSnapshot.playerResumeTokens,
-          )) {
-            playerResumeTokens.set(playerId, token);
+          // 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.
+          applyCallSequence = boundSnapshot.sequences.trace;
+          if (boundSession.playerSessions) {
+            priorExternalPlayerTokens = snapshotPlayerResumeTokens();
+            externalStoreRestoreAttempted = true;
           }
+          restorePlayerResumeTokens(boundSnapshot.playerResumeTokens);
           suppressInspectionEmissions = true;
           actor = buildActor(runtimePorts, boundSnapshot.machine);
           actor.start();
@@ -2633,14 +3476,371 @@ 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;
         }
       },
 
+      // DR-029 / PBRT-52: side-effect-free control view over the live
+      // snapshot, valid at parked quiescence outside an active boundary.
+      // The view is detached and frozen; producing it emits nothing and
+      // moves nothing.
+      describe(): PlaybookControlView {
+        if (disposed || disposalPromise !== undefined) {
+          throw new Error(
+            'createPlaybookRuntime.describe: runtime is disposing or disposed',
+          );
+        }
+        if (!actor || !savedPorts) {
+          throw new Error(
+            'createPlaybookRuntime.describe: init must be called first',
+          );
+        }
+        if (activeSignal !== undefined) {
+          throw new Error(
+            'createPlaybookRuntime.describe: another runtime turn is active',
+          );
+        }
+        const snapshot = actor.getSnapshot();
+        const state = currentState();
+        const context = ((snapshot as { context?: unknown }).context ??
+          {}) as Record<string, unknown>;
+        const pending = pendingBossQuestionFromContext(context);
+        const lastError = normalizeErrorFull(context.lastError);
+        const projectedContext = projectControlContext(context);
+        const stateDescription = stateDescriptionFor(state);
+        return deepFreeze({
+          state,
+          ...(stateDescription === undefined ? {} : { stateDescription }),
+          ...(projectedContext !== undefined
+            ? { context: projectedContext }
+            : {}),
+          pendingQuestions:
+            pending === undefined
+              ? []
+              : [
+                  {
+                    questionId: pending.questionId,
+                    player: pending.player,
+                    question: pending.question,
+                    sourceItem: pending.sourceItem,
+                  },
+                ],
+          ...(lastError !== undefined ? { lastError } : {}),
+          actions: deriveControlActions(snapshot).map(({ action }) => action),
+        });
+      },
+
+      // DR-029 / PBRT-52: revalidate the named action against the live
+      // state and execute it at most once per idempotency key. The receipt
+      // discriminates rejected-before-any-effect from executed and from
+      // failed-after-effects-may-exist; a repeated key returns the recorded
+      // receipt without re-execution. A rejection settles before acceptance,
+      // so — like a key whose call threw before reaching acceptance — it
+      // records nothing and the key may execute later, once the action is
+      // advertised.
+      async apply(input: {
+        actionId: string;
+        key: string;
+        signal: AbortSignal;
+      }): Promise<PlaybookControlReceipt> {
+        if (input === null || typeof input !== 'object') {
+          throw new TypeError(
+            'createPlaybookRuntime.apply: input must be an object',
+          );
+        }
+        const { actionId, key, signal } = input;
+        if (typeof actionId !== 'string' || actionId.length === 0) {
+          throw new TypeError(
+            'createPlaybookRuntime.apply: actionId must be a non-empty string',
+          );
+        }
+        if (typeof key !== 'string' || key.length === 0) {
+          throw new TypeError(
+            'createPlaybookRuntime.apply: key must be a non-empty string',
+          );
+        }
+        if (!(signal instanceof AbortSignal)) {
+          throw new TypeError(
+            'createPlaybookRuntime.apply: signal must be an AbortSignal',
+          );
+        }
+        if (disposed || disposalPromise !== undefined) {
+          throw new Error(
+            'createPlaybookRuntime.apply: runtime is disposing or disposed',
+          );
+        }
+        if (!actor || !savedPorts) {
+          throw new Error(
+            'createPlaybookRuntime.apply: init must be called first',
+          );
+        }
+        if (activeSignal !== undefined) {
+          throw new Error(
+            'createPlaybookRuntime.apply: another runtime turn is active',
+          );
+        }
+        // Settlement is final: a repeated key returns the recorded receipt
+        // with no revalidation, no execution, and no new trace pair.
+        const recorded = appliedReceipts.get(key);
+        if (recorded !== undefined) return recorded;
+        // An abort before acceptance ends the call with no receipt
+        // recorded, like every other pre-acceptance failure.
+        signal.throwIfAborted();
+
+        const turnId = ++turnSequence;
+        const callId = `apply-${++applyCallSequence}`;
+        const position: TracePosition = { turnId, callId };
+        activeTurnId = turnId;
+        activeSignal = signal;
+        controlPlaneError = undefined;
+        // Every receipt variant is normalized and frozen where it is built,
+        // inside the guarded region, so the recording step below cannot
+        // throw after effects exist.
+        const settledReceipt = (
+          value: PlaybookControlReceipt,
+        ): PlaybookControlReceipt =>
+          deepFreeze(
+            snapshotJsonValue(
+              value,
+              'apply receipt',
+            ) as unknown as PlaybookControlReceipt,
+          );
+        let receipt: PlaybookControlReceipt | undefined;
+        let operationError: unknown;
+        let settlementError: unknown;
+        // Acceptance is the line past which this boundary owes a receipt and
+        // can no longer signal by throwing: the action may have run, and a
+        // caller that gets an exception instead of a receipt is left with an
+        // executed effect it cannot record and a key it will not reuse.
+        let accepted = false;
+        // Publication is the second line this boundary respects. Before it,
+        // nothing has left the runtime: a settlement failure past acceptance
+        // is a post-acceptance control-plane error PBRT-52 settles as the
+        // `failed` receipt, and folding it in replaces the receipt recorded
+        // at acceptance so the finish trace, the returned receipt, and any
+        // replay of the key all report one settlement. Past publication that
+        // agreement is no longer achievable — the disposition is already on
+        // the wire — so the fold refuses to run, by construction rather than
+        // by call ordering. Only the first settlement error is latched, so
+        // one fold is all there is to do.
+        let folded = false;
+        let published = false;
+        const foldSettlementFailure = (): void => {
+          if (published || !accepted || folded) return;
+          if (settlementError === undefined) return;
+          folded = true;
+          receipt = settledReceipt({
+            disposition: 'failed',
+            error: normalizeError(settlementError),
+          });
+          appliedReceipts.set(key, receipt);
+        };
+        // A settlement failure that lands after the receipt is published says
+        // nothing about the effect: the action ran, the caller's receipt is
+        // true, and only the telemetry delivery failed. Rewriting `executed`
+        // to `failed` there would make the runtime lie to its only caller
+        // about work that succeeded, irrecoverably — accepted receipts are
+        // final for their key. Past publication such a failure is therefore
+        // re-latched onto the emission channel, surfacing from the next
+        // public boundary's drain, and `apply` still does not throw past
+        // acceptance (PBRT-52).
+        const latchDeliveryFailure = (error: unknown): void => {
+          emissionFailure ??= error;
+        };
+        try {
+          try {
+            const identity = {
+              actionId,
+              key,
+              ...stateIdentity(currentState().stateId),
+            };
+            // Every apply finish carries the receipt disposition and no
+            // start-only field — `stateId` is on the start alone
+            // (slc/link.md §Playbook trace). Both finishes reachable
+            // before acceptance settle with no effect behind them, so both
+            // carry the canonical `rejected` disposition and the reason
+            // that ended the call, alongside the transport marker.
+            const preAcceptanceFinish = (
+              reason: string,
+            ): Record<string, unknown> => ({
+              actionId,
+              key,
+              ...receiptTracePayload({ disposition: 'rejected', reason }),
+            });
+            await emitCallStarted(
+              'apply.started',
+              'apply.finished',
+              identity,
+              position,
+              preAcceptanceFinish('apply.started trace sink rejected'),
+            );
+            // An abort may land while the awaited started emission drains
+            // (e.g. fired from the trace sink itself); the action must
+            // never execute after abort. Settle the already-started pair
+            // as `aborted` — carrying the canonical rejected-before-any-
+            // effect receipt disposition required of every apply finish —
+            // and end the call pre-acceptance: no receipt is recorded and
+            // the key stays free.
+            if (signal.aborted) {
+              try {
+                await emitTrace(
+                  'apply.finished',
+                  {
+                    ...preAcceptanceFinish('aborted before acceptance'),
+                    status: 'aborted',
+                    error: normalizeError(signal.reason),
+                  },
+                  position,
+                );
+              } catch (error) {
+                // A rejecting finish sink surfaces at the boundary like
+                // any settlement failure (see the precedence below).
+                settlementError ??= error;
+              }
+              signal.throwIfAborted();
+            }
+            const snapshot = actor.getSnapshot();
+            const candidate = deriveControlActions(snapshot).find(
+              ({ action }) => action.id === actionId,
+            );
+            if (candidate === undefined) {
+              receipt = settledReceipt({
+                disposition: 'rejected',
+                reason: `action ${JSON.stringify(
+                  actionId,
+                )} is not currently advertised`,
+              });
+            } else {
+              // Acceptance: from here every outcome records a receipt under
+              // the key, so the action can never execute twice.
+              accepted = true;
+              try {
+                actor.send(candidate.event);
+                await waitForPlaybookQuiescence(actor, {
+                  pendingCalls: nestedBridge,
+                });
+                if (controlPlaneError !== undefined) throw controlPlaneError;
+                const run = runResultFor(settledOutcome(signal));
+                receipt = settledReceipt(
+                  run.outcome === 'failed' || run.outcome === 'aborted'
+                    ? {
+                        disposition: 'failed',
+                        error:
+                          ('error' in run ? run.error : undefined) ??
+                          normalizeError(
+                            new Error(
+                              `apply settled with outcome ${run.outcome}`,
+                            ),
+                          ),
+                      }
+                    : { disposition: 'executed', run },
+                );
+              } catch (error) {
+                // Effects may exist: a post-acceptance failure is the
+                // receipt, not a control-plane rejection (DR-029).
+                receipt = settledReceipt({
+                  disposition: 'failed',
+                  error: normalizeError(error),
+                });
+              }
+            }
+          } catch (error) {
+            operationError = error; // pre-acceptance: no receipt is recorded
+          }
+
+          // Record acceptance before the settlement emissions, so a crash
+          // between acceptance and settlement can never re-execute the
+          // action: the recorded receipt survives and a replayed key
+          // returns it. A rejection settled before acceptance: it is
+          // returned and traced but never recorded, so its key stays free
+          // to execute once the action is advertised.
+          if (receipt !== undefined && receipt.disposition !== 'rejected') {
+            appliedReceipts.set(key, receipt);
+          }
+          try {
+            await drainEmissions();
+          } catch (error) {
+            settlementError = error;
+          }
+          // Fold before the finish emission, the last point at which the
+          // traced disposition and the returned one can still be made the
+          // same value.
+          foldSettlementFailure();
+          if (receipt !== undefined) {
+            // Publication: this disposition is now the settlement, for the
+            // trace, for the caller, and for every replay of the key.
+            published = true;
+            try {
+              await emitTrace(
+                'apply.finished',
+                { actionId, key, ...receiptTracePayload(receipt) },
+                position,
+              );
+            } catch (error) {
+              if (accepted) latchDeliveryFailure(error);
+              else settlementError ??= error;
+            }
+            // Drain even when the finish emission rejected, so this call
+            // leaves no queued emission behind it. Before acceptance the
+            // failure is consumed and thrown, as every pre-acceptance failure
+            // is; past it the failure is re-latched instead — the effect
+            // happened, so the delivery failure travels on the emission
+            // channel to the next boundary rather than rewriting what
+            // happened or vanishing here.
+            try {
+              await drainEmissions();
+            } catch (error) {
+              if (accepted) latchDeliveryFailure(error);
+              else settlementError ??= error;
+            }
+          }
+        } finally {
+          // Always release the boundary sentinel, even on a path no
+          // constructible input reaches today, so a defect here can never
+          // wedge every later public boundary behind "another runtime turn
+          // is active".
+          activeSignal = undefined;
+          activeTurnId = undefined;
+          controlPlaneError = undefined;
+        }
+        // Past acceptance every settlement failure has been folded into the
+        // receipt, so nothing is left to throw and the caller always leaves
+        // with the settlement of the effect it may have caused (PBRT-52).
+        if (accepted && receipt !== undefined) return receipt;
+        // Before acceptance no effect exists and no receipt is owed, so a
+        // failure still surfaces by throwing. Settlement failures (a
+        // rejecting finish sink, a drain-latched emission failure) outrank
+        // the operation error, matching the `drainError ?? operationError`
+        // precedence of the other public boundaries. A start-sink failure is
+        // unaffected: its latched drain error is the start error itself.
+        const failure = settlementError ?? operationError;
+        if (failure !== undefined) throw failure;
+        if (receipt === undefined) {
+          throw new Error(
+            'createPlaybookRuntime.apply: no receipt was produced',
+          );
+        }
+        return receipt;
+      },
+
       async handleBossInput({
         text,
         signal,
@@ -2695,6 +3895,7 @@ export function createXStatePlaybookRuntime<TOptions>(
                 signal,
                 snapshot,
                 boundary,
+                boundOptions,
               );
             }
             signal.throwIfAborted();
@@ -2706,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);
             }
@@ -2714,10 +3915,24 @@ export function createXStatePlaybookRuntime<TOptions>(
             // 3. A final actor cannot accept new events; reconstruct only
             //    after classification produced a real event.
             if (actor.getSnapshot().status === 'done') {
-              actor.stop();
+              stopActor();
               actor = buildActor(runtimePorts!);
+              // The replacement actor's snapshots are real state entries.
+              suppressInspectionEmissions = false;
               actor.start();
             }
+            // DR-029: keep the classified event with its recorded payload
+            // as the retry-replay source. Recording is sanitizing, not
+            // load-bearing: an override classifier's non-JSON-safe event is
+            // simply not recorded, and the turn proceeds unchanged.
+            try {
+              lastBossEvent = snapshotJsonValue(
+                event,
+                'recorded Boss event',
+              ) as unknown as EventObject;
+            } catch {
+              lastBossEvent = undefined;
+            }
             actor.send(event);
             await waitForPlaybookQuiescence(actor, {
               pendingCalls: nestedBridge,
@@ -2861,7 +4076,9 @@ export function createXStatePlaybookRuntime<TOptions>(
             const finalState = actor ? currentState() : undefined;
             // Stop the root before settling a suspended child. Its rejection
             // must not re-enter the FSM and start fresh work during disposal.
-            if (actor) actor.stop();
+            // `stopActor` suppresses inspection first, so the stop snapshot
+            // adds nothing beside the `session.disposed` trace below (PBRT-6).
+            stopActor();
             try {
               await nestedBridge.dispose();
             } catch (error) {
@@ -2889,17 +4106,24 @@ 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();
             emissionQueue.clear();
             judgeQueue.clear();
+            appliedReceipts.clear();
             actor = undefined;
             activeSignal = undefined;
             activeTurnId = undefined;
             controlPlaneError = undefined;
             emissionFailure = undefined;
+            lastBossEvent = undefined;
             savedPorts = undefined;
             runtimePorts = undefined;
             session = undefined;