@sema-agent/server 7.146.0 → 7.148.0

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

@@ -1,3 +1,4 @@
+import { createLogger } from "../observability/logger.js";
 import { join } from "node:path";
 import { existsSync, readFileSync } from "node:fs";
 import { atomicWriteFile, ensureDir } from "@sema-agent/core";
@@ -97,7 +98,7 @@ export class FileOrgDeliveryQuotaStore extends MemoryOrgDeliveryQuotaStore {
         }
         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 });
+            (opts?.warn ?? createLogger().warn)("org_delivery_quota_corrupt_read", { path: this.path, problem: parsed.problem });
             return;
         }
         this.state = parsed.state;

package/dist/plugins/owner-only-file-mode.d.ts

@@ -0,0 +1,29 @@
+export declare const OWNER_ONLY_FILE_MODE = 384;
+/**
+ * 调用方声明的持久化要求(闭集;两个出口同一参数、必填 —— 没有缺省,每只调用点自己说):
+ *  · `required` —— 这次写是一道围栏的持久化事实(例:local 数据根的引擎版本高水位):目录项没证落盘就不算写成,目录 fsync 失败 ⇒ 抛;
+ *  · `best-effort` —— 一般留痕 / 缓存 / 账本:目录 fsync 失败 ⇒ 写算成功(新内容已可见),F 类留痕 `server.atomic-write.dir-fsync-failed`。
+ */
+export type AtomicWriteDurability = "required" | "best-effort";
+/** 原子写的选项(两个出口同形)。 */
+export interface AtomicWriteOptions {
+    readonly durability: AtomicWriteDurability;
+}
+/**
+ * 异步原子写:同目录 tmp 以 `open(tmp, "wx", {@link OWNER_ONLY_FILE_MODE})` 显式独占新建 —— **拿到句柄那一刻起 tmp 归我**(不从错误形推断);
+ * 写好、fsync、关句柄、`rename` 到 `target`,再 fsync 目录(失败的去向按 `opts.durability`)—— 读者只见整份旧文件或整份新文件(撞名与清理律见头注)。
+ * I/O 经 `node:fs/promises`(与会话店的读口同一只模块):测试对那只模块装的拦点(打开 / 改名)看得见每一次写。
+ */
+export declare function atomicWriteFileAsync(target: string, data: string | Uint8Array, opts: AtomicWriteOptions): Promise<void>;
+/**
+ * 一只**已在位**的文件的持久化屏障(原子写以它收尾的那两步:fsync 文件、fsync 它的目录;win32 不 fsync 目录)—— 给「相等不写」的调用方:
+ * 读到的那一份可能是上一次写落了 `rename` 而目录项没证到的,不重写也要证它在盘上。失败即抛(它只服务 `required` 的事实;不是写口,不改字节、inode、mtime)。
+ */
+export declare function proveDurableSync(target: string): void;
+/**
+ * 同步原子写:与异步形同一只命名与清理律,外加 core `atomicWriteFile` 的其余语义(先 `ensureDir` 父目录;tmp 写好 `fsync`,`rename` 之后 fsync 目录)。
+ * 目录 fsync 失败不回滚(新内容已经可见,也回滚不了);抛不抛按 `opts.durability`(`best-effort` 不抛、留痕;`required` 抛 —— 头注那一座)。
+ * win32 不 fsync 目录(打不开目录 fd;NTFS 的目录项由文件系统日志落盘)。
+ */
+export declare function atomicWriteFileSync(target: string, data: string | Uint8Array, opts: AtomicWriteOptions): void;
+//# sourceMappingURL=owner-only-file-mode.d.ts.map

package/dist/plugins/owner-only-file-mode.js

