@effect-vfs/core 0.5.0 → 0.6.0

package/dist/VirtualFileSystem.js

@@ -1,24 +1,32 @@
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
 import * as Result from "effect/Result";
 import * as Schema from "effect/Schema";
 import * as SchemaIssue from "effect/SchemaIssue";
 import * as SchemaTransformation from "effect/SchemaTransformation";
+import * as Sink from "effect/Sink";
+import * as Stream from "effect/Stream";
+import * as CallerModule from "./Caller.js";
+import * as FileHandleModule from "./FileHandle.js";
+import * as FixtureModule from "./Fixture.js";
+import * as MetadataModule from "./Metadata.js";
+import * as VfsErrorModule from "./VfsError.js";
+import * as VolumeModule from "./Volume.js";
+import * as WatchModule from "./Watch.js";
+export { Entry, isEntry, isTarget, Name, Target } from "./Target.js";
 export { BytePath } from "./BytePath.js";
-export { DecodeLimits, ImageError, SnapshotTypeId } from "./Snapshot.js";
-import { decodeConfiguration } from "./internal/errors.js";
+export { DecodeLimits, SnapshotTypeId } from "./Snapshot.js";
+import { BudgetFromDecodeLimits, DeltaBudgetFromLimits } from "./internal/budget.js";
+import { decodeConfiguration, retargetFailure } from "./internal/errors.js";
 import * as FixtureInternal from "./internal/fixture.js";
 import * as Image from "./internal/image.js";
 import * as Path from "./internal/path.js";
 import * as SnapshotDeltaInternal from "./internal/snapshotDelta.js";
 import * as VfsModel from "./internal/virtualFileSystem.js";
+import { open as openLiveVolume } from "./LiveVolume.js";
 import * as SnapshotDeltaModel from "./SnapshotDelta.js";
-export { SnapshotChange, SnapshotChangesOptions, SnapshotDeltaError, SnapshotDeltaLimits, SnapshotDeltaTypeId, SnapshotDifference, SnapshotNodeKind } from "./SnapshotDelta.js";
-const VolumeId = VfsModel.VolumeId;
-const CallerId = VfsModel.CallerId;
-const FileHandleId = VfsModel.FileHandleId;
-const DirectoryHandleId = VfsModel.DirectoryHandleId;
-const ObjectReferenceId = VfsModel.ObjectReferenceId;
+export { SnapshotChange, SnapshotChangesOptions, SnapshotDeltaLimits, SnapshotDeltaTypeId, SnapshotDifference, SnapshotNodeKind } from "./SnapshotDelta.js";
 /**
  * Schema for portable virtual filesystem error codes.
  *
@@ -49,7 +57,7 @@ const ObjectReferenceId = VfsModel.ObjectReferenceId;
  * @category schemas
  * @since 0.1.0
  */
-export const FsCode = VfsModel.FsCode;
+export const FsCode = VfsErrorModule.FsCode;
 /**
  * Describes an expected filesystem operation failure.
  *
@@ -60,7 +68,6 @@ export const FsCode = VfsModel.FsCode;
  * @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*() {
@@ -69,28 +76,26 @@ export const FsCode = VfsModel.FsCode;
  *   // 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.
@@ -100,32 +105,31 @@ 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 { DeltaCode, ImageCode, StoreCode, VfsCode, VfsError } from "./VfsError.js";
 /**
  * Schema for a caller's numeric identity, supplementary groups, and explicit privilege.
  *
  * @category schemas
  * @since 0.1.0
  */
-export const Identity = VfsModel.Identity;
+export const Identity = CallerModule.Identity;
 /**
  * Schema for root caller credentials and creation mask.
  *
  * @example
  * ```ts
  * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
  * import { Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -146,56 +150,88 @@ export const Identity = VfsModel.Identity;
  *   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 const RootCallerOptions = VfsModel.RootCallerOptions;
+export const RootCallerOptions = CallerModule.RootCallerOptions;
 /**
  * Schema for the failure boundary survived by an acknowledged volume write.
  *
  * @category schemas
  * @since 0.1.0
  */
