@statewalker/cellb 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikhail Kotelnikov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,324 @@
-# Temporary Holding Version
+# @statewalker/cellb
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+cellb is a Durable Objects runtime written in TypeScript that runs the same Workers code in a
+browser and in Node. A Worker module and its Durable Object classes, unmodified, get synchronous
+SQLite storage, input and output gates, stubs with `fetch` and RPC, alarms, WebSockets, Worker
+Loaders and facets. In a browser the cells live in SQLite on OPFS inside Dedicated Workers and are
+reached through a ServiceWorker; in Node they live in `node:sqlite`. Cells are stored exactly as
+celld stores them, so one cell can move between cellb in a browser, cellb in Node and celld nodes
+through one bucket.
+
+## Why it exists
+
+Workers and Durable Objects normally need a server: Cloudflare, workerd (which Miniflare wraps) or
+celld, all native binaries. That leaves out a browser tab, which can hold durable state in OPFS
+but cannot run a binary, accept a socket, or start a server. cellb is the runtime written for that
+constraint: pure TypeScript, synchronous SQLite through WebAssembly, HTTP through a ServiceWorker,
+WebSockets over MessagePorts. The same core runs in Node, so a project behaves the same on both.
+
+celld is the reference, not an afterthought. cellb answers every recorded celld request the same
+way, stores cells in celld's format, and speaks celld's ownership and peer protocols, so a fleet can
+mix celld nodes, cellb nodes and browsers.
+
+## How to use it
+
+```sh
+npm install @statewalker/cellb
+npm install esbuild   # for loadNodeProject and bundleWorkerForBrowser (an optional peer dependency)
+```
+
+The package has three entry points, one per platform, and two more for bundling. Published, it is
+JavaScript with type declarations (`dist/`, built by `scripts/build.mjs`); in this repository the
+entry points are the TypeScript sources, which the workspace's examples and tests import directly.
+In a browser app, a bundler must handle `new Worker(new URL("…", import.meta.url))`: the LTX store
+worker is started that way (checked with a Vite build, see `scripts/pack-check.mjs`).
+
+| Import | What it gives |
+|---|---|
+| `@statewalker/cellb` | the runtime (`createCellRuntime`, `createProjectRuntime`), `DurableObject` and `WorkerEntrypoint`, the ports and `CellStorage`, `celldBucket`, the object stores (`s3ObjectStore`, `memoryObjectStore`, `filesApiObjectStore`), `filesApiLtxLog`, `filesApiChangeLog`, `filesApiBackup`, `wasmMemoryOpener` (in-memory SQLite WASM), links over ports, `CellRouter`, `createShardWorker`, the WebSocket classes, and the errors embedders catch |
+| `@statewalker/cellb/node` | `nodeSqliteOpener`, `sqliteObjectStore` (celld dev's local bucket), `loadNodeProject`, `applyNodeD1Migrations`, and celld's peer protocol (`startCelldPeerServer`, `celldPeers`) |
+| `@statewalker/cellb/browser` | `browserProjectRuntime`, `startProjectShards`, `joinProjectShards` and `serveProjectShard` (shards in workers and tabs), `installProjectRouter` (the ServiceWorker side), `sahpoolOpener`, `idbObjectStore`, `createProjectSite`, `serviceWorkerConnector` |
+| `@statewalker/cellb/host-modules` | for bundlers other than cellb's own (webrun-bundler in a browser, say): the sources of `cloudflare:workers`, `node:*` and the Workers globals as cellb's realms provide them (`cellbHostModule`, `CELLS_GLOBALS_MODULE`) |
+| `@statewalker/cellb/isolate-worker` | the Dedicated Worker that runs a Worker-Loader Worker in a realm of its own (`isolateScript`) |
+
+Node 22.13 or later is needed for `node:sqlite`. `loadNodeProject` bundles a project with
+`esbuild`, which the embedder must install.
+
+A runtime is a `(Request) ⇒ Response` handler: mount `runtime.fetch` on `node:http`, a
+ServiceWorker or a test, and call `runtime.close()` when done. `close()` takes final backups,
+closes every database, then closes the storage.
+
+## Examples
+
+### A Worker and a Durable Object in Node
+
+```ts
+import { createCellRuntime, DurableObject } from "@statewalker/cellb";
+import { nodeSqliteOpener } from "@statewalker/cellb/node";
+
+class Counter extends DurableObject {
+  increment(): number {
+    const sql = this.ctx.storage.sql;
+    sql.exec("CREATE TABLE IF NOT EXISTS c (id INTEGER PRIMARY KEY, n INTEGER)");
+    sql.exec("INSERT INTO c (id, n) VALUES (1, 1) ON CONFLICT(id) DO UPDATE SET n = n + 1");
+    return sql.exec<{ n: number }>("SELECT n FROM c WHERE id = 1").one().n;
+  }
+}
+
+const runtime = createCellRuntime({
+  worker: {
+    Counter,
+    default: {
+      fetch: async (req: Request, env: any) =>
+        Response.json({ n: await env.COUNTER.getByName(new URL(req.url).pathname).increment() }),
+    },
+  },
+  durableObjects: { COUNTER: { className: "Counter" } },
+  openSql: nodeSqliteOpener("./data"), // a file per cell in an existing directory; () = in memory
+});
+const res = await runtime.fetch(new Request("http://local/counter/a")); // {"n":1}
+await runtime.close();
+```
+
+### A wrangler project on a bucket shared with celld
+
+```ts
+import { celldBucket } from "@statewalker/cellb";
+import { loadNodeProject, nodeSqliteOpener, sqliteObjectStore } from "@statewalker/cellb/node";
+import { MemFilesApi } from "@statewalker/webrun-files-mem";
+
+const dir = "./counter"; // wrangler.jsonc and its `main`
+const { runtime, unsupported } = await loadNodeProject(dir, {
+  openSql: nodeSqliteOpener(), // in memory: every cell is restored from the bucket on first use
+  files: new MemFilesApi(), // blob store for large KV values
+  storage: celldBucket(sqliteObjectStore(`${dir}/.celld/dev/objects.sqlite3`), { node: "cellb-1" }),
+});
+console.log(unsupported); // configuration entries cellb does not support, e.g. []
+await runtime.fetch(new Request("http://localhost/increment?name=a"));
+await runtime.close(); // releases the cells, so celld can take them at once
+```
+
+`sqliteObjectStore` is the bucket `celld dev` keeps in that file. A fleet on S3 uses
+`s3ObjectStore({ endpoint, bucket, prefix, region, accessKeyId, secretAccessKey })` instead.
+
+A project with a Workers AI binding (`"ai": { "binding": "AI" }`) needs an OpenAI-compatible
+endpoint behind it (llama.cpp, Ollama, a hosted API); without one, `ai` is in `unsupported`:
+
+```ts
+const { runtime } = await loadNodeProject(dir, {
+  openSql: nodeSqliteOpener(),
+  files: new MemFilesApi(),
+  ai: {
+    baseUrl: "http://127.0.0.1:8080/v1",
+    apiKey: process.env.LLM_KEY, // optional
+    models: { "@cf/meta/llama-3.3-70b-instruct-fp8-fast": "llama3", "*": "llama3" },
+  },
+});
+```
+
+`env.AI.run(model, inputs, options)` then answers text generation (`{ prompt }` or
+`{ messages, tools?, stream? }`, in Workers AI's `{ response, tool_calls, usage }` shape or its
+`data: {"response": …}` stream), the endpoint's own response with `returnRawResponse` (Flue's
+`cloudflare` provider reads it), and embeddings (`{ text }`); other model kinds throw an `AiError`.
+`browserProjectRuntime`, `startProjectShards` and `joinProjectShards` take the same `ai`.
+
+### A wrangler project in a browser worker
+
+```ts
+// in a Dedicated Worker
+import sqlite3InitModule from "@sqlite.org/sqlite-wasm";
+import { browserProjectRuntime } from "@statewalker/cellb/browser";
+
+const host = await browserProjectRuntime({
+  config, // the parsed wrangler.jsonc
+  code: { bundle }, // `main` bundled for browsers (or { site } for the in-browser HTTP server)
+  sqlite3: await sqlite3InitModule(),
+  pool: "my-app", // the OPFS SQLite pool; one per worker
+  filesDir: "my-app-files",
+});
+const res = await host.runtime.fetch(new Request("http://browser/"));
+await host.close();
+```
+
+Where the cells live is the `pool` (an opfs-sahpool SQLite pool, one per worker) unless `bucket`
+says otherwise: `bucket: { idb, node }` keeps them in memory with page logs in IndexedDB, and
+`bucket: { ltx, node }` keeps each one as LTX files in an OPFS directory, read page by page through
+a SQLite VFS (cross-origin isolation needed). [docs/browser-host.md](docs/browser-host.md)
+compares them.
+
+To run each Worker-Loader Worker in a Dedicated Worker of its own, pass the shipped isolate worker:
+with Vite, `import isolateWorker from "@statewalker/cellb/isolate-worker?worker&url"` and
+`isolateScript: new URL(isolateWorker, import.meta.url)`.
+
+[docs/browser-host.md](docs/browser-host.md) shows how requests reach this worker through a
+ServiceWorker, how to shard an origin, and how to put the cells on an S3 bucket shared with celld.
+
+### A runtime behind a MessagePort
+
+```ts
+import { connectRuntime, serveRuntime } from "@statewalker/cellb";
+
+const { port1, port2 } = new MessageChannel();
+await serveRuntime(port1, runtime); // in the worker that owns the cells
+const remote = await connectRuntime(port2); // in the page, or another thread
+const res = await remote.fetch(new Request("http://local/counter/a")); // bodies stream
+```
+
+## Internals
+
+### One core, and ports for what differs per platform
+
+`src/core` knows nothing about the platform. It depends on the ports in `src/ports.ts`: a
+synchronous SQLite driver per cell, a `CellStorage` bundle (durability, backup, ownership, R2
+objects), a `Lease`, a `Clock`. The SQL port is synchronous because `ctx.storage.sql.exec()` is
+synchronous in Workers, and both drivers are synchronous underneath (`node:sqlite`, and SQLite WASM
+in a Dedicated Worker). [docs/architecture.md](docs/architecture.md) has the request path and the
+layers.
+
+### Where everything is
+
+```
+src/core            runtime, stubs, ids, gates, SQL and KV storage, alarms, celld's internal schema
+src/ports.ts        the port interfaces and CellStorage
+src/adapters        node:sqlite and SQLite WASM drivers, the WASM page hook, the LTX VFS, FilesApi logs and backups
+src/bucket          object stores (S3, SQLite, memory, FilesApi), the LTX writer, celldBucket
+src/ltx             the LTX v3 codec (LZ4, CRC-64, xxHash32), page reads and compaction over a FilesApi,
+                    the LTX store worker and its OPFS files (bucket: { ltx })
+src/v8              V8 serialization in TypeScript
+src/transport       the HTTP surface of a runtime, and links over ports
+src/router          CellRouter and the shard worker (browser origins)
+src/ws              WebSocket client, WebSocketPair and 101 Response over MessagePorts
+src/project         wrangler projects for Node and browsers, the in-browser site, Workers globals
+src/bindings        assets, cache, cron, D1 migrations, HTMLRewriter, KV, Queues, R2, Workflows, Worker Loader
+src/isolate         loaded Workers in a realm of their own (worker threads, Dedicated Workers)
+src/peer            celld's peer protocol, server and client (Node)
+src/node-compat     node:* modules for nodejs_compat in browsers
+src/miniflare-compat  shims for Miniflare's vendored D1 simulator
+vendor/             celld's KV, Queues and Workflows code; Miniflare's D1; html-rewriter-wasm
+conformance/        celld examples, our projects, workerd's tests, recorded goldens
+test/               unit tests (vitest, Node)
+e2e/                tests against a real celld and RustFS (vitest; skipped without CELLD_BIN)
+e2e-browser/        Playwright specs; pages/ holds the demo pages, the host app, ServiceWorker and
+                    shard workers they drive; probes/ the exploratory browser probes (ServiceWorker idling)
+scripts/            vendoring, the interop environment, mutation harnesses
+probes/             Node hypothesis probes (SQLite locks, webrun-modules globals)
+docs/               topic pages
+```
+
+### Decisions a reader would otherwise undo
+
+- **celld's storage format is the only one** — ids, internal tables, V8-serialized values, LTX
+  logs — so cells move between cellb and celld without conversion
+  ([docs/celld-compatibility.md](docs/celld-compatibility.md)).
+- **KV, Queues and Workflows run celld's own JavaScript**, vendored unchanged, so a queue, workflow
+  instance or KV namespace written by celld continues on cellb, and back.
+- **celld judges conformance**, because cellb's storage must be celld's; workerd is recorded to
+  pin where celld differs, and judges only where cellb follows it on purpose: stubs, functions and
+  `RpcTarget`s pass by reference, and calls on a pending result are pipelined, which celld
+  refuses ([docs/conformance.md](docs/conformance.md)).
+- **The gates use no `AsyncLocalStorage`**, which browsers lack.
+- **A browser origin has a fixed number of shards**, because an OPFS pool is exclusive per worker
+  ([docs/browser-host.md](docs/browser-host.md)).
+- **WebSockets travel over MessagePorts**, because a ServiceWorker cannot accept them. A port
+  has no send buffer to measure, so the server end acknowledges each message it dispatched and
+  a client's `bufferedAmount` counts the bytes not acknowledged yet: the WHATWG signal a sender
+  throttles on. workerd's server-side WebSocket has no `bufferedAmount`, and cellb's has none.
+- **Each loaded Worker gets a realm of its own**, a thread or a Dedicated Worker: as in celld's
+  isolates, loaded code must not see the host's globals or env.
+- **`idFromName` is synchronous**, with `@noble/hashes` instead of `crypto.subtle`, which is
+  asynchronous only; Worker code relies on getting the id at once.
+- **Ownership depends on the deployment**: a Web Lock per shard in an origin, celld's ownership
+  records per cell on a fleet bucket
+  ([docs/ownership-and-durability.md](docs/ownership-and-durability.md)).
+- **An idle database closes without letting go of its cell.** `hibernateAfterMs` drops an idle
+  object's instance; `closeDatabaseAfterMs` (longer, opt-in) also closes its SQLite handle, and the
+  next event reopens it. The cell lease is kept: taking the cell again would start a new generation,
+  whose first commit uploads the whole database. It is off by default because an in-memory database
+  without a log or backup would come back empty; a cell whose last changes are not backed up yet
+  stays open until they are.
+
+What cellb does not do yet is in [docs/gaps.md](docs/gaps.md); how it matches celld is in
+[docs/celld-compatibility.md](docs/celld-compatibility.md). The vocabulary is in
+[CONTEXT.md](CONTEXT.md).
+
+### Dependencies, and why
+
+- `@sqlite.org/sqlite-wasm` — SQLite in browsers (opfs-sahpool needs no COOP/COEP headers);
+  `sqlite-vec` for celld's `sqlite_vec` flag.
+- `@noble/hashes` — synchronous SHA-256 and HMAC for object ids.
+- `@statewalker/webrun-rpc`, `webrun-http-streams`, `webrun-streams` — HTTP with streaming bodies
+  over MessagePorts.
+- `@statewalker/webrun-files` — the FilesApi for logs, backups and KV blobs;
+  `webrun-http-browser`, `webrun-site-builder`, `webrun-site-host` — ServiceWorker ingress and the
+  in-browser HTTP server.
+- `worker-timers` — unthrottled heartbeat timers on a page's main thread.
+- `buffer`, `events`, `util`, `assert`, `path-browserify` — `nodejs_compat` in browsers.
+
+### What will surprise you
+
+- **`ERR_MODULE_NOT_FOUND` for `…/src/…/*.js` when importing this repository's sources with plain
+  `node`.** In the workspace the entry points are TypeScript; use vitest or tsx there, or the
+  published package (`pnpm pack`).
+- **`Durable Object <Class>/<id> is owned by another node`** (`CellOwnedElsewhereError`). Another live
+  node owns the cell in the fleet bucket. Pass `peers` to route to it, or wait for it to release the
+  cell or for its node lease to expire.
+- **`Durable Object reset because …`** (`BrokenObjectError`). A commit did not become durable, the
+  constructor's `blockConcurrencyWhile()` failed, or the cell lease was lost. The next call builds a
+  fresh instance.
+- **`unable to open database file`** from `nodeSqliteOpener(dir)` or `sqliteObjectStore(file)`. The
+  directory does not exist; neither creates it. (`celld dev` creates `.celld/dev/` on its first run.)
+- **`NoModificationAllowedError` in a browser.** Two workers opened the same OPFS pool. Each worker
+  needs its own `pool`.
+- **`storage quota exceeded writing …`** or **`ltx: cell … is open in another tab or worker`** with
+  `bucket: { ltx }`: the origin's storage is full, or another tab's store holds the cell. See
+  [docs/browser-host.md](docs/browser-host.md#what-breaks).
+- **`A stub was used after it was disposed.`** Loaded code, or its host, called a stub of the other
+  side after `stub[Symbol.dispose]()`. A stub into a loaded Worker holds its value until disposed or
+  garbage-collected ([docs/gaps.md](docs/gaps.md)).
+- **`DataCloneError: Functions, RpcTargets and stubs cannot be sent to another node …`** A call to
+  an object owned by another tab, worker or peer carried one of them, as an argument or a result.
+  They pass by reference only within one runtime ([docs/gaps.md](docs/gaps.md)).
+- **`DataCloneError: Only ctx.exports.<name>({ props }) stubs and class handles can be stored.`** A
+  Durable Object stub or an `RpcTarget` was put into storage; only `ctx.exports` handles with props
+  are storable.
+- **Writes after the last backup are gone after a crash** when the storage is a periodic backup
+  alone (`filesApiBackup`). That is its RPO; a log (`celldBucket`, `filesApiLtxLog`) has none.
+
+### Commands
+
+Run from `packages/cellb` after `pnpm install` at the repository root.
+
+| Command | What it does |
+|---|---|
+| `pnpm test` | `test/` and `e2e/` (vitest). The `e2e/` tests skip without `CELLD_BIN`; with it, each run makes its own S3 bucket (`TEST_BUCKET`) on `RUSTFS_ENDPOINT`, or starts a RustFS of its own on a free port when that is unset. Every server a test starts takes a free port, so several checkouts can run at once. `pnpm test:unit` and `pnpm test:e2e` run one folder. |
+| `pnpm typecheck` | TypeScript for `src/`, `test/`, `e2e/` and the browser pages |
+| `pnpm build` | `dist/` as published: `tsc -p tsconfig.build.json`, the hand-written declarations, worker URLs pointed at the compiled `.js` (`scripts/build.mjs`); `pnpm pack` runs it |
+| `node scripts/pack-check.mjs` | the package as published: packs it, checks the packed manifest (no `workspace:`/`catalog:` specifier, export targets present, every import of `dist/` and `vendor/` declared), installs the tarball with npm outside the workspace and runs it from plain Node, TypeScript and a Vite app in Chromium (`PW_CHROMIUM` for the binary) |
+| `pnpm e2e` | Chromium tests (Playwright, `e2e-browser/`), on a dev server at a free port, with the same bucket setup as `pnpm test`. Chromium is found from `PW_CHROMIUM`, then Playwright's own, then the one `@sparticuz/chromium` packages in `node_modules`. |
+| `pnpm e2e:firefox`, `pnpm e2e:webkit` | the same suite in Playwright's Firefox or WebKit (`npx playwright install firefox webkit`; `PW_BROWSERS` takes a comma-separated list). What differs in Firefox: [docs/browser-host.md](docs/browser-host.md#firefox-and-webkit). |
+| `pnpm interop` | `e2e/` and the celld conformance in Node: `scripts/interop-env.sh` downloads the pinned celld and RustFS into `~/.cache/cellb-interop`, starts a shared RustFS on `127.0.0.1:9200` (`RUSTFS_PORT`), and sets `CELLD_BIN`, `ESBUILD_DIR`, `RUSTFS_ENDPOINT` |
+| `pnpm interop:browser` | the same for Chromium |
+| `pnpm mutate`, `pnpm mutate:browser` | mutation harnesses in a throw-away copy, after a baseline run; `MUTANTS=0,3` runs a subset |
+| `pnpm browser:dev` | the demo pages in `e2e-browser/pages`: `/` (one cell worker), `/sharded/`, `/backup/`, and `/host/`, the host app that runs a project folder |
+
+### Releasing
+
+Releases are made by hand from a local checkout, with the maintainer's npm login and 2FA; CI
+never publishes (the statewalker convention). A change to the package carries a changeset
+(`pnpm changeset` at the repository root). To release:
+
+```sh
+pnpm changeset version                 # versions and changelog from the pending changesets
+git commit -am "chore: version packages"
+pnpm changeset publish                 # publishes what npm lacks (prepack builds dist/), tags it
+git push --follow-tags
+```
+
+Run `node scripts/pack-check.mjs` first: it checks exactly what `publish` uploads.
+
+## License
+
+MIT. Vendored code keeps its own licence, named in each file's first line or a `LICENSE` beside it:
+`vendor/celld/` and `conformance/celld-examples/` are Apache-2.0 (celld), `vendor/miniflare/` is
+MIT OR Apache-2.0 (Miniflare) and Apache-2.0 (workerd's D1 client), `vendor/html-rewriter-wasm/` is
+BSD-3-Clause, and `conformance/workerd-tests/` carry workerd's Apache-2.0.

package/dist/adapters/files-backup.d.ts

@@ -0,0 +1,16 @@
+import type { FilesApi } from "@statewalker/webrun-files";
+import type { CellBackup } from "../ports.js";
+export interface FilesApiBackupOptions {
+    /** Folder inside the FilesApi (default "/cells"). */
+    dir?: string;
+    intervalMs?: number;
+    onError?: (cellKey: string, error: unknown) => void;
+}
+/**
+ * CellBackup on a @statewalker/webrun-files FilesApi (OPFS, S3, memory, node fs…).
+ * Layout per cell:  {dir}/{Class}/{hexId}.sqlite  (+ .json with the BackupInfo).
+ * The image is written to a temporary file and `move`d over the previous one, so a
+ * crash during upload never leaves a truncated image as "the" backup (on backends
+ * whose move is atomic; S3 has no rename — there the last complete PUT wins).
+ */
+export declare function filesApiBackup(files: FilesApi, opts?: FilesApiBackupOptions): CellBackup;

package/dist/adapters/files-backup.js

@@ -0,0 +1,32 @@
+import { tryReadFile } from "@statewalker/webrun-files";
+/**
+ * CellBackup on a @statewalker/webrun-files FilesApi (OPFS, S3, memory, node fs…).
+ * Layout per cell:  {dir}/{Class}/{hexId}.sqlite  (+ .json with the BackupInfo).
+ * The image is written to a temporary file and `move`d over the previous one, so a
+ * crash during upload never leaves a truncated image as "the" backup (on backends
+ * whose move is atomic; S3 has no rename — there the last complete PUT wins).
+ */
+export function filesApiBackup(files, opts = {}) {
+    const dir = (opts.dir ?? "/cells").replace(/\/$/, "");
+    const path = (cellKey) => `${dir}/${cellKey
+        .split("/")
+        .map((p) => p.replace(/[^\w.-]/g, "_"))
+        .join("/")}.sqlite`;
+    return {
+        intervalMs: opts.intervalMs,
+        onError: opts.onError,
+        async save(cellKey, image, info) {
+            const target = path(cellKey);
+            const tmp = `${target}.${info.seq}.${info.takenAt}.tmp`;
+            await files.write(tmp, [image]);
+            await files.move(tmp, target);
+            await files.write(`${target}.json`, [
+                new TextEncoder().encode(JSON.stringify({ cellKey, ...info, bytes: image.byteLength })),
+            ]);
+        },
+        async load(cellKey) {
+            return tryReadFile(files, path(cellKey));
+        },
+    };
+}
+//# sourceMappingURL=files-backup.js.map

package/dist/adapters/files-backup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"files-backup.js","sourceRoot":"","sources":["../../src/adapters/files-backup.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAUxD;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,KAAe,EAAE,IAAI,GAA0B,EAAE;IAC9E,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,QAAQ,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACtD,MAAM,IAAI,GAAG,CAAC,OAAe,EAAE,EAAE,CAC/B,GAAG,GAAG,IAAI,OAAO;SACd,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;SACtC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC;IACxB,OAAO;QACL,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,KAAK,CAAC,IAAI,CAAC,OAAe,EAAE,KAAiB,EAAE,IAAgB;YAC7D,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;YAC7B,MAAM,GAAG,GAAG,GAAG,MAAM,IAAI,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,OAAO,MAAM,CAAC;YACxD,MAAM,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;YAChC,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YAC9B,MAAM,KAAK,CAAC,KAAK,CAAC,GAAG,MAAM,OAAO,EAAE;gBAClC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC;aACxF,CAAC,CAAC;QACL,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,OAAe;YACxB,OAAO,WAAW,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QAC3C,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["import type { FilesApi } from \"@statewalker/webrun-files\";\nimport { tryReadFile } from \"@statewalker/webrun-files\";\nimport type { BackupInfo, CellBackup } from \"../ports.js\";\n\nexport interface FilesApiBackupOptions {\n  /** Folder inside the FilesApi (default \"/cells\"). */\n  dir?: string;\n  intervalMs?: number;\n  onError?: (cellKey: string, error: unknown) => void;\n}\n\n/**\n * CellBackup on a @statewalker/webrun-files FilesApi (OPFS, S3, memory, node fs…).\n * Layout per cell:  {dir}/{Class}/{hexId}.sqlite  (+ .json with the BackupInfo).\n * The image is written to a temporary file and `move`d over the previous one, so a\n * crash during upload never leaves a truncated image as \"the\" backup (on backends\n * whose move is atomic; S3 has no rename — there the last complete PUT wins).\n */\nexport function filesApiBackup(files: FilesApi, opts: FilesApiBackupOptions = {}): CellBackup {\n  const dir = (opts.dir ?? \"/cells\").replace(/\\/$/, \"\");\n  const path = (cellKey: string) =>\n    `${dir}/${cellKey\n      .split(\"/\")\n      .map((p) => p.replace(/[^\\w.-]/g, \"_\"))\n      .join(\"/\")}.sqlite`;\n  return {\n    intervalMs: opts.intervalMs,\n    onError: opts.onError,\n    async save(cellKey: string, image: Uint8Array, info: BackupInfo) {\n      const target = path(cellKey);\n      const tmp = `${target}.${info.seq}.${info.takenAt}.tmp`;\n      await files.write(tmp, [image]);\n      await files.move(tmp, target);\n      await files.write(`${target}.json`, [\n        new TextEncoder().encode(JSON.stringify({ cellKey, ...info, bytes: image.byteLength })),\n      ]);\n    },\n    async load(cellKey: string) {\n      return tryReadFile(files, path(cellKey));\n    },\n  };\n}\n"]}

package/dist/adapters/files-changelog.d.ts

@@ -0,0 +1,33 @@
+import type { FilesApi } from "@statewalker/webrun-files";
+import type { CellBackup, CellDurability, CommitChanges } from "../ports.js";
+/**
+ * Transaction-log durability on a webrun-files FilesApi (OPFS, S3, node fs, memory…) —
+ * celld's model (every acknowledged write is in the bucket) with SQLite *changesets*
+ * instead of LTX page frames:
+ *
+ *   {dir}/{cell}/log/{epoch}-{logSeq}.seg   one segment per committed transaction
+ *   {dir}/{cell}/snapshot.sqlite (+ .json)  periodic image, carrying its logSeq
+ *
+ * `committed()` resolves when the segment is written, and the output gate holds every
+ * reply until then: RPO = 0 against the FilesApi. Restore = snapshot + the segments after
+ * its logSeq. After a successful snapshot the segments it contains are deleted.
+ * `epoch` (e.g. a lease fencing token) prefixes segment names: segments of different owners
+ * never overwrite each other, and a stale owner's segments are void from the first sequence
+ * number a newer owner wrote (celld fences the same way with the epoch in its log keys).
+ */
+export interface ChangeLogOptions {
+    dir?: string;
+    /** Fencing epoch of the current owner (default 0). */
+    epoch?: number;
+    /** Snapshot interval (compaction); default: no periodic snapshot. */
+    intervalMs?: number;
+    onError?: (cellKey: string, error: unknown) => void;
+}
+export declare function encodeSegment(c: CommitChanges, epoch: number): Uint8Array;
+export declare function decodeSegment(bytes: Uint8Array): CommitChanges & {
+    epoch: number;
+};
+export declare function filesApiChangeLog(files: FilesApi, opts?: ChangeLogOptions): {
+    durability: CellDurability;
+    backup: CellBackup;
+};

package/dist/adapters/files-changelog.js

@@ -0,0 +1,96 @@
+import { tryReadFile } from "@statewalker/webrun-files";
+const MAGIC = new TextEncoder().encode("CLOG1");
+const pad = (n, w) => String(n).padStart(w, "0");
+export function encodeSegment(c, epoch) {
+    const header = new TextEncoder().encode(JSON.stringify({
+        logSeq: c.logSeq,
+        epoch,
+        ddl: c.ddl,
+        statements: c.statements,
+        at: Date.now(),
+    }));
+    const out = new Uint8Array(MAGIC.length + 4 + header.length + c.changeset.byteLength);
+    out.set(MAGIC, 0);
+    new DataView(out.buffer).setUint32(MAGIC.length, header.length);
+    out.set(header, MAGIC.length + 4);
+    out.set(c.changeset, MAGIC.length + 4 + header.length);
+    return out;
+}
+export function decodeSegment(bytes) {
+    for (let i = 0; i < MAGIC.length; i++)
+        if (bytes[i] !== MAGIC[i])
+            throw new Error("not a change-log segment");
+    const len = new DataView(bytes.buffer, bytes.byteOffset).getUint32(MAGIC.length);
+    const header = JSON.parse(new TextDecoder().decode(bytes.subarray(MAGIC.length + 4, MAGIC.length + 4 + len)));
+    return { ...header, changeset: bytes.slice(MAGIC.length + 4 + len) };
+}
+export function filesApiChangeLog(files, opts = {}) {
+    const dir = (opts.dir ?? "/cells").replace(/\/$/, "");
+    const epoch = opts.epoch ?? 0;
+    const cellDir = (cellKey) => `${dir}/${cellKey
+        .split("/")
+        .map((p) => p.replace(/[^\w.-]/g, "_"))
+        .join("/")}`;
+    const segments = async (cellKey) => {
+        const logDir = `${cellDir(cellKey)}/log`;
+        const out = [];
+        if (!(await files.exists(logDir)))
+            return out;
+        for await (const f of files.list(logDir)) {
+            const m = /(\d+)-(\d+)\.seg$/.exec(f.path);
+            if (f.kind === "file" && m)
+                out.push({ path: f.path, epoch: Number(m[1]), logSeq: Number(m[2]) });
+        }
+        // Fencing: a segment written by an older owner (epoch e) is void from the first logSeq
+        // that a newer owner (epoch > e) wrote — a stale owner's late writes never replay.
+        const firstOfEpoch = new Map();
+        for (const s of out)
+            firstOfEpoch.set(s.epoch, Math.min(firstOfEpoch.get(s.epoch) ?? s.logSeq, s.logSeq));
+        const valid = out.filter((s) => ![...firstOfEpoch].some(([e, first]) => e > s.epoch && first <= s.logSeq));
+        return valid.sort((a, b) => a.logSeq - b.logSeq || b.epoch - a.epoch);
+    };
+    const log = {
+        captureChanges: true,
+        intervalMs: opts.intervalMs,
+        onError: opts.onError,
+        async committed(cellKey, { changes }) {
+            if (!changes)
+                return;
+            const e = changes.epoch ?? epoch; // the cell's lease epoch wins over the static one
+            const name = `${pad(e, 10)}-${pad(changes.logSeq, 12)}.seg`;
+            await files.write(`${cellDir(cellKey)}/log/${name}`, [encodeSegment(changes, e)]);
+        },
+        async save(cellKey, image, info) {
+            const base = cellDir(cellKey);
+            const tmp = `${base}/snapshot.${info.takenAt}.tmp`;
+            await files.write(tmp, [image]);
+            await files.move(tmp, `${base}/snapshot.sqlite`);
+            await files.write(`${base}/snapshot.json`, [
+                new TextEncoder().encode(JSON.stringify({ cellKey, ...info })),
+            ]);
+            // Compaction: the image contains every segment up to its logSeq.
+            for (const s of await segments(cellKey))
+                if (s.logSeq <= (info.logSeq ?? 0))
+                    await files.remove(s.path);
+        },
+        async load(cellKey) {
+            return tryReadFile(files, `${cellDir(cellKey)}/snapshot.sqlite`);
+        },
+        async *replay(cellKey, afterLogSeq) {
+            let last = afterLogSeq;
+            for (const s of await segments(cellKey)) {
+                if (s.logSeq <= last)
+                    continue;
+                if (s.logSeq !== last + 1)
+                    throw new Error(`change log of ${cellKey}: segment ${last + 1} is missing`);
+                const bytes = await tryReadFile(files, s.path);
+                if (!bytes)
+                    throw new Error(`change log of ${cellKey}: cannot read ${s.path}`);
+                last = s.logSeq;
+                yield decodeSegment(bytes);
+            }
+        },
+    };
+    return { durability: log, backup: log };
+}
+//# sourceMappingURL=files-changelog.js.map

package/dist/adapters/files-changelog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"files-changelog.js","sourceRoot":"","sources":["../../src/adapters/files-changelog.ts"],"names":[],"mappings":"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","sourcesContent":["import type { FilesApi } from \"@statewalker/webrun-files\";\nimport { tryReadFile } from \"@statewalker/webrun-files\";\nimport type { BackupInfo, CellBackup, CellDurability, CommitChanges } from \"../ports.js\";\n\n/**\n * Transaction-log durability on a webrun-files FilesApi (OPFS, S3, node fs, memory…) —\n * celld's model (every acknowledged write is in the bucket) with SQLite *changesets*\n * instead of LTX page frames:\n *\n *   {dir}/{cell}/log/{epoch}-{logSeq}.seg   one segment per committed transaction\n *   {dir}/{cell}/snapshot.sqlite (+ .json)  periodic image, carrying its logSeq\n *\n * `committed()` resolves when the segment is written, and the output gate holds every\n * reply until then: RPO = 0 against the FilesApi. Restore = snapshot + the segments after\n * its logSeq. After a successful snapshot the segments it contains are deleted.\n * `epoch` (e.g. a lease fencing token) prefixes segment names: segments of different owners\n * never overwrite each other, and a stale owner's segments are void from the first sequence\n * number a newer owner wrote (celld fences the same way with the epoch in its log keys).\n */\nexport interface ChangeLogOptions {\n  dir?: string;\n  /** Fencing epoch of the current owner (default 0). */\n  epoch?: number;\n  /** Snapshot interval (compaction); default: no periodic snapshot. */\n  intervalMs?: number;\n  onError?: (cellKey: string, error: unknown) => void;\n}\n\nconst MAGIC = new TextEncoder().encode(\"CLOG1\");\nconst pad = (n: number, w: number) => String(n).padStart(w, \"0\");\n\nexport function encodeSegment(c: CommitChanges, epoch: number): Uint8Array {\n  const header = new TextEncoder().encode(\n    JSON.stringify({\n      logSeq: c.logSeq,\n      epoch,\n      ddl: c.ddl,\n      statements: c.statements,\n      at: Date.now(),\n    }),\n  );\n  const out = new Uint8Array(MAGIC.length + 4 + header.length + c.changeset.byteLength);\n  out.set(MAGIC, 0);\n  new DataView(out.buffer).setUint32(MAGIC.length, header.length);\n  out.set(header, MAGIC.length + 4);\n  out.set(c.changeset, MAGIC.length + 4 + header.length);\n  return out;\n}\n\nexport function decodeSegment(bytes: Uint8Array): CommitChanges & { epoch: number } {\n  for (let i = 0; i < MAGIC.length; i++)\n    if (bytes[i] !== MAGIC[i]) throw new Error(\"not a change-log segment\");\n  const len = new DataView(bytes.buffer, bytes.byteOffset).getUint32(MAGIC.length);\n  const header = JSON.parse(\n    new TextDecoder().decode(bytes.subarray(MAGIC.length + 4, MAGIC.length + 4 + len)),\n  );\n  return { ...header, changeset: bytes.slice(MAGIC.length + 4 + len) };\n}\n\nexport function filesApiChangeLog(\n  files: FilesApi,\n  opts: ChangeLogOptions = {},\n): { durability: CellDurability; backup: CellBackup } {\n  const dir = (opts.dir ?? \"/cells\").replace(/\\/$/, \"\");\n  const epoch = opts.epoch ?? 0;\n  const cellDir = (cellKey: string) =>\n    `${dir}/${cellKey\n      .split(\"/\")\n      .map((p) => p.replace(/[^\\w.-]/g, \"_\"))\n      .join(\"/\")}`;\n  const segments = async (cellKey: string) => {\n    const logDir = `${cellDir(cellKey)}/log`;\n    const out: { path: string; epoch: number; logSeq: number }[] = [];\n    if (!(await files.exists(logDir))) return out;\n    for await (const f of files.list(logDir)) {\n      const m = /(\\d+)-(\\d+)\\.seg$/.exec(f.path);\n      if (f.kind === \"file\" && m)\n        out.push({ path: f.path, epoch: Number(m[1]), logSeq: Number(m[2]) });\n    }\n    // Fencing: a segment written by an older owner (epoch e) is void from the first logSeq\n    // that a newer owner (epoch > e) wrote — a stale owner's late writes never replay.\n    const firstOfEpoch = new Map<number, number>();\n    for (const s of out)\n      firstOfEpoch.set(s.epoch, Math.min(firstOfEpoch.get(s.epoch) ?? s.logSeq, s.logSeq));\n    const valid = out.filter(\n      (s) => ![...firstOfEpoch].some(([e, first]) => e > s.epoch && first <= s.logSeq),\n    );\n    return valid.sort((a, b) => a.logSeq - b.logSeq || b.epoch - a.epoch);\n  };\n\n  const log: CellDurability & CellBackup = {\n    captureChanges: true,\n    intervalMs: opts.intervalMs,\n    onError: opts.onError,\n\n    async committed(cellKey, { changes }) {\n      if (!changes) return;\n      const e = changes.epoch ?? epoch; // the cell's lease epoch wins over the static one\n      const name = `${pad(e, 10)}-${pad(changes.logSeq, 12)}.seg`;\n      await files.write(`${cellDir(cellKey)}/log/${name}`, [encodeSegment(changes, e)]);\n    },\n\n    async save(cellKey: string, image: Uint8Array, info: BackupInfo) {\n      const base = cellDir(cellKey);\n      const tmp = `${base}/snapshot.${info.takenAt}.tmp`;\n      await files.write(tmp, [image]);\n      await files.move(tmp, `${base}/snapshot.sqlite`);\n      await files.write(`${base}/snapshot.json`, [\n        new TextEncoder().encode(JSON.stringify({ cellKey, ...info })),\n      ]);\n      // Compaction: the image contains every segment up to its logSeq.\n      for (const s of await segments(cellKey))\n        if (s.logSeq <= (info.logSeq ?? 0)) await files.remove(s.path);\n    },\n\n    async load(cellKey: string) {\n      return tryReadFile(files, `${cellDir(cellKey)}/snapshot.sqlite`);\n    },\n\n    async *replay(cellKey: string, afterLogSeq: number) {\n      let last = afterLogSeq;\n      for (const s of await segments(cellKey)) {\n        if (s.logSeq <= last) continue;\n        if (s.logSeq !== last + 1)\n          throw new Error(`change log of ${cellKey}: segment ${last + 1} is missing`);\n        const bytes = await tryReadFile(files, s.path);\n        if (!bytes) throw new Error(`change log of ${cellKey}: cannot read ${s.path}`);\n        last = s.logSeq;\n        yield decodeSegment(bytes);\n      }\n    },\n  };\n  return { durability: log, backup: log };\n}\n"]}

