@effect-vfs/core 0.1.0 → 0.3.0

package/dist/VirtualFileSystem.d.ts

@@ -1,31 +1,29 @@
-import * as Context from "effect/Context";
-import { DecodeLimits, ImageError, type Snapshot } from "./Snapshot.js";
-export { DecodeLimits, ImageError, type Snapshot, SnapshotTypeId } from "./Snapshot.js";
-import * as Effect from "effect/Effect";
-import * as Schema from "effect/Schema";
-import * as Scope from "effect/Scope";
-import * as Stream from "effect/Stream";
-declare const BytePathId: unique symbol;
-declare const VolumeId: unique symbol;
-declare const CallerId: unique symbol;
-declare const FileHandleId: unique symbol;
-declare const DirectoryHandleId: unique symbol;
 /**
- * An opaque path that preserves arbitrary non-NUL bytes without UTF-8 conversion.
+ * Runtime-neutral virtual filesystem contracts and constructors.
  *
- * @category models
- * @since 0.1.0
- */
-export interface BytePath {
-    readonly [BytePathId]: true;
-}
-/**
- * Schema for an opaque byte-preserving filesystem path.
+ * **Details**
+ *
+ * Volumes own isolated namespaces. Callers carry path context and credentials,
+ * while file and directory handles use `Scope` for deterministic release.
  *
- * @category schemas
  * @since 0.1.0
  */
-export declare const BytePath: Schema.declare<BytePath, BytePath>;
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import type * as Scope from "effect/Scope";
+import type * as Stream from "effect/Stream";
+import { BytePath } from "./BytePath.js";
+export { BytePath } from "./BytePath.js";
+import { DecodeLimits, ImageError, type Snapshot } from "./Snapshot.js";
+export { DecodeLimits, ImageError, type Snapshot, SnapshotTypeId } from "./Snapshot.js";
+import * as VfsModel from "./internal/virtualFileSystem.js";
+import * as SnapshotDeltaModel from "./SnapshotDelta.js";
+export { SnapshotChange, SnapshotChangesOptions, type SnapshotDelta, SnapshotDeltaError, SnapshotDeltaLimits, SnapshotDeltaTypeId, SnapshotDifference, SnapshotNodeKind } from "./SnapshotDelta.js";
+declare const VolumeId: typeof VfsModel.VolumeId;
+declare const CallerId: typeof VfsModel.CallerId;
+declare const FileHandleId: typeof VfsModel.FileHandleId;
+declare const DirectoryHandleId: typeof VfsModel.DirectoryHandleId;
+declare const ObjectReferenceId: typeof VfsModel.ObjectReferenceId;
 /**
  * A UTF-8 string path or an opaque byte-preserving path.
  *
@@ -39,7 +37,7 @@ export type PathInput = string | BytePath;
  * @category schemas
  * @since 0.1.0
  */
-export declare const FsCode: Schema.Literals<readonly ["NotFound", "AlreadyExists", "NotEmpty", "NotDirectory", "AccessDenied", "InvalidHandle", "ForeignHandle", "ClosedCaller", "InvalidArgument", "InvalidPathEncoding", "PathTooLong", "NoSpace", "IsDirectory", "FileTooLarge", "NoData", "SymlinkLoop", "UnrepresentableName"]>;
+export declare const FsCode: typeof VfsModel.FsCode;
 /**
  * A portable virtual filesystem error code.
  *
@@ -47,37 +45,25 @@ export declare const FsCode: Schema.Literals<readonly ["NotFound", "AlreadyExist
  * @since 0.1.0
  */
 export type FsCode = typeof FsCode.Type;
-declare const FsError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
-    readonly _tag: "FsError";
-} & Readonly<A>;
 /**
  * Describes an expected filesystem operation failure.
  *
  * @category errors
  * @since 0.1.0
  */
-export declare class FsError extends FsError_base<{
-    /** Machine-readable reason for the failure. */
-    readonly code: FsCode;
-    /** Operation that detected the failure. */
-    readonly operation: string;
-    /** Path involved in the failure, when one path identifies it. */
-    readonly path?: PathInput;
-}> {
+export declare const FsError: typeof VfsModel.FsError;
+/** @internal */
+export interface FsError extends VfsModel.FsError {
 }
-declare const ConfigurationError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
-    readonly _tag: "ConfigurationError";
-} & Readonly<A>;
 /**
  * Describes an invalid volume or caller option and names the rejected field.
  *
  * @category errors
  * @since 0.1.0
  */
