@sema-agent/core 5.53.0 → 5.55.0

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

@@ -0,0 +1,342 @@
+import { existsSync, readdirSync, renameSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteFileSync, lockedStrictUpdate, readStrictSidecar, ControlPlaneCorruptError, ensureDirExists } from "./layout.js";
+export function deriveSupersededSet(headers, opts = {}) {
+    const byId = new Map();
+    for (const h of headers)
+        byId.set(h.id, h);
+    const out = new Map();
+    for (const h of headers) {
+        const d = h.distilled;
+        if (d === undefined || d.supersedes.length === 0)
+            continue;
+        if (opts.excluded?.(h.id) === true)
+            continue;
+        if (h.rev !== d.carrierRev)
+            continue;
+        for (const edge of d.supersedes) {
+            const target = byId.get(edge.id);
+            if (target === undefined)
+                continue;
+            if (target.scope !== h.scope)
+                continue;
+            if (target.rev !== edge.rev)
+                continue;
+            if (!out.has(edge.id))
+                out.set(edge.id, h.id);
+        }
+    }
+    return out;
+}
+export function memorySupersededNote(carrierId) {
+    return `note: a newer consolidated entry supersedes this one — memory entry ${carrierId} carries the current form; this entry remains readable as evidence.`;
+}
+export const MEMORY_SEARCH_SUPERSEDED_TAG = "[superseded]";
+export const CONSOLIDATION_DEFAULTS = {
+    supersedeRatioCap: 0.25,
+    supersedeAbsoluteFloor: 4,
+    maxProductsPerRun: 64,
+    maxInputsPerProduct: 32,
+    maxDirectedPatchesPerPlan: 32,
+    minRunIntervalMs: 24 * 60 * 60 * 1000,
+    minSessionsBetweenRuns: 5,
+};
+export const CONSOLIDATION_FORCE_THROTTLE_FLOOR_MS = 60_000;
+export const CONSOLIDATION_SESSION_RING_MAX = 64;
+export const CONSOLIDATION_SEAT_FREEZE_GRACE_MS = 10 * 60_000;
+function coded(message, code) {
+    const e = new Error(message);
+    e.code = code;
+    return e;
+}
+export function screenConsolidationOptions(raw, provenance) {
+    if (provenance === "off") {
+        throw coded(`MemoryEngineOptions.consolidation cannot be enabled under provenance: "off" — the consolidation fold law must be able to mint origin markers (a marked input's product would otherwise commit unmarked). Enable provenance "carry" or remove the consolidation options.`, "config.memory_consolidation_provenance_off");
+    }
+    const num = (name, v, check, want) => {
+        if (v === undefined)
+            return CONSOLIDATION_DEFAULTS[name];
+        if (typeof v !== "number" || !Number.isFinite(v) || !check(v)) {
+            const got = typeof v === "number" ? String(v) : v === null ? "null" : typeof v;
+            throw coded(`MemoryEngineOptions.consolidation.${name} must be ${want} when present (got ${got}) — an unevaluable knob is refused loudly, never folded to the default.`, "config.memory_consolidation");
+        }
+        return v;
+    };
+    const screened = {
+        supersedeRatioCap: num("supersedeRatioCap", raw.supersedeRatioCap, (n) => n > 0 && n <= 1, "a number in (0, 1]"),
+        supersedeAbsoluteFloor: num("supersedeAbsoluteFloor", raw.supersedeAbsoluteFloor, (n) => Number.isInteger(n) && n >= 0, "a non-negative integer"),
+        maxProductsPerRun: num("maxProductsPerRun", raw.maxProductsPerRun, (n) => Number.isInteger(n) && n >= 1, "a positive integer"),
+        maxInputsPerProduct: num("maxInputsPerProduct", raw.maxInputsPerProduct, (n) => Number.isInteger(n) && n >= 1, "a positive integer"),
+        maxDirectedPatchesPerPlan: num("maxDirectedPatchesPerPlan", raw.maxDirectedPatchesPerPlan, (n) => Number.isInteger(n) && n >= 1, "a positive integer"),
+        minRunIntervalMs: num("minRunIntervalMs", raw.minRunIntervalMs, (n) => n > 0, "a positive number of milliseconds"),
+        minSessionsBetweenRuns: num("minSessionsBetweenRuns", raw.minSessionsBetweenRuns, (n) => Number.isInteger(n) && n >= 0, "a non-negative integer"),
+        multiNode: raw.multiNode === true,
+        ...(raw.lease !== undefined ? { lease: raw.lease } : {}),
+    };
+    if (raw.multiNode !== undefined && raw.multiNode !== true) {
+        throw coded(`MemoryEngineOptions.consolidation.multiNode must be exactly true when present (a posture declaration, not a boolean knob).`, "config.memory_consolidation");
+    }
+    if (screened.multiNode && screened.lease === undefined) {
+        throw coded(`MemoryEngineOptions.consolidation.multiNode declared without a lease seat — a multi-node deployment MUST inject the host's global lease (the local plan-seat CAS does not reach across nodes). Inject consolidation.lease or remove the multiNode declaration.`, "config.memory_consolidation_lease_required");
+    }
+    if (raw.lease !== undefined && typeof raw.lease.acquire !== "function") {
+        throw coded(`MemoryEngineOptions.consolidation.lease.acquire must be a function.`, "config.memory_consolidation");
+    }
+    return screened;
+}
+export function supersessionFuseCeiling(activeSetSize, opts) {
+    if (activeSetSize <= 1)
+        return 0;
+    return Math.min(activeSetSize - 1, Math.max(opts.supersedeAbsoluteFloor, Math.floor(opts.supersedeRatioCap * activeSetSize)));
+}
+export function consolidationTypeEligible(type) {
+    return type !== "episodic" && type !== "procedural";
+}
+export const CONSOLIDATION_GATE_FILE = "consolidation-gate.json";
+export const CONSOLIDATION_PLANS_DIR = "consolidation-plans";
+export const CONSOLIDATION_INTENTS_FILE = "consolidation-intents.json";
+function coerceGateFile(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 gate store has an unrecognized shape (fail-closed sidecar)");
+    }
+    const scopes = raw.scopes;
+    const out = { v: 1, scopes: {} };
+    for (const [scope, rowRaw] of Object.entries(scopes)) {
+        if (typeof rowRaw !== "object" || rowRaw === null)
+            throw new ControlPlaneCorruptError(`memory consolidation gate store row for scope ${JSON.stringify(scope)} is malformed (fail-closed sidecar)`);
+        const r = rowRaw;
+        const sessions = r["sessions"];
+        if (typeof sessions !== "object" ||
+            sessions === null ||
+            typeof sessions.count !== "number" ||
+            !Array.isArray(sessions.ring ?? []) ||
+            (sessions.ring !== undefined && !sessions.ring.every((s) => typeof s === "string")) ||
+            typeof r["epoch"] !== "number" ||
+            !Number.isInteger(r["epoch"])) {
+            throw new ControlPlaneCorruptError(`memory consolidation gate store row for scope ${JSON.stringify(scope)} is malformed (fail-closed sidecar)`);
+        }
+        out.scopes[scope] = rowRaw;
+    }
+    return out;
+}
+function freshRow() {
+    return { sessions: { count: 0, ring: [] }, epoch: 0 };
+}
+export function updateConsolidationGate(controlDir, fn) {
+    return lockedStrictUpdate(controlDir, CONSOLIDATION_GATE_FILE, "memory consolidation gate store", coerceGateFile, fn);
+}
+export function readConsolidationGateFile(controlDir) {
+    return coerceGateFile(readStrictSidecar(controlDir, CONSOLIDATION_GATE_FILE, "memory consolidation gate store"));
+}
+export function consolidationGateFileExists(controlDir) {
+    return existsSync(join(controlDir, CONSOLIDATION_GATE_FILE));
+}
+export function recordConsolidationSession(controlDir, scope, sessionId, opts, now) {
+    return updateConsolidationGate(controlDir, (file) => {
+        const row = file.scopes[scope] ?? freshRow();
+        if (row.sessions.ring.includes(sessionId)) {
+            return { result: { recommended: false, sessionsSince: row.sessions.count } };
+        }
+        row.sessions.count += 1;
+        row.sessions.ring.push(sessionId);
+        if (row.sessions.ring.length > CONSOLIDATION_SESSION_RING_MAX)
+            row.sessions.ring.splice(0, row.sessions.ring.length - CONSOLIDATION_SESSION_RING_MAX);
+        const at = now();
+        const timeOpen = row.lastRunAt === undefined || at - row.lastRunAt >= opts.minRunIntervalMs;
+        const sessionsOpen = row.sessions.count >= opts.minSessionsBetweenRuns;
+        const edgeArmed = row.lastRecommendedAt === undefined || (row.lastRunAt !== undefined && row.lastRecommendedAt <= row.lastRunAt);
+        let recommended = false;
+        if (timeOpen && sessionsOpen && edgeArmed) {
+            recommended = true;
+            row.lastRecommendedAt = at;
+        }
+        file.scopes[scope] = row;
+        return { next: file, result: { recommended, sessionsSince: row.sessions.count } };
+    });
+}
+export function recordActiveSetBaseline(controlDir, scope, size, ratioCap, _now) {
+    return updateConsolidationGate(controlDir, (file) => {
+        const row = file.scopes[scope] ?? freshRow();
+        const prev = row.activeSetBaseline;
+        row.activeSetBaseline = size;
+        file.scopes[scope] = row;
+        const collapsed = prev !== undefined && prev > 0 && size < prev && (prev - size) / prev > ratioCap ? { from: prev, to: size } : undefined;
+        return { next: file, result: collapsed !== undefined ? { collapsed } : {} };
+    });
+}
+export function isValidConsolidationPlanId(value) {
+    return /^[A-Za-z0-9][A-Za-z0-9_-]{7,63}$/.test(value);
+}
+function planPath(controlDir, planId) {
+    if (!isValidConsolidationPlanId(planId)) {
+        throw new ControlPlaneCorruptError(`consolidation plan id ${JSON.stringify(planId.slice(0, 80))} fails the id grammar — a plan id doubles as a control-plane file name and must never be joined as a path`);
+    }
+    return join(controlDir, CONSOLIDATION_PLANS_DIR, `${planId}.json`);
+}
+export function writeConsolidationPlan(controlDir, plan) {
+    ensureDirExists(join(controlDir, CONSOLIDATION_PLANS_DIR));
+    atomicWriteFileSync(planPath(controlDir, plan.planId), `${JSON.stringify(plan, null, 2)}\n`);
+}
+const CONSOLIDATION_PLAN_STATES = new Set(["open", "applying", "completed", "conflict", "discarded"]);
+const CONSOLIDATION_DIRECTED_STATES = new Set(["pending", "applied", "satisfied", "conflict"]);
+const CONSOLIDATION_INTENT_STATES = new Set(["pending", "settled", "abandoned"]);
+function planShapeInvalid(raw, planId) {
+    if (typeof raw !== "object" || raw === null)
+        return "not an object";
+    const p = raw;
+    if (p["v"] !== 1)
+        return "unrecognized version";
+    if (p["planId"] !== planId)
+        return "planId mismatch";
+    if (typeof p["scope"] !== "string" || p["scope"].length === 0)
+        return "missing scope";
+    if (typeof p["requestId"] !== "string")
+        return "missing requestId";
+    if (typeof p["createdAt"] !== "number")
+        return "missing createdAt";
+    if (typeof p["visibleMarked"] !== "boolean")
+        return "missing visibleMarked";
+    if (typeof p["state"] !== "string" || !CONSOLIDATION_PLAN_STATES.has(p["state"]))
+        return "unrecognized state";
+    if (!Array.isArray(p["products"]) || !p["products"].every((e) => typeof e === "object" && e !== null && typeof e.id === "string"))
+        return "malformed products";
+    const productIds = p["products"].map((e) => e.id);
+    const states = p["productStates"];
+    if (typeof states !== "object" || states === null)
+        return "malformed productStates";
+    const stateKeys = Object.keys(states);
+    if (stateKeys.length !== productIds.length || !productIds.every((id) => states[id] === "pending" || states[id] === "applied" || states[id] === "conflict")) {
+        return "productStates do not cover the product set one-to-one";
+    }
+    if (!Array.isArray(p["directed"]) ||
+        !p["directed"].every((d0) => {
+            if (typeof d0 !== "object" || d0 === null)
+                return false;
+            const d = d0;
+            if (typeof d["id"] !== "string" || typeof d["intentRequestId"] !== "string" || typeof d["baseRev"] !== "string")
+                return false;
+            if (d["op"] !== "update" && d["op"] !== "delete")
+                return false;
+            if (typeof d["state"] !== "string" || !CONSOLIDATION_DIRECTED_STATES.has(d["state"]))
+                return false;
+            if (d["op"] === "update") {
+                if (typeof d["plannedPostRev"] !== "string")
+                    return false;
+                if (d["state"] === "pending" && (typeof d["entry"] !== "object" || d["entry"] === null))
+                    return false;
+            }
+            else if (d["entry"] !== undefined)
+                return false;
+            return true;
+        })) {
+        return "malformed directed set";
+    }
+    const intentIds = new Set();
+    if (!Array.isArray(p["intents"]) ||
+        !p["intents"].every((i0) => {
+            if (typeof i0 !== "object" || i0 === null)
+                return false;
+            const i = i0;
+            if (typeof i["requestId"] !== "string")
+                return false;
+            intentIds.add(i["requestId"]);
+            return typeof i["state"] === "string" && CONSOLIDATION_INTENT_STATES.has(i["state"]);
+        })) {
+        return "malformed intents";
+    }
+    if (!p["directed"].every((d) => intentIds.has(d.intentRequestId)))
+        return "directed patch references an undeclared intent";
+    if (!Array.isArray(p["audit"]))
+        return "malformed audit trail";
+    return undefined;
+}
+export function readConsolidationPlan(controlDir, planId) {
+    if (!isValidConsolidationPlanId(planId))
+        return { state: "absent" };
+    const path = planPath(controlDir, planId);
+    if (!existsSync(path))
+        return { state: "absent" };
+    try {
+        const raw = readStrictSidecar(join(controlDir, CONSOLIDATION_PLANS_DIR), `${planId}.json`, "memory consolidation plan");
+        const bad = planShapeInvalid(raw, planId);
+        if (bad !== undefined)
+            return { state: "corrupt", detail: bad };
+        return { state: "ok", plan: raw };
+    }
+    catch (err) {
+        return { state: "corrupt", detail: err instanceof Error ? err.message : String(err) };
+    }
+}
+export function listConsolidationPlanIds(controlDir) {
+    const dir = join(controlDir, CONSOLIDATION_PLANS_DIR);
+    if (!existsSync(dir))
+        return [];
+    try {
+        return readdirSync(dir)
+            .filter((f) => f.endsWith(".json") && !f.endsWith(".corrupt.json"))
+            .map((f) => f.slice(0, -".json".length))
+            .filter((id) => isValidConsolidationPlanId(id));
+    }
+    catch {
+        return [];
+    }
+}
+export function quarantineCorruptPlan(controlDir, planId) {
+    if (!isValidConsolidationPlanId(planId))
+        return undefined;
+    const from = planPath(controlDir, planId);
+    if (!existsSync(from))
+        return undefined;
+    const name = `${planId}.corrupt.json`;
+    try {
+        renameSync(from, join(controlDir, CONSOLIDATION_PLANS_DIR, name));
+        return name;
+    }
+    catch {
+        return undefined;
+    }
+}
+function coerceIntentFile(raw) {
+    if (raw === undefined)
+        return { v: 1, rows: {} };
+    if (typeof raw !== "object" || raw === null || raw.v !== 1 || typeof raw.rows !== "object" || raw.rows === null) {
+        throw new ControlPlaneCorruptError("memory consolidation intent-credential account has an unrecognized shape (fail-closed sidecar)");
+    }
+    return raw;
+}
+export function recordIntentCredentials(controlDir, rows) {
+    if (rows.length === 0)
+        return [];
+    return lockedStrictUpdate(controlDir, CONSOLIDATION_INTENTS_FILE, "memory consolidation intent-credential account", coerceIntentFile, (file) => {
+        const written = [];
+        for (const row of rows) {
+            if (file.rows[row.requestId] !== undefined)
+                continue;
+            file.rows[row.requestId] = row;
+            written.push(row.requestId);
+        }
+        return written.length > 0 ? { next: file, result: written } : { result: written };
+    });
+}
+export function readIntentCredentials(controlDir) {
+    const raw = readStrictSidecar(controlDir, CONSOLIDATION_INTENTS_FILE, "memory consolidation intent-credential account");
+    return coerceIntentFile(raw).rows;
+}
+export function deriveProductSlug(name, fallback) {
+    const base = (name ?? "").toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[-.]+|[-.]+$/g, "");
+    return base.length > 0 ? base : fallback;
+}
+export class ConsolidationRefusedError extends Error {
+    code;
+    reasons;
+    constructor(code, message, reasons = []) {
+        super(reasons.length > 0 ? `${message}\n${reasons.map((r) => `  - ${r}`).join("\n")}` : message);
+        this.code = code;
+        this.reasons = reasons;
+    }
+}
+export function productAddPatch(product) {
+    return { op: "add", id: product.id, entry: product, guard: "absent" };
+}

