@giovannijecha/jecode 0.8.3 → 0.8.5

package/dist/sessions/catalog.js

@@ -0,0 +1,199 @@
+// Small, head-tied projections for the resume catalogue.
+//
+// Conversation nodes remain authoritative and are fully decoded when a
+// session is selected. This auxiliary record lets listing stay independent of
+// every unselected tree's depth; a missing or suspect record falls back to the
+// strict loader and can be rebuilt without changing the session schema.
+import { Buffer } from "node:buffer";
+import { CONVERSATION_LIMITS } from "../conversation.js";
+import { leadingText } from "../text-boundary.js";
+import { decodeHead, encodeHead } from "./codec.js";
+export const SESSION_CATALOG_FILE = "catalog.json";
+export const SESSION_CHECKPOINT_FILE = ".checkpoint";
+export const SESSION_CATALOG_BYTES = 4 * 1_024;
+const CATALOG_SCHEMA = 1;
+const PREVIEW_CODE_UNITS = 160;
+export function sessionCatalog(meta, head, conversation) {
+    assertActiveHead(head, conversation);
+    const resumable = conversation.latestResumable();
+    return own({
+        version: CATALOG_SCHEMA,
+        id: meta.id,
+        workspaceDigest: meta.workspaceDigest,
+        createdAt: meta.createdAt,
+        head,
+        resumeNodeId: resumable?.activeNodeId ?? 0,
+        turns: resumable === undefined ? 0 : selectedTurnCount(resumable),
+        preview: resumable === undefined ? "" : firstUserText(resumable),
+    });
+}
+/** Advance the common linear checkpoint path without walking prior turns. */
+export function advanceSessionCatalog(previous, meta, head, conversation) {
+    assertActiveHead(head, conversation);
+    if (previous.id !== meta.id ||
+        previous.workspaceDigest !== meta.workspaceDigest ||
+        previous.createdAt !== meta.createdAt)
+        throw new Error("session catalogue does not match its metadata");
+    const active = conversation.activeNode;
+    const revisesHead = active.id === previous.head.nodeId &&
+        active.parentId === previous.head.parentId &&
+        active.revision === previous.head.revision + 1;
+    const extendsHead = active.parentId === previous.head.nodeId &&
+        active.id > previous.head.nodeId && active.revision === 1;
+    if (!revisesHead && !extendsHead)
+        return sessionCatalog(meta, head, conversation);
+    // A resumable child of an unfinished head makes that intermediate node part
+    // of the selected path. Rebuild in that uncommon case so the turn count is
+    // exact instead of assuming one visible turn was appended.
+    if (extendsHead && active.settlement !== "checkpointed" &&
+        previous.resumeNodeId !== previous.head.nodeId)
+        return sessionCatalog(meta, head, conversation);
+    if (active.settlement === "checkpointed" && previous.resumeNodeId === active.id) {
+        return sessionCatalog(meta, head, conversation);
+    }
+    const resumable = active.settlement !== "checkpointed";
+    const addsTurn = resumable && previous.resumeNodeId !== active.id;
+    const turns = previous.turns + (addsTurn ? 1 : 0);
+    const preview = turns === 0
+        ? ""
+        : previous.turns === 0
+            ? firstUserTextInNode(active)
+            : previous.preview;
+    return own({
+        version: CATALOG_SCHEMA,
+        id: meta.id,
+        workspaceDigest: meta.workspaceDigest,
+        createdAt: meta.createdAt,
+        head,
+        resumeNodeId: resumable ? active.id : previous.resumeNodeId,
+        turns,
+        preview,
+    });
+}
+export function encodeSessionCatalog(catalog) {
+    const encoded = `${JSON.stringify(catalog, null, 2)}\n`;
+    decodeSessionCatalog(JSON.parse(encoded));
+    if (Buffer.byteLength(encoded, "utf8") > SESSION_CATALOG_BYTES) {
+        throw new Error("session catalogue data is invalid or unsupported");
+    }
+    return encoded;
+}
+export function decodeSessionCatalog(value) {
+    if (!record(value) || !keys(value, "createdAt,head,id,preview,resumeNodeId,turns,version,workspaceDigest"))
+        throw invalid();
+    const head = decodeHead(value["head"]);
+    const resumeNodeId = value["resumeNodeId"];
+    const turns = value["turns"];
+    const preview = value["preview"];
+    if (value["version"] !== CATALOG_SCHEMA ||
+        !identifier(value["id"]) ||
+        !digest(value["workspaceDigest"]) ||
+        !timestamp(value["createdAt"]) ||
+        !integer(resumeNodeId, 0) || resumeNodeId > head.nodeId ||
+        !integer(turns, 0) || turns > CONVERSATION_LIMITS.nodes || turns > resumeNodeId ||
+        typeof preview !== "string" || preview.length > PREVIEW_CODE_UNITS ||
+        (resumeNodeId === 0) !== (turns === 0) ||
+        (turns === 0 ? preview !== "" : preview === ""))
+        throw invalid();
+    return Object.freeze({
+        version: CATALOG_SCHEMA,
+        id: value["id"],
+        workspaceDigest: value["workspaceDigest"],
+        createdAt: value["createdAt"],
+        head,
+        resumeNodeId,
+        turns,
+        preview,
+    });
+}
+export function catalogMatches(catalog, meta, head) {
+    return catalog.id === meta.id &&
+        catalog.workspaceDigest === meta.workspaceDigest &&
+        catalog.createdAt === meta.createdAt &&
+        sameSessionHead(catalog.head, head);
+}
+export function sameSessionHead(left, right) {
+    return left.version === right.version &&
+        left.sequence === right.sequence &&
+        left.nodeId === right.nodeId &&
+        left.parentId === right.parentId &&
+        left.revision === right.revision &&
+        left.updatedAt === right.updatedAt;
+}
+function own(value) {
+    encodeHead(value.head);
+    return decodeSessionCatalog(structuredClone(value));
+}
+function assertActiveHead(head, conversation) {
+    const active = conversation.activeNode;
+    if (active === undefined || active.id !== head.nodeId ||
+        active.parentId !== head.parentId || active.revision !== head.revision)
+        throw new Error("session catalogue does not match its conversation head");
+}
+function selectedTurnCount(conversation) {
+    let count = 0;
+    let id = conversation.activeNodeId;
+    while (id !== 0) {
+        count++;
+        id = conversation.node(id)?.parentId ?? 0;
+    }
+    return count;
+}
+function firstUserText(conversation) {
+    const path = [];
+    let id = conversation.activeNodeId;
+    while (id !== 0) {
+        const node = conversation.node(id);
+        if (node === undefined)
+            throw new Error("session catalogue path is incomplete");
+        path.push(node);
+        id = node.parentId;
+    }
+    for (let index = path.length - 1; index >= 0; index--) {
+        const preview = userTextInNode(path[index]);
+        if (preview !== undefined)
+            return preview;
+    }
+    return "Untitled session";
+}
+function firstUserTextInNode(node) {
+    return userTextInNode(node) ?? "Untitled session";
+}
+function userTextInNode(node) {
+    for (const message of node.messages) {
+        if (message.role !== "user")
+            continue;
+        const preview = textPreview(message.content.find((block) => block.kind === "text")?.text);
+        if (preview !== undefined)
+            return preview;
+    }
+    return undefined;
+}
+function textPreview(text) {
+    const normalized = text?.replace(/\s+/gu, " ").trim();
+    return normalized === undefined || normalized === ""
+        ? undefined
+        : leadingText(normalized, PREVIEW_CODE_UNITS);
+}
+function keys(value, expected) {
+    return Object.keys(value).sort().join(",") === expected;
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function integer(value, minimum) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= minimum;
+}
+function identifier(value) {
+    return typeof value === "string" && /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(value);
+}
+function digest(value) {
+    return typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+}
+function timestamp(value) {
+    return typeof value === "string" && value.length >= 20 && value.length <= 64 &&
+        Number.isFinite(Date.parse(value));
+}
+function invalid() {
+    return new Error("session catalogue data is invalid or unsupported");
+}

