@avantf/dsh-mem 0.6.4 → 0.8.0

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

@@ -0,0 +1,43 @@
+/**
+ * The storage DRIVER contract (docs/DB_DRIVER_LAYOUT.md §二/§八).
+ *
+ * "Adding a storage" = writing one driver directory that implements this interface, not editing a
+ * store. A driver:
+ *
+ *  - declares the `name` its config section is chosen by (`storage.driver`, or the DB-1 alias
+ *    `storage.backend`);
+ *  - declares the CONTRACT MAJOR it was written against (`contractVersion`): the host refuses a
+ *    mismatch at registration AND at open (never a silent fallback);
+ *  - declares what it can do ({@link StorageCapabilities}), so optional behaviour is a flag rather
+ *    than a probe that fails at query time;
+ *  - parses ITS OWN config section (`storage.sqlite`, `storage.fake`, `storage.postgres`), owns its
+ *    connection, schema/migrations, transactions and error mapping, and returns a
+ *    {@link StorageBackend}.
+ *
+ * `open` is async for every driver, including the in-process one: the host must not have two opening
+ * paths, and a remote driver's open is I/O by nature.
+ *
+ * @module interfaces/storage_driver
+ */
+import type { StorageCapabilities } from './capabilities.js';
+import type { StorageBackend } from './storage_backend.js';
+/**
+ * What the host hands a driver at open.
+ *
+ * Deliberately tiny: a driver owns its connection and its configuration. The one thing the host has
+ * to pass is a runtime knob that is NOT the driver's business (the contradiction threshold is a
+ * domain policy the detector is built with, and the detector lives above the storage layer).
+ */
+export interface DriverDeps {
+    /** `lifecycle.contradiction_threshold` — supplied to the contradiction façade at construction. */
+    readonly contradictionThreshold?: number;
+}
+export interface StorageDriver<Config = unknown> {
+    /** The name `storage.driver` selects (also the config section key). */
+    readonly name: string;
+    /** The interface ABI this driver was written against (`interfaces/version.ts`). */
+    readonly contractVersion: number;
+    readonly capabilities: StorageCapabilities;
+    /** Open (or create) the store and return its backend. Rejecting = the host fails to mount. */
+    open(config: Config, deps: DriverDeps): Promise<StorageBackend>;
+}

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

@@ -0,0 +1,34 @@
+/**
+ * The storage HAL's CONTRACT VERSION (docs/DB_DRIVER_LAYOUT.md §八).
+ *
+ * `contractVersion` is the interface ABI, NOT the package version. It exists because a driver and
+ * the host that opens it are independent upgrade units: without a number, a driver built for a
+ * different shape of `StorageBackend` would load, open and then misbehave silently.
+ *
+ * Rules (the doc's §8.2, restated where the code enforces them):
+ *
+ *  - major = a breaking interface change (a method, a parameter or a return's meaning changed);
+ *  - minor = an ADDITIVE change (an optional capability flag, an optional field): old drivers keep
+ *    loading because they simply do not declare it;
+ *  - a driver must implement the major it declares — no "partial implementation";
+ *  - the host verifies the number at REGISTRATION and at OPEN, and refuses with
+ *    {@link UnsupportedStorageContractError}. It never falls back to another driver.
+ *
+ * Bump {@link STORAGE_CONTRACT_VERSION} only with the interface change, and add the previous major to
+ * {@link SUPPORTED_STORAGE_CONTRACT_VERSIONS} when an adapter for it is actually written.
+ *
+ * @module interfaces/version
+ */
+/** The contract major this build implements (`storage/ports` shapes, async boundary). */
+export declare const STORAGE_CONTRACT_VERSION = 2;
+/** The contract majors this host can open. A driver outside this list is refused at registration. */
+export declare const SUPPORTED_STORAGE_CONTRACT_VERSIONS: readonly [2];
+/** The error a driver/host mismatch raises. Explicit refusal, never a silent fallback. */
+export declare class UnsupportedStorageContractError extends Error {
+    readonly driver: string;
+    readonly contractVersion: number;
+    readonly supported: readonly number[];
+    constructor(driver: string, contractVersion: number, supported?: readonly number[]);
+}
+/** Whether this host can open a driver that declares `version`. */
+export declare function supportsStorageContract(version: number): boolean;