package/dist/adapters/files-ltx.d.ts

@@ -0,0 +1,35 @@
+import type { FilesApi } from "@statewalker/webrun-files";
+/**
+ * The LTX log on a webrun-files FilesApi (OPFS in browsers, a directory on Node), without
+ * ownership: the same writer as celldBucket (src/bucket/ltx-log.ts), on the FilesApi as an
+ * object store. Keys are celld's: `<dir>/<Class>:<id>/ltx/e<epoch>/0000/<min>-<max>.ltx`
+ * (`dir` defaults to "/cells"), so the files read the same in celld.
+ */
+export interface FilesApiLtxLogOptions {
+    /** Where the `cells/` keys live; defaults to "/cells". */
+    dir?: string;
+    /** The epoch the files are written in (no ownership); 0 by default. */
+    epoch?: number;
+    intervalMs?: number;
+    onError?: (cellKey: string, error: unknown) => void;
+}
+export declare function filesApiLtxLog(files: FilesApi, opts?: FilesApiLtxLogOptions): {
+    durability: import("../ports.js").CellDurability & import("../ports.js").CellBackup & {
+        logCommit: import("../ports.js").CellDurability["committed"];
+    } & {
+        begin(cellKey: string, epoch: number): void;
+        forget(cellKey: string): void;
+    } & {
+        intervalMs: number | undefined;
+        onError: ((cellKey: string, error: unknown) => void) | undefined;
+    };
+    backup: import("../ports.js").CellDurability & import("../ports.js").CellBackup & {
+        logCommit: import("../ports.js").CellDurability["committed"];
+    } & {
+        begin(cellKey: string, epoch: number): void;
+        forget(cellKey: string): void;
+    } & {
+        intervalMs: number | undefined;
+        onError: ((cellKey: string, error: unknown) => void) | undefined;
+    };
+};