@@ -0,0 +1,141 @@
+import { closeSync, fsyncSync, openSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { open, rename, rm } from "node:fs/promises";
+import { randomBytes } from "node:crypto";
+import { dirname } from "node:path";
+import { ensureDir } from "@sema-agent/core";
+import { IS_WIN32 } from "./host-platform.js";
+import { recordFailOpen } from "../observability/fail-open.js";
+export const OWNER_ONLY_FILE_MODE = 0o600;
+const TMP_RANDOM_BYTES = 6;
+const TMP_ATTEMPTS = 8;
+const tmpPathFor = (target) => `${target}.${process.pid}.${randomBytes(TMP_RANDOM_BYTES).toString("hex")}.tmp`;
+const collided = (err) => typeof err === "object" && err !== null && "code" in err && err.code === "EEXIST";
+const messageOf = (e) => (e instanceof Error ? e.message : String(e));
+const cleanupFailed = (target, tmp, err, cleanup) => new Error(`atomic write of ${target} failed (${messageOf(err)}) and its temporary file ${tmp} could not be removed (${messageOf(cleanup)})`, { cause: err });
+const useAndCloseFailed = (use, close) => Object.assign(new AggregateError([use, close], messageOf(use)), { code: typeof use === "object" && use !== null && "code" in use ? use.code : undefined });
+async function usingHandle(handle, use) {
+    try {
+        await use(handle);
+    }
+    catch (err) {
+        await handle.close().catch((close) => {
+            throw useAndCloseFailed(err, close);
+        });
+        throw err;
+    }
+    await handle.close();
+}
+function usingFd(fd, use) {
+    try {
+        use(fd);
+    }
+    catch (err) {
+        try {
+            closeSync(fd);
+        }
+        catch (close) {
+            throw useAndCloseFailed(err, close);
+        }
+        throw err;
+    }
+    closeSync(fd);
+}
+function dirFsyncFailed(target, err, durability) {
+    switch (durability) {
+        case "required":
+            throw new Error(`atomic write of ${target} landed but its directory entry could not be made durable (${messageOf(err)}) — the write is visible but not proven on disk`, { cause: err });
+        case "best-effort":
+            recordFailOpen("server.atomic-write.dir-fsync-failed", `path=${target} err=${messageOf(err)}`);
+            return;
+        default: {
+            const unhandled = durability;
+            throw new Error(`atomic write of ${target}: unknown durability ${String(unhandled)}`);
+        }
+    }
+}
+export async function atomicWriteFileAsync(target, data, opts) {
+    const { tmp, handle } = await openOwnTmpAsync(target);
+    try {
+        await usingHandle(handle, async (h) => {
+            await h.writeFile(data);
+            await h.sync();
+        });
+        await rename(tmp, target);
+    }
+    catch (err) {
+        try {
+            await rm(tmp, { force: true });
+        }
+        catch (cleanup) {
+            throw cleanupFailed(target, tmp, err, cleanup);
+        }
+        throw err;
+    }
+    if (IS_WIN32)
+        return;
+    try {
+        await usingHandle(await open(dirname(target), "r"), (dir) => dir.sync());
+    }
+    catch (err) {
+        dirFsyncFailed(target, err, opts.durability);
+    }
+}
+async function openOwnTmpAsync(target) {
+    for (let attempt = 1;; attempt += 1) {
+        const tmp = tmpPathFor(target);
+        try {
+            return { tmp, handle: await open(tmp, "wx", OWNER_ONLY_FILE_MODE) };
+        }
+        catch (err) {
+            if (!collided(err) || attempt >= TMP_ATTEMPTS)
+                throw err;
+        }
+    }
+}
+function openOwnTmpSync(target) {
+    for (let attempt = 1;; attempt += 1) {
+        const tmp = tmpPathFor(target);
+        try {
+            return { tmp, fd: openSync(tmp, "wx", OWNER_ONLY_FILE_MODE) };
+        }
+        catch (err) {
+            if (!collided(err) || attempt >= TMP_ATTEMPTS)
+                throw err;
+        }
+    }
+}
+export function proveDurableSync(target) {
+    usingFd(openSync(target, "r"), fsyncSync);
+    if (IS_WIN32)
+        return;
+    usingFd(openSync(dirname(target), "r"), fsyncSync);
+}
+export function atomicWriteFileSync(target, data, opts) {
+    ensureDir(dirname(target));
+    const { tmp, fd } = openOwnTmpSync(target);
+    try {
+        usingFd(fd, (f) => {
+            writeFileSync(f, data);
+            fsyncSync(f);
+        });
+        renameSync(tmp, target);
+    }
+    catch (err) {
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch (cleanup) {
+            throw cleanupFailed(target, tmp, err, cleanup);
+        }
+        throw err;
+    }
+    if (IS_WIN32)
+        return;
+    try {
+        usingFd(openSync(dirname(target), "r"), fsyncSync);
+    }
+    catch (err) {
+        dirFsyncFailed(target, err, opts.durability);
+    }
+}
+//# sourceMappingURL=owner-only-file-mode.js.map

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

@@ -1,4 +1,5 @@
 import { FileDurableRulePartitionProvider, type RuleApprovalRecord, type RuleApprovalRecordStore, type StaleRuleApprovalRecord } from "@sema-agent/core";
+import type { RuleBucketCensus } from "./imported-layer-root-retirement.js";
 import { type RuleImportTicket, type RuleTicketPurpose, type RuleTicketReclaimResult, type RuleTicketRedeemResult, type RuleTicketSnapshot } from "./permission-rule-store-sql.js";
 import type { PermissionRuleStoreBundle } from "../rules-consent.js";
 import type { Logger } from "../observability/logger.js";
@@ -14,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;
@@ -27,10 +28,9 @@ export declare class FileRuleApprovalRecordStore implements RuleApprovalRecordSt
     create(record: RuleApprovalRecord): Promise<void>;
     cas(id: string, expectRev: number, next: RuleApprovalRecord): Promise<boolean>;
     /**
-     * 一次性迁移 M36(窗口见 `plugins/one-time-migrations.ts` 登记表)在 File 店的桶来源之一:本店**导入记录**点名过的每一个属主(逐条记录取、**这里不去重**:
-     * 多条记录点名同一属主就重复出现,按桶键去重在退役步)。引擎 File 分区的桶文件按属主名的单向摘要命名,桶的属主不写在文件里;File 腿读的桶集是
-     * {@link fileRuleBucketOwners} 取的并集 = 本店导入记录点名的属主 ∪ 引擎 `listBucketOwners().owners`(自 core 7.64.0 起的列桶口:本机属主那只桶与收编标记点名的身份),
-     * 所以记录不是 File 腿叫得出桶属主的唯一来源(SQL 店不经记录,直接列规则表)。引擎 `unnamedBuckets` 为什么本步不报、File 侧还剩的缺口,见 `imported-layer-root-retirement.ts` 头注「读哪些桶」。
+     * 一次性迁移 M36(窗口见 `plugins/one-time-migrations.ts` 登记表)在 File 店交给引擎列桶口的那一半:本店**导入记录**点名过的每一个属主(逐条记录取、**这里不去重**:
+     * 多条记录点名同一属主就重复出现,引擎按名去重)。引擎 File 分区的桶文件按属主名的单向摘要命名,桶的属主不写在文件里;{@link fileRuleBucketOwners} 把这里的身份名
+     * 作 `knownOwners` 交给引擎 `listBucketOwners`,由引擎一次答出桶在场的属主与叫不出名字的桶数(SQL 店不经记录,直接列规则表),见 `imported-layer-root-retirement.ts` 头注「读哪些桶」。
      * 上一形的记录(Stale 信封)读不出种类 ⇒ 属主读得出就算上(多读一只桶零写,少读一只会漏)。
      * 损坏闸合着 ⇒ 抛(读不全记录就叫不全桶;与本面其余口同一条 fail-closed)。
      */
@@ -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。 */
@@ -99,11 +99,11 @@ export declare class FileRuleImportTicketStore {
 /** 三面束在数据根下的目录名(唯一一处;束在第一次装配时建它 —— 没开过规则店的数据根下没有它)。 */
 export declare const FILE_PERMISSION_RULE_DIR = "permission-rules";
 /**
- * M36 File 腿读哪些桶(窗口见 `plugins/one-time-migrations.ts` 登记表;读法见 `imported-layer-root-retirement.ts` 头注「读哪些桶」):
- * 导入记录点名过的属主 ∪ 引擎 File 分区后端列得出名字的属主(本机属主那只桶、收编标记点名的身份)。两源有重 ⇒ 退役步按桶键去重。
- * 引擎列桶口的拒(目录用不了 `bucket_damaged`、列不出 `bucket_unreadable`、坏收编标记)原样抛 ⇒ 起服拒(叫不全桶就不判)。
+ * M36 File 腿的桶普查(窗口见 `plugins/one-time-migrations.ts` 登记表;读法见 `imported-layer-root-retirement.ts` 头注「读哪些桶」):引擎 File 分区后端的列桶口一次答 ——
+ * 目录自己叫得出名字的属主(本机属主那只桶、收编标记点名的身份)+ 导入记录点名过的身份里桶文件在场的那些(`knownOwners`),与两者都叫不出属主的桶数。
+ * 引擎列桶口的拒(目录用不了 `bucket_damaged`、列不出 `bucket_unreadable`、坏收编标记、`knownOwners` 里有不是身份名的串 `config.invalid_argument`)原样抛 ⇒ 起服拒(叫不全桶就不判)。
  */
-export declare function fileRuleBucketOwners(stores: Pick<FilePermissionRuleStores, "approvals" | "durable">): Promise<readonly RuleOwner[]>;
+export declare function fileRuleBucketOwners(stores: Pick<FilePermissionRuleStores, "approvals" | "durable">): Promise<RuleBucketCensus>;
 /**
  * 这只读桶抛出物是不是引擎 File 分区的**确定性整桶拒**(拒码 `permission_rules.bucket_damaged`:同一份字节每次读都同样拒,读侧零规则、什么都不放行)。
  * 别的都不是:`permission_rules.bucket_unreadable`(一次读失败,带 `errno`;证明不了以后也读不出)、`permission_rules.later_grammar`(更新的引擎写的桶)、
@@ -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-file.js

@@ -333,8 +333,20 @@ export class FileRuleImportTicketStore {
 }
 export const FILE_PERMISSION_RULE_DIR = "permission-rules";
 export async function fileRuleBucketOwners(stores) {
-    const listed = stores.durable.listBucketOwners();
-    return [...(await stores.approvals.importRecordOwners()), ...listed.owners];
+    const knownOwners = (await stores.approvals.importRecordOwners()).flatMap(principalNameOfOwner);
+    return stores.durable.listBucketOwners({ knownOwners });
+}
+function principalNameOfOwner(owner) {
+    switch (owner.kind) {
+        case "principal":
+            return [owner.principal];
+        case "local-owner":
+            return [];
+        default: {
+            const unknown = owner;
+            throw new Error(`M36: an owner of a kind this pass does not know: ${JSON.stringify(unknown)}`);
+        }
+    }
 }
 export function isFileBucketDamaged(e) {
     return typeof e === "object" && e !== null && e.code === PERMISSION_RULES_DAMAGED_BUCKET_CODE;

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 墙)。
@@ -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 { 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;
     }
@@ -593,13 +590,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 +605,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 +859,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).
@@ -99,7 +69,8 @@ export declare function acquirePgEnsureSchemaLock(client: pg.PoolClient, tag: st
 /** {@link acquirePgEnsureSchemaLock} 的释放(尽力而为 —— 锁随连接归还自动释放)。 */
 export declare function releasePgEnsureSchemaLock(client: pg.PoolClient, tag: string): Promise<void>;
 /** 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).
+ *  every PG store's own (disjoint) tables. Order is irrelevant (CREATE IF NOT EXISTS) except for the one cross-table FK: the session
+ *  side table `session_ext` references `session_meta`, so it is created right after the session store's tables.
  *
  *  Concurrency: callers run this concurrently — tests fan ALL integration suites out in parallel (each beforeAll
  *  calls ensurePgSchema), and in production every replica calls it at boot. Concurrent DDL on the SAME table makes