@effect-vfs/core 0.3.0 → 0.4.0

package/README.md

@@ -1,13 +1,10 @@
 # @effect-vfs/core
 
-`@effect-vfs/core` is a runtime-neutral virtual filesystem engine for Effect. It gives you isolated in-memory volumes,
-byte-preserving paths, POSIX-inspired permissions, logical quotas, change streams, deterministic fixtures, and portable
-encoded snapshots without reading from or writing to the host filesystem.
+`@effect-vfs/core` manages in-memory volumes with byte-preserving paths, callers with explicit permissions, quotas,
+watches, fixtures, and portable snapshots. It does not access the host filesystem.
 
-Use it when filesystem state is part of your domain: sandboxing a tool, modeling several users against one namespace,
-testing permission behavior, building repeatable fixtures, or saving and restoring an in-memory workspace. If you need
-Effect's standard `FileSystem` service, use [`@effect-vfs/memory`](https://www.npmjs.com/package/@effect-vfs/memory),
-which adapts this package to that interface.
+Use core when you need direct control over a shared volume or byte-oriented paths. For Effect's standard
+`FileSystem` service, use [`@effect-vfs/memory`](../memory/README.md).
 
 The package implements a documented subset of POSIX behavior. It does not claim full POSIX conformance. See the
 [implemented profile](https://github.com/lloydrichards/effect-virtual-fs/blob/main/.okf/profiles/implemented-filesystem.md)
@@ -19,7 +16,8 @@ for the exact permission, path, timestamp, quota, and atomicity rules.
 npm install @effect-vfs/core effect@4.0.0-rc.114
 ```
 
-Version `0.1.0` targets the exact peer version `effect@4.0.0-rc.114`.
+The package currently requires the exact peer version `effect@4.0.0-rc.114`. The examples also need a `Crypto`
+service; on Node or Bun, install `@effect/platform-node-shared@4.0.0-rc.114` and provide `NodeCrypto.layer`.
 
 ## The mental model
 
@@ -40,6 +38,7 @@ lifetime are explicit values that can be composed in one Effect program.
 
 ```ts
 import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
 import { ByteSize, Effect } from "effect"
 
 const utf8 = new TextEncoder()
@@ -76,7 +75,7 @@ const program = Effect.scoped(Effect.gen(function*() {
   }
 }))
 
-const result = await Effect.runPromise(program)
+const result = await Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer)))
 console.log(result) // { config: { feature: "preview" }, mode: "640" }
 ```
 
@@ -94,6 +93,7 @@ contain names which are not valid UTF-8.
 
 ```ts
 import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
 import { Effect } from "effect"
 
 const program = Effect.gen(function*() {
@@ -112,7 +112,7 @@ const program = Effect.gen(function*() {
   return { names: names.map((name) => Array.from(name)), roundTrip: Array.from(roundTrip) }
 })
 
-console.log(await Effect.runPromise(program))
+console.log(await Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))))
 // { names: [[255]], roundTrip: [47, 255] }
 ```
 
@@ -128,6 +128,7 @@ resettable sandboxes.
 
 ```ts
 import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
 import { Effect } from "effect"
 import * as ByteSize from "effect/ByteSize"
 
@@ -165,7 +166,7 @@ const program = Effect.gen(function*() {
   return new TextDecoder().decode(yield* b.readFile("/project/settings.json"))
 })
 
