@gamaze/hicortex 0.20.9 → 0.21.0

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

@@ -71,6 +71,8 @@ export 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 RESOLVED overrides (the
@@ -208,6 +210,12 @@ export declare function cosineBetweenVectors(a: Float32Array, b: Float32Array):
 /**
  * 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;
@@ -242,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>;

package/dist/retrieval.js

@@ -146,6 +146,10 @@ const SCORING_DEFAULTS = {
     rrfCompositeWeight: CALIBRATION.RRF_COMPOSITE_WEIGHT,
     rrfFtsWeight: CALIBRATION.RRF_FTS_WEIGHT,
     rrfVectorWeight: CALIBRATION.RRF_VECTOR_WEIGHT,
+    // #425 (calibration.ts): the both-channel genuine-match boost. 0.10 is
+    // the sweep-chosen size — D3's dominance margin (>= 0.10 x the similarity
+    // weight) with the battery stability gates intact.
+    bothChannelBoost: CALIBRATION.BOTH_CHANNEL_BOOST,
 };
 let scoringWeights = { ...SCORING_DEFAULTS };
 /**
@@ -182,6 +186,7 @@ function configureScoring(overrides) {
         rrfCompositeWeight: num(overrides?.rrfCompositeWeight, SCORING_DEFAULTS.rrfCompositeWeight, 0, 1),
         rrfFtsWeight: numW(overrides?.rrfFtsWeight, SCORING_DEFAULTS.rrfFtsWeight),
         rrfVectorWeight: numW(overrides?.rrfVectorWeight, SCORING_DEFAULTS.rrfVectorWeight),
+        bothChannelBoost: num(overrides?.bothChannelBoost, SCORING_DEFAULTS.bothChannelBoost, 0, 1),
     };
     return { ...scoringWeights };
 }
@@ -483,9 +488,16 @@ function parseTimestamp(ts) {
 /**
  * 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.
  */
 function effectiveStrength(baseStrength, lastAccessed, now, options) {
-    const importance = options?.importance ?? baseStrength;
+    const rawImportance = options?.importance ?? baseStrength;
+    const importance = Math.min(rawImportance, CALIBRATION.IMPORTANCE_CEILING);
     const accessCount = options?.accessCount ?? 0;
     const linkCount = options?.linkCount ?? 0;
     const hours = Math.max((now.getTime() - parseTimestamp(lastAccessed).getTime()) / 3_600_000, 0);
@@ -512,6 +524,11 @@ function computeScore(memory, distance, connectionCount, maxConnections, now, op
     // is a data-driven follow-up if the eval shows it is needed.
     const similarity = Math.max(0, l2ToCosine(distance));
     const effStrength = effectiveStrength(memory.base_strength ?? 0.5, memory.last_accessed, now, {
+        // #425: importance passed EXPLICITLY (the same default value
+        // effectiveStrength would apply — base strength IS importance at read
+        // time — now stated at the call site so the triple-win coupling
+        // (score share, decay rate, floor) is visible and single-sourced).
+        importance: memory.base_strength ?? 0.5,
         accessCount: memory.access_count ?? 0,
         linkCount: connectionCount,
     });
@@ -567,6 +584,15 @@ function computeScore(memory, distance, connectionCount, maxConnections, now, op
                 score += maxWeight * scoringWeights.domainAffinity;
         }
     }
+    // #425 both-channel boost: vector KNN and BM25 FTS AGREEING on a candidate
+    // is the genuine-match signature (a distinctive proper noun the user knows
+    // exists — the field failure this fixes: 0.90/0.95-strength domain-adjacent
+    // memories outranked the best-similarity exact-token match). ADDITIVE,
+    // zero-boost neutral, never a penalty; rides the composite side only (like
+    // projectAffinity — the RRF side is #205 territory); applied BEFORE the
+    // superseded multiplier so a superseded both-channel row still demotes.
+    if (options?.bothChannel)
+        score += scoringWeights.bothChannelBoost;
     // Superseded demotion (#191 Phase B): a memory whose decision was reversed by
     // a later one keeps its content and strength but must not outrank the
     // decision that replaced it. Applied as an explicit multiplier here rather
@@ -802,6 +828,9 @@ async function retrieve(db, embedFn, query, options) {
             superseded: supersededIds.has(mid),
             scope,
             tagWeights: tagWeightsByMemory?.get(mid),
+            // #425: the two retrieval channels agreeing is the genuine-match
+            // signature — graph-only and single-channel candidates add nothing.
+            bothChannel: source === "both",
         });
         const effStr = effectiveStrength(mem.base_strength ?? 0.5, mem.last_accessed, now, {
             accessCount: mem.access_count ?? 0,

package/dist/stages.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Memory maturity stages — the console's derived presentation layer
+ * (#409/#421 Phase 1).
+ *
+ * The E-reframe (standing ruling in the #409 thread): stages are DERIVED
+ * presentation of the one numeric strength signal, never stored state. This
+ * module holds the pure derivation only — thresholds live in calibration.ts
+ * (the #408 single home, release-managed with the evolution contract); no
+ * db, no I/O, no config reads.
+ *
+ * Wire keys are forming/belief/truth/fading (lifecycle order). The console
+ * renders human labels over these keys; nothing else consumes them.
+ */
+/** A memory's derived maturity stage (lifecycle order). */
+export type Stage = "forming" | "belief" | "truth" | "fading";
+/** The four stages in lifecycle order: forming → belief → truth → fading. */
+export declare const STAGE_KEYS: readonly Stage[];
+/**
+ * Derive a memory's stage from its effective strength and recency.
+ *
+ * The recency gate runs FIRST: a memory untouched for
+ * STAGE_FADING_DAYS days is Fading no matter how strong it is — decay is a
+ * function of access in this system (effectiveStrength already folds
+ * last_accessed in, but the gate makes long silence legible on its own).
+ * Then the strength bands (calibrated against the measured production
+ * distribution — see calibration.ts): < FADING → fading (the weak cluster),
+ * ≥ TRUTH → truth, ≥ BELIEF → belief, else forming.
+ *
+ * `daysSinceAccess` is whole days (UTC day diff is fine — capture is
+ * night-resolution) since the memory was last touched. The DASHBOARD handler
+ * passes days since `last_accessed`, falling back to days since `created_at`
+ * when last_accessed is NULL (never accessed since ingest — creation is the
+ * last real signal). `null` means "recency unknown" and skips the gate
+ * (strength-only derivation) — the handler never sends it; it exists so the
+ * function is total over caller data quality.
+ */
+export declare function deriveStage(effectiveStrength: number, daysSinceAccess: number | null): Stage;

package/dist/stages.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Memory maturity stages — the console's derived presentation layer
+ * (#409/#421 Phase 1).
+ *
+ * The E-reframe (standing ruling in the #409 thread): stages are DERIVED
+ * presentation of the one numeric strength signal, never stored state. This
+ * module holds the pure derivation only — thresholds live in calibration.ts
+ * (the #408 single home, release-managed with the evolution contract); no
+ * db, no I/O, no config reads.
+ *
+ * Wire keys are forming/belief/truth/fading (lifecycle order). The console
+ * renders human labels over these keys; nothing else consumes them.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STAGE_KEYS = void 0;
+exports.deriveStage = deriveStage;
+const calibration_js_1 = require("./calibration.js");
+/** The four stages in lifecycle order: forming → belief → truth → fading. */
+exports.STAGE_KEYS = ["forming", "belief", "truth", "fading"];
+/**
+ * Derive a memory's stage from its effective strength and recency.
+ *
+ * The recency gate runs FIRST: a memory untouched for
+ * STAGE_FADING_DAYS days is Fading no matter how strong it is — decay is a
+ * function of access in this system (effectiveStrength already folds
+ * last_accessed in, but the gate makes long silence legible on its own).
+ * Then the strength bands (calibrated against the measured production
+ * distribution — see calibration.ts): < FADING → fading (the weak cluster),
+ * ≥ TRUTH → truth, ≥ BELIEF → belief, else forming.
+ *
+ * `daysSinceAccess` is whole days (UTC day diff is fine — capture is
+ * night-resolution) since the memory was last touched. The DASHBOARD handler
+ * passes days since `last_accessed`, falling back to days since `created_at`
+ * when last_accessed is NULL (never accessed since ingest — creation is the
+ * last real signal). `null` means "recency unknown" and skips the gate
+ * (strength-only derivation) — the handler never sends it; it exists so the
+ * function is total over caller data quality.
+ */
+function deriveStage(effectiveStrength, daysSinceAccess) {
+    if (daysSinceAccess !== null && daysSinceAccess >= calibration_js_1.STAGE_FADING_DAYS) {
+        return "fading";
+    }
+    if (effectiveStrength < calibration_js_1.STAGE_FADING_STRENGTH)
+        return "fading";
+    if (effectiveStrength >= calibration_js_1.STAGE_TRUTH_STRENGTH)
+        return "truth";
+    if (effectiveStrength >= calibration_js_1.STAGE_BELIEF_STRENGTH)
+        return "belief";
+    return "forming";
+}

package/dist/state.d.ts

@@ -62,14 +62,32 @@ export interface HicortexState {
     /**
      * Resume cursor for the nightly's reconsolidation stage (#384) — highest
      * memories.rowid whose candidates have been evaluated (or infra-skipped)
-     * this run. Absent/0 = never run. Same advance-past-considered-candidates
-     * discipline as supersessionCursor, with one addition: when a rewrite group
-     * could not be applied (budget exhausted / rewrite-call infra error), the
-     * cursor holds BELOW the earliest candidate contributing to an un-applied
-     * group so those pairs are re-detected next run — a confirmed correction is
-     * never silently dropped by the cursor passing it.
+     * with all their CONFIRMED work applied. Absent/0 = never run. Same
+     * advance-past-considered-candidates discipline as supersessionCursor,
+     * with one addition (#439): confirmed merges and rewrite groups apply at
+     * the candidate boundary — the END of the iteration that confirmed them —
+     * and the cursor advances past a candidate only when that apply landed.
+     * A deferral (budget refusal at the rewrite call, deadline at the
+     * boundary, backup failure, lock-busy merge surviving the final drain)
+     * holds the cursor BELOW the current candidate, so the hold is bounded to
+     * ONE candidate's pairs: next run re-detects and re-judges exactly those
+     * (dup-over-loss — a confirmed resolution is never silently dropped by the
+     * cursor passing it). The ONE cross-candidate window is the lock-busy
+     * retry list (plus deadline/backup-dropped tails re-queued at their
+     * boundary): while any retry merge is pending, every persisted checkpoint
+     * clamps below its earliest contributor, so a killed or stopped run can
+     * never strand a confirmed merge behind the cursor (fix round, #440).
      */
     reconsolidationCursor?: number;
+    /**
+     * #439 scan high-water for the reconsolidation stage — the highest
+     * memories.rowid any run has ENTERED, never held back by un-applied work
+     * (unlike reconsolidationCursor, which holds below deferred applies).
+     * Seeds the re-judged/new verdict split: a verdict call on a candidate
+     * at/below this mark is a re-judgment of previously judged work. Absent =
+     * never run; persisted alongside the cursor at every checkpoint.
+     */
+    reconsolidationScannedRowid?: number;
     /**
      * Resume cursor for `hicortex classify-types` (#216) — highest memories.rowid
      * whose batch has been fully committed. Absent/0 = never run (or reset).
@@ -77,6 +95,14 @@ export interface HicortexState {
      * interruption never loses more than the in-flight batch.
      */
     typeCursor?: number;
+    /**
+     * Resume cursor for `hicortex rescore-importance` (#425) — highest live
+     * memories.rowid re-judged under the current rubric. Absent/0 = never run
+     * (or reset). Advances per committed batch (LLM calls are 10 rows each
+     * inside a `--batch` slice); an infra error holds it at the last fully
+     * committed slice so a re-run resumes cleanly.
+     */
+    rescoreImportanceCursor?: number;
     /**
      * LLM token usage accrued this billing period (#246). Period reset is
      * monthly: when `periodStart` is in a previous calendar month, the totals

package/dist/storage.d.ts

@@ -8,6 +8,13 @@ import type { Memory, MemoryLink, InsertMemoryOptions } from "./types.js";
  * Serialize a Float32Array embedding to a Buffer for sqlite-vec.
  */
 export declare function embedToBlob(embedding: Float32Array): Buffer;
+/**
+ * #421 machine × harness identity: optional capture-machine provenance on
+ * /ingest + /distill. A string, trimmed, capped at 128 chars; anything else
+ * (absent, wrong type, blank) becomes NULL — a wrong machine name is worse
+ * than none. Never filtered; presentation grouping only.
+ */
+export declare function sanitizeSourceMachine(v: unknown): string | null;
 /**
  * Insert a memory and its vector embedding. Returns the memory's UUID.
  *
@@ -35,6 +42,28 @@ export declare function updateMemory(db: Database.Database, memoryId: string, fi
  * Atomically increment access_count and reset last_accessed.
  */
 export declare function strengthenMemory(db: Database.Database, memoryId: string, nowIsoStr: string): void;
+/**
+ * Record an owner corroboration (#423 phase 3): one UPDATE that bumps
+ * corroboration_count, nudges base_strength up by the calibration delta
+ * (MIN-capped at the importance ceiling, #425; COALESCE keeps NULL bases
+ * honest — the unscored default), stamps the importance watermark, and
+ * refreshes last_accessed (the console's "last confirmed" cell reads it: an
+ * enrich IS a confirmation, and it keeps the stage fading gate honest).
+ * EVIDENCE ABOUT IMPORTANCE ONLY — never access_count (reserved for real
+ * recall use) nor shown_count (index exposure): faking either corrupts the
+ * uses-per-showing adoption metric.
+ *
+ * Nightly interaction: the importance pool keys on importance_scored_at IS
+ * NULL (#425), so the watermark stamp here keeps the pre-#425 contract — an
+ * enriched memory leaves the pool and the owner's mark stands in for (and is
+ * never stomped by) the first LLM score. Dedup merges take
+ * max(base_strength), so a merge never loses the mark. Returns the fresh row
+ * values (re-read after the update); null when the id matches nothing.
+ */
+export declare function enrichMemory(db: Database.Database, memoryId: string, nowIsoStr: string): {
+    corroborationCount: number;
+    baseStrength: number;
+} | null;
 /**
  * Record that memories appeared in a pushed recall index (#192): bump
  * shown_count and refresh last_accessed (a mild strengthen — the decay clock
@@ -267,8 +296,11 @@ export declare function getPruneCandidates(db: Database.Database, cutoffIso: str
  */
 export declare function getAllLinkCounts(db: Database.Database): Map<string, number>;
 /**
- * Get all memories with default base_strength (never scored).
- * Absorbed memories are excluded (#384): they are invisible to recall, so
+ * Get all never-scored memories — the nightly importance pool, keyed on the
+ * importance_scored_at watermark (#425, migration v19). The pre-v19 sentinel
+ * (`base_strength = 0.5`) re-rolled every row the model genuinely scored
+ * 0.5, every night; NULL watermark = never scored under ANY rubric. Absorbed
+ * memories are excluded (#384): they are invisible to recall, so
  * importance-scoring one would spend an LLM call on dead evidence.
  */
 export declare function getUnscoredMemories(db: Database.Database): Memory[];