@effect-vfs/core 0.7.1 → 0.9.0

package/README.md

@@ -16,29 +16,17 @@ for the exact permission, path, timestamp, quota, and atomicity rules.
 npm install @effect-vfs/core@latest
 ```
 
-The package declares its exact Effect version as a peer dependency. Volume constructors and snapshot delta functions require Effect’s `Crypto` service. On Node, install the matching
+The package declares its exact Effect version as a peer dependency. Volume constructors and snapshot delta functions require Effect's `Crypto` service. On Node, install the matching
 provider and supply `NodeCrypto.layer` when running these effects:
 
 ```sh
 npm install "@effect/platform-node-shared@$(npm view @effect-vfs/core peerDependencies.effect)"
 ```
 
-## The mental model
-
-The API has three levels:
-
-- A `Volume` owns one isolated namespace and its file contents.
-- A `Caller` accesses that volume with its own identity, umask, and current directory.
-- File and directory handles are scoped capabilities. Effect closes them when their scope ends.
-
-Callers created from the same volume see the same files. A new volume starts with independent state. This separation
-lets you model access by several users without reaching for process globals or the host filesystem.
-
 ## Create an isolated workspace
 
-This example creates a bounded workspace, gives an unprivileged caller access to one directory, and uses a scoped file
-handle to read the result. It demonstrates the main benefit of the core API: storage, credentials, limits, and resource
-lifetime are explicit values that can be composed in one Effect program.
+A volume owns the files. A caller supplies identity, permissions, and a working directory. Scoped handles close when
+their Effect scope ends. This example gives an unprivileged caller access to one directory in a bounded volume.
 
 ```ts
 import { VirtualFileSystem as Vfs } from "@effect-vfs/core"
@@ -89,230 +77,28 @@ callers default to umask `0o022`; the developer's `0o027` mask turns the request
 The root package exports `VirtualFileSystem` as a namespace. The equivalent direct module import is
 `import * as Vfs from "@effect-vfs/core/VirtualFileSystem"`.
 
