@effect-vfs/core 0.2.0 → 0.3.1

package/dist/internal/snapshotDelta.js

@@ -1,22 +1,34 @@
-/** Exact snapshot delta construction, inspection, serialization, and application. @internal */
+// Exact snapshot delta construction, inspection, serialization, and application.
 import * as ByteSize from "effect/ByteSize";
 import * as Crypto from "effect/Crypto";
 import * as Effect from "effect/Effect";
 import * as Encoding from "effect/Encoding";
-import * as Equal from "effect/Equal";
+import * as Fn from "effect/Function";
+import * as Match from "effect/Match";
+import * as Predicate from "effect/Predicate";
 import * as Result from "effect/Result";
 import * as Schema from "effect/Schema";
-import { make as makeBytePath } from "../BytePath.js";
 import { ImageError } from "../Snapshot.js";
-import { makeSnapshotDelta, SnapshotDeltaError, snapshotDeltaValue } from "../SnapshotDelta.js";
-import * as CanonicalBase64 from "./canonicalBase64.js";
+import { SnapshotDeltaError, SnapshotDifference, SnapshotNodeKind } from "../SnapshotDelta.js";
+import { make as makeBytePath } from "./bytePath.js";
+import { bytesOrder, sameBytes } from "./bytes.js";
+import { CanonicalBase64 } from "./canonicalBase64.js";
 import * as Image from "./image.js";
