@serfab/cadre-core 0.11.0 → 0.13.0

package/dist/types.d.ts

@@ -1,12 +1,14 @@
 import type { ConnectionGater, Libp2p, PeerId, PrivateKey } from '@libp2p/interface';
 import type { IRawStorage, Libp2pTransports } from '@optimystic/db-p2p';
 import type { IPeerNetwork, IRepo } from '@optimystic/db-core';
-import type { StrandBackfillConfig } from './strand-backfill.js';
+import type { PeerJoinBackfillConfig } from './peer-join-backfill.js';
+import type { StrandRevocationEnforcementConfig } from './strand-revocation-enforcer.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 { EnrolledMachineStore } from './enrolled-machine-store.js';
 import type { PushNotifier } from './push-notifier.js';
 import type { RevocableTable } from './control-authorization.js';
 /**
@@ -20,7 +22,7 @@ export interface Libp2pNodeWithRepo extends Libp2p {
      * `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.
+     * backfill (`peer-join-backfill.ts`) logs once and stays inert when it is absent.
      */
     keyNetwork?: IPeerNetwork;
 }
@@ -98,12 +100,12 @@ export declare const HIBERNATION_TIMEOUTS: Record<LatencyHint, HibernationTimeou
  * 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.
+ * Either form is safe with a persistent backend. One instance handed to every scope
+ * also shares ONE cache wrapper (`wrapStorageWithCache` memoizes per inner instance),
+ * which counts its holders: a scope stopping releases only its own claim, and the
+ * wrapper is retired when the last scope releases it. The factory form is still the
+ * better default for a different reason — it partitions each strand's data, which
+ * simplifies cleanup.
  */
 export type RawStorageProvider = IRawStorage | ((strandId: string) => IRawStorage);
 /**
@@ -140,28 +142,75 @@ export interface StorageConfig {
  * Network configuration for libp2p
  */
 export interface NetworkConfig {
+    /**
+     * Addresses this machine's libp2p nodes bind. Omitted, `@optimystic/db-p2p`'s own
+     * default (`/ip4/0.0.0.0/tcp/0`) applies; `[]` means "cannot listen" and is honored
+     * as written (React Native hosts rely on that).
+     *
+     * The machine runs one control node plus one node per strand, so a FIXED port here
+     * can only belong to one of them. The control node binds it as configured; each
+     * strand node binds the same entry with its port rewritten to `0`, keeping the
+     * interface and transport (`/ws`, a specific-interface bind). A
+     * `<relay>/p2p-circuit` entry is untouched — the port inside it is the relay's, not
+     * a local bind. See `strand-network-config.ts`.
+     *
+     * **Only TCP, WebSocket (`/ws`, `/wss`) and circuit-relay addresses are bindable**
+     * unless {@link transports} supplies the factories for something else. A `/ws` entry
+     * switches the WebSocket transport on by itself; anything else — `/quic-v1`,
+     * `/webrtc`, `/webtransport` — refuses node start naming the address and the libp2p
+     * package it would need, rather than being dropped in silence by libp2p's transport
+     * manager. See `relay-addrs.ts` → `resolveTransportOptions`.
+     */
     listenAddrs?: string[];
     /**
-     * Addresses to advertise to peers instead of `listenAddrs` — for a node behind
+     * 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).
+     * (e.g. `mynode.example.com:4001` in front of a `0.0.0.0:4001` listener). Reaches
+     * libp2p's `addresses.announce` via `@optimystic/db-p2p`'s `NodeOptions.announceAddrs`.
      *
-     * 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.
+     * **Applies to this machine's CONTROL node only.** Strand nodes drop it: any concrete
+     * entry names a port, and that port is the control node's, so a strand node
+     * advertising it would send peers to the wrong node (`strand-network-config.ts`).
+     * Entries are still validated at node start whichever node ends up using them.
      *
-     * 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.
+     * **A non-empty value REPLACES the advertised set entirely.** Observed addresses,
+     * and the `/p2p-circuit` address earned from a {@link relayAddrs} reservation, are
+     * all dropped from what peers are told — so a node configured with both this and
+     * `relayAddrs` stops being reachable through its relay. `CadreNode.start()` warns
+     * when it sees that combination; it does not refuse it, since a node whose relay
+     * slot is decorative may legitimately want only the announced address.
+     *
+     * Reach for {@link appendAnnounceAddrs} instead in the common case — one publicly
+     * reachable address ADDED to everything else the node advertises. Or for
+     * {@link relayAddrs} alone, when the node has no stable public address to name and
+     * a relay reservation is what makes it dialable. (`inviteAddressResolver` is a
+     * narrower tool again: it substitutes a reachable address into invite payloads
+     * only, and changes nothing about what this node advertises on the wire.)
+     *
+     * An empty array means "unset" — it is dropped rather than forwarded, so it cannot
+     * land as an explicit empty announce set. An empty *entry* is a different thing and
+     * is rejected: a list of one blank string is non-empty, so it would replace every
+     * advertised address with nothing. Malformed entries are rejected on the same terms,
+     * both at node start — libp2p itself would not notice either until its first address
+     * lookup (see `announce-addrs.ts`), so this repo checks each entry up front.
      */
     announceAddrs?: string[];
+    /**
+     * Addresses to advertise **in addition to** `listenAddrs` — the field most
+     * deployments actually want, since it makes a node reachable at a public address
+     * without discarding the observed and `/p2p-circuit` addresses it would otherwise
+     * advertise. Reaches libp2p's `addresses.appendAnnounce` via
+     * `@optimystic/db-p2p`'s `NodeOptions.appendAnnounceAddrs`.
+     *
+     * **Control node only**, on the same terms as {@link announceAddrs}.
+     *
+     * **Ignored while {@link announceAddrs} is non-empty** — that is libp2p's own
+     * precedence, applied upstream; this repo does not merge the two locally. Set one
+     * or the other, not both.
+     *
+     * Empty-array, blank-entry and malformed-entry handling all match {@link announceAddrs}.
+     */
+    appendAnnounceAddrs?: 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
@@ -169,18 +218,26 @@ export interface NetworkConfig {
      * `/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`).
+     * On the CONTROL node this adds libp2p's bare `/p2p-circuit` SEARCH listener to
+     * {@link listenAddrs} (`relay-addrs.ts`) and `CadreNode.start()` drives the
+     * reservation itself once the control database is up — the ordering matters,
+     * because a listener that dials its relay from inside `libp2p.start()` put a
+     * sibling in this node's cohort before its own database existed, and a sibling
+     * that had not yet replicated this node's membership row refused the bring-up.
+     * STRAND nodes inherit the older per-relay `<relay>/p2p-circuit` listener, which
+     * has no such ordering hazard. A relay named here 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.
+     * FAIL-FAST both ways: a malformed entry throws at node start rather than being
+     * silently dropped, and a first reservation attempt that lands no
+     * `/p2p-circuit` address throws `RelayReservationFailedError` out of `start()`.
+     * The fail-soft posture over the same machinery is `CadreNode.reserveRelays()`.
      */
     relayAddrs?: string[];
     /**
@@ -189,6 +246,16 @@ export interface NetworkConfig {
      * better connectivity and uptime), false for transaction profile nodes.
      */
     enableRelay?: boolean;
+    /**
+     * Cap on concurrent circuit-relay reservations this node's relay server grants to
+     * peers it cannot (yet) recognize as authorized members — the boot-ordering window
+     * where a genuine member reserves its relay slot before its membership row has
+     * replicated here (see `membership-connection-gater.ts` → "The relay-reservation
+     * seam"). Authorized members and announced delegate peers are never counted against
+     * it. Default `MAX_UNAUTHORIZED_RELAY_RESERVATIONS` (8); 0 refuses every
+     * unauthorized reservation. Only meaningful while {@link enableRelay} is on.
+     */
+    unauthorizedRelayReservationCap?: number;
     /**
      * Custom libp2p transports. When omitted, the default transports from
      * `@optimystic/db-p2p` are used (TCP + circuit relay for Node.js).
@@ -211,6 +278,11 @@ export interface NetworkConfig {
      * (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.
+     *
+     * Returned addresses need NOT carry a `/p2p/<peerId>` suffix: `CadreNode`
+     * appends its own before publishing or dialing any of them, so a resolver
+     * cannot leave a sibling with the mixed suffixed/unsuffixed list that
+     * `libp2p.dial` rejects. Returning them already suffixed is equally fine.
      */
     inviteAddressResolver?: () => Promise<string[]>;
     /**
@@ -225,8 +297,14 @@ export interface NetworkConfig {
      * 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).
+     * either this gater or the membership policy denies.
+     *
+     * Strand cohort nodes: an OPEN strand's node receives this gater as-is (its
+     * peers are legitimately cross-party). A CLOSED strand's node composes
+     * revoked-peer denial onto it (`strand-revocation-enforcer.ts`) — every hook
+     * supplied here is still honored unchanged, and on the composed hooks
+     * (inbound encrypted connection, outbound peer dial, relay reservation) a
+     * deny from either this gater or the revocation check denies.
      */
     connectionGater?: ConnectionGater;
     /**
@@ -307,8 +385,14 @@ export interface ControlNetworkConfig {
  * by omission); the strand breadth defaults to
  * {@link CadreNodeConfig.strandClusterSize} while its policy is the fixed
  * {@link STRAND_CLUSTER_POLICY}.
+ *
+ * The two `*ClusterPolicy` BUILDERS are the same objects with the block-repair
+ * corroboration yardstick declared from the machines enrolled in this party
+ * ({@link resolveRepairYardstick}); handed no count, each returns its frozen base
+ * constant unchanged. A network picks the derived number up when its libp2p node is
+ * built, which for a strand is every wake from hibernation.
  */
-export { MIN_CLUSTER_SIZE, CONTROL_REPLICATION_BREADTH, CONTROL_CLUSTER_POLICY, DEFAULT_STRAND_CLUSTER_SIZE, STRAND_CLUSTER_POLICY, resolveStrandClusterSize } from '@serfab/quereus-plugin-sereus';
+export { MIN_CLUSTER_SIZE, CONTROL_REPLICATION_BREADTH, CONTROL_CLUSTER_POLICY, DEFAULT_STRAND_CLUSTER_SIZE, STRAND_CLUSTER_POLICY, resolveStrandClusterSize, resolveRepairYardstick, controlClusterPolicy, strandClusterPolicy } from '@serfab/quereus-plugin-sereus';
 /**
  * Main configuration for a CadreNode
  */
@@ -323,8 +407,8 @@ export interface CadreNodeConfig {
      * Pluggable secure store for node key material. When set, the node loads its
      * identity from `keyStore` under {@link identityKeyId}, generating + persisting
      * a fresh Ed25519 key on first run (protobuf bytes are the canonical stored
-     * form). Mutually exclusive with {@link privateKey}. Absent ⇒ legacy behavior
-     * (use `privateKey`, else libp2p generates an ephemeral key).
+     * form). Mutually exclusive with {@link privateKey}. Absent ⇒ use `privateKey`
+     * when set, else libp2p generates an ephemeral key.
      *
      * In the single-key reference model the owner signing key is *derived from*
      * the node identity (see {@link CadreNode.getIdentityOwnerKey}), so
@@ -369,17 +453,42 @@ export interface CadreNodeConfig {
      */
     strandClusterSize?: number;
     /**
-     * Tuning for the strand peer-join block catch-up (see `strand-backfill.ts`):
+     * Tuning for the strand peer-join block catch-up (see `peer-join-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.
+     * up physically holding them. Applies to every strand this node starts.
+     * Omit for the defaults (`DEFAULT_PEER_JOIN_BACKFILL`); `{ enabled: false }`
+     * restores the no-backfill behaviour. The control network runs its own,
+     * separately tuned catch-up — see {@link controlBackfill}.
+     */
+    strandBackfill?: PeerJoinBackfillConfig;
+    /**
+     * Tuning for the CONTROL network's peer-join block catch-up (same module,
+     * `peer-join-backfill.ts`, wired in `CadreNode.start`): when the control
+     * libp2p node connects to an AUTHORIZED party member this runtime has not yet
+     * caught up, every block in the control database's own raw store is pushed to
+     * it. This is what makes a control block committed while the writer was alone
+     * (collection headers written at genesis above all) physically reach members
+     * that joined later — without it, such a member that restarts offline reads
+     * the affected tables as empty. Pushes are gated on
+     * `CadreNode.isAuthorizedMember`, checked at push time, because the control
+     * network's inbound gate deliberately admits non-members in several states
+     * (seed delivery, enrollment, bootstrap/relay peers). Omit for the defaults
+     * (`DEFAULT_PEER_JOIN_BACKFILL`); `{ enabled: false }` disables it.
      */
-    strandBackfill?: StrandBackfillConfig;
+    controlBackfill?: PeerJoinBackfillConfig;
+    /**
+     * Tuning for the CLOSED-strand revoked-peer gate
+     * (`strand-revocation-enforcer.ts`), applied to every closed strand this node
+     * starts: each strand node materializes the peer ids bound to REMOVED members
+     * (orphaned `Strand.MemberPeer` rows) and refuses them at the stream and
+     * connection layers, so removing a party cuts the network to its machines
+     * rather than only deleting its row. Open strands never arm it. Omit for the
+     * defaults (`DEFAULT_REVOCATION_POLL_INTERVAL_MS` refresh cadence);
+     * `{ enabled: false }` restores the pre-existing behaviour.
+     */
+    strandRevocationEnforcement?: StrandRevocationEnforcementConfig;
     /** Hibernation configuration */
     hibernation?: HibernationConfig;
     /** Polling interval for strand watcher in ms (default: 5000) */
@@ -463,6 +572,39 @@ export interface CadreNodeConfig {
          */
         store?: BootstrapPeerStore;
     };
+    /**
+     * Node-local record of how many machines this party had enrolled the last time
+     * this node looked (see `enrolled-machine-store.ts`): the block-repair
+     * corroboration yardstick the CONTROL node declares when its libp2p node is
+     * built. Sibling of {@link trustedOwners} / {@link bootstrapPeers} — same
+     * NON-replicated, per-party, injected-backend shape — and, like
+     * {@link bootstrapPeers}, nothing here is trust-bearing: it is a repair hint,
+     * recomputed from `CadrePeer` rows the moment the control database is up.
+     *
+     * It exists only because the control node is created BEFORE that database, so
+     * the live count is unreadable at the one moment it is needed; remembering it
+     * across the restart is what breaks that deadlock. Absent ⇒ an in-memory store
+     * is created at start(), which cold-starts on every launch and therefore
+     * declares nothing — byte-for-byte the behaviour before this record existed.
+     * No embedder is forced to change.
+     *
+     * A party that grows applies the larger number on each node's NEXT launch,
+     * deliberately: Optimystic freezes the policy at node construction and offers
+     * no runtime setter, and a node still holding the old value runs at exactly
+     * today's behaviour, so there is no forced rebuild.
+     *
+     * A new platform needs no new store class: supply a `DurableSlot` for the
+     * platform's storage and inject `PersistentEnrolledMachineStore.open(slot, partyId)`.
+     */
+    enrolledMachines?: {
+        /**
+         * Injected store instance — e.g. a `FileEnrolledMachineStore` from the
+         * Node-only subpath `@serfab/cadre-core/enrolled-machine-store-file`,
+         * persisted in the node's state directory. Its `partyId` must match
+         * `controlNetwork.partyId`; start() fails closed on a mismatch.
+         */
+        store?: EnrolledMachineStore;
+    };
     /**
      * 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
@@ -555,6 +697,17 @@ export interface StrandRow {
     Id: string;
     MemberPrivateKey: string | null;
     Type: 'o' | 'c';
+    /**
+     * ed25519 (base64url) owner key of the MACHINE that published this row — the
+     * signer of the owner-signed `Strand` insert (`== context.OwnerKey`, pinned by
+     * the schema's `AuthorizedInsert`). Identifies the founding machine, so a
+     * launch with no explicit `founder` flag derives "am I the founder?" by
+     * comparing it to the node's own owner key (see `CadreNode.launchStrand`).
+     * `null` on a consent-seated strand (the unsigned `FormationUsage` branch
+     * records no trustworthy signer). Provenance, not content —
+     * `strandRowMismatches` excludes it from the identical-content comparison.
+     */
+    FounderOwnerKey: string | null;
 }
 /**
  * sApp configuration provided by the hosting application when creating a strand.
@@ -592,11 +745,62 @@ export interface StrandConfig {
      * 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`+`Manager`). A joiner leaves this
-     * `false`/unset and writes nothing — it receives those rows via Optimystic sync.
-     * Defaults to `false`.
+     * unset and writes nothing — it receives those rows via Optimystic sync.
+     *
+     * When unset, founder-ness is DERIVED from the row: this node founds iff
+     * {@link StrandRow.FounderOwnerKey} equals its own owner key. An explicit
+     * `true`/`false` wins over the derivation — the formation/responder flows pass
+     * it deliberately, since a consent-seated row carries a null column.
      */
     founder?: boolean;
 }
