@sema-agent/server 7.43.0 → 7.44.0

package/dist/plugins/shared-memory-store-sql.js

@@ -1,28 +1,14 @@
 import { SHARED_MEMORY_READ_CAP_BYTES, SharedMemoryStoreError, } from "@sema-agent/core";
 import { mysqlDriver, pgDriver } from "./sql-driver.js";
 import { isDupKeyError } from "./sql-errors.js";
-/** 唯一键冲突的方言判别 —— 判据属主 = `sql-errors.ts`(A-032 P1-①:本站点原是全仓唯一的硬化形,
- *  收编时把它**升格成属主**,其余六处按它对齐;`Reflect.get` 走原型链的理由见属主头注)。
- *  只用来把并发登记撞 PK 翻成一句人话,不让驱动错误对象漏给调用方。 */
 const isDupKey = isDupKeyError;
-/** Per-org plane state (`connecting` / `unavailable` / `connected`). One row per org scope. */
 export const SHARED_MEMORY_SCOPE_TABLE = "shared_memory_scope";
-/** The model-facing store registry: one row per browsable library. */
 export const SHARED_MEMORY_STORE_TABLE = "shared_memory_store";
-/** The documents. One row per (store, path). */
 export const SHARED_MEMORY_ENTRY_TABLE = "shared_memory_entry";
-/** core's store-id rule, restated on the WRITE side: `/^[A-Za-z0-9_.-]{1,64}$/` and no `__` (the
- *  protocol table's namespace separator). A row failing it would be dropped from every listing — an id
- *  the model cannot echo back is worse than an absent one — so we refuse to store it in the first place. */
 const STORE_ID_RE = /^[A-Za-z0-9_.-]{1,64}$/;
-/** core's org scope shape, shared with org-memory-admission. */
 const ORG_SCOPE_RE = /^org:\S{1,185}$/;
-/** core's FORBIDDEN_PATH_CHARS, restated. A path carrying any of these is dropped by core's listing gate. */
 const FORBIDDEN_PATH_CHARS = /[\p{Cc}\p{Cf}\p{Co}\p{Cn}\p{Default_Ignorable_Code_Point}\u2028\u2029\\]/u;
-/** core's DOCUMENT_SUFFIXES, restated. */
 const DOCUMENT_SUFFIXES = [".md", ".txt", ".json", ".jsonl"];
-/** The `path` column width. core's own bound is 1024 UTF-16 units; the column is the tighter of the two
- *  and is enforced here so an over-long path fails LOUDLY instead of being truncated by the engine. */
 const PATH_MAX_CHARS = 512;
 const DESCRIPTION_MAX_CHARS = 512;
 const DEFAULT_MAX_LIST_LIMIT = 500;
@@ -36,11 +22,6 @@ export function assertScopeKey(scopeKey) {
         throw new Error(`shared-memory scope key ${JSON.stringify(scopeKey)} is not usable: it must match /^org:\\S{1,185}$/`);
     }
 }
