@sema-agent/server 7.146.0 → 7.148.0

package/dist/plugins/local-session-window.d.ts

@@ -52,8 +52,9 @@ export declare class LocalSessionWindow extends BaseSessionStorage {
     private constructor();
     appendEntry(): Promise<void>;
     setLeafId(): Promise<void>;
-    /** `SessionStorage.getEpochAnchor?()` — the nearest carrier on the branch below the floor, as stored ({@link scanEpochAnchor}).
-     *  A row's `seq` is its position on the branch; the whole branch is in memory, so one page holds every row. */
+    /** `SessionStorage.getEpochAnchor?()` — the nearest carrier on the branch below the floor, as stored ({@link scanEpochAnchor}: the floor's
+     *  parent chain, the one walk every windowed storage shares). A row's `seq` is its position on the branch; the whole branch is in memory,
+     *  so one page holds every row (every one of them on the walk). */
     getEpochAnchor(): Promise<unknown>;
     /** Wake the window of `sessionId` from the local session store's rows; `null` if there is no such session. */
     static wake(rows: LocalSessionRows, sessionId: string): Promise<LocalSessionWindow | null>;

package/dist/plugins/local-session-window.js

@@ -1,5 +1,5 @@
 import { BaseSessionStorage, InMemorySessionStorage, SessionError, boundedTail } from "@sema-agent/core";
-import { scanEpochAnchor } from "./session-epoch-anchor.js";
+import { epochFloorOf, scanEpochAnchor } from "./session-epoch-anchor.js";
 export class LocalSessionWindow extends BaseSessionStorage {
     below;
     constructor(metadata, window, leafId, floorEntryId, below) {
@@ -13,7 +13,8 @@ export class LocalSessionWindow extends BaseSessionStorage {
         throw new SessionError("storage", "LocalSessionWindow is a read-only view of a session — write through the session store");
     }
     async getEpochAnchor() {
-        return scanEpochAnchor(this.below.length, async (beforeSeq) => this.below.slice(0, beforeSeq).map((entry, seq) => ({ seq, entry })).reverse(), (row) => row.entry);
+        const floorId = this.getFloorId();
+        return scanEpochAnchor(epochFloorOf(this.below.length, floorId === null ? undefined : await this.getEntry(floorId)), async (beforeSeq) => this.below.slice(0, beforeSeq).map((entry, seq) => ({ seq, id: entry.id, parentId: entry.parentId ?? null, type: entry.type, entry })).reverse(), (row) => row.entry);
     }
     static async wake(rows, sessionId) {
         const log = await rows.exportEntries(sessionId);

package/dist/plugins/local-sidecar-quarantine.js

@@ -1,3 +1,4 @@
+import { writeLogText } from "../observability/logger.js";
 import { renameSync } from "node:fs";
 export function quarantineUnreadableSidecar(path, what, reason) {
     const target = `${path}.corrupt-${Date.now()}-${process.pid}`;
@@ -5,11 +6,11 @@ export function quarantineUnreadableSidecar(path, what, reason) {
         renameSync(path, target);
     }
     catch (e) {
-        console.warn(`${what}: ${path} is unreadable (${reason}) and could NOT be quarantined (${e instanceof Error ? e.message : String(e)}) — ` +
+        writeLogText("stderr", `${what}: ${path} is unreadable (${reason}) and could NOT be quarantined (${e instanceof Error ? e.message : String(e)}) — ` +
             `the bytes are still at that path; a later write to it may replace them`);
         return undefined;
     }
-    console.warn(`${what}: ${path} is unreadable (${reason}) — quarantined at ${target} so the next write cannot replace it`);
+    writeLogText("stderr", `${what}: ${path} is unreadable (${reason}) — quarantined at ${target} so the next write cannot replace it`);
     return target;
 }
 //# sourceMappingURL=local-sidecar-quarantine.js.map

package/dist/plugins/local-task-attachment-store.d.ts

@@ -1,11 +1,24 @@
 import { type AttachmentStoreBindOutcome, type TaskAttachmentStore, type TaskAttachmentRecord } from "./task-attachment-store.js";
+import type { LocalSessionStore } from "./local-session-store.js";
+/** 附件店在数据根下的目录(构造器与一次性迁移 M39 的名册同读这一只)。 */
+export declare function attachmentStoreDirFor(rootDir: string): string;
 export declare class LocalTaskAttachmentStore implements TaskAttachmentStore {
     private readonly dir;
     private metas;
     private hydration;
     /** 变更串行段的尾(见 `serialized`):每只变更口排在上一只的落盘与合回之后。本店唯一一只。 */
     private mutationTail;
-    constructor(rootDir: string);
+    /**
+     * 客户端写计数口(同一数据根上的 local 会话店;提交出口撤回一只刚铸会话之前读这只计数,`session-birth.ts`):绑定在这只会话的根行锁里判、真绑上行时先 +1 再落盘。
+     * 缺席 = 本店的绑定不计数 —— 撤回就可能删掉一只已绑附件的会话,所以带会话店的装配必须交它(只测附件店的用例不交)。
+     */
+    private readonly clientWrites;
+    constructor(rootDir: string, opts?: {
+        readonly clientWrites?: Pick<LocalSessionStore, "withClientWrite">;
+    });
+    /** 一次性迁移 **M42 的 local 附件腿**(场景前缀的切换检查;窗口见 `plugins/one-time-migrations.ts` 登记表):属主以保留前缀开头的附件数。
+     *  附件可以先于任何会话 / run 上传(属主不经那两只店)⇒ 本店自己一处来源。水合那一读,零写;读不出的 meta 照水合同一条跳过臂。 */
+    scenarioPrefixOwnerRowsM42(): Promise<number>;
     private hydrate;
     /**
      * 本店**唯一**的变更串行段:凡改 `this.metas` 或删盘上行的口(put / bind / delete / deleteBySession / reapUnbound)把**整条操作**
@@ -21,10 +34,16 @@ export declare class LocalTaskAttachmentStore implements TaskAttachmentStore {
     getContent(owner: string, id: string): Promise<Uint8Array | null>;
     private persistMeta;
     bind(owner: string, ids: readonly string[], sessionId: string, boundAtMs: number): Promise<AttachmentStoreBindOutcome>;
+    /** {@link bind} 的串行段一形(`count` = 客户端写计数,真绑上行时在落盘之前调;缺 = 不计)。 */
+    private bindSerialized;
     listBySession(sessionId: string): Promise<TaskAttachmentRecord[]>;
     /** 删一行(meta + bytes + 内存索引)。只在 `serialized` 的操作体里调用。 */
     private removeRow;
     delete(owner: string, id: string): Promise<boolean>;
+    /** local 形一行一份字节(不跨行共享,行删即字节删,见 `removeRow`)⇒ 给不出「行已删、字节还在」的哈希:local 执行体回执里的附件哈希恒空,这一口无字节可放。 */
+    releaseBytes(_shas: readonly string[]): Promise<{
+        readonly failed: readonly string[];
+    }>;
     deleteBySession(sessionId: string): Promise<number>;
     reapUnbound(olderThanMs: number): Promise<number>;
 }

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

@@ -1,16 +1,31 @@
+import { SCENARIO_SUBJECT_PREFIX } from "../owner-brands.js";
 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");
+    clientWrites;
+    constructor(rootDir, opts) {
+        this.dir = attachmentStoreDirFor(rootDir);
+        this.clientWrites = opts?.clientWrites;
+    }
+    async scenarioPrefixOwnerRowsM42() {
+        let n = 0;
+        for (const meta of (await this.hydrate()).values())
+            if (meta.owner.startsWith(SCENARIO_SUBJECT_PREFIX))
+                n += 1;
+        return n;
     }
     hydrate() {
         this.hydration ??= (async () => {
@@ -46,14 +61,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,11 +84,15 @@ 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) {
+        const gate = this.clientWrites;
+        if (gate === undefined)
+            return this.bindSerialized(owner, ids, sessionId, boundAtMs, undefined);
+        return gate.withClientWrite(sessionId, (count) => this.bindSerialized(owner, ids, sessionId, boundAtMs, count));
+    }
+    bindSerialized(owner, ids, sessionId, boundAtMs, count) {
         return this.serialized(async () => {
             const metas = await this.hydrate();
             const draft = new Map(metas);
@@ -87,6 +102,8 @@ export class LocalTaskAttachmentStore {
                     draft.set(id, { ...row });
             }
             const { outcome, claimed } = bindRowsInProcess(draft, owner, ids, sessionId, boundAtMs);
+            if (claimed.length > 0 && count !== undefined)
+                await count();
             const landed = [];
             try {
                 for (const m of claimed) {
@@ -122,6 +139,9 @@ export class LocalTaskAttachmentStore {
             return true;
         });
     }
+    async releaseBytes(_shas) {
+        return { failed: [] };
+    }
     deleteBySession(sessionId) {
         return this.serialized(async () => {
             const metas = await this.hydrate();

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

@@ -1,7 +1,11 @@
 import { joinRequestUrl } from "@sema-agent/core";
 import { z } from "zod";
-import { egressRedirectRefusal } from "../egress-redirect.js";
+import { EgressRedirectRefusedError, createEgressFetch } from "../egress-redirect.js";
 import { buildDisplaySafeRefusal, buildDisplaySafeUrl } from "../trace/redact.js";
+import { createLogger } from "../observability/logger.js";
+import { errorText } from "../observability/err-text.js";
+const MEMORY_EMBEDDER_HOOK_THREW = "memory_embedder_observability_hook_threw";
+const embedderLog = createLogger();
 const EmbeddingsResponse = z.object({
     data: z.array(z.object({ embedding: z.array(z.number()) })).min(1),
 });
@@ -28,7 +32,7 @@ function credentialsInQuery(endpoint) {
 export function createOpenAiCompatEmbedder(opts) {
     const url = embeddingsUrl(opts.endpoint);
     const shownUrl = buildDisplaySafeUrl(url);
-    const fetchImpl = opts.fetchImpl ?? fetch;
+    const fetchImpl = createEgressFetch("declare the final endpoint as MEMORY_EMBEDDER_ENDPOINT", opts.fetchImpl);
     const { model, dimensions, timeoutMs, apiKey, onFailure } = opts;
     const secrets = [...(apiKey !== undefined ? [apiKey] : []), ...credentialsInQuery(opts.endpoint)];
     const scrub = (raw) => secrets.reduce((acc, s) => acc.replaceAll(s, "***"), raw);
@@ -44,15 +48,13 @@ export function createOpenAiCompatEmbedder(opts) {
                 },
                 body: JSON.stringify({ model, input: text }),
                 signal: AbortSignal.timeout(timeoutMs),
-                redirect: "manual",
             });
         }
         catch (transportErr) {
+            if (transportErr instanceof EgressRedirectRefusedError)
+                throw new Error(`memory embedder POST ${shownUrl}: ${transportErr.message}`);
             throw new Error(`memory embedder POST ${shownUrl}: transport failure — ${safeSlice(String(transportErr))}`);
         }
-        const redirected = egressRedirectRefusal(res, "declare the final endpoint as MEMORY_EMBEDDER_ENDPOINT");
-        if (redirected !== undefined)
-            throw new Error(`memory embedder POST ${shownUrl}: ${redirected}`);
         const raw = await res.text().catch((readErr) => {
             throw new Error(`memory embedder POST ${shownUrl}: response body unreadable — ${safeSlice(String(readErr))}`);
         });
@@ -86,7 +88,7 @@ export function createOpenAiCompatEmbedder(opts) {
                     onFailure?.(err);
                 }
                 catch (hookErr) {
-                    process.emitWarning(`memory embedder onFailure hook threw: ${String(hookErr)}`, "MemoryEmbedderObservabilityWarning");
+                    embedderLog.warn(MEMORY_EMBEDDER_HOOK_THREW, { err: errorText(hookErr) });
                 }
                 throw err;
             }
@@ -94,9 +96,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

@@ -41,7 +41,7 @@ export interface PgMemoryEngineBackendOptions {
      *  connections, so a true transaction would require refactoring the constructor to a client-checkout
      *  seam (breaks the origin-core@3071dd3 minimal-diff move-in discipline).
      *  Chosen trade-off: entry write commits first, history append is BEST-EFFORT
-     *  (failure = swallow + console.warn) — history is the AUDIT face, not the correctness face: a lost
+     *  (failure = swallow + a log-seam warn line) — history is the AUDIT face, not the correctness face: a lost
      *  history row loses an audit line, never data (the entries table stays the single truth). */
     history?: {
         appendHistory(rows: readonly MemoryHistoryAppendRow[]): Promise<void>;
@@ -86,13 +86,15 @@ 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`;其余 =
-     *  CAS 冲突,currentRev 报现值(行没了 ⇒ 判时的值)。 */
+     *  CAS 冲突,currentRev 报现值(行没了 ⇒ 判时的值)。撞唯一键:主键 `id` 不变,能撞的只有 `(scope, slug)` —— 目标名在判之后被别的 id 占了
+     *  ⇒ `slug-taken`(与 add 口同一结局词;驱动器重判,判当场判成冲突)。 */
     private writeUpdate;
     /** delete:条件同 update。 */
     private writeDelete;

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

@@ -1,3 +1,4 @@
+import { writeLogText } from "../observability/logger.js";
 import { cosineDistance, jaccardDistance, termSet } from "@sema-agent/core";
 import { isUniqueViolation, readEmbeddingColumn, readFrontmatterColumn } from "./memory-engine-vector-util.js";
 import { decodeJsonColumn, decodeNullableJsonColumn, foldJsonColumn, isJsonColumnBodyProblem, jsonColumnText } from "./sql-json-column.js";
@@ -222,10 +223,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,17 +244,25 @@ 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];
         confirm();
-        const res = await this.query(`UPDATE ${PG_MEMORY_ENGINE_TABLES.entry}
-          SET scope = $2, slug = $3, frontmatter = $4, body = $5, rev = $6, mtime_ms = $7, size_bytes = $8, embedding = $9
-        WHERE id = $1 AND rev = $10 AND scope = $11 AND slug = $12
-        RETURNING id`, params);
+        let res;
+        try {
+            res = await this.query(`UPDATE ${PG_MEMORY_ENGINE_TABLES.entry}
+            SET scope = $2, slug = $3, frontmatter = $4, body = $5, rev = $6, mtime_ms = $7, size_bytes = $8, embedding = $9
+          WHERE id = $1 AND rev = $10 AND scope = $11 AND slug = $12
+          RETURNING id`, params);
+        }
+        catch (err) {
+            if (isUniqueViolation(err))
+                return { kind: "slug-taken" };
+            throw err;
+        }
         if (res.rows.length > 0)
             return { kind: "committed" };
         const fresh = await this.freshRow(entry.id);
@@ -279,7 +288,7 @@ export class PgMemoryEngineBackend {
         }
         catch (err) {
             this.historyRowsLost += rows.length;
-            console.warn(`PgMemoryEngineBackend: best-effort history append failed (${rows.length} row(s) lost, ${this.historyRowsLost} cumulative — audit face only, entries committed): ${err instanceof Error ? err.message : String(err)}`);
+            writeLogText("stderr", `PgMemoryEngineBackend: best-effort history append failed (${rows.length} row(s) lost, ${this.historyRowsLost} cumulative — audit face only, entries committed): ${err instanceof Error ? err.message : String(err)}`);
         }
     }
     async getConsolidationCursor(scope) {

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

@@ -24,17 +24,24 @@
  * · LANDING = 一个 patch 写下或移走的每个拼写 `{ id, scope, slug }`:add 的终拼(含撞名后缀)、同 scope 改名留下的旧拼、update 的目标
  *   与移走的旧拼、delete 移走的拼。
  * · 写语句把**计划的投影**也绑进条件(rev 是内容哈希、不含 scope / slug,单靠 `WHERE id AND rev` 绑不住落点):行在计划之后被挪到别的拼写
- *   ⇒ 写不落,方言写口按现读答 `moved`,驱动器重判(新拼写同样要问过才写);名被占(唯一键冲突)⇒ `slug-taken`,重判从下一个后缀起
- *   (与改前「撞键即退下一个后缀」同一序列)。
+ *   ⇒ 写不落,方言写口按现读答 `moved`,驱动器重判(新拼写同样要问过才写);名被占(唯一键 `(scope, slug)` 冲突,add 与 update 两口同译)
+ *   ⇒ `slug-taken`,一条律:这一 patch 的候选起格越过被拒的那个拼写、驱动器重判 —— add 从下一个后缀起(与改前「撞键即退下一个后缀」同一序列);
+ *   update 只有一个候选(目标拼写)⇒ 越过即没有候选,判成冲突(被库拒过的拼写本次 apply 不再重写:对手在拒之后腾出名也一样,重写留给下次 apply ——
+ *   否则「每条写前占名、拒后腾名」的对手能让同一计划无界重写)。
+ * · 「目标名被别的 id 占着」只在判里判一处({@link planSqlPatch} 的 update 支):计划阶段就看得见的占名在那里直接判成冲突(一句、方言无关、
+ *   零写语句、不产落点);写语句那一刻才撞上的占名经 `slug-taken` 推过候选起格、回到同一处判。所以这一冲突两条路同一句,且都不是「可能写过」。
  * · 问的次数有上限(core `MAX_LANDING_ADMISSION_ROUNDS`),超了 core 抛 `memory.landing_unstable`(此时恒一字未写)。
  * · `confirm` = 调用方的最后一句话:方言写口在**每条** entry 写语句发出之前同步调它(与写语句之间没有 await)。SQL 腿不持事务锁 ——
  *   confirm 与写语句之间仍有一段竞争窗,这是两腿「单语句 CAS、无事务」的既有结构事实(MIGRATION / USAGE 的已知限制一句)。
  * · 抛错分诊:per-patch 的 catch 只把读 / 写 I/O 失败记成 `io error` 冲突(改前同);`confirm` 的抛被包成 {@link CallerThrow} 越过这道
  *   catch,出驱动器时还原成调用方抛出的**同一个值**;`admit` 根本不在 catch 内。已提交 patch 的 history 在 `finally` 里照冲刷。
  * · 「已经写过」按**可能写过**算:一条写语句发出之后以 I/O 失败收场,库里落没落不知道 ⇒ 当作写过(此后不再问),否则后面一次被拒的重问
- *   就可能发生在一笔其实已落下的写之后。写语句的三种「没落」结局(唯一键冲突 / 零行 + 现读)是库给的确答,不算写过。
+ *   就可能发生在一笔其实已落下的写之后。写语句的「没落」结局(唯一键冲突 —— add 与 update 两口 / 零行 + 现读)是库给的确答,不算写过。
  * · 不传 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 +66,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 {
@@ -82,7 +95,7 @@ export interface SqlDeleteWrite {
     readonly baseRev: string | undefined;
 }
 /**
- * 一次写的结局:`committed` = 落了;`slug-taken` = 唯一键 `(scope, slug)` 冲突(名在计划之后被别的副本占了);`moved` = 写不落而现读显示
+ * 一次写的结局:`committed` = 落了;`slug-taken` = 唯一键 `(scope, slug)` 冲突(名在计划之后被别的副本占了;add 与 update 两口同译);`moved` = 写不落而现读显示
  * 这个 id 的行已不在计划的投影上(或计划时没有、现在有了);`lost` = rev CAS 输了(冲突里的 currentRev 是现值)。
  */
 export type SqlWriteOutcome = {