@giovannijecha/jecode 0.8.5 → 0.8.7

package/dist/sessions/catalog-io.js

@@ -0,0 +1,162 @@
+// Head-tied resume listing and repairable catalogue-file IO.
+import * as path from "node:path";
+import { atomicWrite } from "../atomic.js";
+import { assertDirectoryAnchor } from "../directory-anchor.js";
+import { readStableDirectory } from "../stable-directory.js";
+import { catalogMatches, decodeSessionCatalog, encodeSessionCatalog, sameSessionHead, SESSION_CATALOG_BYTES, SESSION_CATALOG_FILE, SESSION_CHECKPOINT_FILE, } from "./catalog.js";
+import { decodeHead, decodeMeta, SESSION_FILE_LIMITS } from "./codec.js";
+import { FILE_MODE, readJson, SESSION_NAME } from "./files.js";
+import { leaseOwner, pidIsAlive, removeLease } from "./lease.js";
+const MAX_CATALOG_ENTRIES = 4_096;
+const CATALOG_READ_CONCURRENCY = 8;
+export class SessionCatalogIO {
+    #bucket;
+    #reader;
+    constructor(bucket, reader) {
+        this.#bucket = bucket;
+        this.#reader = reader;
+    }
+    async list(limit = 32) {
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 64) {
+            throw new Error("session catalogue limit is invalid");
+        }
+        await this.#bucket.assert();
+        const names = await catalogNames(this.#bucket.anchor);
+        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);
+    }
+    async write(id, catalog, checkpointToken) {
+        const directory = this.#bucket.directory(id);
+        const directoryAnchor = await this.#bucket.captureSession(id);
+        const validateDirectory = async () => {
+            await this.#bucket.assertSession(directoryAnchor);
+        };
+        const validate = async () => {
+            await validateDirectory();
+            const currentHead = decodeHead(await readJson(path.join(directory, "head.json"), SESSION_FILE_LIMITS.metadataBytes, undefined, validateDirectory));
+            if (!sameSessionHead(currentHead, catalog.head)) {
+                throw new Error("session head changed while updating its catalogue");
+            }
+        };
+        await atomicWrite(path.join(directory, SESSION_CATALOG_FILE), encodeSessionCatalog(catalog), { mode: FILE_MODE, validate });
+        if (checkpointToken !== undefined) {
+            await validateDirectory();
+            await removeLease(path.join(directory, SESSION_CHECKPOINT_FILE), checkpointToken);
+            await validateDirectory();
+        }
+    }
+    async #leaseIsActive(id, directory) {
+        if (directory !== undefined)
+            await this.#bucket.assertSession(directory);
+        else
+            await this.#bucket.assert();
+        const owner = await leaseOwner(path.join(this.#bucket.directory(id), "active"));
+        if (directory !== undefined)
+            await this.#bucket.assertSession(directory);
+        return owner !== undefined && pidIsAlive(owner.pid);
+    }
+    async #catalogEntry(id) {
+        try {
+            const directory = this.#bucket.directory(id);
+            const directoryAnchor = await this.#bucket.captureSession(id);
+            const validateDirectory = async () => {
+                await this.#bucket.assertSession(directoryAnchor);
+            };
+            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++) {
+                await validateDirectory();
+                const checkpointBefore = await leaseOwner(checkpointFile);
+                try {
+                    const [metaValue, headValue, catalogValue] = await Promise.all([
+                        readJson(path.join(directory, "meta.json"), SESSION_FILE_LIMITS.metadataBytes, undefined, validateDirectory),
+                        readJson(path.join(directory, "head.json"), SESSION_FILE_LIMITS.metadataBytes, undefined, validateDirectory),
+                        readJson(path.join(directory, SESSION_CATALOG_FILE), SESSION_CATALOG_BYTES, undefined, validateDirectory),
+                    ]);
+                    const meta = decodeMeta(metaValue);
+                    const head = decodeHead(headValue);
+                    const storedCatalog = decodeSessionCatalog(catalogValue);
+                    this.#bucket.assertWorkspace(meta, id);
+                    const confirmedHead = decodeHead(await readJson(path.join(directory, "head.json"), SESSION_FILE_LIMITS.metadataBytes, undefined, validateDirectory));
+                    await validateDirectory();
+                    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, directoryAnchor) ||
+                        checkpointAfter !== undefined;
+                    return catalogEntry(storedCatalog, active);
+                }
+                catch {
+                    break;
+                }
+            }
+            // 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, directoryAnchor) ||
+                (checkpoint !== undefined && pidIsAlive(checkpoint.pid)))
+                return undefined;
+            const repairLease = await this.#reader.claim(id);
+            let snapshot;
+            try {
+                snapshot = await this.#reader.load(id, repairLease);
+                await this.write(id, snapshot.catalog, checkpoint?.legacy === true ? undefined : checkpoint?.token).catch(() => undefined);
+            }
+            finally {
+                await repairLease.close();
+            }
+            const currentCheckpoint = await leaseOwner(checkpointFile);
+            const active = await this.#leaseIsActive(id, directoryAnchor) ||
+                (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 function catalogNames(directory) {
+    await assertDirectoryAnchor(directory);
+    const inspected = await readStableDirectory(directory.path, directory.path, {
+        maxEntries: MAX_CATALOG_ENTRIES + 1,
+    });
+    if (inspected.capped || inspected.entries.length > MAX_CATALOG_ENTRIES) {
+        throw new Error(`session catalogue exceeds ${MAX_CATALOG_ENTRIES} entries`);
+    }
+    return inspected.entries
+        .filter((entry) => entry.kind === "directory" && SESSION_NAME.test(entry.name))
+        .map((entry) => entry.name)
+        .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 && left?.legacy === right?.legacy;
+}

package/dist/sessions/catalog.js

@@ -11,7 +11,9 @@ 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;
+// Older indexes can hide a node committed before a failed head write. Rebuild
+// them through strict loading instead of trusting their apparently current head.
+const CATALOG_SCHEMA = 2;
 const PREVIEW_CODE_UNITS = 160;
 export function sessionCatalog(meta, head, conversation) {
     assertActiveHead(head, conversation);

package/dist/sessions/codec-messages.js

@@ -0,0 +1,122 @@
+// Normalized provider-message records; opaque provider data never persists.
+import { bounded, boundedText, integer, invalid, keys, record, SESSION_FILE_LIMITS, } from "./codec-values.js";
+export function messageRecord(message) {
+    return {
+        role: message.role,
+        content: message.content.map(contentRecord),
+        usage: message.usage ?? null,
+    };
+}
+export function messageFromRecord(value) {
+    if (!record(value) || !keys(value, "content,role,usage"))
+        throw invalid();
+    if ((value["role"] !== "user" && value["role"] !== "assistant") ||
+        !Array.isArray(value["content"]) || value["content"].length > SESSION_FILE_LIMITS.blocks)
+        throw invalid();
+    const usage = value["usage"] === null ? undefined : usageFromRecord(value["usage"]);
+    return {
+        role: value["role"],
+        content: value["content"].map(contentFromRecord),
+        ...(usage === undefined ? {} : { usage }),
+    };
+}
+function contentRecord(block) {
+    if (block.kind === "text")
+        return { kind: block.kind, text: block.text };
+    if (block.kind === "tool_call") {
+        return { kind: block.kind, id: block.id, name: block.name, input: block.input };
+    }
+    return {
+        kind: block.kind,
+        id: block.id,
+        output: block.output,
+        isError: block.isError,
+    };
+}
+function contentFromRecord(value) {
+    if (!record(value) || typeof value["kind"] !== "string")
+        throw invalid();
+    if (value["kind"] === "text" && keys(value, "kind,text") && boundedText(value["text"])) {
+        return { kind: "text", text: value["text"] };
+    }
+    if (value["kind"] === "tool_call" && keys(value, "id,input,kind,name") &&
+        bounded(value["id"], 512) && bounded(value["name"], 256)) {
+        const input = jsonObject(value["input"]);
+        return { kind: "tool_call", id: value["id"], name: value["name"], input };
+    }
+    if (value["kind"] === "tool_result" && keys(value, "id,isError,kind,output") &&
+        bounded(value["id"], 512) && boundedText(value["output"]) &&
+        typeof value["isError"] === "boolean") {
+        return {
+            kind: "tool_result",
+            id: value["id"],
+            output: value["output"],
+            isError: value["isError"],
+        };
+    }
+    throw invalid();
+}
+function usageFromRecord(value) {
+    if (!record(value) || !keys(value, "cacheWriteInputTokens,cachedInputTokens,inputTokens,outputTokens,reasoningTokens"))
+        throw invalid();
+    const inputTokens = value["inputTokens"];
+    const outputTokens = value["outputTokens"];
+    const cachedInputTokens = value["cachedInputTokens"];
+    const cacheWriteInputTokens = value["cacheWriteInputTokens"];
+    const reasoningTokens = value["reasoningTokens"];
+    if (!integer(inputTokens, 0) || !integer(outputTokens, 0) ||
+        !integer(cachedInputTokens, 0) || !integer(cacheWriteInputTokens, 0) ||
+        !integer(reasoningTokens, 0))
+        throw invalid();
+    return {
+        inputTokens,
+        outputTokens,
+        cachedInputTokens,
+        cacheWriteInputTokens,
+        reasoningTokens,
+    };
+}
+function jsonObject(value) {
+    const budget = { nodes: 0 };
+    const safe = jsonValue(value, budget, 0);
+    if (!record(safe))
+        throw invalid();
+    return safe;
+}
+function jsonValue(value, budget, depth) {
+    budget.nodes++;
+    if (budget.nodes > SESSION_FILE_LIMITS.jsonNodes || depth > SESSION_FILE_LIMITS.jsonDepth) {
+        throw invalid();
+    }
+    if (value === null || typeof value === "boolean")
+        return value;
+    if (typeof value === "string") {
+        if (!boundedText(value))
+            throw invalid();
+        return value;
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw invalid();
+        return value;
+    }
+    if (Array.isArray(value)) {
+        if (value.length > SESSION_FILE_LIMITS.blocks)
+            throw invalid();
+        return value.map((item) => jsonValue(item, budget, depth + 1));
+    }
+    if (!record(value) || Object.keys(value).length > SESSION_FILE_LIMITS.blocks)
+        throw invalid();
+    const safe = {};
+    for (const [name, child] of Object.entries(value)) {
+        if (!boundedText(name, 1_024))
+            throw invalid();
+        Object.defineProperty(safe, name, {
+            value: jsonValue(child, budget, depth + 1),
+            enumerable: true,
+            configurable: true,
+            writable: true,
+        });
+    }
+    return safe;
+}

package/dist/sessions/codec-transcript.js

@@ -0,0 +1,93 @@
+// Settled transcript evidence across supported session schema versions.
+import { bounded, boundedText, integer, invalid, keys, nullableInteger, record, SESSION_FILE_LIMITS, } from "./codec-values.js";
+export function blockRecord(block) {
+    if (block.kind === "notice")
+        return [];
+    if (block.kind === "user" || block.kind === "answer" || block.kind === "reasoning") {
+        return [{ kind: block.kind, text: block.text }];
+    }
+    if (block.tone === "pending")
+        return [];
+    return [{
+            kind: block.kind,
+            name: block.name,
+            target: block.target,
+            right: block.right,
+            tone: block.tone,
+            body: block.body?.map(detailRecord) ?? null,
+            durationMs: block.durationMs ?? null,
+        }];
+}
+export function blockFromRecord(value, version) {
+    if (!record(value) || typeof value["kind"] !== "string")
+        throw invalid();
+    if ((value["kind"] === "user" || value["kind"] === "answer" || value["kind"] === "reasoning") &&
+        keys(value, "kind,text") && boundedText(value["text"]))
+        return { kind: value["kind"], text: value["text"] };
+    const toolKeys = version >= 4
+        ? "body,durationMs,kind,name,right,target,tone"
+        : "body,kind,name,right,target,tone";
+    if (value["kind"] === "tool" && keys(value, toolKeys) &&
+        bounded(value["name"], 256) && boundedText(value["target"]) &&
+        boundedText(value["right"], 1_024) &&
+        (value["tone"] === "ok" || value["tone"] === "fail" || value["tone"] === "deny") &&
+        (version < 4 || nullableInteger(value["durationMs"], 0)) &&
+        (value["body"] === null ||
+            (Array.isArray(value["body"]) && value["body"].length <= SESSION_FILE_LIMITS.details))) {
+        const body = value["body"] === null
+            ? undefined
+            : value["body"].map(detailFromRecord);
+        return {
+            kind: "tool",
+            name: value["name"],
+            target: value["target"],
+            right: value["right"],
+            tone: value["tone"],
+            ...(body === undefined ? {} : { body }),
+            ...(version < 4 || value["durationMs"] === null
+                ? {}
+                : { durationMs: value["durationMs"] }),
+        };
+    }
+    throw invalid();
+}
+function detailRecord(detail) {
+    if (detail.kind === "out" || detail.kind === "gap")
+        return { kind: detail.kind, text: detail.text };
+    return {
+        kind: detail.kind,
+        text: detail.text,
+        oldLine: detail.oldLine ?? null,
+        newLine: detail.newLine ?? null,
+        emphasis: detail.emphasis ?? null,
+    };
+}
+function detailFromRecord(value) {
+    if (!record(value) || typeof value["kind"] !== "string")
+        throw invalid();
+    if ((value["kind"] === "out" || value["kind"] === "gap") &&
+        keys(value, "kind,text") && boundedText(value["text"]))
+        return { kind: value["kind"], text: value["text"] };
+    if ((value["kind"] === "keep" || value["kind"] === "add" || value["kind"] === "del") &&
+        keys(value, "emphasis,kind,newLine,oldLine,text") && boundedText(value["text"]) &&
+        nullableInteger(value["oldLine"], 1) && nullableInteger(value["newLine"], 1)) {
+        const emphasis = emphasisFromRecord(value["emphasis"]);
+        return {
+            kind: value["kind"],
+            text: value["text"],
+            ...(value["oldLine"] === null ? {} : { oldLine: value["oldLine"] }),
+            ...(value["newLine"] === null ? {} : { newLine: value["newLine"] }),
+            ...(emphasis === undefined ? {} : { emphasis }),
+        };
+    }
+    throw invalid();
+}
+function emphasisFromRecord(value) {
+    if (value === null)
+        return undefined;
+    if (!record(value) || !keys(value, "length,start"))
+        throw invalid();
+    if (!integer(value["start"], 0) || !integer(value["length"], 1))
+        throw invalid();
+    return { start: value["start"], length: value["length"] };
+}

package/dist/sessions/codec-values.js

@@ -0,0 +1,52 @@
+// Shared strict value checks and limits for the canonical session codec.
+import { Buffer } from "node:buffer";
+import { MAX_TEXT_CODE_UNITS } from "../text-boundary.js";
+export const SESSION_FILE_LIMITS = Object.freeze({
+    text: MAX_TEXT_CODE_UNITS,
+    metadataBytes: 64 * 1_024,
+    nodeBytes: 20 * 1_024 * 1_024,
+    jsonDepth: 24,
+    jsonNodes: 32_768,
+    blocks: 8_192,
+    details: 8_192,
+});
+function line(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+export function boundedLine(value, maxBytes) {
+    const encoded = line(value);
+    if (Buffer.byteLength(encoded, "utf8") > maxBytes)
+        throw invalid();
+    return encoded;
+}
+export function keys(value, expected) {
+    return Object.keys(value).sort().join(",") === expected;
+}
+export function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function bounded(value, limit = SESSION_FILE_LIMITS.text) {
+    return typeof value === "string" && value.length > 0 && value.length <= limit;
+}
+export function boundedText(value, limit = SESSION_FILE_LIMITS.text) {
+    return typeof value === "string" && value.length <= limit;
+}
+export function integer(value, minimum) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= minimum;
+}
+export function nullableInteger(value, minimum) {
+    return value === null || integer(value, minimum);
+}
+export function identifier(value) {
+    return typeof value === "string" && /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(value);
+}
+export function digest(value) {
+    return typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+}
+export function timestamp(value) {
+    return typeof value === "string" && value.length >= 20 && value.length <= 64 &&
+        Number.isFinite(Date.parse(value));
+}
+export function invalid() {
+    return new Error("session data is invalid or unsupported");
+}