open-multi-agent-kit 0.90.8 → 0.91.0

package/dist/core/durable-file-io.js

@@ -0,0 +1,179 @@
+import { createHash } from "node:crypto";
+import { closeSync, existsSync, fstatSync, fsyncSync, openSync, readFileSync, realpathSync, statSync, unlinkSync, writeSync, } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { ensureDurableParentDirectorySync, fsyncDirectorySync } from "./durable-file-directory.js";
+import { enforcePrivateFileDescriptorModeSync } from "./durable-file-mode.js";
+export { ensureDurableDirectorySync, ensureDurableParentDirectorySync, fsyncDirectorySync, } from "./durable-file-directory.js";
+export class DurableFileReadRaceError extends Error {
+    constructor() {
+        super("Durable file identity or bytes changed while being read");
+        this.name = "DurableFileReadRaceError";
+    }
+}
+function generation(stat) {
+    return Object.freeze({
+        dev: stat.dev.toString(),
+        ino: stat.ino.toString(),
+        birthtimeNs: stat.birthtimeNs.toString(),
+        ctimeNs: stat.ctimeNs.toString(),
+    });
+}
+export function normalizeDurablePathIdentity(path, platform) {
+    if (platform === "darwin")
+        return path.normalize("NFD").toLowerCase();
+    if (platform === "win32")
+        return path.normalize("NFC").toLowerCase();
+    return path;
+}
+function canonicalizePath(path) {
+    const requested = resolve(path);
+    let cursor = requested;
+    const tail = [];
+    while (true) {
+        try {
+            return resolve(realpathSync.native(cursor), ...tail);
+        }
+        catch (error) {
+            const code = error instanceof Error && "code" in error ? Reflect.get(error, "code") : undefined;
+            if (code !== "ENOENT" && code !== "ENOTDIR")
+                throw error;
+            const parent = dirname(cursor);
+            if (parent === cursor)
+                return requested;
+            tail.unshift(basename(cursor));
+            cursor = parent;
+        }
+    }
+}
+export function resolveDurableFileIdentity(path) {
+    const canonicalPath = canonicalizePath(path);
+    let fileGeneration = null;
+    try {
+        fileGeneration = generation(statSync(path, { bigint: true }));
+    }
+    catch (error) {
+        const code = error instanceof Error && "code" in error ? Reflect.get(error, "code") : undefined;
+        if (code !== "ENOENT" && code !== "ENOTDIR")
+            throw error;
+    }
+    const lockPathIdentity = normalizeDurablePathIdentity(canonicalPath, process.platform);
+    const pathKey = createHash("sha256").update(`path\0${lockPathIdentity}`, "utf8").digest("hex");
+    const aliasKey = fileGeneration
+        ? createHash("sha256")
+            .update(`inode\0${fileGeneration.dev}\0${fileGeneration.ino}\0${fileGeneration.birthtimeNs}`, "utf8")
+            .digest("hex")
+        : pathKey;
+    return Object.freeze({
+        canonicalPath,
+        generation: fileGeneration,
+        pathKey,
+        aliasKey,
+        lockKeys: Object.freeze([...new Set([pathKey, aliasKey])].sort()),
+    });
+}
+export function sameDurableFileGeneration(left, right) {
+    if (left === null || right === null)
+        return left === right;
+    return (left.dev === right.dev &&
+        left.ino === right.ino &&
+        left.birthtimeNs === right.birthtimeNs &&
+        left.ctimeNs === right.ctimeNs);
+}
+export function readDurableFileSnapshot(path) {
+    let fd;
+    try {
+        fd = openSync(path, "r");
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && Reflect.get(error, "code") === "ENOENT")
+            return null;
+        throw error;
+    }
+    try {
+        enforcePrivateFileDescriptorModeSync(fd, path);
+        const before = fstatSync(fd, { bigint: true });
+        const bytes = readFileSync(fd);
+        const after = fstatSync(fd, { bigint: true });
+        let current;
+        try {
+            current = statSync(path, { bigint: true });
+        }
+        catch {
+            throw new DurableFileReadRaceError();
+        }
+        if (before.dev !== after.dev ||
+            before.ino !== after.ino ||
+            before.size !== after.size ||
+            before.mtimeNs !== after.mtimeNs ||
+            before.ctimeNs !== after.ctimeNs ||
+            before.dev !== current.dev ||
+            before.ino !== current.ino ||
+            before.size !== current.size ||
+            before.mtimeNs !== current.mtimeNs ||
+            before.ctimeNs !== current.ctimeNs ||
+            before.birthtimeNs !== current.birthtimeNs) {
+            throw new DurableFileReadRaceError();
+        }
+        return Object.freeze({ bytes, generation: generation(before) });
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function writeAll(fd, bytes) {
+    let offset = 0;
+    while (offset < bytes.byteLength) {
+        offset += writeSync(fd, bytes, offset, bytes.byteLength - offset);
+    }
+}
+/** Append without truncation. On an indeterminate fsync failure, visible bytes are retained. */
+export function appendFileDurablySync(path, bytes) {
+    ensureDurableParentDirectorySync(path);
+    const existed = existsSync(path);
+    const fd = openSync(path, "a", 0o600);
+    try {
+        enforcePrivateFileDescriptorModeSync(fd, path);
+        writeAll(fd, bytes);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    if (!existed)
+        fsyncDirectorySync(dirname(path));
+}
+export function writeExclusiveFileDurablySync(path, bytes) {
+    ensureDurableParentDirectorySync(path);
+    const fd = openSync(path, "wx", 0o600);
+    try {
+        enforcePrivateFileDescriptorModeSync(fd, path);
+        writeAll(fd, bytes);
+        fsyncSync(fd);
+    }
+    catch (error) {
+        closeSync(fd);
+        try {
+            unlinkSync(path);
+            fsyncDirectorySync(dirname(path));
+        }
+        catch (cleanupError) {
+            throw new AggregateError([error, cleanupError], "Exclusive durable file cleanup failed");
+        }
+        throw error;
+    }
+    closeSync(fd);
+    try {
+        fsyncDirectorySync(dirname(path));
+    }
+    catch (error) {
+        try {
+            unlinkSync(path);
+            fsyncDirectorySync(dirname(path));
+        }
+        catch (cleanupError) {
+            throw new AggregateError([error, cleanupError], "Exclusive durable file rollback failed");
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=durable-file-io.js.map

package/dist/core/durable-file-io.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-file-io.js","sourceRoot":"","sources":["../../src/core/durable-file-io.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from \"node:crypto\";\nimport {\n\ttype BigIntStats,\n\tcloseSync,\n\texistsSync,\n\tfstatSync,\n\tfsyncSync,\n\topenSync,\n\treadFileSync,\n\trealpathSync,\n\tstatSync,\n\tunlinkSync,\n\twriteSync,\n} from \"node:fs\";\nimport { basename, dirname, resolve } from \"node:path\";\nimport { ensureDurableParentDirectorySync, fsyncDirectorySync } from \"./durable-file-directory.ts\";\nimport { enforcePrivateFileDescriptorModeSync } from \"./durable-file-mode.ts\";\n\nexport {\n\tensureDurableDirectorySync,\n\tensureDurableParentDirectorySync,\n\tfsyncDirectorySync,\n} from \"./durable-file-directory.ts\";\n\nexport interface DurableFileGeneration {\n\treadonly dev: string;\n\treadonly ino: string;\n\treadonly birthtimeNs: string;\n\treadonly ctimeNs: string;\n}\n\nexport interface DurableFileIdentity {\n\treadonly canonicalPath: string;\n\treadonly generation: DurableFileGeneration | null;\n\treadonly pathKey: string;\n\treadonly aliasKey: string;\n\treadonly lockKeys: readonly string[];\n}\n\nexport interface DurableFileSnapshot {\n\treadonly bytes: Uint8Array;\n\treadonly generation: DurableFileGeneration;\n}\n\nexport class DurableFileReadRaceError extends Error {\n\tconstructor() {\n\t\tsuper(\"Durable file identity or bytes changed while being read\");\n\t\tthis.name = \"DurableFileReadRaceError\";\n\t}\n}\n\nfunction generation(stat: BigIntStats): DurableFileGeneration {\n\treturn Object.freeze({\n\t\tdev: stat.dev.toString(),\n\t\tino: stat.ino.toString(),\n\t\tbirthtimeNs: stat.birthtimeNs.toString(),\n\t\tctimeNs: stat.ctimeNs.toString(),\n\t});\n}\n\nexport function normalizeDurablePathIdentity(path: string, platform: NodeJS.Platform): string {\n\tif (platform === \"darwin\") return path.normalize(\"NFD\").toLowerCase();\n\tif (platform === \"win32\") return path.normalize(\"NFC\").toLowerCase();\n\treturn path;\n}\n\nfunction canonicalizePath(path: string): string {\n\tconst requested = resolve(path);\n\tlet cursor = requested;\n\tconst tail: string[] = [];\n\twhile (true) {\n\t\ttry {\n\t\t\treturn resolve(realpathSync.native(cursor), ...tail);\n\t\t} catch (error) {\n\t\t\tconst code = error instanceof Error && \"code\" in error ? Reflect.get(error, \"code\") : undefined;\n\t\t\tif (code !== \"ENOENT\" && code !== \"ENOTDIR\") throw error;\n\t\t\tconst parent = dirname(cursor);\n\t\t\tif (parent === cursor) return requested;\n\t\t\ttail.unshift(basename(cursor));\n\t\t\tcursor = parent;\n\t\t}\n\t}\n}\n\nexport function resolveDurableFileIdentity(path: string): DurableFileIdentity {\n\tconst canonicalPath = canonicalizePath(path);\n\tlet fileGeneration: DurableFileGeneration | null = null;\n\ttry {\n\t\tfileGeneration = generation(statSync(path, { bigint: true }));\n\t} catch (error) {\n\t\tconst code = error instanceof Error && \"code\" in error ? Reflect.get(error, \"code\") : undefined;\n\t\tif (code !== \"ENOENT\" && code !== \"ENOTDIR\") throw error;\n\t}\n\tconst lockPathIdentity = normalizeDurablePathIdentity(canonicalPath, process.platform);\n\tconst pathKey = createHash(\"sha256\").update(`path\\0${lockPathIdentity}`, \"utf8\").digest(\"hex\");\n\tconst aliasKey = fileGeneration\n\t\t? createHash(\"sha256\")\n\t\t\t\t.update(`inode\\0${fileGeneration.dev}\\0${fileGeneration.ino}\\0${fileGeneration.birthtimeNs}`, \"utf8\")\n\t\t\t\t.digest(\"hex\")\n\t\t: pathKey;\n\treturn Object.freeze({\n\t\tcanonicalPath,\n\t\tgeneration: fileGeneration,\n\t\tpathKey,\n\t\taliasKey,\n\t\tlockKeys: Object.freeze([...new Set([pathKey, aliasKey])].sort()),\n\t});\n}\n\nexport function sameDurableFileGeneration(\n\tleft: DurableFileGeneration | null,\n\tright: DurableFileGeneration | null,\n): boolean {\n\tif (left === null || right === null) return left === right;\n\treturn (\n\t\tleft.dev === right.dev &&\n\t\tleft.ino === right.ino &&\n\t\tleft.birthtimeNs === right.birthtimeNs &&\n\t\tleft.ctimeNs === right.ctimeNs\n\t);\n}\n\nexport function readDurableFileSnapshot(path: string): DurableFileSnapshot | null {\n\tlet fd: number;\n\ttry {\n\t\tfd = openSync(path, \"r\");\n\t} catch (error) {\n\t\tif (error instanceof Error && \"code\" in error && Reflect.get(error, \"code\") === \"ENOENT\") return null;\n\t\tthrow error;\n\t}\n\ttry {\n\t\tenforcePrivateFileDescriptorModeSync(fd, path);\n\t\tconst before = fstatSync(fd, { bigint: true });\n\t\tconst bytes: Uint8Array = readFileSync(fd);\n\t\tconst after = fstatSync(fd, { bigint: true });\n\t\tlet current: BigIntStats;\n\t\ttry {\n\t\t\tcurrent = statSync(path, { bigint: true });\n\t\t} catch {\n\t\t\tthrow new DurableFileReadRaceError();\n\t\t}\n\t\tif (\n\t\t\tbefore.dev !== after.dev ||\n\t\t\tbefore.ino !== after.ino ||\n\t\t\tbefore.size !== after.size ||\n\t\t\tbefore.mtimeNs !== after.mtimeNs ||\n\t\t\tbefore.ctimeNs !== after.ctimeNs ||\n\t\t\tbefore.dev !== current.dev ||\n\t\t\tbefore.ino !== current.ino ||\n\t\t\tbefore.size !== current.size ||\n\t\t\tbefore.mtimeNs !== current.mtimeNs ||\n\t\t\tbefore.ctimeNs !== current.ctimeNs ||\n\t\t\tbefore.birthtimeNs !== current.birthtimeNs\n\t\t) {\n\t\t\tthrow new DurableFileReadRaceError();\n\t\t}\n\t\treturn Object.freeze({ bytes, generation: generation(before) });\n\t} finally {\n\t\tcloseSync(fd);\n\t}\n}\n\nfunction writeAll(fd: number, bytes: Uint8Array): void {\n\tlet offset = 0;\n\twhile (offset < bytes.byteLength) {\n\t\toffset += writeSync(fd, bytes, offset, bytes.byteLength - offset);\n\t}\n}\n\n/** Append without truncation. On an indeterminate fsync failure, visible bytes are retained. */\nexport function appendFileDurablySync(path: string, bytes: Uint8Array): void {\n\tensureDurableParentDirectorySync(path);\n\tconst existed = existsSync(path);\n\tconst fd = openSync(path, \"a\", 0o600);\n\ttry {\n\t\tenforcePrivateFileDescriptorModeSync(fd, path);\n\t\twriteAll(fd, bytes);\n\t\tfsyncSync(fd);\n\t} finally {\n\t\tcloseSync(fd);\n\t}\n\tif (!existed) fsyncDirectorySync(dirname(path));\n}\n\nexport function writeExclusiveFileDurablySync(path: string, bytes: Uint8Array): void {\n\tensureDurableParentDirectorySync(path);\n\tconst fd = openSync(path, \"wx\", 0o600);\n\ttry {\n\t\tenforcePrivateFileDescriptorModeSync(fd, path);\n\t\twriteAll(fd, bytes);\n\t\tfsyncSync(fd);\n\t} catch (error) {\n\t\tcloseSync(fd);\n\t\ttry {\n\t\t\tunlinkSync(path);\n\t\t\tfsyncDirectorySync(dirname(path));\n\t\t} catch (cleanupError) {\n\t\t\tthrow new AggregateError([error, cleanupError], \"Exclusive durable file cleanup failed\");\n\t\t}\n\t\tthrow error;\n\t}\n\tcloseSync(fd);\n\ttry {\n\t\tfsyncDirectorySync(dirname(path));\n\t} catch (error) {\n\t\ttry {\n\t\t\tunlinkSync(path);\n\t\t\tfsyncDirectorySync(dirname(path));\n\t\t} catch (cleanupError) {\n\t\t\tthrow new AggregateError([error, cleanupError], \"Exclusive durable file rollback failed\");\n\t\t}\n\t\tthrow error;\n\t}\n}\n"]}

package/dist/core/durable-file-lock-cleanup.d.ts

@@ -0,0 +1,12 @@
+/** Mutable progress is retained by the owning lock so failed cleanup can be retried. */
+export interface DurableFileLockRetirement {
+    retiredPath: string | undefined;
+    retirementSynced: boolean;
+    ownerRemoved: boolean;
+    directoryRemoved: boolean;
+    cleanupSynced: boolean;
+}
+export declare function createDurableFileLockRetirement(): DurableFileLockRetirement;
+/** Atomically retire an active lock and durably clean its private artifact. */
+export declare function retireDurableFileLockSync(lockPath: string, retirement: DurableFileLockRetirement): void;
+//# sourceMappingURL=durable-file-lock-cleanup.d.ts.map

package/dist/core/durable-file-lock-cleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-file-lock-cleanup.d.ts","sourceRoot":"","sources":["../../src/core/durable-file-lock-cleanup.ts"],"names":[],"mappings":"AAKA,wFAAwF;AACxF,MAAM,WAAW,yBAAyB;IACzC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,gBAAgB,EAAE,OAAO,CAAC;IAC1B,YAAY,EAAE,OAAO,CAAC;IACtB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,aAAa,EAAE,OAAO,CAAC;CACvB;AAED,wBAAgB,+BAA+B,IAAI,yBAAyB,CAQ3E;AAED,+EAA+E;AAC/E,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,yBAAyB,GAAG,IAAI,CAuBvG","sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport { renameSync, rmdirSync, unlinkSync } from \"node:fs\";\nimport { dirname } from \"node:path\";\nimport { fsyncDirectorySync } from \"./durable-file-io.ts\";\n\n/** Mutable progress is retained by the owning lock so failed cleanup can be retried. */\nexport interface DurableFileLockRetirement {\n\tretiredPath: string | undefined;\n\tretirementSynced: boolean;\n\townerRemoved: boolean;\n\tdirectoryRemoved: boolean;\n\tcleanupSynced: boolean;\n}\n\nexport function createDurableFileLockRetirement(): DurableFileLockRetirement {\n\treturn {\n\t\tretiredPath: undefined,\n\t\tretirementSynced: false,\n\t\townerRemoved: false,\n\t\tdirectoryRemoved: false,\n\t\tcleanupSynced: false,\n\t};\n}\n\n/** Atomically retire an active lock and durably clean its private artifact. */\nexport function retireDurableFileLockSync(lockPath: string, retirement: DurableFileLockRetirement): void {\n\tif (retirement.retiredPath === undefined) {\n\t\tconst retiredPath = `${lockPath}.release-${randomUUID()}`;\n\t\trenameSync(lockPath, retiredPath);\n\t\tretirement.retiredPath = retiredPath;\n\t}\n\tif (!retirement.retirementSynced) {\n\t\tfsyncDirectorySync(dirname(lockPath));\n\t\tretirement.retirementSynced = true;\n\t}\n\tconst retiredPath = retirement.retiredPath;\n\tif (!retirement.ownerRemoved) {\n\t\tunlinkSync(`${retiredPath}/owner.json`);\n\t\tretirement.ownerRemoved = true;\n\t}\n\tif (!retirement.directoryRemoved) {\n\t\trmdirSync(retiredPath);\n\t\tretirement.directoryRemoved = true;\n\t}\n\tif (!retirement.cleanupSynced) {\n\t\tfsyncDirectorySync(dirname(lockPath));\n\t\tretirement.cleanupSynced = true;\n\t}\n}\n"]}

package/dist/core/durable-file-lock-cleanup.js

@@ -0,0 +1,39 @@
+import { randomUUID } from "node:crypto";
+import { renameSync, rmdirSync, unlinkSync } from "node:fs";
+import { dirname } from "node:path";
+import { fsyncDirectorySync } from "./durable-file-io.js";
+export function createDurableFileLockRetirement() {
+    return {
+        retiredPath: undefined,
+        retirementSynced: false,
+        ownerRemoved: false,
+        directoryRemoved: false,
+        cleanupSynced: false,
+    };
+}
+/** Atomically retire an active lock and durably clean its private artifact. */
+export function retireDurableFileLockSync(lockPath, retirement) {
+    if (retirement.retiredPath === undefined) {
+        const retiredPath = `${lockPath}.release-${randomUUID()}`;
+        renameSync(lockPath, retiredPath);
+        retirement.retiredPath = retiredPath;
+    }
+    if (!retirement.retirementSynced) {
+        fsyncDirectorySync(dirname(lockPath));
+        retirement.retirementSynced = true;
+    }
+    const retiredPath = retirement.retiredPath;
+    if (!retirement.ownerRemoved) {
+        unlinkSync(`${retiredPath}/owner.json`);
+        retirement.ownerRemoved = true;
+    }
+    if (!retirement.directoryRemoved) {
+        rmdirSync(retiredPath);
+        retirement.directoryRemoved = true;
+    }
+    if (!retirement.cleanupSynced) {
+        fsyncDirectorySync(dirname(lockPath));
+        retirement.cleanupSynced = true;
+    }
+}
+//# sourceMappingURL=durable-file-lock-cleanup.js.map

package/dist/core/durable-file-lock-cleanup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-file-lock-cleanup.js","sourceRoot":"","sources":["../../src/core/durable-file-lock-cleanup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAW1D,MAAM,UAAU,+BAA+B,GAA8B;IAC5E,OAAO;QACN,WAAW,EAAE,SAAS;QACtB,gBAAgB,EAAE,KAAK;QACvB,YAAY,EAAE,KAAK;QACnB,gBAAgB,EAAE,KAAK;QACvB,aAAa,EAAE,KAAK;KACpB,CAAC;AAAA,CACF;AAED,+EAA+E;AAC/E,MAAM,UAAU,yBAAyB,CAAC,QAAgB,EAAE,UAAqC,EAAQ;IACxG,IAAI,UAAU,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QAC1C,MAAM,WAAW,GAAG,GAAG,QAAQ,YAAY,UAAU,EAAE,EAAE,CAAC;QAC1D,UAAU,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;QAClC,UAAU,CAAC,WAAW,GAAG,WAAW,CAAC;IACtC,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,gBAAgB,EAAE,CAAC;QAClC,kBAAkB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;QACtC,UAAU,CAAC,gBAAgB,GAAG,IAAI,CAAC;IACpC,CAAC;IACD,MAAM,WAAW,GAAG,UAAU,CAAC,WAAW,CAAC;IAC3C,IAAI,CAAC,UAAU,CAAC,YAAY,EAAE,CAAC;QAC9B,UAAU,CAAC,GAAG,WAAW,aAAa,CAAC,CAAC;QACxC,UAAU,CAAC,YAAY,GAAG,IAAI,CAAC;IAChC,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,gBAAgB,EAAE,CAAC;QAClC,SAAS,CAAC,WAAW,CAAC,CAAC;QACvB,UAAU,CAAC,gBAAgB,GAAG,IAAI,CAAC;IACpC,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,aAAa,EAAE,CAAC;QAC/B,kBAAkB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;QACtC,UAAU,CAAC,aAAa,GAAG,IAAI,CAAC;IACjC,CAAC;AAAA,CACD","sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport { renameSync, rmdirSync, unlinkSync } from \"node:fs\";\nimport { dirname } from \"node:path\";\nimport { fsyncDirectorySync } from \"./durable-file-io.ts\";\n\n/** Mutable progress is retained by the owning lock so failed cleanup can be retried. */\nexport interface DurableFileLockRetirement {\n\tretiredPath: string | undefined;\n\tretirementSynced: boolean;\n\townerRemoved: boolean;\n\tdirectoryRemoved: boolean;\n\tcleanupSynced: boolean;\n}\n\nexport function createDurableFileLockRetirement(): DurableFileLockRetirement {\n\treturn {\n\t\tretiredPath: undefined,\n\t\tretirementSynced: false,\n\t\townerRemoved: false,\n\t\tdirectoryRemoved: false,\n\t\tcleanupSynced: false,\n\t};\n}\n\n/** Atomically retire an active lock and durably clean its private artifact. */\nexport function retireDurableFileLockSync(lockPath: string, retirement: DurableFileLockRetirement): void {\n\tif (retirement.retiredPath === undefined) {\n\t\tconst retiredPath = `${lockPath}.release-${randomUUID()}`;\n\t\trenameSync(lockPath, retiredPath);\n\t\tretirement.retiredPath = retiredPath;\n\t}\n\tif (!retirement.retirementSynced) {\n\t\tfsyncDirectorySync(dirname(lockPath));\n\t\tretirement.retirementSynced = true;\n\t}\n\tconst retiredPath = retirement.retiredPath;\n\tif (!retirement.ownerRemoved) {\n\t\tunlinkSync(`${retiredPath}/owner.json`);\n\t\tretirement.ownerRemoved = true;\n\t}\n\tif (!retirement.directoryRemoved) {\n\t\trmdirSync(retiredPath);\n\t\tretirement.directoryRemoved = true;\n\t}\n\tif (!retirement.cleanupSynced) {\n\t\tfsyncDirectorySync(dirname(lockPath));\n\t\tretirement.cleanupSynced = true;\n\t}\n}\n"]}