-console.log(await Effect.runPromise(program)) // {"theme":"dark"}
+console.log(await Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer)))) // {"theme":"dark"}
 ```
 
 Fixture paths must be absolute and unique, and parent directories must be listed explicitly. Fixtures can also contain
@@ -175,140 +176,15 @@ Snapshot decoding requires explicit work limits because encoded bytes may come f
 contains the reachable namespace and metadata. It excludes callers, open handles, cursor positions, watch
 subscriptions, and unlinked content. Each restored volume is independent.
 
-## Branch from one immutable snapshot
+## Overlays and snapshot deltas
 
-Use `makeOverlay` when several writable workspaces start from the same snapshot. Untouched regular-file contents are
-shared internally. A content change copies that whole file for the editing workspace; namespace and metadata state are
-always private. Logical quotas still count the complete visible volume, including shared base files and unlinked-open
-contents.
+An overlay creates a writable workspace from an immutable snapshot. Untouched file bytes remain shared until a
+workspace edits them. See the [overlay guide](../../apps/docs/app/content/guides/overlay-filesystems.mdx) for the
+workflow and conflict rules.
 
-```ts
-import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
-import { Effect } from "effect"
-import * as ByteSize from "effect/ByteSize"
-
-const branch = Effect.gen(function*() {
-  const template = yield* Vfs.fromFixture({
-    entries: [
-      { kind: "directory", path: "/project" },
-      { kind: "file", path: "/project/settings.json", bytes: new Uint8Array() }
-    ]
-  })
-  const base = yield* template.snapshot
-  const workspace = yield* Vfs.makeOverlay(base, { maxBytes: ByteSize.megabytes(1) })
-  const fs = yield* workspace.caller()
-
-  yield* fs.rename("/project/settings.json", "/project/preferences.json")
-  return yield* workspace.capture()
-})
-```
-
-`makeOverlay(base, options)` returns a reusable Effect. Each execution creates a fresh workspace from `base`; it does
-not memoize or reset an earlier workspace. Invalid volume options fail with `ConfigurationError`, while failure to
-inspect the base snapshot fails with `ImageError`.
-
-`changes()` reports final differences from the base. It hides timestamp-only differences unless called with
-`{ includeTimestamps: true }`. Renames are paired only from retained object identity; equal contents are never treated
-as rename evidence. Paths in summaries are `BytePath` values, so inspect them with `pathToBytes` when names may not be
-UTF-8. Although `OverlayChange` and its options have schemas, a summary is an in-process value containing opaque
-`BytePath` objects. The schema is not a portable summary encoding.
-
-`capture()` returns a complete version 1 snapshot and matching summary from one committed state. Later writes change
-neither result. The snapshot works with `encodeSnapshot`, `fromSnapshot`, and `@effect-vfs/persistence` checkpoints.
-Restoring it recovers the complete filesystem state, not the earlier overlay base relationship or summary. To reset,
-create a fresh overlay from the base and replace your application reference; existing callers, handles, and watches
-remain attached to the old workspace until their own lifetimes end.
-
-The Effects returned by `changes(options)` and `capture(options)` are also reusable. Each execution observes the
-workspace again. Invalid summary options fail with `ConfigurationError`; failure to construct the complete observed
-snapshot fails with `ImageError`. Reusing a previously completed `capture()` result does not observe later writes.
-
-## Store and apply exact snapshot deltas
-
-Use `diffSnapshots` when you need a portable description of the exact difference between two immutable snapshots.
-The result is an opaque `SnapshotDelta`: inspect it for a path-oriented summary, encode it with Effect Schema, or apply
-it to a semantically identical base to reconstruct the target snapshot.
-
-```ts
-import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
-import * as NodeCrypto from "@effect/platform-node/NodeCrypto"
-import { Effect, Schema } from "effect"
-import * as ByteSize from "effect/ByteSize"
-
-const Delta = Vfs.SnapshotDeltaFromBytes()
-
-const program = Effect.gen(function*() {
-  const baseVolume = yield* Vfs.fromFixture({
-    entries: [{ kind: "file", path: "/old.txt", bytes: new TextEncoder().encode("before") }]
-  })
-  const targetVolume = yield* Vfs.fromFixture({
-    entries: [{ kind: "file", path: "/new.txt", bytes: new TextEncoder().encode("after") }]
-  })
-  const base = yield* baseVolume.snapshot
-  const target = yield* targetVolume.snapshot
-
-  const delta = yield* Vfs.diffSnapshots(base, target)
-  const changes = yield* Vfs.inspectSnapshotDelta(base, delta)
-  const bytes = yield* Schema.encodeEffect(Delta)(delta)
-  const decoded = yield* Schema.decodeEffect(Delta)(bytes)
-  const restored = yield* Vfs.applySnapshotDelta(base, decoded)
-
-  return { changes, restored }
-})
-
-await Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer)))
-```
-
-Inspection verifies the delta against its semantic base before reporting what the two snapshots prove. It does not guess renames from equal contents or paths: a move is a
-`Removed` change followed by an `Added` change. `Updated` records identify changed semantic fields, including content,
-metadata, symbolic-link targets, and hard-link topology. Summaries do not contain replay payloads; the opaque delta does.
-
-Each delta records the semantic identity of its required base. Inspecting or applying it against a different valid snapshot fails with a
-`SnapshotDeltaError` whose `code` is `BaseMismatch`. Equivalent snapshots are accepted even if their encoded bytes or
-internal record identifiers differ. Applying a delta returns another immutable `Snapshot`; call `fromSnapshot` when
-you need a writable volume.
-
-Creation, inspection, encoding, decoding, and application use finite `SnapshotDeltaLimits.default` limits when none are supplied.
-Delta creation, inspection, and application require Effect's platform-neutral `Crypto.Crypto` service for SHA-256 base identity.
-Provide the official Node, Bun, browser, or Deno crypto layer at the application edge; the core never imports a host
-crypto implementation. Memory-sensitive applications can use one policy throughout the workflow:
-
-```ts
-const limits = Vfs.SnapshotDeltaLimits.constrained
-const Delta = Vfs.SnapshotDeltaFromBytes(limits)
-
-const constrained = Effect.gen(function*() {
-  const delta = yield* Vfs.diffSnapshots(base, target, limits)
-  const bytes = yield* Schema.encodeEffect(Delta)(delta)
-  const decoded = yield* Schema.decodeEffect(Delta)(bytes)
-  return yield* Vfs.applySnapshotDelta(base, decoded, limits)
-})
-```
-
-Both presets are frozen complete policies. The shipped values are:
-
-| limit                               | `constrained` | `default` |
-| ----------------------------------- | ------------: | --------: |
-| encoded bytes                       |         2 MiB |    16 MiB |
-| canonical identity bytes            |         4 MiB |    32 MiB |
-| stored records plus summary changes |         6,500 |    50,000 |
-| decoded delta bytes                 |       512 KiB |     8 MiB |
-| base records                        |         6,500 |    50,000 |
-| target records                      |         6,500 |    50,000 |
-| namespace entries                   |         6,500 |   100,000 |
-| output records                      |         6,500 |    50,000 |
-| output payload bytes                |       256 KiB |     4 MiB |
-| inherited records                   |         6,500 |    50,000 |
-
-These are conservative finite defaults, not universal workspace-size or memory guarantees. To tune one dimension,
-spread a preset into a complete `SnapshotDeltaLimits` value and replace that field.
-
-```ts
-const limits = {
-  ...Vfs.SnapshotDeltaLimits.default,
-  maxOutputBytes: ByteSize.mebibytes(8)
-}
-```
+Snapshot deltas encode exact changes between compatible images. They have separate decode and application limits;
+check those limits before accepting an untrusted delta. See the
+[snapshot delta API](../../apps/docs/app/content/api/core/snapshot-delta.mdx) for operations and defaults.
 
 ## Use scoped handles for incremental I/O
 
@@ -318,6 +194,7 @@ interruption.
 
 ```ts
 import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
 import { Effect } from "effect"
 
 const program = Effect.scoped(Effect.gen(function*() {
@@ -335,7 +212,7 @@ const program = Effect.scoped(Effect.gen(function*() {
   return [first, second, preview].map((bytes) => new TextDecoder().decode(bytes))
 }))
 
-console.log(await Effect.runPromise(program)) // ["one\n", "two\n", "one"]
+console.log(await Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer)))) // ["one\n", "two\n", "one"]
 ```
 
 Handles also expose an explicit `close` effect when early release matters. Calling explicit close twice fails, while
@@ -349,6 +226,7 @@ expected failures.
 
 ```ts
 import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
 import { Effect } from "effect"
 
 const program = Effect.gen(function*() {
@@ -362,7 +240,7 @@ const program = Effect.gen(function*() {
   )
 })
 
-const bytes = await Effect.runPromise(program)
+const bytes = await Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer)))
 console.log(new TextDecoder().decode(bytes)) // {}
 ```
 
@@ -374,6 +252,7 @@ current directory.
 
 ```ts
 import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
 import { Effect } from "effect"
 
 const loadConfig = Effect.gen(function*() {
@@ -391,7 +270,7 @@ const program = Effect.gen(function*() {
   return yield* loadConfig.pipe(Effect.provideService(Vfs.CurrentFileSystem, fs))
 })
 
-const bytes = await Effect.runPromise(program)
+const bytes = await Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer)))
 console.log(new TextDecoder().decode(bytes)) // {}
 ```
 
@@ -410,9 +289,17 @@ candidate.
 - Components are limited to 255 bytes. Symbolic-link traversal is limited to 40 links.
 - Omitted logical quotas are unbounded by configuration, apart from fixed file and component bounds.
 - Absolute paths ignore a supplied directory base. Relative paths can use a live, same-volume directory handle.
-- Operations coordinate through one permit per volume. Interruption while waiting makes no change; interruption after
-  a commit does not roll it back.
-- Watch streams contain byte paths and report future committed creates, updates, and removals without replay.
+- Operations coordinate through one permit per volume. At most 65 operations are admitted at once by
+  default, including the active operation; set `maxPendingOperations` to change the waiting budget.
+  Excess work fails with retryable `FsError` code `VolumeBusy`
+  before mutation or storage commit. Interruption while waiting makes no change; interruption after a commit
+  does not roll it back.
+- Each watch subscriber retains at most 256 events by default; set `maxWatchEvents` to change this bound
+  (minimum 2). A subscriber that loses events receives `Rescan` with path `/` after its buffered events.
+  Rescan the volume, then continue consuming the watch; repeat the scan if another `Rescan` arrives.
+  Delivered events retain their order. The memory `FileSystem.watch` stream fails with a platform error
+  identified by `MemoryFileSystem.isWatchOverflow`. Open a new watch before rescanning its path so changes
+  during the scan remain observable.
 - `sync` checks handle liveness. An in-memory volume provides no host or crash durability.
 
 For the complete contract, read the

package/dist/BytePath.d.ts

@@ -1,23 +1,55 @@
+/**
+ * Opaque, byte-preserving filesystem paths.
+ *
+ * A `BytePath` stores the exact bytes of a path component so that names which
+ * are not valid UTF-8 survive a round trip through the virtual filesystem.
+ *
+ * @since 0.1.0
+ */
 import type * as Equal from "effect/Equal";
 import type { Pipeable } from "effect/Pipeable";
 import * as Schema from "effect/Schema";
 /**
  * Type identifier for opaque byte-preserving filesystem paths.
  *
- * @category type ids
+ * @category type IDs
  * @since 0.1.0
  */
 export declare const BytePathId: "@effect-vfs/core/BytePath";
 /**
  * Type identifier for opaque byte-preserving filesystem paths.
  *
- * @category type ids
+ * @category type IDs
  * @since 0.1.0
  */
 export type BytePathId = typeof BytePathId;
 /**
  * An opaque path that preserves arbitrary non-NUL bytes without UTF-8 conversion.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+ * import { Effect } from "effect"
+ *
+ * // A name that is not valid UTF-8 still round-trips exactly.
+ * const program = Effect.gen(function*() {
+ *   const caller = yield* (yield* Vfs.make()).caller()
+ *   const path = yield* Vfs.pathFromBytes(new Uint8Array([47, 0xff, 0xfe]))
+ *
+ *   yield* caller.writeFile(path, new Uint8Array([1]), {
+ *     access: "write",
+ *     create: "exclusive"
+ *   })
+ *
+ *   // `readDirectory` fails `UnrepresentableName` here; the byte variant keeps it.
+ *   return yield* caller.readDirectoryBytes("/")
+ * })
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * // [ Uint8Array(2) [ 255, 254 ] ]
+ * ```
+ *
  * @category models
  * @since 0.1.0
  */

