@effect-vfs/core 0.3.0 → 0.4.0

package/dist/VirtualFileSystem.js

@@ -1,25 +1,15 @@
-/**
- * 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 Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Result from "effect/Result";
 import * as Schema from "effect/Schema";
 import * as SchemaIssue from "effect/SchemaIssue";
 import * as SchemaTransformation from "effect/SchemaTransformation";
-import { BytePath } from "./BytePath.js";
 export { BytePath } from "./BytePath.js";
-import { DecodeLimits, ImageError } from "./Snapshot.js";
 export { DecodeLimits, ImageError, SnapshotTypeId } from "./Snapshot.js";
 import * as Image from "./internal/image.js";
 import * as SnapshotDeltaInternal from "./internal/snapshotDelta.js";
 import * as VfsModel from "./internal/virtualFileSystem.js";
+import { decodeConfiguration } from "./internal/virtualFileSystem/errors.js";
 import * as FixtureInternal from "./internal/virtualFileSystem/fixture.js";
 import * as Path from "./internal/virtualFileSystem/path.js";
 import * as SnapshotDeltaModel from "./SnapshotDelta.js";
@@ -32,6 +22,30 @@ const ObjectReferenceId = VfsModel.ObjectReferenceId;
 /**
  * Schema for portable virtual filesystem error codes.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import { Effect, Schema } from "effect"
+ *
+ * const asCode = Schema.decodeUnknownEffect(Vfs.FsCode)
+ *
+ * // Useful when a code has crossed a process boundary and arrives back as data.
+ * const program = Effect.gen(function*() {
+ *   const payload = JSON.parse(`{"code":"NotFound","other":"Nonsense"}`)
+ *
+ *   const known = yield* asCode(payload.code)
+ *
+ *   const unknown = yield* asCode(payload.other).pipe(
+ *     Effect.orElseSucceed(() => "not a code")
+ *   )
+ *
+ *   return [known, unknown]
+ * })
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // [ 'NotFound', 'not a code' ]
+ * ```
+ *
  * @category schemas
  * @since 0.1.0
  */
@@ -39,17 +53,65 @@ export const FsCode = VfsModel.FsCode;
 /**
  * Describes an expected filesystem operation failure.
  *
+ * Durable providers distinguish `StorageRejected` (the operation definitely did not commit),
+ * `OutcomeUnknown` (it may have committed), and `VolumeUnavailable` (the provider cannot safely
+ * serve further operations until recovery). Built-in memory volumes never emit these codes.
+ *
+ * @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 caller = yield* (yield* Vfs.make()).caller()
+ *
+ *   // Every filesystem operation fails with this one tagged error; `code`
+ *   // distinguishes the cases, so match on it rather than on the tag alone.
+ *   return yield* caller.readFile("/missing").pipe(
+ *     Effect.catchTag("FsError", (error) =>
+ *       error.code === "NotFound"
+ *         ? Effect.succeed(new Uint8Array())
+ *         : Effect.fail(error))
+ *   )
+ * })
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * // Uint8Array(0) []
+ * ```
+ *
  * @category errors
  * @since 0.1.0
  */
-export const FsError = VfsModel.FsError;
+export { FsError } from "./VirtualFileSystemError.js";
 /**
  * Describes an invalid volume or caller option and names the rejected field.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+ * import { Effect } from "effect"
+ *
+ * // `field` names the rejected option, so the caller learns which key was wrong.
+ * const program = Effect.gen(function*() {
+ *   // Options that arrived from a config file or CLI flag, not a literal.
+ *   const options = JSON.parse(`{"maxEntries":-1}`) as Vfs.VolumeOptions
+ *
+ *   return yield* Vfs.make(options).pipe(
+ *     Effect.as("ok"),
+ *     Effect.catchTag("ConfigurationError", (error) => Effect.succeed(`rejected ${error.field}`))
+ *   )
+ * })
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * // rejected maxEntries
+ * ```
+ *
  * @category errors
  * @since 0.1.0
  */
