@serfab/cadre-core 0.9.0 → 0.11.0

package/dist/types.d.ts

@@ -1,16 +1,28 @@
 import type { ConnectionGater, Libp2p, PeerId, PrivateKey } from '@libp2p/interface';
 import type { IRawStorage, Libp2pTransports } from '@optimystic/db-p2p';
-import type { IRepo } from '@optimystic/db-core';
+import type { IPeerNetwork, IRepo } from '@optimystic/db-core';
+import type { StrandBackfillConfig } from './strand-backfill.js';
 import type { StrandDatabase } from './strand-database.js';
 import type { SeedTrustPolicy } from './seed-trust-policy.js';
 import type { KeyStore, KeyId } from './key-store.js';
+import type { TrustedOwnerStore, TrustSource } from './trusted-owner-store.js';
+import type { BootstrapPeerStore } from './bootstrap-peer-store.js';
 import type { PushNotifier } from './push-notifier.js';
+import type { RevocableTable } from './control-authorization.js';
 /**
  * Extended Libp2p node with the coordinatedRepo attached by db-p2p's
  * createLibp2pNode after node creation (not surfaced on the base Libp2p type).
  */
 export interface Libp2pNodeWithRepo extends Libp2p {
     coordinatedRepo: IRepo;
+    /**
+     * The node's key-addressed peer network, attached by db-p2p's factory alongside
+     * `coordinatedRepo` (`libp2p-node-base.ts`). Optional deliberately: the base
+     * factory always assigns it, but it is not part of the upstream node type, so
+     * declaring it required would be a claim this repo cannot enforce. The strand
+     * backfill (`strand-backfill.ts`) logs once and stays inert when it is absent.
+     */
+    keyNetwork?: IPeerNetwork;
 }
 /**
  * Node profile determines storage participation
@@ -70,8 +82,28 @@ export interface HibernationTimeouts {
  */
 export declare const HIBERNATION_TIMEOUTS: Record<LatencyHint, HibernationTimeouts>;
 /**
- * Storage provider type - either an IRawStorage instance or a factory function.
+ * Storage provider - either an `IRawStorage` instance or a factory function.
  * Factory functions are useful for creating strand-specific storage instances.
+ *
+ * **Called once per scope per runtime lifetime.** The scopes are the literal string
+ * `'control'` (once per `CadreNode.start()`) and each strand id (once per
+ * `startStrand`). Hibernation — `quiesceStrand` then `resumeStrand` — reuses the
+ * store already resolved for that strand and does NOT re-enter this callback.
+ *
+ * It IS re-entered for a scope after that scope's runtime has stopped
+ * (`stopStrand`, or a `stop()` then `start()` cycle on one `CadreNode`), so it must
+ * be able to hand back a store over the same durable backend a second time. A
+ * factory may mint a fresh object per call; it must not *need* to.
+ *
+ * cadre-core disposes only its own cache wrapper — it never closes the store you
+ * returned. Closing the underlying handle stays the embedder's job.
+ *
+ * **Prefer the factory form for any persistent backend.** One instance handed to
+ * every scope also shares ONE cache wrapper (`wrapStorageWithCache` memoizes per
+ * inner instance), and no scope solely owns it — so the first scope to stop retires
+ * the wrapper the still-running scopes are reading through. See
+ * `tickets/backlog/debt-storage-cache-wrap-unrefcounted.md`; an in-memory store is
+ * unaffected, since it is never wrapped.
  */
 export type RawStorageProvider = IRawStorage | ((strandId: string) => IRawStorage);
 /**
@@ -80,6 +112,7 @@ export type RawStorageProvider = IRawStorage | ((strandId: string) => IRawStorag
 export interface StorageConfig {
     /**
      * Storage provider - either an IRawStorage instance or a factory function.
+     * See {@link RawStorageProvider} for how often cadre-core calls it.
      *
      * For Node.js environments, use FileRawStorage from @optimystic/db-p2p-storage-fs:
      * ```typescript
@@ -89,8 +122,9 @@ export interface StorageConfig {
      *
      * For React Native, use the appropriate storage from @optimystic/db-p2p-storage-rn:
      * ```typescript
-     * import { RNRawStorage } from '@optimystic/db-p2p-storage-rn';
-     * storage: { provider: (strandId) => new RNRawStorage(strandId) }
+     * import { LevelDBRawStorage } from '@optimystic/db-p2p-storage-rn';
+     * // `db` is an open LevelDB handle (see `openOptimysticRNDb` over `rn-leveldb`)
+     * storage: { provider: (strandId) => new LevelDBRawStorage(openDb(`sereus-${strandId}`)) }
      * ```
      *
      * For in-memory storage (testing):
@@ -107,7 +141,47 @@ export interface StorageConfig {
  */
 export interface NetworkConfig {
     listenAddrs?: string[];
+    /**
+     * Addresses to advertise to peers instead of `listenAddrs` — for a node behind
+     * NAT or a reverse proxy that is reachable at a different address than it binds
+     * (e.g. `mynode.example.com:4001` in front of a `0.0.0.0:4001` listener).
+     *
+     * Accepted (settable in `cadre.yaml`, via `CADRE_ANNOUNCE_ADDRS`, and through the
+     * Docker entrypoint) but **not yet applied**: libp2p only takes announce addresses
+     * at construction (`addresses.announce` / `addresses.appendAnnounce`), and
+     * `@optimystic/db-p2p`'s `NodeOptions` has no field for either — there is nothing
+     * in this repo to wire this into. `CadreNode.start()` warns when this is set,
+     * rather than pretending it works. Unblocked by the `announce-addrs-option`
+     * request filed against `@optimystic/db-p2p`; wiring lands here once this repo's
+     * dependency range moves to a version carrying it.
+     *
+     * Use {@link relayAddrs} for reachability behind NAT today (a reserved relay slot
+     * gives the node a real dialable circuit address), or `inviteAddressResolver` to
+     * substitute a reachable address into invite payloads specifically — neither
+     * changes what this node advertises on the wire, but both cover the operator need
+     * this field cannot yet.
+     */
     announceAddrs?: string[];
+    /**
+     * Circuit-relay servers this node reserves a slot on, so peers can reach it
+     * from behind NAT. Each entry is the relay's DIRECT dial multiaddr ending in
+     * its peerId — `/dns4/relay.example.com/tcp/4001/p2p/12D3KooW…` — with no
+     * `/p2p-circuit` suffix (one is appended for you; an entry that already has
+     * one is passed through unchanged).
+     *
+     * This is sugar for a circuit entry in {@link listenAddrs}: `relay-addrs.ts`
+     * resolves the two into one listen list, and listening on a relay's circuit
+     * addr is what makes libp2p dial it and hold the reservation. A relay named
+     * here therefore also becomes a delegate-announce target, so this node's
+     * strand nodes may reserve on it too (see `delegate-admission.ts`).
+     *
+     * Setting this gives the node a listener even when `listenAddrs` is `[]` —
+     * that is the point of naming a relay, but note that React Native hosts
+     * (`reference-app-rn`'s `cadre-phone.ts`) deliberately do NOT listen, and
+     * must not acquire a listener by accident.
+     *
+     * A malformed entry throws at node start rather than being silently dropped.
+     */
     relayAddrs?: string[];
     /**
      * Enable circuit relay server - allows this node to relay connections for other peers.
@@ -147,15 +221,22 @@ export interface NetworkConfig {
      * Playwright e2e, RN simulators) supply a permissive gater here — e.g.
      * `{ denyDialMultiaddr: () => false }`. See `@optimystic/db-p2p`'s
      * `libp2p-node-base` for the underlying option.
+     *
+     * On the CONTROL node this gater is composed with the built-in membership
+     * admission gate (`membership-connection-gater.ts`): every hook supplied here
+     * is honored unchanged, and on inbound encrypted connections a deny from
+     * either this gater or the membership policy denies. Strand cohort nodes
+     * receive this gater as-is (their peers are legitimately cross-party).
      */
     connectionGater?: ConnectionGater;
     /**
      * Tuning for the proactive control-cohort dial routine
      * ({@link CadreNode.reconcileControlCohort}), which keeps a party's control
      * nodes connected so the `CadreControl` collections form a replicating cohort.
-     * Both fields are optional; omit for the defaults
+     * Every field is optional; omit for the defaults
      * ({@link DEFAULT_CONTROL_COHORT_TARGET_DEGREE} /
-     * {@link DEFAULT_CONTROL_COHORT_RECONCILE_MS}).
+     * {@link DEFAULT_CONTROL_COHORT_RECONCILE_MS} /
+     * {@link DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS} / `STRAND_PEER_ADDR_REFRESH_MS`).
      */
     controlCohort?: {
         /**
@@ -169,6 +250,20 @@ export interface NetworkConfig {
          * {@link DEFAULT_CONTROL_COHORT_RECONCILE_MS}.
          */
         reconcileMs?: number;
+        /**
+         * Budget for ONE sibling's proactive dial, in ms. Bounds a pass at
+         * (dialed siblings) × this, instead of leaving it to each address's own
+         * libp2p attempt timeout multiplied by address fan-out and relay hops.
+         * Defaults to {@link DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS}.
+         */
+        dialTimeoutMs?: number;
+        /**
+         * How often each running strand re-resolves its siblings' strand-network
+         * addresses into its own libp2p address book — a step of the reconcile pass,
+         * on its own much longer throttle. Defaults to `STRAND_PEER_ADDR_REFRESH_MS`
+         * (10 min); must stay well under the peerStore's one-hour address expiry.
+         */
+        strandAddrRefreshMs?: number;
     };
 }
 /**
@@ -201,6 +296,19 @@ export interface ControlNetworkConfig {
     /** Optional path to the control schema file (defaults to bundled schema) */
     schemaPath?: string;
 }
