@sublang/playbook 8.0.0 → 9.0.0

package/src/xstate-runtime.d.ts

@@ -1,6 +1,14 @@
 import { type AnyActorRef, type PromiseActorLogic, type SnapshotFrom } from 'xstate';
 import type { CaptainResult, JsonValue, NormalizedError, PlaybookCallRequest, PlaybookCallResult, PlaybookCallStart, PlaybookPendingCall, PlaybookRuntimeSnapshot, PlaybookSession, PlaybookState, PlaybookSuspendedCall, PlayerResult } from './runtime.js';
 export * from './xstate-playbook-runtime.js';
+/**
+ * Immutable cancellation provenance for one runtime operation. The captured
+ * signal identities do not change when a mutable runtime advances to another
+ * public boundary, while each signal's eventual reason remains observable.
+ */
+interface AbortReasonClassifier {
+    isAbortReason(error: unknown): boolean;
+}
 /**
  * Compose invocation-lifetime and imperative-boundary cancellation without
  * installing a second forwarding listener in each generated runtime.
@@ -22,7 +30,7 @@ export declare function hiddenControlEnvelope(prompt: string): string;
 export declare function normalizeError(error: unknown): NormalizedError;
 export interface PlaybookStateMetadata {
     stateId: string;
-    description: string;
+    description?: string;
 }
 /** Read stable state identity without consulting XState's private `_nodes`. */
 export declare function activePlaybookStateMetadata(snapshot: unknown): readonly PlaybookStateMetadata[];
@@ -59,12 +67,14 @@ export interface NestedPlaybookBridgeOptions {
     /** 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;
+    emitStarted(event: PlaybookCallStarted, aborts?: AbortReasonClassifier): Promise<void>;
+    emitFinished(event: PlaybookCallFinished, aborts?: AbortReasonClassifier): Promise<void>;
+    drain(aborts?: AbortReasonClassifier): Promise<void>;
+    bindResumeSignal?(signal: AbortSignal, aborts?: AbortReasonClassifier): void;
+    /** Bind provenance to the root transition caused by this child result. */
+    bindActorSettlement?(aborts: AbortReasonClassifier): void;
+    onControlPlaneError?(error: unknown, aborts?: AbortReasonClassifier): void;
+    onBackgroundError?(error: unknown, aborts?: AbortReasonClassifier): void;
 }
 export declare class NestedPlaybookCallError extends Error {
     readonly result: PlaybookCallResult;

package/src/xstate-runtime.js

@@ -31,9 +31,19 @@ function withAbort(promise, signal) {
         });
     });
 }
