@sema-agent/core 5.57.0 → 5.59.0

package/dist/core/memory-engine/consolidation-driver.d.ts

@@ -0,0 +1,211 @@
+/**
+ * design/376 片② — the host CONSOLIDATION DRIVER verb: one call that takes a long-accumulated,
+ * never-consolidated library to its fold fixpoint through the four engine verbs, as a PERSISTENT
+ * MULTI-CYCLE RUN.
+ *
+ * Why a run is a first-class object: under factory defaults a cold-start consolidation is a
+ * dozen-plus cycles with a hard 60-second throttle floor between them — a persistent job measured
+ * in minutes, not a call. The engine deliberately keeps NO driver state (its gate row settles per
+ * plan and clears the session count), so without a durable run account a process exit between two
+ * cycles would strand the work: no open plan to reconcile, no session edge to re-arm, and a naive
+ * re-entry would re-mint the whole plan at full model cost. The run row under the control plane is
+ * the resume seat: `runMemoryConsolidation` first looks for a PENDING run of the scope and
+ * CONTINUES it (same plan cache, same force requestId, zero new mint) — the idempotent re-entry
+ * GD-15 pins.
+ *
+ * Boundary reminders (design/339 §1.1, unchanged by this module):
+ *  - the engine adjudicates and commits; this driver only proposes and schedules — every write
+ *    goes through `commitConsolidationPlan`, nothing here touches the store;
+ *  - the engine holds no model seat; the model reaches this module as an explicit chat function;
+ *  - core still owns no timer: the throttle waits here run INSIDE a host's explicit call (or the
+ *    auto lane's task-boundary tick), never on a background schedule of core's own.
+ */
+import type { EngineNotice } from "../types.js";
+import { type ConsolidationGateRow, type ConsolidationRunStopReason, type MemoryConsolidationOptions } from "./consolidation.js";
+import { type ConsolidationPlanFoldEvidence, type ConsolidationPlanSummary } from "./engine.js";
+import { mintLlmConsolidationPlan, type ConsolidationDriveCycleRow, type ConsolidationDriveEngine, type ConsolidationFoldState, type DistillerChatFn, type LlmConsolidationPlan, type LlmConsolidationPlanProduct, type LlmDistillerContract } from "./distiller.js";
+export declare const CONSOLIDATION_DRIVER_RUNS_FILE = "distiller-runs.json";
+/** §1.6-4 — the mint archive: what was shown to the model and what it answered, verbatim, per run
+ *  (the fold law's audit other-half; strict-family placement beside the plan workbook). */
+export declare const CONSOLIDATION_DRIVER_PLANS_DIR = "distiller-plans";
+export interface ConsolidationDriverRunRow {
+    runId: string;
+    scope: string;
+    /** The WRITER claim: every open/resume bumps this under the run
+     *  store's lock, and every later write of the row is conditional on (runId, attempt) still
+     *  standing — of two invocations that raced onto one scope, exactly one keeps writing; the
+     *  superseded one stops with a coded error instead of silently clobbering the winner's counters
+     *  or terminal state. (Model spend under a genuine concurrent double-call is still at-least-once
+     *  — the claim serializes the ACCOUNT; the engine's plan-seat CAS serializes the store, and
+     *  cross-node cost suppression is the engine lease seat's job.) */
+    attempt: number;
+    /** The run-scoped force credential: ONE requestId across every forced snapshot of the run (the
+     *  engine dedups the FORCED audit announcement on it — one line per run). */
+    requestId: string;
+    /** The contract version of the run's surviving MINT — stamped at open, RE-stamped (with
+     *  {@link model}) by a resume that re-mints. */
+    contractVersion: string;
+    /** The id that minted the run's surviving plan: stamped at open; RE-stamped on a resume that
+     *  re-mints (the plan cache absent — nothing of the opening mint survived, so the current seat
+     *  mints every byte this run commits). The per-attempt plan archive is the byte-level anchor
+     *  either way. */
+    model: string;
+    startedAt: number;
+    state: "pending" | "settled";
+    /** Terminal only; the ONE closed set the receipt and the `_incomplete` notice share. */
+    outcome?: ConsolidationRunStopReason;
+    settledAt?: number;
+    stopDetail?: string;
+    /** The minted plan's replayable half (mint ONCE per run; each cycle filters, never re-mints). */
+    planCache?: {
+        maxInputsPerProduct: number;
+        products: LlmConsolidationPlanProduct[];
+    };
+    /** The archived mint transcript's file name under {@link CONSOLIDATION_DRIVER_PLANS_DIR}. */
+    planArchive?: string;
+    /** COMMITTED cycles only (the store moved): a refused/fuse-blocked/zero-delta cycle row does
+     *  not count — the receipt's "committed cycle(s)" label and the incomplete notice's zero-cycle
+     *  branch both read this number as writes. */
+    cyclesDone: number;
+    /** Store-delta superseded total across EVERY invocation of this run (the conservation wall's
+     *  evidence half — see the convergence check in the verb). Accumulated per cycle AFTER the
+     *  commit, so a crash between a cycle's commit and its row write loses that cycle's delta —
+     *  {@link foldBaseline} is the wall's immune second witness for exactly that window. */
+    entriesSuperseded: number;
+    /** The scope's fold-state `superseded` count at run OPEN (fresh claim; absent on rows opened
+     *  before the field existed). The conservation wall's STORE anchor: `final.superseded − this`
+     *  attests the run's folds even when a crash lands between a cycle's commit and its account
+     *  write — the seat serializes this scope's folds, so the since-open delta is this run's. */
+    foldBaseline?: {
+        superseded: number;
+    };
+    planIds: string[];
+    usage: {
+        calls: number;
+        promptTokens: number;
+        completionTokens: number;
+        retries: number;
+        truncations: number;
+    };
+    repairs: {
+        hallucinatedMembers: number;
+        duplicateMembers: number;
+        nonIntegerMembers: number;
+        emptyGroups: number;
+        oversizeGroups: number;
+    };
+    writeFailures: Array<{
+        key: string;
+        members: number;
+        reason: string | null;
+    }>;
+    residue?: Array<{
+        name: string;
+        targets: number;
+    }>;
+    /** The next moment a snapshot can pass the hard throttle (resume scheduling hint). */
+    nextEligibleAt?: number;
+}
+/** Host read face: the scope's latest driver run row (pending = resumable; settled = audit). */
+export declare function readConsolidationDriverRun(controlDir: string, scope: string): ConsolidationDriverRunRow | undefined;
+/** Archive one mint (prompts + transcript verbatim) beside the run account. The name carries the
+ *  CLAIM (`attempt`): two invocations that raced onto one run each archive
+ *  under their own name, so a superseded worker can never overwrite the winning transcript — the
+ *  run row's `planArchive` (written under the attempt guard) names the one that counts. */
+export declare function distillerPlanArchiveName(runId: string, attempt: number): string;
+export declare function archiveDistillerPlan(controlDir: string, runId: string, plan: LlmConsolidationPlan, attempt?: number): string;
+/** The engine face this verb consumes — `MemoryEngine` satisfies it structurally.
+ *  (`readConsolidationPlanFoldEvidence` joined in design/376 slice ③, #436: the conservation
+ *  wall's terminal witness is member-level, so the face is REQUIRED — an engine without it could
+ *  only offer the store-delta counts an interleaved fold can numerically offset.) */
+export interface ConsolidationDriverEngine extends ConsolidationDriveEngine {
+    readConsolidationGate(scope: string): ConsolidationGateRow | undefined;
+    listConsolidationPlans(): ConsolidationPlanSummary[];
+    readConsolidationPlanFoldEvidence(planId: string): ConsolidationPlanFoldEvidence;
+    readConsolidationFoldState(scope: string): Promise<ConsolidationFoldState>;
+    readonly controlPlaneRoot: string;
+}
+export interface RunMemoryConsolidationOptions {
+    /** The explicit model seat (design/339 §1.1: the ENGINE holds none). Build one with
+     *  `openAiCompatChatSeat` or hand any JSON-only completion function. */
+    chat: DistillerChatFn;
+    /** The explicit model id, recorded into the run and the archive (alias spellings refuse). */
+    model: string;
+    /** Audit locator recorded into the archive when the seat is endpoint-shaped. */
+    baseUrl?: string;
+    /** The frozen prompt contract; default = the product v1 (dl-3 byte-identical). A different
+     *  version here is a deployment's explicit measured choice. */
+    contract?: LlmDistillerContract;
+    /** The PROTOCOL knobs — pass the same object the engine was constructed with
+     *  (`MemoryEngineOptions.consolidation`); the driver derives its throttle window and per-plan
+     *  caps from it. Defaults = the factory defaults. */
+    consolidation?: MemoryConsolidationOptions;
+    /** Abort the run after this many cycles in THIS call (the run row stays pending only on crash;
+     *  a reached bound settles `max_cycles`). Positive integer; default 64. */
+    maxCycles?: number;
+    /** R2 — the structural-repair budget over the mint's member references: the ratio of member
+     *  claims the sanitiser had to DROP (hallucinated + duplicate + non-integer) to all member
+     *  claims the model made. Above this, the plan does not represent the model's intent and the
+     *  run aborts with zero writes rather than committing a harness-repaired fold. In [0, 1];
+     *  default 0.10. (Empty groups are the same drops counted at group grain; oversize groups are
+     *  not repairs — they ride on, named, and the schedule reports them infeasible. Format repairs
+     *  and retries are disclosed separately and bounded by the contract's own retry count.) */
+    mintRepairBudget?: number;
+    /** The run's force credential; defaults to a minted id. A RESUMED run keeps its original. */
+    requestId?: string;
+    /** Host seams for the throttle waits (tests and hosts with their own clocks). */
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    onProgress?: Parameters<typeof mintLlmConsolidationPlan>[0]["onProgress"];
+}
+export interface ConsolidationRunReceipt {
+    runId: string;
+    scope: string;
+    /** Whether this call CONTINUED a pending run (no new mint) instead of starting one. */
+    resumed: boolean;
+    outcome: ConsolidationRunStopReason;
+    converged: boolean;
+    stopDetail?: string;
+    /** This call's cycles (store-delta accounted); `cyclesDone` is the run total across resumes. */
+    cycles: ConsolidationDriveCycleRow[];
+    cyclesDone: number;
+    productsCommitted: number;
+    entriesSuperseded: number;
+    planIds: string[];
+    model: string;
+    contractVersion: string;
+    usage: ConsolidationDriverRunRow["usage"];
+    repairs: ConsolidationDriverRunRow["repairs"];
+    writeFailures: ConsolidationDriverRunRow["writeFailures"];
+    residue: Array<{
+        name: string;
+        targets: number;
+    }>;
+    planArchive?: string;
+    /** Advisory notices minted for this run (the `_incomplete` disclosure when not converged). */
+    notices: EngineNotice[];
+    /** A failed announcement enqueue is disclosed, never allowed to fail the settled run. */
+    announceFailures?: string[];
+}
+/**
+ * Run (or RESUME) one scope's consolidation as a persistent multi-cycle job. See the module note
+ * for the shape; the per-refusal behavior implements the design/376 §1.2 failure table:
+ *
+ *  - `_disabled` / a corrupt gate / an unreadable governance account BEFORE any commit: the coded
+ *    error is rethrown (a configuration/store fault the host must repair — a pending run row, if
+ *    one exists, stays resumable after the repair);
+ *  - `_gated` (time/session gate): retried under the run's force requestId — the run-level force
+ *    the design names; the FORCED audit line is engine-deduplicated to once per run;
+ *  - `_gated` (hard throttle): the driver WAITS the window out (`min(minRunIntervalMs, 60s)`) and
+ *    continues — a throttled cycle is scheduling, not a terminal;
+ *  - `_busy`: never a blind snapshot retry (the seat refuses snapshots too — a blind loop spins
+ *    forever): `reconcileConsolidation` first; a conflict/corrupt plan parks the run for the host
+ *    valve; a live competing worker is waited out briefly, then reported;
+ *  - model failures / a mint over the repair budget: the run settles `driver_failed` with ZERO
+ *    writes — the mint sits between snapshot and commit, so no seat was taken, `lastRunAt` never
+ *    moved and the time gate is not burned (the failure is free to retry);
+ *  - a conflict plan mid-run parks (`parked`); fuse residue and the cycle bound settle
+ *    `fuse_residue` / `max_cycles` with the residue named — the next run's FULL snapshot
+ *    re-distills the shrunken library (cross-run = re-mint; in-run = plan cache).
+ */
+export declare function runMemoryConsolidationDriver(engine: ConsolidationDriverEngine, scope: string, opts: RunMemoryConsolidationOptions): Promise<ConsolidationRunReceipt>;

