@sema-agent/server 7.144.0 → 7.146.0

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,32 @@ 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 的幂等
+     * 覆盖;行被挪走就不覆盖 —— 被挪去的那个拼写没问过);计划时没有 ⇒ `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`
+            : "ON CONFLICT (id) DO NOTHING";
+        if (prior !== undefined)
+            params.push(prior.scope, prior.slug);
+        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))
+            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`);
+    }
+    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]);

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

@@ -0,0 +1,121 @@
+/**
+ * 两只 SQL 记忆腿(`memory-engine-pg.ts` / `memory-engine-tidb.ts`)的 `applyPatches` —— **一份判、一个驱动器**。
+ *
+ * ## 为什么是一个共享模块
+ *
+ * 两腿此前各抄一份 `applyOne`(op 闭集 / 键宽 / 歧义 origin / 不可变律 / guard / 跨 scope / 撞名后缀 / rev CAS),逐段「Pg 版同注」,
+ * 且「判」与「写」交织在一条循环里。core 的落点问询协议(`MemoryBackend.applyPatches` 的 `opts.admit` / `opts.confirm` 与能力位
+ * `admitsLandings`,协议原文 = core `landing-admission.d.ts` 头注)要求后端**先判出整批的落点、问过、再写** —— 交织形做不到,两份
+ * 各拆一遍就是两个写者写同一条协议。所以判只有一份({@link planSqlPatch},只读,产出决定 + 落点),驱动器只有一个
+ * ({@link applySqlPatches}),两腿各自只剩**读口**(两只 SELECT)、**方言写口**(add / update / delete 的 CAS 写)与 history 冲刷。
+ *
+ * ## 协议在 SQL 上的读法
+ *
+ * 与 core File 腿(`file-backend.js` 的 `applyPatches` / `applyPatchesLocked`)的差别都出自「SQL 腿没有事务锁」这一个结构事实:
+ * ① File 在锁内计划、出锁问、再进锁重计划,直到整批每个落点都问过才开始提交;这里没有锁可出,计划是对库的只读预测,问过之后
+ *    **再整批预测一遍**(File 的「再计划」),仍有没问过的就再问 —— 所以 `admit` 的每一次调用都在本次 apply 的第一笔写之前,拒 ⇒ 一字未写。
+ *    「问、记下问过的、轮数预算、超限的码与句」整圈是 core 的 `admittingLandings`(File 腿同一只),本模块只交它一次尝试(预测 + 提交);
+ *    「这些落点问过没有」只问 core 的 `requireLandingsAdmitted`(问过的集合与它的键都是 core 的,本模块不持第二份);
+ * ② 提交恒为一 patch 一条写语句(两态都不会一次提交两个 patch 的落点)。每条写之前现判一次:落点在最后一次预测之后才变(并发写者抢名 /
+ *    挪走行)且变出了没问过的拼写 ⇒ 本次 apply 还一笔没写时回去再问;已经写过 ⇒ 不再问(再问就可能「拒了却已写了前缀」),这一条报冲突、
+ *    一字不写,下次 apply 再问 —— 与 File「崩在两个落点之间,后一个留给下次 apply 再问」同一语义(变去的拼写都问过 ⇒ 照写);
+ * ③ File 的 confirm 在事务锁下调;这里在写语句之前同步调,不持锁。
+ *
+ * · LANDING = 一个 patch 写下或移走的每个拼写 `{ id, scope, slug }`:add 的终拼(含撞名后缀)、同 scope 改名留下的旧拼、update 的目标
+ *   与移走的旧拼、delete 移走的拼。
+ * · 写语句把**计划的投影**也绑进条件(rev 是内容哈希、不含 scope / slug,单靠 `WHERE id AND rev` 绑不住落点):行在计划之后被挪到别的拼写
+ *   ⇒ 写不落,方言写口按现读答 `moved`,驱动器重判(新拼写同样要问过才写);名被占(唯一键冲突)⇒ `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 失败收场,库里落没落不知道 ⇒ 当作写过(此后不再问),否则后面一次被拒的重问
+ *   就可能发生在一笔其实已落下的写之后。写语句的三种「没落」结局(唯一键冲突 / 零行 + 现读)是库给的确答,不算写过。
+ * · 不传 opts ⇒ 没有计划阶段、`confirm` 是空操作;常规路径与改前逐字同。只在并发竞争路径上收紧:行在判与写之间被挪走 ⇒ 按现状重判
+ *   再写(此前按 id 盲写);同 id 的行在判与写之间被别的副本插入 ⇒ 重判(guard / 跨 scope 拒照判,此前按 id 盲覆盖)。
+ */
+import { type MemoryBackend, type MemoryEntry, type MemoryEntryFrontmatter, type NotePatch, type PatchReport } from "@sema-agent/core";
+import type { MemoryHistoryAppendRow } from "./memory-sync-store-pg.js";
+/** `applyPatches` 的第二参 —— 从 core 的 `MemoryBackend` 接口推导,不手抄。 */
+export type SqlApplyOpts = NonNullable<Parameters<MemoryBackend["applyPatches"]>[1]>;
+export type SqlPatchConflict = PatchReport["conflicts"][number];
+/** 计划读到的一行已提交 entry(frontmatter 已解码)。 */
+export interface SqlEntryRow {
+    readonly scope: string;
+    readonly slug: string;
+    readonly rev: string;
+    readonly frontmatter: MemoryEntryFrontmatter;
+}
+/** 判的两只读口(方言自供)。 */
+export interface SqlEntryReads {
+    rowOf(id: string): Promise<SqlEntryRow | undefined>;
+    /** 占着 `(scope, slug)` 的 id(唯一键 ⇒ 至多一个;数组形让叠层视图能并入计划中的行)。 */
+    idsAt(scope: string, slug: string): Promise<readonly string[]>;
+}
+/** 一个拼写在库里的位置(写语句绑定的投影)。 */
+export interface SqlProjection {
+    readonly scope: string;
+    readonly slug: string;
+}
+/** add 的写入单:`stored` = 终拼形(含后缀)。`prior` = 计划时这个 id 的行所在的投影(缺席 = 计划时没有这一行):写语句只覆盖仍在那里的行,
+ *  没有 prior 时只插入 —— 行在判与写之间被挪走 / 被别的副本插入都答 `moved`。 */
+export interface SqlAddWrite {
+    readonly stored: MemoryEntry;
+    readonly rev: string;
+    readonly prior: SqlProjection | undefined;
+}
+/** update 的写入单:条件 = 判过的 rev **且**判过的投影 `current`。 */
+export interface SqlUpdateWrite {
+    readonly entry: MemoryEntry;
+    readonly rev: string;
+    readonly currentRev: string;
+    readonly current: SqlProjection;
+    readonly baseRev: string | undefined;
+}
+/** delete 的写入单:条件同 update。 */
+export interface SqlDeleteWrite {
+    readonly id: string;
+    readonly currentRev: string;
+    readonly current: SqlProjection;
+    readonly baseRev: string | undefined;
+}
+/**
+ * 一次写的结局:`committed` = 落了;`slug-taken` = 唯一键 `(scope, slug)` 冲突(名在计划之后被别的副本占了);`moved` = 写不落而现读显示
+ * 这个 id 的行已不在计划的投影上(或计划时没有、现在有了);`lost` = rev CAS 输了(冲突里的 currentRev 是现值)。
+ */
+export type SqlWriteOutcome = {
+    readonly kind: "committed";
+} | {
+    readonly kind: "slug-taken";
+} | {
+    readonly kind: "moved";
+} | {
+    readonly kind: "lost";
+    readonly conflict: SqlPatchConflict;
+};
+/**
+ * 方言写口。每只都必须在它发出的**每条** entry 写语句之前同步调 `confirm()`(中间不许有 await);只把「这条写没落成」的形翻译成结局,
+ * 其余 I/O 失败原样抛。`prepare` 在一个 patch 第一次要写之前调一次,结果交给它的每一次写(撞名 / 被挪重试不重算 —— PG 的向量)。
+ */
+export interface SqlEntryWrites<P> {
+    prepare(entry: MemoryEntry): Promise<P>;
+    add(w: SqlAddWrite, prepared: P, confirm: () => void): Promise<SqlWriteOutcome>;
+    update(w: SqlUpdateWrite, prepared: P, confirm: () => void): Promise<SqlWriteOutcome>;
+    remove(w: SqlDeleteWrite, confirm: () => void): Promise<SqlWriteOutcome>;
+}
+/** 一只 SQL 腿交给驱动器的全部东西。 */
+export interface SqlMemoryLeg<P> {
+    readonly reads: SqlEntryReads;
+    readonly writes: SqlEntryWrites<P>;
+    /** 本方言的 `unstorable_bytes` 拒绝文案(两方言措辞不同,判据同一只 `pgHasUnstorable`)。 */
+    readonly unstorableReason: string;
+    /** history 行的落笔时刻(只在 `appendHistory` 在场时调,与改前的时钟调用次数同)。 */
+    readonly now: () => number;
+    /** best-effort history 冲刷(自己吞错计数,永不抛);缺席 ⇒ 不攒 history 行。 */
+    readonly appendHistory?: (rows: readonly MemoryHistoryAppendRow[]) => Promise<void>;
+}
+/** 两只 SQL 腿的 `applyPatches`。读法见文件头注。 */
+export declare function applySqlPatches<P>(patches: readonly NotePatch[], opts: SqlApplyOpts | undefined, leg: SqlMemoryLeg<P>): Promise<PatchReport>;
+//# sourceMappingURL=memory-engine-sql-apply.d.ts.map