@avantf/dsh-mem 0.7.0 → 0.8.0

package/lib/engine/mem/entities/extract.d.ts

@@ -1,27 +1,27 @@
 /**
- * Entity + SPO triples extraction. Uses nodejieba (optional dependency) for POS;
- * degrades gracefully to a character/regex fallback when unavailable, exactly like
- * the `jieba_available()` guard.
+ * Entity extraction: POS tagging and the noun-ish names that become `entities` rows.
+ *
+ * Uses nodejieba (optional dependency) for POS; degrades gracefully to a character/regex fallback
+ * when unavailable, exactly like the `jieba_available()` guard.
  *
  * Note: nodejieba's `tag()` returns `{ word, tag }` objects, and its POS flag set
  * differs from Python jieba (e.g. proper nouns → `nr`, 名动词 → `vn`).
+ *
+ * WHAT THIS MODULE IS NOT. It owns what is an entity NAME — nothing about relations. The relation
+ * half (SVO candidate triples, explicit patterns, the name/statement/confidence gates and the
+ * predicate vocabulary) lives in `relations/`; the two halves share exactly one thing, the tagging
+ * pass ({@link tagText}), so a write pays for the dictionary once and drives both.
  */
 export interface ExtractedEntity {
     name: string;
     type: string;
     method: string;
 }
-export interface ExtractedTriple {
-    subj: string;
-    pred: string;
-    obj: string;
-    confidence: number;
-    source: string;
-}
-type PosToken = {
+/** One tagged token — the tokenizer's shape, shared with `relations/extract.ts`. */
+export interface PosToken {
     word: string;
     tag: string;
-};
+}
 /**
  * Attempts made so far — the mechanism, not the wall time.
  *
@@ -33,52 +33,49 @@ type PosToken = {
 export declare function jiebaLoadAttempts(): number;
 export declare function jiebaAvailable(): Promise<boolean>;
 /**
- * Version of the extraction RULES below (accepted tags, stop words, triple patterns).
+ * Version of the ENTITY extraction rules below (accepted tags, the regex fallback).
+ *
+ * Persisted per chunk so a reindex can skip rows whose text is unchanged while still rebuilding the
+ * ones produced by an older rule set. Bump this whenever a change here would yield different
+ * ENTITIES for the same text — it is the only thing that separates "already extracted" from
+ * "extracted by the previous version" (DESIGN §20).
+ *
+ * The relation rules have their OWN version (`db/graph.ts#EDGE_EXTRACTOR_VERSION` in `edges`):
+ * an entity-rule change is not an edge-policy change, and vice versa.
+ *
+ * 2 (Phase 5b, docs/RELATIONAL_RECALL.md §十七): punctuation is an ARGUMENT BOUNDARY instead of an
+ * argument in the relation half; `nrt`/`zg` count as arguments like they already counted as entities
+ * (`阿里巴巴`); an opening bracket at an argument's edge is skipped (`（架构评审）`); more negations
+ * are kept on the predicate (`不再/不会/不能/未能`); and triples are stamped `source: 'svo'` so the
+ * graph can require a STATED relation from this producer (`relations/statement.ts`).
+ *
+ * 3 (2026-10-25 relation review, docs/REVIEW-RELATION-EXTRACTION.md): the relation half's TRIPLES
+ * change, not the entity names — curated-predicate surface matching (`主管/隶属于/汇报/部署在/工作于/
+ * 属于/合作` are nouns or non-verbs to the tagger, so they were unreachable), `p`/`c` as a merge
+ * BOUNDARY instead of tokens to step over, strict + weak predicate candidates merged instead of
+ * fallbacks, and a triple-contiguity filter (`isContiguousTriple`). The bump is what makes
+ * `reindexEntities` re-run the extractor over existing facts — `reextractEdges` alone only
+ * re-derives edges from STORED triples and would keep the old, partial extraction.
  *
- * Persisted per chunk so a reindex can skip rows whose text is unchanged while still
- * rebuilding the ones produced by an older rule set. Bump this whenever a change here would
- * yield different entities/triples for the same text — it is the only thing that separates
- * "already extracted" from "extracted by the previous version" (DESIGN §20).
+ * The relation half's naming rules themselves are unchanged by 3; `triples` move because the
+ * identifier of "what the text extractor saw" is this stamp, and `MemoryStore.reindexEntities`
+ * rewrites entities, triples and edges together under it.
  */
