@sema-agent/server 1.322.0 → 2.0.0

package/dist/plugins/memory-engine-pg.js

@@ -1,12 +1,39 @@
+// ⚠️ ORIGIN: @sema-agent/core 1.267.0 `src/core/memory-engine/pg-backend.ts`(core commit 3071dd3)——
+// 边界重切整段移交:core 从此只养 File backend+MemoryBackend seam+memoryBackendContract
+// 契约套件;Pg/TiDB 方言实现归 service(数据面方言=deployment 半场,TiDBRunStore/PgRunStore 先例)。
+// 移交纪律:保留此头注双向可追;core 下版撤 PgMemoryEngineBackend 公开导出。
+// 改动 vs origin:import 面重指(types/frontmatter 从 @sema-agent/core 公开面;memory-vector 三函数+
+// isUniqueViolation 内联于 memory-engine-vector-util.ts(core 1.424 示例适配器退包面后回归内联,勿再切 re-export)。
+// design/138 S3-core — PgMemoryEngineBackend: the SECOND MemoryBackend implementation (TOB/multi-tenant
+// authority disk), proving the S1 entry-transactional seam holds off the file plane. Same contract as
+// FileMemoryEngineBackend; radically simpler internals, because Postgres retires the file backend's
+// control-plane machinery instead of porting it (S3 拍板, design/138 §S3-core):
+//   - committed-rev ledger  → the row's `rev` column IS the committed rev (no zero-copy problem: the
+//     model edits file PROJECTIONS, never DB rows, so "read current rev" cannot self-conflict);
+//   - redo journal          → per-statement conditional writes (`UPDATE … WHERE rev = $expected
+//     RETURNING`, the pg.ts checkpoint OCC template) — the DB's atomicity replaces staging/journaling;
+//   - shadow/ quarantine/   → dropped: a DB row cannot go "missing" outside an explicit delete patch,
+//     so the "缺失≠删除" recovery axis has no Pg counterpart; inbound writes are engine-only (a
+//     deployment sharing the tables with other writers owns validation — same posture as stores/pg.ts);
+//   - scope registry        → dropped: `scope` is a plain column; tenant keying is the deployment's.
+// Vector rungs (design/81, re-mounted here per §4): lexical (jaccard, byte-equal to FileBackend) →
+// portable (jsonb vectors, in-process cosine) → native (pgvector `<=>` SQL). All three share the
+// cosine-distance contract score ∈ [0,2] — upgrading recall is a config change, not a recalibration.
 import { cosineDistance, jaccardDistance, termSet, isUniqueViolation } from "./memory-engine-vector-util.js";
 import { computeEntryRev, serializeEntryFile } from "@sema-agent/core";
 import { pgSafeJsonStringify, pgHasUnstorable } from "./pg-safe-json.js";
+/** Table names (single source). Deliberately DISJOINT from the legacy `agent_memory*` tables —
+ *  the retired MemoryStore plane and this entry plane must never cross-write. */
 export const PG_MEMORY_ENGINE_TABLES = {
     entries: "agent_memory_engine_entries",
     cursors: "agent_memory_engine_cursors",
 };
