@effect-vfs/core 0.3.0 → 0.3.1

package/dist/VirtualFileSystem.d.ts

@@ -12,9 +12,9 @@ import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
 import type * as Scope from "effect/Scope";
 import type * as Stream from "effect/Stream";
-import { BytePath } from "./BytePath.js";
+import type { BytePath } from "./BytePath.js";
 export { BytePath } from "./BytePath.js";
-import { DecodeLimits, ImageError, type Snapshot } from "./Snapshot.js";
+import type { DecodeLimits, ImageError, Snapshot } from "./Snapshot.js";
 export { DecodeLimits, ImageError, type Snapshot, SnapshotTypeId } from "./Snapshot.js";
 import * as VfsModel from "./internal/virtualFileSystem.js";
 import * as SnapshotDeltaModel from "./SnapshotDelta.js";
@@ -27,6 +27,12 @@ declare const ObjectReferenceId: typeof VfsModel.ObjectReferenceId;
 /**
  * A UTF-8 string path or an opaque byte-preserving path.
  *
+ * **Details**
+ *
+ * Every operation accepts both. Pass a string unless a name is not valid UTF-8;
+ * strings are the normal case and byte paths are the escape hatch.
+ *
+ * @see {@link BytePath} for the byte-preserving form.
  * @category models
  * @since 0.1.0
  */
@@ -34,6 +40,30 @@ export type PathInput = string | BytePath;
 /**
  * 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
  */
@@ -48,6 +78,28 @@ export type FsCode = typeof FsCode.Type;
 /**
  * Describes an expected filesystem operation failure.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * 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).then(console.log)
+ * // Uint8Array(0) []
+ * ```
+ *
  * @category errors
  * @since 0.1.0
  */
