@avantf/dsh-mem 0.6.4 → 0.8.0

package/lib/engine/mem/store/memory.d.ts

@@ -1,14 +1,18 @@
-import { type Config, type ContradictionRecord, type FactDetail, type FactPage, type FloorProfile, type RecallResult, type RememberResult, type SourceCoverage, type TrustDiagnostic, type ValidityCoverage, type VectorMigrationOutcome, type VectorMigrationProgress, type VectorSpaceHealth, type VectorsDiagnostic, type VectorsFixStoreReport } from '../../mem-contract/index.js';
+import { type Config, type ContradictionRecord, type FactDetail, type FactPage, type MemoryKind, type FloorProfile, type RecallResult, type RememberResult, type SourceCoverage, type StatusFilter, type TimeFilter, type MemorySearchResult, type RelationInput, type TitlesResult, type TrustDiagnostic, type ValidityCoverage, type VectorMigrationOutcome, type VectorMigrationProgress, type VectorSpaceHealth, type VectorsDiagnostic, type VectorsFixStoreReport } from '../../mem-contract/index.js';
 import type { SemanticBackend, VectorStore } from '../../mem-retrieval/index.js';
 import { ENTITY_SWEEP_BATCH, type EntitySweepReport } from './entity_sweep.js';
+import type { RestoreOptions, RestoreReport } from './facts_restore.js';
+import type { FactsExportDocument } from '../facts_io.js';
 import { DEFAULT_VECTOR_MIGRATION_BATCH, type VectorRepairTarget } from './vector_repair.js';
-import type { Db } from '../db/conn.js';
 import { type LexicalProbe } from './lexical.js';
 import { type FloorLeg } from './floors.js';
-import { type TriplePattern } from '../entities/extract.js';
-import { type Sig } from '../lifecycle/contradiction.js';
-import { type MaintenanceResult } from '../lifecycle/maintenance.js';
-import { type TickResult } from '../lifecycle/tick.js';
+import type { GraphReader } from '../../graph-recall/index.js';
+import type { RelationVocabulary, SurfaceMatch } from './relation_planner.js';
+import type { EdgeReextractReport, GraphCoverageReport } from '../interfaces/repositories.js';
+import type { Sig } from '../lifecycle/contradiction.js';
+import type { MaintenanceResult } from '../lifecycle/maintenance.js';
+import type { TickResult } from '../lifecycle/tick.js';
+import type { StorageBackend } from '../interfaces/storage_backend.js';
 /**
  * Result shapes live in `@avantf/mem-contract` (single source for tool/UI payloads); these
  * aliases keep the long-standing `@avantf/mem` export names working for consumers.
@@ -76,7 +80,7 @@ export interface ContradictionResolution {
 }
 export interface SearchInput {
     query: string;
-    category?: string;
+    kind?: MemoryKind;
     /**
      * P-08: restrict every leg to facts whose `fact_sources.ref` equals this value. Applied INSIDE
      * each leg's SQL (an `EXISTS` predicate, before its `LIMIT cap`), never as a post-fusion filter:
@@ -132,6 +136,24 @@ export interface SearchInput {
     recordStats?: boolean;
     /** P-01: attach per-leg evidence (`scores` / `final`) to the returned hits. Default false. */
     includeScores?: boolean;
+    /**
+     * Override `retriever.min_score` (`0` = off). The unified cross-store entry passes `0` and applies
+     * the floor once on the NORMALIZED merged pool (DESIGN §7); a direct store search leaves it absent.
+     */
+    minScore?: number;
+    /** Read-only probe (`AvantfRuntime.wouldFind`): no reinforcement, stats or model warm. */
+    probe?: boolean;
+    /**
+     * The caller's EXPLICIT time filter (D1-D5), normalized by `store/time_filter.ts` and applied
+     * INSIDE every leg's SQL. A HARD filter: a fact outside the window is not a candidate at all, so
+     * the leg caps and the fusion pool are filled from the window only. No `COALESCE` fallback across
+     * axes — an `event` filter never reads `created_at`.
+     *
+     * When present it REPLACES the implicit `retriever.time_window` leg (the text-parsed one): the
+     * caller has said exactly which window it means, and stacking a second, phrase-derived window on
+     * top would silently widen an explicitly narrowed question.
+     */
+    time?: TimeFilter;
 }
 /**
  * P-08 / P-13 write-side extras on `add` / `update`.
@@ -147,25 +169,97 @@ export interface FactWriteOptions {
     eventDate?: string;
     /** P-13: known end → `valid_to`, WITHOUT archiving the row. */
     validUntil?: string;