package/dist/core/memory-engine/consolidation-driver.js

@@ -0,0 +1,427 @@
+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 { CONSOLIDATION_FORCE_THROTTLE_FLOOR_MS, screenConsolidationOptions, supersessionFuseCeiling, } from "./consolidation.js";
+import { memoryConsolidationIncompleteNotice } from "./engine.js";
+import { CONSOLIDATION_DRIVE_ABORT, CONSOLIDATION_SNAPSHOT_PARKED, MEMORY_DISTILLER_CONTRACT_V1, driveConsolidationToFixpoint, isAliasModelId, llmPlanDistiller, mintLlmConsolidationPlan, } 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;
+}
+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;
+    }
+}
+const codeOf = (err) => {
+    const c = err?.code;
+    return typeof c === "string" ? c : undefined;
+};
+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 : new Error(String(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;
+    const parkedSeat = await recoverSeat(engine, scope, { sleep, windowMs: throttleWindowMs });
+    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(err instanceof Error ? err.message : String(err));
+        }
+    };
+    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);
+        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);
+            announce([notice.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.planArchive !== undefined ? { planArchive: run.planArchive } : {}),
+            notices,
+            ...(announceFailures.length > 0 ? { announceFailures: [...announceFailures] } : {}),
+        };
+    };
+    if (parkedSeat !== undefined) {
+        return settle("parked", undefined, parkedSeat);
+    }
+    let staleResidue = [];
+    let staleResidueMemberIds = new Set();
+    const distill = async (candidates, snapshot, s) => {
+        if (run.planCache === undefined) {
+            let minted;
+            try {
+                minted = await mintLlmConsolidationPlan({
+                    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;
+                throw new DriverMintFailure(`the model seat failed during the mint: ${err instanceof Error ? err.message : String(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) {
+                throw new DriverMintFailure(minted.reason);
+            }
+            const plan = minted.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})`);
+            }
+            run.planArchive = distillerPlanArchiveName(run.runId, run.attempt);
+            run.planCache = { maxInputsPerProduct: plan.maxInputsPerProduct, products: plan.products };
+            writeDriverRun(controlDir, run);
+            archiveDistillerPlan(controlDir, run.runId, plan, run.attempt);
+        }
+        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 });
+                    if (parked !== undefined) {
+                        const e = new Error(parked);
+                        e[CONSOLIDATION_SNAPSHOT_PARKED] = true;
+                        throw e;
+                    }
+                    continue;
+                }
+                throw err;
+            }
+        }
+    };
+    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,
+            onCycle: (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);
+        }
+        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 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 }) {
+    await engine.reconcileConsolidation(scope);
+    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);
+    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;
+}