@serfab/quereus-plugin-sereus 1.17.0 → 1.19.0

package/README.md

@@ -1,388 +1,390 @@
-# @serfab/quereus-plugin-sereus
-
-A [Quereus](https://github.com/nicktobey/quereus) plugin that connects a Quereus
-database to a [Sereus](../../docs/architecture.md) strand for SQL access. It
-composes the [@optimystic/quereus-plugin-crypto](https://github.com/nicktobey/optimystic/tree/main/packages/quereus-plugin-crypto)
-and [@optimystic/quereus-plugin-optimystic](https://github.com/nicktobey/optimystic/tree/main/packages/quereus-plugin-optimystic)
-plugins, manages libp2p networking, and optionally applies a sApp schema.
-
-## Features
-
-- **Strand connection**: Connect a Quereus database to a Sereus strand with a single call.
-- **Plugin composition**: Automatically registers the crypto and optimystic plugins.
-- **Node management**: Creates a libp2p node or accepts an injected one (e.g. from a CadreNode).
-- **Schema application**: Wraps DDL in `declare schema App { ... } apply schema App;`.
-- **Two runtimes**: A Node entry (`./plugin`) and a self-contained browser bundle
-  (`./plugin-browser`) for Quoomb-web and other browser/worker hosts.
-- **Two entry points**: A plugin-loader-compatible default export and a
-  programmatic `connectToStrand()` API.
-
-## Artifacts
-
-The package ships two plugin artifacts, selected automatically by the consumer's
-environment via the `exports` map:
-
-| Artifact | Built by | Transports | Default storage | Use from |
-|---|---|---|---|---|
-| `dist/plugin.js` | `tsc` | TCP + WebSockets | in-memory / FS | Node (`./plugin`) |
-| `dist/plugin-browser.js` | `esbuild` | WebSockets + circuit-relay | IndexedDB | Browser/worker (`./plugin-browser`) |
-
-The browser bundle is a single self-contained, minified ESM file of roughly 1.9 MiB
-raw / 0.6 MiB gzipped (the exact measurement and its date live beside the size caps in
-`test/browser-bundle.spec.ts`; a second copy of the numbers here would go stale). A
-source map, `dist/plugin-browser.js.map`, ships beside it with the original sources
-embedded, so devtools still show readable code. It bundles only the TCP-free libp2p
-surface (`@optimystic/db-p2p/rn`) and does **not** import `@quereus/quereus` at
-runtime — registrations are applied against the host-supplied `db`, so it reuses the
-host's Quereus instance rather than instantiating a second one.
-
-## Installation
-
-```bash
-npm install @serfab/quereus-plugin-sereus
-# or
-yarn add @serfab/quereus-plugin-sereus
-```
-
----
-
-## Using it from Quoomb Web (step by step)
-
-[Quoomb Web](../../../quereus/packages/quoomb-web) loads plugins by URL: its
-worker calls `import(url)` and registers the module's default export against the
-live database. To connect Quoomb Web to a strand you need to (1) make the
-**browser bundle** reachable at an importable URL, and (2) give it a strand id
-and at least one **browser-dialable** bootstrap address.
-
-### Prerequisites
-
-- A **strand id** (UUID) to connect to.
-- For networked use: a libp2p **bootstrap/relay reachable over secure WebSockets**
-  (`/wss`) from an `https://` page. Browsers cannot dial raw TCP, and a plain
-  `ws://`/`tcp` address will not dial from a TLS origin. WebSockets +
-  circuit-relay are the only supported transports in v1.
-- The strand's **sApp schema** (optional — only needed to bootstrap a brand-new
-  strand or to expose `App.*` tables before any peer has).
-
-### Step 1 — Make the browser bundle importable
-
-Pick one of the hosting options below ([Hosting the browser
-bundle](#hosting-the-browser-bundle)). The quickest are:
-
-- **Published CDN URL** (recommended once published):
-  `https://cdn.jsdelivr.net/npm/@serfab/quereus-plugin-sereus/dist/plugin-browser.js`
-- **Local dev**: copy `dist/plugin-browser.js` into Quoomb Web's `public/` folder
-  so it is served same-origin at `http://localhost:5173/plugin-browser.js`.
-
-The URL must serve the file with `Content-Type: text/javascript` (or
-`application/javascript`) and CORS that permits the page origin.
-
-### Step 2a — Load via the Plugins panel (manual)
-
-1. Open Quoomb Web → **Plugins** panel.
-2. Paste the bundle URL into the plugin URL field and install it.
-   - The manual installer validates the URL and only accepts **`https://`** (or
-     `file://`) ending in `.js`/`.mjs`. A same-origin `http://localhost` URL is
-     **rejected here** — use Step 2b (config) for local-dev http, or serve
-     Quoomb over https.
-3. Open the plugin's config and set at least:
-   - `strand_id` — the strand UUID.
-   - `bootstrap_nodes` — comma-separated `/wss` multiaddrs.
-   - `schema` — optional sApp DDL.
-4. Run a query, e.g. `select * from App.Message`.
-
-### Step 2b — Load via `quoomb.config.json` (autoload)
-
-The config/autoload path calls the loader directly and **bypasses the
-https-only check**, so it is the right choice for local `http://localhost`
-during development. In Quoomb Web, open the **Config** modal and import this
-JSON (or set it as `quoomb.config.json`):
-
-```jsonc
-{
-  "plugins": [
-    {
-      "source": "https://cdn.jsdelivr.net/npm/@serfab/quereus-plugin-sereus/dist/plugin-browser.js",
-      "config": {
-        "strand_id": "550e8400-e29b-41d4-a716-446655440000",
-        "bootstrap_nodes": "/dns4/relay.example/tcp/443/wss/p2p/Qm...",
-        "schema": "table Message (Id integer primary key, Content text not null)"
-      }
-    }
-  ],
-  "autoload": true
-}
-```
-
-With `autoload: true`, the plugin loads on session start and applies the schema.
-
-### Step 3 — Query the strand
-
-Once loaded, the `optimystic` vtab is the default and `App.*` tables resolve
-against the strand:
-
-```sql
-select * from App.Message;
-insert into App.Message (Id, Content) values (1, 'hello strand');
-```
-
-### Notes & limitations
-
-- **Storage.** When `storage` is not injected, the browser bundle opens a default
-  `IndexedDBRawStorage` against an IndexedDB database named
-  `sereus-strand-<strandId>`. State survives reload. The plugin treats the
-  IndexedDB handle as borrowed and does **not** close it on `shutdown()` — its
-  lifecycle is the page/worker.
-- **Network transactor by default.** Every connection commits through the
-  strand's libp2p cohort unless it asks otherwise; the in-process `local`
-  transactor is a testing/tooling option (`connectToStrand({ transactor:
-  'local' })`), not a browser deployment mode.
-- **WebRTC** requires cross-origin isolation (COOP/COEP) and is tracked as a
-  follow-up; v1 is WebSockets + circuit-relay only.
-- **Lifecycle.** Quoomb Web's loader keeps only the manifest and discards the
-  plugin's returned `shutdown()`, so the libp2p node is torn down with the
-  worker rather than on plugin unload.
-
----
-
-## Hosting the browser bundle
-
-The browser bundle is just an ESM file; it can be served from anywhere that
-returns a JavaScript content type with appropriate CORS.
-
-### Published package on a CDN (recommended)
-
-After `yarn pub:quereus-plugin-sereus` (see [Publishing](#publishing)), the npm
-package is mirrored by the public CDNs, which serve the correct content type and
-CORS automatically:
-
-- jsDelivr: `https://cdn.jsdelivr.net/npm/@serfab/quereus-plugin-sereus/dist/plugin-browser.js`
-- jsDelivr (pinned): `https://cdn.jsdelivr.net/npm/@serfab/quereus-plugin-sereus@0.7.1/dist/plugin-browser.js`
-- unpkg: `https://unpkg.com/@serfab/quereus-plugin-sereus/dist/plugin-browser.js`
-
-### Self-hosted / same-origin
-
-Copy `dist/plugin-browser.js` to any static host (or Quoomb Web's `public/`) and
-reference it by URL. Same-origin hosting sidesteps CORS entirely.
-
-### Loading from GitHub
-
-Loading the bundle straight from a GitHub repo has a caveat: **`dist/` is
-gitignored**, and `raw.githubusercontent.com` serves files as `text/plain` with
-`X-Content-Type-Options: nosniff`, so the browser refuses to `import()` it as a
-module. Two routes that *do* work:
-
-1. **jsDelivr's GitHub endpoint**, which serves repo files with the correct MIME
-   type and CORS — but only files that exist at the ref. Since `dist/` is not
-   committed, this requires the built bundle to be present at the ref you point
-   at (e.g. a CI step that commits `plugin-browser.js` to a `dist`/`gh-pages`
-   branch or a tag):
-
-   ```
-   https://cdn.jsdelivr.net/gh/gotchoices/sereus@<tag-or-branch>/packages/quereus-plugin-sereus/dist/plugin-browser.js
-   ```
-
-2. **GitHub Pages**: publish `plugin-browser.js` to a Pages site, which serves it
-   with a JavaScript content type and CORS.
-
-For most cases the npm-backed CDN URL above is simpler and is the recommended
-GitHub-free hosting path. (Note: GitHub *Release assets* are served as
-`application/octet-stream` and cannot be imported as ESM.)
-
----
-
-## Programmatic API
-
-```typescript
-import { Database } from '@quereus/quereus';
-import { connectToStrand } from '@serfab/quereus-plugin-sereus';
-
-const db = new Database();
-const strand = await connectToStrand(db, {
-  strandId: '550e8400-e29b-41d4-a716-446655440000',
-  schema: 'table Message (Id integer primary key, Content text not null)',
-  bootstrapNodes: ['/ip4/1.2.3.4/tcp/9100/p2p/QmPeerId'],
-});
-
-for await (const row of db.eval('select * from App.Message')) {
-  console.log(row);
-}
-
-await strand.shutdown();
-```
-
-### Plugin-loader (Node)
-
-The `./plugin` export is compatible with Quereus plugin-loader:
-
-```typescript
-import { Database, registerPlugin } from '@quereus/quereus';
-import sereusPlugin from '@serfab/quereus-plugin-sereus/plugin';
-
-const db = new Database();
-const result = await registerPlugin(db, sereusPlugin, {
-  strand_id: '550e8400-e29b-41d4-a716-446655440000',
-  schema: 'table Message (Id integer primary key, Content text not null)',
-  bootstrap_nodes: '/ip4/1.2.3.4/tcp/9100/p2p/QmPeerId',
-});
-
-await result.shutdown();
-```
-
-### Local transactor (in-process, no cohort)
-
-`transactor: 'local'` sends every transaction straight to this process's raw
-storage — no peers are consulted at all. It is for in-process tests and tooling
-(this package's own e2e suites run on it); applications should stay on the
-default `network` transactor, which a lone node coordinates for itself.
-
-Pair it with a persistent `IRawStorage` to survive restart: the same storage
-instance is wired into both the libp2p data path and the optimystic plugin's
-local transactor.
-
-```typescript
-import { FileRawStorage } from '@optimystic/db-p2p-storage-fs';
-
-const storage = new FileRawStorage('./data/my-strand');
-const strand = await connectToStrand(db, {
-  strandId: 'abc',
-  transactor: 'local',
-  storage,
-  schema: 'table Msg (Id integer primary key, Body text not null)',
-});
-```
-
-The plugin treats `storage` as borrowed: `shutdown()` releases the libp2p node
-and collection factory but does **not** close the storage.
-
-### With an injected node
-
-When integrating with an existing CadreNode or other libp2p host:
-
-```typescript
-const strand = await connectToStrand(db, {
-  strandId: 'abc',
-  libp2pNode: existingNode,
-  coordinatedRepo: existingRepo,
-});
-```
-
-The plugin uses the injected node instead of creating one, and will not stop it
-on shutdown.
-
-### A commit's durability
-
-The result's `onCommitDurability(listener)` is called after every commit that wrote something, before the commit returns, with who holds what it wrote; `onCommitFullyHeld(listener)` is called once when a commit reported `followed` below full replication becomes held by its whole cohort. Both pass through from `@optimystic/quereus-plugin-optimystic`, whose README explains the report ([A commit's durability](https://github.com/gotchoices/optimystic/blob/main/packages/quereus-plugin-optimystic/README.md#a-commits-durability--pluginoncommitdurabilitylistener)); the `SqlCommitDurability` and `CommitFullyHeld` types are re-exported here. A cadre app reads the same reports through `@serfab/cadre-core` ([strands.md → A commit's durability](../../docs/strands.md#a-commits-durability)).
-
-### Founding a strand: `createEmptyCollections()`
-
-A table nobody has written has no collection, so no single machine can show it empty: every read of it asks the other members, and fails while they are offline. The result's `createEmptyCollections()` commits an empty collection for every table the `Strand` and `App` schemas declare that has none yet, and resolves to how many it committed. The founder calls it once, before writing `Strand.Header`, while no other machine can have written to the strand; cadre-core's founder bootstrap does this ([strands.md → Joining](../../docs/strands.md#joining-no-writes-before-the-first-sync)). Call it only while nothing else writes through the `Database`: it commits whatever is staged in those collections outside any SQL transaction.
-
----
-
-## Configuration
-
-### `StrandConnectionOptions` (programmatic API)
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `strandId` | string | *required* | UUID of the strand to connect to |
-| `bootstrapNodes` | string[] | `[]` | Bootstrap multiaddrs for peer discovery |
-| `schema` | string | — | sApp schema DDL to apply, as the body of `declare schema App { ... }`. An item the Quereus parser would skip (`create unique index …`, a misspelled item keyword) is refused rather than ignored. Its tables may share names with the strand's own tables; they are stored separately ([Same-Named Tables](../../docs/strands.md#same-named-tables-in-strand-and-app)) |
-| `sAppId` | string | `'unknown'` | sApp author public key |
-| `sAppVersion` | string | `'1.0.0'` | sApp version |
-| `port` | number | `0` | libp2p listening port (0 = random) |
-| `enableCache` | boolean | `true` | Enable optimystic caching |
-| `fretProfile` | `'edge' \| 'core'` | `'edge'` | FRET profile |
-| `clusterSize` | number | `4` | Nodes the **strand's** replication cluster should have (the control network uses its own fixed `CONTROL_REPLICATION_BREADTH` and never reads this). 4 is the smallest breadth whose 0.75 super-majority (`ceil(4 × 0.75) = 3`) still commits with one holder offline; at 2 or 3 every holder must be awake for every write, and at 2 read repair cannot converge at all. Every peer on the strand should use the same value: a peer configured much higher derives a larger expected cohort and can reject a coordinator's smaller declared peer set as a downsize. Frozen when the libp2p node is created, so a change takes effect on the next restart. Must be an integer ≥ 2 (`MIN_CLUSTER_SIZE`, Optimystic's own minimum). Leaving it unset is *not* the same as passing 4 elsewhere — Optimystic's own fallback is 10, so this default is applied here. Ignored when `libp2pNode` is injected |
-| `libp2pNode` | Libp2p | — | Inject an existing libp2p node |
-| `coordinatedRepo` | IRepo | — | Required when `libp2pNode` is provided |
-| `transactor` | `'local' \| 'network' \| 'test'` | `'network'` | Storage engine transactions go through. `'network'`: the strand's libp2p cohort, which a lone node coordinates for itself — the only value an application should use. `'local'`: this process's raw storage directly, no peers consulted (in-process tests and tooling). `'test'`: Optimystic's in-memory fake; no libp2p node is created unless one is injected (unit tests) |
-| `storage` | IRawStorage | — | Persistent raw storage. Borrowed — not closed on `shutdown()` |
-
-### Plugin settings (plugin-loader / Quoomb)
-
-| Setting | Type | Default | Description |
-|---|---|---|---|
-| `strand_id` | string | *required* | UUID of the strand |
-| `bootstrap_nodes` | string | `''` | Comma-separated bootstrap multiaddrs |
-| `schema` | string | — | sApp schema DDL |
-| `sapp_id` | string | `'unknown'` | sApp author public key |
-| `sapp_version` | string | `'1.0.0'` | sApp version |
-| `port` | number | `0` | libp2p listening port: an integer from 0 to 65535 (0 = random) |
-| `enable_cache` | boolean | `true` | Enable caching: `true`, `false`, `1` or `0` |
-| `fret_profile` | select | `'edge'` | FRET profile (`'edge'` or `'core'`) |
-| `transactor` | select | `'network'` | Storage engine (`'local'`, `'network'` or `'test'`) — see the `transactor` row above |
-| `storage_path` | string | — | Node entry only: directory for a persistent `FileRawStorage`. The browser entry rejects it (it stores in IndexedDB) |
-
-Settings are checked strictly at load. An unknown key (including the retired
-`mode`) or a value of the wrong type fails the load with one error that names
-every offending setting; nothing falls back to a default the user did not
-choose. Leaving a setting out, NULL, or `''` means "use the default" (`''`
-only for the string and select settings). A host that adds keys of its own to
-the plugin's settings map therefore fails to load the plugin. `port` and
-`enable_cache` must be a JSON number and boolean: a `${VAR}` reference in
-`quoomb.config.json` expands to a string, which they reject.
-
-**Bootstrap multiaddrs.** Browsers can only dial transports reachable from an
-`https://` page. Use `/wss` (or `/dns/.../wss`, or a relay-fronted multiaddr).
-Plain `/tcp/.../ws` over HTTP won't dial from a TLS origin, and raw TCP is
-unavailable in the browser.
-
-## Provided functions and modules
-
-Registered automatically from the composed plugins:
-
-- **Virtual table module**: `optimystic` (set as default vtab)
-- **Functions**: `StampId()`, `digest()`, `sign()`, `verify()`, `randomBytes()`
-
----
-
-## Development
-
-```bash
-yarn build    # tsc + esbuild (emits dist/plugin.js and dist/plugin-browser.js)
-yarn test     # Run tests (unit + e2e projects, plus browser-bundle smoke tests)
-yarn test:e2e # Run only the e2e project (real libp2p + FileRawStorage)
-yarn dev:test # Watch mode
-```
-
-`build` runs `tsc -p tsconfig.build.json` (emits `dist/plugin.js`,
-`dist/plugin-browser.js` declarations, and other entries) and then
-`node scripts/build-browser.mjs` (overwrites `dist/plugin-browser.js` with the
-bundled artifact and its sourcemap, and prints raw + gzipped size).
-
-The browser-bundle smoke tests (`test/browser-bundle.spec.ts` and
-`test/browser-shape.spec.ts`) run under the `unit` project: they build the
-bundle on demand if missing, then check that the artifact parses as ESM, has no
-Node-only or TCP imports, stays under the size caps, and that its default export
-reaches the IndexedDB layer in a jsdom + `fake-indexeddb` environment.
-
-The `e2e` project covers two scenarios over real libp2p + `FileRawStorage`:
-
-- `test/e2e/local-transactor.e2e.spec.ts` — a single in-process connection on the
-  `local` transactor, including cold-restart persistence across the shared
-  storage directory.
-- `test/e2e/networked.e2e.spec.ts` — two in-process peers exchanging strand data
-  through a `createLibp2pNode` mesh: cross-peer replication, bidirectional
-  convergence, and late-joiner catch-up.
-
-## Publishing
-
-From the monorepo root:
-
-```bash
-yarn pub:quereus-plugin-sereus   # clean + build + npm publish --access public
-```
-
-This is also included in the aggregate `yarn pub` release step. Publishing emits
-both `dist/plugin.js` and the browser bundle `dist/plugin-browser.js` (both are
-in the package `files`), so the CDN URLs under [Hosting the browser
-bundle](#hosting-the-browser-bundle) resolve immediately after a successful
-publish.
-
-## License
-
-MIT
-</content>
-</invoke>
+# @serfab/quereus-plugin-sereus
+
+A [Quereus](https://github.com/nicktobey/quereus) plugin that connects a Quereus
+database to a [Sereus](../../docs/architecture.md) strand for SQL access. It
+composes the [@optimystic/quereus-plugin-crypto](https://github.com/nicktobey/optimystic/tree/main/packages/quereus-plugin-crypto)
+and [@optimystic/quereus-plugin-optimystic](https://github.com/nicktobey/optimystic/tree/main/packages/quereus-plugin-optimystic)
+plugins, manages libp2p networking, and optionally applies a sApp schema.
+
+## Features
+
+- **Strand connection**: Connect a Quereus database to a Sereus strand with a single call.
+- **Plugin composition**: Automatically registers the crypto and optimystic plugins.
+- **Node management**: Creates a libp2p node or accepts an injected one (e.g. from a CadreNode).
+- **Schema application**: Wraps DDL in `declare schema App { ... } apply schema App;`.
+- **Two runtimes**: A Node entry (`./plugin`) and a self-contained browser bundle
+  (`./plugin-browser`) for Quoomb-web and other browser/worker hosts.
+- **Two entry points**: A plugin-loader-compatible default export and a
+  programmatic `connectToStrand()` API.
+
+## Artifacts
+
+The package ships two plugin artifacts, selected automatically by the consumer's
+environment via the `exports` map:
+
+| Artifact | Built by | Transports | Default storage | Use from |
+|---|---|---|---|---|
+| `dist/plugin.js` | `tsc` | TCP + WebSockets | in-memory / FS | Node (`./plugin`) |
+| `dist/plugin-browser.js` | `esbuild` | WebSockets + circuit-relay | IndexedDB | Browser/worker (`./plugin-browser`) |
+
+The browser bundle is a single self-contained, minified ESM file of roughly 1.9 MiB
+raw / 0.6 MiB gzipped (the exact measurement and its date live beside the size caps in
+`test/browser-bundle.spec.ts`; a second copy of the numbers here would go stale). A
+source map, `dist/plugin-browser.js.map`, ships beside it with the original sources
+embedded, so devtools still show readable code. It bundles only the TCP-free libp2p
+surface (`@optimystic/db-p2p/rn`) and does **not** import `@quereus/quereus` at
+runtime — registrations are applied against the host-supplied `db`, so it reuses the
+host's Quereus instance rather than instantiating a second one.
+
+## Installation
+
+```bash
+npm install @serfab/quereus-plugin-sereus
+# or
+yarn add @serfab/quereus-plugin-sereus
+```
+
+---
+
+## Using it from Quoomb Web (step by step)
+
+[Quoomb Web](../../../quereus/packages/quoomb-web) loads plugins by URL: its
+worker calls `import(url)` and registers the module's default export against the
+live database. To connect Quoomb Web to a strand you need to (1) make the
+**browser bundle** reachable at an importable URL, and (2) give it a strand id
+and at least one **browser-dialable** bootstrap address.
+
+### Prerequisites
+
+- A **strand id** (UUID) to connect to.
+- For networked use: a libp2p **bootstrap/relay reachable over secure WebSockets**
+  (`/wss`) from an `https://` page. Browsers cannot dial raw TCP, and a plain
+  `ws://`/`tcp` address will not dial from a TLS origin. WebSockets +
+  circuit-relay are the only supported transports in v1.
+- The strand's **sApp schema** (optional — only needed to bootstrap a brand-new
+  strand or to expose `App.*` tables before any peer has).
+
+### Step 1 — Make the browser bundle importable
+
+Pick one of the hosting options below ([Hosting the browser
+bundle](#hosting-the-browser-bundle)). The quickest are:
+
+- **Published CDN URL** (recommended once published):
+  `https://cdn.jsdelivr.net/npm/@serfab/quereus-plugin-sereus/dist/plugin-browser.js`
+- **Local dev**: copy `dist/plugin-browser.js` into Quoomb Web's `public/` folder
+  so it is served same-origin at `http://localhost:5173/plugin-browser.js`.
+
+The URL must serve the file with `Content-Type: text/javascript` (or
+`application/javascript`) and CORS that permits the page origin.
+
+### Step 2a — Load via the Plugins panel (manual)
+
+1. Open Quoomb Web → **Plugins** panel.
+2. Paste the bundle URL into the plugin URL field and install it.
+   - The manual installer validates the URL and only accepts **`https://`** (or
+     `file://`) ending in `.js`/`.mjs`. A same-origin `http://localhost` URL is
+     **rejected here** — use Step 2b (config) for local-dev http, or serve
+     Quoomb over https.
+3. Open the plugin's config and set at least:
+   - `strand_id` — the strand UUID.
+   - `bootstrap_nodes` — comma-separated `/wss` multiaddrs.
+   - `schema` — optional sApp DDL.
+4. Run a query, e.g. `select * from App.Message`.
+
+### Step 2b — Load via `quoomb.config.json` (autoload)
+
+The config/autoload path calls the loader directly and **bypasses the
+https-only check**, so it is the right choice for local `http://localhost`
+during development. In Quoomb Web, open the **Config** modal and import this
+JSON (or set it as `quoomb.config.json`):
+
+```jsonc
+{
+  "plugins": [
+    {
+      "source": "https://cdn.jsdelivr.net/npm/@serfab/quereus-plugin-sereus/dist/plugin-browser.js",
+      "config": {
+        "strand_id": "550e8400-e29b-41d4-a716-446655440000",
+        "bootstrap_nodes": "/dns4/relay.example/tcp/443/wss/p2p/Qm...",
+        "schema": "table Message (Id integer primary key, Content text not null)"
+      }
+    }
+  ],
+  "autoload": true
+}
+```
+
+With `autoload: true`, the plugin loads on session start and applies the schema.
+
+### Step 3 — Query the strand
+
+Once loaded, the `optimystic` vtab is the default and `App.*` tables resolve
+against the strand:
+
+```sql
+select * from App.Message;
+insert into App.Message (Id, Content) values (1, 'hello strand');
+```
+
+### Notes & limitations
+
+- **Storage.** When `storage` is not injected, the browser bundle opens a default
+  `IndexedDBRawStorage` against an IndexedDB database named
+  `sereus-strand-<strandId>`. State survives reload. The plugin treats the
+  IndexedDB handle as borrowed and does **not** close it on `shutdown()` — its
+  lifecycle is the page/worker.
+- **Network transactor by default.** Every connection commits through the
+  strand's libp2p cohort unless it asks otherwise; the in-process `local`
+  transactor is a testing/tooling option (`connectToStrand({ transactor:
+  'local' })`), not a browser deployment mode.
+- **WebRTC** requires cross-origin isolation (COOP/COEP) and is tracked as a
+  follow-up; v1 is WebSockets + circuit-relay only.
+- **Lifecycle.** Quoomb Web's loader keeps only the manifest and discards the
+  plugin's returned `shutdown()`, so the libp2p node is torn down with the
+  worker rather than on plugin unload.
+
+---
+
+## Hosting the browser bundle
+
+The browser bundle is just an ESM file; it can be served from anywhere that
+returns a JavaScript content type with appropriate CORS.
+
+### Published package on a CDN (recommended)
+
+After `yarn pub:quereus-plugin-sereus` (see [Publishing](#publishing)), the npm
+package is mirrored by the public CDNs, which serve the correct content type and
+CORS automatically:
+
+- jsDelivr: `https://cdn.jsdelivr.net/npm/@serfab/quereus-plugin-sereus/dist/plugin-browser.js`
+- jsDelivr (pinned): `https://cdn.jsdelivr.net/npm/@serfab/quereus-plugin-sereus@0.7.1/dist/plugin-browser.js`
+- unpkg: `https://unpkg.com/@serfab/quereus-plugin-sereus/dist/plugin-browser.js`
+
+### Self-hosted / same-origin
+
+Copy `dist/plugin-browser.js` to any static host (or Quoomb Web's `public/`) and
+reference it by URL. Same-origin hosting sidesteps CORS entirely.
+
+### Loading from GitHub
+
+Loading the bundle straight from a GitHub repo has a caveat: **`dist/` is
+gitignored**, and `raw.githubusercontent.com` serves files as `text/plain` with
+`X-Content-Type-Options: nosniff`, so the browser refuses to `import()` it as a
+module. Two routes that *do* work:
+
+1. **jsDelivr's GitHub endpoint**, which serves repo files with the correct MIME
+   type and CORS — but only files that exist at the ref. Since `dist/` is not
+   committed, this requires the built bundle to be present at the ref you point
+   at (e.g. a CI step that commits `plugin-browser.js` to a `dist`/`gh-pages`
+   branch or a tag):
+
+   ```
+   https://cdn.jsdelivr.net/gh/gotchoices/sereus@<tag-or-branch>/packages/quereus-plugin-sereus/dist/plugin-browser.js
+   ```
+
+2. **GitHub Pages**: publish `plugin-browser.js` to a Pages site, which serves it
+   with a JavaScript content type and CORS.
+
+For most cases the npm-backed CDN URL above is simpler and is the recommended
+GitHub-free hosting path. (Note: GitHub *Release assets* are served as
+`application/octet-stream` and cannot be imported as ESM.)
+
+---
+
+## Programmatic API
+
+```typescript
+import { Database } from '@quereus/quereus';
+import { connectToStrand } from '@serfab/quereus-plugin-sereus';
+
+const db = new Database();
+const strand = await connectToStrand(db, {
+  strandId: '550e8400-e29b-41d4-a716-446655440000',
+  schema: 'table Message (Id integer primary key, Content text not null)',
+  bootstrapNodes: ['/ip4/1.2.3.4/tcp/9100/p2p/QmPeerId'],
+});
+
+for await (const row of db.eval('select * from App.Message')) {
+  console.log(row);
+}
+
+await strand.shutdown();
+```
+
+### Plugin-loader (Node)
+
+The `./plugin` export is compatible with Quereus plugin-loader:
+
+```typescript
+import { Database, registerPlugin } from '@quereus/quereus';
+import sereusPlugin from '@serfab/quereus-plugin-sereus/plugin';
+
+const db = new Database();
+const result = await registerPlugin(db, sereusPlugin, {
+  strand_id: '550e8400-e29b-41d4-a716-446655440000',
+  schema: 'table Message (Id integer primary key, Content text not null)',
+  bootstrap_nodes: '/ip4/1.2.3.4/tcp/9100/p2p/QmPeerId',
+});
+
+await result.shutdown();
+```
+
+### Local transactor (in-process, no cohort)
+
+`transactor: 'local'` sends every transaction straight to this process's raw
+storage — no peers are consulted at all. It is for in-process tests and tooling
+(this package's own e2e suites run on it); applications should stay on the
+default `network` transactor, which a lone node coordinates for itself.
+
+Pair it with a persistent `IRawStorage` to survive restart: the same storage
+instance is wired into both the libp2p data path and the optimystic plugin's
+local transactor.
+
+```typescript
+import { FileRawStorage } from '@optimystic/db-p2p-storage-fs';
+
+const storage = new FileRawStorage('./data/my-strand');
+const strand = await connectToStrand(db, {
+  strandId: 'abc',
+  transactor: 'local',
+  storage,
+  schema: 'table Msg (Id integer primary key, Body text not null)',
+});
+```
+
+The plugin treats `storage` as borrowed: `shutdown()` releases the libp2p node
+and collection factory but does **not** close the storage.
+
+### With an injected node
+
+When integrating with an existing CadreNode or other libp2p host:
+
+```typescript
+const strand = await connectToStrand(db, {
+  strandId: 'abc',
+  libp2pNode: existingNode,
+  coordinatedRepo: existingRepo,
+});
+```
+
+The plugin uses the injected node instead of creating one, and will not stop it
+on shutdown.
+
+### A commit's durability
+
+The result's `onCommitDurability(listener)` is called after every commit that wrote something, before the commit returns, with who holds what it wrote; `onCommitFullyHeld(listener)` is called once when a commit reported `followed` below full replication becomes held by its whole cohort. Both pass through from `@optimystic/quereus-plugin-optimystic`, whose README explains the report ([A commit's durability](https://github.com/gotchoices/optimystic/blob/main/packages/quereus-plugin-optimystic/README.md#a-commits-durability--pluginoncommitdurabilitylistener)); the `SqlCommitDurability` and `CommitFullyHeld` types are re-exported here. A cadre app reads the same reports through `@serfab/cadre-core` ([strands.md → A commit's durability](../../docs/strands.md#a-commits-durability)).
+
+### Founding a strand: `createEmptyCollections()`
+
+A table nobody has written has no collection, so no single machine can show it empty: every read of it asks the other members, and fails while they are offline. The result's `createEmptyCollections(except?)` commits an empty collection for every table the `Strand` and `App` schemas declare that has none yet, and resolves to how many it committed. `except` lists qualified tables (`'Strand.Header'`) the caller is about to write: their inserts create their collections, so every tree of those tables is left out, and a name matching no declared table throws. The founder calls it once, before its founding write, while no other machine can have written to the strand; cadre-core's founder bootstrap does this, leaving out the tables its founding transaction writes ([strands.md → Joining](../../docs/strands.md#joining-no-writes-before-the-first-sync)). Call it only while nothing else writes through the `Database`: it commits whatever is staged in those collections outside any SQL transaction.
+
+The same step is exported on its own as `createEmptyCollections(db, bridge, schemaNames, except?)`, for a database composed outside this plugin: `bridge` is the Optimystic plugin's transaction bridge (`txnBridge` on its result), and the call throws when `schemaNames` declare no Optimystic table. cadre-core's control-database genesis calls it with `['CadreControl']` ([architecture.md → Control tables are network-backed](../../docs/architecture.md#control-tables-are-network-backed)).
+
+---
+
+## Configuration
+
+### `StrandConnectionOptions` (programmatic API)
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `strandId` | string | *required* | UUID of the strand to connect to |
+| `bootstrapNodes` | string[] | `[]` | Bootstrap multiaddrs for peer discovery |
+| `schema` | string | — | sApp schema DDL to apply, as the body of `declare schema App { ... }`. An item the Quereus parser would skip (`create unique index …`, a misspelled item keyword) is refused rather than ignored. Its tables may share names with the strand's own tables; they are stored separately ([Same-Named Tables](../../docs/strands.md#same-named-tables-in-strand-and-app)) |
+| `sAppId` | string | `'unknown'` | sApp author public key |
+| `sAppVersion` | string | `'1.0.0'` | sApp version |
+| `port` | number | `0` | libp2p listening port (0 = random) |
+| `enableCache` | boolean | `true` | Enable optimystic caching |
+| `fretProfile` | `'edge' \| 'core'` | `'edge'` | FRET profile |
+| `clusterSize` | number | `4` | Nodes the **strand's** replication cluster should have (the control network uses its own fixed `CONTROL_REPLICATION_BREADTH` and never reads this). 4 is the smallest breadth whose 0.75 super-majority (`ceil(4 × 0.75) = 3`) still commits with one holder offline; at 2 or 3 every holder must be awake for every write, and at 2 read repair cannot converge at all. Every peer on the strand should use the same value: a peer configured much higher derives a larger expected cohort and can reject a coordinator's smaller declared peer set as a downsize. Frozen when the libp2p node is created, so a change takes effect on the next restart. Must be an integer ≥ 2 (`MIN_CLUSTER_SIZE`, Optimystic's own minimum). Leaving it unset is *not* the same as passing 4 elsewhere — Optimystic's own fallback is 10, so this default is applied here. Ignored when `libp2pNode` is injected |
+| `libp2pNode` | Libp2p | — | Inject an existing libp2p node |
+| `coordinatedRepo` | IRepo | — | Required when `libp2pNode` is provided |
+| `transactor` | `'local' \| 'network' \| 'test'` | `'network'` | Storage engine transactions go through. `'network'`: the strand's libp2p cohort, which a lone node coordinates for itself — the only value an application should use. `'local'`: this process's raw storage directly, no peers consulted (in-process tests and tooling). `'test'`: Optimystic's in-memory fake; no libp2p node is created unless one is injected (unit tests) |
+| `storage` | IRawStorage | — | Persistent raw storage. Borrowed — not closed on `shutdown()` |
+
+### Plugin settings (plugin-loader / Quoomb)
+
+| Setting | Type | Default | Description |
+|---|---|---|---|
+| `strand_id` | string | *required* | UUID of the strand |
+| `bootstrap_nodes` | string | `''` | Comma-separated bootstrap multiaddrs |
+| `schema` | string | — | sApp schema DDL |
+| `sapp_id` | string | `'unknown'` | sApp author public key |
+| `sapp_version` | string | `'1.0.0'` | sApp version |
+| `port` | number | `0` | libp2p listening port: an integer from 0 to 65535 (0 = random) |
+| `enable_cache` | boolean | `true` | Enable caching: `true`, `false`, `1` or `0` |
+| `fret_profile` | select | `'edge'` | FRET profile (`'edge'` or `'core'`) |
+| `transactor` | select | `'network'` | Storage engine (`'local'`, `'network'` or `'test'`) — see the `transactor` row above |
+| `storage_path` | string | — | Node entry only: directory for a persistent `FileRawStorage`. The browser entry rejects it (it stores in IndexedDB) |
+
+Settings are checked strictly at load. An unknown key (including the retired
+`mode`) or a value of the wrong type fails the load with one error that names
+every offending setting; nothing falls back to a default the user did not
+choose. Leaving a setting out, NULL, or `''` means "use the default" (`''`
+only for the string and select settings). A host that adds keys of its own to
+the plugin's settings map therefore fails to load the plugin. `port` and
+`enable_cache` must be a JSON number and boolean: a `${VAR}` reference in
+`quoomb.config.json` expands to a string, which they reject.
+
+**Bootstrap multiaddrs.** Browsers can only dial transports reachable from an
+`https://` page. Use `/wss` (or `/dns/.../wss`, or a relay-fronted multiaddr).
+Plain `/tcp/.../ws` over HTTP won't dial from a TLS origin, and raw TCP is
+unavailable in the browser.
+
+## Provided functions and modules
+
+Registered automatically from the composed plugins:
+
+- **Virtual table module**: `optimystic` (set as default vtab)
+- **Functions**: `StampId()`, `digest()`, `sign()`, `verify()`, `randomBytes()`
+
+---
+
+## Development
+
+```bash
+yarn build    # tsc + esbuild (emits dist/plugin.js and dist/plugin-browser.js)
+yarn test     # Run tests (unit + e2e projects, plus browser-bundle smoke tests)
+yarn test:e2e # Run only the e2e project (real libp2p + FileRawStorage)
+yarn dev:test # Watch mode
+```
+
+`build` runs `tsc -p tsconfig.build.json` (emits `dist/plugin.js`,
+`dist/plugin-browser.js` declarations, and other entries) and then
+`node scripts/build-browser.mjs` (overwrites `dist/plugin-browser.js` with the
+bundled artifact and its sourcemap, and prints raw + gzipped size).
+
+The browser-bundle smoke tests (`test/browser-bundle.spec.ts` and
+`test/browser-shape.spec.ts`) run under the `unit` project: they build the
+bundle on demand if missing, then check that the artifact parses as ESM, has no
+Node-only or TCP imports, stays under the size caps, and that its default export
+reaches the IndexedDB layer in a jsdom + `fake-indexeddb` environment.
+
+The `e2e` project covers two scenarios over real libp2p + `FileRawStorage`:
+
+- `test/e2e/local-transactor.e2e.spec.ts` — a single in-process connection on the
+  `local` transactor, including cold-restart persistence across the shared
+  storage directory.
+- `test/e2e/networked.e2e.spec.ts` — two in-process peers exchanging strand data
+  through a `createLibp2pNode` mesh: cross-peer replication, bidirectional
+  convergence, and late-joiner catch-up.
+
+## Publishing
+
+From the monorepo root:
+
+```bash
+yarn pub:quereus-plugin-sereus   # clean + build + npm publish --access public
+```
+
+This is also included in the aggregate `yarn pub` release step. Publishing emits
+both `dist/plugin.js` and the browser bundle `dist/plugin-browser.js` (both are
+in the package `files`), so the CDN URLs under [Hosting the browser
+bundle](#hosting-the-browser-bundle) resolve immediately after a successful
+publish.
+
+## License
+
+MIT
+</content>
+</invoke>