package/dist/sessions/lease.js

@@ -1,83 +1,166 @@
-// A tiny, bounded process lease for one durable conversation.
-import { randomUUID } from "node:crypto";
-import { lstat, open, unlink } from "node:fs/promises";
-const MAX_LEASE_BYTES = 256;
+// A tiny, generation-safe process lease for one durable conversation.
+import { lstat, unlink } from "node:fs/promises";
+import { BoundedFileError, readBoundedText, stableFileExpectation, } from "../bounded-file.js";
+import { fileIdentity, sameFileIdentity } from "../file-identity.js";
+import { createProcessLeaseDirectory, inspectProcessLease, pidIsAlive, ProcessLeaseError, processLease, processLeaseToken, removeProcessLease, tryAcquireProcessLease, } from "../process-lease.js";
+const LEGACY_LEASE_BYTES = 256;
+const sessionLeaseScopes = new WeakMap();
 export function leaseToken() {
-    return `${process.pid}:${randomUUID()}`;
+    return processLeaseToken();
 }
-export function sessionLease(id, file, token) {
+export async function createLeaseDirectory(directory, token) {
+    return createProcessLeaseDirectory(directory, token);
+}
+export async function claimLeaseDirectory(directory, token) {
+    try {
+        return await tryAcquireProcessLease(directory, token, { staleMs: 0, setupGraceMs: 1_000 });
+    }
+    catch (error) {
+        if (error instanceof ProcessLeaseError)
+            throw unsafeLease();
+        throw error;
+    }
+}
+export function leaseFromGeneration(directory, generation) {
+    return processLease(directory, generation);
+}
+export function sessionLease(id, scope, lease) {
     let closed = false;
-    return Object.freeze({
+    const owned = Object.freeze({
         id,
         assertOwned: async () => {
             if (closed)
                 throw new Error("session lease is closed");
-            const current = await readLease(file);
-            if (current !== token)
+            try {
+                await lease.assertOwned();
+            }
+            catch {
                 throw new Error("session lease is no longer owned by this process");
+            }
         },
         close: async () => {
             if (closed)
                 return;
+            const removed = await lease.release();
+            if (!removed)
+                throw new Error("session lease is no longer owned by this process");
             closed = true;
-            try {
-                await removeLease(file, token);
-            }
-            catch {
-                // A recovered, replaced, or already-closed lease is no longer ours.
-            }
         },
     });
+    sessionLeaseScopes.set(owned, { id, scope });
+    return owned;
+}
+export function sessionLeaseOwns(lease, id, scope) {
+    const owner = sessionLeaseScopes.get(lease);
+    return owner?.id === id && owner.scope === scope;
 }
-export async function leaseOwner(file) {
+export async function leaseOwner(directory, hooks = {}) {
     try {
-        const token = await readLease(file);
-        const match = /^([1-9]\d*):/.exec(token.trim());
-        if (match === null)
-            return { pid: 0, token };
-        const pid = Number(match[1]);
-        return { pid: Number.isSafeInteger(pid) ? pid : 0, token };
+        const owner = await inspectProcessLease(directory);
+        return owner === undefined
+            ? undefined
+            : { pid: owner.pid, token: owner.token, legacy: false };
     }
     catch (error) {
-        if (error.code === "ENOENT")
-            return undefined;
+        if (error instanceof ProcessLeaseError) {
+            let legacy;
+            try {
+                legacy = await legacyLeaseOwner(directory, hooks);
+            }
+            catch (legacyError) {
+                if (unsafeLegacyRace(legacyError))
+                    throw unsafeLease();
+                throw legacyError;
+            }
+            if (legacy !== undefined)
+                return legacy;
+            throw unsafeLease();
+        }
         throw error;
     }
 }
-export async function removeLease(file, token) {
-    const current = await readLease(file).catch(() => undefined);
-    if (current === token)
-        await unlink(file).catch(() => undefined);
+export async function removeLease(directory, token) {
+    try {
+        return await removeProcessLease(directory, token);
+    }
+    catch (error) {
+        if (error instanceof ProcessLeaseError)
+            throw unsafeLease();
+        throw error;
+    }
 }
-export function pidIsAlive(pid) {
-    if (!Number.isSafeInteger(pid) || pid < 1 || pid > 0x7fff_ffff)
+/** Remove a legacy fixed-file marker only while its session is exclusively owned. */
+export async function removeLegacyLeaseExclusive(file, token, owner) {
+    if (!sessionLeaseScopes.has(owner)) {
+        throw new Error("legacy lease migration requires a Jecode session lease");
+    }
+    await owner.assertOwned();
+    let before;
+    try {
+        before = await lstat(file, { bigint: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return true;
+        throw error;
+    }
+    if (before.isSymbolicLink() || !before.isFile() || before.size > BigInt(LEGACY_LEASE_BYTES)) {
         return false;
+    }
     try {
-        process.kill(pid, 0);
+        const current = await readBoundedText(file, LEGACY_LEASE_BYTES, {
+            label: "legacy session lease",
+            expected: stableFileExpectation(before),
+        });
+        if (current !== token)
+            return false;
+        const after = await lstat(file, { bigint: true });
+        if (!sameFileIdentity(fileIdentity(before), fileIdentity(after)))
+            return false;
+        await owner.assertOwned();
+        await unlink(file);
         return true;
     }
     catch (error) {
-        return error.code !== "ESRCH";
+        if (unsafeLegacyRace(error))
+            return false;
+        throw error;
     }
 }
-async function readLease(file) {
-    const before = await lstat(file);
-    if (before.isSymbolicLink() || !before.isFile() || before.size > MAX_LEASE_BYTES) {
-        throw new Error("session lease is unsafe or too large");
-    }
-    const handle = await open(file, "r");
+export { pidIsAlive };
+function unsafeLease() {
+    return new Error("session lease is unsafe or too large, or invalid");
+}
+async function legacyLeaseOwner(file, hooks) {
+    let details;
     try {
-        const opened = await handle.stat();
-        if (!opened.isFile() || opened.size > MAX_LEASE_BYTES ||
-            opened.dev !== before.dev || opened.ino !== before.ino)
-            throw new Error("session lease changed while opening");
-        const bytes = Buffer.alloc(MAX_LEASE_BYTES + 1);
-        const { bytesRead } = await handle.read(bytes, 0, bytes.length, 0);
-        if (bytesRead > MAX_LEASE_BYTES)
-            throw new Error("session lease is too large");
-        return bytes.subarray(0, bytesRead).toString("utf8");
+        details = await lstat(file, { bigint: true });
     }
-    finally {
-        await handle.close();
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    if (details.isSymbolicLink() || !details.isFile() || details.size > BigInt(LEGACY_LEASE_BYTES)) {
+        return undefined;
     }
+    await hooks.afterLegacyStat?.();
+    const token = await readBoundedText(file, LEGACY_LEASE_BYTES, {
+        label: "legacy session lease",
+        expected: stableFileExpectation(details),
+    });
+    const match = /^([1-9]\d*):/.exec(token.trim());
+    const pid = match === null ? 0 : Number(match[1]);
+    return {
+        pid: Number.isSafeInteger(pid) && pid <= 0x7fff_ffff ? pid : 0,
+        token,
+        legacy: true,
+    };
+}
+function unsafeLegacyRace(error) {
+    if (error instanceof BoundedFileError)
+        return true;
+    const code = error.code;
+    return code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP" ||
+        code === "EISDIR" || code === "ENXIO";
 }

package/dist/sessions/runtime.js

@@ -3,36 +3,38 @@
 // One logical conversation keeps one stable session id across every resume.
 // New turns advance that session's tree head; /new is the boundary that starts
 // another durable session.
-import { DurableSessionStore } from "./store.js";
+import { DurableSessionStore, reserveSessionId } from "./store.js";
 export class SessionPersistence {
     #store;
     #sessionId;
+    #conversationId;
     #lease;
     #snapshot;
     #failure;
-    constructor(store, sessionId, lease, snapshot) {
+    constructor(store, sessionId, lease, snapshot, conversationId = sessionId ?? reserveSessionId()) {
         this.#store = store;
         this.#sessionId = sessionId;
+        this.#conversationId = conversationId;
         this.#lease = lease;
         this.#snapshot = snapshot;
     }
     static fresh(store) {
-        return new SessionPersistence(store, null);
+        return new SessionPersistence(store, null, undefined, undefined, reserveSessionId());
     }
     static async resume(store, id) {
         const lease = await store.claim(id);
         try {
-            const snapshot = await store.load(id);
+            const snapshot = await store.load(id, lease);
             const conversation = snapshot.conversation.latestResumable();
             if (conversation === undefined)
                 throw new Error("session has no resumable turn");
             return Object.freeze({
                 conversation,
-                persistence: new SessionPersistence(store, id, lease, snapshot),
+                persistence: new SessionPersistence(store, id, lease, snapshot, id),
             });
         }
         catch (error) {
-            await lease.close();
+            await lease.close().catch(() => undefined);
             throw error;
         }
     }
@@ -45,12 +47,16 @@ export class SessionPersistence {
     get sessionId() {
         return this.#sessionId;
     }
+    /** Reserved before publication so provider cache identity survives resume. */
+    get conversationId() {
+        return this.#conversationId;
+    }
     async checkpoint(conversation) {
         if (this.#failure !== undefined)
             throw this.#failure;
         try {
             if (this.#sessionId === null) {
-                const published = await this.#store.publish(conversation, true);
+                const published = await this.#store.publish(conversation, true, this.#conversationId);
                 this.#lease = published.lease;
                 this.#sessionId = published.meta.id;
                 this.#snapshot = published;
@@ -60,7 +66,7 @@ export class SessionPersistence {
                 throw new Error("session persistence has no verified owner snapshot");
             }
             await this.#lease.assertOwned();
-            this.#snapshot = await this.#store.checkpoint(this.#snapshot, conversation);
+            this.#snapshot = await this.#store.checkpoint(this.#snapshot, conversation, this.#lease);
         }
         catch (error) {
             this.#failure = error;
@@ -71,6 +77,7 @@ export class SessionPersistence {
         await this.#lease?.close();
         this.#lease = undefined;
         this.#sessionId = null;
+        this.#conversationId = reserveSessionId();
         this.#snapshot = undefined;
         this.#failure = undefined;
     }