@sema-agent/server 7.138.0 → 7.139.0

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

@@ -1,15 +1,19 @@
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { assertFirstOwnerWritable, forkOwnerOf, importerOwnerOf } from "./session-ownership.js";
-import { FileSessionRepo, SessionError, StoredSession, settledForkOptions, validateEntriesForImport } from "@sema-agent/core";
+import { FileSessionRepo, SessionError, StoredSession, sessionLogMarkOf, settledForkOptions, validateEntriesForImport } from "@sema-agent/core";
 import { z } from "zod";
 import { contentForkRelation, fastForwardSharedContentDiverged, identicalIdsAlsoIdenticalContent } from "../session-sync-content.js";
+import { judgeSessionRowWrite, sessionRowTagKey, settleSessionRowWrite, } from "../session-row.js";
 import { quarantineUnreadableSidecar } from "./local-sidecar-quarantine.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 { UnreadableLeaf, carriedIncarnation, headFromRow, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
+import { UnreadableLeaf, carriedRowCells, headFromRow, incarnationFromCell, mintSessionIncarnation, sessionFaceFromRow } from "../session-incarnation.js";
+import { isExecutionLane } from "../execution-lane-caps.js";
+import { SessionForkInProgressError, SessionWriterPresentError, WRITABLE, assertPlaceableLane, isUnusableArchive, settledMirrorOutcome, settledPlaceOutcome, } from "../execution-placement.js";
+import { classifyForkTarget, forkByFreshId } from "./session-fork.js";
 import { decodeInstructionSource, encodeInstructionSource, sameInstructionSourceBaseline } from "../instruction-source-notice.js";
 import { decodeSessionWorkspaceCell, encodeSessionWorkspaceCell } from "./session-workspace-cell.js";
 import { noteReplayInSessionOpenScope, openSessionForItself } from "../session-records-skipped-notice.js";
@@ -18,6 +22,35 @@ import { buildObjectivePreview, isAttachmentFrame } from "../user-authored-text.
 import { classifySyncRelationshipByIds, ownerCellIs, SyncConflictError, StagedCommitOwnerChangedError, stagingIdFor, } from "../session-sync-kernel.js";
 const ownerEq = (a, b) => (a ?? null) === (b ?? null);
 const isNotFound = (e) => e instanceof SessionError && e.code === "not_found";
+function archiveFaultWord(code) {
+    switch (code) {
+        case "not_found":
+            return "absent";
+        case "corrupt_session":
+        case "invalid_session":
+            return code;
+        case "invalid_entry":
+        case "invalid_fork_target":
+        case "storage":
+        case "conflict":
+        case "placement_refused":
+        case "unknown":
+            return "storage";
+        default: {
+            const unknownCode = code;
+            throw new Error(`LocalSessionStore: no archive state for session error code ${JSON.stringify(unknownCode)}`);
+        }
+    }
+}
+function unusableArchiveOf(word, fault) {
+    const code = fault instanceof SessionError ? undefined : fault?.code;
+    return { state: "unusable", word, fault, ...(word === "storage" && typeof code === "string" ? { errno: code } : {}) };
+}
+function importRowRefused(sessionId, landing) {
+    return new SessionError("conflict", landing === "create"
+        ? `session ${sessionId} already exists — importEntries only creates a session (replaceEntries rewrites one); nothing was written`
+        : `session ${sessionId} is not the importer's row — an import replaces only a log whose row the importer owns (or an anonymous row, by an anonymous import); nothing was written`);
+}
 const SESSION_OBJECTIVE_PREVIEW_CHARS = 200;
 function userText(entry) {
     if (entry.type !== "message")
@@ -38,11 +71,24 @@ function userText(entry) {
 }
 const SIDECAR_DEGRADES = { lastActivity: "recency", title: "title", pinned: "pin state", "instruction-source": "instruction-source baseline", workspace: "each session's last recorded place and project (the next frame records it again)", "session-meta": "session owner + incarnation (the write that needed it failed loudly)" };
 const readPinnedSidecar = createZodColumnReader(z.record(z.string(), z.literal(true)));
+const MIRROR_CELL = { role: "mirror" };
 function readSessionMetaCell(cell) {
-    return typeof cell === "string" ? { incarnation: cell, owner: undefined } : cell;
+    return typeof cell === "string" ? { incarnation: cell, owner: undefined, execution: undefined, forkKey: undefined } : { incarnation: cell.incarnation, owner: cell.owner, execution: cell.execution, forkKey: cell.forkKey };
 }
 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()]));
