@sublang/playbook 12.0.0 → 12.2.0

package/src/xstate-playbook-runtime.js

@@ -568,6 +568,30 @@ export function defaultComposeCaptainPrompt(input, placeholderFields = {}) {
     blocks.push(body);
     return blocks.join('\n\n');
 }
+// A result description's output clause (slc/link.md §Captain adjudication):
+// everything after `Output shall include` / `输出应包含` names the outcome's
+// payload fields, each as a bare backticked name or the annotated
+// `name: <placeholder>` form. The text before the clause is the outcome's
+// meaning.
+const OUTPUT_CLAUSE_MARKERS = [
+    'Output shall include',
+    '输出应包含',
+];
+const PAYLOAD_FIELD_PATTERN = /`([A-Za-z_$][A-Za-z0-9_$]*)(?::\s*([^`]*))?`/g;
+// Separators between one field's authored segment and the next field token.
+const SEGMENT_SEPARATOR_SUFFIX = /(?:\s|[,;.，、；。]|\band\b)+$/;
+function splitOutputClause(description) {
+    for (const marker of OUTPUT_CLAUSE_MARKERS) {
+        const idx = description.indexOf(marker);
+        if (idx !== -1) {
+            return {
+                meaning: description.slice(0, idx).trim(),
+                clause: description.slice(idx + marker.length),
+            };
+        }
+    }
+    return { meaning: description.trim() };
+}
 /**
  * Default required-field extraction (slc/link.md §Captain adjudication).
  * Limited to the description's `Output shall include` / `输出应包含` clause;
@@ -575,21 +599,11 @@ export function defaultComposeCaptainPrompt(input, placeholderFields = {}) {
  * form.
  */
 export function defaultExtractRequiredFields(description) {
-    const markers = ['Output shall include', '输出应包含'];
-    let clauseStart = -1;
-    for (const marker of markers) {
-        const idx = description.indexOf(marker);
-        if (idx !== -1) {
-            clauseStart = idx + marker.length;
-            break;
-        }
-    }
-    if (clauseStart === -1)
+    const { clause } = splitOutputClause(description);
+    if (clause === undefined)
         return [];
-    const clause = description.slice(clauseStart);
     const fields = [];
-    const re = /`([A-Za-z_$][A-Za-z0-9_$]*)(?::[^`]*)?`/g;
-    for (const m of clause.matchAll(re))
+    for (const m of clause.matchAll(PAYLOAD_FIELD_PATTERN))
         fields.push(m[1]);
     return fields;
 }
@@ -615,6 +629,71 @@ export function defaultBuildJudgePrompt(input, finalText) {
     }
     return lines.join('\n');
 }
