@sema-agent/server 7.145.0 → 7.147.0

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

@@ -1,5 +1,6 @@
 import type { MemoryHistoryAppendRow } from "./memory-sync-store-pg.js";
 import type { PgEmbedder, PgQueryFn } from "./pg-query.js";
+import { type SqlApplyOpts } from "./memory-engine-sql-apply.js";
 import type { MemoryBackend, MemoryEntry, MemoryEntryHeader, NotePatch, PatchReport, ScoredMemoryEntry } from "@sema-agent/core";
 import { type IndexSpec } from "./ensure-index.js";
 /** Table names (single source). Deliberately DISJOINT from the legacy `agent_memory*` tables —
@@ -54,6 +55,8 @@ export declare class PgMemoryEngineBackend implements MemoryBackend {
     private readonly history?;
     /** Cumulative lost-row count — audit-line breakage must itself be auditable. */
     private historyRowsLost;
+    /** 交给共享驱动器的读口 / 写口 / history 冲刷(构造末尾铸一次)。 */
+    private readonly leg;
     /** [ref] rung indicator — same semantics as PgMemoryStore.vectorMode. */
     get vectorMode(): "native" | "portable" | "lexical";
     constructor(query: PgQueryFn, opts?: PgMemoryEngineBackendOptions);
@@ -70,12 +73,33 @@ export declare class PgMemoryEngineBackend implements MemoryBackend {
         limit?: number;
         exposureBands?: boolean;
     }): Promise<ScoredMemoryEntry[]>;
-    applyPatches(patches: readonly NotePatch[]): Promise<PatchReport>;
-    private applyOne;
-    /** When the conditional write returns zero rows (a write landed inside the
-     *  SELECT→write window), the report's `currentRev` must be the rev NOW — re-reporting the pre-race
-     *  SELECT value could claim `baseRev === currentRev` alongside a "rev mismatch" reason. */
-    private freshRev;
+    /** core 落点问询协议的能力位:`applyPatches` 兑现 `opts.admit` / `opts.confirm`(读法见 `memory-engine-sql-apply.ts` 头注)。 */
+    readonly admitsLandings: true;
+    /** 判与驱动器只在 `memory-engine-sql-apply.ts` 一处(两只 SQL 腿共用);本腿只供读口、PG 方言写口(写语句绑定计划的投影)与 history 冲刷。
+     *  `opts.anchoredRoot` 是带目录的后端的事,本腿没有目录 ⇒ 不读(core 契约原文:a backend without a directory ignores it)。 */
+    applyPatches(patches: readonly NotePatch[], opts?: SqlApplyOpts): Promise<PatchReport>;
+    private rowOf;
+    private idsAt;
+    /** 一个 patch 第一次要写之前算一次它的向量参数(撞名 / 被挪重试复用,不重调 embedder —— 改前 add 也只在后缀循环外算一次)。
+     *  haystack 用调用方给的原形(add 的原名,不是撞名后缀),与改前同。 */
+    private prepareWrite;
+    /** 写不落之后的现读:这个 id 的行此刻的 rev 与投影(没了 ⇒ undefined)。 */
+    private freshRow;
+    /**
+     * 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 报现值(行没了 ⇒ 判时的值)。 */
+    private writeUpdate;
+    /** delete:条件同 update。 */
+    private writeDelete;
+    /** BEST-EFFORT history append(见 PgMemoryEngineBackendOptions.history 的如实取舍):entry 写已提交,审计行追加失败不许让报告失败 ——
+     *  吞 + warn,永不抛;appendHistory 按 (id, rev) 幂等,调用方重试安全。 */
+    private appendHistory;
     getConsolidationCursor(scope: string): Promise<string | undefined>;
     setConsolidationCursor(scope: string, cursor: string): Promise<void>;
 }

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

@@ -2,10 +2,11 @@ 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";
 import { recordFailOpen } from "../observability/fail-open.js";
