@effect-vfs/core 0.3.1 → 0.4.0

package/dist/internal/liveImage.d.ts

@@ -0,0 +1,286 @@
+import * as ByteSize from "effect/ByteSize";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { ImageError } from "../Snapshot.js";
+/** @internal */
+export declare const Record: Schema.TaggedUnion<{
+    readonly directory: Schema.TaggedStruct<"directory", {
+        readonly ino: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+        readonly revision: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+        readonly lineage: Schema.optionalKey<Schema.String>;
+        readonly metadata: Schema.Struct<{
+            readonly uid: Schema.Natural;
+            readonly gid: Schema.Natural;
+            readonly mode: Schema.Natural;
+            readonly atimeNs: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+            readonly mtimeNs: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+            readonly ctimeNs: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+            readonly birthtimeNs: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+            readonly nlink: Schema.Natural;
+            readonly size: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+        }>;
+        readonly entries: Schema.$Array<Schema.Struct<{
+            readonly name: Schema.brand<Schema.refine<string, Schema.String>, "CanonicalBase64">;
+            readonly target: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+        }>>;
+    }>;
+    readonly file: Schema.TaggedStruct<"file", {
+        readonly ino: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+        readonly revision: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+        readonly lineage: Schema.optionalKey<Schema.String>;
+        readonly metadata: Schema.Struct<{
+            readonly uid: Schema.Natural;
+            readonly gid: Schema.Natural;
+            readonly mode: Schema.Natural;
+            readonly atimeNs: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+            readonly mtimeNs: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+            readonly ctimeNs: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+            readonly birthtimeNs: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+            readonly nlink: Schema.Natural;
+            readonly size: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+        }>;
+        readonly data: Schema.brand<Schema.refine<string, Schema.String>, "CanonicalBase64">;
+    }>;
+    readonly symlink: Schema.TaggedStruct<"symlink", {
+        readonly ino: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+        readonly revision: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+        readonly lineage: Schema.optionalKey<Schema.String>;
+        readonly metadata: Schema.Struct<{
+            readonly uid: Schema.Natural;
+            readonly gid: Schema.Natural;
+            readonly mode: Schema.Natural;
+            readonly atimeNs: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+            readonly mtimeNs: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+            readonly ctimeNs: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+            readonly birthtimeNs: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+            readonly nlink: Schema.Natural;
+            readonly size: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+        }>;
+        readonly target: Schema.brand<Schema.refine<string, Schema.String>, "CanonicalBase64">;
+    }>;
+}>;
+/** @internal */
+export type Record = typeof Record.Type;
+/** @internal */
+export declare const Document: Schema.Struct<{
+    readonly format: Schema.Literal<"effect-vfs-live">;
+    readonly version: Schema.Literal<1>;
+    readonly identity: Schema.String;
+    readonly root: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+    readonly nextInode: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+    readonly revisionCounter: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+    readonly entries: Schema.Natural;
+    readonly usedBytes: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+    readonly limits: Schema.Struct<{
+        readonly maxEntries: Schema.optionalKey<Schema.Natural>;
+        readonly maxBytes: Schema.optionalKey<Schema.decodeTo<Schema.BigInt, Schema.String, never, never>>;
+        readonly maxFileBytes: Schema.optionalKey<Schema.decodeTo<Schema.BigInt, Schema.String, never, never>>;
+        readonly maxPathBytes: Schema.optionalKey<Schema.decodeTo<Schema.BigInt, Schema.String, never, never>>;
+    }>;
+    readonly retainedFiles: Schema.$Array<Schema.decodeTo<Schema.BigInt, Schema.String, never, never>>;
+    readonly records: Schema.$Array<Schema.TaggedUnion<{
+        readonly directory: Schema.TaggedStruct<"directory", {
+            readonly ino: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+            readonly revision: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+            readonly lineage: Schema.optionalKey<Schema.String>;
+            readonly metadata: Schema.Struct<{
+                readonly uid: Schema.Natural;
+                readonly gid: Schema.Natural;
+                readonly mode: Schema.Natural;
+                readonly atimeNs: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+                readonly mtimeNs: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+                readonly ctimeNs: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+                readonly birthtimeNs: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+                readonly nlink: Schema.Natural;
+                readonly size: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+            }>;
+            readonly entries: Schema.$Array<Schema.Struct<{
+                readonly name: Schema.brand<Schema.refine<string, Schema.String>, "CanonicalBase64">;
+                readonly target: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+            }>>;
+        }>;
+        readonly file: Schema.TaggedStruct<"file", {
+            readonly ino: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+            readonly revision: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+            readonly lineage: Schema.optionalKey<Schema.String>;
+            readonly metadata: Schema.Struct<{
+                readonly uid: Schema.Natural;
+                readonly gid: Schema.Natural;
+                readonly mode: Schema.Natural;
+                readonly atimeNs: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+                readonly mtimeNs: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+                readonly ctimeNs: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+                readonly birthtimeNs: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+                readonly nlink: Schema.Natural;
+                readonly size: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+            }>;
+            readonly data: Schema.brand<Schema.refine<string, Schema.String>, "CanonicalBase64">;
+        }>;
+        readonly symlink: Schema.TaggedStruct<"symlink", {
+            readonly ino: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+            readonly revision: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+            readonly lineage: Schema.optionalKey<Schema.String>;
+            readonly metadata: Schema.Struct<{
+                readonly uid: Schema.Natural;
+                readonly gid: Schema.Natural;
+                readonly mode: Schema.Natural;
+                readonly atimeNs: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+                readonly mtimeNs: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+                readonly ctimeNs: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+                readonly birthtimeNs: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+                readonly nlink: Schema.Natural;
+                readonly size: Schema.decodeTo<Schema.BigInt, Schema.String, never, never>;
+            }>;
+            readonly target: Schema.brand<Schema.refine<string, Schema.String>, "CanonicalBase64">;
+        }>;
+    }>>;
+}>;
+/** @internal */
+export type Document = typeof Document.Type;
+/** @internal */
+export declare const encode: (document: {
+    readonly format: "effect-vfs-live";
+    readonly version: 1;
+    readonly identity: string;
+    readonly root: bigint;
+    readonly nextInode: bigint;
+    readonly revisionCounter: bigint;
+    readonly entries: number;
+    readonly usedBytes: bigint;
+    readonly limits: {
+        readonly maxEntries?: number;
+        readonly maxBytes?: bigint;
+        readonly maxFileBytes?: bigint;
+        readonly maxPathBytes?: bigint;
+    };
+    readonly retainedFiles: readonly bigint[];
+    readonly records: readonly ({
+        readonly _tag: "directory";
+        readonly ino: bigint;
+        readonly revision: bigint;
+        readonly lineage?: string;
+        readonly metadata: {
+            readonly uid: number;
+            readonly gid: number;
+            readonly mode: number;
+            readonly atimeNs: bigint;
+            readonly mtimeNs: bigint;
+            readonly ctimeNs: bigint;
+            readonly birthtimeNs: bigint;
+            readonly nlink: number;
+            readonly size: bigint;
+        };
+        readonly entries: readonly {
+            readonly name: string & import("effect/Brand").Brand<"CanonicalBase64">;
+            readonly target: bigint;
+        }[];
+    } | {
+        readonly _tag: "file";
+        readonly ino: bigint;
+        readonly revision: bigint;
+        readonly lineage?: string;
+        readonly metadata: {
+            readonly uid: number;
+            readonly gid: number;
+            readonly mode: number;
+            readonly atimeNs: bigint;
+            readonly mtimeNs: bigint;
+            readonly ctimeNs: bigint;
+            readonly birthtimeNs: bigint;
+            readonly nlink: number;
+            readonly size: bigint;
+        };
+        readonly data: string & import("effect/Brand").Brand<"CanonicalBase64">;
+    } | {
+        readonly _tag: "symlink";
+        readonly ino: bigint;
+        readonly revision: bigint;
+        readonly lineage?: string;
+        readonly metadata: {
+            readonly uid: number;
+            readonly gid: number;
+            readonly mode: number;
+            readonly atimeNs: bigint;
+            readonly mtimeNs: bigint;
+            readonly ctimeNs: bigint;
+            readonly birthtimeNs: bigint;
+            readonly nlink: number;
+            readonly size: bigint;
+        };
+        readonly target: string & import("effect/Brand").Brand<"CanonicalBase64">;
+    })[];
+}) => Effect.Effect<Uint8Array<ArrayBuffer>, ImageError, never>;
+/** @internal */
+export declare const decode: (bytes: Uint8Array<ArrayBufferLike>, maxEncodedBytes: ByteSize.ByteSize) => Effect.Effect<{
+    readonly format: "effect-vfs-live";
+    readonly version: 1;
+    readonly identity: string;
+    readonly root: bigint;
+    readonly nextInode: bigint;
+    readonly revisionCounter: bigint;
+    readonly entries: number;
+    readonly usedBytes: bigint;
+    readonly limits: {
+        readonly maxEntries?: number;
+        readonly maxBytes?: bigint;
+        readonly maxFileBytes?: bigint;
+        readonly maxPathBytes?: bigint;
+    };
+    readonly retainedFiles: readonly bigint[];
+    readonly records: readonly ({
+        readonly _tag: "directory";
+        readonly ino: bigint;
+        readonly revision: bigint;
+        readonly lineage?: string;
+        readonly metadata: {
+            readonly uid: number;
+            readonly gid: number;
+            readonly mode: number;
+            readonly atimeNs: bigint;
+            readonly mtimeNs: bigint;
+            readonly ctimeNs: bigint;
+            readonly birthtimeNs: bigint;
+            readonly nlink: number;
+            readonly size: bigint;
+        };
+        readonly entries: readonly {
+            readonly name: string & import("effect/Brand").Brand<"CanonicalBase64">;
+            readonly target: bigint;
+        }[];
+    } | {
+        readonly _tag: "file";
+        readonly ino: bigint;
+        readonly revision: bigint;
+        readonly lineage?: string;
+        readonly metadata: {
+            readonly uid: number;
+            readonly gid: number;
+            readonly mode: number;
+            readonly atimeNs: bigint;
+            readonly mtimeNs: bigint;
+            readonly ctimeNs: bigint;
+            readonly birthtimeNs: bigint;
+            readonly nlink: number;
+            readonly size: bigint;
+        };
+        readonly data: string & import("effect/Brand").Brand<"CanonicalBase64">;
+    } | {
+        readonly _tag: "symlink";
+        readonly ino: bigint;
+        readonly revision: bigint;
+        readonly lineage?: string;
+        readonly metadata: {
+            readonly uid: number;
+            readonly gid: number;
+            readonly mode: number;
+            readonly atimeNs: bigint;
+            readonly mtimeNs: bigint;
+            readonly ctimeNs: bigint;
+            readonly birthtimeNs: bigint;
+            readonly nlink: number;
+            readonly size: bigint;
+        };
+        readonly target: string & import("effect/Brand").Brand<"CanonicalBase64">;
+    })[];
+}, ImageError, never>;
+//# sourceMappingURL=liveImage.d.ts.map