+/**
+ * Replication-breadth constants, both networks' cluster policies, and the strand
+ * resolver, re-exported so cadre embedders, the SQL plugin and the integration
+ * harness share one definition. Defined in `@serfab/quereus-plugin-sereus`
+ * because that package also creates libp2p nodes and cannot depend on this one.
+ * The control network's breadth is fixed ({@link CONTROL_REPLICATION_BREADTH},
+ * not configurable) and so is its consensus policy ({@link CONTROL_CLUSTER_POLICY}
+ * — notably the super-majority threshold, which it leaves at Optimystic's default
+ * by omission); the strand breadth defaults to
+ * {@link CadreNodeConfig.strandClusterSize} while its policy is the fixed
+ * {@link STRAND_CLUSTER_POLICY}.
+ */
+export { MIN_CLUSTER_SIZE, CONTROL_REPLICATION_BREADTH, CONTROL_CLUSTER_POLICY, DEFAULT_STRAND_CLUSTER_SIZE, STRAND_CLUSTER_POLICY, resolveStrandClusterSize } from '@serfab/quereus-plugin-sereus';
 /**
  * Main configuration for a CadreNode
  */
@@ -237,6 +345,41 @@ export interface CadreNodeConfig {
     storage?: StorageConfig;
     /** Network configuration */
     network?: NetworkConfig;
+    /**
+     * Number of nodes Optimystic is told a **strand** network's replication cluster
+     * should have, for every strand this node starts. The control network is not
+     * configurable — it always replicates to {@link CONTROL_REPLICATION_BREADTH}
+     * nodes, which is above any party's node count, because every member reads the
+     * whole control database and a member that misses a write may never learn the
+     * fact (see that constant for the full reasoning).
+     *
+     * Every node on the same strand should use the same value: the number bounds the
+     * cohort a member independently derives, and Optimystic's cluster-membership gate
+     * can reject a coordinator's smaller declared set as a downsize against a larger
+     * derived view.
+     *
+     * Frozen when the strand's libp2p node is created; a change takes effect on
+     * restart, not when cadre membership grows. Defaults to
+     * {@link DEFAULT_STRAND_CLUSTER_SIZE} (4 — the smallest breadth whose 0.75
+     * super-majority still commits with one holder offline); anything below
+     * {@link MIN_CLUSTER_SIZE} is rejected before a node is created. The cost of a
+     * small value is replication breadth and reliance on read repair, not commit
+     * correctness — but at 2 that read repair cannot converge, because a lone
+     * corroborator's stale answer is accepted as the cluster's truth.
+     */
+    strandClusterSize?: number;
+    /**
+     * Tuning for the strand peer-join block catch-up (see `strand-backfill.ts`):
+     * when a strand's libp2p node connects to a peer this runtime has not yet
+     * caught up, every block in the strand's own raw store is pushed to that peer,
+     * so a machine that joined the strand after blocks were committed still ends
+     * up physically holding them. Applies to every strand this node starts;
+     * strand-only — the control network has its own row-level re-issue queue
+     * (`drainPendingControlReplication`). Omit for the defaults
+     * (`DEFAULT_STRAND_BACKFILL`); `{ enabled: false }` restores the
+     * no-backfill behaviour.
+     */
+    strandBackfill?: StrandBackfillConfig;
     /** Hibernation configuration */
     hibernation?: HibernationConfig;
     /** Polling interval for strand watcher in ms (default: 5000) */
@@ -253,13 +396,73 @@ export interface CadreNodeConfig {
      * into every SeedBootstrapService this node constructs (owner, receive-only
      * listener, and the temp service used by applySeed when no service exists), and
      * used as the service-level default the libp2p seed-protocol handler relies on
-     * (that path has no per-call override seam). Defaults to dbAnchoredTrustPolicy()
-     * inside SeedBootstrapService when unset — a cold-start node then rejects every
-     * seed. A per-call `applySeed(seed, { trustPolicy })` override still wins over
-     * this default for callers that hold out-of-band material (e.g. a pinned key
-     * from a CadreInvite).
+     * (that path has no per-call override seam). Defaults to anchoredTrustPolicy()
+     * inside SeedBootstrapService when unset — a node whose node-local trusted-owner
+     * anchor was never seeded then rejects every seed. A per-call
+     * `applySeed(seed, { trustPolicy })` override still wins over this default for
+     * callers that hold out-of-band material (e.g. a pinned key from a CadreInvite).
      */
     seedTrustPolicy?: SeedTrustPolicy;
+    /**
+     * Node-local trusted-owner anchor (see `trusted-owner-store.ts`): the
+     * NON-replicated, per-party record of owner keys established out of band —
+     * the anchor membership/seed trust can rest on, since the replicated
+     * `OwnerKey` table can be polluted by a stranger's self-genesis. Absent ⇒ an
+     * in-memory store is created at start() (ephemeral: anchored trust does not
+     * survive the process).
+     */
+    trustedOwners?: {
+        /**
+         * Injected store instance — e.g. a `FileTrustedOwnerStore` from the
+         * Node-only subpath `@serfab/cadre-core/trusted-owner-store-file`,
+         * persisted in the node's state directory (same injection/isolation pattern
+         * as {@link keyStore}). Its `partyId` must match `controlNetwork.partyId`;
+         * start() fails closed on a mismatch.
+         */
+        store?: TrustedOwnerStore;
+        /**
+         * Owner keys (base64url ed25519) established out of band and seeded into
+         * the store during start(): operator pins (e.g. cadre-cli
+         * `--pin-owner-key` / `CADRE_OWNER_KEYS`) or a `CadreInvite.ownerKeys`
+         * already known at config time. Seeding is idempotent across restarts.
+         */
+        pinnedKeys?: string[];
+        /**
+         * Provenance recorded for {@link pinnedKeys}. Default: 'operator'.
+         * ('genesis' is reserved for the node's own founding key, seeded
+         * internally by `initializeSeedBootstrap`.)
+         */
+        pinnedSource?: Exclude<TrustSource, 'genesis'>;
+    };
+    /**
+     * Node-local cold-start bootstrap-peer store (see `bootstrap-peer-store.ts`):
+     * the owner addresses an applied seed nominated, kept so
+     * `reconcileControlCohort`'s cold-start branch can keep retrying a node that
+     * was seeded but never managed to connect. Sibling of {@link trustedOwners} —
+     * same NON-replicated, per-party, injected-backend shape — but nothing here is
+     * trust-bearing: these are dial hints only, and every address is re-bound to
+     * its peer id before the dial. Absent ⇒ an in-memory store is created at
+     * start() (ephemeral: the retry set does not survive the process, and such a
+     * node is stranded permanently if it restarts before connecting).
+     *
+     * The Node CLI, the browser, and React Native all inject a durable backend
+     * today; only NativeScript stays ephemeral, tracked by the
+     * `ns-durable-node-local-stores` ticket (which covers the same gap for
+     * {@link trustedOwners}). A new platform needs no new store class: supply a
+     * `DurableSlot` for the platform's storage and inject
+     * `PersistentBootstrapPeerStore.open(slot, partyId)` /
+     * `PersistentTrustedOwnerStore.open(slot, partyId)`.
+     */
+    bootstrapPeers?: {
+        /**
+         * Injected store instance — e.g. a `FileBootstrapPeerStore` from the
+         * Node-only subpath `@serfab/cadre-core/bootstrap-peer-store-file`, persisted
+         * in the node's state directory (same injection/isolation pattern as
+         * {@link keyStore} / {@link trustedOwners}). Its `partyId` must match
+         * `controlNetwork.partyId`; start() fails closed on a mismatch.
+         */
+        store?: BootstrapPeerStore;
+    };
     /**
      * Platform push-delivery for suspended mobile peers. When present, the node's
      * server fan-out can deliver strand-wake data messages over the platform push
@@ -375,20 +578,6 @@ export interface SAppConfig {
     /** Latency hint for hibernation behavior (optional, defaults to config) */
     latencyHint?: LatencyHint;
 }
-/**
- * Lifecycle mode for a strand.
- *
- * - `bootstrap`: newly created locally; no remote peers exist for this strand yet.
- *   Schema apply and data operations route through a local (non-network) transactor
- *   so a solo node can fully initialize without any peer round trips.
- * - `networked`: strand has (or is expected to have) remote peers. Operations route
- *   through the network transactor.
- *
- * Transition `bootstrap -> networked` happens at first remote-peer enrollment for
- * the strand; because the transactor is fixed at plugin registration time, the
- * transition requires stopping and restarting the strand.
- */
-export type StrandMode = 'bootstrap' | 'networked';
 /**
  * Full strand configuration when adding a strand via the API
  */
@@ -397,13 +586,6 @@ export interface StrandConfig {
     strandRow: StrandRow;
     /** sApp configuration provided by the hosting application */
     sAppConfig: SAppConfig;
-    /**
-     * Lifecycle mode for this strand instance. When omitted, CadreNode infers the
-     * mode from cohort membership (`bootstrap` for a solo/first node with no other
-     * `CadrePeer` rows, `networked` once the cohort has other members). An explicit
-     * value always wins.
-     */
-    mode?: StrandMode;
     /**
      * Whether THIS node is the strand's founder — the party that provisioned and
      * published the strand (the responder in formation, the creator in host/solo
@@ -473,15 +655,6 @@ export interface FormStrandResult {
      */
     memberPrivateKey?: string;
 }
-/**
- * Result of validating a strand formation request
- */
-export interface ValidateFormationResult {
-    /** Public key for validating this formation */
-    validationKey: string;
-    /** Signature over the formation approval */
-    validationSignature: string;
-}
 /**
  * Disclosure object provided during strand formation.
  * Contains identity and context information from the initiator.
@@ -589,13 +762,57 @@ export interface PeerAddressRecord {
     /** ed25519 self-signature over the signed payload, base64url. */
     sig: string;
 }
