@sema-agent/server 1.323.0 → 2.0.0

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

@@ -1,9 +1,37 @@
+// TiDB (MySQL wire) dialect twin of `memory-engine-pg.ts` — the THIRD MemoryBackend implementation
+// (边界重切:core 养 File backend+seam+memoryBackendContract,SQL 方言归 service;先例=
+// TiDBRunStore/PgRunStore 方言孪生对)。Same tables, same contract, mysql2 posture throughout.
+//
+// 方言改造点(core 指引,与 Pg 版逐条对照):
+//   - `$n` 占位符 → `?`;`jsonb` → `JSON`(mysql2 对 JSON 列返回已解析对象,fromJson 防御 string 形);
+//   - `UPDATE/DELETE … WHERE rev = ? RETURNING` → MySQL 无 RETURNING:条件写后看 affectedRows;零行=
+//     conflict,且 currentRev 必须 SELECT 现值(freshRev 语义——绝不把 pre-race SELECT 的旧值当 currentRev)。
+//     ⚠️ affectedRows 语义(归因修正:mysql2 默认 flags 含 FOUND_ROWS ⇒ affectedRows=
+//     MATCHED 行数;此前注释写反)。真库契约在真默认语义下全绿;下述 fresh-rev 比对分支让两种语义都正确:matched-but-
+//     identical 也是 0——零行后用 freshRev 消歧(现 rev==新 rev ⇒ 内容已是目标态=幂等成功,非 conflict);
+//   - add 路径 Pg 用 `INSERT … ON CONFLICT (id) DO UPDATE`(冲突靶=仅 PK)。MySQL 的 ON DUPLICATE KEY
+//     UPDATE 会被 **任意** 唯一键触发——(scope,slug) 撞键时它会把竞争对手的行改写成本 entry 的 id(数据毁),
+//     不能用;拆成「不存在→INSERT / 已存在→UPDATE by id」,两条腿的 ER_DUP_ENTRY 都按键名分诊(PRIMARY=
+//     并发同 id add → 转 UPDATE 腿;uk_scope_slug=并发 slug 竞争 → 下一个 -n 后缀重试);
+//   - unique violation 判定:ER_DUP_ENTRY(errno 1062),不是 Pg 的 23505;
+//   - pg-mem 伪影 workaround(索引列 ANY 零行/重复占位符重复行)不抄——MySQL 本就走 IN-list,dedupe 保留
+//     是因为它同时是诚实语义(重复 key 问的是同一个 entry,契约锁死 once-per-entry);
+//   - (scope, slug) UNIQUE 约束照立(竞态正确性:两实例各自探得 free 同时 INSERT,DB 约束是唯一仲裁);
+//   - 表名与 Pg 版同名(两方言不会同库;与退役 MemoryStore 的 `agent_memory*` 面刻意不相交);
+//   - v1 lexical only:embedder/vector 面无 TiDB 对应(Pg 的 pgvector rung 是 Pg 专属);构造签名保留
+//     opts 但传入 embedder=fail-loud 拒绝,search 恒走 jaccard 词面,haystack 与 Pg/File 逐字节同构
+//     (`${name ?? slug} ${description} ${body}`——memoryBackendContract 的 search 等价断言依赖)。
 import { jaccardDistance, termSet } from "./memory-engine-vector-util.js";
 import { computeEntryRev, serializeEntryFile } from "@sema-agent/core";
+/** Table names (single source) — SAME names as PG_MEMORY_ENGINE_TABLES (the two dialects never share
+ *  one database), deliberately DISJOINT from the legacy `agent_memory*` MemoryStore plane. */
 export const TIDB_MEMORY_ENGINE_TABLES = {
     entries: "agent_memory_engine_entries",
     cursors: "agent_memory_engine_cursors",
 };