-export declare class ConfigurationError extends ConfigurationError_base<{
-    /** Name of the rejected option. */
-    readonly field: string;
-}> {
+export declare const ConfigurationError: typeof VfsModel.ConfigurationError;
+/** @internal */
+export interface ConfigurationError extends VfsModel.ConfigurationError {
 }
 /**
  * Schema for a caller's numeric identity, supplementary groups, and explicit privilege.
@@ -85,16 +71,7 @@ export declare class ConfigurationError extends ConfigurationError_base<{
  * @category schemas
  * @since 0.1.0
  */
-export declare const Identity: Schema.Struct<{
-    /** Numeric user identifier used by ownership and permission checks. */
-    readonly uid: Schema.Finite;
-    /** Primary numeric group identifier. */
-    readonly gid: Schema.Finite;
-    /** Supplementary group identifiers used by group permission checks. */
-    readonly groups: Schema.$Array<Schema.Finite>;
-    /** Grants root-style permission bypasses independently of `uid`. */
-    readonly privileged: Schema.Boolean;
-}>;
+export declare const Identity: typeof VfsModel.Identity;
 /**
  * A caller identity used for permission checks.
  *
@@ -108,21 +85,7 @@ export type Identity = typeof Identity.Type;
  * @category schemas
  * @since 0.1.0
  */
-export declare const RootCallerOptions: Schema.Struct<{
-    /** Caller identity. Defaults to privileged uid and gid `0`. */
-    readonly identity: Schema.optionalKey<Schema.Struct<{
-        /** Numeric user identifier used by ownership and permission checks. */
-        readonly uid: Schema.Finite;
-        /** Primary numeric group identifier. */
-        readonly gid: Schema.Finite;
-        /** Supplementary group identifiers used by group permission checks. */
-        readonly groups: Schema.$Array<Schema.Finite>;
-        /** Grants root-style permission bypasses independently of `uid`. */
-        readonly privileged: Schema.Boolean;
-    }>>;
-    /** Creation mask applied to requested modes. Defaults to `0o022`. */
-    readonly umask: Schema.optionalKey<Schema.Finite>;
-}>;
+export declare const RootCallerOptions: typeof VfsModel.RootCallerOptions;
 /**
  * Options for creating a root caller on a volume.
  *
@@ -136,16 +99,7 @@ export type RootCallerOptions = typeof RootCallerOptions.Type;
  * @category schemas
  * @since 0.1.0
  */
-export declare const VolumeOptions: Schema.Struct<{
-    /** Maximum number of filesystem nodes. Omission leaves the count unbounded. */
-    readonly maxEntries: Schema.optionalKey<Schema.Finite>;
-    /** Maximum combined regular-file content in bytes. */
-    readonly maxBytes: Schema.optionalKey<Schema.Finite>;
-    /** Maximum content size of one regular file in bytes. */
-    readonly maxFileBytes: Schema.optionalKey<Schema.Finite>;
-    /** Maximum encoded byte length of an absolute or relative path. */
-    readonly maxPathBytes: Schema.optionalKey<Schema.Finite>;
-}>;
+export declare const VolumeOptions: typeof VfsModel.VolumeOptions;
 /**
  * Capacity and path limits for a volume.
  *
@@ -159,19 +113,7 @@ export type VolumeOptions = typeof VolumeOptions.Type;
  * @category schemas
  * @since 0.1.0
  */
-export declare const Metadata: Schema.Struct<{
-    readonly kind: Schema.Literals<readonly ["directory", "file", "symlink"]>;
-    readonly ino: Schema.BigInt;
-    readonly nlink: Schema.Finite;
-    readonly size: Schema.BigInt;
-    readonly uid: Schema.Finite;
-    readonly gid: Schema.Finite;
-    readonly mode: Schema.Finite;
-    readonly atimeNs: Schema.BigInt;
-    readonly mtimeNs: Schema.BigInt;
-    readonly ctimeNs: Schema.BigInt;
-    readonly birthtimeNs: Schema.BigInt;
-}>;
+export declare const Metadata: typeof VfsModel.Metadata;
 /**
  * Metadata for a directory, regular file, or symbolic link.
  *
@@ -179,6 +121,35 @@ export declare const Metadata: Schema.Struct<{
  * @since 0.1.0
  */
 export type Metadata = typeof Metadata.Type;
+/**
+ * An opaque identity for one object in one live volume.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface ObjectReference {
+    readonly [ObjectReferenceId]: true;
+}
+/**
+ * A value and the revision of the object from the same coordinated observation.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface ObjectObservation<A> {
+    readonly value: A;
+    readonly revision: bigint;
+}
+/**
+ * One owned directory name paired with the referenced child object.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface DirectoryEntry {
+    readonly name: Uint8Array;
+    readonly reference: ObjectReference;
+}
 /**
  * Resolves a relative path from a live directory handle instead of the caller's directory.
  *
@@ -205,10 +176,7 @@ export interface MetadataOptions extends RelativeOptions {
  * @category schemas
  * @since 0.1.0
  */
-export declare const OwnerUpdate: Schema.Struct<{
-    readonly uid: Schema.optionalKey<Schema.Finite>;
-    readonly gid: Schema.optionalKey<Schema.Finite>;
-}>;
+export declare const OwnerUpdate: typeof VfsModel.OwnerUpdate;
 /**
  * An owner update for `chown` operations.
  *
@@ -222,38 +190,14 @@ export type OwnerUpdate = typeof OwnerUpdate.Type;
  * @category schemas
  * @since 0.1.0
  */
-export declare const TimeUpdate: Schema.Union<readonly [Schema.Struct<{
-    readonly kind: Schema.Literal<"now">;
-}>, Schema.Struct<{
-    readonly kind: Schema.Literal<"omit">;
-}>, Schema.Struct<{
-    readonly kind: Schema.Literal<"value">;
-    readonly nanoseconds: Schema.BigInt;
-}>]>;
+export declare const TimeUpdate: typeof VfsModel.TimeUpdate;
 /**
  * Schema for independent access and modification time updates.
  *
  * @category schemas
  * @since 0.1.0
  */
-export declare const Times: Schema.Struct<{
-    readonly access: Schema.Union<readonly [Schema.Struct<{
-        readonly kind: Schema.Literal<"now">;
-    }>, Schema.Struct<{
-        readonly kind: Schema.Literal<"omit">;
-    }>, Schema.Struct<{
-        readonly kind: Schema.Literal<"value">;
-        readonly nanoseconds: Schema.BigInt;
-    }>]>;
-    readonly modification: Schema.Union<readonly [Schema.Struct<{
-        readonly kind: Schema.Literal<"now">;
-    }>, Schema.Struct<{
-        readonly kind: Schema.Literal<"omit">;
-    }>, Schema.Struct<{
-        readonly kind: Schema.Literal<"value">;
-        readonly nanoseconds: Schema.BigInt;
-    }>]>;
-}>;
+export declare const Times: typeof VfsModel.Times;
 /**
  * Access and modification time updates for `utimes` operations.
  *
@@ -269,9 +213,7 @@ export type Times = typeof Times.Type;
  */
 export interface DirectoryHandle {
     readonly [DirectoryHandleId]: true;
-    /** Reads metadata for the directory while the handle remains open. */
     readonly stat: Effect.Effect<Metadata, FsError>;
-    /** Closes the handle. A repeated explicit close fails; scope cleanup remains safe. */
     readonly close: Effect.Effect<void, FsError>;
 }
 /**
@@ -280,7 +222,7 @@ export interface DirectoryHandle {
  * @category schemas
  * @since 0.1.0
  */
-export declare const SeekMode: Schema.Literals<readonly ["start", "current", "end", "data", "hole"]>;
+export declare const SeekMode: typeof VfsModel.SeekMode;
 /**
  * The origin used by a file handle seek operation.
  *
@@ -294,20 +236,7 @@ export type SeekMode = typeof SeekMode.Type;
  * @category schemas
  * @since 0.1.0
  */
-export declare const OpenSettings: Schema.Struct<{
-    /** Permitted operations on the returned handle. */
-    readonly access: Schema.Literals<readonly ["read", "write", "readWrite"]>;
-    /** Creation policy. Defaults to `"never"`. */
-    readonly create: Schema.optionalKey<Schema.Literals<readonly ["never", "ifMissing", "exclusive"]>>;
-    /** Requested mode for a new file, before applying the caller's umask. */
-    readonly mode: Schema.optionalKey<Schema.Finite>;
-    /** Write at the current end of file regardless of the handle cursor. */
-    readonly append: Schema.optionalKey<Schema.Boolean>;
-    /** Truncate an existing regular file to zero bytes during open. */
-    readonly truncate: Schema.optionalKey<Schema.Boolean>;
-    /** Follow the final symbolic link. Defaults to `true`. */
-    readonly followFinalSymlink: Schema.optionalKey<Schema.Boolean>;
-}>;
+export declare const OpenSettings: typeof VfsModel.OpenSettings;
 /**
  * Options for acquiring a scoped file handle.
  *
@@ -315,31 +244,13 @@ export declare const OpenSettings: Schema.Struct<{
  * @since 0.1.0
  */
 export type OpenOptions = typeof OpenSettings.Type & RelativeOptions;
-declare const WriteFileSettings: Schema.Struct<{
-    /** Permitted operations on the returned handle. */
-    readonly access: Schema.Literals<readonly ["read", "write", "readWrite"]>;
-    /** Creation policy. Defaults to `"never"`. */
-    readonly create: Schema.optionalKey<Schema.Literals<readonly ["never", "ifMissing", "exclusive"]>>;
-    /** Requested mode for a new file, before applying the caller's umask. */
-    readonly mode: Schema.optionalKey<Schema.Finite>;
-    /** Write at the current end of file regardless of the handle cursor. */
-    readonly append: Schema.optionalKey<Schema.Boolean>;
-    /** Truncate an existing regular file to zero bytes during open. */
-    readonly truncate: Schema.optionalKey<Schema.Boolean>;
-    /** Follow the final symbolic link. Defaults to `true`. */
-    readonly followFinalSymlink: Schema.optionalKey<Schema.Boolean>;
-    /** Replace the final symbolic link itself instead of its target. */
-    readonly replaceFinalSymlink: Schema.optionalKey<Schema.Boolean>;
-    /** Mode to apply after replacing an existing file. */
-    readonly finalMode: Schema.optionalKey<Schema.Finite>;
-}>;
 /**
  * Options for an atomic whole-file write, including replacement and final mode controls.
  *
  * @category models
  * @since 0.1.0
  */
-export type WriteFileOptions = typeof WriteFileSettings.Type & RelativeOptions;
+export type WriteFileOptions = VfsModel.WriteFileOptions;
 /**
  * A scoped regular-file capability with an independent bigint cursor.
  *
@@ -375,13 +286,25 @@ 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. */
+    readonly observeMetadata: (reference: ObjectReference) => Effect.Effect<ObjectObservation<Metadata>, FsError>;
+    /** Reads owned directory entries and their matching directory revision. */
+    readonly observeDirectory: (reference: ObjectReference) => Effect.Effect<ObjectObservation<ReadonlyArray<DirectoryEntry>>, FsError>;
+    /** Reads an owned symbolic-link target through a stable reference. */
+    readonly readLinkReference: (reference: ObjectReference) => Effect.Effect<Uint8Array, FsError>;
+    /** Opens a referenced regular file for reading. */
+    readonly openReference: (reference: ObjectReference) => Effect.Effect<FileHandle, FsError, Scope.Scope>;
     /** Reads metadata, following the final symbolic link by default. */
     readonly stat: (path: PathInput, options?: RelativeOptions) => Effect.Effect<Metadata, FsError>;
     /** Atomically moves an entry within this volume without replacing a non-empty directory. */
     readonly rename: (source: PathInput, destination: PathInput, options?: {
-        /** Base directory for a relative source path. */
         readonly sourceRelativeTo?: DirectoryHandle;
-        /** Base directory for a relative destination path. */
         readonly destinationRelativeTo?: DirectoryHandle;
     }) => Effect.Effect<void, FsError>;
     /** Reads and returns an owned copy of a regular file's complete contents. */
@@ -408,11 +331,8 @@ export interface Caller {
     readonly lstat: (path: PathInput, options?: RelativeOptions) => Effect.Effect<Metadata, FsError>;
     /** Creates a hard link to an existing non-directory entry. */
     readonly link: (source: PathInput, destination: PathInput, options?: {
-        /** Base directory for a relative source path. */
         readonly sourceRelativeTo?: DirectoryHandle;
-        /** Base directory for a relative destination path. */
         readonly destinationRelativeTo?: DirectoryHandle;
-        /** Link to the final symbolic link's target instead of the link itself. */
         readonly followSourceSymlink?: boolean;
     }) => Effect.Effect<void, FsError>;
     /** Creates a symbolic link. The target bytes are stored without resolving them. */
@@ -437,7 +357,6 @@ export interface Caller {
     readonly rmdir: (path: PathInput, options?: RelativeOptions) => Effect.Effect<void, FsError>;
     /** Creates one directory. Parent directories must already exist. */
     readonly mkdir: (path: PathInput, options?: RelativeOptions & {
-        /** Requested mode before applying the caller's umask. Defaults to `0o777`. */
         readonly mode?: number;
     }) => Effect.Effect<void, FsError>;
     /** Creates a scoped caller whose current directory is the resolved directory identity. */
@@ -463,7 +382,7 @@ export interface Change {
  * @category schemas
  * @since 0.1.0
  */
-export declare const OverlayNodeKind: Schema.Literals<readonly ["directory", "file", "symlink"]>;
+export declare const OverlayNodeKind: typeof VfsModel.OverlayNodeKind;
 /**
  * A filesystem entry kind reported by an overlay summary.
  *
@@ -477,7 +396,7 @@ export type OverlayNodeKind = typeof OverlayNodeKind.Type;
  * @category schemas
  * @since 0.1.0
  */
-export declare const OverlayDifference: Schema.Literals<readonly ["content", "mode", "uid", "gid", "atimeNs", "mtimeNs", "ctimeNs", "birthtimeNs"]>;
+export declare const OverlayDifference: typeof VfsModel.OverlayDifference;
 /**
  * A content, ownership, permission, or timestamp field that differs from the overlay base.
  *
@@ -496,27 +415,7 @@ export type OverlayDifference = typeof OverlayDifference.Type;
  * @category schemas
  * @since 0.1.0
  */
-export declare const OverlayChange: Schema.Union<readonly [Schema.TaggedStruct<"Added", {
-    readonly path: Schema.declare<BytePath, BytePath>;
-    readonly kind: Schema.Literals<readonly ["directory", "file", "symlink"]>;
-}>, Schema.TaggedStruct<"Removed", {
-    readonly path: Schema.declare<BytePath, BytePath>;
-    readonly kind: Schema.Literals<readonly ["directory", "file", "symlink"]>;
-}>, Schema.TaggedStruct<"Replaced", {
-    readonly path: Schema.declare<BytePath, BytePath>;
-    readonly beforeKind: Schema.Literals<readonly ["directory", "file", "symlink"]>;
-    readonly afterKind: Schema.Literals<readonly ["directory", "file", "symlink"]>;
-    readonly differences: Schema.$Array<Schema.Literals<readonly ["content", "mode", "uid", "gid", "atimeNs", "mtimeNs", "ctimeNs", "birthtimeNs"]>>;
-}>, Schema.TaggedStruct<"Renamed", {
-    readonly from: Schema.declare<BytePath, BytePath>;
-    readonly to: Schema.declare<BytePath, BytePath>;
-    readonly kind: Schema.Literals<readonly ["directory", "file", "symlink"]>;
-    readonly differences: Schema.$Array<Schema.Literals<readonly ["content", "mode", "uid", "gid", "atimeNs", "mtimeNs", "ctimeNs", "birthtimeNs"]>>;
-}>, Schema.TaggedStruct<"Updated", {
-    readonly path: Schema.declare<BytePath, BytePath>;
-    readonly kind: Schema.Literals<readonly ["directory", "file", "symlink"]>;
-    readonly differences: Schema.$Array<Schema.Literals<readonly ["content", "mode", "uid", "gid", "atimeNs", "mtimeNs", "ctimeNs", "birthtimeNs"]>>;
-}>]>;
+export declare const OverlayChange: typeof VfsModel.OverlayChange;
 /**
  * A path-oriented final-state difference from an overlay's immutable base.
  *
@@ -530,10 +429,7 @@ export type OverlayChange = typeof OverlayChange.Type;
  * @category schemas
  * @since 0.1.0
  */
-export declare const OverlayChangesOptions: Schema.Struct<{
-    /** Include access, modification, change, and birth-time differences. Defaults to `false`. */
-    readonly includeTimestamps: Schema.optionalKey<Schema.Boolean>;
-}>;
+export declare const OverlayChangesOptions: typeof VfsModel.OverlayChangesOptions;
 /**
  * Filtering options for an overlay final-difference summary.
  *
@@ -580,15 +476,15 @@ export interface OverlayVolume extends Volume {
     /** Captures one committed state when this reusable effect executes. */
     readonly capture: (options?: OverlayChangesOptions) => Effect.Effect<OverlayCapture, ConfigurationError | ImageError>;
 }
-declare const CurrentFileSystem_base: Context.ServiceClass<CurrentFileSystem, "@effect-vfs/core/CurrentFileSystem", Caller>;
 /**
  * Optional Effect service for providing an existing filesystem caller.
  *
  * @category services
  * @since 0.1.0
  */
-export declare class CurrentFileSystem extends CurrentFileSystem_base {
-}
+export declare const CurrentFileSystem: typeof VfsModel.CurrentFileSystem;
+/** @internal */
+export type CurrentFileSystem = VfsModel.CurrentFileSystem;
 /**
  * Encodes a snapshot as owned UTF-8 JSON bytes using the version 1 snapshot format.
  *
@@ -603,6 +499,87 @@ export declare const encodeSnapshot: (snapshot: Snapshot) => Effect.Effect<Uint8
  * @since 0.1.0
  */
 export declare const decodeSnapshot: (input: Uint8Array, limits: DecodeLimits) => Effect.Effect<Snapshot, ImageError>;
+/**
+ * Computes an exact portable delta between two immutable snapshots.
+ * Requires the platform-neutral `Crypto.Crypto` service for base identity.
+ *
+ * @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>;
+/**
+ * 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.
+ *
+ * @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>;
+/**
+ * Applies an exact delta to its semantically matching base and returns a new snapshot.
+ * Requires the platform-neutral `Crypto.Crypto` service for base identity.
+ *
+ * @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>;
+/**
+ * Creates an Effect Schema codec between owned bytes and opaque snapshot deltas.
+ * Omission uses `SnapshotDeltaLimits.default`.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const SnapshotDeltaFromBytes: (limits?: SnapshotDeltaModel.SnapshotDeltaLimits) => Schema.decodeTo<Schema.declare<SnapshotDeltaModel.SnapshotDelta, SnapshotDeltaModel.SnapshotDelta>, Schema.Uint8Array, never, never>;
 /**
  * Creates an opaque byte path by copying the input when the Effect executes.
  *
@@ -613,14 +590,32 @@ export declare const decodeSnapshot: (input: Uint8Array, limits: DecodeLimits) =
  * @category constructors
  * @since 0.1.0
  */
-export declare const pathFromBytes: (bytes: Uint8Array<ArrayBufferLike>) => Effect.Effect<BytePath, FsError, never>;
+export declare const pathFromBytes: (bytes: Uint8Array) => Effect.Effect<BytePath, FsError>;
 /**
  * Copies the bytes held by an opaque byte path.
  *
  * @category getters
  * @since 0.1.0
  */
-export declare const pathToBytes: (path: BytePath) => Effect.Effect<Uint8Array<ArrayBuffer>, FsError, never>;
+export declare const pathToBytes: (path: BytePath) => Effect.Effect<Uint8Array, FsError>;
+/**
+ * Schema for a complete fixture namespace with optional metadata and forward hard links.
+ *
+ * **Details**
+ *
+ * Fixture paths must be absolute, unique, and explicitly include their parent directories.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const Fixture: typeof VfsModel.Fixture;
+/**
+ * A complete filesystem fixture accepted by `fromFixture`.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Fixture = typeof Fixture.Type;
 /**
  * Creates a fresh empty volume and captures the current Effect `Clock`.
  *
@@ -632,24 +627,14 @@ export declare const pathToBytes: (path: BytePath) => Effect.Effect<Uint8Array<A
  * @category constructors
  * @since 0.1.0
  */
-export declare const make: (options?: {
-    readonly maxEntries?: number;
-    readonly maxBytes?: number;
-    readonly maxFileBytes?: number;
-    readonly maxPathBytes?: number;
-} | undefined) => Effect.Effect<Volume, ConfigurationError, never>;
+export declare const make: (options?: VolumeOptions) => Effect.Effect<Volume, ConfigurationError>;
 /**
  * Restores a fresh volume from an opaque snapshot under the supplied destination limits.
  *
  * @category constructors
  * @since 0.1.0
  */
-export declare const fromSnapshot: (snapshot: Snapshot, options?: {
-    readonly maxEntries?: number;
-    readonly maxBytes?: number;
-    readonly maxFileBytes?: number;
-    readonly maxPathBytes?: number;
-} | undefined) => Effect.Effect<Volume, ConfigurationError | ImageError, never>;
+export declare const fromSnapshot: (snapshot: Snapshot, options?: VolumeOptions) => Effect.Effect<Volume, ConfigurationError | ImageError>;
 /**
  * Creates an isolated writable volume relative to one immutable snapshot base.
  *
@@ -666,146 +651,12 @@ export declare const fromSnapshot: (snapshot: Snapshot, options?: {
  * @category constructors
  * @since 0.1.0
  */
-export declare const makeOverlay: (base: Snapshot, options?: {
-    readonly maxEntries?: number;
-    readonly maxBytes?: number;
-    readonly maxFileBytes?: number;
-    readonly maxPathBytes?: number;
-} | undefined) => Effect.Effect<OverlayVolume, ConfigurationError | ImageError, never>;
-/**
- * Schema for a complete fixture namespace with optional metadata and forward hard links.
- *
- * **Details**
- *
- * Fixture paths must be absolute, unique, and explicitly include their parent directories.
- *
- * @category schemas
- * @since 0.1.0
- */
-export declare const Fixture: Schema.Struct<{
-    readonly rootMetadata: Schema.optionalKey<Schema.Struct<{
-        readonly uid: Schema.optionalKey<Schema.Finite>;
-        readonly gid: Schema.optionalKey<Schema.Finite>;
-        readonly mode: Schema.optionalKey<Schema.Finite>;
-        readonly atimeNs: Schema.optionalKey<Schema.BigInt>;
-        readonly mtimeNs: Schema.optionalKey<Schema.BigInt>;
-        readonly ctimeNs: Schema.optionalKey<Schema.BigInt>;
-        readonly birthtimeNs: Schema.optionalKey<Schema.BigInt>;
-    }>>;
-    readonly entries: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
-        readonly kind: Schema.Literal<"directory">;
-        readonly path: Schema.Union<readonly [Schema.String, Schema.declare<BytePath, BytePath>]>;
-        readonly metadata: Schema.optionalKey<Schema.Struct<{
-            readonly uid: Schema.optionalKey<Schema.Finite>;
-            readonly gid: Schema.optionalKey<Schema.Finite>;
-            readonly mode: Schema.optionalKey<Schema.Finite>;
-            readonly atimeNs: Schema.optionalKey<Schema.BigInt>;
-            readonly mtimeNs: Schema.optionalKey<Schema.BigInt>;
-            readonly ctimeNs: Schema.optionalKey<Schema.BigInt>;
-            readonly birthtimeNs: Schema.optionalKey<Schema.BigInt>;
-        }>>;
-    }>, Schema.Struct<{
-        readonly kind: Schema.Literal<"file">;
-        readonly path: Schema.Union<readonly [Schema.String, Schema.declare<BytePath, BytePath>]>;
-        readonly bytes: Schema.Uint8Array;
-        readonly metadata: Schema.optionalKey<Schema.Struct<{
-            readonly uid: Schema.optionalKey<Schema.Finite>;
-            readonly gid: Schema.optionalKey<Schema.Finite>;
-            readonly mode: Schema.optionalKey<Schema.Finite>;
-            readonly atimeNs: Schema.optionalKey<Schema.BigInt>;
-            readonly mtimeNs: Schema.optionalKey<Schema.BigInt>;
-            readonly ctimeNs: Schema.optionalKey<Schema.BigInt>;
-            readonly birthtimeNs: Schema.optionalKey<Schema.BigInt>;
-        }>>;
-    }>, Schema.Struct<{
-        readonly kind: Schema.Literal<"symlink">;
-        readonly path: Schema.Union<readonly [Schema.String, Schema.declare<BytePath, BytePath>]>;
-        readonly target: Schema.Union<readonly [Schema.String, Schema.declare<BytePath, BytePath>]>;
-        readonly metadata: Schema.optionalKey<Schema.Struct<{
-            readonly uid: Schema.optionalKey<Schema.Finite>;
-            readonly gid: Schema.optionalKey<Schema.Finite>;
-            readonly mode: Schema.optionalKey<Schema.Finite>;
-            readonly atimeNs: Schema.optionalKey<Schema.BigInt>;
-            readonly mtimeNs: Schema.optionalKey<Schema.BigInt>;
-            readonly ctimeNs: Schema.optionalKey<Schema.BigInt>;
-            readonly birthtimeNs: Schema.optionalKey<Schema.BigInt>;
-        }>>;
-    }>, Schema.Struct<{
-        readonly kind: Schema.Literal<"hardLink">;
-        readonly path: Schema.Union<readonly [Schema.String, Schema.declare<BytePath, BytePath>]>;
-        readonly target: Schema.Union<readonly [Schema.String, Schema.declare<BytePath, BytePath>]>;
-    }>]>>;
-}>;
-/**
- * A complete filesystem fixture accepted by `fromFixture`.
- *
- * @category models
- * @since 0.1.0
- */
-export type Fixture = typeof Fixture.Type;
+export declare const makeOverlay: (base: Snapshot, options?: VolumeOptions) => Effect.Effect<OverlayVolume, ConfigurationError | ImageError>;
 /**
  * Builds a fresh volume from a validated final-state fixture.
  *
  * @category constructors
  * @since 0.1.0
  */
-export declare const fromFixture: (fixture: {
-    readonly rootMetadata?: {
-        readonly uid?: number;
-        readonly gid?: number;
-        readonly mode?: number;
-        readonly atimeNs?: bigint;
-        readonly mtimeNs?: bigint;
-        readonly ctimeNs?: bigint;
-        readonly birthtimeNs?: bigint;
-    };
-    readonly entries: readonly ({
-        readonly kind: "directory";
-        readonly path: string | BytePath;
-        readonly metadata?: {
-            readonly uid?: number;
-            readonly gid?: number;
-            readonly mode?: number;
-            readonly atimeNs?: bigint;
-            readonly mtimeNs?: bigint;
-            readonly ctimeNs?: bigint;
-            readonly birthtimeNs?: bigint;
-        };
-    } | {
-        readonly kind: "file";
-        readonly path: string | BytePath;
-        readonly bytes: Uint8Array<ArrayBufferLike>;
-        readonly metadata?: {
-            readonly uid?: number;
-            readonly gid?: number;
-            readonly mode?: number;
-            readonly atimeNs?: bigint;
-            readonly mtimeNs?: bigint;
-            readonly ctimeNs?: bigint;
-            readonly birthtimeNs?: bigint;
-        };
-    } | {
-        readonly kind: "symlink";
-        readonly path: string | BytePath;
-        readonly target: string | BytePath;
-        readonly metadata?: {
-            readonly uid?: number;
-            readonly gid?: number;
-            readonly mode?: number;
-            readonly atimeNs?: bigint;
-            readonly mtimeNs?: bigint;
-            readonly ctimeNs?: bigint;
-            readonly birthtimeNs?: bigint;
-        };
-    } | {
-        readonly kind: "hardLink";
-        readonly path: string | BytePath;
-        readonly target: string | BytePath;
-    })[];
-}, options?: {
-    readonly maxEntries?: number;
-    readonly maxBytes?: number;
-    readonly maxFileBytes?: number;
-    readonly maxPathBytes?: number;
-} | undefined) => Effect.Effect<Volume, ConfigurationError | ImageError, never>;
+export declare const fromFixture: (fixture: Fixture, options?: VolumeOptions) => Effect.Effect<Volume, ConfigurationError | ImageError>;
 //# sourceMappingURL=VirtualFileSystem.d.ts.map