@sublang/playbook 4.0.0 → 5.0.0

package/src/xstate-playbook-runtime.js

@@ -42,6 +42,30 @@ function isFsmResultFailure(error) {
         fsmResultFailures.has(error));
 }
 // ---------------------------------------------------------------------------
+// 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) {
+    return finalText === undefined || finalText.trim().length === 0;
+}
+const emptyOkRetryFailures = new WeakSet();
+function markEmptyOkRetryFailure(error) {
+    emptyOkRetryFailures.add(error);
+    return error;
+}
+function isEmptyOkRetryFailure(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        emptyOkRetryFailures.has(error));
+}
+// ---------------------------------------------------------------------------
 // DR-022: the engine's compatibility self-report. A linked thin module
 // records the values current at link time in `spec.compat`; the factory
 // checks that declaration against this very module — the engine instance
@@ -425,19 +449,39 @@ export function createPlayerBridge(spec, ports, getActiveSignal, boundary, onCon
         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) => 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');
         }
         try {
-            const output = await adjudicatePlayerOutput(spec.adjudication, input, result.finalText, ports, activeSignal, boundary);
+            const output = await adjudicatePlayerOutput(spec.adjudication, input, finalText, ports, activeSignal, boundary);
             validateBossReplyOutput(input, output, spec.resumableStateIds);
             return output;
         }
