@sema-agent/core 5.54.0 → 5.55.0

package/dist/core/mcp.js

@@ -537,6 +537,82 @@ export async function mapContent(content, serverName, imageResizer) {
     }
     return out;
 }
+export const MCP_INVISIBLE_TEXT_RE = /[\p{Cf}\p{Co}\p{Cn}]/gu;
+const MCP_SANITIZE_MAX_ROUNDS = 10;
+function sanitizeMcpModelFacingText(text) {
+    let out = text;
+    for (let round = 0; round < MCP_SANITIZE_MAX_ROUNDS; round++) {
+        const next = out.normalize("NFKC").replace(MCP_INVISIBLE_TEXT_RE, "");
+        if (next === out)
+            return out;
+        out = next;
+    }
+    return out.replace(MCP_INVISIBLE_TEXT_RE, "");
+}
+const MCP_SCHEMA_PROSE_KEYS = new Set(["description", "title", "$comment"]);
+const MCP_SCHEMA_CHILD_SEAT = new Map([
+    ...["properties", "definitions", "$defs", "dependentSchemas"].map((k) => [k, "properties"]),
+    ...["patternProperties"].map((k) => [k, "schemaMap"]),
+    ...["items", "prefixItems", "additionalItems", "additionalProperties", "unevaluatedItems", "unevaluatedProperties", "contains", "propertyNames", "contentSchema", "not", "if", "then", "else", "allOf", "anyOf", "oneOf"].map((k) => [k, "schema"]),
+    ...["required", "dependentRequired", "dependencies", "$ref", "$dynamicRef", "$id", "$anchor", "$dynamicAnchor"].map((k) => [k, "nameRefs"]),
+]);
+class McpPayloadKeyCollision extends Error {
+}
+function sanitizeMcpSchemaNameRefs(value) {
+    if (typeof value === "string")
+        return sanitizeMcpModelFacingText(value);
+    if (Array.isArray(value))
+        return value.map(sanitizeMcpSchemaNameRefs);
+    if (value !== null && typeof value === "object") {
+        const out = Object.create(null);
+        for (const [key, v] of Object.entries(value)) {
+            const neutralized = sanitizeMcpModelFacingText(key);
+            if (Object.hasOwn(out, neutralized))
+                throw new McpPayloadKeyCollision(neutralized);
+            out[neutralized] = Array.isArray(v) ? sanitizeMcpSchemaNameRefs(v) : sanitizeMcpModelFacingValue(v, "schema");
+        }
+        return out;
+    }
+    return value;
+}
+function sanitizeMcpModelFacingValue(value, seat = "schema") {
+    if (seat === "data")
+        return value;
+    if (seat === "nameRefs")
+        return sanitizeMcpSchemaNameRefs(value);
+    if (Array.isArray(value))
+        return value.map((v) => sanitizeMcpModelFacingValue(v, seat === "schema" ? "schema" : "data"));
+    if (value !== null && typeof value === "object") {
+        const out = Object.create(null);
+        for (const [key, v] of Object.entries(value)) {
+            if (seat === "schemaMap") {
+                out[key] = sanitizeMcpModelFacingValue(v, "schema");
+                continue;
+            }
+            const neutralized = sanitizeMcpModelFacingText(key);
+            if (Object.hasOwn(out, neutralized))
+                throw new McpPayloadKeyCollision(neutralized);
+            if (seat === "properties") {
+                out[neutralized] = sanitizeMcpModelFacingValue(v, "schema");
+                continue;
+            }
+            if (MCP_SCHEMA_PROSE_KEYS.has(neutralized)) {
+                out[neutralized] = typeof v === "string" ? sanitizeMcpModelFacingText(v) : v;
+                continue;
+            }
+            out[neutralized] = sanitizeMcpModelFacingValue(v, MCP_SCHEMA_CHILD_SEAT.get(neutralized) ?? "data");
+        }
+        return out;
+    }
+    return value;
+}
+const MCP_TOOL_DESCRIPTION_MAX_CHARS = 2048;
+const MCP_TOOL_DESCRIPTION_TRUNCATION_MARK = "… [truncated]";
+function capMcpToolDescription(description) {
+    if (description.length <= MCP_TOOL_DESCRIPTION_MAX_CHARS)
+        return description;
+    return sliceHeadSafe(description, MCP_TOOL_DESCRIPTION_MAX_CHARS) + MCP_TOOL_DESCRIPTION_TRUNCATION_MARK;
+}
 const MCP_SCHEMA_COMBINATOR_KEYS = ["anyOf", "oneOf", "allOf"];
 const MCP_SCHEMA_PROP_NAME_RE = /^[a-zA-Z0-9_.-]{1,64}$/;
 const MCP_SCHEMA_CARRY_KEYS = ["$defs", "definitions", "$schema", "additionalProperties", "description", "title"];
