@sublang/playbook 7.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);
@@ -268,6 +280,25 @@ function capturedSessionStore(descriptors) {
         restore: method('restore'),
     });
 }
+function capturedRoleBindings(descriptors) {
+    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 = {};
+    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) {
     if (!isRecord(session)) {
@@ -287,6 +318,7 @@ export function snapshotPlaybookSession(session) {
     const hasParentSessionId = Object.prototype.hasOwnProperty.call(sessionDescriptors, 'parentSessionId');
     const hasParentCallId = Object.prototype.hasOwnProperty.call(sessionDescriptors, 'parentCallId');
     const hasPlayerSessions = Object.prototype.hasOwnProperty.call(sessionDescriptors, 'playerSessions');
+    const hasRoleBindings = Object.prototype.hasOwnProperty.call(sessionDescriptors, 'roleBindings');
     let parentSessionId;
     let parentCallId;
     if (depth === 0) {
@@ -320,6 +352,9 @@ export function snapshotPlaybookSession(session) {
     const playerSessions = hasPlayerSessions
         ? capturedSessionStore(sessionDescriptors)
         : undefined;
+    const roleBindings = hasRoleBindings
+        ? capturedRoleBindings(sessionDescriptors)
+        : undefined;
     return Object.freeze({
         sessionId,
         playbookId,
@@ -327,6 +362,7 @@ export function snapshotPlaybookSession(session) {
         ...(parentSessionId === undefined ? {} : { parentSessionId }),
         ...(parentCallId === undefined ? {} : { parentCallId }),
         depth,
+        ...(roleBindings === undefined ? {} : { roleBindings }),
         ...(playerSessions === undefined ? {} : { playerSessions }),
         ports,
     });
@@ -460,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));
 }
@@ -548,9 +595,10 @@ function snapshotSuspendedCall(value, path = 'runtime snapshot suspendedCall') {
     }
     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, expectedPlaybookId, options = {}) {
     const snapshot = snapshotJsonValue(value, 'runtime snapshot');
     if (!isRecord(snapshot)) {
@@ -566,25 +614,21 @@ export function assertPlaybookRuntimeSnapshot(value, expectedPlaybookId, options
         throw new TypeError('runtime snapshot validation options.allowSuspendedCall must be boolean');
     }
     const allowSuspendedCall = capturedOptions.allowSuspendedCall ?? false;
-    if (snapshot.schemaVersion !== 1 && snapshot.schemaVersion !== 2) {
-        throw new TypeError(`runtime snapshot schemaVersion ${String(snapshot.schemaVersion)} is not supported (expected 1 or 2)`);
+    if (snapshot.schemaVersion !== 3) {
+        throw new TypeError(`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',
         'suspendedCall',
     ], 'runtime snapshot');
-    if (schemaVersion === 1 && own(snapshot, 'suspendedCall')) {
-        throw new TypeError('runtime snapshot schemaVersion 1 must not carry suspendedCall');
-    }
     let suspendedCall;
-    if (schemaVersion === 2 && own(snapshot, 'suspendedCall')) {
+    if (own(snapshot, 'suspendedCall')) {
         suspendedCall = snapshotSuspendedCall(snapshot.suspendedCall);
         if (!allowSuspendedCall) {
             throw new TypeError('runtime snapshot suspendedCall requires a restore path that explicitly allows it');
@@ -598,12 +642,12 @@ export function assertPlaybookRuntimeSnapshot(value, expectedPlaybookId, options
         throw new TypeError('runtime snapshot machine must be an object');
     }
     const machine = snapshot.machine;
-    if (!isRecord(snapshot.playerResumeTokens)) {
-        throw new TypeError('runtime snapshot playerResumeTokens must be an object');
+    if (!isRecord(snapshot.roleResumeTokens)) {
+        throw new TypeError('runtime snapshot roleResumeTokens must be an object');
     }
-    const playerResumeTokens = {};
-    for (const [playerId, token] of Object.entries(snapshot.playerResumeTokens)) {
-        defineEnumerableDataProperty(playerResumeTokens, playerId, requireNonEmptyString(token, `runtime snapshot playerResumeTokens.${playerId}`));
+    const roleResumeTokens = {};
+    for (const [roleId, token] of Object.entries(snapshot.roleResumeTokens)) {
+        defineEnumerableDataProperty(roleResumeTokens, requireNonEmptyString(roleId, 'runtime snapshot roleResumeTokens role id'), requireNonEmptyString(token, `runtime snapshot roleResumeTokens.${roleId}`));
     }
     if (!isRecord(snapshot.sequences)) {
         throw new TypeError('runtime snapshot sequences must be an object');
@@ -627,7 +671,7 @@ export function assertPlaybookRuntimeSnapshot(value, expectedPlaybookId, options
     validateState(snapshot.state, 'runtime snapshot state');
     const state = snapshot.state;
     if (state.tags.includes(SUSPENDED_TAG) && suspendedCall === undefined) {
-        throw new TypeError(`runtime snapshot state tagged ${SUSPENDED_TAG} requires schemaVersion 2 suspendedCall`);
+        throw new TypeError(`runtime snapshot state tagged ${SUSPENDED_TAG} requires suspendedCall`);
     }
     if (suspendedCall) {
         if (sequences.playbookCall === 0) {
@@ -654,10 +698,28 @@ export function assertPlaybookRuntimeSnapshot(value, expectedPlaybookId, options
         const path = `runtime snapshot pendingBossQuestions[${index}]`;
         if (!isRecord(entry))
             throw new TypeError(`${path} must be an object`);
-        rejectUnknownKeys(entry, ['questionId', 'player', 'question', 'sourceItem'], path);
+        rejectUnknownKeys(entry, ['questionId', 'asker', 'question', 'sourceItem'], path);
+        if (!isRecord(entry.asker)) {
+            throw new TypeError(`${path}.asker must be an object`);
+        }
+        let 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 = {
             questionId: requireNonEmptyString(entry.questionId, `${path}.questionId`),
-            player: requireNonEmptyString(entry.player, `${path}.player`),
+            asker,
             question: requireNonEmptyString(entry.question, `${path}.question`),
             ...(entry.sourceItem === undefined
                 ? {}
@@ -670,16 +732,13 @@ export function assertPlaybookRuntimeSnapshot(value, expectedPlaybookId, options
     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 }),
     });
@@ -773,6 +832,9 @@ export function validatePlayerResult(value, path = 'player result') {
     rejectUnknownKeys(result, ['status', 'resumeToken', 'finalText', 'error'], path);
     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;
@@ -909,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) => {
@@ -964,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();
@@ -992,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 {
@@ -1003,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;
@@ -1012,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;
@@ -1026,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);
             }
@@ -1087,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;
     };
@@ -1097,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;
@@ -1113,7 +1199,7 @@ export function createNestedPlaybookBridge(options) {
                 listener(pendingCall);
             }
             catch (error) {
-                reportBackgroundError(error);
+                reportBackgroundError(error, active.aborts);
             }
         }
         if (active.signal.aborted)
@@ -1183,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);
@@ -1200,6 +1289,7 @@ export function createNestedPlaybookBridge(options) {
                 finished: deferred(),
                 controller,
                 signal: callSignal,
+                aborts: callAborts,
                 phase: 'restoring',
                 childSessionId: seed.childSessionId,
             };
@@ -1214,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, {
@@ -1252,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);
@@ -1265,6 +1357,7 @@ export function createNestedPlaybookBridge(options) {
             finished: deferred(),
             controller,
             signal: callSignal,
+            aborts: callAborts,
             phase: 'starting',
         };
         current = active;
@@ -1273,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,
@@ -1315,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;
                 });
@@ -1332,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)
@@ -1464,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;
@@ -1493,7 +1601,7 @@ export function createNestedPlaybookBridge(options) {
                     listener(pendingCall);
                 }
                 catch (error) {
-                    reportBackgroundError(error);
+                    reportBackgroundError(error, current?.aborts);
                 }
             }
             return () => pendingListeners.delete(listener);
@@ -1521,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() {