@serfab/quereus-plugin-sereus 0.8.0

package/README.md

@@ -0,0 +1,360 @@
+# @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 ESM file (~2.5 MiB raw, ~550 KiB
+gzipped). 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.
+- **Networked-only via the loader.** The plugin-loader settings expose the
+  `network` transactor; offline/solo `bootstrap` mode is only reachable through
+  the programmatic `connectToStrand({ mode: 'bootstrap' })` API.
+- **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();
+```
+
+### Bootstrap mode (solo node with persistent storage)
+
+For a solo node (e.g. first-launch sApp init, single-host dev) that should apply
+schema and accept DML without peer round trips, set `mode: 'bootstrap'` and pass
+a persistent `IRawStorage`. The same storage instance is wired into both the
+libp2p data path and the optimystic plugin's local transactor, so writes persist
+across restart.
+
+```typescript
+import { FileRawStorage } from '@optimystic/db-p2p-storage-fs';
+
+const storage = new FileRawStorage('./data/my-strand');
+const strand = await connectToStrand(db, {
+  strandId: 'abc',
+  mode: 'bootstrap',
+  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.
+
+---
+
+## 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 |
+| `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 |
+| `libp2pNode` | Libp2p | — | Inject an existing libp2p node |
+| `coordinatedRepo` | IRepo | — | Required when `libp2pNode` is provided |
+| `mode` | `'bootstrap' \| 'networked'` | `'networked'` | `'bootstrap'` routes through the local transactor (no peer round trips); `'networked'` uses the network transactor |
+| `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 |
+| `enable_cache` | boolean | `true` | Enable caching |
+| `fret_profile` | string | `'edge'` | FRET profile (`'edge'` or `'core'`) |
+
+**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/bootstrap.e2e.spec.ts` — solo-node bootstrap mode, 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>

package/dist/compose-strand.d.ts

@@ -0,0 +1,84 @@
+import type { Database } from '@quereus/quereus';
+import type { Libp2p } from '@libp2p/interface';
+import type { IRawStorage } from '@optimystic/db-p2p';
+import type { StrandConnectionOptions, SereusPluginResult } from './types.js';
+/** Registration shape shared by the crypto and optimystic plugin results. */
+interface PluginRegistrations {
+    vtables?: Array<{
+        name: string;
+        module: unknown;
+        auxData: unknown;
+    }>;
+    functions?: Array<{
+        schema: unknown;
+    }>;
+    collations?: Array<{
+        name: string;
+        func: unknown;
+        normalizer?: unknown;
+    }>;
+}
+/**
+ * Inline equivalent of `@quereus/quereus`'s `registerPlugin` for plugins that
+ * only return functions/vtables/collations. Used directly for the optimystic
+ * result (so the composition can read `collectionFactory` off the same object),
+ * and by the browser crypto strategy to keep the browser bundle from pulling a
+ * duplicate `@quereus/quereus` next to the host's instance.
+ */
+export declare function applyRegistrations(db: Database, result: PluginRegistrations): void;
+/** Context passed to the platform's node-creation strategy. */
+export interface CreateNodeContext {
+    networkName: string;
+    bootstrapNodes: string[];
+    fretProfile: 'edge' | 'core';
+    /** libp2p listening port (Node TCP). Browser transports ignore it. */
+    port: number;
+    /** Resolved persistent storage to back the node, if any. */
+    storage?: IRawStorage;
+}
+/** Context passed to the platform's storage-resolution strategy. */
+export interface ResolveStorageContext {
+    strandId: string;
+    resolvedTransactor: string;
+    /** The storage the caller passed in `options.storage`, if any. */
+    requestedStorage?: IRawStorage;
+}
+/**
+ * Platform-specific seams the shared composition delegates to. Everything else
+ * (transactor resolution, plugin config, registration, default vtab, hydrate,
+ * schema apply, cleanup/shutdown) is identical across Node and browser and lives
+ * in {@link composeStrand}.
+ */
+export interface StrandPlatform {
+    /**
+     * Register the crypto plugin against `db`. Node uses `@quereus/quereus`'s
+     * `registerPlugin`; the browser inlines `applyRegistrations` to avoid bundling
+     * a second `@quereus/quereus`.
+     */
+    registerCrypto(db: Database): void | Promise<void>;
+    /**
+     * Resolve the persistent storage to use. Optional — when omitted the caller's
+     * `options.storage` is used verbatim (Node). The browser supplies this to
+     * default to IndexedDB so a reload survives.
+     */
+    resolveStorage?(ctx: ResolveStorageContext): Promise<IRawStorage | undefined> | IRawStorage | undefined;
+    /**
+     * Create a libp2p node. Called only when no node is injected and the
+     * transactor needs one. Node creates a TCP node via `@optimystic/db-p2p`;
+     * the browser creates a WebSockets + circuit-relay node via the `/rn` entry.
+     * Returns the created node (its `coordinatedRepo` is read by the composition).
+     */
+    createNode(ctx: CreateNodeContext): Promise<Libp2p>;
+}
+/**
+ * Connect a Quereus `Database` to a Sereus strand. This is the single shared
+ * SQL-surface composition: `connectToStrand` (Node), `connectToStrandBrowser`
+ * (browser), and `cadre-core`'s `StrandDatabase` all flow through here, so the
+ * hydrate-before-apply fix and any future schema wiring land in one place.
+ *
+ * Steps: resolve transactor + storage, register crypto + optimystic plugins,
+ * acquire (inject or create) the libp2p node, set optimystic as the default
+ * vtab, hydrate the catalog, then apply the sApp schema.
+ */
+export declare function composeStrand(db: Database, options: StrandConnectionOptions, platform: StrandPlatform): Promise<SereusPluginResult>;
+export {};

package/dist/compose-strand.js

@@ -0,0 +1,194 @@
+import debug from 'debug';
+import optimysticPlugin from '@optimystic/quereus-plugin-optimystic/plugin';
+import { STRAND_SCHEMA } from './strand-schema.js';
+const log = debug('sereus:plugin:strand');
+const timing = debug('sereus:plugin:strand:timing');
+/**
+ * Inline equivalent of `@quereus/quereus`'s `registerPlugin` for plugins that
+ * only return functions/vtables/collations. Used directly for the optimystic
+ * result (so the composition can read `collectionFactory` off the same object),
+ * and by the browser crypto strategy to keep the browser bundle from pulling a
+ * duplicate `@quereus/quereus` next to the host's instance.
+ */
+export function applyRegistrations(db, result) {
+    for (const vtable of result.vtables ?? []) {
+        db.registerModule(vtable.name, vtable.module, vtable.auxData);
+    }
+    for (const func of result.functions ?? []) {
+        db.registerFunction(func.schema);
+    }
+    for (const collation of result.collations ?? []) {
+        db.registerCollation(collation.name, collation.func, collation.normalizer);
+    }
+}
+/**
+ * Connect a Quereus `Database` to a Sereus strand. This is the single shared
+ * SQL-surface composition: `connectToStrand` (Node), `connectToStrandBrowser`
+ * (browser), and `cadre-core`'s `StrandDatabase` all flow through here, so the
+ * hydrate-before-apply fix and any future schema wiring land in one place.
+ *
+ * Steps: resolve transactor + storage, register crypto + optimystic plugins,
+ * acquire (inject or create) the libp2p node, set optimystic as the default
+ * vtab, hydrate the catalog, then apply the sApp schema.
+ */
+export async function composeStrand(db, options, platform) {
+    const { strandId, bootstrapNodes = [], schema, port = 0, enableCache = true, fretProfile = 'edge', mode, } = options;
+    // Resolve the transactor. `mode` is the public knob: bootstrap -> local,
+    // networked -> network. The legacy `transactor` override (used by unit
+    // tests with `'test'`) only applies when `mode` is unspecified.
+    let resolvedTransactor;
+    if (mode !== undefined) {
+        resolvedTransactor = mode === 'bootstrap' ? 'local' : 'network';
+    }
+    else if (options.transactor !== undefined) {
+        resolvedTransactor = options.transactor;
+    }
+    else {
+        resolvedTransactor = 'network';
+    }
+    const networkName = `strand-${strandId}`;
+    log('Connecting to strand %s (network: %s, mode=%s, transactor=%s)', strandId, networkName, mode ?? '(default)', resolvedTransactor);
+    // Resolve storage. Node passes `options.storage` through; the browser
+    // defaults to IndexedDB. The resolved instance feeds BOTH the plugin's
+    // bootstrap `rawStorageFactory` and node creation, so it must be decided up
+    // front (before pluginConfig is built).
+    const storage = platform.resolveStorage
+        ? await platform.resolveStorage({ strandId, resolvedTransactor, requestedStorage: options.storage })
+        : options.storage;
+    // 1. Register crypto plugin (digest, sign, verify, etc.)
+    await platform.registerCrypto(db);
+    log('Registered crypto plugin');
+    // 2. Register optimystic plugin with transactor defaults. In local mode with
+    // persistent storage, hand the same instance to the plugin so the local
+    // transactor persists DML on the host backend (not in-memory).
+    const pluginConfig = {
+        default_transactor: resolvedTransactor,
+        default_key_network: 'libp2p',
+        default_network_name: networkName,
+        enable_cache: enableCache,
+    };
+    if (resolvedTransactor === 'local' && storage) {
+        pluginConfig.rawStorageFactory = () => storage;
+    }
+    // The plugin's published signature is `Record<string, SqlValue>` but it
+    // also reads `rawStorageFactory` (a function reference) from the same map.
+    // Cast through unknown rather than widen the public type.
+    const pluginResult = optimysticPlugin(db, pluginConfig);
+    applyRegistrations(db, pluginResult);
+    log('Registered optimystic vtables and functions');
+    const { collectionFactory } = pluginResult;
+    let createdNode = null;
+    let hydrated;
+    try {
+        // 3. Acquire the libp2p node. Skip only when this is the unit-test fake
+        // transactor with no injected node — every real path needs a node.
+        if (resolvedTransactor !== 'test' || options.libp2pNode) {
+            let node;
+            let coordinatedRepo;
+            if (options.libp2pNode) {
+                node = options.libp2pNode;
+                if (!options.coordinatedRepo) {
+                    throw new Error('coordinatedRepo is required when libp2pNode is provided');
+                }
+                coordinatedRepo = options.coordinatedRepo;
+                log('Using injected libp2p node');
+            }
+            else {
+                const created = await platform.createNode({ networkName, bootstrapNodes, fretProfile, port, storage });
+                createdNode = created;
+                node = created;
+                const repo = created.coordinatedRepo;
+                if (!repo) {
+                    throw new Error('coordinatedRepo not available on created libp2p node');
+                }
+                coordinatedRepo = repo;
+                log('Created libp2p node (port: %d, fretProfile: %s, storage=%s)', port, fretProfile, !!storage);
+            }
+            collectionFactory.registerLibp2pNode(networkName, node, coordinatedRepo);
+            log('Registered libp2p node with collection factory');
+        }
+        // 4. Set optimystic as default vtab so `declare schema` tables use it.
+        db.setDefaultVtabName('optimystic');
+        db.setDefaultVtabArgs({
+            networkName,
+            transactor: resolvedTransactor,
+            keyNetwork: 'libp2p',
+        });
+        log('Set default vtab to optimystic (networkName=%s, transactor=%s)', networkName, resolvedTransactor);
+        // 5. Hydrate Quereus's catalog from persisted optimystic vtab schemas
+        // BEFORE applying the sApp schema. Without this, a warm restart diffs the
+        // wrapped DDL against an empty catalog and re-emits CREATE TABLE / CREATE
+        // INDEX for every persisted object — each round-tripping through optimystic
+        // storage (the measured ~160s warm-start regression). No-op on first launch.
+        const t0 = performance.now();
+        hydrated = await pluginResult.hydrate(db);
+        timing('[strand:%s] hydrate: %dms (tables=%d, indexes=%d)', strandId, Math.round(performance.now() - t0), hydrated.tables, hydrated.indexes);
+        log('Hydrated catalog for strand %s (tables=%d, indexes=%d)', strandId, hydrated.tables, hydrated.indexes);
+        // 6. Apply the strand membership/RBAC schema (`schemas/strand.qsql`,
+        // embedded as STRAND_SCHEMA) UNCONDITIONALLY — every strand has membership
+        // semantics whether or not an sApp schema is supplied. There are no
+        // cross-schema references between `Strand` and `App`, so order is
+        // irrelevant; apply `Strand` first for clarity. Because this runs AFTER
+        // hydrate, a warm restart diffs the membership DDL against the already-
+        // hydrated catalog and re-emits nothing (same fix as the sApp apply).
+        //
+        // This ticket only makes the tables present and their constraints active;
+        // nothing here writes membership rows. Founder bootstrap (Header, founding
+        // Authority/Member, invite/peer flows) is owned by the lifecycle ticket
+        // `strand-membership-lifecycle-population`.
+        log('Applying Strand membership schema for strand %s', strandId);
+        await db.exec(`
+			declare schema Strand {
+				${STRAND_SCHEMA}
+			}
+			apply schema Strand;
+		`);
+        log('Strand membership schema applied');
+        // 7. Apply the sApp schema, if provided.
+        //
+        // SEAM: this and the Strand apply above are the single composition point
+        // where strand-level declarative DDL is applied. Keep new schema wiring
+        // here so it stays a one-location edit across Node, browser, and cadre-core.
+        if (schema) {
+            log('Applying sApp schema for strand %s', strandId);
+            await db.exec(`
+				declare schema App {
+					${schema}
+				}
+				apply schema App;
+			`);
+            log('sApp schema applied');
+        }
+    }
+    catch (err) {
+        // Clean up resources if setup fails after partial initialization.
+        await collectionFactory.shutdown();
+        if (createdNode) {
+            await createdNode.stop();
+        }
+        throw err;
+    }
+    // 8. Return result with hydrate counts + shutdown handler. `shutdown` tears
+    // down the collection factory, and `collectionFactory.shutdown()` stops EVERY
+    // node registered with it — including an injected one (registered via
+    // `registerLibp2pNode`). So an injected node IS stopped on `shutdown`; the
+    // `createdNode` guard below only avoids a redundant second `stop()` on a node
+    // we created ourselves, it is not what spares an injected node. A caller that
+    // needs an injected node to outlive `shutdown` must re-create it (cadre-core's
+    // `StrandInstanceManager` instead re-stops it, which is idempotent).
+    return {
+        vtables: [],
+        functions: [],
+        collations: [],
+        hydrated,
+        async shutdown() {
+            log('Shutting down strand connection %s', strandId);
+            await collectionFactory.shutdown();
+            if (createdNode) {
+                await createdNode.stop();
+            }
+            log('Strand connection %s shut down', strandId);
+        },
+    };
+}
+//# sourceMappingURL=compose-strand.js.map

package/dist/compose-strand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose-strand.js","sourceRoot":"","sources":["../src/compose-strand.ts"],"names":[],"mappings":"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"}

package/dist/connect-browser.d.ts

@@ -0,0 +1,14 @@
+import type { Database } from '@quereus/quereus';
+import type { StrandConnectionOptions, SereusPluginResult } from './types.js';
+/**
+ * Connect a Quereus Database to a Sereus strand from a browser/worker.
+ *
+ * Thin adapter over the shared {@link composeStrand} composition, supplying the
+ * browser platform seams:
+ *  - crypto registered inline (no runtime `@quereus/quereus` import, so the
+ *    bundle does not duplicate the host's instance),
+ *  - storage defaulting to `IndexedDBRawStorage` keyed by `sereus-strand-<id>`,
+ *  - a node created via the TCP-free `@optimystic/db-p2p/rn` entry with explicit
+ *    `webSockets()` + `circuitRelayTransport()` transports.
+ */
+export declare function connectToStrandBrowser(db: Database, options: StrandConnectionOptions): Promise<SereusPluginResult>;