-export const VolumeDurability = VfsModel.VolumeDurability;
+export const VolumeDurability = VolumeModule.VolumeDurability;
 /**
  * Weakest-to-strongest ordering for volume durability guarantees.
  *
  * @category ordering
  * @since 0.1.0
  */
-export const VolumeDurabilityOrder = VfsModel.VolumeDurabilityOrder;
+export const VolumeDurabilityOrder = VolumeModule.VolumeDurabilityOrder;
 /**
  * Returns whether `actual` survives at least the failure boundary required by `required`.
  *
  * @category predicates
  * @since 0.1.0
  */
-export const isVolumeDurabilityAtLeast = VfsModel.isVolumeDurabilityAtLeast;
+export const isVolumeDurabilityAtLeast = VolumeModule.isVolumeDurabilityAtLeast;
 /**
  * Schema for the stable logical identity of a volume.
  *
  * @category schemas
  * @since 0.1.0
  */
-export const VolumeIdentity = VfsModel.VolumeIdentity;
+export const VolumeIdentity = VolumeModule.VolumeIdentity;
 /**
  * Schema for one uninterrupted storage lifetime of a volume.
  *
  * @category schemas
  * @since 0.1.0
  */
-export const VolumeIncarnation = VfsModel.VolumeIncarnation;
+export const VolumeIncarnation = VolumeModule.VolumeIncarnation;
+/**
+ * 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 const ReferenceKey = VolumeModule.ReferenceKey;
 /**
  * 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.
@@ -208,25 +244,24 @@ export const VolumeIncarnation = VfsModel.VolumeIncarnation;
  *     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 const VolumeOptions = VfsModel.VolumeOptions;
+export const VolumeOptions = VolumeModule.VolumeOptions;
 /**
  * Schema for filesystem node metadata with bigint inode, size, and nanosecond fields.
  *
  * @example
  * ```ts
  * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
  * import { Effect } from "effect"
  *
  * // Sizes and inode numbers are bigint; times are nanosecond timestamps.
@@ -243,49 +278,56 @@ export const VolumeOptions = VfsModel.VolumeOptions;
  *   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 const Metadata = VfsModel.Metadata;
+export const Metadata = MetadataModule.Metadata;
+/**
+ * Settings for walking a directory tree: the order and the optional depth,
+ * entry, and byte bounds.
+ *
+ * @category schemas
+ * @since 0.6.0
+ */
+export const WalkOptions = CallerModule.WalkOptions;
 /**
  * A directory revision transition captured inside one coordinated operation.
  *
  * @category schemas
  * @since 0.4.0
  */
-export const DirectoryChange = VfsModel.DirectoryChange;
+export const DirectoryChange = CallerModule.DirectoryChange;
 /**
  * The directory transitions produced by a same-directory or cross-directory rename.
  *
  * @category schemas
  * @since 0.4.0
  */
-export const RenameReferenceResult = VfsModel.RenameReferenceResult;
+export const RenameReferenceResult = CallerModule.RenameReferenceResult;
 /**
  * Schema for an owner update. Omitted fields retain their existing values.
  *
  * @category schemas
  * @since 0.1.0
  */
-export const OwnerUpdate = VfsModel.OwnerUpdate;
+export const OwnerUpdate = MetadataModule.OwnerUpdate;
 /**
  * Schema for setting a timestamp to the clock, retaining it, or supplying nanoseconds.
  *
  * @category schemas
  * @since 0.1.0
  */
