@effect-vfs/core 0.5.0 → 0.6.0

package/dist/VirtualFileSystem.d.ts

@@ -12,24 +12,33 @@ import type * as ByteSize from "effect/ByteSize";
 import * as Context from "effect/Context";
 import type * as Crypto from "effect/Crypto";
 import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
 import type * as Order from "effect/Order";
 import type * as PlatformError from "effect/PlatformError";
 import * as Schema from "effect/Schema";
 import type * as Scope from "effect/Scope";
-import type * as Stream from "effect/Stream";
+import * as Sink from "effect/Sink";
+import * as Stream from "effect/Stream";
 import type { BytePath } from "./BytePath.js";
-import type { ConfigurationError, FsError } from "./VirtualFileSystemError.js";
+import type { CallerId, ObjectReferenceId } from "./Caller.js";
+import * as CallerModule from "./Caller.js";
+import type { DirectoryHandleId, FileHandleId } from "./FileHandle.js";
+import * as FileHandleModule from "./FileHandle.js";
+import * as FixtureModule from "./Fixture.js";
+import * as MetadataModule from "./Metadata.js";
+import type { Entry, EntryInput, Target, TargetInput } from "./Target.js";
+import type { ArgumentFailure, FsFailure, ImageFailure, VfsError } from "./VfsError.js";
+import * as VfsErrorModule from "./VfsError.js";
+import type { VolumeId } from "./Volume.js";
+import * as VolumeModule from "./Volume.js";
+import * as WatchModule from "./Watch.js";
+export { Entry, type EntryInput, isEntry, isTarget, Name, type NameInput, type PathTarget, Target, type TargetInput } from "./Target.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 type { DecodeLimits, Snapshot } from "./Snapshot.js";
+export { DecodeLimits, type Snapshot, SnapshotTypeId } from "./Snapshot.js";
+import { type LiveImageStore, type Options as LiveVolumeOptions } from "./LiveVolume.js";
 import * as SnapshotDeltaModel from "./SnapshotDelta.js";
-export { SnapshotChange, SnapshotChangesOptions, type SnapshotDelta, SnapshotDeltaError, SnapshotDeltaLimits, SnapshotDeltaTypeId, SnapshotDifference, SnapshotNodeKind } from "./SnapshotDelta.js";
-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;
+export { SnapshotChange, SnapshotChangesOptions, type SnapshotDelta, SnapshotDeltaLimits, SnapshotDeltaTypeId, SnapshotDifference, SnapshotNodeKind } from "./SnapshotDelta.js";
 /**
  * A UTF-8 string path or an opaque byte-preserving path.
  *
@@ -73,7 +82,7 @@ export type PathInput = string | BytePath;
  * @category schemas
  * @since 0.1.0
  */
-export declare const FsCode: typeof VfsModel.FsCode;
+export declare const FsCode: typeof VfsErrorModule.FsCode;
 /**
  * A portable virtual filesystem error code.
  *
@@ -91,7 +100,6 @@ export type FsCode = typeof FsCode.Type;
  * @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*() {
@@ -100,28 +108,26 @@ export type FsCode = typeof FsCode.Type;
  *   // 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) =>
+ *     Effect.catchTag("VfsError", (error) =>
  *       error.code === "NotFound"
  *         ? Effect.succeed(new Uint8Array())
  *         : Effect.fail(error))
  *   )
  * })
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * Effect.runPromise(program).then(console.log)
  * // Uint8Array(0) []
  * ```
  *
  * @category errors
  * @since 0.1.0
  */
-export { FsError } from "./VirtualFileSystemError.js";
 /**
  * Describes an invalid volume or caller option and names the rejected field.
  *
  * @example
  * ```ts
  * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
  * import { Effect } from "effect"
  *
  * // `field` names the rejected option, so the caller learns which key was wrong.
@@ -131,25 +137,25 @@ export { FsError } from "./VirtualFileSystemError.js";
  *
  *   return yield* Vfs.make(options).pipe(
  *     Effect.as("ok"),
- *     Effect.catchTag("ConfigurationError", (error) => Effect.succeed(`rejected ${error.field}`))
+ *     Effect.catchTag("VfsError", (error) => Effect.succeed(`rejected ${error.field}`))
  *   )
  * })
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * Effect.runPromise(program).then(console.log)
  * // rejected maxEntries
  * ```
  *
  * @category errors
  * @since 0.1.0
  */
-export { ConfigurationError } from "./VirtualFileSystemError.js";
+export { type ArgumentFailure, DeltaCode, type FsFailure, ImageCode, type ImageFailure, StoreCode, type StoreFailure, VfsCode, VfsError } from "./VfsError.js";
 /**
  * Schema for a caller's numeric identity, supplementary groups, and explicit privilege.
  *
  * @category schemas
  * @since 0.1.0
  */
-export declare const Identity: typeof VfsModel.Identity;
+export declare const Identity: typeof CallerModule.Identity;
 /**
  * A caller identity used for permission checks.
  *
@@ -163,7 +169,6 @@ export type Identity = typeof Identity.Type;
  * @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*() {
@@ -184,14 +189,14 @@ export type Identity = typeof Identity.Type;
  *   return ((yield* user.stat("/home/user")).mode & 0o777).toString(8)
  * })
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * Effect.runPromise(program).then(console.log)
  * // 755
  * ```
  *
  * @category schemas
  * @since 0.1.0
  */
-export declare const RootCallerOptions: typeof VfsModel.RootCallerOptions;
+export declare const RootCallerOptions: typeof CallerModule.RootCallerOptions;
 /**
  * Options for creating a root caller on a volume.
  *
@@ -205,7 +210,7 @@ export type RootCallerOptions = typeof RootCallerOptions.Type;
  * @category schemas
  * @since 0.1.0
  */
-export declare const VolumeDurability: typeof VfsModel.VolumeDurability;
+export declare const VolumeDurability: typeof VolumeModule.VolumeDurability;
 /**
  * The failure boundary survived by an acknowledged volume write.
  *
@@ -233,7 +238,7 @@ export declare const isVolumeDurabilityAtLeast: (actual: VolumeDurability, requi
  * @category schemas
  * @since 0.1.0
  */
-export declare const VolumeIdentity: typeof VfsModel.VolumeIdentity;
+export declare const VolumeIdentity: typeof VolumeModule.VolumeIdentity;
 /**
  * Stable logical identity of a volume as a branded 128-bit lowercase hexadecimal string.
  *
@@ -247,7 +252,7 @@ export type VolumeIdentity = typeof VolumeIdentity.Type;
  * @category schemas
  * @since 0.1.0
  */
-export declare const VolumeIncarnation: typeof VfsModel.VolumeIncarnation;
+export declare const VolumeIncarnation: typeof VolumeModule.VolumeIncarnation;
 /**
  * One uninterrupted storage lifetime as a branded 128-bit lowercase hexadecimal string.
  *
@@ -255,13 +260,52 @@ export declare const VolumeIncarnation: typeof VfsModel.VolumeIncarnation;
  * @since 0.1.0
  */
 export type VolumeIncarnation = typeof VolumeIncarnation.Type;
+/**
+ * Schema for the serialisable name of one object in one volume: the volume's
+ * identity, the epoch of its inode numbers, the object's inode number, and a
+ * tag only the volume can compute, so a key cannot be guessed from another.
+ *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import { Effect, Schema } from "effect"
+ *
+ * const Json = Schema.fromJsonString(Vfs.ReferenceKey)
+ *
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make()
+ *   const caller = yield* volume.caller()
+ *   yield* caller.writeFile("/f", new Uint8Array([1]), { access: "write", create: "exclusive" })
+ *
+ *   // The key survives a wire; resolving it returns the same reference.
+ *   const reference = yield* caller.lookup("/f")
+ *   const text = yield* Schema.encodeEffect(Json)(yield* volume.referenceKey(reference))
+ *   const key = yield* Schema.decodeEffect(Json)(text)
+ *
+ *   return (yield* volume.resolveReferenceKey(key)) === reference
+ * })
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // true
+ * ```
+ *
+ * @category schemas
+ * @since 0.6.0
+ */
+export declare const ReferenceKey: typeof VolumeModule.ReferenceKey;
+/**
+ * The serialisable name of one object in one volume.
+ *
+ * @category models
+ * @since 0.6.0
+ */
+export type ReferenceKey = typeof ReferenceKey.Type;
 /**
  * Schema for optional volume capacity and path limits.
  *
  * @example
  * ```ts
  * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
  * import { ByteSize, Effect } from "effect"
  *
  * // Every limit is optional, and each one is enforced once set.
@@ -274,18 +318,18 @@ export type VolumeIncarnation = typeof VolumeIncarnation.Type;
  *     create: "exclusive"
  *   }).pipe(
  *     Effect.as("written"),
- *     Effect.catchTag("FsError", (error) => Effect.succeed(error.code))
+ *     Effect.catchTag("VfsError", (error) => Effect.succeed(error.code))
  *   )
  * })
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * Effect.runPromise(program).then(console.log)
  * // FileTooLarge
  * ```
  *
  * @category schemas
  * @since 0.1.0
  */
-export declare const VolumeOptions: typeof VfsModel.VolumeOptions;
+export declare const VolumeOptions: typeof VolumeModule.VolumeOptions;
 /**
  * Capacity, admission, watch retention, and path limits for a volume.
  * `maxPendingOperations` defaults to 64 and `maxWatchEvents` defaults to 256.
@@ -328,7 +372,6 @@ export interface VolumeUsage {
  * @example
  * ```ts
  * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
  * import { Effect } from "effect"
  *
  * // Sizes and inode numbers are bigint; times are nanosecond timestamps.
@@ -345,14 +388,14 @@ export interface VolumeUsage {
  *   return [metadata.kind, metadata.size, metadata.nlink]
  * })
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * Effect.runPromise(program).then(console.log)
  * // [ 'file', 3n, 1 ]
  * ```
  *
  * @category schemas
  * @since 0.1.0
  */
