@effect-vfs/core 0.1.0 → 0.3.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,34 @@
+import type * as Equal from "effect/Equal";
+import type { Pipeable } from "effect/Pipeable";
+import * as Schema from "effect/Schema";
+/**
+ * Type identifier for opaque byte-preserving filesystem paths.
+ *
+ * @category type ids
+ * @since 0.1.0
+ */
+export declare const BytePathId: "@effect-vfs/core/BytePath";
+/**
+ * Type identifier for opaque byte-preserving filesystem paths.
+ *
+ * @category type ids
+ * @since 0.1.0
+ */
+export type BytePathId = typeof BytePathId;
+/**
+ * An opaque path that preserves arbitrary non-NUL bytes without UTF-8 conversion.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface BytePath extends Equal.Equal, Pipeable {
+    readonly [BytePathId]: BytePathId;
+}
+/**
+ * Schema for an opaque byte-preserving filesystem path.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const BytePath: Schema.declare<BytePath, BytePath>;
+//# 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,KAAK,KAAK,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC;;;;;GAKG;AACH,eAAO,MAAM,UAAU,EAAE,2BAAiD,CAAA;AAE1E;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAA;AAE1C;;;;;GAKG;AACH,MAAM,WAAW,QAAS,SAAQ,KAAK,CAAC,KAAK,EAAE,QAAQ;IACrD,QAAQ,CAAC,CAAC,UAAU,CAAC,EAAE,UAAU,CAAA;CAClC;AAED;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,oCAAgD,CAAA"}

package/dist/BytePath.js

@@ -0,0 +1,16 @@
+import * as Schema from "effect/Schema";
+import * as Internal from "./internal/bytePath.js";
+/**
+ * Type identifier for opaque byte-preserving filesystem paths.
+ *
+ * @category type ids
+ * @since 0.1.0
+ */
+export const BytePathId = Internal.BytePathId;
+/**
+ * Schema for an opaque byte-preserving filesystem path.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const BytePath = Schema.declare(Internal.isBytePath);

package/dist/Snapshot.d.ts

@@ -5,7 +5,7 @@ import * as Schema from "effect/Schema";
  * @category type ids
  * @since 0.1.0
  */
-export declare const SnapshotTypeId: unique symbol;
+export declare const SnapshotTypeId: "@effect-vfs/core/Snapshot";
 /**
  * Type identifier for opaque filesystem snapshots.
  *
@@ -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;
+    readonly maxRecords: Schema.Natural;
     /** Maximum number of namespace entries. */
-    readonly maxEntries: Schema.Finite;
+    readonly maxEntries: Schema.Natural;
     /** Maximum combined decoded byte content. */
-    readonly maxDecodedBytes: Schema.Finite;
+    readonly maxDecodedBytes: Schema.ByteSize;
 }>;
 /**
  * Resource limits applied while decoding a snapshot.

package/dist/Snapshot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Snapshot.d.ts","sourceRoot":"","sources":["../src/Snapshot.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAQvC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,eAAsC,CAAA;AAEjE;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAA;AAElD;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,cAAc,CAAA;CAC1C;;;;AAED;;;;;GAKG;AACH,qBAAa,UAAW,SAAQ,gBAA+B;IAC7D,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,GAAG,oBAAoB,GAAG,kBAAkB,GAAG,eAAe,CAAA;IAC9F,kFAAkF;IAClF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB,CAAC;CAAG;AAEL;;;;;GAKG;AACH,eAAO,MAAM,YAAY;IACvB,sDAAsD;;IAEtD,6DAA6D;;IAE7D,2CAA2C;;IAE3C,6CAA6C;;EAE7C,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAA"}
+{"version":3,"file":"Snapshot.d.ts","sourceRoot":"","sources":["../src/Snapshot.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAG,2BAAoC,CAAA;AAElE;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAA;AAElD;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,cAAc,CAAA;CAC1C;;;;AAED;;;;;GAKG;AACH,qBAAa,UAAW,SAAQ,gBAA+B;IAC7D,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,GAAG,oBAAoB,GAAG,kBAAkB,GAAG,eAAe,CAAA;IAC9F,kFAAkF;IAClF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB,CAAC;CAAG;AAEL;;;;;GAKG;AACH,eAAO,MAAM,YAAY;IACvB,sDAAsD;;IAEtD,6DAA6D;;IAE7D,2CAA2C;;IAE3C,6CAA6C;;EAE7C,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAA"}

package/dist/Snapshot.js

@@ -9,14 +9,13 @@
  */
 import * as Data from "effect/Data";
 import * as Schema from "effect/Schema";
-const Natural = Schema.Finite.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER));
 /**
  * Type identifier for opaque filesystem snapshots.
  *
  * @category type ids
  * @since 0.1.0
  */
-export const SnapshotTypeId = Symbol("@effect-vfs/core/Snapshot");
+export const SnapshotTypeId = "@effect-vfs/core/Snapshot";
 /**
  * Describes a snapshot encoding, decoding, structure, or resource-limit failure.
  *
@@ -33,11 +32,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,
+    maxRecords: Schema.Natural,
     /** Maximum number of namespace entries. */
-    maxEntries: Natural,
+    maxEntries: Schema.Natural,
     /** Maximum combined decoded byte content. */
-    maxDecodedBytes: Natural
+    maxDecodedBytes: Schema.ByteSize
 });

package/dist/SnapshotDelta.d.ts

