ai-foreman 1.7.28 → 2.0.0

package/dist/structuredCutoverFiles.js

@@ -0,0 +1,181 @@
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { invalidStructuredRun, STRUCTURED_CUTOVER_REASON } from "./structuredCutover.js";
+/** Only these declared local projections can carry resumable communication state. */
+export const COMMUNICATION_FILE_OWNERSHIP = Object.freeze([
+    { directory: ".rafi/interviews", kind: "interview", recurse: false },
+    { directory: ".foreman/runs", kind: "build-checkpoint", recurse: false },
+    { directory: ".foreman/delivery-sessions", kind: "branch-session", recurse: false },
+    { directory: ".tickets/delivery-sessions", kind: "branch-session", recurse: false },
+    { directory: ".foreman/qa-report-recovery", kind: "qa-recovery", recurse: true },
+]);
+/** Unknown/oversized file state conservatively retains evidence until classified. */
+export function communicationFileEvidenceReferences(root) {
+    const references = new Set();
+    const walk = (path) => {
+        if (!existsSync(path))
+            return;
+        const stat = lstatSync(path);
+        if (stat.isSymbolicLink()) {
+            references.add("*");
+            return;
+        }
+        if (stat.isDirectory()) {
+            for (const name of readdirSync(path))
+                walk(join(path, name));
+            return;
+        }
+        if (!stat.isFile() || stat.size > 8 * 1024 * 1024) {
+            references.add("*");
+            return;
+        }
+        for (const match of readFileSync(path, "utf8").matchAll(/\b[a-f0-9]{64}\b/g))
+            references.add(match[0]);
+    };
+    for (const owner of COMMUNICATION_FILE_OWNERSHIP)
+        walk(join(root, owner.directory));
+    walk(join(root, ".rafi", "communication-quarantine"));
+    return references;
+}
+export function quarantineCommunicationFiles(root, db) {
+    const archive = join(root, ".rafi", "communication-quarantine");
+    const sync = (path) => { const fd = openSync(path, "r"); try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    } };
+    for (const owner of COMMUNICATION_FILE_OWNERSHIP) {
+        if (owner.kind === "qa-recovery") {
+            const directory = join(root, owner.directory);
+            if (existsSync(directory) && lstatSync(directory).isSymbolicLink())
+                throw new Error("QA recovery storage symlink is not allowed during cutover");
+            if (existsSync(directory))
+                for (const name of readdirSync(directory)) {
+                    const packet = join(directory, name);
+                    if (lstatSync(packet).isSymbolicLink())
+                        throw new Error("Cutover cannot classify symlinked QA recovery state");
+                    if (lstatSync(packet).isDirectory()) {
+                        const manifestPath = join(packet, "manifest.json");
+                        if (existsSync(manifestPath)) {
+                            if (lstatSync(manifestPath).isSymbolicLink())
+                                throw new Error("QA recovery manifest symlink is not allowed during cutover");
+                            let manifest = {};
+                            try {
+                                manifest = JSON.parse(readFileSync(manifestPath, "utf8")) ?? {};
+                            }
+                            catch { /* Incompatible packet remains preserved behind the sentinel. */ }
+                            if (manifest.version === 2 && typeof manifest.runId === "string" && typeof manifest.packetDigest === "string"
+                                && db.prepare(`SELECT 1 FROM workflow_runs r JOIN qa_packet_projections p ON p.run_id=r.run_id
+                WHERE r.run_id=? AND r.checkpoint<>? AND p.packet_digest=? AND p.ticket_id=?
+                AND CASE WHEN json_valid(p.manifest_json) THEN json_extract(p.manifest_json,'$.revision') ELSE NULL END=? AND p.path=?`)
+                                    .get(manifest.runId, STRUCTURED_CUTOVER_REASON, manifest.packetDigest, manifest.ticketId, manifest.revision, packet))
+                                continue;
+                        }
+                        const marker = join(packet, ".structured-communication-v2-cutover");
+                        if (existsSync(marker) && lstatSync(marker).isSymbolicLink())
+                            throw new Error("Unsafe QA cutover marker");
+                        if (!existsSync(marker))
+                            writeFileSync(marker, STRUCTURED_CUTOVER_REASON, { mode: 0o600, flag: "wx" });
+                        sync(marker);
+                        sync(packet);
+                    }
+                }
+            continue;
+        }
+        const walk = (directory) => {
+            if (!existsSync(directory))
+                return;
+            if (lstatSync(directory).isSymbolicLink())
+                throw new Error(`Cutover cannot classify symlinked communication storage: ${directory}`);
+            for (const name of readdirSync(directory)) {
+                const path = join(directory, name), stat = lstatSync(path);
+                if (stat.isSymbolicLink())
+                    throw new Error(`Cutover cannot classify a symlinked communication projection: ${path}`);
+                if (stat.isDirectory()) {
+                    if (owner.recurse)
+                        walk(path);
+                    continue;
+                }
+                if (!name.endsWith(".json") || !stat.isFile())
+                    continue;
+                const bytes = readFileSync(path);
+                let value;
+                try {
+                    value = JSON.parse(bytes.toString());
+                }
+                catch {
+                    value = {};
+                }
+                if (!value || typeof value !== "object" || Array.isArray(value))
+                    value = {};
+                if (value.structuredCommunicationCutover?.reason === STRUCTURED_CUTOVER_REASON)
+                    continue;
+                if (owner.kind === "interview" && value.communicationProtocolVersion === 2 && value.version === 2
+                    && typeof value.id === "string" && typeof value.workflow === "string" && typeof value.checkpoint === "string"
+                    && value.answers && typeof value.answers === "object" && value.runtime && typeof value.runtime === "object"
+                    && !value.runtime.sessionId && value.sessionIds && Object.keys(value.sessionIds).length === 0
+                    && Array.isArray(value.outputs) && value.outputs.every(output => output && typeof output.path === "string" && (output.sha256 === null || /^[a-f0-9]{64}$/.test(output.sha256))))
+                    continue; // Human answers, file observations and host-only preparation.
+                if (value.communicationProtocolVersion === 2 && typeof value.runId === "string" && Object.keys(value).every(key => ["communicationProtocolVersion", "runId", "dispatchId"].includes(key))) {
+                    const run = db.prepare("SELECT checkpoint FROM workflow_runs WHERE run_id=?").get(value.runId);
+                    if (run && run.checkpoint !== STRUCTURED_CUTOVER_REASON && typeof value.dispatchId === "string" && db.prepare("SELECT 1 FROM operation_journal WHERE run_id=? AND idempotency_key=? AND status='confirmed'").get(value.runId, value.dispatchId))
+                        continue;
+                }
+                if (owner.kind === "interview" && value.communicationProtocolVersion === 2 && value.version === 2 && value.workflow === "tickets-plan") {
+                    const reference = value.decisions?.nativeDispatch;
+                    try {
+                        const run = reference && db.prepare("SELECT * FROM workflow_runs WHERE run_id=?").get(reference.runId);
+                        const operation = reference && db.prepare("SELECT intent_json FROM operation_journal WHERE run_id=? AND idempotency_key=? AND status='confirmed'").get(reference.runId, reference.dispatchId);
+                        const tuple = operation && JSON.parse(operation.intent_json).tuple;
+                        if (reference?.version === 2 && Object.keys(reference).length === 4 && reference.runId === `ticket-plan:${value.id}` &&
+                            tuple?.operation === "ticket-plan" && tuple.digest === reference.tupleDigest && tuple.sessionId === value.runtime?.sessionId &&
+                            !value.decisions.structuredResponse && !value.decisions.proposalResponse && run && !invalidStructuredRun(db, run, root))
+                            continue;
+                    }
+                    catch { /* Unverifiable native references remain incompatible. */ }
+                }
+                if (owner.kind === "build-checkpoint") {
+                    const run = db.prepare("SELECT checkpoint FROM workflow_runs WHERE run_id=?").get(value.runId);
+                    if (run && run.checkpoint !== STRUCTURED_CUTOVER_REASON && !value.builder && !value.qa && !value.receipts && !value.sessionBindings)
+                        continue;
+                }
+                mkdirSync(archive, { recursive: true, mode: 0o700 });
+                if (lstatSync(archive).isSymbolicLink())
+                    throw new Error("Unsafe communication quarantine storage");
+                const digest = createHash("sha256").update(bytes).digest("hex");
+                const archived = join(archive, `${digest}.json`);
+                if (!existsSync(archived))
+                    writeFileSync(archived, bytes, { mode: 0o600, flag: "wx" });
+                if (lstatSync(archived).isSymbolicLink() || createHash("sha256").update(readFileSync(archived)).digest("hex") !== digest)
+                    throw new Error("Communication quarantine integrity failure");
+                sync(archived);
+                sync(archive);
+                const next = { ...value, status: owner.kind === "interview" ? "incompatible" : "superseded",
+                    checkpoint: STRUCTURED_CUTOVER_REASON, runtime: {}, sessionIds: {}, continuityLost: true,
+                    structuredCommunicationCutover: { version: 2, reason: STRUCTURED_CUTOVER_REASON, archiveDigest: digest, kind: owner.kind } };
+                // The archive and stage survive SQLite rollback. A restart can classify
+                // either original or incompatible bytes without losing the input or
+                // treating a partial filesystem rewrite as completed DB repair.
+                const replacement = `${JSON.stringify(next, null, 2)}\n`;
+                const stageDigest = createHash("sha256").update(path).update(digest).digest("hex");
+                const stage = join(archive, `${stageDigest}.stage.json`);
+                const stagedBytes = JSON.stringify({ version: 1, path, originalDigest: digest,
+                    replacementDigest: createHash("sha256").update(replacement).digest("hex"), replacement });
+                if (!existsSync(stage))
+                    writeFileSync(stage, stagedBytes, { mode: 0o600, flag: "wx" });
+                if (lstatSync(stage).isSymbolicLink() || readFileSync(stage, "utf8") !== stagedBytes)
+                    throw new Error("Communication quarantine stage integrity failure");
+                sync(stage);
+                sync(archive);
+                const temporary = `${path}.${randomUUID()}.cutover.tmp`;
+                writeFileSync(temporary, replacement, { mode: 0o600, flag: "wx" });
+                sync(temporary);
+                renameSync(temporary, path);
+                sync(directory);
+            }
+        };
+        walk(join(root, owner.directory));
+    }
+}

