@sublang/playbook 7.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);
@@ -386,6 +428,50 @@ function capturedSessionStore(
   });
 }
 
+function capturedRoleBindings(
+  descriptors: PropertyDescriptorMap,
+): NonNullable<PlaybookSession['roleBindings']> {
+  const captured = snapshotJsonValue(
+    capturedDataValue(
+      descriptors,
+      'roleBindings',
+      'playbook session roleBindings',
+    ),
+    'playbook session roleBindings',
+  );
+  if (!isRecord(captured)) {
+    throw new TypeError('playbook session roleBindings must be an object');
+  }
+  const bindings: Record<
+    string,
+    { readonly playerId: string; readonly promptIdentity: string }
+  > = {};
+  for (const [roleId, value] of Object.entries(captured)) {
+    requireNonEmptyString(roleId, 'playbook session roleBindings role id');
+    if (!isRecord(value)) {
+      throw new TypeError(
+        `playbook session roleBindings.${roleId} must be an object`,
+      );
+    }
+    rejectUnknownKeys(
+      value,
+      ['playerId', 'promptIdentity'],
+      `playbook session roleBindings.${roleId}`,
+    );
+    defineEnumerableDataProperty(bindings, roleId, Object.freeze({
+      playerId: requireNonEmptyString(
+        value.playerId,
+        `playbook session roleBindings.${roleId}.playerId`,
+      ),
+      promptIdentity: requireNonEmptyString(
+        value.promptIdentity,
+        `playbook session roleBindings.${roleId}.promptIdentity`,
+      ),
+    }));
+  }
+  return Object.freeze(bindings);
+}
+
 /** Validate session causality and detach its immutable identity from the host. */
 export function snapshotPlaybookSession(
   session: PlaybookSession,
@@ -453,6 +539,10 @@ export function snapshotPlaybookSession(
     sessionDescriptors,
     'playerSessions',
   );
+  const hasRoleBindings = Object.prototype.hasOwnProperty.call(
+    sessionDescriptors,
+    'roleBindings',
+  );
   let parentSessionId: string | undefined;
   let parentCallId: string | undefined;
   if (depth === 0) {
@@ -501,6 +591,9 @@ export function snapshotPlaybookSession(
   const playerSessions = hasPlayerSessions
     ? capturedSessionStore(sessionDescriptors)
     : undefined;
+  const roleBindings = hasRoleBindings
+    ? capturedRoleBindings(sessionDescriptors)
+    : undefined;
   return Object.freeze({
     sessionId,
     playbookId,
@@ -508,6 +601,7 @@ export function snapshotPlaybookSession(
     ...(parentSessionId === undefined ? {} : { parentSessionId }),
     ...(parentCallId === undefined ? {} : { parentCallId }),
     depth,
+    ...(roleBindings === undefined ? {} : { roleBindings }),
     ...(playerSessions === undefined ? {} : { playerSessions }),
     ports,
   });
@@ -619,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 {
@@ -666,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),
@@ -805,9 +916,10 @@ function snapshotSuspendedCall(
   return Object.freeze(call);
 }
 
-// DR-014 §1 / DR-031 §5: validate and detach a host-supplied runtime
-// snapshot before restore touches any state. A suspended schema-2 call is
-// rejected unless the restore path explicitly promises to seed and claim it.
+// DR-014 §1 / DR-031 §5 / DR-032: validate and detach a host-supplied
+// schema-3 runtime snapshot before restore touches any state. A suspended
+// call is rejected unless the restore path explicitly promises to seed and
+// claim it; older schemas are rejected rather than guessing role identity.
 export function assertPlaybookRuntimeSnapshot(
   value: unknown,
   expectedPlaybookId: string,
@@ -838,19 +950,18 @@ export function assertPlaybookRuntimeSnapshot(
     );
   }
   const allowSuspendedCall = capturedOptions.allowSuspendedCall ?? false;
-  if (snapshot.schemaVersion !== 1 && snapshot.schemaVersion !== 2) {
+  if (snapshot.schemaVersion !== 3) {
     throw new TypeError(
-      `runtime snapshot schemaVersion ${String(snapshot.schemaVersion)} is not supported (expected 1 or 2)`,
+      `runtime snapshot schemaVersion ${String(snapshot.schemaVersion)} is not supported (expected 3)`,
     );
   }
-  const schemaVersion = snapshot.schemaVersion;
   rejectUnknownKeys(
     snapshot,
     [
       'schemaVersion',
       'playbookId',
       'machine',
-      'playerResumeTokens',
+      'roleResumeTokens',
       'sequences',
       'state',
       'pendingBossQuestions',
@@ -858,13 +969,8 @@ export function assertPlaybookRuntimeSnapshot(
     ],
     'runtime snapshot',
   );
-  if (schemaVersion === 1 && own(snapshot, 'suspendedCall')) {
-    throw new TypeError(
-      'runtime snapshot schemaVersion 1 must not carry suspendedCall',
-    );
-  }
   let suspendedCall: PlaybookSuspendedCall | undefined;
-  if (schemaVersion === 2 && own(snapshot, 'suspendedCall')) {
+  if (own(snapshot, 'suspendedCall')) {
     suspendedCall = snapshotSuspendedCall(snapshot.suspendedCall);
     if (!allowSuspendedCall) {
       throw new TypeError(
@@ -885,19 +991,19 @@ export function assertPlaybookRuntimeSnapshot(
     throw new TypeError('runtime snapshot machine must be an object');
   }
   const machine = snapshot.machine;
-  if (!isRecord(snapshot.playerResumeTokens)) {
+  if (!isRecord(snapshot.roleResumeTokens)) {
     throw new TypeError(
-      'runtime snapshot playerResumeTokens must be an object',
+      'runtime snapshot roleResumeTokens must be an object',
     );
   }
-  const playerResumeTokens: Record<string, string> = {};
-  for (const [playerId, token] of Object.entries(snapshot.playerResumeTokens)) {
+  const roleResumeTokens: Record<string, string> = {};
+  for (const [roleId, token] of Object.entries(snapshot.roleResumeTokens)) {
     defineEnumerableDataProperty(
-      playerResumeTokens,
-      playerId,
+      roleResumeTokens,
+      requireNonEmptyString(roleId, 'runtime snapshot roleResumeTokens role id'),
       requireNonEmptyString(
         token,
-        `runtime snapshot playerResumeTokens.${playerId}`,
+        `runtime snapshot roleResumeTokens.${roleId}`,
       ),
     );
   }
@@ -932,7 +1038,7 @@ export function assertPlaybookRuntimeSnapshot(
   const state = snapshot.state as unknown as PlaybookState;
   if (state.tags.includes(SUSPENDED_TAG) && suspendedCall === undefined) {
     throw new TypeError(
-      `runtime snapshot state tagged ${SUSPENDED_TAG} requires schemaVersion 2 suspendedCall`,
+      `runtime snapshot state tagged ${SUSPENDED_TAG} requires suspendedCall`,
     );
   }
   if (suspendedCall) {
@@ -976,15 +1082,36 @@ export function assertPlaybookRuntimeSnapshot(
       if (!isRecord(entry)) throw new TypeError(`${path} must be an object`);
       rejectUnknownKeys(
         entry,
-        ['questionId', 'player', 'question', 'sourceItem'],
+        ['questionId', 'asker', 'question', 'sourceItem'],
         path,
       );
+      if (!isRecord(entry.asker)) {
+        throw new TypeError(`${path}.asker must be an object`);
+      }
+      let asker: PlaybookPendingBossQuestion['asker'];
+      if (entry.asker.kind === 'captain') {
+        rejectUnknownKeys(entry.asker, ['kind'], `${path}.asker`);
+        asker = Object.freeze({ kind: 'captain' });
+      } else if (entry.asker.kind === 'role') {
+        rejectUnknownKeys(entry.asker, ['kind', 'roleId'], `${path}.asker`);
+        asker = Object.freeze({
+          kind: 'role',
+          roleId: requireNonEmptyString(
+            entry.asker.roleId,
+            `${path}.asker.roleId`,
+          ),
+        });
+      } else {
+        throw new TypeError(
+          `${path}.asker.kind must be "captain" or "role"`,
+        );
+      }
       const question: PlaybookPendingBossQuestion = {
         questionId: requireNonEmptyString(
           entry.questionId,
           `${path}.questionId`,
         ),
-        player: requireNonEmptyString(entry.player, `${path}.player`),
+        asker,
         question: requireNonEmptyString(entry.question, `${path}.question`),
         ...(entry.sourceItem === undefined
           ? {}
@@ -1001,16 +1128,13 @@ export function assertPlaybookRuntimeSnapshot(
   const fields = {
     playbookId,
     machine,
-    playerResumeTokens: Object.freeze(playerResumeTokens),
+    roleResumeTokens: Object.freeze(roleResumeTokens),
     sequences: Object.freeze(sequences),
     state,
     pendingBossQuestions: Object.freeze(pendingBossQuestions),
   };
-  if (schemaVersion === 1) {
-    return Object.freeze({ schemaVersion: 1, ...fields });
-  }
   return Object.freeze({
-    schemaVersion: 2,
+    schemaVersion: 3,
     ...fields,
     ...(suspendedCall === undefined ? {} : { suspendedCall }),
   });
@@ -1041,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 {
@@ -1070,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;
@@ -1228,6 +1370,9 @@ export function validatePlayerResult(
   );
   validateRunStatus(result.status, `${path}.status`);
   validateOptionalString(result, 'resumeToken', path);
+  if (result.resumeToken !== undefined) {
+    requireNonEmptyString(result.resumeToken, `${path}.resumeToken`);
+  }
   validateOptionalString(result, 'finalText', path);
   validateOptionalString(result, 'error', path);
   return result as unknown as PlayerResult;
@@ -1441,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);
     }
   };
 
@@ -1510,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 (
@@ -1530,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();
@@ -1551,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;
@@ -1571,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;
@@ -1588,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) {
@@ -1652,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;
   };
@@ -1665,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;
@@ -1682,7 +1864,7 @@ export function createNestedPlaybookBridge<
       try {
         listener(pendingCall);
       } catch (error) {
-        reportBackgroundError(error);
+        reportBackgroundError(error, active.aborts);
       }
     }
     if (active.signal.aborted) abortListener();
@@ -1766,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) {
@@ -1786,6 +1975,7 @@ export function createNestedPlaybookBridge<
           finished: deferred<void>(),
           controller,
           signal: callSignal,
+          aborts: callAborts,
           phase: 'restoring',
           childSessionId: seed.childSessionId,
         };
@@ -1804,8 +1994,7 @@ export function createNestedPlaybookBridge<
           }
           rollbackRestoredCall(
             mode,
-            active.signal.reason ??
-              new Error('Restored nested playbook invocation aborted'),
+            active.signal.reason,
           );
         };
         active.abortListener = restoreAbortListener;
@@ -1847,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) {
@@ -1863,6 +2059,7 @@ export function createNestedPlaybookBridge<
         finished: deferred<void>(),
         controller,
         signal: callSignal,
+        aborts: callAborts,
         phase: 'starting',
       };
       current = active;
@@ -1872,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,
           );
         }
 
@@ -1934,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;
             },
           );
@@ -1951,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,
@@ -2140,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;
@@ -2167,7 +2382,7 @@ export function createNestedPlaybookBridge<
         try {
           listener(pendingCall);
         } catch (error) {
-          reportBackgroundError(error);
+          reportBackgroundError(error, current?.aborts);
         }
       }
       return () => pendingListeners.delete(listener);
@@ -2209,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() {