@@ -0,0 +1,193 @@
+/**
+ * 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.
+ *
+ * @category type ids
+ * @since 0.1.0
+ */
+export declare const SnapshotDeltaTypeId: "@effect-vfs/core/SnapshotDelta";
+/**
+ * Type identifier for opaque snapshot deltas.
+ *
+ * @category type ids
+ * @since 0.1.0
+ */
+export type SnapshotDeltaTypeId = typeof SnapshotDeltaTypeId;
+/**
+ * An immutable, opaque description of the exact difference between two snapshots.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface SnapshotDelta {
+    readonly [SnapshotDeltaTypeId]: SnapshotDeltaTypeId;
+}
+/**
+ * Schema for an already validated opaque snapshot delta.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const SnapshotDelta: Schema.declare<SnapshotDelta, SnapshotDelta>;
+/**
+ * Schema for filesystem entry kinds reported by snapshot inspection.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const SnapshotNodeKind: Schema.Literals<readonly ["directory", "file", "symlink"]>;
+/**
+ * A filesystem entry kind reported by snapshot inspection.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type SnapshotNodeKind = typeof SnapshotNodeKind.Type;
+/**
+ * Schema for semantic fields that can differ between snapshots.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+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.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+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.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+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.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type SnapshotChange = typeof SnapshotChange.Type;
+/**
+ * Schema for snapshot-delta inspection options.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+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.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+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.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+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.Natural;
+    readonly maxDecodedDeltaBytes: Schema.ByteSize;
+    readonly maxBaseRecords: Schema.Natural;
+    readonly maxTargetRecords: Schema.Natural;
+    readonly maxEntries: Schema.Natural;
+    readonly maxOutputRecords: Schema.Natural;
+    readonly maxOutputBytes: Schema.ByteSize;
+    readonly maxInheritedRecords: Schema.Natural;
+}>;
+/**
+ * Resource limits shared by delta creation, inspection, encoding, decoding, and application.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+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.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const SnapshotDeltaLimits: Schema.Struct<{
+    readonly maxEncodedBytes: Schema.ByteSize;
+    readonly maxIdentityBytes: Schema.ByteSize;
+    readonly maxDeltaRecords: Schema.Natural;
+    readonly maxDecodedDeltaBytes: Schema.ByteSize;
+    readonly maxBaseRecords: Schema.Natural;
+    readonly maxTargetRecords: Schema.Natural;
+    readonly maxEntries: Schema.Natural;
+    readonly maxOutputRecords: Schema.Natural;
+    readonly maxOutputBytes: Schema.ByteSize;
+    readonly maxInheritedRecords: Schema.Natural;
+}> & {
+    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;AAGxC;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,gCAA+D,CAAA;AAEjG;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,mBAAmB,CAAA;AAE5D;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,CAAC,mBAAmB,CAAC,EAAE,mBAAmB,CAAA;CACpD;AAED;;;;;GAKG;AACH,eAAO,MAAM,aAAa,8CAA0D,CAAA;AAEpF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,4DAAoD,CAAA;AAEjF;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,gBAAgB,CAAC,IAAI,CAAA;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,4IAY7B,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC,IAAI,CAAA;AAI/D;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;IASzB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAA;AAEvD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB;IACjC,6FAA6F;;EAE7F,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG,OAAO,sBAAsB,CAAC,IAAI,CAAA;;;;AAEvE;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,wBAAuC;IAC7E,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAC9B,CAAC;CAAG;AAEL,QAAA,MAAM,yBAAyB;;;;;;;;;;;EAW7B,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,yBAAyB,CAAC,IAAI,CAAA;AAEvE,kFAAkF;AAClF,eAAO,MAAM,uBAAuB,WAAY,mBAAmB,KAAG,mBACxC,CAAA;AA2B9B;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAG9B,CAAA"}

package/dist/SnapshotDelta.js

@@ -0,0 +1,139 @@
+/**
+ * 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";
+import * as Internal from "./internal/snapshotDeltaModel.js";
+/**
+ * Type identifier for opaque snapshot deltas.
+ *
+ * @category type ids
+ * @since 0.1.0
+ */
+export const SnapshotDeltaTypeId = Internal.SnapshotDeltaTypeId;
+/**
+ * Schema for an already validated opaque snapshot delta.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const SnapshotDelta = Schema.declare(Internal.isSnapshotDelta);
+/**
+ * Schema for filesystem entry kinds reported by snapshot inspection.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const SnapshotNodeKind = Schema.Literals(["directory", "file", "symlink"]);
+/**
+ * Schema for semantic fields that can differ between snapshots.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+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.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+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.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+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.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export class SnapshotDeltaError extends Data.TaggedError("SnapshotDeltaError") {
+}
+const SnapshotDeltaLimitsSchema = Schema.Struct({
+    maxEncodedBytes: Schema.ByteSize,
+    maxIdentityBytes: Schema.ByteSize,
+    maxDeltaRecords: Schema.Natural,
+    maxDecodedDeltaBytes: Schema.ByteSize,
+    maxBaseRecords: Schema.Natural,
+    maxTargetRecords: Schema.Natural,
+    maxEntries: Schema.Natural,
+    maxOutputRecords: Schema.Natural,
+    maxOutputBytes: Schema.ByteSize,
+    maxInheritedRecords: Schema.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.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const SnapshotDeltaLimits = Object.assign(SnapshotDeltaLimitsSchema, {
+    constrained,
+    default: defaultLimits
+});