@effect-vfs/core 0.4.0 → 0.6.0

package/dist/Fixture.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Fixture schemas: a declarative final state from which a volume is built.
+ *
+ * @since 0.6.0
+ */
+import * as Schema from "effect/Schema";
+import { BytePath } from "./BytePath.js";
+/**
+ * Schema for the metadata a fixture entry may pin; omitted fields take the
+ * volume's defaults.
+ *
+ * @category schemas
+ * @since 0.6.0
+ */
+export declare const FixtureMetadata: Schema.Struct<{
+    readonly uid: Schema.optionalKey<Schema.Natural>;
+    readonly gid: Schema.optionalKey<Schema.Natural>;
+    readonly mode: Schema.optionalKey<Schema.Natural>;
+    readonly atimeNs: Schema.optionalKey<Schema.BigInt>;
+    readonly mtimeNs: Schema.optionalKey<Schema.BigInt>;
+    readonly ctimeNs: Schema.optionalKey<Schema.BigInt>;
+    readonly birthtimeNs: Schema.optionalKey<Schema.BigInt>;
+}>;
+/**
+ * Metadata a fixture entry pins.
+ *
+ * @category models
+ * @since 0.6.0
+ */
+export type FixtureMetadata = typeof FixtureMetadata.Type;
+/**
+ * Schema for one fixture entry: a directory, a file with bytes, a symbolic
+ * link, or a hard link to an earlier file entry.
+ *
+ * @category schemas
+ * @since 0.6.0
+ */
+export declare const FixtureEntry: Schema.toTaggedUnion<"kind", 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.Natural>;
+        readonly gid: Schema.optionalKey<Schema.Natural>;
+        readonly mode: Schema.optionalKey<Schema.Natural>;
+        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.Natural>;
+        readonly gid: Schema.optionalKey<Schema.Natural>;
+        readonly mode: Schema.optionalKey<Schema.Natural>;
+        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.Natural>;
+        readonly gid: Schema.optionalKey<Schema.Natural>;
+        readonly mode: Schema.optionalKey<Schema.Natural>;
+        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>]>;
+}>]>;
+/**
+ * One fixture entry.
+ *
+ * @category models
+ * @since 0.6.0
+ */
+export type FixtureEntry = typeof FixtureEntry.Type;
+/**
+ * Schema for a whole fixture: optional root metadata and its entries in order.
+ *
+ * @category schemas
+ * @since 0.6.0
+ */
+export declare const Fixture: Schema.Struct<{
+    readonly rootMetadata: Schema.optionalKey<Schema.Struct<{
+        readonly uid: Schema.optionalKey<Schema.Natural>;
+        readonly gid: Schema.optionalKey<Schema.Natural>;
+        readonly mode: Schema.optionalKey<Schema.Natural>;
+        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.toTaggedUnion<"kind", 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.Natural>;
+            readonly gid: Schema.optionalKey<Schema.Natural>;
+            readonly mode: Schema.optionalKey<Schema.Natural>;
+            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.Natural>;
+            readonly gid: Schema.optionalKey<Schema.Natural>;
+            readonly mode: Schema.optionalKey<Schema.Natural>;
+            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.Natural>;
+            readonly gid: Schema.optionalKey<Schema.Natural>;
+            readonly mode: Schema.optionalKey<Schema.Natural>;
+            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 whole fixture.
+ *
+ * @category models
+ * @since 0.6.0
+ */
+export type Fixture = typeof Fixture.Type;
+//# sourceMappingURL=Fixture.d.ts.map

package/dist/Fixture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Fixture.d.ts","sourceRoot":"","sources":["../src/Fixture.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAGxC;;;;;;GAMG;AACH,eAAO,MAAM,eAAe;;;;;;;;EAQ1B,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC,IAAI,CAAA;AAOzD;;;;;;GAMG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAmBY,CAAA;AAErC;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAA;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAGlB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GAAG,OAAO,OAAO,CAAC,IAAI,CAAA"}

package/dist/Fixture.js

@@ -0,0 +1,65 @@
+/**
+ * Fixture schemas: a declarative final state from which a volume is built.
+ *
+ * @since 0.6.0
+ */
+import * as Schema from "effect/Schema";
+import { BytePath } from "./BytePath.js";
+import { Mode, Timestamp } from "./Metadata.js";
+/**
+ * Schema for the metadata a fixture entry may pin; omitted fields take the
+ * volume's defaults.
+ *
+ * @category schemas
+ * @since 0.6.0
+ */
+export const FixtureMetadata = Schema.Struct({
+    uid: Schema.optionalKey(Schema.Natural),
+    gid: Schema.optionalKey(Schema.Natural),
+    mode: Schema.optionalKey(Mode),
+    atimeNs: Schema.optionalKey(Timestamp),
+    mtimeNs: Schema.optionalKey(Timestamp),
+    ctimeNs: Schema.optionalKey(Timestamp),
+    birthtimeNs: Schema.optionalKey(Timestamp)
+});
+const FixturePath = Schema.Union([
+    Schema.String,
+    BytePath
+]);
+/**
+ * Schema for one fixture entry: a directory, a file with bytes, a symbolic
+ * link, or a hard link to an earlier file entry.
+ *
+ * @category schemas
+ * @since 0.6.0
+ */
+export const FixtureEntry = Schema.Union([
+    Schema.Struct({
+        kind: Schema.Literal("directory"),
+        path: FixturePath,
+        metadata: Schema.optionalKey(FixtureMetadata)
+    }),
+    Schema.Struct({
+        kind: Schema.Literal("file"),
+        path: FixturePath,
+        bytes: Schema.Uint8Array,
+        metadata: Schema.optionalKey(FixtureMetadata)
+    }),
+    Schema.Struct({
+        kind: Schema.Literal("symlink"),
+        path: FixturePath,
+        target: FixturePath,
+        metadata: Schema.optionalKey(FixtureMetadata)
+    }),
+    Schema.Struct({ kind: Schema.Literal("hardLink"), path: FixturePath, target: FixturePath })
+]).pipe(Schema.toTaggedUnion("kind"));
+/**
+ * Schema for a whole fixture: optional root metadata and its entries in order.
+ *
+ * @category schemas
+ * @since 0.6.0
+ */
+export const Fixture = Schema.Struct({
+    rootMetadata: Schema.optionalKey(FixtureMetadata),
+    entries: Schema.Array(FixtureEntry)
+});

package/dist/LiveVolume.d.ts

@@ -3,38 +3,27 @@
  *
  * An adapter must preserve the supplied bytes atomically and classify each
  * commit as confirmed, definitely rejected, or uncertain. The opened volume
- * stays at `memory-only` until the adapter's durability is qualified.
+ * stays at `memory-only` unless the adapter explicitly supplies a qualified
+ * durability tier.
  *
  * @since 0.4.0
  */
 import { Context, Effect } from "effect";
 import * as ByteSize from "effect/ByteSize";
-import type * as Crypto from "effect/Crypto";
-import type * as PlatformError from "effect/PlatformError";
 import type * as Scope from "effect/Scope";
-import type { ConfigurationError, ImageError, Volume, VolumeOptions } from "./VirtualFileSystem.js";
+import { type ArgumentFailure, type StoreFailure, VfsError } from "./VfsError.js";
+import type { Volume, VolumeDurability, VolumeOptions } from "./VirtualFileSystem.js";
 /**
  * A storage commit's observed outcome.
  *
+ * @category models
  * @since 0.4.0
  */
 export type CommitOutcome = "committed" | "rejected" | "unknown";
-declare const LiveVolumeError_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: "LiveVolumeError";
-} & Readonly<A>;
-/**
- * A failed live-store startup or recovery.
- *
- * @category errors
- * @since 0.4.0
- */
-export declare class LiveVolumeError extends LiveVolumeError_base<{
-    readonly code: "InvalidConfiguration" | "Storage" | "Ownership" | "IncompatibleStore" | "CorruptStore";
-    readonly cause?: unknown;
-}> {
-}
 declare const LiveImageStore_base: Context.ServiceClass<LiveImageStore, "@effect-vfs/core/LiveImageStore", {
-    readonly loadOrCreate: (initial: Uint8Array) => Effect.Effect<Uint8Array, LiveVolumeError>;
+    /** Storage guarantee for successful commits; omission means memory-only. */
+    readonly durability?: VolumeDurability;
+    readonly loadOrCreate: (initial: Uint8Array) => Effect.Effect<Uint8Array, StoreFailure | ArgumentFailure>;
     readonly commit: (image: Uint8Array) => Effect.Effect<CommitOutcome>;
 }>;
 /**
@@ -42,6 +31,7 @@ declare const LiveImageStore_base: Context.ServiceClass<LiveImageStore, "@effect
  * volume has shut down. Providers must atomically replace each image and
  * classify ambiguous commits as `unknown`.
  *
+ * @category services
  * @since 0.4.0
  */
 export declare class LiveImageStore extends LiveImageStore_base {
@@ -60,9 +50,10 @@ export interface Options {
  * Open a live volume using the supplied store Layer. The caller owns a Scope;
  * the volume shuts down before that Layer releases its storage resource.
  *
+ * @category constructors
  * @since 0.4.0
  */
-export declare const open: (options: Options) => Effect.Effect<Volume, LiveVolumeError, LiveImageStore | Crypto.Crypto | Scope.Scope>;
+export declare const open: (options: Options) => Effect.Effect<Volume, VfsError, LiveImageStore | Scope.Scope>;
 /**
  * A live volume and the shutdown action its storage adapter must run before
  * closing the underlying store.
@@ -85,17 +76,19 @@ export interface ImageSession {
  * Construct a versioned image for a new, empty volume.
  * Store this image before opening it for mutation.
  *
+ * @category constructors
  * @since 0.4.0
  */
-export declare const prepareEmptyImage: (options?: VolumeOptions) => Effect.Effect<Uint8Array, ConfigurationError | ImageError | PlatformError.PlatformError, Crypto.Crypto>;
+export declare const prepareEmptyImage: (options?: VolumeOptions) => Effect.Effect<Uint8Array, VfsError>;
 /**
  * Open a validated image and stage every mutation before calling `commit`.
  * The returned session contains the volume and a coordinated shutdown effect.
  * Run shutdown before releasing the storage connection. An uncertain commit
  * makes the volume unavailable until it is reopened.
  *
+ * @category constructors
  * @since 0.4.0
  */
-export declare const openImage: (image: Uint8Array, maxImageBytes: ByteSize.ByteSize, commit: (image: Uint8Array) => Effect.Effect<CommitOutcome>) => Effect.Effect<ImageSession, ConfigurationError | ImageError | PlatformError.PlatformError, Crypto.Crypto>;
+export declare const openImage: (image: Uint8Array, maxImageBytes: ByteSize.ByteSize, commit: (image: Uint8Array) => Effect.Effect<CommitOutcome>, durability?: VolumeDurability) => Effect.Effect<ImageSession, VfsError>;
 export {};
 //# sourceMappingURL=LiveVolume.d.ts.map

package/dist/LiveVolume.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LiveVolume.d.ts","sourceRoot":"","sources":["../src/LiveVolume.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,OAAO,EAAQ,MAAM,EAAE,MAAM,QAAQ,CAAA;AAC9C,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAA;AAC5C,OAAO,KAAK,KAAK,aAAa,MAAM,sBAAsB,CAAA;AAC1D,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAA;AAE1C,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAEnG;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,CAAA;;;;AAEhE;;;;;GAKG;AACH,qBAAa,eAAgB,SAAQ,qBAAoC;IACvE,QAAQ,CAAC,IAAI,EAAE,sBAAsB,GAAG,SAAS,GAAG,WAAW,GAAG,mBAAmB,GAAG,cAAc,CAAA;IACtG,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CACzB,CAAC;CAAG;;2BAUoB,CAAC,OAAO,EAAE,UAAU,KAAK,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,eAAe,CAAC;qBACzE,CAAC,KAAK,EAAE,UAAU,KAAK,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC;;AATtE;;;;;;GAMG;AACH,qBAAa,cAAe,SAAQ,mBAGG;CAAG;AAE1C;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,QAAQ,CAAA;IACzC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;CAC/B;AAED;;;;;GAKG;AACH,eAAO,MAAM,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,CACpD,MAAM,EACN,eAAe,EACf,cAAc,GAAG,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC,KAAK,CAkC5C,CAAA;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;CACvC;AAED;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,CAAC,OAAO,CAAC,EAAE,aAAa,KAAK,MAAM,CAAC,MAAM,CACxE,UAAU,EACV,kBAAkB,GAAG,UAAU,GAAG,aAAa,CAAC,aAAa,EAC7D,MAAM,CAAC,MAAM,CACgB,CAAA;AAE/B;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,EAAE,CACtB,KAAK,EAAE,UAAU,EACjB,aAAa,EAAE,QAAQ,CAAC,QAAQ,EAChC,MAAM,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,KACxD,MAAM,CAAC,MAAM,CAChB,YAAY,EACZ,kBAAkB,GAAG,UAAU,GAAG,aAAa,CAAC,aAAa,EAC7D,MAAM,CAAC,MAAM,CACU,CAAA"}
+{"version":3,"file":"LiveVolume.d.ts","sourceRoot":"","sources":["../src/LiveVolume.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AACxC,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAA;AAG1C,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACjF,OAAO,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AAErF;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,CAAA;;IAW9D,4EAA4E;0BACtD,gBAAgB;2BACf,CAAC,OAAO,EAAE,UAAU,KAAK,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,YAAY,GAAG,eAAe,CAAC;qBACxF,CAAC,KAAK,EAAE,UAAU,KAAK,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC;;AAZtE;;;;;;;GAOG;AACH,qBAAa,cAAe,SAAQ,mBAKG;CAAG;AAE1C;;;;;GAKG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,QAAQ,CAAA;IACzC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;CAC/B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,CACpD,MAAM,EACN,QAAQ,EACR,cAAc,GAAG,KAAK,CAAC,KAAK,CAuC5B,CAAA;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;CACvC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,CAAC,OAAO,CAAC,EAAE,aAAa,KAAK,MAAM,CAAC,MAAM,CACxE,UAAU,EACV,QAAQ,CAKP,CAAA;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,EAAE,CACtB,KAAK,EAAE,UAAU,EACjB,aAAa,EAAE,QAAQ,CAAC,QAAQ,EAChC,MAAM,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,EAC3D,UAAU,CAAC,EAAE,gBAAgB,KAC1B,MAAM,CAAC,MAAM,CAChB,YAAY,EACZ,QAAQ,CACe,CAAA"}

package/dist/LiveVolume.js

@@ -3,26 +3,22 @@
  *
  * An adapter must preserve the supplied bytes atomically and classify each
  * commit as confirmed, definitely rejected, or uncertain. The opened volume
- * stays at `memory-only` until the adapter's durability is qualified.
+ * stays at `memory-only` unless the adapter explicitly supplies a qualified
+ * durability tier.
  *
  * @since 0.4.0
  */
-import { Context, Data, Effect } from "effect";
+import { Context, Effect } from "effect";
 import * as ByteSize from "effect/ByteSize";
+import { argumentFailure, retargetFailure } from "./internal/errors.js";
 import * as Model from "./internal/virtualFileSystem.js";
-/**
- * A failed live-store startup or recovery.
- *
- * @category errors
- * @since 0.4.0
- */
-export class LiveVolumeError extends Data.TaggedError("LiveVolumeError") {
-}
+import { VfsError } from "./VfsError.js";
 /**
  * One exclusively owned store. Its Layer holds the storage resource until the
  * volume has shut down. Providers must atomically replace each image and
  * classify ambiguous commits as `unknown`.
  *
+ * @category services
  * @since 0.4.0
  */
 export class LiveImageStore extends Context.Service()("@effect-vfs/core/LiveImageStore") {
@@ -31,16 +27,22 @@ export class LiveImageStore extends Context.Service()("@effect-vfs/core/LiveImag
  * Open a live volume using the supplied store Layer. The caller owns a Scope;
  * the volume shuts down before that Layer releases its storage resource.
  *
+ * @category constructors
  * @since 0.4.0
  */
 export const open = Effect.fn("LiveVolume.open")(function* (options) {
     const store = yield* LiveImageStore;
-    const initial = yield* prepareEmptyImage(options.volume).pipe(Effect.mapError((cause) => new LiveVolumeError({ code: "InvalidConfiguration", cause })));
+    const initial = yield* prepareEmptyImage(options.volume).pipe(
+    // Names the nested option that failed, such as `volume.maxEntries`.
+    Effect.mapError((cause) => {
+        const field = "field" in cause ? cause.field : undefined;
+        return argumentFailure("LiveVolume.open", field === undefined ? "volume" : `volume.${field}`, cause);
+    }));
     if (BigInt(initial.length) > ByteSize.toBigInt(options.maxImageBytes)) {
-        return yield* new LiveVolumeError({ code: "InvalidConfiguration" });
+        return yield* argumentFailure("LiveVolume.open", "maxImageBytes");
     }
     const image = yield* store.loadOrCreate(initial);
-    const session = yield* openImage(image, options.maxImageBytes, store.commit).pipe(Effect.mapError((cause) => new LiveVolumeError({ code: "CorruptStore", cause })));
+    const session = yield* openImage(image, options.maxImageBytes, store.commit, store.durability ?? "memory-only").pipe(Effect.mapError((cause) => new VfsError({ code: "CorruptStore", operation: "LiveVolume.open", cause })));
     yield* Effect.addFinalizer(() => session.shutdown);
     const volume = session.volume;
     if (volume.limits.maxEntries !== options.volume.maxEntries || volume.limits.maxBytes === undefined ||
@@ -50,7 +52,7 @@ export const open = Effect.fn("LiveVolume.open")(function* (options) {
         ByteSize.toBigInt(volume.limits.maxFileBytes) !== ByteSize.toBigInt(options.volume.maxFileBytes) ||
         ByteSize.toBigInt(volume.limits.maxPathBytes) !== ByteSize.toBigInt(options.volume.maxPathBytes) ||
         (options.volume.identity !== undefined && options.volume.identity !== volume.identity)) {
-        return yield* new LiveVolumeError({ code: "IncompatibleStore" });
+        return yield* new VfsError({ code: "IncompatibleStore", operation: "LiveVolume.open" });
     }
     return volume;
 });
@@ -58,15 +60,17 @@ export const open = Effect.fn("LiveVolume.open")(function* (options) {
  * Construct a versioned image for a new, empty volume.
  * Store this image before opening it for mutation.
  *
+ * @category constructors
  * @since 0.4.0
  */
-export const prepareEmptyImage = Model.prepareEmptyLiveImage;
+export const prepareEmptyImage = (options) => Effect.mapError(Model.prepareEmptyLiveImage(options), (error) => retargetFailure("LiveVolume.prepareEmptyImage", error));
 /**
  * Open a validated image and stage every mutation before calling `commit`.
  * The returned session contains the volume and a coordinated shutdown effect.
  * Run shutdown before releasing the storage connection. An uncertain commit
  * makes the volume unavailable until it is reopened.
  *
+ * @category constructors
  * @since 0.4.0
  */
 export const openImage = Model.openImageVolume;

package/dist/Metadata.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Metadata schemas for virtual filesystem objects: timestamps, permission modes,
+ * the metadata record every observation returns, and the owner and time updates
+ * that mutations accept.
+ *
+ * @since 0.6.0
+ */
+import * as Schema from "effect/Schema";
+/**
+ * Schema for a timestamp in nanoseconds since the Unix epoch. Values stay
+ * within 128 decimal digits so they round-trip through snapshot encodings.
+ *
+ * @category schemas
+ * @since 0.6.0
+ */
+export declare const Timestamp: Schema.BigInt;
+/**
+ * A timestamp in nanoseconds since the Unix epoch.
+ *
+ * @category models
+ * @since 0.6.0
+ */
+export type Timestamp = typeof Timestamp.Type;
+/**
+ * Schema for a POSIX permission mode: the permission, setuid, setgid and sticky
+ * bits without any file-type bits.
+ *
+ * @category schemas
+ * @since 0.6.0
+ */
+export declare const Mode: Schema.Natural;
+/**
+ * A POSIX permission mode.
+ *
+ * @category models
+ * @since 0.6.0
+ */
+export type Mode = typeof Mode.Type;
+/**
+ * Schema for the metadata of a filesystem object.
+ *
+ * @category schemas
+ * @since 0.6.0
+ */
+export declare const Metadata: Schema.Struct<{
+    readonly kind: Schema.Literals<readonly ["directory", "file", "symlink"]>;
+    readonly ino: Schema.BigInt;
+    readonly nlink: Schema.Natural;
+    readonly size: Schema.BigInt;
+    readonly uid: Schema.Natural;
+    readonly gid: Schema.Natural;
+    readonly mode: Schema.Natural;
+    readonly atimeNs: Schema.BigInt;
+    readonly mtimeNs: Schema.BigInt;
+    readonly ctimeNs: Schema.BigInt;
+    readonly birthtimeNs: Schema.BigInt;
+    /** The object's revision, advanced by every committed change to it. */
+    readonly revision: Schema.BigInt;
+}>;
+/**
+ * Metadata of a filesystem object, including its revision.
+ *
+ * @category models
+ * @since 0.6.0
+ */
+export type Metadata = typeof Metadata.Type;
+/**
+ * Mask of the file-type bits in a POSIX `st_mode`.
+ *
+ * @category constants
+ * @since 0.6.0
+ */
+export declare const S_IFMT = 61440;
+/**
+ * File-type bits of a regular file in a POSIX `st_mode`.
+ *
+ * @category constants
+ * @since 0.6.0
+ */
+export declare const S_IFREG = 32768;
+/**
+ * File-type bits of a directory in a POSIX `st_mode`.
+ *
+ * @category constants
+ * @since 0.6.0
+ */
+export declare const S_IFDIR = 16384;
+/**
+ * File-type bits of a symbolic link in a POSIX `st_mode`.
+ *
+ * @category constants
+ * @since 0.6.0
+ */
+export declare const S_IFLNK = 40960;
+/**
+ * The POSIX `st_mode` of an object: the file-type bits of its `kind` joined
+ * with its permission `mode`. `mode` itself never carries type bits, so the
+ * kind has a single source.
+ *
+ * A volume has no device nodes, so a `stat` built from metadata reports `dev`
+ * and `rdev` as 0, and `(dev, ino)` identifies an object only within one volume.
+ *
+ * @example
+ * ```ts
+ * import { S_IFDIR, S_IFMT, typedMode } from "@effect-vfs/core/Metadata"
+ *
+ * const stMode = typedMode({ kind: "directory", mode: 0o755 })
+ *
+ * console.log(stMode.toString(8)) // "40755"
+ * console.log((stMode & S_IFMT) === S_IFDIR) // true
+ * ```
+ *
+ * @category getters
+ * @since 0.6.0
+ */
+export declare const typedMode: (metadata: Pick<Metadata, "kind" | "mode">) => number;
+/**
+ * Schema for an ownership update; an omitted field keeps its current value.
+ *
+ * @category schemas
+ * @since 0.6.0
+ */
+export declare const OwnerUpdate: Schema.Struct<{
+    readonly uid: Schema.optionalKey<Schema.Natural>;
+    readonly gid: Schema.optionalKey<Schema.Natural>;
+}>;
+/**
+ * An ownership update.
+ *
+ * @category models
+ * @since 0.6.0
+ */
+export type OwnerUpdate = typeof OwnerUpdate.Type;
+/**
+ * Schema for one timestamp update: the current time, no change, or an explicit value.
+ *
+ * @category schemas
+ * @since 0.6.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;
+}>]>;
+/**
+ * One timestamp update.
+ *
+ * @category models
+ * @since 0.6.0
+ */
+export type TimeUpdate = typeof TimeUpdate.Type;
+/**
+ * Schema for the access and modification time updates a mutation applies together.
+ *
+ * @category schemas
+ * @since 0.6.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.
+ *
+ * @category models
+ * @since 0.6.0
+ */
+export type Times = typeof Times.Type;
+//# sourceMappingURL=Metadata.d.ts.map

package/dist/Metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Metadata.d.ts","sourceRoot":"","sources":["../src/Metadata.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAIvC;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,eAGrB,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,SAAS,CAAC,IAAI,CAAA;AAE7C;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,gBAA2D,CAAA;AAE5E;;;;;GAKG;AACH,MAAM,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,IAAI,CAAA;AAEnC;;;;;GAKG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;IAYnB,uEAAuE;;EAEvE,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAA;AAE3C;;;;;GAKG;AACH,eAAO,MAAM,MAAM,QAAW,CAAA;AAE9B;;;;;GAKG;AACH,eAAO,MAAM,OAAO,QAAW,CAAA;AAE/B;;;;;GAKG;AACH,eAAO,MAAM,OAAO,QAAW,CAAA;AAE/B;;;;;GAKG;AACH,eAAO,MAAM,OAAO,QAAW,CAAA;AAI/B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,SAAS,aAAc,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,KAAG,MACvB,CAAA;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,WAAW;;;EAGtB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC,IAAI,CAAA;AAEjD;;;;;GAKG;AACH,eAAO,MAAM,UAAU;;;;;;;IAIrB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAC,IAAI,CAAA;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;EAAkE,CAAA;AAEpF;;;;;GAKG;AACH,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAA"}