@sema-agent/server 7.12.0 → 7.13.0

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

@@ -190,7 +190,12 @@ export const TIDB_PERMISSION_RULE_STATEMENTS = [
     created_at_ms BIGINT NOT NULL,
     updated_at_ms BIGINT NOT NULL,
     PRIMARY KEY (record_id),
-    KEY idx_permission_rule_approval_owner (owner_key)
+    KEY idx_permission_rule_approval_owner (owner_key),
+    -- 保留期腿的**支撑索引**(A-010.17 / codex R2 [high])。这张表按设计**永久**留着 approved/redeemed
+    -- 的审计事实,所以它只增不减 ⇒ 一条没有索引的 WHERE state='pending' AND created_at_ms < ? 谓词
+    -- 是一次随审计史无限增长的全表扫,而且每 tick 一次。(state, created_at_ms) 复合序把清扫收敛成
+    -- 一次窄区间扫:pending 段本来就短命,超期的那几行紧挨着。
+    KEY idx_permission_rule_approval_sweep (state, created_at_ms)
   ) COLLATE utf8mb4_bin`,
     `CREATE TABLE IF NOT EXISTS ${PERMISSION_RULE_TICKET_TABLE} (
     ticket_id VARCHAR(190) NOT NULL,
@@ -209,7 +214,9 @@ export const TIDB_PERMISSION_RULE_STATEMENTS = [
     consumed_at_ms BIGINT NULL,
     created_at_ms BIGINT NOT NULL,
     PRIMARY KEY (ticket_id),
-    KEY idx_permission_rule_ticket_owner (owner_key)
+    KEY idx_permission_rule_ticket_owner (owner_key),
+    -- 保留期腿的支撑索引(同上):WHERE expires_at_ms <= ? 是每 tick 一次的区间扫。
+    KEY idx_permission_rule_ticket_expires (expires_at_ms)
   ) COLLATE utf8mb4_bin`,
 ];
 /** {@link TIDB_PERMISSION_RULE_STATEMENTS} 的遍历壳(生产路径走 `tidb-pool.ts` 中央 `ensureSchema`;
@@ -255,6 +262,10 @@ export async function ensurePgPermissionRuleSchema(q) {
     PRIMARY KEY (record_id)
   )`);
     await q(`CREATE INDEX IF NOT EXISTS idx_permission_rule_approval_owner ON ${PERMISSION_RULE_APPROVAL_TABLE} (owner_key)`);
+    // 保留期腿的支撑索引(MySQL 孪生的行内注写了理由:这张表按设计永久留审计事实,无索引的清扫谓词
+    // 是一次随史增长的全表扫)。PG 侧是独立 CREATE INDEX —— 存量库上 `IF NOT EXISTS` 会**真的补建**,
+    // 与 MySQL 侧「索引写在 CREATE TABLE 里、存量表拿不到」的不对称如实登记在 reapExpired 的注里。
+    await q(`CREATE INDEX IF NOT EXISTS idx_permission_rule_approval_sweep ON ${PERMISSION_RULE_APPROVAL_TABLE} (state, created_at_ms)`);
     await q(`CREATE TABLE IF NOT EXISTS ${PERMISSION_RULE_TICKET_TABLE} (
     ticket_id VARCHAR(190) COLLATE "C" NOT NULL,
     owner_key VARCHAR(190) COLLATE "C" NOT NULL,
@@ -268,6 +279,7 @@ export async function ensurePgPermissionRuleSchema(q) {
     PRIMARY KEY (ticket_id)
   )`);
     await q(`CREATE INDEX IF NOT EXISTS idx_permission_rule_ticket_owner ON ${PERMISSION_RULE_TICKET_TABLE} (owner_key)`);
+    await q(`CREATE INDEX IF NOT EXISTS idx_permission_rule_ticket_expires ON ${PERMISSION_RULE_TICKET_TABLE} (expires_at_ms)`);
 }
 // ─────────────────────────────────────────────────────────────────────────────────────────────────
 // 纯函数(桶键 / 摘要 / delta 折叠)
@@ -807,11 +819,57 @@ export class SqlRuleImportTicketStore {
         };
     }
 }
+/**
+ * 孤儿 pending 审批记录的保留期(A-010.17)。
+ *
+ * 判据是「**可证已死**」,不是一个拍脑袋的时长:一条 pending 记录只能经 `redeemRuleTicket` 走活,
+ * 而兑付要么发生在铸它的**那一次请求内**(`persistCardRule` 的 prepare→confirm→redeem 三步同请求),
+ * 要么要拿一张导入票 —— 而票自铸起最多活 {@link RULE_IMPORT_TICKET_TTL_MS}(10 分钟,`consume` 的
+ * `expires_at_ms > now` 是硬条件)。所以创建时刻早于「now − 票 TTL」的 pending 记录**再也不可能**
+ * 被兑付。24 小时是在这条上界之上再压两个数量级的余量,留给运维「昨天那次导入怎么没成」的排查窗。
+ *
+ * 🔴 **只收 pending**。`approved` / `redeemed` 是一次真人同意的**审计事实**(与 `discardPendingRecord`
+ * 的 `WHERE state = 'pending'` 同一条硬约束,也与收编把这张表判成 D2「史实不改写」同源)——
+ * 保留期策略动不到它们,本腿一行都不碰。
+ */
+export const RULE_PENDING_APPROVAL_RETENTION_MS = 24 * 60 * 60_000;
+/**
+ * 保留期腿**每轮**最多删多少行(codex R2 [high])。
+ *
+ * 为什么必须有界:`permission_rule_approval` 按设计**永久**留 approved/redeemed 的审计事实(收编把它
+ * 判成 D2「史实不改写」,`discardPendingRecord` 的 `WHERE state='pending'` 也是同一条硬约束)——
+ * 也就是说这张表**只增不减**。一条无界 DELETE 在首次开清扫、或一次长期没跑的部署上,会在一个事务里
+ * 处理整个积压。500 的取值:一轮的最坏工作量钉在「几百行删除」这个数量级,而常态每轮的真实行数是个位数
+ * (一次 prepare 留一行);积压按轮渐进清空,每轮都是完整语义,绝不留半干净状态。
+ *
+ * ⚠️ 两方言的**索引到货方式不对称**,如实登记:PG 侧是独立的 `CREATE INDEX IF NOT EXISTS`,存量库
+ * 下次 `ensureSchema` 就补建;MySQL 侧索引写在 `CREATE TABLE` 里,而本仓 schema 口径是「启动 DDL 是唯一
+ * 真源、不发 ALTER」⇒ **存量表拿不到这两个索引**,要靠一次删库重建(与 7.8.0 / 7.10.0 两次 BREAKING 窗
+ * 同口径)。在那之前,MySQL 存量库上这条腿仍是全表扫 —— 但每轮 500 行的上界让它的**单次**代价仍然有界。
+ */
+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),
         approvals: new SqlRuleApprovalRecordStore(db, now),
         tickets: new SqlRuleImportTicketStore(db, now),