package/dist/internal/liveImage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"liveImage.d.ts","sourceRoot":"","sources":["../../src/internal/liveImage.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAmB3C,gBAAgB;AAChB,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAOjB,CAAA;AAEF,gBAAgB;AAChB,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAA;AAEvC,gBAAgB;AAChB,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiBnB,CAAA;AAEF,gBAAgB;AAChB,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAA;AAgI3C,gBAAgB;AAChB,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+DAMjB,CAAA;AAEF,gBAAgB;AAChB,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAuBjB,CAAA"}

package/dist/internal/liveImage.js

@@ -0,0 +1,176 @@
+// Private, versioned image for a live volume. Unlike a public snapshot, this
+// retains inode numbers, revisions, allocator state, and open unlinked files.
+import * as ByteSize from "effect/ByteSize";
+import * as Effect from "effect/Effect";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import * as SchemaTransformation from "effect/SchemaTransformation";
+import { ImageError } from "../Snapshot.js";
+import { CanonicalBase64 } from "./canonicalBase64.js";
+import { StoredMetadata } from "./metadata.js";
+const NaturalBigInt = Schema.String.check(Schema.isPattern(/^(0|[1-9][0-9]{0,127})$/)).pipe(Schema.decodeTo(Schema.BigInt, SchemaTransformation.bigintFromString));
+const Common = {
+    ino: NaturalBigInt,
+    revision: NaturalBigInt,
+    lineage: Schema.optionalKey(Schema.String),
+    metadata: Schema.Struct({
+        ...StoredMetadata.fields,
+        nlink: Schema.Natural,
+        size: NaturalBigInt
+    })
+};
+/** @internal */
+export const Record = Schema.TaggedUnion({
+    directory: {
+        ...Common,
+        entries: Schema.Array(Schema.Struct({ name: CanonicalBase64.Encoded, target: NaturalBigInt }))
+    },
+    file: { ...Common, data: CanonicalBase64.Encoded },
+    symlink: { ...Common, target: CanonicalBase64.Encoded }
+});
+/** @internal */
+export const Document = Schema.Struct({
+    format: Schema.Literal("effect-vfs-live"),
+    version: Schema.Literal(1),
+    identity: Schema.String.check(Schema.isPattern(/^[0-9a-f]{32}$/)),
+    root: NaturalBigInt,
+    nextInode: NaturalBigInt,
+    revisionCounter: NaturalBigInt,
+    entries: Schema.Natural,
+    usedBytes: NaturalBigInt,
+    limits: Schema.Struct({
+        maxEntries: Schema.optionalKey(Schema.Natural),
+        maxBytes: Schema.optionalKey(NaturalBigInt),
+        maxFileBytes: Schema.optionalKey(NaturalBigInt),
+        maxPathBytes: Schema.optionalKey(NaturalBigInt)
+    }),
+    retainedFiles: Schema.Array(NaturalBigInt),
+    records: Schema.Array(Record)
+});
+const invalid = () => new ImageError({ code: "InvalidStructure", field: "liveImage" });
+const validate = Effect.fnUntraced(function* (document) {
+    const records = new Map();
+    for (const record of document.records) {
+        if (record.ino < 1n || records.has(record.ino) || record.revision < 1n ||
+            record.revision > document.revisionCounter || record.ino >= document.nextInode)
+            return yield* invalid();
+        records.set(record.ino, record);
+    }
+    const root = records.get(document.root);
+    if (document.root !== 1n || root?._tag !== "directory" || document.revisionCounter < 1n) {
+        return yield* invalid();
+    }
+    const links = new Map();
+    const pending = [[root, 1n]];
+    const seenDirectories = new Set();
+    const reachable = new Set();
+    let entries = 0;
+    for (let index = 0; index < pending.length; index++) {
+        const current = pending[index];
+        if (current === undefined)
+            return yield* invalid();
+        const [directory, pathBytes] = current;
+        if (seenDirectories.has(directory.ino))
+            return yield* invalid();
+        seenDirectories.add(directory.ino);
+        reachable.add(directory.ino);
+        const names = new Set();
+        for (const entry of directory.entries) {
+            if (names.has(entry.name) || entry.target === document.root)
+                return yield* invalid();
+            names.add(entry.name);
+            const name = yield* CanonicalBase64.decode(entry.name);
+            if (name.length < 1 || name.length > 255 || name.includes(0) || name.includes(47) ||
+                (name.length === 1 && name[0] === 46) ||
+                (name.length === 2 && name[0] === 46 && name[1] === 46))
+                return yield* invalid();
+            const childPathBytes = pathBytes + BigInt(name.length) + (pathBytes === 1n ? 0n : 1n);
+            if (document.limits.maxPathBytes !== undefined && childPathBytes > document.limits.maxPathBytes) {
+                return yield* invalid();
+            }
+            const target = records.get(entry.target);
+            if (target === undefined)
+                return yield* invalid();
+            entries++;
+            links.set(target.ino, (links.get(target.ino) ?? 0) + 1);
+            reachable.add(target.ino);
+            if (Record.guards.directory(target))
+                pending.push([target, childPathBytes]);
+        }
+    }
+    if (entries !== document.entries || links.has(root.ino))
+        return yield* invalid();
+    const retained = new Set(document.retainedFiles);
+    if (retained.size !== document.retainedFiles.length)
+        return yield* invalid();
+    let usedBytes = 0n;
+    for (const record of document.records) {
+        const actualLinks = links.get(record.ino) ?? 0;
+        if (Record.guards.directory(record)) {
+            const childDirectories = record.entries.filter((entry) => {
+                const child = records.get(entry.target);
+                return child !== undefined && Record.guards.directory(child);
+            }).length;
+            if (!seenDirectories.has(record.ino) || (record.ino !== root.ino && actualLinks !== 1) ||
+                record.metadata.nlink !== 2 + childDirectories || record.metadata.size !== 0n)
+                return yield* invalid();
+        }
+        else {
+            const payload = Record.guards.file(record) ? record.data : record.target;
+            const length = BigInt(CanonicalBase64.decodedLength(payload));
+            if (record.metadata.size !== length || record.metadata.nlink !== actualLinks)
+                return yield* invalid();
+            if (Record.guards.file(record)) {
+                if (document.limits.maxFileBytes !== undefined && length > document.limits.maxFileBytes) {
+                    return yield* invalid();
+                }
+                if (actualLinks === 0 && !retained.has(record.ino))
+                    return yield* invalid();
+                if (actualLinks > 0 && retained.has(record.ino))
+                    return yield* invalid();
+            }
+            else {
+                if (actualLinks === 0 || retained.has(record.ino) || (yield* CanonicalBase64.decode(record.target)).includes(0)) {
+                    return yield* invalid();
+                }
+            }
+            usedBytes += length;
+        }
+        if (!reachable.has(record.ino) && !retained.has(record.ino))
+            return yield* invalid();
+    }
+    if (document.limits.maxPathBytes !== undefined && document.limits.maxPathBytes < 1n)
+        return yield* invalid();
+    if (usedBytes !== document.usedBytes ||
+        (document.limits.maxEntries !== undefined && entries > document.limits.maxEntries) ||
+        (document.limits.maxBytes !== undefined && usedBytes > document.limits.maxBytes))
+        return yield* invalid();
+    for (const ino of retained) {
+        if (records.get(ino)?._tag !== "file" || reachable.has(ino))
+            return yield* invalid();
+    }
+    return document;
+});
+/** @internal */
+export const encode = Effect.fnUntraced(function* (document) {
+    const text = yield* Schema.encodeEffect(Schema.fromJsonString(Document))(yield* validate(document)).pipe(Effect.mapError(() => new ImageError({ code: "InvalidStructure", field: "liveImage" })));
+    return new TextEncoder().encode(text);
+});
+/** @internal */
+export const decode = Effect.fnUntraced(function* (bytes, maxEncodedBytes) {
+    if (!(bytes instanceof Uint8Array) || !(bytes.buffer instanceof ArrayBuffer)) {
+        return yield* new ImageError({ code: "InvalidEncoding", field: "liveImage" });
+    }
+    if (ByteSize.isGreaterThan(ByteSize.bytes(bytes.byteLength), maxEncodedBytes)) {
+        return yield* new ImageError({ code: "LimitExceeded", field: "encodedBytes" });
+    }
+    const text = yield* Effect.try({
+        try: () => new TextDecoder("utf-8", { fatal: true }).decode(new Uint8Array(bytes)),
+        catch: () => new ImageError({ code: "InvalidEncoding", field: "liveImage" })
+    });
+    const parsed = yield* Schema.decodeEffect(Schema.fromJsonString(Schema.Unknown))(text).pipe(Effect.mapError(() => new ImageError({ code: "InvalidEncoding", field: "liveImage" })));
+    const document = Schema.decodeUnknownResult(Document, { onExcessProperty: "error" })(parsed);
+    if (Result.isFailure(document))
+        return yield* new ImageError({ code: "InvalidStructure", field: "liveImage" });
+    return yield* validate(document.success);
+});

