@serfab/cadre-core 0.12.0 → 1.0.0

package/src/enrolled-machine-store-file.ts

@@ -0,0 +1,43 @@
+/**
+ * Node-only file-backed {@link EnrolledMachineStore}: one JSON file per party under
+ * a configured directory (the node's state directory — `cadre-cli` passes
+ * `ResolvedConfig.nodeStateDir`), holding the node-local, non-replicated count of
+ * machines this party had enrolled the last time this node looked.
+ *
+ * Nothing but the file itself lives here: the envelope, the cold-start-on-anything
+ * load policy (deliberately NOT the throw-on-unreadable policy its two sibling
+ * records use — see the `enrolled-machine-store.ts` module comment) and the
+ * serialised writes are cross-platform in `PersistentEnrolledMachineStore`, and the
+ * file is a `FileDurableSlot`. This module exists only so the `node:fs` edge stays
+ * out of the package's cross-platform default entry (`./index.js`) — import it from
+ * the dedicated subpath instead:
+ *
+ * ```ts
+ * import { FileEnrolledMachineStore } from '@serfab/cadre-core/enrolled-machine-store-file';
+ * ```
+ *
+ * A React Native / browser entry graph never resolves this path, so the `node:fs`
+ * edge never reaches a bundler that cannot satisfy it (same isolation pattern as
+ * `bootstrap-peer-store-file.ts` / `trusted-owner-store-file.ts` / `key-store-file.ts`).
+ */
+import { FileDurableSlot } from './file-durable-slot.js';
+import { PersistentEnrolledMachineStore } from './enrolled-machine-store.js';
+import type { EnrolledMachineStore } from './enrolled-machine-store.js';
+
+/** Base name of the store file: `<dir>/enrolled-machines.<encoded partyId>.json`. */
+const SLOT_NAME = 'enrolled-machines';
+
+/**
+ * File-backed {@link EnrolledMachineStore}. Open via {@link open}, which loads the
+ * existing file and returns the cross-platform store over it. An absent, corrupt,
+ * wrong-party, junk-valued **or unreadable** file is a cold start (`count()` is
+ * `undefined`, the node declares no repair yardstick and runs at the base control
+ * policy) — `open` never rejects, unlike the sibling stores' file backends. That
+ * divergence and its reasoning live on `enrolled-machine-store.ts`.
+ */
+export const FileEnrolledMachineStore = {
+	/** Load (or cold-start) the party's last recorded machine count from a file in `dir`. */
+	async open(dir: string, partyId: string): Promise<EnrolledMachineStore> {
+		return PersistentEnrolledMachineStore.open(new FileDurableSlot(dir, SLOT_NAME, partyId), partyId);
+	}
+};

package/src/enrolled-machine-store.ts

