@sema-agent/server 7.52.1 → 7.54.0

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

@@ -15,7 +15,7 @@ import { type SqlDriver } from "./sql-driver.js";
  */
 export declare function writerOfSqlRuleStore(store: PermissionRuleStore): PermissionRuleWriter | undefined;
 /**
- * 382P1(core 7.0.0 design/382 §4.3)—— 这是 **DURABLE 二员面**的 at-rest 形:`{global, project-with-root}`,
+ * 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` 探针表钉住)。
  * `RuleScope` 联合自 v7 起有第三员 `session`,但它**结构上**不许进持久店(家在会话 overlay,随会话死):
  * at-rest 解码不认它 ⇒ 一条被外部写进来的 session 行整桶拒读(fail-closed),写臂另由 core 的
@@ -32,7 +32,7 @@ export declare const PERMISSION_RULE_TICKET_TABLE = "permission_rule_ticket";
  * `tidb-pool.ts` 的 `SCHEMA_STATEMENTS` 用 `...TIDB_PERMISSION_RULE_STATEMENTS` 展开,于是三张表跟着
  * 中央 `ensureSchema` 在 **named-lock 的那条 conn** 上建(同 `TIDB_APPROVAL_ASK_STATEMENTS` 先例)。
  *
- * 列宽依据(#192 A10 的「每列的值由谁铸、有没有入口上限」口径):
+ * 列宽依据([ref] A10 的「每列的值由谁铸、有没有入口上限」口径):
  *  · `owner_key` / `record_id` / `ticket_id` / `approval_id` / `payload_hash` / `checksum` → 190:
  *    全是本仓自铸的键类值(sha256 hex 64 / uuid 36 / `sha256:` 前缀 71),190 是全仓键轴的统一宽度。
  *  · `principal` → 512:principal 入口上限是 `PRINCIPAL_MAX_LENGTH = 190`(`security.ts`),这里给
@@ -46,7 +46,7 @@ export declare const TIDB_PERMISSION_RULE_STATEMENTS: readonly string[];
  *  本函数留给只需要这三张表的集成测试)。 */
 export declare function ensureTiDBPermissionRuleSchema(pool: MySqlPool): Promise<void>;
 /**
- * #340 升级前置断言 —— **拒启**,不是 warn(codex 交叉复审 [high],验真后修;形照 #119 的
+ * [ref] 升级前置断言 —— **拒启**,不是 warn(codex 交叉复审 [high],验真后修;形照 [ref] 的
  * `assertToolResultProvenanceSchema` 先例)。
  *
  * 病:本仓不发 `ALTER TABLE` 迁移(SCHEMA POLICY:改列就改 CREATE + 删库重建)。于是一台**没删表**就升
@@ -57,10 +57,11 @@ export declare function ensureTiDBPermissionRuleSchema(pool: MySqlPool): Promise
  *    `rule_store_error` —— 裁决照常 200,服务看起来完全健康;
  *  · CC 导入的 prepare 连 pending 记录都落不下;
  *  · 而 `/v1/capabilities` 的 `permissionRules` 仍然报 true ⇒ 本仓「says yes ⟺ route works」整句为假。
- * 没有这道断言,运维得不到**任何**「这次升级必须重建表」的信号 —— 那正是 #157「禁静默降级」要挡的形态。
+ * 没有这道断言,运维得不到**任何**「这次升级必须重建表」的信号 —— 那正是 [ref]「禁静默降级」要挡的形态。
  *
  * 判据用**能力探测**而不是版本号/information_schema:发一条恒空的 `WHERE 1=0` 读,列不在就报错。
- * 只判「两列在不在」,不判宽度(两列都是 TEXT 族,没有截断轴)。
+ * 只判「五列在不在」(command / edited_json / offers_json 三列 TEXT 族 + version / selected_offer 两列
+ * INT),不判宽度(TEXT 族无截断轴,INT 无宽度轴)。
  *
  * 🔴 **只有可证的缺列才给破坏性指路**(codex 交叉复审 round2/round3 [high],两轮收窄后的终形):
  * 「探针失败」**不等于**「列不在」。超时、连接被重置、取消、资源不足、列级权限被拒、表整个不存在 ——
@@ -69,12 +70,12 @@ export declare function ensureTiDBPermissionRuleSchema(pool: MySqlPool): Promise
  * 终形判据 = **方言的缺列错误码**,一行一方言的闭集(见 {@link isMissingColumnError});其余错误
  * **原样 rethrow**,一个字都不加工。真库两条腿各自跑过这条路径(db-integration 的存量表格),所以
  * 这张码表不是抄手册抄来的,是实测钉住的。
- * 🔴 位置与 #119 同款:**不在** `ensureSchema` 里(那条通道的契约是「只发 CREATE」,有运行时门看着),
+ * 🔴 位置与 [ref] 同款:**不在** `ensureSchema` 里(那条通道的契约是「只发 CREATE」,有运行时门看着),
  * 放在 DDL 之后、任何路由装配之前 —— 还没开始服务,拒启的意义仍在;且**只在规则车道真会被装配时**跑
  * (`PERMISSION_RULES_ENABLED=false` 的部署根本不碰这张表,为它拒启是纯误伤,见调用点)。
  */
 /**
- * 「这个错误**是**『列不存在』吗」——判据属主自 #363 起收在 `sql-errors.ts`(与 `isDupKeyError` 同族、
+ * 「这个错误**是**『列不存在』吗」——判据属主自 [ref] 起收在 `sql-errors.ts`(与 `isDupKeyError` 同族、
  * 同理由:识别集复制一次就会漂,而这条谓词守的是一句**破坏性**指路)。本文件此前那份逐字实现已下车,
  * 语义一个字不变(闭集与 fail-safe 方向逐字见那边的头注)。
  */
