@effect-vfs/core 0.2.0 → 0.3.1

package/dist/VirtualFileSystem.d.ts

@@ -8,25 +8,31 @@
  *
  * @since 0.1.0
  */
-import * as ByteSize from "effect/ByteSize";
-import * as Context from "effect/Context";
-import { DecodeLimits, ImageError, type Snapshot } from "./Snapshot.js";
-export { DecodeLimits, ImageError, type Snapshot, SnapshotTypeId } from "./Snapshot.js";
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
-import * as Scope from "effect/Scope";
-import * as Stream from "effect/Stream";
-import { BytePath } from "./BytePath.js";
+import type * as Scope from "effect/Scope";
+import type * as Stream from "effect/Stream";
+import type { BytePath } from "./BytePath.js";
 export { BytePath } from "./BytePath.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";
 export { SnapshotChange, SnapshotChangesOptions, type SnapshotDelta, SnapshotDeltaError, SnapshotDeltaLimits, SnapshotDeltaTypeId, SnapshotDifference, SnapshotNodeKind } from "./SnapshotDelta.js";
-declare const VolumeId: unique symbol;
-declare const CallerId: unique symbol;
-declare const FileHandleId: unique symbol;
-declare const DirectoryHandleId: unique symbol;
+declare const VolumeId: typeof VfsModel.VolumeId;
+declare const CallerId: typeof VfsModel.CallerId;
+declare const FileHandleId: typeof VfsModel.FileHandleId;
+declare const DirectoryHandleId: typeof VfsModel.DirectoryHandleId;
+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,10 +40,34 @@ 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
  */
-export declare const FsCode: Schema.Literals<readonly ["NotFound", "AlreadyExists", "NotEmpty", "NotDirectory", "AccessDenied", "InvalidHandle", "ForeignHandle", "ClosedCaller", "InvalidArgument", "InvalidPathEncoding", "PathTooLong", "NoSpace", "IsDirectory", "FileTooLarge", "NoData", "SymlinkLoop", "UnrepresentableName"]>;
+export declare const FsCode: typeof VfsModel.FsCode;
 /**
  * A portable virtual filesystem error code.
  *
@@ -45,37 +75,67 @@ export declare const FsCode: Schema.Literals<readonly ["NotFound", "AlreadyExist
  * @since 0.1.0
  */
 export type FsCode = typeof FsCode.Type;
-declare const FsError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
-    readonly _tag: "FsError";
-} & Readonly<A>;
 /**
  * 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
  */
-export declare class FsError extends FsError_base<{
-    /** Machine-readable reason for the failure. */
-    readonly code: FsCode;
-    /** Operation that detected the failure. */
-    readonly operation: string;
-    /** Path involved in the failure, when one path identifies it. */
-    readonly path?: PathInput;
-}> {
+export declare const FsError: typeof VfsModel.FsError;
+/** @internal */
+export interface FsError extends VfsModel.FsError {
 }
-declare const ConfigurationError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
-    readonly _tag: "ConfigurationError";
-} & Readonly<A>;
 /**
  * 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
  */
