@sema-agent/server 7.118.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/plugins/snapshot-bucket-presence.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 对象存储配了快照桶却**不存在** = 部署错 —— boot 期核**一次**,缺 ⇒ 响亮拒启(不是每一拍 sweep 一条静默的 404)。
+ *
+ * ## 病
+ * `SESSION_SNAPSHOT_BUCKET`(缺省 `session-snapshots`)是 snapshot-BLOB offload 与 SendUserFile 私有 presigned 轨 / 沙箱 staging 的桶。server 不建桶
+ * (`docs/DEPLOY-PREREQS.md`「对象存储桶」),sema-up 的建桶清单又漏过它 ⇒ 起服绿,之后每一次对象写、每一拍孤儿 sweep 的列举(每分钟)都是
+ * 404 NoSuchBucket —— 运维读到的是一串「失败的请求」,不是「桶没建」。
+ *
+ * ## 形(一条规则,不加特例)
+ *  · 核的是 {@link MinioBlobBackend.probeBucket}(presigned 列举 `max-keys=1`);**只有** 404 + `NoSuchBucket` 是「缺」,其余证明不了的形(连不上 / 403 / 5xx / 没有
+ *    NoSuchBucket 的 404)⇒ **不拒**、照常起服,走登记过的 F 类兜底口 `recordFailOpen("server.snapshot-bucket.presence-unproven")`(计数 + 探针行 + 记录器的一次性 warn;
+ *    三问写在该 tag 的 note 里)—— 拒启要有证据,没有证据只留痕;
+ *  · 缺 = 配置好的店资源还没就绪,与「库连不上」同一类处境:在 `STORE_LOCK_WAIT_MS` 窗内重试({@link openWithinWait},同一只窗、同一只节拍、同一条窗尾规则 —— 编排里
+ *    建桶晚于 server 起是常态),到窗时手上有缺桶的证据 ⇒ 拒启,拒句点名桶名、`MINIO_ENDPOINT` 的显示安全形(`buildDisplaySafeUrl` 的产物:userinfo 落地、
+ *    query 值成记号,不带密钥)与出路;探针从头到尾没答过(每一次都挂到窗尾)⇒ 同样是「证明不了」,走上面那只兜底口、照常起服。
+ *  · 只核**快照桶**(`config.snapshotBlobStore.bucket`;SendUserFile 的私桶缺省同一只);公桶 `sema-public` 是运维另配的匿名桶,不在本核之内。
+ */
+import type { ServiceConfig } from "../config-types.js";
+import { type StoreOpenWaitClock } from "./store-open-wait.js";
+type SnapshotBlobStoreConfig = NonNullable<ServiceConfig["snapshotBlobStore"]>;
+/** boot 期单次探针的上界(ms):黑洞端点(丢包不拒连)不许把起服拖到对象存储 IO 的 120s;到点 ⇒ `unknown`(证明不了缺桶 ⇒ 不拒、报一次)。 */
+export declare const SNAPSHOT_BUCKET_PROBE_TIMEOUT_MS = 10000;
+/** 缺桶的拒启句(唯一铸点)。 */
+/** @param endpoint `MINIO_ENDPOINT` 的**显示安全形**(调用方过 {@link buildDisplaySafeUrl};本函数不碰原串)。 */
+export declare function buildSnapshotBucketRefusal(bucket: string, endpoint: string, waitedMs: number): string;
+/** 探针到窗尾一次都没答过时,兜底口 detail 里的成因(证明不了缺桶的一形)。 */
+export declare const SNAPSHOT_BUCKET_PROBE_PENDING = "probe still pending when the window ended";
+/**
+ * boot 期核一次快照桶(`boot/stores.ts`)。缺桶 ⇒ 窗内重试、到窗拒启;证明不了 ⇒ 兜底口留痕、照常起服。
+ * @param waitMs `config.storeLockWaitMs`。`0` ⇒ 只核一次(缺就当场拒)。
+ */
+export declare function ensureSnapshotBucket(store: SnapshotBlobStoreConfig, waitMs: number, logger: {
+    warn(msg: string, meta?: Record<string, unknown>): void;
+}, clock?: StoreOpenWaitClock): Promise<void>;
+export {};
+//# sourceMappingURL=snapshot-bucket-presence.d.ts.map

package/dist/plugins/snapshot-bucket-presence.js

@@ -0,0 +1,40 @@
+import { buildDisplaySafeUrl } from "../trace/redact.js";
+import { MinioBlobBackend } from "./blob-backend.js";
+import { recordFailOpen } from "../observability/fail-open.js";
+import { isStoreOpenWindowExpired, openWithinWait } from "./store-open-wait.js";
+export const SNAPSHOT_BUCKET_PROBE_TIMEOUT_MS = 10_000;
+class SnapshotBucketMissing extends Error {
+    constructor() {
+        super("snapshot bucket missing");
+    }
+}
+export function buildSnapshotBucketRefusal(bucket, endpoint, waitedMs) {
+    const waited = waitedMs > 0 ? `after retrying for ${waitedMs}ms (STORE_LOCK_WAIT_MS)` : "on the first check (STORE_LOCK_WAIT_MS=0: no wait)";
+    return (`Object storage is configured (MINIO_ENDPOINT → ${endpoint}) but the snapshot bucket "${bucket}" (SESSION_SNAPSHOT_BUCKET; default session-snapshots) does not exist there ${waited} — refusing to boot: ` +
+        `the server never creates buckets, so every snapshot-offload write and SendUserFile private-track request would answer 404 NoSuchBucket (and the orphan sweep would log one every minute, forever). ` +
+        `Next: create the bucket (mc mb <alias>/${bucket}; this version's sema-up scripts create it — re-run them on an existing sema-up deployment), or set SESSION_SNAPSHOT_BUCKET to a bucket that exists.`);
+}
+export const SNAPSHOT_BUCKET_PROBE_PENDING = "probe still pending when the window ended";
+export async function ensureSnapshotBucket(store, waitMs, logger, clock) {
+    const probe = new MinioBlobBackend({ endpoint: store.endpoint, bucket: store.bucket, accessKey: store.accessKey, secretKey: store.secretKey, ...(store.region ? { region: store.region } : {}), ...(store.keyPrefix ? { keyPrefix: store.keyPrefix } : {}) });
+    let verdict;
+    try {
+        verdict = await openWithinWait(async () => {
+            const r = await probe.probeBucket(SNAPSHOT_BUCKET_PROBE_TIMEOUT_MS);
+            if (r.state === "missing")
+                throw new SnapshotBucketMissing();
+            return r;
+        }, waitMs, (w) => logger.warn("snapshot_bucket_wait", { bucket: store.bucket, endpoint: buildDisplaySafeUrl(store.endpoint), waitMs: w.waitMs, error: w.error }), clock);
+    }
+    catch (err) {
+        if (err instanceof SnapshotBucketMissing)
+            throw new Error(buildSnapshotBucketRefusal(store.bucket, buildDisplaySafeUrl(store.endpoint), waitMs), { cause: err });
+        if (!isStoreOpenWindowExpired(err))
+            throw err;
+        verdict = { state: "unknown", detail: SNAPSHOT_BUCKET_PROBE_PENDING };
+    }
+    if (verdict.state === "unknown") {
+        recordFailOpen("server.snapshot-bucket.presence-unproven", `bucket=${store.bucket} endpoint=${buildDisplaySafeUrl(store.endpoint)} ${verdict.detail}`);
+    }
+}
+//# sourceMappingURL=snapshot-bucket-presence.js.map