@sublang/playbook 0.9.0 → 1.3.0

package/reference/sdlc/code.playbook/code.playbook.js

@@ -11,16 +11,44 @@
 //                alias's first alternative)
 // Boss event:    free-text judge classification
 // Adjudication:  LLM-judge per state
-// Contract:      PlayerResult / PlaybookPorts / PlaybookRuntime imported
-//                and re-exported from @sublang/playbook/runtime
+// Contract:      PlayerResult / PlaybookPorts / PlaybookSession /
+//                PlaybookRuntime imported and re-exported from
+//                @sublang/playbook/runtime
 //                (slc/link.md §Output, DR-004 Addendum A4)
-import { createActor, fromPromise } from 'xstate';
+// Runtime:       the shared createXStatePlaybookRuntime factory from
+//                @sublang/playbook/xstate-runtime interprets the FSM
+//                (slc/link.md §Output, DR-019); this module carries only
+//                the CODE-specific spec — options validation, player
+//                binding, prompt composition, Boss-event classification,
+//                and Captain-pane status formatting.
+import { createPlayerBridge, createXStatePlaybookRuntime, adjudicatePlayerOutput, normalizeError, normalizeErrorCompact, normalizeErrorFull, parseJudgeJson, snapshotJsonValue, } from '../../../src/xstate-runtime.js';
 import { codingMachine, } from './code.fsm.js';
 import { enumerateAwaitBossReply, enumerateCaptainStates, enumerateRootEvents, } from './code.fsm.introspect.js';
-const BOSS_REPLY_ERRORS = {
-    missingQuestion: "needsBossReply outcome missing 'question' field",
-    unregisteredState: (stateId) => `state ${stateId} declared needsBossReply but is not registered as resumable`,
-};
+function snapshotCodePlaybookOptions(value) {
+    const captured = snapshotJsonValue(value, 'CODE runtime options');
+    if (captured === null ||
+        typeof captured !== 'object' ||
+        Array.isArray(captured)) {
+        throw new TypeError('CODE runtime options must be an object');
+    }
+    const record = captured;
+    const allowed = new Set([
+        'intent',
+        'irNumber',
+        'coderPlayer',
+        'reviewerPlayer',
+        'committerPlayer',
+    ]);
+    for (const [key, option] of Object.entries(record)) {
+        if (!allowed.has(key)) {
+            throw new TypeError(`CODE runtime options.${key} is not declared`);
+        }
+        if (typeof option !== 'string') {
+            throw new TypeError(`CODE runtime options.${key} must be a string`);
+        }
+    }
+    return captured;
+}
 // Required-payload fields whose value is the player's verbatim long-form
 // prose. The runtime carries `finalText.trim()` into these fields rather
 // than asking the judge to round-trip the text through JSON. Short
@@ -30,59 +58,47 @@ const VERBATIM_PAYLOAD_FIELDS = new Set([
     'reviews',
     'challenges',
 ]);
