@sublang/playbook 15.1.0 → 16.0.0

package/reference/sdlc/branch.playbook/branch.playbook.ts

@@ -1,217 +1,174 @@
 // 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:    ./branch.fsm.ts
-// Role metadata: Coder→coder (canonical local role)
-// Boss event:    deterministic START_BRANCH entry; exact Boss text becomes
-//                callerInput; pending Coder questions retain BOSS_REPLY
-// Adjudication:  LLM judge for the one Coder state; coderOutput is carried
-//                verbatim; baseRevision is receipt-owned effect evidence —
-//                the unchanged receipt's observed HEAD — never taken from
-//                Coder's prose
-// Compat:        artifact schema 3 / runtime ABI 1
-
+// Generated by slc/materialize-link.mjs; governed by the complete slc/link.md.
+// FSM: "./branch.fsm.js"; export: branchMachine; strategies: shared defaults with labelled string relays and nested actors.
+import { branchMachine as machine } from "./branch.fsm.js";
+import type { PlayerInput as SourcePlayerInput } from "./branch.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 {
-  branchMachine,
-  type BranchInput,
-  type PlayerInput,
-} from './branch.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,
-};
+  PlaybookControlReceipt,
+  PlaybookControlView,
+} from '@sublang/playbook/runtime';
 
-export type BranchPlaybookOptions = BranchInput;
-export type BranchPlaybookHostCapabilities =
-  PlaybookHostConstructionCapabilities &
-    XStatePlaybookRuntimeConstruction<BranchPlaybookOptions, object>['hostCapabilities'];
+export interface PlaybookRuntimeOptions {
 
-const PLACEHOLDER = /<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>/g;
+}
+export type PlaybookHostCapabilities = XStatePlaybookRuntimeConstruction<
+  PlaybookRuntimeOptions, { readonly authority: object }
+>['hostCapabilities'];
 
+const OPTION_SCHEMA = {} as const;
+const INPUT_MAPPING = {} as const;
+const RESUMABLE_STATE_IDS: ReadonlySet<string> = new Set([
+  "createBranch"
+]);
+const UNFINISHED_FINAL_STATE_IDS: ReadonlySet<string> = new Set([
+  "refused"
+]);
 const VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string> = new Set([
-  'coderOutput',
+  "coderOutput"
 ]);
-const UNFINISHED_FINAL_STATE_IDS: ReadonlySet<string> = new Set(['refused']);
-
-function snapshotBranchOptions(value: unknown): BranchPlaybookOptions {
-  const captured = snapshotJsonValue(value, 'BRANCH runtime options');
-  if (
-    captured === null ||
-    typeof captured !== 'object' ||
-    Array.isArray(captured)
-  ) {
-    throw new TypeError('BRANCH runtime options must be an object');
+export function validateOptions(value: unknown): PlaybookRuntimeOptions {
+  const captured = snapshotJsonValue(value === undefined ? {} : value, "BRANCH runtime options");
+  if (captured === null || typeof captured !== 'object' || Array.isArray(captured)) {
+    throw new TypeError("BRANCH runtime options must be an object");
   }
-  const record = captured as Readonly<Record<string, JsonValue>>;
-  for (const key of Object.keys(record)) {
-    throw new TypeError(`BRANCH runtime options.${key} is not declared`);
+  const fields = captured as Readonly<Record<string, unknown>>;
+  for (const key of Object.keys(captured)) {
+    if (!Object.hasOwn(OPTION_SCHEMA, key)) throw new TypeError("BRANCH runtime options." + key + ' is not declared');
   }
-  return captured as unknown as BranchPlaybookOptions;
-}
-
-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> ');
+  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("BRANCH runtime options." + key + ' is required');
+    } else if (typeof fields[key] !== schema.type || (schema.type === 'number' && !Number.isFinite(fields[key]))) {
+      throw new TypeError("BRANCH runtime options." + key + ' must be a ' + schema.type);
+    }
+  }
+  return captured as unknown as PlaybookRuntimeOptions;
 }
-
-/**
- * Preserve authored Markdown quote markers around every line of relayed
- * runtime text. The generic composer preserves the marker itself; BRANCH's
- * override additionally keeps a multiline caller input inside that quote.
- */
-function composePlayerPrompt(input: PlayerInput, resuming = false): string {
-  const fields = input as unknown as Record<string, unknown>;
-  const body = input.prompt.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>([]);
+  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);
 }
