@sublang/playbook 12.2.2 → 12.3.0

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

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')) {
@@ -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,