@avantf/dsh-mem 0.3.0 → 0.4.0

package/lib/engine/mem/db/dao/facts.d.ts

@@ -0,0 +1,472 @@
+/**
+ * `facts` — the memory store's main table.
+ *
+ * Started with the READ paths the detector, the diagnostics and the clock self-heal need;
+ * the write path (`persistFact`, archive/restore/feedback, vector repair) moves here next, so
+ * the store ends up holding business rules only and no SQL. See DESIGN §19.
+ */
+import type { Db } from '../port.js';
+/**
+ * Every `facts` column EXCEPT the two BLOBs (`hrr_vector` ~8 KB, `semantic_vector` ~2 KB per row).
+ *
+ * Multi-row reads that only need scalars used to be `SELECT *`, so a page of the admin list and
+ * every recall's trust settlement dragged the whole vector corpus through the driver — tens of
+ * megabytes per query at 33k facts, for columns the caller never looked at. The vector reads that DO
+ * want them keep their own explicit projections (`activeVectorRows`, `hrrRowsForFacts`).
+ *
+ * `getById` deliberately still selects everything: `restore` re-indexes the persisted vector it
+ * reads off that one row.
+ *
+ * `test/db_lifecycle.spec.ts` asserts this list against `PRAGMA table_info(facts)`, so a new column
+ * fails a test instead of silently vanishing from these two reads.
+ */
+export declare const FACT_COLUMNS_NO_BLOB = "fact_id, content, category, tags, trust_score, settle_clock,\n    pinned, pinned_at, bonus_count, bonus_window_at, last_reinforced_at, archived_clock,\n    retrieval_count, helpful_count, last_retrieved_at, embedding_model, vector_store, status,\n    supersedes_id, entities_version, conflict_checked, archived_at, archive_reason, ttl_days,\n    mirror_source, mirror_target, created_at, updated_at";
+/**
+ * The FTS leg's exact SQL, exported so the plan guard (`test/fts_plan.spec.ts`) and the bench
+ * control group EXPLAIN the production text itself instead of a copy that can silently drift.
+ *
+ * `NOT INDEXED` on the `facts` join is LOAD-BEARING, not decoration — this query is the one place
+ * where a healthy-looking covering index (`idx_facts_status_category (status, category)`) is the
+ * WRONG drive. Without planner statistics SQLite cannot know that `MATCH` is the selective access
+ * path, so it drives from `facts` and RE-RUNS the whole external-content MATCH once per row:
+ *
+ *   bad : SEARCH fa USING COVERING INDEX idx_facts_status_category (status=?)
+ *         | SCAN f VIRTUAL TABLE INDEX 0:=M1        <- the inner `=M1`
+ *   good: SCAN f VIRTUAL TABLE INDEX 0:M1
+ *         | SEARCH fa USING INTEGER PRIMARY KEY (rowid=?)
+ *
+ * Measured on the synthetic corpus at n=1000 (selective query, ~10 hits) in the fresh-session
+ * shape: 574 ms → 4.6 ms for the leg; the hint's `LIMIT 1` shape is the SAME statement, 568 ms
+ * → 1.9 ms.
+ *
+ * Why the missing statistics are not a startup-only blip: the open tick's `PRAGMA optimize` writes
+ * no stats for an EMPTY database, so on a fresh install the whole first session runs without them
+ * while the corpus grows in it; the next tick (≤60 min heartbeat) or a restart is what writes them.
+ * `bench-memory` used to hide this because it seeds, then REOPENS the runtime (whose open tick
+ * analyzes). Hence "ANALYZE facts at open when `sqlite_stat1` lacks a `facts` row and `facts` has
+ * rows" does NOT close the window either: at open the fresh database has zero rows (the guard is
+ * false), and once rows exist the next optimize is up to an hour away. `NOT INDEXED` pins the
+ * FTS-driven plan independently of `sqlite_stat1`, so there is no window at all. It cannot change
+ * results — only the join order — because the rowid join to `facts` is an INTEGER PRIMARY KEY
+ * lookup (still available under `NOT INDEXED`), and `status`/`category` stay residual filters on
+ * that one joined row, exactly as in the good plan above. Same spirit as §19 `page()`'s
+ * `INDEXED BY`, which pins the plan against `PRAGMA optimize` flipping it back.
+ */
+export declare const FTS_SEARCH_SQL = "SELECT f.rowid AS id, bm25(facts_fts) AS rank FROM facts_fts f\n         JOIN facts fa NOT INDEXED ON fa.fact_id = f.rowid\n         WHERE facts_fts MATCH ? AND fa.status = 'active' AND (? IS NULL OR fa.category = ?)\n         ORDER BY rank ASC\n         LIMIT ?";
+export declare class FactsDao {
+    private readonly db;
+    constructor(db: Db);
+    /**
+     * The subset of `ids` that is ACTIVE, batched.
+     *
+     * The catch-up sweep hands this the whole pending set, which grows with the corpus: one
+     * statement would exceed SQLite's bind-parameter cap (see `db/chunk.ts`).
+     */
+    activeIds(ids: readonly number[]): number[];
+    /** One row by id (the store's `getRow`), undefined when absent. */
+    getById(factId: number): Record<string, unknown> | undefined;
+    /** Lowest `settle_clock` in the store (trust diagnostics). */
+    minSettleClock(): number | null;
+    /** Vector-index health counters: total rows, rows with a vector, active rows without one. */
+    vectorCounts(): {
+        total: number;
+        withSemantic: number;
+        missing: number;
+    };
+    /** Highest `settle_clock` ever written, or null on an empty store (clock self-heal). */
+    maxSettleClock(): number | null;
+    countAll(): number;
+    countByStatus(): {
+        active: number;
+        archived: number;
+    };
+    /**
+     * Rows by id (trust settlement, hit projection); order is the caller's business.
+     *
+     * Scalars only — see {@link FACT_COLUMNS_NO_BLOB}. This runs on EVERY recall, over the whole hit
+     * set, to read trust and window fields.
+     */
+    rowsByIds(ids: readonly number[]): Record<string, unknown>[];
+    /** `fact_id → content` for a hit set (never N+1). */
+    textsByIds(ids: readonly number[]): Map<number, string>;
+    /** `fact_id → created_at/updated_at` for a hit set (the recall hit's two timestamps). */
+    timesByIds(ids: readonly number[]): Map<number, {
+        created_at: string;
+        updated_at: string | null;
+    }>;
+    /** Active rows that carry a persisted vector (index classification). */
+    activeVectorRows(): {
+        fact_id: number;
+        semantic_vector: Uint8Array;
+        embedding_model: string | null;
+    }[];
+    /**
+     * Facts per archive reason — the trust diagnostics breakdown. One grouped scan rather than
+     * a count per reason, because the reasons are few but the table is not.
+     */
+    archivedByReason(): {
+        reason: string;
+        n: number;
+    }[];
+    /** Distinct embedding models among active facts (vector diagnostics). */
+    embeddingModels(): {
+        model: string | null;
+        n: number;
+    }[];
+    /**
+     * Insert one revision. `INSERT OR IGNORE` is the duplicate-content guard (R1), so the
+     * caller must treat `changes === 0` as "content already exists" and fall back to the
+     * duplicate branch.
+     *
+     * `createdAt` is named EXPLICITLY rather than left to the column DEFAULT, because a
+     * superseding revision must INHERIT the archived row's `created_at` (the memory's first
+     * assertion date, distinct from when its text was rewritten). `updated_at` and
+     * `last_retrieved_at` are stamped `CURRENT_TIMESTAMP` in the same statement: a revision
+     * whose `created_at` is old must not be judged idle by the next tick, where "idle" reads
+     * `COALESCE(last_retrieved_at, created_at)`.
+     */
+    insertRevision(v: {
+        content: string;
+        category: string;
+        ttlDays: number;
+        supersedesId: number | null;
+        hrr: Uint8Array;
+        trust: number;
+        clock: number;
+        pinned: 0 | 1;
+        pinnedAt: string | null;
+        windowAt: string;
+        createdAt: string;
+    }): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+    findByContent(content: string): Record<string, unknown> | undefined;
+    /**
+     * ACTIVE facts whose entity/triple rows were produced by OLDER extraction rules.
+     *
+     * `entities_version < ?` (not `!= ?` or `IS NULL OR`) so `idx_facts_entities_version` serves it
+     * as a range seek; the column is `NOT NULL DEFAULT 0`, so no row can be invisible to it.
+     * Budgeted, because the first sweep after a rule change has the whole corpus to do.
+     *
+     * ORDER BY is the INDEX's own order (`entities_version, fact_id`), deliberately: ordering by
+     * `fact_id` alone cannot be served by an index whose first column is a RANGE, so the planner
+     * sorted every matching row in a temp b-tree before applying the LIMIT — i.e. the budget
+     * bounded what was rebuilt but not what was read. This order also drains the oldest vintage
+     * first, which is the more useful one when several rule changes are pending.
+     */
+    staleEntityRows(version: number, limit: number): {
+        fact_id: number;
+        content: string;
+    }[];
+    countStaleEntities(version: number): number;
+    /** Stamp the rules that produced a batch of rows' entity/triple data. */
+    setEntitiesVersion(ids: readonly number[], version: number): number;
+    /**
+     * Replace a fact's HRR vector.
+     *
+     * The bundle is derived from the ENTITY NAMES (`encodeHrrEntityVector`), so re-extraction has to
+     * rewrite it together with the entity rows — otherwise the probe leg would keep scoring a bundle
+     * built from names the fact no longer has.
+     */
+    setHrrVector(factId: number, bytes: Uint8Array): void;
+    /**
+     * ACTIVE facts still awaiting the EMBEDDING leg of the conflict check, in `fact_id` order.
+     *
+     * The durable replacement for the detector's in-process pending set: a fact written while the
+     * embedder was unavailable stays here across restarts instead of being lost (and instead of the
+     * set growing without bound).
+     *
+     * `semantic_vector IS NOT NULL` is a cheap pre-filter, NOT the completion test: the legs are
+     * scored from the live index, and a row can hold a vector the index cannot serve (another
+     * process's write, a blob this process's index dropped at rebuild). The store stamps only what a
+     * pass could actually complete, so such a row stays here until `vectors_fix` re-encodes it.
+     *
+     * `after` is what keeps that from becoming a stall. The drain takes rows ABOVE the last id it
+     * attempted, so a row it cannot complete is stepped over rather than pinned to the head with
+     * every row behind it: without this, either the drain re-selects the same un-completable rows
+     * forever (and never reaches the rest of the queue), or it has to stamp rows it never checked,
+     * which is the defect the completion test exists to prevent.
+     *
+     * The ORDER BY rides `idx_facts_conflict_pending` (both leading columns are equalities, so the
+     * index is already in `fact_id` order) — no temp b-tree, and no blob in the index.
+     */
+    pendingConflictRows(limit: number, after?: number): {
+        fact_id: number;
+        content: string;
+    }[];
+    /**
+     * Facts whose embedding-leg check has not run.
+     *
+     * Deliberately WITHOUT the `semantic_vector IS NOT NULL` filter that {@link pendingConflictRows}
+     * needs: the interesting number is "how far behind is the detector", and with the embedder down
+     * that is exactly the population with NO vector — those are waiting for the model (and for
+     * `vectors_fix`), so hiding them would report an empty queue while nothing had been checked.
+     */
+    countPendingConflicts(): number;
+    markConflictChecked(ids: readonly number[]): number;
+    /**
+     * Send facts BACK to the conflict queue (`conflict_checked = 0`), batched.
+     *
+     * Needed whenever a fact's derived inputs move, because the verdict is a statement about those
+     * inputs: the embedding leg's candidate set comes from `fact_entities`, and the structural leg
+     * reads `triples`. A rule change rewrites both (`reindexEntities`), so the old verdict was about
+     * a fact that no longer exists — and leaving the marker would keep it while `conflict_pending`
+     * reported zero behind. Same rule as {@link setSemanticVector}: what the check SAW changed.
+     */
+    requeueConflictCheck(ids: readonly number[]): number;
+    /** Revive an archived row (R18/R19: refresh the idle clock, clear the archive bookkeeping). */
+    revive(factId: number, category: string, ttlDays: number, trust: number, clock: number): number;
+    /** Land explicit category/TTL on a row that already exists (pure duplicate). */
+    applyValues(factId: number, category: string, ttlDays: number): void;
+    statusOf(factId: number): string | undefined;
+    /**
+     * Land a (re-)encoded vector, and RE-QUEUE the fact for the conflict check.
+     *
+     * `conflict_checked` answers "has the embedding leg run against the vector in this row?", so a
+     * new vector invalidates it: the scorer's second input is the vector, and a re-encode (a model
+     * swap, `vectors_fix`, a first encode) is a different question from the one that was answered.
+     * Without the reset the marker means "checked in whatever space this row happened to be in when
+     * the leg last ran" — and after a model swap the leg had never run in the new space at all,
+     * while `conflict_pending` reported zero. See DESIGN §20.16.
+     */
+    setSemanticVector(factId: number, vector: Uint8Array, model: string, store: string): void;
+    /** Archive with an explicit reason; returns how many rows moved. */
+    archive(factId: number, clock: number, reason: string): number;
+    /** The superseded revision leaves the active corpus (`replaced`). */
+    archiveSuperseded(factId: number, clock: number): number;
+    linkSupersede(factId: number, supersedesId: number): void;
+    /**
+     * Restore an archived fact, settling its trust and refreshing the idle clock (spec §2.6).
+     *
+     * `AND status = 'archived'` is load-bearing, like the guard on every sibling above: this UPDATE
+     * clears the archive bookkeeping and refreshes `last_retrieved_at`, so ungated it would take an
+     * ACTIVE row and (a) push its idle clock forward — silently extending the life of a fact the next
+     * tick was about to re-archive — and (b) reset `trust_score` to the settled value it computed. It
+     * returned `1` either way, so the caller could not tell that a row it never asked about had moved.
+     */
+    restore(factId: number, trust: number, clock: number): number;
+    bumpHelpful(factId: number, delta: number): void;
+    /** Feedback outcome: pin at the permanent threshold (trust snaps to 1). */
+    pinOutcome(factId: number, clock: number, bonusCount: number, windowAt: string): void;
+    /** Feedback outcome: the forget line was reached — archive in the same statement. */
+    forgetOutcome(factId: number, trust: number, clock: number, bonusCount: number, windowAt: string): void;
+    /** Feedback outcome: reinforced (or decayed) but still active. */
+    reinforceOutcome(factId: number, trust: number, clock: number, bonusCount: number, windowAt: string): void;
+    pin(factId: number, clock: number): number;
+    unpin(factId: number, clock: number): number;
+    /**
+     * One page, newest first (the `list` action).
+     *
+     * TWO shapes, deliberately, because they want different indexes and the shared
+     * `(? IS NULL OR category = ?)` form made the planner sort EVERY active row for the unfiltered
+     * one (measured 124 ms at 33k facts against 2.1 ms with an index that carries the order):
+     *
+     *  - unfiltered: pinned to `idx_facts_created(status, created_at DESC)`. `INDEXED BY` is
+     *    load-bearing, not decoration — the lifecycle tick runs `PRAGMA optimize`, and once
+     *    `sqlite_stat1` exists the planner can switch this query back to `SCAN facts` + a temp
+     *    b-tree (verified at 33k rows), silently undoing the fix at exactly the scale it matters.
+     *  - category-filtered: left to the planner, which seeks `idx_facts_status_category` and sorts
+     *    only that category's rows. Pinning the created-at index here would instead walk the whole
+     *    index in order and filter per row (measured 9.8 ms for a category with 17 rows at 33k),
+     *    i.e. it would trade a fast path for a slow one to save an index we do not need.
+     */
+    page(status: string, category: string | undefined, limit: number, offset: number): Record<string, unknown>[];
+    countInStatus(status: string, category?: string): number;
+    /** Every ACTIVE fact (the report's `active`). */
+    countActive(): number;
+    /** ACTIVE and permanent — pinned facts are exempt from decay (the report's `pinned`). */
+    countPinnedActive(): number;
+    /**
+     * ACTIVE facts whose decayed trust would reach zero within `withinDays` ACTIVE days —
+     * i.e. `trust_score - step × (clock - settle_clock) <= step × withinDays`.
+     */
+    countForgettingWithin(p: {
+        step: number;
+        clock: number;
+        withinDays: number;
+    }): number;
+    /** Facts with a still-live (calendar 24h) reinforcement window — the per-fact quota. */
+    /**
+     * The two "reinforcement quota" numbers of `trust_diagnose`, from ONE statement.
+     *
+     * They share a predicate and used to run it twice — twice the mission for two columns of the same
+     * rows. It is now also sargable (`bonus_window_at > datetime('now', '-1 day')`, a plain string
+     * comparison on the stored UTC-ISO format) and served by `idx_facts_bonus_window`, instead of
+     * calling `julianday` on every row of `facts` (measured 13.4–16.2 ms at 20k, per query).
+     */
+    bonusStatedToday(): {
+        count: number;
+        granted: number;
+    };
+    /** ACTIVE, unpinned facts unused for `days` CALENDAR days (the idle-archival fallback). */
+    countIdleCandidates(days: number): number;
+    /**
+     * Rows still due for ②③④ after a budgeted tick — what the NEXT pass will archive.
+     *
+     * One statement over the three predicates (they are alternatives, and the sets are disjoint:
+     * a row has either a TTL, a forgotten trust score, or an idle clock). Only called when a step
+     * actually filled its budget, so the common tick pays nothing for it.
+     */
+    countArchiveBacklog(p: {
+        forgetThreshold: number;
+        idleCalendarDays: number;
+    }): number;
+    /**
+     * Drop unusable (stale-dim) vectors so a re-encode can replace them — and re-queue the same
+     * rows, for the same reason {@link setSemanticVector} does: the vector the leg was checked
+     * against is gone, so the check has to run again once the replacement lands.
+     */
+    clearVectors(ids: readonly number[]): number;
+    /** Active facts with no persisted vector — what `vectors_fix` has to encode. */
+    missingVectorRows(): {
+        fact_id: number;
+        content: string;
+    }[];
+    /** Persisted HRR vectors of the active corpus (probe leg). */
+    /**
+     * Active HRR rows, NEWEST FIRST when capped.
+     *
+     * `LIMIT` without `ORDER BY` returns an arbitrary (implementation-defined) slice, which is the
+     * wrong way to bound a leg: the caller could not reason about what it had scored, and at 33k
+     * facts with a cap of 200 it silently made 32.8k of them unreachable. Recency is the honest
+     * prior for a memory store and `idx_facts_created(status, created_at DESC)` already serves it.
+     */
+    activeHrrRows(category?: string, limit?: number): {
+        fact_id: number;
+        hrr_vector: Uint8Array;
+    }[];
+    /**
+     * HRR vectors for a KNOWN candidate set (batched) — the probe leg's normal path.
+     *
+     * Reading every active row meant decoding one 8 KB blob per fact and running 1024 `cos` calls
+     * on each (measured 1.37 s for a probe at 33k facts). The candidates come from the entity leg,
+     * which is the same information the HRR bundle encodes (its atoms ARE the entity names), so the
+     * narrowing removes the O(N) part rather than a meaningful part of the ranking.
+     */
+    hrrRowsForFacts(ids: readonly number[], category?: string): {
+        fact_id: number;
+        hrr_vector: Uint8Array;
+    }[];
+    /** ACTIVE subset of `ids` in one category (`null` = any) — the semantic leg's filter. */
+    activeIdsIn(ids: readonly number[], category?: string): number[];
+    /** `retrieval_count` + the "last used" clock (spec §2.5), batched. */
+    touchUsage(ids: readonly number[]): void;
+    /** Recall bonus not granted: only the settled trust moved. */
+    settleTrust(factId: number, trust: number, clock: number): void;
+    /** Recall bonus granted: trust + the daily quota window. */
+    reinforce(factId: number, trust: number, clock: number, bonusCount: number, windowAt: string): void;
+    /**
+     * FTS5 leg over the external-content `facts_fts`.
+     *
+     * `bm25()` is negative (more negative = better), so the caller negates; a JOIN back to
+     * `facts` keeps archived rows and other categories out of the leg — and `NOT INDEXED` keeps
+     * that JOIN from becoming the drive (see {@link FTS_SEARCH_SQL}, which carries the plans and
+     * measurements).
+     */
+    ftsSearch(ftsQuery: string, category?: string, limit?: number): {
+        id: number;
+        rank: number;
+    }[];
+    /**
+     * ①'s predicate: the active-day counter crossed an integer boundary since the last settle.
+     * Kept next to its four siblings so the tick's ORDER and the SQL stay in one place.
+     *
+     * SARGABLE on purpose. It used to be `CAST(settle_clock AS INTEGER) < CAST(:clock AS INTEGER)`,
+     * and a function on the LEFT column forbids a range seek on
+     * `idx_facts_trust(status, pinned, settle_clock)` — so every tick read EVERY active unpinned row
+     * (measured 13.5 ms per statement at 180k, twice: settle + countPendingSettle).
+     *
+     * Equivalence for `settle_clock >= 0` (it is an active-day counter, and clocks only advance):
+     * with `c = CAST(:clock AS INTEGER)` an integer, `floor(x) < c` ⟺ `x < c` — if `x < c` then
+     * `floor(x) <= x < c`; if `x >= c` then `floor(x) >= c`. So dropping the left CAST changes no
+     * row, and `settle_clock < c` is a seek + range scan of exactly the pending rows.
+     */
+    private static readonly SETTLE_PREDICATE;
+    /** ① materialize decay, bounded to `budget` rows. */
+    settleBudgeted(p: {
+        step: number;
+        clock: number;
+        budget: number;
+    }): number;
+    /** ① materialize decay for every pending row (no budget). */
+    settleAll(p: {
+        step: number;
+        clock: number;
+    }): number;
+    /** Rows still awaiting ① (the budget ran out). */
+    countPendingSettle(p: {
+        clock: number;
+    }): number;
+    /**
+     * ② calendar TTL — explicit instruction, so `pinned` is NOT exempt.
+     *
+     * `budget` (0 = none) caps how many rows ONE tick may archive: the tick is a single IMMEDIATE
+     * transaction shared by several processes, so an unbudgeted pass over a large backlog held the
+     * write lock for as long as it took (measured 14400 rows in one tick). The remainder stays due
+     * and is reported as a deferred count, then archived by the next tick.
+     */
+    archiveExpiredByTtl(p: {
+        clock: number;
+        budget?: number;
+    }): number[];
+    /**
+     * ③ trust-driven forgetting (① already clamped trust to the threshold).
+     *
+     * Sargable as written (`status`/`pinned` equality + `trust_score <= ?`), and served by
+     * `idx_facts_forget(status, pinned, trust_score)`: before that index this statement read every
+     * active unpinned row per tick (measured 18.6–27.4 ms at 180k, with ZERO matches).
+     */
+    archiveForgotten(p: {
+        clock: number;
+        forgetThreshold: number;
+        budget?: number;
+    }): number[];
+    /**
+     * ④ calendar fallback: never touched for `idle_calendar_days`.
+     *
+     * The comparison is written as `<expression> < julianday('now', :modifier)` — the same
+     * expression `idx_facts_idle_cutoff` indexes — so it is a range seek. The old form
+     * (`julianday('now') - <expression> > :days`) called `julianday` on EVERY active row and could
+     * not use any index (measured 33–212 ms at 180k).
+     */
+    archiveIdle(p: {
+        clock: number;
+        idleCalendarDays: number;
+        budget?: number;
+    }): number[];
+    /**
+     * ⑤ physical delete of archived rows past the retention window.
+     *
+     * TWO statements in this order, sharing one predicate:
+     *
+     *   1. clear `supersedes_id` on the rows about to be deleted. The column self-references
+     *      `facts`, and an ACTIVE revision points at the archived revision it replaced, so the
+     *      DELETE below failed with `SQLITE_CONSTRAINT_FOREIGNKEY` whenever a revision chain
+     *      crossed `purge_after_archived_days`. Because the whole tick is ONE transaction and it
+     *      runs from the store's constructor, that failure did not merely skip the purge: it rolled
+     *      back settle/TTL/idle with it and left the process unable to start, permanently.
+     *   2. delete them.
+     *
+     * The predicate is built once and interpolated into both statements, so "which rows are
+     * purged" cannot drift between the unlink and the delete. Both run inside the caller's
+     * IMMEDIATE transaction (`runTrustTick`), so no reader observes the unlinked state.
+     */
+    purgeArchived(p: {
+        clock: number;
+        enabled: number;
+        purgeAfterDays: number;
+        skipPinned: boolean;
+        budget?: number;
+    }): number[];
+    /** The two mutually exclusive purge branches (see `purgeArchived` for why they are split). */
+    private static purgeBranches;
+    private static purgeParams;
+    /** Archived rows still due for ⑤ after a budgeted pass (0 when the pass finished them). */
+    countPurgeBacklog(p: {
+        clock: number;
+        enabled: number;
+        purgeAfterDays: number;
+        skipPinned: boolean;
+    }): number;
+}