+function cellWith(before, bits) {
+    const base = typeof before === "string" ? { incarnation: before } : before;
+    return { ...base, ...("owner" in bits ? { owner: bits.owner } : {}), ...(bits.execution !== undefined ? { execution: bits.execution } : {}) };
+}
+const isForkCreatedCell = (meta) => meta !== undefined && meta.forkKey !== undefined && meta.execution === undefined;
+function readingOfCell(sessionId, meta, forking) {
+    return { occupant: sessionFaceFromRow(sessionId, meta.owner ?? null, meta.incarnation), cell: forking ? { role: "forking" } : (meta.execution ?? { role: "absent" }) };
+}
+const LOCAL_EXECUTION_CELL = z.discriminatedUnion("role", [
+    z.object({ role: z.literal("writer"), lane: z.custom((v) => typeof v === "string" && isExecutionLane(v), { message: "not an execution lane" }) }).strict(),
+    z.object({ role: z.literal("mirror") }).strict(),
+]);
+const SESSION_META_SIDECAR = z.record(z.string(), z.union([z.string(), z.object({ incarnation: z.string(), owner: z.string().nullable().optional(), execution: LOCAL_EXECUTION_CELL.optional(), forkKey: z.string().optional() }).strict()]));
 const readSessionMetaSidecar = createZodColumnReader(SESSION_META_SIDECAR);
 function ownerClaimWindowOpen() {
     const window = ONE_TIME_MIGRATIONS.find((w) => w.id === "M10");
@@ -185,6 +231,8 @@ export class LocalSessionStore {
     meta;
     log;
     sessionWriteLocks;
+    executionPlacement;
+    executionPlacementBackfill;
     constructor(repo, runs, dataDir, opts) {
         this.repo = repo;
         this.runs = runs;
@@ -200,6 +248,86 @@ export class LocalSessionStore {
         if (root !== undefined && !SESSION_WRITE_LOCKS_BY_ROOT.has(root))
             SESSION_WRITE_LOCKS_BY_ROOT.set(root, new Map());
         this.sessionWriteLocks = root !== undefined ? SESSION_WRITE_LOCKS_BY_ROOT.get(root) : new Map();
+        this.executionPlacement = {
+            read: (sessionId) => this.readExecutionPlacement(sessionId),
+            place: (sessionId, occupant, cell) => this.placeExecution(sessionId, occupant, cell),
+            markMirror: (sessionId, occupant) => this.markMirrorExecution(sessionId, occupant),
+        };
+        this.executionPlacementBackfill = {
+            read: (sessionId) => this.placementRead(sessionId),
+            place: (sessionId, occupant, cell) => this.placeExecution(sessionId, occupant, cell),
+        };
+    }
+    async forkingRead(sessionId, meta) {
+        if (!isForkCreatedCell(meta))
+            return false;
+        const probe = await this.probeArchive(sessionId);
+        if (probe.state === "unusable" && probe.word === "storage")
+            return probe;
+        return probe.state === "absent";
+    }
+    async forkingOf(sessionId, meta) {
+        const forking = await this.forkingRead(sessionId, meta);
+        if (typeof forking !== "boolean")
+            throw forking.fault;
+        return forking;
+    }
+    async placementRead(sessionId) {
+        const read = await this.metaRead(sessionId);
+        if (read.state === "unusable")
+            return read;
+        if (read.state === "absent")
+            return undefined;
+        const forking = await this.forkingRead(sessionId, read.meta);
+        return typeof forking === "boolean" ? readingOfCell(sessionId, read.meta, forking) : forking;
+    }
+    async readExecutionPlacement(sessionId) {
+        const reading = await this.placementRead(sessionId);
+        if (isUnusableArchive(reading))
+            throw reading.fault;
+        return reading;
+    }
+    async placeExecution(sessionId, occupant, cell) {
+        assertPlaceableLane(sessionId, cell);
+        return this.withSessionWriteLock(sessionId, () => this.settleExecutionHeld(sessionId, (reading) => {
+            const settled = settledPlaceOutcome(sessionId, reading, occupant, cell);
+            return settled === WRITABLE ? { outcome: { outcome: "placed" }, execution: { role: "writer", lane: cell.lane } } : { outcome: settled };
+        }));
+    }
+    async markMirrorExecution(sessionId, occupant) {
+        return this.withSessionWriteLock(sessionId, async () => {
+            await this.meta.ensureLoaded();
+            const claim = this.metaCellOf(sessionId) === undefined ? undefined : await this.runs.getActiveTaskId(sessionId);
+            return this.settleExecutionHeld(sessionId, (reading) => {
+                const settled = settledMirrorOutcome(sessionId, reading, occupant);
+                if (settled !== WRITABLE)
+                    return { outcome: settled };
+                return claim === undefined ? { outcome: { outcome: "mirrored" }, execution: MIRROR_CELL } : { outcome: { outcome: "active", activeTaskId: claim } };
+            });
+        });
+    }
+    async settleExecutionHeld(sessionId, judge) {
+        await this.meta.ensureLoaded();
+        const forking = await this.forkingOf(sessionId, this.metaCellOf(sessionId));
+        let settled;
+        let fault;
+        await this.writeMeta(sessionId, (before) => {
+            try {
+                settled = judge(before === undefined ? undefined : readingOfCell(sessionId, readSessionMetaCell(before), forking));
+            }
+            catch (e) {
+                fault = e;
+                return undefined;
+            }
+            return settled.execution === undefined || before === undefined ? undefined : cellWith(before, { execution: settled.execution });
+        });
+        if (fault !== undefined)
+            throw fault;
+        return settled.outcome;
+    }
+    metaCellOf(sessionId) {
+        const cell = this.meta.state.entries.get(sessionId);
+        return cell === undefined ? undefined : readSessionMetaCell(cell);
     }
     async writeMeta(sessionId, next) {
         await this.meta.ensureLoaded();
@@ -234,29 +362,44 @@ export class LocalSessionStore {
                 locks.delete(sessionId);
         }
     }
-    async existsInRepo(sessionId) {
+    async probeArchive(sessionId) {
         try {
             await this.repo.open({ id: sessionId, createdAt: "" });
-            return true;
+            return { state: "readable" };
         }
         catch (e) {
-            if (isNotFound(e))
-                return false;
-            throw e;
+            const word = e instanceof SessionError ? archiveFaultWord(e.code) : "storage";
+            return word === "absent" ? { state: "absent" } : unusableArchiveOf(word, e);
         }
     }
+    async existsInRepo(sessionId) {
+        const probe = await this.probeArchive(sessionId);
+        if (probe.state === "unusable")
+            throw probe.fault;
+        return probe.state === "readable";
+    }
     async metaOf(sessionId) {
+        const read = await this.metaRead(sessionId);
+        if (read.state === "unusable")
+            throw read.fault;
+        return read.state === "found" ? read.meta : undefined;
+    }
+    async metaRead(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 this.cellOfPresent(sessionId);
+            return { state: "found", meta: readSessionMetaCell(cell) };
+        const probe = await this.probeArchive(sessionId);
+        if (probe.state === "unusable")
+            return probe;
+        if (probe.state === "absent")
+            return { state: "absent" };
+        const meta = await this.cellOfPresent(sessionId);
+        return meta === undefined ? { state: "absent" } : { state: "found", meta };
     }
     async cellOfPresent(sessionId) {
         if (!this.meta.state.entries.has(sessionId))
-            await this.writeMeta(sessionId, (before) => (before === undefined ? mintSessionIncarnation() : undefined));
+            await this.writeMeta(sessionId, (before) => (before === undefined ? { incarnation: mintSessionIncarnation() } : undefined));
         const cell = this.meta.state.entries.get(sessionId);
         return cell === undefined ? undefined : readSessionMetaCell(cell);
     }
@@ -282,55 +425,86 @@ export class LocalSessionStore {
         return this.titles.state.entries.has(sessionId) ? "titled" : "untitled";
     }
     async setTitleIfNull(sessionId, title) {
-        await this.titles.ensureLoaded();
-        const entries = this.titles.state.entries;
-        if (entries.has(sessionId))
-            return false;
-        entries.set(sessionId, title);
-        await this.titles.persist();
-        return true;
+        return this.withSessionWriteLock(sessionId, async () => {
+            await this.titles.ensureLoaded();
+            const entries = this.titles.state.entries;
+            if (entries.has(sessionId))
+                return false;
+            entries.set(sessionId, title);
+            await this.titles.persist();
+            return true;
+        });
     }
-    async patchSessionMeta(sessionId, patch, face) {
+    async writeSessionRowCells(sessionId, cells, how) {
         return this.withSessionWriteLock(sessionId, async () => {
-            await this.meta.ensureLoaded();
-            if (!this.occupiedBy(sessionId, face) || (await this.listedMeta(sessionId)) === undefined)
-                return undefined;
-            const { title, pinned } = patch;
-            if (title !== undefined) {
-                await this.titles.ensureLoaded();
-                const ok = await this.titles.commit((draft) => {
-                    if (title === null)
-                        return draft.delete(sessionId);
-                    if (draft.get(sessionId) === title)
-                        return false;
-                    draft.set(sessionId, title);
-                    return true;
-                });
-                if (!ok)
-                    throw new SessionError("storage", `LocalSessionStore: title sidecar write failed for session ${sessionId} — the title was not recorded`);
-            }
-            if (pinned !== undefined) {
-                await this.pinned.ensureLoaded();
-                const ok = await this.pinned.commit((draft) => {
-                    if (!pinned)
-                        return draft.delete(sessionId);
-                    if (draft.get(sessionId) === true)
-                        return false;
-                    draft.set(sessionId, true);
-                    return true;
-                });
-                if (!ok)
-                    throw new SessionError("storage", `LocalSessionStore: pin sidecar write failed for session ${sessionId} — the pin was not recorded`);
-            }
-            const rollups = await this.runRollups();
             await this.loadRowSidecars();
-            const meta = await this.listedMeta(sessionId);
-            return meta === undefined ? undefined : this.summaryOf(meta, rollups);
+            const locked = await this.lockedRowOf(sessionId);
+            const mark = how.row.log === undefined || locked === undefined ? undefined : sessionLogMarkOf((await this.exportEntries(sessionId)) ?? []);
+            const verdict = judgeSessionRowWrite(sessionId, how, locked, () => {
+                if (mark === undefined)
+                    throw new Error(`LocalSessionStore.writeSessionRowCells: the judge asked session ${sessionId}'s log mark, but the expectation carries none`);
+                return mark;
+            });
+            switch (verdict) {
+                case "absent":
+                    return { kind: "absent" };
+                case "mirror":
+                    return { kind: "mirror" };
+                case "write":
+                    await this.writeRowCellsHeld(sessionId, cells);
+                    return settleSessionRowWrite(how, verdict, await this.listRowOf(sessionId));
+                case "changed":
+                    return settleSessionRowWrite(how, verdict, await this.listRowOf(sessionId));
+                default: {
+                    const unknownVerdict = verdict;
+                    throw new Error(`LocalSessionStore.writeSessionRowCells: no verdict ${JSON.stringify(unknownVerdict)}`);
+                }
+            }
         });
     }
-    occupiedBy(sessionId, face) {
-        const cell = this.meta.state.entries.get(sessionId);
-        return cell !== undefined && readSessionMetaCell(cell).incarnation === face.incarnation;
+    async lockedRowOf(sessionId) {
+        const meta = this.metaCellOf(sessionId);
+        if (meta === undefined || (await this.listedMeta(sessionId)) === undefined)
+            return undefined;
+        return { owner: meta.owner ?? null, incarnation: incarnationFromCell(sessionId, meta.incarnation, "absent"), placed: false, mirror: meta.execution?.role === "mirror", cells: this.rowCellsOf(sessionId) };
+    }
+    rowCellsOf(sessionId) {
+        return { title: this.titles.state.entries.get(sessionId) ?? null, pinned: this.pinned.state.entries.get(sessionId) === true };
+    }
+    async writeRowCellsHeld(sessionId, cells) {
+        const { title, pinned } = cells;
+        if (title !== undefined) {
+            const ok = await this.titles.commit((draft) => {
+                if (title === null)
+                    return draft.delete(sessionId);
+                if (draft.get(sessionId) === title)
+                    return false;
+                draft.set(sessionId, title);
+                return true;
+            });
+            if (!ok)
+                throw new SessionError("storage", `LocalSessionStore: title sidecar write failed for session ${sessionId} — the title was not recorded`);
+        }
+        if (pinned !== undefined) {
+            const ok = await this.pinned.commit((draft) => {
+                if (!pinned)
+                    return draft.delete(sessionId);
+                if (draft.get(sessionId) === true)
+                    return false;
+                draft.set(sessionId, true);
+                return true;
+            });
+            if (!ok)
+                throw new SessionError("storage", `LocalSessionStore: pin sidecar write failed for session ${sessionId} — the pin was not recorded`);
+        }
+    }
+    async listRowOf(sessionId) {
+        await this.loadRowSidecars();
+        const listed = await this.listedMeta(sessionId);
+        const meta = this.metaCellOf(sessionId);
+        if (listed === undefined || meta === undefined)
+            return undefined;
+        return { row: await this.summaryOf(listed, await this.runRollups()), occupant: { owner: meta.owner ?? null, incarnation: incarnationFromCell(sessionId, meta.incarnation, "absent") } };
     }
     async sessionSummaryOf(sessionId) {
         await this.loadRowSidecars();
@@ -472,6 +646,8 @@ export class LocalSessionStore {
                     throw e;
             }
             await this.meta.ensureLoaded();
+            if (isForkCreatedCell(this.metaCellOf(sessionId)))
+                throw new SessionForkInProgressError(sessionId);
             const session = await this.repo.create({ id: sessionId });
             await this.writeMeta(sessionId, (before) => ({ incarnation: mintSessionIncarnation(), owner: before !== undefined && ownerRecorded(before) ? (readSessionMetaCell(before).owner ?? null) : null }));
             return this.handOut(sessionId, session);
@@ -489,13 +665,17 @@ export class LocalSessionStore {
                 return;
             assertFirstOwnerWritable(sessionId, owner);
             const existed = await this.existsInRepo(sessionId);
+            if (!existed && isForkCreatedCell(this.metaCellOf(sessionId)))
+                throw new SessionForkInProgressError(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 (claim)
+                    return before === undefined ? { incarnation: mintSessionIncarnation(), owner } : cellWith(before, { owner });
+                if (!existed)
+                    return { incarnation: mintSessionIncarnation(), owner };
+                return before === undefined ? { incarnation: mintSessionIncarnation() } : undefined;
             });
             if (!existed && wrote)
                 await this.repo.create({ id: sessionId });
@@ -544,17 +724,29 @@ export class LocalSessionStore {
     }
     async summaryOf(meta, rollups) {
         const firstActivityAt = meta.createdAt || new Date(0).toISOString();
+        const owner = this.ownerCellOf(meta.id);
+        const cells = this.rowCellsOf(meta.id);
+        const rowTag = this.rowTagKeyOf(meta.id, owner, cells);
+        const lastActivityAt = this.lastActivity.get(meta.id) ?? firstActivityAt;
+        const objectivePreview = await this.previewOf(meta);
         return {
             sessionId: meta.id,
-            owner: this.ownerCellOf(meta.id),
-            lastActivityAt: this.lastActivity.get(meta.id) ?? firstActivityAt,
+            owner,
+            lastActivityAt,
             firstActivityAt,
-            objectivePreview: await this.previewOf(meta),
+            objectivePreview,
             ...this.runProjectionOf(meta.id, rollups),
-            title: this.titles.state.entries.get(meta.id) ?? null,
-            pinned: this.pinned.state.entries.get(meta.id) === true,
+            title: cells.title,
+            pinned: cells.pinned,
+            ...rowTag,
         };
     }
+    rowTagKeyOf(sessionId, owner, cells) {
+        const meta = this.metaCellOf(sessionId);
+        if (meta === undefined)
+            return {};
+        return sessionRowTagKey({ sessionId, owner, incarnation: incarnationFromCell(sessionId, meta.incarnation, "absent"), cells });
+    }
     async runRollups() {
         const rows = await this.runs.listSessions({ limit: Number.MAX_SAFE_INTEGER });
         return new Map(rows.map((r) => [r.sessionId, { runCount: r.runCount, lastStatus: r.lastStatus, lastRunId: r.lastRunId, ...(r.lastTaskRunId !== undefined ? { lastTaskRunId: r.lastTaskRunId } : {}) }]));
@@ -579,24 +771,52 @@ export class LocalSessionStore {
         }
     }
     async fork(sourceId, owner) {
+        return forkByFreshId((s, o, t) => this.forkTo(s, o, t), sourceId, owner);
+    }
+    async forkTo(sourceId, owner, target) {
         await this.meta.ensureLoaded();
-        return this.withSessionWriteLock(sourceId, async () => {
-            const source = this.meta.state.entries.get(sourceId);
-            const forkOwner = forkOwnerOf(owner, source === undefined ? undefined : readSessionMetaCell(source).owner);
+        if (target.id === sourceId)
+            return this.withSessionWriteLock(sourceId, () => this.forkToHeld(sourceId, owner, target));
+        const [first, second] = sourceId < target.id ? [sourceId, target.id] : [target.id, sourceId];
+        return this.withSessionWriteLock(first, () => this.withSessionWriteLock(second, () => this.forkToHeld(sourceId, owner, target)));
+    }
+    async forkToHeld(sourceId, owner, target) {
+        const sourceMeta = { id: sourceId, createdAt: "" };
+        let forkOptions;
+        try {
+            forkOptions = await settledForkOptions(await this.repo.open(sourceMeta));
+        }
+        catch (e) {
+            if (isNotFound(e))
+                return null;
+            throw e;
+        }
+        const forkOwner = forkOwnerOf(owner, this.metaCellOf(sourceId)?.owner);
+        const existing = this.metaCellOf(target.id);
+        const targetArchived = await this.existsInRepo(target.id);
+        const copy = () => this.repo.fork(sourceMeta, { ...forkOptions, id: target.id });
+        if (existing === undefined && !targetArchived) {
+            const created = await this.writeMeta(target.id, (before) => before !== undefined ? undefined : { incarnation: mintSessionIncarnation(), ...(forkOwner !== undefined ? { owner: forkOwner } : {}), ...(target.key !== undefined ? { forkKey: target.key } : {}) });
+            if (!created)
+                throw new SessionError("storage", `LocalSessionStore: fork target ${target.id} gained a session-meta cell under its own write lock — refusing to guess`);
             try {
-                const sourceMeta = { id: sourceId, createdAt: "" };
-                const forkOptions = await settledForkOptions(await this.repo.open(sourceMeta));
-                const session = await this.repo.fork(sourceMeta, forkOptions);
-                const id = (await session.getMetadata()).id;
-                await this.writeMeta(id, () => (forkOwner === undefined ? mintSessionIncarnation() : { incarnation: mintSessionIncarnation(), owner: forkOwner }));
-                return id;
+                await copy();
             }
-            catch (e) {
-                if (isNotFound(e))
-                    return null;
-                throw e;
+            catch (err) {
+                try {
+                    await this.dropMeta(target.id);
+                }
+                catch (dropErr) {
+                    throw new SessionError("storage", `LocalSessionStore: fork into ${target.id} failed while copying (${err instanceof Error ? err.message : String(err)}) and its target cell could not be withdrawn (${dropErr instanceof Error ? dropErr.message : String(dropErr)}) — the target stays in the fork-in-progress state; retry the same fork or delete the session`, err instanceof Error ? err : undefined);
+                }
+                throw err;
             }
-        });
+            return { outcome: "created", id: target.id };
+        }
+        const out = classifyForkTarget(target, { owner: existing?.owner, forkKey: existing?.forkKey }, forkOwner);
+        if (out.outcome === "replayed" && !targetArchived)
+            await copy();
+        return out;
     }
     async exportEntries(sessionId) {
         if (!this.repo.exportEntries)
@@ -627,43 +847,91 @@ export class LocalSessionStore {
         return gen();
     }
     async importEntries(sessionId, owner, entries) {
-        await this.withImportLock(sessionId, owner, (importer) => this.importHeld(sessionId, importer, entries, "in_place"));
+        await this.withImportLock(sessionId, owner, (importer) => this.importHeld(sessionId, importer, entries, "create"));
     }
     async replaceEntries(sessionId, owner, entries) {
-        await this.withImportLock(sessionId, owner, (importer) => this.importHeld(sessionId, importer, entries, "purge_first"));
+        await this.withImportLock(sessionId, owner, (importer) => this.importHeld(sessionId, importer, entries, "replace"));
     }
     async withImportLock(sessionId, owner, body) {
         const importer = importerOwnerOf(owner);
         return this.withSessionWriteLock(sessionId, () => body(importer));
     }
-    async importHeld(sessionId, owner, entries, swap) {
-        const row = await this.metaOf(sessionId);
-        if (row !== undefined && !ownerEq(row.owner ?? null, owner)) {
-            throw new SessionError("conflict", `session ${sessionId} is not the importer's row (its owner cell differs) — nothing was written`);
-        }
-        await this.swapLogHeld(sessionId, entries, swap);
-        await this.finishSwap(sessionId, owner);
-    }
-    async swapLogHeld(sessionId, entries, swap) {
+    async importHeld(sessionId, owner, entries, landing) {
         if (!this.repo.importEntries)
             throw new SessionError("storage", "session import is not supported by this local backend");
-        const archive = await this.archiveToSwap(sessionId, entries, swap);
-        await this.repo.importEntries(sessionId, archive?.owner ?? undefined, entries, { expect: { row: archive } });
-    }
-    async archiveToSwap(sessionId, entries, swap) {
-        switch (swap) {
-            case "in_place":
-                return (await this.repo.headOf(sessionId)) ?? null;
-            case "purge_first":
-                validateEntriesForImport(entries);
-                await this.repo.delete({ id: sessionId, createdAt: "" });
-                return null;
+        await this.meta.ensureLoaded();
+        validateEntriesForImport(entries);
+        const current = this.metaCellOf(sessionId);
+        if (current?.execution?.role === "writer")
+            throw new SessionWriterPresentError(sessionId, current.execution.lane);
+        if (await this.forkingOf(sessionId, current))
+            throw new SessionForkInProgressError(sessionId);
+        if (!(await this.importMayLand(sessionId, current, owner, landing)))
+            throw importRowRefused(sessionId, landing);
+        const prior = await this.landImportCell(sessionId, owner);
+        switch (landing) {
+            case "create":
+            case "judged":
+                try {
+                    const archive = (await this.repo.headOf(sessionId)) ?? null;
+                    await this.repo.importEntries(sessionId, archive?.owner ?? undefined, entries, { expect: { row: archive } });
+                }
+                catch (err) {
+                    await this.withdrawImportCell(sessionId, prior, err);
+                    throw err;
+                }
+                break;
+            case "replace":
+                try {
+                    await this.repo.delete({ id: sessionId, createdAt: "" });
+                }
+                catch (e) {
+                    if (!isNotFound(e))
+                        throw e;
+                }
+                await this.repo.importEntries(sessionId, undefined, entries, { expect: { row: null } });
+                break;
+            default: {
+                const unknownLanding = landing;
+                throw new Error(`LocalSessionStore: no import landing ${JSON.stringify(unknownLanding)}`);
+            }
         }
-    }
-    async finishSwap(sessionId, owner) {
-        await this.writeMeta(sessionId, (before) => ({ incarnation: carriedIncarnation(sessionId, before === undefined ? undefined : readSessionMetaCell(before)), owner }));
         await this.touch(sessionId);
     }
+    async importMayLand(sessionId, current, owner, landing) {
+        switch (landing) {
+            case "create":
+                return current === undefined && !(await this.existsInRepo(sessionId));
+            case "replace":
+                return current !== undefined ? ownerEq(current.owner ?? null, owner) : ownerEq(null, owner) || !(await this.existsInRepo(sessionId));
+            case "judged":
+                return true;
+            default: {
+                const unknownLanding = landing;
+                throw new Error(`LocalSessionStore: no import landing ${JSON.stringify(unknownLanding)}`);
+            }
+        }
+    }
+    async landImportCell(sessionId, owner) {
+        let prior;
+        await this.writeMeta(sessionId, (before) => {
+            prior = before;
+            const cells = carriedRowCells(sessionId, before === undefined ? undefined : readSessionMetaCell(before));
+            return { incarnation: cells.incarnation, owner, execution: MIRROR_CELL, ...(cells.forkKey !== null ? { forkKey: cells.forkKey } : {}) };
+        });
+        return prior;
+    }
+    async withdrawImportCell(sessionId, prior, cause) {
+        try {
+            if (prior === undefined)
+                await this.dropMeta(sessionId);
+            else
+                await this.writeMeta(sessionId, () => prior);
+        }
+        catch (withdrawErr) {
+            throw new SessionError("storage", `LocalSessionStore: import into ${sessionId} failed (${cause instanceof Error ? cause.message : String(cause)}) and its session-meta cell could not be put back (${withdrawErr instanceof Error ? withdrawErr.message : String(withdrawErr)}) — the session reads as a mirror until the next push`, cause instanceof Error ? cause : undefined);
+        }
+    }
     beginImportStaging(realSessionId, token) {
         const h = new LocalStagingHandle(this, realSessionId, stagingIdFor(realSessionId, token));
         this.stagings.set(h.stagingId, h);
@@ -680,6 +948,8 @@ export class LocalSessionStore {
             const current = await this.metaOf(sessionId);
             if (!ownerCellIs(opts.expectedOwner, current === undefined ? undefined : (current.owner ?? null)))
                 throw new StagedCommitOwnerChangedError(sessionId);
+            if (await this.forkingOf(sessionId, current))
+                throw new SessionForkInProgressError(sessionId);
             const dstEntries = await this.exportEntries(sessionId);
             const rel = classifySyncRelationshipByIds(staged.map((e) => e.id), dstEntries === null ? null : dstEntries.map((e) => e.id));
             if ((rel.relation === "fork" || rel.relation === "stale") && opts.resolution !== "overwrite-dst") {
@@ -692,10 +962,15 @@ export class LocalSessionStore {
                     throw new SyncConflictError(sessionId, contentForkRelation(diverged, rel.newEntryIds));
             }
             const contentEqual = rel.relation === "identical" && identicalIdsAlsoIdenticalContent(staged, dstEntries);
+            if (current?.execution?.role === "writer")
+                throw new SessionWriterPresentError(sessionId, current.execution.lane);
             if (rel.relation !== "identical" || !contentEqual) {
-                await this.swapLogHeld(sessionId, staged, "in_place");
+                await this.importHeld(sessionId, importer, staged, "judged");
+            }
+            else {
+                await this.landImportCell(sessionId, importer);
+                await this.touch(sessionId);
             }
-            await this.finishSwap(sessionId, importer);
             const meta = await this.metaOf(sessionId);
             if (meta === undefined)
                 throw new SessionError("storage", `LocalSessionStore: staged commit for session ${sessionId} left no session face — nothing was settled`);

package/dist/plugins/memory-key-guards.d.ts

@@ -15,6 +15,10 @@ export declare const MEMORY_SLUG_COLUMN_CHARS = 512;
  *  sync_cursor/push_queue/history)。`formatUserScope`/`formatProjScope` 的段编码(百分号转义)会
  *  **膨胀**——非 ASCII principal 编码后可超列宽,故产出处与写口两道都要判。 */
 export declare const MEMORY_SCOPE_COLUMN_CHARS = 190;
+/** memory-sync 店 `sync_cursor.peer` 列宽(两方言 VARCHAR(190) 同宽)—— 中心侧请求的 `peer` 落这一列。两个读者:中心侧验型
+ *  (`memory-sync.ts` `parseMemorySyncRequest`,超宽 400)与客户端的身份铸点(`memory-sync-client.ts` `memorySyncPeerOf`,超宽拒启:
+ *  身份就是请求的 `peer`,装不进这一列的身份每一轮都会被中心拒)。 */
+export declare const MEMORY_SYNC_PEER_COLUMN_CHARS = 190;
 export declare function assertSlugWidth(slug: string): void;
 export declare function assertMemoryScopeWidth(scope: string): void;
 /**

package/dist/plugins/memory-key-guards.js

@@ -1,5 +1,6 @@
 export const MEMORY_SLUG_COLUMN_CHARS = 512;
 export const MEMORY_SCOPE_COLUMN_CHARS = 190;
+export const MEMORY_SYNC_PEER_COLUMN_CHARS = 190;
 function widthChars(v) {
     return [...v].length;
 }