@sublang/playbook 9.0.0 → 11.0.0

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,12 +1,15 @@
 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 {
     readonly adapter: string;
     readonly model: TuningSelection;
     readonly effort: TuningSelection<Effort>;
+    /** Adapter-scoped fast mode. Absence is the provider default; `false` is a
+     * literal request, so this carries no provider-default sentinel. */
+    readonly fastMode?: boolean;
     readonly instruction?: string;
     readonly permissions?: PermissionPolicy;
 }
@@ -19,11 +22,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;
-type SnapshotAgentEnvelope = DeepReadonly<Omit<SessionAgent, 'model' | 'effort'>>;
+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' | 'fastMode'>>;
 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 +46,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 +125,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 +137,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 +153,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 +169,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 +177,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;