@sublang/playbook 17.8.1 → 17.9.0

package/src/xstate-playbook-runtime.js

@@ -569,6 +569,9 @@ function pendingBossQuestionRecord(pending) {
 // Generic strategy defaults.
 // ---------------------------------------------------------------------------
 const CONTINUATION_PREAMBLE = 'Continue the same task using Boss’s reply below.';
+// The labelled continuation a compiled artifact's composer renders, which
+// slc's prompt-contract verifier pins. The runtime no longer sends it: it
+// hands a composer no question and reply, and marks them itself (DR-090 §2).
 function continuationBlocks(input, resuming = false) {
     if (input.pendingBossQuestion === undefined || input.bossReply === undefined) {
         return [];
@@ -579,6 +582,59 @@ function continuationBlocks(input, resuming = false) {
         `Boss reply:\n${input.bossReply}`,
     ];
 }
+// DR-090 §2: a Boss exchange reaches a player as structure, not as an
+// English instruction — a marker line before each question and each reply,
+// whatever language the run speaks.
+const BOSS_QUESTION_MARKER = '? ⟶';
+const BOSS_REPLY_MARKER = 'Boss ⟶';
+function bossQuestionBlock(question) {
+    return `${BOSS_QUESTION_MARKER}\n${question}`;
+}
+function bossReplyBlock(reply) {
+    return `${BOSS_REPLY_MARKER}\n${reply}`;
+}
+/** DR-090 §2: the marked continuation of a call after a Boss reply. */
+function markedContinuationBlocks(input, resuming = false) {
+    if (input.pendingBossQuestion === undefined || input.bossReply === undefined) {
+        return [];
+    }
+    return [
+        ...(resuming ? [] : [bossQuestionBlock(input.pendingBossQuestion.question)]),
+        bossReplyBlock(input.bossReply),
+    ];
+}
+/**
+ * The input a composer receives: without the question and reply, which the
+ * runtime marks itself (DR-090 §2), so a composer adds no labelled blocks.
+ */
+function withoutContinuation(input) {
+    if (input.pendingBossQuestion === undefined && input.bossReply === undefined) {
+        return input;
+    }
+    const { pendingBossQuestion: _question, bossReply: _reply, ...rest } = input;
+    return rest;
+}
+/**
+ * DR-090 §1: the run's Boss exchanges a player call carries before its body,
+ * leaving out the one exchange the call's own continuation blocks carry, so
+ * the asking role reads its answered question once.
+ */
+function bossExchangeBlocks(exchanges, input) {
+    let carried = -1;
+    if (input.pendingBossQuestion !== undefined && input.bossReply !== undefined) {
+        const question = input.pendingBossQuestion.question;
+        for (let index = exchanges.length - 1; index >= 0; index -= 1) {
+            const exchange = exchanges[index];
+            if (exchange.question === question && exchange.reply === input.bossReply) {
+                carried = index;
+                break;
+            }
+        }
+    }
+    return exchanges.flatMap((exchange, index) => index === carried
+        ? []
+        : [bossQuestionBlock(exchange.question), bossReplyBlock(exchange.reply)]);
+}
 /** Add clarification context without repeating the question in a live conversation. */
 export function composePlayerContinuation(input, body, resuming = false) {
     return [...continuationBlocks(input, resuming), body].join('\n\n');
@@ -2005,8 +2061,9 @@ function snapshotOutcomeAuthority(descriptor, label, playerStates, verbatimPaylo
 // the machine's transition selection — guards only, no action runs — with
 // sample values, and the first combination of shapes whose arm carries that
 // outcome's accepted-outcome marker is the contract the judge is shown and the
-// reconciler enforces. A field whose shape the machine does not reveal, or
-// that it admits as a string, stays a string.
+// reconciler enforces. A field the machine admits as a string is recorded as
+// one; a field whose shape it does not reveal is recorded with none, so the
+// reconciler leaves its value to the machine's own validator (DR-091).
 // ---------------------------------------------------------------------------
 const SEMANTIC_SHAPE_SAMPLES = [
     ['string', 'sample'],
@@ -2045,9 +2102,10 @@ function shapeCombinations(fieldCount) {
         left.join(',').localeCompare(right.join(',')));
 }
 /**
- * DR-089: the non-string JSON value shape the compiled machine admits for
- * each semantic-owned field of each governed outcome, keyed by state id and
- * then by outcome. Exported so linked machinery of an artifact's own reads
+ * DR-089: the JSON value shape the compiled machine admits for each
+ * semantic-owned field of each governed outcome, keyed by state id and then
+ * by outcome. A field, outcome, or state the probe reveals no shape for is
+ * left out (DR-091). Exported so linked machinery of an artifact's own reads
  * the same contract the shared factory enforces.
  */
 export function inferSemanticValueShapes(machine, authority) {
@@ -2127,18 +2185,17 @@ export function inferSemanticValueShapes(machine, authority) {
                 });
                 if (!admits(values))
                     continue;
+                // DR-091: an admitted string is recorded too, so only a field the
+                // probe revealed nothing for goes unrecorded.
                 const shapes = {};
                 semanticFields.forEach((field, index) => {
                     let shape = SEMANTIC_SHAPE_SAMPLES[combination[index]][0];
                     if (shape === 'string-array' && admits({ ...values, [field]: [1] })) {
                         shape = 'string-or-number-array';
                     }
-                    if (shape !== 'string')
-                        shapes[field] = shape;
+                    shapes[field] = shape;
                 });
-                if (Object.keys(shapes).length > 0) {
-                    stateShapes[guard] = Object.freeze(shapes);
-                }
+                stateShapes[guard] = Object.freeze(shapes);
                 break;
             }
         }
@@ -2715,8 +2772,13 @@ export function createXStatePlaybookRuntime(machine, spec) {
     }
     const composePlayerPrompt = spec.composePlayerPrompt ??
         ((input, _identity, resuming = false) => defaultComposePlayerPrompt(input, spec.placeholderFields, resuming));
-    const composeCaptainPrompt = spec.composeCaptainPrompt ??
+    const composeArtifactCaptainPrompt = spec.composeCaptainPrompt ??
         ((input) => defaultComposeCaptainPrompt(input, spec.placeholderFields));
+    // DR-090 §2: a direct-Captain continuation is marked by the runtime too.
+    const composeCaptainPrompt = (input) => [
+        ...markedContinuationBlocks(input),
+        composeArtifactCaptainPrompt(withoutContinuation(input)),
+    ].join('\n\n');
     const extractFields = spec.extractRequiredFields ?? defaultExtractRequiredFields;
     const verbatimPayloadFields = new Set(spec.verbatimPayloadFields ?? NO_VERBATIM_FIELDS);
     const adjudication = {
@@ -2865,6 +2927,9 @@ export function createXStatePlaybookRuntime(machine, spec) {
         const currentEffectLedger = () => assertPlaybookEffectLedger(effectLedgerCapability.snapshot(), `${label} current host effect ledger`);
         let effectLedgerMirror = currentEffectLedger();
         let recoveryCheckpoint;
+        // DR-090 §1: the run's Boss exchanges, in order. A run begins at the
+        // artifact's entry event; the list travels in the snapshot.
+        let bossExchanges = [];
         let retainedEffectSourceSessionId;
         let retainedEffectReconciliation;
         let retainedEffectReconciliationRequired = false;
@@ -3495,7 +3560,17 @@ export function createXStatePlaybookRuntime(machine, spec) {
             }
             return session?.roleBindings?.[roleId]?.promptIdentity ?? roleId;
         }
+        // DR-090 §3: the first block names the role and, where the host bound
+        // it, the model the call runs on as configured, so a player can name
+        // both where its project asks (a commit trailer, say).
+        function playerIdentityBlock(roleId) {
+            const binding = session?.roleBindings?.[roleId];
+            return binding === undefined
+                ? `Role: ${roleId}`
+                : `Role: ${roleId} · Model: ${binding.promptIdentity}`;
+        }
         function composeBoundPlayerPrompt(input, resuming = false) {
+            const roleId = requireRoleId(input);
             let active = true;
             const lookup = (roleId) => {
                 if (!active) {
@@ -3503,12 +3578,44 @@ export function createXStatePlaybookRuntime(machine, spec) {
                 }
                 return promptIdentity(roleId);
             };
+            let body;
             try {
-                return composePlayerPrompt(input, lookup, resuming);
+                body = composePlayerPrompt(withoutContinuation(input), lookup, resuming);
             }
             finally {
                 active = false;
             }
+            // DR-090 §1, §2: every role hears the Boss — the run's exchanges come
+            // before the body whatever the role, and the asking role's marked
+            // continuation carries the exchange it asked.
+            return [
+                playerIdentityBlock(roleId),
+                ...bossExchangeBlocks(bossExchanges, input),
+                ...markedContinuationBlocks(input, resuming),
+                body,
+            ].join('\n\n');
+        }
+        /** DR-090 §1: record a Boss reply the machine is about to receive. */
+        function recordBossExchange(event, pending) {
+            if (event.type !== 'BOSS_REPLY')
+                return;
+            const { questionId, answer } = event;
+            if (typeof answer !== 'string' || answer.trim().length === 0)
+                return;
+            const question = pending.find((candidate) => candidate.questionId === questionId) ??
+                (questionId === undefined && pending.length === 1 ? pending[0] : undefined);
+            if (question === undefined)
+                return;
+            bossExchanges = Object.freeze([
+                ...bossExchanges,
+                Object.freeze({ question: question.question, reply: answer }),
+            ]);
+        }
+        /** DR-090 §1: an entry event begins a new run, with no exchanges yet. */
+        function beginRunIfEntry(event) {
+            if (spec.entryEvent !== undefined && event.type === spec.entryEvent.type) {
+                bossExchanges = [];
+            }
         }
         function continuationKey(roleId, playerId) {
             return playerId ?? roleId;
@@ -4372,7 +4479,10 @@ export function createXStatePlaybookRuntime(machine, spec) {
             try {
                 await claim.assertOwner();
                 const restored = snapshotJsonValue(await repositoryCapability.observe());
-                if (!isDeepStrictEqual(restored, saved.baseline)) {
+                // DR-090 §4: the branch an observation names is never compared.
+                const { branch: _restoredBranch, ...restoredState } = restored;
+                const { branch: _savedBranch, ...savedState } = saved.baseline;
+                if (!isDeepStrictEqual(restoredState, savedState)) {
                     throw new Error(`${label} preparation has not restored the stopped step's repository; it remains paused`);
                 }
                 signal.throwIfAborted();
@@ -4580,6 +4690,14 @@ export function createXStatePlaybookRuntime(machine, spec) {
                 ...((state.stateId === 'failed' || pendingQuestions.length > 0) && recoveryCheckpoint !== undefined
                     ? { recoveryCheckpoint } : {}),
                 ...(suspendedCall === undefined ? {} : { suspendedCall }),
+                ...(bossExchanges.length === 0
+                    ? {}
+                    : {
+                        bossExchanges: bossExchanges.map(({ question, reply }) => ({
+                            question,
+                            reply,
+                        })),
+                    }),
             };
         }
         async function runJournalledStep(kind, input, signal, execute) {
@@ -6354,6 +6472,7 @@ export function createXStatePlaybookRuntime(machine, spec) {
             deferInspectionEmissions = false;
             deferredInspectionEmissions = [];
             recoveryCheckpoint = undefined;
+            bossExchanges = [];
             suppressInspectionEmissions = false;
             initialized = false;
             traceSequence = 0;
@@ -6706,6 +6825,9 @@ export function createXStatePlaybookRuntime(machine, spec) {
                     }
                     restoreRoleResumeTokens(boundSnapshot.roleResumeTokens);
                 }
+                // DR-090 §1: a restored or adopted run keeps the Boss exchanges it
+                // heard; a snapshot without them heard none.
+                bossExchanges = Object.freeze((boundSnapshot.bossExchanges ?? []).map(({ question, reply }) => Object.freeze({ question, reply })));
                 nestedBridge.prepareRestore(suspendedCall);
                 if (suspendedCall !== undefined) {
                     playbookCallTurnIds.set(suspendedCall.callId, suspendedCall.turnId);
@@ -7671,7 +7793,14 @@ export function createXStatePlaybookRuntime(machine, spec) {
                             deferredOperation !== undefined) {
                             if (isExactDeferredBossReply(classifiedSnapshot, event, deferredPending)) {
                                 const statusLine = classificationStatus(event);
-                                const continuation = await continueBoundDeferredOperation(deferredOperation, event, signal, turnId, statusLine, onAccepted);
+                                const acceptedPending = deferredPending;
+                                const acceptedEvent = event;
+                                const continuation = await continueBoundDeferredOperation(deferredOperation, event, signal, turnId, statusLine, () => {
+                                    // DR-090 §1: the host started the continuation, so the
+                                    // machine receives this reply now.
+                                    recordBossExchange(acceptedEvent, [acceptedPending]);
+                                    onAccepted?.();
+                                });
                                 if (continuation === 'continued') {
                                     if (controlPlaneError !== undefined) {
                                         throw controlPlaneError;
@@ -7715,13 +7844,21 @@ export function createXStatePlaybookRuntime(machine, spec) {
                             signal.throwIfAborted();
                             // 3. A final actor cannot accept new events; reconstruct only
                             //    after classification produced a real event.
+                            const acceptedPending = classifiedSnapshot === undefined
+                                ? []
+                                : pendingBossQuestionsFor(normalizePlaybookSnapshot(classifiedSnapshot), (classifiedSnapshot.context ??
+                                    {}));
                             if (actor.getSnapshot().status === 'done') {
                                 stopActor();
                                 actor = buildActor(runtimePorts);
                                 // The replacement actor's snapshots are real state entries.
                                 suppressInspectionEmissions = false;
                                 actor.start();
+                                // DR-090 §1: a finished run's exchanges end with it.
+                                bossExchanges = [];
                             }
+                            beginRunIfEntry(event);
+                            recordBossExchange(event, acceptedPending);
                             onAccepted?.();
                             actor.send(event);
                             await waitForPlaybookQuiescence(actor, {
@@ -8002,6 +8139,7 @@ export function createXStatePlaybookRuntime(machine, spec) {
                         failedGovernedAttemptId = undefined;
                         controlPlaneError = undefined;
                         emissionFailure = undefined;
+                        bossExchanges = [];
                         retainedEffectSourceSessionId = undefined;
                         retainedEffectReconciliation = undefined;
                         retainedEffectReconciliationRequired = false;

package/src/xstate-playbook-runtime.ts

@@ -58,6 +58,7 @@ import type {
   CaptainResult,
   JsonValue,
   PlaybookAdoptionContext,
+  PlaybookBossExchange,
   PlaybookCallResult,
   PlaybookControlAction,
   PlaybookControlReceipt,
@@ -1327,6 +1328,9 @@ function pendingBossQuestionRecord(
 const CONTINUATION_PREAMBLE =
   'Continue the same task using Boss’s reply below.';
 
+// The labelled continuation a compiled artifact's composer renders, which
+// slc's prompt-contract verifier pins. The runtime no longer sends it: it
+// hands a composer no question and reply, and marks them itself (DR-090 §2).
 function continuationBlocks(input: {
   pendingBossQuestion?: { readonly question: string };
   bossReply?: string;
@@ -1341,6 +1345,76 @@ function continuationBlocks(input: {
   ];
 }
 
+// DR-090 §2: a Boss exchange reaches a player as structure, not as an
+// English instruction — a marker line before each question and each reply,
+// whatever language the run speaks.
+const BOSS_QUESTION_MARKER = '? ⟶';
+const BOSS_REPLY_MARKER = 'Boss ⟶';
+
+function bossQuestionBlock(question: string): string {
+  return `${BOSS_QUESTION_MARKER}\n${question}`;
+}
+
+function bossReplyBlock(reply: string): string {
+  return `${BOSS_REPLY_MARKER}\n${reply}`;
+}
+
+/** DR-090 §2: the marked continuation of a call after a Boss reply. */
+function markedContinuationBlocks(input: {
+  pendingBossQuestion?: { readonly question: string };
+  bossReply?: string;
+}, resuming = false): string[] {
+  if (input.pendingBossQuestion === undefined || input.bossReply === undefined) {
+    return [];
+  }
+  return [
+    ...(resuming ? [] : [bossQuestionBlock(input.pendingBossQuestion.question)]),
+    bossReplyBlock(input.bossReply),
+  ];
+}
+
+/**
+ * The input a composer receives: without the question and reply, which the
+ * runtime marks itself (DR-090 §2), so a composer adds no labelled blocks.
+ */
+function withoutContinuation<T extends {
+  pendingBossQuestion?: unknown;
+  bossReply?: unknown;
+}>(input: T): T {
+  if (input.pendingBossQuestion === undefined && input.bossReply === undefined) {
+    return input;
+  }
+  const { pendingBossQuestion: _question, bossReply: _reply, ...rest } = input;
+  return rest as T;
+}
+
+/**
+ * DR-090 §1: the run's Boss exchanges a player call carries before its body,
+ * leaving out the one exchange the call's own continuation blocks carry, so
+ * the asking role reads its answered question once.
+ */
+function bossExchangeBlocks(
+  exchanges: readonly PlaybookBossExchange[],
+  input: Pick<PlaybookPlayerInput, 'pendingBossQuestion' | 'bossReply'>,
+): string[] {
+  let carried = -1;
+  if (input.pendingBossQuestion !== undefined && input.bossReply !== undefined) {
+    const question = input.pendingBossQuestion.question;
+    for (let index = exchanges.length - 1; index >= 0; index -= 1) {
+      const exchange = exchanges[index]!;
+      if (exchange.question === question && exchange.reply === input.bossReply) {
+        carried = index;
+        break;
+      }
+    }
+  }
+  return exchanges.flatMap((exchange, index) =>
+    index === carried
+      ? []
+      : [bossQuestionBlock(exchange.question), bossReplyBlock(exchange.reply)],
+  );
+}
+
 /** Add clarification context without repeating the question in a live conversation. */
 export function composePlayerContinuation(
   input: Pick<PlaybookPlayerInput, 'pendingBossQuestion' | 'bossReply'>,
@@ -3273,8 +3347,9 @@ function snapshotOutcomeAuthority(
 // the machine's transition selection — guards only, no action runs — with
 // sample values, and the first combination of shapes whose arm carries that
 // outcome's accepted-outcome marker is the contract the judge is shown and the
-// reconciler enforces. A field whose shape the machine does not reveal, or
-// that it admits as a string, stays a string.
+// reconciler enforces. A field the machine admits as a string is recorded as
+// one; a field whose shape it does not reveal is recorded with none, so the
+// reconciler leaves its value to the machine's own validator (DR-091).
 // ---------------------------------------------------------------------------
 
 const SEMANTIC_SHAPE_SAMPLES: readonly (readonly [
@@ -3337,9 +3412,10 @@ function shapeCombinations(fieldCount: number): readonly number[][] {
 }
 
 /**
- * DR-089: the non-string JSON value shape the compiled machine admits for
- * each semantic-owned field of each governed outcome, keyed by state id and
- * then by outcome. Exported so linked machinery of an artifact's own reads
+ * DR-089: the JSON value shape the compiled machine admits for each
+ * semantic-owned field of each governed outcome, keyed by state id and then
+ * by outcome. A field, outcome, or state the probe reveals no shape for is
+ * left out (DR-091). Exported so linked machinery of an artifact's own reads
  * the same contract the shared factory enforces.
  */
 export function inferSemanticValueShapes(
@@ -3425,17 +3501,17 @@ export function inferSemanticValueShapes(
           values[field] = SEMANTIC_SHAPE_SAMPLES[combination[index]!]![1];
         });
         if (!admits(values)) continue;
+        // DR-091: an admitted string is recorded too, so only a field the
+        // probe revealed nothing for goes unrecorded.
         const shapes: Record<string, PlaybookSemanticValueShape> = {};
         semanticFields.forEach((field, index) => {
           let shape = SEMANTIC_SHAPE_SAMPLES[combination[index]!]![0];
           if (shape === 'string-array' && admits({ ...values, [field]: [1] })) {
             shape = 'string-or-number-array';
           }
-          if (shape !== 'string') shapes[field] = shape;
+          shapes[field] = shape;
         });
-        if (Object.keys(shapes).length > 0) {
-          stateShapes[guard] = Object.freeze(shapes);
-        }
+        stateShapes[guard] = Object.freeze(shapes);
         break;
       }
     }
@@ -4269,10 +4345,16 @@ export function createXStatePlaybookRuntime<
     spec.composePlayerPrompt ??
     ((input: PlaybookPlayerInput, _identity: XStatePromptIdentity, resuming = false) =>
       defaultComposePlayerPrompt(input, spec.placeholderFields, resuming));
-  const composeCaptainPrompt =
+  const composeArtifactCaptainPrompt =
     spec.composeCaptainPrompt ??
     ((input: PlaybookCaptainInput) =>
       defaultComposeCaptainPrompt(input, spec.placeholderFields));
+  // DR-090 §2: a direct-Captain continuation is marked by the runtime too.
+  const composeCaptainPrompt = (input: PlaybookCaptainInput): string =>
+    [
+      ...markedContinuationBlocks(input),
+      composeArtifactCaptainPrompt(withoutContinuation(input)),
+    ].join('\n\n');
   const extractFields =
     spec.extractRequiredFields ?? defaultExtractRequiredFields;
   const verbatimPayloadFields: ReadonlySet<string> = new Set(
@@ -4508,6 +4590,9 @@ export function createXStatePlaybookRuntime<
       );
     let effectLedgerMirror = currentEffectLedger();
     let recoveryCheckpoint: PlaybookRuntimeSnapshot['recoveryCheckpoint'];
+    // DR-090 §1: the run's Boss exchanges, in order. A run begins at the
+    // artifact's entry event; the list travels in the snapshot.
+    let bossExchanges: readonly PlaybookBossExchange[] = [];
     let retainedEffectSourceSessionId: string | undefined;
     let retainedEffectReconciliation:
       | PlaybookRuntimeSnapshot['retainedEffectReconciliation']
@@ -5406,7 +5491,18 @@ export function createXStatePlaybookRuntime<
       return session?.roleBindings?.[roleId]?.promptIdentity ?? roleId;
     }
 
+    // DR-090 §3: the first block names the role and, where the host bound
+    // it, the model the call runs on as configured, so a player can name
+    // both where its project asks (a commit trailer, say).
+    function playerIdentityBlock(roleId: string): string {
+      const binding = session?.roleBindings?.[roleId];
+      return binding === undefined
+        ? `Role: ${roleId}`
+        : `Role: ${roleId} · Model: ${binding.promptIdentity}`;
+    }
+
     function composeBoundPlayerPrompt(input: PlaybookPlayerInput, resuming = false): string {
+      const roleId = requireRoleId(input);
       let active = true;
       const lookup: XStatePromptIdentity = (roleId) => {
         if (!active) {
@@ -5416,11 +5512,49 @@ export function createXStatePlaybookRuntime<
         }
         return promptIdentity(roleId);
       };
+      let body: string;
       try {
-        return composePlayerPrompt(input, lookup, resuming);
+        body = composePlayerPrompt(withoutContinuation(input), lookup, resuming);
       } finally {
         active = false;
       }
+      // DR-090 §1, §2: every role hears the Boss — the run's exchanges come
+      // before the body whatever the role, and the asking role's marked
+      // continuation carries the exchange it asked.
+      return [
+        playerIdentityBlock(roleId),
+        ...bossExchangeBlocks(bossExchanges, input),
+        ...markedContinuationBlocks(input, resuming),
+        body,
+      ].join('\n\n');
+    }
+
+    /** DR-090 §1: record a Boss reply the machine is about to receive. */
+    function recordBossExchange(
+      event: EventObject,
+      pending: readonly PlaybookPendingBossQuestionContext[],
+    ): void {
+      if (event.type !== 'BOSS_REPLY') return;
+      const { questionId, answer } = event as {
+        readonly questionId?: unknown;
+        readonly answer?: unknown;
+      };
+      if (typeof answer !== 'string' || answer.trim().length === 0) return;
+      const question =
+        pending.find((candidate) => candidate.questionId === questionId) ??
+        (questionId === undefined && pending.length === 1 ? pending[0] : undefined);
+      if (question === undefined) return;
+      bossExchanges = Object.freeze([
+        ...bossExchanges,
+        Object.freeze({ question: question.question, reply: answer }),
+      ]);
+    }
+
+    /** DR-090 §1: an entry event begins a new run, with no exchanges yet. */
+    function beginRunIfEntry(event: EventObject): void {
+      if (spec.entryEvent !== undefined && event.type === spec.entryEvent.type) {
+        bossExchanges = [];
+      }
     }
 
     function continuationKey(
@@ -6706,7 +6840,10 @@ export function createXStatePlaybookRuntime<
       try {
         await claim.assertOwner();
         const restored = snapshotJsonValue(await repositoryCapability!.observe!()) as unknown as PlaybookRepositoryReceipt['baseline'];
-        if (!isDeepStrictEqual(restored, saved.baseline)) {
+        // DR-090 §4: the branch an observation names is never compared.
+        const { branch: _restoredBranch, ...restoredState } = restored;
+        const { branch: _savedBranch, ...savedState } = saved.baseline;
+        if (!isDeepStrictEqual(restoredState, savedState)) {
           throw new Error(`${label} preparation has not restored the stopped step's repository; it remains paused`);
         }
         signal.throwIfAborted();
@@ -6954,6 +7091,14 @@ export function createXStatePlaybookRuntime<
           ...((state.stateId === 'failed' || pendingQuestions.length > 0) && recoveryCheckpoint !== undefined
             ? { recoveryCheckpoint } : {}),
           ...(suspendedCall === undefined ? {} : { suspendedCall }),
+          ...(bossExchanges.length === 0
+            ? {}
+            : {
+                bossExchanges: bossExchanges.map(({ question, reply }) => ({
+                  question,
+                  reply,
+                })),
+              }),
         };
     }
 
@@ -9224,6 +9369,7 @@ export function createXStatePlaybookRuntime<
       deferInspectionEmissions = false;
       deferredInspectionEmissions = [];
       recoveryCheckpoint = undefined;
+      bossExchanges = [];
       suppressInspectionEmissions = false;
       initialized = false;
       traceSequence = 0;
@@ -9671,6 +9817,13 @@ export function createXStatePlaybookRuntime<
           }
           restoreRoleResumeTokens(boundSnapshot.roleResumeTokens);
         }
+        // DR-090 §1: a restored or adopted run keeps the Boss exchanges it
+        // heard; a snapshot without them heard none.
+        bossExchanges = Object.freeze(
+          (boundSnapshot.bossExchanges ?? []).map(({ question, reply }) =>
+            Object.freeze({ question, reply }),
+          ),
+        );
         nestedBridge.prepareRestore(suspendedCall);
         if (suspendedCall !== undefined) {
           playbookCallTurnIds.set(
@@ -10870,13 +11023,20 @@ export function createXStatePlaybookRuntime<
                 )
               ) {
                 const statusLine = classificationStatus(event);
+                const acceptedPending = deferredPending;
+                const acceptedEvent = event;
                 const continuation = await continueBoundDeferredOperation(
                   deferredOperation,
                   event,
                   signal,
                   turnId,
                   statusLine,
-                  onAccepted,
+                  () => {
+                    // DR-090 §1: the host started the continuation, so the
+                    // machine receives this reply now.
+                    recordBossExchange(acceptedEvent, [acceptedPending]);
+                    onAccepted?.();
+                  },
                 );
                 if (continuation === 'continued') {
                   if (controlPlaneError !== undefined) {
@@ -10921,13 +11081,25 @@ export function createXStatePlaybookRuntime<
               signal.throwIfAborted();
               // 3. A final actor cannot accept new events; reconstruct only
               //    after classification produced a real event.
+              const acceptedPending =
+                classifiedSnapshot === undefined
+                  ? []
+                  : pendingBossQuestionsFor(
+                      normalizePlaybookSnapshot(classifiedSnapshot),
+                      ((classifiedSnapshot as { context?: unknown }).context ??
+                        {}) as Record<string, unknown>,
+                    );
               if (actor.getSnapshot().status === 'done') {
                 stopActor();
                 actor = buildActor(runtimePorts!);
                 // The replacement actor's snapshots are real state entries.
                 suppressInspectionEmissions = false;
                 actor.start();
+                // DR-090 §1: a finished run's exchanges end with it.
+                bossExchanges = [];
               }
+              beginRunIfEntry(event);
+              recordBossExchange(event, acceptedPending);
               onAccepted?.();
               actor.send(event);
               await waitForPlaybookQuiescence(actor, {
@@ -11236,6 +11408,7 @@ export function createXStatePlaybookRuntime<
             failedGovernedAttemptId = undefined;
             controlPlaneError = undefined;
             emissionFailure = undefined;
+            bossExchanges = [];
             retainedEffectSourceSessionId = undefined;
             retainedEffectReconciliation = undefined;
             retainedEffectReconciliationRequired = false;

package/src/xstate-runtime.d.ts

@@ -56,13 +56,14 @@ export interface PlaybookSemanticOutcomeSpec {
 }
 /**
  * The JSON value shape a compiled machine admits for one semantic-owned field
- * (DR-089). A field the machine admits as a string, or whose shape the
- * machine does not reveal, is `string`.
+ * (DR-089). A field the machine admits as a string is `string`; a field whose
+ * shape the machine does not reveal has none (DR-091).
  */
 export type PlaybookSemanticValueShape = 'string' | 'string-array' | 'number-array' | 'string-or-number-array' | 'number' | 'boolean';
 /**
- * Per outcome, the non-string shapes of its semantic-owned fields; a field
- * left out is a string.
+ * Per outcome, the shapes of its semantic-owned fields; a field left out has
+ * no revealed shape and takes any JSON value, the machine's own validator
+ * deciding it (DR-091).
  */
 export type PlaybookSemanticValueShapes = Readonly<Record<string, Readonly<Record<string, PlaybookSemanticValueShape>>>>;
 /** The words a judge prompt or validation error uses for one value shape. */
@@ -76,7 +77,8 @@ export interface PlaybookSemanticEvidenceInput {
     readonly runtimeFields?: unknown;
     /**
      * DR-089: the shape the compiled machine admits for each semantic-owned
-     * field, keyed by outcome; every field it leaves out is a string.
+     * field, keyed by outcome; a field it leaves out takes any JSON value
+     * (DR-091).
      */
     readonly semanticValueShapes?: PlaybookSemanticValueShapes;
 }