@sublang/playbook 0.9.0 → 1.3.0

package/reference/sdlc/code.playbook/code.playbook.ts

@@ -11,15 +11,35 @@
 //                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)
+// 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 { createActor, fromPromise } from 'xstate';
+import {
+  createPlayerBridge,
+  createXStatePlaybookRuntime,
+  adjudicatePlayerOutput,
+  normalizeError,
+  normalizeErrorCompact,
+  normalizeErrorFull,
+  parseJudgeJson,
+  snapshotJsonValue,
+  type PlaybookPlayerInput,
+  type RuntimeBoundaryCalls,
+  type ScheduledStatus,
+  type XStatePlaybookRuntimeSpec,
+} from '../../../src/xstate-runtime.js';
 import {
   codingMachine,
-  type CaptainInput,
-  type CaptainOutput,
+  type PlayerInput,
+  type PlayerOutput,
   type CodingEvent,
   type CodingInput,
 } from './code.fsm.js';
@@ -29,27 +49,87 @@ import {
   enumerateRootEvents,
 } from './code.fsm.introspect.js';
 import type {
+  CaptainCallOptions,
+  CaptainResult,
+  JsonValue,
+  NormalizedError,
+  PlayerCallOptions,
+  PlaybookCallRequest,
+  PlaybookCallResult,
+  PlaybookCallStart,
+  PlaybookPendingCall,
+  PlaybookRunResult,
+  PlaybookRuntimeSnapshot,
+  PlaybookSession,
+  PlaybookState,
+  PlaybookStateValue,
+  PlaybookTraceEvent,
+  PlaybookTraceType,
   PlaybookPorts,
   PlaybookRuntime,
+  PlaybookRuntimeFactory,
   PlayerResult,
 } from '@sublang/playbook/runtime';
 
-// Public contract. `PlayerResult`, `PlaybookPorts`, and `PlaybookRuntime`
-// are re-exported from the shared `@sublang/playbook/runtime` module
+// Public contract. `PlayerResult`, `PlaybookPorts`, `PlaybookSession`, and
+// `PlaybookRuntime` are re-exported from the shared runtime module
 // (slc/link.md §Output, DR-004 Addendum A4) so this playbook and any
 // future one resolve one contract definition rather than redefining it.
 // `CodePlaybookOptions` and the default `createPlaybookRuntime` factory
 // (typed `PlaybookRuntimeFactory<CodePlaybookOptions>`) stay
 // CODE-specific.
-export type { PlayerResult, PlaybookPorts, PlaybookRuntime };
+export type {
+  CaptainCallOptions,
+  CaptainResult,
+  JsonValue,
+  NormalizedError,
+  PlayerCallOptions,
+  PlaybookCallRequest,
+  PlaybookCallResult,
+  PlaybookCallStart,
+  PlaybookPendingCall,
+  PlaybookRunResult,
+  PlayerResult,
+  PlaybookPorts,
+  PlaybookSession,
+  PlaybookState,
+  PlaybookStateValue,
+  PlaybookTraceEvent,
+  PlaybookTraceType,
+  PlaybookRuntime,
+  PlaybookRuntimeFactory,
+  PlaybookRuntimeSnapshot,
+};
 
 export type CodePlaybookOptions = CodingInput;
 
-const BOSS_REPLY_ERRORS = {
-  missingQuestion: "needsBossReply outcome missing 'question' field",
-  unregisteredState: (stateId: string) =>
-    `state ${stateId} declared needsBossReply but is not registered as resumable`,
-} as const;
+function snapshotCodePlaybookOptions(value: unknown): CodePlaybookOptions {
+  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 as Readonly<Record<string, JsonValue>>;
+  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 as unknown as CodePlaybookOptions;
+}
 
 // Required-payload fields whose value is the player's verbatim long-form
 // prose. The runtime carries `finalText.trim()` into these fields rather
