@sublang/playbook 8.0.0 → 10.0.0

package/src/runtime.ts

@@ -83,10 +83,13 @@ export interface PlaybookPendingCall {
 // DR-031 §5: complete durable identity for one nested call whose start
 // boundary has already been published and whose child remains suspended.
 // `turnId` is absent when the call was opened outside a Boss-turn boundary.
+// A schema-3 runtime adds the effect-ledger prefix captured before the causal
+// public boundary; null records that the prefix could not be observed.
 export interface PlaybookSuspendedCall extends PlaybookPendingCall {
   stateId: string;
   text: string;
   turnId?: number;
+  effectBoundaryPrefixSequence?: number | null;
 }
 
 export interface PlaybookCallRequest {
@@ -124,6 +127,7 @@ export type PlaybookCallStart =
 
 export type PlaybookRunResult =
   | { outcome: 'quiescent' | 'no-action'; state: PlaybookState }
+  | { outcome: 'unresolved-effect'; state: PlaybookState }
   | {
       outcome: 'failed' | 'aborted';
       state: PlaybookState;
@@ -132,6 +136,7 @@ export type PlaybookRunResult =
   | {
       outcome: 'terminal';
       state: PlaybookState;
+      stateDescription?: string;
       output?: JsonValue;
     }
   | {
@@ -173,6 +178,16 @@ export interface PlaybookSession {
   ports: PlaybookPorts;
 }
 
+// DR-038 §5: the source identities and, for a suspended nested call, the
+// fresh target child identity that let adoption start one explicit target
+// trace lineage without carrying source-session counters or child UUIDs
+// forward.
+export interface PlaybookAdoptionContext {
+  readonly sourceSessionId: string;
+  readonly sourceGenerationId: string;
+  readonly targetChildSessionId?: string;
+}
+
 export type PlaybookTraceType =
   | 'session.started'
   | 'boss.input.received'
@@ -187,12 +202,13 @@ export type PlaybookTraceType =
   | 'apply.started'
   | 'apply.finished'
   | 'fsm.transition'
+  | 'outcome.accepted'
   | 'status.emitted'
   | 'boss.input.settled'
   | 'session.disposed';
 
 export interface PlaybookTraceEvent {
-  schemaVersion: 3;
+  schemaVersion: 4;
   sessionId: string;
   playbookId: string;
   rootSessionId: string;
@@ -214,12 +230,164 @@ export interface PlaybookPendingBossQuestion {
   sourceItem?: string;
 }
 
+/** One repository disposition declared by a governed outcome arm (DR-040). */
+export type PlaybookRepositoryDisposition =
+  | 'unchanged'
+  | 'one-descendant-commit'
+  | 'deferred';
+
+/** A detached Git-visible repository observation owned by the effect ledger. */
+export interface PlaybookRepositoryObservation {
+  readonly worktree: string;
+  readonly gitDir: string;
+  readonly head: string;
+  readonly projection: Readonly<Record<string, JsonValue>>;
+  readonly projectionDigest: string;
+}
+
+/** The fail-closed classification of one complete physical or logical receipt. */
+export interface PlaybookRepositoryReceipt {
+  readonly classification:
+    | 'unchanged'
+    | 'one-descendant-commit'
+    | 'multiple-commits'
+    | 'rewritten-or-non-descendant'
+    | 'worktree-only-change'
+    | 'concurrent-or-foreign-change'
+    | 'observation-ambiguous';
+  readonly baseline: PlaybookRepositoryObservation;
+  readonly after?: PlaybookRepositoryObservation;
+  readonly commitOid?: string;
+}
+
+/** One durably ordered physical governed-player boundary (DR-040). */
+export interface PlaybookEffectBoundary {
+  readonly sequence: number;
+  readonly boundaryId: string;
+  readonly attemptId: string;
+  readonly attemptNumber: number;
+  readonly playbookId: string;
+  readonly runtimeSessionId: string;
+  readonly turnId: number;
+  readonly callId: string;
+  readonly roleId: string;
+  readonly sourceStateId: string;
+  readonly sourceOutcomeSchema: JsonValue;
+  readonly dispositions: readonly PlaybookRepositoryDisposition[];
+  readonly canonicalWorktree: {
+    readonly worktree: string;
+    readonly gitDir: string;
+  };
+  readonly baseline: PlaybookRepositoryObservation;
+  readonly after?: PlaybookRepositoryObservation;
+  readonly physicalReceipt?: PlaybookRepositoryReceipt;
+  readonly finalText?: string;
+  readonly semanticCandidate?: JsonValue;
+  readonly initialSemanticCandidate?: JsonValue;
+  readonly correctionBudget: { readonly limit: 1; readonly spent: boolean };
+  readonly cohortId?: string;
+  readonly logicalOperationId?: string;
+}
+
+/** One physical boundary before the host assigns attempt and sequence data. */
+export type PlaybookEffectBoundaryStart = Omit<
+  PlaybookEffectBoundary,
+  | 'sequence'
+  | 'attemptId'
+  | 'attemptNumber'
+  | 'after'
+  | 'physicalReceipt'
+  | 'finalText'
+  | 'semanticCandidate'
+  | 'initialSemanticCandidate'
+>;
+
+/** One deferred logical operation spanning its ordered physical boundaries. */
+export interface PlaybookEffectLogicalOperation {
+  readonly sequence: number;
+  readonly operationId: string;
+  readonly playbookId: string;
+  readonly runtimeSessionId: string;
+  readonly boundaryIds: readonly string[];
+  readonly originalBaseline: PlaybookRepositoryObservation;
+  readonly checkpoint?: PlaybookRepositoryObservation;
+  readonly pendingQuestion?: PlaybookPendingBossQuestion;
+  readonly playerContinuation?: JsonValue;
+  readonly checkpointRestorationEligible: boolean;
+  readonly logicalReceipt?: PlaybookRepositoryReceipt;
+}
+
+/** Complete detached mirror of one host-owned reconciliation ledger. */
+export interface PlaybookEffectLedger {
+  readonly schemaVersion: 1;
+  readonly revision: number;
+  readonly boundaries: readonly PlaybookEffectBoundary[];
+  readonly logicalOperations: readonly PlaybookEffectLogicalOperation[];
+}
+
+/** One mutation accepted by the host-owned effect-ledger write-ahead boundary. */
+export type PlaybookEffectLedgerCommand =
+  | {
+      readonly kind: 'start-boundaries';
+      readonly boundaries: readonly [
+        PlaybookEffectBoundaryStart,
+        ...PlaybookEffectBoundaryStart[],
+      ];
+    }
+  | {
+      readonly kind: 'replace-boundaries';
+      readonly replacements: readonly [
+        {
+          readonly expected: PlaybookEffectBoundary;
+          readonly next: PlaybookEffectBoundary;
+        },
+        ...{
+          readonly expected: PlaybookEffectBoundary;
+          readonly next: PlaybookEffectBoundary;
+        }[],
+      ];
+    }
+  | {
+      readonly kind: 'append-logical-operations';
+      readonly operations: readonly [
+        Omit<PlaybookEffectLogicalOperation, 'sequence'>,
+        ...Omit<PlaybookEffectLogicalOperation, 'sequence'>[],
+      ];
+    }
+  | {
+      readonly kind: 'replace-logical-operations';
+      readonly replacements: readonly [
+        {
+          readonly expected: PlaybookEffectLogicalOperation;
+          readonly next: PlaybookEffectLogicalOperation;
+        },
+        ...{
+          readonly expected: PlaybookEffectLogicalOperation;
+          readonly next: PlaybookEffectLogicalOperation;
+        }[],
+      ];
+    };
+
+/** A nonempty command batch persisted as one ledger revision. */
+export type PlaybookEffectLedgerCommandBatch = readonly [
+  PlaybookEffectLedgerCommand,
+  ...PlaybookEffectLedgerCommand[],
+];
+
+/** Live current-host seam for atomic effect-ledger observation and mutation. */
+export interface PlaybookEffectLedgerCapability {
+  snapshot(): PlaybookEffectLedger;
+  writeAhead(
+    commands: PlaybookEffectLedgerCommandBatch,
+  ): Promise<PlaybookEffectLedger>;
+}
+
 // DR-014 §1 / DR-031 §5 / DR-032: JSON-safe capture of a parked or nested-call
 // suspended session. `machine` is the opaque XState persisted snapshot;
 // pending Boss questions and a suspended call are first-class so a
 // host never has to reconstruct durable ownership from presentation records.
 export interface PlaybookRuntimeSnapshot {
-  schemaVersion: 3;
+  schemaVersion: 4;
   playbookId: string;
   machine: JsonValue;
   roleResumeTokens: { readonly [roleId: string]: string };
@@ -233,6 +401,21 @@ export interface PlaybookRuntimeSnapshot {
   };
   state: PlaybookState;
   pendingBossQuestions: readonly PlaybookPendingBossQuestion[];
+  effectLedger: PlaybookEffectLedger;
+  /** Original runtime identity retained across schema-3 adoption lineage. */
+  retainedEffectSourceSessionId?: string;
+  /**
+   * Unsafe retained-adoption checkpoint. The marker remains durable until
+   * authoritative reconciliation proves its complete suffix replay-safe.
+   */
+  retainedEffectReconciliation?: {
+    readonly sourceSessionId: string;
+    readonly checkpoint: PlaybookEffectLedger;
+  };
+  failedEffectAttempt?: {
+    readonly boundaryPrefix: number;
+    readonly attemptId: string | null;
+  };
   suspendedCall?: PlaybookSuspendedCall;
 }
 
@@ -268,6 +451,15 @@ export type PlaybookControlReceipt =
   | { disposition: 'executed'; run: PlaybookRunResult }
   | { disposition: 'failed'; error: NormalizedError };
 
+// DR-038 §2: link-authored metadata the Captain uses to decide whether a
+// quiescent generation is eligible for retention and whether a root terminal
+// outcome preserves its pre-terminal generation. Presence is classification
+// data, independent from the optional adoption operation; an explicitly empty
+// final-state list is meaningful.
+export interface PlaybookRetainedGenerationMetadata {
+  readonly unfinishedFinalStateIds: readonly string[];
+}
+
 export interface PlaybookRuntime {
   init(session: PlaybookSession): Promise<void>;
   // DR-014 §1 optional durable-session capability: a runtime implements
@@ -280,6 +472,16 @@ export interface PlaybookRuntime {
     session: PlaybookSession,
     snapshot: PlaybookRuntimeSnapshot,
   ): Promise<void>;
+  // DR-038 §1 optional generation-adoption capability: a distinct
+  // initialization path that rehydrates a retained snapshot under a fresh
+  // engagement identity. Presence is feature-detected independently from
+  // retained-generation classification metadata.
+  adopt?(
+    session: PlaybookSession,
+    snapshot: PlaybookRuntimeSnapshot,
+    context: PlaybookAdoptionContext,
+  ): Promise<void>;
+  readonly retainedGenerationMetadata?: PlaybookRetainedGenerationMetadata;
   // DR-029 optional control-surface capability: a runtime implements
   // both members or neither. `describe` is side-effect free and valid at
   // parked quiescence outside an active boundary; `apply` revalidates the
@@ -288,6 +490,16 @@ export interface PlaybookRuntime {
   // runtime lacking the pair advertises no actions; plain text delivery is
   // the only verb against it.
   describe?(): PlaybookControlView;
+  /**
+   * Host-only identities of the durable envelopes that still require
+   * unresolved-effect settlement. The host owns their bounded projection
+   * from its authoritative effect ledger; no repository evidence enters a
+   * runtime-owned run result.
+   */
+  unresolvedEffectEnvelopes?(): readonly (
+    | { readonly kind: 'boundary'; readonly boundaryId: string }
+    | { readonly kind: 'logical-operation'; readonly operationId: string }
+  )[];
   apply?(input: {
     actionId: string;
     key: string;

package/src/xstate-playbook-runtime.d.ts

@@ -1,5 +1,5 @@
 import type { AnyStateMachine, EventObject, PromiseActorLogic } from 'xstate';
-import type { CaptainResult, JsonValue, PlaybookPorts, PlaybookRuntimeFactory, PlaybookSession, PlaybookState, PlayerResult } from './runtime.js';
+import type { CaptainResult, JsonValue, PlaybookEffectBoundary, PlaybookEffectBoundaryStart, PlaybookEffectLedger, PlaybookEffectLedgerCapability, PlaybookPendingBossQuestion, PlaybookPorts, PlaybookRepositoryReceipt, PlaybookRuntimeFactory, PlaybookSession, PlaybookState, PlayerResult } from './runtime.js';
 export interface PlaybookPendingBossQuestionContext {
     questionId: string;
     resumeStateId: string;
@@ -52,9 +52,23 @@ export type JudgePurpose = 'boss-input-classification' | 'player-output-adjudica
  */
 export interface RuntimeBoundaryCalls {
     callPlayer(input: PlaybookPlayerInput, roleId: string, prompt: string, signal: AbortSignal): Promise<PlayerResult>;
+    /**
+     * Return the host-acknowledged adjudication performed while a governed
+     * repository claim was still held. The value is consumable once.
+     */
+    takeGovernedPlayerOutput?(result: PlayerResult): GovernedPlayerSettlement | undefined;
+    recordGovernedPlayerOutput?(result: PlayerResult, output: PlaybookActorOutput): void;
     callJudge(purpose: JudgePurpose, stateId: string | undefined, prompt: string, signal: AbortSignal): Promise<string>;
     callCaptain?(input: PlaybookCaptainInput, prompt: string, signal: AbortSignal, callOptions?: XStateCaptainCallOptions): Promise<CaptainResult>;
 }
+/** Host-acknowledged outcome of one governed player reconciliation. */
+type GovernedPlayerSettlement = {
+    readonly status: 'resolved';
+    readonly output: PlaybookActorOutput;
+} | {
+    readonly status: 'unresolved';
+    readonly error: unknown;
+};
 /**
  * Presentation selection for one traced direct-Captain call
  * (slc/link.md §Captain adjudication). `'visible'` (the default) is the
@@ -95,6 +109,87 @@ export declare const BOSS_REPLY_ERRORS: {
     readonly missingQuestion: "needsBossReply outcome missing 'question' field";
     readonly unregisteredState: (stateId: string) => string;
 };
+interface XStateRepositoryOperationSettlement<T> {
+    readonly status: 'fulfilled';
+    readonly value: T;
+}
+interface XStateRepositoryOperationRejection {
+    readonly status: 'rejected';
+    readonly reason: unknown;
+}
+interface XStateRepositoryExclusiveCompletion<T> {
+    readonly boundary: PlaybookEffectBoundary;
+    readonly operation: XStateRepositoryOperationSettlement<T> | XStateRepositoryOperationRejection;
+    readonly receipt: PlaybookRepositoryReceipt;
+    /** Physical receipt for an ordinary call; cumulative receipt for a chain. */
+    readonly outcomeReceipt: PlaybookRepositoryReceipt;
+}
+interface XStateDeferredBinding {
+    readonly operationId: string;
+    readonly pendingQuestion: PlaybookPendingBossQuestion;
+    readonly playerContinuation: JsonValue;
+}
+interface XStateRepositoryCompletionEvidence {
+    readonly finalText?: string;
+    readonly semanticCandidate?: JsonValue;
+    readonly deferred?: XStateDeferredBinding;
+    readonly unresolved?: true;
+}
+interface XStateRepositoryExclusiveResult<T> {
+    readonly operation: XStateRepositoryOperationSettlement<T> | XStateRepositoryOperationRejection;
+    readonly receipt: PlaybookRepositoryReceipt;
+    readonly effectLedger: PlaybookEffectLedger;
+    readonly deferredStatus?: 'bound' | 'unresolved';
+}
+interface XStateRepositoryDeferredContinuationResult<T> {
+    readonly status: 'continued';
+    readonly operation: XStateRepositoryOperationSettlement<T> | XStateRepositoryOperationRejection;
+    readonly receipt: PlaybookRepositoryReceipt;
+    readonly logicalReceipt?: PlaybookRepositoryReceipt;
+    readonly effectLedger: PlaybookEffectLedger;
+    readonly deferredStatus?: 'bound' | 'unresolved';
+}
+interface XStateRepositoryDeferredCheckpointMismatch {
+    readonly status: 'checkpoint-mismatch' | 'ineligible';
+    readonly effectLedger: PlaybookEffectLedger;
+}
+interface XStateRepositoryDeferredParked {
+    readonly status: 'parked';
+    readonly effectLedger: PlaybookEffectLedger;
+}
+interface XStateRepositoryDeferredRestoreResult {
+    readonly status: 'restored' | 'checkpoint-mismatch' | 'ineligible';
+    readonly effectLedger: PlaybookEffectLedger;
+}
+type XStateEffectBoundarySeed = Omit<PlaybookEffectBoundaryStart, 'playbookId' | 'canonicalWorktree' | 'baseline' | 'cohortId'>;
+export interface XStateRepositoryCapability {
+    runExclusive<T>(options: {
+        readonly signal: AbortSignal;
+        readonly effectBoundary: XStateEffectBoundarySeed;
+        readonly operation: (context: {
+            readonly baseline: PlaybookRepositoryReceipt['baseline'];
+            readonly identity: unknown;
+        }) => Promise<T>;
+        readonly completeEffectBoundary: (completion: XStateRepositoryExclusiveCompletion<T>) => XStateRepositoryCompletionEvidence | Promise<XStateRepositoryCompletionEvidence>;
+    }): Promise<XStateRepositoryExclusiveResult<T>>;
+    runDeferred<T>(options: {
+        readonly mode: 'continue';
+        readonly signal: AbortSignal;
+        readonly operationId: string;
+        readonly effectBoundary: XStateEffectBoundarySeed;
+        readonly operation: (context: {
+            readonly baseline: PlaybookRepositoryReceipt['baseline'];
+            readonly identity: unknown;
+            readonly playerContinuation: JsonValue;
+        }) => Promise<T>;
+        readonly completeEffectBoundary: (completion: XStateRepositoryExclusiveCompletion<T>) => XStateRepositoryCompletionEvidence | Promise<XStateRepositoryCompletionEvidence>;
+    }): Promise<XStateRepositoryDeferredContinuationResult<T> | XStateRepositoryDeferredCheckpointMismatch>;
+    runDeferred(options: {
+        readonly mode: 'park' | 'restore';
+        readonly signal: AbortSignal;
+        readonly operationId: string;
+    }): Promise<XStateRepositoryDeferredParked | XStateRepositoryDeferredRestoreResult>;
+}
 /** The runtime ABI this engine implements (DR-022). */
 export declare const RUNTIME_ABI = 1;
 /** The linked-artifact schema versions this engine accepts (DR-022). */
@@ -106,6 +201,43 @@ export interface XStatePlaybookRuntimeCompat {
     /** The engine ABI the artifact was linked against. */
     runtimeAbi: number;
 }
+/** Authority for one schema-3 delegated-player outcome payload field. */
+export type XStateOutcomeFieldAuthority = 'presentation' | 'semantic' | 'effect' | 'runtime';
+/** Repository disposition required by one schema-3 outcome arm. */
+export type XStateRepositoryDisposition = 'unchanged' | 'one-descendant-commit' | 'deferred';
+/** Closed authority and repository contract for one governed outcome. */
+export interface XStateGovernedOutcomeSpec {
+    readonly fields: Readonly<Record<string, XStateOutcomeFieldAuthority>>;
+    readonly repositoryDisposition: XStateRepositoryDisposition;
+}
+/**
+ * Schema-3 authority metadata, keyed first by player state and then by its
+ * declared outcome. A roleless artifact supplies an explicitly empty
+ * `governedPlayerStates` object.
+ */
+export interface XStateOutcomeAuthoritySpec {
+    readonly governedPlayerStates: Readonly<Record<string, Readonly<Record<string, XStateGovernedOutcomeSpec>>>>;
+}
+/**
+ * Schema-3 factory input composed by a registry from persisted configured
+ * options and live current-host capabilities. The engine snapshots only the
+ * first member and never places the second in machine input or persistence.
+ */
+export interface XStatePlaybookRuntimeConstruction<ConfiguredOptions, HostCapabilities extends object> {
+    readonly configuredOptions: ConfiguredOptions;
+    readonly hostCapabilities: HostCapabilities & {
+        readonly repository: XStateRepositoryCapability;
+        readonly effectLedger: PlaybookEffectLedgerCapability;
+    };
+}
+export type XStatePlaybookRuntimeFactoryOptions<ConfiguredOptions, HostCapabilities extends object> = XStatePlaybookRuntimeConstruction<ConfiguredOptions, HostCapabilities>;
+/** Shared XState factory with its captured, validated artifact compatibility. */
+export type XStatePlaybookRuntimeFactory<Options = unknown, ArtifactSchema extends 3 = 3> = PlaybookRuntimeFactory<Options> & {
+    readonly compat: Readonly<{
+        readonly artifactSchema: ArtifactSchema;
+        readonly runtimeAbi: typeof RUNTIME_ABI;
+    }>;
+};
 /**
  * One direct-Captain actor invocation handed to a spec's `captainStrategy`
  * (slc/link.md §Captain adjudication, controller form). The engine owns
@@ -146,15 +278,9 @@ export interface XStateCaptainStrategyRun<TOptions> {
     recoverableFailure<E extends Error>(error: E): E;
 }
 export type XStateCaptainStrategy<TOptions> = (run: XStateCaptainStrategyRun<TOptions>) => Promise<PlaybookActorOutput>;
-export interface XStatePlaybookRuntimeSpec<TOptions> {
+interface XStatePlaybookRuntimeSpecBase<TOptions> {
     /** Diagnostic label used in internal invariant errors. Default 'playbook'. */
     label?: string;
-    /**
-     * Link-time compatibility declaration checked at construction against the
-     * loaded engine's self-report (DR-022). Absent declarations reject because
-     * their overloaded player metadata has no safe local-role interpretation.
-     */
-    compat?: XStatePlaybookRuntimeCompat;
     /** Validate and JSON-snapshot the caller's per-run options. */
     snapshotOptions: (value: unknown) => TOptions;
     /** Derive the FSM machine input from validated options. Default: identity. */
@@ -168,6 +294,15 @@ export interface XStatePlaybookRuntimeSpec<TOptions> {
     entryEvent?: {
         type: string;
         textField: string;
+        /**
+         * DR-034: the FSM context member this machine's entry action copies the
+         * exact Boss text into. Where it is named, the failure-state retry
+         * builds its payload from that member of the live snapshot instead of
+         * from the process-local recorded event, so the action derives the same
+         * before and after `restore`. Absent: the recorded event stays the
+         * source and the action lives only as long as the process.
+         */
+        contextField?: string;
     };
     /**
      * Exact flat Boss-event contracts whose non-text fields the judge may
@@ -217,6 +352,8 @@ export interface XStatePlaybookRuntimeSpec<TOptions> {
      * surfaced first-class by the view and shall not be named here.
      */
     controlContextFields?: readonly string[];
+    /** Root final states whose terminal outcome leaves unfinished work. Default: none. */
+    unfinishedFinalStateIds?: ReadonlySet<string>;
     /** States that may suspend for a Boss reply. Default: targets of the FSM's `awaitBossReply` BOSS_REPLY transitions. */
     resumableStateIds?: ReadonlySet<string>;
     /** Human status lines for a root transition. Default: guard, declared-player, question, and failure lines. */
@@ -228,6 +365,14 @@ export interface XStatePlaybookRuntimeSpec<TOptions> {
     /** Working directory for `script` actors. Default: the validated options' string `cwd`, else the process working directory. */
     scriptCwd?: (options: TOptions) => string | undefined;
 }
+export interface XStatePlaybookRuntimeSpec<TOptions> extends XStatePlaybookRuntimeSpecBase<TOptions> {
+    compat: XStatePlaybookRuntimeCompat & {
+        artifactSchema: 3;
+    };
+    outcomeAuthority: XStateOutcomeAuthoritySpec;
+}
+/** Schema-3 shared-engine spec with required exact outcome authority metadata. */
+export type XStatePlaybookRuntimeSpecV3<TOptions> = XStatePlaybookRuntimeSpec<TOptions>;
 /** Strip a single Markdown code fence that wraps the whole string. */
 export declare function stripCodeFence(text: string): string;
 export declare function extractJsonValue(text: string, start: number, repair: boolean): string | undefined;
@@ -283,9 +428,11 @@ export interface PlayerAdjudicationSpec {
 export declare function adjudicatePlayerOutput(spec: PlayerAdjudicationSpec, input: PlaybookPlayerInput, finalText: string, ports: PlaybookPorts, signal: AbortSignal, boundary?: RuntimeBoundaryCalls): Promise<PlaybookActorOutput>;
 interface PlayerBridgeSpec {
     resolveRoleId: (input: PlaybookPlayerInput) => string;
+    validateInput?: (input: PlaybookPlayerInput) => void;
     composePlayerPrompt: (input: PlaybookPlayerInput) => string;
     adjudication: PlayerAdjudicationSpec;
     resumableStateIds: ReadonlySet<string>;
+    allowsCorrectiveReplay?: (result: PlayerResult) => boolean;
 }
 export declare function createPlayerBridge(spec: PlayerBridgeSpec, ports: PlaybookPorts, getActiveSignal?: () => AbortSignal | undefined, boundary?: RuntimeBoundaryCalls, onControlPlaneError?: (error: unknown) => void): PromiseActorLogic<PlaybookActorOutput, PlaybookPlayerInput>;
 /**
@@ -311,11 +458,13 @@ export declare function stateDescriptionsFromMachine(machine: AnyStateMachine):
  * under the slc/link.md contract. The factory provides every actor kind the
  * machine declares — `player`, `script`, `captain`, and nested `playbook`
  * (literal and dynamic) — and implements the full runtime lifecycle including
- * the optional parked-session snapshot capability (DR-014).
+ * the optional parked-session snapshot capability (DR-014) and the retained-
+ * snapshot adoption capability (DR-038).
  *
- * Scope: machines that declare no parallel state (each snapshot exposes
- * exactly one playbook state id). Parallel-region FSMs keep their own linked
- * runtimes.
+ * Scope: flat single-region machines — no parallel state, no compound
+ * child states, and every root state's `meta.playbook.stateId` equal to its
+ * state key — so each snapshot exposes exactly one playbook state id.
+ * Parallel-region FSMs keep their own linked runtimes.
  */
-export declare function createXStatePlaybookRuntime<TOptions>(machine: AnyStateMachine, spec: XStatePlaybookRuntimeSpec<TOptions>): PlaybookRuntimeFactory<TOptions>;
+export declare function createXStatePlaybookRuntime<TOptions, THostCapabilities extends object>(machine: AnyStateMachine, spec: XStatePlaybookRuntimeSpecV3<TOptions>): XStatePlaybookRuntimeFactory<XStatePlaybookRuntimeConstruction<TOptions, THostCapabilities>, 3>;
 export {};