@sublang/playbook 4.0.0 → 6.0.0

package/reference/sdlc/captain.playbook/captain.playbook.js

@@ -1,21 +1,40 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 //
-// slc link artifact
-// FSM path: ./captain.fsm.ts
-// Player binding: none (no delegated-player states)
-// Adjudication strategy: LLM-judge per Captain state
-// Boss-event mapping: deterministic ready entry; LLM-judge classification otherwise
-import PQueue from 'p-queue';
-import { createActor, fromPromise } from 'xstate';
+// Generated by slc/link.md (FSM-to-Runtime linker).
+// Source FSM:    ./captain.fsm.ts
+// Player bind:   none (the session Captain declares no player behavior)
+// Boss event:    deterministic controller entry (slc/link.md §Boss-event
+//                mapping): every turn maps from the exact Boss text and the
+//                host's command-parse resolution supplied through the linked
+//                options' controller port — BOSS_TURN / PARSED_RESPOND /
+//                PARSED_ACTION / SHUTDOWN — with no classifier judge call.
+// Captain calls: hidden controller form (slc/link.md §Captain adjudication,
+//                DR-029): decision and closing-reply calls run
+//                `{ visibility: 'hidden' }`; the host's session-Captain
+//                wrapper owns the durable-conversation resume selection and
+//                pins the returned token (the runtime requests
+//                `resume: false` as the typed placeholder and its traces
+//                carry no resume member). The decision reply is `{ action,
+//                … }` control JSON validated here against the declared
+//                decision-state contract — never adjudicated through a
+//                judge call and never Boss presentation; controller prose
+//                reaches Boss only as host-validated captain speech through
+//                the host's presentation seam (cligent
+//                `CaptainContext.emitReply`).
+// Contract:      types imported and re-exported from
+//                @sublang/playbook/runtime (slc/link.md §Output); the
+//                shared createXStatePlaybookRuntime factory from
+//                @sublang/playbook/xstate-runtime interprets the FSM
+//                (DR-019). This module carries only the Captain-specific
+//                spec: options validation (catalog + controller port),
+//                deterministic entry mapping, the controller captain-call
+//                strategy with its single corrective re-ask (CAPPLAY-18),
+//                controller-port submission, and status formatting.
+// Compat:        spec.compat = { artifactSchema: 1, runtimeAbi: 1 }
+//                (DR-022; checked at construction by the loading engine).
+import { createXStatePlaybookRuntime, defaultComposeCaptainPrompt, normalizeError, normalizeErrorCompact, parseJudgeJson, snapshotJsonValue, RUNTIME_ABI, } from '../../../src/xstate-runtime.js';
 import { captainMachine, } from './captain.fsm.js';
