@sublang/playbook 12.2.2 → 13.0.0

package/reference/sdlc/decide.playbook/decide.playbook.js

@@ -19,7 +19,7 @@ import { randomUUID } from 'node:crypto';
 import PQueue from 'p-queue';
 import { createActor, fromPromise } from 'xstate';
 import { createAcceptedOutcomeConsumer, } from '../../../src/accepted-outcome.js';
-import { assertJsonSafe, assertPlaybookEffectLedger, assertPlaybookRuntimeSnapshot, combineAbortSignals, createNestedPlaybookBridge, detachPersistedMachineSnapshot, normalizeError, normalizePlaybookSnapshot, PlaybookSemanticCandidateStructureError, reconcilePlaybookSemanticEvidence, renderGovernedOutcomeContract, snapshotJsonValue, snapshotPlaybookSession, validatePlayerResult, waitForPlaybookQuiescence, } from '../../../src/xstate-runtime.js';
+import { assertJsonSafe, assertPlaybookEffectLedger, assertPlaybookRuntimeSnapshot, combineAbortSignals, createNestedPlaybookBridge, detachPersistedMachineSnapshot, normalizeError, normalizePlaybookSnapshot, PlaybookSemanticCandidateStructureError, reconcilePlaybookSemanticEvidence, renderGovernedOutcomeContract, snapshotJsonValue, snapshotPlaybookSession, terminalOutcomesFromMachine, validatePlayerResult, waitForPlaybookQuiescence, } from '../../../src/xstate-runtime.js';
 import decideMachine from './decide.fsm.js';
 function snapshotDecideRuntimeOptions(value) {
     const captured = snapshotJsonValue(value, 'DECIDE runtime options');
@@ -54,6 +54,9 @@ function authoredStateDescriptions(states) {
     return Object.freeze(descriptions);
 }
 const STATE_DESCRIPTIONS = authoredStateDescriptions(decideMachine.config.states);
+// DR-048: each root final state's compiled terminal kind, read from this
+// artifact through the shared reader the factory-backed runtimes use.
+const TERMINAL_KINDS = terminalOutcomesFromMachine(decideMachine, 'DECIDE');
 const ROLE_STATES = [
     { stateId: 'askCoderProposal', role: 'coder', sourceItem: 'DECIDE-1' },
     {
@@ -2814,18 +2817,33 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
             const output = snapshot.output;
             if (output !== undefined)
                 assertJsonSafe(output, 'terminal output');
-            const stateDescription = state.activeStateIds.includes('done')
-                ? STATE_DESCRIPTIONS.done
+            const finalStateId = state.activeStateIds.includes('done')
+                ? 'done'
                 : state.activeStateIds.includes('reportedReviewFailure')
-                    ? STATE_DESCRIPTIONS.reportedReviewFailure
+                    ? 'reportedReviewFailure'
                     : undefined;
-            if (stateDescription === undefined) {
+            const stateDescription = finalStateId === undefined
+                ? undefined
+                : STATE_DESCRIPTIONS[finalStateId];
+            if (finalStateId === undefined || stateDescription === undefined) {
                 throw new Error('decide runtime: completed actor has no authored final-state description');
             }
+            // DR-048: the reached final state's compiled terminal kind, read from
+            // this artifact exactly as the shared factory reads it.
+            const terminalKind = TERMINAL_KINDS.get(finalStateId);
             return {
                 outcome: 'terminal',
                 state,
                 stateDescription,
+                ...(terminalKind === undefined
+                    ? {}
+                    : {
+                        terminal: {
+                            stateId: finalStateId,
+                            kind: terminalKind,
+                            description: stateDescription,
+                        },
+                    }),
                 ...(output === undefined ? {} : { output }),
             };
         }

package/reference/sdlc/decide.playbook/decide.playbook.ts

@@ -41,6 +41,7 @@ import {
   renderGovernedOutcomeContract,
   snapshotJsonValue,
   snapshotPlaybookSession,
+  terminalOutcomesFromMachine,
   validatePlayerResult,
   waitForPlaybookQuiescence,
 } from '../../../src/xstate-runtime.js';
@@ -190,6 +191,10 @@ const STATE_DESCRIPTIONS = authoredStateDescriptions(
     | undefined,
 );
 
+// DR-048: each root final state's compiled terminal kind, read from this
+// artifact through the shared reader the factory-backed runtimes use.
+const TERMINAL_KINDS = terminalOutcomesFromMachine(decideMachine, 'DECIDE');
+
 const ROLE_STATES = [
   { stateId: 'askCoderProposal', role: 'coder', sourceItem: 'DECIDE-1' },
   {
@@ -4247,20 +4252,36 @@ function createDecidePlaybookRuntime(
     if (snapshot.status === 'done') {
       const output = (snapshot as { output?: unknown }).output;
       if (output !== undefined) assertJsonSafe(output, 'terminal output');
-      const stateDescription = state.activeStateIds.includes('done')
-        ? STATE_DESCRIPTIONS.done
+      const finalStateId = state.activeStateIds.includes('done')
+        ? 'done'
         : state.activeStateIds.includes('reportedReviewFailure')
-          ? STATE_DESCRIPTIONS.reportedReviewFailure
+          ? 'reportedReviewFailure'
           : undefined;
-      if (stateDescription === undefined) {
+      const stateDescription =
+        finalStateId === undefined
+          ? undefined
+          : STATE_DESCRIPTIONS[finalStateId];
+      if (finalStateId === undefined || stateDescription === undefined) {
         throw new Error(
           'decide runtime: completed actor has no authored final-state description',
         );
       }
+      // DR-048: the reached final state's compiled terminal kind, read from
+      // this artifact exactly as the shared factory reads it.
+      const terminalKind = TERMINAL_KINDS.get(finalStateId);
       return {
         outcome: 'terminal',
         state,
         stateDescription,
+        ...(terminalKind === undefined
+          ? {}
+          : {
+              terminal: {
+                stateId: finalStateId,
+                kind: terminalKind,
+                description: stateDescription,
+              },
+            }),
         ...(output === undefined ? {} : { output }),
       };
     }

package/reference/sdlc/dev.playbook/dev.fsm.js

@@ -47,6 +47,18 @@ function playbookMeta(stateId, role) {
         },
     };
 }
+// DR-048: a final state additionally declares whether its outcome means the
+// workflow succeeded or failed, so DEV's own caller learns that from the
+// machine rather than from DEV's output fields.
+function terminalMeta(stateId, terminal) {
+    return {
+        playbook: {
+            stateId,
+            description: STATE_DESCRIPTIONS[stateId],
+            terminal,
+        },
+    };
+}
 function isRecord(value) {
     if (value === null || typeof value !== 'object' || Array.isArray(value)) {
         return false;
@@ -172,6 +184,16 @@ function nestedResultFromError(error) {
     const result = error.result;
     return isRecord(result) ? result : undefined;
 }
+function isFailureTerminalRecord(value) {
+    if (!isRecord(value))
+        return false;
+    const allowed = new Set(['stateId', 'kind', 'description']);
+    return (Reflect.ownKeys(value).every((key) => typeof key === 'string' && allowed.has(key)) &&
+        isNonEmptyString(value.stateId) &&
+        value.kind === 'failure' &&
+        (!Object.prototype.hasOwnProperty.call(value, 'description') ||
+            typeof value.description === 'string'));
+}
 function normalizedChildFailure(error, playbookId) {
     const result = nestedResultFromError(error);
     if (result === undefined)
@@ -181,10 +203,12 @@ function normalizedChildFailure(error, playbookId) {
         'playbookId',
         'childSessionId',
         'state',
-        'error',
+        ...(result.status === 'ok' ? ['output', 'terminal'] : ['error']),
     ]);
     if (Reflect.ownKeys(result).some((key) => typeof key !== 'string' || !allowed.has(key)) ||
-        (result.status !== 'aborted' && result.status !== 'error') ||
+        (result.status !== 'aborted' &&
+            result.status !== 'error' &&
+            result.status !== 'ok') ||
         result.playbookId !== playbookId) {
         return undefined;
     }
@@ -192,6 +216,21 @@ function normalizedChildFailure(error, playbookId) {
         !isNonEmptyString(result.childSessionId)) {
         return undefined;
     }
+    if (result.status === 'ok') {
+        if (!Object.prototype.hasOwnProperty.call(result, 'terminal') ||
+            !isFailureTerminalRecord(result.terminal) ||
+            !isNonEmptyString(result.childSessionId) ||
+            (Object.prototype.hasOwnProperty.call(result, 'state') &&
+                !isPlaybookState(result.state))) {
+            return undefined;
+        }
+        return {
+            status: 'ok',
+            ...(result.output === undefined
+                ? {}
+                : { output: result.output }),
+        };
+    }
     if (Object.prototype.hasOwnProperty.call(result, 'state') &&
         !isPlaybookState(result.state)) {
         return undefined;
@@ -233,8 +272,9 @@ function authoredChildFailureGuard(playbookId) {
 function authoredChildError(event, playbookId) {
     const outer = isRecord(event) ? event.error : undefined;
     const failure = normalizedChildFailure(outer, playbookId);
-    if (failure?.error !== undefined)
+    if (failure !== undefined && failure.status !== 'ok' && failure.error) {
         return failure.error;
+    }
     if (failure?.status === 'aborted') {
         return {
             name: 'AbortError',
@@ -249,9 +289,19 @@ function authoredChildError(event, playbookId) {
 function relayedChildFailure(event, playbookId) {
     const outer = isRecord(event) ? event.error : undefined;
     const failure = normalizedChildFailure(outer, playbookId);
+    // DR-048: a completed child that reached an authored failure terminal
+    // relays its own output, exactly as a terminal result that did not prove
+    // success did before it was routed through the error path.
+    if (failure?.status === 'ok') {
+        return {
+            playbookId,
+            status: 'ok',
+            ...(failure.output === undefined ? {} : { output: failure.output }),
+        };
+    }
     return {
         playbookId,
-        status: failure?.status ?? 'error',
+        status: failure?.status === 'aborted' ? 'aborted' : 'error',
         error: authoredChildError(event, playbookId),
     };
 }
@@ -703,19 +753,19 @@ export const devMachine = machineSetup.createMachine({
         discussionComplete: {
             id: 'discussionComplete',
             description: STATE_DESCRIPTIONS.discussionComplete,
-            meta: playbookMeta('discussionComplete'),
+            meta: terminalMeta('discussionComplete', 'success'),
             type: 'final',
         },
         done: {
             id: 'done',
             description: STATE_DESCRIPTIONS.done,
-            meta: playbookMeta('done'),
+            meta: terminalMeta('done', 'success'),
             type: 'final',
         },
         reportedChildFailure: {
             id: 'reportedChildFailure',
             description: STATE_DESCRIPTIONS.reportedChildFailure,
-            meta: playbookMeta('reportedChildFailure'),
+            meta: terminalMeta('reportedChildFailure', 'failure'),
             type: 'final',
         },
     },

package/reference/sdlc/dev.playbook/dev.fsm.ts

@@ -197,6 +197,22 @@ function playbookMeta<StateId extends keyof typeof STATE_DESCRIPTIONS>(
   };
 }
 
+// DR-048: a final state additionally declares whether its outcome means the
+// workflow succeeded or failed, so DEV's own caller learns that from the
+// machine rather than from DEV's output fields.
+function terminalMeta<StateId extends keyof typeof STATE_DESCRIPTIONS>(
+  stateId: StateId,
+  terminal: 'success' | 'failure',
+) {
+  return {
+    playbook: {
+      stateId,
+      description: STATE_DESCRIPTIONS[stateId],
+      terminal,
+    },
+  };
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   if (value === null || typeof value !== 'object' || Array.isArray(value)) {
     return false;
@@ -367,10 +383,32 @@ function nestedResultFromError(
   return isRecord(result) ? result : undefined;
 }
 
-type AuthoredChildFailure = {
-  readonly status: 'aborted' | 'error';
-  readonly error?: CompactError;
-};
+type AuthoredChildFailure =
+  | {
+      readonly status: 'aborted' | 'error';
+      readonly error?: CompactError;
+    }
+  // DR-048: a child that completed at an authored failure terminal. The
+  // bridge rejects it through the same error path, so DEV recognizes the
+  // failure from the child's own machine and never from its output fields.
+  | {
+      readonly status: 'ok';
+      readonly output?: JsonValue;
+    };
+
+function isFailureTerminalRecord(value: unknown): boolean {
+  if (!isRecord(value)) return false;
+  const allowed = new Set(['stateId', 'kind', 'description']);
+  return (
+    Reflect.ownKeys(value).every(
+      (key) => typeof key === 'string' && allowed.has(key),
+    ) &&
+    isNonEmptyString(value.stateId) &&
+    value.kind === 'failure' &&
+    (!Object.prototype.hasOwnProperty.call(value, 'description') ||
+      typeof value.description === 'string')
+  );
+}
 
 function normalizedChildFailure(
   error: unknown,
@@ -383,13 +421,15 @@ function normalizedChildFailure(
     'playbookId',
     'childSessionId',
     'state',
-    'error',
+    ...(result.status === 'ok' ? ['output', 'terminal'] : ['error']),
   ]);
   if (
     Reflect.ownKeys(result).some(
       (key) => typeof key !== 'string' || !allowed.has(key),
     ) ||
-    (result.status !== 'aborted' && result.status !== 'error') ||
+    (result.status !== 'aborted' &&
+      result.status !== 'error' &&
+      result.status !== 'ok') ||
     result.playbookId !== playbookId
   ) {
     return undefined;
@@ -400,6 +440,23 @@ function normalizedChildFailure(
   ) {
     return undefined;
   }
+  if (result.status === 'ok') {
+    if (
+      !Object.prototype.hasOwnProperty.call(result, 'terminal') ||
+      !isFailureTerminalRecord(result.terminal) ||
+      !isNonEmptyString(result.childSessionId) ||
+      (Object.prototype.hasOwnProperty.call(result, 'state') &&
+        !isPlaybookState(result.state))
+    ) {
+      return undefined;
+    }
+    return {
+      status: 'ok',
+      ...(result.output === undefined
+        ? {}
+        : { output: result.output as JsonValue }),
+    };
+  }
   if (
     Object.prototype.hasOwnProperty.call(result, 'state') &&
     !isPlaybookState(result.state)
@@ -453,7 +510,9 @@ function authoredChildError(
 ): CompactError {
   const outer = isRecord(event) ? event.error : undefined;
   const failure = normalizedChildFailure(outer, playbookId);
-  if (failure?.error !== undefined) return failure.error;
+  if (failure !== undefined && failure.status !== 'ok' && failure.error) {
+    return failure.error;
+  }
   if (failure?.status === 'aborted') {
     return {
       name: 'AbortError',
@@ -472,9 +531,19 @@ function relayedChildFailure(
 ): CompletedChildResult {
   const outer = isRecord(event) ? event.error : undefined;
   const failure = normalizedChildFailure(outer, playbookId);
+  // DR-048: a completed child that reached an authored failure terminal
+  // relays its own output, exactly as a terminal result that did not prove
+  // success did before it was routed through the error path.
+  if (failure?.status === 'ok') {
+    return {
+      playbookId,
+      status: 'ok',
+      ...(failure.output === undefined ? {} : { output: failure.output }),
+    };
+  }
   return {
     playbookId,
-    status: failure?.status ?? 'error',
+    status: failure?.status === 'aborted' ? 'aborted' : 'error',
     error: authoredChildError(event, playbookId),
   };
 }
@@ -967,19 +1036,19 @@ export const devMachine = machineSetup.createMachine({
     discussionComplete: {
       id: 'discussionComplete',
       description: STATE_DESCRIPTIONS.discussionComplete,
-      meta: playbookMeta('discussionComplete'),
+      meta: terminalMeta('discussionComplete', 'success'),
       type: 'final',
     },
     done: {
       id: 'done',
       description: STATE_DESCRIPTIONS.done,
-      meta: playbookMeta('done'),
+      meta: terminalMeta('done', 'success'),
       type: 'final',
     },
     reportedChildFailure: {
       id: 'reportedChildFailure',
       description: STATE_DESCRIPTIONS.reportedChildFailure,
-      meta: playbookMeta('reportedChildFailure'),
+      meta: terminalMeta('reportedChildFailure', 'failure'),
       type: 'final',
     },
   },

package/reference/sdlc/review.playbook/review.fsm.js

@@ -104,6 +104,16 @@ const playbookMeta = (stateId, role) => ({
         ...(role === undefined ? {} : { role }),
     },
 });
+// DR-048: a final state additionally declares whether its outcome means the
+// workflow succeeded or failed, so a caller learns that from the machine
+// rather than from REVIEW's output fields.
+const terminalMeta = (stateId, terminal) => ({
+    playbook: {
+        stateId,
+        description: stateDescriptions[stateId],
+        terminal,
+    },
+});
 const outputOf = (event) => event.output;
 const isNonEmptyString = (value) => typeof value === 'string' && value.trim().length > 0;
 const stateMetadata = {
@@ -685,7 +695,7 @@ export const reviewMachine = setup({
         done: {
             id: 'done',
             description: stateDescriptions.done,
-            meta: playbookMeta('done'),
+            meta: terminalMeta('done', 'success'),
             type: 'final',
         },
     },

package/reference/sdlc/review.playbook/review.fsm.ts

@@ -212,6 +212,20 @@ const playbookMeta = <StateId extends keyof typeof stateDescriptions>(
   },
 });
 
+// DR-048: a final state additionally declares whether its outcome means the
+// workflow succeeded or failed, so a caller learns that from the machine
+// rather than from REVIEW's output fields.
+const terminalMeta = <StateId extends keyof typeof stateDescriptions>(
+  stateId: StateId,
+  terminal: 'success' | 'failure',
+) => ({
+  playbook: {
+    stateId,
+    description: stateDescriptions[stateId],
+    terminal,
+  },
+});
+
 const outputOf = (event: unknown): PlayerOutput =>
   (event as PlayerDoneEvent).output;
 
@@ -832,7 +846,7 @@ export const reviewMachine = setup({
     done: {
       id: 'done',
       description: stateDescriptions.done,
-      meta: playbookMeta('done'),
+      meta: terminalMeta('done', 'success'),
       type: 'final',
     },
   },

package/slc/gears2fsm.md

@@ -431,8 +431,11 @@ behavior. The generic `failed` state is the default only when Source declares
 no recovery or reassessment path for a rejected child.
 That recovering `onError` shall be an ordered transition array. Its first arm
 shall use a typed structural guard that accepts only an `Error` carrying a
-validated public child `result` with `status: 'aborted' | 'error'`; only that
-arm appends sanitized child evidence and continues. A fallback arm shall retain
+validated public child `result` that is either `status: 'aborted' | 'error'`
+or `status: 'ok'` with `terminal.kind === 'failure'` — a child that completed
+at its own authored failure terminal, which the bridge delivers through this
+same error path; only that arm appends sanitized child evidence and
+continues. A fallback arm shall retain
 the control error normalized as JSON-safe `{ name, message, stack? }` in
 `lastError` and route to `failed` without appending a completed child result;
 the linked runtime alone retains the original error in its out-of-machine
@@ -444,9 +447,14 @@ result, the error action shall inspect whether its status was `aborted` or
 `error`; it shall not collapse both into an invented success/failure enum. The
 FSM may inspect that public structural data without importing the runner or
 constructing runtime call identities.
+Because a failure terminal reaches `onError`, `onDone` alone proves the child
+succeeded: a caller shall not decide success by inspecting the callee's output
+fields, and shall read those fields only where its own Source relays them.
 For a workflow that reassesses child results, use a typed JSON-safe record such
 as `{ playbookId, status: 'ok', output }` on `onDone` and
-`{ playbookId, status: 'aborted' | 'error', error }` on `onError`. Because the
+`{ playbookId, status: 'aborted' | 'error', error }` on `onError`, with a
+rejected `status: 'ok'` failure terminal recorded in that same `ok` shape so
+the child's own output is relayed. Because the
 runtime rejection is an `Error` with a public `result` property, normalization
 shall inspect `result.status` and `result.error` before applying a generic
 `Error` normalizer. It shall persist only the current context target id, the
@@ -773,6 +781,16 @@ This constrains only published meaning: the declared machine `output` still
 derives its status and fields from typed context, so a caller that does read
 the output is unaffected.
 
+Each final state shall additionally declare `terminal: 'success' | 'failure'`
+in its `meta.playbook`, derived from the Source's own outcome wording exactly
+as the description is: an outcome Source states as the workflow completing is
+`'success'`, and one Source states as a failure the workflow reports instead
+of parking is `'failure'`. The kind is fixed at compile time and adds no agent
+call. The runtime publishes it, with the reached state's id and description, as
+the completed run's terminal record, so this workflow's own caller learns
+whether it succeeded from the machine it reached rather than from these output
+fields.
+
 Where Source declares a JSON-safe terminal result, the setup types shall
 declare that output and the root machine shall derive it from typed context
 through XState's machine `output` function. A final-state transition alone does

package/slc/link.md

@@ -338,6 +338,7 @@ type PlaybookRunResult =
       outcome: 'terminal';
       state: PlaybookState;
       stateDescription?: string;
+      terminal?: PlaybookTerminalOutcome;
       output?: JsonValue;
     }
   | {
@@ -515,6 +516,12 @@ interface PlaybookCallRequest {
   text: string;
 }
 
+interface PlaybookTerminalOutcome {
+  stateId: string;
+  kind: 'success' | 'failure';
+  description?: string;
+}
+
 type PlaybookCallResult =
   | {
       status: 'ok';
@@ -522,6 +529,7 @@ type PlaybookCallResult =
       childSessionId: string;
       state?: PlaybookState;
       output?: JsonValue;
+      terminal?: PlaybookTerminalOutcome;
     }
   | {
       status: 'aborted';
@@ -1448,12 +1456,23 @@ playbook id, and child session id; bind its new turn signal for work resumed in
 the parent; emit and drain the call-finish trace; settle the bridge deferred;
 and use XState `waitFor` to drive the parent to its next
 quiescent, suspended, failed, aborted, or terminal result.
-An `ok` result resolves the actor and reaches `invoke.onDone`; `aborted` and
-`error` results reject it and reach `invoke.onError`.
+An `ok` result whose `terminal.kind` is `success`, and an `ok` result carrying
+no `terminal` record at all, resolve the actor and reach `invoke.onDone`;
+`aborted` and `error` results, and an `ok` result whose `terminal.kind` is
+`failure`, reject it and reach `invoke.onError`.
 The rejection shall be an `Error` whose public readonly `result` property is
 the exact normalized `PlaybookCallResult`; throwing the result object directly
 or discarding its status prevents the FSM from distinguishing abort from
 failure during recovery.
+A completed child's `ok` result carries `terminal` exactly when the child's
+artifact declares its reached final state's kind: the runtime reads
+`meta.playbook.terminal` and that state's authored description from the
+artifact, never from an agent reply, and a declared value other than `success`
+or `failure` is a control-plane error rather than a child outcome.
+Because the bridge routes a failure terminal to the error path, `onDone` alone
+proves the child succeeded and a caller never inspects a callee's output fields
+to decide that; a caller reads those fields only when its own Source relays
+them.
 Unknown, duplicate, or stale call ids reject without changing actor state.
 The finish trace shall therefore precede any parent FSM transition caused by
 the child return.

package/src/runtime.d.ts

@@ -62,12 +62,18 @@ export interface PlaybookCallRequest {
     playbookId: string;
     text: string;
 }
+export interface PlaybookTerminalOutcome {
+    stateId: string;
+    kind: 'success' | 'failure';
+    description?: string;
+}
 export type PlaybookCallResult = {
     status: 'ok';
     playbookId: string;
     childSessionId: string;
     state?: PlaybookState;
     output?: JsonValue;
+    terminal?: PlaybookTerminalOutcome;
 } | {
     status: 'aborted';
     playbookId: string;
@@ -102,6 +108,7 @@ export type PlaybookRunResult = {
     outcome: 'terminal';
     state: PlaybookState;
     stateDescription?: string;
+    terminal?: PlaybookTerminalOutcome;
     output?: JsonValue;
 } | {
     outcome: 'suspended';

package/src/runtime.ts

@@ -98,6 +98,16 @@ export interface PlaybookCallRequest {
   text: string;
 }
 
+// DR-048: the reached final state's compiled terminal meaning. `kind` is
+// authored metadata read from the artifact, never from an agent reply, and
+// `description` repeats that state's authored description when it declares
+// one. An artifact whose final states declare no kind carries no such record.
+export interface PlaybookTerminalOutcome {
+  stateId: string;
+  kind: 'success' | 'failure';
+  description?: string;
+}
+
 export type PlaybookCallResult =
   | {
       status: 'ok';
@@ -105,6 +115,7 @@ export type PlaybookCallResult =
       childSessionId: string;
       state?: PlaybookState;
       output?: JsonValue;
+      terminal?: PlaybookTerminalOutcome;
     }
   | {
       status: 'aborted';
@@ -137,6 +148,7 @@ export type PlaybookRunResult =
       outcome: 'terminal';
       state: PlaybookState;
       stateDescription?: string;
+      terminal?: PlaybookTerminalOutcome;
       output?: JsonValue;
     }
   | {

package/src/xstate-playbook-runtime.d.ts

@@ -468,6 +468,19 @@ export declare function resumableStateIdsFromMachine(machine: AnyStateMachine):
  * these descriptions (DR-029); a state without one has no entry.
  */
 export declare function stateDescriptionsFromMachine(machine: AnyStateMachine): ReadonlyMap<string, string>;
+/**
+ * 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 declare function terminalOutcomesFromMachine(machine: AnyStateMachine, label?: string): ReadonlyMap<string, 'success' | 'failure'>;
 /**
  * Build a `PlaybookRuntimeFactory` that interprets the given FSM artifact
  * under the slc/link.md contract. The factory provides every actor kind the