@serfab/quereus-plugin-sereus 0.11.0 → 0.13.0

package/dist/cached-storage.d.ts

@@ -31,6 +31,19 @@
  * `MemoryRawStorage` is returned unwrapped on upstream's own guidance: the backend
  * is already in-memory, so the cache adds bookkeeping with nothing to save.
  *
+ * **{@link wrapStorageWithCache} and {@link disposeStorageCache} are a matched pair
+ * with a holder count between them.** Every wrap that hands back a cache this module
+ * created takes one claim on it; every dispose of that cache releases one. The cache
+ * is emptied, unregistered from the shared pool, and forgotten only when the LAST
+ * claim goes. That is what makes overlapping scopes safe: `CadreNodeConfig.storage.provider`
+ * may be a single `IRawStorage` shared by the control database and every workspace,
+ * and without a count the first scope to stop would retire the cache the others are
+ * still reading through — then the next scope to start, finding the memo empty, would
+ * build a SECOND cache over the same backend, and each would serve its own stale view
+ * (including remembered "this block does not exist" answers). It is also what lets
+ * `composeStrand` release its own claim unconditionally on `shutdown()` without having
+ * to guess whether it or cadre-core created the wrapper.
+ *
  * 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
@@ -39,28 +52,44 @@
  * `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.
+ * When a scope's runtime stops for good, it 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.
+ *
+ * NOTE: upstream ships an equivalent counted wrap of its own — `withReadCache`, which
+ * hands back a `ReadCacheLease` per caller and additionally dedupes by
+ * `getStoreIdentity()`, so two DISTINCT instances over one directory share one cache.
+ * This module keeps its own count instead, because its public surface releases by
+ * WRAPPER (`disposeStorageCache(storage)`) rather than by lease, and `withReadCache`
+ * returns no lease on its already-cached pass-through — which would leave
+ * `composeStrand`'s unconditional release unable to tell its own claim from cadre-core's.
+ * Adopting the lease API would mean changing that surface at all three call sites; worth
+ * doing if Sereus ever needs the identity-keyed dedupe (two `FileRawStorage` over one
+ * path), and not before.
  */
 import { type IRawStorage } from '@optimystic/db-p2p/rn';
 /**
- * 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).
+ * The cached view of `storage`, memoized per instance, with one holder claim taken for
+ * this caller — release it with {@link disposeStorageCache} when this caller's scope
+ * ends. `label` names the store in the shared pool's `stats()` (e.g. `control`, or the
+ * strand id); on a memo hit the first caller's label sticks, since a second cache over
+ * one backend is the failure that matters and a stale pool label is not.
  */
 export declare function wrapStorageWithCache(storage: IRawStorage, label: string): IRawStorage;
 /**
- * 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.
+ * Release this caller's claim on the cache wrapper {@link wrapStorageWithCache} returned.
+ * The wrapper is emptied, unregistered from the shared pool, and dropped from the memo
+ * only when the LAST holder releases — so a scope stopping never retires a cache another
+ * live scope is still reading through, and a still-held wrapper is never replaced by a
+ * competing second cache over the same backend.
+ *
+ * A wrapper with no live claim is left alone: that covers both a cache the embedder built
+ * itself (theirs to dispose) and a late second dispose of an already-retired wrapper,
+ * whose successor in the memo must not be dropped.
  *
- * 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.
+ * 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 declare function disposeStorageCache(storage: IRawStorage): Promise<void>;

package/dist/cached-storage.js

@@ -31,6 +31,19 @@
  * `MemoryRawStorage` is returned unwrapped on upstream's own guidance: the backend
  * is already in-memory, so the cache adds bookkeeping with nothing to save.
  *
+ * **{@link wrapStorageWithCache} and {@link disposeStorageCache} are a matched pair
+ * with a holder count between them.** Every wrap that hands back a cache this module
+ * created takes one claim on it; every dispose of that cache releases one. The cache
+ * is emptied, unregistered from the shared pool, and forgotten only when the LAST
+ * claim goes. That is what makes overlapping scopes safe: `CadreNodeConfig.storage.provider`
+ * may be a single `IRawStorage` shared by the control database and every workspace,
+ * and without a count the first scope to stop would retire the cache the others are
+ * still reading through — then the next scope to start, finding the memo empty, would
+ * build a SECOND cache over the same backend, and each would serve its own stale view
+ * (including remembered "this block does not exist" answers). It is also what lets
+ * `composeStrand` release its own claim unconditionally on `shutdown()` without having
+ * to guess whether it or cadre-core created the wrapper.
+ *
  * 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
@@ -39,10 +52,21 @@
  * `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.