+/**
+ * One `CadreControl.CadrePeer` row as read by `ControlDatabase.queryCadrePeers`:
+ * the addressing columns plus the persisted membership voucher.
+ *
+ * The voucher triple (`stampId`, `vouchOwner`, `vouchSig`) is what
+ * {@link CadreNode.listAuthorizedMembers} re-checks against the node-local
+ * trusted-owner anchor — it is null on a row written before the voucher columns
+ * existed, and all three must be present for the row to be authorizable. Named
+ * (rather than restated inline at each read site) so a future column addition
+ * cannot reach the query without the predicate seeing it.
+ */
+export interface CadrePeerRow {
+    /** libp2p peer ID (base58btc) — the row key. */
+    peerId: string;
+    /** Comma-joined dialable multiaddrs as stored, or null when unpublished. */
+    multiaddr: string | null;
+    /** Single-use anti-replay nonce the voucher signature is bound to. */
+    stampId: string | null;
+    /** ed25519 public key (base64url) of the owner that vouched this row. */
+    vouchOwner: string | null;
+    /** That owner's signature over `digest('CadreControl.CadrePeer', 'vouch', peerId, stampId)`, base64url. */
+    vouchSig: string | null;
+}
+/** The voucher-bearing subset of a {@link CadrePeerRow} — what the authorized-membership predicate reads. */
+export type CadrePeerVoucherFields = Pick<CadrePeerRow, 'peerId' | 'stampId' | 'vouchOwner' | 'vouchSig'>;
+/**
+ * One `CadreControl.Revocation` tombstone as read by
+ * `ControlDatabase.queryRevocations`: the identity triple plus the `ReissuedAt`
+ * counter an owner bumps (`ControlDatabase.reissueRevocations`) to re-write — and
+ * therefore re-broadcast — a tombstone that committed while the node was alone.
+ */
+export interface RevocationRow {
+    /** Which guarded table's stamp was retired. */
+    tableName: RevocableTable;
+    /** Primary key of the removed row (peer id / key / strand id). */
+    rowKey: string;
+    /** The retired single-use nonce — the tombstone's identity. */
+    stampId: string;
+    /** Monotonic re-issue counter; carries no semantics (see the schema comment). */
+    reissuedAt: number;
+}
 /**
  * Outcome of {@link CadreNode.registerSelf}, surfaced so callers (e.g. the CLI
  * `--owner` branch) can log what happened:
  * - `inserted` — the first owner-signed INSERT of this node's `CadrePeer` row.
  * - `refreshed` — a self-signed UPDATE of an existing row (heartbeat / addr change).
- * - `skipped` — nothing written (no self-signing key, or not yet a member with no
- *   owner service to self-insert).
+ *   Also reported when a first publish found its row seated by a concurrent
+ *   `authorizePeer` of this node's own id and fell through to the UPDATE — the write
+ *   really was an UPDATE, even though the caller's intent was a first publish.
+ * - `skipped` — nothing written (no self-signing key, not yet a member with no
+ *   owner service to self-insert, or the row was removed mid-publish).
  */
 export type SelfRegistrationOutcome = 'inserted' | 'refreshed' | 'skipped';
 /**
@@ -668,6 +885,20 @@ export interface DeviceTokenRecord {
     /** ed25519 self-signature over the signed payload, base64url. */
     sig: string;
 }