package/lib/engine/mem/db/dao/stats.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `avantf_stats` — the key/value side table (currently the active-day clock and the last
+ * presence timestamp).
+ *
+ * Lives in `db/dao/` like every other aggregate: the SQL belongs to the DAO, while what the
+ * clock MEANS and when it advances stays in `lifecycle/presence.ts`.
+ */
+import type { Db } from '../port.js';
+export declare class StatsDao {
+    private readonly db;
+    constructor(db: Db);
+    read(key: string): string | null;
+    write(key: string, value: string): void;
+}

package/lib/engine/mem/db/dao/triples.d.ts

@@ -0,0 +1,80 @@
+/**
+ * `triples` — the SPO graph behind `ask` / `chain`, the structural contradiction signals and
+ * the supersede cleanup.
+ *
+ * The two structural lookups are exported as SQL builders so that the statement whose QUERY PLAN
+ * matters (they must seek a triples index and never scan) is the very one production runs, not a
+ * copy of it kept somewhere else.
+ */
+import type { Db } from '../port.js';
+interface TripleRow {
+    subj: string;
+    pred: string;
+    obj: string;
+    confidence: number;
+}
+/**
+ * Structural lookup ①: same (subj, obj), opposite polarity.
+ *
+ * JOIN, never `fact_id IN (SELECT fact_id FROM facts WHERE status='active')`: the IN-subquery
+ * makes SQLite materialize EVERY active fact id on each call, so the cost tracked the corpus
+ * instead of the match set — measured 202 ms with ZERO matches on a 300k-triple corpus, paid
+ * by every `remember`. The join keeps the plan on `idx_triples_subj` and checks the (indexed)
+ * status per candidate row: 0.18 ms, and it does not depend on planner statistics.
+ */
+export declare function polarityLookupSql(predCount: number): string;
+/** Structural lookup ②: same (subj, pred), different object. Same rewrite as above. */
+export declare function sameSubjPredLookupSql(): string;
+/** The optional `subj`/`pred`/`obj` slots an `ask` pattern may fill. */
+interface TriplePatternParts {
+    subj?: string;
+    pred?: string;
+    obj?: string;
+}
+export declare class TriplesDao {
+    private readonly db;
+    constructor(db: Db);
+    /** Idempotent insert for a fact's extracted triples. */
+    insertMany(factId: number, triples: readonly {
+        subj: string;
+        pred: string;
+        obj: string;
+        confidence: number;
+        source: string;
+    }[]): void;
+    /** The fact's triples, in insertion order (detail view). */
+    listForFact(factId: number): TripleRow[];
+    /** Minimal projection the contradiction detector reads. */
+    getByFact(factId: number): {
+        subj: string;
+        pred: string;
+        obj: string;
+    }[];
+    /** Drop a fact's triples — the superseded revision leaves the live graph. */
+    deleteForFact(factId: number): void;
+    findPolarityCounterparts(subj: string, obj: string, preds: readonly string[], excludeFactId: number): {
+        fact_id: number;
+    }[];
+    findSameSubjPredOtherObj(subj: string, pred: string, obj: string, excludeFactId: number): {
+        fact_id: number;
+    }[];
+    /**
+     * First hop of `chain`: the objects reachable from `subj` (optionally via one predicate).
+     *
+     * JOIN, not `fact_id IN (SELECT … WHERE status='active')` — the same shape {@link polarityLookupSql}
+     * documents as a measured 202 ms on a 300k-triple corpus with zero matches, because the subquery
+     * materializes EVERY active fact id per call. The chain path paid that on every hop.
+     */
+    objectsForSubject(subj: string, pred?: string): string[];
+    /**
+     * Second hop of `chain`: active facts whose subject is one of the mid names.
+     *
+     * JOIN for the same reason as {@link objectsForSubject}.
+     */
+    activeFactsBySubject(subjs: readonly string[], secondPred?: string): number[];
+    /** Active facts whose triple matches every given slot exactly (`ask`, exact layer). */
+    activeFactsMatchingExact(parts: TriplePatternParts): number[];
+    /** Same, with `=` relaxed to `LIKE %term%` (`ask`, recall-recovery layer). */
+    activeFactsMatchingLike(parts: TriplePatternParts): number[];
+}
+export {};

