@sema-agent/server 7.119.0 → 7.120.0

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

@@ -4,16 +4,12 @@ import { readdirSync } from "node:fs";
 import { performance } from "node:perf_hooks";
 import { FileDurableRulePartitionProvider, AppendLog, ensureDir, } from "@sema-agent/core";
 import { z } from "zod";
-import { buildRulePayloadHash } from "./permission-rule-store-sql.js";
+import { DurableRuleScopeSchema, buildRulePayloadHash } from "./permission-rule-store-sql.js";
 import { replayJsonlGuarded } from "../observability/corrupt-read-seat.js";
 import { EDITED_RULE_BREADTH_WARNING_CODES, RULE_APPROVAL_RECORD_SCHEMA, UNCOVERED_SEGMENT_REASONS } from "../permission-rule-vocab.js";
 import { RULE_BEHAVIORS } from "@sema-agent/core";
-const RuleScopeSchema = z.union([
-    z.object({ kind: z.literal("global") }).strict(),
-    z.object({ kind: z.literal("project"), root: z.string().min(1) }).strict(),
-]);
 const RuleDotSchema = z.object({ actor: z.string().min(1), counter: z.number().int().nonnegative().safe() }).strict();
-const RuleCandidateSchema = z.object({ behavior: z.enum(RULE_BEHAVIORS), rule: z.string(), scope: RuleScopeSchema }).strict();
+const RuleCandidateSchema = z.object({ behavior: z.enum(RULE_BEHAVIORS), rule: z.string(), scope: DurableRuleScopeSchema }).strict();
 const RuleOffer2Schema = z.union([
     z.object({ kind: z.literal("single"), candidate: z.number().int().nonnegative().safe() }).strict(),
     z

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 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 RuleBehavior, 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 } from "./sql-driver.js";
@@ -16,13 +16,19 @@ import { type IndexSpec } from "./ensure-index.js";
  */
 export declare function writerOfSqlRuleStore(store: DurableRulePartition): PermissionRuleWriter | undefined;
 /**
- * 382P1(core 7.0.0 [ref] §4.3)—— 这是 **DURABLE 二员面**的 at-rest 形:`{global, project-with-root}`,
- * 与 core `isValidDurableScope` 逐格等价(`test/permission-rule-durable-face-pin.test.ts` 探针表钉住)。
+ * 382P1(core 7.0.0 [ref] §4.3)—— DURABLE 二员面的 at-rest **形**:`{kind:"global"}` | `{kind:"project", root:string}`。
+ *
+ * 🔴 **只判形,不判 root 收不收**。「这个 root 能不能当持久项目 scope」只有一只判据 —— core 的 `isValidDurableScope`
+ * (7.46.0 起 root 必须是完整绝对路径):写臂在 {@link SqlDurableRulePartition.apply} 里经 core 的
+ * `assertWriteDeltaScopeDurable` 先拒,读侧由 core 的统一店在有效视图里丢掉那一行并发 `permission.rule_row_dropped`
+ * (一行的坏只丢那一行)。本 schema 若再判一次 root,就是第二份判据:它与 core 答案不同的那一天(`proj` / `C:`
+ * 本仓收、引擎丢;空 root 本仓整桶拒、引擎只丢一行),同一行在两侧是两种命运。core 自己的 File 参照后端在 at-rest
+ * 上同样只判形。入口(wire)的判据见 `rules-consent.ts` 的 `parseRuleScope`(调同一只谓词)。
+ *
  * `RuleScope` 联合自 v7 起有第三员 `session`,但它**结构上**不许进持久店(家在会话 overlay,随会话死):
  * at-rest 解码不认它 ⇒ 一条被外部写进来的 session 行整桶拒读(fail-closed),写臂另由 core 的
- * `assertWriteDeltaScopeDurable` 在任何 DB 往返之前以典型码拒(见 `apply`)。consent 面(三员)归
- * engine/cli 半场;本仓 wire 入口 `parseRuleScope` 只拼二员,所以审批记录的候选也用这张表(下方
- * `RuleCandidateSchema`)——那是本仓自己的窄型收口,不是把两张表合成一张。
+ * `assertWriteDeltaScopeDurable` 在任何 DB 往返之前以典型码拒(见 `apply`)。审批记录的候选也用这张表
+ * (下方 `RuleCandidateSchema`;File 店的审批记录读同一只)。
  */
 export declare const DurableRuleScopeSchema: z.ZodType<RuleScope>;
 export declare const PERMISSION_RULE_TABLE = "permission_rule";
@@ -406,6 +412,58 @@ export declare const RULE_PENDING_APPROVAL_RETENTION_MS: number;
  * 同口径)。在那之前,MySQL 存量库上这条腿仍是全表扫 —— 但每轮 500 行的上界让它的**单次**代价仍然有界。
  */
 export declare const RULE_REAP_BATCH = 500;
