@effect-vfs/core 0.3.1 → 0.4.0

package/dist/VirtualFileSystem.d.ts

@@ -8,11 +8,17 @@
  *
  * @since 0.1.0
  */
+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 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 type { BytePath } from "./BytePath.js";
+import type { ConfigurationError, FsError } from "./VirtualFileSystemError.js";
 export { BytePath } from "./BytePath.js";
 import type { DecodeLimits, ImageError, Snapshot } from "./Snapshot.js";
 export { DecodeLimits, ImageError, type Snapshot, SnapshotTypeId } from "./Snapshot.js";
@@ -78,9 +84,14 @@ export type FsCode = typeof FsCode.Type;
 /**
  * Describes an expected filesystem operation failure.
  *
+ * Durable providers distinguish `StorageRejected` (the operation definitely did not commit),
+ * `OutcomeUnknown` (it may have committed), and `VolumeUnavailable` (the provider cannot safely
+ * serve further operations until recovery). Built-in memory volumes never emit these codes.
+ *
  * @example
  * ```ts
  * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
  * import { Effect } from "effect"
  *
  * const program = Effect.gen(function*() {
@@ -96,23 +107,21 @@ export type FsCode = typeof FsCode.Type;
  *   )
  * })
  *
- * Effect.runPromise(program).then(console.log)
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
  * // Uint8Array(0) []
  * ```
  *
  * @category errors
  * @since 0.1.0
  */
-export declare const FsError: typeof VfsModel.FsError;
-/** @internal */
-export interface FsError extends VfsModel.FsError {
-}
+export { FsError } from "./VirtualFileSystemError.js";
 /**
  * Describes an invalid volume or caller option and names the rejected field.
  *
  * @example
  * ```ts
  * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
  * import { Effect } from "effect"
  *
  * // `field` names the rejected option, so the caller learns which key was wrong.
@@ -126,17 +135,14 @@ export interface FsError extends VfsModel.FsError {
  *   )
  * })
  *
- * Effect.runPromise(program).then(console.log)
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
  * // rejected maxEntries
  * ```
  *
  * @category errors
  * @since 0.1.0
  */
-export declare const ConfigurationError: typeof VfsModel.ConfigurationError;
-/** @internal */
-export interface ConfigurationError extends VfsModel.ConfigurationError {
-}
+export { ConfigurationError } from "./VirtualFileSystemError.js";
 /**
  * Schema for a caller's numeric identity, supplementary groups, and explicit privilege.
  *
@@ -157,6 +163,7 @@ 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*() {
@@ -177,7 +184,7 @@ export type Identity = typeof Identity.Type;
  *   return ((yield* user.stat("/home/user")).mode & 0o777).toString(8)
  * })
  *
- * Effect.runPromise(program).then(console.log)
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
  * // 755
  * ```
  *
@@ -192,12 +199,69 @@ export declare const RootCallerOptions: typeof VfsModel.RootCallerOptions;
  * @since 0.1.0
  */
 export type RootCallerOptions = typeof RootCallerOptions.Type;
