@sublang/playbook 15.1.0 → 16.0.0

package/reference/sdlc/review.playbook/review.playbook.ts

@@ -1,288 +1,248 @@
 // 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:    ./review.fsm.ts
-// Role metadata: Coder→coder, Reviewer→reviewer (canonical local roles)
-// Boss event:    deterministic START_REVIEW entry; exact Boss text becomes
-//                callerInput; pending player questions retain BOSS_REPLY
-// Adjudication:  LLM judge per state; coderOutput and reviewerOutput are
-//                carried verbatim; latestCommit is receipt-owned effect
-//                evidence, never taken from either player's prose
-// Compat:        artifact schema 3 / runtime ABI 1
-
+// Generated by slc/materialize-link.mjs; governed by the complete slc/link.md.
+// FSM: "./review.fsm.js"; export: reviewMachine; strategies: shared defaults with labelled string relays and nested actors.
+import { reviewMachine as machine } from "./review.fsm.js";
+import type { PlayerInput as SourcePlayerInput } from "./review.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 {
-  reviewMachine,
-  type PlayerInput,
-  type ReviewInput,
-} from './review.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 ReviewPlaybookOptions = ReviewInput;
-export type ReviewPlaybookHostCapabilities =
-  PlaybookHostConstructionCapabilities &
-    XStatePlaybookRuntimeConstruction<ReviewPlaybookOptions, 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([
+  "firstReview",
+  "fixFindings",
+  "reviewAfterFix",
+  "reviewAfterRejection"
+]);
+const UNFINISHED_FINAL_STATE_IDS: ReadonlySet<string> = new Set([]);
 const VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string> = new Set([
-  'reviewerOutput',
-  'coderOutput',
+  "reviewerOutput",
+  "coderOutput"
 ]);