-## Preserve path bytes exactly
-
-JavaScript strings cannot represent every filename allowed by a byte-oriented filesystem. `BytePath` keeps arbitrary
-non-NUL path bytes intact. This matters when reproducing archives, protocol fixtures, or Unix directory trees that
-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*() {
-  const volume = yield* Vfs.make()
-  const fs = yield* volume.caller()
-
-  // Absolute path whose final component is the single byte 0xff.
-  const opaquePath = yield* Vfs.pathFromBytes(new Uint8Array([0x2f, 0xff]))
-  yield* fs.writeFile(opaquePath, new Uint8Array([1, 2, 3]), {
-    access: "write",
-    create: "exclusive"
-  })
-
-  const listing = yield* fs.readDirectory("/")
-  const roundTrip = yield* Vfs.pathToBytes(opaquePath)
-  return { names: listing.value.map((entry) => Array.from(entry.name)), roundTrip: Array.from(roundTrip) }
-})
-
-console.log(await Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer))))
-// { names: [[255]], roundTrip: [47, 255] }
-```
-
-The constructors and byte-returning operations copy their buffers, so later mutation cannot change stored paths.
-Directory listings, symbolic-link targets, and resolved paths come back as bytes; decoding them to text is the caller's
-choice, and a strict decoder reports a name that is not valid UTF-8.
-
-## Build fixtures and restore snapshots
-
-Fixtures make tests deterministic without a setup sequence. Snapshots let you capture that prepared state, serialize
-it, and create independent workspaces from the same image. This is useful for test isolation, preview environments, and
-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"
-
-const decodeLimits = {
-  maxEncodedBytes: ByteSize.megabytes(1),
-  maxRecords: 1_000,
-  maxEntries: 1_000,
-  maxDecodedBytes: ByteSize.megabytes(1)
-}
-
-const program = Effect.gen(function*() {
-  const template = yield* Vfs.fromFixture({
-    entries: [
-      { kind: "directory", path: "/project" },
-      {
-        kind: "file",
-        path: "/project/settings.json",
-        bytes: new TextEncoder().encode("{\"theme\":\"dark\"}")
-      }
-    ]
-  })
-
-  const encoded = yield* Vfs.encodeSnapshot(yield* template.snapshot)
-  const snapshot = yield* Vfs.decodeSnapshot(encoded, decodeLimits)
-  const workspaceA = yield* Vfs.fromSnapshot(snapshot)
-  const workspaceB = yield* Vfs.fromSnapshot(snapshot)
-  const a = yield* workspaceA.caller()
-  const b = yield* workspaceB.caller()
-
-  yield* a.writeFile("/project/settings.json", new TextEncoder().encode("{\"theme\":\"light\"}"), {
-    access: "write",
-    truncate: true
-  })
-
-  return new TextDecoder().decode(yield* b.readFile("/project/settings.json"))
-})
-
-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
-symbolic links, metadata, and forward hard links.
-
-Snapshot decoding requires explicit work limits because encoded bytes may come from an untrusted source. A snapshot
-contains the reachable namespace and metadata. It excludes callers, open handles, cursor positions, watch
-subscriptions, and unlinked content. Each restored volume is independent.
-
-## Overlays and snapshot deltas
-
-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.
-
-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
+## Confine a caller to a directory
 
-Whole-file operations are convenient, but handles give each open file an independent `bigint` cursor and support
-incremental reads, positional I/O, seeking, and truncation. `Effect.scoped` guarantees cleanup on success, failure, or
-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*() {
-  const fs = yield* (yield* Vfs.make()).caller()
-  yield* fs.writeFile("/events.log", new TextEncoder().encode("one\ntwo\n"), {
-    access: "write",
-    create: "exclusive"
-  })
-
-  const file = yield* fs.open("/events.log", { access: "read" })
-  const first = yield* file.read(4) // Advances this handle's cursor.
-  const second = yield* file.read(4)
-  const preview = yield* file.pread(3, 0n) // Does not move the cursor.
-
-  const decode = (bytes: Uint8Array) => new TextDecoder().decode(bytes)
-
-  // A positioned read also says whether it reached the end of the file.
-  return [decode(first), decode(second), decode(preview.bytes), preview.eof]
-}))
-
-console.log(await Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer)))) // ["one\n", "two\n", "one", false]
-```
-
-Handles also expose an explicit `close` effect when early release matters. Calling explicit close twice fails, while
-scope cleanup remains safe after an explicit close.
-
-## Handle expected failures as data
-
-Every failure is a `VfsError` with a stable `code` and the `operation` that failed. A rejected option names its
-`field`, a path-addressed failure names its `path` as bytes, and a classified failure keeps its `cause`. Codec and
-store failures share the class with their own codes. Interruption and defects remain separate from these 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*() {
-  const fs = yield* (yield* Vfs.make()).caller()
-
-  return yield* fs.readFile("/optional.json").pipe(
-    Effect.catchTag("VfsError", (error) =>
-      error.code === "NotFound"
-        ? Effect.succeed(new TextEncoder().encode("{}"))
-        : Effect.fail(error))
-  )
-})
-
-const bytes = await Effect.runPromise(program.pipe(Effect.provide(NodeCrypto.layer)))
-console.log(new TextDecoder().decode(bytes)) // {}
-```
-
-## Provide a volume and a caller as Effect services
-
-`Volume` and `Caller` are services with static layers. `Volume.layer()` builds a fresh empty volume,
-`Volume.layerFromSnapshot`, `Volume.layerFromFixture` and `Volume.layerOverlay` build one from existing state, and
-`Volume.layerLive` opens a durable one through the `LiveImageStore` in context. `Caller.layer(options)` makes a root
-caller on the volume in context. A caller supplied through the service keeps its original volume, identity, umask and
-working 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*() {
-  const fs = yield* Vfs.Caller
-  return yield* fs.readFile("/app/config.json")
-})
-
-const program = Effect.gen(function*() {
-  const fs = yield* Vfs.Caller
-  yield* fs.mkdir("/app")
-  yield* fs.writeFile("/app/config.json", new TextEncoder().encode("{}"), {
-    access: "write",
-    create: "exclusive"
-  })
-  return yield* loadConfig
-})
-
-const bytes = await Effect.runPromise(
-  program.pipe(Effect.provide(Vfs.Caller.layer()), Effect.provide(Vfs.Volume.layer()), Effect.provide(NodeCrypto.layer))
-)
-console.log(new TextDecoder().decode(bytes)) // {}
-```
+`caller.withRoot(path)` creates a scoped caller whose `/` is that directory. Absolute symlinks and `..` stay
+inside the root. Renaming the root preserves access; deleting it permanently invalidates the caller.
 
