@sema-agent/server 7.58.0 → 7.60.0

package/dist/plugins/shared-memory-store-sql.d.ts

@@ -54,18 +54,18 @@
  * live library both re-scans the prefix on every page and skips rows when a document is inserted mid-walk.
  *
  * ─────────────────────────────────────────────────────────────────────────────────────────────────
- * 事务与锁 —— 为什么用 `begin()` 而不是 `beginPessimistic()`
+ * 事务与锁
  * ─────────────────────────────────────────────────────────────────────────────────────────────────
- * 三个写方法(putStore / putDocument / deleteStore)都是「先读注册行、再按结果写」的形状,并且都用
- * `SELECT … FOR UPDATE` 拿同一把行锁,于是彼此串行。事务动词取**普通** `begin()`:
- *  · `BEGIN PESSIMISTIC` 是 TiDB 专有语法,在 MySQL / MariaDB 上是**语法错误**——而本仓 `kind: "mysql"`
- *    按定义覆盖任何 MySQL 协议服务端(本机验收台就是真 MySQL 9.7)。用它等于让这个店在多数目标上直接
- *    不可用,那比它要防的那道窄窗口严重得多;
- *  · MySQL InnoDB 的加锁读(`FOR UPDATE`)在 REPEATABLE READ 下**恒是 current read**,读到的是最新已提交
- *    版本,并且对不存在的键取 gap/next-key 锁 ⇒ 并发登记天然串行。TiDB 自 v5 起默认就是悲观事务,同理;
- *  · 唯一残留的窄窗口是「TiDB 集群被显式配成乐观模式」。那一格由**第二道防线**兜底:`store_id` 的主键
- *    唯一性是真正的裁决者,撞键被 {@link isDupKey} 翻成一句响亮的拒绝(见 putStore)。也就是说即便快照
- *    读陈旧,结果也只会是「一方被响亮拒绝」,绝不会是一次静默的换属主。
+ * **四个**写方法(putStore / putDocument / deleteDocument / deleteStore)都是「先读注册行、再按结果写」
+ * 的形状,并且都用 `SELECT … FOR UPDATE` 拿同一把行锁,于是彼此串行。判据只有一处:
+ * {@link SqlTxConn.begin} 的 `@contract txn.read-semantics` —— 加锁读在两引擎都是当前读,而「当前读」
+ * 的前提(TiDB 悲观模式、MySQL 会话级 REPEATABLE READ)是**连接初始化**的结构保证,不是服务器默认值。
+ *
+ * 本店的**第二道防线**照旧在:`store_id` 的主键唯一性才是最终裁决者,撞键被 {@link isDupKey} 翻成一句
+ * 响亮的拒绝(见 putStore)—— 即便某一天读语义出岔,结果也只会是「一方被响亮拒绝」,绝不会是一次静默
+ * 的换属主。⚠️ 另一处不可混线的分歧:InnoDB 的加锁读对**不存在的键**取 gap/next-key 锁,TiDB 悲观事务
+ * **没有** gap 锁(retention-store 的「先 ON DUPLICATE 造行、再 FOR UPDATE 锁行」就是为它而写)。
+ * 「加锁读=当前读」两引擎同真,「gap 锁」只有 InnoDB 有 —— 两条性质不共享一个「同理」。
  */
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
@@ -154,15 +154,21 @@ export declare class SqlSharedMemoryStore implements SharedMemoryStoreProvider {
         signal?: AbortSignal;
     }): Promise<SharedMemorySnapshot>;
     /**
-     * 盘状态 + 库登记,**一个事务一个快照**(轮2 F3 修)。
+     * 盘状态 + 库登记,**一条语句一个快照**。
+     *
+     * 🔴 S-131(codex 对抗复审 r1 [high] 采,[ref] 的终局):这一对读要的不是新鲜度,而是「scope 行与
+     * store 行读齐、不撕」——一个 importer 若落在两条读之间,快照会把**旧的 connected 盘态**和**新登记的
+     * 库**拼在一起,于是壳拿到一个「已连接」的盘和一份不完整的库,而 reader 只复核 (store, scope) 归属、
+     * 从不复核盘态。
+     *
+     * 此前这条保证挂在**隔离级**上(轮2 F3 起用事务,[ref] 又把两臂都钉成 REPEATABLE READ)。S-131 把
+     * 隔离级收进连接初始化之后,那条路在 PG 腿上走不通:PG 的 REPEATABLE READ 是快照隔离,把会话钉过去
+     * 会让本仓每一条 `SELECT … FOR UPDATE` 从「等锁后读当前」变成 `40001` 序列化失败(`@contract
+     * txn.read-semantics` ② 的 PG 段),而 PG 的 `BEGIN` 是 READ COMMITTED、**每条语句各自取快照**。
      *
-     * 🔴 [ref](两臂不对称,验真后修):此前 PG 臂显式抬隔离级别、**MySQL 臂只靠服务端默认值**,
-     * 注里写的是「MySQL/TiDB 的默认隔离级别就是 REPEATABLE READ ⇒ 天然同快照」。那句话对**默认配置**
-     * 为真,但 `transaction_isolation` 是可设的服务端/会话变量:一台跑 READ COMMITTED 的实例(托管
-     * MySQL 的厂商默认、中间层代理、运维手改)会把「一个事务一个快照」悄悄降成「每条语句各自取快照」,
-     * 而本方法**不会报任何错**——它只是读到一对撕裂的 scope/store 行。「靠默认值成立」不是结构保证。
-     * 两臂现在都走 {@link SqlTxConn.beginRepeatableRead}(语句文本与**摆放位置**的方言分歧写在那里:
-     * MySQL 必须在 BEGIN **之前**发、PG 必须在 BEGIN **之后**发)。
+     * ⇒ 改用**一条语句**读齐两张表(`UNION ALL` + `kind` 判别列)。一条语句在**任何**引擎、任何隔离级
+     * 下都是一个快照,于是这条保证不再依赖隔离级、不再需要事务、也不必为一次纯读去拿行锁(锁读会让
+     * 并发读被写者串起来,而这是会话附着的热路径)。规则少了一条:全店从此只有写方法开事务。
      */
     private readBinding;
     private readerFor;

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

