@gamaze/hicortex 0.20.9 → 0.20.10

package/dist/eval/ranking-fixtures.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Planted ranking fixtures for the search-trust calibration gate (#425).
+ *
+ * Two fixture cases, both shaped like the field failure that opened the
+ * issue (the owner's live console test, 2026-09-13): a user searches a
+ * DISTINCTIVE PROPER NOUN they know exists; the one memory carrying that
+ * token has the best similarity of all candidates AND the literal FTS hit,
+ * yet ranks behind hardened but less-relevant memories that win on
+ * effective strength + graph connections.
+ *
+ *   (a) sirnas_exact_match — the AC1 fixture: a low-strength, unlinked,
+ *       never-accessed memory carrying an invented proper noun against
+ *       base-≥0.9 rivals with links among themselves, access history, and
+ *       older creation dates. The rivals share the query's DOMAIN
+ *       vocabulary (harbours, docks, boats) but never the proper noun.
+ *       Declared expectation: the proper-noun row ranks #1.
+ *   (b) no_match_control — the AC2 fixture: a "mamma"-class query with no
+ *       relevant match and NO FTS hits anywhere in the corpus. Whatever
+ *       nearest-neighbor junk vector search returns must be byte-stable
+ *       under the ranking work (no both-channel candidates exist, so the
+ *       boost can never fire — the case pins that the no-regression
+ *       guarantee is structural, not lucky).
+ *
+ * Honesty rules (the planted-pairs #393 A discipline):
+ *  - The texts are synthetic and generic (this package publishes to npm —
+ *    no real infrastructure, people, or fleet detail), but SHAPED like the
+ *    field failure: the proper noun is invented (it must appear nowhere
+ *    else — verified by an invariant test), the rivals are hardened with
+ *    metadata the production pipeline itself writes (base strength, access
+ *    hardening, link counts).
+ *  - Similarities are MEASURED at run time with the real bge-small-en-v1.5
+ *    embedder (ranking-eval.ts) — never asserted into existence. The
+ *    declared expectation is about ORDER under the shipped ranking, and
+ *    the report prints the measured similarity/score of every top row.
+ *  - Strength metadata is written through the production helpers
+ *    (insertMemory + updateMemory + addLink), not hand-rolled SQL, so the
+ *    fixture exercises the same rows retrieval() will see.
+ */
+export interface RankingRow {
+    /** Stable identifier used by expectations, links, and the report. */
+    key: string;
+    content: string;
+    /** ISO timestamp. */
+    createdAt: string;
+    /** knowledge | experience | decision. */
+    memoryType: string;
+    /** Birth base_strength — the value stageImportance would have written. */
+    baseStrength: number;
+    /** Access history (hardening + the decay clock). */
+    accessCount: number;
+    /** Days before the run's `now` of the last access (0 = touched today). */
+    lastAccessedDaysAgo: number;
+    /** Keys this row links to (links are created after all inserts). */
+    linksTo: string[];
+}
+export interface RankingFixture {
+    /** Case identifier (report + photo keys). */
+    key: string;
+    description: string;
+    rows: RankingRow[];
+    query: string;
+    /**
+     * The token that makes the query distinctive — invariant-tested to appear
+     * in exactly one row (the target) and in no rival/filler content.
+     */
+    distinctiveToken: string;
+    /** Declared expectation: this row's key must be returned at position 1. */
+    expectedTop1: string;
+}
+/** All planted rows share project + source_agent (metadata never refuses). */
+export declare const RANKING_PROJECT = "ranking-eval";
+export declare const RANKING_SOURCE_AGENT = "ranking-eval";
+export declare const SIRNAS_FIXTURE: RankingFixture;
+export declare const NO_MATCH_FIXTURE: RankingFixture;
+/** The battery runs against a real snapshot copy (ranking-eval.ts case 3). */
+export declare const REAL_SIRNAS_MEMORY_ID = "12980c9d-0eba-4963-95eb-0548bc2aa93e";
+export declare function checkFixtureInvariants(f: RankingFixture): string[];

package/dist/eval/ranking-fixtures.js

@@ -0,0 +1,226 @@
+"use strict";
+/**
+ * Planted ranking fixtures for the search-trust calibration gate (#425).
+ *
+ * Two fixture cases, both shaped like the field failure that opened the
+ * issue (the owner's live console test, 2026-09-13): a user searches a
+ * DISTINCTIVE PROPER NOUN they know exists; the one memory carrying that
+ * token has the best similarity of all candidates AND the literal FTS hit,
+ * yet ranks behind hardened but less-relevant memories that win on
+ * effective strength + graph connections.
+ *
+ *   (a) sirnas_exact_match — the AC1 fixture: a low-strength, unlinked,
+ *       never-accessed memory carrying an invented proper noun against
+ *       base-≥0.9 rivals with links among themselves, access history, and
+ *       older creation dates. The rivals share the query's DOMAIN
+ *       vocabulary (harbours, docks, boats) but never the proper noun.
+ *       Declared expectation: the proper-noun row ranks #1.
+ *   (b) no_match_control — the AC2 fixture: a "mamma"-class query with no
+ *       relevant match and NO FTS hits anywhere in the corpus. Whatever
+ *       nearest-neighbor junk vector search returns must be byte-stable
+ *       under the ranking work (no both-channel candidates exist, so the
+ *       boost can never fire — the case pins that the no-regression
+ *       guarantee is structural, not lucky).
+ *
+ * Honesty rules (the planted-pairs #393 A discipline):
+ *  - The texts are synthetic and generic (this package publishes to npm —
+ *    no real infrastructure, people, or fleet detail), but SHAPED like the
+ *    field failure: the proper noun is invented (it must appear nowhere
+ *    else — verified by an invariant test), the rivals are hardened with
+ *    metadata the production pipeline itself writes (base strength, access
+ *    hardening, link counts).
+ *  - Similarities are MEASURED at run time with the real bge-small-en-v1.5
+ *    embedder (ranking-eval.ts) — never asserted into existence. The
+ *    declared expectation is about ORDER under the shipped ranking, and
+ *    the report prints the measured similarity/score of every top row.
+ *  - Strength metadata is written through the production helpers
+ *    (insertMemory + updateMemory + addLink), not hand-rolled SQL, so the
+ *    fixture exercises the same rows retrieval() will see.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REAL_SIRNAS_MEMORY_ID = exports.NO_MATCH_FIXTURE = exports.SIRNAS_FIXTURE = exports.RANKING_SOURCE_AGENT = exports.RANKING_PROJECT = void 0;
+exports.checkFixtureInvariants = checkFixtureInvariants;
+/** All planted rows share project + source_agent (metadata never refuses). */
+exports.RANKING_PROJECT = "ranking-eval";
+exports.RANKING_SOURCE_AGENT = "ranking-eval";
+// ---------------------------------------------------------------------------
+// Case 1 — sirnas_exact_match (AC1)
+// ---------------------------------------------------------------------------
+//
+// The target mirrors the field case's SHAPE with invented names: a home
+// harbour memory carrying one distinctive proper noun, born weak (base 0.35,
+// the "routine-but-curated" band), never accessed, unlinked, a few months
+// old. The rivals are what the decay model produces for early-hardened
+// technical rows: base 0.90-0.95, mutual links, access history, created
+// BEFORE the target. They share the harbour/boating domain vocabulary — so
+// a bare proper-noun query lands in their neighborhood — but none carries
+// the proper noun.
+const SIRNAS_ROWS = [
+    // --- rivals: hardened, connected, older, domain-adjacent ---
+    {
+        key: "rival_fees",
+        content: "Harbour fees and guest dock rules: pay at the machine by the fuel quay, electricity on the guest dock is metered, " +
+            "and visiting boats must clear their berth by ten in the morning during the summer season.",
+        createdAt: "2026-03-02T09:00:00.000Z",
+        memoryType: "knowledge",
+        baseStrength: 0.9,
+        accessCount: 4,
+        lastAccessedDaysAgo: 6,
+        linksTo: ["rival_channel", "rival_maintenance"],
+    },
+    {
+        key: "rival_channel",
+        content: "Sailing notes for the home bay: the channel is marked with cardinal buoys, the shallow spit near the outer dock " +
+            "dries at low water, and the ferry has right of way inside the harbour basin.",
+        createdAt: "2026-03-16T09:00:00.000Z",
+        memoryType: "knowledge",
+        baseStrength: 0.95,
+        accessCount: 6,
+        lastAccessedDaysAgo: 2,
+        linksTo: ["rival_fees", "rival_maintenance"],
+    },
+    {
+        key: "rival_maintenance",
+        content: "Boat maintenance log: scrub the hull and check the anodes before launch, service the winch every spring, and " +
+            "book the boatyard crane early — the lifting slot list fills up in May.",
+        createdAt: "2026-03-30T09:00:00.000Z",
+        memoryType: "experience",
+        baseStrength: 0.9,
+        accessCount: 3,
+        lastAccessedDaysAgo: 11,
+        linksTo: ["rival_fees"],
+    },
+    {
+        key: "rival_passage",
+        content: "Passage plan habits: file the float plan before leaving the dock, plot the tidal gate times, and always take the " +
+            "safe water mark side of the reef when the light is obscured.",
+        createdAt: "2026-04-13T09:00:00.000Z",
+        memoryType: "knowledge",
+        baseStrength: 0.9,
+        accessCount: 2,
+        lastAccessedDaysAgo: 20,
+        linksTo: ["rival_channel"],
+    },
+    // --- the target: the exact proper-noun match, born humble ---
+    {
+        key: "target_harbour",
+        content: "Home harbour: Vindarsvik (near Stensundet). The guest berth is east of the ferry pier; hold slack when the " +
+            "fishing boats unload.",
+        createdAt: "2026-05-25T09:00:00.000Z",
+        memoryType: "knowledge",
+        baseStrength: 0.35,
+        accessCount: 0,
+        lastAccessedDaysAgo: 118,
+        linksTo: [],
+    },
+    // --- neutral filler: keeps neighborhoods non-trivial, off-domain ---
+    {
+        key: "fill_recipe",
+        content: "Batch-cooked a tomato and butter sauce from the Rome cookbook: San Marzano tomatoes, one whole onion halved, and far more butter than seems reasonable.",
+        createdAt: "2026-04-01T09:00:00.000Z",
+        memoryType: "experience",
+        baseStrength: 0.5,
+        accessCount: 0,
+        lastAccessedDaysAgo: 160,
+        linksTo: [],
+    },
+    {
+        key: "fill_books",
+        content: "Finished the third novel in the frontier trilogy. The middle book dragged through the mining-town chapters, but the finale pays off when the surveyor reads her grandmother's letters.",
+        createdAt: "2026-04-20T09:00:00.000Z",
+        memoryType: "experience",
+        baseStrength: 0.5,
+        accessCount: 0,
+        lastAccessedDaysAgo: 140,
+        linksTo: [],
+    },
+    {
+        key: "fill_lang",
+        content: "Language study notes: the dative prepositions finally clicked after drilling them as a sung list; irregular verbs still need spaced repetition.",
+        createdAt: "2026-05-10T09:00:00.000Z",
+        memoryType: "experience",
+        baseStrength: 0.5,
+        accessCount: 0,
+        lastAccessedDaysAgo: 120,
+        linksTo: [],
+    },
+    {
+        key: "fill_garden",
+        content: "The raised beds need refreshing before spring: compost the spent tomato vines, rotate the legume row, and prune the apple espalier before the buds swell.",
+        createdAt: "2026-06-02T09:00:00.000Z",
+        memoryType: "experience",
+        baseStrength: 0.5,
+        accessCount: 0,
+        lastAccessedDaysAgo: 100,
+        linksTo: [],
+    },
+];
+exports.SIRNAS_FIXTURE = {
+    key: "sirnas_exact_match",
+    description: "AC1: a distinctive proper-noun query must rank the exact-match (both-channel) memory first, " +
+        "ahead of hardened domain-adjacent rivals that win on strength + connections.",
+    rows: SIRNAS_ROWS,
+    query: "Vindarsvik",
+    distinctiveToken: "vindarsvik",
+    expectedTop1: "target_harbour",
+};
+// ---------------------------------------------------------------------------
+// Case 2 — no_match_control (AC2)
+// ---------------------------------------------------------------------------
+//
+// A "mamma"-class query: a common household word in the user's language that
+// appears in NO corpus row — no FTS token, no semantic neighbor. Vector
+// search still returns nearest-neighbor junk (the field's 0.53-similarity
+// technical rows); the case pins the FULL returned list so any drift in
+// how unrelated junk is ordered is caught, and asserts structurally that
+// the ranking work cannot touch it (no both-channel candidates exist).
+exports.NO_MATCH_FIXTURE = {
+    key: "no_match_control",
+    description: "AC2: a no-match query (no FTS hits anywhere) returns a byte-stable list — no both-channel " +
+        "candidates exist, so the boost is structurally inert.",
+    // Same corpus as case 1 (minus nothing): the query matches none of it.
+    rows: SIRNAS_ROWS,
+    query: "mamma",
+    distinctiveToken: "",
+    // No declared top-1 — the assertion is stability, not order (the photo
+    // records the list; the gate compares runs).
+    expectedTop1: "",
+};
+/** The battery runs against a real snapshot copy (ranking-eval.ts case 3). */
+exports.REAL_SIRNAS_MEMORY_ID = "12980c9d-0eba-4963-95eb-0548bc2aa93e";
+// ---------------------------------------------------------------------------
+// Fixture invariants (checked by ranking-eval at run time AND pinned in
+// tests/ranking-eval-tooling.test.ts — a corpus that silently drifts from
+// its declared shape would fake a pass/fail)
+// ---------------------------------------------------------------------------
+function checkFixtureInvariants(f) {
+    const problems = [];
+    const keys = new Set(f.rows.map((r) => r.key));
+    if (keys.size !== f.rows.length)
+        problems.push("duplicate row keys");
+    for (const r of f.rows) {
+        for (const to of r.linksTo) {
+            if (!keys.has(to))
+                problems.push(`${r.key} links to unknown key ${to}`);
+            if (to === r.key)
+                problems.push(`${r.key} links to itself`);
+        }
+    }
+    if (f.expectedTop1 && !keys.has(f.expectedTop1)) {
+        problems.push(`expectedTop1 ${f.expectedTop1} is not a row key`);
+    }
+    if (f.distinctiveToken) {
+        const token = f.distinctiveToken.toLowerCase();
+        const carriers = f.rows.filter((r) => r.content.toLowerCase().includes(token));
+        if (carriers.length !== 1) {
+            problems.push(`distinctive token "${f.distinctiveToken}" carried by ${carriers.length} rows (expected exactly 1)`);
+        }
+        else if (f.expectedTop1 && carriers[0].key !== f.expectedTop1) {
+            problems.push(`distinctive token carried by ${carriers[0].key}, not expectedTop1 ${f.expectedTop1}`);
+        }
+        if (!f.query.toLowerCase().includes(token)) {
+            problems.push(`query does not contain the distinctive token`);
+        }
+    }
+    return problems;
+}

package/dist/identity-store.d.ts

@@ -351,3 +351,24 @@ export declare function serveIdentityBody(handlerResult: HandlerResult, memoryEn
  * symlink safety). Throws are left to the adapter to turn into a 500.
  */
 export declare function handleIdentityPut(identityDir: string, body: unknown, query?: Record<string, unknown>, identityAgents?: Record<string, AgentMode>): HandlerResult;
+/**
+ * PUT /identity/mode (#423 phase 3): switch ONE agent's scope to
+ * override/global/off. Pure validation + merge — the ADAPTER (mcp-server.ts)
+ * does three things with the result: (1) persists `agents` as the config's
+ * `identityAgents` (survives restarts), (2) sets the daemon's live boot-time
+ * map to the same merged map (single-writer: the map changes at boot or
+ * here — never diverges), so the switch is live on the very next
+ * GET /identity?agent= (applies: "immediate"), and (3) responds with this
+ * body. Externally hand-edited config still needs a restart (pre-existing
+ * posture — only this endpoint updates the live map).
+ *
+ * Interplay with PUT /identity: its black-hole guard 409s section writes
+ * while config forces off/global for the agent (sections written under
+ * agents/<id>/ would never be served); switching to 'override' here FIRST
+ * unblocks section editing. `dir_present` tells the caller whether an agent
+ * section dir already exists ('real' — agent content to serve) or not
+ * (override on a fresh dir = global content until sections are written).
+ */
+export declare function handleIdentityModePut(identityDir: string, body: unknown, query: Record<string, unknown>, currentAgents: Record<string, AgentMode>): HandlerResult & {
+    agents?: Record<string, AgentMode>;
+};

package/dist/identity-store.js

@@ -56,6 +56,7 @@ exports.readResolvedSections = readResolvedSections;
 exports.handleIdentityGet = handleIdentityGet;
 exports.serveIdentityBody = serveIdentityBody;
 exports.handleIdentityPut = handleIdentityPut;
+exports.handleIdentityModePut = handleIdentityModePut;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_crypto_1 = require("node:crypto");
@@ -875,3 +876,51 @@ function handleIdentityPut(identityDir, body, query = {}, identityAgents = {}) {
     }
     return { status: 200, body: respBody, warn };
 }
+/**
+ * PUT /identity/mode (#423 phase 3): switch ONE agent's scope to
+ * override/global/off. Pure validation + merge — the ADAPTER (mcp-server.ts)
+ * does three things with the result: (1) persists `agents` as the config's
+ * `identityAgents` (survives restarts), (2) sets the daemon's live boot-time
+ * map to the same merged map (single-writer: the map changes at boot or
+ * here — never diverges), so the switch is live on the very next
+ * GET /identity?agent= (applies: "immediate"), and (3) responds with this
+ * body. Externally hand-edited config still needs a restart (pre-existing
+ * posture — only this endpoint updates the live map).
+ *
+ * Interplay with PUT /identity: its black-hole guard 409s section writes
+ * while config forces off/global for the agent (sections written under
+ * agents/<id>/ would never be served); switching to 'override' here FIRST
+ * unblocks section editing. `dir_present` tells the caller whether an agent
+ * section dir already exists ('real' — agent content to serve) or not
+ * (override on a fresh dir = global content until sections are written).
+ */
+function handleIdentityModePut(identityDir, body, query, currentAgents) {
+    const { agentId, error } = extractAgentParam(query);
+    if (error)
+        return { status: 400, body: { error } };
+    if (agentId === null) {
+        return {
+            status: 400,
+            body: { error: "The ?agent= query parameter is required (PUT /identity/mode sets ONE agent's scope)" },
+        };
+    }
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+        return { status: 400, body: { error: "Body must be a JSON object {mode}" } };
+    }
+    const { mode } = body;
+    if (mode !== "override" && mode !== "global" && mode !== "off") {
+        return { status: 400, body: { error: "Invalid 'mode' — expected one of \"override\", \"global\", \"off\"" } };
+    }
+    return {
+        status: 200,
+        body: {
+            agent: agentId,
+            mode,
+            dir_present: agentDirState(identityDir, agentId) === "real",
+            applies: "immediate",
+        },
+        // The merged map the adapter persists AND applies to the live boot-time
+        // map — other agents' entries are preserved untouched.
+        agents: { ...currentAgents, [agentId]: mode },
+    };
+}

package/dist/init.d.ts

@@ -94,6 +94,20 @@ export declare function loadConfigStrict(configPath: string): {
     config: Record<string, unknown>;
     hadFile: boolean;
 };
+/**
+ * Apply a sparse set of config updates atomically-ish (strict load → merge →
+ * save): the HTTP-side sibling of persistLlmConfig (which drives the
+ * interactive init flow). `null` values DELETE the key — the console's
+ * "clear field" semantic. Values are assumed VALIDATED by the caller (the
+ * /dashboard/model PUT validates its allowlisted subset BEFORE calling); this
+ * function only owns load-strictly + merge + save, so a malformed existing
+ * config throws here and the file is left UNTOUCHED (the 0.16.x contract —
+ * see loadConfigStrict). Returns the freshly persisted config so the caller
+ * can answer with the post-write truth (re-read, not echo).
+ *
+ * Exported for dashboard.ts's PUT handler + tests.
+ */
+export declare function persistConfigUpdates(configPath: string, updates: Record<string, unknown>): Record<string, unknown>;
 /**
  * `init --repair-config` escape hatch: move a malformed config.json aside so
  * init can rebuild, instead of dead-ending on loadConfigStrict's throw.

package/dist/init.js

@@ -30,6 +30,7 @@ exports.parseEnvFile = parseEnvFile;
 exports.isLlmConfigured = isLlmConfigured;
 exports.persistLlmConfig = persistLlmConfig;
 exports.loadConfigStrict = loadConfigStrict;
+exports.persistConfigUpdates = persistConfigUpdates;
 exports.quarantineMalformedConfig = quarantineMalformedConfig;
 exports.generateAuthToken = generateAuthToken;
 exports.persistAuthToken = persistAuthToken;
@@ -65,6 +66,7 @@ const node_crypto_1 = require("node:crypto");
 const claude_md_js_1 = require("./claude-md.js");
 const claude_desktop_js_1 = require("./claude-desktop.js");
 const config_read_js_1 = require("./config-read.js");
+const calibration_js_1 = require("./calibration.js");
 const run_deadline_js_1 = require("./run-deadline.js");
 const identity_store_js_1 = require("./identity-store.js");
 const HICORTEX_HOME = (0, paths_js_1.hicortexHome)();
@@ -1052,6 +1054,30 @@ function loadConfigStrict(configPath) {
     }
     return { config: parsed, hadFile: true };
 }
+/**
+ * Apply a sparse set of config updates atomically-ish (strict load → merge →
+ * save): the HTTP-side sibling of persistLlmConfig (which drives the
+ * interactive init flow). `null` values DELETE the key — the console's
+ * "clear field" semantic. Values are assumed VALIDATED by the caller (the
+ * /dashboard/model PUT validates its allowlisted subset BEFORE calling); this
+ * function only owns load-strictly + merge + save, so a malformed existing
+ * config throws here and the file is left UNTOUCHED (the 0.16.x contract —
+ * see loadConfigStrict). Returns the freshly persisted config so the caller
+ * can answer with the post-write truth (re-read, not echo).
+ *
+ * Exported for dashboard.ts's PUT handler + tests.
+ */
+function persistConfigUpdates(configPath, updates) {
+    const { config } = loadConfigStrict(configPath);
+    for (const [k, v] of Object.entries(updates)) {
+        if (v === null)
+            delete config[k];
+        else
+            config[k] = v;
+    }
+    saveConfig(configPath, config);
+    return config;
+}
 /**
  * `init --repair-config` escape hatch: move a malformed config.json aside so
  * init can rebuild, instead of dead-ending on loadConfigStrict's throw.
@@ -1943,6 +1969,9 @@ async function runInit(options = {}) {
     // the install → first-nightly → retained funnel is measurable. Never blocks:
     // failures are swallowed inside sendLifecycleEvent.
     await (0, telemetry_js_1.sendLifecycleEvent)("install", HICORTEX_HOME, readHomeConfig(HICORTEX_HOME), pkgVersion());
+    // #436: the first-run lookback cap is invisible until it bites — tell the
+    // long-history user where the rest went and how to get it, once, at install.
+    console.log(`History import: the first nightly captures the last ${calibration_js_1.DEFAULT_FIRST_RUN_LOOKBACK_DAYS} days of your agents' sessions by default — run \`hicortex nightly --recapture-window <days>\` once to import more.`);
     console.log("Next steps:");
     // Counter-based so the list stays contiguous (1,2,3,4) whether or not Hermes
     // was detected — a conditional middle step used to leave a "1, 3, 4" gap.
@@ -2128,6 +2157,9 @@ async function runClientInit(serverUrl, agentName) {
     // the install → first-nightly → retained funnel is measurable. Never blocks:
     // failures are swallowed inside sendLifecycleEvent.
     await (0, telemetry_js_1.sendLifecycleEvent)("install", HICORTEX_HOME, readHomeConfig(HICORTEX_HOME), pkgVersion());
+    // #436: the first-run lookback cap is invisible until it bites — tell the
+    // long-history user where the rest went and how to get it, once, at install.
+    console.log(`History import: the first nightly captures the last ${calibration_js_1.DEFAULT_FIRST_RUN_LOOKBACK_DAYS} days of your agents' sessions on this machine by default — run \`hicortex nightly --recapture-window <days>\` once to import more.`);
     console.log("How it works:");
     console.log("  • MCP tools (search, identity, ingest) talk to the remote server");
     console.log("  • Nightly pipeline denoises CC transcripts, POSTs to server for distillation");

package/dist/mcp-server.d.ts

@@ -42,6 +42,18 @@ export declare function createMcpServer(): McpServer;
  * at each step; invalid/absent falls through.
  */
 export declare function resolveBodyLimitMb(configVal: unknown, hostedMode: boolean): number;
+/**
+ * Resolve the OPTIONAL /search relevance floor (`minSimilarity` query param,
+ * #409 console polish). Pure — exported for tests. Absent/blank/invalid →
+ * undefined = NO gate (byte-identical to every pre-existing caller: agents,
+ * plugins, MCP tools never send the param). A finite number in [0, 1] → that
+ * floor, clamped into range so a hostile `?minSimilarity=42` cannot widen or
+ * invert the gate. Applied AFTER retrieve() with the exported recall gate
+ * (passesRelevanceGate: FTS/`both` hits pass regardless — a token match is
+ * real evidence; vector-only hits must clear the floor) — the same post-hoc
+ * shape /recall-index uses, so the two recall surfaces gate identically.
+ */
+export declare function resolveSearchSimilarityFloor(raw: unknown): number | undefined;
 /**
  * Express error middleware (#7): translate express.json's default HTML 413
  * (entity.too.large) into a consistent JSON response. Catches body-parser