@avantf/dsh-mem 0.6.4 → 0.8.0

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

@@ -0,0 +1,49 @@
+/** A query needs this many CJK characters for a literal content match to mean anything. */
+export declare const EXACT_MIN_CJK = 2;
+/** …or this many Latin letters (case-folded for the comparison). */
+export declare const EXACT_MIN_LATIN = 3;
+/** The default page of an exact result, and its hard cap. */
+export declare const EXACT_DEFAULT_LIMIT = 10;
+export declare const EXACT_MAX_LIMIT = 50;
+/**
+ * The widest literal match set that still counts as an ANSWER (P1-2, REVIEW-2026-10-24).
+ *
+ * A ten-character sentence that occurs verbatim in a few facts is a literal answer; a common word
+ * (`mem`, `插件`) that occurs in dozens is a corpus scan, and a page of it says nothing a fuzzy
+ * shortlist would not say better. So the literal stage refuses a `total` above this bound and lets
+ * the rest of the pipeline answer: the relation stage may still plan it, otherwise fuzzy runs.
+ *
+ * The number is the page cap's neighbourhood (10 default, 50 max): 20 literal matches is already
+ * "everything that mentions this word", which is not what "字面命中" promises.
+ */
+export declare const EXACT_MAX_TOTAL = 20;
+/** The fuzzy shortlist: how many rows, and the fused-score floor they must clear. */
+export declare const FUZZY_TOP_K = 5;
+export declare const FUZZY_MIN_SCORE = 0.5;
+/** How many Han characters `text` contains. */
+export declare function cjkCount(text: string): number;
+/** How many Latin letters `text` contains. */
+export declare function latinCount(text: string): number;
+/**
+ * Is this (already normalized) query long enough to trigger the literal pass?
+ *
+ * A mixed query passes on EITHER bar: 「DSH 插件」 is 2 CJK (and 3 Latin) and is a real phrase, while
+ * 「a记忆」 is one Latin and one CJK and is not a phrase in either sense.
+ */
+export declare function exactEligible(query: string): boolean;
+/**
+ * The query a literal comparison uses: well-formed + NFC (`normalizeWrite`, the store's one write
+ * normalization) then trimmed. Trimming is what keeps a pasted `" 迁移 "` from missing its row.
+ */
+export declare function normalizeExactQuery(query: string): string;
+/**
+ * The page an exact result reports, from the caller's `offset`/`limit`.
+ *
+ * Both are clamped rather than refused: they are pagination, not a filter, and a caller asking for
+ * page 100 of a 3-row result should get an empty page with an honest `total`, not an error. The cap
+ * is the contract's own (max 50) — a page bigger than that is answered with 50.
+ */
+export declare function exactPage(offset: number | undefined, limit: number | undefined): {
+    offset: number;
+    limit: number;
+};

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

