@avantf/dsh-mem 0.6.4 → 0.8.0

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

@@ -1,6 +1,5 @@
 /**
- * `triples` — the SPO graph behind `ask` / `chain`, the structural contradiction signals and
- * the supersede cleanup.
+ * `triples` — the SPO graph behind 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
@@ -25,12 +24,6 @@ interface TripleRow {
 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);
@@ -58,23 +51,5 @@ export declare class TriplesDao {
     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/graph.d.ts

@@ -0,0 +1,249 @@
+import type { Db } from './port.js';
+import type { EdgeReextractOptions, EdgeReextractReport, EdgeRebuildReport, EdgeSourceTriple, EdgeWriteReport, GraphCoverageReport } from '../interfaces/repositories.js';
+export type { EdgeDropReason, EdgeDropSample, EdgeRebuildReport, EdgeReextractMode, EdgeReextractOptions, EdgeReextractReport, EdgeSourceTriple, EdgeVersionCount, EdgeWriteReport, GraphCoverageReport, } from '../interfaces/repositories.js';
+/**
+ * `edges.extraction_version` for rows converted from the legacy string `triples`.
+ *
+ * 0 = "no versioned edge extractor produced this" — the same meaning the value has for
+ * `facts.entities_version` (a row from before the rules were versioned). Phase 2's extractor stamps
+ * 1 and up, so a re-extraction pass selects these rows with `extraction_version < :current` instead
+ * of needing to know which migration wrote them.
+ */
+export declare const LEGACY_EDGE_EXTRACTION_VERSION = 0;
+/** One edge as the graph reads it: IDs for walkers, names for a result payload. */
+export interface GraphEdgeRow {
+    edge_id: number;
+    fact_id: number;
+    subject_id: number;
+    predicate_id: number;
+    object_id: number;
+    subject: string;
+    predicate: string;
+    object: string;
+    confidence: number;
+    source: string;
+    extraction_version: number;
+}
+/** What one schema+backfill pass did (0 for every `*Created` counter on a repeated run). */
+export interface RelationalGraphReport {
+    /** Legacy `triples` rows seen. */
+    triples: number;
+    /** Of those, rows skipped because a slot is blank (no node is invented for `''`). */
+    skipped: number;
+    /** `entities` rows this run created. */
+    entitiesCreated: number;
+    /** `predicates` rows this run created. */
+    predicatesCreated: number;
+    /** `edges` rows this run created. */
+    edgesCreated: number;
+    /** `edges` rows in the table after the run. */
+    edges: number;
+}
+/** `CREATE … IF NOT EXISTS` for the four tables and their indexes — then the backfill. */
+export declare function applyRelationalGraphSchema(db: Db): RelationalGraphReport;
+/**
+ * Convert `triples` → `edges` (idempotent; the tables must already exist).
+ *
+ * Kept separate from {@link applyRelationalGraphSchema} so a re-run can never be confused with a
+ * schema change: this function only inserts rows, and it reports how many it actually inserted.
+ *
+ * Only NOTE triples are converted (STRUCTURED_RELATIONS §四). The report's `triples`/`skipped`
+ * counters still describe every legacy row the conversion looked at, so "the conversion saw N rows
+ * but created fewer edges" stays explainable; `edgesCreated` is what a re-run can be compared against.
+ */
+export declare function backfillEdges(db: Db): RelationalGraphReport;
+/**
+ * One fact's edges, resolved back to names — the evidence contract of R1/R4 ("every edge can be
+ * traced back to its `fact_id`").
+ *
+ * The IDs are returned next to the names because a path walker joins on them; the names are what a
+ * `RelationPath` payload shows. `ORDER BY edge_id` is insertion order, i.e. stable across reads and
+ * deterministic in tests.
+ */
+export declare function edgesForFact(db: Db, factId: number): GraphEdgeRow[];
+/**
+ * One fact's EXPLICIT relations, resolved back to their three stored names
+ * (STRUCTURED_RELATIONS §2) — the read model behind `FactDetail.relations`, the v5 export and the
+ * restore write.
+ *
+ * Only `source = 'explicit'` rows are returned: an extracted edge is derivable from the fact text
+ * and is not something a caller stated, so it must not appear as a declared relation. `ORDER BY
+ * edge_id` is insertion order (the order the caller listed them, minus the four-tuple duplicates),
+ * which is what makes an export→restore round trip compare equal.
+ *
+ * A journal has no edges at all (§四), so this returns `[]` for one without a second query.
+ */
+export declare function explicitRelationsForFact(db: Db, factId: number): {
+    subject: string;
+    predicate: string;
+    object: string;
+}[];
+/**
+ * `edges.extraction_version` for rows THIS module's extractor wrote (Phase 2, R2/R3).
+ *
+ * 1 is the first versioned rule set: alias/canonical normalization of both entity slots and of the
+ * predicate, the confidence policy below, and the direction rule. `LEGACY_EDGE_EXTRACTION_VERSION`
+ * (0) stays what the migration wrote, so `reextractEdges` selects "older than me" without knowing
+ * which code path produced a row. Bump this whenever a change here would produce different edges for
+ * the same triples (the same contract `ENTITY_EXTRACTOR_VERSION` has).
+ *
+ * 2 (Phase 5b, docs/RELATIONAL_RECALL.md §十七) adds the two QUALITY gates every edge now passes:
+ *  - `relations/name-quality.ts#graphNameIssue`: both slots must be bounded, punctuation-free names.
+ *    This is what removes the fragments (`）。**`, `，仓库…`) that Phase 5a measured in 69 of 87 live
+ *    node names;
+ *  - `relations/statement.ts#isStatedRelation`: a triple the text extractor produced (`source: 'svo'`)
+ *    must appear in the fact text as one clause. On the 2026-10-25 live snapshot NONE of the 48
+ *    curated triples the v1 policy had accepted is a stated clause, so every edge v1 wrote was a
+ *    fragment.
+ *
+ * 3 (2026-10-25 relation review, docs/REVIEW-RELATION-EXTRACTION.md) — what changes the EDGE SET for
+ * the same stored triples:
+ *  - `合作` is a `symmetric` predicate (`relations/normalize.ts`), so a walk from either end of that
+ *    family answers (a WRITE is unchanged: one edge, sentence order);
+ *  - the curated vocabulary gained reachable surfaces, so the triples `reextractEdges` re-derives are
+ *    scored against a fuller predicate table (a surface resolves to a curated family instead of
+ *    creating an undescribed one, which is the difference between 0.3 and 0.75 for the same triple).
+ *    Triples themselves are re-derived under `ENTITY_EXTRACTOR_VERSION` 3 — `reextractEdges` reads
+ *    what `triples` holds, so both bumps are required (see `EDGE_REEXTRACT_BATCH`'s counterpart in
+ *    `store/memory.ts#reindexEntities`).
+ */
+export declare const EDGE_EXTRACTOR_VERSION = 3;
+/**
+ * Default facts one {@link reextractEdges} pass may rewrite.
+ *
+ * The same size as `ENTITY_SWEEP_BATCH` on purpose: both are "one bounded pass" of the derived state
+ * run from `maintenance()`, and a corpus should take the same number of passes through either half.
+ * This pass is the cheaper of the two — it reads stored triples instead of re-tagging content, and
+ * measured ~0.04 ms per fact (§14.5).
+ */
+export declare const EDGE_REEXTRACT_BATCH = 2000;
+/**
+ * Write one fact's edges from its extracted triples — the call the WRITE PATH makes (add / update /
+ * revive / merge) right after it inserted the same triples, inside the same transaction.
+ *
+ * The legacy `triples` row is not replaced or read back: it stays the record of "what the string
+ * extractor saw" (the contradiction detector reads it), while `edges` is its normalized, versioned
+ * view. That double write is what lets Phase 2 land without a schema change or a re-extraction of the
+ * corpus, and it is also why this function can be a no-op without breaking anything.
+ *
+ * Never throws on a bad triple (it reports it); it CAN throw on a broken database, which is why the
+ * store calls it best-effort — a graph write must not fail a fact write (§4.3).
+ *
+ * Phase 5b reads the fact's `content` once when at least one triple came from the TEXT extractor
+ * (`source: 'svo'`), because the statement test (`relations/statement.ts`) is a test against what the
+ * fact actually says. One indexed row read per fact, and none for explicitly asserted triples.
+ *
+ * The gates themselves are `relations/confidence.ts#evaluateRelation`; this function reads the
+ * content the test needs and materializes what the policy accepted.
+ *
+ * @param options.dryRun resolve WITHOUT creating entities/predicates and report what would happen
+ *   (the coverage report's "why is this fact missing from the graph" view).
+ */
+export declare function writeEdgesForFact(db: Db, factId: number, triples: readonly EdgeSourceTriple[], options?: {
+    dryRun?: boolean;
+    samples?: number;
+}): EdgeWriteReport;
+/**
+ * Write the relations a CALLER stated (`mem_remember.relations`, STRUCTURED_RELATIONS §2).
+ *
+ * A thin, named wrapper over {@link writeEdgesForFact}: the caller's `{subject, predicate, object}`
+ * are mapped onto the same triple shape the extractor produces, with `source: 'explicit'` and
+ * confidence 1 — that source is what makes the writer skip the confidence floor and the statement
+ * test, while still normalizing both entity slots and the predicate and still applying the name
+ * gate. Callers pass already-validated relations (`store/explicit_relations.ts`); this function
+ * reports what was written, dropped or already present, and the STORE decides what a drop means.
+ */
+export declare function writeExplicitEdgesForFact(db: Db, factId: number, relations: readonly {
+    subject: string;
+    predicate: string;
+    object: string;
+}[]): EdgeWriteReport;
+/**
+ * Drop one fact's edges (a superseded revision leaves the live graph, like its triples).
+ *
+ * Two narrowing flags, both about STRUCTURED_RELATIONS §2's `source: 'explicit'` rows — an explicit
+ * edge is the only one NOT derivable from the fact text, so the passes that re-derive edges must be
+ * able to leave them alone while a write that REPLACES the declared relations must be able to drop
+ * exactly them:
+ *
+ *  - `keepExplicit` — re-derivation (`reextractEdges`, the entity sweep) deletes what it can
+ *    recreate and keeps what it cannot;
+ *  - `onlyExplicit` — an `update` that carries new relations rebuilds that revision's explicit set.
+ *
+ * With neither (the default) everything goes: the revision itself is gone (`supersede`).
+ */
+export declare function deleteEdgesForFact(db: Db, factId: number, options?: {
+    keepExplicit?: boolean;
+    onlyExplicit?: boolean;
+}): number;
+/**
+ * Delete every edge whose fact is NOT a note (STRUCTURED_RELATIONS §四/§七).
+ *
+ * The one-time cleanup of the pre-5c graph: before this phase a `journal` write produced edges, and
+ * an upgraded database still carries them. It is a DELETE on the derived table only — the facts and
+ * their `triples` are untouched (the contradiction detector still reads those) — and it is
+ * idempotent, so `maintenance` can call it on every pass and report 0.
+ *
+ * `kind <> 'note'` rather than `kind = 'journal'`: `journal` is the only other value the closed set
+ * has, and legacy values a pre-13 database might still hold all map onto `note`
+ * (`store/kinds.ts#mapLegacyKind`), so the negative form is the one that cannot under-clean.
+ */
+export declare function deleteNonNoteEdges(db: Db): number;
+/**
+ * Re-derive one fact's edge set under the CURRENT policy (STRUCTURED_RELATIONS §五/§七).
+ *
+ * WHY THIS EXISTS. `reextractEdges` only selects ACTIVE facts, so an archived row keeps whatever
+ * edges it had — including the version-0 rows migration 15's backfill created from legacy triples.
+ * Those are exactly the rows Phase 5b's rules were written to refuse (fragments, unstated
+ * clauses), and the reader hides them only while the row is archived: a restore would put them
+ * back on the graph without ever re-deriving them. This is the one-fact rebuild both re-entry paths
+ * call (`store/memory.ts#restore` and the revive branch of `persistFact`), so an archived row comes
+ * back with the edges TODAY's rules would write and never with an older extractor's leftovers.
+ *
+ * Two properties that make it safe to call blindly:
+ *  - it is IDEMPOTENT in edge SET (same triples + same policy → same rows; only `edge_id`s move);
+ *  - it never touches `source: 'explicit'` rows. A declared relation cannot be re-derived from the
+ *    fact text (`deleteEdgesForFact`'s `keepExplicit`), so losing one here would lose a caller's
+ *    statement — the one thing a restore must preserve even when the extracted half is rebuilt.
+ *
+ * A JOURNAL gets its non-explicit edges dropped and nothing written (§四). The caller decides the
+ * failure policy: the write path and `restore` call it best-effort inside a savepoint, so a broken
+ * row keeps its previous edges and the fact write is never blocked (§4.3).
+ */
+export declare function rebuildEdgesForFact(db: Db, factId: number, kind: string): EdgeRebuildReport;
+/**
+ * Re-derive edges from the STORED triples of facts whose edges predate the current extractor
+ * (§4.3 "支持按 extraction_version 重抽/回填").
+ *
+ * Why it re-derives from `triples` and not from the fact text: the rules that changed in Phase 2 are
+ * functions of the triples (alias/canonical resolution, confidence, direction). A change to the TEXT
+ * extraction is `ENTITY_EXTRACTOR_VERSION`'s business — `reindexEntities` re-tags the content, and
+ * it now rewrites the edges in the same transaction (`store/memory.ts`). Re-tagging here would mean
+ * a jieba round-trip per fact for a pass that is otherwise pure SQL.
+ *
+ * One transaction per fact, so a row that cannot be re-derived keeps its previous edges and stays
+ * selected for the next pass instead of leaving a half-rewritten graph.
+ *
+ * ONLY NOTES ARE SELECTED (STRUCTURED_RELATIONS §四): the graph expresses stable facts, so a
+ * `journal` row's triples are no longer turned into edges at all — its leftover edges from before
+ * this phase are removed by {@link deleteNonNoteEdges}, not rewritten here. Explicit relations
+ * (`source: 'explicit'`) survive the rewrite: they cannot be re-derived from `triples`.
+ *
+ * Idempotent in version mode: a second pass finds nothing older than the current version and
+ * reports `facts: 0`. In `all` mode it re-derives everything again by definition — the edge SET is
+ * identical, only `edge_id`s are new.
+ */
+export declare function reextractEdges(db: Db, options?: EdgeReextractOptions): EdgeReextractReport;
+/**
+ * Read the coverage numbers — what Phase 2 actually produces on this corpus, and why the rest did
+ * not make it (§R6: "抽取覆盖率、错误边样本").
+ *
+ * `samples` is a bounded PREVIEW (it re-runs the resolver with `dryRun` over the first
+ * `sampleFacts` facts that have triples), not a persisted log: a drop is a decision, not a row, and
+ * the triples are what the decision was made from. Keeping it computed means it can never disagree
+ * with the write path — both call the same policy functions.
+ */
+export declare function graphCoverage(db: Db, options?: {
+    samples?: number;
+    sampleFacts?: number;
+}): GraphCoverageReport;

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

