@sema-agent/core 5.57.0 → 5.58.0

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

@@ -0,0 +1,378 @@
+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 = [];
+    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);
+        }
+        staleResidue = (run.planCache?.products ?? []).flatMap((p) => {
+            const offered = new Map();
+            for (const c of candidates)
+                if (typeof c?.entry?.id === "string")
+                    offered.set(c.entry.id, c.entry.rev);
+            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;
+            return stale || vanished || unanchored ? [{ 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 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 (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");
+}
+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;
+}

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

@@ -126,7 +126,7 @@ export declare const CONSOLIDATION_FORCE_THROTTLE_FLOOR_MS = 60000;
 /** The bounded distinct-session ring (§2.3 sessionsSince dedup). */
 export declare const CONSOLIDATION_SESSION_RING_MAX = 64;
 /**
- * codex r2 — the seat's FREEZE GRACE: reconcile's orphan-release arm treats a seat whose plan file
+ * the seat's FREEZE GRACE: reconcile's orphan-release arm treats a seat whose plan file
  * is absent as crashed ONLY once the claim is at least this old. Calibration: the freeze between
  * the seat CAS and the plan file's durable write is committed READS only (headers + a bounded
  * getByIds) — seconds on any healthy store; ten minutes is orders of magnitude past it, while a
@@ -177,13 +177,23 @@ export interface ConsolidationGateRow {
     /** The plan-seat mutex: the one non-terminal (or conflict-parked) plan of this scope. */
     openPlanId?: string;
     /** When the seat was claimed (ms epoch) — the reconcile orphan-release arm's staleness anchor
-     *  (codex r2: a freeze legitimately computes for a while between the seat CAS and the plan
+     *  (a freeze legitimately computes for a while between the seat CAS and the plan
      *  file's durable write; an absent file alone must never read as a crash). */
     seatClaimedAt?: number;
     /** §1.4.5 collapse-fuse baseline (last observed active-set size). */
     activeSetBaseline?: number;
     /** Once-per-crossing edge for the recommendation notice. */
     lastRecommendedAt?: number;
+    /** The last force requestId whose FORCED announcement was enqueued (additive; design/376 §1.1-4):
+     *  a RUN-scoped force carries ONE requestId across every cycle of a multi-cycle run, and the
+     *  audit announcement is deduplicated on it — one disclosure per run, never one per cycle (a
+     *  cold start would otherwise flood the next session's injection face with a dozen identical
+     *  lines). A NEW requestId re-arms the disclosure. The dedup is the ONLY record: this row keeps
+     *  just the LAST id (no history structure exists — the gate row is mutated in place, the
+     *  announcement queue is drained destructively, and plan files do not mark forced-ness), so
+     *  per-force facts beyond the one announcement are not persisted, and a caller that reuses a
+     *  fixed requestId across runs keeps the disclosure silent for as long as it does. */
+    lastForcedRequestId?: string;
     /** Run watermark: increments on every completed/discarded settlement (the stale-proposal gate). */
     epoch: number;
     /** §1.2-1 — the last COMPLETED run's full-eligible-set fingerprint (id → committed rev):
@@ -375,4 +385,38 @@ export declare class ConsolidationRefusedError extends Error {
 }
 /** A NotePatch list for one frozen product (the §1.3 add-only arm's one spelling). */
 export declare function productAddPatch(product: MemoryEntry): NotePatch;
+/**
+ * Why a driver run stopped — ONE closed set shared verbatim by the run receipt and the
+ * `memory.consolidation_incomplete` notice (two vocabularies for the same fact would let an
+ * operator-facing channel and the host-facing receipt drift). Non-`converged` values mark a
+ * library in a PARTIAL fold — a transitional state the readings show is worse than unfolded, so
+ * it must never pass silently:
+ *  - `converged`      — nothing left to fold (the only completed-run value; includes the
+ *                       empty-plan no-op: a model that proposes nothing commits nothing);
+ *  - `fuse_residue`   — the supersession fuse admits no remaining product; the residue is named
+ *                       and the next run's full snapshot re-distills the shrunken library;
+ *  - `max_cycles`     — the cycle bound elapsed before a fixpoint;
+ *  - `parked`         — a plan settled conflict (or a corrupt plan holds the seat); the host
+ *                       valve `resolveConsolidationPlan` is the only way forward;
+ *  - `refused`        — an engine verb refused and the drive could not continue this run;
+ *  - `driver_failed`  — the DRIVER half could not complete. Two grains, one verdict: a failed
+ *                       MINT (model unreachable/unreadable/over the repair budget) settles with
+ *                       zero writes, zero seat and an unburned time gate; a run whose surviving
+ *                       plan reached its fixpoint while the driver's own half left groups
+ *                       unfolded (writing-pass failures, or products dropped stale against
+ *                       inputs edited mid-run) settles here TOO — committed cycles stand
+ *                       (add-only, no rollback), the residue is named, and a fresh run re-mints
+ *                       over the current bytes. The clean `converged` label never covers a
+ *                       driver-side residue.
+ * Extending this set is a consumer-visible closed-set expansion (release-note duty: every
+ * downstream that pinned the enumeration becomes a named party).
+ *
+ * The type DERIVES from the array (never `satisfies` beside it): the array exists precisely for
+ * downstream enumeration, and two independent declarations would let a new union arm skip the
+ * array with no compile error — the derived form makes an edit to either side a type error at
+ * the other.
+ */
+export declare const CONSOLIDATION_RUN_STOP_REASONS: readonly ["converged", "fuse_residue", "max_cycles", "parked", "refused", "driver_failed"];
+/** See the doc on {@link CONSOLIDATION_RUN_STOP_REASONS} — the single source this derives from. */
+export type ConsolidationRunStopReason = (typeof CONSOLIDATION_RUN_STOP_REASONS)[number];
 export {};

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

@@ -340,3 +340,4 @@ export class ConsolidationRefusedError extends Error {
 export function productAddPatch(product) {
     return { op: "add", id: product.id, entry: product, guard: "absent" };
 }
+export const CONSOLIDATION_RUN_STOP_REASONS = ["converged", "fuse_residue", "max_cycles", "parked", "refused", "driver_failed"];

package/dist/core/memory-engine/data-plane.d.ts

@@ -4,7 +4,7 @@ import type { HarvestRejection, MemoryBackend, MemoryEntry, NotePatch, PatchRepo
 export declare const REMOTE_HARVEST_PER_FILE_BYTES: number;
 /** Missing-file ratio above which the harvest refuses wholesale (engine MASS_DELETION_FUSE_RATIO). */
 export declare const REMOTE_MASS_DELETION_FUSE_RATIO = 0.5;
-/** File-count cap per harvest (host DEFAULT_MAX_MEMORY_FILES parity — codex H10). */
+/** File-count cap per harvest (host DEFAULT_MAX_MEMORY_FILES parity). */
 export declare const REMOTE_HARVEST_MAX_FILES = 500;
 /** Max DIRECTORY nesting depth below the memory root (host DEFAULT_MAX_ENTRY_DEPTH parity — the
  *  host's `scanEntryFiles` walks a subdir only while `depth + 1 <= maxDepth`, so it counts directory