@@ -82,7 +83,7 @@ export declare function assertPermissionRuleApprovalSchema(query: (sql: string)
     rows: Record<string, unknown>[];
 }>, dialect: "tidb" | "pg"): Promise<void>;
 /**
- * #265 A7 升级前置断言 —— **拒启**(形与理由逐字照 {@link assertPermissionRuleApprovalSchema} 的配方,
+ * [ref] A7 升级前置断言 —— **拒启**(形与理由逐字照 {@link assertPermissionRuleApprovalSchema} 的配方,
  * 那条头注写了这道门为什么必须是拒启而不是 warn:本仓不发 `ALTER TABLE`,`CREATE TABLE IF NOT EXISTS`
  * 对存量表是空操作,而新列被**无条件**引用)。
  *
@@ -172,7 +173,7 @@ export interface RuleImportTicket {
     expiresAtMs: number;
 }
 /**
- * #265 A7 —— 一张票是**哪条导入车道**铸的(codex 交叉轮 R1-F2,验真后修)。
+ * [ref] A7 —— 一张票是**哪条导入车道**铸的(codex 交叉轮 R1-F2,验真后修)。
  *
  * 🔴 闭集且**不可变**:两条车道共用这张表,而它们的票语义刻意不同(cc-import 一次性 / local-import
  * 可恢复三态)。票不带这一位时,两条车道的兑付口互相**可以吃对方的票** —— 那不是"多一条路",那是让
@@ -195,7 +196,7 @@ export type RuleTicketRedeemResult = {
     reason: "unknown" | "wrong-principal" | "wrong-purpose" | "expired" | "consumed";
 };
 /**
- * [4232]③/[4235]③ —— 票的**判定钟**覆写(记账钟永远不覆写,见 `consume` 内注)。
+ * [ref]③/[ref]③ —— 票的**判定钟**覆写(记账钟永远不覆写,见 `consume` 内注)。
  *
  * 缺席 = 墙钟,既有行为逐字不变。在场 = 调用方(同意车道)按**单调锚**投影出来的那个时刻:
  * 铸票时刻的墙钟 + 自铸票起单调钟走过的量。它只能让判定更贴近**真实经过的时间**,给不了票额外寿命
@@ -205,7 +206,7 @@ export interface RuleTicketDecisionClock {
     decisionNowMs?: number;
 }
 /**
- * #265 A7 —— 一张票的**三态快照**(MINTED → CLAIMED → SETTLED)。
+ * [ref] A7 —— 一张票的**三态快照**(MINTED → CLAIMED → SETTLED)。
  *
  * 🔴 判别式联合而不是"一个态字符串 + 两个可选字段":三个态各自带的东西**互不相干**,而消费方对三者
  * 要做的事完全不同(首兑 / 判租约 / 逐字回放)。塌成一个可选包会让"已落定却读不出终局"这种矛盾态
@@ -213,7 +214,7 @@ export interface RuleTicketDecisionClock {
  * 对属主说一次谎)。
  *
  * `claimAgeMs` 由**店自己**用它的记账钟算,不交给调用方去减:认领戳(`consumed_at_ms`)是真墙钟,
- * 而车道手里那只是单调投影 —— 两只钟不在同一个域,跨域相减出来的"年龄"没有意义(本仓 [4232]③ 的
+ * 而车道手里那只是单调投影 —— 两只钟不在同一个域,跨域相减出来的"年龄"没有意义(本仓 [ref]③ 的
  * 教训:两只钟必须分家,谁的问题谁的钟答)。
  */
 export type RuleTicketSnapshot = {
@@ -226,7 +227,7 @@ export type RuleTicketSnapshot = {
     outcome: unknown;
 };
 /**
- * #265 A7 —— 抢认领的结果。赢家拿回**票上那两样不可变的东西**(`approval_id` / `payload_hash`),
+ * [ref] A7 —— 抢认领的结果。赢家拿回**票上那两样不可变的东西**(`approval_id` / `payload_hash`),
  * 与 {@link RuleTicketRedeemResult} 的成功臂同形:抢到认领之后要做的事与首次认领之后**一模一样**
  * (读记录 → 载荷比对 → 走批),所以两条路必须交出同一份素材,否则恢复臂就得自己再发一条读 ——
  * 而"认领之后还有一次可能失败的 I/O"正是本仓 round4 修掉的那个形。
@@ -242,27 +243,28 @@ export type RuleTicketReclaimResult = {
     ok: false;
 };
 /**
- * [4232]③ 同族的 **GC 宽限**:`reapExpired` 只收「按墙钟至少已死一个完整 TTL」的票行。
+ * [ref]③ 同族的 **GC 宽限**:`reapExpired` 只收「按墙钟至少已死一个完整 TTL」的票行。
  *
  * 为什么需要它:判定侧改单调锚之后,一张「按墙钟已过期、按单调钟还在窗内」的票是**可兑付**的;
  * 若 GC 仍按 `expires_at_ms <= now` 收行,判定修好了而行先没了 —— 用户拿到的从 `expired` 变成 `unknown`,
- * 缺陷只是换了个归因。宽限一个 TTL 覆盖住「铸票时钟慢了不到一个 TTL」这一族(含 [4232]③ 的真实构造)。
+ * 缺陷只是换了个归因。宽限一个 TTL 覆盖住「铸票时钟慢了不到一个 TTL」这一族(含 [ref]③ 的真实构造)。
  *
  * 残余(如实登记,不假称已解):墙钟被拨慢**超过**一个 TTL 时,行仍可能在单调窗内被收。彻底解需要行上
- * 存单调基准,而单调基准跨进程无意义(core [4235] 的判词)。补偿是现成的:prepare 廉价,重铸一张即可
+ * 存单调基准,而单调基准跨进程无意义(core [ref] 的判词)。补偿是现成的:prepare 廉价,重铸一张即可
  * ——这正是 core 建议的姿态(「接受 + 票廉价重铸」)。
  */
 export declare const RULE_IMPORT_TICKET_GC_GRACE_MS: number;
 /**
- * #265 A7 —— **数据库自己的钟**(毫秒),两方言各一句(codex 交叉轮 R5-F1,验真后修)。
+ * [ref] A7 —— **数据库自己的钟**(毫秒),两方言各一句(codex 交叉轮 R5-F1,验真后修)。
  *
  * 用处:`settled_at_ms` 的写入与清扫「已落定」那一支的截止**必须在同一个钟域**。它们此前各拿各副本的
- * 墙钟:落定那台若比跑清扫那台慢过一个宽限(本仓 [4232]③ 记过一次真实的 11 分钟 NTP 纠正),一份**刚刚**
+ * 墙钟:落定那台若比跑清扫那台慢过一个宽限(本仓 [ref]③ 记过一次真实的 11 分钟 NTP 纠正),一份**刚刚**
  * 生出来的权威回执下一拍就被删,而"落定之后必有一个完整的回放窗"是本批新许下的承诺 —— 它不能建立在
  * 「两台机器的钟差不多」这条没人声明过的假设上。数据库的钟是这两台副本**唯一**共享的那口钟。
  *
- * 🔴 射程**刻意只到这一支**:票的其余三列(`expires_at_ms` / `consumed_at_ms` / `created_at_ms`)仍在
- * 既有的副本墙钟域里 —— 那是 cc-import 车道的**既存已登记残余**([4232]③,收口方向逐字见
+ * 🔴 射程更新(车K 2026-08-30 对账):`consumed_at_ms` 自 R8-F2 起**也走本钟**(`consume` 的 UPDATE
+ * 直写本常量,见其行注);仍留在副本墙钟域的是 `expires_at_ms` / `created_at_ms` 两列 —— 那是
+ * cc-import 车道的**既存已登记残余**([ref]③,收口方向逐字见
  * `rules-consent.ts` 的 anchors 头注),把它一并搬走会改动两条车道共用的认领谓词,不在本批射程。
  * 这一句同时也是那次收口的**样板**:形已经在这里了,下一批照抄即可。
  */
@@ -292,8 +294,8 @@ export declare class SqlRuleImportTicketStore {
         ttlMs: number;
     }): Promise<RuleImportTicket>;
     /**
-     * **一次性原子认领**(F1 ③)。四个条件全部写在 `WHERE` 里 —— ticket 身份、principal 绑定、未过期、
-     * 未认领 —— 于是并发双 redeem 由引擎的行锁裁决,恰一条 `affected === 1`。
+     * **一次性原子认领**(F1 ③)。五个条件全部写在 `WHERE` 里 —— ticket 身份、principal 绑定、车道绑定
+     * (purpose,A7 R1-F2)、未认领、未过期 —— 于是并发双 redeem 由引擎的行锁裁决,恰一条 `affected === 1`。
      *
      * 🔴 **认领的 UPDATE 是这条方法的最后一次 I/O**(codex 交叉复审 round4 [high],验真后修)。
      * 旧形是「先 UPDATE 认领、再 SELECT 取 approvalId/payloadHash」——那条 SELECT 失败时本方法**抛错**,
@@ -302,8 +304,8 @@ export declare class SqlRuleImportTicketStore {
      * `approval_id` / `payload_hash` 自铸票起就是**不可变**列,先读与后读读到的是同一份字节。
      *
      * 🔴 **这仍然不是 read-then-write**(禁令的语义没有松动):**裁决**依旧只由那条条件 `UPDATE` 的
-     * `WHERE` 做出 —— 预读的三条否定项只用来**短路 + 归因**(把拒绝分成 unknown/wrong-principal/
-     * expired/consumed 四类给服务端日志;wire 面把四类折成同一个 404)。预读说「可以」而 UPDATE 命中零行,
+     * `WHERE` 做出 —— 预读的五条否定项只用来**短路 + 归因**(把拒绝分成 unknown/wrong-principal/
+     * wrong-purpose/expired/consumed 五类给服务端日志;wire 面把五类折成同一个 404)。预读说「可以」而 UPDATE 命中零行,
      * 只可能是我们在这两跳之间输给了一个并发认领者 —— 如实报 `consumed`,而不是把这次失败当成成功。
      */
     consume(ticketId: string, principal: string, purpose: RuleTicketPurpose, opts?: RuleTicketDecisionClock): Promise<RuleTicketRedeemResult>;