+ * When a scope's runtime stops for good, it 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.
+ *
+ * NOTE: upstream ships an equivalent counted wrap of its own — `withReadCache`, which
+ * hands back a `ReadCacheLease` per caller and additionally dedupes by
+ * `getStoreIdentity()`, so two DISTINCT instances over one directory share one cache.
+ * This module keeps its own count instead, because its public surface releases by
+ * WRAPPER (`disposeStorageCache(storage)`) rather than by lease, and `withReadCache`
+ * returns no lease on its already-cached pass-through — which would leave
+ * `composeStrand`'s unconditional release unable to tell its own claim from cadre-core's.
+ * Adopting the lease API would mean changing that surface at all three call sites; worth
+ * doing if Sereus ever needs the identity-keyed dedupe (two `FileRawStorage` over one
+ * path), and not before.
  */
 // Imported from the `/rn` entry — the platform-neutral surface (no Node-only
 // transports) — because `composeStrand` reaches this module on the browser path
@@ -50,54 +74,83 @@
 // identity (the `instanceof` checks below) is unaffected on Node.
 import { CachedRawStorage, MemoryRawStorage } from '@optimystic/db-p2p/rn';
 const wraps = new WeakMap();
+const claims = new WeakMap();
 /**
- * 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.
+ * Count one more holder of `wrapped`, if this module created it. A cache built outside
+ * this module stays its creator's to release, so it is left uncounted and
+ * {@link disposeStorageCache} no-ops on it.
  */
-const inners = new WeakMap();
+function addHolder(wrapped) {
+    const claim = claims.get(wrapped);
+    if (claim) {
+        claim.holders += 1;
+    }
+}
 /**
- * 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).
+ * The cached view of `storage`, memoized per instance, with one holder claim taken for
+ * this caller — release it with {@link disposeStorageCache} when this caller's scope
+ * ends. `label` names the store in the shared pool's `stats()` (e.g. `control`, or the
+ * strand id); on a memo hit the first caller's label sticks, since a second cache over
+ * one backend is the failure that matters and a stale pool label is not.
  */
 export function wrapStorageWithCache(storage, label) {
-    if (storage instanceof MemoryRawStorage || storage instanceof CachedRawStorage) {
+    if (storage instanceof MemoryRawStorage) {
+        return storage;
+    }
+    if (storage instanceof CachedRawStorage) {
+        // Already the wrapper this module handed out: cadre-core wraps at its own seams
+        // and passes the wrapper down to `composeStrand`, which wraps again. Count the
+        // new holder rather than stacking a second cache over one backend.
+        // NOTE: a RETIRED wrapper (last holder already released) is also returned as-is,
+        // uncounted — the caller gets a dead cache with no error. No call site can reach
+        // that today: both retire sites drop their reference in the same block that
+        // releases. If a caller ever holds a wrapper across its own release, make this
+        // branch throw on an absent claim rather than hand back the corpse.
+        addHolder(storage);
         return storage;
     }
-    let wrapped = wraps.get(storage);
-    if (!wrapped) {
-        wrapped = new CachedRawStorage(storage, undefined, label);
-        wraps.set(storage, wrapped);
-        inners.set(wrapped, storage);
+    const memoized = wraps.get(storage);
+    if (memoized) {
+        addHolder(memoized);
+        return memoized;
     }
+    const wrapped = new CachedRawStorage(storage, undefined, label);
+    wraps.set(storage, wrapped);
+    claims.set(wrapped, { inner: storage, holders: 1 });
     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.
+ * Release this caller's claim on the cache wrapper {@link wrapStorageWithCache} returned.
+ * The wrapper is emptied, unregistered from the shared pool, and dropped from the memo
+ * only when the LAST holder releases — so a scope stopping never retires a cache another
+ * live scope is still reading through, and a still-held wrapper is never replaced by a
+ * competing second cache over the same backend.
+ *
+ * A wrapper with no live claim is left alone: that covers both a cache the embedder built
+ * itself (theirs to dispose) and a late second dispose of an already-retired wrapper,
+ * whose successor in the memo must not be dropped.
  *
- * 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.
+ * 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) {
     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);
-        }
+    const claim = claims.get(storage);
+    if (!claim) {
+        return;
+    }
+    // Decrement, and on zero retire the bookkeeping, all in this SYNCHRONOUS prefix —
+    // before the await below. A wrap of the same inner instance interleaved between the
+    // two would otherwise find a memo entry pointing at a dying cache.
+    claim.holders -= 1;
+    if (claim.holders > 0) {
+        return;
     }
+    claims.delete(storage);
+    wraps.delete(claim.inner);
     await storage.dispose();
 }
 //# sourceMappingURL=cached-storage.js.map