+        reapExpired: async (nowMs) => {
+            // 两条 DELETE **不包事务**:它们互相独立、各自幂等,一条失败不该把另一条已删的行回滚回来
+            // (维护腿的既有姿势 —— 邻居 reaper 腿全是独立语句)。
+            //
+            // 🔴 **每 tick 有界**(codex 对抗复审 R2 [high],验真后修):第一版是两条**无界** DELETE。
+            // 首次开清扫(或一次长时间没跑的部署)会在**一个事务**里删掉整个积压 —— 一条能跑很久、锁很多行、
+            // 把 binlog/WAL 顶起来的语句;而调用点当时又没有重入守卫,一旦耗时越过 tick 间隔,下一轮就叠上来。
+            // 收成每轮 {@link RULE_REAP_BATCH} 行:积压按轮**渐进**清空(每轮都是完整语义,不留半干净状态),
+            // 单条语句的最坏时长与库大小脱钩。调用侧另配了 in-flight 守卫(`boot/reapers.ts`)。
+            const deadTickets = await db.query(q(`DELETE FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE expires_at_ms <= ? LIMIT ${RULE_REAP_BATCH}`, 
+            // PG 的 DELETE 没有 LIMIT ⇒ 用 ctid 子查询限行(PG 侧的标准写法;`ctid` 是物理行号,
+            // 子查询里带 LIMIT 才是被支持的那一形)。两方言的**语义**相同:本轮最多删这么多行。
+            `DELETE FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE ctid IN (SELECT ctid FROM ${PERMISSION_RULE_TICKET_TABLE} WHERE expires_at_ms <= $1 LIMIT ${RULE_REAP_BATCH})`), [nowMs]);
+            const orphanPending = await db.query(q(`DELETE FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE state = 'pending' AND created_at_ms < ? LIMIT ${RULE_REAP_BATCH}`, `DELETE FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE ctid IN (SELECT ctid FROM ${PERMISSION_RULE_APPROVAL_TABLE} WHERE state = 'pending' AND created_at_ms < $1 LIMIT ${RULE_REAP_BATCH})`), [nowMs - RULE_PENDING_APPROVAL_RETENTION_MS]);
+            return deadTickets.affected + orphanPending.affected;
+        },
         // 两个方言逐字同形(`COUNT(*)` 无方言差),所以刻意**不**走 `q(tidb, pg)` 的双串姿势 —— 那会造出
         // 两份可以各自漂的同一句 SQL。参数空数组:本语句没有绑定位。
         countBuckets: async () => {

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

@@ -154,10 +154,15 @@ export declare class SqlSharedMemoryStore implements SharedMemoryStoreProvider {
         signal?: AbortSignal;
     }): Promise<SharedMemorySnapshot>;
     /**
-     * 盘状态 + 库登记,**一个事务一个快照**(轮2 F3 修)。方言差异显式:
-     *  · MySQL/TiDB 的默认隔离级别就是 REPEATABLE READ ⇒ 一个事务内的两条 SELECT 天然同快照;
-     *  · PG 默认 READ COMMITTED,**每条语句各自取快照** ⇒ 必须显式抬到 REPEATABLE READ,否则这个事务
-     *    对本条竞态毫无作用(那正是"包了事务就以为一致"最容易踩空的地方)。
+     * 盘状态 + 库登记,**一个事务一个快照**(轮2 F3 修)。
+     *
+     * 🔴 A-010.11(两臂不对称,验真后修):此前 PG 臂显式抬隔离级别、**MySQL 臂只靠服务端默认值**,
+     * 注里写的是「MySQL/TiDB 的默认隔离级别就是 REPEATABLE READ ⇒ 天然同快照」。那句话对**默认配置**
+     * 为真,但 `transaction_isolation` 是可设的服务端/会话变量:一台跑 READ COMMITTED 的实例(托管
+     * MySQL 的厂商默认、中间层代理、运维手改)会把「一个事务一个快照」悄悄降成「每条语句各自取快照」,
+     * 而本方法**不会报任何错**——它只是读到一对撕裂的 scope/store 行。「靠默认值成立」不是结构保证。
+     * 两臂现在都走 {@link SqlTxConn.beginRepeatableRead}(语句文本与**摆放位置**的方言分歧写在那里:
+     * MySQL 必须在 BEGIN **之前**发、PG 必须在 BEGIN **之后**发)。
      */
     private readBinding;
     private readerFor;