@@ -0,0 +1,210 @@
+/**
+ * Controlled relation backfill for the LEGACY corpus (docs/RELATION_BACKFILL.md §七, Phase 7).
+ *
+ * The problem this file solves is a REVIEW problem, not an extraction one. Phase 5b measured that
+ * live notes are mostly not statements, so a deterministic extractor cannot reach them without
+ * loosening the name/statement gates — which the plan refuses (§四). Instead a human/agent READS the
+ * notes, writes candidate relations with the exact text that says so, and an operator approves them.
+ * This module is the deterministic, auditable machinery around that loop:
+ *
+ *   1. `proposeRelations` — read-only selection of the notes that need review, as a portable JSON
+ *      document. It never calls a model and never writes a row.
+ *   2. `parseRelationProposal` — the strict reader for a reviewed file. Strict because the file is
+ *      HAND-EDITED: a silently ignored typo (`aproved: true`) would look like a reviewed entry that
+ *      the tool refused for another reason.
+ *   3. `applyRelationProposal` — per-entry validation + write through the EXISTING `remember.update`
+ *      (content passed back verbatim, so the row is not superseded and `fact_id` is preserved).
+ *      One bad entry is reported, never fatal: a batch of 50 reviewed notes must not be lost to the
+ *      one entry whose source text changed under the reviewer.
+ *   4. `relationCoverage` — how much of the active NOTE corpus carries caller-stated relations.
+ *
+ * WHAT THIS FILE DELIBERATELY DOES NOT DO:
+ *
+ *  - **No LLM.** The proposal generator is external by contract (§7.2); this module cannot create a
+ *    relation from fact text and would not be allowed to apply one unattended.
+ *  - **No second write path.** `apply` calls `MemoryStore.update` with the UNCHANGED content. The
+ *    store's duplicate-content branch lands on the same row, so `fact_id` survives and the explicit
+ *    edge set is replaced in place (STRUCTURED_RELATIONS §5). Riding that path has one visible cost:
+ *    the write counts as a duplicate ASSERTION, so `assert_count` moves by one per applied entry.
+ *  - **No journal.** A journal is an episode, not a stable fact: `propose` never emits one, the
+ *    document parser refuses a `kind: "journal"` entry, and `apply` re-checks the LIVE row's kind
+ *    (a proposal can be stale, and a note can be edited into a journal in between).
+ *  - **No forged evidence.** Every relation's `evidence` must be a contiguous substring of the live
+ *    content, and the live content must still be the one the proposal recorded. This is the audit
+ *    trail §一 asks for: "每一条回填边必须能回查 fact_id + 原文证据".
+ *  - **No recall surface change.** Nothing here is reachable from `mem_recall`; the CLI `relations`
+ *    command is the only caller today.
+ *
+ * ONE INHERITED WRINKLE, stated so it is not mistaken for a bug here: the edge writer is
+ * `INSERT OR IGNORE` on `(fact_id, subject, predicate, object)`. When the text extractor ALREADY
+ * derived the same relation from the note's content (`source: 'svo'` / `'pattern'`), the explicit
+ * write is the duplicate and the edge keeps its derived source — the relation is in the graph and
+ * answers questions, but it does not become `explicit`. `apply` notices the shortfall (it counts the
+ * fact's explicit edges after the write) and reports the entry as `failed` with that explanation
+ * rather than claiming a success it cannot see. `--dry-run` cannot detect it, because the conflict
+ * only exists once the write runs; that asymmetry is documented on {@link RelationApplyReport}.
+ *
+ * @module store/relation_backfill
+ */
+import { type FactRelation } from '../../mem-contract/index.js';
+import type { Db } from '../db/port.js';
+import { NOTE_KIND } from './kinds.js';
+import type { MemoryStore } from './memory.js';
+/** The proposal document's version. Bump when the SHAPE changes, and keep the parser strict. */
+export declare const RELATION_PROPOSAL_VERSION = 1;
+/** Notes one `propose` run returns when the caller gives no `--limit` (§7.2's example page). */
+export declare const DEFAULT_PROPOSAL_LIMIT = 20;
+/** One relation a reviewer wants written, with the text that says it. */
+export interface ProposedRelation {
+    subject: string;
+    predicate: string;
+    object: string;
+    /** A CONTIGUOUS fragment of the fact's content. Checked against the live row, never trusted. */
+    evidence: string;
+    /** Reviewer's own ordering hint; never a hidden gate (the write path owns every gate). */
+    confidence?: number;
+}
+/** One note in a proposal file: what the reviewer saw, what it proposes, and whether it is approved. */
+export interface ProposedFact {
+    fact_id: number;
+    /** Notes only — the layer boundary is part of the document's shape, not a runtime check alone. */
+    kind: typeof NOTE_KIND;
+    /** The content the reviewer read. Compared with the live row before any write (staleness guard). */
+    content: string;
+    /**
+     * The explicit relations the reviewer saw on this note (`[]` for the untouched notes `propose`
+     * selects). `apply` requires it to EQUAL the live set: a proposal is a compare-and-swap, so two
+     * reviewers (or a reviewer and an `edit --relation`) cannot silently overwrite each other.
+     */
+    existing_relations: FactRelation[];
+    relations: ProposedRelation[];
+    /** Defaults to `false` — only an explicit `true` is written (§7.3). */
+    approved: boolean;
+}
+/** The portable proposal file (`version` 1). */
+export interface RelationProposalDocument {
+    version: typeof RELATION_PROPOSAL_VERSION;
+    /** When the file was generated. Absent on a hand-written file; never interpreted as a TTL. */
+    generated_at?: string;
+    facts: ProposedFact[];
+}
+/** Options for {@link proposeRelations}. */
+export interface RelationProposeOptions {
+    /** Page size; defaults to {@link DEFAULT_PROPOSAL_LIMIT}. */
+    limit?: number;
+    /** The clock the document records — injectable so a test can pin `generated_at`. */
+    generatedAt?: Date;
+}
+/** Read-only coverage of caller-stated relations over the ACTIVE note corpus. */
+export interface RelationCoverageReport {
+    /** Active notes — the denominator, and the only layer a relation may live on. */
+    active_notes: number;
+    /** Active notes carrying at least one `source: 'explicit'` edge. */
+    notes_with_explicit_relations: number;
+    notes_without_explicit_relations: number;
+    /** Explicit edge rows on active notes (a note may carry several). */
+    explicit_relations: number;
+    /** `notes_with_explicit_relations / active_notes`, rounded to three decimals. */
+    coverage: number;
+    /**
+     * Explicit edges on a NON-note row. Must be `0`: a journal has no business in the graph (§四), so
+     * a non-zero value means some writer bypassed the layer rule and the graph now contains episodes.
+     */
+    journal_relations: number;
+}
+/** What one proposal entry came to. */
+export type RelationApplyStatus = 
+/** Written; the fact's explicit set was replaced by the proposal's (and verified after the write). */
+'applied'
+/** `--dry-run`: every check passed, nothing was written. */
+ | 'planned'
+/** Not approved — the reviewer left it out, so it is not this run's business. */
+ | 'skipped'
+/** Refused before any write: journal / archived / stale content / forged evidence / bad relation. */
+ | 'rejected'
+/** The write itself failed, or the explicit set the store kept is not the one the proposal stated. */
+ | 'failed';
+/** Per-entry outcome. `reason` is always populated for `skipped`/`rejected`/`failed`. */
+export interface RelationApplyEntryResult {
+    fact_id: number;
+    status: RelationApplyStatus;
+    /** How many relations the entry proposed (what was, or would be, written). */
+    relations: number;
+    reason?: string;
+    /**
+     * The fact id the write landed on. Present only for a real write; it must equal `fact_id`
+     * (a changed content would open a new revision instead — which `apply` refuses, not performs).
+     */
+    fact_id_after?: number;
+}
+/**
+ * The batch report. `facts` is in DOCUMENT ORDER and `total` counts every entry, so "50 reviewed,
+ * 3 rejected" is readable without re-reading the file.
+ *
+ * `dry_run` is stated on the report rather than inferred from the statuses. The two modes agree on
+ * `skipped`/`rejected` (the same validation gate runs) and differ on `applied`/`planned`; the one
+ * asymmetry is the post-write edge check, which only a real write can perform (module header).
+ */
+export interface RelationApplyReport {
+    dry_run: boolean;
+    total: number;
+    applied: number;
+    planned: number;
+    skipped: number;
+    rejected: number;
+    failed: number;
+    facts: RelationApplyEntryResult[];
+}
+/** The slice of the store `apply` needs. Narrow on purpose: `Pick<MemoryStore, …>` keeps it honest. */
+export type RelationWriter = Pick<MemoryStore, 'get' | 'update'>;
+/**
+ * The notes that need review: `status = 'active'`, `kind = 'note'`, and NO explicit relation yet.
+ *
+ * §2.1's selection, as SQL. "No explicit relation" is the `edges.source` of the fact — not the
+ * extracted triples — because the backfill's question is "has a CALLER ever stated a relation for
+ * this note", and an extracted edge is a guess about the text, which is exactly what Phase 5b found
+ * insufficient. Ordered by `fact_id` ASC: one stable order across runs, so a reviewed batch and a
+ * re-run page describe the same window.
+ *
+ * The emitted `relations` are empty by construction: filling them is the external reviewer's step
+ * (§7.2: "propose 不调用 LLM"), and an empty list is what makes an UNREVIEWED entry unapplicable
+ * (`apply` refuses an empty `relations`) rather than an accidental no-op.
+ */
+export declare function proposeRelations(db: Db, options?: RelationProposeOptions): RelationProposalDocument;
+/**
+ * How much of the active note corpus carries a CALLER-STATED relation (read-only, one report).
+ *
+ * `journal_relations` is in the report because this is the tool that would expose the violation: the
+ * layer rule lives in the write path, and a backfill that reports its own coverage should also say
+ * whether anything ELSE put an explicit edge on an episodic row.
+ */
+export declare function relationCoverage(db: Db): RelationCoverageReport;
+/**
+ * Parse a reviewed proposal file, or refuse the WHOLE file.
+ *
+ * Whole-file refusal is the rule because nothing here is derived state: a broken document is a
+ * caller mistake, and applying "the part that parsed" is exactly the silent partial write §7.4.5
+ * forbids. A per-ENTRY problem that a stale row creates is `apply`'s business instead — that one is
+ * reported entry by entry so the rest of a reviewed batch still lands.
+ *
+ * Required per entry: `fact_id` (positive integer), `kind: "note"`, `content` (non-empty). Optional:
+ * `existing_relations` (default `[]`), `relations` (default `[]` — an unreviewed entry, which
+ * `apply` refuses), `approved` (default `false`). Duplicate `fact_id` entries and duplicate
+ * relations inside one entry are refused: both would make "what this file says" ambiguous.
+ */
+export declare function parseRelationProposal(text: string): RelationProposalDocument;
+/**
+ * Apply a reviewed proposal document (docs/RELATION_BACKFILL.md §7.3).
+ *
+ * Per entry: `approved !== true` → `skipped`; {@link validateEntry} refuses → `rejected`; otherwise
+ * either `planned` (dry run, nothing written) or a real write through `remember.update`.
+ *
+ * NOT atomic across entries, on purpose (§7.3: "失败条目单独报告，不中断其他条目"). Each entry is one
+ * store transaction, so the batch can never be half-written WITHIN an entry; across entries the
+ * report is the record of what landed, and re-running the same file is safe: an applied entry's
+ * explicit set no longer matches its `existing_relations`, so the second run refuses it as stale
+ * rather than writing twice.
+ */
+export declare function applyRelationProposal(db: Db, memory: RelationWriter, document: RelationProposalDocument, options?: {
+    dryRun?: boolean;
+}): Promise<RelationApplyReport>;

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