+    /**
+     * The journal title (JOURNAL_TITLE_SEARCH §2.2/§11.1). `undefined` = not given, `null` = "no
+     * title", a string = the (already normalized) title. On a revision an omitted title INHERITS the
+     * replaced row's, and an explicitly DIFFERENT one is refused — except for a row whose title is
+     * still NULL, which may be backfilled once, and except under {@link retitle}.
+     */
+    title?: string | null;
+    /**
+     * v17 / R3: the CONTROLLED way to correct a title inside a revision chain.
+     *
+     * With this flag the immutability rule steps aside for ONE write, and the title it replaces is
+     * recorded as an alias of the revision (`title_aliases`), so searches for the old handle still find
+     * the transaction. It requires an explicit new `title` and an existing fact to rewrite — a first
+     * `add` has no chain to correct — and it changes nothing about the rule afterwards: the next update
+     * that names a different title WITHOUT this flag is refused exactly as before.
+     *
+     * Deliberately not a free rename: the caller must say "I am correcting a handle", which is the
+     * difference between fixing a typo and silently renaming a transaction the caller merely thinks it
+     * is continuing (the merge branch keeps refusing a conflicting title for the same reason).
+     */
+    retitle?: true;
+    /**
+     * Enforce the MODEL-facing rule "a journal needs a title" (JOURNAL_TITLE_SEARCH §2.3/§11.2).
+     *
+     * Set ONLY by the model-facing tool boundary (`@avantf/mem`'s `runToolSpec`). The CLI, an import,
+     * a merge and the UI leave it off: legacy journals, old exports and scripts must keep working, and
+     * a store-wide rule would break them.
+     */
+    requireJournalTitle?: boolean;
+    /**
+     * STRUCTURED_RELATIONS §2: relations the CALLER states, written as edges of this revision.
+     *
+     * `journal` refuses a non-empty list outright ({@link RELATIONS_NEED_NOTE}). The list is passed to
+     * `persistFact`, which writes the explicit edges BEFORE the extracted ones so a relation the caller
+     * stated wins the four-tuple dedupe against the extractor's guess at the same relation.
+     *
+     * OMITTED VERSUS EMPTY. Omitting the field means "this write says nothing about relations" — a
+     * write that lands on an existing row (duplicate `add`, revive, unchanged-content `update`) leaves
+     * that row's explicit edges untouched. An EMPTY ARRAY means "this write declares none" and clears
+     * them, which is the only way to remove the last relation from a fact whose content did not
+     * change (no new revision is created, so `supersede` cannot delete the edge).
+     */
+    relations?: readonly RelationInput[];
+}
+/**
+ * The `mem_recall.titles` request (JOURNAL_TITLE_SEARCH §4/§11.4, RECALL_INTERFACE §2.3).
+ *
+ * Defaults are the action's documented ones — `status: 'active'`, `kind: 'journal'` — applied HERE
+ * rather than in the contract, because the contract leaves an omitted field absent and the engine
+ * owns what absence means. `offset`/`limit` page the EXACT (title-equal) result only; the fuzzy
+ * fallback is the engine's fixed shortlist.
+ */
+export interface TitleInput {
+    query: string;
+    kind?: MemoryKind;
+    status?: StatusFilter;
+    time?: TimeFilter;
+    offset?: number;
+    limit?: number;
+    includeExcerpt?: boolean;
+}
+/**
+ * The `mem_recall.search` request, after the engine's two-stage policy is applied to it
+ * (docs/RECALL_INTERFACE.md): the caller's `limit`/`offset` page the EXACT result, while the fuzzy
+ * fallback is fixed by the engine (`FUZZY_TOP_K` / `FUZZY_MIN_SCORE`), never by the caller.
+ *
+ * `query` is OPTIONAL (RECALL_INTERFACE §2.4): a call with only `time` is a PURE TIME window
+ * (`mode:"time"`), which never runs the literal/relation/fuzzy stages at all. An omitted `query`
+ * without a `time` is the caller's error, refused in {@link MemoryStore.searchMemory}.
+ */
+export interface MemorySearchInput extends Omit<SearchInput, 'query'> {
+    /** The literal query. Omitted = a pure time window (then `time` is required). */
+    query?: string;
+    /** The exact page's first row (default 0). Only read when the literal pass matches. */
+    offset?: number;
 }
 export declare class MemoryStore {
-    private readonly db;
     private readonly config;
     private readonly semantic;
     private readonly vstore;
     private readonly contradictions;
     private readonly facts;
+    private readonly relations;
     private readonly entities;
     private readonly triples;
     private readonly sources;
-    /**
-     * The tokenizer `facts_fts` was ACTUALLY built with, read from the database at open.
-     *
-     * Not `resolveFtsTokenizer()`: `CREATE VIRTUAL TABLE IF NOT EXISTS` never rebuilds an existing
-     * table, so a database created under another SQLite build keeps the tokenizer it was born with,
-     * and building MATCH expressions for the wrong one is silent zero recall (see `db/tokenizer.ts`).
-     */
-    private readonly ftsTokenizer;
+    private readonly searchIndex;
+    private readonly keyValue;
+    private readonly lifecycle;
+    /** The store's database path, used ONLY to name the vector index snapshot beside it. */
+    private readonly dbPath;
     /**
      * Identity object for the shared entity sweep's in-flight guard (`store/entity_sweep.ts`).
      *
@@ -179,9 +273,18 @@ export declare class MemoryStore {
      * derived state: nothing is lost when it resets, and the queue itself is in the database.
      */
     private conflictDrainCursor;
-    constructor(db: Db, config: Config, semantic: SemanticBackend, vstore: VectorStore, 
+    constructor(backend: StorageBackend, config: Config, semantic: SemanticBackend, vstore: VectorStore, 
     /** The store's database path, used ONLY to name the vector index snapshot beside it. */
     dbPath?: string);
+    /**
+     * The open-time pass, now an explicit step (DB-2).
+     *
+     * It used to run inside the constructor. A constructor cannot `await` a repository call, and
+     * silently skipping the pass on a backend that answers asynchronously would leave the clock
+     * unrepaired and the semantic index empty — so the composition root wires the store first and
+     * starts it here, in the order the comments below explain.
+     */
+    start(): Promise<void>;
     /**
      * One automatic trust/lifecycle pass (spec §5): advance the active-day clock
      * (when trust is enabled), run the tick, and evict archived/purged vectors from
@@ -189,7 +292,7 @@ export declare class MemoryStore {
      */
     trustTick(opts?: {
         budget?: number | null;
-    }): TickResult;
+    }): Promise<TickResult>;
     /**
      * Identity of the vector space this store currently writes into — the REPRESENTATION fingerprint
      * (`vectorSpaceId` + the backend's declared pooling/normalize/window/revision), not just the
@@ -221,14 +324,14 @@ export declare class MemoryStore {
      * The counts are the same two `VectorsDiagnostic` already separates (`stale` / `space_stale`); this
      * is the read model those surfaces use instead of the full diagnose pass.
      */
