@gamaze/hicortex 0.20.7 → 0.20.10

package/dist/consolidate.js

@@ -38,10 +38,14 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_MEMORY_SOFT_CAP = exports.DEFAULT_SUPERSESSION_MAX_CALLS = exports.DEFAULT_SUPERSESSION_MIN_SIMILARITY = exports.BudgetTracker = exports.REFLECTION_CONTRADICTION_MIN_COSINE = exports.l2ToCosine = exports.CROSS_PROJECT_LINK_THRESHOLD = exports.CONSOLIDATE_LINK_TOP_K = exports.CONSOLIDATE_LINK_THRESHOLD = exports.CONSOLIDATE_MAX_LLM_CALLS = void 0;
+exports.DEFAULT_MEMORY_SOFT_CAP = exports.DEFAULT_SUPERSESSION_MIN_SIMILARITY = exports.BudgetTracker = exports.REFLECTION_CONTRADICTION_MIN_COSINE = exports.l2ToCosine = exports.CROSS_PROJECT_LINK_THRESHOLD = exports.CONSOLIDATE_LINK_TOP_K = exports.CONSOLIDATE_LINK_THRESHOLD = exports.DEFAULT_NIGHTLY_LLM_CALL_BUDGET = void 0;
+exports.resolveNightlyLlmCallBudget = resolveNightlyLlmCallBudget;
 exports.isContradictionCandidate = isContradictionCandidate;
+exports.warnUnmeteredTokensRun = warnUnmeteredTokensRun;
+exports.isStaleTokenPeriod = isStaleTokenPeriod;
 exports.shouldThrottleTokens = shouldThrottleTokens;
 exports.parseJsonLenient = parseJsonLenient;
+exports.scoreMemoriesImportance = scoreMemoriesImportance;
 exports.rebuildContentModuleIndex = rebuildContentModuleIndex;
 exports.discoverLinkCandidates = discoverLinkCandidates;
 exports.classifyLinkCandidates = classifyLinkCandidates;
@@ -53,8 +57,6 @@ exports.stageDecayPrune = stageDecayPrune;
 exports.resolveMemorySoftCap = resolveMemorySoftCap;
 exports.stageMemoryCapEviction = stageMemoryCapEviction;
 exports.runConsolidation = runConsolidation;
-exports.msUntilHour = msUntilHour;
-exports.scheduleConsolidation = scheduleConsolidation;
 const retrieval_js_1 = require("./retrieval.js");
 const storage = __importStar(require("./storage.js"));
 const config_read_js_1 = require("./config-read.js");
@@ -68,19 +70,41 @@ const schema_prototypes_js_1 = require("./schema-prototypes.js");
 const nofit_js_1 = require("./nofit.js");
 const reconsolidation_js_1 = require("./reconsolidation.js");
 const dedup_js_1 = require("./dedup.js");
+const CALIBRATION = __importStar(require("./calibration.js"));
 // Default config constants (matching Python config.py)
 /**
- * Default ceiling on total LLM calls across all classify-tier consolidation
- * stages (content-domain, link discovery, supersession) per run. This is a
- * runaway BACKSTOP, not a throughput throttle — on a free local model there is
- * no per-call cost to defend against; the binding constraint is the nightly
- * unit's wall-clock timeout (TimeoutStartSec), not call count. 5000 clears a
- * one-time classification backlog (a ~2000-memory batch drains in ~1-2 runs
- * instead of ~11 nights at the old 200) with margin for link/supersession, and
- * ~5000 calls x ~1-3s/call ≈ 1.4-4.2h fits the 6h consolidation backstop.
- * Config-overridable as `consolidateMaxLlmCalls` (#241).
+ * Default ceiling on LLM calls across the WHOLE nightly pipeline (#405; the
+ * #241 consolidateMaxLlmCalls mechanism, renamed and widened). A runaway
+ * BACKSTOP that bounds money/load INDEPENDENT OF LATENCY — a fast metered or
+ * capacity-limited endpoint permits thousands of calls inside the wall-clock
+ * budget, so time alone cannot protect it (owner ruling 2026-09-12). Consumed
+ * in run order: a stage that exhausts it defers its remainder via its cursor.
+ * 5000 clears a one-time classification backlog (a ~2000-memory batch drains
+ * in ~1-2 runs) with margin. Config: `nightlyLlmCallBudget` (#405); the old
+ * `consolidateMaxLlmCalls` key is a deprecated alias honored one release.
  */