@@ -0,0 +1,280 @@
+/**
+ * Node-local, NON-replicated record of how many machines this party had enrolled
+ * the last time this node looked — the block-repair corroboration yardstick the
+ * CONTROL network declares when its libp2p node is built.
+ *
+ * ## Why the number has to be remembered rather than read
+ *
+ * `resolveRepairYardstick` (in `@serfab/quereus-plugin-sereus`'s `cluster-size.ts`
+ * — read it first; the arithmetic and both clamps are explained there and are not
+ * repeated here) derives the yardstick from the machines that SERVE the network being
+ * configured. For the CONTROL network that is the machines enrolled in the party, and
+ * exactly so: every enrolled machine runs the control node by construction. (It is NOT
+ * the right number for a strand, which runs on a subset — see
+ * `StartStrandConfig.servingMachines`. This store is control-network-only, and that
+ * scope is a safety property, not an accident.) Optimystic freezes a network's
+ * `clusterPolicy` when its libp2p node is built and offers no runtime setter, so the
+ * number has to be known at construction time.
+ *
+ * The control node cannot read it when it needs it. `CadreNode.buildControlNodeOptions`
+ * runs inside `start()` BEFORE `createControlNode()`, which is before the
+ * `ControlDatabase` holding the `CadrePeer` rows exists — so at the one moment the
+ * number is needed, nothing can answer. That deadlock is why the control network
+ * declared no yardstick at all and ran at `CONTROL_CLUSTER_POLICY`'s
+ * `assumedClusterSize` of 2.
+ *
+ * This store breaks it the only way a chicken-and-egg is broken: by remembering
+ * across the restart. `CadreNode.refreshAuthorizedControlPeers` records the count
+ * every time membership is recomputed; `CadreNode.start()` reads it back before the
+ * control node is built. A node therefore declares what it last knew, and a party
+ * that grows applies the larger number on each node's NEXT launch. Raising the
+ * yardstick is the safe direction and a node still holding the old value is running
+ * at exactly today's behaviour, so the next natural restart is soon enough — there
+ * is deliberately no forced rebuild.
+ *
+ * ## Why this is NOT a `NodeLocalSnapshot` like its two siblings
+ *
+ * The trusted-owner anchor (`trusted-owner-store.ts`) and the cold-start
+ * bootstrap-peer store (`bootstrap-peer-store.ts`) are the same `{ version,
+ * partyId, ... }` envelope over a {@link DurableSlot} this record is, and this
+ * module is deliberately symmetrical with them — same injected-backend shape, same
+ * `Memory*` / `Persistent*` / `File*` split, same party scoping. It does NOT share
+ * their `NodeLocalSnapshot` machinery, for two reasons:
+ *
+ *  - **Shape.** `NodeLocalSnapshot` is a `key -> entry` map. This record is one
+ *    integer that must be able to go DOWN after a machine is removed.
+ *  - **Load policy — the important one.** `NodeLocalSnapshot.open` THROWS when the
+ *    slot is present but unreadable. That is right for the anchor (a record that
+ *    cannot be read in full is not a trust anchor) and right for the peer store (a
+ *    failed read reported as absent would let the next snapshot write destroy a
+ *    stranded node's only way home). It is WRONG here. Nothing in this record is
+ *    trust-bearing, it holds nothing that is not recomputed the moment the control
+ *    database is up, and refusing to start a node over an unreadable *repair hint*
+ *    is strictly worse than declaring today's 2. So every unreadable, unparsable,
+ *    foreign-party or junk slot LOGS and COLD-STARTS, yielding `undefined`, which
+ *    declares nothing, which is byte-for-byte today's behaviour.
+ *
+ * Do not "unify" the three modules by routing this one through `NodeLocalSnapshot`:
+ * that would quietly import the throw, and turn an unreadable hint into a node that
+ * will not start.
+ *
+ * NOTE: writes are serialised in-process only, the same caveat `NodeLocalSnapshot`
+ * carries. Two processes (or two browser tabs) sharing ONE slot for ONE party each
+ * write their own view and the loser's count is lost. Two same-origin tabs of
+ * `reference-app-web` do exactly that — its slot is one key of a shared IndexedDB
+ * database, the same last-writer-wins caveat its `node-local-slots.ts` already
+ * records for the other two records. Harmless here, unlike there: this value is one
+ * integer both tabs re-derive from the same membership rows on their next refresh,
+ * so the views reconverge rather than losing an entry nobody rewrites.
+ */
+import debug from 'debug';
+import type { DurableSlot } from './node-local-snapshot.js';
+
+const log = debug('sereus:cadre:enrolled-machine-store');
+
+/** Envelope version. Guards future migrations; an unknown version cold-starts. */
+const ENVELOPE_VERSION = 1;
+
+/** Envelope property holding the count. */
+const PAYLOAD_KEY = 'enrolledMachines';
+
+export interface EnrolledMachineStore {
+	/** Party this store is scoped to. */
+	readonly partyId: string;
+
+	/**
+	 * Machines last recorded for this party, or `undefined` when nothing usable was
+	 * ever recorded — a brand-new node, or a slot that could not be read. Callers
+	 * pass this straight to `controlClusterPolicy`, whose `undefined` branch returns
+	 * the frozen base policy unchanged, so "this node does not know" and "this node
+	 * has never run" are the same declaration: none.
+	 */
+	count(): number | undefined;
+
+	/**
+	 * Record the current count. Reflected by {@link count} SYNCHRONOUSLY; the
+	 * returned promise resolves once the persist attempt has settled.
+	 *
+	 * **Never rejects.** Its sole caller is
+	 * `CadreNode.refreshAuthorizedControlPeers`, whose contract is never-rejects and
+	 * which leaves the promise un-awaited (`void`) — so a rejection here would
+	 * surface as an unhandled rejection in the embedder's process, over a hint that
+	 * re-lands on the next refresh anyway. A failed persist is LOGGED, and the
+	 * in-memory count stays correct for this session.
+	 *
+	 * A count that is not a positive integer is a caller bug: it is logged and
+	 * IGNORED rather than persisted, so a degenerate value can never reach the slot
+	 * and be read back as a declaration nobody chose.
+	 */
+	record(count: number): Promise<void>;
+}
+
+/**
+ * Ephemeral in-memory store — the default when no store is injected via
+ * `CadreNodeConfig.enrolledMachines`. A node using this cold-starts on every
+ * launch: `count()` is `undefined` at `start()`, so its control node declares
+ * nothing and runs at today's behaviour, exactly as before this record existed.
+ */
+export class MemoryEnrolledMachineStore implements EnrolledMachineStore {
+	private current: number | undefined;
+
+	constructor(readonly partyId: string) {}
+
+	count(): number | undefined {
+		return this.current;
+	}
+
+	async record(count: number): Promise<void> {
+		const accepted = asMachineCount(count);
+		if (accepted === undefined) {
+			log('refusing to record a non-positive-integer count %o for party %s', count, this.partyId);
+			return;
+		}
+		this.current = accepted;
+	}
+}
+
+/**
+ * Durable {@link EnrolledMachineStore} over an app-supplied {@link DurableSlot} —
+ * the cross-platform half of every persistent backend (the Node
+ * `FileEnrolledMachineStore` is this class over a file slot).
+ *
+ * Construct via {@link open}. Load policy is the module comment's: every failure
+ * mode cold-starts, and `open` never rejects.
+ */
+export class PersistentEnrolledMachineStore implements EnrolledMachineStore {
+	/** Serialises persists so the last count recorded is the last one written. */
+	private writeChain: Promise<void> = Promise.resolve();
+	/** Last count accepted, whether or not it has reached the slot yet. */
+	private current: number | undefined;
+	/** Last count believed to BE in the slot; drives the unchanged-write skip. */
+	private persisted: number | undefined;
+
+	private constructor(
+		private readonly slot: DurableSlot,
+		readonly partyId: string,
+		loaded: number | undefined
+	) {
+		this.current = loaded;
+		this.persisted = loaded;
+	}
+
+	/** Load (or cold-start) the party's last recorded machine count from `slot`. */
+	static async open(slot: DurableSlot, partyId: string): Promise<PersistentEnrolledMachineStore> {
+		return new PersistentEnrolledMachineStore(slot, partyId, await loadCount(slot, partyId));
+	}
+
+	count(): number | undefined {
+		return this.current;
+	}
+
+	/**
+	 * Record the count: visible via {@link count} synchronously, then persisted.
+	 *
+	 * Writes are SKIPPED when the slot already holds this number, because the sole
+	 * caller runs on every committed membership write *and* every timed reconcile
+	 * pass — a party whose membership is stable would otherwise rewrite the same
+	 * integer forever. The skip is keyed off {@link persisted} rather than
+	 * {@link current}, so a write that FAILED is retried by the next refresh instead
+	 * of being suppressed as "unchanged".
+	 */
+	record(count: number): Promise<void> {
+		const accepted = asMachineCount(count);
+		if (accepted === undefined) {
+			log('refusing to record a non-positive-integer count %o for party %s', count, this.partyId);
+			return Promise.resolve();
+		}
+		this.current = accepted;
+		if (this.persisted === accepted) {
+			return Promise.resolve();
+		}
+		this.writeChain = this.writeChain.then(() => this.persistCurrent());
+		return this.writeChain;
+	}
+
+	/**
+	 * Write whatever {@link current} holds when this link of the chain runs — so a
+	 * burst of records collapses into one write of the latest value — and never
+	 * throw (see {@link EnrolledMachineStore.record}).
+	 */
+	private async persistCurrent(): Promise<void> {
+		const pending = this.current;
+		if (pending === undefined || pending === this.persisted) {
+			return;
+		}
+		const envelope = {
+			version: ENVELOPE_VERSION,
+			partyId: this.partyId,
+			[PAYLOAD_KEY]: pending
+		};
+		try {
+			await this.slot.save(JSON.stringify(envelope, null, '\t'));
+			this.persisted = pending;
+			log('recorded %d enrolled machine(s) for party %s', pending, this.partyId);
+		} catch (error) {
+			log(
+				'persisting %d enrolled machine(s) for party %s failed (in-memory count stands, retried on the next refresh): %o',
+				pending, this.partyId, error
+			);
+		}
+	}
+}
+
+/**
+ * A usable machine count, or `undefined`. Anything that is not a positive integer
+ * is unknown rather than coerced — `'3'`, `0`, `-1`, `2.5`, `null` and a missing key
+ * all cold-start. Coercing here would be the beginning of a parser, and Optimystic
+ * itself treats a degenerate declaration as absent, so a rounded value would be a
+ * number nobody chose.
+ */
+function asMachineCount(value: unknown): number | undefined {
+	return typeof value === 'number' && Number.isInteger(value) && value >= 1 ? value : undefined;
+}
+
+/**
+ * Read the slot into the initial count. EVERY failure — unreadable slot, unparsable
+ * JSON, wrong envelope version, foreign `partyId`, junk payload — logs and returns
+ * `undefined` (see the module comment for why this record, unlike its two siblings,
+ * must not throw on an unreadable slot).
+ */
+async function loadCount(slot: DurableSlot, partyId: string): Promise<number | undefined> {
+	let text: string | undefined;
+	try {
+		text = await slot.load();
+	} catch (error) {
+		// The deliberate divergence from `NodeLocalSnapshot.open`, which throws here.
+		log('slot for party %s is present but unreadable (cold start — this node declares no yardstick): %o', partyId, error);
+		return undefined;
+	}
+	if (text === undefined) {
+		return undefined;
+	}
+
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text);
+	} catch (error) {
+		log('corrupt slot for party %s (cold start): %o', partyId, error);
+		return undefined;
+	}
+
+	if (!isRecord(parsed) || parsed.version !== ENVELOPE_VERSION || parsed.partyId !== partyId) {
+		// A non-string partyId cannot equal the requested one, so this covers both a
+		// malformed envelope and a slot reused for another party.
+		log('slot for party %s has an unknown shape or a foreign partyId (cold start)', partyId);
+		return undefined;
+	}
+
+	const count = asMachineCount(parsed[PAYLOAD_KEY]);
+	if (count === undefined) {
+		log('slot for party %s holds an unusable %s value %o (cold start)', partyId, PAYLOAD_KEY, parsed[PAYLOAD_KEY]);
+		return undefined;
+	}
+	log('loaded %d enrolled machine(s) for party %s', count, partyId);
+	return count;
+}
+
+/** A plain JSON object. Arrays excluded: an array envelope is not an envelope. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/file-durable-slot.ts

@@ -5,9 +5,11 @@
  * parties without cross-party leakage.
  *
  * This is the whole platform-specific part of the file-backed node-local
- * stores (`trusted-owner-store-file.ts`, `bootstrap-peer-store-file.ts`); the
- * load policy, envelope and write chain are cross-platform in
- * `node-local-snapshot.ts`. Like its two importers, this module imports
+ * stores (`trusted-owner-store-file.ts`, `bootstrap-peer-store-file.ts`,
+ * `enrolled-machine-store-file.ts`); the load policy, envelope and write chain
+ * are cross-platform — in `node-local-snapshot.ts` for the first two, and in
+ * `enrolled-machine-store.ts` for the third, which deliberately does not share
+ * that machinery. Like its three importers, this module imports
  * `node:fs/promises`, so it is kept OUT of the package's cross-platform
  * default entry and is not itself an exported subpath.
  */

