@avantf/dsh-mem 0.6.4 → 0.8.0

package/lib/engine/mem/relations/normalize.d.ts

@@ -0,0 +1,275 @@
+/**
+ * Entity / predicate normalization — the vocabulary half of Phase 2
+ * (docs/RELATIONAL_RECALL.md §4.1–4.2/R2), and the middle step of the relation pipeline:
+ *
+ * ```text
+ *   relations/extract.ts   → candidates (strings only, no database)
+ *   relations/normalize.ts → alias/name + predicate vocabulary (THIS module; needs a `Db`)
+ *   relations/confidence.ts → the name/statement/confidence gates (pure)
+ *   db/graph.ts            → ids, direction, rows
+ * ```
+ *
+ * It resolves BOTH halves of an edge — the two entity names and the predicate — because an edge is
+ * two names plus a predicate, and the alias tables are the vocabulary's, not the POS extractor's.
+ * `entities/` owns tagging and entity names; this module owns what those strings MEAN.
+ *
+ * What this module owns, and what it deliberately refuses to do:
+ *
+ *  - **Predicate vocabulary.** §4.2 names the families (管理/负责/主管, 使用/依赖, 属于/归属) and
+ *    requires that an unfittable predicate keep its own word. So there is a small CURATED table
+ *    below: a canonical name per relation family, its surface aliases, a direction, and a
+ *    description. It is code, not a data migration, because a relation vocabulary is a judgement
+ *    about the language, not about one operator's corpus — and because a seeded row must never
+ *    overwrite a row an operator already corrected (first write wins, the same rule
+ *    `entities.entity_type` has).
+ *  - **Entity aliases.** §4.1 forbids automatic merging of two entities and asks for explicit
+ *    aliases only. `entity_aliases` is therefore filled from exactly one automatic source —
+ *    an EXPLICIT alias statement in the text (`A（又名 B）`, `A 简称 B`, `A aka B`, …) — plus the
+ *    explicit `registerEntityAlias` entry point. "Two names look similar" / "both are frequent" is
+ *    not evidence and never merges anything.
+ *  - **Resolution order: alias, then name, then (optionally) create.** An alias row is an explicit
+ *    statement, so it outranks a raw extracted token; the token's own `entities` row is left alone
+ *    (content recall still uses it), only the GRAPH uses the canonical name. Creating is the last
+ *    resort and is the caller's choice (`create: false` is how a dry run learns what it would do
+ *    without polluting the vocabulary).
+ *
+ * Why the alias tables are seeded from HERE and not from a migration: a migration runs once per
+ * database, but the vocabulary is allowed to grow with the code, and the seeding is idempotent
+ * (`INSERT OR IGNORE` on `predicates.canonical_name` / `predicate_aliases.alias`). The memo below
+ * makes it one pass per connection rather than one per write.
+ *
+ * @module relations/normalize
+ */
+import type { Db } from '../db/port.js';
+import { type RelationTripleInput } from './types.js';
+/**
+ * Which way a predicate's surface order maps onto its stored edge.
+ *
+ * `forward` (almost every seeded family): the stored edge reads subject → object, i.e. the same
+ * order the sentence used. `inverse`: the surface sentence puts the END of the relation first
+ * ("A 的下属是 B" states "B 管理 A"), so the edge is written with the two entity slots swapped and
+ * every walker can read all edges in one direction (§4.2's "保留方向" — the direction is a property
+ * of the relation, recorded once on the predicate row, not re-guessed per edge).
+ *
+ * `symmetric`: the relation holds in BOTH directions (合作), so one stored edge — written in the
+ * sentence's own order — must answer from either end. Nothing is swapped at write time; the READER
+ * expands the walk (see `store/graph_reader.ts` and {@link isSymmetricPredicate} for why the code's
+ * vocabulary, not only the row, decides).
+ */
+export type PredicateDirection = 'forward' | 'inverse' | 'symmetric';
+/** One curated relation family. */
+export interface PredicateSeed {
+    /** The stored `predicates.canonical_name`. */
+    canonical: string;
+    /** Surface forms that mean the same relation (never including the canonical name itself). */
+    aliases: readonly string[];
+    direction?: PredicateDirection;
+    description: string;
+}
+/**
+ * The curated predicate vocabulary (§4.2's three families plus the relations this store's own
+ * fixtures and docs already exercise).
+ *
+ * Rules a new entry must follow, because getting them wrong is what makes a graph lie:
+ *  - only relations that assert something STABLE about two entities. Modal / hearsay / planning
+ *    verbs (计划, 打算, 听说, 可能) are absent on purpose: §R3's "不把「可能/计划/听说」抽成确定关系".
+ *    They stay unmatched, which is what makes the edge writer drop them (see `edgeConfidence`).
+ *  - an alias must be a form that is interchangeable in this store's usage, not merely related.
+ *    `修` is left out because it is below the extractor's 2-character floor anyway; `用` likewise.
+ */
+export declare const PREDICATE_VOCABULARY: readonly PredicateSeed[];
+/** What one seeding pass inserted (0/0 once the vocabulary is already there). */
+export interface VocabularySeedReport {
+    predicatesCreated: number;
+    aliasesCreated: number;
+}
+/**
+ * Create the curated predicates and their aliases if they are missing — idempotent, first write wins.
+ *
+ * An existing `predicates` row keeps its `direction` / `description`: both may have been corrected by
+ * an operator, and re-asserting the code's version on every open would silently undo that. The one
+ * exception is a row that has NO description — that is the state every Phase 1 backfill row is in
+ * (`INSERT OR IGNORE INTO predicates (canonical_name)`), and "no description" means "nobody has said
+ * what relation this is", which is exactly the fact {@link ensureRelationalVocabulary} can fill in.
+ * Without that fill-in an upgraded database would keep every predicate uncurated and the write path's
+ * confidence policy would refuse all of its relations. The same holds for `predicate_aliases`.
+ *
+ * Requires the v15 graph tables; called from the store's write path, so a database that predates
+ * them would already have failed its migration.
+ */
+export declare function ensureRelationalVocabulary(db: Db): VocabularySeedReport;
+/** How a name was matched — the provenance a caller reports or asserts on. */
+export type ResolveVia = 'alias' | 'name' | 'created';
+/** One resolved entity. */
+export interface EntityRef {
+    entity_id: number;
+    /** The CANONICAL name (the `entities.name` the graph uses), not necessarily the input. */
+    name: string;
+    via: ResolveVia;
+}
+/** One resolved predicate. */
+export interface PredicateRef {
+    predicate_id: number;
+    canonical: string;
+    direction: PredicateDirection;
+    /**
+     * Whether someone has SAID what relation this is (`predicates.description` is set) — the seed does,
+     * an operator-registered relation is expected to, a row created by name-mapping does not. This is
+     * the bit the confidence policy uses: an undescribed verb is a guess, and a guess with a weak
+     * producer score stays out of the graph.
+     */
+    curated: boolean;
+    via: ResolveVia;
+}
+/** Options shared by the two resolvers. `create: false` is the dry-run / read-only mode. */
+export interface ResolveOptions {
+    /** Create a vocabulary row for an unseen name (default true). */
+    create?: boolean;
+    /** `entities.extraction_method` for a row this call creates (default `'graph'`). */
+    method?: string;
+}
+/**
+ * Whether a canonical relation is SYMMETRIC — read from the curated vocabulary, not from the row.
+ *
+ * `predicates.direction` is written once per database (`INSERT OR IGNORE`), and a row seeded by an
+ * earlier build holds the column default `'forward'`: re-asserting the code's value on open would
+ * silently undo an operator's correction, which is why the seeding is first-write-wins. Symmetry is
+ * therefore a fact about the RELATION FAMILY as this build defines it, and the reader asks this
+ * function so an upgraded database answers `合作` from both ends without a data migration. A
+ * relation an operator registers is asymmetric unless it is one of these families — there is no
+ * operator-facing way to declare a new one yet, and pretending otherwise would be a promise the
+ * reader cannot keep.
+ */
+export declare function isSymmetricPredicate(canonical: string): boolean;
+/**
+ * Resolve one entity name to its canonical node: **alias first**, then exact name, then create.
+ *
+ * Alias first is the whole point of registration: a registered alias is an explicit statement
+ * ("老张 就是 张伟"), while the extracted token is a guess about a string. The token's own row — if
+ * one exists — is left untouched, so nothing that reads `fact_entities` changes behaviour; only the
+ * graph follows the canonical name.
+ *
+ * @returns `undefined` only when the name is unusable or `create: false` and it is unknown.
+ */
+export declare function resolveEntity(db: Db, rawName: string, options?: ResolveOptions): EntityRef | undefined;
+/**
+ * Resolve one predicate word to its canonical relation: alias, then canonical name, then create.
+ *
+ * The direction comes from the resolved ROW, so a predicate an operator registered as `inverse`
+ * keeps that meaning through every later write; a newly created row is `'forward'` (the only
+ * direction any seeded family uses, and the only claim an unknown word supports).
+ *
+ * `curated` is the one bit the confidence policy reads (see `confidence.ts#edgeConfidence`), and it is
+ * derived from the ROW rather than from the code's seed list so an operator-registered relation
+ * counts too: a predicate is curated when it carries a DESCRIPTION. The seed writes one for every
+ * family (and fills it into a row the Phase 1 backfill created without one); a row created by
+ * name-mapping or by this function's `create` path has none, which is the honest state of "a verb the
+ * extractor produced, which nobody has said is a relation".
+ *
+ * @returns `undefined` when the word is unusable or `create: false` and it is unknown — the caller
+ *   treats that as "not a relation we can name", which is what the confidence policy acts on.
+ */
+export declare function resolvePredicate(db: Db, rawPred: string, options?: ResolveOptions): PredicateRef | undefined;
+/** One alias statement found in a text. */
+export interface AliasPair {
+    /** The alternative name (`B` in "A（又名 B）"). */
+    alias: string;
+    /** The name it is stated to be another form of (`A`). */
+    canonical: string;
+}
+/**
+ * Explicit alias statements in `text`, in order of appearance.
+ *
+ * Both groups are narrow on purpose: no spaces, 2–20 characters, and the cue word is required. A
+ * false match would merge two nodes, which §4.1 ranks as the one thing not to automate.
+ *
+ * `knownNames` is the second half of that guard, and it is what makes the pattern usable at all:
+ * Chinese has no spaces, so `X` before the cue is a raw character run ("张伟管理缓存层（又名 …）"
+ * would otherwise become one alias target). Only a candidate the extractor ALSO recognised as an
+ * entity is accepted — the cue states the identity, the entity list states that the left side is a
+ * name rather than a sentence.
+ */
+export declare function parseAliasPairs(text: string, knownNames?: readonly string[]): AliasPair[];
+/**
+ * Strip an alias statement that the extractor merged into an entity slot.
+ *
+ * The SVO extractor (`relations/extract.ts`) merges everything noun-ish on one side of the predicate,
+ * so a sentence that
+ * states an alias ("张伟（又名 老张）负责李娜", "老张又名四哥，管理王五") yields a subject that contains
+ * the whole statement. Turning that into an entity would create a node whose name is a sentence, and
+ * would hide the fact from the canonical entity — so the graph resolves the slot to the name BEFORE
+ * the cue.
+ *
+ * Narrow on purpose: only a candidate that CONTAINS an alias cue is touched, a parenthesised group is
+ * only dropped when it carries a cue, and an empty result falls back to the input (nothing is
+ * invented to replace a name).
+ */
+export declare function stripAliasClause(rawName: string): string;
+/** Why an alias statement did not become a row (absent = it did). */
+export type AliasSkipReason = 'blank' | 'self' | 'already-aliased';
+/** What one alias registration did. */
+export interface AliasRegistration {
+    alias: string;
+    canonical: string;
+    written: boolean;
+    reason?: AliasSkipReason;
+}
+/**
+ * Record `alias → canonical` in `entity_aliases`, creating the canonical entity if it is new.
+ *
+ * Two refusals, both conservative:
+ *  - `alias === canonical` / either slot blank: not a statement about two names.
+ *  - the alias is ALREADY registered to another entity: `alias` is UNIQUE, and re-pointing it would
+ *    rewrite an earlier explicit statement. Reported, never silently overwritten.
+ *
+ * Registering an alias whose text is also an existing entity name is ALLOWED: the alias is an
+ * explicit statement about the string, the entity row is the extractor's guess, and resolution
+ * prefers the alias (see `resolveEntity`). Nothing is merged or deleted — the old row keeps its
+ * `fact_entities` links.
+ */
+export declare function registerEntityAlias(db: Db, pair: AliasPair, options?: ResolveOptions): AliasRegistration;
+/** {@link registerEntityAlias} over the statements found in one text (best-effort, in order). */
+export declare function registerEntityAliasesFromText(db: Db, text: string, knownNames: readonly string[], options?: ResolveOptions): AliasRegistration[];
+/**
+ * A producer triple after normalization — the input of `confidence.ts#evaluateRelation` and then of
+ * the storage step (`db/graph.ts`). Everything the policy needs is on this object, which is why the
+ * policy itself reads no database.
+ */
+export interface NormalizedRelation {
+    /** The slots the graph stores: an alias STATEMENT is stripped, both sides trimmed. */
+    subj: string;
+    pred: string;
+    obj: string;
+    /**
+     * The slots as the producer wrote them (trimmed, alias statement INCLUDED). The statement test
+     * (`statement.ts#isStatedRelation`) reads the fact text against THESE — the strip above changed
+     * the slot, and the test has to ask about what is actually in the text.
+     */
+    raw: {
+        subj: string;
+        pred: string;
+        obj: string;
+    };
+    /** The producer's score, before the policy adjusts it. */
+    confidence: number | null | undefined;
+    /** The producer's provenance (`'svo'`, `'pattern'`, `'explicit'`, `'llm'`, …). */
+    source: string;
+    /** `source === 'explicit'`: a caller's statement, which the policy trusts outright. */
+    explicit: boolean;
+    /**
+     * The vocabulary row for `pred`, when it already exists. The probe is `create: false` on purpose:
+     * whether an unknown predicate earns a row of its own is the STORAGE step's decision, taken only
+     * after the policy accepted the relation (a refused triple must not leave a predicate behind).
+     */
+    predicate?: PredicateRef;
+}
+/**
+ * Normalize one producer triple onto the vocabulary: strip an alias STATEMENT that the extractor
+ * merged into an entity slot (`张伟（又名 老张）` → `张伟`), trim the predicate, and look its row up.
+ *
+ * Total: a blank slot is a relation the policy refuses (`confidence.ts#evaluateRelation` reports it
+ * as `blank`), not an error here — the slots are still returned so a drop sample can name them. An
+ * UNKNOWN predicate is not a refusal either: §4.2 keeps the producer's own word, and the
+ * `predicate` field is simply absent (the policy then scores it uncurated).
+ */
+export declare function normalizeRelation(db: Db, triple: RelationTripleInput): NormalizedRelation;

