@effect-vfs/core 0.3.0 → 0.3.1

package/dist/BytePath.d.ts

@@ -1,23 +1,54 @@
+/**
+ * Opaque, byte-preserving filesystem paths.
+ *
+ * A `BytePath` stores the exact bytes of a path component so that names which
+ * are not valid UTF-8 survive a round trip through the virtual filesystem.
+ *
+ * @since 0.1.0
+ */
 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
+ * @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
+ * @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.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import { Effect } from "effect"
+ *
+ * // A name that is not valid UTF-8 still round-trips exactly.
+ * const program = Effect.gen(function*() {
+ *   const caller = yield* (yield* Vfs.make()).caller()
+ *   const path = yield* Vfs.pathFromBytes(new Uint8Array([47, 0xff, 0xfe]))
+ *
+ *   yield* caller.writeFile(path, new Uint8Array([1]), {
+ *     access: "write",
+ *     create: "exclusive"
+ *   })
+ *
+ *   // `readDirectory` fails `UnrepresentableName` here; the byte variant keeps it.
+ *   return yield* caller.readDirectoryBytes("/")
+ * })
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // [ Uint8Array(2) [ 255, 254 ] ]
+ * ```
+ *
  * @category models
  * @since 0.1.0
  */

package/dist/BytePath.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"BytePath.d.ts","sourceRoot":"","sources":["../src/BytePath.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;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

@@ -3,7 +3,7 @@ import * as Internal from "./internal/bytePath.js";
 /**
  * Type identifier for opaque byte-preserving filesystem paths.
  *
- * @category type ids
+ * @category type IDs
  * @since 0.1.0
  */
 export const BytePathId = Internal.BytePathId;

package/dist/Snapshot.d.ts

@@ -2,14 +2,14 @@ import * as Schema from "effect/Schema";
 /**
  * Type identifier for opaque filesystem snapshots.
  *
- * @category type ids
+ * @category type IDs
  * @since 0.1.0
  */
 export declare const SnapshotTypeId: "@effect-vfs/core/Snapshot";
 /**
  * Type identifier for opaque filesystem snapshots.
  *
- * @category type ids
+ * @category type IDs
  * @since 0.1.0
  */
 export type SnapshotTypeId = typeof SnapshotTypeId;
@@ -28,6 +28,35 @@ declare const ImageError_base: new <A extends Record<string, any> = {}>(args: im
 /**
  * Describes a snapshot encoding, decoding, structure, or resource-limit failure.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import { ByteSize, Effect } from "effect"
+ *
+ * // Decoding is a trust boundary. `code` says what went wrong and `field` says
+ * // which input or limit it was, so a caller can decline just the bad payload.
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make()
+ *   const bytes = yield* Vfs.encodeSnapshot(yield* volume.snapshot)
+ *
+ *   return yield* Vfs.decodeSnapshot(bytes, {
+ *     maxEncodedBytes: ByteSize.bytes(16),
+ *     maxRecords: 10_000,
+ *     maxEntries: 10_000,
+ *     maxDecodedBytes: ByteSize.megabytes(16)
+ *   }).pipe(
+ *     Effect.as("accepted"),
+ *     Effect.catchTag("ImageError", (error) =>
+ *       error.code === "LimitExceeded"
+ *         ? Effect.succeed(`declined at ${error.field}`)
+ *         : Effect.fail(error))
+ *   )
+ * })
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // declined at encodedBytes
+ * ```
+ *
  * @category errors
  * @since 0.1.0
  */
