@sublang/playbook 8.0.0 → 10.0.0

package/src/accepted-outcome.d.ts

@@ -0,0 +1,18 @@
+import type { PlaybookState } from './runtime.js';
+export declare const ACCEPTED_OUTCOME_ACTION_TYPE = "playbook.acceptedOutcome";
+export interface AcceptedOutcomeReceipt {
+    readonly source: string;
+    readonly target: string;
+    readonly acceptedOutcome: string;
+}
+interface InspectedAction {
+    readonly type: string;
+    readonly params: unknown;
+}
+export interface AcceptedOutcomeConsumer {
+    capture(action: InspectedAction): void;
+    confirm(previousState: PlaybookState | undefined, state: PlaybookState): readonly AcceptedOutcomeReceipt[];
+    reset(): void;
+}
+export declare function createAcceptedOutcomeConsumer(isDeclared: (source: string, acceptedOutcome: string) => boolean): AcceptedOutcomeConsumer;
+export {};

package/src/accepted-outcome.js

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+export const ACCEPTED_OUTCOME_ACTION_TYPE = 'playbook.acceptedOutcome';
+function exactMarkerParams(value) {
+    if (value === null ||
+        typeof value !== 'object' ||
+        Array.isArray(value) ||
+        (Object.getPrototypeOf(value) !== Object.prototype &&
+            Object.getPrototypeOf(value) !== null)) {
+        throw new TypeError(`${ACCEPTED_OUTCOME_ACTION_TYPE} params must be a plain object`);
+    }
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    const keys = Reflect.ownKeys(descriptors);
+    const expected = ['acceptedOutcome', 'source', 'target'];
+    if (keys.length !== expected.length ||
+        keys.some((key) => typeof key !== 'string' || !expected.includes(key))) {
+        throw new TypeError(`${ACCEPTED_OUTCOME_ACTION_TYPE} params must contain exactly source, target, and acceptedOutcome`);
+    }
+    const stringValue = (key) => {
+        const descriptor = descriptors[key];
+        if (descriptor === undefined ||
+            !Object.prototype.hasOwnProperty.call(descriptor, 'value') ||
+            descriptor.enumerable !== true ||
+            typeof descriptor.value !== 'string' ||
+            descriptor.value.trim().length === 0) {
+            throw new TypeError(`${ACCEPTED_OUTCOME_ACTION_TYPE} params.${key} must be a nonempty enumerable string data property`);
+        }
+        return descriptor.value;
+    };
+    return Object.freeze({
+        source: stringValue('source'),
+        target: stringValue('target'),
+        acceptedOutcome: stringValue('acceptedOutcome'),
+    });
+}
+export function createAcceptedOutcomeConsumer(isDeclared) {
+    let pending = [];
+    let invalidBatch = false;
+    return Object.freeze({
+        capture(action) {
+            if (action.type !== ACCEPTED_OUTCOME_ACTION_TYPE) {
+                return;
+            }
+            if (invalidBatch)
+                return;
+            try {
+                const marker = exactMarkerParams(action.params);
+                if (!isDeclared(marker.source, marker.acceptedOutcome)) {
+                    throw new TypeError(`${ACCEPTED_OUTCOME_ACTION_TYPE} names undeclared outcome ` +
+                        `${marker.source}.${marker.acceptedOutcome}`);
+                }
+                pending.push(marker);
+            }
+            catch (error) {
+                pending = [];
+                invalidBatch = true;
+                throw error;
+            }
+        },
+        confirm(previousState, state) {
+            if (invalidBatch) {
+                pending = [];
+                invalidBatch = false;
+                return Object.freeze([]);
+            }
+            if (pending.length === 0)
+                return Object.freeze([]);
+            const captured = pending;
+            pending = [];
+            if (previousState === undefined) {
+                throw new TypeError(`${ACCEPTED_OUTCOME_ACTION_TYPE} marker has no prior public root snapshot`);
+            }
+            const seen = new Set();
+            for (const marker of captured) {
+                const identity = marker.source;
+                if (seen.has(identity)) {
+                    throw new TypeError(`${ACCEPTED_OUTCOME_ACTION_TYPE} source ${marker.source} was instrumented more than once in one action batch`);
+                }
+                seen.add(identity);
+                if (!previousState.activeStateIds.includes(marker.source)) {
+                    throw new TypeError(`${ACCEPTED_OUTCOME_ACTION_TYPE} source ${marker.source} was not confirmed by the prior public root snapshot`);
+                }
+                if (!state.activeStateIds.includes(marker.target)) {
+                    throw new TypeError(`${ACCEPTED_OUTCOME_ACTION_TYPE} target ${marker.target} was not confirmed by the public root snapshot`);
+                }
+            }
+            return Object.freeze(captured);
+        },
+        reset() {
+            pending = [];
+            invalidBatch = false;
+        },
+    });
+}

