@untangle-code/storage-local 0.0.0-stage → 0.1.1

package/dist/local-file-system.js

@@ -0,0 +1,193 @@
+/**
+ * `FileSystemPort` adapter backed by `node:fs/promises`, scoped to one or
+ * more workspace/state roots (architecture.md §2.1, §23.1; docs/BUILD_PLAN.md
+ * WP-12 acceptance: "Pfad-Sandbox, Symlink-Prüfung").
+ *
+ * Every method resolves its path through `assertWithinWorkspace` (domain)
+ * BEFORE touching the filesystem — a lexical check that rejects `../` escapes
+ * regardless of whether the path exists yet (needed for `writeFile`/`mkdir`
+ * of not-yet-existing paths). Where the path (or its parent, for a
+ * not-yet-existing leaf) already exists on disk, the adapter additionally
+ * resolves the real, symlink-free path and re-asserts against it — the
+ * "adapters are responsible for the symlink-aware part of the sandbox"
+ * contract from `ports.ts`'s `FileSystemPort` doc comment. See README
+ * "Entscheidungen" for the precise guarantee and its documented limits.
+ */
+import * as nodeFs from "node:fs/promises";
+import * as nodePath from "node:path";
+import { assertWithinWorkspace, UntangleError } from "@untangle-code/domain";
+import { assertNotAborted } from "./abort.js";
+import { isNotFoundError } from "./fs-errors.js";
+/**
+ * Resolves `candidate` as far as the real filesystem allows: walks up to the
+ * nearest EXISTING ancestor, `realpath`s that ancestor, then re-appends the
+ * not-yet-existing suffix segments lexically. This is what makes the
+ * symlink guard correct even for paths that do not exist yet (a `writeFile`
+ * target, a directory `mkdir` is about to create) AND for roots that
+ * themselves contain an unresolved symlink segment (e.g. macOS'
+ * `/var` → `/private/var`) — comparing an already-realpath-resolved
+ * candidate against a NOT-resolved root would otherwise falsely report
+ * every path under that root as an escape (the same class of bug
+ * `@untangle-code/scanner`'s README "Entscheidungen" #7 documents and fixes
+ * for its own, narrower realpath use). Returns `candidate` unchanged if NO
+ * ancestor exists at all (e.g. the whole tree is hypothetical).
+ */
+async function resolveAsFarAsPossible(candidate) {
+    const pendingSuffix = [];
+    let probe = candidate;
+    for (;;) {
+        try {
+            const real = await nodeFs.realpath(probe);
+            return pendingSuffix.length === 0 ? real : nodePath.join(real, ...pendingSuffix.reverse());
+        }
+        catch (error) {
+            if (!isNotFoundError(error)) {
+                throw error;
+            }
+            const parent = nodePath.dirname(probe);
+            if (parent === probe) {
+                // Reached the filesystem root without finding an existing ancestor.
+                return candidate;
+            }
+            pendingSuffix.push(nodePath.basename(probe));
+            probe = parent;
+        }
+    }
+}
+function kindOf(stats) {
+    if (stats.isSymbolicLink()) {
+        return "symlink";
+    }
+    if (stats.isDirectory()) {
+        return "directory";
+    }
+    if (stats.isFile()) {
+        return "file";
+    }
+    return "other";
+}
+function toFileStat(path, stats) {
+    return {
+        path,
+        sizeBytes: stats.size,
+        mtimeEpochMs: Math.trunc(stats.mtimeMs),
+        kind: kindOf(stats),
+    };
+}
+/**
+ * Node-backed, path-sandboxed `FileSystemPort`. Construct one per set of
+ * roots that should be reachable (typically just the `.untangle` state
+ * directory for this package's own callers).
+ */
+export class LocalFileSystem {
+    roots;
+    constructor(roots) {
+        if (roots.length === 0) {
+            throw new UntangleError("PATH_OUTSIDE_WORKSPACE", "LocalFileSystem needs at least one root", {
+                operation: "local_file_system_init",
+            });
+        }
+        this.roots = roots;
+    }
+    /**
+     * Lexical sandbox check (throws `PATH_OUTSIDE_WORKSPACE` on escape), plus a
+     * real-path re-check via {@link resolveAsFarAsPossible} on BOTH the
+     * candidate and the configured roots — needed on both sides: the candidate
+     * may not exist yet (`writeFile`/`mkdir` of a new entry) and a root itself
+     * may contain an unresolved symlink segment (e.g. macOS'
+     * `/var` → `/private/var`) that would otherwise make every path under it
+     * look like an escape. Recomputed per call rather than cached, since which
+     * prefix of a root already exists changes over the adapter's lifetime
+     * (the root itself usually does not exist yet on first use).
+     */
+    async guard(candidatePath) {
+        const lexical = assertWithinWorkspace(candidatePath, this.roots);
+        const resolvedCandidate = await resolveAsFarAsPossible(lexical);
+        const resolvedRoots = await Promise.all(this.roots.map(resolveAsFarAsPossible));
+        assertWithinWorkspace(resolvedCandidate, resolvedRoots);
+        return lexical;
+    }
+    async stat(path, options) {
+        assertNotAborted(options, "stat");
+        const resolved = await this.guard(path);
+        try {
+            const stats = await nodeFs.stat(resolved);
+            return toFileStat(path, stats);
+        }
+        catch (error) {
+            if (isNotFoundError(error)) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    async lstat(path, options) {
+        assertNotAborted(options, "lstat");
+        const resolved = await this.guard(path);
+        try {
+            const stats = await nodeFs.lstat(resolved);
+            return toFileStat(path, stats);
+        }
+        catch (error) {
+            if (isNotFoundError(error)) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    async readFile(path, options) {
+        assertNotAborted(options, "read_file");
+        const resolved = await this.guard(path);
+        const buffer = await nodeFs.readFile(resolved, { signal: options?.signal });
+        return new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+    }
+    async readTextFile(path, options) {
+        assertNotAborted(options, "read_text_file");
+        const resolved = await this.guard(path);
+        return await nodeFs.readFile(resolved, { encoding: "utf8", signal: options?.signal });
+    }
+    async readDir(path, options) {
+        assertNotAborted(options, "read_dir");
+        const resolved = await this.guard(path);
+        const entries = await nodeFs.readdir(resolved, { withFileTypes: true });
+        return entries.map((entry) => {
+            const kind = entry.isSymbolicLink()
+                ? "symlink"
+                : entry.isDirectory()
+                    ? "directory"
+                    : entry.isFile()
+                        ? "file"
+                        : "other";
+            return { name: entry.name, path: nodePath.join(path, entry.name), kind };
+        });
+    }
+    async realPath(path, options) {
+        assertNotAborted(options, "real_path");
+        const lexical = assertWithinWorkspace(path, this.roots);
+        const real = await nodeFs.realpath(lexical);
+        const resolvedRoots = await Promise.all(this.roots.map(resolveAsFarAsPossible));
+        return assertWithinWorkspace(real, resolvedRoots);
+    }
+    async writeFile(path, data, options) {
+        assertNotAborted(options, "write_file");
+        const resolved = await this.guard(path);
+        await nodeFs.writeFile(resolved, data, { signal: options?.signal, mode: options?.mode });
+    }
+    async mkdir(path, options) {
+        assertNotAborted(options, "mkdir");
+        const resolved = await this.guard(path);
+        await nodeFs.mkdir(resolved, { recursive: options?.recursive ?? false });
+    }
+    async rename(from, to, options) {
+        assertNotAborted(options, "rename");
+        const resolvedFrom = await this.guard(from);
+        const resolvedTo = await this.guard(to);
+        await nodeFs.rename(resolvedFrom, resolvedTo);
+    }
+    async remove(path, options) {
+        assertNotAborted(options, "remove");
+        const resolved = await this.guard(path);
+        await nodeFs.rm(resolved, { recursive: options?.recursive ?? false, force: true });
+    }
+}
+//# sourceMappingURL=local-file-system.js.map

package/dist/local-file-system.js.map

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

package/dist/lock-provider.d.ts

@@ -0,0 +1,59 @@
+import type { Clock, FileSystemPort, LockHandle, LockProvider, LockRecordV1, PortCallOptions, Random } from "@untangle-code/domain";
+/** File-based `LockProvider` rooted at one `locks/` directory. */
+export declare class FileLockProvider implements LockProvider {
+    private readonly fs;
+    private readonly locksDir;
+    private readonly clock;
+    private readonly random;
+    private readonly host;
+    /** Set once `locksDir` is known to exist, to skip a redundant `mkdir` on
+     * every `tryAcquire()` call — real disk I/O is not free, and the lease
+     * contract tests run with tight (double-digit millisecond) timing
+     * margins that a spurious extra round trip can eat into. */
+    private locksDirEnsured;
+    private readonly corruptGraceMs;
+    constructor(fs: FileSystemPort, locksDir: string, clock: Clock, random: Random, host?: string, 
+    /** Overrides `DEFAULT_CORRUPT_GRACE_MS` — exposed mainly so tests can
+     * exercise the grace-period boundary without a real multi-minute wait. */
+    corruptGraceMs?: number);
+    private lockDirFor;
+    private recordPathFor;
+    private isExpired;
+    private buildRecord;
+    /**
+     * Reads the current state of a lock directory:
+     * - `"absent"` — the directory (or its `record.json`) does not exist yet,
+     *   INCLUDING the tiny window where a concurrent winner's `mkdir` has
+     *   landed but its `record.json` write has not — that window is treated as
+     *   "busy", never as stale, so it can never be mistaken for a takeover
+     *   opportunity (that would break exclusivity for the very case the
+     *   directory-mkdir primitive exists to make airtight);
+     * - `"corrupt"` — `record.json` exists but does not parse. Because every
+     *   write goes through temp-file-then-rename (see the file doc comment),
+     *   this can no longer be an in-flight write caught mid-write — it is a
+     *   genuine anomaly. The caller still has to check `mtimeEpochMs` against
+     *   the corruption grace period before treating it as takeover-eligible
+     *   (see `DEFAULT_CORRUPT_GRACE_MS`) — corrupt is NOT auto-stale;
+     * - `"valid"` — a well-formed record, which the caller still has to check
+     *   for lease expiry itself.
+     */
+    private readRecordState;
+    private isCorruptGraceElapsed;
+    /**
+     * Writes `record.json` atomically — temp file, then a single `rename` onto
+     * the live path — mirroring `checkpoint-store.ts`'s `writeAtomic` in this
+     * same package. Used by both the initial `tryAcquire()` write and every
+     * `renew()`, so a reader can never observe a half-written record (WP-80).
+     */
+    private writeRecordAtomic;
+    private makeHandle;
+    tryAcquire(key: string, options?: PortCallOptions & {
+        leaseMs?: number;
+    }): Promise<LockHandle | null>;
+    acquire(key: string, options?: PortCallOptions & {
+        leaseMs?: number;
+        waitMs?: number;
+    }): Promise<LockHandle>;
+    inspect(key: string, options?: PortCallOptions): Promise<LockRecordV1 | null>;
+}
+//# sourceMappingURL=lock-provider.d.ts.map

package/dist/lock-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock-provider.d.ts","sourceRoot":"","sources":["../src/lock-provider.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EACV,KAAK,EACL,cAAc,EACd,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,MAAM,EACP,MAAM,uBAAuB,CAAC;AA6E/B,kEAAkE;AAClE,qBAAa,gBAAiB,YAAW,YAAY;IAUjD,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAZzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B;;;gEAG4D;IAC5D,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;gBAGrB,EAAE,EAAE,cAAc,EAClB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,MAAM,EAC/B,IAAI,CAAC,EAAE,MAAM;IACb;8EAC0E;IAC1E,cAAc,CAAC,EAAE,MAAM;IAMzB,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,WAAW;IAanB;;;;;;;;;;;;;;;;OAgBG;YACW,eAAe;IA2B7B,OAAO,CAAC,qBAAqB;IAI7B;;;;;OAKG;YACW,iBAAiB;IAW/B,OAAO,CAAC,UAAU;IAuCL,UAAU,CACrB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,eAAe,GAAG;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAC/C,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAkEhB,OAAO,CAClB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,eAAe,GAAG;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAChE,OAAO,CAAC,UAAU,CAAC;IA0BT,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;CAQ3F"}

package/dist/lock-provider.js

@@ -0,0 +1,318 @@
+/**
+ * File-based `LockProvider` (architecture.md §21.1–§21.2; docs/BUILD_PLAN.md
+ * WP-12 acceptance criteria).
+ *
+ * One lock = one directory named `sha256(key)` under the configured locks
+ * root, containing a single `record.json`. `FileSystemPort.mkdir` without
+ * `recursive` is the exclusivity primitive: Node's `mkdir` atomically fails
+ * with `EEXIST` when the directory already exists, so "did I just create the
+ * directory" is a genuine, OS-atomic exclusive-acquire test — no separate
+ * locking mechanism is layered on top of it.
+ *
+ * Stale-lease takeover (an expired holder's lock being stolen) is NOT fully
+ * race-free across processes with plain directory operations — see README
+ * "Entscheidungen" for the exact, documented race window and why it is an
+ * acceptable MVP tradeoff (architecture.md §21.2 explicitly scopes file
+ * locks to MVP; "Remote Team Mode" gets a real distributed lease). What IS
+ * fully race-free, because it needs no takeover step at all, is contention
+ * over a lock nobody holds yet — the common case, and the one this file's
+ * own "two providers race for the same lock" test exercises.
+ *
+ * `record.json` itself is written temp-file-then-rename (mirroring
+ * `checkpoint-store.ts`'s "every write is temp-file-then-rename" in this
+ * same package) — never by a direct `writeFile` onto the live path. A
+ * reader can therefore never observe a half-written record: the file on
+ * disk is always either the previous good record or the fully-formed new
+ * one, whether the write is happening on the initial `tryAcquire()` or on
+ * `renew()`. Before this, a reader racing a writer could see a torn record,
+ * fail to parse it, and — because "corrupt" was treated as immediately
+ * takeover-eligible — steal a lock that was still validly held (WP-80).
+ * See `DEFAULT_CORRUPT_GRACE_MS`'s doc comment and README "Entscheidungen"
+ * for how a *genuinely* corrupt record (external tampering, disk fault —
+ * atomic rename rules out "caught mid-write") is now handled instead.
+ */
+import * as os from "node:os";
+import * as nodePath from "node:path";
+import { sha256Hex, UntangleError } from "@untangle-code/domain";
+import { assertNotAborted } from "./abort.js";
+import { isAlreadyExistsError, isNotFoundError } from "./fs-errors.js";
+import { realNowEpochMs } from "./real-time.js";
+const DEFAULT_LEASE_MS = 30_000;
+const POLL_INTERVAL_MS = 20;
+const RECORD_FILE_NAME = "record.json";
+/** Bounds the stale-takeover retry loop so pathological contention returns
+ * "held" rather than spinning forever. */
+const MAX_TAKEOVER_ATTEMPTS = 16;
+/**
+ * How long a `record.json` that fails to parse must sit untouched (by
+ * mtime) before this provider will treat it as takeover-eligible.
+ *
+ * Every `record.json` write is now temp-file-then-rename (see the file doc
+ * comment), so a reader can no longer see a half-written record — the file
+ * on disk is always either the previous good record or the new one, never
+ * a torn mix of both. That removes the one legitimate reason the old code
+ * had for treating "corrupt" as an automatic, immediate takeover signal.
+ * What remains, once "caught mid-write" is off the table, is a genuinely
+ * unparsable file: a manual edit, a disk fault, a record written by some
+ * future/incompatible format. That is an error condition, not a routine
+ * lifecycle state — and unlike an expired lease (which carries its own
+ * trustworthy `leaseExpiresAt`), a corrupt record carries no information at
+ * all about how long ago it stopped being valid. Immediately stealing it
+ * would repeat exactly the WP-80 mistake (treating "I can't explain this" as
+ * "safe to take"), just with a different root cause.
+ *
+ * The chosen policy (documented in README "Entscheidungen"): require a
+ * conservative grace period — much longer than any expected lease or write
+ * latency — to pass since the file's own last-modified time before a corrupt
+ * record becomes takeover-eligible, exactly like an expired lease. Until
+ * then `tryAcquire()` treats it like a held lock (returns `null`), never
+ * throwing and never stealing. This self-heals without an operator having
+ * to intervene, while giving any in-flight (however slow) legitimate write
+ * — or a human investigating — a wide window to land or act first.
+ */
+const DEFAULT_CORRUPT_GRACE_MS = 5 * 60_000;
+function encode(text) {
+    return new TextEncoder().encode(text);
+}
+function toPublicRecord(record) {
+    return {
+        key: record.key,
+        pid: record.pid,
+        processInstanceId: record.processInstanceId,
+        host: record.host,
+        acquiredAt: record.acquiredAt,
+        leaseExpiresAt: record.leaseExpiresAt,
+    };
+}
+/** File-based `LockProvider` rooted at one `locks/` directory. */
+export class FileLockProvider {
+    fs;
+    locksDir;
+    clock;
+    random;
+    host;
+    /** Set once `locksDir` is known to exist, to skip a redundant `mkdir` on
+     * every `tryAcquire()` call — real disk I/O is not free, and the lease
+     * contract tests run with tight (double-digit millisecond) timing
+     * margins that a spurious extra round trip can eat into. */
+    locksDirEnsured = false;
+    corruptGraceMs;
+    constructor(fs, locksDir, clock, random, host, 
+    /** Overrides `DEFAULT_CORRUPT_GRACE_MS` — exposed mainly so tests can
+     * exercise the grace-period boundary without a real multi-minute wait. */
+    corruptGraceMs) {
+        this.fs = fs;
+        this.locksDir = locksDir;
+        this.clock = clock;
+        this.random = random;
+        this.host = host ?? os.hostname();
+        this.corruptGraceMs = corruptGraceMs ?? DEFAULT_CORRUPT_GRACE_MS;
+    }
+    lockDirFor(key) {
+        return nodePath.join(this.locksDir, sha256Hex(key));
+    }
+    recordPathFor(lockDir) {
+        return nodePath.join(lockDir, RECORD_FILE_NAME);
+    }
+    isExpired(record, nowEpochMs) {
+        return Date.parse(record.leaseExpiresAt) <= nowEpochMs;
+    }
+    buildRecord(key, leaseMs) {
+        const nowMs = this.clock.nowEpochMs();
+        return {
+            key,
+            pid: process.pid,
+            processInstanceId: this.random.uuid(),
+            host: this.host,
+            acquiredAt: this.clock.nowIso(),
+            leaseExpiresAt: new Date(nowMs + leaseMs).toISOString(),
+            processStartedAtEpochMs: Math.round(nowMs - process.uptime() * 1000),
+        };
+    }
+    /**
+     * Reads the current state of a lock directory:
+     * - `"absent"` — the directory (or its `record.json`) does not exist yet,
+     *   INCLUDING the tiny window where a concurrent winner's `mkdir` has
+     *   landed but its `record.json` write has not — that window is treated as
+     *   "busy", never as stale, so it can never be mistaken for a takeover
+     *   opportunity (that would break exclusivity for the very case the
+     *   directory-mkdir primitive exists to make airtight);
+     * - `"corrupt"` — `record.json` exists but does not parse. Because every
+     *   write goes through temp-file-then-rename (see the file doc comment),
+     *   this can no longer be an in-flight write caught mid-write — it is a
+     *   genuine anomaly. The caller still has to check `mtimeEpochMs` against
+     *   the corruption grace period before treating it as takeover-eligible
+     *   (see `DEFAULT_CORRUPT_GRACE_MS`) — corrupt is NOT auto-stale;
+     * - `"valid"` — a well-formed record, which the caller still has to check
+     *   for lease expiry itself.
+     */
+    async readRecordState(lockDir, options) {
+        const recordPath = this.recordPathFor(lockDir);
+        let text;
+        try {
+            text = await this.fs.readTextFile(recordPath, options);
+        }
+        catch (error) {
+            if (isNotFoundError(error)) {
+                return { kind: "absent" };
+            }
+            throw error;
+        }
+        try {
+            return { kind: "valid", record: JSON.parse(text) };
+        }
+        catch {
+            // `record.json` exists (the readTextFile above succeeded) but does not
+            // parse — stat it for the corruption-grace-period check. A `null`
+            // stat here means a concurrent takeover removed it between our read
+            // and this stat; fall back to "now" so that race resolves toward
+            // "not yet eligible" rather than throwing on a missing file.
+            const stat = await this.fs.stat(recordPath, options);
+            return { kind: "corrupt", mtimeEpochMs: stat?.mtimeEpochMs ?? this.clock.nowEpochMs() };
+        }
+    }
+    isCorruptGraceElapsed(mtimeEpochMs, nowEpochMs) {
+        return nowEpochMs - mtimeEpochMs >= this.corruptGraceMs;
+    }
+    /**
+     * Writes `record.json` atomically — temp file, then a single `rename` onto
+     * the live path — mirroring `checkpoint-store.ts`'s `writeAtomic` in this
+     * same package. Used by both the initial `tryAcquire()` write and every
+     * `renew()`, so a reader can never observe a half-written record (WP-80).
+     */
+    async writeRecordAtomic(lockDir, record, options) {
+        const finalPath = this.recordPathFor(lockDir);
+        const tempPath = `${finalPath}.${this.random.uuid()}.tmp`;
+        await this.fs.writeFile(tempPath, encode(JSON.stringify(record)), options);
+        await this.fs.rename(tempPath, finalPath, options);
+    }
+    makeHandle(lockDir, record, leaseMs) {
+        let current = record;
+        return {
+            get key() {
+                return current.key;
+            },
+            get record() {
+                return toPublicRecord(current);
+            },
+            renew: async (options) => {
+                assertNotAborted(options, "lock_renew");
+                const state = await this.readRecordState(lockDir, options);
+                if (state.kind !== "valid" ||
+                    state.record.processInstanceId !== current.processInstanceId) {
+                    throw new UntangleError("LOCK_HELD", `Lock "${current.key}" was lost before renew`, {
+                        operation: "lock_renew",
+                        context: { key: current.key },
+                    });
+                }
+                const renewed = this.buildRecord(current.key, leaseMs);
+                await this.writeRecordAtomic(lockDir, renewed, options);
+                current = renewed;
+            },
+            release: async () => {
+                const state = await this.readRecordState(lockDir);
+                if (state.kind === "valid" &&
+                    state.record.processInstanceId === current.processInstanceId) {
+                    await this.fs.remove(lockDir, { recursive: true });
+                }
+                // Otherwise: this handle already lost the lock to another holder —
+                // a safe no-op, never removing the new holder's directory.
+            },
+        };
+    }
+    async tryAcquire(key, options) {
+        assertNotAborted(options, "lock_try_acquire");
+        const leaseMs = options?.leaseMs ?? DEFAULT_LEASE_MS;
+        const lockDir = this.lockDirFor(key);
+        const mkdirOptions = options?.signal ? { signal: options.signal } : undefined;
+        // Lets this provider be used before any explicit `ensureStateDirLayout()`
+        // call (e.g. in a focused unit test) — but only paid once per instance
+        // (see `locksDirEnsured`'s doc comment).
+        if (!this.locksDirEnsured) {
+            await this.fs.mkdir(this.locksDir, { recursive: true, ...mkdirOptions });
+            this.locksDirEnsured = true;
+        }
+        for (let attempt = 0; attempt < MAX_TAKEOVER_ATTEMPTS; attempt += 1) {
+            assertNotAborted(options, "lock_try_acquire");
+            try {
+                await this.fs.mkdir(lockDir, mkdirOptions);
+            }
+            catch (error) {
+                if (!isAlreadyExistsError(error)) {
+                    throw error;
+                }
+                const state = await this.readRecordState(lockDir, options);
+                if (state.kind === "absent") {
+                    // Someone else's mkdir landed but their record.json has not yet —
+                    // busy, not stale. Report "held" rather than racing to remove a
+                    // directory that is mid-creation by its legitimate owner.
+                    return null;
+                }
+                if (state.kind === "valid" && !this.isExpired(state.record, this.clock.nowEpochMs())) {
+                    return null; // genuinely held
+                }
+                if (state.kind === "corrupt" &&
+                    !this.isCorruptGraceElapsed(state.mtimeEpochMs, this.clock.nowEpochMs())) {
+                    // Unparsable, but too recently modified to trust as abandoned —
+                    // could still be a legitimate (if unusually slow) in-flight write,
+                    // or fresh external damage nobody has had a chance to react to
+                    // yet. Treat exactly like "genuinely held": never steal it before
+                    // the corruption grace period elapses (see
+                    // `DEFAULT_CORRUPT_GRACE_MS`; this is the WP-80 fix).
+                    return null;
+                }
+                // Either a really-expired lease, or a record.json that has stayed
+                // unparsable for longer than the corruption grace period: attempt
+                // takeover by removing the stale directory, then race for mkdir
+                // again from the top of the loop.
+                try {
+                    await this.fs.remove(lockDir, { recursive: true, ...mkdirOptions });
+                }
+                catch (removeError) {
+                    if (!isNotFoundError(removeError)) {
+                        throw removeError;
+                    }
+                    // Someone else already removed it — loop back and race for mkdir.
+                }
+                continue;
+            }
+            // Our mkdir won: we are the exclusive owner of a brand-new directory.
+            const record = this.buildRecord(key, leaseMs);
+            await this.writeRecordAtomic(lockDir, record, options);
+            return this.makeHandle(lockDir, record, leaseMs);
+        }
+        return null;
+    }
+    async acquire(key, options) {
+        const waitMs = options?.waitMs ?? 0;
+        // Bounded by REAL elapsed time, not the injected `Clock` — see
+        // `real-time.ts` for why (mirrors `InMemoryLockProvider`'s identical
+        // reasoning in `@untangle-code/testkit`).
+        const startedAtRealMs = realNowEpochMs();
+        for (;;) {
+            const handle = await this.tryAcquire(key, options);
+            if (handle) {
+                return handle;
+            }
+            const elapsedRealMs = realNowEpochMs() - startedAtRealMs;
+            if (elapsedRealMs >= waitMs) {
+                throw new UntangleError("LOCK_HELD", `Lock "${key}" is held`, {
+                    operation: "lock_acquire",
+                    retryable: true,
+                    context: { key },
+                });
+            }
+            assertNotAborted(options, "lock_acquire");
+            await new Promise((resolve) => setTimeout(resolve, Math.min(POLL_INTERVAL_MS, waitMs - elapsedRealMs)));
+        }
+    }
+    async inspect(key, options) {
+        assertNotAborted(options, "lock_inspect");
+        const state = await this.readRecordState(this.lockDirFor(key), options);
+        if (state.kind !== "valid" || this.isExpired(state.record, this.clock.nowEpochMs())) {
+            return null;
+        }
+        return toPublicRecord(state.record);
+    }
+}
+//# sourceMappingURL=lock-provider.js.map

package/dist/lock-provider.js.map

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

package/dist/real-time.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The single, isolated real-wall-clock read in this package, used ONLY to
+ * bound `FileLockProvider.acquire()`'s retry-polling loop — a real file lock
+ * has no injectable `Clock` for "how long have we actually been waiting",
+ * since that loop sleeps via real `setTimeout` regardless of what the
+ * injected `Clock` reports (see `lock-provider.ts` for the full reasoning;
+ * this mirrors `@untangle-code/testkit`'s own `SystemClock`, which exists for
+ * exactly the same reason and carries the same isolation comment).
+ *
+ * Lease/record timestamps themselves (`acquiredAt`, `leaseExpiresAt`, cache
+ * and checkpoint `savedAt`/access times) always go through the injected
+ * `Clock` port, never this function — this is deliberately the ONE place in
+ * the package's non-test code that reads real time directly.
+ */
+export declare function realNowEpochMs(): number;
+//# sourceMappingURL=real-time.d.ts.map

package/dist/real-time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"real-time.d.ts","sourceRoot":"","sources":["../src/real-time.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAGvC"}

package/dist/real-time.js

@@ -0,0 +1,19 @@
+/**
+ * The single, isolated real-wall-clock read in this package, used ONLY to
+ * bound `FileLockProvider.acquire()`'s retry-polling loop — a real file lock
+ * has no injectable `Clock` for "how long have we actually been waiting",
+ * since that loop sleeps via real `setTimeout` regardless of what the
+ * injected `Clock` reports (see `lock-provider.ts` for the full reasoning;
+ * this mirrors `@untangle-code/testkit`'s own `SystemClock`, which exists for
+ * exactly the same reason and carries the same isolation comment).
+ *
+ * Lease/record timestamps themselves (`acquiredAt`, `leaseExpiresAt`, cache
+ * and checkpoint `savedAt`/access times) always go through the injected
+ * `Clock` port, never this function — this is deliberately the ONE place in
+ * the package's non-test code that reads real time directly.
+ */
+export function realNowEpochMs() {
+    // eslint-disable-next-line no-restricted-syntax -- see file doc comment above.
+    return Date.now();
+}
+//# sourceMappingURL=real-time.js.map

package/dist/real-time.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"real-time.js","sourceRoot":"","sources":["../src/real-time.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,cAAc;IAC5B,+EAA+E;IAC/E,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC;AACpB,CAAC"}