@gamaze/hicortex 0.20.7 → 0.20.9

package/dist/retrieval.js

@@ -3,14 +3,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
@@ -52,7 +53,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SESSION_INTENT_ALPHA = exports.DEFAULT_DECAY_HALF_LIFE_DAYS = void 0;
+exports.BELIEF_WALK_MAX_HOPS = exports.SESSION_INTENT_ALPHA = exports.DEFAULT_DECAY_HALF_LIFE_DAYS = void 0;
 exports.decayConstantForHalfLife = decayConstantForHalfLife;
 exports.configureDecay = configureDecay;
 exports.configureRecall = configureRecall;
@@ -64,7 +65,9 @@ exports.blendQueryVector = blendQueryVector;
 exports.recallQueryVector = recallQueryVector;
 exports.findSupersededIds = findSupersededIds;
 exports.findDemotedIds = findDemotedIds;
+exports.beliefWalkTerminal = beliefWalkTerminal;
 exports.l2ToCosine = l2ToCosine;
+exports.cosineBetweenVectors = cosineBetweenVectors;
 exports.effectiveStrength = effectiveStrength;
 exports.computeScore = computeScore;
 exports.retrieve = retrieve;
@@ -72,11 +75,10 @@ exports.searchRecent = searchRecent;
 const storage = __importStar(require("./storage.js"));
 const schema_prototypes_js_1 = require("./schema-prototypes.js");
 const type_labels_js_1 = require("./type-labels.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. */
-exports.DEFAULT_DECAY_HALF_LIFE_DAYS = 365;
+const CALIBRATION = __importStar(require("./calibration.js"));
+/** Default decay half-life (days) at importance 0.5 — release-managed
+ *  (#408): the constant lives in calibration.ts with its provenance. */
+exports.DEFAULT_DECAY_HALF_LIFE_DAYS = CALIBRATION.DECAY_HALF_LIFE_DAYS;
 /**
  * Derive the per-hour base decay constant from a half-life target: for the
  * decayable portion, retention^hours = 0.5 at `days`, evaluated at the
@@ -89,110 +91,98 @@ function decayConstantForHalfLife(days) {
 }
 let BASE_DECAY = decayConstantForHalfLife(exports.DEFAULT_DECAY_HALF_LIFE_DAYS);
 /**
- * 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.
  */
-function configureDecay(options) {
-    const days = Number(options?.halfLifeDays);
+function configureDecay(halfLifeDays) {
+    const days = Number(halfLifeDays);
     BASE_DECAY = decayConstantForHalfLife(Number.isFinite(days) && days > 0 ? days : exports.DEFAULT_DECAY_HALF_LIFE_DAYS);
     return BASE_DECAY;
 }
 const RECALL_DEFAULTS = {
-    searchLimit: 8,
-    recentLimit: 12,
-    recentWindowDays: 180,
-    coldExposureSlots: 2,
+    searchLimit: CALIBRATION.SEARCH_LIMIT,
+    recentLimit: CALIBRATION.RECENT_LIMIT,
+    recentWindowDays: CALIBRATION.RECENT_WINDOW_DAYS,
+    coldExposureSlots: CALIBRATION.COLD_EXPOSURE_SLOTS,
 };
 let recallDefaults = { ...RECALL_DEFAULTS };
 /**
- * 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).
  */
-function configureRecall(config) {
-    const pick = (key) => {
-        const v = Number(config?.[key]);
-        return Number.isFinite(v) && v >= 0 ? Math.floor(v) : RECALL_DEFAULTS[key];
+function configureRecall(overrides) {
+    const pick = (v, dflt) => {
+        const n = Number(v);
+        return Number.isFinite(n) && n >= 0 ? Math.floor(n) : dflt;
     };
     recallDefaults = {
-        searchLimit: Math.max(1, pick("searchLimit")),
-        recentLimit: Math.max(1, pick("recentLimit")),
-        recentWindowDays: Math.max(1, pick("recentWindowDays")),
-        coldExposureSlots: pick("coldExposureSlots"),
+        searchLimit: Math.max(1, pick(overrides?.searchLimit, RECALL_DEFAULTS.searchLimit)),
+        recentLimit: Math.max(1, pick(overrides?.recentLimit, RECALL_DEFAULTS.recentLimit)),
+        recentWindowDays: Math.max(1, pick(overrides?.recentWindowDays, RECALL_DEFAULTS.recentWindowDays)),
+        coldExposureSlots: pick(overrides?.coldExposureSlots, RECALL_DEFAULTS.coldExposureSlots),
     };
     return { ...recallDefaults };
 }
 const SCORING_DEFAULTS = {
-    similarity: 0.5,
-    strength: 0.2,
-    connections: 0.15,
-    recency: 0.15,
-    freshnessBoostDays: 7,
-    freshnessBoostWeight: 0.15,
-    supersededDemotion: 0.5,
-    projectAffinity: 0.15,
-    domainAffinity: 0.15,
-    // #205 defaults: rrfK + rrfCompositeWeight match the pre-#205 hardcoded
-    // values (60 and 0.8) so the no-config path is byte-identical to 0.15.3
-    // except for the FTS per-list weight (1.0 → 0.5) — the one deliberate
-    // nudge toward vector that the recall-sweep eval gates. The eval showed
-    // 0.7 was too timid (Q4 marine contamination persisted) and 0.5 is the
-    // bisection point where BM25F + composite-affinity finally flip the
-    // token-exact marine body match below the same-scope hardware field
-    // (Q4 ON contamination 0.20 → 0.00). 0.5 is still "conservative" — FTS
-    // contributes half its RRF share, enough that pure-keyword queries (the
-    // focused-family "login/CORS/webhook" turns) keep recall@5 = 1.0.
-    rrfK: 60,
-    rrfCompositeWeight: 0.8,
-    rrfFtsWeight: 0.5,
-    rrfVectorWeight: 1.0,
+    similarity: CALIBRATION.SCORE_SIMILARITY_WEIGHT,
+    strength: CALIBRATION.SCORE_STRENGTH_WEIGHT,
+    connections: CALIBRATION.SCORE_CONNECTIONS_WEIGHT,
+    recency: CALIBRATION.SCORE_RECENCY_WEIGHT,
+    freshnessBoostDays: CALIBRATION.FRESHNESS_BOOST_DAYS,
+    freshnessBoostWeight: CALIBRATION.FRESHNESS_BOOST_WEIGHT,
+    supersededDemotion: CALIBRATION.SUPERSEDED_DEMOTION,
+    projectAffinity: CALIBRATION.PROJECT_AFFINITY_WEIGHT,
+    domainAffinity: CALIBRATION.DOMAIN_AFFINITY_WEIGHT,
+    // #205 (calibration.ts): rrfK + rrfCompositeWeight match the pre-#205
+    // hardcoded values (60 and 0.8); the FTS per-list weight (1.0 → 0.5) is the
+    // one deliberate nudge toward vector — the bisection point where BM25F +
+    // composite-affinity flip the token-exact marine body match below the
+    // same-scope hardware field while pure-keyword queries keep recall@5 = 1.0.
+    rrfK: CALIBRATION.RRF_K,
+    rrfCompositeWeight: CALIBRATION.RRF_COMPOSITE_WEIGHT,
+    rrfFtsWeight: CALIBRATION.RRF_FTS_WEIGHT,
+    rrfVectorWeight: CALIBRATION.RRF_VECTOR_WEIGHT,
 };
 let scoringWeights = { ...SCORING_DEFAULTS };
 /**
- * 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.)
  */
-function configureScoring(config) {
-    const num = (key, dflt, min, max) => {
-        const v = Number(config?.[key]);
-        return Number.isFinite(v) && v >= min && v <= max ? v : dflt;
+function configureScoring(overrides) {
+    const num = (v, dflt, min, max) => {
+        const n = Number(v);
+        return Number.isFinite(n) && n >= min && n <= max ? n : dflt;
     };
-    // #205 BM25F weights use a [0, ∞) range (no upper bound — a field can dominate
-    // if the operator wills it; 0 drops the field entirely). Invalid ⇒ default.
-    const numW = (key, dflt) => {
-        const v = Number(config?.[key]);
-        return Number.isFinite(v) && v >= 0 ? v : dflt;
+    // #205 BM25F-style weights use a [0, ∞) range (no upper bound; 0 drops the
+    // field/list entirely). Invalid ⇒ default.
+    const numW = (v, dflt) => {
+        const n = Number(v);
+        return Number.isFinite(n) && n >= 0 ? n : dflt;
     };
     scoringWeights = {
-        similarity: num("scoreSimilarityWeight", SCORING_DEFAULTS.similarity, 0, 1),
-        strength: num("scoreStrengthWeight", SCORING_DEFAULTS.strength, 0, 1),
-        connections: num("scoreConnectionsWeight", SCORING_DEFAULTS.connections, 0, 1),
-        recency: num("scoreRecencyWeight", SCORING_DEFAULTS.recency, 0, 1),
-        freshnessBoostDays: num("freshnessBoostDays", SCORING_DEFAULTS.freshnessBoostDays, 0, 365),
-        freshnessBoostWeight: num("freshnessBoostWeight", SCORING_DEFAULTS.freshnessBoostWeight, 0, 1),
-        supersededDemotion: num("supersededDemotion", SCORING_DEFAULTS.supersededDemotion, 0, 1),
-        projectAffinity: num("projectAffinityWeight", SCORING_DEFAULTS.projectAffinity, 0, 1),
-        domainAffinity: num("domainAffinityWeight", SCORING_DEFAULTS.domainAffinity, 0, 1),
-        rrfK: numW("rrfK", SCORING_DEFAULTS.rrfK),
-        rrfCompositeWeight: num("rrfCompositeWeight", SCORING_DEFAULTS.rrfCompositeWeight, 0, 1),
-        rrfFtsWeight: numW("rrfFtsWeight", SCORING_DEFAULTS.rrfFtsWeight),
-        rrfVectorWeight: numW("rrfVectorWeight", SCORING_DEFAULTS.rrfVectorWeight),
+        similarity: num(overrides?.similarity, SCORING_DEFAULTS.similarity, 0, 1),
+        strength: num(overrides?.strength, SCORING_DEFAULTS.strength, 0, 1),
+        connections: num(overrides?.connections, SCORING_DEFAULTS.connections, 0, 1),
+        recency: num(overrides?.recency, SCORING_DEFAULTS.recency, 0, 1),
+        freshnessBoostDays: num(overrides?.freshnessBoostDays, SCORING_DEFAULTS.freshnessBoostDays, 0, 365),
+        freshnessBoostWeight: num(overrides?.freshnessBoostWeight, SCORING_DEFAULTS.freshnessBoostWeight, 0, 1),
+        supersededDemotion: num(overrides?.supersededDemotion, SCORING_DEFAULTS.supersededDemotion, 0, 1),
+        projectAffinity: num(overrides?.projectAffinity, SCORING_DEFAULTS.projectAffinity, 0, 1),
+        domainAffinity: num(overrides?.domainAffinity, SCORING_DEFAULTS.domainAffinity, 0, 1),
+        rrfK: numW(overrides?.rrfK, SCORING_DEFAULTS.rrfK),
+        rrfCompositeWeight: num(overrides?.rrfCompositeWeight, SCORING_DEFAULTS.rrfCompositeWeight, 0, 1),
+        rrfFtsWeight: numW(overrides?.rrfFtsWeight, SCORING_DEFAULTS.rrfFtsWeight),
+        rrfVectorWeight: numW(overrides?.rrfVectorWeight, SCORING_DEFAULTS.rrfVectorWeight),
     };
-    // #205: push BM25F field weights into storage so searchFts uses them. Same
-    // config object, one tuning surface; storage owns the module-level mirror
-    // next to the FTS column declaration (the positional order matters there).
-    storage.configureBm25Fts({
-        bm25WeightBody: numW("bm25WeightBody", 1.0),
-        bm25WeightProject: numW("bm25WeightProject", 2.0),
-        bm25WeightDomain: numW("bm25WeightDomain", 2.0),
-    });
     return { ...scoringWeights };
 }
 /** Current resolved weights (tests + status output). */
@@ -200,11 +190,11 @@ function getScoringWeights() {
     return { ...scoringWeights };
 }
 // ---------------------------------------------------------------------------
-// Session-intent keying (#192, 0.15.3). ONE config knob:
-//   sessionIntentWeight  0.33  blend weight of the rolling centroid in the
-//                              search vector: query = (1-w)·prompt + w·centroid.
-//                              0 = DISABLED (pure prompt, the kill-switch —
-//                              current behavior). Range [0, 1].
+// Session-intent keying (#192, 0.15.3). ONE calibration constant (#408):
+//   SESSION_INTENT_WEIGHT  0.33  blend weight of the rolling centroid in the
+//                                search vector: query = (1-w)·prompt + w·centroid.
+//                                configureSessionIntent(0) is the eval-only
+//                                kill-switch (pure prompt). Range [0, 1].
 //
 // The EMA rate α is a shipped constant (SESSION_INTENT_ALPHA, 0.4), not a
 // second knob — owner directive 0.15.3: one knob is enough to tune/disable;
@@ -218,18 +208,18 @@ function getScoringWeights() {
 // ---------------------------------------------------------------------------
 /** EMA rate for the session-intent centroid: centroid_new = (1-α)·old + α·prompt. */
 exports.SESSION_INTENT_ALPHA = 0.4;
-const SESSION_INTENT_DEFAULT_WEIGHT = 0.33;
+const SESSION_INTENT_DEFAULT_WEIGHT = CALIBRATION.SESSION_INTENT_WEIGHT;
 let sessionIntentWeight = SESSION_INTENT_DEFAULT_WEIGHT;
 /**
- * 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.
  */
-function configureSessionIntent(config) {
-    const v = Number(config?.sessionIntentWeight);
+function configureSessionIntent(weight) {
+    const v = Number(weight);
     sessionIntentWeight =
         Number.isFinite(v) && v >= 0 && v <= 1 ? v : SESSION_INTENT_DEFAULT_WEIGHT;
     return { weight: sessionIntentWeight, alpha: exports.SESSION_INTENT_ALPHA };
@@ -305,6 +295,123 @@ function findDemotedIds(db, candidateIds) {
         .all(...candidateIds, ...candidateIds);
     return new Set(rows.map((r) => r.id));
 }
+// ---------------------------------------------------------------------------
+// Belief walk (#393 increment D)
+// ---------------------------------------------------------------------------
+/**
+ * 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).
+ */
+exports.BELIEF_WALK_MAX_HOPS = 10;
+/**
+ * The one outgoing supersession edge to follow from `id` (#393 D): when a
+ * memory carries several `superseded_by` edges the NEWEST target by
+ * created_at wins (deterministic target_id tie-break), null when there is
+ * none. Indexed by idx_links_source; one row read.
+ */
+function nextSupersedingId(db, id) {
+    const row = db
+        .prepare(`SELECT ml.target_id AS target_id
+         FROM memory_links ml
+         JOIN memories m ON m.id = ml.target_id
+        WHERE ml.source_id = ? AND ml.relationship = 'superseded_by'
+        ORDER BY m.created_at DESC, ml.target_id ASC
+        LIMIT 1`)
+        .get(id);
+    return row ? row.target_id : null;
+}
+/**
+ * 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).
+ */
+function beliefWalkTerminal(db, id, maxHops = exports.BELIEF_WALK_MAX_HOPS) {
+    const visited = new Set([id]);
+    let current = id;
+    for (let hop = 0; hop < maxHops; hop++) {
+        const next = nextSupersedingId(db, current);
+        if (next === null || visited.has(next))
+            return current;
+        visited.add(next);
+        current = next;
+    }
+    return current;
+}
+/**
+ * The belief-walk splice (#393 D) — the retrieval-side half of "newest wins
+ * by construction". Applied to the FINAL top-k of retrieve()/searchRecent(),
+ * after the sort and after the cold-exposure splice: a superseded candidate
+ * is replaced IN ITS SLOT by its chain's terminal (beliefWalkTerminal), so a
+ * strong stale record can never outrank — or appear alongside — the truth
+ * that replaced it. The ancestor stays fetchable by id (evidence) but never
+ * surfaces as a competing truth in recall.
+ *
+ * Per entry of `top`, in order:
+ *   - not superseded            → kept untouched (fast path, zero queries)
+ *   - terminal === entry        → kept (no outgoing edge — the entry is its
+ *                                 own terminal; a self-loop aborts here too.
+ *                                 A hop-cap or non-self-cycle abort stops the
+ *                                 walk on a DIFFERENT node, so the entry
+ *                                 falls through to the bullets below — e.g.
+ *                                 a 2-cycle with both members in top drops
+ *                                 both, conservative but nothing stale
+ *                                 surfaces (corrupt-data corner only; edges
+ *                                 advance created_at, acyclic by
+ *                                 construction). supersededDemotion in
+ *                                 computeScore stays the safety net for rows
+ *                                 the walk does not resolve)
+ *   - terminal already surfaced → the entry is DROPPED (its truth is present)
+ *   - otherwise                 → buildReplacement(terminal); null (terminal
+ *                                 unfetchable or absorbed — absorbed rows
+ *                                 are invisible to recall by contract) keeps
+ *                                 the ancestor in-slot, fail-soft
+ *
+ * The replacement takes the ancestor's SLOT (position), not its score — no
+ * re-sort after the splice; ranking remains the sort's verdict. Idempotent
+ * by construction: walk-stable and unsuperseded entries are returned as-is.
+ */
+function applyBeliefWalk(db, top, supersededIds, buildReplacement) {
+    const present = new Set(top.map((t) => t.mem.id));
+    const out = [];
+    for (const entry of top) {
+        if (!supersededIds.has(entry.mem.id)) {
+            out.push(entry);
+            continue;
+        }
+        const terminal = beliefWalkTerminal(db, entry.mem.id);
+        if (terminal === entry.mem.id) {
+            out.push(entry);
+            continue;
+        }
+        if (present.has(terminal)) {
+            // The chain's truth is already surfaced — drop the ancestor.
+            continue;
+        }
+        const replacement = buildReplacement(terminal);
+        if (replacement === null) {
+            out.push(entry);
+            continue;
+        }
+        out.push(replacement);
+        present.add(terminal);
+    }
+    return out;
+}
 /**
  * Placeholder L2 distance for candidates that have no measured vector
  * distance (FTS-only hits and graph-discovered neighbors). Chosen so that
@@ -332,6 +439,28 @@ const DEFAULT_RRF_K = 60;
 function l2ToCosine(distance) {
     return 1 - (distance * distance) / 2;
 }
+/**
+ * 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).
+ */
+function cosineBetweenVectors(a, b) {
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    if (na === 0 || nb === 0)
+        return 0;
+    return dot / Math.sqrt(na * nb);
+}
 // ---------------------------------------------------------------------------
 // Timestamp parsing
 // ---------------------------------------------------------------------------
@@ -715,6 +844,38 @@ async function retrieve(db, embedFn, query, options) {
             }
         }
     }
+    // 6b. Belief walk (#393 D) — a superseded top-k member is replaced in-slot
+    // by its chain's terminal. A terminal already in `scored` reuses its honest
+    // entry (similarity/RRF/score); one outside the candidate set is computed
+    // fresh with source "graph" and RRF share 0 (it entered by LINK, not by any
+    // retrieval channel — finalScore = composite × rrfCompositeWeight only).
+    // The strengthen() below then fires on the SURFACED set: the terminal
+    // accrues the use signal, the dropped ancestor does not. supersededDemotion
+    // in computeScore stays as the safety net for rows the walk does not reach.
+    const scoredById = new Map(scored.map((s) => [s.mem.id, s]));
+    top = applyBeliefWalk(db, top, supersededIds, (terminalId) => {
+        const existing = scoredById.get(terminalId);
+        if (existing)
+            return existing;
+        const mem = storage.getMemory(db, terminalId);
+        if (!mem || mem.status === "absorbed")
+            return null; // fail-soft
+        // Hard-filter invariant (#393 D): sourceAgent is the one hard filter left
+        // in retrieve(), and the walk must not bypass it — a terminal authored by
+        // a different agent never slips into recall through its link entry
+        // (mirrors the graph pull-in guard above; fail-soft: the ancestor keeps
+        // its slot, demoted).
+        if (sourceAgent && mem.source_agent !== sourceAgent)
+            return null;
+        const connCount = storage.getLinks(db, terminalId, "both").length;
+        const composite = computeScore(mem, DEFAULT_GRAPH_DISTANCE, connCount, maxConnections, now, { superseded: supersededIds.has(terminalId) });
+        const finalScore = composite * scoringWeights.rrfCompositeWeight;
+        const effStr = effectiveStrength(mem.base_strength ?? 0.5, mem.last_accessed, now, {
+            accessCount: mem.access_count ?? 0,
+            linkCount: connCount,
+        });
+        return { mem, finalScore, effStr, connCount, similarity: null, source: "graph" };
+    });
     const results = top.map((t) => formatResult(t.mem, t.finalScore, t.effStr, t.connCount, {
         similarity: t.similarity,
         source: t.source,
@@ -765,7 +926,34 @@ function searchRecent(db, options) {
         scored.push({ mem, score, effStr, connCount });
     }
     scored.sort((a, b) => b.score - a.score);
-    const top = scored.slice(0, limit);
+    let top = scored.slice(0, limit);
+    // Belief walk (#393 D) — same contract as retrieve(): a superseded recent
+    // memory is replaced in-slot by its chain terminal (this path has no
+    // similarity/RRF channels, so a fresh replacement carries the composite
+    // score only). The trailing strengthen() runs over the WALKED list — the
+    // terminal accrues the use signal, the dropped ancestor does not.
+    // supersededDemotion in computeScore stays as the safety net for rows the
+    // walk does not reach (no edge, absorbed terminal, cycles/caps).
+    top = applyBeliefWalk(db, top, supersededRecent, (terminalId) => {
+        const mem = storage.getMemory(db, terminalId);
+        if (!mem || mem.status === "absorbed")
+            return null; // fail-soft
+        // Hard-filter invariant (#393 D, review fix): project is the one hard
+        // filter in searchRecent(), and the walk must not bypass it — supersession
+        // edges are discovered corpus-wide (no project predicate), so a terminal
+        // in a different project never slips into project-scoped recall through
+        // its link entry (mirrors retrieve()'s sourceAgent guard; fail-soft: the
+        // ancestor keeps its slot, demoted).
+        if (project && mem.project !== project)
+            return null;
+        const connCount = storage.getLinks(db, terminalId, "both").length;
+        const score = computeScore(mem, DEFAULT_GRAPH_DISTANCE, connCount, maxConnections, now, { superseded: supersededRecent.has(terminalId) });
+        const effStr = effectiveStrength(mem.base_strength ?? 0.5, mem.last_accessed, now, {
+            accessCount: mem.access_count ?? 0,
+            linkCount: connCount,
+        });
+        return { mem, score, effStr, connCount };
+    });
     const results = top.map((t) => formatResult(t.mem, t.score, t.effStr, t.connCount));
     strengthen(db, top.map((t) => t.mem), now);
     return results;

package/dist/run-deadline.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The ONE cooperative wall-clock deadline for a nightly run (#405).
+ *
+ * Generalizes the #401/#402/#404 reconsolidation pattern (a deadline checked
+ * at safe boundaries + resumable cursors) from one stage to the whole
+ * pipeline: capture segments, every consolidation stage boundary, the
+ * item loops, and the deterministic merge zone all check the SAME deadline,
+ * created once at nightly start. On expiry each check site stops cleanly at
+ * its last safe boundary — cursors (capture per-session, supersession,
+ * reconsolidation) hold below unconfirmed work, so the next run resumes
+ * without redoing confirmed work or losing deferred work.
+ *
+ * Deferral is a REPORTED outcome, not an error: a run whose deadline fired
+ * reports consolidation status "deferred" and does NOT advance
+ * `lastConsolidated` (the same gate as endpoint_down — otherwise the
+ * pending-set queries would silently lose the deferred work).
+ *
+ * One structured log line per deferred stage (`event=deadline_deferred`,
+ * the same key=value style as `event=budget_exhausted` /
+ * `event=circuit_open`) so `grep event=deadline_deferred` is one of the two
+ * nightly health greps.
+ */
+/** Default wall-clock budget for a full nightly run, in minutes (#405).
+ *  240 sits between the old stage-local reconsolidation clock (120) and the
+ *  old systemd backstop (360) — the deadline is now the operating bound and
+ *  the unit backstop (budget + 60 min slack) only catches a true hang. */
+export declare const DEFAULT_NIGHTLY_TIME_BUDGET_MINUTES = 240;
+/**
+ * Cooperative deadline handle. Injectable clock (`now`) so tests can pin or
+ * advance time deterministically (the reconsolidation.test.ts 0.000001-minute
+ * pattern). All methods are safe to call after expiry — they keep answering.
+ */
+export interface RunDeadline {
+    /** Absolute epoch-ms timestamp the run must finish by. */
+    readonly deadlineAt: number;
+    /** Milliseconds left until the deadline (never negative). */
+    remainingMs(): number;
+    /** True once the clock has passed the deadline. */
+    expired(): boolean;
+    /**
+     * Check + record in one call: returns true when the deadline has fired,
+     * logging `event=deadline_deferred stage=<name>` ONCE per stage name (a
+     * boundary check and in-loop checks for the same stage log once). Use the
+     * same stage name at a stage's boundary and inside its loops.
+     */
+    hit(stage: string): boolean;
+    /** Stage names that deferred so far this run (insertion order). */
+    deferredStages(): readonly string[];
+}
+/**
+ * Create a run deadline of `minutes` (already-resolved value; see
+ * resolveNightlyTimeBudgetMinutes for the config boundary).
+ */
+export declare function createRunDeadline(minutes: number, now?: () => number): RunDeadline;
+/**
+ * Resolve `nightlyTimeBudgetMinutes` from the saved config (#405): positive
+ * finite number wins; absent/0/invalid → the 240 default. Unlike the old
+ * `reconsolidationMaxMinutes`, 0 does NOT disable — there is ALWAYS a
+ * deadline (readPositiveConfig rejects 0 with a warn, which is the loud
+ * migration signal for an operator who used 0 as "off").
+ */
+export declare function resolveNightlyTimeBudgetMinutes(config: Record<string, unknown> | null | undefined): number;

package/dist/run-deadline.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * The ONE cooperative wall-clock deadline for a nightly run (#405).
+ *
+ * Generalizes the #401/#402/#404 reconsolidation pattern (a deadline checked
+ * at safe boundaries + resumable cursors) from one stage to the whole
+ * pipeline: capture segments, every consolidation stage boundary, the
+ * item loops, and the deterministic merge zone all check the SAME deadline,
+ * created once at nightly start. On expiry each check site stops cleanly at
+ * its last safe boundary — cursors (capture per-session, supersession,
+ * reconsolidation) hold below unconfirmed work, so the next run resumes
+ * without redoing confirmed work or losing deferred work.
+ *
+ * Deferral is a REPORTED outcome, not an error: a run whose deadline fired
+ * reports consolidation status "deferred" and does NOT advance
+ * `lastConsolidated` (the same gate as endpoint_down — otherwise the
+ * pending-set queries would silently lose the deferred work).
+ *
+ * One structured log line per deferred stage (`event=deadline_deferred`,
+ * the same key=value style as `event=budget_exhausted` /
+ * `event=circuit_open`) so `grep event=deadline_deferred` is one of the two
+ * nightly health greps.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_NIGHTLY_TIME_BUDGET_MINUTES = void 0;
+exports.createRunDeadline = createRunDeadline;
+exports.resolveNightlyTimeBudgetMinutes = resolveNightlyTimeBudgetMinutes;
+const config_read_js_1 = require("./config-read.js");
+/** Default wall-clock budget for a full nightly run, in minutes (#405).
+ *  240 sits between the old stage-local reconsolidation clock (120) and the
+ *  old systemd backstop (360) — the deadline is now the operating bound and
+ *  the unit backstop (budget + 60 min slack) only catches a true hang. */
+exports.DEFAULT_NIGHTLY_TIME_BUDGET_MINUTES = 240;
+/**
+ * Create a run deadline of `minutes` (already-resolved value; see
+ * resolveNightlyTimeBudgetMinutes for the config boundary).
+ */
+function createRunDeadline(minutes, now = Date.now) {
+    const start = now();
+    const deadlineAt = start + Math.max(0, Math.round(minutes * 60_000));
+    const logged = new Set();
+    const deferred = [];
+    return {
+        deadlineAt,
+        remainingMs: () => Math.max(0, deadlineAt - now()),
+        expired: () => now() >= deadlineAt,
+        hit(stage) {
+            if (now() < deadlineAt)
+                return false;
+            if (!logged.has(stage)) {
+                logged.add(stage);
+                deferred.push(stage);
+                // Structured (grep-able) + human-readable — same contract as
+                // event=budget_exhausted (consolidate.ts) and event=circuit_open
+                // (llm.ts). remaining_ms=0 states the reason plainly.
+                console.warn(`[hicortex] event=deadline_deferred stage=${stage} ` +
+                    `deadline_minutes=${(deadlineAt - start) / 60_000} remaining_ms=0`);
+            }
+            return true;
+        },
+        deferredStages: () => deferred,
+    };
+}
+/**
+ * Resolve `nightlyTimeBudgetMinutes` from the saved config (#405): positive
+ * finite number wins; absent/0/invalid → the 240 default. Unlike the old
+ * `reconsolidationMaxMinutes`, 0 does NOT disable — there is ALWAYS a
+ * deadline (readPositiveConfig rejects 0 with a warn, which is the loud
+ * migration signal for an operator who used 0 as "off").
+ */
+function resolveNightlyTimeBudgetMinutes(config) {
+    return (0, config_read_js_1.readPositiveConfig)(config ?? {}, "nightlyTimeBudgetMinutes", exports.DEFAULT_NIGHTLY_TIME_BUDGET_MINUTES);
+}