package/lib/engine/mem/db/hash.d.ts

@@ -0,0 +1,2 @@
+/** Stable content digest (sha1: change detection, not security). */
+export declare function contentHash(text: string): string;

package/lib/engine/mem/db/knowledge.d.ts

@@ -0,0 +1,17 @@
+import { type OpenedStore, type StoreSchema } from './store.js';
+/** Knowledge DB schema: documents under `domain → source`, split into chunks. */
+export declare const KNOWLEDGE_DDL: string[];
+/**
+ * The external-content FTS5 table, created separately so the tokenizer can be
+ * chosen at open time (same DESIGN §16 mitigation as the memory store).
+ */
+export declare function chunksFtsTableDdl(tokenizer: string): string;
+/**
+ * Ordered schema steps. Step 1 is the base schema and MUST stay idempotent: a database
+ * created before this mechanism existed reports `user_version = 0` while already holding it.
+ */
+export declare const KNOWLEDGE_SCHEMA: StoreSchema;
+/** Open (or create) the knowledge DB, bringing its schema up to the current version. */
+export declare function openKnowledgeDb(path: string): OpenedStore['db'];
+/** Open and report which migrations ran (tests, and any explicit upgrade path). */
+export declare function openKnowledgeStore(path: string): OpenedStore;

package/lib/engine/mem/db/migrations.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Versioned schema migrations — the "upgrade" half of the store lifecycle.
+ *
+ * The engine used to apply an idempotent `CREATE TABLE IF NOT EXISTS` blob on every open and
+ * call that "no migrations needed, a schema change ships by recreating the file". That
+ * stopped being true the first time a change had to fix data in place (the duplicate open
+ * contradiction rows that a partial unique index must not choke on), so the schema now has a
+ * version and ordered steps.
+ *
+ * Mechanics, deliberately boring:
+ *  - the version lives in SQLite's own `PRAGMA user_version` (no side table needed to order
+ *    steps), and every applied step is ALSO recorded in `schema_migrations` for audit;
+ *  - each step runs in its own transaction together with its `user_version` bump, so a
+ *    failure rolls the step back completely — a database is never "half upgraded";
+ *  - step 1 is the base schema and stays idempotent, because databases created before this
+ *    mechanism existed report `user_version = 0` while already holding the schema; adopting
+ *    them is a no-op that just stamps the version.
+ */
+import type { Db } from './port.js';
+import type { FtsTokenizer } from './tokenizer.js';
+/** What a migration may need from its store (the FTS tokenizer is chosen before the DDL). */
+interface MigrationContext {
+    readonly tokenizer: FtsTokenizer;
+}
+export interface Migration {
+    /** 1-based, contiguous, unique — see {@link validateMigrations}. */
+    readonly version: number;
+    readonly name: string;
+    /** Must be idempotent enough to run against a database from the pre-versioning era. */
+    readonly up: (db: Db, ctx: MigrationContext) => void;
+}
+export interface MigrationResult {
+    readonly from: number;
+    readonly to: number;
+    readonly applied: readonly number[];
+}
+/**
+ * `ALTER TABLE … ADD COLUMN`, skipped when the column is already there.
+ *
+ * SQLite has no `ADD COLUMN IF NOT EXISTS`, and every step must stay runnable against a
+ * database from the pre-versioning era (`user_version = 0` with the schema already present),
+ * so the check is explicit rather than implied by the version number. New columns should ALSO
+ * be added to the base DDL: a fresh database then gets them from step 1 and this becomes a
+ * no-op, while an existing one is upgraded here.
+ */
+export declare function addColumnIfMissing(db: Db, table: string, column: string, columnDdl: string): void;
+/** The schema version stored in the database header (0 = pre-versioning). */
+export declare function readUserVersion(db: Db): number;
+/**
+ * Steps must be 1..N with no gaps: a database at version k then always has a defined path
+ * forward, and a mistaken edit (duplicate or skipped number) fails at startup instead of
+ * silently leaving a store behind.
+ */
+export declare function validateMigrations(migrations: readonly Migration[]): void;
+/**
+ * The database was written by a NEWER build than the one opening it.
+ *
+ * Migrations are one-way (each step's `up` fixes data in place, and there is no `down`), so an
+ * older build cannot know what the extra steps did: running it against such a schema is undefined
+ * behaviour dressed up as a normal open — it may read columns that moved, or write rows the newer
+ * schema constrains differently. Refusing is the only honest answer, and the message has to say
+ * what to do, because this is what a plugin downgrade looks like in practice.
+ */
+export declare class SchemaDowngradeError extends Error {
+    readonly databaseVersion: number;
+    readonly codeVersion: number;
+    constructor(databaseVersion: number, codeVersion: number);
+}
+/** Apply every migration newer than the stored version. Returns what ran. */
+export declare function migrate(db: Db, migrations: readonly Migration[], ctx: MigrationContext): MigrationResult;
+export {};