@sublang/playbook 0.9.0 → 1.3.0

package/src/xstate-runtime.js

@@ -0,0 +1,1258 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+import { fromPromise, waitFor, } from 'xstate';
+// 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';
+function deferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((resolvePromise, rejectPromise) => {
+        resolve = resolvePromise;
+        reject = rejectPromise;
+    });
+    return { promise, resolve, reject };
+}
+function withAbort(promise, signal) {
+    if (signal.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener('abort', onAbort, { once: true });
+        void promise.then((value) => {
+            signal.removeEventListener('abort', onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener('abort', onAbort);
+            reject(error);
+        });
+    });
+}
+function isAbortReason(error, signal) {
+    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) {
+    const present = [];
+    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();
+/**
+ * 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, cleanup) {
+    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) {
+    const failures = [];
+    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) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function own(value, key) {
+    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, path = '$', ancestors = new Set()) {
+    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;
+        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;
+        const indexed = [];
+        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 = [];
+        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 = {};
+    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, path = '$', ancestors = new Set()) {
+    snapshotJsonValueFromDescriptors(value, path, ancestors);
+}
+function defineEnumerableDataProperty(target, key, value) {
+    // 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, path = '$') {
+    return snapshotJsonValueFromDescriptors(value, path);
+}
+function capturedDataValue(descriptors, key, path, required = true) {
+    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(descriptors, name) {
+    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;
+}
+/** Validate session causality and detach its immutable identity from the host. */
+export function snapshotPlaybookSession(session) {
+    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 < 0) {
+        throw new TypeError('playbook session depth must be a non-negative integer');
+    }
+    const depth = capturedDepth;
+    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;
+    let parentCallId;
+    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 = 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) {
+    if (error instanceof Error) {
+        let name = 'Error';
+        let message = 'Unknown error';
+        let stack;
+        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, path) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new TypeError(`${path} must be a non-empty string`);
+    }
+    return value;
+}
+function normalizeStateValue(value, path = 'snapshot.value', ancestors = new Set()) {
+    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 = {};
+    for (const key of Object.keys(value).sort()) {
+        defineEnumerableDataProperty(normalized, key, normalizeStateValue(value[key], `${path}.${key}`, nextAncestors));
+    }
+    return normalized;
+}
+function asMachineSnapshot(snapshot) {
+    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;
+}
+/** Read stable state identity without consulting XState's private `_nodes`. */
+export function activePlaybookStateMetadata(snapshot) {
+    const machineSnapshot = asMachineSnapshot(snapshot);
+    const byStateId = new Map();
+    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 function normalizePlaybookSnapshot(snapshot, options = {}) {
+    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) {
+    return snapshotJsonValue(withErrorsNormalized(persisted, new Set()), 'persisted machine snapshot');
+}
+function withErrorsNormalized(value, ancestors) {
+    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 = {};
+        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',
+];
+// 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, expectedPlaybookId) {
+    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 = {};
+    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 = {};
+    for (const key of SNAPSHOT_SEQUENCE_KEYS) {
+        const sequence = value.sequences[key];
+        if (!Number.isSafeInteger(sequence) || sequence < 0) {
+            throw new TypeError(`runtime snapshot sequences.${key} must be a non-negative integer`);
+        }
+        sequences[key] = sequence;
+    }
+    const captainCall = value.sequences.captainCall;
+    if (captainCall !== undefined) {
+        if (!Number.isSafeInteger(captainCall) || captainCall < 0) {
+            throw new TypeError('runtime snapshot sequences.captainCall must be a non-negative integer');
+        }
+        sequences.captainCall = captainCall;
+    }
+    validateState(value.state, 'runtime snapshot state');
+    const state = snapshotJsonValue(value.state, 'runtime snapshot state');
+    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 = {
+            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 class NestedPlaybookCallError extends Error {
+    result;
+    constructor(result) {
+        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;
+    }
+}
+function validateState(state, path) {
+    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, allowed, path) {
+    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, path) {
+    if (status !== 'ok' && status !== 'aborted' && status !== 'error') {
+        throw new TypeError(`${path} is invalid`);
+    }
+}
+function validateOptionalString(value, key, path) {
+    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, path = 'Captain result') {
+    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;
+}
+/** Validate, detach, and freeze a host delegated-player result. */
+export function validatePlayerResult(value, path = 'player result') {
+    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;
+}
+function validateNormalizedError(error, path) {
+    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, expectedPlaybookId, expectedChildSessionId) {
+    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;
+}
+class PlaybookCallIdentityError extends TypeError {
+}
+export function validatePlaybookCallStart(start, expectedPlaybookId) {
+    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) {
+    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, childSessionId, error, aborted) {
+    const normalized = normalizeError(error);
+    const result = aborted
+        ? {
+            status: 'aborted',
+            playbookId,
+            ...(childSessionId ? { childSessionId } : {}),
+            error: normalized,
+        }
+        : {
+            status: 'error',
+            playbookId,
+            ...(childSessionId ? { childSessionId } : {}),
+            error: normalized,
+        };
+    return snapshotJsonValue(result, 'playbook result');
+}
+function outputOrThrow(result) {
+    if (result.status === 'ok')
+        return result.output;
+    throw new NestedPlaybookCallError(result);
+}
+export function createNestedPlaybookBridge(options) {
+    let current;
+    let disposed = false;
+    const usedCallIds = new Set();
+    const pendingListeners = new Set();
+    const reportBackgroundError = (error) => {
+        try {
+            options.onBackgroundError?.(error);
+        }
+        catch {
+            // Background observers are a terminal sink and cannot own cleanup.
+        }
+    };
+    const reportControlPlaneError = (error) => {
+        try {
+            options.onControlPlaneError?.(error);
+        }
+        catch (callbackError) {
+            // Observability callbacks must never prevent terminal cleanup of the
+            // invocation they are observing.
+            reportBackgroundError(callbackError);
+        }
+    };
+    const rejectControlPlane = (error) => {
+        reportControlPlaneError(error);
+        throw error;
+    };
+    const pendingIdentity = (active) => active?.phase === 'suspended' && active.childSessionId
+        ? {
+            callId: active.callId,
+            playbookId: active.input.playbookId,
+            childSessionId: active.childSessionId,
+        }
+        : undefined;
+    const clear = (active) => {
+        if (active.abortListener) {
+            active.signal.removeEventListener('abort', active.abortListener);
+        }
+        if (current === active)
+            current = undefined;
+    };
+    const emitFinish = async (active, result) => {
+        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, result, controlError, resultAfterAbortCleanup) => {
+        let effectiveResult = result;
+        let cleanupControlError;
+        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;
+        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, result, controlError) => {
+        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 () => {
+            let effectiveResult = result;
+            let cleanupControlError;
+            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(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'),
+                ];
+            }
+            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;
+        try {
+            callSignal = combineAbortSignals(invocationSignal, options.getBoundarySignal?.(), controller.signal);
+        }
+        catch (error) {
+            return rejectControlPlane(error);
+        }
+        const active = {
+            callId,
+            input: normalizedInput,
+            deferred: deferred(),
+            finished: deferred(),
+            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 = {
+                callId,
+                playbookId: normalizedInput.playbookId,
+                text: normalizedInput.text,
+            };
+            let rawStart;
+            let observedStart;
+            let startSettled = false;
+            let removeOpeningAbortListener = () => 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) => {
+                    startSettled = true;
+                    throw error;
+                });
+                const openingCleanup = starting.then(() => undefined, (error) => {
+                    if (isAbortReason(error, active.signal))
+                        return;
+                    throw error;
+                });
+                void openingCleanup.catch(() => undefined);
+                const registerOpeningCleanup = () => registerPlaybookAbortCleanup(active.signal, openingCleanup);
+                removeOpeningAbortListener = () => 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;
+            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 = () => {
+                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) => {
+                    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 = new Error('Nested playbook call aborted')) => {
+        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;
+            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();
+            }
+        },
+    };
+}
+/**
+ * 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(actor, options = {}) {
+    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 = () => 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 = () => undefined;
+    const pendingWait = new Promise((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);
+    }
+}