+/** Idempotent DDL for the entry plane (TiDB dialect). Call once at startup.
+ *  Key lengths: utf8mb4 = 4 bytes/char and the default index-key cap is 3072 bytes, so the
+ *  (scope, slug) unique key budget is scope 190 + slug 512 = 702 chars ⇒ 2808 bytes ≤ 3072. */
 export async function ensureTiDBMemoryEngineSchema(pool) {
     await pool.query(`CREATE TABLE IF NOT EXISTS ${TIDB_MEMORY_ENGINE_TABLES.entries} (
     id          VARCHAR(64)  NOT NULL,
@@ -19,6 +47,9 @@ export async function ensureTiDBMemoryEngineSchema(pool) {
     KEY idx_scope (scope),
     UNIQUE KEY uk_scope_slug (scope, slug)
   )`);
+    // The (scope, slug) UNIQUE key above is CORRECTNESS, not perf (Pg 版同注):two
+    // instances racing an add of one scope+slug (different ids) can both probe "free" and both insert;
+    // the DB constraint is the only true arbiter and the add path retries the next suffix on violation.
     await pool.query(`CREATE TABLE IF NOT EXISTS ${TIDB_MEMORY_ENGINE_TABLES.cursors} (
     scope  VARCHAR(190) NOT NULL,
     \`cursor\` TEXT     NOT NULL,
@@ -30,9 +61,12 @@ function isDupEntry(err) {
         return false;
     return err.code === "ER_DUP_ENTRY" || err.errno === 1062;
 }
+/** ER_DUP_ENTRY messages name the violated key (`… for key 'tbl.PRIMARY'` / `… for key 'tbl.uk_scope_slug'`)
+ *  — the add path uses this to tell "id already exists (→ overwrite leg)" from "slug race (→ -n retry)". */
 function isPrimaryKeyDup(err) {
     return isDupEntry(err) && /for key '[^']*PRIMARY'/i.test(String(err.message ?? ""));
 }
+/** `?, ?, …` for a dynamic IN list (MySQL has no ANY(param); plain IN-list on both engines). */
 function inPlaceholders(count) {
     return Array.from({ length: count }, () => "?").join(", ");
 }
@@ -43,7 +77,9 @@ export class TiDBMemoryEngineBackend {
     pool;
     clock;
     history;
+    /** Cumulative lost-row count — audit-line breakage must itself be auditable. */
     historyRowsLost = 0;
+    /** design/81 rung indicator — TiDB v1 sits on the lexical floor (Pg twin parity surface). */
     get vectorMode() {
         return "lexical";
     }
@@ -63,6 +99,7 @@ export class TiDBMemoryEngineBackend {
         const [res] = await this.pool.query(sql, params);
         return res;
     }
+    /** The search haystack — BYTE-EQUAL to the File/Pg backends' lexical haystack (contract equivalence). */
     haystackOf(slug, fm, body) {
         return `${fm.name ?? slug} ${fm.description ?? ""} ${body}`;
     }
@@ -91,6 +128,8 @@ export class TiDBMemoryEngineBackend {
         };
     }
     async listHeaders(scopes) {
+        // Dedupe (all three read paths): honest semantic — a caller repeating a key asks about ONE entry
+        // (contract-locked once-per-entry; real IN-lists don't duplicate anyway).
         const uniq = [...new Set(scopes)];
         if (uniq.length === 0)
             return [];
@@ -102,13 +141,15 @@ export class TiDBMemoryEngineBackend {
         if (uniq.length === 0)
             return [];
         const rows = await this.selectRows(`SELECT id, scope, slug, frontmatter, body, rev, mtime_ms, size_bytes FROM ${TIDB_MEMORY_ENGINE_TABLES.entries} WHERE id IN (${inPlaceholders(uniq.length)}) ORDER BY id`, uniq);
-        return rows.map((r) => this.entryFromRow(r));
+        return rows.map((r) => this.entryFromRow(r)); // unknown ids: silently absent
     }
     async search(query, scopes, opts) {
+        // Limit normalization mirrors the Pg twin verbatim (floor semantics; NaN rejected; Infinity = no cap).
         const rawLimit = opts?.limit ?? 20;
         const limit = Number.isFinite(rawLimit) ? Math.floor(rawLimit) : rawLimit;
         if (scopes.length === 0 || !(limit > 0))
             return [];
+        // EMPTY-QUERY contract is backend-uniform: no terms → [] (File/Pg parity).
         const q = termSet(query);
         if (q.size === 0)
             return [];
@@ -120,16 +161,22 @@ export class TiDBMemoryEngineBackend {
             const fm = fromJson(r.frontmatter);
             const d = jaccardDistance(q, this.haystackOf(r.slug, fm, r.body));
             if (d === null)
-                continue;
+                continue; // zero-overlap: not a candidate
             scored.push({ ...this.headerFromRow(r), score: d });
         }
+        // Deterministic id tie-break (opus 审 C4,Pg 版同注): tied scores must not order by row-arrival
+        // accident — the cross-backend equivalence assertion compares ordered projections.
         scored.sort((a, b) => 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: [] };
+        // At most ONE non-delete op per id per batch (file-backend parity — a COPY keeping its frontmatter
+        // id would leave the projection↔applied binding ambiguous; refuse the later one).
         const nonDeleteIds = new Set();
+        // In-batch (scope, slug) claims so two adds of one slug in one batch suffix deterministically.
         const plannedSlugs = new Set();
+        // 142-S5.1: one history row per APPLIED patch, flushed as one batch below (append-only audit face).
         const historyRows = [];
         for (const patch of patches) {
             try {
@@ -146,11 +193,17 @@ export class TiDBMemoryEngineBackend {
                 report.conflicts.push({ op: patch.op, id: patch.id, reason: `io error: ${err instanceof Error ? err.message : String(err)}` });
             }
         }
+        // BEST-EFFORT history append (see TiDBMemoryEngineBackendOptions.history for the honest trade-off:
+        // the entry writes above are already committed; a failed audit append must not fail the report —
+        // swallow + warn, never throw. appendHistory is (id,rev)-idempotent, so a caller retry is safe.
         if (this.history && historyRows.length > 0) {
             try {
                 await this.history.appendHistory(historyRows);
             }
             catch (err) {
+                // Every warn carries the CUMULATIVE lost count — a persistent silent failure
+                // (history table dropped, grant flipped) shows as a growing number, not a one-off line.
+                // The metrics counter leg lives in the main.ts sink wrapper (memory_history_append_failed_total).
                 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)}`);
             }
