@effect-vfs/core 0.0.1 → 0.2.0

package/dist/VirtualFileSystem.js

@@ -8,6 +8,7 @@
  *
  * @since 0.1.0
  */
+import * as ByteSize from "effect/ByteSize";
 import * as Clock from "effect/Clock";
 import * as Context from "effect/Context";
 import { DecodeLimits, ImageError } from "./Snapshot.js";
@@ -18,11 +19,20 @@ import * as Encoding from "effect/Encoding";
 import * as PubSub from "effect/PubSub";
 import * as Result from "effect/Result";
 import * as Schema from "effect/Schema";
+import * as SchemaIssue from "effect/SchemaIssue";
+import * as SchemaTransformation from "effect/SchemaTransformation";
 import * as Scope from "effect/Scope";
 import * as Semaphore from "effect/Semaphore";
 import * as Stream from "effect/Stream";
+import { BytePath, getBytes as getBytePathBytes, make as makeBytePath } from "./BytePath.js";
+export { BytePath } from "./BytePath.js";
+import * as Content from "./internal/content.js";
 import * as Image from "./internal/image.js";
-const BytePathId = Symbol("@effect-vfs/core/BytePath");
+import { compareOverlay } from "./internal/overlayChanges.js";
+import * as OverlayTesting from "./internal/overlayTesting.js";
+import * as SnapshotDeltaInternal from "./internal/snapshotDelta.js";
+import * as SnapshotDeltaModel from "./SnapshotDelta.js";
+export { SnapshotChange, SnapshotChangesOptions, SnapshotDeltaError, SnapshotDeltaLimits, SnapshotDeltaTypeId, SnapshotDifference, SnapshotNodeKind } from "./SnapshotDelta.js";
 const VolumeId = Symbol("@effect-vfs/core/Volume");
 const CallerId = Symbol("@effect-vfs/core/Caller");
 const FileHandleId = Symbol("@effect-vfs/core/FileHandle");
@@ -108,11 +118,11 @@ export const VolumeOptions = Schema.Struct({
     /** Maximum number of filesystem nodes. Omission leaves the count unbounded. */
     maxEntries: Schema.optionalKey(Natural),
     /** Maximum combined regular-file content in bytes. */
-    maxBytes: Schema.optionalKey(Natural),
+    maxBytes: Schema.optionalKey(Schema.ByteSize),
     /** Maximum content size of one regular file in bytes. */
-    maxFileBytes: Schema.optionalKey(Natural.check(Schema.isLessThanOrEqualTo(0xffffffff))),
+    maxFileBytes: Schema.optionalKey(Schema.ByteSize.check(Schema.makeFilter((size) => ByteSize.isLessThanOrEqualTo(size, ByteSize.bytes(0xffffffff)) ? undefined : "must be at most 4294967295 bytes"))),
     /** Maximum encoded byte length of an absolute or relative path. */
-    maxPathBytes: Schema.optionalKey(Natural.check(Schema.isGreaterThanOrEqualTo(1)))
+    maxPathBytes: Schema.optionalKey(Schema.ByteSize.check(Schema.makeFilter((size) => ByteSize.isGreaterThanOrEqualTo(size, ByteSize.bytes(1)) ? undefined : "must be at least 1 byte")))
 });
 // Match snapshot v1's canonical signed decimal timestamp domain.
 const timestampLimit = 10n ** 128n - 1n;
@@ -195,6 +205,69 @@ const WriteFileSettings = Schema.Struct({
     /** Mode to apply after replacing an existing file. */
     finalMode: Schema.optionalKey(Mode)
 });
+/**
+ * Schema for the filesystem entry kinds reported by overlay summaries.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const OverlayNodeKind = Schema.Literals(["directory", "file", "symlink"]);
+/**
+ * Schema for observable fields that can differ from an overlay's immutable base.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+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));
+/**
+ * Schema for a final-state overlay difference.
+ *
+ * **Details**
+ *
+ * Paths retain arbitrary non-NUL bytes. Renames are reported only when retained
+ * base identity makes the removed and added names unambiguous.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+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 })
+]);
+/**
+ * Schema for overlay summary filtering.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const OverlayChangesOptions = Schema.Struct({
+    /** Include access, modification, change, and birth-time differences. Defaults to `false`. */
+    includeTimestamps: Schema.optionalKey(Schema.Boolean)
+});
 /**
  * Optional Effect service for providing an existing filesystem caller.
  *
@@ -217,22 +290,66 @@ export const encodeSnapshot = Image.encodeSnapshot;
  * @since 0.1.0
  */
 export const decodeSnapshot = Image.decodeSnapshot;