-export declare const Metadata: typeof VfsModel.Metadata;
+export declare const Metadata: typeof MetadataModule.Metadata;
 /**
  * Metadata for a directory, regular file, or symbolic link.
  *
@@ -375,7 +418,6 @@ export interface ObjectReference {
  * @example
  * ```ts
  * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
  * import { Effect } from "effect"
  *
  * // References survive renames, and each observation carries the revision it
@@ -385,20 +427,20 @@ export interface ObjectReference {
  *
  *   yield* caller.mkdir("/work")
  *
- *   const root = yield* caller.rootReference
- *   const work = yield* caller.lookupReference(root, new TextEncoder().encode("work"))
+ *   const root = yield* caller.root
+ *   const work = yield* caller.lookup(Vfs.Entry(root, "work"))
  *
- *   const before = yield* caller.observeMetadata(work)
+ *   const before = yield* caller.stat(work)
  *
  *   yield* caller.rename("/work", "/moved")
  *
- *   const after = yield* caller.observeMetadata(work)
+ *   const after = yield* caller.stat(work)
  *
- *   return [before.value.kind, after.value.kind]
+ *   return [before.kind, after.kind, after.revision > before.revision]
  * })
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
- * // [ 'directory', 'directory' ]
+ * Effect.runPromise(program).then(console.log)
+ * // [ 'directory', 'directory', true ]
  * ```
  *
  * @category models
@@ -418,13 +460,60 @@ export interface DirectoryEntry {
     readonly name: Uint8Array;
     readonly reference: ObjectReference;
 }
+/**
+ * One entry a walk reached: its path below the walk's root, its name, the
+ * object it names and the directory it was listed in, its kind, and its depth.
+ *
+ * **Details**
+ *
+ * `path` is relative to the walk's root, with no leading slash (`a/b` for
+ * `b` in the root's child `a`), so it reads the same whichever way the root
+ * was addressed; the root itself is not an entry. `depth` is 1 for a child of
+ * the root. A symbolic link is reported as a link and never followed.
+ *
+ * @category models
+ * @since 0.6.0
+ */
+export interface WalkEntry {
+    readonly path: BytePath;
+    readonly name: Uint8Array;
+    readonly reference: ObjectReference;
+    readonly directory: ObjectReference;
+    readonly kind: Metadata["kind"];
+    readonly depth: number;
+}
+/**
+ * What a walk fails with: a failure of the directory it lists, or
+ * `LimitExceeded` when it would pass one of its bounds, which `field` names.
+ *
+ * @category models
+ * @since 0.6.0
+ */
+export type WalkFailure = FsFailure | (VfsError & {
+    readonly code: "LimitExceeded";
+});
+/**
+ * Settings for walking a directory tree: the order and the optional depth,
+ * entry, and byte bounds.
+ *
+ * @category schemas
+ * @since 0.6.0
+ */
+export declare const WalkOptions: typeof CallerModule.WalkOptions;
+/**
+ * Settings for walking a directory tree.
+ *
+ * @category models
+ * @since 0.6.0
+ */
+export type WalkOptions = typeof WalkOptions.Type;
 /**
  * A directory revision transition captured inside one coordinated operation.
  *
  * @category schemas
  * @since 0.4.0
  */
-export declare const DirectoryChange: typeof VfsModel.DirectoryChange;
+export declare const DirectoryChange: typeof CallerModule.DirectoryChange;
 /**
  * A directory revision transition captured inside one coordinated operation.
  *
@@ -448,7 +537,7 @@ export interface ReferenceEntryResult {
  * @category schemas
  * @since 0.4.0
  */
-export declare const RenameReferenceResult: typeof VfsModel.RenameReferenceResult;
+export declare const RenameReferenceResult: typeof CallerModule.RenameReferenceResult;
 /**
  * The directory transitions produced by a same-directory or cross-directory rename.
  *
@@ -456,64 +545,13 @@ export declare const RenameReferenceResult: typeof VfsModel.RenameReferenceResul
  * @since 0.4.0
  */
 export type RenameReferenceResult = typeof RenameReferenceResult.Type;
-/**
- * Resolves a relative path from a live directory handle instead of the caller's directory.
- *
- * @category models
- * @since 0.1.0
- */
-export interface RelativeOptions {
-    /** Resolve relative paths from this live, same-volume handle instead of the caller's current directory. */
-    readonly relativeTo?: DirectoryHandle;
-}
-/**
- * Controls the base directory and whether metadata operations follow the final symbolic link.
- *
- * @example
- * ```ts
- * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
- * import { Effect } from "effect"
- *
- * const program = Effect.gen(function*() {
- *   const caller = yield* (yield* Vfs.make()).caller()
- *
- *   yield* caller.writeFile("/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.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
- * // [ '600', '600' ]
- * ```
- *
- * @category models
- * @since 0.1.0
- */
-export interface MetadataOptions extends RelativeOptions {
-    /** Follow the final symbolic link. Defaults to `true`. */
-    readonly followFinalSymlink?: boolean;
-}
 /**
  * Schema for an owner update. Omitted fields retain their existing values.
  *
  * @category schemas
  * @since 0.1.0
  */
-export declare const OwnerUpdate: typeof VfsModel.OwnerUpdate;
+export declare const OwnerUpdate: typeof MetadataModule.OwnerUpdate;
 /**
  * An owner update for `chown` operations.
  *
@@ -527,14 +565,13 @@ export type OwnerUpdate = typeof OwnerUpdate.Type;
  * @category schemas
  * @since 0.1.0
  */
-export declare const TimeUpdate: typeof VfsModel.TimeUpdate;
+export declare const TimeUpdate: typeof MetadataModule.TimeUpdate;
 /**
  * Schema for independent access and modification time updates.
  *
  * @example
  * ```ts
  * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
  * import { Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -556,14 +593,14 @@ export declare const TimeUpdate: typeof VfsModel.TimeUpdate;
  *   return [metadata.atimeNs, metadata.mtimeNs === 1_000n]
  * })
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * Effect.runPromise(program).then(console.log)
  * // [ 1000n, false ]
  * ```
  *
  * @category schemas
  * @since 0.1.0
  */
-export declare const Times: typeof VfsModel.Times;
+export declare const Times: typeof MetadataModule.Times;
 /**
  * Access and modification time updates for `utimes` operations.
  *
@@ -577,7 +614,6 @@ export type Times = typeof Times.Type;
  * @example
  * ```ts
  * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
  * import { Effect } from "effect"
  *
  * // The handle anchors relative paths to the directory itself, so a rename in
@@ -590,16 +626,15 @@ export type Times = typeof Times.Type;
  *   const directory = yield* caller.openDirectory("/project")
  *
  *   yield* caller.rename("/project", "/renamed")
- *   yield* caller.writeFile("notes.txt", new TextEncoder().encode("kept"), {
+ *   yield* caller.writeFile(Vfs.Target.Path({ path: "notes.txt", relativeTo: directory }), new TextEncoder().encode("kept"), {
  *     access: "write",
- *     create: "exclusive",
- *     relativeTo: directory
+ *     create: "exclusive"
  *   })
  *
- *   return yield* caller.readDirectory("/renamed")
+ *   return (yield* caller.readDirectory("/renamed")).value.map((entry) => new TextDecoder().decode(entry.name))
  * }).pipe(Effect.scoped)
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * Effect.runPromise(program).then(console.log)
  * // [ 'notes.txt' ]
  * ```
  *
@@ -608,8 +643,8 @@ export type Times = typeof Times.Type;
  */
 export interface DirectoryHandle {
     readonly [DirectoryHandleId]: true;
-    readonly stat: Effect.Effect<Metadata, FsError>;
-    readonly close: Effect.Effect<void, FsError>;
+    readonly stat: Effect.Effect<Metadata, FsFailure>;
+    readonly close: Effect.Effect<void, FsFailure>;
 }
 /**
  * Schema for file seek origins, including dense-file data and hole queries.
@@ -617,7 +652,7 @@ export interface DirectoryHandle {
  * @category schemas
  * @since 0.1.0
  */
-export declare const SeekMode: typeof VfsModel.SeekMode;
+export declare const SeekMode: typeof FileHandleModule.SeekMode;
 /**
  * The origin used by a file handle seek operation.
  *
@@ -631,7 +666,6 @@ export type SeekMode = typeof SeekMode.Type;
  * @example
  * ```ts
  * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
  * import { Effect } from "effect"
  *
  * // `access` is required; `create` decides whether a missing file is an error.
@@ -649,65 +683,86 @@ export type SeekMode = typeof SeekMode.Type;
  *   return (yield* handle.stat).size
  * }).pipe(Effect.scoped)
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * Effect.runPromise(program).then(console.log)
  * // 2n
  * ```
  *
  * @category schemas
  * @since 0.1.0
  */
-export declare const OpenSettings: typeof VfsModel.OpenSettings;
+export declare const OpenOptions: typeof CallerModule.OpenOptions;
 /**
- * Options for acquiring a scoped file handle.
+ * Options of `open` on a target.
  *
  * @category models
  * @since 0.1.0
  */