@@ -194,12 +199,21 @@ export declare class SqlSharedMemoryStore implements SharedMemoryStoreProvider {
      *    与插入之间穿过去,留下一行孤儿文档 —— 被删的内容在 id 复用时复活。
      */
     putDocument(record: SharedMemoryDocumentRecord): Promise<void>;
-    /** Remove one document. Scope-fenced like {@link putDocument} (a stale delete must not reach a
-     *  successor tenant's library). Returns whether a row was actually there. */
+    /**
+     * Remove one document. Scope-fenced like {@link putDocument} (a stale delete must not reach a
+     * successor tenant's library). Returns whether a row was actually there.
+     *
+     * 🔴 A-010.14(验真后修):此前围栏是**两条独立语句** —— `assertOwnedBy()` 先查一次登记表,然后另
+     * 起一条 DELETE。它自称与 `putDocument` 对齐,但 `putDocument` 的检查与写是**同事务同行锁**
+     * (`FOR UPDATE`),而这里的两条语句之间有一道真窗:登记检查通过之后、DELETE 发出之前,另一个 org
+     * 完成 `deleteStore` + `putStore` 的 id 复用,这条 DELETE 就落进**继任租户**的库里删掉他们的文档。
+     * 那正是 `putDocument` 的注里写明要挡住的那一形。现在逐字照它:同一事务、对登记行 `FOR UPDATE`、
+     * 拿到锁之后再删。
+     *
+     * 「未登记 ⇒ 响亮抛」与「登记了但没这条文档 ⇒ 回 false」两件事仍然分家(调用方据此分支),所以
+     * 不能收成一条 `DELETE … WHERE EXISTS(…)`:那样 `affected === 0` 会把两种结局压成同一个读数。
+     */
     deleteDocument(storeId: string, scopeKey: string, path: string): Promise<boolean>;
-    /** 属主围栏的共用断言(轮3 F1)。**不**覆盖同一个 org 内的"删了又建"代际重用——那不是跨租户面,
-     *  真要挡住需要一枚不可变的 generation token;这里如实说明边界,不假装它被覆盖了。 */
-    private assertOwnedBy;
     /**
      * De-register a store AND its documents, ATOMICALLY.
      *

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

@@ -215,17 +215,20 @@ export class SqlSharedMemoryStore {
         };
     }
     /**
-     * 盘状态 + 库登记,**一个事务一个快照**(轮2 F3 修)。方言差异显式:
-     *  · MySQL/TiDB 的默认隔离级别就是 REPEATABLE READ ⇒ 一个事务内的两条 SELECT 天然同快照;
-     *  · PG 默认 READ COMMITTED,**每条语句各自取快照** ⇒ 必须显式抬到 REPEATABLE READ,否则这个事务
-     *    对本条竞态毫无作用(那正是"包了事务就以为一致"最容易踩空的地方)。
+     * 盘状态 + 库登记,**一个事务一个快照**(轮2 F3 修)。
+     *
+     * 🔴 A-010.11(两臂不对称,验真后修):此前 PG 臂显式抬隔离级别、**MySQL 臂只靠服务端默认值**,
+     * 注里写的是「MySQL/TiDB 的默认隔离级别就是 REPEATABLE READ ⇒ 天然同快照」。那句话对**默认配置**
+     * 为真,但 `transaction_isolation` 是可设的服务端/会话变量:一台跑 READ COMMITTED 的实例(托管
+     * MySQL 的厂商默认、中间层代理、运维手改)会把「一个事务一个快照」悄悄降成「每条语句各自取快照」,
+     * 而本方法**不会报任何错**——它只是读到一对撕裂的 scope/store 行。「靠默认值成立」不是结构保证。
+     * 两臂现在都走 {@link SqlTxConn.beginRepeatableRead}(语句文本与**摆放位置**的方言分歧写在那里:
+     * MySQL 必须在 BEGIN **之前**发、PG 必须在 BEGIN **之后**发)。
      */
     async readBinding(scopes) {
         const conn = await this.db.connect();
         try {
-            await conn.begin();
-            if (this.db.dialect === "pg")
-                await conn.query("SET TRANSACTION ISOLATION LEVEL REPEATABLE READ");
+            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();
@@ -444,23 +447,57 @@ export class SqlSharedMemoryStore {
             throw new Error(`shared-memory store ${JSON.stringify(record.storeId)} is not registered under ${JSON.stringify(record.scopeKey)} — either it was never created, or the id has since been recycled by another org (call putStore() first; a stale retry must NOT land in the new tenant's library)`);
         }
     }
-    /** Remove one document. Scope-fenced like {@link putDocument} (a stale delete must not reach a
-     *  successor tenant's library). Returns whether a row was actually there. */
+    /**
+     * Remove one document. Scope-fenced like {@link putDocument} (a stale delete must not reach a
+     * successor tenant's library). Returns whether a row was actually there.
+     *
+     * 🔴 A-010.14(验真后修):此前围栏是**两条独立语句** —— `assertOwnedBy()` 先查一次登记表,然后另
+     * 起一条 DELETE。它自称与 `putDocument` 对齐,但 `putDocument` 的检查与写是**同事务同行锁**
+     * (`FOR UPDATE`),而这里的两条语句之间有一道真窗:登记检查通过之后、DELETE 发出之前,另一个 org
+     * 完成 `deleteStore` + `putStore` 的 id 复用,这条 DELETE 就落进**继任租户**的库里删掉他们的文档。
+     * 那正是 `putDocument` 的注里写明要挡住的那一形。现在逐字照它:同一事务、对登记行 `FOR UPDATE`、
+     * 拿到锁之后再删。
+     *
+     * 「未登记 ⇒ 响亮抛」与「登记了但没这条文档 ⇒ 回 false」两件事仍然分家(调用方据此分支),所以
+     * 不能收成一条 `DELETE … WHERE EXISTS(…)`:那样 `affected === 0` 会把两种结局压成同一个读数。
+     */
     async deleteDocument(storeId, scopeKey, path) {
-        await this.assertOwnedBy(storeId, scopeKey);
-        const res = await this.db.query(this.q(`DELETE FROM ${SHARED_MEMORY_ENTRY_TABLE} WHERE store_id = ? AND path = ?`, `DELETE FROM ${SHARED_MEMORY_ENTRY_TABLE} WHERE store_id = $1 AND path = $2`), [storeId, path]);
-        return res.affected > 0;
-    }
-    /** 属主围栏的共用断言(轮3 F1)。**不**覆盖同一个 org 内的"删了又建"代际重用——那不是跨租户面,
-     *  真要挡住需要一枚不可变的 generation token;这里如实说明边界,不假装它被覆盖了。 */
-    async assertOwnedBy(storeId, scopeKey) {
         assertStoreId(storeId);
         assertScopeKey(scopeKey);
-        const res = await this.db.query(this.q(`SELECT store_id FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = ? AND scope_key = ?`, `SELECT store_id FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = $1 AND scope_key = $2`), [storeId, scopeKey]);
-        if (res.rows.length === 0) {
+        let unregistered = false;
+        let deleted = false;
+        const conn = await this.db.connect();
+        try {
+            await conn.begin(); // 为什么不是 beginPessimistic:见本类头注的"事务与锁"段(与 putDocument 同判)
+            const registered = await conn.query(this.q(`SELECT store_id FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = ? AND scope_key = ? FOR UPDATE`, `SELECT store_id FROM ${SHARED_MEMORY_STORE_TABLE} WHERE store_id = $1 AND scope_key = $2 FOR UPDATE`), [storeId, scopeKey]);
+            if (registered.rows.length === 0) {
+                unregistered = true;
+                await conn.rollback();
+            }
+            else {
+                const res = await conn.query(this.q(`DELETE FROM ${SHARED_MEMORY_ENTRY_TABLE} WHERE store_id = ? AND path = ?`, `DELETE FROM ${SHARED_MEMORY_ENTRY_TABLE} WHERE store_id = $1 AND path = $2`), [storeId, path]);
+                deleted = res.affected > 0;
+                await conn.commit();
+            }
+        }
+        catch (err) {
+            await rollbackPreservingError(conn, err);
+            throw err;
+        }
+        finally {
+            conn.release();
+        }
+        if (unregistered) {
+            // 文案逐字同 assertOwnedBy(调用方/测试按它对表);围栏的**执行面**改了,拒绝的**说法**没改。
             throw new Error(`shared-memory store ${JSON.stringify(storeId)} is not registered under ${JSON.stringify(scopeKey)} — either it does not exist, or the id has since been recycled by another org`);
         }
+        return deleted;
     }
+    // 属主围栏的共用断言 `assertOwnedBy()` 曾住在这里(轮3 F1)。A-010.14 把它**唯一**的消费者
+    // (`deleteDocument`)改成「同事务 + FOR UPDATE」之后它就没有调用点了 —— 留着一个自带围栏语义却
+    // 无人调用的私有方法,下一个人会以为「围栏在这儿,照着调就行」,而它恰恰是被判定为不够强的那一版。
+    // 边界的如实说明随之搬进 `deleteDocument` / `putDocument`:两者**都不**覆盖同一个 org 内的
+    // "删了又建"代际重用 —— 那不是跨租户面,真要挡住需要一枚不可变的 generation token。
     /**
      * De-register a store AND its documents, ATOMICALLY.
      *

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

@@ -91,6 +91,25 @@ 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 (A-010.11).
+     *
+     * 🔴 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.
+     */
+    beginRepeatableRead(): Promise<void>;
     commit(): Promise<void>;
     rollback(): Promise<void>;
     release(): void;

package/dist/plugins/sql-driver.js

@@ -24,6 +24,12 @@ export function mysqlDriver(pool) {
                 beginPessimistic: async () => {
                     await c.query("BEGIN PESSIMISTIC");
                 },
+                // Scope-less `SET TRANSACTION …` = next-transaction only, so it goes BEFORE the BEGIN and
+                // leaves the pooled connection's session default untouched for whoever gets it next.
+                beginRepeatableRead: async () => {
+                    await c.query("SET TRANSACTION ISOLATION LEVEL REPEATABLE READ");
+                    await c.beginTransaction();
+                },
                 commit: () => c.commit(),
                 rollback: () => c.rollback(),
                 release: () => c.release(),
@@ -50,6 +56,12 @@ export function pgDriver(pool) {
                 beginPessimistic: async () => {
                     await c.query("BEGIN");
                 },
+                // PG takes it INSIDE the transaction (and only before its first query) — the mirror image of
+                // the MySQL arm above. Same verb, deliberately different placement.
+                beginRepeatableRead: async () => {
+                    await c.query("BEGIN");
+                    await c.query("SET TRANSACTION ISOLATION LEVEL REPEATABLE READ");
+                },
                 commit: async () => {
                     await c.query("COMMIT");
                 },

package/dist/plugins/store-backend.js

@@ -222,7 +222,30 @@ class LocalBackend {
         // adoptLocalDataRoot 到完成,或修 adoption.json」的出路),我们没有更好的话可说,包一层只会更差。
         // 包装只留给真正的 boot-lock 类失败(那句文案的适用条件)。
         try {
-            this.fileBackend = new FileStorageBackend({ root, ...(config.rewindSnapshotMaxMb !== undefined ? { snapshotBounds: { maxBytes: Math.round(config.rewindSnapshotMaxMb * 1024 * 1024) } } : {}) }); // REWIND_SNAPSHOT_MAX_MB
+            this.fileBackend = new FileStorageBackend({
+                root,
+                ...(config.rewindSnapshotMaxMb !== undefined ? { snapshotBounds: { maxBytes: Math.round(config.rewindSnapshotMaxMb * 1024 * 1024) } } : {}), // REWIND_SNAPSHOT_MAX_MB
+                // 🔴 腐读披露座(交接件④,与 `run-local.ts` 的同座同形、同 warn 名 `file_store_corrupt_read`)。
+                // core 对**读不出来的**持久文件是 documented fail-open —— 当作「缺席」继续跑(抛会让整条任务死,
+                // 也会自锁修复写)。这条 fail-open 是 core 的裁定,本仓不改它;但它**不许无声**(#157 安全轴纪律)。
+                // 此前 HTTP 服务的 local 车道**根本没接这个座**:同一份坏字节,run-local 上打一行、服务上一个字
+                // 都没有 —— 而服务形恰恰是没人盯着终端的那一个。
+                //
+                // ⚠️ 文案按脸分列后果、**不下统一结论**(run-local 那次 codex R2-medium 的教训一并吸收):一个座
+                // 覆盖 core 转发的三张脸,后果各不相同 —— 把「少了会话规则这一层」写成「整个任务无约束」会误导
+                // 事故定级,而且对另外两张脸根本不成立。共同事实只有一句:一次持久读被当成了缺席。
+                // ENOENT 不触发(那是真缺席,不是腐读)。
+                onCorruptRead: (info) => this.onWarn?.("file_store_corrupt_read", {
+                    path: info.path,
+                    reason: info.reason,
+                    ...(info.sessionId !== undefined ? { sessionId: info.sessionId } : {}),
+                    ...(info.principal !== undefined ? { principal: info.principal } : {}),
+                    note: "a durable read was treated as ABSENT because the bytes were unreadable (never a plain ENOENT). " +
+                        "Consequence depends on which store read it: session-policy = that run lost its SUBTRACTIVE session-rule " +
+                        "layer (deployment policy / hooks / shell gate still applied); session repo = a listing silently omitted " +
+                        "rows; file-snapshot = a snapshot or scope read as missing. Inspect the named path before deciding.",
+                }),
+            });
         }
         catch (e) {
             if (e instanceof AdoptionError)

package/dist/rules-consent.d.ts

@@ -1,4 +1,4 @@
-import { type ImportPreview, type ImportResult, type ImportedSettingsLayer, type PersistedAllowRule, type RemoveResult, type RuleScope } from "@sema-agent/core";
+import { type RuleOwner, type ImportPreview, type ImportResult, type ImportedSettingsLayer, type PersistedAllowRule, type RemoveResult, type RuleScope } from "@sema-agent/core";
 import type { PermissionRuleStoreProvider, RuleApprovalRecordStore } from "@sema-agent/core";
 import { type RuleImportTicket, type RuleTicketRedeemResult } from "./plugins/permission-rule-store-sql.js";
 /**
@@ -47,6 +47,16 @@ export interface PermissionRuleStoreBundle extends RuleConsentStores {
     /** #203 §3:库里已有几只规则桶(一 owner 一桶)。boot 期休眠行审计的**唯一**依赖;
      *  为什么数桶不数规则、以及读失败必须响亮,见 `boot/permission-rules-audit.ts` 与两个实现处的注。 */
     countBuckets(): Promise<number>;
+    /**
+     * A-010.17 保留期腿:清掉**可证已死**的导入票与孤儿 pending 审批记录,返回删掉的总行数。
+     * 谓词与「为什么不需要旋钮」逐字见 `plugins/permission-rule-store-sql.ts` 的同名成员。
+     *
+     * 🔴 **可选**,而缺席是**如实登记**过的:File 车道(`permission-rule-store-file.ts`)的审批/票两面是
+     * **追加日志**,删一行等于重写整个日志 —— 那是一次压实(compaction)设计,与 SQL 的一条 DELETE 不是
+     * 同一件事,不在本条射程内。缺席的实际后果有界:File 车道 = 单用户本地形,两只日志的增长由**一个人**
+     * 的导入次数封顶,不是多租户共享库那种无界增长。要做压实时在这里补实现,消费点(reaper)零改动。
+     */
+    reapExpired?(nowMs: number): Promise<number>;
 }
 /** 导入票的存活窗。人从「看到预览」到「按下确认」是一次交互,不是一段会话——十分钟宽到不会误伤,
  *  窄到一张泄漏的票不会常驻。运维旋钮暂不开(没有部署形要求它可调;要开时走 config.ts 的既有姿势)。 */
@@ -147,6 +157,20 @@ export interface PersistedRuleListing {
     rows: PersistedRuleWireRow[];
     rev: number;
 }
+/**
+ * 撤销面两口寻址的**桶**(#203 收官件,core 5.24.0 提货批 [3427])。
+ *
+ * 裸串 = principal 简写(既有调用方逐字不变);结构形 {@link RuleOwner} 多出 `{kind:"local-owner"}`
+ * —— 身份缺席的单机形自己那只桶。这不是 server 发明的第二种寻址:core 的
+ * `PermissionRuleStoreProvider.forLocalOwner()`(design/182 §4.5)一直就有这只桶,缺的是**撤销入口
+ * 叫不出它的名字** —— 我方 [3399]① 请托、core 5.24.0 把 `removePersistedRule` 的 `principal` 入参扩成
+ * `string | RuleOwner` 兑现(d.ts 那段注逐字写着「downstream request, 2026-08-10」)。
+ *
+ * 🔴 **绝不用哨兵串**表示身份缺席(core 的 `RuleOwner` 头注就是这条纪律的出处):`forPrincipal("")` /
+ * `forPrincipal("local-owner")` 都会让一个**编出来的名字**流进身份面,而身份面上编的名字与真名在下游
+ * 不可分。判别式联合是唯一诚实的形。
+ */
+export type RuleBucketRef = string | RuleOwner;
 export interface RuleConsentLane {
     /** 卡道兑付口:一次 ask 决议携规则确认 ⇒ prepare→confirm→redeem 一气呵成。 */
     persistCardRule(input: {
@@ -165,13 +189,15 @@ export interface RuleConsentLane {
     /** 导入道:原子消费票 → confirm → redeemRuleBatch。 */
     redeemImport(principal: string, ticket: string): Promise<RuleImportRedeemed>;
     /**
-     * 撤销面读半场:列出一位 principal 名下**活着**的规则(墓碑已折算)。
+     * 撤销面读半场:列出一只桶名下**活着**的规则(墓碑已折算)。
      *
      * 排序 = (scope, rule) 字典序,**确定性**:分页游标是 keyset 形,而 keyset 的全部前提就是「同一份
      * 数据每次以同一个顺序出现」。core 的 `list()` 不承诺顺序(SQL 形按写入顺序、File 形按文件内顺序),
      * 所以序在这里定,不在店里。
+     *
+     * 入参裸串 = principal 简写(既有调用方逐字不变);{@link RuleBucketRef} 的结构形另开 local-owner 桶。
      */
-    listRules(principal: string): Promise<PersistedRuleListing>;
+    listRules(bucket: RuleBucketRef): Promise<PersistedRuleListing>;
     /**
      * 撤销面写半场。**恒经 core `removePersistedRule`**(design/203 §2 裁定)——它产墓碑,而墓碑是
      * `screenRuleSyncState` 的筛子保证「别的副本不把这条规则回灌回来」的唯一凭据。直接删 SQL 行/文件行
@@ -180,9 +206,12 @@ export interface RuleConsentLane {
      * 返回值逐字是 core 的 `RemoveResult` 三态(removed / no-op / failed),**不塌**:
      * `removed.stillLive:true` 意思是「墓碑落了,但本次调用期间又落了一次新的批准,规则按 add-wins
      * 仍然活着」——那是一个**有名字的真结果**,不是异常,更不是「撤销完成」。
+     *
+     * `principal` 裸串 = principal 简写(既有调用方逐字不变);{@link RuleBucketRef} 的结构形让
+     * local-owner 桶**真可撤**(core 5.24.0 起 `removePersistedRule` 的入参 union 扩,#203 收官件)。
      */
     removeRule(input: {
-        principal: string;
+        principal: RuleBucketRef;
         rule: string;
         scope: RuleScope;
     }): Promise<RemoveResult>;

package/dist/rules-consent.js

@@ -87,6 +87,42 @@ export function parseRuleScope(text) {
     // (空前缀包含一切)——一条项目内规则就此悄悄升成全局规则(cc-import 那侧同判据,同一条 codex 发现)。
     return root === "" ? undefined : { kind: "project", root };
 }
+/**
+ * 桶引用 → 具体的规则店。
+ *
+ * 🔴 **穷举判别,未知形一律抛**(CLAUDE.md 词表闭集律 + codex 对抗复审 R3-[medium],验真后改)。
+ * 第一稿写的是 `kind === "principal" ? 甲 : 乙` 的二分:TS 那侧是穷举的,**运行期不是** —— 本车道是
+ * 一个**导出**的束,调用方可以是任何一层(HTTP 路由今天只递裸串,但这条口正是为了将来递结构形才开的)。
+ * 于是 `{kind:"principle"}`(拼错)或 `{}` 会静默落进 local-owner 那支 = 一次**跨桶读**;更坏的是
+ * 同一个坏值递给 core 的 `removePersistedRule` 时它按 `kind === "local-owner"` 反着判,落到
+ * `forPrincipal(undefined)`(空店)—— 列举和撤销**指向两只不同的桶**,而两边都不报错。
+ * 身份面上「不认识的形」只有一个正确答案:响亮拒。
+ *
+ * 🔴 local-owner 桶而 provider 没有 `forLocalOwner` ⇒ 同样**抛**,不静默回落到别的桶。回落到
+ * `forPrincipal(…)` 会把「读/删身份缺席桶」变成「读/删某个 principal 的桶」——那是一次跨桶的读或写,
+ * 是本车道最不该出的错。报文与 core 的 `removePersistedRule` 同支同措辞(那侧回 `failed` 带
+ * `forLocalOwner` 字样),两侧一起读日志时对得上。
+ */
+function storeForBucket(provider, ref) {
+    // 裸串 = principal 简写(core `removePersistedRule` 的同款归一,两侧对同一个输入判同一只桶)。
+    if (typeof ref === "string")
+        return provider.forPrincipal(ref);
+    // `ref.kind` 在类型上是闭集;`switch` 的 default 是**运行期**的那道门(不是死码)。
+    switch (ref.kind) {
+        case "principal":
+            return provider.forPrincipal(ref.principal);
+        case "local-owner":
+            if (provider.forLocalOwner === undefined) {
+                throw new Error("this provider has no local-owner bucket (forLocalOwner is not implemented) — a local-owner rule cannot be listed or removed through it");
+            }
+            return provider.forLocalOwner();
+        default: {
+            // core 给 `RuleOwner` 加员时这里是**编译**红(`never` 赋值失败),不是静默继承某一支。
+            const unknown = ref;
+            throw new Error(`unrecognised permission-rule bucket reference (${JSON.stringify(unknown)}) — refusing to guess which bucket it names`);
+        }
+    }
+}
 export function createRuleConsentLane(stores, opts) {
     const deps = { provider: stores.provider, approvals: stores.approvals };
     const ticketTtlMs = opts?.ticketTtlMs ?? RULE_IMPORT_TICKET_TTL_MS;
@@ -222,10 +258,10 @@ export function createRuleConsentLane(stores, opts) {
                 return await indeterminate(err instanceof Error ? err.message : String(err));
             }
         },
-        async listRules(principal) {
+        async listRules(bucket) {
             // `list()` 已经把墓碑折算掉(`applyTombstones`)⇒ 这里拿到的就是**活着**的规则,治理面看到的
             // 与引擎放行时看到的是同一份。空桶 = 空表 + rev 0,不是错误(「这个人没有规则」是合法状态)。
-            const stored = await stores.provider.forPrincipal(principal).list();
+            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 }));
             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 };
@@ -233,6 +269,11 @@ export function createRuleConsentLane(stores, opts) {
         async removeRule(input) {
             // 🔴 一行也不自己写:OCC 重试、墓碑铸造、`stillLive` 的读回全在 core 那条原语里,而它的语义
             // (add-wins、observed-remove、失败必须由读回确认「什么都没写」)是 core 的单一属主。
+            // 桶引用**原样**递下去(裸串走 core 的 principal 简写臂,结构形走 owner 臂)——我方不在这里
+            // 归一成 owner 对象:core 5.24.0 的 `removePersistedRule` 自己就做那次归一(`typeof === "string"`),
+            // 多归一一次等于把上游的简写语义抄一份到下游,抄件会漂。local-owner 而 provider 无 `forLocalOwner`
+            // 的那支也归 core:它回的是 `failed` + 报文含 `forLocalOwner`(C13 判据),比抛错更适合这条
+            // 三态返回的口。
             return await removePersistedRule({ rule: input.rule, scope: input.scope, principal: input.principal, provider: stores.provider });
         },
     };

package/dist/run-local.js

@@ -582,6 +582,11 @@ export async function runLocal(argv, deps = {}) {
      */
     const sharedRunnerDeps = createSharedRunnerDeps({
         config,
+        // 交接件⑤:commit 尾注署名座进**共享基座** ⇒ 主 runner 与 subRunner 同源。
+        // [931]① clay 拍:run-local = Sema 品牌本地形态,commit 尾注接 Sema 署名(core 1.300 缺省已翻转不署)。
+        // 修前它只写在下面主 runner 的差异键里 ⇒ **委派出去的子代提交不带署名**,而它提交进的是同一个仓、
+        // 代表的是同一个部署。那不是一次有理由的分歧(差异键注释块逐条列了理由,唯独没提它),是漏配。
+        hands: { commitCoAuthor: "Sema <noreply@vivi-ai.com>" },
         brain,
         pricing,
         tracer: createTracer(metrics),
@@ -601,8 +606,7 @@ export async function runLocal(argv, deps = {}) {
     const runnerDeps = {
         ...sharedRunnerDeps,
         // ── 以下为主 runner 的差异键(不在共享基座;逐个有因)──────────────────────────────────────
-        // [931]① clay 拍:run-local=Sema 品牌本地形态,commit 尾注接 Sema 署名(core 1.300 缺省已翻转不署)。
-        hands: { commitCoAuthor: "Sema <noreply@vivi-ai.com>" },
+        // (`hands` 已随共享基座展开 —— 交接件⑤;这里手写同名键会 override 展开、把 subRunner 重新甩开。)
         sessionStore,
         ...(memoryEngine ? { memoryBackend: memoryEngine.backend, memoryEngineDir: memoryEngine.root } : {}),
         checkpointStore: fileBackend.checkpointStore,

package/dist/runtime-governance.d.ts

@@ -93,6 +93,39 @@ export declare function compileCommandPolicy(rules: CommandRule[] | undefined):
  *  - `auto` / `undefined` → `{}` (no extra tightening; still subject to the deployment baseline + commandPolicy).
  */
 export declare function autonomyOverrides(autonomy: Autonomy | undefined): Partial<TaskSpec>;
+/**
+ * #220:**部署级**判据 —— 本部署的治理层自己是否把 shellGate 抬到 `"always"`。
+ *
+ * 用途 = 持久门(park 行)的出身归因。活卡腿判「这只 ask 是治理层产的」靠 ALS 标记表(见本文件
+ * `createGovernanceAskMarkingPolicy` / `createGovernanceShellGateMarkPolicy`),而 park 腿天然跨副本、
+ * 跨重启,进程内的表在那里结构上够不着;行上唯一的取证格是 core 写的
+ * `gate.riskDescriptor.shellGateDoctrine`。
+ *
+ * 🔴 **为什么单看行上那一格不够**:有效档 `"always"` **不止治理层一个产地** —— `resolve-spec` 的 SUP 路由
+ * 姿态(`supPostureOverrides`)在 governance **之后**叠,同样产 `"always"`(本文件 `manualModeShellGate`
+ * 合成段的注释里已如实记着这条时序)。只看行 ⇒ 一条 SUP 路由出来的门会被谎报成「运维治理层强制」,
+ * 而那恰是这个信号要回答的那个问题。所以归因取**合取**:行上是 `always` **∧** 本部署的治理层本来就
+ * 要求 `always`(后者成立时,治理层就是一个真成因,SUP 是否也抬过不改变这句话的真假)。
+ *
+ * 判据逐字对着两个产地(与 `applyRuntimeGovernance` 里 `overrides.shellGate` 的取值同源):
+ * `autonomyOverrides(autonomy).shellGate`(`AUTONOMY=ask`)与 `MANUAL_MODE_SHELL_GATE` 旋钮,取「有一个
+ * 是 always」。`commandPolicy` 不入判据:它产的是 `toolPolicy` 的 ask,不抬 shellGate 档,与本格无关。
+ *
+ * ⚠️ **已知残留(codex 对抗复审 2026-08-11 逮到,如实登记而不是掩盖)**:本判据读的是**当下**的
+ * config,而 `config.autonomy` 是**热改**的(`config-center/apply-effective.ts` 就地写 `config.autonomy`)。
+ * 于是失真是**双向**的,不是我原先写的「只往缺席方向」:
+ *  · 缺席向(常见):mint 之后运维把 `AUTONOMY=ask` 撤了 ⇒ 老 park 行归不出治理出身,少标一个;
+ *  · **在场向**(窄):一条**纯 SUP 路由**产的门(`ROUTER_ENABLED` 开 ∧ 路由判 supervisor ∧ 当时治理层
+ *    并不要求 always),之后运维把 autonomy 热改成 `ask`,那条老行会被标成治理出身 —— 五个前提要**同时**
+ *    成立,且该行仍未决。
+ * 根治要**在 mint 那一刻把出身写进行里**(core 的 `CheckpointGate` 属主面,不是本仓能单方面做的);
+ * 在那之前这一位的定位是**分诊提示**,不是裁决输入 —— 它不参与任何门/CAS/resume 判定,消费端也只拿它
+ * 渲染徽标。登记在此,不加特征化测试(把已知残留钉成契约是另一种病)。
+ */
+export declare function governanceMandatesShellGateAlways(governance: {
+    autonomy?: Autonomy;
+    manualModeShellGate?: "always" | "classify";
+}): boolean;
 /**
  * Apply the operator's runtime governance (autonomy + commandPolicy + manualModeShellGate) onto a base
  * `TaskSpec`, TIGHTEN-ONLY, in a SINGLE {@link tightenTaskSpec} call: commandPolicy compiles to a `toolPolicy`

package/dist/runtime-governance.js

@@ -219,6 +219,38 @@ export function autonomyOverrides(autonomy) {
             return {};
     }
 }
+/**
+ * #220:**部署级**判据 —— 本部署的治理层自己是否把 shellGate 抬到 `"always"`。
+ *
+ * 用途 = 持久门(park 行)的出身归因。活卡腿判「这只 ask 是治理层产的」靠 ALS 标记表(见本文件
+ * `createGovernanceAskMarkingPolicy` / `createGovernanceShellGateMarkPolicy`),而 park 腿天然跨副本、
+ * 跨重启,进程内的表在那里结构上够不着;行上唯一的取证格是 core 写的
+ * `gate.riskDescriptor.shellGateDoctrine`。
+ *
+ * 🔴 **为什么单看行上那一格不够**:有效档 `"always"` **不止治理层一个产地** —— `resolve-spec` 的 SUP 路由
+ * 姿态(`supPostureOverrides`)在 governance **之后**叠,同样产 `"always"`(本文件 `manualModeShellGate`
+ * 合成段的注释里已如实记着这条时序)。只看行 ⇒ 一条 SUP 路由出来的门会被谎报成「运维治理层强制」,
+ * 而那恰是这个信号要回答的那个问题。所以归因取**合取**:行上是 `always` **∧** 本部署的治理层本来就
+ * 要求 `always`(后者成立时,治理层就是一个真成因,SUP 是否也抬过不改变这句话的真假)。
+ *
+ * 判据逐字对着两个产地(与 `applyRuntimeGovernance` 里 `overrides.shellGate` 的取值同源):
+ * `autonomyOverrides(autonomy).shellGate`(`AUTONOMY=ask`)与 `MANUAL_MODE_SHELL_GATE` 旋钮,取「有一个
+ * 是 always」。`commandPolicy` 不入判据:它产的是 `toolPolicy` 的 ask,不抬 shellGate 档,与本格无关。
+ *
+ * ⚠️ **已知残留(codex 对抗复审 2026-08-11 逮到,如实登记而不是掩盖)**:本判据读的是**当下**的
+ * config,而 `config.autonomy` 是**热改**的(`config-center/apply-effective.ts` 就地写 `config.autonomy`)。
+ * 于是失真是**双向**的,不是我原先写的「只往缺席方向」:
+ *  · 缺席向(常见):mint 之后运维把 `AUTONOMY=ask` 撤了 ⇒ 老 park 行归不出治理出身,少标一个;
+ *  · **在场向**(窄):一条**纯 SUP 路由**产的门(`ROUTER_ENABLED` 开 ∧ 路由判 supervisor ∧ 当时治理层
+ *    并不要求 always),之后运维把 autonomy 热改成 `ask`,那条老行会被标成治理出身 —— 五个前提要**同时**
+ *    成立,且该行仍未决。
+ * 根治要**在 mint 那一刻把出身写进行里**(core 的 `CheckpointGate` 属主面,不是本仓能单方面做的);
+ * 在那之前这一位的定位是**分诊提示**,不是裁决输入 —— 它不参与任何门/CAS/resume 判定,消费端也只拿它
+ * 渲染徽标。登记在此,不加特征化测试(把已知残留钉成契约是另一种病)。
+ */
+export function governanceMandatesShellGateAlways(governance) {
+    return autonomyOverrides(governance.autonomy).shellGate === "always" || governance.manualModeShellGate === "always";
+}
 /**
  * [2942]/[2943] `governanceForced` 的**写侧** —— 把内层策略(治理层自己合成的那些)产的 `ask` 记进标记表。
  *

package/dist/tool-approval.d.ts

@@ -61,6 +61,38 @@ export interface ToolApprovalFrame {
      * `governance-ask-marks.ts` 顶注。
      */
     governanceForced?: true;
+    /**
+     * #144(core 5.25.0,[3438] 接力契约 / [3443] 主件;**ADDITIVE**,`"tool_approval"` only)——
+     * 这只 ask **命中了**调用方的一条持久 allow 规则,而那条规则**没能清掉它**。值 = 被越级的那条规则
+     * **原文**(core `AskRequest.persistedRuleShadowed`,四个 mint 点全带;core 侧已过 `inlineUntrusted`)。
+     *
+     * 🔴 **它存在的理由是一次真实的用户面回归**:core 5.25.0 收窄了消音边界(裁定逐字:「Allow rules
+     * silence the CLASSIFIER's questions, never a MANDATED one」)—— `shellGate:"always"` 的部署、工具自带
+     * egress/irreversible mark、以及既有的 governance 三类门下,用户此前被规则消掉的 ask **重新出现**。
+     * 没有这个键,人看到的是「我明明点过『不再询问』,它怎么又问」,唯一合理的结论是「我的规则坏了/没存上」。
+     * 有了它,壳能渲「你的规则仍在,只是这次调用被(运维令 / 工具本性)要求逐次确认」。
+     *
+     * 🔴 **缺席 ≠「你没有规则」**:本键只在「有规则命中 ∧ 规则清不掉这只 ask」时在场。绝大多数 ask
+     * 压根没有规则命中(缺席),而**命中且清掉了**的那些根本不会变成 ask(它们被消音了,没有卡)。
+     * 消费端禁把缺席读成「你在这条命令上没有规则」。
+     *
+     * 与 {@link ToolApprovalFrame.governanceForced} **刻意分列、不合并**:那个键回答「门是谁下的」
+     * (运维治理层),本键回答「你那条规则怎么了」。governance 只是不可消音的三个来源之一,另两个
+     * (doctrine `always` / 工具自带 mark)不打 governance 标 —— 合并会让后两类的 ask 要么谎报治理出身、
+     * 要么丢掉规则解释。出身的完整推法见 [3438]:`gate.safetyAxis` + `riskDescriptor.shellGateDoctrine` +
+     * `realApproval.origin` 组合读,server 不新铸出身键。
+     *
+     * 值是**用户内容族**(规则原文是人写的文本)⇒ 与 `message`/`sourceAgentName` 同待遇:`redactSecrets`
+     * 后上帧,UNTRUSTED-for-display。空串**不铸键**(core 只在真有命中时带它,空串是坏值不是「空规则」)。
+     *
+     * 耐久路(park 行)的对偶是 `gate.riskDescriptor.shadowedRule` —— 我方对 `riskDescriptor` 是**整体透传**
+     * (SQL 双生落整只 JSON 列、`listPending` 整只回读、两条 durable 读面整行上 wire),所以那一路**键集**零施工;
+     * 唯一的施工是**内容**:那两条读面(`GET /v1/approvals` + `/v1/approvals/stream`)在读边界对这一格补
+     * `redactSecrets`(core 只中和不脱敏,而运维队列是跨租户可见的那一条 —— 见
+     * `http/routes/approvals-assistant.ts` 的 `redactPendingDisclosures` 顶注)。
+     * 两路的钉见 `test/approval-shadowed-rule-wire.test.ts` 与 db-integration 的「#209 件4」格。
+     */
+    persistedRuleShadowed?: string;
     /**
      * #154 车二(core 5.18.0 design/179):`"tool_approval"` only —— 引擎为这次 ask 铸的**规则候选**
      * (`AskRequest.ruleSuggestions`,逐字透传:闭词表 `match` + 引擎铸的文本,server 不重铸不重排)。