package/dist/internal/virtualFileSystem/errors.d.ts

@@ -1,31 +1,12 @@
 import * as Result from "effect/Result";
 import * as Schema from "effect/Schema";
-import type { PathInput } from "../../VirtualFileSystem.js";
+import { ConfigurationError, FsError } from "../../VirtualFileSystemError.js";
 /** @internal */
-export declare const FsCode: Schema.Literals<readonly ["NotFound", "AlreadyExists", "NotEmpty", "NotDirectory", "AccessDenied", "InvalidHandle", "ForeignHandle", "InvalidReference", "ForeignReference", "StaleReference", "ClosedCaller", "InvalidArgument", "InvalidPathEncoding", "PathTooLong", "NoSpace", "IsDirectory", "FileTooLarge", "NoData", "SymlinkLoop", "UnrepresentableName"]>;
+export { ConfigurationError, FsError };
 /** @internal */
-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>;
-/** @internal */
-export declare class FsError extends FsError_base<{
-    readonly code: FsCode;
-    readonly operation: string;
-    readonly path?: PathInput;
-}> {
-    get message(): string;
-}
-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>;
+export declare const FsCode: Schema.Literals<readonly ["NotFound", "AlreadyExists", "NotEmpty", "NotDirectory", "AccessDenied", "InvalidHandle", "ForeignHandle", "InvalidReference", "ForeignReference", "StaleReference", "ClosedCaller", "InvalidArgument", "InvalidPathEncoding", "PathTooLong", "NoSpace", "IsDirectory", "FileTooLarge", "NoData", "SymlinkLoop", "UnrepresentableName", "StorageRejected", "OutcomeUnknown", "VolumeUnavailable", "VolumeBusy"]>;
 /** @internal */