-export type OpenOptions = typeof OpenSettings.Type & RelativeOptions;
+export type OpenOptions = typeof OpenOptions.Type;
 /**
  * Settings for creating a directory through a parent object reference.
  * `exactMode` skips the caller's umask for an explicit creation mode; permission policy still applies.
+ * `recursive` creates every missing directory on a path in one change, as `mkdir -p` does.
  *
  * @category schemas
  * @since 0.4.0
  */
-export declare const MkdirReferenceSettings: typeof VfsModel.MkdirReferenceSettings;
+export declare const MkdirOptions: typeof CallerModule.MkdirOptions;
 /**
  * Settings for creating a directory through a parent object reference.
  * `exactMode` skips the caller's umask for an explicit creation mode; permission policy still applies.
+ * `recursive` creates every missing directory on a path in one change, as `mkdir -p` does.
  *
  * @category models
  * @since 0.4.0
  */
-export type MkdirReferenceSettings = typeof MkdirReferenceSettings.Type;
+export type MkdirOptions = typeof MkdirOptions.Type;
+/**
+ * Settings for removing an entry: whether a directory goes with everything
+ * under it, and whether a missing target is success.
+ *
+ * @category schemas
+ * @since 0.6.0
+ */
+export declare const RemoveOptions: typeof CallerModule.RemoveOptions;
+/**
+ * Settings for removing an entry.
+ *
+ * @category models
+ * @since 0.6.0
+ */
+export type RemoveOptions = typeof RemoveOptions.Type;
 /**
  * Settings for creating a symbolic link through a parent object reference.
  *
  * @category schemas
  * @since 0.4.0
  */
-export declare const SymlinkReferenceSettings: typeof VfsModel.SymlinkReferenceSettings;
+export declare const SymlinkOptions: typeof CallerModule.SymlinkOptions;
 /**
  * Settings for creating a symbolic link through a parent object reference.
  *
  * @category models
  * @since 0.4.0
  */
-export type SymlinkReferenceSettings = typeof SymlinkReferenceSettings.Type;
+export type SymlinkOptions = typeof SymlinkOptions.Type;
 /**
- * Settings for opening an existing regular-file reference.
+ * The attributes `setattr` changes together: a regular file's size, the
+ * permission mode, the owner, and the access and modification times. An
+ * omitted attribute keeps its current value. `expected` pins the revision the
+ * caller last observed and fails as `StaleReference` naming `expected` when
+ * the target has moved on.
  *
  * @category schemas
- * @since 0.4.0
+ * @since 0.6.0
  */
-export declare const OpenReferenceSettings: typeof VfsModel.OpenReferenceSettings;
+export declare const SetattrOptions: typeof CallerModule.SetattrOptions;
 /**
- * Settings for opening an existing regular-file reference.
+ * The attributes `setattr` changes together.
  *
  * @category models
- * @since 0.4.0
+ * @since 0.6.0
  */
-export type OpenReferenceSettings = typeof OpenReferenceSettings.Type;
+export type SetattrOptions = typeof SetattrOptions.Type;
 /**
  * Settings for atomically looking up or creating and opening one referenced child.
  * `exactMode` skips the caller's umask for an explicit creation mode; permission policy still applies.
@@ -715,7 +770,7 @@ export type OpenReferenceSettings = typeof OpenReferenceSettings.Type;
  * @category schemas
  * @since 0.4.0
  */
-export declare const OpenChildReferenceSettings: typeof VfsModel.OpenChildReferenceSettings;
+export declare const OpenEntryOptions: typeof CallerModule.OpenEntryOptions;
 /**
  * Settings for atomically looking up or creating and opening one referenced child.
  * `exactMode` skips the caller's umask for an explicit creation mode; permission policy still applies.
@@ -728,14 +783,14 @@ export declare const OpenChildReferenceSettings: typeof VfsModel.OpenChildRefere
  * @category models
  * @since 0.4.0
  */
-export type OpenChildReferenceSettings = typeof OpenChildReferenceSettings.Type;
+export type OpenEntryOptions = typeof OpenEntryOptions.Type;
 /**
  * A scoped child-open result captured inside one coordinated operation.
  *
  * @category models
  * @since 0.4.0
  */
-export interface OpenChildReferenceResult {
+export interface OpenEntryResult {
     readonly handle: FileHandle;
     readonly reference: ObjectReference;
     readonly created: boolean;
@@ -747,7 +802,6 @@ export interface OpenChildReferenceResult {
  * @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*() {
@@ -767,7 +821,7 @@ export interface OpenChildReferenceResult {
  *     create: "exclusive"
  *   }).pipe(
  *     Effect.as("replaced"),
- *     Effect.catchTag("FsError", (error) => Effect.succeed(error.code))
+ *     Effect.catchTag("VfsError", (error) => Effect.succeed(error.code))
  *   )
  *
  *   yield* caller.writeFile("/app.conf", bytes, { access: "write", truncate: true })
@@ -775,21 +829,37 @@ export interface OpenChildReferenceResult {
  *   return [refused, new TextDecoder().decode(yield* caller.readFile("/app.conf"))]
  * })
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * Effect.runPromise(program).then(console.log)
  * // [ 'AlreadyExists', 'v2' ]
  * ```
  *
  * @category models
  * @since 0.1.0
  */
-export type WriteFileOptions = VfsModel.WriteFileOptions;
+export declare const WriteFileOptions: typeof CallerModule.WriteFileOptions;
+/**
+ * Options of `writeFile`.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type WriteFileOptions = typeof WriteFileOptions.Type;
+/**
+ * The bytes a positional read returned and whether they reach the end of the file.
+ *
+ * @category models
+ * @since 0.6.0
+ */
+export interface ReadResult {
+    readonly bytes: Uint8Array;
+    readonly eof: boolean;
+}
 /**
  * A scoped regular-file capability with an independent bigint cursor.
  *
  * @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*() {
@@ -805,11 +875,11 @@ export type WriteFileOptions = VfsModel.WriteFileOptions;
  *   // `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")]
+ *   return [slice.bytes, slice.eof, yield* handle.seek(0n, "current")]
  * }).pipe(Effect.scoped)
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
- * // [ Uint8Array(2) [ 2, 3 ], 4n ]
+ * Effect.runPromise(program).then(console.log)
+ * // [ Uint8Array(2) [ 2, 3 ], false, 4n ]
  * ```
  *
  * @category models
@@ -818,23 +888,23 @@ export type WriteFileOptions = VfsModel.WriteFileOptions;
 export interface FileHandle {
     readonly [FileHandleId]: true;
     /** Reads up to `maximumBytes` from the cursor and advances it by the returned length. */
-    readonly read: (maximumBytes: number) => Effect.Effect<Uint8Array, FsError>;
+    readonly read: (maximumBytes: number) => Effect.Effect<Uint8Array, FsFailure>;
     /** Reads at `offset` without changing the cursor. */
-    readonly pread: (maximumBytes: number, offset: bigint) => Effect.Effect<Uint8Array, FsError>;
+    readonly pread: (maximumBytes: number, offset: bigint) => Effect.Effect<ReadResult, FsFailure>;
     /** Writes at the cursor and advances it, or writes at end of file when opened for append. */
-    readonly write: (bytes: Uint8Array) => Effect.Effect<number, FsError>;
+    readonly write: (bytes: Uint8Array) => Effect.Effect<number, FsFailure>;
     /** Writes at `offset` without changing the cursor. Append mode does not affect positional writes. */
-    readonly pwrite: (bytes: Uint8Array, offset: bigint) => Effect.Effect<number, FsError>;
+    readonly pwrite: (bytes: Uint8Array, offset: bigint) => Effect.Effect<number, FsFailure>;
     /** Moves the cursor and returns its new offset. `data` finds content and `hole` finds end of file. */
-    readonly seek: (offset: bigint, mode: SeekMode) => Effect.Effect<bigint, FsError>;
+    readonly seek: (offset: bigint, mode: SeekMode) => Effect.Effect<bigint, FsFailure>;
     /** Sets the file length without changing the cursor. */
-    readonly truncate: (length: bigint) => Effect.Effect<void, FsError>;
+    readonly truncate: (length: bigint) => Effect.Effect<void, FsFailure>;
     /** Reads metadata for the open file. */
-    readonly stat: Effect.Effect<Metadata, FsError>;
+    readonly stat: Effect.Effect<Metadata, FsFailure>;
     /** Checks handle and provider health. Durable mutations have already committed; memory volumes have nothing to flush. */
-    readonly sync: Effect.Effect<void, FsError>;
+    readonly sync: Effect.Effect<void, FsFailure>;
     /** Closes the handle. A repeated explicit close fails; scope cleanup remains safe. */
-    readonly close: Effect.Effect<void, FsError>;
+    readonly close: Effect.Effect<void, FsFailure>;
 }
 /**
  * A filesystem caller with its own identity, creation mask, and current directory.
@@ -842,7 +912,6 @@ export interface FileHandle {
  * @example
  * ```ts
  * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
  * import { Effect } from "effect"
  *
  * // Whole-file reads and writes need no scope. `writeFile` always takes an
@@ -857,17 +926,16 @@ export interface FileHandle {
  *     create: "exclusive"
  *   })
  *
- *   return yield* caller.readDirectory("/work")
+ *   return (yield* caller.readDirectory("/work")).value.map((entry) => new TextDecoder().decode(entry.name))
  * })
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * Effect.runPromise(program).then(console.log)
  * // [ 'notes.txt' ]
  * ```
  *
  * @example
  * ```ts
  * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
  * import { Effect } from "effect"
  *
  * // Reach for a handle when a whole-file write will not do. A handle carries a