+/** Idempotent DDL for the entry plane. Call once at startup (or run through your migration tool). */
 export async function ensurePgMemoryEngineSchema(query, opts = {}) {
     const vec = opts.memoryVector;
+    // dimensions must be a finite positive integer — NaN/Infinity would interpolate
+    // invalid DDL (`vector(NaN)`), and a silent fractional truncation could disagree with the embedder's
+    // declared dimensions. Boot-time config error ⇒ throw loudly, never emit broken DDL.
     if (vec !== undefined && (!Number.isInteger(vec.dimensions) || vec.dimensions < 1)) {
         throw new Error(`ensurePgMemoryEngineSchema: memoryVector.dimensions must be a positive integer (got ${String(vec.dimensions)})`);
     }
@@ -28,16 +55,27 @@ export async function ensurePgMemoryEngineSchema(query, opts = {}) {
         await query(`CREATE INDEX IF NOT EXISTS ${PG_MEMORY_ENGINE_TABLES.entries}_scope_idx ON ${PG_MEMORY_ENGINE_TABLES.entries} (scope)`);
     }
     catch {
+        /* pg-mem: partial CREATE INDEX support — the index is a perf add-on, never correctness */
     }
+    // The (scope, slug) UNIQUE constraint is CORRECTNESS, not perf — two
+    // instances racing an add of the same scope+slug (different ids) could both probe "free" and both
+    // insert, leaving two entries whose file projections overwrite each other at materialize. The DB
+    // constraint is the only true arbiter; the add path catches the violation and retries the next
+    // suffix. NOT wrapped in try/catch — if this constraint cannot be created, the backend is unsafe.
     await query(`CREATE UNIQUE INDEX IF NOT EXISTS ${PG_MEMORY_ENGINE_TABLES.entries}_scope_slug_uq ON ${PG_MEMORY_ENGINE_TABLES.entries} (scope, slug)`);
     await query(`CREATE TABLE IF NOT EXISTS ${PG_MEMORY_ENGINE_TABLES.cursors} (
     scope text PRIMARY KEY,
     cursor text NOT NULL
   )`);
 }
+/** pgvector input literal — the same `[…]` string JSON.parse reads back from jsonb (one format, two columns). */
 function vectorLiteral(v) {
     return `[${v.join(",")}]`;
 }
+/** `$k, $k+1, …` for a dynamic IN list. Used instead of `= ANY($1)` — pg-mem (the offline test rig)
+ *  silently returns ZERO rows for `ANY(param)` on an INDEXED column (index-path bug, verified
+ *  2026-07-11: unindexed ANY works, indexed ANY is empty, indexed `=` works). IN-lists are plain SQL
+ *  on both engines, so the production path never bends toward the emulator. */
 function inPlaceholders(first, count) {
     return Array.from({ length: count }, (_, i) => `$${first + i}`).join(", ");
 }