-const UNFINISHED_FINAL_STATE_IDS: ReadonlySet<string> = new Set();
-
-function snapshotReviewOptions(value: unknown): ReviewPlaybookOptions {
-  const captured = snapshotJsonValue(value, 'REVIEW runtime options');
-  if (
-    captured === null ||
-    typeof captured !== 'object' ||
-    Array.isArray(captured)
-  ) {
-    throw new TypeError('REVIEW runtime options must be an object');
+export function validateOptions(value: unknown): PlaybookRuntimeOptions {
+  const captured = snapshotJsonValue(value === undefined ? {} : value, "REVIEW runtime options");
+  if (captured === null || typeof captured !== 'object' || Array.isArray(captured)) {
+    throw new TypeError("REVIEW runtime options must be an object");
   }
-  const record = captured as Readonly<Record<string, JsonValue>>;
-  for (const key of Object.keys(record)) {
-    throw new TypeError(`REVIEW 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("REVIEW runtime options." + key + ' is not declared');
   }
-  return captured as unknown as ReviewPlaybookOptions;
-}
-
-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("REVIEW runtime options." + key + ' is required');
+    } else if (typeof fields[key] !== schema.type || (schema.type === 'number' && !Number.isFinite(fields[key]))) {
+      throw new TypeError("REVIEW runtime options." + key + ' must be a ' + schema.type);
+    }
+  }
+  return captured as unknown as PlaybookRuntimeOptions;
 }
-
-/** Keep every line of a relayed runtime value inside its authored quote. */
-function composePlayerPrompt(
-  input: PlayerInput,
-  promptIdentity: XStatePromptIdentity,
-  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 =
-        token === 'coder-llm'
-          ? promptIdentity('coder')
-          : token === 'reviewer-llm'
-            ? promptIdentity('reviewer')
-            : 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","reviewer-llm":"reviewer"};
+  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;
-      return source.slice(lineStart, offset).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: 'REVIEW',
-  // 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: snapshotReviewOptions,
-  entryEvent: {
-    type: 'START_REVIEW',
-    textField: 'callerInput',
-    // `copyStartInput` 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": "REVIEW",
+  "compat": {
+    "artifactSchema": 3,
+    "runtimeAbi": 1
   },
-  roleStates: {
-    reviewInitial: {
-      role: 'reviewer',
-      label:
-        "REVIEW-1: Reviewer reviews the caller's review scope against the original intent.",
-    },
-    addressFindings: {
-      role: 'coder',
-      label: 'REVIEW-2: Coder accepts or rejects every current review finding.',
+  "entryEvent": {
+    "type": "START_REVIEW",
+    "textField": "callerInput",
+    "contextField": "callerInput"
+  },
+  "bossEvents": [],
+  "roleStates": {
+    "firstReview": {
+      "role": "reviewer",
+      "label": "Reviewer runs the first review round over the review scope."
     },
-    reviewAfterCommit: {
-      role: 'reviewer',
-      label:
-        'REVIEW-3: Reviewer reviews the cumulative committed state after a review-fix commit.',
+    "fixFindings": {
+      "role": "coder",
+      "label": "Coder accepts or rejects each of Reviewer's findings and commits any accepted fixes."
     },
-    reviewAfterRebuttal: {
-      role: 'reviewer',
-      label:
-        'REVIEW-4: Reviewer adjudicates an all-rejected Coder disposition.',
+    "reviewAfterFix": {
+      "role": "reviewer",
+      "label": "Reviewer runs the next review round over the cumulative committed state after a review-fix commit."
     },
+    "reviewAfterRejection": {
+      "role": "reviewer",
+      "label": "Reviewer runs the next review round after Coder rejected every finding without a commit."
+    }
   },
-  outcomeAuthority: {
-    governedPlayerStates: {
-      reviewInitial: {
-        hasFindings: {
-          fields: { reviewerOutput: 'presentation' },
-          repositoryDisposition: 'unchanged',
-        },
-        noFindings: {
-          // DR-045: the clean round's unchanged receipt observes the exact
-          // evaluated revision as HEAD; the reconciler injects it here.
-          fields: { evaluatedRevision: 'effect' },
-          repositoryDisposition: 'unchanged',
+  "outcomeAuthority": {
+    "governedPlayerStates": {
+      "firstReview": {
+        "hasFindings": {
+          "fields": {
+            "reviewerOutput": "presentation"
+          },
+          "repositoryDisposition": "unchanged"
         },
-        needsBossReply: {
-          fields: { question: 'presentation' },
-          repositoryDisposition: 'unchanged',
+        "noFindings": {
+          "fields": {
+            "evaluatedRevision": "effect"
+          },
+          "repositoryDisposition": "unchanged"
         },
+        "needsBossReply": {
+          "fields": {
+            "question": "presentation"
+          },
+          "repositoryDisposition": "unchanged"
+        }
       },
-      addressFindings: {
-        committed: {
-          fields: {
-            coderOutput: 'presentation',
-            latestCommit: 'effect',
+      "fixFindings": {
+        "committed": {
+          "fields": {
+            "coderOutput": "presentation",
+            "latestCommit": "effect"
           },
-          repositoryDisposition: 'one-descendant-commit',
-        },
-        rejectedAll: {
-          fields: { coderOutput: 'presentation' },
-          repositoryDisposition: 'unchanged',
+          "repositoryDisposition": "one-descendant-commit"
         },
-        needsBossReply: {
-          fields: { question: 'presentation' },
-          repositoryDisposition: 'deferred',
+        "rejectedAll": {
+          "fields": {
+            "coderOutput": "presentation"
+          },
+          "repositoryDisposition": "unchanged"
         },
+        "needsBossReply": {
+          "fields": {
+            "question": "presentation"
+          },
+          "repositoryDisposition": "deferred"
+        }
       },
-      reviewAfterCommit: {
-        hasFindings: {
-          fields: { reviewerOutput: 'presentation' },
-          repositoryDisposition: 'unchanged',
-        },
-        noFindings: {
-          // DR-045: the clean round's unchanged receipt observes the exact
-          // evaluated revision as HEAD; the reconciler injects it here.
-          fields: { evaluatedRevision: 'effect' },
-          repositoryDisposition: 'unchanged',
+      "reviewAfterFix": {
+        "hasFindings": {
+          "fields": {
+            "reviewerOutput": "presentation"
+          },
+          "repositoryDisposition": "unchanged"
         },
-        needsBossReply: {
-          fields: { question: 'presentation' },
-          repositoryDisposition: 'unchanged',
+        "noFindings": {
+          "fields": {
+            "evaluatedRevision": "effect"
+          },
+          "repositoryDisposition": "unchanged"
         },
+        "needsBossReply": {
+          "fields": {
+            "question": "presentation"
+          },
+          "repositoryDisposition": "unchanged"
+        }
       },
-      reviewAfterRebuttal: {
-        hasFindings: {
-          fields: { reviewerOutput: 'presentation' },
-          repositoryDisposition: 'unchanged',
-        },
-        noFindings: {
-          // DR-045: the clean round's unchanged receipt observes the exact
-          // evaluated revision as HEAD; the reconciler injects it here.
-          fields: { evaluatedRevision: 'effect' },
-          repositoryDisposition: 'unchanged',
+      "reviewAfterRejection": {
+        "hasFindings": {
+          "fields": {
+            "reviewerOutput": "presentation"
+          },
+          "repositoryDisposition": "unchanged"
         },
-        needsBossReply: {
-          fields: { question: 'presentation' },
-          repositoryDisposition: 'unchanged',
+        "noFindings": {
+          "fields": {
+            "evaluatedRevision": "effect"
+          },
+          "repositoryDisposition": "unchanged"
         },
-      },
-    },
+        "needsBossReply": {
+          "fields": {
+            "question": "presentation"
+          },
+          "repositoryDisposition": "unchanged"
+        }
+      }
+    }
   },
-  composePlayerPrompt: (
-    input: PlaybookPlayerInput,
-    promptIdentity: XStatePromptIdentity,
-    resuming?: boolean,
-  ) => composePlayerPrompt(input as PlayerInput, promptIdentity, resuming),
+  "placeholderFields": {},
+  "transitionEventFields": [
+    "callerInput",
+    "targetId",
+    "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',
-    'bossIntent',
-    'targetId',
-    'answer',
-    'questionId',
-  ],
-} satisfies XStatePlaybookRuntimeSpecV3<ReviewPlaybookOptions>;
+} satisfies XStatePlaybookRuntimeSpecV3<PlaybookRuntimeOptions>;
 
+export const _internal = {
+  composePlayerPrompt,
+  RESUMABLE_STATE_IDS,
+  UNFINISHED_FINAL_STATE_IDS,
+  VERBATIM_PAYLOAD_FIELDS,
+};
 const createPlaybookRuntime: XStatePlaybookRuntimeFactory<
-  XStatePlaybookRuntimeConstruction<
-    ReviewPlaybookOptions,
-    ReviewPlaybookHostCapabilities
-  >,
-  3
-> = createXStatePlaybookRuntime<
-  ReviewPlaybookOptions,
-  ReviewPlaybookHostCapabilities
->(reviewMachine, runtimeSpec);
-
+  XStatePlaybookRuntimeConstruction<PlaybookRuntimeOptions, PlaybookHostCapabilities>, 3
+> = createXStatePlaybookRuntime<PlaybookRuntimeOptions, PlaybookHostCapabilities>(machine, runtimeSpec);
 export default createPlaybookRuntime;

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

@@ -1,4 +1,5 @@
-import { type ReviewPlaybookHostCapabilities, type PlaybookRuntime } from './review.playbook.js';
+import { type PlaybookHostCapabilities, type PlaybookRuntime } from './review.playbook.js';
+import type { PlaybookHostConstructionCapabilities } from '../code.playbook/playbook-captain.js';
 export interface PlaybookSummaryPolicy {
     stateCountLabels: Readonly<Record<string, string>>;
     copyPasteGuardNames: readonly string[];
@@ -24,12 +25,12 @@ export interface ReviewPlaybookRegistryEntry {
     concurrentRoleSets: readonly [];
     summaryPolicy: PlaybookSummaryPolicy;
     validateOptions(optionSlice: unknown): ReviewOptions;
-    createRuntime(options: ReviewOptions, hostCapabilities: ReviewPlaybookHostCapabilities): PlaybookRuntime;
+    createRuntime(options: ReviewOptions, hostCapabilities: PlaybookHostConstructionCapabilities & PlaybookHostCapabilities): PlaybookRuntime;
 }
 export declare const reviewStateCountLabels: {
-    readonly reviewInitial: "review round";
-    readonly reviewAfterCommit: "review round";
-    readonly reviewAfterRebuttal: "rebuttal";
+    readonly firstReview: "review round";
+    readonly reviewAfterFix: "review round";
+    readonly reviewAfterRejection: "rebuttal";
 };
 export declare const reviewCopyPasteGuardNames: readonly ["hasFindings", "committed", "rejectedAll"];
 export declare function reviewSavedCountsLine(counts: {

package/reference/sdlc/review.playbook/review.registry.js

@@ -2,9 +2,9 @@
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 import createPlaybookRuntime from './review.playbook.js';
 export const reviewStateCountLabels = {
-    reviewInitial: 'review round',
-    reviewAfterCommit: 'review round',
-    reviewAfterRebuttal: 'rebuttal',
+    firstReview: 'review round',
+    reviewAfterFix: 'review round',
+    reviewAfterRejection: 'rebuttal',
 };
 export const reviewCopyPasteGuardNames = [
     'hasFindings',

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

@@ -2,9 +2,10 @@
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 
 import createPlaybookRuntime, {
-  type ReviewPlaybookHostCapabilities,
+  type PlaybookHostCapabilities,
   type PlaybookRuntime,
 } from './review.playbook.js';
+import type { PlaybookHostConstructionCapabilities } from '../code.playbook/playbook-captain.js';
 
 export interface PlaybookSummaryPolicy {
   stateCountLabels: Readonly<Record<string, string>>;
@@ -33,16 +34,19 @@ export interface ReviewPlaybookRegistryEntry {
   concurrentRoleSets: readonly [];
   summaryPolicy: PlaybookSummaryPolicy;
   validateOptions(optionSlice: unknown): ReviewOptions;
+  // The linked module types live authority as opaque (link-materialization);
+  // the Captain entry binds its own construction capabilities here.
   createRuntime(
     options: ReviewOptions,
-    hostCapabilities: ReviewPlaybookHostCapabilities,
+    hostCapabilities: PlaybookHostConstructionCapabilities &
+      PlaybookHostCapabilities,
   ): PlaybookRuntime;
 }
 
 export const reviewStateCountLabels = {
-  reviewInitial: 'review round',
-  reviewAfterCommit: 'review round',
-  reviewAfterRebuttal: 'rebuttal',
+  firstReview: 'review round',
+  reviewAfterFix: 'review round',
+  reviewAfterRejection: 'rebuttal',
 } as const;
 
 export const reviewCopyPasteGuardNames = [