narraeon 0.1.0

package/dist/node/runtime/content/CurrentTreeContentLibrary.js

@@ -0,0 +1,721 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync, unlinkSync } from "node:fs";
+import { link, open, mkdir, readFile, readdir, rename, rm, stat, unlink, } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, posix, win32 } from "node:path";
+import { portableContentTreePathKey } from "../../protocol/contentTree.js";
+import { defaultContentWorkspaceLimits, } from "./ContentLimits.js";
+import { inspectContentPackageCurrentTree, isContentPackageWorldDocumentPath, worldDocumentTextRequirement, } from "./FileNativeContentTree.js";
+const localIdPattern = /^package-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+const localMetadataFileName = "local.json";
+const currentTreeFileName = "current-tree.json";
+const currentTreePreviousFileName = ".current-tree.previous.json";
+const defaultLimits = defaultContentWorkspaceLimits;
+export class CurrentTreeContentPackageNotFoundError extends Error {
+    constructor() {
+        super("The requested content package was not found");
+        this.name = "CurrentTreeContentPackageNotFoundError";
+    }
+}
+export class CurrentTreeContentLibraryError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "CurrentTreeContentLibraryError";
+    }
+}
+export class CurrentTreeContentPackageBusyError extends CurrentTreeContentLibraryError {
+    constructor() {
+        super("Another source-package save or model operation is still running");
+        this.name = "CurrentTreeContentPackageBusyError";
+    }
+}
+export class InvalidContentTreeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InvalidContentTreeError";
+    }
+}
+/**
+ * Persists one logical current tree per local package. The tree is stored as a
+ * single replaceable envelope so saving cannot expose half of two file sets.
+ */
+export class CurrentTreeContentLibrary {
+    #locksRoot;
+    #packagesRoot;
+    #stagingRoot;
+    #limits;
+    #beforePackagePublish;
+    #beforeCurrentTreeReplace;
+    #mutationTail = Promise.resolve();
+    constructor(dataRoot, options = {}) {
+        this.#locksRoot = join(dataRoot, "content", ".package-locks");
+        this.#packagesRoot = join(dataRoot, "content", "packages");
+        this.#stagingRoot = join(dataRoot, "content", ".package-staging");
+        this.#limits = normalizeLimits(options.limits);
+        this.#beforePackagePublish = options.beforePackagePublish;
+        this.#beforeCurrentTreeReplace = options.beforeCurrentTreeReplace;
+    }
+    createPackage(files = []) {
+        return this.#mutate(async () => {
+            const normalized = normalizeCurrentContentTreeFiles(files, this.#limits);
+            const package_ = await this.#publishNewPackage(normalized);
+            return packageSummary(package_);
+        });
+    }
+    importPackage(files, options = {}) {
+        return this.#mutate(async () => {
+            options.signal?.throwIfAborted();
+            const normalized = normalizeCurrentContentTreeFiles(files, this.#limits);
+            return this.#publishNewPackage(normalized, options.signal);
+        });
+    }
+    copyPackage(localId, options = {}) {
+        return this.#mutate(async () => {
+            options.signal?.throwIfAborted();
+            const source = await this.readPackage(localId);
+            options.signal?.throwIfAborted();
+            return this.#publishNewPackage(source.files, options.signal);
+        });
+    }
+    deletePackage(localId, options = {}) {
+        return this.#mutate(async () => {
+            const lease = await this.acquireOperationLease(localId, {
+                wait: options.waitForLease !== false,
+            });
+            try {
+                options.signal?.throwIfAborted();
+                await mkdir(this.#stagingRoot, { recursive: true, mode: 0o700 });
+                const tombstonePath = join(this.#stagingRoot, `.deleted-${localId}-${randomUUID()}`);
+                try {
+                    options.signal?.throwIfAborted();
+                    await rename(this.#packageRoot(localId), tombstonePath);
+                    await syncDirectory(this.#packagesRoot);
+                }
+                catch (error) {
+                    if (isAbortError(error))
+                        throw error;
+                    throw new CurrentTreeContentLibraryError("Unable to delete the content package atomically", {
+                        cause: error,
+                    });
+                }
+                await rm(tombstonePath, { force: true, recursive: true }).catch(() => undefined);
+            }
+            finally {
+                lease.release();
+            }
+        });
+    }
+    async listPackages() {
+        let entries;
+        try {
+            entries = await readdir(this.#packagesRoot, { withFileTypes: true });
+        }
+        catch (error) {
+            if (isNodeErrorCode(error, "ENOENT")) {
+                return [];
+            }
+            throw new CurrentTreeContentLibraryError("Unable to list content packages", {
+                cause: error,
+            });
+        }
+        const packages = [];
+        for (const entry of entries.sort((left, right) => compareStrings(left.name, right.name))) {
+            if (!entry.isDirectory() || !localIdPattern.test(entry.name)) {
+                throw new CurrentTreeContentLibraryError("The content-package library contains an unrecognized entry");
+            }
+            const detail = await this.readPackage(entry.name);
+            packages.push(packageSummary(detail));
+        }
+        return packages;
+    }
+    async readPackage(localId) {
+        const packageRoot = this.#packageRoot(localId);
+        const metadata = await readJsonFile(join(packageRoot, localMetadataFileName), () => new CurrentTreeContentPackageNotFoundError(), "The local content-package envelope is damaged");
+        if (!isStoredMetadata(metadata) || metadata.localId !== localId) {
+            throw new CurrentTreeContentLibraryError("The local content-package envelope is damaged");
+        }
+        const storedTree = await readJsonFile(join(packageRoot, currentTreeFileName), () => new CurrentTreeContentLibraryError("The content package has no current tree"), "The content package's current tree is damaged");
+        if (!isStoredCurrentTree(storedTree)) {
+            throw new CurrentTreeContentLibraryError("The content package's current tree is damaged");
+        }
+        let files;
+        try {
+            files = normalizeCurrentContentTreeFiles(storedTree.files, this.#limits);
+        }
+        catch (error) {
+            throw new CurrentTreeContentLibraryError("The content package's current tree is damaged", {
+                cause: error,
+            });
+        }
+        return detail(localId, files, inspectContentPackageCurrentTree(files), metadata.name);
+    }
+    /**
+     * Name a package in the local library. The name lives in the package's own
+     * local shell, not in its content, so renaming never touches a document the
+     * runtime reads during play.
+     */
+    renamePackage(localId, name, options = {}) {
+        return this.#mutate(async () => {
+            const trimmed = name.trim();
+            if (!validPackageName(trimmed))
+                throw new CurrentTreeContentLibraryError("A content-package name must contain 1 to 160 characters and no line breaks");
+            const lease = await this.acquireOperationLease(localId, {
+                wait: options.waitForLease !== false,
+            });
+            try {
+                options.signal?.throwIfAborted();
+                const packageRoot = this.#packageRoot(localId);
+                const metadata = await readJsonFile(join(packageRoot, localMetadataFileName), () => new CurrentTreeContentPackageNotFoundError(), "The local content-package envelope is damaged");
+                if (!isStoredMetadata(metadata) || metadata.localId !== localId)
+                    throw new CurrentTreeContentLibraryError("The local content-package envelope is damaged");
+                const temporaryPath = join(packageRoot, `.local-${randomUUID()}.tmp`);
+                try {
+                    await writeDurableNewFile(temporaryPath, serialize({
+                        schemaVersion: 1,
+                        localId,
+                        name: trimmed,
+                    }));
+                    await rename(temporaryPath, join(packageRoot, localMetadataFileName));
+                    await syncDirectory(packageRoot);
+                }
+                catch (error) {
+                    await rm(temporaryPath, { force: true }).catch(() => undefined);
+                    throw error;
+                }
+                return packageSummary(await this.readPackage(localId));
+            }
+            finally {
+                lease.release();
+            }
+        });
+    }
+    replaceCurrentTree(localId, files, options = {}) {
+        return this.#mutate(async () => {
+            const lease = await this.acquireOperationLease(localId, {
+                wait: options.waitForLease !== false,
+            });
+            try {
+                return await lease.replace(files, options);
+            }
+            finally {
+                lease.release();
+            }
+        });
+    }
+    async acquireOperationLease(localId, options = {}) {
+        this.#packageRoot(localId);
+        await mkdir(this.#locksRoot, { recursive: true, mode: 0o700 });
+        const lockPath = this.#packageLockPath(localId);
+        const reclaimPath = this.#packageReclaimPath(localId);
+        await clearDeadPackageLockMarker(reclaimPath);
+        if (await pathExists(reclaimPath)) {
+            throw new CurrentTreeContentPackageBusyError();
+        }
+        const marker = createPackageLockMarker();
+        const temporaryPath = join(this.#locksRoot, `.${localId}.${marker.token}.tmp`);
+        let handle;
+        try {
+            handle = await open(temporaryPath, "wx", 0o600);
+            await handle.writeFile(`${JSON.stringify(marker)}\n`, "utf8");
+            await handle.sync();
+            await handle.close();
+            handle = undefined;
+            try {
+                await link(temporaryPath, lockPath);
+            }
+            catch (error) {
+                if (!isNodeErrorCode(error, "EEXIST"))
+                    throw error;
+                if (options.wait === true) {
+                    await this.#waitForPackageLock(lockPath, reclaimPath, temporaryPath);
+                }
+                else if (!(await this.#tryReplaceDeadPackageLock(lockPath, reclaimPath, temporaryPath))) {
+                    throw new CurrentTreeContentPackageBusyError();
+                }
+            }
+        }
+        catch (error) {
+            await handle?.close().catch(() => undefined);
+            if (error instanceof CurrentTreeContentPackageBusyError)
+                throw error;
+            throw new CurrentTreeContentLibraryError("Unable to acquire the source-package save owner", {
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+        finally {
+            await unlink(temporaryPath).catch(() => undefined);
+        }
+        let released = false;
+        try {
+            const package_ = await this.readPackage(localId);
+            return {
+                package: structuredClone(package_),
+                replace: async (files, options = {}) => {
+                    if (released)
+                        throw new CurrentTreeContentPackageBusyError();
+                    options.signal?.throwIfAborted();
+                    const normalized = normalizeCurrentContentTreeFiles(files, this.#limits);
+                    return this.#replaceNormalizedCurrentTree(localId, normalized, options.signal);
+                },
+                release: () => {
+                    if (released)
+                        return;
+                    released = true;
+                    releasePackageOperationLockSync(lockPath, marker.token);
+                },
+            };
+        }
+        catch (error) {
+            releasePackageOperationLockSync(lockPath, marker.token);
+            throw error;
+        }
+    }
+    async #replaceNormalizedCurrentTree(localId, normalized, signal) {
+        const packageRoot = this.#packageRoot(localId);
+        const temporaryPath = join(packageRoot, `.current-tree-${randomUUID()}.tmp`);
+        const previousPath = join(packageRoot, currentTreePreviousFileName);
+        try {
+            signal?.throwIfAborted();
+            await writeDurableNewFile(temporaryPath, serialize({
+                schemaVersion: 1,
+                files: normalized,
+            }));
+            await crashProcessAtCurrentTreeEdge("after_current_tree_staging");
+            signal?.throwIfAborted();
+            await this.#beforeCurrentTreeReplace?.();
+            signal?.throwIfAborted();
+            await unlink(previousPath).catch((error) => {
+                if (!isNodeErrorCode(error, "ENOENT"))
+                    throw error;
+            });
+            await link(join(packageRoot, currentTreeFileName), previousPath);
+            await syncDirectory(packageRoot);
+            await rename(temporaryPath, join(packageRoot, currentTreeFileName));
+            await syncDirectory(packageRoot);
+            await crashProcessAtCurrentTreeEdge("after_current_tree_replace");
+            failCurrentTreeAfterReplaceForTest();
+            await unlink(previousPath).catch(() => undefined);
+        }
+        catch (error) {
+            await rm(temporaryPath, { force: true }).catch(() => undefined);
+            let rollbackFailure;
+            if (await pathExists(previousPath).catch(() => false)) {
+                try {
+                    await rename(previousPath, join(packageRoot, currentTreeFileName));
+                    await syncDirectory(packageRoot);
+                }
+                catch (rollbackError) {
+                    rollbackFailure = rollbackError;
+                }
+            }
+            if (rollbackFailure !== undefined) {
+                throw new CurrentTreeContentLibraryError("Unable to restore the content package's previous current tree", {
+                    cause: rollbackFailure instanceof Error ? rollbackFailure : undefined,
+                });
+            }
+            if (error instanceof InvalidContentTreeError || isAbortError(error)) {
+                throw error;
+            }
+            throw new CurrentTreeContentLibraryError(error instanceof Error
+                ? error.message
+                : "Unable to replace the content package's current tree atomically", { cause: error });
+        }
+        return detail(localId, normalized, inspectContentPackageCurrentTree(normalized));
+    }
+    async #publishNewPackage(normalized, signal) {
+        const localId = `package-${randomUUID()}`;
+        const stagingPath = join(this.#stagingRoot, localId);
+        const finalPath = join(this.#packagesRoot, localId);
+        await Promise.all([
+            mkdir(this.#packagesRoot, { recursive: true, mode: 0o700 }),
+            mkdir(this.#stagingRoot, { recursive: true, mode: 0o700 }),
+        ]);
+        try {
+            signal?.throwIfAborted();
+            await mkdir(stagingPath, { mode: 0o700 });
+            await writeDurableNewFile(join(stagingPath, localMetadataFileName), serialize({
+                schemaVersion: 1,
+                localId,
+            }));
+            await writeDurableNewFile(join(stagingPath, currentTreeFileName), serialize({
+                schemaVersion: 1,
+                files: normalized,
+            }));
+            await syncDirectory(stagingPath);
+            await crashProcessAtCurrentTreeEdge("after_package_staging");
+            signal?.throwIfAborted();
+            await this.#beforePackagePublish?.();
+            signal?.throwIfAborted();
+            await rename(stagingPath, finalPath);
+            await syncDirectory(this.#packagesRoot);
+            await crashProcessAtCurrentTreeEdge("after_package_publish");
+        }
+        catch (error) {
+            await rm(stagingPath, { force: true, recursive: true }).catch(() => undefined);
+            if (isAbortError(error))
+                throw error;
+            throw new CurrentTreeContentLibraryError("Unable to publish the content package atomically", {
+                cause: error,
+            });
+        }
+        return detail(localId, normalized, inspectContentPackageCurrentTree(normalized));
+    }
+    #packageRoot(localId) {
+        if (!localIdPattern.test(localId)) {
+            throw new CurrentTreeContentPackageNotFoundError();
+        }
+        return join(this.#packagesRoot, localId);
+    }
+    #packageLockPath(localId) {
+        return join(this.#locksRoot, `${localId}.mutation`);
+    }
+    #packageReclaimPath(localId) {
+        return join(this.#locksRoot, `${localId}.reclaim`);
+    }
+    async #tryReplaceDeadPackageLock(lockPath, reclaimPath, replacementPath) {
+        const current = await readPackageLockMarker(lockPath);
+        if (current === null || isProcessAlive(current.pid))
+            return false;
+        const reclaim = createPackageLockMarker();
+        const temporaryPath = join(this.#locksRoot, `.reclaim.${reclaim.token}.tmp`);
+        let handle;
+        try {
+            handle = await open(temporaryPath, "wx", 0o600);
+            await handle.writeFile(`${JSON.stringify(reclaim)}\n`, "utf8");
+            await handle.sync();
+            await handle.close();
+            handle = undefined;
+            await link(temporaryPath, reclaimPath);
+        }
+        catch (error) {
+            await handle?.close().catch(() => undefined);
+            if (isNodeErrorCode(error, "EEXIST"))
+                return false;
+            throw error;
+        }
+        finally {
+            await unlink(temporaryPath).catch(() => undefined);
+        }
+        try {
+            const verified = await readPackageLockMarker(lockPath);
+            if (verified?.token !== current.token || isProcessAlive(current.pid)) {
+                return false;
+            }
+            await unlink(lockPath).catch((error) => {
+                if (!isNodeErrorCode(error, "ENOENT"))
+                    throw error;
+            });
+            await link(replacementPath, lockPath);
+            return true;
+        }
+        finally {
+            const owner = await readPackageLockMarker(reclaimPath);
+            if (owner?.token === reclaim.token) {
+                await unlink(reclaimPath).catch(() => undefined);
+            }
+        }
+    }
+    async #waitForPackageLock(lockPath, reclaimPath, replacementPath) {
+        for (let attempt = 0; attempt < 2_000; attempt += 1) {
+            if ((await this.#tryReplaceDeadPackageLock(lockPath, reclaimPath, replacementPath)) ||
+                (await link(replacementPath, lockPath)
+                    .then(() => true)
+                    .catch((error) => {
+                    if (isNodeErrorCode(error, "EEXIST"))
+                        return false;
+                    throw error;
+                }))) {
+                return;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 5));
+        }
+        throw new CurrentTreeContentPackageBusyError();
+    }
+    async #mutate(operation) {
+        const previous = this.#mutationTail;
+        let release = () => undefined;
+        this.#mutationTail = new Promise((resolve) => {
+            release = resolve;
+        });
+        await previous;
+        try {
+            return await operation();
+        }
+        finally {
+            release();
+        }
+    }
+}
+function detail(localId, files, inspection, name) {
+    return {
+        ...summary(localId, inspection, name),
+        files: files.map((file) => ({ ...file })),
+        documents: structuredClone(inspection.documents),
+        issues: structuredClone(inspection.issues),
+        opening: inspection.opening,
+        control: structuredClone(inspection.control),
+    };
+}
+function summary(localId, inspection, name) {
+    return {
+        localId,
+        // An author-chosen name wins; without one the name still tracks whatever
+        // the package currently contains.
+        displayName: name ?? inspection.displayName,
+        status: inspection.status,
+        documentCount: inspection.documents.length,
+        issueCount: inspection.issues.length,
+    };
+}
+function packageSummary(package_) {
+    return {
+        localId: package_.localId,
+        displayName: package_.displayName,
+        status: package_.status,
+        documentCount: package_.documentCount,
+        issueCount: package_.issueCount,
+    };
+}
+export function normalizeCurrentContentTreeFiles(files, limits = defaultLimits) {
+    if (files.length > limits.maxFiles) {
+        throw new InvalidContentTreeError("The content package exceeds the file-count limit");
+    }
+    const normalized = [];
+    const portableKeys = new Set();
+    let totalBytes = 0;
+    for (const file of files) {
+        if (typeof file !== "object" ||
+            file === null ||
+            typeof file.path !== "string" ||
+            typeof file.contents !== "string" ||
+            (file.encoding !== undefined && file.encoding !== "base64")) {
+            throw new InvalidContentTreeError("Every content-package file must contain a path and text content");
+        }
+        const path = normalizeContentTreePath(file.path);
+        if (isContentPackageWorldDocumentPath(path) &&
+            file.encoding !== undefined) {
+            throw new InvalidContentTreeError(worldDocumentTextRequirement(path));
+        }
+        const leaf = basename(path).toLocaleLowerCase("en-US");
+        if (leaf === "manifest.json" || leaf.endsWith(".package.json")) {
+            throw new InvalidContentTreeError(`The current content tree does not allow manifest files: ${path}`);
+        }
+        const portableKey = portableContentTreePathKey(path);
+        if (portableKeys.has(portableKey)) {
+            throw new InvalidContentTreeError(`The content tree contains a duplicate normalized path: ${path}`);
+        }
+        portableKeys.add(portableKey);
+        const bytes = file.encoding === "base64"
+            ? decodeCanonicalBase64(file.contents, path).byteLength
+            : Buffer.byteLength(file.contents, "utf8");
+        if (bytes > limits.maxFileBytes) {
+            throw new InvalidContentTreeError(`A content-package file exceeds the size limit: ${path}`);
+        }
+        totalBytes += bytes;
+        if (totalBytes > limits.maxTotalBytes) {
+            throw new InvalidContentTreeError("The content package exceeds the total-size limit");
+        }
+        normalized.push({
+            path,
+            contents: file.contents,
+            ...(file.encoding === undefined ? {} : { encoding: file.encoding }),
+        });
+    }
+    return normalized.sort((left, right) => compareStrings(left.path, right.path));
+}
+function decodeCanonicalBase64(contents, path) {
+    if (contents.length % 4 !== 0 ||
+        !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(contents)) {
+        throw new InvalidContentTreeError(`A binary content-package asset is not canonical Base64: ${path}`);
+    }
+    const decoded = Buffer.from(contents, "base64");
+    if (decoded.toString("base64") !== contents) {
+        throw new InvalidContentTreeError(`A binary content-package asset is not canonical Base64: ${path}`);
+    }
+    return decoded;
+}
+function normalizeContentTreePath(value) {
+    if (value.length === 0 ||
+        [...value].length > 512 ||
+        value.includes("\\") ||
+        value.includes("\0") ||
+        isAbsolute(value) ||
+        win32.isAbsolute(value)) {
+        throw new InvalidContentTreeError(`Invalid content-tree path: ${value}`);
+    }
+    const normalized = posix.normalize(value.normalize("NFC"));
+    const segments = normalized.split("/");
+    if (normalized === "." ||
+        normalized.startsWith("../") ||
+        Buffer.byteLength(normalized, "utf8") > 240 ||
+        segments.length > 16 ||
+        segments.some((segment) => segment.length === 0 ||
+            segment === "." ||
+            segment === ".." ||
+            Buffer.byteLength(segment, "utf8") > 80 ||
+            containsControlCharacter(segment))) {
+        throw new InvalidContentTreeError(`Invalid content-tree path: ${value}`);
+    }
+    return normalized;
+}
+function containsControlCharacter(value) {
+    return [...value].some((character) => {
+        const codePoint = character.codePointAt(0) ?? 0;
+        return codePoint <= 0x1f || codePoint === 0x7f;
+    });
+}
+function normalizeLimits(input) {
+    const limits = { ...defaultLimits, ...input };
+    for (const [name, value] of Object.entries(limits)) {
+        if (!Number.isSafeInteger(value) || value <= 0) {
+            throw new TypeError(`${name} must be a positive safe integer`);
+        }
+    }
+    if (limits.maxFileBytes > limits.maxTotalBytes) {
+        throw new TypeError("maxFileBytes must not exceed maxTotalBytes");
+    }
+    return limits;
+}
+async function writeDurableNewFile(path, contents) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const handle = await open(path, "wx", 0o600);
+    try {
+        await handle.writeFile(contents, "utf8");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function syncDirectory(path) {
+    const handle = await open(path, "r");
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function readJsonFile(path, missing, invalidMessage) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        if (isNodeErrorCode(error, "ENOENT")) {
+            throw missing();
+        }
+        throw new CurrentTreeContentLibraryError(invalidMessage, { cause: error });
+    }
+}
+function isStoredMetadata(value) {
+    return (isPlainObject(value) &&
+        Object.keys(value).length === (value.name === undefined ? 2 : 3) &&
+        value.schemaVersion === 1 &&
+        typeof value.localId === "string" &&
+        localIdPattern.test(value.localId) &&
+        (value.name === undefined ||
+            (typeof value.name === "string" && validPackageName(value.name))));
+}
+const packageNamePattern = /^[^\r\n]{1,160}$/u;
+function validPackageName(name) {
+    return packageNamePattern.test(name);
+}
+function isStoredCurrentTree(value) {
+    return (isPlainObject(value) &&
+        Object.keys(value).length === 2 &&
+        value.schemaVersion === 1 &&
+        Array.isArray(value.files));
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function serialize(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+function createPackageLockMarker() {
+    return { schemaVersion: 1, pid: process.pid, token: randomUUID() };
+}
+async function readPackageLockMarker(path) {
+    try {
+        const value = JSON.parse(await readFile(path, "utf8"));
+        return parsePackageLockMarker(value);
+    }
+    catch {
+        return null;
+    }
+}
+function parsePackageLockMarker(value) {
+    if (isPlainObject(value) &&
+        value.schemaVersion === 1 &&
+        typeof value.pid === "number" &&
+        Number.isSafeInteger(value.pid) &&
+        value.pid > 0 &&
+        typeof value.token === "string" &&
+        /^[0-9a-f-]{36}$/u.test(value.token)) {
+        return { schemaVersion: 1, pid: value.pid, token: value.token };
+    }
+    return null;
+}
+function releasePackageOperationLockSync(path, token) {
+    try {
+        const current = parsePackageLockMarker(JSON.parse(readFileSync(path, "utf8")));
+        if (current?.token === token)
+            unlinkSync(path);
+    }
+    catch (error) {
+        if (!isNodeErrorCode(error, "ENOENT"))
+            throw error;
+    }
+}
+async function clearDeadPackageLockMarker(path) {
+    const marker = await readPackageLockMarker(path);
+    if ((marker !== null && !isProcessAlive(marker.pid)) ||
+        (marker === null && (await pathExists(path)))) {
+        await unlink(path).catch(() => undefined);
+    }
+}
+async function pathExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch (error) {
+        if (isNodeErrorCode(error, "ENOENT"))
+            return false;
+        throw error;
+    }
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return !isNodeErrorCode(error, "ESRCH");
+    }
+}
+function isNodeErrorCode(error, code) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === code);
+}
+function isAbortError(error) {
+    return error instanceof Error && error.name === "AbortError";
+}
+async function crashProcessAtCurrentTreeEdge(edge) {
+    if (process.env.NODE_ENV !== "test" ||
+        process.env.NARRAEON_INTERNAL_TEST_CRASH_AT_CURRENT_TREE_EDGE !== edge) {
+        return;
+    }
+    process.kill(process.pid, "SIGKILL");
+    await new Promise(() => undefined);
+}
+function failCurrentTreeAfterReplaceForTest() {
+    if (process.env.NODE_ENV === "test" &&
+        process.env.NARRAEON_INTERNAL_TEST_FAIL_AFTER_CURRENT_TREE_REPLACE === "1") {
+        throw new Error("simulated failure after current tree replace");
+    }
+}
+function compareStrings(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}