-export declare class ConfigurationError extends ConfigurationError_base<{
-    readonly field: string;
-}> {
-    get message(): string;
-}
+export type FsCode = typeof FsCode.Type;
 /** @internal */
 export declare const decodeConfiguration: <A>(schema: Schema.Codec<A>, value: typeof Schema.Unknown.Type) => Result.Result<A, ConfigurationError>;
-export {};
 //# sourceMappingURL=errors.d.ts.map

package/dist/internal/virtualFileSystem/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/internal/virtualFileSystem/errors.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAA;AAE3D,gBAAgB;AAChB,eAAO,MAAM,MAAM,oWAqBjB,CAAA;AAEF,gBAAgB;AAChB,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAA;;;;AAEvC,gBAAgB;AAChB,qBAAa,OAAQ,SAAQ,aAA4B;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAA;CAC1B,CAAC;IAEA,IAAa,OAAO,IAAI,MAAM,CAE7B;CACF;;;;AAED,gBAAgB;AAChB,qBAAa,kBAAmB,SAAQ,wBAAuC;IAC7E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB,CAAC;IACA,IAAa,OAAO,IAAI,MAAM,CAE7B;CACF;AAWD,gBAAgB;AAChB,eAAO,MAAM,mBAAmB,GAAI,CAAC,UAAU,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,OAAO,MAAM,CAAC,OAAO,CAAC,IAAI,yCAG9F,CAAA"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/internal/virtualFileSystem/errors.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAA;AAE7E,gBAAgB;AAChB,OAAO,EAAE,kBAAkB,EAAE,OAAO,EAAE,CAAA;AAEtC,gBAAgB;AAChB,eAAO,MAAM,MAAM,4aA4BjB,CAAA;AAEF,gBAAgB;AAChB,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAA;AAWvC,gBAAgB;AAChB,eAAO,MAAM,mBAAmB,GAAI,CAAC,UAAU,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,OAAO,MAAM,CAAC,OAAO,CAAC,IAAI,yCAG9F,CAAA"}