-export declare class ConfigurationError extends ConfigurationError_base<{
-    /** Name of the rejected option. */
-    readonly field: string;
-}> {
+export declare const ConfigurationError: typeof VfsModel.ConfigurationError;
+/** @internal */
+export interface ConfigurationError extends VfsModel.ConfigurationError {
 }
 /**
  * Schema for a caller's numeric identity, supplementary groups, and explicit privilege.
@@ -83,16 +143,7 @@ export declare class ConfigurationError extends ConfigurationError_base<{
  * @category schemas
  * @since 0.1.0
  */
-export declare const Identity: Schema.Struct<{
-    /** Numeric user identifier used by ownership and permission checks. */
-    readonly uid: Schema.Finite;
-    /** Primary numeric group identifier. */
-    readonly gid: Schema.Finite;
-    /** Supplementary group identifiers used by group permission checks. */
-    readonly groups: Schema.$Array<Schema.Finite>;
-    /** Grants root-style permission bypasses independently of `uid`. */
-    readonly privileged: Schema.Boolean;
-}>;
+export declare const Identity: typeof VfsModel.Identity;
 /**
  * A caller identity used for permission checks.
  *
@@ -103,24 +154,37 @@ 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
  */
-export declare const RootCallerOptions: Schema.Struct<{
-    /** Caller identity. Defaults to privileged uid and gid `0`. */
-    readonly identity: Schema.optionalKey<Schema.Struct<{
-        /** Numeric user identifier used by ownership and permission checks. */
-        readonly uid: Schema.Finite;
-        /** Primary numeric group identifier. */
-        readonly gid: Schema.Finite;
-        /** Supplementary group identifiers used by group permission checks. */
-        readonly groups: Schema.$Array<Schema.Finite>;
-        /** Grants root-style permission bypasses independently of `uid`. */
-        readonly privileged: Schema.Boolean;
-    }>>;
-    /** Creation mask applied to requested modes. Defaults to `0o022`. */
-    readonly umask: Schema.optionalKey<Schema.Finite>;
-}>;
+export declare const RootCallerOptions: typeof VfsModel.RootCallerOptions;
 /**
  * Options for creating a root caller on a volume.
  *
@@ -131,19 +195,33 @@ 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
  */
-export declare const VolumeOptions: Schema.Struct<{
-    /** Maximum number of filesystem nodes. Omission leaves the count unbounded. */
-    readonly maxEntries: Schema.optionalKey<Schema.Finite>;
-    /** Maximum combined regular-file content in bytes. */
-    readonly maxBytes: Schema.optionalKey<Schema.ByteSize>;
-    /** Maximum content size of one regular file in bytes. */
-    readonly maxFileBytes: Schema.optionalKey<Schema.ByteSize>;
-    /** Maximum encoded byte length of an absolute or relative path. */
-    readonly maxPathBytes: Schema.optionalKey<Schema.ByteSize>;
-}>;
+export declare const VolumeOptions: typeof VfsModel.VolumeOptions;
 /**
  * Capacity and path limits for a volume.
  *
@@ -154,22 +232,33 @@ 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
  */
-export declare const Metadata: Schema.Struct<{
-    readonly kind: Schema.Literals<readonly ["directory", "file", "symlink"]>;
-    readonly ino: Schema.BigInt;
-    readonly nlink: Schema.Finite;
-    readonly size: Schema.BigInt;
-    readonly uid: Schema.Finite;
-    readonly gid: Schema.Finite;
-    readonly mode: Schema.Finite;
-    readonly atimeNs: Schema.BigInt;
-    readonly mtimeNs: Schema.BigInt;
-    readonly ctimeNs: Schema.BigInt;
-    readonly birthtimeNs: Schema.BigInt;
-}>;
+export declare const Metadata: typeof VfsModel.Metadata;
 /**
  * Metadata for a directory, regular file, or symbolic link.
  *
@@ -177,6 +266,63 @@ export declare const Metadata: Schema.Struct<{
  * @since 0.1.0
  */
 export type Metadata = typeof Metadata.Type;
+/**
+ * An opaque identity for one object in one live volume.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface ObjectReference {
+    readonly [ObjectReferenceId]: true;
+}
+/**
+ * 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
+ */
+export interface ObjectObservation<A> {
+    readonly value: A;
+    readonly revision: bigint;
+}
+/**
+ * One owned directory name paired with the referenced child object.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface DirectoryEntry {
+    readonly name: Uint8Array;
+    readonly reference: ObjectReference;
+}
 /**
  * Resolves a relative path from a live directory handle instead of the caller's directory.
  *
@@ -190,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
  */
@@ -203,10 +379,7 @@ export interface MetadataOptions extends RelativeOptions {
  * @category schemas
  * @since 0.1.0
  */
-export declare const OwnerUpdate: Schema.Struct<{
-    readonly uid: Schema.optionalKey<Schema.Finite>;
-    readonly gid: Schema.optionalKey<Schema.Finite>;
-}>;
+export declare const OwnerUpdate: typeof VfsModel.OwnerUpdate;
 /**
  * An owner update for `chown` operations.
  *
@@ -220,38 +393,42 @@ export type OwnerUpdate = typeof OwnerUpdate.Type;
  * @category schemas
  * @since 0.1.0
  */
-export declare const TimeUpdate: Schema.Union<readonly [Schema.Struct<{
-    readonly kind: Schema.Literal<"now">;
-}>, Schema.Struct<{
-    readonly kind: Schema.Literal<"omit">;
-}>, Schema.Struct<{
-    readonly kind: Schema.Literal<"value">;
-    readonly nanoseconds: Schema.BigInt;
-}>]>;
+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
  */
-export declare const Times: Schema.Struct<{
-    readonly access: Schema.Union<readonly [Schema.Struct<{
-        readonly kind: Schema.Literal<"now">;
-    }>, Schema.Struct<{
-        readonly kind: Schema.Literal<"omit">;
-    }>, Schema.Struct<{
-        readonly kind: Schema.Literal<"value">;
-        readonly nanoseconds: Schema.BigInt;
-    }>]>;
-    readonly modification: Schema.Union<readonly [Schema.Struct<{
-        readonly kind: Schema.Literal<"now">;
-    }>, Schema.Struct<{
-        readonly kind: Schema.Literal<"omit">;
-    }>, Schema.Struct<{
-        readonly kind: Schema.Literal<"value">;
-        readonly nanoseconds: Schema.BigInt;
-    }>]>;
-}>;
+export declare const Times: typeof VfsModel.Times;
 /**
  * Access and modification time updates for `utimes` operations.
  *
@@ -262,14 +439,40 @@ 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
  */
 export interface DirectoryHandle {
     readonly [DirectoryHandleId]: true;
-    /** Reads metadata for the directory while the handle remains open. */
     readonly stat: Effect.Effect<Metadata, FsError>;
-    /** Closes the handle. A repeated explicit close fails; scope cleanup remains safe. */
     readonly close: Effect.Effect<void, FsError>;
 }
 /**
@@ -278,7 +481,7 @@ export interface DirectoryHandle {
  * @category schemas
  * @since 0.1.0
  */
-export declare const SeekMode: Schema.Literals<readonly ["start", "current", "end", "data", "hole"]>;
+export declare const SeekMode: typeof VfsModel.SeekMode;
 /**
  * The origin used by a file handle seek operation.
  *
@@ -289,23 +492,34 @@ 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
  */
-export declare const OpenSettings: Schema.Struct<{
-    /** Permitted operations on the returned handle. */
-    readonly access: Schema.Literals<readonly ["read", "write", "readWrite"]>;
-    /** Creation policy. Defaults to `"never"`. */
-    readonly create: Schema.optionalKey<Schema.Literals<readonly ["never", "ifMissing", "exclusive"]>>;
-    /** Requested mode for a new file, before applying the caller's umask. */
-    readonly mode: Schema.optionalKey<Schema.Finite>;
-    /** Write at the current end of file regardless of the handle cursor. */
-    readonly append: Schema.optionalKey<Schema.Boolean>;
-    /** Truncate an existing regular file to zero bytes during open. */
-    readonly truncate: Schema.optionalKey<Schema.Boolean>;
-    /** Follow the final symbolic link. Defaults to `true`. */
-    readonly followFinalSymlink: Schema.optionalKey<Schema.Boolean>;
-}>;
+export declare const OpenSettings: typeof VfsModel.OpenSettings;
 /**
  * Options for acquiring a scoped file handle.
  *
@@ -313,34 +527,75 @@ export declare const OpenSettings: Schema.Struct<{
  * @since 0.1.0
  */
 export type OpenOptions = typeof OpenSettings.Type & RelativeOptions;
-declare const WriteFileSettings: Schema.Struct<{
-    /** Permitted operations on the returned handle. */
-    readonly access: Schema.Literals<readonly ["read", "write", "readWrite"]>;
-    /** Creation policy. Defaults to `"never"`. */
-    readonly create: Schema.optionalKey<Schema.Literals<readonly ["never", "ifMissing", "exclusive"]>>;
-    /** Requested mode for a new file, before applying the caller's umask. */
-    readonly mode: Schema.optionalKey<Schema.Finite>;
-    /** Write at the current end of file regardless of the handle cursor. */
-    readonly append: Schema.optionalKey<Schema.Boolean>;
-    /** Truncate an existing regular file to zero bytes during open. */
-    readonly truncate: Schema.optionalKey<Schema.Boolean>;
-    /** Follow the final symbolic link. Defaults to `true`. */
-    readonly followFinalSymlink: Schema.optionalKey<Schema.Boolean>;
-    /** Replace the final symbolic link itself instead of its target. */
-    readonly replaceFinalSymlink: Schema.optionalKey<Schema.Boolean>;
-    /** Mode to apply after replacing an existing file. */
-    readonly finalMode: Schema.optionalKey<Schema.Finite>;
-}>;
 /**
  * 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
  */
-export type WriteFileOptions = typeof WriteFileSettings.Type & RelativeOptions;
+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
  */
@@ -368,18 +623,108 @@ 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
  */
 export interface Caller {
     readonly [CallerId]: true;
+    /** Returns the stable reference for this volume's root directory. */
+    readonly rootReference: Effect.Effect<ObjectReference, FsError>;
+    /** Looks up one byte-preserving child name from a referenced directory. */
+    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. 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. 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>;
     /** Reads metadata, following the final symbolic link by default. */
     readonly stat: (path: PathInput, options?: RelativeOptions) => Effect.Effect<Metadata, FsError>;
     /** Atomically moves an entry within this volume without replacing a non-empty directory. */
     readonly rename: (source: PathInput, destination: PathInput, options?: {
-        /** Base directory for a relative source path. */
         readonly sourceRelativeTo?: DirectoryHandle;
-        /** Base directory for a relative destination path. */
         readonly destinationRelativeTo?: DirectoryHandle;
     }) => Effect.Effect<void, FsError>;
     /** Reads and returns an owned copy of a regular file's complete contents. */
@@ -406,24 +751,21 @@ export interface Caller {
     readonly lstat: (path: PathInput, options?: RelativeOptions) => Effect.Effect<Metadata, FsError>;
     /** Creates a hard link to an existing non-directory entry. */
     readonly link: (source: PathInput, destination: PathInput, options?: {
-        /** Base directory for a relative source path. */
         readonly sourceRelativeTo?: DirectoryHandle;
-        /** Base directory for a relative destination path. */
         readonly destinationRelativeTo?: DirectoryHandle;
-        /** Link to the final symbolic link's target instead of the link itself. */
         readonly followSourceSymlink?: boolean;
     }) => 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>;
@@ -435,7 +777,6 @@ export interface Caller {
     readonly rmdir: (path: PathInput, options?: RelativeOptions) => Effect.Effect<void, FsError>;
     /** Creates one directory. Parent directories must already exist. */
     readonly mkdir: (path: PathInput, options?: RelativeOptions & {
-        /** Requested mode before applying the caller's umask. Defaults to `0o777`. */
         readonly mode?: number;
     }) => Effect.Effect<void, FsError>;
     /** Creates a scoped caller whose current directory is the resolved directory identity. */
@@ -446,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
  */
@@ -461,7 +833,7 @@ export interface Change {
  * @category schemas
  * @since 0.1.0
  */
-export declare const OverlayNodeKind: Schema.Literals<readonly ["directory", "file", "symlink"]>;
+export declare const OverlayNodeKind: typeof VfsModel.OverlayNodeKind;
 /**
  * A filesystem entry kind reported by an overlay summary.
  *
@@ -475,7 +847,7 @@ export type OverlayNodeKind = typeof OverlayNodeKind.Type;
  * @category schemas
  * @since 0.1.0
  */
-export declare const OverlayDifference: Schema.Literals<readonly ["content", "mode", "uid", "gid", "atimeNs", "mtimeNs", "ctimeNs", "birthtimeNs"]>;
+export declare const OverlayDifference: typeof VfsModel.OverlayDifference;
 /**
  * A content, ownership, permission, or timestamp field that differs from the overlay base.
  *
@@ -494,27 +866,7 @@ export type OverlayDifference = typeof OverlayDifference.Type;
  * @category schemas
  * @since 0.1.0
  */
-export declare const OverlayChange: Schema.Union<readonly [Schema.TaggedStruct<"Added", {
-    readonly path: Schema.declare<BytePath, BytePath>;
-    readonly kind: Schema.Literals<readonly ["directory", "file", "symlink"]>;
-}>, Schema.TaggedStruct<"Removed", {
-    readonly path: Schema.declare<BytePath, BytePath>;
-    readonly kind: Schema.Literals<readonly ["directory", "file", "symlink"]>;
-}>, Schema.TaggedStruct<"Replaced", {
-    readonly path: Schema.declare<BytePath, BytePath>;
-    readonly beforeKind: Schema.Literals<readonly ["directory", "file", "symlink"]>;
-    readonly afterKind: Schema.Literals<readonly ["directory", "file", "symlink"]>;
-    readonly differences: Schema.$Array<Schema.Literals<readonly ["content", "mode", "uid", "gid", "atimeNs", "mtimeNs", "ctimeNs", "birthtimeNs"]>>;
-}>, Schema.TaggedStruct<"Renamed", {
-    readonly from: Schema.declare<BytePath, BytePath>;
-    readonly to: Schema.declare<BytePath, BytePath>;
-    readonly kind: Schema.Literals<readonly ["directory", "file", "symlink"]>;
-    readonly differences: Schema.$Array<Schema.Literals<readonly ["content", "mode", "uid", "gid", "atimeNs", "mtimeNs", "ctimeNs", "birthtimeNs"]>>;
-}>, Schema.TaggedStruct<"Updated", {
-    readonly path: Schema.declare<BytePath, BytePath>;
-    readonly kind: Schema.Literals<readonly ["directory", "file", "symlink"]>;
-    readonly differences: Schema.$Array<Schema.Literals<readonly ["content", "mode", "uid", "gid", "atimeNs", "mtimeNs", "ctimeNs", "birthtimeNs"]>>;
-}>]>;
+export declare const OverlayChange: typeof VfsModel.OverlayChange;
 /**
  * A path-oriented final-state difference from an overlay's immutable base.
  *
@@ -525,13 +877,32 @@ 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
  */
-export declare const OverlayChangesOptions: Schema.Struct<{
-    /** Include access, modification, change, and birth-time differences. Defaults to `false`. */
-    readonly includeTimestamps: Schema.optionalKey<Schema.Boolean>;
-}>;
+export declare const OverlayChangesOptions: typeof VfsModel.OverlayChangesOptions;
 /**
  * Filtering options for an overlay final-difference summary.
  *
@@ -542,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
  */
@@ -554,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
  */
@@ -569,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
  */
@@ -578,18 +1029,73 @@ export interface OverlayVolume extends Volume {
     /** Captures one committed state when this reusable effect executes. */
     readonly capture: (options?: OverlayChangesOptions) => Effect.Effect<OverlayCapture, ConfigurationError | ImageError>;
 }
-declare const CurrentFileSystem_base: Context.ServiceClass<CurrentFileSystem, "@effect-vfs/core/CurrentFileSystem", Caller>;
 /**
  * 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
  */
-export declare class CurrentFileSystem extends CurrentFileSystem_base {
-}
+export declare const CurrentFileSystem: typeof VfsModel.CurrentFileSystem;
+/** @internal */
+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
  */
@@ -597,45 +1103,131 @@ 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
  */
 export declare const diffSnapshots: (base: Snapshot, target: Snapshot, limits?: {
-    readonly maxEncodedBytes: ByteSize.ByteSize;
-    readonly maxIdentityBytes: ByteSize.ByteSize;
+    readonly maxEncodedBytes: import("effect/ByteSize").ByteSize;
+    readonly maxIdentityBytes: import("effect/ByteSize").ByteSize;
     readonly maxDeltaRecords: number;
-    readonly maxDecodedDeltaBytes: ByteSize.ByteSize;
+    readonly maxDecodedDeltaBytes: import("effect/ByteSize").ByteSize;
     readonly maxBaseRecords: number;
     readonly maxTargetRecords: number;
     readonly maxEntries: number;
     readonly maxOutputRecords: number;
-    readonly maxOutputBytes: ByteSize.ByteSize;
+    readonly maxOutputBytes: import("effect/ByteSize").ByteSize;
     readonly maxInheritedRecords: number;
-} | undefined) => Effect.Effect<SnapshotDeltaModel.SnapshotDelta, ConfigurationError | ImageError | import("effect/PlatformError").PlatformError, import("effect/Crypto").Crypto>;
+} | 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
  */
 export declare const inspectSnapshotDelta: (base: Snapshot, delta: SnapshotDeltaModel.SnapshotDelta, options?: {
     readonly includeTimestamps?: boolean;
 } | undefined, limits?: {
-    readonly maxEncodedBytes: ByteSize.ByteSize;
-    readonly maxIdentityBytes: ByteSize.ByteSize;
+    readonly maxEncodedBytes: import("effect/ByteSize").ByteSize;
+    readonly maxIdentityBytes: import("effect/ByteSize").ByteSize;
     readonly maxDeltaRecords: number;
-    readonly maxDecodedDeltaBytes: ByteSize.ByteSize;
+    readonly maxDecodedDeltaBytes: import("effect/ByteSize").ByteSize;
     readonly maxBaseRecords: number;
     readonly maxTargetRecords: number;
     readonly maxEntries: number;
     readonly maxOutputRecords: number;
-    readonly maxOutputBytes: ByteSize.ByteSize;
+    readonly maxOutputBytes: import("effect/ByteSize").ByteSize;
     readonly maxInheritedRecords: number;
 } | undefined) => Effect.Effect<readonly ({
     readonly _tag: "Added";
@@ -651,29 +1243,92 @@ export declare const inspectSnapshotDelta: (base: Snapshot, delta: SnapshotDelta
     readonly beforeKind: "directory" | "file" | "symlink";
     readonly afterKind: "directory" | "file" | "symlink";
     readonly differences: readonly ("atimeNs" | "birthtimeNs" | "content" | "ctimeNs" | "gid" | "hardLinks" | "kind" | "mode" | "mtimeNs" | "target" | "uid")[];
-})[], ConfigurationError | ImageError | import("effect/PlatformError").PlatformError | SnapshotDeltaModel.SnapshotDeltaError, import("effect/Crypto").Crypto>;
+})[], 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
  */
 export declare const applySnapshotDelta: (base: Snapshot, delta: SnapshotDeltaModel.SnapshotDelta, limits?: {
-    readonly maxEncodedBytes: ByteSize.ByteSize;
-    readonly maxIdentityBytes: ByteSize.ByteSize;
+    readonly maxEncodedBytes: import("effect/ByteSize").ByteSize;
+    readonly maxIdentityBytes: import("effect/ByteSize").ByteSize;
     readonly maxDeltaRecords: number;
-    readonly maxDecodedDeltaBytes: ByteSize.ByteSize;
+    readonly maxDecodedDeltaBytes: import("effect/ByteSize").ByteSize;
     readonly maxBaseRecords: number;
     readonly maxTargetRecords: number;
     readonly maxEntries: number;
     readonly maxOutputRecords: number;
-    readonly maxOutputBytes: ByteSize.ByteSize;
+    readonly maxOutputBytes: import("effect/ByteSize").ByteSize;
     readonly maxInheritedRecords: number;
-} | undefined) => Effect.Effect<Snapshot, ConfigurationError | ImageError | import("effect/PlatformError").PlatformError | SnapshotDeltaModel.SnapshotDeltaError, import("effect/Crypto").Crypto>;
+} | undefined) => Effect.Effect<Snapshot, VfsModel.ConfigurationError | ImageError | import("effect/PlatformError").PlatformError | SnapshotDeltaModel.SnapshotDeltaError, import("effect/Crypto").Crypto>;
 /**
  * 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
  */
 export declare const SnapshotDeltaFromBytes: (limits?: SnapshotDeltaModel.SnapshotDeltaLimits) => Schema.decodeTo<Schema.declare<SnapshotDeltaModel.SnapshotDelta, SnapshotDeltaModel.SnapshotDelta>, Schema.Uint8Array, never, never>;
 /**
@@ -683,17 +1338,77 @@ 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
  */
-export declare const pathFromBytes: (bytes: Uint8Array<ArrayBufferLike>) => Effect.Effect<BytePath, FsError, never>;
+export declare const pathFromBytes: (bytes: Uint8Array) => Effect.Effect<BytePath, FsError>;
 /**
  * Copies the bytes held by an opaque byte path.
  *
  * @category getters
  * @since 0.1.0
  */
-export declare const pathToBytes: (path: BytePath) => Effect.Effect<Uint8Array<ArrayBuffer>, FsError, never>;
+export declare const pathToBytes: (path: BytePath) => Effect.Effect<Uint8Array, FsError>;
+/**
+ * Schema for a complete fixture namespace with optional metadata and forward hard links.
+ *
+ * **Details**
+ *
+ * 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
+ */
+export declare const Fixture: typeof VfsModel.Fixture;
+/**
+ * A complete filesystem fixture accepted by `fromFixture`.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Fixture = typeof Fixture.Type;
 /**
  * Creates a fresh empty volume and captures the current Effect `Clock`.
  *
@@ -702,27 +1417,71 @@ export declare const pathToBytes: (path: BytePath) => Effect.Effect<Uint8Array<A
  * 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
  */
-export declare const make: (options?: {
-    readonly maxEntries?: number;
-    readonly maxBytes?: ByteSize.ByteSize;
-    readonly maxFileBytes?: ByteSize.ByteSize;
-    readonly maxPathBytes?: ByteSize.ByteSize;
-} | undefined) => Effect.Effect<Volume, ConfigurationError, never>;
+export declare const make: (options?: VolumeOptions) => Effect.Effect<Volume, ConfigurationError>;
 /**
  * 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
  */
-export declare const fromSnapshot: (snapshot: Snapshot, options?: {
-    readonly maxEntries?: number;
-    readonly maxBytes?: ByteSize.ByteSize;
-    readonly maxFileBytes?: ByteSize.ByteSize;
-    readonly maxPathBytes?: ByteSize.ByteSize;
-} | undefined) => Effect.Effect<Volume, ConfigurationError | ImageError, never>;
+export declare const fromSnapshot: (snapshot: Snapshot, options?: VolumeOptions) => Effect.Effect<Volume, ConfigurationError | ImageError>;
 /**
  * Creates an isolated writable volume relative to one immutable snapshot base.
  *
@@ -736,149 +1495,77 @@ export declare const fromSnapshot: (snapshot: Snapshot, options?: {
  * Invalid base snapshots fail with `ImageError`; invalid volume limits fail
  * with `ConfigurationError`. Each execution creates a fresh workspace.
  *
- * @category constructors
- * @since 0.1.0
- */
-export declare const makeOverlay: (base: Snapshot, options?: {
-    readonly maxEntries?: number;
-    readonly maxBytes?: ByteSize.ByteSize;
-    readonly maxFileBytes?: ByteSize.ByteSize;
-    readonly maxPathBytes?: ByteSize.ByteSize;
-} | undefined) => Effect.Effect<OverlayVolume, ConfigurationError | ImageError, never>;
-/**
- * Schema for a complete fixture namespace with optional metadata and forward hard links.
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import { Effect } from "effect"
  *
- * **Details**
+ * const program = Effect.gen(function*() {
+ *   const base = yield* Vfs.make()
+ *   const origin = yield* base.caller()
  *
- * Fixture paths must be absolute, unique, and explicitly include their parent directories.
+ *   yield* origin.writeFile("/config.json", new TextEncoder().encode("{}"), {
+ *     access: "write",
+ *     create: "exclusive"
+ *   })
  *
- * @category schemas
- * @since 0.1.0
- */
-export declare const Fixture: Schema.Struct<{
-    readonly rootMetadata: Schema.optionalKey<Schema.Struct<{
-        readonly uid: Schema.optionalKey<Schema.Finite>;
-        readonly gid: Schema.optionalKey<Schema.Finite>;
-        readonly mode: Schema.optionalKey<Schema.Finite>;
-        readonly atimeNs: Schema.optionalKey<Schema.BigInt>;
-        readonly mtimeNs: Schema.optionalKey<Schema.BigInt>;
-        readonly ctimeNs: Schema.optionalKey<Schema.BigInt>;
-        readonly birthtimeNs: Schema.optionalKey<Schema.BigInt>;
-    }>>;
-    readonly entries: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
-        readonly kind: Schema.Literal<"directory">;
-        readonly path: Schema.Union<readonly [Schema.String, Schema.declare<BytePath, BytePath>]>;
-        readonly metadata: Schema.optionalKey<Schema.Struct<{
-            readonly uid: Schema.optionalKey<Schema.Finite>;
-            readonly gid: Schema.optionalKey<Schema.Finite>;
-            readonly mode: Schema.optionalKey<Schema.Finite>;
-            readonly atimeNs: Schema.optionalKey<Schema.BigInt>;
-            readonly mtimeNs: Schema.optionalKey<Schema.BigInt>;
-            readonly ctimeNs: Schema.optionalKey<Schema.BigInt>;
-            readonly birthtimeNs: Schema.optionalKey<Schema.BigInt>;
-        }>>;
-    }>, Schema.Struct<{
-        readonly kind: Schema.Literal<"file">;
-        readonly path: Schema.Union<readonly [Schema.String, Schema.declare<BytePath, BytePath>]>;
-        readonly bytes: Schema.Uint8Array;
-        readonly metadata: Schema.optionalKey<Schema.Struct<{
-            readonly uid: Schema.optionalKey<Schema.Finite>;
-            readonly gid: Schema.optionalKey<Schema.Finite>;
-            readonly mode: Schema.optionalKey<Schema.Finite>;
-            readonly atimeNs: Schema.optionalKey<Schema.BigInt>;
-            readonly mtimeNs: Schema.optionalKey<Schema.BigInt>;
-            readonly ctimeNs: Schema.optionalKey<Schema.BigInt>;
-            readonly birthtimeNs: Schema.optionalKey<Schema.BigInt>;
-        }>>;
-    }>, Schema.Struct<{
-        readonly kind: Schema.Literal<"symlink">;
-        readonly path: Schema.Union<readonly [Schema.String, Schema.declare<BytePath, BytePath>]>;
-        readonly target: Schema.Union<readonly [Schema.String, Schema.declare<BytePath, BytePath>]>;
-        readonly metadata: Schema.optionalKey<Schema.Struct<{
-            readonly uid: Schema.optionalKey<Schema.Finite>;
-            readonly gid: Schema.optionalKey<Schema.Finite>;
-            readonly mode: Schema.optionalKey<Schema.Finite>;
-            readonly atimeNs: Schema.optionalKey<Schema.BigInt>;
-            readonly mtimeNs: Schema.optionalKey<Schema.BigInt>;
-            readonly ctimeNs: Schema.optionalKey<Schema.BigInt>;
-            readonly birthtimeNs: Schema.optionalKey<Schema.BigInt>;
-        }>>;
-    }>, Schema.Struct<{
-        readonly kind: Schema.Literal<"hardLink">;
-        readonly path: Schema.Union<readonly [Schema.String, Schema.declare<BytePath, BytePath>]>;
-        readonly target: Schema.Union<readonly [Schema.String, Schema.declare<BytePath, BytePath>]>;
-    }>]>>;
-}>;
-/**
- * A complete filesystem fixture accepted by `fromFixture`.
+ *   const workspace = yield* Vfs.makeOverlay(yield* base.snapshot)
  *
- * @category models
+ *   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
  */