@@ -50,7 +88,9 @@ export class PgMemoryEngineBackend {
     pgvectorSql;
     clock;
     history;
+    /** Cumulative lost-row count — audit-line breakage must itself be auditable. */
     historyRowsLost = 0;
+    /** design/81 rung indicator — same semantics as PgMemoryStore.vectorMode. */
     get vectorMode() {
         return this.pgvectorSql ? "native" : this.embedder ? "portable" : "lexical";
     }
@@ -63,9 +103,12 @@ export class PgMemoryEngineBackend {
         if (this.pgvectorSql && !this.embedder)
             throw new Error("PgMemoryEngineBackend: pgvectorSql requires an embedder");
     }
+    /** The embed/search haystack — BYTE-EQUAL to FileBackend's lexical haystack (file-backend search). */
     haystackOf(slug, fm, body) {
         return `${fm.name ?? slug} ${fm.description ?? ""} ${body}`;
     }
+    /** Dimension-guarded embedding parameter (mirrors PgMemoryStore.embeddingParam — wrong-length ⇒ null,
+     *  the row falls open to the lexical stand-in instead of poisoning reads). */
     async embeddingParam(text) {
         if (!this.embedder)
             return null;
@@ -99,6 +142,9 @@ export class PgMemoryEngineBackend {
         };
     }
     async listHeaders(scopes) {
+        // Dedupe (all three read paths): a repeated key must not repeat rows — real Postgres IN-lists
+        // don't, but pg-mem duplicates matches per repeated placeholder value; dedupe is also the honest
+        // semantic (a caller repeating an id asks about ONE entry).
         const uniq = [...new Set(scopes)];
         if (uniq.length === 0)
             return [];
@@ -110,16 +156,24 @@ export class PgMemoryEngineBackend {
         if (uniq.length === 0)
             return [];
         const res = await this.query(`SELECT id, scope, slug, frontmatter, body, rev, mtime_ms, size_bytes FROM ${PG_MEMORY_ENGINE_TABLES.entries} WHERE id IN (${inPlaceholders(1, uniq.length)}) ORDER BY id`, uniq);
-        return res.rows.map((r) => this.entryFromRow(r));
+        return res.rows.map((r) => this.entryFromRow(r)); // unknown ids: silently absent
     }
     async search(query, scopes, opts) {
+        // Normalize the limit ONCE for all three rungs — `Math.floor`
+        // makes a fractional limit (0.5) behave like File's `slice` (→ 0 → empty), `!(lim > 0)` also
+        // rejects NaN (NaN > 0 is false — it previously reached the native rung's interpolated LIMIT as
+        // a SQL syntax error). Infinity stays legal ("no cap") and is clamped before interpolation.
         const rawLimit = opts?.limit ?? 20;
         const limit = Number.isFinite(rawLimit) ? Math.floor(rawLimit) : rawLimit;
         if (scopes.length === 0 || !(limit > 0))
             return [];
+        // The EMPTY-QUERY contract is backend-uniform — File returns [] when the
+        // query has no terms, so the vector rungs must not answer it either (an embedder may happily
+        // embed "" and score every row). One guard ahead of ALL rungs.
         const q = termSet(query);
         if (q.size === 0)
             return [];
+        // Native rung: rank in SQL. Excludes embedding-less rows (documented migration note).
         if (this.pgvectorSql && this.embedder) {
             const qv = await this.embedder.embed(query);
             if (Array.isArray(qv) && qv.length === this.embedder.dimensions) {
@@ -131,6 +185,7 @@ export class PgMemoryEngineBackend {
             LIMIT ${Math.min(limit, 100_000)}`, [...scopes, vectorLiteral(qv)]);
                 return res.rows.map((r) => ({ ...this.headerFromRow(r), score: Number(r.dist) }));
             }
+            // Wrong-dimension query vector (transient embedder fault) — fall open to the in-process path.
         }
         const res = await this.query(`SELECT id, scope, slug, frontmatter, body, rev, mtime_ms, size_bytes, embedding FROM ${PG_MEMORY_ENGINE_TABLES.entries} WHERE scope IN (${inPlaceholders(1, scopes.length)})`, [...scopes]);
         const queryVec = this.embedder ? await this.embedder.embed(query).catch(() => null) : null;
@@ -139,6 +194,8 @@ export class PgMemoryEngineBackend {
         for (const raw of res.rows) {
             const r = raw;
             const fm = fromJson(r.frontmatter);
+            // Portable rung: cosine over the stored jsonb vector when both sides are dimension-valid;
+            // any missing/invalid side falls open to the lexical floor for THIS row (never dropped).
             if (queryVec && Array.isArray(queryVec) && queryVec.length === dims && r.embedding != null) {
                 const stored = fromJson(r.embedding);
                 if (Array.isArray(stored) && stored.length === dims) {
@@ -151,13 +208,19 @@ export class PgMemoryEngineBackend {
                 continue;
             scored.push({ ...this.headerFromRow(r), score: d });
         }
+        // opus 审 C4: deterministic id tie-break — tied scores must not order by row-arrival accident
+        // (the cross-backend equivalence assertion compares ordered projections; File mirrors this).
         scored.sort((a, b) => a.score - b.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
         return scored.slice(0, limit);
     }
     async applyPatches(patches) {
         const report = { applied: [], conflicts: [] };
+        // At most ONE non-delete op per id per batch (file-backend parity — a COPY keeping its frontmatter
+        // id would leave the projection↔applied binding ambiguous; refuse the later one).
         const nonDeleteIds = new Set();
+        // In-batch (scope, slug) claims so two adds of one slug in one batch suffix deterministically.
         const plannedSlugs = new Set();
+        // 142-S5.1: one history row per APPLIED patch, flushed as one batch below (append-only audit face).
         const historyRows = [];
         for (const patch of patches) {
             try {
@@ -174,11 +237,17 @@ export class PgMemoryEngineBackend {
                 report.conflicts.push({ op: patch.op, id: patch.id, reason: `io error: ${err instanceof Error ? err.message : String(err)}` });
             }
         }
+        // BEST-EFFORT history append (see PgMemoryEngineBackendOptions.history for the honest trade-off:
+        // the entry writes above are already committed; a failed audit append must not fail the report —
+        // swallow + warn, never throw. appendHistory is (id,rev)-idempotent, so a caller retry is safe.
         if (this.history && historyRows.length > 0) {
             try {
                 await this.history.appendHistory(historyRows);
             }
             catch (err) {
+                // Every warn carries the CUMULATIVE lost count — a persistent silent failure
+                // (history table dropped, grant flipped) shows as a growing number, not a one-off line.
+                // The metrics counter leg lives in the main.ts sink wrapper (memory_history_append_failed_total).
                 this.historyRowsLost += historyRows.length;
                 console.warn(`PgMemoryEngineBackend: best-effort history append failed (${historyRows.length} row(s) lost, ${this.historyRowsLost} cumulative — audit face only, entries committed): ${err instanceof Error ? err.message : String(err)}`);
             }
@@ -187,6 +256,9 @@ export class PgMemoryEngineBackend {
     }
     async applyOne(patch, report, plannedSlugs, historyRows) {
         const T = PG_MEMORY_ENGINE_TABLES.entries;
+        // A patch whose entry carries a DIFFERENT id than the patch addresses is
+        // malformed — the two backends would otherwise diverge (File writes the entry's id, Pg would
+        // key the SELECT on patch.id but the write on entry.id). Refused up front, both backends alike.
         if (patch.op !== "delete" && patch.entry !== undefined && patch.entry.id !== patch.id) {
             report.conflicts.push({ op: patch.op, id: patch.id, reason: `patch id ${JSON.stringify(patch.id)} != entry id ${JSON.stringify(patch.entry.id)} (malformed patch refused)` });
             return;
@@ -197,13 +269,28 @@ export class PgMemoryEngineBackend {
                 report.conflicts.push({ op: "add", id: patch.id, reason: "add patch without an entry" });
                 return;
             }
+            // codex R2-H3→R3(终形):**拒绝式**——sync 协议的 rev/CAS/幂等全部对拍原文,存储层任何改写
+            // (有损或 canonical)都让 ack rev≠库内 rev(响应丢失重试=假冲突,R3 实锚)。含不可存字节的
+            // entry 在 PG 后端 fail-loud 报 conflict(reason 指路客户端清源);File 后端能存=后端能力差,
+            // 诚实暴露优于静默改写。重试恒同答=幂等成立。
             if (pgHasUnstorable(rawEntry.frontmatter) || pgHasUnstorable(rawEntry.body) || pgHasUnstorable(rawEntry.slug)) {
                 report.conflicts.push({ op: "add", id: rawEntry.id, reason: "unstorable_bytes (PG cannot store NUL/lone surrogates; strip them at the source — the store never rewrites content)" });
                 return;
             }
             const entry = rawEntry;
+            // opus 审 C3: an add whose id already lives in a DIFFERENT scope is refused explicitly — the bare
+            // `ON CONFLICT (id) DO UPDATE SET scope=…` would silently MOVE the row across scopes (and diverge
+            // from the File backend, which never scans other scopes on add). The engine's call surface never
+            // produces this input (harvest/materialize are scope-local); a conflict report is the honest
+            // fail-closed answer. Same-scope re-add stays the idempotent overwrite (File parity).
+            // One probe serves BOTH the E-02 guard below and the cross-scope refusal (File-backend parity).
             const prior = await this.query(`SELECT scope, slug, rev FROM ${T} WHERE id = $1`, [entry.id]);
             const priorRow = prior.rows.length > 0 ? prior.rows[0] : undefined;
+            // E-02 add-if-absent guard (core 1.275.1/1.276.0 contract clause, design/142 S2.5): a
+            // `guard:"absent"` add must NEVER blind-overwrite an existing id — same rev AND same
+            // (scope, slug) projection = idempotent fall-through; different rev OR different projection =
+            // REPORTED `add_guard_absent_conflict` carrying currentRev (File backend semantics verbatim;
+            // caught live by the contract suite on real TiDB 2026-07-13 — the twins had no guard leg).
             if (patch.guard === "absent" && priorRow) {
                 const currentRev = String(priorRow.rev);
                 if (currentRev !== computeEntryRev(entry)) {
@@ -214,6 +301,7 @@ export class PgMemoryEngineBackend {
                     report.conflicts.push({ op: "add", id: entry.id, reason: `add_guard_absent_conflict (id already exists at the same rev but a different projection ${JSON.stringify(`${String(priorRow.scope)}/${String(priorRow.slug)}`)}; add-if-absent refuses to duplicate)`, currentRev });
                     return;
                 }
+                // same rev AND same projection ⇒ idempotent; fall through to the normal add (no-op re-write).
             }
             if (priorRow) {
                 const held = String(priorRow.scope);
@@ -222,7 +310,13 @@ export class PgMemoryEngineBackend {
                     return;
                 }
             }
-            const cEntry = entry;
+            // Slug collision with a DIFFERENT entry (same scope+slug, other id) → deterministic `-n` suffix
+            // (file-backend parity). In-batch planned slugs count as taken too.
+            // The SELECT probe alone is a race window — two instances can both observe "free" and both
+            // insert one slug. The INSERT itself sits INSIDE the loop: a (scope,slug) unique-violation from
+            // the concurrent loser retries the next suffix, so the DB constraint (ensureSchema) is the one
+            // true arbiter and the probe is only an optimization.
+            const cEntry = entry; // R3 终形:拒绝式守卫后恒干净
             const embedding = await this.embeddingParam(this.haystackOf(cEntry.slug, cEntry.frontmatter, cEntry.body));
             let slug = cEntry.slug;
             for (let n = 2;; n++) {
@@ -241,12 +335,14 @@ export class PgMemoryEngineBackend {
                         catch (err) {
                             if (isUniqueViolation(err)) {
                                 slug = `${entry.slug}-${n}`;
-                                continue;
+                                continue; // concurrent winner took this (scope,slug) — try the next suffix
                             }
                             throw err;
                         }
                         plannedSlugs.add(key);
                         report.applied.push({ op: "add", id: stored.id, slug: stored.slug });
+                        // History: chain head — prevRev absent by contract (a same-scope idempotent re-add of
+                        // identical content dedupes on the (id, rev) PK; changed content starts a fresh head).
                         if (this.history)
                             historyRows.push({ id: stored.id, rev, op: "add", scope: stored.scope, snapshot: { ...stored, rev }, writtenAtMs: this.clock() });
                         return;
@@ -255,6 +351,8 @@ export class PgMemoryEngineBackend {
                 slug = `${entry.slug}-${n}`;
             }
         }
+        // update/delete address an EXISTING entry by immutable id. (scope in the projection = the
+        // history row's scope for delete — a tombstone can't be joined back to the deleted row.)
         const cur = await this.query(`SELECT slug, rev, scope, frontmatter FROM ${PG_MEMORY_ENGINE_TABLES.entries} WHERE id = $1`, [patch.id]);
         if (cur.rows.length === 0) {
             report.conflicts.push({ op: patch.op, id: patch.id, reason: "unknown id (entry not found in backend)" });
@@ -263,6 +361,10 @@ export class PgMemoryEngineBackend {
         const currentRev = String(cur.rows[0].rev);
         const currentSlug = String(cur.rows[0].slug);
         const currentScope = String(cur.rows[0].scope);
+        // Read-side whitewash refusal (core 1.302 contract I-2, File-backend parity incl. ordering: judged
+        // BEFORE the rev CAS): an update may not strip provenance/trust off a repo-ingested entry. Judged on
+        // the committed frontmatter of THIS SELECT — a write racing past it flips rev and the conditional
+        // write below re-reports as a CAS conflict, so the window stays closed.
         if (patch.op === "update" && patch.entry !== undefined) {
             const committedFm = fromJson(cur.rows[0].frontmatter);
             if (committedFm.provenance?.kind === "repo_file") {
@@ -280,16 +382,28 @@ export class PgMemoryEngineBackend {
             }
         }
         if (patch.baseRev !== undefined && patch.baseRev !== currentRev) {
+            // Per-id CAS (§2.4 并发): NEVER blind-write over a concurrent change. No shadow-restore leg here —
+            // the DB row IS the committed state; nothing on a disk projection can shadow it.
+            // ABA note (opus 审 C1): rev is a CONTENT hash, so an A→B→A round-trip by another writer makes a
+            // stale baseRev "current" again and this CAS passes. Benign by construction — same hash ⇒ same
+            // canonical content, the overwrite is idempotent; only the intervening-write SIGNAL is lost.
+            // Shared with the File backend (same computeEntryRev), inherent to content-hash CAS.
             report.conflicts.push({ op: patch.op, id: patch.id, reason: "rev mismatch (concurrent change)", baseRev: patch.baseRev, currentRev });
             return;
         }
         if (patch.op === "delete") {
+            // Conditional on the rev we just judged — a write that lands between the SELECT and this DELETE
+            // re-reports as the same CAS conflict instead of silently deleting the newer committed state.
             const res = await this.query(`DELETE FROM ${PG_MEMORY_ENGINE_TABLES.entries} WHERE id = $1 AND rev = $2 RETURNING id`, [patch.id, currentRev]);
             if (res.rows.length === 0) {
                 report.conflicts.push({ op: "delete", id: patch.id, reason: "rev mismatch (concurrent change)", baseRev: patch.baseRev, currentRev: await this.freshRev(patch.id, currentRev) });
                 return;
             }
             report.applied.push({ op: "delete", id: patch.id, slug: currentSlug });
+            // History tombstone. rev must be DISTINCT from the deleted version's rev — the (id, rev) PK
+            // already holds a row for currentRev (the add/update that committed it), and ON CONFLICT DO
+            // NOTHING would silently drop a colliding tombstone. Deterministic derived key: revs are
+            // 16-hex content hashes (computeEntryRev), so the prefixed form stays well under varchar(128).
             if (this.history)
                 historyRows.push({ id: patch.id, rev: `tombstone:${currentRev}`, prevRev: currentRev, op: "delete", scope: currentScope, writtenAtMs: this.clock() });
             return;
@@ -303,7 +417,7 @@ export class PgMemoryEngineBackend {
             report.conflicts.push({ op: "update", id: patch.id, reason: "unstorable_bytes (PG cannot store NUL/lone surrogates; strip them at the source — the store never rewrites content)" });
             return;
         }
-        const cEntry = entry;
+        const cEntry = entry; // R3 终形:拒绝式后恒干净,rev 对拍原文
         const rev = computeEntryRev(cEntry);
         const embedding = await this.embeddingParam(this.haystackOf(cEntry.slug, cEntry.frontmatter, cEntry.body));
         const res = await this.query(`UPDATE ${PG_MEMORY_ENGINE_TABLES.entries}
@@ -315,9 +429,13 @@ export class PgMemoryEngineBackend {
             return;
         }
         report.applied.push({ op: "update", id: entry.id, slug: entry.slug });
+        // History: rev-chain link — snapshot carries the committed entry (rev = the NEW content hash).
         if (this.history)
             historyRows.push({ id: entry.id, rev, prevRev: currentRev, op: "update", scope: entry.scope, snapshot: { ...entry, rev }, writtenAtMs: this.clock() });
     }
+    /** When the conditional write returns zero rows (a write landed inside the
+     *  SELECT→write window), the report's `currentRev` must be the rev NOW — re-reporting the pre-race
+     *  SELECT value could claim `baseRev === currentRev` alongside a "rev mismatch" reason. */
     async freshRev(id, fallback) {
         const res = await this.query(`SELECT rev FROM ${PG_MEMORY_ENGINE_TABLES.entries} WHERE id = $1`, [id]);
         return res.rows.length > 0 ? String(res.rows[0].rev) : fallback;

package/dist/plugins/memory-engine-tidb.d.ts

@@ -2,14 +2,32 @@ import type { MemoryHistoryAppendRow } from "./memory-sync-store-pg.js";
 import type { PgEmbedder } from "./pg-query.js";
 import type { MemoryBackend, MemoryEntry, MemoryEntryHeader, NotePatch, PatchReport, ScoredMemoryEntry } from "@sema-agent/core";
 import type { Pool } from "mysql2/promise";
+/** Table names (single source) — SAME names as PG_MEMORY_ENGINE_TABLES (the two dialects never share
+ *  one database), deliberately DISJOINT from the legacy `agent_memory*` MemoryStore plane. */
 export declare const TIDB_MEMORY_ENGINE_TABLES: {
     readonly entries: "agent_memory_engine_entries";
     readonly cursors: "agent_memory_engine_cursors";
 };
+/** Idempotent DDL for the entry plane (TiDB dialect). Call once at startup.
+ *  Key lengths: utf8mb4 = 4 bytes/char and the default index-key cap is 3072 bytes, so the
+ *  (scope, slug) unique key budget is scope 190 + slug 512 = 702 chars ⇒ 2808 bytes ≤ 3072. */
 export declare function ensureTiDBMemoryEngineSchema(pool: Pool): Promise<void>;
+/** Options for {@link TiDBMemoryEngineBackend}. Signature-parity with the Pg twin, but v1 is
+ *  LEXICAL ONLY — there is no TiDB vector rung yet; passing an embedder is refused loudly
+ *  (no-stopgap: never silently ignore a caller's recall-quality expectation). */
 export interface TiDBMemoryEngineBackendOptions {
+    /** NOT SUPPORTED in v1 (lexical only) — present for signature parity; a value throws at construction. */
     embedder?: PgEmbedder;
+    /** Clock injection (file-backend precedent) — drives `mtime_ms`. Default `Date.now`. */
     now?: () => number;
+    /** 142-S5.1 history write point — OPTIONAL audit sink, one history row per APPLIED patch, appended
+     *  AFTER the entry write. Absent → byte-equal legacy behavior (additive). 同事务诚实记档(Pg 版同注,
+     *  posture 对称保持):this backend does hold a Pool (a getConnection+txn wrap IS possible), but the
+     *  entry plane itself is deliberately NON-transactional (single-statement CAS is the correctness
+     *  mechanism), and the Pg twin's bare-PgQueryFn seam cannot cheaply transact — wrapping only the
+     *  TiDB side would fork the twins' semantics. Chosen trade-off on BOTH dialects: entry write commits
+     *  first, history append is BEST-EFFORT (failure = swallow + console.warn) — history is the AUDIT
+     *  face, not the correctness face: a lost history row loses an audit line, never data. */
     history?: {
         appendHistory(rows: readonly MemoryHistoryAppendRow[]): Promise<void>;
     };
@@ -18,11 +36,14 @@ export declare class TiDBMemoryEngineBackend implements MemoryBackend {
     private readonly pool;
     private readonly clock;
     private readonly history?;
+    /** Cumulative lost-row count — audit-line breakage must itself be auditable. */
     private historyRowsLost;
+    /** design/81 rung indicator — TiDB v1 sits on the lexical floor (Pg twin parity surface). */
     get vectorMode(): "lexical";
     constructor(pool: Pool, opts?: TiDBMemoryEngineBackendOptions);
     private selectRows;
     private write;
+    /** The search haystack — BYTE-EQUAL to the File/Pg backends' lexical haystack (contract equivalence). */
     private haystackOf;
     private headerFromRow;
     private entryFromRow;
@@ -33,7 +54,12 @@ export declare class TiDBMemoryEngineBackend implements MemoryBackend {
     }): Promise<ScoredMemoryEntry[]>;
     applyPatches(patches: readonly NotePatch[]): Promise<PatchReport>;
     private applyOne;
+    /** The row's rev NOW, or undefined if the row is gone. The existence distinction is the whole point
+     *  (codex lens-3): a concurrent delete must not be mistaken for an idempotent already-at-target write. */
     private freshRevOrMissing;
+    /** When the conditional write reports zero rows (a write landed inside the SELECT→write window), the
+     *  report's `currentRev` must be the rev NOW — re-reporting the pre-race SELECT value could claim
+     *  `baseRev === currentRev` alongside a "rev mismatch" reason. Row gone ⇒ fallback (Pg parity). */
     private freshRev;
     getConsolidationCursor(scope: string): Promise<string | undefined>;
     setConsolidationCursor(scope: string, cursor: string): Promise<void>;