@sema-agent/server 7.147.0 → 7.149.0

package/dist/plugins/org-delivery-quota-store.d.ts

@@ -18,20 +18,43 @@ export interface OrgDeliveryQuotaPolicy {
     /** 一个收件人在一个窗里能收的封数上界(全部发件人合计)。 */
     readonly perRecipient: number;
 }
+/** 一次记账的判决:放行,或拒 + 到店钟当前窗结束的整秒数(头注「拒的判决带重试指引」)。 */
+export type OrgDeliveryQuotaVerdict = {
+    readonly granted: true;
+} | {
+    readonly granted: false;
+    readonly retryAfterSec: number;
+};
+/**
+ * 店读不出自己的状态(File 腿:快照坏了)⇒ **拒用**的那一只错。fail-closed:每一次记账都抛它,绝不当成「放行」。
+ * 两句话各有读者,所以分开存:`message` = 运维句(点名文件与坏处、出路 —— 只进运维日志);{@link ORG_DELIVERY_QUOTA_UNREADABLE_SENTENCE} = 上线的
+ * 固定句(不点名宿主路径、不带坏处原文 —— 调用方是组织里的任何成员,不是运维)。HTTP 兜底(`http/server.ts`)按本类映射成带因的 500
+ * (码字面量只写在那一处发送点,wire 码目录的扫描面看得见它)。
+ */
+export declare const ORG_DELIVERY_QUOTA_UNREADABLE_SENTENCE = "the cross-principal delivery quota state on this server cannot be read, so every delivery is refused until an operator repairs it \u2014 nothing was delivered, and retrying will not change the answer";
+export declare class OrgDeliveryQuotaUnreadableError extends Error {
+    constructor(operatorSentence: string);
+}
 export interface OrgDeliveryQuotaStore {
     /**
-     * 原子地把这位发件人的一次投递**尝试**算进店钟当前窗:未满 ⇒ +1、答 `true`;已满 ⇒ 什么都不记、答 `false`。
+     * 原子地把这位发件人的一次投递**尝试**算进店钟当前窗:未满 ⇒ +1、答放行;已满 ⇒ 什么都不记、答拒(带重试指引)。
      * 店读不出 / 写不进 ⇒ **抛**(调用方按失败处置,绝不当成「放行」)。
      */
-    admitAttempt(fromScope: string, policy: OrgDeliveryQuotaPolicy): Promise<boolean>;
+    admitAttempt(fromScope: string, policy: OrgDeliveryQuotaPolicy): Promise<OrgDeliveryQuotaVerdict>;
     /**
-     * 原子地把一封 (fromScope → toScope) 的信算进**店钟当前窗**的两只计数器:两界都未满 ⇒ 两只各 +1、答 `true`;
-     * 任一界已满 ⇒ 什么都不记、答 `false`。店读不出 / 写不进 ⇒ **抛**。
+     * 原子地把一封 (fromScope → toScope) 的信算进**店钟当前窗**的两只计数器:两界都未满 ⇒ 两只各 +1、答放行;
+     * 任一界已满 ⇒ 什么都不记、答拒(带重试指引)。店读不出 / 写不进 ⇒ **抛**。
      */
-    take(fromScope: string, toScope: string, policy: OrgDeliveryQuotaPolicy): Promise<boolean>;
+    take(fromScope: string, toScope: string, policy: OrgDeliveryQuotaPolicy): Promise<OrgDeliveryQuotaVerdict>;
 }
 /** 窗起点(一处算法,三条腿共用)。 */
 export declare function quotaWindowStart(nowMs: number, windowMs: number): number;
+/**
+ * 拒的判决的退避秒数(三条腿共用的**唯一**算式):店钟 `nowMs` 到当前窗结束,向上取整。≥ 1 是桶公式的推论、不另设下限:`nowMs` 严格早于窗末
+ * (`floor(now / w)` 之下 `(桶 + 1) × w − now ∈ (0, w]`),正数向上取整至少是 1 —— 窗末前最后 1 ms 也答 1,不叫客户端「立刻重试」。
+ * 桶与退避秒数的公式不在这里写第二份:都读 `observability/cost-quota.ts` 的 `alignedWindow` / `retryAfterSecUntil`(成本配额、速率限制器同锚)。
+ */
+export declare function quotaRetryAfterSec(nowMs: number, windowMs: number): number;
 /** 店里记着的那个窗(`heldStart`)的计数此刻还算不算数 —— 头注那条律的**唯一**写法:此刻的窗,或此刻的下一个窗。 */
 export declare function heldWindowCounts(heldStart: number, at: number, windowMs: number): boolean;
 /** 一位发件人的当前窗(`windowMs` = 开窗那一次的窗宽:窗何时结束是条目自己的事实,File 腿据它丢已过窗的条目)。 */
@@ -58,8 +81,8 @@ export declare class MemoryOrgDeliveryQuotaStore implements OrgDeliveryQuotaStor
     protected state: QuotaWindows;
     /** @param nowMs 店钟(单进程腿:店 = 这个进程,缺省本进程墙钟)。 */
     constructor(nowMs?: () => number);