-// Normalize an unknown error value to the compact `{ name, message }`
-// shape used by Captain-pane / status emissions. Returns `undefined`
-// for nullish input so callers can omit absent errors.
-function normalizeErrorCompact(err) {
-    if (err === undefined || err === null)
+// Normalize any `error` field inside a telemetry event so failed
+// transitions don't leak raw Error instances through the channel.
+function normalizeEventForTelemetry(event) {
+    if (event === undefined)
         return undefined;
-    if (err instanceof Error) {
-        return { name: err.name, message: err.message };
-    }
-    if (typeof err === 'object') {
-        const o = err;
-        if (typeof o.message === 'string') {
-            return {
-                name: typeof o.name === 'string' ? o.name : 'Error',
-                message: o.message,
-            };
-        }
-    }
-    return { name: 'Error', message: String(err) };
+    return normalizeEventValue(event, 'FSM event', new Set());
 }
-// Normalize an unknown error value to the full `{ name, message, stack }`
-// shape used by telemetry emissions. Returns `undefined` for nullish
-// input. `stack` is omitted when not available on the source value.
-function normalizeErrorFull(err) {
-    const compact = normalizeErrorCompact(err);
-    if (compact === undefined)
-        return undefined;
-    if (err instanceof Error) {
-        return err.stack !== undefined ? { ...compact, stack: err.stack } : compact;
-    }
-    if (typeof err === 'object' && err !== null) {
-        const stack = err.stack;
-        if (typeof stack === 'string') {
-            return { ...compact, stack };
+function normalizeEventValue(value, path, ancestors) {
+    if (Array.isArray(value))
+        return snapshotJsonValue(value, path);
+    if (value === null || typeof value !== 'object') {
+        return snapshotJsonValue(value, path);
+    }
+    if (ancestors.has(value)) {
+        throw new TypeError(`${path} must not contain a JSON cycle`);
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        return snapshotJsonValue(value, path);
+    }
+    if (Object.getOwnPropertySymbols(value).length > 0) {
+        return snapshotJsonValue(value, path);
+    }
+    const nextAncestors = new Set(ancestors).add(value);
+    const normalized = {};
+    for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(value))) {
+        if (!descriptor.enumerable) {
+            throw new TypeError(`${path}.${key} must be an enumerable JSON property`);
+        }
+        if (!Object.prototype.hasOwnProperty.call(descriptor, 'value')) {
+            throw new TypeError(`${path}.${key} must be a JSON data property`);
         }
+        if (descriptor.value === undefined)
+            continue;
+        normalized[key] =
+            key === 'error'
+                ? snapshotJsonValue(normalizeError(descriptor.value), `${path}.error`)
+                : normalizeEventValue(descriptor.value, `${path}.${key}`, nextAncestors);
     }
-    return compact;
+    return snapshotJsonValue(normalized, path);
 }
-// Normalize any `error` field inside a telemetry event so failed
-// transitions don't leak raw Error instances through the channel.
-function normalizeEventForTelemetry(event) {
-    if (event === null || typeof event !== 'object' || Array.isArray(event)) {
-        return event;
-    }
-    const e = event;
-    if (!('error' in e))
-        return event;
-    const normalized = normalizeErrorFull(e.error);
-    return { ...e, error: normalized };
-}
-// Internal capabilities (DR-004 §10). Each ships with its final
-// signature; behavior lands in the per-capability task noted by the
-// TODO marker.
 // Player-prompt composer — DR-004 §6.
 // Substitutes the three placeholder tokens in `input.prompt` (literal
 // string replace, no escaping) and arranges labelled blocks around
@@ -163,52 +179,6 @@ function resolvePlayerId(input) {
         }
     }
 }
