@sema-agent/server 7.43.0 → 7.44.0

package/dist/plugins/memory-embedder.js

@@ -1,71 +1,23 @@
-/**
- * #228 —— OpenAI 兼容的 embedder(黑板 [3590] 裁②:core 只留了 `PgEmbedder` 这个**纯接口**
- * (`{ embed(text) → number[]; dimensions }`),没有任何现成实现件;部署半场归本仓)。
- *
- * ## 形
- *
- * `POST {endpoint}/embeddings`,body `{ model, input }`,读 `data[0].embedding` —— OpenAI /
- * DashScope / TEI / vllm / ollama 的 `/v1` 面同形。auth 可选(自托管端点通常没有 key)。
- *
- * ## 为什么校验做得这么硬
- *
- * 向量列写错维度是**静默毒库**形([3606] 裁③):错长度向量既不会让 DB 报错(本仓 pg 记忆表的
- * embedding 列是 `jsonb`,无维度约束),也不会让检索报错(维度不匹配的行只是悄悄退回词面档)——
- * 于是「向量面开着」这句话变成一句谎,而且没有任何一层会说出来。所以:
- *  · 响应形用 zod 校验(`data[0].embedding` 必须是 `number[]`),不符 = 抛带上下文的错;
- *  · 长度与声明维度不等 = 抛,**绝不截断 / 补零**(那正是把毒喂进库的两种手法);
- *  · 非 2xx / 非 JSON = 抛(status + body 前 200 字节,memory-sync transport 同款诊断姿势)。
- *
- * 抛出去之后由调用方处置:`PgMemoryEngineBackend.embeddingParam` 的长度门会让该行退回词面档,
- * `search` 的词面腿 `.catch(() => null)` 会让检索继续跑 —— 即「embedder 坏了 = 退回 lexical」,
- * 而不是「embedder 坏了 = 写坏向量」。
- *
- * ## 超时
- *
- * `AbortSignal.timeout(timeoutMs)`(缺省 30s,`MEMORY_EMBEDDER_TIMEOUT_MS` 覆盖,越界/坏值拒启)。
- * 记忆写入路径是同步等 embed 的,挂死的端点会把整条 harvest 吊住(undici 默认 headers 超时 300s 太钝)。
- */
 import { z } from "zod";
-/** OpenAI `/v1/embeddings` 响应的**最小**契约:只读第一条向量,其余键(usage/object/model)不关心。 */
 const EmbeddingsResponse = z.object({
     data: z.array(z.object({ embedding: z.array(z.number()) })).min(1),
 });
-/**
- * 端点归一:`MEMORY_EMBEDDER_ENDPOINT` 收两种写法 —— OpenAI 兼容**基址**(`https://x/v1`)或**完整**
- * 端点(`https://x/v1/embeddings`)。两种都是 operator 手上真实存在的抄法,而一律硬拼 `/embeddings`
- * 会产出 `/v1/embeddings/embeddings`(这条键最常见的手滑形)。归一不是降级:两条路都指向同一个真 URL,
- * 没有任何一种输入被静默改成**别的**语义。
- *
- * ⚠️ 只动 `pathname`(codex 复审 F3,已核真):第一版在**整串**上做 `endsWith`/拼接,于是带 query 的
- * 端点全错 —— Azure OpenAI 形 `https://h/v1/embeddings?api-version=1` 会被拼成 query 值里带
- * `1/embeddings`,`https://h/v1?api-version=1` 则永远拿不到 `/embeddings` 路径。两种都过得了启动期的
- * URL 合法性门,只在运行期炸(而运行期的炸法就是上面那条「写入失败/检索退档」的静默病)。
- */
 export function embeddingsUrl(endpoint) {
-    const u = new URL(endpoint); // config 层已校验;直调工厂时坏 URL 在这里响亮抛
-    u.hash = ""; // fragment 对服务端无意义,带上只会污染日志
+    const u = new URL(endpoint);
+    u.hash = "";
     const path = u.pathname.replace(/\/+$/, "");
-    // 「已经带尾巴了吗」按**解码后**的末段判(codex 二轮 F3,已核真):`/v1/%65mbeddings` 与
-    // `/v1/embeddings` 是同一条路径,只比对序列化文本会给前者再叠一层。只解 unreserved 转义
-    // (RFC 3986 的 `A-Za-z0-9-._~`)—— 其余转义原样保留,decodeURIComponent 的坏 `%` 抛错面也一并避开。
     u.pathname = decodeUnreservedEscapes(path).endsWith("/embeddings") ? path : `${path}/embeddings`;
     return u.toString();
 }
