@effect-vfs/core 0.0.1 → 0.2.0

package/README.md

@@ -10,16 +10,16 @@ Effect's standard `FileSystem` service, use [`@effect-vfs/memory`](https://www.n
 which adapts this package to that interface.
 
 The package implements a documented subset of POSIX behavior. It does not claim full POSIX conformance. See the
-[implemented profile](https://github.com/lloydrichards/effect-virtual-fs/blob/main/.docs/context/implemented-profile.md)
+[implemented profile](https://github.com/lloydrichards/effect-virtual-fs/blob/main/.okf/profiles/implemented-filesystem.md)
 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*() {
@@ -174,6 +175,141 @@ Snapshot decoding requires explicit work limits because encoded bytes may come f
 contains the reachable namespace and metadata. It excludes callers, open handles, cursor positions, watch
 subscriptions, and unlinked content. Each restored volume is independent.
 
+## Branch from one immutable snapshot
+
+Use `makeOverlay` when several writable workspaces start from the same snapshot. Untouched regular-file contents are
+shared internally. A content change copies that whole file for the editing workspace; namespace and metadata state are
+always private. Logical quotas still count the complete visible volume, including shared base files and unlinked-open
+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({
+    entries: [
+      { kind: "directory", path: "/project" },
+      { kind: "file", path: "/project/settings.json", bytes: new Uint8Array() }
+    ]
+  })
+  const base = yield* template.snapshot
+  const workspace = yield* Vfs.makeOverlay(base, { maxBytes: ByteSize.megabytes(1) })
+  const fs = yield* workspace.caller()
+
+  yield* fs.rename("/project/settings.json", "/project/preferences.json")
+  return yield* workspace.capture()
+})
+```
+
+`makeOverlay(base, options)` returns a reusable Effect. Each execution creates a fresh workspace from `base`; it does
+not memoize or reset an earlier workspace. Invalid volume options fail with `ConfigurationError`, while failure to
+inspect the base snapshot fails with `ImageError`.
+
+`changes()` reports final differences from the base. It hides timestamp-only differences unless called with
+`{ includeTimestamps: true }`. Renames are paired only from retained object identity; equal contents are never treated
+as rename evidence. Paths in summaries are `BytePath` values, so inspect them with `pathToBytes` when names may not be
+UTF-8. Although `OverlayChange` and its options have schemas, a summary is an in-process value containing opaque
+`BytePath` objects. The schema is not a portable summary encoding.
+
+`capture()` returns a complete version 1 snapshot and matching summary from one committed state. Later writes change
+neither result. The snapshot works with `encodeSnapshot`, `fromSnapshot`, and `@effect-vfs/persistence` checkpoints.
+Restoring it recovers the complete filesystem state, not the earlier overlay base relationship or summary. To reset,
+create a fresh overlay from the base and replace your application reference; existing callers, handles, and watches
+remain attached to the old workspace until their own lifetimes end.
+
+The Effects returned by `changes(options)` and `capture(options)` are also reusable. Each execution observes the
+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
@@ -280,4 +416,4 @@ candidate.
 - `sync` checks handle liveness. An in-memory volume provides no host or crash durability.
 
 For the complete contract, read the
-[implemented profile](https://github.com/lloydrichards/effect-virtual-fs/blob/main/.docs/context/implemented-profile.md).
+[implemented profile](https://github.com/lloydrichards/effect-virtual-fs/blob/main/.okf/profiles/implemented-filesystem.md).

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
+});