@gamaze/hicortex 0.20.7 → 0.20.10

package/dist/relink.js

@@ -134,7 +134,6 @@ async function runRelink(options = {}) {
             `This machine is a client of ${config.serverUrl ?? "a remote server"} — run relink on the server.`);
     }
     // Classification is heuristic-only — no LLM client, no budget cap.
-    const budget = new consolidate_js_1.BudgetTracker(Number.MAX_SAFE_INTEGER);
     const dbPath = (0, db_js_1.resolveDbPath)(options.dbPath);
     const db = (0, db_js_1.initDb)(dbPath);
     const report = {
@@ -215,9 +214,9 @@ async function runRelink(options = {}) {
             report.skippedExisting += batchSkippedExisting;
             report.skippedDuplicate += batchSkippedDuplicate;
             // Phase B: classification — shared heuristic-only path (LLM retired).
-            // classifyLinkCandidates ignores the null LLM/budget and returns each
-            // candidate's heuristic type (extends/relates_to).
-            const classified = await (0, consolidate_js_1.classifyLinkCandidates)(candidates, null, budget);
+            // classifyLinkCandidates returns each candidate's heuristic type
+            // (extends/relates_to); #405 dropped its dead llm/budget params.
+            const classified = await (0, consolidate_js_1.classifyLinkCandidates)(candidates);
             const types = classified.types;
             report.llmClassified += classified.llmClassified; // always 0
             report.heuristicFallback += classified.heuristicFallback;

package/dist/rescore-importance.d.ts

@@ -0,0 +1,80 @@
+/**
+ * `hicortex rescore-importance` (#425) — the one-shot LLM backfill that
+ * re-judges the EXISTING corpus under the re-anchored importance rubric
+ * (owner decision D1, 2026-09-13: rescore via LLM, resumable, local
+ * gateway).
+ *
+ * Precedents, deliberately mixed per the issue's attribution:
+ *   - classify-domains (src/classify-domains.ts): resumable rowid cursor in
+ *     state.json, --batch rows per invocation, --reset, server-mode-only,
+ *     infra-error abort that leaves the cursor at the last committed batch.
+ *   - dedup (src/dedup.ts): dry-run DEFAULT with --apply, and a DB backup
+ *     taken FIRST — the CLI aborts (nothing written) if the backup fails.
+ *
+ * The scoring itself is the SHARED production loop — consolidate.ts
+ * `scoreMemoriesImportance` (the extracted stageImportance core): batches of
+ * 10, serial calls, the 0.95 write cap and the importance_scored_at
+ * watermark identical to the nightly. No forked scoring code.
+ *
+ * Scope: every LIVE (non-absorbed) memory, rowid-ascending. A row's
+ * corroboration_count survives untouched; base_strength is re-judged (that
+ * is D1's explicit trade: one rubric for all rows, the 2026-08-21-validated
+ * ORDERING is re-derived rather than mapped).
+ */
+import { LlmClient } from "./llm.js";
+export interface RescoreImportanceOptions {
+    /** Execute (default: dry run — report only, zero writes, no backup). */
+    apply?: boolean;
+    /** Rows per invocation chunk (default 500). */
+    batchSize?: number;
+    /** Ignore the saved cursor and restart from rowid 0. */
+    reset?: boolean;
+    /** DB path override (tests). Defaults to resolveDbPath(). */
+    dbPath?: string;
+    /** State dir override (tests). Defaults to ~/.hicortex. */
+    stateDir?: string;
+    /** LLM override (tests). Bypasses config resolution. */
+    llm?: LlmClient;
+    /** Config override (tests). Defaults to reading stateDir/config.json. */
+    config?: Record<string, unknown> | null;
+}
+export interface RescoreImportanceReport {
+    /** True when this invocation was a dry run (zero writes). */
+    dryRun: boolean;
+    /** Live rows remaining to process AFTER this invocation (whole corpus minus cursor). */
+    remaining: number;
+    /** Rows this invocation re-judged (0 on a dry run). */
+    rescored: number;
+    /** Rows whose scoring call failed (endpoint down / unusable) — untouched. */
+    failed: number;
+    /** LLM calls made (10 rows each). */
+    calls: number;
+    /** Cursor after this invocation. */
+    cursor: number;
+    /** True when the run stopped early on an infra error (cursor holds). */
+    aborted: boolean;
+    /** Path to the pre-run DB backup (apply mode only). */
+    backupPath?: string;
+    /** CURRENT base_strength percentiles over the remaining rows (preview). */
+    currentDistribution: DistributionPreview;
+    /** For apply runs over rows that were actually re-judged: before → after. */
+    before?: DistributionPreview;
+    after?: DistributionPreview;
+}
+export interface DistributionPreview {
+    n: number;
+    min: number;
+    p25: number;
+    median: number;
+    p75: number;
+    p90: number;
+    max: number;
+    atCeiling: number;
+    atSentinel: number;
+}
+/**
+ * Run the rescore pass. Returns a structured report. Throws on setup errors
+ * (client mode, no LLM, backup failure) — the cursor always reflects the
+ * last committed batch.
+ */
+export declare function runRescoreImportance(options?: RescoreImportanceOptions): Promise<RescoreImportanceReport>;

package/dist/rescore-importance.js

@@ -0,0 +1,236 @@
+"use strict";
+/**
+ * `hicortex rescore-importance` (#425) — the one-shot LLM backfill that
+ * re-judges the EXISTING corpus under the re-anchored importance rubric
+ * (owner decision D1, 2026-09-13: rescore via LLM, resumable, local
+ * gateway).
+ *
+ * Precedents, deliberately mixed per the issue's attribution:
+ *   - classify-domains (src/classify-domains.ts): resumable rowid cursor in
+ *     state.json, --batch rows per invocation, --reset, server-mode-only,
+ *     infra-error abort that leaves the cursor at the last committed batch.
+ *   - dedup (src/dedup.ts): dry-run DEFAULT with --apply, and a DB backup
+ *     taken FIRST — the CLI aborts (nothing written) if the backup fails.
+ *
+ * The scoring itself is the SHARED production loop — consolidate.ts
+ * `scoreMemoriesImportance` (the extracted stageImportance core): batches of
+ * 10, serial calls, the 0.95 write cap and the importance_scored_at
+ * watermark identical to the nightly. No forked scoring code.
+ *
+ * Scope: every LIVE (non-absorbed) memory, rowid-ascending. A row's
+ * corroboration_count survives untouched; base_strength is re-judged (that
+ * is D1's explicit trade: one rubric for all rows, the 2026-08-21-validated
+ * ORDERING is re-derived rather than mapped).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runRescoreImportance = runRescoreImportance;
+const node_fs_1 = require("node:fs");
+const node_fs_2 = require("node:fs");
+const node_path_1 = require("node:path");
+const paths_js_1 = require("./paths.js");
+const db_js_1 = require("./db.js");
+const state_js_1 = require("./state.js");
+const consolidate_js_1 = require("./consolidate.js");
+const llm_js_1 = require("./llm.js");
+const backup_js_1 = require("./backup.js");
+const config_read_js_1 = require("./config-read.js");
+const calibration_js_1 = require("./calibration.js");
+const HICORTEX_HOME = (0, paths_js_1.hicortexHome)();
+/** Rows per invocation chunk (LLM calls are 10 rows each inside a chunk). */
+const DEFAULT_BATCH = 500;
+/** The scoring loop's fixed 10-per-call slice (mirrors stageImportance). */
+const LLM_SLICE = 10;
+const PRE_RESCORE_BACKUP_PATTERN = /^pre-rescore-.*\.db$/;
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return Number.NaN;
+    const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil((p / 100) * sorted.length) - 1));
+    return sorted[idx];
+}
+function distributionPreview(values) {
+    const sorted = [...values].sort((a, b) => a - b);
+    return {
+        n: values.length,
+        min: percentile(sorted, 0),
+        p25: percentile(sorted, 25),
+        median: percentile(sorted, 50),
+        p75: percentile(sorted, 75),
+        p90: percentile(sorted, 90),
+        max: percentile(sorted, 100),
+        atCeiling: values.filter((v) => v >= calibration_js_1.IMPORTANCE_CEILING).length,
+        atSentinel: values.filter((v) => v === 0.5).length,
+    };
+}
+function readConfig(stateDir) {
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(stateDir, "config.json"), "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+function fetchChunk(db, cursor, limit) {
+    return db
+        .prepare(`SELECT rowid AS __rowid, id, base_strength FROM memories
+       WHERE rowid > ? AND COALESCE(status, '') != 'absorbed'
+       ORDER BY rowid ASC LIMIT ?`)
+        .all(cursor, limit);
+}
+function countRemaining(db, cursor) {
+    return db
+        .prepare(`SELECT COUNT(*) AS n FROM memories
+         WHERE rowid > ? AND COALESCE(status, '') != 'absorbed'`)
+        .get(cursor).n;
+}
+/** Full Memory rows for the ids in `rows` (the scoring loop's input type). */
+function memoriesForIds(db, rows) {
+    const byId = new Map(rows.map((r) => {
+        const mem = db
+            .prepare("SELECT * FROM memories WHERE id = ?")
+            .get(r.id);
+        return [r.id, mem];
+    }));
+    return rows.map((r) => byId.get(r.id)).filter((m) => m !== undefined);
+}
+/** Pre-run DB backup (the dedup precedent): throws on failure — abort. */
+async function takePreRescoreBackup(db, stateDir, config) {
+    const backupDir = (0, node_path_1.join)(stateDir, "backups");
+    (0, node_fs_2.mkdirSync)(backupDir, { recursive: true });
+    const backupPath = (0, node_path_1.join)(backupDir, `pre-rescore-${new Date().toISOString().replace(/[:.]/g, "-")}.db`);
+    await db.backup(backupPath);
+    const retention = (0, config_read_js_1.readNonNegativeConfig)(config ?? {}, "backupRetention", backup_js_1.DEFAULT_BACKUP_RETENTION);
+    (0, backup_js_1.pruneBackupArtifacts)(backupDir, retention, PRE_RESCORE_BACKUP_PATTERN);
+    return backupPath;
+}
+/**
+ * Run the rescore pass. Returns a structured report. Throws on setup errors
+ * (client mode, no LLM, backup failure) — the cursor always reflects the
+ * last committed batch.
+ */
+async function runRescoreImportance(options = {}) {
+    const batchSize = options.batchSize ?? DEFAULT_BATCH;
+    const stateDir = options.stateDir ?? HICORTEX_HOME;
+    const apply = options.apply ?? false;
+    if (!Number.isInteger(batchSize) || batchSize < 1) {
+        throw new Error(`[hicortex] rescore-importance: invalid --batch value: ${options.batchSize}`);
+    }
+    const config = options.config !== undefined ? options.config : readConfig(stateDir);
+    // Server-mode only — client installs have no local DB (classify-domains).
+    if (config?.mode === "client") {
+        throw new Error("[hicortex] rescore-importance is server-mode only (it needs the local DB). " +
+            `This machine is a client of ${config.serverUrl ?? "a remote server"} — run it on the server.`);
+    }
+    let llm;
+    if (options.llm) {
+        llm = options.llm;
+    }
+    else {
+        const resolved = (0, llm_js_1.resolveSavedLlmConfig)(config);
+        if (!resolved.config) {
+            throw new Error("[hicortex] rescore-importance: no LLM configured — run `npx @gamaze/hicortex init`.");
+        }
+        llm = new llm_js_1.LlmClient(resolved.config);
+    }
+    const dbPath = (0, db_js_1.resolveDbPath)(options.dbPath);
+    const db = (0, db_js_1.initDb)(dbPath);
+    try {
+        let cursor = options.reset ? 0 : ((0, state_js_1.loadState)(stateDir).rescoreImportanceCursor ?? 0);
+        const remaining = countRemaining(db, cursor);
+        const plannedCalls = Math.ceil(Math.min(remaining, batchSize) / LLM_SLICE);
+        // Current distribution preview over the REMAINING rows (what is queued).
+        const remainingRows = fetchChunk(db, cursor, Number.MAX_SAFE_INTEGER);
+        const currentDistribution = distributionPreview(remainingRows.map((r) => r.base_strength ?? 0.5));
+        console.log(`[hicortex] rescore-importance ${apply ? "APPLY" : "dry run"}: ${remaining} live rows queued, ` +
+            `batch ${batchSize}, cursor ${cursor}${options.reset ? " (reset)" : ""}, ` +
+            `~${plannedCalls} LLM calls this invocation (10 rows each)`);
+        console.log(`[hicortex]   current base_strength of queued rows: median ${currentDistribution.median.toFixed(2)}, ` +
+            `p90 ${currentDistribution.p90.toFixed(2)}, max ${currentDistribution.max.toFixed(2)}, ` +
+            `at ceiling ${currentDistribution.atCeiling}, at 0.5 sentinel ${currentDistribution.atSentinel}`);
+        if (!apply) {
+            console.log("[hicortex] rescore-importance dry run complete — zero writes. Re-run with --apply to execute.");
+            return {
+                dryRun: true,
+                remaining,
+                rescored: 0,
+                failed: 0,
+                calls: 0,
+                cursor,
+                aborted: false,
+                currentDistribution,
+            };
+        }
+        // Backup FIRST (dedup precedent) — abort with zero writes if it fails.
+        const backupPath = await takePreRescoreBackup(db, stateDir, config);
+        console.log(`[hicortex] rescore-importance backup written: ${backupPath}`);
+        const chunk = fetchChunk(db, cursor, batchSize);
+        const before = distributionPreview(chunk.map((r) => r.base_strength ?? 0.5));
+        let rescored = 0;
+        let failed = 0;
+        let calls = 0;
+        let committedRowid = cursor;
+        let aborted = false;
+        const touchedIds = [];
+        // LLM slices of 10 INSIDE the invocation chunk, cursor-ordered: an infra
+        // error holds the cursor at the last fully committed slice (the
+        // classify-domains posture — the failing rows are untouched, re-run
+        // resumes there).
+        for (let i = 0; i < chunk.length; i += LLM_SLICE) {
+            const sliceRows = chunk.slice(i, i + LLM_SLICE);
+            const memories = memoriesForIds(db, sliceRows);
+            const r = await (0, consolidate_js_1.scoreMemoriesImportance)(db, memories, llm, {
+                onBatch: (written, batchFailed) => {
+                    calls++;
+                },
+            });
+            if (r.failed > 0) {
+                // The slice's call threw (endpoint down) or a write failed — nothing
+                // usable came out of it. Stop; the cursor stays at the last
+                // committed slice's end.
+                failed += r.failed;
+                aborted = true;
+                console.warn(`[hicortex] rescore-importance ABORTED on a scoring-endpoint error ` +
+                    `(slice at rowid ${sliceRows[0].__rowid}). Cursor at last committed slice — ` +
+                    `re-run when the endpoint is back up.`);
+                break;
+            }
+            rescored += r.scored;
+            touchedIds.push(...sliceRows.map((row) => row.id));
+            committedRowid = sliceRows[sliceRows.length - 1].__rowid;
+            (0, state_js_1.updateState)((s) => { s.rescoreImportanceCursor = committedRowid; }, stateDir);
+            if ((i / LLM_SLICE) % 25 === 0) {
+                console.log(`[hicortex]   ${rescored} rows re-judged (cursor ${committedRowid}, ` +
+                    `${countRemaining(db, committedRowid)} remaining)`);
+            }
+        }
+        cursor = committedRowid;
+        // before → after over the rows this invocation actually touched.
+        const afterRows = touchedIds
+            .map((id) => db
+            .prepare("SELECT base_strength FROM memories WHERE id = ?")
+            .get(id))
+            .filter((r) => r !== undefined);
+        const after = distributionPreview(afterRows.map((r) => r.base_strength ?? 0.5));
+        const afterLog = (label, d) => `${label}: median ${d.median.toFixed(2)} p90 ${d.p90.toFixed(2)} max ${d.max.toFixed(2)} at-ceiling ${d.atCeiling}`;
+        console.log(`[hicortex] rescore-importance ${aborted ? "ABORTED" : "chunk complete"}: ` +
+            `${rescored} re-judged, ${failed} failed, ${calls} calls, cursor ${cursor}, ` +
+            `${countRemaining(db, cursor)} remaining`);
+        console.log(`[hicortex]   re-judged rows — ${afterLog("before", before)}`);
+        console.log(`[hicortex]   re-judged rows — ${afterLog("after ", after)}`);
+        return {
+            dryRun: false,
+            remaining: countRemaining(db, cursor),
+            rescored,
+            failed,
+            calls,
+            cursor,
+            aborted,
+            backupPath,
+            currentDistribution,
+            before,
+            after,
+        };
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/retrieval.d.ts

@@ -2,14 +2,15 @@
  * Retrieval layer with composite scoring, RRF fusion, and graph traversal.
  * Ported from hicortex/retrieval.py — same scoring model and weights.
  *
- * Scoring model (weights are config-driven since 0.15.2 — see configureScoring):
+ * Scoring model (weights are RELEASE-MANAGED since #408 — calibration.ts;
+ * configureScoring is the eval/test seam only):
  *   score = similarity * 0.50 + effective_strength * 0.20
  *         + connection_score * 0.15 + recency * 0.15
  *         + fresh-memory bonus (≤ 0.15, linear over the first 7 days)
  *         then × 0.50 if the memory was superseded by a later decision
  *
  * Decay model (B+E+D):
- *   base_decay = derived from decayHalfLifeDays (config; default 365 → ~1-year
+ *   base_decay = derived from the calibration half-life (365 → ~1-year
  *                half-life at importance 0.5, importance-scaled either way)
  *   decay_rate = 1 - base_decay * (1 - importance)
  *   decay_rate = 1 - (1 - decay_rate) * 0.7^access_count
@@ -19,10 +20,8 @@
  */
 import type Database from "better-sqlite3";
 import type { Memory, MemorySearchResult } from "./types.js";
-/** Default decay half-life (days) at importance 0.5. #192: was 0.0005/h
- *  (~115-day half-life at base 0.5) — aggressive enough to bury the long tail
- *  in ranking. Long-term remembering is the product; time preference stays,
- *  but mild. */
+/** Default decay half-life (days) at importance 0.5 — release-managed
+ *  (#408): the constant lives in calibration.ts with its provenance. */
 export declare const DEFAULT_DECAY_HALF_LIFE_DAYS = 365;
 /**
  * Derive the per-hour base decay constant from a half-life target: for the
@@ -33,26 +32,26 @@ export declare const DEFAULT_DECAY_HALF_LIFE_DAYS = 365;
  */
 export declare function decayConstantForHalfLife(days: number): number;
 /**
- * Configure the decay speed from config (`decayHalfLifeDays`). Called at boot
- * by the server and the nightly so both processes score with the same clock.
- * Invalid/absent values keep the default. Exported value for tests.
+ * Configure the decay speed for THIS process (the eval/test seam — #408).
+ * Production NEVER passes an argument: every process scores with the
+ * calibration half-life (calibration.ts DECAY_HALF_LIFE_DAYS). An
+ * invalid/absent value keeps the default. Exported value for tests.
  */
-export declare function configureDecay(options?: {
-    halfLifeDays?: unknown;
-}): number;
-interface RecallDefaults {
+export declare function configureDecay(halfLifeDays?: number): number;
+export interface RecallDefaults {
     searchLimit: number;
     recentLimit: number;
     recentWindowDays: number;
     coldExposureSlots: number;
 }
 /**
- * Configure recall breadth from config. Called at boot next to
- * configureDecay(); invalid/absent values keep the shipped defaults.
- * Returns the resolved values (for logging + tests).
+ * Configure recall breadth from RESOLVED overrides (the eval/test seam —
+ * #408). Production calls this with no argument: the calibration defaults
+ * (calibration.ts) apply. Invalid/absent values keep the shipped default per
+ * key. Returns the resolved values (for logging + tests).
  */
-export declare function configureRecall(config?: Record<string, unknown> | null): RecallDefaults;
-interface ScoringWeights {
+export declare function configureRecall(overrides?: Partial<RecallDefaults> | null): RecallDefaults;
+export interface ScoringWeights {
     similarity: number;
     strength: number;
     connections: number;
@@ -72,31 +71,32 @@ interface ScoringWeights {
     rrfFtsWeight: number;
     /** #205 per-list RRF weight for the vector list (KNN-driven candidates). */
     rrfVectorWeight: number;
+    /** #425 additive boost for both-channel (vector AND FTS) candidates. */
+    bothChannelBoost: number;
 }
 /**
- * Configure scoring weights + ranking knobs from config. Called at boot by the
- * server and the nightly (alongside configureDecay/configureRecall) so
- * retrieval and consolidation rank identically. Invalid/absent values keep the
- * shipped default per key. Returns the resolved set for logging/tests. Also
- * pushes the #205 BM25F field weights into storage (storage.configureBm25Fts)
- * so searchFts ranks with the same config — BM25F weights live in storage.ts
- * (next to the FTS column declaration they mirror) but are read here from the
- * SAME config object for one-place tuning.
+ * Configure scoring weights + ranking knobs from RESOLVED overrides (the
+ * eval/test seam — #408). Production calls this with no argument: the
+ * calibration defaults (calibration.ts) apply, identically in the daemon and
+ * the nightly. Invalid/absent values keep the shipped default per key.
+ * Returns the resolved set for logging/tests. (The #205 BM25F field weights
+ * are NOT touched here — they live in storage.ts and resolve from the same
+ * calibration module via storage.configureBm25Fts.)
  */
-export declare function configureScoring(config?: Record<string, unknown> | null): ScoringWeights;
+export declare function configureScoring(overrides?: Partial<ScoringWeights> | null): ScoringWeights;
 /** Current resolved weights (tests + status output). */
 export declare function getScoringWeights(): ScoringWeights;
 /** EMA rate for the session-intent centroid: centroid_new = (1-α)·old + α·prompt. */
 export declare const SESSION_INTENT_ALPHA = 0.4;
 /**
- * Configure session-intent keying from config. Called at server boot next to
- * configureScoring (the nightly does no recall, so it does not need this).
- * Reads only `sessionIntentWeight` ([0,1]; 0 = disabled). Invalid/out-of-range
- * values keep the shipped default. Returns `{ weight, alpha }` — alpha is the
- * fixed constant, surfaced so the recall closure passes it to the registry in
- * one call.
+ * Configure session-intent keying for THIS process (the eval/test seam —
+ * #408). Production calls this with no argument: the calibration weight
+ * (calibration.ts SESSION_INTENT_WEIGHT) applies. `weight` is [0,1] (0 =
+ * disabled — the eval kill-switch); invalid/out-of-range values keep the
+ * shipped default. Returns `{ weight, alpha }` — alpha is the fixed constant,
+ * surfaced so the recall closure passes it to the registry in one call.
  */
-export declare function configureSessionIntent(config?: Record<string, unknown> | null): {
+export declare function configureSessionIntent(weight?: number): {
     weight: number;
     alpha: number;
 };
@@ -161,6 +161,32 @@ export declare function findSupersededIds(db: Database.Database, candidateIds: s
  * (NULL status, no link) — they never match either arm.
  */
 export declare function findDemotedIds(db: Database.Database, candidateIds: string[]): Set<string>;
+/**
+ * Hop cap for the belief walk (#393 D). Supersession edges advance
+ * created_at monotonically (the stage only links old → new), so chains are
+ * acyclic by construction and 10 hops is far beyond any real revision depth;
+ * the cap is cheap insurance (see beliefWalkTerminal for why it is needed
+ * anyway).
+ */
+export declare const BELIEF_WALK_MAX_HOPS = 10;
+/**
+ * Terminal of the supersession chain starting at `id` (#393 D): follow
+ * superseded_by edges transitively until a memory with no outgoing edge and
+ * return it — `id` itself when there is nothing to walk, or whichever node
+ * the walk stopped on when it aborts. Shared by retrieval (the belief-walk
+ * splice in retrieve()/searchRecent()) and the eval harness (the
+ * planted-pairs version_chain class probe), so both agree on what "the
+ * chain's current truth" is.
+ *
+ * Edges advance created_at monotonically (acyclic by construction), BUT
+ * applyExplicitMark does no age check and created_at is backdatable from
+ * session_date — so a cycle or an absurdly long chain is not impossible.
+ * The visited set (seeded with `id`) and the BELIEF_WALK_MAX_HOPS cap are
+ * cheap insurance against exactly that; the supersededDemotion multiplier
+ * in computeScore remains the safety net for rows the walk does not fully
+ * resolve (no edge, cycle, cap abort, absorbed terminal).
+ */
+export declare function beliefWalkTerminal(db: Database.Database, id: string, maxHops?: number): string;
 /**
  * Convert an L2 distance (as returned by sqlite-vec's vec0 `distance`) to
  * cosine similarity. Valid because our embeddings are L2-normalized
@@ -171,9 +197,25 @@ export declare function findDemotedIds(db: Database.Database, candidateIds: stri
  * by consolidate.ts so pre-#145 importers keep working.
  */
 export declare function l2ToCosine(distance: number): number;
+/**
+ * Cosine similarity between two stored embeddings (#393 increment B). The
+ * similarity source measures cosines transitively via vec0 L2 distances; the
+ * scout source finds its candidates through FTS (no vec0 query), so it
+ * measures the pair cosine directly from the stored vectors instead —
+ * valid because every embedding we store is L2-normalized (embedder.ts).
+ * Used as link strength / a ranker, never as a gate (the scout has no
+ * similarity floor — that is the point of the increment).
+ */
+export declare function cosineBetweenVectors(a: Float32Array, b: Float32Array): number;
 /**
  * Compute decayed strength with adaptive decay (B+E+D model).
  * Exported for use by consolidation decay/prune stage.
+ *
+ * #425 read-side law: the decay-relevant importance is CLAMPED at the
+ * release-managed ceiling (calibration.ts IMPORTANCE_CEILING) — at importance
+ * exactly 1.0 the decay rate is exactly 1.0 and the row never decays, so
+ * legacy base-1.0 rows (and any write site that predates the cap) decay
+ * again. The clamp applies to explicit importance passes too.
  */
 export declare function effectiveStrength(baseStrength: number, lastAccessed: string | null, now: Date, options?: {
     importance?: number;
@@ -208,6 +250,10 @@ export declare function computeScore(memory: Memory, distance: number, connectio
         tag: string;
         weight: number | null;
     }>;
+    /** #425: the candidate was matched by BOTH retrieval channels (vector
+     *  KNN AND BM25 FTS) — the genuine-match signature. Adds the
+     *  release-managed bothChannelBoost (zero-boost neutral). */
+    bothChannel?: boolean;
 }): number;
 export interface EmbedFn {
     (text: string): Promise<Float32Array>;
@@ -264,4 +310,3 @@ export declare function searchRecent(db: Database.Database, options?: {
     project?: string | null;
     limit?: number;
 }): MemorySearchResult[];
-export {};