@giovannijecha/jecode 0.8.5 → 0.8.6

package/dist/sessions/files.js

@@ -0,0 +1,158 @@
+// Bounded session-file IO and cleanup of verified temporary directories.
+import { randomUUID } from "node:crypto";
+import { lstat, opendir, rename, rm } from "node:fs/promises";
+import * as path from "node:path";
+import { BoundedFileError, readBoundedText, stableFileExpectation } from "../bounded-file.js";
+import { CONVERSATION_LIMITS } from "../conversation.js";
+import { assertDirectoryAnchor, captureDirectDirectory } from "../directory-anchor.js";
+import { sameFileIdentity } from "../file-identity.js";
+import { decodeNode, SESSION_FILE_LIMITS } from "./codec.js";
+export const DIRECTORY_MODE = 0o700;
+export const FILE_MODE = 0o600;
+export const SESSION_NAME = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/;
+const MAX_NODE_READ_CONCURRENCY = 8;
+const MAX_NODE_READ_IN_FLIGHT_BYTES = 64 * 1_024 * 1_024;
+const MAX_SESSION_NODE_BYTES = 192 * 1_024 * 1_024;
+const NODE_READ_CONCURRENCY = Math.max(1, Math.min(MAX_NODE_READ_CONCURRENCY, Math.floor(MAX_NODE_READ_IN_FLIGHT_BYTES / SESSION_FILE_LIMITS.nodeBytes)));
+const NODE_NAME = /^(\d{6})\.json$/;
+const ATOMIC_NODE_TEMP = /^\.\d{6}\.json\.\d+\.[a-f0-9-]+\.tmp$/;
+export async function assertMissingNode(file, validate) {
+    await validate?.();
+    try {
+        await lstat(file);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            await validate?.();
+            return;
+        }
+        throw error;
+    }
+    await validate?.();
+    throw new Error("session has an incomplete node outside its verified snapshot");
+}
+export async function readNodes(directory, validate) {
+    await validate();
+    await assertDirectoryAnchor(directory);
+    const names = [];
+    let entries = 0;
+    const handle = await opendir(directory.path);
+    for await (const entry of handle) {
+        entries++;
+        if (entries > CONVERSATION_LIMITS.nodes + 64) {
+            throw new Error("session node directory contains unsupported data");
+        }
+        if (!entry.isFile() || (!NODE_NAME.test(entry.name) && !ATOMIC_NODE_TEMP.test(entry.name))) {
+            throw new Error("session node directory contains unsupported data");
+        }
+        if (NODE_NAME.test(entry.name))
+            names.push(entry.name);
+    }
+    await validate();
+    await assertDirectoryAnchor(directory);
+    names.sort();
+    if (names.length === 0 || names.length > CONVERSATION_LIMITS.nodes) {
+        throw new Error("session has an invalid conversation size");
+    }
+    const files = [];
+    let storedBytes = 0;
+    for (let index = 0; index < names.length; index++) {
+        const name = names[index];
+        const id = Number(NODE_NAME.exec(name)?.[1]);
+        if (id !== index + 1) {
+            throw new Error("session conversation nodes are not contiguous");
+        }
+        const details = await lstat(path.join(directory.path, name), { bigint: true });
+        if (details.isSymbolicLink() || !details.isFile() || details.size < 0n ||
+            details.size > BigInt(SESSION_FILE_LIMITS.nodeBytes))
+            throw new Error("session node file is unsafe or too large");
+        storedBytes += Number(details.size);
+        if (storedBytes > MAX_SESSION_NODE_BYTES) {
+            throw new Error("session node files exceed their aggregate storage limit");
+        }
+        files.push({ name, id, expected: stableFileExpectation(details) });
+    }
+    await validate();
+    const stored = [];
+    const sequences = new Set();
+    let messageCodeUnits = 0;
+    let transcriptCodeUnits = 0;
+    let contextCodeUnits = 0;
+    for (let start = 0; start < files.length; start += NODE_READ_CONCURRENCY) {
+        const decoded = await Promise.all(files.slice(start, start + NODE_READ_CONCURRENCY)
+            .map(async ({ name, id, expected }) => {
+            const entry = decodeNode(await readJson(path.join(directory.path, name), SESSION_FILE_LIMITS.nodeBytes, expected));
+            if (entry.node.id !== id) {
+                throw new Error("session conversation node identity is invalid");
+            }
+            return entry;
+        }));
+        for (const entry of decoded) {
+            if (sequences.has(entry.sequence)) {
+                throw new Error("session conversation node identity is invalid");
+            }
+            messageCodeUnits += JSON.stringify(entry.node.messages).length;
+            transcriptCodeUnits += JSON.stringify(entry.node.blocks).length;
+            contextCodeUnits += entry.node.context?.summary.length ?? 0;
+            if (messageCodeUnits > CONVERSATION_LIMITS.messageCodeUnits ||
+                transcriptCodeUnits > CONVERSATION_LIMITS.transcriptCodeUnits ||
+                contextCodeUnits > CONVERSATION_LIMITS.contextCodeUnits) {
+                throw new Error("session conversation exceeds its aggregate limit");
+            }
+            sequences.add(entry.sequence);
+            stored.push(entry);
+        }
+    }
+    await validate();
+    return stored;
+}
+export async function readJson(file, limit, expected, validate) {
+    try {
+        return JSON.parse(await readBoundedText(file, limit, {
+            label: "session file",
+            expected,
+            validate,
+        }));
+    }
+    catch (error) {
+        if (error instanceof SyntaxError) {
+            throw new Error("session file is not valid JSON");
+        }
+        if (error instanceof BoundedFileError) {
+            throw new Error("session file is unsafe or too large, or changed while opening");
+        }
+        throw error;
+    }
+}
+export async function removeTemporaryDirectory(directory, bucket, expected) {
+    const relative = path.relative(bucket.path, 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 assertDirectoryAnchor(bucket);
+    let observed;
+    try {
+        observed = await captureDirectDirectory(directory, "temporary session directory");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    if (expected !== undefined &&
+        !sameFileIdentity(expected.identity, observed.identity))
+        throw new Error("refusing to remove a replaced session directory");
+    const quarantine = path.join(bucket.path, `.discard-${process.pid}-${randomUUID()}.tmp`);
+    await assertDirectoryAnchor(bucket);
+    await rename(directory, quarantine);
+    const moved = await captureDirectDirectory(quarantine, "discarded session directory");
+    if (!sameFileIdentity(observed.identity, moved.identity)) {
+        throw new Error("session cleanup target changed during quarantine");
+    }
+    await assertDirectoryAnchor(bucket);
+    await assertDirectoryAnchor(moved);
+    await rm(quarantine, { recursive: true });
+}
+export function nodeName(id) {
+    return `${String(id).padStart(6, "0")}.json`;
+}

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/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");
+    }
+}