+/**
+ * Judge-facing rendering of one governed outcome (DR-040 §1). The artifact's
+ * description is not altered: its meaning is carried through verbatim, while
+ * its `Output shall include` clause — authored for the complete actor output
+ * — is replaced by the reply contract `outcomeAuthority` gives the judge:
+ * exactly `guard` plus the outcome's semantic-owned fields, each keeping the
+ * placeholder or guidance the clause authors for it, and every
+ * presentation-, effect-, or runtime-owned field named as runtime-supplied
+ * so the judge omits it. Rendering the clause verbatim asked the judge for
+ * `question`, `planningResult`, or `evaluatedRevision`, which the reconciler
+ * rejects as a structural error, spending the single correction on a
+ * self-inflicted defect. Exported so a bespoke linked runtime (DECIDE's
+ * parallel machinery) renders the identical contract instead of restating it.
+ */
+export function renderGovernedOutcomeContract(guard, description, outcome) {
+    const { meaning, clause } = splitOutputClause(description);
+    // Each field's authored segment runs from its token to the next token:
+    // the annotated `name: <placeholder>` form, or the bare name followed by
+    // its guidance (`` `irNumber` identifying the continued IR ``).
+    const authored = new Map();
+    if (clause !== undefined) {
+        const matches = [...clause.matchAll(PAYLOAD_FIELD_PATTERN)];
+        matches.forEach((m, i) => {
+            const field = m[1];
+            if (authored.has(field))
+                return;
+            const start = m.index ?? 0;
+            const end = matches[i + 1]?.index ?? clause.length;
+            const segment = clause
+                .slice(start, end)
+                .replace(SEGMENT_SEPARATOR_SUFFIX, '');
+            const placeholder = m[2]?.trim();
+            authored.set(field, {
+                segment,
+                ...(placeholder !== undefined && placeholder.length > 0
+                    ? { placeholder }
+                    : {}),
+            });
+        });
+    }
+    const replyMembers = [`"guard": ${JSON.stringify(guard)}`];
+    const semanticAsAuthored = [];
+    const runtimeSupplied = [];
+    for (const [field, authority] of Object.entries(outcome?.fields ?? {})) {
+        if (authority === 'semantic') {
+            const entry = authored.get(field);
+            replyMembers.push(`${JSON.stringify(field)}: ${entry?.placeholder ?? '<string>'}`);
+            semanticAsAuthored.push(entry?.segment ?? `\`${field}\``);
+        }
+        else {
+            runtimeSupplied.push(`\`${field}\` (${authority}-owned)`);
+        }
+    }
+    const lines = [
+        meaning.length === 0 ? `- \`${guard}\`` : `- \`${guard}\` — ${meaning}`,
+        `  Reply exactly: { ${replyMembers.join(', ')} }`,
+    ];
+    if (semanticAsAuthored.length > 0) {
+        lines.push(`  Semantic fields as authored: ${semanticAsAuthored.join('; ')}`);
+    }
+    if (runtimeSupplied.length > 0) {
+        lines.push(`  Runtime-supplied, do not include: ${runtimeSupplied.join(', ')}`);
+    }
+    return lines;
+}
 function buildGovernedJudgePrompt(input, finalText, outcomes, correction) {
     const lines = [
         'This is hidden control work. Do not call tools, inspect files, or seek external evidence.',
@@ -627,17 +706,12 @@ function buildGovernedJudgePrompt(input, finalText, outcomes, correction) {
         finalText,
         '```',
         '',
-        'Pick exactly one declared `guard`. Include every semantic-owned field for that guard and no other field.',
-        'Do not include presentation-, effect-, or runtime-owned fields; the runtime supplies those from their authoritative evidence.',
+        'Pick exactly one declared `guard` and reply with exactly that outcome\'s reply shape below: `guard` plus its semantic-owned fields and nothing else.',
+        'A field listed as runtime-supplied is owned by presentation, effect, or runtime evidence; the runtime fills it itself, and a reply that includes one is structurally invalid.',
         '',
     ];
     for (const [guard, description] of Object.entries(input.result)) {
-        const semanticFields = Object.entries(outcomes[guard]?.fields ?? {})
-            .filter(([, authority]) => authority === 'semantic')
-            .map(([field]) => field);
-        lines.push(`- \`${guard}\` — semantic fields: ${semanticFields.length === 0
-            ? '(none)'
-            : semanticFields.map((field) => `\`${field}\``).join(', ')}; ${description}`);
+        lines.push(...renderGovernedOutcomeContract(guard, description, outcomes[guard]));
     }
     if (correction !== undefined) {
         lines.push('', 'Your first reply was structurally invalid:', '', '```', correction.reply, '```', '', `Validation error: ${correction.error}`, 'Correct only that structure using the same player output and outcome schema.');
@@ -2080,9 +2154,24 @@ export function createXStatePlaybookRuntime(machine, spec) {
                 return undefined;
             }
         }
+        // DR-040 §4 parks only an envelope whose evidence proves a repository
+        // delta or cannot exclude one. A standalone boundary whose complete
+        // physical receipt is exactly `unchanged` excludes any effect, so missing
+        // or unresolved semantics over it are an ordinary failure — the FSM's
+        // failure state with its fenced retry — never a parked reconciliation:
+        // that state's only exits, reconcile and abandon, project no effect
+        // evidence from an `unchanged` receipt, so parking it deadlocks the
+        // engagement. A boundary inside a deferred chain is judged by the chain's
+        // cumulative receipt from its original baseline, not by its own step.
+        function boundaryExcludesEffect(boundary) {
+            return (boundary.logicalOperationId === undefined &&
+                boundary.physicalReceipt?.classification === 'unchanged');
+        }
         function boundaryNeedsSemanticReconciliation(candidate, ledger) {
             if (!runtimeBoundaryIsOwned(candidate))
                 return false;
+            if (boundaryExcludesEffect(candidate))
+                return false;
             if (governedOutcomesForBoundary(candidate) === undefined)
                 return true;
             const persisted = persistedBoundaryReconciliation(candidate, ledger);
@@ -3110,7 +3199,11 @@ export function createXStatePlaybookRuntime(machine, spec) {
             if (governedSettlement !== undefined) {
                 governedSettlementsByBoundaryId.delete(boundaryId);
                 governedPlayerSettlements.set(result, governedSettlement);
-                if (governedSettlement.status === 'unresolved') {
+                // An unresolved settlement over an `unchanged` standalone receipt
+                // still throws into the failure state through the player bridge; it
+                // just never becomes an effect-possible envelope.
+                if (governedSettlement.status === 'unresolved' &&
+                    !boundaryExcludesEffect(completed)) {
                     unresolvedSemanticBoundaryIds.add(boundaryId);
                 }
                 else {
@@ -4830,6 +4923,10 @@ export function createXStatePlaybookRuntime(machine, spec) {
                 delivery: deferredValue(),
             };
             activeDeferredContinuation = continuation;
+            // Emissions are buffered only until the host durably starts the
+            // continuation: an exit that starts no player (checkpoint mismatch,
+            // ineligible operation) publishes nothing, so the bound wait it
+            // preserves is never contradicted by a classification line.
             deferInspectionEmissions = true;
             let continuationStarted = false;
             let deliverySettled = false;
@@ -4858,6 +4955,14 @@ export function createXStatePlaybookRuntime(machine, spec) {
                         continuation.playerContinuation = selectedContinuation;
                         continuationStarted = true;
                         actor.send(event);
+                        // The host has durably started this boundary and the FSM has
+                        // moved: publish the buffered classification line and the
+                        // authored transition now, and let every later transition,
+                        // accepted outcome, and status emit inline. Holding them until
+                        // the operation settled put the cause after its effects — the
+                        // player call, the nested call a target state starts, and their
+                        // finishes were traced and sequenced first (PBRT-37).
+                        settleDeferredInspectionBuffer(true);
                         // The invoked player remains gated inside boundary.callPlayer.
                         // Return to the host only after the raw player call settles so it
                         // can capture and persist the receipt before any actor output or

package/src/xstate-playbook-runtime.ts

@@ -1304,6 +1304,36 @@ export function defaultComposeCaptainPrompt(
   return blocks.join('\n\n');
 }
 
+// A result description's output clause (slc/link.md §Captain adjudication):
+// everything after `Output shall include` / `输出应包含` names the outcome's
+// payload fields, each as a bare backticked name or the annotated
+// `name: <placeholder>` form. The text before the clause is the outcome's
+// meaning.
+const OUTPUT_CLAUSE_MARKERS: readonly string[] = [
+  'Output shall include',
+  '输出应包含',
+];
+const PAYLOAD_FIELD_PATTERN =
+  /`([A-Za-z_$][A-Za-z0-9_$]*)(?::\s*([^`]*))?`/g;
+// Separators between one field's authored segment and the next field token.
+const SEGMENT_SEPARATOR_SUFFIX = /(?:\s|[,;.，、；。]|\band\b)+$/;
+
+function splitOutputClause(description: string): {
+  readonly meaning: string;
+  readonly clause?: string;
+} {
+  for (const marker of OUTPUT_CLAUSE_MARKERS) {
+    const idx = description.indexOf(marker);
+    if (idx !== -1) {
+      return {
+        meaning: description.slice(0, idx).trim(),
+        clause: description.slice(idx + marker.length),
+      };
+    }
+  }
+  return { meaning: description.trim() };
+}
+
 /**
  * Default required-field extraction (slc/link.md §Captain adjudication).
  * Limited to the description's `Output shall include` / `输出应包含` clause;
@@ -1311,20 +1341,10 @@ export function defaultComposeCaptainPrompt(
  * form.
  */
 export function defaultExtractRequiredFields(description: string): string[] {
-  const markers = ['Output shall include', '输出应包含'];
-  let clauseStart = -1;
-  for (const marker of markers) {
-    const idx = description.indexOf(marker);
-    if (idx !== -1) {
-      clauseStart = idx + marker.length;
-      break;
-    }
-  }
-  if (clauseStart === -1) return [];
-  const clause = description.slice(clauseStart);
+  const { clause } = splitOutputClause(description);
+  if (clause === undefined) return [];
   const fields: string[] = [];
-  const re = /`([A-Za-z_$][A-Za-z0-9_$]*)(?::[^`]*)?`/g;
-  for (const m of clause.matchAll(re)) fields.push(m[1]);
+  for (const m of clause.matchAll(PAYLOAD_FIELD_PATTERN)) fields.push(m[1]);
   return fields;
 }
 
@@ -1358,6 +1378,83 @@ export function defaultBuildJudgePrompt(
   return lines.join('\n');
 }
 
+/**
+ * Judge-facing rendering of one governed outcome (DR-040 §1). The artifact's
+ * description is not altered: its meaning is carried through verbatim, while
+ * its `Output shall include` clause — authored for the complete actor output
+ * — is replaced by the reply contract `outcomeAuthority` gives the judge:
+ * exactly `guard` plus the outcome's semantic-owned fields, each keeping the
+ * placeholder or guidance the clause authors for it, and every
+ * presentation-, effect-, or runtime-owned field named as runtime-supplied
+ * so the judge omits it. Rendering the clause verbatim asked the judge for
+ * `question`, `planningResult`, or `evaluatedRevision`, which the reconciler
+ * rejects as a structural error, spending the single correction on a
+ * self-inflicted defect. Exported so a bespoke linked runtime (DECIDE's
+ * parallel machinery) renders the identical contract instead of restating it.
+ */
+export function renderGovernedOutcomeContract(
+  guard: string,
+  description: string,
+  outcome: XStateGovernedOutcomeSpec | undefined,
+): string[] {
+  const { meaning, clause } = splitOutputClause(description);
+  // Each field's authored segment runs from its token to the next token:
+  // the annotated `name: <placeholder>` form, or the bare name followed by
+  // its guidance (`` `irNumber` identifying the continued IR ``).
+  const authored = new Map<
+    string,
+    { readonly segment: string; readonly placeholder?: string }
+  >();
+  if (clause !== undefined) {
+    const matches = [...clause.matchAll(PAYLOAD_FIELD_PATTERN)];
+    matches.forEach((m, i) => {
+      const field = m[1];
+      if (authored.has(field)) return;
+      const start = m.index ?? 0;
+      const end = matches[i + 1]?.index ?? clause.length;
+      const segment = clause
+        .slice(start, end)
+        .replace(SEGMENT_SEPARATOR_SUFFIX, '');
+      const placeholder = m[2]?.trim();
+      authored.set(field, {
+        segment,
+        ...(placeholder !== undefined && placeholder.length > 0
+          ? { placeholder }
+          : {}),
+      });
+    });
+  }
+  const replyMembers = [`"guard": ${JSON.stringify(guard)}`];
+  const semanticAsAuthored: string[] = [];
+  const runtimeSupplied: string[] = [];
+  for (const [field, authority] of Object.entries(outcome?.fields ?? {})) {
+    if (authority === 'semantic') {
+      const entry = authored.get(field);
+      replyMembers.push(
+        `${JSON.stringify(field)}: ${entry?.placeholder ?? '<string>'}`,
+      );
+      semanticAsAuthored.push(entry?.segment ?? `\`${field}\``);
+    } else {
+      runtimeSupplied.push(`\`${field}\` (${authority}-owned)`);
+    }
+  }
+  const lines = [
+    meaning.length === 0 ? `- \`${guard}\`` : `- \`${guard}\` — ${meaning}`,
+    `  Reply exactly: { ${replyMembers.join(', ')} }`,
+  ];
+  if (semanticAsAuthored.length > 0) {
+    lines.push(
+      `  Semantic fields as authored: ${semanticAsAuthored.join('; ')}`,
+    );
+  }
+  if (runtimeSupplied.length > 0) {
+    lines.push(
+      `  Runtime-supplied, do not include: ${runtimeSupplied.join(', ')}`,
+    );
+  }
+  return lines;
+}
+
 function buildGovernedJudgePrompt(
   input: PlaybookPlayerInput,
   finalText: string,
@@ -1375,20 +1472,13 @@ function buildGovernedJudgePrompt(
     finalText,
     '```',
     '',
-    'Pick exactly one declared `guard`. Include every semantic-owned field for that guard and no other field.',
-    'Do not include presentation-, effect-, or runtime-owned fields; the runtime supplies those from their authoritative evidence.',
+    'Pick exactly one declared `guard` and reply with exactly that outcome\'s reply shape below: `guard` plus its semantic-owned fields and nothing else.',
+    'A field listed as runtime-supplied is owned by presentation, effect, or runtime evidence; the runtime fills it itself, and a reply that includes one is structurally invalid.',
     '',
   ];
   for (const [guard, description] of Object.entries(input.result)) {
-    const semanticFields = Object.entries(outcomes[guard]?.fields ?? {})
-      .filter(([, authority]) => authority === 'semantic')
-      .map(([field]) => field);
     lines.push(
-      `- \`${guard}\` — semantic fields: ${
-        semanticFields.length === 0
-          ? '(none)'
-          : semanticFields.map((field) => `\`${field}\``).join(', ')
-      }; ${description}`,
+      ...renderGovernedOutcomeContract(guard, description, outcomes[guard]),
     );
   }
   if (correction !== undefined) {
@@ -3480,11 +3570,28 @@ export function createXStatePlaybookRuntime<
       }
     }
 
+    // DR-040 §4 parks only an envelope whose evidence proves a repository
+    // delta or cannot exclude one. A standalone boundary whose complete
+    // physical receipt is exactly `unchanged` excludes any effect, so missing
+    // or unresolved semantics over it are an ordinary failure — the FSM's
+    // failure state with its fenced retry — never a parked reconciliation:
+    // that state's only exits, reconcile and abandon, project no effect
+    // evidence from an `unchanged` receipt, so parking it deadlocks the
+    // engagement. A boundary inside a deferred chain is judged by the chain's
+    // cumulative receipt from its original baseline, not by its own step.
+    function boundaryExcludesEffect(boundary: PlaybookEffectBoundary): boolean {
+      return (
+        boundary.logicalOperationId === undefined &&
+        boundary.physicalReceipt?.classification === 'unchanged'
+      );
+    }
+
     function boundaryNeedsSemanticReconciliation(
       candidate: PlaybookEffectBoundary,
       ledger: PlaybookEffectLedger,
     ): boolean {
       if (!runtimeBoundaryIsOwned(candidate)) return false;
+      if (boundaryExcludesEffect(candidate)) return false;
       if (governedOutcomesForBoundary(candidate) === undefined) return true;
       const persisted = persistedBoundaryReconciliation(candidate, ledger);
       if (persisted !== undefined) {
@@ -5009,7 +5116,13 @@ export function createXStatePlaybookRuntime<
       if (governedSettlement !== undefined) {
         governedSettlementsByBoundaryId.delete(boundaryId);
         governedPlayerSettlements.set(result, governedSettlement);
-        if (governedSettlement.status === 'unresolved') {
+        // An unresolved settlement over an `unchanged` standalone receipt
+        // still throws into the failure state through the player bridge; it
+        // just never becomes an effect-possible envelope.
+        if (
+          governedSettlement.status === 'unresolved' &&
+          !boundaryExcludesEffect(completed)
+        ) {
           unresolvedSemanticBoundaryIds.add(boundaryId);
         } else {
           unresolvedSemanticBoundaryIds.delete(boundaryId);
@@ -7145,6 +7258,10 @@ export function createXStatePlaybookRuntime<
         delivery: deferredValue<PlayerResult>(),
       };
       activeDeferredContinuation = continuation;
+      // Emissions are buffered only until the host durably starts the
+      // continuation: an exit that starts no player (checkpoint mismatch,
+      // ineligible operation) publishes nothing, so the bound wait it
+      // preserves is never contradicted by a classification line.
       deferInspectionEmissions = true;
       let continuationStarted = false;
       let deliverySettled = false;
@@ -7181,6 +7298,14 @@ export function createXStatePlaybookRuntime<
             continuation.playerContinuation = selectedContinuation;
             continuationStarted = true;
             actor!.send(event);
+            // The host has durably started this boundary and the FSM has
+            // moved: publish the buffered classification line and the
+            // authored transition now, and let every later transition,
+            // accepted outcome, and status emit inline. Holding them until
+            // the operation settled put the cause after its effects — the
+            // player call, the nested call a target state starts, and their
+            // finishes were traced and sequenced first (PBRT-37).
+            settleDeferredInspectionBuffer(true);
             // The invoked player remains gated inside boundary.callPlayer.
             // Return to the host only after the raw player call settles so it
             // can capture and persist the receipt before any actor output or