@@ -0,0 +1,35 @@
+/**
+ * The one schema+data step that turns the old `category` vocabulary into the two memory layers
+ * (JOURNAL_NOTES_REDESIGN N1–N5).
+ *
+ * It is a FUNCTION, not an inline migration body, because two callers need the exact same work:
+ *
+ *  - `MEMORY_SCHEMA` migration 13 (`journal-and-notes`) — the published upgrade path, which starts
+ *    from the last released schema (`user_version = 10`, 16 free-form categories);
+ *  - `scripts/migrate-local-kind.mjs` — the ONE-OFF manual conversion of a local database that was
+ *    already put into the never-published eight-category shape by an earlier build of migration 13.
+ *    That database sits at `user_version = 13` with a `categories` table, the `facts_category_*`
+ *    triggers and an eight-value `category` column, so it needs the DATA half without a version bump.
+ *
+ * Both states are handled by the same predicates: the old `category` column is mapped when it exists,
+ * the lookup table and triggers are dropped when they exist, and every step is idempotent so a
+ * second run is a no-op. `worklog` (the one episodic value in the published set) becomes `journal`;
+ * every other value — the other 15 published ones and all eight experimental ones — becomes `note`,
+ * because the eight-category experiment already collapsed the episodic/stable distinction and only
+ * `worklog` was ever an episode.
+ *
+ * WHAT IT DOES NOT DO: rebuild FTS (`kind` is not indexed by it), touch `created_at`/`content`, or
+ * bump `user_version` (the caller does that — `migrate()` for the published path, nobody for the
+ * manual one).
+ */
+import type { Db } from './port.js';
+/** What one run did, for the operator-facing script and the tests. */
+export interface JournalNotesMigrationReport {
+    /** Rows the old `category` column labelled `worklog` (→ `journal`). */
+    journal: number;
+    /** Every other row (→ `note`). */
+    note: number;
+    /** Whether the old `category` column existed and was dropped by this run. */
+    droppedCategoryColumn: boolean;
+}
+export declare function applyJournalAndNotesSchema(db: Db): JournalNotesMigrationReport;

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

