@sema-agent/server 7.59.0 → 7.60.0

package/dist/plugins/permission-rule-store-sql.d.ts

@@ -1,10 +1,10 @@
 import { z } from "zod";
-import { type PermissionRuleWriter, type PermissionRuleStore, type PermissionRuleStoreProvider, type RuleScope, type RuleSyncFrontier, type RuleApprovalRecord, type StaleRuleApprovalRecord, type RuleApprovalRecordStore, type RuleOwner } from "@sema-agent/core";
+import { type PermissionRuleWriter, type DurableRulePartition, type DurableRulePartitionProvider, type RuleScope, type RuleSyncFrontier, type RuleApprovalRecord, type StaleRuleApprovalRecord, type RuleApprovalRecordStore, type RuleOwner } from "@sema-agent/core";
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { PgQueryFn } from "./pg-query.js";
 import { type SqlDriver } from "./sql-driver.js";
 /**
- * 一只店的写面,或 `undefined`(该 backend 从引擎侧看是只读的)。
+ * 一只 durable 分区的写面,或 `undefined`(该 backend 从引擎侧看是只读的)。
  *
  * 与 core 的 `writerOf` 的**唯一**区别是判据更严:core 只看 `apply`/`nextDot` 两个方法在不在(它服务的是
  * 引擎自己的兑付腿),本函数还要求 `readRaw` —— 本仓的消费点(测试/取证)读的是**完整**写面,少一个方法
@@ -13,7 +13,7 @@ import { type SqlDriver } from "./sql-driver.js";
  * 结构检查而不是断言:没有这个函数,每个调用点都会各写一次 `as unknown as {…}`,那既是三处宽松断言,
  * 也是三份会各自漂的形状假设。
  */
-export declare function writerOfSqlRuleStore(store: PermissionRuleStore): PermissionRuleWriter | undefined;
+export declare function writerOfSqlRuleStore(store: DurableRulePartition): PermissionRuleWriter | undefined;
 /**
  * 382P1(core 7.0.0 [ref] §4.3)—— 这是 **DURABLE 二员面**的 at-rest 形:`{global, project-with-root}`,
  * 与 core `isValidDurableScope` 逐格等价(`test/permission-rule-durable-face-pin.test.ts` 探针表钉住)。
@@ -127,17 +127,20 @@ export declare function buildRuleBucketChecksum(body: {
     observedVector?: RuleSyncFrontier;
 }): string;
 /**
- * SQL 双方言的 {@link PermissionRuleStoreProvider}。
+ * SQL 双方言的 {@link DurableRulePartitionProvider} —— [ref] 里的 **durable 分区后端**
+ * (`user` + `project` 两源的 OR-Set CRDT),**不是**引擎接缝本身:
+ * `RunnerDeps.permissionRuleStore` 是 `createPermissionRuleStoreProvider({ durable })` 合成出来的
+ * 统一店,合成点在 `main.ts` 一处(分区构成是**部署**决定,不是 backend 决定)。
  *
- * `forPrincipal(undefined)` 恒解析成**零规则**店(core 硬条款:未鉴权任务解析到零规则而不是一只共享桶
- * —— 放宽面上的 fail-closed 是「更少的允许」,绝不是「一只共享的」)。
+ * `forPrincipal(undefined)` 恒解析成**零规则**分区(core 硬条款:未鉴权任务解析到零规则而不是一只
+ * 共享桶 —— 放宽面上的 fail-closed 是「更少的允许」,绝不是「一只共享的」)。
  */
