@sema-agent/server 7.144.0 → 7.146.0

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 } : 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,38 @@ 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 腿只覆盖仍在计划投影上的行;零 AFFECTED 行 ⇒ 现读:行没了 = 被并发删掉 ⇒ 转 INSERT 腿、同一拼写(改前同);
+     * 行在别处 ⇒ `moved`;行还在计划的投影上且已是这一份内容 = 匹配但值逐字相同(连接未开 FOUND_ROWS 时只数改动行)⇒ 已落;
+     * 行还在计划的投影上却不是这一份内容 = 判与现读之间行被挪走又挪回 ⇒ 响亮抛(记成这一条的 io error 冲突,与 PG 孪生同答)。INSERT 腿的 ER_DUP_ENTRY 按键名分诊:
+     * PRIMARY = 同 id 的行在判与写之间被别的副本插入 ⇒ `moved`(驱动器按现状重判,guard / 跨 scope 拒照判);`uq_…scope_slug` = 名在计划之后
+     * 被占 ⇒ `slug-taken`。每次重发写语句前都调 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>;
 }