+/**
+ * A stored `CadreControl.DeviceToken` row: the self-signed
+ * {@link DeviceTokenRecord} plus the row's single-use `StampId` nonce.
+ *
+ * The stamp is deliberately OUTSIDE `DeviceTokenRecord`: the peer's own `Sig`
+ * covers only (peerId, platform, token, updatedAt), while the stamp is bound by
+ * the OWNER's insert/delete approvals. Readers need it to drop a row whose stamp
+ * has been retired into `CadreControl.Revocation` (a token resurrected by an
+ * approval replay on a node that had not yet converged on the tombstone).
+ */
+export interface DeviceTokenRow extends DeviceTokenRecord {
+    /** Single-use authorization nonce; rotates on every (re)insert. */
+    stampId: string;
+}
 /**
  * Options for {@link CadreNode.resolveDeviceToken}.
  */
@@ -815,6 +1046,14 @@ export interface WakeAck {
 export interface StrandAddrRequest {
     /** The strand whose strand-network address the requester wants to seed from. */
     strandId: string;
+    /**
+     * The derived transport peerId the requester's own strand-`strandId` node
+     * runs as (see `strand-transport-key.ts`). Present → the responder records a
+     * delegate admission grant for it, so its own connection gate (and thus its
+     * circuit-relay server, when it runs one) admits that peerId; absent →
+     * today's behavior exactly. See `delegate-admission.ts` for the trust model.
+     */
+    delegatePeerId?: string;
 }
 /**
  * Response to a {@link StrandAddrRequest}, carrying the responder's strand-node
@@ -849,6 +1088,27 @@ export interface ApplySeedResult {
     peersAdded: number;
     /** Error message if not successful */
     error?: string;
+    /**
+     * Owner-flagged seed peers this apply attempted to dial. Zero when the seed
+     * carried no owner peer with an address, or when the seed was rejected before
+     * the dial loop ran.
+     */
+    ownerDialsAttempted: number;
+    /**
+     * How many of those dials threw. `ownerDialsAttempted > 0 && ownerDialsFailed
+     * === ownerDialsAttempted` means "seeded but stranded": the seed itself was
+     * accepted (`success: true`) but no owner could be reached, so this node has
+     * no connection to bootstrap its control database from. The node retries those
+     * addresses on every control-cohort reconcile pass (see
+     * `CadreNode.dialColdStartBootstrap`), so this is a signal, not a fatal error.
+     *
+     * Zero failures is NOT proof of a live connection: the receiving node's
+     * membership gate denies AFTER the dialer's upgrade completes (see
+     * `createMembershipConnectionGater`), so a dial can resolve and then be torn
+     * down. Treat a non-zero value as certain failure and zero as "no failure
+     * observed".
+     */
+    ownerDialsFailed: number;
 }
 /**
  * Node network topology type for seed helper scenarios.
@@ -867,7 +1127,10 @@ export interface CadreInvite {
      * Owner ed25519 public keys (base64url) of the cadre, carried out-of-band
      * so a cold-start invitee can pin the trusted owner set before applying
      * any seed (the seed itself cannot vouch for its own signer). Populated by
-     * `createInvite` from the issuer's `OwnerKey` table.
+     * `createInvite` from the issuer's OWN node-local trusted-owner anchor —
+     * not its replicated `OwnerKey` table, because the invitee anchors whatever
+     * arrives here and a stranger's genesis-inserted key must not ride an
+     * otherwise-legitimate invite into a fresh node's anchor.
      */
     ownerKeys?: string[];
     /** Optional invite token for validation */