-export declare class SqlPermissionRuleStoreProvider implements PermissionRuleStoreProvider {
+export declare class SqlDurableRulePartitionProvider implements DurableRulePartitionProvider {
     private readonly db;
     private readonly now;
     constructor(db: SqlDriver, now?: () => number);
-    forPrincipal(principal: string | undefined): PermissionRuleStore;
-    forLocalOwner(): PermissionRuleStore;
+    forPrincipal(principal: string | undefined): DurableRulePartition;
+    forLocalOwner(): DurableRulePartition;
 }
 /**
  * durable 审批记录。CAS **按 rev**,不按 state —— core 的原话:批记录的第二个候选会 redeemed→redeemed,
@@ -428,9 +431,10 @@ export declare const RULE_PENDING_APPROVAL_RETENTION_MS: number;
  * 同口径)。在那之前,MySQL 存量库上这条腿仍是全表扫 —— 但每轮 500 行的上界让它的**单次**代价仍然有界。
  */
 export declare const RULE_REAP_BATCH = 500;
-/** 三个 SQL 店的一次性装配束(one driver, three faces)。 */
+/** 三个 SQL 面的一次性装配束(one driver, three faces)。`durable` = [ref] 的 durable 分区后端;
+ *  引擎接缝上的统一店由 `main.ts` 用 `createPermissionRuleStoreProvider({ durable })` 合成一次。 */
 export interface PermissionRuleStores {
-    provider: SqlPermissionRuleStoreProvider;
+    durable: SqlDurableRulePartitionProvider;
     approvals: SqlRuleApprovalRecordStore;
     tickets: SqlRuleImportTicketStore;
     /** [ref] §3 —— boot 期休眠行审计的**窄读口**:库里已有几只桶(`permission_rule` 一行一桶)。

package/dist/plugins/permission-rule-store-sql.js

@@ -1,6 +1,6 @@
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { z } from "zod";
-import { applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, foldDelta, parseAllowRuleText, screenRuleSyncState, PERMISSION_RULE_WRITER, RULE_SYNC_DROP_CODES, } from "@sema-agent/core";
+import { applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, foldDelta, parseAllowRuleText, screenRuleSyncState, PERMISSION_RULE_WRITER, RULE_SYNC_DROP_CODES, EMPTY_DURABLE_RULE_PARTITION, } from "@sema-agent/core";
 import { dialectProtocolJsonEncoder } from "./sql-driver.js";
 import { isMissingColumnError } from "./sql-errors.js";
 import { canonicalJson } from "../canonical-json.js";
@@ -332,7 +332,7 @@ function parseColumn(schema, raw, column, ownerKey) {
         throw new Error(`permission_rule.${column} for bucket ${ownerKey} does not carry a readable shape: ${parsed.error.message}`);
     return parsed.data;
 }
-class SqlPermissionRuleStore {
+class SqlDurableRulePartition {
     db;
     owner;
     now;
@@ -490,7 +490,7 @@ class SqlPermissionRuleStore {
         },
     };
 }
-export class SqlPermissionRuleStoreProvider {
+export class SqlDurableRulePartitionProvider {
     db;
     now;
     constructor(db, now = Date.now) {
@@ -499,17 +499,13 @@ export class SqlPermissionRuleStoreProvider {
     }
     forPrincipal(principal) {
         if (typeof principal !== "string" || principal === "")
-            return ZERO_RULE_STORE;
-        return new SqlPermissionRuleStore(this.db, { kind: "principal", principal }, this.now);
+            return EMPTY_DURABLE_RULE_PARTITION;
+        return new SqlDurableRulePartition(this.db, { kind: "principal", principal }, this.now);
     }
     forLocalOwner() {
-        return new SqlPermissionRuleStore(this.db, { kind: "local-owner" }, this.now);
+        return new SqlDurableRulePartition(this.db, { kind: "local-owner" }, this.now);
     }
 }
-const ZERO_RULE_STORE = {
-    list: async () => ({ rules: [], tombstones: [], rev: 0 }),
-    durability: "process-local",
-};
 export class SqlRuleApprovalRecordStore {
     db;
     now;
@@ -744,7 +740,7 @@ export const RULE_REAP_BATCH = 500;
 export function createSqlPermissionRuleStores(db, now) {
     const q = (tidb, pg) => (db.dialect === "tidb" ? tidb : pg);
     return {
-        provider: new SqlPermissionRuleStoreProvider(db, now),
+        durable: new SqlDurableRulePartitionProvider(db, now),
         approvals: new SqlRuleApprovalRecordStore(db, now),
         tickets: new SqlRuleImportTicketStore(db),
         reapExpired: async (nowMs) => {

package/dist/plugins/retention-lane-store-sql.d.ts

@@ -21,8 +21,8 @@
  *   - upsert:`ON DUPLICATE KEY UPDATE col = VALUES(col)` vs `ON CONFLICT (…) DO UPDATE SET col = EXCLUDED.col`;
  *   - 条件自增:`IF(cond, 0, 1)` vs `CASE WHEN cond THEN 0 ELSE 1 END`(本文件不用 —— 见 `acquire` 顶注:
  *     自增判据在**应用层**算,因为它同时要产出返回给调用方的 token);
- *   - 事务动词:平凡 `begin()`(理由逐字见车1 `SqlRetentionStore.tx` 的头注:`BEGIN PESSIMISTIC` 是 TiDB
- *     专有语法,发到普通 MySQL 上是语法错,而发车门的 canonical `TIDB_TEST_URL` 指向的正是普通 MySQL)。
+ *   - 事务动词:只有 `begin()` 一个;读语义的判据在 {@link SqlTxConn.begin} 的 `@contract txn.read-semantics`
+ *     (本店唯一的读是 `acquire` 的租约行 `FOR UPDATE` —— 锁读在两引擎都是当前读)。
  *   - schema 属主:**四张表全部由车1 的 `retention-store-sql.ts` 建**(`TIDB_RETENTION_STATEMENTS` /
  *     `PG_RETENTION_SCHEMA`)。本文件一条 DDL 都不发 —— 「一张表恰好一个 DDL 属主」(db-gate.ts 顶注
  *     的实测结论:第二个属主的 `IF NOT EXISTS` 会静默吞掉列/索引差异)。

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

@@ -36,8 +36,7 @@
  *   - JSON 提取(workflow_run 的 originatingSessionId):`JSON_UNQUOTE(JSON_EXTRACT(run,'$.x'))` vs
  *     `run::json->>'x'`
  *   - 表级 `COLLATE utf8mb4_bin` vs 逐列 `COLLATE "C"`(`isolation-key-collation` 门执法)
- *   - 事务动词:两条方言都是平凡 `begin()` —— **不是** `beginPessimistic()`(它是 TiDB 专有语法,发到
- *     普通 MySQL 上语法错;完整判据见 `SqlRetentionStore.tx` 的头注)
+ *   - 事务动词:只有 `begin()` 一个;读语义的判据在 {@link SqlTxConn.begin} 的 `@contract txn.read-semantics`
  *   - schema 属主:MySQL DDL 由本文件导出、展开进 `tidb-pool.ts` 的 `SCHEMA_STATEMENTS`;PG DDL 由本文件的
  *     `ensurePgRetentionSchema` 导出、由 `pg-pool.ts` 的中央 `ensurePgSchema` 组合(与 leader-run 同姿势)。
  *
@@ -191,16 +190,9 @@ export declare class SqlRetentionStore implements ManagedRetentionCapability {
         params: unknown[];
     };
     /**
-     * 事务壳 —— **平凡 `begin()`,不是 `beginPessimistic()`**(真库实测定谳,不是口味):
-     *
-     *  · MySQL-protocol 腿:`BEGIN PESSIMISTIC` 是 **TiDB 专有语法**,发到普通 MySQL 上是语法错
-     *    (本机 MySQL 9.7 实测 `ER_PARSE_ERROR near 'PESSIMISTIC'`)—— 而发车门 2.6 的 canonical
-     *    `TIDB_TEST_URL` 默认指向的正是一台**普通 MySQL**。用那条动词等于让本店在标准工作流上必红。
-     *  · 语义上也不需要它:本店要的只是 `SELECT … FOR UPDATE` 是**当前读**。InnoDB 的加锁读在 RR 下本来
-     *    就读最新已提交版本;TiDB 自 3.0.8 起事务默认就是悲观模式,同样是当前读。显式动词只在「部署把
-     *    TiDB 改回乐观模式」这一种配置下才多出保障,而那种部署会同时打破仓内其它 FOR UPDATE 腿
-     *    (run-store 的 task_active 门、checkpoint 的 approval 门),不是本店能独自承担的假设。
-     *  · PG:READ COMMITTED 逐语句取新快照,平凡 `BEGIN` 即所需。
+     * 事务壳。本店要的是「`SELECT … FOR UPDATE` 是**当前读**」—— 判据不在这里,在
+     * {@link SqlTxConn.begin} 的 `@contract txn.read-semantics`(隔离级与 TiDB 悲观模式是**连接的事实**,
+     * 每条池连接初始化时钉一次,设不上就拒启)。
      *
      * `protected` = 真库套件的语句录制注入点(判据「hold 锁读是事务首条 SQL」靠它自证)。
      */

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

@@ -367,6 +367,10 @@ export class SqlRetentionStore {
             const s = set("owner_session_id", 1);
             await conn.query(`DELETE FROM tool_result WHERE ${s.sql}`, s.params);
         }
+        {
+            const s = set("scope", 1);
+            await conn.query(`SELECT scope FROM file_history_scope WHERE ${s.sql} ORDER BY scope FOR UPDATE`, s.params);
+        }
         for (const [table, col] of [
             ["resume_anchor", "session_id"],
             ["approval_exemption", "session_id"],

package/dist/plugins/session-policy-store-sql.d.ts

@@ -29,8 +29,15 @@ export declare class SqlSessionPolicyStore implements SessionPolicyStore {
      *  Return shape aligned to core 1.423's optional interface seam (`Promise<void>`) — the affectedRows count was
      *  incidental and unconsumed; the integration test asserts the post-state (listBySession empty) instead. */
     deleteBySession(sessionId: string): Promise<void>;
-    /** `begin()` (NOT `beginPessimistic()`) — matches both twins' original call shape: TiDB's native
-     *  `beginTransaction()` (optimistic), PG's plain `BEGIN`. Normalized by SqlDriver's shared tx plumbing. */
+    /**
+     * The store's one read-check-write transaction. Its load-bearing read is line ~106's
+     * `SELECT rules, rev … FOR UPDATE` — a LOCKING read, therefore a CURRENT read on both engines, which is
+     * what makes the loosen-diff decision see the prior it is diffing against. That "therefore" is not a
+     * property of the verb: it holds because {@link SqlTxConn.begin}'s `@contract txn.read-semantics` pins
+     * TiDB to pessimistic transactions at connection init (an optimistic session would read `FOR UPDATE` off
+     * the start-ts snapshot). Second line of defence, unchanged: the `rev` re-check plus the first write's
+     * PK race.
+     */
     private tx;
 }
 /** MySQL-protocol (TiDB) binding — historical class name + ctor shape preserved. */

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 的禁令不变,它禁的是「会遗忘的店」,
      * 不是「单机的店」。
      */