-export const TimeUpdate = VfsModel.TimeUpdate;
+export const TimeUpdate = 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*() {
@@ -307,28 +349,27 @@ export const TimeUpdate = 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 const Times = VfsModel.Times;
+export const Times = MetadataModule.Times;
 /**
  * Schema for file seek origins, including dense-file data and hole queries.
  *
  * @category schemas
  * @since 0.1.0
  */
-export const SeekMode = VfsModel.SeekMode;
+export const SeekMode = FileHandleModule.SeekMode;
 /**
  * Schema for file access, creation, append, truncate, and symlink behavior.
  *
  * @example
  * ```ts
  * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
  * import { Effect } from "effect"
  *
  * // `access` is required; `create` decides whether a missing file is an error.
@@ -346,36 +387,49 @@ export const SeekMode = VfsModel.SeekMode;
  *   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 const OpenSettings = VfsModel.OpenSettings;
+export const OpenOptions = CallerModule.OpenOptions;
 /**
  * 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 const MkdirReferenceSettings = VfsModel.MkdirReferenceSettings;
+export const MkdirOptions = CallerModule.MkdirOptions;
+/**
+ * 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 const RemoveOptions = CallerModule.RemoveOptions;
 /**
  * Settings for creating a symbolic link through a parent object reference.
  *
  * @category schemas
  * @since 0.4.0
  */
-export const SymlinkReferenceSettings = VfsModel.SymlinkReferenceSettings;
+export const SymlinkOptions = CallerModule.SymlinkOptions;
 /**
- * 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 const OpenReferenceSettings = VfsModel.OpenReferenceSettings;
+export const SetattrOptions = CallerModule.SetattrOptions;
 /**
  * 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.
@@ -383,21 +437,143 @@ export const OpenReferenceSettings = VfsModel.OpenReferenceSettings;
  * @category schemas
  * @since 0.4.0
  */
-export const OpenChildReferenceSettings = VfsModel.OpenChildReferenceSettings;
+export const OpenEntryOptions = CallerModule.OpenEntryOptions;
+/**
+ * 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("VfsError", (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 const WriteFileOptions = CallerModule.WriteFileOptions;
+/**
+ * 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 schemas
+ * @since 0.1.0
+ */
+export const Change = WatchModule.Change;
+/**
+ * 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 const WatchOptions = WatchModule.WatchOptions;
 /**
  * Schema for the filesystem entry kinds reported by overlay summaries.
  *
  * @category schemas
  * @since 0.1.0
  */
-export const OverlayNodeKind = VfsModel.OverlayNodeKind;
+export const OverlayNodeKind = VolumeModule.OverlayNodeKind;
 /**
  * Schema for observable fields that can differ from an overlay's immutable base.
  *
  * @category schemas
  * @since 0.1.0
  */
-export const OverlayDifference = VfsModel.OverlayDifference;
+export const OverlayDifference = VolumeModule.OverlayDifference;
 /**
  * Schema for a final-state overlay difference.
  *
@@ -409,14 +585,13 @@ export const OverlayDifference = VfsModel.OverlayDifference;
  * @category schemas
  * @since 0.1.0
  */
-export const OverlayChange = VfsModel.OverlayChange;
+export const OverlayChange = VolumeModule.OverlayChange;
 /**
  * Schema for overlay summary filtering.
  *
  * @example
  * ```ts
  * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
- * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
  * import { Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -432,58 +607,118 @@ export const OverlayChange = VfsModel.OverlayChange;
  *   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 const OverlayChangesOptions = VfsModel.OverlayChangesOptions;
+export const OverlayChangesOptions = VolumeModule.OverlayChangesOptions;
 /**
- * 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 const Volume = Object.assign(Context.Service("@effect-vfs/core/Volume"), {
+    layer: (options) => Layer.effect(Volume, VfsModel.make(options)),
+    layerFromSnapshot: (snapshot, options) => Layer.effect(Volume, VfsModel.fromSnapshot(snapshot, options)),
+    layerFromFixture: (fixture, options) => Layer.effect(Volume, FixtureInternal.fromFixture(fixture, options)),
+    layerOverlay: (base, options) => Layer.effect(Volume, VfsModel.makeOverlay(base, options)),
+    layerLive: (options) => Layer.effect(Volume, openLiveVolume(options))
+});
+/**
+ * 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 const Caller = Object.assign(Context.Service("@effect-vfs/core/Caller"), {
+    layer: (options) => Layer.effect(Caller, Effect.flatMap(Volume, (volume) => volume.caller(options)))
+});
+const snapshotBudget = (operation, limits) => Effect.fromResult(decodeConfiguration(BudgetFromDecodeLimits, limits, operation));
+const optionalBudget = (operation, limits) => limits === undefined ? Effect.undefined : snapshotBudget(operation, limits);
+/**
+ * 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 const CurrentFileSystem = Context.Service("@effect-vfs/core/CurrentFileSystem");
+export const encodeSnapshotStream = (snapshot, limits) => Stream.unwrap(Effect.map(optionalBudget("encodeSnapshotStream", limits), (budget) => Image.encodeSnapshotStream(snapshot, budget))).pipe(Stream.mapError((error) => retargetFailure("encodeSnapshotStream", error)));
 /**
- * Encodes a snapshot as owned UTF-8 JSON bytes using the version 1 snapshot format.
+ * Encodes a snapshot as owned UTF-8 bytes in 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.
@@ -498,11 +733,11 @@ export const CurrentFileSystem = Context.Service("@effect-vfs/core/CurrentFileSy
  *
  *   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
  * ```
  *
@@ -510,17 +745,75 @@ export const CurrentFileSystem = Context.Service("@effect-vfs/core/CurrentFileSy
  * @category serialization
  * @since 0.1.0
  */
-export const encodeSnapshot = Image.encodeSnapshot;
+export const encodeSnapshot = (snapshot, limits) => Effect.flatMap(optionalBudget("encodeSnapshot", limits), (budget) => Image.encodeSnapshot(snapshot, budget)).pipe(Effect.mapError((error) => retargetFailure("encodeSnapshot", error)));
+/**
+ * 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 const decodeSnapshotSink = (limits) => Sink.unwrap(Effect.map(snapshotBudget("decodeSnapshot", limits), (budget) => Image.decodeSnapshotSink(budget))).pipe(Sink.mapError((error) => retargetFailure("decodeSnapshot", error)));
 /**
  * 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)
@@ -532,11 +825,11 @@ export const encodeSnapshot = Image.encodeSnapshot;
  *     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' ]
  * ```
  *
@@ -544,11 +837,8 @@ export const encodeSnapshot = Image.encodeSnapshot;
  * @category serialization
  * @since 0.1.0
  */
-export const decodeSnapshot = Image.decodeSnapshot;
-const deltaLimits = (limits) => {
-    const decoded = decodeConfiguration(SnapshotDeltaModel.SnapshotDeltaLimits, limits ?? SnapshotDeltaModel.SnapshotDeltaLimits.default);
-    return Result.isFailure(decoded) ? Effect.fail(decoded.failure) : Effect.succeed(decoded.success);
-};
+export const decodeSnapshot = (input, limits) => Stream.run(Stream.succeed(input), decodeSnapshotSink(limits));
+const deltaLimits = (operation, limits) => Effect.fromResult(decodeConfiguration(DeltaBudgetFromLimits, limits ?? SnapshotDeltaModel.SnapshotDeltaLimits.default, operation));
 /**
  * Computes an exact portable delta between two immutable snapshots.
  * Requires the platform-neutral `Crypto.Crypto` service for base identity. Provide
@@ -587,7 +877,8 @@ const deltaLimits = (limits) => {
  * @since 0.1.0
  */
 export const diffSnapshots = Effect.fn("VirtualFileSystem.diffSnapshots")(function* (base, target, limits) {
-    return yield* SnapshotDeltaInternal.diffSnapshots(base, target, yield* deltaLimits(limits));
+    // The delta codec fails under its own name; the public entry point names itself.
+    return yield* SnapshotDeltaInternal.diffSnapshots(base, target, yield* deltaLimits("diffSnapshots", limits)).pipe(Effect.mapError((error) => retargetFailure("diffSnapshots", error)));
 });
 /**
  * Verifies an exact snapshot delta against its base and derives an owned path-oriented summary.
@@ -624,10 +915,8 @@ export const diffSnapshots = Effect.fn("VirtualFileSystem.diffSnapshots")(functi
  * @since 0.1.0
  */
 export const inspectSnapshotDelta = Effect.fn("VirtualFileSystem.inspectSnapshotDelta")(function* (base, delta, options, limits) {
-    const decoded = decodeConfiguration(SnapshotDeltaModel.SnapshotChangesOptions, options ?? {});
-    if (Result.isFailure(decoded))
-        return yield* decoded.failure;
-    return yield* SnapshotDeltaInternal.inspectSnapshotDelta(base, delta, decoded.success, yield* deltaLimits(limits));
+    const decoded = yield* Effect.fromResult(decodeConfiguration(SnapshotDeltaModel.SnapshotChangesOptions, options ?? {}, "inspectSnapshotDelta"));
+    return yield* SnapshotDeltaInternal.inspectSnapshotDelta(base, delta, decoded, yield* deltaLimits("inspectSnapshotDelta", limits)).pipe(Effect.mapError((error) => retargetFailure("inspectSnapshotDelta", error)));
 });
 /**
  * Applies an exact delta to its semantically matching base and returns a new snapshot.
@@ -669,7 +958,7 @@ export const inspectSnapshotDelta = Effect.fn("VirtualFileSystem.inspectSnapshot
  * @since 0.1.0
  */
 export const applySnapshotDelta = Effect.fn("VirtualFileSystem.applySnapshotDelta")(function* (base, delta, limits) {
-    return yield* SnapshotDeltaInternal.applySnapshotDelta(base, delta, yield* deltaLimits(limits));
+    return yield* SnapshotDeltaInternal.applySnapshotDelta(base, delta, yield* deltaLimits("applySnapshotDelta", limits)).pipe(Effect.mapError((error) => retargetFailure("applySnapshotDelta", error)));
 });
 const deltaSchemaIssue = (cause, input, options) => new SchemaIssue.InvalidValue({ message: `Snapshot delta ${cause.code}${cause.field === undefined ? "" : ` at ${cause.field}`}` }, input, options);
 /**
@@ -708,7 +997,7 @@ const deltaSchemaIssue = (cause, input, options) => new SchemaIssue.InvalidValue
  * @since 0.1.0
  */
 export const SnapshotDeltaFromBytes = (limits) => {
-    const selected = Schema.decodeResult(SnapshotDeltaModel.SnapshotDeltaLimits, { onExcessProperty: "error" })(limits ?? SnapshotDeltaModel.SnapshotDeltaLimits.default);
+    const selected = Schema.decodeResult(DeltaBudgetFromLimits, { onExcessProperty: "error" })(limits ?? SnapshotDeltaModel.SnapshotDeltaLimits.default);
     return Schema.Uint8Array.pipe(Schema.decodeTo(SnapshotDeltaModel.SnapshotDelta, SchemaTransformation.transformEffect({
         decode: (input, options) => Result.isFailure(selected)
             ? Effect.fail(new SchemaIssue.InvalidValue({ message: "Invalid snapshot delta limits" }, limits, options))
@@ -737,7 +1026,7 @@ export const SnapshotDeltaFromBytes = (limits) => {
  *
  *   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]
@@ -768,7 +1057,6 @@ export const pathToBytes = Path.pathToBytes;
  * @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.
@@ -779,17 +1067,17 @@ export const pathToBytes = Path.pathToBytes;
  * }).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 const Fixture = VfsModel.Fixture;
+export const Fixture = FixtureModule.Fixture;
 /**
  * Creates a fresh empty volume and captures the current Effect `Clock`.
  *
@@ -801,7 +1089,6 @@ export const Fixture = VfsModel.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 program = Effect.gen(function*() {
@@ -814,7 +1101,7 @@ export const Fixture = VfsModel.Fixture;
  *   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 ]
  * ```
  *
@@ -823,13 +1110,58 @@ export const Fixture = VfsModel.Fixture;
  * @since 0.1.0
  */
 export const make = VfsModel.make;
+/**
+ * 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 const snapshotEntries = Image.snapshotEntries;
 /**
  * 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*() {
@@ -856,7 +1188,7 @@ export const make = VfsModel.make;
  *   ]
  * })
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * Effect.runPromise(program).then(console.log)
  * // [ 'one', 'two' ]
  * ```
  *
@@ -875,13 +1207,12 @@ export const fromSnapshot = VfsModel.fromSnapshot;
  * 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*() {
@@ -907,7 +1238,7 @@ export const fromSnapshot = VfsModel.fromSnapshot;
  *   ]
  * })
  *
- * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * Effect.runPromise(program).then(console.log)
  * // [ '{}', [ 'Updated' ] ]
  * ```
  *
@@ -922,13 +1253,12 @@ export const makeOverlay = VfsModel.makeOverlay;
  * @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" },
@@ -941,11 +1271,14 @@ export const makeOverlay = VfsModel.makeOverlay;
  *     ]
  *   })
  *
- *   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`.