@avantf/dsh-mem 0.6.4 → 0.8.0

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

@@ -6,8 +6,48 @@
  * would exceed SQLite's bind-parameter cap and, on the write path, silently disable
  * contradiction detection (see `db/chunk.ts`).
  */
+import type { MemoryKind } from '../../../mem-contract/index.js';
 import type { Db } from '../port.js';
 import type { ExtractedEntity } from '../../entities/extract.js';
+import type { TimeSql } from '../../store/time_filter.js';
+import { type SurfaceMatch } from '../../store/relation_planner.js';
+import type { FactContainingPage, FactsContainingAllQuery } from '../../interfaces/repositories.js';
+/**
+ * The two vocabulary scans behind {@link EntitiesDao.factEntitiesIn}, as constants because the
+ * benchmark (`scripts/bench-facts.mjs`) EXPLAINs them: their `EXISTS` subquery is DRIVEN BY THE
+ * PLANNER'S STATISTICS, so a timing without the plan that produced it is not comparable. With no
+ * `sqlite_stat1` SQLite drives the EXISTS from `facts` by `status` (every ACTIVE fact visited once
+ * per matched name); with full statistics it seeks `idx_fact_entities_entity` instead. The same
+ * arrangement as `facts.ts#FTS_SEARCH_SQL`, and for the same reason: the measured SQL must be the
+ * text production runs, not a copy that can drift.
+ */
+export declare const FACT_ENTITIES_IN_SQL = "SELECT n.name AS name\n           FROM entities n\n          WHERE instr(?, n.name) > 0\n            AND EXISTS (\n                  SELECT 1\n                    FROM fact_entities fe\n                    JOIN facts fa ON fa.fact_id = fe.fact_id\n                   WHERE fe.entity_id = n.entity_id AND fa.status = 'active'\n                )";
+/** The alias half of {@link FACT_ENTITIES_IN_SQL} (aliases first, see `factEntitiesIn`). */
+export declare const FACT_ENTITY_ALIASES_IN_SQL = "SELECT a.alias AS alias, n.name AS name\n           FROM entity_aliases a\n           JOIN entities n ON n.entity_id = a.entity_id\n          WHERE instr(?, a.alias) > 0\n            AND EXISTS (\n                  SELECT 1\n                    FROM fact_entities fe\n                    JOIN facts fa ON fa.fact_id = fe.fact_id\n                   WHERE fe.entity_id = a.entity_id AND fa.status = 'active'\n                )";
+/** One statement plus its positional binds, exactly as production runs it. */
+export interface FactAndStatement {
+    sql: string;
+    params: unknown[];
+}
+/**
+ * The two statements one fact-level AND page runs — the `total` count and the page itself — as text
+ * plus binds, built from the RESOLVED ids.
+ *
+ * A function (not a constant like {@link FACT_ENTITIES_IN_SQL}) because the placeholder count, the
+ * time clause and limit/offset are per-call, and EXPORTED for the same reason as that constant: the
+ * benchmark (`scripts/bench-facts.mjs`) EXPLAINs the statements production runs, so the recorded plan
+ * cannot drift from the timed query. The AND page's plan is statistics-dependent too — a timing
+ * without the plan that produced it is not comparable.
+ *
+ * Bind order is the text's order: entity ids, kind ×2, source ×2, time params, the AND cardinality,
+ * then (page only) limit/offset.
+ */
+export declare function factsContainingAllStatements(db: Db, query: Omit<FactsContainingAllQuery, 'time'> & {
+    time?: TimeSql;
+}): {
+    total: FactAndStatement;
+    page: FactAndStatement;
+} | null;
 export declare class EntitiesDao {
     private readonly db;
     constructor(db: Db);
@@ -61,11 +101,6 @@ export declare class EntitiesDao {
      * whole corpus. The hint makes the plan independent of ANALYZE timing.
      */
     candidateFacts(factId: number, minShared: number, maxEntities: number): number[];
-    /** Active facts linked to `name`, optionally limited to one category (`related` leg). */
-    activeFactsForEntity(name: string, category?: string): number[];
-    /** Active facts linked to ALL of `names` (AND-join, `reason` leg). */
-    activeFactsForAllEntities(names: readonly string[]): number[];
-    /** Active facts sharing ANY of `names`, in one category (the entity leg). */
     /**
      * Candidate facts for an entity query, ordered by the leg's score and CAPPED.
      *
@@ -82,10 +117,48 @@ export declare class EntitiesDao {
      * deterministic tie-break among equal ratios. The caller still recomputes the score in JS for the
      * survivors, so one formula stays in charge.
      */
-    candidateFactsForAnyEntity(names: readonly string[], category: string | undefined, limit: number, queryWidth: number, widthCap: number, 
+    candidateFactsForAnyEntity(names: readonly string[], kind: MemoryKind | undefined, limit: number, queryWidth: number, widthCap: number, 
     /**
      * P-08 provenance filter (`fact_sources.ref`). `EXISTS`, never a JOIN: a fact with several
      * sources would fan out into several rows and eat the leg's `LIMIT`, silently shrinking recall.
      */
-    source?: string): number[];
+    source?: string, 
+    /**
+     * The explicit `mem_recall.time` predicate (see `store/time_filter.ts`). It is part of the
+     * statement rather than a post-fusion filter for the same reason as P-08's `source`: the leg's
+     * `LIMIT` must apply WITHIN the window, or window-external facts eat the cap and the in-window
+     * ones never reach fusion.
+     */
+    time?: TimeSql): number[];
+    /**
+     * The FACT-level entity vocabulary for the query text (docs/GRAPH_RECALL_AND_SEMANTICS.md §7.9).
+     *
+     * Canonical names and registered aliases are BOTH reported (alias-first is what `resolveNode` and
+     * `relations/normalize.ts` do, so an alias and its canonical form are one entity to the planner),
+     * and both are narrowed to entities linked to at least one ACTIVE fact. A name whose facts are all
+     * archived is not part of the live corpus: reporting it would form a plan that can only come back
+     * empty, which is the fuzzy fallback with extra work.
+     *
+     * NOT the graph reader's `entitiesIn`: that one requires an `edges` row, so a journal entry (which
+     * never has one) or a note whose extraction produced no relation would be invisible here — exactly
+     * the facts a fact-level AND must cover. The `kind`/`source`/`time` filters are deliberately not
+     * applied (the caller's page applies them, and an empty page falls back to fuzzy).
+     */
+    factEntitiesIn(text: string): SurfaceMatch[];
+    /**
+     * One fact-level AND page (docs/GRAPH_RECALL_AND_SEMANTICS.md §7.9): ACTIVE facts that mention
+     * EVERY requested entity.
+     *
+     * The entity names are resolved to ids alias-first (`resolveNode`'s order), deduplicated, and an
+     * UNKNOWN name ends the query with an empty page: "all of these entities appear" cannot hold when
+     * one of them does not exist. The grouping is the AND itself — `COUNT(DISTINCT fe.entity_id)`
+     * equals the number of distinct entities — so a fact carrying some of them is not a candidate,
+     * unlike the entity leg's `minSupport`.
+     *
+     * `ORDER BY fact_id DESC` is the exact page's own convention (newest row first), and
+     * `total`/`offset`/`limit` are the FACT-level page, not an edge page.
+     */
+    factsContainingAll(query: Omit<FactsContainingAllQuery, 'time'> & {
+        time?: TimeSql;
+    }): FactContainingPage;
 }

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

@@ -1,14 +1,3 @@
-/**
- * `fact_sources` — where a memory fact came from (P-08).
- *
- * One row per `(fact_id, kind, ref)`. `kind` is a closed vocabulary (`session` / `kb_doc` /
- * `tool` / `manual`) so a reader can trust what a reference IS; `ref` is opaque to this layer
- * (a session id, a document id, a tool name, or a free-form note).
- *
- * The SQL lives here like every other aggregate. The store decides WHICH source a write carries
- * (and refuses to invent one when the caller gave none); the DAO only records and reads rows.
- */
-import type { FactSourceView } from '../../../mem-contract/index.js';
 import type { Db } from '../port.js';
 /**
  * The kind axis is the CONTRACT's, not a second list: `FactSourceView['kind']` is what `admin detail`
@@ -16,7 +5,8 @@ import type { Db } from '../port.js';
  * vocabulary" one thing. (Before, the array here and the union in `types.ts` were two independent
  * spellings that happened to agree.)
  */
-export type FactSourceKind = FactSourceView['kind'];
+export type { FactSourceKind } from '../../interfaces/repositories.js';
+import type { FactSourceKind } from '../../interfaces/repositories.js';
 /**
  * The closed `kind` vocabulary, spelled once so the store and the tests share it.
  *
@@ -42,7 +32,7 @@ export interface FactSource {
  * `kind:` prefix — `session:…` / `kb_doc:…` / `tool:…` — and anything else, INCLUDING the fallback
  * kind's own name, is `manual` with the reference kept VERBATIM. No shape guessing: a bare
  * `domain:source:title` becomes a `manual` source whose ref is exactly what the caller wrote, which
- * is strictly more honest than inventing a category from how the string looks.
+ * is strictly more honest than inventing a provenance kind from how the string looks.
  *
  * The prefix table comes from {@link FACT_SOURCE_KINDS} (see {@link FACT_SOURCE_PREFIX_KINDS}) rather
  * than from a hand-written alternation, which is what keeps the recognized set and the recorded set

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

@@ -6,6 +6,8 @@
  * the store ends up holding business rules only and no SQL. See DESIGN §19.
  */
 import type { Db } from '../port.js';
+import { type TimeRange, type TimeSql } from '../../store/time_filter.js';
+import type { MemoryKind } from '../../../mem-contract/index.js';
 /**
  * Every `facts` column EXCEPT the two BLOBs (`hrr_vector` ~8 KB, `semantic_vector` ~2 KB per row)
  * and the two DEPRECATED provenance columns (`mirror_source` / `mirror_target`, see below).
@@ -26,39 +28,8 @@ import type { Db } from '../port.js';
  * `test/db_lifecycle.spec.ts` asserts this list against `PRAGMA table_info(facts)` MINUS those
  * two deprecations, so a new column fails a test instead of silently vanishing from these 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    valid_from, valid_to, assert_count, 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 const FACT_COLUMNS_NO_BLOB = "fact_id, content, kind, title, 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    valid_from, valid_to, valid_from_ms, valid_to_ms, assert_count, created_at, updated_at";
+export declare const FTS_SEARCH_SQL: string;
 /**
  * {@link FTS_SEARCH_SQL} with the P-08 source predicate, as a SEPARATE statement rather than one
  * more `(? IS NULL OR …)` branch in the shared text.
@@ -73,7 +44,106 @@ export declare const FTS_SEARCH_SQL = "SELECT f.rowid AS id, bm25(facts_fts) AS
  * rows, and this leg is `ORDER BY bm25 … LIMIT cap` — the duplicates would eat cap slots and shrink
  * recall behind the caller's back.
  */
-export declare const FTS_SEARCH_SQL_FILTERED = "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           AND (? IS NULL OR EXISTS (\n                 SELECT 1 FROM fact_sources fs WHERE fs.fact_id = fa.fact_id AND fs.ref = ?\n               ))\n         ORDER BY rank ASC\n         LIMIT ?";
+export declare const FTS_SEARCH_SQL_FILTERED: string;
+/**
+ * One row of a TITLE search (`mem_recall.titles`), as the DAO returns it.
+ *
+ * `title` is non-null here by construction (`title IS NOT NULL`); the store maps the row onto the
+ * contract's `TitleCandidate`, which is where `kind` is renamed to `memory_kind` and `valid_from` to
+ * `event_date`. `excerpt` is the content's first 200 characters, computed in SQL so a candidate page
+ * never drags whole documents through the driver.
+ *
+ * `matched_title` is the title text the query actually matched — the CURRENT title, or one of the
+ * aliases a corrected transaction used to carry (v17). It equals `title` unless the row was found
+ * through an old handle, which is exactly what the caller needs to know before it decides "same
+ * transaction or not".
+ */
+export interface TitleRow {
+    fact_id: number;
+    title: string;
+    matched_title: string;
+    kind: string;
+    status: string;
+    created_at: string | null;
+    updated_at: string | null;
+    valid_from: string | null;
+    excerpt: string | null;
+}
+/**
+ * The filters BOTH title statements apply — one shape, so the FTS path and the LIKE fallback cannot
+ * drift into two meanings of `status`/`kind`/`time`.
+ *
+ * `status: 'all'` is the one value that adds no predicate (it is what `titles`'s documented
+ * "include the old revisions" means); `kind` undefined means no layer restriction — the STORE applies
+ * the action's `journal` default, because that is a product decision, not a SQL one.
+ */
+export interface TitleFilters {
+    kind?: MemoryKind;
+    status: 'active' | 'archived' | 'all';
+    time?: TimeSql;
+}
+export interface TitleQuery extends TitleFilters {
+    /** The normalized query, used for the exact/prefix comparison. */
+    query: string;
+    /** The query's keywords, used by `matched_terms` and by the LIKE fallback. */
+    terms: readonly string[];
+    limit: number;
+}
+/** The exact-title filter: the same `kind`/`status`/`time` axis, one literal query. */
+export interface ExactTitleQuery extends TitleFilters {
+    query: string;
+}
+/** The exact-content filter (docs/RECALL_INTERFACE.md §2.2): one literal substring, active rows only. */
+export interface ExactContentQuery {
+    /** The normalized literal a fact's content must CONTAIN. */
+    query: string;
+    kind?: MemoryKind;
+    source?: string;
+    time?: TimeSql;
+}
+/**
+ * One SQL text WITH its bind values — the ONLY way the title statements leave this module.
+ *
+ * The caller used to bind `rank.params`, the MATCH expression, the filter values and the LIMIT by
+ * hand, which meant the parameter order was a comment instead of a fact (REVIEW-2026-10-24 P2). The
+ * builders below assemble the values in the order the `?` placeholders appear in the text they
+ * produce, so a statement and its params cannot come from two different shapes.
+ */
+export interface TitleStatement {
+    readonly sql: string;
+    readonly params: (string | number | null)[];
+}
+/** The status/kind/time predicate text plus its bind values, built by {@link titleFilter}. */
+export interface TitleFilterSql {
+    readonly sql: string;
+    readonly params: (string | number | null)[];
+}
+/** What the fuzzy title statements need from their caller (everything but the SQL itself). */
+export interface TitleFuzzyInput {
+    /** The normalized query (the `=`/prefix comparison). */
+    readonly query: string;
+    /** The query's keywords (the LIKE predicate and `matched_terms`). */
+    readonly terms: readonly string[];
+    /** The status/kind/time predicate, over the `fa.` alias both statements use for `facts`. */
+    readonly filter: TitleFilterSql;
+    readonly limit: number;
+}
+/** {@link TitleFuzzyInput} plus the FTS5 MATCH expression from `store/titles.ts#titleFtsQuery`. */
+export interface TitleFtsSearchInput extends TitleFuzzyInput {
+    readonly fts: string;
+}
+/**
+ * The FTS title statement, exported so the plan guard (`test/journal_title.spec.ts`) EXPLAINs the
+ * production text (and binds the production params) instead of a copy — the same arrangement
+ * {@link FTS_SEARCH_SQL} uses.
+ */
+export declare function titleFtsSearchSql(input: TitleFtsSearchInput): TitleStatement;
+/**
+ * The short-query fallback: a `title LIKE` scan instead of the FTS index, plus the same alias
+ * source — a corrected chain's 1–2 character old handle has to stay findable too, and the trigram
+ * table cannot express a run that short.
+ */
+export declare function titleLikeSearchSql(input: TitleFuzzyInput): TitleStatement;
 export declare class FactsDao {
     private readonly db;
     constructor(db: Db);
@@ -110,12 +180,19 @@ export declare class FactsDao {
     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/validity` for a hit set (the recall hit's timestamps). */
-    timesByIds(ids: readonly number[]): Map<number, {
+    /**
+     * `fact_id →` the scalar fields a `RecallHit` renders (timestamps, validity, title) for a hit set.
+     *
+     * Renamed from `timesByIds` when `title` joined the projection: the read is the hit's META, not
+     * only its clocks. One statement for the whole hit set — never N+1 — and the title arrives here
+     * rather than in a second query because it is on the same row.
+     */
+    hitMetaByIds(ids: readonly number[]): Map<number, {
         created_at: string;
         updated_at: string | null;
         valid_from: string | null;
         valid_to: string | null;
+        title: string | null;
     }>;
     /** Active rows that carry a persisted vector (index classification). */
     activeVectorRows(): {
@@ -162,7 +239,7 @@ export declare class FactsDao {
      */
     insertRevision(v: {
         content: string;
-        category: string;
+        kind: MemoryKind;
         ttlDays: number;
         supersedesId: number | null;
         hrr: Uint8Array;
@@ -172,6 +249,12 @@ export declare class FactsDao {
         pinnedAt: string | null;
         windowAt: string;
         createdAt: string;
+        /**
+         * The journal title of this revision (JOURNAL_TITLE_SEARCH §2.2). `null` = none (a note, a
+         * legacy journal, a CLI/import write) — and that is why the column is nullable. The FTS index
+         * follows through the `facts_title_ai` trigger; this statement never touches it by hand.
+         */
+        title?: string | null;
         /**
          * P-13: the caller's event time / known end, written straight onto the new row. `null` means
          * "unknown" and is what an omitted argument leaves (the column has no default on purpose).
@@ -180,6 +263,15 @@ export declare class FactsDao {
          */
         validFrom?: string | null;
         validTo?: string | null;
+        /**
+         * The INSTANTS the two text bounds name (`valid_from_ms`/`valid_to_ms`).
+         *
+         * Written in the same statement as the text, never computed later: the text is what a reader
+         * displays and the epoch is what an `event` window compares, so writing them apart would let the
+         * two describe different times. `null` = "no event time" (the axis then excludes the row, D5).
+         */
+        validFromMs?: number | null;
+        validToMs?: number | null;
     }): {
         changes: number;
         lastInsertRowid: number | bigint;
@@ -187,9 +279,15 @@ export declare class FactsDao {
     /**
      * P-10: land an explicitly given validity on a row that already exists (a duplicate `add` whose
      * caller named `event_date` / `valid_until`). Omitted arguments keep what the row has, exactly
-     * like `category`/`ttl_days` (see `add`'s doc).
+     * like `kind`/`ttl_days` (see `add`'s doc).
      */
-    applyValidity(factId: number, validFrom: string | undefined, validTo: string | undefined): void;
+    applyValidity(factId: number, validFrom: {
+        text: string;
+        ms: number;
+    } | undefined, validTo: {
+        text: string;
+        ms: number;
+    } | undefined): void;
     /** P-10: the row's assertion counter (`1` when the column is somehow NULL on a legacy row). */
     assertCount(factId: number): number;
     /**
@@ -206,7 +304,7 @@ export declare class FactsDao {
      * contradiction verdict). `COALESCE` keeps an end the caller already declared (`valid_until`):
      * overwriting it with the archival instant would replace a real answer with an administrative one.
      */
-    markValidTo(factId: number, at: string): void;
+    markValidTo(factId: number, at: string, atMs?: number | null): void;
     /**
      * P-07: "who superseded this fact", derived from the existing `supersedes_id` link — no
      * redundant column. `MIN` is deterministic when several revisions named the same predecessor
@@ -240,7 +338,7 @@ export declare class FactsDao {
      * `EXISTS`, never a JOIN on `fact_sources` (the {@link FTS_SEARCH_SQL_FILTERED} rule): the cap is
      * `LIMIT`, and a multi-source fact would eat cap slots with duplicate rows.
      */
-    windowRows(fromDate: string, toDate: string, category: string | undefined, cap: number, source?: string): number[];
+    windowRows(fromDate: string, toDate: string, kind: MemoryKind | undefined, cap: number, source?: string): number[];
     findByContent(content: string): Record<string, unknown> | undefined;
     /**
      * ACTIVE facts whose entity/triple rows were produced by OLDER extraction rules.
@@ -254,10 +352,15 @@ export declare class FactsDao {
      * 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.
+     *
+     * `kind` rides along because the sweep's edge write depends on it (STRUCTURED_RELATIONS §四: a
+     * journal gets no graph edges). Reading it here costs nothing — the row is already being decoded,
+     * and a per-fact lookup would be one more query per sweep item.
      */
     staleEntityRows(version: number, limit: number): {
         fact_id: number;
         content: string;
+        kind: string;
     }[];
     countStaleEntities(version: number): number;
     /** Stamp the rules that produced a batch of rows' entity/triple data. */
@@ -316,9 +419,47 @@ export declare class FactsDao {
      */
     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;
+    revive(factId: number, kind: MemoryKind, ttlDays: number, trust: number, clock: number): number;
+    /** Land explicit kind/TTL on a row that already exists (pure duplicate). */
+    applyValues(factId: number, kind: MemoryKind, ttlDays: number): void;
+    /**
+     * Land a title on a row that already exists — the ONE write behind every "backfill" path
+     * (JOURNAL_TITLE_SEARCH §11.2/§11.3): a duplicate `add` that names a title for an existing
+     * untitled row, and an update that merges into another row whose title is NULL.
+     *
+     * It MUST be an `UPDATE`, not a second `INSERT OR IGNORE`: the insert trigger only fires for a row
+     * that is actually inserted, so a backfill written that way would leave `facts_title_fts` holding
+     * the old (empty) title forever. `AFTER UPDATE OF title` is what moves the index here.
+     */
+    setTitle(factId: number, title: string): void;
+    /**
+     * Record `title` as a handle `factId` USED to carry (v17, the controlled `retitle: true`).
+     *
+     * `INSERT OR IGNORE` because the alias is derived search state, not a log: a correction that lands
+     * on the same old handle twice (retitle A→B, retitle B→A, retitle A→B) must not fail on the
+     * `(fact_id, title)` primary key. The row belongs to the revision that NOW carries the title, which
+     * is what makes the old search find the ACTIVE revision rather than an archived predecessor.
+     */
+    insertTitleAlias(factId: number, title: string): void;
+    /**
+     * Drop an alias row that has become the fact's CURRENT title (v17).
+     *
+     * Reached by a correction that goes BACK to an earlier handle (A → B, then B → A): the alias table
+     * exists to hold handles the row does not carry any more, and a row repeating the current title
+     * would be a second source of truth for the same string. `INSERT OR IGNORE` alone cannot express
+     * that (it adds, never removes), hence the explicit delete.
+     */
+    dropTitleAlias(factId: number, title: string): void;
+    /**
+     * Carry a revision's aliases onto the revision that replaces it (v17).
+     *
+     * Aliases are chain-level knowledge — "this transaction was once called X" — stored per revision
+     * because that is the row a search joins. Without this copy, the second update after a correction
+     * would move the title onto a new row and strand every alias on the archived predecessor, so the
+     * old handle would stop finding the live transaction. `currentTitle` is excluded so the table never
+     * holds a row that merely repeats the current handle.
+     */
+    copyTitleAliases(fromFactId: number, toFactId: number, currentTitle: string): void;
     statusOf(factId: number): string | undefined;
     /**
      * Land a (re-)encoded vector, and RE-QUEUE the fact for the conflict check.
@@ -359,20 +500,35 @@ export declare class FactsDao {
      * 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
+     * `(? IS NULL OR kind = ?)` 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),
+     *  - kind-filtered: left to the planner, which seeks `idx_facts_status_kind` and sorts
+     *    only that kind'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 kind 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, source?: string): Record<string, unknown>[];
-    countInStatus(status: string, category?: string, source?: string): number;
+    page(status: string, kind: MemoryKind | undefined, limit: number, offset: number, source?: string): Record<string, unknown>[];
+    /**
+     * Run one of `page()`'s INDEXED BY-pinned statements, degrading to the unpinned form when the
+     * pinned index is missing.
+     *
+     * The `INDEXED BY` pins the PLAN, not the RESULT: without the hint the same rows come back, the
+     * planner just chooses for itself. `idx_facts_created` comes from migration 4 / the base DDL, and
+     * both create it idempotently — but a database whose migration was interrupted (or whose index was
+     * dropped out of band) at an already-current `user_version` has no pending step left to recreate
+     * it, and without this fallback the WHOLE list path errors out on "no such index". Degrading is
+     * preferred over an open-time self-check/rebuild: the migrations are the open path's only repair
+     * mechanism (each step idempotent), a missing index hurts exactly ONE query's plan choice, and
+     * rebuilding is a DDL write the open path should not take on for it. Only the "no such index"
+     * failure degrades — every other error still propagates.
+     */
+    private pageByCreatedIndex;
+    countInStatus(status: string, kind?: MemoryKind, source?: string): number;
     /** Every ACTIVE fact (the report's `active`). */
     countActive(): number;
     /** ACTIVE and permanent — pinned facts are exempt from decay (the report's `pinned`). */
@@ -432,7 +588,7 @@ export declare class FactsDao {
      * 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, source?: string): {
+    activeHrrRows(kind?: MemoryKind, limit?: number, source?: string, time?: TimeSql): {
         fact_id: number;
         hrr_vector: Uint8Array;
     }[];
@@ -444,12 +600,12 @@ export declare class FactsDao {
      * 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, source?: string): {
+    hrrRowsForFacts(ids: readonly number[], kind?: MemoryKind, source?: string): {
         fact_id: number;
         hrr_vector: Uint8Array;
     }[];
-    /** ACTIVE subset of `ids` in one category/source (`null` = any) — the semantic leg's filter. */
-    activeIdsIn(ids: readonly number[], category?: string, source?: string): number[];
+    /** ACTIVE subset of `ids` in one kind/source (`null` = any) — the semantic leg's filter. */
+    activeIdsIn(ids: readonly number[], kind?: MemoryKind, source?: string, time?: TimeSql): 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. */
@@ -464,7 +620,7 @@ export declare class FactsDao {
      * that JOIN from becoming the drive (see {@link FTS_SEARCH_SQL}, which carries the plans and
      * measurements).
      */
-    ftsSearch(ftsQuery: string, category?: string, limit?: number, source?: string): {
+    ftsSearch(ftsQuery: string, kind?: MemoryKind, limit?: number, source?: string, time?: TimeSql): {
         id: number;
         rank: number;
     }[];
@@ -479,10 +635,109 @@ export declare class FactsDao {
      * single-term query (all ranks 1) has a deterministic order. `ORDER BY rank` must read the SELECT
      * alias, so the LIKE expressions are built once and bound twice — same fragment, same order.
      */
-    ftsSubstringSearch(terms: readonly string[], category?: string, limit?: number, source?: string): {
+    ftsSubstringSearch(terms: readonly string[], kind?: MemoryKind, limit?: number, source?: string, time?: TimeSql): {
         id: number;
         rank: number;
     }[];
+    /**
+     * One statement's worth of candidates, from the TITLE FTS index (JOURNAL_TITLE_SEARCH §11.4).
+     *
+     * The FTS table only PRODUCES candidates: `bm25` is the last, tie-breaking key, and the three keys
+     * above it are computed on `facts.title` itself (exact match, prefix, how many of the query's
+     * keywords the title contains). That split is the design's whole point — a title's bm25 score is
+     * not a content-relevance score, and the ordering the caller acts on ("is this the same
+     * transaction?") is about the title text, not about a corpus-wide term weight.
+     *
+     * `NOT INDEXED` on the `facts` join is the same load-bearing hint as {@link FTS_SEARCH_SQL}: without
+     * statistics the planner can drive from `facts` and re-run the external-content MATCH per row.
+     * `fa.title IS NOT NULL` keeps the empty-string rows FTS5 indexes for NULL out of the answer.
+     *
+     * Since v17 the same statement also consults `title_aliases` (see {@link titleAliasSource}): a
+     * corrected transaction must not become unfindable by the handle it used to carry, so the candidate
+     * set is the union of "the current title matches" and "an alias matches", deduped with the current
+     * title winning, and `matched_title` says which text the query actually hit.
+     */
+    searchTitleRowsByFts(q: TitleQuery & {
+        fts: string;
+    }): TitleRow[];
+    /**
+     * The SHORT-QUERY fallback: a `title LIKE` scan over the same filters and the same ordering.
+     *
+     * Reached when the FTS table's tokenizer cannot express the query (a 1–2 character CJK run, a
+     * 1–2 character latin word, or a unicode61 table — see `store/titles.ts`). The predicate matches
+     * ANY keyword (not the whole query contiguously), exactly like the content leg's substring
+     * fallback; `matched_terms` is what ranks a row containing all keywords above one containing a
+     * single one. The alias source rides along for the same reason it does in the FTS statement.
+     */
+    searchTitleRowsByLike(q: TitleQuery): TitleRow[];
+    /**
+     * The WHERE body of the content-exact statements: active facts whose content CONTAINS the query.
+     *
+     * `lower()` is SQLite's — ASCII-only case folding. Latin queries are therefore case-insensitive
+     * (`DSH` finds `dsh`) while CJK is compared as-is, which is exactly the rule; a non-ASCII accented
+     * letter stays case-sensitive, and that is stated in the spec's "拉丁部分大小写不敏感".
+     */
+    /**
+     * How many active facts contain `q.query` (the exact page's `total`).
+     */
+    countContentContaining(q: ExactContentQuery): number;
+    /** One page of active facts containing `q.query`, newest row first. */
+    contentContainingRows(q: ExactContentQuery & {
+        limit: number;
+        offset: number;
+    }): number[];
+    /**
+     * How many rows carry exactly `q.query` as their title — OR as one of their aliases (v17), under
+     * the same filters as the fuzzy path.
+     *
+     * Including the alias set here is what makes an old handle answer the EXACT stage instead of
+     * falling through to the fuzzy shortlist: "the title of this transaction used to be X" is exactly
+     * the same question as "a transaction titled X", and the caller cannot tell the two apart.
+     */
+    countTitleEqual(q: ExactTitleQuery): number;
+    /**
+     * One page of title-equal rows.
+     *
+     * `=`, not `LIKE`: the contract is "title EQUALS the query" (case-sensitive, because title is an
+     * immutable handle), so no wildcard and no folding — `fa.title = ?` under SQLite's BINARY collation
+     * is exactly that comparison. An ALIAS that equals the query counts too (v17); `matched_title`
+     * carries the text that matched, while `title` stays the row's current handle.
+     *
+     * Bind order (the statement's, not a rule of thumb): the SELECT's `matched_title` expression first
+     * (query, query), then the filter, then the WHERE's equality pair (query, query), then the page.
+     */
+    titleEqualRows(q: ExactTitleQuery & {
+        limit: number;
+        offset: number;
+    }): TitleRow[];
+    /**
+     * How many ACTIVE facts fall inside the window (the `mode:"time"` envelope's `total`).
+     */
+    countTimeWindow(range: TimeRange, opts?: {
+        kind?: MemoryKind;
+        source?: string;
+    }): number;
+    /**
+     * One page of that window, newest first along the axis the caller filtered on.
+     *
+     * The order follows the SAME axis as the WHERE (one mapping in {@link timeAxisColumn}), so the
+     * first row is the newest one the window contains; `fact_id ASC` is the deterministic tie-break
+     * among equal instants (an import can produce several).
+     */
+    timeWindowRows(range: TimeRange, opts: {
+        kind?: MemoryKind;
+        source?: string;
+        limit: number;
+        offset: number;
+    }): number[];
+    /**
+     * `mem_admin list` narrowed by a window: the same page shape and order as {@link page}, plus the
+     * caller's time predicate. Separate from `page` because that method pins two different indexes by
+     * hand and a window is exactly the shape where the indexed range should drive instead.
+     */
+    pageTimeWindow(status: string, kind: MemoryKind | undefined, range: TimeRange, limit: number, offset: number, source?: string): Record<string, unknown>[];
+    /** How many rows `pageTimeWindow` would page through (the `admin list` `total`). */
+    countStatusTimeWindow(status: string, kind: MemoryKind | undefined, range: TimeRange, source?: string): 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.