-    vectorSpaceHealth(): VectorSpaceHealth;
+    vectorSpaceHealth(): Promise<VectorSpaceHealth>;
     /**
      * {@link vectorSpaceHealth} plus the internal `legacy` split (how many `space_stale` rows predate
      * the representation fingerprint). Kept off the contract type so the public detection surface —
      * and every existing assertion on it — is unchanged; only the warning's wording uses it.
      */
     private vectorSpaceCounts;
-    add(content: string, category?: string, ttlDays?: number, opts?: FactWriteOptions): Promise<RememberResult>;
+    add(content: string, kind?: MemoryKind, ttlDays?: number, opts?: FactWriteOptions): Promise<RememberResult>;
     /**
      * Write-path contradiction detection (DESIGN §11): check the fact that was just
      * written against the corpus, then report its FULL open-conflict set.
@@ -255,18 +358,18 @@ export declare class MemoryStore {
     private warnIndexFailure;
     /** Best-effort semantic indexing: encode the fact and add it to the vstore. */
     private maybeIndexSemantic;
-    update(fact_id: number, content: string, category?: string, ttlDays?: number, opts?: FactWriteOptions): Promise<RememberResult>;
-    remove(fact_id: number, reason?: string): boolean;
-    archive(fact_id: number, reason?: string): boolean;
+    update(fact_id: number, content: string, kind?: MemoryKind, ttlDays?: number, opts?: FactWriteOptions): Promise<RememberResult>;
+    remove(fact_id: number, reason?: string): Promise<boolean>;
+    archive(fact_id: number, reason?: string): Promise<boolean>;
     /**
      * Bring an archived fact back (spec §2.6): a `forgot` fact is lifted to
      * `recall_floor` (otherwise the very next tick would re-archive it, R4), the
      * idle clock is refreshed (otherwise an `idle`-archived fact dies again, R18),
      * and `settle_clock` moves to now so the downtime is not charged.
      */
-    restore(fact_id: number): boolean;
-    helpful(fact_id: number): number | null;
-    unhelpful(fact_id: number): number | null;
+    restore(fact_id: number): Promise<boolean>;
+    helpful(fact_id: number): Promise<number | null>;
+    unhelpful(fact_id: number): Promise<number | null>;
     /**
      * Explicit feedback (spec §2.4). Pinned/archived rows only move `helpful_count`
      * (R7); otherwise the decay is settled first, then `±feedback_delta`, pin at the
@@ -274,40 +377,46 @@ export declare class MemoryStore {
      */
     private applyFeedback;
     /** Permanent-memory administration (spec §6). */
-    pin(fact_id: number): boolean;
-    unpin(fact_id: number): boolean;
+    pin(fact_id: number): Promise<boolean>;
+    unpin(fact_id: number): Promise<boolean>;
     /**
      * Trust/forgetting diagnostics (spec §6, R17/R24): the quota is PER FACT, so the
      * report exposes "facts that consumed quota today" and "total effective gains"
      * rather than a meaningless global remaining.
      */
-    trustDiagnose(): TrustDiagnostic;
-    get(fact_id: number): FactDetail | null;
+    trustDiagnose(): Promise<TrustDiagnostic>;
+    get(fact_id: number): Promise<FactDetail | null>;
     private triplesOf;
     /**
      * One page of facts, newest first.
-     * @param category - optional category filter.
+     * @param kind - optional kind filter.
      * @param status - `active` (default) or `archived`.
      * @param limit - page size.
      * @param offset - page offset (0-based).
      * @returns the page, the page size (`count`), the matching total, and whether
      * more rows remain after this page.
      */
-    list(category?: string, status?: string, limit?: number, offset?: number, 
+    list(kind?: MemoryKind, status?: string, limit?: number, offset?: number, 
     /** P-08: only facts whose `fact_sources.ref` equals this value (reverse provenance lookup). */
-    source?: string): FactPage;
+    source?: string, 
+    /**
+     * The caller's EXPLICIT time window (the same normalized filter `search` takes). It NARROWS the
+     * page: `total`/`truncated` count the window, and the page order stays `created_at DESC` (a list
+     * page is a listing, not a chronological walk along whichever axis was filtered).
+     */
+    time?: TimeFilter): Promise<FactPage>;
     /**
      * P-08 coverage over the ACTIVE corpus, for `admin stats`: the share of facts that can answer
      * "why do I remember this". Reported from day one so the field cannot quietly become a second
      * `mirror_source` (filled but meaningless).
      */
-    sourceCoverage(): SourceCoverage;
+    sourceCoverage(): Promise<SourceCoverage>;
     /** P-13 coverage over the ACTIVE corpus: the share of facts carrying an event time. */
-    validityCoverage(): ValidityCoverage;
-    countByStatus(): {
+    validityCoverage(): Promise<ValidityCoverage>;
+    countByStatus(): Promise<{
         active: number;
         archived: number;
-    };
+    }>;
     /** Run one incremental contradiction-detection pass; returns newly logged pairs. */
     /**
      * Drain the DURABLE pending queue, bounded by `budget`.
@@ -331,9 +440,9 @@ export declare class MemoryStore {
      *
      * A throw keeps the batch queued too — `checkMany` never returns, so nothing is stamped.
      */
-    drainConflicts(budget?: number): ConflictDrainReport;
+    drainConflicts(budget?: number): Promise<ConflictDrainReport>;
     /** {@link drainConflicts}, reduced to the pairs it logged (the `contradict_check` payload). */