-const bytePaths = new WeakMap();
+const deltaLimits = (limits) => {
+    const decoded = decodeConfiguration(SnapshotDeltaModel.SnapshotDeltaLimits, limits ?? SnapshotDeltaModel.SnapshotDeltaLimits.default);
+    return Result.isFailure(decoded) ? Effect.fail(decoded.failure) : Effect.succeed(decoded.success);
+};
+/**
+ * Computes an exact portable delta between two immutable snapshots.
+ * Requires the platform-neutral `Crypto.Crypto` service for base identity.
+ *
+ * @category snapshots
+ * @since 0.1.0
+ */
+export const diffSnapshots = Effect.fn("VirtualFileSystem.diffSnapshots")(function* (base, target, limits) {
+    return yield* SnapshotDeltaInternal.diffSnapshots(base, target, yield* deltaLimits(limits));
+});
+/**
+ * Verifies an exact snapshot delta against its base and derives an owned path-oriented summary.
+ * Requires the platform-neutral `Crypto.Crypto` service for base identity.
+ */
+export const inspectSnapshotDelta = Effect.fn("VirtualFileSystem.inspectSnapshotDelta")(function* (base, delta, options, limits) {
+    const decoded = decodeConfiguration(SnapshotDeltaModel.SnapshotChangesOptions, options ?? {});
+    if (Result.isFailure(decoded))
+        return yield* decoded.failure;
+    return yield* SnapshotDeltaInternal.inspectSnapshotDelta(base, delta, decoded.success, yield* deltaLimits(limits));
+});
+/**
+ * Applies an exact delta to its semantically matching base and returns a new snapshot.
+ * Requires the platform-neutral `Crypto.Crypto` service for base identity.
+ *
+ * @category snapshots
+ * @since 0.1.0
+ */
+export const applySnapshotDelta = Effect.fn("VirtualFileSystem.applySnapshotDelta")(function* (base, delta, limits) {
+    return yield* SnapshotDeltaInternal.applySnapshotDelta(base, delta, yield* deltaLimits(limits));
+});
+const deltaSchemaIssue = (cause, input, options) => new SchemaIssue.InvalidValue({ message: `Snapshot delta ${cause.code}${cause.field === undefined ? "" : ` at ${cause.field}`}` }, input, options);
+/**
+ * Creates an Effect Schema codec between owned bytes and opaque snapshot deltas.
+ * Omission uses `SnapshotDeltaLimits.default`.
+ */
+export const SnapshotDeltaFromBytes = (limits) => {
+    const selected = Schema.decodeResult(SnapshotDeltaModel.SnapshotDeltaLimits, { onExcessProperty: "error" })(limits ?? SnapshotDeltaModel.SnapshotDeltaLimits.default);
+    return Schema.Uint8Array.pipe(Schema.decodeTo(SnapshotDeltaModel.SnapshotDelta, SchemaTransformation.transformEffect({
+        decode: (input, options) => Result.isFailure(selected)
+            ? Effect.fail(new SchemaIssue.InvalidValue({ message: "Invalid snapshot delta limits" }, limits, options))
+            : SnapshotDeltaInternal.decodeSnapshotDelta(input, selected.success).pipe(Effect.mapError((cause) => deltaSchemaIssue(cause, input, options))),
+        encode: (delta, options) => Result.isFailure(selected)
+            ? Effect.fail(new SchemaIssue.InvalidValue({ message: "Invalid snapshot delta limits" }, limits, options))
+            : SnapshotDeltaInternal.encodeSnapshotDelta(delta, selected.success).pipe(Effect.mapError((cause) => deltaSchemaIssue(cause, delta, options)))
+    })));
+};
 const failure = (code, operation, path) => new FsError({ code, operation, ...(path === undefined ? {} : { path }) });
 const ownedPath = (bytes) => {
-    const path = Object.freeze({ [BytePathId]: true });
-    bytePaths.set(path, bytes);
-    return path;
+    return makeBytePath(bytes);
 };
 const strictString = (bytes, operation) => Effect.try({
     try: () => new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes),
     catch: () => failure("UnrepresentableName", operation)
 });
 const nameBytes = (name) => {
-    const bytes = new Uint8Array(name.length / 2);
-    for (let i = 0; i < bytes.length; i++)
-        bytes[i] = Number.parseInt(name.slice(i * 2, i * 2 + 2), 16);
-    return bytes;
+    return Result.getOrThrow(Encoding.decodeHex(name));
 };
 // A zero-length view distinguishes a detached buffer from a valid empty buffer.
 const attachedBuffer = (bytes) => {
@@ -265,9 +382,7 @@ export const pathFromBytes = Effect.fn("VirtualFileSystem.pathFromBytes")(functi
     const owned = new Uint8Array(bytes);
     if (owned.length === 0 || owned.includes(0))
         return yield* failure("InvalidArgument", "pathFromBytes");
-    const path = Object.freeze({ [BytePathId]: true });
-    bytePaths.set(path, owned);
-    return path;
+    return makeBytePath(owned);
 });
 /**
  * Copies the bytes held by an opaque byte path.
@@ -276,7 +391,7 @@ export const pathFromBytes = Effect.fn("VirtualFileSystem.pathFromBytes")(functi
  * @since 0.1.0
  */
 export const pathToBytes = Effect.fn("VirtualFileSystem.pathToBytes")(function* (path) {
-    const bytes = bytePaths.get(path);
+    const bytes = getBytePathBytes(path);
     if (bytes === undefined)
         return yield* failure("InvalidArgument", "pathToBytes");
     return new Uint8Array(bytes);
@@ -304,7 +419,7 @@ const preparePath = (input, operation, maxPathBytes) => {
         bytes = new TextEncoder().encode(input);
     }
     else if (typeof input === "object" && input !== null) {
-        bytes = bytePaths.get(input);
+        bytes = getBytePathBytes(input);
     }
     if (bytes === undefined)
         return Result.fail(failure("InvalidArgument", operation));
@@ -312,7 +427,7 @@ const preparePath = (input, operation, maxPathBytes) => {
         return Result.fail(failure("NotFound", operation, input));
     if (bytes.includes(0))
         return Result.fail(failure("InvalidArgument", operation, input));
-    if (maxPathBytes !== undefined && bytes.length > maxPathBytes) {
+    if (maxPathBytes !== undefined && ByteSize.isGreaterThan(ByteSize.bytes(bytes.length), maxPathBytes)) {
         return Result.fail(failure("PathTooLong", operation, input));
     }
     const components = [];
@@ -370,7 +485,8 @@ const storedMetadata = (metadata) => ({
     birthtimeNs: String(metadata.birthtimeNs)
 });
 /** Each execution constructs a fresh volume and captures its Clock. */
-const makeVolume = Effect.fn("VirtualFileSystem.makeVolume")(function* (options, image) {
+const makeVolume = Effect.fn("VirtualFileSystem.makeVolume")(function* (source, options) {
+    const image = source._tag === "Empty" ? undefined : source.image;
     const decoded = decodeConfiguration(VolumeOptions, options === undefined ? {} : options);
     if (Result.isFailure(decoded))
         return yield* decoded.failure;
@@ -388,17 +504,19 @@ const makeVolume = Effect.fn("VirtualFileSystem.makeVolume")(function* (options,
     const gate = Semaphore.makeUnsafe(1);
     const root = {
         kind: "directory",
+        lineage: image?.root,
         parent: undefined,
         entries: new Map(),
         metadata: directoryMetadata(1n, 0, 0, 0o755, initialTime)
     };
     let nextInode = 2n;
     let entries = 0;
-    let usedBytes = 0;
-    const maxFileBytes = settings.maxFileBytes ?? 0xffffffff;
+    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)));
     if (image !== undefined) {
         const incoming = new Map();
-        let content = 0;
+        let content = 0n;
         let count = 0;
         for (const record of image.records) {
             if (record.kind === "directory")
@@ -408,13 +526,14 @@ const makeVolume = Effect.fn("VirtualFileSystem.makeVolume")(function* (options,
                 if (record.kind === "file" && length > maxFileBytes) {
                     return yield* new ImageError({ code: "LimitExceeded", field: "maxFileBytes" });
                 }
-                content += length;
+                content += BigInt(length);
             }
         }
         if ((settings.maxEntries !== undefined && count > settings.maxEntries) ||
-            (settings.maxBytes !== undefined && content > settings.maxBytes)) {
+            (settings.maxBytes !== undefined && content > ByteSize.toBigInt(settings.maxBytes))) {
             return yield* new ImageError({ code: "LimitExceeded", field: "volume" });
         }
+        const baseContents = source._tag === "Overlay" ? Content.forOverlay(source.base, image) : undefined;
         for (const record of image.records) {
             const metadata = {
                 ...record.metadata,
@@ -430,22 +549,28 @@ const makeVolume = Effect.fn("VirtualFileSystem.makeVolume")(function* (options,
             if (record.kind === "directory") {
                 const node = record.id === image.root
                     ? root
-                    : { kind: "directory", parent: undefined, entries: new Map(), metadata };
+                    : { kind: "directory", lineage: record.id, parent: undefined, entries: new Map(), metadata };
                 node.metadata = metadata;
                 incoming.set(record.id, node);
             }
             else if (record.kind === "file") {
-                const data = Image.bytes(record.data);
+                const data = baseContents?.get(record.id) ?? Content.make(Image.bytes(record.data));
                 incoming.set(record.id, {
                     kind: "file",
+                    lineage: record.id,
                     data,
                     openCount: 0,
-                    metadata: { ...metadata, size: BigInt(data.length) }
+                    metadata: { ...metadata, size: BigInt(data.bytes.length) }
                 });
             }
             else {
                 const target = Image.bytes(record.target);
-                incoming.set(record.id, { kind: "symlink", target, metadata: { ...metadata, size: BigInt(target.length) } });
+                incoming.set(record.id, {
+                    kind: "symlink",
+                    lineage: record.id,
+                    target,
+                    metadata: { ...metadata, size: BigInt(target.length) }
+                });
             }
         }
         for (const record of image.records) {
@@ -513,6 +638,75 @@ const makeVolume = Effect.fn("VirtualFileSystem.makeVolume")(function* (options,
             }
         }
     };
+    const captureSnapshot = Effect.fnUntraced(function* () {
+        const ids = new Map([[root, "0"]]);
+        const pending = [root];
+        const records = [];
+        for (let index = 0; index < pending.length; index++) {
+            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: Image.base64(nameBytes(name)), target });
+                }
+                records.push({ id, kind: "directory", metadata, entries: children });
+            }
+            else if (node.kind === "file") {
+                records.push({ id, kind: "file", metadata, data: Image.base64(node.data.bytes) });
+            }
+            else
+                records.push({ id, kind: "symlink", metadata, target: Image.base64(node.target) });
+        }
+        return yield* Image.capture({ format: "effect-vfs", version: 1, root: "0", records });
+    });
+    const observeChanges = () => {
+        const observation = [];
+        const paths = [[root, new Uint8Array([47])]];
+        for (let index = 0; index < paths.length; index++) {
+            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++] = 47;
+                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: observeChanges() };
+    });
     // Permit waits stay interruptible. State transitions and resource registration do not.
     const coordinated = (effect) => gate.withPermit(Effect.uninterruptible(effect));
     const release = (reference) => coordinated(Effect.sync(() => {
@@ -534,8 +728,8 @@ const makeVolume = Effect.fn("VirtualFileSystem.makeVolume")(function* (options,
     };
     const reclaim = (file) => {
         if (file.metadata.nlink === 0 && file.openCount === 0) {
-            usedBytes -= file.data.length;
-            file.data = new Uint8Array(0);
+            usedBytes -= BigInt(file.data.bytes.length);
+            file.data = Content.empty();
         }
     };
     const detach = (node, now) => {
@@ -548,7 +742,7 @@ const makeVolume = Effect.fn("VirtualFileSystem.makeVolume")(function* (options,
             if (node.kind === "file")
                 reclaim(node);
             else if (node.metadata.nlink === 0)
-                usedBytes -= node.target.length;
+                usedBytes -= BigInt(node.target.length);
         }
     };
     const releaseFile = (ref) => {
@@ -565,14 +759,15 @@ const makeVolume = Effect.fn("VirtualFileSystem.makeVolume")(function* (options,
         if (length > BigInt(maxFileBytes))
             return yield* failure("FileTooLarge", operation);
         const size = Number(length);
-        if (size - file.data.length > (settings.maxBytes ?? Number.MAX_SAFE_INTEGER) - usedBytes) {
+        if (settings.maxBytes !== undefined &&
+            BigInt(size - file.data.bytes.length) > ByteSize.toBigInt(settings.maxBytes) - usedBytes) {
             return yield* failure("NoSpace", operation);
         }
         const data = new Uint8Array(size);
-        data.set(file.data.subarray(0, size));
+        data.set(file.data.bytes.subarray(0, size));
         const now = yield* timestamp(operation);
-        usedBytes += size - file.data.length;
-        file.data = data;
+        usedBytes += BigInt(size - file.data.bytes.length);
+        file.data = Content.make(data);
         file.metadata = {
             ...file.metadata,
             size: length,
@@ -596,7 +791,7 @@ const makeVolume = Effect.fn("VirtualFileSystem.makeVolume")(function* (options,
                 return yield* failure("InvalidArgument", "read");
             }
             const start = Number(offset > file.metadata.size ? file.metadata.size : offset);
-            const data = file.data.slice(start, start + Math.min(maximum, file.data.length - start));
+            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")) };
             }
@@ -621,19 +816,23 @@ const makeVolume = Effect.fn("VirtualFileSystem.makeVolume")(function* (options,
                 if (offset >= BigInt(maxFileBytes))
                     return yield* failure("FileTooLarge", "write");
                 const start = Number(offset);
-                const free = (settings.maxBytes ?? Number.MAX_SAFE_INTEGER) - usedBytes;
-                const end = Math.min(maxFileBytes, file.data.length + free);
+                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* failure("NoSpace", "write");
-                const size = Math.max(file.data.length, start + count);
-                const data = size === file.data.length ? file.data : new Uint8Array(size);
-                if (data !== file.data)
-                    data.set(file.data);
+                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);
-                usedBytes += size - file.data.length;
-                file.data = data;
+                usedBytes += BigInt(size - file.data.bytes.length);
+                file.data = Content.make(data);
                 file.metadata = {
                     ...file.metadata,
                     size: BigInt(size),
@@ -750,7 +949,8 @@ const makeVolume = Effect.fn("VirtualFileSystem.makeVolume")(function* (options,
                     if (++traversals > 40)
                         return yield* failure("SymlinkLoop", operation, path.input);
                     const suffix = work.suffixes[index] ?? new Uint8Array(0);
-                    if (settings.maxPathBytes !== undefined && child.target.length + suffix.length > settings.maxPathBytes) {
+                    if (settings.maxPathBytes !== undefined &&
+                        ByteSize.isGreaterThan(ByteSize.bytes(child.target.length + suffix.length), settings.maxPathBytes)) {
                         return yield* failure("PathTooLong", operation, path.input);
                     }
                     const expansion = new Uint8Array(child.target.length + suffix.length);
@@ -958,7 +1158,7 @@ const makeVolume = Effect.fn("VirtualFileSystem.makeVolume")(function* (options,
                     if (node.kind !== "file")
                         return yield* failure("IsDirectory", "readFile", input);
                     yield* authorize(node, identity, 4, "readFile", input);
-                    const data = new Uint8Array(node.data);
+                    const data = new Uint8Array(node.data.bytes);
                     node.metadata = { ...node.metadata, atimeNs: (yield* timestamp("readFile")) };
                     return data;
                 }));
@@ -1009,14 +1209,15 @@ const makeVolume = Effect.fn("VirtualFileSystem.makeVolume")(function* (options,
                     else
                         yield* authorize(file, identity, chosen.access === "readWrite" ? 6 : 2, "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.length ?? 0;
+                    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* failure("FileTooLarge", "writeFile", input);
                     const reclaimed = replaced !== undefined && replaced.metadata.nlink === 1 ? replaced.target.length : 0;
-                    if (size - previous > (settings.maxBytes ?? Number.MAX_SAFE_INTEGER) - usedBytes + reclaimed) {
+                    if (settings.maxBytes !== undefined &&
+                        BigInt(size - previous) > ByteSize.toBigInt(settings.maxBytes) - usedBytes + BigInt(reclaimed)) {
                         return yield* failure("NoSpace", "writeFile", input);
                     }
                     if (file !== undefined && !chosen.truncate && captured.length === 0 && chosen.finalMode === undefined) {
@@ -1026,14 +1227,15 @@ const makeVolume = Effect.fn("VirtualFileSystem.makeVolume")(function* (options,
                     if (position !== 0 || size !== captured.length) {
                         data = new Uint8Array(size);
                         if (file !== undefined && !chosen.truncate)
-                            data.set(file.data);
+                            data.set(file.data.bytes);
                         data.set(captured, position);
                     }
                     const now = yield* timestamp("writeFile");
                     const node = file ??
                         {
                             kind: "file",
-                            data,
+                            lineage: undefined,
+                            data: Content.make(data),
                             openCount: 0,
                             metadata: {
                                 ...directoryMetadata(nextInode++, identity.uid, parent.metadata.gid, (chosen.mode ?? 0o666) & 0o777 & ~umask, now),
@@ -1041,7 +1243,7 @@ const makeVolume = Effect.fn("VirtualFileSystem.makeVolume")(function* (options,
                                 nlink: 1
                             }
                         };
-                    node.data = data;
+                    node.data = Content.make(data);
                     node.metadata = {
                         ...node.metadata,
                         mode: finalMode ?? node.metadata.mode & ~0o6000,
@@ -1049,7 +1251,7 @@ const makeVolume = Effect.fn("VirtualFileSystem.makeVolume")(function* (options,
                         mtimeNs: now,
                         ctimeNs: now
                     };
-                    usedBytes += size - previous;
+                    usedBytes += BigInt(size - previous);
                     if (file === undefined) {
                         if (replaced !== undefined)
                             detach(replaced, now);
@@ -1152,7 +1354,7 @@ const makeVolume = Effect.fn("VirtualFileSystem.makeVolume")(function* (options,
                 if (typeof target === "string" && !wellFormed(target)) {
                     return yield* failure("InvalidPathEncoding", "symlink", target);
                 }
-                const rawTarget = typeof target === "string" ? new TextEncoder().encode(target) : bytePaths.get(target);
+                const rawTarget = typeof target === "string" ? new TextEncoder().encode(target) : getBytePathBytes(target);
                 if (rawTarget === undefined || rawTarget.includes(0)) {
                     return yield* failure("InvalidArgument", "symlink", target);
                 }
@@ -1170,11 +1372,13 @@ const makeVolume = Effect.fn("VirtualFileSystem.makeVolume")(function* (options,
                     if (path.trailingSlash)
                         return yield* failure("NotDirectory", "symlink", input);
                     if ((settings.maxEntries !== undefined && entries >= settings.maxEntries) ||
-                        bytes.length > (settings.maxBytes ?? Number.MAX_SAFE_INTEGER) - usedBytes)
+                        (settings.maxBytes !== undefined &&
+                            BigInt(bytes.length) > ByteSize.toBigInt(settings.maxBytes) - usedBytes))
                         return yield* failure("NoSpace", "symlink", 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),
@@ -1187,7 +1391,7 @@ const makeVolume = Effect.fn("VirtualFileSystem.makeVolume")(function* (options,
                     parent.metadata = { ...parent.metadata, mtimeNs: now, ctimeNs: now };
                     nextInode += 1n;
                     entries += 1;
-                    usedBytes += bytes.length;
+                    usedBytes += BigInt(bytes.length);
                     publishEntry("Create", parent, name);
                 }));
             }),
@@ -1269,7 +1473,8 @@ const makeVolume = Effect.fn("VirtualFileSystem.makeVolume")(function* (options,
                         const now = yield* timestamp("open");
                         file = {
                             kind: "file",
-                            data: new Uint8Array(0),
+                            lineage: undefined,
+                            data: Content.empty(),
                             openCount: 0,
                             metadata: {
                                 ...directoryMetadata(nextInode, identity.uid, parent.metadata.gid, (chosen.mode ?? 0o666) & 0o777 & ~umask, now),
@@ -1464,6 +1669,7 @@ const makeVolume = Effect.fn("VirtualFileSystem.makeVolume")(function* (options,
                     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 & 0o1000), now)
@@ -1506,6 +1712,28 @@ const makeVolume = Effect.fn("VirtualFileSystem.makeVolume")(function* (options,
             })
         });
     };
+    const baseObservation = source._tag === "Overlay" ? observeChanges() : undefined;
+    const publicChange = (change) => {
+        switch (change._tag) {
+            case "Added":
+            case "Removed":
+            case "Updated":
+            case "Replaced":
+                return Object.freeze({ ...change, path: ownedPath(new Uint8Array(change.path)) });
+            case "Renamed":
+                return Object.freeze({
+                    ...change,
+                    from: ownedPath(new Uint8Array(change.from)),
+                    to: ownedPath(new Uint8Array(change.to))
+                });
+        }
+        throw new Error("Unknown internal overlay change");
+    };
+    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);
+    };
     const volume = Object.freeze({
         [VolumeId]: true,
         watch: Effect.gen(function* () {
@@ -1516,39 +1744,7 @@ const makeVolume = Effect.fn("VirtualFileSystem.makeVolume")(function* (options,
             }));
             return Stream.fromEffectRepeat(PubSub.take(subscription));
         }).pipe(Effect.withSpan("Volume.watch")),
-        snapshot: coordinated(Effect.gen(function* () {
-            const ids = new Map([[root, "0"]]);
-            const pending = [root];
-            const records = [];
-            for (let index = 0; index < pending.length; index++) {
-                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: Image.base64(nameBytes(name)), target });
-                    }
-                    records.push({ id, kind: "directory", metadata, entries: children });
-                }
-                else if (node.kind === "file") {
-                    records.push({ id, kind: "file", metadata, data: Image.base64(node.data) });
-                }
-                else
-                    records.push({ id, kind: "symlink", metadata, target: Image.base64(node.target) });
-            }
-            return yield* Image.capture({ format: "effect-vfs", version: 1, root: "0", records });
-        })).pipe(Effect.withSpan("Volume.snapshot")),
+        snapshot: coordinated(captureSnapshot()).pipe(Effect.withSpan("Volume.snapshot")),
         caller: Effect.fn("Volume.caller")(function* (options) {
             const decoded = decodeConfiguration(RootCallerOptions, options === undefined ? {} : options);
             if (Result.isFailure(decoded))
@@ -1558,7 +1754,27 @@ const makeVolume = Effect.fn("VirtualFileSystem.makeVolume")(function* (options,
             return createCaller({ volume: volumeIdentity, directory: root, closed: false }, identity, decoded.success.umask ?? 0o022);
         })
     });
-    return volume;
+    if (source._tag !== "Overlay" || baseObservation === undefined) {
+        return { _tag: "Volume", volume };
+    }
+    const hook = OverlayTesting.getObservationHook(source.base);
+    const overlay = Object.freeze({
+        ...volume,
+        changes: Effect.fn("OverlayVolume.changes")(function* (options) {
+            const selected = yield* changeOptions(options);
+            const current = yield* coordinated(Effect.sync(observeChanges));
+            return publicChanges(compareOverlay(baseObservation, current, selected.includeTimestamps ?? false));
+        }),
+        capture: Effect.fn("OverlayVolume.capture")(function* (options) {
+            const selected = yield* changeOptions(options);
+            const current = yield* coordinated(captureState(hook));
+            return Object.freeze({
+                snapshot: current.snapshot,
+                changes: publicChanges(compareOverlay(baseObservation, current.observation, selected.includeTimestamps ?? false))
+            });
+        })
+    });
+    return { _tag: "Overlay", volume: overlay };
 });
 /**
  * Creates a fresh empty volume and captures the current Effect `Clock`.
@@ -1572,7 +1788,10 @@ const makeVolume = Effect.fn("VirtualFileSystem.makeVolume")(function* (options,
  * @since 0.1.0
  */
 export const make = Effect.fn("VirtualFileSystem.make")(function* (options) {
-    return yield* makeVolume(options).pipe(Effect.catchTag("ImageError", Effect.die));
+    const result = yield* makeVolume({ _tag: "Empty" }, options).pipe(Effect.catchTag("ImageError", Effect.die));
+    if (result._tag === "Overlay")
+        return yield* Effect.die(new Error("empty volume constructed as overlay"));
+    return result.volume;
 });
 /**
  * Restores a fresh volume from an opaque snapshot under the supplied destination limits.
@@ -1582,7 +1801,33 @@ export const make = Effect.fn("VirtualFileSystem.make")(function* (options) {
  */
 export const fromSnapshot = Effect.fn("VirtualFileSystem.fromSnapshot")(function* (snapshot, options) {
     const image = yield* Image.inspect(snapshot);
-    return yield* makeVolume(options, image);
+    const result = yield* makeVolume({ _tag: "Snapshot", image }, options);
+    if (result._tag === "Overlay")
+        return yield* new ImageError({ code: "InvalidStructure" });
+    return result.volume;
+});
+/**
+ * Creates an isolated writable volume relative to one immutable snapshot base.
+ *
+ * **Details**
+ *
+ * Workspaces made from the same snapshot share unchanged regular-file payloads.
+ * The first content mutation copies the whole file into workspace-private
+ * storage. Metadata, namespace state, coordination, handles, and watches are
+ * always private to the new workspace.
+ *
+ * Invalid base snapshots fail with `ImageError`; invalid volume limits fail
+ * with `ConfigurationError`. Each execution creates a fresh workspace.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export const makeOverlay = Effect.fn("VirtualFileSystem.makeOverlay")(function* (base, options) {
+    const image = yield* Image.inspect(base);
+    const result = yield* makeVolume({ _tag: "Overlay", base, image }, options);
+    if (result._tag === "Volume")
+        return yield* new ImageError({ code: "InvalidStructure" });
+    return result.volume;
 });
 const FixtureMetadata = Schema.Struct({
     uid: Schema.optionalKey(Natural),
@@ -1595,7 +1840,7 @@ const FixtureMetadata = Schema.Struct({
 });
 const FixturePath = Schema.Union([
     Schema.String,
-    Schema.declare((value) => typeof value === "object" && value !== null && BytePathId in value && value[BytePathId] === true)
+    BytePath
 ]);
 /**
  * Schema for a complete fixture namespace with optional metadata and forward hard links.
@@ -1713,7 +1958,7 @@ export const fromFixture = Effect.fn("VirtualFileSystem.fromFixture")(function*
             }
             const target = typeof entry.target === "string"
                 ? new TextEncoder().encode(entry.target)
-                : bytePaths.get(entry.target);
+                : getBytePathBytes(entry.target);
             if (target === undefined || target.includes(0)) {
                 return yield* new ImageError({
                     code: "InvalidStructure",
@@ -1764,5 +2009,9 @@ export const fromFixture = Effect.fn("VirtualFileSystem.fromFixture")(function*
     }
     const records = [...new Set(declarations.values())].map((record) => record.kind === "directory" ? { ...record, entries: children.get(record.id) ?? [] } : record);
     const snapshot = yield* Image.capture({ format: "effect-vfs", version: 1, root: "root", records });
-    return yield* makeVolume(config.success, yield* Image.inspect(snapshot));
+    const image = yield* Image.inspect(snapshot);
+    const result = yield* makeVolume({ _tag: "Snapshot", image }, config.success);
+    if (result._tag === "Overlay")
+        return yield* new ImageError({ code: "InvalidStructure" });
+    return result.volume;
 });