+/**
+ * Schema for the failure boundary survived by an acknowledged volume write.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const VolumeDurability: typeof VfsModel.VolumeDurability;
+/**
+ * The failure boundary survived by an acknowledged volume write.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type VolumeDurability = typeof VolumeDurability.Type;
+/**
+ * Weakest-to-strongest ordering for volume durability guarantees.
+ *
+ * @category ordering
+ * @since 0.1.0
+ */
+export declare const VolumeDurabilityOrder: Order.Order<VolumeDurability>;
+/**
+ * Returns whether `actual` survives at least the failure boundary required by `required`.
+ *
+ * @category predicates
+ * @since 0.1.0
+ */
+export declare const isVolumeDurabilityAtLeast: (actual: VolumeDurability, required: VolumeDurability) => boolean;
+/**
+ * Schema for the stable logical identity of a volume.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const VolumeIdentity: typeof VfsModel.VolumeIdentity;
+/**
+ * Stable logical identity of a volume as a branded 128-bit lowercase hexadecimal string.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type VolumeIdentity = typeof VolumeIdentity.Type;
+/**
+ * Schema for one uninterrupted storage lifetime of a volume.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const VolumeIncarnation: typeof VfsModel.VolumeIncarnation;
+/**
+ * One uninterrupted storage lifetime as a branded 128-bit lowercase hexadecimal string.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type VolumeIncarnation = typeof VolumeIncarnation.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.
@@ -214,7 +278,7 @@ export type RootCallerOptions = typeof RootCallerOptions.Type;
  *   )
  * })
  *
- * Effect.runPromise(program).then(console.log)
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
  * // FileTooLarge
  * ```
  *
@@ -223,18 +287,48 @@ export type RootCallerOptions = typeof RootCallerOptions.Type;
  */
 export declare const VolumeOptions: typeof VfsModel.VolumeOptions;
 /**
- * Capacity and path limits for a volume.
+ * Capacity, admission, watch retention, and path limits for a volume.
+ * `maxPendingOperations` defaults to 64 and `maxWatchEvents` defaults to 256.
  *
  * @category models
  * @since 0.1.0
  */
 export type VolumeOptions = typeof VolumeOptions.Type;
+/**
+ * Effective capacity and path limits of a live volume. An absent limit is unlimited.
+ * `maxFileBytes` always includes the engine's maximum representable file size.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface VolumeLimits {
+    readonly maxBytes: ByteSize.ByteSize | undefined;
+    readonly maxFileBytes: ByteSize.ByteSize;
+    readonly maxEntries: number | undefined;
+    readonly maxPathBytes: ByteSize.ByteSize | undefined;
+    /** Waiting budget; at most this many plus one callers are admitted at once. */
+    readonly maxPendingOperations: number;
+    /** Maximum retained events per watch subscriber, including the rescan marker. */
+    readonly maxWatchEvents: number;
+}
+/**
+ * Live logical content and directory-entry usage of a volume.
+ * Open unlinked files remain in `usedBytes` until their last handle closes.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface VolumeUsage {
+    readonly usedBytes: bigint;
+    readonly entries: number;
+}
 /**
  * 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.
@@ -251,7 +345,7 @@ export type VolumeOptions = typeof VolumeOptions.Type;
  *   return [metadata.kind, metadata.size, metadata.nlink]
  * })
  *
- * Effect.runPromise(program).then(console.log)
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
  * // [ 'file', 3n, 1 ]
  * ```
  *
@@ -281,6 +375,7 @@ 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
@@ -302,7 +397,7 @@ export interface ObjectReference {
  *   return [before.value.kind, after.value.kind]
  * })
  *
- * Effect.runPromise(program).then(console.log)
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
  * // [ 'directory', 'directory' ]
  * ```
  *
@@ -323,6 +418,44 @@ export interface DirectoryEntry {
     readonly name: Uint8Array;
     readonly reference: ObjectReference;
 }
+/**
+ * A directory revision transition captured inside one coordinated operation.
+ *
+ * @category schemas
+ * @since 0.4.0
+ */
+export declare const DirectoryChange: typeof VfsModel.DirectoryChange;
+/**
+ * A directory revision transition captured inside one coordinated operation.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export type DirectoryChange = typeof DirectoryChange.Type;
+/**
+ * The identity and parent-directory transition produced by a named entry mutation.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface ReferenceEntryResult {
+    readonly reference: ObjectReference;
+    readonly directory: DirectoryChange;
+}
+/**
+ * The directory transitions produced by a same-directory or cross-directory rename.
+ *
+ * @category schemas
+ * @since 0.4.0
+ */
+export declare const RenameReferenceResult: typeof VfsModel.RenameReferenceResult;
+/**
+ * The directory transitions produced by a same-directory or cross-directory rename.
+ *
+ * @category models
+ * @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.
  *
@@ -339,6 +472,7 @@ export interface RelativeOptions {
  * @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*() {
@@ -362,7 +496,7 @@ export interface RelativeOptions {
  *   return [followed.toString(8), unchanged.toString(8)]
  * })
  *
- * Effect.runPromise(program).then(console.log)
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
  * // [ '600', '600' ]
  * ```
  *
@@ -400,6 +534,7 @@ export declare const TimeUpdate: typeof VfsModel.TimeUpdate;
  * @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*() {
@@ -421,7 +556,7 @@ export declare const TimeUpdate: typeof VfsModel.TimeUpdate;
  *   return [metadata.atimeNs, metadata.mtimeNs === 1_000n]
  * })
  *
- * Effect.runPromise(program).then(console.log)
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
  * // [ 1000n, false ]
  * ```
  *
@@ -442,6 +577,7 @@ 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
@@ -463,7 +599,7 @@ export type Times = typeof Times.Type;
  *   return yield* caller.readDirectory("/renamed")
  * }).pipe(Effect.scoped)
  *
- * Effect.runPromise(program).then(console.log)
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
  * // [ 'notes.txt' ]
  * ```
  *
@@ -495,6 +631,7 @@ 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.
@@ -512,7 +649,7 @@ export type SeekMode = typeof SeekMode.Type;
  *   return (yield* handle.stat).size
  * }).pipe(Effect.scoped)
  *
- * Effect.runPromise(program).then(console.log)
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
  * // 2n
  * ```
  *
@@ -527,12 +664,90 @@ export declare const OpenSettings: typeof VfsModel.OpenSettings;
  * @since 0.1.0
  */
 export type OpenOptions = typeof OpenSettings.Type & RelativeOptions;