-export declare const ENTITY_EXTRACTOR_VERSION = 1;
-export interface TriplePattern {
-    subj?: string;
-    pred?: string;
-    obj?: string;
-}
+export declare const ENTITY_EXTRACTOR_VERSION = 3;
 /**
  * POS-tag `text` ONCE, or `null` when nodejieba is unavailable (callers fall back to regex).
  *
- * Exists so one write can drive BOTH extractors from a single `jieba.tag()` call: `add`/`update`
- * used to tag the same content twice (once for entities, once for triples), which is pure repeated
- * mission — measured ~1.1 ms per 1000 characters per pass.
+ * Exists so one write can drive BOTH halves from a single `jieba.tag()` call: entity names and
+ * relation candidates used to tag the same content twice, which is pure repeated work — measured
+ * ~1.1 ms per 1000 characters per pass.
  */
 export declare function tagText(text: string): Promise<PosToken[] | null>;
 /**
  * Entities from ALREADY-TAGGED tokens (`null` = tagger unavailable → regex fallback on `text`).
  *
- * The token array is passed in rather than re-derived, so a caller that needs entities AND triples
- * pays for one tagging pass (see `tagText`).
+ * The token array is passed in rather than re-derived, so a caller that needs entities AND
+ * relations pays for one tagging pass (see `tagText`).
  */
 export declare function entitiesFromTokens(tokens: PosToken[] | null, text: string): ExtractedEntity[];
 /** Extract entity names using nodejieba POS when available, else a regex fallback. */
 export declare function extractEntities(text: string): Promise<ExtractedEntity[]>;
-/**
- * SPO triples from ALREADY-TAGGED tokens (`null` = tagger unavailable → no triples, as before).
- *
- * `pos` is exported alongside `entitiesFromTokens` so the write path can tag once and drive both.
- */
-export declare function triplesFromTokens(rawTokens: PosToken[] | null): ExtractedTriple[];
-/** Extract a few SPO triples via a simplified SVO heuristic. Returns [] when jieba unavailable. */
-export declare function extractTriples(text: string): Promise<ExtractedTriple[]>;
-/**
- * Parse a natural-language question into a direction-aware TriplePattern where
- * interrogative slots are wildcards (`undefined`).
- * `parse_query_pattern`: predicates anchor to the interrogative, and no literal
- * interrogative word fills a slot.
- *
- *   「李娜管理谁」 → { subj: '李娜', pred: '管理' }
- *   「谁管理李娜」 → { pred: '管理', obj: '李娜' }
- */
-export declare function parseQueryPattern(query: string): Promise<TriplePattern>;
-export {};

package/lib/engine/mem/eval/derived_runner.d.ts

@@ -69,12 +69,17 @@ export interface DerivedRuntimePort {
     }): Promise<{
         fact_id: number;
     }>;