-import { assertJsonSafe, combineAbortSignals, createNestedPlaybookBridge, defaultBuildCaptainJudgePrompt, normalizeError, normalizePlaybookSnapshot, snapshotJsonValue, snapshotPlaybookSession, validateCaptainResult, waitForPlaybookQuiescence, } from '../../../src/xstate-runtime.js';
-const CAPTAIN_OPTIONS = {
-    visibility: 'visible',
-    resume: false,
-    allowedTools: [],
-};
-const CONTINUATION_PREAMBLE = 'You previously paused this task to ask Boss a question; Boss has now replied. Continue the same task using the reply below.';
 function assertNonEmptyString(value, label) {
     if (typeof value !== 'string' || value.trim().length === 0) {
         throw new TypeError(`${label} must be a non-empty string`);
@@ -29,66 +48,6 @@ function isRecord(value) {
     const prototype = Object.getPrototypeOf(value);
     return prototype === Object.prototype || prototype === null;
 }
-function omitUndefined(value) {
-    const copy = {};
-    for (const [key, entry] of Object.entries(value)) {
-        if (entry !== undefined) {
-            assertJsonSafe(entry, key);
-            copy[key] = snapshotJsonValue(entry, key);
-        }
-    }
-    return snapshotJsonValue(copy);
-}
-function stableJson(value) {
-    const json = snapshotJsonValue(value);
-    return JSON.stringify(sortJson(json));
-}
-function sortJson(value) {
-    if (Array.isArray(value))
-        return Object.freeze(value.map((entry) => sortJson(entry)));
-    if (value && typeof value === 'object') {
-        const record = value;
-        const sorted = {};
-        for (const key of Object.keys(value).sort()) {
-            sorted[key] = sortJson(record[key]);
-        }
-        return Object.freeze(sorted);
-    }
-    return value;
-}
-function replacePlaceholders(template, replacements) {
-    return template.replace(/<[^>\n]+>/g, (placeholder) => replacements.get(placeholder) ?? placeholder);
-}
-function continuationPrefix(input) {
-    if (!input.pendingBossQuestion || !input.bossReply)
-        return '';
-    return [
-        CONTINUATION_PREAMBLE,
-        '',
-        'Boss question:',
-        input.pendingBossQuestion.question,
-        '',
-        'Boss reply:',
-        input.bossReply,
-        '',
-        '',
-    ].join('\n');
-}
-export function composeCaptainPrompt(input) {
-    const replacements = new Map();
-    replacements.set('<boss-intent>', input.bossIntent);
-    replacements.set('<enabled-playbooks>', stableJson(input.enabledPlaybooks));
-    if (input.remainingPlan !== undefined) {
-        replacements.set('<remaining-plan>', stableJson(input.remainingPlan));
-    }
-    if (input.completedCallResults !== undefined) {
-        replacements.set('<completed-call-results>', stableJson(input.completedCallResults));
-    }
-    return `${continuationPrefix(input)}${replacePlaceholders(input.prompt, replacements)}`;
-}
-export function composePlayerPrompt(input) {
-    return `${continuationPrefix(input)}${input.prompt}`;
-}
 function validateEnabledPlaybooks(value) {
     if (!Array.isArray(value)) {
         throw new TypeError('enabledPlaybooks must be an array');
@@ -112,950 +71,481 @@ function validateEnabledPlaybooks(value) {
         return Object.freeze({ id, command, intent });
     }));
 }
-function parseJsonObjectLoose(text) {
-    const source = text;
-    for (let start = 0; start < source.length; start += 1) {
-        if (source[start] !== '{')
-            continue;
-        const bounded = boundedJsonCandidate(source, start);
-        const candidates = bounded ? [bounded, bounded.replace(/,\s*([}\]])/g, '$1')] : [repairJsonSuffix(source.slice(start))];
-        for (const candidate of candidates) {
-            try {
-                const parsed = JSON.parse(candidate);
-                if (isRecord(parsed))
-                    return parsed;
-            }
-            catch {
-                // Try the next candidate at the same object boundary.
-            }
-        }
+function validateControllerPort(value) {
+    if (value === null || typeof value !== 'object') {
+        throw new TypeError('options.controller must be an object');
     }
-    return undefined;
-}
-function boundedJsonCandidate(source, start) {
-    let depth = 0;
-    let inString = false;
-    let escaped = false;
-    for (let index = start; index < source.length; index += 1) {
-        const char = source[index];
-        if (inString) {
-            if (escaped)
-                escaped = false;
-            else if (char === '\\')
-                escaped = true;
-            else if (char === '"')
-                inString = false;
-            continue;
-        }
-        if (char === '"')
-            inString = true;
-        else if (char === '{' || char === '[')
-            depth += 1;
-        else if (char === '}' || char === ']') {
-            depth -= 1;
-            if (depth === 0)
-                return source.slice(start, index + 1);
-        }
+    const record = value;
+    if (typeof record.submit !== 'function') {
+        throw new TypeError('options.controller.submit must be a function');
     }
-    return undefined;
-}
-function repairJsonSuffix(source) {
-    let repaired = source.replace(/,\s*$/g, '');
-    let inString = false;
-    let escaped = false;
-    const stack = [];
-    for (const char of repaired) {
-        if (inString) {
-            if (escaped)
-                escaped = false;
-            else if (char === '\\')
-                escaped = true;
-            else if (char === '"')
-                inString = false;
-            continue;
-        }
-        if (char === '"')
-            inString = true;
-        else if (char === '{')
-            stack.push('}');
-        else if (char === '[')
-            stack.push(']');
-        else if (char === '}' || char === ']')
-            stack.pop();
+    if (record.resolveParsedTurn !== undefined &&
+        typeof record.resolveParsedTurn !== 'function') {
+        throw new TypeError('options.controller.resolveParsedTurn must be a function when present');
     }
-    if (inString)
-        repaired += '"';
-    while (stack.length > 0)
-        repaired += stack.pop();
-    return repaired.replace(/,\s*([}\]])/g, '$1');
-}
-function requiredOutputFields(description) {
-    const marker = description.match(/Output shall include\s+(.+)$/);
-    if (!marker)
-        return [];
-    const fields = [];
-    const seen = new Set();
-    const regex = /`([^`]+)`/g;
-    let match;
-    while ((match = regex.exec(marker[1])) !== null) {
-        const name = match[1].split(':', 1)[0]?.trim();
-        if (name && /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) && !seen.has(name)) {
-            seen.add(name);
-            fields.push(name);
-        }
-    }
-    return fields;
+    return value;
 }
-function makeJudgePrompt(input, visibleText) {
-    return defaultBuildCaptainJudgePrompt(input, visibleText);
+function snapshotCaptainOptions(value) {
+    if (!isRecord(value)) {
+        throw new TypeError('Captain runtime options must be an object');
+    }
+    const allowed = new Set(['enabledPlaybooks', 'controller']);
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key)) {
+            throw new TypeError(`Captain runtime options.${key} is not declared`);
+        }
+    }
+    const enabledPlaybooks = validateEnabledPlaybooks(value.enabledPlaybooks);
+    const controller = value.controller === undefined
+        ? undefined
+        : validateControllerPort(value.controller);
+    return Object.freeze({
+        enabledPlaybooks,
+        ...(controller === undefined ? {} : { controller }),
+    });
 }
-// CAPPLAY-18: a structurally malformed adjudication reply gets exactly one
-// corrective re-ask carrying the rejection reason and the restated shape.
-function makeJudgeRetryPrompt(judgePrompt, rejection) {
-    return [
-        judgePrompt,
-        '',
-        `Your previous control reply was rejected: ${normalizeError(rejection).message}.`,
-        'Reply again with exactly one JSON object naming one declared `guard` key and only its required structural fields, with no prose.',
-    ].join('\n');
+// ---------------------------------------------------------------------------
+// Deterministic controller entry mapping (slc/link.md §Boss-event mapping):
+// the exact Boss text rides the runtime-owned `bossText` field; the host's
+// parse resolution selects the hub entry arm; no classifier judge call runs.
+// ---------------------------------------------------------------------------
+function validateParsedActingDecision(value) {
+    if (!isRecord(value)) {
+        throw new TypeError('parse-resolved decision must be an object');
+    }
+    if (value.action === 'deliver') {
+        if (Object.keys(value).length !== 1) {
+            throw new TypeError('a parse-resolved deliver decision carries no payload');
+        }
+        return { action: 'deliver' };
+    }
+    if (value.action !== 'start' && value.action !== 'switch') {
+        throw new TypeError(`parse-resolved decision names unknown action ${String(value.action)}`);
+    }
+    const allowed = new Set(['action', 'playbookId', 'input']);
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key)) {
+            throw new TypeError(`parse-resolved decision carries undeclared ${key}`);
+        }
+    }
+    return {
+        action: value.action,
+        playbookId: assertNonEmptyString(value.playbookId, 'parse-resolved decision playbookId'),
+        input: assertNonEmptyString(value.input, 'parse-resolved decision input'),
+    };
 }
-function adjudicateCaptainOutput(input, visibleText, judgeText) {
-    const parsed = parseJsonObjectLoose(judgeText);
-    if (!parsed)
-        throw new Error('adjudicator reply did not contain a JSON object');
-    const guard = parsed.guard;
-    if (typeof guard !== 'string' || !(guard in input.result)) {
-        throw new Error(`adjudicator selected undeclared guard ${String(guard)}`);
-    }
-    const allowed = new Set(['guard']);
-    for (const field of requiredOutputFields(input.result[guard] ?? '')) {
-        if (field !== 'question' && field !== 'response')
-            allowed.add(field);
-    }
-    for (const key of Object.keys(parsed)) {
-        if (!allowed.has(key))
-            throw new Error(`adjudicator supplied undeclared field ${key}`);
-    }
-    if (guard === 'question' || guard === 'followUpQuestion' || guard === 'needsBossReply') {
-        return { guard, question: visibleText };
-    }
-    if (guard === 'final') {
-        return { guard, response: visibleText };
-    }
-    if (guard === 'delegation' || guard === 'continuing') {
-        const missing = ['remainingPlan', 'nextPlaybookId', 'nextPlaybookInput'].filter((field) => !(field in parsed));
-        if (missing.length > 0) {
-            throw new Error(`adjudicator omitted required field ${missing.join(', ')}`);
-        }
-        const remainingPlan = snapshotJsonValue(parsed.remainingPlan, 'remainingPlan');
-        if (!Array.isArray(remainingPlan))
-            throw new Error('adjudicator remainingPlan must be a JSON array');
-        return {
-            guard,
-            remainingPlan,
-            nextPlaybookId: assertNonEmptyString(parsed.nextPlaybookId, 'nextPlaybookId'),
-            nextPlaybookInput: assertNonEmptyString(parsed.nextPlaybookInput, 'nextPlaybookInput'),
-        };
-    }
-    throw new Error(`adjudicator selected unsupported guard ${guard}`);
-}
-function validateClassifier(text, bossText, pendingQuestionId) {
-    const parsed = parseJsonObjectLoose(text);
-    if (!parsed)
-        return undefined;
-    const type = parsed.type;
-    if (type === 'NO_ACTION') {
-        if (Object.keys(parsed).length !== 1)
-            return undefined;
-        return { type: 'NO_ACTION' };
-    }
-    if (type === 'BOSS_INTENT') {
-        if (Object.keys(parsed).length !== 1)
-            return undefined;
-        return { type: 'BOSS_INTENT', bossIntent: bossText };
-    }
-    if (type === 'BOSS_INTERRUPT') {
-        if (Object.keys(parsed).sort().join('\0') !== ['targetId', 'type'].join('\0'))
-            return undefined;
-        if (parsed.targetId !== 'routing')
-            return undefined;
-        return { type: 'BOSS_INTERRUPT', targetId: 'routing', bossIntent: bossText };
-    }
-    if (type === 'BOSS_REPLY') {
-        const keys = Object.keys(parsed).sort();
-        if (keys.join('\0') !== ['questionId', 'type'].join('\0') && keys.join('\0') !== 'type')
-            return undefined;
-        const questionId = parsed.questionId === undefined ? pendingQuestionId : parsed.questionId;
-        if (questionId !== pendingQuestionId || typeof questionId !== 'string')
-            return undefined;
-        return { type: 'BOSS_REPLY', answer: bossText, questionId };
+function classifyControllerTurn(text, _ports, _signal, _snapshotOrState, _boundary, options) {
+    const resolution = options?.controller?.resolveParsedTurn?.(text);
+    if (resolution === undefined) {
+        return Promise.resolve({ type: 'BOSS_TURN', bossText: text });
+    }
+    if (!isRecord(resolution)) {
+        throw new TypeError('controller parse resolution must be an object');
+    }
+    const widened = resolution;
+    switch (widened.kind) {
+        case 'respond':
+            return Promise.resolve({ type: 'PARSED_RESPOND', bossText: text });
+        case 'action':
+            return Promise.resolve({
+                type: 'PARSED_ACTION',
+                bossText: text,
+                decision: validateParsedActingDecision(widened.decision),
+            });
+        case 'shutdown':
+            return Promise.resolve({ type: 'SHUTDOWN' });
+        default:
+            throw new TypeError(`controller parse resolution names unknown kind ${String(widened.kind)}`);
     }
-    return undefined;
 }
-function classifierPrompt(text, state, pending) {
+// ---------------------------------------------------------------------------
+// Decision-reply validation (CAPPLAY-18): the hidden decision call's reply is
+// `{ action, … }` control JSON over the closed set, validated against the
+// declared decision-state contract — known action, required payload fields,
+// catalog membership, never this Captain playbook itself as a target. A
+// malformed reply earns exactly one corrective call appending the rejection
+// reason and the restated reply contract; a second malformed reply settles
+// the turn as a recoverable hub return with no action executed.
+// ---------------------------------------------------------------------------
+const RESTATED_REPLY_CONTRACT = [
+    'Reply again with exactly one JSON object `{ "action": …, … }` and no other text, selecting exactly one action from the closed set `respond` | `start` | `switch` | `dismiss` | `deliver` | `runtime`:',
+    '`{ "action": "respond", "text": … }`, `{ "action": "start", "playbookId": …, "input": … }`, `{ "action": "switch", "playbookId": …, "input": … }`, `{ "action": "dismiss" }`, `{ "action": "deliver" }`, or `{ "action": "runtime", "actionId": … }`; every `input` is one nonempty complete standalone request.',
+].join('\n');
+function correctiveDecisionPrompt(prompt, reason) {
     return [
-        'Classify this Boss message for the Captain playbook FSM.',
+        prompt,
         '',
-        'Boss message:',
-        text,
-        '',
-        'Current state:',
-        stableJson(state),
-        '',
-        'Pending Boss question:',
-        stableJson(pending ?? null),
-        '',
-        'Return JSON only. Allowed objects are {"type":"BOSS_REPLY","questionId":"routing-or-reassessing"}, {"type":"BOSS_INTERRUPT","targetId":"routing"}, {"type":"BOSS_INTENT"}, or {"type":"NO_ACTION"}.',
+        `Your previous control reply was rejected: ${reason}.`,
+        RESTATED_REPLY_CONTRACT,
     ].join('\n');
 }
-function stateFromSnapshot(actor, pendingCall) {
-    return normalizePlaybookSnapshot(actor.getSnapshot(), { pendingCall });
-}
-function resultFromState(state, output, pendingCall, error) {
-    if (pendingCall)
-        return { outcome: 'suspended', state, pendingCall };
-    if (state.status === 'done') {
-        return output === undefined ? { outcome: 'terminal', state } : { outcome: 'terminal', state, output };
-    }
-    if (state.stateId === 'failed') {
-        return error === undefined ? { outcome: 'failed', state } : { outcome: 'failed', state, error: normalizeError(error) };
-    }
-    return { outcome: 'quiescent', state };
-}
-function isAbortLikeError(error) {
-    return normalizeError(error).name === 'AbortError';
-}
-function isSignalAbort(error, signal) {
-    return signal.aborted && error === signal.reason;
-}
-class CaptainPlaybookRuntime {
-    enabledPlaybooks;
-    emissionQueue = new PQueue({ concurrency: 1 });
-    captainLane = new PQueue({ concurrency: 1 });
-    session;
-    actor;
-    nestedBridge;
-    sequence = 0;
-    turnId = 0;
-    callId = 0;
-    boundaryTurnId;
-    playbookCallTurnIds = new Map();
-    activeBoundarySignal;
-    activeTurn;
-    disposing;
-    disposed = false;
-    terminallyDisposedBeforeInit = false;
-    disposalTraceEmitted = false;
-    initializing = false;
-    initializationDone;
-    resolveInitializationDone;
-    latchedControlError;
-    suppressInspection = false;
-    previousState;
-    constructor(options) {
-        this.enabledPlaybooks = validateEnabledPlaybooks(options.enabledPlaybooks);
-    }
-    async init(session) {
-        if (this.session || this.actor)
-            throw new Error('playbook runtime is already initialized');
-        if (this.disposed || this.terminallyDisposedBeforeInit || this.disposing)
-            throw new Error('playbook runtime is disposed');
-        this.initializing = true;
-        this.initializationDone = new Promise((resolve) => {
-            this.resolveInitializationDone = resolve;
-        });
-        this.disposalTraceEmitted = false;
-        let actor;
-        let initialState;
-        try {
-            const captured = snapshotPlaybookSession(session);
-            this.session = captured;
-            this.nestedBridge = this.createBridge(captured);
-            actor = this.createActor(captured, this.nestedBridge);
-            this.actor = actor;
-            initialState = stateFromSnapshot(actor);
-            this.previousState = initialState;
-            await this.trace('session.started', omitUndefined({ state: initialState, stateId: initialState.stateId }));
-            await this.drain();
-            actor.start();
-            await this.drain();
-        }
-        catch (error) {
-            this.suppressInspection = true;
-            actor?.stop();
-            if (initialState && !this.disposalTraceEmitted)
-                await this.bestEffortDisposeTrace(initialState);
-            this.session = undefined;
-            this.actor = undefined;
-            this.nestedBridge = undefined;
-            this.sequence = 0;
-            this.turnId = 0;
-            this.callId = 0;
-            this.latchedControlError = undefined;
-            this.previousState = undefined;
-            this.suppressInspection = false;
-            throw error;
-        }
-        finally {
-            this.initializing = false;
-            this.resolveInitializationDone?.();
-            this.resolveInitializationDone = undefined;
-        }
-    }
-    async handleBossInput(turn) {
-        if (this.activeTurn)
-            throw new Error('playbook runtime already has an active boundary');
-        if (this.disposing || this.disposed)
-            throw new Error('playbook runtime is disposing');
-        const run = this.handleBossInputInner(turn);
-        this.activeTurn = run;
-        try {
-            return await run;
-        }
-        catch (error) {
-            if (isSignalAbort(error, turn.signal)) {
-                const actor = this.actor;
-                const bridge = this.nestedBridge;
-                const snapshot = actor
-                    ? await waitForPlaybookQuiescence(actor, { pendingCalls: bridge })
-                    : undefined;
-                const state = snapshot
-                    ? normalizePlaybookSnapshot(snapshot, { pendingCall: bridge?.getPendingCall() })
-                    : { value: 'failed', activeStateIds: ['failed'], tags: ['playbook.parked'], status: 'active', quiescent: true, stateId: 'failed' };
-                try {
-                    await this.drain();
-                }
-                catch {
-                    // The signal-driven abort remains the public outcome.
-                }
-                return { outcome: 'aborted', state, error: normalizeError(error) };
-            }
-            throw error;
-        }
-        finally {
-            this.activeTurn = undefined;
-            const error = this.latchedControlError;
-            this.latchedControlError = undefined;
-            const aborted = this.activeBoundarySignal?.aborted === true;
-            this.activeBoundarySignal = undefined;
-            this.boundaryTurnId = undefined;
-            if (error && (!aborted || !isAbortLikeError(error)))
-                throw error;
-        }
+function readDecisionReply(reply, options, selfPlaybookId, declaredActions) {
+    let parsed;
+    try {
+        parsed = parseJudgeJson(reply);
     }
-    async resumePlaybookCall(input) {
-        if (this.activeTurn)
-            throw new Error('playbook runtime already has an active boundary');
-        if (this.disposing || this.disposed)
-            throw new Error('playbook runtime is disposing');
-        const run = this.resumePlaybookCallInner(input);
-        this.activeTurn = run;
-        try {
-            return await run;
-        }
-        finally {
-            this.activeTurn = undefined;
-            const error = this.latchedControlError;
-            this.latchedControlError = undefined;
-            const aborted = this.activeBoundarySignal?.aborted === true;
-            this.activeBoundarySignal = undefined;
-            this.boundaryTurnId = undefined;
-            if (error && (!aborted || !isAbortLikeError(error)))
-                throw error;
-        }
-    }
-    dispose() {
-        if (this.activeTurn)
-            return Promise.reject(new Error('cannot dispose during an active boundary'));
-        if (this.disposing)
-            return this.disposing;
-        if (!this.initializing && !this.session && !this.actor && !this.disposed) {
-            this.terminallyDisposedBeforeInit = true;
-            this.disposed = true;
-            this.disposing = Promise.resolve();
-            return this.disposing;
-        }
-        this.disposing = this.disposeInner();
-        return this.disposing;
+    catch {
+        return { reason: 'the reply contains no recoverable JSON object' };
     }
-    async handleBossInputInner(turn) {
-        const actor = this.requireActor();
-        const nestedBridge = this.requireBridge();
-        const currentTurnId = this.nextTurnId();
-        this.boundaryTurnId = currentTurnId;
-        this.activeBoundarySignal = turn.signal;
-        await this.trace('boss.input.received', { text: turn.text }, currentTurnId);
-        const state = stateFromSnapshot(actor, nestedBridge.getPendingCall());
-        let event;
-        if (turn.text.trim().length === 0) {
-            const result = { outcome: 'no-action', state };
-            await this.traceSettled(result, currentTurnId);
-            await this.drain();
-            return result;
-        }
-        if (state.stateId === 'ready' || state.stateId === 'failed') {
-            event = { type: 'BOSS_INTENT', bossIntent: turn.text };
-        }
-        else {
-            try {
-                event = await this.classifyBossInput(turn.text, state, turn.signal);
-            }
-            catch (error) {
-                if (isSignalAbort(error, turn.signal)) {
-                    const result = { outcome: 'aborted', state, error: normalizeError(error) };
-                    await this.traceSettled(result, currentTurnId);
-                    await this.drain();
-                    return result;
-                }
-                await this.trace('boss.input.settled', omitUndefined({
-                    outcome: 'no-action',
-                    state,
-                    stateId: state.stateId,
-                    error: normalizeError(error),
-                }), currentTurnId);
-                await this.drain();
-                throw error;
-            }
-            if (!event) {
-                await this.emitStatus('classification was invalid; Boss input was not actionable.', { state });
-                const result = { outcome: 'no-action', state };
-                await this.traceSettled(result, currentTurnId);
-                await this.drain();
-                return result;
-            }
-        }
-        if (event?.type === 'NO_ACTION') {
-            const result = { outcome: 'no-action', state };
-            await this.traceSettled(result, currentTurnId);
-            await this.drain();
-            return result;
-        }
-        if (turn.signal.aborted) {
-            const result = { outcome: 'aborted', state, error: normalizeError(turn.signal.reason) };
-            await this.traceSettled(result, currentTurnId);
-            await this.drain();
-            return result;
-        }
-        if (actor.getSnapshot().status === 'done') {
-            this.reconstructActor();
-        }
-        this.requireActor().send(event);
-        const snapshot = await waitForPlaybookQuiescence(this.requireActor(), { pendingCalls: nestedBridge });
-        const settledState = normalizePlaybookSnapshot(snapshot, { pendingCall: nestedBridge.getPendingCall() });
-        const result = turn.signal.aborted
-            ? { outcome: 'aborted', state: settledState, error: normalizeError(turn.signal.reason) }
-            : resultFromState(settledState, this.machineOutput(), nestedBridge.getPendingCall(), this.latchedControlError);
-        await this.traceSettled(result, currentTurnId);
-        await this.drain();
-        return result;
+    if (!isRecord(parsed)) {
+        return { reason: 'the reply is not a JSON object' };
     }
-    async resumePlaybookCallInner(input) {
-        const nestedBridge = this.requireBridge();
-        this.activeBoundarySignal = input.signal;
-        this.boundaryTurnId = this.playbookCallTurnIds.get(input.callId);
-        let resumeError;
-        try {
-            await nestedBridge.resume(input);
-        }
-        catch (error) {
-            resumeError = error;
-        }
-        const snapshot = await waitForPlaybookQuiescence(this.requireActor(), { pendingCalls: nestedBridge });
-        const pendingCall = nestedBridge.getPendingCall();
-        const state = normalizePlaybookSnapshot(snapshot, { pendingCall });
-        const result = resultFromState(state, this.machineOutput(), pendingCall);
-        await this.drain();
-        if (resumeError !== undefined)
-            throw resumeError;
-        return input.signal.aborted ? { outcome: 'aborted', state, error: normalizeError(input.signal.reason) } : result;
+    const action = parsed.action;
+    if (typeof action !== 'string' || !declaredActions.has(action)) {
+        return {
+            reason: `the reply names no known action (got ${JSON.stringify(action ?? null)})`,
+        };
     }
-    async disposeInner() {
-        if (this.disposed)
-            return;
-        if (this.initializing) {
-            await this.initializationDone;
-        }
-        const actor = this.actor;
-        const bridge = this.nestedBridge;
-        const finalState = actor ? stateFromSnapshot(actor, bridge?.getPendingCall()) : undefined;
-        let cleanupError;
-        this.suppressInspection = true;
-        actor?.stop();
-        try {
-            await bridge?.dispose();
-        }
-        catch (error) {
-            cleanupError = error;
-        }
-        if (this.initializing) {
-            try {
-                await this.drain();
-            }
-            catch (error) {
-                if (cleanupError === undefined)
-                    cleanupError = error;
+    const requireKeys = (required, tolerated = []) => {
+        for (const key of required) {
+            if (!(key in parsed)) {
+                return `the ${action} selection omits required field \`${key}\``;
             }
         }
