@sema-agent/server 7.144.0 → 7.146.0

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

@@ -1,10 +1,10 @@
 import { jaccardDistance, termSet } from "@sema-agent/core";
 import { readFrontmatterColumn } from "./memory-engine-vector-util.js";
 import { decodeJsonColumn, foldJsonColumn, jsonColumnText } from "./sql-json-column.js";
-import { computeEntryRev, serializeEntryFile } from "@sema-agent/core";
-import { pgHasUnstorable } from "./pg-safe-json.js";
-import { assertMemoryScopeWidth, memoryEntryKeyWidthRefusal } from "./memory-key-guards.js";
-import { ambiguousOriginRefusal, createBatchCommittedBaseline, exposureBandOf, exposureCarriage, originWhitewashRefusal, rememberBatchCommitted, distilledWhitewashRefusal, distilledCarriage, unknownPatchOpRefusal, } from "./memory-origin-law.js";
+import { serializeEntryFile } from "@sema-agent/core";
+import { assertMemoryScopeWidth } from "./memory-key-guards.js";
+import { exposureBandOf, exposureCarriage, distilledCarriage } from "./memory-origin-law.js";
+import { applySqlPatches, } from "./memory-engine-sql-apply.js";
 import { isMysqlDupKeyError } from "./sql-errors.js";
 import { ensureIndexes } from "./ensure-index.js";
 import { MEMORY_ENGINE_INDEXES, PG_MEMORY_ENGINE_TABLES } from "./memory-engine-pg.js";
@@ -40,6 +40,7 @@ const isDupEntry = isMysqlDupKeyError;
 function isPrimaryKeyDup(err) {
     return isDupEntry(err) && /for key '[^']*PRIMARY'/i.test(String(err.message ?? ""));
 }
+const AT_PLANNED_PROJECTION = "CAST(scope AS BINARY) = CAST(? AS BINARY) AND CAST(slug AS BINARY) = CAST(? AS BINARY)";
 function inPlaceholders(count) {
     return Array.from({ length: count }, () => "?").join(", ");
 }