+/**
+ * Settings for creating a directory through a parent object reference.
+ * `exactMode` skips the caller's umask for an explicit creation mode; permission policy still applies.
+ *
+ * @category schemas
+ * @since 0.4.0
+ */
+export declare const MkdirReferenceSettings: typeof VfsModel.MkdirReferenceSettings;
+/**
+ * Settings for creating a directory through a parent object reference.
+ * `exactMode` skips the caller's umask for an explicit creation mode; permission policy still applies.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export type MkdirReferenceSettings = typeof MkdirReferenceSettings.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;
+/**
+ * Settings for creating a symbolic link through a parent object reference.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export type SymlinkReferenceSettings = typeof SymlinkReferenceSettings.Type;
+/**
+ * Settings for opening an existing regular-file reference.
+ *
+ * @category schemas
+ * @since 0.4.0
+ */
+export declare const OpenReferenceSettings: typeof VfsModel.OpenReferenceSettings;
+/**
+ * Settings for opening an existing regular-file reference.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export type OpenReferenceSettings = typeof OpenReferenceSettings.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.
+ *
+ * @category schemas
+ * @since 0.4.0
+ */
+export declare const OpenChildReferenceSettings: typeof VfsModel.OpenChildReferenceSettings;
+/**
+ * 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.
+ * Initial mode, times, `initialSize`, and owner apply only to a newly created file.
+ * `expectedChild: null` requires an absent direct child. An observation requires
+ * the same direct object, revision, and timestamps; a mismatch fails with
+ * `StaleReference` before changing the file. Omission skips this observation check.
+ * This condition checks the named entry before any final symbolic-link traversal.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export type OpenChildReferenceSettings = typeof OpenChildReferenceSettings.Type;
+/**
+ * A scoped child-open result captured inside one coordinated operation.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface OpenChildReferenceResult {
+    readonly handle: FileHandle;
+    readonly reference: ObjectReference;
+    readonly created: boolean;
+    readonly directory: DirectoryChange;
+}
 /**
  * Options for an atomic whole-file write, including replacement and final mode controls.
  *
  * @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*() {
@@ -560,7 +775,7 @@ export type OpenOptions = typeof OpenSettings.Type & RelativeOptions;
  *   return [refused, new TextDecoder().decode(yield* caller.readFile("/app.conf"))]
  * })
  *
- * Effect.runPromise(program).then(console.log)
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
  * // [ 'AlreadyExists', 'v2' ]
  * ```
  *
@@ -574,6 +789,7 @@ export type WriteFileOptions = VfsModel.WriteFileOptions;
  * @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*() {
@@ -592,7 +808,7 @@ export type WriteFileOptions = VfsModel.WriteFileOptions;
  *   return [slice, yield* handle.seek(0n, "current")]
  * }).pipe(Effect.scoped)
  *
- * Effect.runPromise(program).then(console.log)
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
  * // [ Uint8Array(2) [ 2, 3 ], 4n ]
  * ```
  *
@@ -615,7 +831,7 @@ export interface FileHandle {
     readonly truncate: (length: bigint) => Effect.Effect<void, FsError>;
     /** Reads metadata for the open file. */
     readonly stat: Effect.Effect<Metadata, FsError>;
