@sublang/playbook 12.2.2 → 13.0.0

package/src/xstate-playbook-runtime.js

@@ -1073,6 +1073,45 @@ export function stateDescriptionsFromMachine(machine) {
     }
     return descriptions;
 }
+/**
+ * DR-048: each root final state's declared terminal kind, read from
+ * `meta.playbook.terminal` in `machine.config`. The kind is compiled
+ * metadata — the compiler derives it from the Source's own outcome wording,
+ * exactly as it derives the state's description — so a caller learns whether
+ * a completed child succeeded from the machine it reached, never from the
+ * child's output fields or an agent's prose.
+ *
+ * A machine whose final states declare no kind yields an empty map and keeps
+ * the pre-DR-048 delivery. A `terminal` on a non-final state, or a value
+ * other than `success` or `failure`, is a malformed artifact and throws.
+ */
+export function terminalOutcomesFromMachine(machine, label = 'playbook') {
+    const kinds = new Map();
+    const config = machine.config;
+    if (!isPlainObject(config) || !isPlainObject(config.states))
+        return kinds;
+    for (const [key, stateDef] of Object.entries(config.states)) {
+        if (!isPlainObject(stateDef))
+            continue;
+        const playbook = isPlainObject(stateDef.meta)
+            ? stateDef.meta.playbook
+            : undefined;
+        const declared = isPlainObject(playbook) ? playbook.terminal : undefined;
+        if (declared === undefined)
+            continue;
+        if (declared !== 'success' && declared !== 'failure') {
+            throw new TypeError(`${label} state ${key} declares meta.playbook.terminal ` +
+                `${JSON.stringify(declared)}; only 'success' or 'failure' is a ` +
+                'terminal kind');
+        }
+        if (stateDef.type !== 'final') {
+            throw new TypeError(`${label} state ${key} declares meta.playbook.terminal but is not ` +
+                'a final state');
+        }
+        kinds.set(key, declared);
+    }
+    return kinds;
+}
 /**
  * First configured target of `eventType` from the state with `stateId`,
  * falling back to the machine root's own transitions. Used only to pick the
@@ -1834,6 +1873,10 @@ export function createXStatePlaybookRuntime(machine, spec) {
     // DR-029: source state descriptions label the control actions the
     // runtime advertises through `describe()`.
     const stateDescriptions = stateDescriptionsFromMachine(machine);
+    // DR-048: a malformed terminal declaration is a control-plane defect of the
+    // artifact, so it fails construction rather than at the one run that
+    // happens to reach that final state.
+    const terminalKinds = terminalOutcomesFromMachine(machine, label);
     const roleStatesDescriptor = specDescriptors.roleStates;
     if (roleStatesDescriptor !== undefined &&
         !Object.prototype.hasOwnProperty.call(roleStatesDescriptor, 'value')) {
@@ -2804,7 +2847,7 @@ export function createXStatePlaybookRuntime(machine, spec) {
             };
         }
         function detachedPlayerContinuation(roleId, playerId) {
-            return snapshotJsonValue(selectPlayerResume(roleId, playerId), `${label} deferred player continuation`);
+            return snapshotJsonValue({ v: 1, playerId: playerId ?? roleId }, `${label} deferred player continuation`);
         }
         function completionEvidenceFor(input, roleId, playerId, signal, operationId) {
             return async (completion) => {
@@ -4275,10 +4318,18 @@ export function createXStatePlaybookRuntime(machine, spec) {
                 const stateDescription = !hasUnresolvedReconciliation()
                     ? stateDescriptionFor(state)
                     : undefined;
+                // DR-048: the reached final state's compiled terminal meaning, read
+                // from the artifact. It is withheld exactly when the published
+                // description is, so an unresolved reconciliation publishes no
+                // terminal meaning at all.
+                const terminal = hasUnresolvedReconciliation() || state.stateId === undefined
+                    ? undefined
+                    : terminalOutcomeFor(state.stateId, stateDescription);
                 return {
                     outcome,
                     state,
                     ...(stateDescription === undefined ? {} : { stateDescription }),
+                    ...(terminal === undefined ? {} : { terminal }),
                     ...(output === undefined
                         ? {}
                         : {
@@ -4629,6 +4680,18 @@ export function createXStatePlaybookRuntime(machine, spec) {
             }
             return undefined;
         }
+        // DR-048: the public terminal record for a reached final state, present
+        // only for an artifact that declares that state's kind.
+        function terminalOutcomeFor(stateId, description) {
+            const kind = terminalKinds.get(stateId);
+            if (kind === undefined)
+                return undefined;
+            return {
+                stateId,
+                kind,
+                ...(description === undefined ? {} : { description }),
+            };
+        }
         function receiptTracePayload(receipt) {
             return {
                 disposition: receipt.disposition,
@@ -4916,6 +4979,15 @@ export function createXStatePlaybookRuntime(machine, spec) {
                 throw new Error(`${label} deferred continuation requires repository.runDeferred`);
             }
             const effectBoundary = continuationBoundarySeed(operation, turnId);
+            const boundPlayerId = resolvedPlayerId(effectBoundary.roleId);
+            const validateBinding = (value) => {
+                if (!isPlainObject(value) || Object.keys(value).length !== 2 ||
+                    value.v !== 1 ||
+                    value.playerId !== (boundPlayerId ?? effectBoundary.roleId)) {
+                    throw new TypeError(`${label} bound deferred player continuation is invalid`);
+                }
+            };
+            validateBinding(operation.playerContinuation);
             const continuation = {
                 operationId: operation.operationId,
                 effectBoundary,
@@ -4941,18 +5013,8 @@ export function createXStatePlaybookRuntime(machine, spec) {
                     operationId: operation.operationId,
                     effectBoundary,
                     operation: async ({ playerContinuation }) => {
-                        const selectedContinuation = retainedEffectSourceSessionId === undefined
-                            ? playerContinuation
-                            : selectPlayerResume(effectBoundary.roleId, resolvedPlayerId(effectBoundary.roleId));
-                        if (selectedContinuation !== false &&
-                            (typeof selectedContinuation !== 'string' ||
-                                selectedContinuation.trim().length === 0)) {
-                            throw new TypeError(`${label} bound deferred player continuation is invalid`);
-                        }
-                        // Retained adoption owns a fresh Captain-session player ledger;
-                        // no source token becomes target ownership. Same-engagement
-                        // continuation still uses the exact durable binding.
-                        continuation.playerContinuation = selectedContinuation;
+                        validateBinding(playerContinuation);
+                        continuation.playerContinuation = selectPlayerResume(effectBoundary.roleId, boundPlayerId);
                         continuationStarted = true;
                         actor.send(event);
                         // The host has durably started this boundary and the FSM has

package/src/xstate-playbook-runtime.ts

@@ -71,6 +71,7 @@ import type {
   PlaybookSession,
   PlaybookState,
   PlaybookSuspendedCall,
+  PlaybookTerminalOutcome,
   PlaybookTraceEvent,
   PlaybookTraceType,
   PlayerResult,
@@ -1980,6 +1981,50 @@ export function stateDescriptionsFromMachine(
   return descriptions;
 }
 
+/**
+ * DR-048: each root final state's declared terminal kind, read from
+ * `meta.playbook.terminal` in `machine.config`. The kind is compiled
+ * metadata — the compiler derives it from the Source's own outcome wording,
+ * exactly as it derives the state's description — so a caller learns whether
+ * a completed child succeeded from the machine it reached, never from the
+ * child's output fields or an agent's prose.
+ *
+ * A machine whose final states declare no kind yields an empty map and keeps
+ * the pre-DR-048 delivery. A `terminal` on a non-final state, or a value
+ * other than `success` or `failure`, is a malformed artifact and throws.
+ */
+export function terminalOutcomesFromMachine(
+  machine: AnyStateMachine,
+  label = 'playbook',
+): ReadonlyMap<string, 'success' | 'failure'> {
+  const kinds = new Map<string, 'success' | 'failure'>();
+  const config = (machine as unknown as { config?: unknown }).config;
+  if (!isPlainObject(config) || !isPlainObject(config.states)) return kinds;
+  for (const [key, stateDef] of Object.entries(config.states)) {
+    if (!isPlainObject(stateDef)) continue;
+    const playbook = isPlainObject(stateDef.meta)
+      ? (stateDef.meta as Record<string, unknown>).playbook
+      : undefined;
+    const declared = isPlainObject(playbook) ? playbook.terminal : undefined;
+    if (declared === undefined) continue;
+    if (declared !== 'success' && declared !== 'failure') {
+      throw new TypeError(
+        `${label} state ${key} declares meta.playbook.terminal ` +
+          `${JSON.stringify(declared)}; only 'success' or 'failure' is a ` +
+          'terminal kind',
+      );
+    }
+    if (stateDef.type !== 'final') {
+      throw new TypeError(
+        `${label} state ${key} declares meta.playbook.terminal but is not ` +
+          'a final state',
+      );
+    }
+    kinds.set(key, declared);
+  }
+  return kinds;
+}
+
 /**
  * First configured target of `eventType` from the state with `stateId`,
  * falling back to the machine root's own transitions. Used only to pick the
@@ -3075,6 +3120,10 @@ export function createXStatePlaybookRuntime<
   // DR-029: source state descriptions label the control actions the
   // runtime advertises through `describe()`.
   const stateDescriptions = stateDescriptionsFromMachine(machine);
+  // DR-048: a malformed terminal declaration is a control-plane defect of the
+  // artifact, so it fails construction rather than at the one run that
+  // happens to reach that final state.
+  const terminalKinds = terminalOutcomesFromMachine(machine, label);
   const roleStatesDescriptor = specDescriptors.roleStates;
   if (
     roleStatesDescriptor !== undefined &&
@@ -4474,7 +4523,7 @@ export function createXStatePlaybookRuntime<
       playerId: string | undefined,
     ): JsonValue {
       return snapshotJsonValue(
-        selectPlayerResume(roleId, playerId),
+        { v: 1, playerId: playerId ?? roleId },
         `${label} deferred player continuation`,
       );
     }
@@ -6477,10 +6526,19 @@ export function createXStatePlaybookRuntime<
           !hasUnresolvedReconciliation()
             ? stateDescriptionFor(state)
             : undefined;
+        // DR-048: the reached final state's compiled terminal meaning, read
+        // from the artifact. It is withheld exactly when the published
+        // description is, so an unresolved reconciliation publishes no
+        // terminal meaning at all.
+        const terminal =
+          hasUnresolvedReconciliation() || state.stateId === undefined
+            ? undefined
+            : terminalOutcomeFor(state.stateId, stateDescription);
         return {
           outcome,
           state,
           ...(stateDescription === undefined ? {} : { stateDescription }),
+          ...(terminal === undefined ? {} : { terminal }),
           ...(output === undefined
             ? {}
             : {
@@ -6867,6 +6925,21 @@ export function createXStatePlaybookRuntime<
       return undefined;
     }
 
+    // DR-048: the public terminal record for a reached final state, present
+    // only for an artifact that declares that state's kind.
+    function terminalOutcomeFor(
+      stateId: string,
+      description: string | undefined,
+    ): PlaybookTerminalOutcome | undefined {
+      const kind = terminalKinds.get(stateId);
+      if (kind === undefined) return undefined;
+      return {
+        stateId,
+        kind,
+        ...(description === undefined ? {} : { description }),
+      };
+    }
+
     function receiptTracePayload(
       receipt: PlaybookControlReceipt,
     ): Record<string, unknown> {
@@ -7251,6 +7324,15 @@ export function createXStatePlaybookRuntime<
         );
       }
       const effectBoundary = continuationBoundarySeed(operation, turnId);
+      const boundPlayerId = resolvedPlayerId(effectBoundary.roleId);
+      const validateBinding = (value: unknown): void => {
+        if (!isPlainObject(value) || Object.keys(value).length !== 2 ||
+            value.v !== 1 ||
+            value.playerId !== (boundPlayerId ?? effectBoundary.roleId)) {
+          throw new TypeError(`${label} bound deferred player continuation is invalid`);
+        }
+      };
+      validateBinding(operation.playerContinuation);
       const continuation: NonNullable<typeof activeDeferredContinuation> = {
         operationId: operation.operationId,
         effectBoundary,
@@ -7276,26 +7358,10 @@ export function createXStatePlaybookRuntime<
           operationId: operation.operationId,
           effectBoundary,
           operation: async ({ playerContinuation }) => {
-            const selectedContinuation =
-              retainedEffectSourceSessionId === undefined
-                ? playerContinuation
-                : selectPlayerResume(
-                    effectBoundary.roleId,
-                    resolvedPlayerId(effectBoundary.roleId),
-                  );
-            if (
-              selectedContinuation !== false &&
-              (typeof selectedContinuation !== 'string' ||
-                selectedContinuation.trim().length === 0)
-            ) {
-              throw new TypeError(
-                `${label} bound deferred player continuation is invalid`,
-              );
-            }
-            // Retained adoption owns a fresh Captain-session player ledger;
-            // no source token becomes target ownership. Same-engagement
-            // continuation still uses the exact durable binding.
-            continuation.playerContinuation = selectedContinuation;
+            validateBinding(playerContinuation);
+            continuation.playerContinuation = selectPlayerResume(
+              effectBoundary.roleId, boundPlayerId,
+            );
             continuationStarted = true;
             actor!.send(event);
             // The host has durably started this boundary and the FSM has

package/src/xstate-runtime.js

@@ -1617,7 +1617,13 @@ export function assertPlaybookRuntimeSnapshot(value, expectedPlaybookId, options
 export class NestedPlaybookCallError extends Error {
     result;
     constructor(result) {
-        const fallback = `Child playbook ${result.playbookId} ${result.status}`;
+        // DR-048: a completed child that reached an authored failure terminal is
+        // rejected through the same error path as an abort or an error, so its
+        // message names that final state rather than reporting `ok`.
+        const fallback = result.status === 'ok'
+            ? `Child playbook ${result.playbookId} reached failure terminal ` +
+                `${result.terminal?.stateId ?? 'unknown'}`
+            : `Child playbook ${result.playbookId} ${result.status}`;
         const normalized = result.status === 'ok' ? undefined : result.error;
         super(normalized?.message ?? fallback);
         this.name = normalized?.name ?? 'NestedPlaybookCallError';
@@ -1723,6 +1729,26 @@ function validateNormalizedError(error, path) {
         throw new TypeError(`${path}.stack must be a string`);
     }
 }
+// DR-048: the completed child's compiled terminal record. It is runtime-owned
+// data read from the child's artifact, so a malformed one is a control-plane
+// error rather than an authored child outcome.
+function validateTerminalOutcome(value) {
+    if (!isRecord(value)) {
+        throw new TypeError('playbook result terminal must be an object');
+    }
+    rejectUnknownKeys(value, ['stateId', 'kind', 'description'], 'playbook result terminal');
+    requireNonEmptyString(value.stateId, 'playbook result terminal stateId');
+    if (value.kind !== 'success' && value.kind !== 'failure') {
+        throw new TypeError("playbook result terminal kind must be 'success' or 'failure'");
+    }
+    if (own(value, 'description') && typeof value.description !== 'string') {
+        throw new TypeError('playbook result terminal description must be a string');
+    }
+}
+/** DR-048: a completed child that reached an authored failure terminal. */
+function isFailureTerminal(result) {
+    return result.status === 'ok' && result.terminal?.kind === 'failure';
+}
 export function validatePlaybookCallResult(result, expectedPlaybookId, expectedChildSessionId) {
     const capturedResult = snapshotJsonValue(result, 'playbook result');
     if (!isRecord(capturedResult)) {
@@ -1737,8 +1763,11 @@ export function validatePlaybookCallResult(result, expectedPlaybookId, expectedC
         throw new PlaybookCallIdentityError(`playbook result target ${String(capturedResult.playbookId)} does not match ${expectedPlaybookId}`);
     }
     if (capturedResult.status === 'ok') {
-        rejectUnknownKeys(capturedResult, ['status', 'playbookId', 'childSessionId', 'state', 'output'], 'playbook result');
+        rejectUnknownKeys(capturedResult, ['status', 'playbookId', 'childSessionId', 'state', 'output', 'terminal'], 'playbook result');
         requireNonEmptyString(capturedResult.childSessionId, 'playbook result childSessionId');
+        if (own(capturedResult, 'terminal')) {
+            validateTerminalOutcome(capturedResult.terminal);
+        }
     }
     else {
         rejectUnknownKeys(capturedResult, ['status', 'playbookId', 'childSessionId', 'state', 'error'], 'playbook result');
@@ -1832,8 +1861,9 @@ function resultFromThrown(playbookId, childSessionId, error, aborted) {
     return snapshotJsonValue(result, 'playbook result');
 }
 function outputOrThrow(result) {
-    if (result.status === 'ok')
+    if (result.status === 'ok' && !isFailureTerminal(result)) {
         return result.output;
+    }
     throw new NestedPlaybookCallError(result);
 }
 export function createNestedPlaybookBridge(options) {
@@ -2014,7 +2044,8 @@ export function createNestedPlaybookBridge(options) {
             else if (cleanupControlError !== undefined) {
                 active.deferred.reject(cleanupControlError);
             }
-            else if (effectiveResult.status === 'ok') {
+            else if (effectiveResult.status === 'ok' &&
+                !isFailureTerminal(effectiveResult)) {
                 active.deferred.resolve(effectiveResult.output);
             }
             else {

package/src/xstate-runtime.ts

@@ -2596,7 +2596,14 @@ export class NestedPlaybookCallError extends Error {
   readonly result: PlaybookCallResult;
 
   constructor(result: PlaybookCallResult) {
-    const fallback = `Child playbook ${result.playbookId} ${result.status}`;
+    // DR-048: a completed child that reached an authored failure terminal is
+    // rejected through the same error path as an abort or an error, so its
+    // message names that final state rather than reporting `ok`.
+    const fallback =
+      result.status === 'ok'
+        ? `Child playbook ${result.playbookId} reached failure terminal ` +
+          `${result.terminal?.stateId ?? 'unknown'}`
+        : `Child playbook ${result.playbookId} ${result.status}`;
     const normalized = result.status === 'ok' ? undefined : result.error;
     super(normalized?.message ?? fallback);
     this.name = normalized?.name ?? 'NestedPlaybookCallError';
@@ -2794,6 +2801,36 @@ function validateNormalizedError(error: unknown, path: string): void {
   }
 }
 
+// DR-048: the completed child's compiled terminal record. It is runtime-owned
+// data read from the child's artifact, so a malformed one is a control-plane
+// error rather than an authored child outcome.
+function validateTerminalOutcome(value: unknown): void {
+  if (!isRecord(value)) {
+    throw new TypeError('playbook result terminal must be an object');
+  }
+  rejectUnknownKeys(
+    value,
+    ['stateId', 'kind', 'description'],
+    'playbook result terminal',
+  );
+  requireNonEmptyString(value.stateId, 'playbook result terminal stateId');
+  if (value.kind !== 'success' && value.kind !== 'failure') {
+    throw new TypeError(
+      "playbook result terminal kind must be 'success' or 'failure'",
+    );
+  }
+  if (own(value, 'description') && typeof value.description !== 'string') {
+    throw new TypeError(
+      'playbook result terminal description must be a string',
+    );
+  }
+}
+
+/** DR-048: a completed child that reached an authored failure terminal. */
+function isFailureTerminal(result: PlaybookCallResult): boolean {
+  return result.status === 'ok' && result.terminal?.kind === 'failure';
+}
+
 export function validatePlaybookCallResult(
   result: unknown,
   expectedPlaybookId: string,
@@ -2818,13 +2855,16 @@ export function validatePlaybookCallResult(
   if (capturedResult.status === 'ok') {
     rejectUnknownKeys(
       capturedResult,
-      ['status', 'playbookId', 'childSessionId', 'state', 'output'],
+      ['status', 'playbookId', 'childSessionId', 'state', 'output', 'terminal'],
       'playbook result',
     );
     requireNonEmptyString(
       capturedResult.childSessionId,
       'playbook result childSessionId',
     );
+    if (own(capturedResult, 'terminal')) {
+      validateTerminalOutcome(capturedResult.terminal);
+    }
   } else {
     rejectUnknownKeys(
       capturedResult,
@@ -2973,7 +3013,9 @@ function resultFromThrown(
 }
 
 function outputOrThrow(result: PlaybookCallResult): JsonValue | undefined {
-  if (result.status === 'ok') return result.output;
+  if (result.status === 'ok' && !isFailureTerminal(result)) {
+    return result.output;
+  }
   throw new NestedPlaybookCallError(result);
 }
 
@@ -3206,7 +3248,10 @@ export function createNestedPlaybookBridge<
         active.deferred.reject(controlError);
       } else if (cleanupControlError !== undefined) {
         active.deferred.reject(cleanupControlError);
-      } else if (effectiveResult.status === 'ok') {
+      } else if (
+        effectiveResult.status === 'ok' &&
+        !isFailureTerminal(effectiveResult)
+      ) {
         active.deferred.resolve(effectiveResult.output);
       } else {
         active.deferred.reject(new NestedPlaybookCallError(effectiveResult));