@@ -56,6 +57,7 @@ export class TiDBMemoryEngineBackend {
     clock;
     history;
     historyRowsLost = 0;
+    leg;
     get vectorMode() {
         return "lexical";
     }
@@ -66,6 +68,18 @@ export class TiDBMemoryEngineBackend {
         }
         this.clock = opts.now ?? Date.now;
         this.history = opts.history;
+        this.leg = {
+            reads: { rowOf: (id) => this.rowOf(id), idsAt: (scope, slug) => this.idsAt(scope, slug) },
+            writes: {
+                prepare: async () => undefined,
+                add: (w, prepared, confirm) => this.writeAdd(w, prepared, confirm),
+                update: (w, prepared, confirm) => this.writeUpdate(w, prepared, confirm),
+                remove: (w, confirm) => this.writeDelete(w, confirm),
+            },
+            unstorableReason: "unstorable_bytes (utf8mb4 cannot store NUL/lone surrogates without mangling; strip them at the source — the store never rewrites content)",
+            now: () => this.clock(),
+            ...(this.history !== undefined ? { appendHistory: (rows) => this.appendHistory(rows) } : {}),
+        };
     }
     async selectRows(sql, params) {
         const [rows] = await this.pool.query(sql, params);
@@ -141,242 +155,98 @@ export class TiDBMemoryEngineBackend {
         scored.sort((a, b) => (bands ? exposureBandOf(a) - exposureBandOf(b) : 0) || a.score - b.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
         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(`TiDBMemoryEngineBackend: 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 rows = await this.selectRows(`SELECT slug, rev, scope, ${jsonColumnText("mysql", "frontmatter")} FROM ${TIDB_MEMORY_ENGINE_TABLES.entry} WHERE id = ?`, [id]);
+        const r = 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 applyOne(patch, report, plannedSlugs, historyRows, originBaseline) {
+    async idsAt(scope, slug) {
+        const rows = await this.selectRows(`SELECT id FROM ${TIDB_MEMORY_ENGINE_TABLES.entry} WHERE scope = ? AND slug = ?`, [scope, slug]);
+        return rows.map((r) => String(r.id));
+    }
+    async freshRow(id) {
+        const rows = await this.selectRows(`SELECT rev, scope, slug FROM ${TIDB_MEMORY_ENGINE_TABLES.entry} WHERE id = ?`, [id]);
+        const r = rows[0];
+        return r === undefined ? undefined : { rev: String(r.rev), scope: String(r.scope), slug: String(r.slug) };
+    }
+    async writeAdd({ stored, rev, prior }, _prepared, confirm) {
         const T = TIDB_MEMORY_ENGINE_TABLES.entry;
-        {
-            const refusal = unknownPatchOpRefusal(patch.op);
-            if (refusal !== undefined) {
-                report.conflicts.push({ op: patch.op, id: patch.id, reason: refusal });
-                return;
-            }
-        }
-        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;
-        }
-        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 entry = patch.entry;
-            if (!entry) {
-                report.conflicts.push({ op: "add", id: patch.id, reason: "add patch without an entry" });
-                return;
-            }
-            if (pgHasUnstorable(entry.frontmatter) || pgHasUnstorable(entry.body) || pgHasUnstorable(entry.slug)) {
-                report.conflicts.push({ op: "add", id: entry.id, reason: "unstorable_bytes (utf8mb4 cannot store NUL/lone surrogates without mangling; strip them at the source — the store never rewrites content)" });
-                return;
-            }
-            const prior = await this.selectRows(`SELECT scope, slug, rev, ${jsonColumnText("mysql", "frontmatter")} FROM ${T} WHERE id = ?`, [entry.id]);
-            const priorRow = prior.length > 0 ? prior[0] : undefined;
-            let existsById = priorRow !== 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;
-                }
-            }
-            let slug = entry.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.selectRows(`SELECT id FROM ${T} WHERE scope = ? AND slug = ?`, [entry.scope, slug]);
-                    const otherId = taken.find((r) => String(r.id) !== entry.id);
-                    if (!otherId) {
-                        const stored = { ...entry, slug };
-                        const rev = computeEntryRev(stored);
-                        const sizeBytes = Buffer.byteLength(serializeEntryFile(stored), "utf8");
-                        try {
-                            if (existsById) {
-                                const res = await this.write(`UPDATE ${T} SET scope = ?, slug = ?, frontmatter = ?, body = ?, rev = ?, mtime_ms = ?, size_bytes = ?, embedding = NULL WHERE id = ?`, [stored.scope, stored.slug, JSON.stringify(stored.frontmatter), stored.body, rev, this.clock(), sizeBytes, stored.id]);
-                                if (res.affectedRows === 0) {
-                                    const still = await this.selectRows(`SELECT id FROM ${T} WHERE id = ?`, [stored.id]);
-                                    if (still.length === 0) {
-                                        existsById = false;
-                                        continue;
-                                    }
-                                }
-                            }
-                            else {
-                                await this.write(`INSERT INTO ${T} (id, scope, slug, frontmatter, body, rev, mtime_ms, size_bytes, embedding) VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL)`, [stored.id, stored.scope, stored.slug, JSON.stringify(stored.frontmatter), stored.body, rev, this.clock(), sizeBytes]);
-                            }
+        const sizeBytes = Buffer.byteLength(serializeEntryFile(stored), "utf8");
+        let overwrite = prior;
+        for (;;) {
+            try {
+                if (overwrite !== undefined) {
+                    const params = [stored.scope, stored.slug, JSON.stringify(stored.frontmatter), stored.body, rev, this.clock(), sizeBytes, stored.id, overwrite.scope, overwrite.slug];
+                    confirm();
+                    const res = await this.write(`UPDATE ${T} SET scope = ?, slug = ?, frontmatter = ?, body = ?, rev = ?, mtime_ms = ?, size_bytes = ?, embedding = NULL WHERE id = ? AND ${AT_PLANNED_PROJECTION}`, params);
+                    if (res.affectedRows === 0) {
+                        const fresh = await this.freshRow(stored.id);
+                        if (fresh === undefined) {
+                            overwrite = undefined;
+                            continue;
                         }
-                        catch (err) {
-                            if (isDupEntry(err)) {
-                                if (isPrimaryKeyDup(err)) {
-                                    existsById = true;
-                                    continue;
-                                }
-                                slug = `${entry.slug}-${n}`;
-                                continue;
-                            }
-                            throw err;
+                        if (fresh.scope !== overwrite.scope || fresh.slug !== overwrite.slug)
+                            return { kind: "moved" };
+                        if (fresh.rev !== rev) {
+                            throw new Error(`memory-engine: the add of ${JSON.stringify(stored.id)} wrote no row, yet the row is still at the planned projection with other content — refusing to report it either way`);
                         }
-                        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.selectRows(`SELECT slug, rev, scope, ${jsonColumnText("mysql", "frontmatter")} FROM ${T} WHERE id = ?`, [patch.id]);
-        if (cur.length === 0) {
-            report.conflicts.push({ op: patch.op, id: patch.id, reason: "unknown id (entry not found in backend)" });
-            return;
-        }
-        const currentRev = String(cur[0].rev);
-        const currentSlug = String(cur[0].slug);
-        const currentScope = String(cur[0].scope);
-        const committedFm = readFrontmatter(cur[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;
+                else {
+                    const params = [stored.id, stored.scope, stored.slug, JSON.stringify(stored.frontmatter), stored.body, rev, this.clock(), sizeBytes];
+                    confirm();
+                    await this.write(`INSERT INTO ${T} (id, scope, slug, frontmatter, body, rev, mtime_ms, size_bytes, embedding) VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL)`, params);
                 }
             }
-            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.write(`DELETE FROM ${T} WHERE id = ? AND rev = ?`, [patch.id, currentRev]);
-            if (res.affectedRows === 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;
+            catch (err) {
+                if (!isDupEntry(err))
+                    throw err;
+                return isPrimaryKeyDup(err) ? { kind: "moved" } : { kind: "slug-taken" };
             }
-            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;
+            return { kind: "committed" };
         }
-        if (pgHasUnstorable(entry.frontmatter) || pgHasUnstorable(entry.body) || pgHasUnstorable(entry.slug)) {
-            report.conflicts.push({ op: "update", id: patch.id, reason: "unstorable_bytes (utf8mb4 cannot store NUL/lone surrogates without mangling; strip them at the source — the store never rewrites content)" });
+    }
+    async writeUpdate({ entry, rev, currentRev, current, baseRev }, _prepared, confirm) {
+        const params = [entry.scope, entry.slug, JSON.stringify(entry.frontmatter), entry.body, rev, this.clock(), Buffer.byteLength(serializeEntryFile(entry), "utf8"), entry.id, currentRev, current.scope, current.slug];
+        confirm();
+        const res = await this.write(`UPDATE ${TIDB_MEMORY_ENGINE_TABLES.entry} SET scope = ?, slug = ?, frontmatter = ?, body = ?, rev = ?, mtime_ms = ?, size_bytes = ?, embedding = NULL WHERE id = ? AND rev = ? AND ${AT_PLANNED_PROJECTION}`, params);
+        if (res.affectedRows > 0)
+            return { kind: "committed" };
+        const fresh = await this.freshRow(entry.id);
+        const atPlanned = fresh !== undefined && fresh.rev === currentRev && fresh.scope === current.scope && fresh.slug === current.slug;
+        const writesNothingNew = rev === currentRev && entry.scope === current.scope && entry.slug === current.slug;
+        if (atPlanned && writesNothingNew)
+            return { kind: "committed" };
+        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.write(`DELETE FROM ${TIDB_MEMORY_ENGINE_TABLES.entry} WHERE id = ? AND rev = ? AND ${AT_PLANNED_PROJECTION}`, [id, currentRev, current.scope, current.slug]);
+        if (res.affectedRows > 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);
         }
-        const rev = computeEntryRev(entry);
-        const res = await this.write(`UPDATE ${T} SET scope = ?, slug = ?, frontmatter = ?, body = ?, rev = ?, mtime_ms = ?, size_bytes = ?, embedding = NULL WHERE id = ? AND rev = ?`, [entry.scope, entry.slug, JSON.stringify(entry.frontmatter), entry.body, rev, this.clock(), Buffer.byteLength(serializeEntryFile(entry), "utf8"), entry.id, currentRev]);
-        if (res.affectedRows === 0) {
-            const fresh = await this.freshRevOrMissing(entry.id);
-            if (fresh === rev) {
-                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() });
-                return;
-            }
-            report.conflicts.push({ op: "update", id: patch.id, reason: "rev mismatch (concurrent change)", baseRev: patch.baseRev, currentRev: fresh ?? currentRev });
-            return;
+        catch (err) {
+            this.historyRowsLost += rows.length;
+            console.warn(`TiDBMemoryEngineBackend: 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 freshRevOrMissing(id) {
-        const rows = await this.selectRows(`SELECT rev FROM ${TIDB_MEMORY_ENGINE_TABLES.entry} WHERE id = ?`, [id]);
-        return rows.length > 0 ? String(rows[0].rev) : undefined;
-    }
-    async freshRev(id, fallback) {
-        return (await this.freshRevOrMissing(id)) ?? fallback;
     }
     async getConsolidationCursor(scope) {
         const rows = await this.selectRows(`SELECT \`cursor\` FROM ${TIDB_MEMORY_ENGINE_TABLES.cursor} WHERE scope = ?`, [scope]);

package/dist/plugins/memory-key-guards.d.ts

@@ -22,7 +22,7 @@ export declare const MEMORY_SYNC_PEER_COLUMN_CHARS = 190;
 export declare function assertSlugWidth(slug: string): void;
 export declare function assertMemoryScopeWidth(scope: string): void;
 /**
- * 一个 entry 写(add / update)的两个键宽一起判 —— 两方言的 `applyOne` 在**任何 I/O 之前**调用它。
+ * 一个 entry 写(add / update)的两个键宽一起判 —— 两方言共用的判(`memory-engine-sql-apply.ts` 的 `planSqlPatch`)在**任何 I/O 之前**调用它。
  *
  * 为什么两条腿共用一个入口而不是各自展开:add 与 update 写的是**同两列**(update 的
  * `SET scope = …, slug = …` 会改盘也会改名),R5 那批只护住了 add ⇒ 一次改名就能把超宽 slug 送进

package/dist/plugins/memory-origin-law.d.ts

@@ -30,8 +30,8 @@
  * ① **判据本身**({@link originWhitewashRefusal}):`committedOriginOf` / `originEquals` 都用 core 的
  *    导出实现,**不重写** —— 它们要处理 `frontmatter.origin` 与「保留在 `extra` 里的 origin 形字节块」
  *    两种承载形(legacy / 外来),自己写一份近似的等于给洗白留一条旁路。
- * ② **批次基线**({@link rememberBatchOrigin}):两支 SQL 后端逐条 patch 直打真库(没有 File backend
- *    那种「先规划整批再落盘」的阶段),所以同批 `delete` 之后再 `add` 时,库里已经没有那一行了 ——
+ * ② **批次基线**({@link rememberBatchCommitted}):两支 SQL 后端的提交阶段逐条 patch 现判、直打真库(落点问询的
+ *    计划阶段只是只读预测,不是 File backend 那种「先规划整批再落盘」),所以同批 `delete` 之后再 `add` 时,库里已经没有那一行了 ——
  *    只看当下的库会把它误判成合法新生命。基线 map 按**本批第一次触碰**记下该 id 的已提交 origin,
  *    之后同批的任何 op 都按那一份判。⇒「同批 delete+re-add 拒 / 已提交墓碑后 add 放」这条分界
  *    (core 契约逐字要求的那条)才成立。
@@ -128,7 +128,7 @@ export declare function rememberBatchCommitted(baseline: BatchCommittedBaseline,
 /**
  * 未知 op 拼写的**前置**拒绝(codex R1-[high],验真后采纳;**既有**缺口,不是本批引入)。
  *
- * 病:两支 SQL 后端的 `applyOne` 形状是「`if (op === "add") {…}` → 落到 update/delete 段」,而段内
+ * 病:两支 SQL 后端当时各一份的 `applyOne`(今两腿共用的判 `memory-engine-sql-apply.ts` 的 `planSqlPatch`)形状是「`if (op === "add") {…}` → 落到 update/delete 段」,而段内
  * 的两道白洗守卫(repo_file provenance / 本模块的 origin 不可变律)都写成 `if (patch.op === "update")`。
  * ⇒ 一个**词表外**的 op(`"upsert"` / 打错的字 / 将来 core 加的新词)会:跳过两道守卫 → 走到 update
  * 的 SQL → 把行改掉 → 在 `report.applied` 里报成一次 update。TypeScript 的联合型是**编译期**的,

package/dist/plugins/memory-run-store.d.ts

@@ -57,6 +57,8 @@ export declare class MemoryRunStore implements InProcessClaimFence {
     bindIdemBodyFingerprint(taskId: string, idem: RunIdemBinding): Promise<string | null>;
     /** The run a submission's scoped `Idempotency-Key` names, if any. */
     getRunByIdem(idemKey: string): Promise<RunRecord | undefined>;
+    /** run 行预览的写一次补写(SQL 孪生同义:列仍是 null 才写,建行写过 / 已补过的不动;行不在 ⇒ 无事)。 */
+    fillObjectivePreview(taskId: string, preview: string): Promise<void>;
     requestCancel(taskId: string, owner: string | null): Promise<boolean>;
     isCancelRequested(taskId: string, owner: string | null): Promise<boolean>;
     requestPreempt(taskId: string, owner: string | null): Promise<boolean>;

package/dist/plugins/memory-run-store.js

@@ -109,6 +109,12 @@ export class MemoryRunStore {
         const r = taskId !== undefined ? this.runs.get(taskId) : undefined;
         return r ? this.toRecord(r) : undefined;
     }
+    async fillObjectivePreview(taskId, preview) {
+        const r = this.runs.get(taskId);
+        if (!r || r.objectivePreview !== null)
+            return;
+        r.objectivePreview = preview;
+    }
     async requestCancel(taskId, owner) {
         const r = this.runs.get(taskId);
         if (!r || !ownerEq(r.owner, owner) || r.status !== "running")