package/lib/engine/mem/relations/patterns.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Explicit relation patterns — the deterministic half of Phase 5b's extraction repair
+ * (docs/RELATIONAL_RECALL.md §4.3/R3, §十七; the 2026-10-25 review's §三/§七).
+ *
+ * WHY PATTERNS AT ALL. The token-based producers (`relations/extract.ts`) need a predicate WORD with
+ * a name on each side, and they take those names from proximity. That misses two whole classes of
+ * statement the live corpus does contain:
+ *
+ *  - a relation expressed with a PREPOSITION rather than a verb: `冯飞在阿里巴巴工作`;
+ *  - a relation whose surface order puts the object before the predicate: `张伟向李娜汇报`,
+ *    `张伟与李娜合作`.
+ *
+ * Patterns are the right tool for exactly this: fixed cue words, fixed argument order, a small and
+ * closed set. They are NOT a general parser, and this module deliberately holds only patterns whose
+ * surface form cannot mean anything else. The bar for adding one is the same as for a curated
+ * predicate: an operator can read the cue and predict the edge.
+ *
+ * WHAT KEEPS A PATTERN HONEST — the "statement check" this module performs itself, because the
+ * canonical predicate a pattern writes (`工作于`) is not the word the text contains and
+ * `relations/statement.ts`'s gate therefore cannot be applied to it:
+ *
+ *  - the cue is required, so a sentence without it produces nothing;
+ *  - the cue must END at a clause boundary (`AFTER`, built from the statement gate's own
+ *    `CLAUSE_BOUNDARY_CHARS`): this is the 2026-10-25 review's §三 false positive — `工作区`,
+ *    `工作人员`, `工作报告` all used to match `工作` as a PREFIX and become `工作于` edges at
+ *    confidence 0.95. A cue that continues into another word is not a cue;
+ *  - the OBJECT must end at a clause boundary too, and must not itself contain a cue: a greedy name
+ *    class otherwise swallows the rest of the clause (`张伟就职于某公司工作` → `某公司工作`);
+ *  - both arguments must pass `graphNameIssue` (a bounded, punctuation-free name), and a trailing
+ *    parenthetical is dropped (`阿里巴巴（阿里）` → `阿里巴巴`);
+ *  - the relation name written is the CANONICAL predicate (`工作于`), which the curated vocabulary
+ *    (`relations/normalize.ts`) must contain — an uncurated pattern name would be refused by the
+ *    edge writer's confidence policy anyway, so a pattern cannot smuggle in a new relation family;
+ *  - the triple is stamped `source: 'pattern'` and a confidence above the heuristic's, because the
+ *    cue is evidence: it is not guessed from proximity.
+ *
+ * The patterns run on the RAW TEXT (not on POS tokens) on purpose: the tokenizer loses the
+ * preposition/verb distinction that makes the cue unambiguous, and a pattern needs no tagger, so it
+ * also works when nodejieba is unavailable.
+ *
+ * @module relations/patterns
+ */
+import type { RelationCandidate } from './types.js';
+/** Confidence a pattern triple carries: the cue is evidence, unlike an inferred proximity triple. */
+export declare const PATTERN_TRIPLE_CONFIDENCE = 0.7;
+/** One pattern's yield (used by the extraction report to separate "no cue" from "cue but refused"). */
+export interface PatternYield {
+    id: string;
+    matches: number;
+    accepted: number;
+    refused: number;
+}
+/**
+ * Extract the relations stated by an EXPLICIT cue in `text`.
+ *
+ * Every module-level regex is `g` and therefore stateful, so `lastIndex` is reset before each
+ * `matchAll` — the same guard `normalize.parseAliasPairs` uses. A match is accepted only when both
+ * arguments are usable names AND the object is not a clause continuation; the rest are counted as
+ * refusals, not silently dropped, so a report can say which pattern matched and why it produced
+ * nothing.
+ */
+export declare function patternTriples(text: string): RelationCandidate[];
+/** {@link patternTriples} plus the per-pattern accounting (the eval script's half). */
+export declare function patternTriplesWithReport(text: string): {
+    triples: RelationCandidate[];
+    yields: PatternYield[];
+};

package/lib/engine/mem/relations/statement.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Was a relation actually STATED, or did the extractor cut a fragment out of prose? — Phase 5b's
+ * precision gate (docs/RELATIONAL_RECALL.md §4.3/R3, §十七).
+ *
+ * THE PROBLEM. `relations/extract.ts` is an SVO proximity heuristic: for every verb it takes the
+ * noun-ish run on its left as the subject and the run on its right as the object. On a short
+ * declarative fact (`张伟管理李娜`) that is exactly a statement. On a long engineering note
+ * (`…命令：npm publish … 发布账号 ffeng86…`) it produces `命令 —创建→ 仓库README`: two fragments that
+ * happen to sit on either side of a verb, glued into a relation nobody asserted.
+ *
+ * Phase 5a measured the live graph at 48 active edges / 38 facts; this test finds that NONE of the
+ * 48 curated triples among the 809 stored active triples is a stated relation. So the 0.216 coverage
+ * Phase 5a reported was fragment coverage — the metric was measuring how much prose the tokenizer
+ * walked over, not how many relations the store knows. §R3 is explicit about the direction to fix
+ * it: a wrong edge is worse than a missing one, so an edge now requires the fact's TEXT to assert
+ * the triple as a clause.
+ *
+ * WHAT "STATED" MEANS HERE, exactly — the triple's three parts must appear as one contiguous run in
+ * the fact content, with:
+ *
+ *  - a clause boundary before the subject and after the object (start/end of text, whitespace, any
+ *    sentence punctuation, a quote or a bracket). A match that needs text on its outside is a
+ *    fragment of a longer clause, so it is not a statement.
+ *  - nothing but a closed set of REALIS adverbs between subject and predicate (`已经/已/正在/都/…`).
+ *    A single comma is also allowed there: Chinese shares a subject across a comma-splice
+ *    (`老张又名四哥，负责王五` states that 老张/四哥 manages 王五), and the live corpus has no case where
+ *    that tolerance admits a fragment (measured: still 0/809).
+ *    Modals and hedges are absent on purpose: `将要`, `需要`, `可以`, `可能`, `计划` mean the relation
+ *    is not asserted, and §R3 forbids turning them into facts. A NEGATION (`不`, `没有`, `未`, `别`)
+ *    is absent too — and because the adverb set is closed, `不再依赖` cannot match the positive
+ *    `依赖` triple at all. That is how "the store must not assert the opposite of what was written"
+ *    is enforced without a separate negation parser.
+ *  - only an aspect particle (`了/着/过`) between predicate and object.
+ *
+ * The test is deliberately CONSERVATIVE: it is a substring test over the stored text, so a fact that
+ * paraphrases its own triple is dropped. That is the intended failure direction (§R3), and it is
+ * why the triple is still stored (`triples` remains "what the string extractor saw") even when the
+ * edge is refused.
+ *
+ * The gate applies to triples the TEXT EXTRACTOR produced (`source: 'svo'`), not to triples a
+ * caller asserts explicitly (a curated/LLM/fixture producer already knows the relation, and R2's
+ * write path lets it say so). See `confidence.ts#evaluateRelation`.
+ *
+ * TWO CALLERS, ONE DEFINITION. The extractor's triple-shape invariant shares the same regex parts:
+ * {@link isContiguousTriple} asks the weaker question "are the three slots one unbroken run of
+ * text?" and `relations/extract.ts` refuses a candidate that fails it before the triple is stored,
+ * while {@link isStatedRelation} is the edge gate above. Both read `CLAUSE_BOUNDARY_CHARS`, and
+ * `relations/patterns.ts` uses that same constant for a cue's right boundary — one definition of
+ * "clause", so the extractor, the patterns and the gate cannot disagree about where a clause ends.
+ *
+ * @module relations/statement
+ */
+/**
+ * Clause characters that may sit immediately before a subject / after an object.
+ *
+ * EXPORTED because it is the definition, not a copy: `relations/extract.ts` (the triple-contiguity
+ * check) and `relations/patterns.ts` (a cue's right boundary) must agree with the statement gate on
+ * what ends a clause — otherwise a pattern can match text this gate would call one clause and a
+ * fragment, which is exactly how `工作区` became an edge.
+ */
+export declare const CLAUSE_BOUNDARY_CHARS = "\\s\uFF0C\u3002\u3001\uFF1B\uFF1A\uFF01\uFF1F,;:!?\uFF08\uFF09()\u3010\u3011\u300A\u300B\u3008\u3009\u300C\u300D\u300E\u300F\u201C\u201D\u2018\u2019\"'`*#>\u2014\u2026";
+/**
+ * Whether `content` states `subj pred obj` as one clause.
+ *
+ * Returns `false` for an empty part: a blank slot is not a statement (the edge writer refuses it
+ * for a different reason, and this function must not turn that into a match on `(?:^|…)`).
+ */
+export declare function isStatedRelation(content: string, subj: string, pred: string, obj: string): boolean;
+/**
+ * Whether `subj`, `pred` and `obj` appear as ONE contiguous run in `content` — the extractor's
+ * triple-shape invariant, WITHOUT the edge gate's clause-boundary requirement.
+ *
+ * WHY THIS IS NOT {@link isStatedRelation}. Two different questions:
+ *
+ *  - the GATE (`isStatedRelation`) asks whether the fact ASSERTS the relation as a clause, so it
+ *    insists on a boundary before the subject and after the object. It runs on the edge path and
+ *    only for proximity triples (`relations/confidence.ts`);
+ *  - this asks whether the three slots the tokenizer produced are one unbroken run of text at all.
+ *    A triple that fails it was glued together across something the merge is not allowed to cross
+ *    (the 2026-10-25 review measured `张伟在阿里巴巴工作报告` → `张伟阿里巴巴 — 工作 — 报告`), and it
+ *    is refused BEFORE it reaches `triples`: the table feeds contradiction detection, and a
+ *    fragment there is pollution even when the edge gate would refuse the edge anyway.
+ *
+ * Tolerances are the same as the gate's (realis adverbs, one comma splice, an aspect particle,
+ * edge padding), because those are exactly the tokens the merge is allowed to step over. A blank
+ * part is `false` — a slot-less triple is not a statement of anything.
+ */
+export declare function isContiguousTriple(content: string, subj: string, pred: string, obj: string): boolean;

package/lib/engine/mem/relations/types.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The relation module's shapes: what a producer hands over, and what the policy decides.
+ *
+ * WHY THIS MODULE EXISTS. Building an edge used to be spread over three places — `entities/extract`
+ * (candidate rules), `entities/normalize` (the vocabulary) and `db/graph.ts` (the gates AND the
+ * storage). That made "why did this relation not become an edge?" a question about one 900-line
+ * file, and it made the gates unreachable for a producer that is not the string extractor. The
+ * `relations/` module owns the pipeline now:
+ *
+ * ```text
+ *   extractRelationCandidates(text, tokens?)   ← SVO heuristic + explicit patterns (extract.ts)
+ *   normalizeRelation(db, candidate)           ← alias/name + predicate vocabulary (normalize.ts)
+ *   evaluateRelation(normalized, content)      ← name / statement / confidence gates (confidence.ts)
+ *   writeEdgesForFact(db, id, candidates)      ← ids, direction, rows, versions (db/graph.ts)
+ * ```
+ *
+ * `db/graph.ts` only materializes and stores; `entities/` only tags and extracts entity names. A
+ * future LLM or backfill producer implements {@link RelationExtractor} and gets the SAME gates,
+ * because it can only produce candidates.
+ *
+ * @module relations/types
+ */
+/**
+ * The minimum a producer must supply: the three slots, the producer's score and its provenance.
+ *
+ * `confidence` and `source` are optional because a stored `triples` row may predate both — the
+ * column defaults describe a legacy heuristic triple, and the policy reads a missing score as the
+ * heuristic's `0.5` (see `confidence.ts#edgeConfidence`).
+ */
+export interface RelationTripleInput {
+    subj: string;
+    pred: string;
+    obj: string;
+    confidence?: number | null;
+    source?: string | null;
+}
+/** One extracted relation — what `extractRelationCandidates` returns and the write path stores. */
+export interface RelationCandidate extends RelationTripleInput {
+    confidence: number;
+    source: string;
+}
+/**
+ * `triples.source` of the POS/SVO proximity extractor (`relations/extract.ts`).
+ *
+ * Load-bearing, not cosmetic: it is the ONLY source the statement test (`statement.ts`) is applied
+ * to. A curated/LLM/fixture producer already knows the relation, and a caller-asserted one
+ * (`explicit`) outranks any test against the text.
+ */
+export declare const SVO_SOURCE = "svo";
+/** `triples.source` of an explicit pattern (`relations/patterns.ts`) — the cue is evidence. */
+export declare const PATTERN_SOURCE = "pattern";
+/**
+ * `edges.source` for a relation a CALLER stated (`mem_remember.relations`).
+ *
+ * It is the one producer whose triples are not extracted from the text, so it is also the one the
+ * confidence policy trusts outright: no floor, no statement test. `reextractEdges` preserves these
+ * rows instead of re-deriving them (they cannot be re-derived — the fact text does not contain
+ * them).
+ */
+export declare const EXPLICIT_EDGE_SOURCE = "explicit";
+/** Why an extracted relation never became an edge. */
+export type RelationDropReason = 
+/** A slot is blank after trimming — not a relation at all. */
+'blank'
+/** The confidence policy put it below `EDGE_MIN_CONFIDENCE` (`confidence.ts`). */
+ | 'low-confidence'
+/** A slot is not a usable node name (`name-quality.ts`) — the Phase 5b fragment gate. */
+ | 'unusable-name'
+/** A proximity triple (`SVO_SOURCE`) that the fact text never states as a clause. */
+ | 'not-a-statement';
+/** What the policy decided about one normalized relation. */
+export interface RelationEvaluation {
+    /** Whether the edge may be written. */
+    accepted: boolean;
+    /** The confidence the edge would carry — computed even when refused, so a report can show it. */
+    confidence: number;
+    /** Why it was refused; absent when accepted. */
+    reason?: RelationDropReason;
+}