@sublang/playbook 0.9.0 → 1.3.0

package/src/xstate-runtime.ts

@@ -0,0 +1,1816 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+import {
+  fromPromise,
+  waitFor,
+  type AnyActorRef,
+  type PromiseActorLogic,
+  type SnapshotFrom,
+} from 'xstate';
+
+import type {
+  CaptainResult,
+  JsonValue,
+  NormalizedError,
+  PlaybookCallRequest,
+  PlaybookCallResult,
+  PlaybookCallStart,
+  PlaybookPendingBossQuestion,
+  PlaybookPendingCall,
+  PlaybookRuntimeSnapshot,
+  PlaybookSession,
+  PlaybookState,
+  PlaybookStateValue,
+  PlayerResult,
+} from './runtime.js';
+
+// DR-019: the generic linked-runtime factory and its strategy helpers live
+// in the sibling module and are re-exported here so linked artifacts import
+// one shared engine surface.
+export * from './xstate-playbook-runtime.js';
+
+const BUSY_TAG = 'playbook.busy';
+const SUSPENDED_TAG = 'playbook.suspended';
+
+type Deferred<T> = {
+  promise: Promise<T>;
+  resolve(value: T): void;
+  reject(reason: unknown): void;
+};
+
+function deferred<T>(): Deferred<T> {
+  let resolve!: (value: T) => void;
+  let reject!: (reason: unknown) => void;
+  const promise = new Promise<T>((resolvePromise, rejectPromise) => {
+    resolve = resolvePromise;
+    reject = rejectPromise;
+  });
+  return { promise, resolve, reject };
+}
+
+function withAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  if (signal.aborted) return Promise.reject(signal.reason);
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = (): void => reject(signal.reason);
+    signal.addEventListener('abort', onAbort, { once: true });
+    void promise.then(
+      (value) => {
+        signal.removeEventListener('abort', onAbort);
+        resolve(value);
+      },
+      (error: unknown) => {
+        signal.removeEventListener('abort', onAbort);
+        reject(error);
+      },
+    );
+  });
+}
+
+function isAbortReason(error: unknown, signal: AbortSignal): boolean {
+  return (
+    signal.aborted &&
+    (error === signal.reason || normalizeError(error).name === 'AbortError')
+  );
+}
+
+const NEVER_ABORTED_SIGNAL = new AbortController().signal;
+
+/**
+ * Compose invocation-lifetime and imperative-boundary cancellation without
+ * installing a second forwarding listener in each generated runtime.
+ */
+export function combineAbortSignals(
+  ...signals: readonly (AbortSignal | undefined)[]
+): AbortSignal {
+  const present: AbortSignal[] = [];
+  for (const [index, signal] of signals.entries()) {
+    if (signal === undefined) continue;
+    if (!(signal instanceof AbortSignal)) {
+      throw new TypeError(`abort signal ${index} must be an AbortSignal`);
+    }
+    present.push(signal);
+  }
+  if (present.length === 0) return NEVER_ABORTED_SIGNAL;
+  if (present.length === 1) return present[0];
+  return AbortSignal.any(present);
+}
+
+const abortCleanups = new WeakMap<AbortSignal, Set<Promise<unknown>>>();
+
+/**
+ * Register host cleanup started synchronously by an invocation abort.
+ * The nested bridge drains these promises before it publishes the matching
+ * call-finish boundary, without widening the public six-port contract.
+ */
+export function registerPlaybookAbortCleanup(
+  signal: AbortSignal,
+  cleanup: Promise<unknown>,
+): void {
+  let pending = abortCleanups.get(signal);
+  if (!pending) {
+    pending = new Set();
+    abortCleanups.set(signal, pending);
+  }
+  pending.add(cleanup);
+  // Mark rejection handled immediately, but retain the settled promise until
+  // the bridge's allSettled drain observes its outcome.
+  void cleanup.catch(() => undefined);
+}
+
+async function drainPlaybookAbortCleanups(signal: AbortSignal): Promise<void> {
+  const failures: unknown[] = [];
+  while (true) {
+    const pending = abortCleanups.get(signal);
+    if (!pending || pending.size === 0) break;
+    const batch = [...pending];
+    pending.clear();
+    const outcomes = await Promise.allSettled(batch);
+    for (const outcome of outcomes) {
+      if (outcome.status === 'rejected') failures.push(outcome.reason);
+    }
+  }
+  abortCleanups.delete(signal);
+  if (failures.length === 1) throw failures[0];
+  if (failures.length > 1) {
+    throw new AggregateError(failures, 'playbook abort cleanup failed');
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value) as unknown;
+  return prototype === Object.prototype || prototype === null;
+}
+
+function own(value: object, key: PropertyKey): boolean {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+/**
+ * Validate and detach one JSON value from the exact property descriptors that
+ * were inspected. Reading `value[key]` after validation would let a Proxy
+ * substitute a different value between the check and the clone.
+ */
+function snapshotJsonValueFromDescriptors(
+  value: unknown,
+  path = '$',
+  ancestors: ReadonlySet<object> = new Set(),
+): JsonValue {
+  if (
+    value === null ||
+    typeof value === 'string' ||
+    typeof value === 'boolean'
+  ) {
+    return value;
+  }
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new TypeError(`${path} must contain a finite JSON number`);
+    }
+    if (Object.is(value, -0)) {
+      throw new TypeError(`${path} must not contain negative zero`);
+    }
+    return value;
+  }
+  if (Array.isArray(value)) {
+    if (Object.getPrototypeOf(value) !== Array.prototype) {
+      throw new TypeError(`${path} must be a plain JSON array`);
+    }
+    if (ancestors.has(value)) {
+      throw new TypeError(`${path} must not contain a JSON cycle`);
+    }
+    const nextAncestors = new Set(ancestors).add(value);
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    const descriptorMap = descriptors as unknown as Record<
+      PropertyKey,
+      PropertyDescriptor | undefined
+    >;
+    const descriptorKeys = Reflect.ownKeys(descriptors);
+    if (descriptorKeys.some((key) => typeof key === 'symbol')) {
+      throw new TypeError(`${path} must not contain symbol-keyed properties`);
+    }
+    const lengthDescriptor = descriptorMap.length;
+    if (
+      !lengthDescriptor ||
+      !own(lengthDescriptor, 'value') ||
+      !Number.isSafeInteger(lengthDescriptor.value) ||
+      lengthDescriptor.value < 0
+    ) {
+      throw new TypeError(`${path} must be a plain JSON array`);
+    }
+    const length = lengthDescriptor.value as number;
+    const indexed: Array<[number, PropertyDescriptor]> = [];
+    for (const key of descriptorKeys) {
+      if (typeof key === 'symbol') continue;
+      if (key === 'length') continue;
+      const descriptor = descriptorMap[key];
+      if (!descriptor) continue;
+      const index = Number(key);
+      if (
+        !Number.isSafeInteger(index) ||
+        index < 0 ||
+        index >= length ||
+        String(index) !== key
+      ) {
+        throw new TypeError(`${path}.${key} is not a JSON array index`);
+      }
+      indexed.push([index, descriptor]);
+    }
+    if (indexed.length !== length) {
+      throw new TypeError(`${path} must not be a sparse JSON array`);
+    }
+    indexed.sort(([left], [right]) => left - right);
+    const copy: JsonValue[] = [];
+    for (const [index, descriptor] of indexed) {
+      if (!descriptor.enumerable) {
+        throw new TypeError(
+          `${path}[${index}] must be an enumerable JSON property`,
+        );
+      }
+      if (!own(descriptor, 'value')) {
+        throw new TypeError(`${path}[${index}] must be a JSON data property`);
+      }
+      copy.push(
+        snapshotJsonValueFromDescriptors(
+          descriptor.value,
+          `${path}[${index}]`,
+          nextAncestors,
+        ),
+      );
+    }
+    return Object.freeze(copy);
+  }
+  if (!isRecord(value)) {
+    throw new TypeError(`${path} must be a JSON value`);
+  }
+  if (ancestors.has(value)) {
+    throw new TypeError(`${path} must not contain a JSON cycle`);
+  }
+  const descriptors = Object.getOwnPropertyDescriptors(value);
+  const descriptorKeys = Reflect.ownKeys(descriptors);
+  if (descriptorKeys.some((key) => typeof key === 'symbol')) {
+    throw new TypeError(`${path} must not contain symbol-keyed properties`);
+  }
+  const nextAncestors = new Set(ancestors).add(value);
+  const copy: Record<string, JsonValue> = {};
+  for (const key of descriptorKeys) {
+    if (typeof key === 'symbol') continue;
+    const descriptor = descriptors[key];
+    if (!descriptor) continue;
+    if (!descriptor.enumerable) {
+      throw new TypeError(`${path}.${key} must be an enumerable JSON property`);
+    }
+    if (!own(descriptor, 'value')) {
+      throw new TypeError(`${path}.${key} must be a JSON data property`);
+    }
+    defineEnumerableDataProperty(
+      copy,
+      key,
+      snapshotJsonValueFromDescriptors(
+        descriptor.value,
+        `${path}.${key}`,
+        nextAncestors,
+      ),
+    );
+  }
+  return Object.freeze(copy);
+}
+
+/** Reject values that would be changed, omitted, or rejected by JSON. */
+export function assertJsonSafe(
+  value: unknown,
+  path = '$',
+  ancestors: ReadonlySet<object> = new Set(),
+): asserts value is JsonValue {
+  snapshotJsonValueFromDescriptors(value, path, ancestors);
+}
+
+function defineEnumerableDataProperty<T>(
+  target: Record<string, T>,
+  key: string,
+  value: T,
+): void {
+  // Assignment to Object.prototype's legacy `__proto__` setter changes a
+  // clone's prototype and silently drops the JSON member. Defining an own data
+  // property preserves every valid JSON key while retaining an ordinary object
+  // prototype for callers.
+  Object.defineProperty(target, key, {
+    value,
+    enumerable: true,
+    configurable: true,
+    writable: true,
+  });
+}
+
+/** Validate, detach, and recursively freeze host-owned JSON input. */
+export function snapshotJsonValue(value: unknown, path = '$'): JsonValue {
+  return snapshotJsonValueFromDescriptors(value, path);
+}
+
+function capturedDataValue(
+  descriptors: PropertyDescriptorMap,
+  key: string,
+  path: string,
+  required = true,
+): unknown {
+  const descriptor = descriptors[key];
+  if (!descriptor) {
+    if (required) throw new TypeError(`${path} must be an own data property`);
+    return undefined;
+  }
+  if (!own(descriptor, 'value')) {
+    throw new TypeError(`${path} must be an own data property`);
+  }
+  return descriptor.value;
+}
+
+function capturedPort<K extends keyof PlaybookSession['ports']>(
+  descriptors: PropertyDescriptorMap,
+  name: K,
+): PlaybookSession['ports'][K] {
+  const value = capturedDataValue(
+    descriptors,
+    name,
+    `playbook session ports.${name}`,
+  );
+  if (typeof value !== 'function') {
+    throw new TypeError(`playbook session ports.${name} must be a function`);
+  }
+  return value as PlaybookSession['ports'][K];
+}
+
+/** Validate session causality and detach its immutable identity from the host. */
+export function snapshotPlaybookSession(
+  session: PlaybookSession,
+): PlaybookSession {
+  if (!isRecord(session)) {
+    throw new TypeError('playbook session must be an object');
+  }
+  const sessionDescriptors = Object.getOwnPropertyDescriptors(session);
+  const sessionId = requireNonEmptyString(
+    capturedDataValue(
+      sessionDescriptors,
+      'sessionId',
+      'playbook session sessionId',
+    ),
+    'playbook session sessionId',
+  );
+  const playbookId = requireNonEmptyString(
+    capturedDataValue(
+      sessionDescriptors,
+      'playbookId',
+      'playbook session playbookId',
+    ),
+    'playbook session playbookId',
+  );
+  const rootSessionId = requireNonEmptyString(
+    capturedDataValue(
+      sessionDescriptors,
+      'rootSessionId',
+      'playbook session rootSessionId',
+    ),
+    'playbook session rootSessionId',
+  );
+  const capturedDepth = capturedDataValue(
+    sessionDescriptors,
+    'depth',
+    'playbook session depth',
+  );
+  if (!Number.isSafeInteger(capturedDepth) || (capturedDepth as number) < 0) {
+    throw new TypeError(
+      'playbook session depth must be a non-negative integer',
+    );
+  }
+  const depth = capturedDepth as number;
+  const capturedParentSessionId = capturedDataValue(
+    sessionDescriptors,
+    'parentSessionId',
+    'playbook session parentSessionId',
+    false,
+  );
+  const capturedParentCallId = capturedDataValue(
+    sessionDescriptors,
+    'parentCallId',
+    'playbook session parentCallId',
+    false,
+  );
+  const hasParentSessionId = Object.prototype.hasOwnProperty.call(
+    sessionDescriptors,
+    'parentSessionId',
+  );
+  const hasParentCallId = Object.prototype.hasOwnProperty.call(
+    sessionDescriptors,
+    'parentCallId',
+  );
+  let parentSessionId: string | undefined;
+  let parentCallId: string | undefined;
+  if (depth === 0) {
+    if (rootSessionId !== sessionId) {
+      throw new TypeError(
+        'root playbook session must be its own rootSessionId',
+      );
+    }
+    if (hasParentSessionId || hasParentCallId) {
+      throw new TypeError(
+        'root playbook session must not carry parent identity',
+      );
+    }
+  } else {
+    parentSessionId = requireNonEmptyString(
+      capturedParentSessionId,
+      'playbook session parentSessionId',
+    );
+    parentCallId = requireNonEmptyString(
+      capturedParentCallId,
+      'playbook session parentCallId',
+    );
+    if (sessionId === rootSessionId || sessionId === parentSessionId) {
+      throw new TypeError(
+        'child playbook sessionId must differ from its root and parent session ids',
+      );
+    }
+  }
+  const capturedPorts = capturedDataValue(
+    sessionDescriptors,
+    'ports',
+    'playbook session ports',
+  );
+  if (!isRecord(capturedPorts)) {
+    throw new TypeError('playbook session ports must be an object');
+  }
+  const portDescriptors = Object.getOwnPropertyDescriptors(capturedPorts);
+  const ports: PlaybookSession['ports'] = Object.freeze({
+    callPlayer: capturedPort(portDescriptors, 'callPlayer'),
+    callCaptain: capturedPort(portDescriptors, 'callCaptain'),
+    callJudge: capturedPort(portDescriptors, 'callJudge'),
+    callPlaybook: capturedPort(portDescriptors, 'callPlaybook'),
+    emitStatus: capturedPort(portDescriptors, 'emitStatus'),
+    emitTelemetry: capturedPort(portDescriptors, 'emitTelemetry'),
+  });
+  return Object.freeze({
+    sessionId,
+    playbookId,
+    rootSessionId,
+    ...(parentSessionId === undefined ? {} : { parentSessionId }),
+    ...(parentCallId === undefined ? {} : { parentCallId }),
+    depth,
+    ports,
+  });
+}
+
+export function normalizeError(error: unknown): NormalizedError {
+  if (error instanceof Error) {
+    let name = 'Error';
+    let message = 'Unknown error';
+    let stack: string | undefined;
+    try {
+      if (typeof error.name === 'string' && error.name.length > 0) {
+        name = error.name;
+      }
+    } catch {
+      // Keep the stable fallback for hostile Error subclasses.
+    }
+    try {
+      if (typeof error.message === 'string') message = error.message;
+    } catch {
+      // Keep the stable fallback for hostile Error subclasses.
+    }
+    try {
+      if (typeof error.stack === 'string') stack = error.stack;
+    } catch {
+      // A stack is optional at the public boundary.
+    }
+    return {
+      name,
+      message,
+      ...(stack ? { stack } : {}),
+    };
+  }
+  if (typeof error === 'string') {
+    return { name: 'Error', message: error };
+  }
+  try {
+    assertJsonSafe(error);
+    if (isRecord(error) && typeof error.message === 'string') {
+      return {
+        name:
+          typeof error.name === 'string' && error.name.length > 0
+            ? error.name
+            : 'Error',
+        message: error.message,
+        ...(typeof error.stack === 'string' ? { stack: error.stack } : {}),
+      };
+    }
+    return { name: 'Error', message: JSON.stringify(error) };
+  } catch {
+    try {
+      return { name: 'Error', message: String(error) };
+    } catch {
+      return { name: 'Error', message: 'Unknown error' };
+    }
+  }
+}
+
+function requireNonEmptyString(value: unknown, path: string): string {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new TypeError(`${path} must be a non-empty string`);
+  }
+  return value;
+}
+
+function normalizeStateValue(
+  value: unknown,
+  path = 'snapshot.value',
+  ancestors: ReadonlySet<object> = new Set(),
+): PlaybookStateValue {
+  if (typeof value === 'string') return value;
+  if (!isRecord(value)) {
+    throw new TypeError(`${path} must be an XState string or object value`);
+  }
+  if (ancestors.has(value)) {
+    throw new TypeError(`${path} must not contain an XState state cycle`);
+  }
+  const nextAncestors = new Set(ancestors).add(value);
+  const normalized: Record<string, PlaybookStateValue> = {};
+  for (const key of Object.keys(value).sort()) {
+    defineEnumerableDataProperty(
+      normalized,
+      key,
+      normalizeStateValue(value[key], `${path}.${key}`, nextAncestors),
+    );
+  }
+  return normalized;
+}
+
+export interface PlaybookStateMetadata {
+  stateId: string;
+  description: string;
+}
+
+interface MachineSnapshotLike {
+  value: unknown;
+  status: 'active' | 'done' | 'error' | 'stopped';
+  tags: ReadonlySet<string>;
+  getMeta(): Record<string, unknown>;
+}
+
+function asMachineSnapshot(snapshot: unknown): MachineSnapshotLike {
+  if (!isRecord(snapshot)) {
+    throw new TypeError('snapshot must be an XState machine snapshot');
+  }
+  const status = snapshot.status;
+  if (
+    status !== 'active' &&
+    status !== 'done' &&
+    status !== 'error' &&
+    status !== 'stopped'
+  ) {
+    throw new TypeError('snapshot.status is not an XState actor status');
+  }
+  if (!(snapshot.tags instanceof Set)) {
+    throw new TypeError('snapshot.tags must be an XState tag set');
+  }
+  if (typeof snapshot.getMeta !== 'function') {
+    throw new TypeError('snapshot.getMeta must be an XState public method');
+  }
+  return snapshot as unknown as MachineSnapshotLike;
+}
+
+/** Read stable state identity without consulting XState's private `_nodes`. */
+export function activePlaybookStateMetadata(
+  snapshot: unknown,
+): readonly PlaybookStateMetadata[] {
+  const machineSnapshot = asMachineSnapshot(snapshot);
+  const byStateId = new Map<string, PlaybookStateMetadata>();
+  for (const [nodeId, meta] of Object.entries(machineSnapshot.getMeta())) {
+    if (!isRecord(meta) || !own(meta, 'playbook')) continue;
+    if (!isRecord(meta.playbook)) {
+      throw new TypeError(`${nodeId}.meta.playbook must be an object`);
+    }
+    const stateId = requireNonEmptyString(
+      meta.playbook.stateId,
+      `${nodeId}.meta.playbook.stateId`,
+    );
+    const description = requireNonEmptyString(
+      meta.playbook.description,
+      `${nodeId}.meta.playbook.description`,
+    );
+    const previous = byStateId.get(stateId);
+    if (previous && previous.description !== description) {
+      throw new TypeError(
+        `active state id ${stateId} has conflicting descriptions`,
+      );
+    }
+    byStateId.set(stateId, { stateId, description });
+  }
+  return [...byStateId.values()].sort((left, right) =>
+    left.stateId.localeCompare(right.stateId),
+  );
+}
+
+export interface SnapshotNormalizationOptions {
+  pendingCall?: PlaybookPendingCall;
+}
+
+export function normalizePlaybookSnapshot(
+  snapshot: unknown,
+  options: SnapshotNormalizationOptions = {},
+): PlaybookState {
+  const machineSnapshot = asMachineSnapshot(snapshot);
+  const active = activePlaybookStateMetadata(machineSnapshot);
+  const activeStateIds = active.map(({ stateId }) => stateId);
+  const tags = [...machineSnapshot.tags].sort();
+  const busy = tags.includes(BUSY_TAG);
+  const suspended = tags.includes(SUSPENDED_TAG);
+  const quiescent =
+    machineSnapshot.status !== 'active' ||
+    (!busy && (!suspended || options.pendingCall !== undefined));
+  return {
+    value: normalizeStateValue(machineSnapshot.value),
+    activeStateIds,
+    tags,
+    status: machineSnapshot.status,
+    quiescent,
+    ...(activeStateIds.length === 1 ? { stateId: activeStateIds[0] } : {}),
+  };
+}
+
+// DR-014 §1: deep-detach an XState persisted actor snapshot into strict
+// JSON for a PlaybookRuntimeSnapshot, normalizing any raw Error value
+// (for example FSM context `lastError`) instead of rejecting it.
+export function detachPersistedMachineSnapshot(persisted: unknown): JsonValue {
+  return snapshotJsonValue(
+    withErrorsNormalized(persisted, new Set()),
+    'persisted machine snapshot',
+  );
+}
+
+function withErrorsNormalized(
+  value: unknown,
+  ancestors: ReadonlySet<object>,
+): unknown {
+  if (value instanceof Error) return normalizeError(value);
+  if (Array.isArray(value)) {
+    if (ancestors.has(value)) return value;
+    const nextAncestors = new Set(ancestors).add(value);
+    return value.map((entry) => withErrorsNormalized(entry, nextAncestors));
+  }
+  if (isRecord(value)) {
+    if (ancestors.has(value)) return value;
+    const nextAncestors = new Set(ancestors).add(value);
+    const normalized: Record<string, unknown> = {};
+    for (const key of Object.keys(value)) {
+      // XState persisted snapshots carry `output: undefined` (and similar)
+      // on non-final states; JSON serialization drops those members, so the
+      // detached snapshot drops them too instead of rejecting.
+      if (value[key] === undefined) continue;
+      defineEnumerableDataProperty(
+        normalized,
+        key,
+        withErrorsNormalized(value[key], nextAncestors),
+      );
+    }
+    return normalized;
+  }
+  return value;
+}
+
+const SNAPSHOT_SEQUENCE_KEYS = [
+  'trace',
+  'turn',
+  'judgeCall',
+  'playerCall',
+  'playbookCall',
+] as const;
+
+// DR-014 §1: validate and detach a host-supplied runtime snapshot before
+// restore touches any state. Rejects a schema-version or playbook-id
+// mismatch with a path-named error.
+export function assertPlaybookRuntimeSnapshot(
+  value: unknown,
+  expectedPlaybookId: string,
+): PlaybookRuntimeSnapshot {
+  if (!isRecord(value)) {
+    throw new TypeError('runtime snapshot must be an object');
+  }
+  if (value.schemaVersion !== 1) {
+    throw new TypeError(
+      `runtime snapshot schemaVersion ${String(value.schemaVersion)} is not supported (expected 1)`,
+    );
+  }
+  const playbookId = requireNonEmptyString(
+    value.playbookId,
+    'runtime snapshot playbookId',
+  );
+  if (playbookId !== expectedPlaybookId) {
+    throw new TypeError(
+      `runtime snapshot playbookId ${playbookId} does not match runtime playbook ${expectedPlaybookId}`,
+    );
+  }
+  if (!isRecord(value.machine)) {
+    throw new TypeError('runtime snapshot machine must be an object');
+  }
+  const machine = snapshotJsonValue(value.machine, 'runtime snapshot machine');
+  if (!isRecord(value.playerResumeTokens)) {
+    throw new TypeError(
+      'runtime snapshot playerResumeTokens must be an object',
+    );
+  }
+  const playerResumeTokens: Record<string, string> = {};
+  for (const [playerId, token] of Object.entries(value.playerResumeTokens)) {
+    defineEnumerableDataProperty(
+      playerResumeTokens,
+      playerId,
+      requireNonEmptyString(
+        token,
+        `runtime snapshot playerResumeTokens.${playerId}`,
+      ),
+    );
+  }
+  if (!isRecord(value.sequences)) {
+    throw new TypeError('runtime snapshot sequences must be an object');
+  }
+  const sequences = {} as PlaybookRuntimeSnapshot['sequences'];
+  for (const key of SNAPSHOT_SEQUENCE_KEYS) {
+    const sequence = value.sequences[key];
+    if (!Number.isSafeInteger(sequence) || (sequence as number) < 0) {
+      throw new TypeError(
+        `runtime snapshot sequences.${key} must be a non-negative integer`,
+      );
+    }
+    sequences[key] = sequence as number;
+  }
+  const captainCall = value.sequences.captainCall;
+  if (captainCall !== undefined) {
+    if (!Number.isSafeInteger(captainCall) || (captainCall as number) < 0) {
+      throw new TypeError(
+        'runtime snapshot sequences.captainCall must be a non-negative integer',
+      );
+    }
+    sequences.captainCall = captainCall as number;
+  }
+  validateState(value.state, 'runtime snapshot state');
+  const state = snapshotJsonValue(
+    value.state,
+    'runtime snapshot state',
+  ) as unknown as PlaybookState;
+  if (!Array.isArray(value.pendingBossQuestions)) {
+    throw new TypeError(
+      'runtime snapshot pendingBossQuestions must be an array',
+    );
+  }
+  const pendingBossQuestions = value.pendingBossQuestions.map(
+    (entry, index) => {
+      const path = `runtime snapshot pendingBossQuestions[${index}]`;
+      if (!isRecord(entry)) throw new TypeError(`${path} must be an object`);
+      const question: PlaybookPendingBossQuestion = {
+        questionId: requireNonEmptyString(
+          entry.questionId,
+          `${path}.questionId`,
+        ),
+        player: requireNonEmptyString(entry.player, `${path}.player`),
+        question: requireNonEmptyString(entry.question, `${path}.question`),
+        ...(entry.sourceItem === undefined
+          ? {}
+          : {
+              sourceItem: requireNonEmptyString(
+                entry.sourceItem,
+                `${path}.sourceItem`,
+              ),
+            }),
+      };
+      return Object.freeze(question);
+    },
+  );
+  return Object.freeze({
+    schemaVersion: 1,
+    playbookId,
+    machine,
+    playerResumeTokens: Object.freeze(playerResumeTokens),
+    sequences: Object.freeze(sequences),
+    state,
+    pendingBossQuestions: Object.freeze(pendingBossQuestions),
+  });
+}
+
+export interface NestedPlaybookInput {
+  stateId: string;
+  playbookId: string;
+  text: string;
+}
+
+export interface PlaybookCallStarted {
+  callId: string;
+  stateId: string;
+  playbookId: string;
+  text: string;
+}
+
+export interface PlaybookCallFinished extends PlaybookCallStarted {
+  result: PlaybookCallResult;
+}
+
+export interface NestedPlaybookBridgeOptions {
+  nextCallId(): string;
+  /** Active public runtime boundary whose abort also owns a new child call. */
+  getBoundarySignal?(): AbortSignal | undefined;
+  callPlaybook(
+    request: PlaybookCallRequest,
+    signal: AbortSignal,
+  ): Promise<PlaybookCallStart>;
+  emitStarted(event: PlaybookCallStarted): Promise<void>;
+  emitFinished(event: PlaybookCallFinished): Promise<void>;
+  drain(): Promise<void>;
+  bindResumeSignal?(signal: AbortSignal): void;
+  onControlPlaneError?(error: unknown): void;
+  onBackgroundError?(error: unknown): void;
+}
+
+export class NestedPlaybookCallError extends Error {
+  readonly result: PlaybookCallResult;
+
+  constructor(result: PlaybookCallResult) {
+    const fallback = `Child playbook ${result.playbookId} ${result.status}`;
+    const normalized = result.status === 'ok' ? undefined : result.error;
+    super(normalized?.message ?? fallback);
+    this.name = normalized?.name ?? 'NestedPlaybookCallError';
+    if (normalized?.stack) this.stack = normalized.stack;
+    this.result = result;
+  }
+}
+
+interface ActiveCall {
+  readonly callId: string;
+  readonly input: NestedPlaybookInput;
+  readonly deferred: Deferred<JsonValue | undefined>;
+  readonly finished: Deferred<void>;
+  readonly controller: AbortController;
+  readonly signal: AbortSignal;
+  phase: 'starting' | 'suspended' | 'settling';
+  childSessionId?: string;
+  abortListener?: () => void;
+  settlement?: Promise<void>;
+  runError?: unknown;
+}
+
+export interface PendingCallObserver {
+  getPendingCall(): PlaybookPendingCall | undefined;
+  subscribePendingCall(
+    listener: (pendingCall: PlaybookPendingCall) => void,
+  ): () => void;
+}
+
+export interface NestedPlaybookBridge<
+  TInput extends NestedPlaybookInput = NestedPlaybookInput,
+> extends PendingCallObserver {
+  actorLogic: PromiseActorLogic<JsonValue | undefined, TInput>;
+  resume(input: {
+    callId: string;
+    result: PlaybookCallResult;
+    signal: AbortSignal;
+  }): Promise<void>;
+  abortPending(error?: unknown): Promise<void>;
+  dispose(): Promise<void>;
+}
+
+function validateState(state: unknown, path: string): void {
+  if (!isRecord(state)) throw new TypeError(`${path} must be an object`);
+  rejectUnknownKeys(
+    state,
+    ['value', 'activeStateIds', 'tags', 'status', 'quiescent', 'stateId'],
+    path,
+  );
+  normalizeStateValue(state.value, `${path}.value`);
+  if (!Array.isArray(state.activeStateIds)) {
+    throw new TypeError(`${path}.activeStateIds must be an array`);
+  }
+  state.activeStateIds.forEach((value, index) => {
+    requireNonEmptyString(value, `${path}.activeStateIds[${index}]`);
+  });
+  if (new Set(state.activeStateIds).size !== state.activeStateIds.length) {
+    throw new TypeError(`${path}.activeStateIds must not contain duplicates`);
+  }
+  if (
+    !Array.isArray(state.tags) ||
+    !state.tags.every((tag) => typeof tag === 'string' && tag.trim().length > 0)
+  ) {
+    throw new TypeError(`${path}.tags must be a non-empty string array`);
+  }
+  if (new Set(state.tags).size !== state.tags.length) {
+    throw new TypeError(`${path}.tags must not contain duplicates`);
+  }
+  if (
+    state.status !== 'active' &&
+    state.status !== 'done' &&
+    state.status !== 'error' &&
+    state.status !== 'stopped'
+  ) {
+    throw new TypeError(`${path}.status is invalid`);
+  }
+  if (typeof state.quiescent !== 'boolean') {
+    throw new TypeError(`${path}.quiescent must be boolean`);
+  }
+  if (own(state, 'stateId')) {
+    const stateId = requireNonEmptyString(state.stateId, `${path}.stateId`);
+    if (
+      state.activeStateIds.length !== 1 ||
+      state.activeStateIds[0] !== stateId
+    ) {
+      throw new TypeError(
+        `${path}.stateId must equal the sole active state id`,
+      );
+    }
+  }
+}
+
+function rejectUnknownKeys(
+  value: Record<string, unknown>,
+  allowed: readonly string[],
+  path: string,
+): void {
+  const allowedKeys = new Set(allowed);
+  for (const key of Object.keys(value)) {
+    if (!allowedKeys.has(key)) {
+      throw new TypeError(`${path}.${key} is not a declared property`);
+    }
+  }
+}
+
+function validateRunStatus(
+  status: unknown,
+  path: string,
+): asserts status is 'ok' | 'aborted' | 'error' {
+  if (status !== 'ok' && status !== 'aborted' && status !== 'error') {
+    throw new TypeError(`${path} is invalid`);
+  }
+}
+
+function validateOptionalString(
+  value: Record<string, unknown>,
+  key: string,
+  path: string,
+): void {
+  if (own(value, key) && typeof value[key] !== 'string') {
+    throw new TypeError(`${path}.${key} must be a string`);
+  }
+}
+
+/** Validate, detach, and freeze a host direct-Captain result. */
+export function validateCaptainResult(
+  value: unknown,
+  path = 'Captain result',
+): CaptainResult {
+  const result = snapshotJsonValue(value, path);
+  if (!isRecord(result)) {
+    throw new TypeError(`${path} must be an object`);
+  }
+  rejectUnknownKeys(result, ['status', 'finalText', 'error'], path);
+  validateRunStatus(result.status, `${path}.status`);
+  validateOptionalString(result, 'finalText', path);
+  validateOptionalString(result, 'error', path);
+  return result as unknown as CaptainResult;
+}
+
+/** Validate, detach, and freeze a host delegated-player result. */
+export function validatePlayerResult(
+  value: unknown,
+  path = 'player result',
+): PlayerResult {
+  const result = snapshotJsonValue(value, path);
+  if (!isRecord(result)) {
+    throw new TypeError(`${path} must be an object`);
+  }
+  rejectUnknownKeys(
+    result,
+    ['status', 'resumeToken', 'finalText', 'error'],
+    path,
+  );
+  validateRunStatus(result.status, `${path}.status`);
+  validateOptionalString(result, 'resumeToken', path);
+  validateOptionalString(result, 'finalText', path);
+  validateOptionalString(result, 'error', path);
+  return result as unknown as PlayerResult;
+}
+
+function validateNormalizedError(error: unknown, path: string): void {
+  if (!isRecord(error)) {
+    throw new TypeError(`${path} must be a normalized error`);
+  }
+  rejectUnknownKeys(error, ['name', 'message', 'stack'], path);
+  requireNonEmptyString(error.name, `${path}.name`);
+  if (typeof error.message !== 'string') {
+    throw new TypeError(`${path}.message must be a string`);
+  }
+  if (error.stack !== undefined && typeof error.stack !== 'string') {
+    throw new TypeError(`${path}.stack must be a string`);
+  }
+}
+
+export function validatePlaybookCallResult(
+  result: unknown,
+  expectedPlaybookId: string,
+  expectedChildSessionId?: string,
+): PlaybookCallResult {
+  const capturedResult = snapshotJsonValue(result, 'playbook result');
+  if (!isRecord(capturedResult)) {
+    throw new TypeError('playbook result must be an object');
+  }
+  if (
+    capturedResult.status !== 'ok' &&
+    capturedResult.status !== 'aborted' &&
+    capturedResult.status !== 'error'
+  ) {
+    throw new TypeError('playbook result status is invalid');
+  }
+  if (capturedResult.playbookId !== expectedPlaybookId) {
+    throw new PlaybookCallIdentityError(
+      `playbook result target ${String(capturedResult.playbookId)} does not match ${expectedPlaybookId}`,
+    );
+  }
+  if (capturedResult.status === 'ok') {
+    rejectUnknownKeys(
+      capturedResult,
+      ['status', 'playbookId', 'childSessionId', 'state', 'output'],
+      'playbook result',
+    );
+    requireNonEmptyString(
+      capturedResult.childSessionId,
+      'playbook result childSessionId',
+    );
+  } else {
+    rejectUnknownKeys(
+      capturedResult,
+      ['status', 'playbookId', 'childSessionId', 'state', 'error'],
+      'playbook result',
+    );
+  }
+  if (capturedResult.status !== 'ok' && own(capturedResult, 'childSessionId')) {
+    requireNonEmptyString(
+      capturedResult.childSessionId,
+      'playbook result childSessionId',
+    );
+  }
+  if (
+    expectedChildSessionId !== undefined &&
+    capturedResult.childSessionId !== expectedChildSessionId
+  ) {
+    throw new PlaybookCallIdentityError(
+      `playbook result child session ${String(capturedResult.childSessionId)} does not match ${expectedChildSessionId}`,
+    );
+  }
+  if (own(capturedResult, 'state'))
+    validateState(capturedResult.state, 'playbook result state');
+  if (capturedResult.status === 'error' && !own(capturedResult, 'error')) {
+    throw new TypeError('playbook error result requires a normalized error');
+  }
+  if (capturedResult.status !== 'ok' && capturedResult.error !== undefined) {
+    validateNormalizedError(capturedResult.error, 'playbook result error');
+  }
+  return capturedResult as unknown as PlaybookCallResult;
+}
+
+class PlaybookCallIdentityError extends TypeError {}
+
+export function validatePlaybookCallStart(
+  start: unknown,
+  expectedPlaybookId: string,
+): PlaybookCallStart {
+  const capturedStart = snapshotJsonValue(start, 'playbook call start');
+  if (!isRecord(capturedStart)) {
+    throw new TypeError('playbook call start must be an object');
+  }
+  if (capturedStart.state === 'settled') {
+    rejectUnknownKeys(
+      capturedStart,
+      ['state', 'result'],
+      'playbook call start',
+    );
+    return Object.freeze({
+      state: 'settled',
+      result: validatePlaybookCallResult(
+        capturedStart.result,
+        expectedPlaybookId,
+      ),
+    });
+  }
+  if (capturedStart.state === 'suspended') {
+    rejectUnknownKeys(
+      capturedStart,
+      ['state', 'childSessionId'],
+      'playbook call start',
+    );
+    const childSessionId = requireNonEmptyString(
+      capturedStart.childSessionId,
+      'playbook call start childSessionId',
+    );
+    return Object.freeze({
+      state: 'suspended',
+      childSessionId,
+    });
+  }
+  throw new TypeError('playbook call start state is invalid');
+}
+
+function assignedChildSessionId(start: unknown): string | undefined {
+  if (!isRecord(start)) return undefined;
+  try {
+    const startDescriptors = Object.getOwnPropertyDescriptors(start);
+    const state = capturedDataValue(
+      startDescriptors,
+      'state',
+      'playbook call start state',
+      false,
+    );
+    if (state === 'suspended') {
+      const childSessionId = capturedDataValue(
+        startDescriptors,
+        'childSessionId',
+        'playbook call start childSessionId',
+        false,
+      );
+      return typeof childSessionId === 'string' &&
+        childSessionId.trim().length > 0
+        ? childSessionId
+        : undefined;
+    }
+    if (state !== 'settled') return undefined;
+    const result = capturedDataValue(
+      startDescriptors,
+      'result',
+      'playbook call start result',
+      false,
+    );
+    if (!isRecord(result)) return undefined;
+    const resultDescriptors = Object.getOwnPropertyDescriptors(result);
+    const childSessionId = capturedDataValue(
+      resultDescriptors,
+      'childSessionId',
+      'playbook result childSessionId',
+      false,
+    );
+    return typeof childSessionId === 'string' &&
+      childSessionId.trim().length > 0
+      ? childSessionId
+      : undefined;
+  } catch {
+    // Cleanup identity is best effort for malformed or accessor-backed input.
+    return undefined;
+  }
+}
+
+function resultFromThrown(
+  playbookId: string,
+  childSessionId: string | undefined,
+  error: unknown,
+  aborted: boolean,
+): PlaybookCallResult {
+  const normalized = normalizeError(error);
+  const result: PlaybookCallResult = aborted
+    ? {
+        status: 'aborted',
+        playbookId,
+        ...(childSessionId ? { childSessionId } : {}),
+        error: normalized,
+      }
+    : {
+        status: 'error',
+        playbookId,
+        ...(childSessionId ? { childSessionId } : {}),
+        error: normalized,
+      };
+  return snapshotJsonValue(
+    result,
+    'playbook result',
+  ) as unknown as PlaybookCallResult;
+}
+
+function outputOrThrow(result: PlaybookCallResult): JsonValue | undefined {
+  if (result.status === 'ok') return result.output;
+  throw new NestedPlaybookCallError(result);
+}
+
+export function createNestedPlaybookBridge<
+  TInput extends NestedPlaybookInput = NestedPlaybookInput,
+>(options: NestedPlaybookBridgeOptions): NestedPlaybookBridge<TInput> {
+  let current: ActiveCall | undefined;
+  let disposed = false;
+  const usedCallIds = new Set<string>();
+  const pendingListeners = new Set<
+    (pendingCall: PlaybookPendingCall) => void
+  >();
+
+  const reportBackgroundError = (error: unknown): void => {
+    try {
+      options.onBackgroundError?.(error);
+    } catch {
+      // Background observers are a terminal sink and cannot own cleanup.
+    }
+  };
+
+  const reportControlPlaneError = (error: unknown): void => {
+    try {
+      options.onControlPlaneError?.(error);
+    } catch (callbackError) {
+      // Observability callbacks must never prevent terminal cleanup of the
+      // invocation they are observing.
+      reportBackgroundError(callbackError);
+    }
+  };
+
+  const rejectControlPlane = (error: unknown): never => {
+    reportControlPlaneError(error);
+    throw error;
+  };
+
+  const pendingIdentity = (
+    active: ActiveCall | undefined,
+  ): PlaybookPendingCall | undefined =>
+    active?.phase === 'suspended' && active.childSessionId
+      ? {
+          callId: active.callId,
+          playbookId: active.input.playbookId,
+          childSessionId: active.childSessionId,
+        }
+      : undefined;
+
+  const clear = (active: ActiveCall): void => {
+    if (active.abortListener) {
+      active.signal.removeEventListener('abort', active.abortListener);
+    }
+    if (current === active) current = undefined;
+  };
+
+  const emitFinish = async (
+    active: ActiveCall,
+    result: PlaybookCallResult,
+  ): Promise<void> => {
+    await options.emitFinished({
+      callId: active.callId,
+      stateId: active.input.stateId,
+      playbookId: active.input.playbookId,
+      text: active.input.text,
+      result,
+    });
+    await options.drain();
+  };
+
+  const finishImmediate = async (
+    active: ActiveCall,
+    result: PlaybookCallResult,
+    controlError?: unknown,
+    resultAfterAbortCleanup?: () => PlaybookCallResult,
+  ): Promise<JsonValue | undefined> => {
+    let effectiveResult = result;
+    let cleanupControlError: unknown;
+    if (result.status === 'aborted' || active.signal.aborted) {
+      try {
+        await drainPlaybookAbortCleanups(active.signal);
+      } catch (error) {
+        cleanupControlError = error;
+        reportControlPlaneError(error);
+        effectiveResult = resultFromThrown(
+          active.input.playbookId,
+          active.childSessionId,
+          error,
+          false,
+        );
+      }
+      if (cleanupControlError === undefined && resultAfterAbortCleanup) {
+        effectiveResult = resultAfterAbortCleanup();
+      }
+    }
+    let finishControlError: unknown;
+    try {
+      await emitFinish(active, effectiveResult);
+    } catch (error) {
+      reportControlPlaneError(error);
+      finishControlError = error;
+    } finally {
+      // An immediate call can never be resumed. Even when its finish
+      // emission fails, do not leave a permanently unresumable call in the
+      // bridge and prevent disposal or a later invocation.
+      clear(active);
+    }
+    if (controlError !== undefined) throw controlError;
+    if (cleanupControlError !== undefined) throw cleanupControlError;
+    if (finishControlError !== undefined) throw finishControlError;
+    return outputOrThrow(effectiveResult);
+  };
+
+  const settlePending = async (
+    active: ActiveCall,
+    result: PlaybookCallResult,
+    controlError?: unknown,
+  ): Promise<void> => {
+    if (active.phase === 'settling' && active.settlement) {
+      await active.settlement;
+      return;
+    }
+    if (active.phase !== 'suspended') {
+      throw new Error(`playbook call ${active.callId} is not suspended`);
+    }
+    active.phase = 'settling';
+    const settlement = (async (): Promise<void> => {
+      let effectiveResult = result;
+      let cleanupControlError: unknown;
+      if (result.status === 'aborted' || active.signal.aborted) {
+        if (result.status !== 'aborted' && active.signal.aborted) {
+          effectiveResult = resultFromThrown(
+            active.input.playbookId,
+            active.childSessionId,
+            active.signal.reason ??
+              new Error('Nested playbook invocation aborted'),
+            true,
+          );
+        }
+        try {
+          await drainPlaybookAbortCleanups(active.signal);
+        } catch (cleanupError) {
+          cleanupControlError = cleanupError;
+          reportControlPlaneError(cleanupError);
+          effectiveResult = resultFromThrown(
+            active.input.playbookId,
+            active.childSessionId,
+            cleanupError,
+            false,
+          );
+        }
+      }
+      try {
+        await emitFinish(active, effectiveResult);
+      } catch (error) {
+        // A finish event is the durable return boundary. If it cannot be
+        // emitted and drained, the child result must not remain retryable:
+        // clear the identity and fail the promise actor so its parent takes
+        // onError instead of observing a phantom suspended child.
+        reportControlPlaneError(error);
+        clear(active);
+        active.deferred.reject(error);
+        throw error;
+      }
+      clear(active);
+      if (controlError !== undefined) {
+        active.deferred.reject(controlError);
+      } else if (cleanupControlError !== undefined) {
+        active.deferred.reject(cleanupControlError);
+      } else if (effectiveResult.status === 'ok') {
+        active.deferred.resolve(effectiveResult.output);
+      } else {
+        active.deferred.reject(new NestedPlaybookCallError(effectiveResult));
+      }
+      if (cleanupControlError !== undefined) throw cleanupControlError;
+    })();
+    active.settlement = settlement;
+    try {
+      await settlement;
+    } catch (error) {
+      await active.finished.promise;
+      throw error;
+    }
+  };
+
+  const actorLogic = fromPromise<JsonValue | undefined, TInput>(
+    async ({ input, signal: invocationSignal }) => {
+      if (disposed) {
+        rejectControlPlane(new Error('nested playbook bridge is disposed'));
+      }
+      if (current) {
+        rejectControlPlane(
+          new Error(`playbook call ${current.callId} is already outstanding`),
+        );
+      }
+      const [normalizedInput, callId] = (() => {
+        try {
+          return [
+            {
+              stateId: requireNonEmptyString(
+                input.stateId,
+                'playbook input stateId',
+              ),
+              playbookId: requireNonEmptyString(
+                input.playbookId,
+                'playbook input playbookId',
+              ),
+              text: requireNonEmptyString(input.text, 'playbook input text'),
+            },
+            requireNonEmptyString(
+              options.nextCallId(),
+              'allocated playbook call id',
+            ),
+          ] as const;
+        } catch (error) {
+          return rejectControlPlane(error);
+        }
+      })();
+      if (usedCallIds.has(callId)) {
+        rejectControlPlane(
+          new Error(`allocated duplicate playbook call id ${callId}`),
+        );
+      }
+      usedCallIds.add(callId);
+      const controller = new AbortController();
+      let callSignal: AbortSignal;
+      try {
+        callSignal = combineAbortSignals(
+          invocationSignal,
+          options.getBoundarySignal?.(),
+          controller.signal,
+        );
+      } catch (error) {
+        return rejectControlPlane(error);
+      }
+      const active: ActiveCall = {
+        callId,
+        input: normalizedInput,
+        deferred: deferred<JsonValue | undefined>(),
+        finished: deferred<void>(),
+        controller,
+        signal: callSignal,
+        phase: 'starting',
+      };
+      current = active;
+
+      try {
+        // Promise actors may begin before XState publishes the root snapshot
+        // for their entering state. Yield through the runtime's global queue so
+        // that transition/status telemetry is enqueued before call.started.
+        try {
+          await options.drain();
+        } catch (error) {
+          reportControlPlaneError(error);
+          clear(active);
+          throw error;
+        }
+        try {
+          await options.emitStarted({ callId, ...normalizedInput });
+        } catch (error) {
+          reportControlPlaneError(error);
+          return await finishImmediate(
+            active,
+            resultFromThrown(
+              normalizedInput.playbookId,
+              undefined,
+              error,
+              false,
+            ),
+            error,
+          );
+        }
+        try {
+          await options.drain();
+        } catch (error) {
+          reportControlPlaneError(error);
+          return await finishImmediate(
+            active,
+            resultFromThrown(
+              normalizedInput.playbookId,
+              undefined,
+              error,
+              false,
+            ),
+            error,
+          );
+        }
+
+        const request: PlaybookCallRequest = {
+          callId,
+          playbookId: normalizedInput.playbookId,
+          text: normalizedInput.text,
+        };
+        let rawStart: unknown;
+        let observedStart: unknown;
+        let startSettled = false;
+        let removeOpeningAbortListener = (): void => undefined;
+        try {
+          if (active.signal.aborted) throw active.signal.reason;
+          const starting = options.callPlaybook(request, active.signal).then(
+            (value) => {
+              observedStart = value;
+              startSettled = true;
+              return value;
+            },
+            (error: unknown) => {
+              startSettled = true;
+              throw error;
+            },
+          );
+          const openingCleanup = starting.then(
+            () => undefined,
+            (error: unknown) => {
+              if (isAbortReason(error, active.signal)) return;
+              throw error;
+            },
+          );
+          void openingCleanup.catch(() => undefined);
+          const registerOpeningCleanup = (): void =>
+            registerPlaybookAbortCleanup(active.signal, openingCleanup);
+          removeOpeningAbortListener = (): void =>
+            active.signal.removeEventListener('abort', registerOpeningCleanup);
+          if (active.signal.aborted) registerOpeningCleanup();
+          else {
+            active.signal.addEventListener('abort', registerOpeningCleanup, {
+              once: true,
+            });
+          }
+          rawStart = await withAbort(starting, active.signal);
+        } catch (error) {
+          const controlError = active.signal.aborted ? undefined : error;
+          if (controlError !== undefined) reportControlPlaneError(controlError);
+          const result = resultFromThrown(
+            normalizedInput.playbookId,
+            undefined,
+            error,
+            active.signal.aborted,
+          );
+          return await finishImmediate(
+            active,
+            result,
+            controlError,
+            active.signal.aborted
+              ? () =>
+                  resultFromThrown(
+                    normalizedInput.playbookId,
+                    startSettled
+                      ? assignedChildSessionId(observedStart)
+                      : undefined,
+                    error,
+                    true,
+                  )
+              : undefined,
+          );
+        } finally {
+          removeOpeningAbortListener();
+        }
+
+        let start: PlaybookCallStart;
+        try {
+          start = validatePlaybookCallStart(
+            rawStart,
+            normalizedInput.playbookId,
+          );
+        } catch (error) {
+          reportControlPlaneError(error);
+          const childSessionId = assignedChildSessionId(rawStart);
+          active.childSessionId = childSessionId;
+          if (
+            isRecord(rawStart) &&
+            rawStart.state === 'suspended' &&
+            !active.controller.signal.aborted
+          ) {
+            // The host may already have opened a child before returning this
+            // malformed suspended start. Abort the same signal it received so
+            // its registered child cleanup drains before the parent finish.
+            active.controller.abort(error);
+          }
+          return await finishImmediate(
+            active,
+            resultFromThrown(
+              normalizedInput.playbookId,
+              childSessionId,
+              error,
+              false,
+            ),
+            error,
+          );
+        }
+
+        if (active.signal.aborted) {
+          return await finishImmediate(
+            active,
+            resultFromThrown(
+              normalizedInput.playbookId,
+              start.state === 'suspended' ? start.childSessionId : undefined,
+              active.signal.reason,
+              true,
+            ),
+          );
+        }
+        if (start.state === 'settled') {
+          return await finishImmediate(active, start.result);
+        }
+
+        active.phase = 'suspended';
+        active.childSessionId = start.childSessionId;
+        const abortListener = (): void => {
+          if (active.phase !== 'suspended') return;
+          const result = resultFromThrown(
+            active.input.playbookId,
+            active.childSessionId,
+            active.signal.reason ??
+              new Error('Nested playbook invocation aborted'),
+            true,
+          );
+          void settlePending(active, result).catch((error: unknown) => {
+            reportBackgroundError(error);
+          });
+        };
+        active.abortListener = abortListener;
+        active.signal.addEventListener('abort', abortListener, { once: true });
+        const pendingCall = pendingIdentity(active);
+        if (!pendingCall) {
+          throw new Error('suspended call identity was not recorded');
+        }
+        for (const listener of pendingListeners) {
+          try {
+            listener(pendingCall);
+          } catch (error) {
+            reportBackgroundError(error);
+          }
+        }
+        if (active.signal.aborted) abortListener();
+        return await active.deferred.promise;
+      } catch (error) {
+        active.runError = error;
+        throw error;
+      } finally {
+        active.finished.resolve(undefined);
+      }
+    },
+  );
+
+  const abortPending = async (
+    error: unknown = new Error('Nested playbook call aborted'),
+  ): Promise<void> => {
+    const active = current;
+    if (!active) return;
+    if (!active.controller.signal.aborted) active.controller.abort(error);
+    if (active.phase === 'starting') {
+      await active.finished.promise;
+      if (
+        active.runError !== undefined &&
+        !(active.runError instanceof NestedPlaybookCallError)
+      ) {
+        throw active.runError;
+      }
+      return;
+    }
+    if (active.phase === 'settling' && active.settlement) {
+      await active.settlement;
+      await active.finished.promise;
+      return;
+    }
+    const pendingCall = pendingIdentity(active);
+    if (!pendingCall) return;
+    await settlePending(
+      active,
+      resultFromThrown(
+        pendingCall.playbookId,
+        pendingCall.childSessionId,
+        error,
+        true,
+      ),
+    );
+    await active.finished.promise;
+  };
+
+  return {
+    actorLogic,
+    getPendingCall: () => pendingIdentity(current),
+    subscribePendingCall(listener) {
+      if (disposed) return () => undefined;
+      pendingListeners.add(listener);
+      const pendingCall = pendingIdentity(current);
+      if (pendingCall) {
+        try {
+          listener(pendingCall);
+        } catch (error) {
+          reportBackgroundError(error);
+        }
+      }
+      return () => pendingListeners.delete(listener);
+    },
+    async resume({ callId, result, signal }) {
+      const active = current;
+      const pendingCall = pendingIdentity(active);
+      if (!active || !pendingCall) {
+        throw new Error(`unknown or stale playbook call id ${callId}`);
+      }
+      if (callId !== pendingCall.callId) {
+        const error = new PlaybookCallIdentityError(
+          `playbook call id ${callId} does not match ${pendingCall.callId}`,
+        );
+        reportControlPlaneError(error);
+        throw error;
+      }
+      let validatedResult: PlaybookCallResult;
+      try {
+        validatedResult = validatePlaybookCallResult(
+          result,
+          pendingCall.playbookId,
+          pendingCall.childSessionId,
+        );
+      } catch (error) {
+        reportControlPlaneError(error);
+        if (!(error instanceof PlaybookCallIdentityError)) {
+          await settlePending(
+            active,
+            resultFromThrown(
+              pendingCall.playbookId,
+              pendingCall.childSessionId,
+              error,
+              false,
+            ),
+            error,
+          );
+          await active.finished.promise;
+        }
+        throw error;
+      }
+      options.bindResumeSignal?.(signal);
+      await settlePending(active, validatedResult);
+    },
+    abortPending,
+    async dispose() {
+      if (disposed) return;
+      disposed = true;
+      try {
+        const active = current;
+        await abortPending(new Error('Nested playbook bridge disposed'));
+        if (
+          active?.runError !== undefined &&
+          !(active.runError instanceof NestedPlaybookCallError)
+        ) {
+          throw active.runError;
+        }
+      } finally {
+        pendingListeners.clear();
+      }
+    },
+  };
+}
+
+export interface WaitForPlaybookQuiescenceOptions {
+  signal?: AbortSignal;
+  timeout?: number;
+  pendingCalls?: PendingCallObserver;
+}
+
+/**
+ * Wait at the imperative runtime boundary; workflow waiting remains in XState.
+ * A pending-call notification covers the case where the suspended state was
+ * entered before its host returned the child session id.
+ */
+export async function waitForPlaybookQuiescence<TActorRef extends AnyActorRef>(
+  actor: TActorRef,
+  options: WaitForPlaybookQuiescenceOptions = {},
+): Promise<SnapshotFrom<TActorRef>> {
+  const current = actor.getSnapshot();
+  const normalized = normalizePlaybookSnapshot(current, {
+    pendingCall: options.pendingCalls?.getPendingCall(),
+  });
+  if (normalized.quiescent) return current;
+
+  const waitOptions = {
+    ...(options.timeout === undefined ? {} : { timeout: options.timeout }),
+  };
+  const waitController = options.pendingCalls
+    ? new AbortController()
+    : undefined;
+  const forwardAbort = (): void =>
+    waitController?.abort(options.signal?.reason);
+  if (waitController && options.signal) {
+    if (options.signal.aborted) forwardAbort();
+    else options.signal.addEventListener('abort', forwardAbort, { once: true });
+  }
+  const snapshotWait = waitFor(
+    actor,
+    (snapshot) =>
+      normalizePlaybookSnapshot(snapshot, {
+        pendingCall: options.pendingCalls?.getPendingCall(),
+      }).quiescent,
+    {
+      ...waitOptions,
+      ...(waitController
+        ? { signal: waitController.signal }
+        : options.signal
+          ? { signal: options.signal }
+          : {}),
+    },
+  );
+  if (!options.pendingCalls) return snapshotWait;
+
+  let unsubscribe = (): void => undefined;
+  const pendingWait = new Promise<SnapshotFrom<TActorRef>>((resolve) => {
+    unsubscribe =
+      options.pendingCalls?.subscribePendingCall(() => {
+        const snapshot = actor.getSnapshot();
+        if (
+          normalizePlaybookSnapshot(snapshot, {
+            pendingCall: options.pendingCalls?.getPendingCall(),
+          }).quiescent
+        ) {
+          resolve(snapshot);
+        }
+      }) ?? unsubscribe;
+  });
+  try {
+    return await Promise.race([snapshotWait, pendingWait]);
+  } finally {
+    unsubscribe();
+    waitController?.abort(new Error('Playbook quiescence already settled'));
+    options.signal?.removeEventListener('abort', forwardAbort);
+  }
+}