-import { computeEntryRev, serializeEntryFile } from "@sema-agent/core";
-import { pgSafeJsonStringify, pgHasUnstorable } from "./pg-safe-json.js";
-import { assertMemoryScopeWidth, memoryEntryKeyWidthRefusal } from "./memory-key-guards.js";
-import { ambiguousOriginRefusal, createBatchCommittedBaseline, exposureBandOf, exposureCarriage, originMarkedSqlPredicate, originWhitewashRefusal, rememberBatchCommitted, distilledWhitewashRefusal, distilledCarriage, unknownPatchOpRefusal, } from "./memory-origin-law.js";
+import { serializeEntryFile } from "@sema-agent/core";
+import { pgSafeJsonStringify } from "./pg-safe-json.js";
+import { assertMemoryScopeWidth } from "./memory-key-guards.js";
+import { exposureBandOf, exposureCarriage, originMarkedSqlPredicate, distilledCarriage } from "./memory-origin-law.js";
+import { applySqlPatches, } from "./memory-engine-sql-apply.js";
 import { ensureIndexes } from "./ensure-index.js";
 export const PG_MEMORY_ENGINE_TABLES = {
     entry: "agent_memory_engine_entry",
@@ -72,6 +73,7 @@ export class PgMemoryEngineBackend {
     clock;
     history;
     historyRowsLost = 0;
+    leg;
     get vectorMode() {
         return this.pgvectorSql ? "native" : this.embedder ? "portable" : "lexical";
     }
@@ -83,6 +85,18 @@ export class PgMemoryEngineBackend {
         this.history = opts.history;
         if (this.pgvectorSql && !this.embedder)
             throw new Error("PgMemoryEngineBackend: pgvectorSql requires an embedder");
+        this.leg = {
+            reads: { rowOf: (id) => this.rowOf(id), idsAt: (scope, slug) => this.idsAt(scope, slug) },
+            writes: {
+                prepare: (entry) => this.prepareWrite(entry),
+                add: (w, embedding, confirm) => this.writeAdd(w, embedding, confirm),
+                update: (w, embedding, confirm) => this.writeUpdate(w, embedding, confirm),
+                remove: (w, confirm) => this.writeDelete(w, confirm),
+            },
+            unstorableReason: "unstorable_bytes (PG cannot store NUL/lone surrogates; strip them at the source — the store never rewrites content)",
+            now: () => this.clock(),
+            ...(this.history !== undefined ? { appendHistory: (rows) => this.appendHistory(rows) } : {}),
+        };
     }
     haystackOf(slug, fm, body) {
         return `${fm.name ?? slug} ${fm.description ?? ""} ${body}`;
@@ -181,224 +195,92 @@ export class PgMemoryEngineBackend {
         scored.sort(contractOrder);
         return scored.slice(0, limit);
     }
-    async applyPatches(patches) {
-        const report = { applied: [], conflicts: [] };
-        const nonDeleteIds = new Set();
-        const plannedSlugs = new Set();
-        const historyRows = [];
-        const originBaseline = createBatchCommittedBaseline();
-        for (const patch of patches) {
-            try {
-                if (patch.op !== "delete") {
-                    if (nonDeleteIds.has(patch.id)) {
-                        report.conflicts.push({ op: patch.op, id: patch.id, reason: "duplicate id in batch: another add/update for this id is already planned (copied file keeping its frontmatter id?)" });
-                        continue;
-                    }
-                    nonDeleteIds.add(patch.id);
-                }
-                await this.applyOne(patch, report, plannedSlugs, historyRows, originBaseline);
-            }
-            catch (err) {
-                report.conflicts.push({ op: patch.op, id: patch.id, reason: `io error: ${err instanceof Error ? err.message : String(err)}` });
-            }
-        }
-        if (this.history && historyRows.length > 0) {
-            try {
-                await this.history.appendHistory(historyRows);
-            }
-            catch (err) {
-                this.historyRowsLost += historyRows.length;
-                console.warn(`PgMemoryEngineBackend: best-effort history append failed (${historyRows.length} row(s) lost, ${this.historyRowsLost} cumulative — audit face only, entries committed): ${err instanceof Error ? err.message : String(err)}`);
-            }
-        }
-        return report;
+    admitsLandings = true;
+    async applyPatches(patches, opts) {
+        return applySqlPatches(patches, opts, this.leg);
+    }
+    async rowOf(id) {
+        const res = await this.query(`SELECT slug, rev, scope, ${jsonColumnText("pg", "frontmatter")} FROM ${PG_MEMORY_ENGINE_TABLES.entry} WHERE id = $1`, [id]);
+        const r = res.rows[0];
+        if (r === undefined)
+            return undefined;
+        return { scope: String(r.scope), slug: String(r.slug), rev: String(r.rev), frontmatter: readFrontmatter(r.frontmatter, id) };
+    }
+    async idsAt(scope, slug) {
+        const res = await this.query(`SELECT id FROM ${PG_MEMORY_ENGINE_TABLES.entry} WHERE scope = $1 AND slug = $2`, [scope, slug]);
+        return res.rows.map((r) => String(r.id));
+    }
+    prepareWrite(entry) {
+        return this.embeddingParam(this.haystackOf(entry.slug, entry.frontmatter, entry.body));
     }
-    async applyOne(patch, report, plannedSlugs, historyRows, originBaseline) {
+    async freshRow(id) {
+        const res = await this.query(`SELECT rev, scope, slug FROM ${PG_MEMORY_ENGINE_TABLES.entry} WHERE id = $1`, [id]);
+        const r = res.rows[0];
+        return r === undefined ? undefined : { rev: String(r.rev), scope: String(r.scope), slug: String(r.slug) };
+    }
+    async writeAdd({ stored, rev, prior }, embedding, confirm) {
         const T = PG_MEMORY_ENGINE_TABLES.entry;
-        {
-            const refusal = unknownPatchOpRefusal(patch.op);
-            if (refusal !== undefined) {
-                report.conflicts.push({ op: patch.op, id: patch.id, reason: refusal });
-                return;
-            }
+        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${prior.rev !== undefined ? ` AND ${T}.rev = $12` : ""}`
+            : "ON CONFLICT (id) DO NOTHING";
+        if (prior !== undefined)
+            params.push(prior.scope, prior.slug, ...(prior.rev !== undefined ? [prior.rev] : []));
+        confirm();
+        let landed;
+        try {
+            const res = await this.query(`INSERT INTO ${T} (id, scope, slug, frontmatter, body, rev, mtime_ms, size_bytes, embedding)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+         ${onConflict}
+         RETURNING id`, params);
+            landed = res.rows.length > 0;
         }
-        if (patch.op !== "delete" && patch.entry !== undefined && patch.entry.id !== patch.id) {
-            report.conflicts.push({ op: patch.op, id: patch.id, reason: `patch id ${JSON.stringify(patch.id)} != entry id ${JSON.stringify(patch.entry.id)} (malformed patch refused)` });
-            return;
+        catch (err) {
+            if (isUniqueViolation(err))
+                return { kind: "slug-taken" };
+            throw err;
         }
-        if (patch.op !== "delete" && patch.entry !== undefined) {
-            const refusal = memoryEntryKeyWidthRefusal(patch.entry.scope, patch.entry.slug);
-            if (refusal !== undefined) {
-                report.conflicts.push({ op: patch.op, id: patch.id, reason: refusal });
-                return;
-            }
-        }
-        if (patch.op !== "delete" && patch.entry !== undefined) {
-            const refusal = ambiguousOriginRefusal(patch.entry.frontmatter);
-            if (refusal !== undefined) {
-                report.conflicts.push({ op: patch.op, id: patch.id, reason: refusal });
-                return;
-            }
-        }
-        if (patch.op === "add") {
-            const rawEntry = patch.entry;
-            if (!rawEntry) {
-                report.conflicts.push({ op: "add", id: patch.id, reason: "add patch without an entry" });
-                return;
-            }
-            if (pgHasUnstorable(rawEntry.frontmatter) || pgHasUnstorable(rawEntry.body) || pgHasUnstorable(rawEntry.slug)) {
-                report.conflicts.push({ op: "add", id: rawEntry.id, reason: "unstorable_bytes (PG cannot store NUL/lone surrogates; strip them at the source — the store never rewrites content)" });
-                return;
-            }
-            const entry = rawEntry;
-            const prior = await this.query(`SELECT scope, slug, rev, ${jsonColumnText("pg", "frontmatter")} FROM ${T} WHERE id = $1`, [entry.id]);
-            const priorRow = prior.rows.length > 0 ? prior.rows[0] : undefined;
-            {
-                const committedBaseFm = rememberBatchCommitted(originBaseline, entry.id, priorRow !== undefined ? readFrontmatter(priorRow.frontmatter, entry.id) : undefined);
-                const refusal = originWhitewashRefusal("add", committedBaseFm, entry.frontmatter);
-                if (refusal !== undefined) {
-                    report.conflicts.push({ op: "add", id: entry.id, reason: refusal });
-                    return;
-                }
-                const dRefusal = distilledWhitewashRefusal("add", committedBaseFm, entry.frontmatter);
-                if (dRefusal !== undefined) {
-                    report.conflicts.push({ op: "add", id: entry.id, reason: dRefusal });
-                    return;
-                }
-            }
-            if (patch.guard === "absent" && priorRow) {
-                const currentRev = String(priorRow.rev);
-                if (currentRev !== computeEntryRev(entry)) {
-                    report.conflicts.push({ op: "add", id: entry.id, reason: "add_guard_absent_conflict (id already exists at a different rev; add-if-absent refuses to overwrite)", currentRev });
-                    return;
-                }
-                if (String(priorRow.scope) !== entry.scope || String(priorRow.slug) !== entry.slug) {
-                    report.conflicts.push({ op: "add", id: entry.id, reason: `add_guard_absent_conflict (id already exists at the same rev but a different projection ${JSON.stringify(`${String(priorRow.scope)}/${String(priorRow.slug)}`)}; add-if-absent refuses to duplicate)`, currentRev });
-                    return;
-                }
-            }
-            if (priorRow) {
-                const held = String(priorRow.scope);
-                if (held !== entry.scope) {
-                    report.conflicts.push({ op: "add", id: entry.id, reason: `id already exists in scope ${JSON.stringify(held)} (cross-scope add refused)` });
-                    return;
-                }
-            }
-            const cEntry = entry;
-            const embedding = await this.embeddingParam(this.haystackOf(cEntry.slug, cEntry.frontmatter, cEntry.body));
-            let slug = cEntry.slug;
-            for (let n = 2;; n++) {
-                const derivedRefusal = memoryEntryKeyWidthRefusal(entry.scope, slug);
-                if (derivedRefusal !== undefined) {
-                    report.conflicts.push({ op: "add", id: entry.id, reason: `${derivedRefusal} (slug collision suffix "-${n - 1}" no longer fits the column — shorten the entry name)` });
-                    return;
-                }
-                const key = `${entry.scope}|${slug}`;
-                if (!plannedSlugs.has(key)) {
-                    const taken = await this.query(`SELECT id FROM ${T} WHERE scope = $1 AND slug = $2`, [entry.scope, slug]);
-                    const otherId = taken.rows.find((r) => String(r.id) !== entry.id);
-                    if (!otherId) {
-                        const stored = { ...cEntry, slug };
-                        const rev = computeEntryRev(stored);
-                        try {
-                            await this.query(`INSERT INTO ${T} (id, scope, slug, frontmatter, body, rev, mtime_ms, size_bytes, embedding)
-                 VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
-                 ON CONFLICT (id) DO UPDATE SET scope = $2, slug = $3, frontmatter = $4, body = $5, rev = $6, mtime_ms = $7, size_bytes = $8, embedding = $9`, [stored.id, stored.scope, stored.slug, pgSafeJsonStringify(stored.frontmatter), stored.body, rev, this.clock(), Buffer.byteLength(serializeEntryFile(stored), "utf8"), embedding]);
-                        }
-                        catch (err) {
-                            if (isUniqueViolation(err)) {
-                                slug = `${entry.slug}-${n}`;
-                                continue;
-                            }
-                            throw err;
-                        }
-                        plannedSlugs.add(key);
-                        report.applied.push({ op: "add", id: stored.id, slug: stored.slug });
-                        if (this.history)
-                            historyRows.push({ id: stored.id, rev, op: "add", scope: stored.scope, snapshot: { ...stored, rev }, writtenAtMs: this.clock() });
-                        return;
-                    }
-                }
-                slug = `${entry.slug}-${n}`;
-            }
-        }
-        const cur = await this.query(`SELECT slug, rev, scope, ${jsonColumnText("pg", "frontmatter")} FROM ${PG_MEMORY_ENGINE_TABLES.entry} WHERE id = $1`, [patch.id]);
-        if (cur.rows.length === 0) {
-            report.conflicts.push({ op: patch.op, id: patch.id, reason: "unknown id (entry not found in backend)" });
-            return;
-        }
-        const currentRev = String(cur.rows[0].rev);
-        const currentSlug = String(cur.rows[0].slug);
-        const currentScope = String(cur.rows[0].scope);
-        const committedFm = readFrontmatter(cur.rows[0].frontmatter, patch.id);
-        const committedBaseFm = rememberBatchCommitted(originBaseline, patch.id, committedFm);
-        if (patch.op === "update" && patch.entry !== undefined) {
-            if (committedFm.provenance?.kind === "repo_file") {
-                const next = patch.entry.frontmatter;
-                const stripsProvenance = next.provenance === undefined;
-                const stripsTrust = committedFm.trust !== undefined && next.trust === undefined;
-                if (stripsProvenance || stripsTrust) {
-                    report.conflicts.push({
-                        op: "update",
-                        id: patch.id,
-                        reason: `repo_file provenance whitewash refused: update drops ${stripsProvenance ? "provenance" : "trust"} from a repo-ingested entry (malformed patch refused)`,
-                    });
-                    return;
-                }
-            }
-            const refusal = originWhitewashRefusal("update", committedBaseFm, patch.entry.frontmatter);
-            if (refusal !== undefined) {
-                report.conflicts.push({ op: "update", id: patch.id, reason: refusal });
-                return;
-            }
-            const dRefusal = distilledWhitewashRefusal("update", committedBaseFm, patch.entry.frontmatter);
-            if (dRefusal !== undefined) {
-                report.conflicts.push({ op: "update", id: patch.id, reason: dRefusal });
-                return;
-            }
-        }
-        if (patch.baseRev !== undefined && patch.baseRev !== currentRev) {
-            report.conflicts.push({ op: patch.op, id: patch.id, reason: "rev mismatch (concurrent change)", baseRev: patch.baseRev, currentRev });
-            return;
-        }
-        if (patch.op === "delete") {
-            const res = await this.query(`DELETE FROM ${PG_MEMORY_ENGINE_TABLES.entry} WHERE id = $1 AND rev = $2 RETURNING id`, [patch.id, currentRev]);
-            if (res.rows.length === 0) {
-                report.conflicts.push({ op: "delete", id: patch.id, reason: "rev mismatch (concurrent change)", baseRev: patch.baseRev, currentRev: await this.freshRev(patch.id, currentRev) });
-                return;
-            }
-            report.applied.push({ op: "delete", id: patch.id, slug: currentSlug });
-            if (this.history)
-                historyRows.push({ id: patch.id, rev: `tombstone:${currentRev}`, prevRev: currentRev, op: "delete", scope: currentScope, writtenAtMs: this.clock() });
-            return;
-        }
-        const entry = patch.entry;
-        if (!entry) {
-            report.conflicts.push({ op: "update", id: patch.id, reason: "update patch without an entry" });
-            return;
-        }
-        if (pgHasUnstorable(entry.frontmatter) || pgHasUnstorable(entry.body) || pgHasUnstorable(entry.slug)) {
-            report.conflicts.push({ op: "update", id: patch.id, reason: "unstorable_bytes (PG cannot store NUL/lone surrogates; strip them at the source — the store never rewrites content)" });
-            return;
-        }
-        const cEntry = entry;
-        const rev = computeEntryRev(cEntry);
-        const embedding = await this.embeddingParam(this.haystackOf(cEntry.slug, cEntry.frontmatter, cEntry.body));
+        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 || (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 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
-        RETURNING id`, [cEntry.id, cEntry.scope, cEntry.slug, pgSafeJsonStringify(cEntry.frontmatter), cEntry.body, rev, this.clock(), Buffer.byteLength(serializeEntryFile(cEntry), "utf8"), embedding, currentRev]);
-        if (res.rows.length === 0) {
-            report.conflicts.push({ op: "update", id: patch.id, reason: "rev mismatch (concurrent change)", baseRev: patch.baseRev, currentRev: await this.freshRev(patch.id, currentRev) });
+        WHERE id = $1 AND rev = $10 AND scope = $11 AND slug = $12
+        RETURNING id`, params);
+        if (res.rows.length > 0)
+            return { kind: "committed" };
+        const fresh = await this.freshRow(entry.id);
+        if (fresh !== undefined && fresh.rev === currentRev && (fresh.scope !== current.scope || fresh.slug !== current.slug))
+            return { kind: "moved" };
+        return { kind: "lost", conflict: { op: "update", id: entry.id, reason: "rev mismatch (concurrent change)", baseRev, currentRev: fresh?.rev ?? currentRev } };
+    }
+    async writeDelete({ id, currentRev, current, baseRev }, confirm) {
+        confirm();
+        const res = await this.query(`DELETE FROM ${PG_MEMORY_ENGINE_TABLES.entry} WHERE id = $1 AND rev = $2 AND scope = $3 AND slug = $4 RETURNING id`, [id, currentRev, current.scope, current.slug]);
+        if (res.rows.length > 0)
+            return { kind: "committed" };
+        const fresh = await this.freshRow(id);
+        if (fresh !== undefined && fresh.rev === currentRev && (fresh.scope !== current.scope || fresh.slug !== current.slug))
+            return { kind: "moved" };
+        return { kind: "lost", conflict: { op: "delete", id, reason: "rev mismatch (concurrent change)", baseRev, currentRev: fresh?.rev ?? currentRev } };
+    }
+    async appendHistory(rows) {
+        if (!this.history)
             return;
+        try {
+            await this.history.appendHistory(rows);
+        }
+        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)}`);
         }
-        report.applied.push({ op: "update", id: entry.id, slug: entry.slug });
-        if (this.history)
-            historyRows.push({ id: entry.id, rev, prevRev: currentRev, op: "update", scope: entry.scope, snapshot: { ...entry, rev }, writtenAtMs: this.clock() });
-    }
-    async freshRev(id, fallback) {
-        const res = await this.query(`SELECT rev FROM ${PG_MEMORY_ENGINE_TABLES.entry} WHERE id = $1`, [id]);
-        return res.rows.length > 0 ? String(res.rows[0].rev) : fallback;
     }
     async getConsolidationCursor(scope) {
         const res = await this.query(`SELECT cursor FROM ${PG_MEMORY_ENGINE_TABLES.cursor} WHERE scope = $1`, [scope]);