package/dist/core/durable-file-lock-owner.d.ts

@@ -0,0 +1,18 @@
+export interface DurableFileLockOwner {
+    readonly pid: number;
+    readonly host: string;
+    readonly token: string;
+}
+export interface DurableFileLockOwnerSnapshot {
+    readonly owner: DurableFileLockOwner;
+    readonly dev: string;
+    readonly ino: string;
+}
+export declare class DurableFileLockOwnerError extends Error {
+    readonly name = "DurableFileLockOwnerError";
+}
+export declare function fileErrorCode(error: unknown): string | undefined;
+/** Read one owner while binding its token to both owner-file and lock-directory inodes. */
+export declare function readDurableFileLockOwnerSync(lockPath: string): DurableFileLockOwnerSnapshot;
+export declare function sameDurableFileLockOwner(left: DurableFileLockOwnerSnapshot, right: DurableFileLockOwnerSnapshot): boolean;
+//# sourceMappingURL=durable-file-lock-owner.d.ts.map

package/dist/core/durable-file-lock-owner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-file-lock-owner.d.ts","sourceRoot":"","sources":["../../src/core/durable-file-lock-owner.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,4BAA4B;IAC5C,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;IACrC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,yBAA0B,SAAQ,KAAK;IACnD,SAAkB,IAAI,+BAA+B;CACrD;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAEhE;AA8BD,2FAA2F;AAC3F,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,MAAM,GAAG,4BAA4B,CAqC3F;AAED,wBAAgB,wBAAwB,CACvC,IAAI,EAAE,4BAA4B,EAClC,KAAK,EAAE,4BAA4B,GACjC,OAAO,CAET","sourcesContent":["import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync } from \"node:fs\";\nimport { enforcePrivateFileDescriptorModeSync } from \"./durable-file-mode.ts\";\n\nconst MAX_OWNER_BYTES = 1_024;\nconst MAX_OWNER_TEXT = 512;\n\nexport interface DurableFileLockOwner {\n\treadonly pid: number;\n\treadonly host: string;\n\treadonly token: string;\n}\n\nexport interface DurableFileLockOwnerSnapshot {\n\treadonly owner: DurableFileLockOwner;\n\treadonly dev: string;\n\treadonly ino: string;\n}\n\nexport class DurableFileLockOwnerError extends Error {\n\toverride readonly name = \"DurableFileLockOwnerError\";\n}\n\nexport function fileErrorCode(error: unknown): string | undefined {\n\treturn error instanceof Error && \"code\" in error ? String(Reflect.get(error, \"code\")) : undefined;\n}\n\nfunction parseOwner(input: string): DurableFileLockOwner {\n\tlet value: unknown;\n\ttry {\n\t\tvalue = JSON.parse(input);\n\t} catch (error) {\n\t\tthrow new DurableFileLockOwnerError(\"Durable file lock owner record is malformed\", { cause: error });\n\t}\n\tif (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n\t\tthrow new DurableFileLockOwnerError(\"Durable file lock owner record is invalid\");\n\t}\n\tconst pid = Reflect.get(value, \"pid\");\n\tconst host = Reflect.get(value, \"host\");\n\tconst token = Reflect.get(value, \"token\");\n\tif (\n\t\t!Number.isSafeInteger(pid) ||\n\t\tNumber(pid) <= 0 ||\n\t\ttypeof host !== \"string\" ||\n\t\thost.length === 0 ||\n\t\thost.length > MAX_OWNER_TEXT ||\n\t\ttypeof token !== \"string\" ||\n\t\ttoken.length === 0 ||\n\t\ttoken.length > MAX_OWNER_TEXT\n\t) {\n\t\tthrow new DurableFileLockOwnerError(\"Durable file lock owner record is invalid\");\n\t}\n\treturn Object.freeze({ pid: Number(pid), host, token });\n}\n\n/** Read one owner while binding its token to both owner-file and lock-directory inodes. */\nexport function readDurableFileLockOwnerSync(lockPath: string): DurableFileLockOwnerSnapshot {\n\tconst beforeDirectory = lstatSync(lockPath, { bigint: true });\n\tif (!beforeDirectory.isDirectory() || beforeDirectory.isSymbolicLink()) {\n\t\tthrow new DurableFileLockOwnerError(\"Durable file lock is not a real directory\");\n\t}\n\tconst path = `${lockPath}/owner.json`;\n\tconst fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));\n\ttry {\n\t\tenforcePrivateFileDescriptorModeSync(fd, path);\n\t\tconst beforeOwner = fstatSync(fd, { bigint: true });\n\t\tif (!beforeOwner.isFile() || beforeOwner.size <= 0 || beforeOwner.size > MAX_OWNER_BYTES) {\n\t\t\tthrow new DurableFileLockOwnerError(\"Durable file lock owner record is outside its size bound\");\n\t\t}\n\t\tconst bytes: Buffer = readFileSync(fd);\n\t\tconst afterOwner = fstatSync(fd, { bigint: true });\n\t\tconst currentOwner = lstatSync(path, { bigint: true });\n\t\tconst afterDirectory = lstatSync(lockPath, { bigint: true });\n\t\tif (\n\t\t\tbeforeOwner.dev !== afterOwner.dev ||\n\t\t\tbeforeOwner.ino !== afterOwner.ino ||\n\t\t\tbeforeOwner.size !== afterOwner.size ||\n\t\t\tafterOwner.size !== BigInt(bytes.byteLength) ||\n\t\t\tafterOwner.dev !== currentOwner.dev ||\n\t\t\tafterOwner.ino !== currentOwner.ino ||\n\t\t\tbeforeDirectory.dev !== afterDirectory.dev ||\n\t\t\tbeforeDirectory.ino !== afterDirectory.ino\n\t\t) {\n\t\t\tthrow new DurableFileLockOwnerError(\"Durable file lock owner changed during inspection\");\n\t\t}\n\t\treturn Object.freeze({\n\t\t\towner: parseOwner(bytes.toString(\"utf8\")),\n\t\t\tdev: afterDirectory.dev.toString(),\n\t\t\tino: afterDirectory.ino.toString(),\n\t\t});\n\t} finally {\n\t\tcloseSync(fd);\n\t}\n}\n\nexport function sameDurableFileLockOwner(\n\tleft: DurableFileLockOwnerSnapshot,\n\tright: DurableFileLockOwnerSnapshot,\n): boolean {\n\treturn left.dev === right.dev && left.ino === right.ino && left.owner.token === right.owner.token;\n}\n"]}