+/**
+ * What {@link CadreNode.foundStrand} needs to publish a strand's control row AND start it
+ * locally as its founder — the resumable one-call form of `publishStrand` + `addStrand`.
+ *
+ * No `strandRow`: the row is the OUTPUT of founding, either freshly published or read back
+ * from an interrupted earlier attempt. `StrandConfig` (the join/attach shape) takes one
+ * because there the row already exists and came from the control network.
+ */
+export interface FoundStrandConfig {
+    /** Unique strand identifier. Trimmed; blank is rejected. */
+    strandId: string;
+    /** `'o'` for open (default) or `'c'` for closed. */
+    type?: 'o' | 'c';
+    /**
+     * Membership key gating a closed strand. Required in practice for `type: 'c'` (the
+     * founder bootstrap rejects a null key), and IGNORED when the strand is already
+     * published — the stored key wins, so read the resolved key back off the returned
+     * instance rather than trusting a freshly minted one.
+     */
+    memberPrivateKey?: string;
+    /** sApp configuration the hosting application provides, as for {@link StrandConfig}. */
+    sAppConfig: SAppConfig;
+}
+/**
+ * What {@link CadreNode.foundStrand} hands back: the running instance PLUS the `Strand` row
+ * the strand actually runs under.
+ *
+ * The row is returned separately rather than left for the caller to read off the instance
+ * because on a resumed founding it is NOT the caller's input — a closed strand adopts the
+ * stored `MemberPrivateKey`, discarding a freshly minted one. A caller that must carry the
+ * membership key onward (to mint an invitation, say) reads it from HERE.
+ */
+export interface FoundStrandResult {
+    /** The active local instance, as {@link CadreNode.addStrand} would have returned. */
+    instance: StrandInstance;
+    /** The live control-plane row: freshly published, or the one already there. */
+    strandRow: StrandRow;
+    /**
+     * Whether THIS machine actually founded (ran / will have run the one-time
+     * founder bootstrap). `false` when the resolved row was published by a
+     * DIFFERENT machine's owner key — e.g. a sibling won a concurrent founding
+     * race — in which case the call attached as a joiner instead, which is the
+     * correct outcome (two machines bootstrapping one strand on separate replicas
+     * is the double-`Header` hazard).
+     */
+    founded: boolean;
+}
 /**
  * Result of creating a new cadre peer
  */