-    admitAttempt(fromScope: string, policy: OrgDeliveryQuotaPolicy): Promise<boolean>;
-    take(fromScope: string, toScope: string, policy: OrgDeliveryQuotaPolicy): Promise<boolean>;
+    admitAttempt(fromScope: string, policy: OrgDeliveryQuotaPolicy): Promise<OrgDeliveryQuotaVerdict>;
+    take(fromScope: string, toScope: string, policy: OrgDeliveryQuotaPolicy): Promise<OrgDeliveryQuotaVerdict>;
     /**
      * 落新的整份状态,只留窗还没结束的条目(按条目自己的窗宽判;已结束的发件人 / 收件人整个丢掉 —— 有界:量 = 本窗活跃的主体数)。
      * 丢掉的条目按头注那条律本来就不再算数(过去的窗),所以剪枝不改任何判决;剪枝写在**这里**而不是 File 腿里,Memory 与 File
@@ -89,16 +112,16 @@ export declare class FileOrgDeliveryQuotaStore extends MemoryOrgDeliveryQuotaSto
         nowMs?: () => number;
         warn?: (event: string, fields: Record<string, unknown>) => void;
     });
-    admitAttempt(fromScope: string, policy: OrgDeliveryQuotaPolicy): Promise<boolean>;
-    take(fromScope: string, toScope: string, policy: OrgDeliveryQuotaPolicy): Promise<boolean>;
+    admitAttempt(fromScope: string, policy: OrgDeliveryQuotaPolicy): Promise<OrgDeliveryQuotaVerdict>;
+    take(fromScope: string, toScope: string, policy: OrgDeliveryQuotaPolicy): Promise<OrgDeliveryQuotaVerdict>;
     protected persist(next: QuotaWindows): void;
 }
 export declare class SqlOrgDeliveryQuotaStore implements OrgDeliveryQuotaStore {
     private readonly db;
     constructor(db: SqlDriver);
     private q;
-    admitAttempt(fromScope: string, policy: OrgDeliveryQuotaPolicy): Promise<boolean>;
-    take(fromScope: string, toScope: string, policy: OrgDeliveryQuotaPolicy): Promise<boolean>;
+    admitAttempt(fromScope: string, policy: OrgDeliveryQuotaPolicy): Promise<OrgDeliveryQuotaVerdict>;
+    take(fromScope: string, toScope: string, policy: OrgDeliveryQuotaPolicy): Promise<OrgDeliveryQuotaVerdict>;
     /**
      * 一个记账事务:库钟先读(池上一条值语句,不在事务里留普通 SELECT),判过 ⇒ 提交,判拒 ⇒ 回滚(零残留)。
      * 🔴 **引擎判了死锁 ⇒ 整事务重来**(`retryOnDeadlock`:全仓唯一的重来写法、唯一的上界与判据):被挑中的一方已整事务回滚、锁全放,

package/dist/plugins/org-delivery-quota-store.js

@@ -1,15 +1,28 @@
+import { createLogger } from "../observability/logger.js";
 import { join } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import { atomicWriteFile, ensureDir } from "@sema-agent/core";
 import { mysqlDriver, pgDriver, sqlDbNowMs } from "./sql-driver.js";
 import { retryOnDeadlock } from "./sql-errors.js";
-import { alignedWindow } from "../observability/cost-quota.js";
+import { alignedWindow, retryAfterSecUntil } from "../observability/cost-quota.js";
 export const ORG_DELIVERY_SENDER_QUOTA_TABLE = "org_delivery_sender_quota";
 export const ORG_DELIVERY_RECIPIENT_QUOTA_TABLE = "org_delivery_recipient_quota";
 export const ORG_DELIVERY_PAIR_QUOTA_TABLE = "org_delivery_pair_quota";
+export const ORG_DELIVERY_QUOTA_UNREADABLE_SENTENCE = "the cross-principal delivery quota state on this server cannot be read, so every delivery is refused until an operator repairs it — nothing was delivered, and retrying will not change the answer";
+export class OrgDeliveryQuotaUnreadableError extends Error {
+    constructor(operatorSentence) {
+        super(operatorSentence);
+        this.name = "OrgDeliveryQuotaUnreadableError";
+    }
+}
 export function quotaWindowStart(nowMs, windowMs) {
     return alignedWindow(nowMs, windowMs).bucket * windowMs;
 }
+const GRANTED = Object.freeze({ granted: true });
+export function quotaRetryAfterSec(nowMs, windowMs) {
+    return retryAfterSecUntil(alignedWindow(nowMs, windowMs));
+}
+const refused = (nowMs, windowMs) => ({ granted: false, retryAfterSec: quotaRetryAfterSec(nowMs, windowMs) });
 export function heldWindowCounts(heldStart, at, windowMs) {
     return heldStart === at || heldStart === at + windowMs;
 }
@@ -20,25 +33,27 @@ export class MemoryOrgDeliveryQuotaStore {
         this.nowMs = nowMs;
     }
     async admitAttempt(fromScope, policy) {
-        const at = quotaWindowStart(this.nowMs(), policy.windowMs);
+        const now = this.nowMs();
+        const at = quotaWindowStart(now, policy.windowMs);
         const held = this.state.senders.get(fromScope);
         const current = held !== undefined && heldWindowCounts(held.windowStart, at, policy.windowMs) ? held : { windowStart: at, windowMs: policy.windowMs, attempts: 0 };
         if (current.attempts >= policy.attemptsPerSender)
-            return false;
+            return refused(now, policy.windowMs);
         const senders = new Map(this.state.senders).set(fromScope, { ...current, attempts: current.attempts + 1 });
         this.commit({ senders, recipients: this.state.recipients });
-        return true;
+        return GRANTED;
     }
     async take(fromScope, toScope, policy) {
-        const at = quotaWindowStart(this.nowMs(), policy.windowMs);
+        const now = this.nowMs();
+        const at = quotaWindowStart(now, policy.windowMs);
         const held = this.state.recipients.get(toScope);
         const current = held !== undefined && heldWindowCounts(held.windowStart, at, policy.windowMs) ? held : { windowStart: at, windowMs: policy.windowMs, total: 0, pairs: new Map() };
         const pair = current.pairs.get(fromScope) ?? 0;
         if (current.total >= policy.perRecipient || pair >= policy.perPair)
-            return false;
+            return refused(now, policy.windowMs);
         const next = { ...current, total: current.total + 1, pairs: new Map(current.pairs).set(fromScope, pair + 1) };
         this.commit({ senders: this.state.senders, recipients: new Map(this.state.recipients).set(toScope, next) });
-        return true;
+        return GRANTED;
     }
     commit(next) {
         const now = this.nowMs();
@@ -96,20 +111,20 @@ export class FileOrgDeliveryQuotaStore extends MemoryOrgDeliveryQuotaStore {
             parsed = { ok: false, problem: err instanceof Error ? err.message : String(err) };
         }
         if (!parsed.ok) {
-            this.unusable = `the cross-principal delivery quota file ${this.path} cannot be read (${parsed.problem}) — every delivery is refused until an operator moves it away (moving it resets the current window's counts)`;
-            (opts?.warn ?? ((event, fields) => console.warn(event, fields)))("org_delivery_quota_corrupt_read", { path: this.path, problem: parsed.problem });
+            this.unusable = `the cross-principal delivery quota file ${this.path} cannot be read (${parsed.problem}) — every delivery is refused until an operator repairs or moves it away and restarts this server — the file is read once at startup (moving it away resets the current window's counts)`;
+            (opts?.warn ?? createLogger().warn)("org_delivery_quota_corrupt_read", { path: this.path, problem: parsed.problem });
             return;
         }
         this.state = parsed.state;
     }
     async admitAttempt(fromScope, policy) {
         if (this.unusable !== undefined)
-            throw new Error(this.unusable);
+            throw new OrgDeliveryQuotaUnreadableError(this.unusable);
         return super.admitAttempt(fromScope, policy);
     }
     async take(fromScope, toScope, policy) {
         if (this.unusable !== undefined)
-            throw new Error(this.unusable);
+            throw new OrgDeliveryQuotaUnreadableError(this.unusable);
         return super.take(fromScope, toScope, policy);
     }
     persist(next) {
@@ -140,16 +155,17 @@ export class SqlOrgDeliveryQuotaStore {
         return retryOnDeadlock(this.db.dialect, () => this.inTxOnce(table, policy, body));
     }
     async inTxOnce(table, policy, body) {
-        const at = quotaWindowStart(await sqlDbNowMs(this.db, table), policy.windowMs);
+        const now = await sqlDbNowMs(this.db, table);
+        const at = quotaWindowStart(now, policy.windowMs);
         const conn = await this.db.connect();
         try {
             await conn.begin();
-            const granted = await body(conn, at);
-            if (granted)
+            const ok = await body(conn, at);
+            if (ok)
                 await conn.commit();
             else
                 await conn.rollback();
-            return granted;
+            return ok ? GRANTED : refused(now, policy.windowMs);
         }
         catch (err) {
             await conn.rollback().catch((rollbackErr) => {

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

@@ -15,7 +15,7 @@ export declare class FileRuleApprovalRecordStore implements RuleApprovalRecordSt
     private readonly log;
     /** 本面的损坏闸([ref] 起由重放属主交回;置位后每个方法第一行响亮拒)。 */
     private readonly gate;