package/src/index.ts

@@ -8,7 +8,7 @@ export { canonicalJson } from './canonical-json.js';
 export { CadreNode } from './cadre-node.js';
 
 // Control database
-export { ControlDatabase, MissingHostStrandError, buildAuthorizationMessage, formationVouchMessage, formationConsentMessage, REAPABLE_TABLES, type ReapableTable, type ControlDatabaseConfig, type ControlTable, type RevocableTable, type FormationUsageResult, type MembershipChangeListener, type GuardedDeleteListener, type RevokedRowRef } from './control-database.js';
+export { ControlDatabase, MissingHostStrandError, buildAuthorizationMessage, formationVouchMessage, formationConsentMessage, REAPABLE_TABLES, type ReapableTable, type ControlDatabaseConfig, type ControlTable, type RevocableTable, type FormationUsageResult, type MembershipChangeListener, type GuardedDeleteListener, type ControlWriteAbandonedListener, type RevokedRowRef } from './control-database.js';
 
 // Bounded retry for transient control-write failures (classifier + loop behind
 // ControlDatabase.lockedWithRetry; exported so the integration package can drive the
@@ -35,6 +35,15 @@ export {
   type ControlReadRetryOptions
 } from './control-read-retry.js';
 
+// The bounded retry loop both control policies share. Only the abandonment record leaves
+// this package: it is the payload of the `control:write-abandoned` node event, so an
+// embedding app can type a handler for it.
+export type {
+  ControlRetryAbandonment,
+  ControlRetryAbandonReason,
+  ControlRetryAbandonListener
+} from './control-retry.js';
+
 // Control-plane authorization field vector (the domain/action tagging every signer shares)
 export { controlAuthorizationFields, type ControlDomain, type ControlAction } from './control-authorization.js';
 