package/dist/types.js

@@ -40,4 +40,17 @@ export const HIBERNATION_TIMEOUTS = {
  * See {@link HibernationConfig.checkInWindowMs}.
  */
 export const DEFAULT_CHECKIN_WINDOW_MS = 15 * 1000;
+/**
+ * Replication-breadth constants, both networks' cluster policies, and the strand
+ * resolver, re-exported so cadre embedders, the SQL plugin and the integration
+ * harness share one definition. Defined in `@serfab/quereus-plugin-sereus`
+ * because that package also creates libp2p nodes and cannot depend on this one.
+ * The control network's breadth is fixed ({@link CONTROL_REPLICATION_BREADTH},
+ * not configurable) and so is its consensus policy ({@link CONTROL_CLUSTER_POLICY}
+ * — notably the super-majority threshold, which it leaves at Optimystic's default
+ * by omission); the strand breadth defaults to
+ * {@link CadreNodeConfig.strandClusterSize} while its policy is the fixed
+ * {@link STRAND_CLUSTER_POLICY}.
+ */
+export { MIN_CLUSTER_SIZE, CONTROL_REPLICATION_BREADTH, CONTROL_CLUSTER_POLICY, DEFAULT_STRAND_CLUSTER_SIZE, STRAND_CLUSTER_POLICY, resolveStrandClusterSize } from '@serfab/quereus-plugin-sereus';
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA+DA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA6C;IAC5E,QAAQ,EAAE;QACR,WAAW,EAAE,QAAQ,EAAS,aAAa;QAC3C,gBAAgB,EAAE,QAAQ,EAAI,kBAAkB;QAChD,eAAe,EAAE,QAAQ,EAAK,MAAM;QACpC,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,QAAQ,CAAE,MAAM;KACrC;IACD,WAAW,EAAE;QACX,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,YAAY;QAC1C,gBAAgB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,wBAAwB;QAC1D,eAAe,EAAE,EAAE,GAAG,IAAI,EAAI,mBAAmB;QACjD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe;KACnD;IACD,UAAU,EAAE;QACV,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,WAAW;QACzC,gBAAgB,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAG,uBAAuB;QACzD,eAAe,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,kBAAkB;QACpD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,gBAAgB;KACxD;IACD,OAAO,EAAE;QACP,WAAW,EAAE,EAAE,GAAG,IAAI,EAAQ,aAAa;QAC3C,gBAAgB,EAAE,EAAE,GAAG,IAAI,EAAG,wBAAwB;QACtD,eAAe,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAG,eAAe;QACjD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe;KAC5D;CACF,CAAC;AA4HF;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,GAAG,IAAI,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA2EA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA6C;IAC5E,QAAQ,EAAE;QACR,WAAW,EAAE,QAAQ,EAAS,aAAa;QAC3C,gBAAgB,EAAE,QAAQ,EAAI,kBAAkB;QAChD,eAAe,EAAE,QAAQ,EAAK,MAAM;QACpC,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,QAAQ,CAAE,MAAM;KACrC;IACD,WAAW,EAAE;QACX,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,YAAY;QAC1C,gBAAgB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,wBAAwB;QAC1D,eAAe,EAAE,EAAE,GAAG,IAAI,EAAI,mBAAmB;QACjD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe;KACnD;IACD,UAAU,EAAE;QACV,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,WAAW;QACzC,gBAAgB,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAG,uBAAuB;QACzD,eAAe,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,kBAAkB;QACpD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,gBAAgB;KACxD;IACD,OAAO,EAAE;QACP,WAAW,EAAE,EAAE,GAAG,IAAI,EAAQ,aAAa;QAC3C,gBAAgB,EAAE,EAAE,GAAG,IAAI,EAAG,wBAAwB;QACtD,eAAe,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAG,eAAe;QACjD,oBAAoB,EAAE,CAAC;QACvB,kBAAkB,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe;KAC5D;CACF,CAAC;AA+MF;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,GAAG,IAAI,CAAC;AAYnD;;;;;;;;;;;GAWG;AACH,OAAO,EACL,gBAAgB,EAChB,2BAA2B,EAC3B,sBAAsB,EACtB,2BAA2B,EAC3B,qBAAqB,EACrB,wBAAwB,EACzB,MAAM,+BAA+B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serfab/cadre-core",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "type": "module",
   "description": "Core library for Sereus cadre nodes - manages control networks and strand participation",
   "main": "dist/index.js",
@@ -24,6 +24,14 @@
       "types": "./dist/key-store-file.d.ts",
       "import": "./dist/key-store-file.js"
     },
