@sublang/playbook 15.0.0 → 16.0.0

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

@@ -1,287 +1,238 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
-//
-// Generated by slc/link.md (FSM-to-Runtime linker).
-// Source FSM:    ./code.fsm.ts
-// Role metadata: Coder→coder (canonical local role)
-// Boss event:    deterministic START_CODE entry; exact Boss text becomes
-//                callerInput; pending Coder questions retain BOSS_REPLY
-// Adjudication:  LLM judge per player state; coderOutput is carried verbatim;
-//                the first phase decides among four semantic outcomes
-// Nested call:   literal review target through the shared bridge
-// Compat:        artifact schema 3 / runtime ABI 1
-
+// Generated by slc/materialize-link.mjs; governed by the complete slc/link.md.
+// FSM: "./code.fsm.js"; export: codeMachine; strategies: shared defaults with labelled string relays and nested actors.
+import { codeMachine as machine } from "./code.fsm.js";
+import type { PlayerInput as SourcePlayerInput } from "./code.fsm.js";
 import {
-  createXStatePlaybookRuntime,
-  composePlayerContinuation,
-  snapshotJsonValue,
+  createXStatePlaybookRuntime, snapshotJsonValue,
+  composePlayerContinuation, type XStatePromptIdentity,
   type PlaybookPlayerInput,
-  type XStatePlaybookRuntimeFactory,
   type XStatePlaybookRuntimeConstruction,
-  type XStatePromptIdentity,
+  type XStatePlaybookRuntimeFactory,
   type XStatePlaybookRuntimeSpecV3,
 } from '@sublang/playbook/xstate-runtime';
-import {
-  codingMachine,
-  type CodingInput,
-  type PlayerInput,
-} from './code.fsm.js';
-import type { PlaybookHostConstructionCapabilities } from './playbook-captain.js';
-import type {
-  CaptainCallOptions,
-  CaptainResult,
-  JsonValue,
-  NormalizedError,
-  PlayerCallOptions,
-  PlaybookCallRequest,
-  PlaybookCallResult,
-  PlaybookCallStart,
-  PlaybookControlReceipt,
-  PlaybookControlView,
-  PlaybookPendingCall,
-  PlaybookPorts,
-  PlaybookRunResult,
-  PlaybookRuntime,
-  PlaybookRuntimeFactory,
-  PlaybookRuntimeSnapshot,
-  PlaybookSession,
-  PlaybookState,
-  PlaybookStateValue,
-  PlaybookTraceEvent,
-  PlaybookTraceType,
+export type {
   PlayerResult,
+  PlayerCallOptions,
   PlayerSessionStore,
-} from '@sublang/playbook/runtime';
-
-export type {
-  CaptainCallOptions,
   CaptainResult,
+  CaptainCallOptions,
   JsonValue,
   NormalizedError,
-  PlayerCallOptions,
   PlaybookCallRequest,
   PlaybookCallResult,
   PlaybookCallStart,
-  PlaybookControlReceipt,
-  PlaybookControlView,
+  PlaybookStateValue,
+  PlaybookState,
   PlaybookPendingCall,
-  PlaybookPorts,
   PlaybookRunResult,
   PlaybookRuntime,
   PlaybookRuntimeFactory,
   PlaybookRuntimeSnapshot,
   PlaybookSession,
-  PlaybookState,
-  PlaybookStateValue,
+  PlaybookPorts,
   PlaybookTraceEvent,
   PlaybookTraceType,
-  PlayerResult,
-  PlayerSessionStore,
-};
-
-export type CodePlaybookOptions = CodingInput;
-export type CodePlaybookHostCapabilities =
-  PlaybookHostConstructionCapabilities &
-    XStatePlaybookRuntimeConstruction<CodePlaybookOptions, object>['hostCapabilities'];
+  PlaybookControlReceipt,
+  PlaybookControlView,
+} from '@sublang/playbook/runtime';
 
-const OPTION_KEYS = new Set(['runResults']);
-const PLACEHOLDER = /<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>/g;
+export interface PlaybookRuntimeOptions {
+  readonly "runResults"?: string;
+}
+export type PlaybookHostCapabilities = XStatePlaybookRuntimeConstruction<
+  PlaybookRuntimeOptions, { readonly authority: object }
+>['hostCapabilities'];
 
