@giovannijecha/jecode 0.8.4 → 0.8.6

package/dist/sessions/load.js

@@ -0,0 +1,90 @@
+// Strict full-session loading and one adjacent checkpoint recovery.
+import * as path from "node:path";
+import { atomicWrite } from "../atomic.js";
+import { ConversationTree } from "../conversation.js";
+import { assertDirectoryAnchor, captureDirectDirectory } from "../directory-anchor.js";
+import { assertSessionId } from "./bucket.js";
+import { sameSessionHead, sessionCatalog } from "./catalog.js";
+import { decodeHead, decodeMeta, encodeHead, SESSION_FILE_LIMITS, SESSION_SCHEMA } from "./codec.js";
+import { FILE_MODE, readJson, readNodes } from "./files.js";
+import { sessionLeaseOwns } from "./lease.js";
+export async function loadSession(bucket, id, scope, recoveryLease) {
+    assertSessionId(id);
+    await bucket.assert();
+    const directory = bucket.directory(id);
+    const directoryAnchor = await captureDirectDirectory(directory, "session directory");
+    const nodesAnchor = await captureDirectDirectory(path.join(directory, "nodes"), "session node directory");
+    const validateSession = async () => {
+        await Promise.all([
+            bucket.assert(),
+            assertDirectoryAnchor(directoryAnchor),
+            assertDirectoryAnchor(nodesAnchor),
+        ]);
+    };
+    const meta = decodeMeta(await readJson(path.join(directory, "meta.json"), SESSION_FILE_LIMITS.metadataBytes, undefined, validateSession));
+    bucket.assertWorkspace(meta, id);
+    const persistedHead = decodeHead(await readJson(path.join(directory, "head.json"), SESSION_FILE_LIMITS.metadataBytes, undefined, validateSession));
+    let head = persistedHead;
+    const stored = await readNodes(nodesAnchor, validateSession);
+    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");
+        }
+        if (recoveryLease === undefined ||
+            !sessionLeaseOwns(recoveryLease, id, scope)) {
+            throw new Error("session recovery requires exclusive ownership");
+        }
+        await recoveryLease.assertOwned();
+        head = Object.freeze({
+            version: SESSION_SCHEMA,
+            sequence: candidate.sequence,
+            nodeId: candidate.node.id,
+            parentId: candidate.node.parentId,
+            revision: candidate.node.revision,
+            updatedAt: candidate.updatedAt,
+        });
+    }
+    // Recovery must pass all turn, tree, and catalogue invariants before it
+    // changes durable state; the file codec alone cannot validate the tree.
+    const nodes = stored.map((entry) => entry.node);
+    const conversation = ConversationTree.restore(nodes, head.nodeId);
+    const catalog = sessionCatalog(meta, head, conversation);
+    if (head !== persistedHead && recoveryLease !== undefined) {
+        await atomicWrite(path.join(directory, "head.json"), encodeHead(head), {
+            mode: FILE_MODE,
+            validate: async (phase) => {
+                await validateSession();
+                if (phase !== "before-rename")
+                    return;
+                await recoveryLease.assertOwned();
+                const current = decodeHead(await readJson(path.join(directory, "head.json"), SESSION_FILE_LIMITS.metadataBytes, undefined, validateSession));
+                if (!sameSessionHead(current, persistedHead)) {
+                    throw new Error("session head changed while recovering its checkpoint");
+                }
+            },
+        });
+    }
+    return Object.freeze({ meta, head, conversation, catalog });
+}

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;
     }

package/dist/sessions/snapshot.js

@@ -0,0 +1,33 @@
+// Verified in-memory checkpoint identity shared by persistence operations.
+import { catalogMatches, encodeSessionCatalog } from "./catalog.js";
+import { encodeHead, encodeMeta } from "./codec.js";
+import { assertSessionId, workspaceKey } from "./bucket.js";
+export 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");
+        }
+    }
+}
+export 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");
+    }
+}