@serfab/cadre-core 0.11.0 → 0.12.0

package/src/strand-membership-writer.ts

@@ -228,6 +228,28 @@ async function strandTableCount(db: Database, table: 'Header' | 'Member' | 'Mana
   return 0;
 }
 
+/**
+ * Whether any `Strand.Revocation` row has ever retired a `Manager` seat — the
+ * exact condition that permanently closes the founding branch of
+ * `Manager.Authorized` (see the schema's bootstrap-branch comment). Unfiltered
+ * scan + JavaScript comparison, the module's scan-not-seek idiom (rationale on
+ * {@link scanMemberPeers}).
+ *
+ * NOTE: walks the whole append-only `Strand.Revocation` table when no `Manager`
+ * tombstone is present (it returns on the first one it finds). Cheap at strand
+ * scale; if membership churn ever makes that table large — the growth the
+ * `Revocation` schema comment already flags, tracked by `debt-strand-tombstone-reap`
+ * — this wants a stored "founding closed" marker rather than a scan per call.
+ */
+async function strandHasManagerRevocation(db: Database): Promise<boolean> {
+  for await (const row of db.eval('select TableName from Strand.Revocation')) {
+    if (row.TableName === 'Manager') {
+      return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Insert the singleton `Strand.Header` if absent.
  *
@@ -304,12 +326,25 @@ async function insertFounderMemberIfAbsent(db: Database, memberKey: string, stra
  * `Manager.OnlyClosed` is a deferred (subquery) check evaluated at commit. The
  * sequential auto-commit Header→Member→Manager order in
  * {@link bootstrapFounderMembership} satisfies both.
+ *
+ * SEALED strands are skipped, not re-founded: a strand whose sole manager has
+ * {@link sealStrand}ed also has zero `Manager` rows, but its founding branch is
+ * closed for good (the schema's bootstrap branch requires no `Manager`-table
+ * `Revocation` row to exist). Attempting the founding insert here would be
+ * schema-rejected and turn every founder restart of a sealed strand into a
+ * loud failure — so this mirrors the schema's own gate and returns quietly.
+ * A crash BETWEEN the founding Member and Manager inserts leaves no Revocation
+ * rows at all, so that restart still completes the founding.
  */
 async function insertFounderManagerIfAbsent(db: Database, memberKey: string, strandId: string): Promise<void> {
   if (await strandTableCount(db, 'Manager') > 0) {
     log('Manager already present for strand %s; skipping founder Manager', strandId);
     return;
   }
+  if (await strandHasManagerRevocation(db)) {
+    log('Strand %s has retired a manager seat (sealed); skipping founder Manager', strandId);
+    return;
+  }
   await db.exec(
     `insert into Strand.Manager (MemberKey, Generation, StampId)
        with context ManagerKey = null, Signature = null
@@ -814,8 +849,8 @@ export interface RevokeMemberParams {
  * A manager must resign its `Manager` row before (or in the same transaction
  * as) losing membership — `Member.NotAManager` rejects un-membering a key that
  * still holds a Manager row. And the strand never drops to zero members
- * (`Member.MinOneMember`, a local-count floor with the same cross-node caveat
- * as `MinOneManager`).
+ * (`Member.MinOneMember`, a local-count floor with the cross-node caveat its
+ * schema NOTE states).
  *
  * @param db - The closed strand's database.
  * @param params - The revoking manager keypair and the target member key.
@@ -1382,13 +1417,19 @@ export interface RemoveManagerParams {
  * — deferred — IS enforced here: a signer that is neither an existing manager nor
  * the target itself is rejected at commit.
  *
- * THE LAST MANAGER CANNOT BE REMOVED. `Manager.MinOneManager` (`check on delete`,
- * deferred, so it sees the POST-delete count) rejects any delete that would leave the
- * strand with zero managers — an admin-less closed strand could never admit anyone
- * again, since `Invite`, `addMemberByManager`, and `addManager` all require a
- * `Manager` row. The bootstrap branch of `Manager.Authorized` is gated to INSERTs
+ * THE SOLE MANAGER CANNOT ORDINARILY RESIGN — it SEALS instead. The `'resign'`
+ * branch of `Manager.Authorized` requires at least one manager in the POST-delete
+ * image, so a resignation that would empty the `Manager` table is schema-rejected;
+ * emptying it deliberately is a distinct, self-signed act — {@link sealStrand} —
+ * that permanently freezes admission. This writer refuses the sole-manager
+ * self-resignation up front with an error naming `sealStrand`; that TS guard is UX,
+ * not the trust boundary — the schema rejects a mis-counted `'resign'` approval
+ * regardless. Reading the count inside a caller-joined transaction is correct: an
+ * add-then-resign hand-off composed in one transaction sees 2 and passes, while
+ * the already-rejected delete-then-add swap sees 1 and is refused here as well as
+ * by the schema. The bootstrap branch of `Manager.Authorized` is gated to INSERTs
  * (`old.MemberKey is null`), so it does not waive the signature check on a delete
- * that drops the count toward the floor: a second-to-last removal is authorized
+ * that drops the count toward zero: a second-to-last removal is authorized
  * exactly like any other.
  *
  * HAND-OFF ORDER: a sole manager transferring control must ADD the successor FIRST
@@ -1397,15 +1438,19 @@ export interface RemoveManagerParams {
  * successor's insert has no other manager to authorize it once the sole manager's
  * row is gone.
  *
- * Cross-node caveat: `MinOneManager` counts rows visible to THIS transaction, so two
- * nodes concurrently removing different managers can each see a survivor and still
- * converge to zero. Noted in the schema; a cross-node floor is not attempted here.
+ * Cross-node caveat: the `'resign'`/`'seal'` branches count rows visible to THIS
+ * transaction, so two nodes concurrently removing different managers can each see
+ * a survivor and still converge to zero — an unintended seal. Noted in the schema
+ * (the `Manager` table's seal-propagation NOTE); a cross-node floor is not
+ * attempted here.
  *
  * @param db - The closed strand's database.
  * @param params - The authorizing keypair and the target manager key.
- * @throws If `Manager.Authorized` rejects (a signer that is neither another existing
- *   manager nor the target itself) or `Manager.MinOneManager` rejects (the removal
- *   would leave no managers); the whole delete+tombstone transaction rolls back.
+ * @throws If the signer IS the target and it is the sole manager (before writing —
+ *   the operation the caller wants is {@link sealStrand}), or if `Manager.Authorized`
+ *   rejects (a signer that is neither another existing manager nor the target
+ *   itself, or a raw sole-manager `'resign'` whose post-image count is zero); the
+ *   whole delete+tombstone transaction rolls back.
  */
 export async function removeManager(db: Database, params: RemoveManagerParams): Promise<void> {
   const { byManagerKeyPair, targetManagerKey } = params;
@@ -1415,6 +1460,12 @@ export async function removeManager(db: Database, params: RemoveManagerParams):
     return;
   }
   const tag = byManagerKeyPair.publicKeyB64 === targetManagerKey ? 'resign' : 'remove';
+  if (tag === 'resign' && await strandTableCount(db, 'Manager') === 1) {
+    throw new Error(
+      'Cannot resign as the SOLE manager: an ordinary resignation never empties the '
+      + 'Manager table. To permanently freeze admission instead, call sealStrand.',
+    );
+  }
   const signature = signStrandApproval(
     ['Strand.Manager', tag, targetManagerKey, target.stampId],
     byManagerKeyPair.privateKeyB64,
@@ -1430,3 +1481,147 @@ export async function removeManager(db: Database, params: RemoveManagerParams):
   });
   log('Removed manager %s by %s', targetManagerKey, byManagerKeyPair.publicKeyB64);
 }
+
+// ── Sealing (the sole manager permanently freezes admission) ──────────────────
+
+/** Parameters for {@link sealStrand}. */
+export interface SealStrandParams {
+  /**
+   * The SOLE manager's strand keypair. Its `publicKeyB64` must be the one live
+   * `Strand.Manager` row; it signs the seal-tagged digest over its own key and
+   * live stamp, and files the accompanying tombstone (it is still a committed
+   * member, which is what `Revocation.Authorized` checks).
+   */
+  managerKeyPair: Ed25519KeyPair;
+}
+
+/**
+ * Seal the strand: the SOLE manager deliberately steps down, permanently freezing
+ * membership.
+ *
+ * A sealed strand has zero `Manager` rows, and every admission path — issuing or
+ * cancelling an invitation, consuming one issued BEFORE the seal
+ * (`ConsumedInvite.NotSealed`), admitting a member, promoting a manager — requires
+ * one, so nobody can ever be let in again. That freeze is a privacy guarantee to
+ * everyone who contributed: no key holds the power to admit a party who would then
+ * read the strand's whole history. Sealing is irreversible — the founding branch
+ * of `Manager.Authorized` closes for good once any manager stamp is retired into
+ * `Strand.Revocation`. What remains possible: members may {@link leaveStrand}
+ * (floored by `MinOneMember`), manage their own `MemberPeer` rows, and file
+ * `Revocation` tombstones.
+ *
+ * The `'seal'` branch of `Manager.Authorized` accepts a self-signed delete only
+ * when the POST-image manager count is ZERO — a distinct action tag from
+ * `'resign'`, so a captured resignation approval can never seal and a raw writer
+ * cannot seal by accident. Like {@link removeManager}, the delete pairs with its
+ * `Strand.Revocation` tombstone in one transaction.
+ *
+ * The TS count/identity checks below are UX guards, not the trust boundary — the
+ * schema rejects a mis-tagged or mis-counted approval regardless of what this
+ * writer (or any raw writer) presents.
+ *
+ * NOTE: a seal approval is a bearer token for its row incarnation, like every other
+ * self-signed approval here — but the `'seal'` branch's post-image count of 0 is
+ * satisfied for EVERY row deleted in the same transaction, so N managers each
+ * presenting a valid `'seal'` approval seal jointly (pinned as an accepted case in
+ * `strand-seal.spec.ts`). Unreachable today: this writer mints a seal signature only
+ * while its caller is the SOLE manager, and spends it immediately, so a second
+ * manager never has one to combine. If seal-approval MINTING is ever split from
+ * spending — offline signing, a two-phase seal, a queued approval — one manager
+ * holding another's unspent seal approval could freeze the strand irreversibly
+ * without its current consent; re-gate here (or narrow the schema branch) then.
+ *
+ * @param db - The closed strand's database.
+ * @param params - The sole manager's own keypair.
+ * @throws If more than one manager exists (the caller wants {@link removeManager}),
+ *   or the supplied keypair holds no `Manager` row while one exists, or the strand
+ *   holds no `Manager` row and has never retired one (not founded yet — see
+ *   {@link isStrandSealed}), or any schema constraint rejects; the whole
+ *   delete+tombstone transaction rolls back. A strand that is ALREADY sealed logs
+ *   and returns quietly (restart-safe, matching {@link bootstrapFounderMembership}
+ *   and {@link removeManager}'s absent-row no-op).
+ */
+export async function sealStrand(db: Database, params: SealStrandParams): Promise<void> {
+  const { managerKeyPair } = params;
+  const managerCount = await strandTableCount(db, 'Manager');
+  if (managerCount === 0) {
+    // Zero managers is NOT by itself a seal — a closed strand between its Header
+    // and Manager founding inserts looks identical. The retired `Manager` stamp is
+    // what separates "frozen forever" from "still foundable"; returning quietly on
+    // the latter would report a seal that never happened.
+    if (await strandHasManagerRevocation(db)) {
+      log('Strand already sealed (no Manager rows, manager stamp retired); skipping seal');
+      return;
+    }
+    throw new Error(
+      'Cannot seal: the strand holds no Manager row and has never retired one — it is '
+      + 'not founded yet, not sealed. Bootstrap the founding manager first.',
+    );
+  }
+  if (managerCount > 1) {
+    throw new Error(
+      `Cannot seal: ${managerCount} managers exist and sealing is the SOLE manager's act. `
+      + 'The other managers must step down first (removeManager).',
+    );
+  }
+  const self = await managerRow(db, managerKeyPair.publicKeyB64);
+  if (self == null) {
+    throw new Error('Cannot seal: the supplied keypair does not hold the sole Manager row.');
+  }
+  const signature = signStrandApproval(
+    ['Strand.Manager', 'seal', managerKeyPair.publicKeyB64, self.stampId],
+    managerKeyPair.privateKeyB64,
+  );
+  await inStrandTransaction(db, async () => {
+    await db.exec(
+      `delete from Strand.Manager
+         with context ManagerKey = ?, Signature = ?
+         where MemberKey = ?`,
+      [managerKeyPair.publicKeyB64, signature, managerKeyPair.publicKeyB64],
+    );
+    await insertRevocation(db, 'Manager', self.stampId, managerKeyPair);
+  });
+  log('Sealed strand: sole manager %s stepped down', managerKeyPair.publicKeyB64);
+}
+
+/**
+ * Whether the strand is `Type = 'c'` (closed). Reads the singleton `Header` via
+ * the same `db.eval` scan idiom as {@link strandTableCount}; a strand with no
+ * `Header` row yet reports `false`.
+ */
+async function strandIsClosed(db: Database): Promise<boolean> {
+  for await (const row of db.eval('select Type from Strand.Header')) {
+    return row.Type === 'c';
+  }
+  return false;
+}
+
+/**
+ * Whether the strand is sealed: a CLOSED strand that holds no `Manager` rows AND
+ * has retired at least one `Manager` stamp into `Strand.Revocation`.
+ *
+ * All three conjuncts are load-bearing:
+ * - `Header.Type` — an OPEN strand never holds `Manager` rows at all
+ *   (`Manager.OnlyClosed`), so a bare manager-count test would report every open
+ *   strand as sealed.
+ * - the manager count — sealing IS the empty `Manager` table.
+ * - the retired `Manager` stamp — "sealed" means admission is frozen FOREVER, and
+ *   what makes it permanent is the founding branch of `Manager.Authorized`
+ *   refusing to re-seat a generation-0 manager once any `Manager` stamp has been
+ *   retired. Without this conjunct a closed strand that is merely NOT FOUNDED YET
+ *   reads as sealed: {@link bootstrapFounderMembership} commits `Header`,
+ *   `Member` and `Manager` as three sequential statements, so the window between
+ *   the first and the last is exactly "closed, zero managers, still foundable".
+ *
+ * Reads locally visible rows — a node that has not yet converged on the seal
+ * still reports `false` (the schema's seal-propagation NOTE).
+ *
+ * @param db - The strand's database.
+ * @returns `true` iff the strand is closed, holds zero `Manager` rows, and has
+ *   permanently closed its founding branch.
+ */
+export async function isStrandSealed(db: Database): Promise<boolean> {
+  return await strandIsClosed(db)
+    && await strandTableCount(db, 'Manager') === 0
+    && await strandHasManagerRevocation(db);
+}

package/src/strand-solicitation.ts

@@ -41,7 +41,7 @@ export interface DisclosureValidator {
  * Discriminated result of resolving the host strand an invite binds to (responder side):
  *
  * - `unbound`: the invite carries no `StrandId` → the responder-provisions path (provision
- *   a NEW strand; legacy/open).
+ *   a NEW strand; unbound/open).
  * - `bound`: the invite names a host strand AND that strand row is present on this responder
  *   → provision-then-record (record consent against it, return it + its membership key).
  * - `missing`: the invite names a host strand but the row is ABSENT on this responder (e.g.
@@ -286,18 +286,17 @@ export class StrandSolicitationService {
    * This generates a member key, contacts the responder's cadre, and negotiates
    * strand formation.
    *
-   * @param invitation The open invitation (or just token for legacy API)
+   * @param invitation The open invitation
    * @param disclosure Identity/context information to share with the responder
    * @param node Optional libp2p node for real protocol handling
    * @returns The member key and strand info if successful
    */
   async formStrand(
-    invitation: OpenInvitation | string,
+    invitation: OpenInvitation,
     disclosure: StrandFormationDisclosure,
     node?: Libp2p
   ): Promise<FormStrandResult> {
-    // Handle legacy API where just token was passed
-    const token = typeof invitation === 'string' ? invitation : invitation.token;
+    const token = invitation.token;
     log('Forming strand with token: %s', token);
 
     // Generate a new keypair for this strand membership
@@ -310,8 +309,8 @@ export class StrandSolicitationService {
 
     log('Generated member key: %s', memberKey);
 
-    // If we have a full invitation and a node, use the real protocol
-    if (typeof invitation !== 'string' && node) {
+    // If we have a node, use the real protocol
+    if (node) {
       log('Using native cadre-core formation transport');
       const { privateKeyB64, publicKeyB64 } = ed25519KeyPairFromLibp2p(privateKey);
       const usageStampId = generateStampId(memberKey);

package/src/strand-wake-protocol.ts

@@ -44,9 +44,35 @@ export const WAKE_PROTOCOL = '/sereus/strand-wake/1.0.0';
  */
 const MAX_WAKE_SIZE = 64 * 1024;
 
-/** Default time to wait for the ack before abandoning a wake dial (ms). */
+/** Default time to wait for the ack before abandoning ONE wake dial attempt (ms). */
 const DEFAULT_WAKE_TIMEOUT_MS = 10_000;
 
+/**
+ * Default budget for a WHOLE {@link dialWake} call, in ms — every candidate
+ * address together, not each one.
+ *
+ * Without it the cost of a wake is (candidate count × {@link
+ * DEFAULT_WAKE_TIMEOUT_MS}), a number nothing chooses or bounds. That is not
+ * hypothetical: an address behind a dropped NAT mapping, or any host that
+ * blackholes rather than sending a RST, burns its full attempt timeout instead
+ * of failing in milliseconds, so a two-address peer costs 20 s and a
+ * five-address one costs 50 s.
+ *
+ * This makes the TARGET PEER the unit rather than the address — the same
+ * decision, for the same reason, as
+ * `DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS` in `control-cohort.ts`, and the same
+ * chosen number. 20 s is deliberately wider than one attempt timeout so a
+ * reachable peer whose signaling address is stale still gets a genuine try at
+ * its direct one; a peer needing longer than that is not "asleep and reachable",
+ * which is the only case a wake is for. The last attempt inside the budget gets
+ * whatever remains of it, so the call returns at the budget, not past it.
+ *
+ * Override per call with {@link DialWakeOptions.budgetMs} — tests that drive
+ * dead addresses on purpose set it low so a dial's duration is a chosen number
+ * rather than a transitive libp2p default stretched by machine load.
+ */
+export const DEFAULT_WAKE_DIAL_BUDGET_MS = 20_000;
+
 /** Default time the receiver waits for an inbound wake frame before aborting (ms). */
 const DEFAULT_WAKE_READ_TIMEOUT_MS = 10_000;
 
@@ -234,19 +260,45 @@ export class StrandWakeService {
 
 /** Options for {@link dialWake}. */
 export interface DialWakeOptions {
-  /** Per-dial timeout in ms (default {@link DEFAULT_WAKE_TIMEOUT_MS}). */
+  /** Per-ATTEMPT timeout in ms (default {@link DEFAULT_WAKE_TIMEOUT_MS}). */
   timeoutMs?: number;
+  /**
+   * Budget for the whole call — every candidate together (default
+   * {@link DEFAULT_WAKE_DIAL_BUDGET_MS}).
+   */
+  budgetMs?: number;
   /** Override the protocol id (defaults to {@link WAKE_PROTOCOL}). */
   protocolId?: string;
 }
 
+/** One candidate's outcome, kept so the thrown error can name every attempt. */
+interface WakeDialFailure {
+  addr: Multiaddr;
+  error: Error;
+}
+
 /**
  * Sender side: dial a target's control-network address(es), send a
  * {@link WakeRequest} over `WAKE_PROTOCOL`, and return the peer's {@link WakeAck}.
  *
  * Tries each candidate address in order (signaling/relay first, as produced by
  * `CadreNode.resolvePeerAddrs`) until one dials, so a NAT'd peer is reachable via
- * its circuit-relay address. Throws if no address is dialable.
+ * its circuit-relay address. Each attempt is bounded by `timeoutMs` and the call
+ * as a whole by `budgetMs` (see {@link DEFAULT_WAKE_DIAL_BUDGET_MS}); a candidate
+ * the budget leaves no room for is reported as untried rather than silently
+ * dropped.
+ *
+ * Throws if no address is dialable — with an error naming EVERY candidate and
+ * why it failed, not merely the last one. That distinction is not cosmetic:
+ * with only the last candidate's message the failure that mattered (usually the
+ * signaling address, tried first) is invisible outside a debug log, and the
+ * surfaced message points at whichever address happened to be tried last.
+ *
+ * The candidate loop is deliberately explicit rather than one
+ * `dialProtocol(addrs)` call. libp2p sorts any multi-address dial with
+ * `defaultAddressSorter`, whose `circuitRelayAddressesLast` pass would demote
+ * exactly the signaling address this ordering puts first — silently inverting
+ * it, with no per-dial sorter override to opt out of.
  */
 export async function dialWake(
   node: Libp2p,
@@ -259,23 +311,57 @@ export async function dialWake(
   }
   const protocolId = options.protocolId ?? WAKE_PROTOCOL;
   const timeoutMs = options.timeoutMs ?? DEFAULT_WAKE_TIMEOUT_MS;
+  const budgetMs = options.budgetMs ?? DEFAULT_WAKE_DIAL_BUDGET_MS;
+  const deadline = Date.now() + budgetMs;
 
-  let lastError: Error | null = null;
+  const failures: WakeDialFailure[] = [];
   for (const addr of addrs) {
+    // Whatever is left of the whole-call budget caps this attempt, so the last
+    // candidate inside the budget still gets a real (if shortened) try.
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) {
+      failures.push({ addr, error: new Error(`not tried — the ${budgetMs}ms wake dial budget was spent on earlier addresses`) });
+      continue;
+    }
+    const attemptMs = Math.min(timeoutMs, remaining);
     try {
       // One deadline per attempt: its signal aborts the in-flight dialProtocol and
       // resets the live stream, so neither the connect nor the ack-read leaks.
       return await withDeadline(
-        timeoutMs,
+        attemptMs,
         `Wake dial ${addr.toString()}`,
-        (signal) => sendWake(node, addr, protocolId, request, timeoutMs, signal),
+        (signal) => sendWake(node, addr, protocolId, request, attemptMs, signal),
       );
     } catch (err) {
-      lastError = err instanceof Error ? err : new Error(String(err));
+      failures.push({ addr, error: err instanceof Error ? err : new Error(String(err)) });
       log('Wake dial to %s failed: %o', addr.toString(), err);
     }
   }
-  throw lastError ?? new Error('Wake dial failed');
+  throw wakeDialError(failures);
+}
+
+/**
+ * Fold every candidate's failure into the one error {@link dialWake} throws.
+ *
+ * A single candidate throws its own error unchanged, so a one-address wake reads
+ * exactly as it always has (and `rejects.toThrow(/timed out/)` still means what
+ * it says). Several candidates produce one message naming each address and its
+ * cause, with the FIRST failure as `cause` — the first candidate is the
+ * signaling address, which is the one that matters when a relayed peer goes
+ * unreachable.
+ */
+function wakeDialError(failures: WakeDialFailure[]): Error {
+  if (failures.length === 0) {
+    return new Error('Wake dial failed');
+  }
+  if (failures.length === 1) {
+    return failures[0].error;
+  }
+  const detail = failures.map((f) => `${f.addr.toString()} — ${f.error.message}`).join('; ');
+  return new Error(
+    `Wake dial failed for all ${failures.length} candidate addresses: ${detail}`,
+    { cause: failures[0].error },
+  );
 }
 
 /**

package/src/types.ts

@@ -128,12 +128,12 @@ export const HIBERNATION_TIMEOUTS: Record<LatencyHint, HibernationTimeouts> = {
  * 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);
 
@@ -174,26 +174,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.
    *
-   * 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.
+   * **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.
    *
-   * 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.
+   * 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`.
+   *
+   * **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
@@ -201,18 +223,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[];
   /**
@@ -221,6 +251,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).
@@ -243,6 +283,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[]>;
   /**
@@ -368,8 +413,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