@sema-agent/server 7.117.0 → 7.119.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

@@ -28,6 +28,11 @@ export interface OneTimeMigrationReport {
     readonly allowRuleShadowRowsMigrated: number;
     /** M8:带旧键字样、但这一格的 JSON 读不懂 ⇒ 没改写的行数(留给读口自己的响亮臂;非零 = 运维该看一眼这些行)。SQL 独有;local 恒 0。 */
     readonly allowRuleShadowRowsUnreadable: number;
+    /** M9:workflow park 指针索引的主键 —— `reshaped` = 本次把只有 `session_id` 的主键改成 `(session_id, run_id)`;`current` = 早已是新形
+     *  (新库 / 第二跑);`file-ledger` = local 文件车道(账本一行本来就是一条 run 的指针集,没有主键可改)。 */
+    readonly workflowParkIndexKey: "reshaped" | "current" | "file-ledger";
+    /** M9:改形时原样搬进新表的指针行数(`current` / `file-ledger` 时恒 0)。非零 = 这次迁移真重建了一张表,运维该看见一次。 */
+    readonly workflowParkIndexRowsCarried: number;
 }
 /**
  * S-590 —— 一条一次性迁移的窗(登记表的一行;纯数据)。字段注写着每个值的取证方式,改一行之前照着重核。
@@ -60,6 +65,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}。 */