-    /** @param warn 腐读披露座([ref];缺席 ⇒ 属主退回 `console.warn`)。 */
+    /** @param warn 腐读披露座([ref];缺席 ⇒ 属主退回日志出口接缝的文本出口 `writeLogText`)。 */
     constructor(dir: string, warn?: Logger["warn"]);
     /** 取证/自证用:本面是否因内部损坏而 fail-closed。 */
     get corrupt(): boolean;
@@ -55,7 +55,7 @@ export declare class FileRuleImportTicketStore {
     private readonly gate;
     /** 单调钟(判定用)。与 {@link now}(墙钟,记账用)是两只不同的钟,别混。 */
     private readonly monotonic;
-    /** @param warn 腐读披露座([ref];缺席 ⇒ 属主退回 `console.warn`)。 */
+    /** @param warn 腐读披露座([ref];缺席 ⇒ 属主退回日志出口接缝的文本出口 `writeLogText`)。 */
     constructor(dir: string, now?: () => number, warn?: Logger["warn"], monotonic?: () => number);
     private readonly now;
     /** 取证/自证用:本面是否因内部损坏而 fail-closed。 */
@@ -128,7 +128,7 @@ export interface FilePermissionRuleStores extends PermissionRuleStoreBundle {
  * `onError` 接的是 core 规则文件的**披露面**(读不出来 / 校验和不符 / 撞上符号链接时它答零规则并
  * 说出来)。接住它打一条 warn 是**必须**的:那条路径上「零规则」与「真的没有规则」在读面上同形,
  * 不留痕就变成一次静默的 fail-closed(用户会突然被反复询问,却没有任何线索)。
- * `warn`([ref])接的是本仓审批记录 / 导入票两份日志的**腐读座**(逐行披露 + 计数;缺席 ⇒ `console.warn`)。
+ * `warn`([ref])接的是本仓审批记录 / 导入票两份日志的**腐读座**(逐行披露 + 计数;缺席 ⇒ 接缝的文本出口 `writeLogText`)。
  */
 export declare function createFilePermissionRuleStores(root: string, opts?: {
     onError?: (message: string) => void;

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

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { type PermissionRuleWriter, type DurableRulePartition, type DurableRulePartitionProvider, type RuleScope, type RuleSyncFrontier, type RuleBehavior, type RuleCandidate, type RuleApprovalRecord, type StaleRuleApprovalRecord, type RuleApprovalRecordStore, type RuleOwner } from "@sema-agent/core";
+import { type PermissionRuleWriter, type DurableRulePartition, type DurableRulePartitionProvider, type RuleScope, type RuleSyncFrontier, type RuleCandidate, 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, type SqlDialect } from "./sql-driver.js";
@@ -59,7 +59,7 @@ export declare const PERMISSION_RULE_TICKET_TABLE = "permission_rule_ticket";
  * 列宽依据([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`),这里给
+ *  · `principal` → 512:principal 入口上限是 `PRINCIPAL_MAX_BYTES = 190` UTF-8 字节(`principal-shape.ts`),这里给
  *    名类宽度 512 是**上界宽于入口**的方向(绝不制造静默截断面)。
  *  · `actor` → 190:本 backend 自铸的副本身份(`sql-<12 hex>`),按构造 ≤ 20 字符。
  *  · 内容列一律 LONGTEXT / TEXT:一只桶的规则集没有硬上限(导入一份大 settings 就能过 64K TEXT 墙)。
@@ -121,7 +121,7 @@ export declare function assertPermissionRuleApprovalSchema(query: (sql: string)
  *
  * 判据同款:发一条恒空的 `WHERE 1=0` 读;**只有可证的缺列**才给「缺列」的拒因(其余错误原样 rethrow ——
  * 超时/连接重置/权限/表不在都会让这条读抛,把它们诊断成「缺列」是一条比缺陷更贵的诊断)。出路是**闭集三条**
- * (与整库对账同一份,{@link describeProbedTableDrift}),没有销毁性的一条。
+ * (与整库对账同一份,{@link probedMissingColumnRefusal}),没有销毁性的一条。
  *
  * 文案照实说本表的分量:票是分钟级 TTL 的治理瞬态(过期即死),持久规则在 `permission_rule` 里,一行都不动。
  */
@@ -185,7 +185,7 @@ export declare function recordOwnerOf(record: {
     readonly principal?: unknown;
 }): RuleOwner | undefined;
 /**
- * 一次性迁移 M36(窗口见 `plugins/one-time-migrations.ts` 登记表)要读的桶:**规则表里的每一只桶**(按 `owner_key` 分页,与 M11 同一只走法)。
+ * 一次性迁移 M36(窗口见 `plugins/one-time-migrations.ts` 登记表)要读的桶:**规则表里的每一只桶**(按 `owner_key` 分页)。
  * 不从审批记录推:收编腿把规则桶整桶改键到新身份、而审批史按 D2 留在旧身份名下(`src/adoption/plan.ts` 的 `permission_rule#owner_key` 腿与
  * `permission-rule-approval-history` 一员)—— 从记录推出的属主集在收编之后漏掉新桶。属主读法只有引擎的 `readRuleOwner`(与本店读口同一只);
  * 读不出属主的行不点名任何可解析的桶(读腿同样解析不到它),不返回。`db` 是池或迁移握锁的那一条连接。
@@ -205,7 +205,7 @@ export declare function isSqlBucketVanished(e: unknown): boolean;
  *  · {@link BucketRefusedError} —— 判官四道(文法戳 / 指纹 / 行的 behavior / 引擎校验器)的拒;
  *  · {@link StoreCorruptError} —— 某只 JSON 列的体读不出(`not-json` / `malformed`),读腿在 {@link refusingUnreadableColumns} 把判官抛的列错误折成的店拒绝契约。
  * 两类都是这一行的确定性判决:原样再读也读不出,读腿对它同样整桶拒(零规则),所以它什么都不放行。
- * 别的抛出物**不是**这一类:连接 / 超时 / 权限(一次读失败证明不了以后也读不出);以及仍以 {@link SqlJsonColumnError} 穿出读腿的唯一一形 `not-text`
+ * 别的抛出物**不是**这一类:连接 / 超时 / 权限(一次读失败证明不了以后也读不出);以及仍以 `SqlJsonColumnError` 穿出读腿的唯一一形 `not-text`
  * (列没按文本投影:读腿与解码点漂了,是码缺陷不是坏数据 —— 按列错误类判它会把一次码漂读成「这只桶坏了」)。
  */
 export declare function isSqlBucketRefusal(e: unknown): boolean;
@@ -473,65 +473,6 @@ export declare const RULE_PENDING_APPROVAL_RETENTION_MS: number;
  * 补建完成之前(或某个副本还没起过新版),这条腿在存量库上仍是全表扫 —— 但每轮 500 行的上界让它的**单次**代价仍然有界。
  */
 export declare const RULE_REAP_BATCH = 500;
-/**
- * M11 删掉的一行。只带桶键、态、工具名与 scope 的 root —— 规则正文不出本函数(命令行里可以有任何东西)。
- *
- * `kind` 是闭集(启动日志按它穷尽分句,`one-time-migrations.ts` `logOneTimeMigrations`):
- *  · `rule` —— 仍有活 add 的规则行(引擎读侧每跑一次丢它并告知;它从未生效,要的话按项目的完整路径重写);
- *  · `revoked-rule` —— 没有活 add 的规则行(判活用 core 的 `applyTombstones`:每个 add 都已被同桶墓碑撤掉,或这一行本来就没有 add):它在任何一侧都已不生效
- *    (allow / deny / ask 同判),无需处置;逐行 warn 的句子只说这个事实,不依赖桶里有没有墓碑、也不依赖态;
- *  · `tombstone` —— 一条撤销记录。它只盖得住同 (behavior, 文本, scope) 的规则 ⇒ 那些规则的 scope 与它同样不被收,随它一起删了或本来就不在,
- *    删它不会让任何被撤销的东西回来。
- */
-export interface UndurableScopeRuleRow {
-    /** 桶键(sha256,不是 principal 原文)。 */
-    readonly ownerKey: string;
-    readonly kind: "rule" | "revoked-rule" | "tombstone";
-    readonly behavior: RuleBehavior;
-    readonly tool: string;
-    /** scope 的 root,**过 `redactSecrets`**(本仓唯一脱敏器):坏 root 是最不可信的自由文本,可能夹着凭据形,而本读数进启动日志与拒因。 */
-    readonly scopeRoot: string;
-}
-/** M11 判成读不出、一个字节没动的桶。`why` = 唯一判官那次整桶拒**不带任何行内容**的拒因(读腿对这只桶照旧整桶拒,它仍是这只桶的属主)。 */
-export interface UnreadableRuleBucket {
-    /** 桶键(sha256,不是 principal 原文)。 */
-    readonly ownerKey: string;
-    readonly why: string;
-}
-/**
- * M11 写进的读数账 —— 三格与一次性迁移段那一只收据账(`one-time-migrations.ts` 的 `MigrationReceipts`)上的同名三格**同名同形**,迁移段把它的账直接递进来
- * ([ref]:一次起服一只收据账,M11 不另起第二套):删掉的行在那只桶的回写**提交的那一刻**追加,之后任何一步失败,拒因随账带走它们。
- */
-export interface UndurableScopePurgeReadings {
-    /** 删掉的行(一行一条读数;每只桶的回写提交之后才追加)。 */
-    readonly undurableScopeRuleRows: UndurableScopeRuleRow[];
-    /** 连续争不过在线写者(OCC 每次都输)而留到下一次起服的桶数。那些桶里的坏行这期间照旧由引擎读侧丢掉并告知。 */
-    undurableScopeRuleBucketsDeferred: number;
-    /** 读腿整桶拒的桶(形 / 指纹 / behavior 闭集 / 墓碑规范文本 / 单一验证器):一个字节不动,逐桶交出拒因,等人处置。 */
-    readonly undurableScopeRuleBucketsUnreadable: UnreadableRuleBucket[];
-}
-/** {@link purgeUndurableScopeRows} 要的最小查询口(一次性迁移段的 `MigrationDb` 同形;占位符按方言由本函数写)。 */
-export interface UndurableScopePurgeDb {
-    rows(sql: string, params?: readonly unknown[]): Promise<Record<string, unknown>[]>;
-    exec(sql: string, params?: readonly unknown[]): Promise<number>;
-}
-/**
- * **M11** —— 把持久桶里 scope 不被 core `isValidDurableScope` 收的行(规则行与墓碑)删掉,一行一条读数。
- *
- * 这些行从哪来:7.119.0 及更早的本仓入口按「root 非空」收 project scope(`/v1/rules` 写口、两条导入面),引擎 7.45 也收;
- * 引擎 7.46.0 把 project root 收窄成完整绝对路径 ⇒ `project:myproj` 一类存量行在读侧被丢(`permission.rule_row_dropped`,每跑一条),
- * 而撤销口删不动它(引擎的写臂对这种 scope 的墓碑同样拒)。⇒ 一次性迁移,不留「撤销口对坏 scope 另开一条读法」的长期双读。
- *
- * 读法与写法都是**店的那一只**:每只桶先过唯一判官 {@link decodeBucketRow}(读腿用的同一只),判官整桶拒 ⇒ 这只桶**一个字节不动**,
- * 进 `undurableScopeRuleBucketsUnreadable`(桶键 + 不带行内容的拒因;读腿对它的整桶拒仍是它的属主,出路是人);判官放行 ⇒ 在那份合法状态上筛 scope,
- * 经写臂的同一只 {@link writeBucket} 整桶 OCC 回写(`WHERE owner_key = ? AND rev = ?`,rev+1,落盘字节与指纹同写臂)—— 不碰别的桶。
- * **硬删、不铸墓碑**:墓碑的作用是挡同步回灌,而引擎的 sync-join 对 scope 不合法的入站行本来就丢(`applySyncJoin`),
- * 本店也不实现同步(见 `apply` 的 sync-join 臂)。
- * 幂等:第二跑零命中零写(读不出的桶每一跑照报,直到有人处置)。
- * 读数写进调用方递进来的账(`into`,{@link UndurableScopePurgeReadings}):删掉的行在那只桶的回写提交之后追加 ⇒ 本函数半途抛出时,已删的行已经在账上;
- * 错误**原样**上抛(不加工、不自铸拒因句 —— 收据由迁移段那一只收据账随拒因带走,[ref])。
- */
-export declare function purgeUndurableScopeRows(db: UndurableScopePurgeDb, dialect: SqlDialect, into: UndurableScopePurgeReadings, now?: () => number): Promise<void>;
 /** 三个 SQL 面的一次性装配束(one driver, three faces)。`durable` = [ref] 的 durable 分区后端;
  *  引擎接缝上的统一店由 `main.ts` 用 `createPermissionRuleStoreProvider({ durable })` 合成一次。 */
 export interface PermissionRuleStores {

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

@@ -1,13 +1,12 @@
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { z } from "zod";
-import { applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, foldDelta, isValidDurableScope, parseRuleText, readRowBehavior, screenRuleSyncState, PERMISSION_RULE_WRITER, RULE_ADD_ORIGINS, RULE_APPROVAL_KINDS, RULE_APPROVAL_RECORD_SCHEMA, RULE_APPROVAL_STATES, RULE_BEHAVIORS, RULE_SYNC_DROP_CODES, EDITED_RULE_BREADTH_WARNING_CODES, PERSISTED_RULE_MATCHES, EMPTY_DURABLE_RULE_PARTITION, PERMISSION_RULES_LATER_GRAMMAR_CODE, SESSION_RULES_GRAMMAR, readRuleGrammarStamp, readRuleOwner, principalNameOf, readRuleOffer2, } from "@sema-agent/core";
+import { applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, foldDelta, parseRuleText, readRowBehavior, screenRuleSyncState, PERMISSION_RULE_WRITER, RULE_ADD_ORIGINS, RULE_APPROVAL_KINDS, RULE_APPROVAL_RECORD_SCHEMA, RULE_APPROVAL_STATES, RULE_BEHAVIORS, RULE_SYNC_DROP_CODES, EDITED_RULE_BREADTH_WARNING_CODES, PERSISTED_RULE_MATCHES, EMPTY_DURABLE_RULE_PARTITION, PERMISSION_RULES_LATER_GRAMMAR_CODE, SESSION_RULES_GRAMMAR, readRuleGrammarStamp, readRuleOwner, principalNameOf, readRuleOffer2, } from "@sema-agent/core";
 import { dialectProtocolJsonEncoder, sqlDbNowMs, SQL_DB_NOW_MS } from "./sql-driver.js";
 import { isMissingColumnError } from "./sql-errors.js";
-import { describeProbedTableDrift } from "./schema-drift-sentence.js";
+import { probedMissingColumnRefusal } from "./schema-drift-sentence.js";
 import { canonicalJsonStringify } from "@sema-agent/core";
 import { ensureIndexes } from "./ensure-index.js";
-import { createZodColumnReader, decodeJsonColumn, foldJsonColumn, jsonColumnText, readJsonObjectColumn, SqlJsonColumnError, StoreCorruptError } from "./sql-json-column.js";
-import { redactSecrets } from "../trace/redact.js";
+import { createZodColumnReader, decodeJsonColumn, foldJsonColumn, jsonColumnText, readJsonObjectColumn, StoreCorruptError } from "./sql-json-column.js";
 export function writerOfSqlRuleStore(store) {
     const w = Reflect.get(store, PERMISSION_RULE_WRITER);
     if (w === null || typeof w !== "object")
@@ -63,11 +62,9 @@ function readBucketRowBehavior(raw, what, ownerKey) {
     return behavior;
 }
 class BucketRefusedError extends Error {
-    verdict;
     code;
     constructor(verdict, evidence, code) {
         super(`${verdict} ${evidence}`);
-        this.verdict = verdict;
         if (code !== undefined)
             this.code = code;
     }
@@ -237,15 +234,13 @@ export async function assertPermissionRuleApprovalSchema(query, dialect) {
     catch (err) {
         if (!isMissingColumnError(err, dialect))
             throw err;
-        throw new Error(`${PERMISSION_RULE_APPROVAL_TABLE} is missing required columns — refusing to start. This build needs the ` +
+        throw await probedMissingColumnRefusal(query, dialect, [PERMISSION_RULE_APPROVAL_TABLE], `${PERMISSION_RULE_APPROVAL_TABLE} is missing required columns — refusing to start. This build needs the ` +
             `#340 card-edit columns (command / edited_json) and the design/375 record-form columns ` +
             `(version / offers_json / selected_offer): the approval record now stores its OPTION structure and the ` +
             `chosen offer, and the store refuses to read rows whose record-form version it cannot vouch for. ` +
             `This table holds pending/settled approval RECORDS (the audit trail of who said yes to which ` +
             `rule), not the rules themselves — persisted rules live in ${PERMISSION_RULE_TABLE} and are untouched; ` +
-            `an in-place ALTER keeps the record trail.\n` +
-            `Underlying probe error: ${err instanceof Error ? err.message : String(err)}\n\n` +
-            (await describeProbedTableDrift(query, dialect, [PERMISSION_RULE_APPROVAL_TABLE])));
+            `an in-place ALTER keeps the record trail.`, err);
     }
 }
 export async function assertPermissionRuleTicketSchema(query, dialect) {
@@ -255,14 +250,12 @@ export async function assertPermissionRuleTicketSchema(query, dialect) {
     catch (err) {
         if (!isMissingColumnError(err, dialect))
             throw err;
-        throw new Error(`${PERMISSION_RULE_TICKET_TABLE} is missing required columns (redeemed_outcome / claim_id / purpose / settled_at_ms) — refusing to start. This build needs ` +
+        throw await probedMissingColumnRefusal(query, dialect, [PERMISSION_RULE_TICKET_TABLE], `${PERMISSION_RULE_TICKET_TABLE} is missing required columns (redeemed_outcome / claim_id / purpose / settled_at_ms) — refusing to start. This build needs ` +
             `the #265 A7 three-state redemption columns (MINTED → CLAIMED → SETTLED, the claim generation that fences a superseded ` +
             `claimant, and the lane binding that keeps cc-import and local-import tickets from being interchangeable): without them a ` +
             `local-import ticket can be claimed but never settled, so a redemption that already wrote rules to the store answers its ` +
             `owner with a retry-later it can never satisfy. This table holds minute-TTL single-use import ` +
-            `tickets (a governance transient that dies on expiry); persisted rules live in ${PERMISSION_RULE_TABLE} and are untouched.\n` +
-            `Underlying probe error: ${err instanceof Error ? err.message : String(err)}\n\n` +
-            (await describeProbedTableDrift(query, dialect, [PERMISSION_RULE_TICKET_TABLE])));
+            `tickets (a governance transient that dies on expiry); persisted rules live in ${PERMISSION_RULE_TABLE} and are untouched.`, err);
     }
 }
 export const PERMISSION_RULE_INDEXES = [
@@ -593,13 +586,14 @@ export class SqlDurableRulePartitionProvider {
 export function recordOwnerOf(record) {
     return readRuleOwner(record.owner ?? { kind: "principal", principal: record.principal });
 }
+const RULE_BUCKET_SCAN_PAGE = 200;
 export async function listRuleBucketOwners(db) {
     const owners = [];
     let after = "";
     for (;;) {
         const { rows } = await db.query(db.dialect === "mysql"
-            ? `SELECT owner_key, owner_kind, principal FROM ${PERMISSION_RULE_TABLE} WHERE owner_key > ? ORDER BY owner_key LIMIT ${UNDURABLE_PURGE_PAGE}`
-            : `SELECT owner_key, owner_kind, principal FROM ${PERMISSION_RULE_TABLE} WHERE owner_key > $1 ORDER BY owner_key LIMIT ${UNDURABLE_PURGE_PAGE}`, [after]);
+            ? `SELECT owner_key, owner_kind, principal FROM ${PERMISSION_RULE_TABLE} WHERE owner_key > ? ORDER BY owner_key LIMIT ${RULE_BUCKET_SCAN_PAGE}`
+            : `SELECT owner_key, owner_kind, principal FROM ${PERMISSION_RULE_TABLE} WHERE owner_key > $1 ORDER BY owner_key LIMIT ${RULE_BUCKET_SCAN_PAGE}`, [after]);
         for (const row of rows) {
             after = String(row["owner_key"]);
             const principal = row["principal"] === null || row["principal"] === undefined ? undefined : String(row["principal"]);
@@ -607,7 +601,7 @@ export async function listRuleBucketOwners(db) {
             if (owner !== undefined)
                 owners.push(owner);
         }
-        if (rows.length < UNDURABLE_PURGE_PAGE)
+        if (rows.length < RULE_BUCKET_SCAN_PAGE)
             return owners;
     }
 }
@@ -861,84 +855,6 @@ export class SqlRuleImportTicketStore {
 }
 export const RULE_PENDING_APPROVAL_RETENTION_MS = 24 * 60 * 60_000;
 export const RULE_REAP_BATCH = 500;
-const UNDURABLE_PURGE_PAGE = 200;
-const UNDURABLE_PURGE_OCC_ATTEMPTS = 5;
-export async function purgeUndurableScopeRows(db, dialect, into, now = Date.now) {
-    const cols = `owner_key, ${bucketRowColumns(dialect)}`;
-    let after = "";
-    for (;;) {
-        const page = await db.rows(dialect === "mysql"
-            ? `SELECT ${cols} FROM ${PERMISSION_RULE_TABLE} WHERE owner_key > ? ORDER BY owner_key LIMIT ${UNDURABLE_PURGE_PAGE}`
-            : `SELECT ${cols} FROM ${PERMISSION_RULE_TABLE} WHERE owner_key > $1 ORDER BY owner_key LIMIT ${UNDURABLE_PURGE_PAGE}`, [after]);
-        for (const first of page) {
-            const ownerKey = String(first.owner_key);
-            after = ownerKey;
-            let row = first;
-            let settled = false;
-            for (let attempt = 0; attempt < UNDURABLE_PURGE_OCC_ATTEMPTS && row !== undefined && !settled; attempt++) {
-                const outcome = await purgeOneBucket(db, dialect, ownerKey, row, now);
-                switch (outcome.kind) {
-                    case "purged":
-                        into.undurableScopeRuleRows.push(...outcome.rows);
-                        settled = true;
-                        break;
-                    case "unreadable":
-                        into.undurableScopeRuleBucketsUnreadable.push({ ownerKey, why: outcome.why });
-                        settled = true;
-                        break;
-                    case "clean":
-                        settled = true;
-                        break;
-                    case "conflict":
-                        row = (await db.rows(dialect === "mysql" ? `SELECT ${cols} FROM ${PERMISSION_RULE_TABLE} WHERE owner_key = ?` : `SELECT ${cols} FROM ${PERMISSION_RULE_TABLE} WHERE owner_key = $1`, [ownerKey]))[0];
-                        if (row === undefined)
-                            settled = true;
-                        break;
-                    default: {
-                        const unknown = outcome;
-                        throw new Error(`M11: unhandled bucket outcome ${JSON.stringify(unknown)}`);
-                    }
-                }
-            }
-            if (!settled)
-                into.undurableScopeRuleBucketsDeferred += 1;
-        }
-        if (page.length < UNDURABLE_PURGE_PAGE)
-            break;
-    }
-}
-async function purgeOneBucket(db, dialect, ownerKey, row, now) {
-    let cur;
-    try {
-        cur = decodeBucketRow(ownerKey, row);
-    }
-    catch (e) {
-        return { kind: "unreadable", why: contentFreeRefusal(ownerKey, e) };
-    }
-    const badRules = cur.rules.filter((r) => !isValidDurableScope(r.scope));
-    const badTombstones = cur.tombstones.filter((t) => !isValidDurableScope(t.scope));
-    if (badRules.length === 0 && badTombstones.length === 0)
-        return { kind: "clean" };
-    const rootOf = (scope) => redactSecrets(scope.kind === "project" ? scope.root : scope.kind);
-    const rows = [
-        ...badRules.map((r) => ({ ownerKey, kind: applyTombstones([r], cur.tombstones).length > 0 ? "rule" : "revoked-rule", behavior: r.behavior, tool: r.tool, scopeRoot: rootOf(r.scope) })),
-        ...badTombstones.map((t) => {
-            const parsed = parseRuleText(t.rule, t.behavior);
-            if ("reject" in parsed)
-                throw new Error(`permission_rule bucket ${ownerKey}: a tombstone the bucket judge admitted does not parse here — refusing to touch the bucket`);
-            return { ownerKey, kind: "tombstone", behavior: t.behavior, tool: parsed.rule.tool, scopeRoot: rootOf(t.scope) };
-        }),
-    ];
-    const landed = await writeBucket((sql, params) => db.exec(sql, params), dialect, ownerKey, cur, { rules: cur.rules.filter((r) => !badRules.includes(r)), tombstones: cur.tombstones.filter((t) => !badTombstones.includes(t)) }, now());
-    return landed ? { kind: "purged", rows } : { kind: "conflict" };
-}
-function contentFreeRefusal(ownerKey, e) {
-    if (e instanceof BucketRefusedError)
-        return e.verdict;
-    if (e instanceof SqlJsonColumnError)
-        return `${e.where}: ${e.problem}`;
-    return `permission_rule bucket ${ownerKey}: the bucket judge threw ${e instanceof Error ? e.name : typeof e} (its text is withheld here: it may quote the row)`;
-}
 export function createSqlPermissionRuleStores(db, now) {
     const q = (mysql, pg) => (db.dialect === "mysql" ? mysql : pg);
     return {

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

@@ -1,33 +1,3 @@
-/**
- * PostgreSQL pool + central schema — the PG sibling of tidb-pool.ts, for the second run-store backend
- * (clay 2026-06-21). Schema ownership is CENTRAL (one ensurePgSchema, like tidb-pool's SCHEMA_STATEMENTS) — PG
- * stores assume the tables exist and NEVER create their own (a per-store `CREATE TABLE IF NOT EXISTS` is
- * first-writer-wins, so a trimmed table would shadow the full one and drop columns).
- *
- * Dialect deltas vs the MySQL DDL in tidb-pool.ts: JSON→JSONB, DATETIME(3)→TIMESTAMPTZ(3), TINYINT(1)→SMALLINT,
- * inline `KEY …`→separate `CREATE INDEX`. checkpoint timestamps stay epoch-ms BIGINT (core's Checkpoint uses ms),
- * matching the TiDB schema byte-for-byte semantically. Only the tables PG backends implement so far are listed
- * (run-store + checkpoint); the remaining tidb-* tables are added as their PG stores land (tracked).
- *
- * ─────────────────────────────── SCHEMA POLICY (clay 裁 2026-07-26) ───────────────────────────────
- * THIS CODE IS THE SINGLE SOURCE OF TRUTH for the PG schema, and there is NO in-place migration seam in this statement array: a database that
- * lags behind the code is refused at boot with the exact `ALTER TABLE … ADD COLUMN …` statements printed, and the
- * deployer runs them themselves: the column-set check and its refusal never alter a database. The only DDL this
- * process runs by itself on a table that already exists is idempotent index creation (`ensureIndex`: indexes only,
- * never a column) and the registered one-time migrations (each has a window and a registry row in
- * `one-time-migrations.ts`) — adding / changing / renaming a column or dropping a table is done by those migrations
- * and by nothing else.
- *
- * Consequence, and it is a hard rule: **do NOT add new `ALTER TABLE` seams here.** Every column / default /
- * constraint change is folded into its own `CREATE TABLE`, and this array stays pure `CREATE TABLE` +
- * `CREATE INDEX`. The historical additive-ALTER seams were folded in on 2026-07-26 (they had all decayed
- * into permanent no-ops — the CREATEs already carried the columns).
- *
- * Because the seams are gone, the semantics they used to document now live as inline `--` comments ON THE
- * COLUMN inside the CREATE, not as TypeScript comments outside the template literal: the full-set SQL
- * baseline `docs/schema/baseline-pg.sql` is GENERATED from these statement strings, so only what is inside
- * the SQL survives the export. The baseline is a derived artifact — regenerate it, never hand-edit it.
- */
 import pg from "pg";
 import type { ServiceConfig } from "../config-types.js";
 export declare const PG_SCHEMA_STATEMENTS: readonly string[];
@@ -70,7 +40,7 @@ export type PgPoolWarnSink = (msg: string, meta?: Record<string, unknown>) => vo
  *     不留痕则只能靠间接症状发现;
  *   · 不动 shutdown.ts 的 uncaughtException 钩 —— exit 1 对**真**未捕获仍是正确姿势,旁路兜底
  *     会吞掉别人的崩溃([ref] 纪律:修源头,不下游兜)。
- *  `onIdleClientError` 缺省 console.warn(与本文件 `ensurePgSchema` 的既有告警姿势一致)——生产
+ *  `onIdleClientError` 缺省 = 日志出口接缝缺省 logger 的 `warn`(与装配后同一种 JSON 行)——生产
  *  装配(store-backend `createStoreBackend`)递结构化 logger 的 warn 座。 */
 export declare function createPgPool(opts: string | pg.PoolConfig, onIdleClientError?: PgPoolWarnSink): pg.Pool;
 /** A fixed bigint key for the `pg_advisory_lock` that serializes the whole `ensurePgSchema` DDL run (see below).
@@ -81,7 +51,7 @@ export declare function createPgPool(opts: string | pg.PoolConfig, onIdleClientE
 export declare const ENSURE_SCHEMA_LOCK_KEY = 4906;
 /**
  * {@link ENSURE_SCHEMA_LOCK_KEY} 的**非阻塞**获取(轮询 + 抖动退避)—— MySQL 孪生
- * `tidb-pool.ts acquireEnsureSchemaLock` 的逐条同形(循环共用 `ensure-schema-lock-policy.ts`)。轮到拿到为止;坏连接连续抛上抛
+ * `tidb-pool.ts acquireEnsureSchemaLock` 的逐条同形(两只都是 `ensure-schema-lock-policy.ts` 取锁器的薄壳:语句 / 读法 / 循环共用)。轮到拿到为止;坏连接连续抛上抛
  * (每条 DDL 本来就各自幂等),而不是把启动挂死。
  *
  * 🔴 **为什么不能再用阻塞的 `pg_advisory_lock()`**([ref] 复审 H1,对 7.82.1 的回归):本仓自 [ref] 起在