@@ -44,6 +44,15 @@ export interface MigrationResult {
  * no-op, while an existing one is upgraded here.
  */
 export declare function addColumnIfMissing(db: Db, table: string, column: string, columnDdl: string): void;
+/**
+ * Whether `table` already has `column`.
+ *
+ * Used by {@link addColumnIfMissing} and by a step whose data fix depends on a column an earlier
+ * step may or may not have created — a database from the never-published eight-category era has no
+ * `facts.kind` at all until the local conversion script adds it, and such a file must still be
+ * upgradable by the plugin (docs/JOURNAL_NOTES_REDESIGN.md §6.2).
+ */
+export declare function hasColumn(db: Db, table: string, column: string): boolean;
 /** The schema version stored in the database header (0 = pre-versioning). */
 export declare function readUserVersion(db: Db): number;
 /**

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

@@ -13,9 +13,11 @@
  * `pragma`, 4 `close` call sites, and none of the statement extras such as
  * `pluck`/`raw`/`iterate`/`columns`/`function`/`loadExtension`).
  *
- * SYNCHRONOUS by design: `persistFact` runs contradiction detection inside its transaction
- * and the lifecycle tick is one synchronous pass, so an async driver does not fit this port.
- * That is a decision, not an oversight.
+ * SYNCHRONOUS CALLS, ONE ASYNC ENTRY POINT: a statement call is synchronous, because the SQLite
+ * driver is and the lifecycle tick/hot read paths are synchronous passes over it. What a REMOTE
+ * backend needs is not an async `prepare` but an async UNIT OF WORK, which is
+ * {@link Db.transactionAsync}: the store's write paths await repository calls inside a transaction,
+ * and that is the only place this port has to span an `await` (DB-2).
  */
 export interface DbRunResult {
     changes: number;
@@ -48,10 +50,27 @@ export interface DbTransaction<T> {
     deferred(): T;
     exclusive(): T;
 }
+/**
+ * The transaction mode of {@link Db.transactionAsync}. `IMMEDIATE` takes the write lock up front,
+ * which is what a cross-process read-modify-write needs (see {@link DbTransaction.immediate}).
+ */
+export type DbTransactionMode = 'DEFERRED' | 'IMMEDIATE';
 export interface Db {
     prepare<Row = unknown>(sql: string): DbStatement<Row>;
     exec(sql: string): void;
     transaction<T>(fn: () => T): DbTransaction<T>;
+    /**
+     * An ASYNC body inside one transaction (DB-2). Added beside the synchronous runner because the
+     * store's write paths now await repository calls: a remote backend has no synchronous transaction
+     * to offer, and the connection-scoped "one unit of work" must survive those awaits.
+     *
+     * The two runners share the connection's nesting depth, so an async transaction opened inside a
+     * synchronous one (or vice versa) becomes a SAVEPOINT rather than a second `BEGIN`. Bodies that
+     * do not await are unaffected by this method; bodies that do must accept that a single SQLite
+     * connection cannot interleave two units of work — the adapter serializes async transactions so a
+     * second one waits for the first to commit or roll back.
+     */
+    transactionAsync<T>(fn: () => T | Promise<T>, mode?: DbTransactionMode): Promise<T>;
     pragma(source: string): unknown;
     close(): void;
 }

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

@@ -6,6 +6,101 @@
  * so adopting them must be a no-op plus a version stamp (see `migrations.ts`). Later schema
  * changes belong in a numbered migration — `ONE_OPEN_CONTRADICTION_ROW_SQL` below is v2.
  */
+/**
+ * The two columns that replace the eight-value `category` vocabulary
+ * (JOURNAL_NOTES_REDESIGN N1–N5).
+ *
+ * `kind` is the memory LAYER — `journal` (episodic, must carry an event date) or `note` (semantic,
+ * no event time required) — and it is the only classification any code or tool reads. The CHECK is
+ * the DB-level backstop for a non-cooperating writer (an older build sharing the file, a hand-run
+ * `sqlite3`); the application guard refuses an unknown value before it gets here.
+ *
+ * `legacy_category` is the AUDIT column: migration 13 copies the old free-form `category` into it
+ * (all 16 published values, `worklog` included) so the provenance of a migrated row is not lost. No
+ * tool schema, filter or query reads it.
+ *
+ * Both are exported as the exact column DDL because the base schema and migration 13 must produce
+ * BYTE-IDENTICAL column definitions (`test/db_upgrade_parity.spec.ts` compares sqlite_master).
+ */
+export declare const FACT_KIND_COLUMN_DDL = "TEXT NOT NULL DEFAULT 'note' CHECK (kind IN ('journal','note'))";
+export declare const FACT_LEGACY_CATEGORY_COLUMN_DDL = "TEXT";
+/**
+ * The journal title's column DDL (JOURNAL_TITLE_SEARCH §2.1/§11.1).
+ *
+ * NULLABLE on purpose: every journal written before this column existed has no title, and the
+ * model-facing "a journal needs a title" rule is enforced at the WRITE boundary, never by a CHECK
+ * (a `CHECK (kind='journal' → title IS NOT NULL)` could not be added to a corpus that is all NULL).
+ * Shared with migration 14 so the base schema and the upgrade produce byte-identical definitions.
+ */
+export declare const FACT_TITLE_COLUMN_DDL = "TEXT";
+/**
+ * A title this fact USED to carry (v17; JOURNAL_TITLE_SEARCH §2.2 + R3's controlled retitle).
+ *
+ * A title is immutable inside a revision chain *by default*, but a wrong handle had no way out: the
+ * only accepted change was the one-time backfill of a NULL title, so a typo stayed searchable-by-
+ * nothing forever and the only repair was deleting the transaction. `retitle: true` on an update is
+ * that way out, and this table is what keeps it honest: the OLD title is recorded as an alias of the
+ * revision that replaced it, so every search for the old handle still finds the transaction (with
+ * `matched_title` naming what actually matched).
+ *
+ * Why `(fact_id, title)` rather than a chain id: aliases are derived search state of the revision
+ * that carries the title, exactly like `fact_sources`. The write path copies the predecessor's alias
+ * rows forward onto each new revision (see `copyTitleAliases`), so a correction never strands an old
+ * handle on an archived row. `ON DELETE CASCADE` keeps a purge from leaving orphans.
+ *
+ * No global UNIQUE on `title`: two unrelated transactions may have carried the same handle at
+ * different times, and refusing the second one would make the table a naming registry instead of a
+ * search aid.
+ */
+export declare const TITLE_ALIASES_TABLE_DDL = "CREATE TABLE IF NOT EXISTS title_aliases (\n  fact_id    INTEGER NOT NULL REFERENCES facts(fact_id) ON DELETE CASCADE,\n  title      TEXT NOT NULL,\n  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,\n  PRIMARY KEY (fact_id, title)\n)";
+/**
+ * v17's alias index: both the EXACT title comparison and the fuzzy title statement look an alias up
+ * by its TEXT (`ta.title = ?` / `ta.title LIKE ?`), and `(fact_id, title)` cannot serve that
+ * direction. The table only holds corrected handles, so it stays small; the index is what keeps the
+ * per-search cost independent of how many corrections the corpus has seen.
+ */
+export declare const TITLE_ALIASES_INDEXES: string[];
+/**
+ * v15's relation graph (RELATIONAL_RECALL §3): `entity_aliases`, `predicates`, `predicate_aliases`
+ * and `edges`.
+ *
+ * Why a second set of tables next to `entities` / `fact_entities` / `triples` instead of rewriting
+ * them: `triples` stores `subj` / `pred` / `obj` as TEXT, so every graph question is a string match
+ * that cannot tell two spellings of one entity apart and cannot keep a predicate's aliases in one
+ * place. `edges` keeps the same fact-level provenance (`fact_id`, `confidence`, `source`) but points
+ * at IDs, which is what a path query and a confidence policy need. The legacy `triples` table stays
+ * exactly as it is (the write path fills it, the contradiction detector reads it); `edges` is
+ * DERIVED from it by migration 15 until Phase 2 moves extraction onto IDs.
+ *
+ * Two shapes here are deliberate and easy to get wrong:
+ *  - `extraction_version` is NOT NULL DEFAULT 0, the same convention as `facts.entities_version`:
+ *    0 means "before edge extraction was versioned", which is exactly what a row converted from
+ *    `triples` is. A later re-extraction pass can therefore adopt it with
+ *    `WHERE extraction_version < :current` instead of the row hiding behind a NULL forever.
+ *  - `edges.created_at` carries the LEGACY triple's timestamp (`COALESCE(created_at, now)`), not the
+ *    moment the backfill ran: this graph describes when a relation was recorded, and stamping a
+ *    migration's wall clock onto a years-old relation would destroy that.
+ *
+ * `direction` has NO CHECK on purpose: the §4.2 vocabulary is Phase 2's to finish, and a CHECK on an
+ * enum that is still being designed costs a table rebuild to extend. The only value this phase
+ * writes is `'forward'`, documented as "subject → object is the stored direction; a reverse query
+ * reads the same edge backwards and is not a second edge".
+ */
+export declare const ENTITY_ALIASES_TABLE_DDL = "CREATE TABLE IF NOT EXISTS entity_aliases (\n  alias      TEXT NOT NULL UNIQUE,\n  entity_id  INTEGER NOT NULL REFERENCES entities(entity_id) ON DELETE CASCADE,\n  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP\n)";
+export declare const PREDICATES_TABLE_DDL = "CREATE TABLE IF NOT EXISTS predicates (\n  predicate_id   INTEGER PRIMARY KEY AUTOINCREMENT,\n  canonical_name TEXT NOT NULL UNIQUE,\n  direction      TEXT NOT NULL DEFAULT 'forward',\n  description    TEXT,\n  created_at     TIMESTAMP DEFAULT CURRENT_TIMESTAMP\n)";
+export declare const PREDICATE_ALIASES_TABLE_DDL = "CREATE TABLE IF NOT EXISTS predicate_aliases (\n  alias        TEXT NOT NULL UNIQUE,\n  predicate_id INTEGER NOT NULL REFERENCES predicates(predicate_id) ON DELETE CASCADE,\n  created_at   TIMESTAMP DEFAULT CURRENT_TIMESTAMP\n)";
+export declare const EDGES_TABLE_DDL = "CREATE TABLE IF NOT EXISTS edges (\n  edge_id            INTEGER PRIMARY KEY AUTOINCREMENT,\n  fact_id            INTEGER NOT NULL REFERENCES facts(fact_id) ON DELETE CASCADE,\n  subject_id         INTEGER NOT NULL REFERENCES entities(entity_id) ON DELETE CASCADE,\n  predicate_id       INTEGER NOT NULL REFERENCES predicates(predicate_id) ON DELETE CASCADE,\n  object_id          INTEGER NOT NULL REFERENCES entities(entity_id) ON DELETE CASCADE,\n  confidence         REAL NOT NULL DEFAULT 0.5,\n  extraction_version INTEGER NOT NULL DEFAULT 0,\n  source             TEXT NOT NULL DEFAULT 'heuristic',\n  created_at         TIMESTAMP DEFAULT CURRENT_TIMESTAMP,\n  UNIQUE (fact_id, subject_id, predicate_id, object_id)\n)";
+/**
+ * The graph's indexes, spelled once for the base DDL and migration 15.
+ *
+ * `UNIQUE (fact_id, subject_id, predicate_id, object_id)` already serves "this fact's edges" and the
+ * `ON DELETE CASCADE` check for `fact_id`. The other three columns each need their own leading index
+ * because they are ALSO cascade parents and because they are the two directions a graph query walks:
+ * subject → (predicate) → object is one-hop/two-hop, object → predicate → subject is the reverse
+ * query ("who manages 李娜"). Without them every entity/predicate delete scans `edges`, and the
+ * reverse walk has no index at all.
+ */
+export declare const RELATIONAL_GRAPH_INDEXES: string[];
 export declare const DDL: string[];
 /**
  * v2 — at most one OPEN row per contradiction pair.
@@ -24,3 +119,27 @@ export declare const ONE_OPEN_CONTRADICTION_ROW_SQL: string[];
  */
 export declare function factsFtsTableDdl(tokenizer: string): string;
 export declare const FTS_TRIGGERS: string[];
+/** The title-side FTS table's name — one spelling for the DDL, the triggers and the query builder. */
+export declare const TITLE_FTS_TABLE = "facts_title_fts";
+/**
+ * The title FTS table (JOURNAL_TITLE_SEARCH §3/§11.3): a SECOND, independent external-content index.
+ *
+ * `facts_fts` keeps indexing `content` only and is not touched by this at all — mixing titles into the
+ * content score is exactly what the separate action exists to avoid. The table is external-content
+ * (`content='facts'`) so the rows are the fact table itself and `rebuild` can re-derive the index;
+ * `COALESCE(title,'')` in the triggers is what makes a NULL title indexable (external-content FTS5
+ * cannot store a NULL).
+ *
+ * A function, like {@link factsFtsTableDdl}, because the tokenizer is the one the database was built
+ * with (read back from `sqlite_master`), not necessarily this process's preference.
+ */
+export declare function titleFtsTableDdl(tokenizer: string): string;
+/**
+ * Keep {@link TITLE_FTS_TABLE} in step with `facts.title` — insert, delete, and `UPDATE OF title`.
+ *
+ * `AFTER UPDATE OF title` is deliberate and narrow: the content triggers fire for every content
+ * rewrite, while a title change is the one event this index cares about (a backfill, a merge copying
+ * a title onto an existing row). The `'delete'` command needs the OLD value, which is why the row is
+ * re-inserted rather than updated in place.
+ */
+export declare const TITLE_FTS_TRIGGERS: string[];

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

@@ -82,3 +82,12 @@ export declare function likeSubstring(column: string, terms: readonly string[]):
     count: string;
     params: string[];
 };
+/**
+ * The bind values {@link likeSubstring} uses, in its own order.
+ *
+ * Split out because a statement can compute the same substring predicate over TWO different columns
+ * (the title search ranks on the title that matched, which is either `facts.title` or an alias) while
+ * binding one pattern list. Empty terms are dropped here, so the caller never gets a `%%` that
+ * matches everything, and `%`/`_` stay literal through the same escaping.
+ */
+export declare function likePatterns(terms: readonly string[]): string[];

package/lib/engine/mem/dbdrivers/fake/driver.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The MOCK-REMOTE storage driver (DB-4, docs/DB_DRIVER_LAYOUT.md §五).
+ *
+ * What `storage.driver: fake` selects. It is a REAL driver — registered in the same registry as
+ * SQLite, declaring `contractVersion`, capabilities and an async `open()` — whose backend is the
+ * SQLite backend placed behind a simulated hop ({@link MockRemoteTransport}):
+ *
+ *   store → StorageBackend (fake) → async surface (one hop per call) → SQLite core (in-memory)
+ *
+ * The purpose is narrow and stated: it proves the CONFIG SWITCH and the ASYNC BOUNDARY
+ * (`docs/DB_DRIVER_LAYOUT.md` §五, `docs/DATABASE_PORTABILITY.md` §十四). It is NOT a second storage
+ * engine and NOT the SQL independence proof: its core is this build's SQLite, so a query that only
+ * SQLite can answer would still "pass". A truly independent fake (or DB-5's `postgres`) plugs into
+ * the same registry and must pass the same `test/helpers/storage_contract.ts` suite unchanged — which
+ * is exactly the acceptance criterion, not this driver's implementation.
+ *
+ * Consequences of that choice, stated rather than hidden:
+ *
+ *  - capabilities are the core's, because the mock has no capability of its own (no probing);
+ *  - `relationalHandle()` returns the core's handle: the runtime's transitional SQL surfaces keep
+ *    working on a fake-backed store (a genuinely remote driver would omit it and the runtime fails
+ *    loudly, see `buildRuntime`);
+ *  - the default core is `:memory:`, so opening a fake creates no file; `storage.fake.path` opts into
+ *    a file-backed core for a test that wants one.
+ *
+ * @module dbdrivers/fake/driver
+ */
+import type { StorageConfig } from '../../../mem-contract/index.js';
+import type { StorageCapabilities } from '../../interfaces/capabilities.js';
+import type { MigrationRunner } from '../../interfaces/migrations.js';
+import type { ContradictionRepository, KeyValueRepository, MemoryRepository, RelationRepository, SourceRepository } from '../../interfaces/repositories.js';
+import type { SearchIndex } from '../../interfaces/search_index.js';
+import type { LifecycleService, StorageBackend } from '../../interfaces/storage_backend.js';
+import type { StorageDriver } from '../../interfaces/storage_driver.js';
+import { SqliteStorageBackend } from '../sqlite/driver.js';
+import { MockRemoteTransport } from './transport.js';
+/** The in-memory core a mock remote serves when `storage.fake.path` is unset. */
+export declare const FAKE_IN_MEMORY_PATH = ":memory:";
+/** What this driver can do: the core's capabilities, declared once and never probed above. */
+export declare const FAKE_CAPABILITIES: StorageCapabilities;
+/**
+ * The mock-remote backend: the same repositories as the core, every call one transport hop.
+ *
+ * The surface tree is derived from the core ({@link asyncSurface}), so a method added to a port is
+ * routed through the transport automatically — there is no hand-written delegation list that can
+ * silently miss one.
+ */
+export declare class FakeStorageBackend implements StorageBackend {
+    readonly kind = "fake";
+    readonly capabilities: StorageCapabilities;
+    readonly facts: MemoryRepository;
+    readonly relations: RelationRepository;
+    readonly sources: SourceRepository;
+    readonly contradictions: ContradictionRepository;
+    readonly search: SearchIndex;
+    readonly keyValue: KeyValueRepository;
+    readonly lifecycle: LifecycleService;
+    readonly migrations: MigrationRunner;
+    /** The simulated hop every call above crosses (exposed for tests and diagnostics). */
+    readonly transport: MockRemoteTransport;
+    private readonly core;
+    constructor(core: SqliteStorageBackend, transport: MockRemoteTransport);
+    /**
+     * The transitional relational handle, delegated to the core (see this module's doc: a genuinely
+     * remote driver omits it, and `buildRuntime` refuses to start rather than inventing one).
+     */
+    relationalHandle(): unknown;
+    /**
+     * Closing the backend is not a REQUEST: the core is released directly, so a simulated failure can
+     * never leave a test (or a process) holding a half-closed store.
+     */
+    close(): Promise<void>;
+}
+/** The mock-remote driver: what `storage.driver: fake` (or the `storage.backend` alias) selects. */
+export declare const fakeDriver: StorageDriver<StorageConfig>;

package/lib/engine/mem/dbdrivers/fake/index.d.ts

@@ -0,0 +1,7 @@
+import type { StorageBackend } from '../../interfaces/storage_backend.js';
+import { FakeStorageBackend } from './driver.js';
+export { FAKE_CAPABILITIES, FAKE_IN_MEMORY_PATH, FakeStorageBackend, fakeDriver, } from './driver.js';
+export { MOCK_REMOTE_FAILURE_CODE, MockRemoteTransport, type MockRemoteTurnaround, type StorageTransport, type TransportRequestRecord, } from './transport.js';
+export { asyncSurface, type AsyncSurfaceOptions } from './surface.js';
+/** Whether a backend was opened by THIS driver (a mock remote over this build's SQLite core). */
+export declare function isFakeStorageBackend(backend: StorageBackend): backend is FakeStorageBackend;