package/dist/cached-storage.js.map

@@ -1 +1 @@
-{"version":3,"file":"cached-storage.js","sourceRoot":"","sources":["../src/cached-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,6EAA6E;AAC7E,gFAAgF;AAChF,4EAA4E;AAC5E,kEAAkE;AAClE,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAoB,MAAM,uBAAuB,CAAC;AAE7F,MAAM,KAAK,GAAG,IAAI,OAAO,EAAiC,CAAC;AAE3D;;;;GAIG;AACH,MAAM,MAAM,GAAG,IAAI,OAAO,EAAiC,CAAC;AAE5D;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAoB,EAAE,KAAa;IACvE,IAAI,OAAO,YAAY,gBAAgB,IAAI,OAAO,YAAY,gBAAgB,EAAE,CAAC;QAChF,OAAO,OAAO,CAAC;IAChB,CAAC;IACD,IAAI,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACjC,IAAI,CAAC,OAAO,EAAE,CAAC;QACd,OAAO,GAAG,IAAI,gBAAgB,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;QAC1D,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAC5B,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,OAAO,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,OAAoB;IAC7D,IAAI,CAAC,CAAC,OAAO,YAAY,gBAAgB,CAAC,EAAE,CAAC;QAC5C,OAAO;IACR,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAClC,IAAI,KAAK,EAAE,CAAC;QACX,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACvB,6EAA6E;QAC7E,2EAA2E;QAC3E,IAAI,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,OAAO,EAAE,CAAC;YAClC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC;IACF,CAAC;IACD,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;AACzB,CAAC"}
+{"version":3,"file":"cached-storage.js","sourceRoot":"","sources":["../src/cached-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AAEH,6EAA6E;AAC7E,gFAAgF;AAChF,4EAA4E;AAC5E,kEAAkE;AAClE,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAoB,MAAM,uBAAuB,CAAC;AAE7F,MAAM,KAAK,GAAG,IAAI,OAAO,EAAiC,CAAC;AAmB3D,MAAM,MAAM,GAAG,IAAI,OAAO,EAAgC,CAAC;AAE3D;;;;GAIG;AACH,SAAS,SAAS,CAAC,OAAyB;IAC3C,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAClC,IAAI,KAAK,EAAE,CAAC;QACX,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;IACpB,CAAC;AACF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAoB,EAAE,KAAa;IACvE,IAAI,OAAO,YAAY,gBAAgB,EAAE,CAAC;QACzC,OAAO,OAAO,CAAC;IAChB,CAAC;IACD,IAAI,OAAO,YAAY,gBAAgB,EAAE,CAAC;QACzC,gFAAgF;QAChF,+EAA+E;QAC/E,mEAAmE;QACnE,iFAAiF;QACjF,iFAAiF;QACjF,4EAA4E;QAC5E,+EAA+E;QAC/E,oEAAoE;QACpE,SAAS,CAAC,OAAO,CAAC,CAAC;QACnB,OAAO,OAAO,CAAC;IAChB,CAAC;IACD,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACpC,IAAI,QAAQ,EAAE,CAAC;QACd,SAAS,CAAC,QAAQ,CAAC,CAAC;QACpB,OAAO,QAAQ,CAAC;IACjB,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,gBAAgB,CAAC,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;IAChE,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC5B,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC;IACpD,OAAO,OAAO,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,OAAoB;IAC7D,IAAI,CAAC,CAAC,OAAO,YAAY,gBAAgB,CAAC,EAAE,CAAC;QAC5C,OAAO;IACR,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAClC,IAAI,CAAC,KAAK,EAAE,CAAC;QACZ,OAAO;IACR,CAAC;IACD,kFAAkF;IAClF,oFAAoF;IACpF,mEAAmE;IACnE,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;IACnB,IAAI,KAAK,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO;IACR,CAAC;IACD,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACvB,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC1B,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;AACzB,CAAC"}

package/dist/cluster-size.d.ts

@@ -1,3 +1,4 @@
+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
@@ -7,7 +8,12 @@ export declare 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.
+ * on every member of the party. Cohort width alone only delivers that for blocks written
+ * while the members were serving the network: a block committed while the writer was
+ * alone (the founder's genesis above all — collection headers are written once and never
+ * revised) has a cohort of one, and it reaches later joiners through cadre-core's
+ * peer-join block catch-up (`peer-join-backfill.ts`, membership-gated on the control
+ * network), not through this breadth.
  *
  * **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
@@ -90,6 +96,20 @@ export declare const CONTROL_REPLICATION_BREADTH = 16;
  * 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`.
  *
+ * **`assumedClusterSize` is now the ADMISSION yardstick.** Since Optimystic grew
+ * `repairCorroborationClusterSize` (see {@link controlClusterPolicy}), the repair corroboration
+ * floor prefers that separate declaration and reads this field only when nothing was declared —
+ * the unknown-machine-count path, where the paragraph above still describes what it does. So on
+ * every path where the count IS known, the 2 here governs one consumer: the membership admission
+ * gate's low-confidence fallback path. Leaving
+ * it at 2 is deliberate and must NOT be "fixed" to match the repair yardstick. Raising it would
+ * make the gate demand `ceil(0.75 x N)` DECLARED peers before it admits a coordinator's peer
+ * set on that path, and a Cadre party is phones and laptops: it cannot promise that three
+ * quarters of its enrolled machines are awake at any moment, so a party of eight with three
+ * awake would stop transacting entirely. The repair yardstick has no such cost (it gates only
+ * whether this node believes a repair answer), which is exactly why the two are now separate
+ * numbers rather than one.
+ *
  * 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`.
@@ -125,6 +145,13 @@ export declare const CONTROL_CLUSTER_POLICY: Readonly<{
  * 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).
  *
+ * **Exercised at four machines** by `integration-tests`'
+ * `scenarios/strand-two-party-two-machine.integration.ts`, the only scenario that runs a
+ * strand at this breadth. It shows a write committing while one of the four machines is off.
+ * It does NOT distinguish that from a commit on a cohort downsized to the three live holders
+ * (`allowDownsize` in {@link STRAND_CLUSTER_POLICY}), so the table row above remains reasoned
+ * arithmetic with an end-to-end existence proof under it, not a measurement of cohort width.
+ *
  * **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
@@ -133,12 +160,24 @@ export declare const CONTROL_CLUSTER_POLICY: Readonly<{
  * 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.
+ * voter is a third machine **or a declaration that there are three** — not a wider target.
+ * `corroboratorCapacity` takes the max of the cohort peers actually present and the declared
+ * repair yardstick, so raising *this* number (the replication breadth) does nothing: the
+ * yardstick is a separate declaration, and **a strand node makes no such declaration today**.
+ * The control network derives one from the party's enrolled machines
+ * ({@link controlClusterPolicy}), which is exact there because every enrolled machine runs the
+ * control node. A strand has no equivalent count: it launches only on machines whose embedder
+ * registered its sApp config, and reusing the party count over-declares — which is worse than
+ * declaring nothing, because at a yardstick of three or more the corroboration floor is pinned
+ * at two peers and a strand that can field only one could then never repair at all. So every
+ * strand runs {@link STRAND_CLUSTER_POLICY} unchanged and takes the single-voter exposure
+ * whenever its cohort view shrinks to one peer. The underlying Optimystic behaviour is unfixed
+ * (`backlog/debt-read-repair-single-voter-corroboration`) and the per-strand serving count that
+ * would let a strand declare honestly is `backlog/feat-strand-yardstick-from-serving-machines`
+ * — its seam ({@link strandClusterPolicy}'s `servingMachines`, threaded through
+ * `StartStrandConfig.servingMachines`) is already in place and fed by nothing. Raising this
+ * number does not buy the way out; a machine, or an honest declaration of the machines actually
+ * serving the strand, 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
@@ -205,6 +244,17 @@ export declare const DEFAULT_STRAND_CLUSTER_SIZE = 4;
  * 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").
  *
+ * `assumedClusterSize` also carries the ADMISSION yardstick, and on the strand path it carries
+ * BOTH jobs today. Optimystic prefers a separately declared
+ * `repairCorroborationClusterSize` for the repair floor and falls back to this field only when
+ * nothing was declared — which, for a strand, is always: no per-strand serving count exists yet,
+ * so {@link strandClusterPolicy} declares nothing and the 2 here governs the repair floor
+ * exactly as the paragraph above describes, alongside the membership admission gate's
+ * low-confidence fallback. Do not raise it if a strand yardstick ever does get declared
+ * (`backlog/feat-strand-yardstick-from-serving-machines`): a strand shared between phones cannot
+ * promise that `ceil(0.75 x N)` of its machines are awake, and the admission gate would refuse
+ * its writes. Same reason and same warning as {@link CONTROL_CLUSTER_POLICY}'s.
+ *
  * The `satisfies` is load-bearing for the same reason as {@link CONTROL_CLUSTER_POLICY}'s.
  */
 export declare const STRAND_CLUSTER_POLICY: Readonly<{
@@ -229,3 +279,121 @@ export declare const STRAND_CLUSTER_POLICY: Readonly<{
  * this comment described. See `docs/architecture.md` → "Replication cluster size".
  */
 export declare function resolveStrandClusterSize(configured?: number): number;
+/**
+ * The repair yardstick to declare for a network, from the machines that SERVE that network and
+ * the breadth it replicates to.
+ *
+ * ## What this number does
+ *
+ * Optimystic's block repair (read-repair and reconcile) asks a block's cohort for the newest
+ * revision and trusts an answer only when enough independent peers agree on it. "Enough" is
+ * measured against a **declared** number rather than the peers currently visible — deliberately,
+ * because the visible set comes from unauthenticated routing, and a partition (or an attacker
+ * with routing influence) can shrink it. `clusterPolicy.repairCorroborationClusterSize` is that
+ * declaration; it moves the repair yardstick ALONE, leaving
+ * {@link CONTROL_CLUSTER_POLICY}'s / {@link STRAND_CLUSTER_POLICY}'s `assumedClusterSize` — the
+ * membership admission gate's yardstick — untouched. Optimystic resolves
+ * `repairCorroborationClusterSize -> assumedClusterSize -> clusterSize`, and a value that is not
+ * a positive integer falls THROUGH to the next term rather than being clamped, which is why the
+ * builders below refuse to pass a degenerate count at all.
+ *
+ * ## The arithmetic, and why the formula is what it is
+ *
+ * Three consumers read the resolved yardstick `N`. With `p` = cohort peers currently visible
+ * (self excluded) and Optimystic's `CORROBORATION_FLOOR` = 2:
+ *
+ * - **Repair corroboration floor** (`corroboratorCapacity` / `quorumSize` in
+ *   `db-p2p/src/cluster/quorum-restore.ts`): capacity is `max(p, N - 1)` and the floor is
+ *   `max(1, min(2, capacity))`. So `N = 1` and `N = 2` behave IDENTICALLY at every `p` — both
+ *   leave the floor at a single voter whenever `p <= 1`. `N >= 3` pins the floor at two
+ *   corroborators unconditionally, including when the view has shrunk to one peer. That is the
+ *   entire point of declaring. `N` above 3 raises nothing further (the `min(2, ...)` caps it), so
+ *   a larger declaration buys only honesty, never more repair.
+ * - **Commit freshness window** (`CoordinatorRepo.commitQuorumRulesOutRivals`): `fullCohortSize`
+ *   is `max(observed cohort, N)`, and a local commit arms the lazy read-repair window only when
+ *   `approvals > fullCohortSize / 2`. Here a larger `N` is NOT free — see the NOTE below.
+ * - The `repair-fault-tolerance` startup advisory — log text only.
+ *
+ * Hence `max(MIN_CLUSTER_SIZE, min(servingMachines, replicationBreadth))`, two clamps each for
+ * a stated reason:
+ *
+ * - **Capped at the replication breadth**, because a block only ever lives on
+ *   `min(breadth, machines serving)` machines. A party of eight running strands at
+ *   {@link DEFAULT_STRAND_CLUSTER_SIZE} has a cohort of four; declaring eight would make
+ *   `approvals > 4` unsatisfiable (a super-majority of four is three), so the freshness window
+ *   would never arm for any strand commit, forever — and buy nothing on repair, whose floor is
+ *   already at its cap at four. Declare the machines that can hold the block, not the machines
+ *   that exist.
+ * - **Floored at {@link MIN_CLUSTER_SIZE}**, so this can only ever RAISE the declared number
+ *   relative to the un-derived constants. A node that authorizes nobody is a genuine
+ *   founder-alone party, but it is equally a freshly seeded node whose membership rows have not
+ *   replicated yet, or one whose trusted-owner anchor is empty — and this node cannot tell those
+ *   apart. Declaring 1 is safety-neutral for repair (identical to 2 at every `p`, per the table
+ *   above) but it WOULD let a solo commit arm the freshness window, which is wrong if the "solo"
+ *   reading came from stale local records. Lifting that floor for a node that can prove it is
+ *   genuinely alone is separate work: `backlog/feat-solo-node-arms-its-own-freshness-window`.
+ *
+ * The yardstick is per-node and protects only that node's own reads — no node refuses another
+ * anything over it — so two members disagreeing (one has replicated a new `CadrePeer` row, one
+ * has not) is harmless by construction, not a race to close.
+ *
+ * ## The contract: callers pass machines that SERVE this network, or nothing at all
+ *
+ * Over-declaring is not merely wasteful, it is unsafe in the availability direction: at
+ * `N >= 3` the corroboration floor is pinned at two peers, so a cohort that can only ever
+ * field one peer can never repair at all (`cluster-fetch:no-quorum`), where a declaration of
+ * 2 would have let its single peer answer. So the number a caller passes must be the machines
+ * that actually serve the network in question — never a broader population that merely bounds
+ * it from above, and never a guess. A caller with no trustworthy count passes nothing, which
+ * the builders below turn into "declare no yardstick at all".
+ *
+ * The CONTROL network satisfies this from the party's enrolled machines, because every enrolled
+ * machine runs the control node by construction: there, enrolled IS serving
+ * ({@link controlClusterPolicy}, fed by cadre-core's `enrolled-machine-store.ts`). A STRAND does
+ * not — it launches only on machines whose embedder registered its sApp config
+ * (`CadreNode.addStrand`), so a closed strand shared by two machines of a three-machine party is
+ * served by two, and declaring three would be exactly the unsafe over-declaration above. No
+ * authenticated per-strand serving count exists yet, so strand nodes declare NOTHING and run the
+ * frozen {@link STRAND_CLUSTER_POLICY} — keeping the known, upstream-tracked single-voter
+ * exposure (`backlog/debt-read-repair-single-voter-corroboration`) rather than risking the
+ * cannot-repair-at-all failure. Building that count:
+ * `backlog/feat-strand-yardstick-from-serving-machines`.
+ *
+ * Both arguments must be positive integers; the builders below sanitize before calling, and
+ * a degenerate value here propagates (`NaN` in, `NaN` out) rather than being clamped.
+ *
+ * NOTE: on a party of three or more machines where fewer than half are awake, a commit reaches a
+ * downsized cohort and no longer arms the freshness window, so each such block's next read costs
+ * one cohort consult per read-repair window instead of trusting the local commit. That is the
+ * correct reading of the honest number — a commit that reached two of five machines genuinely
+ * does not rule out a rival quorum, and arming it today is a consequence of under-declaring — and
+ * the cost is bounded at one consult per block per window by the read path's solo-self-skip exit.
+ * NOT measured under load. If a large, mostly-hibernating party's read path ever shows up as
+ * slow, this is the first thing to look at.
+ */
+export declare function resolveRepairYardstick(servingMachines: number, replicationBreadth: number): number;
+/**
+ * {@link CONTROL_CLUSTER_POLICY} with the repair yardstick declared from `enrolledMachines`
+ * (see {@link resolveRepairYardstick}); the frozen base object ITSELF when the count is unknown,
+ * so the cold path is provably today's behaviour and identity assertions keep holding.
+ *
+ * The parameter keeps the name `enrolledMachines`, unlike {@link strandClusterPolicy}'s, because
+ * for the CONTROL network the two quantities are one and the same by construction: every
+ * enrolled machine runs the control node, so the machines enrolled in the party ARE the machines
+ * serving this network.
+ */
+export declare function controlClusterPolicy(enrolledMachines?: number): NonNullable<NodeOptions['clusterPolicy']>;
+/**
+ * {@link STRAND_CLUSTER_POLICY} with the repair yardstick declared from `servingMachines` — the
+ * machines that serve THIS strand — and this strand's own `clusterSize` (already resolved by
+ * {@link resolveStrandClusterSize}, so it is at least {@link MIN_CLUSTER_SIZE} and the formula's
+ * two clamps can never cross); the frozen base object ITSELF when the count is unknown.
+ *
+ * **The unknown path is the production path today.** No authenticated per-strand serving count
+ * exists, and the party's enrolled-machine count is emphatically not one (see
+ * {@link resolveRepairYardstick}'s contract section), so cadre-core passes nothing and every
+ * strand node runs the frozen constant. The parameter and its threading through
+ * `StartStrandConfig.servingMachines` stay in place as the seam that
+ * `backlog/feat-strand-yardstick-from-serving-machines` plugs a real count into.
+ */
+export declare function strandClusterPolicy(clusterSize: number, servingMachines?: number): NonNullable<NodeOptions['clusterPolicy']>;