-/** 只把 unreserved 字符的百分号转义解回来(不抛、不改变其它转义)。 */
 function decodeUnreservedEscapes(s) {
     return s.replace(/%([0-9A-Fa-f]{2})/g, (whole, hex) => {
         const c = String.fromCharCode(Number.parseInt(hex, 16));
         return /[A-Za-z0-9\-._~]/.test(c) ? c : whole;
     });
 }
-/**
- * 诊断面用的**脱敏** URL(codex 复审 F4,已核真):端点里可能带 userinfo(`https://user:pass@h/v1`)
- * 或把凭据放 query(Azure 的 `api-key=`),而错误文本会进日志、进 PatchReport 的 conflict reason。
- * 主机与路径保留(诊断价值全在这里),userinfo 抹掉、query 值一律换成 `***`(键名保留,便于认形)。
- */
 export function redactEndpointForLog(raw) {
     if (!URL.canParse(raw))
-        return "<invalid-url>"; // 谓词先行,不用 catch 兜(#191 静默降级门:catch 回默认值是被数的形)
+        return "<invalid-url>";
     const u = new URL(raw);
     u.username = "";
     u.password = "";
@@ -73,28 +25,20 @@ export function redactEndpointForLog(raw) {
         u.searchParams.set(k, "***");
     return u.toString();
 }
-/** 端点 query 上的**值**(Azure 形把 key 放 query;这些字面量要从任何诊断文本里洗掉)。 */
 function credentialsInQuery(endpoint) {
     if (!URL.canParse(endpoint))
         return [];
     return [...new URL(endpoint).searchParams.values()].filter((v) => v.length > 0);
 }
-/** 造一个 OpenAI 兼容的 `PgEmbedder`(工厂命名律:返回带行为的对象 ⇒ `create*`)。 */
 export function createOpenAiCompatEmbedder(opts) {
     const url = embeddingsUrl(opts.endpoint);
     const shownUrl = redactEndpointForLog(url);
     const fetchImpl = opts.fetchImpl ?? fetch;
     const { model, dimensions, timeoutMs, apiKey, onFailure } = opts;
-    // 洗白名单 = 本部署已知的**全部**凭据字面量:apiKey + 端点 query 上的值(Azure 形把 key 放 query;
-    // codex 二轮 F1)。userinfo 在 config 层就被拒了,这里不再单列。
     const secrets = [...(apiKey !== undefined ? [apiKey] : []), ...credentialsInQuery(opts.endpoint)];
-    /** 供应商 body / 传输层错误进诊断文本前先洗一遍:回显自家凭据的代理/网关是真实存在的形。 */
     const scrub = (raw) => secrets.reduce((acc, s) => acc.replaceAll(s, "***"), raw);
     const safeSlice = (raw) => scrub(raw).slice(0, 200);
     const call = async (text) => {
-        // 传输层失败(DNS/连不上/超时)也要走脱敏形(codex 二轮 F1):undici 的错误链里可能带上完整 URL,
-        // 而这条错会进 warn 日志与 PatchReport 的 conflict reason。**刻意不挂 cause**:挂上等于把没洗过的
-        // 原始文本从后门放回诊断面(打印错误链的人一样看得见),这里只带洗过的文本。
         let res;
         try {
             res = await fetchImpl(url, {
@@ -113,8 +57,6 @@ export function createOpenAiCompatEmbedder(opts) {
         const raw = await res.text().catch((readErr) => {
             throw new Error(`memory embedder POST ${shownUrl}: response body unreadable — ${safeSlice(String(readErr))}`);
         });
-        // 诊断面纪律:回显 status + body 前缀(端点的 typed error body 就是最好的线索),但 URL 走脱敏形、
-        // body 先洗掉全部已知凭据字面量 —— 错误文本会进日志与 PatchReport 的 conflict reason。
         if (!res.ok)
             throw new Error(`memory embedder POST ${shownUrl}: HTTP ${res.status} ${safeSlice(raw)}`);
         let json;
@@ -141,25 +83,17 @@ export function createOpenAiCompatEmbedder(opts) {
                 return await call(text);
             }
             catch (err) {
-                // 先让部署面看见,再**原样**抛(观测腿绝不改变结果,连真错的属性都不碰)
                 try {
                     onFailure?.(err);
                 }
                 catch (hookErr) {
-                    // 观测腿自己坏了:①不许顶替真故障(拿监控的病盖住业务的病是最坏的一种交换);②不许改动真错
-                    // ——第一版往 err.cause 上挂,冻结/不可写的 err 会让**赋值本身**抛,于是 TypeError 顶替了
-                    //   真错(codex 二轮 F2,已核真);③也不许无声 —— 走 process.emitWarning,不碰真错分毫。
                     process.emitWarning(`memory embedder onFailure hook threw: ${String(hookErr)}`, "MemoryEmbedderObservabilityWarning");
                 }
-                throw err; // 原对象原样抛出(identity 不变)
+                throw err;
             }
         },
     };
 }
-/**
- * 装配腿:配置在场 ⇒ 造 embedder,缺席 ⇒ `undefined`(= core 的三档推断落回 lexical)。
- * 这一层单独存在是为了让「注入真的接上了」可测 —— `openStores` 本身要真 DB 才跑得起来。
- */
 export function memoryEmbedderFor(config, deps = {}) {
     const cfg = config.memoryEmbedder;
     if (cfg === undefined)

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

@@ -1,43 +1,15 @@
-// ⚠️ 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 } from "@sema-agent/core";
 import { isUniqueViolation } from "./memory-engine-vector-util.js";
 import { computeEntryRev, serializeEntryFile } from "@sema-agent/core";
 import { pgSafeJsonStringify, 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 不可变律 —— 两支 SQL 孪生共用**一份**判据。
+import { assertMemoryScopeWidth, memoryEntryKeyWidthRefusal } from "./memory-key-guards.js";
 import { ambiguousOriginRefusal, createBatchCommittedBaseline, exposureBandOf, exposureCarriage, originMarkedSqlPredicate, originWhitewashRefusal, rememberBatchCommitted, distilledWhitewashRefusal, distilledCarriage, unknownPatchOpRefusal, } from "./memory-origin-law.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 = {
     entry: "agent_memory_engine_entry",
     cursor: "agent_memory_engine_cursor",
 };
-/** 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)})`);
     }
@@ -59,27 +31,16 @@ export async function ensurePgMemoryEngineSchema(query, opts = {}) {
         await query(`CREATE INDEX IF NOT EXISTS idx_${PG_MEMORY_ENGINE_TABLES.entry}_scope ON ${PG_MEMORY_ENGINE_TABLES.entry} (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 uq_${PG_MEMORY_ENGINE_TABLES.entry}_scope_slug ON ${PG_MEMORY_ENGINE_TABLES.entry} (scope, slug)`);
     await query(`CREATE TABLE IF NOT EXISTS ${PG_MEMORY_ENGINE_TABLES.cursor} (
     scope varchar(190) COLLATE "C" PRIMARY KEY,
     cursor text COLLATE "C" 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(", ");
 }
@@ -92,9 +53,7 @@ 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";
     }
@@ -107,12 +66,9 @@ 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;
@@ -133,10 +89,7 @@ export class PgMemoryEngineBackend {
             mtimeMs: Number(r.mtime_ms),
             rev: r.rev,
             sizeBytes: Number(r.size_bytes),
-            // #319(design/336 §5.2):committed external-origin 事实随**每一个**头面(listHeaders + search)。
-            // 归一化只有一份(memory-origin-law.exposureCarriage → core 的 committedOriginOf),两支方言同源。
             ...exposureCarriage(fm),
-            // #337(conformance c38,TiDB 孪生同注):distilled 事实(carrierRev + supersedes)随每一个头面。
             ...distilledCarriage(fm),
         };
     }
@@ -151,9 +104,6 @@ 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 [];
@@ -165,52 +115,31 @@ 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.entry} WHERE id IN (${inPlaceholders(1, uniq.length)}) ORDER BY id`, uniq);
-        return res.rows.map((r) => this.entryFromRow(r)); // unknown ids: silently absent
+        return res.rows.map((r) => this.entryFromRow(r));
     }
     async search(query, scopes, opts) {
-        // #319(design/336 §5.2):两带序 —— 未标记先、已标记后,**带序在截断之前**(理由见
-        // memory-origin-law.exposureBandOf 的顶注)。缺席/false ⇒ 单带序,与本方法 pre-336 形逐字节同。
         const bands = opts?.exposureBands === true;
-        /** 契约序:(带号 ‖ 缺席时恒 0) → score 升 → id。三档共用一只比较器,谁都别自己写一份。 */
         const contractOrder = (a, b) => (bands ? exposureBandOf(a) - exposureBandOf(b) : 0) || a.score - b.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
-        // 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) {
                 const vecParam = scopes.length + 1;
-                // #319:本档的排序**和截断都在 SQL 里**,所以两带序也必须进 ORDER BY —— 在进程里对一页
-                // 已截断的结果重排是排不出来的(那正是契约要拒的「干净条目被饿死」)。带号谓词=不可变律
-                // 模块里那条 `committedOriginOf` 的下推形(逐元素跑 core 的行首正则,与 JS 判据机器对表;
-                // 为什么不能图省事写成 LIKE,见 originMarkedSqlPredicate 的顶注)。
                 const bandExpr = bands ? `(CASE WHEN ${originMarkedSqlPredicate("frontmatter")} THEN 1 ELSE 0 END) ASC, ` : "";
                 const res = await this.query(`SELECT id, scope, slug, frontmatter, rev, mtime_ms, size_bytes, embedding <=> $${vecParam}::vector AS dist
              FROM ${PG_MEMORY_ENGINE_TABLES.entry}
             WHERE scope IN (${inPlaceholders(1, scopes.length)}) AND embedding IS NOT NULL
             ORDER BY ${bandExpr}embedding <=> $${vecParam}::vector ASC, id ASC
             LIMIT ${Math.min(limit, 100_000)}`, [...scopes, vectorLiteral(qv)]);
-                // ⚠️ `id ASC` 必须写在 SQL 的 ORDER BY 里、也就是 LIMIT **之前**(codex 对抗复审 R1-[medium]):
-                // 同分(同一条向量距离)超过 limit 条时,决定「谁被截掉」的是这一句;缺了它,留下哪几条由执行
-                // 计划随机决定,页内怎么重排都换不回被截掉的那条。列是 `text COLLATE "C"` ⇒ 字节序,与下面
-                // 进程内比较器的定序同向。
                 const hits = res.rows.map((r) => ({ ...this.headerFromRow(r), score: Number(r.dist) }));
-                // 页内再排一次:契约序的最终裁决在进程侧(单带时是恒等重排)。
                 return hits.sort(contractOrder);
             }
-            // 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.entry} WHERE scope IN (${inPlaceholders(1, scopes.length)})`, [...scopes]);
         const queryVec = this.embedder ? await this.embedder.embed(query).catch(() => null) : null;
@@ -219,8 +148,6 @@ 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) {
@@ -233,24 +160,14 @@ 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).
-        // #319:整档在进程内排完**再**切片 ⇒ 两带序天然落在截断之前(SQL 侧无 LIMIT 可绕过)。
         scored.sort(contractOrder);
         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 不可变律的**批次基线**。本后端逐条 patch 直打真库,
-        // 所以同批 delete 之后再 add 时库里已无该行 —— 只看当下会把它误判成「合法新生命」。按本批第一次
-        // 触碰记下已提交 origin,整批按那一份判(理由与两半判据见 memory-origin-law.ts 顶注)。
         const originBaseline = createBatchCommittedBaseline();
         for (const patch of patches) {
             try {
@@ -267,17 +184,11 @@ 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)}`);
             }
@@ -286,9 +197,6 @@ export class PgMemoryEngineBackend {
     }
     async applyOne(patch, report, plannedSlugs, historyRows, originBaseline) {
         const T = PG_MEMORY_ENGINE_TABLES.entry;
-        // #307 件6(codex R1-[high]):op 闭集**前置**判 —— 词表外的 op 会跳过两道白洗守卫(它们都写成
-        // `if (patch.op === "update")`)、落进 update 的 SQL 并报成一次 applied。零 I/O 拒绝(理由与
-        // 今日可达性见 memory-origin-law.ts 的 unknownPatchOpRefusal 顶注;tidb 孪生同处同判)。
         {
             const refusal = unknownPatchOpRefusal(patch.op);
             if (refusal !== undefined) {
@@ -296,18 +204,10 @@ export class PgMemoryEngineBackend {
                 return;
             }
         }
-        // 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;
         }
-        // #271 件1(R-1):键宽在**任何 I/O 之前**判,add/update 两条腿一处收(tidb 版同注)。R5 那批只
-        // 护住了 add 腿的 slug ⇒ 一次改名(update `SET scope=…, slug=…`)就能把超宽键送进 DB;而超宽键
-        // 的两个结局都坏——PG 落不可分类的裸 22001,非严格 MySQL **静默截断**(截断后的键指向**另一个**
-        // scope/slug:两租户的盘折叠 / 两条目互串)。拒绝式,与 unstorable_bytes 同族(后端能力差异诚实
-        // 暴露,重试恒同答=幂等成立);写语句一条都不发出去。
         if (patch.op !== "delete" && patch.entry !== undefined) {
             const refusal = memoryEntryKeyWidthRefusal(patch.entry.scope, patch.entry.slug);
             if (refusal !== undefined) {
@@ -315,9 +215,6 @@ export class PgMemoryEngineBackend {
                 return;
             }
         }
-        // #319 增量([4768] 勘误 + core `1a5ebaa1`):**歧义 origin 表示**零写拒。判位与 File 的 planOne
-        // 逐字同 —— 表示合法性先于状态比较:排在键形守卫之后、add/update 两支的 guard/跨 scope/白洗/CAS
-        // 之前,且在任何 I/O 之前。判据用 core 导出的谓词(禁手抄),文案照抄 File(跨后端同一输入同一答复)。
         if (patch.op !== "delete" && patch.entry !== undefined) {
             const refusal = ambiguousOriginRefusal(patch.entry.frontmatter);
             if (refusal !== undefined) {
@@ -331,28 +228,13 @@ 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;
             }
-            // (R5 的 add-only slug 守卫已上提到 applyOne 顶部的键宽块 —— add/update 同判,见那里的注。)
             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, frontmatter FROM ${T} WHERE id = $1`, [entry.id]);
             const priorRow = prior.rows.length > 0 ? prior.rows[0] : undefined;
-            // #307 件6(design/336 §2.3-2)—— external-origin 不可变律,**判在 guard 之前**:core File backend
-            // 的 planOne 也是先判 origin 再判 `guard:"absent"`,而契约试剂盒对「带 guard 的洗白 add」要的是
-            // `/malformed patch refused/`;顺序反了会先报 `add_guard_absent_conflict`,同一输入两后端两个答复。
-            // 基线取「本批第一次触碰」那一份(同批 delete 之后的 re-add 照样被这条拒;已提交的墓碑才是合法出口)。
             {
                 const committedBaseFm = rememberBatchCommitted(originBaseline, entry.id, priorRow !== undefined ? fromJson(priorRow.frontmatter) : undefined);
                 const refusal = originWhitewashRefusal("add", committedBaseFm, entry.frontmatter);
@@ -360,19 +242,12 @@ export class PgMemoryEngineBackend {
                     report.conflicts.push({ op: "add", id: entry.id, reason: refusal });
                     return;
                 }
-                // #337(conformance c36,design/339,TiDB 孪生同注):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, 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)) {
@@ -383,7 +258,6 @@ 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);
@@ -392,18 +266,10 @@ export class PgMemoryEngineBackend {
                     return;
                 }
             }
-            // 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 cEntry = entry;
             const embedding = await this.embeddingParam(this.haystackOf(cEntry.slug, cEntry.frontmatter, cEntry.body));
             let slug = cEntry.slug;
             for (let n = 2;; n++) {
-                // #271 件1(codex 对抗复审 H1;tidb 版同注):**派生**候选也要吃守卫 —— 顶部那道只判原始 slug,
-                // 而撞键派生的 `${slug}-${n}` 可以越过列宽(511 + "-2" = 513),此前直奔 INSERT 落裸 22001。
                 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)` });
@@ -424,14 +290,12 @@ export class PgMemoryEngineBackend {
                         catch (err) {
                             if (isUniqueViolation(err)) {
                                 slug = `${entry.slug}-${n}`;
-                                continue; // concurrent winner took this (scope,slug) — try the next suffix
+                                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;
@@ -440,8 +304,6 @@ 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.entry} 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)" });
@@ -450,13 +312,7 @@ 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.
         const committedFm = fromJson(cur.rows[0].frontmatter);
-        // #307 件6:**delete 腿也要记基线** —— 同批「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") {
@@ -472,15 +328,11 @@ export class PgMemoryEngineBackend {
                     return;
                 }
             }
-            // #307 件6:origin 不可变律的 update 腿。顺序与 core File backend 逐字同 —— repo_file 白洗判据
-            // 在前、origin 在后、两者都在 rev CAS 之前(judged on the committed frontmatter of THIS SELECT)。
             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,TiDB 孪生同注):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 });
@@ -488,28 +340,16 @@ 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.entry} 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;
@@ -523,7 +363,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; // R3 终形:拒绝式后恒干净,rev 对拍原文
+        const cEntry = entry;
         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.entry}
@@ -535,13 +375,9 @@ 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.entry} WHERE id = $1`, [id]);
         return res.rows.length > 0 ? String(res.rows[0].rev) : fallback;
@@ -551,7 +387,7 @@ export class PgMemoryEngineBackend {
         return res.rows.length > 0 ? String(res.rows[0].cursor) : undefined;
     }
     async setConsolidationCursor(scope, cursor) {
-        assertMemoryScopeWidth(scope); // #271 件1:游标表 PK 也是 varchar(190) —— 截断=把两个盘的整合游标折叠成一个
+        assertMemoryScopeWidth(scope);
         await this.query(`INSERT INTO ${PG_MEMORY_ENGINE_TABLES.cursor} (scope, cursor) VALUES ($1, $2)
        ON CONFLICT (scope) DO UPDATE SET cursor = $2`, [scope, cursor]);
     }