@@ -94,6 +103,25 @@ export {
   type BootstrapPeerEntry
 } from './bootstrap-peer-store.js';
 
+// Node-local enrolled-machine count: the machines this party had enrolled the
+// last time this node looked, remembered across restarts so the CONTROL node can
+// declare a block-repair yardstick at bring-up — which is before the database
+// holding the membership rows exists. Same cross-platform split as the two
+// records above; Node-only file backend behind the subpath
+// '@serfab/cadre-core/enrolled-machine-store-file'. Its load policy deliberately
+// DIVERGES from theirs (an unreadable slot cold-starts rather than throwing) —
+// see the module comment before unifying the three.
+export {
+  MemoryEnrolledMachineStore,
+  PersistentEnrolledMachineStore,
+  type EnrolledMachineStore
+} from './enrolled-machine-store.js';
+
+// Storage scope keys — what `CadreNodeConfig.storage.provider` is called with. A
+// strand's key is its strand id; the control database's key carries the party id,
+// so two parties on one device never share a control store.
+export { controlStorageScope, isControlStorageScope } from './storage-scope.js';
+
 // Strand database
 export { StrandDatabase, type StrandDatabaseConfig } from './strand-database.js';
 
@@ -109,20 +137,71 @@ export {
   StrandInstanceManager,
   type StartStrandConfig,
   type ResumeStrandOverrides,
-  getStrandStoragePath
+  getStrandStoragePath,
+  isAwaitingFirstSync,
+  liveStrandStatus
 } from './strand-instance-manager.js';
 