+/**
+ * M11 删掉的一行。只带桶键、态、工具名与 scope 的 root —— 规则正文不出本函数(命令行里可以有任何东西)。
+ *
+ * `kind` 是闭集(启动日志按它穷尽分句,`one-time-migrations.ts` `logOneTimeMigrations`):
+ *  · `rule` —— 仍有活 add 的规则行(引擎读侧每跑一次丢它并告知;它从未生效,要的话按项目的完整路径重写);
+ *  · `revoked-rule` —— 每个 add 都已被同桶墓碑撤掉的规则行(判活用 core 的 `applyTombstones`):它什么都不授予,人的撤销照旧成立,无需处置;
+ *  · `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 一次跑完的读数。 */
+export interface UndurableScopePurge {
+    readonly removed: readonly UndurableScopeRuleRow[];
+    /** 连续争不过在线写者(OCC 每次都输)而留到下一次起服的桶数。那些桶里的坏行这期间照旧由引擎读侧丢掉并告知。 */
+    readonly bucketsDeferred: number;
+    /** 读腿整桶拒的桶(形 / 指纹 / behavior 闭集 / 墓碑规范文本 / 单一验证器):一个字节不动,逐桶交出拒因,等人处置。 */
+    readonly bucketsUnreadable: readonly 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}(读腿用的同一只),判官整桶拒 ⇒ 这只桶**一个字节不动**,
+ * 进 `bucketsUnreadable`(桶键 + 不带行内容的拒因;读腿对它的整桶拒仍是它的属主,出路是人);判官放行 ⇒ 在那份合法状态上筛 scope,
+ * 经写臂的同一只 {@link writeBucket} 整桶 OCC 回写(`WHERE owner_key = ? AND rev = ?`,rev+1,落盘字节与指纹同写臂)—— 不碰别的桶。
+ * **硬删、不铸墓碑**:墓碑的作用是挡同步回灌,而引擎的 sync-join 对 scope 不合法的入站行本来就丢(`applySyncJoin`),
+ * 本店也不实现同步(见 `apply` 的 sync-join 臂)。
+ * 幂等:第二跑零命中零写(读不出的桶每一跑照报,直到有人处置)。
+ */
+export declare function purgeUndurableScopeRows(db: UndurableScopePurgeDb, dialect: "tidb" | "pg", now?: () => number): Promise<UndurableScopePurge>;
 /** 三个 SQL 面的一次性装配束(one driver, three faces)。`durable` = [ref] 的 durable 分区后端;
  *  引擎接缝上的统一店由 `main.ts` 用 `createPermissionRuleStoreProvider({ durable })` 合成一次。 */
 export interface PermissionRuleStores {

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

@@ -1,12 +1,13 @@
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { z } from "zod";
-import { applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, foldDelta, parseRuleText, readRowBehavior, screenRuleSyncState, PERMISSION_RULE_WRITER, RULE_BEHAVIORS, RULE_SYNC_DROP_CODES, EMPTY_DURABLE_RULE_PARTITION, } from "@sema-agent/core";
+import { applyTombstones, assertDeleteDeltaCarriesNoAdd, assertRedemptionNotQuarantined, assertWriteDeltaScopeDurable, foldDelta, isValidDurableScope, parseRuleText, readRowBehavior, screenRuleSyncState, PERMISSION_RULE_WRITER, RULE_BEHAVIORS, RULE_SYNC_DROP_CODES, EMPTY_DURABLE_RULE_PARTITION, } from "@sema-agent/core";
 import { dialectProtocolJsonEncoder, sqlDbNowMs, SQL_DB_NOW_MS } from "./sql-driver.js";
 import { isMissingColumnError } from "./sql-errors.js";
 import { canonicalJson } from "../canonical-json.js";
 import { EDITED_RULE_BREADTH_WARNING_CODES, PERSISTED_RULE_MATCHES, isPersistedRuleTool, RULE_APPROVAL_RECORD_SCHEMA, UNCOVERED_SEGMENT_REASONS } from "../permission-rule-vocab.js";
 import { ensureIndexes } from "./ensure-index.js";
-import { createZodColumnReader, decodeJsonColumn, foldJsonColumn, jsonColumnText, readJsonObjectColumn } from "./sql-json-column.js";
+import { createZodColumnReader, decodeJsonColumn, foldJsonColumn, jsonColumnText, readJsonObjectColumn, SqlJsonColumnError } from "./sql-json-column.js";
+import { redactSecrets } from "../trace/redact.js";
 export function writerOfSqlRuleStore(store) {
     const w = Reflect.get(store, PERMISSION_RULE_WRITER);
     if (w === null || typeof w !== "object")
@@ -20,7 +21,7 @@ export function writerOfSqlRuleStore(store) {
 }
 export const DurableRuleScopeSchema = z.union([
     z.object({ kind: z.literal("global") }).strict(),
-    z.object({ kind: z.literal("project"), root: z.string().min(1) }).strict(),
+    z.object({ kind: z.literal("project"), root: z.string() }).strict(),
 ]);
 const RuleDotSchema = z.object({ actor: z.string().min(1), counter: z.number().int().nonnegative().safe() }).strict();
 const RuleAddSchema = z
@@ -57,11 +58,17 @@ const QuarantinedRuleAddRowSchema = z
 function readBucketRowBehavior(raw, what, ownerKey) {
     const behavior = readRowBehavior(raw);
     if (behavior === undefined) {
-        throw new Error(`permission_rule bucket ${ownerKey} carries a ${what} whose behavior word is outside the closed set (${JSON.stringify(raw)}) — ` +
-            `refusing the whole bucket rather than reading a standing deny as "no rule"`);
+        throw new BucketRefusedError(`permission_rule bucket ${ownerKey} carries a ${what} whose behavior word is outside the closed set`, `(${JSON.stringify(raw)}) — refusing the whole bucket rather than reading a standing deny as "no rule"`);
     }
     return behavior;
 }
+class BucketRefusedError extends Error {
+    verdict;
+    constructor(verdict, evidence) {
+        super(`${verdict} ${evidence}`);
+        this.verdict = verdict;
+    }
+}
 const WritablePersistedRuleSchema = PersistedRuleRowSchema.extend({ behavior: z.enum(RULE_BEHAVIORS) });
 const WritableRuleTombstoneSchema = RuleTombstoneSchema.extend({ behavior: z.enum(RULE_BEHAVIORS) });
 const FrontierSchema = z.record(z.string(), z.number().int().nonnegative().safe());
@@ -349,6 +356,64 @@ async function refusingUnreadableColumns(what, fn) {
         throw foldJsonColumn(e, (m) => `${m} — the ${what} does not carry a readable shape; refusing the whole of it rather than report a partial one`);
     }
 }
+function bucketRowColumns(dialect) {
+    return `actor, counter, rev, ${jsonColumnText(dialect, "rules_json")}, ${jsonColumnText(dialect, "tombstones_json")}, ${jsonColumnText(dialect, "quarantined_json")}, ${jsonColumnText(dialect, "observed_vector_json")}, checksum`;
+}
+function decodeBucketRow(ownerKey, row) {
+    const at = `${PERMISSION_RULE_TABLE} bucket ${ownerKey}`;
+    const rulesRaw = decodeJsonColumn(row.rules_json, readRulesJson, `${at}.rules_json`);
+    const tombstonesRaw = decodeJsonColumn(row.tombstones_json, readTombstonesJson, `${at}.tombstones_json`);
+    const quarantinedRaw = decodeJsonColumn(row.quarantined_json, readQuarantinedJson, `${at}.quarantined_json`);
+    const observedVector = row.observed_vector_json === null || row.observed_vector_json === undefined ? undefined : decodeJsonColumn(row.observed_vector_json, readObservedVectorJson, `${at}.observed_vector_json`);
+    const expected = buildRuleBucketChecksum({ rules: rulesRaw, tombstones: tombstonesRaw, quarantined: quarantinedRaw, ...(observedVector !== undefined ? { observedVector } : {}) });
+    if (String(row.checksum ?? "") !== expected) {
+        throw new BucketRefusedError(`permission_rule bucket ${ownerKey} failed its integrity check`, `(stored ${String(row.checksum)}, computed ${expected}) — refusing the whole bucket rather than reporting a partial rule set`);
+    }
+    const rules = rulesRaw.map((r) => ({ ...r, behavior: readBucketRowBehavior(r.behavior, "rule row", ownerKey) }));
+    const tombstones = tombstonesRaw.map((t) => ({ ...t, behavior: readBucketRowBehavior(t.behavior, "tombstone", ownerKey) }));
+    const quarantined = quarantinedRaw.map((q) => ({ ...q, behavior: readBucketRowBehavior(q.behavior, "quarantined row", ownerKey) }));
+    const badTombstone = tombstones.find((t) => {
+        const parsed = parseRuleText(t.rule, t.behavior);
+        return "reject" in parsed || parsed.rule.rule !== t.rule;
+    });
+    if (badTombstone !== undefined) {
+        throw new BucketRefusedError(`permission_rule bucket ${ownerKey} carries a tombstone whose rule text the single validator refuses or does not spell canonically`, `(${badTombstone.rule}) — refusing the whole bucket rather than keeping a rule alive under a tombstone that can never match it`);
+    }
+    const screened = screenRuleSyncState({ rules, tombstones });
+    if (screened.rejected.length > 0) {
+        const names = screened.rejected.map((r) => `${r.rule}(${r.reason})`).join(", ");
+        throw new BucketRefusedError(`permission_rule bucket ${ownerKey} carries rows the single validator refuses`, `[${names}] — refusing the whole bucket rather than authorizing a rule whose text and matcher metadata disagree`);
+    }
+    return {
+        actor: String(row.actor ?? ""),
+        counter: Number(row.counter ?? 0),
+        rev: Number(row.rev ?? 0),
+        rules,
+        tombstones,
+        quarantined,
+        ...(observedVector !== undefined ? { observedVector } : {}),
+    };
+}
+async function writeBucket(exec, dialect, ownerKey, cur, next, nowMs) {
+    const writable = z.object({ rules: z.array(WritablePersistedRuleSchema), tombstones: z.array(WritableRuleTombstoneSchema) }).safeParse(next);
+    if (!writable.success) {
+        throw new Error(`refusing to write a permission_rule bucket this backend could not read back: ${writable.error.message}`);
+    }
+    const body = { rules: next.rules, tombstones: next.tombstones, quarantined: cur.quarantined, ...(cur.observedVector !== undefined ? { observedVector: cur.observedVector } : {}) };
+    const enc = dialectProtocolJsonEncoder(dialect);
+    const affected = await exec(dialect === "tidb"
+        ? `UPDATE ${PERMISSION_RULE_TABLE} SET rules_json = ?, tombstones_json = ?, quarantined_json = ?, checksum = ?, rev = rev + 1, updated_at_ms = ? WHERE owner_key = ? AND rev = ?`
+        : `UPDATE ${PERMISSION_RULE_TABLE} SET rules_json = $1, tombstones_json = $2, quarantined_json = $3, checksum = $4, rev = rev + 1, updated_at_ms = $5 WHERE owner_key = $6 AND rev = $7`, [
+        enc(next.rules, "permission_rule.rules_json"),
+        enc(next.tombstones, "permission_rule.tombstones_json"),
+        enc(cur.quarantined, "permission_rule.quarantined_json"),
+        buildRuleBucketChecksum(body),
+        nowMs,
+        ownerKey,
+        cur.rev,
+    ]);
+    return affected === 1;
+}
 class SqlDurableRulePartition {
     db;
     owner;
@@ -372,47 +437,11 @@ class SqlDurableRulePartition {
         return refusingUnreadableColumns(`bucket ${this.ownerKey}`, () => this.readBucketRow());
     }
     async readBucketRow() {
-        const { rows } = await this.db.query(this.q(`SELECT actor, counter, rev, ${jsonColumnText("tidb", "rules_json")}, ${jsonColumnText("tidb", "tombstones_json")}, ${jsonColumnText("tidb", "quarantined_json")}, ${jsonColumnText("tidb", "observed_vector_json")}, checksum FROM ${PERMISSION_RULE_TABLE} WHERE owner_key = ?`, `SELECT actor, counter, rev, ${jsonColumnText("pg", "rules_json")}, ${jsonColumnText("pg", "tombstones_json")}, ${jsonColumnText("pg", "quarantined_json")}, ${jsonColumnText("pg", "observed_vector_json")}, checksum FROM ${PERMISSION_RULE_TABLE} WHERE owner_key = $1`), [this.ownerKey]);
+        const { rows } = await this.db.query(this.q(`SELECT ${bucketRowColumns("tidb")} FROM ${PERMISSION_RULE_TABLE} WHERE owner_key = ?`, `SELECT ${bucketRowColumns("pg")} FROM ${PERMISSION_RULE_TABLE} WHERE owner_key = $1`), [this.ownerKey]);
         const row = rows[0];
         if (row === undefined)
             return { ...EMPTY_BUCKET, rules: [], tombstones: [], quarantined: [] };
-        const at = `${PERMISSION_RULE_TABLE} bucket ${this.ownerKey}`;
-        const rulesRaw = decodeJsonColumn(row.rules_json, readRulesJson, `${at}.rules_json`);
-        const tombstonesRaw = decodeJsonColumn(row.tombstones_json, readTombstonesJson, `${at}.tombstones_json`);
-        const quarantinedRaw = decodeJsonColumn(row.quarantined_json, readQuarantinedJson, `${at}.quarantined_json`);
-        const observedVector = row.observed_vector_json === null || row.observed_vector_json === undefined ? undefined : decodeJsonColumn(row.observed_vector_json, readObservedVectorJson, `${at}.observed_vector_json`);
-        const expected = buildRuleBucketChecksum({ rules: rulesRaw, tombstones: tombstonesRaw, quarantined: quarantinedRaw, ...(observedVector !== undefined ? { observedVector } : {}) });
-        if (String(row.checksum ?? "") !== expected) {
-            throw new Error(`permission_rule bucket ${this.ownerKey} failed its integrity check (stored ${String(row.checksum)}, computed ${expected}) — ` +
-                `refusing the whole bucket rather than reporting a partial rule set`);
-        }
-        const rules = rulesRaw.map((r) => ({ ...r, behavior: readBucketRowBehavior(r.behavior, "rule row", this.ownerKey) }));
-        const tombstones = tombstonesRaw.map((t) => ({ ...t, behavior: readBucketRowBehavior(t.behavior, "tombstone", this.ownerKey) }));
-        const quarantined = quarantinedRaw.map((q) => ({ ...q, behavior: readBucketRowBehavior(q.behavior, "quarantined row", this.ownerKey) }));
-        const state = {
-            actor: String(row.actor ?? ""),
-            counter: Number(row.counter ?? 0),
-            rev: Number(row.rev ?? 0),
-            rules,
-            tombstones,
-            quarantined,
-            ...(observedVector !== undefined ? { observedVector } : {}),
-        };
-        const badTombstone = tombstones.find((t) => {
-            const parsed = parseRuleText(t.rule, t.behavior);
-            return "reject" in parsed || parsed.rule.rule !== t.rule;
-        });
-        if (badTombstone !== undefined) {
-            throw new Error(`permission_rule bucket ${this.ownerKey} carries a tombstone whose rule text the single validator refuses or does not spell canonically (${badTombstone.rule}) — ` +
-                `refusing the whole bucket rather than keeping a rule alive under a tombstone that can never match it`);
-        }
-        const screened = screenRuleSyncState({ rules, tombstones });
-        if (screened.rejected.length > 0) {
-            const names = screened.rejected.map((r) => `${r.rule}(${r.reason})`).join(", ");
-            throw new Error(`permission_rule bucket ${this.ownerKey} carries rows the single validator refuses [${names}] — ` +
-                `refusing the whole bucket rather than authorizing a rule whose text and matcher metadata disagree`);
-        }
-        return state;
+        return decodeBucketRow(this.ownerKey, row);
     }
     async ensureBucket() {
         const nowMs = this.now();
@@ -500,22 +529,8 @@ class SqlDurableRulePartition {
                     throw new Error(`the SQL permission-rule backend was handed a write delta it does not know: ${JSON.stringify(unknown)}`);
                 }
             }
-            const writable = z.object({ rules: z.array(WritablePersistedRuleSchema), tombstones: z.array(WritableRuleTombstoneSchema) }).safeParse({ rules: nextRules, tombstones: nextTombstones });
-            if (!writable.success) {
-                throw new Error(`refusing to write a permission_rule bucket this backend could not read back: ${writable.error.message}`);
-            }
-            const body = { rules: nextRules, tombstones: nextTombstones, quarantined: cur.quarantined, ...(cur.observedVector !== undefined ? { observedVector: cur.observedVector } : {}) };
-            const nowMs = this.now();
-            const { affected } = await this.db.query(this.q(`UPDATE ${PERMISSION_RULE_TABLE} SET rules_json = ?, tombstones_json = ?, quarantined_json = ?, checksum = ?, rev = rev + 1, updated_at_ms = ? WHERE owner_key = ? AND rev = ?`, `UPDATE ${PERMISSION_RULE_TABLE} SET rules_json = $1, tombstones_json = $2, quarantined_json = $3, checksum = $4, rev = rev + 1, updated_at_ms = $5 WHERE owner_key = $6 AND rev = $7`), [
-                this.enc(nextRules, "permission_rule.rules_json"),
-                this.enc(nextTombstones, "permission_rule.tombstones_json"),
-                this.enc(cur.quarantined, "permission_rule.quarantined_json"),
-                buildRuleBucketChecksum(body),
-                nowMs,
-                this.ownerKey,
-                opts.expectedRev,
-            ]);
-            if (affected === 0) {
+            const landed = await writeBucket(async (sql, params) => (await this.db.query(sql, params)).affected, this.db.dialect, this.ownerKey, cur, { rules: nextRules, tombstones: nextTombstones }, this.now());
+            if (!landed) {
                 const again = await this.read();
                 return { conflict: true, rev: again.rev };
             }
@@ -766,6 +781,98 @@ 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, now = Date.now) {
+    const acc = { removed: [], bucketsDeferred: 0, bucketsUnreadable: [] };
+    try {
+        await purgeAllBuckets(db, dialect, now, acc);
+    }
+    catch (e) {
+        if (acc.removed.length === 0)
+            throw e;
+        throw new Error(`the one-time removal of persisted permission rules whose scope the engine refuses failed AFTER removing ${acc.removed.length} row(s) — record them before retrying: ` +
+            acc.removed.map((r) => `${r.kind} in bucket ${r.ownerKey} (${r.behavior} ${r.tool}, scope root ${JSON.stringify(r.scopeRoot)})`).join("; ") +
+            `. Underlying failure: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+    }
+    return acc;
+}
+async function purgeAllBuckets(db, dialect, now, acc) {
+    const cols = `owner_key, ${bucketRowColumns(dialect)}`;
+    let after = "";
+    for (;;) {
+        const page = await db.rows(dialect === "tidb"
+            ? `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":
+                        acc.removed.push(...outcome.rows);
+                        settled = true;
+                        break;
+                    case "unreadable":
+                        acc.bucketsUnreadable.push({ ownerKey, why: outcome.why });
+                        settled = true;
+                        break;
+                    case "clean":
+                        settled = true;
+                        break;
+                    case "conflict":
+                        row = (await db.rows(dialect === "tidb" ? `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)
+                acc.bucketsDeferred += 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 = (tidb, pg) => (db.dialect === "tidb" ? tidb : pg);
     return {

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

@@ -152,6 +152,12 @@ export declare class RemoteDeviceExecutionEnv implements RemoteExecutionEnv {
     private absentGuardFaces;
     private driftError;
     private resolve;
+    /**
+     * exec / execStream 指令帧的 `cwd` —— **恒填、恒绝对**的唯一铸点(协议文档 §3.1:executor 不再有「缺席时按
+     * 隐含工作目录」的第二种读法)。调用方没给 ⇒ env 的 cwd(铸造时已由 {@link effectiveDeviceCwd} 保证绝对);
+     * 给了 ⇒ 按同一只 {@link resolve} 解成绝对。其余指令 kind 的路径参数在下发前就已是绝对路径,不带 `cwd`。
+     */
+    private instructionCwd;
     absolutePath(p: string): Promise<Result<string, FileError>>;
     joinPath(parts: string[]): Promise<Result<string, FileError>>;
     workspaceHandle(): WorkspaceHandle;
@@ -321,8 +327,13 @@ export declare function deviceExecutionEnvFactory(deps: DeviceEnvFactoryDeps): E
  * §4.3.3 的 cwd 优先序 —— 与 host 腿的 `effectiveHostWorkspace` **同源**:
  *   ① 本 session 显式注册的 cwd(`deviceCwdHonored` 闸下由 resolve-spec 写);
  *   ② `ctx.parentCwd`(委派子代:自己没注册过 cwd,继承父的工作目录 —— 少了它子代会丢工作目录);
- *   ③ 设备 hello 声明并落库的 `workspaceRoot`(缺 cwd 时的解析基准,有明确 wire 契约,不是「executor
+ *   ③ 设备入籍时登记并落库的 `workspaceRoot`(缺 cwd 时的解析基准,有明确 wire 契约,不是「executor
  *      默认根」这种空话)。
+ *
+ * 🔴 **这一只解析源同时守它的后置条件:结果必是 POSIX 绝对路径,否则响亮抛。** 协议文档对 executor 的承诺是
+ * 「exec / execStream 的指令帧恒带绝对 `cwd`」—— 不带或带相对的,都会把「用哪个目录」这件事留给 executor
+ * 自己猜(同一个事实两种读法)。判据是入籍口那**同一只**谓词 `isDeviceAbsolutePath`(`device-store.ts`):入籍口用它拒相对的
+ * `workspaceRoot`;这里的判留作存量行守卫(入籍口收紧之前落库的相对根)并守另两个来源 —— 委派链的父 cwd 来自引擎,不经入籍口。
  */
 export declare function effectiveDeviceCwd(sessionCwd: string | undefined, parentCwd: string | undefined, row: Pick<DeviceRow, "workspaceRoot">): string;
 export {};

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, } from "../device-store.js";
+import { DEVICE_ERROR_CODES, isDeviceAbsolutePath, } from "../device-store.js";
 export const DEVICE_PROVIDER = "device";
 const ok = (value) => ({ ok: true, value });
 const STREAM_PENDING_MAX_BYTES = 2 * 1024 * 1024;
@@ -166,7 +166,10 @@ export class RemoteDeviceExecutionEnv {
             "performing a NON-atomic write here is exactly the silent downgrade guarded writes exist to prevent (#157). Refusing; the per-task factory mints a correctly-shaped env on the next task.", absPath);
     }
     resolve(p) {
-        return posix.isAbsolute(p) ? posix.normalize(p) : posix.normalize(posix.join(this.cwd, p));
+        return isDeviceAbsolutePath(p) ? posix.normalize(p) : posix.normalize(posix.join(this.cwd, p));
+    }
+    instructionCwd(requested) {
+        return requested === undefined ? this.cwd : this.resolve(requested);
     }
     async absolutePath(p) {
         return ok(this.resolve(p));
@@ -354,7 +357,7 @@ export class RemoteDeviceExecutionEnv {
         const res = await this.dispatch("exec", { command }, {
             timeoutMs: this.timeoutMsFor(options?.timeout),
             ...(options?.abortSignal === undefined ? {} : { signal: options.abortSignal }),
-            cwd: options?.cwd === undefined ? this.cwd : this.resolve(options.cwd),
+            cwd: this.instructionCwd(options?.cwd),
             ...(mergedEnv(this.cfg.shellEnv, options?.env) === undefined ? {} : { shellEnv: mergedEnv(this.cfg.shellEnv, options?.env) }),
             onChunk: (c) => {
                 if (c.kind === "stdout") {
@@ -430,7 +433,7 @@ export class RemoteDeviceExecutionEnv {
         const settled = this.dispatch("execStream", { command }, {
             timeoutMs: this.timeoutMsFor(options?.timeout),
             signal: inner.signal,
-            cwd: options?.cwd === undefined ? this.cwd : this.resolve(options.cwd),
+            cwd: this.instructionCwd(options?.cwd),
             ...(mergedEnv(this.cfg.shellEnv, options?.env) === undefined ? {} : { shellEnv: mergedEnv(this.cfg.shellEnv, options?.env) }),
             onChunk: (c) => {
                 if (!accepting) {
@@ -811,6 +814,11 @@ export function deviceExecutionEnvFactory(deps) {
     };
 }
 export function effectiveDeviceCwd(sessionCwd, parentCwd, row) {
-    return sessionCwd ?? parentCwd ?? row.workspaceRoot;
+    const [source, cwd] = sessionCwd !== undefined ? ["session cwd", sessionCwd] : parentCwd !== undefined ? ["parent cwd", parentCwd] : ["device workspaceRoot", row.workspaceRoot];
+    if (!isDeviceAbsolutePath(cwd)) {
+        throw new Error(`device lane: the effective working directory (${source}) ${JSON.stringify(cwd)} is not an absolute path — every exec / execStream instruction carries an absolute \`cwd\`, ` +
+            "and the executor must never be left to guess a base directory. Fix the source named above (a device's workspaceRoot is fixed at enrollment: enroll again with an absolute path)");
+    }
+    return cwd;
 }
 //# sourceMappingURL=remote-env-device.js.map

package/dist/plugins/scheduler-support.d.ts

@@ -26,8 +26,11 @@ type Caps = SchedulerCapability["schedulerCapabilities"];
  * cron via core `isValidCronExpr` (RCE-safe, no shell-exec); delay/at bounded by minDelaySec + horizon.
  */
 export declare function validateIntent(intent: ScheduledIntent, caps: Caps, nowMs: number): SchedulerError | null;
-/** The default shared store path: `SEMA_CONFIG_DIR` → `~/.sema`, file `scheduled_tasks.json` (server + shell agree). */
-export declare function defaultSchedulerStorePath(): string;
+/** The default shared store path: the configuration root (the `agentConfigDir` seat `loadConfig` minted from `SEMA_CONFIG_DIR`, else `~/.sema`),
+ *  file `scheduled_tasks.json` (server + shell agree). Reads the seat, never `process.env` at call time. */
+export declare function defaultSchedulerStorePath(config: {
+    readonly agentConfigDir?: string;
+}): string;
 /**
  * File-backed SchedulerCapability (durable across daemon restarts). Store = a single JSON file (atomic write via
  * the registry-core /node binding). The resident shell daemon reads the same store to fire intents. `now`
@@ -37,8 +40,9 @@ export declare class FileSchedulerBackend implements SchedulerCapability {
     readonly schedulerCapabilities: Caps;
     private readonly storePath;
     private readonly now;
-    constructor(opts?: {
-        storePath?: string;
+    /** `storePath` 必填:路径是装配层从配置定的事实(`SCHEDULER_STORE_PATH` ?? {@link defaultSchedulerStorePath}),本类不自己找缺省。 */
+    constructor(opts: {
+        storePath: string;
         caps?: Partial<Caps>;
         now?: () => number;
     });

package/dist/plugins/scheduler-support.js

@@ -1,8 +1,8 @@
 import { join } from "node:path";
-import { homedir } from "node:os";
 import { randomBytes, createHash } from "node:crypto";
 import { SchedulerError, isValidCronExpr } from "@sema-agent/core";
 import { loadSchedulerStore, saveSchedulerStore } from "@sema-agent/settings-schema/node";
+import { configRootOf } from "../sema-config-dir.js";
 const ok = (value) => ({ ok: true, value });
 const err = (error) => ({ ok: false, error });
 export const DEFAULT_SCHEDULER_CAPS = {
@@ -59,16 +59,16 @@ function computeNextRunMs(when, nowMs) {
         return nowMs + when.delaySec * 1000;
     return undefined;
 }
-export function defaultSchedulerStorePath() {
-    return join(process.env.SEMA_CONFIG_DIR ?? join(homedir(), ".sema"), "scheduled_tasks.json");
+export function defaultSchedulerStorePath(config) {
+    return join(configRootOf(config), "scheduled_tasks.json");
 }
 export class FileSchedulerBackend {
     schedulerCapabilities;
     storePath;
     now;
-    constructor(opts = {}) {
+    constructor(opts) {
         this.schedulerCapabilities = { ...DEFAULT_SCHEDULER_CAPS, ...(opts.caps ?? {}) };
-        this.storePath = opts.storePath ?? defaultSchedulerStorePath();
+        this.storePath = opts.storePath;
         this.now = opts.now ?? (() => Date.now());
     }
     load() {

package/dist/rule-entry-list.d.ts

@@ -21,7 +21,6 @@
  */
 import { compileAllowList } from "@sema-agent/core";
 import { emptyToolSegmentOf } from "./namespaced-rule-name.js";
-export declare function presentRuleEntry(entry: string): string;
 /** ① 形:字符串数组(空串也是字符串 —— 引擎把它读成 `grammar` 并通告 / 拒,见 ③)。 */
 export declare const ruleEntryListShapeOk: (v: unknown) => v is readonly string[];
 /**

package/dist/rule-entry-list.js

@@ -1,11 +1,6 @@
 import { compileAllowList } from "@sema-agent/core";
+import { displayListEntry } from "./list-entry-display.js";
 import { describeEmptyToolSegment, emptyToolSegmentOf, NO_DECLARED_TOOL_NAMES, ruleEntryToolName } from "./namespaced-rule-name.js";
-import { CONTROL_AND_BIDI_STRIP_RE } from "./text-bidi.js";
-const PRESENTED_ENTRY_MAX = 160;
-export function presentRuleEntry(entry) {
-    const clean = entry.replace(CONTROL_AND_BIDI_STRIP_RE, "");
-    return clean.length <= PRESENTED_ENTRY_MAX ? clean : `${clean.slice(0, PRESENTED_ENTRY_MAX)}…(${entry.length} chars)`;
-}
 export const ruleEntryListShapeOk = (v) => Array.isArray(v) && v.every((x) => typeof x === "string");
 export const MAX_ALLOW_LAYER_ENTRIES = 1_000;
 export function describeAllowLayerOverCap(field, count) {
@@ -26,14 +21,14 @@ export function emptyToolSegmentEntryOf(list) {
     return undefined;
 }
 export function describeEmptyToolSegmentEntry(field, u) {
-    return `${field} names "${presentRuleEntry(u.entry)}", which can never match a tool (${describeEmptyToolSegment(u.ns)})`;
+    return `${field} names ${displayListEntry(u.entry)}, which can never match a tool (${describeEmptyToolSegment(u.ns)})`;
 }
 export function inertRuleEntriesOf(list, behavior) {
     return compileAllowList(list, behavior, NO_DECLARED_TOOL_NAMES).inert;
 }
 export function inertRuleEntryGuidance(i) {
     const reason = i.reason;
-    const write = i.currentName !== undefined ? ` — write "${presentRuleEntry(i.currentName)}"` : "";
+    const write = i.currentName !== undefined ? ` — write ${displayListEntry(i.currentName)}` : "";
     switch (reason) {
         case "tool_name":
             return `the tool name can never match a mounted tool (${i.verdict ?? "stale"})${write}`;
@@ -58,7 +53,7 @@ export function inertRuleEntryGuidance(i) {
     }
 }
 export function describeInertRuleEntries(field, inert) {
-    return inert.map((i) => `${field} entry "${presentRuleEntry(i.entry)}" reads as nothing (${i.reason}): ${inertRuleEntryGuidance(i)}`).join("; ");
+    return inert.map((i) => `${field} entry ${displayListEntry(i.entry)} reads as nothing (${i.reason}): ${inertRuleEntryGuidance(i)}`).join("; ");
 }
 const isPlainRecord = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 function skillDenyInertSentence(skill) {

package/dist/rules-consent.d.ts

@@ -163,7 +163,7 @@ export interface LocalImportRuleKey {
  * 它在端点上先判、有自己的整句文案,而且判完就把类型收窄掉(`permission-rule-vocab.ts` 的
  * `DIRECT_RULE_WRITE_ADMITS`)⇒ 放宽态根本到不了本表所服务的那段代码。 */
 export type LocalImportRefusalCode = 
-/** scope 串读不出形(既不是 `global` 也不是 `project:<非空 root>`)。 */
+/** scope 串读不出形,或读出来的 scope 引擎的 durable 谓词不收(既不是 `global` 也不是 `project:<绝对 root>`;判据 = {@link parseRuleScope})。 */
 "scope_unreadable"
 /** scope 的 project root 里有 bidi 控制符([ref]② Trojan Source 族):人看到的射程与机器判据用的
  *  射程不是同一串 —— 一条规则的**作用范围**因此可以被伪装。 */
@@ -480,7 +480,7 @@ export declare function serializeRuleScope(scope: RuleScope): string;
  * 各挑各的」这件事本身,不是把某个数字调大一点)。
  *
  * 病:铸侧 `cardRuleScopeRoot` 对 root 长度零把关(入口尺 = `isValidCwd` 的 {@link MAX_CWD_CHARS}),
- * core 与两个店都只校验 `root.min(1)` ⇒ 写面全程无阻;而 `DELETE /v1/rules` 的体 schema 此前独立写死
+ * core 与两个店都不设 root 长度上限 ⇒ 写面全程无阻;而 `DELETE /v1/rules` 的体 schema 此前独立写死
  * `scope: max(1088)`,且 safeParse 排在 `parseRuleScope`/权限判据**之前** ⇒ 超限 root 的规则
  * `GET /v1/rules` **列得出**、按同一串 DELETE **恒 400**。全仓只有一个 `lane.removeRule` 调用点(直删
  * 店行是无墓碑硬删、会被 sync 的 join 复活),所以那是**一条已列出的常驻放行规则在受支持接口上不可撤**;
@@ -502,8 +502,17 @@ export type DurableRuleScope = Exclude<RuleScope, {
     kind: "session";
 }>;
 /** {@link serializeRuleScope} 的逆。读不出形 ⇒ `undefined`(调用方 400,绝不猜一个 global 出来 ——
- *  猜 global 会把一次「删项目内规则」的请求变成一次删不掉任何东西的 no-op,或者更糟)。 */
+ *  猜 global 会把一次「删项目内规则」的请求变成一次删不掉任何东西的 no-op,或者更糟)。
+ *
+ *  🔴 **收不收只有一只判据:core 的 `isValidDurableScope`**(引擎 7.46.0 起 project root 必须是完整绝对路径:`/…`、`X:\…` /
+ *  `X:/…`、`\\host\…`)。四个 wire 入口(`/v1/rules` 写 / 撤 / 列举过滤、local-import 的行)都经这里;cc-import 的层 root 调同一只
+ *  谓词(`http/routes/rules.ts`)。修前这里手抄了一份「root 非空」:`project:myproj` 本仓收、引擎写臂拒(写口答 503「再发一次」——
+ *  客户端会无限重试)、引擎读侧丢(撤销口删不动),一条规则在两侧是两种命运。存量的那种行由一次性迁移 M11 删
+ *  (`plugins/one-time-migrations.ts` 登记表)。 */
 export declare function parseRuleScope(text: string): DurableRuleScope | undefined;
+/** 引擎不收的 scope(或 cc-import 层 root)的**唯一一句**拒句:写 / 撤 / 列举过滤三个路由口、cc-import 预览的层 root、local-import 的成员拒因
+ *  `scope_unreadable` 都出站这一只(各口的码照旧各自的),不在读点各抄一份。 */
+export declare const RULE_SCOPE_REFUSAL_SENTENCE = "scope must be 'global' or 'project:<root>' with an absolute root";
 /** 一条规则在 wire 上的行 = 一个逻辑 (rule, scope) 对([ref] v2 §6 F5)。
  *  `adds` **如实上 wire**、不折叠成单值:同一条规则可以被批准过多次(不同 dot、不同来源、不同时刻),
  *  折成「一个 addedAt」会让「这条规则是我导入的还是我点过卡的」在治理面上不可分。 */