@sublang/playbook 8.0.0 → 10.0.0

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

@@ -8,21 +8,23 @@
 //                callerInput; pending Coder questions retain BOSS_REPLY
 // Adjudication:  LLM judge per player state; coderOutput is carried verbatim
 // Nested call:   literal review target through the shared bridge
-// Compat:        artifact schema 2 / runtime ABI 1
+// Compat:        artifact schema 3 / runtime ABI 1
 
 import {
-  RUNTIME_ABI,
   createXStatePlaybookRuntime,
   snapshotJsonValue,
   type PlaybookPlayerInput,
+  type XStatePlaybookRuntimeFactory,
+  type XStatePlaybookRuntimeConstruction,
   type XStatePromptIdentity,
-  type XStatePlaybookRuntimeSpec,
+  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,
@@ -76,6 +78,9 @@ export type {
 };
 
 export type CodePlaybookOptions = CodingInput;
+export type CodePlaybookHostCapabilities =
+  PlaybookHostConstructionCapabilities &
+    XStatePlaybookRuntimeConstruction<CodePlaybookOptions, object>['hostCapabilities'];
 
 const OPTION_KEYS = new Set(['runResults']);
 const PLACEHOLDER = /<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>/g;
@@ -85,6 +90,9 @@ const CONTINUATION_PREAMBLE =
 const VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string> = new Set([
   'coderOutput',
 ]);
+const UNFINISHED_FINAL_STATE_IDS: ReadonlySet<string> = new Set([
+  'reportedReviewFailure',
+]);
 
 function snapshotCodeOptions(value: unknown): CodePlaybookOptions {
   const captured = snapshotJsonValue(value, 'CODE runtime options');
@@ -164,13 +172,25 @@ function composePlayerPrompt(
 export const _internal = {
   composePlayerPrompt,
   VERBATIM_PAYLOAD_FIELDS,
+  UNFINISHED_FINAL_STATE_IDS,
 };
 
 const runtimeSpec = {
   label: 'CODE',
-  compat: { artifactSchema: 2, runtimeAbi: RUNTIME_ABI },
+  // 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' },
+  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',
+  },
   roleStates: {
     runFirstPhase: {
       role: 'coder',
@@ -182,16 +202,75 @@ const runtimeSpec = {
       label: 'Coder is implementing exactly one unfinished intent-record task.',
     },
   },
+  outcomeAuthority: {
+    governedPlayerStates: {
+      runFirstPhase: {
+        directCommit: {
+          fields: {
+            coderOutput: 'presentation',
+            latestCommit: 'effect',
+          },
+          repositoryDisposition: 'one-descendant-commit',
+        },
+        irCommit: {
+          fields: {
+            coderOutput: 'presentation',
+            latestCommit: 'effect',
+            irNumber: 'semantic',
+            irTask: 'semantic',
+          },
+          repositoryDisposition: 'one-descendant-commit',
+        },
+        needsBossReply: {
+          fields: { question: 'presentation' },
+          repositoryDisposition: 'deferred',
+        },
+      },
+      runIrTask: {
+        moreTasks: {
+          fields: {
+            coderOutput: 'presentation',
+            latestCommit: 'effect',
+            irTask: 'semantic',
+          },
+          repositoryDisposition: 'one-descendant-commit',
+        },
+        finalTask: {
+          fields: {
+            coderOutput: 'presentation',
+            latestCommit: 'effect',
+          },
+          repositoryDisposition: 'one-descendant-commit',
+        },
+        needsBossReply: {
+          fields: { question: 'presentation' },
+          repositoryDisposition: 'deferred',
+        },
+      },
+    },
+  },
   composePlayerPrompt: (
     input: PlaybookPlayerInput,
     promptIdentity: XStatePromptIdentity,
   ) => composePlayerPrompt(input as PlayerInput, promptIdentity),
   verbatimPayloadFields: VERBATIM_PAYLOAD_FIELDS,
   controlContextFields: ['phase'],
+  unfinishedFinalStateIds: UNFINISHED_FINAL_STATE_IDS,
   transitionEventFields: ['callerInput', 'answer', 'questionId'],
-} satisfies XStatePlaybookRuntimeSpec<CodePlaybookOptions>;
+} satisfies XStatePlaybookRuntimeSpecV3<CodePlaybookOptions>;
 
-const createPlaybookRuntime: PlaybookRuntimeFactory<CodePlaybookOptions> =
-  createXStatePlaybookRuntime(codingMachine, runtimeSpec);
+const createPlaybookRuntime: XStatePlaybookRuntimeFactory<
+  XStatePlaybookRuntimeConstruction<
+    CodePlaybookOptions,
+    CodePlaybookHostCapabilities
+  >,
+  3
+> = createXStatePlaybookRuntime<
+  CodePlaybookOptions,
+  CodePlaybookHostCapabilities
+>(
+  codingMachine,
+  runtimeSpec,
+);
 
 export default createPlaybookRuntime;

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

@@ -1,4 +1,4 @@
-import { type PlaybookRuntime } from './code.playbook.js';
+import { type CodePlaybookHostCapabilities, type PlaybookRuntime } from './code.playbook.js';
 export interface PlaybookSummaryPolicy {
     stateCountLabels: Readonly<Record<string, string>>;
     copyPasteGuardNames: readonly string[];
@@ -12,12 +12,19 @@ export interface CodePlaybookRegistryEntry {
     id: 'code';
     command: 'code';
     intent: string;
-    artifactSchema: 2;
+    artifactSchema: 3;
+    runtimeProfile: {
+        readonly kind: 'shared-factory';
+        readonly compat: {
+            readonly artifactSchema: 3;
+            readonly runtimeAbi: number;
+        };
+    };
     requiredRoleIds: readonly ['coder'];
     concurrentRoleSets: readonly [];
     summaryPolicy: PlaybookSummaryPolicy;
     validateOptions(optionSlice: unknown): CodeOptions;
-    createRuntime(options: CodeOptions): PlaybookRuntime;
+    createRuntime(options: CodeOptions, hostCapabilities: CodePlaybookHostCapabilities): PlaybookRuntime;
 }
 export declare const codeStateCountLabels: {};
 export declare const codeCopyPasteGuardNames: readonly ["directCommit", "irCommit", "moreTasks", "finalTask"];

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

@@ -47,13 +47,20 @@ export const codePlaybookRegistryEntry = {
     id: 'code',
     command: 'code',
     intent: 'implement a coding intent in reviewed, one-commit phases, using an intent record when needed',
-    artifactSchema: 2,
+    artifactSchema: 3,
+    runtimeProfile: Object.freeze({
+        kind: 'shared-factory',
+        compat: createPlaybookRuntime.compat,
+    }),
     requiredRoleIds: ['coder'],
     concurrentRoleSets: [],
     summaryPolicy: codeSummaryPolicy,
     validateOptions: validateCodeOptions,
-    createRuntime(options) {
-        return createPlaybookRuntime(options);
+    createRuntime(options, hostCapabilities) {
+        return createPlaybookRuntime({
+            configuredOptions: options,
+            hostCapabilities,
+        });
     },
 };
 export default codePlaybookRegistryEntry;

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

@@ -2,6 +2,7 @@
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 
 import createPlaybookRuntime, {
+  type CodePlaybookHostCapabilities,
   type PlaybookRuntime,
 } from './code.playbook.js';
 
@@ -20,12 +21,22 @@ export interface CodePlaybookRegistryEntry {
   id: 'code';
   command: 'code';
   intent: string;
-  artifactSchema: 2;
+  artifactSchema: 3;
+  runtimeProfile: {
+    readonly kind: 'shared-factory';
+    readonly compat: {
+      readonly artifactSchema: 3;
+      readonly runtimeAbi: number;
+    };
+  };
   requiredRoleIds: readonly ['coder'];
   concurrentRoleSets: readonly [];
   summaryPolicy: PlaybookSummaryPolicy;
   validateOptions(optionSlice: unknown): CodeOptions;
-  createRuntime(options: CodeOptions): PlaybookRuntime;
+  createRuntime(
+    options: CodeOptions,
+    hostCapabilities: CodePlaybookHostCapabilities,
+  ): PlaybookRuntime;
 }
 
 // REVIEW owns and labels its real review rounds. CODE's two suspended wrapper
@@ -91,13 +102,20 @@ export const codePlaybookRegistryEntry: CodePlaybookRegistryEntry = {
   command: 'code',
   intent:
     'implement a coding intent in reviewed, one-commit phases, using an intent record when needed',
-  artifactSchema: 2,
+  artifactSchema: 3,
+  runtimeProfile: Object.freeze({
+    kind: 'shared-factory',
+    compat: createPlaybookRuntime.compat,
+  }),
   requiredRoleIds: ['coder'],
   concurrentRoleSets: [],
   summaryPolicy: codeSummaryPolicy,
   validateOptions: validateCodeOptions,
-  createRuntime(options) {
-    return createPlaybookRuntime(options);
+  createRuntime(options, hostCapabilities) {
+    return createPlaybookRuntime({
+      configuredOptions: options,
+      hostCapabilities,
+    });
   },
 };
 

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

@@ -1,6 +1,6 @@
 import { type Captain, type CaptainSession, type TuningSelection } from '@sublang/cligent/tmux-play';
 import type { Effort, PermissionPolicy } from '@sublang/cligent';
-import type { JsonValue, PlaybookRuntime, PlaybookRuntimeSnapshot } from '@sublang/playbook/runtime';
+import type { JsonValue, PlaybookEffectLedger, PlaybookEffectLedgerCommandBatch, PlaybookRuntime, PlaybookRuntimeSnapshot } from '@sublang/playbook/runtime';
 import { type CaptainControllerPort } from '../captain.playbook/captain.playbook.js';
 import type { PlaybookSummaryPolicy } from './code.registry.js';
 interface SessionAgent {
@@ -19,11 +19,22 @@ interface PlayerLedgerEntry {
 type DeepReadonly<T> = T extends (...args: never[]) => unknown ? T : T extends readonly (infer Element)[] ? readonly DeepReadonly<Element>[] : T extends object ? {
     readonly [Key in keyof T]: DeepReadonly<T[Key]>;
 } : T;
+export interface PlaybookCaptainUnresolvedEffect {
+    readonly classification: 'one-descendant-commit' | 'multiple-commits' | 'rewritten-or-non-descendant' | 'worktree-only-change' | 'concurrent-or-foreign-change' | 'observation-ambiguous' | 'incomplete';
+    readonly baselineHead: string;
+    readonly afterHead?: string;
+    readonly commitOid?: string;
+}
+interface PlaybookCaptainUnresolvedEffectSettlementInput {
+    readonly rootPlaybookId: string;
+    readonly unresolvedEffects: readonly PlaybookCaptainUnresolvedEffect[];
+}
 type SnapshotAgentEnvelope = DeepReadonly<Omit<SessionAgent, 'model' | 'effort'>>;
 type PlayerLedgerSnapshotEntry = DeepReadonly<PlayerLedgerEntry>;
 export interface PlaybookCaptainDeps {
     loadModule?: (specifier: string) => Promise<unknown>;
     createSessionId?: () => string;
+    hostCapabilities?: Readonly<Record<string, PlaybookHostConstructionCapabilities>>;
     createCaptainRuntime?: (options: {
         readonly enabledPlaybooks: readonly {
             readonly id: string;
@@ -32,18 +43,67 @@ export interface PlaybookCaptainDeps {
         }[];
         readonly controller: CaptainControllerPort;
     }) => PlaybookRuntime;
+    unresolvedEffectSettlement?: {
+        begin(input: PlaybookCaptainUnresolvedEffectSettlementInput): Promise<void>;
+        complete(input: PlaybookCaptainUnresolvedEffectSettlementInput): Promise<void>;
+    };
+}
+/** Live, artifact-typed host facilities supplied outside configured options. */
+export interface PlaybookHostConstructionCapabilities {
+    readonly authority: {
+        readonly playbookId: string;
+        readonly artifactSchema: 3;
+        readonly cwd: string;
+        readonly sessionId: string;
+        readonly leaseOwnerToken: string;
+        readonly canonicalWorktree: {
+            readonly worktree: string;
+            readonly gitDir: string;
+        };
+        readonly requiredRoleIds: readonly string[];
+        readonly concurrentRoleSets: readonly (readonly string[])[];
+    };
+    readonly repository: {
+        readonly identity: {
+            readonly worktree: string;
+            readonly gitDir: string;
+        };
+        readonly observe: (options?: unknown) => Promise<unknown>;
+        readonly acquire: (options?: unknown) => Promise<unknown>;
+        readonly runExclusive: (options: unknown) => Promise<unknown>;
+        readonly runCohort: (options: unknown) => Promise<unknown>;
+        readonly runDeferred: (options: unknown) => Promise<unknown>;
+    };
+    readonly effectLedger: {
+        readonly snapshot: () => PlaybookEffectLedger;
+        readonly writeAhead: (commands: PlaybookEffectLedgerCommandBatch) => Promise<PlaybookEffectLedger>;
+    };
 }
-export interface PlaybookCaptainRegistryEntry {
+export type PlaybookCaptainRuntimeProfile = {
+    readonly kind: 'shared-factory';
+    readonly compat: {
+        readonly artifactSchema: 3;
+        readonly runtimeAbi: number;
+    };
+} | {
+    readonly kind: 'bespoke';
+    readonly artifactSchema: 3;
+};
+interface PlaybookCaptainRegistryEntryBase {
     id: string;
     command: string;
     intent: string;
-    artifactSchema: 2;
+    runtimeProfile: PlaybookCaptainRuntimeProfile;
     requiredRoleIds: readonly string[];
     concurrentRoleSets: readonly (readonly string[])[];
     summaryPolicy?: PlaybookSummaryPolicy;
     validateOptions(optionSlice: unknown): unknown;
-    createRuntime(options: unknown): PlaybookRuntime;
 }
+export interface PlaybookCaptainRegistryEntryV3 extends PlaybookCaptainRegistryEntryBase {
+    artifactSchema: 3;
+    createRuntime(configuredOptions: unknown, hostCapabilities: PlaybookHostConstructionCapabilities): PlaybookRuntime;
+}
+export type PlaybookCaptainRegistryEntry = PlaybookCaptainRegistryEntryV3;
 type PlaybookCaptainConversationSnapshot = {
     readonly kind: 'unopened';
 } | {
@@ -62,7 +122,7 @@ interface PlaybookCaptainJournalRecord {
     readonly kind: 'boss' | 'reply' | 'handoff' | 'action' | 'outcome';
     readonly payload: JsonValue;
 }
-interface PlaybookCaptainFrameSnapshot {
+export interface PlaybookCaptainFrameSnapshot {
     readonly playbookId: string;
     readonly sessionId: string;
     readonly rootSessionId: string;
@@ -74,7 +134,8 @@ interface PlaybookCaptainFrameSnapshot {
     readonly runtime: DeepReadonly<PlaybookRuntimeSnapshot>;
 }
 interface PlaybookCaptainShellSnapshotFields {
-    readonly schemaVersion: 3;
+    readonly schemaVersion: 4;
+    readonly effectLedger: DeepReadonly<PlaybookEffectLedger>;
     readonly captain: {
         readonly sessionId: string;
         readonly runtime: DeepReadonly<PlaybookRuntimeSnapshot>;
@@ -89,7 +150,7 @@ interface PlaybookCaptainShellSnapshotFields {
         readonly journal: number;
     };
     readonly journal: readonly PlaybookCaptainJournalRecord[];
-    readonly lastAction?: 'respond' | 'start' | 'switch' | 'dismiss' | 'deliver' | 'runtime';
+    readonly lastAction?: 'respond' | 'start' | 'switch' | 'resume' | 'dismiss' | 'deliver' | 'runtime';
     readonly lastSettlementStatus?: 'ok' | 'rejected' | 'failed';
 }
 /**
@@ -105,6 +166,7 @@ type PlaybookCaptainShellSnapshotValue = PlaybookCaptainShellSnapshotFields & ({
     readonly mode: 'engaged.parked';
     /** Root-to-leaf engagement order. */
     readonly frames: readonly PlaybookCaptainFrameSnapshot[];
+    readonly retainedEffectReconciliation?: PlaybookCaptainRetainedEffectReconciliation;
     readonly pendingBossQuestions?: JsonValue;
     readonly lastError?: {
         readonly name: string;
@@ -112,11 +174,41 @@ type PlaybookCaptainShellSnapshotValue = PlaybookCaptainShellSnapshotFields & ({
     };
 });
 export type PlaybookCaptainShellSnapshot = DeepReadonly<PlaybookCaptainShellSnapshotValue>;
+export interface PlaybookCaptainRetainedGeneration {
+    /** Repository-effect checkpoint reflected by the retained machine state. */
+    readonly effectLedger: DeepReadonly<PlaybookEffectLedger>;
+    readonly frames: readonly PlaybookCaptainFrameSnapshot[];
+    readonly retainedEffectReconciliation?: {
+        readonly sourceGenerationId: string;
+    };
+    /** Boss-facing description published for the retained root state, if any. */
+    readonly rootStateDescription?: string;
+}
+interface PlaybookCaptainRetainedEffectReconciliation {
+    readonly sourceGenerationId: string;
+    readonly checkpoint: DeepReadonly<PlaybookEffectLedger>;
+}
+export type PlaybookCaptainRetentionUpdate = {
+    readonly kind: 'retain';
+    readonly rootPlaybookId: string;
+    readonly generation: PlaybookCaptainRetainedGeneration;
+} | {
+    readonly kind: 'clear';
+    readonly rootPlaybookId: string;
+};
+export interface PlaybookCaptainSettlement {
+    readonly snapshot: PlaybookCaptainShellSnapshot;
+    readonly retentionUpdates: readonly PlaybookCaptainRetentionUpdate[];
+    readonly unresolvedEffects: readonly PlaybookCaptainUnresolvedEffect[];
+}
 /** tmux and headless front ends share this one durable Captain shell API. */
 export interface PlaybookCaptainShell extends Captain {
+    installRetainedGenerations(generations: Readonly<Record<string, PlaybookCaptainRetainedGeneration>>): Promise<void>;
     exportSnapshot(): PlaybookCaptainShellSnapshot | undefined;
+    exportSettlement(): PlaybookCaptainSettlement | undefined;
     restore(session: CaptainSession, snapshot: PlaybookCaptainShellSnapshot): Promise<void>;
 }
+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;