@avantf/dsh-mem 0.6.4 → 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 {