@effect-vfs/core 0.1.0 → 0.2.0

package/README.md

@@ -16,10 +16,10 @@ for the exact permission, path, timestamp, quota, and atomicity rules.
 ## Install
 
 ```sh
-npm install @effect-vfs/core effect@4.0.0-rc.112
+npm install @effect-vfs/core effect@4.0.0-rc.114
 ```
 
-Version `0.1.0` targets the exact peer version `effect@4.0.0-rc.112`.
+Version `0.1.0` targets the exact peer version `effect@4.0.0-rc.114`.
 
 ## The mental model
 
@@ -40,15 +40,15 @@ lifetime are explicit values that can be composed in one Effect program.
 
 ```ts
 import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
-import { Effect } from "effect"
+import { ByteSize, Effect } from "effect"
 
 const utf8 = new TextEncoder()
 
 const program = Effect.scoped(Effect.gen(function*() {
   const volume = yield* Vfs.make({
     maxEntries: 100,
-    maxBytes: 1_000_000,
-    maxFileBytes: 100_000
+    maxBytes: ByteSize.megabytes(1),
+    maxFileBytes: ByteSize.kilobytes(100)
   })
 
   const admin = yield* volume.caller()
@@ -129,12 +129,13 @@ resettable sandboxes.
 ```ts
 import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
 import { Effect } from "effect"