-export type Fixture = typeof Fixture.Type;
+export declare const makeOverlay: (base: Snapshot, options?: VolumeOptions) => Effect.Effect<OverlayVolume, ConfigurationError | ImageError>;
 /**
  * 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
  */
-export declare const fromFixture: (fixture: {
-    readonly rootMetadata?: {
-        readonly uid?: number;
-        readonly gid?: number;
-        readonly mode?: number;
-        readonly atimeNs?: bigint;
-        readonly mtimeNs?: bigint;
-        readonly ctimeNs?: bigint;
-        readonly birthtimeNs?: bigint;
-    };
-    readonly entries: readonly ({
-        readonly kind: "directory";
-        readonly path: string | BytePath;
-        readonly metadata?: {
-            readonly uid?: number;
-            readonly gid?: number;
-            readonly mode?: number;
-            readonly atimeNs?: bigint;
-            readonly mtimeNs?: bigint;
-            readonly ctimeNs?: bigint;
-            readonly birthtimeNs?: bigint;
-        };
-    } | {
-        readonly kind: "file";
-        readonly path: string | BytePath;
-        readonly bytes: Uint8Array<ArrayBufferLike>;
-        readonly metadata?: {
-            readonly uid?: number;
-            readonly gid?: number;
-            readonly mode?: number;
-            readonly atimeNs?: bigint;
-            readonly mtimeNs?: bigint;
-            readonly ctimeNs?: bigint;
-            readonly birthtimeNs?: bigint;
-        };
-    } | {
-        readonly kind: "symlink";
-        readonly path: string | BytePath;
-        readonly target: string | BytePath;
-        readonly metadata?: {
-            readonly uid?: number;
-            readonly gid?: number;
-            readonly mode?: number;
-            readonly atimeNs?: bigint;
-            readonly mtimeNs?: bigint;
-            readonly ctimeNs?: bigint;
-            readonly birthtimeNs?: bigint;
-        };
-    } | {
-        readonly kind: "hardLink";
-        readonly path: string | BytePath;
-        readonly target: string | BytePath;
-    })[];
-}, options?: {
-    readonly maxEntries?: number;
-    readonly maxBytes?: ByteSize.ByteSize;
-    readonly maxFileBytes?: ByteSize.ByteSize;
-    readonly maxPathBytes?: ByteSize.ByteSize;
-} | undefined) => Effect.Effect<Volume, ConfigurationError | ImageError, never>;
+export declare const fromFixture: (fixture: Fixture, options?: VolumeOptions) => Effect.Effect<Volume, ConfigurationError | ImageError>;
 //# sourceMappingURL=VirtualFileSystem.d.ts.map