package/dist/structuredDispatchAuthority.d.ts

@@ -0,0 +1,22 @@
+import { type OutputContract, type ProviderSessionRefV1, type SelectedDispatchTupleV2 } from "rafi-spec";
+import type { TurnResult } from "./adapters/types.js";
+declare const authorityBrand: unique symbol;
+/** An in-process capability; JSON or a caller-created owner label cannot mint it. */
+export interface StructuredDispatchCapability {
+    readonly [authorityBrand]: true;
+}
+/** Only the host's explicit, durable fresh-recovery decision grants this scope. */
+export declare function withFreshRecoveryValidation<T>(root: string, runId: string, role: "builder" | "qa", send: (authorization: import("./workflowDb.js").FreshRecoveryValidation) => Promise<T>): Promise<T>;
+export declare function currentFreshRecoveryValidation(root: string, runId: string): import("./workflowDb.js").FreshRecoveryValidation | undefined;
+export declare function withSealedDispatch<T>(root: string, tuple: SelectedDispatchTupleV2, send: (capability: StructuredDispatchCapability) => Promise<T>, session?: ProviderSessionRefV1): Promise<T>;
+/** Provider initialization is discarded and cannot use an authoritative operation contract. */
+export declare function withEphemeralInitializationDispatch<T>(root: string, tuple: SelectedDispatchTupleV2, send: (capability: StructuredDispatchCapability) => Promise<T>, session: ProviderSessionRefV1): Promise<T>;
+export declare function assertSealedDispatch(root: string, capability: StructuredDispatchCapability, tuple: SelectedDispatchTupleV2 | undefined, instruction?: string): void;
+export declare function assertActiveProviderDispatch(policy: import("./adapters/types.js").TurnRequest, instruction: string, provider?: "claude" | "codex", session?: ProviderSessionRefV1): asserts policy is import("./adapters/types.js").SealedTurnPolicy;
+/** Domain callbacks create their durable turn before entering the sealing gateway. */
+export declare function durableOwnerDispatch<T extends (...args: any[]) => Promise<TurnResult>>(root: string, output: OutputContract, owner: {
+    runId: string;
+    actionId: string;
+}, dispatch: T): T;
+export declare function isDurableOwnerDispatch(dispatch: Function): boolean;
+export {};

