@superbee/core 0.1.0

package/dist/filesystem-identity.js

@@ -0,0 +1,675 @@
+/**
+ * Exact filesystem identity for the filesystem adapter.
+ *
+ * A bundle-relative path `rel` names ONE physical entry only when every segment's on-disk
+ * spelling equals the requested spelling. On a case- or normalization-insensitive filesystem
+ * (case-insensitive APFS, NTFS, ext4 casefold, normalization-insensitive APFS) two distinct
+ * canonical ids would otherwise reach one file, so reads, compare-and-swap, and deletes would
+ * alias. This module is the single owner of that decision:
+ *
+ * - Observations record every `rel` segment's inode, verify each segment's spelling by listing
+ *   before and after use, confirm any would-be alias by probing the requested spelling against
+ *   the recorded inode, and hold the read handle open through the post-walk so the bytes stay
+ *   bound to a live inode. They hold no lock and write nothing, so an absent bundle root stays
+ *   absent. A symbolic link observed by any probe is refused; a link swapped in and out
+ *   entirely between two probes of one observation can be traversed by the operating system
+ *   during a listing or open, but its bytes can never be returned as EXACT, because the leaf
+ *   witness at the post-walk must match the entry the requested path reaches.
+ * - Mutations hold one cross-process lock keyed by a pure fold of the root and `rel`, decide
+ *   inside it, create directories one segment at a time with a spelling check, and publish a
+ *   first-created leaf with `link` so the host's own equivalence refuses a second spelling the
+ *   fold did not equate; a first-creation race cannot succeed with the wrong spelling and cannot
+ *   silently replace the winner.
+ *
+ * An observation's linearization point is the post-walk that validated the bytes: what it returns
+ * is a state of THIS identity at that instant, never a foreign one and never bytes straddling two
+ * states. A read concurrent with a legitimate same-spelling replacement may therefore return the
+ * old value or the new one, both real; a caller that needs one state across several reads uses
+ * versions and compare-and-swap, as mutations already do. Sustained interference is bounded
+ * rather than resolved: after MAX_RESTARTS the observation refuses with
+ * {@link ConcurrentReplacementError} instead of attributing bytes to a state it cannot name.
+ * This rests on published bytes being immutable per inode — every write publishes a complete temp
+ * file with `link` or `rename` and never edits a live one — since the bytes are read BEFORE the
+ * post-walk. A non-core writer editing a published file in place is the case it excludes.
+ *
+ * Exactness applies to `rel` segments only. The bundle root is the declared storage context:
+ * a root (tail) segment that already exists as a directory under any spelling is accepted,
+ * and the root's spelling is folded into the lock key rather than verified.
+ *
+ * Every filesystem call goes through a {@link FilesystemIdentityPort} passed to the protocol
+ * functions. Production binds {@link nodeFilesystemIdentityPort} once, as a module constant;
+ * nothing on a backend instance can substitute it. Normalizing stores that rewrite names on
+ * write (legacy HFS+) are unsupported: an id whose NFD form differs from its own form is written
+ * and then refused as an alias on every later observation, never silently aliased.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { ConcurrentReplacementError, FilesystemIdentityAliasError, InvalidInputError } from "./errors.js";
+import { acquireFilesystemIdentityLock } from "./filesystem-lock.js";
+const WINDOWS_REPLACE_CONFLICT_CODES = new Set(["EACCES", "EBUSY", "EPERM"]);
+/**
+ * Windows can transiently deny replacement while another process is closing a read handle or a
+ * scanner holds the destination. An in-place rename retry cannot remain bound to the complete
+ * parent-and-leaf observation: either can change after any final check. Abort this attempt instead,
+ * mapping only the errno values Node uses for a Windows replacement sharing violation to the typed
+ * contention signal owned by the higher-level fresh read/decide/CAS loop. Every other platform and
+ * errno remains the original immediate failure.
+ */
+async function replaceExistingLeaf(port, tmp, target, rel) {
+    try {
+        await port.rename(tmp, target);
+    }
+    catch (err) {
+        const code = err.code ?? "";
+        if ((port.platform ?? process.platform) === "win32" && WINDOWS_REPLACE_CONFLICT_CODES.has(code)) {
+            throw new ConcurrentReplacementError(rel, 1, 10);
+        }
+        throw err;
+    }
+}
+/**
+ * A symbolic link at a `rel` segment. The walk never follows links: a link's own inode is not the
+ * inode of what opening it would reach, so no exactness verdict is possible. Refused as caller
+ * input (the layout is unsupported) rather than reported as a runtime failure.
+ */
+export class FilesystemSymlinkEntryError extends InvalidInputError {
+    rel;
+    segment;
+    constructor(rel, segment) {
+        super(`Path '${rel}' reaches a symbolic link at segment '${segment}'; symlinked entries inside a bundle are unsupported.`);
+        this.name = "FilesystemSymlinkEntryError";
+        this.rel = rel;
+        this.segment = segment;
+    }
+}
+/**
+ * A regular file where a directory is needed (or the reverse) at an exactly spelled segment.
+ * A runtime state of the bundle, not a caller-input error, so it is not an `InvalidInputError`.
+ */
+export class FilesystemShapeMismatchError extends Error {
+    rel;
+    segment;
+    constructor(rel, segment) {
+        super(`Path '${rel}' needs a directory at segment '${segment}' but a regular file exists there.`);
+        this.name = "FilesystemShapeMismatchError";
+        this.rel = rel;
+        this.segment = segment;
+    }
+}
+const ABSENT_PATH_CODES = new Set(["ENOENT", "ENOTDIR"]);
+function isAbsentPathError(err) {
+    return ABSENT_PATH_CODES.has(err?.code ?? "");
+}
+/**
+ * Split `rel` into its exact segments. Ids and keys are validated upstream by `paths.ts`; this
+ * repeats the containment guard so no caller can escape the bundle root even if it skipped
+ * that guard. Lone `.` segments are dropped, exactly as `path.resolve` used to collapse them.
+ */
+function relSegments(rel) {
+    if (typeof rel !== "string" || rel.startsWith("/")) {
+        throw new InvalidInputError(`Path '${String(rel)}' resolves outside the bundle root.`);
+    }
+    const segments = rel.split("/").filter((segment) => segment !== "" && segment !== ".");
+    if (segments.length === 0 || segments.some((segment) => segment === "..")) {
+        throw new InvalidInputError(`Path '${rel}' resolves outside the bundle root.`);
+    }
+    return segments;
+}
+// ── identity key ──────────────────────────────────────────────────────────────
+/**
+ * NFKD, then Unicode FULL case folding applied as lower-upper-lower (locale-independent). A plain
+ * lower-case fold misses the pairs a case-insensitive host equates through full case mapping
+ * (ß/ss, ẞ/SS, final sigma ς/σ, iota-subscript ᾈ/ἀι and its family): two such spellings would get
+ * different keys, both first-creation writers would realize ABSENT, and the second rename would
+ * silently replace the first document. The round trip through upper case expands every such
+ * pair to a common form, so the fold is a superset of every supported host's equivalence;
+ * over-folding (dotless ı with i) only adds serialization, never removes exclusion.
+ */
+export function foldSegment(segment) {
+    return segment.normalize("NFKD").toLowerCase().toUpperCase().toLowerCase();
+}
+/** The physical path of the longest existing ancestor of `resolved`, plus the absent remainder. */
+async function existingAnchor(resolved) {
+    const tail = [];
+    let candidate = resolved;
+    for (;;) {
+        try {
+            return { anchor: await fs.realpath(candidate), tail };
+        }
+        catch (err) {
+            if (!isAbsentPathError(err))
+                throw err;
+        }
+        const parent = path.dirname(candidate);
+        if (parent === candidate)
+            return { anchor: candidate, tail };
+        tail.unshift(path.basename(candidate));
+        candidate = parent;
+    }
+}
+/**
+ * The lock key for one logical identity `(root, rel)`: a digest of the fully folded physical
+ * root path and the folded `rel`. The WHOLE existing ancestor chain is resolved and folded, so
+ * the key is identical whether it is computed before or after any part of the root is created,
+ * and identical for every case or normalization spelling of any segment. It depends on nothing
+ * else: not the environment, the clock, the process, or the host name.
+ */
+export async function identityKey(root, rel) {
+    const foldedRel = relSegments(rel).map(foldSegment).join("/");
+    const { anchor, tail } = await existingAnchor(path.resolve(root));
+    const anchorSegments = anchor.split(path.sep).filter((segment, index) => index === 0 || segment !== "");
+    const foldedRoot = [...anchorSegments, ...tail].map(foldSegment).join("/");
+    return createHash("sha256").update(`superbee-identity/v1\0${foldedRoot}\0${foldedRel}`).digest("hex");
+}
+// ── pure decisions ────────────────────────────────────────────────────────────
+function sameWitness(a, b) {
+    return a.dev === b.dev && a.ino === b.ino;
+}
+/**
+ * The confirmed-witness rule for one `rel` segment: a fresh probe of the requested spelling is
+ * compared with the inode recorded for that segment earlier in the same observation, whether or
+ * not the exact spelling is present in the parent listing. A listing on its own is never a
+ * verdict: an entry can be REPLACED under its own spelling (a non-core actor swapping a whole
+ * directory) without the listing changing at all, and that must restart the observation rather
+ * than let records from two different states pass as one EXACT read (I6). ALIASED requires the
+ * probe to reach the recorded inode while the exact spelling is absent; a different inode is
+ * ambiguous (replaced under either spelling, or deleted and recreated) and restarts; a
+ * same-spelling replacement is NOT an alias.
+ */
+export function confirmAlias(listingHasExact, probe, recorded) {
+    if (probe === null)
+        return "absent";
+    if (!sameWitness(probe, recorded))
+        return "restart";
+    return listingHasExact ? "continue" : "aliased";
+}
+/**
+ * Post-use verdict for the leaf, over the six cells of (listed, probe): the bytes came from the
+ * handle's inode, which must still be what the requested spelling reaches, under its own name.
+ */
+export function classifyLeaf(snapshot) {
+    if (snapshot.probe === null)
+        return "absent";
+    if (!sameWitness(snapshot.probe, snapshot.handle))
+        return "replaced";
+    return snapshot.listed ? "exact" : "aliased";
+}
+/**
+ * Verdict for one non-recursive `mkdir` outcome against the parent listing. A `rel` segment
+ * that already exists is exact only under the requested spelling and only as a directory; a
+ * tail (root) segment that already exists as a directory is accepted under any spelling.
+ */
+export function classifyMkdir(outcome, listing, segment, isTail) {
+    if (outcome === "created")
+        return "created";
+    const exact = listing.find((entry) => entry.name === segment);
+    if (exact === undefined)
+        return isTail ? "exact" : "aliased";
+    return exact.kind === "directory" ? "exact" : "shape-mismatch";
+}
+// ── walks ─────────────────────────────────────────────────────────────────────
+/** `probe` that refuses a symbolic link at any `rel` segment (the walk never follows links). */
+async function probeSegment(port, candidate, rel, segment) {
+    const probed = await port.probe(candidate);
+    if (probed !== null && probed.kind === "symlink")
+        throw new FilesystemSymlinkEntryError(rel, segment);
+    return probed;
+}
+function hasExact(listing, segment) {
+    return listing.some((entry) => entry.name === segment);
+}
+/**
+ * M-REALIZE: per segment, root to leaf, it must exist and the parent listing must carry its exact
+ * spelling. A listing-only alias decision is sound here because the identity lock is held: no
+ * same-key operation can remove the leaf concurrently, and core never removes directories.
+ */
+async function walkExact(port, rootResolved, segments, rel) {
+    let parent = rootResolved;
+    for (let index = 0; index < segments.length; index++) {
+        const segment = segments[index];
+        const candidate = path.join(parent, segment);
+        const probed = await probeSegment(port, candidate, rel, segment);
+        if (probed === null)
+            return { state: "absent", depth: index };
+        const listing = await port.entries(parent);
+        if (listing === null)
+            return { state: "absent", depth: index };
+        if (!hasExact(listing, segment))
+            throw new FilesystemIdentityAliasError(rel, segment);
+        if (index === segments.length - 1)
+            return { state: "exact", leaf: probed };
+        if (probed.kind !== "directory")
+            return { state: "shape-mismatch", segment };
+        parent = candidate;
+    }
+    throw new InvalidInputError(`Path '${rel}' resolves outside the bundle root.`);
+}
+// ── observation ───────────────────────────────────────────────────────────────
+const MAX_RESTARTS = 3;
+/** O-PROBE: walk `rel` root to leaf recording each segment's witness; `null` when any segment is absent. */
+async function recordWalk(port, rootResolved, segments, rel) {
+    const recorded = [];
+    let parent = rootResolved;
+    for (let index = 0; index < segments.length; index++) {
+        const segment = segments[index];
+        const candidate = path.join(parent, segment);
+        const probed = await probeSegment(port, candidate, rel, segment);
+        if (probed === null)
+            return null;
+        if (index < segments.length - 1 && probed.kind !== "directory")
+            return null;
+        recorded.push(probed);
+        parent = candidate;
+    }
+    return recorded;
+}
+/**
+ * One listing walk under the confirmed-witness rule. Every DIRECTORY segment is probed and
+ * compared with its recorded inode even when its exact spelling is listed, so a directory
+ * replaced under the same spelling between walks restarts the observation instead of letting the
+ * replacement's contents pass as EXACT (I6: under non-core directory renames the protocol
+ * restarts or refuses; A11 narrows only the case where a rename away and back restores the SAME
+ * inode between two probes of one walk, which no witness can distinguish from no change). The
+ * LEAF of a handle-bearing pre-walk is deliberately exempt when its spelling is listed: a
+ * same-spelling document replacement is a legitimate concurrent update, and the open handle plus
+ * the post-walk's six-cell leaf table bind the returned bytes to one entry. O-POSTVERIFY
+ * (`handle` given) applies that leaf table against the handle's inode, probing the leaf
+ * unconditionally.
+ */
+async function confirmedWalk(port, rootResolved, segments, rel, recorded, handle) {
+    let parent = rootResolved;
+    for (let index = 0; index < segments.length; index++) {
+        const segment = segments[index];
+        const candidate = path.join(parent, segment);
+        const listing = await port.entries(parent);
+        if (listing === null)
+            return "absent";
+        const listed = hasExact(listing, segment);
+        if (handle !== null && index === segments.length - 1) {
+            const verdict = classifyLeaf({ listed, probe: await probeSegment(port, candidate, rel, segment), handle });
+            if (verdict === "aliased")
+                throw new FilesystemIdentityAliasError(rel, segment);
+            return verdict === "replaced" ? "restart" : verdict;
+        }
+        if (index < segments.length - 1 || !listed) {
+            const verdict = confirmAlias(listed, await probeSegment(port, candidate, rel, segment), recorded[index]);
+            if (verdict === "aliased")
+                throw new FilesystemIdentityAliasError(rel, segment);
+            if (verdict !== "continue")
+                return verdict;
+        }
+        parent = candidate;
+    }
+    return "continue";
+}
+function countRestart(restarts, rel) {
+    if (restarts >= MAX_RESTARTS)
+        throw new ConcurrentReplacementError(rel, restarts + 1);
+    return restarts + 1;
+}
+/**
+ * Observe `(root, rel)` without a lock and without writing anything, reading through one open
+ * handle. Every segment is probed and recorded (O-PROBE), verified by listing with inode
+ * confirmation (O-VERIFY), opened and read, then re-verified with fresh listings while the handle
+ * is still open so its inode cannot be recycled (O-POSTVERIFY). Every ambiguous outcome restarts
+ * from O-PROBE, bounded; the handle is closed before any restart opens another.
+ */
+export async function observeExact(port, root, rel, read) {
+    const segments = relSegments(rel);
+    const rootResolved = path.resolve(root);
+    const target = path.join(rootResolved, ...segments);
+    for (let restarts = 0;;) {
+        const recorded = await recordWalk(port, rootResolved, segments, rel);
+        if (recorded === null)
+            return { state: "absent" };
+        const verified = await confirmedWalk(port, rootResolved, segments, rel, recorded, null);
+        if (verified === "absent")
+            return { state: "absent" };
+        if (verified === "restart") {
+            restarts = countRestart(restarts, rel);
+            continue;
+        }
+        let opened;
+        try {
+            opened = await port.open(target);
+        }
+        catch (err) {
+            if (isAbsentPathError(err))
+                return { state: "absent" };
+            // Win32 can report EPERM when a concurrent delete/replace briefly denies an open. That is
+            // an uncertain generation, not a durable permission verdict; re-run the witnessed walk and
+            // let the existing bound turn persistent contention into ConcurrentReplacementError.
+            if (process.platform === "win32" && err.code === "EPERM") {
+                restarts = countRestart(restarts, rel);
+                continue;
+            }
+            throw err;
+        }
+        let value;
+        let verdict;
+        try {
+            value = await read(opened.handle, target);
+            if (value === null)
+                return { state: "absent" };
+            verdict = await confirmedWalk(port, rootResolved, segments, rel, recorded, opened);
+        }
+        finally {
+            await port.close(opened.handle);
+        }
+        if (verdict === "exact")
+            return { state: "exact", value };
+        if (verdict === "absent")
+            return { state: "absent" };
+        restarts = countRestart(restarts, rel);
+    }
+}
+/**
+ * Handle-less observation of presence: the same walks, with the recorded leaf inode standing in
+ * for an open handle. Yields the leaf's kind and witness as verified by the post-walk.
+ */
+export async function probeExact(port, root, rel) {
+    const segments = relSegments(rel);
+    const rootResolved = path.resolve(root);
+    for (let restarts = 0;;) {
+        const recorded = await recordWalk(port, rootResolved, segments, rel);
+        if (recorded === null)
+            return { state: "absent" };
+        const leaf = recorded[recorded.length - 1];
+        const verified = await confirmedWalk(port, rootResolved, segments, rel, recorded, null);
+        const verdict = verified === "continue" ? await confirmedWalk(port, rootResolved, segments, rel, recorded, leaf) : verified;
+        if (verdict === "exact")
+            return { state: "exact", value: leaf };
+        if (verdict === "absent")
+            return { state: "absent" };
+        restarts = countRestart(restarts, rel);
+    }
+}
+// ── mutation ──────────────────────────────────────────────────────────────────
+/**
+ * Roots (resolved) whose filesystem refused a hard link. Learned lazily on the first creation
+ * that hit the unsupported error class, never by a probe write, and remembered per root so later
+ * first creations there go straight to `rename`. On such filesystems (exFAT, FAT32, some FUSE
+ * mounts) the host's own EEXIST cannot arbitrate a fold gap, so the residual "two concurrent
+ * first-creation writers of a host-equated pair the fold misses are not excluded" applies there
+ * and only there.
+ */
+const linkUnsupportedRoots = new Set();
+/**
+ * Process-local queue per identity key, shared by every `FilesystemBackend` instance: the
+ * engine constructs a fresh adapter per bundle operation, so an instance-level map would
+ * serialize nothing. The entry is dropped once it drains and no newer waiter replaced it.
+ */
+const queues = new Map();
+function enqueue(key, fn) {
+    const tail = queues.get(key) ?? Promise.resolve();
+    const run = tail.then(fn, fn);
+    const settled = run.then(() => undefined, () => undefined);
+    queues.set(key, settled);
+    void settled.then(() => {
+        if (queues.get(key) === settled)
+            queues.delete(key);
+    });
+    return run;
+}
+const ABSENT_FILE_CODES = new Set(["ENOENT", "ENOTDIR", "EISDIR"]);
+function absentDirectoryError(dir) {
+    const err = new Error(`ENOENT: no such file or directory, scandir '${dir}'`);
+    err.code = "ENOENT";
+    err.syscall = "scandir";
+    err.path = dir;
+    return err;
+}
+/** Open, read every byte, close; `null` for the absent-file error class. */
+async function readWhole(port, target) {
+    let opened;
+    try {
+        opened = await port.open(target);
+    }
+    catch (err) {
+        if (ABSENT_FILE_CODES.has(err?.code ?? ""))
+            return null;
+        throw err;
+    }
+    try {
+        return await port.readAll(opened.handle);
+    }
+    catch (err) {
+        if (ABSENT_FILE_CODES.has(err?.code ?? ""))
+            return null;
+        throw err;
+    }
+    finally {
+        await port.close(opened.handle);
+    }
+}
+async function mkdirExact(port, parent, segment, isTail, rel) {
+    const outcome = await port.mkdir(path.join(parent, segment));
+    if (outcome === "created")
+        return;
+    const listing = await port.entries(parent);
+    if (listing === null)
+        throw absentDirectoryError(parent);
+    if (listing.some((entry) => entry.name === segment && entry.kind === "symlink")) {
+        throw new FilesystemSymlinkEntryError(rel, segment);
+    }
+    const verdict = classifyMkdir(outcome, listing, segment, isTail);
+    if (verdict === "aliased")
+        throw new FilesystemIdentityAliasError(rel, segment);
+    if (verdict === "shape-mismatch")
+        throw new FilesystemShapeMismatchError(rel, segment);
+}
+/**
+ * Create every missing directory from the deepest existing one down to the leaf's parent, one
+ * non-recursive `mkdir` at a time. `mkdir` is atomic and core never renames directories, so a
+ * segment this process created keeps its spelling; an EEXIST on a `rel` segment is accepted
+ * only when the parent listing carries the exact spelling.
+ */
+async function ensureExactDirectories(port, rootResolved, segments, existingDepth, rel) {
+    if (existingDepth === 0 && (await port.probe(rootResolved)) === null) {
+        const tail = [];
+        let candidate = rootResolved;
+        for (;;) {
+            const parent = path.dirname(candidate);
+            if (parent === candidate)
+                break;
+            tail.unshift(path.basename(candidate));
+            candidate = parent;
+            if ((await port.probe(candidate)) !== null)
+                break;
+        }
+        for (const segment of tail) {
+            await mkdirExact(port, candidate, segment, true, rel);
+            candidate = path.join(candidate, segment);
+        }
+    }
+    let parent = path.join(rootResolved, ...segments.slice(0, existingDepth));
+    for (const segment of segments.slice(existingDepth, -1)) {
+        await mkdirExact(port, parent, segment, false, rel);
+        parent = path.join(parent, segment);
+    }
+}
+/**
+ * First creation of a leaf that M-REALIZE found ABSENT: publish the complete temp file under the
+ * exact name with `link`, which is atomic and fails EEXIST for ANY entry the host equates with
+ * the name, whatever the identity fold thought. The identity lock prevents spurious refusals
+ * between writers of one identity; the host's EEXIST is what prevents a silent overwrite when
+ * two writers hold different keys for names the host equates. On EEXIST the parent listing
+ * decides: our exact spelling absent means an equated entry won (refused as an alias); present
+ * means a same-spelling entry appeared under our key, which core cannot do (fail closed).
+ * A successful link leaves the temp name as a second hard link to the same inode; removing it can
+ * fail without unmaking the write, so that failure is not reported (the leftover is the
+ * dot-prefixed crash-residue class listings already skip).
+ */
+async function createExactLeaf(port, tmp, target, rel, leaf, rootResolved) {
+    const outcome = await port.link(tmp, target);
+    if (outcome === "linked") {
+        await port.unlink(tmp).catch(() => { });
+        return;
+    }
+    if (outcome === "unsupported") {
+        linkUnsupportedRoots.add(rootResolved);
+        await port.rename(tmp, target);
+        return;
+    }
+    const listing = (await port.entries(path.dirname(target))) ?? [];
+    if (hasExact(listing, leaf))
+        throw new ConcurrentReplacementError(rel, 1);
+    throw new FilesystemIdentityAliasError(rel, leaf);
+}
+/**
+ * Mutate `(root, rel)` inside its identity lock: claim the key, realize the exact state, and let
+ * `body` decide (compare-and-swap, delete-of-absent) before anything is written. An alias at
+ * any segment, a conflict, or an early return leaves the bundle untouched; the bundle root and
+ * missing directories are created only by `replace`. The lock is released on every path.
+ */
+export async function mutateExact(port, root, rel, body) {
+    const segments = relSegments(rel);
+    const rootResolved = path.resolve(root);
+    const target = path.join(rootResolved, ...segments);
+    const leaf = segments[segments.length - 1];
+    const key = await identityKey(root, rel);
+    return enqueue(key, async () => {
+        const release = await port.claim(key, { root: rootResolved, rel });
+        try {
+            const realized = await walkExact(port, rootResolved, segments, rel);
+            if (realized.state === "shape-mismatch")
+                throw new FilesystemShapeMismatchError(rel, realized.segment);
+            const existingDepth = realized.state === "absent" ? realized.depth : segments.length - 1;
+            const context = {
+                state: realized.state,
+                async current() {
+                    return realized.state === "exact" ? readWhole(port, target) : null;
+                },
+                async replace(bytes) {
+                    await ensureExactDirectories(port, rootResolved, segments, existingDepth, rel);
+                    const dir = path.dirname(target);
+                    // Unique per call, not per process: one process can issue two writes to the same
+                    // target within a millisecond, and the second's temp file must not clobber the first's.
+                    const tmpName = `.${leaf}.${process.pid}.${Date.now()}.${randomUUID()}.tmp`;
+                    const tmp = path.join(dir, tmpName);
+                    await port.writeTemp(dir, tmpName, bytes);
+                    try {
+                        if (realized.state === "exact") {
+                            // Replace: the target exists under our exact spelling, so any writer of an
+                            // equated spelling is refused at its own M-REALIZE; an atomic rename is safe.
+                            await replaceExistingLeaf(port, tmp, target, rel);
+                            return;
+                        }
+                        if (linkUnsupportedRoots.has(rootResolved)) {
+                            await port.rename(tmp, target);
+                            return;
+                        }
+                        await createExactLeaf(port, tmp, target, rel, leaf, rootResolved);
+                    }
+                    catch (err) {
+                        await port.unlink(tmp).catch(() => { });
+                        throw err;
+                    }
+                },
+                async remove() {
+                    await port.unlink(target);
+                },
+            };
+            return await body(context);
+        }
+        finally {
+            await release();
+        }
+    });
+}
+// ── production port ───────────────────────────────────────────────────────────
+function kindOf(stats) {
+    if (stats.isSymbolicLink())
+        return "symlink";
+    if (stats.isDirectory())
+        return "directory";
+    if (stats.isFile())
+        return "file";
+    return "other";
+}
+/** The one production binding: `node:fs`, the temp-file convention, and the identity lock. */
+export const nodeFilesystemIdentityPort = Object.freeze({
+    platform: process.platform,
+    async probe(target) {
+        let lstats;
+        try {
+            lstats = await fs.lstat(target);
+        }
+        catch (err) {
+            if (isAbsentPathError(err))
+                return null;
+            throw err;
+        }
+        return { kind: kindOf(lstats), dev: lstats.dev, ino: lstats.ino };
+    },
+    async entries(dir) {
+        try {
+            const dirents = await fs.readdir(dir, { withFileTypes: true });
+            return dirents.map((dirent) => ({ name: dirent.name, kind: kindOf(dirent) }));
+        }
+        catch (err) {
+            if (isAbsentPathError(err))
+                return null;
+            throw err;
+        }
+    },
+    async open(target) {
+        const handle = await fs.open(target, "r");
+        try {
+            const stats = await handle.stat();
+            return { handle, dev: stats.dev, ino: stats.ino };
+        }
+        catch (err) {
+            await handle.close().catch(() => { });
+            throw err;
+        }
+    },
+    readAll(handle) {
+        return handle.readFile();
+    },
+    close(handle) {
+        return handle.close();
+    },
+    async stat(target) {
+        return { mtime: (await fs.stat(target)).mtime };
+    },
+    async mkdir(dir) {
+        try {
+            await fs.mkdir(dir);
+            return "created";
+        }
+        catch (err) {
+            if (err.code === "EEXIST")
+                return "exists";
+            throw err;
+        }
+    },
+    async writeTemp(dir, name, bytes) {
+        await fs.writeFile(path.join(dir, name), bytes);
+    },
+    async link(from, to) {
+        try {
+            await fs.link(from, to);
+            return "linked";
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === "EEXIST")
+                return "exists";
+            if (code === "EPERM" || code === "ENOTSUP" || code === "EOPNOTSUPP" || code === "EXDEV")
+                return "unsupported";
+            throw err;
+        }
+    },
+    async rename(from, to) {
+        await fs.rename(from, to);
+    },
+    async unlink(target) {
+        await fs.unlink(target);
+    },
+    claim(key, identity) {
+        return acquireFilesystemIdentityLock(key, `${identity.root}:${identity.rel}`, { portableRoot: identity.root });
+    },
+});
+//# sourceMappingURL=filesystem-identity.js.map