-    /** Checks handle liveness. In-memory storage has no host or crash durability to flush. */
+    /** Checks handle and provider health. Durable mutations have already committed; memory volumes have nothing to flush. */
     readonly sync: Effect.Effect<void, FsError>;
     /** Closes the handle. A repeated explicit close fails; scope cleanup remains safe. */
     readonly close: Effect.Effect<void, FsError>;
@@ -626,6 +842,7 @@ 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
@@ -643,13 +860,14 @@ export interface FileHandle {
  *   return yield* caller.readDirectory("/work")
  * })
  *
- * Effect.runPromise(program).then(console.log)
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).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
@@ -669,13 +887,14 @@ export interface FileHandle {
  *   return new TextDecoder().decode(yield* handle.read(64))
  * }).pipe(Effect.scoped)
  *
- * Effect.runPromise(program).then(console.log)
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).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
@@ -696,7 +915,7 @@ export interface FileHandle {
  *   return yield* caller.readDirectory("/dist")
  * }).pipe(Effect.scoped)
  *
- * Effect.runPromise(program).then(console.log)
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
  * // [ 'out.txt' ]
  * ```
  *
@@ -714,12 +933,38 @@ export interface Caller {
     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>;
-    /** Opens a referenced regular file for reading. */
-    readonly openReference: (reference: ObjectReference) => Effect.Effect<FileHandle, FsError, Scope.Scope>;
+    /** 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. */
@@ -790,6 +1035,7 @@ 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*() {
@@ -814,7 +1060,7 @@ export interface Caller {
  *     ))
  * }).pipe(Effect.scoped)
  *
- * Effect.runPromise(program).then(console.log)
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
  * // [ 'Create /logs', 'Remove /logs' ]
  * ```
  *