@@ -887,14 +955,13 @@ export interface FileHandle {
  *   return new TextDecoder().decode(yield* handle.read(64))
  * }).pipe(Effect.scoped)
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * Effect.runPromise(program).then(console.log)
  * // first second
  * ```
  *
  * @example
  * ```ts
  * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
  * import { Effect } from "effect"
  *
  * // A derived caller holds the directory's identity, not its path, so renaming
@@ -912,10 +979,10 @@ export interface FileHandle {
  *     create: "exclusive"
  *   })
  *
- *   return yield* caller.readDirectory("/dist")
+ *   return (yield* caller.readDirectory("/dist")).value.map((entry) => new TextDecoder().decode(entry.name))
  * }).pipe(Effect.scoped)
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * Effect.runPromise(program).then(console.log)
  * // [ 'out.txt' ]
  * ```
  *
@@ -925,109 +992,99 @@ export interface FileHandle {
  */
 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>;
-    /** Checks permission bits on the exact referenced object without resolving a path. */
-    readonly accessReference: (reference: ObjectReference, bits?: number) => Effect.Effect<void, 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>;
-    /** Creates one directory from a referenced parent and returns its exact identity and directory transition. */
-    readonly mkdirReference: (directory: ObjectReference, name: Uint8Array, settings?: MkdirReferenceSettings) => Effect.Effect<ReferenceEntryResult, FsError>;
-    /** Creates one symbolic link from a referenced parent and returns its exact identity and directory transition. */
-    readonly symlinkReference: (target: PathInput, directory: ObjectReference, name: Uint8Array, settings?: SymlinkReferenceSettings) => Effect.Effect<ReferenceEntryResult, FsError>;
-    /** Creates another name for the exact source object; symbolic links are not followed. */
-    readonly linkReference: (source: ObjectReference, destinationDirectory: ObjectReference, destinationName: Uint8Array) => Effect.Effect<ReferenceEntryResult, FsError>;
-    /** Removes a non-directory child and returns the parent directory transition. */
-    readonly unlinkReference: (directory: ObjectReference, name: Uint8Array) => Effect.Effect<DirectoryChange, FsError>;
-    /** Removes an empty directory child and returns the parent directory transition. */
-    readonly rmdirReference: (directory: ObjectReference, name: Uint8Array) => Effect.Effect<DirectoryChange, FsError>;
-    /** Removes a child of either type in one coordinated mutation and returns the parent directory transition. */
-    readonly removeReference: (directory: ObjectReference, name: Uint8Array) => Effect.Effect<DirectoryChange, FsError>;
-    /** Renames one referenced child and returns one transition per distinct parent directory. */
-    readonly renameReference: (sourceDirectory: ObjectReference, sourceName: Uint8Array, destinationDirectory: ObjectReference, destinationName: Uint8Array) => Effect.Effect<RenameReferenceResult, FsError>;
-    /** Changes permission bits on the exact referenced object. */
-    readonly chmodReference: (reference: ObjectReference, mode: number) => Effect.Effect<void, FsError>;
-    /** Changes ownership on the exact referenced object. */
-    readonly chownReference: (reference: ObjectReference, owner: OwnerUpdate) => Effect.Effect<void, FsError>;
-    /** Changes timestamps on the exact referenced object. */
-    readonly utimesReference: (reference: ObjectReference, times: Times) => Effect.Effect<void, FsError>;
-    /** Changes the length of the exact referenced regular file. */
-    readonly truncateReference: (reference: ObjectReference, length: bigint) => Effect.Effect<void, FsError>;
-    /** Opens an existing referenced regular file. Omitted settings preserve read-only behavior. */
-    readonly openReference: (reference: ObjectReference, settings?: OpenReferenceSettings) => Effect.Effect<FileHandle, FsError, Scope.Scope>;
-    /** Atomically looks up or creates and opens one child; `expected` guards its current identity, with `null` meaning absent. */
-    readonly openChildReference: (directory: ObjectReference, name: Uint8Array, settings: OpenChildReferenceSettings, expected?: ObjectReference | null) => Effect.Effect<OpenChildReferenceResult, 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?: {
-        readonly sourceRelativeTo?: DirectoryHandle;
-        readonly destinationRelativeTo?: DirectoryHandle;
-    }) => Effect.Effect<void, FsError>;
-    /** Reads and returns an owned copy of a regular file's complete contents. */
-    readonly readFile: (path: PathInput, options?: RelativeOptions) => Effect.Effect<Uint8Array, FsError>;
-    /** Atomically writes a complete regular file according to the replacement options. */
-    readonly writeFile: (path: PathInput, bytes: Uint8Array, options: WriteFileOptions) => Effect.Effect<void, FsError>;
-    /** Checks the requested permission bits without opening the entry. */
-    readonly access: (path: PathInput, bits?: number, options?: RelativeOptions) => Effect.Effect<void, FsError>;
-    /** Sets a regular file's length. Extending creates a zero-filled region. */
-    readonly truncate: (path: PathInput, length: bigint, options?: RelativeOptions) => Effect.Effect<void, FsError>;
-    /** Changes permission bits, following the final symbolic link by default. */
-    readonly chmod: (path: PathInput, mode: number, options?: MetadataOptions) => Effect.Effect<void, FsError>;
-    /** Changes uid, gid, or both, following the final symbolic link by default. */
-    readonly chown: (path: PathInput, owner: OwnerUpdate, options?: MetadataOptions) => Effect.Effect<void, FsError>;
-    /** Updates access and modification times, following the final symbolic link by default. */
-    readonly utimes: (path: PathInput, times: Times, options?: MetadataOptions) => Effect.Effect<void, FsError>;
-    /** Changes permission bits through a live, same-volume handle. */
-    readonly chmodHandle: (handle: FileHandle | DirectoryHandle, mode: number) => Effect.Effect<void, FsError>;
-    /** Changes uid, gid, or both through a live, same-volume handle. */
-    readonly chownHandle: (handle: FileHandle | DirectoryHandle, owner: OwnerUpdate) => Effect.Effect<void, FsError>;
-    /** Updates access and modification times through a live, same-volume handle. */
-    readonly utimesHandle: (handle: FileHandle | DirectoryHandle, times: Times) => Effect.Effect<void, FsError>;
-    /** Reads metadata without following the final symbolic link. */
-    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?: {
-        readonly sourceRelativeTo?: DirectoryHandle;
-        readonly destinationRelativeTo?: DirectoryHandle;
-        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 `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 `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, 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>;
-    /** Opens a scoped regular-file handle. The surrounding scope closes it automatically. */
-    readonly open: (path: PathInput, options: OpenOptions) => Effect.Effect<FileHandle, FsError, Scope.Scope>;
-    /** Removes a non-directory entry. Open handles remain usable until closed. */
-    readonly unlink: (path: PathInput, options?: RelativeOptions) => Effect.Effect<void, FsError>;
+    /** The reference of the volume's root directory. */
+    readonly root: Effect.Effect<ObjectReference, FsFailure>;
+    /** The reference of a child of a directory, without following it. */
+    readonly lookup: (entry: EntryInput) => Effect.Effect<ObjectReference, FsFailure>;
+    /** The reference of a directory's parent; the root is its own parent. */
+    readonly parent: (directory: TargetInput) => Effect.Effect<ObjectReference, FsFailure>;
+    /** Metadata and revision of a target. A path follows a final symbolic link unless its target says otherwise. */
+    readonly stat: (target: TargetInput) => Effect.Effect<Metadata, FsFailure>;
+    /** The entries of a directory with their references, and the directory's revision. */
+    readonly readDirectory: (directory: TargetInput) => Effect.Effect<ObjectObservation<ReadonlyArray<DirectoryEntry>>, FsFailure>;
+    /**
+     * Every entry below a directory, as a stream that reads one directory at a time and holds no handle. Entries
+     * arrive depth first, each directory's entries in the byte order of their names; symbolic links are reported,
+     * never followed. Each directory is read in one observation, so the walk sees each listing whole but no
+     * snapshot of the tree, and it refreshes no access time. Each directory below the root is reached by name, as a
+     * path lookup reaches it, so it needs search permission on every directory above it, and one that goes away or
+     * is renamed out of the tree before the walk reads it is skipped. A failure below the root names the entry's
+     * path under the path the root was given by, or under the root when it was given by reference or handle.
+     */
+    readonly walk: (directory: TargetInput, options?: WalkOptions) => Stream.Stream<WalkEntry, WalkFailure>;
+    /** The bytes a symbolic link points at. A path never follows the final link. */
+    readonly readLink: (target: TargetInput) => Effect.Effect<Uint8Array, FsFailure>;
+    /** The canonical absolute path of a target. */
+    readonly realPath: (target: TargetInput) => Effect.Effect<BytePath, FsFailure>;
+    /** The bits of `bits` the caller may exercise on the target: READ, WRITE, EXECUTE as 4, 2, 1. */
+    readonly access: (target: TargetInput, bits?: number) => Effect.Effect<number, FsFailure>;
+    /** The whole content of a regular file. */
+    readonly readFile: (target: TargetInput) => Effect.Effect<Uint8Array, FsFailure>;
+    /** Writes a whole file in one operation, creating or replacing it as the options say. */
+    readonly writeFile: (entry: EntryInput, bytes: Uint8Array, options: WriteFileOptions) => Effect.Effect<void, FsFailure>;
+    /**
+     * Opens a file. On a target, the file must exist and `create` is rejected. On an entry, the name is looked up
+     * and created in one gate hold, and the result reports whether it was created.
+     */
+    readonly open: {
+        (target: Target | PathInput | ObjectReference | FileHandle, options: OpenOptions): Effect.Effect<FileHandle, FsFailure, Scope.Scope>;
+        (entry: Entry, options: OpenEntryOptions): Effect.Effect<OpenEntryResult, FsFailure, Scope.Scope>;
+    };
+    /**
+     * Creates a directory. With `recursive`, every missing directory on a path is created in one change, so a
+     * failure creates none and a watcher sees them all at once; symbolic links on the way are followed, dot names
+     * are walked, and a final name that is already a directory (or a link to one) succeeds without a change. The
+     * result names the directory the path ends on, with its parent's revision before and after the call, so a path
+     * that leaves a directory it created, such as `new/..`, still reports the change. A name on the way that is not
+     * a directory fails with `NotDirectory`, a final one with `AlreadyExists`, and only names the caller wrote are
+     * created, so a dangling link fails with `NotFound`.
+     */
+    readonly mkdir: (entry: EntryInput, options?: MkdirOptions) => Effect.Effect<ReferenceEntryResult, FsFailure>;
+    /** Creates a symbolic link to `target`, stored as given. */
+    readonly symlink: (target: PathInput, entry: EntryInput, options?: SymlinkOptions) => Effect.Effect<ReferenceEntryResult, FsFailure>;
+    /** Adds a name for an existing file or symbolic link. A path source follows a final symbolic link only when its target says so. */
+    readonly link: (source: TargetInput, entry: EntryInput) => Effect.Effect<ReferenceEntryResult, FsFailure>;
+    /** Removes a file or symbolic link. */
+    readonly unlink: (entry: EntryInput) => Effect.Effect<DirectoryChange, FsFailure>;
     /** Removes an empty directory. */
-    readonly rmdir: (path: PathInput, options?: RelativeOptions) => Effect.Effect<void, FsError>;
-    /** Creates one directory. Parent directories must already exist. */
-    readonly mkdir: (path: PathInput, options?: RelativeOptions & {
-        readonly mode?: number;
-    }) => Effect.Effect<void, FsError>;
-    /** Creates a scoped caller whose current directory is the resolved directory identity. */
-    readonly withDirectory: (path: PathInput, options?: RelativeOptions) => Effect.Effect<Caller, FsError, Scope.Scope>;
-    /** Opens a scoped directory handle for metadata and relative path resolution. */
-    readonly openDirectory: (path: PathInput, options?: RelativeOptions) => Effect.Effect<DirectoryHandle, FsError, Scope.Scope>;
+    readonly rmdir: (entry: EntryInput) => Effect.Effect<DirectoryChange, FsFailure>;
+    /**
+     * Removes a file, a symbolic link, or an empty directory. With `recursive`, a directory that has entries is
+     * emptied first, entries before their directories, each removal its own change; it stops at the first failure,
+     * whose path names the entry it stopped at, and leaves what it has not reached. Each entry is removed by its name
+     * in a directory reached by name, so a subtree renamed out of the target is left alone. A directory with entries
+     * must be readable, and no permission is changed to make it so. With `force`, a missing target is success and the
+     * result is `undefined`; a failure below the target is still a failure.
+     */
+    readonly remove: {
+        (entry: EntryInput, options?: RemoveOptions & {
+            readonly force?: false;
+        }): Effect.Effect<DirectoryChange, FsFailure>;
+        (entry: EntryInput, options: RemoveOptions): Effect.Effect<DirectoryChange | undefined, FsFailure>;
+    };
+    /** Moves an entry, replacing a compatible destination. */
+    readonly rename: (from: EntryInput, to: EntryInput) => Effect.Effect<RenameReferenceResult, FsFailure>;
+    /** Sets the permission bits of a target. */
+    readonly chmod: (target: TargetInput, mode: number) => Effect.Effect<void, FsFailure>;
+    /** Changes the owner or group of a target. */
+    readonly chown: (target: TargetInput, owner: OwnerUpdate) => Effect.Effect<void, FsFailure>;
+    /** Sets the access and modification times of a target. */
+    readonly utimes: (target: TargetInput, times: Times) => Effect.Effect<void, FsFailure>;
+    /** Sets the size of a regular file. */
+    readonly truncate: (target: TargetInput, length: bigint) => Effect.Effect<void, FsFailure>;
+    /**
+     * Changes a target's size, owner, mode and times as one change. Every check passes before any attribute
+     * applies, so a failure changes nothing. The attributes apply as size, owner, mode, then times, the POSIX
+     * composition of chown then chmod, so a requested mode wins over the set-ID clearing an owner change or a
+     * resize triggers. A protocol adapter that sanitises the requested mode, as NFS does after Linux knfsd,
+     * does so before it calls setattr, and passes the revision it read as `expected` so the change refuses a
+     * target another change has moved.
+     */
+    readonly setattr: (target: TargetInput, attributes: SetattrOptions) => Effect.Effect<void, FsFailure>;
+    /** A caller whose working directory is the target, released with the scope. */
+    readonly withDirectory: (directory: TargetInput) => Effect.Effect<Caller, FsFailure, Scope.Scope>;
+    /** A handle on a directory, released with the scope. */
+    readonly openDirectory: (directory: TargetInput) => Effect.Effect<DirectoryHandle, FsFailure, Scope.Scope>;
 }
 /**
  * A committed namespace or content change emitted by a volume watch stream.
@@ -1035,14 +1092,13 @@ export interface Caller {
  * @example
  * ```ts
  * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
  * 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(
+ *   const watcher = yield* volume.watch().pipe(
  *     Effect.flatMap((stream) => Stream.runCollect(Stream.take(stream, 2))),
  *     Effect.forkChild({ startImmediately: true })
  *   )
@@ -1060,26 +1116,80 @@ export interface Caller {
  *     ))
  * }).pipe(Effect.scoped)
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * Effect.runPromise(program).then(console.log)
  * // [ 'Create /logs', 'Remove /logs' ]
  * ```
  *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const Change: typeof WatchModule.Change;
+/**
+ * One committed change observed through a watch subscription. `Rescan` means
+ * the subscriber lost events; it names `/` for a volume-wide watch and the
+ * scope's current path for a scoped one.
+ *
  * @category models
  * @since 0.1.0
  */
-export interface Change {
-    /** Kind of committed change. `Rescan` means this subscriber lost events. */
-    readonly _tag: "Create" | "Update" | "Remove" | "Rescan";
-    /** Absolute path of the changed entry, or `/` when retained events were lost. */
-    readonly path: BytePath;
-}
+export type Change = typeof Change.Type;
+/**
+ * Schema for the options of `Volume.watch`: an object reference to narrow the
+ * watch to, and whether its whole subtree is reported.
+ *
+ * @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()
+ *   yield* caller.mkdir("/work")
+ *   const work = yield* caller.lookup("/work")
+ *
+ *   const watcher = yield* volume.watch({ scope: work }).pipe(
+ *     Effect.flatMap((stream) => Stream.runCollect(Stream.take(stream, 3))),
+ *     Effect.forkChild({ startImmediately: true })
+ *   )
+ *
+ *   // Outside the scope, so not reported.
+ *   yield* caller.mkdir("/elsewhere")
+ *   // The scope is the directory, not its path: the rename is reported and the watch goes on.
+ *   yield* caller.rename("/work", "/renamed")
+ *   yield* caller.mkdir("/renamed/out")
+ *
+ *   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)
+ * // [ 'Remove /work', 'Create /renamed', 'Create /renamed/out' ]
+ * ```
+ *
+ * @category schemas
+ * @since 0.6.0
+ */
+export declare const WatchOptions: typeof WatchModule.WatchOptions;
+/**
+ * Options of `Volume.watch`.
+ *
+ * @category models
+ * @since 0.6.0
+ */
+export type WatchOptions = typeof WatchOptions.Type;
 /**
  * Schema for the filesystem entry kinds reported by overlay summaries.
  *
  * @category schemas
  * @since 0.1.0
  */