-## When to use core or memory
+Keep the caller's scope open and pass only the capabilities the consumer needs. Existing hard links can share
+file contents across roots. See [Confine a workspace](../../apps/docs/app/content/guides/confined-workspaces.mdx)
+for a complete example with Effect's `FileSystem` service and the confinement limits.
 
-Choose `@effect-vfs/core` when you need direct access to volumes, callers, credentials, byte paths, quotas, watches,
-fixtures, or snapshots. Choose `@effect-vfs/memory` when existing code expects Effect's `FileSystem` service and you
-want an in-memory implementation. The memory adapter is built on this core, so you can create a core volume and bind
-the adapter to it when you need both interfaces.
+## Guides and reference
 
-## Compatibility and behavioral limits
+- [Fixtures and snapshots](../../apps/docs/app/content/guides/fixtures-and-snapshots.mdx) covers seeded trees, codecs, and portable deltas.
+- [Overlay workspaces](../../apps/docs/app/content/guides/overlay-filesystems.mdx) covers independent edits and `mergeSnapshotDeltas` conflicts.
+- [Snapshot search](../../apps/docs/app/content/guides/snapshot-search.mdx) covers filename globs, content matches, and bounded results.
+- [Filesystem model](../../apps/docs/app/content/concepts/filesystem-model.mdx) explains callers, handles, permissions, and byte paths.
+- [API reference](../../apps/docs/app/content/api/core/virtual-file-system.mdx) lists constructors, services, and operations.
 
-This package is experimental. Its public API may change between minor releases while Effect v4 remains a release
-candidate.
+## Limits
 
-- 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. 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 `VfsError` 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.
+The package is experimental. Public APIs may change between minor releases.
 
