@giovannijecha/jecode 0.8.4 → 0.8.6

package/dist/sessions/store.js

@@ -3,117 +3,61 @@
 // Each node is its own atomically replaced file. The head is advanced only
 // after that node is durable, so a crash leaves either the prior checkpoint or
 // one strictly recoverable mutation -- never an ambiguous partial history.
-import { createHash, randomUUID } from "node:crypto";
-import { chmod, lstat, mkdir, open, opendir, readFile, readdir, realpath, rename, rm, } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { lstat, rename } from "node:fs/promises";
 import * as path from "node:path";
 import { atomicWrite } from "../atomic.js";
-import { CONVERSATION_LIMITS, ConversationTree } from "../conversation.js";
+import { stableFileExpectation } from "../bounded-file.js";
+import { assertDirectoryAnchor, captureDirectDirectory, createPrivateDirectory, } from "../directory-anchor.js";
+import { sameFileIdentity } from "../file-identity.js";
 import { userDataPath } from "../user-data.js";
-import { advanceSessionCatalog, catalogMatches, decodeSessionCatalog, encodeSessionCatalog, sameSessionHead, sessionCatalog, SESSION_CATALOG_BYTES, SESSION_CATALOG_FILE, SESSION_CHECKPOINT_FILE, } from "./catalog.js";
-import { decodeHead, decodeMeta, decodeNode, encodeHead, encodeMeta, encodeNode, SESSION_FILE_LIMITS, SESSION_SCHEMA, } from "./codec.js";
-import { leaseOwner, leaseToken, pidIsAlive, removeLease, sessionLease, } from "./lease.js";
-const DIRECTORY_MODE = 0o700;
-const FILE_MODE = 0o600;
-const MAX_CATALOG_ENTRIES = 4_096;
-const CATALOG_READ_CONCURRENCY = 8;
-const NODE_READ_CONCURRENCY = 4;
-const SESSION_NAME = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/;
-const NODE_NAME = /^(\d{6})\.json$/;
-const ATOMIC_NODE_TEMP = /^\.\d{6}\.json\.\d+\.[a-f0-9-]+\.tmp$/;
+import { assertSessionId, SessionBucket } from "./bucket.js";
+import { SessionCatalogIO } from "./catalog-io.js";
+import { advanceSessionCatalog, encodeSessionCatalog, sameSessionHead, sessionCatalog, SESSION_CATALOG_FILE, SESSION_CHECKPOINT_FILE, } from "./catalog.js";
+import { decodeHead, encodeHead, encodeMeta, encodeNode, SESSION_FILE_LIMITS, SESSION_SCHEMA, } from "./codec.js";
+import { claimLeaseDirectory, createLeaseDirectory, leaseFromGeneration, leaseOwner, leaseToken, pidIsAlive, removeLegacyLeaseExclusive, removeLease, sessionLease, sessionLeaseOwns, } from "./lease.js";
+import { assertMissingNode, DIRECTORY_MODE, FILE_MODE, nodeName, readJson, removeTemporaryDirectory, } from "./files.js";
+import { loadSession } from "./load.js";
+import { assertSharedNodes, assertSnapshot } from "./snapshot.js";
 export class DurableSessionStore {
     workspaceRoot;
     workspaceDigest;
-    #sessionsRoot;
     #bucket;
-    constructor(workspaceRoot, sessionsRoot) {
-        this.workspaceRoot = workspaceRoot;
-        this.workspaceDigest = digestWorkspace(workspaceRoot);
-        this.#sessionsRoot = sessionsRoot;
-        this.#bucket = path.join(sessionsRoot, this.workspaceDigest);
+    #catalog;
+    #hooks;
+    #leaseScope = Object.freeze({});
+    constructor(bucket, hooks) {
+        this.workspaceRoot = bucket.workspaceRoot;
+        this.workspaceDigest = bucket.workspaceDigest;
+        this.#bucket = bucket;
+        this.#hooks = hooks;
+        this.#catalog = new SessionCatalogIO(bucket, {
+            claim: (id) => this.claim(id),
+            load: (id, lease) => this.load(id, lease),
+        });
     }