@@ -325,7 +327,7 @@ export declare class SqlRuleImportTicketStore {
      */
     release(ticketId: string, principal: string, claimId: string, mustRemainValidMs?: number, opts?: RuleTicketDecisionClock): Promise<boolean>;
     /**
-     * #265 A7 —— CLAIMED → **SETTLED**:把这一次兑付的终局写进行里。
+     * [ref] A7 —— CLAIMED → **SETTLED**:把这一次兑付的终局写进行里。
      *
      * 🔴 判据全写在 `WHERE` 里(与 `consume` 同一条纪律,**禁 read-then-write**):必须**持有认领**
      * (`consumed_at_ms IS NOT NULL`)且**尚未落定**(`redeemed_outcome IS NULL`)。两个写者同时到达时
@@ -338,14 +340,14 @@ export declare class SqlRuleImportTicketStore {
      */
     settle(ticketId: string, principal: string, claimId: string, outcome: unknown): Promise<boolean>;
     /**
-     * #265 A7 —— 读一张票的三态。**principal 绑定**与四类拒同源:别人的票 / 不存在的票一律 `undefined`
+     * [ref] A7 —— 读一张票的三态。**principal 绑定**与四类拒同源:别人的票 / 不存在的票一律 `undefined`
      * (调用方把它折成同一个 404,零存在性 oracle)。
      *
      * `claimAgeMs` 在**这里**算(店的记账钟),不交给调用方:见 {@link RuleTicketSnapshot} 的头注。
      */
     peek(ticketId: string, principal: string, purpose: RuleTicketPurpose): Promise<RuleTicketSnapshot | undefined>;
     /**
-     * #265 A7 —— **崩溃窗恢复**:把一次**可证陈旧**的认领抢过来。
+     * [ref] A7 —— **崩溃窗恢复**:把一次**可证陈旧**的认领抢过来。
      *
      * 病:`consume` 之后、`settle` 之前硬崩,票停在 CLAIMED 且永远不会自己走完。旧形(cc-import)对这
      * 一格没有答案 —— 票随 TTL 消失,人的确认丢掉;而 `release` 帮不上忙,它要求那个死掉的进程**还活着
@@ -373,7 +375,7 @@ export declare class SqlRuleImportTicketStore {
     private readRow;
 }
 /**
- * 孤儿 pending 审批记录的保留期(A-010.17)。
+ * 孤儿 pending 审批记录的保留期([ref])。
  *
  * 判据是「**可证已死**」,不是一个拍脑袋的时长:一条 pending 记录只能经 `redeemRuleTicket` 走活,
  * 而兑付要么发生在铸它的**那一次请求内**(`persistCardRule` 的 prepare→confirm→redeem 三步同请求),
@@ -406,7 +408,7 @@ export interface PermissionRuleStores {
     provider: SqlPermissionRuleStoreProvider;
     approvals: SqlRuleApprovalRecordStore;
     tickets: SqlRuleImportTicketStore;
-    /** #203 §3 —— boot 期休眠行审计的**窄读口**:库里已有几只桶(`permission_rule` 一行一桶)。
+    /** [ref] §3 —— boot 期休眠行审计的**窄读口**:库里已有几只桶(`permission_rule` 一行一桶)。
      *
      *  🔴 为什么数**桶**而不是数**规则**:数规则要把每一行的 `rules_json` 都读回来再解析(一只桶的规则集
      *  没有硬上限,顶注 §列宽依据已说明它是 LONGTEXT),那是一次无界的 boot 期扫描 —— 为一条诊断行付这个
@@ -414,7 +416,7 @@ export interface PermissionRuleStores {
      *  索引级 `COUNT(*)`。消费点(`boot/permission-rules-audit.ts`)的文案因此逐字说的是 bucket,不是 rule。 */
     countBuckets(): Promise<number>;
     /**
-     * 保留期腿(A-010.17)。返回删掉的**总行数**(两张表合计),给 reaper 的 `reapCount` 用。
+     * 保留期腿([ref])。返回删掉的**总行数**(两张表合计),给 reaper 的 `reapCount` 用。
      *
      * 病:这两张表此前**没有任何 retention 腿**,而它们都是只进不出的:
      *  · `permission_rule_ticket` —— 每一次 `POST /v1/rules/cc-import/prepare` 落一行,不管有没有人去
@@ -424,9 +426,12 @@ export interface PermissionRuleStores {
      *    没按确认」这条最常见的人类路径,每走一次留一条永远没人要的行(`discardPendingRecord` 只收
      *    「超帽当场拒」那一条路,不收「人改主意了」)。
      *
-     * 两条谓词都只删**可证已死**的行,所以本腿不需要旋钮(没有可调的语义):
-     *  · 票:`expires_at_ms <= now` —— `consume` 的硬条件是 `expires_at_ms > now`,过期票已不可兑付;
-     *  · 记录:`state = 'pending' AND created_at_ms < now − {@link RULE_PENDING_APPROVAL_RETENTION_MS}`。
+     * 两张表的谓词都只删**可证已死**的行,所以本腿不需要旋钮(没有可调的语义):
+     *  · 票(三支 OR,A7 交叉复审定形,逐支论证见 reapExpired 实现内注):甲=从未认领且已过期;
+     *    乙=已落定且落定后过 GC 宽限(按 `settled_at_ms` 判,走 DB 钟);丙=CLAIMED-未结且认领戳老过
+     *    废弃期(按 `consumed_at_ms` 判,走 DB 钟);
+     *  · 记录:`state = 'pending' AND created_at_ms < now − {@link RULE_PENDING_APPROVAL_RETENTION_MS}`,
+     *    再加 `NOT EXISTS`(载荷必须陪着把手活,R6-F1:仍有票引用的 pending 记录不删)。
      */
     reapExpired(nowMs: number): Promise<number>;
 }

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

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, foldDelta, parseAllowRuleText, screenRuleSyncState, PERMISSION_RULE_WRITER, RULE_SYNC_DROP_CODES, } from "@sema-agent/core";
 import { dialectProtocolJsonEncoder } from "./sql-driver.js";
 import { isMissingColumnError } from "./sql-errors.js";