package/dist/BytePath.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BytePath.d.ts","sourceRoot":"","sources":["../src/BytePath.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC;;;;;GAKG;AACH,eAAO,MAAM,UAAU,EAAE,2BAAiD,CAAA;AAE1E;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAA;AAE1C;;;;;GAKG;AACH,MAAM,WAAW,QAAS,SAAQ,KAAK,CAAC,KAAK,EAAE,QAAQ;IACrD,QAAQ,CAAC,CAAC,UAAU,CAAC,EAAE,UAAU,CAAA;CAClC;AAED;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,oCAAgD,CAAA"}
+{"version":3,"file":"BytePath.d.ts","sourceRoot":"","sources":["../src/BytePath.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,KAAK,KAAK,MAAM,cAAc,CAAA;AAC1C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC;;;;;GAKG;AACH,eAAO,MAAM,UAAU,EAAE,2BAAiD,CAAA;AAE1E;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,UAAU,CAAA;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,QAAS,SAAQ,KAAK,CAAC,KAAK,EAAE,QAAQ;IACrD,QAAQ,CAAC,CAAC,UAAU,CAAC,EAAE,UAAU,CAAA;CAClC;AAED;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,oCAAgD,CAAA"}

package/dist/BytePath.js

@@ -3,7 +3,7 @@ import * as Internal from "./internal/bytePath.js";
 /**
  * Type identifier for opaque byte-preserving filesystem paths.
  *
- * @category type ids
+ * @category type IDs
  * @since 0.1.0
  */
 export const BytePathId = Internal.BytePathId;

package/dist/LiveVolume.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Image boundary for a storage adapter that commits each live volume mutation.
+ *
+ * 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.
+ *
+ * @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";
+/**
+ * A storage commit's observed outcome.
+ *
+ * @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>;
+    readonly commit: (image: Uint8Array) => Effect.Effect<CommitOutcome>;
+}>;
+/**
+ * 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`.
+ *
+ * @since 0.4.0
+ */
+export declare class LiveImageStore extends LiveImageStore_base {
+}
+/**
+ * Configuration shared by every live-image provider.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface Options {
+    readonly maxImageBytes: ByteSize.ByteSize;
+    readonly volume: VolumeOptions;
+}
+/**
+ * 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.
+ *
+ * @since 0.4.0
+ */
+export declare const open: (options: Options) => Effect.Effect<Volume, LiveVolumeError, LiveImageStore | Crypto.Crypto | Scope.Scope>;
+/**
+ * A live volume and the shutdown action its storage adapter must run before
+ * closing the underlying store.
+ *
+ * @example
+ * ```ts
+ * import type { ImageSession } from "@effect-vfs/core/LiveVolume"
+ *
+ * const shutdown = (session: ImageSession) => session.shutdown
+ * ```
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface ImageSession {
+    readonly volume: Volume;
+    readonly shutdown: Effect.Effect<void>;
+}
+/**
+ * Construct a versioned image for a new, empty volume.
+ * Store this image before opening it for mutation.
+ *
+ * @since 0.4.0
+ */
+export declare const prepareEmptyImage: (options?: VolumeOptions) => Effect.Effect<Uint8Array, ConfigurationError | ImageError | PlatformError.PlatformError, Crypto.Crypto>;
+/**
+ * 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.
+ *
+ * @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 {};
+//# sourceMappingURL=LiveVolume.d.ts.map

package/dist/LiveVolume.d.ts.map

@@ -0,0 +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"}

package/dist/LiveVolume.js

@@ -0,0 +1,72 @@
+/**
+ * Image boundary for a storage adapter that commits each live volume mutation.
+ *
+ * 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.
+ *
+ * @since 0.4.0
+ */
+import { Context, Data, Effect } from "effect";
+import * as ByteSize from "effect/ByteSize";
+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") {
+}
+/**
+ * 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`.
+ *
+ * @since 0.4.0
+ */
+export class LiveImageStore extends Context.Service()("@effect-vfs/core/LiveImageStore") {
+}
+/**
+ * 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.
+ *
+ * @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 })));
+    if (BigInt(initial.length) > ByteSize.toBigInt(options.maxImageBytes)) {
+        return yield* new LiveVolumeError({ code: "InvalidConfiguration" });
+    }
+    const image = yield* store.loadOrCreate(initial);
+    const session = yield* openImage(image, options.maxImageBytes, store.commit).pipe(Effect.mapError((cause) => new LiveVolumeError({ code: "CorruptStore", cause })));
+    yield* Effect.addFinalizer(() => session.shutdown);
+    const volume = session.volume;
+    if (volume.limits.maxEntries !== options.volume.maxEntries || volume.limits.maxBytes === undefined ||
+        volume.limits.maxPathBytes === undefined || options.volume.maxBytes === undefined ||
+        options.volume.maxFileBytes === undefined || options.volume.maxPathBytes === undefined ||
+        ByteSize.toBigInt(volume.limits.maxBytes) !== ByteSize.toBigInt(options.volume.maxBytes) ||
+        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 volume;
+});
+/**
+ * Construct a versioned image for a new, empty volume.
+ * Store this image before opening it for mutation.
+ *
+ * @since 0.4.0
+ */
+export const prepareEmptyImage = Model.prepareEmptyLiveImage;
+/**
+ * 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.
+ *
+ * @since 0.4.0
+ */
+export const openImage = Model.openImageVolume;

