@sema-agent/core/dist/core/memory-engine/consolidation-driver.js

Stateless, task-oriented AI agent core

import { join } from "node:path";
import { uuidv7 } from "../../internal/harness.js";
import { atomicWriteFileSync, ensureDirExists, lockedStrictUpdate, readStrictSidecar, enqueueMemoryAnnouncement, ControlPlaneCorruptError } from "./layout.js";
import { inlineUntrusted } from "../untrusted-text.js";
import { deliverEngineNotice } from "../engine-notice.js";
import { CONSOLIDATION_FORCE_THROTTLE_FLOOR_MS, screenConsolidationOptions, supersessionFuseCeiling, updateConsolidationGate, recommendationUnconsumed, CONSOLIDATION_WRITE_REFUSED_CODE, ConsolidationRefusedError, } from "./consolidation.js";
import { memoryConsolidationIncompleteNotice, memoryConsolidationWithheldNotice } from "./engine.js";
import { asThrownError, thrownText } from "../thrown-value.js";
import { CONSOLIDATION_DRIVE_ABORT, CONSOLIDATION_SNAPSHOT_PARKED, MEMORY_DISTILLER_CONTRACT_V1, detectCleanArmVerbatimLeak, driveConsolidationToFixpoint, isAliasModelId, llmPlanDistiller, mintExposurePartitionedPlan, mintLlmConsolidationPlan, normalizedCandidateRev, } from "./distiller.js";
export const CONSOLIDATION_DRIVER_RUNS_FILE = "distiller-runs.json";
export const CONSOLIDATION_DRIVER_PLANS_DIR = "distiller-plans";
function coerceRunsFile(raw) {
    if (raw === undefined)
        return { v: 1, scopes: {} };
    if (typeof raw !== "object" || raw === null || raw.v !== 1 || typeof raw.scopes !== "object" || raw.scopes === null) {
        throw new ControlPlaneCorruptError("memory consolidation driver run account has an unrecognized shape (fail-closed sidecar)");
    }
    for (const [scope, rowRaw] of Object.entries(raw.scopes)) {
        const r = rowRaw;
        if (typeof r !== "object" || r === null || typeof r["runId"] !== "string" || (r["state"] !== "pending" && r["state"] !== "settled") || typeof r["cyclesDone"] !== "number") {
            throw new ControlPlaneCorruptError(`memory consolidation driver run row for scope ${JSON.stringify(scope)} is malformed (fail-closed sidecar)`);
        }
    }
    return raw;
}
export function readConsolidationDriverRun(controlDir, scope) {
    return coerceRunsFile(readStrictSidecar(controlDir, CONSOLIDATION_DRIVER_RUNS_FILE, "memory consolidation driver run account")).scopes[scope];
}
function writeDriverRun(controlDir, row) {
    lockedStrictUpdate(controlDir, CONSOLIDATION_DRIVER_RUNS_FILE, "memory consolidation driver run account", coerceRunsFile, (file) => {
        const cur = file.scopes[row.scope];
        if (cur === undefined || cur.runId !== row.runId || (cur.attempt ?? 0) !== row.attempt) {
            const e = new Error(`memory consolidation driver run seat for scope ${JSON.stringify(row.scope)} was taken over by a newer invocation${cur !== undefined ? ` (run ${cur.runId} attempt ${cur.attempt ?? 0})` : ""} — this worker stops without settling; the newer claim owns the account.`);
            e.code = "memory.consolidation_driver_superseded";
            e[CONSOLIDATION_DRIVE_ABORT] = true;
            throw e;
        }
        file.scopes[row.scope] = row;
        return { next: file, result: undefined };
    });
}
function claimDriverRun(controlDir, scope, fresh) {
    return lockedStrictUpdate(controlDir, CONSOLIDATION_DRIVER_RUNS_FILE, "memory consolidation driver run account", coerceRunsFile, (file) => {
        const cur = file.scopes[scope];
        if (cur !== undefined && cur.state === "pending") {
            cur.attempt = (cur.attempt ?? 0) + 1;
            file.scopes[scope] = cur;
            return { next: file, result: { row: structuredClone(cur), resumed: true } };
        }
        const row = fresh();
        file.scopes[scope] = row;
        return { next: file, result: { row: structuredClone(row), resumed: false } };
    });
}
export function distillerPlanArchiveName(runId, attempt) {
    return `${runId}-a${attempt}.json`;
}
export function archiveDistillerPlan(controlDir, runId, plan, attempt = 1) {
    ensureDirExists(join(controlDir, CONSOLIDATION_DRIVER_PLANS_DIR));
    const name = distillerPlanArchiveName(runId, attempt);
    atomicWriteFileSync(join(controlDir, CONSOLIDATION_DRIVER_PLANS_DIR, name), `${JSON.stringify(plan, null, 2)}\n`);
    return name;
}
export { CONSOLIDATION_WRITE_REFUSED_CODE };
function driverConfigRefusal(message) {
    const e = new Error(message);
    e.code = "config.memory_consolidation_driver";
    return e;
}
class DriverMintFailure extends Error {
    detail;
    constructor(detail) {
        super(detail);
        this.detail = detail;
    }
}
class DriverPurityViolation extends Error {
    detail;
    constructor(detail) {
        super(detail);
        this.detail = detail;
    }
}
class MintInvalidated extends Error {
    detail;
    residue;
    constructor(detail, residue = []) {
        super(detail);
        this.detail = detail;
        this.residue = residue;
    }
}
const codeOf = (err) => {
    const c = err?.code;
    return typeof c === "string" ? c : undefined;
};
async function refuseUnlessWriteAllowed(judge, target, consequence) {
    let verdict;
    let threw;
    try {
        verdict = await judge(target);
    }
    catch (err) {
        threw = thrownText(err);
    }
    const answer = typeof verdict === "object" && verdict !== null ? verdict : undefined;
    if (threw === undefined && answer?.verdict === "no_objection")
        return;
    const text = (v) => (typeof v === "string" && v !== "" ? inlineUntrusted(v, 200) : undefined);
    const where = text(answer?.layer);
    let why;
    if (threw !== undefined)
        why = `the write judge threw (${inlineUntrusted(threw, 200)}), so whether a standing rule forbids this write is unknown`;
    else if (answer?.verdict === "deny")
        why = `a standing rule layer${where !== undefined ? ` (${where})` : ""} refuses writes into this library${text(answer.message) !== undefined ? `: ${text(answer.message)}` : ""}`;
    else if (answer?.verdict === "ask")
        why = `a standing rule layer${where !== undefined ? ` (${where})` : ""} would ask a person before a write into this library, and a background run has nobody to answer${text(answer.message) !== undefined ? `: ${text(answer.message)}` : ""}`;
    else if (answer?.verdict === "unanswerable")
        why = `the write judge could not answer${where !== undefined ? ` at ${where}` : ""}${text(answer.cause) !== undefined ? ` (${text(answer.cause)})` : ""}${text(answer.reason) !== undefined ? `: ${text(answer.reason)}` : ""}, so whether a standing rule forbids this write is unknown`;
    else
        why = "the write judge answered something outside its closed set of verdicts";
    throw new ConsolidationRefusedError(CONSOLIDATION_WRITE_REFUSED_CODE, `memory consolidation refused for scope ${inlineUntrusted(target.scope, 80)}: ${why}${consequence !== undefined ? ` — ${consequence}` : ""} (library ${inlineUntrusted(target.path, 200)})`);
}
const MAX_THROTTLE_WAITS_PER_SNAPSHOT = 4;
const MAX_BUSY_WAITS = 2;
export async function runMemoryConsolidationDriver(engine, scope, opts) {
    if (typeof opts?.chat !== "function")
        throw driverConfigRefusal("runMemoryConsolidationDriver needs an explicit chat seat (opts.chat) — the engine holds no model seat and a driver that silently skips would publish nothing as a model's answer.");
    if (typeof opts.model !== "string" || opts.model.trim() === "" || isAliasModelId(opts.model)) {
        throw driverConfigRefusal(`runMemoryConsolidationDriver needs an EXPLICIT model id, got ${JSON.stringify(opts.model)} — an alias can be re-pointed upstream and would move the run with no trace in the archive.`);
    }
    if (opts.mintRepairBudget !== undefined && (typeof opts.mintRepairBudget !== "number" || !Number.isFinite(opts.mintRepairBudget) || opts.mintRepairBudget < 0 || opts.mintRepairBudget > 1)) {
        throw driverConfigRefusal(`runMemoryConsolidationDriver: mintRepairBudget must be a number in [0, 1] when present (got ${String(opts.mintRepairBudget)}) — an unevaluable budget is refused loudly, never folded to the default.`);
    }
    if (opts.maxCycles !== undefined && (!Number.isInteger(opts.maxCycles) || opts.maxCycles < 1)) {
        throw driverConfigRefusal(`runMemoryConsolidationDriver: maxCycles must be a positive integer when present (got ${String(opts.maxCycles)}).`);
    }
    const contract = opts.contract ?? MEMORY_DISTILLER_CONTRACT_V1;
    if (typeof contract?.version !== "string" || contract.version === "" || typeof contract?.grouping?.instructions !== "string" || typeof contract?.writing?.instructions !== "string") {
        throw driverConfigRefusal("runMemoryConsolidationDriver: opts.contract does not carry the contract shape (version + grouping/writing instructions).");
    }
    const screened = screenConsolidationOptions(opts.consolidation ?? {}, "carry");
    const mintRepairBudget = opts.mintRepairBudget ?? 0.1;
    const now = opts.now ?? Date.now;
    const rawSleep = opts.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
    const sleep = async (ms) => {
        try {
            await rawSleep(ms);
        }
        catch (err) {
            const e = typeof err === "object" && err !== null ? err : asThrownError(err);
            Reflect.set(e, CONSOLIDATION_DRIVE_ABORT, true);
            throw e;
        }
    };
    const throttleWindowMs = Math.min(screened.minRunIntervalMs, CONSOLIDATION_FORCE_THROTTLE_FLOOR_MS);
    const controlDir = engine.controlPlaneRoot;
    if (typeof opts.writeJudge !== "function")
        throw driverConfigRefusal(`runMemoryConsolidationDriver needs an explicit write judge (opts.writeJudge), got ${typeof opts.writeJudge} — a run writes the library with nobody watching, so it asks the judgment a foreground write meets before it starts; an absent seat is refused, never read as "no rules apply" (a host that holds no rules passes a judge that answers no_objection).`);
    let libraryHome;
    try {
        libraryHome = engine.consolidationWriteHome(scope);
    }
    catch (err) {
        throw new ConsolidationRefusedError(CONSOLIDATION_WRITE_REFUSED_CODE, `memory consolidation refused for scope ${inlineUntrusted(scope, 80)}: where this run would write could not be derived (${inlineUntrusted(thrownText(err), 200)}), so whether a standing rule forbids it is unknown — no run was started and nothing was written.`);
    }
    await refuseUnlessWriteAllowed(opts.writeJudge, { scope, path: libraryHome }, "no run was started and nothing was written.");
    const writeGate = (target) => refuseUnlessWriteAllowed(opts.writeJudge, target);
    let refusedSeat = undefined;
    const parkedSeat = await recoverSeat(engine, scope, { sleep, windowMs: throttleWindowMs, writeGate }).catch((err) => {
        if (!(err instanceof ConsolidationRefusedError) || err.code !== CONSOLIDATION_WRITE_REFUSED_CODE)
            throw err;
        refusedSeat = err;
        return undefined;
    });
    const openFold = await engine.readConsolidationFoldState(scope);
    const { row: run, resumed } = claimDriverRun(controlDir, scope, () => ({
        runId: uuidv7(),
        scope,
        attempt: 1,
        requestId: opts.requestId ?? `consolidation-run-${uuidv7()}`,
        contractVersion: contract.version,
        model: opts.model,
        startedAt: now(),
        state: "pending",
        cyclesDone: 0,
        entriesSuperseded: 0,
        foldBaseline: { superseded: openFold.superseded },
        planIds: [],
        usage: { calls: 0, promptTokens: 0, completionTokens: 0, retries: 0, truncations: 0 },
        repairs: { hallucinatedMembers: 0, duplicateMembers: 0, nonIntegerMembers: 0, emptyGroups: 0, oversizeGroups: 0 },
        writeFailures: [],
    }));
    if (resumed && run.planCache === undefined && (run.model !== opts.model || run.contractVersion !== contract.version)) {
        run.model = opts.model;
        run.contractVersion = contract.version;
    }
    const announceFailures = [];
    const announce = (items) => {
        try {
            enqueueMemoryAnnouncement(controlDir, { kind: "gate", at: now(), items });
        }
        catch (err) {
            announceFailures.push(thrownText(err));
        }
    };
    const egressEndpoint = ((raw) => {
        if (raw === undefined)
            return " (host-supplied chat seat; no endpoint recorded)";
        try {
            const u = new URL(raw);
            return ` at ${inlineUntrusted(u.origin, 120)}`;
        }
        catch {
            return " at an endpoint whose value could not be parsed as a URL (not echoed here — it may carry credentials)";
        }
    })(opts.baseUrl);
    const egressSeat = `${inlineUntrusted(opts.model, 80)}${egressEndpoint}`;
    const announceMintEgress = (calls, offered, plan) => {
        if (calls === 0) {
            announce([
                `memory consolidation driver run ${run.runId} for scope ${inlineUntrusted(scope, 80)} made NO model call: all ${offered} offered candidate(s) were withheld from every arm, so no memory content left this process.`,
            ]);
            return;
        }
        const armLine = (plan?.minting.arms ?? []).map((a) => `${a.arm} arm ${a.candidateCount} candidate(s) in ${a.calls} call(s)`).join(", ");
        announce([
            `memory consolidation driver run ${run.runId} for scope ${inlineUntrusted(scope, 80)} SENT memory content to the configured consolidation model: ${egressSeat} — ${armLine || `up to ${offered} candidate(s) over ${calls} call(s) (the mint failed before its per-arm split was recorded; an arm that never ran sent nothing)`}. Each candidate was rendered as its name, description and body.`,
        ]);
        const withheld = run.withheldFromCleanArm ?? 0;
        if (withheld > 0) {
            const neverSent = run.withheldNeverSent ?? 0;
            const sent = Math.max(0, withheld - neverSent);
            announce([
                `  ${withheld} externally-marked entr${withheld === 1 ? "y was" : "ies were"} withheld from the clean products' prompts.` +
                    (sent > 0 ? ` ${sent} of those ${sent === 1 ? "was" : "were"} sent to the model in a separate marked-only call.` : "") +
                    (neverSent > 0 ? ` ${neverSent} ${neverSent === 1 ? "was" : "were"} not sent to the model at all.` : ""),
            ]);
        }
    };
    const settle = (outcome, drive, stopDetail) => {
        run.state = "settled";
        run.outcome = outcome;
        run.settledAt = now();
        if (stopDetail !== undefined)
            run.stopDetail = stopDetail;
        run.residue = run.residue ?? drive?.stop?.fuseBlocked;
        writeDriverRun(controlDir, run);
        if (outcome === "converged") {
            try {
                updateConsolidationGate(controlDir, (file) => {
                    const row = file.scopes[scope];
                    if (row === undefined || !recommendationUnconsumed(row))
                        return { result: undefined };
                    row.lastRunAt = now();
                    return { next: file, result: undefined };
                });
            }
            catch (err) {
                announceFailures.push(thrownText(err));
            }
        }
        const notices = [];
        if (outcome !== "converged") {
            const notice = memoryConsolidationIncompleteNotice({ scope, runId: run.runId, stop: outcome, residueProducts: run.residue?.length ?? 0, cyclesDone: run.cyclesDone });
            notices.push(notice);
            if (opts.onNotice !== undefined)
                deliverEngineNotice(opts.onNotice, notice);
            announce([notice.message]);
        }
        if ((run.withheldFromCleanArm ?? 0) > 0) {
            const withheldNotice = memoryConsolidationWithheldNotice({ scope, runId: run.runId, withheld: run.withheldFromCleanArm, neverSent: run.withheldNeverSent ?? 0 });
            notices.push(withheldNotice);
            if (opts.onNotice !== undefined)
                deliverEngineNotice(opts.onNotice, withheldNotice);
            announce([withheldNotice.message]);
        }
        return {
            runId: run.runId,
            scope,
            resumed,
            outcome,
            converged: outcome === "converged",
            ...(run.stopDetail !== undefined ? { stopDetail: run.stopDetail } : {}),
            cycles: drive?.cycles ?? [],
            cyclesDone: run.cyclesDone,
            productsCommitted: drive?.productsCommitted ?? 0,
            entriesSuperseded: drive?.entriesSuperseded ?? 0,
            planIds: [...run.planIds],
            model: run.model,
            contractVersion: run.contractVersion,
            usage: { ...run.usage },
            repairs: { ...run.repairs },
            writeFailures: [...run.writeFailures],
            residue: run.residue ?? [],
            ...(run.withheldFromCleanArm !== undefined ? { withheldFromCleanArm: run.withheldFromCleanArm } : {}),
            ...(run.withheldNeverSent !== undefined ? { withheldNeverSent: run.withheldNeverSent } : {}),
            ...(run.planArchive !== undefined ? { planArchive: run.planArchive } : {}),
            notices,
            ...(announceFailures.length > 0 ? { announceFailures: [...announceFailures] } : {}),
        };
    };
    if (parkedSeat !== undefined) {
        return settle("parked", undefined, parkedSeat);
    }
    if (refusedSeat !== undefined)
        return settle("refused", undefined, `reconcileConsolidation refused the plan an earlier run left seated: ${refusedSeat.code}: ${refusedSeat.message}`);
    let staleResidue = [];
    let staleResidueMemberIds = new Set();
    const distill = async (candidates, snapshot, s) => {
        if (run.planCache === undefined) {
            let minted;
            try {
                minted = await mintExposurePartitionedPlan({
                    candidates,
                    chat: opts.chat,
                    model: opts.model,
                    ...(opts.baseUrl !== undefined ? { baseUrl: opts.baseUrl } : {}),
                    maxInputsPerProduct: screened.maxInputsPerProduct,
                    contract,
                    onProgress: opts.onProgress ?? null,
                });
            }
            catch (err) {
                if (codeOf(err) === "config.memory_consolidation_driver")
                    throw err;
                announce([
                    `memory consolidation driver run ${run.runId} for scope ${inlineUntrusted(scope, 80)} ATTEMPTED to send memory content to the configured consolidation model: ${egressSeat} — the seat threw before any answer was recorded, so whether any content reached the provider is NOT observable from here; up to ${candidates.length} candidate(s) were in flight, each rendered as its name, description and body. Treat this as a possible transmission.`,
                ]);
                throw new DriverMintFailure(`the model seat failed during the mint: ${thrownText(err)}`);
            }
            const transcript = minted.ok ? minted.plan.minting.transcript : minted.calls;
            run.usage.calls += transcript.length;
            for (const c of transcript) {
                run.usage.promptTokens += c.usage?.promptTokens ?? 0;
                run.usage.completionTokens += c.usage?.completionTokens ?? 0;
            }
            if (!minted.ok) {
                announceMintEgress(transcript.length, candidates.length);
                throw new DriverMintFailure(minted.reason);
            }
            const plan = minted.plan;
            if (plan.withheldFromCleanArm !== undefined) {
                run.withheldFromCleanArm = plan.withheldFromCleanArm;
                const markedServed = (plan.servedCandidates ?? []).filter((r) => r.marked).length;
                run.withheldNeverSent = Math.max(0, plan.withheldFromCleanArm - markedServed);
            }
            announceMintEgress(transcript.length, candidates.length, plan);
            run.usage.retries += plan.minting.parseRepairs.retries;
            run.usage.truncations += plan.minting.parseRepairs.lengthCapped.length;
            run.repairs = {
                hallucinatedMembers: plan.minting.repairs.hallucinatedMembers,
                duplicateMembers: plan.minting.repairs.duplicateMembers,
                nonIntegerMembers: plan.minting.repairs.nonIntegerMembers,
                emptyGroups: plan.minting.repairs.emptyGroups,
                oversizeGroups: plan.minting.repairs.oversizeGroups.length,
            };
            run.writeFailures = plan.minting.writeFailures.map((w) => ({ key: w.key, members: w.members, reason: w.reason })) ?? [];
            const dropped = plan.minting.repairs.hallucinatedMembers + plan.minting.repairs.duplicateMembers + plan.minting.repairs.nonIntegerMembers;
            const claimed = plan.products.reduce((a, p) => a + p.inputIds.length, 0) + plan.minting.writeFailures.reduce((a, w) => a + w.members, 0);
            const total = dropped + claimed;
            const ratio = total === 0 ? (dropped > 0 ? 1 : 0) : dropped / total;
            if (ratio > mintRepairBudget) {
                throw new DriverMintFailure(`the mint needed structural repairs on ${dropped} of ${total} member claim(s) (${(ratio * 100).toFixed(1)}% > mintRepairBudget ${(mintRepairBudget * 100).toFixed(1)}%) — a plan repaired this much does not represent the model's intent, and committing it would fold entries the harness chose, not the model (hallucinated ${plan.minting.repairs.hallucinatedMembers}, duplicate ${plan.minting.repairs.duplicateMembers}, nonInteger ${plan.minting.repairs.nonIntegerMembers}; emptied groups ${plan.minting.repairs.emptyGroups}, oversize ${plan.minting.repairs.oversizeGroups.length})`);
            }
            const purity = detectCleanArmVerbatimLeak(plan);
            if (purity.findings.length > 0) {
                run.planArchive = distillerPlanArchiveName(run.runId, run.attempt);
                writeDriverRun(controlDir, run);
                archiveDistillerPlan(controlDir, run.runId, plan, run.attempt);
                const where = [...new Set(purity.findings.map((f) => `#${f.productIndex}.${f.field}`))].sort();
                throw new DriverPurityViolation(`the exposure partition's clean arm is not clean: ${purity.findings.length} verbatim marked-side byte sequence(s) surfaced in ${new Set(purity.findings.map((f) => f.productIndex)).size} product(s) that would commit UNMARKED, across ${purity.scannedProducts} scanned product(s) against ${purity.markedUniqueShingles} marked-unique shingle(s). Locations (product index into the archived plan . field): ${where.slice(0, 8).join(", ")}${where.length > 8 ? ", …" : ""}. The whole mint is discarded with zero writes; NO model-authored bytes (neither the offending text nor the product keys) are reproduced here — re-run detectCleanArmVerbatimLeak over the archived plan ${run.planArchive} for the byte-level witness.`);
            }
            run.planArchive = distillerPlanArchiveName(run.runId, run.attempt);
            run.planCache = {
                maxInputsPerProduct: plan.maxInputsPerProduct,
                products: plan.products,
                ...(plan.mintExposure !== undefined ? { mintExposure: plan.mintExposure } : {}),
                ...(plan.servedCandidates !== undefined ? { servedCandidates: plan.servedCandidates } : {}),
            };
            writeDriverRun(controlDir, run);
            archiveDistillerPlan(controlDir, run.runId, plan, run.attempt);
        }
        const roster = run.planCache?.servedCandidates;
        if (roster !== undefined && roster.length > 0) {
            const offeredNow = new Map();
            for (const c of candidates) {
                if (typeof c?.entry?.id === "string")
                    offeredNow.set(c.entry.id, { rev: normalizedCandidateRev(c.entry.rev), marked: c.marked === true });
            }
            let ownFold;
            const violations = [];
            for (const rowR of roster) {
                const off = offeredNow.get(rowR.id);
                if (off !== undefined) {
                    if (off.rev !== rowR.rev)
                        violations.push(`${rowR.id}: rev moved since the mint`);
                    else if (off.marked !== rowR.marked)
                        violations.push(`${rowR.id}: marked flag flipped since the mint (${String(rowR.marked)} -> ${String(off.marked)})`);
                    continue;
                }
                ownFold ??= collectRunFoldEvidence(engine, scope, run.requestId);
                if (ownFold.unreadable !== undefined)
                    continue;
                if (!ownFold.targets.has(rowR.id))
                    violations.push(`${rowR.id}: left the candidate set without a fold this run's plans attest (deleted, excluded, or folded by another writer)`);
            }
            if (violations.length > 0) {
                const residue = (run.planCache?.products ?? []).flatMap((p) => {
                    const live = (p.inputIds ?? []).filter((id) => offeredNow.has(id));
                    return live.length > 0 ? [{ name: p.name, targets: live.length }] : [];
                });
                delete run.planCache;
                throw new MintInvalidated(`the mint's served-world roster failed the cross-cycle re-check (${violations.length} row(s)): ${violations.slice(0, 5).join("; ")}${violations.length > 5 ? "; …" : ""} — the cached plan is discarded; committed cycles stand and a fresh run re-mints over the current library`, residue);
            }
        }
        const offered = new Map();
        for (const c of candidates)
            if (typeof c?.entry?.id === "string")
                offered.set(c.entry.id, c.entry.rev);
        staleResidueMemberIds = new Set();
        staleResidue = (run.planCache?.products ?? []).flatMap((p) => {
            const ids = p.inputIds ?? [];
            const live = ids.filter((id) => offered.has(id));
            if (live.length === 0)
                return [];
            const stale = p.inputRevs !== undefined && live.some((id) => p.inputRevs[id] !== undefined && offered.get(id) !== p.inputRevs[id]);
            const vanished = live.length < ids.length;
            const unanchored = p.inputRevs === undefined;
            if (!(stale || vanished || unanchored))
                return [];
            for (const id of live)
                staleResidueMemberIds.add(id);
            return [{ name: p.name, targets: live.length }];
        });
        const replayView = run.planCache !== undefined && run.planCache.products.some((p) => p.inputRevs === undefined)
            ? { ...run.planCache, products: run.planCache.products.filter((p) => p.inputRevs !== undefined) }
            : run.planCache;
        return llmPlanDistiller(replayView)(candidates, snapshot, s);
    };
    let firstSnapshotOfNewRun = !resumed;
    const takeSnapshot = async (_cycle) => {
        writeDriverRun(controlDir, run);
        let force = !firstSnapshotOfNewRun;
        let throttleWaits = 0;
        let busyWaits = 0;
        for (;;) {
            try {
                const snap = await engine.snapshotConsolidationCandidates(scope, { full: true, ...(force ? { force: { requestId: run.requestId } } : {}) });
                firstSnapshotOfNewRun = false;
                return snap;
            }
            catch (err) {
                const code = codeOf(err);
                if (code === "memory.consolidation_gated") {
                    if (!force) {
                        force = true;
                        continue;
                    }
                    if (throttleWaits >= MAX_THROTTLE_WAITS_PER_SNAPSHOT)
                        throw err;
                    throttleWaits += 1;
                    const lastRunAt = engine.readConsolidationGate(scope)?.lastRunAt;
                    const until = (lastRunAt ?? now()) + throttleWindowMs;
                    run.nextEligibleAt = until;
                    writeDriverRun(controlDir, run);
                    const waitMs = Math.max(1, until - now());
                    await sleep(waitMs);
                    continue;
                }
                if (code === "memory.consolidation_busy") {
                    if (busyWaits >= MAX_BUSY_WAITS)
                        throw err;
                    busyWaits += 1;
                    const parked = await recoverSeat(engine, scope, { sleep, windowMs: throttleWindowMs, writeGate });
                    if (parked !== undefined) {
                        const e = new Error(parked);
                        e[CONSOLIDATION_SNAPSHOT_PARKED] = true;
                        throw e;
                    }
                    continue;
                }
                throw err;
            }
        }
    };
    const cyclesSeen = [];
    let drive;
    try {
        drive = await driveConsolidationToFixpoint(engine, scope, {
            distill,
            readFoldState: () => engine.readConsolidationFoldState(scope),
            options: screened,
            fuseCeilingOf: supersessionFuseCeiling,
            requestIdPrefix: run.requestId,
            maxCycles: opts.maxCycles ?? 64,
            takeSnapshot,
            writeGate,
            onCycle: (row) => {
                cyclesSeen.push(row);
                if (row.committed.products > 0 || row.committed.superseded > 0)
                    run.cyclesDone += 1;
                run.entriesSuperseded = (run.entriesSuperseded ?? 0) + row.committed.superseded;
                if (row.planId !== undefined)
                    run.planIds.push(row.planId);
                run.nextEligibleAt = now() + throttleWindowMs;
                writeDriverRun(controlDir, run);
            },
        });
    }
    catch (err) {
        if (err instanceof DriverMintFailure) {
            announce([`memory consolidation driver run ${run.runId} for scope ${inlineUntrusted(scope, 80)} FAILED before any write: ${inlineUntrusted(err.detail, 300)}`]);
            return settle("driver_failed", undefined, err.detail);
        }
        if (err instanceof DriverPurityViolation) {
            announce([`memory consolidation driver run ${run.runId} for scope ${inlineUntrusted(scope, 80)} REFUSED on the clean-arm purity gate (no writes): ${inlineUntrusted(err.detail, 300)}`]);
            return settle("purity_violation", undefined, err.detail);
        }
        if (err instanceof MintInvalidated) {
            announce([`memory consolidation driver run ${run.runId} for scope ${inlineUntrusted(scope, 80)} MINT INVALIDATED: ${inlineUntrusted(err.detail, 300)}`]);
            if (run.residue === undefined && err.residue.length > 0)
                run.residue = err.residue;
            const partial = {
                cycles: cyclesSeen,
                productsCommitted: cyclesSeen.reduce((a, c) => a + c.committed.products, 0),
                entriesSuperseded: cyclesSeen.reduce((a, c) => a + c.committed.superseded, 0),
            };
            return settle("mint_invalidated", partial, err.detail);
        }
        throw err;
    }
    const writeResidue = run.writeFailures.map((w) => ({ name: w.key, targets: w.members }));
    const driverResidue = [...staleResidue, ...writeResidue];
    if (drive.converged) {
        const plannedIds = [...new Set((run.planCache?.products ?? []).flatMap((p) => p.inputIds ?? []))];
        const plannedMembers = (run.planCache?.products ?? []).reduce((a, p) => a + (p.inputIds?.length ?? 0), 0);
        const rowAccount = run.entriesSuperseded ?? 0;
        const storeAccount = run.foldBaseline !== undefined ? Math.max(0, drive.foldState.after.superseded - run.foldBaseline.superseded) : rowAccount;
        const supersededAttested = Math.max(rowAccount, storeAccount);
        const residueTargets = driverResidue.reduce((a, r) => a + r.targets, 0);
        const accounted = supersededAttested + residueTargets;
        if (plannedMembers > accounted) {
            run.residue = driverResidue;
            return settle("driver_failed", drive, `the drive reached a fixpoint but the account does not balance: ${plannedMembers} planned member(s), ${supersededAttested} superseded attested for this run (row account ${rowAccount}, store delta ${run.foldBaseline !== undefined ? storeAccount : "unavailable — the row predates the store anchor"}), ${residueTargets} in named residue — ${plannedMembers - accounted} member(s) left the candidate set without a fold the store attests (deleted or excluded mid-run${run.foldBaseline !== undefined ? "" : ", or folded in a window whose account write did not survive"}); their entries stand (or revive with their exclusion), and a fresh run re-mints over the current library`);
        }
        if (plannedIds.length > 0) {
            const evidence = collectRunFoldEvidence(engine, scope, run.requestId);
            if (evidence.skipped.length > 0) {
                const named = evidence.skipped.slice(0, 5).map((s) => `${s.planId} (${s.state})`).join(", ");
                announce([
                    `memory consolidation conservation wall for scope ${inlineUntrusted(scope, 80)}: ${evidence.skipped.length} same-scope plan file(s) answered unreadable and were SKIPPED as foreign to run ${run.runId} — they attest nothing for this run and need out-of-band repair: ${named}${evidence.skipped.length > 5 ? ", …" : ""}`,
                ]);
            }
            if (evidence.unreadable !== undefined) {
                run.residue = driverResidue;
                return settle("driver_failed", drive, `the drive reached a fixpoint but the member-level fold evidence is incomplete: plan ${evidence.unreadable} — one of THIS run's own cycles — answered ${evidence.unreadableState} (control-plane damage on run-owned evidence, not a transient race); a converged label needs attestable members; the library stands as committed and a fresh run re-mints over the current bytes`);
            }
            const missing = plannedIds.filter((id) => !evidence.targets.has(id) && !staleResidueMemberIds.has(id));
            if (missing.length > 0) {
                run.residue = driverResidue;
                return settle("driver_failed", drive, `the drive reached a fixpoint but ${missing.length} of ${plannedIds.length} planned member(s) left the candidate set without a fold this run's plans attest (deleted, excluded, or superseded by another writer mid-run; e.g. ${missing.slice(0, 5).join(", ")}) — a store-delta count can be numerically offset by an unrelated interleaved fold, so member identity is the final judge; the entries stand (or revive with their exclusion) and a fresh run re-mints over the current library`);
            }
        }
        if (driverResidue.length > 0) {
            run.residue = driverResidue;
            return settle("driver_failed", drive, `the drive reached the surviving plan's fixpoint, but the driver's own half left ${driverResidue.length} group(s) unfolded (${staleResidue.length} stale against edited inputs, ${writeResidue.length} writing-pass failure(s)) — their members stay as they were; a fresh run re-mints over the current bytes`);
        }
        return settle("converged", drive);
    }
    if (driverResidue.length > 0)
        run.residue = [...(drive.stop?.fuseBlocked ?? []), ...driverResidue];
    const plannedAtStop = (run.planCache?.products ?? []).some((p) => (p.inputIds?.length ?? 0) > 0);
    if (plannedAtStop) {
        const evidence = collectRunFoldEvidence(engine, scope, run.requestId);
        if (evidence.unreadable !== undefined) {
            announce([
                `memory consolidation driver run ${run.runId} for scope ${inlineUntrusted(scope, 80)}: plan ${evidence.unreadable} — one of THIS run's own cycles — answered ${evidence.unreadableState} (control-plane damage on run-owned evidence, not a transient race); the run stops non-converged with the damage disclosed, and a fresh run re-mints over the current bytes`,
            ]);
        }
    }
    const stop = drive.stop;
    if (stop?.fuseBlocked !== undefined)
        return settle("fuse_residue", drive, stop.reason);
    if (stop?.exhausted === true)
        return settle("max_cycles", drive, stop.reason);
    if (stop?.parked === true)
        return settle("parked", drive, stop.reason);
    return settle("refused", drive, stop?.reason ?? "the drive stopped without a stated reason");
}
function collectRunFoldEvidence(engine, scope, requestId) {
    const cycleId = new RegExp(`^${requestId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}-c\\d+$`);
    const targets = new Set();
    const skipped = [];
    for (const summary of engine.listConsolidationPlans()) {
        if (summary.corrupt === true)
            continue;
        if (summary.scope !== scope)
            continue;
        const ev = engine.readConsolidationPlanFoldEvidence(summary.planId);
        if (ev.state !== "ok") {
            if (ev.state === "corrupt" && ev.requestId !== undefined && cycleId.test(ev.requestId)) {
                return { targets, unreadable: summary.planId, unreadableState: ev.state, skipped };
            }
            skipped.push({ planId: summary.planId, state: ev.state });
            continue;
        }
        if (ev.scope !== scope || !cycleId.test(ev.requestId))
            continue;
        for (const t of ev.supersededTargets)
            targets.add(t);
    }
    return { targets, skipped };
}
async function recoverSeat(engine, scope, { sleep, windowMs, writeGate }) {
    await engine.reconcileConsolidation(scope, { writeGate });
    let seat = engine.readConsolidationGate(scope)?.openPlanId;
    if (seat === undefined)
        return undefined;
    const summary = engine.listConsolidationPlans().find((p) => p.planId === seat);
    if (summary?.corrupt === true || summary?.state === "conflict") {
        return `plan ${seat} holds the ${JSON.stringify(scope)} seat in a ${summary.corrupt === true ? "corrupt" : "conflict"} state — resolveConsolidationPlan(planId, "retry" | "discard") is the host valve; the run parks rather than stacking a second plan on the seat`;
    }
    await sleep(windowMs);
    await engine.reconcileConsolidation(scope, { writeGate });
    seat = engine.readConsolidationGate(scope)?.openPlanId;
    if (seat === undefined)
        return undefined;
    const again = engine.listConsolidationPlans().find((p) => p.planId === seat);
    if (again?.corrupt === true || again?.state === "conflict") {
        return `plan ${seat} holds the ${JSON.stringify(scope)} seat in a ${again.corrupt === true ? "corrupt" : "conflict"} state — resolveConsolidationPlan(planId, "retry" | "discard") is the host valve; the run parks rather than stacking a second plan on the seat`;
    }
    return undefined;
}