@sema-agent/server 7.43.0 → 7.44.0

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

@@ -1,42 +1,13 @@
-// TiDB (MySQL wire) dialect twin of `memory-engine-pg.ts` — the THIRD MemoryBackend implementation
-// (边界重切:core 养 File backend+seam+memoryBackendContract,SQL 方言归 service;先例=
-// TiDBRunStore/PgRunStore 方言孪生对)。Same tables, same contract, mysql2 posture throughout.
-//
-// 方言改造点(core 指引,与 Pg 版逐条对照):
-//   - `$n` 占位符 → `?`;`jsonb` → `JSON`(mysql2 对 JSON 列返回已解析对象,fromJson 防御 string 形);
-//   - `UPDATE/DELETE … WHERE rev = ? RETURNING` → MySQL 无 RETURNING:条件写后看 affectedRows;零行=
-//     conflict,且 currentRev 必须 SELECT 现值(freshRev 语义——绝不把 pre-race SELECT 的旧值当 currentRev)。
-//     ⚠️ affectedRows 语义(归因修正:mysql2 默认 flags 含 FOUND_ROWS ⇒ affectedRows=
-//     MATCHED 行数;此前注释写反)。真库契约在真默认语义下全绿;下述 fresh-rev 比对分支让两种语义都正确:matched-but-
-//     identical 也是 0——零行后用 freshRev 消歧(现 rev==新 rev ⇒ 内容已是目标态=幂等成功,非 conflict);
-//   - add 路径 Pg 用 `INSERT … ON CONFLICT (id) DO UPDATE`(冲突靶=仅 PK)。MySQL 的 ON DUPLICATE KEY
-//     UPDATE 会被 **任意** 唯一键触发——(scope,slug) 撞键时它会把竞争对手的行改写成本 entry 的 id(数据毁),
-//     不能用;拆成「不存在→INSERT / 已存在→UPDATE by id」,两条腿的 ER_DUP_ENTRY 都按键名分诊(PRIMARY=
-//     并发同 id add → 转 UPDATE 腿;uq_agent_memory_engine_entry_scope_slug=并发 slug 竞争 → 下一个 -n 后缀重试);
-//   - unique violation 判定:ER_DUP_ENTRY(errno 1062),不是 Pg 的 23505;
-//   - pg-mem 伪影 workaround(索引列 ANY 零行/重复占位符重复行)不抄——MySQL 本就走 IN-list,dedupe 保留
-//     是因为它同时是诚实语义(重复 key 问的是同一个 entry,契约锁死 once-per-entry);
-//   - (scope, slug) UNIQUE 约束照立(竞态正确性:两实例各自探得 free 同时 INSERT,DB 约束是唯一仲裁);
-//   - 表名与 Pg 版同名(两方言不会同库;与退役 MemoryStore 的 `agent_memory*` 面刻意不相交);
-//   - v1 lexical only:embedder/vector 面无 TiDB 对应(Pg 的 pgvector rung 是 Pg 专属);构造签名保留
-//     opts 但传入 embedder=fail-loud 拒绝,search 恒走 jaccard 词面,haystack 与 Pg/File 逐字节同构
-//     (`${name ?? slug} ${description} ${body}`——memoryBackendContract 的 search 等价断言依赖)。
 import { jaccardDistance, termSet } from "@sema-agent/core";
 import { computeEntryRev, serializeEntryFile } from "@sema-agent/core";
 import { pgHasUnstorable } from "./pg-safe-json.js";
-import { assertMemoryScopeWidth, memoryEntryKeyWidthRefusal } from "./memory-key-guards.js"; // R5 批γ + #271 件1:scope/slug 写前宽守卫
-// #307 件6(core 5.46.0 design/336 §2.3-2):external-origin 不可变律 —— 与 Pg 孪生共用**一份**判据。
+import { assertMemoryScopeWidth, memoryEntryKeyWidthRefusal } from "./memory-key-guards.js";
 import { ambiguousOriginRefusal, createBatchCommittedBaseline, exposureBandOf, exposureCarriage, originWhitewashRefusal, rememberBatchCommitted, distilledWhitewashRefusal, distilledCarriage, unknownPatchOpRefusal, } from "./memory-origin-law.js";
 import { isMysqlDupKeyError } from "./sql-errors.js";
