@effect-vfs/core 0.0.1

package/dist/VirtualFileSystem.d.ts

@@ -0,0 +1,674 @@
+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.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface BytePath {
+    readonly [BytePathId]: true;
+}
+/**
+ * A UTF-8 string path or an opaque byte-preserving path.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type PathInput = string | BytePath;
+/**
+ * Schema for portable virtual filesystem error codes.
+ *
+ * @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"]>;
+/**
+ * A portable virtual filesystem error code.
+ *
+ * @category models
+ * @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;
+}> {
+}
+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;
+}> {
+}
+/**
+ * Schema for a caller's numeric identity, supplementary groups, and explicit privilege.
+ *
+ * @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;
+}>;
+/**
+ * A caller identity used for permission checks.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Identity = typeof Identity.Type;
+/**
+ * Schema for root caller credentials and creation mask.
+ *
+ * @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>;
+}>;
+/**
+ * Options for creating a root caller on a volume.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type RootCallerOptions = typeof RootCallerOptions.Type;
+/**
+ * Schema for optional volume capacity and path limits.
+ *
+ * @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>;
+}>;
+/**
+ * Capacity and path limits for a volume.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type VolumeOptions = typeof VolumeOptions.Type;
+/**
+ * Schema for filesystem node metadata with bigint inode, size, and nanosecond fields.
+ *
+ * @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;
+}>;
+/**
+ * Metadata for a directory, regular file, or symbolic link.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Metadata = typeof Metadata.Type;
+/**
+ * Resolves a relative path from a live directory handle instead of the caller's directory.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface RelativeOptions {
+    /** Resolve relative paths from this live, same-volume handle instead of the caller's current directory. */
+    readonly relativeTo?: DirectoryHandle;
+}
+/**
+ * Controls the base directory and whether metadata operations follow the final symbolic link.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface MetadataOptions extends RelativeOptions {
+    /** Follow the final symbolic link. Defaults to `true`. */
+    readonly followFinalSymlink?: boolean;
+}
+/**
+ * Schema for an owner update. Omitted fields retain their existing values.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const OwnerUpdate: Schema.Struct<{
+    readonly uid: Schema.optionalKey<Schema.Finite>;
+    readonly gid: Schema.optionalKey<Schema.Finite>;
+}>;
+/**
+ * An owner update for `chown` operations.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type OwnerUpdate = typeof OwnerUpdate.Type;
+/**
+ * Schema for setting a timestamp to the clock, retaining it, or supplying nanoseconds.
+ *
+ * @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;
+}>]>;
+/**
+ * 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;
+    }>]>;
+}>;
+/**
+ * Access and modification time updates for `utimes` operations.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Times = typeof Times.Type;
+/**
+ * A scoped directory capability that can be used for metadata and relative lookup.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface DirectoryHandle {
+    readonly [DirectoryHandleId]: true;
+    /** Reads metadata for the directory while the handle remains open. */
+    readonly stat: Effect.Effect<Metadata, FsError>;
+    /** Closes the handle. A repeated explicit close fails; scope cleanup remains safe. */
+    readonly close: Effect.Effect<void, FsError>;
+}
+/**
+ * Schema for file seek origins, including dense-file data and hole queries.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const SeekMode: Schema.Literals<readonly ["start", "current", "end", "data", "hole"]>;
+/**
+ * The origin used by a file handle seek operation.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type SeekMode = typeof SeekMode.Type;
+/**
+ * Schema for file access, creation, append, truncate, and symlink behavior.
+ *
+ * @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>;
+}>;
+/**
+ * Options for acquiring a scoped file handle.
+ *
+ * @category models
+ * @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;
+/**
+ * A scoped regular-file capability with an independent bigint cursor.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface FileHandle {
+    readonly [FileHandleId]: true;
+    /** Reads up to `maximumBytes` from the cursor and advances it by the returned length. */
+    readonly read: (maximumBytes: number) => Effect.Effect<Uint8Array, FsError>;
+    /** Reads at `offset` without changing the cursor. */
+    readonly pread: (maximumBytes: number, offset: bigint) => Effect.Effect<Uint8Array, FsError>;
+    /** Writes at the cursor and advances it, or writes at end of file when opened for append. */
+    readonly write: (bytes: Uint8Array) => Effect.Effect<number, FsError>;
+    /** Writes at `offset` without changing the cursor. Append mode does not affect positional writes. */
+    readonly pwrite: (bytes: Uint8Array, offset: bigint) => Effect.Effect<number, FsError>;
+    /** Moves the cursor and returns its new offset. `data` finds content and `hole` finds end of file. */
+    readonly seek: (offset: bigint, mode: SeekMode) => Effect.Effect<bigint, FsError>;
+    /** Sets the file length without changing the cursor. */
+    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. */
+    readonly sync: Effect.Effect<void, FsError>;
+    /** Closes the handle. A repeated explicit close fails; scope cleanup remains safe. */
+    readonly close: Effect.Effect<void, FsError>;
+}
+/**
+ * A filesystem caller with its own identity, creation mask, and current directory.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Caller {
+    readonly [CallerId]: true;
+    /** 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. */
+    readonly readFile: (path: PathInput, options?: RelativeOptions) => Effect.Effect<Uint8Array, FsError>;
+    /** Atomically writes a complete regular file according to the replacement options. */
+    readonly writeFile: (path: PathInput, bytes: Uint8Array, options: WriteFileOptions) => Effect.Effect<void, FsError>;
+    /** Checks the requested permission bits without opening the entry. */
+    readonly access: (path: PathInput, bits?: number, options?: RelativeOptions) => Effect.Effect<void, FsError>;
+    /** Sets a regular file's length. Extending creates a zero-filled region. */
+    readonly truncate: (path: PathInput, length: bigint, options?: RelativeOptions) => Effect.Effect<void, FsError>;
+    /** Changes permission bits, following the final symbolic link by default. */
+    readonly chmod: (path: PathInput, mode: number, options?: MetadataOptions) => Effect.Effect<void, FsError>;
+    /** Changes uid, gid, or both, following the final symbolic link by default. */
+    readonly chown: (path: PathInput, owner: OwnerUpdate, options?: MetadataOptions) => Effect.Effect<void, FsError>;
+    /** Updates access and modification times, following the final symbolic link by default. */
+    readonly utimes: (path: PathInput, times: Times, options?: MetadataOptions) => Effect.Effect<void, FsError>;
+    /** Changes permission bits through a live, same-volume handle. */
+    readonly chmodHandle: (handle: FileHandle | DirectoryHandle, mode: number) => Effect.Effect<void, FsError>;
+    /** Changes uid, gid, or both through a live, same-volume handle. */
+    readonly chownHandle: (handle: FileHandle | DirectoryHandle, owner: OwnerUpdate) => Effect.Effect<void, FsError>;
+    /** Updates access and modification times through a live, same-volume handle. */
+    readonly utimesHandle: (handle: FileHandle | DirectoryHandle, times: Times) => Effect.Effect<void, FsError>;
+    /** Reads metadata without following the final symbolic link. */
+    readonly lstat: (path: PathInput, options?: RelativeOptions) => Effect.Effect<Metadata, FsError>;
+    /** Creates a hard link to an existing non-directory entry. */
+    readonly link: (source: PathInput, destination: PathInput, options?: {
+        /** Base directory for a relative source path. */
+        readonly sourceRelativeTo?: DirectoryHandle;
+        /** Base directory for a relative destination path. */
+        readonly destinationRelativeTo?: DirectoryHandle;
+        /** Link to the final symbolic link's target instead of the link itself. */
+        readonly followSourceSymlink?: boolean;
+    }) => Effect.Effect<void, FsError>;
+    /** Creates a symbolic link. The target bytes are stored without resolving them. */
+    readonly symlink: (target: PathInput, path: PathInput, options?: RelativeOptions) => Effect.Effect<void, FsError>;
+    /** Reads a symbolic-link target as UTF-8, failing with `UnrepresentableName` for other bytes. */
+    readonly readLink: (path: PathInput, options?: RelativeOptions) => Effect.Effect<string, FsError>;
+    /** Reads a symbolic-link target as owned bytes. */
+    readonly readLinkBytes: (path: PathInput, options?: RelativeOptions) => Effect.Effect<Uint8Array, FsError>;
+    /** Reads directory names as UTF-8, failing if any name is not representable. */
+    readonly readDirectory: (path: PathInput, options?: RelativeOptions) => Effect.Effect<ReadonlyArray<string>, FsError>;
+    /** Reads directory names as owned byte arrays. */
+    readonly readDirectoryBytes: (path: PathInput, options?: RelativeOptions) => Effect.Effect<ReadonlyArray<Uint8Array>, FsError>;
+    /** Resolves links and normalizes a path as UTF-8. */
+    readonly realPath: (path: PathInput, options?: RelativeOptions) => Effect.Effect<string, FsError>;
+    /** Resolves links and normalizes a path without requiring UTF-8 names. */
+    readonly realPathBytes: (path: PathInput, options?: RelativeOptions) => Effect.Effect<BytePath, FsError>;
+    /** Opens a scoped regular-file handle. The surrounding scope closes it automatically. */
+    readonly open: (path: PathInput, options: OpenOptions) => Effect.Effect<FileHandle, FsError, Scope.Scope>;
+    /** Removes a non-directory entry. Open handles remain usable until closed. */
+    readonly unlink: (path: PathInput, options?: RelativeOptions) => Effect.Effect<void, FsError>;
+    /** Removes an empty directory. */
+    readonly rmdir: (path: PathInput, options?: RelativeOptions) => Effect.Effect<void, FsError>;
+    /** Creates one directory. Parent directories must already exist. */
+    readonly mkdir: (path: PathInput, options?: RelativeOptions & {
+        /** 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. */
+    readonly withDirectory: (path: PathInput, options?: RelativeOptions) => Effect.Effect<Caller, FsError, Scope.Scope>;
+    /** Opens a scoped directory handle for metadata and relative path resolution. */
+    readonly openDirectory: (path: PathInput, options?: RelativeOptions) => Effect.Effect<DirectoryHandle, FsError, Scope.Scope>;
+}
+/**
+ * A committed namespace or content change emitted by a volume watch stream.
+ *
+ * @category models
+ * @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. */
+    readonly path: BytePath;
+}
+/**
+ * An isolated virtual filesystem namespace that creates callers, snapshots, and watch streams.
+ *
+ * @category models
+ * @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>;
+    /** Captures an isolated snapshot of the reachable namespace and metadata. */
+    readonly snapshot: Effect.Effect<Snapshot, ImageError>;
+    readonly [VolumeId]: true;
+    /** Creates a caller rooted at `/` with independent credentials, umask, and current directory. */
+    readonly caller: (options?: RootCallerOptions) => Effect.Effect<Caller, ConfigurationError>;
+}
+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 {
+}
+/**
+ * Encodes a snapshot as owned UTF-8 JSON bytes using the version 1 snapshot format.
+ *
+ * @category serialization
+ * @since 0.1.0
+ */
+export declare const encodeSnapshot: (snapshot: Snapshot) => Effect.Effect<Uint8Array, ImageError>;
+/**
+ * Decodes version 1 snapshot bytes while enforcing explicit input and payload limits.
+ *
+ * @category serialization
+ * @since 0.1.0
+ */
+export declare const decodeSnapshot: (input: Uint8Array, limits: DecodeLimits) => Effect.Effect<Snapshot, ImageError>;
+/**
+ * Creates an opaque byte path by copying the input when the Effect executes.
+ *
+ * **Gotchas**
+ *
+ * Shared-memory-backed and detached views fail with `InvalidArgument`.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const pathFromBytes: (bytes: Uint8Array<ArrayBufferLike>) => Effect.Effect<BytePath, FsError, never>;
+/**
+ * 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>;
+/**
+ * Creates a fresh empty volume and captures the current Effect `Clock`.
+ *
+ * **Details**
+ *
+ * Each execution creates independent storage. Snapshot image failures cannot
+ * arise because this constructor does not accept persisted input.
+ *
+ * @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>;
+/**
+ * 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>;
+/**
+ * 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;
+/**
+ * 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>;
+//# sourceMappingURL=VirtualFileSystem.d.ts.map