@sema-agent/server 1.322.0 → 2.0.0

package/dist/plugins/local-task-attachment-store.js

@@ -1,6 +1,15 @@
+/**
+ * LocalTaskAttachmentStore —— D-1 附件店的 local 形(seamless-local-cloud 铁律:StoreBackend
+ * kind tidb|pg|local 三态,附件面不得 cloud-only)。
+ *
+ * 布局:`<root>/attachments/<id>.json`(meta)+ `<id>.bin`(bytes)。id=uuidv7(server 铸,不含用户
+ * 输入 ⇒ 文件名安全);meta 内含 owner/session 轴,门在读侧比对(单机单进程,无并发租户;SQL 店才是
+ * 多租户形)。写=tmp+rename 原子(半写行不可见);索引=首次使用时全目录水合进内存 Map,之后同进程
+ * 内存权威(local 模式规模小;跨进程并发不在 local 契约内——与 file-run-store 同口径)。
+ */
 import { promises as fsp } from "node:fs";
 import { join } from "node:path";
-const ID_RE = /^[0-9a-f-]{16,64}$/i;
+const ID_RE = /^[0-9a-f-]{16,64}$/i; // uuid 形(server 铸);水合时非此形的文件一律跳过
 export class LocalTaskAttachmentStore {
     dir;
     metas;
@@ -24,10 +33,12 @@ export class LocalTaskAttachmentStore {
                         m.set(id, meta);
                 }
                 catch {
+                    /* 半写/损坏 meta:跳过(bin 无 meta 即孤儿,reap 收) */
                 }
             }
         }
         catch {
+            /* 目录不存在 = 空店 */
         }
         this.metas = m;
         return m;