@@ -654,6 +858,21 @@ export interface FormStrandResult {
      * from {@link invitePrivateKey} (the initiator's own generated signing key).
      */
     memberPrivateKey?: string;
+    /**
+     * The responder's live STRAND-network multiaddrs for the formed strand — the only
+     * cross-party discovery seed there is, since the strand-addr RPC that resolves a
+     * sibling's strand addresses answers own-party callers only.
+     *
+     * Always an array, frequently EMPTY: the responder discloses none when it holds no
+     * live strand node for the strand it just provisioned (the responder-provisions path
+     * mints a strand that has not launched yet). `CadreNode.formStrand` records these
+     * itself, so an embedding app only needs them to seed a strand it launches OUTSIDE
+     * that node.
+     *
+     * One-shot and in-memory: they are the responder's addresses at the moment of
+     * formation and are never re-resolved — see `docs/strands.md`.
+     */
+    strandAddrs: string[];
 }
 /**
  * Disclosure object provided during strand formation.
@@ -706,6 +925,26 @@ export interface CadreNodeEvents {
     'strand:waking': {
         strandId: string;
     };
+    /**
+     * Emitted when this node discovers it is no longer a member of a CLOSED
+     * strand — its party was removed by a manager, or it left. Detected by the
+     * strand's revoked-peer gate (`strand-revocation-enforcer.ts`) seeing this
+     * node's own peer id in the revoked set, so it is BEST-EFFORT: it fires only
+     * if the removal replicated here before the rest of the strand cut us off,
+     * and a node that was already offline may never see it at all.
+     *
+     * Nothing is stopped or torn down for you. Treat it as "this strand will no
+     * longer sync": remaining members refuse this node's streams, dials, and
+     * connections, so reads keep working against whatever is stored locally while
+     * writes stop propagating. Stopping the strand (`stopStrand`) or deleting its
+     * data is the app's decision. Emitted once per removal — re-armed if a manager
+     * re-admits this party, so a second removal is reported again — and a
+     * hibernation wake rebuilds the gate, which may re-emit for a strand still
+     * revoked.
+     */
+    'strand:revoked': {
+        strandId: string;
+    };
     /**
      * Emitted when the control network advertises a strand this node has no
      * registered `sAppConfig` for — i.e. a strand created by another member. The

package/dist/types.js

@@ -51,6 +51,12 @@ export const DEFAULT_CHECKIN_WINDOW_MS = 15 * 1000;
  * by omission); the strand breadth defaults to
  * {@link CadreNodeConfig.strandClusterSize} while its policy is the fixed
  * {@link STRAND_CLUSTER_POLICY}.
+ *
+ * The two `*ClusterPolicy` BUILDERS are the same objects with the block-repair
+ * corroboration yardstick declared from the machines enrolled in this party
+ * ({@link resolveRepairYardstick}); handed no count, each returns its frozen base
+ * constant unchanged. A network picks the derived number up when its libp2p node is
+ * built, which for a strand is every wake from hibernation.
  */
-export { MIN_CLUSTER_SIZE, CONTROL_REPLICATION_BREADTH, CONTROL_CLUSTER_POLICY, DEFAULT_STRAND_CLUSTER_SIZE, STRAND_CLUSTER_POLICY, resolveStrandClusterSize } from '@serfab/quereus-plugin-sereus';
+export { MIN_CLUSTER_SIZE, CONTROL_REPLICATION_BREADTH, CONTROL_CLUSTER_POLICY, DEFAULT_STRAND_CLUSTER_SIZE, STRAND_CLUSTER_POLICY, resolveStrandClusterSize, resolveRepairYardstick, controlClusterPolicy, strandClusterPolicy } 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":"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"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA6EA;;;;;;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;AA2RF;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,GAAG,IAAI,CAAC;AAYnD;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EACL,gBAAgB,EAChB,2BAA2B,EAC3B,sBAAsB,EACtB,2BAA2B,EAC3B,qBAAqB,EACrB,wBAAwB,EACxB,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,+BAA+B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serfab/cadre-core",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "type": "module",
   "description": "Core library for Sereus cadre nodes - manages control networks and strand participation",
   "main": "dist/index.js",
@@ -32,6 +32,10 @@
       "types": "./dist/bootstrap-peer-store-file.d.ts",
       "import": "./dist/bootstrap-peer-store-file.js"
     },