-// LLM judge — DR-004 §4. Builds a prompt that lists each declared
-// outcome verbatim, asks ports.callJudge for a JSON
-// `{ guard, …payloadFields }` response, and returns the parsed
-// object once the chosen guard is one of the input.result keys.
-// Adjudicator failures (malformed JSON, missing/unknown guard) are
-// control-plane errors and propagate via throw per slc/link.md.
-async function adjudicate(input, finalText, ports, signal) {
-    const prompt = buildJudgePrompt(input, finalText);
-    const raw = await ports.callJudge(prompt, signal);
-    const parsed = parseJudgeJson(raw);
-    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-        throw new Error('adjudicate: judge response is not a JSON object');
-    }
-    const obj = parsed;
-    const guard = obj.guard;
-    if (typeof guard !== 'string') {
-        throw new Error('adjudicate: judge response missing string "guard" field');
-    }
-    if (!Object.prototype.hasOwnProperty.call(input.result, guard)) {
-        throw new Error(`adjudicate: unknown guard "${guard}" — declared guards: ${Object.keys(input.result).join(', ')}`);
-    }
-    // Per slc/link.md, a missing payload field the state's `result`
-    // description requires is a control-plane error. The FSM names
-    // required fields with the literal phrase
-    //   Output shall include `<fieldName>: <...>`
-    // so we extract those tokens and require each to be a string in
-    // the judge response — except for VERBATIM_PAYLOAD_FIELDS
-    // (`reviews`, `challenges`), where the runtime substitutes
-    // `finalText.trim()` so the long-form prose is not round-tripped
-    // through judge JSON. Short extracted fields like `question` and
-    // `taskDescription` keep the existing extract-and-validate path.
-    const verbatim = finalText.trim();
-    for (const field of extractRequiredFields(input.result[guard])) {
-        if (VERBATIM_PAYLOAD_FIELDS.has(field)) {
-            obj[field] = verbatim;
-            continue;
-        }
-        if (typeof obj[field] !== 'string') {
-            if (guard === 'needsBossReply' && field === 'question') {
-                throw new Error(BOSS_REPLY_ERRORS.missingQuestion);
-            }
-            throw new Error(`adjudicate: judge response missing required field "${field}" for guard "${guard}"`);
-        }
-    }
-    return obj;
-}
 function extractRequiredFields(description) {
     const fields = [];
     const re = /Output shall include `([A-Za-z_][A-Za-z0-9_]*):/g;
@@ -237,145 +207,23 @@ function buildJudgePrompt(input, finalText) {
     }
     return lines.join('\n');
 }
-// Judge replies are meant to be a single JSON object, but LLMs
-// routinely wrap them in prose ("Here is the result: …"), Markdown
-// code fences, or trailing commentary, and occasionally emit a
-// trailing comma or truncate the tail (a dropped closing brace, an
-// unterminated string). parseJudgeJson is deliberately lenient: it
-// first tries a strict parse of the (optionally fenced) body, then
-// scans every `{`/`[` as a possible start in document order and
-// returns the first recoverable object. At each start it prefers a
-// strict balanced span and falls back to a repaired (trailing-comma /
-// truncation) span, so a damaged object earlier in the prose is not
-// overridden by a cleaner one later. Scanning every start (not just
-// the first bracket) keeps a bracketed fragment in surrounding prose —
-// e.g. an aside like `see [1]` or `{n/a}` before the real object —
-// from masking a later, genuinely valid object. Both callers
-// (classification and adjudication) expect an object, so plain objects
-// win over arrays/scalars; the first value of any shape is remembered
-// so a legitimately array/scalar reply still surfaces to the caller's
-// own object check. Only a reply from which no JSON value can be
-// recovered is treated as malformed and throws, preserving the
-// control-plane error contract (PBRT-7, PBRT-10).
-function parseJudgeJson(raw) {
-    const fenced = stripCodeFence(raw.trim());
-    // Fast path: a well-formed (optionally fenced) JSON body.
-    try {
-        return JSON.parse(fenced);
-    }
-    catch {
-        // Fall through to lenient extraction + repair.
-    }
-    const starts = [];
-    for (let i = 0; i < fenced.length; i++) {
-        const ch = fenced[i];
-        if (ch === '{' || ch === '[')
-            starts.push(i);
-    }
-    // Walk starts in document order. At each start prefer a strict
-    // balanced span (most trustworthy) and fall back to a repaired one
-    // for a trailing-comma / truncated tail, so the earliest intended
-    // object wins even when it needs repair. Return the first plain
-    // object; remember the first value of any shape so a legitimately
-    // array/scalar reply still surfaces to the caller's own object check.
-    let firstValue;
-    for (const start of starts) {
-        let parsedHere;
-        for (const repair of [false, true]) {
-            const candidate = extractJsonValue(fenced, start, repair);
-            if (candidate === undefined)
-                continue;
-            try {
-                parsedHere = { value: JSON.parse(candidate) };
-            }
-            catch {
-                continue; // not parseable this way — try repair, then next start
-            }
-            break; // prefer the strict span at this start over its repair
-        }
-        if (parsedHere === undefined)
-            continue;
-        if (isPlainObject(parsedHere.value))
-            return parsedHere.value;
-        if (firstValue === undefined)
-            firstValue = parsedHere;
-    }
-    if (firstValue !== undefined)
-        return firstValue.value;
-    throw new Error('adjudicate: judge response is not valid JSON');
-}
-function isPlainObject(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-// Strip a single Markdown code fence that wraps the whole string.
-function stripCodeFence(text) {
-    const fence = text.match(/^```(?:json)?\s*\n?([\s\S]*?)\n?```$/);
-    return fence ? fence[1].trim() : text;
-}
-// Scan from `start` (a `{`/`[` index), tracking string and
-// bracket-nesting state, and emit the balanced JSON value rooted
-// there. Anything after the top-level value closes is ignored (so a
-// trailing code fence or commentary does not matter). With
-// `repair === false` the span is returned only if it actually closes,
-// and trailing commas are left intact — so the caller can prefer a
-// cleanly-balanced span before attempting repair; if input ends
-// before the value closes, undefined is returned. With
-// `repair === true` common damage is fixed: a trailing comma before a
-// close is removed, an unterminated string is closed, and any
-// brackets still open at end-of-input are closed in order.
-function extractJsonValue(text, start, repair) {
-    const stack = [];
-    let out = '';
-    let inString = false;
-    let escaped = false;
-    for (let i = start; i < text.length; i++) {
-        const ch = text[i];
-        if (inString) {
-            out += ch;
-            if (escaped)
-                escaped = false;
-            else if (ch === '\\')
-                escaped = true;
-            else if (ch === '"')
-                inString = false;
-            continue;
-        }
-        if (ch === '"') {
-            inString = true;
-            out += ch;
-            continue;
-        }
-        if (ch === '{' || ch === '[') {
-            stack.push(ch === '{' ? '}' : ']');
-            out += ch;
-            continue;
-        }
-        if (ch === '}' || ch === ']') {
-            if (repair)
-                out = dropTrailingComma(out);
-            out += ch;
-            stack.pop();
-            if (stack.length === 0)
-                return out; // top-level value complete
-            continue;
-        }
-        out += ch;
-    }
-    // End of input before the top-level value closed.
-    if (!repair)
-        return undefined; // strict pass: no balanced span here
-    if (inString)
-        out += '"';
-    out = dropTrailingComma(out);
-    while (stack.length > 0)
-        out += stack.pop();
-    return out;
-}
-// Remove a trailing comma (and any whitespace after it) at the end of
-// the accumulated output, so `{"a":1,}` / `[1,2,]` and truncated
-// `{"a":1,` repair to valid JSON.
-function dropTrailingComma(out) {
-    return out.replace(/,(\s*)$/, '$1');
+// CODE-specific adjudication strategy: the CODE judge prompt above, the
+// DR-004 `Output shall include` required-field extraction, and the
+// verbatim long-form payload fields.
+const CODE_ADJUDICATION = {
+    buildJudgePrompt: (input, finalText) => buildJudgePrompt(input, finalText),
+    extractRequiredFields,
+    verbatimPayloadFields: VERBATIM_PAYLOAD_FIELDS,
+};
+// LLM judge — DR-004 §4. Delegates to the shared adjudicator with the
+// CODE strategy: it lists each declared outcome verbatim, asks
+// ports.callJudge for a JSON `{ guard, …payloadFields }` response, and
+// returns the parsed object once the chosen guard is one of the
+// input.result keys. Adjudicator failures (malformed JSON,
+// missing/unknown guard) are control-plane errors and propagate via
+// throw per slc/link.md.
+async function adjudicate(input, finalText, ports, signal, boundary) {
+    return (await adjudicatePlayerOutput(CODE_ADJUDICATION, input, finalText, ports, signal, boundary));
 }
 // Boss-event classifier — DR-004 §3.
 // Every non-empty Boss turn goes through ports.callJudge. Slash-prefixed
@@ -384,19 +232,22 @@ function dropTrailingComma(out) {
 // classifier is state-aware so awaitBossReply can distinguish a direct
 // answer (BOSS_REPLY) from a fresh directive that abandons the pending
 // question through the FSM's existing transitions.
-async function classifyBossText(text, ports, signal, snapshotOrState) {
+async function classifyBossText(text, ports, signal, snapshotOrState, boundary) {
     const trimmed = text.trim();
     if (trimmed === '')
         return undefined;
-    return classifyWithLlm(text, ports, signal, snapshotOrState);
+    return classifyWithLlm(text, ports, signal, snapshotOrState, boundary);
 }
 const rootEvents = enumerateRootEvents(codingMachine);
 const bossInterruptTargets = rootEvents.bossInterruptTargetDescriptions;
 const bossInterruptTargetIds = new Set(bossInterruptTargets.map((target) => target.stateId));
-async function classifyWithLlm(text, ports, signal, snapshotOrState) {
+async function classifyWithLlm(text, ports, signal, snapshotOrState, boundary) {
     const state = classifierState(snapshotOrState);
     const prompt = buildClassifierPrompt(text, state);
-    const raw = await ports.callJudge(prompt, signal);
+    const stateId = typeof state.value === 'string' ? state.value : undefined;
+    const raw = boundary
+        ? await boundary.callJudge('boss-input-classification', stateId, prompt, signal)
+        : await ports.callJudge(prompt, signal);
     let parsed;
     try {
         parsed = parseJudgeJson(raw);
@@ -479,7 +330,26 @@ async function classifyWithLlm(text, ports, signal, snapshotOrState) {
                 await ports.emitStatus('Classifier omitted answer for BOSS_REPLY');
                 return undefined;
             }
-            return { type: 'BOSS_REPLY', answer: payload.answer };
+            const pending = pendingBossQuestionFromContext(state.context);
+            if (!pending) {
+                await ports.emitStatus('Classifier returned BOSS_REPLY without a pending question');
+                return undefined;
+            }
+            if (payload.questionId !== undefined &&
+                typeof payload.questionId !== 'string') {
+                await ports.emitStatus('Classifier supplied a non-string questionId for BOSS_REPLY');
+                return undefined;
+            }
+            if (typeof payload.questionId === 'string' &&
+                payload.questionId !== pending.questionId) {
+                await ports.emitStatus(`Classifier supplied unknown questionId for BOSS_REPLY: ${payload.questionId}`);
+                return undefined;
+            }
+            return {
+                type: 'BOSS_REPLY',
+                answer: payload.answer,
+                questionId: pending.questionId,
+            };
         }
         default:
             await ports.emitStatus(`Classifier returned unknown event type: ${eventType}`);
@@ -503,7 +373,9 @@ function classifierState(snapshotOrState) {
     return { value: snapshotOrState, context: {} };
 }
 function buildClassifierPrompt(text, state) {
-    const currentState = typeof state.value === 'string' ? state.value : 'unknown';
+    const currentState = typeof state.value === 'string'
+        ? state.value
+        : JSON.stringify(state.value ?? null);
     const pendingBossQuestion = pendingBossQuestionFromContext(state.context);
     const lines = [
         'Classify the following Boss message into exactly one of these events.',
@@ -513,14 +385,14 @@ function buildClassifierPrompt(text, state) {
         `Current state: ${currentState}`,
     ];
     if (pendingBossQuestion !== undefined) {
-        lines.push(`Pending Boss question: ${pendingBossQuestion.question}`, `Pending resume state: ${pendingBossQuestion.resumeStateId}`);
+        lines.push(`Pending question id: ${pendingBossQuestion.questionId}`, `Pending asking player: ${pendingBossQuestion.player}`, `Pending Boss question: ${pendingBossQuestion.question}`);
     }
     lines.push('', 'Events:', '- START_CODING: payload { intent: "<free-form goal>" }', '- CONTINUE_IR: payload { irNumber: "<number>" }', '- SUMMARIZE_IR: payload { irNumber: "<number>" }', '- BOSS_INTERRUPT: payload { targetId: "<stateId>", intent?: "<free-form goal>", irNumber?: "<number>" }', '  targetId must be one of these jumpable states:');
     for (const target of bossInterruptTargets) {
         lines.push(`  - ${target.stateId}: ${target.description}`);
     }
     if (currentState === 'awaitBossReply') {
-        lines.push('- BOSS_REPLY: payload { answer: "<verbatim Boss answer>" }');
+        lines.push('- BOSS_REPLY: payload { answer: "<verbatim Boss answer>", questionId?: "<pending question id>" }');
     }
     else {
         lines.push('- BOSS_REPLY: valid only when Current state is awaitBossReply');
@@ -528,36 +400,28 @@ function buildClassifierPrompt(text, state) {
     lines.push('', 'Boss message:', '```', text, '```');
     return lines.join('\n');
 }
-// Captain-actor bridge — DR-004 §7. One PromiseActorLogic that the
-// codingMachine invokes from every captain-invoking state. Per turn:
-// resolve playerId, compose the player prompt, await
-// ports.callPlayer, adjudicate the finalText. PlayerResult status of
-// 'aborted' or 'error' throws so XState routes via onError → #failed
-// (the single fail-stop sink for both Captain errors and player
-// failures).
+// Delegated-player actor bridge — DR-004 §7. One PromiseActorLogic that the
+// codingMachine invokes from every player-invoking state, built by the
+// shared createPlayerBridge with the CODE binding, composer, and
+// adjudication strategy. Per turn: resolve playerId, compose the player
+// prompt, await ports.callPlayer, adjudicate the finalText. PlayerResult
+// status of 'aborted' or 'error' throws so XState routes via onError →
+// #failed (the single fail-stop sink for both Captain errors and player
+// failures). Captain remains the orchestrator and adjudicator; it is not
+// encoded as the delegated FSM actor.
 //
 // `getActiveSignal` is the runtime's hook for flowing the Boss's
 // `handleBossInput.signal` into the host port calls — fromPromise
 // hands the bridge XState's actor-scoped signal, which only fires
 // on actor.stop(), not on Boss abort. When omitted (e.g. direct
 // captainBridge tests), the bridge falls back to XState's signal.
-function captainBridge(ports, getActiveSignal) {
-    return fromPromise(async ({ input, signal }) => {
-        const activeSignal = getActiveSignal?.() ?? signal;
-        const playerId = resolvePlayerId(input);
-        const prompt = composePlayerPrompt(input);
-        const result = await ports.callPlayer(playerId, prompt, activeSignal);
-        if (result.status !== 'ok') {
-            throw new Error(result.error ??
-                `captainBridge: callPlayer status "${result.status}"`);
-        }
-        if (result.finalText === undefined) {
-            throw new Error('captainBridge: callPlayer returned status=ok with no finalText');
-        }
-        const output = await adjudicate(input, result.finalText, ports, activeSignal);
-        validateBossReplyOutput(input, output);
-        return output;
-    });
+function captainBridge(ports, getActiveSignal, boundary, onControlPlaneError) {
+    return createPlayerBridge({
+        resolvePlayerId: (input) => resolvePlayerId(input),
+        composePlayerPrompt: (input) => composePlayerPrompt(input),
+        adjudication: CODE_ADJUDICATION,
+        resumableStateIds: registeredResumableStateIds,
+    }, ports, getActiveSignal, boundary, onControlPlaneError);
 }
 // Captain pane display — PBRT-3 / PBRT-14.
 // The Captain pane is a stream of three glyphs plus one bare
@@ -565,7 +429,7 @@ function captainBridge(ports, getActiveSignal) {
 // glance:
 //   (no glyph)  bare FSM event type — host renders as captain speech
 //               (e.g., `captain> START_CODING`)
-//   ⤷           captain-invoking state entry: `<Player>: <label>`
+//   ⤷           player-invoking state entry: `<Player>: <label>`
 //   →           transition guard outcome (`· field=N` tallies
 //               appended); the host presenter owns any visual
 //               nesting under the preceding ⤷ entry
@@ -602,29 +466,14 @@ const stateMetadata = (() => {
     for (const s of enumerateCaptainStates(codingMachine)) {
         const label = STATE_LABELS[s.stateId];
         if (!label) {
-            throw new Error(`code.playbook.ts: STATE_LABELS missing entry for captain-invoking state '${s.stateId}'`);
+            throw new Error(`code.playbook.ts: STATE_LABELS missing entry for player-invoking state '${s.stateId}'`);
         }
         const input = s.getInput({});
         m.set(s.stateId, { player: input.player, sourceItem: s.sourceItem, label });
     }
     return m;
 })();
-const stateIdBySourceItem = new Map([...stateMetadata.entries()].map(([stateId, meta]) => [
-    meta.sourceItem,
-    stateId,
-]));
 const registeredResumableStateIds = new Set(enumerateAwaitBossReply(codingMachine).bossReplyTransitions.map((transition) => transition.target));
-function validateBossReplyOutput(input, output) {
-    if (output.guard !== 'needsBossReply')
-        return;
-    if (typeof output.question !== 'string') {
-        throw new Error(BOSS_REPLY_ERRORS.missingQuestion);
-    }
-    const stateId = stateIdBySourceItem.get(input.sourceItem);
-    if (stateId === undefined || !registeredResumableStateIds.has(stateId)) {
-        throw new Error(BOSS_REPLY_ERRORS.unregisteredState(stateId ?? input.sourceItem));
-    }
-}
 const QUIESCENT_STATES = new Set([
     'ready',
     'awaitBossReply',
@@ -635,11 +484,8 @@ const QUIESCENT_STATES = new Set([
 // pane per PBRT-3: the readline returning to its `boss>` prompt is
 // the implicit "turn over" signal, so a `◆ ready` / `◆ done`
 // tombstone is redundant.
-const SUPPRESSED_ENTRY_STATES = new Set([
-    'ready',
-    'done',
-]);
-// Captain-pane surface (PBRT-3): every captain-invoking state plus
+const SUPPRESSED_ENTRY_STATES = new Set(['ready', 'done']);
+// Captain-pane surface (PBRT-3): every player-invoking state plus
 // the quiescent states whose entry still carries information
 // (failure with `lastError`, awaitBossReply with the pending
 // question). `ready` and `done` flow through the inspect handler
@@ -656,12 +502,14 @@ function pendingBossQuestionFromContext(context) {
     }
     const candidate = pending;
     if (typeof candidate.resumeStateId !== 'string' ||
+        typeof candidate.questionId !== 'string' ||
         typeof candidate.sourceItem !== 'string' ||
         typeof candidate.player !== 'string' ||
         typeof candidate.question !== 'string') {
         return undefined;
     }
     return {
+        questionId: candidate.questionId,
         resumeStateId: candidate.resumeStateId,
         sourceItem: candidate.sourceItem,
         player: candidate.player,
@@ -726,9 +574,9 @@ function formatClassification(eventType) {
 }
 function stateTelemetryPayload(from, to, event, context) {
     const payload = {
-        from,
+        from: from ?? null,
         to,
-        event: normalizeEventForTelemetry(event),
+        event: normalizeEventForTelemetry(event) ?? null,
     };
     if (to === 'awaitBossReply') {
         const pendingBossQuestion = pendingBossQuestionFromContext(context);
@@ -744,10 +592,40 @@ function stateTelemetryPayload(from, to, event, context) {
     }
     return payload;
 }
+// Captain-pane status lines for a root transition (PBRT-3 / PBRT-14):
+// the `→ guard` outcome line for the settling transition, then either
+// the awaitBossReply question + rider-less marker pair or the state's
+// entry line (with `lastError` data on `failed`).
+function statusesForState(state, context, event) {
+    const to = state.stateId;
+    if (to === undefined || !CAPTAIN_PANE_STATES.has(to))
+        return [];
+    const statuses = [];
+    const transitionLine = formatTransition(event);
+    if (transitionLine !== undefined) {
+        statuses.push({ message: transitionLine });
+    }
+    if (to === 'awaitBossReply') {
+        statuses.push({ message: formatAwaitBossReplyQuestion(context) }, { message: formatAwaitBossReplyMarker(context) });
+    }
+    else {
+        const entryLine = formatStateEntry(to);
+        if (entryLine !== undefined) {
+            const lastError = to === 'failed' ? normalizeErrorCompact(context.lastError) : undefined;
+            statuses.push({
+                message: entryLine,
+                ...(lastError === undefined
+                    ? {}
+                    : {
+                        data: snapshotJsonValue({ lastError }, 'failed status data'),
+                    }),
+            });
+        }
+    }
+    return statuses;
+}
 // Internal export surface for tests. Not part of the stable public API;
-// the leading underscore signals "subject to change." Each member is
-// referenced here so `noUnusedLocals` stays clean while later tasks
-// wire the factory body to use them.
+// the leading underscore signals "subject to change."
 export const _internal = {
     composePlayerPrompt,
     resolvePlayerId,
@@ -768,192 +646,25 @@ export const _internal = {
     normalizeEventForTelemetry,
     VERBATIM_PAYLOAD_FIELDS,
 };
-export default function createPlaybookRuntime(options) {
-    let actor;
-    let savedPorts;
-    // The Boss's per-turn AbortSignal, surfaced to captainBridge so
-    // ports.callPlayer / callJudge see the right cancellation source.
-    // null between turns; set by handleBossInput.
-    let activeSignal;
-    // Previous root-machine state for the inspect-driven telemetry /
-    // status emitter. undefined before the first inspect firing.
-    let priorState;
-    // Emission queue. slc/link.md says emissions "shall be ordered,
-    // awaited, and never-dropped"; subscribe/inspect callbacks are
-    // synchronous and can't await, so each emit is enqueued and a
-    // single drainer processes them sequentially.
-    const emitQueue = [];
-    let drainer;
-    function enqueueEmit(fn) {
-        emitQueue.push(fn);
-        if (!drainer) {
-            drainer = (async () => {
-                while (emitQueue.length > 0) {
-                    try {
-                        await emitQueue.shift()();
-                    }
-                    catch {
-                        // Suppress host-side emission errors; the control plane
-                        // surfaces real failures via handleBossInput throws.
-                    }
-                }
-                drainer = undefined;
-            })();
-        }
-    }
-    function drainEmissions() {
-        return drainer ?? Promise.resolve();
-    }
-    function buildActor(ports) {
-        priorState = undefined;
-        return createActor(codingMachine.provide({
-            actors: { captain: captainBridge(ports, () => activeSignal) },
-        }), {
-            input: options,
-            inspect: (inspectionEvent) => {
-                if (inspectionEvent.type !== '@xstate.snapshot')
-                    return;
-                const snap = inspectionEvent.snapshot;
-                // Filter out captain sub-actor (fromPromise) snapshots —
-                // only the root codingMachine snapshot has a string value.
-                if (typeof snap.value !== 'string')
-                    return;
-                const to = snap.value;
-                if (priorState === to)
-                    return;
-                const from = priorState;
-                priorState = to;
-                // Telemetry on every transition (PBRT-14).
-                const context = snap.context ?? {};
-                enqueueEmit(() => ports.emitTelemetry({
-                    topic: 'playbook.fsm.state',
-                    payload: stateTelemetryPayload(from, to, inspectionEvent.event, context),
-                }));
-                // Captain pane (PBRT-3 / PBRT-14): show the transition
-                // guard first (when this is an actor-done transition with
-                // a known guard), then the new state entry, then any
-                // context riders the entering state cares about. Terminal
-                // entry to `failed` carries `lastError` as the data arg.
-                if (!CAPTAIN_PANE_STATES.has(to))
-                    return;
-                const transitionLine = formatTransition(inspectionEvent.event);
-                if (transitionLine !== undefined) {
-                    enqueueEmit(() => ports.emitStatus(transitionLine));
-                }
-                // awaitBossReply surfaces two lines per PBRT-3 / PBRT-14: the
-                // full player question as captain speech, then the rider-less
-                // routing marker. The full-question telemetry rides
-                // stateTelemetryPayload above.
-                if (to === 'awaitBossReply') {
-                    const questionLine = formatAwaitBossReplyQuestion(context);
-                    const markerLine = formatAwaitBossReplyMarker(context);
-                    enqueueEmit(() => ports.emitStatus(questionLine));
-                    enqueueEmit(() => ports.emitStatus(markerLine));
-                    return;
-                }
-                const entryLine = formatStateEntry(to);
-                if (entryLine === undefined)
-                    return;
-                if (to === 'failed') {
-                    const lastError = snap.context
-                        ?.lastError;
-                    const data = { lastError: normalizeErrorCompact(lastError) };
-                    enqueueEmit(() => ports.emitStatus(entryLine, data));
-                }
-                else {
-                    enqueueEmit(() => ports.emitStatus(entryLine));
-                }
-            },
-        });
-    }
-    const runtime = {
-        async init(ports) {
-            savedPorts = ports;
-            actor = buildActor(ports);
-            actor.start();
-            await drainEmissions();
-        },
-        async handleBossInput({ text, signal, }) {
-            if (!actor || !savedPorts) {
-                throw new Error('createPlaybookRuntime.handleBossInput: init must be called first');
-            }
-            activeSignal = signal;
-            try {
-                // 1. Classify non-empty text into an FSM event through the judge.
-                const event = await classifyBossText(text, savedPorts, signal, actor.getSnapshot());
-                // Empty input, no-action classifier output, or invalid classifier
-                // output — nothing to send.
-                if (event === undefined) {
-                    await drainEmissions();
-                    return;
-                }
-                // 2. Captain-pane classification line (PBRT-14): the bare
-                //    FSM event type, emitted before the FSM advances so the
-                //    host can render it as captain speech (e.g.,
-                //    `captain> START_CODING`). Enqueued so it interleaves
-                //    cleanly with the inspect-driven transition emissions.
-                const echoPorts = savedPorts;
-                enqueueEmit(() => echoPorts.emitStatus(formatClassification(event.type)));
-                // 3. final state ('done') cannot accept new events — dispose
-                //    and reconstruct per DR-004 §5.
-                if (actor.getSnapshot().status === 'done') {
-                    actor.stop();
-                    actor = buildActor(savedPorts);
-                    actor.start();
-                }
-                // 4. Send the event.
-                actor.send(event);
-                // 5. Drive to quiescence. On signal-abort we take no FSM
-                //    action: the captain bridge's awaited callPlayer rejects
-                //    naturally, the bridge throws, XState routes through
-                //    onError → #failed, and this loop sees the quiescent
-                //    snapshot and returns (DR-004 §8 natural rejection).
-                await driveToQuiescence(actor);
-                // Drain transition emissions before returning so the Boss
-                // sees the final status line for this turn.
-                await drainEmissions();
-            }
-            finally {
-                activeSignal = undefined;
-            }
-        },
-        async dispose() {
-            if (actor) {
-                actor.stop();
-                actor = undefined;
-            }
-            // Drain any in-flight emissions per slc/link.md §Session
-            // lifecycle ("stop the actor and drain pending port emissions").
-            await drainEmissions();
-            savedPorts = undefined;
-        },
-        // @internal — test-only escape hatch for inspecting the
-        // underlying actor's snapshot. Most state assertions are now
-        // expressible via the recorded emitStatus / emitTelemetry
-        // calls (DR-004 §9); the hatch stays for the few cases where
-        // direct context inspection is clearer (e.g., the dispose
-        // teardown test).
-        _getActor() {
-            return actor;
-        },
-    };
-    return runtime;
-}
-function driveToQuiescence(actor) {
-    return new Promise((resolve) => {
-        if (isQuiescent(actor.getSnapshot())) {
-            resolve();
-            return;
-        }
-        const sub = actor.subscribe((snap) => {
-            if (isQuiescent(snap)) {
-                sub.unsubscribe();
-                resolve();
-            }
-        });
-    });
-}
-function isQuiescent(snap) {
-    const v = snap.value;
-    return typeof v === 'string' && QUIESCENT_STATES.has(v);
-}
+// The CODE-specific spec handed to the shared runtime factory
+// (slc/link.md §Output, DR-019). The generic machinery — actor wiring,
+// boundary tracing, Boss-turn lifecycle, nested-playbook bridge, and the
+// DR-014 parked-session snapshot capability — lives in
+// @sublang/playbook/xstate-runtime; this spec carries only what is
+// CODE-specific.
+const runtimeSpec = {
+    label: 'CODE',
+    snapshotOptions: snapshotCodePlaybookOptions,
+    resolvePlayerId: (input) => resolvePlayerId(input),
+    composePlayerPrompt: (input) => composePlayerPrompt(input),
+    buildJudgePrompt: CODE_ADJUDICATION.buildJudgePrompt,
+    extractRequiredFields,
+    verbatimPayloadFields: VERBATIM_PAYLOAD_FIELDS,
+    resumableStateIds: registeredResumableStateIds,
+    classifyBossText: (text, ports, signal, snapshotOrState, boundary) => classifyBossText(text, ports, signal, snapshotOrState, boundary),
+    classificationStatus: (event) => formatClassification(event.type),
+    statusesForState,
+    normalizeTransitionEvent: (event) => normalizeEventForTelemetry(event),
+};
+const createPlaybookRuntime = createXStatePlaybookRuntime(codingMachine, runtimeSpec);
+export default createPlaybookRuntime;