@sema-agent/server 7.58.0 → 7.60.0

package/dist/plugins/file-history-store-sql.js

@@ -49,7 +49,7 @@ export class SqlFileHistoryStore {
         for (const scope of [...new Set(scopes)].sort()) {
             let locked = false;
             for (let i = 0; i < 3 && !locked; i++) {
-                await conn.query(this.q("INSERT IGNORE INTO file_history_scope (scope, created_at_ms) VALUES (?,?)", "INSERT INTO file_history_scope (scope, created_at_ms) VALUES ($1,$2) ON CONFLICT (scope) DO NOTHING"), [scope, Date.now()]);
+                await conn.query(this.q("INSERT INTO file_history_scope (scope, created_at_ms) VALUES (?,?) ON DUPLICATE KEY UPDATE scope = scope", "INSERT INTO file_history_scope (scope, created_at_ms) VALUES ($1,$2) ON CONFLICT (scope) DO NOTHING"), [scope, Date.now()]);
                 const r = await conn.query(this.q("SELECT scope FROM file_history_scope WHERE scope = ? FOR UPDATE", "SELECT scope FROM file_history_scope WHERE scope = $1 FOR UPDATE"), [scope]);
                 locked = Boolean(r.rows[0]);
             }
@@ -92,7 +92,7 @@ export class SqlFileHistoryStore {
                 const conn = await this.db.connect();
                 let minted = false;
                 try {
-                    await conn.beginPessimistic();
+                    await conn.begin();
                     await this.lockScope(conn, scope);
                     const ins = await conn.query(this.q("INSERT IGNORE INTO file_history_tracked (scope, key_hash, track_key, key_kind, key_family, base_available, observed_later, created_at_ms) VALUES (?,?,?,?,?,?,0,?)", "INSERT INTO file_history_tracked (scope, key_hash, track_key, key_kind, key_family, base_available, observed_later, created_at_ms) VALUES ($1,$2,$3,$4,$5,$6,FALSE,$7) ON CONFLICT (scope, key_hash) DO NOTHING"), [scope, keyHash, key, keyDesc.kind, keyDesc.family, this.bool(baseAvailable), Date.now()]);
                     minted = ins.affected === 1;
@@ -159,7 +159,7 @@ export class SqlFileHistoryStore {
             }
             const conn = await this.db.connect();
             try {
-                await conn.beginPessimistic();
+                await conn.begin();
                 await this.lockScope(conn, scope);
                 const del = await conn.query(this.q(`DELETE FROM file_history_tracked WHERE scope = ? AND key_hash = ? AND observed_later = 0
                AND NOT EXISTS (SELECT 1 FROM file_history_boundary_file bf WHERE bf.scope = ? AND bf.key_hash = ?)
@@ -202,8 +202,9 @@ export class SqlFileHistoryStore {
             baseAvailable: truthy(row.base_available),
         }));
     }
-    async loadVersions(exec, scope) {
-        const r = await exec.query(this.q("SELECT key_hash, version, blob_hash, mode, parent_ident, backup_time FROM file_history_version WHERE scope = ? ORDER BY version", "SELECT key_hash, version, blob_hash, mode, parent_ident, backup_time FROM file_history_version WHERE scope = $1 ORDER BY version"), [scope]);
+    async loadVersions(exec, scope, forUpdate = false) {
+        const suffix = forUpdate ? " FOR UPDATE" : "";
+        const r = await exec.query(this.q(`SELECT key_hash, version, blob_hash, mode, parent_ident, backup_time FROM file_history_version WHERE scope = ? ORDER BY version${suffix}`, `SELECT key_hash, version, blob_hash, mode, parent_ident, backup_time FROM file_history_version WHERE scope = $1 ORDER BY version${suffix}`), [scope]);
         const out = new Map();
         for (const row of r.rows) {
             const kh = String(row.key_hash);
@@ -240,9 +241,9 @@ export class SqlFileHistoryStore {
             await this.beforeRetentionPass(scope);
             const conn = await this.db.connect();
             try {
-                await conn.beginPessimistic();
+                await conn.begin();
                 await this.lockScope(conn, scope);
-                const { rows } = await conn.query(this.q("SELECT entry_id, publish_seq FROM file_history_boundary WHERE scope = ? ORDER BY publish_seq ASC", "SELECT entry_id, publish_seq FROM file_history_boundary WHERE scope = $1 ORDER BY publish_seq ASC"), [scope]);
+                const { rows } = await conn.query(this.q("SELECT entry_id, publish_seq FROM file_history_boundary WHERE scope = ? ORDER BY publish_seq ASC FOR UPDATE", "SELECT entry_id, publish_seq FROM file_history_boundary WHERE scope = $1 ORDER BY publish_seq ASC FOR UPDATE"), [scope]);
                 const ordered = rows.map((r) => ({ id: String(r.entry_id), seq: Number(r.publish_seq) }));
                 if (ordered.length === 0) {
                     await conn.rollback();
@@ -275,8 +276,9 @@ export class SqlFileHistoryStore {
             recordFailOpen("server.file-history.retention-trim-failed", `scope=${scope} entry=${justCommitted}: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
-    async boundaryExists(exec, scope, entryId) {
-        const r = await exec.query(this.q("SELECT 1 FROM file_history_boundary WHERE scope = ? AND entry_id = ? LIMIT 1", "SELECT 1 FROM file_history_boundary WHERE scope = $1 AND entry_id = $2 LIMIT 1"), [scope, entryId]);
+    async boundaryExists(exec, scope, entryId, forUpdate = false) {
+        const suffix = forUpdate ? " FOR UPDATE" : "";
+        const r = await exec.query(this.q(`SELECT 1 FROM file_history_boundary WHERE scope = ? AND entry_id = ? LIMIT 1${suffix}`, `SELECT 1 FROM file_history_boundary WHERE scope = $1 AND entry_id = $2 LIMIT 1${suffix}`), [scope, entryId]);
         return Boolean(r.rows[0]);
     }
     async snapshot(scope, entryId, env, root, signal) {
@@ -344,7 +346,7 @@ export class SqlFileHistoryStore {
             await this.beforePublish(scope);
             const conn = await this.db.connect();
             try {
-                await conn.beginPessimistic();
+                await conn.begin();
                 await this.beforePublishLock(scope);
                 await this.lockScope(conn, scope);
                 if (signal?.aborted) {
@@ -356,17 +358,17 @@ export class SqlFileHistoryStore {
                     await conn.rollback();
                     return reapedEntryRefusal(entryId);
                 }
-                const seqRow = await conn.query(this.q("SELECT publish_seq FROM file_history_boundary WHERE scope = ? ORDER BY publish_seq DESC LIMIT 1 FOR UPDATE", "SELECT publish_seq FROM file_history_boundary WHERE scope = $1 ORDER BY publish_seq DESC LIMIT 1"), [scope]);
+                const seqRow = await conn.query(this.q("SELECT publish_seq FROM file_history_boundary WHERE scope = ? ORDER BY publish_seq DESC LIMIT 1 FOR UPDATE", "SELECT publish_seq FROM file_history_boundary WHERE scope = $1 ORDER BY publish_seq DESC LIMIT 1 FOR UPDATE"), [scope]);
                 const publishSeq = (seqRow.rows[0] !== undefined ? Number(seqRow.rows[0].publish_seq) : 0) + 1;
-                const ins = await conn.query(this.q("INSERT IGNORE INTO file_history_boundary (scope, entry_id, published_at_ms, publish_seq) VALUES (?,?,CAST(UNIX_TIMESTAMP(NOW(3))*1000 AS SIGNED),?)", "INSERT INTO file_history_boundary (scope, entry_id, published_at_ms, publish_seq) VALUES ($1,$2,(EXTRACT(EPOCH FROM clock_timestamp())*1000)::bigint,$3) ON CONFLICT (scope, entry_id) DO NOTHING"), [scope, entryId, publishSeq]);
-                if (ins.affected !== 1) {
-                    const won = await conn.query(this.q("SELECT 1 FROM file_history_boundary WHERE scope = ? AND entry_id = ? FOR UPDATE", "SELECT 1 FROM file_history_boundary WHERE scope = $1 AND entry_id = $2 FOR UPDATE"), [scope, entryId]);
-                    if (!won.rows[0]) {
-                        throw new Error(`boundary publish for entry "${entryId}" was suppressed without a same-entry winner (publish_seq allocation invariant breach) — refusing to report a boundary that was not stored`);
-                    }
+                const priorWinner = await conn.query(this.q("SELECT 1 FROM file_history_boundary WHERE scope = ? AND entry_id = ? FOR UPDATE", "SELECT 1 FROM file_history_boundary WHERE scope = $1 AND entry_id = $2 FOR UPDATE"), [scope, entryId]);
+                if (priorWinner.rows[0]) {
                     await conn.rollback();
                     return { ok: true };
                 }
+                const ins = await conn.query(this.q("INSERT IGNORE INTO file_history_boundary (scope, entry_id, published_at_ms, publish_seq) VALUES (?,?,CAST(UNIX_TIMESTAMP(NOW(3))*1000 AS SIGNED),?)", "INSERT INTO file_history_boundary (scope, entry_id, published_at_ms, publish_seq) VALUES ($1,$2,(EXTRACT(EPOCH FROM clock_timestamp())*1000)::bigint,$3) ON CONFLICT (scope, entry_id) DO NOTHING"), [scope, entryId, publishSeq]);
+                if (ins.affected !== 1) {
+                    throw new Error(`boundary publish for entry "${entryId}" was suppressed without a same-entry winner (publish_seq allocation invariant breach) — refusing to report a boundary that was not stored`);
+                }
                 for (const [keyHash, cap] of staged) {
                     let version;
                     if (cap.kind === "unchanged") {
@@ -496,16 +498,16 @@ export class SqlFileHistoryStore {
     async restorePlan(scope, entryId) {
         const conn = await this.db.connect();
         try {
-            await conn.beginPessimistic();
+            await conn.begin();
             await this.lockScope(conn, scope);
-            if (!(await this.boundaryExists(conn, scope, entryId))) {
+            if (!(await this.boundaryExists(conn, scope, entryId, true))) {
                 await conn.rollback();
                 return null;
             }
             await this.duringRestorePlan(scope, entryId);
-            const tracked = (await this.loadTracked(conn, scope)).sort((a, b) => (a.trackKey < b.trackKey ? -1 : a.trackKey > b.trackKey ? 1 : 0));
-            const versions = await this.loadVersions(conn, scope);
-            const mapRows = await conn.query(this.q("SELECT key_hash, version FROM file_history_boundary_file WHERE scope = ? AND entry_id = ?", "SELECT key_hash, version FROM file_history_boundary_file WHERE scope = $1 AND entry_id = $2"), [scope, entryId]);
+            const tracked = (await this.loadTracked(conn, scope, true)).sort((a, b) => (a.trackKey < b.trackKey ? -1 : a.trackKey > b.trackKey ? 1 : 0));
+            const versions = await this.loadVersions(conn, scope, true);
+            const mapRows = await conn.query(this.q("SELECT key_hash, version FROM file_history_boundary_file WHERE scope = ? AND entry_id = ? FOR UPDATE", "SELECT key_hash, version FROM file_history_boundary_file WHERE scope = $1 AND entry_id = $2 FOR UPDATE"), [scope, entryId]);
             const boundary = new Map(mapRows.rows.map((r) => [String(r.key_hash), Number(r.version)]));
             await conn.commit();
             return { tracked, versions, boundary };
@@ -524,9 +526,9 @@ export class SqlFileHistoryStore {
     async reap(scope, keepEntryIds) {
         const conn = await this.db.connect();
         try {
-            await conn.beginPessimistic();
+            await conn.begin();
             await this.lockScope(conn, scope);
-            const ids = await conn.query(this.q("SELECT entry_id FROM file_history_boundary WHERE scope = ?", "SELECT entry_id FROM file_history_boundary WHERE scope = $1"), [scope]);
+            const ids = await conn.query(this.q("SELECT entry_id FROM file_history_boundary WHERE scope = ? FOR UPDATE", "SELECT entry_id FROM file_history_boundary WHERE scope = $1 FOR UPDATE"), [scope]);
             const dropped = await this.reapWithin(conn, scope, new Set(keepEntryIds), ids.rows.map((r) => String(r.entry_id)));
             await conn.commit();
             return dropped;
@@ -557,7 +559,7 @@ export class SqlFileHistoryStore {
     async deleteBySession(scope) {
         const conn = await this.db.connect();
         try {
-            await conn.beginPessimistic();
+            await conn.begin();
             await this.lockScope(conn, scope);
             let total = 0;
             for (const table of ["file_history_boundary_file", "file_history_boundary", "file_history_reaped_entry", "file_history_version", "file_history_tracked", "file_history_scope"]) {
@@ -606,13 +608,13 @@ export class SqlFileHistoryStore {
                 return { ok: true };
             const conn = await this.db.connect();
             try {
-                await conn.beginPessimistic();
+                await conn.begin();
                 await this.lockScope(conn, fromScope, toScope);
                 if (!(await this.scopeEmpty(conn, toScope, true))) {
                     await conn.rollback();
                     return { ok: false, error: { code: "conflict", message: `adoptScope target "${toScope}" already has history of its own — adoption is legal only onto an EMPTY scope (the fork/resume boundary before the new session's first turn)` } };
                 }
-                if (await this.scopeEmpty(conn, fromScope)) {
+                if (await this.scopeEmpty(conn, fromScope, true)) {
                     await this.copyReapedEntries(conn, fromScope, toScope);
                     await conn.commit();
                     return { ok: true };
@@ -645,14 +647,15 @@ export class SqlFileHistoryStore {
         const b = await exec.query(this.q(`SELECT 1 FROM file_history_boundary WHERE scope = ? LIMIT 1${suffix}`, `SELECT 1 FROM file_history_boundary WHERE scope = $1 LIMIT 1${suffix}`), [scope]);
         return !b.rows[0];
     }
-    async exportOf(exec, scope) {
-        const tracked = await this.loadTracked(exec, scope);
-        const versions = await this.loadVersions(exec, scope);
-        const headers = await exec.query(this.q("SELECT entry_id FROM file_history_boundary WHERE scope = ?", "SELECT entry_id FROM file_history_boundary WHERE scope = $1"), [scope]);
+    async exportOf(exec, scope, forUpdate = false) {
+        const suffix = forUpdate ? " FOR UPDATE" : "";
+        const tracked = await this.loadTracked(exec, scope, forUpdate);
+        const versions = await this.loadVersions(exec, scope, forUpdate);
+        const headers = await exec.query(this.q(`SELECT entry_id FROM file_history_boundary WHERE scope = ?${suffix}`, `SELECT entry_id FROM file_history_boundary WHERE scope = $1${suffix}`), [scope]);
         if (tracked.length === 0 && headers.rows.length === 0)
             return null;
         await this.duringExportGraph(scope);
-        const files = await exec.query(this.q("SELECT entry_id, key_hash, version FROM file_history_boundary_file WHERE scope = ?", "SELECT entry_id, key_hash, version FROM file_history_boundary_file WHERE scope = $1"), [scope]);
+        const files = await exec.query(this.q(`SELECT entry_id, key_hash, version FROM file_history_boundary_file WHERE scope = ?${suffix}`, `SELECT entry_id, key_hash, version FROM file_history_boundary_file WHERE scope = $1${suffix}`), [scope]);
         const keyOfHash = new Map(tracked.map((t) => [t.keyHash, t.trackKey]));
         const byEntry = new Map();
         for (const row of files.rows) {
@@ -688,9 +691,9 @@ export class SqlFileHistoryStore {
     async exportHistory(scope) {
         const conn = await this.db.connect();
         try {
-            await conn.beginPessimistic();
+            await conn.begin();
             await this.lockScope(conn, scope);
-            const out = await this.exportOf(conn, scope);
+            const out = await this.exportOf(conn, scope, true);
             await conn.commit();
             return out;
         }
@@ -743,10 +746,10 @@ export class SqlFileHistoryStore {
             }
             const conn = await this.db.connect();
             try {
-                await conn.beginPessimistic();
+                await conn.begin();
                 await this.lockScope(conn, scope);
                 if (!(await this.scopeEmpty(conn, scope, true))) {
-                    const now = await this.exportOf(conn, scope);
+                    const now = await this.exportOf(conn, scope, true);
                     if (now !== null && fileHistoryExportDigest(now) === fileHistoryExportDigest(data)) {
                         await conn.commit();
                         return { ok: true };

package/dist/plugins/image-bake-store-sql.js

@@ -139,8 +139,8 @@ export class SqlImageBake {
         let inserted = false;
         try {
             if (this.db.dialect === "tidb") {
-                await conn.beginPessimistic();
-                await conn.query("INSERT IGNORE INTO image_bake_admit (pool) VALUES (?)", [this.poolName]);
+                await conn.begin();
+                await conn.query("INSERT INTO image_bake_admit (pool) VALUES (?) ON DUPLICATE KEY UPDATE pool = pool", [this.poolName]);
                 await conn.query("SELECT pool FROM image_bake_admit WHERE pool = ? FOR UPDATE", [this.poolName]);
                 const busy = await conn.query("SELECT 1 FROM image_bake WHERE status IN ('queued','running') AND dry_run = 0 LIMIT 1 FOR UPDATE");
                 if (busy.rows.length === 0) {

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

@@ -36,8 +36,11 @@
  *  - reap 候删 = 事务外粗筛 + 事务内**逐盒锁定重验**(当前读 newest):窗内新到的消息救活盒,
  *    绝不连带删信;盒行已被并发 drop = 跳过不计。
  *  - append 的 ensure 与 FOR UPDATE 之间被并发 drop 提交 = 同事务内重建一次(语义 = drop 后重建,
- *    seq 从 1)。键长 > 190 字节写入即拒(fail-loud)——TiDB `INSERT IGNORE` 会把超长键**静默截断**,
- *    截断键与全长查询参数字节比对恒 miss(分配读空行崩/隔离键错位)。
+ *    seq 从 1)。建盒动词 = 形 A(S-127)`ON DUPLICATE KEY UPDATE <pk> = <pk>`:重复键取 X 锁,与随后的
+ *    `FOR UPDATE` **同锁模式**(`INSERT IGNORE` 取 S 再升 X = InnoDB 上的并发死锁形,B-013)。
+ *  - 键长 > 190 字节写入即拒(fail-loud):截断键与全长查询参数字节比对恒 miss(分配读空行崩/隔离键
+ *    错位)。守卫在**语句之前**,与建行动词无关 —— 换成 ON DUPLICATE 之后超长键由引擎直接报错(严格
+ *    模式下 IGNORE 会把它降级成静默截断),方向=更响亮,守卫依旧是第一道。
  */
 import type { Pool as MySqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";

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

@@ -189,10 +189,10 @@ export class TiDBMailboxStore {
         const hopChain = encodeHopChain(msg.hopChain);
         const peerMeta = encodePeerMeta(msg.peerMeta);
         return this.tx(async (c) => {
-            await c.query(`INSERT IGNORE INTO ${MAILBOX_TABLE} (scope_key, handle, scope, next_seq) VALUES (?, ?, ?, 1)`, [scope, handle, scope]);
+            await c.query(`INSERT INTO ${MAILBOX_TABLE} (scope_key, handle, scope, next_seq) VALUES (?, ?, ?, 1) ON DUPLICATE KEY UPDATE scope_key = scope_key`, [scope, handle, scope]);
             let [rows] = (await c.query(`SELECT next_seq FROM ${MAILBOX_TABLE} WHERE scope_key = ? AND handle = ? FOR UPDATE`, [scope, handle]));
             if (rows.length === 0) {
-                await c.query(`INSERT IGNORE INTO ${MAILBOX_TABLE} (scope_key, handle, scope, next_seq) VALUES (?, ?, ?, 1)`, [scope, handle, scope]);
+                await c.query(`INSERT INTO ${MAILBOX_TABLE} (scope_key, handle, scope, next_seq) VALUES (?, ?, ?, 1) ON DUPLICATE KEY UPDATE scope_key = scope_key`, [scope, handle, scope]);
                 [rows] = (await c.query(`SELECT next_seq FROM ${MAILBOX_TABLE} WHERE scope_key = ? AND handle = ? FOR UPDATE`, [scope, handle]));
             }
             const seq = Number(rows[0].next_seq);

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

@@ -1,4 +1,4 @@
-import { FilePermissionRuleStoreProvider, type RuleApprovalRecord, type RuleApprovalRecordStore, type RuleScope, type StaleRuleApprovalRecord } from "@sema-agent/core";
+import { FileDurableRulePartitionProvider, type RuleApprovalRecord, type RuleApprovalRecordStore, type RuleScope, type StaleRuleApprovalRecord } from "@sema-agent/core";
 import { type RuleImportTicket, type RuleTicketPurpose, type RuleTicketReclaimResult, type RuleTicketRedeemResult, type RuleTicketSnapshot } from "./permission-rule-store-sql.js";
 import type { PermissionRuleStoreBundle } from "../rules-consent.js";
 /**
@@ -84,9 +84,9 @@ export declare class FileRuleImportTicketStore {
      *  那一条:过期只挡开始一次兑付,不挡做完一次已经开始的)。抢到之后**换一代认领**。 */
     reclaim(ticketId: string, principal: string, purpose: RuleTicketPurpose, minClaimAgeMs: number): Promise<RuleTicketReclaimResult>;
 }
-/** local 车道的三面束 + 生命周期。`dispose()` 释放 core File provider 的写锁(见 {@link createFilePermissionRuleStores})。 */
+/** local 车道的三面束 + 生命周期。`dispose()` 释放 core File durable 分区 provider 的写锁(见 {@link createFilePermissionRuleStores})。 */
 export interface FilePermissionRuleStores extends PermissionRuleStoreBundle {
-    provider: FilePermissionRuleStoreProvider;
+    durable: FileDurableRulePartitionProvider;
     approvals: FileRuleApprovalRecordStore;
     tickets: FileRuleImportTicketStore;
     dispose(): void;
@@ -94,7 +94,7 @@ export interface FilePermissionRuleStores extends PermissionRuleStoreBundle {
 /**
  * 装配 local 三面束。
  *
- * 🔴 `provider` 必须是**单例**(F1):core 的 `FilePermissionRuleStoreProvider` 在第一次取写面时对规则
+ * 🔴 `durable` 必须是**单例**(F1):core 的 `FileDurableRulePartitionProvider` 在第一次取写面时对规则
  * 目录取一把进程级写锁,每次 `new` 一个就是第二个持有者 —— 而它对第二个持有者是**响亮拒绝**,不是
  * 排队。所以束在 `LocalBackend` 上按字段持有,`LocalBackend.close()` 调 `dispose()` 释放
  * (不释放 ⇒ 一次优雅重启会被自己上一条命留下的锁挡在门外,与数据根 `root/LOCK` 同一个病)。

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

@@ -2,7 +2,7 @@ import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 import { readdirSync } from "node:fs";
 import { performance } from "node:perf_hooks";
-import { FilePermissionRuleStoreProvider, AppendLog, ensureDir, readJsonlRecords, } from "@sema-agent/core";
+import { FileDurableRulePartitionProvider, AppendLog, ensureDir, readJsonlRecords, } from "@sema-agent/core";
 import { z } from "zod";
 import { buildRulePayloadHash } from "./permission-rule-store-sql.js";
 import { EDITED_RULE_BREADTH_WARNING_CODES, RULE_APPROVAL_RECORD_SCHEMA, UNCOVERED_SEGMENT_REASONS } from "../permission-rule-vocab.js";
@@ -341,18 +341,18 @@ export class FileRuleImportTicketStore {
 export function createFilePermissionRuleStores(root, opts) {
     const dir = join(root, "permission-rules");
     ensureDir(dir);
-    const provider = opts?.onError ? new FilePermissionRuleStoreProvider(dir, opts.onError) : new FilePermissionRuleStoreProvider(dir);
+    const durable = opts?.onError ? new FileDurableRulePartitionProvider(dir, opts.onError) : new FileDurableRulePartitionProvider(dir);
     const approvals = new FileRuleApprovalRecordStore(dir, opts?.onError);
     const tickets = new FileRuleImportTicketStore(dir, opts?.now, opts?.onError, opts?.monotonic);
     return {
-        provider,
+        durable,
         approvals,
         tickets,
         countBuckets: async () => readdirSync(dir).filter((n) => n === "local-owner.json" || /^[0-9a-f]{64}\.json$/.test(n)).length,
         dispose: () => {
             approvals.close();
             tickets.close();
-            provider.dispose();
+            durable.dispose();
         },
     };
 }

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

@@ -15,12 +15,14 @@
  *
  * ── 方言差异台账(显式,永不藏进抽象;A12 判据)───────────────────────────────────────────────────
  *   - `?` 占位符 vs `$n`;
- *   - 幂等插入:`INSERT IGNORE` vs `ON CONFLICT (…) DO NOTHING`;
+ *   - 幂等建行(哨兵形 A,S-127):`ON DUPLICATE KEY UPDATE <pk> = <pk>` vs `ON CONFLICT (…) DO NOTHING`
+ *     —— MySQL 侧刻意**不用** `INSERT IGNORE`:重复键的 IGNORE 取 S 锁,与随后的 `FOR UPDATE` 之间是
+ *     S→X 升级,InnoDB 上两并发事务互等即 ER_LOCK_DEADLOCK(B-013);ON DUPLICATE 的重复键取的就是 X;
  *   - 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` 会静默吞掉列/索引差异)。
@@ -122,8 +124,10 @@ export declare class SqlRetentionLaneStore implements RetentionLaneStore {
      * **本 tick 零写静默跳过**。
      *
      * 事务三步,一步不能省:
-     *  ① `INSERT IGNORE`(PG:`ON CONFLICT DO NOTHING`)一条 `expires_at_ms = 0` 的**哨兵行** —— 它永远
-     *     不会改写一条既存租约(两方言的这两个动词都只在缺行时写);
+     *  ① 幂等建一条 `expires_at_ms = 0` 的**哨兵行**(形 A,S-127:MySQL `ON DUPLICATE KEY UPDATE
+     *     singleton = singleton` / PG `ON CONFLICT DO NOTHING`)—— 它永远不会改写一条既存租约(两方言的这
+     *     两个动词都只在缺行时写),且重复键取的是 **X** 锁,与 ② 的 `FOR UPDATE` 同锁模式(B-013:
+     *     `INSERT IGNORE` 在这里取 S 再升 X,InnoDB 上两副本抢租互等直接死锁);
      *  ② `SELECT … FOR UPDATE` —— 行现在必定存在,锁真的拿得到;
      *  ③ 判 + `UPDATE`,同事务提交。
      *
@@ -170,7 +174,7 @@ export declare class SqlRetentionLaneStore implements RetentionLaneStore {
      * (车1 交接件②,逐字)。
      *
      * 🔴 为什么删行是**拆锁**而不是"解除":`retention_hold` 的行同时是**域级互斥哨兵** —— 车1 的三条破坏性
-     * 事务首步就是锁读这一行(`INSERT IGNORE` 补哨兵 → `SELECT … FOR UPDATE`),而 `FOR UPDATE`
+     * 事务首步就是锁读这一行(ON DUPLICATE 补哨兵 → `SELECT … FOR UPDATE`),而 `FOR UPDATE`
      * **锁不住一条不存在的行**(TiDB 无 gap lock;PG READ COMMITTED 同病)。删掉行 = 下一个 PUT 与一条
      * 在飞的删除事务又可以同时读到"没有 hold",于是 operator 拿到成功回执之后数据仍被删 —— 那正是 §5 F2
      * 要消灭的那件事。upsert 让两者抢**同一把行锁**,「PUT 提交完成 ⇒ 其后每个破坏性事务的首读必见

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

@@ -14,7 +14,7 @@ export class SqlRetentionLaneStore {
         const conn = await this.db.connect();
         try {
             await conn.begin();
-            await conn.query(this.q(`INSERT IGNORE INTO ${RETENTION_LEASE_TABLE} (singleton, holder, fencing_token, expires_at_ms) VALUES ('x','',0,0)`, `INSERT INTO ${RETENTION_LEASE_TABLE} (singleton, holder, fencing_token, expires_at_ms) VALUES ('x','',0,0) ON CONFLICT (singleton) DO NOTHING`));
+            await conn.query(this.q(`INSERT INTO ${RETENTION_LEASE_TABLE} (singleton, holder, fencing_token, expires_at_ms) VALUES ('x','',0,0) ON DUPLICATE KEY UPDATE singleton = singleton`, `INSERT INTO ${RETENTION_LEASE_TABLE} (singleton, holder, fencing_token, expires_at_ms) VALUES ('x','',0,0) ON CONFLICT (singleton) DO NOTHING`));
             const { rows } = await conn.query(this.q(`SELECT holder, fencing_token, expires_at_ms FROM ${RETENTION_LEASE_TABLE} WHERE singleton = 'x' FOR UPDATE`, `SELECT holder, fencing_token, expires_at_ms FROM ${RETENTION_LEASE_TABLE} WHERE singleton = 'x' FOR UPDATE`));
             const cur = rows[0];
             const curHolder = String(cur?.holder ?? "");

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

@@ -28,14 +28,15 @@
  * ── 方言差异台账(显式,永不藏进抽象;A12 判据)───────────────────────────────────────────────────
  *   - `?` 占位符 vs `$n`;多值集合 MySQL 用 `IN (?,?,…)`、PG 用 `= ANY($n::text[])`(先例:
  *     workflow-run-store-sql 的 reap)
- *   - 幂等插入:`INSERT IGNORE` vs `ON CONFLICT (…) DO NOTHING`
+ *   - 幂等建行:哨兵形(形 A,S-127)`ON DUPLICATE KEY UPDATE <pk> = <pk>` vs `ON CONFLICT (…) DO NOTHING`
+ *     —— 随后有同行 `FOR UPDATE` 的建行**必须**用 ON DUPLICATE(重复键取 X,同锁模式);墓碑那种
+ *     「只读 affected 不加锁读」的写点(形 B)才保留 `INSERT IGNORE`
  *   - 级联 DELETE 的 JOIN 形:`DELETE te FROM a te JOIN b …` vs `DELETE FROM a te USING b …`
  *   - null-safe 比较:`<=>` vs `IS NOT DISTINCT FROM`(及其**占位符数量**差:`?` 不可复用)
  *   - 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 同姿势)。
  *
@@ -189,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」靠它自证)。
      */
@@ -213,8 +207,10 @@ export declare class SqlRetentionStore implements ManagedRetentionCapability {
      * 事务**首步**:拿本域的互斥行锁,并读出「这个域是不是冻结中」(§5 F2 承重)。
      *
      * 两步,缺一不可:
-     *  ① `INSERT IGNORE`(PG:`ON CONFLICT DO NOTHING`)一条 `held = 0` 的**哨兵行** —— 它永远不会改写
-     *     一条既存的 hold(两方言的这两个动词都只在缺行时写),只保证**接下来那把行锁有东西可锁**;
+     *  ① 幂等建一条 `held = 0` 的**哨兵行**(形 A,S-127:MySQL `ON DUPLICATE KEY UPDATE domain = domain` /
+     *     PG `ON CONFLICT DO NOTHING`)—— 它永远不会改写一条既存的 hold(两方言的这两个动词都只在缺行时
+     *     写),只保证**接下来那把行锁有东西可锁**;重复键取的是 **X** 锁,与 ② 的 `FOR UPDATE` 同锁模式
+     *     (`INSERT IGNORE` 在这里取 S 再升 X = InnoDB 上两个并发 sweep 互等的死锁形,B-013);
      *  ② `SELECT held … FOR UPDATE` —— 现在这行必定存在,于是锁真的拿到了。
      *
      * 🔴 为什么必须先造行(codex 交叉复审 R1-[high],验真后改):`FOR UPDATE` 锁不住缺席行(TiDB 无 gap

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

@@ -38,7 +38,7 @@ export const TIDB_RETENTION_STATEMENTS = [
      -- 而 SELECT … FOR UPDATE **锁不住一条不存在的行**(TiDB 无 gap lock;PG 的 READ COMMITTED 同样
      -- 不锁缺席行)。presence 形下两边都读到「没有 hold」是完全可能的,于是 operator 拿到成功回执之后
      -- 数据仍被删 —— 那正是 F2 要消灭的那件事,只是换了个位置复发。
-     -- ⇒ 行**恒存在**(破坏性事务首步 INSERT IGNORE 一条 held=0 的哨兵),冻结与否写在这一列上。
+     -- ⇒ 行**恒存在**(破坏性事务首步幂等建一条 held=0 的哨兵),冻结与否写在这一列上。
      -- 于是 hold 的放置(同一 PK 的 upsert)与三只破坏性事务抢的是**同一把行锁**,串行化由引擎给出:
      -- PUT 提交完成 ⇒ 其后每一个破坏性事务的首读必见 held=1。放置/解除都必须走这一列(车2 交接件)。
      held         TINYINT(1)   NOT NULL DEFAULT 0,
@@ -186,7 +186,7 @@ export class SqlRetentionStore {
     }
     async holdInForce(conn, domain) {
         const key = domain;
-        await conn.query(this.q(`INSERT IGNORE INTO ${RETENTION_HOLD_TABLE} (domain, held, placed_by, placed_at_ms, note) VALUES (?,0,NULL,NULL,NULL)`, `INSERT INTO ${RETENTION_HOLD_TABLE} (domain, held, placed_by, placed_at_ms, note) VALUES ($1,0,NULL,NULL,NULL) ON CONFLICT (domain) DO NOTHING`), [key]);
+        await conn.query(this.q(`INSERT INTO ${RETENTION_HOLD_TABLE} (domain, held, placed_by, placed_at_ms, note) VALUES (?,0,NULL,NULL,NULL) ON DUPLICATE KEY UPDATE domain = domain`, `INSERT INTO ${RETENTION_HOLD_TABLE} (domain, held, placed_by, placed_at_ms, note) VALUES ($1,0,NULL,NULL,NULL) ON CONFLICT (domain) DO NOTHING`), [key]);
         const { rows } = await conn.query(this.q(`SELECT held FROM ${RETENTION_HOLD_TABLE} WHERE domain = ? FOR UPDATE`, `SELECT held FROM ${RETENTION_HOLD_TABLE} WHERE domain = $1 FOR UPDATE`), [key]);
         return Number(rows[0]?.held ?? 0) === 1;
     }
@@ -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. */