-
-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: 'BRANCH',
-  // 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: snapshotBranchOptions,
-  entryEvent: {
-    type: 'START_BRANCH',
-    textField: 'callerInput',
-    // `startBranch` 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": "BRANCH",
+  "compat": {
+    "artifactSchema": 3,
+    "runtimeAbi": 1
+  },
+  "entryEvent": {
+    "type": "START_BRANCH",
+    "textField": "callerInput",
+    "contextField": "callerInput"
   },
-  roleStates: {
-    createBranch: {
-      role: 'coder',
-      label:
-        'Coder is reading the named issue and creating and checking out a new branch at the current commit.',
-    },
+  "bossEvents": [],
+  "roleStates": {
+    "createBranch": {
+      "role": "coder",
+      "label": "Coder is identifying the request's issue and creating and checking out a new branch at the current commit."
+    }
   },
-  // DR-050: BRANCH owns no repository commit — every Coder outcome, including
-  // the Boss question for an ambiguous request, is governed with the
-  // `unchanged` repository disposition, because a new branch at the current
-  // commit changes neither HEAD's OID nor the worktree projection.
-  outcomeAuthority: {
-    governedPlayerStates: {
-      createBranch: {
-        branched: {
-          fields: {
-            branch: 'semantic',
-            // DR-045: the unchanged receipt observes the commit the branch
-            // was created from as HEAD; the reconciler injects it here.
-            baseRevision: 'effect',
-            issueSummary: 'semantic',
+  "outcomeAuthority": {
+    "governedPlayerStates": {
+      "createBranch": {
+        "branched": {
+          "fields": {
+            "branch": "semantic",
+            "baseRevision": "effect",
+            "issueSummary": "semantic"
           },
-          repositoryDisposition: 'unchanged',
+          "repositoryDisposition": "unchanged"
         },
-        refused: {
-          fields: { coderOutput: 'presentation' },
-          repositoryDisposition: 'unchanged',
-        },
-        needsBossReply: {
-          fields: { question: 'presentation' },
-          repositoryDisposition: 'unchanged',
+        "refused": {
+          "fields": {
+            "coderOutput": "presentation"
+          },
+          "repositoryDisposition": "unchanged"
         },
-      },
-    },
+        "needsBossReply": {
+          "fields": {
+            "question": "presentation"
+          },
+          "repositoryDisposition": "unchanged"
+        }
+      }
+    }
   },
-  composePlayerPrompt: (input: PlaybookPlayerInput, _identity, resuming) =>
-    composePlayerPrompt(input as PlayerInput, resuming),
+  "placeholderFields": {},
+  "transitionEventFields": [
+    "callerInput",
+    "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: ['callerInput', 'answer', 'questionId'],
-} satisfies XStatePlaybookRuntimeSpecV3<BranchPlaybookOptions>;
+} satisfies XStatePlaybookRuntimeSpecV3<PlaybookRuntimeOptions>;
 
+export const _internal = {
+  composePlayerPrompt,
+  RESUMABLE_STATE_IDS,
+  UNFINISHED_FINAL_STATE_IDS,
+  VERBATIM_PAYLOAD_FIELDS,
+};
 const createPlaybookRuntime: XStatePlaybookRuntimeFactory<
-  XStatePlaybookRuntimeConstruction<
-    BranchPlaybookOptions,
-    BranchPlaybookHostCapabilities
-  >,
-  3
-> = createXStatePlaybookRuntime<
-  BranchPlaybookOptions,
-  BranchPlaybookHostCapabilities
->(branchMachine, runtimeSpec);
-
+  XStatePlaybookRuntimeConstruction<PlaybookRuntimeOptions, PlaybookHostCapabilities>, 3
+> = createXStatePlaybookRuntime<PlaybookRuntimeOptions, PlaybookHostCapabilities>(machine, runtimeSpec);
 export default createPlaybookRuntime;

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

@@ -1,4 +1,5 @@
-import { type BranchPlaybookHostCapabilities, type PlaybookRuntime } from './branch.playbook.js';
+import { type PlaybookHostCapabilities, type PlaybookRuntime } from './branch.playbook.js';
+import type { PlaybookHostConstructionCapabilities } from '../code.playbook/playbook-captain.js';
 export interface PlaybookSummaryPolicy {
     stateCountLabels: Readonly<Record<string, string>>;
     copyPasteGuardNames: readonly string[];
@@ -24,7 +25,7 @@ export interface BranchPlaybookRegistryEntry {
     concurrentRoleSets: readonly [];
     summaryPolicy: PlaybookSummaryPolicy;
     validateOptions(optionSlice: unknown): BranchOptions;
-    createRuntime(options: BranchOptions, hostCapabilities: BranchPlaybookHostCapabilities): PlaybookRuntime;
+    createRuntime(options: BranchOptions, hostCapabilities: PlaybookHostConstructionCapabilities & PlaybookHostCapabilities): PlaybookRuntime;
 }
 export declare const branchStateCountLabels: {
     readonly createBranch: "branching round";

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

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