package/dist/core/durable-file-lock-owner.js

@@ -0,0 +1,78 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync } from "node:fs";
+import { enforcePrivateFileDescriptorModeSync } from "./durable-file-mode.js";
+const MAX_OWNER_BYTES = 1_024;
+const MAX_OWNER_TEXT = 512;
+export class DurableFileLockOwnerError extends Error {
+    name = "DurableFileLockOwnerError";
+}
+export function fileErrorCode(error) {
+    return error instanceof Error && "code" in error ? String(Reflect.get(error, "code")) : undefined;
+}
+function parseOwner(input) {
+    let value;
+    try {
+        value = JSON.parse(input);
+    }
+    catch (error) {
+        throw new DurableFileLockOwnerError("Durable file lock owner record is malformed", { cause: error });
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new DurableFileLockOwnerError("Durable file lock owner record is invalid");
+    }
+    const pid = Reflect.get(value, "pid");
+    const host = Reflect.get(value, "host");
+    const token = Reflect.get(value, "token");
+    if (!Number.isSafeInteger(pid) ||
+        Number(pid) <= 0 ||
+        typeof host !== "string" ||
+        host.length === 0 ||
+        host.length > MAX_OWNER_TEXT ||
+        typeof token !== "string" ||
+        token.length === 0 ||
+        token.length > MAX_OWNER_TEXT) {
+        throw new DurableFileLockOwnerError("Durable file lock owner record is invalid");
+    }
+    return Object.freeze({ pid: Number(pid), host, token });
+}
+/** Read one owner while binding its token to both owner-file and lock-directory inodes. */
+export function readDurableFileLockOwnerSync(lockPath) {
+    const beforeDirectory = lstatSync(lockPath, { bigint: true });
+    if (!beforeDirectory.isDirectory() || beforeDirectory.isSymbolicLink()) {
+        throw new DurableFileLockOwnerError("Durable file lock is not a real directory");
+    }
+    const path = `${lockPath}/owner.json`;
+    const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        enforcePrivateFileDescriptorModeSync(fd, path);
+        const beforeOwner = fstatSync(fd, { bigint: true });
+        if (!beforeOwner.isFile() || beforeOwner.size <= 0 || beforeOwner.size > MAX_OWNER_BYTES) {
+            throw new DurableFileLockOwnerError("Durable file lock owner record is outside its size bound");
+        }
+        const bytes = readFileSync(fd);
+        const afterOwner = fstatSync(fd, { bigint: true });
+        const currentOwner = lstatSync(path, { bigint: true });
+        const afterDirectory = lstatSync(lockPath, { bigint: true });
+        if (beforeOwner.dev !== afterOwner.dev ||
+            beforeOwner.ino !== afterOwner.ino ||
+            beforeOwner.size !== afterOwner.size ||
+            afterOwner.size !== BigInt(bytes.byteLength) ||
+            afterOwner.dev !== currentOwner.dev ||
+            afterOwner.ino !== currentOwner.ino ||
+            beforeDirectory.dev !== afterDirectory.dev ||
+            beforeDirectory.ino !== afterDirectory.ino) {
+            throw new DurableFileLockOwnerError("Durable file lock owner changed during inspection");
+        }
+        return Object.freeze({
+            owner: parseOwner(bytes.toString("utf8")),
+            dev: afterDirectory.dev.toString(),
+            ino: afterDirectory.ino.toString(),
+        });
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function sameDurableFileLockOwner(left, right) {
+    return left.dev === right.dev && left.ino === right.ino && left.owner.token === right.owner.token;
+}
+//# sourceMappingURL=durable-file-lock-owner.js.map

package/dist/core/durable-file-lock-owner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-file-lock-owner.js","sourceRoot":"","sources":["../../src/core/durable-file-lock-owner.ts"],"names":[],"mappings":"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","sourcesContent":["import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync } from \"node:fs\";\nimport { enforcePrivateFileDescriptorModeSync } from \"./durable-file-mode.ts\";\n\nconst MAX_OWNER_BYTES = 1_024;\nconst MAX_OWNER_TEXT = 512;\n\nexport interface DurableFileLockOwner {\n\treadonly pid: number;\n\treadonly host: string;\n\treadonly token: string;\n}\n\nexport interface DurableFileLockOwnerSnapshot {\n\treadonly owner: DurableFileLockOwner;\n\treadonly dev: string;\n\treadonly ino: string;\n}\n\nexport class DurableFileLockOwnerError extends Error {\n\toverride readonly name = \"DurableFileLockOwnerError\";\n}\n\nexport function fileErrorCode(error: unknown): string | undefined {\n\treturn error instanceof Error && \"code\" in error ? String(Reflect.get(error, \"code\")) : undefined;\n}\n\nfunction parseOwner(input: string): DurableFileLockOwner {\n\tlet value: unknown;\n\ttry {\n\t\tvalue = JSON.parse(input);\n\t} catch (error) {\n\t\tthrow new DurableFileLockOwnerError(\"Durable file lock owner record is malformed\", { cause: error });\n\t}\n\tif (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n\t\tthrow new DurableFileLockOwnerError(\"Durable file lock owner record is invalid\");\n\t}\n\tconst pid = Reflect.get(value, \"pid\");\n\tconst host = Reflect.get(value, \"host\");\n\tconst token = Reflect.get(value, \"token\");\n\tif (\n\t\t!Number.isSafeInteger(pid) ||\n\t\tNumber(pid) <= 0 ||\n\t\ttypeof host !== \"string\" ||\n\t\thost.length === 0 ||\n\t\thost.length > MAX_OWNER_TEXT ||\n\t\ttypeof token !== \"string\" ||\n\t\ttoken.length === 0 ||\n\t\ttoken.length > MAX_OWNER_TEXT\n\t) {\n\t\tthrow new DurableFileLockOwnerError(\"Durable file lock owner record is invalid\");\n\t}\n\treturn Object.freeze({ pid: Number(pid), host, token });\n}\n\n/** Read one owner while binding its token to both owner-file and lock-directory inodes. */\nexport function readDurableFileLockOwnerSync(lockPath: string): DurableFileLockOwnerSnapshot {\n\tconst beforeDirectory = lstatSync(lockPath, { bigint: true });\n\tif (!beforeDirectory.isDirectory() || beforeDirectory.isSymbolicLink()) {\n\t\tthrow new DurableFileLockOwnerError(\"Durable file lock is not a real directory\");\n\t}\n\tconst path = `${lockPath}/owner.json`;\n\tconst fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));\n\ttry {\n\t\tenforcePrivateFileDescriptorModeSync(fd, path);\n\t\tconst beforeOwner = fstatSync(fd, { bigint: true });\n\t\tif (!beforeOwner.isFile() || beforeOwner.size <= 0 || beforeOwner.size > MAX_OWNER_BYTES) {\n\t\t\tthrow new DurableFileLockOwnerError(\"Durable file lock owner record is outside its size bound\");\n\t\t}\n\t\tconst bytes: Buffer = readFileSync(fd);\n\t\tconst afterOwner = fstatSync(fd, { bigint: true });\n\t\tconst currentOwner = lstatSync(path, { bigint: true });\n\t\tconst afterDirectory = lstatSync(lockPath, { bigint: true });\n\t\tif (\n\t\t\tbeforeOwner.dev !== afterOwner.dev ||\n\t\t\tbeforeOwner.ino !== afterOwner.ino ||\n\t\t\tbeforeOwner.size !== afterOwner.size ||\n\t\t\tafterOwner.size !== BigInt(bytes.byteLength) ||\n\t\t\tafterOwner.dev !== currentOwner.dev ||\n\t\t\tafterOwner.ino !== currentOwner.ino ||\n\t\t\tbeforeDirectory.dev !== afterDirectory.dev ||\n\t\t\tbeforeDirectory.ino !== afterDirectory.ino\n\t\t) {\n\t\t\tthrow new DurableFileLockOwnerError(\"Durable file lock owner changed during inspection\");\n\t\t}\n\t\treturn Object.freeze({\n\t\t\towner: parseOwner(bytes.toString(\"utf8\")),\n\t\t\tdev: afterDirectory.dev.toString(),\n\t\t\tino: afterDirectory.ino.toString(),\n\t\t});\n\t} finally {\n\t\tcloseSync(fd);\n\t}\n}\n\nexport function sameDurableFileLockOwner(\n\tleft: DurableFileLockOwnerSnapshot,\n\tright: DurableFileLockOwnerSnapshot,\n): boolean {\n\treturn left.dev === right.dev && left.ino === right.ino && left.owner.token === right.owner.token;\n}\n"]}

