@sublang/playbook 17.7.0 → 17.8.0

package/slc/text2gears.md

@@ -35,7 +35,8 @@ E.g.:
 - Coder
 - Reviewer
 
-Capitalize English role names (e.g., `Writer`); quote non-English names (e.g., `作者`) when needed to distinguish from prose.
+Each role name shall be one capitalized word — an uppercase letter, or a letter of a script without case, followed only by letters and digits — so a two-word role is written as one word, e.g. `RiskOfficer`, never `Risk Officer`.
+Quote non-English names (e.g., `作者`) when needed to distinguish from prose.
 
 ## Behaviors
 
@@ -67,14 +68,15 @@ Boss-visible contract and is nonconformant.
 
 ### Authored prompt fragments
 
-Source may compose one acting prompt from authored Markdown instruction blocks and runtime context that it explicitly says to relay in quotes (`>`).
+Source may compose one acting prompt from authored Markdown instruction blocks and runtime context that it explicitly marks as relayed in quotes.
+The relay marker is a backticked `>` in ASCII or full-width parentheses, `` (`>`) `` or `` （`>`） ``, in the prose introducing the blockquote; the words around it, such as "in quotes" or "以引用形式", are prose in the Source's language.
 A fenced `markdown` block introduced as an instruction or prompt is an authored static prompt fragment: its fence delimiters are Source syntax, while every interior line and blank line is prompt content preserved after documented Markdown unescaping.
 
 An instruction fence and a relayed-context fragment that apply to one behavior shall appear in the target blockquote in their Source order.
 Distinct non-empty fragments shall be separated by one blank prompt line unless Source explicitly supplies a different boundary.
 text2gears shall not move a shared instruction ahead of behavior-specific context, move quoted evidence after an instruction that Source says follows the evidence, or otherwise regroup fragments for convenience.
 
-Where Source says that a runtime value is relayed in quotes, the leading `>` is prompt content rather than Source-only blockquote syntax.
+Where Source marks a runtime value as relayed in quotes, the leading `>` is prompt content rather than Source-only blockquote syntax.
 If Source supplies a blockquoted template for that relay, text2gears shall keep one literal leading `>` on every quoted line; the target GEARS line therefore uses its outer blockquote marker followed by the literal marker, such as `> > Coder output: <coder-output>`.
 If Source names the relayed value but supplies no template, text2gears shall emit a bare quoted prompt-content line, exactly `> <token>`, written as `> > <token>` in the GEARS file because the first marker encloses the prompt and the second is literal content, without an added label or surrounding prose, and shall not summarize, paraphrase, or invent the relayed value.
 An ordinary Source blockquote that specifies a complete acting prompt without requiring quoted relay retains the existing rule above: its one leading marker is Source syntax and is not prompt content.

package/src/runtime.d.ts

@@ -255,6 +255,12 @@ export interface PlaybookRepositoryReceipt {
     readonly baseline: PlaybookRepositoryObservation;
     readonly after?: PlaybookRepositoryObservation;
     readonly commitOid?: string;
+    /**
+     * Every new commit, oldest first and ending at `commitOid`, present exactly
+     * when a `one-descendant-commit` receipt's HEAD advanced by more than one
+     * (DR-088).
+     */
+    readonly commits?: readonly string[];
     readonly preExisting?: PlaybookRepositoryPreExistingChanges;
 }
 /** One durably ordered physical governed-player boundary (DR-040). */

package/src/runtime.ts

@@ -618,6 +618,12 @@ export interface PlaybookRepositoryReceipt {
   readonly baseline: PlaybookRepositoryObservation;
   readonly after?: PlaybookRepositoryObservation;
   readonly commitOid?: string;
+  /**
+   * Every new commit, oldest first and ending at `commitOid`, present exactly
+   * when a `one-descendant-commit` receipt's HEAD advanced by more than one
+   * (DR-088).
+   */
+  readonly commits?: readonly string[];
   readonly preExisting?: PlaybookRepositoryPreExistingChanges;
 }
 

package/src/xstate-playbook-runtime.d.ts

@@ -1,4 +1,5 @@
 import type { AnyStateMachine, EventObject, PromiseActorLogic } from 'xstate';
