@sublang/playbook 15.0.0 → 16.0.0

package/reference/sdlc/dev.playbook/dev.playbook.ts

@@ -1,245 +1,195 @@
 // 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:    ./dev.fsm.ts
-// Role metadata: Analyst→analyst (canonical local role)
-// Boss event:    deterministic START_DEV entry; exact Boss text becomes
-//                developmentRequest; pending Analyst questions retain
-//                BOSS_REPLY
-// Adjudication:  LLM judge for the one Analyst state; planningResult is
-//                carried verbatim
-// Nested calls:  literal code, decide, branch, and pr targets through the
-//                shared bridge; branch, revision, commit, and pull-request
-//                identities enter only from canonical child results
-// Compat:        artifact schema 3 / runtime ABI 1
-
+// Generated by slc/materialize-link.mjs; governed by the complete slc/link.md.
+// FSM: "./dev.fsm.js"; export: devMachine; strategies: shared defaults with labelled string relays and nested actors.
+import { devMachine as machine } from "./dev.fsm.js";
+import type { PlayerInput as SourcePlayerInput } from "./dev.fsm.js";
 import {
-  createXStatePlaybookRuntime,
-  composePlayerContinuation,
-  snapshotJsonValue,
+  createXStatePlaybookRuntime, snapshotJsonValue,
+  composePlayerContinuation, type XStatePromptIdentity,
   type PlaybookPlayerInput,
-  type XStatePlaybookRuntimeFactory,
   type XStatePlaybookRuntimeConstruction,
+  type XStatePlaybookRuntimeFactory,
   type XStatePlaybookRuntimeSpecV3,
 } from '@sublang/playbook/xstate-runtime';