@@ -0,0 +1,191 @@
+/**
+ * The deterministic query planner for the relation stage of `mem_recall.search`
+ * (docs/RELATIONAL_RECALL.md §6–7, Phase 4).
+ *
+ * WHAT IT IS. A closed, pure string/position rule set over TWO vocabularies the store already owns —
+ * `entities` / `entity_aliases` and `predicates` / `predicate_aliases` — that decides whether a query
+ * is a relation QUESTION the graph can answer, and if so which walk answers it:
+ *
+ * ```text
+ *   谁 <pred> <entity>            → reverse   (谁管理李娜)
+ *   <entity> <pred> 谁/什么        → one-hop   (张伟管理谁)
+ *   <entity> <pred> 的人 <pred2> 什么 → two-hop  (张伟管理的人负责什么)
+ *   <entity> <pred>               → one-hop   (张伟管理: bare SPO, no question word)
+ *   <pred> <entity>               → reverse   (管理张伟: the same statement, object first)
+ * ```
+ *
+ * THE SURFACE-ONLY RULE (2026-10-24 review, P1-3/P2). The two bare-SPO shapes are only plans when
+ * the query is EXACTLY their surfaces: after removing the entity/predicate nothing meaningful may
+ * remain. Otherwise a normal content query that happens to mention a known entity would be answered
+ * from the graph instead of by retrieval — "张伟管理的缓存层" is a QUESTION ABOUT THE CACHE LAYER,
+ * not about the person. The interrogative shapes keep their documented behaviour: the question word
+ * already says what the answer slot is.
+ *
+ * WHAT IT IS NOT. No model, no jieba, no natural-language generation, no arbitrary depth. Every
+ * decision is `String#indexOf` on the caller's query plus the vocabulary rows, so the same query over
+ * the same database always yields the same plan — which is what lets `search` be predictable and the
+ * tests be exact.
+ *
+ * MULTIPLE ENTITIES ARE NOT A RELATION QUESTION (docs/GRAPH_RECALL_AND_SEMANTICS.md §7.9). This
+ * planner only answers a question about ONE entity plus a predicate; "张伟和李娜" asks which recorded
+ * facts mention both, which is a FACT-level question, and its edges (when a fact has any) are
+ * evidence of that fact rather than a path between the two entities. So the multi-entity shape is
+ * planned by {@link planFactQuery} over `fact_entities` — journal entries and notes without any
+ * relation edge included — and the graph walk is never asked to fake it with `andPaths`.
+ *
+ * THE FALLBACK IS THE DEFAULT. Anything short of a COMPLETE plan (an entity, a predicate, the
+ * interrogative that makes it a question, in the expected order) returns `null`, and the caller then
+ * runs the next stage. §6's "判定不足时不要猜关系" is implemented as `return null`, not as a
+ * best-effort guess: a wrong relation answer is worse than a fuzzy one, because it claims structure
+ * the corpus never stated.
+ *
+ * WHY THE VOCABULARY IS A PORT. The planner only needs "which entity/predicate surfaces occur where
+ * in this text"; `MemoryGraphReader` answers that from SQL (and applies the store's kind/source/time
+ * filters at the same time). Keeping it an interface means the rules can be tested with a fake
+ * vocabulary, without a database, and that the planner stays free of SQLite.
+ *
+ * @module store/relation_planner
+ */
+import { type GraphReader, type GraphResult, type RelationPath as GraphRelationPath } from '../../graph-recall/index.js';
+import type { RelationPath } from '../../mem-contract/index.js';
+/** One surface form found in the query text, with the span it occupies. */
+export interface SurfaceMatch {
+    /** The string as it occurred — an alias or the canonical name. What `resolveNode` gets. */
+    ref: string;
+    /** The canonical entity name / predicate this surface means. */
+    canonical: string;
+    /** Inclusive character offset of the match in the query. */
+    start: number;
+    /** Exclusive character offset. */
+    end: number;
+}
+/**
+ * The two lookups the planner needs. `MemoryGraphReader` is the production implementation; the
+ * planner never sees a table.
+ */
+export interface RelationVocabulary {
+    /** Known entity surfaces (canonical names and explicit aliases) occurring in `text`, any order. */
+    entitiesIn(text: string): SurfaceMatch[];
+    /** Known predicate surfaces (canonical names and aliases) occurring in `text`, any order. */
+    predicatesIn(text: string): SurfaceMatch[];
+}
+/**
+ * A complete relation question.
+ *
+ * `start`/`object` are SURFACE refs (not ids): the executor resolves them through the reader, which
+ * is also what canonicalizes an alias to its entity. `predicate`/`secondPredicate` are already
+ * canonical names — the vocabulary resolved them — so an alias (`负责`) and its canonical (`管理`)
+ * produce the same walk.
+ */
+export type RelationQueryPlan = {
+    intent: 'one-hop';
+    start: string;
+    predicate: string;
+} | {
+    intent: 'reverse';
+    object: string;
+    predicate: string;
+} | {
+    intent: 'two-hop';
+    start: string;
+    predicate: string;
+    secondPredicate: string;
+};
+/** The most paths one relation answer returns (the library's own default page size). */
+export declare const RELATION_PATH_LIMIT = 10;
+/**
+ * The most entities ONE fact-level AND question may name (§7.9); beyond it the query falls back to
+ * fuzzy rather than asking a storage layer for an `IN (…)` list nobody bounded.
+ */
+export declare const MAX_FACT_ENTITIES = 50;
+/**
+ * Every start offset of `surface` in `text`.
+ *
+ * Both vocabularies (the graph reader's and the fact-level one) need POSITIONS — which side of the
+ * interrogative a name sits on — and a query may mention the same name twice
+ * ("张伟管理的人张伟自己负责什么" is not a good question, but the vocabulary must report both
+ * occurrences so the planner can reject it rather than pick one). Shared here so the two
+ * implementations cannot disagree about what "occurs" means.
+ */
+export declare function surfaceOccurrences(text: string, surface: string): number[];
+/**
+ * Decide whether `query` is a relation question, and which walk answers it.
+ *
+ * Order of the rules is intentional: the two-predicate `two-hop` shape is checked BEFORE the
+ * single-predicate shapes, because a query that has both ("…管理的人负责什么") would otherwise be
+ * answered one hop short. A partially matching multi-predicate query is then `null` rather than
+ * silently reduced to the first hop. Within the single-predicate branch the interrogative forms win:
+ * they say which slot the caller left open, so the bare-SPO fallback (which GUESSES the direction
+ * from surface order) only sees queries that ask nothing.
+ *
+ * @param vocabulary - entity/predicate surfaces (production: `MemoryGraphReader`).
+ * @param query - the caller's query text, verbatim.
+ * @returns the plan, or `null` when the query must fall back to fuzzy.
+ */
+export declare function planRelationQuery(vocabulary: RelationVocabulary, query: string): RelationQueryPlan | null;
+/**
+ * A fact-level AND question: a page of recorded facts that mention EVERY one of these entities
+ * (docs/GRAPH_RECALL_AND_SEMANTICS.md §7.9).
+ *
+ * `entities` are SURFACE refs (an alias or the canonical name), exactly like a relation plan's
+ * `start`/`object`: the fact repository resolves them alias-first, so the planner, the graph reader
+ * and the fact reader cannot disagree about what a name means. The planner DEDUPLICATES by canonical
+ * name, so an alias and its canonical form are one requirement rather than two.
+ */
+export interface FactQueryPlan {
+    /** The discriminant, named like every relation intent so a caller can switch on it. */
+    intent: 'facts';
+    entities: string[];
+}
+/**
+ * The one lookup the fact-level planner needs: known entity surfaces occurring in `text`.
+ *
+ * Production is `EntitiesDao.factEntitiesIn` (entities linked through `fact_entities`, so journal
+ * entries and notes without a relation edge count too), reached through `MemoryStore`; keeping it a
+ * callback means the rules can be tested without a database and stay independent of the storage
+ * layer. It may answer synchronously or asynchronously.
+ */
+export type FactEntityLookup = (text: string) => readonly SurfaceMatch[] | Promise<readonly SurfaceMatch[]>;
+/**
+ * Decide whether `query` is a PURE multi-entity question, and which entities it asks about.
+ *
+ * This is the fact-level AND stage: "张伟和李娜" is answered by the recorded facts that mention both,
+ * never by a graph walk between them. The shape is deliberately narrow, and each rule is a
+ * documented one:
+ *
+ *  - at least ONE conjunction ("和/与/以及/跟/同/、") — the cheap proof that the query is about
+ *    several entities, so a plain content search never pays for the vocabulary scan;
+ *  - at least TWO DISTINCT canonical entities;
+ *  - at most {@link MAX_FACT_ENTITIES} of them (§7.9; beyond that the query falls back to fuzzy);
+ *  - no interrogative: "张伟和李娜谁负责什么" asks a question this stage does not answer;
+ *  - after removing the entity and conjunction surfaces, NOTHING meaningful may remain:
+ *    "张伟和李娜的项目" is a content query that happens to name two entities.
+ *
+ * @param entitiesIn - the fact-level entity vocabulary lookup.
+ * @param query - the caller's query text, verbatim.
+ * @returns the plan, or `null` when the next stage answers the query.
+ */
+export declare function planFactQuery(entitiesIn: FactEntityLookup, query: string): Promise<FactQueryPlan | null>;
+/**
+ * Run one plan over a reader.
+ *
+ * This is deliberately only dispatch: the walks themselves are `@avantf/graph-recall`'s operators,
+ * so memory and knowledge cannot drift on what "two hops" means. Every branch RESOLVES its surface
+ * refs through the reader (an unresolved entity means the plan cannot run) and returns an empty
+ * result rather than throwing — an empty result is what makes `search` fall back to fuzzy.
+ *
+ * @param reader - the filtered graph view (kind/source/time already applied by the adapter).
+ * @param plan - a plan from {@link planRelationQuery}.
+ * @param limit - maximum paths to return.
+ */
+export declare function executeRelationPlan(reader: GraphReader, plan: RelationQueryPlan, limit?: number): GraphResult;
+/**
+ * Map the library's paths onto the contract's shape (`RelationPath` in `@avantf/mem-contract`).
+ *
+ * Two deliberate translations:
+ *  - the library's `GraphNode.id` is a string; memory's entity id is an integer;
+ *  - an edge WITHOUT a `factId` is not evidence, and the relation contract promises every edge can
+ *    be followed back to an openable fact — so such a path is dropped here rather than published as
+ *    structure nobody can verify. (The memory adapter always sets one; this guards the invariant.)
+ */
+export declare function relationPathViews(paths: readonly GraphRelationPath[]): RelationPath[];

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