-export declare const OverlayNodeKind: typeof VfsModel.OverlayNodeKind;
+export declare const OverlayNodeKind: typeof VolumeModule.OverlayNodeKind;
 /**
  * A filesystem entry kind reported by an overlay summary.
  *
@@ -1093,7 +1203,7 @@ export type OverlayNodeKind = typeof OverlayNodeKind.Type;
  * @category schemas
  * @since 0.1.0
  */
-export declare const OverlayDifference: typeof VfsModel.OverlayDifference;
+export declare const OverlayDifference: typeof VolumeModule.OverlayDifference;
 /**
  * A content, ownership, permission, or timestamp field that differs from the overlay base.
  *
@@ -1112,7 +1222,7 @@ export type OverlayDifference = typeof OverlayDifference.Type;
  * @category schemas
  * @since 0.1.0
  */
-export declare const OverlayChange: typeof VfsModel.OverlayChange;
+export declare const OverlayChange: typeof VolumeModule.OverlayChange;
 /**
  * A path-oriented final-state difference from an overlay's immutable base.
  *
@@ -1126,7 +1236,6 @@ export type OverlayChange = typeof OverlayChange.Type;
  * @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*() {
@@ -1142,14 +1251,14 @@ export type OverlayChange = typeof OverlayChange.Type;
  *   return [plain.length, timed.length]
  * })
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * Effect.runPromise(program).then(console.log)
  * // [ 1, 2 ]
  * ```
  *
  * @category schemas
  * @since 0.1.0
  */
