@sublang/playbook 17.8.0 → 17.9.0

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 {

package/src/xstate-runtime.ts

@@ -13,6 +13,7 @@ import {
 
 import { assertPlaybookFailureCause } from './runtime.js';
 import type {
+  PlaybookBossExchange,
   CaptainResult,
   JsonValue,
   NormalizedError,
@@ -992,6 +993,20 @@ function effectInteger(value: unknown, path: string, minimum = 0): number {
   return value as number;
 }
 
+// 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: PlaybookRepositoryObservation,
+  right: PlaybookRepositoryObservation,
+): boolean {
+  const { branch: _left, ...leftState } = left;
+  const { branch: _right, ...rightState } = right;
+  return jsonValuesEqual(
+    leftState as unknown as JsonValue,
+    rightState as unknown as JsonValue,
+  );
+}
+
 function jsonValuesEqual(left: JsonValue, right: JsonValue): boolean {
   if (Object.is(left, right)) return true;
   if (Array.isArray(left) || Array.isArray(right)) {
@@ -1110,7 +1125,7 @@ function effectObservation(
   if (!isRecord(value)) throw new TypeError(`${path} must be an object`);
   rejectUnknownKeys(
     value,
-    ['worktree', 'gitDir', 'head', 'projection', 'projectionDigest'],
+    ['worktree', 'gitDir', 'head', 'branch', 'projection', 'projectionDigest'],
     path,
   );
   requireNonEmptyString(value.worktree, `${path}.worktree`);
@@ -1119,6 +1134,10 @@ function effectObservation(
   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`);
   }
@@ -1252,10 +1271,7 @@ function effectReceipt(
   if (
     classification === 'unchanged' &&
     after !== undefined &&
-    !jsonValuesEqual(
-      baseline as unknown as JsonValue,
-      after as unknown as JsonValue,
-    )
+    !observedStatesEqual(baseline, after)
   ) {
     throw new TypeError(`${path} classified unchanged observations that differ`);
   }
@@ -1370,8 +1386,8 @@ 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'
@@ -1382,8 +1398,9 @@ export type PlaybookSemanticValueShape =
   | '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>>>
@@ -1444,7 +1461,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;
 }
@@ -1548,14 +1566,13 @@ function snapshotSemanticCandidate(
     );
   }
   // 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'
@@ -2099,7 +2116,7 @@ function effectBoundary(value: unknown, index: number): PlaybookEffectBoundary {
   }
   if (own(value, 'restored')) {
     const restored = effectObservation(value.restored, `${path}.restored`);
-    if (!jsonValuesEqual(restored as unknown as JsonValue, baseline as unknown as JsonValue) ||
+    if (!observedStatesEqual(restored, baseline) ||
         !isRecord(value.physicalReceipt) || after?.head !== baseline.head ||
         (value.dispositions as string[]).some((item) => item !== 'unchanged') ||
         value.cohortId !== undefined || value.logicalOperationId !== undefined) {
@@ -2237,10 +2254,7 @@ function effectLogicalOperation(
     if (
       previous.physicalReceipt === undefined ||
       previous.after === undefined ||
-      !jsonValuesEqual(
-        boundary.baseline as unknown as JsonValue,
-        previous.after as unknown as JsonValue,
-      )
+      !observedStatesEqual(boundary.baseline, previous.after)
     ) {
       throw new TypeError(
         `${path}.boundaryIds must form one completed checkpoint chain`,
@@ -2259,10 +2273,7 @@ function effectLogicalOperation(
     );
     if (
       latestAfter === undefined ||
-      !jsonValuesEqual(
-        checkpoint as unknown as JsonValue,
-        latestAfter as unknown as JsonValue,
-      )
+      !observedStatesEqual(checkpoint, latestAfter)
     ) {
       throw new TypeError(`${path}.checkpoint must equal its latest boundary after`);
     }
@@ -2737,6 +2748,7 @@ export function assertPlaybookRuntimeSnapshot(
       'failedEffectAttempt',
       'recoveryCheckpoint',
       'suspendedCall',
+      'bossExchanges',
     ],
     'runtime snapshot',
   );
@@ -3044,6 +3056,22 @@ export function assertPlaybookRuntimeSnapshot(
     }
     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 as const } : {})});
   }
+  // DR-090 §1: the run's Boss exchanges, present only when there is one.
+  let bossExchanges: readonly PlaybookBossExchange[] | undefined;
+  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: unknown, index: number) => {
+      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,
@@ -3067,6 +3095,7 @@ export function assertPlaybookRuntimeSnapshot(
     schemaVersion: 4,
     ...fields,
     ...(suspendedCall === undefined ? {} : { suspendedCall }),
+    ...(bossExchanges === undefined ? {} : { bossExchanges }),
   });
 }