@@ -574,6 +618,95 @@ export function resumableStateIdsFromMachine(machine) {
     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) {
+    const descriptions = new Map();
+    const record = (key, description) => {
+        if (typeof key !== 'string' || key.length === 0)
+            return;
+        if (!descriptions.has(key))
+            descriptions.set(key, description);
+    };
+    const visit = (key, stateDef) => {
+        if (!isPlainObject(stateDef))
+            return;
+        const playbook = isPlainObject(stateDef.meta)
+            ? stateDef.meta.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.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, stateId, eventType) {
+    const config = machine.config;
+    if (!isPlainObject(config))
+        return undefined;
+    const candidates = [];
+    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(value) {
+    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.
 // ---------------------------------------------------------------------------
 const SUPPRESSED_ENTRY_STATES = new Set(['ready', 'done']);
@@ -892,6 +1025,18 @@ function makeDefaultClassifyBossText(machine, entryEvent, bossEvents) {
         return event;
     };
 }
+function machineDeclaresParallelState(machine) {
+    const visit = (stateDef) => {
+        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.config);
+}
 /**
  * Build a `PlaybookRuntimeFactory` that interprets the given FSM artifact
  * under the slc/link.md contract. The factory provides every actor kind the
@@ -899,16 +1044,37 @@ function makeDefaultClassifyBossText(machine, entryEvent, bossEvents) {
  * (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(machine, spec) {
     const label = spec.label ?? 'playbook';
     // 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);
+    // 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 = 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 ??
         ((input) => defaultComposePlayerPrompt(input, spec.placeholderFields));
@@ -968,6 +1134,19 @@ export function createXStatePlaybookRuntime(machine, spec) {
         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;
+        // 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();
         const playerResumeTokens = new Map();
         const activePlayerIds = new Set();
         const playbookCallTurnIds = new Map();
@@ -1105,14 +1284,25 @@ export function createXStatePlaybookRuntime(machine, spec) {
                 },
             };
         }
-        async function emitCallStarted(startedType, finishedType, identity, position) {
+        async function emitCallStarted(startedType, finishedType, identity, position, 
+        // 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 = identity) {
             try {
                 await emitTrace(startedType, identity, position);
             }
             catch (error) {
                 controlPlaneError ??= error;
                 try {
-                    await emitTrace(finishedType, { ...identity, status: 'error', error: normalizeError(error) }, position);
+                    await emitTrace(finishedType, {
+                        ...finishIdentity,
+                        status: 'error',
+                        error: normalizeError(error),
+                    }, position);
                 }
                 catch {
                     // Preserve the start failure after one best-effort finish attempt.
@@ -1150,6 +1340,11 @@ export function createXStatePlaybookRuntime(machine, spec) {
                     await emitTrace('player.call.started', { ...identity, prompt }, position);
                     let rawResult;
                     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, signal, { resume });
                         // A host promise is not required to honor cancellation. Do not let
                         // a late result mutate continuity or publish a successful finish.
@@ -1230,6 +1425,11 @@ export function createXStatePlaybookRuntime(machine, spec) {
                     await emitCallStarted('judge.call.started', 'judge.call.finished', { ...identity, prompt }, position);
                     let reply;
                     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();
                     }
@@ -1261,18 +1461,23 @@ export function createXStatePlaybookRuntime(machine, spec) {
                     return reply;
                 });
             },
-            async callCaptain(input, prompt, signal) {
+            async callCaptain(input, prompt, signal, callOptions) {
                 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',
-                        resume: false,
+                        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 } : {}),
                         ...(input.allowedTools === undefined
                             ? {}
                             : { allowedTools: [...input.allowedTools] }),
@@ -1284,8 +1489,13 @@ export function createXStatePlaybookRuntime(machine, spec) {
                     await emitCallStarted('captain.call.started', 'captain.call.finished', { ...identity, prompt }, position);
                     let rawResult;
                     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 }
@@ -1317,12 +1527,14 @@ export function createXStatePlaybookRuntime(machine, spec) {
                     // authoritative for the actor's error path even when the required
                     // finish emission fails or a coincident boundary abort lands.
                     let resultFailure;
+                    let emptyOkRetry = false;
                     if (result.status !== 'ok') {
                         resultFailure = markFsmResultFailure(new Error(result.error ??
                             `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('captain.call.finished', {
@@ -1341,13 +1553,18 @@ export function createXStatePlaybookRuntime(machine, spec) {
                     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;
                 });
@@ -1379,17 +1596,52 @@ export function createXStatePlaybookRuntime(machine, spec) {
                 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: (error) => {
+                                markFsmResultFailure(error);
+                                return error;
+                            },
+                        });
+                        validateBossReplyOutput(input, output, resumableStateIds);
+                        return output;
+                    }
+                    let result;
+                    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);
+                    const judgePrompt = defaultBuildCaptainJudgePrompt(input, finalText);
                     const raw = await boundary.callJudge('captain-output-adjudication', input.stateId, judgePrompt, active);
-                    const output = adjudicateCaptainOutput(extractFields, input, result.finalText, raw);
+                    const output = adjudicateCaptainOutput(extractFields, input, finalText, raw);
                     validateBossReplyOutput(input, output, resumableStateIds);
                     return output;
                 }
@@ -1569,6 +1821,20 @@ export function createXStatePlaybookRuntime(machine, spec) {
             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() {
+            if (!actor)
+                return;
+            suppressInspectionEmissions = true;
+            actor.stop();
+        }
         function buildActor(ports, machineSnapshot) {
             priorState = undefined;
             const actors = {};
@@ -1695,9 +1961,8 @@ export function createXStatePlaybookRuntime(machine, spec) {
                     // A state that cannot even normalize has no disposal descriptor.
                 }
             }
-            suppressInspectionEmissions = true;
             try {
-                actor?.stop();
+                stopActor();
             }
             catch {
                 // Preserve the original startup failure.
@@ -1735,6 +2000,7 @@ export function createXStatePlaybookRuntime(machine, spec) {
             activeEmissionCalls.clear();
             emissionQueue.clear();
             judgeQueue.clear();
+            appliedReceipts.clear();
             actor = undefined;
             session = undefined;
             savedPorts = undefined;
@@ -1744,6 +2010,7 @@ export function createXStatePlaybookRuntime(machine, spec) {
             controlPlaneError = undefined;
             emissionFailure = undefined;
             priorState = undefined;
+            lastBossEvent = undefined;
             suppressInspectionEmissions = false;
             initialized = false;
             traceSequence = 0;
@@ -1752,6 +2019,159 @@ export function createXStatePlaybookRuntime(machine, spec) {
             playerCallSequence = 0;
             playbookCallSequence = 0;
             captainCallSequence = 0;
+            applyCallSequence = 0;
+        }
+        function snapshotCan(snapshot, event) {
+            const can = snapshot?.can;
+            return (typeof can === 'function' &&
+                can.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, stateId) {
+            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.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) {
+            // 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;
+            try {
+                state = normalizePlaybookSnapshot(snapshot, {
+                    pendingCall: nestedBridge.getPendingCall(),
+                });
+            }
+            catch {
+                return [];
+            }
+            if (state.status !== 'active' ||
+                !state.quiescent ||
+                nestedBridge.getPendingCall()) {
+                return [];
+            }
+            const derived = [];
+            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 };
+                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) {
+            const projected = {};
+            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) {
+            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) {
+            return {
+                disposition: receipt.disposition,
+                ...(receipt.disposition === 'rejected'
+                    ? { reason: receipt.reason }
+                    : {}),
+                ...(receipt.disposition === 'failed' ? { error: receipt.error } : {}),
+                ...(receipt.disposition === 'executed' ? { run: receipt.run } : {}),
+            };
         }
         const runtime = {
             async init(nextSession) {
@@ -1867,6 +2287,11 @@ export function createXStatePlaybookRuntime(machine, spec) {
                             // Every Captain call already consumed at least one trace number,
                             // so the global trace counter is a collision-safe id floor.
                             boundSnapshot.sequences.trace;
+                    // The schema-1 snapshot carries no apply counter (PBRT-50: no
+                    // schema bump); every apply boundary consumed trace numbers, so
+                    // the persisted trace counter is a collision-safe id floor here
+                    // too, keeping `apply-<n>` call ids unique across restore.
+                    applyCallSequence = boundSnapshot.sequences.trace;
                     playerResumeTokens.clear();
                     for (const [playerId, token] of Object.entries(boundSnapshot.playerResumeTokens)) {
                         playerResumeTokens.set(playerId, token);
@@ -1895,6 +2320,301 @@ export function createXStatePlaybookRuntime(machine, spec) {
                         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() {
+                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.context ??
+                    {});
+                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) {
+                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 = { 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) => deepFreeze(snapshotJsonValue(value, 'apply receipt'));
+                let receipt;
+                let operationError;
+                let settlementError;
+                // 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 = () => {
+                    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) => {
+                    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) => ({
+                            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, }) {
                 if (!actor || !savedPorts) {
                     throw new Error('createPlaybookRuntime.handleBossInput: init must be called first');
@@ -1930,7 +2650,7 @@ export function createXStatePlaybookRuntime(machine, spec) {
                             };
                         }
                         else {
-                            event = await classifyBossText(text, runtimePorts, signal, snapshot, boundary);
+                            event = await classifyBossText(text, runtimePorts, signal, snapshot, boundary, boundOptions);
                         }
                         signal.throwIfAborted();
                     }
@@ -1950,10 +2670,22 @@ export function createXStatePlaybookRuntime(machine, spec) {
                         // 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');
+                        }
+                        catch {
+                            lastBossEvent = undefined;
+                        }
                         actor.send(event);
                         await waitForPlaybookQuiescence(actor, {
                             pendingCalls: nestedBridge,
@@ -2080,8 +2812,9 @@ export function createXStatePlaybookRuntime(machine, spec) {
                         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();
                         }
@@ -2116,11 +2849,13 @@ export function createXStatePlaybookRuntime(machine, spec) {
                         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;