+    /**
+     * `search` as this harness needs it. `hits` is OPTIONAL because the answer has three modes since
+     * Phase 4 (a `mode:"relation"` answer carries paths + evidence instead); a relation answer ranks
+     * nothing here — this harness grades content retrieval.
+     */
     recall(req: {
         action: 'search';
         query: string;
         limit?: number;
     }): Promise<{
-        hits: {
+        hits?: {
             ref_id: number;
         }[];
     }>;

package/lib/engine/mem/eval/relation_gold.d.ts

@@ -0,0 +1,251 @@
+/**
+ * The relation-recall gold set and its evaluator (docs/RELATIONAL_RECALL.md R6 / Phase 5a).
+ *
+ * WHAT THIS FILE IS. One deterministic corpus, one list of labelled queries, and a runner that
+ * seeds a THROWAWAY database through the production write path and measures the rule the relation
+ * stage promises (RELATIONAL_RECALL §6–7):
+ *
+ *  - a COMPLETE relation question (one-hop / reverse / two-hop) is answered with structure;
+ *  - a PURE multi-entity connection ("张伟和李娜") is answered at the FACT level (`mode:"facts"`,
+ *    docs/GRAPH_RECALL_AND_SEMANTICS.md §7.9), including journal entries and notes without edges;
+ *  - an incomplete or unanswerable one (no plan, no path/fact, archived evidence, filter mismatch)
+ *    falls back to fuzzy and never returns an empty `mode:"relation"` / `mode:"facts"`;
+ *  - exact content and `titles` still win / stay untouched;
+ *  - aliases (entity + predicate), `kind` / `source` / `time` filters narrow the graph.
+ *
+ * WHY A GOLD SET AND NOT MORE SPECS. A spec asserts one behaviour per test; an eval fixture assigns
+ * every query an expected ROUTE and an expected ANSWER, then reports route accuracy, path
+ * precision/recall and the fallback rate over the whole set. The vitest spec
+ * (`test/relation_eval.spec.ts`) freezes the numbers, while `scripts/relation_gold_eval.mjs`
+ * prints the same report for the docs — both import THIS module, so the table cannot drift from
+ * the assertion.
+ *
+ * HOW THE FIXTURE IS SEEDED. Facts go through `rt.remember` (real FTS rows, entity links, triples,
+ * edges). The facts whose object surface the STRING EXTRACTOR's tokenizer would decide differently
+ * (`李娜负责支付网关` yields `网关`) get `writeEdgesForFact` afterwards: extraction quality is R3's
+ * subject, while the planner/walk is what this fixture evaluates. `writeEdgesForFact` is still the
+ * production edge writer (normalization, confidence policy, version stamp), so the seeded graph is
+ * the shape production builds. `archive` is the real admin action.
+ *
+ * WHAT IS DELIBERATELY NOT HERE. No timing assertions (those are `scripts/bench-relation.mjs`,
+ * because a CI runner's p95 is not a specification), no live database, no model, no new action.
+ *
+ * @module eval/relation_gold
+ */
+import type { MemoryKind, TimeFilter } from '../../mem-contract/index.js';
+import type { AvantfRuntime } from '../runtime.js';
+/** One triple the fixture wants in the graph, as the production edge writer takes it. */
+export interface RelationGoldEdge {
+    subj: string;
+    pred: string;
+    obj: string;
+}
+/** One fact of the synthetic corpus. `key` is the only handle expectations use. */
+export interface RelationGoldFact {
+    key: string;
+    content: string;
+    kind?: MemoryKind;
+    title?: string;
+    eventDate?: string;
+    sourceRef?: string;
+    /**
+     * `facts.created_at` to force after the write — the time axis is a caller-visible filter, and
+     * "yesterday's fact" must be constructible without waiting a day.
+     */
+    createdAt?: string;
+    /** Edges to (re)write through `writeEdgesForFact`; omitted = whatever the text extractor produced. */
+    edges?: readonly RelationGoldEdge[];
+    /** Archive this fact after the corpus is seeded (the edge is written first, then hidden). */
+    archived?: boolean;
+}
+/** Which behaviour a query is labelled with. One primary label per query keeps the table readable. */
+export type RelationGoldCategory = 'one-hop' | 'reverse' | 'two-hop' | 'facts' | 'alias' | 'archived' | 'kind' | 'source' | 'time' | 'negative' | 'exact';
+/** One expected path, by entity names and the ordered fact keys behind its edges. */
+export interface RelationGoldPath {
+    start: string;
+    end: string;
+    hops: number;
+    facts: readonly string[];
+}
+/** The four routes a gold query may be graded on ('time' is not one: every gold query has a `query`). */
+export type RelationGoldMode = 'relation' | 'facts' | 'fuzzy' | 'exact';
+/** What a query must produce. */
+export interface RelationGoldExpectation {
+    mode: RelationGoldMode;
+    /** Relation answers: the COMPLETE path set (no extra, no missing). */
+    paths?: readonly RelationGoldPath[];
+    /**
+     * The facts the answer must cite. For `relation` this is the evidence set; for `facts` it is the
+     * WHOLE fact page (`facts` requires equality, in any order); for `exact`/`fuzzy` it is the hit set
+     * (`exact` requires equality, `fuzzy` requires inclusion in its top-5 page).
+     */
+    facts?: readonly string[];
+}
+/** One labelled query. */
+export interface RelationGoldQuery {
+    id: string;
+    query: string;
+    category: RelationGoldCategory;
+    kind?: MemoryKind;
+    source?: string;
+    time?: TimeFilter;
+    expect: RelationGoldExpectation;
+}
+/** A `mem_recall.titles` regression check (the title search must not see the planner). */
+export interface RelationGoldTitleCheck {
+    id: string;
+    query: string;
+    /** Title-holder fact keys, in the order the exact title page returns them. */
+    facts: readonly string[];
+}
+/**
+ * The corpus.
+ *
+ * The entity sets are DELIBERATELY disjoint enough that each query has one unambiguous answer:
+ *
+ * ```text
+ *   张伟 ──管理──▶ 李娜 ──管理(负责)──▶ 支付网关        note
+ *   张伟 ──管理──▶ 王强 ──管理(负责)──▶ 风控引擎        note (distilled from the journal below) / note
+ *   张伟 ──管理──▶ 赵敏                                note, ARCHIVED
+ *   张伟, 李娜 ──参与(参加)──▶ 架构评审                  note
+ *   赵敏 ──管理(负责)──▶ 数据平台                       note, created_at 2020
+ *   周杰, 陈静                                          note, NO edge (fact-level AND only)
+ *   钱伟, 孙丽                                          note, NO edge, created_at 2020
+ * ```
+ *
+ * `zhang-zhao` is archived AFTER its edge is written, which is the state the reader must hide.
+ *
+ * `zhang-wang` is the corpus's JOURNAL, and it states the same relation the note `wang-note`
+ * distils — that pair is STRUCTURED_RELATIONS §一's promotion rule in fixture form, and it is what
+ * makes the `kind` dimension mean something: the journal keeps its `triples` and produces NO edge,
+ * so `kind: "journal"` cannot answer a relation question, while the note that carries the stable
+ * fact can. (Before Phase 5c both rows were one journal fact with an edge; the graph is note-only
+ * now, so the relation moved to the note it belongs to.)
+ *
+ * The fact-level AND stage (§7.9) reads `fact_entities`, not `edges`, and that is exactly why
+ * `zhang-wang` (the journal, no edge), `note-consensus` and `old-pair` (notes whose text produced
+ * no relation) are in the corpus: they are the rows a graph-only answer would silently miss.
+ */
+export declare const RELATION_GOLD_FACTS: readonly RelationGoldFact[];
+/** An entity alias registered through the production entry point (explicit, never inferred). */
+export declare const RELATION_GOLD_ALIASES: readonly {
+    alias: string;
+    canonical: string;
+}[];
+/**
+ * The labelled queries.
+ *
+ * 17 relation questions, 9 fact-level AND questions, 16 negative controls, 1 exact-precedence probe
+ * (STRUCTURED_RELATIONS §四 moved the `kind: "journal"` relation question into the negative set: a
+ * journal produces no edge, so the layer filter can only answer with fuzzy). The breakdown is what
+ * makes the report diagnosable: a route-accuracy regression can be read per category, and the
+ * negative controls are the half that catches a planner that guesses.
+ */
+export declare const RELATION_GOLD_QUERIES: readonly RelationGoldQuery[];
+/** `titles` must keep answering the title index, never the planner. */
+export declare const RELATION_GOLD_TITLE_CHECKS: readonly RelationGoldTitleCheck[];
+/** The runtime surface the fixture needs (the real `AvantfRuntime` satisfies it). */
+export type RelationGoldRuntime = Pick<AvantfRuntime, 'db' | 'remember' | 'recall' | 'admin' | 'memory'>;
+/** Result of seeding: fact key → `fact_id`. */
+export type RelationGoldIds = Readonly<Record<string, number>>;
+/**
+ * Seed the corpus into an EMPTY store through the production write path.
+ *
+ * Order is load-bearing: every fact is written first (so text extraction has run and the FTS rows
+ * exist), then explicit edges replace what the extractor produced, then the clock/alias/archive
+ * adjustments are applied. Archiving last is what makes `zhang-zhao` a fact whose edge EXISTS but
+ * must not be walkable — the exact state the reader's active filter is for.
+ *
+ * @param rt - a runtime on a throwaway database.
+ * @returns fact key → id, for expectations that name facts.
+ */
+export declare function seedRelationGold(rt: RelationGoldRuntime): Promise<RelationGoldIds>;
+/** One query's measured route + answer. */
+export interface RelationGoldRow {
+    id: string;
+    query: string;
+    category: RelationGoldCategory;
+    expected_mode: RelationGoldMode;
+    mode: RelationGoldMode;
+    /** What the planner decided BEFORE any read (`null` = neither planner formed a question). */
+    plan: 'one-hop' | 'reverse' | 'two-hop' | 'facts' | null;
+    /**
+     * For a fuzzy answer: why no structured stage answered (diagnosis, not a failure). `no-fact`
+     * means the fact-level plan formed but no active fact mentions every entity; `no-path` means the
+     * relation plan formed but the graph had no walk; `planner-refused` means neither did.
+     */
+    fallback: 'planner-refused' | 'no-fact' | 'no-path' | null;
+    expected_facts: string[];
+    returned_facts: string[];
+    missing_facts: string[];
+    extra_facts: string[];
+    fact_precision: number | null;
+    fact_recall: number | null;
+    paths_expected: number | null;
+    paths_returned: number | null;
+    path_matches: number | null;
+    path_precision: number | null;
+    path_recall: number | null;
+    pass: boolean;
+    failure: string | null;
+}
+/** Per-category roll-up. */
+export interface RelationGoldCategoryRow {
+    total: number;
+    passed: number;
+    route_accuracy: number;
+}
+/** The whole report. `failures` is what a reviewer reads when `pass` is not 1. */
+export interface RelationGoldReport {
+    rows: RelationGoldRow[];
+    title_checks: {
+        id: string;
+        query: string;
+        mode: 'exact' | 'fuzzy';
+        passed: boolean;
+        expected_facts: string[];
+        returned_facts: string[];
+    }[];
+    summary: {
+        total: number;
+        passed: number;
+        route_accuracy: number;
+        relation_queries: number;
+        relation_answered: number;
+        relation_route_accuracy: number;
+        facts_queries: number;
+        facts_answered: number;
+        facts_route_accuracy: number;
+        negative_queries: number;
+        negative_fallback_rate: number;
+        exact_queries: number;
+        exact_answered: number;
+        plan_formed: number;
+        plan_rate: number;
+        /** Relations only: `path_matches / paths_returned`, and `path_matches / paths_expected`. */
+        path_precision: number | null;
+        path_recall: number | null;
+        /** Relations only: fact-set precision/recall over evidence. */
+        fact_precision: number | null;
+        fact_recall: number | null;
+        /** Fraction of ALL queries the store answered with fuzzy (diagnosis of the middle layer). */
+        fuzzy_fallback_rate: number;
+        titles_total: number;
+        titles_passed: number;
+        by_category: Record<string, RelationGoldCategoryRow>;
+        failures: string[];
+    };
+}
+/**
+ * Evaluate the whole gold set against one seeded runtime.
+ *
+ * Both planners are invoked SEPARATELY from the store's answer — the relation planner through the
+ * same `memory.graphReader(filter)` the store uses in `relationPage`, the fact-level planner through
+ * `memory.factEntitiesIn` — so the report can distinguish "the planner refused" from "the planner
+ * planned and the read found nothing". That distinction is the point of a routing metric: both fall
+ * back to fuzzy, but only one of them is a coverage gap.
+ *
+ * @param rt - the runtime seeded by {@link seedRelationGold} (or an equivalent fixture).
+ * @param ids - fact key → id returned by the seeder.
+ */
+export declare function evaluateRelationGold(rt: RelationGoldRuntime, ids: RelationGoldIds): Promise<RelationGoldReport>;

package/lib/engine/mem/eval/write_metrics.d.ts

@@ -22,7 +22,7 @@
  * it in the text looks natural and is a trap: the token ends up inside the subject/predicate/
  * object the detector parses, and the case silently stops exercising the signal it exists for
  * (measured: an in-text token suppressed the polarity conflict in 4 of 5 placements). A label
- * the store never interprets — `category` — is stable across extractor changes.
+ * the store never interprets — the fact text's own label — is stable across extractor changes.
  */
 /** What a case is about. `expect_action` is structural only; `live` is content only. */
 export interface WriteCase {

package/lib/engine/mem/facts_io.d.ts

@@ -1,4 +1,4 @@
-import { EXPORT_STATUSES, type ExportStatus, type RememberRequest } from '../mem-contract/index.js';
+import { EXPORT_STATUSES, type ExportStatus, type MemoryKind, type RememberRequest } from '../mem-contract/index.js';
 /**
  * The runtime slice these flows actually touch.
  *
@@ -21,15 +21,18 @@ export interface FactsIoRuntime {
 /** The document's discriminator. A file without it is not an export of this tool. */
 export declare const FACTS_EXPORT_FORMAT = "avantf-mem-facts";
 /**
- * The version THIS build writes: 2 (v1 + the facts columns v1 did not carry).
+ * The version THIS build writes: 5 (v4's `title` plus the note-only `relations`).
  *
- * Versions are additive by design: v2 adds OPTIONAL fields, so a v1 document is still the same
- * shape minus the new keys. A version outside {@link FACTS_EXPORT_VERSIONS} must be refused, never
- * guessed at.
+ * Versions are additive by design: v2/v3/v4/v5 each add OPTIONAL fields, so an older document is the
+ * same shape minus the new keys. A version outside {@link FACTS_EXPORT_VERSIONS} must be refused,
+ * never guessed at.
  */
-export declare const FACTS_EXPORT_VERSION = 2;
-/** A version this build can READ. v1 documents are what users already have on disk. */
-export declare const FACTS_EXPORT_VERSIONS: readonly [1, 2];
+export declare const FACTS_EXPORT_VERSION = 5;
+/**
+ * A version this build can READ. v1–v4 documents are what users already have on disk, and a v5
+ * document adds only the OPTIONAL `relations` field — so all five parse into the same type.
+ */
+export declare const FACTS_EXPORT_VERSIONS: readonly [1, 2, 3, 4, 5];
 /** The version literal, so a parsed document can say which field set it came from. */
 export type FactsExportVersion = (typeof FACTS_EXPORT_VERSIONS)[number];
 /**
@@ -54,7 +57,21 @@ export interface ExportedFact {
     /** Source-local row id. For reports/debugging ONLY; content is the identity. */
     source_id: number;
     content: string;
-    category: string;
+    /** The memory layer (v3). ABSENT on a v1/v2 document, which carries `category` instead. */
+    kind?: MemoryKind;
+    /**
+     * v4: the journal title (JOURNAL_TITLE_SEARCH §7). ABSENT on a v1/v2/v3 document — those rows had
+     * no title column at all, and an import restores them as NULL rather than inventing one.
+     */
+    title?: string | null;
+    /** The old free-form label, kept for audit only; `null` when the row predates the migration. */
+    legacy_category?: string | null;
+    /**
+     * v1/v2 ONLY: the old free-form category. Read (and mapped) for backward compatibility, never
+     * written by this build — an export from a v10 source database still carries it, and a v1/v2
+     * document on disk is exactly that shape.
+     */
+    category?: string;
     status: string;
     created_at: string | null;
     updated_at: string | null;
@@ -93,11 +110,27 @@ export interface ExportedFact {
      */
     entities_version?: number | null;
     conflict_checked?: number | null;
+    /**
+     * v5: the relations the CALLER stated on this note (`edges.source = 'explicit'`), in insertion
+     * order. ABSENT on a v1–v4 document (those rows were written before the field existed) and on
+     * every `journal` row — a journal refuses relations by contract, so the key there would assert a
+     * relation set a journal cannot have.
+     *
+     * These are NOT the extracted (`svo`) edges: those are re-derived from `content`, while an
+     * explicit relation is the one graph fact the text does not contain. That is why it travels.
+     */
+    relations?: ExportedRelation[];
+}
+/** One caller-stated relation inside an export document (v5). */
+export interface ExportedRelation {
+    subject: string;
+    predicate: string;
+    object: string;
 }
 /** The single JSON document `export` writes (and `import`/`restore` read). */
 export interface FactsExportDocument {
     format: typeof FACTS_EXPORT_FORMAT;
-    /** The version the document was WRITTEN as (1 or 2); this build writes 2. */
+    /** The version the document was WRITTEN as (1, 2 or 3); this build writes 3. */
     version: FactsExportVersion;
     exported_at: string;
     source: {
@@ -274,6 +307,13 @@ export declare function parseFactsExport(text: string): FactsExportDocument;
  * Order of decisions per fact: archived → skipped_archived (v1 never revives); content already in
  * the target (or planned by an earlier row of this same document) → skipped_existing; otherwise the
  * store's add path runs. A row the store refuses is collected in `failed` and the loop continues.
+ *
+ * A v5 row's `relations` travel through that same add path, so the imported fact gets its declared
+ * relations as `source: 'explicit'` edges (normalized, name-gated, four-tuple deduped against the
+ * extracted ones). Two consequences worth knowing: a row that is SKIPPED as already-present keeps
+ * the target's own relation set (this is a content union, not a merge of graphs), and a `journal`
+ * row carrying relations is refused per row with {@link RELATIONS_NEED_NOTE} — that combination is
+ * unrepresentable, so it must be reported rather than silently stripped.
  */
 export declare function importFacts(rt: FactsIoRuntime, doc: FactsExportDocument, options?: ImportOptions): Promise<ImportReport>;
 /**

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

@@ -19,15 +19,19 @@ export * from './modelBootstrap.js';
 export * from './dispatch.js';
 export * from './trustHeartbeat.js';
 export * from './runtime.js';
+export * from './storage/index.js';
+export * from './interfaces/index.js';
+export { isSqliteStorageBackend, sqliteDriver, SqliteStorageBackend, SQLITE_CAPABILITIES } from './dbdrivers/sqlite/index.js';
+export { FAKE_CAPABILITIES, FakeStorageBackend, fakeDriver, isFakeStorageBackend, MockRemoteTransport, type MockRemoteTurnaround, type StorageTransport, type TransportRequestRecord, } from './dbdrivers/fake/index.js';
 export * from './store/memory.js';
-export * from './store/knowledge.js';
 export { normalizeWrite } from './store/common.js';
 export * from './facts_io.js';
 export * from './maintenance_paths.js';
 export * from './store/facts_restore.js';
 export * from './store/vector_repair.js';
 export * from './store/hybrid.js';
-export * from './store/source_picker.js';
 export * from './store/lexical.js';
 export * from './store/floors.js';
 export { registerSemanticBackend, registerVectorStore, type SemanticBackend, type VectorStore, } from '../mem-retrieval/index.js';
+export * from './store/relation_backfill.js';
+export { extractRelationCandidates, normalizeRelation, evaluateRelation, type RelationCandidate, type RelationEvaluation, type RelationExtractor, } from './relations/index.js';

package/lib/engine/mem/interfaces/capabilities.d.ts

@@ -0,0 +1,30 @@
+/**
+ * What a storage driver DECLARES it can do (docs/DB_DRIVER_LAYOUT.md §二).
+ *
+ * Capabilities are how the HAL stays honest about optional behaviour without a second interface per
+ * driver: a backend that cannot do full-text search says so once, here, instead of the store probing
+ * it with a query that fails. Adding a flag is a MINOR contract change (an old driver that does not
+ * know the flag simply does not declare it; the host must tolerate unknown flags).
+ *
+ * @module interfaces/capabilities
+ */
+export interface StorageCapabilities {
+    /** Async unit-of-work transactions (`LifecycleService.transaction`). */
+    transactions: boolean;
+    /** Content full-text search (`SearchIndex.searchContent`). */
+    fullText: boolean;
+    /** Title search (`SearchIndex.searchTitles` + the exact-title face). */
+    titles: boolean;
+    /** The relation graph (entities / triples / edges / graph reader). */
+    relations: boolean;
+    /**
+     * Persisted vector BLOBS (`facts.semantic_vector` / `hrr_vector`) and their inventory reads. The
+     * live vector INDEX is a retrieval concern resolved above the storage layer; this flag is about
+     * storing and reading the rows a driver owns.
+     */
+    vectors: boolean;
+    /** The backend applies its own schema migrations on open (`MigrationRunner`). */
+    migrations: boolean;
+    /** The contract is async (always `true` for contract major 1 — see `interfaces/version.ts`). */
+    async: true;
+}

package/lib/engine/mem/interfaces/common.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The storage HAL's async shape (DB-2).
+ *
+ * Every port method that touches stored state returns this: the in-process SQLite driver fulfils the
+ * contract by returning a plain value (it has no I/O to wait for), while a remote driver returns a
+ * promise. Callers ALWAYS `await`, so no store, no retrieval leg and no lifecycle caller has to know
+ * which kind of driver it holds — and a new driver never rewrites a call site.
+ *
+ * @module interfaces/common
+ */
+export type Awaitable<T> = T | Promise<T>;

package/lib/engine/mem/interfaces/errors.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The storage error boundary (DB-3).
+ *
+ * SQLite reports failures as a driver error object with a numeric `errcode`; PostgreSQL has SQLSTATE,
+ * an HTTP backend has status codes, and none of those belong above the port. The store has exactly
+ * three things it can usefully do with a failed read/write: retry (the backend is temporarily
+ * unavailable), report a conflict (a uniqueness/constraint rule refused the write), or fail (anything
+ * else). This module names those three, and `db/sqlite.ts` — the one place that sees a driver error —
+ * maps into them.
+ *
+ * WHAT THIS IS NOT: a replacement for the domain refusals. `TITLE_IMMUTABLE`, `RELATIONS_NEED_NOTE`
+ * and the other `Error`s the store throws are decisions about the caller's request, not backend
+ * failures; they stay plain and unchanged. Only errors that come out of the database layer are
+ * classified here.
+ *
+ * The messages are preserved verbatim (the classification is metadata), so every existing caller and
+ * test that asserts on a driver message keeps working.
+ *
+ * @module interfaces/errors
+ */
+/** What a caller can do about a failed storage operation. */
+export type StorageFailureKind = 'unavailable' | 'constraint' | 'corrupt' | 'unknown';
+/** A database-layer failure, classified so the boundary does not leak a driver's error shape. */
+export declare class StorageError extends Error {
+    readonly kind: StorageFailureKind;
+    constructor(message: string, kind: StorageFailureKind, options?: {
+        code?: string | number;
+        cause?: unknown;
+    });
+    /** The driver's own code, kept for a log line — never branched on above the adapter. */
+    readonly code?: string | number;
+    /** Whether the same call may succeed if repeated later (a lock timeout, a restarting server). */
+    get retryable(): boolean;
+}
+/** The backend is temporarily unable to serve (SQLite: `SQLITE_BUSY`/`SQLITE_LOCKED`). */
+export declare class StorageUnavailableError extends StorageError {
+    constructor(message: string, options?: {
+        code?: string | number;
+        cause?: unknown;
+    });
+}
+/** The backend refused the write because of one of its integrity rules. */
+export declare class StorageConstraintError extends StorageError {
+    constructor(message: string, options?: {
+        code?: string | number;
+        cause?: unknown;
+    });
+}
+/** The stored data cannot be read (SQLite: `SQLITE_CORRUPT`/`SQLITE_NOTADB`). */
+export declare class StorageCorruptError extends StorageError {
+    constructor(message: string, options?: {
+        code?: string | number;
+        cause?: unknown;
+    });
+}
+/** Whether a caught value is already one of ours (a second mapping must not wrap it again). */
+export declare function isStorageError(error: unknown): error is StorageError;
+/**
+ * Classify a driver failure into the storage vocabulary.
+ *
+ * Takes `unknown` because that is what a `catch` binds; anything already classified is returned
+ * untouched (mapping is idempotent), and a non-error value becomes a generic `StorageError` carrying
+ * its string form, so callers never have to re-check.
+ */
+export declare function mapStorageError(error: unknown): StorageError;

package/lib/engine/mem/interfaces/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The storage HAL contract (docs/DB_DRIVER_LAYOUT.md).
+ *
+ * Nothing in this directory may import `dbdrivers/`, `db/dao` or `node:sqlite`: these files are the
+ * vocabulary a driver implements and the store consumes, and they have to stay loadable in a host
+ * that has no SQLite at all.
+ *
+ * @module interfaces
+ */
+export * from './common.js';
+export * from './version.js';
+export * from './capabilities.js';
+export * from './migrations.js';
+export * from './repositories.js';
+export * from './search_index.js';
+export * from './errors.js';
+export * from './storage_backend.js';
+export * from './storage_driver.js';