-export const ConfigurationError = VfsModel.ConfigurationError;
+export { ConfigurationError } from "./VirtualFileSystemError.js";
 /**
  * Schema for a caller's numeric identity, supplementary groups, and explicit privilege.
  *
@@ -60,13 +122,100 @@ export const Identity = VfsModel.Identity;
 /**
  * Schema for root caller credentials and creation mask.
  *
+ * @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()
+ *
+ *   // Omitting `identity` yields a privileged root caller.
+ *   const root = yield* volume.caller({ umask: 0 })
+ *   const user = yield* volume.caller({
+ *     identity: { uid: 1000, gid: 1000, groups: [], privileged: false },
+ *     umask: 0o022
+ *   })
+ *
+ *   yield* root.mkdir("/home", { mode: 0o777 })
+ *
+ *   // The umask clears its bits from the requested mode.
+ *   yield* user.mkdir("/home/user", { mode: 0o777 })
+ *
+ *   return ((yield* user.stat("/home/user")).mode & 0o777).toString(8)
+ * })
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * // 755
+ * ```
+ *
  * @category schemas
  * @since 0.1.0
  */
 export const RootCallerOptions = VfsModel.RootCallerOptions;
+/**
+ * Schema for the failure boundary survived by an acknowledged volume write.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const VolumeDurability = VfsModel.VolumeDurability;
+/**
+ * Weakest-to-strongest ordering for volume durability guarantees.
+ *
+ * @category ordering
+ * @since 0.1.0
+ */
+export const VolumeDurabilityOrder = VfsModel.VolumeDurabilityOrder;
+/**
+ * Returns whether `actual` survives at least the failure boundary required by `required`.
+ *
+ * @category predicates
+ * @since 0.1.0
+ */
+export const isVolumeDurabilityAtLeast = VfsModel.isVolumeDurabilityAtLeast;
+/**
+ * Schema for the stable logical identity of a volume.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const VolumeIdentity = VfsModel.VolumeIdentity;
+/**
+ * Schema for one uninterrupted storage lifetime of a volume.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export const VolumeIncarnation = VfsModel.VolumeIncarnation;
 /**
  * Schema for optional volume capacity and path limits.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+ * import { ByteSize, Effect } from "effect"
+ *
+ * // Every limit is optional, and each one is enforced once set.
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make({ maxFileBytes: ByteSize.bytes(4) })
+ *   const caller = yield* volume.caller()
+ *
+ *   return yield* caller.writeFile("/big.bin", new Uint8Array(16), {
+ *     access: "write",
+ *     create: "exclusive"
+ *   }).pipe(
+ *     Effect.as("written"),
+ *     Effect.catchTag("FsError", (error) => Effect.succeed(error.code))
+ *   )
+ * })
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * // FileTooLarge
+ * ```
+ *
  * @category schemas
  * @since 0.1.0
  */
@@ -74,10 +223,48 @@ export const VolumeOptions = VfsModel.VolumeOptions;
 /**
  * Schema for filesystem node metadata with bigint inode, size, and nanosecond fields.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+ * import { Effect } from "effect"
+ *
+ * // Sizes and inode numbers are bigint; times are nanosecond timestamps.
+ * const program = Effect.gen(function*() {
+ *   const caller = yield* (yield* Vfs.make()).caller()
+ *
+ *   yield* caller.writeFile("/f", new Uint8Array([1, 2, 3]), {
+ *     access: "write",
+ *     create: "exclusive"
+ *   })
+ *
+ *   const metadata = yield* caller.stat("/f")
+ *
+ *   return [metadata.kind, metadata.size, metadata.nlink]
+ * })
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * // [ 'file', 3n, 1 ]
+ * ```
+ *
  * @category schemas
  * @since 0.1.0
  */
 export const Metadata = VfsModel.Metadata;