package/src/accepted-outcome.ts

@@ -0,0 +1,140 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+import type { PlaybookState } from './runtime.js';
+
+export const ACCEPTED_OUTCOME_ACTION_TYPE = 'playbook.acceptedOutcome';
+
+export interface AcceptedOutcomeReceipt {
+  readonly source: string;
+  readonly target: string;
+  readonly acceptedOutcome: string;
+}
+
+interface InspectedAction {
+  readonly type: string;
+  readonly params: unknown;
+}
+
+export interface AcceptedOutcomeConsumer {
+  capture(action: InspectedAction): void;
+  confirm(
+    previousState: PlaybookState | undefined,
+    state: PlaybookState,
+  ): readonly AcceptedOutcomeReceipt[];
+  reset(): void;
+}
+
+function exactMarkerParams(value: unknown): AcceptedOutcomeReceipt {
+  if (
+    value === null ||
+    typeof value !== 'object' ||
+    Array.isArray(value) ||
+    (Object.getPrototypeOf(value) !== Object.prototype &&
+      Object.getPrototypeOf(value) !== null)
+  ) {
+    throw new TypeError(
+      `${ACCEPTED_OUTCOME_ACTION_TYPE} params must be a plain object`,
+    );
+  }
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  const keys = Reflect.ownKeys(descriptors);
+  const expected = ['acceptedOutcome', 'source', 'target'];
+  if (
+    keys.length !== expected.length ||
+    keys.some((key) => typeof key !== 'string' || !expected.includes(key))
+  ) {
+    throw new TypeError(
+      `${ACCEPTED_OUTCOME_ACTION_TYPE} params must contain exactly source, target, and acceptedOutcome`,
+    );
+  }
+  const stringValue = (key: string): string => {
+    const descriptor = descriptors[key];
+    if (
+      descriptor === undefined ||
+      !Object.prototype.hasOwnProperty.call(descriptor, 'value') ||
+      descriptor.enumerable !== true ||
+      typeof descriptor.value !== 'string' ||
+      descriptor.value.trim().length === 0
+    ) {
+      throw new TypeError(
+        `${ACCEPTED_OUTCOME_ACTION_TYPE} params.${key} must be a nonempty enumerable string data property`,
+      );
+    }
+    return descriptor.value;
+  };
+  return Object.freeze({
+    source: stringValue('source'),
+    target: stringValue('target'),
+    acceptedOutcome: stringValue('acceptedOutcome'),
+  });
+}
+
+export function createAcceptedOutcomeConsumer(
+  isDeclared: (source: string, acceptedOutcome: string) => boolean,
+): AcceptedOutcomeConsumer {
+  let pending: AcceptedOutcomeReceipt[] = [];
+  let invalidBatch = false;
+  return Object.freeze({
+    capture(action: InspectedAction) {
+      if (action.type !== ACCEPTED_OUTCOME_ACTION_TYPE) {
+        return;
+      }
+      if (invalidBatch) return;
+      try {
+        const marker = exactMarkerParams(action.params);
+        if (!isDeclared(marker.source, marker.acceptedOutcome)) {
+          throw new TypeError(
+            `${ACCEPTED_OUTCOME_ACTION_TYPE} names undeclared outcome ` +
+              `${marker.source}.${marker.acceptedOutcome}`,
+          );
+        }
+        pending.push(marker);
+      } catch (error) {
+        pending = [];
+        invalidBatch = true;
+        throw error;
+      }
+    },
+    confirm(previousState: PlaybookState | undefined, state: PlaybookState) {
+      if (invalidBatch) {
+        pending = [];
+        invalidBatch = false;
+        return Object.freeze([]);
+      }
+      if (pending.length === 0) return Object.freeze([]);
+      const captured = pending;
+      pending = [];
+      if (previousState === undefined) {
+        throw new TypeError(
+          `${ACCEPTED_OUTCOME_ACTION_TYPE} marker has no prior public root snapshot`,
+        );
+      }
+      const seen = new Set<string>();
+      for (const marker of captured) {
+        const identity = marker.source;
+        if (seen.has(identity)) {
+          throw new TypeError(
+            `${ACCEPTED_OUTCOME_ACTION_TYPE} source ${marker.source} was instrumented more than once in one action batch`,
+          );
+        }
+        seen.add(identity);
+        if (!previousState.activeStateIds.includes(marker.source)) {
+          throw new TypeError(
+            `${ACCEPTED_OUTCOME_ACTION_TYPE} source ${marker.source} was not confirmed by the prior public root snapshot`,
+          );
+        }
+        if (!state.activeStateIds.includes(marker.target)) {
+          throw new TypeError(
+            `${ACCEPTED_OUTCOME_ACTION_TYPE} target ${marker.target} was not confirmed by the public root snapshot`,
+          );
+        }
+      }
+      return Object.freeze(captured);
+    },
+    reset() {
+      pending = [];
+      invalidBatch = false;
+    },
+  });
+}