package/dist/structuredDispatchAuthority.js

@@ -0,0 +1,110 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { structuredDigest, initializationOutput, historicProviderWireContract } from "rafi-spec";
+const capabilities = new WeakMap();
+const active = new AsyncLocalStorage();
+const freshRecovery = new AsyncLocalStorage();
+/** Only the host's explicit, durable fresh-recovery decision grants this scope. */
+export async function withFreshRecoveryValidation(root, runId, role, send) {
+    const { WorkflowDb } = await import("./workflowDb.js");
+    const db = new WorkflowDb(root);
+    let authorization;
+    try {
+        authorization = db.freshRecoveryValidation(runId, role);
+    }
+    finally {
+        db.close();
+    }
+    return freshRecovery.run({ root, runId, authorization }, () => send(authorization));
+}
+export function currentFreshRecoveryValidation(root, runId) {
+    const scope = freshRecovery.getStore();
+    return scope?.root === root && scope.runId === runId ? scope.authorization : undefined;
+}
+function withCapability(root, tuple, send, session, consume) {
+    const capability = Object.freeze({});
+    capabilities.set(capability, { root, tuple, submitted: false, consume, session: session && Object.freeze({ ...session }) });
+    return active.run(capability, () => send(capability));
+}
+export async function withSealedDispatch(root, tuple, send, session) {
+    const { WorkflowDb } = await import("./workflowDb.js");
+    const db = new WorkflowDb(root);
+    try {
+        const claimId = db.claimStructuredSubmission(tuple, session);
+        return await withCapability(root, tuple, send, session, () => db.consumeStructuredSubmission(tuple, claimId, session));
+    }
+    finally {
+        db.close();
+    }
+}
+/** Provider initialization is discarded and cannot use an authoritative operation contract. */
+export function withEphemeralInitializationDispatch(root, tuple, send, session) {
+    historicProviderWireContract(initializationOutput, tuple);
+    if (tuple.operation !== initializationOutput.operation || tuple.sessionId !== session.sessionId || tuple.generation !== session.generation)
+        throw new Error("Ephemeral initialization cannot authorize workflow content");
+    return withCapability(root, tuple, send, session);
+}
+export function assertSealedDispatch(root, capability, tuple, instruction) {
+    const sealed = capabilities.get(capability);
+    if (active.getStore() !== capability || !sealed || sealed.root !== root || sealed.tuple !== tuple ||
+        instruction !== undefined && structuredDigest(instruction) !== sealed.tuple.instructionDigest)
+        throw new Error("Structured dispatch requires the active committed sealing capability");
+}
+export function assertActiveProviderDispatch(policy, instruction, provider, session) {
+    if (!policy.output)
+        throw new Error("Sealed provider policy requires an output contract");
+    const capability = policy.dispatchCapability;
+    const sealed = capability && capabilities.get(capability);
+    if (!capability || !sealed)
+        throw new Error("Structured provider send requires a committed sealing capability");
+    assertSealedDispatch(sealed.root, capability, policy.selectedDispatch, instruction);
+    if (policy.output.operation !== sealed.tuple.operation || policy.output.schemaDigest !== sealed.tuple.schemaDigest || policy.output.schemaVersion !== sealed.tuple.schemaVersion)
+        throw new Error("Structured output contract differs from its sealed owner tuple");
+    if (provider && sealed.tuple.provider !== provider)
+        throw new Error("Sealed dispatch belongs to another provider");
+    if (sealed.session && (!session || ["provider", "sessionId", "role", "stream", "generation", "cwd", "configRoot", "workspaceIdentity", "ticketId", "deliveryUnitId"]
+        .some(field => session[field] !== sealed.session[field])))
+        throw new Error("Provider session scope changed after dispatch sealing");
+    if (!policy.wireContract || policy.renderedWireContractDigest !== policy.wireContract.descriptorDigest ||
+        policy.wireContract.descriptorDigest !== sealed.tuple.descriptorDigest || policy.dispatchId !== sealed.tuple.dispatchId)
+        throw new Error("Structured provider policy differs from its sealed descriptor");
+    if (sealed.submitted)
+        throw new Error("Sealed structured dispatch was already submitted; reconcile before a new dispatch");
+    sealed.consume?.();
+    sealed.submitted = true;
+}
+const ownerDispatches = new WeakSet();
+/** Domain callbacks create their durable turn before entering the sealing gateway. */
+export function durableOwnerDispatch(root, output, owner, dispatch) {
+    const owned = async (...args) => {
+        const { WorkflowDb } = await import("./workflowDb.js");
+        const preparation = new WorkflowDb(root);
+        try {
+            const record = output.operation === "qa-verdict" ? preparation.qaReviewAttempt(owner.actionId)
+                : output.operation === "builder-remediation" ? preparation.qaRemediationAttempt(owner.actionId) : undefined;
+            if (!record || record.runId !== owner.runId || record.status !== "started")
+                throw new Error("Domain dispatch requires its active persisted owner attempt");
+        }
+        finally {
+            preparation.close();
+        }
+        const result = await dispatch(...args);
+        if (!result.isError && !result.failure) {
+            if (!result.selectedDispatch)
+                throw new Error("Durable owner returned an unsealed provider turn");
+            const db = new WorkflowDb(root);
+            try {
+                if (result.selectedDispatch.actionId !== owner.actionId || db.operation(result.selectedDispatch.dispatchId)?.runId !== owner.runId ||
+                    db.structuredOwnerDispatch(result.selectedDispatch.dispatchId).tupleDigest !== result.selectedDispatch.digest)
+                    throw new Error("Domain callback returned a receipt for another owner");
+                db.replayStructuredDispatch(result.selectedDispatch.dispatchId, output);
+            }
+            finally {
+                db.close();
+            }
+        }
+        return result;
+    };
+    ownerDispatches.add(owned);
+    return owned;
+}
+export function isDurableOwnerDispatch(dispatch) { return ownerDispatches.has(dispatch); }

