@sublang/playbook 17.6.0 → 17.8.0

package/src/xstate-runtime.js

@@ -796,7 +796,7 @@ function assertObservationIdentity(observation, identity, path) {
 function effectReceipt(value, path, expectedBaseline, expectedAfter, matchExpectedAfter = false, dispositions) {
     if (!isRecord(value))
         throw new TypeError(`${path} must be an object`);
-    rejectUnknownKeys(value, ['classification', 'baseline', 'after', 'commitOid', 'preExisting'], path);
+    rejectUnknownKeys(value, ['classification', 'baseline', 'after', 'commitOid', 'commits', 'preExisting'], path);
     if (typeof value.classification !== 'string' ||
         !EFFECT_RECEIPT_CLASSIFICATIONS.has(value.classification)) {
         throw new TypeError(`${path}.classification is not supported`);
@@ -837,6 +837,21 @@ function effectReceipt(value, path, expectedBaseline, expectedAfter, matchExpect
     else if (commitOid !== undefined) {
         throw new TypeError(`${path}.commitOid is permitted only for one-descendant-commit`);
     }
+    // DR-088 §1: a receipt of more than one new commit lists every one, oldest
+    // first and ending at its commit OID; one new commit keeps today's shape.
+    if (own(value, 'commits')) {
+        const commits = value.commits;
+        if (classification !== 'one-descendant-commit' ||
+            !Array.isArray(commits) ||
+            commits.length < 2 ||
+            commits.some((oid) => typeof oid !== 'string' ||
+                !EFFECT_OID_PATTERN.test(oid) ||
+                oid === baseline.head) ||
+            new Set(commits).size !== commits.length ||
+            commits.at(-1) !== commitOid) {
+            throw new TypeError(`${path}.commits must list two or more new commits ending at the commit OID of a one-descendant-commit receipt`);
+        }
+    }
     if (classification === 'unchanged' &&
         after !== undefined &&
         !jsonValuesEqual(baseline, after)) {
@@ -902,6 +917,39 @@ function effectReceipt(value, path, expectedBaseline, expectedAfter, matchExpect
     }
     return value;
 }
+const SEMANTIC_VALUE_SHAPE_WORDS = {
+    string: 'a JSON string',
+    'string-array': 'a JSON array of strings',
+    'number-array': 'a JSON array of numbers',
+    'string-or-number-array': 'a JSON array of strings or numbers',
+    number: 'a JSON number',
+    boolean: 'a JSON boolean',
+};
+/** The words a judge prompt or validation error uses for one value shape. */
+export function describePlaybookSemanticValueShape(shape) {
+    return SEMANTIC_VALUE_SHAPE_WORDS[shape];
+}
+/** Whether one detached JSON value has the given semantic value shape. */
+function isPlaybookSemanticValueShape(value, shape) {
+    const isFiniteNumber = (entry) => typeof entry === 'number' && Number.isFinite(entry);
+    switch (shape) {
+        case 'string':
+            return typeof value === 'string';
+        case 'number':
+            return isFiniteNumber(value);
+        case 'boolean':
+            return typeof value === 'boolean';
+        case 'string-array':
+            return Array.isArray(value) && value.every((entry) => typeof entry === 'string');
+        case 'number-array':
+            return Array.isArray(value) && value.every(isFiniteNumber);
+        case 'string-or-number-array':
+            return (Array.isArray(value) &&
+                value.every((entry) => typeof entry === 'string' || isFiniteNumber(entry)));
+        default:
+            return false;
+    }
+}
 /**
  * A judge candidate is structurally invalid, rather than merely awaiting or
  * conflicting with effect evidence. Callers use this distinction to spend at
@@ -916,7 +964,7 @@ export class PlaybookSemanticCandidateStructureError extends TypeError {
 function semanticCandidateStructureError(message) {
     throw new PlaybookSemanticCandidateStructureError(message);
 }
-function snapshotSemanticCandidate(value, outcomes) {
+function snapshotSemanticCandidate(value, outcomes, shapes) {
     let detached;
     try {
         detached = snapshotJsonValue(value, 'semantic candidate');
@@ -948,9 +996,17 @@ function snapshotSemanticCandidate(value, outcomes) {
             (missing.length === 0 ? '' : `; missing ${missing.join(', ')}`) +
             (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.
+    const outcomeShapes = shapes !== undefined && own(shapes, guard) ? shapes[guard] : undefined;
     for (const field of semanticFields) {
-        if (typeof detached[field] !== 'string') {
-            semanticCandidateStructureError(`field ${JSON.stringify(field)} must be a string`);
+        const shape = outcomeShapes !== undefined && own(outcomeShapes, field)
+            ? outcomeShapes[field]
+            : 'string';
+        if (!isPlaybookSemanticValueShape(detached[field], shape)) {
+            semanticCandidateStructureError(shape === 'string'
+                ? `field ${JSON.stringify(field)} must be a string`
+                : `field ${JSON.stringify(field)} must be ${describePlaybookSemanticValueShape(shape)}`);
         }
     }
     return {
@@ -1005,7 +1061,9 @@ function divergentProjectionPaths(baseline, after) {
  * proved. The receipt states the failure; nothing here infers one.
  */
 function playbookRepositoryFailureCause(required, receipt) {
-    const observed = receipt.classification;
+    // DR-088 §3: a receipt listing more than one new commit reads as
+    // `multiple-commits`, so its statement names more than one commit.
+    const observed = receipt.commits === undefined ? receipt.classification : 'multiple-commits';
     const baselineHead = receipt.baseline.head;
     const after = receipt.after;
     const common = { required, observed, baselineHead };
@@ -1096,11 +1154,25 @@ function unresolvedSemanticEvidence(reason, evidence, cause = assertPlaybookFail
 })) {
     return Object.freeze({ status: 'unresolved', reason, cause, evidence });
 }
+/**
+ * DR-088 §2: whether the player's final text names one commit as a word, by
+ * its full OID or by an abbreviation of at least seven leading hex digits.
+ * It designates which observed commit is the work and proves nothing itself.
+ */
+function finalTextNamesCommit(finalText, oid) {
+    for (const [word] of finalText.matchAll(/(?<![0-9A-Za-z_])[0-9A-Fa-f]{7,64}(?![0-9A-Za-z_])/g)) {
+        if (oid.startsWith(word.toLowerCase()))
+            return true;
+    }
+    return false;
+}
 /**
  * Reconcile one exact semantic candidate with host-owned effect evidence.
  * Presentation prose remains opaque: it is retained verbatim and only its
  * trimmed value is copied into linker-declared presentation fields. No
- * repository fact is inferred from that prose or from the semantic candidate.
+ * repository fact is inferred from that prose or from the semantic candidate;
+ * the prose may only name, as the work, the commit an `unchanged` receipt
+ * observed at HEAD (DR-088 §2).
  */
 export function reconcilePlaybookSemanticEvidence(input) {
     let report;
@@ -1117,7 +1189,7 @@ export function reconcilePlaybookSemanticEvidence(input) {
             evidence: { reason: `No declared outcome matches: ${report.blocked}` },
         }));
     }
-    const { candidate, outcome } = snapshotSemanticCandidate(input.semanticCandidate, input.outcomes);
+    const { candidate, outcome } = snapshotSemanticCandidate(input.semanticCandidate, input.outcomes, input.semanticValueShapes);
     const evidence = retainedSemanticEvidence(candidate, input.finalText);
     const finalText = typeof input.finalText === 'string' ? input.finalText.trim() : undefined;
     if (finalText === undefined || finalText.length === 0) {
@@ -1135,9 +1207,18 @@ export function reconcilePlaybookSemanticEvidence(input) {
         return unresolvedSemanticEvidence('invalid-repository-receipt', evidence);
     }
     const disposition = outcome.repositoryDisposition;
+    // DR-088 §2: a commit outcome over an unchanged receipt takes the commit
+    // already at HEAD when the final text names it and the call declares no
+    // outcome of its own for leaving the repository unchanged.
+    const alreadyAtHead = disposition === 'one-descendant-commit' &&
+        receipt.classification === 'unchanged' &&
+        receipt.after !== undefined &&
+        !/^0+$/.test(receipt.after.head) &&
+        Object.values(input.outcomes).every(({ repositoryDisposition }) => repositoryDisposition !== 'unchanged') &&
+        finalTextNamesCommit(finalText, receipt.after.head);
     const dispositionMatches = (disposition === 'unchanged' && receipt.classification === 'unchanged') ||
         (disposition === 'one-descendant-commit' &&
-            receipt.classification === 'one-descendant-commit') ||
+            (receipt.classification === 'one-descendant-commit' || alreadyAtHead)) ||
         (disposition === 'deferred' &&
             candidate.guard === 'needsBossReply' &&
             Object.entries(input.outcomes).some(([guard, declared]) => guard !== candidate.guard &&
@@ -1182,13 +1263,16 @@ export function reconcilePlaybookSemanticEvidence(input) {
             // DR-045: effect injection selects by the accepted arm's declared
             // repository disposition, never by the field's name. A
             // one-descendant-commit arm's effect fields carry the qualifying
-            // receipt's exact new-descendant commit OID; an unchanged arm's effect
-            // fields carry the matching unchanged receipt's observed HEAD OID. A
-            // deferred arm declares no effect field, and any shape the validated
-            // receipt cannot prove fails closed as unresolved.
+            // receipt's exact new-descendant commit OID, or the HEAD OID its final
+            // text named over an unchanged receipt (DR-088 §2); an unchanged arm's
+            // effect fields carry the matching unchanged receipt's observed HEAD
+            // OID. A deferred arm declares no effect field, and any shape the
+            // validated receipt cannot prove fails closed as unresolved.
             value =
                 disposition === 'one-descendant-commit'
-                    ? receipt.commitOid
+                    ? alreadyAtHead
+                        ? receipt.after?.head
+                        : receipt.commitOid
                     : disposition === 'unchanged'
                         ? receipt.after?.head
                         : undefined;

package/src/xstate-runtime.ts

@@ -1167,7 +1167,7 @@ function effectReceipt(
   if (!isRecord(value)) throw new TypeError(`${path} must be an object`);
   rejectUnknownKeys(
     value,
-    ['classification', 'baseline', 'after', 'commitOid', 'preExisting'],
+    ['classification', 'baseline', 'after', 'commitOid', 'commits', 'preExisting'],
     path,
   );
   if (
@@ -1227,6 +1227,28 @@ function effectReceipt(
       `${path}.commitOid is permitted only for one-descendant-commit`,
     );
   }
+  // DR-088 §1: a receipt of more than one new commit lists every one, oldest
+  // first and ending at its commit OID; one new commit keeps today's shape.
+  if (own(value, 'commits')) {
+    const commits = value.commits;
+    if (
+      classification !== 'one-descendant-commit' ||
+      !Array.isArray(commits) ||
+      commits.length < 2 ||
+      commits.some(
+        (oid) =>
+          typeof oid !== 'string' ||
+          !EFFECT_OID_PATTERN.test(oid) ||
+          oid === baseline.head,
+      ) ||
+      new Set(commits).size !== commits.length ||
+      commits.at(-1) !== commitOid
+    ) {
+      throw new TypeError(
+        `${path}.commits must list two or more new commits ending at the commit OID of a one-descendant-commit receipt`,
+      );
+    }
+  }
   if (
     classification === 'unchanged' &&
     after !== undefined &&
@@ -1346,6 +1368,73 @@ export interface PlaybookSemanticOutcomeSpec {
   readonly repositoryDisposition: PlaybookRepositoryDisposition;
 }
 
+/**
+ * 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`.
+ */
+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.
+ */
+export type PlaybookSemanticValueShapes = Readonly<
+  Record<string, Readonly<Record<string, PlaybookSemanticValueShape>>>
+>;
+
+const SEMANTIC_VALUE_SHAPE_WORDS: Readonly<
+  Record<PlaybookSemanticValueShape, string>
+> = {
+  string: 'a JSON string',
+  'string-array': 'a JSON array of strings',
+  'number-array': 'a JSON array of numbers',
+  'string-or-number-array': 'a JSON array of strings or numbers',
+  number: 'a JSON number',
+  boolean: 'a JSON boolean',
+};
+
+/** The words a judge prompt or validation error uses for one value shape. */
+export function describePlaybookSemanticValueShape(
+  shape: PlaybookSemanticValueShape,
+): string {
+  return SEMANTIC_VALUE_SHAPE_WORDS[shape];
+}
+
+/** Whether one detached JSON value has the given semantic value shape. */
+function isPlaybookSemanticValueShape(
+  value: unknown,
+  shape: PlaybookSemanticValueShape,
+): boolean {
+  const isFiniteNumber = (entry: unknown): boolean =>
+    typeof entry === 'number' && Number.isFinite(entry);
+  switch (shape) {
+    case 'string':
+      return typeof value === 'string';
+    case 'number':
+      return isFiniteNumber(value);
+    case 'boolean':
+      return typeof value === 'boolean';
+    case 'string-array':
+      return Array.isArray(value) && value.every((entry) => typeof entry === 'string');
+    case 'number-array':
+      return Array.isArray(value) && value.every(isFiniteNumber);
+    case 'string-or-number-array':
+      return (
+        Array.isArray(value) &&
+        value.every((entry) => typeof entry === 'string' || isFiniteNumber(entry))
+      );
+    default:
+      return false;
+  }
+}
+
 /** Evidence available when one governed semantic candidate is reconciled. */
 export interface PlaybookSemanticEvidenceInput {
   readonly outcomes: Readonly<Record<string, PlaybookSemanticOutcomeSpec>>;
@@ -1353,11 +1442,16 @@ export interface PlaybookSemanticEvidenceInput {
   readonly finalText?: unknown;
   readonly receipt?: unknown;
   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.
+   */
+  readonly semanticValueShapes?: PlaybookSemanticValueShapes;
 }
 
 /** The exact detached actor output admitted to FSM delivery. */
 export type PlaybookReconciledSemanticOutput = Readonly<
-  Record<string, string>
+  Record<string, JsonValue>
 > & {
   readonly guard: string;
 };
@@ -1365,7 +1459,7 @@ export type PlaybookReconciledSemanticOutput = Readonly<
 /** Retained presentation and semantic evidence, kept separate from output. */
 export interface PlaybookRetainedSemanticEvidence {
   readonly finalText?: string;
-  readonly semanticCandidate: Readonly<Record<string, string>>;
+  readonly semanticCandidate: Readonly<Record<string, JsonValue>>;
 }
 
 export type PlaybookSemanticReconciliationReason =
@@ -1412,8 +1506,9 @@ function semanticCandidateStructureError(message: string): never {
 function snapshotSemanticCandidate(
   value: unknown,
   outcomes: Readonly<Record<string, PlaybookSemanticOutcomeSpec>>,
+  shapes: PlaybookSemanticValueShapes | undefined,
 ): {
-  readonly candidate: Readonly<Record<string, string>> & {
+  readonly candidate: Readonly<Record<string, JsonValue>> & {
     readonly guard: string;
   };
   readonly outcome: PlaybookSemanticOutcomeSpec;
@@ -1452,15 +1547,25 @@ function snapshotSemanticCandidate(
         (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.
+  const outcomeShapes =
+    shapes !== undefined && own(shapes, guard) ? shapes[guard] : undefined;
   for (const field of semanticFields) {
-    if (typeof detached[field] !== 'string') {
+    const shape =
+      outcomeShapes !== undefined && own(outcomeShapes, field)
+        ? outcomeShapes[field]!
+        : 'string';
+    if (!isPlaybookSemanticValueShape(detached[field], shape)) {
       semanticCandidateStructureError(
-        `field ${JSON.stringify(field)} must be a string`,
+        shape === 'string'
+          ? `field ${JSON.stringify(field)} must be a string`
+          : `field ${JSON.stringify(field)} must be ${describePlaybookSemanticValueShape(shape)}`,
       );
     }
   }
   return {
-    candidate: detached as Readonly<Record<string, string>> & {
+    candidate: detached as Readonly<Record<string, JsonValue>> & {
       readonly guard: string;
     },
     outcome,
@@ -1468,7 +1573,7 @@ function snapshotSemanticCandidate(
 }
 
 function retainedSemanticEvidence(
-  candidate: Readonly<Record<string, string>>,
+  candidate: Readonly<Record<string, JsonValue>>,
   finalText: unknown,
 ): PlaybookRetainedSemanticEvidence {
   return Object.freeze({
@@ -1544,7 +1649,10 @@ function playbookRepositoryFailureCause(
   required: PlaybookRepositoryDisposition,
   receipt: PlaybookRepositoryReceipt,
 ): PlaybookFailureCause {
-  const observed = receipt.classification;
+  // DR-088 §3: a receipt listing more than one new commit reads as
+  // `multiple-commits`, so its statement names more than one commit.
+  const observed =
+    receipt.commits === undefined ? receipt.classification : 'multiple-commits';
   const baselineHead = receipt.baseline.head;
   const after = receipt.after;
   const common = { required, observed, baselineHead };
@@ -1645,11 +1753,27 @@ function unresolvedSemanticEvidence(
   return Object.freeze({ status: 'unresolved', reason, cause, evidence });
 }
 
+/**
+ * DR-088 §2: whether the player's final text names one commit as a word, by
+ * its full OID or by an abbreviation of at least seven leading hex digits.
+ * It designates which observed commit is the work and proves nothing itself.
+ */
+function finalTextNamesCommit(finalText: string, oid: string): boolean {
+  for (const [word] of finalText.matchAll(
+    /(?<![0-9A-Za-z_])[0-9A-Fa-f]{7,64}(?![0-9A-Za-z_])/g,
+  )) {
+    if (oid.startsWith(word.toLowerCase())) return true;
+  }
+  return false;
+}
+
 /**
  * Reconcile one exact semantic candidate with host-owned effect evidence.
  * Presentation prose remains opaque: it is retained verbatim and only its
  * trimmed value is copied into linker-declared presentation fields. No
- * repository fact is inferred from that prose or from the semantic candidate.
+ * repository fact is inferred from that prose or from the semantic candidate;
+ * the prose may only name, as the work, the commit an `unchanged` receipt
+ * observed at HEAD (DR-088 §2).
  */
 export function reconcilePlaybookSemanticEvidence(
   input: PlaybookSemanticEvidenceInput,
@@ -1664,7 +1788,7 @@ export function reconcilePlaybookSemanticEvidence(
       typeof report.blocked === 'string' && report.blocked.trim().length > 0) {
     return unresolvedSemanticEvidence(
       'no-matching-outcome',
-      retainedSemanticEvidence(report as Readonly<Record<string, string>>, input.finalText),
+      retainedSemanticEvidence(report as Readonly<Record<string, JsonValue>>, input.finalText),
       assertPlaybookFailureCause({
         code: 'runtime-defect',
         evidence: { reason: `No declared outcome matches: ${report.blocked}` },
@@ -1674,6 +1798,7 @@ export function reconcilePlaybookSemanticEvidence(
   const { candidate, outcome } = snapshotSemanticCandidate(
     input.semanticCandidate,
     input.outcomes,
+    input.semanticValueShapes,
   );
   const evidence = retainedSemanticEvidence(candidate, input.finalText);
   const finalText =
@@ -1706,10 +1831,22 @@ export function reconcilePlaybookSemanticEvidence(
   }
 
   const disposition = outcome.repositoryDisposition;
+  // DR-088 §2: a commit outcome over an unchanged receipt takes the commit
+  // already at HEAD when the final text names it and the call declares no
+  // outcome of its own for leaving the repository unchanged.
+  const alreadyAtHead =
+    disposition === 'one-descendant-commit' &&
+    receipt.classification === 'unchanged' &&
+    receipt.after !== undefined &&
+    !/^0+$/.test(receipt.after.head) &&
+    Object.values(input.outcomes).every(
+      ({ repositoryDisposition }) => repositoryDisposition !== 'unchanged',
+    ) &&
+    finalTextNamesCommit(finalText, receipt.after.head);
   const dispositionMatches =
     (disposition === 'unchanged' && receipt.classification === 'unchanged') ||
     (disposition === 'one-descendant-commit' &&
-      receipt.classification === 'one-descendant-commit') ||
+      (receipt.classification === 'one-descendant-commit' || alreadyAtHead)) ||
     (disposition === 'deferred' &&
       candidate.guard === 'needsBossReply' &&
       Object.entries(input.outcomes).some(
@@ -1761,10 +1898,10 @@ export function reconcilePlaybookSemanticEvidence(
     return unresolvedSemanticEvidence('inconsistent-runtime-evidence', evidence);
   }
 
-  const output: Record<string, string> = {};
+  const output: Record<string, JsonValue> = {};
   defineEnumerableDataProperty(output, 'guard', candidate.guard);
   for (const [field, authority] of Object.entries(outcome.fields)) {
-    let value: string | undefined;
+    let value: JsonValue | undefined;
     if (authority === 'semantic') {
       value = candidate[field];
     } else if (authority === 'presentation') {
@@ -1773,13 +1910,16 @@ export function reconcilePlaybookSemanticEvidence(
       // DR-045: effect injection selects by the accepted arm's declared
       // repository disposition, never by the field's name. A
       // one-descendant-commit arm's effect fields carry the qualifying
-      // receipt's exact new-descendant commit OID; an unchanged arm's effect
-      // fields carry the matching unchanged receipt's observed HEAD OID. A
-      // deferred arm declares no effect field, and any shape the validated
-      // receipt cannot prove fails closed as unresolved.
+      // receipt's exact new-descendant commit OID, or the HEAD OID its final
+      // text named over an unchanged receipt (DR-088 §2); an unchanged arm's
+      // effect fields carry the matching unchanged receipt's observed HEAD
+      // OID. A deferred arm declares no effect field, and any shape the
+      // validated receipt cannot prove fails closed as unresolved.
       value =
         disposition === 'one-descendant-commit'
-          ? receipt.commitOid
+          ? alreadyAtHead
+            ? receipt.after?.head
+            : receipt.commitOid
           : disposition === 'unchanged'
             ? receipt.after?.head
             : undefined;