package/src/runtime.d.ts

@@ -55,6 +55,7 @@ export interface PlaybookSuspendedCall extends PlaybookPendingCall {
     stateId: string;
     text: string;
     turnId?: number;
+    effectBoundaryPrefixSequence?: number | null;
 }
 export interface PlaybookCallRequest {
     callId: string;
@@ -90,6 +91,9 @@ export type PlaybookCallStart = {
 export type PlaybookRunResult = {
     outcome: 'quiescent' | 'no-action';
     state: PlaybookState;
+} | {
+    outcome: 'unresolved-effect';
+    state: PlaybookState;
 } | {
     outcome: 'failed' | 'aborted';
     state: PlaybookState;
@@ -97,6 +101,7 @@ export type PlaybookRunResult = {
 } | {
     outcome: 'terminal';
     state: PlaybookState;
+    stateDescription?: string;
     output?: JsonValue;
 } | {
     outcome: 'suspended';
@@ -125,9 +130,14 @@ export interface PlaybookSession {
     playerSessions?: PlayerSessionStore;
     ports: PlaybookPorts;
 }
-export type PlaybookTraceType = 'session.started' | 'boss.input.received' | 'judge.call.started' | 'judge.call.finished' | 'player.call.started' | 'player.call.finished' | 'captain.call.started' | 'captain.call.finished' | 'playbook.call.started' | 'playbook.call.finished' | 'apply.started' | 'apply.finished' | 'fsm.transition' | 'status.emitted' | 'boss.input.settled' | 'session.disposed';
+export interface PlaybookAdoptionContext {
+    readonly sourceSessionId: string;
+    readonly sourceGenerationId: string;
+    readonly targetChildSessionId?: string;
+}
+export type PlaybookTraceType = 'session.started' | 'boss.input.received' | 'judge.call.started' | 'judge.call.finished' | 'player.call.started' | 'player.call.finished' | 'captain.call.started' | 'captain.call.finished' | 'playbook.call.started' | 'playbook.call.finished' | '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;
@@ -152,8 +162,127 @@ export interface PlaybookPendingBossQuestion {
     question: string;
     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>;
+}
 export interface PlaybookRuntimeSnapshot {
-    schemaVersion: 3;
+    schemaVersion: 4;
     playbookId: string;
     machine: JsonValue;
     roleResumeTokens: {
@@ -169,6 +298,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;
 }
 export interface PlaybookControlAction {
@@ -193,11 +337,29 @@ export type PlaybookControlReceipt = {
     disposition: 'failed';
     error: NormalizedError;
 };
+export interface PlaybookRetainedGenerationMetadata {
+    readonly unfinishedFinalStateIds: readonly string[];
+}
 export interface PlaybookRuntime {
     init(session: PlaybookSession): Promise<void>;
     exportSnapshot?(): PlaybookRuntimeSnapshot | undefined;
     restore?(session: PlaybookSession, snapshot: PlaybookRuntimeSnapshot): Promise<void>;
+    adopt?(session: PlaybookSession, snapshot: PlaybookRuntimeSnapshot, context: PlaybookAdoptionContext): Promise<void>;
+    readonly retainedGenerationMetadata?: PlaybookRetainedGenerationMetadata;
     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;