+/**
+ * A directory revision transition captured inside one coordinated operation.
+ *
+ * @category schemas
+ * @since 0.4.0
+ */
+export const DirectoryChange = VfsModel.DirectoryChange;
+/**
+ * The directory transitions produced by a same-directory or cross-directory rename.
+ *
+ * @category schemas
+ * @since 0.4.0
+ */
+export const RenameReferenceResult = VfsModel.RenameReferenceResult;
 /**
  * Schema for an owner update. Omitted fields retain their existing values.
  *
@@ -95,6 +282,35 @@ export const TimeUpdate = VfsModel.TimeUpdate;
 /**
  * Schema for independent access and modification time updates.
  *
+ * @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 caller = yield* (yield* Vfs.make()).caller()
+ *
+ *   yield* caller.writeFile("/f", new Uint8Array([1]), {
+ *     access: "write",
+ *     create: "exclusive"
+ *   })
+ *
+ *   // Each field is set to a value, to the current clock, or left alone.
+ *   yield* caller.utimes("/f", {
+ *     access: { kind: "value", nanoseconds: 1_000n },
+ *     modification: { kind: "omit" }
+ *   })
+ *
+ *   const metadata = yield* caller.stat("/f")
+ *
+ *   return [metadata.atimeNs, metadata.mtimeNs === 1_000n]
+ * })
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * // [ 1000n, false ]
+ * ```
+ *
  * @category schemas
  * @since 0.1.0
  */
@@ -109,10 +325,65 @@ export const SeekMode = VfsModel.SeekMode;
 /**
  * Schema for file access, creation, append, truncate, and symlink behavior.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+ * import { Effect } from "effect"
+ *
+ * // `access` is required; `create` decides whether a missing file is an error.
+ * const program = Effect.gen(function*() {
+ *   const caller = yield* (yield* Vfs.make()).caller()
+ *
+ *   const handle = yield* caller.open("/log.txt", {
+ *     access: "readWrite",
+ *     create: "ifMissing",
+ *     append: true
+ *   })
+ *
+ *   yield* handle.write(new Uint8Array([1, 2]))
+ *
+ *   return (yield* handle.stat).size
+ * }).pipe(Effect.scoped)
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * // 2n
+ * ```
+ *
  * @category schemas
  * @since 0.1.0
  */
 export const OpenSettings = VfsModel.OpenSettings;
+/**
+ * Settings for creating a directory through a parent object reference.
+ * `exactMode` skips the caller's umask for an explicit creation mode; permission policy still applies.
+ *
+ * @category schemas
+ * @since 0.4.0
+ */
+export const MkdirReferenceSettings = VfsModel.MkdirReferenceSettings;
+/**
+ * Settings for creating a symbolic link through a parent object reference.
+ *
+ * @category schemas
+ * @since 0.4.0
+ */
+export const SymlinkReferenceSettings = VfsModel.SymlinkReferenceSettings;
+/**
+ * Settings for opening an existing regular-file reference.
+ *
+ * @category schemas
+ * @since 0.4.0
+ */
+export const OpenReferenceSettings = VfsModel.OpenReferenceSettings;
+/**
+ * Settings for atomically looking up or creating and opening one referenced child.
+ * `exactMode` skips the caller's umask for an explicit creation mode; permission policy still applies.
+ *
+ * @category schemas
+ * @since 0.4.0
+ */
+export const OpenChildReferenceSettings = VfsModel.OpenChildReferenceSettings;
 /**
  * Schema for the filesystem entry kinds reported by overlay summaries.
  *
@@ -142,6 +413,29 @@ export const OverlayChange = VfsModel.OverlayChange;
 /**
  * Schema for overlay summary filtering.
  *
+ * @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 base = yield* Vfs.make()
+ *   const workspace = yield* Vfs.makeOverlay(yield* base.snapshot)
+ *
+ *   yield* (yield* workspace.caller()).mkdir("/out")
+ *
+ *   // Timestamps are excluded by default, since they change on every write.
+ *   const plain = yield* workspace.changes()
+ *   const timed = yield* workspace.changes({ includeTimestamps: true })
+ *
+ *   return [plain.length, timed.length]
+ * })
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * // [ 1, 2 ]
+ * ```
+ *
  * @category schemas
  * @since 0.1.0
  */