package/dist/core/memory-engine/dual-root.js

@@ -75,6 +75,9 @@ export function mergeHarvestReports(a, b) {
     const qf = [...(a.quarantineFailures ?? []), ...(b.quarantineFailures ?? [])];
     if (qf.length > 0)
         merged.quarantineFailures = qf;
+    const rec = a.consolidationRecommended ?? b.consolidationRecommended;
+    if (rec !== undefined)
+        merged.consolidationRecommended = rec;
     const ac = a.containment;
     const bc = b.containment;
     if (ac !== undefined || bc !== undefined) {

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

@@ -1,10 +1,11 @@
 import type { EngineNotice } from "../types.js";
+import { type ConsolidationGateRow, type ConsolidationPlanFile, type ConsolidationProposal, type MemoryConsolidationOptions } from "./consolidation.js";
 import { foreignDanglingSessionAccounts, type EffectiveSettlement, type HoldRow } from "./delegation-settlement.js";
 import { type OriginClearanceRow } from "./origin-clearance.js";
 import { type CommittedBinding, type EraseMemoryEntriesInput, type MemoryErasureAttestation, type TransferEvidence } from "./file-backend.js";
 import { type MemoryExportBundle, type MemoryImportReport } from "./export-bundle.js";
 import { type ChallengeAssignment, type ChallengeEvent, type ControlPlaneRebuildReceipt, type StrictControlPlaneLedger, type ChallengedHistoryRow, type LineagePendingTxn, type LineagePromotion, type MemoryPartitionIncidentSink, type RetrievedAccountRow, type SessionPollutionMarkOutcome, type SessionPollutionRecord } from "./layout.js";
-import type { HarvestReport, MemoryAnnouncement, MemoryBackend, MemoryEntryOrigin, MemorySessionHandle, ScanFinding } from "./types.js";
+import type { HarvestReport, MemoryAnnouncement, MemoryBackend, MemoryEntry, MemoryEntryOrigin, MemorySessionHandle, ScanFinding } from "./types.js";
 /**
  * The CC `# Memory` instruction section — VERBATIM from the live capture
  * (bench/cc-parity-toolsuite/reminders/live-capture-main-session-2026-07-08.md §12), with the
@@ -100,10 +101,12 @@ export declare const MEMORY_ANNOUNCEMENT_READONLY_CODA = "The memory store itsel
  * false` — where the runner's write gate also refuses the file channel, keeping the engine-refusal
  * sentence true), and for a write-less roster the persistence inference cannot vouch for. A merely
  * Write-less roster does NOT qualify — other tools can still write the root. Name-free by
- * construction (#181 class — it names no tool), and NOT part of the CC-verbatim capture: CC has no
- * read-only memory layering, so there is nothing to capture; the section is sema-authored.
+ * construction (#181 class — it names no tool). The closing sentence is CC-verbatim (2.1.223
+ * read-only memory arm — the same sentence CC uses for both its whole-memory and team-memory
+ * read-only states); the state sentence above it is sema-authored context (CC's surrounding prose
+ * describes its own file layout, which does not transfer here).
  */
-export declare const MEMORY_READONLY_NOTICE = "# Memory\n\nYou have READ-ONLY access to persistent memory in this session: stored notes are available below, but this session has no memory write channel \u2014 the engine will not accept writes into the memory store. If the user asks you to remember something for later, say plainly that you cannot save it in this session \u2014 never claim to have noted or remembered it.";
+export declare const MEMORY_READONLY_NOTICE = "# Memory\n\nYou have READ-ONLY access to persistent memory in this session: stored notes are available below, but this session has no memory write channel \u2014 the engine will not accept writes into the memory store. If the user asks you to remember something, explain that memory is read-only in this session.";
 /** CC index-injection parameters: MEMORY.md's first 200 lines / 25KB enter the prompt. */
 export declare const MEMORY_INDEX_MAX_LINES = 200;
 export declare const MEMORY_INDEX_MAX_BYTES: number;
@@ -201,6 +204,20 @@ export interface MemoryEngineOptions {
      * Absent ⇒ advisory-silent; neither a mount nor a harvest ever fails over this seat.
      */
     onIncident?: MemoryPartitionIncidentSink;
+    /**
+     * design/339 §6.1 — the v3 consolidation write protocol's master switch. ABSENT = OFF (the
+     * shipped default: continuous automatic consolidation degrading useful memory is the研究-backed
+     * failure mode, so the protocol only arms on an explicit host decision): the four consolidation
+     * verbs refuse loudly (`memory.consolidation_disabled`), the gate store writes nothing (no file
+     * is ever created), the recommendation seat never mints, and the control plane stays
+     * byte-identical to a pre-339 deployment (G1). PRESENT = enabled; every knob screens at
+     * construction (#123 bad-value loudness — see {@link import("./consolidation.js").screenConsolidationOptions}),
+     * `provenance: "off"` beside it refuses at construction (D-12a: the fold law must be able to
+     * mint), and `multiNode: true` without an injected lease refuses (D-13a). Note the READ-side
+     * active-set treatment (index rows / search filter / get disclosure) is NOT behind this switch —
+     * supersession edges are store-level data facts and take effect wherever they exist (D-4a).
+     */
+    consolidation?: MemoryConsolidationOptions;
 }
 /** What {@link MemoryEngine.inject} produces: the trusted CC-verbatim instruction section + the
  *  FENCED (untrusted-downgraded) derived index, and the combined block for the memory prompt slot. */
@@ -426,6 +443,103 @@ export declare function memoryHarvestQuarantinedNotice(input: {
  * identifiers, neutralized and length-capped before they ride the message or the detail.
  */
 export declare function memoryHoldNotices(report: HarvestReport, sessionId?: string): EngineNotice[];
+/** §6.3 B-4 — verb ②'s receipt. */
+export interface ConsolidationCommitReceipt {
+    planId: string;
+    state: "completed" | "conflict";
+    products: {
+        frozen: number;
+        applied: number;
+        conflicts: number;
+        refused: Array<{
+            index: number;
+            reason: string;
+        }>;
+    };
+    directed: {
+        frozen: number;
+        applied: number;
+        satisfied: number;
+        conflicts: number;
+    };
+    intents: {
+        settled: string[];
+        pending: string[];
+    };
+    foldedOrigin: boolean;
+    notices: EngineNotice[];
+}
+export interface ConsolidationReconcileReport {
+    replayed?: {
+        planId: string;
+        state: "completed" | "conflict";
+    };
+    releasedOrphanSeat?: string;
+    /** codex r2 — a seat whose plan file is absent but whose claim is YOUNGER than the freeze grace:
+     *  a live commit is (very likely) mid-freeze; reconcile leaves it alone and reports it here. */
+    seatInFlight?: string;
+    corruptPlan?: {
+        planId: string;
+        detail: string;
+    };
+    propagatedChallenges: string[];
+    sweepError?: string;
+}
+export interface ConsolidationResolveReceipt {
+    planId: string;
+    action: "discard" | "retry";
+    state: "discarded" | "completed" | "conflict";
+    custody?: string;
+    abandonedIntents?: string[];
+    retryPlanId?: string;
+    retryReceipt?: ConsolidationCommitReceipt;
+}
+export interface ConsolidationPlanSummary {
+    planId: string;
+    corrupt?: true;
+    scope?: string;
+    state?: ConsolidationPlanFile["state"];
+    createdAt?: number;
+    products?: number;
+    directed?: number;
+    intents?: number;
+}
+/** §2.2 — the recommendation notice, minted off the harvest report's advisory member (the runner's
+ *  hold-notice consumption point is its natural home). Undefined ⇔ this harvest crossed no edge. */
+export declare function memoryConsolidationRecommendedNotice(report: HarvestReport, sessionId?: string): EngineNotice | undefined;
+export declare function memoryConsolidationCommittedNotice(input: {
+    planId: string;
+    scope: string;
+    products: number;
+    superseded: number;
+    intents: number;
+}): EngineNotice;
+/** The CONFLICT parking notice. Two things it must not overstate:
+ *  - the CAUSE. A park is reached three ways: a concurrent write takes a target to a third state
+ *    (the CAS arm), the store declines a patch outright (an immutability guard, a malformed-patch
+ *    refusal), or the engine's own re-judgment parks a row before any patch is offered at all (a
+ *    retry whose target moved scope, vanished, or has no replayable terminal). A fixed label naming
+ *    only the first would report a race that never happened, and naming only the first two would
+ *    claim a store answer that was never asked for. The per-target reason is verbatim in the plan
+ *    file's audit rows for ALL THREE — the re-judgment writes its own rows precisely so this
+ *    sentence stays true.
+ *  - the EXTENT. A park is plan-wide but application is per-row: a batch answers applied and
+ *    conflicted siblings together, and the product batch runs before the directed one, so a parked
+ *    plan may well have committed some of its patches. "Nothing was overwritten" is true only of
+ *    the REFUSED targets, and `discard` rolls nothing back — an operator reading otherwise would
+ *    abandon a plan believing it had no effects. The counts live on the receipt (products/directed
+ *    applied vs conflicts); this notice stays ids-only and points at them. */
+export declare function memoryConsolidationConflictNotice(input: {
+    planId: string;
+    scope: string;
+}): EngineNotice;
+/** The refusal's notice dialect (the verb itself throws the coded {@link ConsolidationRefusedError};
+ *  a host converting the throw into its notice stream uses this one spelling). */
+export declare function memoryConsolidationRefusedNotice(input: {
+    code: string;
+    scope?: string;
+    reason?: string;
+}): EngineNotice;
 export declare class MemoryEngine {
     private readonly backend;
     private readonly memoryDir;
@@ -446,6 +560,8 @@ export declare class MemoryEngine {
     /** A backend-pinned directory (FileBackend zero-copy detection). */
     private readonly backendPinnedRoot?;
     constructor(opts: MemoryEngineOptions);
+    /** {@link MemoryEngineOptions.consolidation}, screened — undefined ⇔ the protocol is OFF. */
+    private readonly consolidation?;
     /**
      * The ONE delivery point for a failed announcement-queue operation (`memory.announce_failed`, ruled
      * 2026-08-03). Every enqueue/drain call site stays fail-OPEN — a broken queue must never fail a
@@ -763,6 +879,123 @@ export declare class MemoryEngine {
     /** Read face: the dangling foreign session-account rows a given session would classify residue
      *  against (host audit for the §3.6 valve). */
     readDanglingSessionAccounts(selfSessionId: string): ReturnType<typeof foreignDanglingSessionAccounts>;
+    /** The coded off-switch refusal every verb answers first (G1). */
+    private requireConsolidation;
+    /** Gate-store read with the strict fail-closed translation (F5: corrupt ⇒ verbs refuse coded;
+     *  read faces and harvests are untouched — they never come through here). */
+    private readConsolidationGateOrRefuse;
+    /** §1.7 — the lease check run before EVERY apply batch (fencing-token re-validation; the token
+     *  narrows a stale holder's overlap to a single batch — §1.2-4 names the in-batch residue).
+     *  Absent seat ⇒ single-machine deployment, the plan-seat CAS is the mutex. */
+    /** §1.7 — best-effort lease RELEASE at every verb exit (an outside pass's finding, adopted:
+     *  acquire without a paired release starved every later worker on explicit-release lease
+     *  implementations until expiry). Releasing beside an UNFINISHED durable plan is safe — the
+     *  plan replays under whichever holder next acquires, and the fencing re-check before each
+     *  batch keeps a stale holder to one batch. Failures die here (the lease is cost suppression,
+     *  never safety — a failed release converges at the lease's own expiry). */
+    private releaseConsolidationLease;
+    private consolidationLeaseCurrent;
+    /** §3.1 — the candidate-eligibility context, read once per snapshot/freeze pass off the
+     *  committed faces and governance accounts (write and read sides share this predicate). */
+    private consolidationEligibility;
+    /**
+     * §1.2-1 — verb ①: snapshot the candidate set (committed, side-effect-free read face), gate-
+     * checked (§2.2 案 c: mutex and the same-scope throttle floor are HARD; the time and session
+     * gates yield to `force` with a requestId audit). Increments are CHANGE-DRIVEN: the candidate
+     * set is the eligible entries that are new to — or moved rev against — the last completed run's
+     * fingerprint; a lost/absent fingerprint answers the full set (conservative). `full: true`
+     * requests the full set explicitly (a host's re-distillation choice).
+     */
+    snapshotConsolidationCandidates(scope: string, opts?: {
+        force?: {
+            requestId: string;
+        };
+        full?: boolean;
+    }): Promise<{
+        cycleToken: string;
+        watermark: {
+            epoch: number;
+            at: number;
+        };
+        candidates: Array<{
+            entry: MemoryEntry;
+            marked: boolean;
+        }>;
+    }>;
+    /**
+     * §1.2-2/§1.2-3 — verb ②: mechanical acceptance + plan FREEZE + apply-to-terminal. Structural
+     * violations (scan findings, out-of-snapshot attribution, caps, the instruction hard gate, the
+     * supersession fuse) refuse the WHOLE plan — zero partial freeze; per-product eligibility drift
+     * (an input's rev moved / an input got challenged between snapshot and freeze) refuses THAT
+     * product with a disclosed reason while the rest freeze (§1.2-2 冻结时资格复验).
+     */
+    commitConsolidationPlan(cycleToken: string, proposal: ConsolidationProposal, opts: {
+        requestId: string;
+    }): Promise<ConsolidationCommitReceipt>;
+    /** §1.2-2/§1.2-3 — the freeze: mechanical acceptance over the committed NOW + assembly of the
+     *  immutable plan workbook (engine-authored frontmatter: minted ids, folded origin, distilled
+     *  blocks with the carrierRev anchor; per-product rev pre-computed). */
+    private freezeConsolidationPlan;
+    /**
+     * §1.3/§1.5-2 — the apply-to-terminal leg (first run AND every replay: the plan is the ONLY
+     * input — no distillation ever re-runs). Idempotent by construction: product adds ride
+     * `guard: "absent"` over plan-frozen ids (an identical replay is a no-op), directed patches
+     * judge conflicts TERMINAL-STATE-wise (update: committed rev == plannedPostRev ⇒ satisfied;
+     * delete: absence ⇒ satisfied — this arm has no re-record leg, so acknowledging absence can
+     * revive nothing; attribution degrades to "unattributed" across the crash micro-window while
+     * the judgment never degrades, r2-4/G25).
+     */
+    private applyConsolidationPlan;
+    /** Terminal settlement: per-item terminals → the plan terminal, the credential write (§1.5-3:
+     *  ALL-satisfied only), the gate watermark/fingerprint/seat update and the announcements. */
+    private settleConsolidationPlan;
+    private consolidationReceipt;
+    /**
+     * §1.7/§1.8 — verb ③: idempotent replay/convergence. Replays the seated plan to terminal (a
+     * crash at ANY point converges — the plan is the only input), releases an orphan seat (a crash
+     * between seat and freeze left nothing to replay: the plan never returned to its caller), and
+     * runs the RETROACTIVE challenge propagation sweep (D-6a: committed products whose
+     * `distilled.inputs` name a currently-challenged id are challenged mechanically — the lineage
+     * travels with the entry, so products that arrived by sync/bundle propagate too, r1-4/G19).
+     */
+    reconcileConsolidation(scope: string): Promise<ConsolidationReconcileReport>;
+    /** The stale-claim orphan-seat release (extracted for the in-flight split above): crash between
+     *  seat and plan-file write — nothing frozen, nothing to replay — release the seat with an audit
+     *  line (the commit call never returned a planId to its caller). */
+    private releaseOrphanConsolidationSeat;
+    /** ---- D-6a retroactive propagation sweep (reconcile's second half) ---- */
+    private runConsolidationPropagationSweep;
+    /** The gate half of a terminal plan's settlement (idempotent, seat-guarded — reconcile's repair
+     *  arm for a crash between the plan-state write and the gate update). */
+    private settleGateForTerminalPlan;
+    /** The settlement fingerprint's FRESH eligibility predicate: (id, rev) stays in the map only
+     *  while it is committed at that rev, unchallenged and unsuperseded RIGHT NOW. Undefined ⇔ the
+     *  read failed — the caller drops the fingerprint (full candidates next round). */
+    private settleFingerprintFilter;
+    /**
+     * §1.5-3 — verb ④: the host valve over a parked/corrupt plan. `discard` = the intents settle
+     * ABANDONED explicitly (audited; never a silent drop — unfulfilled and given-up stay two
+     * distinguishable account facts, G24) and the seat releases; `retry` = the plan's unfulfilled
+     * intents re-judge NOW into a NEW plan (fresh freeze, fresh baseRevs — the ONE authorized
+     * re-judgment point) which applies immediately. Both audited by requestId.
+     */
+    resolveConsolidationPlan(planId: string, action: "discard" | "retry", opts: {
+        requestId: string;
+    }): Promise<ConsolidationResolveReceipt>;
+    /** Rebuild the directed patches for a retry: the ORIGINAL terminal intent (recovered from the
+     *  conflicted plan's frozen patch) re-judged against the committed now.
+     *
+     *  Some of those judgments settle a row as CONFLICT here, without ever offering a patch to the
+     *  store — the target moved out of the plan's scope, it vanished, or the frozen entry is not
+     *  replayable. Those rows get no backend answer, so they would otherwise reach the parked plan
+     *  with no per-target reason anywhere: `reasons` carries them out to the retry plan's audit, which
+     *  is where the conflict notice tells a host to look. */
+    private reconstructIntentsForRetry;
+    /** §6.2 — host read face: every plan's summary (audit enumeration, zero model surface). */
+    listConsolidationPlans(): ConsolidationPlanSummary[];
+    /** §6.2 — host read face: one scope's gate row (undefined when the store has no row — reading
+     *  never creates the file, so the OFF deployment stays byte-identical, G1). */
+    readConsolidationGate(scope: string): ConsolidationGateRow | undefined;
     /** The committed, side-effect-free audit read: the adoption-restricted committed view when the
      *  backend offers one (zero-copy File — ledger+shadow, no disk adoption), else the non-adopting
      *  retrieval view (copy-out File), else the backend itself (Pg/TiDB shapes — naturally committed