package/dist/core/durable-file-lock-storage.d.ts

@@ -0,0 +1,35 @@
+import { type DurableFileLockRetirement } from "./durable-file-lock-cleanup.ts";
+import { type DurableFileLockOwnerSnapshot } from "./durable-file-lock-owner.ts";
+export type DurableFileLockPathObservation = {
+    readonly status: "absent";
+} | {
+    readonly status: "live";
+    readonly pid: number;
+    readonly host: string;
+} | {
+    readonly status: "unknown";
+};
+export interface HeldDurableFileLock {
+    readonly key: string;
+    readonly path: string;
+    readonly token: string;
+    readonly expectedOwner: DurableFileLockOwnerSnapshot;
+    readonly retirement: DurableFileLockRetirement;
+}
+export declare class DurableFileLockBusyError extends Error {
+    readonly name = "DurableFileLockBusyError";
+    constructor();
+}
+export declare class DurableFileLockOwnershipError extends Error {
+    readonly name = "DurableFileLockOwnershipError";
+    constructor();
+}
+export declare function getDurableFileLockRoot(): string;
+export declare function releaseDurableFileLockPathsSync(held: HeldDurableFileLock[], selected: readonly HeldDurableFileLock[]): void;
+export declare function retainRetryableDurableFileLocks(locks: readonly HeldDurableFileLock[]): void;
+export declare function assertDurableFileLockPathsOwnedSync(locks: readonly HeldDurableFileLock[]): void;
+export declare function drainRetryableDurableFileLocksSync(): void;
+export declare function durableFileLockPath(scope: string, key: string): string;
+export declare function acquireDurableFileLockPathSync(key: string, path: string, deadline: number): HeldDurableFileLock;
+export declare function inspectDurableFileLockPathSync(lockPath: string, deadline: number): DurableFileLockPathObservation;
+//# sourceMappingURL=durable-file-lock-storage.d.ts.map