-        else {
-            try {
-                await this.drain();
+        for (const key of Object.keys(parsed)) {
+            if (key !== 'action' &&
+                !required.includes(key) &&
+                !tolerated.includes(key)) {
+                return `the ${action} selection carries undeclared field \`${key}\``;
             }
-            catch (error) {
-                if (cleanupError === undefined)
-                    cleanupError = error;
-            }
-        }
-        this.latchedControlError = undefined;
-        if (finalState && !this.disposalTraceEmitted) {
-            this.disposalTraceEmitted = true;
-            try {
-                await this.trace('session.disposed', omitUndefined({ state: finalState, stateId: finalState.stateId }));
-            }
-            catch (error) {
-                if (cleanupError === undefined)
-                    cleanupError = error;
-            }
-        }
-        try {
-            await this.drain();
         }
-        catch (error) {
-            if (cleanupError === undefined)
-                cleanupError = error;
-        }
-        this.session = undefined;
-        this.actor = undefined;
-        this.nestedBridge = undefined;
-        this.disposed = true;
-        if (cleanupError !== undefined)
-            throw cleanupError;
-    }
-    createActor(session, bridge) {
-        const provided = captainMachine.provide({
-            actors: {
-                captain: fromPromise(async ({ input, signal }) => {
-                    await this.drain();
-                    const combined = combineAbortSignals(signal, this.activeBoundarySignal);
-                    return await this.runCaptainActor(input, combined);
-                }),
-                playbook: bridge.actorLogic,
-            },
-        });
-        let rootActor;
-        rootActor = createActor(provided, {
-            input: {
-                enabledPlaybooks: this.enabledPlaybooks,
-                selfPlaybookId: session.playbookId,
-            },
-            inspect: (inspectionEvent) => {
-                if (this.suppressInspection)
-                    return;
-                if (inspectionEvent.type !== '@xstate.snapshot')
-                    return;
-                if (inspectionEvent.actorRef !== rootActor)
-                    return;
-                try {
-                    this.enqueueTransition(inspectionEvent.event, rootActor);
-                }
-                catch (error) {
-                    this.latchControlError(error);
-                }
-            },
-        });
-        return rootActor;
-    }
-    createBridge(session) {
-        return createNestedPlaybookBridge({
-            nextCallId: () => `call-${this.nextCallId()}`,
-            getBoundarySignal: () => this.activeBoundarySignal,
-            callPlaybook: (request, signal) => session.ports.callPlaybook(request, signal),
-            emitStarted: async (event) => {
-                const turnId = this.currentTraceTurnId();
-                if (turnId !== undefined)
-                    this.playbookCallTurnIds.set(event.callId, turnId);
-                await this.trace('playbook.call.started', {
-                    stateId: event.stateId,
-                    playbookId: event.playbookId,
-                    text: event.text,
-                }, turnId, event.callId);
-            },
-            emitFinished: async (event) => {
-                const turnId = this.playbookCallTurnIds.get(event.callId) ?? this.currentTraceTurnId();
-                await this.trace('playbook.call.finished', {
-                    stateId: event.stateId,
-                    playbookId: event.playbookId,
-                    text: event.text,
-                    result: event.result,
-                }, turnId, event.callId);
-                this.playbookCallTurnIds.delete(event.callId);
-            },
-            drain: () => this.drain(),
-            bindResumeSignal: (signal) => {
-                this.activeBoundarySignal = signal;
-            },
-            onControlPlaneError: (error) => this.latchControlError(error),
-            onBackgroundError: (error) => this.latchControlError(error),
-        });
-    }
-    async runCaptainActor(input, signal) {
-        try {
-            const prompt = composeCaptainPrompt(input);
-            const result = await this.callCaptain(input, prompt, signal);
-            if (signal.aborted)
-                throw signal.reason;
-            if (result.status !== 'ok') {
-                throw new Error(result.error ?? `Captain returned ${result.status}`);
-            }
-            if (!result.finalText) {
-                throw new Error('Captain returned ok without finalText');
-            }
-            const judgePrompt = makeJudgePrompt(input, result.finalText);
-            const judgeText = await this.callJudge('captain-output-adjudication', judgePrompt, signal, input.stateId);
-            try {
-                return adjudicateCaptainOutput(input, result.finalText, judgeText);
+        return undefined;
+    };
+    const nonEmpty = (key) => typeof parsed[key] === 'string' && parsed[key].trim().length > 0
+        ? undefined
+        : `the ${action} selection's \`${key}\` must be a non-empty string`;
+    switch (action) {
+        case 'respond': {
+            const shape = requireKeys(['text']) ?? nonEmpty('text');
+            if (shape !== undefined)
+                return { reason: shape };
+            return { selection: { action, text: parsed.text } };
+        }
+        case 'start':
+        case 'switch': {
+            const shape = requireKeys(['playbookId', 'input']) ??
+                nonEmpty('playbookId') ??
+                nonEmpty('input');
+            if (shape !== undefined)
+                return { reason: shape };
+            const playbookId = parsed.playbookId;
+            if (playbookId === selfPlaybookId) {
+                return {
+                    reason: `the ${action} target may never be this Captain playbook itself`,
+                };
             }
-            catch (rejection) {
-                // One corrective re-ask on a malformed control reply (CAPPLAY-18);
-                // a judge transport failure above never reaches this catch.
-                if (signal.aborted)
-                    throw signal.reason;
-                const retryPrompt = makeJudgeRetryPrompt(judgePrompt, rejection);
-                const retryText = await this.callJudge('captain-output-adjudication', retryPrompt, signal, input.stateId);
-                return adjudicateCaptainOutput(input, result.finalText, retryText);
+            if (!options.enabledPlaybooks.some((entry) => entry.id === playbookId)) {
+                return {
+                    reason: `the ${action} target ${JSON.stringify(playbookId)} is not an enabled catalog id`,
+                };
             }
-        }
-        catch (error) {
-            if (!signal.aborted)
-                this.latchControlError(error);
-            throw error;
-        }
+            return {
+                selection: {
+                    action,
+                    playbookId,
+                    input: parsed.input,
+                },
+            };
+        }
+        case 'dismiss': {
+            const shape = requireKeys([]);
+            if (shape !== undefined)
+                return { reason: shape };
+            return { selection: { action } };
+        }
+        case 'deliver': {
+            // A deliver selection carries no text payload: the host is
+            // authoritative for the delivered text, so a carried `text` is
+            // ignored and never delivered (CAPPLAY-9).
+            const shape = requireKeys([], ['text']);
+            if (shape !== undefined)
+                return { reason: shape };
+            return { selection: { action } };
+        }
+        case 'runtime': {
+            const shape = requireKeys(['actionId']) ?? nonEmpty('actionId');
+            if (shape !== undefined)
+                return { reason: shape };
+            return { selection: { action, actionId: parsed.actionId } };
+        }
+        default:
+            return { reason: `the reply names no known action (${action})` };
     }
-    async callCaptain(input, prompt, signal) {
-        const callId = `captain-${this.nextCallId()}`;
-        const startPayload = {
-            stateId: input.stateId,
-            sourceItem: input.sourceItem,
-            prompt,
-            visibility: 'visible',
-            resume: false,
-            allowedTools: [],
-        };
-        try {
-            await this.trace('captain.call.started', startPayload, this.currentTraceTurnId(), callId);
-        }
-        catch (error) {
-            await this.tracePreservingError('captain.call.finished', {
-                ...startPayload,
-                status: 'error',
-                error: normalizeError(error),
-            }, error, this.currentTraceTurnId(), callId);
-            throw error;
-        }
-        let result;
-        let failure;
-        try {
-            result = await this.captainLane.add(async () => {
-                if (signal.aborted)
-                    throw signal.reason;
-                const raw = await this.requireSession().ports.callCaptain(prompt, signal, CAPTAIN_OPTIONS);
-                if (signal.aborted)
-                    throw signal.reason;
-                return validateCaptainResult(raw);
-            });
-            if (result.status !== 'ok') {
-                failure = new Error(result.error ?? `Captain returned ${result.status}`);
-            }
-            else if (!result.finalText) {
-                failure = new Error('Captain returned ok without finalText');
-            }
-        }
-        catch (error) {
-            failure = error;
-        }
-        const normalized = failure === undefined ? undefined : normalizeError(failure);
-        const abortedFailure = failure !== undefined && isSignalAbort(failure, signal);
-        const finishPayload = {
-            stateId: input.stateId,
-            sourceItem: input.sourceItem,
-            prompt,
-            visibility: 'visible',
-            resume: false,
-            allowedTools: [],
-            status: result?.status ?? (abortedFailure ? 'aborted' : 'error'),
-            ...(result?.finalText === undefined ? {} : { finalText: result.finalText }),
-            ...(result?.error === undefined ? {} : { error: result.error }),
-            ...(normalized === undefined ? {} : { error: normalized }),
+}
+function selectionFromParsedDecision(decision) {
+    if (decision.action === 'deliver') {
+        return { action: 'deliver' };
+    }
+    // A parse-resolved `start` / `switch` is always the exact command remainder
+    // supplied by the host (CAPTAIN-7 command table).
+    return {
+        action: decision.action,
+        playbookId: decision.playbookId,
+        input: decision.input,
+    };
+}
+/** The machine retains the selected standalone input and settlement evidence. */
+function decisionOutputOf(selection) {
+    if (selection.action === 'start' || selection.action === 'switch') {
+        return {
+            guard: selection.action,
+            playbookId: selection.playbookId,
+            input: selection.input,
         };
-        if (failure !== undefined) {
-            if (isSignalAbort(failure, signal)) {
-                await this.trace('captain.call.finished', finishPayload, this.currentTraceTurnId(), callId);
-                throw failure;
-            }
-            await this.tracePreservingError('captain.call.finished', finishPayload, failure, this.currentTraceTurnId(), callId);
-            throw failure;
-        }
-        await this.trace('captain.call.finished', finishPayload, this.currentTraceTurnId(), callId);
-        if (failure !== undefined)
-            throw failure;
-        if (!result)
-            throw new Error('Captain returned no result');
-        return result;
     }
-    async callJudge(purpose, prompt, signal, stateId) {
-        const callId = `judge-${this.nextCallId()}`;
-        const startPayload = omitUndefined({ purpose, prompt, stateId });
-        try {
-            await this.trace('judge.call.started', startPayload, this.currentTraceTurnId(), callId);
-        }
-        catch (error) {
-            await this.tracePreservingError('judge.call.finished', omitUndefined({ purpose, prompt, stateId, status: 'error', error: normalizeError(error) }), error, this.currentTraceTurnId(), callId);
-            throw error;
-        }
-        let reply;
-        let failure;
-        try {
-            reply = await this.captainLane.add(async () => {
-                if (signal.aborted)
-                    throw signal.reason;
-                const text = await this.requireSession().ports.callJudge(prompt, signal);
-                if (signal.aborted)
-                    throw signal.reason;
-                if (typeof text !== 'string')
-                    throw new TypeError('judge reply must be a string');
-                return text;
-            });
+    return { ...selection, guard: selection.action };
+}
+// ---------------------------------------------------------------------------
+// Settlement validation: the returned settlement is the only evidence of
+// effects, and the machine retains only its status, facts, receipt
+// disposition, and leaf-state summary (CAPPLAY-10). A malformed settlement
+// is a host control-plane failure.
+// ---------------------------------------------------------------------------
+function validateSettlement(value) {
+    if (!isRecord(value)) {
+        throw new TypeError('controller settlement must be an object');
+    }
+    const allowed = new Set([
+        'status',
+        'facts',
+        'reason',
+        'receipt',
+        'leafStateSummary',
+    ]);
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key)) {
+            throw new TypeError(`controller settlement carries undeclared ${key}`);
+        }
+    }
+    if (value.status !== 'ok' &&
+        value.status !== 'rejected' &&
+        value.status !== 'failed') {
+        throw new TypeError(`controller settlement status must be ok | rejected | failed (got ${String(value.status)})`);
+    }
+    if (!Array.isArray(value.facts) ||
+        value.facts.some((fact) => typeof fact !== 'string')) {
+        throw new TypeError('controller settlement facts must be a string array');
+    }
+    if ('reason' in value && typeof value.reason !== 'string') {
+        throw new TypeError('controller settlement reason must be a string');
+    }
+    if ('leafStateSummary' in value &&
+        typeof value.leafStateSummary !== 'string') {
+        throw new TypeError('controller settlement leafStateSummary must be a string');
+    }
+    let receipt;
+    if ('receipt' in value) {
+        if (!isRecord(value.receipt)) {
+            throw new TypeError('controller settlement receipt must be an object');
+        }
+        const receiptAllowed = new Set(['disposition', 'reason', 'error']);
+        for (const key of Object.keys(value.receipt)) {
+            if (!receiptAllowed.has(key)) {
+                throw new TypeError(`controller settlement receipt carries undeclared ${key}`);
+            }
         }
-        catch (error) {
-            failure = error;
+        const disposition = value.receipt.disposition;
+        if (disposition !== 'executed' &&
+            disposition !== 'rejected' &&
+            disposition !== 'failed') {
+            throw new TypeError('controller settlement receipt disposition must be executed | rejected | failed');
         }
-        if (failure !== undefined) {
-            const aborted = isSignalAbort(failure, signal);
-            const finishPayload = omitUndefined({
-                purpose,
-                prompt,
-                stateId,
-                status: aborted ? 'aborted' : 'error',
-                error: normalizeError(failure),
-            });
-            if (aborted) {
-                await this.trace('judge.call.finished', finishPayload, this.currentTraceTurnId(), callId);
-            }
-            else {
-                await this.tracePreservingError('judge.call.finished', finishPayload, failure, this.currentTraceTurnId(), callId);
-            }
-            throw failure;
+        if ('reason' in value.receipt && typeof value.receipt.reason !== 'string') {
+            throw new TypeError('controller settlement receipt reason must be a string');
         }
-        await this.trace('judge.call.finished', omitUndefined({ purpose, prompt, stateId, status: 'ok', reply }), this.currentTraceTurnId(), callId);
-        if (reply === undefined)
-            throw new Error('judge returned no reply');
-        return reply;
-    }
-    async classifyBossInput(text, state, signal) {
-        const pending = this.pendingQuestion();
-        const prompt = classifierPrompt(text, state, pending ? { questionId: pending.questionId, player: pending.player, question: pending.question } : undefined);
-        const reply = await this.callJudge('boss-input-classification', prompt, signal, state.stateId);
-        const event = validateClassifier(reply, text, pending?.questionId);
-        if (!event)
-            return undefined;
-        return event;
-    }
-    pendingQuestion() {
-        const snapshot = this.actor?.getSnapshot();
-        const context = snapshot?.context;
-        if (!isRecord(context) || !isRecord(context.pendingBossQuestion))
-            return undefined;
-        return {
-            questionId: assertNonEmptyString(context.pendingBossQuestion.questionId, 'pending question id'),
-            player: assertNonEmptyString(context.pendingBossQuestion.player, 'pending question player'),
-            question: assertNonEmptyString(context.pendingBossQuestion.question, 'pending question text'),
-        };
-    }
-    enqueueTransition(event, actor) {
-        const state = stateFromSnapshot(actor, this.nestedBridge?.getPendingCall());
-        const previousState = this.previousState ?? state;
-        this.previousState = state;
-        const transition = omitUndefined({
-            event: this.describeEvent(event),
-            from: previousState,
-            to: state,
-            previousState,
-            state,
-            stateId: state.stateId,
-            pendingBossQuestion: this.pendingQuestion(),
-            lastError: this.lastError(),
-        });
-        this.enqueue(async () => {
-            await this.traceNow('fsm.transition', transition, this.currentTraceTurnId());
-            await this.requireSession().ports.emitTelemetry({ topic: 'playbook.fsm.state', payload: transition });
-            if (state.stateId !== 'ready' && state.stateId !== 'done') {
-                await this.traceNow('status.emitted', omitUndefined({ message: `Entered ${state.stateId ?? 'state'}`, state, stateId: state.stateId }), this.currentTraceTurnId());
-                await this.requireSession().ports.emitStatus(`Entered ${state.stateId ?? 'state'}`, transition);
+        let error;
+        if ('error' in value.receipt) {
+            const compact = normalizeErrorCompact(value.receipt.error);
+            if (compact === undefined) {
+                throw new TypeError('controller settlement receipt error must be a normalized error');
             }
+            error = compact;
+        }
+        receipt = Object.freeze({
+            disposition,
+            ...(typeof value.receipt.reason === 'string'
+                ? { reason: value.receipt.reason }
+                : {}),
+            ...(error === undefined ? {} : { error: Object.freeze(error) }),
         });
     }
-    describeEvent(event) {
-        if (!isRecord(event))
-            return { type: 'unknown' };
-        const type = typeof event.type === 'string' ? event.type : 'unknown';
-        const copy = { type };
-        for (const key of ['bossIntent', 'targetId', 'answer', 'questionId', 'output']) {
-            if (key in event && event[key] === undefined)
-                continue;
-            if (key in event)
-                copy[key] = snapshotJsonValue(event[key], `event.${key}`);
-        }
-        if ('error' in event)
-            copy.error = snapshotJsonValue(normalizeError(event.error));
-        return snapshotJsonValue(copy);
-    }
-    lastError() {
-        const context = this.actor?.getSnapshot().context;
-        if (!isRecord(context) || !('lastError' in context))
-            return undefined;
-        if (context.lastError === undefined)
-            return undefined;
-        return snapshotJsonValue(context.lastError, 'lastError');
-    }
-    machineOutput() {
-        const snapshot = this.actor?.getSnapshot();
-        if (!snapshot || snapshot.status !== 'done')
-            return undefined;
-        const output = snapshot.output;
-        return output === undefined ? undefined : snapshotJsonValue(output, 'machine output');
-    }
-    async emitStatus(message, data) {
-        const state = stateFromSnapshot(this.requireActor(), this.nestedBridge?.getPendingCall());
-        const payload = omitUndefined({ message, data, state, stateId: state.stateId });
-        await this.trace('status.emitted', payload, this.currentTraceTurnId());
-        await this.requireSession().ports.emitStatus(message, data);
-    }
-    async traceSettled(result, turnId) {
-        await this.trace('boss.input.settled', this.runResultPayload(result), turnId);
-    }
-    runResultPayload(result) {
-        return omitUndefined({
-            outcome: result.outcome,
-            state: result.state,
-            stateId: result.state.stateId,
-            pendingCall: 'pendingCall' in result ? result.pendingCall : undefined,
-            output: 'output' in result ? result.output : undefined,
-            error: 'error' in result ? result.error : undefined,
-        });
+    return Object.freeze({
+        status: value.status,
+        facts: Object.freeze([...value.facts]),
+        ...(typeof value.reason === 'string' ? { reason: value.reason } : {}),
+        ...(receipt === undefined ? {} : { receipt }),
+        ...(typeof value.leafStateSummary === 'string'
+            ? { leafStateSummary: value.leafStateSummary }
+            : {}),
+    });
+}
+// ---------------------------------------------------------------------------
+// The controller captain-call strategy (slc/link.md §Captain adjudication,
+// controller form). The engine composes the prompt, traces every call as its
+// own captain.call pair on the shared serialized lane, and owns
+// control-plane latching; this strategy owns the hidden calls, the decision
+// validation with its one corrective re-ask, and the controller-port
+// submission.
+// ---------------------------------------------------------------------------
+const HIDDEN = { visibility: 'hidden' };
+async function callHidden(run, prompt) {
+    try {
+        return await run.callCaptain(prompt, HIDDEN);
+    }
+    catch (error) {
+        // DR-028: exactly one corrective re-ask of the same composed call on an
+        // empty `ok` result; a second such result follows the failure path from
+        // the boundary itself.
+        if (!run.isEmptyOkRetry(error))
+            throw error;
+        return await run.callCaptain(prompt, HIDDEN);
     }
-    async trace(type, payload, turnId, callId) {
-        this.enqueue(async () => {
-            await this.traceNow(type, payload, turnId, callId);
-        });
-        await this.drain();
+}
+function requireControllerPort(options) {
+    if (options.controller === undefined) {
+        throw new Error('captain.playbook: the host-supplied controller port is required to settle a Boss turn (CAPPLAY-9); construct the runtime with options.controller');
     }
-    async tracePreservingError(type, payload, preservedError, turnId, callId) {
-        const previous = this.latchedControlError;
-        this.latchedControlError = undefined;
-        try {
-            await this.trace(type, payload, turnId, callId);
-        }
-        catch (error) {
-            // Preserve the earlier boundary/control failure.
-        }
-        finally {
-            this.latchedControlError = previous ?? preservedError;
+    return options.controller;
+}
+async function submitSelection(run, selection) {
+    const port = requireControllerPort(run.options);
+    const settlement = validateSettlement(await port.submit(selection, run.signal));
+    run.signal.throwIfAborted();
+    return settlement;
+}
+async function runDecisionState(run) {
+    const input = run.input;
+    const declaredActions = new Set(Object.keys(run.input.result));
+    let selection;
+    if (input.parsedDecision !== undefined) {
+        // A parse-resolved turn enters with its decision already made: the
+        // injected decision object is the turn's decision and no decision call
+        // occurs (CAPTAIN-7, CAPPLAY-6). A malformed injection is a host bug —
+        // control-plane, not a corrective re-ask.
+        selection = selectionFromParsedDecision(validateParsedActingDecision(input.parsedDecision));
+    }
+    else {
+        const first = await callHidden(run, run.prompt);
+        const firstReading = readDecisionReply(first.finalText ?? '', run.options, run.session.playbookId, declaredActions);
+        if (firstReading.selection !== undefined) {
+            selection = firstReading.selection;
         }
-    }
-    async traceNow(type, payload, turnId, callId) {
-        const session = this.requireSession();
-        const event = {
-            schemaVersion: 2,
-            sessionId: session.sessionId,
-            playbookId: session.playbookId,
-            rootSessionId: session.rootSessionId,
-            ...(session.parentSessionId === undefined ? {} : { parentSessionId: session.parentSessionId }),
-            ...(session.parentCallId === undefined ? {} : { parentCallId: session.parentCallId }),
-            depth: session.depth,
-            sequence: this.nextSequence(),
-            timestamp: Date.now(),
-            type,
-            ...(turnId === undefined ? {} : { turnId }),
-            ...(callId === undefined ? {} : { callId }),
-            payload: snapshotJsonValue(payload, `trace ${type}`),
-        };
-        await session.ports.emitTelemetry({ topic: 'playbook.trace', payload: event });
-    }
-    enqueue(task) {
-        void this.emissionQueue.add(async () => {
-            try {
-                await task();
-            }
-            catch (error) {
-                this.latchControlError(error);
-                throw error;
+        else {
+            // CAPPLAY-18: exactly one corrective call appending the rejection
+            // reason and the restated reply contract to the same prompt.
+            const second = await callHidden(run, correctiveDecisionPrompt(run.prompt, firstReading.reason));
+            const secondReading = readDecisionReply(second.finalText ?? '', run.options, run.session.playbookId, declaredActions);
+            if (secondReading.selection === undefined) {
+                // A second malformed reply settles the turn as a Boss-appropriate
+                // failure reply with no action executed and the engagement stack
+                // untouched; the machine returns to its hub (CAPPLAY-18/19). The
+                // marker property routes the FSM's authored hub-recovery arm.
+                const failure = new Error(`the decision reply stayed malformed after one corrective re-ask: ${secondReading.reason}`);
+                failure.name = 'ControllerDecisionError';
+                failure.controllerDecisionFailure = true;
+                throw run.recoverableFailure(failure);
             }
-        }).catch(() => undefined);
-    }
-    drain() {
-        return this.emissionQueue.onIdle().then(() => {
-            if (this.latchedControlError)
-                throw this.latchedControlError;
-        });
-    }
-    async bestEffortDisposeTrace(state) {
-        try {
-            this.disposalTraceEmitted = true;
-            await this.trace('session.disposed', omitUndefined({ state, stateId: state.stateId }));
-            await this.drain();
-        }
-        catch {
-            // Preserve the original initialization error.
+            selection = secondReading.selection;
         }
     }
-    reconstructActor() {
-        this.actor?.stop();
-        const session = this.requireSession();
-        const bridge = this.requireBridge();
-        this.actor = this.createActor(session, bridge);
-        this.actor.start();
-    }
-    requireSession() {
-        if (!this.session)
-            throw new Error('playbook runtime is not initialized');
-        return this.session;
-    }
-    requireActor() {
-        if (!this.actor)
-            throw new Error('playbook runtime actor is not initialized');
-        return this.actor;
-    }
-    requireBridge() {
-        if (!this.nestedBridge)
-            throw new Error('nested bridge is not initialized');
-        return this.nestedBridge;
-    }
-    nextSequence() {
-        this.sequence += 1;
-        return this.sequence;
-    }
-    nextTurnId() {
-        this.turnId += 1;
-        return this.turnId;
-    }
-    currentTraceTurnId() {
-        return this.boundaryTurnId;
-    }
-    nextCallId() {
-        this.callId += 1;
-        return this.callId;
-    }
-    latchControlError(error) {
-        if (!this.latchedControlError)
-            this.latchedControlError = error;
+    const settlement = await submitSelection(run, selection);
+    return {
+        ...decisionOutputOf(selection),
+        settlement,
+    };
+}
+async function controllerCaptainStrategy(run) {
+    if (run.input.stateId === 'deciding') {
+        return (await runDecisionState(run));
+    }
+    // The prose states (answeringCommand, reporting): one hidden durable call
+    // whose validated text the host surfaces as captain speech through its
+    // presentation seam; the machine retains no reply prose (CAPPLAY-10) and
+    // the state settles with the default single-outcome `done` contract.
+    await callHidden(run, run.prompt);
+    return { guard: 'done' };
+}
+// ---------------------------------------------------------------------------
+// Captain-pane status lines. The shell suppresses this runtime's human
+// status stream while forwarding structured telemetry (CAPPLAY-9); the
+// lines stay Boss-appropriate regardless. The parked hub and the shutdown
+// state emit no human status (slc/link.md §Session lifecycle).
+// ---------------------------------------------------------------------------
+function statusesForState(state, context) {
+    switch (state.stateId) {
+        case 'deciding':
+            return [{ message: '⤷ Captain: decide the Boss turn' }];
+        case 'answeringCommand':
+            return [{ message: '⤷ Captain: answer the command turn' }];
+        case 'reporting':
+            return [{ message: '⤷ Captain: compose the closing reply' }];
+        case 'failed': {
+            const lastError = normalizeErrorCompact(context.lastError);
+            return [
+                {
+                    message: '◆ failed',
+                    ...(lastError === undefined
+                        ? {}
+                        : { data: snapshotJsonValue({ lastError }, 'failed status data') }),
+                },
+            ];
+        }
+        default:
+            return [];
     }
 }
+// Internal export surface for verification and tests. Not part of the
+// stable public API; the leading underscore signals "subject to change."
 export const _internal = {
-    composeCaptainPrompt,
-    composePlayerPrompt,
-    parseJsonObjectLoose,
+    // No placeholder exists in any compiled Captain prompt: the labeled
+    // Boss-message, ControlView digest, and catalog digest blocks are
+    // shell-composed inside the hidden-control envelope (CAPTAIN-9), so the
+    // shared default composer emits the verbatim GEARS domain body.
+    composeCaptainPrompt: (input) => defaultComposeCaptainPrompt(input),
+    classifyControllerTurn,
+    readDecisionReply,
+    correctiveDecisionPrompt,
+    validateSettlement,
+    validateParsedActingDecision,
+    statusesForState,
+    normalizeError,
+};
+// The Captain-specific spec handed to the shared runtime factory
+// (slc/link.md §Output, DR-019). Generic machinery — actor wiring, boundary
+// tracing, lifecycle, abort, the parked-session snapshot, and the DR-029
+// describe/apply control surface — lives in @sublang/playbook/xstate-runtime.
+const runtimeSpec = {
+    label: 'CAPTAIN',
+    compat: { artifactSchema: 1, runtimeAbi: RUNTIME_ABI },
+    snapshotOptions: snapshotCaptainOptions,
+    machineInput: (options) => ({ enabledPlaybooks: options.enabledPlaybooks }),
+    classifyBossText: (text, ports, signal, snapshotOrState, boundary, options) => classifyControllerTurn(text, ports, signal, snapshotOrState, boundary, options),
+    playerStates: {},
+    classificationStatus: () => undefined,
+    captainStrategy: controllerCaptainStrategy,
+    // CAPPLAY-10 / PBRT-52: the Captain's own ControlView context projection —
+    // the settlement evidence the machine retains for its decision and reply
+    // phases, and nothing else. `enabledPlaybooks` is the host-supplied
+    // catalog (an option value), and `parsedDecision` and `lastError` are
+    // control-plane scratch; none of the three is settlement evidence, so none
+    // is exported. Declaring the list here is what makes "Captain-visible
+    // context" an enumerated set rather than whatever the FSM happens to hold.
+    controlContextFields: [
+        'bossText',
+        'selectedAction',
+        'settlementStatus',
+        'settlementFacts',
+        'settlementReason',
+        'receiptDisposition',
+        'receiptReason',
+        'receiptError',
+        'leafStateSummary',
+    ],
+    statusesForState,
 };
+const createCaptainPlaybookRuntime = createXStatePlaybookRuntime(captainMachine, runtimeSpec);
 export function createPlaybookRuntime(options) {
-    return new CaptainPlaybookRuntime(options);
+    return createCaptainPlaybookRuntime(options);
 }
 const factory = createPlaybookRuntime;
 export default factory;