@@ -149,13 +443,70 @@ export const OverlayChangesOptions = VfsModel.OverlayChangesOptions;
 /**
  * Optional Effect service for providing an existing filesystem caller.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+ * import { Effect } from "effect"
+ *
+ * // Code depending on the service does not choose the volume it runs against.
+ * const readVersion = Effect.gen(function*() {
+ *   const caller = yield* Vfs.CurrentFileSystem
+ *
+ *   return yield* caller.readFile("/version")
+ * })
+ *
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make()
+ *   const caller = yield* volume.caller()
+ *
+ *   yield* caller.writeFile("/version", new Uint8Array([49]), {
+ *     access: "write",
+ *     create: "exclusive"
+ *   })
+ *
+ *   return yield* readVersion.pipe(Effect.provideService(Vfs.CurrentFileSystem, caller))
+ * })
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * // Uint8Array(1) [ 49 ]
+ * ```
+ *
+ * @see The testing guide at `/guides/testing-with-an-isolated-filesystem`.
  * @category services
  * @since 0.1.0
  */
-export const CurrentFileSystem = VfsModel.CurrentFileSystem;
+export const CurrentFileSystem = Context.Service("@effect-vfs/core/CurrentFileSystem");
 /**
  * Encodes a snapshot as owned UTF-8 JSON bytes using the version 1 snapshot format.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+ * import { Effect } from "effect"
+ *
+ * // Bytes are portable: store or transmit them, then decode under explicit limits.
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make()
+ *   const caller = yield* volume.caller()
+ *
+ *   yield* caller.writeFile("/f", new Uint8Array([1, 2, 3]), {
+ *     access: "write",
+ *     create: "exclusive"
+ *   })
+ *
+ *   const bytes = yield* Vfs.encodeSnapshot(yield* volume.snapshot)
+ *
+ *   // The bytes are UTF-8 JSON carrying the version 1 snapshot format.
+ *   return JSON.parse(new TextDecoder().decode(bytes)).version
+ * })
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * // 1
+ * ```
+ *
+ * @see {@link decodeSnapshot} for reading the bytes back under limits.
  * @category serialization
  * @since 0.1.0
  */
@@ -163,18 +514,75 @@ export const encodeSnapshot = Image.encodeSnapshot;
 /**
  * Decodes version 1 snapshot bytes while enforcing explicit input and payload limits.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+ * import { ByteSize, Effect } from "effect"
+ *
+ * // Limits are mandatory: decoding is the boundary where untrusted input arrives.
+ * 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(1),
+ *     maxRecords: 10_000,
+ *     maxEntries: 10_000,
+ *     maxDecodedBytes: ByteSize.megabytes(16)
+ *   }).pipe(
+ *     Effect.as("accepted"),
+ *     Effect.catchTag("ImageError", (error) => Effect.succeed([error.code, error.field]))
+ *   )
+ * })
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * // [ 'LimitExceeded', 'encodedBytes' ]
+ * ```
+ *
+ * @see {@link DecodeLimits} for what each bound protects.
  * @category serialization
  * @since 0.1.0
  */
 export const decodeSnapshot = Image.decodeSnapshot;
 const deltaLimits = (limits) => {
-    const decoded = Path.decodeConfiguration(SnapshotDeltaModel.SnapshotDeltaLimits, limits ?? SnapshotDeltaModel.SnapshotDeltaLimits.default);
+    const decoded = decodeConfiguration(SnapshotDeltaModel.SnapshotDeltaLimits, limits ?? SnapshotDeltaModel.SnapshotDeltaLimits.default);
     return Result.isFailure(decoded) ? Effect.fail(decoded.failure) : Effect.succeed(decoded.success);
 };
 /**
  * Computes an exact portable delta between two immutable snapshots.
- * Requires the platform-neutral `Crypto.Crypto` service for base identity.
+ * Requires the platform-neutral `Crypto.Crypto` service for base identity. Provide
+ * `NodeCrypto.layer`, `BunCrypto.layer`, or your own via `Crypto.make`.
+ *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+ * import { Effect } from "effect"
+ *
+ * // Two snapshots in, one opaque delta out. `inspectSnapshotDelta` reads it.
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make()
+ *   const caller = yield* volume.caller()
+ *   const base = yield* volume.snapshot
+ *
+ *   yield* caller.writeFile("/added.txt", new Uint8Array([1]), {
+ *     access: "write",
+ *     create: "exclusive"
+ *   })
+ *
+ *   const delta = yield* Vfs.diffSnapshots(base, yield* volume.snapshot)
+ *
+ *   const changes = yield* Vfs.inspectSnapshotDelta(base, delta)
+ *
+ *   return new TextDecoder().decode(yield* Vfs.pathToBytes(changes[0]!.path))
+ * }).pipe(Effect.provide(NodeCrypto.layer))
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // /added.txt
+ * ```
  *
+ * @see {@link inspectSnapshotDelta} to read a delta, {@link applySnapshotDelta} to apply one.
  * @category snapshots
  * @since 0.1.0
  */