@@ -10,7 +10,6 @@
  * What it does NOT do, by design:
  *  - no rewriting (a silently redacted fact is a lie the caller cannot see);
  *  - no scanning of what is already stored (writes only, never a retroactive sweep);
- *  - no knowledge-base coverage (`kb_add` ingests user-provided documents and is out of scope);
  *  - no config/override path (the refusal carries its own remedy: record WHERE the secret lives).
  *
  * The refusal message is the interface: it names the shape and tells the caller what to write

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

@@ -9,8 +9,10 @@
  * family of questions over the strict bar (0.685 / 0.677 / 0.626 vs 0.476 / 0.459 / 0.420).
  *
  * WHAT THIS MODULE IS, AND IS NOT. A pure string table: cues (substrings) → ONE canonical rewrite.
- * No model, no tokenizer, no await, no I/O — that is what lets the SAME table serve the synchronous
- * conditional hint (`runtime.relevance`, 方案 A②) and the async retrieval path (`store/hybrid.ts`).
+ * No model, no tokenizer, no await, no I/O — that is what lets the retrieval path
+ * (`store/hybrid.ts`) apply it as an AUGMENTATION, and the conditional hint inherit the exact same
+ * behaviour for free: the hint is `AvantfRuntime.wouldFind`, which runs that retrieval path
+ * (DESIGN §12), so there is no second copy of the table or of its rewrite logic.
  *
  * WHY THE TABLE IS CLOSED AND WHY ONLY ONE REWRITE. The first match wins and produces exactly one
  * canonical string. Chinese self-reference has unbounded variants ("我叫啥" / "本人是" / "我是干啥的"),

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

