@sema-agent/server 7.9.0 → 7.11.0

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

@@ -0,0 +1,516 @@
+import { SHARED_MEMORY_READ_CAP_BYTES, SharedMemoryStoreError, } from "@sema-agent/core";
+import { mysqlDriver, pgDriver } from "./sql-driver.js";
+/** 唯一键冲突的方言判别(approval-ask/checkpoint 同一对常量)——mysql2 挂 `errno`,node-pg 挂 SQLSTATE。
+ *  只用来把并发登记撞 PK 翻成一句人话,不让驱动错误对象漏给调用方。 */
+const DUP_ENTRY = 1062; // MySQL/TiDB ER_DUP_ENTRY
+const PG_UNIQUE_VIOLATION = "23505";
+function isDupKey(dialect, err) {
+    if (err === null || typeof err !== "object")
+        return false;
+    // Reflect.get (not a spread): driver error classes carry these on the PROTOTYPE chain in some
+    // versions, and `{...err}` would silently miss them — a missed dup-key leaks the raw driver object.
+    return dialect === "tidb" ? Number(Reflect.get(err, "errno")) === DUP_ENTRY : String(Reflect.get(err, "code")) === PG_UNIQUE_VIOLATION;
+}
+/** 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;
+export function assertStoreId(storeId) {
+    if (!STORE_ID_RE.test(storeId) || storeId.includes("__")) {
+        throw new Error(`shared-memory store id ${JSON.stringify(storeId)} is not usable: it must match /^[A-Za-z0-9_.-]{1,64}$/ and must not contain "__"`);
+    }
+}
+export function assertScopeKey(scopeKey) {
+    if (!ORG_SCOPE_RE.test(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}`);
+    };
+    if (!path.startsWith("/"))
+        refuse("it must be absolute (leading \"/\")");
+    if (path.length > PATH_MAX_CHARS)
+        refuse(`it is ${path.length} UTF-16 units, over the ${PATH_MAX_CHARS} the column stores`);
+    if (FORBIDDEN_PATH_CHARS.test(path))
+        refuse("it carries a control/format/private-use character or a backslash");
+    const segments = path.slice(1).split("/");
+    if (!segments.every((s) => s !== "" && !s.startsWith(".")))
+        refuse("every folder segment must be non-empty and must not start with \".\"");
+    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) {
+        switch (state) {
+            case "unavailable":
+                return "unavailable";
+            case "connecting":
+                sawConnecting = true;
+                break;
+            case "connected":
+                break;
+        }
+    }
+    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) {
+        case "connecting":
+        case "unavailable":
+        case "connected":
+            return word;
+        default:
+            throw new Error(`${SHARED_MEMORY_SCOPE_TABLE}.state holds an unknown word ${JSON.stringify(word)} (expected connecting|unavailable|connected)`);
+    }
+}
+function strOrNull(v) {
+    return v === null || v === undefined ? null : String(v);
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted !== true)
+        return;
+    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();
+    }
+    catch (rollbackErr) {
+        console.warn("[shared-memory-store] rollback failed after a failed transaction; reporting the PRIMARY error:", { primary, rollbackErr });
+    }
+}
+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 {
+        path: String(r.path),
+        sizeBytes: Number(r.size_bytes),
+        ...(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;
+    now;
+    maxListLimit;
+    constructor(db, authorizer, opts = {}) {
+        this.db = db;
+        this.authorizer = authorizer;
+        this.now = opts.now ?? Date.now;
+        this.maxListLimit = opts.maxListLimit ?? DEFAULT_MAX_LIST_LIMIT;
+    }
+    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);
+            return { state: "unavailable", ...(message !== null ? { message } : {}) };
+        }
+        if (folded === "connecting")
+            return { state: "connecting" };
+        return {
+            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 修)。方言差异显式:
+     *  · MySQL/TiDB 的默认隔离级别就是 REPEATABLE READ ⇒ 一个事务内的两条 SELECT 天然同快照;
+     *  · PG 默认 READ COMMITTED,**每条语句各自取快照** ⇒ 必须显式抬到 REPEATABLE READ,否则这个事务
+     *    对本条竞态毫无作用(那正是"包了事务就以为一致"最容易踩空的地方)。
+     */
+    async readBinding(scopes) {
+        const conn = await this.db.connect();
+        try {
+            await conn.begin();
+            if (this.db.dialect === "pg")
+                await conn.query("SET TRANSACTION ISOLATION LEVEL REPEATABLE READ");
+            const scopeRows = await conn.query(this.q(`SELECT scope_key, state, message FROM ${SHARED_MEMORY_SCOPE_TABLE} WHERE scope_key IN (${scopes.map(() => "?").join(", ")})`, `SELECT scope_key, state, message FROM ${SHARED_MEMORY_SCOPE_TABLE} WHERE scope_key IN (${scopes.map((_, i) => `$${i + 1}`).join(", ")})`), [...scopes]);
+            const storeRows = await conn.query(this.q(`SELECT store_id, scope_key, description, writable FROM ${SHARED_MEMORY_STORE_TABLE} WHERE scope_key IN (${scopes.map(() => "?").join(", ")}) ORDER BY store_id`, `SELECT store_id, scope_key, description, writable FROM ${SHARED_MEMORY_STORE_TABLE} WHERE scope_key IN (${scopes.map((_, i) => `$${i + 1}`).join(", ")}) ORDER BY store_id`), [...scopes]);
+            await conn.commit();
+            return { scopeRows: scopeRows.rows, storeRows: storeRows.rows };
+        }
+        catch (err) {
+            await rollbackPreservingError(conn, err);
+            throw err;
+        }
+        finally {
+            conn.release();
+        }
+    }
+    readerFor(storeId, scopeKey) {
+        return {
+            list: (prefix, opts) => this.listDocuments(storeId, scopeKey, prefix, opts),
+            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) => {
+            params.push(value);
+            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);
+        const window = res.rows.slice(0, limit).map(rowToEntry);
+        const hasMore = res.rows.length > limit;
+        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 = ?
+          WHERE s.store_id = ? AND s.scope_key = ?`, `SELECT e.path AS path, OCTET_LENGTH(e.content) AS content_bytes, CASE WHEN OCTET_LENGTH(e.content) <= $1 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 = $2
+          WHERE s.store_id = $3 AND s.scope_key = $4`), [SHARED_MEMORY_READ_CAP_BYTES, path, storeId, scopeKey]);
+        const row = res.rows[0];
+        if (row === undefined)
+            throw storeGone(storeId);
+        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();
+        await this.db.query(this.q(`INSERT INTO ${SHARED_MEMORY_SCOPE_TABLE} (scope_key, state, message, updated_at_ms) VALUES (?, ?, ?, ?)
+           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);
+        if (record.description.length > DESCRIPTION_MAX_CHARS) {
+            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} 头注的"事务与锁"段
+            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) {
+                ownedBy = owner;
+                await conn.rollback();
+            }
+            else if (owner !== undefined) {
+                await conn.query(this.q(`UPDATE ${SHARED_MEMORY_STORE_TABLE} SET description = ?, writable = ?, updated_at_ms = ? WHERE store_id = ?`, `UPDATE ${SHARED_MEMORY_STORE_TABLE} SET description = $1, writable = $2, updated_at_ms = $3 WHERE store_id = $4`), [record.description, record.writable ? 1 : 0, now, record.storeId]);
+                await conn.commit();
+            }
+            else {
+                await conn.query(this.q(`INSERT INTO ${SHARED_MEMORY_STORE_TABLE} (store_id, scope_key, description, writable, updated_at_ms) VALUES (?, ?, ?, ?, ?)`, `INSERT INTO ${SHARED_MEMORY_STORE_TABLE} (store_id, scope_key, description, writable, updated_at_ms) VALUES ($1, $2, $3, $4, $5)`), [record.storeId, record.scopeKey, record.description, record.writable ? 1 : 0, now]);
+                await conn.commit();
+            }
+        }
+        catch (err) {
+            await rollbackPreservingError(conn, err);
+            if (isDupKey(this.db.dialect, err)) {
+                throw new Error(`shared-memory store id ${JSON.stringify(record.storeId)} was concurrently registered by another writer — store ids are globally unique and their owning org is immutable`);
+            }
+            throw err;
+        }
+        finally {
+            conn.release();
+        }
+        if (ownedBy !== undefined) {
+            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);
+        assertDocumentPath(record.path);
+        const sizeBytes = Buffer.byteLength(record.content, "utf8");
+        if (sizeBytes > SHARED_MEMORY_READ_CAP_BYTES) {
+            throw new Error(`shared-memory document ${JSON.stringify(record.path)} is ${sizeBytes} bytes, over the ${SHARED_MEMORY_READ_CAP_BYTES}-byte shared-store read cap — core refuses an over-cap document outright (it is never truncated), so storing it would create a row nothing can ever read. Split it at import.`);
+        }
+        const now = this.now();
+        let unregistered = false;
+        const conn = await this.db.connect();
+        try {
+            await conn.begin(); // 为什么不是 beginPessimistic:见 {@link SqlSharedMemoryStore} 头注的"事务与锁"段
+            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;
+                await conn.rollback();
+            }
+            else {
+                await conn.query(this.q(`INSERT INTO ${SHARED_MEMORY_ENTRY_TABLE} (store_id, path, content, updated_at_iso, size_bytes, updated_at_ms) VALUES (?, ?, ?, ?, ?, ?)
+               ON DUPLICATE KEY UPDATE content = VALUES(content), updated_at_iso = VALUES(updated_at_iso), size_bytes = VALUES(size_bytes), updated_at_ms = VALUES(updated_at_ms)`, `INSERT INTO ${SHARED_MEMORY_ENTRY_TABLE} (store_id, path, content, updated_at_iso, size_bytes, updated_at_ms) VALUES ($1, $2, $3, $4, $5, $6)
+               ON CONFLICT (store_id, path) DO UPDATE SET content = EXCLUDED.content, updated_at_iso = EXCLUDED.updated_at_iso, size_bytes = EXCLUDED.size_bytes, updated_at_ms = EXCLUDED.updated_at_ms`), [record.storeId, record.path, record.content, record.updatedAtIso ?? null, sizeBytes, now]);
+                await conn.commit();
+            }
+        }
+        catch (err) {
+            await rollbackPreservingError(conn, err);
+            throw err;
+        }
+        finally {
+            conn.release();
+        }
+        if (unregistered) {
+            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. */
+    async deleteDocument(storeId, scopeKey, path) {
+        await this.assertOwnedBy(storeId, scopeKey);
+        const res = await this.db.query(this.q(`DELETE FROM ${SHARED_MEMORY_ENTRY_TABLE} WHERE store_id = ? AND path = ?`, `DELETE FROM ${SHARED_MEMORY_ENTRY_TABLE} WHERE store_id = $1 AND path = $2`), [storeId, path]);
+        return res.affected > 0;
+    }
+    /** 属主围栏的共用断言(轮3 F1)。**不**覆盖同一个 org 内的"删了又建"代际重用——那不是跨租户面,
+     *  真要挡住需要一枚不可变的 generation token;这里如实说明边界,不假装它被覆盖了。 */
+    async assertOwnedBy(storeId, scopeKey) {
+        assertStoreId(storeId);
+        assertScopeKey(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]);
+        if (res.rows.length === 0) {
+            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`);
+        }
+    }
+    /**
+     * 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} 头注的"事务与锁"段
+            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;
+                await conn.rollback();
+            }
+            else {
+                await conn.query(this.q(`DELETE FROM ${SHARED_MEMORY_ENTRY_TABLE} WHERE store_id = ?`, `DELETE FROM ${SHARED_MEMORY_ENTRY_TABLE} WHERE store_id = $1`), [storeId]);
+                await conn.query(this.q(`DELETE FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = ?`, `DELETE FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = $1`), [storeId]);
+                await conn.commit();
+            }
+        }
+        catch (err) {
+            await rollbackPreservingError(conn, err);
+            throw err;
+        }
+        finally {
+            conn.release();
+        }
+        if (notOwned) {
+            throw new Error(`shared-memory store ${JSON.stringify(storeId)} is not registered under ${JSON.stringify(scopeKey)} — refusing to delete: either it is already gone, or the id has since been recycled by another org (a stale retry must never erase the successor's library)`);
+        }
+    }
+}
+/** 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);
+    }
+}
+//# sourceMappingURL=shared-memory-store-sql.js.map

package/dist/plugins/store-backend.d.ts

@@ -22,6 +22,9 @@ import { PgCostQuota } from "./pg-cost-quota.js";
 import { TiDBRateLimiter } from "./tidb-rate-limiter.js";
 import type { CounterDegradeHook } from "./write-behind-counter.js";
 import { PgRateLimiter } from "./pg-rate-limiter.js";
+import { type SqlSharedMemoryStore, type SharedMemoryScopeAuthorizer } from "./shared-memory-store-sql.js";
+import { type AdoptionLogStore } from "./adoption-log-sql.js";
+import { type PermissionRuleStores } from "./permission-rule-store-sql.js";
 export type RunStore = TiDBRunStore | PgRunStore | FileRunStore;
 /** E18 resume-at eventId→entryId anchor map — tidb/pg/local 3-backend (works LOCAL; needs only the session tree +
  *  this map, no cloud-only checkpoint). Union = the three nominal twins; consumers use put/resolve/deleteBySession.
@@ -125,6 +128,20 @@ export interface StoreBackend {
      *  无 backend 的 env-only worker 压根没有 `StoreBackend` ⇒ 协调器拿到 undefined askStore ⇒ 车2 的
      *  D1 逐字现行为(store 缺席 = 现行 `tool_approval` 活卡腿一字不变)。 */
     approvalAsk(): ApprovalAskStoreType;