@@ -40,6 +51,7 @@ export class LocalTaskAttachmentStore {
         const metaTmp = join(this.dir, `${rec.id}.json.tmp`);
         await fsp.writeFile(binTmp, Buffer.from(content));
         await fsp.rename(binTmp, join(this.dir, `${rec.id}.bin`));
+        // meta 后落:meta 在场 ⇒ bytes 必在场(读侧无半态)
         await fsp.writeFile(metaTmp, JSON.stringify(meta));
         await fsp.rename(metaTmp, join(this.dir, `${rec.id}.json`));
         metas.set(rec.id, { ...meta });
@@ -56,7 +68,7 @@ export class LocalTaskAttachmentStore {
             return new Uint8Array(await fsp.readFile(join(this.dir, `${id}.bin`)));
         }
         catch {
-            return null;
+            return null; // meta 在 bytes 丢(外力删档)——按不存在答,不抛
         }
     }
     async persistMeta(m) {

package/dist/plugins/mailbox-store-sql.d.ts

@@ -1,3 +1,40 @@
+/**
+ * MailboxStore SQL twins(design/151 S3c server pg 半场,[1530] 提货单①)——core teammate 信箱
+ * (SendMessage 链)的 TiDB/PG 双方言实现。挂载缝 = S3c 行为车的 `RunnerDeps.mailboxStore`(core
+ * 命名预告,[1530]§三);本文件先就绪 store 半场,行为车到货接线。
+ *
+ * 语义真源 = core `InMemoryMailboxStore`(dist/core/mailbox-store.js)+ [1530] 定谳(core 1.372
+ * 终版文本,conformance 无两可):
+ *  1. **同主重 claim = 续期 + 纳新**(crash-retry 正形):活 lease 只挡**别的** owner;同 owner 任意
+ *     时刻重 claim 重设 TTL 并拿到当前全部未 ack 消息(maxSeq 随最新行走)。
+ *  2. **seq = 盒生命周期内不复用**:box 行携 `next_seq`,分配与 append 同事务;`drop`/`reap` 删整盒
+ *     (含 box 行)= 生命周期终结,重建从 1(core 定谳:行随盒亡,dedup 键携 handle)。
+ *  3. **ack 无 owner 守卫**(信任 claim 赢者链):`seq <= upToSeq` 删行;lease 的 `maxSeq <= upToSeq`
+ *     时顺带清 lease(全量 ack = 释放)。
+ *  4. **lease 过期判 = 严格 `expiresAt > now` 才挡**;`releaseLease` 只在 owner 匹配时清。
+ *  5. `peekCount` 含已 lease 消息(可见性 ≠ lease 态);空盒 claim = null(box 行在而消息 0 也 null)。
+ *  6. **reap = SQL 全量真扫**(core File 实现只扫已加载盒 = 进程内 backstop,[1530] 确认 SQL 是全量
+ *     真扫的正确层):`maxAgeMs` 缺省 → 0;按盒 newest `sentAt < now - maxAgeMs` 删整盒;空盒(有
+ *     box 行无消息)不删(InMemory 同形——`newest === undefined` 不删)。
+ *
+ * 键列 = 字节等价(TiDB VARBINARY / PG COLLATE "C",roster F2 案):scope/handle/lease_owner 的
+ * `=` 必须纯字节——PAD SPACE 近撞不得穿隔离/抢别人 lease。PG unstorable bytes([1439] 三层定谳):
+ * `content` 是消息**内容面**(收件人将读到、注入对话)→ 与 PG 转录 payload 同族 lossy(pgSanitizeText,
+ * U+FFFD 标记,内容不失行);**身份键 scope/handle/owner/from 拒绝式**(pgHasUnstorable →
+ * PgUnstorableError fail-loud——attribution/路由键清洗形变 = 行与查询键错位,协议数据同向)。TiDB
+ * 侧 LONGTEXT/VARBINARY verbatim(replay 面定谳)。
+ *
+ * 并发正确性(InMemory 单进程无此象限、SQL 多副本有;发车复审 F2/F3/F4 批):
+ *  - **锁序统一「盒行 → 消息行」**(append/claim/ack/drop/reap 五面同序)——ack/drop/reap 原为
+ *    消息先行,与 claim 的盒先行构成 ABBA 死锁形;统一后同盒并发只在盒行锁上排队。
+ *  - drop/reap 先删/锁**盒行**再动消息:反序留「消息已删、盒行未删」窗,并发 append 完整穿过后
+ *    盒重建会撞存活的孤儿消息行(PK 冲突→此后 append 永久失败)。
+ *  - reap 候删 = 事务外粗筛 + 事务内**逐盒锁定重验**(当前读 newest):窗内新到的消息救活盒,
+ *    绝不连带删信;盒行已被并发 drop = 跳过不计。
+ *  - append 的 ensure 与 FOR UPDATE 之间被并发 drop 提交 = 同事务内重建一次(语义 = drop 后重建,
+ *    seq 从 1)。键长 > 190 字节写入即拒(fail-loud)——TiDB `INSERT IGNORE` 会把超长键**静默截断**,
+ *    截断键与全长查询参数字节比对恒 miss(分配读空行崩/隔离键错位)。
+ */
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
 import type { MailboxLease, MailboxStore } from "@sema-agent/core";
@@ -27,6 +64,7 @@ export declare class PgMailboxStore implements MailboxStore {
     private readonly pool;
     constructor(pool: PgPool);
     private tx;
+    /** 身份键拒绝式([1439] 协议纪律):scope/handle/owner/from 清洗形变 = 路由/attribution 错位。 */
     private assertIdentity;
     append(scope: string, handle: string, msg: {
         from?: string;

package/dist/plugins/mailbox-store-sql.js

@@ -1,11 +1,15 @@
 import { pgHasUnstorable, pgSanitizeText, PgUnstorableError } from "./pg-safe-json.js";
 export const MAILBOX_TABLE = "mailboxes";
 export const MAILBOX_MSG_TABLE = "mailbox_messages";
+/** InMemory append 同文案形(default-deny 谓词精神:无 scope 的盒=路由不明,写入即拒)。 */
 function assertScope(scope) {
     if (scope === undefined || scope === "") {
         throw new Error("MailboxStore.append: refusing a message without a scope");
     }
 }
+/** 键长守卫(复审 F5):TiDB `INSERT IGNORE` 对超 190 字节键**静默截断**(warning 降级)——截断键
+ *  与全长参数的字节比对恒 miss(seq 分配读空行 TypeError / 隔离键错位);PG 侧是干净 22001,同点
+ *  提前拒 = 双方言同文案 fail-loud。 */
 function assertKeyBytes(what, v) {
     if (Buffer.byteLength(v, "utf8") > 190) {
         throw new Error(`MailboxStore: ${what} exceeds the 190-byte key column (refusing — a truncated key would desync from its byte-exact lookups)`);
@@ -23,6 +27,8 @@ function rowToMessage(r) {
     };
 }
 export async function ensureTiDBMailboxSchema(pool) {
+    // VARBINARY 键列(bg-agent/roster 同案);lease_owner 同为字节等价(claim 的 owner 比对是身份判)。
+    // content LONGTEXT:消息正文可超 64K TEXT(转录段落/大 diff 转述)。
     await pool.query(`CREATE TABLE IF NOT EXISTS ${MAILBOX_TABLE} (
     scope_key VARBINARY(190) NOT NULL,
     handle VARBINARY(190) NOT NULL,
@@ -91,10 +97,14 @@ export class TiDBMailboxStore {
         assertScope(scope);
         assertKeyBytes("scope", scope);
         assertKeyBytes("handle", handle);
+        // ensure-first 形:先幂等 INSERT IGNORE 建盒(next_seq=1,首条/drop 后重建同臂)再 FOR UPDATE——
+        // 「无行 FOR UPDATE + INSERT」的并发死锁/dup 撞车形整个消掉;seq 分配与 append 同事务(定谳 2)。
         return this.tx(async (c) => {
             await c.query(`INSERT IGNORE INTO ${MAILBOX_TABLE} (scope_key, handle, scope, next_seq) VALUES (?, ?, ?, 1)`, [scope, handle, scope]);
             let [rows] = (await c.query(`SELECT next_seq FROM ${MAILBOX_TABLE} WHERE scope_key = ? AND handle = ? FOR UPDATE`, [scope, handle]));
             if (rows.length === 0) {
+                // ensure 与锁之间盒被并发 drop/reap 提交(复审 #5 窗)——同事务重建一次(语义 = drop 后重建,
+                // seq 从 1;同事务内自插行必可见,再空 = 真障碍 fail-loud)。
                 await c.query(`INSERT IGNORE INTO ${MAILBOX_TABLE} (scope_key, handle, scope, next_seq) VALUES (?, ?, ?, 1)`, [scope, handle, scope]);
                 [rows] = (await c.query(`SELECT next_seq FROM ${MAILBOX_TABLE} WHERE scope_key = ? AND handle = ? FOR UPDATE`, [scope, handle]));
             }
@@ -110,24 +120,35 @@ export class TiDBMailboxStore {
             if (boxes.length === 0)
                 return null;
             const box = boxes[0];
+            // 定谳 4:严格 expiresAt > now 才挡;定谳 1:同 owner 恒续期(字节等价比对——VARBINARY 读回 Buffer)。
+            // 残余记账(F7 TiDB 臂):owner 含 lone surrogate 时 mysql2 编码层塌缩 U+FFFD,读回串 ≠ 原参数
+            // → 同主续期被误拒(fail-closed 向,无越权);owner 是内部 mint 的 worker id(ASCII 域),接受。
             if (box.lease_owner !== null &&
                 Number(box.lease_expires_at_ms) > now &&
                 bufToStr(box.lease_owner) !== owner) {
                 return null;
             }
+            // FOR UPDATE = 当前读:TiDB 悲观事务的普通 SELECT 按 start_ts 快照(task-list twin 同案)——
+            // 锁到 box 行后消息集必须读「现在」,否则 drop+重建窗内老消息混进新盒 lease(maxSeq 错位)。
             const [msgs] = (await c.query(`SELECT seq, from_id, content, sent_at_ms FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? AND handle = ? ORDER BY seq FOR UPDATE`, [scope, handle]));
             if (msgs.length === 0)
-                return null;
+                return null; // 定谳 5:空盒 claim = null(box 行在也 null)
             const maxSeq = Number(msgs[msgs.length - 1].seq);
             await c.query(`UPDATE ${MAILBOX_TABLE} SET lease_owner = ?, lease_expires_at_ms = ?, lease_max_seq = ? WHERE scope_key = ? AND handle = ?`, [owner, now + ttlMs, maxSeq, scope, handle]);
             return { messages: msgs.map(rowToMessage), maxSeq };
         });
     }
     async ack(scope, handle, owner, upToSeq) {
+        // MB1/core 1.452 BREAKING:ack 带 **owner 围栏**(core InMemory 同语义:lease 缺席或 owner 不符 ⇒
+        // 整个 ack no-op,一条消息都不删——原「定谳 3 无守卫,信任 claim 赢者链」被 [1937] MB1 推翻:
+        // 任何人可删别人租约内消息)。锁序仍=盒行先(复审 F3 ABBA 死锁形);盒不存在=SELECT 空 ⇒ no-op。
         await this.tx(async (c) => {
             const [rows] = (await c.query(`SELECT lease_owner FROM ${MAILBOX_TABLE} WHERE scope_key = ? AND handle = ? FOR UPDATE`, [scope, handle]));
+            // 🔴 真双库抓的坑(2026-07-28,mock 无法抓):lease_owner 是 VARBINARY,mysql2 读回 **Buffer**——
+            // `Buffer !== string` 恒真 ⇒ 首版围栏把正主也拒了(所有 ack 恒 no-op)。bufToStr 字节等价比对,
+            // claim 的定谳 1 同坑同解(:186)。
             if (rows.length === 0 || rows[0].lease_owner == null || bufToStr(rows[0].lease_owner) !== owner)
-                return;
+                return; // 围栏:非当前持租者 ⇒ no-op
             await c.query(`DELETE FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? AND handle = ? AND seq <= ?`, [scope, handle, upToSeq]);
             await c.query(`UPDATE ${MAILBOX_TABLE} SET lease_owner = NULL, lease_expires_at_ms = NULL, lease_max_seq = NULL
          WHERE scope_key = ? AND handle = ? AND lease_max_seq IS NOT NULL AND lease_max_seq <= ?`, [scope, handle, upToSeq]);
@@ -142,6 +163,8 @@ export class TiDBMailboxStore {
         return Number(rows[0].n);
     }
     async drop(scope, handle) {
+        // 整盒删含 box 行 = seq 生命周期终结(定谳 2;重建从 1)。**盒行先删**(锁序统一 + F2:反序在
+        // 「消息已删、盒未删」窗放并发 append 穿过 → 盒重建撞孤儿消息行 PK,append 从此永败)。
         await this.tx(async (c) => {
             await c.query(`DELETE FROM ${MAILBOX_TABLE} WHERE scope_key = ? AND handle = ?`, [scope, handle]);
             await c.query(`DELETE FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? AND handle = ?`, [scope, handle]);
@@ -151,6 +174,9 @@ export class TiDBMailboxStore {
         if (opts?.maxAgeMs === undefined)
             return 0;
         const cutoff = now - opts.maxAgeMs;
+        // 全量真扫(定谳 6):事务外粗筛(索引面)+ 事务内逐盒「锁盒行 → 当前读重验 newest」(复审
+        // F2/F4:粗筛与删除之间窗内新到的消息必须救活盒,绝不连带删信;GROUP BY 不能 FOR UPDATE,
+        // 重验用 ORDER BY … LIMIT 1 当前读)。空盒不删(newest 无行);盒行已被并发 drop = 跳过。
         const [cands] = (await this.pool.query(`SELECT handle FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = ? GROUP BY handle HAVING MAX(sent_at_ms) < ?`, [scope, cutoff]));
         if (cands.length === 0)
             return 0;
@@ -193,6 +219,7 @@ export class PgMailboxStore {
             c.release();
         }
     }
+    /** 身份键拒绝式([1439] 协议纪律):scope/handle/owner/from 清洗形变 = 路由/attribution 错位。 */
     assertIdentity(what, v) {
         if (v !== undefined && pgHasUnstorable(v))
             throw new PgUnstorableError(`mailbox ${what}`);
@@ -202,9 +229,10 @@ export class PgMailboxStore {
         this.assertIdentity("scope", scope);
         this.assertIdentity("handle", handle);
         this.assertIdentity("from", msg.from);
-        const content = pgSanitizeText(msg.content);
+        const content = pgSanitizeText(msg.content); // 内容面 lossy(U+FFFD 标记,与 PG 转录 payload 同族)
         assertKeyBytes("scope", scope);
         assertKeyBytes("handle", handle);
+        // ensure-first 形(TiDB 同注):幂等建盒再 FOR UPDATE,死锁/dup 撞车形消。
         return this.tx(async (c) => {
             await c.query(`INSERT INTO ${MAILBOX_TABLE} (scope_key, handle, scope, next_seq) VALUES ($1, $2, $3, 1) ON CONFLICT (scope_key, handle) DO NOTHING`, [
                 scope,
@@ -213,6 +241,7 @@ export class PgMailboxStore {
             ]);
             let { rows } = await c.query(`SELECT next_seq FROM ${MAILBOX_TABLE} WHERE scope_key = $1 AND handle = $2 FOR UPDATE`, [scope, handle]);
             if (rows.length === 0) {
+                // ensure 与锁之间盒被并发 drop/reap 提交(TiDB 同注)——同事务重建一次。
                 await c.query(`INSERT INTO ${MAILBOX_TABLE} (scope_key, handle, scope, next_seq) VALUES ($1, $2, $3, 1) ON CONFLICT (scope_key, handle) DO NOTHING`, [
                     scope,
                     handle,
@@ -227,7 +256,7 @@ export class PgMailboxStore {
         });
     }
     async claimLease(scope, handle, owner, ttlMs, now = Date.now()) {
-        this.assertIdentity("owner", owner);
+        this.assertIdentity("owner", owner); // 复审 F7:lease 排他键同为身份键,裸 22021/塌缩比对都不许
         return this.tx(async (c) => {
             const { rows: boxes } = await c.query(`SELECT lease_owner, lease_expires_at_ms FROM ${MAILBOX_TABLE} WHERE scope_key = $1 AND handle = $2 FOR UPDATE`, [scope, handle]);
             if (boxes.length === 0)
@@ -244,17 +273,19 @@ export class PgMailboxStore {
         });
     }
     async ack(scope, handle, owner, upToSeq) {
+        // MB1 owner 围栏(TiDB 孪生同注);锁序=盒行先(F3 ABBA 死锁形消)。
         await this.tx(async (c) => {
             const r = (await c.query(`SELECT lease_owner FROM ${MAILBOX_TABLE} WHERE scope_key = $1 AND handle = $2 FOR UPDATE`, [scope, handle]));
+            // PG 列是 VARCHAR COLLATE "C"(读回 string,无 TiDB 臂的 Buffer 坑),bufToStr 幂等包一层求同形。
             if (r.rows.length === 0 || r.rows[0].lease_owner == null || bufToStr(r.rows[0].lease_owner) !== owner)
-                return;
+                return; // 围栏:非当前持租者 ⇒ no-op
             await c.query(`DELETE FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = $1 AND handle = $2 AND seq <= $3`, [scope, handle, upToSeq]);
             await c.query(`UPDATE ${MAILBOX_TABLE} SET lease_owner = NULL, lease_expires_at_ms = NULL, lease_max_seq = NULL
          WHERE scope_key = $1 AND handle = $2 AND lease_max_seq IS NOT NULL AND lease_max_seq <= $3`, [scope, handle, upToSeq]);
         });
     }
     async releaseLease(scope, handle, owner) {
-        this.assertIdentity("owner", owner);
+        this.assertIdentity("owner", owner); // F7 同注
         await this.pool.query(`UPDATE ${MAILBOX_TABLE} SET lease_owner = NULL, lease_expires_at_ms = NULL, lease_max_seq = NULL
        WHERE scope_key = $1 AND handle = $2 AND lease_owner = $3`, [scope, handle, owner]);
     }
@@ -263,6 +294,7 @@ export class PgMailboxStore {
         return Number(rows[0].n);
     }
     async drop(scope, handle) {
+        // 盒行先删(TiDB 同注,F2 孤儿消息行窗关死)。
         await this.tx(async (c) => {
             await c.query(`DELETE FROM ${MAILBOX_TABLE} WHERE scope_key = $1 AND handle = $2`, [scope, handle]);
             await c.query(`DELETE FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = $1 AND handle = $2`, [scope, handle]);
@@ -272,6 +304,7 @@ export class PgMailboxStore {
         if (opts?.maxAgeMs === undefined)
             return 0;
         const cutoff = now - opts.maxAgeMs;
+        // 事务外粗筛 + 事务内逐盒锁定重验(TiDB 同注,F2/F4:窗内新信救活盒,不丢信)。
         const { rows: cands } = await this.pool.query(`SELECT handle FROM ${MAILBOX_MSG_TABLE} WHERE scope_key = $1 GROUP BY handle HAVING MAX(sent_at_ms) < $2`, [scope, cutoff]);
         if (cands.length === 0)
             return 0;

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

@@ -1,21 +1,43 @@
 import type { MemoryHistoryAppendRow } from "./memory-sync-store-pg.js";
 import type { PgEmbedder, PgQueryFn } from "./pg-query.js";
 import type { MemoryBackend, MemoryEntry, MemoryEntryHeader, NotePatch, PatchReport, ScoredMemoryEntry } from "@sema-agent/core";
+/** Table names (single source). Deliberately DISJOINT from the legacy `agent_memory*` tables —
+ *  the retired MemoryStore plane and this entry plane must never cross-write. */
 export declare const PG_MEMORY_ENGINE_TABLES: {
     readonly entries: "agent_memory_engine_entries";
     readonly cursors: "agent_memory_engine_cursors";
 };
+/** Options for {@link ensurePgMemoryEngineSchema} — same `memoryVector` contract as PgAgentSchemaOptions. */
 export interface PgMemoryEngineSchemaOptions {
+    /** Omitted → `jsonb` embedding column (portable). `{ dimensions, pgvector: true }` → `CREATE EXTENSION
+     *  vector` + a `vector(d)` column (native `<=>`). Pick once; keep the backend options consistent. */
     memoryVector?: {
         dimensions: number;
         pgvector?: boolean;
     };
 }
+/** Idempotent DDL for the entry plane. Call once at startup (or run through your migration tool). */
 export declare function ensurePgMemoryEngineSchema(query: PgQueryFn, opts?: PgMemoryEngineSchemaOptions): Promise<void>;
+/** Options for {@link PgMemoryEngineBackend}. */
 export interface PgMemoryEngineBackendOptions {
+    /** Entries are embedded on add/update and `search` ranks by cosine distance. Absent → lexical floor. */
     embedder?: PgEmbedder;
+    /** `true` → rank in SQL via pgvector `<=>` (schema must carry `memoryVector: { pgvector: true }`).
+     *  Same migration note as PgMemoryStoreOptions: the SQL path EXCLUDES rows without an embedding —
+     *  backfill before enabling. Requires `embedder`. */
     pgvectorSql?: boolean;
+    /** Clock injection (file-backend precedent) — drives `mtime_ms`. Default `Date.now`. */
     now?: () => number;
+    /** 142-S5.1 history write point (改动 vs origin): OPTIONAL audit sink — every APPLIED
+     *  patch appends one `agent_memory_engine_history` row (add=chain head/update=prevRev link/
+     *  delete=tombstone) AFTER its entry write commits. Absent → byte-equal legacy behavior (additive).
+     *  ⚠️ 同事务诚实记档:the 142-S4 design draft says "同事务追加", but this backend's ONLY DB seam is
+     *  a bare `PgQueryFn` — with a pooled query fn, BEGIN/COMMIT statements may land on DIFFERENT
+     *  connections, so a true transaction would require refactoring the constructor to a client-checkout
+     *  seam (breaks the origin-core@3071dd3 minimal-diff move-in discipline).
+     *  Chosen trade-off: entry write commits first, history append is BEST-EFFORT
+     *  (failure = swallow + console.warn) — history is the AUDIT face, not the correctness face: a lost
+     *  history row loses an audit line, never data (the entries table stays the single truth). */
     history?: {
         appendHistory(rows: readonly MemoryHistoryAppendRow[]): Promise<void>;
     };
@@ -26,10 +48,15 @@ export declare class PgMemoryEngineBackend implements MemoryBackend {
     private readonly pgvectorSql;
     private readonly clock;
     private readonly history?;
+    /** Cumulative lost-row count — audit-line breakage must itself be auditable. */
     private historyRowsLost;
+    /** design/81 rung indicator — same semantics as PgMemoryStore.vectorMode. */
     get vectorMode(): "native" | "portable" | "lexical";
     constructor(query: PgQueryFn, opts?: PgMemoryEngineBackendOptions);
+    /** The embed/search haystack — BYTE-EQUAL to FileBackend's lexical haystack (file-backend search). */
     private haystackOf;
+    /** Dimension-guarded embedding parameter (mirrors PgMemoryStore.embeddingParam — wrong-length ⇒ null,
+     *  the row falls open to the lexical stand-in instead of poisoning reads). */
     private embeddingParam;
     private headerFromRow;
     private entryFromRow;
@@ -40,6 +67,9 @@ export declare class PgMemoryEngineBackend implements MemoryBackend {
     }): Promise<ScoredMemoryEntry[]>;
     applyPatches(patches: readonly NotePatch[]): Promise<PatchReport>;
     private applyOne;
+    /** When the conditional write returns zero rows (a write landed inside the
+     *  SELECT→write window), the report's `currentRev` must be the rev NOW — re-reporting the pre-race
+     *  SELECT value could claim `baseRev === currentRev` alongside a "rev mismatch" reason. */
     private freshRev;
     getConsolidationCursor(scope: string): Promise<string | undefined>;
     setConsolidationCursor(scope: string, cursor: string): Promise<void>;