-/** 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 const TIDB_MEMORY_ENGINE_TABLES = {
     entry: "agent_memory_engine_entry",
     cursor: "agent_memory_engine_cursor",
 };
-/** 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 async function ensureTiDBMemoryEngineSchema(pool) {
     await pool.query(`CREATE TABLE IF NOT EXISTS ${TIDB_MEMORY_ENGINE_TABLES.entry} (
     id          VARCHAR(64)  NOT NULL,
@@ -52,23 +23,16 @@ export async function ensureTiDBMemoryEngineSchema(pool) {
     KEY idx_agent_memory_engine_entry_scope (scope),
     UNIQUE KEY uq_agent_memory_engine_entry_scope_slug (scope, slug)
   ) COLLATE utf8mb4_bin`);
-    // The (scope, slug) UNIQUE key above is CORRECTNESS, not perf (Pg 版同注):two
-    // instances racing an add of one scope+slug (different ids) can both probe "free" and both insert;
-    // the DB constraint is the only true arbiter and the add path retries the next suffix on violation.
     await pool.query(`CREATE TABLE IF NOT EXISTS ${TIDB_MEMORY_ENGINE_TABLES.cursor} (
     scope  VARCHAR(190) NOT NULL,
     \`cursor\` TEXT     NOT NULL,
     PRIMARY KEY (scope)
   ) COLLATE utf8mb4_bin`);
 }
-/** 判据属主 = `sql-errors.ts`(A-032 P1-①;本站点旧形已是并集形,收编后语义不变)。 */
 const isDupEntry = isMysqlDupKeyError;
-/** ER_DUP_ENTRY messages name the violated key (`… for key 'tbl.PRIMARY'` / `… for key 'tbl.uq_agent_memory_engine_entry_scope_slug'`)
- *  — the add path uses this to tell "id already exists (→ overwrite leg)" from "slug race (→ -n retry)". */
 function isPrimaryKeyDup(err) {
     return isDupEntry(err) && /for key '[^']*PRIMARY'/i.test(String(err.message ?? ""));
 }
-/** `?, ?, …` for a dynamic IN list (MySQL has no ANY(param); plain IN-list on both engines). */
 function inPlaceholders(count) {
     return Array.from({ length: count }, () => "?").join(", ");
 }
@@ -79,9 +43,7 @@ export class TiDBMemoryEngineBackend {
     pool;
     clock;
     history;
-    /** Cumulative lost-row count — audit-line breakage must itself be auditable. */
     historyRowsLost = 0;
-    /** design/81 rung indicator — TiDB v1 sits on the lexical floor (Pg twin parity surface). */
     get vectorMode() {
         return "lexical";
     }
@@ -101,7 +63,6 @@ export class TiDBMemoryEngineBackend {
         const [res] = await this.pool.query(sql, params);
         return res;
     }
-    /** The search haystack — BYTE-EQUAL to the File/Pg backends' lexical haystack (contract equivalence). */
     haystackOf(slug, fm, body) {
         return `${fm.name ?? slug} ${fm.description ?? ""} ${body}`;
     }
@@ -117,9 +78,7 @@ export class TiDBMemoryEngineBackend {
             mtimeMs: Number(r.mtime_ms),
             rev: r.rev,
             sizeBytes: Number(r.size_bytes),
-            // #319(design/336 §5.2,Pg 孪生同注):committed external-origin 事实随每一个头面;归一化同源。
             ...exposureCarriage(fm),
-            // #337(conformance c38,Pg 孪生同注):distilled 事实(carrierRev + supersedes)随每一个头面。
             ...distilledCarriage(fm),
         };
     }