package/dist/internal/virtualFileSystem/errors.js

@@ -1,8 +1,10 @@
 // Virtual filesystem failure schemas and identities shared by the runtime implementation.
-import * as Data from "effect/Data";
 import * as Predicate from "effect/Predicate";
 import * as Result from "effect/Result";
 import * as Schema from "effect/Schema";
+import { ConfigurationError, FsError } from "../../VirtualFileSystemError.js";
+/** @internal */
+export { ConfigurationError, FsError };
 /** @internal */
 export const FsCode = Schema.Literals([
     "NotFound",
@@ -24,21 +26,15 @@ export const FsCode = Schema.Literals([
     "FileTooLarge",
     "NoData",
     "SymlinkLoop",
-    "UnrepresentableName"
+    "UnrepresentableName",
+    // A durable provider knows the mutation was not committed.
+    "StorageRejected",
+    // A commit or publication failed after its outcome ceased to be knowable to the caller.
+    "OutcomeUnknown",
+    // The provider stopped serving operations until recovery establishes its state.
+    "VolumeUnavailable",
+    "VolumeBusy"
 ]);
-/** @internal */
-export class FsError extends Data.TaggedError("FsError") {
-    // The path is omitted on purpose: byte paths are not printable and may carry user data.
-    get message() {
-        return `${this.operation} failed with ${this.code}`;
-    }
-}
-/** @internal */
-export class ConfigurationError extends Data.TaggedError("ConfigurationError") {
-    get message() {
-        return `Invalid option: ${this.field}`;
-    }
-}
 // Names the offending option so the caller learns which key it got wrong, not just that decoding failed.
 const configurationField = (issue) => {
     if (Predicate.isTagged("Pointer")(issue))

package/dist/internal/virtualFileSystem/fixture.d.ts

@@ -55,9 +55,12 @@ export declare const fromFixture: (fixture: {
         readonly target: string | import("../../BytePath.js").BytePath;
     })[];
 }, options?: {
+    readonly identity?: string & import("effect/Brand").Brand<"@effect-vfs/core/VolumeIdentity">;
     readonly maxEntries?: number;
+    readonly maxPendingOperations?: number;
+    readonly maxWatchEvents?: number;
     readonly maxBytes?: import("effect/ByteSize").ByteSize;
     readonly maxFileBytes?: import("effect/ByteSize").ByteSize;
     readonly maxPathBytes?: import("effect/ByteSize").ByteSize;
-} | undefined) => Effect.Effect<import("../../VirtualFileSystem.js").Volume, import("./errors.js").ConfigurationError | ImageError, never>;
+} | undefined) => Effect.Effect<import("../../VirtualFileSystem.js").Volume, import("./errors.js").ConfigurationError | ImageError | import("effect/PlatformError").PlatformError, import("effect/Crypto").Crypto>;
 //# sourceMappingURL=fixture.d.ts.map