+// slc/link.md §Abort: cancellation is causal identity with the applicable
+// signal's reason; an `AbortError`-named rejection that is not that exact
+// reason is a control-plane failure to surface, never an abort to swallow.
 function isAbortReason(error, signal) {
-    return (signal.aborted &&
-        (error === signal.reason || normalizeError(error).name === 'AbortError'));
+    return signal.aborted && Object.is(error, signal.reason);
+}
+function createAbortReasonClassifier(...sources) {
+    const captured = Object.freeze(sources.filter((source) => source !== undefined));
+    return Object.freeze({
+        isAbortReason: (error) => captured.some((source) => source instanceof AbortSignal
+            ? isAbortReason(error, source)
+            : source.isAbortReason(error)),
+    });
 }
 const NEVER_ABORTED_SIGNAL = new AbortController().signal;
 /**
@@ -73,7 +83,7 @@ export function registerPlaybookAbortCleanup(signal, cleanup) {
     // the bridge's allSettled drain observes its outcome.
     void cleanup.catch(() => undefined);
 }
-async function drainPlaybookAbortCleanups(signal) {
+async function drainPlaybookAbortCleanups(signal, aborts) {
     const failures = [];
     while (true) {
         const pending = abortCleanups.get(signal);
@@ -83,8 +93,10 @@ async function drainPlaybookAbortCleanups(signal) {
         pending.clear();
         const outcomes = await Promise.allSettled(batch);
         for (const outcome of outcomes) {
-            if (outcome.status === 'rejected')
+            if (outcome.status === 'rejected' &&
+                !aborts.isAbortReason(outcome.reason)) {
                 failures.push(outcome.reason);
+            }
         }
     }
     abortCleanups.delete(signal);
@@ -484,12 +496,23 @@ export function activePlaybookStateMetadata(snapshot) {
             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`);
+        // Description is optional: a state may declare none and stay fully
+        // usable, merely carrying no `stateDescription` downstream. A declared
+        // description must still be a nonempty string.
+        const description = meta.playbook.description === undefined
+            ? undefined
+            : requireNonEmptyString(meta.playbook.description, `${nodeId}.meta.playbook.description`);
         const previous = byStateId.get(stateId);
-        if (previous && previous.description !== description) {
+        if (previous?.description !== undefined &&
+            description !== undefined &&
+            previous.description !== description) {
             throw new TypeError(`active state id ${stateId} has conflicting descriptions`);
         }
-        byStateId.set(stateId, { stateId, description });
+        const effective = description ?? previous?.description;
+        byStateId.set(stateId, {
+            stateId,
+            ...(effective === undefined ? {} : { description: effective }),
+        });
     }
     return [...byStateId.values()].sort((left, right) => left.stateId.localeCompare(right.stateId));
 }
@@ -948,22 +971,26 @@ export function createNestedPlaybookBridge(options) {
     let disposed = false;
     const usedCallIds = new Set();
     const pendingListeners = new Set();
-    const reportBackgroundError = (error) => {
+    const reportBackgroundError = (error, aborts) => {
+        if (aborts?.isAbortReason(error))
+            return;
         try {
-            options.onBackgroundError?.(error);
+            options.onBackgroundError?.(error, aborts);
         }
         catch {
             // Background observers are a terminal sink and cannot own cleanup.
         }
     };
-    const reportControlPlaneError = (error) => {
+    const reportControlPlaneError = (error, aborts) => {
+        if (aborts?.isAbortReason(error))
+            return;
         try {
-            options.onControlPlaneError?.(error);
+            options.onControlPlaneError?.(error, aborts);
         }
         catch (callbackError) {
             // Observability callbacks must never prevent terminal cleanup of the
             // invocation they are observing.
-            reportBackgroundError(callbackError);
+            reportBackgroundError(callbackError, aborts);
         }
     };
     const rejectControlPlane = (error) => {
@@ -1003,27 +1030,37 @@ export function createNestedPlaybookBridge(options) {
         if (current === active)
             current = undefined;
     };
-    const emitFinish = async (active, result) => {
+    // A failure causally identical to an applicable abort reason is the
+    // cancellation's own evidence, never a control-plane error.
+    const reportNonAbortControlError = (error, aborts) => {
+        reportControlPlaneError(error, aborts);
+    };
+    const emitFinish = async (active, result, aborts) => {
         await options.emitFinished({
             callId: active.callId,
             stateId: active.input.stateId,
             playbookId: active.input.playbookId,
             text: active.input.text,
             result,
-        });
-        await options.drain();
+        }, aborts);
+        await options.drain(aborts);
     };
     const finishImmediate = async (active, result, controlError, resultAfterAbortCleanup) => {
+        const aborts = active.aborts;
         let effectiveResult = result;
         let cleanupControlError;
         if (result.status === 'aborted' || active.signal.aborted) {
             try {
-                await drainPlaybookAbortCleanups(active.signal);
+                await drainPlaybookAbortCleanups(active.signal, aborts);
             }
             catch (error) {
-                cleanupControlError = error;
-                reportControlPlaneError(error);
-                effectiveResult = resultFromThrown(active.input.playbookId, active.childSessionId, error, false);
+                // A cleanup rejection identical to an applicable abort reason is
+                // the cancellation's own evidence — no latch, no result override.
+                if (!aborts.isAbortReason(error)) {
+                    cleanupControlError = error;
+                    reportControlPlaneError(error, aborts);
+                    effectiveResult = resultFromThrown(active.input.playbookId, active.childSessionId, error, false);
+                }
             }
             if (cleanupControlError === undefined && resultAfterAbortCleanup) {
                 effectiveResult = resultAfterAbortCleanup();
@@ -1031,10 +1068,10 @@ export function createNestedPlaybookBridge(options) {
         }
         let finishControlError;
         try {
-            await emitFinish(active, effectiveResult);
+            await emitFinish(active, effectiveResult, aborts);
         }
         catch (error) {
-            reportControlPlaneError(error);
+            reportNonAbortControlError(error, aborts);
             finishControlError = error;
         }
         finally {
@@ -1042,6 +1079,7 @@ export function createNestedPlaybookBridge(options) {
             // emission fails, do not leave a permanently unresumable call in the
             // bridge and prevent disposal or a later invocation.
             clear(active);
+            options.bindActorSettlement?.(aborts);
         }
         if (controlError !== undefined)
             throw controlError;
@@ -1051,7 +1089,7 @@ export function createNestedPlaybookBridge(options) {
             throw finishControlError;
         return outputOrThrow(effectiveResult);
     };
-    const settlePending = async (active, result, controlError) => {
+    const settlePending = async (active, result, controlError, aborts = active.aborts) => {
         if (active.phase === 'settling' && active.settlement) {
             await active.settlement;
             return;
@@ -1065,32 +1103,40 @@ export function createNestedPlaybookBridge(options) {
             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);
+                    effectiveResult = resultFromThrown(active.input.playbookId, active.childSessionId, active.signal.reason, true);
                 }
                 try {
-                    await drainPlaybookAbortCleanups(active.signal);
+                    await drainPlaybookAbortCleanups(active.signal, aborts);
                 }
                 catch (cleanupError) {
-                    cleanupControlError = cleanupError;
-                    reportControlPlaneError(cleanupError);
-                    effectiveResult = resultFromThrown(active.input.playbookId, active.childSessionId, cleanupError, false);
+                    // A cleanup rejection identical to an applicable abort reason is
+                    // the cancellation's own evidence — no latch, no result override.
+                    if (!aborts.isAbortReason(cleanupError)) {
+                        cleanupControlError = cleanupError;
+                        reportControlPlaneError(cleanupError, aborts);
+                        effectiveResult = resultFromThrown(active.input.playbookId, active.childSessionId, cleanupError, false);
+                    }
                 }
             }
             try {
-                await emitFinish(active, effectiveResult);
+                await emitFinish(active, effectiveResult, aborts);
             }
             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);
+                // onError instead of observing a phantom suspended child. A finish
+                // rejection that is an applicable abort reason — the invocation's
+                // or the settling resume's — evidences cancellation, not a
+                // control-plane failure (slc/link.md §Abort).
+                reportControlPlaneError(error, aborts);
                 clear(active);
+                options.bindActorSettlement?.(aborts);
                 active.deferred.reject(error);
                 throw error;
             }
             clear(active);
+            options.bindActorSettlement?.(aborts);
             if (controlError !== undefined) {
                 active.deferred.reject(controlError);
             }
@@ -1126,6 +1172,7 @@ export function createNestedPlaybookBridge(options) {
         active.restoreRolledBack = true;
         clear(active);
         usedCallIds.delete(active.callId);
+        options.bindActorSettlement?.(active.aborts);
         active.deferred.reject(error);
         return active;
     };
@@ -1136,9 +1183,9 @@ export function createNestedPlaybookBridge(options) {
         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);
+            const result = resultFromThrown(active.input.playbookId, active.childSessionId, active.signal.reason, true);
             void settlePending(active, result).catch((error) => {
-                reportBackgroundError(error);
+                reportBackgroundError(error, active.aborts);
             });
         };
         active.abortListener = abortListener;
@@ -1152,7 +1199,7 @@ export function createNestedPlaybookBridge(options) {
                 listener(pendingCall);
             }
             catch (error) {
-                reportBackgroundError(error);
+                reportBackgroundError(error, active.aborts);
             }
         }
         if (active.signal.aborted)
@@ -1222,8 +1269,11 @@ export function createNestedPlaybookBridge(options) {
             }
             const controller = new AbortController();
             let callSignal;
+            let callAborts;
             try {
-                callSignal = combineAbortSignals(invocationSignal, options.getBoundarySignal?.(), controller.signal);
+                const boundarySignal = options.getBoundarySignal?.();
+                callSignal = combineAbortSignals(invocationSignal, boundarySignal, controller.signal);
+                callAborts = createAbortReasonClassifier(invocationSignal, boundarySignal, controller.signal);
             }
             catch (error) {
                 failRestoreMode(mode, error);
@@ -1239,6 +1289,7 @@ export function createNestedPlaybookBridge(options) {
                 finished: deferred(),
                 controller,
                 signal: callSignal,
+                aborts: callAborts,
                 phase: 'restoring',
                 childSessionId: seed.childSessionId,
             };
@@ -1253,8 +1304,7 @@ export function createNestedPlaybookBridge(options) {
                     active.phase !== 'restoring') {
                     return;
                 }
-                rollbackRestoredCall(mode, active.signal.reason ??
-                    new Error('Restored nested playbook invocation aborted'));
+                rollbackRestoredCall(mode, active.signal.reason);
             };
             active.abortListener = restoreAbortListener;
             active.signal.addEventListener('abort', restoreAbortListener, {
@@ -1291,8 +1341,11 @@ export function createNestedPlaybookBridge(options) {
         usedCallIds.add(callId);
         const controller = new AbortController();
         let callSignal;
+        let callAborts;
         try {
-            callSignal = combineAbortSignals(invocationSignal, options.getBoundarySignal?.(), controller.signal);
+            const boundarySignal = options.getBoundarySignal?.();
+            callSignal = combineAbortSignals(invocationSignal, boundarySignal, controller.signal);
+            callAborts = createAbortReasonClassifier(invocationSignal, boundarySignal, controller.signal);
         }
         catch (error) {
             return rejectControlPlane(error);
@@ -1304,6 +1357,7 @@ export function createNestedPlaybookBridge(options) {
             finished: deferred(),
             controller,
             signal: callSignal,
+            aborts: callAborts,
             phase: 'starting',
         };
         current = active;
@@ -1312,26 +1366,39 @@ export function createNestedPlaybookBridge(options) {
             // 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();
+                await options.drain(active.aborts);
             }
             catch (error) {
-                reportControlPlaneError(error);
+                reportNonAbortControlError(error, active.aborts);
                 clear(active);
                 throw error;
             }
             try {
-                await options.emitStarted({ callId, ...normalizedInput });
+                await options.emitStarted({ callId, ...normalizedInput }, active.aborts);
             }
             catch (error) {
-                reportControlPlaneError(error);
-                return await finishImmediate(active, resultFromThrown(normalizedInput.playbookId, undefined, error, false), error);
+                // A start-sink rejection identical to the applicable abort
+                // reason is the cancellation itself: the pair finishes
+                // `aborted` and nothing is reported (slc/link.md §Abort).
+                const controlError = active.aborts.isAbortReason(error)
+                    ? undefined
+                    : error;
+                if (controlError !== undefined) {
+                    reportControlPlaneError(controlError, active.aborts);
+                }
+                return await finishImmediate(active, resultFromThrown(normalizedInput.playbookId, undefined, error, controlError === undefined), controlError);
             }
             try {
-                await options.drain();
+                await options.drain(active.aborts);
             }
             catch (error) {
-                reportControlPlaneError(error);
-                return await finishImmediate(active, resultFromThrown(normalizedInput.playbookId, undefined, error, false), error);
+                const controlError = active.aborts.isAbortReason(error)
+                    ? undefined
+                    : error;
+                if (controlError !== undefined) {
+                    reportControlPlaneError(controlError, active.aborts);
+                }
+                return await finishImmediate(active, resultFromThrown(normalizedInput.playbookId, undefined, error, controlError === undefined), controlError);
             }
             const request = {
                 callId,
@@ -1354,7 +1421,7 @@ export function createNestedPlaybookBridge(options) {
                     throw error;
                 });
                 const openingCleanup = starting.then(() => undefined, (error) => {
-                    if (isAbortReason(error, active.signal))
+                    if (active.aborts.isAbortReason(error))
                         return;
                     throw error;
                 });
@@ -1371,11 +1438,14 @@ export function createNestedPlaybookBridge(options) {
                 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
+                const controlError = active.aborts.isAbortReason(error)
+                    ? undefined
+                    : error;
+                if (controlError !== undefined) {
+                    reportControlPlaneError(controlError, active.aborts);
+                }
+                const result = resultFromThrown(normalizedInput.playbookId, undefined, error, controlError === undefined && active.signal.aborted);
+                return await finishImmediate(active, result, controlError, controlError === undefined && active.signal.aborted
                     ? () => resultFromThrown(normalizedInput.playbookId, startSettled
                         ? assignedChildSessionId(observedStart)
                         : undefined, error, true)
@@ -1503,8 +1573,7 @@ export function createNestedPlaybookBridge(options) {
             }
             const active = mode.active;
             if (active.signal.aborted) {
-                const error = active.signal.reason ??
-                    new Error('Restored nested playbook invocation aborted');
+                const error = active.signal.reason;
                 rollbackRestoredCall(mode, error);
                 restoreMode = undefined;
                 throw error;
@@ -1532,7 +1601,7 @@ export function createNestedPlaybookBridge(options) {
                     listener(pendingCall);
                 }
                 catch (error) {
-                    reportBackgroundError(error);
+                    reportBackgroundError(error, current?.aborts);
                 }
             }
             return () => pendingListeners.delete(listener);
@@ -1560,8 +1629,17 @@ export function createNestedPlaybookBridge(options) {
                 }
                 throw error;
             }
-            options.bindResumeSignal?.(signal);
-            await settlePending(active, validatedResult);
+            // A resume whose signal is already aborted delivers nothing: the
+            // validated child result is not consumed, no finish is emitted, and
+            // the pending call survives for a later resume with a fresh signal
+            // (slc/link.md §Nested playbook bridge). Identity and validation
+            // control errors above still win — they are the caller's defects.
+            if (signal.aborted) {
+                throw signal.reason;
+            }
+            const resumeAborts = createAbortReasonClassifier(active.aborts, signal);
+            options.bindResumeSignal?.(signal, resumeAborts);
+            await settlePending(active, validatedResult, undefined, resumeAborts);
         },
         abortPending,
         async dispose() {