@kamilio/wire 0.1.9 → 0.1.11

package/node_modules/toolcraft/node_modules/@poe-code/safe-fs/dist/fs/overlay/index.js

@@ -0,0 +1,1305 @@
+import { OverlayMemoryPublication } from "./memory-publication.js";
+import { platform } from "#safe-fs-platform";
+import { openRetainedReadFile, requireCapabilities, retainedReadCapabilities } from "../capabilities.js";
+import { finishCleanup } from "../../contracts/cleanup.js";
+import { collectBytes, readBytes } from "../../contracts/io.js";
+import { FsError, toFsError } from "../../contracts/errors.js";
+import { dirname, isPathWithin, normalizePath, validatePath } from "../../contracts/virtual-path.js";
+import { compareIdentity } from "../mount/identity.js";
+import { compareEntries, registerEntryView } from "../mount/comparison.js";
+import { admitDirectoryEntries, directoryEntryLimit } from "../directory-admission.js";
+function snapshotStat(stat) {
+    const { type, filesystemType, size, allocatedBytes, ioBlockSize, preferredIoBlockSize, mode, mtimeMs, atimeMs, ctimeMs, birthtimeMs, revision, identityScope, opaqueIdentity, opaqueVersion, ino, dev, rdevMajor, rdevMinor, nlink, uid, gid } = stat;
+    return {
+        type, size, mode, mtimeMs, atimeMs, ctimeMs,
+        ...(filesystemType === undefined ? {} : { filesystemType }),
+        ...(allocatedBytes === undefined ? {} : { allocatedBytes }),
+        ...(ioBlockSize === undefined ? {} : { ioBlockSize }),
+        ...(preferredIoBlockSize === undefined ? {} : { preferredIoBlockSize }),
+        ...(birthtimeMs === undefined ? {} : { birthtimeMs }),
+        ...(revision === undefined ? {} : { revision }),
+        ...(identityScope === undefined ? {} : { identityScope }),
+        ...(opaqueIdentity === undefined ? {} : { opaqueIdentity }),
+        ...(opaqueVersion === undefined ? {} : { opaqueVersion }),
+        ...(ino === undefined ? {} : { ino }),
+        ...(dev === undefined ? {} : { dev }),
+        ...(rdevMajor === undefined ? {} : { rdevMajor }),
+        ...(rdevMinor === undefined ? {} : { rdevMinor }),
+        ...(nlink === undefined ? {} : { nlink }),
+        ...(uid === undefined ? {} : { uid }),
+        ...(gid === undefined ? {} : { gid }),
+    };
+}
+function hasCode(error, code) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
+function fail(code, path, message) {
+    throw new FsError(code, { syscall: "overlay", path, ...(message === undefined ? {} : { message }) });
+}
+function integer(value, path, unlimited = false) {
+    if (unlimited && value === Infinity)
+        return;
+    if (!Number.isSafeInteger(value) || value < 0)
+        fail("EINVAL", path);
+}
+function mode(value, path) {
+    if (value !== undefined && (!Number.isInteger(value) || value < 0 || value > 0o7777))
+        fail("EINVAL", path);
+}
+function movedPath(path, moves) {
+    for (const move of moves) {
+        if (isPathWithin(move.source, path))
+            path = move.destination + path.slice(move.source.length);
+    }
+    return path;
+}
+async function waitForTurn(previous, signal) {
+    signal?.throwIfAborted();
+    if (!signal)
+        return previous;
+    return new Promise((resolve, reject) => {
+        const abort = () => { signal.removeEventListener("abort", abort); reject(signal.reason); };
+        signal.addEventListener("abort", abort, { once: true });
+        void previous.then(() => { signal.removeEventListener("abort", abort); resolve(); });
+    });
+}
+export class OverlayFileSystem {
+    capabilities;
+    #upper;
+    #lower;
+    maxBufferBytes;
+    whiteouts = new Set();
+    opaque = new Set();
+    garbage = new Set();
+    activeStages = new Set();
+    linkMetadata = new Map();
+    linkOrigins = new Map();
+    publication;
+    queue = Promise.resolve();
+    constructor(options) {
+        if (options.upper === options.lower)
+            throw new TypeError("Overlay upper and lower must be distinct backends");
+        this.#upper = options.upper;
+        this.#lower = options.lower;
+        this.publication = new OverlayMemoryPublication(this.#upper, this.#lower, this.whiteouts, this.opaque, this.activeStages);
+        registerEntryView(this, (path, options) => this.run(options, async () => {
+            const entry = await this.required(path, options);
+            return { filesystem: entry.backend, path: entry.path, readOnly: this.capabilities.readOnly === true };
+        }, false));
+        this.maxBufferBytes = options.maxBufferBytes ?? Infinity;
+        if (options.maxBufferBytes !== undefined)
+            integer(options.maxBufferBytes, "/", true);
+        const writable = !this.#upper.capabilities.readOnly && this.#upper.capabilities.atomicRename === true;
+        const readable = [this.#upper, this.#lower].map((backend) => retainedReadCapabilities(backend).retainedRead);
+        const streamingRead = readable.every((capability) => capability === true) ? true
+            : readable.every((capability) => capability === false) ? false : undefined;
+        const retainedRead = streamingRead;
+        const streamingWrite = writable && this.#upper.capabilities.streamingWrite === true
+            && retainedReadCapabilities(this.#upper).retainedRead === true
+            && typeof this.#upper.writeStream === "function"
+            ? readable.every((capability) => capability === true) ? true : undefined : false;
+        const append = !writable || this.#upper.capabilities.append === false ? false
+            : this.#upper.capabilities.append === true ? true : undefined;
+        const upper = this.#upper.capabilities;
+        const mutation = requireCapabilities(writable, upper.mkdir, upper.rename, upper.remove, upper.exclusiveCreate, upper.timestamps, upper.permissions);
+        const effectiveAppend = requireCapabilities(append, mutation);
+        const effectiveStreamingWrite = requireCapabilities(streamingWrite, mutation);
+        const semantics = Object.fromEntries([
+            ...["read", "stat", "readdir", "realpath", "access"].map(capability => [capability,
+                requireCapabilities(upper[capability], this.#lower.capabilities[capability], ...(capability === "read" ? readable : []))]),
+            ["write", requireCapabilities(mutation, upper.write)],
+            ["exclusiveCreate", requireCapabilities(mutation, upper.exclusiveCreate)],
+            ["mkdir", requireCapabilities(mutation, upper.mkdir)],
+            ["recursiveMkdir", requireCapabilities(mutation, upper.recursiveMkdir)],
+            ["remove", requireCapabilities(mutation, upper.remove)],
+            ["removeDirectory", requireCapabilities(mutation, upper.removeDirectory)],
+            ["recursiveRemove", requireCapabilities(mutation, upper.recursiveRemove)],
+            ["rename", requireCapabilities(mutation, upper.rename, upper.write)],
+            ["copy", requireCapabilities(mutation, upper.write)],
+            ["exclusiveCopy", requireCapabilities(mutation, upper.exclusiveCreate)],
+            ["truncate", requireCapabilities(mutation, streamingWrite)],
+            ["streamingAppend", requireCapabilities(mutation, streamingWrite)],
+            ["randomAccessWrite", requireCapabilities(mutation, upper.randomAccessWrite)],
+            ["explicitDirectories", requireCapabilities(upper.explicitDirectories, this.#lower.capabilities.explicitDirectories)],
+        ].filter(([, value]) => value !== undefined));
+        this.capabilities = Object.freeze({
+            ...semantics,
+            open: false,
+            conditionalChmod: this.publication.supported(),
+            atomicFilePublication: false, atomicFileMutation: this.publication.supported(), atomicEntryRemoval: false, atomicEntryRemovalReceipt: false, atomicFileStaging: this.publication.supported(), atomicStagingAncestry: this.publication.supported(), retainedStagingCleanup: this.publication.supported(), atomicDirectoryMetadata: this.publication.supported(), trustedOwnedStaging: false,
+            implicitDirectories: false,
+            readlink: upper.readlink === true && this.#lower.capabilities.readlink === true ? true
+                : upper.readlink === false && this.#lower.capabilities.readlink === false ? false : undefined,
+            ...(upper.readOnly === undefined ? {} : { readOnly: upper.readOnly }),
+            ...(effectiveAppend === undefined ? {} : { append: effectiveAppend }),
+            atomicRename: this.publication.supported(), atomicRenameNoReplace: this.publication.supported(),
+            descriptorWriteStream: false,
+            retainedResize: false, atomicResize: false,
+            hardlinks: false,
+            symlinks: writable && this.#upper.capabilities.symlinks === true
+                && typeof this.#upper.symlink === "function" && typeof this.#upper.readlink === "function"
+                && (this.#lower.capabilities.symlinks !== true || typeof this.#lower.readlink === "function"),
+            permissions: writable && this.#upper.capabilities.permissions === true && typeof this.#upper.chmod === "function",
+            timestamps: writable && this.#upper.capabilities.timestamps === true && typeof this.#upper.utimes === "function",
+            ...(streamingRead === undefined ? {} : { streamingRead }),
+            ...(retainedRead === undefined ? {} : { retainedRead }),
+            ...(effectiveStreamingWrite === undefined ? {} : { streamingWrite: effectiveStreamingWrite }),
+        });
+        Object.defineProperty(this, "capabilities", { writable: false, configurable: false });
+    }
+    confineExtraction(roots, options = {}) {
+        if (options.commitGuard !== undefined)
+            return Promise.reject(new FsError("ENOTSUP"));
+        return this.run(options, async () => this.publication.confine(roots, options, (options, operation) => this.run(options, operation, false), this, this.maxBufferBytes), false);
+    }
+    createStagedFile(directory, name, content, options) {
+        return this.run(options, async () => {
+            if (content.type === "file" && content.data.byteLength > this.maxBufferBytes)
+                fail("EFBIG", directory);
+            return this.publication.create(directory, name, content, options);
+        }, false);
+    }
+    publishStagedFile(staging, destination, options) {
+        return this.run(options, () => this.publication.publish(staging, destination, options), false);
+    }
+    removeStagedFile(staging, options = {}) {
+        return this.run(options, () => this.publication.cleanup(staging, options), false);
+    }
+    async open(path, options) {
+        options.signal?.throwIfAborted();
+        throw new FsError("ENOTSUP", { syscall: "open", path });
+    }
+    async run(options, operation, cleanup = true) {
+        options.signal?.throwIfAborted();
+        const previous = this.queue;
+        let release;
+        this.queue = new Promise((resolve) => { release = resolve; });
+        try {
+            await waitForTurn(previous, options.signal);
+        }
+        catch (error) {
+            void previous.then(release);
+            throw error;
+        }
+        try {
+            options.signal?.throwIfAborted();
+            if (cleanup)
+                await this.cleanGarbage(false);
+            return await operation();
+        }
+        finally {
+            release();
+        }
+    }
+    capabilitiesFor(path, options = {}) {
+        return this.run(options, async () => {
+            validatePath(path);
+            // Owned cleanup queries capabilities before using its retained receipt;
+            // private staging is deliberately unavailable to pathname resolution.
+            if ([...this.activeStages].some(root => isPathWithin(root, path)))
+                return this.capabilities;
+            const location = await this.resolve(path, options, options.create !== undefined || options.creation !== "exclusive", true);
+            const backend = location.entry?.backend ?? this.#upper;
+            const capabilities = await backend.capabilitiesFor?.(location.path, options) ?? backend.capabilities;
+            options.signal?.throwIfAborted();
+            const { retainedRead: ignoredRetainedRead, ...composed } = this.capabilities;
+            const retainedRead = retainedReadCapabilities(backend, capabilities).retainedRead;
+            return Object.freeze({ ...composed, ...(retainedRead === undefined ? {} : { retainedRead }) });
+        }, false);
+    }
+    openReadFile(path, options = {}) {
+        return this.run(options, async () => {
+            const entry = await this.required(path, options);
+            if (entry.stat.type !== "file") {
+                const allowDirectory = options.allowDirectory === true;
+                options.signal?.throwIfAborted();
+                if (entry.stat.type !== "directory" || !allowDirectory)
+                    fail("EISDIR", path);
+            }
+            this.permission(entry, 4);
+            return this.pinRead(entry, options);
+        }, false);
+    }
+    async pinRead(entry, options) {
+        // A retained object, not the resolved pathname, carries read authority.
+        if (compareIdentity(entry.stat, entry.stat) !== "same")
+            fail("ENOTSUP", entry.path, "overlay reads require stable backend identity");
+        const ancestors = [];
+        let parent = dirname(entry.path);
+        while (true) {
+            const stat = await entry.backend.lstat(parent, options);
+            if (stat.type !== "directory" || compareIdentity(stat, stat) !== "same")
+                fail("ENOTSUP", entry.path, "overlay reads require stable directory ancestry");
+            ancestors.push({ backend: entry.backend, path: parent, stat });
+            if (parent === "/")
+                break;
+            parent = dirname(parent);
+        }
+        const handle = await openRetainedReadFile(entry.backend, entry.path, options);
+        try {
+            if (compareIdentity(entry.stat, await handle.stat(options)) !== "same")
+                fail("ENOTSUP", entry.path, "backend read object changed during admission");
+            for (const ancestor of ancestors) {
+                const stat = await entry.backend.lstat(ancestor.path, options);
+                if (stat.type !== "directory" || compareIdentity(ancestor.stat, stat) !== "same")
+                    fail("ENOTSUP", entry.path, "backend read ancestry changed during admission");
+            }
+            const current = await this.required(entry.path, options);
+            if (current.backend !== entry.backend || compareIdentity(entry.stat, current.stat) !== "same")
+                fail("ENOTSUP", entry.path, "overlay read layer changed during admission");
+            options.signal?.throwIfAborted();
+            if (entry.stat.type === "directory" && this.publication.supported()) {
+                const logical = this.publication.stat(entry.path, snapshotStat(entry.stat));
+                return new Proxy(handle, {
+                    get(target, property) {
+                        if (property === "stat")
+                            return async (options = {}) => ({
+                                ...await target.stat(options), identityScope: logical.identityScope, dev: logical.dev, ino: logical.ino,
+                            });
+                        const value = Reflect.get(target, property, target);
+                        return typeof value === "function" ? value.bind(target) : value;
+                    },
+                });
+            }
+            return handle;
+        }
+        catch (error) {
+            await finishCleanup(() => handle.close(), true);
+            throw error;
+        }
+    }
+    async *handleBytes(handle, options) {
+        let position = options.start ?? 0;
+        const end = options.endExclusive ?? Number.MAX_SAFE_INTEGER;
+        const chunkSize = options.chunkSize ?? 64 * 1024;
+        while (position < end) {
+            const size = Math.min(chunkSize, end - position);
+            const chunk = await handle.read(position, size, options);
+            options.signal?.throwIfAborted();
+            if (!(chunk instanceof Uint8Array) || chunk.byteLength > size)
+                fail("EIO", "", "backend returned invalid retained bytes");
+            if (!chunk.byteLength)
+                break;
+            position += chunk.byteLength;
+            yield new Uint8Array(chunk);
+        }
+    }
+    writable(path) {
+        if (this.#upper.capabilities.readOnly)
+            fail("EROFS", path);
+        if (this.#upper.capabilities.atomicRename !== true)
+            fail("ENOTSUP", path, "staged mutations require an atomic-rename-capable upper");
+    }
+    permission(entry, mask) {
+        if (entry.backend.capabilities.permissions && ((entry.stat.mode >> 6) & mask) !== mask)
+            fail("EACCES", entry.path);
+    }
+    async maybeStat(backend, path, options) {
+        options.signal?.throwIfAborted();
+        let stat;
+        try {
+            stat = await backend.lstat(path, options);
+        }
+        catch (error) {
+            options.signal?.throwIfAborted();
+            if (hasCode(error, "ENOENT"))
+                return undefined;
+            throw error;
+        }
+        return snapshotStat(stat);
+    }
+    hidden(path) {
+        return [...this.garbage, ...this.activeStages].some((root) => isPathWithin(root, path));
+    }
+    async lowerVisible(path, options) {
+        for (const root of this.whiteouts)
+            if (isPathWithin(root, path))
+                return false;
+        for (const root of this.opaque)
+            if (root !== path && isPathWithin(root, path))
+                return false;
+        const ancestors = path.split("/").filter(Boolean).slice(0, -1);
+        let parent = "";
+        for (const component of ancestors) {
+            parent += `/${component}`;
+            const stat = await this.maybeStat(this.#lower, parent, options);
+            if (!stat || stat.type !== "directory")
+                return false;
+        }
+        return true;
+    }
+    async lookup(path, options) {
+        if (this.hidden(path))
+            return undefined;
+        const upper = await this.maybeStat(this.#upper, path, options);
+        if (upper)
+            return { path, backend: this.#upper, stat: { ...upper, ...(upper.type === "symlink" ? this.linkMetadata.get(path) : {}) } };
+        if (!await this.lowerVisible(path, options))
+            return undefined;
+        const lower = await this.maybeStat(this.#lower, path, options);
+        return lower ? { path, backend: this.#lower, stat: lower } : undefined;
+    }
+    async resolve(path, options, followFinal = true, allowMissing = false, createMode) {
+        validatePath(path);
+        if (!path)
+            fail("ENOENT", path);
+        const pending = path.split("/").filter(Boolean);
+        if (path.endsWith("/"))
+            pending.push(".");
+        const verifications = [];
+        const verified = async (location) => {
+            for (const verification of verifications) {
+                const canonical = await verification.backend.realpath(verification.path, options);
+                options.signal?.throwIfAborted();
+                validatePath(canonical);
+                if (!canonical.startsWith("/"))
+                    fail("EIO", verification.path, "backend returned a nonabsolute realpath");
+                if (verification.finalName !== undefined) {
+                    try {
+                        await verification.backend.lstat(`${verification.path}/${verification.finalName}`, options);
+                    }
+                    catch (error) {
+                        if (location.entry || !hasCode(error, "ENOENT"))
+                            throw error;
+                    }
+                }
+                const expected = verification.finalName === undefined ? canonical
+                    : `${canonical === "/" ? "" : canonical}/${verification.finalName}`;
+                if (location.path !== movedPath(expected, verification.moves ?? []))
+                    fail("ENOTSUP", path, "backend cannot confirm the overlay symlink namespace");
+            }
+            options.signal?.throwIfAborted();
+            return location;
+        };
+        let current = "/";
+        let links = 0;
+        while (pending.length) {
+            options.signal?.throwIfAborted();
+            const parent = await this.lookup(current, options);
+            if (!parent)
+                fail("ENOENT", current);
+            if (parent.stat.type !== "directory")
+                fail("ENOTDIR", current);
+            this.permission(parent, 1);
+            const component = pending.shift();
+            if (component === ".")
+                continue;
+            if (component === "..") {
+                current = dirname(current);
+                continue;
+            }
+            if (new TextEncoder().encode(component).byteLength > 255)
+                fail("ENAMETOOLONG", path);
+            const candidate = current === "/" ? `/${component}` : `${current}/${component}`;
+            if (this.hidden(candidate))
+                fail(allowMissing || createMode !== undefined ? "EBUSY" : "ENOENT", candidate);
+            let entry = await this.lookup(candidate, options);
+            if (!entry && createMode !== undefined) {
+                if (verifications.length)
+                    fail("ENOTSUP", path, "recursive creation through symlinks cannot be verified before mutation");
+                await this.makeDirectory(candidate, createMode, options);
+                entry = await this.lookup(candidate, options);
+            }
+            if (!entry) {
+                if (allowMissing && pending.length === 0)
+                    return verified({ path: candidate });
+                fail("ENOENT", candidate);
+            }
+            if (entry.stat.type === "symlink" && (followFinal || pending.length > 0)) {
+                if (++links > 40)
+                    fail("ELOOP", path);
+                const suffix = [...pending];
+                const last = suffix.at(-1);
+                const finalName = !followFinal && last !== undefined && last !== "." && last !== ".." ? suffix.pop() : undefined;
+                verifications.push({
+                    backend: entry.backend,
+                    path: candidate + (suffix.length ? `/${suffix.join("/")}` : ""),
+                    finalName,
+                });
+                const origin = entry.backend === this.#upper ? this.linkOrigins.get(candidate) : undefined;
+                if (origin)
+                    verifications.push({
+                        backend: this.#lower,
+                        path: origin.path + (suffix.length ? `/${suffix.join("/")}` : ""),
+                        finalName,
+                        moves: origin.moves,
+                    });
+                const target = await this.linkTarget(entry, options);
+                const parts = target.split("/").filter(Boolean);
+                if (target.endsWith("/"))
+                    parts.push(".");
+                pending.unshift(...parts);
+                if (target.startsWith("/"))
+                    current = "/";
+            }
+            else
+                current = candidate;
+        }
+        const entry = await this.lookup(current, options);
+        if (!entry)
+            fail("ENOENT", current);
+        return verified({ path: current, entry });
+    }
+    async linkTarget(entry, options) {
+        if (!entry.backend.readlink)
+            fail("ENOTSUP", entry.path);
+        const target = await entry.backend.readlink(entry.path, options);
+        options.signal?.throwIfAborted();
+        validatePath(target);
+        if (!target)
+            fail("ENOENT", entry.path);
+        return target;
+    }
+    async movableLinkTarget(entry, options) {
+        const target = await this.linkTarget(entry, options);
+        const canonical = await entry.backend.realpath(entry.path, options);
+        options.signal?.throwIfAborted();
+        const parts = target.split("/").filter(Boolean);
+        if (target.endsWith("/"))
+            parts.push(".");
+        let current = target.startsWith("/") ? "/" : dirname(entry.path);
+        let stat = await this.maybeStat(entry.backend, current, options);
+        for (const part of parts) {
+            if (!stat)
+                fail("ENOENT", current);
+            if (stat.type !== "directory")
+                fail("ENOTSUP", entry.path, "symlink copy-up requires an alias-free target path");
+            if (part === ".")
+                continue;
+            current = part === ".." ? dirname(current) : `${current === "/" ? "" : current}/${part}`;
+            stat = await this.maybeStat(entry.backend, current, options);
+            if (stat?.type === "symlink")
+                fail("ENOTSUP", entry.path, "symlink copy-up cannot preserve an ambiguous target alias");
+        }
+        if (!stat)
+            fail("ENOENT", current);
+        if (canonical !== current)
+            fail("ENOTSUP", entry.path, "backend cannot prove symlink semantics survive copy-up");
+        return target;
+    }
+    async required(path, options, followFinal = true) {
+        return (await this.resolve(path, options, followFinal)).entry;
+    }
+    async listing(entry, options, limit) {
+        if (entry.stat.type !== "directory")
+            fail("ENOTDIR", entry.path);
+        this.permission(entry, 4);
+        const names = new Set();
+        const admit = (name) => {
+            options.signal?.throwIfAborted();
+            if (!names.has(name))
+                admitDirectoryEntries(names.size + 1, limit, entry.path);
+            names.add(name);
+        };
+        const upper = await this.maybeStat(this.#upper, entry.path, options);
+        if (upper?.type === "directory") {
+            const children = await this.#upper.readdir(entry.path, options);
+            options.signal?.throwIfAborted();
+            admitDirectoryEntries(children.length, limit, entry.path);
+            for (const child of children)
+                admit(child.name);
+        }
+        if (await this.lowerVisible(entry.path, options) && !this.opaque.has(entry.path)) {
+            const lower = await this.maybeStat(this.#lower, entry.path, options);
+            if (lower?.type === "directory") {
+                const children = await this.#lower.readdir(entry.path, options);
+                options.signal?.throwIfAborted();
+                admitDirectoryEntries(children.length, limit, entry.path);
+                for (const child of children)
+                    admit(child.name);
+            }
+        }
+        const entries = [];
+        for (const name of [...names].sort()) {
+            if (!name || name === "." || name === ".." || name.includes("/") || name.includes("\0"))
+                fail("EIO", entry.path, "invalid backend directory entry");
+            const child = await this.lookup(entry.path === "/" ? `/${name}` : `${entry.path}/${name}`, options);
+            if (child)
+                entries.push({ name, type: child.stat.type });
+        }
+        return entries;
+    }
+    async bytes(entry, options) {
+        if (entry.stat.type !== "file")
+            fail("EISDIR", entry.path);
+        this.permission(entry, 4);
+        if (options.maxBytes !== undefined)
+            integer(options.maxBytes, entry.path, true);
+        const limit = Math.min(options.maxBytes ?? this.maxBufferBytes, this.maxBufferBytes);
+        if (entry.stat.size > limit)
+            fail("EFBIG", entry.path);
+        const handle = await this.pinRead(entry, options);
+        let failed = true;
+        try {
+            const result = await collectBytes(this.handleBytes(handle, options), { ...options, ...(limit === Infinity ? {} : { maxBytes: limit }) });
+            failed = false;
+            return result;
+        }
+        finally {
+            await finishCleanup(() => handle.close(), failed);
+        }
+    }
+    async cleanGarbage(strict) {
+        const failures = [];
+        for (const path of this.garbage) {
+            try {
+                await this.#upper.rm(path, { recursive: true, force: true });
+                this.garbage.delete(path);
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+        if (strict && failures.length)
+            throw new AggregateError(failures, "Overlay staging cleanup failed");
+    }
+    async cleanup(options = {}) {
+        return this.run(options, () => this.cleanGarbage(true));
+    }
+    // Receipts describe overlay paths and identities, never backing-layer staging paths.
+    stagingOptions({ signal }) {
+        return signal === undefined ? {} : { signal };
+    }
+    async staged(options, operation) {
+        options = this.stagingOptions(options);
+        const root = `/.virtual-bash-overlay-${platform.randomUUID()}`;
+        if (await this.maybeStat(this.#upper, root, options) || await this.maybeStat(this.#lower, root, options))
+            fail("EEXIST", root);
+        this.activeStages.add(root);
+        try {
+            await this.#upper.mkdir(root, { ...options, mode: 0o700 });
+            return await operation(`${root}/entry`);
+        }
+        finally {
+            this.activeStages.delete(root);
+            this.garbage.add(root);
+            await this.cleanGarbage(false);
+        }
+    }
+    async preserve(path, stat, options) {
+        options = this.stagingOptions(options);
+        if (this.#upper.chmod)
+            await this.#upper.chmod(path, stat.mode & 0o7777, options);
+        else if (((await this.#upper.lstat(path, options)).mode & 0o7777) !== (stat.mode & 0o7777))
+            fail("ENOTSUP", path, "upper cannot preserve modes");
+        if (!this.#upper.utimes)
+            fail("ENOTSUP", path, "upper cannot preserve timestamps during copy-up");
+        await this.#upper.utimes(path, stat.atimeMs, stat.mtimeMs, options);
+    }
+    async clone(entry, destination, options) {
+        options = this.stagingOptions(options);
+        if (entry.stat.type !== "directory" && ((entry.stat.nlink ?? 1) > 1
+            || (entry.backend.capabilities.hardlinks === true && entry.stat.nlink === undefined))) {
+            fail("ENOTSUP", entry.path, "copy-up cannot preserve hardlink identity");
+        }
+        if (entry.stat.type === "symlink") {
+            if (!this.capabilities.symlinks || !entry.backend.readlink || !this.#upper.symlink)
+                fail("ENOTSUP", entry.path);
+            await this.#upper.symlink(await this.movableLinkTarget(entry, options), destination, options);
+            return;
+        }
+        if (entry.stat.type === "directory")
+            await this.#upper.mkdir(destination, { ...options, mode: entry.stat.mode & 0o7777 });
+        else {
+            if (this.#upper.capabilities.streamingWrite !== true || !this.#upper.writeStream)
+                fail("ENOTSUP", destination, "copy-up requires a streaming upper");
+            this.permission(entry, 4);
+            if (entry.stat.size > this.maxBufferBytes)
+                fail("EFBIG", entry.path);
+            await this.streamToUpper(destination, this.bounded(this.entryBytes(entry, options), entry.path, options), { ...options, mode: 0o600, flag: "wx" });
+        }
+        await this.preserve(destination, entry.stat, options);
+    }
+    rememberLink(entry, destination) {
+        this.linkMetadata.delete(destination);
+        if (entry.stat.type === "symlink") {
+            this.linkMetadata.set(destination, { mode: entry.stat.mode, atimeMs: entry.stat.atimeMs, mtimeMs: entry.stat.mtimeMs });
+        }
+    }
+    async ensureDirectory(path, options) {
+        options = this.stagingOptions(options);
+        const entry = await this.lookup(path, options);
+        if (!entry)
+            fail("ENOENT", path);
+        if (entry.stat.type !== "directory")
+            fail("ENOTDIR", path);
+        if (entry.backend === this.#upper)
+            return;
+        await this.copyUp(entry, options);
+    }
+    async copyUp(entry, options) {
+        options = this.stagingOptions(options);
+        if (entry.backend === this.#upper)
+            return;
+        if (entry.path === "/")
+            fail("ENOTSUP", entry.path, "upper must have a directory root");
+        let origin;
+        if (entry.stat.type === "symlink") {
+            const target = await this.movableLinkTarget(entry, options);
+            origin = { path: entry.path, target, canonical: normalizePath(target, dirname(entry.path)), moves: [] };
+        }
+        await this.ensureDirectory(dirname(entry.path), options);
+        await this.staged(options, async (temporary) => {
+            await this.clone(entry, temporary, options);
+            options.signal?.throwIfAborted();
+            await this.#upper.rename(temporary, entry.path, options);
+            if (entry.stat.type === "directory")
+                this.publication.copiedDirectory(entry.path, entry.stat);
+            this.rememberLink(entry, entry.path);
+            if (origin)
+                this.linkOrigins.set(entry.path, origin);
+        });
+    }
+    async parent(path, options) {
+        options = this.stagingOptions(options);
+        const parent = await this.lookup(dirname(path), options);
+        if (!parent)
+            fail("ENOENT", dirname(path));
+        if (parent.stat.type !== "directory")
+            fail("ENOTDIR", dirname(path));
+        this.permission(parent, 3);
+        await this.ensureDirectory(parent.path, options);
+    }
+    async makeDirectory(path, permissions, options) {
+        await this.parent(path, options);
+        await this.staged(options, async (temporary) => {
+            await this.#upper.mkdir(temporary, { ...options, mode: permissions });
+            options.signal?.throwIfAborted();
+            await this.#upper.rename(temporary, path, options);
+            this.opaque.add(path);
+            this.linkMetadata.delete(path);
+            this.linkOrigins.delete(path);
+        });
+    }
+    writeOptions(path, options) {
+        this.writable(path);
+        mode(options.mode, path);
+        if (!["w", "wx", "a", "ax"].includes(options.flag ?? "w"))
+            fail("EINVAL", path);
+    }
+    async writeLocation(path, options) {
+        const exclusive = options.flag === "wx" || options.flag === "ax";
+        const location = await this.resolve(path, options, !exclusive, true);
+        if (exclusive && location.entry)
+            fail("EEXIST", path);
+        if (location.entry) {
+            if (location.entry.stat.type !== "file")
+                fail("EISDIR", path);
+            this.permission(location.entry, 2);
+        }
+        return location;
+    }
+    async replace(location, options, operation, commitGuard) {
+        await this.parent(location.path, options);
+        await this.staged(options, async (temporary) => {
+            if (location.entry)
+                await this.clone(location.entry, temporary, options);
+            await operation(temporary);
+            options.signal?.throwIfAborted();
+            commitGuard?.();
+            await this.#upper.rename(temporary, location.path, options);
+            this.linkMetadata.delete(location.path);
+            this.linkOrigins.delete(location.path);
+        });
+    }
+    async readFile(path, options = {}) {
+        return this.run(options, async () => this.bytes(await this.required(path, options), options));
+    }
+    async writeFile(path, data, options = {}) {
+        options.signal?.throwIfAborted();
+        this.writeOptions(path, options);
+        if (!(data instanceof Uint8Array))
+            throw new TypeError("Overlay files require Uint8Array data");
+        if (data.byteLength > this.maxBufferBytes)
+            fail("EFBIG", path);
+        const bytes = new Uint8Array(data);
+        return this.run(options, async () => {
+            const location = await this.writeLocation(path, options);
+            const append = options.flag === "a" || options.flag === "ax";
+            if (append && (location.entry?.stat.size ?? 0) + bytes.byteLength > this.maxBufferBytes)
+                fail("EFBIG", path);
+            if (this.publication.supported() && location.entry?.backend === this.#upper) {
+                const parent = await this.required(dirname(location.path), options);
+                await this.publication.writeFile(location.path, bytes, {
+                    ...options, parent: this.publication.stat(parent.path, parent.stat),
+                    expected: this.publication.stat(location.path, location.entry.stat), append,
+                }, this.maxBufferBytes);
+            }
+            else {
+                await this.replace(location, options, async (temporary) => {
+                    await this.#upper.writeFile(temporary, bytes, { ...options, flag: append ? "a" : "w" });
+                });
+            }
+        });
+    }
+    prepareDirectory(path, options) {
+        const captured = { ...options };
+        return this.run(captured, () => this.publication.prepareDirectory(path, captured), false);
+    }
+    async writeFileConditional(path, data, options) {
+        options.signal?.throwIfAborted();
+        if (!(data instanceof Uint8Array))
+            throw new TypeError("Overlay files require Uint8Array data");
+        const bytes = new Uint8Array(data);
+        if (bytes.byteLength > this.maxBufferBytes)
+            fail("EFBIG", path);
+        const captured = { ...options };
+        return this.run(captured, () => this.publication.writeFile(path, bytes, captured, this.maxBufferBytes), false);
+    }
+    removeFileConditional(path, options) {
+        const captured = { ...options };
+        return this.run(captured, () => this.publication.removeFile(path, captured), false);
+    }
+    async appendFile(path, data, options = {}) {
+        return this.writeFile(path, data, { ...options, flag: "a" });
+    }
+    async stat(path, options = {}) {
+        return this.run(options, async () => {
+            const entry = await this.required(path, options);
+            return this.publication.stat(entry.path, snapshotStat(entry.stat));
+        }, false);
+    }
+    async lstat(path, options = {}) {
+        return this.run(options, async () => {
+            const entry = await this.required(path, options, false);
+            return this.publication.stat(entry.path, snapshotStat(entry.stat));
+        }, false);
+    }
+    compareEntry(path, peer, peerPath, options = {}) {
+        return compareEntries(this, path, peer, peerPath, options);
+    }
+    async readdir(path, options = {}) {
+        const limit = directoryEntryLimit(options, path);
+        return this.run(options, async () => this.listing(await this.required(path, options), options, limit), false);
+    }
+    async *iterateDirectory(path, options = {}) {
+        const directory = await this.run(options, async () => {
+            const entry = await this.required(path, options);
+            if (entry.stat.type !== "directory")
+                fail("ENOTDIR", path);
+            this.permission(entry, 4);
+            return entry.path;
+        }, false);
+        const admit = async () => {
+            const current = await this.required(path, options);
+            if (current.path !== directory || current.stat.type !== "directory")
+                fail("EBUSY", path);
+            this.permission(current, 4);
+        };
+        for (const backend of [this.#upper, this.#lower]) {
+            const iterator = await this.run(options, async () => {
+                await admit();
+                if (backend === this.#lower && (!await this.lowerVisible(directory, options) || this.opaque.has(directory)))
+                    return undefined;
+                if ((await this.maybeStat(backend, directory, options))?.type !== "directory")
+                    return undefined;
+                if (!backend.iterateDirectory)
+                    fail("ENOTSUP", directory);
+                return backend.iterateDirectory(directory, options)[Symbol.asyncIterator]();
+            }, false);
+            if (!iterator)
+                continue;
+            let complete = false, failed = false;
+            try {
+                while (true) {
+                    const result = await this.run(options, async () => {
+                        await admit();
+                        if (backend === this.#lower && (!await this.lowerVisible(directory, options) || this.opaque.has(directory)))
+                            fail("EBUSY", path);
+                        const next = await iterator.next();
+                        options.signal?.throwIfAborted();
+                        if (next.done)
+                            return { done: true };
+                        const name = next.value.name;
+                        if (!name || name === "." || name === ".." || name.includes("/") || name.includes("\0"))
+                            fail("EIO", directory, "invalid backend directory entry");
+                        const child = await this.lookup(directory === "/" ? `/${name}` : `${directory}/${name}`, options);
+                        options.signal?.throwIfAborted();
+                        // A lower name shadowed by upper storage is skipped by lookup,
+                        // without retaining a directory-sized set of previously seen names.
+                        return { done: false, entry: child?.backend === backend ? { name, type: child.stat.type } : undefined };
+                    }, false);
+                    if (result.done) {
+                        complete = true;
+                        break;
+                    }
+                    if (result.entry)
+                        yield result.entry;
+                }
+            }
+            catch (error) {
+                failed = true;
+                throw error;
+            }
+            finally {
+                if (!complete)
+                    await finishCleanup(() => iterator.return?.(), failed);
+            }
+        }
+        options.signal?.throwIfAborted();
+    }
+    async realpath(path, options = {}) {
+        return this.run(options, async () => (await this.required(path, options)).path, false);
+    }
+    async access(path, requestedMode = 0, options = {}) {
+        return this.run(options, async () => {
+            if (!Number.isInteger(requestedMode) || requestedMode < 0 || requestedMode > 7)
+                fail("EINVAL", path);
+            const entry = await this.required(path, options);
+            if (requestedMode & 2)
+                this.writable(path);
+            this.permission(entry, requestedMode);
+            await entry.backend.access(entry.path, requestedMode & ~2, options);
+        }, false);
+    }
+    async mkdir(path, options = {}) {
+        return this.run(options, async () => {
+            this.writable(path);
+            mode(options.mode, path);
+            validatePath(path);
+            if (options.recursive) {
+                const entry = (await this.resolve(path, options, true, false, options.mode ?? 0o777)).entry;
+                if (entry.stat.type !== "directory")
+                    fail("EEXIST", path);
+            }
+            else {
+                const location = await this.resolve(path.replace(/\/+$/, "") || (path ? "/" : ""), options, false, true);
+                if (location.entry)
+                    fail("EEXIST", path);
+                await this.makeDirectory(location.path, options.mode ?? 0o777, options);
+            }
+        });
+    }
+    async rmdir(path, options = {}) {
+        try {
+            await this.run(options, async () => {
+                this.writable(path);
+                validatePath(path);
+                const entry = await this.required(path.replace(/\/+$/, "") || (path ? "/" : ""), options, false);
+                if (/(?:^|\/)\.{1,2}\/*$/.test(path))
+                    fail("EINVAL", path);
+                if (entry.path === "/")
+                    fail("EBUSY", path);
+                if (entry.stat.type !== "directory")
+                    fail("ENOTDIR", path);
+                const parent = await this.required(dirname(entry.path), options);
+                this.permission(parent, 3);
+                if ((await this.listing(entry, options)).length)
+                    fail("ENOTEMPTY", path);
+                options.signal?.throwIfAborted();
+                if (this.#upper.capabilities.snapshotRmdir === true) {
+                    fail("ENOTSUP", path, "snapshot-marker upper removal cannot safely publish an overlay whiteout");
+                }
+                if (entry.backend === this.#upper) {
+                    if (!this.#upper.rmdir)
+                        fail("ENOTSUP", path);
+                    await this.#upper.rmdir(entry.path, options);
+                }
+                this.whiteouts.add(entry.path);
+                for (const key of this.linkMetadata.keys())
+                    if (isPathWithin(entry.path, key))
+                        this.linkMetadata.delete(key);
+                for (const key of this.linkOrigins.keys())
+                    if (isPathWithin(entry.path, key))
+                        this.linkOrigins.delete(key);
+            }, false);
+        }
+        catch (error) {
+            options.signal?.throwIfAborted();
+            throw new FsError(toFsError(error).code, { syscall: "rmdir", path, cause: error });
+        }
+    }
+    async rm(path, options = {}) {
+        return this.run(options, async () => {
+            this.writable(path);
+            let entry;
+            try {
+                entry = await this.required(path, options, false);
+            }
+            catch (error) {
+                if (options.force && hasCode(error, "ENOENT"))
+                    return;
+                throw error;
+            }
+            if (entry.path === "/")
+                fail("EBUSY", path);
+            if (entry.stat.type === "directory" && !options.recursive && (await this.listing(entry, options)).length)
+                fail("ENOTEMPTY", path);
+            await this.parent(entry.path, options);
+            if (entry.backend === this.#upper) {
+                await this.staged(options, async (temporary) => {
+                    options.signal?.throwIfAborted();
+                    await this.#upper.rename(entry.path, temporary, options);
+                    this.whiteouts.add(entry.path);
+                });
+            }
+            else {
+                options.signal?.throwIfAborted();
+                this.whiteouts.add(entry.path);
+            }
+            for (const key of this.linkMetadata.keys())
+                if (isPathWithin(entry.path, key))
+                    this.linkMetadata.delete(key);
+            for (const key of this.linkOrigins.keys())
+                if (isPathWithin(entry.path, key))
+                    this.linkOrigins.delete(key);
+        });
+    }
+    async materialize(entry, options) {
+        if (entry.stat.type === "symlink" && entry.backend === this.#upper)
+            await this.movableLinkTarget(entry, options);
+        const children = entry.stat.type === "directory" ? await this.listing(entry, options) : [];
+        await this.copyUp(entry, options);
+        for (const child of children) {
+            const path = `${entry.path}/${child.name}`;
+            const visible = await this.lookup(path, options);
+            if (!visible)
+                fail("EIO", path, "visible tree changed during materialization");
+            await this.materialize(visible, options);
+        }
+        if (entry.stat.type === "directory")
+            await this.preserve(entry.path, entry.stat, options);
+    }
+    async rename(source, destination, options = {}) {
+        return this.run(options, async () => {
+            if (options.noReplace && !this.publication.supported())
+                fail("ENOTSUP", source, "atomic no-replace rename is unsupported");
+            this.writable(source);
+            const original = await this.required(source, options, false);
+            const target = await this.resolve(destination, options, false, true);
+            if (options.noReplace && target.entry)
+                fail("EEXIST", destination);
+            if (original.path === target.path)
+                return;
+            if (original.path === "/" || target.path === "/")
+                fail("EBUSY", source);
+            if (original.stat.type === "directory" && isPathWithin(original.path, target.path))
+                fail("EINVAL", destination);
+            if (target.entry) {
+                if (original.stat.type === "directory" && target.entry.stat.type !== "directory")
+                    fail("ENOTDIR", destination);
+                if (original.stat.type !== "directory" && target.entry.stat.type === "directory")
+                    fail("EISDIR", destination);
+                if (target.entry.stat.type === "directory" && (await this.listing(target.entry, options)).length)
+                    fail("ENOTEMPTY", destination);
+            }
+            const guard = this.capabilities.atomicRename ? this.publication.prepareRename(original.path, target.path) : undefined;
+            await this.parent(original.path, options);
+            await this.parent(target.path, options);
+            await this.materialize(original, options);
+            options.signal?.throwIfAborted();
+            const move = { source: original.path, destination: target.path };
+            const movedOrigins = [];
+            for (const [path, origin] of this.linkOrigins) {
+                if (!isPathWithin(original.path, path))
+                    continue;
+                const destination = movedPath(path, [move]);
+                const moves = origin.target.startsWith("/") ? origin.moves : [...origin.moves, move];
+                if (normalizePath(origin.target, dirname(destination)) !== movedPath(origin.canonical, moves)) {
+                    fail("ENOTSUP", path, "relocation changes an unprovable relative symlink target");
+                }
+                movedOrigins.push([destination, { ...origin, moves }]);
+            }
+            options.signal?.throwIfAborted();
+            if (this.capabilities.atomicRename)
+                await this.publication.rename(original.path, target.path, options, guard);
+            else
+                await this.#upper.rename(original.path, target.path, options);
+            this.whiteouts.add(original.path);
+            if (original.stat.type === "directory")
+                this.opaque.add(target.path);
+            const moved = [...this.linkMetadata].filter(([path]) => isPathWithin(original.path, path));
+            for (const path of this.linkMetadata.keys()) {
+                if (isPathWithin(original.path, path) || isPathWithin(target.path, path))
+                    this.linkMetadata.delete(path);
+            }
+            for (const [path, metadata] of moved)
+                this.linkMetadata.set(target.path + path.slice(original.path.length), metadata);
+            for (const path of this.linkOrigins.keys()) {
+                if (isPathWithin(original.path, path) || isPathWithin(target.path, path))
+                    this.linkOrigins.delete(path);
+            }
+            for (const [path, origin] of movedOrigins)
+                this.linkOrigins.set(path, origin);
+        });
+    }
+    async copyFile(source, destination, options = {}) {
+        return this.run(options, async () => {
+            this.writable(destination);
+            const original = await this.required(source, options);
+            const target = await this.writeLocation(destination, { ...options, flag: options.exclusive ? "wx" : "w" });
+            if (original.path === target.path)
+                fail("EINVAL", destination, "source and destination are the same file");
+            if (target.entry) {
+                let identity = compareIdentity(original.stat, target.entry.stat);
+                if (identity === "unknown")
+                    identity = await compareEntries(original.backend, original.path, target.entry.backend, target.entry.path, options);
+                if (identity === "same")
+                    fail("EINVAL", destination, "source and destination are the same file");
+                if (identity === "unknown")
+                    fail("ENOTSUP", destination, "backing-entry identity is unknown");
+            }
+            if (target.entry?.backend !== this.#upper) {
+                const upper = await this.maybeStat(this.#upper, target.path, options);
+                if (upper) {
+                    let identity = compareIdentity(original.stat, upper);
+                    if (identity === "unknown")
+                        identity = await compareEntries(original.backend, original.path, this.#upper, target.path, options);
+                    if (identity === "same")
+                        fail("EINVAL", destination, "source and destination are the same file");
+                    if (identity === "unknown")
+                        fail("ENOTSUP", destination, "upper backing-entry identity is unknown");
+                }
+            }
+            await this.cleanGarbage(false);
+            if (original.stat.size > this.maxBufferBytes)
+                fail("EFBIG", source);
+            await this.replace(target, options, async (temporary) => {
+                await this.streamToUpper(temporary, this.entryBytes(original, options), { ...options, mode: original.stat.mode & 0o7777, flag: "w" });
+                if (this.#upper.chmod)
+                    await this.#upper.chmod(temporary, original.stat.mode & 0o7777, options);
+                else if (((await this.#upper.lstat(temporary, options)).mode & 0o7777) !== (original.stat.mode & 0o7777))
+                    fail("ENOTSUP", destination);
+            });
+        }, false);
+    }
+    async readlink(path, options = {}) {
+        return this.run(options, async () => {
+            const entry = await this.required(path, options, false);
+            if (entry.stat.type !== "symlink")
+                fail("EINVAL", path);
+            if (!entry.backend.readlink)
+                fail("ENOTSUP", path);
+            return entry.backend.readlink(entry.path, options);
+        }, false);
+    }
+    async symlink(target, path, options = {}) {
+        return this.run(options, async () => {
+            this.writable(path);
+            if (!this.capabilities.symlinks || !this.#upper.symlink)
+                fail("ENOTSUP", path);
+            validatePath(target);
+            if (!target)
+                fail("ENOENT", path);
+            const location = await this.resolve(path, options, false, true);
+            if (location.entry)
+                fail("EEXIST", path);
+            await this.replace(location, options, (temporary) => this.#upper.symlink(target, temporary, options));
+        });
+    }
+    async link(_existingPath, newPath, options = {}) {
+        options.signal?.throwIfAborted();
+        fail("ENOTSUP", newPath, "overlay hardlinks are not supported");
+    }
+    async metadata(path, capability, options, operation) {
+        return this.run(options, async () => {
+            this.writable(path);
+            if (!this.capabilities[capability])
+                fail("ENOTSUP", path);
+            const entry = await this.required(path, options);
+            if (entry.stat.type === "directory") {
+                await this.copyUp(entry, options);
+                await operation(entry.path);
+            }
+            else if (this.publication.supported() && entry.backend === this.#upper) {
+                await operation(entry.path);
+            }
+            else
+                await this.replace({ path: entry.path, entry }, options, operation);
+        });
+    }
+    async chmod(path, permissions, options = {}) {
+        options.signal?.throwIfAborted();
+        if (permissions === undefined)
+            fail("EINVAL", path);
+        mode(permissions, path);
+        const guard = this.publication.prepareChmod(path, options);
+        if (guard) {
+            const controls = options.signal === undefined ? {} : { signal: options.signal };
+            return this.run(controls, async () => {
+                this.writable(path);
+                guard();
+                const entry = await this.required(path, controls, false);
+                guard();
+                if (entry.stat.type === "directory") {
+                    await this.copyUp(entry, controls);
+                    guard();
+                    await this.#upper.chmod(entry.path, permissions, controls);
+                }
+                else {
+                    await this.replace({ path: entry.path, entry }, controls, temporary => this.#upper.chmod(temporary, permissions, controls), guard);
+                }
+            });
+        }
+        return this.metadata(path, "permissions", options, (target) => this.#upper.chmod(target, permissions, options));
+    }
+    async utimes(path, atimeMs, mtimeMs, options = {}) {
+        options.signal?.throwIfAborted();
+        if (!Number.isFinite(atimeMs) || !Number.isFinite(mtimeMs))
+            fail("EINVAL", path);
+        return this.metadata(path, "timestamps", options, (target) => this.#upper.utimes(target, atimeMs, mtimeMs, options));
+    }
+    async truncate(path, length = 0, options = {}) {
+        integer(length, path);
+        return this.run(options, async () => {
+            this.writable(path);
+            if (length > this.maxBufferBytes)
+                fail("EFBIG", path);
+            const entry = await this.required(path, options);
+            if (entry.stat.type !== "file")
+                fail("EISDIR", path);
+            this.permission(entry, 2);
+            if ((entry.stat.nlink ?? 1) > 1 || (entry.backend.capabilities.hardlinks === true && entry.stat.nlink === undefined)) {
+                fail("ENOTSUP", path, "copy-up cannot preserve hardlink identity");
+            }
+            await this.parent(entry.path, options);
+            await this.staged(options, async (temporary) => {
+                const prefix = this.entryBytes(entry, { ...options, endExclusive: length });
+                const source = async function* () {
+                    let written = 0;
+                    for await (const chunk of prefix) {
+                        written += chunk.byteLength;
+                        yield chunk;
+                    }
+                    while (written < length) {
+                        options.signal?.throwIfAborted();
+                        const zero = new Uint8Array(Math.min(64 * 1024, length - written));
+                        written += zero.byteLength;
+                        yield zero;
+                    }
+                };
+                await this.streamToUpper(temporary, source(), { ...options, mode: 0o600, flag: "wx" });
+                await this.preserve(temporary, entry.stat, options);
+                await this.#upper.utimes(temporary, entry.stat.atimeMs, Date.now(), options);
+                options.signal?.throwIfAborted();
+                await this.#upper.rename(temporary, entry.path, options);
+            });
+        });
+    }
+    async *readStream(path, options = {}) {
+        options.signal?.throwIfAborted();
+        const start = options.start ?? 0;
+        const chunkSize = options.chunkSize ?? 64 * 1024;
+        integer(start, path);
+        integer(chunkSize, path);
+        if (!chunkSize)
+            fail("EINVAL", path);
+        if (options.endExclusive !== undefined) {
+            integer(options.endExclusive, path);
+            if (options.endExclusive < start)
+                fail("EINVAL", path);
+        }
+        const handle = await this.run(options, async () => {
+            const entry = await this.required(path, options);
+            if (entry.stat.type !== "file")
+                fail("EISDIR", path);
+            this.permission(entry, 4);
+            return this.pinRead(entry, options);
+        });
+        let failed = true;
+        try {
+            yield* readBytes(this.handleBytes(handle, options), options.signal);
+            failed = false;
+        }
+        finally {
+            await finishCleanup(() => handle.close(), failed);
+        }
+    }
+    async *bounded(source, path, options) {
+        let size = 0;
+        for await (const chunk of readBytes(source, options.signal)) {
+            if (chunk.byteLength > this.maxBufferBytes - size)
+                fail("EFBIG", path);
+            size += chunk.byteLength;
+            yield new Uint8Array(chunk);
+        }
+    }
+    async streamToUpper(path, source, options) {
+        if (!this.#upper.writeStream || this.#upper.capabilities.streamingWrite !== true)
+            fail("ENOTSUP", path);
+        const input = readBytes(source, options.signal);
+        let failed = false;
+        try {
+            await this.#upper.writeStream(path, input, options);
+        }
+        catch (error) {
+            failed = true;
+            throw error;
+        }
+        finally {
+            await finishCleanup(() => input.return(undefined), failed);
+        }
+    }
+    async *entryBytes(entry, options) {
+        this.permission(entry, 4);
+        const handle = this.activeStages.has(dirname(entry.path)) && entry.backend === this.#upper
+            ? await openRetainedReadFile(this.#upper, entry.path, options) : await this.pinRead(entry, options);
+        let failed = true;
+        try {
+            if (compareIdentity(await handle.stat(options), entry.stat) !== "same")
+                fail("EAGAIN", entry.path);
+            yield* this.handleBytes(handle, options);
+            failed = false;
+        }
+        finally {
+            await finishCleanup(() => handle.close(), failed);
+        }
+    }
+    async writeStream(path, source, options = {}) {
+        options.signal?.throwIfAborted();
+        this.writeOptions(path, options);
+        if (this.capabilities.streamingWrite === false)
+            fail("ENOTSUP", path, "streaming requires retained reads and a streaming upper");
+        await this.run(options, () => this.writeLocation(path, options));
+        await this.staged(options, async (incoming) => {
+            await this.streamToUpper(incoming, this.bounded(source, path, options), { ...options, flag: "wx", mode: 0o600 });
+            const incomingEntry = { path: incoming, backend: this.#upper, stat: await this.#upper.lstat(incoming, options) };
+            await this.run(options, async () => {
+                const location = await this.writeLocation(path, options);
+                const append = options.flag === "a" || options.flag === "ax";
+                if (append && (location.entry?.stat.size ?? 0) + incomingEntry.stat.size > this.maxBufferBytes)
+                    fail("EFBIG", path);
+                if (this.publication.supported() && location.entry?.backend === this.#upper) {
+                    const parent = await this.required(dirname(location.path), options);
+                    const controls = { ...options, parent: this.publication.stat(parent.path, parent.stat),
+                        expected: this.publication.stat(location.path, location.entry.stat) };
+                    const guard = this.publication.prepareWrite(location.path, controls);
+                    if (append) {
+                        await this.staged(options, async (temporary) => {
+                            const previous = this.entryBytes(location.entry, options);
+                            const added = this.entryBytes(incomingEntry, options);
+                            await this.streamToUpper(temporary, (async function* () { yield* previous; yield* added; })(), { ...options, flag: "wx", mode: 0o600 });
+                            this.publication.replaceContents(temporary, location.path, guard);
+                        });
+                    }
+                    else
+                        this.publication.replaceContents(incoming, location.path, guard);
+                }
+                else {
+                    if (location.entry && ((location.entry.stat.nlink ?? 1) > 1
+                        || (location.entry.backend.capabilities.hardlinks === true && location.entry.stat.nlink === undefined))) {
+                        fail("ENOTSUP", path, "copy-up cannot preserve hardlink identity");
+                    }
+                    await this.parent(location.path, options);
+                    await this.staged(options, async (temporary) => {
+                        const previous = append && location.entry ? this.entryBytes(location.entry, options) : undefined;
+                        const added = this.entryBytes(incomingEntry, options);
+                        await this.streamToUpper(temporary, (async function* () { if (previous)
+                            yield* previous; yield* added; })(), { ...options, flag: "wx", mode: location.entry ? 0o600 : options.mode ?? 0o666 });
+                        if (location.entry) {
+                            await this.preserve(temporary, location.entry.stat, options);
+                            await this.#upper.utimes(temporary, location.entry.stat.atimeMs, Date.now(), options);
+                        }
+                        options.signal?.throwIfAborted();
+                        await this.#upper.rename(temporary, location.path, options);
+                        this.linkMetadata.delete(location.path);
+                        this.linkOrigins.delete(location.path);
+                    });
+                }
+            });
+        });
+    }
+}
+export function createOverlayFileSystem(options) {
+    return new OverlayFileSystem(options);
+}