package/dist/internal/virtualFileSystem/fixture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fixture.d.ts","sourceRoot":"","sources":["../../../src/internal/virtualFileSystem/fixture.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAmB9C,gBAAgB;AAChB,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0IAiLvB,CAAA"}
+{"version":3,"file":"fixture.d.ts","sourceRoot":"","sources":["../../../src/internal/virtualFileSystem/fixture.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAoB9C,gBAAgB;AAChB,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kNAwLvB,CAAA"}

package/dist/internal/virtualFileSystem/fixture.js

@@ -5,7 +5,7 @@ import * as Schema from "effect/Schema";
 import { ImageError } from "../../Snapshot.js";
 import { CanonicalBase64 } from "../canonicalBase64.js";
 import * as Image from "../image.js";
-import { Fixture as FixtureSchema, FixtureEntry, makeVolume, VolumeOptions as VolumeOptionsSchema, VolumeSource } from "../virtualFileSystem.js";
+import { Fixture as FixtureSchema, FixtureEntry, makeVolume, VolumeIdentity, VolumeOptions as VolumeOptionsSchema, VolumeSource } from "../virtualFileSystem.js";
 import { decodeConfiguration, FsError } from "./errors.js";
 import { inputBytes, isAttachedBytes, isDotComponent, nameBytes, preparePath } from "./path.js";
 const DEFAULT_MODE = { directory: 0o755, file: 0o644, symlink: 0o777 };
@@ -140,5 +140,11 @@ export const fromFixture = Effect.fn("VirtualFileSystem.fromFixture")(function*
     }));
     const snapshot = yield* Image.capture({ format: "effect-vfs", version: 1, root: "root", records }, undefined, true);
     const image = yield* Image.inspect(snapshot);