-const Path = Schema.String;
-const Payload = Schema.Union([
-    Schema.TaggedStruct("Inline", { bytes: Schema.String }),
-    Schema.TaggedStruct("Base", { path: Path })
-]);
-const Record = Schema.Union([
+import { WireStoredMetadata } from "./metadata.js";
+import * as SnapshotDeltaModel from "./snapshotDeltaModel.js";
+const FORMAT = "effect-vfs-delta";
+const ALGORITHM = "effect-vfs-semantic-sha256-v1";
+const SLASH_BYTE = 47;
+const DOT_BYTE = 46;
+const MAX_NAME_BYTES = 255;
+const NUL_BYTE = 0;
+const SHA256_BYTES = 32;
+const ROOT_PATH = new Uint8Array([SLASH_BYTE]);
+const Path = CanonicalBase64.Encoded;
+const InlinePayload = Schema.TaggedStruct("Inline", { bytes: CanonicalBase64.Encoded });
+const BasePayload = Schema.TaggedStruct("Base", { path: Path });
+const Payload = Schema.Union([InlinePayload, BasePayload]);
+const DeltaRecord = Schema.Union([
     Schema.Struct({ kind: Schema.Literal("directory"), paths: Schema.Array(Path), metadata: Image.StoredMetadata }),
     Schema.Struct({
         kind: Schema.Literal("file"),
@@ -31,241 +43,256 @@ const Record = Schema.Union([
         payload: Payload
     })
 ]);
-const Kind = Schema.Literals(["directory", "file", "symlink"]);
-const Difference = Schema.Literals([
-    "kind",
-    "content",
-    "target",
-    "hardLinks",
-    "mode",
-    "uid",
-    "gid",
-    "atimeNs",
-    "mtimeNs",
-    "ctimeNs",
-    "birthtimeNs"
+const AddedChange = Schema.TaggedStruct("Added", { path: Path, kind: SnapshotNodeKind });
+const RemovedChange = Schema.TaggedStruct("Removed", { path: Path, kind: SnapshotNodeKind });
+const UpdatedChange = Schema.TaggedStruct("Updated", {
+    path: Path,
+    beforeKind: SnapshotNodeKind,
+    afterKind: SnapshotNodeKind,
+    differences: Schema.Array(SnapshotDifference).check(Schema.isMinLength(1))
+});
+const Change = Schema.Union([AddedChange, RemovedChange, UpdatedChange]);
+const WirePayload = Schema.Union([
+    Schema.TaggedStruct("Inline", { bytes: Schema.String }),
+    Schema.TaggedStruct("Base", { path: Schema.String })
 ]);
-const Change = Schema.Union([
-    Schema.TaggedStruct("Added", { path: Path, kind: Kind }),
-    Schema.TaggedStruct("Removed", { path: Path, kind: Kind }),
+const WireDeltaRecord = Schema.Union([
+    Schema.Struct({
+        kind: Schema.Literal("directory"),
+        paths: Schema.Array(Schema.String),
+        metadata: WireStoredMetadata
+    }),
+    Schema.Struct({
+        kind: Schema.Literal("file"),
+        paths: Schema.Array(Schema.String),
+        metadata: WireStoredMetadata,
+        payload: WirePayload
+    }),
+    Schema.Struct({
+        kind: Schema.Literal("symlink"),
+        paths: Schema.Array(Schema.String),
+        metadata: WireStoredMetadata,
+        payload: WirePayload
+    })
+]);
+const WireChange = Schema.Union([
+    Schema.TaggedStruct("Added", { path: Schema.String, kind: SnapshotNodeKind }),
+    Schema.TaggedStruct("Removed", { path: Schema.String, kind: SnapshotNodeKind }),
     Schema.TaggedStruct("Updated", {
-        path: Path,
-        beforeKind: Kind,
-        afterKind: Kind,
-        differences: Schema.Array(Difference).check(Schema.isMinLength(1))
+        path: Schema.String,
+        beforeKind: SnapshotNodeKind,
+        afterKind: SnapshotNodeKind,
+        differences: Schema.Array(SnapshotDifference).check(Schema.isMinLength(1))
     })
 ]);
+const sameChanges = Schema.toEquivalence(Schema.Array(Change));
+const VersionProbe = Schema.Struct({
+    format: Schema.Literal(FORMAT),
+    version: Schema.Unknown
+});
 const Document = Schema.Struct({
-    format: Schema.Literal("effect-vfs-delta"),
+    format: Schema.Literal(FORMAT),
     version: Schema.Literal(1),
-    base: Schema.Struct({ algorithm: Schema.Literal("effect-vfs-semantic-sha256-v1"), digest: Schema.String }),
-    records: Schema.Array(Record),
+    base: Schema.Struct({ algorithm: Schema.Literal(ALGORITHM), digest: CanonicalBase64.Encoded }),
+    records: Schema.Array(DeltaRecord),
     changes: Schema.Array(Change)
 });
+const WireDocument = Schema.Struct({
+    format: Schema.Literal(FORMAT),
+    version: Schema.Literal(1),
+    base: Schema.Struct({ algorithm: Schema.Literal(ALGORITHM), digest: Schema.String }),
+    records: Schema.Array(WireDeltaRecord),
+    changes: Schema.Array(WireChange)
+});
 const timestampFields = new Set(["atimeNs", "mtimeNs", "ctimeNs", "birthtimeNs"]);
-const differenceOrder = [
-    "kind",
-    "content",
-    "target",
-    "hardLinks",
-    "mode",
-    "uid",
-    "gid",
-    "atimeNs",
-    "mtimeNs",
-    "ctimeNs",
-    "birthtimeNs"
-];
+const differenceOrder = SnapshotDifference.literals;
 const encoder = new TextEncoder();
 const Json = Schema.fromJsonString(Schema.Unknown);
-const failure = (code, field) => new ImageError({ code, ...(field === undefined ? {} : { field }) });
-const sameBytes = (a, b) => Equal.equals(a, b);
-const compareBytes = (a, b) => {
-    for (let i = 0; i < Math.min(a.length, b.length); i++) {
-        const d = a[i] - b[i];
-        if (d !== 0)
-            return d;
-    }
-    return a.length - b.length;
-};
+const JsonDocument = Schema.fromJsonString(Document);
 const key = Encoding.encodeHex;
 const join = (parent, name) => {
     const out = new Uint8Array(parent.length + (parent.length === 1 ? 0 : 1) + name.length);
     out.set(parent);
     let offset = parent.length;
     if (parent.length !== 1)
-        out[offset++] = 47;
+        out[offset++] = SLASH_BYTE;
     out.set(name, offset);
     return out;
 };
 const parentKey = (path) => {
     let slash = path.length - 1;
-    while (slash > 0 && path[slash] !== 47)
+    while (slash > 0 && path[slash] !== SLASH_BYTE)
         slash--;
-    return key(slash === 0 ? new Uint8Array([47]) : path.subarray(0, slash));
+    return key(slash === 0 ? ROOT_PATH : path.subarray(0, slash));
 };
 const basename = (path) => {
     let slash = path.length - 1;
-    while (slash > 0 && path[slash] !== 47)
+    while (slash > 0 && path[slash] !== SLASH_BYTE)
         slash--;
     return path.subarray(slash + 1);
 };
-const decode64 = (s, field) => CanonicalBase64.isCanonical(s) ? Effect.succeed(Image.bytes(s)) : Effect.fail(failure("InvalidEncoding", field));
 const safeAdd = (a, b) => {
     const n = a + b;
     return Number.isSafeInteger(n) ? n : undefined;
 };
-const encodedPayloadLength = (value) => value.length / 4 * 3 - (value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0);
-const exceedsByteLimit = (value, limit) => BigInt(value) > BigInt(limit);
+const exceeds = (value, limit) => ByteSize.isGreaterThan(ByteSize.bytes(value), limit);
 const validPath = (path) => {
-    if (path.length === 0 || path[0] !== 47 || path.includes(0) || (path.length > 1 && path.at(-1) === 47))
+    if (path.length === 0 || path[0] !== SLASH_BYTE || path.includes(NUL_BYTE) ||
+        (path.length > 1 && path.at(-1) === SLASH_BYTE))
         return false;
     if (path.length === 1)
         return true;
     let start = 1;
     for (let i = 1; i <= path.length; i++) {
-        if (i === path.length || path[i] === 47) {
+        if (i === path.length || path[i] === SLASH_BYTE) {
             const length = i - start;
-            if (length < 1 || length > 255 || (length === 1 && path[start] === 46) ||
-                (length === 2 && path[start] === 46 && path[start + 1] === 46))
+            if (length < 1 || length > MAX_NAME_BYTES || (length === 1 && path[start] === DOT_BYTE) ||
+                (length === 2 && path[start] === DOT_BYTE && path[start + 1] === DOT_BYTE))
                 return false;
             start = i + 1;
         }
     }
     return true;
 };
+const roleBudget = (limits, role) => role === "base"
+    ? {
+        records: limits.maxBaseRecords,
+        recordsField: "baseRecords",
+        pathBytes: limits.maxIdentityBytes,
+        pathBytesField: "identityBytes",
+        payloadBytes: limits.maxIdentityBytes,
+        payloadBytesField: "identityBytes"
+    }
+    : {
+        records: limits.maxTargetRecords,
+        recordsField: "targetRecords",
+        pathBytes: limits.maxDecodedDeltaBytes,
+        pathBytesField: "decodedDeltaBytes",
+        payloadBytes: limits.maxOutputBytes,
+        payloadBytesField: "outputBytes"
+    };
+const encodedPayload = (record) => Match.value(record).pipe(Match.tag("directory", () => undefined), Match.tag("file", (record) => record.data), Match.tag("symlink", (record) => record.target), Match.exhaustive);
 const normalize = Effect.fnUntraced(function* (snapshot, limits, role) {
     const doc = yield* Image.inspect(snapshot);
-    if (doc.records.length > (role === "base" ? limits.maxBaseRecords : limits.maxTargetRecords)) {
-        return yield* failure("LimitExceeded", `${role}Records`);
+    const budget = roleBudget(limits, role);
+    if (doc.records.length > budget.records) {
+        return yield* new ImageError({ code: "LimitExceeded", field: budget.recordsField });
     }
     const records = new Map(doc.records.map((record) => [record.id, record]));
     const pathsById = new Map();
-    const pending = [[doc.root, new Uint8Array([47])]];
+    const pending = [[doc.root, ROOT_PATH]];
     let entries = 0;
-    let pathBytes = 1;
+    let pathBytes = ByteSize.bytes(ROOT_PATH.length);
+    // Index loop: `pending` grows while it is being walked.
     for (let i = 0; i < pending.length; i++) {
         const [recordId, path] = pending[i];
         const record = records.get(recordId);
         if (record === undefined)
-            return yield* failure("InvalidStructure", role);
+            return yield* new ImageError({ code: "InvalidStructure", field: role });
         const paths = pathsById.get(recordId);
         if (paths === undefined)
             pathsById.set(recordId, [path]);
         else
             paths.push(path);
-        if (record.kind === "directory") {
+        if (Image.Record.guards.directory(record)) {
             for (const entry of record.entries) {
                 if (++entries > limits.maxEntries)
-                    return yield* failure("LimitExceeded", "entries");
-                const nameLength = encodedPayloadLength(entry.name);
-                const pathLength = safeAdd(path.length + (path.length === 1 ? 0 : 1), nameLength);
-                const nextPathBytes = pathLength === undefined ? undefined : safeAdd(pathBytes, pathLength);
-                const pathLimit = role === "base" ? limits.maxIdentityBytes : limits.maxDecodedDeltaBytes;
-                if (nextPathBytes === undefined || exceedsByteLimit(nextPathBytes, pathLimit)) {
-                    return yield* failure("LimitExceeded", role === "base" ? "identityBytes" : "decodedDeltaBytes");
+                    return yield* new ImageError({ code: "LimitExceeded", field: "entries" });
+                const separator = path.length === ROOT_PATH.length ? 0 : 1;
+                const pathLength = path.length + separator + CanonicalBase64.decodedLength(entry.name);
+                pathBytes = ByteSize.sum(pathBytes, ByteSize.bytes(pathLength));
+                if (ByteSize.isGreaterThan(pathBytes, budget.pathBytes)) {
+                    return yield* new ImageError({ code: "LimitExceeded", field: budget.pathBytesField });
                 }
-                pathBytes = nextPathBytes;
-                pending.push([entry.target, join(path, Image.bytes(entry.name))]);
+                pending.push([entry.target, join(path, yield* CanonicalBase64.decode(entry.name))]);
             }
         }
     }
     const objects = [];
     const byPath = new Map();
-    let payloadBytes = 0;
-    let basePayloadBytes = 0;
+    let payloadBytes = ByteSize.zero;
     for (const record of doc.records) {
         const paths = pathsById.get(record.id);
         if (paths === undefined)
-            return yield* failure("InvalidStructure", role);
-        paths.sort(compareBytes);
-        const encodedPayload = record.kind === "directory"
-            ? undefined
-            : record.kind === "file"
-                ? record.data
-                : record.target;
-        if (encodedPayload !== undefined) {
-            const payloadLength = encodedPayloadLength(encodedPayload);
-            const next = safeAdd(role === "base" ? basePayloadBytes : payloadBytes, payloadLength);
-            const limit = role === "base" ? limits.maxIdentityBytes : limits.maxOutputBytes;
-            if (next === undefined || exceedsByteLimit(next, limit)) {
-                return yield* failure("LimitExceeded", role === "base" ? "identityBytes" : "outputBytes");
+            return yield* new ImageError({ code: "InvalidStructure", field: role });
+        paths.sort(bytesOrder);
+        const encoded = encodedPayload(record);
+        if (encoded !== undefined) {
+            payloadBytes = ByteSize.sum(payloadBytes, ByteSize.bytes(CanonicalBase64.decodedLength(encoded)));
+            if (ByteSize.isGreaterThan(payloadBytes, budget.payloadBytes)) {
+                return yield* new ImageError({ code: "LimitExceeded", field: budget.payloadBytesField });
             }
-            if (role === "base")
-                basePayloadBytes = next;
-            else
-                payloadBytes = next;
         }
-        const payload = encodedPayload === undefined ? undefined : Image.bytes(encodedPayload);
         const object = {
-            kind: record.kind,
+            kind: record._tag,
             metadata: record.metadata,
             paths,
             pathIdentity: paths.map(key).join("/"),
-            payload
+            payload: encoded === undefined ? undefined : yield* CanonicalBase64.decode(encoded)
         };
         objects.push(object);
         for (const path of paths)
             byPath.set(key(path), { object, path });
     }
-    objects.sort((a, b) => compareBytes(a.paths[0], b.paths[0]));
+    objects.sort((a, b) => bytesOrder(a.paths[0], b.paths[0]));
     return { objects, byPath };
 });
+const U64_BYTES = 8;
+const EMPTY = new Uint8Array();
+const IDENTITY_PREFIX = encoder.encode(`${ALGORITHM}\0`);
+const KIND_BYTE = { directory: 0, file: 1, symlink: 2 };
 const u64 = (n) => {
-    const out = new Uint8Array(8);
+    const out = new Uint8Array(U64_BYTES);
     new DataView(out.buffer).setBigUint64(0, BigInt(n), false);
     return out;
 };
+const framedLength = (bytes) => U64_BYTES + bytes.length;
+const timestampBytes = (metadata) => [metadata.atimeNs, metadata.mtimeNs, metadata.ctimeNs, metadata.birthtimeNs].map((value) => encoder.encode(String(value)));
 // This is the versioned semantic identity encoding, not a generic byte builder.
 // Field framing, ordering, and the domain prefix are part of the persisted delta contract.
-const identityBytes = Effect.fnUntraced(function* (view, limits) {
-    let length = 0;
-    const initialCapacity = ByteSize.isGreaterThanOrEqualTo(limits.maxIdentityBytes, ByteSize.kibibytes(1))
-        ? 1024
-        : Number(ByteSize.toBigInt(limits.maxIdentityBytes));
-    let output = new Uint8Array(initialCapacity);
-    const append = (bytes) => {
-        const next = safeAdd(length, bytes.length);
-        if (next === undefined || BigInt(next) > ByteSize.toBigInt(limits.maxIdentityBytes)) {
-            return Effect.fail(failure("LimitExceeded", "identityBytes"));
-        }
-        if (next > output.length) {
-            let capacity = Math.max(1, output.length);
-            while (capacity < next)
-                capacity = Math.min(next, capacity * 2);
-            const expanded = new Uint8Array(capacity);
-            expanded.set(output);
-            output = expanded;
-        }
-        output.set(bytes, length);
-        length = next;
-        return Effect.void;
+const identityBytes = (view, limits) => {
+    const timestamps = view.objects.map((object) => timestampBytes(object.metadata));
+    let total = ByteSize.bytes(IDENTITY_PREFIX.length + U64_BYTES);
+    for (const [index, object] of view.objects.entries()) {
+        const objectBytes = U64_BYTES +
+            object.paths.reduce((sum, path) => sum + framedLength(path), 0) +
+            1 + 3 * U64_BYTES +
+            timestamps[index].reduce((sum, stamp) => sum + framedLength(stamp), 0) +
+            framedLength(object.payload ?? EMPTY);
+        total = ByteSize.sum(total, ByteSize.bytes(objectBytes));
+    }
+    if (ByteSize.isGreaterThan(total, limits.maxIdentityBytes)) {
+        return Result.fail(new ImageError({ code: "LimitExceeded", field: "identityBytes" }));
+    }
+    const output = new Uint8Array(Number(ByteSize.toBigInt(total)));
+    let offset = 0;
+    const put = (bytes) => {
+        output.set(bytes, offset);
+        offset += bytes.length;
     };
-    const frame = Effect.fnUntraced(function* (bytes) {
-        yield* append(u64(bytes.length));
-        yield* append(bytes);
-    });
-    yield* append(encoder.encode("effect-vfs-semantic-sha256-v1\0"));
-    yield* append(u64(view.objects.length));
-    for (const object of view.objects) {
-        yield* append(u64(object.paths.length));
+    const frame = (bytes) => {
+        put(u64(bytes.length));
+        put(bytes);
+    };
+    put(IDENTITY_PREFIX);
+    put(u64(view.objects.length));
+    for (const [index, object] of view.objects.entries()) {
+        put(u64(object.paths.length));
         for (const path of object.paths)
-            yield* frame(path);
-        yield* append(new Uint8Array([object.kind === "directory" ? 0 : object.kind === "file" ? 1 : 2]));
-        yield* append(u64(object.metadata.uid));
-        yield* append(u64(object.metadata.gid));
-        yield* append(u64(object.metadata.mode));
-        yield* frame(encoder.encode(object.metadata.atimeNs));
-        yield* frame(encoder.encode(object.metadata.mtimeNs));
-        yield* frame(encoder.encode(object.metadata.ctimeNs));
-        yield* frame(encoder.encode(object.metadata.birthtimeNs));
-        yield* frame(object.payload ?? new Uint8Array());
+            frame(path);
+        put(new Uint8Array([KIND_BYTE[object.kind]]));
+        put(u64(object.metadata.uid));
+        put(u64(object.metadata.gid));
+        put(u64(object.metadata.mode));
+        for (const stamp of timestamps[index])
+            frame(stamp);
+        frame(object.payload ?? EMPTY);
     }
-    return output.slice(0, length);
-});
+    return Result.succeed(output);
+};
 const digest = Effect.fnUntraced(function* (view, limits) {
     const crypto = yield* Crypto.Crypto;
-    return yield* crypto.digest("SHA-256", yield* identityBytes(view, limits));
+    return yield* crypto.digest("SHA-256", yield* Effect.fromResult(identityBytes(view, limits)));
 });
 const samePaths = (a, b) => a.pathIdentity === b.pathIdentity;
 const differences = (before, after) => differenceOrder.filter((field) => {
@@ -284,264 +311,265 @@ const differences = (before, after) => differenceOrder.filter((field) => {
 const compare = (base, target) => {
     const changes = [];
     const add = (change, path) => changes.push({ change, path });
-    const differencesByPair = new WeakMap();
-    const cachedDifferences = (before, after) => {
-        let byAfter = differencesByPair.get(before);
-        if (byAfter === undefined) {
-            byAfter = new WeakMap();
-            differencesByPair.set(before, byAfter);
-        }
-        const cached = byAfter.get(after);
-        if (cached !== undefined)
-            return cached;
-        const value = differences(before, after);
-        byAfter.set(after, value);
-        return value;
-    };
+    // Memoized per object pair so hard-link groups compare each pair once.
+    const cachedDifferences = Fn.memoize((before) => Fn.memoize((after) => differences(before, after)));
     for (const [pathKey, before] of base.byPath) {
         const after = target.byPath.get(pathKey);
         if (after === undefined) {
-            add({ _tag: "Removed", path: Image.base64(before.path), kind: before.object.kind }, before.path);
+            add(RemovedChange.make({ path: CanonicalBase64.encode(before.path), kind: before.object.kind }), before.path);
         }
         else {
-            const diff = cachedDifferences(before.object, after.object);
+            const diff = cachedDifferences(before.object)(after.object);
             if (diff.length > 0) {
-                add({
-                    _tag: "Updated",
-                    path: Image.base64(before.path),
+                add(UpdatedChange.make({
+                    path: CanonicalBase64.encode(before.path),
                     beforeKind: before.object.kind,
                     afterKind: after.object.kind,
                     differences: diff
-                }, before.path);
+                }), before.path);
             }
         }
     }
     for (const [pathKey, after] of target.byPath) {
         if (!base.byPath.has(pathKey)) {
-            add({ _tag: "Added", path: Image.base64(after.path), kind: after.object.kind }, after.path);
+            add(AddedChange.make({ path: CanonicalBase64.encode(after.path), kind: after.object.kind }), after.path);
         }
     }
-    changes.sort((a, b) => compareBytes(a.path, b.path));
+    changes.sort((a, b) => bytesOrder(a.path, b.path));
     return changes.map(({ change }) => change);
 };
 const getDocument = (delta) => Effect.suspend(() => {
-    const value = snapshotDeltaValue(delta);
+    const value = SnapshotDeltaModel.value(delta);
     return value !== undefined && Schema.is(Document)(value)
         ? Effect.succeed(value)
-        : Effect.fail(failure("InvalidStructure", "delta"));
+        : Effect.fail(new ImageError({ code: "InvalidStructure", field: "delta" }));
+});
+const byEntryName = (a, b) => bytesOrder(a.name, b.name);
+// Every recorded path must be the root directory or the child of a recorded directory.
+// Together with `validPath` and the per-record path rules in `validate`, this subsumes the
+// structural checks `Image.capture` would otherwise perform on the applied image.
+const linkTree = (paths) => {
+    const rootKey = key(ROOT_PATH);
+    const root = paths.get(rootKey);
+    if (root?.kind !== "directory")
+        return Result.fail(new ImageError({ code: "InvalidStructure", field: "root" }));
+    const entriesById = new Map();
+    for (const entry of paths.values()) {
+        if (entry.kind === "directory")
+            entriesById.set(entry.id, []);
+    }
+    for (const [pathKey, child] of paths) {
+        if (pathKey === rootKey)
+            continue;
+        const parent = paths.get(parentKey(child.bytes));
+        const entries = parent === undefined ? undefined : entriesById.get(parent.id);
+        if (entries === undefined)
+            return Result.fail(new ImageError({ code: "InvalidStructure", field: "parent" }));
+        entries.push({ name: basename(child.bytes), target: child.id });
+    }
+    for (const entries of entriesById.values())
+        entries.sort(byEntryName);
+    return Result.succeed({ root: root.id, entriesById });
+};
+const inheritedPayload = Effect.fnUntraced(function* (base, kind, encodedPath) {
+    const source = base.byPath.get(key(yield* CanonicalBase64.decode(encodedPath)))?.object;
+    return source?.kind === kind ? source.payload : undefined;
 });
+// Expects a document that already passed `validate`.
 const buildImage = Effect.fnUntraced(function* (document, base, limits) {
     const paths = new Map();
-    const records = [];
-    const entriesById = new Map();
-    let bytes = 0;
-    for (let i = 0; i < document.records.length; i++) {
-        const record = document.records[i];
-        const recordId = String(i);
+    for (const [index, record] of document.records.entries()) {
         for (const encodedPath of record.paths) {
-            const path = yield* decode64(encodedPath, "path");
-            paths.set(key(path), { id: recordId, kind: record.kind, bytes: path });
+            const bytes = yield* CanonicalBase64.decode(encodedPath);
+            paths.set(key(bytes), { id: String(index), kind: record.kind, bytes });
         }
+    }
+    const tree = yield* Effect.fromResult(linkTree(paths));
+    const records = [];
+    let outputBytes = ByteSize.zero;
+    for (const [index, record] of document.records.entries()) {
+        const id = String(index);
         if (record.kind === "directory") {
-            const entries = [];
-            entriesById.set(recordId, entries);
-            records.push({ id: recordId, kind: "directory", metadata: record.metadata, entries });
+            records.push(Image.Record.cases.directory.make({
+                id,
+                metadata: record.metadata,
+                entries: (tree.entriesById.get(id) ?? []).map((entry) => ({
+                    name: CanonicalBase64.encode(entry.name),
+                    target: entry.target
+                }))
+            }));
             continue;
         }
-        const inherited = record.payload._tag === "Base"
-            ? base?.byPath.get(key(yield* decode64(record.payload.path, "basePath")))?.object
-            : undefined;
-        const inlineLength = record.payload._tag === "Inline"
-            ? encodedPayloadLength(record.payload.bytes)
-            : undefined;
-        const payloadLength = inlineLength ?? (base === undefined
-            ? 0
-            : inherited?.kind === record.kind
-                ? inherited.payload?.length
-                : undefined);
-        const next = payloadLength === undefined ? undefined : safeAdd(bytes, payloadLength);
-        if (next !== undefined && exceedsByteLimit(next, limits.maxOutputBytes)) {
-            return yield* failure("LimitExceeded", "outputBytes");
+        const payload = Predicate.isTagged("Inline")(record.payload)
+            ? yield* CanonicalBase64.decode(record.payload.bytes)
+            : yield* inheritedPayload(base, record.kind, record.payload.path);
+        if (payload === undefined)
+            return yield* new ImageError({ code: "InvalidStructure", field: "baseReference" });
+        outputBytes = ByteSize.sum(outputBytes, ByteSize.bytes(payload.length));
+        if (ByteSize.isGreaterThan(outputBytes, limits.maxOutputBytes)) {
+            return yield* new ImageError({ code: "LimitExceeded", field: "outputBytes" });
         }
-        const payload = record.payload._tag === "Inline"
-            ? yield* decode64(record.payload.bytes, "payload")
-            : inherited?.kind === record.kind
-                ? inherited.payload
-                : undefined;
-        if (payload === undefined && base !== undefined)
-            return yield* failure("InvalidStructure", "baseReference");
-        const actual = payload ?? new Uint8Array();
-        if (next === undefined)
-            return yield* failure("LimitExceeded", "outputBytes");
-        bytes = next;
         records.push(record.kind === "file"
-            ? { id: recordId, kind: "file", metadata: record.metadata, data: Image.base64(actual) }
-            : { id: recordId, kind: "symlink", metadata: record.metadata, target: Image.base64(actual) });
+            ? Image.Record.cases.file.make({ id, metadata: record.metadata, data: CanonicalBase64.encode(payload) })
+            : Image.Record.cases.symlink.make({
+                id,
+                metadata: record.metadata,
+                target: CanonicalBase64.encode(payload)
+            }));
     }
-    const root = paths.get(key(new Uint8Array([47])));
-    if (root?.kind !== "directory")
-        return yield* failure("InvalidStructure", "root");
-    for (const [pathKey, child] of paths) {
-        if (pathKey !== key(new Uint8Array([47]))) {
-            const parent = paths.get(parentKey(child.bytes));
-            const entries = parent === undefined ? undefined : entriesById.get(parent.id);
-            if (entries === undefined)
-                return yield* failure("InvalidStructure", "parent");
-            entries.push({ name: Image.base64(basename(child.bytes)), target: child.id });
-        }
-    }
-    for (const entries of entriesById.values())
-        entries.sort((a, b) => a.name.localeCompare(b.name));
-    return yield* Image.capture({ format: "effect-vfs", version: 1, root: root.id, records });
+    return yield* Image.capture({ format: "effect-vfs", version: 1, root: tree.root, records }, undefined, true);
 });
 const validate = Effect.fnUntraced(function* (document, limits) {
     const deltaRecords = safeAdd(document.records.length, document.changes.length);
     if (deltaRecords === undefined || deltaRecords > limits.maxDeltaRecords) {
-        return yield* failure("LimitExceeded", "deltaRecords");
+        return yield* new ImageError({ code: "LimitExceeded", field: "deltaRecords" });
+    }
+    if (document.records.length > limits.maxOutputRecords) {
+        return yield* new ImageError({ code: "LimitExceeded", field: "outputRecords" });
     }
-    if (document.records.length > limits.maxOutputRecords)
-        return yield* failure("LimitExceeded", "outputRecords");
-    if (!CanonicalBase64.isCanonical(document.base.digest) || CanonicalBase64.decodedLength(document.base.digest) !== 32) {
-        return yield* failure("InvalidEncoding", "digest");
+    if (!CanonicalBase64.is(document.base.digest) ||
+        CanonicalBase64.decodedLength(document.base.digest) !== SHA256_BYTES) {
+        return yield* new ImageError({ code: "InvalidEncoding", field: "digest" });
     }
-    let decoded = 32;
+    let decoded = ByteSize.bytes(SHA256_BYTES);
+    let outputBytes = ByteSize.zero;
     let entries = -1;
     let inherited = 0;
-    const seen = new Set();
-    for (const record of document.records) {
+    const paths = new Map();
+    const charge = (encoded) => {
+        decoded = ByteSize.sum(decoded, ByteSize.bytes(CanonicalBase64.decodedLength(encoded)));
+        return ByteSize.isGreaterThan(decoded, limits.maxDecodedDeltaBytes)
+            ? Effect.fail(new ImageError({ code: "LimitExceeded", field: "decodedDeltaBytes" }))
+            : Effect.void;
+    };
+    for (const [index, record] of document.records.entries()) {
         if (record.paths.length < 1 || (record.kind === "directory" && record.paths.length !== 1)) {
-            return yield* failure("InvalidStructure", "paths");
+            return yield* new ImageError({ code: "InvalidStructure", field: "paths" });
         }
         for (const encodedPath of record.paths) {
-            if (!CanonicalBase64.isCanonical(encodedPath))
-                return yield* failure("InvalidEncoding", "path");
-            decoded = safeAdd(decoded, CanonicalBase64.decodedLength(encodedPath)) ?? Number.POSITIVE_INFINITY;
-            if (BigInt(decoded) > ByteSize.toBigInt(limits.maxDecodedDeltaBytes)) {
-                return yield* failure("LimitExceeded", "decodedDeltaBytes");
+            if (!CanonicalBase64.is(encodedPath)) {
+                return yield* new ImageError({ code: "InvalidEncoding", field: "path" });
             }
+            yield* charge(encodedPath);
             entries++;
             if (entries > limits.maxEntries)
-                return yield* failure("LimitExceeded", "entries");
-            const path = yield* decode64(encodedPath, "path");
-            if (!validPath(path) || seen.has(key(path)))
-                return yield* failure("InvalidStructure", "path");
-            seen.add(key(path));
+                return yield* new ImageError({ code: "LimitExceeded", field: "entries" });
+            const bytes = yield* CanonicalBase64.decode(encodedPath);
+            const pathKey = key(bytes);
+            if (!validPath(bytes) || paths.has(pathKey)) {
+                return yield* new ImageError({ code: "InvalidStructure", field: "path" });
+            }
+            paths.set(pathKey, { id: String(index), kind: record.kind, bytes });
         }
-        if (record.kind !== "directory") {
-            if (record.payload._tag === "Inline") {
-                if (!CanonicalBase64.isCanonical(record.payload.bytes))
-                    return yield* failure("InvalidEncoding", "payload");
-                decoded = safeAdd(decoded, CanonicalBase64.decodedLength(record.payload.bytes)) ?? Number.POSITIVE_INFINITY;
-                if (BigInt(decoded) > ByteSize.toBigInt(limits.maxDecodedDeltaBytes)) {
-                    return yield* failure("LimitExceeded", "decodedDeltaBytes");
-                }
+        if (record.kind === "directory")
+            continue;
+        if (Predicate.isTagged("Inline")(record.payload)) {
+            if (!CanonicalBase64.is(record.payload.bytes)) {
+                return yield* new ImageError({ code: "InvalidEncoding", field: "payload" });
             }
-            else {
-                if (!CanonicalBase64.isCanonical(record.payload.path))
-                    return yield* failure("InvalidEncoding", "basePath");
-                decoded = safeAdd(decoded, CanonicalBase64.decodedLength(record.payload.path)) ?? Number.POSITIVE_INFINITY;
-                if (BigInt(decoded) > ByteSize.toBigInt(limits.maxDecodedDeltaBytes)) {
-                    return yield* failure("LimitExceeded", "decodedDeltaBytes");
-                }
-                inherited++;
-                if (inherited > limits.maxInheritedRecords) {
-                    return yield* failure("LimitExceeded", "inheritedRecords");
-                }
-                const path = yield* decode64(record.payload.path, "basePath");
-                if (!validPath(path) || !record.paths.includes(record.payload.path)) {
-                    return yield* failure("InvalidStructure", "basePath");
-                }
+            yield* charge(record.payload.bytes);
+            outputBytes = ByteSize.sum(outputBytes, ByteSize.bytes(CanonicalBase64.decodedLength(record.payload.bytes)));
+        }
+        else {
+            if (!CanonicalBase64.is(record.payload.path)) {
+                return yield* new ImageError({ code: "InvalidEncoding", field: "basePath" });
+            }
+            yield* charge(record.payload.path);
+            inherited++;
+            if (inherited > limits.maxInheritedRecords) {
+                return yield* new ImageError({ code: "LimitExceeded", field: "inheritedRecords" });
+            }
+            if (!validPath(yield* CanonicalBase64.decode(record.payload.path)) || !record.paths.includes(record.payload.path)) {
+                return yield* new ImageError({ code: "InvalidStructure", field: "basePath" });
             }
         }
     }
     let previous;
     for (const change of document.changes) {
-        if (!CanonicalBase64.isCanonical(change.path))
-            return yield* failure("InvalidEncoding", "changePath");
-        decoded = safeAdd(decoded, CanonicalBase64.decodedLength(change.path)) ?? Number.POSITIVE_INFINITY;
-        if (BigInt(decoded) > ByteSize.toBigInt(limits.maxDecodedDeltaBytes)) {
-            return yield* failure("LimitExceeded", "decodedDeltaBytes");
+        if (!CanonicalBase64.is(change.path)) {
+            return yield* new ImageError({ code: "InvalidEncoding", field: "changePath" });
         }
-        const path = yield* decode64(change.path, "changePath");
-        if (!validPath(path) || (previous !== undefined && compareBytes(previous, path) >= 0)) {
-            return yield* failure("InvalidStructure", "changes");
+        yield* charge(change.path);
+        const path = yield* CanonicalBase64.decode(change.path);
+        if (!validPath(path) || (previous !== undefined && bytesOrder(previous, path) >= 0)) {
+            return yield* new ImageError({ code: "InvalidStructure", field: "changes" });
         }
         previous = path;
     }
-    yield* buildImage(document, undefined, limits);
+    if (ByteSize.isGreaterThan(outputBytes, limits.maxOutputBytes)) {
+        return yield* new ImageError({ code: "LimitExceeded", field: "outputBytes" });
+    }
+    yield* Effect.fromResult(linkTree(paths));
+    // Inline symlink targets are the only applied payloads a base snapshot has not already vetted.
+    for (const record of document.records) {
+        if (record.kind !== "symlink" || !Predicate.isTagged("Inline")(record.payload))
+            continue;
+        if (!CanonicalBase64.is(record.payload.bytes)) {
+            return yield* new ImageError({ code: "InvalidEncoding", field: "payload" });
+        }
+        if ((yield* CanonicalBase64.decode(record.payload.bytes)).includes(NUL_BYTE)) {
+            return yield* new ImageError({ code: "InvalidStructure", field: "symlink" });
+        }
+    }
 });
 /** @internal */
-export const diffSnapshots = Effect.fn("VirtualFileSystem.diffSnapshots")(function* (base, target, limits) {
+export const diffSnapshots = Effect.fnUntraced(function* (base, target, limits) {
     const before = yield* normalize(base, limits, "base");
     const after = yield* normalize(target, limits, "target");
     const changes = [...compare(before, after)];
     const deltaRecords = safeAdd(after.objects.length, changes.length);
     if (deltaRecords === undefined || deltaRecords > limits.maxDeltaRecords) {
-        return yield* failure("LimitExceeded", "deltaRecords");
+        return yield* new ImageError({ code: "LimitExceeded", field: "deltaRecords" });
     }
-    const payloadEquality = new WeakMap();
-    const samePayload = (source, target) => {
-        let byTarget = payloadEquality.get(source);
-        if (byTarget === undefined) {
-            byTarget = new WeakMap();
-            payloadEquality.set(source, byTarget);
-        }
-        const cached = byTarget.get(target);
-        if (cached !== undefined)
-            return cached;
-        const value = sameBytes(source.payload, target.payload);
-        byTarget.set(target, value);
-        return value;
-    };
+    const samePayload = Fn.memoize((source) => Fn.memoize((candidate) => sameBytes(source.payload, candidate.payload)));
     const records = after.objects.map((object) => {
-        const paths = object.paths.map(Image.base64);
+        const paths = object.paths.map(CanonicalBase64.encode);
         if (object.kind === "directory")
             return { kind: object.kind, paths, metadata: object.metadata };
         const inherited = object.paths.find((path) => {
             const source = before.byPath.get(key(path));
-            return source?.object.kind === object.kind && samePayload(source.object, object);
+            return source?.object.kind === object.kind && samePayload(source.object)(object);
         });
         return {
             kind: object.kind,
             paths,
             metadata: object.metadata,
             payload: inherited === undefined
-                ? { _tag: "Inline", bytes: Image.base64(object.payload ?? new Uint8Array()) }
-                : { _tag: "Base", path: Image.base64(inherited) }
+                ? InlinePayload.make({ bytes: CanonicalBase64.encode(object.payload ?? new Uint8Array()) })
+                : BasePayload.make({ path: CanonicalBase64.encode(inherited) })
         };
     });
     const document = {
-        format: "effect-vfs-delta",
+        format: FORMAT,
         version: 1,
-        base: { algorithm: "effect-vfs-semantic-sha256-v1", digest: Image.base64(yield* digest(before, limits)) },
+        base: { algorithm: ALGORITHM, digest: CanonicalBase64.encode(yield* digest(before, limits)) },
         records,
         changes
     };
     yield* validate(document, limits);
-    return makeSnapshotDelta(document);
+    return SnapshotDeltaModel.make(document);
 });
 /** @internal */
 const verify = Effect.fnUntraced(function* (base, document, limits) {
     yield* validate(document, limits);
     const before = yield* normalize(base, limits, "base");
-    if (!sameBytes(yield* digest(before, limits), Image.bytes(document.base.digest))) {
+    if (!sameBytes(yield* digest(before, limits), yield* CanonicalBase64.decode(document.base.digest))) {
         return yield* new SnapshotDeltaError({ code: "BaseMismatch" });
     }
     const target = yield* buildImage(document, before, limits);
     const changes = compare(before, yield* normalize(target, limits, "target"));
-    const actualChanges = yield* Schema.encodeEffect(Json)(changes).pipe(Effect.mapError(() => failure("InvalidStructure", "changes")));
-    const expectedChanges = yield* Schema.encodeEffect(Json)(document.changes).pipe(Effect.mapError(() => failure("InvalidStructure", "changes")));
-    if (actualChanges !== expectedChanges)
-        return yield* failure("InvalidStructure", "changes");
+    if (!sameChanges(changes, document.changes)) {
+        return yield* new ImageError({ code: "InvalidStructure", field: "changes" });
+    }
     return { changes, target };
 });
 /** @internal */
-export const inspectSnapshotDelta = Effect.fn("VirtualFileSystem.inspectSnapshotDelta")(function* (base, delta, options, limits) {
+export const inspectSnapshotDelta = Effect.fnUntraced(function* (base, delta, options, limits) {
     const output = [];
     const { changes } = yield* verify(base, yield* getDocument(delta), limits);
     for (const change of changes) {
-        const path = makeBytePath(new Uint8Array(yield* decode64(change.path, "changePath")));
-        if (change._tag !== "Updated")
+        const path = makeBytePath(yield* CanonicalBase64.decode(change.path));
+        if (!Predicate.isTagged("Updated")(change))
             output.push(Object.freeze({ ...change, path }));
         else {
             const fields = change.differences.filter((field) => options.includeTimestamps === true || !timestampFields.has(field));
@@ -555,35 +583,40 @@ export const inspectSnapshotDelta = Effect.fn("VirtualFileSystem.inspectSnapshot
 export const encodeSnapshotDelta = Effect.fnUntraced(function* (delta, limits) {
     const document = yield* getDocument(delta);
     yield* validate(document, limits);
-    const text = yield* Schema.encodeEffect(Json)(document).pipe(Effect.mapError(() => failure("InvalidStructure")));
+    const text = yield* Schema.encodeEffect(JsonDocument)(document).pipe(Effect.mapError(() => new ImageError({ code: "InvalidStructure" })));
     const bytes = encoder.encode(text);
-    if (BigInt(bytes.length) > ByteSize.toBigInt(limits.maxEncodedBytes)) {
-        return yield* failure("LimitExceeded", "encodedBytes");
+    if (exceeds(bytes.length, limits.maxEncodedBytes)) {
+        return yield* new ImageError({ code: "LimitExceeded", field: "encodedBytes" });
     }
     return bytes;
 });
 /** @internal */
 export const decodeSnapshotDelta = Effect.fnUntraced(function* (input, limits) {
-    if (!(input instanceof Uint8Array) || !(input.buffer instanceof ArrayBuffer))
-        return yield* failure("InvalidEncoding");
-    if (BigInt(input.byteLength) > ByteSize.toBigInt(limits.maxEncodedBytes)) {
-        return yield* failure("LimitExceeded", "encodedBytes");
+    if (!(input instanceof Uint8Array) || !(input.buffer instanceof ArrayBuffer)) {
+        return yield* new ImageError({ code: "InvalidEncoding" });
+    }
+    if (exceeds(input.byteLength, limits.maxEncodedBytes)) {
+        return yield* new ImageError({ code: "LimitExceeded", field: "encodedBytes" });
     }
     const text = yield* Effect.try({
         try: () => new TextDecoder("utf-8", { fatal: true }).decode(new Uint8Array(input)),
-        catch: () => failure("InvalidEncoding")
+        catch: () => new ImageError({ code: "InvalidEncoding" })
     });
-    const value = yield* Schema.decodeEffect(Json)(text).pipe(Effect.mapError(() => failure("InvalidEncoding")));
-    if (typeof value === "object" && value !== null && "format" in value && value.format === "effect-vfs-delta" &&
-        "version" in value && value.version !== 1)
-        return yield* failure("UnsupportedVersion");
+    const value = yield* Schema.decodeEffect(Json)(text).pipe(Effect.mapError(() => new ImageError({ code: "InvalidEncoding" })));
+    const version = Schema.decodeUnknownResult(VersionProbe)(value);
+    if (Result.isSuccess(version) && version.success.version !== 1) {
+        return yield* new ImageError({ code: "UnsupportedVersion" });
+    }
+    const wire = Schema.decodeUnknownResult(WireDocument, { onExcessProperty: "error" })(value);
+    if (Result.isFailure(wire))
+        return yield* new ImageError({ code: "InvalidStructure" });
+    yield* validate(wire.success, limits);
     const parsed = Schema.decodeUnknownResult(Document, { onExcessProperty: "error" })(value);
     if (Result.isFailure(parsed))
-        return yield* failure("InvalidStructure");
-    yield* validate(parsed.success, limits);
-    return makeSnapshotDelta(parsed.success);
+        return yield* new ImageError({ code: "InvalidEncoding" });
+    return SnapshotDeltaModel.make(parsed.success);
 });
 /** @internal */
-export const applySnapshotDelta = Effect.fn("VirtualFileSystem.applySnapshotDelta")(function* (base, delta, limits) {
+export const applySnapshotDelta = Effect.fnUntraced(function* (base, delta, limits) {
     return (yield* verify(base, yield* getDocument(delta), limits)).target;
 });