@@ -41,6 +70,33 @@ export declare class ImageError extends ImageError_base<{
 /**
  * Schema for the mandatory resource limits applied while decoding a snapshot.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import { ByteSize, Effect } from "effect"
+ *
+ * // All four are required: each bounds a different resource. `maxEncodedBytes`
+ * // caps the wire payload before parsing; `maxDecodedBytes` caps memory after it.
+ * const limits: Vfs.DecodeLimits = {
+ *   maxEncodedBytes: ByteSize.megabytes(4),
+ *   maxRecords: 10_000,
+ *   maxEntries: 10_000,
+ *   maxDecodedBytes: ByteSize.megabytes(16)
+ * }
+ *
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make()
+ *   const bytes = yield* Vfs.encodeSnapshot(yield* volume.snapshot)
+ *
+ *   yield* Vfs.decodeSnapshot(bytes, limits)
+ *
+ *   return "accepted"
+ * })
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // accepted
+ * ```
+ *
  * @category schemas
  * @since 0.1.0
  */

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;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"}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;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

@@ -12,13 +12,42 @@ import * as Schema from "effect/Schema";
 /**
  * Type identifier for opaque filesystem snapshots.
  *
- * @category type ids
+ * @category type IDs
  * @since 0.1.0
  */
 export const SnapshotTypeId = "@effect-vfs/core/Snapshot";
 /**
  * Describes a snapshot encoding, decoding, structure, or resource-limit failure.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import { ByteSize, Effect } from "effect"
+ *
+ * // Decoding is a trust boundary. `code` says what went wrong and `field` says
+ * // which input or limit it was, so a caller can decline just the bad payload.
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make()
+ *   const bytes = yield* Vfs.encodeSnapshot(yield* volume.snapshot)
+ *
+ *   return yield* Vfs.decodeSnapshot(bytes, {
+ *     maxEncodedBytes: ByteSize.bytes(16),
+ *     maxRecords: 10_000,
+ *     maxEntries: 10_000,
+ *     maxDecodedBytes: ByteSize.megabytes(16)
+ *   }).pipe(
+ *     Effect.as("accepted"),
+ *     Effect.catchTag("ImageError", (error) =>
+ *       error.code === "LimitExceeded"
+ *         ? Effect.succeed(`declined at ${error.field}`)
+ *         : Effect.fail(error))
+ *   )
+ * })
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // declined at encodedBytes
+ * ```
+ *
  * @category errors
  * @since 0.1.0
  */
@@ -27,6 +56,33 @@ export class ImageError extends Data.TaggedError("ImageError") {
 /**
  * Schema for the mandatory resource limits applied while decoding a snapshot.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import { ByteSize, Effect } from "effect"
+ *
+ * // All four are required: each bounds a different resource. `maxEncodedBytes`
+ * // caps the wire payload before parsing; `maxDecodedBytes` caps memory after it.
+ * const limits: Vfs.DecodeLimits = {
+ *   maxEncodedBytes: ByteSize.megabytes(4),
+ *   maxRecords: 10_000,
+ *   maxEntries: 10_000,
+ *   maxDecodedBytes: ByteSize.megabytes(16)
+ * }
+ *
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make()
+ *   const bytes = yield* Vfs.encodeSnapshot(yield* volume.snapshot)
+ *
+ *   yield* Vfs.decodeSnapshot(bytes, limits)
+ *
+ *   return "accepted"
+ * })
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // accepted
+ * ```
+ *
  * @category schemas
  * @since 0.1.0
  */

package/dist/SnapshotDelta.d.ts

@@ -9,14 +9,14 @@ import { BytePath } from "./BytePath.js";
 /**
  * Type identifier for opaque snapshot deltas.
  *
- * @category type ids
+ * @category type IDs
  * @since 0.1.0
  */
 export declare const SnapshotDeltaTypeId: "@effect-vfs/core/SnapshotDelta";
 /**
  * Type identifier for opaque snapshot deltas.
  *
- * @category type ids
+ * @category type IDs
  * @since 0.1.0
  */
 export type SnapshotDeltaTypeId = typeof SnapshotDeltaTypeId;
@@ -70,6 +70,39 @@ export type SnapshotDifference = typeof SnapshotDifference.Type;
  * Independent snapshots do not preserve shared lineage, so moves are reported
  * as a removal and an addition rather than an inferred rename.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make()
+ *   const caller = yield* volume.caller()
+ *
+ *   yield* caller.writeFile("/f", new Uint8Array([1]), {
+ *     access: "write",
+ *     create: "exclusive"
+ *   })
+ *
+ *   const base = yield* volume.snapshot
+ *
+ *   yield* caller.writeFile("/f", new Uint8Array([2, 3]), { access: "write", truncate: true })
+ *   yield* caller.chmod("/f", 0o600)
+ *
+ *   const delta = yield* Vfs.diffSnapshots(base, yield* volume.snapshot)
+ *   const changes = yield* Vfs.inspectSnapshotDelta(base, delta)
+ *
+ *   // `Updated` carries which fields moved; `Added` and `Removed` carry a kind.
+ *   const change = changes[0]!
+ *
+ *   return change._tag === "Updated" ? change.differences : change.kind
+ * }).pipe(Effect.provide(NodeCrypto.layer))
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // [ 'content', 'mode' ]
+ * ```
+ *
  * @category schemas
  * @since 0.1.0
  */
@@ -95,6 +128,32 @@ export type SnapshotChange = typeof SnapshotChange.Type;
 /**
  * Schema for snapshot-delta inspection options.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make()
+ *   const caller = yield* volume.caller()
+ *   const base = yield* volume.snapshot
+ *
+ *   yield* caller.mkdir("/work")
+ *
+ *   const delta = yield* Vfs.diffSnapshots(base, yield* volume.snapshot)
+ *
+ *   // Timestamps are excluded by default, since they change on every write.
+ *   const plain = yield* Vfs.inspectSnapshotDelta(base, delta)
+ *   const timed = yield* Vfs.inspectSnapshotDelta(base, delta, { includeTimestamps: true })
+ *
+ *   return [plain.length, timed.length]
+ * }).pipe(Effect.provide(NodeCrypto.layer))
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // [ 1, 2 ]
+ * ```
+ *
  * @category schemas
  * @since 0.1.0
  */