+    /**
+     * #154 车二(core 5.18.0 design/179 + 5.22.0 design/182):**持久化权限规则店**(「不再询问」车道)
+     * 三面 —— 规则桶 provider / durable 审批记录 / server 自铸的 CC 导入票。
+     *
+     * 🔴 **可选**(与上面那些 REQUIRED 家族不同),缺席是一个真答案:core 的 `RunnerDeps.permissionRuleStore`
+     * 本身就是 optional,缺席 ⇒ 引擎的 `permissionRules.storeWired` 如实报 `false`,ask 帧不投 `ruleSuggestions`
+     * (发一格按下去无处可兑的「不再询问」= wire 谎言,比缺席更坏)。
+     *
+     * `local` 车道**刻意不给 in-memory twin**:一条规则是「人授权过的持久事实」,进程内 Map 形会在重启时
+     * 静默丢掉那份授权,而消费端(下一次同命令的 ask)读到的是「没有规则」——那是**放宽面**上的静默降级。
+     * 诚实缺席(storeWired:false)比一个会遗忘的店正确。要在 local 真上,先落 File 形(core 现成
+     * `FilePermissionRuleStoreProvider` 即可当模子)。
+     */
+    permissionRule(): PermissionRuleStores | undefined;
     /** SendUserFile scope↔object ledger (multi-tenant list/revoke handle; the hashed key segment hides the
      *  mapping from URLs). REQUIRED on all backends (works local — one JSONL, like approvalExemption). */
     sendFileLedger(): SendFileLedger;