-import {
-  devMachine,
-  type DevInput,
-  type PlayerInput,
-} from './dev.fsm.js';
-import type { PlaybookHostConstructionCapabilities } from '../code.playbook/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 DevPlaybookOptions = DevInput;
-export type DevPlaybookHostCapabilities =
-  PlaybookHostConstructionCapabilities &
-    XStatePlaybookRuntimeConstruction<DevPlaybookOptions, 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([
-  'planningResult',
+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([
+  "planAnalysis"
 ]);
 const UNFINISHED_FINAL_STATE_IDS: ReadonlySet<string> = new Set([
-  'reportedChildFailure',
+  "reportedChildFailure"
 ]);
-
-function snapshotDevOptions(value: unknown): DevPlaybookOptions {
-  const captured = snapshotJsonValue(value, 'DEV runtime options');
-  if (
-    captured === null ||
-    typeof captured !== 'object' ||
-    Array.isArray(captured)
-  ) {
-    throw new TypeError('DEV runtime options must be an object');
+const VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string> = new Set([
+  "planningResult"
+]);
+export function validateOptions(value: unknown): PlaybookRuntimeOptions {
+  const captured = snapshotJsonValue(value === undefined ? {} : value, "DEV runtime options");
+  if (captured === null || typeof captured !== 'object' || Array.isArray(captured)) {
+    throw new TypeError("DEV 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(`DEV runtime options.${key} is not declared`);
-    }
-    if (typeof option !== 'string') {
-      throw new TypeError(`DEV 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("DEV 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("DEV runtime options." + key + ' is required');
+    } else if (typeof fields[key] !== schema.type || (schema.type === 'number' && !Number.isFinite(fields[key]))) {
+      throw new TypeError("DEV runtime options." + key + ' must be a ' + schema.type);
     }
   }
-  return captured as unknown as DevPlaybookOptions;
+  return captured as unknown as PlaybookRuntimeOptions;
 }
-
-function placeholderField(token: string): string {
-  if (token === '#') return 'irNumber';
-  return token.replace(/-([A-Za-z0-9_$])/g, (_match, next: string) =>
-    next.toUpperCase(),
-  );
-}
-
-function quotedContinuation(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; DEV's
- * override additionally keeps a multiline value inside that quote and drops
- * the optional relays that have no value yet.
- */
-function composePlayerPrompt(input: PlayerInput, resuming = false): string {
-  const fields = input as unknown as Record<string, unknown>;
-  const template = input.prompt
-    .split('\n')
-    .filter(
-      (line) =>
-        !(
-          line === '> Prior discussion: <discussion-context>' &&
-          input.discussionContext.length === 0
-        ) &&
-        !(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 = 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>> = {};
+  const omitted = new Set<string>(["> Prior discussion: <discussion-context>","> 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('> ') ? quotedContinuation(value) : value;
-    },
-  );
+      return line.startsWith('> ') ? value.replace(/\r?\n/g, (ending: string) => ending + '> ') : value;
+    }) + (parts[index + 1] ?? '');
+  }
   return composePlayerContinuation(input, body, resuming);
 }
-
+const composePlayerPrompt = (input: PlaybookPlayerInput, promptIdentity: XStatePromptIdentity, resuming?: boolean): string =>
+  renderPlayerPrompt(input as SourcePlayerInput, promptIdentity, resuming);
 const runtimeSpec = {
-  label: 'DEV',
-  // 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: snapshotDevOptions,
-  entryEvent: {
-    type: 'START_DEV',
-    textField: 'developmentRequest',
-    // `startDev` 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: 'developmentRequest',
+  composePlayerPrompt,
+  ...{
+  "label": "DEV",
+  "compat": {
+    "artifactSchema": 3,
+    "runtimeAbi": 1
   },
-  roleStates: {
-    planAnalysis: {
-      role: 'analyst',
-      label: 'Analyst is choosing the development path.',
-    },
+  "entryEvent": {
+    "type": "START_DEV",
+    "textField": "developmentRequest",
+    "contextField": "developmentRequest"
   },
-  // DR-044: DEV owns no repository commit — every Analyst outcome is
-  // governed with the `unchanged` repository disposition, so planning that
-  // mutates the repository fails authority instead of being adopted.
-  outcomeAuthority: {
-    governedPlayerStates: {
-      planAnalysis: {
-        discussionComplete: {
-          fields: {},
-          repositoryDisposition: 'unchanged',
-        },
-        code: {
-          fields: { planningResult: 'presentation' },
-          repositoryDisposition: 'unchanged',
+  "bossEvents": [],
+  "roleStates": {
+    "planAnalysis": {
+      "role": "analyst",
+      "label": "Analyst chooses the development path in a short planning note."
+    }
+  },
+  "outcomeAuthority": {
+    "governedPlayerStates": {
+      "planAnalysis": {
+        "discussionComplete": {
+          "fields": {},
+          "repositoryDisposition": "unchanged"
         },
-        decideThenCode: {
-          fields: { planningResult: 'presentation' },
-          repositoryDisposition: 'unchanged',
+        "code": {
+          "fields": {
+            "planningResult": "presentation"
+          },
+          "repositoryDisposition": "unchanged"
         },
-        // DR-050: reading a GitHub issue during planning is not an effect, so
-        // the two pull-request outcomes stay `unchanged` like the plain ones.
-        codeViaPullRequest: {
-          fields: { planningResult: 'presentation' },
-          repositoryDisposition: 'unchanged',
+        "decideThenCode": {
+          "fields": {
+            "planningResult": "presentation"
+          },
+          "repositoryDisposition": "unchanged"
         },
-        decideThenCodeViaPullRequest: {
-          fields: { planningResult: 'presentation' },
-          repositoryDisposition: 'unchanged',
+        "codeViaPullRequest": {
+          "fields": {
+            "planningResult": "presentation"
+          },
+          "repositoryDisposition": "unchanged"
         },
-        needsBossReply: {
-          fields: { question: 'presentation' },
-          repositoryDisposition: 'unchanged',
+        "decideThenCodeViaPullRequest": {
+          "fields": {
+            "planningResult": "presentation"
+          },
+          "repositoryDisposition": "unchanged"
         },
-      },
-    },
+        "needsBossReply": {
+          "fields": {
+            "question": "presentation"
+          },
+          "repositoryDisposition": "unchanged"
+        }
+      }
+    }
   },
-  composePlayerPrompt: (input: PlaybookPlayerInput, _identity, resuming?: boolean) =>
-    composePlayerPrompt(input as PlayerInput, resuming),
+  "placeholderFields": {},
+  "transitionEventFields": [
+    "developmentRequest",
+    "answer",
+    "questionId"
+  ],
+  "controlContextFields": []
+},
+  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: [],
+  resumableStateIds: RESUMABLE_STATE_IDS,
   unfinishedFinalStateIds: UNFINISHED_FINAL_STATE_IDS,
-  transitionEventFields: ['developmentRequest', 'answer', 'questionId'],
-} satisfies XStatePlaybookRuntimeSpecV3<DevPlaybookOptions>;
+} satisfies XStatePlaybookRuntimeSpecV3<PlaybookRuntimeOptions>;
 
 export const _internal = {
-  composePlayerPrompt: runtimeSpec.composePlayerPrompt,
-  VERBATIM_PAYLOAD_FIELDS,
+  composePlayerPrompt,
+  RESUMABLE_STATE_IDS,
   UNFINISHED_FINAL_STATE_IDS,
+  VERBATIM_PAYLOAD_FIELDS,
 };
-
 const createPlaybookRuntime: XStatePlaybookRuntimeFactory<
-  XStatePlaybookRuntimeConstruction<
-    DevPlaybookOptions,
-    DevPlaybookHostCapabilities
-  >,
-  3
-> = createXStatePlaybookRuntime<
-  DevPlaybookOptions,
-  DevPlaybookHostCapabilities
->(devMachine, runtimeSpec);
-
+  XStatePlaybookRuntimeConstruction<PlaybookRuntimeOptions, PlaybookHostCapabilities>, 3
+> = createXStatePlaybookRuntime<PlaybookRuntimeOptions, PlaybookHostCapabilities>(machine, runtimeSpec);
 export default createPlaybookRuntime;

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

@@ -1,4 +1,5 @@
-import { type DevPlaybookHostCapabilities, type PlaybookRuntime } from './dev.playbook.js';
+import type { PlaybookHostConstructionCapabilities } from '../code.playbook/playbook-captain.js';
+import { type PlaybookHostCapabilities, type PlaybookRuntime } from './dev.playbook.js';
 export interface PlaybookSummaryPolicy {
     stateCountLabels: Readonly<Record<string, string>>;
     copyPasteGuardNames: readonly string[];
@@ -24,7 +25,7 @@ export interface DevPlaybookRegistryEntry {
     concurrentRoleSets: readonly [];
     summaryPolicy: PlaybookSummaryPolicy;
     validateOptions(optionSlice: unknown): DevOptions;
-    createRuntime(options: DevOptions, hostCapabilities: DevPlaybookHostCapabilities): PlaybookRuntime;
+    createRuntime(options: DevOptions, hostCapabilities: PlaybookHostConstructionCapabilities & PlaybookHostCapabilities): PlaybookRuntime;
 }
 export declare const devStateCountLabels: {
     readonly planAnalysis: "planning round";

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

@@ -1,8 +1,9 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 
+import type { PlaybookHostConstructionCapabilities } from '../code.playbook/playbook-captain.js';
 import createPlaybookRuntime, {
-  type DevPlaybookHostCapabilities,
+  type PlaybookHostCapabilities,
   type PlaybookRuntime,
 } from './dev.playbook.js';
 
@@ -33,9 +34,12 @@ export interface DevPlaybookRegistryEntry {
   concurrentRoleSets: readonly [];
   summaryPolicy: PlaybookSummaryPolicy;
   validateOptions(optionSlice: unknown): DevOptions;
+  // The linked module types live authority as opaque (link-materialization);
+  // the Captain entry binds its own construction capabilities here.
   createRuntime(
     options: DevOptions,
-    hostCapabilities: DevPlaybookHostCapabilities,
+    hostCapabilities: PlaybookHostConstructionCapabilities &
+      PlaybookHostCapabilities,
   ): PlaybookRuntime;
 }