@@ -58,6 +110,26 @@ export interface FsError extends VfsModel.FsError {
 /**
  * Describes an invalid volume or caller option and names the rejected field.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * 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).then(console.log)
+ * // rejected maxEntries
+ * ```
+ *
  * @category errors
  * @since 0.1.0
  */
@@ -82,6 +154,33 @@ export type Identity = typeof Identity.Type;
 /**
  * Schema for root caller credentials and creation mask.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * 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).then(console.log)
+ * // 755
+ * ```
+ *
  * @category schemas
  * @since 0.1.0
  */
@@ -96,6 +195,29 @@ export type RootCallerOptions = typeof RootCallerOptions.Type;
 /**
  * Schema for optional volume capacity and path limits.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * 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).then(console.log)
+ * // FileTooLarge
+ * ```
+ *
  * @category schemas
  * @since 0.1.0
  */
@@ -110,6 +232,29 @@ export type VolumeOptions = typeof VolumeOptions.Type;
 /**
  * Schema for filesystem node metadata with bigint inode, size, and nanosecond fields.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * 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).then(console.log)
+ * // [ 'file', 3n, 1 ]
+ * ```
+ *
  * @category schemas
  * @since 0.1.0
  */
@@ -133,6 +278,34 @@ export interface ObjectReference {
 /**
  * A value and the revision of the object from the same coordinated observation.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import { Effect } from "effect"
+ *
+ * // References survive renames, and each observation carries the revision it
+ * // matched, so a caller can tell whether what it read is still current.
+ * const program = Effect.gen(function*() {
+ *   const caller = yield* (yield* Vfs.make()).caller()
+ *
+ *   yield* caller.mkdir("/work")
+ *
+ *   const root = yield* caller.rootReference
+ *   const work = yield* caller.lookupReference(root, new TextEncoder().encode("work"))
+ *
+ *   const before = yield* caller.observeMetadata(work)
+ *
+ *   yield* caller.rename("/work", "/moved")
+ *
+ *   const after = yield* caller.observeMetadata(work)
+ *
+ *   return [before.value.kind, after.value.kind]
+ * })
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // [ 'directory', 'directory' ]
+ * ```
+ *
  * @category models
  * @since 0.1.0
  */
@@ -163,6 +336,36 @@ export interface RelativeOptions {
 /**
  * Controls the base directory and whether metadata operations follow the final symbolic link.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const caller = yield* (yield* Vfs.make()).caller()
+ *
+ *   yield* caller.writeFile("/target", new Uint8Array([1]), {
+ *     access: "write",
+ *     create: "exclusive",
+ *     mode: 0o644
+ *   })
+ *   yield* caller.symlink("/target", "/link")
+ *
+ *   // Metadata operations follow the final link by default, so this reaches the
+ *   // target; opting out changes the link itself and leaves the target alone.
+ *   yield* caller.chmod("/link", 0o600)
+ *   const followed = (yield* caller.stat("/target")).mode & 0o777
+ *
+ *   yield* caller.chmod("/link", 0o777, { followFinalSymlink: false })
+ *   const unchanged = (yield* caller.stat("/target")).mode & 0o777
+ *
+ *   return [followed.toString(8), unchanged.toString(8)]
+ * })
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // [ '600', '600' ]
+ * ```
+ *
  * @category models
  * @since 0.1.0
  */
@@ -194,6 +397,34 @@ export declare const TimeUpdate: typeof VfsModel.TimeUpdate;
 /**
  * Schema for independent access and modification time updates.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * 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).then(console.log)
+ * // [ 1000n, false ]
+ * ```
+ *
  * @category schemas
  * @since 0.1.0
  */
@@ -208,6 +439,34 @@ export type Times = typeof Times.Type;
 /**
  * A scoped directory capability that can be used for metadata and relative lookup.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import { Effect } from "effect"
+ *
+ * // The handle anchors relative paths to the directory itself, so a rename in
+ * // between does not send the write somewhere else.
+ * const program = Effect.gen(function*() {
+ *   const caller = yield* (yield* Vfs.make()).caller()
+ *
+ *   yield* caller.mkdir("/project")
+ *
+ *   const directory = yield* caller.openDirectory("/project")
+ *
+ *   yield* caller.rename("/project", "/renamed")
+ *   yield* caller.writeFile("notes.txt", new TextEncoder().encode("kept"), {
+ *     access: "write",
+ *     create: "exclusive",
+ *     relativeTo: directory
+ *   })
+ *
+ *   return yield* caller.readDirectory("/renamed")
+ * }).pipe(Effect.scoped)
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // [ 'notes.txt' ]
+ * ```
+ *
  * @category models
  * @since 0.1.0
  */
@@ -233,6 +492,30 @@ export type SeekMode = typeof SeekMode.Type;
 /**
  * Schema for file access, creation, append, truncate, and symlink behavior.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * 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).then(console.log)
+ * // 2n
+ * ```
+ *
  * @category schemas
  * @since 0.1.0
  */
@@ -247,6 +530,40 @@ export type OpenOptions = typeof OpenSettings.Type & RelativeOptions;
 /**
  * Options for an atomic whole-file write, including replacement and final mode controls.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const caller = yield* (yield* Vfs.make()).caller()
+ *   const bytes = new TextEncoder().encode("v2")
+ *
+ *   // `access` is required. `create: "exclusive"` refuses to replace an entry,
+ *   // while `truncate` overwrites one that already exists.
+ *   yield* caller.writeFile("/app.conf", new TextEncoder().encode("v1"), {
+ *     access: "write",
+ *     create: "exclusive",
+ *     mode: 0o640
+ *   })
+ *
+ *   const refused = yield* caller.writeFile("/app.conf", bytes, {
+ *     access: "write",
+ *     create: "exclusive"
+ *   }).pipe(
+ *     Effect.as("replaced"),
+ *     Effect.catchTag("FsError", (error) => Effect.succeed(error.code))
+ *   )
+ *
+ *   yield* caller.writeFile("/app.conf", bytes, { access: "write", truncate: true })
+ *
+ *   return [refused, new TextDecoder().decode(yield* caller.readFile("/app.conf"))]
+ * })
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // [ 'AlreadyExists', 'v2' ]
+ * ```
+ *
  * @category models
  * @since 0.1.0
  */
@@ -254,6 +571,31 @@ export type WriteFileOptions = VfsModel.WriteFileOptions;
 /**
  * A scoped regular-file capability with an independent bigint cursor.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import { Effect } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const caller = yield* (yield* Vfs.make()).caller()
+ *
+ *   const handle = yield* caller.open("/data.bin", {
+ *     access: "readWrite",
+ *     create: "exclusive"
+ *   })
+ *
+ *   yield* handle.write(new Uint8Array([1, 2, 3, 4]))
+ *
+ *   // `pread` reads at an offset and leaves the cursor where writing left it.
+ *   const slice = yield* handle.pread(2, 1n)
+ *
+ *   return [slice, yield* handle.seek(0n, "current")]
+ * }).pipe(Effect.scoped)
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // [ Uint8Array(2) [ 2, 3 ], 4n ]
+ * ```
+ *
  * @category models
  * @since 0.1.0
  */
@@ -281,6 +623,84 @@ export interface FileHandle {
 /**
  * A filesystem caller with its own identity, creation mask, and current directory.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import { Effect } from "effect"
+ *
+ * // Whole-file reads and writes need no scope. `writeFile` always takes an
+ * // options bag; `access` is required and `create` decides what a missing file means.
+ * 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 TextEncoder().encode("hello"), {
+ *     access: "write",
+ *     create: "exclusive"
+ *   })
+ *
+ *   return yield* caller.readDirectory("/work")
+ * })
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // [ 'notes.txt' ]
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import { Effect } from "effect"
+ *
+ * // Reach for a handle when a whole-file write will not do. A handle carries a
+ * // cursor and lives until its scope closes.
+ * const program = Effect.gen(function*() {
+ *   const caller = yield* (yield* Vfs.make()).caller()
+ *
+ *   const handle = yield* caller.open("/log.txt", {
+ *     access: "readWrite",
+ *     create: "exclusive"
+ *   })
+ *
+ *   yield* handle.write(new TextEncoder().encode("first "))
+ *   yield* handle.write(new TextEncoder().encode("second"))
+ *   yield* handle.seek(0n, "start")
+ *
+ *   return new TextDecoder().decode(yield* handle.read(64))
+ * }).pipe(Effect.scoped)
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // first second
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import { Effect } from "effect"
+ *
+ * // A derived caller holds the directory's identity, not its path, so renaming
+ * // the directory does not redirect later relative writes.
+ * const program = Effect.gen(function*() {
+ *   const caller = yield* (yield* Vfs.make()).caller()
+ *
+ *   yield* caller.mkdir("/build")
+ *
+ *   const work = yield* caller.withDirectory("/build")
+ *
+ *   yield* caller.rename("/build", "/dist")
+ *   yield* work.writeFile("out.txt", new TextEncoder().encode("done"), {
+ *     access: "write",
+ *     create: "exclusive"
+ *   })
+ *
+ *   return yield* caller.readDirectory("/dist")
+ * }).pipe(Effect.scoped)
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // [ 'out.txt' ]
+ * ```
+ *
+ * @see The filesystem model at `/concepts/filesystem-model`.
  * @category models
  * @since 0.1.0
  */
@@ -292,11 +712,11 @@ export interface Caller {
     readonly lookupReference: (directory: ObjectReference, name: Uint8Array) => Effect.Effect<ObjectReference, FsError>;
     /** Returns a referenced directory's current parent. The root is its own parent. */
     readonly parentReference: (directory: ObjectReference) => Effect.Effect<ObjectReference, FsError>;
-    /** Reads metadata and its matching live revision. */
+    /** Reads metadata and its matching live revision. Requires no permission on the object, as `stat` does not. */
     readonly observeMetadata: (reference: ObjectReference) => Effect.Effect<ObjectObservation<Metadata>, FsError>;
     /** Reads owned directory entries and their matching directory revision. */
     readonly observeDirectory: (reference: ObjectReference) => Effect.Effect<ObjectObservation<ReadonlyArray<DirectoryEntry>>, FsError>;
-    /** Reads an owned symbolic-link target through a stable reference. */
+    /** Reads an owned symbolic-link target through a stable reference. Requires no permission on the link. */
     readonly readLinkReference: (reference: ObjectReference) => Effect.Effect<Uint8Array, FsError>;
     /** Opens a referenced regular file for reading. */
     readonly openReference: (reference: ObjectReference) => Effect.Effect<FileHandle, FsError, Scope.Scope>;
@@ -337,15 +757,15 @@ export interface Caller {
     }) => Effect.Effect<void, FsError>;
     /** Creates a symbolic link. The target bytes are stored without resolving them. */
     readonly symlink: (target: PathInput, path: PathInput, options?: RelativeOptions) => Effect.Effect<void, FsError>;
-    /** Reads a symbolic-link target as UTF-8, failing with `UnrepresentableName` for other bytes. */
+    /** Reads a symbolic-link target as UTF-8, failing `UnrepresentableName` for other bytes. See `readLinkBytes`. */
     readonly readLink: (path: PathInput, options?: RelativeOptions) => Effect.Effect<string, FsError>;
     /** Reads a symbolic-link target as owned bytes. */
     readonly readLinkBytes: (path: PathInput, options?: RelativeOptions) => Effect.Effect<Uint8Array, FsError>;
-    /** Reads directory names as UTF-8, failing if any name is not representable. */
+    /** Reads directory names as UTF-8, failing `UnrepresentableName` for other bytes. See `readDirectoryBytes`. */
     readonly readDirectory: (path: PathInput, options?: RelativeOptions) => Effect.Effect<ReadonlyArray<string>, FsError>;
     /** Reads directory names as owned byte arrays. */
     readonly readDirectoryBytes: (path: PathInput, options?: RelativeOptions) => Effect.Effect<ReadonlyArray<Uint8Array>, FsError>;
-    /** Resolves links and normalizes a path as UTF-8. */
+    /** Resolves links and normalizes a path as UTF-8, failing `UnrepresentableName` for other bytes. See `realPathBytes`. */
     readonly realPath: (path: PathInput, options?: RelativeOptions) => Effect.Effect<string, FsError>;
     /** Resolves links and normalizes a path without requiring UTF-8 names. */
     readonly realPathBytes: (path: PathInput, options?: RelativeOptions) => Effect.Effect<BytePath, FsError>;
@@ -367,6 +787,37 @@ export interface Caller {
 /**
  * A committed namespace or content change emitted by a volume watch stream.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import { Effect, Fiber, Stream } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make()
+ *   const caller = yield* volume.caller()
+ *
+ *   const watcher = yield* volume.watch.pipe(
+ *     Effect.flatMap((stream) => Stream.runCollect(Stream.take(stream, 2))),
+ *     Effect.forkChild({ startImmediately: true })
+ *   )
+ *
+ *   yield* caller.mkdir("/logs")
+ *   yield* caller.rmdir("/logs")
+ *
+ *   // Each event pairs the kind of change with the absolute path it happened to.
+ *   const events = yield* Fiber.join(watcher)
+ *
+ *   return yield* Effect.forEach(events, (change) =>
+ *     Effect.map(
+ *       Vfs.pathToBytes(change.path),
+ *       (bytes) => `${change._tag} ${new TextDecoder().decode(bytes)}`
+ *     ))
+ * }).pipe(Effect.scoped)
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // [ 'Create /logs', 'Remove /logs' ]
+ * ```
+ *
  * @category models
  * @since 0.1.0
  */
@@ -426,6 +877,28 @@ export type OverlayChange = typeof OverlayChange.Type;
 /**
  * Schema for overlay summary filtering.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * 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).then(console.log)
+ * // [ 1, 2 ]
+ * ```
+ *
  * @category schemas
  * @since 0.1.0
  */
@@ -440,6 +913,36 @@ export type OverlayChangesOptions = typeof OverlayChangesOptions.Type;
 /**
  * A complete snapshot and final-difference summary captured from one committed state.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * 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()).writeFile("/out.txt", new TextEncoder().encode("built"), {
+ *     access: "write",
+ *     create: "exclusive"
+ *   })
+ *
+ *   // One committed state: the summary describes exactly the snapshot beside it,
+ *   // so restoring from it cannot disagree with the change list.
+ *   const captured = yield* workspace.capture()
+ *   const restored = yield* Vfs.fromSnapshot(captured.snapshot)
+ *   const reader = yield* restored.caller()
+ *
+ *   return [
+ *     captured.changes.map((change) => change._tag),
+ *     new TextDecoder().decode(yield* reader.readFile("/out.txt"))
+ *   ]
+ * })
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // [ [ 'Added' ], 'built' ]
+ * ```
+ *
  * @category models
  * @since 0.1.0
  */
@@ -452,6 +955,32 @@ export interface OverlayCapture {
 /**
  * An isolated virtual filesystem namespace that creates callers, snapshots, and watch streams.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import { Effect, Fiber, Option, Stream } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make()
+ *   const caller = yield* volume.caller()
+ *
+ *   // `watch` reports future changes only; nothing is replayed.
+ *   const watcher = yield* volume.watch.pipe(
+ *     Effect.flatMap(Stream.runHead),
+ *     Effect.forkChild({ startImmediately: true })
+ *   )
+ *
+ *   yield* caller.mkdir("/logs")
+ *
+ *   const change = yield* Fiber.join(watcher)
+ *
+ *   return Option.getOrElse(Option.map(change, (event) => event._tag), () => "none")
+ * }).pipe(Effect.scoped)
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // Create
+ * ```
+ *
  * @category models
  * @since 0.1.0
  */
@@ -467,6 +996,30 @@ export interface Volume {
 /**
  * An ordinary volume with final-state inspection relative to one immutable snapshot base.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * 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()).writeFile("/added.txt", new Uint8Array([1]), {
+ *     access: "write",
+ *     create: "exclusive"
+ *   })
+ *
+ *   // `capture` pairs one committed snapshot with the summary describing it.
+ *   const captured = yield* workspace.capture()
+ *
+ *   return captured.changes.map((change) => change._tag)
+ * })
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // [ 'Added' ]
+ * ```
+ *
  * @category models
  * @since 0.1.0
  */
@@ -479,6 +1032,35 @@ export interface OverlayVolume extends Volume {
 /**
  * Optional Effect service for providing an existing filesystem caller.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * 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).then(console.log)
+ * // Uint8Array(1) [ 49 ]
+ * ```
+ *
+ * @see The testing guide at `/guides/testing-with-an-isolated-filesystem`.
  * @category services
  * @since 0.1.0
  */
@@ -488,6 +1070,32 @@ export type CurrentFileSystem = VfsModel.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 { 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).then(console.log)
+ * // 1
+ * ```
+ *
+ * @see {@link decodeSnapshot} for reading the bytes back under limits.
  * @category serialization
  * @since 0.1.0
  */
@@ -495,14 +1103,70 @@ export declare const encodeSnapshot: (snapshot: Snapshot) => Effect.Effect<Uint8
 /**
  * Decodes version 1 snapshot bytes while enforcing explicit input and payload limits.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * 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).then(console.log)
+ * // [ 'LimitExceeded', 'encodedBytes' ]
+ * ```
+ *
+ * @see {@link DecodeLimits} for what each bound protects.
  * @category serialization
  * @since 0.1.0
  */
 export declare const decodeSnapshot: (input: Uint8Array, limits: DecodeLimits) => Effect.Effect<Snapshot, ImageError>;
 /**
  * Computes an exact portable delta between two immutable snapshots.
- * Requires the platform-neutral `Crypto.Crypto` service for base identity.
+ * 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
  */
@@ -520,8 +1184,35 @@ export declare const diffSnapshots: (base: Snapshot, target: Snapshot, limits?:
 } | undefined) => Effect.Effect<SnapshotDeltaModel.SnapshotDelta, VfsModel.ConfigurationError | ImageError | import("effect/PlatformError").PlatformError, import("effect/Crypto").Crypto>;
 /**
  * Verifies an exact snapshot delta against its base and derives an owned path-oriented summary.
- * Requires the platform-neutral `Crypto.Crypto` service for base identity.
+ * 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
  */
@@ -555,8 +1246,40 @@ export declare const inspectSnapshotDelta: (base: Snapshot, delta: SnapshotDelta
 })[], VfsModel.ConfigurationError | ImageError | import("effect/PlatformError").PlatformError | SnapshotDeltaModel.SnapshotDeltaError, import("effect/Crypto").Crypto>;
 /**
  * Applies an exact delta to its semantically matching base and returns a new snapshot.
- * Requires the platform-neutral `Crypto.Crypto` service for base identity.
+ * 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
  */
@@ -576,6 +1299,34 @@ export declare const applySnapshotDelta: (base: Snapshot, delta: SnapshotDeltaMo
  * 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
  */
@@ -587,6 +1338,28 @@ export declare const SnapshotDeltaFromBytes: (limits?: SnapshotDeltaModel.Snapsh
  *
  * 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
  */
@@ -605,6 +1378,26 @@ export declare const pathToBytes: (path: BytePath) => Effect.Effect<Uint8Array,
  *
  * Fixture paths must be absolute, unique, and explicitly include their parent directories.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * 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).then(console.log)
+ * // rejected: InvalidStructure
+ * ```
+ *
  * @category schemas
  * @since 0.1.0
  */
@@ -624,6 +1417,26 @@ export type Fixture = typeof Fixture.Type;
  * 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 { 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).then(console.log)
+ * // Uint8Array(2) [ 104, 105 ]
+ * ```
+ *
+ * @see The testing guide at `/guides/testing-with-an-isolated-filesystem`.
  * @category constructors
  * @since 0.1.0
  */
@@ -631,6 +1444,40 @@ export declare const make: (options?: VolumeOptions) => Effect.Effect<Volume, Co
 /**
  * Restores a fresh volume from an opaque snapshot under the supplied destination limits.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * 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).then(console.log)
+ * // [ 'one', 'two' ]
+ * ```
+ *
+ * @see {@link makeOverlay} for a copy-on-write workspace over the same base.
  * @category constructors
  * @since 0.1.0
  */
@@ -648,6 +1495,39 @@ export declare const fromSnapshot: (snapshot: Snapshot, options?: VolumeOptions)
  * 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 { 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).then(console.log)
+ * // [ '{}', [ 'Updated' ] ]
+ * ```
+ *
+ * @see The overlay guide at `/guides/overlay-filesystems`.
  * @category constructors
  * @since 0.1.0
  */
@@ -655,6 +1535,35 @@ export declare const makeOverlay: (base: Snapshot, options?: VolumeOptions) => E
 /**
  * Builds a fresh volume from a validated final-state fixture.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * 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).then(console.log)
+ * // [ 'package.json', 'latest' ]
+ * ```
+ *
+ * @see The fixtures guide at `/guides/fixtures-and-snapshots`.
  * @category constructors
  * @since 0.1.0
  */