package/lib/engine/mem/lifecycle/contradiction.d.ts

@@ -1,4 +1,4 @@
-import { MAX_REPORTED_CONFLICTS, type ContradictionRecord } from '../../mem-contract/index.js';
+import { MAX_REPORTED_CONFLICTS, type ContradictionRecord, type MemoryKind } from '../../mem-contract/index.js';
 import type { Db } from '../db/conn.js';
 import { type ConflictPair, type StoredConflict } from '../db/dao/contradictions.js';
 export { polarityLookupSql, sameSubjPredLookupSql } from '../db/dao/triples.js';
@@ -97,7 +97,7 @@ export declare class ContradictDetector {
     /** Record a verdict on a conflict WITHOUT touching the facts (see `resolveContradiction`). */
     resolve(id: number, resolution: 'true_positive' | 'false_positive', loserFactId?: number): void;
     /** List conflicts for the admin surface (`resolved` 0 = open). */
-    list(resolved?: number, category?: string, threshold?: number, limit?: number): ContradictionRecord[];
+    list(resolved?: number, kind?: MemoryKind, threshold?: number, limit?: number): ContradictionRecord[];
     /** Drain the pending set: the incremental sweep (`admin contradict_check`). */
     /**
      * Check a LIST of facts — the store's durable drain supplies it (`contradict_check`).

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

@@ -0,0 +1,41 @@
+import type { FactsExportCodec } from './facts_io.js';
+/** Hard cap on a file a maintenance action will read (import / merge / restore_snapshot). */
+export declare const MAINTENANCE_MAX_FILE_BYTES: number;
+/** Where an export lands when the caller does not name a file. */
+export declare const MAINTENANCE_BACKUP_DIRNAME = "backups";
+/**
+ * `<data home>/backups/memory-YYYYMMDD-HHMMSS.<ext>` — never inside `memory/`.
+ *
+ * Brotli is the default because it is the smallest (measured: 70.6 KiB vs 92.3 gzip vs 300.0 plain
+ * for 233 facts). A caller that passes another codec keeps the file name truthful by changing the
+ * suffix along with the bytes.
+ */
+export declare function defaultFactsExportPath(home: string, now?: Date, codec?: FactsExportCodec): string;
+/** A resolved export destination, plus whether this call will overwrite an existing file. */
+export interface MaintenanceExportTarget {
+    file: string;
+    existed: boolean;
+}
+/**
+ * Resolve an export destination inside the data root.
+ *
+ * The TARGET may not exist yet (that is the normal case), so containment is established on the
+ * nearest existing ancestor: every component below it is one this call will create, and a
+ * not-yet-created component cannot be a symlink. When the target DOES exist, its realpath is
+ * checked — a symlink pointing outside is refused rather than followed.
+ */
+export declare function resolveMaintenanceExportTarget(home: string, input?: string): MaintenanceExportTarget;
+/**
+ * Resolve an INPUT file (import / merge / restore_snapshot) inside the data root.
+ *
+ * The file must exist, be a regular file, and be no larger than {@link MAINTENANCE_MAX_FILE_BYTES}.
+ * A symlink to a regular file INSIDE the root is usable; a symlink that escapes it is refused before
+ * the size or existence of the outside target is examined.
+ */
+export declare function resolveMaintenanceInputFile(home: string, input: string): string;
+/**
+ * Write a file atomically: a sibling temp file, then one `rename` (same directory, so the rename
+ * cannot cross a filesystem). An overwrite is therefore either the old bytes or the new bytes, never
+ * a truncated export. The temp file is removed when anything fails.
+ */
+export declare function writeFileAtomic(path: string, bytes: Buffer | string): void;

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

@@ -122,7 +122,7 @@ export interface ProvisionSweepResult {
  * It replaced a one-shot model warm-up that sat beside a separate tools sweep, which meant two
  * initialization paths, two logging vocabularies, and no single answer to "is this host fully
  * provisioned?". Callers (the DSH plugin mount, the MCP entry) now make one call, and the per-artifact
- * result lines in the host log come from the same mechanism that installs pandoc.
+ * result lines in the host log come from the same mechanism that provisions each artifact.
  *
  * The FIRST step is the dsh compatibility gate: an incompatible host means NOTHING is resolved,
  * installed or warmed — preparing an environment for an API we cannot drive is wasted mission.

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

@@ -0,0 +1,39 @@
+import type { NormalizedRelation } from './normalize.js';
+import { type RelationEvaluation } from './types.js';
+/**
+ * Edges below this confidence are NOT written (§4.3: "低置信度不写 edges，或写但 planner 不默认
+ * 使用" — this store takes the first option, because an unqueryable edge is still a lie a later
+ * reader can see).
+ *
+ * The number is a POLICY, kept in one place so a gold set (R6) can move it:
+ *
+ *  - a triple whose predicate is CURATED (a described relation — see `PredicateRef.curated` in
+ *    `normalize.ts`; every seeded family is, and so is one an operator registered with a
+ *    description) scores `min(1, base + 0.25)` → 0.75 at the extractor's 0.5, well above the line;
+ *  - an undescribed predicate scores `base × 0.6` → 0.3, below it, so the relation stays a
+ *    legacy triple + content hit and never enters the graph. That is the §R3 stance: a wrong edge
+ *    is worse than a missing one, and "计划/听说/可能" style verbs must not become facts.
+ *  - a high-confidence non-heuristic triple (an `llm` row at 0.9 → 0.54) still qualifies, because
+ *    the confidence came from the producer rather than from our vocabulary.
+ */
+export declare const EDGE_MIN_CONFIDENCE = 0.5;
+/** An explicit relation's confidence: the caller asserted it, so there is no score to compute. */
+export declare const EXPLICIT_EDGE_CONFIDENCE = 1;
+/**
+ * The confidence an edge carries, as a pure function of the producer's score and one bit of
+ * vocabulary knowledge.
+ */
+export declare function edgeConfidence(tripleConfidence: number | null | undefined, curatedPredicate: boolean): number;
+/**
+ * Decide whether one normalized relation may become an edge — and with what confidence.
+ *
+ * The result is a decision, not a mutation: the caller (`db/graph.ts#resolveForEdge`) keeps its own
+ * drop accounting (it adds the post-resolution `self-relation` case, which needs ids), and a
+ * refused relation is reported with the reason so a coverage report can say WHERE the relation was
+ * lost.
+ *
+ * `content` is the fact's text; it is what the statement test reads. A caller without text (a dry
+ * run over an `.svo` triple) gets `''`, which can only refuse an `svo` triple — the honest answer,
+ * since nothing is known to have stated it.
+ */
+export declare function evaluateRelation(relation: NormalizedRelation, content: string): RelationEvaluation;

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

@@ -0,0 +1,128 @@
+/**
+ * Relation CANDIDATE extraction — the two producers that read a fact's text, and the seam a third
+ * producer would implement (docs/RELATIONAL_RECALL.md §4.3/R3, §十七).
+ *
+ * WHAT A CANDIDATE IS. `(subj, pred, obj)` plus the producer's confidence and provenance. A
+ * candidate is NOT an edge: nothing here resolves names, applies the gates or touches a database.
+ * The pipeline is
+ *
+ * ```text
+ *   extractRelationCandidates(text, tokens?)  ← THIS module (SVO heuristic + explicit patterns)
+ *   normalizeRelation(db, candidate)          ← normalize.ts (aliases, predicate vocabulary)
+ *   evaluateRelation(normalized, content)     ← confidence.ts (name / statement / confidence gates)
+ *   writeEdgesForFact(db, factId, candidates) ← db/graph.ts (ids, direction, rows)
+ * ```
+ *
+ * THREE READINGS, ONE ENTRY POINT. The POS/SVO heuristic, the curated vocabulary's surface matching
+ * (`主管`/`隶属于`/`汇报`/`部署在` are nouns to the tagger, relations to the store) and the explicit
+ * patterns are three readings of the same text; they must not disagree about what counts as a
+ * candidate, so one function returns all of them (the write path, `update`, and the entity sweep all
+ * call {@link relationCandidatesFromText}). The pattern half needs the RAW TEXT, which is why the
+ * entry point takes both the content and its tokens — and why the token-based half is additionally
+ * filtered by `relations/statement.ts#isContiguousTriple`: its arguments come from proximity, so a
+ * merge that crossed a clause boundary must not reach `triples`.
+ *
+ * THE TOKENS COME FROM `entities/extract.ts`. Tagging is the expensive step (~1.1 ms per 1000
+ * characters) and the entity half needs it too, so the write path tags ONCE and hands the same
+ * array to both — `relationCandidatesFromText` is the sync form for exactly that caller.
+ * `extractRelationCandidates` is the standalone form: omit `tokens` and it tags; pass `null` to say
+ * "the tagger is unavailable" (patterns still run, the token-based halves produce nothing).
+ *
+ * @module relations/extract
+ */
+import { type PosToken } from '../entities/extract.js';
+import { type RelationCandidate } from './types.js';
+/**
+ * Predicates that are a verb in form only — the tokenizer's reading of them carries no relation.
+ *
+ * `属于` used to sit here while `relations/normalize.ts#PREDICATE_VOCABULARY` curates the 属于 family
+ * (`归属/隶属于/隶属`), so the canonical form was unreachable and only an alias could produce the
+ * `属于` edge (`项目归属平台组` worked, `项目属于平台组` produced nothing) — the 2026-10-25 review's
+ * §2.1. The invariant that prevents a repeat is `STOP_PREDICATES ∩ curated surfaces = ∅`, asserted
+ * in `test/relation_extraction.spec.ts`: a word this list refuses may not be a word the vocabulary
+ * promises to extract.
+ *
+ * EXPORTED for that test. It is a closed list of closed-class verbs (`是`, `有`, `可以`, `成为`…),
+ * not a tuning knob.
+ */
+export declare const STOP_PREDICATES: Set<string>;
+/** A query's triple shape: an interrogative slot is a wildcard (`undefined`). */
+export interface TriplePattern {
+    subj?: string;
+    pred?: string;
+    obj?: string;
+}
+/**
+ * The POS/SVO half: triples from ALREADY-TAGGED tokens (`null` = tagger unavailable → no triples).
+ *
+ * The triples are stamped `source: 'svo'` (Phase 5b): they are the product of a PROXIMITY heuristic,
+ * so the graph holds them to the "was this actually stated?" test in `relations/statement.ts`.
+ *
+ * STRICT AND WEAK ARE MERGED, not fallbacks (2026-10-25 review §六). The old rule ran the weak
+ * reading (`vn`/preposition) only when the strict verbs produced NOTHING, so one strict candidate —
+ * which the gates might refuse a moment later — suppressed a weak candidate that would have become a
+ * real edge. Both readings now contribute, deduplicated, and the gates decide.
+ */
+export declare function svoCandidatesFromTokens(rawTokens: PosToken[] | null): RelationCandidate[];
+/**
+ * The curated vocabulary's reading of a tagged text: one candidate per surface OCCURRENCE, with the
+ * same left/right argument merge the SVO half uses.
+ *
+ * A surface matches only as a whole TOKEN RUN (`工作于` = `工作` + `于`), which is the boundary rule:
+ * a tokenizer boundary is a word boundary, so `工作区` (`工作` + `区`) can never match `工作` and the
+ * `区` cannot be read as an object either. `pred` is the SURFACE as written (`汇报`, `部署在`), not
+ * the canonical name: `relations/normalize.ts` maps it, and `relations/statement.ts` has to test the
+ * word the fact actually contains.
+ *
+ * Stamped `source: 'svo'` on purpose. A curated word is evidence that a RELATION was written, not
+ * evidence of who did what to whom — the arguments still come from proximity, so the statement gate
+ * must run. (`relations/patterns.ts` is the half that carries a syntactic cue; those triples are
+ * `source: 'pattern'`.)
+ */
+export declare function vocabularyCandidatesFromTokens(rawTokens: PosToken[] | null): RelationCandidate[];
+/**
+ * EVERYTHING the write path turns into `triples` + `edges`: the two token-based producers above plus
+ * the explicit patterns of `relations/patterns.ts`, deduplicated.
+ *
+ * The token-based half is filtered by {@link isContiguousTriple} first: a candidate whose three slots
+ * are not one unbroken run of the fact text came out of a merge that crossed a clause boundary, and
+ * it must not reach `triples` at all (the review's §五 `张伟阿里巴巴 — 工作 — 报告`). Pattern triples
+ * are exempt: their predicate is the CANONICAL name and their evidence is the cue, so the text does
+ * not contain the three slots literally — `relations/patterns.ts` enforces its own boundaries.
+ *
+ * Sync on purpose: the caller already tagged the text for the entity half, and re-tagging here would
+ * pay the dictionary cost twice for one write (see the module note).
+ */
+export declare function relationCandidatesFromText(text: string, tokens: PosToken[] | null): RelationCandidate[];
+/**
+ * The module's candidate-extraction API: every relation this text yields, with one tagging pass.
+ *
+ * `tokens` is the SAME tagging pass a caller may already have (see `entities/extract.ts#tagText`);
+ * omit it to tag here, or pass `null` when the tagger is unavailable. The resolved value is
+ * candidates only — the caller still has to normalize and evaluate them before anything is stored.
+ */
+export declare function extractRelationCandidates(text: string, tokens?: PosToken[] | null): Promise<RelationCandidate[]>;
+/**
+ * A relation PRODUCER — the seam for anything that is not the string extractor (a later LLM pass,
+ * the legacy backfill, a test fixture).
+ *
+ * `extract` may only produce CANDIDATES: it cannot normalize, evaluate or write anything, so
+ * implementing this interface is not a way around the name/statement/confidence gates. `id` is what
+ * a coverage report can attribute a candidate to.
+ */
+export interface RelationExtractor {
+    readonly id: string;
+    extract(text: string, tokens?: PosToken[] | null): Promise<RelationCandidate[]>;
+}
+/** The engine's own producer: the POS/SVO heuristic plus the explicit patterns. */
+export declare const ruleBasedRelationExtractor: RelationExtractor;
+/**
+ * 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>;

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

@@ -0,0 +1,32 @@
+/**
+ * The relation module's front door.
+ *
+ * WHAT BELONGS HERE. One relation edge is decided by four steps, and this module owns the first
+ * three; the fourth (rows, ids, direction) is storage and lives in `db/graph.ts`:
+ *
+ * ```text
+ *   extractRelationCandidates(text, tokens?)  candidates from the text — no database
+ *   normalizeRelation(db, candidate)          alias/name + predicate vocabulary
+ *   evaluateRelation(normalized, content)     name / statement / confidence gates
+ *   writeEdgesForFact(db, factId, candidates) ids, direction, rows, extraction_version
+ * ```
+ *
+ * Nothing else in the engine needs to know which rule produced a candidate: `db/graph.ts` reads the
+ * policy from here, `store/memory.ts` reads the extractor from here, and the caller-relation
+ * validator (`store/explicit_relations.ts`) reads the same name gate every extracted edge passes.
+ * A producer that is not the string extractor implements {@link RelationExtractor} and gets the same
+ * gates for free.
+ *
+ * The module is importable BY PATH (`relations/extract.js`, …) like every other internal module;
+ * the names below are the ones the rest of the engine (and a future LLM/backfill producer) should
+ * use, so a rule exists in exactly one place.
+ *
+ * @module relations
+ */
+export { STOP_PREDICATES, extractRelationCandidates, relationCandidatesFromText, svoCandidatesFromTokens, vocabularyCandidatesFromTokens, ruleBasedRelationExtractor, parseQueryPattern, type RelationExtractor, type TriplePattern, } from './extract.js';
+export { ensureRelationalVocabulary, isSymmetricPredicate, normalizeRelation, parseAliasPairs, registerEntityAlias, registerEntityAliasesFromText, resolveEntity, resolvePredicate, stripAliasClause, PREDICATE_VOCABULARY, type AliasPair, type AliasRegistration, type AliasSkipReason, type EntityRef, type NormalizedRelation, type PredicateDirection, type PredicateRef, type PredicateSeed, type ResolveOptions, type ResolveVia, type VocabularySeedReport, } from './normalize.js';
+export { EDGE_MIN_CONFIDENCE, EXPLICIT_EDGE_CONFIDENCE, edgeConfidence, evaluateRelation, } from './confidence.js';
+export { GRAPH_NAME_MAX_CHARS, GRAPH_NAME_MAX_CJK_CHARS, graphNameIssue, isGraphName, stripParentheticalSuffix, type GraphNameIssue, } from './name-quality.js';
+export { CLAUSE_BOUNDARY_CHARS, isContiguousTriple, isStatedRelation } from './statement.js';
+export { PATTERN_TRIPLE_CONFIDENCE, patternTriples, patternTriplesWithReport, type PatternYield, } from './patterns.js';
+export { EXPLICIT_EDGE_SOURCE, PATTERN_SOURCE, SVO_SOURCE, type RelationCandidate, type RelationDropReason, type RelationEvaluation, type RelationTripleInput, } from './types.js';

package/lib/engine/mem/relations/name-quality.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Is a string a plausible NAME for a graph node? — the deterministic quality gate of Phase 5b
+ * (docs/RELATIONAL_RECALL.md §4.3/R3, §十七).
+ *
+ * WHY THIS EXISTS. The POS/SVO heuristic (`relations/extract.ts`) merges the noun-ish tokens on each
+ * side of a verb, and on real prose (long engineering notes) that rule happily produces slots like
+ * `）。**`, `，仓库…` or `包与CLI/MCP）。`. Phase 5a measured the result on a live snapshot: 69 of the
+ * 87 entity names in the active graph contained punctuation, and every edge v1 accepted was a clause
+ * fragment rather than a relation. A node whose name is a sentence fragment cannot be asked about,
+ * so it is worse than a missing node: it makes `relationCoverage` look healthy while the graph
+ * answers nothing (§R3's "错误边比缺失边更危险").
+ *
+ * The gate is a SHAPE test, not a semantics test. It cannot tell `阿里巴巴` (a company) from
+ * `发布节奏` (a compound noun) — that needs the statement test in `relations/statement.ts`. What it
+ * does guarantee is that every name the graph stores is a bounded, punctuation-free token, which is
+ * the precondition for the statement test to mean anything.
+ *
+ * Rules, each derived from the live failure samples (2026-10-25):
+ *
+ *  - **identifier form is accepted as-is.** `@avantf/dsh-mem`, `v0.1.5`, `104.16.0.34`,
+ *    `packages/core` are names in this store's corpus, and their punctuation (`.` `/` `-` `+` `@`
+ *    `:`) is part of the name. They are matched by {@link IDENTIFIER_NAME}, so the punctuation rules
+ *    below cannot reject them (the length bounds still apply).
+ *  - **markup / quotes / brackets are refused.** A name that came out of Markdown emphasis, a code
+ *    span, a quotation or a parenthesis is a fragment of formatting, not a name.
+ *  - **sentence punctuation is refused.** Chinese commas/periods inside a slot mean the merge ran
+ *    across a clause boundary.
+ *  - **whitespace is refused.** The extractor joins tokens without spaces, so a space inside a
+ *    slot means two tokens the tokenizer did not consider adjacent. (A multi-word ASCII name is the
+ *    one case this loses; the live corpus has none, and accepting spaces would readmit clauses.)
+ *  - **the name must carry a letter or digit.** Pure symbols (`——`, `**`, `（）`) are not nodes.
+ *  - **length is bounded**: {@link GRAPH_NAME_MAX_CHARS} overall, {@link GRAPH_NAME_MAX_CJK_CHARS}
+ *    for a name with CJK in it. Chinese has no spaces, so a long CJK run is a clause; the shorter
+ *    bound is what rejects it. Latin identifiers keep the longer one.
+ *  - **a clause particle at the start is refused** (`的了着而并且或把被让`). A slot that OPENS with one
+ *    starts mid-clause (`的那个工作区` passed for `当前会话所在的那个工作区`). The rule is deliberately
+ *    starts-only: Chinese compounds routinely END in characters from that set, so a tail rule would
+ *    reject `知识入库的规则`, `参与` and `行为` — measured against the live graph, the tail rule cost
+ *    more real names than fragments.
+ *
+ * The gate is used by the EDGE writer (`db/graph.ts#resolveForEdge`) and by the caller-relation
+ * validator (`store/explicit_relations.ts`). `entities`/`fact_entities` keep the extractor's raw
+ * names: content recall searches what was written, and narrowing that is a different (and riskier)
+ * change.
+ *
+ * @module relations/name-quality
+ */
+/** Longest name the graph accepts, in characters (a package path or a version fits; a clause does not). */
+export declare const GRAPH_NAME_MAX_CHARS = 40;
+/**
+ * Longest name the graph accepts when it contains CJK, in characters.
+ *
+ * Chinese needs no spaces, so this is the only length signal that separates a name (`阿里巴巴`,
+ * `支付网关`) from a clause (`用户可以立即重发一个新版本`). 20 leaves room for names like
+ * `知识入库的规则` while rejecting sentence-shaped runs.
+ */
+export declare const GRAPH_NAME_MAX_CJK_CHARS = 20;
+/** Why a string cannot be a graph node name. */
+export type GraphNameIssue = 'blank' | 'too-long' | 'markup' | 'punctuation' | 'whitespace' | 'no-content' | 'long-clause' | 'function-word';
+/**
+ * Classify `name` against the graph's name rules — `undefined` means "usable as a node".
+ *
+ * Pure and total: the edge writer calls it for both slots of every triple, so it must not throw
+ * on any input (the extractor can hand it anything the tokenizer produced).
+ */
+export declare function graphNameIssue(name: string): GraphNameIssue | undefined;
+/** Whether {@link graphNameIssue} accepts `name` (the boolean form callers usually want). */
+export declare function isGraphName(name: string): boolean;
+/**
+ * Drop a parenthetical suffix when what remains is still a name: `阿里巴巴（阿里）` → `阿里巴巴`.
+ *
+ * The extractor merges brackets into the slot (`阿里巴巴（阿里）` is one argument), and the graph's
+ * own alias rule already strips a PARENTHESISED ALIAS STATEMENT (`（又名 老张）`). A bare parenthesis
+ * — the common "full name (short name)" form — is not an alias statement and has no canonical
+ * side, so the graph uses the head. Only a TRAILING group is dropped, and only when the head is a
+ * usable name; anything else is returned unchanged so a caller never receives an invented name.
+ */
+export declare function stripParentheticalSuffix(name: string): string;