-    checkContradictions(budget?: number): Sig[];
+    checkContradictions(budget?: number): Promise<Sig[]>;
     /**
      * One bounded conflict pass for {@link maintenance}, reduced to COUNTS.
      *
@@ -349,10 +458,10 @@ export declare class MemoryStore {
     /** List contradiction candidates (`resolved` 0 = open, 1 = closed with a recorded verdict). */
     listContradictions(opts?: {
         resolved?: number;
-        category?: string;
+        kind?: MemoryKind;
         threshold?: number;
         limit?: number;
-    }): ContradictionRecord[];
+    }): Promise<ContradictionRecord[]>;
     /**
      * Adjudicate one logged conflict — the outlet the detector never had.
      *
@@ -369,7 +478,7 @@ export declare class MemoryStore {
      * The verdict is recorded on this row either way: `archive()` short-circuits for a fact that
      * is already archived, and the row would otherwise stay open on a technicality.
      */
-    resolveContradiction(id: number, resolution: 'true_positive' | 'false_positive', loserFactId?: number): ContradictionResolution;
+    resolveContradiction(id: number, resolution: 'true_positive' | 'false_positive', loserFactId?: number): Promise<ContradictionResolution>;
     /**
      * Semantic-index health for the ACTIVE corpus (the only thing the index serves):
      *  - `missing`     active facts with no persisted vector at all;
@@ -383,7 +492,7 @@ export declare class MemoryStore {
      *                  upgraded past the space id) — usable bytes, incomparable scores.
      * `total`/`with_semantic` still describe the whole table (including archived).
      */
-    vectorsDiagnose(): VectorsDiagnostic;
+    vectorsDiagnose(): Promise<VectorsDiagnostic>;
     /**
      * ONE read+decode pass over the persisted vectors, shared by diagnose and fix
      * (the two methods used to re-scan and re-decode the same blobs 4-5× per call).
@@ -395,7 +504,7 @@ export declare class MemoryStore {
      * `semantic.auto_migrate`, the dry-run split and the drop-before-encode order — lives there once,
      * for both stores.
      */
-    vectorRepairTarget(): VectorRepairTarget;
+    vectorRepairTarget(): Promise<VectorRepairTarget>;
     /**
      * {@link classifyVectors} reduced to what the repair flow steps on: the counts, the ids to drop
      * (bounded by `limit`) and the decoded vectors that can go back into a lost live index.
@@ -458,6 +567,7 @@ export declare class MemoryStore {
     maintenance(): Promise<MaintenanceResult & {
         entities: EntitySweepReport;
         conflicts: ConflictSweepCounts;
+        edges: EdgeReextractReport;
     }>;
     /**
      * Re-extract the entity/triple rows of facts written by OLDER extraction rules (bounded).
@@ -487,6 +597,56 @@ export declare class MemoryStore {
      * selection (`facts.staleEntityRows`, ACTIVE facts only) and the per-fact write below.
      */
     reindexEntities(budget?: number): Promise<EntitySweepReport>;
+    /**
+     * Phase 2 (RELATIONAL_RECALL §4.3/R2): re-derive `edges` for facts written by an older edge
+     * extractor — the graph's counterpart of {@link reindexEntities}.
+     *
+     * Why an explicit entry point instead of only the write path: every database upgraded to v15 has
+     * `edges.extraction_version = 0` rows (the Phase 1 backfill's), and the alias/canonical rules of
+     * this phase are functions of the STORED triples — so the corpus can be brought to the current
+     * version without re-tagging a single fact. `all` re-derives every active fact with triples, which
+     * is what an operator runs after the curated vocabulary or the confidence floor changed (those do
+     * not bump the extractor version by themselves).
+     *
+     * `maintenance()` runs one bounded pass of it, so the graph becomes current the same way the entity
+     * stamp and the conflict queue do; the CLI/UI surface is Phase 5 (R7) work.
+     *
+     * It is ALSO where STRUCTURED_RELATIONS §四/§七's one-time cleanup happens: `db/graph.ts`'s pass
+     * deletes the edges of non-note facts before re-deriving, because a database written by a pre-5c
+     * build still carries journal edges. The delete is idempotent (0 rows once clean) and touches
+     * `edges` only — the facts and their `triples`, which the contradiction detector reads, stay.
+     */
+    reextractEdges(options?: {
+        budget?: number;
+        all?: boolean;
+    }): Promise<EdgeReextractReport>;
+    /**
+     * Phase 2 (§R2/§R6): what the graph actually covers, and why the rest is missing.
+     *
+     * Two ratios rather than one, because they answer different questions: `tripleCoverage` is how
+     * much of the active corpus yields any relation at all (the string extractor's reach), while
+     * `relationCoverage` is how much of THAT survives normalization and the confidence floor (the
+     * graph's precision policy). `samples` shows the refused triples with their reason, which is the
+     * failure-sample half of §4.3's "记录抽取覆盖率/失败样本".
+     */
+    graphCoverage(options?: {
+        samples?: number;
+        sampleFacts?: number;
+    }): Promise<GraphCoverageReport>;
+    /**
+     * Rebuild this library from an export document — the engine half of `avantf-mem restore <file>`.
+     *
+     * A THIN adapter on purpose: the empty-table rule, the insert order, the SQL and the report all
+     * live in `store/facts_restore.ts`, because this class is a hub and a rebuild of the whole facts
+     * table must not become another reason to grow it. What it contributes is the two things only the
+     * store has: the ONE write connection (so the restored rows are immediately visible to every
+     * reader here) and the derived-state entity sweep that runs after the commit.
+     *
+     * Reachable from `mem_admin restore_snapshot` (and from the CLI): after a real restore this
+     * method refreshes the live vector index and resets the conflict-drain cursor, so a host that
+     * rebuilt its library from a tool call answers from the NEW rows without a restart.
+     */
+    restoreFacts(doc: FactsExportDocument, options?: RestoreOptions): Promise<RestoreReport>;
     /**
      * A fact left the ACTIVE corpus: retire the open conflicts that name it, so
      * `contradict` never reports a pair whose revision is archived and repeated
@@ -495,20 +655,204 @@ export declare class MemoryStore {
      */
     private retireConflicts;
     /**
-     * Entities that co-occur with `entity` across ACTIVE facts, ranked by occurrence
-     * count. Archived (incl. superseded) facts are excluded — their entities are not
-     * part of the live graph.
-     */
-    related(entity: string, limit?: number, category?: string): {
-        entity: string;
-        count: number;
-    }[];
-    /** Two-hop traversal: subj -pred-> mid, mid -second_pred-> obj. Returns the second-hop facts. */
-    chain(subj: string, pred?: string, secondPred?: string, limit?: number): Promise<RecallResult>;
-    /** Facts whose entity set contains ALL given entities (AND-join). */
-    reason(entities: string[], limit?: number): Promise<RecallResult>;
-    /** Hybrid search over the memory corpus (semantic + FTS + entity Jaccard [+ HRR probe] via fusion). */
+     * Hybrid search over the memory corpus (semantic + FTS + entity Jaccard [+ HRR probe] via fusion).
+     *
+     * This is the FUZZY half of `mem_recall.search` (see {@link searchMemory}) — the relevance-ranked
+     * retrieval with the floors, the fused-score floor and the output budget. It is also the
+     * conditional hint's probe (`AvantfRuntime.wouldFind`) and the cross-store path's memory leg, so it
+     * stays a public store method even though the public tool no longer exposes its knobs.
+     */
     search(input: SearchInput): Promise<RecallResult>;