@@ -822,9 +1068,9 @@ export interface Caller {
  * @since 0.1.0
  */
 export interface Change {
-    /** Kind of committed namespace or content change. */
-    readonly _tag: "Create" | "Update" | "Remove";
-    /** Absolute path of the changed entry. */
+    /** 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;
 }
 /**
@@ -880,6 +1126,7 @@ 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*() {
@@ -895,7 +1142,7 @@ export type OverlayChange = typeof OverlayChange.Type;
  *   return [plain.length, timed.length]
  * })
  *
- * Effect.runPromise(program).then(console.log)
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
  * // [ 1, 2 ]
  * ```
  *
@@ -916,6 +1163,7 @@ 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*() {
@@ -939,7 +1187,7 @@ export type OverlayChangesOptions = typeof OverlayChangesOptions.Type;
  *   ]
  * })
  *
- * Effect.runPromise(program).then(console.log)
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
  * // [ [ 'Added' ], 'built' ]
  * ```
  *
@@ -958,6 +1206,7 @@ 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*() {
@@ -977,7 +1226,7 @@ export interface OverlayCapture {
  *   return Option.getOrElse(Option.map(change, (event) => event._tag), () => "none")
  * }).pipe(Effect.scoped)
  *
- * Effect.runPromise(program).then(console.log)
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
  * // Create
  * ```
  *
@@ -985,13 +1234,23 @@ export interface OverlayCapture {
  * @since 0.1.0
  */
 export interface Volume {
-    /** Opens a scoped stream of future committed changes. Events are not replayed. */
-    readonly watch: Effect.Effect<Stream.Stream<Change>, never, Scope.Scope>;
+    /** The strongest failure boundary survived by acknowledged writes. */
+    readonly durability: VolumeDurability;
+    /** Stable logical identity, preserved across reconstruction only when supplied explicitly. */
+    readonly identity: VolumeIdentity;
+    /** Fresh identity for this uninterrupted storage lifetime. */
+    readonly incarnation: VolumeIncarnation;
+    /** 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>;
     /** Captures an isolated snapshot of the reachable namespace and metadata. */
-    readonly snapshot: Effect.Effect<Snapshot, ImageError>;
+    readonly snapshot: Effect.Effect<Snapshot, ImageError | FsError>;
     readonly [VolumeId]: true;
     /** Creates a caller rooted at `/` with independent credentials, umask, and current directory. */
-    readonly caller: (options?: RootCallerOptions) => Effect.Effect<Caller, ConfigurationError>;
+    readonly caller: (options?: RootCallerOptions) => Effect.Effect<Caller, ConfigurationError | FsError>;
 }
 /**
  * An ordinary volume with final-state inspection relative to one immutable snapshot base.
@@ -999,6 +1258,7 @@ 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*() {
@@ -1016,7 +1276,7 @@ export interface Volume {
  *   return captured.changes.map((change) => change._tag)
  * })
  *
- * Effect.runPromise(program).then(console.log)
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
  * // [ 'Added' ]
  * ```
  *
@@ -1025,9 +1285,9 @@ 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>;
+    readonly changes: (options?: OverlayChangesOptions) => Effect.Effect<ReadonlyArray<OverlayChange>, ConfigurationError | ImageError | FsError>;
     /** Captures one committed state when this reusable effect executes. */
-    readonly capture: (options?: OverlayChangesOptions) => Effect.Effect<OverlayCapture, ConfigurationError | ImageError>;
+    readonly capture: (options?: OverlayChangesOptions) => Effect.Effect<OverlayCapture, ConfigurationError | ImageError | FsError>;
 }
 /**
  * Optional Effect service for providing an existing filesystem caller.
@@ -1035,6 +1295,7 @@ export interface OverlayVolume extends 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.
@@ -1056,7 +1317,7 @@ export interface OverlayVolume extends Volume {
  *   return yield* readVersion.pipe(Effect.provideService(Vfs.CurrentFileSystem, caller))
  * })
  *
- * Effect.runPromise(program).then(console.log)
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
  * // Uint8Array(1) [ 49 ]
  * ```
  *
@@ -1064,15 +1325,22 @@ export interface OverlayVolume extends Volume {
  * @category services
  * @since 0.1.0
  */
-export declare const CurrentFileSystem: typeof VfsModel.CurrentFileSystem;
-/** @internal */
-export type CurrentFileSystem = VfsModel.CurrentFileSystem;
+export declare const CurrentFileSystem: Context.Service<CurrentFileSystem, Caller>;
+/**
+ * The caller supplied by the optional filesystem service.
+ *
+ * @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.
  *
  * @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.
@@ -1091,7 +1359,7 @@ export type CurrentFileSystem = VfsModel.CurrentFileSystem;
  *   return JSON.parse(new TextDecoder().decode(bytes)).version
  * })
  *
- * Effect.runPromise(program).then(console.log)
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
  * // 1
  * ```
  *
@@ -1106,6 +1374,7 @@ export declare const encodeSnapshot: (snapshot: Snapshot) => Effect.Effect<Uint8
  * @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.
@@ -1124,7 +1393,7 @@ export declare const encodeSnapshot: (snapshot: Snapshot) => Effect.Effect<Uint8
  *   )
  * })
  *
- * Effect.runPromise(program).then(console.log)
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
  * // [ 'LimitExceeded', 'encodedBytes' ]
  * ```
  *
@@ -1170,18 +1439,7 @@ export declare const decodeSnapshot: (input: Uint8Array, limits: DecodeLimits) =
  * @category snapshots
  * @since 0.1.0
  */
-export declare const diffSnapshots: (base: Snapshot, target: Snapshot, limits?: {
-    readonly maxEncodedBytes: import("effect/ByteSize").ByteSize;
-    readonly maxIdentityBytes: import("effect/ByteSize").ByteSize;
-    readonly maxDeltaRecords: number;
-    readonly maxDecodedDeltaBytes: import("effect/ByteSize").ByteSize;
-    readonly maxBaseRecords: number;
-    readonly maxTargetRecords: number;
-    readonly maxEntries: number;
-    readonly maxOutputRecords: number;
-    readonly maxOutputBytes: import("effect/ByteSize").ByteSize;
-    readonly maxInheritedRecords: number;
-} | undefined) => Effect.Effect<SnapshotDeltaModel.SnapshotDelta, VfsModel.ConfigurationError | ImageError | import("effect/PlatformError").PlatformError, import("effect/Crypto").Crypto>;
+export declare const diffSnapshots: (base: Snapshot, target: Snapshot, limits?: SnapshotDeltaModel.SnapshotDeltaLimits) => Effect.Effect<SnapshotDeltaModel.SnapshotDelta, ConfigurationError | ImageError | 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
@@ -1216,34 +1474,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?: {
-    readonly includeTimestamps?: boolean;
-} | undefined, limits?: {
-    readonly maxEncodedBytes: import("effect/ByteSize").ByteSize;
-    readonly maxIdentityBytes: import("effect/ByteSize").ByteSize;
-    readonly maxDeltaRecords: number;
-    readonly maxDecodedDeltaBytes: import("effect/ByteSize").ByteSize;
-    readonly maxBaseRecords: number;
-    readonly maxTargetRecords: number;
-    readonly maxEntries: number;
-    readonly maxOutputRecords: number;
-    readonly maxOutputBytes: import("effect/ByteSize").ByteSize;
-    readonly maxInheritedRecords: number;
-} | undefined) => Effect.Effect<readonly ({
-    readonly _tag: "Added";
-    readonly path: BytePath;
-    readonly kind: "directory" | "file" | "symlink";
-} | {
-    readonly _tag: "Removed";
-    readonly path: BytePath;
-    readonly kind: "directory" | "file" | "symlink";
-} | {
-    readonly _tag: "Updated";
-    readonly path: BytePath;
-    readonly beforeKind: "directory" | "file" | "symlink";
-    readonly afterKind: "directory" | "file" | "symlink";
-    readonly differences: readonly ("atimeNs" | "birthtimeNs" | "content" | "ctimeNs" | "gid" | "hardLinks" | "kind" | "mode" | "mtimeNs" | "target" | "uid")[];
-})[], VfsModel.ConfigurationError | ImageError | import("effect/PlatformError").PlatformError | SnapshotDeltaModel.SnapshotDeltaError, import("effect/Crypto").Crypto>;
+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>;
 /**
  * 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
@@ -1283,18 +1514,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?: {
-    readonly maxEncodedBytes: import("effect/ByteSize").ByteSize;
-    readonly maxIdentityBytes: import("effect/ByteSize").ByteSize;
-    readonly maxDeltaRecords: number;
-    readonly maxDecodedDeltaBytes: import("effect/ByteSize").ByteSize;
-    readonly maxBaseRecords: number;
-    readonly maxTargetRecords: number;
-    readonly maxEntries: number;
-    readonly maxOutputRecords: number;
-    readonly maxOutputBytes: import("effect/ByteSize").ByteSize;
-    readonly maxInheritedRecords: number;
-} | undefined) => Effect.Effect<Snapshot, VfsModel.ConfigurationError | ImageError | import("effect/PlatformError").PlatformError | SnapshotDeltaModel.SnapshotDeltaError, import("effect/Crypto").Crypto>;
+export declare const applySnapshotDelta: (base: Snapshot, delta: SnapshotDeltaModel.SnapshotDelta, limits?: SnapshotDeltaModel.SnapshotDeltaLimits) => Effect.Effect<Snapshot, ConfigurationError | ImageError | PlatformError.PlatformError | SnapshotDeltaModel.SnapshotDeltaError, Crypto.Crypto>;
 /**
  * Creates an Effect Schema codec between owned bytes and opaque snapshot deltas.
  * Omission uses `SnapshotDeltaLimits.default`.
@@ -1381,6 +1601,7 @@ 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.
@@ -1394,7 +1615,7 @@ export declare const pathToBytes: (path: BytePath) => Effect.Effect<Uint8Array,
  *   Effect.catchTag("ImageError", (error) => Effect.succeed(`rejected: ${error.code}`))
  * )
  *
- * Effect.runPromise(program).then(console.log)
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
  * // rejected: InvalidStructure
  * ```
  *
@@ -1420,6 +1641,7 @@ 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*() {
@@ -1432,7 +1654,7 @@ export type Fixture = typeof Fixture.Type;
  *   return yield* caller.readFile("/work/notes.txt")
  * })
  *
- * Effect.runPromise(program).then(console.log)
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
  * // Uint8Array(2) [ 104, 105 ]
  * ```
  *
@@ -1440,13 +1662,14 @@ export type Fixture = typeof Fixture.Type;
  * @category constructors
  * @since 0.1.0
  */