@@ -643,6 +719,19 @@ export function normalizeMcpToolSchema(schema) {
         return { outcome: "drop", reason: `input schema uses top-level ${combinatorsPresent.join("/")} and could not be normalized` };
     }
 }
+export function mcpToolSchemaAdvisory(schema) {
+    if (schema === undefined || !isPlainSchemaObject(schema))
+        return undefined;
+    const properties = schema.properties;
+    if (!isPlainSchemaObject(properties))
+        return undefined;
+    for (const key of Object.keys(properties)) {
+        if (!MCP_SCHEMA_PROP_NAME_RE.test(key)) {
+            return `its parameter name ${inlineUntrusted(JSON.stringify(key), 80)} is outside the character set some providers accept for tool parameters (${MCP_SCHEMA_PROP_NAME_RE.source}); requests carrying this tool may be rejected by such a provider`;
+        }
+    }
+    return undefined;
+}
 export function mcpToolSchemaProblem(schema) {
     if (schema === undefined)
         return undefined;
@@ -741,6 +830,11 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                     resourceServers.push(s.resourceServer);
                 for (const d of s.dropped)
                     droppedTools.push({ server: inlineUntrusted(spec.name, 160), ...d });
+                for (const a of s.schemaAdvisories)
+                    warnings.push(schemaAdvisoryWarning(spec.name, a.tool, a.reason));
+                if (s.toolsCapabilityAbsent === true && spec.allowTools !== undefined && spec.allowTools.length > 0) {
+                    warnings.push(toolsCapabilityAbsentWarning(spec.name));
+                }
                 if (s.listingIncomplete)
                     warnings.push(listingIncompleteWarning(spec.name, s.listingIncomplete));
                 statuses.push(s.status);
@@ -1329,6 +1423,8 @@ export function parseCallToolResultLenient(data) {
 }
 const LENIENT_CALL_TOOL_RESULT_SCHEMA = { safeParse: parseCallToolResultLenient };
 async function listToolsLenient(client, options) {
+    if (!client.getServerCapabilities()?.tools)
+        return { tools: [], toolsCapabilityAbsent: true };
     const walk = await walkMcpListPages(async (cursor, remainingMs) => {
         const page = await client.request({ method: "tools/list", params: cursor === undefined ? {} : { cursor } }, LenientListToolsResultSchema, { ...options, timeout: remainingMs });
         return {
@@ -1379,7 +1475,7 @@ async function connectServer(spec, principal, onElicit, imageResizer, reminderDi
         };
         const listed = await listToolsLenient(client, startupOpts);
         cacheMcpToolMetadata(client, listed.tools);
-        const { serverTools, serverAxes, dropped } = intakeListedTools(listed, spec, client, health, imageResizer, reminderDisclosure, isServerRevoked);
+        const { serverTools, serverAxes, dropped, advisories } = intakeListedTools(listed, spec, client, health, imageResizer, reminderDisclosure, isServerRevoked);
         const caps = client.getServerCapabilities();
         const resourceInfo = caps?.resources
             ? {
@@ -1403,6 +1499,8 @@ async function connectServer(spec, principal, onElicit, imageResizer, reminderDi
             tools: serverTools,
             axes: serverAxes,
             dropped,
+            schemaAdvisories: advisories,
+            ...(listed.toolsCapabilityAbsent === true ? { toolsCapabilityAbsent: true } : {}),
             listedTools: listed.tools,
             ...(instructions ? { instructions } : {}),
             ...(listed.incomplete !== undefined ? { listingIncomplete: listed.incomplete } : {}),
@@ -1418,14 +1516,28 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
     const serverTools = [];
     const serverAxes = [];
     const dropped = [];
+    const advisories = [];
     const mintedNames = new Map();
     for (const t of listed.tools) {
         if (spec.allowTools && !spec.allowTools.includes(t.name)) {
             continue;
         }
-        const normalized = normalizeMcpToolSchema(t.inputSchema);
-        let effectiveInputSchema = t.inputSchema;
-        let effectiveDescription = t.description !== undefined ? sanitizeUntrustedText(t.description) : undefined;
+        let modelFacingSchema;
+        let sanitizedDescription;
+        try {
+            modelFacingSchema = sanitizeMcpModelFacingValue(t.inputSchema);
+            sanitizedDescription = t.description !== undefined ? sanitizeMcpModelFacingText(t.description) : undefined;
+        }
+        catch (err) {
+            const reason = err instanceof McpPayloadKeyCollision
+                ? `two of its advertised names neutralize to the same model-facing spelling ${inlineUntrusted(JSON.stringify(err.message), 80)}; one parameter would have vanished from the schema the model is given while the server still expects it`
+                : "advertised tool payload could not be neutralized for model-facing display (pathological nesting)";
+            dropped.push({ tool: inlineUntrusted(t.name), reason: inlineUntrusted(reason, 240) });
+            continue;
+        }
+        const normalized = normalizeMcpToolSchema(modelFacingSchema);
+        let effectiveInputSchema = modelFacingSchema;
+        let effectiveDescription = sanitizedDescription !== undefined ? sanitizeUntrustedText(sanitizedDescription) : undefined;
         if (normalized.outcome === "drop") {
             dropped.push({ tool: inlineUntrusted(t.name), reason: inlineUntrusted(normalized.reason, 240) });
             continue;
@@ -1439,6 +1551,10 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
             dropped.push({ tool: inlineUntrusted(t.name), reason: inlineUntrusted(schemaProblem, 240) });
             continue;
         }
+        const schemaAdvisory = mcpToolSchemaAdvisory(effectiveInputSchema);
+        if (schemaAdvisory !== undefined) {
+            advisories.push({ tool: inlineUntrusted(t.name), reason: inlineUntrusted(schemaAdvisory, 240) });
+        }
         const remoteName = t.name;
         const namespacedName = mintNamespacedToolName(MCP_NAMESPACE, spec.name, remoteName);
         const mintedBy = mintedNames.get(namespacedName);
@@ -1462,7 +1578,7 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
         const mcpAlwaysLoad = mcpToolMeta?.["anthropic/alwaysLoad"] === true;
         serverTools.push({
             name: namespacedName,
-            description: effectiveDescription ?? `MCP tool ${remoteName} from ${spec.name}`,
+            description: capMcpToolDescription(effectiveDescription ?? `MCP tool ${inlineUntrusted(sanitizeMcpModelFacingText(remoteName))} from ${spec.name}`),
             label: `${spec.name}:${remoteName}`,
             parameters: (effectiveInputSchema ?? { type: "object" }),
             ...(mcpMaxResultSizeChars !== undefined ? { mcpMaxResultSizeChars } : {}),
@@ -1564,13 +1680,23 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
             },
         });
     }
-    return { serverTools, serverAxes, dropped };
+    return { serverTools, serverAxes, dropped, advisories };
 }
 function asServerWarning(spec, err) {
     const warning = new Error(`mcp: server "${spec.name}" failed to connect — skipped (${namedMcpFailureText(err)})`, { cause: err });
     warning.code = "mcp.server_unavailable";
     return warning;
 }
+function schemaAdvisoryWarning(server, tool, reason) {
+    const warning = new Error(`mcp: server "${inlineUntrusted(server, 160)}" tool "${tool}" is mounted, but ${reason}.`);
+    warning.code = "mcp.tool_schema_advisory";
+    return warning;
+}
+function toolsCapabilityAbsentWarning(server) {
+    const warning = new Error(`mcp: server "${inlineUntrusted(server, 160)}" declared no "tools" capability, so no tool listing was requested and none of the tools named in this server's allowTools can be mounted. If the server does serve tools, it must declare the capability at initialize.`);
+    warning.code = "mcp.tools_capability_absent";
+    return warning;
+}
 function listingIncompleteWarning(server, flag) {
     const warning = new Error(`mcp: server "${inlineUntrusted(server, 160)}" listed its tools INCOMPLETELY — ${listingIncompleteNote(flag)}. The tools beyond the ${flag.pages} page${flag.pages === 1 ? "" : "s"} retrieved are NOT mounted for this task.`);
     warning.code = "mcp.listing_incomplete";

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

@@ -0,0 +1,378 @@
+/**
+ * design/339 — the v3 consolidation WRITE PROTOCOL's engine-side module: active-set derivation
+ * (§1.4.3), the gate store / plan store control-plane sidecars (§2.3), option screening (§6.1) and
+ * the model-visible wording the read-side supersession treatment mints (§3.4).
+ *
+ * The derivation here is the ONE predicate every read face consumes (index mechanical rows,
+ * memory_search's default filter, memory_get's disclosure, and the v2 retention/recall knives when
+ * they land) — a second implementation would be a drift seam, exactly the class the challenge
+ * exclusion view closed.
+ */
+import type { MemoryEntry, MemoryEntryHeader, MemoryEntryOrigin, NotePatch } from "./types.js";
+/**
+ * Derive the SUPERSEDED set from a committed header listing: superseded entry id → the standing
+ * carrier (product) id whose edge suppresses it. `active(x) ⇔ !returned.has(x.id)` over non-
+ * tombstoned entries (tombstones never reach a header listing).
+ *
+ * Edge validity (§1.4.3, the r1-2/r3-2 amended law) — an edge (target, rev) carried by product `p`
+ * is VALID ⇔ all of:
+ *  - `p` stands in the listing (a tombstoned carrier lists nothing — its edges die with it);
+ *  - `p` is not excluded by the local governance overlay (`excluded`: challenge/lineage-latch —
+ *    a QUESTIONED replacement must not keep suppressing its net inputs; the inputs revive, the
+ *    information never falls into a double black hole). The overlay is deliberately LOCAL (the
+ *    challenge ledger does not travel) — a deployment without the account derives from committed
+ *    facts alone and shows MORE evidence, the safe direction;
+ *  - `p`'s committed rev still equals the block's `carrierRev` (the CARRIER-side rev anchor,
+ *    r3-2): a legitimate edit of the product suspends its edges — the edited product may have
+ *    rewritten or retracted what it integrated, and the only accurate copy must not hide outside
+ *    the default face. Deep-carrying idempotent touches move no rev and keep the edges;
+ *  - the TARGET stands in the listing at exactly the edge's anchored rev (the input-side rev
+ *    anchor, D-2a): a later legitimate edit of the superseded entry REVIVES it (new information
+ *    is never suppressed by an edge frozen over old bytes); an absent/tombstoned target makes the
+ *    edge inert (nothing to suppress — the partial-apply direction is safe by the self-containment
+ *    law: an edge exists only on a landed product);
+ *  - the target lives in the CARRIER'S OWN SCOPE (§3.3 内闭合, read side). The freeze and the retry
+ *    enforce "one plan, one scope" on the WRITE side, but every read consumer here is fed a
+ *    MULTI-scope listing (the tool face lists a plane's scopes, index rebuild and the collapse fuse
+ *    list every mounted scope), and an edge frozen legally inside scope A can later face a target
+ *    in scope B: `computeEntryRev` deliberately excludes scope/slug, so a supported cross-scope
+ *    MOVE leaves the anchored rev intact, and an adopted carrier (sync/bundle) is validated for its
+ *    OWN scope with its edge list checked for SHAPE only. Consolidation authority is per-scope
+ *    (seat + lease), so a scope-A carrier must not pull a scope-B entry out of B's default face.
+ *    A whole-scope migration moves carrier and target together and keeps this leg satisfied; only
+ *    the split/partial case changes, and it degrades toward REVIVAL — this module's stated safe
+ *    direction (a deployment shows MORE evidence, never less).
+ *
+ * CHAIN RULE (§1.4.3, explicit): a carrier that is ITSELF superseded (by a later product) keeps
+ * its edges — supersession is convergence, not discredit; the chain p2→p1→x keeps x suppressed.
+ * Only integrity questioning (the overlay) and the tombstone suspend a carrier's edges.
+ *
+ * NON-EMPTINESS (§1.4.3 定理, r2-1): edges only point at a product's own inputs, and inputs are
+ * committed before the product exists — the supersession relation is a DAG, its maximal elements
+ * are always active, so a non-empty library can never derive an empty active set (pinned by test
+ * with the dual-plan full-coverage construction).
+ */
+export declare function deriveSupersededSet(headers: readonly MemoryEntryHeader[], opts?: {
+    excluded?: (id: string) => boolean;
+}): Map<string, string>;
+/** memory_get head note for a superseded entry (delivery proceeds — disclosure, never refusal). */
+export declare function memorySupersededNote(carrierId: string): string;
+/** The tag suffixed to a search hit line when a superseded entry is retrieved explicitly. */
+export declare const MEMORY_SEARCH_SUPERSEDED_TAG = "[superseded]";
+/**
+ * §1.7/§2.3 — the host-injected GLOBAL lease seat (multi-node deployments). The protocol's SAFETY
+ * never depends on it (§1.7 four-independence table) — the lease is COST suppression (one
+ * distillation fleet-wide) plus the fencing token that shrinks a stale holder's overlap window to
+ * a single applyPatches batch. `acquire` answers `undefined` when the lease is NOT held; a held
+ * answer may carry a monotonic `token` whose CURRENT value is re-checked before every apply batch
+ * (a changed token aborts the batch — the plan stays replayable under the new holder).
+ */
+export interface ConsolidationLeaseSeat {
+    acquire(scope: string): Promise<{
+        token?: string;
+    } | undefined> | {
+        token?: string;
+    } | undefined;
+    renew?(scope: string): Promise<{
+        token?: string;
+    } | undefined> | {
+        token?: string;
+    } | undefined;
+    release?(scope: string): Promise<void> | void;
+}
+/** design/339 §6.1 — the `MemoryEngineOptions.consolidation` seat (absent = OFF, the v3 default). */
+export interface MemoryConsolidationOptions {
+    /** Fuse ratio (0,1]: one plan's supersession targets ≤ min(N-1, max(floor, ⌊ratio×N⌋)). */
+    supersedeRatioCap?: number;
+    /** Small-library floor (positive integer), capped by the N-1 ceiling. */
+    supersedeAbsoluteFloor?: number;
+    maxProductsPerRun?: number;
+    maxInputsPerProduct?: number;
+    maxDirectedPatchesPerPlan?: number;
+    minRunIntervalMs?: number;
+    minSessionsBetweenRuns?: number;
+    /** D-13a — the multi-node POSTURE declaration: present ⇒ `lease` must be injected (constructor
+     *  refusal otherwise). Multi-node without declaring is OUT OF CONTRACT (structurally
+     *  undetectable — the declaration turns a silent omission into an explicit choice). */
+    multiNode?: true;
+    /** The global lease (§1.7). Absent ⇒ the single-machine plan-seat CAS is the only mutex. */
+    lease?: ConsolidationLeaseSeat;
+}
+/**
+ * D-10 — factory defaults. CC-product-default transplants, NOT sema calibrations (178 ①-3): the
+ * 24h/5-session cadence mirrors the background-consolidation cadence CC-family products ship;
+ * 0.25/floor-4 mirror the mass-deletion fuse family's calibration posture (MASS_DELETION_FUSE_RATIO
+ * 0.5 halved — a LOGICAL delete rides on top of the physical fuse, so its单窗 ceiling is stricter);
+ * 64/32/32 are the "小 N" ruling's quantification. Hosts can configure every one.
+ */
+export declare const CONSOLIDATION_DEFAULTS: {
+    readonly supersedeRatioCap: 0.25;
+    readonly supersedeAbsoluteFloor: 4;
+    readonly maxProductsPerRun: 64;
+    readonly maxInputsPerProduct: 32;
+    readonly maxDirectedPatchesPerPlan: 32;
+    readonly minRunIntervalMs: number;
+    readonly minSessionsBetweenRuns: 5;
+};
+/**
+ * §2.2 — the HARD throttle floor: even a `force` run cannot start a second same-scope run within
+ * this window of the previous one (cost floor + double-run suppression; the mutex covers overlap,
+ * this covers thrash). The window is `min(minRunIntervalMs, THIS)` — the knob is reused as the
+ * cap, never exceeded — because a full-`minRunIntervalMs` hard throttle would make `force`
+ * structurally dead (the doc's force-bypassable time gate and its unbypassable throttle share the
+ * knob; this floor form is the one reading that keeps both meaningful, disclosed).
+ */
+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
+ * 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
+ * genuinely crashed claim still self-heals within one recommendation cadence. Inside the window
+ * reconcile reports the claim as in-flight instead of releasing it.
+ */
+export declare const CONSOLIDATION_SEAT_FREEZE_GRACE_MS: number;
+export interface ScreenedConsolidationOptions {
+    supersedeRatioCap: number;
+    supersedeAbsoluteFloor: number;
+    maxProductsPerRun: number;
+    maxInputsPerProduct: number;
+    maxDirectedPatchesPerPlan: number;
+    minRunIntervalMs: number;
+    minSessionsBetweenRuns: number;
+    multiNode: boolean;
+    lease?: ConsolidationLeaseSeat;
+}
+/**
+ * Screen the consolidation options at engine construction (#123 bad-value loudness: every bad
+ * value refuses with a code, never folds to a default). Two structural refusals beyond values:
+ *  - D-12a: `provenance: "off"` × consolidation present is a CONSTRUCTION refusal — off means "no
+ *    origin is ever minted", while consolidation's fold law must be able to mint (a marked input's
+ *    product would otherwise commit unmarked = the laundering window). Enable carry or disable
+ *    consolidation.
+ *  - D-13a: `multiNode: true` without an injected lease refuses — the declaration exists exactly
+ *    to make that omission explicit.
+ */
+export declare function screenConsolidationOptions(raw: MemoryConsolidationOptions, provenance: "off" | "carry"): ScreenedConsolidationOptions;
+/** §1.2-2 — the supersession fuse ceiling: min(N-1, max(floor, ⌊ratio×N⌋)); N ≤ 1 ⇒ 0 (one plan
+ *  may NEVER empty the active set — the N-1 ceiling is unconditional, G21). */
+export declare function supersessionFuseCeiling(activeSetSize: number, opts: Pick<ScreenedConsolidationOptions, "supersedeRatioCap" | "supersedeAbsoluteFloor">): number;
+/** §3.1 — the type axis of the eligibility predicate: episodic entries are read-only evidence
+ *  (never candidates, never supersession/directed targets, A-7); procedural promotion is a v3
+ *  follow-on ticket. Unknown/absent types are ordinary semantic notes — eligible. */
+export declare function consolidationTypeEligible(type: string | undefined): boolean;
+export declare const CONSOLIDATION_GATE_FILE = "consolidation-gate.json";
+export declare const CONSOLIDATION_PLANS_DIR = "consolidation-plans";
+export declare const CONSOLIDATION_INTENTS_FILE = "consolidation-intents.json";
+export interface ConsolidationGateRow {
+    /** Last COMPLETED run's settle time (ms epoch). */
+    lastRunAt?: number;
+    /** Distinct terminal-harvest sessions since the last run (count + bounded dedup ring). */
+    sessions: {
+        count: number;
+        ring: string[];
+    };
+    /** 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
+     *  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;
+    /** 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):
+     *  change-driven increments diff against THIS — a candidate is an eligible entry that is new
+     *  to the map or whose rev moved (eligibility flips INTO the set read as "new": the map only
+     *  ever holds eligible entries). Absent/lost ⇒ full candidates (conservative: 多看不少看). */
+    fingerprint?: Record<string, {
+        rev: string;
+    }>;
+    /** The last snapshot taken for this scope (the engine's visible-set account, §1.2-2 r3-1: the
+     *  fold/instruction authority is what the engine actually SERVED — recorded here, keyed by the
+     *  cycle token; a newer snapshot replaces it, and commit refuses a token that no longer
+     *  matches). `candidates`: the served (incremental) id → rev set — the edge-target legality
+     *  domain; `eligible`: the FULL eligible id → rev map at snapshot time (the next fingerprint on
+     *  completion); `marked`: any served candidate carried a committed external-origin marker. */
+    snapshot?: {
+        token: string;
+        at: number;
+        epoch: number;
+        candidates: Record<string, string>;
+        eligible: Record<string, string>;
+        marked: boolean;
+    };
+}
+interface ConsolidationGateFile {
+    v: 1;
+    scopes: Record<string, ConsolidationGateRow>;
+}
+/** Locked, journaled gate update (the strict family's exact discipline). */
+export declare function updateConsolidationGate<T>(controlDir: string, fn: (file: ConsolidationGateFile) => {
+    next?: ConsolidationGateFile;
+    result: T;
+}): T;
+/** Lock-less journal-aware gate read (corrupt ⇒ throws — the verbs' fail-closed arm). */
+export declare function readConsolidationGateFile(controlDir: string): ConsolidationGateFile;
+/** True ⇔ the gate store file exists at all (G1's zero-file pin reads this negatively). */
+export declare function consolidationGateFileExists(controlDir: string): boolean;
+/**
+ * §2.2 — the engine-minted session count (harvest-tail bookkeeping; ≤1 row write per terminal
+ * harvest; the OFF mode never calls this — D-9a zero-write). Returns the recommendation edge:
+ * `recommended` is true exactly ONCE per threshold crossing (once-per-越线沿; a completed run
+ * resets the edge).
+ */
+export declare function recordConsolidationSession(controlDir: string, scope: string, sessionId: string, opts: ScreenedConsolidationOptions, now: () => number): {
+    recommended: boolean;
+    sessionsSince: number;
+};
+/**
+ * §1.4.5 — the active-set COLLAPSE fuse: record the freshly derived active-set size against the
+ * stored baseline; a single-window shrink beyond the ratio cap answers the collapse fact (the
+ * caller discloses via incident + announcement — the read face NEVER refuses service over it).
+ * Baseline loss ⇒ re-baseline silently (conservative: one extra disclosure at worst next window).
+ */
+export declare function recordActiveSetBaseline(controlDir: string, scope: string, size: number, ratioCap: number, _now: () => number): {
+    collapsed?: {
+        from: number;
+        to: number;
+    };
+};
+/** §1.5 — a directed-change intent (TERMINAL-STATE form: the intent names the target end state,
+ *  never an increment — the precondition for replay/re-judgment converging at any interleaving). */
+export type ConsolidationIntent = {
+    requestId: string;
+    kind: "forget";
+    entryId: string;
+} | {
+    requestId: string;
+    kind: "rewrite";
+    entryId: string;
+    body: string;
+    name?: string;
+    description?: string;
+    type?: string;
+};
+/** §1.1 — one proposed product (driver output = DATA, zero carriage authority: origin/distilled
+ *  in a proposal do not exist as fields — the engine computes both at freeze). */
+export interface ConsolidationProductProposal {
+    name?: string;
+    description?: string;
+    type?: string;
+    body: string;
+    /** The product's COMPLETE input attribution; `supersede: true` rows are the proposed edges. */
+    inputs: Array<{
+        id: string;
+        supersede?: boolean;
+    }>;
+}
+export interface ConsolidationProposal {
+    scope: string;
+    products: ConsolidationProductProposal[];
+    intents?: ConsolidationIntent[];
+}
+export type ConsolidationDirectedState = "pending" | "applied" | "satisfied" | "conflict";
+export interface ConsolidationDirectedPatch {
+    intentRequestId: string;
+    op: "update" | "delete";
+    id: string;
+    baseRev: string;
+    /** update: computeEntryRev of the frozen terminal entry (the satisfied-judgment anchor, r2-4);
+     *  absent for delete (the delete terminal is ABSENCE — probed, not hashed). */
+    plannedPostRev?: string;
+    entry?: MemoryEntry;
+    state: ConsolidationDirectedState;
+    /** delete only (§1.5-2): who reached the terminal — "self" when THIS plan's apply landed it,
+     *  "unattributed" when a replay found the terminal already standing (the F9 crash micro-window:
+     *  audit degrades, the judgment never does). */
+    attribution?: "self" | "unattributed";
+}
+export type ConsolidationPlanState = "open" | "applying" | "completed" | "conflict" | "discarded";
+export interface ConsolidationPlanFile {
+    v: 1;
+    planId: string;
+    scope: string;
+    requestId: string;
+    createdAt: number;
+    cycleToken?: string;
+    epoch: number;
+    /** r3-1 — the ENGINE-VISIBLE-SET fold fact this run froze under (authority = what the engine
+     *  served, never the proposal's declaration). */
+    visibleMarked: boolean;
+    foldedOrigin?: MemoryEntryOrigin;
+    /** Frozen products — FULL entry bytes (id/frontmatter incl. distilled + origin/body/rev). */
+    products: MemoryEntry[];
+    productStates: Record<string, "pending" | "applied" | "conflict">;
+    directed: ConsolidationDirectedPatch[];
+    intents: Array<{
+        requestId: string;
+        state: "pending" | "settled" | "abandoned";
+    }>;
+    state: ConsolidationPlanState;
+    audit: Array<{
+        at: number;
+        event: string;
+        requestId?: string;
+        detail?: string;
+    }>;
+}
+/**
+ * Plan ids are ENGINE-MINTED uuids, but the host-facing verbs (`resolveConsolidationPlan`,
+ * `reconcileConsolidation` via the gate row) echo them back as ARGUMENTS — and the id doubles as a
+ * control-plane FILE NAME, so a crafted spelling (`../…`, an absolute path) would escape the plans
+ * directory on the read AND on the corrupt-custody RENAME (an outside pass's security finding,
+ * adopted). One grammar (the entry-id family's shape), judged before any path join — the 幽灵行
+ * guard's refusal posture: an invalid spelling reads as absent/refused, never as a path.
+ */
+export declare function isValidConsolidationPlanId(value: string): boolean;
+export declare function writeConsolidationPlan(controlDir: string, plan: ConsolidationPlanFile): void;
+export type ConsolidationPlanRead = {
+    state: "ok";
+    plan: ConsolidationPlanFile;
+} | {
+    state: "absent";
+} | {
+    state: "corrupt";
+    detail: string;
+};
+export declare function readConsolidationPlan(controlDir: string, planId: string): ConsolidationPlanRead;
+export declare function listConsolidationPlanIds(controlDir: string): string[];
+/** F5 custody — a corrupt plan file the valve DISCARDS is moved aside (never deleted: the bytes
+ *  are the only record of what the plan was). Returns the custody file name. */
+export declare function quarantineCorruptPlan(controlDir: string, planId: string): string | undefined;
+export interface ConsolidationIntentCredentialRow {
+    requestId: string;
+    state: "settled" | "abandoned";
+    planId: string;
+    at: number;
+    patches: Array<{
+        op: "update" | "delete";
+        id: string;
+        attribution?: "self" | "unattributed";
+    }>;
+}
+/**
+ * Record intent credentials — IDEMPOTENT on requestId (F10: two plans racing one intent cannot
+ * double-settle; the first credential row stands, a later contradictory write is dropped with the
+ * losing verdict returned to the caller for audit). Returns the requestIds actually written.
+ */
+export declare function recordIntentCredentials(controlDir: string, rows: readonly ConsolidationIntentCredentialRow[]): string[];
+export declare function readIntentCredentials(controlDir: string): Record<string, ConsolidationIntentCredentialRow>;
+/** Derive a product's slug from its proposed name (memory filename charset; collisions are the
+ *  backend's deterministic -n suffix). */
+export declare function deriveProductSlug(name: string | undefined, fallback: string): string;
+/** The refusal error every consolidation verb throws (structured: stable `code` + the per-item
+ *  disclosure list — G5/G7/G14's "结构化拒+披露" shape). */
+export declare class ConsolidationRefusedError extends Error {
+    readonly code: string;
+    readonly reasons: string[];
+    constructor(code: string, message: string, reasons?: string[]);
+}
+/** A NotePatch list for one frozen product (the §1.3 add-only arm's one spelling). */
+export declare function productAddPatch(product: MemoryEntry): NotePatch;
+export {};