+    /**
+     * `mem_recall.search` — the ONE content retrieval (docs/RECALL_INTERFACE.md §2.2/§4,
+     * docs/RELATIONAL_RECALL.md §6, docs/GRAPH_RECALL_AND_SEMANTICS.md §7.9).
+     *
+     * Four stages, in this order and with this precedence:
+     *
+     *  1. EXACT: active facts whose content literally CONTAINS the query. A literal match ends the
+     *     pass — the answer is a page (`total`/`offset`/`limit`/`truncated`) of raw hits whose
+     *     `score` is the constant 1 (a literal hit, not a relevance number; RECALL_INTERFACE §5 says
+     *     the model must not read it as one). The pass runs only when the query is long enough to be
+     *     a literal answer at all AND the literal set is small enough to be one
+     *     (`store/recall_policy.ts`: `exactEligible` / `EXACT_MAX_TOTAL`).
+     *  2. FACTS, only when stage 1 matched nothing AND the query was a PURE multi-entity connection
+     *     ("张伟和李娜", no other meaningful token — `planFactQuery`): the ACTIVE facts that mention
+     *     EVERY named entity, paged at the FACT level. This is the fact-level AND over
+     *     `fact_entities`, so journal entries and notes without any relation edge are covered. An
+     *     empty page is NOT an answer — the pass returns `null` and the later stages run, which is
+     *     the same no-empty-answer rule the relation stage follows.
+     *  3. RELATION, only when the earlier stages did not answer AND `store/relation_planner.ts` formed
+     *     a complete plan: the graph walk whose paths answer the question. A plan that finds no path is
+     *     NOT an answer — the pass returns `null` and fuzzy runs, which is the documented fallback
+     *     ("无路径时不能返回空的 relation"). The caller's `kind`/`source`/`time` filters are handed
+     *     to the graph reader, so the path is walked over exactly the corpus the caller asked about.
+     *  4. FUZZY, only when no earlier stage answered: the hybrid retrieval, unchanged, with the
+     *     engine's fixed shortlist (`topK = 5`, `min_score = 0.5`). The caller's `limit`/`offset` page
+     *     the exact and facts results (and the relation page is capped by the graph's own limit) and
+     *     are NOT forwarded here: a five-item ranked shortlist has no page 2.
+     *
+     * A call with NO `query` skips all four stages and answers the pure time window instead
+     * ({@link timePage}, `mode:"time"`): the window is the whole question, so there is nothing to
+     * match, plan or rank.
+     *
+     * The exact, facts and relation passes reinforce the facts they return, exactly like the fuzzy
+     * pass does for its hits: all are recalls the caller actually reads. A caller that must stay
+     * read-only passes `track: false` (the conditional hint's probe does). Exact, facts, relation and
+     * time also honour the caller's output budget (their text is the caller's to bound).
+     *
+     * It does NOT emit a retrieval-health event. Those counters describe the retrieval PIPELINE
+     * (legs, fusion, semantic-live rate); none of an exact, facts, relation or time answer ran a leg,
+     * so counting them would report the semantic leg as degraded for a query that never asked it
+     * anything.
+     */
+    searchMemory(input: MemorySearchInput): Promise<MemorySearchResult>;
+    /**
+     * The pure time stage of {@link searchMemory} — `mem_recall.search` with no query (RECALL_INTERFACE
+     * §2.4). The window IS the question: no literal pass, no relation plan, no legs, nothing to rank.
+     *
+     * The order is the window's OWN axis, newest first (`db/dao/facts.ts#timeAxisColumn`), so "what
+     * happened that day" reads in the order it happened; `score` is the constant 1 exactly like the
+     * exact page's, because there is no relevance number here for the model to compare.
+     *
+     * It honours `kind`/`source`, pages with the same `offset`/`limit` (default 10, cap 50) and the
+     * same `max_tokens` budget as every other recall, and reinforces the rows it returns unless
+     * `track: false` — a window the caller reads is a recall like any other.
+     */
+    private timePage;
+    /**
+     * The literal stage of {@link searchMemory}, or `null` when it did not apply.
+     *
+     * `null` has four causes and they are deliberately not distinguished for the caller: the query is
+     * too short to be literal (`exactEligible`), it matched no active fact, the literal set is WIDER
+     * than a literal answer (`EXACT_MAX_TOTAL` — a common word's dozens of rows are a corpus scan, not
+     * a page), or it was blank. All four mean "the rest of the pipeline answers this".
+     */
+    private exactContentPage;
+    /**
+     * The FACT-level entity vocabulary for the fact-level AND stage
+     * (docs/GRAPH_RECALL_AND_SEMANTICS.md §7.9): entity surfaces linked to at least one ACTIVE fact
+     * through `fact_entities`, so journal entries and notes without a relation edge are visible.
+     *
+     * Public on the store but not on any tool/action (like {@link graphReader}): the gold evaluator
+     * plans the same question the stage answers, without going through `search`.
+     */
+    factEntitiesIn(text: string): Promise<SurfaceMatch[]>;
+    /**
+     * The FACTS stage of {@link searchMemory}, or `null` when it did not answer.
+     *
+     * `null` has three causes, deliberately not distinguished for the caller: the query is not a PURE
+     * multi-entity connection (`planFactQuery` refused it), the caller's `kind`/`source`/`time` filter
+     * leaves no fact mentioning every entity, or a named entity does not exist in the live corpus. All
+     * three mean "the next stage answers this": a facts result with zero rows is never returned,
+     * because `mode:"facts"` is a promise that a FACT page was found.
+     *
+     * Order inside the stage, and why:
+     *  - the plan is checked BEFORE the repository read: no conjunction, fewer than two entities or a
+     *    leftover meaningful token means no fact query at all;
+     *  - the explicit `time` filter is normalized here (before the read, after the plan), so a
+     *    malformed window is the caller's error exactly as it is in the exact page;
+     *  - the page is FACT-level (`total`/`offset`/`limit`/`truncated`), and the caller's output budget
+     *    only shortens `content` — dropping a row would make `total` disagree with the page;
+     *  - the returned facts are reinforced unless `track: false`, like every other recall the caller
+     *    actually reads.
+     */
+    private factPage;
+    /**
+     * The graph view over exactly the facts a search with these filters may read.
+     *
+     * This is the ONE way the store reaches `@avantf/graph-recall`: the planner's vocabulary
+     * (`entitiesIn` / `predicatesIn`), the walks, and — later, for evaluation — a gold-set harness all
+     * get the same reader, so none of them can accidentally walk the unfiltered corpus. The filter
+     * semantics live in `MemoryGraphReader` (active facts only; kind/source/time in SQL), not here.
+     *
+     * Public on the store but not on any tool/action: like `graphCoverage()`, it is an internal
+     * capability, not a public recall surface.
+     */
+    graphReader(filter?: {
+        kind?: MemoryKind;
+        source?: string;
+        time?: TimeFilter;
+    }): Promise<GraphReader & RelationVocabulary>;
+    /**
+     * The relation stage of {@link searchMemory}, or `null` when it did not answer.
+     *
+     * `null` has exactly two causes, and they are deliberately not distinguished for the caller
+     * (RELATIONAL_RECALL §6): the query is not a COMPLETE relation question (`planRelationQuery`
+     * refused it), or it is one and the graph has no path for it under the caller's filters. Both mean
+     * "fuzzy answers this" — a relation result with zero paths is never returned, because `mode:
+     * "relation"` is a promise that structure was found and every edge's fact is openable.
+     *
+     * ORDER INSIDE THIS STAGE, and why:
+     *  - the reader is built FIRST (through {@link graphReader}) and carries the caller's
+     *    `kind`/`source`/`time` filter, so both the vocabulary ("is this a known name") and the walks
+     *    see one consistent view. An invalid `time` therefore throws here exactly as it would in
+     *    `search` (the caller's error, not an empty answer);
+     *  - the plan is checked BEFORE any walk: no plan means no graph read beyond the cheap vocabulary
+     *    lookup;
+     *  - evidence is loaded from the paths' own `fact_id`s (`rowsByIds`, one query) and the output
+     *    budget is applied to it, never to the paths: shortening evidence text is allowed, dropping an
+     *    evidence row would break the invariant that every path's edges point at a returned fact.
+     */
+    private relationPage;
+    /**
+     * The facts behind a relation answer, in path order and deduplicated.
+     *
+     * `RelationEvidence` is NOT a `RecallHit`: a relation answer is not a ranked content match, so no
+     * `score` is produced here (there is nothing to rank it against) and the handle is `fact_id`, which
+     * every path edge also carries. Only ACTIVE rows can reach this point — the graph reader filters
+     * on `facts.status` before any edge is walked.
+     */
+    private relationEvidence;
+    /**
+     * Apply the caller's output budget (`max_tokens`) to relation evidence.
+     *
+     * The shared `applyOutputBudget` cannot be reused directly: its input type carries a `score`, and a
+     * relation answer deliberately has none (nothing ranks it). `fitToTokenBudget` itself never reads
+     * `score` — it walks the entries in the order it is given and can only SHORTEN text — so the rank
+     * below is a placeholder that is dropped before the values leave this function. Order is preserved,
+     * `truncated` is set exactly where the text was cut, and no evidence row is ever removed.
+     */
+    private budgetRelationEvidence;
+    /**
+     * Apply the caller's output budget (`max_tokens`) to a FACT page.
+     *
+     * Same reason as {@link budgetRelationEvidence}: `applyOutputBudget` is typed for hits (`text` +
+     * `score`) and a `FactEvidence` carries `content` and no score. `fitToTokenBudget` never reads the
+     * score, so the entry rides through as `{ …entry, text: content, score: 0 }` and the budgeted text
+     * goes back into `content`; a shortened row keeps its `fact_id` and carries `truncated: true`.
+     */
+    private budgetFactEvidence;
+    /**
+     * `mem_recall.titles` — the ONE title search (JOURNAL_TITLE_SEARCH §4/§11.4, RECALL_INTERFACE §2.3).
+     *
+     * It answers a different question from `search`: "which journal entries have this title / titles
+     * like these keywords", so the caller can read the candidates and decide whether the thing it is
+     * about to write belongs to an existing transaction. Consequences, all deliberate:
+     *
+     *  - EXACT first: `normalizeTitle(query)` compared with `=` (case-SENSITIVE: `DSH` and `dsh` are
+     *    two titles, §11.1) pages like `search`'s exact stage. Any title-equal row ends the pass;
+     *  - the FTS index it consults is `facts_title_fts`, never `facts_fts` — a title word that does not
+     *    occur in any content is invisible to {@link searchMemory} by design, and vice versa;
+     *  - the fuzzy ordering is computed on `facts.title` (exact > prefix > matched keywords > recency),
+     *    with bm25 only as a tie-break inside the FTS path; no `score` is returned at all, because a
+     *    title match is not a content-relevance number and the model must not compare the two;
+     *  - it is READ-ONLY: no `reinforce`, no `touchUsage`, no `retrieval_count` / `last_retrieved_at` /
+     *    trust change, in EITHER stage. Reading candidates is the common case (the caller may not write
+     *    at all), so treating it as a recall would let a few searches rewrite the dormancy clock of a
+     *    whole transaction;
+     *  - defaults follow the documented ones: `status='active'` (the current revision), `kind='journal'`.
+     */
+    titles(input: TitleInput): Promise<TitlesResult>;
+    /**
+     * Resolve a caller's `title` for a write (JOURNAL_TITLE_SEARCH §2.4/§11.1).
+     *
+     * Three-way by design: `undefined` stays "not given" so an update can inherit, `null` is the store's
+     * "no title" (a blank NOTE title normalizes to it), and a string is normalized. A blank JOURNAL
+     * title is refused rather than silently stored as NULL — the caller tried to give one, it just had
+     * no content. The title passes the same secret scan as the content because it is rendered into the
+     * UI and into the model's context.
+     */
+    private resolveWriteTitle;
     /**
      * This store's half of the shared orchestration (`store/hybrid.ts`): the legs, the text load, the
      * fact→hit mapping, and what to do with the hits the caller actually receives.
@@ -554,11 +898,9 @@ export declare class MemoryStore {
      */
     private timeWindowPath;
     /**
-     * The one fact→RecallHit mapper (kind/source_ref/entities shape lives here ONLY;
-     * chain/reason/ask/search all used to carry byte-identical copies, three of them
-     * with an N+1 entity load each). Facts have no knowledge-base taxonomy, so
-     * `domain`/`source` are null — that is what keeps a `domain`-filtered cross query
-     * from ever matching a memory hit.
+     * The one fact→RecallHit mapper (kind/source_ref/entities shape lives here ONLY; the exact page,
+     * the fuzzy search and the single-fact loader all go through it, so a hit cannot describe the same
+     * row two ways).
      */
     private factHits;
     /**
@@ -566,10 +908,10 @@ export declare class MemoryStore {
      * the trust bonus is quota-limited (per fact, calendar 24h), zero-gain recalls
      * cost nothing, and a recall can never push a fact to permanent (D11).
      *
-     * Public so `runtime.query` can reinforce ONLY the merged hits it actually
-     * returns, after the router's kind/domain/source filtering (R5/R21).
+     * Public so a caller that post-filters a search result can reinforce ONLY the facts it actually
+     * returns (R5/R21).
      */