+    "./trusted-owner-store-file": {
+      "types": "./dist/trusted-owner-store-file.d.ts",
+      "import": "./dist/trusted-owner-store-file.js"
+    },
+    "./bootstrap-peer-store-file": {
+      "types": "./dist/bootstrap-peer-store-file.d.ts",
+      "import": "./dist/bootstrap-peer-store-file.js"
+    },
     "./push-node": {
       "types": "./dist/push-node.d.ts",
       "import": "./dist/push-node.js"
@@ -54,8 +62,12 @@
   "devDependencies": {
     "@chainsafe/libp2p-noise": "^17.0.0",
     "@chainsafe/libp2p-yamux": "^8.0.1",
-    "@libp2p/peer-id-factory": "^4.2.4",
+    "@libp2p/circuit-relay-v2": "^4.1.3",
+    "@libp2p/identify": "4.0.10",
     "@libp2p/tcp": "^11.0.10",
+    "@libp2p/webrtc": "6.0.14",
+    "@libp2p/websockets": "^10.1.3",
+    "@optimystic/db-p2p-storage-fs": "^0.24.0",
     "@types/debug": "^4.1.12",
     "@types/node": "^25.0.10",
     "@vitest/coverage-v8": "^4.0.17",
@@ -68,12 +80,12 @@
     "@libp2p/interface": "^3.1.0",
     "@libp2p/peer-id": "^6.0.4",
     "@multiformats/multiaddr": "^12.5.1",
-    "@optimystic/db-core": "^0.14.1",
-    "@optimystic/db-p2p": "^0.14.1",
-    "@optimystic/quereus-plugin-crypto": "^0.14.1",
-    "@optimystic/quereus-plugin-optimystic": "^0.14.1",
-    "@quereus/quereus": "^4.4.0",
-    "@serfab/quereus-plugin-sereus": "^0.9.0",
+    "@optimystic/db-core": "^0.24.0",
+    "@optimystic/db-p2p": "^0.24.0",
+    "@optimystic/quereus-plugin-crypto": "^0.24.0",
+    "@optimystic/quereus-plugin-optimystic": "^0.24.0",
+    "@quereus/quereus": "^4.14.0",
+    "@serfab/quereus-plugin-sereus": "^0.11.0",
     "debug": "^4.4.3",
     "libp2p": "^3.1.3",
     "uint8arrays": "^5.1.0"