@sema-agent/server 7.118.0 → 7.120.0

package/dist/plugins/local-session-store.js

@@ -1,13 +1,17 @@
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
-import { SessionError, validateEntriesForImport } from "@sema-agent/core";
+import { FileSessionRepo, SessionError, validateEntriesForImport } from "@sema-agent/core";
+import { z } from "zod";
 import { contentForkRelation, fastForwardSharedContentDiverged, identicalIdsAlsoIdenticalContent } from "../session-sync-content.js";
 import { quarantineUnreadableSidecar } from "./local-sidecar-quarantine.js";
-import { decodeJsonColumn, readStringRecordColumn, SqlJsonColumnError } from "./sql-json-column.js";
+import { createZodColumnReader, decodeJsonColumn, readStringRecordColumn, SqlJsonColumnError } from "./sql-json-column.js";
+import { ONE_TIME_MIGRATIONS, migrationWindowOpen } from "./one-time-migrations.js";
+import { createLogger } from "../observability/logger.js";
 import { UNMANAGED_RETENTION } from "./retention-store-sql.js";
 import { carriedIncarnation, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
 import { decodeInstructionSource, encodeInstructionSource, sameInstructionSourceBaseline } from "../instruction-source-notice.js";
-import { openSessionForItself } from "../session-records-skipped-notice.js";
+import { noteReplayInSessionOpenScope, openSessionForItself } from "../session-records-skipped-notice.js";
+import { createCorruptReadFailOpenSeat } from "../observability/corrupt-read-seat.js";
 import { classifySyncRelationshipByIds, SyncConflictError, stagingIdFor, } from "../session-sync-kernel.js";
 const ownerEq = (a, b) => (a ?? null) === (b ?? null);
 const isNotFound = (e) => e instanceof SessionError && e.code === "not_found";
@@ -30,18 +34,32 @@ function userText(entry) {
     }
     return null;
 }
-const SIDECAR_DEGRADES = { lastActivity: "recency", title: "auto-title", "instruction-source": "instruction-source baseline", incarnation: "session-incarnation (the write that needed it failed loudly)" };
+const SIDECAR_DEGRADES = { lastActivity: "recency", title: "auto-title", "instruction-source": "instruction-source baseline", "session-meta": "session owner + incarnation (the write that needed it failed loudly)" };
+function readSessionMetaCell(cell) {
+    return typeof cell === "string" ? { incarnation: cell, owner: undefined } : cell;
+}
+const ownerRecorded = (cell) => cell !== undefined && readSessionMetaCell(cell).owner !== undefined;
+const SESSION_META_SIDECAR = z.record(z.string(), z.union([z.string(), z.object({ incarnation: z.string(), owner: z.string().nullable() }).strict()]));
+const readSessionMetaSidecar = createZodColumnReader(SESSION_META_SIDECAR);
+function ownerClaimWindowOpen() {
+    const window = ONE_TIME_MIGRATIONS.find((w) => w.id === "M10");
+    if (window === undefined)
+        throw new Error("LocalSessionStore: the one-time migration registry has no M10 row (the local session-owner claim window) — the claim arm outlived its registry row; delete it with that row");
+    return migrationWindowOpen(window, new Date().toISOString().slice(0, 10));
+}
 const SIDECAR_MAP_STATE_BY_PATH = new Map();