@@ -183,21 +591,80 @@ export const diffSnapshots = Effect.fn("VirtualFileSystem.diffSnapshots")(functi
 });
 /**
  * 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.
+ * Requires the platform-neutral `Crypto.Crypto` service for base identity. Provide
+ * `NodeCrypto.layer`, `BunCrypto.layer`, or your own via `Crypto.make`.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+ * import { Effect } from "effect"
+ *
+ * // Inspection verifies the delta against its base before describing it.
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make()
+ *   const caller = yield* volume.caller()
+ *   const base = yield* volume.snapshot
+ *
+ *   yield* caller.mkdir("/logs")
+ *
+ *   const delta = yield* Vfs.diffSnapshots(base, yield* volume.snapshot)
+ *   const changes = yield* Vfs.inspectSnapshotDelta(base, delta)
+ *
+ *   return changes.map((change) =>
+ *     change._tag === "Updated" ? change.afterKind : change.kind)
+ * }).pipe(Effect.provide(NodeCrypto.layer))
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // [ 'directory' ]
+ * ```
+ *
+ * @see {@link SnapshotChangesOptions} for including timestamp differences.
  * @category snapshots
  * @since 0.1.0
  */
 export const inspectSnapshotDelta = Effect.fn("VirtualFileSystem.inspectSnapshotDelta")(function* (base, delta, options, limits) {
-    const decoded = Path.decodeConfiguration(SnapshotDeltaModel.SnapshotChangesOptions, options ?? {});
+    const decoded = decodeConfiguration(SnapshotDeltaModel.SnapshotChangesOptions, options ?? {});
     if (Result.isFailure(decoded))
         return yield* decoded.failure;
     return yield* SnapshotDeltaInternal.inspectSnapshotDelta(base, delta, decoded.success, yield* deltaLimits(limits));
 });
 /**
  * Applies an exact delta to its semantically matching base and returns a new snapshot.
- * Requires the platform-neutral `Crypto.Crypto` service for base identity.
+ * Requires the platform-neutral `Crypto.Crypto` service for base identity. Provide
+ * `NodeCrypto.layer`, `BunCrypto.layer`, or your own via `Crypto.make`.
+ *
+ * @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.writeFile("/f", new Uint8Array([7]), {
+ *     access: "write",
+ *     create: "exclusive"
+ *   })
+ *
+ *   const delta = yield* Vfs.diffSnapshots(base, yield* volume.snapshot)
  *
+ *   // Applying the delta to the same base reproduces the target snapshot.
+ *   const applied = yield* Vfs.applySnapshotDelta(base, delta)
+ *   const restored = yield* Vfs.fromSnapshot(applied)
+ *   const reader = yield* restored.caller()
+ *
+ *   return yield* reader.readFile("/f")
+ * }).pipe(Effect.provide(NodeCrypto.layer))
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // Uint8Array(1) [ 7 ]
+ * ```
+ *
+ * @see {@link SnapshotDeltaFromBytes} for moving a delta across a boundary.
  * @category snapshots
  * @since 0.1.0
  */