-export declare const OverlayChangesOptions: typeof VfsModel.OverlayChangesOptions;
+export declare const OverlayChangesOptions: typeof VolumeModule.OverlayChangesOptions;
 /**
  * Filtering options for an overlay final-difference summary.
  *
@@ -1163,7 +1272,6 @@ export type OverlayChangesOptions = typeof OverlayChangesOptions.Type;
  * @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*() {
@@ -1187,7 +1295,7 @@ export type OverlayChangesOptions = typeof OverlayChangesOptions.Type;
  *   ]
  * })
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * Effect.runPromise(program).then(console.log)
  * // [ [ 'Added' ], 'built' ]
  * ```
  *
@@ -1206,7 +1314,6 @@ export interface OverlayCapture {
  * @example
  * ```ts
  * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
  * import { Effect, Fiber, Option, Stream } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -1214,7 +1321,7 @@ export interface OverlayCapture {
  *   const caller = yield* volume.caller()
  *
  *   // `watch` reports future changes only; nothing is replayed.
- *   const watcher = yield* volume.watch.pipe(
+ *   const watcher = yield* volume.watch().pipe(
  *     Effect.flatMap(Stream.runHead),
  *     Effect.forkChild({ startImmediately: true })
  *   )
@@ -1226,7 +1333,7 @@ export interface OverlayCapture {
  *   return Option.getOrElse(Option.map(change, (event) => event._tag), () => "none")
  * }).pipe(Effect.scoped)
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * Effect.runPromise(program).then(console.log)
  * // Create
  * ```
  *
@@ -1243,14 +1350,31 @@ export interface Volume {
     /** Effective static limits, where `undefined` means unlimited. */
     readonly limits: VolumeLimits;
     /** Samples content bytes and directory entries together from the current committed state. */
-    readonly usage: Effect.Effect<VolumeUsage, FsError>;
-    /** Opens a scoped stream of future changes. `Rescan` at `/` requires a full rescan; events are not replayed. */
-    readonly watch: Effect.Effect<Stream.Stream<Change>, FsError, Scope.Scope>;
+    readonly usage: Effect.Effect<VolumeUsage, FsFailure>;
+    /**
+     * Opens a scoped stream of future changes, registered before it returns; events are not replayed. Without a
+     * scope it covers the volume and `Rescan` at `/` requires a full rescan; with one it covers that object (and its
+     * subtree unless `recursive` is `false`), `Rescan` names the object's current path, and the stream ends after
+     * `Remove` for the object once its last name is gone.
+     */
+    readonly watch: (options?: WatchOptions) => Effect.Effect<Stream.Stream<Change>, FsFailure, Scope.Scope>;
     /** Captures an isolated snapshot of the reachable namespace and metadata. */
-    readonly snapshot: Effect.Effect<Snapshot, ImageError | FsError>;
+    readonly snapshot: Effect.Effect<Snapshot, VfsError>;
+    /**
+     * The serialisable key of an object this volume issued. Fails with `InvalidReference` for a value that is not a
+     * reference, `ForeignReference` for another volume's, and `StaleReference` once the object is gone.
+     */
+    readonly referenceKey: (reference: ObjectReference) => Effect.Effect<ReferenceKey, FsFailure>;
+    /**
+     * The object a key names, as the same reference traversal returns. Fails with `InvalidReference` for a malformed
+     * key or one whose tag this volume did not compute, `ForeignReference` for a key another volume or another epoch
+     * of this one minted, and `StaleReference` once the object is gone. It checks no permission: holding the volume
+     * already grants every caller, and the tag keeps a key holder from reaching an object no key was issued for.
+     */
+    readonly resolveReferenceKey: (key: ReferenceKey) => Effect.Effect<ObjectReference, FsFailure>;
     readonly [VolumeId]: true;
     /** Creates a caller rooted at `/` with independent credentials, umask, and current directory. */
-    readonly caller: (options?: RootCallerOptions) => Effect.Effect<Caller, ConfigurationError | FsError>;
+    readonly caller: (options?: RootCallerOptions) => Effect.Effect<Caller, VfsError>;
 }
 /**
  * An ordinary volume with final-state inspection relative to one immutable snapshot base.
@@ -1258,7 +1382,6 @@ export interface Volume {
  * @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*() {
@@ -1276,7 +1399,7 @@ export interface Volume {
  *   return captured.changes.map((change) => change._tag)
  * })
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * Effect.runPromise(program).then(console.log)
  * // [ 'Added' ]
  * ```
  *
@@ -1285,62 +1408,118 @@ export interface Volume {
  */
 export interface OverlayVolume extends Volume {
     /** Computes final differences from the immutable base when this reusable effect executes. */
-    readonly changes: (options?: OverlayChangesOptions) => Effect.Effect<ReadonlyArray<OverlayChange>, ConfigurationError | ImageError | FsError>;
+    readonly changes: (options?: OverlayChangesOptions) => Effect.Effect<ReadonlyArray<OverlayChange>, VfsError>;
     /** Captures one committed state when this reusable effect executes. */
-    readonly capture: (options?: OverlayChangesOptions) => Effect.Effect<OverlayCapture, ConfigurationError | ImageError | FsError>;
+    readonly capture: (options?: OverlayChangesOptions) => Effect.Effect<OverlayCapture, VfsError>;
 }
 /**
- * Optional Effect service for providing an existing filesystem caller.
+ * The volume an application runs against, as an Effect service. The static
+ * layers wrap the explicit constructors; each call builds a fresh layer, so
+ * share one layer value to share one volume.
  *
  * @example
  * ```ts
  * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
  * import { Effect } from "effect"
  *
- * // Code depending on the service does not choose the volume it runs against.
- * const readVersion = Effect.gen(function*() {
- *   const caller = yield* Vfs.CurrentFileSystem
+ * const program = Effect.gen(function*() {
+ *   const fs = yield* Vfs.Caller
+ *   yield* fs.mkdir("/work")
  *
- *   return yield* caller.readFile("/version")
+ *   return (yield* fs.readDirectory("/")).value.map((entry) => new TextDecoder().decode(entry.name))
  * })
  *
- * const program = Effect.gen(function*() {
- *   const volume = yield* Vfs.make()
- *   const caller = yield* volume.caller()
+ * Effect.runPromise(program.pipe(Effect.provide(Vfs.Caller.layer()), Effect.provide(Vfs.Volume.layer())))
+ *   .then(console.log)
+ * // [ 'work' ]
+ * ```
  *
- *   yield* caller.writeFile("/version", new Uint8Array([49]), {
- *     access: "write",
- *     create: "exclusive"
+ * @category services
+ * @since 0.6.0
+ */
+export declare const Volume: Context.Service<Volume, Volume> & {
+    /** A fresh empty volume. */
+    readonly layer: (options?: VolumeOptions) => Layer.Layer<Volume, VfsError>;
+    /** A fresh volume restored from a snapshot. */
+    readonly layerFromSnapshot: (snapshot: Snapshot, options?: VolumeOptions) => Layer.Layer<Volume, VfsError>;
+    /** A fresh volume built from a fixture. */
+    readonly layerFromFixture: (fixture: Fixture, options?: VolumeOptions) => Layer.Layer<Volume, VfsError>;
+    /** A writable overlay over a snapshot base. */
+    readonly layerOverlay: (base: Snapshot, options?: VolumeOptions) => Layer.Layer<Volume, VfsError>;
+    /** A durable volume opened through the `LiveImageStore` in context; it shuts down with the layer's scope. */
+    readonly layerLive: (options: LiveVolumeOptions) => Layer.Layer<Volume, VfsError, LiveImageStore>;
+};
+/**
+ * The caller an application operates through, as an Effect service. A caller
+ * supplied through the service keeps its own volume, credentials, umask and
+ * working directory; `layer` makes a root caller on the `Volume` in context.
+ *
+ * @category services
+ * @since 0.6.0
+ */
+export declare const Caller: Context.Service<Caller, Caller> & {
+    /** A root caller on the volume in context; root callers need no scope. */
+    readonly layer: (options?: RootCallerOptions) => Layer.Layer<Caller, VfsError, Volume>;
+};
+/**
+ * Streams a snapshot's version 1 encoding as owned UTF-8 chunks: a header line,
+ * then one line per node, each ending in a newline.
+ *
+ * **Details**
+ *
+ * The encoding is newline-delimited JSON. The first line names the format and
+ * version; each later line is one node in inode order, with names and payloads
+ * as canonical base64. Nodes are encoded as the stream is pulled, so writing a
+ * large snapshot to a file or a socket never holds its whole encoding. A chunk
+ * holds at most 128 lines and 64 KiB, so a pull holds at most that and the next
+ * line; a line longer than 64 KiB is a chunk of its own.
+ *
+ * Given `limits`, the stream fails with `LimitExceeded` at the first line that
+ * `decodeSnapshot` would refuse under the same limits, naming the same field,
+ * so bytes it completes are known to decode without decoding them.
+ *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import { Effect, Stream } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.fromFixture({
+ *     entries: [{ kind: "file", path: "/f", bytes: new Uint8Array([1]) }]
  *   })
  *
- *   return yield* readVersion.pipe(Effect.provideService(Vfs.CurrentFileSystem, caller))
+ *   const text = yield* Vfs.encodeSnapshotStream(yield* volume.snapshot).pipe(
+ *     Stream.decodeText,
+ *     Stream.mkString
+ *   )
+ *
+ *   // A header line, then the root and the file, each line ending in a newline.
+ *   return text.split("\n").map((line) => (line === "" ? "end" : JSON.parse(line)._tag ?? "header"))
  * })
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
- * // Uint8Array(1) [ 49 ]
+ * Effect.runPromise(program).then(console.log)
+ * // [ 'header', 'directory', 'file', 'end' ]
  * ```
  *
- * @see The testing guide at `/guides/testing-with-an-isolated-filesystem`.
- * @category services
- * @since 0.1.0
+ * @see {@link encodeSnapshot} for the same bytes collected into one array.
+ * @see {@link decodeSnapshotSink} for reading a stream back under limits.
+ * @category serialization
+ * @since 0.6.0
  */