-// Strand peer-join block catch-up (push this strand's own blocks to each newly
-// connected strand peer, so a late joiner physically holds pre-join blocks).
+// The joining machine's first-sync write gate: a non-founder launch withholds its
+// database (status 'syncing') until the strand's Header has arrived from a peer, so a
+// write before the first sync can never fork the strand's tables.
+export {
+  StrandAwaitingFirstSyncError,
+  DEFAULT_STRAND_FIRST_SYNC_TIMEOUT_MS,
+  DEFAULT_STRAND_FIRST_SYNC_POLL_MS,
+  strandHeaderHeld,
+  appTablesReadable,
+  strandFirstSyncComplete,
+  type StrandFirstSyncConfig
+} from './strand-first-sync-gate.js';
+
+// Peer-join block catch-up (push this network's own blocks to each newly
+// connected peer, so a late joiner physically holds pre-join blocks). Shared
+// by the strand networks (ungated) and the control network (membership-gated).
 export {
-  StrandBackfill,
-  DEFAULT_STRAND_BACKFILL,
+  PeerJoinBackfill,
+  DEFAULT_PEER_JOIN_BACKFILL,
   MAX_BLOCK_MESSAGE_BYTES,
-  type StrandBackfillConfig,
-  type StrandBackfillDeps,
-  type StrandBackfillResult,
-  type StrandBackfillPushClient
-} from './strand-backfill.js';
+  type PeerJoinBackfillConfig,
+  type PeerJoinBackfillDeps,
+  type PeerJoinBackfillResult,
+  type PeerJoinBackfillPushClient
+} from './peer-join-backfill.js';
+
+// Closed-strand revoked-peer enforcement (deny the network nodes of removed
+// members at the stream and connection layers, and hang up the sessions they
+// already hold — see the module doc for the settled deny-list design, the
+// teardown seam, and the fail directions).
+export {
+  StrandRevocationEnforcer,
+  createRevocationConnectionGater,
+  readStrandRevocationRows,
+  DEFAULT_REVOCATION_POLL_INTERVAL_MS,
+  type StrandRevocationEnforcementConfig,
+  type StrandRevocationEnforcerDeps,
+  type StrandRevocationRows,
+  type StrandMemberPeerBinding,
+  type StrandRevocationJudge,
+  type StrandRevocationNetwork,
+  type RevocationRefreshScheduler
+} from './strand-revocation-enforcer.js';
+
+// Closed-strand membership reconciliation: the bring-up loop that finishes a
+// party's join on every machine — redeem the staged formation invitation, then
+// write the durable machine→party MemberPeer binding — without ever blocking
+// bring-up (see the module doc for the pass ladder and terminal states).
+export {
+  StrandMembershipReconciler,
+  IDLE_PASSES_BEFORE_ESCALATION,
+  INITIAL_JOIN_RETRY_INTERVAL_MS,
+  type StrandMembershipReconcilerDeps,
+  type StrandMembershipReconciliationConfig,
+  type PendingMembershipInviteSource
+} from './strand-membership-reconciler.js';
+
+// The timer seam the self-rescheduling strand bring-up loops share (first-sync gate
+// probe loop, membership retry ladder) — injected by tests as a hand-cranked clock.
+export { defaultTimeoutScheduler, type TimeoutScheduler } from './timeout-scheduler.js';
 
 // Hibernation
 export {
@@ -187,8 +266,11 @@ export {
   signStrandApproval,
   generateStrandStampId,
   bootstrapFounderMembership,
+  PreSplitStrandIdentityError,
   issueInvite,
   consumeInvite,
+  burnInvite,
+  isStrandMember,
   cancelInvite,
   listOutstandingInvites,
   addMemberByManager,
@@ -202,6 +284,7 @@ export {
   removeManager,
   sealStrand,
   isStrandSealed,
+  StrandTransactionBusyError,
   STRAND_ENGINE,
   STRAND_ENGINE_VERSION,
   type FounderBootstrapParams,
@@ -220,7 +303,8 @@ export {
   type AddManagerParams,
   type AdmitManagerParams,
   type RemoveManagerParams,
-  type SealStrandParams
+  type SealStrandParams,
+  type StrandWriteOptions
 } from './strand-membership-writer.js';
 
 // Engine-canonical datetime helper (shared by control + strand signed-write flows
@@ -334,12 +418,25 @@ export {
 // the cadence/degree defaults the proactive reconcile routine reads.
 export {
   selectControlCohortDials,
-  DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS,
   DEFAULT_CONTROL_COHORT_RECONCILE_MS,
   DEFAULT_CONTROL_COHORT_TARGET_DEGREE,
-  type ControlCohortSelection
+  type ControlCohortSelection,
+  type ControlCohortReconcileResult
 } from './control-cohort.js';
 
+// Dialing one peer from several candidate addresses, each under its own time
+// limit, so an address that never answers cannot starve the rest.
+export {
+  dialPeerAddrs,
+  tryAddrsInTurn,
+  directBeforeRelayed,
+  DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS,
+  DEFAULT_CONTROL_COHORT_PER_ADDRESS_DIAL_TIMEOUT_MS,
+  DEFAULT_PEER_DIAL_BUDGET,
+  type PeerDialBudget,
+  type AddrDialer
+} from './peer-dial.js';
+
 // Seed trust policy (trust anchor for incoming seeds)
 export {
   anchoredTrustPolicy,
@@ -363,6 +460,8 @@ export {
   FormationListener,
   dialFormation,
   isValidResponderCreatesResult,
+  isWellFormedMembershipInvite,
+  sanitizeStrandAddrs,
   FORMATION_PROTOCOL,
   type FormationParty,
   type FormationContactMessage,
@@ -372,6 +471,7 @@ export {
   type FormationDbConnectionInfo,
   type FormationListenerOptions,
   type FormationDialOptions,
+  type FormationDialResult,
   type ResponderProvisionOutcome
 } from './strand-formation-protocol.js';
 
@@ -379,6 +479,9 @@ export {
 export {
   StrandFormationManager,
   createStrandFormationManager,
+  MEMBERSHIP_INVITE_TTL_MS,
+  MEMBERSHIP_INVITE_UNAVAILABLE_REASON,
+  HOST_STRAND_MUST_BE_RECREATED_REASON,
   type StrandFormationManagerConfig,
   type StrandFormationManagerOptions
 } from './strand-formation-manager.js';
@@ -400,7 +503,23 @@ export {
 // Thrown out of `CadreNode.start()` when a `network.relayAddrs` reservation does
 // not land on its first attempt — the fail-fast posture of that config field now
 // that the control node reserves AFTER control-database bring-up (relay-addrs.ts).
-export { RelayReservationFailedError, RELAY_SEARCH_LISTEN_ADDR } from './relay-addrs.js';
+// `UnbindableListenAddressError` is the same posture for the OTHER half of the listen
+// config: a `network.listenAddrs` entry whose transport the node will not have refuses
+// start instead of being silently dropped by libp2p's transport manager.
+//
+// `resolveListenAddrs` and `strandNodeAddrs` are the derivations themselves — what a
+// `NetworkConfig` actually turns into for the control node and for each strand node.
+// Exported so an embedder that hand-writes a `network` block (the React Native and web
+// reference apps) can assert on the resulting SHAPE rather than on its own field names,
+// which is the difference between a test that proves reachability and one that proves a
+// spelling.
+export {
+  RelayReservationFailedError,
+  UnbindableListenAddressError,
+  RELAY_SEARCH_LISTEN_ADDR,
+  resolveListenAddrs
+} from './relay-addrs.js';
+export { strandNodeAddrs, type StrandNodeAddrs } from './strand-network-config.js';
 
 // Relay reservation via the bare `/p2p-circuit` search listener — the one route
 // every control node takes; `network.relayAddrs` is its fail-fast posture

package/src/membership-connection-gater.ts

@@ -367,7 +367,11 @@ export class UnauthorizedReservationBudget {
  * dialer sees its "open" connection close moments later.
  *
  * Control node only: strand cohort nodes legitimately connect cross-party
- * peers, so `CadreNode` threads the raw configured gater to them unchanged.
+ * peers, so cadre membership never gates them. An OPEN strand's node receives
+ * the raw configured gater unchanged; a CLOSED strand's node composes its own
+ * revoked-peer denial onto it instead — a deny-list on positive revocation
+ * evidence, not this module's membership admission — see
+ * `strand-revocation-enforcer.ts`.
  */
 export function createMembershipConnectionGater(
   policy: InboundAdmissionPolicy,
@@ -440,9 +444,11 @@ export function createMembershipConnectionGater(
  * fail-open outcome) if it has not settled in time — see
  * {@link ADMISSION_DECISION_TIMEOUT_MS} for why an unbounded await is not safe
  * on the connection hook. The timer is always cleared so a decided call never
- * holds the event loop open.
+ * holds the event loop open. Exported for the strand revoked-peer gate
+ * (`strand-revocation-enforcer.ts`), which bounds its connection hooks with the
+ * same fail-open contract.
  */
-async function decideWithinDeadline<T>(
+export async function decideWithinDeadline<T>(
   decide: () => Promise<T> | T,
   fallback: T,
   timeoutMs: number,