@opfs-vfs/effect 0.2.0

package/LICENSE.md

@@ -0,0 +1,73 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/README.md

@@ -0,0 +1,211 @@
+# @opfs-vfs/effect
+
+Effect v4 adapter for worker-backed OPFS volumes and direct mounts. Requires `effect@4.0.0-rc.118`.
+
+```ts
+import { Effect } from 'effect';
+import { Volume } from '@opfs-vfs/effect';
+
+const program = Effect.gen(function* () {
+  const volume = yield* Volume.make({ fileName: 'app.bin' });
+  yield* volume.sync;
+  return yield* volume.persistence;
+}).pipe(Effect.scoped);
+```
+
+`OpfsFileSystem.layer` builds the standard `FileSystem` service on a mounted
+`Volume`. It supports scoped file handles, descriptor reads and writes, and
+bounded whole-file helpers up to 16 MiB. Larger files and other open flags use
+descriptor I/O. Use `stream` and `sink` for bounded-memory transfers. See
+`examples/filesystem-stream.ts` for a chunked copy and
+`examples/filesystem-save.ts` for handling persistence errors. A successful
+write does not mean the data is durable; use `Volume.withSync` or await
+`volume.sync` at save boundaries.
+
+### Save boundaries
+
+`effect.pipe(Volume.withSync)` runs the effect, then syncs the `Volume` service
+on success and preserves its value. Its filesystem must use that same volume
+instance. If the wrapped operation fails, defects, or is interrupted, the helper does
+not start its success sync and preserves the original failure. Existing
+cancellation behavior still applies; cancellation can occur after sync dispatch
+and does not guarantee that sync completes.
+A sync failure fails the wrapped effect. Each wrapper syncs once after success,
+including nested wrappers. Wrap a batch once to share its sync cost. There is
+no isolation or rollback, and concurrent writes can also be flushed.
+
+The default balanced mode schedules background synchronization about 150 ms
+after the first dirty change, without restarting the timer for later changes.
+This is not a durability deadline: scheduling, worker suspension, and I/O or
+quota failures can delay or prevent completion. Background failures record a
+persistence error rather than retroactively failing a completed write.
+
+| Approach                                  | Benefit                                             | Cost or limit                                                        |
+| ----------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------- |
+| Background balanced mode                  | Groups nearby writes without awaiting each flush.   | Write success does not acknowledge durability.                       |
+| `Volume.withSync` or manual `volume.sync` | Returns an explicit sync result at a save boundary. | The caller waits for sync and its I/O cost.                          |
+| One wrapper around a batch                | Syncs once after all writes succeed.                | Failure can leave earlier writes applied without the wrapper's sync. |
+
+Disk mode avoids a full RAM copy of file contents, but its OPFS writes and
+metadata still need flushing for confirmation. Balanced background sync applies
+in disk mode too. A confirmed save needs `Volume.withSync` or manual sync in
+either buffer mode; eventual balanced persistence does not require sync after
+each individual write.
+
+Background flushing and explicit boundaries are complementary. Relaxed mode
+defers flushing to explicit sync or orderly close. Strict mode additionally
+flushes memory-mode recovery records, not every disk-mode write. A clean
+`volume.persistence` snapshot does not prove an earlier save survived an owner
+change. See the [Effect guide](https://opfs.dev/docs/effect/) for session lifetime
+and uncertain-save handling.
+
+The adapter also supports path metadata, permissions, links, directory creation,
+listing, removal, rename, recursive copy and volume-local temporary paths.
+Unlike Node's filesystem, operands must be absolute volume paths; relative
+symlink targets are preserved. Recursive copy does not follow symlinks, keeps
+copied relative link targets as written (Node's default copy resolves them to
+the source), is not atomic, and does not preserve hard-link topology. `chown`
+and `glob` remain intentionally unsupported in v1 and return typed `ENOTSUP`
+errors. Scoped temporary paths remove only their private directory
+when the scope closes; the default parent is `/tmp` inside the volume. A temporary
+path uses its resolved physical parent, so retargeting the caller-supplied parent
+symlink does not redirect cleanup. Ownership covers the created root pathname and
+its current descendants; cleanup is not an atomic inode-identity check. Keep the
+resolved physical ancestors stable until cleanup completes. Shutdown, owner
+replacement, or cleanup failure can leave temporary paths for explicit reclamation.
+
+`FileSystem.watch` uses the same logical-change registration and cleanup path as
+rich subscriptions. It checks the target when the stream is acquired: a missing
+path fails with `NotFound`, and a symlink target fails with `BadResource`. It
+watches regular files or directories and emits absolute volume paths as
+`Create`, `Update`, or `Remove`. Recursive directory watching preserves the
+native descendant records for directory renames; symlink entries inside a
+watched directory are reported, but a symlink target is not followed.
+
+Watch notifications are hints, not a replayable log. Preflight checks and
+directory scans are not atomic snapshots; logical event counts and ordering can
+differ from native operating-system watchers. Reconciliation marks its view
+stale when stream consumption observes a failure, so that callback can lag the
+terminal notification. A takeover ends the stream
+with `Unknown` and a `SubscriptionError` whose code is
+`SUBSCRIPTION_INTERRUPTED`; the standard API does not silently resubscribe.
+Readiness and retirement timeouts map to `TimedOut`. Use a bounded retry only
+when the application also invalidates and reconciles its current view. The
+standard watch API has no registration-ready signal, so use rich subscriptions
+when a view must subscribe before its initial scan. See
+`examples/reconciled-view.ts` for subscribe-before-scan recovery with bounded
+retries and retirement waiting. Its three-retry budget resets after a fresh scan
+is successfully published.
+
+`Subscriptions.layer` provides the Effect subscriptions service when the mounted
+volume has the compatible logical-change capability. Worker mounts request it
+with `subscriptionsRequest()`; direct mounts configure a logical-change plugin.
+Without that capability, layer acquisition fails with a typed unsupported
+`VolumeError`.
+
+```ts
+import { Effect, Layer, Stream } from 'effect';
+import { Subscriptions, Volume } from '@opfs-vfs/effect';
+import { subscriptionsRequest } from '@opfs-vfs/plugin-subscriptions/config';
+
+const liveLayer = Layer.provide(
+  Subscriptions.layer,
+  Volume.layer({ fileName: 'app.bin', plugins: () => [subscriptionsRequest()] }),
+);
+
+const observe = Effect.scoped(
+  Effect.gen(function* () {
+    const subscriptions = yield* Subscriptions.Subscriptions;
+    const subscription = yield* subscriptions.subscribe({ path: '/', scope: 'directory', recursive: true });
+    yield* Stream.runForEach(subscription.changes, (change) => Effect.sync(() => console.log(change.path)));
+  }),
+).pipe(Effect.provide(liveLayer));
+```
+
+Each `changes` stream can be consumed once. Stream completion, interruption, or
+scope close unsubscribes it; `retired` can be evaluated repeatedly to read the
+same released or unknown cleanup result. The stream has bounded delivery and
+preserves terminal subscription errors. It has no initial snapshot or replay;
+subscribe before scanning and reconcile notifications received during the scan.
+See `examples/subscriptions.ts` for a complete worker-backed example.
+
+The adapter buffers at most 16 changes and permits one additional producer
+offer to wait; a terminal error clears buffered changes and fails the stream.
+Content capture is off by default (`content: false`). The adapter queue and its
+one pending offer retain up to 17 * `maxBytes` of included payloads, in addition
+to source buffers and any data a caller retains. If retirement is unknown,
+new subscriptions on that same owner generation fail until the volume observes
+a different ready generation. Recreating a handle in the same generation does
+not clear the barrier; a new generation does, while an old handle's `retired`
+result remains unchanged. Direct mounts cannot observe a new owner generation,
+so an unknown retirement requires remounting.
+
+```ts
+import { Effect, FileSystem, Layer } from 'effect';
+import { OpfsFileSystem, Volume } from '@opfs-vfs/effect';
+
+const FileSystemLive = Layer.provideMerge(OpfsFileSystem.layer, Volume.layer({ fileName: 'app.bin' }));
+
+const app = Effect.gen(function* () {
+  const fs = yield* FileSystem.FileSystem;
+  yield* fs.writeFileString('/note.txt', 'Hello');
+}).pipe(Volume.withSync, Effect.provide(FileSystemLive));
+```
+
+`make` and `layer` own a worker client in the current `Scope`. The bundled
+dedicated worker registers the subscriptions plugin; request it with
+`plugins: () => [subscriptionsRequest()]`. Other plugin requests require a
+custom worker that registers those plugins. A supplied SharedWorker factory is
+required for `transport: 'shared-worker'`; that worker must register the same
+requested plugins. `auto` retains the core worker's dedicated fallback behavior.
+
+`makeDirect` and `layerDirect` own a direct backend in the current `Scope` and
+must run where OPFS synchronous access handles are available. Configured direct
+plugins must be created by a fresh `plugins` thunk for each acquisition.
+`unsafeBackend` only borrows that backend: do not call `closeVfs`, and do not use
+it after the owning scope closes.
+
+`examples/worker-session.ts` is a runnable worker-backed save/read session.
+`examples/direct.ts` shows the direct API.
+
+`examples/encrypted-session.ts` shows an application-owned worker that registers
+encryption and subscriptions, inspects before opening an existing encrypted
+volume, and keeps one `ManagedRuntime` for the session. Its save controller
+serializes work and credential replacement, preserves use and disposal exits,
+and never replays the failed save. Closing stops admission immediately, abandons
+a pending credential prompt, ignores late answers, and waits for runtime disposal.
+The creation helper is the only path that
+accepts an initial passkey. Its controller config must match the initial
+runtime's file name, profile, and plugin order; a replacement supplies a new
+secret only. The paired
+`examples/encrypted-session.worker.ts` is application code; the base adapter
+does not depend on the premium encryption package.
+
+An existing unlocked owner can accept a follower without authenticating that
+follower's secret. The secret is checked only if the follower takes ownership,
+which can then fail. `Redacted` protects display while wrapped, but requests
+and layers can retain revealed secrets and do not zeroize them. Mounting does
+not encrypt or migrate existing plaintext storage; no format migration is
+introduced here.
+
+The encrypted packed check is explicit and requires a reviewed local candidate:
+
+```sh
+OPFS_VFS_ENCRYPTION_TARBALL=/absolute/path/plugin-encryption.tgz \
+OPFS_VFS_ENCRYPTION_SHA256=<sha256> pnpm --filter @opfs-vfs/effect test:encrypted-packed
+```
+
+### Conformance and release preparation
+
+Run the shared Node, direct-worker, and worker-backed filesystem contract from
+the repository root with
+`OPFS_VFS_TEST_BROWSER=chromium pnpm --filter @opfs-vfs/effect test:conformance`;
+set the browser variable to `webkit` for the second browser engine. Node's
+`@effect/platform-node` adapter is a development-only test dependency and is
+loaded only by the separate Node test configuration.
+
+These checks validate the exact local workspace candidates. A Changesets
+preview or local tarball is not a published release. Final registry peer ranges
+and the private encryption package's core pin must be checked against the
+versioned core release before claiming released-package compatibility; this
+test command does not version or publish packages.

package/dist/coordinator.d.ts

@@ -0,0 +1,50 @@
+import { Deferred, Effect, Semaphore } from 'effect';
+import type { Scope } from 'effect';
+import type { OpfsVfs } from '@opfs-vfs/opfs-vfs';
+import type { OpfsVfsWorkerClient } from '@opfs-vfs/opfs-vfs/worker-client';
+import type { VolumeService } from './volume.js';
+import type { VolumeError } from './errors.js';
+export type Backend = OpfsVfs | OpfsVfsWorkerClient;
+export type Continuity = {
+    readonly _tag: 'clean';
+} | {
+    readonly _tag: 'pending';
+    readonly generation: string;
+} | {
+    readonly _tag: 'lost';
+    readonly generation: string;
+};
+export interface SubscriptionSetupRecord {
+    readonly generation: string;
+    readonly closed: Promise<{
+        readonly status: 'released';
+    } | {
+        readonly status: 'unknown';
+        readonly error: unknown;
+    }>;
+    state: 'active' | 'retiring';
+}
+export interface Coordinator {
+    readonly backend: Backend;
+    readonly scope?: Scope.Scope;
+    readonly fileName: string;
+    readonly isClosed: () => boolean;
+    readonly currentGeneration: () => string | undefined;
+    readonly canRecapture: () => boolean;
+    readonly readinessTimeout: number;
+    readonly subscriptionsAvailable: boolean;
+    readonly terminal: () => VolumeError | undefined;
+    readonly awaitReady: (budget: {
+        remaining: number;
+    }, operation: string) => Effect.Effect<string, VolumeError>;
+    readonly gate: Semaphore.Semaphore;
+    readonly terminalSignal: Deferred.Deferred<VolumeError>;
+    readonly files: Set<() => Effect.Effect<void>>;
+    readonly subscriptionSetups: Map<SubscriptionSetupRecord['closed'], SubscriptionSetupRecord>;
+    readonly subscriptionUnknown: Map<string, unknown>;
+    continuity: Continuity;
+}
+export declare const makeCoordinator: (options: Omit<Coordinator, 'gate' | 'terminalSignal' | 'continuity' | 'files' | 'subscriptionSetups' | 'subscriptionUnknown'>) => Coordinator;
+export declare const registerCoordinator: (service: VolumeService, coordinator: Coordinator) => void;
+export declare const getCoordinator: (service: VolumeService) => Coordinator | undefined;
+export declare const latchTerminal: (coordinator: Coordinator, error: VolumeError) => void;

package/dist/errors.d.ts

@@ -0,0 +1,76 @@
+import { Schema } from 'effect';
+export declare const RemoteErrorDetails: Schema.Struct<{
+    readonly message: Schema.String;
+    readonly name: Schema.optionalKey<Schema.String>;
+    readonly code: Schema.optionalKey<Schema.String>;
+    readonly errno: Schema.optionalKey<Schema.Number>;
+    readonly category: Schema.optionalKey<Schema.Literals<readonly ["meta-snapshot", "data-wal", "bitmap", "meta-log", "format-version"]>>;
+    readonly offset: Schema.optionalKey<Schema.Number>;
+}>;
+export interface RemoteErrorDetails extends Schema.Schema.Type<typeof RemoteErrorDetails> {
+}
+export type ErrorOutcome = 'not-applied' | 'possibly-applied' | 'unknown';
+export type VolumeErrorKind = 'configuration' | 'unsupported' | 'filesystem' | 'conflict' | 'quota' | 'corruption' | 'encryption' | 'lifecycle' | 'subscription' | 'persistence' | 'unknown';
+declare const VolumeError_base: Schema.Class<VolumeError, Schema.TaggedStruct<"VolumeError", {
+    readonly fileName: Schema.NullOr<Schema.String>;
+    readonly operation: Schema.String;
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly code: Schema.optionalKey<Schema.String>;
+    readonly outcome: Schema.Literals<readonly ["not-applied", "possibly-applied", "unknown"]>;
+    readonly details: Schema.NullOr<Schema.Struct<{
+        readonly message: Schema.String;
+        readonly name: Schema.optionalKey<Schema.String>;
+        readonly code: Schema.optionalKey<Schema.String>;
+        readonly errno: Schema.optionalKey<Schema.Number>;
+        readonly category: Schema.optionalKey<Schema.Literals<readonly ["meta-snapshot", "data-wal", "bitmap", "meta-log", "format-version"]>>;
+        readonly offset: Schema.optionalKey<Schema.Number>;
+    }>>;
+    readonly cause: Schema.optionalKey<Schema.Defect>;
+    readonly kind: Schema.Literals<readonly ["configuration", "unsupported", "filesystem", "conflict", "quota", "corruption", "encryption", "lifecycle", "subscription", "persistence", "unknown"]>;
+}>, import("effect/Cause").YieldableError>;
+export declare class VolumeError extends VolumeError_base {
+}
+declare const EncryptionError_base: Schema.Class<EncryptionError, Schema.TaggedStruct<"EncryptionError", {
+    readonly fileName: Schema.NullOr<Schema.String>;
+    readonly operation: Schema.String;
+    readonly path: Schema.optionalKey<Schema.String>;
+    readonly code: Schema.optionalKey<Schema.String>;
+    readonly outcome: Schema.Literals<readonly ["not-applied", "possibly-applied", "unknown"]>;
+    readonly details: Schema.NullOr<Schema.Struct<{
+        readonly message: Schema.String;
+        readonly name: Schema.optionalKey<Schema.String>;
+        readonly code: Schema.optionalKey<Schema.String>;
+        readonly errno: Schema.optionalKey<Schema.Number>;
+        readonly category: Schema.optionalKey<Schema.Literals<readonly ["meta-snapshot", "data-wal", "bitmap", "meta-log", "format-version"]>>;
+        readonly offset: Schema.optionalKey<Schema.Number>;
+    }>>;
+    readonly cause: Schema.optionalKey<Schema.Defect>;
+    readonly reason: Schema.Literals<readonly ["CredentialsRejected", "KeyDerivationFailed", "VaultCorrupt", "UnsupportedFormat", "SidecarCorrupt", "IntegrityFailure", "PlaintextVolume"]>;
+}>, import("effect/Cause").YieldableError>;
+export declare class EncryptionError extends EncryptionError_base {
+}
+export type SubscriptionErrorCode = 'SUBSCRIPTION_OVERFLOW' | 'SUBSCRIPTION_INTERRUPTED' | 'SUBSCRIPTION_CALLBACK_FAILED' | 'SUBSCRIPTION_RESYNC_REQUIRED' | 'SUBSCRIPTION_RETIREMENT_UNKNOWN' | 'SUBSCRIPTION_SETUP_FAILED' | 'EINVAL' | 'EBADF';
+declare const SubscriptionError_base: Schema.Class<SubscriptionError, Schema.TaggedStruct<"SubscriptionError", {
+    readonly code: Schema.Literals<readonly ["SUBSCRIPTION_OVERFLOW", "SUBSCRIPTION_INTERRUPTED", "SUBSCRIPTION_CALLBACK_FAILED", "SUBSCRIPTION_RESYNC_REQUIRED", "SUBSCRIPTION_RETIREMENT_UNKNOWN", "SUBSCRIPTION_SETUP_FAILED", "EINVAL", "EBADF"]>;
+    readonly fileName: Schema.String;
+    readonly path: Schema.String;
+    readonly sourceCode: Schema.optionalKey<Schema.String>;
+    readonly details: Schema.NullOr<Schema.Struct<{
+        readonly message: Schema.String;
+        readonly name: Schema.optionalKey<Schema.String>;
+        readonly code: Schema.optionalKey<Schema.String>;
+        readonly errno: Schema.optionalKey<Schema.Number>;
+        readonly category: Schema.optionalKey<Schema.Literals<readonly ["meta-snapshot", "data-wal", "bitmap", "meta-log", "format-version"]>>;
+        readonly offset: Schema.optionalKey<Schema.Number>;
+    }>>;
+    readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+export declare class SubscriptionError extends SubscriptionError_base {
+}
+export declare const MountError: Schema.Union<readonly [typeof VolumeError, typeof EncryptionError]>;
+export type MountError = typeof MountError.Type;
+export declare const remoteDetails: (error: unknown) => RemoteErrorDetails;
+export declare const classify: (details: RemoteErrorDetails) => VolumeErrorKind;
+export declare const volumeError: (error: unknown, fileName: string | null, operation: string, kind?: VolumeErrorKind, outcome?: ErrorOutcome, path?: string) => VolumeError;
+export declare const mountError: (error: unknown, fileName: string | null, operation: string, kind?: VolumeErrorKind, outcome?: ErrorOutcome) => MountError;
+export {};

package/dist/errors.js

@@ -0,0 +1,159 @@
+import { Schema as e } from "effect";
+//#region src/errors.ts
+var t = [
+	"meta-snapshot",
+	"data-wal",
+	"bitmap",
+	"meta-log",
+	"format-version"
+], n = e.Struct({
+	message: e.String,
+	name: e.optionalKey(e.String),
+	code: e.optionalKey(e.String),
+	errno: e.optionalKey(e.Number),
+	category: e.optionalKey(e.Literals(t)),
+	offset: e.optionalKey(e.Number)
+}), r = {
+	fileName: e.NullOr(e.String),
+	operation: e.String,
+	path: e.optionalKey(e.String),
+	code: e.optionalKey(e.String),
+	outcome: e.Literals([
+		"not-applied",
+		"possibly-applied",
+		"unknown"
+	]),
+	details: e.NullOr(n),
+	cause: e.optionalKey(e.Defect())
+}, i = class extends e.TaggedError()("VolumeError", {
+	kind: e.Literals([
+		"configuration",
+		"unsupported",
+		"filesystem",
+		"conflict",
+		"quota",
+		"corruption",
+		"encryption",
+		"lifecycle",
+		"subscription",
+		"persistence",
+		"unknown"
+	]),
+	...r
+}) {}, a = class extends e.TaggedError()("EncryptionError", {
+	reason: e.Literals([
+		"CredentialsRejected",
+		"KeyDerivationFailed",
+		"VaultCorrupt",
+		"UnsupportedFormat",
+		"SidecarCorrupt",
+		"IntegrityFailure",
+		"PlaintextVolume"
+	]),
+	...r
+}) {}, o = class extends e.TaggedError()("SubscriptionError", {
+	code: e.Literals([
+		"SUBSCRIPTION_OVERFLOW",
+		"SUBSCRIPTION_INTERRUPTED",
+		"SUBSCRIPTION_CALLBACK_FAILED",
+		"SUBSCRIPTION_RESYNC_REQUIRED",
+		"SUBSCRIPTION_RETIREMENT_UNKNOWN",
+		"SUBSCRIPTION_SETUP_FAILED",
+		"EINVAL",
+		"EBADF"
+	]),
+	fileName: e.String,
+	path: e.String,
+	sourceCode: e.optionalKey(e.String),
+	details: e.NullOr(n),
+	cause: e.optionalKey(e.Defect())
+}) {}, s = e.Union([i, a]), c = (e, t) => {
+	try {
+		return Reflect.get(e, t);
+	} catch {
+		return;
+	}
+}, l = (e) => {
+	let n = e !== null && (typeof e == "object" || typeof e == "function") ? e : null, r = n ? c(n, "message") : void 0, i = (e) => {
+		if (e.length <= 1024) return e;
+		let t = 1023, n = e.charCodeAt(t - 1);
+		return n >= 55296 && n <= 56319 && t--, `${e.slice(0, t)}…`;
+	}, a;
+	if (typeof r == "string") a = i(r);
+	else try {
+		a = i(String(e));
+	} catch {
+		a = "Unknown VFS error";
+	}
+	let o = n ? c(n, "name") : void 0, s = n ? c(n, "code") : void 0, l = n ? c(n, "errno") : void 0, u = n ? c(n, "category") : void 0, d = n ? c(n, "offset") : void 0;
+	return {
+		message: a,
+		...typeof o == "string" && /^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(o) && o !== "Error" ? { name: o } : {},
+		...typeof s == "string" && /^[A-Z][A-Z0-9_]{0,63}$/.test(s) ? { code: s } : {},
+		...typeof l == "number" && Number.isSafeInteger(l) ? { errno: l } : {},
+		...typeof u == "string" && t.includes(u) ? { category: u } : {},
+		...typeof d == "number" && Number.isSafeInteger(d) && d >= 0 ? { offset: d } : {}
+	};
+}, u = /* @__PURE__ */ new Set([
+	"VFS_SHUTTING_DOWN",
+	"VFS_ATTACHMENT_LOST",
+	"VFS_PROTOCOL_MISMATCH",
+	"VFS_PLUGIN_MISMATCH",
+	"VFS_NOT_LEADER",
+	"VFS_LEADER_NOT_READY",
+	"VFS_WORKER_FAILED",
+	"VFS_INITIALIZATION_TIMEOUT",
+	"VFS_OWNER_READY_TIMEOUT",
+	"LEADER_RESPONSE_TIMEOUT",
+	"VOLUME_IMPORTING"
+]), d = {
+	EVOLUMELOCKED: "CredentialsRejected",
+	EKDF: "KeyDerivationFailed",
+	EVAULTCORRUPT: "VaultCorrupt",
+	EVAULTFORMAT: "UnsupportedFormat",
+	ECRYPTSIDECAR: "SidecarCorrupt",
+	ECRYPTOINTEGRITY: "IntegrityFailure",
+	EPLAINTEXTVOLUME: "PlaintextVolume"
+}, f = (e) => {
+	let { code: t, category: n, name: r } = e;
+	return t === "VFS_WORKER_FACTORY_FAILED" ? "configuration" : n || [
+		"VfsCorruptionError",
+		"MetaSnapshotCorruptionError",
+		"DataWalCorruptionError"
+	].includes(r ?? "") ? "corruption" : t && d[t] ? "encryption" : t === "VFS_STORAGE_PLUGIN_REQUIRED" ? "unsupported" : t === "VFS_SYNC_OWNER_CHANGED" || t === "VFS_ACK_OWNER_CHANGED" ? "persistence" : t === "VFS_SUBSCRIPTION_RETIREMENT_TIMEOUT" ? "subscription" : t && u.has(t) ? "lifecycle" : t?.startsWith("SUBSCRIPTION_") ? "subscription" : t === "ENOSPC" || r === "QuotaExceededError" ? "quota" : t === "EEXIST" ? "conflict" : /^E[A-Z0-9]+$/.test(t ?? "") ? "filesystem" : "unknown";
+}, p = (t) => {
+	try {
+		return e.is(i)(t) || e.is(a)(t) || e.is(o)(t) ? t : void 0;
+	} catch {
+		return;
+	}
+}, m = (e, t, n, r, a = "unknown", o) => {
+	let s = l(e), c = p(e), u = {
+		fileName: typeof t == "string" ? t : null,
+		operation: n,
+		...o === void 0 ? {} : { path: o },
+		...s.code ? { code: s.code } : {},
+		outcome: a,
+		details: s,
+		...c === void 0 ? {} : { cause: c }
+	}, d = f(s);
+	return new i({
+		kind: r === "configuration" ? r : d === "unknown" ? r ?? d : d,
+		...u
+	});
+}, h = (e, t, n, r, i = "unknown") => {
+	let o = l(e), s = f(o), c = r === "configuration" || s === "unknown" ? r : s, u = c === "configuration" ? void 0 : o.code ? d[o.code] : void 0;
+	if (!u) return m(e, t, n, c, i);
+	let h = p(e);
+	return new a({
+		reason: u,
+		fileName: t,
+		operation: n,
+		...o.code ? { code: o.code } : {},
+		outcome: i,
+		details: o,
+		...h === void 0 ? {} : { cause: h }
+	});
+};
+//#endregion
+export { a as EncryptionError, s as MountError, n as RemoteErrorDetails, o as SubscriptionError, i as VolumeError, f as classify, h as mountError, l as remoteDetails, m as volumeError };

package/dist/filesystem.d.ts

@@ -0,0 +1,9 @@
+import { FileSystem, Layer } from 'effect';
+import { Volume } from './volume.js';
+import type { VolumeService } from './volume.js';
+declare const make: (volume: VolumeService) => FileSystem.FileSystem;
+export declare const OpfsFileSystem: {
+    readonly make: typeof make;
+    readonly layer: Layer.Layer<FileSystem.FileSystem, never, Volume>;
+};
+export {};

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * as Volume from './volume.js';
+export * as Subscriptions from './subscriptions.js';
+export { OpfsFileSystem } from './filesystem.js';
+export { EncryptionError, MountError, RemoteErrorDetails, SubscriptionError, VolumeError } from './errors.js';
+export type { ErrorOutcome, SubscriptionErrorCode, VolumeErrorKind } from './errors.js';
+export type { PersistenceSnapshot, VolumeService, DirectMountOptions, WorkerMountOptions } from './volume.js';