+import { canonicalJson } from "../canonical-json.js";
 export function writerOfSqlRuleStore(store) {
     const w = Reflect.get(store, PERMISSION_RULE_WRITER);
     if (w === null || typeof w !== "object")
@@ -80,10 +81,14 @@ export const TIDB_PERMISSION_RULE_STATEMENTS = [
     tombstones_json LONGTEXT NOT NULL,
     quarantined_json LONGTEXT NOT NULL,
     -- observed_vector_json:同步游标面(design/182 §5.1 的观测向量)。整读整写的 JSON blob——
-    -- core 明令不得拆成一 actor 一行(会让「半个更新」变得可表达)。
+    -- core 明令不得拆成一 actor 一行(会让「半个更新」变得可表达)。⚠️ 现状如实(车K 2026-08-30 亲核):
+    -- 本店**零 UPDATE 写口**(ensureBucket 恒插 NULL,cas 的 SET 不含此列)⇒ 该列今日恒 NULL;读侧
+    -- (read 的 parse、checksum 的 observedVector 参与位)是为它备的座。「是否该有写口」已登记候裁,
+    -- 裁前不添写口、不删读座。
     observed_vector_json LONGTEXT NULL,
     last_round_at_ms BIGINT NULL,
-    -- checksum:core \`ruleStoreChecksum\` 同精神的完整性指纹(**只覆盖内容三列**,不含 rev/counter)。
+    -- checksum:core \`ruleStoreChecksum\` 同精神的完整性指纹(覆盖内容三列 + observed_vector 在场时的
+    -- 观测向量,不含 rev/counter——算法单点=buildRuleBucketChecksum)。
     -- 读回不符 ⇒ throw(绝不静默当空店 —— core 对读失败的姿势明令如此)。
     checksum VARCHAR(190) NOT NULL,
     created_at_ms BIGINT NOT NULL,
@@ -303,16 +308,6 @@ export function buildRuleOwnerKey(owner) {
 export function buildRuleBucketChecksum(body) {
     return `sha256:${createHash("sha256").update(canonicalJson(body), "utf8").digest("hex")}`;
 }
-function canonicalJson(v) {
-    if (v === null || typeof v !== "object")
-        return JSON.stringify(v) ?? "null";
-    if (Array.isArray(v))
-        return `[${v.map(canonicalJson).join(",")}]`;
-    const entries = Object.entries(v)
-        .filter(([, val]) => val !== undefined)
-        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
-    return `{${entries.map(([k, val]) => `${JSON.stringify(k)}:${canonicalJson(val)}`).join(",")}}`;
-}
 const NEXT_DOT_MAX_ATTEMPTS = 8;
 const EMPTY_BUCKET = { actor: "", counter: 0, rev: 0, rules: [], tombstones: [], quarantined: [] };
 function parseColumn(schema, raw, column, ownerKey) {

package/dist/plugins/pg-cost-quota.d.ts

@@ -5,7 +5,7 @@
  * bucket), PostgreSQL dialect instead of MySQL/TiDB. The two are kept in lock-step by ONE shared real-DB
  * integration suite (test/pg-cost-quota-integration.test.ts) running the SAME scenarios on BOTH engines.
  *
- * design/158 A12 C1b: this file used to carry a PRIVATE inline copy of the write-behind counter, hardwired
+ * [ref] A12 C1b: this file used to carry a PRIVATE inline copy of the write-behind counter, hardwired
  * to the `cost_quota` columns — the third copy of the same 150 lines. It is gone; both dialects now share
  * ONE dialect-parameterized implementation (write-behind-counter.ts), and the dialect deltas this header
  * used to enumerate ($n placeholders / ON CONFLICT increment / rowCount / BIGINT-as-string) are documented
@@ -16,7 +16,7 @@ import type { QuotaDecision, QuotaLimits, QuotaTracker } from "../observability/
 import { type CounterDegradeHook } from "./write-behind-counter.js";
 export declare class PgCostQuota implements QuotaTracker {
     private readonly counter;
-    /** #322:与 TiDB 孪生逐字同语义(限额=比较参数;关断哨兵零 SQL;窗长换代=换桶)。 */
+    /** [ref]:与 TiDB 孪生逐字同语义(限额=比较参数;关断哨兵零 SQL;窗长换代=换桶)。 */
     private limitMicroUsd;
     private refreshRequested;
     private refreshIntervalMs;

package/dist/plugins/pg-pool.d.ts

@@ -39,9 +39,36 @@ export declare const PG_SCHEMA_STATEMENTS: readonly string[];
  *  Unset = both off (byte-compat: legit heavyweight statements — boot DDL, ≤64 MiB snapshot-blob rows — make a
  *  universal default unsafe; the S9 write-behind counter face carries its own always-on per-query timeout). */
 export declare function pgPoolOptions(pgCfg: NonNullable<ServiceConfig["pg"]>, dbQueryTimeoutMs?: number): pg.PoolConfig;
+/** 池连接错误的结构化摘要([ref];idle 态与 checked-out 态两监听共用)。纯函数,单测直打。字段
+ *  **诚实缺席**:code/severity 只在错误对象上真有 string 值时才出键(pg 的 DatabaseError 把两者
+ *  平铺在错误对象上;裸网络错误没有)—— 不 String() 硬铸,「不知道 ≠ 铸一个假值」([ref] 同族纪律)。 */
+export interface PgPoolClientErrorMeta {
+    message: string;
+    code?: string;
+    severity?: string;
+}
+export declare function pgPoolClientErrorMeta(err: unknown): PgPoolClientErrorMeta;
+/** `createPgPool` 的 warn 座(形=store-backend 的 `BootLogSink`;不 import 它——那是反向依赖)。 */
+export type PgPoolWarnSink = (msg: string, meta?: Record<string, unknown>) => void;
 /** Create the PG pool from a connection string (or pg.PoolConfig). Thin — production backend-selection wiring
- *  (a ServiceConfig.pg sibling of .tidb) is a tracked follow-on. */
-export declare function createPgPool(opts: string | pg.PoolConfig): pg.Pool;
+ *  (a ServiceConfig.pg sibling of .tidb) is a tracked follow-on.
+ *
+ *  ── [ref](DEBTS;test [ref] 独立复现 FATAL 57P01→exit)——池必须挂 'error' 监听 ─────────────────
+ *  node-postgres 语义(pg-pool@3.14.0 `makeIdleListener`):一条**空闲**连接出错
+ *  (`pg_terminate_backend` / 云端故障切换 / LB 空闲回收 / 网络断)⇒ 池先 `_remove(client)` 再
+ *  `pool.emit('error', err, client)`。Pool 是 EventEmitter ⇒ 无 'error' 监听时 Node 把这枚事件转
+ *  throw(ERR_UNHANDLED_ERROR)⇒ `boot/shutdown.ts` 的 uncaughtException 钩无条件 exit 1 ⇒
+ *  **一条空闲连接的死换整进程的死**。修在源头监听,三件明确**不做**:
+ *   · 不 exit —— 坏连接在 emit **之前**已被池淘汰,下次 acquire 发新连接,在飞查询(在别的
+ *     client 上)零影响,这不是进程级故障;
+ *   · 不静默 —— 每次事件一条结构化 warn(含 code/severity)+ `recordFailOpen`(F 类,census 第
+ *     52 行):「连接不断被外部杀」(故障切换风暴 / 回收策略过激)与「一切正常」在服务面同形,
+ *     不留痕则只能靠间接症状发现;
+ *   · 不动 shutdown.ts 的 uncaughtException 钩 —— exit 1 对**真**未捕获仍是正确姿势,旁路兜底
+ *     会吞掉别人的崩溃([ref] 纪律:修源头,不下游兜)。
+ *  `onIdleClientError` 缺省 console.warn(与本文件 `ensurePgSchema` 的既有告警姿势一致)——生产
+ *  装配(store-backend `createStoreBackend`)递结构化 logger 的 warn 座。 */
+export declare function createPgPool(opts: string | pg.PoolConfig, onIdleClientError?: PgPoolWarnSink): pg.Pool;
 /** Idempotent central schema apply (the PG twin of tidb-pool.ts ensureSchema): the run/checkpoint tables here +
  *  every PG store's own (disjoint) tables. Order is irrelevant (CREATE IF NOT EXISTS, no cross-table FKs).
  *

package/dist/plugins/pg-pool.js

@@ -1,4 +1,5 @@
 import pg from "pg";
+import { recordFailOpen } from "../observability/fail-open.js";
 import { ensureSchema as ensureSessionSchema } from "./pg-session-storage.js";
 import { ensureSchema as ensureToolResultSchema } from "./tool-result-store-sql.js";
 import { ensureSchema as ensureCostQuotaSchema } from "./pg-cost-quota.js";
@@ -9,6 +10,7 @@ import { ensureSchema as ensureImageIndexSchema } from "./image-index-sql.js";
 import { ensurePgImageBakeSchema as ensureImageBakeSchema } from "./image-bake-store-sql.js";
 import { ensurePgApprovalAskSchema } from "./approval-ask-store-sql.js";
 import { ensurePgMemoryOptOutGrantSchema } from "./memory-optout-grant-store-sql.js";
+import { ensurePgSessionCaptureOptOutSchema } from "./session-capture-record-store-sql.js";
 import { ensurePgAdoptionLogSchema } from "./adoption-log-sql.js";
 import { ensurePgPermissionRuleSchema } from "./permission-rule-store-sql.js";
 import { ensurePgLeaderRunSchema } from "./leader-run-store-sql.js";
@@ -90,6 +92,9 @@ export const PG_SCHEMA_STATEMENTS = [
      -- rule_suggestions:语义、铸行侧的窄读/脱敏/截断纪律、以及「NULL = 无供给 ⇒ 读口省键」的完整由来见
      -- MySQL 孪生(tidb-pool.ts 同名列的行内注)。
      rule_suggestions TEXT COLLATE "C",
+     -- has_bidi_controls(S-30① / #356②):bidi 在场位,语义与「1 或 NULL、恒不写 0」见 MySQL 孪生同名列的
+     -- 行内注。clay 批 TINYINT(1) 归一先例:PG 侧统一 SMALLINT。
+     has_bidi_controls SMALLINT,
      PRIMARY KEY (token)
    )`,
     `CREATE INDEX IF NOT EXISTS idx_checkpoint_status_deadline ON checkpoint (status, deadline)`,
@@ -337,8 +342,50 @@ export function pgPoolOptions(pgCfg, dbQueryTimeoutMs) {
         ...(dbQueryTimeoutMs ? { statement_timeout: dbQueryTimeoutMs, query_timeout: dbQueryTimeoutMs + 5_000 } : {}),
     };
 }
-export function createPgPool(opts) {
-    return typeof opts === "string" ? new pg.Pool({ connectionString: opts }) : new pg.Pool(opts);
+export function pgPoolClientErrorMeta(err) {
+    const bag = typeof err === "object" && err !== null ? err : {};
+    return {
+        message: err instanceof Error ? err.message : String(err),
+        ...(typeof bag.code === "string" ? { code: bag.code } : {}),
+        ...(typeof bag.severity === "string" ? { severity: bag.severity } : {}),
+    };
+}
+export function createPgPool(opts, onIdleClientError) {
+    const pool = typeof opts === "string" ? new pg.Pool({ connectionString: opts }) : new pg.Pool(opts);
+    const warn = onIdleClientError ?? ((msg, meta) => console.warn(`[pg-pool] ${msg}`, meta));
+    const report = (msgName, state, err, count) => {
+        const meta = pgPoolClientErrorMeta(err);
+        try {
+            warn(msgName, { ...meta });
+        }
+        catch {
+        }
+        if (!count)
+            return;
+        const firstLine = meta.message.split("\n", 1)[0] ?? "";
+        recordFailOpen("server.pg-pool.idle-client-error", `state=${state} ${meta.code ?? "uncoded"}/${meta.severity ?? "?"} ${firstLine.slice(0, 200)}`);
+    };
+    pool.on("error", (err) => report("pg_pool_idle_client_error", "idle", err, true));
+    const checkoutGuards = new WeakMap();
+    pool.on("acquire", (client) => {
+        if (checkoutGuards.has(client))
+            return;
+        let counted = false;
+        const guard = (err) => {
+            report("pg_pool_checked_out_client_error", "checked-out", err, !counted);
+            counted = true;
+        };
+        checkoutGuards.set(client, guard);
+        client.on("error", guard);
+    });
+    pool.on("release", (_err, client) => {
+        const guard = checkoutGuards.get(client);
+        if (guard !== undefined) {
+            client.removeListener("error", guard);
+            checkoutGuards.delete(client);
+        }
+    });
+    return pool;
 }
 const ENSURE_SCHEMA_LOCK_KEY = 4906;
 export async function ensurePgSchema(pool) {
@@ -364,6 +411,7 @@ export async function ensurePgSchema(pool) {
         await ensureImageBakeSchema(client);
         await ensurePgApprovalAskSchema((text, params) => client.query(text, params));
         await ensurePgMemoryOptOutGrantSchema((text, params) => client.query(text, params));
+        await ensurePgSessionCaptureOptOutSchema((text, params) => client.query(text, params));
         await ensurePgAdoptionLogSchema((text, params) => client.query(text, params));
         await ensurePgPermissionRuleSchema((text, params) => client.query(text, params));
         await ensurePgLeaderRunSchema((text, params) => client.query(text, params));

package/dist/plugins/pg-query.d.ts

@@ -4,7 +4,7 @@
  *
  * HISTORY: this type used to be re-exported by `@sema-agent/core` from its pg REFERENCE adapter. core 1.424.0
  * removed the whole example-adapter export surface from the npm package (clay's package-hygiene ruling,
- * board [1803] — examples are in-repo samples, not user API). The type itself is server-owned wiring, so it
+ * board [ref] — examples are in-repo samples, not user API). The type itself is server-owned wiring, so it
  * moved here VERBATIM (same shape as core 1.423's `examples/adapters/pg-adapter.d.ts`); six plugins consume it.
  */
 export interface PgQueryResult {

package/dist/plugins/pg-rate-limiter.d.ts

@@ -6,7 +6,7 @@
  * (eventually consistent: a replica may briefly admit a few requests over the ceiling at a window
  * boundary before peers' counts propagate).
  *
- * design/158 A12 C1b: the `PgWriteBehindCounter` this file used to define inline now lives in
+ * [ref] A12 C1b: the `PgWriteBehindCounter` this file used to define inline now lives in
  * write-behind-counter.ts as the PG binding of ONE dialect-parameterized counter (the mysql2 twin is
  * `WriteBehindCounter`); the SQL-dialect deltas are documented and branched there.
  *
@@ -18,7 +18,7 @@ import type { RateDecision, RateGate, RateLimits } from "../observability/rate-l
 import { type CounterDegradeHook } from "./write-behind-counter.js";
 export declare class PgRateLimiter implements RateGate {
     private readonly counter;
-    /** #322:与 TiDB 孪生逐字同语义(限额=比较参数;关断哨兵停/起刷新环)。 */
+    /** [ref]:与 TiDB 孪生逐字同语义(限额=比较参数;关断哨兵停/起刷新环)。 */
     private limit;
     private refreshRequested;
     private refreshIntervalMs;

package/dist/plugins/pg-session-storage.d.ts

@@ -24,7 +24,7 @@ export declare class PgSessionStorage extends BaseSessionStorage {
     private readonly sessionId;
     private readonly floorSeq;
     constructor(pool: Pool, sessionId: string, metadata: SessionMetadata, entries: SessionTreeEntry[], leafId: string | null, floorEntryId?: string | null, floorSeq?: number);
-    /** @see TiDBSessionStorage.getEpochAnchor — [976] S3 RB-14 pull seam, PG dialect twin
+    /** @see TiDBSessionStorage.getEpochAnchor — [ref] S3 [ref] pull seam, PG dialect twin
      *  (keyset-paged to exhaustion: a bounded scan over restatement-less pre-epoch compactions would
      *  misreport an epoch-bearing session as pre-epoch — codex HIGH). */
     getEpochAnchor(): Promise<PromptEpochDescriptor | undefined>;
@@ -49,9 +49,9 @@ export declare class PgSessionStorage extends BaseSessionStorage {
  */
 export declare class PgSessionStore implements SessionStore {
     private readonly pool;
-    /** #270 车1:托管留存声明(TiDB 孪生同格)。读法见 `retention-store-sql.ts` 的 {@link MANAGED_RETENTION}。 */
+    /** [ref] 车1:托管留存声明(TiDB 孪生同格)。读法见 `retention-store-sql.ts` 的 {@link MANAGED_RETENTION}。 */
     readonly retention: import("@sema-agent/core").RetentionDeclaration;
-    /** #292 C18(core 5.48.0 design/323):placement 声明(TiDB 孪生同格,义务逐条见
+    /** [ref] C18(core 5.48.0 [ref]):placement 声明(TiDB 孪生同格,义务逐条见
      *  `src/plugins/session-placement.ts` 顶注)。 */
     readonly placements: {
         readonly subagent: {
@@ -64,11 +64,11 @@ export declare class PgSessionStore implements SessionStore {
     acquire(sessionId?: string, opts?: PlacementAcquireOpts): Promise<AcquiredSession>;
     private load;
     /** Idempotently create a session_meta row with an owner. Existing owner is never overwritten.
-     *  #292:`placement` 与行同一条 INSERT;`DO NOTHING` 臂 ⇒ 已存在行的元组永不被重写(first-write 不可变)。 */
+     *  [ref]:`placement` 与行同一条 INSERT;`DO NOTHING` 臂 ⇒ 已存在行的元组永不被重写(first-write 不可变)。 */
     register(sessionId: string, owner: string | null, placement?: SessionPlacement): Promise<void>;
-    /** #292 义务 6 的廉价探针(TiDB 孪生 {@link TiDBSessionStore.placementOf} 同义)。 */
+    /** [ref] 义务 6 的廉价探针(TiDB 孪生 {@link TiDBSessionStore.placementOf} 同义)。 */
     placementOf(sessionId: string): Promise<SessionPlacementRecord | undefined>;
-    /** #292 义务 5 —— placed 分区枚举(年龄锚/上界/tupleIncomplete 三条读法与 TiDB 孪生逐字同义,
+    /** [ref] 义务 5 —— placed 分区枚举(年龄锚/上界/tupleIncomplete 三条读法与 TiDB 孪生逐字同义,
      *  见 {@link TiDBSessionStore.listPlaced})。 */
     listPlaced(kind: "subagent", opts?: {
         olderThanMs?: number;
@@ -80,20 +80,20 @@ export declare class PgSessionStore implements SessionStore {
     /** E18 — the session's current leaf SessionTreeEntry.id (session_meta.leaf_id). @see TiDBSessionStore.getLeafId
      *  (single SELECT, no acquire/lock, cache-bypassing — safe to read mid-run for the resume-at turn-capture). */
     getLeafId(sessionId: string): Promise<string | null>;
-    /** [1196] 六轮复审:owner+leafId 单行原子快照(@see TiDBSessionStore.getHead——混世代组合防)。 */
+    /** [ref] 六轮复审:owner+leafId 单行原子快照(@see TiDBSessionStore.getHead——混世代组合防)。 */
     getHead(sessionId: string): Promise<{
         owner: string | null;
         leafId: string | null;
     } | undefined>;
     /** Durable history is retained; just drop any in-flight cache entry.
-     *  🔴 #292 义务 4:**placed 会话例外 —— release 是真删除**(理由/ABA 条件删/失败上浮三条读法逐字见
+     *  🔴 [ref] 义务 4:**placed 会话例外 —— release 是真删除**(理由/ABA 条件删/失败上浮三条读法逐字见
      *  {@link TiDBSessionStore.release},本腿是它的 PG 孪生)。 */
     release(sessionId: string): Promise<void>;
     /** @see TiDBSessionStore.forget — 丢引用不动 durable 史(preflight 纪律的落点;PG 孪生)。 */
     forget(sessionId: string): void;
     /** @see TiDBSessionStore.deletePlacedSession — PG 孪生(条件删门 + meta 先删 + 失败上浮同义)。 */
     private deletePlacedSession;
-    /** #292:placed id 拒绝 session-sync 的整段换装(TiDB 孪生 {@link TiDBSessionStore.assertNotPlaced} 同义)。 */
+    /** [ref]:placed id 拒绝 session-sync 的整段换装(TiDB 孪生 {@link TiDBSessionStore.assertNotPlaced} 同义)。 */
     private assertNotPlaced;
     /** @see TiDBSessionStore.listSessions — session identity from session_meta (owner-filtered), task_run LEFT JOIN for preview. */
     listSessions(opts: {

package/dist/plugins/remote-env-adb.d.ts

@@ -23,7 +23,7 @@ type ConnectResult = {
     error: RemoteExecutionError;
 };
 /**
- * Test seam (design/61 §9.3 fault-injection): inject `spawn` and/or a `connectOnce` that replays an error
+ * Test seam ([ref] §9.3 fault-injection): inject `spawn` and/or a `connectOnce` that replays an error
  * sequence, so the retry policy + first-attach behaviour is deterministically testable without a real device
  * (the E2B-adapter bug that only surfaced in dogfood is the lesson this guards against).
  */

package/dist/plugins/remote-env-device.d.ts

@@ -1,5 +1,5 @@
 import { ExecutionError, FileError, RemoteExecutionError, type ExecutionEnv, type ExecutionEnvFactory, type ExecStreamOptions, type FileInfo, type OutputChunk, type RemoteConnectConfig, type RemoteExecutionEnv, type Result, type SessionToken, type SnapshotId, type VmLifecycleOptions, type WorkspaceHandle, type WriteExpectation, type WriteReceipt } from "@sema-agent/core";
-import { DEVICE_RATE_LIMIT_CODE, type DeviceErrorCode, type DeviceOwner, type DeviceRow, type DeviceStore } from "../device-store.js";
+import { type DeviceOwner, type DeviceRejectCode, type DeviceRow, type DeviceStore } from "../device-store.js";
 import type { DeviceEnrollment } from "../device-enrollment.js";
 import type { DeviceWsHub } from "../device-ws-hub.js";
 import type { DeviceInstructionKind, DeviceOutcomeErrorCode } from "../device-ws-protocol.js";
@@ -12,7 +12,7 @@ type ExecOpts = Parameters<ExecutionEnv["exec"]>[1];
  * 设备**结局帧**的错误码 → core `FileErrorCode`。
  *
  * `Record<DeviceOutcomeErrorCode, …>` 是**穷举**的:协议的结局码闭集加词而此处不加行 = 编译红
- * (#157 词表纪律;不是运行时 switch 的默认臂)。
+ * ([ref] 词表纪律;不是运行时 switch 的默认臂)。
  *
  * 🔴 三条不许折错的线:
  *  ① `outcome_unknown` **原样过境**——core 把它排除在 `RETRYABLE_REMOTE_ERROR_CODES` 之外正是为了
@@ -34,7 +34,7 @@ export declare const DEVICE_OUTCOME_TO_FILE_ERROR: Readonly<Record<DeviceOutcome
  * **从未启动**,因为可执行面解析不了」,与「设备没有这条指令面」同侧;never-started 语义保住)。
  */
 export declare const DEVICE_OUTCOME_TO_EXEC_ERROR: Readonly<Record<DeviceOutcomeErrorCode, ExecutionError["code"]>>;
-type RejectCode = DeviceErrorCode | typeof DEVICE_RATE_LIMIT_CODE;
+type RejectCode = DeviceRejectCode;
 /**
  * 汇聚端的 **typed 拒**(投递门**之前**,§5.3 投递边界:设备从未可能见过这条指令)→ core 错误码。
  *
@@ -44,6 +44,8 @@ type RejectCode = DeviceErrorCode | typeof DEVICE_RATE_LIMIT_CODE;
  * 例外 `identity_mismatch` / `revoked` / `not_found`:那是**永久**拒(换设备/吊销/不是你的),重试
  * 只会同样失败 —— exec 面落 `auth_failed`(NEVER retry 的那一格),file 面无对位词落 `permission_denied`
  * (「这条路你走不通,而且不是暂时的」是它最近的语义)。
+ * `draining`([ref] 借用位)与 busy 同侧(commit 前拒,从未启动)—— 判别靠 rejectText 把 `[draining]`
+ * 整句带进文案:重试该去**替换副本**,不是稍后打同一个。
  */
 export declare const DEVICE_REJECT_TO_EXEC_ERROR: Readonly<Record<RejectCode, ExecutionError["code"]>>;
 export declare const DEVICE_REJECT_TO_FILE_ERROR: Readonly<Record<RejectCode, FileError["code"]>>;
@@ -88,7 +90,7 @@ export declare class RemoteDeviceExecutionEnv implements RemoteExecutionEnv {
         suspendable: boolean;
     };
     readonly externalContentTarget = true;
-    /** #211:设备路径不在 worker 宿主文件系统上 —— host-path 回执消费方据此拒绝把它当宿主路径呈现。 */
+    /** [ref]:设备路径不在 worker 宿主文件系统上 —— host-path 回执消费方据此拒绝把它当宿主路径呈现。 */
     readonly hostLocalPaths = false;
     cwd: string;
     /** 可选面(presence-typed,见文件头「铁律」段):构造期按设备声明装配,缺席就是缺席。 */

package/dist/plugins/remote-env-device.js

@@ -1,6 +1,6 @@
 import { posix } from "node:path";
 import { ExecutionError, FileError, RemoteExecutionError, } from "@sema-agent/core";
-import { DEVICE_ERROR_CODES, DEVICE_RATE_LIMIT_CODE, } from "../device-store.js";
+import { DEVICE_ERROR_CODES, } from "../device-store.js";
 export const DEVICE_PROVIDER = "device";
 const ok = (value) => ({ ok: true, value });
 const STREAM_PENDING_MAX_BYTES = 2 * 1024 * 1024;
@@ -60,6 +60,7 @@ export const DEVICE_REJECT_TO_EXEC_ERROR = {
     "device.enrollment_invalid": "auth_failed",
     "not_found.device": "auth_failed",
     "limit.rate_exceeded": "target_unavailable",
+    "draining": "target_unavailable",
 };
 export const DEVICE_REJECT_TO_FILE_ERROR = {
     "device.not_bound": "transport_lost",
@@ -73,6 +74,7 @@ export const DEVICE_REJECT_TO_FILE_ERROR = {
     "device.enrollment_invalid": "permission_denied",
     "not_found.device": "permission_denied",
     "limit.rate_exceeded": "transport_lost",
+    "draining": "transport_lost",
 };
 const DEVICE_REJECT_TO_REMOTE_ERROR = {
     "device.not_bound": "connect_failed",
@@ -86,6 +88,7 @@ const DEVICE_REJECT_TO_REMOTE_ERROR = {
     "device.enrollment_invalid": "auth_failed",
     "not_found.device": "auth_failed",
     "limit.rate_exceeded": "connect_failed",
+    "draining": "connect_failed",
 };
 function rejectText(reject) {
     return `[${reject.code}] ${reject.message}`;