-/**
- * WRITE-side document-path admission. Deliberately at least as strict as core's READ-side listing gate
- * (`isListablePath`): a row core would silently drop is refused here where an operator can see it. The
- * ONE rule that is stricter on purpose is the non-BMP refusal — see the header's ORDERING section.
- */
 export function assertDocumentPath(path) {
     const refuse = (why) => {
         throw new Error(`shared-memory document path ${JSON.stringify(path)} is not usable: ${why}`);
@@ -57,27 +38,17 @@ export function assertDocumentPath(path) {
     const last = segments.at(-1);
     if (last === undefined || !DOCUMENT_SUFFIXES.some((s) => last.endsWith(s)))
         refuse(`the filename must end in ${DOCUMENT_SUFFIXES.join(", ")}`);
-    // Non-BMP refusal: SQL orders by code point, core's cursor progress check compares in UTF-16 code
-    // units, and the two disagree ONLY above the BMP. Refusing here keeps "the listing is complete" a
-    // structural fact instead of a probabilistic one.
     for (const ch of path) {
         if (ch.codePointAt(0) > 0xffff)
             refuse("it carries a supplementary-plane character, which would make SQL ordering and core's UTF-16 cursor ordering disagree");
     }
 }
-/** `path` values that start with `prefix` live in `[prefix, succ(prefix))`. `undefined` upper bound ⇒
- *  the range degenerates to `>= prefix`, which is still a legal SUPERSET (core re-filters), just wider. */
 function prefixUpperBound(prefix) {
     const lastUnit = prefix.charCodeAt(prefix.length - 1);
-    // Stop short of the surrogate block: incrementing into 0xD800 would build a lone surrogate, which is
-    // not encodable as UTF-8 and would be rejected by both drivers.
     if (!Number.isFinite(lastUnit) || lastUnit >= 0xd7ff)
         return undefined;
     return prefix.slice(0, -1) + String.fromCharCode(lastUnit + 1);
 }
-/** `unavailable` beats `connecting` beats `connected`. A caller whose orgs are PARTLY down is told the
- *  plane is down rather than served a silently partial store set — a partial set is indistinguishable
- *  from "your team's library has these three documents", which is the failure this state exists to name. */
 function foldPlaneState(states) {
     let sawConnecting = false;
     for (const state of states) {
@@ -93,8 +64,6 @@ function foldPlaneState(states) {
     }
     return sawConnecting ? "connecting" : "connected";
 }
-/** The stored word, re-read. An unknown word in the column is a corrupted/foreign write: refuse the
- *  whole snapshot rather than guess (this is the authorization/availability axis — no silent default). */
 function planeStateOf(raw) {
     const word = String(raw);
     switch (word) {
@@ -115,12 +84,6 @@ function throwIfAborted(signal) {
     const reason = signal.reason;
     throw reason instanceof Error ? reason : new Error("shared-memory read aborted");
 }
-/**
- * 回滚,但**绝不让回滚的失败顶掉主错**(codex 轮2 收尾建议)。裸 `await conn.rollback()` 放在 catch 里,
- * 一旦连接已经坏掉(回滚本身抛),抛出去的就变成了回滚错误,真正的失败原因当场丢失 —— 那是排障时最贵的
- * 一种信息损失。这里吞的只有**次要**错误,而且吞得出声(warn 带上主错);连接由调用方的 finally 归还,
- * 池会在下次取用时体检它。
- */
 async function rollbackPreservingError(conn, primary) {
     try {
         await conn.rollback();
@@ -130,16 +93,11 @@ async function rollbackPreservingError(conn, primary) {
     }
 }
 function storeGone(storeId) {
-    // core folds `store_not_found` to "The memory store was not found — it may not be provisioned yet."
-    // The alternative (an empty listing) would read to the model as "your team's library is empty".
     return new SharedMemoryStoreError("store_not_found", { message: `shared memory store ${JSON.stringify(storeId)} is no longer provisioned` });
 }
 function rowToStoreInfo(r) {
     return { id: String(r.store_id), description: String(r.description), writable: Boolean(Number(r.writable)) };
 }
-/** 列举行。`sizeBytes` 取 `size_bytes` 列 —— 这是**展示用提示**,不是安全判据:该列独立可写,一个外来
- *  写者可以让它与真实长度不符。任何**决定**(读帽)都必须现算 `OCTET_LENGTH(content)`(见 readDocument);
- *  列举不现算是刻意的取舍:对一整窗 LONGTEXT 逐行算字节等于把每次列举变成全文扫描。 */
 function rowToEntry(r) {
     const updatedAt = strOrNull(r.updated_at_iso);
     return {
@@ -148,10 +106,6 @@ function rowToEntry(r) {
         ...(updatedAt !== null ? { updatedAt } : {}),
     };
 }
-/**
- * The dual-dialect implementation. Every statement is written out in BOTH texts at its call site
- * (design/158 A12 判据:方言差异必须显式) — the `q(tidbSql, pgSql)` helper never builds one text.
- */
 export class SqlSharedMemoryStore {
     db;
     authorizer;
@@ -166,31 +120,17 @@ export class SqlSharedMemoryStore {
     q(tidb, pg) {
         return this.db.dialect === "tidb" ? tidb : pg;
     }
-    // ───────────────────────────── the core-facing half (read only) ─────────────────────────────
-    /**
-     * ONE registry-binding snapshot per tool call, as core's seam requires: the state, the store identity
-     * set and each reader binding all come from this one call, so the set cannot change between "list the
-     * stores" and "resolve one". Document state stays live — which is why a store can still vanish between
-     * binding and read, the case {@link storeGone} names.
-     */
     async snapshot(ctx, opts) {
         throwIfAborted(opts.signal);
         const grant = await this.authorizer.resolve(ctx.principal);
         if (grant.kind === "unavailable") {
-            // Host-authored reason, bounded and folded to one line by core. NOT "no stores" — see header.
             return { state: "unavailable", message: `shared memory authorization is unavailable (${grant.reason})` };
         }
         const scopes = [...new Set(grant.scopes)];
         if (scopes.length === 0)
             return { state: "connected", stores: [] };
         throwIfAborted(opts.signal);
-        // 🔴 codex 复审轮2 F3:盘状态与库登记必须来自**同一个数据库快照**。两条独立的池查询之间,一次
-        // 导入可以把 scope 翻成 connecting 再发布新库 —— 请求于是看到"老状态 connected + 新库",一个
-        // 数据库瞬间都不曾出现过的组合,而 connecting 这道门的全部意义正是拦住半截导入的库。
-        // 事务成本(一次连接借出 + 两次往返)由 core 每个工具调用取一次快照的频次承担;这是授权/可见性
-        // 面,一致性优先于省一次借出。
         const { scopeRows, storeRows } = await this.readBinding(scopes);
-        // A scope with no row has never been provisioned — that is "connected with nothing in it", not a fault.
         const folded = foldPlaneState(scopeRows.map((r) => planeStateOf(r.state)));
         if (folded === "unavailable") {
             const message = strOrNull(scopeRows.find((r) => planeStateOf(r.state) === "unavailable")?.message);
@@ -202,23 +142,10 @@ export class SqlSharedMemoryStore {
             state: "connected",
             stores: storeRows.map((r) => ({
                 info: rowToStoreInfo(r),
-                // The reader is PINNED to (store, scope) taken at binding time: a store re-homed to another org
-                // between snapshot and read cannot be reached through the stale binding (it reads as vanished).
                 reader: this.readerFor(String(r.store_id), String(r.scope_key)),
             })),
         };
     }
-    /**
-     * 盘状态 + 库登记,**一个事务一个快照**(轮2 F3 修)。
-     *
-     * 🔴 A-010.11(两臂不对称,验真后修):此前 PG 臂显式抬隔离级别、**MySQL 臂只靠服务端默认值**,
-     * 注里写的是「MySQL/TiDB 的默认隔离级别就是 REPEATABLE READ ⇒ 天然同快照」。那句话对**默认配置**
-     * 为真,但 `transaction_isolation` 是可设的服务端/会话变量:一台跑 READ COMMITTED 的实例(托管
-     * MySQL 的厂商默认、中间层代理、运维手改)会把「一个事务一个快照」悄悄降成「每条语句各自取快照」,
-     * 而本方法**不会报任何错**——它只是读到一对撕裂的 scope/store 行。「靠默认值成立」不是结构保证。
-     * 两臂现在都走 {@link SqlTxConn.beginRepeatableRead}(语句文本与**摆放位置**的方言分歧写在那里:
-     * MySQL 必须在 BEGIN **之前**发、PG 必须在 BEGIN **之后**发)。
-     */
     async readBinding(scopes) {
         const conn = await this.db.connect();
         try {
@@ -242,14 +169,9 @@ export class SqlSharedMemoryStore {
             read: (path, opts) => this.readDocument(storeId, scopeKey, path, opts),
         };
     }
-    /** One keyset window. Always the PAGED shape — a large library must never be materialized per call. */
     async listDocuments(storeId, scopeKey, prefix, opts) {
         throwIfAborted(opts.signal);
         const limit = Math.max(1, Math.min(Math.floor(opts.limit ?? this.maxListLimit) || 1, this.maxListLimit));
-        // The predicate set is genuinely dynamic (cursor and prefix are each optional and independent), so
-        // the two texts are built from ONE clause list rather than written out twice — but the divergence
-        // stays visible: `ph()` is the only thing that differs, and both texts are logged side by side by
-        // the parity harness. Column list and ORDER BY are byte-identical on both dialects.
         const clauses = [];
         const params = [];
         const bind = (value, clause) => {
@@ -257,27 +179,19 @@ export class SqlSharedMemoryStore {
             const position = params.length;
             clauses.push((ph) => clause(ph(position)));
         };
-        // 🔴 codex 复审轮1 F4(真缺陷,已红先复现):列举必须**在主查询里**要求绑定时的 scope,不能只在
-        // 空结果时补查。原式只按 store_id 过滤 ⇒ 一个 id 被回收给另一个 org 之后,旧 reader 只要新属主有
-        // 文档就能列出对方的 path/大小/时间(正文读那条腿一直核 scope,所以这是一次纯元数据泄漏——更隐蔽)。
         bind(scopeKey, (p) => `s.scope_key = ${p}`);
         bind(storeId, (p) => `e.store_id = ${p}`);
-        // EXCLUSIVE lower bound — core's cursor vocabulary, unchanged.
         if (opts.cursor !== undefined)
             bind(opts.cursor, (p) => `e.path > ${p}`);
         if (prefix !== undefined && prefix !== "" && prefix !== "/") {
             bind(prefix, (p) => `e.path >= ${p}`);
             const upper = prefixUpperBound(prefix);
-            // Absent upper bound ⇒ the range degenerates to `>= prefix`: a WIDER superset, which core
-            // re-filters. Never a miss, so this arm needs no compensating knob.
             if (upper !== undefined)
                 bind(upper, (p) => `e.path < ${p}`);
         }
         const whereFor = (ph) => clauses.map((c) => c(ph)).join(" AND ");
         const limitPosition = params.length + 1;
         const from = `FROM ${SHARED_MEMORY_ENTRY_TABLE} e JOIN ${SHARED_MEMORY_STORE_TABLE} s ON s.store_id = e.store_id`;
-        // Fetch one past the window: the extra row IS the "more remain" evidence, so `nextCursor` is a fact
-        // rather than a guess (core consumes it as a HAS-MORE declaration).
         const res = await this.db.query(this.q(`SELECT e.path AS path, e.size_bytes AS size_bytes, e.updated_at_iso AS updated_at_iso ${from} WHERE ${whereFor(() => "?")} ORDER BY e.path LIMIT ?`, `SELECT e.path AS path, e.size_bytes AS size_bytes, e.updated_at_iso AS updated_at_iso ${from} WHERE ${whereFor((n) => `$${n}`)} ORDER BY e.path LIMIT $${limitPosition}`), [...params, limit + 1]);
         if (res.rows.length === 0 && !(await this.storeExists(storeId, scopeKey)))
             throw storeGone(storeId);
@@ -286,21 +200,8 @@ export class SqlSharedMemoryStore {
         const last = window.at(-1);
         return { entries: window, ...(hasMore && last !== undefined ? { nextCursor: last.path } : {}) };
     }
-    /** `null` = the document does not exist. Absence is a VALUE here; only a VANISHED STORE is an error. */
     async readDocument(storeId, scopeKey, path, opts) {
         throwIfAborted(opts.signal);
-        // One statement answers both questions: the LEFT JOIN keeps the store row even when the document is
-        // absent, so zero rows means the STORE is gone (error) and a row with a NULL path means the DOCUMENT
-        // is gone (value). Two separate SELECTs would leave a window where they disagree.
-        //
-        // 🔴 codex 轮1 F2b + 轮2 F1:`content` 走一层 CASE 门,超帽的行**在数据库里就不发字节** —— 否则一份
-        // LONGTEXT 级的文档每次读都要整个物化进进程内存,而它到了 core 那里横竖是被拒的。写面已经把帽挡在
-        // 入库(见 putDocument),这道是第二层:接管旧版/别的写者留下的行。
-        //
-        // 判据取 `OCTET_LENGTH(e.content)` 而**不是** `size_bytes` 列(轮2 修):那一列是独立可写的元数据,
-        // 没有任何约束把它绑在真实内容长度上。**低报**方向才是危险的那个 —— 一行"小 size_bytes + 巨大
-        // content"会让 CASE 门整个失效并把全文物化。真实字节数由引擎现算,元数据说什么都不影响安全判定
-        // (`size_bytes` 因此降级为纯展示用的列举提示,见 rowToEntry)。
         const res = await this.db.query(this.q(`SELECT e.path AS path, OCTET_LENGTH(e.content) AS content_bytes, CASE WHEN OCTET_LENGTH(e.content) <= ? THEN e.content ELSE NULL END AS content, e.updated_at_iso AS updated_at_iso
            FROM ${SHARED_MEMORY_STORE_TABLE} s
            LEFT JOIN ${SHARED_MEMORY_ENTRY_TABLE} e ON e.store_id = s.store_id AND e.path = ?
@@ -314,25 +215,18 @@ export class SqlSharedMemoryStore {
         if (strOrNull(row.path) === null)
             return null;
         if (Number(row.content_bytes) > SHARED_MEMORY_READ_CAP_BYTES) {
-            // A typed refusal, not a truncation and not a `null`: core folds `refused` with the host reason,
-            // and the model is told the document exists but cannot be served — which is true. The byte count
-            // in the message is the ENGINE's, so it is right even when the metadata column lies.
             throw new SharedMemoryStoreError("refused", {
                 reason: "document_too_large",
                 message: `shared memory document ${JSON.stringify(path)} is ${String(row.content_bytes)} bytes, over the ${SHARED_MEMORY_READ_CAP_BYTES}-byte read cap`,
             });
         }
         const updatedAt = strOrNull(row.updated_at_iso);
-        // Content is returned code-unit EXACT: no normalization, no scrubbing. core owns sanitizing, and a
-        // provider that pre-sanitized would make the model read different bytes than the library holds.
         return { content: String(row.content), ...(updatedAt !== null ? { updatedAt } : {}) };
     }
     async storeExists(storeId, scopeKey) {
         const res = await this.db.query(this.q(`SELECT store_id FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = ? AND scope_key = ?`, `SELECT store_id FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = $1 AND scope_key = $2`), [storeId, scopeKey]);
         return res.rows.length > 0;
     }
-    // ───────────────────────── the DEPLOYMENT admin half (never model-facing) ─────────────────────────
-    /** Declare an org's plane state. Absent row ⇒ `connected` (a never-provisioned org simply has no stores). */
     async putScopeState(scopeKey, state, message) {
         assertScopeKey(scopeKey);
         const now = this.now();
@@ -340,18 +234,6 @@ export class SqlSharedMemoryStore {
            ON DUPLICATE KEY UPDATE state = VALUES(state), message = VALUES(message), updated_at_ms = VALUES(updated_at_ms)`, `INSERT INTO ${SHARED_MEMORY_SCOPE_TABLE} (scope_key, state, message, updated_at_ms) VALUES ($1, $2, $3, $4)
            ON CONFLICT (scope_key) DO UPDATE SET state = EXCLUDED.state, message = EXCLUDED.message, updated_at_ms = EXCLUDED.updated_at_ms`), [scopeKey, state, message ?? null, now]);
     }
-    /**
-     * Register (or re-describe) one browsable store.
-     *
-     * 🔴 codex 复审轮1 F1(真缺陷,已红先复现):**属主 org 不可变**。原式是一条 upsert,`scope_key` 跟着
-     * 被改写 —— 而文档行只按 `store_id` 编键、原地不动。于是一次撞 id 的导入(管理面手滑、重试、坏配置,
-     * 零竞态)就把 A 的整座库连内容一起交给了 B,同时 A 失去它。所以这里改成:已存在的 id 只允许它自己的
-     * org 更新描述/writable 位,换 org 一律响亮拒。真要迁库,那是一次需要显式审计的搬迁(先删再建,内容
-     * 由搬迁方决定重导还是丢弃),不能是一条 upsert 的副作用。
-     *
-     * 事务 + 行锁:属主判定与写入之间不留窗口(同一把锁 {@link deleteStore} 也拿)。并发到达的两个新建
-     * 会有一个撞 PK —— 那条也翻成同一句拒绝,不让驱动错误对象漏给调用方。
-     */
     async putStore(record) {
         assertStoreId(record.storeId);
         assertScopeKey(record.scopeKey);
@@ -359,11 +241,10 @@ export class SqlSharedMemoryStore {
             throw new Error(`shared-memory store ${JSON.stringify(record.storeId)} description is ${record.description.length} chars, over the ${DESCRIPTION_MAX_CHARS} the column stores`);
         }
         const now = this.now();
-        // 冲突事实在事务里查明、在事务外抛:避免"分支里 rollback + catch 里再 rollback"的双回滚吞异常形。
         let ownedBy;
         const conn = await this.db.connect();
         try {
-            await conn.begin(); // 为什么不是 beginPessimistic:见 {@link SqlSharedMemoryStore} 头注的"事务与锁"段
+            await conn.begin();
             const existing = await conn.query(this.q(`SELECT scope_key FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = ? FOR UPDATE`, `SELECT scope_key FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = $1 FOR UPDATE`), [record.storeId]);
             const owner = existing.rows[0] === undefined ? undefined : String(existing.rows[0].scope_key);
             if (owner !== undefined && owner !== record.scopeKey) {
@@ -393,18 +274,6 @@ export class SqlSharedMemoryStore {
             throw new Error(`shared-memory store id ${JSON.stringify(record.storeId)} is already owned by ${JSON.stringify(ownedBy)} — a store's org is IMMUTABLE (re-homing it would hand every document already written under it to ${JSON.stringify(record.scopeKey)}). Delete it explicitly first if a transfer is really intended.`);
         }
     }
-    /**
-     * Write one document. Refuses when the store is not registered — an orphan document is unreachable
-     * through the read face, so accepting it would be a silent no-op the writer never learns about, AND a
-     * live landmine: whoever re-registers that id later inherits it.
-     *
-     * 🔴 codex 复审轮1 F2/F3 两修:
-     *  · 帽在**入库**成立 —— 超 `SHARED_MEMORY_READ_CAP_BYTES` 的文档 core 横竖恒拒(从不截断),存下来
-     *    只是一行永远读不出来的死数据,却让每次读都要物化它。写面拒 = 那个帽在结构上为真。库里真有超大
-     *    文档的话,导入方分块——这是它自己就得做的事,因为模型面本来也读不到整份。
-     *  · 存在性检查与写入**同事务同行锁**(与 {@link deleteStore} 争同一把):否则一次并发删除可以从检查
-     *    与插入之间穿过去,留下一行孤儿文档 —— 被删的内容在 id 复用时复活。
-     */
     async putDocument(record) {
         assertStoreId(record.storeId);
         assertScopeKey(record.scopeKey);
@@ -417,7 +286,7 @@ export class SqlSharedMemoryStore {
         let unregistered = false;
         const conn = await this.db.connect();
         try {
-            await conn.begin(); // 为什么不是 beginPessimistic:见 {@link SqlSharedMemoryStore} 头注的"事务与锁"段
+            await conn.begin();
             const registered = await conn.query(this.q(`SELECT store_id FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = ? AND scope_key = ? FOR UPDATE`, `SELECT store_id FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = $1 AND scope_key = $2 FOR UPDATE`), [record.storeId, record.scopeKey]);
             if (registered.rows.length === 0) {
                 unregistered = true;
@@ -441,20 +310,6 @@ export class SqlSharedMemoryStore {
             throw new Error(`shared-memory store ${JSON.stringify(record.storeId)} is not registered under ${JSON.stringify(record.scopeKey)} — either it was never created, or the id has since been recycled by another org (call putStore() first; a stale retry must NOT land in the new tenant's library)`);
         }
     }
-    /**
-     * Remove one document. Scope-fenced like {@link putDocument} (a stale delete must not reach a
-     * successor tenant's library). Returns whether a row was actually there.
-     *
-     * 🔴 A-010.14(验真后修):此前围栏是**两条独立语句** —— `assertOwnedBy()` 先查一次登记表,然后另
-     * 起一条 DELETE。它自称与 `putDocument` 对齐,但 `putDocument` 的检查与写是**同事务同行锁**
-     * (`FOR UPDATE`),而这里的两条语句之间有一道真窗:登记检查通过之后、DELETE 发出之前,另一个 org
-     * 完成 `deleteStore` + `putStore` 的 id 复用,这条 DELETE 就落进**继任租户**的库里删掉他们的文档。
-     * 那正是 `putDocument` 的注里写明要挡住的那一形。现在逐字照它:同一事务、对登记行 `FOR UPDATE`、
-     * 拿到锁之后再删。
-     *
-     * 「未登记 ⇒ 响亮抛」与「登记了但没这条文档 ⇒ 回 false」两件事仍然分家(调用方据此分支),所以
-     * 不能收成一条 `DELETE … WHERE EXISTS(…)`:那样 `affected === 0` 会把两种结局压成同一个读数。
-     */
     async deleteDocument(storeId, scopeKey, path) {
         assertStoreId(storeId);
         assertScopeKey(scopeKey);
@@ -462,7 +317,7 @@ export class SqlSharedMemoryStore {
         let deleted = false;
         const conn = await this.db.connect();
         try {
-            await conn.begin(); // 为什么不是 beginPessimistic:见本类头注的"事务与锁"段(与 putDocument 同判)
+            await conn.begin();
             const registered = await conn.query(this.q(`SELECT store_id FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = ? AND scope_key = ? FOR UPDATE`, `SELECT store_id FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = $1 AND scope_key = $2 FOR UPDATE`), [storeId, scopeKey]);
             if (registered.rows.length === 0) {
                 unregistered = true;
@@ -482,33 +337,17 @@ export class SqlSharedMemoryStore {
             conn.release();
         }
         if (unregistered) {
-            // 文案逐字同 assertOwnedBy(调用方/测试按它对表);围栏的**执行面**改了,拒绝的**说法**没改。
             throw new Error(`shared-memory store ${JSON.stringify(storeId)} is not registered under ${JSON.stringify(scopeKey)} — either it does not exist, or the id has since been recycled by another org`);
         }
         return deleted;
     }
-    // 属主围栏的共用断言 `assertOwnedBy()` 曾住在这里(轮3 F1)。A-010.14 把它**唯一**的消费者
-    // (`deleteDocument`)改成「同事务 + FOR UPDATE」之后它就没有调用点了 —— 留着一个自带围栏语义却
-    // 无人调用的私有方法,下一个人会以为「围栏在这儿,照着调就行」,而它恰恰是被判定为不够强的那一版。
-    // 边界的如实说明随之搬进 `deleteDocument` / `putDocument`:两者**都不**覆盖同一个 org 内的
-    // "删了又建"代际重用 —— 那不是跨租户面,真要挡住需要一枚不可变的 generation token。
-    /**
-     * De-register a store AND its documents, ATOMICALLY.
-     *
-     * 🔴 codex 复审轮1 F3(真缺陷):原式是两条独立语句。崩在中间会留下「登记着但被悄悄清空」的库,而
-     * 并发的 {@link putDocument} 能从检查与插入之间穿过去留下孤儿行 —— 被删的内容会在这个 id 被重新登记时
-     * 复活。现在两条删除同事务,并且**先拿注册行的行锁**:写面争的是同一把锁,两者因此串行。
-     *
-     * 🔴 轮3 F1 同族:必须带 `scopeKey` 围栏。id 删后可复用,而一条**迟到的** deleteStore 若只按 id 寻址,
-     * 会把继任租户刚建好的库连内容一起抹掉 —— 一次歧义的重试变成一次跨租户的破坏性操作。
-     */
     async deleteStore(storeId, scopeKey) {
         assertStoreId(storeId);
         assertScopeKey(scopeKey);
         let notOwned = false;
         const conn = await this.db.connect();
         try {
-            await conn.begin(); // 为什么不是 beginPessimistic:见 {@link SqlSharedMemoryStore} 头注的"事务与锁"段
+            await conn.begin();
             const owned = await conn.query(this.q(`SELECT store_id FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = ? AND scope_key = ? FOR UPDATE`, `SELECT store_id FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = $1 AND scope_key = $2 FOR UPDATE`), [storeId, scopeKey]);
             if (owned.rows.length === 0) {
                 notOwned = true;
@@ -532,13 +371,11 @@ export class SqlSharedMemoryStore {
         }
     }
 }
-/** MySQL-protocol (MySQL / TiDB) binding. */
 export class TiDBSharedMemoryStore extends SqlSharedMemoryStore {
     constructor(pool, authorizer, opts) {
         super(mysqlDriver(pool), authorizer, opts);
     }
 }
-/** PostgreSQL binding. */
 export class PgSharedMemoryStore extends SqlSharedMemoryStore {
     constructor(pool, authorizer, opts) {
         super(pgDriver(pool), authorizer, opts);

package/dist/plugins/sql-driver.js

@@ -1,5 +1,4 @@
 import { pgSafeJsonStringify, pgProtocolJsonStringify } from "./pg-safe-json.js";
-/** mysql2 hands back `[rows]` for a SELECT and `[ResultSetHeader]` for a write. */
 function mysqlResult(r) {
     if (Array.isArray(r))
         return { rows: r, affected: 0 };
@@ -10,8 +9,6 @@ async function mysqlQuery(q, sql, params) {
     const [r] = (await q.query(sql, params ?? []));
     return mysqlResult(r);
 }
-/** MySQL-protocol (TiDB) driver. Transaction control uses mysql2's NATIVE methods — the historical
- *  call shape the fake-pool unit suites script around. */
 export function mysqlDriver(pool) {
     return {
         dialect: "tidb",
@@ -24,8 +21,6 @@ export function mysqlDriver(pool) {
                 beginPessimistic: async () => {
                     await c.query("BEGIN PESSIMISTIC");
                 },
-                // Scope-less `SET TRANSACTION …` = next-transaction only, so it goes BEFORE the BEGIN and
-                // leaves the pooled connection's session default untouched for whoever gets it next.
                 beginRepeatableRead: async () => {
                     await c.query("SET TRANSACTION ISOLATION LEVEL REPEATABLE READ");
                     await c.beginTransaction();
@@ -41,7 +36,6 @@ async function pgQuery(q, sql, params) {
     const res = await q.query(sql, params ?? []);
     return { rows: (res.rows ?? []), affected: res.rowCount ?? 0 };
 }
-/** PostgreSQL driver. Transaction control is issued as STATEMENTS (node-pg has no native verbs). */
 export function pgDriver(pool) {
     return {
         dialect: "pg",
@@ -56,8 +50,6 @@ export function pgDriver(pool) {
                 beginPessimistic: async () => {
                     await c.query("BEGIN");
                 },
-                // PG takes it INSIDE the transaction (and only before its first query) — the mirror image of
-                // the MySQL arm above. Same verb, deliberately different placement.
                 beginRepeatableRead: async () => {
                     await c.query("BEGIN");
                     await c.query("SET TRANSACTION ISOLATION LEVEL REPEATABLE READ");
@@ -73,15 +65,6 @@ export function pgDriver(pool) {
         },
     };
 }
-/** design/158 redesign① — the "safe" JSON-column encoder DISPATCH (run-store/outcome-ledger's identical
- *  ternary, collected): TiDB stores `JSON.stringify` verbatim; PG goes through `pgSafeJsonStringify`'s
- *  protocol-byte defenses (a raw NUL/lone-surrogate would otherwise throw mid-write). Returns a 1-arg
- *  encoder; call sites invoke `dialectJsonEncoder(this.db.dialect)(value)` inline — the dispatch is the
- *  collected thing, not a cached field. */
 export const dialectJsonEncoder = (dialect) => dialect === "tidb" ? JSON.stringify : pgSafeJsonStringify;
-/** design/158 redesign① — the "protocol" JSON-column encoder DISPATCH (approval-store/checkpoint-store's
- *  identical ternary, collected): TiDB stores `JSON.stringify` verbatim (the `label` arg is ignored on that
- *  arm — TiDB has no protocol-byte envelope to name); PG goes through `pgProtocolJsonStringify(v, label)`,
- *  whose `label` names the field in its error text on an unstorable-byte reject. */
 export const dialectProtocolJsonEncoder = (dialect) => dialect === "tidb" ? (v) => JSON.stringify(v) : pgProtocolJsonStringify;
 //# sourceMappingURL=sql-driver.js.map

package/dist/plugins/sql-errors.js

@@ -1,24 +1,17 @@
-/** MySQL/TiDB `ER_DUP_ENTRY` 的数字 errno。 */
 export const MYSQL_ER_DUP_ENTRY_ERRNO = 1062;
-/** MySQL/TiDB `ER_DUP_ENTRY` 的字符串错误码(mysql2 的 `code`)。 */
 export const MYSQL_ER_DUP_ENTRY_CODE = "ER_DUP_ENTRY";
-/** PostgreSQL `unique_violation` 的 SQLSTATE。 */
 export const PG_UNIQUE_VIOLATION_SQLSTATE = "23505";
-/** 非对象(null / undefined / 字符串 / 数字)一律否——谓词自身绝不成为新的失败源。 */
 function keyOf(err, key) {
     if (err === null || typeof err !== "object")
         return undefined;
     return Reflect.get(err, key);
 }
-/** MySQL/TiDB 的唯一键冲突:`code === "ER_DUP_ENTRY"` **或** `errno === 1062`(同一件事的两种写法)。 */
 export function isMysqlDupKeyError(err) {
     return String(keyOf(err, "code")) === MYSQL_ER_DUP_ENTRY_CODE || Number(keyOf(err, "errno")) === MYSQL_ER_DUP_ENTRY_ERRNO;
 }
-/** PostgreSQL 的唯一键冲突:SQLSTATE `23505`(node-pg 挂在 `code` 上)。 */
 export function isPgUniqueViolation(err) {
     return String(keyOf(err, "code")) === PG_UNIQUE_VIOLATION_SQLSTATE;
 }
-/** 方言分派口——双方言店的调用形(`isDupKeyError(this.db.dialect, e)`)。 */
 export function isDupKeyError(dialect, err) {
     return dialect === "tidb" ? isMysqlDupKeyError(err) : isPgUniqueViolation(err);
 }

package/dist/plugins/sql-escape.js

@@ -1,11 +1,3 @@
-/**
- * Backend-NEUTRAL SQL string escaping (design/158 A3 沉底).
- *
- * Lives in its own leaf so no adapter has to load another dialect's adapter module to get a pure
- * string transform (the PG stores used to runtime-import the TiDB tool-result store for exactly
- * this one function). Zero dialect deps by construction — keep it that way.
- */
-/** Escape SQL LIKE metacharacters (`\`, `%`, `_`) so a value is matched literally (default `\` escape char). */
 export function escapeLike(s) {
     return s.replace(/[\\%_]/g, (ch) => `\\${ch}`);
 }

package/dist/plugins/sql-row-helpers.js

@@ -1,17 +1,3 @@
-/**
- * Shared pure row-mapping helpers for the SQL store twins (design/158 S8 纯 helper 归位).
- *
- * These were duplicated verbatim across the pg-/tidb- store twin pairs; each store imports the flavor
- * it was written against (usually under its historical local alias, e.g. `parseJsonStrict as
- * parseJson`) so call sites and semantics are byte-identical to before.
- *
- * THREE parseJson flavors exist ON PURPOSE — they differ in what a corrupted/legacy JSON column
- * reads back as (lenient → null / strict → throw / fallback value), and the TWO nullable date→ISO
- * helpers differ in how a non-Date cell is rendered (String() passthrough vs `new Date()` re-parse).
- * Do NOT collapse them into one.
- */
-/** JSON column → value; a corrupted/legacy JSON column reads back as `null` instead of failing the
- *  read. Non-strings pass through (node-pg parses jsonb → object already). */
 export function parseJsonLenient(v) {
     if (v == null)
         return null;
@@ -24,16 +10,11 @@ export function parseJsonLenient(v) {
         return null;
     }
 }
-/** JSON column → value; malformed JSON THROWS. For stores whose write arm keeps the column clean
- *  (R7 终形:协议面拒绝式,库内恒干净,直读). Non-strings pass through (node-pg parses jsonb →
- *  object already). */
 export function parseJsonStrict(v) {
     if (v == null)
         return null;
     return (typeof v === "string" ? JSON.parse(v) : v);
 }
-/** JSON column → value with a caller-supplied fallback for NULL/corrupted cells. Non-strings pass
- *  through (node-pg parses jsonb → object already; tolerate a string just in case). */
 export function parseJsonOr(v, fallback) {
     if (v == null)
         return fallback;
@@ -46,20 +27,14 @@ export function parseJsonOr(v, fallback) {
         return fallback;
     }
 }
-/** NOT NULL datetime column → ISO string (drivers return Date; a string cell passes through via
- *  String() — NOT re-parsed). */
 export function toIso(v) {
     return v instanceof Date ? v.toISOString() : String(v);
 }
-/** Nullable twin of {@link toIso} (string cells still pass through verbatim). */
 export function toIsoOrNull(v) {
     if (v == null)
         return null;
     return v instanceof Date ? v.toISOString() : String(v);
 }
-/** Nullable datetime column → ISO string, RE-PARSING a string cell via `new Date()` (normalizes a
- *  raw DB datetime string like "2026-01-01 00:00:00" to ISO — unlike {@link toIsoOrNull}, which
- *  passes it through unchanged). */
 export function normalizeIsoOrNull(v) {
     if (v == null)
         return null;