@serfab/cadre-core 0.11.0 → 0.13.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,15 @@ 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).
+ *
+ * Callers running inside a cadre runtime should follow this write with
+ * `CadreNode.refreshRevocationEnforcement(strandId)`. The removed party's
+ * machines are refused at the network layer by the strand's revoked-peer gate
+ * (`strand-revocation-enforcer.ts`), which polls for membership changes because
+ * this bare `Database` handle raises no event the runtime can hook — so without
+ * that call the cut lands up to one poll interval (default 30 s) later.
  *
  * @param db - The closed strand's database.
  * @param params - The revoking manager keypair and the target member key.
@@ -872,6 +914,11 @@ export interface LeaveStrandParams {
  * The same floors as {@link revokeMember} apply: a manager must resign first
  * (`NotAManager`) and the last member cannot leave (`MinOneMember`).
  *
+ * Like {@link revokeMember}, a caller inside a cadre runtime should follow this
+ * with `CadreNode.refreshRevocationEnforcement(strandId)` — here it is what
+ * makes the departing node notice its own departure promptly (the gate emits
+ * `strand:revoked` when it finds this node's own peer id revoked).
+ *
  * @param db - The closed strand's database.
  * @param params - The departing member's own keypair.
  * @throws If `Member.Authorized`, `Member.NotAManager`, or `Member.MinOneMember`
@@ -1172,7 +1219,17 @@ async function deleteOwnMemberPeer(db: Database, params: RemoveOwnPeerParams, st
   await insertRevocation(db, 'MemberPeer', stampId, memberKeyPair);
 }
 
-/** The manager branch: a manager signs the manager-remove-tagged digest + tombstone. */
+/**
+ * The manager branch: a manager signs the manager-remove-tagged digest + tombstone.
+ *
+ * NOTE: clearing an ORPHANED binding (one whose member was already removed) also
+ * forgets the NETWORK DENIAL of that peer id. The orphaned `MemberPeer` row IS
+ * the record the strand revoked-peer gate derives its deny set from
+ * (`strand-revocation-enforcer.ts`) — the `Strand.Revocation` tombstone keeps
+ * only the stamp, not the peer id — so once the orphan is cleared, remaining
+ * members' nodes resume answering and dialing that peer. Only clear a binding
+ * that should never have existed, or a peer that is truly gone.
+ */
 async function deleteMemberPeerByManager(
   db: Database,
   params: RemoveMemberPeerByManagerParams,
@@ -1382,13 +1439,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 +1460,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 +1482,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 +1503,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-network-config.ts

@@ -0,0 +1,172 @@
+/**
+ * Derive the per-STRAND-node view of the machine's one `NetworkConfig`.
+ *
+ * A cadre machine runs one **control** libp2p node plus one more libp2p node per
+ * strand, and every one of them is built from the SAME operator-written
+ * `NetworkConfig` block. Two of its fields describe a single endpoint on the host
+ * and therefore cannot be inherited literally by a second node on that host:
+ *
+ * - **`listenAddrs` with a fixed port.** `cadre-cli`'s example config ships
+ *   `/ip4/0.0.0.0/tcp/4001`. The control node binds it first; every strand node
+ *   then tries to bind the same port and fails with `EADDRINUSE`, so a machine
+ *   configured with a fixed port could not start any strand at all.
+ * - **`announceAddrs` / `appendAnnounceAddrs`.** Any concrete announce entry names
+ *   a port, and that port is the CONTROL node's. A strand node advertising it
+ *   sends peers to the control node — and `announceAddrs` REPLACES the advertised
+ *   set (see `announce-addrs.ts`), so that wrong address would be the ONLY thing
+ *   the strand node publishes.
+ *
+ * The reachability model this rests on: **a strand node is not separately dialable
+ * at a published fixed address.** It is reached through (a) its ephemeral direct
+ * listener plus the addresses peers observe for it, and (b) circuit relay —
+ * `network.relayAddrs` resolves to per-relay `<relay>/p2p-circuit` listen entries
+ * that strand nodes DO inherit correctly, because the port inside such an entry is
+ * the relay's, not a local bind (`relay-addrs.ts`).
+ *
+ * Everything else in `NetworkConfig` — `relayAddrs`, `transports`,
+ * `connectionGater`, `enableRelay` — is inherited by the caller; this module
+ * only owns the two host-endpoint fields above. One caveat on `connectionGater`:
+ * an OPEN strand's node gets it unchanged, while a CLOSED strand's node composes
+ * revoked-peer denial onto it in `strand-instance-manager.ts` (every supplied
+ * hook still honored — see `strand-revocation-enforcer.ts`).
+ *
+ * It does carry one non-address option out with them: the WebSocket transport switch
+ * a `/ws` listen entry implies (`relay-addrs.ts` → `resolveTransportOptions`). That is
+ * DERIVED from the listen entries rather than inherited, so it has to be computed
+ * wherever they are, and a strand node whose listen entries reached libp2p without it
+ * would bind no WebSocket listener and report nothing.
+ */
+
+import { multiaddr, type Component } from '@multiformats/multiaddr';
+import { resolveListenAddrs, resolveTransportOptions } from './relay-addrs.js';
+import type { NetworkConfig } from './types.js';
+
+/**
+ * The address-shaped `createLibp2pNode` options a strand node gets, ready to spread
+ * into the rest of its options.
+ *
+ * There is deliberately no announce field here: a strand node announces NOTHING the
+ * operator configured, only what libp2p derives for it (its own listeners, observed
+ * addresses, and any `/p2p-circuit` address a relay reservation earns).
+ *
+ * NOTE: accepted tradeoff — a hosted deployment that wants a strand node reachable
+ * at its own published public port has no way to say so; the announce config is
+ * dropped for strand nodes wholesale rather than per-strand. Nothing needs that
+ * today, and the alternative is a per-strand network-config surface. Revisit if a
+ * hosted or reverse-proxy deployment ever needs direct-dialable strand nodes.
+ */
+export interface StrandNodeAddrs {
+  /**
+   * Listen entries for this strand node, or `undefined` when the operator
+   * configured neither `listenAddrs` nor `relayAddrs` — in which case the caller
+   * omits the option and inherits `@optimystic/db-p2p`'s own default.
+   */
+  listenAddrs?: string[];
+  /**
+   * The WebSocket transport switch those listen entries imply, present only when one
+   * of them names WebSocket (`relay-addrs.ts` → `resolveTransportOptions`). Not an
+   * address — it is deliberately `0` and nothing binds it — but it lives here because
+   * it is derived from, and must travel with, the listen entries above. Without it a
+   * `/ws` strand listen entry binds nothing and libp2p reports nothing.
+   */
+  wsPort?: number;
+}
+
+/**
+ * The strand-node view of `network`: the control node's resolved listen entries with
+ * every fixed direct port rewritten to an ephemeral one, and no announce fields.
+ *
+ * Validation is unchanged and still fail-fast — `resolveListenAddrs` throws here on a
+ * malformed `relayAddrs` entry exactly as it does for the control node.
+ *
+ * NOTE: announce entries are no longer validated on this path at all; the CONTROL
+ * node's own build (`cadre-node.ts`) is the only thing that parses them, and it runs
+ * before any strand starts, so a typo still refuses node start today. That is an
+ * ORDERING guarantee, not a structural one. Revisit if a strand node is ever built
+ * before the control node's libp2p options are resolved — a malformed announce entry
+ * would then go unreported until the control node's own build.
+ */
+export function strandNodeAddrs(network: NetworkConfig | undefined): StrandNodeAddrs {
+  // The default `'configured'` relay route, deliberately NOT the control node's
+  // `'search'` route: nothing drives an explicit reservation for a strand node, so a
+  // bare `/p2p-circuit` search entry would register a pending reservation nobody fills
+  // and leave every NAT'd strand node undialable. See `relay-addrs.ts`.
+  const listenAddrs = resolveListenAddrs(network);
+  if (!listenAddrs) {
+    return {};
+  }
+  // An explicitly empty `listenAddrs` (the React Native "cannot listen" case) stays
+  // empty — rewriting must never resurrect a direct listener that was opted out of.
+  const rewritten = dedupe(listenAddrs.map(ephemeralPortListenAddr));
+  // Classified AFTER the ephemeral rewrite, so the check reads what this strand node
+  // will actually bind. Zeroing a port cannot change an entry's transport — only the
+  // `tcp`/`udp` component's value moves — so `/ip4/0.0.0.0/tcp/4002/ws` still resolves
+  // to WebSocket as `/ip4/0.0.0.0/tcp/0/ws`.
+  return { listenAddrs: rewritten, ...resolveTransportOptions(network, rewritten) };
+}
+
+/**
+ * One listen entry with its fixed direct port rewritten to `0`, so the OS assigns a
+ * free one per node. Interface and transport choices are preserved — `/ws`, a
+ * specific-interface bind, a `/udp/…/quic-v1` stack — since only the port is
+ * contended.
+ *
+ * Passed through UNCHANGED when there is nothing to rewrite, so the operator's exact
+ * string survives rather than being round-tripped through the multiaddr normalizer:
+ *
+ * - a circuit entry (`…/p2p-circuit`), whose embedded port belongs to the RELAY and
+ *   is not a local bind at all;
+ * - a port that is already `0`, or an entry that names no port;
+ * - an unparsable entry — libp2p reports a bad listen addr itself, and this helper
+ *   only ever narrows a port.
+ */
+function ephemeralPortListenAddr(listenAddr: string): string {
+  let components: Component[];
+  try {
+    components = multiaddr(listenAddr).getComponents();
+  } catch {
+    return listenAddr;
+  }
+  if (components.some((c) => c.name === 'p2p-circuit')) {
+    return listenAddr;
+  }
+  if (!components.some(isFixedPort)) {
+    return listenAddr;
+  }
+  return multiaddr(components.map(withEphemeralPort)).toString();
+}
+
+/** A `tcp`/`udp` component naming a port the OS did not choose. */
+function isFixedPort(component: Component): boolean {
+  return (component.name === 'tcp' || component.name === 'udp')
+    && component.value !== undefined
+    && component.value !== '0';
+}
+
+/**
+ * `component` with its port zeroed, or unchanged when it is not a fixed port.
+ *
+ * Rebuilt field-by-field rather than spread: a parsed component may carry a `bytes`
+ * cache, and `componentsToBytes` PREFERS that cache over `value` — a spread would
+ * re-encode the old port.
+ */
+function withEphemeralPort(component: Component): Component {
+  return isFixedPort(component)
+    ? { code: component.code, name: component.name, value: '0' }
+    : component;
+}
+
+/**
+ * Exact-string dedupe, first occurrence wins — matching `relay-addrs.ts`. Entries
+ * that differed only by port collapse into one after the rewrite, and libp2p would
+ * otherwise try to bind the same ephemeral-port entry twice.
+ *
+ * NOTE: an operator who writes two fixed ports on the same interface and transport
+ * (`/ip4/0.0.0.0/tcp/4001` and `…/tcp/4002`) gets ONE strand listener, not two, since
+ * the two entries are identical once zeroed. Intended — the ports were the only thing
+ * distinguishing them and neither survives. Revisit if a deployment ever needs a
+ * strand node to hold a fixed count of direct listeners.
+ */
+function dedupe(addrs: readonly string[]): string[] {
+  return [...new Set(addrs)];
+}