@gamaze/hicortex 0.22.3 → 0.23.1

package/dist/reconsolidation.js

@@ -3,7 +3,7 @@
  * Reconsolidation (#384, #392) — the store resolves its own corrections, and
  * THE unified resolution stage.
  *
- * Nightly consolidation stage (runs as Stage 3.8, after supersession, before
+ * Nightly consolidation stage (runs as Stage 3.8, after links, before
  * decay/prune) that detects memories which correct, retract, supersede, or
  * DUPLICATE older ones; REWRITES corrected facts in place (absorbing
  * transition-only trigger memories), MERGES confirmed duplicates via the
@@ -45,8 +45,9 @@
  * planDedup and the judged mergeMemoryIds) refuse to blend a conflicts-linked
  * pair, counted as conflict_skipped. The zone therefore runs AFTER the scan —
  * with the zone first, a >=0.92 conflict pair was blended
- * before the judge ever saw it (the planted-eval harm: canonical=older, the
- * newer truth erased); running it last means verdicts/marks/binds land first
+ * before the judge ever saw it (the planted-eval harm: an unjudged blend —
+ * whichever row lost the canonical pick, its wording was simply erased);
+ * running it last means verdicts/marks/binds land first
  * and the zone merges only what no verdict claimed — a conflicts bind set by
  * this run's scan guards the SAME run's zone.
  *
@@ -154,10 +155,14 @@ exports.RECONSOLIDATION_STAGE_LABEL = "reconsolidation";
 /**
  * Default minimum COSINE similarity for a correction candidate pair —
  * RELEASE-MANAGED since #408 (calibration.ts CORRECTION_MIN_SIMILARITY;
- * provenance there). Lower than the supersession stage's 0.80 on purpose: a
- * retraction often rides inside an otherwise unrelated memory (the field
- * failure that opened this issue), so the neighborhood gate must be a touch
- * wider while the LLM verdict + confidence gate carry the precision load.
+ * provenance there). Deliberately wide: a retraction often rides inside an
+ * otherwise unrelated memory (the field failure that opened this issue), so
+ * the neighborhood gate must be a touch wider while the LLM verdict +
+ * confidence gate carry the precision load. Since #206-B (owner decision 6)
+ * this floor also subsumes the retired Stage 3.7 supersession scan's 0.80:
+ * 3.8 is the ONLY true-update detector, scanning every new memory — no
+ * shape gate, wider floor — with `corrects`/`supersedes` partitioning what
+ * 3.7's binary prompt called a supersession.
  */
 exports.DEFAULT_CORRECTION_MIN_SIMILARITY = CALIBRATION.CORRECTION_MIN_SIMILARITY;
 /**
@@ -167,11 +172,12 @@ exports.DEFAULT_CORRECTION_MIN_SIMILARITY = CALIBRATION.CORRECTION_MIN_SIMILARIT
  * weak rewrite is corruption.
  */
 exports.DEFAULT_CORRECTION_REWRITE_MIN_CONFIDENCE = CALIBRATION.CORRECTION_REWRITE_MIN_CONFIDENCE;
-/** Neighbor pool size before older/similarity filtering narrows to top 5 (supersession mirror). */
+/** Neighbor pool size before older/similarity filtering narrows to top 5
+ *  (formerly the supersession stage's constants — 3.8 inherited the shape). */
 const CORRECTION_NEIGHBOR_POOL = 15;
-/** Older-neighbor pairs kept per candidate after filtering (supersession mirror). */
+/** Older-neighbor pairs kept per candidate after filtering. */
 const CORRECTION_NEIGHBOR_TOP_K = 5;
-/** Content truncation for prompts (classify-tier cost profile; supersession precedent). */
+/** Content truncation for prompts (classify-tier cost profile). */
 const PROMPT_TRUNCATE_CHARS = 1500;
 /** Head of the old content quoted in the provenance footer. */
 exports.FOOTER_HEAD_MAX_CHARS = 160;
@@ -214,7 +220,7 @@ function nowIso() {
 }
 /**
  * Build the constrained correction-shape prompt (classify-tier cost profile:
- * 1500-char truncation, supersession/verdict precedent). The wording asks for
+ *  1500-char truncation, verdict-prompt precedent). The wording asks for
  * the OLD claim's distinctive terms — the field-failure mechanism is that a
  * correction CONTAINS the words of what it corrects, even when the surrounding
  * topics (and therefore the embedding cosine) are unrelated. Guard-C extends
@@ -237,7 +243,8 @@ function buildScoutShapePrompt(content) {
 /**
  * Parse the scout shape reply. Null on unparseable JSON, a missing/non-boolean
  * `correction`, or a missing/out-of-range `confidence` — the caller counts
- * skipped_infra and moves on (parseSupersessionReply discipline: never
+ * skipped_infra and moves on (the retired supersession stage's parse
+ * discipline, kept: never
  * mis-detect on ambiguity). `references` is lenient (missing/non-string → "")
  * because an empty string simply yields no FTS hits — a harmless miss, not a
  * mis-judgment.
@@ -264,7 +271,7 @@ function parseScoutShape(reply) {
     const references = typeof obj.references === "string" ? obj.references : "";
     return { correction: obj.correction, references: references.trim(), confidence };
 }
-/** Build the constrained pair-verdict prompt (1500-char truncation, supersession precedent). */
+/** Build the constrained pair-verdict prompt (1500-char truncation). */
 function buildCorrectionVerdictPrompt(oldContent, newContent) {
     const trunc = (s) => (s.length > PROMPT_TRUNCATE_CHARS ? `${s.slice(0, PROMPT_TRUNCATE_CHARS)}…` : s);
     return (`You are checking how a NEWER memory relates to an OLDER one in an AI agent's long-term memory.\n\n` +
@@ -287,7 +294,7 @@ function buildCorrectionVerdictPrompt(oldContent, newContent) {
 /**
  * Parse the pair verdict. Null on anything unparseable, unknown action, or an
  * out-of-range/missing confidence — the caller counts skipped_infra and moves
- * on (same discipline as parseSupersessionReply: never mis-judge on ambiguity).
+ * on (the same never-mis-judge-on-ambiguity discipline).
  */
 function parseCorrectionVerdict(reply) {
     if (!reply)
@@ -558,8 +565,8 @@ function accumulateBandStat(cumulative, run) {
     cumulative.none += run.none;
     cumulative.merge_below_gate += run.merge_below_gate;
     cumulative.conf_sum += run.conf_sum;
-    if (run.metadata_skipped !== undefined) {
-        cumulative.metadata_skipped = (cumulative.metadata_skipped ?? 0) + run.metadata_skipped;
+    if (run.project_skipped !== undefined) {
+        cumulative.project_skipped = (cumulative.project_skipped ?? 0) + run.project_skipped;
     }
 }
 /**
@@ -715,7 +722,9 @@ async function stageReconsolidation(db, llm, budget, embedFn, dryRun, stateDir,
     // re-detect). Once the backlog drains, pairs_reevaluated reads 0.
     const prevScannedRowid = (0, state_js_1.loadState)(stateDir).reconsolidationScannedRowid ?? startCursor;
     let scannedRowidHighwater = startCursor;
-    // NO shape filter (AC2) — unlike stageSupersession. Absorbed rows are
+    // NO shape filter (AC2) — also why 3.8 subsumes the retired Stage 3.7
+    // supersession scan (its shape gate would miss exactly these pairs).
+    // Absorbed rows are
     // excluded: they are invisible to recall and must not re-enter judgment.
     const rows = db
         .prepare(`SELECT rowid AS __rowid, * FROM memories
@@ -739,7 +748,7 @@ async function stageReconsolidation(db, llm, budget, embedFn, dryRun, stateDir,
     let explicitDivergent = 0;
     let mergeBelowGate = 0;
     let skippedAboveCeiling = 0;
-    let skippedMetadataMismatch = 0;
+    let skippedProjectMismatch = 0;
     let mergePairsApplied = 0;
     // #393 guard-C: conflicts verdicts rendered (link written, both live) and
     // judged-path merge refusals on a conflicts-linked pair.
@@ -1228,10 +1237,10 @@ async function stageReconsolidation(db, llm, budget, embedFn, dryRun, stateDir,
                                         console.log(`[hicortex] Reconsolidation: merged ${pair.oldId.slice(0, 8)} + ${pair.newId.slice(0, 8)} ` +
                                             `into canonical ${result.canonicalId.slice(0, 8)} (${result.linksRepointed} link(s) re-pointed)`);
                                     }
-                                    else if (result.reason === "metadata_mismatch") {
-                                        skippedMetadataMismatch++;
+                                    else if (result.reason === "project_mismatch") {
+                                        skippedProjectMismatch++;
                                         console.log(`[hicortex] Reconsolidation: merge of ${pair.oldId.slice(0, 8)} + ${pair.newId.slice(0, 8)} ` +
-                                            `skipped (metadata mismatch) — both kept`);
+                                            `skipped (project mismatch) — both kept`);
                                     }
                                     else if (result.reason === "conflict_linked") {
                                         // #393 guard-C: the pair is conflicts-linked (operator-planted
@@ -1446,10 +1455,10 @@ async function stageReconsolidation(db, llm, budget, embedFn, dryRun, stateDir,
                                 console.log(`[hicortex] Reconsolidation: merged ${pair.oldId.slice(0, 8)} + ${pair.newId.slice(0, 8)} ` +
                                     `into canonical ${result.canonicalId.slice(0, 8)} (${result.linksRepointed} link(s) re-pointed)`);
                             }
-                            else if (result.reason === "metadata_mismatch") {
-                                skippedMetadataMismatch++;
+                            else if (result.reason === "project_mismatch") {
+                                skippedProjectMismatch++;
                                 console.log(`[hicortex] Reconsolidation: merge of ${pair.oldId.slice(0, 8)} + ${pair.newId.slice(0, 8)} ` +
-                                    `skipped (metadata mismatch) — both kept`);
+                                    `skipped (project mismatch) — both kept`);
                             }
                             else if (result.reason === "conflict_linked") {
                                 conflictSkippedJudged++;
@@ -1473,7 +1482,8 @@ async function stageReconsolidation(db, llm, budget, embedFn, dryRun, stateDir,
     // deterministic sweep: verdicts, marks, and binds land first, and the zone
     // merges only what no verdict claimed. With the zone first, a >=0.92
     // genuine-conflict pair was blended before the judge ever saw it
-    // (canonical = oldest, the newer truth erased — the planted-eval harm);
+    // (an unjudged blend — the canonical-pick loser's wording erased —
+    // the planted-eval harm);
     // running it last means a `conflicts` bind set by THIS run's scan guards
     // the SAME run's zone. LLM-free and budget-free — an LLM-less night still
     // drains duplicates (a deadline-deferred cluster re-detects next run at
@@ -1499,8 +1509,8 @@ async function stageReconsolidation(db, llm, budget, embedFn, dryRun, stateDir,
         det.pairs = merges.losers_merged;
         det.merge = merges.losers_merged;
         det.conf_sum = merges.losers_merged;
-        if (merges.skipped_metadata_mismatch > 0) {
-            det.metadata_skipped = merges.skipped_metadata_mismatch;
+        if (merges.skipped_project_mismatch > 0) {
+            det.project_skipped = merges.skipped_project_mismatch;
         }
         bandStats[`>=${autoMergeThreshold}`] = det;
     }
@@ -1569,7 +1579,7 @@ async function stageReconsolidation(db, llm, budget, embedFn, dryRun, stateDir,
         merge_pairs_applied: mergePairsApplied,
         merge_below_gate: mergeBelowGate,
         skipped_above_ceiling: skippedAboveCeiling,
-        skipped_metadata_mismatch: skippedMetadataMismatch,
+        skipped_project_mismatch: skippedProjectMismatch,
         conflict_flagged: conflictFlagged,
         conflict_skipped: conflictSkippedJudged + merges.skipped_conflict,
         scout_scanned: scoutScanned,

package/dist/relink.d.ts

@@ -86,8 +86,8 @@ export interface RelinkReport {
 /**
  * Read the stored embedding for a memory from memory_vectors.
  * Returns null when the row is missing (caller falls back to re-embedding).
- * @deprecated moved to storage.ts (shared with consolidate.ts's supersession
- * stage); re-exported here so existing importers of relink.ts keep working.
+ * @deprecated moved to storage.ts (shared with the resolution stages);
+ * re-exported here so existing importers of relink.ts keep working.
  */
 export { getStoredEmbedding } from "./storage.js";
 /**

package/dist/relink.js

@@ -107,8 +107,8 @@ function loadExistingPairs(db) {
 /**
  * Read the stored embedding for a memory from memory_vectors.
  * Returns null when the row is missing (caller falls back to re-embedding).
- * @deprecated moved to storage.ts (shared with consolidate.ts's supersession
- * stage); re-exported here so existing importers of relink.ts keep working.
+ * @deprecated moved to storage.ts (shared with the resolution stages);
+ * re-exported here so existing importers of relink.ts keep working.
  */
 var storage_js_1 = require("./storage.js");
 Object.defineProperty(exports, "getStoredEmbedding", { enumerable: true, get: function () { return storage_js_1.getStoredEmbedding; } });

package/dist/retrieval.d.ts

@@ -155,14 +155,15 @@ export declare function recallQueryVector(registry: CentroidStore, sessionId: st
 }): Float32Array;
 /**
  * Ids among `candidateIds` that have been superseded by a later memory — i.e.
- * they are the SOURCE of a `superseded_by` link (stageSupersession links
- * old → new). One query, not per-candidate.
+ * they are the SOURCE of a `superseded_by` link (the resolution pass links
+ * old → new; formerly also the retired Stage 3.7 supersession scan). One
+ * query, not per-candidate.
  */
 export declare function findSupersededIds(db: Database.Database, candidateIds: string[]): Set<string>;
 /**
  * The full ranking-demotion set among `candidateIds` (#384): the UNION of
- * (a) sources of a `superseded_by` link (legacy + stageSupersession — link
- * driven, works on pre-v14 rows with NULL status) and (b) rows whose
+ * (a) sources of a `superseded_by` link (legacy + retired-3.7 + resolution
+ * verdicts — link driven, works on pre-v14 rows with NULL status) and (b) rows whose
  * `memories.status` is 'superseded' or 'retracted' (reconsolidation marks +
  * explicit ingest marks). `corrected` is deliberately NOT demoting — a
  * rewritten memory carries the CORRECTION, and demoting it would bury the

package/dist/retrieval.js

@@ -275,8 +275,9 @@ function recallQueryVector(registry, sessionId, promptEmb, opts) {
 }
 /**
  * Ids among `candidateIds` that have been superseded by a later memory — i.e.
- * they are the SOURCE of a `superseded_by` link (stageSupersession links
- * old → new). One query, not per-candidate.
+ * they are the SOURCE of a `superseded_by` link (the resolution pass links
+ * old → new; formerly also the retired Stage 3.7 supersession scan). One
+ * query, not per-candidate.
  */
 function findSupersededIds(db, candidateIds) {
     if (candidateIds.length === 0)
@@ -290,8 +291,8 @@ function findSupersededIds(db, candidateIds) {
 }
 /**
  * The full ranking-demotion set among `candidateIds` (#384): the UNION of
- * (a) sources of a `superseded_by` link (legacy + stageSupersession — link
- * driven, works on pre-v14 rows with NULL status) and (b) rows whose
+ * (a) sources of a `superseded_by` link (legacy + retired-3.7 + resolution
+ * verdicts — link driven, works on pre-v14 rows with NULL status) and (b) rows whose
  * `memories.status` is 'superseded' or 'retracted' (reconsolidation marks +
  * explicit ingest marks). `corrected` is deliberately NOT demoting — a
  * rewritten memory carries the CORRECTION, and demoting it would bury the

package/dist/state.d.ts

@@ -51,19 +51,19 @@ export interface HicortexState {
      */
     domainCursor?: number;
     /**
-     * Resume cursor for the nightly's supersession-detection stage (#191 Phase
-     * B) — highest memories.rowid whose decision/correction candidates have
-     * been evaluated (or infra-skipped) this run. Absent/0 = never run. Unlike
-     * relinkCursor/domainCursor (separate resumable CLI commands), this cursor
-     * advances within the shared nightly LLM call budget as part of the regular
-     * nightly — the corpus is back-processed gradually over many nights.
+     * #206-B: the retired supersession stage's cursor key
+     * (`supersessionCursor`) is deliberately NOT modeled here anymore. The
+     * stage (3.7, #191 Phase B) is retired into the reconsolidation pass, the
+     * whole-corpus backfill was complete before retirement, and nothing reads
+     * the key — pre-#206-B installs keep their stale value on disk, left to
+     * rot unread (no migration, no deletion). Do not repurpose the name.
      */
-    supersessionCursor?: number;
     /**
      * Resume cursor for the nightly's reconsolidation stage (#384) — highest
      * memories.rowid whose candidates have been evaluated (or infra-skipped)
      * with all their CONFIRMED work applied. Absent/0 = never run. Same
-     * advance-past-considered-candidates discipline as supersessionCursor,
+     * advance-past-considered-candidates discipline (formerly the retired
+     * supersessionCursor's),
      * 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.

package/dist/storage.d.ts

@@ -149,8 +149,8 @@ export declare function getMemoryTagsWeightedBatched(db: Database.Database, memo
  * Read the stored embedding for a memory from memory_vectors.
  * Returns null when the row is missing (caller falls back to re-embedding).
  *
- * Shared by `hicortex relink` and the nightly's supersession stage
- * (consolidate.ts) — lives here (not in relink.ts) so consolidate.ts can use
+ * Shared by `hicortex relink` and the nightly's resolution stages
+ * (reconsolidation.ts, consolidate.ts) — lives here (not in relink.ts) so they can use
  * it without importing from relink.ts, which itself imports from
  * consolidate.ts (BudgetTracker, discoverLinkCandidates).
  */

package/dist/storage.js

@@ -408,8 +408,8 @@ function getMemoryTagsWeightedBatched(db, memoryIds) {
  * Read the stored embedding for a memory from memory_vectors.
  * Returns null when the row is missing (caller falls back to re-embedding).
  *
- * Shared by `hicortex relink` and the nightly's supersession stage
- * (consolidate.ts) — lives here (not in relink.ts) so consolidate.ts can use
+ * Shared by `hicortex relink` and the nightly's resolution stages
+ * (reconsolidation.ts, consolidate.ts) — lives here (not in relink.ts) so they can use
  * it without importing from relink.ts, which itself imports from
  * consolidate.ts (BudgetTracker, discoverLinkCandidates).
  */

package/dist/sweep-volatile.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `hicortex sweep-volatile` (#489, deliverable iii — owner decision 3).
+ *
+ * The ONE-SHOT store sweep: the live corpus already holds the GH-status /
+ * version-bump rows gold set A adjudicated ("not healthy to have GH in mem").
+ * This command reuses the SAME deterministic gate the distill path applies
+ * (distiller.ts isVolatileStatusEntry — one gate, one meaning) over the stored
+ * corpus. Mirrors `dedup`:
+ *
+ *   - DRY RUN by default: report candidates only, zero writes.
+ *   - `--apply` is explicit and ordered capture-lock (fail fast) →
+ *     pre-sweep backup (abort ALL writes if it fails) → one transaction.
+ *   - NO hard deletes: swept rows are DEMOTED via storage.absorbMemory —
+ *     status 'absorbed' (recall-invisible everywhere: vector + FTS rows
+ *     dropped, and every read path already handles the state), plain row +
+ *     links retained as evidence. Recovery posture = the dedup posture: the
+ *     pre-sweep backup IS the rollback. The shared absorb primitive means no
+ *     new status vocabulary to thread through candidate paths.
+ *   - Tags cleared + domain NULL'd before absorb (dedup's rule: an absorbed
+ *     row must not count in moduleIndex/tag recomputes).
+ *   - Audit trail: one `volatile_sweep_log` row per swept memory (migration
+ *     v23) — inspectable forever, never silent. No runtime consumer; the
+ *     CAPTURE-side volatility gate is the re-ingest safety net.
+ *
+ * Server-mode only (needs the local DB), like dedup/relink/classify-domains.
+ */
+import { acquireCaptureLock } from "./capture.js";
+export interface SweepVolatileOptions {
+    /** Execute the sweep. Default false = dry run (report only, zero writes). */
+    apply?: boolean;
+    /** DB path override (tests / manual snapshot verification). */
+    dbPath?: string;
+    /** State dir override (tests). Defaults to ~/.hicortex. Backup lands under
+     *  here/backups/. */
+    stateDir?: string;
+    /** Config override (tests). Defaults to reading stateDir/config.json. */
+    config?: Record<string, unknown> | null;
+    /** Capture-lock acquirer override (tests). Defaults to capture.ts's lock. */
+    acquireLock?: typeof acquireCaptureLock;
+}
+export interface SweepVolatileReport {
+    dryRun: boolean;
+    /** Live rows the gate flags, in store order. Empty when the kill-switch is
+     *  off (the sweep is inert without the gate — same release-managed switch,
+     *  one meaning). */
+    candidates: Array<{
+        id: string;
+        preview: string;
+    }>;
+    /** --apply only: rows actually swept (absorbed). */
+    swept?: number;
+    /** --apply only: path to the pre-sweep backup. */
+    backupPath?: string;
+}
+export declare function runSweepVolatile(options?: SweepVolatileOptions): Promise<SweepVolatileReport>;

package/dist/sweep-volatile.js

@@ -0,0 +1,184 @@
+"use strict";
+/**
+ * `hicortex sweep-volatile` (#489, deliverable iii — owner decision 3).
+ *
+ * The ONE-SHOT store sweep: the live corpus already holds the GH-status /
+ * version-bump rows gold set A adjudicated ("not healthy to have GH in mem").
+ * This command reuses the SAME deterministic gate the distill path applies
+ * (distiller.ts isVolatileStatusEntry — one gate, one meaning) over the stored
+ * corpus. Mirrors `dedup`:
+ *
+ *   - DRY RUN by default: report candidates only, zero writes.
+ *   - `--apply` is explicit and ordered capture-lock (fail fast) →
+ *     pre-sweep backup (abort ALL writes if it fails) → one transaction.
+ *   - NO hard deletes: swept rows are DEMOTED via storage.absorbMemory —
+ *     status 'absorbed' (recall-invisible everywhere: vector + FTS rows
+ *     dropped, and every read path already handles the state), plain row +
+ *     links retained as evidence. Recovery posture = the dedup posture: the
+ *     pre-sweep backup IS the rollback. The shared absorb primitive means no
+ *     new status vocabulary to thread through candidate paths.
+ *   - Tags cleared + domain NULL'd before absorb (dedup's rule: an absorbed
+ *     row must not count in moduleIndex/tag recomputes).
+ *   - Audit trail: one `volatile_sweep_log` row per swept memory (migration
+ *     v23) — inspectable forever, never silent. No runtime consumer; the
+ *     CAPTURE-side volatility gate is the re-ingest safety net.
+ *
+ * Server-mode only (needs the local DB), like dedup/relink/classify-domains.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runSweepVolatile = runSweepVolatile;
+const paths_js_1 = require("./paths.js");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const db_js_1 = require("./db.js");
+const storage = __importStar(require("./storage.js"));
+const distiller_js_1 = require("./distiller.js");
+const capture_js_1 = require("./capture.js");
+const config_read_js_1 = require("./config-read.js");
+const calibration_js_1 = require("./calibration.js");
+const backup_js_1 = require("./backup.js");
+const HICORTEX_HOME = (0, paths_js_1.hicortexHome)();
+/** Pre-sweep backup filename pattern — scoped retention (like pre-dedup). */
+const PRE_SWEEP_BACKUP_PATTERN = /^pre-sweep-volatile-.*\.db$/;
+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;
+    }
+}
+/** Live-row filter: active or content-rewritten rows only. Already-retired
+ *  states are not candidates — 'absorbed' is invisible already; 'superseded'
+ *  / 'retracted' are demoted already. */
+const LIVE_ROW_WHERE = `COALESCE(status, '') NOT IN ('absorbed', 'superseded', 'retracted')`;
+/**
+ * Pre-sweep DB backup to <stateDir>/backups/pre-sweep-volatile-<ISO>.db,
+ * pruned to `backupRetention` newest (pattern-scoped, like pre-dedup).
+ * THROWS on failure — runSweepVolatile aborts the whole sweep when it does.
+ */
+async function takePreSweepBackup(db, stateDir, config) {
+    const backupDir = (0, node_path_1.join)(stateDir, "backups");
+    (0, node_fs_1.mkdirSync)(backupDir, { recursive: true });
+    const backupPath = (0, node_path_1.join)(backupDir, `pre-sweep-volatile-${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_SWEEP_BACKUP_PATTERN);
+    return backupPath;
+}
+async function runSweepVolatile(options = {}) {
+    const stateDir = options.stateDir ?? HICORTEX_HOME;
+    const config = options.config !== undefined ? options.config : readConfig(stateDir);
+    // Server-mode only — client installs have no local DB.
+    if (config?.mode === "client") {
+        throw new Error("[hicortex] sweep-volatile is server-mode only (it needs the local DB). " +
+            `This machine is a client of ${config.serverUrl ?? "a remote server"} — run sweep-volatile on the server.`);
+    }
+    const apply = options.apply ?? false;
+    const dbPath = (0, db_js_1.resolveDbPath)(options.dbPath);
+    const db = (0, db_js_1.initDb)(dbPath);
+    try {
+        console.log(`[hicortex] sweep-volatile starting (${apply ? "APPLY" : "dry-run"}): db ${dbPath}`);
+        const rows = db
+            .prepare(`SELECT id, content FROM memories WHERE ${LIVE_ROW_WHERE}`)
+            .all();
+        const candidates = calibration_js_1.VOLATILE_STATUS_FILTER
+            ? rows
+                .filter((r) => (0, distiller_js_1.isVolatileStatusEntry)(r.content))
+                .map((r) => ({ id: r.id, preview: r.content.slice(0, 120) }))
+            : [];
+        if (!calibration_js_1.VOLATILE_STATUS_FILTER) {
+            console.warn("[hicortex] sweep-volatile: the volatility gate is switched off in this release (VOLATILE_STATUS_FILTER) — nothing to sweep.");
+        }
+        const report = { dryRun: !apply, candidates };
+        console.log(`[hicortex] sweep-volatile: ${candidates.length} volatile row(s) among ${rows.length} live (` +
+            `${apply ? "demoting via absorb" : "dry run — zero writes"})`);
+        if (!apply) {
+            for (const c of candidates) {
+                console.log(`[hicortex]   ${c.id.slice(0, 8)}: "${c.preview}"`);
+            }
+            if (candidates.length === 0)
+                console.log("[hicortex]   (nothing matched the gate)");
+            return report;
+        }
+        if (candidates.length === 0)
+            return report;
+        // --apply: fail fast on a busy capture lock — the audit rows and absorb
+        // writes must not race a nightly/capture run (dedup posture).
+        const acquireLock = options.acquireLock ?? capture_js_1.acquireCaptureLock;
+        const releaseLock = await acquireLock(stateDir, 0);
+        if (!releaseLock) {
+            throw new Error("[hicortex] sweep-volatile --apply aborted: another capture/nightly run holds the lock. Retry when it finishes.");
+        }
+        try {
+            // Backup FIRST — abort entirely (no writes attempted) if it fails.
+            let backupPath;
+            try {
+                backupPath = await takePreSweepBackup(db, stateDir, config);
+            }
+            catch (err) {
+                throw new Error(`[hicortex] sweep-volatile --apply aborted: backup failed (${err instanceof Error ? err.message : String(err)}). No rows swept.`);
+            }
+            console.log(`[hicortex] Backup written: ${backupPath}`);
+            report.backupPath = backupPath;
+            // ONE transaction: audit row + tag/domain clear + absorb per row. Any
+            // failure rolls back the whole sweep (all-or-nothing, like /distill's
+            // insert phase) — a partial sweep is never left behind.
+            const sweep = db.transaction(() => {
+                const clearTags = db.prepare("DELETE FROM memory_tags WHERE memory_id = ?");
+                const audit = db.prepare("INSERT OR REPLACE INTO volatile_sweep_log (memory_id, swept_at, preview) VALUES (?, ?, ?)");
+                const now = new Date().toISOString();
+                for (const c of candidates) {
+                    audit.run(c.id, now, c.preview);
+                    clearTags.run(c.id);
+                    storage.updateMemory(db, c.id, { domain: null });
+                    storage.absorbMemory(db, c.id);
+                }
+            });
+            sweep();
+            report.swept = candidates.length;
+            console.log(`[hicortex] sweep-volatile: swept (absorbed) ${report.swept} row(s); ` +
+                `rollback = restore ${backupPath}`);
+            return report;
+        }
+        finally {
+            releaseLock();
+        }
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/types.d.ts

@@ -37,9 +37,13 @@ export interface Memory {
      * never config: NULL/absent = active (the default, and every pre-v14 row);
      * 'superseded'/'retracted' = marked stale or wrong (demoted in ranking);
      * 'corrected' = rewritten in place (does NOT demote — demoting it would
-     * bury the correction); 'absorbed' = invisible to recall (trigger memory
-     * folded into a corrected target — no vector/FTS row, plain row + link
-     * kept as evidence and rollback reference).
+     * bury the correction); 'absorbed' = invisible to recall (no vector/FTS
+     * row, plain row + links kept as evidence and rollback reference). Writers
+     * of 'absorbed': the reconsolidation rewrite path (trigger folded into a
+     * corrected target), dedup merge losers (#392), and the one-shot
+     * `sweep-volatile` demotion (#489 — volatile rows retire through the SAME
+     * primitive, so no new status vocabulary exists to thread through read
+     * paths; recovery is the pre-sweep backup).
      */
     status?: string | null;
     /**
@@ -128,8 +132,13 @@ export interface ResolutionBandStat {
     merge_below_gate: number;
     /** Sum of verdict confidences (divide by `pairs` for the mean). Deterministic merges count 1.0 each. */
     conf_sum: number;
-    /** Deterministic band only: clusters refused by the metadata rails. */
-    metadata_skipped?: number;
+    /**
+     * Deterministic band only: clusters refused by the project rail. #206
+     * decision 2 renamed this from `metadata_skipped` when the source_agent
+     * rail was removed — pre-rename cumulative values stay on disk unread
+     * (their semantics conflated both rails).
+     */
+    project_skipped?: number;
 }
 /**
  * Report of the deterministic merge zone (#392) — the band at/above the merge
@@ -151,8 +160,8 @@ export interface DeterministicMergeZoneReport {
     losers_merged: number;
     /** Loser links re-pointed onto canonicals this run. */
     links_repointed: number;
-    /** Clusters skipped — members disagree on project / source_agent. */
-    skipped_metadata_mismatch: number;
+    /** Clusters skipped — members disagree on project (#206 decision 2: the source_agent rail is removed). */
+    skipped_project_mismatch: number;
     /**
      * #393 guard-C: clusters skipped because a member pair holds a `conflicts`
      * link — a judge-flagged genuine conflict is never blended, both records
@@ -251,27 +260,15 @@ export interface ConsolidationReport {
             heuristic_fallback?: number;
             failed: number;
         };
-        /** Supersession detection (#191 Phase B) — runs after linking, before decay/prune. */
-        supersession?: {
-            /** Decision/correction-shaped candidates examined this run. */
-            scanned: number;
-            /** Older-neighbor pairs actually sent to the classify-tier LLM. */
-            evaluated: number;
-            /** Pairs the LLM judged superseded — a `superseded_by` link was created. */
-            superseded: number;
-            /** Pairs skipped on a parse/infra error (retried naturally next night). */
-            skipped_infra: number;
-            /** Pairs skipped because a superseded_by link already existed (either direction). */
-            skipped_idempotent: number;
-            /** supersessionCursor after this run (unchanged in dry-run). */
-            cursor: number;
-        };
         /**
-         * Reconsolidation (#384) — runs after supersession, before decay/prune.
+         * Reconsolidation (#384) — runs after linking, before decay/prune.
          * Since #392 this is THE unified resolution stage: its verdict also carries
          * a `merge` disposition, and the deterministic merge zone (pairs at/above
          * the merge ceiling — release-managed since #408) runs inside it,
-         * LLM-free, before the scan.
+         * LLM-free, before the scan. Since #206-B (owner decision 6) it is also
+         * the ONLY true-update detector — the standalone supersession stage
+         * (3.7, #191 Phase B) is retired into its `supersedes` verdict action,
+         * and its former `supersession` report slot no longer exists.
          */
         reconsolidation?: {
             /** Candidates examined this run (rowid > cursor; no shape filter). */
@@ -358,11 +355,12 @@ export interface ConsolidationReport {
              */
             skipped_above_ceiling: number;
             /**
-             * #392: judged merge pairs refused by the metadata rails (project /
-             * source_agent disagreement). Both memories kept; the cursor advances —
-             * the verdict was rendered, this is not an infra failure.
+             * #392: judged merge pairs refused by the project rail (project
+             * disagreement — the only metadata rail, #206 decision 2). Both
+             * memories kept; the cursor advances — the verdict was rendered, this
+             * is not an infra failure.
              */
-            skipped_metadata_mismatch: number;
+            skipped_project_mismatch: number;
             /**
              * #393 guard-C: verdicts that flagged a genuine conflict — a `conflicts`
              * link was written, both memories stay live (no status change, no