@@ -0,0 +1,121 @@
+/**
+ * The EXPLICIT time filter behind `mem_recall.search` / `mem_recall.timeline`
+ * (docs/TIME_SEARCH_AND_CATEGORIES.md §3).
+ *
+ * WHAT IT IS. One pure normalizer from the contract's `TimeFilter` to a half-open instant range
+ * `[from, to)`, PLUS the SQL fragment that range becomes in each table. No clock of its own for the
+ * bounds themselves — every bound comes from the caller's own strings — and no third-party date
+ * library: only `Date` and `Intl`.
+ *
+ * WHY IT IS NOT `parseTimeWindow`. That module (P-11) reads a time expression out of a QUERY's text
+ * and feeds a default-OFF recall leg. This one is a caller-named HARD filter with a required axis:
+ * a fact outside the window is not a candidate at all. They stay separate because they answer
+ * different questions ("this text mentions 上个月" vs "the caller asked for these days"), and
+ * because the leg deliberately never filters while this one only filters.
+ *
+ * THE GRAMMAR (D3/D4):
+ *
+ *  - `YYYY-MM-DD` (date only) → the whole local day `[00:00, next 00:00)`.
+ *  - `YYYY-MM-DDTHH:MM` (date + time) → exactly that one minute `[HH:MM:00, HH:MM+1:00)`.
+ *  - a value carrying seconds/milliseconds is ROUNDED to the minute in the direction that does not
+ *    shrink the caller's window: `on`/`from` floor, `to` ceil (so `to=18:00:30` still contains the
+ *    18:00 minute).
+ *  - `from` is INCLUSIVE, `to` is EXCLUSIVE. A date-only `to` expands to the NEXT day's 00:00, which
+ *    is what makes "从 10-01 到 10-07" include the 7th.
+ *  - a value WITHOUT an offset is read in `timezone` (default: the host's own zone — currently
+ *    Asia/Shanghai); a value WITH `Z`/`±HH:MM` keeps its own offset and ignores `timezone`.
+ *  - `on` XOR `from`/`to`; at least one of them; `from > to` is an error, not an empty answer.
+ *
+ * WHY THE RANGE BECOMES BOTH EPOCH MS AND UTC TEXT. `created_at`/`updated_at` are TEXT
+ * (`CURRENT_TIMESTAMP`, `YYYY-MM-DD HH:MM:SS`, UTC) on every existing database, so Phase 1 compares
+ * them lexicographically against the UTC form of the same bounds — no migration, no re-interpretation
+ * of stored clock values. `valid_from` is the caller's own string (date-only or offset ISO), which
+ * cannot be compared lexicographically, so the EVENT axis uses epoch-ms columns
+ * (`valid_from_ms`, migration 11) and this range supplies the numbers.
+ *
+ * @module store/time_filter
+ */
+import type { TimeField, TimeFilter } from '../../mem-contract/index.js';
+/** One normalized filter: the field it applies to and a half-open `[fromMs, toMs)` instant range. */
+export interface TimeRange {
+    field: TimeField;
+    /**
+     * The zone the caller's OFFSET-LESS values were read in (undefined = the host's own zone).
+     *
+     * Kept on the range because the `event` axis's text prefix must be compared in the SAME zone the
+     * caller's bounds were interpreted in — reading it back in the host zone would shift a Shanghai
+     * evening by a day on a UTC host.
+     */
+    timezone?: string;
+    /** Inclusive lower bound, epoch ms. `null` = open (no `from`). */
+    fromMs: number | null;
+    /** Exclusive upper bound, epoch ms. `null` = open (no `to`). */
+    toMs: number | null;
+    /** Inclusive lower bound as a UTC `YYYY-MM-DD HH:MM:SS` string (`created_at`'s own form). */
+    fromUtc: string | null;
+    /** Exclusive upper bound as a UTC `YYYY-MM-DD HH:MM:SS` string. */
+    toUtc: string | null;
+}
+/**
+ * The SQL fragment a {@link TimeRange} becomes, for one table alias.
+ *
+ * `clause(alias)` returns only the predicate body (no leading `AND`) so a caller can append it to a
+ * statement that already has its own filters; `params` binds in the SAME order the caller's `?`
+ * placeholders appear, which is why the fragment is built once and reused verbatim.
+ */
+export interface TimeSql {
+    clause(alias: string): string;
+    params: (string | number)[];
+}
+/** `YYYY-MM-DD HH:MM:SS` in UTC — the form `CURRENT_TIMESTAMP` writes. */
+export declare function utcTimestamp(ms: number): string;
+/** Local `YYYY-MM-DD` for an instant — the day an `event` bound falls on in the host's zone. */
+export declare function localDay(ms: number): string;
+/** A bound at its minute boundary, rounding `up` or down (see the module's rounding rule). */
+/**
+ * Validate and normalize one `time` filter.
+ *
+ * Throws (never returns a "no rows" range) on a caller mistake: an unknown field, a missing/duplicate
+ * bound form, an unparseable value, an unknown timezone, or `from > to`. An empty ANSWER is a valid
+ * outcome; an empty-QUESTION is not, because it returns the same shape as "nothing was written that
+ * day" and the caller cannot tell the two apart.
+ */
+export declare function normalizeTimeFilter(filter: TimeFilter): TimeRange;
+/**
+ * The SQL predicate a normalized range becomes, or `undefined` when the range has no bounds.
+ *
+ * The fragment names the COLUMN for the field (never a `COALESCE` across axes — D5: an event filter
+ * that fell back to `created_at` would answer "上个月做了什么" with facts merely WRITTEN last month),
+ * and it is the one place that decision lives for both stores' legs and the timeline query.
+ */
+export declare function timeSql(range: TimeRange): TimeSql | undefined;
+/**
+ * The `AND <predicate>` suffix for a statement, or `''` when there is no filter.
+ *
+ * A helper rather than string concatenation at every call site: the leading `AND` and the alias are
+ * what a hand-written copy gets wrong, and an append with no predicate would produce a dangling
+ * `WHERE … AND` — a syntax error that only fires on the timed path.
+ */
+export declare function timeAndClause(range: TimeRange | undefined, alias?: string): string;
+/** The bind parameters behind {@link timeAndClause}, in the same order. */
+export declare function timeParams(range: TimeRange | undefined): (string | number)[];
+/**
+ * The calendar day `ms` falls on, in `timeZone` (undefined = the host's zone).
+ *
+ * The `Intl` path is the same formatter cache `zonedWallClock` uses: a caller naming a zone must get
+ * that zone's DATE, not the host's.
+ */
+export declare function dayInZone(ms: number, timeZone?: string): string;
+/**
+ * One stored `valid_from`/`valid_to` string → epoch ms, using the SAME grammar as the filters.
+ *
+ * This is what the write path stamps into `valid_from_ms` and what migration 12's backfill applies to
+ * existing rows, so "the event time a caller wrote" and "the event time a window compares" can never
+ * be produced by two different parsers. A `YYYY-MM-DD` value is that day's local midnight (the
+ * writer's own zone — the engine's host), exactly like a date-only bound in a filter; a value with an
+ * offset keeps its own offset.
+ *
+ * `undefined` means "not a value this engine can place on the axis" — the row then behaves like one
+ * with no event time at all (D5: excluded, never binned by guesswork).
+ */
+export declare function eventTimeMs(value: string | null | undefined): number | undefined;

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