@@ -134,8 +93,6 @@ export class TiDBMemoryEngineBackend {
         };
     }
     async listHeaders(scopes) {
-        // Dedupe (all three read paths): honest semantic — a caller repeating a key asks about ONE entry
-        // (contract-locked once-per-entry; real IN-lists don't duplicate anyway).
         const uniq = [...new Set(scopes)];
         if (uniq.length === 0)
             return [];
@@ -147,18 +104,14 @@ export class TiDBMemoryEngineBackend {
         if (uniq.length === 0)
             return [];
         const rows = await this.selectRows(`SELECT id, scope, slug, frontmatter, body, rev, mtime_ms, size_bytes FROM ${TIDB_MEMORY_ENGINE_TABLES.entry} WHERE id IN (${inPlaceholders(uniq.length)}) ORDER BY id`, uniq);
-        return rows.map((r) => this.entryFromRow(r)); // unknown ids: silently absent
+        return rows.map((r) => this.entryFromRow(r));
     }
     async search(query, scopes, opts) {
-        // #319(design/336 §5.2,Pg 孪生同注):两带序 —— 未标记先,**带序在截断之前**。本方言只有词面档,
-        // 整档在进程内排完再切片,所以「带序先于截断」天然成立(无 SQL LIMIT 可绕过)。
         const bands = opts?.exposureBands === true;
-        // Limit normalization mirrors the Pg twin verbatim (floor semantics; NaN rejected; Infinity = no cap).
         const rawLimit = opts?.limit ?? 20;
         const limit = Number.isFinite(rawLimit) ? Math.floor(rawLimit) : rawLimit;
         if (scopes.length === 0 || !(limit > 0))
             return [];
-        // EMPTY-QUERY contract is backend-uniform: no terms → [] (File/Pg parity).
         const q = termSet(query);
         if (q.size === 0)
             return [];
@@ -170,25 +123,17 @@ export class TiDBMemoryEngineBackend {
             const fm = fromJson(r.frontmatter);
             const d = jaccardDistance(q, this.haystackOf(r.slug, fm, r.body));
             if (d === null)
-                continue; // zero-overlap: not a candidate
+                continue;
             scored.push({ ...this.headerFromRow(r), score: d });
         }
-        // Deterministic id tie-break (opus 审 C4,Pg 版同注): tied scores must not order by row-arrival
-        // accident — the cross-backend equivalence assertion compares ordered projections.
         scored.sort((a, b) => (bands ? exposureBandOf(a) - exposureBandOf(b) : 0) || 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 = [];
-        // #307 件6(design/336 §2.3-2):external-origin 不可变律的**批次基线**(Pg 版同注)。逐条 patch 直打
-        // 真库 ⇒ 同批 delete 之后再 add 时库里已无该行,只看当下会误判成「合法新生命」。
         const originBaseline = createBatchCommittedBaseline();
         for (const patch of patches) {
             try {
@@ -205,17 +150,11 @@ export class TiDBMemoryEngineBackend {
                 report.conflicts.push({ op: patch.op, id: patch.id, reason: `io error: ${err instanceof Error ? err.message : String(err)}` });
             }
         }
-        // BEST-EFFORT history append (see TiDBMemoryEngineBackendOptions.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(`TiDBMemoryEngineBackend: 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)}`);
             }
@@ -224,8 +163,6 @@ export class TiDBMemoryEngineBackend {
     }
     async applyOne(patch, report, plannedSlugs, historyRows, originBaseline) {
         const T = TIDB_MEMORY_ENGINE_TABLES.entry;
-        // #307 件6(codex R1-[high],Pg 版同注):op 闭集**前置**判 —— 词表外的 op 会跳过两道白洗守卫、
-        // 落进 update 的 SQL 并报成一次 applied。零 I/O 拒绝。
         {
             const refusal = unknownPatchOpRefusal(patch.op);
             if (refusal !== undefined) {
@@ -233,15 +170,10 @@ export class TiDBMemoryEngineBackend {
                 return;
             }
         }
-        // A patch whose entry carries a DIFFERENT id than the patch addresses is malformed — refused up
-        // front, all backends alike (Pg 版同注).
         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;
         }
-        // #271 件1(R-1):键宽在任何 I/O 之前判,add/update 两条腿一处收(Pg 版同注)。本方言尤其承重
-        // ——非严格 MySQL 对超宽键**静默截断**(只发 warning),截断后的 scope/slug 指向**另一个**键:
-        // 两租户的盘折叠成一个、两个条目互串,写入侧不炸、读回侧才发现串了。拒绝式,零写。
         if (patch.op !== "delete" && patch.entry !== undefined) {
             const refusal = memoryEntryKeyWidthRefusal(patch.entry.scope, patch.entry.slug);
             if (refusal !== undefined) {
@@ -249,9 +181,6 @@ export class TiDBMemoryEngineBackend {
                 return;
             }
         }
-        // #319 增量([4768] 勘误 + core `1a5ebaa1`,Pg 孪生同注):**歧义 origin 表示**零写拒。判位与
-        // File 的 planOne 逐字同(表示合法性先于状态比较,且在任何 I/O 之前);判据用 core 导出的谓词
-        // (禁手抄——解 extra 里的 origin 形块那只解析器一旦解得比 core 宽松,就是给洗白开后门)。
         if (patch.op !== "delete" && patch.entry !== undefined) {
             const refusal = ambiguousOriginRefusal(patch.entry.frontmatter);
             if (refusal !== undefined) {
@@ -265,25 +194,13 @@ export class TiDBMemoryEngineBackend {
                 report.conflicts.push({ op: "add", id: patch.id, reason: "add patch without an entry" });
                 return;
             }
-            // Reject-not-rewrite for bytes SQL cannot store(Pg 版 applyOne add 分支同一守卫,复用同一
-            // pgHasUnstorable——不是重派生一份近似正则):NUL / 孤立 UTF-16 代理不是 PG 独有的病,mysql2/
-            // utf8mb4 对同样的字节没有 PG 的 22P05 fail-loud 报错,驱动或服务端会静默 mangle(丢字节/替换为
-            // U+FFFD 视驱动版本而定),写入侧不炸、读回侧才发现内容偏离——这比 PG 的写时报错更隐蔽。三后端
-            // (pg/tidb/local)必须对同一输入给出同一行为,否则同一份 sync 数据在不同部署形态下悄悄分叉。
             if (pgHasUnstorable(entry.frontmatter) || pgHasUnstorable(entry.body) || pgHasUnstorable(entry.slug)) {
                 report.conflicts.push({ op: "add", id: entry.id, reason: "unstorable_bytes (utf8mb4 cannot store NUL/lone surrogates without mangling; strip them at the source — the store never rewrites content)" });
                 return;
             }
-            // (R5 的 add-only slug 守卫已上提到 applyOne 顶部的键宽块 —— add/update 同判,见那里的注。)
-            // Cross-scope add refusal (opus 审 C3,Pg 版同注): an add whose id already lives in a DIFFERENT
-            // scope must not silently MOVE the row; same-scope re-add stays the idempotent overwrite.
-            // One probe serves BOTH the E-02 guard and the cross-scope refusal (File/Pg parity).
             const prior = await this.selectRows(`SELECT scope, slug, rev, frontmatter FROM ${T} WHERE id = ?`, [entry.id]);
             const priorRow = prior.length > 0 ? prior[0] : undefined;
             let existsById = priorRow !== undefined;
-            // #307 件6(design/336 §2.3-2)—— external-origin 不可变律,**判在 guard 之前**(Pg 版同注:core
-            // File backend 的 planOne 同序;顺序反了带 guard 的洗白 add 会先报 add_guard_absent_conflict,
-            // 而契约试剂盒要的是 /malformed patch refused/,同一输入两后端两个答复)。
             {
                 const committedBaseFm = rememberBatchCommitted(originBaseline, entry.id, priorRow !== undefined ? fromJson(priorRow.frontmatter) : undefined);
                 const refusal = originWhitewashRefusal("add", committedBaseFm, entry.frontmatter);
@@ -291,17 +208,12 @@ export class TiDBMemoryEngineBackend {
                     report.conflicts.push({ op: "add", id: entry.id, reason: refusal });
                     return;
                 }
-                // #337(conformance c36,design/339):distilled 不可变律的 add 腿 —— origin 律同基线同判位
-                // (guard 之前;同批 delete+re-add 靠基线拒,已提交墓碑后的 add 放行)。
                 const dRefusal = distilledWhitewashRefusal("add", committedBaseFm, entry.frontmatter);
                 if (dRefusal !== undefined) {
                     report.conflicts.push({ op: "add", id: entry.id, reason: dRefusal });
                     return;
                 }
             }
-            // E-02 add-if-absent guard (core 1.275.1/1.276.0 contract clause; caught live by the contract
-            // suite on real TiDB 2026-07-13): same rev AND same (scope, slug) projection = idempotent
-            // fall-through; different rev OR projection = REPORTED add_guard_absent_conflict + currentRev.
             if (patch.guard === "absent" && priorRow) {
                 const currentRev = String(priorRow.rev);
                 if (currentRev !== computeEntryRev(entry)) {
@@ -312,7 +224,6 @@ export class TiDBMemoryEngineBackend {
                     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);
@@ -321,15 +232,8 @@ export class TiDBMemoryEngineBackend {
                     return;
                 }
             }
-            // Slug collision with a DIFFERENT entry → deterministic `-n` suffix (file-backend parity); the
-            // probe is only an optimization — the write INSIDE the loop is arbitrated by uq_agent_memory_engine_entry_scope_slug, and
-            // a concurrent loser retries the next suffix (Pg 版同注).
             let slug = entry.slug;
             for (let n = 2;; n++) {
-                // #271 件1(codex 对抗复审 H1,验真属实):**派生**候选也要吃守卫。顶部那道只判调用方给的原始
-                // slug,而本循环在撞键时派生 `${slug}-${n}` —— 511 字符的合法 slug 撞一次就派生出 513 字符,
-                // 绕过守卫直奔 INSERT(非严格 MySQL 截成另一个 512 字符键、还照报未截断的 slug=最坏形)。
-                // 判在循环**顶**=任何探针/写之前;后缀装不下 ⇒ 可分类 conflict,不是静默截断也不是死循环。
                 const derivedRefusal = memoryEntryKeyWidthRefusal(entry.scope, slug);
                 if (derivedRefusal !== undefined) {
                     report.conflicts.push({ op: "add", id: entry.id, reason: `${derivedRefusal} (slug collision suffix "-${n - 1}" no longer fits the column — shorten the entry name)` });
@@ -345,18 +249,12 @@ export class TiDBMemoryEngineBackend {
                         const sizeBytes = Buffer.byteLength(serializeEntryFile(stored), "utf8");
                         try {
                             if (existsById) {
-                                // Idempotent overwrite leg (Pg 的 ON CONFLICT(id) DO UPDATE 对应面;见文件头:MySQL 的
-                                // ON DUPLICATE KEY UPDATE 会被 (scope,slug) 键劫持改写他人行,禁用)。
                                 const res = await this.write(`UPDATE ${T} SET scope = ?, slug = ?, frontmatter = ?, body = ?, rev = ?, mtime_ms = ?, size_bytes = ?, embedding = NULL WHERE id = ?`, [stored.scope, stored.slug, JSON.stringify(stored.frontmatter), stored.body, rev, this.clock(), sizeBytes, stored.id]);
                                 if (res.affectedRows === 0) {
-                                    // affectedRows: under mysql2 default (FOUND_ROWS ⇒ matched count) 0 = row gone;
-                                    // under changed-only semantics 0 could also mean already-at-target — the fresh-rev branch below covers BOTH: 0 = either the row already
-                                    // holds exactly this content (idempotent no-op = success) or it vanished under a
-                                    // concurrent delete (→ fall back to the INSERT leg, same slug).
                                     const still = await this.selectRows(`SELECT id FROM ${T} WHERE id = ?`, [stored.id]);
                                     if (still.length === 0) {
                                         existsById = false;
-                                        continue; // row deleted concurrently — retry this slug via the INSERT leg
+                                        continue;
                                     }
                                 }
                             }
@@ -367,18 +265,16 @@ export class TiDBMemoryEngineBackend {
                         catch (err) {
                             if (isDupEntry(err)) {
                                 if (isPrimaryKeyDup(err)) {
-                                    existsById = true; // concurrent same-id add won the PK — retry this slug via the overwrite leg
+                                    existsById = true;
                                     continue;
                                 }
-                                slug = `${entry.slug}-${n}`; // concurrent winner took this (scope,slug) — next suffix
+                                slug = `${entry.slug}-${n}`;
                                 continue;
                             }
                             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;
@@ -387,8 +283,6 @@ export class TiDBMemoryEngineBackend {
                 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.selectRows(`SELECT slug, rev, scope, frontmatter FROM ${T} WHERE id = ?`, [patch.id]);
         if (cur.length === 0) {
             report.conflicts.push({ op: patch.op, id: patch.id, reason: "unknown id (entry not found in backend)" });
@@ -397,13 +291,7 @@ export class TiDBMemoryEngineBackend {
         const currentRev = String(cur[0].rev);
         const currentSlug = String(cur[0].slug);
         const currentScope = String(cur[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.
         const committedFm = fromJson(cur[0].frontmatter);
-        // #307 件6:delete 腿也要记基线(Pg 版同注)—— 同批「delete 掉带标记的行、再 add 一条不带标记的」
-        // 正是洗白的最直接写法,而 delete 一旦落库,后面那条 add 的 SELECT 什么都看不到。
         const committedBaseFm = rememberBatchCommitted(originBaseline, patch.id, committedFm);
         if (patch.op === "update" && patch.entry !== undefined) {
             if (committedFm.provenance?.kind === "repo_file") {
@@ -419,14 +307,11 @@ export class TiDBMemoryEngineBackend {
                     return;
                 }
             }
-            // #307 件6:origin 不可变律的 update 腿(Pg 版同注:repo_file 在前、origin 在后、两者都在 rev CAS 之前)。
             const refusal = originWhitewashRefusal("update", committedBaseFm, patch.entry.frontmatter);
             if (refusal !== undefined) {
                 report.conflicts.push({ op: "update", id: patch.id, reason: refusal });
                 return;
             }
-            // #337(conformance c36/c37):distilled 不可变律的 update 腿 —— 同样先于 rev CAS(c37:骑着
-            // stale baseRev 的 strip 答 malformed refusal,不是 rev mismatch)。
             const dRefusal = distilledWhitewashRefusal("update", committedBaseFm, patch.entry.frontmatter);
             if (dRefusal !== undefined) {
                 report.conflicts.push({ op: "update", id: patch.id, reason: dRefusal });
@@ -434,26 +319,16 @@ export class TiDBMemoryEngineBackend {
             }
         }
         if (patch.baseRev !== undefined && patch.baseRev !== currentRev) {
-            // Per-id CAS (§2.4 并发): NEVER blind-write over a concurrent change. ABA note shared with the
-            // File/Pg backends (rev is a content hash — an A→B→A round-trip re-arms a stale baseRev; benign
-            // by construction, same canonical content).
             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 landing between the SELECT and this DELETE
-            // re-reports as the same CAS conflict instead of silently deleting the newer committed state.
-            // DELETE's affectedRows counts deleted rows (FOUND_ROWS only affects UPDATE): 0 = the row changed/vanished.
             const res = await this.write(`DELETE FROM ${T} WHERE id = ? AND rev = ?`, [patch.id, currentRev]);
             if (res.affectedRows === 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 the idempotent
-            // no-op ODKU 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;
@@ -463,8 +338,6 @@ export class TiDBMemoryEngineBackend {
             report.conflicts.push({ op: "update", id: patch.id, reason: "update patch without an entry" });
             return;
         }
-        // Same reject-not-rewrite guard as the add leg above(Pg 版 applyOne update 分支同一守卫)—
-        // an update carrying unstorable bytes must refuse before the CAS write, not mangle silently.
         if (pgHasUnstorable(entry.frontmatter) || pgHasUnstorable(entry.body) || pgHasUnstorable(entry.slug)) {
             report.conflicts.push({ op: "update", id: patch.id, reason: "unstorable_bytes (utf8mb4 cannot store NUL/lone surrogates without mangling; strip them at the source — the store never rewrites content)" });
             return;
@@ -472,22 +345,9 @@ export class TiDBMemoryEngineBackend {
         const rev = computeEntryRev(entry);
         const res = await this.write(`UPDATE ${T} SET scope = ?, slug = ?, frontmatter = ?, body = ?, rev = ?, mtime_ms = ?, size_bytes = ?, embedding = NULL WHERE id = ? AND rev = ?`, [entry.scope, entry.slug, JSON.stringify(entry.frontmatter), entry.body, rev, this.clock(), Buffer.byteLength(serializeEntryFile(entry), "utf8"), entry.id, currentRev]);
         if (res.affectedRows === 0) {
-            // Zero AFFECTED rows is ambiguous under the default protocol (changed-rows counting): the row may
-            // hold rev==currentRev with byte-identical values (matched but unchanged). Disambiguate on the
-            // fresh rev: the row must STILL EXIST and already be at the NEW rev ⇒ the content is exactly the
-            // target state (idempotent success — also covers a concurrent writer landing the same hash);
-            // anything else ⇒ CAS conflict with the rev NOW.
-            // 🔴 codex lens-3: the row-EXISTENCE check is load-bearing. When the row was concurrently DELETED
-            // between the SELECT and this UPDATE, affectedRows is also 0; a fallback that returned the pre-race
-            // rev would make `fresh === rev` true for a byte-identical update and FALSELY report `applied` on a
-            // row that no longer exists — while the Pg twin (UPDATE … RETURNING → zero rows) correctly reports a
-            // conflict. `freshRevOrMissing` returns undefined for a gone row, so it falls through to conflict,
-            // restoring dialect parity (never accept a lost write as applied).
             const fresh = await this.freshRevOrMissing(entry.id);
             if (fresh === rev) {
                 report.applied.push({ op: "update", id: entry.id, slug: entry.slug });
-                // History: the idempotent already-at-target success is a committed version too — the
-                // (id, rev) idempotent append dedupes if this exact version was already recorded.
                 if (this.history)
                     historyRows.push({ id: entry.id, rev, prevRev: currentRev, op: "update", scope: entry.scope, snapshot: { ...entry, rev }, writtenAtMs: this.clock() });
                 return;
@@ -496,19 +356,13 @@ export class TiDBMemoryEngineBackend {
             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() });
     }
-    /** 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. */
     async freshRevOrMissing(id) {
         const rows = await this.selectRows(`SELECT rev FROM ${TIDB_MEMORY_ENGINE_TABLES.entry} WHERE id = ?`, [id]);
         return rows.length > 0 ? String(rows[0].rev) : undefined;
     }
-    /** 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). */
     async freshRev(id, fallback) {
         return (await this.freshRevOrMissing(id)) ?? fallback;
     }
@@ -517,9 +371,7 @@ export class TiDBMemoryEngineBackend {
         return rows.length > 0 ? String(rows[0].cursor) : undefined;
     }
     async setConsolidationCursor(scope, cursor) {
-        assertMemoryScopeWidth(scope); // #271 件1:游标表 PK 也是 VARCHAR(190) —— 截断=把两个盘的整合游标折叠成一个
-        // Single unique key (the PK) on this table — ON DUPLICATE KEY UPDATE is unambiguous here,
-        // unlike the two-unique-key entries table (see the file-head dialect note).
+        assertMemoryScopeWidth(scope);
         await this.write(`INSERT INTO ${TIDB_MEMORY_ENGINE_TABLES.cursor} (scope, \`cursor\`) VALUES (?, ?) ON DUPLICATE KEY UPDATE \`cursor\` = VALUES(\`cursor\`)`, [scope, cursor]);
     }
 }

package/dist/plugins/memory-engine-vector-util.js

@@ -1,17 +1,7 @@
-/** memory-engine 方言实现共用的纯工具函数。三个距离/词集函数(termSet/jaccardDistance/cosineDistance)
- *  在 core(1.268.0 起公开导出,单一语义源)——消费者直引 core([2354] 兼容面全清:此处转口已删)。
- *  `isUniqueViolation` 重新内联:它当年随 core 的 pg **示例适配器**导出面走,core 1.424 按 clay 包卫生令
- *  把整个 examples 面退出 npm 包([1803] BREAKING)⇒ re-export 断源。原为逐字抄自 core 1.423
- *  `examples/adapters/pg-adapter.js`(纯谓词,无 byte-equal 契约约束);A-032 P1-① 后**码面判据**
- *  改走属主 `sql-errors.ts`,只留 message 补充臂(理由在函数体内)。 */
 import { isPgUniqueViolation } from "./sql-errors.js";
 export function isUniqueViolation(err) {
-    // 码面判据 = 属主谓词(A-032 P1-①,`plugins/sql-errors.ts`)。
     if (isPgUniqueViolation(err))
         return true;
-    // 🔴 message 正则臂是**本站点的显式补充**,不上提属主:memory-engine 的 pg 腿吃的是**裸 PgQueryFn**
-    // (调用方自带的连接封装),错误对象未必是 node-pg 的原生错误类——中间层可能只把 message 传下来。
-    // 其余各店都攥着自己的驱动/池,拿得到带 SQLSTATE 的原错误,不需要也不该按文案分支(#90 门②)。
     if (typeof err !== "object" || err === null)
         return false;
     return /duplicate key|unique constraint|already exists/i.test(String(err.message ?? ""));

package/dist/plugins/memory-key-guards.js

@@ -1,29 +1,5 @@
-/** R5(车A [3191] 欠账,批γ 落地;#271 件1 补齐写口):memory 面的键宽写前守卫。
- *  列宽收窄后,模型/调用方可控的键(条目名 slug、租户盘 scope)超宽此前落裸 SQL 错(PG
- *  `value too long`)或非严格 MySQL 静默截断(截断=两个不同的键折叠成同一行=**条目互串 / 两个租户
- *  的盘塌成一个**,最危险形)。写前响亮拒,错误可分类。
- *  列宽同源门=test/key-width-guards.test.ts(守卫常量 vs 两方言 DDL 逐字对表);写口在场门=同文件
- *  「#271 件1」组(超宽键一条写语句都不许发出 seam)。
- *
- *  **本文件是这两个宽度的唯一属主**(#271 件1):scope 守卫此前住在 `src/memory-scope.ts`,只被
- *  `memoryScopeFor` 的产出处消费,而 store 写口全无——同一个列宽有两个居所、两半消费面,正是
- *  「守卫在位≠写口接上」那类缺口的温床。`memory-scope.ts` 现在只**再导出**本文件的这两个符号
- *  (旧 import 路径逐字不变)。 */
-/** memory-engine entry 表 `slug` 列宽(两方言 VARCHAR(512) 同宽;(scope,slug) UNIQUE 键预算注在 DDL)。 */
 export const MEMORY_SLUG_COLUMN_CHARS = 512;
-/** memory 面 `scope` 列宽(两方言 VARCHAR(190) 同宽:engine 的 entry/cursor 两表 + memory-sync 的
- *  sync_cursor/push_queue/history)。`formatUserScope`/`formatProjScope` 的段编码(百分号转义)会
- *  **膨胀**——非 ASCII principal 编码后可超列宽,故产出处与写口两道都要判。 */
 export const MEMORY_SCOPE_COLUMN_CHARS = 190;
-/**
- * 键宽的**计数口径**(codex 对抗复审 M1,#271 件1 验真后修):两方言的 `VARCHAR(n)` 数的都是
- * **字符 = Unicode 码点**(PG varchar(n) / MySQL-protocol utf8mb4 VARCHAR(n) 同口径,后者每字符
- * 最多 4 字节、astral 字符仍算 1)。而 JS 的 `string.length` 数的是 **UTF-16 code unit** —— 一个
- * emoji 算 2。照 `.length` 判会把「库里只占 96 字符」的 scope 按 192 拒掉:守卫从「防截断」变成
- * 「误伤合法窄键」,方向反了。
- *
- * (孤立代理项这种**不可存**字节不归本函数管——那是 `pgHasUnstorable` 的拒绝式,两条判据各司其职。)
- */
 function widthChars(v) {
     return [...v].length;
 }
@@ -41,16 +17,6 @@ export function assertMemoryScopeWidth(scope) {
             `both SQL dialects pin); got ${n} — use a shorter principal/projectId (non-ASCII characters expand ~9x when encoded)`);
     }
 }
-/**
- * 一个 entry 写(add / update)的两个键宽一起判 —— 两方言的 `applyOne` 在**任何 I/O 之前**调用它。
- *
- * 为什么两条腿共用一个入口而不是各自展开:add 与 update 写的是**同两列**(update 的
- * `SET scope = …, slug = …` 会改盘也会改名),R5 那批只护住了 add ⇒ 一次改名就能把超宽 slug 送进
- * DB。一个入口=两条腿不会再各自漂。
- *
- * 返回**字符串**而不是抛:两方言的 `applyPatches` 契约是「冲突进 report,不抛」(与
- * `unstorable_bytes` 的拒绝式同族——后端能力差异诚实暴露,重试恒同答=幂等成立)。`undefined` = 过。
- */
 export function memoryEntryKeyWidthRefusal(scope, slug) {
     try {
         assertMemoryScopeWidth(scope);