+    "./enrolled-machine-store-file": {
+      "types": "./dist/enrolled-machine-store-file.d.ts",
+      "import": "./dist/enrolled-machine-store-file.js"
+    },
     "./push-node": {
       "types": "./dist/push-node.d.ts",
       "import": "./dist/push-node.js"
@@ -64,13 +68,17 @@
     "@chainsafe/libp2p-yamux": "^8.0.1",
     "@libp2p/circuit-relay-v2": "^4.1.3",
     "@libp2p/identify": "4.0.10",
+    "@libp2p/logger": "^6.2.2",
+    "@libp2p/peer-store": "^12.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",
+    "@optimystic/db-p2p-storage-fs": "^1.0.0-beta.2",
     "@types/debug": "^4.1.12",
     "@types/node": "^25.0.10",
     "@vitest/coverage-v8": "^4.0.17",
+    "datastore-core": "^11.0.1",
+    "main-event": "^1.0.1",
     "rimraf": "^6.1.2",
     "typescript": "^5.9.3",
     "vitest": "^4.0.17"
@@ -80,12 +88,12 @@
     "@libp2p/interface": "^3.1.0",
     "@libp2p/peer-id": "^6.0.4",
     "@multiformats/multiaddr": "^12.5.1",
-    "@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",
+    "@optimystic/db-core": "^1.0.0-beta.2",
+    "@optimystic/db-p2p": "^1.0.0-beta.2",
+    "@optimystic/quereus-plugin-crypto": "^1.0.0-beta.2",
+    "@optimystic/quereus-plugin-optimystic": "^1.0.0-beta.2",
+    "@quereus/quereus": "^4.19.0",
+    "@serfab/quereus-plugin-sereus": "^0.13.0",
     "debug": "^4.4.3",
     "libp2p": "^3.1.3",
     "uint8arrays": "^5.1.0"

package/src/announce-addrs.ts

@@ -0,0 +1,93 @@
+/**
+ * Translate `network.announceAddrs` / `network.appendAnnounceAddrs` — the operator-facing
+ * "advertise these addresses" settings — into the two `@optimystic/db-p2p` `NodeOptions`
+ * fields of the same names, which reach libp2p's `addresses.announce` /
+ * `addresses.appendAnnounce`.
+ *
+ * Two jobs, both of which the control node and every strand node need identically, hence
+ * one module rather than the same conditional spread written twice:
+ *
+ * - **Empty means unset.** libp2p treats `announce: []` as "no override", and forwarding
+ *   `[]` would still be forwarding a field. An empty config array is dropped so it cannot
+ *   land as an explicit empty announce set.
+ * - **Validate the multiaddrs here, at start.** libp2p does NOT validate announce addrs
+ *   at construction: `AddressManager` stores them as raw strings and only parses them on
+ *   the first `getAnnounceAddrs()`. A typo therefore produces a node that starts
+ *   cleanly, then throws `InvalidMultiaddrError` out of every `getMultiaddrs()` call —
+ *   including an UNHANDLED one from the debounced peer-store update libp2p runs on
+ *   `transport:listening`. Verified against libp2p's `address-manager` (its constructor
+ *   does `announce.map(ma => ma.toString())`; `getAnnounceAddrs()` does `multiaddr(a)`).
+ *   Parsing each entry up front converts that into a loud failure at node start, which is
+ *   what {@link relayCircuitAddrs} already does for `network.relayAddrs`.
+ *
+ *   Parsing alone is not enough, though: `''` and `'/'` both parse into a component-less
+ *   multiaddr, and a set holding only those is non-empty by the rule above — so it would
+ *   replace every advertised address with nothing at all. An entry naming no address is
+ *   therefore rejected alongside one that fails to parse.
+ */
+
+import { multiaddr, type Multiaddr } from '@multiformats/multiaddr';
+import type { NetworkConfig } from './types.js';
+
+/**
+ * The announce fields to spread into `createLibp2pNode` options. A field is present
+ * only when the operator configured a non-empty list for it, so a node that configures
+ * neither passes neither.
+ */
+export interface ResolvedAnnounceAddrs {
+  announceAddrs?: string[];
+  appendAnnounceAddrs?: string[];
+}
+
+/**
+ * Resolve both announce fields off a `NetworkConfig`. Throws — naming the offending
+ * config field and entry — when any entry is not a parsable multiaddr.
+ */
+export function resolveAnnounceAddrs(network: NetworkConfig | undefined): ResolvedAnnounceAddrs {
+  const announceAddrs = configuredAddrs('network.announceAddrs', network?.announceAddrs);
+  const appendAnnounceAddrs = configuredAddrs('network.appendAnnounceAddrs', network?.appendAnnounceAddrs);
+  return {
+    ...(announceAddrs && { announceAddrs }),
+    ...(appendAnnounceAddrs && { appendAnnounceAddrs })
+  };
+}
+
+/**
+ * Whether this node's advertised set will be REPLACED rather than extended — i.e.
+ * whether {@link ResolvedAnnounceAddrs.announceAddrs} is in play at all. The single
+ * predicate behind `CadreNode.start()`'s operator warning, kept here so the warning
+ * and the forwarding agree on what "set" means (non-empty, not merely present).
+ */
+export function replacesAdvertisedAddrs(network: NetworkConfig | undefined): boolean {
+  return (network?.announceAddrs?.length ?? 0) > 0;
+}
+
+/** The entries to forward for one announce field, or `undefined` when it is unset or empty. */
+function configuredAddrs(field: string, addrs: readonly string[] | undefined): string[] | undefined {
+  if (!addrs || addrs.length === 0) {
+    return undefined;
+  }
+  return addrs.map((addr) => validated(field, addr));
+}
+
+/** `addr` unchanged, having proved it names a real address — config field named on failure. */
+function validated(field: string, addr: string): string {
+  if (parsed(field, addr).getComponents().length === 0) {
+    // `''` and `'/'` PARSE: both yield a component-less multiaddr that stringifies to
+    // `/`. Forwarded, they make an announce set that is non-empty but names nothing —
+    // which by the replacement rule above costs the node every address it would
+    // otherwise advertise, silently. A templated `cadre.yaml` whose address variable went
+    // unsubstituted is the realistic way in, so it is rejected rather than forwarded.
+    throw new Error(`${field} entry names no address: ${JSON.stringify(addr)}`);
+  }
+  return addr;
+}
+
+/** `addr` as a multiaddr, with the config field named on a parse failure. */
+function parsed(field: string, addr: string): Multiaddr {
+  try {
+    return multiaddr(addr);
+  } catch (err) {
+    throw new Error(`${field} entry is not a valid multiaddr: ${addr}`, { cause: err });
+  }
+}