-const VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string> = new Set([
-  'coderOutput',
+const OPTION_SCHEMA = {
+  "runResults": {
+    "type": "string",
+    "required": false
+  }
+} as const;
+const INPUT_MAPPING = {
+  "runResults": "runResults"
+} as const;
+const RESUMABLE_STATE_IDS: ReadonlySet<string> = new Set([
+  "firstPhase",
+  "irTaskPhase"
 ]);
 const UNFINISHED_FINAL_STATE_IDS: ReadonlySet<string> = new Set([
-  'reportedReviewFailure',
+  "reviewFailed"
 ]);
-
-function snapshotCodeOptions(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 VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string> = new Set([
+  "coderOutput"
+]);
+export function validateOptions(value: unknown): PlaybookRuntimeOptions {
+  const captured = snapshotJsonValue(value === undefined ? {} : 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>>;
-  for (const [key, option] of Object.entries(record)) {
-    if (!OPTION_KEYS.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`);
+  const fields = captured as Readonly<Record<string, unknown>>;
+  for (const key of Object.keys(captured)) {
+    if (!Object.hasOwn(OPTION_SCHEMA, key)) throw new TypeError("CODE runtime options." + key + ' is not declared');
+  }
+  for (const [key, schema] of Object.entries(OPTION_SCHEMA) as [string, { type: string; required: boolean }][]) {
+    if (!Object.hasOwn(captured, key)) {
+      if (schema.required) throw new TypeError("CODE runtime options." + key + ' is required');
+    } else if (typeof fields[key] !== schema.type || (schema.type === 'number' && !Number.isFinite(fields[key]))) {
+      throw new TypeError("CODE runtime options." + key + ' must be a ' + schema.type);
     }
   }
-  return captured as unknown as CodePlaybookOptions;
-}
-
-function placeholderField(token: string): string {
-  if (token === '#') return 'irNumber';
-  return token.replace(/-([A-Za-z0-9_$])/g, (_match, next: string) =>
-    next.toUpperCase(),
-  );
+  return captured as unknown as PlaybookRuntimeOptions;
 }
-
-function quoteContinuation(value: string): string {
-  return value.replaceAll('\n', '\n> ');
-}
-
-/**
- * Preserve authored Markdown quote markers around every line of relayed
- * runtime text. The generic composer preserves the marker itself; CODE's
- * override additionally keeps a multiline value inside that quote.
- */
-function composePlayerPrompt(
-  input: PlayerInput,
-  promptIdentity: XStatePromptIdentity,
-  resuming = false,
-): string {
-  const fields = input as unknown as Record<string, unknown>;
-  const template = input.prompt
-    .split('\n')
-    .filter(
-      (line) => !(line === '> Run results: <run-results>' && input.runResults.length === 0),
-    )
-    .join('\n');
-  const body = template.replace(
-    PLACEHOLDER,
-    (match: string, token: string, offset: number, source: string) => {
-      const value =
-        token === 'coder-llm'
-          ? promptIdentity('coder')
-          : fields[placeholderField(token)];
+function renderPlayerPrompt(input: SourcePlayerInput, promptIdentity: XStatePromptIdentity, resuming = false): string {
+  const fields = input as unknown as Readonly<Record<string, unknown>>;
+  const mapping: Readonly<Record<string, string>> = {};
+  const identities: Readonly<Record<string, string>> = {"coder-llm":"coder"};
+  const omitted = new Set<string>(["> Run results: <run-results>"]);
+  const fieldFor = (token: string): string => Object.hasOwn(mapping, token) ? mapping[token]! : (token === '#' ? 'irNumber' : token.replace(/-([A-Za-z0-9_$])/g, (_match: string, next: string) => next.toUpperCase()));
+  const parts = input.prompt.split(/(\r?\n)/);
+  let body = '';
+  for (let index = 0; index < parts.length; index += 2) {
+    const line = parts[index]!;
+    if (omitted.has(line)) {
+      const token = /<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>$/.exec(line)![1]!;
+      if (fields[fieldFor(token)] === '') continue;
+    }
+    body += line.replace(/<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>/g, (match: string, token: string): string => {
+      const value = Object.hasOwn(identities, token) ? promptIdentity(identities[token]!) : fields[fieldFor(token)];
       if (typeof value !== 'string') return match;
-      const lineStart = source.lastIndexOf('\n', offset - 1) + 1;
-      const literal = source.slice(lineStart, offset);
-      return literal.startsWith('> ') ? quoteContinuation(value) : value;
-    },
-  );
+      return line.startsWith('> ') ? value.replace(/\r?\n/g, (ending: string) => ending + '> ') : value;
+    }) + (parts[index + 1] ?? '');
+  }
   return composePlayerContinuation(input, body, resuming);
 }
-
-export const _internal = {
-  composePlayerPrompt,
-  VERBATIM_PAYLOAD_FIELDS,
-  UNFINISHED_FINAL_STATE_IDS,
-};
-
+const composePlayerPrompt = (input: PlaybookPlayerInput, promptIdentity: XStatePromptIdentity, resuming?: boolean): string =>
+  renderPlayerPrompt(input as SourcePlayerInput, promptIdentity, resuming);
 const runtimeSpec = {
-  label: 'CODE',
-  // DR-022 / slc/link.md: the declaration carries the value current at link
-  // time — a literal, never the loading engine's RUNTIME_ABI self-report,
-  // which would follow whatever engine loads the module and make the
-  // factory's skew check compare that engine with itself.
-  compat: { artifactSchema: 3, runtimeAbi: 1 },
-  snapshotOptions: snapshotCodeOptions,
-  entryEvent: {
-    type: 'START_CODE',
-    textField: 'callerInput',
-    // `startCoding` copies the entry text here, so the failure-state retry
-    // reads it back from the persisted machine snapshot and survives a
-    // continued session (DR-034).
-    contextField: 'callerInput',
+  composePlayerPrompt,
+  ...{
+  "label": "CODE",
+  "compat": {
+    "artifactSchema": 3,
+    "runtimeAbi": 1
   },
-  roleStates: {
-    runFirstPhase: {
-      role: 'coder',
-      label:
-        'Coder is running the first coding phase: a direct implementation, a new intent record, or an existing intent-record task.',
-    },
-    runIrTask: {
-      role: 'coder',
-      label: 'Coder is implementing exactly one unfinished intent-record task.',
+  "entryEvent": {
+    "type": "START_CODE",
+    "textField": "callerInput",
+    "contextField": "callerInput"
+  },
+  "bossEvents": [],
+  "roleStates": {
+    "firstPhase": {
+      "role": "coder",
+      "label": "Coder runs the first coding phase: a direct implementation, a new IR, or the next task of an existing IR."
     },
+    "irTaskPhase": {
+      "role": "coder",
+      "label": "Coder implements the identified IR's next unfinished task."
+    }
   },
-  outcomeAuthority: {
-    governedPlayerStates: {
-      runFirstPhase: {
-        directCommit: {
-          fields: {
-            coderOutput: 'presentation',
-            latestCommit: 'effect',
+  "outcomeAuthority": {
+    "governedPlayerStates": {
+      "firstPhase": {
+        "directCommit": {
+          "fields": {
+            "coderOutput": "presentation",
+            "latestCommit": "effect"
           },
-          repositoryDisposition: 'one-descendant-commit',
+          "repositoryDisposition": "one-descendant-commit"
         },
-        irCommit: {
-          fields: {
-            coderOutput: 'presentation',
-            latestCommit: 'effect',
-            irNumber: 'semantic',
+        "irCommit": {
+          "fields": {
+            "coderOutput": "presentation",
+            "latestCommit": "effect",
+            "irNumber": "semantic"
           },
-          repositoryDisposition: 'one-descendant-commit',
+          "repositoryDisposition": "one-descendant-commit"
         },
-        moreTasks: {
-          fields: {
-            coderOutput: 'presentation',
-            latestCommit: 'effect',
-            irNumber: 'semantic',
-            irTask: 'semantic',
+        "moreTasks": {
+          "fields": {
+            "coderOutput": "presentation",
+            "latestCommit": "effect",
+            "irNumber": "semantic",
+            "irTask": "semantic"
           },
-          repositoryDisposition: 'one-descendant-commit',
+          "repositoryDisposition": "one-descendant-commit"
         },
-        finalTask: {
-          fields: {
-            coderOutput: 'presentation',
-            latestCommit: 'effect',
-            irNumber: 'semantic',
-            irTask: 'semantic',
+        "finalTask": {
+          "fields": {
+            "coderOutput": "presentation",
+            "latestCommit": "effect",
+            "irNumber": "semantic",
+            "irTask": "semantic"
           },
-          repositoryDisposition: 'one-descendant-commit',
-        },
-        needsBossReply: {
-          fields: { question: 'presentation' },
-          repositoryDisposition: 'deferred',
+          "repositoryDisposition": "one-descendant-commit"
         },
+        "needsBossReply": {
+          "fields": {
+            "question": "presentation"
+          },
+          "repositoryDisposition": "deferred"
+        }
       },
-      runIrTask: {
-        moreTasks: {
-          fields: {
-            coderOutput: 'presentation',
-            latestCommit: 'effect',
-            irNumber: 'semantic',
-            irTask: 'semantic',
+      "irTaskPhase": {
+        "moreTasks": {
+          "fields": {
+            "coderOutput": "presentation",
+            "latestCommit": "effect",
+            "irNumber": "semantic",
+            "irTask": "semantic"
           },
-          repositoryDisposition: 'one-descendant-commit',
+          "repositoryDisposition": "one-descendant-commit"
         },
-        finalTask: {
-          fields: {
-            coderOutput: 'presentation',
-            latestCommit: 'effect',
-            irNumber: 'semantic',
-            irTask: 'semantic',
+        "finalTask": {
+          "fields": {
+            "coderOutput": "presentation",
+            "latestCommit": "effect",
+            "irNumber": "semantic",
+            "irTask": "semantic"
           },
-          repositoryDisposition: 'one-descendant-commit',
+          "repositoryDisposition": "one-descendant-commit"
         },
-        needsBossReply: {
-          fields: { question: 'presentation' },
-          repositoryDisposition: 'deferred',
-        },
-      },
-    },
+        "needsBossReply": {
+          "fields": {
+            "question": "presentation"
+          },
+          "repositoryDisposition": "deferred"
+        }
+      }
+    }
   },
-  composePlayerPrompt: (
-    input: PlaybookPlayerInput,
-    promptIdentity: XStatePromptIdentity,
-    resuming?: boolean,
-  ) => composePlayerPrompt(input as PlayerInput, promptIdentity, resuming),
+  "placeholderFields": {},
+  "transitionEventFields": [
+    "callerInput",
+    "runResults",
+    "targetId",
+    "answer",
+    "questionId"
+  ],
+  "controlContextFields": [
+    "phaseOutcome",
+    "irNumber",
+    "codeCommit",
+    "evaluatedRevision"
+  ]
+},
+  snapshotOptions: validateOptions,
+  machineInput: (options: PlaybookRuntimeOptions) => Object.fromEntries(
+    Object.entries(INPUT_MAPPING).filter(([, key]) => options[key as keyof PlaybookRuntimeOptions] !== undefined)
+      .map(([field, key]) => [field, options[key as keyof PlaybookRuntimeOptions]]),
+  ),
   verbatimPayloadFields: VERBATIM_PAYLOAD_FIELDS,
-  controlContextFields: ['phase'],
+  resumableStateIds: RESUMABLE_STATE_IDS,
   unfinishedFinalStateIds: UNFINISHED_FINAL_STATE_IDS,
-  transitionEventFields: ['callerInput', 'answer', 'questionId'],
-} satisfies XStatePlaybookRuntimeSpecV3<CodePlaybookOptions>;
+} satisfies XStatePlaybookRuntimeSpecV3<PlaybookRuntimeOptions>;
 
+export const _internal = {
+  composePlayerPrompt,
+  RESUMABLE_STATE_IDS,
+  UNFINISHED_FINAL_STATE_IDS,
+  VERBATIM_PAYLOAD_FIELDS,
+};
 const createPlaybookRuntime: XStatePlaybookRuntimeFactory<
-  XStatePlaybookRuntimeConstruction<
-    CodePlaybookOptions,
-    CodePlaybookHostCapabilities
-  >,
-  3
-> = createXStatePlaybookRuntime<
-  CodePlaybookOptions,
-  CodePlaybookHostCapabilities
->(
-  codingMachine,
-  runtimeSpec,
-);
-
+  XStatePlaybookRuntimeConstruction<PlaybookRuntimeOptions, PlaybookHostCapabilities>, 3
+> = createXStatePlaybookRuntime<PlaybookRuntimeOptions, PlaybookHostCapabilities>(machine, runtimeSpec);
 export default createPlaybookRuntime;

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

@@ -1,4 +1,5 @@
-import { type CodePlaybookHostCapabilities, type PlaybookRuntime } from './code.playbook.js';
+import { type PlaybookHostCapabilities, type PlaybookRuntime } from './code.playbook.js';
+import type { PlaybookHostConstructionCapabilities } from './playbook-captain.js';
 export interface PlaybookSummaryPolicy {
     stateCountLabels: Readonly<Record<string, string>>;
     copyPasteGuardNames: readonly string[];
@@ -24,7 +25,7 @@ export interface CodePlaybookRegistryEntry {
     concurrentRoleSets: readonly [];
     summaryPolicy: PlaybookSummaryPolicy;
     validateOptions(optionSlice: unknown): CodeOptions;
-    createRuntime(options: CodeOptions, hostCapabilities: CodePlaybookHostCapabilities): PlaybookRuntime;
+    createRuntime(options: CodeOptions, hostCapabilities: PlaybookHostConstructionCapabilities & PlaybookHostCapabilities): PlaybookRuntime;
 }
 export declare const codeStateCountLabels: {};
 export declare const codeCopyPasteGuardNames: readonly ["directCommit", "irCommit", "moreTasks", "finalTask"];

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

@@ -2,9 +2,10 @@
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 
 import createPlaybookRuntime, {
-  type CodePlaybookHostCapabilities,
+  type PlaybookHostCapabilities,
   type PlaybookRuntime,
 } from './code.playbook.js';
+import type { PlaybookHostConstructionCapabilities } from './playbook-captain.js';
 
 export interface PlaybookSummaryPolicy {
   stateCountLabels: Readonly<Record<string, string>>;
@@ -33,9 +34,12 @@ export interface CodePlaybookRegistryEntry {
   concurrentRoleSets: readonly [];
   summaryPolicy: PlaybookSummaryPolicy;
   validateOptions(optionSlice: unknown): CodeOptions;
+  // The linked module types live authority as opaque (link-materialization);
+  // the Captain entry binds its own construction capabilities here.
   createRuntime(
     options: CodeOptions,
-    hostCapabilities: CodePlaybookHostCapabilities,
+    hostCapabilities: PlaybookHostConstructionCapabilities &
+      PlaybookHostCapabilities,
   ): PlaybookRuntime;
 }
 

package/reference/sdlc/code.playbook/playbook-captain.d.ts

@@ -243,8 +243,50 @@ export interface PlaybookCaptainShell extends Captain {
      */
     submitShellAction?(actionId: string): string;
 }
+/**
+ * Whether words may stand outside a code span in a statement the shell says
+ * (CAPTAIN-9); the pure renderer accepts everything, and the shell passes its
+ * guard.
+ */
+type Speakable = (text: string) => boolean;
+/**
+ * What the shell recorded of a failure: an error, which may carry the cause
+ * the runtime decided (DR-063 §2), or that cause alone.
+ */
+interface RecordedFailure {
+    readonly message?: string;
+    readonly cause?: unknown;
+}
+type DescribePlaybook = (playbookId: string) => string;
+/**
+ * CAPTAIN-71: the one way a failure is put into words — `<Subject> failed:
+ * <reason>.` — `subject` naming what failed in the Boss's words and `failure`
+ * the error or cause the shell recorded.
+ */
+declare function failureStatement(subject: string, failure: RecordedFailure | undefined, describePlaybook?: DescribePlaybook, speakable?: Speakable): string;
+/**
+ * The three kinds of statement a report the shell says holds (CAPTAIN-69):
+ * a listed fact, a numbered unresolved-effect entry, and the `Failure:` line.
+ */
+type StatementKind = 'fact' | 'entry' | 'failure';
+/** A statement the report assembly weighs. */
+interface BossStatement {
+    readonly text: string;
+    /** Its kind, which decides what may drop it; a fact where absent. */
+    readonly kind?: StatementKind;
+    /** The reason a `Failure:` line states (CAPTAIN-67). */
+    readonly reason?: string;
+}
+/** The statements of `statements` that stay, as CAPTAIN-69 assembles them. */
+declare function bossReport(statements: readonly (string | BossStatement)[], reasons?: Iterable<string>): string[];
 export declare function assertPlaybookCaptainUnresolvedEffects(value: unknown): readonly PlaybookCaptainUnresolvedEffect[];
 /** Validate, detach, and freeze one untrusted shell snapshot. */
 export declare function assertPlaybookCaptainShellSnapshot(value: unknown): PlaybookCaptainShellSnapshot;
 export declare function createPlaybookCaptainShell(options: unknown, deps?: PlaybookCaptainDeps): PlaybookCaptainShell;
+export declare const _internal: {
+    failureStatement: typeof failureStatement;
+    bossReport: typeof bossReport;
+    RUNTIME_REASON_PHRASES: Readonly<Record<string, string>>;
+    LABELLED_RUNTIME_REASONS: readonly (readonly [RegExp, string])[];
+};
 export default createPlaybookCaptainShell;