@serfab/quereus-plugin-sereus 0.9.0 → 0.11.0

package/dist/types.d.ts

@@ -1,6 +1,21 @@
 import type { Libp2p } from '@libp2p/interface';
 import type { IRepo } from '@optimystic/db-core';
 import type { IRawStorage } from '@optimystic/db-p2p';
+/**
+ * Which Optimystic transactor a strand connection commits through — a choice of
+ * storage engine, nothing more. See {@link StrandConnectionOptions.transactor}.
+ *
+ * Deliberately a closed union, and narrower than what Optimystic's
+ * `collection-factory.ts` accepts: that factory also switches on `'mesh-test'`
+ * (its production transactor stack over a one-node mock mesh) and falls through
+ * to a host-registered custom transactor for any other name. Neither is offered
+ * here — `composeStrand`'s node gate special-cases only `'test'`, so
+ * `'mesh-test'` would get a real libp2p node it does not want, and nothing in
+ * this repo registers a custom transactor. A closed union lets `parseConfig`
+ * reject a typo (`'locl'`) instead of handing it downstream; widen it (and the
+ * node gate with it) when one of those values is actually needed.
+ */
+export type StrandTransactor = 'local' | 'network' | 'test';
 export interface StrandConnectionOptions {
     /** UUID of the strand to connect to */
     strandId: string;
@@ -18,29 +33,43 @@ export interface StrandConnectionOptions {
     enableCache?: boolean;
     /** FRET profile (default: 'edge') */
     fretProfile?: 'edge' | 'core';
+    /**
+     * Number of nodes Optimystic is told this strand's replication cluster should
+     * have. Ignored when {@link libp2pNode} is injected (the injected node was
+     * built with its own value). Every peer on the strand should use the same
+     * number — see `resolveStrandClusterSize`. Defaults to
+     * `DEFAULT_STRAND_CLUSTER_SIZE` (4 — the smallest breadth whose 0.75
+     * super-majority still commits with one holder offline).
+     */
+    clusterSize?: number;
     /** Inject an existing libp2p node instead of creating one */
     libp2pNode?: Libp2p;
     /** Required when libp2pNode is provided */
     coordinatedRepo?: IRepo;
-    /**
-     * Lifecycle mode. `'networked'` (default) uses the network transactor and
-     * is appropriate for multi-peer participation. `'bootstrap'` switches to a
-     * local transactor so a solo node can apply schema and accept DML with no
-     * peer round trips; pair it with a persistent `storage` to survive restart.
-     */
-    mode?: 'bootstrap' | 'networked';
     /**
      * Persistent raw storage. When provided:
      *  - it is passed to `createLibp2pNode` as `storage` so the libp2p data path uses it,
-     *  - in `bootstrap` mode it is also handed to the optimystic plugin as
+     *  - with `transactor: 'local'` it is also handed to the optimystic plugin as
      *    `rawStorageFactory: () => storage` so the local transactor persists DML
      *    on the same instance (avoids cache divergence between the two consumers).
      *
      * The plugin treats `storage` as borrowed — it is NOT closed on `shutdown()`.
      */
     storage?: IRawStorage;
-    /** @internal Override transactor type. Used by unit tests with `'test'`. When set, takes precedence only if `mode` is not specified. */
-    transactor?: string;
+    /**
+     * Which Optimystic transactor writes and reads go through (default
+     * `'network'`):
+     *
+     *  - `'network'` — transactions go through the strand's libp2p cohort. A node
+     *    that is alone coordinates for itself, so this works with one peer or
+     *    many; it is the only value an application should use.
+     *  - `'local'` — transactions go straight to this process's raw storage, no
+     *    peers consulted. For in-process tests and tooling; pair it with a
+     *    persistent {@link storage} to survive restart.
+     *  - `'test'` — Optimystic's in-memory fake. No libp2p node is created unless
+     *    one is injected. Unit tests only.
+     */
+    transactor?: StrandTransactor;
 }
 export interface SereusPluginResult {
     vtables: [];
@@ -57,6 +86,13 @@ export interface SereusPluginResult {
         tables: number;
         indexes: number;
     };
+    /**
+     * The transactor this connection actually resolved to — the RESOLVED value,
+     * not the requested one, so a spec whose whole point is the arm it runs on can
+     * assert it rather than assume it. Equals `options.transactor` when one was
+     * given, `'network'` otherwise.
+     */
+    transactor: StrandTransactor;
     /** Shuts down the libp2p node and collection factory. Call when done. */
     shutdown: () => Promise<void>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serfab/quereus-plugin-sereus",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "type": "module",
   "description": "Quereus plugin that connects to a Sereus strand for SQL access",
   "main": "dist/index.js",
@@ -67,13 +67,13 @@
     "@libp2p/circuit-relay-v2": "^4.1.3",
     "@libp2p/interface": "^3.1.0",
     "@libp2p/websockets": "^10.1.3",
-    "@optimystic/db-core": "^0.14.1",
-    "@optimystic/db-p2p": "^0.14.1",
-    "@optimystic/db-p2p-storage-fs": "^0.14.1",
-    "@optimystic/db-p2p-storage-web": "^0.14.1",
-    "@optimystic/quereus-plugin-crypto": "^0.14.1",
-    "@optimystic/quereus-plugin-optimystic": "^0.14.1",
-    "@quereus/quereus": "^4.4.0",
+    "@optimystic/db-core": "^0.24.0",
+    "@optimystic/db-p2p": "^0.24.0",
+    "@optimystic/db-p2p-storage-fs": "^0.24.0",
+    "@optimystic/db-p2p-storage-web": "^0.24.0",
+    "@optimystic/quereus-plugin-crypto": "^0.24.0",
+    "@optimystic/quereus-plugin-optimystic": "^0.24.0",
+    "@quereus/quereus": "^4.14.0",
     "debug": "^4.4.3"
   },
   "quereus": {

package/src/cached-storage.ts

@@ -0,0 +1,107 @@
+/**
+ * Wrap an embedder-supplied `IRawStorage` in `@optimystic/db-p2p`'s write-through
+ * raw-storage cache (`CachedRawStorage`) before handing it to a node or transactor.
+ *
+ * Why: bringing a control database or strand up is raw-storage-operation bound —
+ * uncached, a cold start re-reads the same handful of blocks ~2000 times (see the
+ * budget history in cadre-core's `test/control-start-storage-op-budget.spec.ts` and
+ * the sereus tickets `complete/optimystic-block-read-amplification-on-control-start`
+ * + `complete/optimystic-schema-catalog-reread-per-write-blows-storage-budgets`).
+ * Upstream ships the remedy as an opt-in wrapper — adoption is deliberately the
+ * consumer's choice — and this module is where Sereus opts in. It lives in this
+ * package (not cadre-core) for the same reason `cluster-size.ts` does: both the SQL
+ * plugin's own connectors (`composeStrand`, including the browser/IndexedDB path,
+ * where per-operation latency is highest) and cadre-core's control/strand seams
+ * need the identical wrap, and two copies could disagree.
+ *
+ * Soundness rests on the cache's single-process-owner invariant (upstream
+ * docs/storage.md §6): every write to the backend must funnel through the wrapped
+ * instance. Two rules uphold that:
+ *
+ * - **One wrap per inner instance** (WeakMap memo): the same `IRawStorage` reaches
+ *   this function from several seams at once — cadre-core's node wiring and the
+ *   strand backfill share the instance the node was built with, and the SQL
+ *   plugin's `composeStrand` re-wraps whatever it is handed. Two live caches over
+ *   one backend would each miss the other's writes; the memo makes the wrap
+ *   idempotent instead — a caller wrapping an already-wrapped or already-seen
+ *   instance gets the same object back.
+ * - **A Sereus process owns its data stores** — no second process writes the same
+ *   backend, which is the invariant's other half.
+ *
+ * `MemoryRawStorage` is returned unwrapped on upstream's own guidance: the backend
+ * is already in-memory, so the cache adds bookkeeping with nothing to save.
+ *
+ * The memo dedupes *concurrent* seams; it is not what keeps a cache alive across a
+ * runtime rebuild. That is cadre-core's job, and it does it by OWNERSHIP: one
+ * resolved store per scope per runtime lifetime — a strand's store for the life of
+ * its instance (a hibernation quiesce → resume reuses the store already resolved,
+ * so the wake lands on a warm cache), the control store for the life of one
+ * `CadreNode.start()`. Because the store outlives the rebuild, so does its wrap,
+ * whether or not the embedder's provider returns a stable instance.
+ *
+ * When a scope's runtime stops for good, cadre-core calls {@link disposeStorageCache}
+ * — the release half of that ownership. Without it the retired wrapper's
+ * `CacheStoreHandle` would stay in the shared pool's registry for the process
+ * lifetime (`unregisterStore` is the only removal), one orphan per stop.
+ */
+
+// Imported from the `/rn` entry — the platform-neutral surface (no Node-only
+// transports) — because `composeStrand` reaches this module on the browser path
+// too. Both db-p2p entrypoints re-export the same storage modules, so class
+// identity (the `instanceof` checks below) is unaffected on Node.
+import { CachedRawStorage, MemoryRawStorage, type IRawStorage } from '@optimystic/db-p2p/rn';
+
+const wraps = new WeakMap<IRawStorage, CachedRawStorage>();
+
+/**
+ * Reverse of `wraps`, so {@link disposeStorageCache} can evict the memo entry it
+ * cannot otherwise find — `wraps` is keyed by the inner instance, and dispose is
+ * handed the wrapper.
+ */
+const inners = new WeakMap<CachedRawStorage, IRawStorage>();
+
+/**
+ * The cached view of `storage`, memoized per instance. `label` names the store in
+ * the shared pool's `stats()` (e.g. `control`, or the strand id).
+ */
+export function wrapStorageWithCache(storage: IRawStorage, label: string): IRawStorage {
+	if (storage instanceof MemoryRawStorage || storage instanceof CachedRawStorage) {
+		return storage;
+	}
+	let wrapped = wraps.get(storage);
+	if (!wrapped) {
+		wrapped = new CachedRawStorage(storage, undefined, label);
+		wraps.set(storage, wrapped);
+		inners.set(wrapped, storage);
+	}
+	return wrapped;
+}
+
+/**
+ * Release the cache wrapper {@link wrapStorageWithCache} returned: unregister it from
+ * the shared pool and forget the memo, so a later re-wrap of the same inner instance
+ * gets a live cache rather than this retired one. A disposed wrapper must never be
+ * handed out again — its pool store id is retired and never reused — and providers
+ * that return a stable instance per scope (the web reference app's `strand-storage.ts`,
+ * the integration harness's `captureRawStorage`) would get exactly that back on a
+ * relaunch if the memo were left in place.
+ *
+ * No-op for anything this module returned unwrapped (e.g. `MemoryRawStorage`), so
+ * callers need no `instanceof` test. Only the wrapper is released: the inner store the
+ * embedder returned is never closed — that handle stays the embedder's to manage.
+ */
+export async function disposeStorageCache(storage: IRawStorage): Promise<void> {
+	if (!(storage instanceof CachedRawStorage)) {
+		return;
+	}
+	const inner = inners.get(storage);
+	if (inner) {
+		inners.delete(storage);
+		// Only evict the memo if it still points at THIS wrapper: a re-wrap after an
+		// earlier dispose has already installed a live successor we must not drop.
+		if (wraps.get(inner) === storage) {
+			wraps.delete(inner);
+		}
+	}
+	await storage.dispose();
+}

package/src/cluster-size.ts

@@ -0,0 +1,248 @@
+import type { NodeOptions } from '@optimystic/db-p2p';
+
+/**
+ * Smallest cluster size Optimystic will honour — its own `minAbsoluteClusterSize`,
+ * and the smallest value that reaches the cluster path at all (a lone node writes to
+ * local storage without forming a cluster). A validation floor, not a default.
+ */
+export const MIN_CLUSTER_SIZE = 2;
+
+/**
+ * How many nodes each block of the **control** (cadre membership) database is replicated
+ * to. Chosen to exceed any party's node count, so in practice every control block lands
+ * on every member of the party.
+ *
+ * **Why full replication here.** Every control node reads the whole control database —
+ * membership, peer addresses, the strand list — so a member left out of a block's cohort is
+ * a member that may never learn the fact, and at a cohort of two the *read repair* that is
+ * supposed to make that safe cannot converge (it can ask exactly one peer, and that peer may
+ * be the member that also missed the write). Measured: 4 failures in 10 runs of the
+ * control-DB replication scenario at size 2, 0 in 20 at size 3 and 0 in 10 at size 8.
+ *
+ * **Why this number, and why a constant.** Optimystic caps a cohort at the peers that
+ * actually serve the network and downsizes a cohort it cannot fill (`allowDownsize: true`,
+ * which Cadre passes), so any value at or above the party's node count yields the same
+ * behaviour: cohort = whole party. 16 is roughly twice the largest deployment the product
+ * documents (`docs/architecture.md` → "Enterprise (Multi-Node Mixed)", 7 nodes) — headroom
+ * without pretending to support arbitrarily large parties; a party genuinely running more
+ * than 16 nodes is back to partial replication for its control database and should raise
+ * this. It is a constant rather than the live member count because Optimystic freezes the
+ * value at libp2p-node construction, before the `ControlDatabase` holding the `CadrePeer`
+ * rows exists, and because a per-node derivation lets two members disagree.
+ *
+ * A cadre is one party by construction, so the owner-blind cohort-selection question that
+ * applies to strand networks (see {@link DEFAULT_STRAND_CLUSTER_SIZE} below) is not a question
+ * here: "replicate to the whole party" already is the whole intent, and there is no party
+ * diversity for this breadth to buy or fail to buy.
+ *
+ * Canonical explanation of all of the above — the read-repair mechanics, what whole-party
+ * breadth does and does not remove, and what the wider cohort costs in write availability —
+ * is `docs/architecture.md` → "Replication cluster size". Keep it there, not here.
+ *
+ * **Deliberately not `clusterPolicy.assumedClusterSize`.** That option means "the smallest
+ * cohort this deployment can genuinely field", and it feeds both the membership admission
+ * gate's low-confidence path *and* the read-repair/reconcile corroboration floor. A Cadre
+ * party legitimately runs one or two nodes, so Cadre leaves it at Optimystic's default of 2;
+ * asserting 16 there would make the admission gate demand `ceil(0.75 x 16) = 12` declared
+ * peers and refuse every real party's writes.
+ *
+ * NOTE: cohort selection overfetches proportionally to this number —
+ * `Libp2pKeyPeerNetwork.membershipOverfetch` asks FRET for
+ * `max(clusterSize * 4, clusterSize + 16)` candidates and does a peerStore protocol lookup
+ * per candidate, so 16 requests a 64-peer proximity band. Free today, because the result is
+ * bounded by the peers FRET actually knows (2 in a 3-node party). If control-network cohort
+ * selection ever shows up as slow on a large mesh, look here first.
+ */
+export const CONTROL_REPLICATION_BREADTH = 16;
+
+/**
+ * Cluster consensus policy every CONTROL-network libp2p node runs — production
+ * (`CadreNode.buildControlNodeOptions`) and the integration harness alike. One definition so
+ * the two cannot drift: the object literal used to be hand-copied at both sites, and the copy
+ * at the harness had picked up a `superMajorityThreshold` override production never had.
+ *
+ * `superMajorityThreshold` is deliberately ABSENT. Omitting it makes both the cluster member
+ * and the coordinator fall back to Optimystic's `DEFAULT_SUPER_MAJORITY_THRESHOLD` (0.75) —
+ * the bar a real party commits control writes against. Setting it here, or at any one
+ * consumer, reintroduces exactly the divergence this constant exists to prevent. The absence
+ * is a researched decision, not an inherited default: no threshold both relaxes the
+ * three-node unanimity bar and satisfies Optimystic's partition-safety condition at the
+ * shipped admission fraction — see `docs/architecture.md` → "Replication cluster size".
+ *
+ * `sizeTolerance` only makes sense alongside `allowDownsize`: a fixed
+ * {@link CONTROL_REPLICATION_BREADTH}-wide target is unsatisfiable by any real (2-7 node)
+ * party, so the cohort must be allowed to shrink to the party that actually exists.
+ *
+ * NOT for strand networks: {@link STRAND_CLUSTER_POLICY} is a structurally identical object
+ * for a different network with different reasoning. The shape match is a coincidence; keep
+ * them separate.
+ *
+ * `assumedClusterSize` is REQUIRED here, and 2 is not a guess — it is the smallest party we
+ * support. The field feeds two Optimystic consumers with opposite failure modes, and only one
+ * of them defaults to something workable for us:
+ *
+ * - The membership admission gate already defaults to 2 (`minAbsoluteClusterSize`), so naming
+ *   it changes nothing there.
+ * - The read-repair / reconcile corroboration floor does NOT. Absent this field it falls back
+ *   to `clusterSize` — which for the control network is {@link CONTROL_REPLICATION_BREADTH},
+ *   16. `corroboratorCapacity(peers, 16)` is then `max(peers, 15)`, so the floor of two
+ *   distinct non-self corroborators binds. A two-node party fields exactly one, can never
+ *   reach two, and so can never repair a block: `cluster-fetch:no-quorum` forever.
+ *
+ * Declaring 2 does NOT lower the replication factor — that stays at
+ * {@link CONTROL_REPLICATION_BREADTH}. It states the cohort size we can genuinely field, which
+ * is what the corroboration floor is asking. See Optimystic's `cluster/cluster-policy.ts`
+ * ("Why two size yardsticks, not one") and `corroboratorCapacity` in `cluster/quorum-restore.ts`.
+ *
+ * The `satisfies` is load-bearing: without it a mistyped or obsolete key would compile at both
+ * this definition and every consumer, because TypeScript only excess-property-checks fresh
+ * object literals, not a shared constant handed to `clusterPolicy`.
+ */
+export const CONTROL_CLUSTER_POLICY = Object.freeze({
+	allowDownsize: true,
+	sizeTolerance: 0.5,
+	assumedClusterSize: 2,
+} satisfies NonNullable<NodeOptions['clusterPolicy']>);
+
+/**
+ * Default number of nodes a **strand** network is told its replication cluster should have.
+ *
+ * Strand data is application data, where partial replication is a legitimate choice: only
+ * the control database's every-member-reads-all-of-it character forces full replication
+ * ({@link CONTROL_REPLICATION_BREADTH}). So the question here is not "everyone" but "how
+ * few is too few", and the answer is four.
+ *
+ * **Why four.** A write commits when a super-majority of the cohort approves, and that bar is
+ * Optimystic's `DEFAULT_SUPER_MAJORITY_THRESHOLD` of 0.75 — which Cadre selects by naming no
+ * threshold at all (see {@link CONTROL_CLUSTER_POLICY}). Approvals needed is
+ * `ceil(cohort x 0.75)`, so:
+ *
+ * | copies | approvals needed | holders that may be offline |
+ * |--------|------------------|-----------------------------|
+ * | 2      | 2                | 0                           |
+ * | 3      | 3                | 0                           |
+ * | 4      | 3                | 1                           |
+ * | 5      | 4                | 1                           |
+ * | 6      | 5                | 1                           |
+ *
+ * Four is the smallest breadth that lets a write commit while one holder is away. At two or
+ * three every holder must be awake for every write, which for a workspace shared between
+ * phones and laptops is the ordinary case, not the rare one. Six buys no more fault tolerance
+ * than four and costs more overfetch (see the NOTE below).
+ *
+ * **It is also a correctness floor, not only a durability one — but the floor is measured in
+ * machines, not in this number.** A node that has fallen behind and can ask exactly one peer
+ * whether it is current has Optimystic accept that single answer as the cluster's truth
+ * (`corroboratorCapacity` in `db-p2p/src/cluster/quorum-restore.ts` lowers the corroboration
+ * floor to one when the cohort cannot hold a second voter). If that peer is also behind it
+ * honestly reports the stale revision, the reader concludes it is current, and re-arms its
+ * repair window forever. Measured on the control-DB replication scenario: 4 failures in 10 runs
+ * at breadth 2, 0 in 20 at breadth 3, 0 in 10 at breadth 8. What lifts the floor off a single
+ * voter is a *third machine*, not a wider target: `corroboratorCapacity` takes the cohort peers
+ * actually present against {@link STRAND_CLUSTER_POLICY}'s declared `assumedClusterSize`, so a
+ * three-machine strand needs two corroborators whatever this number says, and a two-machine one
+ * cannot supply them however wide the target is. The underlying Optimystic behaviour is unfixed
+ * — `backlog/debt-read-repair-single-voter-corroboration` — so a two-machine strand still takes
+ * the exposure. Raising this number does not buy the way out; adding a machine does.
+ *
+ * **Why not derived from the party or member count.** The strand's `Member` rows live *in* the
+ * strand database, which runs on the strand libp2p node, whose cluster size is frozen at
+ * construction — reading the list to configure the node needs the node to exist. Open strands
+ * have no member list at all. The count also changes in the unsafe direction: a node that
+ * restarted after someone joined derives a wider expected cohort than one that did not, and the
+ * membership admission gate's confident path is what rejects the *wider* view. And a `Member` is
+ * a party, not a machine; cohort width consumes machines. Full reasoning in
+ * `docs/architecture.md` → "Replication cluster size".
+ *
+ * **Four machines, not four parties.** This number counts machines, and today that is not the
+ * same as counting independent holders. Cohort selection upstream is owner-blind — it
+ * picks nodes by hash proximity with no concept of which peer belongs to which party
+ * (`optimystic/tickets/backlog/feat-cohort-selection-owner-aware-placement`) — and on the
+ * cadre-driven path, the one that resolves a seed for itself, a strand's libp2p mesh is seeded
+ * from exactly one party's own control-database peer rows (`CadreNode.resolveCohortSeed`), so
+ * the cohort actually formed is that one party's machines. Four copies are, on that path, four
+ * machines belonging to one party — one failure domain, one witness. A cross-party mesh is not
+ * forbidden, only undiscoverable: it takes hand-supplied addresses
+ * (`StrandConnectionOptions.bootstrapNodes`) or a hand-written dial (see the doc). Tracked:
+ * `backlog/feat-strand-party-identity`. Full reasoning: `docs/architecture.md` →
+ * "Replication cluster size".
+ *
+ * Raising or lowering it per strand is still the embedder's call
+ * ({@link resolveStrandClusterSize}, `CadreNodeConfig.strandClusterSize`,
+ * `StrandConnectionOptions.clusterSize`) — but every node on one strand must agree, so a change
+ * means restarting all of them. There is no smaller-than-{@link MIN_CLUSTER_SIZE} option.
+ *
+ * NOTE: cohort selection overfetches proportionally — `Libp2pKeyPeerNetwork.membershipOverfetch`
+ * asks FRET for `max(clusterSize * 4, clusterSize + 16)` candidates and does one peerStore
+ * protocol lookup per candidate, so 4 requests a 20-peer band (was 18 at breadth 2). Negligible,
+ * and bounded by the peers FRET actually knows. If strand cohort selection ever shows up as slow,
+ * look here first.
+ */
+export const DEFAULT_STRAND_CLUSTER_SIZE = 4;
+
+/**
+ * Cluster consensus policy every STRAND-network libp2p node runs — production
+ * (`StrandInstanceManager.buildStrandRuntime`) and the plugin's own networked e2e mesh alike.
+ * One definition so the two cannot drift; the literal used to be hand-copied at both sites.
+ *
+ * Structurally identical to {@link CONTROL_CLUSTER_POLICY} and deliberately separate from it:
+ * that one is the control database's, whose breadth is fixed at
+ * {@link CONTROL_REPLICATION_BREADTH} for reasons that do not apply to application data.
+ *
+ * `superMajorityThreshold` is ABSENT for the same reason it is absent there: omitting it is how
+ * both the coordinator and the cluster member select Optimystic's
+ * `DEFAULT_SUPER_MAJORITY_THRESHOLD` (0.75), the bar {@link DEFAULT_STRAND_CLUSTER_SIZE}'s
+ * copies/approvals table is computed against.
+ *
+ * `sizeTolerance` only makes sense alongside `allowDownsize`: a {@link
+ * DEFAULT_STRAND_CLUSTER_SIZE}-wide target is unsatisfiable by a strand of one, two or three
+ * machines, so the cohort must be allowed to shrink to the mesh that actually exists.
+ *
+ * `assumedClusterSize` is REQUIRED, and {@link MIN_CLUSTER_SIZE} is not a guess — it is the
+ * smallest strand that reaches the cluster path at all. Absent this field the read-repair /
+ * reconcile corroboration floor falls back to `clusterSize`, so
+ * `corroboratorCapacity(peers, 4)` is `max(peers, 3)` and two distinct non-self corroborators
+ * become mandatory. A two-machine strand fields exactly one peer, can never reach two, and so
+ * can never repair a block — `cluster-fetch:no-quorum` forever, which is a read that never
+ * catches up and a `create table` that dies with `Missing block` on the joining node. Declaring
+ * the honest floor does NOT lower the replication factor (that stays at
+ * {@link DEFAULT_STRAND_CLUSTER_SIZE}) and does not relax anything a strand with three or more
+ * machines does: `corroboratorCapacity` takes the MAX of the cohort actually present and this
+ * number, so the relaxed branch is reachable only by a cohort that is genuinely that small. See
+ * Optimystic's `cluster/cluster-policy.ts` ("Why two size yardsticks, not one").
+ *
+ * The `satisfies` is load-bearing for the same reason as {@link CONTROL_CLUSTER_POLICY}'s.
+ */
+export const STRAND_CLUSTER_POLICY = Object.freeze({
+	allowDownsize: true,
+	sizeTolerance: 0.5,
+	assumedClusterSize: MIN_CLUSTER_SIZE,
+} satisfies NonNullable<NodeOptions['clusterPolicy']>);
+
+/**
+ * Resolve the cluster size to hand `createLibp2pNode` for a **strand** network, applying
+ * {@link DEFAULT_STRAND_CLUSTER_SIZE} and rejecting values Optimystic cannot honour. The
+ * control network does not route through here — it uses the fixed
+ * {@link CONTROL_REPLICATION_BREADTH}.
+ *
+ * Leaving the value unset is NOT the same as passing the default: Optimystic's own fallback
+ * is 10, so every strand node-creating path must route through here.
+ *
+ * Every node on the same strand should resolve to the same value: the membership admission
+ * gate's *confident* path compares a coordinator's declared set against the member's own
+ * cohort view, and that view is bounded by this number, so a member configured much higher
+ * can reject a smaller declared set as a downsize. Divergence is a live hazard whenever FRET
+ * has a confident network-size estimate — not the unconditional refusal earlier revisions of
+ * this comment described. See `docs/architecture.md` → "Replication cluster size".
+ */
+export function resolveStrandClusterSize(configured?: number): number {
+	if (configured === undefined) {
+		return DEFAULT_STRAND_CLUSTER_SIZE;
+	}
+	if (!Number.isInteger(configured) || configured < MIN_CLUSTER_SIZE) {
+		throw new Error(
+			`clusterSize must be an integer >= ${MIN_CLUSTER_SIZE} (Optimystic's minimum cluster size); got ${configured}`
+		);
+	}
+	return configured;
+}

package/src/compose-strand.ts

@@ -4,8 +4,10 @@ import optimysticPlugin from '@optimystic/quereus-plugin-optimystic/plugin';
 import type { Libp2p } from '@libp2p/interface';
 import type { IRepo } from '@optimystic/db-core';
 import type { IRawStorage } from '@optimystic/db-p2p';
-import type { StrandConnectionOptions, SereusPluginResult, Libp2pNodeWithRepo } from './types.js';
+import type { StrandConnectionOptions, SereusPluginResult, StrandTransactor, Libp2pNodeWithRepo } from './types.js';
 import { STRAND_SCHEMA } from './strand-schema.js';
+import { resolveStrandClusterSize } from './cluster-size.js';
+import { wrapStorageWithCache } from './cached-storage.js';
 
 const log = debug('sereus:plugin:strand');
 const timing = debug('sereus:plugin:strand:timing');
@@ -74,6 +76,12 @@ export interface CreateNodeContext {
 	fretProfile: 'edge' | 'core';
 	/** libp2p listening port (Node TCP). Browser transports ignore it. */
 	port: number;
+	/**
+	 * Resolved replication cluster size. Already defaulted — pass it to
+	 * `createLibp2pNode` verbatim; omitting it falls back to Optimystic's own
+	 * default of 10, which gates writes on any smaller party.
+	 */
+	clusterSize: number;
 	/** Resolved persistent storage to back the node, if any. */
 	storage?: IRawStorage;
 }
@@ -81,7 +89,7 @@ export interface CreateNodeContext {
 /** Context passed to the platform's storage-resolution strategy. */
 export interface ResolveStorageContext {
 	strandId: string;
-	resolvedTransactor: string;
+	resolvedTransactor: StrandTransactor;
 	/** The storage the caller passed in `options.storage`, if any. */
 	requestedStorage?: IRawStorage;
 }
@@ -136,40 +144,40 @@ export async function composeStrand(
 		port = 0,
 		enableCache = true,
 		fretProfile = 'edge',
-		mode,
+		transactor = 'network',
 	} = 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: string;
-	if (mode !== undefined) {
-		resolvedTransactor = mode === 'bootstrap' ? 'local' : 'network';
-	} else if (options.transactor !== undefined) {
-		resolvedTransactor = options.transactor;
-	} else {
-		resolvedTransactor = 'network';
-	}
+	// Resolve (and validate) up front so a nonsense value fails before any plugin
+	// registration or node creation has happened.
+	const clusterSize = resolveStrandClusterSize(options.clusterSize);
+
+	// The storage engine every write and read below goes through — see
+	// `StrandConnectionOptions.transactor`. Named separately from the option so
+	// the default is applied exactly once and reported on the result.
+	const resolvedTransactor: StrandTransactor = transactor;
 
 	const networkName = `strand-${strandId}`;
-	log('Connecting to strand %s (network: %s, mode=%s, transactor=%s)',
-		strandId, networkName, mode ?? '(default)', resolvedTransactor);
+	log('Connecting to strand %s (network: %s, transactor=%s)',
+		strandId, networkName, 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
+	// defaults to IndexedDB. The resolved instance feeds BOTH the local
+	// transactor's `rawStorageFactory` and node creation, so it must be decided
+	// up front (before pluginConfig is built). Wrapped in the write-through
+	// raw-storage cache (cached-storage.ts) — idempotent, so a caller that
+	// already wrapped (cadre-core's seams) passes through unchanged.
+	const resolvedStorage = platform.resolveStorage
 		? await platform.resolveStorage({ strandId, resolvedTransactor, requestedStorage: options.storage })
 		: options.storage;
+	const storage = resolvedStorage ? wrapStorageWithCache(resolvedStorage, strandId) : resolvedStorage;
 
 	// 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).
+	// 2. Register optimystic plugin with transactor defaults. On the local
+	// transactor with persistent storage, hand the same instance to the plugin so
+	// DML persists on the host backend (not in-memory).
 	const pluginConfig: Record<string, unknown> = {
 		default_transactor: resolvedTransactor,
 		default_key_network: 'libp2p',
@@ -209,7 +217,7 @@ export async function composeStrand(
 				coordinatedRepo = options.coordinatedRepo;
 				log('Using injected libp2p node');
 			} else {
-				const created = await platform.createNode({ networkName, bootstrapNodes, fretProfile, port, storage });
+				const created = await platform.createNode({ networkName, bootstrapNodes, fretProfile, port, clusterSize, storage });
 				createdNode = created;
 				node = created;
 				const repo = (created as Libp2pNodeWithRepo).coordinatedRepo;
@@ -302,6 +310,7 @@ export async function composeStrand(
 		functions: [],
 		collations: [],
 		hydrated,
+		transactor: resolvedTransactor,
 		async shutdown() {
 			log('Shutting down strand connection %s', strandId);
 			await collectionFactory.shutdown();