-class SidecarStringMap {
+class SidecarMap {
     path;
     label;
+    read;
     onUnreadable;
     onWriteFailed;
     strict;
     own = { entries: new Map(), writeChain: Promise.resolve() };
-    constructor(path, label, onUnreadable, onWriteFailed, strict = false) {
+    constructor(path, label, read, onUnreadable, onWriteFailed, strict = false) {
         this.path = path;
         this.label = label;
+        this.read = read;
         this.onUnreadable = onUnreadable;
         this.onWriteFailed = onWriteFailed;
         this.strict = strict;
@@ -59,7 +77,7 @@ class SidecarStringMap {
         if (!st.loaded) {
             st.loaded = (async () => {
                 try {
-                    const parsed = decodeJsonColumn(await readFile(path, "utf8"), readStringRecordColumn, this.label);
+                    const parsed = decodeJsonColumn(await readFile(path, "utf8"), this.read, this.label);
                     for (const [id, v] of Object.entries(parsed)) {
                         if (!st.entries.has(id))
                             st.entries.set(id, v);
@@ -73,45 +91,60 @@ class SidecarStringMap {
                         return;
                     }
                     const kind = e instanceof SqlJsonColumnError ? e.problem : (e?.code ?? "unreadable");
-                    throw new Error(`${this.label} is unreadable (${kind}) — refusing to read or mint session incarnations until it is repaired: a replacement ` +
-                        `token for an existing session would make it a different occupant (its memory opt-out would stop binding it), and a write ` +
-                        `would overwrite the unreadable bytes. The file is left in place at ${path}.`);
+                    throw new Error(`${this.label} is unreadable (${kind}) — refusing to read or write session owners and incarnations until it is repaired: ` +
+                        `reading it as empty would turn every session ownerless, and a replacement incarnation token for an existing session would ` +
+                        `make it a different occupant (its memory opt-out would stop binding it); a write would overwrite the unreadable bytes. ` +
+                        `The file is left in place at ${path}.`);
                 }
             })();
         }
         return st.loaded;
     }
     persist() {
-        return this.commit(() => () => undefined);
+        return this.commit(() => true);
     }
     commit(change) {
         const path = this.path;
         const st = this.state;
         const link = st.writeChain.then(async () => {
-            const undo = change(st.entries);
-            if (undo === undefined || !path)
-                return true;
-            try {
-                const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
-                await writeFile(tmp, JSON.stringify(Object.fromEntries(st.entries)), "utf8");
-                await rename(tmp, path);
+            const base = new Map(st.entries);
+            const draft = new Map(base);
+            if (!change(draft))
                 return true;
+            if (path) {
+                try {
+                    const tmp = `${path}.tmp-${process.pid}-${Date.now()}`;
+                    await writeFile(tmp, JSON.stringify(Object.fromEntries(draft)), "utf8");
+                    await rename(tmp, path);
+                }
+                catch (e) {
+                    this.onWriteFailed(e);
+                    return false;
+                }
             }
-            catch (e) {
-                undo();
-                this.onWriteFailed(e);
-                return false;
+            for (const key of new Set([...base.keys(), ...draft.keys()])) {
+                if (draft.has(key) === base.has(key) && draft.get(key) === base.get(key))
+                    continue;
+                if (draft.has(key))
+                    st.entries.set(key, draft.get(key));
+                else
+                    st.entries.delete(key);
             }
+            return true;
         });
         st.writeChain = link.then(() => undefined);
         return link;
     }
 }
+export function createLocalSessionRepo(root) {
+    return new FileSessionRepo(root, {
+        onCorruptRead: createCorruptReadFailOpenSeat("server.session-repo.corrupt-record-skipped", noteReplayInSessionOpenScope),
+    });
+}
 export class LocalSessionStore {
     repo;
     retention = UNMANAGED_RETENTION;
     pending = new Map();
-    owners = new Map();
     lastActivity = new Map();
     lastTaskRun = new Map();
     stagings = new Map();
@@ -124,48 +157,63 @@ export class LocalSessionStore {
     sidecarPath;
     titles;
     instructionSources;
-    incarnations;
-    constructor(repo, dataDir) {
+    meta;
+    log;
+    constructor(repo, dataDir, opts) {
         this.repo = repo;
         this.sidecarPath = dataDir ? join(dataDir, "session-last-activity.json") : undefined;
-        const sidecar = (file, which, strict = false) => new SidecarStringMap(dataDir ? resolve(join(dataDir, file)) : undefined, `${file} (the local ${which} sidecar)`, (path, e) => this.refuseSidecar(path, `LocalSessionStore ${which} sidecar`, e, which), (e) => this.warnSidecar("write", e, which), strict);
-        this.titles = sidecar("session-titles.json", "title");
-        this.instructionSources = sidecar("session-instruction-sources.json", "instruction-source");
-        this.incarnations = sidecar("session-incarnations.json", "incarnation", true);
-    }
-    async writeIncarnation(sessionId, next) {
-        await this.incarnations.ensureLoaded();
-        const committed = await this.incarnations.commit((entries) => {
-            const before = entries.get(sessionId);
-            const value = next(before);
-            if (value === undefined || value === before)
-                return undefined;
-            entries.set(sessionId, value);
-            return () => {
-                if (before === undefined)
-                    entries.delete(sessionId);
-                else
-                    entries.set(sessionId, before);
-            };
+        this.log = opts?.log ?? createLogger();
+        const sidecar = (file, which, read, strict = false) => new SidecarMap(dataDir ? resolve(join(dataDir, file)) : undefined, `${file} (the local ${which} sidecar)`, read, (path, e) => this.refuseSidecar(path, `LocalSessionStore ${which} sidecar`, e, which), (e) => this.warnSidecar("write", e, which), strict);
+        this.titles = sidecar("session-titles.json", "title", readStringRecordColumn);
+        this.instructionSources = sidecar("session-instruction-sources.json", "instruction-source", readStringRecordColumn);
+        this.meta = sidecar("session-incarnations.json", "session-meta", readSessionMetaSidecar, true);
+    }
+    async writeMeta(sessionId, next) {
+        await this.meta.ensureLoaded();
+        let changed = false;
+        const committed = await this.meta.commit((draft) => {
+            const value = next(draft.get(sessionId));
+            if (value === undefined)
+                return false;
+            draft.set(sessionId, value);
+            changed = true;
+            return true;
         });
         if (!committed)
-            throw new SessionError("storage", `LocalSessionStore: session-incarnation sidecar write failed for session ${sessionId} — nothing was recorded`);
+            throw new SessionError("storage", `LocalSessionStore: session-meta sidecar write failed for session ${sessionId} — nothing was recorded`);
+        return changed;
     }
-    mintIncarnation(sessionId) {
-        return this.writeIncarnation(sessionId, () => mintSessionIncarnation());
+    async dropMeta(sessionId) {
+        await this.meta.ensureLoaded();
+        const committed = await this.meta.commit((draft) => draft.delete(sessionId));
+        if (!committed)
+            throw new SessionError("storage", `LocalSessionStore: session-meta sidecar write failed while deleting session ${sessionId} — its owner/incarnation cell is still on disk`);
     }
-    ensureIncarnation(sessionId) {
-        return this.writeIncarnation(sessionId, (before) => (before === undefined ? mintSessionIncarnation() : undefined));
+    async existsInRepo(sessionId) {
+        try {
+            await this.repo.open({ id: sessionId, createdAt: "" });
+            return true;
+        }
+        catch (e) {
+            if (isNotFound(e))
+                return false;
+            throw e;
+        }
     }
-    async sessionFaceOf(sessionId) {
-        const owner = await this.ownerOf(sessionId);
-        if (owner === undefined)
-            return undefined;
-        await this.ensureIncarnation(sessionId);
-        const incarnation = this.incarnations.state.entries.get(sessionId);
-        if (!this.owners.has(sessionId) || (this.owners.get(sessionId) ?? null) !== owner)
+    async metaOf(sessionId) {
+        await this.meta.ensureLoaded();
+        const cell = this.meta.state.entries.get(sessionId);
+        if (cell !== undefined)
+            return readSessionMetaCell(cell);
+        if (!(await this.existsInRepo(sessionId)))
             return undefined;
-        return sessionFaceFromRow(sessionId, owner, incarnation);
+        await this.writeMeta(sessionId, (before) => (before === undefined ? mintSessionIncarnation() : undefined));
+        const minted = this.meta.state.entries.get(sessionId);
+        return minted === undefined ? undefined : readSessionMetaCell(minted);
+    }
+    async sessionFaceOf(sessionId) {
+        const meta = await this.metaOf(sessionId);
+        return meta === undefined ? undefined : sessionFaceFromRow(sessionId, meta.owner ?? null, meta.incarnation);
     }
     async probeTitle(sessionId) {
         await this.titles.ensureLoaded();
@@ -186,17 +234,11 @@ export class LocalSessionStore {
     }
     async recordInstructionSource(sessionId, expected, source) {
         await this.instructionSources.ensureLoaded();
-        const committed = await this.instructionSources.commit((entries) => {
-            const before = entries.get(sessionId);
-            if (!sameInstructionSourceBaseline(decodeInstructionSource(before), expected))
-                return undefined;
-            entries.set(sessionId, encodeInstructionSource(source));
-            return () => {
-                if (before === undefined)
-                    entries.delete(sessionId);
-                else
-                    entries.set(sessionId, before);
-            };
+        const committed = await this.instructionSources.commit((draft) => {
+            if (!sameInstructionSourceBaseline(decodeInstructionSource(draft.get(sessionId)), expected))
+                return false;
+            draft.set(sessionId, encodeInstructionSource(source));
+            return true;
         });
         if (!committed)
             throw new Error("LocalSessionStore: instruction-source sidecar write failed — baseline not recorded");
@@ -271,11 +313,10 @@ export class LocalSessionStore {
     }
     async acquire(sessionId, opts) {
         if (!sessionId) {
-            await this.incarnations.ensureLoaded();
+            await this.meta.ensureLoaded();
             const session = await this.repo.create({});
             const id = (await session.getMetadata()).id;
-            this.owners.set(id, null);
-            await this.mintIncarnation(id);
+            await this.writeMeta(id, () => ({ incarnation: mintSessionIncarnation(), owner: null }));
             return { session: session, sessionId: id };
         }
         if (opts?.requireExisting)
@@ -290,8 +331,6 @@ export class LocalSessionStore {
     async load(sessionId, requireExisting = false) {
         try {
             const session = await openSessionForItself(sessionId, () => this.repo.open({ id: sessionId, createdAt: "" }));
-            if (!this.owners.has(sessionId))
-                this.owners.set(sessionId, null);
             return { session: session, sessionId };
         }
         catch (e) {
@@ -299,56 +338,47 @@ export class LocalSessionStore {
                 throw e;
             if (requireExisting)
                 throw e;
-            await this.incarnations.ensureLoaded();
+            await this.meta.ensureLoaded();
             const session = await this.repo.create({ id: sessionId });
-            await this.mintIncarnation(sessionId);
-            if (!this.owners.has(sessionId))
-                this.owners.set(sessionId, null);
+            await this.writeMeta(sessionId, (before) => ({ incarnation: mintSessionIncarnation(), owner: before !== undefined && ownerRecorded(before) ? (readSessionMetaCell(before).owner ?? null) : null }));
             return { session: session, sessionId };
         }
     }
     async register(sessionId, owner) {
-        if (this.owners.has(sessionId))
+        await this.meta.ensureLoaded();
+        if (ownerRecorded(this.meta.state.entries.get(sessionId)))
             return;
-        await this.incarnations.ensureLoaded();
-        this.owners.set(sessionId, owner);
-        try {
-            await this.repo.open({ id: sessionId, createdAt: "" });
-            await this.ensureIncarnation(sessionId);
-        }
-        catch (e) {
-            if (!isNotFound(e))
-                throw e;
+        const existed = await this.existsInRepo(sessionId);
+        const claim = existed && owner !== null && ownerClaimWindowOpen();
+        const wrote = await this.writeMeta(sessionId, (before) => {
+            if (ownerRecorded(before))
+                return undefined;
+            if (!existed || claim)
+                return { incarnation: existed && before !== undefined ? readSessionMetaCell(before).incarnation : mintSessionIncarnation(), owner };
+            return before === undefined ? mintSessionIncarnation() : undefined;
+        });
+        if (!existed && wrote)
             await this.repo.create({ id: sessionId });
-            await this.mintIncarnation(sessionId);
-        }
+        if (claim && wrote)
+            this.log.info("session_owner_claimed", { sessionId });
     }
     async ownerOf(sessionId) {
-        if (this.owners.has(sessionId))
-            return this.owners.get(sessionId) ?? null;
-        try {
-            await this.repo.open({ id: sessionId, createdAt: "" });
-            this.owners.set(sessionId, null);
-            return null;
-        }
-        catch (e) {
-            if (isNotFound(e))
-                return undefined;
-            throw e;
-        }
+        const meta = await this.metaOf(sessionId);
+        return meta === undefined ? undefined : (meta.owner ?? null);
     }
     async getHead(sessionId) {
-        if (!this.owners.has(sessionId) && (await this.ownerOf(sessionId)) === undefined)
+        const before = await this.metaOf(sessionId);
+        if (before === undefined)
             return undefined;
-        const owner = this.owners.get(sessionId) ?? null;
         const leafId = await this.getLeafId(sessionId);
-        if (!this.owners.has(sessionId) || (this.owners.get(sessionId) ?? null) !== owner)
+        const cell = this.meta.state.entries.get(sessionId);
+        const after = cell === undefined ? undefined : readSessionMetaCell(cell);
+        if (after === undefined || after.incarnation !== before.incarnation || (after.owner ?? null) !== (before.owner ?? null))
             return undefined;
-        return { owner, leafId };
+        return { owner: before.owner ?? null, leafId };
     }
-    restampOwner(sessionId, owner) {
-        if (this.owners.has(sessionId))
-            this.owners.set(sessionId, owner);
+    async restampOwner(sessionId, owner) {
+        await this.writeMeta(sessionId, (before) => (before === undefined ? undefined : { incarnation: readSessionMetaCell(before).incarnation, owner }));
     }
     async touch(sessionId) {
         this.lastActivity.set(sessionId, new Date().toISOString());
@@ -371,10 +401,12 @@ export class LocalSessionStore {
     async listSessions(opts) {
         await this.ensureLoaded();
         await this.titles.ensureLoaded();
+        await this.meta.ensureLoaded();
         const metas = await this.repo.list();
         const all = [];
         for (const meta of metas) {
-            const owner = this.owners.has(meta.id) ? (this.owners.get(meta.id) ?? null) : null;
+            const cell = this.meta.state.entries.get(meta.id);
+            const owner = cell === undefined ? null : (readSessionMetaCell(cell).owner ?? null);
             if (opts.owner !== undefined && owner !== opts.owner && !(opts.includeUnowned === true && owner === null))
                 continue;
             const firstActivityAt = meta.createdAt || new Date(0).toISOString();
@@ -423,12 +455,11 @@ export class LocalSessionStore {
         }
     }
     async fork(sourceId, owner) {
-        await this.incarnations.ensureLoaded();
+        await this.meta.ensureLoaded();
         try {
             const session = await this.repo.fork({ id: sourceId, createdAt: "" }, {});
             const id = (await session.getMetadata()).id;
-            this.owners.set(id, owner);
-            await this.mintIncarnation(id);
+            await this.writeMeta(id, () => ({ incarnation: mintSessionIncarnation(), owner }));
             return id;
         }
         catch (e) {
@@ -471,10 +502,9 @@ export class LocalSessionStore {
     async importEntriesAs(sessionId, owner, entries, incarnation) {
         if (!this.repo.importEntries)
             throw new SessionError("storage", "session import is not supported by this local backend");
-        await this.incarnations.ensureLoaded();
+        await this.meta.ensureLoaded();
         await this.repo.importEntries(sessionId, owner ?? undefined, entries);
-        this.owners.set(sessionId, owner);
-        await this.writeIncarnation(sessionId, () => incarnation);
+        await this.writeMeta(sessionId, () => ({ incarnation, owner }));
     }
     async replaceEntries(sessionId, owner, entries) {
         if (!this.repo.importEntries)
@@ -482,8 +512,8 @@ export class LocalSessionStore {
         if (!this.repo.delete)
             throw new SessionError("storage", "session replace is not supported by this local backend (no delete seam)");
         validateEntriesForImport(entries);
-        await this.incarnations.ensureLoaded();
-        const prior = this.owners.has(sessionId) ? { owner: this.owners.get(sessionId) ?? null, incarnation: this.incarnations.state.entries.get(sessionId) } : undefined;
+        const current = await this.metaOf(sessionId);
+        const prior = current === undefined ? undefined : { owner: current.owner ?? null, incarnation: current.incarnation };
         await this.deleteSession(sessionId, owner);
         await this.importEntriesAs(sessionId, owner, entries, carriedIncarnation(prior, owner));
     }
@@ -499,8 +529,8 @@ export class LocalSessionStore {
         this.stagings.delete(stagingId);
     }
     async deleteSession(sessionId, owner) {
-        const known = this.owners.has(sessionId);
-        if (!known || !ownerEq(this.owners.get(sessionId) ?? null, owner))
+        const current = await this.ownerOf(sessionId);
+        if (current === undefined || !ownerEq(current, owner))
             return false;
         try {
             await this.repo.delete({ id: sessionId, createdAt: "" });
@@ -509,10 +539,10 @@ export class LocalSessionStore {
             if (!isNotFound(e))
                 throw e;
         }
-        this.owners.delete(sessionId);
+        await this.dropMeta(sessionId);
         this.lastActivity.delete(sessionId);
         this.lastTaskRun.delete(sessionId);
-        for (const map of [this.titles, this.instructionSources, this.incarnations]) {
+        for (const map of [this.titles, this.instructionSources]) {
             await map.ensureLoaded();
             if (map.state.entries.delete(sessionId))
                 await map.persist();
@@ -572,7 +602,7 @@ class LocalStagingHandle {
             await this.store.replaceEntries(this.realSessionId, owner, this.staged);
         }
         else {
-            this.store.restampOwner(this.realSessionId, owner);
+            await this.store.restampOwner(this.realSessionId, owner);
         }
         this.store.forgetStaging(this.stagingId);
         return { relation: rel.relation };

package/dist/plugins/one-time-migrations.d.ts

@@ -1,5 +1,6 @@
 import type { Pool as MysqlPool } from "mysql2/promise";
 import type { Pool as PgPool } from "pg";
+import { type UndurableScopeRuleRow, type UnreadableRuleBucket } from "./permission-rule-store-sql.js";
 /** 迁移读数(启动日志一行写全;测试按它断言,不靠日志文本)。 */
 export interface OneTimeMigrationReport {
     /** M1:退役快照索引表 —— `dropped` = 本次真 drop 了,`absent` = 早已不在(第二跑/全新库)。 */
@@ -33,6 +34,13 @@ export interface OneTimeMigrationReport {
     readonly workflowParkIndexKey: "reshaped" | "current" | "file-ledger";
     /** M9:改形时原样搬进新表的指针行数(`current` / `file-ledger` 时恒 0)。非零 = 这次迁移真重建了一张表,运维该看见一次。 */
     readonly workflowParkIndexRowsCarried: number;
+    /** M11:本次从持久规则桶里删掉的、scope 不被引擎 durable 谓词收的行(一行一条,启动日志逐行 warn;local 车道恒空,见头注 M11 段)。 */
+    readonly undurableScopeRuleRows: readonly UndurableScopeRuleRow[];
+    /** M11:连续争不过在线写者、留到下一次起服的桶数(那期间坏行照旧由引擎读侧丢并告知;非零 ⇒ warn)。 */
+    readonly undurableScopeRuleBucketsDeferred: number;
+    /** M11:读腿整桶拒的桶(唯一判官判不过:形 / 指纹 / behavior 闭集 / 墓碑规范文本 / 单一验证器)—— 一个字节没动,一桶一条拒因
+     *  (不带行内容),启动日志逐桶 warn;local 车道恒空(见头注 M11 段)。 */
+    readonly undurableScopeRuleBucketsUnreadable: readonly UnreadableRuleBucket[];
 }
 /**
  * S-590 —— 一条一次性迁移的窗(登记表的一行;纯数据)。字段注写着每个值的取证方式,改一行之前照着重核。
@@ -65,6 +73,12 @@ export interface OneTimeMigrationWindow {
  * 而留着 M3 会让 M3 永远判「跑过了」。三条同版引入、同一天到期,本来就同一次删。
  */
 export declare const ONE_TIME_MIGRATIONS: readonly OneTimeMigrationWindow[];
+/**
+ * 一条登记行的窗**此刻**开着没有(`today` = UTC 日历日 YYYY-MM-DD):未发布形(`removableAfter: null`)⇒ 开;否则今天不晚于 `removableAfter` ⇒ 开
+ * (窗关当天仍开,与到期门「今天严格晚于才红」同一条边界)。
+ * 只给**窗内才生效的行为臂**用(M10 的认领):那种臂过了窗就停,不等删码车 —— 删码因此是零行为变化,而窗只写在本表这一处。
+ */
+export declare function migrationWindowOpen(window: Pick<OneTimeMigrationWindow, "removableAfter">, today: string): boolean;
 /** local 车道上 SQL 独有的四条(M1 / M2 / M4 / M5)的读数(M3 / M6 两车道都有,local 腿的读数由 `LocalBackend.runOneTimeMigrations` 现算):那几张表 / 列在文件底座上从来不存在 ⇒ 如实答 absent / 0。 */
 export declare const NO_SQL_MIGRATIONS: Omit<OneTimeMigrationReport, "askOriginRowsMigrated" | "holderDeathCodeRowsBackfilled">;
 /** 启动期的日志口(logger 的子集)。两级各有其用,见 {@link logOneTimeMigrations}。 */

package/dist/plugins/one-time-migrations.js

@@ -5,6 +5,7 @@ import { ensureIndexes } from "./ensure-index.js";
 import { decodeJsonColumn, isJsonColumnBodyProblem, jsonColumnText, jsonColumnTextExpr, readNonNullJsonValueColumn } from "./sql-json-column.js";
 import { SESSION_META_INCARNATION_COLUMN, mintSessionIncarnation } from "../session-incarnation.js";
 import { RUN_HOLDER_DEATH_CODES, RUN_ORPHANED_ERROR, RUN_STALLED_ERROR } from "./store-contracts.js";
+import { PERMISSION_RULE_TABLE, purgeUndurableScopeRows } from "./permission-rule-store-sql.js";
 export const ONE_TIME_MIGRATIONS = [
     {
         id: "M1",
@@ -119,7 +120,39 @@ export const ONE_TIME_MIGRATIONS = [
             "`decide.workflow_parks_unreadable`);出路不变(续跑发起它的那条 workflow run);随包排空判据没了,换钉前没有机器读数可数这些卡",
         reportKeys: ["workflowParkIndexKey", "workflowParkIndexRowsCarried"],
     },
+    {
+        id: "M10",
+        introducedIn: "7.119.0",
+        releasedOn: "2026-10-08",
+        removableAfter: "2026-11-07",
+        removal: "删 local 车道的认领臂:`LocalSessionStore.register` 里「属主从没被记下的存量会话 ⇒ 带 principal 的登记认领它」那一支、认领日志行 `session_owner_claimed`" +
+            "(连同店构造参数里只为它存在的 `log` 位)与读本表 M10 行的 `ownerClaimWindowOpen`;`security.ts` `createAuthorizer` 里对无主会话的那次认领 `register` 调用;" +
+            "`http/routes/sessions.ts` 409 `conflict.session_ownerless` 句里「Ways out: on the local backend, during the upgrade window …」那半句(连同冻结表 " +
+            "`test/api-error-text-freeze.test.ts` 那一行、契约码目录 `docs/ASSISTANT-WIRE-CONTRACT.md` 那一行);本文件的 `migrationWindowOpen`(若再无别的读者)",
+        afterRemoval: "没有响亮臂(删码本身零行为变化:窗关那一刻起认领臂已经不生效):属主从没被记下的存量会话(边档那一格只有化身 —— 跳过了带本条的版本直接升," +
+            "或窗内从没被带 principal 提交过)照旧答无主(`ownerOf` = null):它的会话规则这条路由读不了也改不了(409 `conflict.session_ownerless`)," +
+            "已存的规则对写下它们的 principal 的 run 照旧生效;出路 = 删会话(`DELETE /v1/sessions/:id`,规则随之删)",
+        reportKeys: [],
+    },
+    {
+        id: "M11",
+        introducedIn: "7.120.0",
+        releasedOn: "2026-10-08",
+        removableAfter: "2026-11-07",
+        removal: "删 migrateOn 的 M11 步(`permission_rule` 在场探针 + `purgeUndurableScopeRows` 调用)与 `permission-rule-store-sql.ts` 的 `purgeUndurableScopeRows` / " +
+            "`purgeAllBuckets` / `purgeOneBucket` / `contentFreeRefusal` / `PurgeAccumulator` / `UndurableScopeRuleRow` / `UnreadableRuleBucket` / `UndurableScopePurge` / " +
+            "`UndurableScopePurgeDb` / `UNDURABLE_PURGE_PAGE` / `UNDURABLE_PURGE_OCC_ATTEMPTS`、本文件的 `removedRuleRowNote`,以及 `BucketRefusedError` 的 `verdict` 位(若届时再无别的读者;" +
+            "判官 `decodeBucketRow` 与写法 `writeBucket` 是读腿 / 写臂本身,留);报告、日志行(含逐行的 `permission_rule_row_removed` 与逐桶的 " +
+            "`permission_rule_bucket_unreadable`)与 `NO_SQL_MIGRATIONS` 的 `undurableScopeRuleRows` / `undurableScopeRuleBucketsDeferred` / `undurableScopeRuleBucketsUnreadable`",
+        afterRemoval: "引擎读侧的既有响亮臂:scope root 不是完整绝对路径的存量行(跳过了带本条的版本直接升的库,或窗关之后别的写者写进来的)在有效视图里被丢、" +
+            "每次 run 一条 `permission.rule_row_dropped`(点名规则与 root)—— 那一行不参与任何检查,但撤销口删不动它(引擎的写臂对这种 scope 同样拒);" +
+            "出路 = 运维在库里把那只桶的那一行删掉(整桶 OCC 回写,指纹按 `buildRuleBucketChecksum` 重算)",
+        reportKeys: ["undurableScopeRuleRows", "undurableScopeRuleBucketsDeferred", "undurableScopeRuleBucketsUnreadable"],
+    },
 ];
+export function migrationWindowOpen(window, today) {
+    return window.removableAfter === null || today <= window.removableAfter;
+}
 export const NO_SQL_MIGRATIONS = {
     retiredSnapshotTable: "absent",
     retiredSnapshotRows: 0,
@@ -132,6 +165,9 @@ export const NO_SQL_MIGRATIONS = {
     allowRuleShadowRowsUnreadable: 0,
     workflowParkIndexKey: "file-ledger",
     workflowParkIndexRowsCarried: 0,
+    undurableScopeRuleRows: [],
+    undurableScopeRuleBucketsDeferred: 0,
+    undurableScopeRuleBucketsUnreadable: [],
 };
 const RETIRED_SNAPSHOT_TABLE = "snapshot_manifest";
 const RETIRED_STEER_SEAT_COLUMN = "pending_steer";
@@ -276,8 +312,16 @@ async function migrateOn(db, dialect) {
     let retiredSnapshotTable = "absent";
     let retiredSnapshotRows = 0;
     let retiredSteerSeatColumn = "absent";
+    let undurableScopeRuleRows = [];
+    let undurableScopeRuleBucketsDeferred = 0;
+    let undurableScopeRuleBucketsUnreadable = [];
     const destroyed = [];
     try {
+        if (await tableExists(db, dialect, PERMISSION_RULE_TABLE)) {
+            ({ removed: undurableScopeRuleRows, bucketsDeferred: undurableScopeRuleBucketsDeferred, bucketsUnreadable: undurableScopeRuleBucketsUnreadable } = await purgeUndurableScopeRows(db, dialect));
+            for (const r of undurableScopeRuleRows)
+                destroyed.push(`removed permission_rule ${r.kind} (bucket ${r.ownerKey}, ${r.behavior} ${r.tool}, scope root ${JSON.stringify(r.scopeRoot)})`);
+        }
         const counted = !snapshotTablePresent
             ? undefined
             : await db.rows(`SELECT COUNT(*) AS n FROM ${RETIRED_SNAPSHOT_TABLE}`).then((rows) => Number(rows[0]?.n ?? 0), async (e) => {
@@ -306,7 +350,7 @@ async function migrateOn(db, dialect) {
     return {
         retiredSnapshotTable, retiredSnapshotRows, retiredSteerSeatColumn, retiredSteerSeatStaleRows, askOriginRowsMigrated, auditDetailJsonNullRows,
         sessionIncarnationColumn, sessionIncarnationsBackfilled, holderDeathCodeRowsBackfilled, allowRuleShadowRowsMigrated, allowRuleShadowRowsUnreadable,
-        workflowParkIndexKey, workflowParkIndexRowsCarried,
+        workflowParkIndexKey, workflowParkIndexRowsCarried, undurableScopeRuleRows, undurableScopeRuleBucketsDeferred, undurableScopeRuleBucketsUnreadable,
     };
 }
 const WORKFLOW_PARK_INDEX_TABLE = "workflow_agent_session";
@@ -508,7 +552,8 @@ export function migrateRetiredAskOrigin(type, data) {
 export function logOneTimeMigrations(log, backend, report) {
     const changed = report.retiredSnapshotTable === "dropped" || report.retiredSteerSeatColumn === "dropped" || report.askOriginRowsMigrated > 0 || report.auditDetailJsonNullRows > 0 ||
         report.sessionIncarnationColumn === "added" || report.sessionIncarnationsBackfilled > 0 || report.holderDeathCodeRowsBackfilled > 0 || report.allowRuleShadowRowsMigrated > 0 || report.allowRuleShadowRowsUnreadable > 0 ||
-        report.workflowParkIndexKey === "reshaped";
+        report.workflowParkIndexKey === "reshaped" || report.undurableScopeRuleRows.length > 0 || report.undurableScopeRuleBucketsDeferred > 0 ||
+        report.undurableScopeRuleBucketsUnreadable.length > 0;
     (changed ? log.warn : log.info).call(log, "one_time_migrations_applied", {
         backend,
         retiredSnapshotTable: report.retiredSnapshotTable,
@@ -524,6 +569,9 @@ export function logOneTimeMigrations(log, backend, report) {
         allowRuleShadowRowsUnreadable: report.allowRuleShadowRowsUnreadable,
         workflowParkIndexKey: report.workflowParkIndexKey,
         workflowParkIndexRowsCarried: report.workflowParkIndexRowsCarried,
+        undurableScopeRuleRowsRemoved: report.undurableScopeRuleRows.length,
+        undurableScopeRuleBucketsDeferred: report.undurableScopeRuleBucketsDeferred,
+        undurableScopeRuleBucketsUnreadable: report.undurableScopeRuleBucketsUnreadable.length,
         removableAfter: Object.fromEntries(ONE_TIME_MIGRATIONS.map((w) => [w.id, w.removableAfter])),
         note: "one-time persisted-data migrations (M1: retired whole-tree snapshot index table dropped; M2: retired single-seat " +
             "steering column dropped; M3: retired ask-origin spelling rewritten in place; M4: audit details written as the JSON " +
@@ -533,10 +581,49 @@ export function logOneTimeMigrations(log, backend, report) {
             "run.orphaned; M7 writes nothing — it is the window of the refusal that keeps a suspended task whose stored allow list was written " +
             "under an earlier reading from resuming under the current one; M8: parked rows' allow-layer disclosure written by an earlier engine " +
             "under its old key shadowedRule rewritten to allowRuleShadowed; M9: the workflow park pointer index rebuilt with the key (session, run), " +
-            "its rows carried over). Each step " +
+            "its rows carried over; M10 writes nothing at boot — on the local backend, while its window is open, the first task submitted with a principal " +
+            "on a session written by an earlier version (which recorded no owner) claims that session for the principal, one session_owner_claimed line per claim; " +
+            "M11: persisted permission rules whose project scope root is not a complete absolute path — accepted by earlier versions, dropped on every read " +
+            "by the current engine and not removable through DELETE /v1/rules — removed, one permission_rule_row_removed line per row; a bucket the read path " +
+            "refuses in whole is left untouched, one permission_rule_bucket_unreadable line per bucket). Each step " +
             "runs on every boot until its window closes (the release that introduced it + 30 days; the per-step date is in " +
             "removableAfter, null while that release is not published yet) and is deleted in the first minor after that — start a " +
             "version that still carries a step at least once before upgrading past its deletion.",
     });
+    for (const row of report.undurableScopeRuleRows) {
+        log.warn("permission_rule_row_removed", {
+            backend,
+            ownerKey: row.ownerKey,
+            kind: row.kind,
+            behavior: row.behavior,
+            tool: row.tool,
+            scopeRoot: row.scopeRoot,
+            note: removedRuleRowNote(row.kind),
+        });
+    }
+    for (const bucket of report.undurableScopeRuleBucketsUnreadable) {
+        log.warn("permission_rule_bucket_unreadable", {
+            backend,
+            ownerKey: bucket.ownerKey,
+            why: bucket.why,
+            note: "a persisted permission-rule bucket that the read path refuses in whole was left untouched by the one-time removal of rows whose project scope root " +
+                "is not a complete absolute path (removing rows from a bucket the read path refuses would turn that refusal into a readable bucket): every read of it " +
+                "keeps being refused, as before this release, until someone repairs or deletes that row by hand",
+        });
+    }
+}
+function removedRuleRowNote(kind) {
+    switch (kind) {
+        case "rule":
+            return "a persisted permission rule whose project scope root is not a complete absolute path was removed by a one-time migration: the current engine drops such a row on every read (it protected nothing) and refuses any write naming that scope, so it could not be revoked through DELETE /v1/rules; re-add it with the project's full path if it is still wanted";
+        case "revoked-rule":
+            return "a persisted permission rule whose project scope root is not a complete absolute path, and which had already been revoked (every approval behind it is removed by a tombstone in the same bucket), was removed by a one-time migration: it granted nothing before and grants nothing now — the revocation stands, no action needed";
+        case "tombstone":
+            return "a revocation record (tombstone) whose project scope root is not a complete absolute path was removed by a one-time migration: it can only cover rules with that same scope, which were removed with it or were never there, so nothing it revoked comes back — no action needed";
+        default: {
+            const unknown = kind;
+            throw new Error(`M11: no log sentence for removed-row kind ${JSON.stringify(unknown)}`);
+        }
+    }
 }
 //# sourceMappingURL=one-time-migrations.js.map