+import { type PlaybookSemanticValueShape, type PlaybookSemanticValueShapes } from './xstate-runtime.js';
 import type { CaptainResult, JsonValue, PlaybookEffectBoundary, PlaybookEffectBoundaryStart, PlaybookEffectLedger, PlaybookEffectLedgerCapability, NormalizedError, PlaybookFailureCause, PlaybookPendingBossQuestion, PlaybookPorts, PlaybookRepositoryReceipt, PlaybookRuntimeFactory, PlaybookSession, PlaybookState, PlayerResult } from './runtime.js';
 export interface PlaybookPendingBossQuestionContext {
     questionId: string;
@@ -494,7 +495,7 @@ export declare function defaultBuildJudgePrompt(input: PlaybookPlayerInput, fina
  * self-inflicted defect. Exported so linked machinery of an artifact's own
  * renders the identical contract instead of restating it.
  */
-export declare function renderGovernedOutcomeContract(guard: string, description: string, outcome: XStateGovernedOutcomeSpec | undefined): string[];
+export declare function renderGovernedOutcomeContract(guard: string, description: string, outcome: XStateGovernedOutcomeSpec | undefined, shapes?: Readonly<Record<string, PlaybookSemanticValueShape>>): string[];
 export interface PlayerAdjudicationSpec {
     buildJudgePrompt?: (input: PlaybookPlayerInput, finalText: string) => string;
     extractRequiredFields?: (description: string) => string[];
@@ -522,13 +523,22 @@ export declare function createPlayerBridge(spec: PlayerBridgeSpec, ports: Playbo
 /**
  * Default direct-Captain adjudicator prompt (DR-025). The single statement of
  * the `{ guard, …structuralPayloadFields }` reply contract, shared with the
- * compiled default Captain artifact so the wording cannot drift.
+ * compiled default Captain artifact so the wording cannot drift. Each declared
+ * key keeps its description verbatim and gains the exact reply it takes
+ * (DR-089): `guard` plus the structural fields its `Output shall include`
+ * clause names, each with its authored placeholder, while the visible
+ * `question` and `response` fields are named as runtime-supplied. A
+ * `correction` restates a structurally invalid first reply and its
+ * validation error for the one corrective adjudication.
  */
 export declare function defaultBuildCaptainJudgePrompt(input: {
     readonly stateId: string;
     readonly sourceItem: string;
     readonly result: Readonly<Record<string, string>>;
-}, finalText: string): string;
+}, finalText: string, correction?: {
+    readonly reply: string;
+    readonly error: string;
+}): string;
 /**
  * Targets of the FSM's `awaitBossReply` BOSS_REPLY transitions, plus — for
  * the parallel shape gears2fsm compiles (DR-067) — the targets of each
@@ -554,6 +564,13 @@ export declare function stateDescriptionsFromMachine(machine: AnyStateMachine):
  * other than `success` or `failure`, is a malformed artifact and throws.
  */
 export declare function terminalOutcomesFromMachine(machine: AnyStateMachine, label?: string): ReadonlyMap<string, 'success' | 'failure'>;
+/**
+ * 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
+ * the same contract the shared factory enforces.
+ */
+export declare function inferSemanticValueShapes(machine: AnyStateMachine, authority: XStateOutcomeAuthoritySpec): ReadonlyMap<string, PlaybookSemanticValueShapes>;
 /**
  * Build a `PlaybookRuntimeFactory` that interprets the given FSM artifact
  * under the slc/link.md contract. The factory provides every actor kind the

package/src/xstate-playbook-runtime.js

@@ -20,9 +20,9 @@ import { randomUUID } from 'node:crypto';
 import { isDeepStrictEqual } from 'node:util';
 import PQueue from 'p-queue';
 import { createActor, fromPromise } from 'xstate';
-import { createAcceptedOutcomeConsumer, } from './accepted-outcome.js';
+import { ACCEPTED_OUTCOME_ACTION_TYPE, createAcceptedOutcomeConsumer, } from './accepted-outcome.js';
 import { assertPlaybookFailureCause } from './runtime.js';
-import { assertPlaybookRuntimeSnapshot, assertPlaybookEffectLedger, attachPlaybookFailureCause, combineAbortSignals, createNestedPlaybookBridge, detachPersistedMachineSnapshot, normalizeError, normalizePlaybookSnapshot, snapshotJsonValue, snapshotPlaybookSession, isPlaybookEffectLedgerMonotonicExtension, PlaybookSemanticCandidateStructureError, reconcilePlaybookSemanticEvidence, validateCaptainResult, validatePlayerResult, waitForPlaybookQuiescence, } from './xstate-runtime.js';
+import { assertPlaybookRuntimeSnapshot, assertPlaybookEffectLedger, attachPlaybookFailureCause, combineAbortSignals, createNestedPlaybookBridge, describePlaybookSemanticValueShape, detachPersistedMachineSnapshot, normalizeError, normalizePlaybookSnapshot, snapshotJsonValue, snapshotPlaybookSession, isPlaybookEffectLedgerMonotonicExtension, PlaybookSemanticCandidateStructureError, reconcilePlaybookSemanticEvidence, validateCaptainResult, validatePlayerResult, waitForPlaybookQuiescence, } from './xstate-runtime.js';
 export const BOSS_REPLY_ERRORS = {
     missingQuestion: "needsBossReply outcome missing 'question' field",
     unregisteredState: (stateId) => `state ${stateId} declared needsBossReply but is not registered as resumable`,
@@ -906,7 +906,7 @@ export function defaultBuildJudgePrompt(input, finalText) {
  * self-inflicted defect. Exported so linked machinery of an artifact's own
  * renders the identical contract instead of restating it.
  */
-export function renderGovernedOutcomeContract(guard, description, outcome) {
+export function renderGovernedOutcomeContract(guard, description, outcome, shapes) {
     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
@@ -934,11 +934,20 @@ export function renderGovernedOutcomeContract(guard, description, outcome) {
     }
     const replyMembers = [`"guard": ${JSON.stringify(guard)}`];
     const semanticAsAuthored = [];
+    const valueShapes = [];
     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>'}`);
+            // DR-089: the value has the shape the compiled machine admits.
+            const shape = shapes !== undefined && Object.prototype.hasOwnProperty.call(shapes, field)
+                ? shapes[field]
+                : 'string';
+            const words = describePlaybookSemanticValueShape(shape);
+            replyMembers.push(`${JSON.stringify(field)}: ${entry?.placeholder ??
+                (shape === 'string' ? '<string>' : `<${words.replace(/^a /, '')}>`)}`);
+            if (shape !== 'string')
+                valueShapes.push(`\`${field}\` is ${words}`);
             semanticAsAuthored.push(entry?.segment ?? `\`${field}\``);
         }
         else {
@@ -949,6 +958,9 @@ export function renderGovernedOutcomeContract(guard, description, outcome) {
         meaning.length === 0 ? `- \`${guard}\`` : `- \`${guard}\` — ${meaning}`,
         `  Reply exactly: { ${replyMembers.join(', ')} }`,
     ];
+    if (valueShapes.length > 0) {
+        lines.push(`  JSON value shape: ${valueShapes.join('; ')}`);
+    }
     if (semanticAsAuthored.length > 0) {
         lines.push(`  Semantic fields as authored: ${semanticAsAuthored.join('; ')}`);
     }
@@ -957,7 +969,7 @@ export function renderGovernedOutcomeContract(guard, description, outcome) {
     }
     return lines;
 }
-function buildGovernedJudgePrompt(input, finalText, outcomes, correction) {
+function buildGovernedJudgePrompt(input, finalText, outcomes, correction, shapes) {
     const lines = [
         'This is hidden control work. Do not call tools, inspect files, or seek external evidence.',
         'Decide only from the supplied player output and declared outcomes.',
@@ -976,7 +988,7 @@ function buildGovernedJudgePrompt(input, finalText, outcomes, correction) {
         '',
     ];
     for (const [guard, description] of Object.entries(input.result)) {
-        lines.push(...renderGovernedOutcomeContract(guard, description, outcomes[guard]));
+        lines.push(...renderGovernedOutcomeContract(guard, description, outcomes[guard], shapes?.[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.');
@@ -1133,9 +1145,15 @@ export function createPlayerBridge(spec, ports, getActiveSignal, boundary, onCon
 /**
  * Default direct-Captain adjudicator prompt (DR-025). The single statement of
  * the `{ guard, …structuralPayloadFields }` reply contract, shared with the
- * compiled default Captain artifact so the wording cannot drift.
+ * compiled default Captain artifact so the wording cannot drift. Each declared
+ * key keeps its description verbatim and gains the exact reply it takes
+ * (DR-089): `guard` plus the structural fields its `Output shall include`
+ * clause names, each with its authored placeholder, while the visible
+ * `question` and `response` fields are named as runtime-supplied. A
+ * `correction` restates a structurally invalid first reply and its
+ * validation error for the one corrective adjudication.
  */
-export function defaultBuildCaptainJudgePrompt(input, finalText) {
+export function defaultBuildCaptainJudgePrompt(input, finalText, correction) {
     const lines = [];
     lines.push('Adjudicate the direct Captain output for this FSM state.');
     lines.push(`State id: ${input.stateId}`);
@@ -1149,25 +1167,71 @@ export function defaultBuildCaptainJudgePrompt(input, finalText) {
     lines.push('Result keys and descriptions:');
     for (const [key, description] of Object.entries(input.result)) {
         lines.push(`- \`${key}\` — ${description}`);
+        const { clause } = splitOutputClause(description);
+        const replyMembers = [`"guard": ${JSON.stringify(key)}`];
+        const runtimeSupplied = [];
+        const seen = new Set();
+        for (const m of clause === undefined
+            ? []
+            : clause.matchAll(PAYLOAD_FIELD_PATTERN)) {
+            const field = m[1];
+            if (seen.has(field))
+                continue;
+            seen.add(field);
+            if (field === 'question' || field === 'response') {
+                runtimeSupplied.push(`\`${field}\``);
+                continue;
+            }
+            const placeholder = m[2]?.trim();
+            replyMembers.push(`${JSON.stringify(field)}: ${placeholder !== undefined && placeholder.length > 0
+                ? placeholder
+                : '<value>'}`);
+        }
+        lines.push(`  Reply exactly: { ${replyMembers.join(', ')} }`);
+        if (runtimeSupplied.length > 0) {
+            lines.push(`  Runtime-supplied, do not include: ${runtimeSupplied.join(', ')}`);
+        }
     }
     lines.push('');
     lines.push('Pick exactly one outcome by `guard` and return JSON ' +
         '`{ guard, …structuralPayloadFields }`. Do not include `question` or ' +
         '`response`; the runtime injects the visible text.');
+    lines.push('Reply with exactly that outcome\'s reply shape above and no other field.');
+    if (correction !== undefined) {
+        lines.push('', 'Your first reply was structurally invalid:', '', '```', correction.reply, '```', '', `Validation error: ${correction.error}`, 'Correct only that structure using the same Captain output and outcome schema.');
+    }
     return lines.join('\n');
 }
+/**
+ * A direct-Captain adjudication reply that fails structural validation
+ * (DR-089): it earns one corrective adjudication, and a second such reply
+ * parks the step as a decided `judge-failed` failure rather than escaping as
+ * a control-plane error.
+ */
+class CaptainAdjudicationStructureError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CaptainAdjudicationStructureError';
+    }
+}
 function adjudicateCaptainOutput(extractFields, input, finalText, judgeText) {
-    const parsed = parseJudgeJson(judgeText);
+    let parsed;
+    try {
+        parsed = parseJudgeJson(judgeText);
+    }
+    catch (error) {
+        throw new CaptainAdjudicationStructureError(`adjudicate: ${error instanceof Error ? error.message : 'judge response is not valid JSON'}`);
+    }
     if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-        throw new Error('adjudicate: judge response is not a JSON object');
+        throw new CaptainAdjudicationStructureError('adjudicate: judge response is not a JSON object');
     }
     const obj = parsed;
     const guard = obj.guard;
     if (typeof guard !== 'string') {
-        throw new Error('adjudicate: judge response missing string "guard" field');
+        throw new CaptainAdjudicationStructureError('adjudicate: judge response missing string "guard" field');
     }
     if (!Object.prototype.hasOwnProperty.call(input.result, guard)) {
-        throw new Error(`adjudicate: unknown guard "${guard}" — declared guards: ${Object.keys(input.result).join(', ')}`);
+        throw new CaptainAdjudicationStructureError(`adjudicate: unknown guard "${guard}" — declared guards: ${Object.keys(input.result).join(', ')}`);
     }
     const required = extractFields(input.result[guard]);
     const allowed = new Set(['guard']);
@@ -1177,14 +1241,14 @@ function adjudicateCaptainOutput(extractFields, input, finalText, judgeText) {
     }
     for (const key of Object.keys(obj)) {
         if (!allowed.has(key)) {
-            throw new Error(`adjudicate: judge response supplied undeclared field "${key}" for guard "${guard}"`);
+            throw new CaptainAdjudicationStructureError(`adjudicate: judge response supplied undeclared field "${key}" for guard "${guard}"`);
         }
     }
     for (const field of required) {
         if (field === 'question' || field === 'response')
             continue;
         if (obj[field] === undefined || obj[field] === null) {
-            throw new Error(`adjudicate: judge response missing required field "${field}" for guard "${guard}"`);
+            throw new CaptainAdjudicationStructureError(`adjudicate: judge response missing required field "${field}" for guard "${guard}"`);
         }
     }
     const output = { ...obj, guard };
@@ -1934,6 +1998,156 @@ function snapshotOutcomeAuthority(descriptor, label, playerStates, verbatimPaylo
         governedPlayerStates: Object.freeze(normalizedStates),
     });
 }
+// ---------------------------------------------------------------------------
+// DR-089: one type contract for semantic-owned fields. The compiled machine's
+// own validator decides which JSON value it admits for each field, so the
+// runtime asks it once at construction: each governed outcome is presented to
+// 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.
+// ---------------------------------------------------------------------------
+const SEMANTIC_SHAPE_SAMPLES = [
+    ['string', 'sample'],
+    ['string-array', ['sample']],
+    ['number-array', [1]],
+    ['number', 1],
+    ['boolean', true],
+];
+const SHAPE_PROBE_TEXT = 'sample';
+const SHAPE_PROBE_COMMIT = '0123456789abcdef0123456789abcdef01234567';
+const SHAPE_PROBE_FIELD_LIMIT = 4;
+function isAcceptedOutcomeMarker(action, stateId, guard) {
+    if (!isPlainObject(action) || action.type !== ACCEPTED_OUTCOME_ACTION_TYPE) {
+        return false;
+    }
+    const params = action.params;
+    return (isPlainObject(params) &&
+        params.source === stateId &&
+        params.acceptedOutcome === guard);
+}
+function shapeCombinations(fieldCount) {
+    const combinations = [[]];
+    for (let field = 0; field < fieldCount; field += 1) {
+        const next = [];
+        for (const prefix of combinations) {
+            for (let sample = 0; sample < SEMANTIC_SHAPE_SAMPLES.length; sample += 1) {
+                next.push([...prefix, sample]);
+            }
+        }
+        combinations.splice(0, combinations.length, ...next);
+    }
+    // Fewest non-string fields first, then the sample order, so a machine that
+    // admits strings keeps them.
+    return combinations.sort((left, right) => left.filter((index) => index !== 0).length -
+        right.filter((index) => index !== 0).length ||
+        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
+ * the same contract the shared factory enforces.
+ */
+export function inferSemanticValueShapes(machine, authority) {
+    const shapesByState = new Map();
+    const playerNodes = new Map();
+    const visit = (node) => {
+        if (node.invoke.some(({ src }) => src === 'player')) {
+            const playbookMeta = isPlainObject(node.config.meta)
+                ? node.config.meta.playbook
+                : undefined;
+            const stateId = isPlainObject(playbookMeta) && typeof playbookMeta.stateId === 'string'
+                ? playbookMeta.stateId
+                : typeof node.config.id === 'string'
+                    ? node.config.id
+                    : node.key;
+            if (!playerNodes.has(stateId))
+                playerNodes.set(stateId, node);
+        }
+        for (const child of Object.values(node.states))
+            visit(child);
+    };
+    try {
+        visit(machine.root);
+    }
+    catch {
+        return shapesByState;
+    }
+    const configContext = machine
+        .config?.context;
+    const context = isPlainObject(configContext) ? configContext : {};
+    for (const [stateId, outcomes] of Object.entries(authority.governedPlayerStates)) {
+        const node = playerNodes.get(stateId);
+        const invokeId = node?.invoke.find(({ src }) => src === 'player')?.id;
+        if (node === undefined || invokeId === undefined)
+            continue;
+        let snapshot;
+        try {
+            const value = [...node.path].reduceRight((inner, key) => (inner === undefined ? key : { [key]: inner }), undefined);
+            snapshot = machine.resolveState({ value: value, context });
+        }
+        catch {
+            continue;
+        }
+        const stateShapes = {};
+        for (const [guard, outcome] of Object.entries(outcomes)) {
+            const semanticFields = Object.entries(outcome.fields)
+                .filter(([, fieldAuthority]) => fieldAuthority === 'semantic')
+                .map(([field]) => field);
+            if (semanticFields.length === 0 ||
+                semanticFields.length > SHAPE_PROBE_FIELD_LIMIT) {
+                continue;
+            }
+            const base = { guard };
+            for (const [field, fieldAuthority] of Object.entries(outcome.fields)) {
+                if (fieldAuthority === 'effect')
+                    base[field] = SHAPE_PROBE_COMMIT;
+                else if (fieldAuthority !== 'semantic')
+                    base[field] = SHAPE_PROBE_TEXT;
+            }
+            const admits = (values) => {
+                try {
+                    const transitions = machine.getTransitionData(snapshot, {
+                        type: `xstate.done.actor.${invokeId}`,
+                        output: { ...base, ...values },
+                        actorId: invokeId,
+                    });
+                    return transitions.some((transition) => transition.actions.some((action) => isAcceptedOutcomeMarker(action, stateId, guard)));
+                }
+                catch {
+                    return false;
+                }
+            };
+            for (const combination of shapeCombinations(semanticFields.length)) {
+                const values = {};
+                semanticFields.forEach((field, index) => {
+                    values[field] = SEMANTIC_SHAPE_SAMPLES[combination[index]][1];
+                });
+                if (!admits(values))
+                    continue;
+                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;
+                });
+                if (Object.keys(shapes).length > 0) {
+                    stateShapes[guard] = Object.freeze(shapes);
+                }
+                break;
+            }
+        }
+        if (Object.keys(stateShapes).length > 0) {
+            shapesByState.set(stateId, Object.freeze(stateShapes));
+        }
+    }
+    return shapesByState;
+}
 function sameStringSet(left, right) {
     if (left.length !== right.length)
         return false;
@@ -2513,6 +2727,7 @@ export function createXStatePlaybookRuntime(machine, spec) {
         verbatimPayloadFields,
     };
     const outcomeAuthority = snapshotOutcomeAuthority(specDescriptors.outcomeAuthority, label, roleStates, verbatimPayloadFields);
+    const semanticValueShapes = inferSemanticValueShapes(machine, outcomeAuthority);
     for (const [stateId, outcomes] of Object.entries(outcomeAuthority.governedPlayerStates)) {
         if (Object.values(outcomes).some(({ repositoryDisposition }) => repositoryDisposition === 'deferred') &&
             !resumableStateIds.has(stateId)) {
@@ -2900,6 +3115,7 @@ export function createXStatePlaybookRuntime(machine, spec) {
                     semanticCandidate: candidate.semanticCandidate,
                     finalText: candidate.finalText,
                     receipt,
+                    semanticValueShapes: semanticValueShapes.get(candidate.sourceStateId),
                 });
                 if (awaitingLogicalReceipt &&
                     reconciliation.status !== 'deferred') {
@@ -3745,7 +3961,7 @@ export function createXStatePlaybookRuntime(machine, spec) {
             }
             let raw;
             try {
-                raw = await boundary.callJudge('player-output-adjudication', input.stateId, buildGovernedJudgePrompt(input, finalText, outcomes), signal);
+                raw = await boundary.callJudge('player-output-adjudication', input.stateId, buildGovernedJudgePrompt(input, finalText, outcomes, undefined, semanticValueShapes.get(input.stateId)), signal);
             }
             catch (error) {
                 governedSettlementsByBoundaryId.set(completion.boundary.boundaryId, unresolvedGovernedSettlement('judge transport failed', error, signal));
@@ -3779,6 +3995,7 @@ export function createXStatePlaybookRuntime(machine, spec) {
                     semanticCandidate: candidate,
                     finalText,
                     receipt: completion.outcomeReceipt,
+                    semanticValueShapes: semanticValueShapes.get(input.stateId),
                 });
             }
             catch (error) {
@@ -3811,7 +4028,7 @@ export function createXStatePlaybookRuntime(machine, spec) {
                     correctiveRaw = await boundary.callJudge('player-output-adjudication', input.stateId, buildGovernedJudgePrompt(input, finalText, outcomes, {
                         reply: raw,
                         error: structuralError.message,
-                    }), signal);
+                    }, semanticValueShapes.get(input.stateId)), signal);
                 }
                 catch (error) {
                     governedSettlementsByBoundaryId.set(completion.boundary.boundaryId, unresolvedGovernedSettlement('corrective judge failed', error, signal));
@@ -3825,6 +4042,7 @@ export function createXStatePlaybookRuntime(machine, spec) {
                         semanticCandidate: candidate,
                         finalText,
                         receipt: completion.outcomeReceipt,
+                        semanticValueShapes: semanticValueShapes.get(input.stateId),
                     });
                 }
                 catch (error) {
@@ -4202,12 +4420,13 @@ export function createXStatePlaybookRuntime(machine, spec) {
             const actorInput = input.snapshot.input;
             const outcomes = governedOutcomesForBoundary(saved);
             const candidate = saved.semanticCandidate ??
-                parseGovernedSemanticCandidate(await boundary.callJudge('player-output-adjudication', saved.sourceStateId, buildGovernedJudgePrompt(actorInput, saved.finalText, outcomes), signal));
+                parseGovernedSemanticCandidate(await boundary.callJudge('player-output-adjudication', saved.sourceStateId, buildGovernedJudgePrompt(actorInput, saved.finalText, outcomes, undefined, semanticValueShapes.get(saved.sourceStateId)), signal));
             const result = reconcilePlaybookSemanticEvidence({
                 outcomes,
                 semanticCandidate: candidate,
                 finalText: saved.finalText,
                 receipt: saved.physicalReceipt,
+                semanticValueShapes: semanticValueShapes.get(saved.sourceStateId),
             });
             signal.throwIfAborted();
             const next = {
@@ -5334,7 +5553,37 @@ export function createXStatePlaybookRuntime(machine, spec) {
                     }
                     const judgePrompt = defaultBuildCaptainJudgePrompt(input, finalText);
                     const raw = await boundary.callJudge('captain-output-adjudication', input.stateId, judgePrompt, active);
-                    const output = adjudicateCaptainOutput(extractFields, input, finalText, raw);
+                    let output;
+                    try {
+                        output = adjudicateCaptainOutput(extractFields, input, finalText, raw);
+                    }
+                    catch (error) {
+                        if (!(error instanceof CaptainAdjudicationStructureError)) {
+                            throw error;
+                        }
+                        // DR-089: one corrective adjudication over the same visible
+                        // output, restating the reply and its validation error; an
+                        // abort before it begins starts none.
+                        active.throwIfAborted();
+                        const correctiveRaw = await boundary.callJudge('captain-output-adjudication', input.stateId, defaultBuildCaptainJudgePrompt(input, finalText, {
+                            reply: raw,
+                            error: error.message,
+                        }), active);
+                        try {
+                            output = adjudicateCaptainOutput(extractFields, input, finalText, correctiveRaw);
+                        }
+                        catch (corrective) {
+                            if (!(corrective instanceof CaptainAdjudicationStructureError)) {
+                                throw corrective;
+                            }
+                            // A second invalid reply parks the step for Boss as a
+                            // decided adjudication failure, never a control-plane error.
+                            const failure = markFsmResultFailure(new Error(`${label} Captain outcome stayed undecided: ${corrective.message}`));
+                            const cause = governedSettlementCause('corrective semantic candidate is invalid', undefined, false, undefined);
+                            failureCauses.retain(failure, cause);
+                            throw attachPlaybookFailureCause(failure, cause);
+                        }
+                    }
                     validateBossReplyOutput(input, output, resumableStateIds);
                     return output;
                 }