-exports.CONSOLIDATE_MAX_LLM_CALLS = 5000;
+exports.DEFAULT_NIGHTLY_LLM_CALL_BUDGET = 5000;
+/**
+ * Resolve the per-run LLM call budget from config (#405):
+ *  - `nightlyLlmCallBudget` present (positive finite) → it wins;
+ *  - else `consolidateMaxLlmCalls` present → used as a DEPRECATED ALIAS with
+ *    a warn naming the replacement (honored one release);
+ *  - absent/invalid → the 5000 default.
+ */
+function resolveNightlyLlmCallBudget(config) {
+    const c = config ?? {};
+    if (c.nightlyLlmCallBudget !== undefined) {
+        return (0, config_read_js_1.readPositiveConfig)(c, "nightlyLlmCallBudget", exports.DEFAULT_NIGHTLY_LLM_CALL_BUDGET);
+    }
+    if (c.consolidateMaxLlmCalls !== undefined) {
+        const legacy = (0, config_read_js_1.readPositiveConfig)(c, "consolidateMaxLlmCalls", exports.DEFAULT_NIGHTLY_LLM_CALL_BUDGET);
+        console.warn(`[hicortex] config key "consolidateMaxLlmCalls" is deprecated — renamed ` +
+            `"nightlyLlmCallBudget" (same meaning, now the ONE per-run LLM call ceiling). ` +
+            `The old key is honored for one release; rename it to clear this warning.`);
+        return legacy;
+    }
+    return exports.DEFAULT_NIGHTLY_LLM_CALL_BUDGET;
+}
 const CONSOLIDATE_PRUNE_MIN_AGE_DAYS = 90;
 /**
  * Minimum COSINE similarity for a link candidate.
@@ -133,14 +157,12 @@ class BudgetTracker {
     callsByStage = {};
     /**
      * Per-stage count of LLM-call REQUESTS refused because the budget was
-     * exhausted (#255). Keys are the same stage labels passed to `use()`. The
-     * value is the SUM of the `count` args passed to each refused `use()` call
-     * in that stage (in production every `use()` call passes count=1, so each
-     * refused call adds 1 — but the API accepts a batch count, so a single
-     * refused batch request accrues its full count). Stages break on the first
-     * refusal, so a stage's value is the count of the one request that crossed
-     * the boundary. For item-level skip counts (how many memories or pairs were
-     * left unprocessed), see the per-stage reports — e.g.
+     * exhausted (#255). Keys are the same stage labels passed to `use()`; each
+     * refused call adds 1 (the dead batch `count` param is gone — #405 —
+     * production always passed 1 anyway). Stages break on the first refusal,
+     * so a stage's value is the count of requests that crossed the boundary.
+     * For item-level skip counts (how many memories or pairs were left
+     * unprocessed), see the per-stage reports — e.g.
      * `stages.importance.skipped_budget` — which count MEMORIES, not call
      * requests. Surfaced in summary() and ConsolidationReport as
      * `deferred_by_stage`.
@@ -168,21 +190,21 @@ class BudgetTracker {
     get remaining() {
         return Math.max(0, this.maxCalls - this.callsUsed);
     }
-    use(stage, count = 1) {
-        if (this.callsUsed + count > this.maxCalls) {
+    use(stage) {
+        if (this.callsUsed >= this.maxCalls) {
             // #255: emit as a STRUCTURED event (not a bare prose warn) so a monitor
             // can grep/parse `event=budget_exhausted` from journald. The line stays
             // human-readable (key=value tokens after the [hicortex] prefix). Deferred
             // counts are accrued BEFORE the log so the line reflects the up-to-date
             // per-stage toll — the refused count is added to this stage's slot.
-            this.deferredByStage[stage] = (this.deferredByStage[stage] ?? 0) + count;
+            this.deferredByStage[stage] = (this.deferredByStage[stage] ?? 0) + 1;
             console.warn(`[hicortex] event=budget_exhausted stage=${stage} ` +
                 `calls_used=${this.callsUsed} max_calls=${this.maxCalls} ` +
                 `deferred_by_stage=${JSON.stringify(this.deferredByStage)}`);
             return false;
         }
-        this.callsUsed += count;
-        this.callsByStage[stage] = (this.callsByStage[stage] ?? 0) + count;
+        this.callsUsed += 1;
+        this.callsByStage[stage] = (this.callsByStage[stage] ?? 0) + 1;
         return true;
     }
     /**
@@ -220,9 +242,44 @@ class BudgetTracker {
     }
 }
 exports.BudgetTracker = BudgetTracker;
+/**
+ * #427 observability: warn when a consolidation run made LLM CALLS but
+ * metered ZERO tokens — the endpoint returned no usage objects on its
+ * completions (recordUsage skips undefined by design, never fabricates a
+ * zero). Such a run still spends budget calls but its snapshot carries token
+ * nulls, which read as a mystery on the dashboard. The warn is a structured
+ * event in the same journald-greppable style as `event=budget_exhausted`
+ * (grep `event=tokens_unmetered`), so the blind spot is visible instead of
+ * silent. Returns true when it warned (for tests); no fabrication either
+ * way — the numbers stay exactly what the endpoint reported.
+ */
+function warnUnmeteredTokensRun(budget) {
+    const calls = budget.calls_used ?? 0;
+    const tokens = budget.tokens_total?.total ?? 0;
+    if (calls <= 0 || tokens > 0)
+        return false;
+    console.warn(`[hicortex] event=tokens_unmetered calls_used=${calls} — the LLM endpoint ` +
+        `returned no usage objects on its completions; this run's snapshot carries ` +
+        `no token metering (budget calls were still counted).`);
+    return true;
+}
 // ---------------------------------------------------------------------------
 // Token fair-use throttle decision (#246)
 // ---------------------------------------------------------------------------
