@avantf/dsh-mem 0.3.1 → 0.4.0

package/lib/engine/mem/db/port.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The relational access port — the ONE place the engine is allowed to say "a database".
+ *
+ * Stores, lifecycle code and DAOs depend on this interface, never on a driver class, so the
+ * database is ONE adapter (`sqlite.ts`, over the runtime's own `node:sqlite`) rather than a
+ * driver smeared through 50 call sites — and the contract that adapter owes is written down in that
+ * file. This is deliberately NOT a query builder or an ORM: the SQL stays SQL (FTS5,
+ * `INDEXED BY`, partial indexes and `julianday` are load-bearing — see DESIGN §19), and the
+ * port only fixes the *shape* of the conversation.
+ *
+ * The surface is five methods on purpose: `prepare / exec / transaction / pragma / close` is
+ * the entire driver API this project uses (104 `prepare`, 11 `exec`, 9 `transaction`, 6
+ * `pragma`, 4 `close` call sites, and none of the statement extras such as
+ * `pluck`/`raw`/`iterate`/`columns`/`function`/`loadExtension`).
+ *
+ * SYNCHRONOUS by design: `persistFact` runs contradiction detection inside its transaction
+ * and the lifecycle tick is one synchronous pass, so an async driver does not fit this port.
+ * That is a decision, not an oversight.
+ */
+export interface DbRunResult {
+    changes: number;
+    lastInsertRowid: number | bigint;
+}
+/**
+ * A prepared statement. Rows are asserted by the caller.
+ *
+ * Params are either positional (`?`, one argument each — `run(a, b)`) or a single object
+ * binding the statement's named parameters (`:step`, `@step` and `$step` all match the key
+ * `step`, with or without the prefix). Both forms are forwarded to the driver untouched, so a
+ * DAO can keep a long predicate readable instead of counting `?` positions — `facts.ts` uses
+ * the named form for the settlement clock and the trust diagnostics.
+ */
+export interface DbStatement<Row = unknown> {
+    all(...params: unknown[]): Row[];
+    get(...params: unknown[]): Row | undefined;
+    run(...params: unknown[]): DbRunResult;
+}
+/**
+ * A transaction runner: call it to execute inside a transaction, or pick a lock mode.
+ *
+ * `immediate()` is load-bearing, not a convenience: the presence clock and the lifecycle
+ * tick do a cross-process read-modify-write, and only `BEGIN IMMEDIATE` takes the write lock
+ * before the first read. A port without it would have silently degraded those paths.
+ */
+export interface DbTransaction<T> {
+    (): T;
+    immediate(): T;
+    deferred(): T;
+    exclusive(): T;
+}
+export interface Db {
+    prepare<Row = unknown>(sql: string): DbStatement<Row>;
+    exec(sql: string): void;
+    transaction<T>(fn: () => T): DbTransaction<T>;
+    pragma(source: string): unknown;
+    close(): void;
+}

package/lib/engine/mem/db/schema.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Memory DB schema.
+ *
+ * `DDL` is the BASE schema (migration 1) and stays idempotent: databases created before the
+ * versioning mechanism existed report `user_version = 0` while already holding these tables,
+ * so adopting them must be a no-op plus a version stamp (see `migrations.ts`). Later schema
+ * changes belong in a numbered migration — `ONE_OPEN_CONTRADICTION_ROW_SQL` below is v2.
+ */
+export declare const DDL: string[];
+/**
+ * v2 — at most one OPEN row per contradiction pair.
+ *
+ * The in-process `suppressedPairs` dedupe cannot see another process, and the dsh host, the CLI
+ * and the MCP server all open this same database. Resolved rows are exempt, so a pair may
+ * legitimately be re-opened after it was retired (archive → restore → re-detect). The DELETE
+ * runs first because a database written by an older build may already hold duplicates for an
+ * open pair, and `CREATE UNIQUE INDEX` would then refuse to build at all.
+ */
+export declare const ONE_OPEN_CONTRADICTION_ROW_SQL: string[];
+/**
+ * The external-content FTS5 table. Created separately from {@link DDL} because the
+ * tokenizer is chosen at open time by the runtime self-check (`resolveFtsTokenizer`)
+ * — a build without `trigram` must not make the store unopenable (DESIGN §16).
+ */
+export declare function factsFtsTableDdl(tokenizer: string): string;
+export declare const FTS_TRIGGERS: string[];

package/lib/engine/mem/db/sqlite.d.ts

@@ -0,0 +1,89 @@
+import type { Db } from './port.js';
+/**
+ * The slice of the `node:sqlite` builtin this port uses, declared structurally.
+ *
+ * Not imported from `@types/node`: the module lives behind its own release line (its typings appeared
+ * part-way through the Node 22 line) and the engine must type-check against whatever `@types/node` a
+ * consumer's build resolves. Declaring the four signatures the port actually calls keeps that
+ * independent.
+ */
+interface RawNodeStatement {
+    all(...params: unknown[]): unknown[];
+    get(...params: unknown[]): unknown;
+    run(...params: unknown[]): {
+        changes: number | bigint;
+        lastInsertRowid: number | bigint;
+    };
+    /**
+     * Present from Node v22.15 / v23.11 (see {@link sqliteProbe}, which refuses a runtime without it).
+     * Optional in the type so this file still compiles against an older `@types/node`.
+     */
+    setAllowUnknownNamedParameters?(enabled: boolean): void;
+}
+interface NodeSqliteDatabase {
+    prepare(sql: string): RawNodeStatement;
+    exec(sql: string): void;
+    close(): void;
+}
+/**
+ * The builtin's module shape, as far as this adapter is concerned.
+ *
+ * Exported for {@link probeModule}'s callers — the contract spec hands it a fake.
+ */
+export interface NodeSqliteModule {
+    DatabaseSync: new (path: string) => NodeSqliteDatabase;
+}
+/**
+ * Whether this runtime can actually SERVE the stores through `node:sqlite`, or why it cannot.
+ *
+ * Constructing a throwaway `:memory:` handle is only the first half. A runtime can expose the module
+ * and still be unusable for this engine in two ways that would otherwise surface much later, as a DDL
+ * error or as a broken lifecycle tick in production:
+ *
+ *  - **no FTS5** — both schemas create `fts5` virtual tables the moment a store is opened, so a build
+ *    without the module cannot hold a store at all;
+ *  - **no `setAllowUnknownNamedParameters`** (Node v22.15 / v23.11) — `node:sqlite` throws on a named
+ *    parameter the statement does not use, while the DAOs deliberately pass one params object to
+ *    statements that use subsets of it. Without the switch, `FactsDao.purgeArchived` takes the whole
+ *    lifecycle tick down.
+ *
+ * The probe reports the FIRST of these that applies as one line; `undefined` means "this runtime can
+ * serve a store". It is NOT a dry run of the caller's database: a file that is corrupt, locked or
+ * written by a newer schema must still fail loudly in {@link openSqlite} (and mount DEGRADED with its
+ * own reason) rather than being reported as a driver problem.
+ */
+export declare function sqliteProbe(): string | undefined;
+/**
+ * The capability half of {@link sqliteProbe}: what a loaded `node:sqlite` module must be able to do.
+ *
+ * Exported — and taking the module as an argument — so the contract spec can hand it a FAKE and
+ * assert each refusal by name. That is not a driver seam: it is the only way to exercise "this
+ * runtime's builtin cannot serve a store" on a machine whose builtin can, and the failure path is
+ * exactly the one nobody sees until it happens on a user's host.
+ */
+export declare function probeModule(module: NodeSqliteModule): string | undefined;
+/**
+ * A one-line, NEVER-THROWING description for the startup log.
+ *
+ * The runtime logs this before it opens the stores, so it must not be the thing that turns "this
+ * runtime cannot serve the builtin" into a crash before the caller's own error handling runs. The
+ * version is part of the line on purpose: the store files stay per-host (a Desktop HOME and a WSL
+ * HOME are different machines' worth of data), so the SQLite version is the one fact that tells an
+ * operator WHICH build is answering — and the fact to quote when a query behaves differently across
+ * two hosts. A refused runtime is reported as such, so this line and the later DEGRADED mount agree.
+ */
+export declare function describeSqlite(): string;
+/**
+ * Open (or create) a SQLite database behind the port. `':memory:'` is a valid path.
+ *
+ * The runtime's verdict is checked HERE, not only by the startup log: a runtime whose builtin cannot
+ * serve a store (no FTS5, or no tolerance for unused named parameters — see {@link sqliteProbe}) must
+ * fail this open, so the caller's own error handling degrades the plugin with that reason instead of
+ * the engine discovering it half-way through a schema migration or a lifecycle tick.
+ *
+ * `verdict` is a TEST seam, and deliberately not a driver seam: there is one implementation and it
+ * cannot be replaced at runtime. It exists so the refusal path can be asserted on a machine whose
+ * builtin missions — the path nobody sees until a user hits it.
+ */
+export declare function openSqlite(path: string, verdict?: () => string | undefined): Db;
+export {};

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

@@ -0,0 +1,35 @@
+import type { Db } from './port.js';
+import { type Migration, type MigrationResult } from './migrations.js';
+import type { FtsTokenizer } from './tokenizer.js';
+/** One store's schema: only the migration steps and a label for diagnostics. */
+export interface StoreSchema {
+    readonly describe: string;
+    readonly migrations: readonly Migration[];
+}
+export interface OpenedStore {
+    readonly db: Db;
+    /** Which steps ran on THIS open (`from`/`to` make a stale store obvious in a log line). */
+    readonly migration: MigrationResult;
+}
+/**
+ * One read-only diagnostic for the startup log, built entirely from the open's already-returned
+ * result — it must never touch the database, block, or throw.
+ *
+ * It is defined for both states (`schema up to date (9)` and `schema upgraded 8 → 9 (applied: 9
+ * contradiction-resolved-indexes)`), but callers are expected to EMIT only the upgraded form: an
+ * up-to-date store is the normal case and does not deserve a line on every boot. The helper exists
+ * so that state is still assertable and so both stores phrase it identically.
+ */
+export declare function describeMigrationOutcome(schema: StoreSchema, migration: MigrationResult): string;
+/** Whether this open actually applied anything (`false` = the store was already current). */
+export declare function wasUpgraded(migration: MigrationResult): boolean;
+/**
+ * Open (or create) a store database: directory, PRAGMAs, then every migration newer than
+ * the file's `user_version`. A failure closes the handle — an open handle keeps the WAL and
+ * its locks alive, and a half-open store would be worse than none.
+ */
+export declare function openStoreDb(opts: {
+    path: string;
+    schema: StoreSchema;
+    tokenizer: FtsTokenizer;
+}): OpenedStore;

package/lib/engine/mem/db/tokenizer.d.ts

@@ -0,0 +1,61 @@
+import type { Db } from './port.js';
+/** FTS5 tokenizer actually used to build the `*_fts` tables. */
+export type FtsTokenizer = 'trigram' | 'unicode61';
+/** Whether this SQLite build supports the CJK-aware FTS5 `trigram` tokenizer. */
+export declare function trigramAvailable(): boolean;
+/**
+ * Choose the tokenizer for newly created FTS tables — DESIGN §16 mitigation.
+ *
+ * A build without `trigram` must not make the store unopenable: fall back to
+ * `unicode61` (CJK recall degrades to exact/whole-token matching) and say so once.
+ * This has to run BEFORE the schema DDL, because `CREATE VIRTUAL TABLE … TOKENIZE
+ * trigram` on such a build throws.
+ */
+export declare function resolveFtsTokenizer(): FtsTokenizer;
+/**
+ * The tokenizer an EXISTING FTS table was actually built with, or `null` if there is no such table.
+ *
+ * Read from `sqlite_master` — not from a stored flag, and not from this build's probe. `CREATE
+ * VIRTUAL TABLE IF NOT EXISTS` never rebuilds an existing table, so what the index contains was
+ * decided by the DDL that ran when the database was first created: possibly years ago, possibly on
+ * another machine, possibly against a SQLite build with different FTS5 support. Querying it with
+ * the OTHER convention is silent zero recall — a trigram table cannot match a whole-token phrase and
+ * a unicode61 table cannot match a 3-gram, and neither raises an error. The store therefore asks the
+ * database which tokenizer it has, and builds MATCH expressions for THAT one.
+ */
+export declare function detectFtsTokenizer(db: Db, table: string): FtsTokenizer | null;
+/**
+ * Say something when a database's FTS table is WEAKER than what this SQLite build could give it.
+ *
+ * Only that direction is worth a line. The reverse (a trigram table opened by a build without
+ * trigram support) loses nothing: the queries are built for the table that exists, so recall is
+ * exactly what it was. But a unicode61 table opened by a trigram-capable build means CJK full-text
+ * recall is limited to whole-token matches — a real, invisible degradation that an operator can fix,
+ * so it is reported once with the remedy named.
+ *
+ * @param label  store label for the message
+ * @param table  the FTS table whose DDL was read
+ * @param detected what {@link detectFtsTokenizer} found (`null` = the table does not exist yet)
+ * @param remedy how to rebuild that table, or `null` when no operator-facing command does
+ */
+export declare function reportFtsTokenizerDrift(label: string, table: string, detected: FtsTokenizer | null, remedy: string | null): void;
+/**
+ * The most OR phrases one query may expand to.
+ *
+ * 64 is far past any query a person types (a 64-character CJK run), and it is the ceiling that keeps a
+ * pathological input from turning `MATCH` into minutes of synchronous mission inside the host process.
+ */
+export declare const MAX_FTS_PHRASES = 64;
+/**
+ * Build an FTS5 MATCH expression for the tokenizer the tables were created with.
+ *
+ * - `trigram`: CJK tokens become OR-joined 3-grams (a phrase needs ≥3 chars);
+ *   latin tokens are quoted whole (≥3 chars — the trigram minimum).
+ * - `unicode61` (fallback build): whole-token phrases; CJK is NOT n-grammed
+ *   (trigram phrases can never match a unicode61 table, so emitting them there
+ *   would mean silent zero recall — the old duplicated builders did exactly that).
+ *
+ * One implementation for memory + knowledge (the two copies had already drifted
+ * once when the tokenizer fallback landed).
+ */
+export declare function buildFtsQuery(query: string, tokenizer?: FtsTokenizer): string | null;

package/lib/engine/mem/db/vectors.d.ts

@@ -0,0 +1,50 @@
+import type { VectorStore } from '../../mem-retrieval/index.js';
+/** Little-endian Float32 ↔ BLOB helpers for persisted vectors (cross-platform stable). */
+export declare function float32ToBytes(vec: Float32Array): Buffer;
+export declare function bytesToFloat32(buf: Uint8Array | null | undefined): Float32Array | null;
+/**
+ * Identity of a VECTOR SPACE: which backend, which model, how wide.
+ *
+ * Persisted beside every vector (`facts.embedding_model`, `doc_chunks.embedding_model`) so
+ * "these vectors came from a different model" is detectable. It used to record only the
+ * backend name, which made a same-width model swap (bge-small-zh → bge-m3, both 512d)
+ * indistinguishable from "already encoded": the two spaces then shared one index and were
+ * ranked against each other.
+ *
+ * The vector STORE is deliberately not part of the identity: numpy vs hnswlib indexes the
+ * same vectors, so switching it must not trigger re-encoding (that is `reloadIndex`).
+ */
+export declare function vectorSpaceId(backend: string, model: string, dim: number): string;
+/**
+ * Rebuild a live vstore from persisted vector BLOBs — the restart-recovery path
+ * shared by both stores (the two copies had already drifted: memory warned on
+ * dim mismatches, knowledge dropped them silently).
+ *
+ * The rows come from the owning store's DAO (DESIGN §19): this helper decodes and
+ * filters them, it never runs SQL itself.
+ *
+ * @param rows - `id` (fact/chunk id) + `vec` (BLOB), as read back from the store.
+ * @param label - store name used in the dim-mismatch warning.
+ */
+export declare function reloadVectorIndex(vstore: VectorStore, rows: readonly {
+    id: number;
+    vec: Uint8Array | null;
+}[], label: string): {
+    loaded: number;
+    skipped: number;
+};
+/**
+ * On-disk ANN snapshot PREFIX for a store's vector index (the adapter appends
+ * `.<fingerprint>.hnsw`), or `null` when the database has no file to sit beside.
+ *
+ * The VECTOR SPACE is part of the name, not just of the rows: a snapshot is a serialized graph, so
+ * loading one built from another model (or width) would silently serve vectors that describe
+ * different text. Embedding the space means a model swap looks for a different file, and the
+ * adapter's fingerprint covers everything else (see `HnswlibVectorStore.snapshotPath`).
+ *
+ * The space is `encodeURIComponent`-escaped rather than sanitized: lossy replacement mapped `a/b`
+ * and `a_b` onto the SAME name, which is exactly the collision this path exists to prevent.
+ * `:memory:` (or any non-file path) returns `null` — otherwise the snapshot is written into the
+ * process working directory under a `:memory:.…` name.
+ */
+export declare function vectorCachePath(dbPath: string, space: string): string | null;

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

@@ -0,0 +1,51 @@
+/**
+ * The model-facing tool dispatch, shared by EVERY surface that answers a contract tool key: the DSH
+ * plugin's tool runner, the plugin's Remote gateway (the operator UI) and the MCP server.
+ *
+ * It lives here rather than in each adapter because the key set is owned by the contract's
+ * `TOOL_SPECS`, and an adapter that hand-writes its own switch rots silently when a spec is added.
+ * That is a measured failure, not a hypothetical: `kb_add`/`kb_list`/`kb_remove`/`kb_reindex` were
+ * advertised by the MCP server's `tools/list` while its dispatcher still knew only the five older
+ * keys, so all four answered `unknown tool key` — a tool that is listed, callable, and always
+ * broken. One table keyed by the contract, plus {@link supportsToolKey} so a spec test can assert
+ * "every advertised key dispatches" instead of trusting a hand-maintained list.
+ *
+ * `ToolSpec.key` is typed `string` (not a literal union), so exhaustiveness cannot be checked at
+ * compile time — the spec assertion is the gate.
+ */
+import type { KbAddRequest } from '../mem-contract/index.js';
+import type { AvantfRuntime } from './runtime.js';
+/**
+ * The default page for a model-facing `kb_list`.
+ *
+ * Without one, `kb_list` on a large library read and parsed EVERY managed file (resolving a path
+ * needs the file's frontmatter to detect collisions) to answer a question nobody asked in full.
+ */
+export declare const KB_LIST_DEFAULT_LIMIT = 50;
+/**
+ * The `kb_add` handler: a thin shell over the runtime's ADD-ONLY face (`rt.kbAdd`), which shares the
+ * store's plan/classify/dispatch entry with the UI's 入库 (`rt.kb`) and differs only in the mode.
+ *
+ * This is the fix for a measured failure: told to "update the KB", a model called the old all-in-one
+ * tool with a *new* title, which silently created a sibling document (《… · 补遗》) while the
+ * original stayed behind — two overlapping documents, and the reader left to reconcile them.
+ * Replacing is now an explicit file edit.
+ *
+ * The refusal itself lives in the STORE (the plan stage), not here: a pre-check in this handler used
+ * to derive the title as `req.title ?? req.source`, which is exactly the fallback the store no
+ * longer uses — so once the store derives an untitled paste from its body, a local pre-check would
+ * check a different identity than the one the store actually writes.
+ */
+export declare function kbAdd(rt: AvantfRuntime, data: KbAddRequest): Promise<unknown>;
+/** Whether {@link dispatchToolKey} can answer this contract tool key. */
+export declare function supportsToolKey(key: string): boolean;
+/**
+ * Run one already-validated tool call.
+ *
+ * The caller owns validation (each surface parses with its own `ToolSpec.input` so the error
+ * envelope matches its protocol) and owns the model-facing shaping
+ * ({@link modelFacingToolResult}); this is the raw runtime call in between. An unknown key THROWS
+ * rather than returning a payload, so a surface cannot mistake it for a successful empty result —
+ * both adapters route the throw through their structured error envelope.
+ */
+export declare function dispatchToolKey(rt: AvantfRuntime, key: string, args: Record<string, unknown>): Promise<unknown>;

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

@@ -0,0 +1,84 @@
+/**
+ * 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.
+ *
+ * Note: nodejieba's `tag()` returns `{ word, tag }` objects, and its POS flag set
+ * differs from Python jieba (e.g. proper nouns → `nr`, 名动词 → `vn`).
+ */
+interface ExtractedEntity {
+    name: string;
+    type: string;
+    method: string;
+}
+export interface ExtractedTriple {
+    subj: string;
+    pred: string;
+    obj: string;
+    confidence: number;
+    source: string;
+}
+type PosToken = {
+    word: string;
+    tag: string;
+};
+/**
+ * Attempts made so far — the mechanism, not the wall time.
+ *
+ * A wall-clock assertion would be machine-dependent, but "how many parses ran" is exact and is
+ * what {@link loadJieba}'s promise-level memo exists to keep at one. The case that matters is
+ * CONCURRENCY: a result-level memo looks correct to any sequential caller and only shows up when
+ * two of them overlap.
+ */
+export declare function jiebaLoadAttempts(): number;
+export declare function jiebaAvailable(): Promise<boolean>;
+/**
+ * Version of the extraction RULES below (accepted tags, stop words, triple patterns).
+ *
+ * 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).
+ */
+export declare const ENTITY_EXTRACTOR_VERSION = 1;
+export interface TriplePattern {
+    subj?: string;
+    pred?: string;
+    obj?: string;
+}
+/**
+ * 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.
+ */
+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`).
+ */
+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/loader.d.ts

@@ -0,0 +1,19 @@
+interface EvalQuery {
+    query: string;
+    k: number;
+    expected_ids: number[];
+    must_include: number[];
+    must_exclude: number[];
+}
+export interface EvalCase {
+    id: string;
+    tags: string[];
+    setup_facts: string[];
+    queries: EvalQuery[];
+}
+/**
+ * Parse the 29-query eval fixture. Each line is one case with
+ * `setup_facts` (ordered) and `queries` whose id lists are indices into setup_facts.
+ */
+export declare function loadEvalCases(path: string): EvalCase[];
+export {};

package/lib/engine/mem/eval/metrics.d.ts

@@ -0,0 +1,25 @@
+/** Retrieval-quality metrics (pure functions, backend-agnostic). */
+export declare function precisionAtK(actual: number[], expected: number[], k: number): number;
+export declare function recallAtK(actual: number[], expected: number[], k: number): number;
+export declare function reciprocalRank(actual: number[], expected: number[]): number;
+export interface PerQueryMetrics {
+    query: string;
+    k: number;
+    precision_at_k: number;
+    recall_at_k: number;
+    reciprocal_rank: number;
+    actual_ids: number[];
+    expected_ids: number[];
+    must_include_satisfied: boolean;
+    must_exclude_satisfied: boolean;
+}
+export interface AggregateMetrics {
+    n_queries: number;
+    mean_precision_at_k: number;
+    mean_recall_at_k: number;
+    mrr: number;
+    empty_rate: number;
+    must_include_pass_rate: number;
+    must_exclude_pass_rate: number;
+}
+export declare function aggregate(perQuery: PerQueryMetrics[]): AggregateMetrics;

package/lib/engine/mem/eval/runner.d.ts

@@ -0,0 +1,10 @@
+import { type PerQueryMetrics, type AggregateMetrics } from './metrics.js';
+import type { EvalCase } from './loader.js';
+/** A retrieve function over the case's facts, returning indices in relevance order. */
+type RetrieveFn = (query: string, k: number, facts: string[]) => Promise<number[]>;
+interface EvalReport {
+    perQuery: PerQueryMetrics[];
+    summary: AggregateMetrics;
+}
+export declare function evaluateCases(cases: EvalCase[], retrieve: RetrieveFn): Promise<EvalReport>;
+export {};

package/lib/engine/mem/eval/write_metrics.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Write-side evaluation: the deterministic half of the memory lifecycle (DESIGN §20).
+ *
+ * The retrieval suite grades what comes OUT of the store; nothing graded what goes IN. Write
+ * behavior is where the invariants live (exact dedupe, one revision per supersede step,
+ * conflicts logged and retired, archive/restore round trips), and unlike answer quality it
+ * needs no model and no judge.
+ *
+ * TWO metrics, deliberately orthogonal (the reference design's split, and the reason it works):
+ *
+ *  - `action_success` — the STRUCTURAL operation the case exists for happened (a revision was
+ *    archived, a pair was opened, a pair was closed). Counts only; it never looks at content.
+ *  - `information_integrity` — every statement survives EXACTLY ONCE (live, or archived when the
+ *    case says it was retired). Content only; it never looks at counts.
+ *
+ * Keeping them apart is the point: an update that archives the old revision but loses a fact it
+ * carried passes the action metric and fails integrity, and a single blended score would hide
+ * which half broke. Both are pure functions over an observation, so the grader is deterministic
+ * and needs no live store — only the scenarios that produce the observations do.
+ *
+ * The identity token is supplied by the observation, NOT parsed out of the fact text. Carrying
+ * 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.
+ */
+/** What a case is about. `expect_action` is structural only; `live` is content only. */
+export interface WriteCase {
+    id: string;
+    /** Identity tokens the LIVE corpus must carry exactly once. */
+    live: string[];
+    /** Tokens that must no longer be live (their statements were superseded/retracted). */
+    retired?: string[];
+    /** Structural claims about the state after the scenario. */
+    expect_action?: {
+        /** Rows in the supersede chain of the fact the scenario follows. */
+        revision_chain?: number;
+        /**
+         * OPEN conflicts naming the facts THIS case names (`live` + `retired`) — never the whole
+         * store: the scenarios share one, so a store-wide count would make a case's verdict depend
+         * on which cases ran before it. That is not hypothetical — a store-wide
+         * `archived_reason_count` held only because its case ran first.
+         */
+        open_conflicts?: number;
+        /** Facts whose archive reason is this value. Omit together with the count to assert "any". */
+        archived_reason?: string;
+        /**
+         * How many archived facts carry `archived_reason` (default 1), or — when `archived_reason`
+         * is omitted — how many carry ANY reason. The standalone form is what "nothing was
+         * archived" needs, and it must actually be checked: gating the count on `archived_reason`
+         * made the standalone form a silent no-op.
+         *
+         * Counted over the facts THIS CASE names (`live` + `retired`), never over the whole store:
+         * the scenarios share one store, so a store-wide count would make a case's result depend on
+         * which cases ran before it.
+         */
+        archived_reason_count?: number;
+    };
+}
+/** What the store actually looks like after the scenario ran. */
+export interface WriteObservation {
+    /** Identity tokens seen in ACTIVE facts, with their occurrence count. */
+    live: Map<string, number>;
+    /** Identity tokens seen in ARCHIVED facts. */
+    archived: Set<string>;
+    /** Archive reason per fact, tagged with the fact's identity token (see `WriteCase.live`). */
+    archive_reasons: {
+        token: string;
+        reason: string;
+    }[];
+    open_conflicts: number;
+    /** Length of the supersede chain rooted at the scenario's fact, when the case asks. */
+    revision_chain?: number;
+}
+interface WriteCaseResult {
+    id: string;
+    action_success: boolean;
+    information_integrity: boolean;
+    /** Human-readable explanation, so a failure says WHICH half broke and how. */
+    detail: string;
+}
+export interface WriteReport {
+    cases: WriteCaseResult[];
+    action_success_rate: number;
+    information_integrity_rate: number;
+}
+export declare function gradeWriteCases(cases: WriteCase[], observations: Map<string, WriteObservation>): WriteReport;
+export {};