-export declare const CurrentFileSystem: Context.Service<CurrentFileSystem, Caller>;
+export declare const encodeSnapshotStream: (snapshot: Snapshot, limits?: DecodeLimits) => Stream.Stream<Uint8Array, ImageFailure | ArgumentFailure>;
 /**
- * The caller supplied by the optional filesystem service.
+ * Encodes a snapshot as owned UTF-8 bytes in the version 1 snapshot format.
  *
- * @category services
- * @since 0.1.0
- */
-export interface CurrentFileSystem extends Caller {
-}
-/**
- * Encodes a snapshot as owned UTF-8 JSON bytes using the version 1 snapshot format.
+ * **Details**
+ *
+ * The bytes are the chunks of {@link encodeSnapshotStream} collected into one
+ * array: newline-delimited JSON, a header line and then one line per node.
+ * Given `limits`, encoding fails with `LimitExceeded` wherever `decodeSnapshot`
+ * would refuse the bytes under the same limits.
  *
  * @example
  * ```ts
  * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
  * import { Effect } from "effect"
  *
  * // Bytes are portable: store or transmit them, then decode under explicit limits.
@@ -1355,11 +1534,11 @@ export interface CurrentFileSystem extends Caller {
  *
  *   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
+ *   // The first line is the header carrying the version 1 snapshot format.
+ *   return JSON.parse(new TextDecoder().decode(bytes).split("\n")[0]!).version
  * })
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * Effect.runPromise(program).then(console.log)
  * // 1
  * ```
  *
@@ -1367,17 +1546,75 @@ export interface CurrentFileSystem extends Caller {
  * @category serialization
  * @since 0.1.0
  */
-export declare const encodeSnapshot: (snapshot: Snapshot) => Effect.Effect<Uint8Array, ImageError>;
+export declare const encodeSnapshot: (snapshot: Snapshot, limits?: DecodeLimits) => Effect.Effect<Uint8Array, ImageFailure | ArgumentFailure>;
+/**
+ * A sink that decodes a stream of version 1 snapshot chunks while enforcing
+ * explicit input and payload limits.
+ *
+ * **Details**
+ *
+ * Chunks may split lines, and UTF-8 sequences, anywhere. Each line is checked
+ * as it ends, so input that breaks a limit or a rule is refused before the
+ * sink holds more than one line of it: `maxLineBytes` bounds that line, and
+ * the other limits bound what the accepted lines add up to. A line is
+ * refused at the byte where it first crosses `maxLineBytes` or
+ * `maxEncodedBytes`, so the field a refusal names does not depend on how the
+ * input is chunked. Every line must end in a newline, the last included; a
+ * carriage return, an empty line, a byte-order mark and malformed UTF-8 are
+ * refused as `InvalidEncoding`.
+ *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import { ByteSize, Effect, Stream } from "effect"
+ *
+ * const limits: Vfs.DecodeLimits = {
+ *   maxEncodedBytes: ByteSize.megabytes(4),
+ *   maxRecords: 10_000,
+ *   maxEntries: 10_000,
+ *   maxDecodedBytes: ByteSize.megabytes(16),
+ *   maxLineBytes: ByteSize.megabytes(1)
+ * }
+ *
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.fromFixture({
+ *     entries: [{ kind: "file", path: "/f", bytes: new Uint8Array([1, 2, 3]) }]
+ *   })
+ *
+ *   // Rechunked to single bytes: the sink joins lines across chunks.
+ *   const snapshot = yield* Vfs.encodeSnapshotStream(yield* volume.snapshot).pipe(
+ *     Stream.flattenIterable,
+ *     Stream.rechunk(1),
+ *     Stream.map((byte) => new Uint8Array([byte])),
+ *     Stream.run(Vfs.decodeSnapshotSink(limits))
+ *   )
+ *
+ *   return yield* (yield* (yield* Vfs.fromSnapshot(snapshot)).caller()).readFile("/f")
+ * })
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // Uint8Array(3) [ 1, 2, 3 ]
+ * ```
+ *
+ * @see {@link DecodeLimits} for what each bound protects.
+ * @see {@link decodeSnapshot} for decoding bytes already in memory.
+ * @category serialization
+ * @since 0.6.0
+ */
+export declare const decodeSnapshotSink: (limits: DecodeLimits) => Sink.Sink<Snapshot, Uint8Array, never, ImageFailure | ArgumentFailure>;
 /**
  * Decodes version 1 snapshot bytes while enforcing explicit input and payload limits.
  *
+ * **Details**
+ *
+ * The same decoder as {@link decodeSnapshotSink}, run over one chunk.
+ *
  * @example
  * ```ts
  * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
  * import { ByteSize, Effect } from "effect"
  *
- * // Limits are mandatory: decoding is the boundary where untrusted input arrives.
+ * // Limits are mandatory: decoding is the boundary where outside input arrives.
  * const program = Effect.gen(function*() {
  *   const volume = yield* Vfs.make()
  *   const bytes = yield* Vfs.encodeSnapshot(yield* volume.snapshot)
@@ -1389,11 +1626,11 @@ export declare const encodeSnapshot: (snapshot: Snapshot) => Effect.Effect<Uint8
  *     maxDecodedBytes: ByteSize.megabytes(16)
  *   }).pipe(
  *     Effect.as("accepted"),
- *     Effect.catchTag("ImageError", (error) => Effect.succeed([error.code, error.field]))
+ *     Effect.catchTag("VfsError", (error) => Effect.succeed([error.code, error.field]))
  *   )
  * })
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * Effect.runPromise(program).then(console.log)
  * // [ 'LimitExceeded', 'encodedBytes' ]
  * ```
  *
@@ -1401,7 +1638,7 @@ export declare const encodeSnapshot: (snapshot: Snapshot) => Effect.Effect<Uint8
  * @category serialization
  * @since 0.1.0
  */
-export declare const decodeSnapshot: (input: Uint8Array, limits: DecodeLimits) => Effect.Effect<Snapshot, ImageError>;
+export declare const decodeSnapshot: (input: Uint8Array, limits: DecodeLimits) => Effect.Effect<Snapshot, ImageFailure | ArgumentFailure>;
 /**
  * Computes an exact portable delta between two immutable snapshots.
  * Requires the platform-neutral `Crypto.Crypto` service for base identity. Provide
@@ -1439,7 +1676,7 @@ export declare const decodeSnapshot: (input: Uint8Array, limits: DecodeLimits) =
  * @category snapshots
  * @since 0.1.0
  */