package/dist/structuredDispatchRecord.d.ts

@@ -0,0 +1,29 @@
+import { type OutputContract, type SelectedDispatchTupleV2, type StructuredResponse } from "rafi-spec";
+export interface SealedDispatchRecordV2 {
+    version: 2;
+    tupleJson: string;
+    tupleDigest: string;
+    descriptorDigest: string;
+    renderedInstructionDigest: string;
+}
+export interface RetainedStructuredReceiptV2 {
+    version: 2;
+    tupleDigest: string;
+    hostTurnId?: string;
+    receipt: Omit<Extract<StructuredResponse, {
+        state: "candidate";
+    }>, "value"> | StructuredResponse | null;
+    valueDigest?: string;
+    rejectedValue?: {
+        representation: "json-text" | "decoded-json";
+        digest: string;
+        evidenceDigest: string;
+        originalBytes: number;
+        retainedBytes: number;
+    };
+}
+export declare function hydrateStructuredReceipt(retained: RetainedStructuredReceiptV2, readEvidence: (digest: string) => Buffer | undefined): StructuredResponse | undefined;
+export declare function sealedDispatchRecord(tuple: SelectedDispatchTupleV2): SealedDispatchRecordV2;
+export declare function persistedDispatchTuple(record: SealedDispatchRecordV2): SelectedDispatchTupleV2;
+/** The same verifier is used before confirmation and by persisted domain readers. */
+export declare function verifyPersistedDispatch<T>(contract: OutputContract<T>, record: SealedDispatchRecordV2, receipt: StructuredResponse | undefined, receivedTuple?: SelectedDispatchTupleV2): T;