package/dist/core/durable-file-lock-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-file-lock-storage.d.ts","sourceRoot":"","sources":["../../src/core/durable-file-lock-storage.ts"],"names":[],"mappings":"AAKA,OAAO,EAEN,KAAK,yBAAyB,EAE9B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACN,KAAK,4BAA4B,EAIjC,MAAM,8BAA8B,CAAC;AAEtC,MAAM,MAAM,8BAA8B,GACvC;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAA;CAAE,GAC7B;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACxE;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;CAAE,CAAC;AAElC,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,aAAa,EAAE,4BAA4B,CAAC;IACrD,QAAQ,CAAC,UAAU,EAAE,yBAAyB,CAAC;CAC/C;AAED,qBAAa,wBAAyB,SAAQ,KAAK;IAClD,SAAkB,IAAI,8BAA8B;IACpD,cAEC;CACD;AAED,qBAAa,6BAA8B,SAAQ,KAAK;IACvD,SAAkB,IAAI,mCAAmC;IACzD,cAEC;CACD;AASD,wBAAgB,sBAAsB,IAAI,MAAM,CAmB/C;AA8BD,wBAAgB,+BAA+B,CAC9C,IAAI,EAAE,mBAAmB,EAAE,EAC3B,QAAQ,EAAE,SAAS,mBAAmB,EAAE,GACtC,IAAI,CAMN;AAED,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,GAAG,IAAI,CAE3F;AAED,wBAAgB,mCAAmC,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,GAAG,IAAI,CAa/F;AAED,wBAAgB,kCAAkC,IAAI,IAAI,CAEzD;AA2BD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAGtE;AAED,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,mBAAmB,CAkD/G;AA8CD,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,8BAA8B,CAQjH","sourcesContent":["import { createHash, randomUUID } from \"node:crypto\";\nimport { chmodSync, lstatSync, mkdirSync, rmdirSync } from \"node:fs\";\nimport { hostname, tmpdir, userInfo } from \"node:os\";\nimport { dirname, join } from \"node:path\";\nimport { ensureDurableDirectorySync, fsyncDirectorySync, writeExclusiveFileDurablySync } from \"./durable-file-io.ts\";\nimport {\n\tcreateDurableFileLockRetirement,\n\ttype DurableFileLockRetirement,\n\tretireDurableFileLockSync,\n} from \"./durable-file-lock-cleanup.ts\";\nimport {\n\ttype DurableFileLockOwnerSnapshot,\n\tfileErrorCode,\n\treadDurableFileLockOwnerSync,\n\tsameDurableFileLockOwner,\n} from \"./durable-file-lock-owner.ts\";\n\nexport type DurableFileLockPathObservation =\n\t| { readonly status: \"absent\" }\n\t| { readonly status: \"live\"; readonly pid: number; readonly host: string }\n\t| { readonly status: \"unknown\" };\n\nexport interface HeldDurableFileLock {\n\treadonly key: string;\n\treadonly path: string;\n\treadonly token: string;\n\treadonly expectedOwner: DurableFileLockOwnerSnapshot;\n\treadonly retirement: DurableFileLockRetirement;\n}\n\nexport class DurableFileLockBusyError extends Error {\n\toverride readonly name = \"DurableFileLockBusyError\";\n\tconstructor() {\n\t\tsuper(\"Durable file lock is held by another live process\");\n\t}\n}\n\nexport class DurableFileLockOwnershipError extends Error {\n\toverride readonly name = \"DurableFileLockOwnershipError\";\n\tconstructor() {\n\t\tsuper(\"Durable file lock ownership changed before retirement\");\n\t}\n}\n\nconst USER = userInfo();\nconst USER_KEY =\n\tUSER.uid >= 0 ? String(USER.uid) : createHash(\"sha256\").update(USER.username).digest(\"hex\").slice(0, 16);\nconst ROOT = join(tmpdir(), `omk-persistence-${USER_KEY}`);\nconst WAITER = new Int32Array(new SharedArrayBuffer(4));\nconst retryableLocks: HeldDurableFileLock[] = [];\n\nexport function getDurableFileLockRoot(): string {\n\tlet value: ReturnType<typeof lstatSync>;\n\ttry {\n\t\tvalue = lstatSync(ROOT);\n\t} catch (error) {\n\t\tif (fileErrorCode(error) !== \"ENOENT\") throw error;\n\t\tensureDurableDirectorySync(ROOT);\n\t\tvalue = lstatSync(ROOT);\n\t}\n\tif (!value.isDirectory() || value.isSymbolicLink()) throw new Error(\"Persistence lock root is not a real directory\");\n\tif (typeof process.getuid === \"function\" && value.uid !== process.getuid()) {\n\t\tthrow new Error(\"Persistence lock root is not owned by the current user\");\n\t}\n\tif ((value.mode & 0o7777) !== 0o700) {\n\t\tchmodSync(ROOT, 0o700);\n\t\tvalue = lstatSync(ROOT);\n\t\tif ((value.mode & 0o7777) !== 0o700) throw new Error(\"Persistence lock root mode is not private\");\n\t}\n\treturn ROOT;\n}\n\nfunction ownerPath(path: string): string {\n\treturn join(path, \"owner.json\");\n}\n\nfunction processIsLive(pid: number): boolean {\n\ttry {\n\t\tprocess.kill(pid, 0);\n\t\treturn true;\n\t} catch (error) {\n\t\tif (!(error instanceof Error)) throw error;\n\t\treturn fileErrorCode(error) !== \"ESRCH\";\n\t}\n}\n\nfunction removeOwnedLock(lock: HeldDurableFileLock): void {\n\tif (lock.retirement.retiredPath === undefined) {\n\t\tlet current: DurableFileLockOwnerSnapshot;\n\t\ttry {\n\t\t\tcurrent = readDurableFileLockOwnerSync(lock.path);\n\t\t} catch (error) {\n\t\t\tif (fileErrorCode(error) === \"ENOENT\") throw new DurableFileLockOwnershipError();\n\t\t\tthrow error;\n\t\t}\n\t\tif (!sameDurableFileLockOwner(current, lock.expectedOwner)) throw new DurableFileLockOwnershipError();\n\t}\n\tretireDurableFileLockSync(lock.path, lock.retirement);\n}\n\nexport function releaseDurableFileLockPathsSync(\n\theld: HeldDurableFileLock[],\n\tselected: readonly HeldDurableFileLock[],\n): void {\n\tfor (const lock of [...selected].reverse()) {\n\t\tremoveOwnedLock(lock);\n\t\tconst index = held.indexOf(lock);\n\t\tif (index >= 0) held.splice(index, 1);\n\t}\n}\n\nexport function retainRetryableDurableFileLocks(locks: readonly HeldDurableFileLock[]): void {\n\tfor (const lock of locks) if (!retryableLocks.includes(lock)) retryableLocks.push(lock);\n}\n\nexport function assertDurableFileLockPathsOwnedSync(locks: readonly HeldDurableFileLock[]): void {\n\tfor (const lock of locks) {\n\t\tif (retryableLocks.includes(lock) || lock.retirement.retiredPath !== undefined)\n\t\t\tthrow new DurableFileLockOwnershipError();\n\t\tlet current: DurableFileLockOwnerSnapshot;\n\t\ttry {\n\t\t\tcurrent = readDurableFileLockOwnerSync(lock.path);\n\t\t} catch (error) {\n\t\t\tif (fileErrorCode(error) === \"ENOENT\") throw new DurableFileLockOwnershipError();\n\t\t\tthrow error;\n\t\t}\n\t\tif (!sameDurableFileLockOwner(current, lock.expectedOwner)) throw new DurableFileLockOwnershipError();\n\t}\n}\n\nexport function drainRetryableDurableFileLocksSync(): void {\n\treleaseDurableFileLockPathsSync(retryableLocks, retryableLocks);\n}\n\nfunction ownerObservation(lockPath: string): DurableFileLockOwnerSnapshot | DurableFileLockPathObservation {\n\ttry {\n\t\treturn readDurableFileLockOwnerSync(lockPath);\n\t} catch (error) {\n\t\tif (!(error instanceof Error)) throw error;\n\t\tif (fileErrorCode(error) === \"ENOENT\") {\n\t\t\ttry {\n\t\t\t\tlstatSync(lockPath);\n\t\t\t} catch (pathError) {\n\t\t\t\tif (!(pathError instanceof Error)) throw pathError;\n\t\t\t\tif (fileErrorCode(pathError) === \"ENOENT\") return { status: \"absent\" };\n\t\t\t}\n\t\t}\n\t\treturn { status: \"unknown\" };\n\t}\n}\n\nfunction reclaimGatePath(lockPath: string, observed: DurableFileLockOwnerSnapshot): string {\n\tconst ownerKey = createHash(\"sha256\")\n\t\t.update(`${observed.owner.token}\\0${observed.dev}\\0${observed.ino}`)\n\t\t.digest(\"hex\")\n\t\t.slice(0, 24);\n\treturn `${lockPath}.reclaim-${ownerKey}.lock`;\n}\n\nexport function durableFileLockPath(scope: string, key: string): string {\n\tif (!/^[a-z-]+$/u.test(scope)) throw new TypeError(\"Durable file lock scope is invalid\");\n\treturn join(getDurableFileLockRoot(), `${scope}-${key}.lock`);\n}\n\nexport function acquireDurableFileLockPathSync(key: string, path: string, deadline: number): HeldDurableFileLock {\n\twhile (true) {\n\t\tconst token = randomUUID();\n\t\ttry {\n\t\t\tmkdirSync(path, { mode: 0o700 });\n\t\t} catch (error) {\n\t\t\tif (fileErrorCode(error) !== \"EEXIST\") throw error;\n\t\t\tif (inspectDurableFileLockPathSync(path, deadline).status === \"absent\") continue;\n\t\t\tif (Date.now() >= deadline) throw new DurableFileLockBusyError();\n\t\t\tAtomics.wait(WAITER, 0, 0, Math.min(10, deadline - Date.now()));\n\t\t\tcontinue;\n\t\t}\n\t\tconst directory = lstatSync(path, { bigint: true });\n\t\tif (!directory.isDirectory() || directory.isSymbolicLink()) throw new DurableFileLockOwnershipError();\n\t\tconst expectedOwner: DurableFileLockOwnerSnapshot = Object.freeze({\n\t\t\towner: Object.freeze({ pid: process.pid, host: hostname(), token }),\n\t\t\tdev: directory.dev.toString(),\n\t\t\tino: directory.ino.toString(),\n\t\t});\n\t\tconst lock: HeldDurableFileLock = {\n\t\t\tkey,\n\t\t\tpath,\n\t\t\ttoken,\n\t\t\texpectedOwner,\n\t\t\tretirement: createDurableFileLockRetirement(),\n\t\t};\n\t\tlet ownerWritten = false;\n\t\ttry {\n\t\t\tfsyncDirectorySync(dirname(path));\n\t\t\twriteExclusiveFileDurablySync(ownerPath(path), Buffer.from(JSON.stringify(expectedOwner.owner), \"utf8\"));\n\t\t\townerWritten = true;\n\t\t\tassertDurableFileLockPathsOwnedSync([lock]);\n\t\t\treturn lock;\n\t\t} catch (error) {\n\t\t\tlet cleanupError: unknown;\n\t\t\ttry {\n\t\t\t\tif (ownerWritten) releaseDurableFileLockPathsSync([lock], [lock]);\n\t\t\t\telse {\n\t\t\t\t\trmdirSync(path);\n\t\t\t\t\tfsyncDirectorySync(dirname(path));\n\t\t\t\t}\n\t\t\t} catch (failure) {\n\t\t\t\tcleanupError = failure instanceof Error ? failure : new Error(String(failure));\n\t\t\t\tif (ownerWritten && !(cleanupError instanceof DurableFileLockOwnershipError))\n\t\t\t\t\tretainRetryableDurableFileLocks([lock]);\n\t\t\t}\n\t\t\tif (cleanupError) throw new AggregateError([error, cleanupError], \"Durable file lock creation cleanup failed\");\n\t\t\tthrow error;\n\t\t}\n\t}\n}\n\nfunction reclaim(lockPath: string, observed: DurableFileLockOwnerSnapshot, deadline: number): boolean {\n\tconst gate = acquireDurableFileLockPathSync(\n\t\t`reclaim:${observed.owner.token}`,\n\t\treclaimGatePath(lockPath, observed),\n\t\tdeadline,\n\t);\n\tconst stale: HeldDurableFileLock = {\n\t\tkey: `stale:${observed.owner.token}`,\n\t\tpath: lockPath,\n\t\ttoken: observed.owner.token,\n\t\texpectedOwner: observed,\n\t\tretirement: createDurableFileLockRetirement(),\n\t};\n\tlet failure: unknown;\n\tlet retired = false;\n\ttry {\n\t\tconst current = readDurableFileLockOwnerSync(lockPath);\n\t\tif (sameDurableFileLockOwner(current, observed)) {\n\t\t\tremoveOwnedLock(stale);\n\t\t\tretired = true;\n\t\t}\n\t} catch (error) {\n\t\tif (fileErrorCode(error) === \"ENOENT\") {\n\t\t\ttry {\n\t\t\t\tlstatSync(lockPath);\n\t\t\t} catch (pathError) {\n\t\t\t\tif (fileErrorCode(pathError) === \"ENOENT\") retired = true;\n\t\t\t\telse failure = pathError instanceof Error ? pathError : new Error(String(pathError));\n\t\t\t}\n\t\t}\n\t\tif (!retired && failure === undefined) failure = error instanceof Error ? error : new Error(String(error));\n\t\tif (stale.retirement.retiredPath !== undefined) retainRetryableDurableFileLocks([stale]);\n\t}\n\ttry {\n\t\treleaseDurableFileLockPathsSync([gate], [gate]);\n\t} catch (error) {\n\t\tretainRetryableDurableFileLocks([gate]);\n\t\tconst cleanupError = error instanceof Error ? error : new Error(String(error));\n\t\tfailure = failure ? new AggregateError([failure, cleanupError], \"Durable lock reclaim failed\") : cleanupError;\n\t}\n\tif (failure) throw failure;\n\treturn retired;\n}\n\nexport function inspectDurableFileLockPathSync(lockPath: string, deadline: number): DurableFileLockPathObservation {\n\tconst observed = ownerObservation(lockPath);\n\tif (\"status\" in observed) return observed;\n\tif (observed.owner.host !== hostname()) return { status: \"unknown\" };\n\tif (processIsLive(observed.owner.pid)) {\n\t\treturn { status: \"live\", pid: observed.owner.pid, host: observed.owner.host };\n\t}\n\treturn reclaim(lockPath, observed, deadline) ? { status: \"absent\" } : { status: \"unknown\" };\n}\n"]}