@@ -61,64 +141,56 @@ const VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string> = new Set([
   '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: unknown,
-): { name: string; message: string } | undefined {
-  if (err === undefined || err === null) return undefined;
-  if (err instanceof Error) {
-    return { name: err.name, message: err.message };
-  }
-  if (typeof err === 'object') {
-    const o = err as Record<string, unknown>;
-    if (typeof o.message === 'string') {
-      return {
-        name: typeof o.name === 'string' ? o.name : 'Error',
-        message: o.message,
-      };
-    }
-  }
-  return { name: 'Error', message: String(err) };
-}
-
-// 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: unknown,
-): { name: string; message: string; stack?: string } | undefined {
-  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 as Record<string, unknown>).stack;
-    if (typeof stack === 'string') {
-      return { ...compact, stack };
-    }
-  }
-  return compact;
-}
-
 // Normalize any `error` field inside a telemetry event so failed
 // transitions don't leak raw Error instances through the channel.
 function normalizeEventForTelemetry(event: unknown): unknown {
-  if (event === null || typeof event !== 'object' || Array.isArray(event)) {
-    return event;
+  if (event === undefined) return undefined;
+  return normalizeEventValue(event, 'FSM event', new Set());
+}
+
+function normalizeEventValue(
+  value: unknown,
+  path: string,
+  ancestors: ReadonlySet<object>,
+): JsonValue {
+  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) as unknown;
+  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: Record<string, JsonValue> = {};
+  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,
+          );
   }
-  const e = event as Record<string, unknown>;
-  if (!('error' in e)) return event;
-  const normalized = normalizeErrorFull(e.error);
-  return { ...e, error: normalized };
+  return snapshotJsonValue(normalized, path);
 }
 