package/dist/structuredDispatchRecord.js

@@ -0,0 +1,36 @@
+import { canonicalJson, historicProviderWireContract, parseSelectedDispatchTupleV2, structuredDigest, validateStructuredCandidate } from "rafi-spec";
+export function hydrateStructuredReceipt(retained, readEvidence) {
+    if (!retained.receipt)
+        return undefined;
+    if (retained.receipt.state !== "candidate")
+        return retained.receipt;
+    if (!retained.valueDigest)
+        throw new Error("Retained native receipt has no bounded value reference");
+    const bytes = readEvidence(retained.valueDigest);
+    if (!bytes)
+        throw new Error("Retained native receipt value is missing");
+    const value = retained.receipt.representation === "json-text" ? bytes.toString() : JSON.parse(bytes.toString());
+    return { ...retained.receipt, value };
+}
+export function sealedDispatchRecord(tuple) {
+    return Object.freeze({ version: 2, tupleJson: canonicalJson(tuple), tupleDigest: tuple.digest,
+        descriptorDigest: tuple.descriptorDigest, renderedInstructionDigest: tuple.instructionDigest });
+}
+export function persistedDispatchTuple(record) {
+    if (!record || record.version !== 2 || typeof record.tupleJson !== "string")
+        throw new Error("Missing persisted sealed owner tuple");
+    const tuple = parseSelectedDispatchTupleV2(JSON.parse(record.tupleJson));
+    const { digest, ...fields } = tuple;
+    if (canonicalJson(tuple) !== record.tupleJson || structuredDigest(fields) !== digest || record.tupleDigest !== digest ||
+        record.descriptorDigest !== tuple.descriptorDigest || record.renderedInstructionDigest !== tuple.instructionDigest)
+        throw new Error("Persisted owner tuple canonical bytes or identity mismatch");
+    return tuple;
+}
+/** The same verifier is used before confirmation and by persisted domain readers. */
+export function verifyPersistedDispatch(contract, record, receipt, receivedTuple) {
+    const tuple = persistedDispatchTuple(record);
+    if (receivedTuple && canonicalJson(receivedTuple) !== record.tupleJson)
+        throw new Error("Receipt tuple differs from persisted owner intent");
+    const descriptor = historicProviderWireContract(contract, tuple);
+    return validateStructuredCandidate(contract, receipt, descriptor, tuple);
+}