-    return yield* makeVolume(VolumeSource.Snapshot({ image }), config.success);
+    const { identity, ...volumeOptions } = config.success;
+    if (identity === undefined)
+        return yield* makeVolume(VolumeSource.Snapshot({ image }), volumeOptions);
+    return yield* makeVolume(VolumeSource.Snapshot({ image }), {
+        ...volumeOptions,
+        identity: VolumeIdentity.make(identity)
+    });
 });

package/dist/internal/virtualFileSystem/stagedState.d.ts

@@ -0,0 +1,22 @@
+import * as Effect from "effect/Effect";
+import { FsError } from "./errors.js";
+/** @internal */
+export type CommitOutcome = "committed" | "rejected" | "unknown";
+/** @internal */
+export interface CommitProvider<State> {
+    /** Provides a gate-coordinated shutdown effect once staging is ready. */
+    readonly onReady?: (shutdown: Effect.Effect<void>) => void;
+    /** Checks and encodes a candidate before the commit boundary. Failure leaves the volume available. */
+    readonly prepare?: (candidate: State) => Effect.Effect<void, FsError>;
+    /** Classifies a candidate as committed, definitely rejected, or uncertain. */
+    readonly commit: (candidate: State) => Effect.Effect<CommitOutcome>;
+}
+/** @internal */
+export declare const makeStagedState: <State, Event = never>(initial: State, copy: (current: State) => Effect.Effect<State>, rawProvider: CommitProvider<State>, publish?: (candidate: State, events: ReadonlyArray<Event>) => void) => {
+    read: <A, E, R>(operation: string, inspect: (state: Readonly<State>) => Effect.Effect<A, E, R>) => Effect.Effect<A, E | FsError, R>;
+    mutate: <A, E, R>(operation: string, change: (candidate: State, emit: (event: Event) => void) => Effect.Effect<A, E, R>, onStorageFailure?: () => void) => Effect.Effect<A, E | FsError, R>;
+    coordinate: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+    checkAvailable: (operation: string) => Effect.Effect<void, FsError, never>;
+    shutdown: Effect.Effect<void, never, never>;
+};
+//# sourceMappingURL=stagedState.d.ts.map

