@sema-agent/server 7.146.0 → 7.147.0

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

@@ -1,16 +1,21 @@
 import { promises as fsp } from "node:fs";
 import { join } from "node:path";
+import { ensureDir } from "@sema-agent/core";
 import { bindRowsInProcess, TaskAttachmentRecordSchema } from "./task-attachment-store.js";
 import { createZodColumnReader, decodeJsonColumn } from "./sql-json-column.js";
+import { atomicWriteFileAsync } from "./owner-only-file-mode.js";
 const ID_RE = /^[0-9a-f-]{16,64}$/i;
 const readAttachmentMeta = createZodColumnReader(TaskAttachmentRecordSchema);
+export function attachmentStoreDirFor(rootDir) {
+    return join(rootDir, "attachments");
+}
 export class LocalTaskAttachmentStore {
     dir;
     metas;
     hydration;
     mutationTail = Promise.resolve();
     constructor(rootDir) {
-        this.dir = join(rootDir, "attachments");
+        this.dir = attachmentStoreDirFor(rootDir);
     }
     hydrate() {
         this.hydration ??= (async () => {
@@ -46,14 +51,10 @@ export class LocalTaskAttachmentStore {
     put(rec) {
         return this.serialized(async () => {
             const metas = await this.hydrate();
-            await fsp.mkdir(this.dir, { recursive: true });
+            ensureDir(this.dir);
             const { content, ...meta } = rec;
-            const binTmp = join(this.dir, `${rec.id}.bin.tmp`);
-            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`));
-            await fsp.writeFile(metaTmp, JSON.stringify(meta));
-            await fsp.rename(metaTmp, join(this.dir, `${rec.id}.json`));
+            await atomicWriteFileAsync(join(this.dir, `${rec.id}.bin`), Buffer.from(content), { durability: "best-effort" });
+            await atomicWriteFileAsync(join(this.dir, `${rec.id}.json`), JSON.stringify(meta), { durability: "best-effort" });
             metas.set(rec.id, { ...meta });
         });
     }
@@ -73,9 +74,7 @@ export class LocalTaskAttachmentStore {
         }
     }
     async persistMeta(m) {
-        const tmp = join(this.dir, `${m.id}.json.tmp`);
-        await fsp.writeFile(tmp, JSON.stringify(m));
-        await fsp.rename(tmp, join(this.dir, `${m.id}.json`));
+        await atomicWriteFileAsync(join(this.dir, `${m.id}.json`), JSON.stringify(m), { durability: "best-effort" });
     }
     bind(owner, ids, sessionId, boundAtMs) {
         return this.serialized(async () => {

package/dist/plugins/memory-embedder-fingerprint.d.ts

@@ -25,29 +25,37 @@
  * 文件**(server 侧),移入文件零改动;表名常量本文件自有(`PG_MEMORY_ENGINE_TABLES` 不动)。
  * 列名 `meta_key`/`meta_value`:`key` 是 MySQL 保留字,将来若补 TiDB 腿零反引号坑(K2)。
  *
- * ## 六态(v2 总表)
+ * ## 六态(v2 总表)与处置律
  *
  * | 态 | 判定 | 动作 |
  * |---|---|---|
  * | A | embedder 配置缺席 | **门不装**(连 ensure 都不调),元表不动——装配点的事,不在本文件 |
  * | B | 元表有行、identity 逐键相等 | 照常,**零写** |
- * | C | 元表有行、不等 | 清列 → upsert 新 identity(`reason:"changed"`) |
- * | D | 元表无行、库内**有**非 NULL 向量 | 同 C 清(存量库无法证明同源=保守清,`reason:"unattributed"`) |
+ * | C | 元表有行、不等(`changed`) | 对不上 |
+ * | D | 元表无行、库内**有**非 NULL 向量(`unattributed`:存量无法证明同源) | 对不上 |
  * | E | 元表无行、零向量行 | 只写 identity,不清(`memory_embedder_identity_armed`) |
- * | F | 元表有行但 value 解析失败 | 走清空臂(`reason:"unreadable"`)——**绝不当成匹配**(边界必 schema) |
+ * | F | 元表有行但 value 解析失败(`unreadable`)——**绝不当成匹配**(边界必 schema) | 对不上 |
  *
  * (F 的判据是 `model`/`dimensions` 缺失或类型不对;**多出来的未知键不算坏**,见 schema 处的注。)
  *
+ * **处置律(一句)**:门从不凭自己的判断清列。「对不上」(C / D / F)⇒ **拒启**,拒句点名所处的态、记下的与配置的身份、
+ * 出路;唯一会清列的路径是运维**显式确认**这一次重嵌 —— `opts.reembedConfirmed`(装配点读 config 的
+ * `memoryEmbedder.reembedConfirmed`,即 env `MEMORY_EMBEDDER_REEMBED=<model>/<dimensions>`,config 层已判过它恰好点名本次配置的
+ * 身份)⇒ 清列 → upsert 新 identity,`memory_embedder_identity_changed` 照旧响亮。理由:清列不可逆(行只在下次被写时才重嵌),
+ * 拒启可逆(改回配置 / 确认 / 撤掉 embedder 走词面档,向量原样不动)。确认口令绑定身份 ⇒ 记下这个身份之后它判 B、不再有东西可确认。
+ *
  * ## 三条不可动的判据
  *
  * 1. **次序:先清列、后写元表**。反序若中间崩溃 = 新 identity 已记而旧向量还在 = 正是被修的病(此后
  *    每次 boot 恒判 B,残留态永不复检);正序中间崩溃 = 下次 boot 无元表行、向量已 NULL ⇒ E 态补记,
  *    幂等安全。
- * 2. **CAS 循环**(v2 C1-2):元表写后**重读**,读回≠自写 ⇒ 另一副本并发写了**不同** identity(部署
- *    配置漂移)⇒ 响亮 `memory_embedder_identity_conflict`(两值并示)+ 重跑比对,上限
- *    {@link CAS_MAX_ROUNDS} 轮,超限抛(拒启)。运行期旧副本混写非 CAS 可拦 ⇒ 归停机纪律(USAGE)。
+ * 2. **CAS 循环**(v2 C1-2):元表的写是**条件写** —— 只落在本轮判出的那一份上(判时没有行 ⇒ 只插入;判时有行 ⇒ 只在值仍是
+ *    读到的那段文本时改写),写后**重读**,读回≠自写 ⇒ 另一副本在判与写之间写了**不同** identity(部署配置漂移)⇒ 响亮
+ *    `memory_embedder_identity_conflict`(两值并示)+ 重跑比对(下一轮按别人的值判:未确认 ⇒ 拒启),上限 {@link CAS_MAX_ROUNDS} 轮,
+ *    超限抛(拒启)。条件写让「判与写之间被别人抢先」恒被读回看见 —— 盲 upsert 会把别人刚写下的身份(连同其后写进列里的另一空间向量)
+ *    静默盖成自己的。运行期旧副本混写非 CAS 可拦 ⇒ 归停机纪律(USAGE)。
  * 3. **门自身失败 = 抛(拒启)**。吞掉 = 元表停留旧值 = 下次 boot 再清一次,把一次性代价变成每次 boot
- *    的代价;且「门在场但没跑成」静默 = fail-open。
+ *    的代价;且「门在场但没跑成」静默 = fail-open。「对不上而未确认」同样是抛(处置律),先于任何写。
  *
  * ## 两条已知残余(codex 交叉复审 R1-F1/R1-F3,均判为真;处置=成文,不落码面)
  *
@@ -118,8 +126,13 @@ export interface EmbedderFingerprintReport {
     /** 收敛用了几轮(1 = 一次过;>1 = 中途撞到并发不同 identity)。 */
     rounds: number;
 }
-/** 比对腿的部署腿注入(日志 + 时钟)。日志缺席 = 纯静默跑(测试/脚本形),装配点必传。 */
+/** 比对腿的部署腿注入(日志 + 时钟 + 确认位)。日志缺席 = 纯静默跑(测试/脚本形),装配点必传。 */
 export interface ReconcileEmbedderFingerprintOptions {
+    /**
+     * 运维已确认「对不上时清掉向量列、按 `identity` 重嵌」(装配点 = config `memoryEmbedder.reembedConfirmed`)。
+     * 缺席 / `false` ⇒ 对不上(changed / unattributed / unreadable)一律拒启,一行不清、元表不写。
+     */
+    reembedConfirmed?: boolean;
     /** boot logger(`info` 报换模型/首装,`error` 报并发 identity 冲突)。 */
     log?: Pick<Logger, "info" | "error">;
     /** 耗时读数的时钟(默认 `Date.now`)——**整次调用**的耗时进日志(含 CAS 重试轮),
@@ -131,8 +144,18 @@ export interface ReconcileEmbedderFingerprintOptions {
  * 幂等,与其余 `ensurePg*Schema` 同姿势;新腿已注册 `PG_LEGS` + `docs/schema/baseline-pg.sql`。
  */
 export declare function ensurePgMemoryEmbedderMetaSchema(query: PgQueryFn): Promise<void>;
+/** 「对不上」的三态(处置律:未确认 ⇒ 拒启)。 */
+type MismatchState = Extract<EmbedderFingerprintState, "changed" | "unattributed" | "unreadable">;
+/**
+ * 「对不上而未确认」的拒句(纯数据:一条字符串)。点名所处的态 + 三态的闭集、记下的与配置的身份、出路(确认口令逐字可抄)。
+ * 每一态的「记下了什么」各一句;出路对三态同一张表,只有 changed 多一条「改回记下的身份」。
+ */
+export declare function buildEmbedderIdentityRefusal(state: MismatchState, recorded: EmbedderIdentity | {
+    unreadable: string;
+} | null, want: EmbedderIdentity): string;
 /**
- * 指纹比对腿 —— boot 一次(env 族是 boot 快照,运行中不热换)。**门自身失败一律抛**(拒启)。
+ * 指纹比对腿 —— boot 一次(env 族是 boot 快照,运行中不热换)。**门自身失败一律抛**(拒启);「对不上」而 `opts.reembedConfirmed`
+ * 不为真 ⇒ 抛 {@link buildEmbedderIdentityRefusal} 的拒句(处置律,先于任何写)。
  *
  * ⚠️ 调用姿势:`ensurePgMemoryEmbedderMetaSchema` 之后、memory backend 构造之前;embedder 配置**在场**
  * 才调(A 态连 ensure 都不调)。

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

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { PG_MEMORY_ENGINE_TABLES } from "./memory-engine-pg.js";
 import { createZodColumnReader, decodeJsonColumn, jsonColumnText, SqlJsonColumnError } from "./sql-json-column.js";
 import { echoCallerText } from "../caller-text-echo.js";
+import { MEMORY_EMBEDDER_REEMBED_ENV, formatEmbedderIdentityToken, formatReembedAssignment } from "../memory-embedder-reembed.js";
 export const PG_MEMORY_ENGINE_META_TABLE = "agent_memory_engine_meta";
 export const EMBEDDER_IDENTITY_META_KEY = "embedder_identity";
 export const CAS_MAX_ROUNDS = 3;
@@ -18,12 +19,12 @@ export async function ensurePgMemoryEmbedderMetaSchema(query) {
 const readEmbedderIdentityColumn = createZodColumnReader(EmbedderIdentitySchema);
 function parseStoredText(text) {
     try {
-        return { kind: "ok", value: decodeJsonColumn(text, readEmbedderIdentityColumn, `${PG_MEMORY_ENGINE_META_TABLE}.meta_value for key ${EMBEDDER_IDENTITY_META_KEY}`) };
+        return { kind: "ok", value: decodeJsonColumn(text, readEmbedderIdentityColumn, `${PG_MEMORY_ENGINE_META_TABLE}.meta_value for key ${EMBEDDER_IDENTITY_META_KEY}`), text };
     }
     catch (err) {
         if (!(err instanceof SqlJsonColumnError))
             throw err;
-        return { kind: "unreadable", raw: `${echoCallerText(text, { maxChars: 160 })} [${err.problem}: ${echoCallerText(err.message, { maxChars: 120 })}]` };
+        return { kind: "unreadable", raw: `${echoCallerText(text, { maxChars: 160 })} [${err.problem}: ${echoCallerText(err.message, { maxChars: 120 })}]`, text };
     }
 }
 async function readStored(query) {
@@ -32,8 +33,9 @@ async function readStored(query) {
     if (row === undefined)
         return { kind: "absent" };
     const text = row.meta_value;
-    if (typeof text !== "string")
-        return { kind: "unreadable", raw: `[meta_value::text did not return text: ${typeof text}]` };
+    if (typeof text !== "string") {
+        throw new Error(`reconcileEmbedderFingerprint: ${PG_MEMORY_ENGINE_META_TABLE}.meta_value::text did not return text (${typeof text}) — the read leg is broken; refusing to start`);
+    }
     return parseStoredText(text);
 }
 async function hasUnattributedVectors(query) {
@@ -45,16 +47,51 @@ async function clearEmbeddings(query) {
      SELECT count(*)::int AS n FROM c`);
     return Number(r.rows[0]?.n ?? 0);
 }
-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)]);
+async function writeIdentity(query, identity, judged) {
+    if (judged.kind === "absent") {
+        await query(`INSERT INTO ${PG_MEMORY_ENGINE_META_TABLE} (meta_key, meta_value) VALUES ($1, $2::jsonb)
+     ON CONFLICT (meta_key) DO NOTHING`, [EMBEDDER_IDENTITY_META_KEY, JSON.stringify(identity)]);
+        return;
+    }
+    await query(`UPDATE ${PG_MEMORY_ENGINE_META_TABLE} SET meta_value = $2::jsonb WHERE meta_key = $1 AND meta_value::text = $3`, [
+        EMBEDDER_IDENTITY_META_KEY,
+        JSON.stringify(identity),
+        judged.text,
+    ]);
 }
 function sameIdentity(a, b) {
     return a.model === b.model && a.dimensions === b.dimensions;
 }
 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";
+export function buildEmbedderIdentityRefusal(state, recorded, want) {
+    const configured = formatEmbedderIdentityToken(want);
+    let what;
+    switch (state) {
+        case "changed":
+            what = `${PG_MEMORY_ENGINE_META_TABLE} records the embedder identity ${recorded !== null && "model" in recorded ? formatEmbedderIdentityToken(recorded) : "(none)"} but the configured embedder is ${configured}`;
+            break;
+        case "unattributed":
+            what = `${PG_MEMORY_ENGINE_META_TABLE} records no embedder identity while ${PG_MEMORY_ENGINE_TABLES.entry}.embedding holds vectors — their origin cannot be proven to be the configured embedder ${configured}`;
+            break;
+        case "unreadable":
+            what = `the embedder identity recorded in ${PG_MEMORY_ENGINE_META_TABLE} cannot be read (${recorded !== null && "unreadable" in recorded ? recorded.unreadable : "unreadable"}), so the vectors cannot be proven to come from the configured embedder ${configured}`;
+            break;
+        default: {
+            const unknown = state;
+            throw new Error(`unknown embedder mismatch state ${JSON.stringify(unknown)}`);
+        }
+    }
+    return (`memory embedder identity mismatch (state: ${state}) — refusing to start: ${what}. ` +
+        `The gate refuses on each of three states (changed: the recorded identity differs; unattributed: no recorded identity while vectors exist; unreadable: the recorded identity cannot be read) ` +
+        `and never clears the vector column on its own — clearing is irreversible (rows re-embed only when next written), refusing is not. Ways out: ` +
+        (state === "changed" ? "configure the recorded identity again (MEMORY_EMBEDDER_MODEL / MEMORY_EMBEDDER_DIM); or " : "") +
+        `confirm the re-embed — set ${formatReembedAssignment(want)} and restart with the fleet stopped (scale to 0): the column is cleared once and ${configured} recorded, after which the confirmation is inert; ` +
+        "or unset MEMORY_EMBEDDER_* to start on the lexical floor with the stored vectors left untouched.");
+}
+const CONFIRMED_NOTE = `re-embed confirmed by ${MEMORY_EMBEDDER_REEMBED_ENV} (inert from now on: this identity is recorded, so the next boot matches)`;
 export async function reconcileEmbedderFingerprint(query, identity, opts = {}) {
     const { log } = opts;
+    const confirmed = opts.reembedConfirmed === true;
     const now = opts.now ?? Date.now;
     const want = EmbedderIdentitySchema.parse(identity);
     const firstStartedAt = now();
@@ -71,7 +108,7 @@ export async function reconcileEmbedderFingerprint(query, identity, opts = {}) {
                 reason: firstClear?.reason ?? firstChange?.reason ?? terminalState,
                 rounds,
                 elapsedMs,
-                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`,
+                note: `${CONFIRMED_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;
         }
@@ -83,7 +120,7 @@ export async function reconcileEmbedderFingerprint(query, identity, opts = {}) {
                 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`,
+                note: `${CONFIRMED_NOTE}; ${SCALE_ZERO_NOTE}; no vectors existed to clear on this boot — the identity itself changed, which is the event`,
             });
             return;
         }
@@ -114,15 +151,18 @@ export async function reconcileEmbedderFingerprint(query, identity, opts = {}) {
         else {
             state = (await hasUnattributedVectors(query)) ? "unattributed" : "armed";
         }
+        const recorded = previous ?? (stored.kind === "unreadable" ? { unreadable: stored.raw } : null);
+        if (state !== "armed" && !confirmed)
+            throw new Error(buildEmbedderIdentityRefusal(state, recorded, want));
         if (state !== "armed" && firstChange === undefined) {
-            firstChange = { reason: state, previous: previous ?? (stored.kind === "unreadable" ? { unreadable: stored.raw } : null) };
+            firstChange = { reason: state, previous: recorded };
         }
         const cleared = state === "armed" ? 0 : await clearEmbeddings(query);
         if (cleared > 0 && firstClear === undefined) {
-            firstClear = { reason: state, previous: previous ?? (stored.kind === "unreadable" ? { unreadable: stored.raw } : null) };
+            firstClear = { reason: state, previous: recorded };
         }
         clearedTotal += cleared;
-        await writeIdentity(query, want);
+        await writeIdentity(query, want, stored);
         const after = await readStored(query);
         if (after.kind === "ok" && sameIdentity(after.value, want)) {
             emitOutcome(state, round);

package/dist/plugins/memory-embedder.d.ts

@@ -1,7 +1,7 @@
 import type { MemoryEmbedderConfig } from "../config-types.js";
 import type { PgEmbedder } from "./pg-query.js";
 /** 工厂入参 = 配置坐标(单一属主 `config-types.ts`)+ 部署腿(观测/注入)。 */
-export interface OpenAiCompatEmbedderOptions extends MemoryEmbedderConfig {
+export interface OpenAiCompatEmbedderOptions extends Omit<MemoryEmbedderConfig, "reembedConfirmed"> {
     /** 注入 fetch(测试/代理场景);缺省全局 `fetch`。 */
     fetchImpl?: typeof fetch;
     /**

package/dist/plugins/memory-embedder.js

@@ -94,9 +94,9 @@ export function createOpenAiCompatEmbedder(opts) {
     };
 }
 export function memoryEmbedderFor(config, deps = {}) {
-    const cfg = config.memoryEmbedder;
-    if (cfg === undefined)
+    if (config.memoryEmbedder === undefined)
         return undefined;
+    const { reembedConfirmed: _confirmation, ...cfg } = config.memoryEmbedder;
     return createOpenAiCompatEmbedder({
         ...cfg,
         ...(deps.fetchImpl !== undefined ? { fetchImpl: deps.fetchImpl } : {}),

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

@@ -86,9 +86,10 @@ export declare class PgMemoryEngineBackend implements MemoryBackend {
     /** 写不落之后的现读:这个 id 的行此刻的 rev 与投影(没了 ⇒ undefined)。 */
     private freshRow;
     /**
-     * add:`INSERT … ON CONFLICT (id)`,冲突靶 = 仅主键。计划时这个 id 已有行 ⇒ `DO UPDATE … WHERE` 行仍在计划的投影上(同 scope re-add 的幂等
-     * 覆盖;行被挪走就不覆盖 —— 被挪去的那个拼写没问过);计划时没有 ⇒ `DO NOTHING`(同 id 的行在判与写之间被别的副本插入就不覆盖)。
-     * 两种「不覆盖」都让 `RETURNING` 交零行 ⇒ 现读确认后答 `moved`(驱动器按现状重判)。剩下能撞的唯一键只有 `(scope, slug)` ⇒ `slug-taken`。
+     * add:`INSERT … ON CONFLICT (id)`,冲突靶 = 仅主键。计划时这个 id 已有行 ⇒ `DO UPDATE … WHERE` 行仍在计划的投影上(同 scope re-add 的
+     * 幂等覆盖;行被挪走就不覆盖 —— 被挪去的那个拼写没问过),add-if-absent 再绑计划读到的 rev(行被改写就不覆盖 —— 它判的是那一份内容);
+     * 计划时没有 ⇒ `DO NOTHING`(同 id 的行在判与写之间被别的副本插入就不覆盖)。两种「不覆盖」都让 `RETURNING` 交零行 ⇒ 现读确认后答
+     * `moved`(驱动器按现状重判)。剩下能撞的唯一键只有 `(scope, slug)` ⇒ `slug-taken`。
      */
     private writeAdd;
     /** update:条件 = 判过的 rev **且**判过的投影(rev 是内容哈希、不含 scope / slug)。零行 ⇒ 现读:内容未变而投影变了 = `moved`;其余 =

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

@@ -222,10 +222,10 @@ export class PgMemoryEngineBackend {
         const T = PG_MEMORY_ENGINE_TABLES.entry;
         const params = [stored.id, stored.scope, stored.slug, pgSafeJsonStringify(stored.frontmatter), stored.body, rev, this.clock(), Buffer.byteLength(serializeEntryFile(stored), "utf8"), embedding];
         const onConflict = prior !== undefined
-            ? `ON CONFLICT (id) DO UPDATE SET scope = $2, slug = $3, frontmatter = $4, body = $5, rev = $6, mtime_ms = $7, size_bytes = $8, embedding = $9 WHERE ${T}.scope = $10 AND ${T}.slug = $11`
+            ? `ON CONFLICT (id) DO UPDATE SET scope = $2, slug = $3, frontmatter = $4, body = $5, rev = $6, mtime_ms = $7, size_bytes = $8, embedding = $9 WHERE ${T}.scope = $10 AND ${T}.slug = $11${prior.rev !== undefined ? ` AND ${T}.rev = $12` : ""}`
             : "ON CONFLICT (id) DO NOTHING";
         if (prior !== undefined)
-            params.push(prior.scope, prior.slug);
+            params.push(prior.scope, prior.slug, ...(prior.rev !== undefined ? [prior.rev] : []));
         confirm();
         let landed;
         try {
@@ -243,9 +243,9 @@ export class PgMemoryEngineBackend {
         if (landed)
             return { kind: "committed" };
         const fresh = await this.freshRow(stored.id);
-        if (fresh !== undefined && (prior === undefined || fresh.scope !== prior.scope || fresh.slug !== prior.slug))
+        if (fresh !== undefined && (prior === undefined || fresh.scope !== prior.scope || fresh.slug !== prior.slug || (prior.rev !== undefined && fresh.rev !== prior.rev)))
             return { kind: "moved" };
-        throw new Error(`memory-engine: the add of ${JSON.stringify(stored.id)} wrote no row, yet the row is ${fresh === undefined ? "absent" : "still at the planned projection"} — refusing to report it either way`);
+        throw new Error(`memory-engine: the add of ${JSON.stringify(stored.id)} wrote no row, yet the row is ${fresh === undefined ? "absent" : "still where the write condition holds"} — refusing to report it either way`);
     }
     async writeUpdate({ entry, rev, currentRev, current, baseRev }, embedding, confirm) {
         const params = [entry.id, entry.scope, entry.slug, pgSafeJsonStringify(entry.frontmatter), entry.body, rev, this.clock(), Buffer.byteLength(serializeEntryFile(entry), "utf8"), embedding, currentRev, current.scope, current.slug];

package/dist/plugins/memory-engine-sql-apply.d.ts

@@ -34,7 +34,10 @@
  * · 「已经写过」按**可能写过**算:一条写语句发出之后以 I/O 失败收场,库里落没落不知道 ⇒ 当作写过(此后不再问),否则后面一次被拒的重问
  *   就可能发生在一笔其实已落下的写之后。写语句的三种「没落」结局(唯一键冲突 / 零行 + 现读)是库给的确答,不算写过。
  * · 不传 opts ⇒ 没有计划阶段、`confirm` 是空操作;常规路径与改前逐字同。只在并发竞争路径上收紧:行在判与写之间被挪走 ⇒ 按现状重判
- *   再写(此前按 id 盲写);同 id 的行在判与写之间被别的副本插入 ⇒ 重判(guard / 跨 scope 拒照判,此前按 id 盲覆盖)。
+ *   再写(此前按 id 盲写);同 id 的行在判与写之间被别的副本插入或改写 ⇒ 重判(guard / 跨 scope 拒照判,此前按 id 盲覆盖)。
+ * · 写条件只有一条律:写语句绑住**判据用到的那一份** —— update / delete 判的是 rev(CAS)与投影 ⇒ 两者都绑;add 覆盖判的是投影
+ *   (落点),`guard: "absent"` 再判「恰是这一份」⇒ 再绑 rev;add 插入判的是「没有这一行」⇒ 只插入。裸 add 的判不看内容(幂等覆盖现值),
+ *   写也不绑 rev。库给的「没落」一律回到判(update / delete 的 rev 变了 = CAS 输,add = 重判)。
  */
 import { type MemoryBackend, type MemoryEntry, type MemoryEntryFrontmatter, type NotePatch, type PatchReport } from "@sema-agent/core";
 import type { MemoryHistoryAppendRow } from "./memory-sync-store-pg.js";
@@ -59,12 +62,18 @@ export interface SqlProjection {
     readonly scope: string;
     readonly slug: string;
 }
-/** add 的写入单:`stored` = 终拼形(含后缀)。`prior` = 计划时这个 id 的行所在的投影(缺席 = 计划时没有这一行):写语句只覆盖仍在那里的行,
- *  没有 prior 时只插入 —— 行在判与写之间被挪走 / 被别的副本插入都答 `moved`。 */
+/** add 覆盖的写条件:投影恒绑;`rev` 只在判据用到了它时在场(`guard: "absent"` 判的是「恰是这一份」),裸 add 的判不看内容 ⇒ `undefined`。 */
+export interface SqlAddPrior extends SqlProjection {
+    readonly rev: string | undefined;
+}
+/** add 的写入单:`stored` = 终拼形(含后缀)。`prior` = 计划时这个 id 的那一行要绑住的部分(缺席 = 计划时没有这一行):写语句只覆盖仍在
+ *  那里(且带 `rev` 时仍是那一份内容)的行,没有 prior 时只插入 —— 行在判与写之间被挪走 / 被改写(带 `rev` 时)/ 被别的副本插入都答 `moved`
+ *  (驱动器按现状重判:`guard: "absent"` 照判 —— 行已在且不是这一份内容 ⇒ `add_guard_absent_conflict`)。add-if-absent 因此是原子的:
+ *  「判时没有」与「判时恰是这一份」两个前提都随写语句一起交给库判,判与写之间的并发写者不会被静默覆盖。 */
 export interface SqlAddWrite {
     readonly stored: MemoryEntry;
     readonly rev: string;
-    readonly prior: SqlProjection | undefined;
+    readonly prior: SqlAddPrior | undefined;
 }
 /** update 的写入单:条件 = 判过的 rev **且**判过的投影 `current`。 */
 export interface SqlUpdateWrite {

package/dist/plugins/memory-engine-sql-apply.js

@@ -94,7 +94,7 @@ async function planSqlPatch(patch, reads, baseline, claims, unstorableReason, su
             kind: "add",
             stored,
             rev: computeEntryRev(stored),
-            prior: prior !== undefined ? { scope: prior.scope, slug: prior.slug } : undefined,
+            prior: prior !== undefined ? { scope: prior.scope, slug: prior.slug, rev: patch.guard === "absent" ? prior.rev : undefined } : undefined,
             frontmatter: entry.frontmatter,
             suffixAt: n,
             landings,

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

@@ -67,11 +67,14 @@ export declare class TiDBMemoryEngineBackend implements MemoryBackend {
     private freshRow;
     /**
      * add:拆成「计划时有行 ⇒ UPDATE by id / 没有 ⇒ INSERT」(见文件头:MySQL 的 ON DUPLICATE KEY UPDATE 会被 `(scope, slug)` 键抢占、改写他人行,
-     * 禁用)。UPDATE 腿只覆盖仍在计划投影上的行;零 AFFECTED 行 ⇒ 现读:行没了 = 被并发删掉 ⇒ 转 INSERT 腿、同一拼写(改前同);
-     * 行在别处 ⇒ `moved`;行还在计划的投影上且已是这一份内容 = 匹配但值逐字相同(连接未开 FOUND_ROWS 时只数改动行)⇒ 已落;
-     * 行还在计划的投影上却不是这一份内容 = 判与现读之间行被挪走又挪回 ⇒ 响亮抛(记成这一条的 io error 冲突,与 PG 孪生同答)。INSERT 腿的 ER_DUP_ENTRY 按键名分诊:
-     * PRIMARY = 同 id 的行在判与写之间被别的副本插入 ⇒ `moved`(驱动器按现状重判,guard / 跨 scope 拒照判);`uq_…scope_slug` = 名在计划之后
-     * 被占 ⇒ `slug-taken`。每次重发写语句前都调 confirm(它是检查,幂等)。
+     * 禁用)。UPDATE 腿只覆盖仍在计划投影上的行,add-if-absent 再绑计划读到的 rev(与 PG 孪生同一条件);零 AFFECTED 行 ⇒ 现读:行没了 = 被并发
+     * 删掉 ⇒ 转 INSERT 腿、同一拼写(改前同);行在别处、或(绑了 rev 时)已被改写 ⇒ `moved`(驱动器按现状重判:add-if-absent 照判);行仍满足写条件且
+     * 已是这一份内容 = 匹配但值逐字相同(连接未开 FOUND_ROWS 时只数改动行)⇒ 已落;仍满足写条件却不是这一份内容 = 判与现读之间行被改走又改回
+     * ⇒ 响亮抛(记成这一条的 io error 冲突,与 PG 孪生同答)。ER_DUP_ENTRY 按**现读**分诊,不按报文里的键名:INSERT 腿撞键之后这个 id 的行在 ⇒
+     * 同 id 的行在判与写之间被别的副本插入 ⇒ `moved`(驱动器按现状重判,guard / 跨 scope 拒照判;与 PG 孪生 `ON CONFLICT (id)` 的仲裁同答);不在 ⇒
+     * 名在计划之后被占 ⇒ `slug-taken`;UPDATE 腿按 id 改、只撞得上 `(scope, slug)` ⇒ `slug-taken`。键名不可作判据:对手以同 id **同拼写**插入时
+     * 两只唯一键同时撞上,引擎报哪一只由它自己定(TiDB 报 `uq_…scope_slug`)—— 按键名会把「同 id 已在」读成「名被占」、退到 `-2` 拼写去覆盖。
+     * 每次重发写语句前都调 confirm(它是检查,幂等)。
      */
     private writeAdd;
     /** update:条件 = 判过的 rev **且**判过的投影(rev 是内容哈希、不含 scope / slug)。零 AFFECTED 行 ⇒ 这一条的 CAS 按 **rev** 判(core 契约:stale

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

@@ -37,9 +37,6 @@ export async function ensureTiDBMemoryEngineSchema(pool) {
     await ensureIndexes((text, params) => pool.query(text, params), "mysql", MEMORY_ENGINE_INDEXES);
 }
 const isDupEntry = isMysqlDupKeyError;
-function isPrimaryKeyDup(err) {
-    return isDupEntry(err) && /for key '[^']*PRIMARY'/i.test(String(err.message ?? ""));
-}
 const AT_PLANNED_PROJECTION = "CAST(scope AS BINARY) = CAST(? AS BINARY) AND CAST(slug AS BINARY) = CAST(? AS BINARY)";
 function inPlaceholders(count) {
     return Array.from({ length: count }, () => "?").join(", ");
@@ -182,19 +179,19 @@ export class TiDBMemoryEngineBackend {
         for (;;) {
             try {
                 if (overwrite !== undefined) {
-                    const params = [stored.scope, stored.slug, JSON.stringify(stored.frontmatter), stored.body, rev, this.clock(), sizeBytes, stored.id, overwrite.scope, overwrite.slug];
+                    const params = [stored.scope, stored.slug, JSON.stringify(stored.frontmatter), stored.body, rev, this.clock(), sizeBytes, stored.id, ...(overwrite.rev !== undefined ? [overwrite.rev] : []), overwrite.scope, overwrite.slug];
                     confirm();
-                    const res = await this.write(`UPDATE ${T} SET scope = ?, slug = ?, frontmatter = ?, body = ?, rev = ?, mtime_ms = ?, size_bytes = ?, embedding = NULL WHERE id = ? AND ${AT_PLANNED_PROJECTION}`, params);
+                    const res = await this.write(`UPDATE ${T} SET scope = ?, slug = ?, frontmatter = ?, body = ?, rev = ?, mtime_ms = ?, size_bytes = ?, embedding = NULL WHERE id = ? AND ${overwrite.rev !== undefined ? "rev = ? AND " : ""}${AT_PLANNED_PROJECTION}`, params);
                     if (res.affectedRows === 0) {
                         const fresh = await this.freshRow(stored.id);
                         if (fresh === undefined) {
                             overwrite = undefined;
                             continue;
                         }
-                        if (fresh.scope !== overwrite.scope || fresh.slug !== overwrite.slug)
+                        if (fresh.scope !== overwrite.scope || fresh.slug !== overwrite.slug || (overwrite.rev !== undefined && fresh.rev !== overwrite.rev))
                             return { kind: "moved" };
                         if (fresh.rev !== rev) {
-                            throw new Error(`memory-engine: the add of ${JSON.stringify(stored.id)} wrote no row, yet the row is still at the planned projection with other content — refusing to report it either way`);
+                            throw new Error(`memory-engine: the add of ${JSON.stringify(stored.id)} wrote no row, yet the row still meets the write condition with other content — refusing to report it either way`);
                         }
                     }
                 }
@@ -207,7 +204,9 @@ export class TiDBMemoryEngineBackend {
             catch (err) {
                 if (!isDupEntry(err))
                     throw err;
-                return isPrimaryKeyDup(err) ? { kind: "moved" } : { kind: "slug-taken" };
+                if (overwrite !== undefined)
+                    return { kind: "slug-taken" };
+                return (await this.freshRow(stored.id)) !== undefined ? { kind: "moved" } : { kind: "slug-taken" };
             }
             return { kind: "committed" };
         }