@@ -0,0 +1,52 @@
+import { type FtsTokenizer } from '../db/tokenizer.js';
+/** Why a title was refused. The messages name the way out, like every other write refusal. */
+export declare const TITLE_EMPTY = "\u6807\u9898\u4E0D\u80FD\u4E3A\u7A7A\uFF1Ajournal \u7684 title \u662F\u4E00\u53E5\u8BDD\u7684\u4E8B\u52A1\u53E5\u67C4\u3002";
+export declare const TITLE_TOO_LONG: string;
+export declare const TITLE_HAS_CONTROL = "\u6807\u9898\u5FC5\u987B\u662F\u5355\u884C\uFF1A\u4E0D\u63A5\u53D7\u6362\u884C\u6216\u63A7\u5236\u5B57\u7B26\u3002";
+/**
+ * The refusal a title CHANGE gets inside one revision chain (JOURNAL_TITLE_SEARCH §2.2).
+ *
+ * One sentence with the way out: the same transaction omits the title (it inherits), and a different
+ * transaction is a new journal. A rename is not offered IMPLICITLY — it would make the old handle
+ * unfindable for every agent that remembered the old name — but v17 added the explicit correction
+ * (`retitle: true`), which records the old title as an alias instead of losing it.
+ */
+export declare const TITLE_IMMUTABLE = "\u6807\u9898\u5728\u4E00\u6761 revision \u94FE\u5185\u4E0D\u53EF\u53D8\uFF1A\u540C\u4E00\u4E8B\u52A1\u8BF7\u7701\u7565 title\uFF08\u81EA\u52A8\u7EE7\u627F\u88AB\u6539\u5199\u7684 revision\uFF09\uFF1B\u786E\u9700\u7EA0\u6B63\u5199\u9519\u7684\u6807\u9898\uFF0C\u8BF7\u5E26 `retitle: true` \u5E76\u7ED9\u51FA\u65B0 title\uFF08\u65E7\u6807\u9898\u4FDD\u7559\u4E3A\u522B\u540D\uFF0C\u65E7\u641C\u7D22\u4ECD\u80FD\u547D\u4E2D\uFF09\u3002";
+/** `retitle: true` on a write that has no chain to correct (an `add`, or the raw write without an id). */
+export declare const TITLE_RETITLE_NEEDS_UPDATE = "retitle \u53EA\u7528\u4E8E\u7EA0\u6B63\u5DF2\u6709\u8BB0\u5F55\u7684\u6807\u9898\uFF1Aadd \u4E0D\u9700\u8981\u5B83\uFF08\u65B0\u8BB0\u5F55\u76F4\u63A5\u7ED9 title \u5373\u53EF\uFF09\u3002";
+/** `retitle: true` without the new title — there is nothing to change it TO. */
+export declare const TITLE_RETITLE_NEEDS_TITLE = "retitle \u9700\u8981\u540C\u65F6\u7ED9\u51FA\u65B0\u7684 title\uFF1A\u5B83\u53EA\u7528\u6765\u6539\u6807\u9898\uFF0C\u4E0D\u7ED9\u65B0\u6807\u9898\u5C31\u6CA1\u6709\u53EF\u6539\u7684\u5185\u5BB9\u3002";
+/** The model-facing "a journal needs a title" refusal (core/import/CLI keep allowing NULL). */
+export declare const TITLE_REQUIRED = "journal\uFF08\u505A\u4E86\u4EC0\u4E48/\u804A\u4E86\u4EC0\u4E48/\u60F3\u4E86\u4EC0\u4E48\uFF09\u5FC5\u987B\u5E26 title\uFF1A\u77ED\u6807\u9898\u662F\u540C\u4E00\u4E8B\u52A1\u7684\u53E5\u67C4\uFF0C\u4E5F\u662F\u6807\u9898\u68C0\u7D22\u7684\u5165\u53E3\uFF1B\u53EA\u8981\u7A33\u5B9A\u4E8B\u5B9E\u8BF7\u8BB0 note\u3002";
+/** A duplicate/merge hit an existing row with a DIFFERENT title — most likely another transaction. */
+export declare const TITLE_CONFLICT = "\u540C\u6837\u7684\u5185\u5BB9\u5DF2\u6709\u4E00\u6761 title \u4E0D\u540C\u7684\u8BB0\u5F55\uFF1A\u5B83\u53EF\u80FD\u5C5E\u4E8E\u53E6\u4E00\u4E2A\u4E8B\u52A1\uFF1B\u540C\u4E00\u4E8B\u52A1\u8BF7 update \u90A3\u6761\u8BB0\u5F55\uFF08\u7701\u7565 title\uFF09\uFF0C\u4E0D\u8981\u65B0\u589E\u3002";
+/**
+ * Normalize a title a WRITE carries. Throws rather than returning `''`: an empty title is a caller
+ * mistake for a journal, and the store decides separately what an empty NOTE title means (NULL).
+ */
+export declare function normalizeTitle(value: string): string;
+/**
+ * Normalize a title SEARCH text. Same rules, except empty is "no query" (`null`) rather than an
+ * error — a whitespace-only search is answered with no candidates, not with a refusal.
+ */
+export declare function normalizeTitleQuery(value: string): string | null;
+/** The keywords a title query is made of (the query is already normalized, so single spaces). */
+export declare function titleTerms(query: string): string[];
+/**
+ * The FTS5 MATCH expression for a title query, or `null` when the table's tokenizer cannot express it.
+ *
+ * Each keyword becomes ONE quoted phrase, OR-joined: in a trigram table a quoted phrase of three or
+ * more characters is a SUBSTRING match (not an n-gram bag), which is exactly the semantics a title
+ * search wants. A keyword shorter than three characters cannot be phrased at all — and a unicode61
+ * table would treat a CJK title as a single token, so a substring query could never match it — hence
+ * `null`, which sends the caller to the LIKE fallback rather than to a silent zero.
+ *
+ * The `null` is ALL-OR-NOTHING on purpose: dropping the inexpressible keywords would answer a
+ * different question than the caller asked (e.g. "dsh 网关" would become "dsh").
+ */
+export declare function titleFtsQuery(query: string, tokenizer: FtsTokenizer): string | null;
+/**
+ * One stored title → the value surfaces read. `null` and `''` both mean "no title" (a restored
+ * legacy row may carry the empty string), and a display never invents one.
+ */
+export declare function storedTitle(value: unknown): string | null;