package/dist/adapters/files-ltx.js

@@ -0,0 +1,9 @@
+import { ltxLog } from "../bucket/ltx-log.js";
+import { filesApiObjectStore } from "../bucket/object-store.js";
+export function filesApiLtxLog(files, opts = {}) {
+    const dir = (opts.dir ?? "/cells").replace(/\/$/, "");
+    const root = dir.endsWith("/cells") ? dir.slice(0, -"/cells".length) : dir;
+    const log = Object.assign(ltxLog(filesApiObjectStore(files, root), { defaultEpoch: opts.epoch ?? 0, compact: true }), { intervalMs: opts.intervalMs, onError: opts.onError });
+    return { durability: log, backup: log };
+}
+//# sourceMappingURL=files-ltx.js.map

package/dist/adapters/files-ltx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"files-ltx.js","sourceRoot":"","sources":["../../src/adapters/files-ltx.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAiBhE,MAAM,UAAU,cAAc,CAAC,KAAe,EAAE,IAAI,GAA0B,EAAE;IAC9E,MAAM,GAAG,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,QAAQ,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACtD,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAC3E,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,CACvB,MAAM,CAAC,mBAAmB,CAAC,KAAK,EAAE,IAAI,CAAC,EAAE,EAAE,YAAY,EAAE,IAAI,CAAC,KAAK,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,EAC1F,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CACvD,CAAC;IACF,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;AAC1C,CAAC","sourcesContent":["import type { FilesApi } from \"@statewalker/webrun-files\";\nimport { ltxLog } from \"../bucket/ltx-log.js\";\nimport { filesApiObjectStore } from \"../bucket/object-store.js\";\n\n/**\n * The LTX log on a webrun-files FilesApi (OPFS in browsers, a directory on Node), without\n * ownership: the same writer as celldBucket (src/bucket/ltx-log.ts), on the FilesApi as an\n * object store. Keys are celld's: `<dir>/<Class>:<id>/ltx/e<epoch>/0000/<min>-<max>.ltx`\n * (`dir` defaults to \"/cells\"), so the files read the same in celld.\n */\nexport interface FilesApiLtxLogOptions {\n  /** Where the `cells/` keys live; defaults to \"/cells\". */\n  dir?: string;\n  /** The epoch the files are written in (no ownership); 0 by default. */\n  epoch?: number;\n  intervalMs?: number;\n  onError?: (cellKey: string, error: unknown) => void;\n}\n\nexport function filesApiLtxLog(files: FilesApi, opts: FilesApiLtxLogOptions = {}) {\n  const dir = (opts.dir ?? \"/cells\").replace(/\\/$/, \"\");\n  const root = dir.endsWith(\"/cells\") ? dir.slice(0, -\"/cells\".length) : dir;\n  const log = Object.assign(\n    ltxLog(filesApiObjectStore(files, root), { defaultEpoch: opts.epoch ?? 0, compact: true }),\n    { intervalMs: opts.intervalMs, onError: opts.onError },\n  );\n  return { durability: log, backup: log };\n}\n"]}

package/dist/adapters/ltx-vfs.d.ts

@@ -0,0 +1,21 @@
+export interface LtxVfsChannel {
+    /** Shared control words [state, length] + payload (≥ one page). */
+    sab: SharedArrayBuffer;
+    /** Posts a request to the store (it answers into `sab`, then notifies). */
+    post(msg: unknown): void;
+}
+export interface LtxVfsStats {
+    reads: number;
+    cacheHits: number;
+    storeReads: number;
+    commits: number;
+    blockedMs: number;
+}
+export declare function installLtxVfs(sqlite3: any, channel: LtxVfsChannel, opts?: {
+    name?: string;
+    cachePages?: number;
+    readAhead?: number;
+}): {
+    name: string;
+    stats: LtxVfsStats;
+};