package/dist/structuredLiveBudget.d.ts

@@ -0,0 +1,2 @@
+import type { ProviderQueryBudget } from "./adapters/types.js";
+export declare function inheritedStructuredLiveBudget(provider: "claude" | "codex", env?: NodeJS.ProcessEnv): ProviderQueryBudget | undefined;

package/dist/structuredLiveBudget.js

@@ -0,0 +1,23 @@
+/** Inherited supervision for public CLI journeys, including detached workers. */
+import { reserveStructuredLiveQuery, structuredLiveBudgetPath } from "rafi-spec";
+export function inheritedStructuredLiveBudget(provider, env = process.env) {
+    if (!env.RAFI_STRUCTURED_LIVE_RUNNER && !env.RAFI_STRUCTURED_LIVE_BUDGET_PATH)
+        return undefined;
+    const deadline = Date.parse(env.RAFI_LIVE_DEADLINE ?? "");
+    const root = env.RAFI_LIVE_RETAINED_LOG_DIRECTORY, scope = env.RAFI_LIVE_CREDENTIAL_SCOPE;
+    if (env.RAFI_LIVE_STRUCTURED !== "1" || !root || !scope || !env.RAFI_STRUCTURED_LIVE_RUNNER ||
+        !Number.isFinite(deadline) || deadline <= Date.now() || deadline > Date.now() + 30 * 60_000 ||
+        env.RAFI_STRUCTURED_LIVE_BUDGET_PATH !== structuredLiveBudgetPath(root, scope, deadline) ||
+        !(env.RAFI_LIVE_PROVIDERS ?? "claude,codex").split(",").includes(provider))
+        throw new Error("Invalid inherited structured live supervision");
+    const requireAuthoritativeCost = env.RAFI_LIVE_REQUIRE_COST_METER === "1";
+    if (requireAuthoritativeCost && provider === "codex")
+        throw new Error("Codex live structured validation is blocked: no authoritative spend meter");
+    const signal = AbortSignal.timeout(Math.max(1, deadline - Date.now()));
+    return { reserveQuery: selected => {
+            if (selected !== provider)
+                throw new Error("Inherited live provider mismatch");
+            return reserveStructuredLiveQuery({ path: env.RAFI_STRUCTURED_LIVE_BUDGET_PATH, runner: `${env.RAFI_STRUCTURED_LIVE_RUNNER}/cli-${process.pid}`,
+                provider, signal, deadline, requireAuthoritativeCost });
+        } };
+}

package/dist/structuredOperation.d.ts

@@ -0,0 +1,18 @@
+import { type OperationResponse, type OutputContract } from "rafi-spec";
+import type { BuilderAdapter, TurnRequest, TurnResult } from "./adapters/types.js";
+import type { StepStatus } from "./foreman.js";
+export declare function operationInstruction(contract: OutputContract): string;
+/**
+ * Actionable host message for a failed structured turn. The response text of an
+ * otherwise valid turn is evidence, not the error; prefer retained host
+ * failures, then the native rejection, then provider diagnostics.
+ */
+export declare function structuredTurnErrorMessage(turn: TurnResult, label?: string): string;
+export declare function operationResponse<T = unknown>(turn: TurnResult, contract: OutputContract): OperationResponse<T>;
+export declare function operationStatus(turn: TurnResult, contract: OutputContract, ticket?: string): StepStatus;
+export declare function operationPayload<T>(turn: TurnResult, contract: OutputContract): T;
+export declare function nativePolicy(output: OutputContract, policy?: TurnRequest): TurnRequest;
+/** Reuses the workflow journal. A receipt is retained before domain interpretation. */
+export declare function journalStructuredDispatch(root: string, adapter: BuilderAdapter, instruction: string, policy: TurnRequest, dispatch: (text: string, policy: TurnRequest) => Promise<TurnResult>): Promise<TurnResult>;
+/** Only unsealed host request fields survive a handoff or a restart. */
+export declare function continuationPolicy(policy: TurnRequest, parentDispatchId: string): TurnRequest;