@sublang/playbook 15.0.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;
 }
 

package/reference/sdlc/code.playbook/bin/repository-effects.js

@@ -520,8 +520,6 @@ function projectionText(projection) {
   return JSON.stringify(projection);
 }
 
-const MISSING_CONTENT_IDENTITY = Object.freeze({ kind: 'missing' });
-
 function hasPath(projection, path) {
   return Object.prototype.hasOwnProperty.call(projection, path);
 }
@@ -555,9 +553,9 @@ function sameTreeEntry(left, right) {
   return left.mode === right.mode && left.oid === right.oid;
 }
 
-// The baseline recorded nothing at the path: a deleted worktree entry, or a
+// The entry records nothing at the path: a deleted worktree entry, or a
 // staged deletion whose index holds no object.
-function baselineEntryIsDeletion(entry) {
+function entryIsDeletion(entry) {
   return entry.worktree === undefined
     ? entry.indexMode === '000000'
     : entry.worktree.kind === 'missing';
@@ -615,14 +613,57 @@ function sameContentIdentity(left, right) {
   );
 }
 
+// A worktree deletion loses the Boss's content only when neither the after
+// index nor the after HEAD tree holds it; content the after HEAD cannot
+// produce fails closed as lost.
+async function deletionRetainsContent(baseline, after, path, entry, afterEntry) {
+  try {
+    const baselineIdentity = await baselineContentIdentity(after.worktree, entry);
+    if (
+      afterEntry.kind === 'ordinary' &&
+      afterEntry.indexMode !== undefined &&
+      afterEntry.indexMode !== '000000'
+    ) {
+      const indexIdentity = await blobContentIdentity(
+        after.worktree,
+        afterEntry.indexMode,
+        afterEntry.indexOid,
+      );
+      if (sameContentIdentity(baselineIdentity, indexIdentity)) return true;
+    }
+    if (baseline.head === after.head) return false;
+    const treeEntry = await afterTreeEntry(after.worktree, after.head, path);
+    if (treeEntry === undefined || treeEntry.mode === '160000') return false;
+    const treeIdentity = await blobContentIdentity(
+      after.worktree,
+      treeEntry.mode,
+      treeEntry.oid,
+    );
+    return sameContentIdentity(baselineIdentity, treeIdentity);
+  } catch {
+    return false;
+  }
+}
+
 // DR-062 §1: the fate of one baseline projection entry at the end of a
 // governed call — `preserved`, `altered-uncommitted`, `altered-committed`,
-// `absorbed`, or `lost`.
+// `absorbed`, or `lost`. Loss is decided before alteration: a kind that
+// admits no content matching, a worktree deletion whose content survives in
+// neither the index nor the new HEAD, and a commit that dropped the path all
+// leave the Boss's content nowhere.
 async function baselineEntryFate(baseline, after, path, entry) {
   if (hasPath(after.projection, path)) {
-    return JSON.stringify(after.projection[path]) === JSON.stringify(entry)
-      ? 'preserved'
-      : 'altered-uncommitted';
+    const afterEntry = after.projection[path];
+    if (JSON.stringify(afterEntry) === JSON.stringify(entry)) {
+      return 'preserved';
+    }
+    if (nonComparableBaselineEntry(entry)) return 'lost';
+    if (entryIsDeletion(afterEntry) && !entryIsDeletion(entry)) {
+      return (await deletionRetainsContent(baseline, after, path, entry, afterEntry))
+        ? 'altered-uncommitted'
+        : 'lost';
+    }
+    return 'altered-uncommitted';
   }
   // The entry left the working tree, so only a commit this call made can hold
   // the Boss's content; a call that moved no HEAD made none.
@@ -635,15 +676,15 @@ async function baselineEntryFate(baseline, after, path, entry) {
       // carried no change of the Boss's and his content is nowhere.
       return 'lost';
     }
-    if (baselineEntryIsDeletion(entry)) {
+    if (entryIsDeletion(entry)) {
       return treeEntry === undefined ? 'absorbed' : 'lost';
     }
-    if (treeEntry?.mode === '160000') return 'lost';
+    // A commit that dropped the path, or replaced it with a gitlink, carries
+    // no content of the Boss's to compare.
+    if (treeEntry === undefined || treeEntry.mode === '160000') return 'lost';
     const [baselineIdentity, treeIdentity] = await Promise.all([
       baselineContentIdentity(after.worktree, entry),
-      treeEntry === undefined
-        ? MISSING_CONTENT_IDENTITY
-        : blobContentIdentity(after.worktree, treeEntry.mode, treeEntry.oid),
+      blobContentIdentity(after.worktree, treeEntry.mode, treeEntry.oid),
     ]);
     return sameContentIdentity(baselineIdentity, treeIdentity)
       ? 'absorbed'