@@ -209,6 +676,34 @@ const deltaSchemaIssue = (cause, input, options) => new SchemaIssue.InvalidValue
  * Creates an Effect Schema codec between owned bytes and opaque snapshot deltas.
  * Omission uses `SnapshotDeltaLimits.default`.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+ * import { Effect, Schema } from "effect"
+ *
+ * // Omitting limits uses `SnapshotDeltaLimits.default`.
+ * const codec = Vfs.SnapshotDeltaFromBytes()
+ *
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make()
+ *   const base = yield* volume.snapshot
+ *
+ *   yield* (yield* volume.caller()).mkdir("/out")
+ *
+ *   const delta = yield* Vfs.diffSnapshots(base, yield* volume.snapshot)
+ *   const bytes = yield* Schema.encodeEffect(codec)(delta)
+ *
+ *   // The delta survives the trip through bytes and still applies to its base.
+ *   const decoded = yield* Schema.decodeEffect(codec)(bytes)
+ *
+ *   return (yield* Vfs.inspectSnapshotDelta(base, decoded)).map((change) => change._tag)
+ * }).pipe(Effect.provide(NodeCrypto.layer))
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // [ 'Added' ]
+ * ```
+ *
  * @category schemas
  * @since 0.1.0
  */
@@ -230,6 +725,28 @@ export const SnapshotDeltaFromBytes = (limits) => {
  *
  * Shared-memory-backed and detached views fail with `InvalidArgument`.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import { Effect } from "effect"
+ *
+ * // Any byte except NUL is accepted. Empty, NUL-bearing, detached, and shared-memory
+ * // input all fail with `InvalidArgument`.
+ * const program = Effect.gen(function*() {
+ *   const path = yield* Vfs.pathFromBytes(new Uint8Array([47, 116, 109, 112]))
+ *
+ *   const rejected = yield* Vfs.pathFromBytes(new Uint8Array([47, 0])).pipe(
+ *     Effect.as("accepted"),
+ *     Effect.catchTag("FsError", (error) => Effect.succeed(error.code))
+ *   )
+ *
+ *   return [yield* Vfs.pathToBytes(path), rejected]
+ * })
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // [ Uint8Array(4) [ 47, 116, 109, 112 ], 'InvalidArgument' ]
+ * ```
+ *
  * @category constructors
  * @since 0.1.0
  */
@@ -248,6 +765,27 @@ export const pathToBytes = Path.pathToBytes;
  *
  * Fixture paths must be absolute, unique, and explicitly include their parent directories.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+ * import { Effect, Schema } from "effect"
+ *
+ * // Fixtures must list every parent directory before its children.
+ * const program = Schema.decodeUnknownEffect(Vfs.Fixture)({
+ *   entries: [
+ *     { kind: "file", path: "/etc/hosts", bytes: new TextEncoder().encode("127.0.0.1") }
+ *   ]
+ * }).pipe(
+ *   Effect.flatMap(Vfs.fromFixture),
+ *   Effect.as("built"),
+ *   Effect.catchTag("ImageError", (error) => Effect.succeed(`rejected: ${error.code}`))
+ * )
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * // rejected: InvalidStructure
+ * ```
+ *
  * @category schemas
  * @since 0.1.0
  */
@@ -260,6 +798,27 @@ export const Fixture = VfsModel.Fixture;
  * Each execution creates independent storage. Snapshot image failures cannot
  * arise because this constructor does not accept persisted input.
  *
+ * @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.mkdir("/work")
+ *   yield* caller.writeFile("/work/notes.txt", new Uint8Array([104, 105]), { access: "write", create: "exclusive" })
+ *
+ *   return yield* caller.readFile("/work/notes.txt")
+ * })
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * // Uint8Array(2) [ 104, 105 ]
+ * ```
+ *
+ * @see The testing guide at `/guides/testing-with-an-isolated-filesystem`.
  * @category constructors
  * @since 0.1.0
  */