package/dist/internal/virtualFileSystem/stagedState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stagedState.d.ts","sourceRoot":"","sources":["../../../src/internal/virtualFileSystem/stagedState.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAErC,gBAAgB;AAChB,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,CAAA;AAEhE,gBAAgB;AAChB,MAAM,WAAW,cAAc,CAAC,KAAK;IACnC,yEAAyE;IACzE,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,IAAI,CAAA;IAC1D,sGAAsG;IACtG,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,KAAK,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;IACrE,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,CAAC,SAAS,EAAE,KAAK,KAAK,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAA;CACpE;AAED,gBAAgB;AAChB,eAAO,MAAM,eAAe,GAAI,KAAK,EAAE,KAAK,mBACjC,KAAK,QAER,CAAC,OAAO,EAAE,KAAK,KAAK,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,eACjC,cAAc,CAAC,KAAK,CAAC,YACxB,CAAC,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,KAAK,IAAI;WAyBpD,CAAC,EAAE,CAAC,EAAE,CAAC,aAAa,MAAM,WAAW,CAAC,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;aAOrF,CAAC,EAAE,CAAC,EAAE,CAAC,aACV,MAAM,UACT,CAAC,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,KAAK,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,qBAC/D,MAAM,IAAI;iBAhBX,CAAC,EAAE,CAAC,EAAE,CAAC,UAAU,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;gCAPxB,MAAM;;CA0E1C,CAAA"}