+import * as ByteSize from "effect/ByteSize"
 
 const decodeLimits = {
-  maxEncodedBytes: 1_000_000,
+  maxEncodedBytes: ByteSize.megabytes(1),
   maxRecords: 1_000,
   maxEntries: 1_000,
-  maxDecodedBytes: 1_000_000
+  maxDecodedBytes: ByteSize.megabytes(1)
 }
 
 const program = Effect.gen(function*() {
@@ -184,6 +185,7 @@ contents.
 ```ts
 import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
 import { Effect } from "effect"
+import * as ByteSize from "effect/ByteSize"
 
 const branch = Effect.gen(function*() {
   const template = yield* Vfs.fromFixture({
@@ -193,7 +195,7 @@ const branch = Effect.gen(function*() {
     ]
   })
   const base = yield* template.snapshot
-  const workspace = yield* Vfs.makeOverlay(base, { maxBytes: 1_000_000 })
+  const workspace = yield* Vfs.makeOverlay(base, { maxBytes: ByteSize.megabytes(1) })
   const fs = yield* workspace.caller()
 
   yield* fs.rename("/project/settings.json", "/project/preferences.json")
@@ -221,6 +223,93 @@ The Effects returned by `changes(options)` and `capture(options)` are also reusa
 workspace again. Invalid summary options fail with `ConfigurationError`; failure to construct the complete observed
 snapshot fails with `ImageError`. Reusing a previously completed `capture()` result does not observe later writes.
 
+## Store and apply exact snapshot deltas
+
+Use `diffSnapshots` when you need a portable description of the exact difference between two immutable snapshots.
+The result is an opaque `SnapshotDelta`: inspect it for a path-oriented summary, encode it with Effect Schema, or apply
+it to a semantically identical base to reconstruct the target snapshot.
+
+```ts
+import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+import * as NodeCrypto from "@effect/platform-node/NodeCrypto"
+import { Effect, Schema } from "effect"
+import * as ByteSize from "effect/ByteSize"
+
+const Delta = Vfs.SnapshotDeltaFromBytes()
+
+const program = Effect.gen(function*() {
+  const baseVolume = yield* Vfs.fromFixture({
+    entries: [{ kind: "file", path: "/old.txt", bytes: new TextEncoder().encode("before") }]
+  })
+  const targetVolume = yield* Vfs.fromFixture({
+    entries: [{ kind: "file", path: "/new.txt", bytes: new TextEncoder().encode("after") }]
+  })
+  const base = yield* baseVolume.snapshot
+  const target = yield* targetVolume.snapshot
+
+  const delta = yield* Vfs.diffSnapshots(base, target)
+  const changes = yield* Vfs.inspectSnapshotDelta(base, delta)
+  const bytes = yield* Schema.encodeEffect(Delta)(delta)
+  const decoded = yield* Schema.decodeEffect(Delta)(bytes)
+  const restored = yield* Vfs.applySnapshotDelta(base, decoded)
+
+  return { changes, restored }
+})
+
+await Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer)))
+```
+
+Inspection verifies the delta against its semantic base before reporting what the two snapshots prove. It does not guess renames from equal contents or paths: a move is a
+`Removed` change followed by an `Added` change. `Updated` records identify changed semantic fields, including content,
+metadata, symbolic-link targets, and hard-link topology. Summaries do not contain replay payloads; the opaque delta does.
+
+Each delta records the semantic identity of its required base. Inspecting or applying it against a different valid snapshot fails with a
+`SnapshotDeltaError` whose `code` is `BaseMismatch`. Equivalent snapshots are accepted even if their encoded bytes or
+internal record identifiers differ. Applying a delta returns another immutable `Snapshot`; call `fromSnapshot` when
+you need a writable volume.
+
+Creation, inspection, encoding, decoding, and application use finite `SnapshotDeltaLimits.default` limits when none are supplied.
+Delta creation, inspection, and application require Effect's platform-neutral `Crypto.Crypto` service for SHA-256 base identity.
+Provide the official Node, Bun, browser, or Deno crypto layer at the application edge; the core never imports a host
+crypto implementation. Memory-sensitive applications can use one policy throughout the workflow:
+
+```ts
+const limits = Vfs.SnapshotDeltaLimits.constrained
+const Delta = Vfs.SnapshotDeltaFromBytes(limits)
+
+const constrained = Effect.gen(function*() {
+  const delta = yield* Vfs.diffSnapshots(base, target, limits)
+  const bytes = yield* Schema.encodeEffect(Delta)(delta)
+  const decoded = yield* Schema.decodeEffect(Delta)(bytes)
+  return yield* Vfs.applySnapshotDelta(base, decoded, limits)
+})
+```
+
+Both presets are frozen complete policies. The shipped values are:
+
+| limit                               | `constrained` | `default` |
+| ----------------------------------- | ------------: | --------: |
+| encoded bytes                       |         2 MiB |    16 MiB |
+| canonical identity bytes            |         4 MiB |    32 MiB |
+| stored records plus summary changes |         6,500 |    50,000 |
+| decoded delta bytes                 |       512 KiB |     8 MiB |
+| base records                        |         6,500 |    50,000 |
+| target records                      |         6,500 |    50,000 |
+| namespace entries                   |         6,500 |   100,000 |
+| output records                      |         6,500 |    50,000 |
+| output payload bytes                |       256 KiB |     4 MiB |
+| inherited records                   |         6,500 |    50,000 |
+
+These are conservative finite defaults, not universal workspace-size or memory guarantees. To tune one dimension,
+spread a preset into a complete `SnapshotDeltaLimits` value and replace that field.
+
+```ts
+const limits = {
+  ...Vfs.SnapshotDeltaLimits.default,
+  maxOutputBytes: ByteSize.mebibytes(8)
+}
+```
+
 ## Use scoped handles for incremental I/O
 
 Whole-file operations are convenient, but handles give each open file an independent `bigint` cursor and support

package/dist/BytePath.d.ts

@@ -0,0 +1,21 @@
+import * as Schema from "effect/Schema";
+export declare const BytePathId: unique symbol;
+/**
+ * An opaque path that preserves arbitrary non-NUL bytes without UTF-8 conversion.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface BytePath {
+    readonly [BytePathId]: true;
+}
+/**
+ * Schema for an opaque byte-preserving filesystem path.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const BytePath: Schema.declare<BytePath, BytePath>;
+export declare const make: (bytes: Uint8Array) => BytePath;
+export declare const getBytes: (path: BytePath) => Uint8Array | undefined;
+//# sourceMappingURL=BytePath.d.ts.map

package/dist/BytePath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BytePath.d.ts","sourceRoot":"","sources":["../src/BytePath.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,eAAO,MAAM,UAAU,eAAsC,CAAA;AAI7D;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,CAAC,UAAU,CAAC,EAAE,IAAI,CAAA;CAC5B;AAED;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,oCAEpB,CAAA;AAED,eAAO,MAAM,IAAI,UAAW,UAAU,KAAG,QAIxC,CAAA;AAED,eAAO,MAAM,QAAQ,SAAU,QAAQ,KAAG,UAAU,GAAG,SAAgC,CAAA"}

package/dist/BytePath.js

@@ -0,0 +1,16 @@
+import * as Schema from "effect/Schema";
+export const BytePathId = Symbol("@effect-vfs/core/BytePath");
+const bytePaths = new WeakMap();
+/**
+ * Schema for an opaque byte-preserving filesystem path.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const BytePath = Schema.declare((value) => typeof value === "object" && value !== null && bytePaths.has(value));
+export const make = (bytes) => {
+    const path = Object.freeze({ [BytePathId]: true });
+    bytePaths.set(path, bytes);
+    return path;
+};
+export const getBytes = (path) => bytePaths.get(path);

package/dist/Snapshot.d.ts

@@ -46,13 +46,13 @@ export declare class ImageError extends ImageError_base<{
  */
 export declare const DecodeLimits: Schema.Struct<{
     /** Maximum accepted encoded input length in bytes. */
-    readonly maxEncodedBytes: Schema.Finite;
+    readonly maxEncodedBytes: Schema.ByteSize;
     /** Maximum number of stored metadata and content records. */
     readonly maxRecords: Schema.Finite;
     /** Maximum number of namespace entries. */
     readonly maxEntries: Schema.Finite;
     /** Maximum combined decoded byte content. */
-    readonly maxDecodedBytes: Schema.Finite;
+    readonly maxDecodedBytes: Schema.ByteSize;
 }>;
 /**
  * Resource limits applied while decoding a snapshot.

package/dist/Snapshot.js

@@ -33,11 +33,11 @@ export class ImageError extends Data.TaggedError("ImageError") {
  */
 export const DecodeLimits = Schema.Struct({
     /** Maximum accepted encoded input length in bytes. */
-    maxEncodedBytes: Natural,
+    maxEncodedBytes: Schema.ByteSize,
     /** Maximum number of stored metadata and content records. */
     maxRecords: Natural,
     /** Maximum number of namespace entries. */
     maxEntries: Natural,
     /** Maximum combined decoded byte content. */
-    maxDecodedBytes: Natural
+    maxDecodedBytes: Schema.ByteSize
 });

package/dist/SnapshotDelta.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Opaque portable snapshot deltas and their public inspection models.
+ *
+ * @since 0.1.0
+ */
+import * as ByteSize from "effect/ByteSize";
+import * as Schema from "effect/Schema";
+import { BytePath } from "./BytePath.js";
+/** Type identifier for opaque snapshot deltas. */
+export declare const SnapshotDeltaTypeId: unique symbol;
+/** Type identifier for opaque snapshot deltas. */
+export type SnapshotDeltaTypeId = typeof SnapshotDeltaTypeId;
+/** An immutable, opaque description of the exact difference between two snapshots. */
+export interface SnapshotDelta {
+    readonly [SnapshotDeltaTypeId]: SnapshotDeltaTypeId;
+}
+/** @internal */
+export declare const makeSnapshotDelta: (value: object) => SnapshotDelta;
+/** @internal */
+export declare const snapshotDeltaValue: (delta: SnapshotDelta) => object | undefined;
+/** Schema for an already validated opaque snapshot delta. */
+export declare const SnapshotDelta: Schema.declare<SnapshotDelta, SnapshotDelta>;
+/** Schema for filesystem entry kinds reported by snapshot inspection. */
+export declare const SnapshotNodeKind: Schema.Literals<readonly ["directory", "file", "symlink"]>;
+/** A filesystem entry kind reported by snapshot inspection. */
+export type SnapshotNodeKind = typeof SnapshotNodeKind.Type;
+/** Schema for semantic fields that can differ between snapshots. */
+export declare const SnapshotDifference: Schema.Literals<readonly ["kind", "content", "target", "hardLinks", "mode", "uid", "gid", "atimeNs", "mtimeNs", "ctimeNs", "birthtimeNs"]>;
+/** A semantic field that differs between two snapshots. */
+export type SnapshotDifference = typeof SnapshotDifference.Type;
+/**
+ * Schema for a path-oriented difference between two snapshots.
+ *
+ * Independent snapshots do not preserve shared lineage, so moves are reported
+ * as a removal and an addition rather than an inferred rename.
+ */
+export declare const SnapshotChange: Schema.Union<readonly [Schema.TaggedStruct<"Added", {
+    readonly path: Schema.declare<BytePath, BytePath>;
+    readonly kind: Schema.Literals<readonly ["directory", "file", "symlink"]>;
+}>, Schema.TaggedStruct<"Removed", {
+    readonly path: Schema.declare<BytePath, BytePath>;
+    readonly kind: Schema.Literals<readonly ["directory", "file", "symlink"]>;
+}>, Schema.TaggedStruct<"Updated", {
+    readonly path: Schema.declare<BytePath, BytePath>;
+    readonly beforeKind: Schema.Literals<readonly ["directory", "file", "symlink"]>;
+    readonly afterKind: Schema.Literals<readonly ["directory", "file", "symlink"]>;
+    readonly differences: Schema.$Array<Schema.Literals<readonly ["kind", "content", "target", "hardLinks", "mode", "uid", "gid", "atimeNs", "mtimeNs", "ctimeNs", "birthtimeNs"]>>;
+}>]>;
+/** A path-oriented semantic difference between two snapshots. */
+export type SnapshotChange = typeof SnapshotChange.Type;
+/** Schema for snapshot-delta inspection options. */
+export declare const SnapshotChangesOptions: Schema.Struct<{
+    /** Include access, modification, change, and birth-time differences. Defaults to `false`. */
+    readonly includeTimestamps: Schema.optionalKey<Schema.Boolean>;
+}>;
+/** Filtering options for snapshot-delta inspection. */
+export type SnapshotChangesOptions = typeof SnapshotChangesOptions.Type;
+declare const SnapshotDeltaError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "SnapshotDeltaError";
+} & Readonly<A>;
+/** A valid snapshot delta was inspected or applied against a valid but semantically different base. */
+export declare class SnapshotDeltaError extends SnapshotDeltaError_base<{
+    readonly code: "BaseMismatch";
+}> {
+}
+declare const SnapshotDeltaLimitsSchema: Schema.Struct<{
+    readonly maxEncodedBytes: Schema.ByteSize;
+    readonly maxIdentityBytes: Schema.ByteSize;
+    readonly maxDeltaRecords: Schema.Finite;
+    readonly maxDecodedDeltaBytes: Schema.ByteSize;
+    readonly maxBaseRecords: Schema.Finite;
+    readonly maxTargetRecords: Schema.Finite;
+    readonly maxEntries: Schema.Finite;
+    readonly maxOutputRecords: Schema.Finite;
+    readonly maxOutputBytes: Schema.ByteSize;
+    readonly maxInheritedRecords: Schema.Finite;
+}>;
+/** Resource limits shared by delta creation, inspection, encoding, decoding, and application. */
+export type SnapshotDeltaLimits = typeof SnapshotDeltaLimitsSchema.Type;
+/** Constructs and freezes a complete snapshot-delta resource policy. @internal */
+export declare const makeSnapshotDeltaLimits: (limits: SnapshotDeltaLimits) => SnapshotDeltaLimits;
+/**
+ * Schema for a complete snapshot-delta resource policy, with frozen presets.
+ *
+ * The constrained preset is intended for memory-sensitive environments. The
+ * default preset permits larger snapshots and payloads while remaining finite.
+ */
+export declare const SnapshotDeltaLimits: Schema.Struct<{
+    readonly maxEncodedBytes: Schema.ByteSize;
+    readonly maxIdentityBytes: Schema.ByteSize;
+    readonly maxDeltaRecords: Schema.Finite;
+    readonly maxDecodedDeltaBytes: Schema.ByteSize;
+    readonly maxBaseRecords: Schema.Finite;
+    readonly maxTargetRecords: Schema.Finite;
+    readonly maxEntries: Schema.Finite;
+    readonly maxOutputRecords: Schema.Finite;
+    readonly maxOutputBytes: Schema.ByteSize;
+    readonly maxInheritedRecords: Schema.Finite;
+}> & {
+    constrained: {
+        readonly maxEncodedBytes: ByteSize.ByteSize;
+        readonly maxIdentityBytes: ByteSize.ByteSize;
+        readonly maxDeltaRecords: number;
+        readonly maxDecodedDeltaBytes: ByteSize.ByteSize;
+        readonly maxBaseRecords: number;
+        readonly maxTargetRecords: number;
+        readonly maxEntries: number;
+        readonly maxOutputRecords: number;
+        readonly maxOutputBytes: ByteSize.ByteSize;
+        readonly maxInheritedRecords: number;
+    };
+    default: {
+        readonly maxEncodedBytes: ByteSize.ByteSize;
+        readonly maxIdentityBytes: ByteSize.ByteSize;
+        readonly maxDeltaRecords: number;
+        readonly maxDecodedDeltaBytes: ByteSize.ByteSize;
+        readonly maxBaseRecords: number;
+        readonly maxTargetRecords: number;
+        readonly maxEntries: number;
+        readonly maxOutputRecords: number;
+        readonly maxOutputBytes: ByteSize.ByteSize;
+        readonly maxInheritedRecords: number;
+    };
+};
+export {};
+//# sourceMappingURL=SnapshotDelta.d.ts.map

package/dist/SnapshotDelta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SnapshotDelta.d.ts","sourceRoot":"","sources":["../src/SnapshotDelta.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAE3C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAQxC,kDAAkD;AAClD,eAAO,MAAM,mBAAmB,eAA2C,CAAA;AAC3E,kDAAkD;AAClD,MAAM,MAAM,mBAAmB,GAAG,OAAO,mBAAmB,CAAA;AAE5D,sFAAsF;AACtF,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,CAAC,mBAAmB,CAAC,EAAE,mBAAmB,CAAA;CACpD;AAID,gBAAgB;AAChB,eAAO,MAAM,iBAAiB,UAAW,MAAM,KAAG,aAIjD,CAAA;AAED,gBAAgB;AAChB,eAAO,MAAM,kBAAkB,UAAW,aAAa,KAAG,MAAM,GAAG,SAAsC,CAAA;AAEzG,6DAA6D;AAC7D,eAAO,MAAM,aAAa,8CAEzB,CAAA;AAED,yEAAyE;AACzE,eAAO,MAAM,gBAAgB,4DAAoD,CAAA;AACjF,+DAA+D;AAC/D,MAAM,MAAM,gBAAgB,GAAG,OAAO,gBAAgB,CAAC,IAAI,CAAA;AAE3D,oEAAoE;AACpE,eAAO,MAAM,kBAAkB,4IAY7B,CAAA;AACF,2DAA2D;AAC3D,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC,IAAI,CAAA;AAI/D;;;;;GAKG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;IASzB,CAAA;AACF,iEAAiE;AACjE,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAA;AAEvD,oDAAoD;AACpD,eAAO,MAAM,sBAAsB;IACjC,6FAA6F;;EAE7F,CAAA;AACF,uDAAuD;AACvD,MAAM,MAAM,sBAAsB,GAAG,OAAO,sBAAsB,CAAC,IAAI,CAAA;;;;AAEvE,uGAAuG;AACvG,qBAAa,kBAAmB,SAAQ,wBAAuC;IAC7E,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAC9B,CAAC;CAAG;AAEL,QAAA,MAAM,yBAAyB;;;;;;;;;;;EAW7B,CAAA;AACF,iGAAiG;AACjG,MAAM,MAAM,mBAAmB,GAAG,OAAO,yBAAyB,CAAC,IAAI,CAAA;AAEvE,kFAAkF;AAClF,eAAO,MAAM,uBAAuB,WAAY,mBAAmB,KAAG,mBACxC,CAAA;AA2B9B;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAG9B,CAAA"}

package/dist/SnapshotDelta.js

@@ -0,0 +1,112 @@
+/**
+ * Opaque portable snapshot deltas and their public inspection models.
+ *
+ * @since 0.1.0
+ */
+import * as ByteSize from "effect/ByteSize";
+import * as Data from "effect/Data";
+import * as Schema from "effect/Schema";
+import { BytePath } from "./BytePath.js";
+const Natural = Schema.Finite.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER));
+/** Type identifier for opaque snapshot deltas. */
+export const SnapshotDeltaTypeId = Symbol("@effect-vfs/core/SnapshotDelta");
+const snapshotDeltas = new WeakMap();
+/** @internal */
+export const makeSnapshotDelta = (value) => {
+    const delta = Object.freeze({ [SnapshotDeltaTypeId]: SnapshotDeltaTypeId });
+    snapshotDeltas.set(delta, value);
+    return delta;
+};
+/** @internal */
+export const snapshotDeltaValue = (delta) => snapshotDeltas.get(delta);
+/** Schema for an already validated opaque snapshot delta. */
+export const SnapshotDelta = Schema.declare((value) => typeof value === "object" && value !== null && snapshotDeltas.has(value));
+/** Schema for filesystem entry kinds reported by snapshot inspection. */
+export const SnapshotNodeKind = Schema.Literals(["directory", "file", "symlink"]);
+/** Schema for semantic fields that can differ between snapshots. */
+export const SnapshotDifference = Schema.Literals([
+    "kind",
+    "content",
+    "target",
+    "hardLinks",
+    "mode",
+    "uid",
+    "gid",
+    "atimeNs",
+    "mtimeNs",
+    "ctimeNs",
+    "birthtimeNs"
+]);
+const SnapshotDifferences = Schema.Array(SnapshotDifference).check(Schema.isMinLength(1));
+/**
+ * Schema for a path-oriented difference between two snapshots.
+ *
+ * Independent snapshots do not preserve shared lineage, so moves are reported
+ * as a removal and an addition rather than an inferred rename.
+ */
+export const SnapshotChange = Schema.Union([
+    Schema.TaggedStruct("Added", { path: BytePath, kind: SnapshotNodeKind }),
+    Schema.TaggedStruct("Removed", { path: BytePath, kind: SnapshotNodeKind }),
+    Schema.TaggedStruct("Updated", {
+        path: BytePath,
+        beforeKind: SnapshotNodeKind,
+        afterKind: SnapshotNodeKind,
+        differences: SnapshotDifferences
+    })
+]);
+/** Schema for snapshot-delta inspection options. */
+export const SnapshotChangesOptions = Schema.Struct({
+    /** Include access, modification, change, and birth-time differences. Defaults to `false`. */
+    includeTimestamps: Schema.optionalKey(Schema.Boolean)
+});
+/** A valid snapshot delta was inspected or applied against a valid but semantically different base. */
+export class SnapshotDeltaError extends Data.TaggedError("SnapshotDeltaError") {
+}
+const SnapshotDeltaLimitsSchema = Schema.Struct({
+    maxEncodedBytes: Schema.ByteSize,
+    maxIdentityBytes: Schema.ByteSize,
+    maxDeltaRecords: Natural,
+    maxDecodedDeltaBytes: Schema.ByteSize,
+    maxBaseRecords: Natural,
+    maxTargetRecords: Natural,
+    maxEntries: Natural,
+    maxOutputRecords: Natural,
+    maxOutputBytes: Schema.ByteSize,
+    maxInheritedRecords: Natural
+});
+/** Constructs and freezes a complete snapshot-delta resource policy. @internal */
+export const makeSnapshotDeltaLimits = (limits) => Object.freeze({ ...limits });
+const constrained = makeSnapshotDeltaLimits({
+    maxEncodedBytes: ByteSize.mebibytes(2),
+    maxIdentityBytes: ByteSize.mebibytes(4),
+    maxDeltaRecords: 6_500,
+    maxDecodedDeltaBytes: ByteSize.kibibytes(512),
+    maxBaseRecords: 6_500,
+    maxTargetRecords: 6_500,
+    maxEntries: 6_500,
+    maxOutputRecords: 6_500,
+    maxOutputBytes: ByteSize.kibibytes(256),
+    maxInheritedRecords: 6_500
+});
+const defaultLimits = makeSnapshotDeltaLimits({
+    maxEncodedBytes: ByteSize.mebibytes(16),
+    maxIdentityBytes: ByteSize.mebibytes(32),
+    maxDeltaRecords: 50_000,
+    maxDecodedDeltaBytes: ByteSize.mebibytes(8),
+    maxBaseRecords: 50_000,
+    maxTargetRecords: 50_000,
+    maxEntries: 100_000,
+    maxOutputRecords: 50_000,
+    maxOutputBytes: ByteSize.mebibytes(4),
+    maxInheritedRecords: 50_000
+});
+/**
+ * Schema for a complete snapshot-delta resource policy, with frozen presets.
+ *
+ * The constrained preset is intended for memory-sensitive environments. The
+ * default preset permits larger snapshots and payloads while remaining finite.
+ */
+export const SnapshotDeltaLimits = Object.assign(SnapshotDeltaLimitsSchema, {
+    constrained,
+    default: defaultLimits
+});

package/dist/VirtualFileSystem.d.ts

@@ -1,3 +1,14 @@
+/**
+ * Runtime-neutral virtual filesystem contracts and constructors.
+ *
+ * **Details**
+ *
+ * Volumes own isolated namespaces. Callers carry path context and credentials,
+ * while file and directory handles use `Scope` for deterministic release.
+ *
+ * @since 0.1.0
+ */
+import * as ByteSize from "effect/ByteSize";
 import * as Context from "effect/Context";
 import { DecodeLimits, ImageError, type Snapshot } from "./Snapshot.js";
 export { DecodeLimits, ImageError, type Snapshot, SnapshotTypeId } from "./Snapshot.js";
@@ -5,27 +16,14 @@ import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
 import * as Scope from "effect/Scope";
 import * as Stream from "effect/Stream";
-declare const BytePathId: unique symbol;
+import { BytePath } from "./BytePath.js";
+export { BytePath } from "./BytePath.js";
+import * as SnapshotDeltaModel from "./SnapshotDelta.js";
+export { SnapshotChange, SnapshotChangesOptions, type SnapshotDelta, SnapshotDeltaError, SnapshotDeltaLimits, SnapshotDeltaTypeId, SnapshotDifference, SnapshotNodeKind } from "./SnapshotDelta.js";
 declare const VolumeId: unique symbol;
 declare const CallerId: unique symbol;
 declare const FileHandleId: unique symbol;
 declare const DirectoryHandleId: unique symbol;
-/**
- * An opaque path that preserves arbitrary non-NUL bytes without UTF-8 conversion.
- *
- * @category models
- * @since 0.1.0
- */
-export interface BytePath {
-    readonly [BytePathId]: true;
-}
-/**
- * Schema for an opaque byte-preserving filesystem path.
- *
- * @category schemas
- * @since 0.1.0
- */
-export declare const BytePath: Schema.declare<BytePath, BytePath>;
 /**
  * A UTF-8 string path or an opaque byte-preserving path.
  *
@@ -140,11 +138,11 @@ export declare const VolumeOptions: Schema.Struct<{
     /** Maximum number of filesystem nodes. Omission leaves the count unbounded. */
     readonly maxEntries: Schema.optionalKey<Schema.Finite>;
     /** Maximum combined regular-file content in bytes. */
-    readonly maxBytes: Schema.optionalKey<Schema.Finite>;
+    readonly maxBytes: Schema.optionalKey<Schema.ByteSize>;
     /** Maximum content size of one regular file in bytes. */
-    readonly maxFileBytes: Schema.optionalKey<Schema.Finite>;
+    readonly maxFileBytes: Schema.optionalKey<Schema.ByteSize>;
     /** Maximum encoded byte length of an absolute or relative path. */
-    readonly maxPathBytes: Schema.optionalKey<Schema.Finite>;
+    readonly maxPathBytes: Schema.optionalKey<Schema.ByteSize>;
 }>;
 /**
  * Capacity and path limits for a volume.
@@ -603,6 +601,81 @@ export declare const encodeSnapshot: (snapshot: Snapshot) => Effect.Effect<Uint8
  * @since 0.1.0
  */
 export declare const decodeSnapshot: (input: Uint8Array, limits: DecodeLimits) => Effect.Effect<Snapshot, ImageError>;
+/**
+ * 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 declare const diffSnapshots: (base: Snapshot, target: Snapshot, limits?: {
+    readonly maxEncodedBytes: ByteSize.ByteSize;
+    readonly maxIdentityBytes: ByteSize.ByteSize;
+    readonly maxDeltaRecords: number;
+    readonly maxDecodedDeltaBytes: ByteSize.ByteSize;
+    readonly maxBaseRecords: number;
+    readonly maxTargetRecords: number;
+    readonly maxEntries: number;
+    readonly maxOutputRecords: number;
+    readonly maxOutputBytes: ByteSize.ByteSize;
+    readonly maxInheritedRecords: number;
+} | undefined) => Effect.Effect<SnapshotDeltaModel.SnapshotDelta, ConfigurationError | ImageError | import("effect/PlatformError").PlatformError, import("effect/Crypto").Crypto>;
+/**
+ * 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 declare const inspectSnapshotDelta: (base: Snapshot, delta: SnapshotDeltaModel.SnapshotDelta, options?: {
+    readonly includeTimestamps?: boolean;
+} | undefined, limits?: {
+    readonly maxEncodedBytes: ByteSize.ByteSize;
+    readonly maxIdentityBytes: ByteSize.ByteSize;
+    readonly maxDeltaRecords: number;
+    readonly maxDecodedDeltaBytes: ByteSize.ByteSize;
+    readonly maxBaseRecords: number;
+    readonly maxTargetRecords: number;
+    readonly maxEntries: number;
+    readonly maxOutputRecords: number;
+    readonly maxOutputBytes: ByteSize.ByteSize;
+    readonly maxInheritedRecords: number;
+} | undefined) => Effect.Effect<readonly ({
+    readonly _tag: "Added";
+    readonly path: BytePath;
+    readonly kind: "directory" | "file" | "symlink";
+} | {
+    readonly _tag: "Removed";
+    readonly path: BytePath;
+    readonly kind: "directory" | "file" | "symlink";
+} | {
+    readonly _tag: "Updated";
+    readonly path: BytePath;
+    readonly beforeKind: "directory" | "file" | "symlink";
+    readonly afterKind: "directory" | "file" | "symlink";
+    readonly differences: readonly ("atimeNs" | "birthtimeNs" | "content" | "ctimeNs" | "gid" | "hardLinks" | "kind" | "mode" | "mtimeNs" | "target" | "uid")[];
+})[], ConfigurationError | ImageError | import("effect/PlatformError").PlatformError | SnapshotDeltaModel.SnapshotDeltaError, import("effect/Crypto").Crypto>;
+/**
+ * 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 declare const applySnapshotDelta: (base: Snapshot, delta: SnapshotDeltaModel.SnapshotDelta, limits?: {
+    readonly maxEncodedBytes: ByteSize.ByteSize;
+    readonly maxIdentityBytes: ByteSize.ByteSize;
+    readonly maxDeltaRecords: number;
+    readonly maxDecodedDeltaBytes: ByteSize.ByteSize;
+    readonly maxBaseRecords: number;
+    readonly maxTargetRecords: number;
+    readonly maxEntries: number;
+    readonly maxOutputRecords: number;
+    readonly maxOutputBytes: ByteSize.ByteSize;
+    readonly maxInheritedRecords: number;
+} | undefined) => Effect.Effect<Snapshot, ConfigurationError | ImageError | import("effect/PlatformError").PlatformError | SnapshotDeltaModel.SnapshotDeltaError, import("effect/Crypto").Crypto>;
+/**
+ * Creates an Effect Schema codec between owned bytes and opaque snapshot deltas.
+ * Omission uses `SnapshotDeltaLimits.default`.
+ */
+export declare const SnapshotDeltaFromBytes: (limits?: SnapshotDeltaModel.SnapshotDeltaLimits) => Schema.decodeTo<Schema.declare<SnapshotDeltaModel.SnapshotDelta, SnapshotDeltaModel.SnapshotDelta>, Schema.Uint8Array, never, never>;
 /**
  * Creates an opaque byte path by copying the input when the Effect executes.
  *
@@ -634,9 +707,9 @@ export declare const pathToBytes: (path: BytePath) => Effect.Effect<Uint8Array<A
  */
 export declare const make: (options?: {
     readonly maxEntries?: number;
-    readonly maxBytes?: number;
-    readonly maxFileBytes?: number;
-    readonly maxPathBytes?: number;
+    readonly maxBytes?: ByteSize.ByteSize;
+    readonly maxFileBytes?: ByteSize.ByteSize;
+    readonly maxPathBytes?: ByteSize.ByteSize;
 } | undefined) => Effect.Effect<Volume, ConfigurationError, never>;
 /**
  * Restores a fresh volume from an opaque snapshot under the supplied destination limits.
@@ -646,9 +719,9 @@ export declare const make: (options?: {
  */
 export declare const fromSnapshot: (snapshot: Snapshot, options?: {
     readonly maxEntries?: number;
-    readonly maxBytes?: number;
-    readonly maxFileBytes?: number;
-    readonly maxPathBytes?: number;
+    readonly maxBytes?: ByteSize.ByteSize;
+    readonly maxFileBytes?: ByteSize.ByteSize;
+    readonly maxPathBytes?: ByteSize.ByteSize;
 } | undefined) => Effect.Effect<Volume, ConfigurationError | ImageError, never>;
 /**
  * Creates an isolated writable volume relative to one immutable snapshot base.
@@ -668,9 +741,9 @@ export declare const fromSnapshot: (snapshot: Snapshot, options?: {
  */
 export declare const makeOverlay: (base: Snapshot, options?: {
     readonly maxEntries?: number;
-    readonly maxBytes?: number;
-    readonly maxFileBytes?: number;
-    readonly maxPathBytes?: number;
+    readonly maxBytes?: ByteSize.ByteSize;
+    readonly maxFileBytes?: ByteSize.ByteSize;
+    readonly maxPathBytes?: ByteSize.ByteSize;
 } | undefined) => Effect.Effect<OverlayVolume, ConfigurationError | ImageError, never>;
 /**
  * Schema for a complete fixture namespace with optional metadata and forward hard links.
@@ -804,8 +877,8 @@ export declare const fromFixture: (fixture: {
     })[];
 }, options?: {
     readonly maxEntries?: number;
-    readonly maxBytes?: number;
-    readonly maxFileBytes?: number;
-    readonly maxPathBytes?: number;
+    readonly maxBytes?: ByteSize.ByteSize;
+    readonly maxFileBytes?: ByteSize.ByteSize;
+    readonly maxPathBytes?: ByteSize.ByteSize;
 } | undefined) => Effect.Effect<Volume, ConfigurationError | ImageError, never>;
 //# sourceMappingURL=VirtualFileSystem.d.ts.map