+/**
+ * True when a token-period start stamp is ABSENT or sits in a previous UTC
+ * calendar month than `now` — the monthly-reset staleness check. #405: ONE
+ * shared helper — the check was triplicated (the nightly's throttle branch,
+ * the nightly's accrual write, token-budget.ts recordDistillUsage) and each
+ * copy re-derived the year+month comparison by hand.
+ */
+function isStaleTokenPeriod(periodStart, now = new Date()) {
+    if (!periodStart)
+        return true;
+    const start = new Date(periodStart);
+    return start.getUTCFullYear() !== now.getUTCFullYear() ||
+        start.getUTCMonth() !== now.getUTCMonth();
+}
 /**
  * Decide whether consolidation should be throttled this run based on the
  * `llmTokensPerMonth` fair-use cap. Pure (no I/O) so it can be unit-tested
@@ -235,22 +292,14 @@ exports.BudgetTracker = BudgetTracker;
  *
  * `cap = 0` (the self-hosted default) → never throttle (unlimited).
  * `periodStart` in a previous calendar month → period resets to 0 first
- * (mirrors the reset logic in nightly.ts; both sides agree because both read
- * the same state + clock).
+ * (isStaleTokenPeriod — the same helper every monthly-reset site uses, so
+ * the sides agree because they read the same state + clock).
  */
 function shouldThrottleTokens(cap, period, lastRunTokens, now = new Date()) {
     if (cap <= 0)
         return { throttle: false };
-    let periodTotal = period?.total ?? 0;
-    const periodStart = period?.periodStart;
-    if (periodStart) {
-        const start = new Date(periodStart);
-        if (start.getUTCFullYear() !== now.getUTCFullYear() ||
-            start.getUTCMonth() !== now.getUTCMonth()) {
-            // Stale period → reset accrual to 0 before the check.
-            periodTotal = 0;
-        }
-    }
+    // Stale period → reset accrual to 0 before the check.
+    const periodTotal = isStaleTokenPeriod(period?.periodStart, now) ? 0 : (period?.total ?? 0);
     if (periodTotal + lastRunTokens > cap) {
         return { throttle: true, used: periodTotal, cap };
     }
@@ -325,29 +374,50 @@ function stagePrecheck(db, stateDir) {
 // ---------------------------------------------------------------------------
 // Stage 2: Importance Scoring
 // ---------------------------------------------------------------------------
-async function stageImportance(db, memories, llm, budget, dryRun) {
+/**
+ * The shared importance-scoring loop (#425 extraction): one LLM call per
+ * 10-memory batch through the production `importanceScoring` prompt, each
+ * written score clamped at IMPORTANCE_CEILING and stamped with the
+ * importance_scored_at watermark. Used by the nightly's stageImportance AND
+ * `hicortex rescore-importance` — there is exactly one scoring code path
+ * (no forked backfill logic; cap + watermark write identically everywhere).
+ *
+ * Failure semantics: a batch whose LLM call THROWS writes nothing (counted
+ * in `failed` — retried naturally later); a batch whose reply parses to a
+ * non-array falls back to 0.5 per memory (written + watermarked — the
+ * endpoint answered, the answer was unusable).
+ */
+async function scoreMemoriesImportance(db, memories, llm, opts = {}) {
     const batchSize = 10;
+    const budget = opts.budget;
+    const deadline = opts.deadline;
+    const dryRun = opts.dryRun ?? false;
     let scored = 0;
     let failed = 0;
     let skippedBudget = 0;
     for (let i = 0; i < memories.length; i += batchSize) {
-        if (budget.exhausted) {
+        if (budget?.exhausted) {
             skippedBudget += memories.length - i;
             break;
         }
+        // #405: the run deadline bounds the batch loop too — a large unscored
+        // backlog must not blow the whole run's wall-clock inside one stage.
+        // Same stage label as the boundary check, so the defer log fires once.
+        if (deadline?.hit("importance"))
+            break;
         const batch = memories.slice(i, i + batchSize);
         const lines = batch.map((mem, idx) => `[${idx}] ${mem.content.slice(0, 500)}`);
         const memoriesBlock = lines.join("\n\n");
         const prompt = (0, prompts_js_1.importanceScoring)(memoriesBlock);
         if (dryRun)
             continue;
-        if (!budget.use("importance")) {
+        if (budget && !budget.use("importance")) {
             skippedBudget += memories.length - i;
             break;
         }
         try {
-            const r = await llm.completeFast(prompt, 256);
-            budget.recordUsage("importance", r.usage);
+            const r = await llm.complete(prompt);
+            budget?.recordUsage("importance", r.usage);
             let scores = parseJsonLenient(r.text, null);
             if (!Array.isArray(scores)) {
                 scores = new Array(batch.length).fill(0.5);
@@ -355,6 +425,8 @@ async function stageImportance(db, memories, llm, budget, dryRun) {
             while (scores.length < batch.length)
                 scores.push(0.5);
             scores = scores.slice(0, batch.length);
+            let batchWritten = 0;
+            let batchFailed = 0;
             for (let j = 0; j < batch.length; j++) {
                 let scoreVal = 0.5;
                 try {
@@ -365,21 +437,37 @@ async function stageImportance(db, memories, llm, budget, dryRun) {
                 catch {
                     scoreVal = 0.5;
                 }
+                // #425: the write cap — importance exactly 1.0 has decay rate exactly
+                // 1.0 and never decays, so no row is ever born immortal. The scored-at
+                // watermark lands in the SAME update, taking the row out of the
+                // nightly's unscored pool however it scored (the pre-#425 0.5-sentinel
+                // re-rolled genuinely-0.5 rows every night).
+                scoreVal = Math.min(scoreVal, CALIBRATION.IMPORTANCE_CEILING);
                 try {
-                    storage.updateMemory(db, batch[j].id, { base_strength: scoreVal });
+                    storage.updateMemory(db, batch[j].id, {
+                        base_strength: scoreVal,
+                        importance_scored_at: new Date().toISOString(),
+                    });
                     scored++;
+                    batchWritten++;
                 }
                 catch {
                     failed++;
+                    batchFailed++;
                 }
             }
+            opts.onBatch?.(batchWritten, batchFailed);
         }
         catch {
             failed += batch.length;
+            opts.onBatch?.(0, batch.length);
         }
     }
     return { scored, failed, skipped_budget: skippedBudget };
 }
+async function stageImportance(db, memories, llm, budget, dryRun, deadline) {
+    return scoreMemoriesImportance(db, memories, llm, { budget, deadline, dryRun });
+}
 // ---------------------------------------------------------------------------
 // Stage 2.5: Reflection
 // ---------------------------------------------------------------------------
@@ -408,7 +496,7 @@ async function stageReflection(db, memories, llm, budget, embedFn, dryRun) {
         return { lessons_generated: 0, skipped: true, reason: "budget_exhausted" };
     }
     try {
-        const r = await llm.completeReflect(prompt, 2048);
+        const r = await llm.complete(prompt);
         budget.recordUsage("reflection", r.usage);
         const lessons = parseJsonLenient(r.text, []);
         if (!Array.isArray(lessons)) {
@@ -458,9 +546,9 @@ async function stageReflection(db, memories, llm, budget, embedFn, dryRun) {
                     const existingText = similarLessons[0].content.slice(0, 300);
                     const newText = content.slice(0, 300);
                     try {
-                        const verdictR = await llm.completeFast(`Two lessons from an AI memory system. Do they CONTRADICT each other (opposite advice on the same topic)?\n\n` +
+                        const verdictR = await llm.complete(`Two lessons from an AI memory system. Do they CONTRADICT each other (opposite advice on the same topic)?\n\n` +
                             `EXISTING: ${existingText}\n\nNEW: ${newText}\n\n` +
-                            `Answer ONLY "yes" or "no". If the new lesson updates/refines the existing one (not contradicts), answer "no".`, 16);
+                            `Answer ONLY "yes" or "no". If the new lesson updates/refines the existing one (not contradicts), answer "no".`);
                         // Stage label "contradiction_check" matches the budget.use() call
                         // above (separate counter from the reflection call proper). Token
                         // accounting follows the same stage partition as the call counter.
@@ -543,7 +631,7 @@ function rebuildContentModuleIndex(db, domains, stateDir) {
     (0, state_js_1.updateState)((s) => { s.moduleIndex = moduleIndex; }, stateDir);
     return { domains: moduleDomains.length };
 }
-async function stageContentDomains(db, domains, llm, budget, embedFn, dryRun, stateDir, weakPrimaryFloor = nofit_js_1.DEFAULT_WEAK_PRIMARY_FLOOR) {
+async function stageContentDomains(db, domains, llm, budget, embedFn, dryRun, stateDir, weakPrimaryFloor = nofit_js_1.DEFAULT_WEAK_PRIMARY_FLOOR, deadline) {
     // Rows needing (re)classification:
     //   - domain IS NULL (never classified), OR
     //   - domain NOT IN the current vocabulary (a rename/removal re-files), OR
@@ -569,6 +657,11 @@ async function stageContentDomains(db, domains, llm, budget, embedFn, dryRun, st
         // refreshes everything from the updated tag sets anyway).
         const { prototypes: startPrototypes } = await (0, schema_prototypes_js_1.computeDomainPrototypes)(db, domains, getEmbedFn);
         for (const row of rows) {
+            // #405: the run deadline bounds the classification row loop (a large
+            // backlog must defer, not blow the wall-clock). Same stage label as the
+            // boundary check, so the defer log fires once.
+            if (deadline?.hit("domain_curation"))
+                break;
             if (budget.exhausted || !budget.use("content_domain")) {
                 console.warn(`[hicortex] content-domain: budget exhausted after ${classified} classified`);
                 break;
@@ -716,7 +809,7 @@ async function stageDomainCuration(db, llm, budget, dryRun, stateDir) {
             .map((r) => `${r.project}: ${r.cnt} / ${lessonsByProject.get(r.project) ?? 0}`)
             .join("\n");
         try {
-            const r = await llm.completeFast((0, prompts_js_1.domainCuration)(projectLines), 1024);
+            const r = await llm.complete((0, prompts_js_1.domainCuration)(projectLines));
             budget.recordUsage("domain_curation", r.usage);
             const parsed = parseJsonLenient(r.text, []);
             if (!Array.isArray(parsed) || parsed.length === 0) {
@@ -847,19 +940,16 @@ function discoverLinkCandidates(db, mem, embedding) {
  * 672-link audit (see the Stage 3 header) found the LLM-classified UPPERCASE
  * types near-useless (CONTRADICTS 4% acceptable). Every candidate now takes its
  * pre-computed `heuristicType` (only `extends` or `relates_to` — see
- * classifyRelationship). No LLM call is made.
- *
- * Signature stability: `llm` and `budget` are RETAINED but intentionally
- * ignored so the callers (nightly `stageLinks`, `hicortex relink`) and the
- * tests that import this need no change to their call sites. The return shape
- * is unchanged; `llmClassified` is always 0 now and `heuristicFallback` counts
- * every candidate. Do NOT re-add an LLM path here without a classifier that
- * passes the audit harness at >= 70% acceptable.
+ * classifyRelationship). No LLM call is made. #405: the ignored `llm`/`budget`
+ * params are deleted — the signature now tells the truth.
+ * The return shape is unchanged; `llmClassified` is always 0 and
+ * `heuristicFallback` counts every candidate. Do NOT re-add an LLM path here
+ * without a classifier that passes the audit harness at >= 70% acceptable.
  *
  * Shared between the nightly `stageLinks` and `hicortex relink`.
  * Returns one relationship type per candidate (same order as input).
  */
-async function classifyLinkCandidates(candidates, _llm, _budget) {
+async function classifyLinkCandidates(candidates) {
     const types = candidates.map((c) => c.heuristicType);
     return { types, llmClassified: 0, heuristicFallback: candidates.length };
 }
@@ -880,8 +970,9 @@ async function stageLinks(db, memories, embedFn, dryRun, llm, budget) {
     if (candidates.length === 0) {
         return { auto_linked: 0, llm_classified: 0, heuristic_fallback: 0, failed };
     }
-    // Phase B: LLM batch classification (heuristic fallback inside)
-    const { types: classifiedTypes, llmClassified, heuristicFallback } = await classifyLinkCandidates(candidates, llm, budget);
+    // Phase B: heuristic-only classification (LLM retired; #405 dropped the
+    // dead llm/budget params)
+    const { types: classifiedTypes, llmClassified, heuristicFallback } = await classifyLinkCandidates(candidates);
     // Phase C: Store all classified links
     for (let i = 0; i < candidates.length; i++) {
         const c = candidates[i];
@@ -930,7 +1021,9 @@ function classifyRelationship(source, target, similarity) {
 // Stage 3.5: Hub Detection & Strength Boost
 // ---------------------------------------------------------------------------
 const HUB_BOOST = 0.1;
-const HUB_STRENGTH_CAP = 1.0;
+// #425: the release-managed importance ceiling (calibration.ts) — hub boosts
+// can no longer push a row to base 1.0 (decay rate exactly 1.0 = immortal).
+const HUB_STRENGTH_CAP = CALIBRATION.IMPORTANCE_CEILING;
 function stageHubBoost(db, dryRun) {
     const hubs = (0, graph_js_1.detectHubs)(db);
     if (hubs.length === 0)
@@ -968,26 +1061,17 @@ function stageHubBoost(db, dryRun) {
 // this is a judgment call about content, not a duplicate).
 //
 // Scope: memories with `rowid > supersessionCursor` (state.json; starts 0 —
-// the corpus is back-processed gradually, config `supersessionMaxCalls` LLM
-// calls per night) whose shape suggests a decision/correction. For each,
-// KNN top-5 OLDER same-shape neighbors at/above `supersessionMinSimilarity`;
-// one constrained classify-tier LLM call per pair decides `superseded: true|
-// false`. A parse/infra error skips just that PAIR (retried naturally next
-// night since the cursor still advances past the memory — see the cursor
-// note below); it never mis-links.
-/** Default minimum COSINE similarity for a supersession candidate pair. */
-exports.DEFAULT_SUPERSESSION_MIN_SIMILARITY = 0.8;
-/**
- * Default max classify-tier LLM calls (pairs evaluated) spent per nightly run.
- * 0 = no separate cap — supersession shares the consolidation budget
- * (CONSOLIDATE_MAX_LLM_CALLS, default 5000) like every other stage. The old
- * default of 30 was set when the corpus had 14 decisions; with the distiller
- * now classifying types correctly (#216), decisions are common and the cap
- * was throttling supersession to a crawl. On a local free model there is no
- * per-call cost to defend against — the binding constraint is the wall-clock
- * timeout (TimeoutStartSec), not call count.
- */
-exports.DEFAULT_SUPERSESSION_MAX_CALLS = 0;
+// the corpus is back-processed gradually) whose shape suggests a
+// decision/correction. For each, KNN top-5 OLDER same-shape neighbors
+// at/above the release-managed similarity floor (calibration.ts); one constrained classify-tier LLM
+// call per pair decides `superseded: true| false`. A parse/infra error skips
+// just that PAIR (retried naturally next night since the cursor still
+// advances past the memory — see the cursor note below); it never mis-links.
+// #405: no per-stage call cap — the ONE run budget (nightlyLlmCallBudget)
+// and the run deadline are the only bounds, like every other stage.
+/** Default minimum COSINE similarity for a supersession candidate pair —
+ *  RELEASE-MANAGED since #408 (calibration.ts SUPERSESSION_MIN_SIMILARITY). */
+exports.DEFAULT_SUPERSESSION_MIN_SIMILARITY = CALIBRATION.SUPERSESSION_MIN_SIMILARITY;
 /** Default multiplier applied to a superseded memory's base_strength. */
 /** Floor under which a superseded memory's base_strength never drops. */
 /** Neighbor pool size before shape/older/similarity filtering narrows to top 5. */
@@ -1067,7 +1151,7 @@ function parseSupersessionReply(reply) {
  */
 async function classifySupersession(llm, oldContent, newContent) {
     try {
-        const r = await llm.completeClassify(buildSupersessionPrompt(oldContent, newContent));
+        const r = await llm.complete(buildSupersessionPrompt(oldContent, newContent));
         return { verdict: parseSupersessionReply(r.text), usage: r.usage };
     }
     catch {
@@ -1107,6 +1191,13 @@ async function findOlderNeighbors(db, candidate, embedFn, minSimilarity) {
  * candidacy. It only stops SHORT of a candidate when the budget is already
  * exhausted before that candidate starts, so the cursor never skips a
  * candidate that was never looked at.
+ *
+ * #405: the cursor persists after EVERY fully-considered candidate (the
+ * post-#404 reconsolidation pattern), not at stage end — a run killed or
+ * deadline-deferred mid-stage loses at most the candidate in flight. No
+ * orphan clamp is needed (unlike reconsolidation): supersession applies each
+ * verdict's link immediately, so `cursor = candidate.__rowid` always sits
+ * after all of that candidate's writes.
  */
 async function stageSupersession(db, llm, budget, embedFn, dryRun, stateDir, options = {}) {
     // Config values pass through `unknown`-typed JSON — validate rather than
@@ -1116,7 +1207,6 @@ async function stageSupersession(db, llm, budget, embedFn, dryRun, stateDir, opt
         return Number.isFinite(n) && ok(n) ? n : fallback;
     };
     const minSimilarity = validNumber(options.minSimilarity, exports.DEFAULT_SUPERSESSION_MIN_SIMILARITY, (n) => n > 0 && n <= 1);
-    const maxCalls = validNumber(options.maxCalls, exports.DEFAULT_SUPERSESSION_MAX_CALLS, (n) => n >= 0);
     const startCursor = (0, state_js_1.loadState)(stateDir).supersessionCursor ?? 0;
     const rows = db
         .prepare(
@@ -1136,10 +1226,26 @@ async function stageSupersession(db, llm, budget, embedFn, dryRun, stateDir, opt
     let superseded = 0;
     let skippedInfra = 0;
     let skippedIdempotent = 0;
-    let callsUsed = 0;
     let cursor = startCursor;
+    // #405: per-candidate checkpoint — persists the cursor after every fully
+    // considered candidate (updateState is an atomic temp-rename of a small
+    // file; the loop cadence is seconds per candidate, so the cost is
+    // negligible). The end-of-stage write below stays the authoritative final
+    // write.
+    const persistCursor = () => {
+        if (dryRun)
+            return;
+        (0, state_js_1.updateState)((s) => {
+            s.supersessionCursor = cursor;
+        }, stateDir);
+    };
     for (const candidate of rows) {
-        if (!dryRun && ((maxCalls > 0 && callsUsed >= maxCalls) || budget.exhausted))
+        // #405: the ONE run budget is the only call cap; the deadline stops the
+        // scan at the candidate boundary — the cursor holds at the last
+        // fully-considered candidate (persisted below).
+        if (!dryRun && budget.exhausted)
+            break;
+        if (!dryRun && options.deadline?.hit("supersession"))
             break;
         scanned++;
         let neighbors;
@@ -1149,6 +1255,7 @@ async function stageSupersession(db, llm, budget, embedFn, dryRun, stateDir, opt
         catch (err) {
             console.warn(`[hicortex] supersession: discovery failed for ${candidate.id.slice(0, 8)} — ${err instanceof Error ? err.message : String(err)}`);
             cursor = candidate.__rowid;
+            persistCursor(); // #405: every exit path persists
             continue;
         }
         for (const neighbor of neighbors) {
@@ -1158,9 +1265,8 @@ async function stageSupersession(db, llm, budget, embedFn, dryRun, stateDir, opt
             }
             if (dryRun)
                 continue; // preview only — no LLM call, no write
-            if ((maxCalls > 0 && callsUsed >= maxCalls) || !budget.use("supersession"))
-                break;
-            callsUsed++;
+            if (!budget.use("supersession"))
+                break; // #405: the ONE run budget
             const { verdict, usage } = await classifySupersession(llm, neighbor.content, candidate.content);
             // Meter every round-tripped attempt (#246) — even a null verdict spent
             // real tokens. The stage label matches the budget.use() above.
@@ -1184,6 +1290,10 @@ async function stageSupersession(db, llm, budget, embedFn, dryRun, stateDir, opt
             }
         }
         cursor = candidate.__rowid;
+        // #405: checkpoint after every fully-considered candidate (post-#404
+        // reconsolidation pattern) — a killed or deadline-deferred run loses at
+        // most the candidate in flight.
+        persistCursor();
     }
     if (!dryRun) {
         (0, state_js_1.updateState)((s) => {
@@ -1311,7 +1421,15 @@ function stageMemoryCapEviction(db, dryRun, cap) {
     // rejects negatives at the boundary, but this stage is callable directly).
     if (cap <= 0)
         return { cap, evicted: 0 };
-    const count = storage.countMemories(db);
+    // #422 (#317 discipline): the cap keys off LIVE (non-absorbed) rows on BOTH
+    // the count and the victim SELECT — absorbed rows are invisible evidence
+    // (no vector, no FTS, recall never serves them); they must neither consume
+    // cap headroom nor be picked as eviction victims. The DISPLAYED headroom
+    // (dashboard.ts headline live_memories vs memory_soft_cap) reads the same
+    // predicate, so the enforced and displayed caps cannot disagree.
+    const count = db
+        .prepare("SELECT COUNT(*) AS c FROM memories WHERE COALESCE(status, '') != 'absorbed'")
+        .get().c;
     if (count <= cap)
         return { cap, evicted: 0 };
     const surplus = count - cap;
@@ -1319,10 +1437,12 @@ function stageMemoryCapEviction(db, dryRun, cap) {
     // NOT NULL after scoring; the `?? 0.5` mirrors stageDecayPrune's defensive
     // default for unscored rows (inserts at 0.5). last_accessed is NULL until
     // first /recall-index exposure — COALESCE to created_at for the tiebreak so
-    // never-shown memories sort by when they entered the corpus.
+    // never-shown memories sort by when they entered the corpus. Same
+    // non-absorbed predicate as the count above.
     const rows = db
         .prepare(`SELECT id, base_strength, last_accessed, access_count, created_at
-         FROM memories`)
+         FROM memories
+        WHERE COALESCE(status, '') != 'absorbed'`)
         .all();
     const linkCounts = storage.getAllLinkCounts(db);
     const now = new Date();
@@ -1376,21 +1496,23 @@ async function skippedRunResolutionReport(db, dryRun, stateDir, options = {}) {
         return Number.isFinite(n) && ok(n) ? n : fallback;
     };
     const autoMergeThreshold = validNumber(options.autoMergeThreshold, dedup_js_1.DEFAULT_DEDUP_MERGE_THRESHOLD, (n) => n > 0 && n <= 1);
-    const maxMerges = validNumber(options.maxMerges, dedup_js_1.DEFAULT_DEDUP_NIGHTLY_MAX_MERGES, (n) => n >= 0);
     const merges = await (0, dedup_js_1.runDeterministicMergeZone)(db, {
         stateDir,
         threshold: autoMergeThreshold,
-        maxMerges,
         dryRun,
         acquireLock: options.acquireLock,
+        deadline: options.deadline,
     });
     const bandStats = {};
-    if (merges.max_merges > 0) {
+    {
+        // #405: recorded whenever the zone ran (the old max_merges>0 gate was a
+        // 0=disabled switch — the switch is gone).
         bandStats[`>=${autoMergeThreshold}`] = {
             pairs: merges.losers_merged,
             merge: merges.losers_merged,
             corrects: 0,
             supersedes: 0,
+            conflicts: 0,
             none: 0,
             merge_below_gate: 0,
             conf_sum: merges.losers_merged,
@@ -1416,29 +1538,52 @@ async function skippedRunResolutionReport(db, dryRun, stateDir, options = {}) {
         explicit_verified: 0,
         explicit_divergent: 0,
         cursor: (0, state_js_1.loadState)(stateDir).reconsolidationCursor ?? 0,
+        // #439 fields: zeros on a quiet night (no scan ran — nothing re-judged,
+        // new, skipped, or deferred; the type carries them so the report surface
+        // stays uniform).
+        pairs_reevaluated: 0,
+        pairs_new: 0,
+        skipped_absorbed: 0,
+        merge_pairs_deferred: 0,
         merges,
         merge_pairs_applied: 0,
         merge_below_gate: 0,
         skipped_above_ceiling: 0,
         skipped_metadata_mismatch: 0,
+        conflict_flagged: 0, // guard-C: no scan on a quiet night — nothing flagged
+        conflict_skipped: merges.skipped_conflict, // guard-C: the zone's guard still counts
+        scout_scanned: 0, // #393 B: the scan (and its shape calls) doesn't run on a quiet night
+        scout_correction_shaped: 0,
+        scout_candidates_found: 0,
         band_stats: bandStats,
     };
 }
 async function runConsolidation(db, llm, embedFn, dryRun = false, skipReflection = false, stateDir, domainOptions, supersessionOptions, 
-/** Total LLM-call ceiling across classify-tier stages (#241). The caller
- *  reads `consolidateMaxLlmCalls` from config and passes it; unset → the
- *  exported `CONSOLIDATE_MAX_LLM_CALLS` default (5000). */
+/** The ONE per-run LLM-call ceiling (#405/#241). The caller resolves
+ *  `nightlyLlmCallBudget` from config (consolidateMaxLlmCalls is a
+ *  deprecated alias — resolveNightlyLlmCallBudget) and passes it; unset →
+ *  the exported DEFAULT_NIGHTLY_LLM_CALL_BUDGET (5000). */
 budgetMaxCalls, 
 /** Soft cap on the corpus (#245). Nightly.ts reads `memorySoftCap` from
  *  config and passes it; unset → `DEFAULT_MEMORY_SOFT_CAP` (10000). `0`
  *  disables eviction (indefinite growth). */
 memorySoftCap, 
-/** Reconsolidation-stage knobs (#384), threaded from config by nightly.ts
- *  (correctionMinSimilarity / correctionRewriteMinConfidence) exactly like
- *  supersessionOptions above; unset fields → the stage's defaults.
- *  Appended AFTER the pre-#384 params so every existing positional caller
- *  (tests, hosted nightly) keeps its argument meaning. */
-reconsolidationOptions) {
+/** Reconsolidation-stage knobs (#384) — eval/test seams since #408 (the
+ *  values are release-managed calibration constants; nightly.ts threads
+ *  NOTHING), exactly like supersessionOptions above; unset fields → the
+ *  stage's calibration defaults. Appended AFTER the pre-#384 params so
+ *  every existing positional caller (tests, hosted nightly) keeps its
+ *  argument meaning. */
+reconsolidationOptions, 
+/**
+ * The run-wide pipeline deadline (#405), created at nightly start and
+ * shared by capture + every consolidation stage. Absent = no deadline
+ * (tests, evict-only paths, pre-#405 callers). When it fires, every
+ * not-yet-run stage defers (logs event=deadline_deferred stage=<name>) and
+ * the report status becomes "deferred" — which keeps lastConsolidated
+ * un-advanced so the next run re-finds the pending work.
+ */
+deadline) {
     const start = new Date();
     const report = {
         started_at: start.toISOString(),
@@ -1483,20 +1628,31 @@ reconsolidationOptions) {
         // stage report (telemetry's "skipped = zero LLM work" stays true), and
         // the zone never runs twice: the main path runs it INSIDE the stage, this
         // skip path returns before that.
-        report.stages.reconsolidation = await skippedRunResolutionReport(db, dryRun, stateDir, reconsolidationOptions);
+        report.stages.reconsolidation = await skippedRunResolutionReport(db, dryRun, stateDir, { ...reconsolidationOptions, deadline });
         report.status = "skipped";
         report.completed_at = new Date().toISOString();
         return report;
     }
-    // Config-overridable total LLM-call ceiling (#241). Default 5000 (was 200) —
-    // see CONSOLIDATE_MAX_LLM_CALLS. The caller reads `consolidateMaxLlmCalls`
-    // from config and passes it here.
-    const budget = new BudgetTracker(budgetMaxCalls ?? exports.CONSOLIDATE_MAX_LLM_CALLS);
+    // #405: the ONE per-run LLM-call ceiling (default 5000). The caller
+    // resolves `nightlyLlmCallBudget` from config (consolidateMaxLlmCalls is a
+    // deprecated alias — see resolveNightlyLlmCallBudget) and passes it here.
+    const budget = new BudgetTracker(budgetMaxCalls ?? exports.DEFAULT_NIGHTLY_LLM_CALL_BUDGET);
+    console.log(`[hicortex] Consolidation LLM call budget: ${budget.maxCalls} calls`);
     try {
+        // #405 stage gating: each boundary checks the run deadline; a hit defers
+        // that stage (absent from the report — it did not run) and logs
+        // event=deadline_deferred stage=<name> once. Later boundaries check
+        // independently, so a mid-run deadline reports every remaining stage as
+        // deferred. Deferred stages drain next run (cursors hold below them).
         // Stage 2: Importance Scoring
-        report.stages.importance = await stageImportance(db, scoreMemories, llm, budget, dryRun);
+        if (!deadline?.hit("importance")) {
+            report.stages.importance = await stageImportance(db, scoreMemories, llm, budget, dryRun, deadline);
+        }
         // Stage 2.5: Reflection
-        if (skipReflection) {
+        if (deadline?.hit("reflection")) {
+            // deferred — stage absent from the report
+        }
+        else if (skipReflection) {
             report.stages.reflection = {
                 lessons_generated: 0,
                 skipped: true,
@@ -1511,40 +1667,60 @@ reconsolidationOptions) {
         // domain list is configured. The single model serves all phases; if it's
         // down, the phase skips and retries on the next nightly run (no fallback).
         const cfgDomains = domainOptions?.domains;
-        if (cfgDomains && cfgDomains.length > 0) {
-            if (domainOptions?.contentDomainsReady === false) {
-                report.stages.domain_curation = {
-                    curated: false,
-                    domains: cfgDomains.length,
-                    reason: "reflect_endpoint_offline",
-                };
+        if (!deadline?.hit("domain_curation")) {
+            if (cfgDomains && cfgDomains.length > 0) {
+                if (domainOptions?.contentDomainsReady === false) {
+                    report.stages.domain_curation = {
+                        curated: false,
+                        domains: cfgDomains.length,
+                        reason: "reflect_endpoint_offline",
+                    };
+                }
+                else {
+                    report.stages.domain_curation = await stageContentDomains(db, cfgDomains, llm, budget, embedFn, dryRun, stateDir, domainOptions?.weakPrimaryFloor ?? nofit_js_1.DEFAULT_WEAK_PRIMARY_FLOOR, deadline);
+                }
             }
             else {
-                report.stages.domain_curation = await stageContentDomains(db, cfgDomains, llm, budget, embedFn, dryRun, stateDir, domainOptions?.weakPrimaryFloor ?? nofit_js_1.DEFAULT_WEAK_PRIMARY_FLOOR);
+                report.stages.domain_curation = await stageDomainCuration(db, llm, budget, dryRun, stateDir);
             }
         }
-        else {
-            report.stages.domain_curation = await stageDomainCuration(db, llm, budget, dryRun, stateDir);
+        // Stage 3: Link Discovery (heuristic edge classification — local work,
+        // but bounded by the same deadline as every other stage).
+        if (!deadline?.hit("links")) {
+            report.stages.links = await stageLinks(db, precheck.newMemories, embedFn, dryRun, llm, budget);
         }
-        // Stage 3: Link Discovery (with LLM-assisted edge classification)
-        report.stages.links = await stageLinks(db, precheck.newMemories, embedFn, dryRun, llm, budget);
         // Stage 3.5: Hub Detection — boost highly-connected memories
-        report.stages.hub_boost = stageHubBoost(db, dryRun);
+        if (!deadline?.hit("hub_boost")) {
+            report.stages.hub_boost = stageHubBoost(db, dryRun);
+        }
         // Stage 3.7: Supersession Detection (#191 Phase B)
-        report.stages.supersession = await stageSupersession(db, llm, budget, embedFn, dryRun, stateDir, supersessionOptions);
+        if (!deadline?.hit("supersession")) {
+            report.stages.supersession = await stageSupersession(db, llm, budget, embedFn, dryRun, stateDir, { ...supersessionOptions, deadline });
+        }
         // Stage 3.8: Reconsolidation (#384) — resolve corrections: rewrite
         // fact-shaped targets in place (absorbing transition-only triggers),
         // mark everything else. Rides the same shared budget under its own stage
         // label + cursor (supersession-stage pattern).
-        report.stages.reconsolidation = await (0, reconsolidation_js_1.stageReconsolidation)(db, llm, budget, embedFn, dryRun, stateDir, reconsolidationOptions);
+        if (!deadline?.hit("reconsolidation")) {
+            report.stages.reconsolidation = await (0, reconsolidation_js_1.stageReconsolidation)(db, llm, budget, embedFn, dryRun, stateDir, { ...reconsolidationOptions, deadline });
+        }
         // Stage 4: Decay & Prune
-        report.stages.decay_prune = stageDecayPrune(db, dryRun);
+        if (!deadline?.hit("decay_prune")) {
+            report.stages.decay_prune = stageDecayPrune(db, dryRun);
+        }
         // (Memory cap eviction moved before the precheck skip — see above.)
     }
     catch (err) {
         report.status = "failed";
         console.error("[hicortex] Consolidation pipeline error:", err);
     }
+    // #405: any deferred stage ⇒ the run is "deferred", not "completed" — the
+    // lastConsolidated gate below then holds the watermark so the next run's
+    // pending-set queries re-find the deferred work (mirrors endpoint_down).
+    // A thrown error still wins ("failed" is the more specific outcome).
+    if (report.status === "completed" && deadline && deadline.deferredStages().length > 0) {
+        report.status = "deferred";
+    }
     // Update last-consolidated timestamp. #357: the stages fail SOFT, so a run
     // against an endpoint that died mid-way still reports status "completed"
     // here — advancing the timestamp made state.json disagree with the
@@ -1568,59 +1744,3 @@ reconsolidationOptions) {
         Math.round((Date.now() - start.getTime()) / 100) / 10;
     return report;
 }
-// ---------------------------------------------------------------------------
-// Scheduling
-// ---------------------------------------------------------------------------
-/**
- * Calculate milliseconds until the next occurrence of a given hour (local time).
- */
-function msUntilHour(hour) {
-    const now = new Date();
-    const target = new Date(now);
-    target.setHours(hour, 30, 0, 0); // :30 past the hour
-    if (target.getTime() <= now.getTime()) {
-        // Already passed today, schedule for tomorrow
-        target.setDate(target.getDate() + 1);
-    }
-    return target.getTime() - now.getTime();
-}
-const ONE_DAY_MS = 24 * 60 * 60 * 1000;
-/**
- * Schedule the consolidation pipeline to run nightly.
- * Returns a cleanup function to cancel the timer.
- *
- * NOTE: currently unused (nightly.ts drives consolidation directly). Any future
- * caller MUST read config.domains and thread `domainOptions` into runConsolidation
- * when content domains are configured — otherwise it silently falls back to the
- * legacy project-grouping path even when a domain list is set.
- */
-function scheduleConsolidation(db, llm, embedFn, hour = 2) {
-    let timeout = null;
-    let interval = null;
-    const runAndScheduleInterval = () => {
-        runConsolidation(db, llm, embedFn)
-            .then((report) => {
-            console.log(`[hicortex] Consolidation ${report.status} in ${report.elapsed_seconds}s`);
-        })
-            .catch((err) => {
-            console.error("[hicortex] Consolidation failed:", err);
-        });
-        // Schedule recurring daily runs
-        if (!interval) {
-            interval = setInterval(() => {
-                runConsolidation(db, llm, embedFn).catch((err) => {
-                    console.error("[hicortex] Consolidation failed:", err);
-                });
-            }, ONE_DAY_MS);
-        }
-    };
-    const delay = msUntilHour(hour);
-    console.log(`[hicortex] Consolidation scheduled in ${Math.round(delay / 60_000)} minutes`);
-    timeout = setTimeout(runAndScheduleInterval, delay);
-    return () => {
-        if (timeout)
-            clearTimeout(timeout);
-        if (interval)
-            clearInterval(interval);
-    };
-}