@@ -267,6 +826,41 @@ export const make = VfsModel.make;
 /**
  * Restores a fresh volume from an opaque snapshot under the supplied destination limits.
  *
+ * @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 original = yield* Vfs.make()
+ *   const source = yield* original.caller()
+ *
+ *   yield* source.writeFile("/seed.txt", new TextEncoder().encode("one"), {
+ *     access: "write",
+ *     create: "exclusive"
+ *   })
+ *
+ *   const restored = yield* Vfs.fromSnapshot(yield* original.snapshot)
+ *   const copy = yield* restored.caller()
+ *
+ *   // Writing to the restore leaves the original untouched: the two are independent.
+ *   yield* copy.writeFile("/seed.txt", new TextEncoder().encode("two"), {
+ *     access: "write",
+ *     truncate: true
+ *   })
+ *
+ *   return [
+ *     new TextDecoder().decode(yield* source.readFile("/seed.txt")),
+ *     new TextDecoder().decode(yield* copy.readFile("/seed.txt"))
+ *   ]
+ * })
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * // [ 'one', 'two' ]
+ * ```
+ *
+ * @see {@link makeOverlay} for a copy-on-write workspace over the same base.
  * @category constructors
  * @since 0.1.0
  */
@@ -284,6 +878,40 @@ export const fromSnapshot = VfsModel.fromSnapshot;
  * Invalid base snapshots fail with `ImageError`; invalid volume limits fail
  * with `ConfigurationError`. Each execution creates a fresh workspace.
  *
+ * @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 base = yield* Vfs.make()
+ *   const origin = yield* base.caller()
+ *
+ *   yield* origin.writeFile("/config.json", new TextEncoder().encode("{}"), {
+ *     access: "write",
+ *     create: "exclusive"
+ *   })
+ *
+ *   const workspace = yield* Vfs.makeOverlay(yield* base.snapshot)
+ *
+ *   yield* (yield* workspace.caller()).writeFile("/config.json", new TextEncoder().encode("[]"), {
+ *     access: "write",
+ *     truncate: true
+ *   })
+ *
+ *   // The write landed in the workspace only; the base still reads its own value.
+ *   return [
+ *     new TextDecoder().decode(yield* origin.readFile("/config.json")),
+ *     (yield* workspace.changes()).map((change) => change._tag)
+ *   ]
+ * })
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * // [ '{}', [ 'Updated' ] ]
+ * ```
+ *
+ * @see The overlay guide at `/guides/overlay-filesystems`.
  * @category constructors
  * @since 0.1.0
  */
@@ -291,6 +919,36 @@ export const makeOverlay = VfsModel.makeOverlay;
 /**
  * Builds a fresh volume from a validated final-state fixture.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+ * import { Effect } from "effect"
+ *
+ * const encoder = new TextEncoder()
+ *
+ * const program = Effect.gen(function*() {
+ *   // Parent directories must be listed explicitly, before their children.
+ *   const volume = yield* Vfs.fromFixture({
+ *     entries: [
+ *       { kind: "directory", path: "/project" },
+ *       {
+ *         kind: "file",
+ *         path: "/project/package.json",
+ *         bytes: encoder.encode(`{"version":"1.2.3"}`)
+ *       },
+ *       { kind: "symlink", path: "/project/latest", target: "/project/package.json" }
+ *     ]
+ *   })
+ *
+ *   return yield* (yield* volume.caller()).readDirectory("/project")
+ * })
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * // [ 'package.json', 'latest' ]
+ * ```
+ *
+ * @see The fixtures guide at `/guides/fixtures-and-snapshots`.
  * @category constructors
  * @since 0.1.0
  */