@@ -161,6 +178,14 @@ export interface StoreBackend {
     /** Cloud-only stores below are OPTIONAL: the `local` (in-memory/file) backend omits them (it has no core
      *  in-memory twin carrying the service extras, and these are fleet/multi-replica concepts), so a local HTTP
      *  service degrades EXACTLY like today's no-DB env (the consumers gate on `backend?.X?.()`). TiDB/PG provide all. */
+    /** design/177 —— org 共享记忆库的供给面(core `RunnerDeps.sharedMemoryStores` + `/v1/shared-memory/*`
+     *  只读面)。授权折叠**注入**:谁属于哪个 org 归 server 的目录面判,持久层只按判决出的 scope 集查表。
+     *
+     *  🔴 local 车道诚实缺席(不是"待补"):这个面的全部意义是**跨用户**共享一个团队库,而 local 后端是
+     *  单机单用户、没有租户边界、也没有 org 目录源。造一个 file 形等于给一个只有一个人的部署做"团队共享",
+     *  能力面会因此对消费方说谎。要在单机真上这条面,先接一个目录源(`MEMORY_ORG_DIRECTORY_JSON`)并选
+     *  SQL 后端 —— 那时它自然点亮。 */
+    sharedMemoryStore?(authorizer: SharedMemoryScopeAuthorizer): SqlSharedMemoryStore;
     checkpoint?(logger?: {
         info?(msg: string, meta?: unknown): void;
     }): CheckpointStoreFull;
@@ -179,6 +204,11 @@ export interface StoreBackend {
     /** S3-TOB(设计 §1.4):the raw PG pool for the memory-engine DB backend's PgQueryFn binding (mirror of
      *  mysqlPool). undefined on non-PG backends. */
     pgPool(): PgPool | undefined;
+    /** design/183 form b(纯身份重绑)的 SQL 收编日志。**SQL 后端专有**(mysql/pg),`local` 刻意省略:
+     *  收编重绑的是**多租身份轴**,而 local 后端整个数据根就属那一个用户、库里没有 owner/scope 分区面
+     *  ——在那儿开这道口只会让一个够不到任何东西的动作看起来可用。消费点按 `backend?.adoptionLog?.()`
+     *  缺席即 501(诚实拒绝),与其它云专有 store 同姿势。 */
+    adoptionLog?(): AdoptionLogStore;
     /** S10 (SILENT-FALLBACK P1): the DB server's wall clock in epoch ms — the reaper probes it against the local
      *  clock to expose replica clock skew (the write-behind counters bucket on LOCAL floor(now/windowMs); skew
      *  splits a fleet window into disjoint buckets = soft-limit leak). OPTIONAL: local backend omits (no fleet). */

package/dist/plugins/store-backend.js

@@ -40,6 +40,11 @@ import { TiDBRateLimiter } from "./tidb-rate-limiter.js";
 import { PgRateLimiter } from "./pg-rate-limiter.js";
 import { TiDBSessionStore } from "./tidb-session-store.js";
 import { PgSessionStore } from "./pg-session-storage.js";
+import { TiDBSharedMemoryStore, PgSharedMemoryStore } from "./shared-memory-store-sql.js";
+import { TiDBAdoptionLogStore, PgAdoptionLogStore } from "./adoption-log-sql.js";
+// #154 车二:持久化权限规则店(三面一束)。`mysqlDriver`/`pgDriver` 是既有的方言中立 seam。
+import { createSqlPermissionRuleStores } from "./permission-rule-store-sql.js";
+import { mysqlDriver, pgDriver } from "./sql-driver.js";
 /** Build the snapshot-BLOB object-store backend from config, or undefined to fall back to the SqlBlobBackend default.
  *  When `config.snapshotBlobStore` (MINIO_* env) is set, the E19/2c file-snapshot stores route ONLY the blob BYTES to
  *  MinIO; the MANIFEST stays in SQL (the transcript hot read never touches MinIO). The MinioBlobBackend is given the
@@ -97,6 +102,7 @@ class TiDBBackend {
     resumeAnchor() { return new TiDBResumeAnchorStore(this.pool); }
     approvalExemption() { return new TiDBApprovalExemptionStore(this.pool); }
     approvalAsk() { return new TiDBApprovalAskStore(this.pool); } // #151 流内审批协议持久层(无状态 store,每次新建同兄弟)
+    permissionRule() { return createSqlPermissionRuleStores(mysqlDriver(this.pool)); } // #154 车二 持久化权限规则店
     sendFileLedger() { return new TiDBSendFileLedger(this.pool); }
     sessionPolicy() { return new TiDBSessionPolicyStore(this.pool); }
     fileSnapshot() { return new TiDBFileSnapshotStore(this.pool, snapshotBlobBackend(this.config, "tidb", this.pool), snapshotBoundsFromConfig(this.config)); }
@@ -105,6 +111,7 @@ class TiDBBackend {
     workflowRun(onWarn) { return new TiDBWorkflowRunStore(this.pool, onWarn); } // P1: cross-replica workflow record(onWarn = C5 oversize-slim 留痕,completionInbox 同款先例)
     completionInbox(onWarn) { return new TiDBWorkflowCompletionInbox(this.pool, onWarn); } // P1: cross-replica push half
     notifyJournal() { return new TiDBWorkflowNotifyJournalStore(this.pool); } // 1.108: cross-replica at-least-once notify
+    sharedMemoryStore(authorizer) { return new TiDBSharedMemoryStore(this.pool, authorizer); } // design/177 org 共享记忆库
     checkpoint(logger) { return new TiDBCheckpointStore(this.pool, logger); }
     toolResult() { return new TiDBToolResultStore(this.pool); }
     imageIndex() { return new TiDBImageIndex(this.pool); }
@@ -113,6 +120,7 @@ class TiDBBackend {
     costQuota(limitMicroUsd, windowMs, onDegraded) { return new TiDBCostQuota(this.pool, limitMicroUsd, windowMs, undefined, onDegraded, this.config.dbQueryTimeoutMs); }
     rateLimiter(limit, onDegraded) { return new TiDBRateLimiter(this.pool, limit, undefined, undefined, onDegraded, this.config.dbQueryTimeoutMs); }
     session() { return new TiDBSessionStore(this.pool); }
+    adoptionLog() { return new TiDBAdoptionLogStore(this.pool); } // design/183 form b 收编日志(无状态 store,每次新建同兄弟)
     mysqlPool() { return this.pool; }
     pgPool() { return undefined; }
     async dbNowMs() { const [rows] = await this.pool.query("SELECT ROUND(UNIX_TIMESTAMP(NOW(3))*1000) AS ms"); return Number(rows[0]?.ms); } // S10
@@ -131,6 +139,7 @@ class PgBackend {
     resumeAnchor() { return new PgResumeAnchorStore(this.pool); }
     approvalExemption() { return new PgApprovalExemptionStore(this.pool); }
     approvalAsk() { return new PgApprovalAskStore(this.pool); } // #151 流内审批协议持久层(SQL twin)
+    permissionRule() { return createSqlPermissionRuleStores(pgDriver(this.pool)); } // #154 车二 持久化权限规则店(SQL twin)
     sendFileLedger() { return new PgSendFileLedger(this.pool); }
     sessionPolicy() { return new PgSessionPolicyStore(this.pool); }
     fileSnapshot() { return new PgFileSnapshotStore(this.pool, snapshotBlobBackend(this.config, "pg", this.pool), snapshotBoundsFromConfig(this.config)); }
@@ -139,6 +148,7 @@ class PgBackend {
     workflowRun(onWarn) { return new PgWorkflowRunStore(this.pool, onWarn); } // P1: cross-replica workflow record(onWarn = C5 oversize-slim 留痕,completionInbox 同款先例)
     completionInbox(onWarn) { return new PgWorkflowCompletionInbox(this.pool, onWarn); } // P1: cross-replica push half
     notifyJournal() { return new PgWorkflowNotifyJournalStore(this.pool); } // 1.108: cross-replica at-least-once notify
+    sharedMemoryStore(authorizer) { return new PgSharedMemoryStore(this.pool, authorizer); } // design/177 org 共享记忆库
     checkpoint(logger) { return new PgCheckpointStore(this.pool, logger); }
     toolResult() { return new PgToolResultStore(this.pool); }
     imageIndex() { return new PgImageIndex(this.pool); }
@@ -147,6 +157,7 @@ class PgBackend {
     costQuota(limitMicroUsd, windowMs, onDegraded) { return new PgCostQuota(this.pool, limitMicroUsd, windowMs, undefined, onDegraded, this.config.dbQueryTimeoutMs); }
     rateLimiter(limit, onDegraded) { return new PgRateLimiter(this.pool, limit, undefined, undefined, onDegraded, this.config.dbQueryTimeoutMs); }
     session() { return new PgSessionStore(this.pool); }
+    adoptionLog() { return new PgAdoptionLogStore(this.pool); } // design/183 form b 收编日志(SQL twin)
     mysqlPool() { return undefined; }
     pgPool() { return this.pool; }
     async dbNowMs() { const res = await this.pool.query("SELECT ROUND(EXTRACT(EPOCH FROM now())*1000) AS ms"); return Number(res.rows[0]?.ms); } // S10
@@ -233,6 +244,9 @@ class LocalBackend {
      *  new 一个就等于每个消费者各拿一份互不可见的账(而 SQL twin 天然共享一张表)。易失代价 +
      *  「local 车道默认不上协议」的裁定见 StoreBackend.approvalAsk() 的接口注。 */
     approvalAsk() { return this.approvalAskStore; }
+    /** #154 车二:local 车道**诚实缺席**(理由逐字见 `StoreBackend.permissionRule()` 的接口注:
+     *  一个会在重启时遗忘授权的规则店,在放宽面上比没有店更坏)。 */
+    permissionRule() { return undefined; }
     sendFileLedger() { return this.sendFileLedgerStore; } // singleton — append fd lives in the instance
     /** Durable HITL / plan-review parking on the LOCAL lane. Lazy singleton (the inner core store holds
      *  an append fd). taskId join ← FileRunStore; E21 owner guard ← LocalSessionStore.ownerOf (same root). */