@serfab/cadre-core 0.8.1 → 0.10.0

package/dist/types.d.ts

@@ -1,15 +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
@@ -88,8 +101,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):
@@ -106,7 +120,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.
@@ -133,7 +187,7 @@ export interface NetworkConfig {
     transports?: Libp2pTransports;
     /**
      * Optional async resolver returning the multiaddrs to embed in invites
-     * (and other authority-address contexts). When unset, `libp2pNode.getMultiaddrs()`
+     * (and other owner-address contexts). When unset, `libp2pNode.getMultiaddrs()`
      * is used. Hosts behind NAT supply this to substitute their DDNS hostname
      * and externally-mapped port — see `@serfab/cadre-host`'s NatService.
      */
@@ -146,6 +200,12 @@ 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;
     /**
@@ -158,8 +218,8 @@ export interface NetworkConfig {
      */
     controlCohort?: {
         /**
-         * Cap on the number of NON-authority siblings dialed per reconcile pass
-         * (backbone/authority members are always dialed and do not count). Defaults
+         * Cap on the number of NON-owner siblings dialed per reconcile pass
+         * (backbone/owner members are always dialed and do not count). Defaults
          * to {@link DEFAULT_CONTROL_COHORT_TARGET_DEGREE}.
          */
         targetDegree?: number;
@@ -200,6 +260,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
  */
@@ -217,10 +290,10 @@ export interface CadreNodeConfig {
      * form). Mutually exclusive with {@link privateKey}. Absent ⇒ legacy behavior
      * (use `privateKey`, else libp2p generates an ephemeral key).
      *
-     * In the single-key reference model the authority signing key is *derived from*
-     * the node identity (see {@link CadreNode.getIdentityAuthorityKey}), so
-     * protecting the identity in a secure enclave protects the authority key too.
-     * A future separate-authority slot (`authorityKeyId`) is anticipated but not
+     * In the single-key reference model the owner signing key is *derived from*
+     * the node identity (see {@link CadreNode.getIdentityOwnerKey}), so
+     * protecting the identity in a secure enclave protects the owner key too.
+     * A future separate-owner slot (`ownerKeyId`) is anticipated but not
      * built here.
      */
     keyStore?: KeyStore;
@@ -236,6 +309,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) */
@@ -249,24 +357,103 @@ export interface CadreNodeConfig {
     requireSignedSchemas?: boolean;
     /**
      * Node-wide default trust anchor for INBOUND control-network seeds. Forwarded
-     * into every SeedBootstrapService this node constructs (authority, receive-only
+     * 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;
     /**
-     * Platform push-delivery credentials (FCM and/or APNs). When present, the node
-     * can deliver strand-wake data messages to suspended mobile peers over the
-     * platform push channel — the server fan-out constructs a `PushNotifier` from
-     * this. Absent ⇒ no platform push (control-network push-wake only). Injected
-     * per node by `cadre-host`; `privateKey` fields are secrets and are never logged.
+     * 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
+     * channel (FCM/APNs). Absent ⇒ no platform push (control-network push-wake only).
+     *
+     * The `notifier` is **injected**, not constructed here: a Node host builds it
+     * from `@serfab/cadre-core/push-node` (`createPushNotifier(credentials)`) and
+     * passes the instance, so the FCM/APNs modules (`node:crypto`/`node:http2`)
+     * stay out of the cross-platform core graph. Ownership transfers to the node on
+     * injection — `CadreNode.stop` closes the notifier (via `PushFanoutService`),
+     * releasing its APNs HTTP/2 session; a host must NOT also close an injected
+     * notifier itself. `cooldownMs`/`debounceMs` carry the fan-out anti-spam policy.
      */
-    push?: PushCredentials;
+    push?: {
+        /** The Node-constructed push router (see `@serfab/cadre-core/push-node`). */
+        notifier: PushNotifier;
+        /**
+         * Per-`(peer, strand)` minimum gap between push-wakes the fan-out emits.
+         * Default {@link DEFAULT_PUSH_COOLDOWN_MS} (5 min).
+         */
+        cooldownMs?: number;
+        /**
+         * Per-strand burst-coalescing window: a second trigger within it is dropped.
+         * Default {@link DEFAULT_PUSH_DEBOUNCE_MS} (10 s).
+         */
+        debounceMs?: number;
+    };
 }
 /**
  * Status of a strand instance
@@ -288,6 +475,13 @@ export interface StrandInstance {
     strandId: string;
     status: StrandStatus;
     sAppInfo?: SAppInfo;
+    /**
+     * The lifecycle mode this instance's runtime was built with — `bootstrap`
+     * (purely local transactor) or `networked` (cluster transactor). Refreshed on
+     * every runtime (re)build, so a resume that shifts `bootstrap → networked`
+     * updates it. Read-only reporting; drives no behavior.
+     */
+    mode: StrandMode;
     /** The libp2p node for this strand (only when active/idle) */
     libp2pNode?: Libp2p;
     /** The Quereus database for this strand (only when active/idle) */
@@ -389,7 +583,7 @@ export interface StrandConfig {
      * published the strand (the responder in formation, the creator in host/solo
      * paths; the same party that calls {@link CadreNode.publishStrand}). The founder
      * runs the one-time membership bootstrap at bring-up (writes `Strand.Header`, and
-     * for a closed strand the founding `Member`+`Authority`). A joiner leaves this
+     * for a closed strand the founding `Member`+`Manager`). A joiner leaves this
      * `false`/unset and writes nothing — it receives those rows via Optimystic sync.
      * Defaults to `false`.
      */
@@ -453,15 +647,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.
@@ -569,13 +754,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
- * `--authority` branch) can log what happened:
- * - `inserted` — the first authority-signed INSERT of this node's `CadrePeer` row.
+ * `--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
- *   authority 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';
 /**
@@ -593,7 +822,7 @@ export interface ResolveOpts {
     /**
      * Pluggable trust gate, evaluated after signature + freshness pass. Defaults
      * to {@link currentMemberTrustPolicy} (any existing — therefore
-     * authority-vouched — CadrePeer member is trusted). Inject a stricter policy
+     * owner-vouched — CadrePeer member is trusted). Inject a stricter policy
      * (e.g. from `seed-signerkey-trust-policy`) to reject otherwise-valid records
      * before dialing.
      */
@@ -648,6 +877,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}.
  */
@@ -720,9 +963,9 @@ export interface SeedPeer {
     peerId: string;
     /** Multiaddrs for connecting to this peer */
     multiaddrs: string[];
-    /** Whether this peer holds an authority key */
-    isAuthority: boolean;
-    /** ed25519 public key (base64url) — present on authority peers for signerKey verification */
+    /** Whether this peer holds an owner key */
+    isOwner: boolean;
+    /** ed25519 public key (base64url) — present on owner peers for signerKey verification */
     publicKey?: string;
 }
 /**
@@ -736,9 +979,9 @@ export interface ControlNetworkSeed {
     partyId: string;
     /** Known peers in the cadre */
     peers: SeedPeer[];
-    /** Signature over the seed by an authority key */
+    /** Signature over the seed by an owner key */
     signature: string;
-    /** The authority key that signed this seed */
+    /** The owner key that signed this seed */
     signerKey: string;
 }
 /**
@@ -750,9 +993,9 @@ export interface SeedMessage {
     partyId: string;
     /** Known peers in the cadre */
     peers: SeedPeer[];
-    /** Signature by an authority key */
+    /** Signature by an owner key */
     signature: string;
-    /** The authority key that signed this message */
+    /** The owner key that signed this message */
     signerKey: string;
 }
 /**
@@ -795,6 +1038,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
@@ -829,6 +1080,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.
@@ -841,15 +1113,18 @@ export type NodeTopology = 'public' | 'nat';
 export interface CadreInvite {
     /** Party ID of the cadre */
     partyId: string;
-    /** Multiaddrs to dial the authority */
-    authorityAddrs: string[];
+    /** Multiaddrs to dial the owner */
+    ownerAddrs: string[];
     /**
-     * Authority ed25519 public keys (base64url) of the cadre, carried out-of-band
-     * so a cold-start invitee can pin the trusted authority set before applying
+     * 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 `AuthorityKey` 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.
      */
-    authorityKeys?: string[];
+    ownerKeys?: string[];
     /** Optional invite token for validation */
     token?: string;
     /** Timestamp when invite was created */

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":"AA8DA;;;;;;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;AA2KF;;;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.8.1",
+  "version": "0.10.0",
   "type": "module",
   "description": "Core library for Sereus cadre nodes - manages control networks and strand participation",
   "main": "dist/index.js",
@@ -23,6 +23,18 @@
     "./key-store-file": {
       "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"
     }
   },
   "repository": {
@@ -50,8 +62,11 @@
   "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",
     "@types/debug": "^4.1.12",
     "@types/node": "^25.0.10",
     "@vitest/coverage-v8": "^4.0.17",
@@ -64,12 +79,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.2.1",
-    "@serfab/quereus-plugin-sereus": "^0.8.1",
+    "@optimystic/db-core": "^0.22.0",
+    "@optimystic/db-p2p": "^0.22.0",
+    "@optimystic/quereus-plugin-crypto": "^0.22.0",
+    "@optimystic/quereus-plugin-optimystic": "^0.22.0",
+    "@quereus/quereus": "^4.10.0",
+    "@serfab/quereus-plugin-sereus": "^0.10.0",
     "debug": "^4.4.3",
     "libp2p": "^3.1.3",
     "uint8arrays": "^5.1.0"