@@ -115,6 +174,32 @@ declare const SnapshotDeltaError_base: new <A extends Record<string, any> = {}>(
 /**
  * A valid snapshot delta was inspected or applied against a valid but semantically different base.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make()
+ *   const caller = yield* volume.caller()
+ *   const base = yield* volume.snapshot
+ *
+ *   yield* caller.mkdir("/work")
+ *
+ *   // Omitting limits uses `default`; `constrained` suits memory-sensitive hosts.
+ *   const tight = { ...Vfs.SnapshotDeltaLimits.constrained, maxOutputRecords: 0 }
+ *
+ *   return yield* Vfs.diffSnapshots(base, yield* volume.snapshot, tight).pipe(
+ *     Effect.as("diffed"),
+ *     Effect.catchTag("ImageError", (error) => Effect.succeed(`${error.code} at ${error.field}`))
+ *   )
+ * }).pipe(Effect.provide(NodeCrypto.layer))
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // LimitExceeded at outputRecords
+ * ```
+ *
  * @category errors
  * @since 0.1.0
  */
@@ -141,7 +226,11 @@ declare const SnapshotDeltaLimitsSchema: Schema.Struct<{
  * @since 0.1.0
  */
 export type SnapshotDeltaLimits = typeof SnapshotDeltaLimitsSchema.Type;
-/** Constructs and freezes a complete snapshot-delta resource policy. @internal */
+/**
+ * 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.
@@ -149,6 +238,27 @@ export declare const makeSnapshotDeltaLimits: (limits: SnapshotDeltaLimits) => S
  * The constrained preset is intended for memory-sensitive environments. The
  * default preset permits larger snapshots and payloads while remaining finite.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make()
+ *   const base = yield* volume.snapshot
+ *
+ *   yield* (yield* volume.caller()).mkdir("/work")
+ *
+ *   // Omitting limits uses `default`; pass `constrained` where memory is tight.
+ *   return yield* Vfs.diffSnapshots(
+ *     base,
+ *     yield* volume.snapshot,
+ *     Vfs.SnapshotDeltaLimits.constrained
+ *   )
+ * }).pipe(Effect.provide(NodeCrypto.layer))
+ * ```
+ *
  * @category schemas
  * @since 0.1.0
  */

package/dist/SnapshotDelta.d.ts.map

@@ -1 +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"}
+{"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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;IASzB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAA;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,sBAAsB;IACjC,6FAA6F;;EAE7F,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG,OAAO,sBAAsB,CAAC,IAAI,CAAA;;;;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;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;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,WAAY,mBAAmB,KAAG,mBACxC,CAAA;AA4B9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAG9B,CAAA"}

package/dist/SnapshotDelta.js

@@ -11,7 +11,7 @@ import * as Internal from "./internal/snapshotDeltaModel.js";
 /**
  * Type identifier for opaque snapshot deltas.
  *
- * @category type ids
+ * @category type IDs
  * @since 0.1.0
  */
 export const SnapshotDeltaTypeId = Internal.SnapshotDeltaTypeId;
@@ -55,6 +55,39 @@ const SnapshotDifferences = Schema.Array(SnapshotDifference).check(Schema.isMinL
  * Independent snapshots do not preserve shared lineage, so moves are reported
  * as a removal and an addition rather than an inferred rename.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make()
+ *   const caller = yield* volume.caller()
+ *
+ *   yield* caller.writeFile("/f", new Uint8Array([1]), {
+ *     access: "write",
+ *     create: "exclusive"
+ *   })
+ *
+ *   const base = yield* volume.snapshot
+ *
+ *   yield* caller.writeFile("/f", new Uint8Array([2, 3]), { access: "write", truncate: true })
+ *   yield* caller.chmod("/f", 0o600)
+ *
+ *   const delta = yield* Vfs.diffSnapshots(base, yield* volume.snapshot)
+ *   const changes = yield* Vfs.inspectSnapshotDelta(base, delta)
+ *
+ *   // `Updated` carries which fields moved; `Added` and `Removed` carry a kind.
+ *   const change = changes[0]!
+ *
+ *   return change._tag === "Updated" ? change.differences : change.kind
+ * }).pipe(Effect.provide(NodeCrypto.layer))
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // [ 'content', 'mode' ]
+ * ```
+ *
  * @category schemas
  * @since 0.1.0
  */
@@ -71,6 +104,32 @@ export const SnapshotChange = Schema.Union([
 /**
  * Schema for snapshot-delta inspection options.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make()
+ *   const caller = yield* volume.caller()
+ *   const base = yield* volume.snapshot
+ *
+ *   yield* caller.mkdir("/work")
+ *
+ *   const delta = yield* Vfs.diffSnapshots(base, yield* volume.snapshot)
+ *
+ *   // Timestamps are excluded by default, since they change on every write.
+ *   const plain = yield* Vfs.inspectSnapshotDelta(base, delta)
+ *   const timed = yield* Vfs.inspectSnapshotDelta(base, delta, { includeTimestamps: true })
+ *
+ *   return [plain.length, timed.length]
+ * }).pipe(Effect.provide(NodeCrypto.layer))
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // [ 1, 2 ]
+ * ```
+ *
  * @category schemas
  * @since 0.1.0
  */
@@ -81,6 +140,32 @@ export const SnapshotChangesOptions = Schema.Struct({
 /**
  * A valid snapshot delta was inspected or applied against a valid but semantically different base.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make()
+ *   const caller = yield* volume.caller()
+ *   const base = yield* volume.snapshot
+ *
+ *   yield* caller.mkdir("/work")
+ *
+ *   // Omitting limits uses `default`; `constrained` suits memory-sensitive hosts.
+ *   const tight = { ...Vfs.SnapshotDeltaLimits.constrained, maxOutputRecords: 0 }
+ *
+ *   return yield* Vfs.diffSnapshots(base, yield* volume.snapshot, tight).pipe(
+ *     Effect.as("diffed"),
+ *     Effect.catchTag("ImageError", (error) => Effect.succeed(`${error.code} at ${error.field}`))
+ *   )
+ * }).pipe(Effect.provide(NodeCrypto.layer))
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // LimitExceeded at outputRecords
+ * ```
+ *
  * @category errors
  * @since 0.1.0
  */
@@ -98,7 +183,11 @@ const SnapshotDeltaLimitsSchema = Schema.Struct({
     maxOutputBytes: Schema.ByteSize,
     maxInheritedRecords: Schema.Natural
 });
-/** Constructs and freezes a complete snapshot-delta resource policy. @internal */
+/**
+ * Constructs and freezes a complete snapshot-delta resource policy.
+ *
+ * @internal
+ */
 export const makeSnapshotDeltaLimits = (limits) => Object.freeze({ ...limits });
 const constrained = makeSnapshotDeltaLimits({
     maxEncodedBytes: ByteSize.mebibytes(2),
@@ -130,6 +219,27 @@ const defaultLimits = makeSnapshotDeltaLimits({
  * The constrained preset is intended for memory-sensitive environments. The
  * default preset permits larger snapshots and payloads while remaining finite.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make()
+ *   const base = yield* volume.snapshot
+ *
+ *   yield* (yield* volume.caller()).mkdir("/work")
+ *
+ *   // Omitting limits uses `default`; pass `constrained` where memory is tight.
+ *   return yield* Vfs.diffSnapshots(
+ *     base,
+ *     yield* volume.snapshot,
+ *     Vfs.SnapshotDeltaLimits.constrained
+ *   )
+ * }).pipe(Effect.provide(NodeCrypto.layer))
+ * ```
+ *
  * @category schemas
  * @since 0.1.0
  */