@sublang/playbook 17.8.1 → 17.10.0

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'>,
@@ -1800,19 +1874,25 @@ export function renderGovernedOutcomeContract(
   for (const [field, authority] of Object.entries(outcome?.fields ?? {})) {
     if (authority === 'semantic') {
       const entry = authored.get(field);
-      // DR-089: the value has the shape the compiled machine admits.
+      // DR-089: the value has the shape the compiled machine admits; a
+      // shape the probe did not reveal is the machine's to judge, so the
+      // example asserts none (DR-091).
       const shape =
         shapes !== undefined && Object.prototype.hasOwnProperty.call(shapes, field)
           ? shapes[field]!
-          : 'string';
-      const words = describePlaybookSemanticValueShape(shape);
+          : undefined;
+      const words = shape === undefined ? undefined : describePlaybookSemanticValueShape(shape);
       replyMembers.push(
         `${JSON.stringify(field)}: ${
           entry?.placeholder ??
-          (shape === 'string' ? '<string>' : `<${words.replace(/^a /, '')}>`)
+          (shape === undefined
+            ? '<value>'
+            : shape === 'string'
+              ? '<string>'
+              : `<${words!.replace(/^a /, '')}>`)
         }`,
       );
-      if (shape !== 'string') valueShapes.push(`\`${field}\` is ${words}`);
+      if (shape !== undefined && shape !== 'string') valueShapes.push(`\`${field}\` is ${words}`);
       semanticAsAuthored.push(entry?.segment ?? `\`${field}\``);
     } else {
       runtimeSupplied.push(`\`${field}\` (${authority}-owned)`);
@@ -3273,8 +3353,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 +3418,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 +3507,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 +4351,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 +4596,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 +5497,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 +5518,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 +6846,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 +7097,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 +9375,7 @@ export function createXStatePlaybookRuntime<
       deferInspectionEmissions = false;
       deferredInspectionEmissions = [];
       recoveryCheckpoint = undefined;
+      bossExchanges = [];
       suppressInspectionEmissions = false;
       initialized = false;
       traceSequence = 0;
@@ -9671,6 +9823,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 +11029,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 +11087,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 +11414,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;
 }

package/src/xstate-runtime.js

@@ -681,6 +681,13 @@ function effectInteger(value, path, minimum = 0) {
     }
     return value;
 }
+// DR-090 §4: an observation's branch is evidence for the Boss only; two
+// observations of one repository state are equal whatever branch each names.
+function observedStatesEqual(left, right) {
+    const { branch: _left, ...leftState } = left;
+    const { branch: _right, ...rightState } = right;
+    return jsonValuesEqual(leftState, rightState);
+}
 function jsonValuesEqual(left, right) {
     if (Object.is(left, right))
         return true;
@@ -760,13 +767,17 @@ function effectPreExisting(value, path, baseline) {
 function effectObservation(value, path) {
     if (!isRecord(value))
         throw new TypeError(`${path} must be an object`);
-    rejectUnknownKeys(value, ['worktree', 'gitDir', 'head', 'projection', 'projectionDigest'], path);
+    rejectUnknownKeys(value, ['worktree', 'gitDir', 'head', 'branch', 'projection', 'projectionDigest'], path);
     requireNonEmptyString(value.worktree, `${path}.worktree`);
     requireNonEmptyString(value.gitDir, `${path}.gitDir`);
     const head = requireNonEmptyString(value.head, `${path}.head`);
     if (!EFFECT_OID_PATTERN.test(head)) {
         throw new TypeError(`${path}.head must be a canonical Git commit OID`);
     }
+    // DR-090 §4: the branch HEAD names, evidence for the Boss only.
+    if (own(value, 'branch')) {
+        requireNonEmptyString(value.branch, `${path}.branch`);
+    }
     if (!isRecord(value.projection)) {
         throw new TypeError(`${path}.projection must be a path-keyed object`);
     }
@@ -854,7 +865,7 @@ function effectReceipt(value, path, expectedBaseline, expectedAfter, matchExpect
     }
     if (classification === 'unchanged' &&
         after !== undefined &&
-        !jsonValuesEqual(baseline, after)) {
+        !observedStatesEqual(baseline, after)) {
         throw new TypeError(`${path} classified unchanged observations that differ`);
     }
     // DR-062 §3: a receipt records the fate of every baseline entry, so the
@@ -997,12 +1008,13 @@ function snapshotSemanticCandidate(value, outcomes, shapes) {
             (extra.length === 0 ? '' : `; extra or wrongly owned ${extra.join(', ')}`));
     }
     // DR-089: each semantic-owned field has the shape the compiled machine
-    // admits for it, a string unless the machine admits another.
+    // admits for it. DR-091: a field whose shape the machine did not reveal
+    // takes any JSON value, and the machine's own validator decides it.
     const outcomeShapes = shapes !== undefined && own(shapes, guard) ? shapes[guard] : undefined;
     for (const field of semanticFields) {
-        const shape = outcomeShapes !== undefined && own(outcomeShapes, field)
-            ? outcomeShapes[field]
-            : 'string';
+        if (outcomeShapes === undefined || !own(outcomeShapes, field))
+            continue;
+        const shape = outcomeShapes[field];
         if (!isPlaybookSemanticValueShape(detached[field], shape)) {
             semanticCandidateStructureError(shape === 'string'
                 ? `field ${JSON.stringify(field)} must be a string`
@@ -1417,7 +1429,7 @@ function effectBoundary(value, index) {
     }
     if (own(value, 'restored')) {
         const restored = effectObservation(value.restored, `${path}.restored`);
-        if (!jsonValuesEqual(restored, baseline) ||
+        if (!observedStatesEqual(restored, baseline) ||
             !isRecord(value.physicalReceipt) || after?.head !== baseline.head ||
             value.dispositions.some((item) => item !== 'unchanged') ||
             value.cohortId !== undefined || value.logicalOperationId !== undefined) {
@@ -1506,7 +1518,7 @@ function effectLogicalOperation(value, index, boundaryById) {
         const previous = boundaries[boundaryIndex - 1];
         if (previous.physicalReceipt === undefined ||
             previous.after === undefined ||
-            !jsonValuesEqual(boundary.baseline, previous.after)) {
+            !observedStatesEqual(boundary.baseline, previous.after)) {
             throw new TypeError(`${path}.boundaryIds must form one completed checkpoint chain`);
         }
     }
@@ -1517,7 +1529,7 @@ function effectLogicalOperation(value, index, boundaryById) {
     if (checkpoint !== undefined) {
         assertObservationIdentity(checkpoint, originalBaseline, `${path}.checkpoint`);
         if (latestAfter === undefined ||
-            !jsonValuesEqual(checkpoint, latestAfter)) {
+            !observedStatesEqual(checkpoint, latestAfter)) {
             throw new TypeError(`${path}.checkpoint must equal its latest boundary after`);
         }
     }
@@ -1810,6 +1822,7 @@ export function assertPlaybookRuntimeSnapshot(value, expectedPlaybookId, options
         'failedEffectAttempt',
         'recoveryCheckpoint',
         'suspendedCall',
+        'bossExchanges',
     ], 'runtime snapshot');
     let suspendedCall;
     if (own(snapshot, 'suspendedCall')) {
@@ -1994,6 +2007,23 @@ export function assertPlaybookRuntimeSnapshot(value, expectedPlaybookId, options
         }
         recoveryCheckpoint = Object.freeze({ stateId, prompt, boundaryPrefix, machine: snapshotJsonValue(checkpoint.machine), ...(own(checkpoint, 'id') ? { id: effectUuid(checkpoint.id, 'recoveryCheckpoint.id') } : {}), ...(own(checkpoint, 'result') ? { result: snapshotJsonValue(checkpoint.result) } : {}), ...(checkpoint.delivered === true ? { delivered: true } : {}) });
     }
+    // DR-090 §1: the run's Boss exchanges, present only when there is one.
+    let bossExchanges;
+    if (own(snapshot, 'bossExchanges')) {
+        const list = snapshot.bossExchanges;
+        if (!Array.isArray(list) || list.length === 0) {
+            throw new TypeError('runtime snapshot bossExchanges must be a nonempty list');
+        }
+        bossExchanges = Object.freeze(list.map((exchange, index) => {
+            const path = `runtime snapshot bossExchanges[${index}]`;
+            if (!isRecord(exchange))
+                throw new TypeError(`${path} must be an object`);
+            rejectUnknownKeys(exchange, ['question', 'reply'], path);
+            const question = requireNonEmptyString(exchange.question, `${path}.question`);
+            const reply = requireNonEmptyString(exchange.reply, `${path}.reply`);
+            return Object.freeze({ question, reply });
+        }));
+    }
     const fields = {
         playbookId,
         machine,
@@ -2017,6 +2047,7 @@ export function assertPlaybookRuntimeSnapshot(value, expectedPlaybookId, options
         schemaVersion: 4,
         ...fields,
         ...(suspendedCall === undefined ? {} : { suspendedCall }),
+        ...(bossExchanges === undefined ? {} : { bossExchanges }),
     });
 }
 export class NestedPlaybookCallError extends Error {