@sema-agent/server 7.145.0 → 7.147.0

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

@@ -0,0 +1,130 @@
+/**
+ * 两只 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 盲覆盖)。
+ * · 写条件只有一条律:写语句绑住**判据用到的那一份** —— update / delete 判的是 rev(CAS)与投影 ⇒ 两者都绑;add 覆盖判的是投影
+ *   (落点),`guard: "absent"` 再判「恰是这一份」⇒ 再绑 rev;add 插入判的是「没有这一行」⇒ 只插入。裸 add 的判不看内容(幂等覆盖现值),
+ *   写也不绑 rev。库给的「没落」一律回到判(update / delete 的 rev 变了 = CAS 输,add = 重判)。
+ */
+import { type MemoryBackend, type MemoryEntry, type MemoryEntryFrontmatter, type NotePatch, type PatchReport } from "@sema-agent/core";
+import type { MemoryHistoryAppendRow } from "./memory-sync-store-pg.js";
+/** `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 覆盖的写条件:投影恒绑;`rev` 只在判据用到了它时在场(`guard: "absent"` 判的是「恰是这一份」),裸 add 的判不看内容 ⇒ `undefined`。 */
+export interface SqlAddPrior extends SqlProjection {
+    readonly rev: string | undefined;
+}
+/** add 的写入单:`stored` = 终拼形(含后缀)。`prior` = 计划时这个 id 的那一行要绑住的部分(缺席 = 计划时没有这一行):写语句只覆盖仍在
+ *  那里(且带 `rev` 时仍是那一份内容)的行,没有 prior 时只插入 —— 行在判与写之间被挪走 / 被改写(带 `rev` 时)/ 被别的副本插入都答 `moved`
+ *  (驱动器按现状重判:`guard: "absent"` 照判 —— 行已在且不是这一份内容 ⇒ `add_guard_absent_conflict`)。add-if-absent 因此是原子的:
+ *  「判时没有」与「判时恰是这一份」两个前提都随写语句一起交给库判,判与写之间的并发写者不会被静默覆盖。 */
+export interface SqlAddWrite {
+    readonly stored: MemoryEntry;
+    readonly rev: string;
+    readonly prior: SqlAddPrior | 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

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

@@ -0,0 +1,358 @@
+import { LandingsNeedAdmission, admittingLandings, computeEntryRev, requireLandingsAdmitted, } from "@sema-agent/core";
+import { memoryEntryKeyWidthRefusal } from "./memory-key-guards.js";
+import { pgHasUnstorable } from "./pg-safe-json.js";
+import { ambiguousOriginRefusal, createBatchCommittedBaseline, distilledWhitewashRefusal, originWhitewashRefusal, rememberBatchCommitted, unknownPatchOpRefusal, } from "./memory-origin-law.js";
+const FIRST_SUFFIX_STEP = 2;
+const candidateAt = (slug, n) => (n === FIRST_SUFFIX_STEP ? slug : `${slug}-${n - 1}`);
+const slugKey = (scope, slug) => JSON.stringify([scope, slug]);
+const distinctLandings = (ls) => {
+    const seen = new Set();
+    return ls.filter((l) => {
+        const key = slugKey(l.scope, l.slug);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+};
+const unadmittedOf = (admitted, landings) => {
+    try {
+        requireLandingsAdmitted(admitted, landings);
+        return [];
+    }
+    catch (err) {
+        if (err instanceof LandingsNeedAdmission)
+            return err.landings;
+        throw err;
+    }
+};
+async function planSqlPatch(patch, reads, baseline, claims, unstorableReason, suffixFrom) {
+    const conflict = (c) => ({ kind: "conflict", conflict: c });
+    const unknownOp = unknownPatchOpRefusal(patch.op);
+    if (unknownOp !== undefined)
+        return conflict({ op: patch.op, id: patch.id, reason: unknownOp });
+    if (patch.op !== "delete" && patch.entry !== undefined && patch.entry.id !== patch.id) {
+        return conflict({ op: patch.op, id: patch.id, reason: `patch id ${JSON.stringify(patch.id)} != entry id ${JSON.stringify(patch.entry.id)} (malformed patch refused)` });
+    }
+    if (patch.op !== "delete" && patch.entry !== undefined) {
+        const refusal = memoryEntryKeyWidthRefusal(patch.entry.scope, patch.entry.slug);
+        if (refusal !== undefined)
+            return conflict({ op: patch.op, id: patch.id, reason: refusal });
+    }
+    if (patch.op !== "delete" && patch.entry !== undefined) {
+        const refusal = ambiguousOriginRefusal(patch.entry.frontmatter);
+        if (refusal !== undefined)
+            return conflict({ op: patch.op, id: patch.id, reason: refusal });
+    }
+    if (patch.op === "add") {
+        const entry = patch.entry;
+        if (!entry)
+            return conflict({ op: "add", id: patch.id, reason: "add patch without an entry" });
+        if (pgHasUnstorable(entry.frontmatter) || pgHasUnstorable(entry.body) || pgHasUnstorable(entry.slug)) {
+            return conflict({ op: "add", id: entry.id, reason: unstorableReason });
+        }
+        const prior = await reads.rowOf(entry.id);
+        const baseFm = rememberBatchCommitted(baseline, entry.id, prior?.frontmatter);
+        const originRefusal = originWhitewashRefusal("add", baseFm, entry.frontmatter);
+        if (originRefusal !== undefined)
+            return conflict({ op: "add", id: entry.id, reason: originRefusal });
+        const distilledRefusal = distilledWhitewashRefusal("add", baseFm, entry.frontmatter);
+        if (distilledRefusal !== undefined)
+            return conflict({ op: "add", id: entry.id, reason: distilledRefusal });
+        if (patch.guard === "absent" && prior !== undefined) {
+            if (prior.rev !== computeEntryRev(entry)) {
+                return conflict({ op: "add", id: entry.id, reason: "add_guard_absent_conflict (id already exists at a different rev; add-if-absent refuses to overwrite)", currentRev: prior.rev });
+            }
+            if (prior.scope !== entry.scope || prior.slug !== entry.slug) {
+                return conflict({
+                    op: "add",
+                    id: entry.id,
+                    reason: `add_guard_absent_conflict (id already exists at the same rev but a different projection ${JSON.stringify(`${prior.scope}/${prior.slug}`)}; add-if-absent refuses to duplicate)`,
+                    currentRev: prior.rev,
+                });
+            }
+        }
+        if (prior !== undefined && prior.scope !== entry.scope) {
+            return conflict({ op: "add", id: entry.id, reason: `id already exists in scope ${JSON.stringify(prior.scope)} (cross-scope add refused)` });
+        }
+        let n = suffixFrom;
+        let slug = candidateAt(entry.slug, n);
+        for (;; n++, slug = candidateAt(entry.slug, n)) {
+            const derivedRefusal = memoryEntryKeyWidthRefusal(entry.scope, slug);
+            if (derivedRefusal !== undefined) {
+                return conflict({ op: "add", id: entry.id, reason: `${derivedRefusal} (slug collision suffix "-${n - 1}" no longer fits the column — shorten the entry name)` });
+            }
+            if (!claims.has(slugKey(entry.scope, slug)) && !(await reads.idsAt(entry.scope, slug)).some((id) => id !== entry.id))
+                break;
+        }
+        const stored = { ...entry, slug };
+        const landings = [];
+        if (prior !== undefined && prior.slug !== slug)
+            landings.push({ id: entry.id, scope: prior.scope, slug: prior.slug });
+        landings.push({ id: entry.id, scope: entry.scope, slug });
+        return {
+            kind: "add",
+            stored,
+            rev: computeEntryRev(stored),
+            prior: prior !== undefined ? { scope: prior.scope, slug: prior.slug, rev: patch.guard === "absent" ? prior.rev : undefined } : undefined,
+            frontmatter: entry.frontmatter,
+            suffixAt: n,
+            landings,
+        };
+    }
+    const current = await reads.rowOf(patch.id);
+    if (current === undefined)
+        return conflict({ op: patch.op, id: patch.id, reason: "unknown id (entry not found in backend)" });
+    const baseFm = rememberBatchCommitted(baseline, patch.id, current.frontmatter);
+    if (patch.op === "update" && patch.entry !== undefined) {
+        if (current.frontmatter.provenance?.kind === "repo_file") {
+            const next = patch.entry.frontmatter;
+            const stripsProvenance = next.provenance === undefined;
+            const stripsTrust = current.frontmatter.trust !== undefined && next.trust === undefined;
+            if (stripsProvenance || stripsTrust) {
+                return conflict({
+                    op: "update",
+                    id: patch.id,
+                    reason: `repo_file provenance whitewash refused: update drops ${stripsProvenance ? "provenance" : "trust"} from a repo-ingested entry (malformed patch refused)`,
+                });
+            }
+        }
+        const originRefusal = originWhitewashRefusal("update", baseFm, patch.entry.frontmatter);
+        if (originRefusal !== undefined)
+            return conflict({ op: "update", id: patch.id, reason: originRefusal });
+        const distilledRefusal = distilledWhitewashRefusal("update", baseFm, patch.entry.frontmatter);
+        if (distilledRefusal !== undefined)
+            return conflict({ op: "update", id: patch.id, reason: distilledRefusal });
+    }
+    if (patch.baseRev !== undefined && patch.baseRev !== current.rev) {
+        return conflict({ op: patch.op, id: patch.id, reason: "rev mismatch (concurrent change)", baseRev: patch.baseRev, currentRev: current.rev });
+    }
+    const at = { scope: current.scope, slug: current.slug };
+    if (patch.op === "delete") {
+        return { kind: "delete", id: patch.id, currentRev: current.rev, current: at, baseRev: patch.baseRev, landings: [{ id: patch.id, ...at }] };
+    }
+    const entry = patch.entry;
+    if (!entry)
+        return conflict({ op: "update", id: patch.id, reason: "update patch without an entry" });
+    if (pgHasUnstorable(entry.frontmatter) || pgHasUnstorable(entry.body) || pgHasUnstorable(entry.slug)) {
+        return conflict({ op: "update", id: patch.id, reason: unstorableReason });
+    }
+    const moves = current.scope !== entry.scope || current.slug !== entry.slug;
+    return {
+        kind: "update",
+        entry,
+        rev: computeEntryRev(entry),
+        currentRev: current.rev,
+        current: at,
+        baseRev: patch.baseRev,
+        landings: [...(moves ? [{ id: patch.id, ...at }] : []), { id: entry.id, scope: entry.scope, slug: entry.slug }],
+    };
+}
+class CallerThrow extends Error {
+    thrown;
+    constructor(thrown) {
+        super("caller confirm threw");
+        this.thrown = thrown;
+    }
+}
+function duplicatePositions(patches) {
+    const seen = new Set();
+    const dup = new Set();
+    patches.forEach((p, i) => {
+        if (p.op === "delete")
+            return;
+        if (seen.has(p.id))
+            dup.add(i);
+        else
+            seen.add(p.id);
+    });
+    return dup;
+}
+async function predictLandings(patches, from, duplicateAt, reads, unstorableReason, baseline, claims, suffixFloor) {
+    const overlay = new Map();
+    const view = {
+        rowOf: async (id) => (overlay.has(id) ? (overlay.get(id) ?? undefined) : reads.rowOf(id)),
+        idsAt: async (scope, slug) => {
+            const ids = (await reads.idsAt(scope, slug)).filter((id) => !overlay.has(id));
+            for (const [id, row] of overlay)
+                if (row !== null && row.scope === scope && row.slug === slug)
+                    ids.push(id);
+            return ids;
+        },
+    };
+    const scratchBaseline = new Map(baseline);
+    const scratchClaims = new Set(claims);
+    const landings = [];
+    for (let i = from; i < patches.length; i++) {
+        if (duplicateAt.has(i))
+            continue;
+        let plan;
+        let targetHeld = false;
+        try {
+            plan = await planSqlPatch(patches[i], view, scratchBaseline, scratchClaims, unstorableReason, suffixFloor.get(i) ?? FIRST_SUFFIX_STEP);
+            if (plan.kind === "update") {
+                const { id, scope, slug } = plan.entry;
+                targetHeld = (await view.idsAt(scope, slug)).some((holder) => holder !== id);
+            }
+        }
+        catch {
+            continue;
+        }
+        if (plan.kind === "conflict")
+            continue;
+        landings.push(...plan.landings);
+        if (plan.kind === "add") {
+            overlay.set(plan.stored.id, { scope: plan.stored.scope, slug: plan.stored.slug, rev: plan.rev, frontmatter: plan.frontmatter });
+            scratchClaims.add(slugKey(plan.stored.scope, plan.stored.slug));
+        }
+        else if (plan.kind === "update") {
+            if (!targetHeld)
+                overlay.set(plan.entry.id, { scope: plan.entry.scope, slug: plan.entry.slug, rev: plan.rev, frontmatter: plan.entry.frontmatter });
+        }
+        else {
+            overlay.set(plan.id, null);
+        }
+    }
+    return landings;
+}
+function movedAfterAdmission(patch, unasked) {
+    const l = unasked[0];
+    return {
+        op: patch.op,
+        id: patch.id,
+        reason: `landing moved after admission (${JSON.stringify(`${l.scope}/${l.slug}`)} was not admitted: a concurrent writer moved the entry or took the name after this batch was asked about and began writing); not written — the next apply asks about it again`,
+    };
+}
+export async function applySqlPatches(patches, opts, leg) {
+    const report = { applied: [], conflicts: [] };
+    const duplicateAt = duplicatePositions(patches);
+    const baseline = createBatchCommittedBaseline();
+    const claims = new Set();
+    const suffixFloor = new Map();
+    const history = [];
+    const preparedAt = new Map();
+    const admit = opts?.admit;
+    let mayHaveWritten = false;
+    const callerConfirm = opts?.confirm;
+    const confirm = () => {
+        if (callerConfirm === undefined)
+            return;
+        try {
+            callerConfirm();
+        }
+        catch (thrown) {
+            throw new CallerThrow(thrown);
+        }
+    };
+    const record = (plan) => {
+        if (plan.kind === "add") {
+            claims.add(slugKey(plan.stored.scope, plan.stored.slug));
+            report.applied.push({ op: "add", id: plan.stored.id, slug: plan.stored.slug });
+            if (leg.appendHistory)
+                history.push({ id: plan.stored.id, rev: plan.rev, op: "add", scope: plan.stored.scope, snapshot: { ...plan.stored, rev: plan.rev }, writtenAtMs: leg.now() });
+        }
+        else if (plan.kind === "update") {
+            report.applied.push({ op: "update", id: plan.entry.id, slug: plan.entry.slug });
+            if (leg.appendHistory)
+                history.push({ id: plan.entry.id, rev: plan.rev, prevRev: plan.currentRev, op: "update", scope: plan.entry.scope, snapshot: { ...plan.entry, rev: plan.rev }, writtenAtMs: leg.now() });
+        }
+        else {
+            report.applied.push({ op: "delete", id: plan.id, slug: plan.current.slug });
+            if (leg.appendHistory)
+                history.push({ id: plan.id, rev: `tombstone:${plan.currentRev}`, prevRev: plan.currentRev, op: "delete", scope: plan.current.scope, writtenAtMs: leg.now() });
+        }
+    };
+    const predictFrom = (from) => predictLandings(patches, from, duplicateAt, leg.reads, leg.unstorableReason, baseline, claims, suffixFloor);
+    const commitOne = async (patch, k, admitted) => {
+        let issued = false;
+        const confirmThenIssue = () => {
+            confirm();
+            issued = true;
+        };
+        try {
+            for (;;) {
+                issued = false;
+                const plan = await planSqlPatch(patch, leg.reads, baseline, claims, leg.unstorableReason, suffixFloor.get(k) ?? FIRST_SUFFIX_STEP);
+                if (plan.kind === "conflict") {
+                    report.conflicts.push(plan.conflict);
+                    return [];
+                }
+                if (admitted !== undefined) {
+                    const unasked = unadmittedOf(admitted, plan.landings);
+                    if (unasked.length > 0)
+                        return unasked;
+                }
+                let outcome;
+                if (plan.kind === "delete")
+                    outcome = await leg.writes.remove(plan, confirmThenIssue);
+                else {
+                    let prepared = preparedAt.get(k);
+                    if (prepared === undefined) {
+                        prepared = { value: await leg.writes.prepare(patch.entry) };
+                        preparedAt.set(k, prepared);
+                    }
+                    outcome = plan.kind === "add" ? await leg.writes.add(plan, prepared.value, confirmThenIssue) : await leg.writes.update(plan, prepared.value, confirmThenIssue);
+                }
+                switch (outcome.kind) {
+                    case "committed":
+                        mayHaveWritten = true;
+                        record(plan);
+                        return [];
+                    case "lost":
+                        report.conflicts.push(outcome.conflict);
+                        return [];
+                    case "slug-taken":
+                        if (plan.kind === "add")
+                            suffixFloor.set(k, plan.suffixAt + 1);
+                        continue;
+                    case "moved":
+                        continue;
+                    default: {
+                        const unknown = outcome;
+                        throw new Error(`unknown write outcome ${JSON.stringify(unknown)}`);
+                    }
+                }
+            }
+        }
+        catch (err) {
+            if (err instanceof CallerThrow)
+                throw err;
+            if (issued)
+                mayHaveWritten = true;
+            report.conflicts.push({ op: patch.op, id: patch.id, reason: `io error: ${err instanceof Error ? err.message : String(err)}` });
+            return [];
+        }
+    };
+    let k = 0;
+    const attempt = async (admitted) => {
+        if (admitted !== undefined)
+            requireLandingsAdmitted(admitted, await predictFrom(k));
+        while (k < patches.length) {
+            const patch = patches[k];
+            if (duplicateAt.has(k)) {
+                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?)" });
+                k++;
+                continue;
+            }
+            const unasked = await commitOne(patch, k, admitted);
+            if (unasked.length > 0 && admitted !== undefined && !mayHaveWritten) {
+                throw new LandingsNeedAdmission(distinctLandings([...unasked, ...unadmittedOf(admitted, await predictFrom(k))]));
+            }
+            if (unasked.length > 0)
+                report.conflicts.push(movedAfterAdmission(patch, unasked));
+            k++;
+        }
+    };
+    try {
+        await admittingLandings(admit, attempt);
+    }
+    catch (err) {
+        throw err instanceof CallerThrow ? err.thrown : err;
+    }
+    finally {
+        if (leg.appendHistory && history.length > 0)
+            await leg.appendHistory(history);
+    }
+    return report;
+}
+//# sourceMappingURL=memory-engine-sql-apply.js.map

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

@@ -1,5 +1,6 @@
 import type { MemoryHistoryAppendRow } from "./memory-sync-store-pg.js";
 import type { PgEmbedder } 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 { Pool } from "mysql2/promise";
 /** Table names (single source) — SAME names as PG_MEMORY_ENGINE_TABLES (the two dialects never share
@@ -38,6 +39,8 @@ export declare class TiDBMemoryEngineBackend 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 — TiDB v1 sits on the lexical floor (Pg twin parity surface). */
     get vectorMode(): "lexical";
     constructor(pool: Pool, opts?: TiDBMemoryEngineBackendOptions);
@@ -53,15 +56,41 @@ export declare class TiDBMemoryEngineBackend implements MemoryBackend {
         limit?: number;
         exposureBands?: boolean;
     }): Promise<ScoredMemoryEntry[]>;
-    applyPatches(patches: readonly NotePatch[]): Promise<PatchReport>;
-    private applyOne;
-    /** The row's rev NOW, or undefined if the row is gone. The existence distinction is the whole point
-     *  (codex lens-3): a concurrent delete must not be mistaken for an idempotent already-at-target write. */
-    private freshRevOrMissing;
-    /** When the conditional write reports 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. Row gone ⇒ fallback (Pg parity). */
-    private freshRev;
+    /** core 落点问询协议的能力位:`applyPatches` 兑现 `opts.admit` / `opts.confirm`(读法见 `memory-engine-sql-apply.ts` 头注)。 */
+    readonly admitsLandings: true;
+    /** 判与驱动器只在 `memory-engine-sql-apply.ts` 一处(Pg 孪生同注);本腿只供读口、MySQL 协议方言写口(写语句绑定计划的投影)与 history 冲刷。
+     *  `opts.anchoredRoot` 是带目录的后端的事,本腿没有目录 ⇒ 不读。 */
+    applyPatches(patches: readonly NotePatch[], opts?: SqlApplyOpts): Promise<PatchReport>;
+    private rowOf;
+    private idsAt;
+    /** 写不落之后的现读:这个 id 的行此刻的 rev 与投影(没了 ⇒ undefined)。 */
+    private freshRow;
+    /**
+     * add:拆成「计划时有行 ⇒ UPDATE by id / 没有 ⇒ INSERT」(见文件头:MySQL 的 ON DUPLICATE KEY UPDATE 会被 `(scope, slug)` 键抢占、改写他人行,
+     * 禁用)。UPDATE 腿只覆盖仍在计划投影上的行,add-if-absent 再绑计划读到的 rev(与 PG 孪生同一条件);零 AFFECTED 行 ⇒ 现读:行没了 = 被并发
+     * 删掉 ⇒ 转 INSERT 腿、同一拼写(改前同);行在别处、或(绑了 rev 时)已被改写 ⇒ `moved`(驱动器按现状重判:add-if-absent 照判);行仍满足写条件且
+     * 已是这一份内容 = 匹配但值逐字相同(连接未开 FOUND_ROWS 时只数改动行)⇒ 已落;仍满足写条件却不是这一份内容 = 判与现读之间行被改走又改回
+     * ⇒ 响亮抛(记成这一条的 io error 冲突,与 PG 孪生同答)。ER_DUP_ENTRY 按**现读**分诊,不按报文里的键名:INSERT 腿撞键之后这个 id 的行在 ⇒
+     * 同 id 的行在判与写之间被别的副本插入 ⇒ `moved`(驱动器按现状重判,guard / 跨 scope 拒照判;与 PG 孪生 `ON CONFLICT (id)` 的仲裁同答);不在 ⇒
+     * 名在计划之后被占 ⇒ `slug-taken`;UPDATE 腿按 id 改、只撞得上 `(scope, slug)` ⇒ `slug-taken`。键名不可作判据:对手以同 id **同拼写**插入时
+     * 两只唯一键同时撞上,引擎报哪一只由它自己定(TiDB 报 `uq_…scope_slug`)—— 按键名会把「同 id 已在」读成「名被占」、退到 `-2` 拼写去覆盖。
+     * 每次重发写语句前都调 confirm(它是检查,幂等)。
+     */
+    private writeAdd;
+    /** update:条件 = 判过的 rev **且**判过的投影(rev 是内容哈希、不含 scope / slug)。零 AFFECTED 行 ⇒ 这一条的 CAS 按 **rev** 判(core 契约:stale
+     *  `baseRev` 的 update 是报告的冲突、带 `currentRev`,不按字节 —— 对手把行写成与本次 update 逐字节相同的目标态,这一条也是冲突,Pg 孪生 RETURNING
+     *  零行同答):
+     *  · 一条什么都没改的 update(新 rev == 判过的 rev 且投影不动)在没开 FOUND_ROWS 的连接上匹配了也数 0 ⇒ 现读行仍在判过的 rev + 投影上 = 条件成立 = 已落;
+     *    这是零行唯一能是 applied 的形 —— 目标 rev 与判过的 rev 不同的 update 一定改动行(rev 列本身变了),零行即未匹配;
+     *    行被对手改走又改回判过的 rev 时,按 rev 它没变过(与 File 腿的比对、与共享判里「A→B→A 让 stale baseRev 重新当前」同一读法),这一条本来就是什么都没改 ⇒ 照样已落;
+     *  · 内容未变而投影变了 = `moved`;其余 = CAS 冲突,`currentRev` 报现值。
+     *  🔴 行存在性是承重的:判与写之间行被并发删掉时 affectedRows 也是 0,现读对没了的行答 undefined ⇒ 落冲突(逐字相同的 update 也一样),两方言同答。 */
+    private writeUpdate;
+    /** delete:条件同 update;DELETE 的 affectedRows 数的是删掉的行(FOUND_ROWS 只影响 UPDATE):0 = 行变了 / 挪了 / 没了。 */
+    private writeDelete;
+    /** BEST-EFFORT history append(见 TiDBMemoryEngineBackendOptions.history 的如实取舍):entry 写已提交,审计行追加失败不许让报告
+     *  失败 —— 吞 + warn,永不抛;appendHistory 按 (id, rev) 幂等,调用方重试安全。 */
+    private appendHistory;
     getConsolidationCursor(scope: string): Promise<string | undefined>;
     setConsolidationCursor(scope: string, cursor: string): Promise<void>;
 }