-    static async open(workspaceRoot, sessionsRoot = userDataPath("sessions")) {
-        const canonical = await realpath(path.resolve(workspaceRoot));
-        return new DurableSessionStore(canonical, path.resolve(sessionsRoot));
+    static async open(workspaceRoot, sessionsRoot = userDataPath("sessions"), hooks = {}) {
+        return new DurableSessionStore(await SessionBucket.open(workspaceRoot, sessionsRoot), hooks);
     }
     async list(limit = 32) {
-        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 64) {
-            throw new Error("session catalogue limit is invalid");
-        }
-        const names = await catalogNames(this.#bucket);
-        const catalog = [];
-        for (let start = 0; start < names.length; start += CATALOG_READ_CONCURRENCY) {
-            const batch = await Promise.all(names.slice(start, start + CATALOG_READ_CONCURRENCY)
-                .map(async (id) => {
-                return await this.#catalogEntry(id);
-            }));
-            catalog.push(...batch.filter((entry) => entry !== undefined));
-        }
-        return catalog
-            .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt) || right.id.localeCompare(left.id))
-            .slice(0, limit);
+        return this.#catalog.list(limit);
     }
-    async load(id) {
-        assertSessionId(id);
-        const directory = this.#sessionDirectory(id);
-        await assertDirectory(directory);
-        const meta = decodeMeta(await readJson(path.join(directory, "meta.json"), SESSION_FILE_LIMITS.metadataBytes));
-        assertSessionWorkspace(meta, id, this.workspaceRoot, this.workspaceDigest);
-        let head = decodeHead(await readJson(path.join(directory, "head.json"), SESSION_FILE_LIMITS.metadataBytes));
-        const stored = await readNodes(path.join(directory, "nodes"));
-        const ahead = stored.filter((entry) => entry.sequence > head.sequence);
-        if (ahead.some((entry) => entry.sequence !== head.sequence + 1) || ahead.length > 1) {
-            throw new Error("session has an ambiguous incomplete checkpoint");
-        }
-        const byId = new Map(stored.map((entry) => [entry.node.id, entry]));
-        const headed = byId.get(head.nodeId);
-        if (headed === undefined)
-            throw new Error("session head is missing its conversation node");
-        if (ahead.length === 0) {
-            if (headed.sequence !== head.sequence || headed.node.revision !== head.revision ||
-                headed.node.parentId !== head.parentId) {
-                throw new Error("session head does not match its conversation node");
-            }
-        }
-        else {
-            const candidate = ahead[0];
-            const replacesHead = candidate.node.id === head.nodeId &&
-                candidate.node.parentId === head.parentId &&
-                candidate.node.revision === head.revision + 1;
-            const candidateParent = byId.get(candidate.node.parentId);
-            const extendsTree = candidate.node.id === stored.length &&
-                candidate.node.revision === 1 && candidateParent !== undefined &&
-                candidateParent.sequence <= head.sequence;
-            if (!replacesHead && !extendsTree) {
-                throw new Error("session checkpoint cannot be recovered safely");
-            }
-            head = Object.freeze({
-                version: SESSION_SCHEMA,
-                sequence: candidate.sequence,
-                nodeId: candidate.node.id,
-                parentId: candidate.node.parentId,
-                revision: candidate.node.revision,
-                updatedAt: candidate.updatedAt,
-            });
-            await atomicWrite(path.join(directory, "head.json"), encodeHead(head), {
-                mode: FILE_MODE,
-                validate: async () => assertDirectory(directory),
-            });
-        }
-        const nodes = stored.map((entry) => entry.node);
-        const conversation = ConversationTree.restore(nodes, head.nodeId);
-        const catalog = sessionCatalog(meta, head, conversation);
-        return Object.freeze({ meta, head, conversation, catalog });
+    async load(id, recoveryLease) {
+        return loadSession(this.#bucket, id, this.#leaseScope, recoveryLease);
     }
-    async publish(conversation, claim) {
+    async publish(conversation, claim, reservedId) {
         const active = conversation.activeNode;
         if (active === undefined)
             throw new Error("an empty conversation cannot be persisted");
-        await this.#ensureBucket();
+        await this.#bucket.assert();
         const now = new Date().toISOString();
-        const id = sessionId(now);
+        const id = reservedId ?? reserveSessionId(now);
+        assertSessionId(id);
         const token = claim === true ? leaseToken() : undefined;
-        const temporary = path.join(this.#bucket, `.${id}.${randomUUID()}.tmp`);
-        const target = this.#sessionDirectory(id);
+        let leaseGeneration;
+        let temporaryAnchor;
+        const temporary = path.join(this.#bucket.anchor.path, `.${id}.${randomUUID()}.tmp`);
+        const target = this.#bucket.directory(id);
         const meta = Object.freeze({
             version: SESSION_SCHEMA,
             id,
@@ -131,43 +75,76 @@ export class DurableSessionStore {
         });
         const catalog = sessionCatalog(meta, head, conversation);
         try {
-            await makePrivateDirectory(temporary);
+            temporaryAnchor = await createPrivateDirectory(temporary, "temporary session directory", DIRECTORY_MODE);
             const nodes = path.join(temporary, "nodes");
-            await makePrivateDirectory(nodes);
+            const nodesAnchor = await createPrivateDirectory(nodes, "temporary session node directory", DIRECTORY_MODE);
+            const validateTemporary = async () => {
+                await this.#bucket.assert();
+                await assertDirectoryAnchor(temporaryAnchor);
+                await assertDirectoryAnchor(nodesAnchor);
+            };
             for (let index = 0; index < conversation.nodes.length; index++) {
                 const node = conversation.nodes[index];
-                await atomicWrite(path.join(nodes, nodeName(node.id)), encodeNode(node, index + 1, now), { mode: FILE_MODE });
+                await atomicWrite(path.join(nodes, nodeName(node.id)), encodeNode(node, index + 1, now), { mode: FILE_MODE, validate: async () => validateTemporary() });
             }
-            await atomicWrite(path.join(temporary, "meta.json"), encodeMeta(meta), { mode: FILE_MODE });
-            await atomicWrite(path.join(temporary, "head.json"), encodeHead(head), { mode: FILE_MODE });
-            await atomicWrite(path.join(temporary, SESSION_CATALOG_FILE), encodeSessionCatalog(catalog), { mode: FILE_MODE });
+            await atomicWrite(path.join(temporary, "meta.json"), encodeMeta(meta), {
+                mode: FILE_MODE,
+                validate: async () => validateTemporary(),
+            });
+            await atomicWrite(path.join(temporary, "head.json"), encodeHead(head), {
+                mode: FILE_MODE,
+                validate: async () => validateTemporary(),
+            });
+            await atomicWrite(path.join(temporary, SESSION_CATALOG_FILE), encodeSessionCatalog(catalog), { mode: FILE_MODE, validate: async () => validateTemporary() });
             if (token !== undefined) {
-                await atomicWrite(path.join(temporary, "active"), token, { mode: FILE_MODE });
+                leaseGeneration = await createLeaseDirectory(path.join(temporary, "active"), token);
             }
+            await validateTemporary();
             await rename(temporary, target);
+            await this.#bucket.assert();
+            const targetAnchor = await captureDirectDirectory(target, "session directory");
+            if (!sameFileIdentity(temporaryAnchor.identity, targetAnchor.identity)) {
+                throw new Error("session directory changed while publishing");
+            }
         }
         catch (error) {
-            await removeTemporaryDirectory(temporary, this.#bucket);
+            await removeTemporaryDirectory(temporary, this.#bucket.anchor, temporaryAnchor)
+                .catch(() => undefined);
             throw error;
         }
         const snapshot = Object.freeze({ meta, head, conversation, catalog });
         if (token === undefined)
             return snapshot;
-        const lease = sessionLease(id, path.join(target, "active"), token);
+        if (leaseGeneration === undefined)
+            throw new Error("session lease was not initialized");
+        const lease = sessionLease(id, this.#leaseScope, leaseFromGeneration(path.join(target, "active"), leaseGeneration));
         return Object.freeze({ ...snapshot, lease });
     }
-    async checkpoint(previous, conversation) {
+    async checkpoint(previous, conversation, lease) {
         assertSnapshot(previous, this.workspaceRoot, this.workspaceDigest);
         const id = previous.meta.id;
-        const directory = this.#sessionDirectory(id);
-        await assertDirectory(directory);
+        if (!sessionLeaseOwns(lease, id, this.#leaseScope)) {
+            throw new Error("session checkpoint requires exclusive ownership");
+        }
+        await lease.assertOwned();
+        const directory = this.#bucket.directory(id);
+        const directoryAnchor = await this.#bucket.captureSession(id);
         const nodesDirectory = path.join(directory, "nodes");
+        const nodesAnchor = await captureDirectDirectory(nodesDirectory, "session node directory");
         const validateNodesDirectory = async () => {
-            await assertDirectory(directory);
-            await assertDirectory(nodesDirectory);
+            await Promise.all([
+                lease.assertOwned(),
+                this.#bucket.assert(),
+                assertDirectoryAnchor(directoryAnchor),
+                assertDirectoryAnchor(nodesAnchor),
+            ]);
         };
         await validateNodesDirectory();
-        const currentHead = decodeHead(await readJson(path.join(directory, "head.json"), SESSION_FILE_LIMITS.metadataBytes));
+        const headFile = path.join(directory, "head.json");
+        const headExpectation = stableFileExpectation(await lstat(headFile, { bigint: true }));
+        await validateNodesDirectory();
+        const currentHead = decodeHead(await readJson(headFile, SESSION_FILE_LIMITS.metadataBytes, headExpectation));
+        await validateNodesDirectory();
         if (!sameSessionHead(currentHead, previous.head)) {
             throw new Error("session head changed after its verified snapshot");
         }
@@ -202,293 +179,121 @@ export class DurableSessionStore {
         });
         const catalog = advanceSessionCatalog(previous.catalog, previous.meta, head, conversation);
         const checkpointToken = leaseToken();
-        await atomicWrite(path.join(directory, SESSION_CHECKPOINT_FILE), checkpointToken, { mode: FILE_MODE, validate: async () => assertDirectory(directory) });
-        await atomicWrite(path.join(nodesDirectory, nodeName(active.id)), encodeNode(active, head.sequence, now), { mode: FILE_MODE, validate: async () => validateNodesDirectory() });
-        await atomicWrite(path.join(directory, "head.json"), encodeHead(head), {
-            mode: FILE_MODE,
-            validate: async () => assertDirectory(directory),
-        });
-        await this.#writeCatalog(previous.meta.id, catalog, checkpointToken).catch(() => undefined);
-        // Once the canonical head is durable, a missing summary is detectable by
-        // its head mismatch and can be rebuilt without retaining a live marker.
-        await removeLease(path.join(directory, SESSION_CHECKPOINT_FILE), checkpointToken);
-        return Object.freeze({ meta: previous.meta, head, conversation, catalog });
-    }
-    async claim(id) {
-        assertSessionId(id);
-        await assertDirectory(this.#sessionDirectory(id));
-        const file = path.join(this.#sessionDirectory(id), "active");
-        const token = leaseToken();
-        for (let attempt = 0; attempt < 2; attempt++) {
-            try {
-                const handle = await open(file, "wx", FILE_MODE);
+        const checkpointFile = path.join(directory, SESSION_CHECKPOINT_FILE);
+        await this.#hooks.beforeCheckpointLease?.();
+        await validateNodesDirectory();
+        const checkpointLease = await claimLeaseDirectory(checkpointFile, checkpointToken);
+        if (checkpointLease === undefined)
+            throw new Error("session checkpoint is already active");
+        let primaryFailure;
+        try {
+            await this.#hooks.afterCheckpointLease?.();
+            const assertBaseHead = async () => {
+                await Promise.all([checkpointLease.assertOwned(), validateNodesDirectory()]);
+                let verified;
                 try {
-                    await handle.writeFile(token, "utf8");
-                    await handle.sync();
+                    verified = decodeHead(await readJson(headFile, SESSION_FILE_LIMITS.metadataBytes, headExpectation));
                 }
-                finally {
-                    await handle.close();
+                catch (error) {
+                    throw new Error("session head changed after its verified snapshot", { cause: error });
                 }
-                return sessionLease(id, file, token);
-            }
-            catch (error) {
-                if (error.code !== "EEXIST")
-                    throw error;
-                const owner = await leaseOwner(file);
-                if (owner !== undefined && pidIsAlive(owner.pid)) {
-                    throw new Error("session is already open in another Jecode process");
-                }
-                if (owner !== undefined) {
-                    await removeLease(file, owner.token);
+                await Promise.all([checkpointLease.assertOwned(), validateNodesDirectory()]);
+                if (!sameSessionHead(verified, previous.head)) {
+                    throw new Error("session head changed after its verified snapshot");
                 }
+            };
+            await assertBaseHead();
+            if (extendsTree) {
+                await assertMissingNode(path.join(nodesDirectory, nodeName(active.id)), validateNodesDirectory);
             }
+            // Publish the next head's index first. Until the head commits, listing
+            // treats it as suspect and loads the tree after ownership is released.
+            // A failed node/head write must never leave an apparently current index.
+            await atomicWrite(path.join(directory, SESSION_CATALOG_FILE), encodeSessionCatalog(catalog), {
+                mode: FILE_MODE,
+                validate: async () => assertBaseHead(),
+            });
+            await atomicWrite(path.join(nodesDirectory, nodeName(active.id)), encodeNode(active, head.sequence, now), {
+                mode: FILE_MODE,
+                validate: async (phase) => {
+                    await assertBaseHead();
+                    if (extendsTree && phase === "before-rename") {
+                        await assertMissingNode(path.join(nodesDirectory, nodeName(active.id)), validateNodesDirectory);
+                    }
+                },
+            });
+            await atomicWrite(path.join(directory, "head.json"), encodeHead(head), {
+                mode: FILE_MODE,
+                validate: async () => assertBaseHead(),
+            });
+            return Object.freeze({ meta: previous.meta, head, conversation, catalog });
         }
-        throw new Error("session could not be claimed");
-    }
-    #sessionDirectory(id) {
-        return path.join(this.#bucket, id);
-    }
-    async #ensureBucket() {
-        await makePrivateDirectory(this.#sessionsRoot);
-        await makePrivateDirectory(this.#bucket);
-    }
-    async #leaseIsActive(id) {
-        const owner = await leaseOwner(path.join(this.#sessionDirectory(id), "active"));
-        return owner !== undefined && pidIsAlive(owner.pid);
-    }
-    async #catalogEntry(id) {
-        try {
-            const directory = this.#sessionDirectory(id);
-            await assertDirectory(directory);
-            const checkpointFile = path.join(directory, SESSION_CHECKPOINT_FILE);
-            // A second head read closes the only useful race: a checkpoint landing
-            // between the small record reads. A changing marker gets one retry.
-            for (let attempt = 0; attempt < 2; attempt++) {
-                const checkpointBefore = await leaseOwner(checkpointFile);
-                try {
-                    const [metaValue, headValue, catalogValue] = await Promise.all([
-                        readJson(path.join(directory, "meta.json"), SESSION_FILE_LIMITS.metadataBytes),
-                        readJson(path.join(directory, "head.json"), SESSION_FILE_LIMITS.metadataBytes),
-                        readJson(path.join(directory, SESSION_CATALOG_FILE), SESSION_CATALOG_BYTES),
-                    ]);
-                    const meta = decodeMeta(metaValue);
-                    const head = decodeHead(headValue);
-                    const storedCatalog = decodeSessionCatalog(catalogValue);
-                    assertSessionWorkspace(meta, id, this.workspaceRoot, this.workspaceDigest);
-                    const confirmedHead = decodeHead(await readJson(path.join(directory, "head.json"), SESSION_FILE_LIMITS.metadataBytes));
-                    const checkpointAfter = await leaseOwner(checkpointFile);
-                    if (!sameLease(checkpointBefore, checkpointAfter))
-                        continue;
-                    if (!sameSessionHead(head, confirmedHead) ||
-                        !catalogMatches(storedCatalog, meta, head))
-                        break;
-                    if (checkpointAfter !== undefined && !pidIsAlive(checkpointAfter.pid))
-                        break;
-                    const active = await this.#leaseIsActive(id) || checkpointAfter !== undefined;
-                    return catalogEntry(storedCatalog, active);
-                }
-                catch {
-                    break;
+        catch (error) {
+            primaryFailure = error;
+            throw error;
+        }
+        finally {
+            try {
+                if (!(await checkpointLease.release()) && primaryFailure === undefined) {
+                    throw new Error("session checkpoint ownership was lost");
                 }
             }
-            // Missing, stale, or malformed summaries are rebuilt only while the
-            // session is idle. Selecting a session still performs this strict load.
-            const checkpoint = await leaseOwner(checkpointFile);
-            if (await this.#leaseIsActive(id) ||
-                (checkpoint !== undefined && pidIsAlive(checkpoint.pid)))
-                return undefined;
-            const snapshot = await this.load(id);
-            await this.#writeCatalog(id, snapshot.catalog, checkpoint?.token).catch(() => undefined);
-            const currentCheckpoint = await leaseOwner(checkpointFile);
-            const active = await this.#leaseIsActive(id) ||
-                (currentCheckpoint !== undefined && pidIsAlive(currentCheckpoint.pid));
-            return catalogEntry(snapshot.catalog, active);
-        }
-        catch {
-            // Corrupt, unsafe, active-without-a-summary, or foreign data never
-            // becomes a resume candidate.
-            return undefined;
-        }
-    }
-    async #writeCatalog(id, catalog, checkpointToken) {
-        const directory = this.#sessionDirectory(id);
-        const validate = async () => {
-            await assertDirectory(directory);
-            const currentHead = decodeHead(await readJson(path.join(directory, "head.json"), SESSION_FILE_LIMITS.metadataBytes));
-            if (!sameSessionHead(currentHead, catalog.head)) {
-                throw new Error("session head changed while updating its catalogue");
+            catch (error) {
+                if (primaryFailure === undefined)
+                    throw error;
             }
-        };
-        await atomicWrite(path.join(directory, SESSION_CATALOG_FILE), encodeSessionCatalog(catalog), { mode: FILE_MODE, validate });
-        if (checkpointToken !== undefined) {
-            await removeLease(path.join(directory, SESSION_CHECKPOINT_FILE), checkpointToken);
         }
     }
-}
-async function catalogNames(directory) {
-    try {
-        await assertDirectory(directory);
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return [];
-        throw error;
-    }
-    const names = [];
-    let entries = 0;
-    const handle = await opendir(directory);
-    for await (const entry of handle) {
-        entries++;
-        if (entries > MAX_CATALOG_ENTRIES) {
-            throw new Error(`session catalogue exceeds ${MAX_CATALOG_ENTRIES} entries`);
+    async claim(id) {
+        assertSessionId(id);
+        const directory = this.#bucket.directory(id);
+        const directoryAnchor = await this.#bucket.captureSession(id);
+        const validateDirectory = async () => {
+            await this.#bucket.assertSession(directoryAnchor);
+        };
+        await validateDirectory();
+        const file = path.join(directory, "active");
+        const previous = await leaseOwner(file);
+        await validateDirectory();
+        if (previous?.legacy === true) {
+            if (pidIsAlive(previous.pid)) {
+                throw new Error("session is already open in an older Jecode process");
+            }
+            throw new Error("session has a stale legacy active marker; close older Jecode processes and remove it before retrying");
         }
-        if (entry.isDirectory() && SESSION_NAME.test(entry.name))
-            names.push(entry.name);
-    }
-    return names.sort((left, right) => right.localeCompare(left));
-}
-function catalogEntry(catalog, active) {
-    if (catalog.resumeNodeId === 0)
-        return undefined;
-    return Object.freeze({
-        id: catalog.id,
-        createdAt: catalog.createdAt,
-        updatedAt: catalog.head.updatedAt,
-        turns: catalog.turns,
-        preview: catalog.preview,
-        active,
-    });
-}
-function sameLease(left, right) {
-    return left?.token === right?.token;
-}
-function assertSessionWorkspace(meta, id, workspaceRoot, workspaceDigest) {
-    if (meta.id !== id || meta.workspaceDigest !== workspaceDigest ||
-        workspaceKey(meta.workspaceRoot) !== workspaceKey(workspaceRoot))
-        throw new Error("session belongs to a different workspace");
-}
-function assertSharedNodes(previous, next, replacedId) {
-    for (const node of previous.nodes) {
-        if (node.id === replacedId)
-            continue;
-        const candidate = next.node(node.id);
-        if (candidate !== node) {
-            throw new Error("session checkpoint rewrites prior conversation history");
+        const token = leaseToken();
+        const lease = await claimLeaseDirectory(file, token);
+        if (lease === undefined) {
+            throw new Error("session is already open in another Jecode process");
         }
-    }
-}
-function assertSnapshot(snapshot, workspaceRoot, workspaceDigest) {
-    encodeMeta(snapshot.meta);
-    encodeHead(snapshot.head);
-    encodeSessionCatalog(snapshot.catalog);
-    assertSessionId(snapshot.meta.id);
-    if (snapshot.meta.workspaceDigest !== workspaceDigest ||
-        workspaceKey(snapshot.meta.workspaceRoot) !== workspaceKey(workspaceRoot))
-        throw new Error("session snapshot belongs to a different workspace");
-    const active = snapshot.conversation.activeNode;
-    if (active === undefined ||
-        active.id !== snapshot.head.nodeId ||
-        active.parentId !== snapshot.head.parentId ||
-        active.revision !== snapshot.head.revision ||
-        snapshot.head.sequence < snapshot.conversation.nodes.length)
-        throw new Error("session snapshot does not match its verified head");
-    if (!catalogMatches(snapshot.catalog, snapshot.meta, snapshot.head)) {
-        throw new Error("session snapshot does not match its verified catalogue");
-    }
-}
-async function assertMissingNode(file) {
-    try {
-        await lstat(file);
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return;
-        throw error;
-    }
-    throw new Error("session has an incomplete node outside its verified snapshot");
-}
-async function readNodes(directory) {
-    await assertDirectory(directory);
-    const entries = await readdir(directory, { withFileTypes: true });
-    const names = entries.filter((entry) => entry.isFile() && NODE_NAME.test(entry.name))
-        .map((entry) => entry.name).sort();
-    if (names.length === 0 || names.length > CONVERSATION_LIMITS.nodes) {
-        throw new Error("session has an invalid conversation size");
-    }
-    if (entries.length > CONVERSATION_LIMITS.nodes + 64 ||
-        entries.some((entry) => !entry.isFile() || (!NODE_NAME.test(entry.name) && !ATOMIC_NODE_TEMP.test(entry.name)))) {
-        throw new Error("session node directory contains unsupported data");
-    }
-    const stored = [];
-    const sequences = new Set();
-    for (let start = 0; start < names.length; start += NODE_READ_CONCURRENCY) {
-        const decoded = await Promise.all(names.slice(start, start + NODE_READ_CONCURRENCY)
-            .map(async (name, offset) => {
-            const id = Number(NODE_NAME.exec(name)?.[1]);
-            if (id !== start + offset + 1) {
-                throw new Error("session conversation nodes are not contiguous");
+        const owned = sessionLease(id, this.#leaseScope, lease);
+        const checkpointFile = path.join(directory, SESSION_CHECKPOINT_FILE);
+        try {
+            await owned.assertOwned();
+            await validateDirectory();
+            const checkpoint = await leaseOwner(checkpointFile);
+            if (checkpoint !== undefined && pidIsAlive(checkpoint.pid)) {
+                throw new Error("session has a live checkpoint from another Jecode process");
             }
-            const entry = decodeNode(await readJson(path.join(directory, name), SESSION_FILE_LIMITS.nodeBytes));
-            if (entry.node.id !== id) {
-                throw new Error("session conversation node identity is invalid");
+            if (checkpoint?.legacy === true) {
+                if (!await removeLegacyLeaseExclusive(checkpointFile, checkpoint.token, owned)) {
+                    throw new Error("session legacy checkpoint changed during migration");
+                }
             }
-            return entry;
-        }));
-        for (const entry of decoded) {
-            if (sequences.has(entry.sequence)) {
-                throw new Error("session conversation node identity is invalid");
+            else if (checkpoint !== undefined &&
+                !await removeLease(checkpointFile, checkpoint.token)) {
+                throw new Error("session checkpoint changed during recovery");
             }
-            sequences.add(entry.sequence);
-            stored.push(entry);
+            await owned.assertOwned();
+            await validateDirectory();
         }
-    }
-    return stored;
-}
-async function readJson(file, limit) {
-    const details = await lstat(file);
-    if (details.isSymbolicLink() || !details.isFile() || details.size > limit) {
-        throw new Error("session file is unsafe or too large");
-    }
-    try {
-        return JSON.parse(await readFile(file, "utf8"));
-    }
-    catch {
-        throw new Error("session file is not valid JSON");
-    }
-}
-async function assertDirectory(directory) {
-    const details = await lstat(directory);
-    if (details.isSymbolicLink() || !details.isDirectory()) {
-        throw new Error("session path is not a direct directory");
+        catch (error) {
+            await owned.close().catch(() => undefined);
+            throw error;
+        }
+        return owned;
     }
 }
-async function makePrivateDirectory(directory) {
-    await mkdir(directory, { recursive: true, mode: DIRECTORY_MODE });
-    await assertDirectory(directory);
-    if (process.platform !== "win32")
-        await chmod(directory, DIRECTORY_MODE);
-}
-async function removeTemporaryDirectory(directory, bucket) {
-    const relative = path.relative(bucket, directory);
-    if (relative === "" || relative.startsWith("..") || path.isAbsolute(relative) ||
-        !path.basename(directory).startsWith(".") || !path.basename(directory).endsWith(".tmp"))
-        throw new Error("refusing to remove an unverified session directory");
-    await rm(directory, { recursive: true, force: true });
-}
-function nodeName(id) {
-    return `${String(id).padStart(6, "0")}.json`;
-}
-function sessionId(now) {
+export function reserveSessionId(now = new Date().toISOString()) {
     return `${now.replace(/[-:.]/g, "").replace("Z", "Z")}-${randomUUID()}`;
 }
-function digestWorkspace(workspaceRoot) {
-    return createHash("sha256").update(workspaceKey(workspaceRoot)).digest("hex");
-}
-function workspaceKey(workspaceRoot) {
-    const normalized = path.normalize(workspaceRoot);
-    return process.platform === "win32" ? normalized.toLocaleLowerCase("en-US") : normalized;
-}
-function assertSessionId(id) {
-    if (!SESSION_NAME.test(id))
-        throw new Error("session id is invalid");
-}