@gamaze/hicortex 0.20.3 → 0.20.5

package/dist/reconsolidation.d.ts

@@ -0,0 +1,323 @@
+/**
+ * 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
+ * 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
+ * dedup core (absorbing the loser), and marks everything else. Companions to
+ * the stage:
+ *  - explicit write-time marking (`corrects`/`supersedes` at /ingest +
+ *    `hicortex_ingest`) — deterministic link + status, zero LLM;
+ *  - `memory_history` audit + the `hicortex history` CLI (listing + rollback).
+ *
+ * #392 — one zone system, ONE verdict per pair: below `correctionMinSimilarity`
+ * (floor, 0.75) pairs are not candidates; in [floor, `dedupAutoMergeThreshold`)
+ * (ceiling, 0.92) each unlinked pair gets ONE verdict call whose action is
+ * `merge` | `corrects` | `supersedes` | `none`; at/above the ceiling the
+ * deterministic merge zone (dedup.ts runDeterministicMergeZone — LLM-free,
+ * budget-free) owns the pair. The merge disposition reuses the dedup core's
+ * execution (canonical pick, link re-point, dedup_log, metadata rails); a
+ * merge verdict below `correctionRewriteMinConfidence` keeps both memories.
+ *
+ * Status vocabulary (code-defined, extensible — deliberately NOT config):
+ *   NULL/'active' default | 'superseded' + 'retracted' demote in ranking |
+ *   'corrected' = rewritten, never demotes (demoting it would bury the
+ *   correction — the exact failure this stage fixes) | 'absorbed' = invisible
+ *   to recall (no vector row, no FTS row; plain row + link kept as evidence,
+ *   session lineage, rollback reference). Merge losers share 'absorbed'
+ *   (storage.absorbMemory is the one primitive) — the only difference is the
+ *   audit trail: rewrites roll back via memory_history; merges recover via
+ *   dedup_log + the retained loser row (NOT history-rollback-able).
+ *
+ * This module deliberately does NOT import consolidate.ts (which imports this
+ * module to wire the stage) — the budget is consumed through the structural
+ * StageBudget interface below, which BudgetTracker satisfies. dedup.ts is
+ * imported (never the reverse) for the merge core.
+ */
+import type Database from "better-sqlite3";
+import type { LlmClient, LlmUsage } from "./llm.js";
+import type { ConsolidationReport } from "./types.js";
+import type { EmbedFn } from "./retrieval.js";
+import { acquireCaptureLock } from "./capture.js";
+/** Stage label used for every budget.use()/recordUsage() call (#384). */
+export declare const RECONSOLIDATION_STAGE_LABEL = "reconsolidation";
+/**
+ * Default minimum COSINE similarity for a correction candidate pair. 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.
+ */
+export declare const DEFAULT_CORRECTION_MIN_SIMILARITY = 0.75;
+/**
+ * Default minimum verdict confidence for the REWRITE fork. Below this a
+ * `corrects` verdict degrades to mark-only — a weak mark is recoverable, a
+ * weak rewrite is corruption.
+ */
+export declare const DEFAULT_CORRECTION_REWRITE_MIN_CONFIDENCE = 0.8;
+/** Head of the old content quoted in the provenance footer. */
+export declare const FOOTER_HEAD_MAX_CHARS = 160;
+/** The code-defined status vocabulary (see module doc). Not user-configurable. */
+export type MemoryStatus = "superseded" | "retracted" | "corrected" | "absorbed";
+/**
+ * Statuses that demote a memory's ranking score (retrieval.ts findDemotedIds).
+ * 'corrected' is deliberately absent — see module doc.
+ */
+export declare const DEMOTED_STATUSES: readonly [MemoryStatus, MemoryStatus];
+/** structural subset of consolidate.BudgetTracker (avoids an import cycle). */
+export interface StageBudget {
+    readonly exhausted: boolean;
+    use(stage: string, count?: number): boolean;
+    recordUsage(stage: string, usage: LlmUsage | undefined): void;
+}
+export interface ReconsolidationOptions {
+    /** correctionMinSimilarity (config; default 0.75). Invalid → default. */
+    minSimilarity?: number;
+    /** correctionRewriteMinConfidence (config; default 0.80). Invalid → default. */
+    rewriteMinConfidence?: number;
+    /**
+     * dedupAutoMergeThreshold (config; default 0.92; legacy dedupMergeThreshold
+     * honored by nightly.ts when the new key is absent). The deterministic/LLM
+     * boundary of the unified resolution pass (#392): pairs at/above it merge
+     * via the LLM-free zone, pairs in [floor, ceiling) get the verdict.
+     * Invalid → default.
+     */
+    autoMergeThreshold?: number;
+    /**
+     * dedupNightlyMaxMerges (config; default 250; 0 disables the merge
+     * machinery). Counts merge OPERATIONS per run — zone clusters + judged
+     * pair merges against ONE cap. Invalid → default.
+     */
+    maxMerges?: number;
+    /**
+     * Capture-lock acquirer override (tests) — the deterministic zone and the
+     * judged-merge phase each hold a short lock window. Defaults to the real
+     * capture.ts lock. DedupOptions.acquireLock pattern.
+     */
+    acquireLock?: typeof acquireCaptureLock;
+}
+/** The 14-field stage report (typed once, in ConsolidationReport). */
+export type ReconsolidationStageResult = NonNullable<ConsolidationReport["stages"]["reconsolidation"]>;
+/**
+ * True when a memory is REWRITE-ELIGIBLE — a fact-shaped target. The fork is
+ * keyed on the existing taxonomy the code already trusts (facts are
+ * rewritten; decisions/plans/experiences are history, marked only).
+ */
+export declare function isFactShapedTarget(mem: {
+    memory_type: string;
+    content: string;
+}): boolean;
+/**
+ * The unified resolution verdict (#392): ONE call per unlinked pair decides
+ * how the newer memory relates to the older — merge (same underlying
+ * fact/verdict, differing in wording/qualifiers), corrects, supersedes, or
+ * none (related but distinct).
+ */
+export type ResolutionAction = "merge" | "corrects" | "supersedes" | "none";
+/** Build the constrained pair-verdict prompt (1500-char truncation, supersession precedent). */
+export declare function buildCorrectionVerdictPrompt(oldContent: string, newContent: string): string;
+export interface CorrectionVerdict {
+    action: ResolutionAction;
+    confidence: number;
+}
+/**
+ * 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).
+ */
+export declare function parseCorrectionVerdict(reply: string): CorrectionVerdict | null;
+export interface RewriteTriggerDisposition {
+    id: string;
+    disposition: "absorb" | "keep";
+}
+export interface RewriteContract {
+    rewritten: string;
+    triggers: RewriteTriggerDisposition[];
+}
+/** Build the constrained rewrite prompt: old content + N trigger contents, nothing else. */
+export declare function buildRewritePrompt(oldContent: string, triggers: Array<{
+    id: string;
+    content: string;
+}>): string;
+/**
+ * Parse + validate the rewrite contract (AC4). Null on ANY failure:
+ *  - unparseable JSON / wrong shape;
+ *  - rewritten empty, identical to the old content, or longer than
+ *    old + 2000 + 500 per additional trigger;
+ *  - the triggers array not covering every input trigger id exactly once
+ *    (missing, unknown, or duplicated) or carrying an invalid disposition.
+ * A null return degrades the WHOLE group to mark-only (never a partial apply).
+ */
+export declare function parseRewriteReply(reply: string, expectedTriggerIds: string[], oldContent: string): RewriteContract | null;
+/**
+ * The provenance footer appended to every rewritten memory:
+ * `previously believed "<≤160-char head of old content>" until <date>`.
+ * date = the ISO DATE (YYYY-MM-DD) derived from the latest trigger's
+ * created_at — the same trigger recorded as the history row's evidence_id.
+ */
+export declare function buildCorrectionFooter(oldContent: string, dateISO: string): string;
+export type ExplicitMarkKind = "corrects" | "supersedes";
+export interface ExplicitMarkInput {
+    kind: ExplicitMarkKind;
+    /** Raw id reference (8-char prefix or full UUID) as the client sent it. */
+    target: string;
+}
+export type ExplicitMarkCheck = {
+    ok: true;
+    targetId: string;
+} | {
+    ok: false;
+    httpStatus: number;
+    error: string;
+};
+/**
+ * Validate an explicit mark target BEFORE anything is written (AC1: on an
+ * unknown/ambiguous id the WHOLE request fails and nothing is stored).
+ * httpStatus is the REST code; the MCP tool reuses the message verbatim.
+ */
+export declare function checkExplicitMarkTarget(db: Database.Database, input: ExplicitMarkInput): ExplicitMarkCheck;
+/**
+ * Apply a validated explicit mark: link old → new + status on the old memory.
+ * Deterministic — no LLM. Link strength 1.0: an operator-declared mark, not a
+ * measured cosine. `corrects` → `corrected_by` + status `retracted`;
+ * `supersedes` → `superseded_by` + status `superseded` (AC1).
+ */
+export declare function applyExplicitMark(db: Database.Database, newMemoryId: string, input: ExplicitMarkInput): void;
+/**
+ * Drop a trigger's retrieval candidacy: status `absorbed`, vector row deleted,
+ * FTS row deleted (direct DELETE — the AFTER UPDATE trigger's `UPDATE … WHERE
+ * rowid` is a silent no-op on the missing row, so later column edits cannot
+ * resurrect it). Row + links are KEPT (evidence, session lineage, rollback).
+ * Must run inside a transaction. Tags/domain deliberately untouched (only the
+ * rewritten TARGET gets its tags cleared).
+ *
+ * #392: the implementation moved to storage.ts (`absorbMemory`) so the dedup
+ * merge core shares the ONE primitive without an import cycle; re-exported
+ * here under its historical name for the rewrite/rollback paths (nothing
+ * external imports it today, but it is the module's documented surface).
+ */
+export declare const absorbTrigger: (db: Database.Database, triggerId: string) => void;
+/**
+ * Replace a memory's vector (delete + insert) — the /update re-embed pattern.
+ * Must run inside a transaction (the caller pre-computes the embedding
+ * asynchronously, outside the sync transaction).
+ */
+export declare function replaceMemoryVector(db: Database.Database, memoryId: string, embedding: Float32Array): void;
+/**
+ * Reverse an absorb: status back to active (NULL), vector re-embedded from the
+ * (untouched) content, FTS row re-inserted explicitly (migration v10's rebuild
+ * pattern — the AFTER UPDATE trigger cannot recreate a deleted FTS row).
+ * Must run inside a transaction; no-op on a memory that is not currently
+ * absorbed (never resurrects an already-live row, never duplicates an FTS row).
+ */
+export declare function unabsorbTrigger(db: Database.Database, triggerId: string, embedding: Float32Array): void;
+export interface MemoryHistoryRow {
+    id: number;
+    memory_id: string;
+    old_content: string;
+    new_content: string;
+    prev_status: string | null;
+    new_status: string | null;
+    triggers_json: string | null;
+    evidence_id: string | null;
+    confidence: number | null;
+    cause: string;
+    created_at: string;
+}
+/** History rows for one memory, oldest first. */
+export declare function getMemoryHistory(db: Database.Database, memoryId: string): MemoryHistoryRow[];
+export declare function getHistoryRow(db: Database.Database, historyRowId: number): MemoryHistoryRow | null;
+export interface ResolutionBand {
+    /** Band label, e.g. "0.75-0.8" or ">=0.92". */
+    label: string;
+    /** Inclusive lower edge. */
+    lo: number;
+    /** Exclusive upper edge (Infinity for the deterministic >= band). */
+    hi: number;
+}
+/**
+ * Build the verdict-statistic bands from the LIVE floor/ceiling (#392): edges
+ * = sorted unique [floor, 0.80, 0.85, 0.90, ceiling]; bands are [e0,e1) …
+ * [e(n-1),en) plus the deterministic ">=en" band. Intermediate edges outside
+ * (floor, ceiling) are dropped — a band below the floor can never receive a
+ * verdict (candidates are >= floor), so a raised floor collapses the lower
+ * bands away instead of seeding dead labels. Labels use the numbers as
+ * configured ("0.75-0.8" … "0.9-0.92", ">=0.92").
+ */
+export declare function buildResolutionBands(floor: number, ceiling: number): ResolutionBand[];
+/**
+ * The band a pair's cosine falls into: the [lo, hi) band that contains it,
+ * falling through to the final >= band for cosines at/above the last edge.
+ * Null only for a cosine below the floor (never a candidate).
+ */
+export declare function bandForCosine(bands: ResolutionBand[], cosine: number): ResolutionBand | null;
+/**
+ * Nightly reconsolidation stage (#384, #392 — THE unified resolution stage).
+ *
+ * Phase 0 (#392): the deterministic merge zone (pairs >= the ceiling) runs
+ * first — LLM-free, budget-free, own lock/backup/cap.
+ *
+ * Scan: every memory with rowid > reconsolidationCursor (no shape filter;
+ * absorbed candidates are skipped — invisible memories are not re-judged).
+ * Each candidate's pairs: incoming explicit marks (verified once, AC7) then
+ * up-to-5 older KNN neighbors in [floor, ceiling) (verdict call per unlinked
+ * pair, AC2 — pairs at/above the ceiling are counted, never judged). Confirmed
+ * `corrects` pairs above the confidence gate on fact-shaped targets group by
+ * target into ONE rewrite call each (AC3); confirmed `merge` pairs queue for
+ * the merge phase; everything else is mark-only.
+ *
+ * Merge phase (#392): queued pairs merge through the dedup core under one
+ * lock/backup window, capped with the zone by dedupNightlyMaxMerges. A pair
+ * that cannot apply keeps both memories and holds the cursor.
+ *
+ * Cursor discipline mirrors stageSupersession: the cursor advances past a
+ * candidate once its neighbor set has been considered, regardless of infra
+ * skips — EXCEPT when rewrite groups or confirmed merges could not be applied
+ * (budget exhausted / rewrite-call infra error / merge cap or lock): the
+ * cursor then holds BELOW the earliest candidate contributing to the
+ * un-applied work, so those pairs are re-detected next run (dup-over-loss —
+ * an un-marked, un-rewritten, un-merged confirmed resolution must never be
+ * silently dropped by the cursor passing it).
+ *
+ * Dry-run: the zone's discovery + the free idempotency check only — zero LLM
+ * calls, zero writes, no cursor or band-stats persistence.
+ */
+export declare function stageReconsolidation(db: Database.Database, llm: LlmClient, budget: StageBudget, embedFn: EmbedFn, dryRun: boolean, stateDir: string | undefined, options?: ReconsolidationOptions): Promise<ReconsolidationStageResult>;
+export interface RollbackResult {
+    historyRowId: number;
+    memoryId: string;
+    restoredStatus: string | null;
+    unabsorbed: string[];
+    newHistoryRowId: number;
+}
+/**
+ * Roll back ONE rewrite history row: restore the recorded prior content and
+ * prior status via the same mechanics as the rewrite (re-embed, clear tags +
+ * domain NULL), reverse every absorb recorded in triggers_json (status
+ * restored, vector re-embedded, FTS row re-inserted), and write the rollback's
+ * own history row (cause `rollback`).
+ *
+ * Newest-first discipline: the row must be the NEWEST history entry for its
+ * memory (rolling back an older entry under a newer one would clobber — undo
+ * the newest first). The rollback row itself can be rolled back (undo the
+ * undo), which is what makes the chain navigable.
+ */
+export declare function rollbackHistoryRow(db: Database.Database, historyRowId: number, embedFn: EmbedFn): Promise<RollbackResult>;
+export interface HistoryCliOptions {
+    /** DB path override (tests / snapshot verification). Defaults to resolveDbPath(). */
+    dbPath?: string;
+    /** Memory id (8-char prefix or full UUID) whose history to list. */
+    memoryId?: string;
+    /** memory_history.id to roll back. */
+    rollbackId?: number;
+    /** Embed fn injection for tests; production lazy-loads the ONNX embedder. */
+    embedFn?: EmbedFn;
+}
+/**
+ * Runner for `hicortex history <id>` / `hicortex history --rollback <n>`.
+ * Returns a process exit code (0 success, 1 failure); throws only on
+ * unexpected infra errors (cli.ts prints those).
+ */
+export declare function runHistoryCommand(options: HistoryCliOptions): Promise<number>;