-export declare const diffSnapshots: (base: Snapshot, target: Snapshot, limits?: SnapshotDeltaModel.SnapshotDeltaLimits) => Effect.Effect<SnapshotDeltaModel.SnapshotDelta, ConfigurationError | ImageError | PlatformError.PlatformError, Crypto.Crypto>;
+export declare const diffSnapshots: (base: Snapshot, target: Snapshot, limits?: SnapshotDeltaModel.SnapshotDeltaLimits) => Effect.Effect<SnapshotDeltaModel.SnapshotDelta, VfsError | PlatformError.PlatformError, 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. Provide
@@ -1474,7 +1711,7 @@ export declare const diffSnapshots: (base: Snapshot, target: Snapshot, limits?:
  * @category snapshots
  * @since 0.1.0
  */
-export declare const inspectSnapshotDelta: (base: Snapshot, delta: SnapshotDeltaModel.SnapshotDelta, options?: SnapshotDeltaModel.SnapshotChangesOptions, limits?: SnapshotDeltaModel.SnapshotDeltaLimits) => Effect.Effect<ReadonlyArray<SnapshotDeltaModel.SnapshotChange>, ConfigurationError | ImageError | PlatformError.PlatformError | SnapshotDeltaModel.SnapshotDeltaError, Crypto.Crypto>;
+export declare const inspectSnapshotDelta: (base: Snapshot, delta: SnapshotDeltaModel.SnapshotDelta, options?: SnapshotDeltaModel.SnapshotChangesOptions, limits?: SnapshotDeltaModel.SnapshotDeltaLimits) => Effect.Effect<ReadonlyArray<SnapshotDeltaModel.SnapshotChange>, VfsError | PlatformError.PlatformError, 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. Provide
@@ -1514,7 +1751,7 @@ export declare const inspectSnapshotDelta: (base: Snapshot, delta: SnapshotDelta
  * @category snapshots
  * @since 0.1.0
  */
-export declare const applySnapshotDelta: (base: Snapshot, delta: SnapshotDeltaModel.SnapshotDelta, limits?: SnapshotDeltaModel.SnapshotDeltaLimits) => Effect.Effect<Snapshot, ConfigurationError | ImageError | PlatformError.PlatformError | SnapshotDeltaModel.SnapshotDeltaError, Crypto.Crypto>;
+export declare const applySnapshotDelta: (base: Snapshot, delta: SnapshotDeltaModel.SnapshotDelta, limits?: SnapshotDeltaModel.SnapshotDeltaLimits) => Effect.Effect<Snapshot, VfsError | PlatformError.PlatformError, Crypto.Crypto>;
 /**
  * Creates an Effect Schema codec between owned bytes and opaque snapshot deltas.
  * Omission uses `SnapshotDeltaLimits.default`.
@@ -1570,7 +1807,7 @@ export declare const SnapshotDeltaFromBytes: (limits?: SnapshotDeltaModel.Snapsh
  *
  *   const rejected = yield* Vfs.pathFromBytes(new Uint8Array([47, 0])).pipe(
  *     Effect.as("accepted"),
- *     Effect.catchTag("FsError", (error) => Effect.succeed(error.code))
+ *     Effect.catchTag("VfsError", (error) => Effect.succeed(error.code))
  *   )
  *
  *   return [yield* Vfs.pathToBytes(path), rejected]
@@ -1583,14 +1820,14 @@ export declare const SnapshotDeltaFromBytes: (limits?: SnapshotDeltaModel.Snapsh
  * @category constructors
  * @since 0.1.0
  */
-export declare const pathFromBytes: (bytes: Uint8Array) => Effect.Effect<BytePath, FsError>;
+export declare const pathFromBytes: (bytes: Uint8Array) => Effect.Effect<BytePath, FsFailure>;
 /**
  * Copies the bytes held by an opaque byte path.
  *
  * @category getters
  * @since 0.1.0
  */
-export declare const pathToBytes: (path: BytePath) => Effect.Effect<Uint8Array, FsError>;
+export declare const pathToBytes: (path: BytePath) => Effect.Effect<Uint8Array, FsFailure>;
 /**
  * Schema for a complete fixture namespace with optional metadata and forward hard links.
  *
@@ -1601,7 +1838,6 @@ export declare const pathToBytes: (path: BytePath) => Effect.Effect<Uint8Array,
  * @example
  * ```ts
  * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
  * import { Effect, Schema } from "effect"
  *
  * // Fixtures must list every parent directory before its children.
@@ -1612,17 +1848,17 @@ export declare const pathToBytes: (path: BytePath) => Effect.Effect<Uint8Array,
  * }).pipe(
  *   Effect.flatMap(Vfs.fromFixture),
  *   Effect.as("built"),
- *   Effect.catchTag("ImageError", (error) => Effect.succeed(`rejected: ${error.code}`))
+ *   Effect.catchTag("VfsError", (error) => Effect.succeed(`rejected: ${error.code}`))
  * )
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * Effect.runPromise(program).then(console.log)
  * // rejected: InvalidStructure
  * ```
  *
  * @category schemas
  * @since 0.1.0
  */
-export declare const Fixture: typeof VfsModel.Fixture;
+export declare const Fixture: typeof FixtureModule.Fixture;
 /**
  * A complete filesystem fixture accepted by `fromFixture`.
  *
@@ -1641,7 +1877,6 @@ export type Fixture = typeof Fixture.Type;
  * @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*() {
@@ -1654,7 +1889,7 @@ export type Fixture = typeof Fixture.Type;
  *   return yield* caller.readFile("/work/notes.txt")
  * })
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * Effect.runPromise(program).then(console.log)
  * // Uint8Array(2) [ 104, 105 ]
  * ```
  *
@@ -1662,14 +1897,59 @@ export type Fixture = typeof Fixture.Type;
  * @category constructors
  * @since 0.1.0
  */
-export declare const make: (options?: VolumeOptions) => Effect.Effect<Volume, ConfigurationError | PlatformError.PlatformError, Crypto.Crypto>;
+export declare const make: (options?: VolumeOptions) => Effect.Effect<Volume, VfsError>;
+/**
+ * Streams the tree at `root` in a snapshot as fixture entries, read from the
+ * snapshot itself without restoring a volume.
+ *
+ * **Details**
+ *
+ * `root` resolves as a privileged caller at `/` of a volume restored from the
+ * snapshot with default options would resolve it, following intermediate
+ * symbolic links but not a final one and applying no path byte limit. Entries come in sorted
+ * pre-order, children in the byte order of their names, with paths rooted at
+ * `root`, so the root entry's path is `/`. A path stays a string while every
+ * name on it is UTF-8 and is a `BytePath` otherwise. A file or symbolic link
+ * that more than one name reaches is an entry at its first path and a
+ * `hardLink` to that path at the others. Each file's bytes are an owned copy,
+ * made when the stream pulls its entry. Every entry after the root's is a
+ * fixture entry for a volume holding the same tree.
+ *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import { Effect, Stream } from "effect"
+ *
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.fromFixture({
+ *     entries: [
+ *       { kind: "directory", path: "/src" },
+ *       { kind: "file", path: "/src/b.txt", bytes: new Uint8Array([2]) },
+ *       { kind: "file", path: "/src/a.txt", bytes: new Uint8Array([1]) },
+ *       { kind: "hardLink", path: "/src/c.txt", target: "/src/a.txt" }
+ *     ]
+ *   })
+ *
+ *   const entries = yield* Stream.runCollect(Vfs.snapshotEntries(yield* volume.snapshot, "/src"))
+ *
+ *   return entries.map((entry) => `${entry.kind} ${String(entry.path)}`)
+ * })
+ *
+ * Effect.runPromise(program).then(console.log)
+ * // [ 'directory /', 'file /a.txt', 'file /b.txt', 'hardLink /c.txt' ]
+ * ```
+ *
+ * @see {@link fromFixture} for building a volume from the entries.
+ * @category snapshots
+ * @since 0.6.0
+ */
+export declare const snapshotEntries: (snapshot: Snapshot, root: PathInput) => Stream.Stream<Fixture["entries"][number], FsFailure | ImageFailure>;
 /**
  * Restores a fresh volume from an opaque snapshot under the supplied destination limits.
  *
  * @example
  * ```ts
  * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
  * import { Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -1696,7 +1976,7 @@ export declare const make: (options?: VolumeOptions) => Effect.Effect<Volume, Co
  *   ]
  * })
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * Effect.runPromise(program).then(console.log)
  * // [ 'one', 'two' ]
  * ```
  *
@@ -1704,7 +1984,7 @@ export declare const make: (options?: VolumeOptions) => Effect.Effect<Volume, Co
  * @category constructors
  * @since 0.1.0
  */
-export declare const fromSnapshot: (snapshot: Snapshot, options?: VolumeOptions) => Effect.Effect<Volume, ConfigurationError | ImageError | PlatformError.PlatformError, Crypto.Crypto>;
+export declare const fromSnapshot: (snapshot: Snapshot, options?: VolumeOptions) => Effect.Effect<Volume, VfsError>;
 /**
  * Creates an isolated writable volume relative to one immutable snapshot base.
  *
@@ -1715,13 +1995,12 @@ export declare const fromSnapshot: (snapshot: Snapshot, options?: VolumeOptions)
  * storage. Metadata, namespace state, coordination, handles, and watches are
  * always private to the new workspace.
  *
- * Invalid base snapshots fail with `ImageError`; invalid volume limits fail
- * with `ConfigurationError`. Each execution creates a fresh workspace.
+ * Invalid base snapshots and invalid volume limits fail with `VfsError`. Each
+ * execution creates a fresh workspace.
  *
  * @example
  * ```ts
  * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
  * import { Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -1747,7 +2026,7 @@ export declare const fromSnapshot: (snapshot: Snapshot, options?: VolumeOptions)
  *   ]
  * })
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * Effect.runPromise(program).then(console.log)
  * // [ '{}', [ 'Updated' ] ]
  * ```
  *
@@ -1755,20 +2034,19 @@ export declare const fromSnapshot: (snapshot: Snapshot, options?: VolumeOptions)
  * @category constructors
  * @since 0.1.0
  */
-export declare const makeOverlay: (base: Snapshot, options?: VolumeOptions) => Effect.Effect<OverlayVolume, ConfigurationError | ImageError | PlatformError.PlatformError, Crypto.Crypto>;
+export declare const makeOverlay: (base: Snapshot, options?: VolumeOptions) => Effect.Effect<OverlayVolume, VfsError>;
 /**
  * Builds a fresh volume from a validated final-state fixture.
  *
  * @example
  * ```ts
  * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
  * import { Effect } from "effect"
  *
  * const encoder = new TextEncoder()
  *
  * const program = Effect.gen(function*() {
- *   // Parent directories must be listed explicitly, before their children.
+ *   // Parent directories must be listed explicitly, in any order.
  *   const volume = yield* Vfs.fromFixture({
  *     entries: [
  *       { kind: "directory", path: "/project" },
@@ -1781,16 +2059,19 @@ export declare const makeOverlay: (base: Snapshot, options?: VolumeOptions) => E
  *     ]
  *   })
  *
- *   return yield* (yield* volume.caller()).readDirectory("/project")
+ *   // A fixture's directories list their entries in the byte order of their names.
+ *   const listing = yield* (yield* volume.caller()).readDirectory("/project")
+ *
+ *   return listing.value.map((entry) => new TextDecoder().decode(entry.name))
  * })
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
- * // [ 'package.json', 'latest' ]
+ * Effect.runPromise(program).then(console.log)
+ * // [ 'latest', 'package.json' ]
  * ```
  *
  * @see The fixtures guide at `/guides/fixtures-and-snapshots`.
  * @category constructors
  * @since 0.1.0
  */
-export declare const fromFixture: (fixture: Fixture, options?: VolumeOptions) => Effect.Effect<Volume, ConfigurationError | ImageError | PlatformError.PlatformError, Crypto.Crypto>;
+export declare const fromFixture: (fixture: Fixture, options?: VolumeOptions) => Effect.Effect<Volume, VfsError>;
 //# sourceMappingURL=VirtualFileSystem.d.ts.map