@sublang/playbook 12.2.2 → 12.3.0

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 &&
@@ -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> {

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));