-export declare const make: (options?: VolumeOptions) => Effect.Effect<Volume, ConfigurationError>;
+export declare const make: (options?: VolumeOptions) => Effect.Effect<Volume, ConfigurationError | PlatformError.PlatformError, Crypto.Crypto>;
 /**
  * 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*() {
@@ -1473,7 +1696,7 @@ export declare const make: (options?: VolumeOptions) => Effect.Effect<Volume, Co
  *   ]
  * })
  *
- * Effect.runPromise(program).then(console.log)
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
  * // [ 'one', 'two' ]
  * ```
  *
@@ -1481,7 +1704,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>;
+export declare const fromSnapshot: (snapshot: Snapshot, options?: VolumeOptions) => Effect.Effect<Volume, ConfigurationError | ImageError | PlatformError.PlatformError, Crypto.Crypto>;
 /**
  * Creates an isolated writable volume relative to one immutable snapshot base.
  *
@@ -1498,6 +1721,7 @@ export declare const fromSnapshot: (snapshot: Snapshot, options?: VolumeOptions)
  * @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*() {
@@ -1523,7 +1747,7 @@ export declare const fromSnapshot: (snapshot: Snapshot, options?: VolumeOptions)
  *   ]
  * })
  *
- * Effect.runPromise(program).then(console.log)
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
  * // [ '{}', [ 'Updated' ] ]
  * ```
  *
@@ -1531,13 +1755,14 @@ 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>;
+export declare const makeOverlay: (base: Snapshot, options?: VolumeOptions) => Effect.Effect<OverlayVolume, ConfigurationError | ImageError | PlatformError.PlatformError, Crypto.Crypto>;
 /**
  * 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()
@@ -1559,7 +1784,7 @@ export declare const makeOverlay: (base: Snapshot, options?: VolumeOptions) => E
  *   return yield* (yield* volume.caller()).readDirectory("/project")
  * })
  *
- * Effect.runPromise(program).then(console.log)
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
  * // [ 'package.json', 'latest' ]
  * ```
  *
@@ -1567,5 +1792,5 @@ export declare const makeOverlay: (base: Snapshot, options?: VolumeOptions) => E
  * @category constructors
  * @since 0.1.0
  */
-export declare const fromFixture: (fixture: Fixture, options?: VolumeOptions) => Effect.Effect<Volume, ConfigurationError | ImageError>;
+export declare const fromFixture: (fixture: Fixture, options?: VolumeOptions) => Effect.Effect<Volume, ConfigurationError | ImageError | PlatformError.PlatformError, Crypto.Crypto>;
 //# sourceMappingURL=VirtualFileSystem.d.ts.map