@claudexor/journal 3.3.16 → 3.4.0

package/dist/journal-compaction.js

@@ -0,0 +1,78 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, constants, openSync, renameSync } from "node:fs";
+import { dirname } from "node:path";
+import { gzipSync } from "node:zlib";
+import { fsyncDirectory } from "@claudexor/util";
+import { encodeJournalPayload } from "./append-batch.js";
+import { COMPACTED_SNAPSHOT, HASH_BYTES, MAX_PAYLOAD_BYTES, ZERO_HASH, encodeFrame, } from "./frame-codec.js";
+import { appendAndSync } from "./journal-files.js";
+export function compactJournalFile(input) {
+    if (input.entries.length === 0)
+        return null;
+    const logical = input.entries.map((record) => ({
+        time: record.time,
+        type: record.type,
+        payload: cloneJson(record.payload),
+    }));
+    const compressed = gzipSync(Buffer.from(JSON.stringify(logical)));
+    const payload = {
+        version: 1,
+        count: logical.length,
+        encoding: "gzip-base64",
+        data: compressed.toString("base64"),
+    };
+    const payloadBytes = encodeJournalPayload(payload);
+    if (payloadBytes.length > MAX_PAYLOAD_BYTES)
+        return null;
+    const epoch = randomUUID();
+    const header = {
+        partition: input.partition,
+        epoch,
+        seq: 1,
+        previousFrameHash: ZERO_HASH,
+        time: input.now().toISOString(),
+        type: COMPACTED_SNAPSHOT,
+        logicalSpan: logical.length,
+    };
+    const frame = encodeFrame(header, payloadBytes);
+    if (frame.length >= input.knownFileBytes)
+        return null;
+    const temp = `${input.path}.${randomUUID()}.compact`;
+    const tempFd = openSync(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+    try {
+        appendAndSync(tempFd, frame);
+    }
+    finally {
+        closeSync(tempFd);
+    }
+    renameSync(temp, input.path);
+    fsyncDirectory(dirname(input.path));
+    const frameHash = frame.subarray(frame.length - HASH_BYTES).toString("hex");
+    const records = logical.map((record, index) => ({
+        partition: input.partition,
+        epoch,
+        seq: index + 1,
+        previousFrameHash: index === 0 ? ZERO_HASH : frameHash,
+        frameHash,
+        time: record.time,
+        type: record.type,
+        payload: cloneJson(record.payload),
+        byteOffset: 0,
+    }));
+    return {
+        receipt: {
+            beforeBytes: input.knownFileBytes,
+            afterBytes: frame.length,
+            records: logical.length,
+        },
+        records,
+        epoch,
+        nextSeq: logical.length + 1,
+        previousFrameHash: frameHash,
+        knownFileBytes: frame.length,
+    };
+}
+function cloneJson(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+//# sourceMappingURL=journal-compaction.js.map

package/dist/journal-compaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal-compaction.js","sourceRoot":"","sources":["../src/journal-compaction.ts"],"names":[],"mappings":"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"}

package/dist/journal-cursor.d.ts

@@ -0,0 +1,9 @@
+export declare class JournalCursorError extends Error {
+    readonly code = "journal_cursor_invalid";
+    readonly status = 409;
+    readonly retryable = true;
+    readonly requiredActions: string[];
+}
+export declare function encodeCursor(partition: string, epoch: string, seq: number): string;
+export declare function cursorError(detail: string): JournalCursorError;
+//# sourceMappingURL=journal-cursor.d.ts.map

package/dist/journal-cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal-cursor.d.ts","sourceRoot":"","sources":["../src/journal-cursor.ts"],"names":[],"mappings":"AAAA,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,IAAI,4BAA4B;IACzC,QAAQ,CAAC,MAAM,OAAO;IACtB,QAAQ,CAAC,SAAS,QAAQ;IAC1B,QAAQ,CAAC,eAAe,WAAkB;CAC3C;AAED,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAIlF;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB,CAE9D"}

package/dist/journal-cursor.js

@@ -0,0 +1,13 @@
+export class JournalCursorError extends Error {
+    code = "journal_cursor_invalid";
+    status = 409;
+    retryable = true;
+    requiredActions = ["resnapshot"];
+}
+export function encodeCursor(partition, epoch, seq) {
+    return Buffer.from(JSON.stringify({ v: 1, p: partition, e: epoch, s: seq })).toString("base64url");
+}
+export function cursorError(detail) {
+    return new JournalCursorError(`journal cursor is ${detail}; resnapshot is required`);
+}
+//# sourceMappingURL=journal-cursor.js.map

package/dist/journal-cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal-cursor.js","sourceRoot":"","sources":["../src/journal-cursor.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,IAAI,GAAG,wBAAwB,CAAC;IAChC,MAAM,GAAG,GAAG,CAAC;IACb,SAAS,GAAG,IAAI,CAAC;IACjB,eAAe,GAAG,CAAC,YAAY,CAAC,CAAC;CAC3C;AAED,MAAM,UAAU,YAAY,CAAC,SAAiB,EAAE,KAAa,EAAE,GAAW;IACxE,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,QAAQ,CACnF,WAAW,CACZ,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,MAAc;IACxC,OAAO,IAAI,kBAAkB,CAAC,qBAAqB,MAAM,0BAA0B,CAAC,CAAC;AACvF,CAAC"}

package/dist/journal-files.d.ts

@@ -0,0 +1,12 @@
+export interface AppendIntent {
+    v: 1;
+    offset: number;
+    length: number;
+}
+export declare function appendAndSync(fd: number, bytes: Buffer): void;
+export declare function ensurePrivateFile(path: string): void;
+export declare function readDescriptor(fd: number): Buffer;
+export declare function readIntent(path: string): AppendIntent | null;
+export declare function writeIntent(path: string, value: AppendIntent): void;
+export declare function removeFile(path: string): void;
+//# sourceMappingURL=journal-files.d.ts.map

package/dist/journal-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal-files.d.ts","sourceRoot":"","sources":["../src/journal-files.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,YAAY;IAC3B,CAAC,EAAE,CAAC,CAAC;IACL,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAI7D;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAcpD;AAED,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAMjD;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAqB5D;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI,CAanE;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAI7C"}

package/dist/journal-files.js

@@ -0,0 +1,84 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, constants, existsSync, fstatSync, fsyncSync, lstatSync, openSync, readFileSync, renameSync, rmSync, writeSync, } from "node:fs";
+import { dirname } from "node:path";
+import { fsyncDirectory } from "@claudexor/util";
+export function appendAndSync(fd, bytes) {
+    let offset = 0;
+    while (offset < bytes.length)
+        offset += writeSync(fd, bytes, offset, bytes.length - offset);
+    fsyncSync(fd);
+}
+export function ensurePrivateFile(path) {
+    if (!existsSync(path)) {
+        const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+        try {
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        fsyncDirectory(dirname(path));
+    }
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== 1) {
+        throw new Error("journal path is not a private regular file");
+    }
+}
+export function readDescriptor(fd) {
+    const size = Number(fstatSync(fd, { bigint: true }).size);
+    if (!Number.isSafeInteger(size) || size < 0)
+        throw new Error("journal file size is invalid");
+    const bytes = readFileSync(fd);
+    if (bytes.length !== size)
+        throw new Error("journal changed while being read");
+    return bytes;
+}
+export function readIntent(path) {
+    if (!existsSync(path))
+        return null;
+    const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > 1024)
+            throw new Error("unsafe file");
+        const value = JSON.parse(readFileSync(fd, "utf8"));
+        if (!isRecord(value) ||
+            value.v !== 1 ||
+            !Number.isSafeInteger(value.offset) ||
+            Number(value.offset) < 0 ||
+            !Number.isSafeInteger(value.length) ||
+            Number(value.length) <= 0) {
+            throw new Error("invalid shape");
+        }
+        return value;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function writeIntent(path, value) {
+    const temp = `${path}.${randomUUID()}.tmp`;
+    const bytes = Buffer.from(`${JSON.stringify(value)}\n`);
+    const fd = openSync(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+    try {
+        let offset = 0;
+        while (offset < bytes.length)
+            offset += writeSync(fd, bytes, offset, bytes.length - offset);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    renameSync(temp, path);
+    fsyncDirectory(dirname(path));
+}
+export function removeFile(path) {
+    if (!existsSync(path))
+        return;
+    rmSync(path);
+    fsyncDirectory(dirname(path));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=journal-files.js.map

package/dist/journal-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal-files.js","sourceRoot":"","sources":["../src/journal-files.ts"],"names":[],"mappings":"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"}

package/dist/journal-partition.d.ts

@@ -0,0 +1,2 @@
+export declare function journalPartitionDirectory(rootDir: string, partition: string): string;
+//# sourceMappingURL=journal-partition.d.ts.map

package/dist/journal-partition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal-partition.d.ts","sourceRoot":"","sources":["../src/journal-partition.ts"],"names":[],"mappings":"AAGA,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAKpF"}

package/dist/journal-partition.js

@@ -0,0 +1,10 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+export function journalPartitionDirectory(rootDir, partition) {
+    if (!partition.trim())
+        throw new Error("journal partition must not be empty");
+    const slug = partition.replace(/[^A-Za-z0-9._-]+/g, "-").slice(0, 48) || "partition";
+    const digest = createHash("sha256").update(Buffer.from(partition)).digest("hex");
+    return join(rootDir, `${slug}-${digest.slice(0, 12)}`);
+}
+//# sourceMappingURL=journal-partition.js.map

package/dist/journal-partition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal-partition.js","sourceRoot":"","sources":["../src/journal-partition.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,UAAU,yBAAyB,CAAC,OAAe,EAAE,SAAiB;IAC1E,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;IAC9E,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,mBAAmB,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,WAAW,CAAC;IACrF,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACjF,OAAO,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;AACzD,CAAC"}

package/dist/read-only-preparation.d.ts

@@ -0,0 +1,41 @@
+import { type JournalRecord } from "./frame-codec.js";
+export interface JournalPreparationReceipt {
+    fingerprint: string;
+    preparationIdentity: string;
+    virtual: boolean;
+    deferredRepair: null | {
+        kind: "discard_unacknowledged_append";
+        discardedBytes: number;
+    };
+}
+export type PreparedJournalRecovery = {
+    status: "ready";
+    discardedTailBytes: number;
+} | {
+    status: "recovery_required";
+    location: {
+        kind: "byte";
+        byteOffset: number;
+    };
+    reason: string;
+    discardedTailBytes: number;
+};
+export interface PreparedJournalInspection {
+    receipt: JournalPreparationReceipt;
+    recovery: PreparedJournalRecovery;
+    records: JournalRecord[];
+    epoch: string;
+    nextSeq: number;
+    previousFrameHash: string;
+    knownFileBytes: number;
+}
+export declare function inspectPreparedJournal(input: {
+    rootDir: string;
+    partitionDir: string;
+    journalPath: string;
+    intentPath: string;
+    partition: string;
+    initialEpoch: string;
+}): PreparedJournalInspection;
+export declare function fingerprintPreparedJournal(rootDir: string, partitionDir: string): Pick<JournalPreparationReceipt, "fingerprint" | "preparationIdentity">;
+//# sourceMappingURL=read-only-preparation.d.ts.map

package/dist/read-only-preparation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-only-preparation.d.ts","sourceRoot":"","sources":["../src/read-only-preparation.ts"],"names":[],"mappings":"AAcA,OAAO,EAA2B,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAE/E,MAAM,WAAW,yBAAyB;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,IAAI,GAAG;QACrB,IAAI,EAAE,+BAA+B,CAAC;QACtC,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC;CACH;AAED,MAAM,MAAM,uBAAuB,GAC/B;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,kBAAkB,EAAE,MAAM,CAAA;CAAE,GAC/C;IACE,MAAM,EAAE,mBAAmB,CAAC;IAC5B,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEN,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,yBAAyB,CAAC;IACnC,QAAQ,EAAE,uBAAuB,CAAC;IAClC,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;CACxB;AAkBD,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,yBAAyB,CAgF5B;AAED,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,GACnB,IAAI,CAAC,yBAAyB,EAAE,aAAa,GAAG,qBAAqB,CAAC,CAMxE"}

package/dist/read-only-preparation.js

@@ -0,0 +1,366 @@
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, readdirSync, readlinkSync, realpathSync, } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { ZERO_HASH, replayFrames } from "./frame-codec.js";
+export function inspectPreparedJournal(input) {
+    const tree = snapshotTree(input.rootDir, input.partitionDir);
+    const journalBytes = tree.files.get(input.journalPath);
+    const intentBytes = tree.files.get(input.intentPath);
+    const unexpected = [...tree.entries].filter((path) => path !== input.journalPath && path !== input.intentPath);
+    let problem = tree.problems[0] ?? null;
+    let byteOffset = 0;
+    let deferredRepair = null;
+    if (!problem &&
+        journalBytes === undefined &&
+        (intentBytes !== undefined || tree.partitionExists)) {
+        if (intentBytes !== undefined || unexpected.length > 0) {
+            problem = "journal file is missing while partition state exists";
+        }
+    }
+    let logicalBytes = journalBytes ?? Buffer.alloc(0);
+    if (!problem && intentBytes !== undefined) {
+        try {
+            const intent = parseIntent(intentBytes);
+            const prefix = replayFrames(logicalBytes.subarray(0, intent.offset), input.partition);
+            if (intent.offset > logicalBytes.length ||
+                logicalBytes.length > intent.offset + intent.length ||
+                prefix.error ||
+                prefix.incompleteOffset !== null) {
+                problem = "append intent does not match the journal prefix";
+                byteOffset = intent.offset;
+            }
+            else {
+                deferredRepair = {
+                    kind: "discard_unacknowledged_append",
+                    discardedBytes: logicalBytes.length - intent.offset,
+                };
+                logicalBytes = logicalBytes.subarray(0, intent.offset);
+            }
+        }
+        catch (error) {
+            problem = `append intent is malformed: ${safeMessage(error)}`;
+        }
+    }
+    const decoded = replayFrames(logicalBytes, input.partition);
+    if (!problem && decoded.incompleteOffset !== null) {
+        problem = "unexplained suffix without append intent";
+        byteOffset = decoded.incompleteOffset;
+    }
+    if (!problem && decoded.error) {
+        problem = decoded.error.reason;
+        byteOffset = decoded.error.offset;
+    }
+    const records = problem ? [] : decoded.records;
+    const last = records.at(-1);
+    const virtual = !tree.rootExists || !tree.partitionExists || journalBytes === undefined;
+    return {
+        receipt: {
+            fingerprint: tree.fingerprint,
+            preparationIdentity: tree.preparationIdentity,
+            virtual,
+            deferredRepair,
+        },
+        recovery: problem
+            ? {
+                status: "recovery_required",
+                location: { kind: "byte", byteOffset },
+                reason: problem,
+                discardedTailBytes: 0,
+            }
+            : { status: "ready", discardedTailBytes: 0 },
+        records,
+        epoch: last?.epoch ?? input.initialEpoch,
+        nextSeq: (last?.seq ?? 0) + 1,
+        previousFrameHash: last?.frameHash ?? ZERO_HASH,
+        knownFileBytes: logicalBytes.length,
+    };
+}
+export function fingerprintPreparedJournal(rootDir, partitionDir) {
+    const observed = snapshotTree(rootDir, partitionDir);
+    return {
+        fingerprint: observed.fingerprint,
+        preparationIdentity: observed.preparationIdentity,
+    };
+}
+function snapshotTree(rootDir, partitionDir) {
+    const contentHash = createHash("sha256");
+    const identityHash = createHash("sha256");
+    const files = new Map();
+    const entries = new Set();
+    const problems = [];
+    if (!inspectTrustedParent(dirname(resolve(rootDir)), identityHash, problems)) {
+        contentHash.update("root\0unreachable\0");
+        return finishSnapshot({
+            contentHash,
+            identityHash,
+            rootExists: false,
+            partitionExists: false,
+            entries,
+            files,
+            problems,
+        });
+    }
+    const root = inspectEntry(rootDir, "root", contentHash, identityHash, files, problems, false);
+    if (root.kind !== "directory") {
+        contentHash.update("partition\0unreachable\0");
+        identityHash.update("partition\0unreachable\0");
+        return finishSnapshot({
+            contentHash,
+            identityHash,
+            rootExists: root.kind !== "missing",
+            partitionExists: false,
+            entries,
+            files,
+            problems,
+        });
+    }
+    const partition = inspectEntry(partitionDir, "partition", contentHash, identityHash, files, problems, false);
+    if (partition.kind === "directory") {
+        walkPartition(partitionDir, partitionDir, partition.stat, contentHash, identityHash, files, entries, problems);
+    }
+    assertDirectoryUnchanged(rootDir, root.stat, problems, "root");
+    return finishSnapshot({
+        contentHash,
+        identityHash,
+        rootExists: true,
+        partitionExists: partition.kind !== "missing",
+        entries,
+        files,
+        problems,
+    });
+}
+function walkPartition(path, partitionDir, before, contentHash, identityHash, files, entries, problems) {
+    let names;
+    try {
+        names = readdirSync(path).sort();
+    }
+    catch (error) {
+        problems.push(`journal partition cannot be listed: ${safeMessage(error)}`);
+        contentHash.update(`list-error\0${safeMessage(error)}\0`);
+        identityHash.update(`list-error\0${safeMessage(error)}\0`);
+        return;
+    }
+    for (const name of names) {
+        const child = `${path}/${name}`;
+        const relative = child.slice(partitionDir.length + 1);
+        entries.add(child);
+        const inspected = inspectEntry(child, relative, contentHash, identityHash, files, problems, true);
+        if (inspected.kind === "directory") {
+            walkPartition(child, partitionDir, inspected.stat, contentHash, identityHash, files, entries, problems);
+        }
+    }
+    try {
+        if (readdirSync(path).sort().join("\0") !== names.join("\0")) {
+            problems.push(`journal directory entries changed while being read: ${path}`);
+        }
+    }
+    catch (error) {
+        problems.push(`journal partition cannot be relisted: ${safeMessage(error)}`);
+    }
+    assertDirectoryUnchanged(path, before, problems, path);
+}
+function inspectEntry(path, label, contentHash, identityHash, files, problems, allowFile) {
+    let stat;
+    try {
+        stat = lstatSync(path, { bigint: true });
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT") {
+            contentHash.update(`${label}\0missing\0`);
+            identityHash.update(`${label}\0missing\0`);
+            assertStillMissing(path, problems, label);
+            return { kind: "missing" };
+        }
+        problems.push(`${label} cannot be inspected: ${safeMessage(error)}`);
+        contentHash.update(`${label}\0error\0${safeMessage(error)}\0`);
+        identityHash.update(`${label}\0error\0${safeMessage(error)}\0`);
+        return { kind: "other" };
+    }
+    contentHash.update(`${label}\0${semanticMetadata(stat)}\0`);
+    identityHash.update(`${label}\0${identityMetadata(stat)}\0`);
+    if (stat.isSymbolicLink()) {
+        try {
+            const target = readlinkSync(path);
+            contentHash.update(`symlink\0${target}\0`);
+            identityHash.update(`symlink\0${target}\0`);
+        }
+        catch (error) {
+            problems.push(`${label} symbolic-link target cannot be read: ${safeMessage(error)}`);
+        }
+        problems.push(`${label} is a symbolic link`);
+        return { kind: "other" };
+    }
+    if (typeof process.getuid === "function" && stat.uid !== BigInt(process.getuid())) {
+        problems.push(`${label} is not owned by the current user`);
+    }
+    if (stat.isDirectory()) {
+        let safe = true;
+        try {
+            if (realpathSync.native(path) !== resolve(path)) {
+                problems.push(`${label} is not canonical`);
+                safe = false;
+            }
+        }
+        catch (error) {
+            problems.push(`${label} cannot be resolved canonically: ${safeMessage(error)}`);
+            safe = false;
+        }
+        if (process.platform !== "win32" && Number(stat.mode & 511n) !== 0o700) {
+            problems.push(`${label} is not private`);
+            safe = false;
+        }
+        if (typeof process.getuid === "function" && stat.uid !== BigInt(process.getuid()))
+            safe = false;
+        return safe ? { kind: "directory", stat } : { kind: "other" };
+    }
+    if (!allowFile || !stat.isFile() || stat.nlink !== 1n) {
+        problems.push(`${label} is not a private regular file`);
+        return { kind: "other" };
+    }
+    if (process.platform !== "win32" && Number(stat.mode & 511n) !== 0o600) {
+        problems.push(`${label} is not private`);
+    }
+    try {
+        const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const opened = fstatSync(fd, { bigint: true });
+            if (opened.dev !== stat.dev ||
+                opened.ino !== stat.ino ||
+                !opened.isFile() ||
+                observationMetadata(opened) !== observationMetadata(stat)) {
+                throw new Error("pathname identity changed while being read");
+            }
+            const bytes = readFileSync(fd);
+            const after = fstatSync(fd, { bigint: true });
+            if (BigInt(bytes.length) !== opened.size ||
+                observationMetadata(opened) !== observationMetadata(after)) {
+                throw new Error("file changed while being read");
+            }
+            const namedAfter = lstatSync(path, { bigint: true });
+            if (observationMetadata(stat) !== observationMetadata(namedAfter)) {
+                throw new Error("pathname identity changed after being read");
+            }
+            files.set(path, bytes);
+            contentHash.update(bytes);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch (error) {
+        problems.push(`${label} cannot be read safely: ${safeMessage(error)}`);
+        contentHash.update(`read-error\0${safeMessage(error)}\0`);
+        identityHash.update(`read-error\0${safeMessage(error)}\0`);
+    }
+    return { kind: "file", stat };
+}
+function finishSnapshot(input) {
+    const fingerprint = input.contentHash.digest("hex");
+    input.identityHash.update(`content\0${fingerprint}\0`);
+    return {
+        fingerprint,
+        preparationIdentity: input.identityHash.digest("hex"),
+        rootExists: input.rootExists,
+        partitionExists: input.partitionExists,
+        entries: input.entries,
+        files: input.files,
+        problems: input.problems,
+    };
+}
+function inspectTrustedParent(path, identityHash, problems) {
+    try {
+        const before = lstatSync(path, { bigint: true });
+        identityHash.update(`trusted-parent\0${identityMetadata(before)}\0`);
+        if (before.isSymbolicLink() ||
+            !before.isDirectory() ||
+            realpathSync.native(path) !== path ||
+            (typeof process.getuid === "function" && before.uid !== BigInt(process.getuid())) ||
+            (process.platform !== "win32" && Number(before.mode & 511n) !== 0o700)) {
+            problems.push("journal root parent is not canonical and private");
+            return false;
+        }
+        const after = lstatSync(path, { bigint: true });
+        if (observationMetadata(before) !== observationMetadata(after)) {
+            problems.push("journal root parent changed while being inspected");
+            return false;
+        }
+        return true;
+    }
+    catch (error) {
+        problems.push(`journal root parent cannot be inspected: ${safeMessage(error)}`);
+        identityHash.update(`trusted-parent-error\0${safeMessage(error)}\0`);
+        return false;
+    }
+}
+function assertDirectoryUnchanged(path, before, problems, label) {
+    try {
+        const after = lstatSync(path, { bigint: true });
+        if (observationMetadata(before) !== observationMetadata(after)) {
+            problems.push(`${label} changed while being inspected`);
+        }
+    }
+    catch (error) {
+        problems.push(`${label} became unavailable while being inspected: ${safeMessage(error)}`);
+    }
+}
+function assertStillMissing(path, problems, label) {
+    try {
+        lstatSync(path);
+        problems.push(`${label} appeared while being inspected`);
+    }
+    catch (error) {
+        if (errorCode(error) !== "ENOENT") {
+            problems.push(`${label} missing state is ambiguous: ${safeMessage(error)}`);
+        }
+    }
+}
+function semanticMetadata(stat) {
+    const base = [entryType(stat), stat.mode & 511n, stat.uid, stat.gid];
+    if (!stat.isDirectory())
+        base.push(stat.nlink, stat.size);
+    return base.join(":");
+}
+function identityMetadata(stat) {
+    const base = [stat.dev, stat.ino, entryType(stat), stat.mode & 511n, stat.uid, stat.gid];
+    if (!stat.isDirectory())
+        base.push(stat.nlink);
+    return base.join(":");
+}
+function observationMetadata(stat) {
+    return [identityMetadata(stat), stat.size, stat.mtimeNs, stat.ctimeNs].join(":");
+}
+function entryType(stat) {
+    if (stat.isDirectory())
+        return "directory";
+    if (stat.isFile())
+        return "file";
+    if (stat.isSymbolicLink())
+        return "symlink";
+    return "other";
+}
+function parseIntent(bytes) {
+    if (bytes.length > 1024)
+        throw new Error("unsafe file");
+    const value = JSON.parse(bytes.toString("utf8"));
+    if (!isRecord(value) ||
+        value.v !== 1 ||
+        !Number.isSafeInteger(value.offset) ||
+        Number(value.offset) < 0 ||
+        !Number.isSafeInteger(value.length) ||
+        Number(value.length) <= 0) {
+        throw new Error("invalid shape");
+    }
+    return value;
+}
+function errorCode(error) {
+    return error && typeof error === "object" && "code" in error
+        ? String(error.code)
+        : undefined;
+}
+function safeMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=read-only-preparation.js.map