@sublang/playbook 8.0.0 → 9.0.0

package/src/xstate-runtime.ts

@@ -68,11 +68,45 @@ function withAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
   });
 }
 
+// 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: unknown, signal: AbortSignal): boolean {
-  return (
-    signal.aborted &&
-    (error === signal.reason || normalizeError(error).name === 'AbortError')
+  return signal.aborted && Object.is(error, signal.reason);
+}
+
+/**
+ * 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;
+}
+
+function createAbortReasonClassifier(
+  ...sources: readonly (
+    | AbortSignal
+    | AbortReasonClassifier
+    | undefined
+  )[]
+): AbortReasonClassifier {
+  const captured = Object.freeze(
+    sources.filter(
+      (
+        source,
+      ): source is AbortSignal | AbortReasonClassifier =>
+        source !== undefined,
+    ),
   );
+  return Object.freeze({
+    isAbortReason: (error: unknown): boolean =>
+      captured.some((source) =>
+        source instanceof AbortSignal
+          ? isAbortReason(error, source)
+          : source.isAbortReason(error),
+      ),
+  });
 }
 
 const NEVER_ABORTED_SIGNAL = new AbortController().signal;
@@ -119,7 +153,10 @@ export function registerPlaybookAbortCleanup(
   void cleanup.catch(() => undefined);
 }
 
-async function drainPlaybookAbortCleanups(signal: AbortSignal): Promise<void> {
+async function drainPlaybookAbortCleanups(
+  signal: AbortSignal,
+  aborts: AbortReasonClassifier,
+): Promise<void> {
   const failures: unknown[] = [];
   while (true) {
     const pending = abortCleanups.get(signal);
@@ -128,7 +165,12 @@ async function drainPlaybookAbortCleanups(signal: AbortSignal): Promise<void> {
     pending.clear();
     const outcomes = await Promise.allSettled(batch);
     for (const outcome of outcomes) {
-      if (outcome.status === 'rejected') failures.push(outcome.reason);
+      if (
+        outcome.status === 'rejected' &&
+        !aborts.isAbortReason(outcome.reason)
+      ) {
+        failures.push(outcome.reason);
+      }
     }
   }
   abortCleanups.delete(signal);
@@ -671,7 +713,10 @@ function normalizeStateValue(
 
 export interface PlaybookStateMetadata {
   stateId: string;
-  description: string;
+  // Optional by contract: a state whose source declares no description
+  // carries none, and no id is ever promoted into one
+  // (slc/link.md §Snapshot normalization).
+  description?: string;
 }
 
 interface MachineSnapshotLike {
@@ -718,17 +763,31 @@ export function activePlaybookStateMetadata(
       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),
@@ -1106,12 +1165,29 @@ export interface NestedPlaybookBridgeOptions {
     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 class NestedPlaybookCallError extends Error {
@@ -1135,6 +1211,7 @@ interface ActiveCall {
   readonly finished: Deferred<void>;
   readonly controller: AbortController;
   readonly signal: AbortSignal;
+  readonly aborts: AbortReasonClassifier;
   phase: 'starting' | 'restoring' | 'suspended' | 'settling';
   childSessionId?: string;
   abortListener?: () => void;
@@ -1509,21 +1586,29 @@ export function createNestedPlaybookBridge<
     (pendingCall: PlaybookPendingCall) => void
   >();
 
-  const reportBackgroundError = (error: unknown): void => {
+  const reportBackgroundError = (
+    error: unknown,
+    aborts?: AbortReasonClassifier,
+  ): void => {
+    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: unknown): void => {
+  const reportControlPlaneError = (
+    error: unknown,
+    aborts?: AbortReasonClassifier,
+  ): void => {
+    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);
     }
   };
 
@@ -1578,18 +1663,31 @@ export function createNestedPlaybookBridge<
     if (current === active) current = undefined;
   };
 
+  // A failure causally identical to an applicable abort reason is the
+  // cancellation's own evidence, never a control-plane error.
+  const reportNonAbortControlError = (
+    error: unknown,
+    aborts: AbortReasonClassifier,
+  ): void => {
+    reportControlPlaneError(error, aborts);
+  };
+
   const emitFinish = async (
     active: ActiveCall,
     result: PlaybookCallResult,
+    aborts: AbortReasonClassifier,
   ): Promise<void> => {
-    await options.emitFinished({
-      callId: active.callId,
-      stateId: active.input.stateId,
-      playbookId: active.input.playbookId,
-      text: active.input.text,
-      result,
-    });
-    await options.drain();
+    await options.emitFinished(
+      {
+        callId: active.callId,
+        stateId: active.input.stateId,
+        playbookId: active.input.playbookId,
+        text: active.input.text,
+        result,
+      },
+      aborts,
+    );
+    await options.drain(aborts);
   };
 
   const finishImmediate = async (
@@ -1598,20 +1696,25 @@ export function createNestedPlaybookBridge<
     controlError?: unknown,
     resultAfterAbortCleanup?: () => PlaybookCallResult,
   ): Promise<JsonValue | undefined> => {
+    const aborts = active.aborts;
     let effectiveResult = result;
     let cleanupControlError: unknown;
     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();
@@ -1619,15 +1722,16 @@ export function createNestedPlaybookBridge<
     }
     let finishControlError: unknown;
     try {
-      await emitFinish(active, effectiveResult);
+      await emitFinish(active, effectiveResult, aborts);
     } catch (error) {
-      reportControlPlaneError(error);
+      reportNonAbortControlError(error, aborts);
       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);
+      options.bindActorSettlement?.(aborts);
     }
     if (controlError !== undefined) throw controlError;
     if (cleanupControlError !== undefined) throw cleanupControlError;
@@ -1639,6 +1743,7 @@ export function createNestedPlaybookBridge<
     active: ActiveCall,
     result: PlaybookCallResult,
     controlError?: unknown,
+    aborts: AbortReasonClassifier = active.aborts,
   ): Promise<void> => {
     if (active.phase === 'settling' && active.settlement) {
       await active.settlement;
@@ -1656,37 +1761,45 @@ export function createNestedPlaybookBridge<
           effectiveResult = resultFromThrown(
             active.input.playbookId,
             active.childSessionId,
-            active.signal.reason ??
-              new Error('Nested playbook invocation aborted'),
+            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);
       } else if (cleanupControlError !== undefined) {
@@ -1720,6 +1833,7 @@ export function createNestedPlaybookBridge<
     active.restoreRolledBack = true;
     clear(active);
     usedCallIds.delete(active.callId);
+    options.bindActorSettlement?.(active.aborts);
     active.deferred.reject(error);
     return active;
   };
@@ -1733,11 +1847,11 @@ export function createNestedPlaybookBridge<
       const result = resultFromThrown(
         active.input.playbookId,
         active.childSessionId,
-        active.signal.reason ?? new Error('Nested playbook invocation aborted'),
+        active.signal.reason,
         true,
       );
       void settlePending(active, result).catch((error: unknown) => {
-        reportBackgroundError(error);
+        reportBackgroundError(error, active.aborts);
       });
     };
     active.abortListener = abortListener;
@@ -1750,7 +1864,7 @@ export function createNestedPlaybookBridge<
       try {
         listener(pendingCall);
       } catch (error) {
-        reportBackgroundError(error);
+        reportBackgroundError(error, active.aborts);
       }
     }
     if (active.signal.aborted) abortListener();
@@ -1834,10 +1948,17 @@ export function createNestedPlaybookBridge<
         }
         const controller = new AbortController();
         let callSignal: AbortSignal;
+        let callAborts: AbortReasonClassifier;
         try {
+          const boundarySignal = options.getBoundarySignal?.();
           callSignal = combineAbortSignals(
             invocationSignal,
-            options.getBoundarySignal?.(),
+            boundarySignal,
+            controller.signal,
+          );
+          callAborts = createAbortReasonClassifier(
+            invocationSignal,
+            boundarySignal,
             controller.signal,
           );
         } catch (error) {
@@ -1854,6 +1975,7 @@ export function createNestedPlaybookBridge<
           finished: deferred<void>(),
           controller,
           signal: callSignal,
+          aborts: callAborts,
           phase: 'restoring',
           childSessionId: seed.childSessionId,
         };
@@ -1872,8 +1994,7 @@ export function createNestedPlaybookBridge<
           }
           rollbackRestoredCall(
             mode,
-            active.signal.reason ??
-              new Error('Restored nested playbook invocation aborted'),
+            active.signal.reason,
           );
         };
         active.abortListener = restoreAbortListener;
@@ -1915,10 +2036,17 @@ export function createNestedPlaybookBridge<
       usedCallIds.add(callId);
       const controller = new AbortController();
       let callSignal: AbortSignal;
+      let callAborts: AbortReasonClassifier;
       try {
+        const boundarySignal = options.getBoundarySignal?.();
         callSignal = combineAbortSignals(
           invocationSignal,
-          options.getBoundarySignal?.(),
+          boundarySignal,
+          controller.signal,
+        );
+        callAborts = createAbortReasonClassifier(
+          invocationSignal,
+          boundarySignal,
           controller.signal,
         );
       } catch (error) {
@@ -1931,6 +2059,7 @@ export function createNestedPlaybookBridge<
         finished: deferred<void>(),
         controller,
         signal: callSignal,
+        aborts: callAborts,
         phase: 'starting',
       };
       current = active;
@@ -1940,40 +2069,56 @@ export function createNestedPlaybookBridge<
         // 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);
+          // 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,
-              false,
+              controlError === undefined,
             ),
-            error,
+            controlError,
           );
         }
         try {
-          await options.drain();
+          await options.drain(active.aborts);
         } catch (error) {
-          reportControlPlaneError(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,
-              false,
+              controlError === undefined,
             ),
-            error,
+            controlError,
           );
         }
 
@@ -2002,7 +2147,7 @@ export function createNestedPlaybookBridge<
           const openingCleanup = starting.then(
             () => undefined,
             (error: unknown) => {
-              if (isAbortReason(error, active.signal)) return;
+              if (active.aborts.isAbortReason(error)) return;
               throw error;
             },
           );
@@ -2019,19 +2164,23 @@ export function createNestedPlaybookBridge<
           }
           rawStart = await withAbort(starting, active.signal);
         } catch (error) {
-          const controlError = active.signal.aborted ? undefined : error;
-          if (controlError !== undefined) reportControlPlaneError(controlError);
+          const controlError = active.aborts.isAbortReason(error)
+            ? undefined
+            : error;
+          if (controlError !== undefined) {
+            reportControlPlaneError(controlError, active.aborts);
+          }
           const result = resultFromThrown(
             normalizedInput.playbookId,
             undefined,
             error,
-            active.signal.aborted,
+            controlError === undefined && active.signal.aborted,
           );
           return await finishImmediate(
             active,
             result,
             controlError,
-            active.signal.aborted
+            controlError === undefined && active.signal.aborted
               ? () =>
                   resultFromThrown(
                     normalizedInput.playbookId,
@@ -2208,9 +2357,7 @@ export function createNestedPlaybookBridge<
       }
       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;
@@ -2235,7 +2382,7 @@ export function createNestedPlaybookBridge<
         try {
           listener(pendingCall);
         } catch (error) {
-          reportBackgroundError(error);
+          reportBackgroundError(error, current?.aborts);
         }
       }
       return () => pendingListeners.delete(listener);
@@ -2277,8 +2424,20 @@ export function createNestedPlaybookBridge<
         }
         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() {