package/dist/Snapshot.d.ts

@@ -2,14 +2,14 @@ import * as Schema from "effect/Schema";
 /**
  * Type identifier for opaque filesystem snapshots.
  *
- * @category type ids
+ * @category type IDs
  * @since 0.1.0
  */
 export declare const SnapshotTypeId: "@effect-vfs/core/Snapshot";
 /**
  * Type identifier for opaque filesystem snapshots.
  *
- * @category type ids
+ * @category type IDs
  * @since 0.1.0
  */
 export type SnapshotTypeId = typeof SnapshotTypeId;
@@ -28,6 +28,36 @@ declare const ImageError_base: new <A extends Record<string, any> = {}>(args: im
 /**
  * Describes a snapshot encoding, decoding, structure, or resource-limit failure.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+ * import { ByteSize, Effect } from "effect"
+ *
+ * // Decoding is a trust boundary. `code` says what went wrong and `field` says
+ * // which input or limit it was, so a caller can decline just the bad payload.
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make()
+ *   const bytes = yield* Vfs.encodeSnapshot(yield* volume.snapshot)
+ *
+ *   return yield* Vfs.decodeSnapshot(bytes, {
+ *     maxEncodedBytes: ByteSize.bytes(16),
+ *     maxRecords: 10_000,
+ *     maxEntries: 10_000,
+ *     maxDecodedBytes: ByteSize.megabytes(16)
+ *   }).pipe(
+ *     Effect.as("accepted"),
+ *     Effect.catchTag("ImageError", (error) =>
+ *       error.code === "LimitExceeded"
+ *         ? Effect.succeed(`declined at ${error.field}`)
+ *         : Effect.fail(error))
+ *   )
+ * })
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * // declined at encodedBytes
+ * ```
+ *
  * @category errors
  * @since 0.1.0
  */
@@ -41,6 +71,34 @@ export declare class ImageError extends ImageError_base<{
 /**
  * Schema for the mandatory resource limits applied while decoding a snapshot.
  *
+ * @example
+ * ```ts
+ * import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
+ * import * as NodeCrypto from "@effect/platform-node-shared/NodeCrypto"
+ * import { ByteSize, Effect } from "effect"
+ *
+ * // All four are required: each bounds a different resource. `maxEncodedBytes`
+ * // caps the wire payload before parsing; `maxDecodedBytes` caps memory after it.
+ * const limits: Vfs.DecodeLimits = {
+ *   maxEncodedBytes: ByteSize.megabytes(4),
+ *   maxRecords: 10_000,
+ *   maxEntries: 10_000,
+ *   maxDecodedBytes: ByteSize.megabytes(16)
+ * }
+ *
+ * const program = Effect.gen(function*() {
+ *   const volume = yield* Vfs.make()
+ *   const bytes = yield* Vfs.encodeSnapshot(yield* volume.snapshot)
+ *
+ *   yield* Vfs.decodeSnapshot(bytes, limits)
+ *
+ *   return "accepted"
+ * })
+ *
+ * Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))).then(console.log)
+ * // accepted
+ * ```
+ *
  * @category schemas
  * @since 0.1.0
  */

package/dist/Snapshot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Snapshot.d.ts","sourceRoot":"","sources":["../src/Snapshot.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAG,2BAAoC,CAAA;AAElE;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAA;AAElD;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,cAAc,CAAA;CAC1C;;;;AAED;;;;;GAKG;AACH,qBAAa,UAAW,SAAQ,gBAA+B;IAC7D,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,GAAG,oBAAoB,GAAG,kBAAkB,GAAG,eAAe,CAAA;IAC9F,kFAAkF;IAClF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB,CAAC;CAAG;AAEL;;;;;GAKG;AACH,eAAO,MAAM,YAAY;IACvB,sDAAsD;;IAEtD,6DAA6D;;IAE7D,2CAA2C;;IAE3C,6CAA6C;;EAE7C,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAA"}
+{"version":3,"file":"Snapshot.d.ts","sourceRoot":"","sources":["../src/Snapshot.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAG,2BAAoC,CAAA;AAElE;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAA;AAElD;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,cAAc,CAAA;CAC1C;;;;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,UAAW,SAAQ,gBAA+B;IAC7D,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,GAAG,oBAAoB,GAAG,kBAAkB,GAAG,eAAe,CAAA;IAC9F,kFAAkF;IAClF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB,CAAC;CAAG;AAEL;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,YAAY;IACvB,sDAAsD;;IAEtD,6DAA6D;;IAE7D,2CAA2C;;IAE3C,6CAA6C;;EAE7C,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAA"}