@@ -159,6 +212,8 @@ export class TiDBMemoryEngineBackend {
     }
     async applyOne(patch, report, plannedSlugs, historyRows) {
         const T = TIDB_MEMORY_ENGINE_TABLES.entries;
+        // A patch whose entry carries a DIFFERENT id than the patch addresses is malformed — refused up
+        // front, all backends alike (Pg 版同注).
         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;
@@ -169,9 +224,15 @@ export class TiDBMemoryEngineBackend {
                 report.conflicts.push({ op: "add", id: patch.id, reason: "add patch without an entry" });
                 return;
             }
+            // Cross-scope add refusal (opus 审 C3,Pg 版同注): an add whose id already lives in a DIFFERENT
+            // scope must not silently MOVE the row; same-scope re-add stays the idempotent overwrite.
+            // One probe serves BOTH the E-02 guard and the cross-scope refusal (File/Pg parity).
             const prior = await this.selectRows(`SELECT scope, slug, rev FROM ${T} WHERE id = ?`, [entry.id]);
             const priorRow = prior.length > 0 ? prior[0] : undefined;
             let existsById = priorRow !== undefined;
+            // E-02 add-if-absent guard (core 1.275.1/1.276.0 contract clause; caught live by the contract
+            // suite on real TiDB 2026-07-13): same rev AND same (scope, slug) projection = idempotent
+            // fall-through; different rev OR projection = REPORTED add_guard_absent_conflict + currentRev.
             if (patch.guard === "absent" && priorRow) {
                 const currentRev = String(priorRow.rev);
                 if (currentRev !== computeEntryRev(entry)) {
@@ -182,6 +243,7 @@ export class TiDBMemoryEngineBackend {
                     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;
                 }
+                // same rev AND same projection ⇒ idempotent; fall through to the normal add (no-op re-write).
             }
             if (priorRow) {
                 const held = String(priorRow.scope);
@@ -190,6 +252,9 @@ export class TiDBMemoryEngineBackend {
                     return;
                 }
             }
+            // Slug collision with a DIFFERENT entry → deterministic `-n` suffix (file-backend parity); the
+            // probe is only an optimization — the write INSIDE the loop is arbitrated by uk_scope_slug, and
+            // a concurrent loser retries the next suffix (Pg 版同注).
             let slug = entry.slug;
             for (let n = 2;; n++) {
                 const key = `${entry.scope}|${slug}`;
@@ -202,12 +267,18 @@ export class TiDBMemoryEngineBackend {
                         const sizeBytes = Buffer.byteLength(serializeEntryFile(stored), "utf8");
                         try {
                             if (existsById) {
+                                // Idempotent overwrite leg (Pg 的 ON CONFLICT(id) DO UPDATE 对应面;见文件头:MySQL 的
+                                // ON DUPLICATE KEY UPDATE 会被 (scope,slug) 键劫持改写他人行,禁用)。
                                 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) {
+                                    // affectedRows: under mysql2 default (FOUND_ROWS ⇒ matched count) 0 = row gone;
+                                    // under changed-only semantics 0 could also mean already-at-target — the fresh-rev branch below covers BOTH: 0 = either the row already
+                                    // holds exactly this content (idempotent no-op = success) or it vanished under a
+                                    // concurrent delete (→ fall back to the INSERT leg, same slug).
                                     const still = await this.selectRows(`SELECT id FROM ${T} WHERE id = ?`, [stored.id]);
                                     if (still.length === 0) {
                                         existsById = false;
-                                        continue;
+                                        continue; // row deleted concurrently — retry this slug via the INSERT leg
                                     }
                                 }
                             }
@@ -218,16 +289,18 @@ export class TiDBMemoryEngineBackend {
                         catch (err) {
                             if (isDupEntry(err)) {
                                 if (isPrimaryKeyDup(err)) {
-                                    existsById = true;
+                                    existsById = true; // concurrent same-id add won the PK — retry this slug via the overwrite leg
                                     continue;
                                 }
-                                slug = `${entry.slug}-${n}`;
+                                slug = `${entry.slug}-${n}`; // concurrent winner took this (scope,slug) — next suffix
                                 continue;
                             }
                             throw err;
                         }
                         plannedSlugs.add(key);
                         report.applied.push({ op: "add", id: stored.id, slug: stored.slug });
+                        // History: chain head — prevRev absent by contract (a same-scope idempotent re-add of
+                        // identical content dedupes on the (id, rev) PK; changed content starts a fresh head).
                         if (this.history)
                             historyRows.push({ id: stored.id, rev, op: "add", scope: stored.scope, snapshot: { ...stored, rev }, writtenAtMs: this.clock() });
                         return;
@@ -236,6 +309,8 @@ export class TiDBMemoryEngineBackend {
                 slug = `${entry.slug}-${n}`;
             }
         }
+        // update/delete address an EXISTING entry by immutable id. (scope in the projection = the
+        // history row's scope for delete — a tombstone can't be joined back to the deleted row.)
         const cur = await this.selectRows(`SELECT slug, rev, scope, 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)" });
@@ -244,6 +319,10 @@ export class TiDBMemoryEngineBackend {
         const currentRev = String(cur[0].rev);
         const currentSlug = String(cur[0].slug);
         const currentScope = String(cur[0].scope);
+        // Read-side whitewash refusal (core 1.302 contract I-2, File-backend parity incl. ordering: judged
+        // BEFORE the rev CAS): an update may not strip provenance/trust off a repo-ingested entry. Judged on
+        // the committed frontmatter of THIS SELECT — a write racing past it flips rev and the conditional
+        // write below re-reports as a CAS conflict, so the window stays closed.
         if (patch.op === "update" && patch.entry !== undefined) {
             const committedFm = fromJson(cur[0].frontmatter);
             if (committedFm.provenance?.kind === "repo_file") {
@@ -261,16 +340,26 @@ export class TiDBMemoryEngineBackend {
             }
         }
         if (patch.baseRev !== undefined && patch.baseRev !== currentRev) {
+            // Per-id CAS (§2.4 并发): NEVER blind-write over a concurrent change. ABA note shared with the
+            // File/Pg backends (rev is a content hash — an A→B→A round-trip re-arms a stale baseRev; benign
+            // by construction, same canonical content).
             report.conflicts.push({ op: patch.op, id: patch.id, reason: "rev mismatch (concurrent change)", baseRev: patch.baseRev, currentRev });
             return;
         }
         if (patch.op === "delete") {
+            // Conditional on the rev we just judged — a write landing between the SELECT and this DELETE
+            // re-reports as the same CAS conflict instead of silently deleting the newer committed state.
+            // DELETE's affectedRows counts deleted rows (FOUND_ROWS only affects UPDATE): 0 = the row changed/vanished.
             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;
             }
             report.applied.push({ op: "delete", id: patch.id, slug: currentSlug });
+            // History tombstone. rev must be DISTINCT from the deleted version's rev — the (id, rev) PK
+            // already holds a row for currentRev (the add/update that committed it), and the idempotent
+            // no-op ODKU would silently drop a colliding tombstone. Deterministic derived key: revs are
+            // 16-hex content hashes (computeEntryRev), so the prefixed form stays well under VARCHAR(128).
             if (this.history)
                 historyRows.push({ id: patch.id, rev: `tombstone:${currentRev}`, prevRev: currentRev, op: "delete", scope: currentScope, writtenAtMs: this.clock() });
             return;
@@ -283,9 +372,22 @@ export class TiDBMemoryEngineBackend {
         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) {
+            // Zero AFFECTED rows is ambiguous under the default protocol (changed-rows counting): the row may
+            // hold rev==currentRev with byte-identical values (matched but unchanged). Disambiguate on the
+            // fresh rev: the row must STILL EXIST and already be at the NEW rev ⇒ the content is exactly the
+            // target state (idempotent success — also covers a concurrent writer landing the same hash);
+            // anything else ⇒ CAS conflict with the rev NOW.
+            // 🔴 codex lens-3: the row-EXISTENCE check is load-bearing. When the row was concurrently DELETED
+            // between the SELECT and this UPDATE, affectedRows is also 0; a fallback that returned the pre-race
+            // rev would make `fresh === rev` true for a byte-identical update and FALSELY report `applied` on a
+            // row that no longer exists — while the Pg twin (UPDATE … RETURNING → zero rows) correctly reports a
+            // conflict. `freshRevOrMissing` returns undefined for a gone row, so it falls through to conflict,
+            // restoring dialect parity (never accept a lost write as applied).
             const fresh = await this.freshRevOrMissing(entry.id);
             if (fresh === rev) {
                 report.applied.push({ op: "update", id: entry.id, slug: entry.slug });
+                // History: the idempotent already-at-target success is a committed version too — the
+                // (id, rev) idempotent append dedupes if this exact version was already recorded.
                 if (this.history)
                     historyRows.push({ id: entry.id, rev, prevRev: currentRev, op: "update", scope: entry.scope, snapshot: { ...entry, rev }, writtenAtMs: this.clock() });
                 return;
@@ -294,13 +396,19 @@ export class TiDBMemoryEngineBackend {
             return;
         }
         report.applied.push({ op: "update", id: entry.id, slug: entry.slug });
+        // History: rev-chain link — snapshot carries the committed entry (rev = the NEW content hash).
         if (this.history)
             historyRows.push({ id: entry.id, rev, prevRev: currentRev, op: "update", scope: entry.scope, snapshot: { ...entry, rev }, writtenAtMs: this.clock() });
     }
+    /** 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. */
     async freshRevOrMissing(id) {
         const rows = await this.selectRows(`SELECT rev FROM ${TIDB_MEMORY_ENGINE_TABLES.entries} WHERE id = ?`, [id]);
         return rows.length > 0 ? String(rows[0].rev) : undefined;
     }
+    /** 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). */
     async freshRev(id, fallback) {
         return (await this.freshRevOrMissing(id)) ?? fallback;
     }
@@ -309,6 +417,8 @@ export class TiDBMemoryEngineBackend {
         return rows.length > 0 ? String(rows[0].cursor) : undefined;
     }
     async setConsolidationCursor(scope, cursor) {
+        // Single unique key (the PK) on this table — ON DUPLICATE KEY UPDATE is unambiguous here,
+        // unlike the two-unique-key entries table (see the file-head dialect note).
         await this.write(`INSERT INTO ${TIDB_MEMORY_ENGINE_TABLES.cursors} (scope, \`cursor\`) VALUES (?, ?) ON DUPLICATE KEY UPDATE \`cursor\` = VALUES(\`cursor\`)`, [scope, cursor]);
     }
 }

package/dist/plugins/memory-engine-vector-util.d.ts

@@ -1,3 +1,8 @@
+/** memory-engine 方言实现共用的纯工具函数。三个距离/词集函数 re-export 自 core(1.268.0 起公开导出,
+ *  单一语义源;memoryBackendContract 的 search 等价断言依赖同源 haystack 距离)。
+ *  `isUniqueViolation` 重新内联:它当年随 core 的 pg **示例适配器**导出面走,core 1.424 按 clay 包卫生令
+ *  把整个 examples 面退出 npm 包([1803] BREAKING)⇒ re-export 断源。逐字抄自 core 1.423
+ *  `examples/adapters/pg-adapter.js`(纯谓词,无 byte-equal 契约约束)。 */
 export { termSet, jaccardDistance, cosineDistance } from "@sema-agent/core";
 export declare function isUniqueViolation(err: unknown): boolean;
 //# sourceMappingURL=memory-engine-vector-util.d.ts.map

package/dist/plugins/memory-engine-vector-util.js

@@ -1,3 +1,8 @@
+/** memory-engine 方言实现共用的纯工具函数。三个距离/词集函数 re-export 自 core(1.268.0 起公开导出,
+ *  单一语义源;memoryBackendContract 的 search 等价断言依赖同源 haystack 距离)。
+ *  `isUniqueViolation` 重新内联:它当年随 core 的 pg **示例适配器**导出面走,core 1.424 按 clay 包卫生令
+ *  把整个 examples 面退出 npm 包([1803] BREAKING)⇒ re-export 断源。逐字抄自 core 1.423
+ *  `examples/adapters/pg-adapter.js`(纯谓词,无 byte-equal 契约约束)。 */
 export { termSet, jaccardDistance, cosineDistance } from "@sema-agent/core";
 export function isUniqueViolation(err) {
     if (typeof err !== "object" || err === null)

package/dist/plugins/memory-resume-anchor-store.d.ts

@@ -1,12 +1,20 @@
 export declare class MemoryResumeAnchorStore {
     private readonly bySession;
+    /** Record/overwrite the anchor for one settled message boundary (idempotent upsert; parity with the SQL ON DUPLICATE/CONFLICT). */
     put(sessionId: string, eventId: string, entryId: string, owner: string | null): Promise<void>;
+    /** Resolve a shell-supplied eventId → the persisted SessionTreeEntry.id for TaskSpec.resumeAt; undefined = unknown
+     *  anchor (the route 4xx's before handing core a bad id). owner null-safe guard = the SQL `owner <=> ?` defense-in-depth. */
     resolve(sessionId: string, eventId: string, owner: string | null): Promise<string | undefined>;
+    /** 2c session-sync: ALL anchors for a session (every eventId→entryId + its owner), UNFILTERED — a cross-backend
+     *  session EXPORT bundles the whole anchor map so the importer can re-key owner to the target principal (§9). Twin of
+     *  the SQL/file stores; kept on all three backends so the ResumeAnchorStore union shares a single contract. */
     listBySession(sessionId: string): Promise<Array<{
         eventId: string;
         entryId: string;
         owner: string | null;
     }>>;
+    /** E21 (§0.5 delete) — purge ALL anchors for a session, scoped by session_id ALONE (the route already proved session
+     *  ownership; a per-row owner guard would orphan rows stored under a divergent per-run principal). Idempotent (count). */
     deleteBySession(sessionId: string): Promise<number>;
 }
 //# sourceMappingURL=memory-resume-anchor-store.d.ts.map

package/dist/plugins/memory-resume-anchor-store.js

@@ -1,6 +1,16 @@
+/**
+ * In-memory resume-at anchor map — the LOCAL (DB-less) twin of {@link TiDBResumeAnchorStore}/{@link PgResumeAnchorStore}
+ * (E18 resume-at; clay seamless local↔cloud). The shell holds the live E2 `eventId` (core never persists it);
+ * core's `TaskSpec.resumeAt` takes a persisted `SessionTreeEntry.id`. This store is the service-owned translation
+ * ("a deployment that holds eventIds owns the eventId→entryId map", core types). resume-at works LOCALLY (it needs
+ * only the session tree + this map, no cloud-only checkpoint), so this is PRESENT on the local backend (a singleton,
+ * like MemoryRunStore) — not omitted like the cloud-only stores. Process-local + ephemeral (lost on restart, same
+ * blast radius as MemoryRunStore; the file-backed follow-on persists it alongside run history).
+ */
 const ownerEq = (a, b) => (a ?? null) === (b ?? null);
 export class MemoryResumeAnchorStore {
     bySession = new Map();
+    /** Record/overwrite the anchor for one settled message boundary (idempotent upsert; parity with the SQL ON DUPLICATE/CONFLICT). */
     async put(sessionId, eventId, entryId, owner) {
         let m = this.bySession.get(sessionId);
         if (!m) {
@@ -9,10 +19,15 @@ export class MemoryResumeAnchorStore {
         }
         m.set(eventId, { entryId, owner });
     }
+    /** Resolve a shell-supplied eventId → the persisted SessionTreeEntry.id for TaskSpec.resumeAt; undefined = unknown
+     *  anchor (the route 4xx's before handing core a bad id). owner null-safe guard = the SQL `owner <=> ?` defense-in-depth. */
     async resolve(sessionId, eventId, owner) {
         const e = this.bySession.get(sessionId)?.get(eventId);
         return e && ownerEq(e.owner, owner) ? e.entryId : undefined;
     }
+    /** 2c session-sync: ALL anchors for a session (every eventId→entryId + its owner), UNFILTERED — a cross-backend
+     *  session EXPORT bundles the whole anchor map so the importer can re-key owner to the target principal (§9). Twin of
+     *  the SQL/file stores; kept on all three backends so the ResumeAnchorStore union shares a single contract. */
     async listBySession(sessionId) {
         const m = this.bySession.get(sessionId);
         if (!m)
@@ -22,6 +37,8 @@ export class MemoryResumeAnchorStore {
             out.push({ eventId, entryId: e.entryId, owner: e.owner });
         return out;
     }
+    /** E21 (§0.5 delete) — purge ALL anchors for a session, scoped by session_id ALONE (the route already proved session
+     *  ownership; a per-row owner guard would orphan rows stored under a divergent per-run principal). Idempotent (count). */
     async deleteBySession(sessionId) {
         const removed = this.bySession.get(sessionId)?.size ?? 0;
         this.bySession.delete(sessionId);

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

@@ -1,17 +1,49 @@
+/**
+ * In-memory async run registry + replayable event log — the LOCAL (DB-less) twin of {@link TiDBRunStore}/
+ * {@link PgRunStore} (clay 2026-06-25: the seamless local↔cloud switch — a locally-run HTTP service must serve the
+ * SAME contract a cloud worker does, incl. `/v1/runs` async runs + the trace event log). Behaviourally identical to
+ * the SQL twins (the shared `storeBehaviorSuite` keeps them in lock-step), but process-local + ephemeral: a restart
+ * loses run history (file-backed durability is the immediate follow-on; the conversation HISTORY + checkpoints DO
+ * persist via core's FileStorageBackend). Single-process, so the cross-replica/durable reapers degrade — see below.
+ *
+ * Mirrors the SQL semantics exactly: the `task_active` single-active-run claim (a Map keyed by sessionId), the
+ * NON-terminal suspend/needs_review parks that KEEP the claim, the markResuming CAS that resets cancel/preempt, the
+ * owner null-safe guard on the flag/heartbeat paths (`<=>` → JS `(a??null)===(b??null)`), and the keyset list order.
+ */
 import { type UsageRow } from "../usage-analytics.js";
 import type { TaskResult, TaskStatus } from "@sema-agent/core";
 import type { RunRecord, SessionSummary, RunEvent } from "./store-contracts.js";
+/**
+ * [868] P0 — the local lane's stand-in for the SQL twins' checkpoint-table JOIN. The file/memory run stores
+ * cannot JOIN `checkpoint` (separate store, separate files), so the suspended-run reapers were NO-OPs — which
+ * left a durable HITL park whose approval was never answered holding the task_active claim FOREVER (the
+ * "suspended run locks the session" incident: every later submit 409s and no reaper path releases it).
+ * The backend assembly (store-backend.ts local lane, where checkpoint + run store are built side by side)
+ * injects this probe so the reapers get the SAME two predicates the SQL twins express as EXISTS subqueries:
+ *  - hasPending  = EXISTS (checkpoint c WHERE c.session_id = ? AND c.status = 'pending')  — the design/80 D-D
+ *    NOT-EXISTS-pending guard: a row whose checkpoint is STILL pending is owned by the checkpoint-state-driven
+ *    sweeps and must NEVER be time-reaped (else two-runs-one-session, see tidb-run-store.ts reapSuspended doc).
+ *  - hasExpired  = EXISTS (checkpoint ce WHERE ce.session_id = ? AND ce.status = 'expired') — the
+ *    failSuspendedWithExpiredCheckpoint driver (checkpoint-STATE-driven, not time-driven).
+ * Probe ABSENT (old assembly / no checkpoint store wired) ⇒ the reapers stay honest NO-OPs — without the
+ * pending-guard there is no safe way to distinguish "abandoned park" from "operator still deciding".
+ */
 export interface RunStoreCheckpointProbe {
     hasPending(sessionId: string): Promise<boolean>;
     hasExpired(sessionId: string): Promise<boolean>;
 }
 export declare class MemoryRunStore {
     private readonly runs;
+    /** sessionId → taskId — the single-active-run claim (the `task_active` table). */
     private readonly active;
+    /** taskId → events (kept seq-sorted on read). */
     private readonly events;
+    /** [868] the checkpoint-table stand-in (see {@link RunStoreCheckpointProbe}); absent ⇒ reapers NO-OP. */
     private checkpointProbe?;
+    /** [868] wire the checkpoint probe (backend assembly, where checkpoint + run store are built together). */
     setCheckpointProbe(probe: RunStoreCheckpointProbe): void;
     private toRecord;
+    /** Create a run iff the session has no active run (the task_active unique-key claim). */
     createRun(taskId: string, sessionId: string, owner: string | null, instanceId: string, meta?: {
         jobId?: string | null;
         source?: string | null;
@@ -31,12 +63,18 @@ export declare class MemoryRunStore {
     maxSeq(taskId: string): Promise<number>;
     retainedFrom(taskId: string): Promise<number>;
     getEvents(taskId: string, afterSeq: number): Promise<RunEvent[]>;
+    /** [888] FIRST terminal writer wins(SQL 孪生同款正向 CAS on running/suspended/needs_review,
+     *  [1.207 codex M1] 负向形漏 blocked/timeout);claim 释放保持无条件(幂等)。 */
     setTerminal(taskId: string, status: TaskStatus, result: TaskResult | null, error: string | null): Promise<void>;
+    /** Durable F4: park NON-terminal `suspended`, KEEP the task_active claim. CAS on running/suspended (reaper-revert guard). */
     setSuspended(taskId: string): Promise<void>;
+    /** design/80 D-B: park NON-terminal `needs_review`, KEEP the claim. CAS on running/needs_review. */
     setNeedsReview(taskId: string): Promise<void>;
+    /** Durable F4 resume: flip suspended/needs_review → running (CAS) + reset cancel/preempt flags. */
     markResuming(taskId: string): Promise<boolean>;
     getActiveTaskId(sessionId: string): Promise<string | undefined>;
     getRun(taskId: string): Promise<RunRecord | undefined>;
+    /** Runs newest-first, keyset on (createdAt, taskId) DESC; optional exact-match filters (owner is exact, like the SQL). */
     listRuns(opts: {
         status?: string;
         jobId?: string;
@@ -48,6 +86,7 @@ export declare class MemoryRunStore {
         };
         limit: number;
     }): Promise<RunRecord[]>;
+    /** DISTINCT sessions newest-first by last activity (the CC /resume picker): latest run's preview/status + first/last/count. */
     listSessions(opts: {
         owner?: string;
         cursor?: {
@@ -57,11 +96,13 @@ export declare class MemoryRunStore {
         limit: number;
         q?: string;
     }): Promise<SessionSummary[]>;
+    /** E21 (§0.5 delete) — purge the runs ledger for one session, owner-guarded; aborts (returns {active}) if a run is live. */
     deleteBySession(sessionId: string, owner: string | null): Promise<{
         removed: number;
     } | {
         active: string;
     }>;
+    /** 用量扫窗——in-memory 腿:遍历窗内行,投影同 usage-analytics 纯函数(SQL 孪生 parity)。 */
     usageScan(fromMs: number, toMs: number, opts?: {
         owner?: string;
         limit?: number;
@@ -74,10 +115,32 @@ export declare class MemoryRunStore {
         status: string;
         count: number;
     }>>;
+    /** Fail stale `running` rows (crashed-run backstop) + release task_active for any now-terminal row. */
     reapStale(olderThanMs: number): Promise<number>;
+    /** [868] shared tail of both suspended-run reapers: flip one parked row → failed('approval.expired'), the
+     *  in-memory twin of the SQL UPDATE (`error`/`error_code` set directly — no result blob to derive from). */
     private failExpiredPark;
+    /** Release the claim for TERMINAL rows only — suspended/needs_review keep it (the `DELETE ta … WHERE tr.status
+     *  NOT IN ('running','suspended','needs_review')` twin, shared by reapStale + the [868] suspended reapers). */
     private releaseTerminalClaims;
+    /**
+     * [868] Durable F4 expiry — the local twin of TiDBRunStore.reapSuspended, driven by the injected checkpoint
+     * probe instead of a SQL JOIN (formerly a NO-OP, which was one of the five closed doors in the "suspended run
+     * locks the session forever" incident). Semantics verbatim from the SQL twin: suspended ∧ updatedAt < cutoff
+     * ∧ NOT probe.hasPending(session) → failed 'approval expired before decision' / error_code 'approval.expired'
+     * + release the task_active claim. The NOT-pending clause is the design/80 D-D adversarial-blocker guard
+     * (see tidb-run-store.ts:577-583): a row whose checkpoint is STILL pending belongs to the checkpoint-state
+     * sweeps (SLA deny-sweep / failSuspendedWithExpiredCheckpoint) — time-reaping it here would orphan a model
+     * leg on a now-unlocked session. Probe absent ⇒ honest NO-OP (never kill a park without the guard).
+     */
     reapSuspended(olderThanMs: number): Promise<number>;
+    /**
+     * [868] design/80 §3 inv#3 crash-safe backstop — the local twin of TiDBRunStore.failSuspendedWithExpiredCheckpoint
+     * (checkpoint-STATE-driven, not time-driven; runs UNCONDITIONALLY every reaper tick, no APPROVAL_TIMEOUT_SEC gate).
+     * Semantics verbatim from the SQL twin: (suspended ∨ needs_review) ∧ probe.hasExpired(session) ∧ NOT
+     * probe.hasPending(session) → same fail + claim release. The NOT-pending clause covers a re-suspended session
+     * that minted a NEW pending gate (wq64gmm5e: an abandoned needs_review park leaks exactly like a suspended one).
+     */
     failSuspendedWithExpiredCheckpoint(): Promise<number>;
 }
 //# sourceMappingURL=memory-run-store.d.ts.map