@effect-vfs/core 0.2.0 → 0.3.1

package/dist/internal/virtualFileSystem.js

@@ -0,0 +1,1755 @@
+// Runtime definitions and cohesive live virtual filesystem engine.
+import * as ByteSize from "effect/ByteSize";
+import * as Clock from "effect/Clock";
+import * as Context from "effect/Context";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Encoding from "effect/Encoding";
+import * as Predicate from "effect/Predicate";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import * as Semaphore from "effect/Semaphore";
+import { BytePath } from "../BytePath.js";
+import { ImageError } from "../Snapshot.js";
+import { CanonicalBase64 } from "./canonicalBase64.js";
+import * as Image from "./image.js";
+import * as MetadataDomain from "./metadata.js";
+import { ConfigurationError, decodeConfiguration, FsCode as FsCodeSchema, FsError } from "./virtualFileSystem/errors.js";
+import * as Content from "./virtualFileSystem/overlayContent.js";
+import { compareOverlay } from "./virtualFileSystem/overlayDiff.js";
+import { DOT_DOT_HEX, DOT_HEX, inputBytes, isAttachedBytes, isDotComponent, MAX_NAME_BYTES, nameBytes, ownedPath, preparePath, SLASH_BYTE, SLASH_HEX, strictString } from "./virtualFileSystem/path.js";
+import * as TestHooks from "./virtualFileSystem/testHooks.js";
+import * as WatchHub from "./virtualFileSystem/watchHub.js";
+/** @internal */
+export const VolumeId = Symbol("@effect-vfs/core/Volume");
+/** @internal */
+export const CallerId = Symbol("@effect-vfs/core/Caller");
+/** @internal */
+export const FileHandleId = Symbol("@effect-vfs/core/FileHandle");
+/** @internal */
+export const DirectoryHandleId = Symbol("@effect-vfs/core/DirectoryHandle");
+/** @internal */
+export const ObjectReferenceId = Symbol("@effect-vfs/core/ObjectReference");
+/** @internal */
+export { ConfigurationError, FsCodeSchema as FsCode, FsError };
+// POSIX permission bits, masked against mode once it is shifted to the caller's class.
+const EXECUTE = 0o1;
+const WRITE = 0o2;
+const READ = 0o4;
+// Execute for every class; a file with none is not executable by anyone.
+const ANY_EXECUTE = 0o111;
+// setuid and setgid, cleared whenever a file's contents or ownership change.
+const SET_ID_BITS = 0o6000;
+// Sticky: only the owner of an entry or of its directory may remove it.
+const STICKY_BIT = 0o1000;
+const WALK_YIELD_INTERVAL = 128;
+// Largest signed 64-bit file offset, as POSIX off_t.
+const MAX_FILE_OFFSET = 0x7fffffffffffffffn;
+const Mode = Schema.Natural.check(Schema.isLessThanOrEqualTo(0o7777));
+const isMode = Schema.is(Mode);
+const isNatural = Schema.is(Schema.Natural);
+/** @internal */
+export const Identity = Schema.Struct({
+    uid: Schema.Natural,
+    gid: Schema.Natural,
+    groups: Schema.Array(Schema.Natural),
+    privileged: Schema.Boolean
+});
+/** @internal */
+export const RootCallerOptions = Schema.Struct({
+    identity: Schema.optionalKey(Identity),
+    umask: Schema.optionalKey(Schema.Natural.check(Schema.isLessThanOrEqualTo(0o777)))
+});
+/** @internal */
+export const VolumeOptions = Schema.Struct({
+    maxEntries: Schema.optionalKey(Schema.Natural),
+    maxBytes: Schema.optionalKey(Schema.ByteSize),
+    maxFileBytes: Schema.optionalKey(Schema.ByteSize.check(Schema.makeFilter((size) => ByteSize.isLessThanOrEqualTo(size, ByteSize.bytes(0xffffffff)) ? undefined : "must be at most 4294967295 bytes"))),
+    maxPathBytes: Schema.optionalKey(Schema.ByteSize.check(Schema.makeFilter((size) => ByteSize.isGreaterThanOrEqualTo(size, ByteSize.bytes(1)) ? undefined : "must be at least 1 byte")))
+});
+const isTimestamp = Schema.is(MetadataDomain.Timestamp);
+/** @internal */
+export const Metadata = Schema.Struct({
+    kind: Schema.Literals(["directory", "file", "symlink"]),
+    ino: Schema.BigInt,
+    nlink: Schema.Natural,
+    size: Schema.BigInt,
+    uid: Schema.Natural,
+    gid: Schema.Natural,
+    mode: Mode,
+    atimeNs: MetadataDomain.Timestamp,
+    mtimeNs: MetadataDomain.Timestamp,
+    ctimeNs: MetadataDomain.Timestamp,
+    birthtimeNs: MetadataDomain.Timestamp
+});
+/** @internal */
+export const OwnerUpdate = Schema.Struct({
+    uid: Schema.optionalKey(Schema.Natural),
+    gid: Schema.optionalKey(Schema.Natural)
+});
+/** @internal */
+export const TimeUpdate = Schema.Union([
+    Schema.Struct({ kind: Schema.Literal("now") }),
+    Schema.Struct({ kind: Schema.Literal("omit") }),
+    Schema.Struct({ kind: Schema.Literal("value"), nanoseconds: MetadataDomain.Timestamp })
+]);
+/** @internal */
+export const Times = Schema.Struct({ access: TimeUpdate, modification: TimeUpdate });
+/** @internal */
+export const SeekMode = Schema.Literals(["start", "current", "end", "data", "hole"]);
+const isSeekMode = Schema.is(SeekMode);
+/** @internal */
+export const OpenSettings = Schema.Struct({
+    access: Schema.Literals(["read", "write", "readWrite"]),
+    create: Schema.optionalKey(Schema.Literals(["never", "ifMissing", "exclusive"])),
+    mode: Schema.optionalKey(Mode),
+    append: Schema.optionalKey(Schema.Boolean),
+    truncate: Schema.optionalKey(Schema.Boolean),
+    followFinalSymlink: Schema.optionalKey(Schema.Boolean)
+});
+const WriteFileSettings = Schema.Struct({
+    ...OpenSettings.fields,
+    replaceFinalSymlink: Schema.optionalKey(Schema.Boolean),
+    finalMode: Schema.optionalKey(Mode)
+});
+const decodeOwnerUpdate = Schema.decodeResult(OwnerUpdate, { onExcessProperty: "error" });
+const decodeTimes = Schema.decodeResult(Times, { onExcessProperty: "error" });
+const decodeWriteFileSettings = Schema.decodeResult(WriteFileSettings, { onExcessProperty: "error" });
+const decodeOpenSettings = Schema.decodeResult(OpenSettings, { onExcessProperty: "error" });
+/** @internal */
+export const OverlayNodeKind = Schema.Literals(["directory", "file", "symlink"]);
+/** @internal */
+export const OverlayDifference = Schema.Literals([
+    "content",
+    "mode",
+    "uid",
+    "gid",
+    "atimeNs",
+    "mtimeNs",
+    "ctimeNs",
+    "birthtimeNs"
+]);
+const OverlayDifferences = Schema.Array(OverlayDifference);
+const NonEmptyOverlayDifferences = OverlayDifferences.check(Schema.isMinLength(1));
+/** @internal */
+export const OverlayChange = Schema.Union([
+    Schema.TaggedStruct("Added", { path: BytePath, kind: OverlayNodeKind }),
+    Schema.TaggedStruct("Removed", { path: BytePath, kind: OverlayNodeKind }),
+    Schema.TaggedStruct("Replaced", {
+        path: BytePath,
+        beforeKind: OverlayNodeKind,
+        afterKind: OverlayNodeKind,
+        differences: OverlayDifferences
+    }),
+    Schema.TaggedStruct("Renamed", {
+        from: BytePath,
+        to: BytePath,
+        kind: OverlayNodeKind,
+        differences: OverlayDifferences
+    }),
+    Schema.TaggedStruct("Updated", { path: BytePath, kind: OverlayNodeKind, differences: NonEmptyOverlayDifferences })
+]);
+/** @internal */
+export const OverlayChangesOptions = Schema.Struct({
+    includeTimestamps: Schema.optionalKey(Schema.Boolean)
+});
+/** @internal */
+export class CurrentFileSystem extends Context.Service()("@effect-vfs/core/CurrentFileSystem") {
+}
+/** @internal */
+export const FixtureMetadata = Schema.Struct({
+    uid: Schema.optionalKey(Schema.Natural),
+    gid: Schema.optionalKey(Schema.Natural),
+    mode: Schema.optionalKey(Mode),
+    atimeNs: Schema.optionalKey(MetadataDomain.Timestamp),
+    mtimeNs: Schema.optionalKey(MetadataDomain.Timestamp),
+    ctimeNs: Schema.optionalKey(MetadataDomain.Timestamp),
+    birthtimeNs: Schema.optionalKey(MetadataDomain.Timestamp)
+});
+const FixturePath = Schema.Union([
+    Schema.String,
+    BytePath
+]);
+/** @internal */
+export const FixtureEntry = Schema.Union([
+    Schema.Struct({
+        kind: Schema.Literal("directory"),
+        path: FixturePath,
+        metadata: Schema.optionalKey(FixtureMetadata)
+    }),
+    Schema.Struct({
+        kind: Schema.Literal("file"),
+        path: FixturePath,
+        bytes: Schema.Uint8Array,
+        metadata: Schema.optionalKey(FixtureMetadata)
+    }),
+    Schema.Struct({
+        kind: Schema.Literal("symlink"),
+        path: FixturePath,
+        target: FixturePath,
+        metadata: Schema.optionalKey(FixtureMetadata)
+    }),
+    Schema.Struct({ kind: Schema.Literal("hardLink"), path: FixturePath, target: FixturePath })
+]).pipe(Schema.toTaggedUnion("kind"));
+/** @internal */
+export const Fixture = Schema.Struct({
+    rootMetadata: Schema.optionalKey(FixtureMetadata),
+    entries: Schema.Array(FixtureEntry)
+});
+const objectReferences = new WeakMap();
+const isFileHandle = (value) => Predicate.hasProperty(FileHandleId)(value);
+// Only a PathInput target names a path; a handle-based call has none to report in its error.
+const pathOf = (target) => isFileHandle(target) || isDirectoryHandle(target) ? undefined : target;
+const isDirectoryHandle = (value) => Predicate.hasProperty(DirectoryHandleId)(value);
+const files = new WeakMap();
+const handles = new WeakMap();
+const directoryMetadata = (ino, uid, gid, mode, now) => ({
+    kind: "directory",
+    ino,
+    uid,
+    gid,
+    mode,
+    nlink: 2,
+    size: 0n,
+    atimeNs: now,
+    mtimeNs: now,
+    ctimeNs: now,
+    birthtimeNs: now
+});
+const storedMetadata = (metadata) => ({
+    uid: metadata.uid,
+    gid: metadata.gid,
+    mode: metadata.mode,
+    atimeNs: metadata.atimeNs,
+    mtimeNs: metadata.mtimeNs,
+    ctimeNs: metadata.ctimeNs,
+    birthtimeNs: metadata.birthtimeNs
+});
+/** @internal */
+export const VolumeSource = Data.taggedEnum();
+const UpdateChange = Schema.TaggedStruct("Update", { path: BytePath });
+// Each execution constructs a fresh volume and captures its Clock.
+/** @internal */
+export const makeVolume = Effect.fnUntraced(function* (source, options) {
+    const image = "image" in source ? source.image : undefined;
+    const decoded = decodeConfiguration(VolumeOptions, options === undefined ? {} : options);
+    if (Result.isFailure(decoded))
+        return yield* decoded.failure;
+    const settings = { ...decoded.success };
+    const clock = yield* Clock.clockWith(Effect.succeed);
+    const initialTime = clock.currentTimeNanosUnsafe();
+    if (!isTimestamp(initialTime)) {
+        return yield* new ConfigurationError({ field: "clock.currentTimeNanos" });
+    }
+    const timestamp = (operation) => Effect.suspend(() => {
+        const now = clock.currentTimeNanosUnsafe();
+        return isTimestamp(now)
+            ? Effect.succeed(now)
+            : Effect.fail(new FsError({ code: "InvalidArgument", operation: operation }));
+    });
+    const volumeIdentity = Symbol();
+    const gate = Semaphore.makeUnsafe(1);
+    let revisionCounter = 0n;
+    const nextRevision = () => ++revisionCounter;
+    const root = {
+        kind: "directory",
+        lineage: image?.root,
+        parent: undefined,
+        entries: new Map(),
+        metadata: directoryMetadata(1n, 0, 0, 0o755, initialTime),
+        revision: nextRevision(),
+        objectReference: undefined
+    };
+    let nextInode = 2n;
+    let entries = 0;
+    let usedBytes = 0n;
+    // The schema caps this value at uint32, so this boundary conversion is exact.
+    const maxFileBytes = Number(ByteSize.toBigInt(settings.maxFileBytes ?? ByteSize.bytes(0xffffffff)));
+    // Permit waits stay interruptible. State transitions and resource registration do not.
+    const coordinated = (effect) => gate.withPermit(Effect.uninterruptible(effect));
+    // Read-only walks hold the permit but mutate nothing, so abandoning one midway loses only
+    // local state. Interruptible so a cancelled snapshot actually stops.
+    const coordinatedRead = (effect) => gate.withPermit(effect);
+    if (image !== undefined) {
+        const incoming = new Map();
+        let content = 0n;
+        let count = 0;
+        for (const record of image.records) {
+            if (Image.Record.guards.directory(record))
+                count += record.entries.length;
+            else {
+                const length = CanonicalBase64.decodedLength(Image.Record.guards.file(record) ? record.data : record.target);
+                if (Image.Record.guards.file(record) && length > maxFileBytes) {
+                    return yield* new ImageError({ code: "LimitExceeded", field: "maxFileBytes" });
+                }
+                content += BigInt(length);
+            }
+        }
+        if ((settings.maxEntries !== undefined && count > settings.maxEntries) ||
+            (settings.maxBytes !== undefined && content > ByteSize.toBigInt(settings.maxBytes))) {
+            return yield* new ImageError({ code: "LimitExceeded", field: "volume" });
+        }
+        const baseContents = Predicate.isTagged("Overlay")(source) ? Content.forOverlay(source.base, image) : undefined;
+        for (const record of image.records) {
+            const metadata = {
+                ...record.metadata,
+                kind: record._tag,
+                ino: record.id === image.root ? 1n : nextInode++,
+                nlink: Image.Record.guards.directory(record) ? 2 : 0,
+                size: 0n,
+                atimeNs: record.metadata.atimeNs,
+                mtimeNs: record.metadata.mtimeNs,
+                ctimeNs: record.metadata.ctimeNs,
+                birthtimeNs: record.metadata.birthtimeNs
+            };
+            if (Image.Record.guards.directory(record)) {
+                const node = record.id === image.root
+                    ? root
+                    : {
+                        kind: "directory",
+                        lineage: record.id,
+                        parent: undefined,
+                        entries: new Map(),
+                        metadata,
+                        revision: nextRevision(),
+                        objectReference: undefined
+                    };
+                node.metadata = metadata;
+                incoming.set(record.id, node);
+            }
+            else if (Image.Record.guards.file(record)) {
+                const data = baseContents?.get(record.id) ?? Content.make(yield* CanonicalBase64.decode(record.data));
+                incoming.set(record.id, {
+                    kind: "file",
+                    lineage: record.id,
+                    data,
+                    openCount: 0,
+                    metadata: { ...metadata, size: BigInt(data.bytes.length) },
+                    revision: nextRevision(),
+                    objectReference: undefined
+                });
+            }
+            else {
+                const target = yield* CanonicalBase64.decode(record.target);
+                incoming.set(record.id, {
+                    kind: "symlink",
+                    lineage: record.id,
+                    target,
+                    metadata: { ...metadata, size: BigInt(target.length) },
+                    revision: nextRevision(),
+                    objectReference: undefined
+                });
+            }
+        }
+        for (const record of image.records) {
+            if (!Image.Record.guards.directory(record))
+                continue;
+            const parent = incoming.get(record.id);
+            if (parent?.kind !== "directory")
+                return yield* new ImageError({ code: "InvalidStructure" });
+            for (const entry of record.entries) {
+                const node = incoming.get(entry.target);
+                if (node === undefined)
+                    return yield* new ImageError({ code: "InvalidStructure" });
+                parent.entries.set(Encoding.encodeHex(yield* CanonicalBase64.decode(entry.name)), node);
+                if (node.kind === "directory") {
+                    node.parent = parent;
+                    parent.metadata = { ...parent.metadata, nlink: parent.metadata.nlink + 1 };
+                }
+                else
+                    node.metadata = { ...node.metadata, nlink: node.metadata.nlink + 1 };
+            }
+        }
+        entries = count;
+        usedBytes = content;
+    }
+    const watchHub = yield* WatchHub.make(coordinated);
+    const directoryHex = (directory) => {
+        const names = [];
+        let current = directory;
+        while (current.parent !== undefined) {
+            const parent = current.parent;
+            const found = [...parent.entries].find(([, node]) => node === current);
+            if (found === undefined)
+                break;
+            names.push(found[0]);
+            current = parent;
+        }
+        return SLASH_HEX + names.reverse().join(SLASH_HEX);
+    };
+    const publishEntry = (_tag, parent, name) => {
+        watchHub.publishUnsafe(() => {
+            const prefix = directoryHex(parent);
+            return { _tag, path: ownedPath(nameBytes(prefix + (prefix === SLASH_HEX ? "" : SLASH_HEX) + name)) };
+        });
+    };
+    const publishNode = (target) => {
+        // Directories are never hard linked, so one name reaches them and the parent chain resolves it.
+        if (target.kind === "directory") {
+            // Removal and rename displacement drop the link count while open handles keep reaching the node.
+            // No name resolves it any more, so its empty parent chain would otherwise read as the root path.
+            // The file scan below stops on the same signal, and `lookup` already reads it as NotFound.
+            if (target.metadata.nlink === 0)
+                return;
+            watchHub.publishUnsafe(() => UpdateChange.make({ path: ownedPath(nameBytes(directoryHex(target))) }));
+            return;
+        }
+        watchHub.publishManyUnsafe(() => {
+            const changes = [];
+            const pending = [[root, SLASH_HEX]];
+            // nlink counts the names bound to this node, so the scan stops once it has found them all.
+            while (pending.length > 0 && changes.length < target.metadata.nlink) {
+                const next = pending.pop();
+                if (next === undefined)
+                    break;
+                const [directory, prefix] = next;
+                for (const [name, node] of directory.entries) {
+                    const path = prefix + name;
+                    if (node === target) {
+                        changes.push(UpdateChange.make({ path: ownedPath(nameBytes(path)) }));
+                    }
+                    if (node.kind === "directory")
+                        pending.push([node, path + SLASH_HEX]);
+                }
+            }
+            return changes;
+        });
+    };
+    const captureSnapshot = Effect.fnUntraced(function* () {
+        const ids = new Map([[root, "0"]]);
+        const pending = [root];
+        const records = [];
+        for (let index = 0; index < pending.length; index++) {
+            if (index % WALK_YIELD_INTERVAL === 0)
+                yield* Effect.yieldNow;
+            const node = pending[index];
+            if (node === undefined)
+                continue;
+            const id = ids.get(node);
+            if (id === undefined)
+                return yield* new ImageError({ code: "InvalidStructure" });
+            const metadata = storedMetadata(node.metadata);
+            if (node.kind === "directory") {
+                const children = [];
+                for (const [name, child] of node.entries) {
+                    let target = ids.get(child);
+                    if (target === undefined) {
+                        target = String(ids.size);
+                        ids.set(child, target);
+                        pending.push(child);
+                    }
+                    children.push({ name: CanonicalBase64.encode(nameBytes(name)), target });
+                }
+                records.push(Image.Record.cases.directory.make({ id, metadata, entries: children }));
+            }
+            else if (node.kind === "file") {
+                records.push(Image.Record.cases.file.make({ id, metadata, data: CanonicalBase64.encode(node.data.bytes) }));
+            }
+            else {
+                records.push(Image.Record.cases.symlink.make({ id, metadata, target: CanonicalBase64.encode(node.target) }));
+            }
+        }
+        return yield* Image.capture({ format: "effect-vfs", version: 1, root: "0", records }, undefined, true);
+    });
+    const observeChanges = Effect.fnUntraced(function* () {
+        const observation = [];
+        const paths = [[root, new Uint8Array([SLASH_BYTE])]];
+        for (let index = 0; index < paths.length; index++) {
+            if (index % WALK_YIELD_INTERVAL === 0)
+                yield* Effect.yieldNow;
+            const current = paths[index];
+            if (current === undefined)
+                continue;
+            const [node, path] = current;
+            observation.push({
+                path: new Uint8Array(path),
+                lineage: node.lineage,
+                kind: node.kind,
+                content: node.kind === "file" ? node.data.bytes : node.kind === "symlink" ? node.target : undefined,
+                metadata: storedMetadata(node.metadata)
+            });
+            if (node.kind !== "directory")
+                continue;
+            for (const [name, child] of node.entries) {
+                const bytes = nameBytes(name);
+                const childPath = new Uint8Array(path.length + (path.length === 1 ? 0 : 1) + bytes.length);
+                childPath.set(path);
+                let offset = path.length;
+                if (path.length !== 1)
+                    childPath[offset++] = SLASH_BYTE;
+                childPath.set(bytes, offset);
+                paths.push([child, childPath]);
+            }
+        }
+        return observation;
+    });
+    const captureState = Effect.fnUntraced(function* (hook) {
+        const snapshot = yield* captureSnapshot();
+        if (hook !== undefined)
+            yield* hook.betweenSnapshotAndSummary;
+        return { snapshot, observation: yield* observeChanges() };
+    });
+    const advanceRevision = (node) => {
+        node.revision = nextRevision();
+    };
+    const referenceFor = (node) => {
+        if (node.objectReference !== undefined)
+            return node.objectReference;
+        const reference = Object.freeze({ [ObjectReferenceId]: true });
+        objectReferences.set(reference, { volume: volumeIdentity, node });
+        node.objectReference = reference;
+        return reference;
+    };
+    const invalidateReference = (node) => {
+        const reference = node.objectReference;
+        if (reference === undefined)
+            return;
+        const state = objectReferences.get(reference);
+        if (state !== undefined)
+            state.node = undefined;
+        node.objectReference = undefined;
+    };
+    const release = (reference) => coordinated(Effect.sync(() => {
+        reference.directory = undefined;
+        reference.closed = true;
+    }));
+    const authorize = (node, identity, bits, operation, path) => {
+        if (identity.privileged)
+            return Effect.void;
+        const metadata = node.metadata;
+        const shift = metadata.uid === identity.uid ?
+            6
+            : metadata.gid === identity.gid || identity.groups.includes(metadata.gid)
+                ? 3
+                : 0;
+        return ((metadata.mode >> shift) & bits) === bits
+            ? Effect.void
+            : Effect.fail(path === undefined
+                ? new FsError({ code: "AccessDenied", operation })
+                : new FsError({ code: "AccessDenied", operation, path }));
+    };
+    const reclaim = (file) => {
+        if (file.metadata.nlink === 0 && file.openCount === 0) {
+            usedBytes -= BigInt(file.data.bytes.length);
+            file.data = Content.empty();
+            invalidateReference(file);
+        }
+    };
+    // Whether the volume's entry quota leaves room for one more name.
+    const atEntryLimit = () => settings.maxEntries !== undefined && entries >= settings.maxEntries;
+    // A new subdirectory's ".." entry is a second link to the parent; other node kinds add none.
+    const attach = (parent, name, node, now) => {
+        parent.entries.set(name, node);
+        parent.metadata = {
+            ...parent.metadata,
+            nlink: parent.metadata.nlink + (node.kind === "directory" ? 1 : 0),
+            mtimeNs: now,
+            ctimeNs: now
+        };
+        advanceRevision(parent);
+    };
+    const detach = (node, now) => {
+        if (node.kind === "directory") {
+            node.parent = undefined;
+            node.metadata = { ...node.metadata, nlink: 0, ctimeNs: now };
+            advanceRevision(node);
+            invalidateReference(node);
+        }
+        else {
+            node.metadata = { ...node.metadata, nlink: node.metadata.nlink - 1, ctimeNs: now };
+            advanceRevision(node);
+            if (node.kind === "file")
+                reclaim(node);
+            else if (node.metadata.nlink === 0) {
+                usedBytes -= BigInt(node.target.length);
+                invalidateReference(node);
+            }
+        }
+    };
+    const releaseFile = (ref) => {
+        if (ref.file !== undefined) {
+            ref.file.openCount -= 1;
+            reclaim(ref.file);
+            ref.file = undefined;
+        }
+        ref.closed = true;
+    };
+    // Replacing a payload clears setuid and setgid, and charges the volume for the size delta.
+    const replaceContent = (file, data, now) => {
+        usedBytes += BigInt(data.length - file.data.bytes.length);
+        file.data = Content.make(data);
+        file.metadata = {
+            ...file.metadata,
+            size: BigInt(data.length),
+            mode: file.metadata.mode & ~SET_ID_BITS,
+            mtimeNs: now,
+            ctimeNs: now
+        };
+        advanceRevision(file);
+        publishNode(file);
+    };
+    const resize = Effect.fnUntraced(function* (file, length, operation) {
+        if (!Predicate.isBigInt(length) || length < 0n) {
+            return yield* new FsError({ code: "InvalidArgument", operation: operation });
+        }
+        if (length > BigInt(maxFileBytes))
+            return yield* new FsError({ code: "FileTooLarge", operation: operation });
+        const size = Number(length);
+        if (settings.maxBytes !== undefined &&
+            BigInt(size - file.data.bytes.length) > ByteSize.toBigInt(settings.maxBytes) - usedBytes) {
+            return yield* new FsError({ code: "NoSpace", operation: operation });
+        }
+        const data = new Uint8Array(size);
+        data.set(file.data.bytes.subarray(0, size));
+        replaceContent(file, data, yield* timestamp(operation));
+    });
+    const fileHandle = (ref) => {
+        const get = (operation, access) => ref.file === undefined || (access === "read" && ref.access === "write") ||
+            (access === "write" && ref.access === "read")
+            ? Effect.fail(new FsError({ code: "InvalidHandle", operation: operation }))
+            : Effect.succeed(ref.file);
+        const read = Effect.fnUntraced(function* (maximum, position) {
+            const file = yield* get(position === undefined ? "read" : "pread", "read");
+            if (!isNatural(maximum))
+                return yield* new FsError({ code: "InvalidArgument", operation: "read" });
+            const offset = position ?? ref.offset;
+            if (!Predicate.isBigInt(offset) || offset < 0n || offset > MAX_FILE_OFFSET) {
+                return yield* new FsError({ code: "InvalidArgument", operation: "read" });
+            }
+            const start = Number(offset > file.metadata.size ? file.metadata.size : offset);
+            const data = file.data.bytes.slice(start, start + Math.min(maximum, file.data.bytes.length - start));
+            if (maximum > 0) {
+                file.metadata = { ...file.metadata, atimeNs: (yield* timestamp("read")) };
+            }
+            if (position === undefined)
+                ref.offset += BigInt(data.length);
+            return data;
+        }, coordinated);
+        const write = Effect.fnUntraced(function* (input, position) {
+            if (!isAttachedBytes(input))
+                return yield* new FsError({ code: "InvalidArgument", operation: "write" });
+            const bytes = new Uint8Array(input);
+            return yield* coordinated(Effect.gen(function* () {
+                const file = yield* get(position === undefined ? "write" : "pwrite", "write");
+                const offset = position ?? (ref.append ? file.metadata.size : ref.offset);
+                if (!Predicate.isBigInt(offset) || offset < 0n || offset > MAX_FILE_OFFSET) {
+                    return yield* new FsError({ code: "InvalidArgument", operation: "write" });
+                }
+                if (bytes.length === 0) {
+                    return 0;
+                }
+                if (offset >= BigInt(maxFileBytes))
+                    return yield* new FsError({ code: "FileTooLarge", operation: "write" });
+                const start = Number(offset);
+                const free = settings.maxBytes === undefined
+                    ? BigInt(maxFileBytes)
+                    : ByteSize.toBigInt(settings.maxBytes) - usedBytes;
+                const maximumEnd = BigInt(file.data.bytes.length) + free;
+                const end = Number(BigInt(maxFileBytes) < maximumEnd ? BigInt(maxFileBytes) : maximumEnd);
+                const count = Math.min(bytes.length, Math.max(0, end - start));
+                if (count === 0)
+                    return yield* new FsError({ code: "NoSpace", operation: "write" });
+                const size = Math.max(file.data.bytes.length, start + count);
+                // Always detach before mutation. A same-sized write is the critical
+                // case: the current payload may belong to the base or a prior capture.
+                const data = new Uint8Array(size);
+                data.set(file.data.bytes);
+                const now = yield* timestamp("write");
+                data.set(bytes.subarray(0, count), start);
+                replaceContent(file, data, now);
+                if (position === undefined)
+                    ref.offset = offset + BigInt(count);
+                return count;
+            }));
+        });
+        const handle = Object.freeze({
+            [FileHandleId]: true,
+            read: Effect.fn("FileHandle.read")(function* (maximum) {
+                return yield* read(maximum);
+            }),
+            pread: Effect.fn("FileHandle.pread")(function* (maximum, offset) {
+                return yield* read(maximum, offset);
+            }),
+            write: Effect.fn("FileHandle.write")(function* (bytes) {
+                return yield* write(bytes);
+            }),
+            pwrite: Effect.fn("FileHandle.pwrite")(function* (bytes, offset) {
+                return yield* write(bytes, offset);
+            }),
+            seek: Effect.fn("FileHandle.seek")(function* (offset, mode) {
+                return yield* coordinated(Effect.gen(function* () {
+                    const file = yield* get("seek");
+                    if (!Predicate.isBigInt(offset) || !isSeekMode(mode)) {
+                        return yield* new FsError({ code: "InvalidArgument", operation: "seek" });
+                    }
+                    let next = mode === "current" ? ref.offset + offset : mode === "end" ? file.metadata.size + offset : offset;
+                    if (next < 0n || next > MAX_FILE_OFFSET) {
+                        return yield* new FsError({ code: "InvalidArgument", operation: "seek" });
+                    }
+                    if (mode === "data" || mode === "hole") {
+                        if (offset >= file.metadata.size)
+                            return yield* new FsError({ code: "NoData", operation: "seek" });
+                        if (mode === "hole")
+                            next = file.metadata.size;
+                    }
+                    ref.offset = next;
+                    return next;
+                }));
+            }),
+            truncate: Effect.fn("FileHandle.truncate")(function* (length) {
+                return yield* coordinated(Effect.gen(function* () {
+                    yield* resize(yield* get("truncate", "write"), length, "truncate");
+                }));
+            }),
+            stat: coordinated(Effect.gen(function* () {
+                return { ...(yield* get("stat")).metadata };
+            })).pipe(Effect.withSpan("FileHandle.stat")),
+            sync: coordinated(Effect.suspend(() => Effect.asVoid(get("sync")))).pipe(Effect.withSpan("FileHandle.sync")),
+            close: coordinated(Effect.gen(function* () {
+                yield* get("close");
+                releaseFile(ref);
+            })).pipe(Effect.withSpan("FileHandle.close"))
+        });
+        files.set(handle, ref);
+        return handle;
+    };
+    const createCaller = (reference, identity, umask) => {
+        const referencedNode = Effect.fnUntraced(function* (target, operation) {
+            if (reference.directory === undefined)
+                return yield* new FsError({ code: "ClosedCaller", operation: operation });
+            if (!Predicate.isObject(target))
+                return yield* new FsError({ code: "InvalidReference", operation: operation });
+            const state = objectReferences.get(target);
+            if (state === undefined)
+                return yield* new FsError({ code: "InvalidReference", operation: operation });
+            if (state.volume !== volumeIdentity) {
+                return yield* new FsError({ code: "ForeignReference", operation: operation });
+            }
+            if (state.node === undefined)
+                return yield* new FsError({ code: "StaleReference", operation: operation });
+            return state.node;
+        });
+        const lookup = Effect.fnUntraced(function* (path, base, operation, options = {}) {
+            const { followFinalSymlink = true, allowMissing = false, parentOnly = false } = options;
+            if (reference.directory === undefined) {
+                return yield* new FsError({ code: "ClosedCaller", operation: operation, path: path.input });
+            }
+            let current = path.absolute ? root : reference.directory;
+            if (!path.absolute && base !== undefined) {
+                const target = handles.get(base);
+                if (target === undefined) {
+                    return yield* new FsError({ code: "InvalidHandle", operation: operation, path: path.input });
+                }
+                if (target.volume !== volumeIdentity) {
+                    return yield* new FsError({ code: "ForeignHandle", operation: operation, path: path.input });
+                }
+                if (target.directory === undefined) {
+                    return yield* new FsError({ code: "InvalidHandle", operation: operation, path: path.input });
+                }
+                current = target.directory;
+                yield* authorize(current, identity, EXECUTE, operation, path.input);
+            }
+            if (current.metadata.nlink === 0) {
+                return yield* new FsError({ code: "NotFound", operation: operation, path: path.input });
+            }
+            let work = path;
+            let parent;
+            let name;
+            let traversals = 0;
+            for (let index = 0; index < work.components.length - (parentOnly ? 1 : 0); index++) {
+                if (current.kind !== "directory") {
+                    return yield* new FsError({ code: "NotDirectory", operation: operation, path: path.input });
+                }
+                yield* authorize(current, identity, EXECUTE, operation, path.input);
+                const component = work.components[index];
+                if (component === undefined)
+                    break;
+                if (component === DOT_HEX)
+                    continue;
+                if (component === DOT_DOT_HEX) {
+                    current = current.parent ?? current;
+                    parent = undefined;
+                    name = undefined;
+                    continue;
+                }
+                parent = current;
+                name = component;
+                const child = current.entries.get(component);
+                if (child === undefined) {
+                    if (allowMissing && index === work.components.length - 1 && !work.trailingSlash) {
+                        return { node: undefined, parent, name };
+                    }
+                    return yield* new FsError({ code: "NotFound", operation: operation, path: path.input });
+                }
+                if (child.kind === "symlink" && (followFinalSymlink || index < work.components.length - 1 || work.trailingSlash)) {
+                    if (child.target.length === 0) {
+                        return yield* new FsError({ code: "NotFound", operation: operation, path: path.input });
+                    }
+                    if (++traversals > 40) {
+                        return yield* new FsError({ code: "SymlinkLoop", operation: operation, path: path.input });
+                    }
+                    const suffix = work.suffixes[index] ?? new Uint8Array(0);
+                    if (settings.maxPathBytes !== undefined &&
+                        ByteSize.isGreaterThan(ByteSize.bytes(child.target.length + suffix.length), settings.maxPathBytes)) {
+                        return yield* new FsError({ code: "PathTooLong", operation: operation, path: path.input });
+                    }
+                    const expansion = new Uint8Array(child.target.length + suffix.length);
+                    expansion.set(child.target);
+                    expansion.set(suffix, child.target.length);
+                    const expanded = preparePath(ownedPath(expansion), operation, settings.maxPathBytes);
+                    // The expansion is synthetic: its per-component limits are the caller's to hear about,
+                    // but the path in the error has to be the one the caller passed in.
+                    if (Result.isFailure(expanded)) {
+                        return yield* new FsError({ code: expanded.failure.code, operation: operation, path: path.input });
+                    }
+                    work = expanded.success;
+                    if (work.absolute)
+                        current = root;
+                    index = -1;
+                }
+                else
+                    current = child;
+            }
+            if (!parentOnly && work.trailingSlash && current.kind !== "directory") {
+                return yield* new FsError({ code: "NotDirectory", operation: operation, path: path.input });
+            }
+            return { node: current, parent, name };
+        });
+        const resolveNode = Effect.fnUntraced(function* (path, base, operation, options) {
+            const result = yield* lookup(path, base, operation, options);
+            if (result.node === undefined) {
+                return yield* new FsError({ code: "NotFound", operation: operation, path: path.input });
+            }
+            return result.node;
+        });
+        const locate = Effect.fnUntraced(function* (path, base, operation, options) {
+            const result = yield* lookup(path, base, operation, options);
+            const node = result.node;
+            if (node === undefined) {
+                return yield* new FsError({ code: "NotFound", operation: operation, path: path.input });
+            }
+            if (node.kind !== "directory") {
+                return yield* new FsError({ code: "NotDirectory", operation: operation, path: path.input });
+            }
+            return node;
+        });
+        const acquireDirectory = Effect.fnUntraced(function* (input, options, operation) {
+            const prepared = preparePath(input, operation, settings.maxPathBytes);
+            const base = options?.relativeTo;
+            const acquired = { volume: volumeIdentity, directory: undefined, closed: false };
+            // Register before retaining a directory. Closed scopes can run this immediately,
+            // so registration must not happen while holding the volume permit.
+            yield* Effect.addFinalizer(() => release(acquired));
+            return yield* coordinated(Effect.gen(function* () {
+                if (acquired.closed)
+                    return yield* Effect.interrupt;
+                const path = yield* Effect.fromResult(prepared);
+                const directory = yield* locate(path, base, operation);
+                yield* authorize(directory, identity, EXECUTE, operation, input);
+                acquired.directory = directory;
+                return acquired;
+            }));
+        });
+        const list = Effect.fnUntraced(function* (input, options) {
+            const prepared = preparePath(input, "readDirectory", settings.maxPathBytes);
+            const base = options?.relativeTo;
+            return yield* coordinated(Effect.gen(function* () {
+                const directory = yield* locate(yield* Effect.fromResult(prepared), base, "readDirectory");
+                yield* authorize(directory, identity, READ, "readDirectory", input);
+                const result = [...directory.entries.keys()].map(nameBytes);
+                directory.metadata = { ...directory.metadata, atimeNs: (yield* timestamp("readDirectory")) };
+                return result;
+            }));
+        });
+        const readTarget = Effect.fnUntraced(function* (input, options) {
+            const prepared = preparePath(input, "readLink", settings.maxPathBytes);
+            const base = options?.relativeTo;
+            return yield* coordinated(Effect.gen(function* () {
+                const node = yield* resolveNode(yield* Effect.fromResult(prepared), base, "readLink", {
+                    followFinalSymlink: false
+                });
+                if (node.kind !== "symlink") {
+                    return yield* new FsError({ code: "InvalidArgument", operation: "readLink", path: input });
+                }
+                return new Uint8Array(node.target);
+            }));
+        });
+        const canonical = Effect.fnUntraced(function* (input, options) {
+            const prepared = preparePath(input, "realPath", settings.maxPathBytes);
+            const base = options?.relativeTo;
+            return yield* coordinated(Effect.gen(function* () {
+                const result = yield* lookup(yield* Effect.fromResult(prepared), base, "realPath");
+                const components = [];
+                if (result.node?.kind !== "directory" && result.name !== undefined)
+                    components.push(result.name);
+                let directory = result.node?.kind === "directory" ? result.node : result.parent;
+                while (directory !== undefined && directory.parent !== undefined) {
+                    const parent = directory.parent;
+                    const entry = [...parent.entries].find(([, child]) => child === directory);
+                    if (entry === undefined)
+                        return yield* new FsError({ code: "NotFound", operation: "realPath", path: input });
+                    components.push(entry[0]);
+                    directory = parent;
+                }
+                return nameBytes(SLASH_HEX + components.reverse().join(SLASH_HEX));
+            }));
+        });
+        const metadataNode = Effect.fnUntraced(function* (target, options, operation) {
+            if (reference.directory === undefined) {
+                return yield* new FsError({ code: "ClosedCaller", operation: operation });
+            }
+            if (isFileHandle(target) || isDirectoryHandle(target)) {
+                const ref = isFileHandle(target) ? files.get(target) : handles.get(target);
+                if (ref === undefined)
+                    return yield* new FsError({ code: "InvalidHandle", operation: operation });
+                if (ref.volume !== volumeIdentity) {
+                    return yield* new FsError({ code: "ForeignHandle", operation: operation });
+                }
+                const node = "file" in ref ? ref.file : ref.directory;
+                if (node === undefined)
+                    return yield* new FsError({ code: "InvalidHandle", operation: operation });
+                return node;
+            }
+            const path = yield* Effect.fromResult(preparePath(target, operation, settings.maxPathBytes));
+            return yield* resolveNode(path, options?.relativeTo, operation, {
+                followFinalSymlink: options?.followFinalSymlink !== false
+            });
+        });
+        const permittedMode = (metadata, mode, operation, path) => {
+            if (!identity.privileged && identity.uid !== metadata.uid) {
+                return Effect.fail(path === undefined
+                    ? new FsError({ code: "AccessDenied", operation })
+                    : new FsError({ code: "AccessDenied", operation, path }));
+            }
+            const group = identity.gid === metadata.gid || identity.groups.includes(metadata.gid);
+            return Effect.succeed(!identity.privileged && metadata.kind === "file" && !group ? mode & ~0o2000 : mode);
+        };
+        const changeMode = Effect.fnUntraced(function* (target, mode, options) {
+            if (!isMode(mode))
+                return yield* new FsError({ code: "InvalidArgument", operation: "chmod" });
+            const chosen = options === undefined ? undefined : { ...options };
+            return yield* coordinated(Effect.gen(function* () {
+                const node = yield* metadataNode(target, chosen, "chmod");
+                const permitted = yield* permittedMode(node.metadata, mode, "chmod");
+                node.metadata = {
+                    ...node.metadata,
+                    mode: permitted,
+                    ctimeNs: (yield* timestamp("chmod"))
+                };
+                advanceRevision(node);
+                publishNode(node);
+            }));
+        });
+        const changeOwner = Effect.fnUntraced(function* (target, owner, options) {
+            const decoded = decodeOwnerUpdate(owner);
+            if (Result.isFailure(decoded))
+                return yield* new FsError({ code: "InvalidArgument", operation: "chown" });
+            const update = { ...decoded.success };
+            const chosen = options === undefined ? undefined : { ...options };
+            return yield* coordinated(Effect.gen(function* () {
+                const node = yield* metadataNode(target, chosen, "chown");
+                if (!identity.privileged && (identity.uid !== node.metadata.uid ||
+                    (update.uid !== undefined && update.uid !== node.metadata.uid) ||
+                    (update.gid !== undefined && update.gid !== identity.gid && !identity.groups.includes(update.gid)))) {
+                    return yield* new FsError({ code: "AccessDenied", operation: "chown" });
+                }
+                if (update.uid === undefined && update.gid === undefined)
+                    return;
+                node.metadata = {
+                    ...node.metadata,
+                    uid: update.uid ?? node.metadata.uid,
+                    gid: update.gid ?? node.metadata.gid,
+                    mode: node.kind === "file" ? node.metadata.mode & ~SET_ID_BITS : node.metadata.mode,
+                    ctimeNs: (yield* timestamp("chown"))
+                };
+                advanceRevision(node);
+                publishNode(node);
+            }));
+        });
+        const changeTimes = Effect.fnUntraced(function* (target, times, options) {
+            const decoded = decodeTimes(times);
+            if (Result.isFailure(decoded))
+                return yield* new FsError({ code: "InvalidArgument", operation: "utimes" });
+            const access = { ...decoded.success.access };
+            const modification = { ...decoded.success.modification };
+            const chosen = options === undefined ? undefined : { ...options };
+            return yield* coordinated(Effect.gen(function* () {
+                const node = yield* metadataNode(target, chosen, "utimes");
+                if (access.kind === "omit" && modification.kind === "omit")
+                    return;
+                // POSIX grants write access only when both times are UTIME_NOW; both UTIME_OMIT
+                // returned above. Every other combination, mixed ones included, needs ownership.
+                if (!identity.privileged && identity.uid !== node.metadata.uid) {
+                    if (access.kind !== "now" || modification.kind !== "now") {
+                        const path = pathOf(target);
+                        return yield* path === undefined
+                            ? new FsError({ code: "AccessDenied", operation: "utimes" })
+                            : new FsError({ code: "AccessDenied", operation: "utimes", path });
+                    }
+                    yield* authorize(node, identity, WRITE, "utimes", pathOf(target));
+                }
+                const now = yield* timestamp("utimes");
+                node.metadata = {
+                    ...node.metadata,
+                    atimeNs: access.kind === "omit"
+                        ? node.metadata.atimeNs
+                        : access.kind === "now"
+                            ? now
+                            : access.nanoseconds,
+                    mtimeNs: modification.kind === "omit"
+                        ? node.metadata.mtimeNs
+                        : modification.kind === "now"
+                            ? now
+                            : modification.nanoseconds,
+                    ctimeNs: now
+                };
+                advanceRevision(node);
+                publishNode(node);
+            }));
+        });
+        const authorizeRemoval = (parent, child, operation, input) => (parent.metadata.mode & STICKY_BIT) !== 0 && !identity.privileged &&
+            identity.uid !== parent.metadata.uid && identity.uid !== child.metadata.uid
+            ? Effect.fail(new FsError({ code: "AccessDenied", operation: operation, path: input }))
+            : Effect.void;
+        return Object.freeze({
+            [CallerId]: true,
+            rootReference: coordinated(Effect.gen(function* () {
+                if (reference.directory === undefined) {
+                    return yield* new FsError({ code: "ClosedCaller", operation: "rootReference" });
+                }
+                return referenceFor(root);
+            })).pipe(Effect.withSpan("Caller.rootReference")),
+            lookupReference: Effect.fn("Caller.lookupReference")(function* (directoryReference, name) {
+                if (!isAttachedBytes(name) || name.length === 0 || name.length > MAX_NAME_BYTES || name.includes(0) ||
+                    name.includes(SLASH_BYTE))
+                    return yield* new FsError({ code: "InvalidArgument", operation: "lookupReference" });
+                const key = Encoding.encodeHex(new Uint8Array(name));
+                if (isDotComponent(key))
+                    return yield* new FsError({ code: "InvalidArgument", operation: "lookupReference" });
+                return yield* coordinated(Effect.gen(function* () {
+                    const directory = yield* referencedNode(directoryReference, "lookupReference");
+                    if (directory.kind !== "directory") {
+                        return yield* new FsError({ code: "NotDirectory", operation: "lookupReference" });
+                    }
+                    yield* authorize(directory, identity, EXECUTE, "lookupReference", "/");
+                    const child = directory.entries.get(key);
+                    if (child === undefined)
+                        return yield* new FsError({ code: "NotFound", operation: "lookupReference" });
+                    return referenceFor(child);
+                }));
+            }),
+            parentReference: Effect.fn("Caller.parentReference")(function* (directoryReference) {
+                return yield* coordinated(Effect.gen(function* () {
+                    const directory = yield* referencedNode(directoryReference, "parentReference");
+                    if (directory.kind !== "directory") {
+                        return yield* new FsError({ code: "NotDirectory", operation: "parentReference" });
+                    }
+                    yield* authorize(directory, identity, EXECUTE, "parentReference", "/");
+                    return referenceFor(directory.parent ?? directory);
+                }));
+            }),
+            observeMetadata: Effect.fn("Caller.observeMetadata")(function* (objectReference) {
+                return yield* coordinated(Effect.gen(function* () {
+                    const node = yield* referencedNode(objectReference, "observeMetadata");
+                    return Object.freeze({ value: Object.freeze({ ...node.metadata }), revision: node.revision });
+                }));
+            }),
+            observeDirectory: Effect.fn("Caller.observeDirectory")(function* (directoryReference) {
+                return yield* coordinated(Effect.gen(function* () {
+                    const directory = yield* referencedNode(directoryReference, "observeDirectory");
+                    if (directory.kind !== "directory") {
+                        return yield* new FsError({ code: "NotDirectory", operation: "observeDirectory" });
+                    }
+                    yield* authorize(directory, identity, READ, "observeDirectory", "/");
+                    const value = Object.freeze([...directory.entries].map(([name, node]) => Object.freeze({ name: nameBytes(name), reference: referenceFor(node) })));
+                    return Object.freeze({ value, revision: directory.revision });
+                }));
+            }),
+            readLinkReference: Effect.fn("Caller.readLinkReference")(function* (objectReference) {
+                return yield* coordinated(Effect.gen(function* () {
+                    const node = yield* referencedNode(objectReference, "readLinkReference");
+                    if (node.kind !== "symlink") {
+                        return yield* new FsError({ code: "InvalidArgument", operation: "readLinkReference" });
+                    }
+                    return new Uint8Array(node.target);
+                }));
+            }),
+            openReference: Effect.fn("Caller.openReference")(function* (objectReference) {
+                const acquired = {
+                    volume: volumeIdentity,
+                    file: undefined,
+                    closed: false,
+                    offset: 0n,
+                    access: "read",
+                    append: false
+                };
+                yield* Effect.addFinalizer(() => coordinated(Effect.sync(() => releaseFile(acquired))));
+                return yield* coordinated(Effect.gen(function* () {
+                    if (acquired.closed)
+                        return yield* Effect.interrupt;
+                    const node = yield* referencedNode(objectReference, "openReference");
+                    if (node.kind !== "file")
+                        return yield* new FsError({ code: "IsDirectory", operation: "openReference" });
+                    if (node.metadata.nlink === 0) {
+                        return yield* new FsError({ code: "StaleReference", operation: "openReference" });
+                    }
+                    yield* authorize(node, identity, READ, "openReference", "/");
+                    node.openCount += 1;
+                    acquired.file = node;
+                    return fileHandle(acquired);
+                }));
+            }),
+            readFile: Effect.fn("Caller.readFile")(function* (input, options) {
+                const prepared = preparePath(input, "readFile", settings.maxPathBytes);
+                const base = options?.relativeTo;
+                return yield* coordinated(Effect.gen(function* () {
+                    const node = yield* resolveNode(yield* Effect.fromResult(prepared), base, "readFile");
+                    if (node.kind !== "file") {
+                        return yield* new FsError({ code: "IsDirectory", operation: "readFile", path: input });
+                    }
+                    yield* authorize(node, identity, READ, "readFile", input);
+                    const data = new Uint8Array(node.data.bytes);
+                    node.metadata = { ...node.metadata, atimeNs: (yield* timestamp("readFile")) };
+                    return data;
+                }));
+            }),
+            writeFile: Effect.fn("Caller.writeFile")(function* (input, bytes, options) {
+                const prepared = preparePath(input, "writeFile", settings.maxPathBytes);
+                if (!isAttachedBytes(bytes)) {
+                    return yield* new FsError({ code: "InvalidArgument", operation: "writeFile", path: input });
+                }
+                const captured = new Uint8Array(bytes);
+                const { relativeTo: base, ...raw } = options;
+                const decoded = decodeWriteFileSettings(raw);
+                if (Result.isFailure(decoded)) {
+                    return yield* new FsError({ code: "InvalidArgument", operation: "writeFile", path: input });
+                }
+                const chosen = decoded.success;
+                return yield* coordinated(Effect.gen(function* () {
+                    const path = yield* Effect.fromResult(prepared);
+                    if (chosen.create === "exclusive") {
+                        const exists = yield* Effect.result(lookup(path, base, "writeFile", { followFinalSymlink: false }));
+                        if (Result.isSuccess(exists)) {
+                            return yield* new FsError({ code: "AlreadyExists", operation: "writeFile", path: input });
+                        }
+                        if (exists.failure.code !== "NotFound")
+                            return yield* exists.failure;
+                    }
+                    const resolved = yield* lookup(path, base, "writeFile", {
+                        followFinalSymlink: chosen.replaceFinalSymlink !== true && chosen.followFinalSymlink !== false,
+                        allowMissing: chosen.create === "ifMissing" || chosen.create === "exclusive"
+                    });
+                    const { name, parent } = resolved;
+                    if (parent === undefined || name === undefined || resolved.node?.kind === "directory") {
+                        return yield* new FsError({ code: "IsDirectory", operation: "writeFile", path: input });
+                    }
+                    const replaced = resolved.node?.kind === "symlink" ? resolved.node : undefined;
+                    if (replaced !== undefined && !chosen.replaceFinalSymlink) {
+                        return yield* new FsError({ code: "SymlinkLoop", operation: "writeFile", path: input });
+                    }
+                    if (chosen.access === "read") {
+                        return yield* new FsError({ code: "InvalidHandle", operation: "writeFile", path: input });
+                    }
+                    const file = resolved.node?.kind === "file" ? resolved.node : undefined;
+                    if (file === undefined) {
+                        yield* authorize(parent, identity, WRITE | EXECUTE, "writeFile", input);
+                        if (replaced !== undefined)
+                            yield* authorizeRemoval(parent, replaced, "writeFile", input);
+                        if (replaced === undefined && atEntryLimit()) {
+                            return yield* new FsError({ code: "NoSpace", operation: "writeFile", path: input });
+                        }
+                    }
+                    else {
+                        yield* authorize(file, identity, chosen.access === "readWrite" ? READ | WRITE : WRITE, "writeFile", input);
+                    }
+                    const finalMode = chosen.finalMode === undefined ? undefined : yield* permittedMode(file?.metadata ?? { kind: "file", uid: identity.uid, gid: parent.metadata.gid }, chosen.finalMode, "writeFile", input);
+                    const previous = file?.data.bytes.length ?? 0;
+                    const initial = chosen.truncate ? 0 : previous;
+                    const position = chosen.append ? initial : 0;
+                    const size = Math.max(initial, position + captured.length);
+                    if (size > maxFileBytes) {
+                        return yield* new FsError({ code: "FileTooLarge", operation: "writeFile", path: input });
+                    }
+                    const reclaimed = replaced !== undefined && replaced.metadata.nlink === 1 ? replaced.target.length : 0;
+                    if (settings.maxBytes !== undefined &&
+                        BigInt(size - previous) > ByteSize.toBigInt(settings.maxBytes) - usedBytes + BigInt(reclaimed)) {
+                        return yield* new FsError({ code: "NoSpace", operation: "writeFile", path: input });
+                    }
+                    if (file !== undefined && !chosen.truncate && captured.length === 0 && chosen.finalMode === undefined) {
+                        return;
+                    }
+                    let data = captured;
+                    if (position !== 0 || size !== captured.length) {
+                        data = new Uint8Array(size);
+                        if (file !== undefined && !chosen.truncate)
+                            data.set(file.data.bytes);
+                        data.set(captured, position);
+                    }
+                    const now = yield* timestamp("writeFile");
+                    const node = file ??
+                        {
+                            kind: "file",
+                            lineage: undefined,
+                            // Assigned below on the shared path that also covers an existing file.
+                            data: Content.empty(),
+                            openCount: 0,
+                            metadata: {
+                                ...directoryMetadata(nextInode++, identity.uid, parent.metadata.gid, (chosen.mode ?? 0o666) & 0o777 & ~umask, now),
+                                kind: "file",
+                                nlink: 1
+                            },
+                            revision: nextRevision(),
+                            objectReference: undefined
+                        };
+                    node.data = Content.make(data);
+                    node.metadata = {
+                        ...node.metadata,
+                        mode: finalMode ?? node.metadata.mode & ~SET_ID_BITS,
+                        size: BigInt(size),
+                        mtimeNs: now,
+                        ctimeNs: now
+                    };
+                    advanceRevision(node);
+                    usedBytes += BigInt(size - previous);
+                    if (file === undefined) {
+                        if (replaced !== undefined)
+                            detach(replaced, now);
+                        attach(parent, name, node, now);
+                        if (replaced === undefined)
+                            entries += 1;
+                        publishEntry(replaced === undefined ? "Create" : "Update", parent, name);
+                    }
+                    else
+                        publishNode(node);
+                }));
+            }),
+            chmod: Effect.fn("Caller.chmod")(function* (path, mode, options) {
+                yield* changeMode(path, mode, options);
+            }),
+            chmodHandle: Effect.fn("Caller.chmodHandle")(function* (handle, mode) {
+                yield* changeMode(handle, mode);
+            }),
+            chown: Effect.fn("Caller.chown")(function* (path, owner, options) {
+                yield* changeOwner(path, owner, options);
+            }),
+            chownHandle: Effect.fn("Caller.chownHandle")(function* (handle, owner) {
+                yield* changeOwner(handle, owner);
+            }),
+            utimes: Effect.fn("Caller.utimes")(function* (path, times, options) {
+                yield* changeTimes(path, times, options);
+            }),
+            utimesHandle: Effect.fn("Caller.utimesHandle")(function* (handle, times) {
+                yield* changeTimes(handle, times);
+            }),
+            access: Effect.fn("Caller.access")(function* (input, bits = 0, options) {
+                const prepared = preparePath(input, "access", settings.maxPathBytes);
+                const base = options?.relativeTo;
+                if (!Number.isInteger(bits) || bits < 0 || bits > (READ | WRITE | EXECUTE)) {
+                    return yield* new FsError({ code: "InvalidArgument", operation: "access", path: input });
+                }
+                return yield* coordinated(Effect.gen(function* () {
+                    const node = yield* resolveNode(yield* Effect.fromResult(prepared), base, "access");
+                    if (node.kind === "file" && (bits & EXECUTE) !== 0 && (node.metadata.mode & ANY_EXECUTE) === 0) {
+                        return yield* new FsError({ code: "AccessDenied", operation: "access", path: input });
+                    }
+                    yield* authorize(node, identity, bits, "access", input);
+                }));
+            }),
+            truncate: Effect.fn("Caller.truncate")(function* (input, length, options) {
+                const prepared = preparePath(input, "truncate", settings.maxPathBytes);
+                const base = options?.relativeTo;
+                return yield* coordinated(Effect.gen(function* () {
+                    const node = yield* resolveNode(yield* Effect.fromResult(prepared), base, "truncate");
+                    if (node.kind !== "file") {
+                        return yield* new FsError({ code: "IsDirectory", operation: "truncate", path: input });
+                    }
+                    yield* authorize(node, identity, WRITE, "truncate", input);
+                    yield* resize(node, length, "truncate");
+                }));
+            }),
+            lstat: Effect.fn("Caller.lstat")(function* (input, options) {
+                const prepared = preparePath(input, "lstat", settings.maxPathBytes);
+                const base = options?.relativeTo;
+                return yield* coordinated(Effect.gen(function* () {
+                    const node = yield* resolveNode(yield* Effect.fromResult(prepared), base, "lstat", {
+                        followFinalSymlink: false
+                    });
+                    return { ...node.metadata };
+                }));
+            }),
+            link: Effect.fn("Caller.link")(function* (source, destination, options) {
+                const a = preparePath(source, "link", settings.maxPathBytes);
+                const b = preparePath(destination, "link", settings.maxPathBytes);
+                const sourceBase = options?.sourceRelativeTo;
+                const destinationBase = options?.destinationRelativeTo;
+                const follow = options?.followSourceSymlink ?? false;
+                return yield* coordinated(Effect.gen(function* () {
+                    const node = yield* resolveNode(yield* Effect.fromResult(a), sourceBase, "link", {
+                        followFinalSymlink: follow
+                    });
+                    if (node.kind === "directory") {
+                        return yield* new FsError({ code: "IsDirectory", operation: "link", path: source });
+                    }
+                    const path = yield* Effect.fromResult(b);
+                    const parent = yield* locate(path, destinationBase, "link", { parentOnly: true });
+                    yield* authorize(parent, identity, WRITE | EXECUTE, "link", destination);
+                    const name = path.components.at(-1);
+                    if (isDotComponent(name) || parent.entries.has(name)) {
+                        return yield* new FsError({ code: "AlreadyExists", operation: "link", path: destination });
+                    }
+                    if (path.trailingSlash) {
+                        return yield* new FsError({ code: "NotDirectory", operation: "link", path: destination });
+                    }
+                    if (atEntryLimit()) {
+                        return yield* new FsError({ code: "NoSpace", operation: "link", path: destination });
+                    }
+                    const now = yield* timestamp("link");
+                    attach(parent, name, node, now);
+                    node.metadata = { ...node.metadata, nlink: node.metadata.nlink + 1, ctimeNs: now };
+                    advanceRevision(node);
+                    entries += 1;
+                    publishEntry("Create", parent, name);
+                }));
+            }),
+            symlink: Effect.fn("Caller.symlink")(function* (target, input, options) {
+                const prepared = preparePath(input, "symlink", settings.maxPathBytes);
+                const rawTarget = inputBytes(target);
+                if (Result.isFailure(rawTarget)) {
+                    return yield* new FsError({ code: rawTarget.failure, operation: "symlink", path: target });
+                }
+                if (rawTarget.success.includes(0)) {
+                    return yield* new FsError({ code: "InvalidArgument", operation: "symlink", path: target });
+                }
+                const targetBytes = new Uint8Array(rawTarget.success);
+                const base = options?.relativeTo;
+                return yield* coordinated(Effect.gen(function* () {
+                    const path = yield* Effect.fromResult(prepared);
+                    const bytes = targetBytes;
+                    const parent = yield* locate(path, base, "symlink", { parentOnly: true });
+                    yield* authorize(parent, identity, WRITE | EXECUTE, "symlink", input);
+                    const name = path.components.at(-1);
+                    if (isDotComponent(name) || parent.entries.has(name)) {
+                        return yield* new FsError({ code: "AlreadyExists", operation: "symlink", path: input });
+                    }
+                    if (path.trailingSlash) {
+                        return yield* new FsError({ code: "NotDirectory", operation: "symlink", path: input });
+                    }
+                    if (atEntryLimit() ||
+                        (settings.maxBytes !== undefined &&
+                            BigInt(bytes.length) > ByteSize.toBigInt(settings.maxBytes) - usedBytes))
+                        return yield* new FsError({ code: "NoSpace", operation: "symlink", path: input });
+                    const now = yield* timestamp("symlink");
+                    const node = {
+                        kind: "symlink",
+                        lineage: undefined,
+                        target: new Uint8Array(bytes),
+                        metadata: {
+                            ...directoryMetadata(nextInode, identity.uid, parent.metadata.gid, 0o777, now),
+                            kind: "symlink",
+                            nlink: 1,
+                            size: BigInt(bytes.length)
+                        },
+                        revision: nextRevision(),
+                        objectReference: undefined
+                    };
+                    attach(parent, name, node, now);
+                    nextInode += 1n;
+                    entries += 1;
+                    usedBytes += BigInt(bytes.length);
+                    publishEntry("Create", parent, name);
+                }));
+            }),
+            readDirectoryBytes: Effect.fn("Caller.readDirectoryBytes")(function* (input, options) {
+                return yield* list(input, options);
+            }),
+            readDirectory: Effect.fn("Caller.readDirectory")(function* (input, options) {
+                return yield* Effect.forEach(yield* list(input, options), (bytes) => strictString(bytes, "readDirectory"));
+            }),
+            readLinkBytes: Effect.fn("Caller.readLinkBytes")(function* (input, options) {
+                return yield* readTarget(input, options);
+            }),
+            readLink: Effect.fn("Caller.readLink")(function* (input, options) {
+                return yield* strictString(yield* readTarget(input, options), "readLink");
+            }),
+            realPathBytes: Effect.fn("Caller.realPathBytes")(function* (input, options) {
+                return ownedPath(yield* canonical(input, options));
+            }),
+            realPath: Effect.fn("Caller.realPath")(function* (input, options) {
+                return yield* strictString(yield* canonical(input, options), "realPath");
+            }),
+            open: Effect.fn("Caller.open")(function* (input, options) {
+                const prepared = preparePath(input, "open", settings.maxPathBytes);
+                const { relativeTo: base, ...raw } = options;
+                const decoded = decodeOpenSettings(raw);
+                if (Result.isFailure(decoded)) {
+                    return yield* new FsError({ code: "InvalidArgument", operation: "open", path: input });
+                }
+                const chosen = { ...decoded.success };
+                if (chosen.access === "read" && (chosen.append || chosen.truncate)) {
+                    return yield* new FsError({ code: "InvalidArgument", operation: "open", path: input });
+                }
+                if (chosen.mode !== undefined && (chosen.create === undefined || chosen.create === "never")) {
+                    return yield* new FsError({ code: "InvalidArgument", operation: "open", path: input });
+                }
+                const acquired = {
+                    volume: volumeIdentity,
+                    file: undefined,
+                    closed: false,
+                    offset: 0n,
+                    access: chosen.access,
+                    append: chosen.append ?? false
+                };
+                yield* Effect.addFinalizer(() => coordinated(Effect.sync(() => releaseFile(acquired))));
+                return yield* coordinated(Effect.gen(function* () {
+                    if (acquired.closed)
+                        return yield* Effect.interrupt;
+                    const path = yield* Effect.fromResult(prepared);
+                    if (chosen.create === "exclusive") {
+                        const existing = yield* Effect.result(lookup(path, base, "open", { followFinalSymlink: false }));
+                        if (Result.isSuccess(existing)) {
+                            return yield* new FsError({ code: "AlreadyExists", operation: "open", path: input });
+                        }
+                        if (existing.failure.code !== "NotFound")
+                            return yield* existing.failure;
+                    }
+                    const resolved = yield* lookup(path, base, "open", {
+                        followFinalSymlink: chosen.followFinalSymlink !== false,
+                        allowMissing: chosen.create === "ifMissing" || chosen.create === "exclusive"
+                    });
+                    const parent = resolved.parent;
+                    if (parent === undefined)
+                        return yield* new FsError({ code: "IsDirectory", operation: "open", path: input });
+                    const name = resolved.name;
+                    if (isDotComponent(name)) {
+                        return yield* new FsError({ code: "IsDirectory", operation: "open", path: input });
+                    }
+                    yield* authorize(parent, identity, EXECUTE, "open", input);
+                    let file = resolved.node;
+                    if (file !== undefined && chosen.create === "exclusive") {
+                        return yield* new FsError({ code: "AlreadyExists", operation: "open", path: input });
+                    }
+                    if (file === undefined) {
+                        if (chosen.create === undefined || chosen.create === "never" || path.trailingSlash) {
+                            return yield* new FsError({ code: "NotFound", operation: "open", path: input });
+                        }
+                        yield* authorize(parent, identity, WRITE | EXECUTE, "open", input);
+                        if (atEntryLimit()) {
+                            return yield* new FsError({ code: "NoSpace", operation: "open", path: input });
+                        }
+                        const now = yield* timestamp("open");
+                        file = {
+                            kind: "file",
+                            lineage: undefined,
+                            data: Content.empty(),
+                            openCount: 0,
+                            metadata: {
+                                ...directoryMetadata(nextInode, identity.uid, parent.metadata.gid, (chosen.mode ?? 0o666) & 0o777 & ~umask, now),
+                                kind: "file",
+                                nlink: 1
+                            },
+                            revision: nextRevision(),
+                            objectReference: undefined
+                        };
+                        attach(parent, name, file, now);
+                        entries += 1;
+                        nextInode += 1n;
+                        publishEntry("Create", parent, name);
+                    }
+                    else {
+                        if (file.kind === "symlink") {
+                            return yield* new FsError({ code: "SymlinkLoop", operation: "open", path: input });
+                        }
+                        if (file.kind !== "file") {
+                            return yield* new FsError({ code: "IsDirectory", operation: "open", path: input });
+                        }
+                        if (path.trailingSlash) {
+                            return yield* new FsError({ code: "NotDirectory", operation: "open", path: input });
+                        }
+                        yield* authorize(file, identity, chosen.access === "read" ? READ : chosen.access === "write" ? WRITE : READ | WRITE, "open", input);
+                        if (chosen.truncate)
+                            yield* resize(file, 0n, "open");
+                    }
+                    file.openCount += 1;
+                    acquired.file = file;
+                    return fileHandle(acquired);
+                }));
+            }),
+            unlink: Effect.fn("Caller.unlink")(function* (input, options) {
+                const prepared = preparePath(input, "unlink", settings.maxPathBytes);
+                const base = options?.relativeTo;
+                return yield* coordinated(Effect.gen(function* () {
+                    const path = yield* Effect.fromResult(prepared);
+                    const parent = yield* locate(path, base, "unlink", { parentOnly: true });
+                    yield* authorize(parent, identity, WRITE | EXECUTE, "unlink", input);
+                    const name = path.components.at(-1);
+                    if (isDotComponent(name)) {
+                        return yield* new FsError({ code: "IsDirectory", operation: "unlink", path: input });
+                    }
+                    const child = parent.entries.get(name);
+                    if (child === undefined)
+                        return yield* new FsError({ code: "NotFound", operation: "unlink", path: input });
+                    if (child.kind === "directory") {
+                        return yield* new FsError({ code: "IsDirectory", operation: "unlink", path: input });
+                    }
+                    if (path.trailingSlash) {
+                        return yield* new FsError({ code: "NotDirectory", operation: "unlink", path: input });
+                    }
+                    yield* authorizeRemoval(parent, child, "unlink", input);
+                    const now = yield* timestamp("unlink");
+                    parent.entries.delete(name);
+                    parent.metadata = { ...parent.metadata, mtimeNs: now, ctimeNs: now };
+                    advanceRevision(parent);
+                    detach(child, now);
+                    entries -= 1;
+                    publishEntry("Remove", parent, name);
+                }));
+            }),
+            rename: Effect.fn("Caller.rename")(function* (source, destination, options) {
+                const oldPrepared = preparePath(source, "rename", settings.maxPathBytes);
+                const newPrepared = preparePath(destination, "rename", settings.maxPathBytes);
+                const oldBase = options?.sourceRelativeTo;
+                const newBase = options?.destinationRelativeTo;
+                return yield* coordinated(Effect.gen(function* () {
+                    const oldPath = yield* Effect.fromResult(oldPrepared);
+                    const newPath = yield* Effect.fromResult(newPrepared);
+                    const oldParent = yield* locate(oldPath, oldBase, "rename", { parentOnly: true });
+                    const newParent = yield* locate(newPath, newBase, "rename", { parentOnly: true });
+                    yield* authorize(oldParent, identity, WRITE | EXECUTE, "rename", source);
+                    yield* authorize(newParent, identity, WRITE | EXECUTE, "rename", destination);
+                    const oldName = oldPath.components.at(-1);
+                    const newName = newPath.components.at(-1);
+                    if (isDotComponent(oldName) || isDotComponent(newName)) {
+                        return yield* new FsError({ code: "InvalidArgument", operation: "rename", path: source });
+                    }
+                    const child = oldParent.entries.get(oldName);
+                    if (child === undefined)
+                        return yield* new FsError({ code: "NotFound", operation: "rename", path: source });
+                    const replaced = newParent.entries.get(newName);
+                    if (newPath.trailingSlash && replaced === undefined) {
+                        return yield* new FsError({ code: "NotFound", operation: "rename", path: destination });
+                    }
+                    if (oldPath.trailingSlash && child.kind !== "directory") {
+                        return yield* new FsError({ code: "NotDirectory", operation: "rename", path: source });
+                    }
+                    if (newPath.trailingSlash && replaced?.kind !== "directory") {
+                        return yield* new FsError({ code: "NotDirectory", operation: "rename", path: destination });
+                    }
+                    if (child === replaced)
+                        return;
+                    yield* authorizeRemoval(oldParent, child, "rename", source);
+                    if (replaced !== undefined) {
+                        yield* authorizeRemoval(newParent, replaced, "rename", destination);
+                        if (child.kind === "directory" && replaced.kind !== "directory") {
+                            return yield* new FsError({ code: "NotDirectory", operation: "rename", path: destination });
+                        }
+                        if (child.kind !== "directory" && replaced.kind === "directory") {
+                            return yield* new FsError({ code: "IsDirectory", operation: "rename", path: destination });
+                        }
+                        if (replaced.kind === "directory" && replaced.entries.size > 0) {
+                            return yield* new FsError({ code: "NotEmpty", operation: "rename", path: destination });
+                        }
+                    }
+                    for (let ancestor = newParent; ancestor !== undefined; ancestor = ancestor.parent) {
+                        if (ancestor === child) {
+                            return yield* new FsError({ code: "InvalidArgument", operation: "rename", path: destination });
+                        }
+                    }
+                    const now = yield* timestamp("rename");
+                    // All rejection checks precede namespace, ancestry, quota, and metadata publication.
+                    const oldEvent = () => ownedPath(nameBytes(directoryHex(oldParent) + (oldParent === root ? "" : SLASH_HEX) + oldName));
+                    oldParent.entries.delete(oldName);
+                    newParent.entries.set(newName, child);
+                    if (child.kind === "directory")
+                        child.parent = newParent;
+                    oldParent.metadata = {
+                        ...oldParent.metadata,
+                        nlink: oldParent.metadata.nlink - (child.kind === "directory" ? 1 : 0),
+                        mtimeNs: now,
+                        ctimeNs: now
+                    };
+                    newParent.metadata = {
+                        ...newParent.metadata,
+                        nlink: newParent.metadata.nlink + (child.kind === "directory" && replaced === undefined ? 1 : 0),
+                        mtimeNs: now,
+                        ctimeNs: now
+                    };
+                    child.metadata = { ...child.metadata, ctimeNs: now };
+                    advanceRevision(oldParent);
+                    if (newParent !== oldParent)
+                        advanceRevision(newParent);
+                    advanceRevision(child);
+                    if (replaced !== undefined) {
+                        detach(replaced, now);
+                        entries -= 1;
+                    }
+                    watchHub.publishUnsafe(() => ({ _tag: "Remove", path: oldEvent() }));
+                    publishEntry("Create", newParent, newName);
+                }));
+            }),
+            rmdir: Effect.fn("Caller.rmdir")(function* (input, options) {
+                const prepared = preparePath(input, "rmdir", settings.maxPathBytes);
+                const base = options?.relativeTo;
+                return yield* coordinated(Effect.gen(function* () {
+                    const path = yield* Effect.fromResult(prepared);
+                    const parent = yield* locate(path, base, "rmdir", { parentOnly: true });
+                    yield* authorize(parent, identity, WRITE | EXECUTE, "rmdir", input);
+                    const name = path.components.at(-1);
+                    if (isDotComponent(name)) {
+                        return yield* new FsError({ code: "InvalidArgument", operation: "rmdir", path: input });
+                    }
+                    const child = parent.entries.get(name);
+                    if (child === undefined)
+                        return yield* new FsError({ code: "NotFound", operation: "rmdir", path: input });
+                    yield* authorizeRemoval(parent, child, "rmdir", input);
+                    if (child.kind !== "directory") {
+                        return yield* new FsError({ code: "NotDirectory", operation: "rmdir", path: input });
+                    }
+                    if (child.entries.size > 0)
+                        return yield* new FsError({ code: "NotEmpty", operation: "rmdir", path: input });
+                    const now = yield* timestamp("rmdir");
+                    parent.entries.delete(name);
+                    parent.metadata = { ...parent.metadata, nlink: parent.metadata.nlink - 1, mtimeNs: now, ctimeNs: now };
+                    child.parent = undefined;
+                    child.metadata = { ...child.metadata, nlink: 0, ctimeNs: now };
+                    advanceRevision(parent);
+                    advanceRevision(child);
+                    invalidateReference(child);
+                    entries -= 1;
+                    publishEntry("Remove", parent, name);
+                }));
+            }),
+            stat: Effect.fn("Caller.stat")(function* (input, options) {
+                const prepared = preparePath(input, "stat", settings.maxPathBytes);
+                const base = options?.relativeTo;
+                return yield* coordinated(Effect.gen(function* () {
+                    const path = yield* Effect.fromResult(prepared);
+                    const directory = yield* resolveNode(path, base, "stat");
+                    return { ...directory.metadata };
+                }));
+            }),
+            mkdir: Effect.fn("Caller.mkdir")(function* (input, options) {
+                const prepared = preparePath(input, "mkdir", settings.maxPathBytes);
+                const base = options?.relativeTo;
+                const mode = options?.mode === undefined ? 0o777 : options.mode;
+                if (!isMode(mode))
+                    return yield* new FsError({ code: "InvalidArgument", operation: "mkdir", path: input });
+                return yield* coordinated(Effect.gen(function* () {
+                    const path = yield* Effect.fromResult(prepared);
+                    const parent = yield* locate(path, base, "mkdir", { parentOnly: true });
+                    yield* authorize(parent, identity, WRITE | EXECUTE, "mkdir", input);
+                    const name = path.components.at(-1);
+                    if (isDotComponent(name) || parent.entries.has(name)) {
+                        return yield* new FsError({ code: "AlreadyExists", operation: "mkdir", path: input });
+                    }
+                    if (atEntryLimit()) {
+                        return yield* new FsError({ code: "NoSpace", operation: "mkdir", path: input });
+                    }
+                    const now = yield* timestamp("mkdir");
+                    const child = {
+                        kind: "directory",
+                        lineage: undefined,
+                        parent,
+                        entries: new Map(),
+                        metadata: directoryMetadata(nextInode, identity.uid, parent.metadata.gid, (mode & 0o777 & ~umask) | (mode & STICKY_BIT), now),
+                        revision: nextRevision(),
+                        objectReference: undefined
+                    };
+                    // No Effect yield or expected failure between these publication writes.
+                    attach(parent, name, child, now);
+                    nextInode += 1n;
+                    entries += 1;
+                    publishEntry("Create", parent, name);
+                }));
+            }),
+            withDirectory: Effect.fn("Caller.withDirectory")(function* (input, options) {
+                const acquired = yield* acquireDirectory(input, options, "withDirectory");
+                return createCaller(acquired, identity, umask);
+            }),
+            openDirectory: Effect.fn("Caller.openDirectory")(function* (input, options) {
+                const acquired = yield* acquireDirectory(input, options, "openDirectory");
+                const handle = Object.freeze({
+                    [DirectoryHandleId]: true,
+                    stat: coordinated(Effect.suspend(() => acquired.directory === undefined
+                        ? Effect.fail(new FsError({ code: "InvalidHandle", operation: "stat" }))
+                        : Effect.succeed({ ...acquired.directory.metadata }))).pipe(Effect.withSpan("DirectoryHandle.stat")),
+                    close: coordinated(Effect.suspend(() => {
+                        if (acquired.directory === undefined) {
+                            return Effect.fail(new FsError({ code: "InvalidHandle", operation: "close" }));
+                        }
+                        acquired.directory = undefined;
+                        acquired.closed = true;
+                        return Effect.void;
+                    })).pipe(Effect.withSpan("DirectoryHandle.close"))
+                });
+                handles.set(handle, acquired);
+                return handle;
+            })
+        });
+    };
+    const baseObservation = Predicate.isTagged("Overlay")(source) ? yield* observeChanges() : undefined;
+    const publicChange = (change) => Predicate.isTagged("Renamed")(change)
+        ? OverlayChange.make({ ...change, from: ownedPath(change.from), to: ownedPath(change.to) })
+        : OverlayChange.make({ ...change, path: ownedPath(change.path) });
+    const publicChanges = (changes) => Object.freeze(changes.map(publicChange));
+    const changeOptions = (options) => {
+        const decoded = decodeConfiguration(OverlayChangesOptions, options === undefined ? {} : options);
+        return Result.isFailure(decoded) ? Effect.fail(decoded.failure) : Effect.succeed(decoded.success);
+    };
+    // An overlay is a spread copy of `volume`, so the object the caller holds is not always the one
+    // built here. `watch` runs lazily, so it reads whichever surface was actually handed out.
+    let surface;
+    const volume = Object.freeze({
+        [VolumeId]: true,
+        watch: Effect.gen(function* () {
+            const hook = TestHooks.getRegistrationHook(surface);
+            return yield* watchHub.subscribe(hook?.afterSubscribe);
+        }).pipe(Effect.withSpan("Volume.watch")),
+        snapshot: coordinatedRead(captureSnapshot()).pipe(Effect.withSpan("Volume.snapshot")),
+        caller: Effect.fn("Volume.caller")(function* (options) {
+            const decoded = decodeConfiguration(RootCallerOptions, options === undefined ? {} : options);
+            if (Result.isFailure(decoded))
+                return yield* decoded.failure;
+            const chosen = decoded.success.identity ?? { uid: 0, gid: 0, groups: [], privileged: true };
+            const identity = Object.freeze({ ...chosen, groups: Object.freeze([...chosen.groups]) });
+            return createCaller({ volume: volumeIdentity, directory: root, closed: false }, identity, decoded.success.umask ?? 0o022);
+        })
+    });
+    surface = volume;
+    if (!Predicate.isTagged("Overlay")(source) || baseObservation === undefined) {
+        // SAFETY: Overlay sources return below, so S is non-Overlay here and VolumeFor<S> is Volume.
+        return volume;
+    }
+    const hook = TestHooks.getObservationHook(source.base);
+    const overlay = Object.freeze({
+        ...volume,
+        changes: Effect.fn("OverlayVolume.changes")(function* (options) {
+            const selected = yield* changeOptions(options);
+            const current = yield* coordinatedRead(observeChanges());
+            return publicChanges(compareOverlay(baseObservation, current, selected.includeTimestamps ?? false));
+        }),
+        capture: Effect.fn("OverlayVolume.capture")(function* (options) {
+            const selected = yield* changeOptions(options);
+            const current = yield* coordinatedRead(captureState(hook));
+            return Object.freeze({
+                snapshot: current.snapshot,
+                changes: publicChanges(compareOverlay(baseObservation, current.observation, selected.includeTimestamps ?? false))
+            });
+        })
+    });
+    surface = overlay;
+    return overlay;
+});
+/** @internal */
+export const make = Effect.fn("VirtualFileSystem.make")(function* (options) {
+    return yield* makeVolume(VolumeSource.Empty(), options).pipe(Effect.catchTag("ImageError", Effect.die));
+});
+/** @internal */
+export const fromSnapshot = Effect.fn("VirtualFileSystem.fromSnapshot")(function* (snapshot, options) {
+    const image = yield* Image.inspect(snapshot);
+    return yield* makeVolume(VolumeSource.Snapshot({ image }), options);
+});
+/** @internal */
+export const makeOverlay = Effect.fn("VirtualFileSystem.makeOverlay")(function* (base, options) {
+    const image = yield* Image.inspect(base);
+    return yield* makeVolume(VolumeSource.Overlay({ base, image }), options);
+});