-// 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
@@ -131,7 +203,7 @@ function normalizeEventForTelemetry(event: unknown): unknown {
 // reply, the continuation preamble and Q/A blocks precede every
 // ordinary block. The FSM's prompt body is never re-flowed.
 
-function composePlayerPrompt(input: CaptainInput): string {
+function composePlayerPrompt(input: PlayerInput): string {
   const blocks: string[] = [];
   if (
     input.pendingBossQuestion !== undefined &&
@@ -189,7 +261,7 @@ function composePlayerPrompt(input: CaptainInput): string {
 // set. The alias selects only the host pane; it is not a PBRT-4
 // identity string, so it leaves <coder-llm> / <reviewer-llm>
 // untouched and `input.player` stays `Committer` (PLAYBOOK-3).
-function resolvePlayerId(input: CaptainInput): string {
+function resolvePlayerId(input: PlayerInput): string {
   switch (input.player) {
     case 'Coder':
       return 'coder';
@@ -202,69 +274,9 @@ function resolvePlayerId(input: CaptainInput): string {
       return 'coder';
     default: {
       const exhaustive: never = input.player;
-      throw new Error(
-        `resolvePlayerId: unknown player ${String(exhaustive)}`,
-      );
-    }
-  }
-}
-
-// 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: CaptainInput,
-  finalText: string,
-  ports: PlaybookPorts,
-  signal: AbortSignal,
-): Promise<CaptainOutput> {
-  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 as Record<string, unknown>;
-  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}"`,
-      );
+      throw new Error(`resolvePlayerId: unknown player ${String(exhaustive)}`);
     }
   }
-  return obj as CaptainOutput;
 }
 
 function extractRequiredFields(description: string): string[] {
@@ -276,7 +288,7 @@ function extractRequiredFields(description: string): string[] {
   return fields;
 }
 
-function buildJudgePrompt(input: CaptainInput, finalText: string): string {
+function buildJudgePrompt(input: PlayerInput, finalText: string): string {
   const lines: string[] = [];
   lines.push(`The ${input.player} just produced this output:`);
   lines.push('');
@@ -299,137 +311,38 @@ function buildJudgePrompt(input: CaptainInput, finalText: string): string {
   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: string): unknown {
-  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: number[] = [];
-  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: { value: unknown } | undefined;
-  for (const start of starts) {
-    let parsedHere: { value: unknown } | undefined;
-    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: unknown): boolean {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-// Strip a single Markdown code fence that wraps the whole string.
-function stripCodeFence(text: string): string {
-  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: string,
-  start: number,
-  repair: boolean,
-): string | undefined {
-  const stack: string[] = [];
-  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;
-}
+// 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: PlaybookPlayerInput, finalText: string) =>
+    buildJudgePrompt(input as unknown as PlayerInput, finalText),
+  extractRequiredFields,
+  verbatimPayloadFields: VERBATIM_PAYLOAD_FIELDS,
+};
 
-// 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: string): string {
-  return out.replace(/,(\s*)$/, '$1');
+// 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: PlayerInput,
+  finalText: string,
+  ports: PlaybookPorts,
+  signal: AbortSignal,
+  boundary?: RuntimeBoundaryCalls,
+): Promise<PlayerOutput> {
+  return (await adjudicatePlayerOutput(
+    CODE_ADJUDICATION,
+    input,
+    finalText,
+    ports,
+    signal,
+    boundary,
+  )) as unknown as PlayerOutput;
 }
 
 // Boss-event classifier — DR-004 §3.
@@ -444,11 +357,12 @@ async function classifyBossText(
   ports: PlaybookPorts,
   signal: AbortSignal,
   snapshotOrState?: unknown,
+  boundary?: RuntimeBoundaryCalls,
 ): Promise<CodingEvent | undefined> {
   const trimmed = text.trim();
   if (trimmed === '') return undefined;
 
-  return classifyWithLlm(text, ports, signal, snapshotOrState);
+  return classifyWithLlm(text, ports, signal, snapshotOrState, boundary);
 }
 
 // JumpableStateId is internal to code.fsm.ts (not exported), so
@@ -469,10 +383,19 @@ async function classifyWithLlm(
   ports: PlaybookPorts,
   signal: AbortSignal,
   snapshotOrState?: unknown,
+  boundary?: RuntimeBoundaryCalls,
 ): Promise<CodingEvent | undefined> {
   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: unknown;
   try {
     parsed = parseJudgeJson(raw);
@@ -562,7 +485,36 @@ async function classifyWithLlm(
         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(
@@ -602,7 +554,9 @@ function classifierState(snapshotOrState: unknown): ClassifierState {
 
 function buildClassifierPrompt(text: string, state: ClassifierState): string {
   const currentState =
-    typeof state.value === 'string' ? state.value : 'unknown';
+    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.',
@@ -613,8 +567,9 @@ function buildClassifierPrompt(text: string, state: ClassifierState): string {
   ];
   if (pendingBossQuestion !== undefined) {
     lines.push(
+      `Pending question id: ${pendingBossQuestion.questionId}`,
+      `Pending asking player: ${pendingBossQuestion.player}`,
       `Pending Boss question: ${pendingBossQuestion.question}`,
-      `Pending resume state: ${pendingBossQuestion.resumeStateId}`,
     );
   }
   lines.push(
@@ -630,27 +585,25 @@ function buildClassifierPrompt(text: string, state: ClassifierState): string {
     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');
   }
-  lines.push(
-    '',
-    'Boss message:',
-    '```',
-    text,
-    '```',
-  );
+  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
@@ -660,33 +613,22 @@ function buildClassifierPrompt(text: string, state: ClassifierState): string {
 function captainBridge(
   ports: PlaybookPorts,
   getActiveSignal?: () => AbortSignal | undefined,
+  boundary?: RuntimeBoundaryCalls,
+  onControlPlaneError?: (error: unknown) => void,
 ) {
-  return fromPromise<CaptainOutput, CaptainInput>(
-    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;
+  return createPlayerBridge(
+    {
+      resolvePlayerId: (input) =>
+        resolvePlayerId(input as unknown as PlayerInput),
+      composePlayerPrompt: (input) =>
+        composePlayerPrompt(input as unknown as PlayerInput),
+      adjudication: CODE_ADJUDICATION,
+      resumableStateIds: registeredResumableStateIds,
     },
+    ports,
+    getActiveSignal,
+    boundary,
+    onControlPlaneError,
   );
 }
 
@@ -696,7 +638,7 @@ function captainBridge(
 // 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
@@ -735,7 +677,7 @@ const STATE_LABELS: Readonly<Record<string, string>> = {
 };
 
 interface StateMetadata {
-  player: CaptainInput['player'];
+  player: PlayerInput['player'];
   sourceItem: string;
   label: string;
 }
@@ -746,7 +688,7 @@ const stateMetadata: ReadonlyMap<string, StateMetadata> = (() => {
     const label = STATE_LABELS[s.stateId];
     if (!label) {
       throw new Error(
-        `code.playbook.ts: STATE_LABELS missing entry for captain-invoking state '${s.stateId}'`,
+        `code.playbook.ts: STATE_LABELS missing entry for player-invoking state '${s.stateId}'`,
       );
     }
     const input = s.getInput({});
@@ -755,35 +697,12 @@ const stateMetadata: ReadonlyMap<string, StateMetadata> = (() => {
   return m;
 })();
 
-const stateIdBySourceItem: ReadonlyMap<string, string> = new Map(
-  [...stateMetadata.entries()].map(([stateId, meta]) => [
-    meta.sourceItem,
-    stateId,
-  ]),
-);
-
 const registeredResumableStateIds: ReadonlySet<string> = new Set(
   enumerateAwaitBossReply(codingMachine).bossReplyTransitions.map(
     (transition) => transition.target,
   ),
 );
 
-function validateBossReplyOutput(
-  input: CaptainInput,
-  output: CaptainOutput,
-): void {
-  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: ReadonlySet<string> = new Set([
   'ready',
   'awaitBossReply',
@@ -795,12 +714,9 @@ const QUIESCENT_STATES: ReadonlySet<string> = 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: ReadonlySet<string> = new Set([
-  'ready',
-  'done',
-]);
+const SUPPRESSED_ENTRY_STATES: ReadonlySet<string> = new Set(['ready', 'done']);
 
-// Captain-pane surface (PBRT-3): every captain-invoking state plus
+// 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
@@ -811,7 +727,12 @@ const CAPTAIN_PANE_STATES: ReadonlySet<string> = new Set([
   ...QUIESCENT_STATES,
 ]);
 
+type BossReplyQuestionId = NonNullable<
+  Extract<CodingEvent, { type: 'BOSS_REPLY' }>['questionId']
+>;
+
 interface PendingBossQuestionForStatus {
+  questionId: BossReplyQuestionId;
   resumeStateId: string;
   sourceItem: string;
   player: string;
@@ -830,6 +751,7 @@ function pendingBossQuestionFromContext(
   >;
   if (
     typeof candidate.resumeStateId !== 'string' ||
+    typeof candidate.questionId !== 'string' ||
     typeof candidate.sourceItem !== 'string' ||
     typeof candidate.player !== 'string' ||
     typeof candidate.question !== 'string'
@@ -837,6 +759,7 @@ function pendingBossQuestionFromContext(
     return undefined;
   }
   return {
+    questionId: candidate.questionId as BossReplyQuestionId,
     resumeStateId: candidate.resumeStateId,
     sourceItem: candidate.sourceItem,
     player: candidate.player,
@@ -864,9 +787,7 @@ function formatAwaitBossReplyQuestion(
 // It carries only the resume target, asking player, and source item;
 // the former `q="<first 80 chars>"` excerpt rider is dropped now that
 // the full question rides the captain-speech line above.
-function formatAwaitBossReplyMarker(
-  context: Record<string, unknown>,
-): string {
+function formatAwaitBossReplyMarker(context: Record<string, unknown>): string {
   const pending = pendingBossQuestionFromContext(context);
   const resumeStateId = pending?.resumeStateId ?? 'unknown';
   const player = pending?.player ?? 'unknown';
@@ -912,9 +833,9 @@ function stateTelemetryPayload(
   context: Record<string, unknown>,
 ): Record<string, unknown> {
   const payload: Record<string, unknown> = {
-    from,
+    from: from ?? null,
     to,
-    event: normalizeEventForTelemetry(event),
+    event: normalizeEventForTelemetry(event) ?? null,
   };
   if (to === 'awaitBossReply') {
     const pendingBossQuestion = pendingBossQuestionFromContext(context);
@@ -931,10 +852,47 @@ function stateTelemetryPayload(
   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: PlaybookState,
+  context: Record<string, unknown>,
+  event: unknown,
+): ScheduledStatus[] {
+  const to = state.stateId;
+  if (to === undefined || !CAPTAIN_PANE_STATES.has(to)) return [];
+  const statuses: ScheduledStatus[] = [];
+  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,
@@ -956,228 +914,31 @@ export const _internal = {
   VERBATIM_PAYLOAD_FIELDS,
 };
 
-export default function createPlaybookRuntime(
-  options: CodePlaybookOptions,
-): PlaybookRuntime {
-  let actor: ReturnType<typeof createActor> | undefined;
-  let savedPorts: PlaybookPorts | undefined;
-  // 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: AbortSignal | undefined;
-  // Previous root-machine state for the inspect-driven telemetry /
-  // status emitter. undefined before the first inspect firing.
-  let priorState: unknown;
-
-  // 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: Array<() => Promise<void>> = [];
-  let drainer: Promise<void> | undefined;
-
-  function enqueueEmit(fn: () => Promise<void>): void {
-    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(): Promise<void> {
-    return drainer ?? Promise.resolve();
-  }
-
-  function buildActor(
-    ports: PlaybookPorts,
-  ): ReturnType<typeof createActor> {
-    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 as {
-            value?: unknown;
-            context?: Record<string, unknown>;
-          };
-          // 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 as { lastError?: unknown })
-              ?.lastError;
-            const data = { lastError: normalizeErrorCompact(lastError) };
-            enqueueEmit(() => ports.emitStatus(entryLine, data));
-          } else {
-            enqueueEmit(() => ports.emitStatus(entryLine));
-          }
-        },
-      },
-    );
-  }
-
-  const runtime = {
-    async init(ports: PlaybookPorts): Promise<void> {
-      savedPorts = ports;
-      actor = buildActor(ports);
-      actor.start();
-      await drainEmissions();
-    },
-
-    async handleBossInput({
-      text,
-      signal,
-    }: {
-      text: string;
-      signal: AbortSignal;
-    }): Promise<void> {
-      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(): Promise<void> {
-      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 as PlaybookRuntime;
-}
+// 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: XStatePlaybookRuntimeSpec<CodePlaybookOptions> = {
+  label: 'CODE',
+  snapshotOptions: snapshotCodePlaybookOptions,
+  resolvePlayerId: (input) => resolvePlayerId(input as unknown as PlayerInput),
+  composePlayerPrompt: (input) =>
+    composePlayerPrompt(input as unknown as PlayerInput),
+  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) as JsonValue | undefined,
+};
 
-function driveToQuiescence(
-  actor: ReturnType<typeof createActor>,
-): Promise<void> {
-  return new Promise<void>((resolve) => {
-    if (isQuiescent(actor.getSnapshot())) {
-      resolve();
-      return;
-    }
-    const sub = actor.subscribe((snap) => {
-      if (isQuiescent(snap)) {
-        sub.unsubscribe();
-        resolve();
-      }
-    });
-  });
-}
+const createPlaybookRuntime: PlaybookRuntimeFactory<CodePlaybookOptions> =
+  createXStatePlaybookRuntime(codingMachine, runtimeSpec);
 
-function isQuiescent(snap: { value: unknown }): boolean {
-  const v = snap.value;
-  return typeof v === 'string' && QUIESCENT_STATES.has(v);
-}
+export default createPlaybookRuntime;