@serfab/cadre-core 0.10.0 → 0.12.0

package/dist/types.d.ts

@@ -82,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.
+ *
+ * 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);
 /**
@@ -92,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
@@ -121,26 +142,48 @@ export interface StorageConfig {
 export interface NetworkConfig {
     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`,
+     * on this node's control node and on every strand node it runs.
+     *
+     * **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.
      *
-     * 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.
+     * 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.)
      *
-     * 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.
+     * 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`.
+     *
+     * **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
@@ -148,18 +191,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[];
     /**
@@ -168,6 +219,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).
@@ -190,6 +251,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[]>;
     /**
@@ -212,9 +278,10 @@ export interface NetworkConfig {
      * 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?: {
         /**
@@ -228,6 +295,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;
     };
 }
 /**
@@ -287,8 +368,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
@@ -475,13 +556,6 @@ 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) */
@@ -549,20 +623,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
  */
@@ -571,13 +631,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

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;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"}
+{"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;AA4PF;;;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.10.0",
+  "version": "0.12.0",
   "type": "module",
   "description": "Core library for Sereus cadre nodes - manages control networks and strand participation",
   "main": "dist/index.js",
@@ -67,6 +67,7 @@
     "@libp2p/tcp": "^11.0.10",
     "@libp2p/webrtc": "6.0.14",
     "@libp2p/websockets": "^10.1.3",
+    "@optimystic/db-p2p-storage-fs": "^0.27.0",
     "@types/debug": "^4.1.12",
     "@types/node": "^25.0.10",
     "@vitest/coverage-v8": "^4.0.17",
@@ -79,12 +80,12 @@
     "@libp2p/interface": "^3.1.0",
     "@libp2p/peer-id": "^6.0.4",
     "@multiformats/multiaddr": "^12.5.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",
+    "@optimystic/db-core": "^0.27.0",
+    "@optimystic/db-p2p": "^0.27.0",
+    "@optimystic/quereus-plugin-crypto": "^0.27.0",
+    "@optimystic/quereus-plugin-optimystic": "^0.27.0",
+    "@quereus/quereus": "^4.18.0",
+    "@serfab/quereus-plugin-sereus": "^0.12.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 });
+  }
+}