-    reinforce(ids: number[]): void;
+    reinforce(ids: number[]): Promise<void>;
     /**
      * Load the persisted retrieval-health counters, and write the current ones back.
      *
@@ -583,7 +925,7 @@ export declare class MemoryStore {
      * Called by `maintenance()` and by the runtime on shutdown — NOT from a `close()`, because the
      * runtime owns the database handle.
      */
-    flushHealth(): void;
+    flushHealth(): Promise<void>;
     /** Retrieval bookkeeping: `retrieval_count` + the "last used" clock (spec §2.5). */
     private touchUsage;
     /**
@@ -592,7 +934,7 @@ export declare class MemoryStore {
      * `onVector` publishes the vector this leg actually used, so the relaxed retry pass can reuse it
      * instead of re-encoding (performance review §7.7 / P8). The flow is shared
      * (`store/legs.ts#semanticLeg`); the only memory-specific piece is the filter — the vstore has no
-     * notion of status/category/source, so candidates go through the DB and archived/purged facts,
+     * notion of status/kind/source, so candidates go through the DB and archived/purged facts,
      * other categories and other sources never leak into the leg.
      */
     private semanticPath;
@@ -602,23 +944,17 @@ export declare class MemoryStore {
      * the probe even when surface text shares no FTS trigrams.
      */
     private hrrPath;
-    /**
-     * Direction-aware question answering over SPO triples.
-     * Parse the query into a TriplePattern, match triples by the filled slots
-     * (unfilled = wildcard), and rank the owning facts. Direction is preserved by
-     * the triple's (subj, pred, obj) roles.
-     */
-    ask(query: string, limit?: number): Promise<RecallResult>;
-    /** Direction-aware answer over SPO triples from an explicit pattern. */
-    askByPattern(pattern: TriplePattern, limit?: number): Promise<RecallResult>;
     /** One-shot flag for the probe fallback warning (see `hrrPath`). */
     private hrrFallbackWarned;
     /**
-     * Sync relevance probe for the plugin's conditional hint (DESIGN §12): how many of `text`'s
-     * terms this store already holds. `store/lexical.ts` carries why it is lexical rather than
-     * semantic, why it must be synchronous, and how the bar itself was measured.
+     * Diagnostic term-count probe: how many of `text`'s terms this store already holds.
+     *
+     * NOT the conditional hint's decision any more — that is `AvantfRuntime.wouldFind`, which runs the
+     * retrieval pipeline itself (DESIGN §12). Kept as the lexical oracle `test/retrieve.spec.ts` uses
+     * to show what the old short-circuit would have answered (a lexical hit can fail `min_score`).
+     * `store/lexical.ts` carries how the two-term bar was measured.
      */
-    lexicalProbe(text: string, stopAt?: number): LexicalProbe;
+    lexicalProbe(text: string, stopAt?: number): Promise<LexicalProbe>;
     private ftsPath;
     /**
      * Entity leg over the precomputed candidate set (see `searchLegs`): the candidates are the facts
@@ -630,14 +966,18 @@ export declare class MemoryStore {
      * the generic-word filter keeps the wider denominator from dragging the corpus in. The fact set is
      * read per candidate and the score is recomputed here even though the DAO ordered by it, so one
      * formula stays in charge (the DAO's `total` tie-break only orders equal scores).
+     *
+     * The candidate also has to clear the rarity-weighted evidence bar (`entityEvidenceFloor`), which
+     * is per candidate because it depends on which anchors the candidate shares; that is why this
+     * method returns the drops instead of letting `runner.scored` count them.
      */
     private jaccardPath;
     /**
      * Insert (or resolve to) a fact row.
      *
-     * `category` / `ttlDays` are `undefined` when the CALLER specified nothing — the
+     * `kind` / `ttlDays` are `undefined` when the CALLER specified nothing — the
      * distinction is load-bearing. A duplicate-content hit must not clobber the existing
-     * row's values with the insert defaults: re-adding a fact without a category used to
+     * row's values with the insert defaults: re-adding a fact without a kind used to
      * reset it to `general`, and reviving an archived one silently cleared an explicit TTL.
      * The rule for all three branches is therefore: an explicitly provided value lands, an
      * omitted one keeps what the row already has, and a brand-new row falls back to the
@@ -673,6 +1013,70 @@ export declare class MemoryStore {
      */
     private normalizeTriples;
     private insertTriples;
+    /**
+     * Phase 2 (RELATIONAL_RECALL §4.3/R2): the SAME extracted triples, resolved onto IDs and written to
+     * `edges` — the write path's half of the graph. Called from every branch that writes triples (fresh
+     * insert, duplicate/merge, revive, and the entity sweep), always inside the surrounding transaction,
+     * so `triples` and `edges` describe one extraction and never two vintages.
+     *
+     * `kind` is the layer the ROW carries, and it is the STRUCTURED_RELATIONS §四 boundary: a `journal`
+     * entry keeps its `triples` (the contradiction detector reads them) but produces NO edges. The
+     * check uses the row's actual kind rather than the request's, because a duplicate-content write
+     * lands on a DIFFERENT row — and the graph's rule is about that row, not about what was asked.
+     *
+     * Best-effort by contract: §4.3's "关系抽取失败不阻塞写入". A throw here is logged and swallowed —
+     * the fact, its triples and its content index are already written, and the graph can be re-derived
+     * from those triples at any time (`reextractEdges`). That is also why this is a `try` around a
+     * single call rather than a per-triple loop: the policy already refuses bad triples individually.
+     */
+    private insertEdges;
+    /**
+     * Re-derive one fact's edges under the current policy — the graph half of "the row's layer/status
+     * changed" (STRUCTURED_RELATIONS §五/§七; `db/graph.ts#rebuildEdgesForFact`).
+     *
+     * Called from the states where the incremental write cannot be right: an ARCHIVED row re-entering
+     * the active set (`restore()` and the revive branch of {@link persistFact}) and a note whose
+     * `keepKind` flips to journal on the duplicate path (a journal keeps no edges). Both call sites
+     * are best-effort by the same contract `insertEdges` has (§4.3: a graph write never fails a fact
+     * write), but the rebuild itself is one savepoint: a throw leaves the row's previous edges in
+     * place instead of half-deleted ones.
+     */
+    private rebuildGraph;
+    /**
+     * STRUCTURED_RELATIONS §2: write the relations the CALLER stated, before the extracted ones.
+     *
+     * Order matters for exactly one reason. Both writers end in `INSERT OR IGNORE` on
+     * `edges(fact_id, subject_id, predicate_id, object_id)`, so when the same relation is both stated
+     * and extracted, whichever runs FIRST owns the row. The caller's statement is the stronger claim
+     * (confidence 1, `source: 'explicit'`), so it goes first and the extractor's guess becomes the
+     * duplicate — the edge keeps the explicit provenance the caller asked for.
+     *
+     * NOT best-effort, unlike {@link insertEdges}: an explicit relation is a request, not a guess. A
+     * throw rolls the whole write back (`db.transaction`), which is also why the caller validated the
+     * list before the transaction — so this path only fails when the DATABASE is broken, and then the
+     * caller must hear about it rather than get a fact whose relations silently do not exist.
+     *
+     * `journal` is refused upstream (`store/explicit_relations.ts`); the guard here is for the merge
+     * branch, where the surviving row's own kind decides and a note request can land on a journal row.
+     *
+     * `explicit === undefined` means "this write said nothing about relations" and leaves the row's
+     * set alone; an EMPTY array means "this write declares none" and drops what is there. That second
+     * case is the only way an unchanged-content update can remove the last relation (the row is not
+     * superseded, so nothing else would delete that edge).
+     */
+    private insertExplicitEdges;
+    /**
+     * Phase 2 (§4.1): record the EXPLICIT alias statements in this write's text.
+     *
+     * Only cue-bearing forms (`A（又名 B）`, `A 简称 B`, …) and only when the left-hand name is one the
+     * extractor recognised as an entity — see `relations/normalize.ts`. Two similar names, or two
+     * frequent ones, never merge; that is the one rule §4.1 makes non-negotiable.
+     *
+     * Best-effort like the edge write: an alias is a refinement of the graph, never a precondition of
+     * the fact. A learned alias is logged at INFO because an automatic merge is exactly the kind of
+     * decision an operator must be able to see and undo (`DELETE FROM entity_aliases WHERE alias = ?`).
+     */
+    private recordAliases;
     private getRow;
     private entityNames;
     private entityBags;