@@ -147,21 +147,23 @@ export class SqlSharedMemoryStore {
         };
     }
     async readBinding(scopes) {
-        const conn = await this.db.connect();
-        try {
-            await conn.beginRepeatableRead();
-            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();
-        }
+        const n = scopes.length;
+        const kindOrder = "ORDER BY kind, store_id";
+        const rows = await this.db.query(this.q(`SELECT 'scope' AS kind, scope_key, state, message, NULL AS store_id, NULL AS description, NULL AS writable
+           FROM ${SHARED_MEMORY_SCOPE_TABLE} WHERE scope_key IN (${scopes.map(() => "?").join(", ")})
+         UNION ALL
+         SELECT 'store' AS kind, scope_key, NULL, NULL, store_id, description, writable
+           FROM ${SHARED_MEMORY_STORE_TABLE} WHERE scope_key IN (${scopes.map(() => "?").join(", ")})
+         ${kindOrder}`, `SELECT 'scope' AS kind, scope_key, state, message, NULL::varchar AS store_id, NULL::varchar AS description, NULL::smallint AS writable
+           FROM ${SHARED_MEMORY_SCOPE_TABLE} WHERE scope_key IN (${scopes.map((_, i) => `$${i + 1}`).join(", ")})
+         UNION ALL
+         SELECT 'store' AS kind, scope_key, NULL::varchar, NULL::varchar, store_id, description, writable
+           FROM ${SHARED_MEMORY_STORE_TABLE} WHERE scope_key IN (${scopes.map((_, i) => `$${n + i + 1}`).join(", ")})
+         ${kindOrder}`), [...scopes, ...scopes]);
+        return {
+            scopeRows: rows.rows.filter((r) => r.kind === "scope"),
+            storeRows: rows.rows.filter((r) => r.kind === "store"),
+        };
     }
     readerFor(storeId, scopeKey) {
         return {

package/dist/plugins/sql-driver.d.ts

@@ -25,10 +25,43 @@
  *     `query_timeout`. The counter family (write-behind-counter.ts) needs those and keeps its own
  *     exec; this seam stays on the plain (sql, params) form.
  *
- * `beginPessimistic()` is TiDB's `BEGIN PESSIMISTIC` (a CURRENT read for the FOR UPDATE admission
- * check — a snapshot read would double-admit) and a plain `BEGIN` on PG (READ COMMITTED already
- * reads the latest committed row under the sentinel lock). It is a NAMED verb precisely so the
- * divergence is visible rather than hidden inside `begin()`.
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * @contract txn.read-semantics — 本仓「事务里的读看到什么」的**唯一**成文处(S-131 / B-020 / B-022)
+ * ─────────────────────────────────────────────────────────────────────────────────────────────────
+ * 五只店的头注此前各写一套「为什么用这个事务动词」的理由(截断的、漏数的、讲历史沿革的都有)。
+ * 判据从今天起只有这一处,店里只留一行 `{@link SqlTxConn.begin}` 指回来。
+ *
+ * **① 事务动词只有一个** —— `begin()`。曾经那个「悲观」专用动词(MySQL 腿发 TiDB 专有的
+ *    `BEGIN PESSIMISTIC`)已删除:那条语句在真 MySQL / MariaDB 上是 `ER_PARSE_ERROR`,四店 18 个事务
+ *    一个都开不了(**B-020**),而它真正保证的东西现在由 ② 结构性地给出。同理,那个「可重复读」专用
+ *    动词也一并并入:隔离级不再由动词决定。
+ *
+ * **② 隔离级与事务模式是「连接的事实」,不是「动词的参数」** —— 见 {@link SqlDriver.facts}。
+ *    每条池连接首次借出时初始化一次(记忆化):
+ *      · MySQL 协议腿:`SET SESSION TRANSACTION ISOLATION LEVEL REPEATABLE READ`;`SELECT @@tidb_txn_mode`
+ *        有值 ⇒ TiDB(值必须是 `pessimistic`,否则会话级设定,**设不上就拒启**——本仓所有 `FOR UPDATE`
+ *        判据都以悲观锁读为前提);`ER_UNKNOWN_SYSTEM_VARIABLE` ⇒ InnoDB(MySQL / MariaDB)。
+ *      · PG:`SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL READ COMMITTED`,同样回读复核。
+ *        两腿钉的**值**不同(RR vs RC)是**引擎事实**不是口味:两边要的都是「加锁读=当前读」,而 PG 的
+ *        REPEATABLE READ 是快照隔离,`FOR UPDATE` 撞并发提交抛 `40001` 而不是等锁 —— 把 PG 钉成 RR 会把
+ *        本仓每一条 `FOR UPDATE` 腿变成需要重试的形。`default_transaction_isolation` 同样是可设变量,
+ *        所以 PG 腿也**不问服务器缺省**。
+ *    「服务器默认值不是结构保证」这条论证的出处是 [ref]:`transaction_isolation` 是可设变量,一台
+ *    跑 READ COMMITTED 的实例会把「一个事务一个快照」悄悄降成「每条语句各自取快照」,而依赖它的调用方
+ *    不会收到任何错。所以 MySQL 腿现在**每条连接自己钉**,不问部署。
+ *
+ * **③ 事务内的集合读一律是锁读**(`… FOR UPDATE`)。普通 `SELECT` 只用于三种情形:读**本事务自己刚写
+ *    的行**、读**值/时钟表达式**(不触任何存量行)、以及 PG 语法明禁加锁的形(**只有**聚合 / GROUP BY /
+ *    DISTINCT / 窗口 / 集合运算;`ORDER BY … LIMIT 1` 尾行读在 PG 上**合法**加锁,不属此类——7.60.0 重扫纠)。
+ *    理由:TiDB 悲观事务的普通 SELECT 仍钉 `start_ts`,`lockScope` 的锁等待窗内别副本的提交看不见
+ *    (**B-022**);InnoDB REPEATABLE READ 下则由本事务的第一条一致性读建 read view —— 两条都是
+ *    **版本相关的副作用**,不是保证。机器门:`test/sql-txn-semantics-gate.test.ts`(G-B,例外闭集
+ *    `INTRA_TXN_PLAIN_READS` 每条带理由);真值神谕:`test/sql-txn-semantics-integration.test.ts`(三引擎)。
+ *
+ * **④ 引擎事实不进店** —— `SqlDriver.facts` 是**运维读面**(`GET /v1/diagnostics/wiring` 的 `sqlEngine`
+ *    段与 `GET /v1/capabilities` 的 `sql` 位)的料。店里不许出现 `if (engine === …)`:引擎判别在全仓
+ *    只有连接初始化这一处,机器门 G-A 守着。`SqlDialect`(SQL **文本**方言,两值)与 `engine`(运行期
+ *    引擎事实,三值)是两条轴,刻意不合成一个三值。
  *
  * ─────────────────────────────────────────────────────────────────────────────────────────────────
  * REPLICATION PLAYBOOK — collapsing the remaining tidb-/pg- twin pairs ([ref] A12)
@@ -90,38 +123,57 @@ export interface SqlExec {
 }
 /** A pooled connection with transaction control (released by the caller in a `finally`). */
 export interface SqlTxConn extends SqlExec {
-    begin(): Promise<void>;
-    /** TiDB: `BEGIN PESSIMISTIC` (current-read txn). PG: plain `BEGIN`. */
-    beginPessimistic(): Promise<void>;
     /**
-     * Open a transaction whose reads are pinned to ONE snapshot ([ref]).
-     *
-     * 🔴 Why this is a named verb and not "just `begin()` — MySQL defaults to REPEATABLE READ anyway":
-     * a *server default* is not a structural guarantee. `transaction_isolation` is a settable
-     * server/session variable; a deployment (or a proxy, or a managed-MySQL vendor default) that runs
-     * READ COMMITTED silently turns "one transaction one snapshot" into "each statement its own
-     * snapshot" — and the caller that relied on it (`shared-memory-store-sql.ts` readBinding) goes on
-     * reading a torn scope/store pair with no error anywhere. The PG arm was already explicit; the
-     * MySQL arm was leaning on the default. Both arms now PIN it.
-     *
-     * The two arms diverge in WHERE the statement goes, and that is not cosmetic:
-     *  · MySQL/TiDB — `SET TRANSACTION ISOLATION LEVEL …` with no scope keyword applies to the **next**
-     *    transaction, and issuing it *inside* an open transaction is an ERROR
-     *    (`ER_CANT_CHANGE_TX_CHARACTERISTICS`). So it must precede `beginTransaction()`.
-     *  · PG — the same statement must be issued *inside* the transaction, before its first query.
-     * Writing one "portable" form would be wrong on one of the two engines; hence one verb, two texts.
+     * The ONE transaction verb (S-131). What its reads see is NOT decided here — it is decided once per
+     * pooled connection at initialization and reported by {@link SqlDriver.facts}. Read the
+     * `@contract txn.read-semantics` block at the top of this file before adding a transaction: the
+     * short version is **intra-transaction collection reads are LOCKING reads**, and a plain `SELECT`
+     * inside a transaction is only legal for this transaction's own writes, for a value/clock
+     * expression, or where PG syntax forbids locking (machine gate: `sql-txn-semantics-gate.test.ts`).
      */
-    beginRepeatableRead(): Promise<void>;
+    begin(): Promise<void>;
     commit(): Promise<void>;
     rollback(): Promise<void>;
     release(): void;
 }
+/**
+ * The runtime SQL **engine** — a different axis from {@link SqlDialect} (which is SQL *text*).
+ * `"tidb"` and `"innodb"` both speak the MySQL protocol and share every statement in this repo, but
+ * they do not share transaction semantics (TiDB has an optimistic mode and no gap locks; InnoDB has
+ * neither an optimistic mode nor `BEGIN PESSIMISTIC`), so the two words must stay separable.
+ */
+export type SqlEngine = "tidb" | "innodb" | "pg";
+/**
+ * What connection initialization ESTABLISHED and then READ BACK on this driver's pool (S-131 §1
+ * 补偿面). Operator read faces: `GET /v1/diagnostics/wiring` → `sqlEngine`, `GET /v1/capabilities`
+ * → `sql`. Store code must never read this (machine gate G-A) — engine discrimination exists in
+ * exactly one place in this repo, and it is `connect()`.
+ */
+export interface SqlEngineFacts {
+    readonly engine: SqlEngine;
+    /** `VERSION()` (MySQL protocol) / `server_version` (PG), verbatim. */
+    readonly version: string;
+    /** The session's transaction isolation, read back AFTER initialization set it. */
+    readonly isolation: string;
+    /** TiDB's session `tidb_txn_mode`; `null` = this engine has no such indicator (NOT "optimistic"). */
+    readonly txnMode: "pessimistic" | null;
+}
 export interface SqlDriver extends SqlExec {
     readonly dialect: SqlDialect;
+    /**
+     * Engine facts, established the first time ANY driver over the same pool hands out a pooled connection
+     * (state is keyed by the pool, so the twenty-odd store drivers sharing one pool report ONE set of facts);
+     * `null` until then (a pool that has never connected has nothing to report — it does not GUESS). Every
+     * pooled connection re-runs initialization the first time it is borrowed (memo keyed by connection
+     * identity), so a pool that reconnects after a fatal error re-establishes the session guarantee on the
+     * new connection rather than inheriting it.
+     */
+    readonly facts: SqlEngineFacts | null;
     connect(): Promise<SqlTxConn>;
 }
-/** MySQL-protocol (TiDB) driver. Transaction control uses mysql2's NATIVE methods — the historical
- *  call shape the fake-pool unit suites script around. */
+/** MySQL-protocol driver (TiDB / MySQL / MariaDB — `dialect` is the SQL TEXT axis, `facts.engine` the
+ *  runtime one). Transaction control uses mysql2's NATIVE methods — the historical call shape the
+ *  fake-pool unit suites script around. */
 export declare function mysqlDriver(pool: MySqlPool): SqlDriver;
 /** PostgreSQL driver. Transaction control is issued as STATEMENTS (node-pg has no native verbs). */
 export declare function pgDriver(pool: PgPool): SqlDriver;

package/dist/plugins/sql-driver.js

@@ -9,22 +9,83 @@ async function mysqlQuery(q, sql, params) {
     const [r] = (await q.query(sql, params ?? []));
     return mysqlResult(r);
 }
+function isUnknownSystemVariable(err) {
+    const e = err;
+    return e?.errno === 1193 || e?.code === "ER_UNKNOWN_SYSTEM_VARIABLE";
+}
+const POOL_SESSIONS = new WeakMap();
+function poolSession(pool) {
+    let st = POOL_SESSIONS.get(pool);
+    if (st === undefined)
+        POOL_SESSIONS.set(pool, (st = { initialized: new WeakSet(), facts: null }));
+    return st;
+}
+async function mysqlVar(c, sql) {
+    try {
+        const r = await mysqlQuery(c, sql);
+        const v = r.rows[0]?.v;
+        return v == null ? "" : String(v);
+    }
+    catch (err) {
+        if (isUnknownSystemVariable(err))
+            return null;
+        throw err;
+    }
+}
+function refuseSession(what) {
+    return new Error(`sql-driver: refusing this connection — ${what}. The repo's read semantics (see @contract txn.read-semantics in src/plugins/sql-driver.ts) ` +
+        `are established per pooled connection at initialization: session REPEATABLE READ on the MySQL protocol, plus TiDB's pessimistic transaction mode. ` +
+        `Neither is optional: every "SELECT … FOR UPDATE" decision point in this service is a CURRENT read only under them.`);
+}
+async function initMySqlSession(c) {
+    await c.query("SET SESSION TRANSACTION ISOLATION LEVEL REPEATABLE READ");
+    let txnMode = await mysqlVar(c, "SELECT @@tidb_txn_mode AS v");
+    const engine = txnMode === null ? "innodb" : "tidb";
+    if (engine === "tidb" && txnMode !== "pessimistic") {
+        try {
+            await c.query("SET SESSION tidb_txn_mode = 'pessimistic'");
+        }
+        catch (err) {
+            throw refuseSession(`this TiDB session is in "${txnMode}" transaction mode and SET SESSION tidb_txn_mode='pessimistic' was rejected (${err.message})`);
+        }
+        txnMode = await mysqlVar(c, "SELECT @@tidb_txn_mode AS v");
+        if (txnMode !== "pessimistic") {
+            throw refuseSession(`this TiDB session reports transaction mode "${txnMode ?? "<absent>"}" after SET SESSION tidb_txn_mode='pessimistic'`);
+        }
+    }
+    const isolation = (await mysqlVar(c, "SELECT @@transaction_isolation AS v")) ?? (await mysqlVar(c, "SELECT @@tx_isolation AS v"));
+    if (isolation === null) {
+        throw refuseSession("this server exposes neither @@transaction_isolation (MySQL 8.0+ / TiDB / MariaDB 11.1+) nor @@tx_isolation (MariaDB 10.x), so the isolation level cannot be VERIFIED");
+    }
+    if (isolation !== "REPEATABLE-READ") {
+        throw refuseSession(`this session reports isolation "${isolation}" after SET SESSION TRANSACTION ISOLATION LEVEL REPEATABLE READ`);
+    }
+    return { engine, version: (await mysqlVar(c, "SELECT VERSION() AS v")) ?? "", isolation, txnMode: engine === "tidb" ? "pessimistic" : null };
+}
 export function mysqlDriver(pool) {
+    const session = poolSession(pool);
     return {
         dialect: "tidb",
+        get facts() {
+            return session.facts;
+        },
         query: (sql, params) => mysqlQuery(pool, sql, params),
         async connect() {
             const c = await pool.getConnection();
+            const pooled = c.connection ?? c;
+            try {
+                if (!session.initialized.has(pooled)) {
+                    session.facts = await initMySqlSession(c);
+                    session.initialized.add(pooled);
+                }
+            }
+            catch (err) {
+                c.release();
+                throw err;
+            }
             return {
                 query: (sql, params) => mysqlQuery(c, sql, params),
                 begin: () => c.beginTransaction(),
-                beginPessimistic: async () => {
-                    await c.query("BEGIN PESSIMISTIC");
-                },
-                beginRepeatableRead: async () => {
-                    await c.query("SET TRANSACTION ISOLATION LEVEL REPEATABLE READ");
-                    await c.beginTransaction();
-                },
                 commit: () => c.commit(),
                 rollback: () => c.rollback(),
                 release: () => c.release(),
@@ -36,24 +97,46 @@ async function pgQuery(q, sql, params) {
     const res = await q.query(sql, params ?? []);
     return { rows: (res.rows ?? []), affected: res.rowCount ?? 0 };
 }
+async function initPgSession(c) {
+    await c.query("SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL READ COMMITTED");
+    const iso = await pgQuery(c, "SHOW transaction_isolation");
+    const isolation = String(iso.rows[0]?.transaction_isolation ?? "");
+    if (isolation !== "read committed") {
+        throw refuseSession(`this PostgreSQL session reports isolation "${isolation}" after SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL READ COMMITTED`);
+    }
+    const ver = await pgQuery(c, "SHOW server_version");
+    return {
+        engine: "pg",
+        version: String(ver.rows[0]?.server_version ?? ""),
+        isolation,
+        txnMode: null,
+    };
+}
 export function pgDriver(pool) {
+    const session = poolSession(pool);
     return {
         dialect: "pg",
+        get facts() {
+            return session.facts;
+        },
         query: (sql, params) => pgQuery(pool, sql, params),
         async connect() {
             const c = await pool.connect();
+            try {
+                if (!session.initialized.has(c)) {
+                    session.facts = await initPgSession(c);
+                    session.initialized.add(c);
+                }
+            }
+            catch (err) {
+                c.release();
+                throw err;
+            }
             return {
                 query: (sql, params) => pgQuery(c, sql, params),
                 begin: async () => {
                     await c.query("BEGIN");
                 },
-                beginPessimistic: async () => {
-                    await c.query("BEGIN");
-                },
-                beginRepeatableRead: async () => {
-                    await c.query("BEGIN");
-                    await c.query("SET TRANSACTION ISOLATION LEVEL REPEATABLE READ");
-                },
                 commit: async () => {
                     await c.query("COMMIT");
                 },

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

@@ -151,10 +151,14 @@ export interface StoreBackend {
      * 本身就是 optional,缺席 ⇒ 引擎的 `permissionRules.storeWired` 如实报 `false`,ask 帧不投 `ruleOffers`
      * (发一格按下去无处可兑的「不再询问」= wire 谎言,比缺席更坏)。
      *
+     * [ref](core 7.5.0):束里的规则那一格是 **durable 分区后端**(`PermissionRuleStoreBundle.durable`),
+     * 引擎接缝上的统一店由 `main.ts` 用 `createPermissionRuleStoreProvider({ durable })` 合成一次 ——
+     * 分区构成(durable / org / session)是**部署**决定,backend 只交它自己那一格。
+     *
      * `local` 车道**刻意不给 in-memory twin**:一条规则是「人授权过的持久事实」,进程内 Map 形会在重启时
      * 静默丢掉那份授权,而消费端(下一次同命令的 ask)读到的是「没有规则」——那是**放宽面**上的静默降级。
-     * ✅ **[ref] §1 已落 File 形**(那条注写下的解除条件逐字是「先落 File 形,core 现成
-     * `FilePermissionRuleStoreProvider` 即可当模子」——本车照办):`local` 现在返回一个**跨重启存活**的
+     * ✅ **[ref] §1 已落 File 形**(那条注写下的解除条件逐字是「先落 File 形,core 现成的
+     * File durable 分区 provider 即可当模子」——本车照办):`local` 现在返回一个**跨重启存活**的
      * 三面束,storeWired 在单机车道上真为 true。in-memory twin 的禁令不变,它禁的是「会遗忘的店」,
      * 不是「单机的店」。
      */

package/dist/plugins/task-list-store-sql.d.ts

@@ -8,8 +8,8 @@ export declare const TASK_LIST_ITEM_TABLE = "task_list_item";
  *
  * 🔴 为什么不直接把 sessionId 当 listKey:sessionId 是**调用方可自报**的不透明串(提交门
  * `http/server.ts` 只卡 ≤64 **字符** —— [#15] 刻意的宽松提交契约,不卡字节数也不卡字符集)。
- * 而本文件的身份键是字节面严格的:{@link assertListKeyBytes} 对 >190 字节当场拒(TiDB
- * `INSERT IGNORE` 静默截断案),PG twin 对孤代理/NUL 走 {@link PgUnstorableError} 拒。直接透传
+ * 而本文件的身份键是字节面严格的:{@link assertListKeyBytes} 对 >190 字节当场拒(超长键截断案),
+ * PG twin 对孤代理/NUL 走 {@link PgUnstorableError} 拒。直接透传
  * 的话,一个 64 字符全四字节 emoji 的会话(256 字节)会让**整条请求**在场景装配处 500 —— 而那条腿
  * 只是待办清单。派生一个恒可存的键把这一整类失败模式消掉(既不是 fail-open 也不是 fail-loud,是让
  * 那条臂不存在)。

package/dist/plugins/task-list-store-sql.js

@@ -56,7 +56,7 @@ export async function ensurePgTaskListSchema(q) {
 }
 async function ensureMeta(exec, dialect, listKey) {
     await exec(dialect === "tidb"
-        ? `INSERT IGNORE INTO ${TASK_LIST_META_TABLE} (list_key, next_id, next_sort) VALUES (?, 1, 1)`
+        ? `INSERT INTO ${TASK_LIST_META_TABLE} (list_key, next_id, next_sort) VALUES (?, 1, 1) ON DUPLICATE KEY UPDATE list_key = list_key`
         : `INSERT INTO ${TASK_LIST_META_TABLE} (list_key, next_id, next_sort) VALUES ($1, 1, 1) ON CONFLICT (list_key) DO NOTHING`, [listKey]);
 }
 async function allocateOn(exec, dialect, listKey) {

package/dist/plugins/usage-window-store-sql.d.ts

@@ -7,9 +7,11 @@
  * first-use bucket lapsed 即弃)完全由 core 纯函数执行——SQL 层零窗语义。
  *
  * 并发正确性(本 store 的靶心;两副本同 key 并发 charge 绝不能丢账——丢账方向=治理窗漏放):
- *  - **ensure-first + 行锁**(mailbox twin 正字先例,[ref] 复审靶1):事务内先幂等
- *    INSERT IGNORE / ON CONFLICT DO NOTHING 建空行 ⇒ SELECT ... FOR UPDATE 时行恒在,
- *    「无行 FOR UPDATE + INSERT」的并发死锁(InnoDB gap-lock)/dup 撞车形整个消掉。
+ *  - **ensure-first + 行锁**(mailbox twin 正字先例,[ref] 复审靶1):事务内先幂等建空行
+ *    (形 A,S-127:MySQL `ON DUPLICATE KEY UPDATE <pk> = <pk>` / PG `ON CONFLICT DO NOTHING`)⇒
+ *    `SELECT … FOR UPDATE` 时行恒在,「无行 FOR UPDATE + INSERT」的并发死锁/dup 撞车形整个消掉。
+ *    MySQL 侧动词**不能**是 `INSERT IGNORE`:InnoDB 对重复键的 IGNORE 取 S 锁,随后的 FOR UPDATE 要升 X,
+ *    两个并发 charge 各持一把 S 互等 ⇒ ER_LOCK_DEADLOCK(B-013);ON DUPLICATE 的重复键取的就是 X。
  *  - charge 频率低(core 只在任务进场/turn 边界/收尾 delta 提交),悲观锁简单正确,不用乐观 CAS。
  *  - `read` 无锁单 SELECT(readUsageRecord 纯函数);行缺席 = EMPTY_USAGE_WINDOW_RECORD。
  *  - record JSON 坏形(手工污染)= **fail-loud throw**:治理窗算错=计费面撒谎,不 fail-open。

package/dist/plugins/usage-window-store-sql.js

@@ -69,11 +69,7 @@ export class TiDBUsageWindowStore {
         const c = await this.pool.getConnection();
         try {
             await c.beginTransaction();
-            await c.query(`INSERT IGNORE INTO ${USAGE_WINDOW_TABLE} (usage_key, record, updated_at_ms) VALUES (?, ?, ?)`, [
-                key,
-                JSON.stringify(EMPTY_USAGE_WINDOW_RECORD),
-                at,
-            ]);
+            await c.query(`INSERT INTO ${USAGE_WINDOW_TABLE} (usage_key, record, updated_at_ms) VALUES (?, ?, ?) ON DUPLICATE KEY UPDATE usage_key = usage_key`, [key, JSON.stringify(EMPTY_USAGE_WINDOW_RECORD), at]);
             const [rows] = (await c.query(`SELECT record FROM ${USAGE_WINDOW_TABLE} WHERE usage_key = ? FOR UPDATE`, [key]));
             if (rows.length === 0) {
                 throw new Error(`usage_window row for key "${key}" vanished between ensure and lock — refusing to drop a governance charge`);

package/dist/rules-consent.d.ts

@@ -1,16 +1,13 @@
-import { type RuleOwner, type ImportPreview, type RedeemedBatchMember, type ImportedSettingsLayer, type PersistedAllowRule, type RemoveResult, type EditedRuleTextPrecheck, type RuleScope, type RuleOffer } from "@sema-agent/core";
-import type { PermissionRuleStoreProvider, RuleApprovalRecordStore } from "@sema-agent/core";
+import { type RuleOwner, type ImportPreview, type RedeemedBatchMember, type ImportedSettingsLayer, type PersistedAllowRule, type EffectivePermissionRule, type RemoveResult, type EditedRuleTextPrecheck, type RuleScope, type RuleOffer } from "@sema-agent/core";
+import type { DurableRulePartitionProvider, PermissionRuleStoreProvider, RuleApprovalRecordStore } from "@sema-agent/core";
 import { type RuleImportTicket, type RuleTicketPurpose, type RuleTicketReclaimResult, type RuleTicketRedeemResult, type RuleTicketSnapshot } from "./plugins/permission-rule-store-sql.js";
 /**
- * 本车道**真正**依赖的三面(**结构**接口,不是 SQL 类)。
- *
- * 🔴 为什么不直接吃 `PermissionRuleStores`(SQL 束):同意车道是**纯协议逻辑**,它对「行躺在 MySQL 还是
- * PG 还是别处」一无所知也不该知道。吃结构接口有两个真收益:①单元测试能用 core 自己的
- * `InMemoryPermissionRuleStore` / `InMemoryRuleApprovalRecordStore` 驱动**同一段**代码(而不是为了测协议
- * 去拉一个数据库);②将来若真出了 File 形规则店,本文件一个字不用改。SQL 束结构上满足本接口。
+ * 规则分区**之外**的两只记录面 —— 它们是 server 自铸的(审批记录的 SQL/File 形、CC 导入票),
+ * 与 [ref] 的分区族不是同一件东西,所以在这里单列一次:一个 backend 交出来的束
+ * ({@link PermissionRuleStoreBundle})与同意车道消费的束({@link RuleConsentStores})都含这两面,
+ * 差的只是规则那一格躺的是 **durable 分区后端**还是**合成好的统一店**。
  */
-export interface RuleConsentStores {
-    provider: PermissionRuleStoreProvider;
+export interface RuleConsentRecordStores {
     /** core 的记录店面 + 一个**可选**的加项:`discardPendingRecord`(超帽拒绝时收掉 `prepareCcImport`
      *  已经落盘的那一条 pending 记录)。没有这个加项的后端只是留一条孤儿行,不影响任何判决
      *  (语义与「已确认的记录永不被收」的硬条款见 SQL 侧同名方法)。 */
@@ -51,6 +48,22 @@ export interface RuleConsentStores {
         reclaim(ticketId: string, principal: string, purpose: RuleTicketPurpose, minClaimAgeMs: number): Promise<RuleTicketReclaimResult>;
     };
 }
+/**
+ * 本车道**真正**依赖的三面(**结构**接口,不是 SQL 类)。
+ *
+ * 🔴 为什么不直接吃 `PermissionRuleStores`(SQL 束):同意车道是**纯协议逻辑**,它对「行躺在 MySQL 还是
+ * PG 还是别处」一无所知也不该知道。吃结构接口有两个真收益:①单元测试能用 core 自己的
+ * `InMemoryDurableRulePartition` / `InMemoryRuleApprovalRecordStore` 驱动**同一段**代码(而不是为了测协议
+ * 去拉一个数据库);②将来若真出了 File 形规则店,本文件一个字不用改。SQL 束结构上满足本接口。
+ *
+ * 🔴 `provider` 是 [ref] **合成后**的统一店(`createPermissionRuleStoreProvider` 的产物),不是
+ * backend 交出来的 durable 分区 —— core 的 `removePersistedRule` / `RuleConsentDeps.provider` 两口收的
+ * 都是它,而合成点只有 `main.ts` 一处:引擎接缝(`RunnerDeps.permissionRuleStore`)与本车道读的必须是
+ * **同一只**对象,否则「卡上给的候选」与「引擎放行时看到的规则」会分别站在两只店上。
+ */
+export interface RuleConsentStores extends RuleConsentRecordStores {
+    provider: PermissionRuleStoreProvider;
+}
 /**
  * 一个 backend 交出来的**完整**规则店束 = 同意车道要的三面 + boot 期审计要的窄读口。
  *
@@ -59,7 +72,13 @@ export interface RuleConsentStores {
  * 结构接口是这条 seam 唯一站得住的形——两个实现各自满足它,消费点(main 装配 / 同意车道 / 撤销面
  * 路由)一个字都不用知道行躺在哪里。
  */
-export interface PermissionRuleStoreBundle extends RuleConsentStores {
+export interface PermissionRuleStoreBundle extends RuleConsentRecordStores {
+    /** [ref] 的 **durable 分区后端**(`user` + `project` 两源)。**不是**引擎接缝本身:
+     *  `RunnerDeps.permissionRuleStore` 与 {@link RuleConsentStores.provider} 是
+     *  `createPermissionRuleStoreProvider({ durable })` 合成出来的统一店,合成在 `main.ts` 一处发生一次。
+     *  分区构成(接不接 org / session)是**部署**决定,不是 backend 决定 —— 让 backend 各自合成,等于
+     *  日后接 org 分区时要挨个改后端,而两个后端合成得不一样时没有任何人看得出来。 */
+    durable: DurableRulePartitionProvider;
     /** [ref] §3:库里已有几只规则桶(一 owner 一桶)。boot 期休眠行审计的**唯一**依赖;
      *  为什么数桶不数规则、以及读失败必须响亮,见 `boot/permission-rules-audit.ts` 与两个实现处的注。 */
     countBuckets(): Promise<number>;
@@ -491,7 +510,30 @@ export interface PersistedRuleWireRow {
     /** 去规范化的命令(core 的匹配器信的就是它 + `match`,不是重新解析 `rule`)。 */
     command: string;
     adds: PersistedAllowRule["adds"];
+    /** [ref](core 7.5.0):这一行来自哪个源。**由 `scope` 派生**(`global`⟺`user`、`project`⟺
+     *  `project`、`session`⟺`session`),不是行上另存的第二个字节 —— core 的 `ruleSourceOf` 是整条映射。
+     *  今天本部署只接 durable 一格分区 ⇒ 值域实为 `user | project`。
+     *
+     *  🔴 为什么上 wire 而不是丢掉:统一读把这一格**交到手里了**,治理列举知道而不说 = 一次 wire 谎言的
+     *  反面(客户端只能自己去 decode `scope` 猜),而 org 分区接线的那天它会立刻变得承重。 */
+    source: EffectivePermissionRule["source"];
+    /** [ref]:这一行的**站位** —— `live` 或 `shadowed-by-org`(org deny 盖到它的命令模式上)。
+     *  今天无 org 分区 ⇒ 恒 `live`;这一格正是「接了 org 分区之后治理面必须看得见的那件事」。 */
+    status: EffectivePermissionRule["status"];
 }
+/**
+ * 一条**可导入**的规则行 = 列举行**减去两格派生键**。
+ *
+ * 🔴 为什么导入输入面不收 `source`/`status`:两格都是**派生**的 —— `source` 由 `scope` 派生
+ * (core 的 `ruleSourceOf` 是整条映射,d.ts 逐字「A row never carries a second source byte that could
+ * drift from its scope」),`status` 由 org 分区的遮蔽判据派生。一个调用方递进来的 `source` 只会与它
+ * 自己的 `scope` 漂,而漂的落点是治理面上「这行到底归谁管」。同族纪律 core 自己在卡面投影上也写过
+ * (「derived HERE, at projection time … never accepted from a caller」)。
+ *
+ * 这不是两份平行形状:`Omit` 让「导入面 = 列举面 − 派生键」是一条**机器判据**,列举行加员时导入面
+ * 自动跟随、`LOCAL_IMPORT_ROW_SHAPE_PIN`(路由侧)当场编译红。
+ */
+export type ImportableRuleRow = Omit<PersistedRuleWireRow, "source" | "status">;
 /** 列举结果。`rev` = 这只桶的 OCC 版本,游标绑它(见路由侧的游标注)。 */
 export interface PersistedRuleListing {
     rows: PersistedRuleWireRow[];
@@ -531,7 +573,7 @@ export interface RuleConsentLane {
     /** 导入道:原子消费票 → confirm → redeemRuleBatch。 */
     redeemImport(principal: string, ticket: string): Promise<RuleImportRedeemed>;
     /** [ref] A7 直通道:逐行校验 → 预览 + pending 记录 + 票(零可导入行 ⇒ 无票)。 */
-    prepareLocalImport(principal: string, rows: readonly PersistedRuleWireRow[]): Promise<LocalImportPrepared>;
+    prepareLocalImport(principal: string, rows: readonly ImportableRuleRow[]): Promise<LocalImportPrepared>;
     /** [ref] A7 直通道:三态兑付(首兑 / 逐字回放 / 崩溃窗重驱),终局落进票行。 */
     redeemLocalImport(principal: string, ticket: string): Promise<LocalImportRedeemed>;
     /**

package/dist/rules-consent.js

@@ -4,7 +4,7 @@ import { recordFailOpen } from "./observability/fail-open.js";
 import { createLogger } from "./observability/logger.js";
 import { MAX_CWD_CHARS } from "./task-cwd.js";
 import { CONTROL_AND_BIDI_CHARS, hasBidiControls } from "./text-bidi.js";
-import { confirmRuleApproval, parseAllowRuleText, precheckEditedRuleText, prepareCardApproval, prepareCcImport, redeemRuleBatch, redeemRuleTicket, removePersistedRule, } from "@sema-agent/core";
+import { confirmRuleApproval, parseAllowRuleText, precheckEditedRuleText, prepareCardApproval, prepareCcImport, redeemRuleBatch, redeemRuleTicket, removePersistedRule, effectiveOrThrow, } from "@sema-agent/core";
 import { buildRulePayloadHash } from "./plugins/permission-rule-store-sql.js";
 export const RULE_IMPORT_TICKET_TTL_MS = 10 * 60_000;
 export const RULE_IMPORT_RETRY_AFTER_SEC = 2;
@@ -682,10 +682,10 @@ export function createRuleConsentLane(stores, opts) {
             }
         },
         async listRules(bucket) {
-            const stored = await storeForBucket(stores.provider, bucket).list();
-            const rows = stored.rules.map((r) => ({ rule: r.rule, scope: serializeRuleScope(r.scope), tool: r.tool, match: r.match, command: r.command, adds: r.adds }));
+            const view = await effectiveOrThrow(storeForBucket(stores.provider, bucket));
+            const rows = view.rules.map((r) => ({ rule: r.rule, scope: serializeRuleScope(r.scope), tool: r.tool, match: r.match, command: r.command, adds: r.adds, source: r.source, status: r.status }));
             rows.sort((a, b) => (a.scope < b.scope ? -1 : a.scope > b.scope ? 1 : a.rule < b.rule ? -1 : a.rule > b.rule ? 1 : 0));
-            return { rows, rev: stored.rev };
+            return { rows, rev: view.rev };
         },
         async removeRule(input) {
             return await removePersistedRule({ rule: input.rule, scope: input.scope, principal: input.principal, provider: stores.provider });

package/dist/run-local.d.ts

@@ -82,7 +82,8 @@ export interface LocalGovernanceConfigView extends DeploymentGovernanceConfigVie
  *   test/run-local.test.ts(该钉已由 🟡 特征化翻成 🔴 正控)。
  * · **禁 memoize**:四个旋钮都是热改字段,每次装配现读活 config(与另两条腿同一姿势)。
  */
-export declare function applyLocalGovernance(base: TaskSpec, config: LocalGovernanceConfigView, workspaceDir: string): TaskSpec;
+/** @param engineDataRoot 本腿已铸的引擎记忆根(`memoryEngineBackendFor(config, root)?.root`,S-133 单一写者);`undefined` = 引擎未接。 */
+export declare function applyLocalGovernance(base: TaskSpec, config: LocalGovernanceConfigView, workspaceDir: string, engineDataRoot: string | undefined): TaskSpec;
 /** {@link createLocalApprover} 的 io 面(全部可注入,所以两条臂都测得动)。 */
 export interface LocalApproverIo {
     /** 这次调用是不是接在一个人面前(生产里 = `process.stdin.isTTY`)。 */

package/dist/run-local.js

@@ -111,8 +111,8 @@ export function missingGatewayRequirements(config) {
     }
     return missing;
 }
-export function applyLocalGovernance(base, config, workspaceDir) {
-    return applyRuntimeGovernance({ ...base, toolPolicy: createApprovalBaselinePolicy(config) }, createDeploymentGovernanceInputs(config, { env: new NodeExecutionEnv({ cwd: workspaceDir }), cwd: workspaceDir }));
+export function applyLocalGovernance(base, config, workspaceDir, engineDataRoot) {
+    return applyRuntimeGovernance({ ...base, toolPolicy: createApprovalBaselinePolicy(config) }, createDeploymentGovernanceInputs(config, { env: new NodeExecutionEnv({ cwd: workspaceDir }), cwd: workspaceDir }, { engineDataRoot }));
 }
 export function createLocalApprover(io) {
     return async (req, signal) => {
@@ -472,7 +472,7 @@ export async function runLocal(argv, deps = {}) {
         ...(mcp ? { mcp } : {}),
         ...(a2a ? { a2a } : {}),
         ...(Object.keys(limits).length > 0 ? { limits } : {}),
-    }, config, workspaceDir);
+    }, config, workspaceDir, memoryEngine?.root);
     logger.info("run_local_start", { scenario: scenarioName, model: spec.model, sessionId, exec: config.remoteExec?.provider ?? "in-process" });
     const settleSessionBackground = async () => {
         const reaped = defaultTaskRegistry.reapSessionBackground(sessionId, scope);