@sema-agent/server 7.43.0 → 7.44.0

package/dist/plugins/local-task-attachment-store.js

@@ -1,15 +1,6 @@
-/**
- * LocalTaskAttachmentStore —— D-1 附件店的 local 形(seamless-local-cloud 铁律:StoreBackend
- * kind tidb|pg|local 三态,附件面不得 cloud-only)。
- *
- * 布局:`<root>/attachments/<id>.json`(meta)+ `<id>.bin`(bytes)。id=uuidv7(server 铸,不含用户
- * 输入 ⇒ 文件名安全);meta 内含 owner/session 轴,门在读侧比对(单机单进程,无并发租户;SQL 店才是
- * 多租户形)。写=tmp+rename 原子(半写行不可见);索引=首次使用时全目录水合进内存 Map,之后同进程
- * 内存权威(local 模式规模小;跨进程并发不在 local 契约内——与 file-run-store 同口径)。
- */
 import { promises as fsp } from "node:fs";
 import { join } from "node:path";
-const ID_RE = /^[0-9a-f-]{16,64}$/i; // uuid 形(server 铸);水合时非此形的文件一律跳过
+const ID_RE = /^[0-9a-f-]{16,64}$/i;
 export class LocalTaskAttachmentStore {
     dir;
     metas;
@@ -18,8 +9,6 @@ export class LocalTaskAttachmentStore {
         this.dir = join(rootDir, "attachments");
     }
     hydrate() {
-        // #131-1:记「在飞的 promise」而非「结果」(同仓正确形=local-session-store.loaded)。记结果时,
-        // 同进程两条并发首触各自 readdir,晚到的空快照会覆盖已被 put() 写入的索引——盘上有档、内存答 null。
         this.hydration ??= (async () => {
             const m = new Map();
             try {
@@ -35,12 +24,10 @@ export class LocalTaskAttachmentStore {
                             m.set(id, meta);
                     }
                     catch {
-                        /* 半写/损坏 meta:跳过(bin 无 meta 即孤儿,reap 收) */
                     }
                 }
             }
             catch {
-                /* 目录不存在 = 空店 */
             }
             this.metas = m;
             return m;
@@ -55,7 +42,6 @@ export class LocalTaskAttachmentStore {
         const metaTmp = join(this.dir, `${rec.id}.json.tmp`);
         await fsp.writeFile(binTmp, Buffer.from(content));
         await fsp.rename(binTmp, join(this.dir, `${rec.id}.bin`));
-        // meta 后落:meta 在场 ⇒ bytes 必在场(读侧无半态)
         await fsp.writeFile(metaTmp, JSON.stringify(meta));
         await fsp.rename(metaTmp, join(this.dir, `${rec.id}.json`));
         metas.set(rec.id, { ...meta });
@@ -72,7 +58,7 @@ export class LocalTaskAttachmentStore {
             return new Uint8Array(await fsp.readFile(join(this.dir, `${id}.bin`)));
         }
         catch {
-            return null; // meta 在 bytes 丢(外力删档)——按不存在答,不抛
+            return null;
         }
     }
     async persistMeta(m) {

package/dist/plugins/mailbox-store-sql.js

@@ -1,17 +1,11 @@
 import { pgHasUnstorable, pgSanitizeText, PgUnstorableError } from "./pg-safe-json.js";
 export const MAILBOX_TABLE = "mailbox";
 export const MAILBOX_MSG_TABLE = "mailbox_message";
-/** InMemory append 同文案形(default-deny 谓词精神:无 scope 的盒=路由不明,写入即拒)。 */
 function assertScope(scope) {
     if (scope === undefined || scope === "") {
         throw new Error("MailboxStore.append: refusing a message without a scope");
     }
 }
-/** 键长守卫(复审 F5):TiDB `INSERT IGNORE` 对超 190 字节键**静默截断**(warning 降级)——截断键
- *  与全长参数的字节比对恒 miss(seq 分配读空行 TypeError / 隔离键错位);PG 侧是干净 22001,同点
- *  提前拒 = 双方言同文案 fail-loud。 */
-/** D4(试剂盒揪出,RB-251 语义):身份键含 NUL/控制符——TiDB VARBINARY 能存但与文件头「两后端一致
- *  拒绝」的声明不符(该声明此前是谎);写入面双方言同精神拒绝(PG 臂经 PgUnstorableError 已拒)。 */
 function assertIdentityChars(what, v) {
     if ([...v].some((ch) => ch.charCodeAt(0) < 0x20 || ch.charCodeAt(0) === 0x7f)) {
         throw new Error(`MailboxStore: ${what} contains control characters (refusing — identity keys must be byte-exact addressable)`);
@@ -25,25 +19,7 @@ function assertKeyBytes(what, v) {
 function bufToStr(v) {
     return Buffer.isBuffer(v) ? v.toString("utf8") : String(v);
 }
-/** `hopChain` 的 JSON 文本列上界(TiDB `TEXT` = 65535 字节)。core 侧链本就有界
- *  (`PEER_ADMISSION_DEFAULTS.maxChainLength` = 28,`PEER_HOP_CHAIN_WINDOW` = 32,元素是 peerAxisToken
- *  短串)⇒ 正常形离这个数几个数量级远;守卫存在的理由是**关掉 MySQL 的静默截断类**(非严格模式下
- *  超长 TEXT 写入只发 warning),截断后的 JSON 文本读侧 parse 失败 = 整条链静默变缺席,而缺席在
- *  mailbox 上是有语义的(见下 encodeHopChain 注)。同 assertKeyBytes 精神:写入面 fail-loud。 */
 const HOP_CHAIN_MAX_BYTES = 60_000;
-/**
- * `hopChain` 存取(core 5.17.0 design/176)。**JSON 文本列**,不是清洗面也不是身份键面:
- *
- *  - 为什么不清洗:链元素参与 core 的 `hop_loop` **等值比对**。内容面的 lossy 清洗(pgSanitizeText 的
- *    U+FFFD 标记)会让两个不同 token 塌成同一个(误报环路)或让一个 token 变形(漏判环路)——两个
- *    方向都是把准入判决改错,与 `content` 那种「读者读到近似文本仍可用」的容忍面性质不同。
- *  - 为什么也不需要拒绝:`JSON.stringify` 是 **well-formed**(ES2019)——NUL 转义成 `\u0000`、lone
- *    surrogate 转义成 `\udXXX`,产物恒是 ASCII 可存字节。于是 PG 的 unstorable 面根本不会被触及,
- *    两方言都拿到逐字 round-trip,不必像 `from`/`scope`/`handle` 那样走拒绝式。
- *  - **缺席 ≠ 空数组**:core 明示 mailbox 的 `hopChain` 在场性本身携带语义(「经 sema 准入门录入」vs
- *    「外部/存量写入」,是整份契约里唯一允许从在场性推断的例外)。所以 NULL 读回 = 不铸键,`[]` 读回
- *    = 铸一个空数组键,两者绝不互相折叠。
- */
 function encodeHopChain(hopChain) {
     if (hopChain === undefined)
         return null;
@@ -53,8 +29,6 @@ function encodeHopChain(hopChain) {
     }
     return text;
 }
-/** 读侧:NULL/缺席 ⇒ undefined(不铸键);坏行(非 JSON / 非字符串数组)⇒ 同样 undefined —— 一条读不
- *  懂的链只能诚实降级成「没有链」,绝不半解析出一条会被拿去做环路比对的残链。 */
 function decodeHopChain(raw) {
     if (raw === null || raw === undefined)
         return undefined;
@@ -80,8 +54,6 @@ function rowToMessage(r) {
     };
 }
 export async function ensureTiDBMailboxSchema(pool) {
-    // VARBINARY 键列(bg-agent/roster 同案);lease_owner 同为字节等价(claim 的 owner 比对是身份判)。
-    // content LONGTEXT:消息正文可超 64K TEXT(转录段落/大 diff 转述)。
     await pool.query(`CREATE TABLE IF NOT EXISTS ${MAILBOX_TABLE} (
     scope_key VARBINARY(190) NOT NULL,
     handle VARBINARY(190) NOT NULL,
@@ -157,15 +129,11 @@ export class TiDBMailboxStore {
         assertIdentityChars("handle", handle);
         assertKeyBytes("scope", scope);
         assertKeyBytes("handle", handle);
-        const hopChain = encodeHopChain(msg.hopChain); // 事务外先编码:超界 fail-loud 必须在建盒/分配 seq 之前
-        // ensure-first 形:先幂等 INSERT IGNORE 建盒(next_seq=1,首条/drop 后重建同臂)再 FOR UPDATE——
-        // 「无行 FOR UPDATE + INSERT」的并发死锁/dup 撞车形整个消掉;seq 分配与 append 同事务(定谳 2)。
+        const hopChain = encodeHopChain(msg.hopChain);
         return this.tx(async (c) => {
             await c.query(`INSERT IGNORE INTO ${MAILBOX_TABLE} (scope_key, handle, scope, next_seq) VALUES (?, ?, ?, 1)`, [scope, handle, scope]);
             let [rows] = (await c.query(`SELECT next_seq FROM ${MAILBOX_TABLE} WHERE scope_key = ? AND handle = ? FOR UPDATE`, [scope, handle]));
             if (rows.length === 0) {
-                // ensure 与锁之间盒被并发 drop/reap 提交(复审 #5 窗)——同事务重建一次(语义 = drop 后重建,
-                // seq 从 1;同事务内自插行必可见,再空 = 真障碍 fail-loud)。
                 await c.query(`INSERT IGNORE INTO ${MAILBOX_TABLE} (scope_key, handle, scope, next_seq) VALUES (?, ?, ?, 1)`, [scope, handle, scope]);
                 [rows] = (await c.query(`SELECT next_seq FROM ${MAILBOX_TABLE} WHERE scope_key = ? AND handle = ? FOR UPDATE`, [scope, handle]));
             }
@@ -181,35 +149,24 @@ export class TiDBMailboxStore {
             if (boxes.length === 0)
                 return null;
             const box = boxes[0];
-            // 定谳 4:严格 expiresAt > now 才挡;定谳 1:同 owner 恒续期(字节等价比对——VARBINARY 读回 Buffer)。
-            // 残余记账(F7 TiDB 臂):owner 含 lone surrogate 时 mysql2 编码层塌缩 U+FFFD,读回串 ≠ 原参数
-            // → 同主续期被误拒(fail-closed 向,无越权);owner 是内部 mint 的 worker id(ASCII 域),接受。
             if (box.lease_owner !== null &&
                 Number(box.lease_expires_at_ms) > now &&
                 bufToStr(box.lease_owner) !== owner) {
                 return null;
             }
-            // FOR UPDATE = 当前读:TiDB 悲观事务的普通 SELECT 按 start_ts 快照(task-list twin 同案)——
-            // 锁到 box 行后消息集必须读「现在」,否则 drop+重建窗内老消息混进新盒 lease(maxSeq 错位)。
             const [msgs] = (await c.query(`SELECT seq, from_id, content, sent_at_ms, hop_chain FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? AND handle = ? ORDER BY seq FOR UPDATE`, [scope, handle]));
             if (msgs.length === 0)
-                return null; // 定谳 5:空盒 claim = null(box 行在也 null)
+                return null;
             const maxSeq = Number(msgs[msgs.length - 1].seq);
             await c.query(`UPDATE ${MAILBOX_TABLE} SET lease_owner = ?, lease_expires_at_ms = ?, lease_max_seq = ? WHERE scope_key = ? AND handle = ?`, [owner, now + ttlMs, maxSeq, scope, handle]);
             return { messages: msgs.map(rowToMessage), maxSeq };
         });
     }
     async ack(scope, handle, owner, upToSeq) {
-        // MB1/core 1.452 BREAKING:ack 带 **owner 围栏**(core InMemory 同语义:lease 缺席或 owner 不符 ⇒
-        // 整个 ack no-op,一条消息都不删——原「定谳 3 无守卫,信任 claim 赢者链」被 [1937] MB1 推翻:
-        // 任何人可删别人租约内消息)。锁序仍=盒行先(复审 F3 ABBA 死锁形);盒不存在=SELECT 空 ⇒ no-op。
         await this.tx(async (c) => {
             const [rows] = (await c.query(`SELECT lease_owner FROM ${MAILBOX_TABLE} WHERE scope_key = ? AND handle = ? FOR UPDATE`, [scope, handle]));
-            // 🔴 真双库抓的坑(2026-07-28,mock 无法抓):lease_owner 是 VARBINARY,mysql2 读回 **Buffer**——
-            // `Buffer !== string` 恒真 ⇒ 首版围栏把正主也拒了(所有 ack 恒 no-op)。bufToStr 字节等价比对,
-            // claim 的定谳 1 同坑同解(:186)。
             if (rows.length === 0 || rows[0].lease_owner == null || bufToStr(rows[0].lease_owner) !== owner)
-                return; // 围栏:非当前持租者 ⇒ no-op
+                return;
             await c.query(`DELETE FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? AND handle = ? AND seq <= ?`, [scope, handle, upToSeq]);
             await c.query(`UPDATE ${MAILBOX_TABLE} SET lease_owner = NULL, lease_expires_at_ms = NULL, lease_max_seq = NULL
          WHERE scope_key = ? AND handle = ? AND lease_max_seq IS NOT NULL AND lease_max_seq <= ?`, [scope, handle, upToSeq]);
@@ -224,8 +181,6 @@ export class TiDBMailboxStore {
         return Number(rows[0].n);
     }
     async drop(scope, handle) {
-        // 整盒删含 box 行 = seq 生命周期终结(定谳 2;重建从 1)。**盒行先删**(锁序统一 + F2:反序在
-        // 「消息已删、盒未删」窗放并发 append 穿过 → 盒重建撞孤儿消息行 PK,append 从此永败)。
         await this.tx(async (c) => {
             await c.query(`DELETE FROM ${MAILBOX_TABLE} WHERE scope_key = ? AND handle = ?`, [scope, handle]);
             await c.query(`DELETE FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? AND handle = ?`, [scope, handle]);
@@ -235,9 +190,6 @@ export class TiDBMailboxStore {
         if (opts?.maxAgeMs === undefined)
             return 0;
         const cutoff = now - opts.maxAgeMs;
-        // 全量真扫(定谳 6):事务外粗筛(索引面)+ 事务内逐盒「锁盒行 → 当前读重验 newest」(复审
-        // F2/F4:粗筛与删除之间窗内新到的消息必须救活盒,绝不连带删信;GROUP BY 不能 FOR UPDATE,
-        // 重验用 ORDER BY … LIMIT 1 当前读)。空盒不删(newest 无行);盒行已被并发 drop = 跳过。
         const [cands] = (await this.pool.query(`SELECT handle FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? GROUP BY handle HAVING MAX(sent_at_ms) < ?`, [scope, cutoff]));
         if (cands.length === 0)
             return 0;
@@ -280,7 +232,6 @@ export class PgMailboxStore {
             c.release();
         }
     }
-    /** 身份键拒绝式([1439] 协议纪律):scope/handle/owner/from 清洗形变 = 路由/attribution 错位。 */
     assertIdentity(what, v) {
         if (v !== undefined && pgHasUnstorable(v))
             throw new PgUnstorableError(`mailbox ${what}`);
@@ -290,11 +241,10 @@ export class PgMailboxStore {
         this.assertIdentity("scope", scope);
         this.assertIdentity("handle", handle);
         this.assertIdentity("from", msg.from);
-        const content = pgSanitizeText(msg.content); // 内容面 lossy(U+FFFD 标记,与 PG 转录 payload 同族)
+        const content = pgSanitizeText(msg.content);
         assertKeyBytes("scope", scope);
         assertKeyBytes("handle", handle);
-        const hopChain = encodeHopChain(msg.hopChain); // TiDB 同注:事务外先编码,超界 fail-loud 不留半个盒
-        // ensure-first 形(TiDB 同注):幂等建盒再 FOR UPDATE,死锁/dup 撞车形消。
+        const hopChain = encodeHopChain(msg.hopChain);
         return this.tx(async (c) => {
             await c.query(`INSERT INTO ${MAILBOX_TABLE} (scope_key, handle, scope, next_seq) VALUES ($1, $2, $3, 1) ON CONFLICT (scope_key, handle) DO NOTHING`, [
                 scope,
@@ -303,7 +253,6 @@ export class PgMailboxStore {
             ]);
             let { rows } = await c.query(`SELECT next_seq FROM ${MAILBOX_TABLE} WHERE scope_key = $1 AND handle = $2 FOR UPDATE`, [scope, handle]);
             if (rows.length === 0) {
-                // ensure 与锁之间盒被并发 drop/reap 提交(TiDB 同注)——同事务重建一次。
                 await c.query(`INSERT INTO ${MAILBOX_TABLE} (scope_key, handle, scope, next_seq) VALUES ($1, $2, $3, 1) ON CONFLICT (scope_key, handle) DO NOTHING`, [
                     scope,
                     handle,
@@ -318,7 +267,7 @@ export class PgMailboxStore {
         });
     }
     async claimLease(scope, handle, owner, ttlMs, now = Date.now()) {
-        this.assertIdentity("owner", owner); // 复审 F7:lease 排他键同为身份键,裸 22021/塌缩比对都不许
+        this.assertIdentity("owner", owner);
         return this.tx(async (c) => {
             const { rows: boxes } = await c.query(`SELECT lease_owner, lease_expires_at_ms FROM ${MAILBOX_TABLE} WHERE scope_key = $1 AND handle = $2 FOR UPDATE`, [scope, handle]);
             if (boxes.length === 0)
@@ -335,32 +284,27 @@ export class PgMailboxStore {
         });
     }
     async ack(scope, handle, owner, upToSeq) {
-        // MB1 owner 围栏(TiDB 孪生同注);锁序=盒行先(F3 ABBA 死锁形消)。
         await this.tx(async (c) => {
             const r = (await c.query(`SELECT lease_owner FROM ${MAILBOX_TABLE} WHERE scope_key = $1 AND handle = $2 FOR UPDATE`, [scope, handle]));
-            // PG 列是 VARCHAR COLLATE "C"(读回 string,无 TiDB 臂的 Buffer 坑),bufToStr 幂等包一层求同形。
             if (r.rows.length === 0 || r.rows[0].lease_owner == null || bufToStr(r.rows[0].lease_owner) !== owner)
-                return; // 围栏:非当前持租者 ⇒ no-op
+                return;
             await c.query(`DELETE FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = $1 AND handle = $2 AND seq <= $3`, [scope, handle, upToSeq]);
             await c.query(`UPDATE ${MAILBOX_TABLE} SET lease_owner = NULL, lease_expires_at_ms = NULL, lease_max_seq = NULL
          WHERE scope_key = $1 AND handle = $2 AND lease_max_seq IS NOT NULL AND lease_max_seq <= $3`, [scope, handle, upToSeq]);
         });
     }
     async releaseLease(scope, handle, owner) {
-        this.assertIdentity("owner", owner); // F7 同注
+        this.assertIdentity("owner", owner);
         await this.pool.query(`UPDATE ${MAILBOX_TABLE} SET lease_owner = NULL, lease_expires_at_ms = NULL, lease_max_seq = NULL
        WHERE scope_key = $1 AND handle = $2 AND lease_owner = $3`, [scope, handle, owner]);
     }
     async peekCount(scope, handle) {
-        // D4(试剂盒揪出):unstorable 身份键在**读面降级**返回 0(该键在写入面就被拒 ⇒ 盒必空),
-        // 而不是把驱动层 22021 裸抛给调用方——与 tool-result 读面「degrades instead」同精神。
         if (pgHasUnstorable(scope) || pgHasUnstorable(handle))
             return 0;
         const { rows } = await this.pool.query(`SELECT COUNT(*) AS n FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = $1 AND handle = $2`, [scope, handle]);
         return Number(rows[0].n);
     }
     async drop(scope, handle) {
-        // 盒行先删(TiDB 同注,F2 孤儿消息行窗关死)。
         await this.tx(async (c) => {
             await c.query(`DELETE FROM ${MAILBOX_TABLE} WHERE scope_key = $1 AND handle = $2`, [scope, handle]);
             await c.query(`DELETE FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = $1 AND handle = $2`, [scope, handle]);
@@ -370,7 +314,6 @@ export class PgMailboxStore {
         if (opts?.maxAgeMs === undefined)
             return 0;
         const cutoff = now - opts.maxAgeMs;
-        // 事务外粗筛 + 事务内逐盒锁定重验(TiDB 同注,F2/F4:窗内新信救活盒,不丢信)。
         const { rows: cands } = await this.pool.query(`SELECT handle FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = $1 GROUP BY handle HAVING MAX(sent_at_ms) < $2`, [scope, cutoff]);
         if (cands.length === 0)
             return 0;

package/dist/plugins/memory-embedder-fingerprint.js

@@ -1,133 +1,24 @@
-/**
- * design/234 —— embedder **指纹门**(清空重建形,clay 终裁 [3647]⑤ 方向;稿=sema-internal
- * `server/design/design-234-embedder-fingerprint-20260812.md` v1+v2)。
- *
- * ## 病灶
- *
- * 向量行落在 `agent_memory_engine_entry.embedding`,**行上没有任何「产自哪个 embedder」的记账**。既有
- * 防线只有 embedder 的维度门(长度≠`MEMORY_EMBEDDER_DIM` ⇒ 抛),它只拦「换模型且维度恰好不同」;
- * **同维度换模型**(768 家族之间、1024 家族之间迁移=最常见形)完全静默——旧空间与新空间的向量在同一
- * 列里做 cosine,检索排序变噪音,没有任何一层会说出来。
- *
- * ## 形
- *
- * 指纹 = identity 两元组 `{ model, dimensions }`,**明文**存(不 hash:诊断可读性 > 紧凑,日志要能直接
- * 念出「从 X 换到了 Y」)。**endpoint 不进指纹**——换供应商域名/代理/端口不换语义空间,进了会造成大量
- * 误清;残余成文:同名模型在不同供应商若是不同实现(自托管 finetune 撞名)指纹辨不出,operator 明知
- * 异实现时改 `MEMORY_EMBEDDER_MODEL` 名或手动清列(USAGE 有一行 SQL)。
- *
- * 存储位 = **新单行元表**(additive,零删库重建窗)。不给主表加列:主表改形=触发本仓「无 ALTER、删库
- * 重建」BREAKING 窗;行级记账在「清空重建」语义下也无增益(全量清 ⇒ 不存在混合态)。
- *
- * ## 属主边界
- *
- * `memory-engine-pg.ts` 是 core 移入件(minimal-diff move-in 纪律)⇒ 元表 DDL + 比对清空腿全在**本
- * 文件**(server 侧),移入文件零改动;表名常量本文件自有(`PG_MEMORY_ENGINE_TABLES` 不动)。
- * 列名 `meta_key`/`meta_value`:`key` 是 MySQL 保留字,将来若补 TiDB 腿零反引号坑(K2)。
- *
- * ## 六态(v2 总表)
- *
- * | 态 | 判定 | 动作 |
- * |---|---|---|
- * | A | embedder 配置缺席 | **门不装**(连 ensure 都不调),元表不动——装配点的事,不在本文件 |
- * | B | 元表有行、identity 逐键相等 | 照常,**零写** |
- * | C | 元表有行、不等 | 清列 → upsert 新 identity(`reason:"changed"`) |
- * | D | 元表无行、库内**有**非 NULL 向量 | 同 C 清(存量库无法证明同源=保守清,`reason:"unattributed"`) |
- * | E | 元表无行、零向量行 | 只写 identity,不清(`memory_embedder_identity_armed`) |
- * | F | 元表有行但 value 解析失败 | 走清空臂(`reason:"unreadable"`)——**绝不当成匹配**(边界必 schema) |
- *
- * (F 的判据是 `model`/`dimensions` 缺失或类型不对;**多出来的未知键不算坏**,见 schema 处的注。)
- *
- * ## 三条不可动的判据
- *
- * 1. **次序:先清列、后写元表**。反序若中间崩溃 = 新 identity 已记而旧向量还在 = 正是被修的病(此后
- *    每次 boot 恒判 B,残留态永不复检);正序中间崩溃 = 下次 boot 无元表行、向量已 NULL ⇒ E 态补记,
- *    幂等安全。
- * 2. **CAS 循环**(v2 C1-2):元表写后**重读**,读回≠自写 ⇒ 另一副本并发写了**不同** identity(部署
- *    配置漂移)⇒ 响亮 `memory_embedder_identity_conflict`(两值并示)+ 重跑比对,上限
- *    {@link CAS_MAX_ROUNDS} 轮,超限抛(拒启)。运行期旧副本混写非 CAS 可拦 ⇒ 归停机纪律(USAGE)。
- * 3. **门自身失败 = 抛(拒启)**。吞掉 = 元表停留旧值 = 下次 boot 再清一次,把一次性代价变成每次 boot
- *    的代价;且「门在场但没跑成」静默 = fail-open。
- *
- * ## 两条已知残余(codex 对抗复审 R1-F1/R1-F3,均判为真;处置=成文,不落码面)
- *
- * - **跨门回滚**(F1):指纹门**之前**的版本(7.14.x/7.15.x:有 embedder、无本门)照写 `embedding` 列却
- *   不认识元表 ⇒「装本版(元表=B)→ 回滚旧版跑一段(写 A 空间向量)→ 升回本版仍配 B」走完,元表与配置
- *   都说 B 而列里是 A 空间 ⇒ 此后恒判 B 态。**与滚动窗是同一族**(第二写者不维护指纹),码面根治只有
- *   行级记账列 —— 稿已列出界(触主表删库重建窗)。纪律面处置与滚动窗同:回滚前后手动清列,或删掉
- *   元表那一行让下次 boot 按 D 态保守清。USAGE 已成文。
- * - **崩溃丢审计行**(F3):「清过就必响亮」以**进程活到 emitOutcome** 为界。清列与写元表是两条各自
- *   autocommit 的语句,日志在回读之后才发 ⇒ 清完即崩 ⇒ 下次 boot 元表无行、向量已 NULL ⇒ 走 E 态报
- *   「没有向量可清」;写完元表即崩 ⇒ 下次 boot 判 B 态、**一条日志都不发**。**数据面安全**(次序钉买的
- *   正是这个:绝不残留旧空间),丢的只有那一次的 cleared 计数。刻意**不做**两阶段 pending marker ——
- *   为纯审计价值给 boot 路加一张表 + 两阶段协议,代价与收益不成比例;承诺句在 USAGE 已标出这条边界。
- *
- * 计数取法:`PgQueryResult` 刻意无 `rowCount` ⇒ 用 CTE `WITH c AS (UPDATE … RETURNING 1) SELECT
- * count(*)::int`(禁 `RETURNING id` 全表拉回)。计数**按整次调用累计**、原因锚在第一次真清的那一轮 ——
- * 「清过就必响亮」对终局判 B 的那一支同样成立(codex R2 finding 2)。
- *
- * ## 射程外(稿 §出界)
- *
- * 主动回填件(清空后不回填,行被 patch 时自然重嵌)/ 行级 embedder 记账列(结构性根治滚动窗)/
- * pgvector 接线件的列 dim 校验 / TiDB 向量面(v1 lexical only)。
- *
- * 🔴 **不回填的真代价(#234 定界车 2026-08-14 实测更正,稿 §4/§V3 说轻了一档)**:稿把代价写成「那些行
- * 长期停留 lexical 档」,读起来像**排序退化**;真码是**可达性悬崖**——`memory-engine-pg.ts` 的进程内腿
- * 对无向量行落 `jaccardDistance`,core 的该函数在**零词交集**时返回 `null`,`search` 当场 `continue`,
- * 行被**丢出结果集**;仍有向量的行则走余弦、不被这道门丢(前提是查询侧也嵌得出来——embedder 故障那一
- * 刻查询拿不到向量,整轮退词面档,零交集的行一起丢)。即清空之后、重嵌之前,那些行对改述/同义/跨
- * 语言查询**检索不到**——而那恰恰是向量档存在的理由。真库端到端实证:db-integration 套件「清空后的
- * 代价」一钉(清空前 "zulu" 命中该行,清空后同查询恒空,有字面交集的查询仍命中)。
- * ⚠️ 这条只更正**成文口径**,不改裁定:主动回填仍在射程外(clay 已否);但将来复裁该件时,输入应当是
- * 「可达性悬崖」而不是「排序退化」。
- */
 import { z } from "zod";
 import { PG_MEMORY_ENGINE_TABLES } from "./memory-engine-pg.js";
-/** 元表名(本文件自有 const —— core 移入文件的 `PG_MEMORY_ENGINE_TABLES` 零改动)。 */
 export const PG_MEMORY_ENGINE_META_TABLE = "agent_memory_engine_meta";
-/** 单行元表里 embedder 指纹那一行的键。 */
 export const EMBEDDER_IDENTITY_META_KEY = "embedder_identity";
-/** CAS 循环上限(v2 C1-2)。超限 = 并发副本带着**不同** identity 在互相覆盖 ⇒ 拒启。 */
 export const CAS_MAX_ROUNDS = 3;
-/**
- * 指纹 schema —— 读回的 `meta_value` 必须过它(手改坏值/回滚残留一律走 F 态,禁 `JSON.parse as` 裸断言)。
- *
- * ⚠️ **未知键刻意放过**(zod 对象默认 strip,不加 `.strict()`):将来某个版本若往这行里多写一个键,
- * 老副本读到它应当照常按 `model`/`dimensions` 比对,而不是判 F 态把整列清掉 —— 「新副本加了个字段」
- * 与「这行坏了」不是一回事,后者才是 F 态要抓的。载荷只有这两个键,多出来的不参与判定。
- */
 const EmbedderIdentitySchema = z.object({
     model: z.string().min(1),
     dimensions: z.number().int().positive(),
 });
-/**
- * 元表 DDL —— **只发 CREATE**(K1:混入 SELECT/UPDATE 会让 `scripts/dump-schema.ts` 的录制门当场抛)。
- * 幂等,与其余 `ensurePg*Schema` 同姿势;新腿已注册 `PG_LEGS` + `docs/schema/baseline-pg.sql`。
- */
 export async function ensurePgMemoryEmbedderMetaSchema(query) {
     await query(`CREATE TABLE IF NOT EXISTS ${PG_MEMORY_ENGINE_META_TABLE} (
     meta_key varchar(190) COLLATE "C" PRIMARY KEY,
     meta_value jsonb NOT NULL
   )`);
 }
-/**
- * 元表值 → 三态。入参是 `meta_value::text`(**JSON 文本**),**只解析一次**。
- *
- * 🔴 为什么读 `::text` 而不是读列本身(codex 对抗复审 R2 finding 1,验真为真):node-pg 已经替我们
- * 解析过 jsonb,所以列里躺着一个 JSON **字符串**时,交到手上的就是一个 JS string —— 上一版对 string
- * 再 `JSON.parse` 一次「宽容一格」,于是**双重编码**的坏值(`'"{\"model\":…}"'::jsonb`)会被解回合法
- * 对象、判成「相等」,来源不明的旧向量原地存活 = 本模块要消灭的静默混空间换了个入口。读 `::text` 让
- * 「对象」与「驱动序列化出的字符串」不再有歧义:解析一次之后**必须是普通对象**,真正的 JSON 字符串
- * (以及数组/数字/null)一律落 F 态。顺带也不再依赖任何驱动的 jsonb 解析姿势。
- */
 function parseStoredText(text) {
     let candidate;
     try {
         candidate = JSON.parse(text);
     }
     catch (err) {
-        // 解析错**当数据交出去**(不静默折成一句「读不出来」):这段文字会随 `reason:"unreadable"` 进
-        // 那条响亮日志,排障时「元表里躺的到底是什么」是第一个要问的。
         return { kind: "unreadable", raw: `${text.slice(0, 160)} [JSON.parse: ${String(err).slice(0, 80)}]` };
     }
     if (typeof candidate !== "object" || candidate === null || Array.isArray(candidate)) {
@@ -144,27 +35,19 @@ async function readStored(query) {
     if (row === undefined)
         return { kind: "absent" };
     const text = row.meta_value_text;
-    // 列是 NOT NULL 且 `::text` 恒给文本 —— 拿不到文本 = 这条读腿被换过(池包装/驱动改形),响亮落 F,
-    // 不猜。
     if (typeof text !== "string")
         return { kind: "unreadable", raw: `[meta_value::text did not return text: ${typeof text}]` };
     return parseStoredText(text);
 }
-/** D/E 的判据:库里还有没有**没主**的向量(元表无行 ⇒ 存量向量无从证明同源)。`LIMIT 1` —— 只问存在性,不拉全表。 */
 async function hasUnattributedVectors(query) {
     const r = await query(`SELECT 1 FROM ${PG_MEMORY_ENGINE_TABLES.entry} WHERE embedding IS NOT NULL LIMIT 1`);
     return r.rows.length > 0;
 }
-/**
- * 清列 + 计数。`PgQueryResult` 无 `rowCount` ⇒ CTE 把受影响行数在 SQL 侧数完再回一行
- * (`RETURNING id` 会把全表主键拉回进程,量级白烧)。
- */
 async function clearEmbeddings(query) {
     const r = await query(`WITH c AS (UPDATE ${PG_MEMORY_ENGINE_TABLES.entry} SET embedding = NULL WHERE embedding IS NOT NULL RETURNING 1)
      SELECT count(*)::int AS n FROM c`);
     return Number(r.rows[0]?.n ?? 0);
 }
-/** 三臂统一 upsert(C2:并发首启两副本同时 INSERT 不撞 PK)。 */
 async function writeIdentity(query, identity) {
     await query(`INSERT INTO ${PG_MEMORY_ENGINE_META_TABLE} (meta_key, meta_value) VALUES ($1, $2::jsonb)
      ON CONFLICT (meta_key) DO UPDATE SET meta_value = EXCLUDED.meta_value`, [EMBEDDER_IDENTITY_META_KEY, JSON.stringify(identity)]);
@@ -172,33 +55,14 @@ async function writeIdentity(query, identity) {
 function sameIdentity(a, b) {
     return a.model === b.model && a.dimensions === b.dimensions;
 }
-/** 换模型这件事的运维纪律(日志与 USAGE 同句;滚动窗混写是纪律面残余,门管 boot 面)。 */
 const SCALE_ZERO_NOTE = "change the embedder identity with the fleet stopped (scale to 0, then start): during a ROLLING window the old replicas keep writing vectors in the OLD space after this gate cleared the column";
-/**
- * 指纹比对腿 —— boot 一次(env 族是 boot 快照,运行中不热换)。**门自身失败一律抛**(拒启)。
- *
- * ⚠️ 调用姿势:`ensurePgMemoryEmbedderMetaSchema` 之后、memory backend 构造之前;embedder 配置**在场**
- * 才调(A 态连 ensure 都不调)。
- */
 export async function reconcileEmbedderFingerprint(query, identity, opts = {}) {
     const { log } = opts;
     const now = opts.now ?? Date.now;
-    // 自家入参也过 schema:装配点喂的是 config 解析结果(已校验),但这条腿也被脚本/测试直调,
-    // 坏 identity 写进元表 = 下次 boot 恒判 F 态清全库。
     const want = EmbedderIdentitySchema.parse(identity);
     const firstStartedAt = now();
-    // 🔴 跨轮累计(codex 对抗复审 R2 finding 2,验真为真):清空计数/原因/旧值**每轮重置**时,
-    // 「round1 清了 N 行、回读撞冲突、round2 只能再清到 0」会把一次整列缓存失效报成 `cleared=0`;更坏的
-    // 一支是 round2 恰好读回我方 identity ⇒ 从 match 臂直接返回、**一条日志都不发**,破坏性动作在运维
-    // 记录里彻底消失(与「任何清空动作必响亮」直接冲突)。所以计数按**整次调用**累计,原因/旧值锚在
-    // **第一次真清**的那一轮,并且只要清过就必发 `memory_embedder_identity_changed` —— 终局是 match
-    // 也不例外。
     let clearedTotal = 0;
     let firstClear;
-    // 🔴 **变更**本身也要跨轮记账,不能只记「清过行」(合并码重扫 codex 复审第二轮,验真为真):零向量库
-    // 的 C/D/F 轮 `cleared` 恒 0 ⇒ 它进不了 `firstClear`;若那一轮的回读又撞上并发冲突、下一轮才收敛到
-    // match,终局臂只看得见 `clearedTotal===0` 与 `terminalState==="match"`,于是一次**真发生过的** identity
-    // 变更(元表已被我方改写)在日志里彻底消失 —— 与「清过必响亮」同族的漏报,只是漏的是零清空那一支。
     let firstChange;
     const emitOutcome = (terminalState, rounds) => {
         const elapsedMs = now() - firstStartedAt;
@@ -207,30 +71,19 @@ export async function reconcileEmbedderFingerprint(query, identity, opts = {}) {
                 previous: firstClear?.previous ?? firstChange?.previous ?? null,
                 next: want,
                 cleared: clearedTotal,
-                reason: firstClear?.reason ?? firstChange?.reason ?? terminalState, // "changed" | "unattributed" | "unreadable"
+                reason: firstClear?.reason ?? firstChange?.reason ?? terminalState,
                 rounds,
                 elapsedMs,
-                // 🔴 代价按真码说(#234 定界车实测,真库端到端钉在 db-integration 的「清空后的代价」):
-                // 「退回 lexical」是**说轻了**——词面档对与查询**零词交集**的行返回「无定义」,检索当场把该行
-                // 跳过,于是清空之后、重嵌之前,那些行对改述/同义/跨语言查询是**不可达**的(带向量的行则恒有
-                // 余弦读数、永不被丢)。operator 看见这条日志的那一刻就该知道丢的是可达性,不是名次。
                 note: `${SCALE_ZERO_NOTE}; cleared vectors are NOT backfilled — rows re-embed only as they are next written, and until then each cleared row is reachable ONLY by a query sharing a literal term with it (the lexical floor drops a row with zero term overlap, whereas a row that still has a vector is scored by cosine as long as the query embeds too) — rewrite the corpus to restore vector reach immediately`,
             });
             return;
         }
-        // 🔴 **identity 真换了但没有向量可清,同样响亮**(合并码重扫,验真后修)。旧判据只有「清过行」与
-        // 「armed」两支,于是 C 态(不等)/ D 态 / F 态(元表行读不出来)碰上 `embedding` 列恰好全 NULL 时,
-        // 元表被静默改写、一条日志都不发 —— 可达形:上一次 boot 已清空过、期间无新语料;或回滚残留的坏元表
-        // 行 + 空向量列(恰恰是最该留痕的一形)。USAGE.md 把三个 reason 并列写进同一句承诺里,没有对
-        // 「清了 0 行」开例外 ⇒ 换 embedder 这件事在启动日志里不许无痕。`match` 仍是零写零响亮(B 态)。
-        // 判据是**本次调用里有没有真发生过 identity 变更**(`firstChange`),不是本轮的 `terminalState` ——
-        // 后者在「首轮 changed(零清空)→ CAS 冲突 → 次轮 match」这条路上会把变更说成没发生过。
         if (firstChange !== undefined) {
             log?.info("memory_embedder_identity_changed", {
                 previous: firstChange.previous,
                 next: want,
                 cleared: 0,
-                reason: firstChange.reason, // "changed" | "unattributed" | "unreadable"
+                reason: firstChange.reason,
                 rounds,
                 elapsedMs,
                 note: `${SCALE_ZERO_NOTE}; no vectors existed to clear on this boot — the identity itself changed, which is the event`,
@@ -245,38 +98,26 @@ export async function reconcileEmbedderFingerprint(query, identity, opts = {}) {
                 elapsedMs,
             });
         }
-        // B(且从未清过)= 零写零响亮:换模型才是事件。
     };
     for (let round = 1; round <= CAS_MAX_ROUNDS; round++) {
         const stored = await readStored(query);
-        // ── 判定 ────────────────────────────────────────────────────────────────────────────────────
         let state;
         let previous = null;
         if (stored.kind === "ok") {
             previous = stored.value;
             if (sameIdentity(stored.value, want)) {
-                // B:零写(连 upsert 都不发 —— 「匹配」这条路径上不许有任何写)。但前序轮若已经清过,
-                // 那次清必须照样被记上、被说出来。
                 emitOutcome("match", round);
                 return { state: "match", cleared: clearedTotal, previous, identity: want, rounds: round };
             }
-            state = "changed"; // C
+            state = "changed";
         }
         else if (stored.kind === "unreadable") {
-            state = "unreadable"; // F —— 绝不当成匹配
+            state = "unreadable";
         }
         else {
-            state = (await hasUnattributedVectors(query)) ? "unattributed" : "armed"; // D / E
+            state = (await hasUnattributedVectors(query)) ? "unattributed" : "armed";
         }
-        // ── 动作:🔴 先清列、后写元表(次序即正确性,见头注 1)────────────────────────────────────
         if (state !== "armed" && firstChange === undefined) {
-            // 变更的锚:第一次判出「不是 match、不是 armed」的那一轮(与清了几行无关)。
-            // ⚠️ 如实登记的残余(codex 复审第三轮提出,判为**过报**而非误报,故不改 SQL 语义):两只**同配置**
-            // 副本同时首启时,两边都可能先读到旧值 ⇒ 各自 clear+upsert(赢家清到行,输家清 0)⇒ 两边各发一条
-            // `memory_embedder_identity_changed`(同一次逻辑变更在两个进程的日志里各留一条)。方向是安全的那
-            // 一侧:多一条过报 < 漏一条(本键的全部理由是「换 embedder 不许无痕」),且两条都如实描述了各自
-            // 观察到的世界(旧值 → 新值)。根治要把 upsert 换成「只在值真变时才写并回带是否变过」的条件形 ——
-            // 那是元表写腿的 SQL 语义变更(双库门),不在本收口批射程,登记为后续件。
             firstChange = { reason: state, previous: previous ?? (stored.kind === "unreadable" ? { unreadable: stored.raw } : null) };
         }
         const cleared = state === "armed" ? 0 : await clearEmbeddings(query);
@@ -285,13 +126,11 @@ export async function reconcileEmbedderFingerprint(query, identity, opts = {}) {
         }
         clearedTotal += cleared;
         await writeIdentity(query, want);
-        // ── CAS 回读(见头注 2)────────────────────────────────────────────────────────────────────
         const after = await readStored(query);
         if (after.kind === "ok" && sameIdentity(after.value, want)) {
             emitOutcome(state, round);
             return { state, cleared: clearedTotal, previous, identity: want, rounds: round };
         }
-        // 读回≠自写 ⇒ 另一副本并发写了**不同** identity(部署配置漂移)。响亮 + 重跑比对。
         log?.error("memory_embedder_identity_conflict", {
             ours: want,
             theirs: after.kind === "ok" ? after.value : after.kind === "unreadable" ? { unreadable: after.raw } : null,