-For the complete contract, read the
-[implemented profile](https://github.com/lloydrichards/effect-virtual-fs/blob/main/.okf/profiles/implemented-filesystem.md).
+Paths preserve arbitrary non-NUL bytes. Components are limited to 255 bytes, and symlink traversal to 40 links.
+Volume options bound entries, file sizes, pending operations, and watch queues. In-memory volumes provide no host or
+crash durability. See [compatibility and limits](../../apps/docs/app/content/reference/compatibility-and-limits.mdx)
+for the complete contract.

package/dist/Caller.d.ts

@@ -230,6 +230,7 @@ export type WalkOptions = typeof WalkOptions.Type;
 /**
  * Schema for the options of `remove`. `recursive` removes a directory and
  * everything under it; `force` succeeds when the target itself is missing.
+ * `expected` pins object identity at each coordinated removal stage. A replacement fails `VolumeBusy`.
  *
  * @category schemas
  * @since 0.6.0
@@ -237,6 +238,7 @@ export type WalkOptions = typeof WalkOptions.Type;
 export declare const RemoveOptions: Schema.Struct<{
     readonly recursive: Schema.optionalKey<Schema.Boolean>;
     readonly force: Schema.optionalKey<Schema.Boolean>;
+    readonly expected: Schema.optionalKey<Schema.suspend<Schema.declare<ObjectReference, ObjectReference>>>;
 }>;
 /**
  * Options of `remove`.

package/dist/Caller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Caller.d.ts","sourceRoot":"","sources":["../src/Caller.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAE7D;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,EAAE,OAAO,MAA8C,CAAA;AAE5E;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAA;AAEtC;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,OAAO,MAAuD,CAAA;AAE9F;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,iBAAiB,CAAA;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ;;;;;EAKnB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAA;AAE3C;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;EAG5B,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,iBAAiB,CAAC,IAAI,CAAA;AAE7D;;;;;;GAMG;AACH,eAAO,MAAM,WAAW;;;;;;EAMtB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC,IAAI,CAAA;AAEjD;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;EAK3B,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,gBAAgB,CAAC,IAAI,CAAA;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,eAAe;;;EAG1B,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC,IAAI,CAAA;AAEzD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;EAMhC,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,OAAO,qBAAqB,CAAC,IAAI,CAAA;AAErE;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;EAKvB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAA;AAEnD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW;;;;;EAKtB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC,IAAI,CAAA;AAEjD;;;;;;GAMG;AACH,eAAO,MAAM,aAAa;;;EAGxB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,IAAI,CAAA;AAErD;;;;;GAKG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;EAEzB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAA;AAEvD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAMzB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAA;AAEvD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,kDAEjC,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAc3B,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,gBAAgB,CAAC,IAAI,CAAA"}
+{"version":3,"file":"Caller.d.ts","sourceRoot":"","sources":["../src/Caller.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAE7D;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,EAAE,OAAO,MAA8C,CAAA;AAE5E;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAA;AAEtC;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,OAAO,MAAuD,CAAA;AAE9F;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,iBAAiB,CAAA;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ;;;;;EAKnB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAA;AAE3C;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;EAG5B,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,iBAAiB,CAAC,IAAI,CAAA;AAE7D;;;;;;GAMG;AACH,eAAO,MAAM,WAAW;;;;;;EAMtB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC,IAAI,CAAA;AAEjD;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;EAK3B,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,gBAAgB,CAAC,IAAI,CAAA;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,eAAe;;;EAG1B,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC,IAAI,CAAA;AAEzD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;EAMhC,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,OAAO,qBAAqB,CAAC,IAAI,CAAA;AAErE;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;EAKvB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAA;AAEnD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW;;;;;EAKtB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,WAAW,CAAC,IAAI,CAAA;AAEjD;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa;;;;EAIxB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,IAAI,CAAA;AAErD;;;;;GAKG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;EAEzB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAA;AAEvD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAMzB,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAA;AAEvD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,kDAEjC,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAc3B,CAAA;AAEF;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,gBAAgB,CAAC,IAAI,CAAA"}

package/dist/Caller.js

@@ -130,13 +130,15 @@ export const WalkOptions = Schema.Struct({
 /**
  * Schema for the options of `remove`. `recursive` removes a directory and
  * everything under it; `force` succeeds when the target itself is missing.
+ * `expected` pins object identity at each coordinated removal stage. A replacement fails `VolumeBusy`.
  *
  * @category schemas
  * @since 0.6.0
  */
 export const RemoveOptions = Schema.Struct({
     recursive: Schema.optionalKey(Schema.Boolean),
-    force: Schema.optionalKey(Schema.Boolean)
+    force: Schema.optionalKey(Schema.Boolean),
+    expected: Schema.optionalKey(Schema.suspend(() => ObjectReferenceSchema))
 });
 /**
  * Schema for the options of `symlink`.

package/dist/LiveVolume.d.ts

@@ -8,8 +8,9 @@
  *
  * @since 0.4.0
  */
-import { Context, Effect } from "effect";
+import { Context, Duration, Effect, Layer } from "effect";
 import * as ByteSize from "effect/ByteSize";
+import type * as Cause from "effect/Cause";
 import type * as Crypto from "effect/Crypto";
 import type * as Scope from "effect/Scope";
 import { type ArgumentFailure, type StoreFailure, VfsError } from "./VfsError.js";
@@ -56,6 +57,73 @@ export interface Options {
  * @since 0.4.0
  */
 export declare const open: (options: Options) => Effect.Effect<Volume, VfsError, LiveImageStore | Scope.Scope | Crypto.Crypto>;
+/**
+ * Scoped access to live volumes shared by canonical storage identity.
+ * Each `get` retains its volume until the borrowing scope closes. Keep that
+ * scope open until its callers and handles finish using the volume.
+ *
+ * @category models
+ * @since 0.9.0
+ */
+export interface Registry<K, E = never> {
+    readonly get: (key: K) => Effect.Effect<Volume, E | VfsError | Cause.ExceededCapacityError, Scope.Scope>;
+}
+/**
+ * Store Layers are built independently for each acquired entry. The same volume
+ * configuration applies to every key. Keys use Effect's equality rules and must
+ * identify canonical storage locations; different aliases can create competing
+ * owners. Coordinate ownership across processes outside this registry.
+ *
+ * @category models
+ * @since 0.9.0
+ */
+export interface RegistryOptions<K, E = never, R = never> {
+    readonly store: (key: K) => Layer.Layer<LiveImageStore, E, R>;
+    readonly volume: Options;
+    /** Positive integer entry limit. Omission means unlimited; idle entries count. */
+    readonly capacity?: number;
+    /** Retain unused entries for this duration. Omission releases them immediately. */
+    readonly idleTimeToLive?: Duration.Input;
+}
+/**
+ * Lazily share one live volume and its store per key through `RcMap`. Concurrent
+ * borrowers share acquisition. Reusing an idle entry avoids rebuilding its store
+ * and decoding its image, while retaining its memory and storage locks.
+ *
+ * The registry's owning scope must outlive all borrowers. Closing it shuts down
+ * every volume, including borrowed ones, before releasing their store Layers.
+ * Capacity exhaustion fails with `Cause.ExceededCapacityError`; it does not evict
+ * idle entries. Acquisition failures remain shared until the entry is released.
+ *
+ * Invalidation is intentionally unavailable: acquiring a replacement while an
+ * existing borrower remains would violate exclusive store ownership. Canonicalize
+ * keys before borrowing and use one registry for each set of backing stores.
+ *
+ * @example
+ * ```ts
+ * import { LiveVolume } from "@effect-vfs/core"
+ * import { ByteSize, Effect, Layer } from "effect"
+ *
+ * declare const storeFor: (key: string) => Layer.Layer<LiveVolume.LiveImageStore>
+ *
+ * const program = Effect.gen(function*() {
+ *   const registry = yield* LiveVolume.makeRegistry({
+ *     store: storeFor,
+ *     volume: { maxImageBytes: ByteSize.megabytes(1), volume: {} },
+ *     capacity: 8,
+ *     idleTimeToLive: "5 seconds"
+ *   })
+ *   return yield* Effect.scoped(Effect.gen(function*() {
+ *     const volume = yield* registry.get("workspace")
+ *     return yield* (yield* volume.caller()).readFile("/plan.md")
+ *   }))
+ * })
+ * ```
+ *
+ * @category constructors
+ * @since 0.9.0
+ */
+export declare const makeRegistry: <K, E, R>(options: RegistryOptions<K, E, R>) => Effect.Effect<Registry<K, E>, ArgumentFailure, R | Crypto.Crypto | Scope.Scope>;
 /**
  * A live volume and the shutdown action its storage adapter must run before
  * closing the underlying store.

package/dist/LiveVolume.d.ts.map

@@ -1 +1 @@
-{"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,MAAM,MAAM,eAAe,CAAA;AAC5C,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;;;;;;;GAOG;AACH,eAAO,MAAM,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC,MAAM,CACpD,MAAM,EACN,QAAQ,EACR,cAAc,GAAG,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,CAuC5C,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;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,EAAE,CAAC,OAAO,CAAC,EAAE,aAAa,KAAK,MAAM,CAAC,MAAM,CACxE,UAAU,EACV,QAAQ,EACR,MAAM,CAAC,MAAM,CAKZ,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,EACR,MAAM,CAAC,MAAM,CACU,CAAA"}
+{"version":3,"file":"LiveVolume.d.ts","sourceRoot":"","sources":["../src/LiveVolume.ts"],"names":[],"mappings":"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"}

package/dist/LiveVolume.js

@@ -8,10 +8,11 @@
  *
  * @since 0.4.0
  */
-import { Context, Effect } from "effect";
+import { Context, Deferred, Duration, Effect, Layer, MutableHashMap, Option, RcMap, Schema } from "effect";
 import * as ByteSize from "effect/ByteSize";
-import { argumentFailure, retargetFailure } from "./internal/errors.js";
+import { argumentFailure, decodeConfiguration, retargetFailure } from "./internal/errors.js";
 import * as Model from "./internal/virtualFileSystem.js";
+import * as Limits from "./internal/volumeLimits.js";
 import { VfsError } from "./VfsError.js";
 /**
  * One exclusively owned store. Its Layer holds the storage resource until the
@@ -31,9 +32,13 @@ export class LiveImageStore extends Context.Service()("@effect-vfs/core/LiveImag
  * @category constructors
  * @since 0.4.0
  */
-export const open = Effect.fn("LiveVolume.open")(function* (options) {
+export const open = Effect.fnUntraced(function* (options) {
     const store = yield* LiveImageStore;
-    const initial = yield* prepareEmptyImage(options.volume).pipe(
+    const { decoded, initial } = yield* Effect.gen(function* () {
+        const decoded = yield* Effect.fromResult(Limits.configuration(options.volume, "LiveVolume.open"));
+        const initial = yield* prepareEmptyImage(decoded.options);
+        return { decoded, initial };
+    }).pipe(
     // Names the nested option that failed, such as `volume.maxEntries`.
     Effect.mapError((cause) => {
         const field = "field" in cause ? cause.field : undefined;
@@ -43,20 +48,92 @@ export const open = Effect.fn("LiveVolume.open")(function* (options) {
         return yield* argumentFailure("LiveVolume.open", "maxImageBytes");
     }
     const image = yield* store.loadOrCreate(initial);
-    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 })));
+    const requested = decoded.limits;
+    const session = yield* Model.openImageVolume(image, options.maxImageBytes, store.commit, store.durability ?? "memory-only", decoded.options).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 ||
-        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)) {
+    if (!Limits.compatible(volume.limits, requested, volume.identity, decoded.identity)) {
         return yield* new VfsError({ code: "IncompatibleStore", operation: "LiveVolume.open" });
     }
     return volume;
 });
+const RegistryCapacity = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1));
+/**
+ * Lazily share one live volume and its store per key through `RcMap`. Concurrent
+ * borrowers share acquisition. Reusing an idle entry avoids rebuilding its store
+ * and decoding its image, while retaining its memory and storage locks.
+ *
+ * The registry's owning scope must outlive all borrowers. Closing it shuts down
+ * every volume, including borrowed ones, before releasing their store Layers.
+ * Capacity exhaustion fails with `Cause.ExceededCapacityError`; it does not evict
+ * idle entries. Acquisition failures remain shared until the entry is released.
+ *
+ * Invalidation is intentionally unavailable: acquiring a replacement while an
+ * existing borrower remains would violate exclusive store ownership. Canonicalize
+ * keys before borrowing and use one registry for each set of backing stores.
+ *
+ * @example
+ * ```ts
+ * import { LiveVolume } from "@effect-vfs/core"
+ * import { ByteSize, Effect, Layer } from "effect"
+ *
+ * declare const storeFor: (key: string) => Layer.Layer<LiveVolume.LiveImageStore>
+ *
+ * const program = Effect.gen(function*() {
+ *   const registry = yield* LiveVolume.makeRegistry({
+ *     store: storeFor,
+ *     volume: { maxImageBytes: ByteSize.megabytes(1), volume: {} },
+ *     capacity: 8,
+ *     idleTimeToLive: "5 seconds"
+ *   })
+ *   return yield* Effect.scoped(Effect.gen(function*() {
+ *     const volume = yield* registry.get("workspace")
+ *     return yield* (yield* volume.caller()).readFile("/plan.md")
+ *   }))
+ * })
+ * ```
+ *
+ * @category constructors
+ * @since 0.9.0
+ */
+export const makeRegistry = Effect.fnUntraced(function* (options) {
+    const capacity = options.capacity === undefined
+        ? Infinity
+        : yield* Effect.fromResult(decodeConfiguration(RegistryCapacity, options.capacity, "LiveVolume.makeRegistry")).pipe(Effect.mapError((cause) => argumentFailure("LiveVolume.makeRegistry", "capacity", cause)));
+    const idleTimeToLive = Duration.fromInput(options.idleTimeToLive ?? 0);
+    if (Option.isNone(idleTimeToLive))
+        return yield* argumentFailure("LiveVolume.makeRegistry", "idleTimeToLive");
+    const store = options.store;
+    const volume = { maxImageBytes: options.volume.maxImageBytes, volume: { ...options.volume.volume } };
+    const retiring = MutableHashMap.empty();
+    const volumes = yield* RcMap.make({
+        lookup: Effect.fnUntraced(function* (key) {
+            // RcMap removes an entry before its asynchronous finalizers finish. Keep
+            // equal keys waiting until both the volume and its store have shut down.
+            yield* Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
+                let previous = MutableHashMap.get(retiring, key);
+                while (Option.isSome(previous)) {
+                    yield* restore(Deferred.await(previous.value));
+                    previous = MutableHashMap.get(retiring, key);
+                }
+                const released = yield* Deferred.make();
+                MutableHashMap.set(retiring, key, released);
+                // Registered first, this runs after the store and volume finalizers.
+                yield* Effect.addFinalizer(() => Effect.gen(function* () {
+                    MutableHashMap.remove(retiring, key);
+                    yield* Deferred.succeed(released, undefined);
+                }));
+            }));
+            // A parent Layer memo must not keep a retired store alive or share its
+            // mutable ownership state with a different volume entry.
+            const services = yield* Layer.build(Layer.fresh(store(key)));
+            return yield* open(volume).pipe(Effect.provideService(LiveImageStore, Context.get(services, LiveImageStore)));
+        }),
+        capacity,
+        idleTimeToLive: idleTimeToLive.value
+    });
+    return { get: (key) => RcMap.get(volumes, key) };
+});
 /**
  * Construct a versioned image for a new, empty volume.
  * Store this image before opening it for mutation.