@serfab/cadre-core 1.13.0 → 1.15.0

package/src/strand-formation-protocol.ts

@@ -1,1036 +1,1039 @@
-/**
- * Native cadre-core strand-formation transport.
- *
- * Mirrors the `seed-bootstrap.ts` protocol service: a dedicated
- * libp2p protocol id, length-prefixed JSON frames, and small single-purpose
- * session helpers. It replaces the removed `@serfab/strand-proto` package's transport,
- * carrying the caller's REAL invitation token + disclosure and BOTH parties'
- * real cadre peer addresses end-to-end (no `{ partyId: sessionId }` / `cadre-*.local`
- * placeholders), and validating the responder's result on the initiator side.
- *
- * Provisioning flow (`responderCreates`, 2 messages): the responder provisions (or, for
- * provision-then-record, resolves + records consent against) the strand and returns the
- * result on approval.
- *
- * Cadre-disclosure timing: the responder reveals its own party id + cadre addresses
- * — and, for a closed strand returned via provision-then-record, that strand's
- * membership key — ONLY after the token and disclosure validate; a rejection
- * discloses none of them.
- */
-
-import debug from 'debug';
-import { multiaddr, type Multiaddr } from '@multiformats/multiaddr';
-import type { Libp2p } from '@libp2p/interface';
-import type { StrandFormationDisclosure, StrandMembershipInvite } from './types.js';
-import { type ControlStream, writeFrame, withDeadline, withTimeout } from './control-stream.js';
-import { canonicalJson } from './canonical-json.js';
-import { requireEd25519PublicKeyB64 } from './ed25519-key.js';
-import { verifyFormationConsent } from './peer-authorization.js';
-// seed-bootstrap imports neither this protocol nor the manager/solicitation layers,
-// so this import introduces no cycle.
-import { ed25519PublicKeyB64FromPeerId } from './seed-bootstrap.js';
-import { trailingPeerId } from './peer-record.js';
-import {
-  formationDeadlines,
-  resolveProvisionTimeoutMs,
-  responderClampReserveMs,
-  splitProvisionBudget
-} from './strand-formation-deadlines.js';
-import {
-  FormationRejectedError,
-  FormationUnreachableError,
-  type FormationRejectionCode
-} from './strand-formation-rejection.js';
-
-const log = debug('sereus:cadre:formation-proto');
-
-/** Protocol id for the native formation transport (parallel to `/sereus/seed/1.0.0`). */
-export const FORMATION_PROTOCOL = '/sereus/formation/1.0.0';
-
-/**
- * Rejection reason for an invitation that cannot be redeemed — unknown here
- * (`'token-unknown'`), or expired or fully spent (`'token-spent'`); the code tells them
- * apart. Shared with `StrandFormationManager`, which reports an `InvitationExhaustedError`
- * (an invite spent out from under a redemption already in flight) with this SAME wording and
- * code on purpose: a joiner that lost the race must be indistinguishable from a non-racing
- * latecomer, so the two sites must never drift apart.
- */
-export const INVALID_TOKEN_REASON = 'Invalid token';
-
-/** Maximum formation message size (1MB). */
-const MAX_FORMATION_MSG_SIZE = 1024 * 1024;
-
-/**
- * Default cap on concurrent inbound formation sessions.
- *
- * NOTE: a session holds its slot for its whole provisioning budget, 171 s at the default
- * declared link ({@link formationDeadlines}), so a slow hook or commit holds slots for
- * minutes. Only a caller holding a valid token AND a valid consent signature reaches
- * provisioning — a stranger is cut at the contact wait (7 s at the default) or at the first
- * validation read — so the exposure is one invitee opening many sessions with one token. If
- * invitation tokens are ever published where untrusted parties can read them, cap in-flight
- * sessions per token rather than lowering this.
- */
-const DEFAULT_MAX_CONCURRENT_SESSIONS = 100;
-
-/**
- * Cap on the strand-network addresses a formation result carries
- * ({@link FormationResultMessage.strandAddrs}). A node's own strand multiaddrs are a
- * handful of entries (one per listen transport, plus a circuit-relay reservation), so
- * 16 is generous for the honest case while keeping the result frame bounded against a
- * peer that would pad it — either direction, since both sides run the list through
- * {@link sanitizeStrandAddrs}. The initiator's kept copy is one arriving list, replaced by
- * the next formation against the same strand, so the same bound holds there.
- */
-const MAX_STRAND_ADDRS = 16;
-
-// ── Roles ────────────────────────────────────────────────────────────────────
-
-export type FormationParty = 'initiator' | 'responder';
-
-// ── Wire messages (length-prefixed JSON frames) ──────────────────────────────
-
-export interface FormationStrandInfo {
-  strandId: string;
-  createdBy: FormationParty;
-}
-
-export interface FormationDbConnectionInfo {
-  endpoint: string;
-  credentialsRef: string;
-}
-
-export interface FormationProvisionResult {
-  strand: FormationStrandInfo;
-  /**
-   * The strand's membership key (closed-strand read-gating secret), delivered to a
-   * validated invitee for provision-then-record formation. Disclosed only AFTER token
-   * + disclosure validation, exactly like the responder identity/cadre — a rejected or
-   * already-used token discloses neither identity nor key. Absent for open strands.
-   */
-  memberPrivateKey?: string;
-  /**
-   * The joiner's single-use membership invitation into the (closed, bound) host
-   * strand — issued by the responder's live strand runtime against `Strand.Invite`
-   * just before the consent row was recorded. Same disclosure timing as
-   * {@link memberPrivateKey}: present only on an approved result, absent for open
-   * strands and the responder-provisions path. Bounded and shape-checked on the
-   * initiator side ({@link isWellFormedMembershipInvite}) — a hostile responder's
-   * malformed field fails validation rather than crashing the initiator.
-   */
-  membershipInvite?: StrandMembershipInvite;
-  dbConnectionInfo: FormationDbConnectionInfo;
-}
-
-/**
- * Outcome of the responder's provisioning hook.
- *
- * Distinct from a bare {@link FormationProvisionResult} so the hook can REJECT a
- * formation AFTER token + disclosure validation — e.g. a bound invite naming a host
- * strand this responder has not yet converged on, or a concurrent-redemption collision.
- * Without this channel such cases threw inside provisioning, the stream closed with no
- * result frame, and the initiator saw a read-error/timeout instead of a clean
- * `approved: false`. A rejection still discloses NO responder identity/cadre.
- */
-export type ResponderProvisionOutcome =
-  | { approved: true; result: FormationProvisionResult }
-  | FormationRejection;
-
-/**
- * A refusal as the responder sends it: never without a code. Carries nothing else — no
- * identity, addresses or keys — so a rejection discloses nothing about the responder.
- */
-export interface FormationRejection {
-  approved: false;
-  code: FormationRejectionCode;
-  /** Human-facing text for logs; joiners branch on `code`. */
-  reason: string;
-}
-
-/** What the responder's token check yields; an invalid token names which way it failed. */
-export type FormationTokenCheck =
-  | { valid: true }
-  | { valid: false; code: Extract<FormationRejectionCode, 'token-unknown' | 'token-spent'> };
-
-/** Initiator → Responder: carries the real token + disclosure + initiator cadre. */
-export interface FormationContactMessage {
-  /** The real invitation token. */
-  token: string;
-  /** Initiator's member key (peer id) — human-facing identity in logs and `FormStrandResult.memberKey`. */
-  partyId: string;
-  /**
-   * Initiator's base64url ed25519 public key — the key behind `partyId`, written to
-   * `FormationUsage.PeerKey` and covered by BOTH signed digests.
-   */
-  peerKey: string;
-  /** Joiner-minted single-use nonce for THIS redemption; both signed digests cover it. */
-  usageStampId: string;
-  /**
-   * The joiner's signature over the `'consent'` digest (see `formationConsentMessage`
-   * in control-database.ts) — proof the named peer agreed to this redemption.
-   */
-  peerSignature: string;
-  /** The real disclosure, carried verbatim. */
-  disclosure: StrandFormationDisclosure;
-  /** Initiator's real multiaddrs. */
-  cadrePeerAddrs: string[];
-}
-
-/** Responder → Initiator: responder identity/cadre disclosed only after validation. */
-export interface FormationResultMessage {
-  approved: boolean;
-  /**
-   * Why the responder refused; present iff `approved === false`. Optional on this wire type
-   * only because a frame from another version may omit it — the responder always sends one
-   * ({@link FormationRejection}), and the joiner reads a missing one as `'unrecognized'`.
-   */
-  code?: FormationRejectionCode;
-  /** Human-facing text; present iff `approved === false`. */
-  reason?: string;
-  /** Responder's real party id (disclosed only after validation). */
-  partyId?: string;
-  /** Responder's real multiaddrs (omitted on rejection). */
-  cadrePeerAddrs?: string[];
-  /**
-   * The responder's live STRAND-network multiaddrs for the provisioned strand — the
-   * initiator's only cross-party discovery seed, since the strand-addr RPC that resolves
-   * a sibling's strand addrs is membership-gated and answers own-party callers only.
-   *
-   * Disclosed on the same terms as `partyId`/`cadrePeerAddrs`: only after token +
-   * disclosure validation AND an approving provisioning outcome; a rejection carries
-   * none. Signaling-first, each entry ending in `/p2p/<responder strand transport
-   * peerId>` so the initiator can attribute it. OMITTED when the responder holds no live
-   * strand node for the provisioned strand (the responder-provisions path mints a strand
-   * that has not launched yet) — an absent or empty list is legal and means "no
-   * cross-party seed", never a protocol error.
-   */
-  strandAddrs?: string[];
-  /** The provisioned strand/db result (always present on approval). */
-  provisionResult?: FormationProvisionResult;
-}
-
-/** An approving result frame as the responder builds it. */
-type ApprovedResultMessage = FormationResultMessage & { approved: true };
-
-/**
- * Normalize a strand-address list arriving from — or heading to — the wire: keep only
- * parsable multiaddr strings, drop duplicates, and cap at {@link MAX_STRAND_ADDRS}.
- * Order is preserved, so the responder's signaling-first ordering survives.
- *
- * Applied on BOTH sides on purpose. The responder bounds what it sends; the initiator
- * bounds what it stores, because a peer is free to ignore the cap. A malformed entry is
- * SKIPPED rather than fatal — these are runtime-discovered addresses (same posture as
- * `extractCircuitRelayTargets` in `delegate-admission.ts`), and one bad entry must not
- * cost a formation that has otherwise succeeded.
- */
-export function sanitizeStrandAddrs(addrs: unknown): string[] {
-  if (!Array.isArray(addrs)) return [];
-  const out: string[] = [];
-  const seen = new Set<string>();
-  for (const entry of addrs) {
-    if (out.length >= MAX_STRAND_ADDRS) break;
-    if (typeof entry !== 'string' || entry.length === 0) {
-      log('strandAddrs: skipping non-string entry %o', entry);
-      continue;
-    }
-    if (seen.has(entry)) continue;
-    try {
-      multiaddr(entry);
-    } catch (error) {
-      // Deliberately not echoing the raw value at error level: it arrived from a remote
-      // peer. The log line below is the observability for a responder announcing junk.
-      log('strandAddrs: skipping unparsable entry: %o', error);
-      continue;
-    }
-    seen.add(entry);
-    out.push(entry);
-  }
-  return out;
-}
-
-// ── Stream framing helpers ───────────────────────────────────────────────────
-
-/**
- * Reads length-prefixed JSON frames from a libp2p stream one frame at a time.
- *
- * Unlike seed delivery (which reads a stream to EOF then parses once), formation
- * is request/response on a single live stream, so reading must stop at each frame
- * boundary. The reader buffers across chunk boundaries and retains any overflow
- * (a following frame coalesced into the same chunk) for the next read.
- */
-class FrameReader {
-  private readonly iterator: AsyncIterator<Uint8Array>;
-  private readonly maxLength: number;
-  private buffer = new Uint8Array(0);
-
-  constructor(stream: AsyncIterable<Uint8Array>, maxLength = MAX_FORMATION_MSG_SIZE) {
-    this.iterator = stream[Symbol.asyncIterator]();
-    this.maxLength = maxLength;
-  }
-
-  private append(chunk: Uint8Array): void {
-    const next = new Uint8Array(this.buffer.length + chunk.length);
-    next.set(this.buffer, 0);
-    next.set(chunk, this.buffer.length);
-    this.buffer = next;
-  }
-
-  /** Pull chunks until the buffer holds ≥ `need` bytes; false if the stream ended first. */
-  private async fill(need: number): Promise<boolean> {
-    while (this.buffer.length < need) {
-      const { value, done } = await this.iterator.next();
-      if (done) return false;
-      const bytes = value instanceof Uint8Array
-        ? value
-        : (value as { subarray(): Uint8Array }).subarray();
-      this.append(bytes);
-    }
-    return true;
-  }
-
-  async read<T>(): Promise<T> {
-    if (!(await this.fill(4))) {
-      throw new Error('Formation stream closed before length prefix');
-    }
-    const length = new DataView(this.buffer.buffer, this.buffer.byteOffset, this.buffer.byteLength).getUint32(0, false);
-    if (length > this.maxLength) {
-      throw new Error(`Formation frame declares length ${length} exceeding max ${this.maxLength}`);
-    }
-    if (!(await this.fill(4 + length))) {
-      throw new Error(`Formation frame declares length ${length} but stream ended early`);
-    }
-    const json = new TextDecoder().decode(this.buffer.subarray(4, 4 + length));
-    this.buffer = this.buffer.subarray(4 + length);
-    return JSON.parse(json) as T;
-  }
-}
-
-// ── Result validation ────────────────────────────────────────────────────────
-
-/** Matches the placeholder cadre addrs (`cadre-a-1.local`, …) of the removed strand-proto transport. */
-const PLACEHOLDER_CADRE_ADDR = /^cadre-[ab]-\d+\.local$/;
-
-/**
- * Both halves of a {@link StrandMembershipInvite} are base64url ed25519 key encodings —
- * 43 chars for 32 bytes. The bound is deliberately loose (a future encoding change must
- * not silently strand joiners) while still capping what a hostile responder can make the
- * initiator retain.
- */
-const MAX_MEMBERSHIP_INVITE_KEY_LENGTH = 256;
-const BASE64URL_KEY = /^[A-Za-z0-9_-]+$/;
-
-/**
- * Is `value` a well-formed {@link StrandMembershipInvite} — exactly two bounded
- * base64url strings? The initiator-side shape check for the one attacker-influenced
- * OBJECT the formation result carries (`strandAddrs` gets the equivalent treatment in
- * {@link sanitizeStrandAddrs}): a malformed field from a hostile responder must fail
- * validation, never crash the initiator or be carried into the joiner's invite cache.
- * `undefined` is NOT well-formed — absence is legal on the result and callers gate on
- * presence first.
- */
-export function isWellFormedMembershipInvite(value: unknown): value is StrandMembershipInvite {
-  if (typeof value !== 'object' || value === null) return false;
-  const { inviteKey, invitePrivateKey } = value as Record<string, unknown>;
-  const wellFormedKey = (key: unknown): boolean =>
-    typeof key === 'string' && key.length > 0 && key.length <= MAX_MEMBERSHIP_INVITE_KEY_LENGTH && BASE64URL_KEY.test(key);
-  return wellFormedKey(inviteKey) && wellFormedKey(invitePrivateKey);
-}
-
-/**
- * Structural check on a `responderCreates` result: the responder must have approved,
- * disclosed a non-empty real identity + cadre (not the legacy `cadre-*.local`
- * placeholders), and returned a strand vouched for by the responder party with a real id.
- *
- * `createdBy: 'responder'` means "the responder party vouches for / returns this strand."
- * Under provision-then-record that strand was minted owner-signed earlier (not created
- * in-session), but it is still the responder party returning its own strand, so the marker
- * — and this structural validator — stay unchanged.
- *
- * The behavioral floor for the initiator: a responder that returns an arbitrary/empty
- * `strandId` or omits its disclosed identity is rejected, not silently accepted.
- */
-export function isValidResponderCreatesResult(response: FormationResultMessage): boolean {
-  if (!response.approved) return false;
-  if (!response.partyId) return false;
-  const addrs = response.cadrePeerAddrs;
-  if (!addrs || addrs.length === 0) return false;
-  if (addrs.some((a) => PLACEHOLDER_CADRE_ADDR.test(a))) return false;
-  const provision = response.provisionResult;
-  if (!provision?.strand?.strandId) return false;
-  if (provision.strand.createdBy !== 'responder') return false;
-  // Optional, but when present it must be well-formed: a malformed invitation is a
-  // membership the joiner can never redeem, so reject the result rather than accept a
-  // formation that would leave a half-member.
-  if (provision.membershipInvite !== undefined && !isWellFormedMembershipInvite(provision.membershipInvite)) {
-    return false;
-  }
-  return true;
-}
-
-// ── Responder (listener) ─────────────────────────────────────────────────────
-
-export interface FormationListenerOptions {
-  /** Validate the invitation token; an invalid one says whether it is unknown here or spent. */
-  validateToken(token: string): Promise<FormationTokenCheck>;
-  /** Validate the initiator's disclosure with the REAL token + disclosure. */
-  validateDisclosure(token: string, disclosure: StrandFormationDisclosure): Promise<boolean>;
-  /**
-   * Provision (or, for provision-then-record, resolve + record consent against) the
-   * strand (`responderCreates`) for the given initiator. The WHOLE contact message is
-   * threaded in: the hook needs the REAL token to map the bound host strand, and the
-   * joiner's `peerKey`/`usageStampId`/`peerSignature` to write the consent columns.
-   *
-   * Returns a {@link ResponderProvisionOutcome}: the hook may REJECT post-validation
-   * (e.g. an unconverged host strand) and the listener turns that into a clean,
-   * non-disclosing `approved: false` reply rather than dropping the result frame.
-   *
-   * `signal` is aborted when the listener's work budget expires: a hook that observes it
-   * BEFORE writing abandons the redemption and leaves the invite unspent. Optional so
-   * signal-unaware hooks (tests, mocks) stay assignable.
-   */
-  provisionStrand(contact: FormationContactMessage, signal?: AbortSignal): Promise<ResponderProvisionOutcome>;
-  /** Responder identity, disclosed only AFTER token + disclosure validation passes. */
-  getResponderIdentity(): { partyId: string; cadrePeerAddrs: string[] };
-  /**
-   * This node's live STRAND-network multiaddrs for a provisioned strand, read on the
-   * approval path only (same disclosure timing as {@link getResponderIdentity}) and
-   * carried back as {@link FormationResultMessage.strandAddrs}.
-   *
-   * Optional, and an empty answer is legal: the strand may not be running here yet (the
-   * responder-provisions path mints it during this very session). The listener cannot
-   * reach the strand runtime itself, so this is the seam `CadreNode` wires to its own
-   * per-strand address lookup.
-   */
-  resolveStrandAddrs?(strandId: string): string[];
-  /**
-   * This machine's declared link round trip (`NetworkConfig.linkRoundTripMs`), from which
-   * every deadline below takes its default ({@link formationDeadlines}). The default
-   * declaration when omitted.
-   */
-  linkRoundTripMs?: number;
-  /** Whole-session budget; default `sessionMs` of the derived ladder. */
-  sessionTimeoutMs?: number;
-  /** Budget for the contact-frame read; default `awaitContactMs` of the derived ladder. */
-  stepTimeoutMs?: number;
-  /**
-   * Budget for the `provisionStrand` hook call, work plus settle grace — distinct from
-   * `stepTimeoutMs` because provisioning is real work, not a bare wire read. Default
-   * `provisionWorkMs + provisionGraceMs` of the derived ladder (171 s at the default
-   * declaration); `0`/unset uses the default; a value that would outlive the session is
-   * clamped ({@link resolveProvisionTimeoutMs}). See {@link formationDeadlines} for the ordering.
-   */
-  provisionTimeoutMs?: number;
-  maxConcurrentSessions?: number;
-}
-
-/**
- * Responder side of the native formation protocol. Registers a libp2p handler and
- * drives each inbound stream through token + disclosure validation, provisioning,
- * and result delivery — enforcing the cadre-disclosure timing rule (responder cadre
- * is revealed only after validation; rejections disclose nothing).
- */
-export class FormationListener {
-  private readonly options: FormationListenerOptions;
-  private readonly sessionTimeoutMs: number;
-  private readonly awaitContactMs: number;
-  private readonly provisionWorkMs: number;
-  private readonly provisionGraceMs: number;
-  private readonly maxConcurrentSessions: number;
-  private readonly registered = new Set<Libp2p>();
-  private activeSessions = 0;
-  private sessionCounter = 0;
-
-  constructor(options: FormationListenerOptions) {
-    this.options = options;
-    const deadlines = formationDeadlines(options.linkRoundTripMs);
-    this.sessionTimeoutMs = options.sessionTimeoutMs ?? deadlines.sessionMs;
-    this.awaitContactMs = options.stepTimeoutMs ?? deadlines.awaitContactMs;
-    const split = splitProvisionBudget(resolveProvisionTimeoutMs(
-      options.provisionTimeoutMs, deadlines.provisionWorkMs + deadlines.provisionGraceMs,
-      this.sessionTimeoutMs, this.awaitContactMs + deadlines.validationMs, 'FormationListener',
-      responderClampReserveMs(deadlines, this.awaitContactMs)
-    ), deadlines.provisionGraceMs);
-    this.provisionWorkMs = split.workMs;
-    this.provisionGraceMs = split.graceMs;
-    this.maxConcurrentSessions = options.maxConcurrentSessions ?? DEFAULT_MAX_CONCURRENT_SESSIONS;
-  }
-
-  /** Number of in-flight inbound sessions. */
-  get activeCount(): number {
-    return this.activeSessions;
-  }
-
-  /** Register the formation handler on `node`. Rejects when libp2p refuses the registration. */
-  async register(node: Libp2p, protocolId: string = FORMATION_PROTOCOL): Promise<void> {
-    if (this.registered.has(node)) {
-      log('node already registered');
-      return;
-    }
-    await node.handle(protocolId, async (rawStream: unknown, _connection: unknown) => {
-      await this.handleStream(rawStream as ControlStream);
-    });
-    this.registered.add(node);
-    log('formation listener registered (%s)', protocolId);
-  }
-
-  async unregister(node: Libp2p, protocolId: string = FORMATION_PROTOCOL): Promise<void> {
-    if (!this.registered.has(node)) return;
-    await node.unhandle(protocolId);
-    this.registered.delete(node);
-    log('formation listener unregistered (%s)', protocolId);
-  }
-
-  private async handleStream(stream: ControlStream): Promise<void> {
-    if (this.activeSessions >= this.maxConcurrentSessions) {
-      const rejection: FormationRejection = { approved: false, code: 'busy', reason: 'Too many concurrent formation sessions' };
-      try { writeFrame(stream, rejection); } catch { /* best effort */ }
-      try { await stream.close(); } catch { /* ignore */ }
-      return;
-    }
-    const id = ++this.sessionCounter;
-    this.activeSessions++;
-    try {
-      await withTimeout(this.sessionTimeoutMs, `Formation session#${id}`, () => this.runSession(id, stream));
-    } catch (err) {
-      log('formation session #%d failed: %o', id, err);
-    } finally {
-      this.activeSessions--;
-      try { await stream.close(); } catch { /* ignore */ }
-    }
-  }
-
-  /**
-   * Run the provisioning hook under its WORK budget — the provisioning budget minus the
-   * trailing settle grace ({@link splitProvisionBudget}).
-   *
-   * When the work budget expires the hook's signal is aborted, then
-   * {@link settleWithinGrace} waits out the grace for the aborted work to settle anyway.
-   * Returns `undefined` for "timed out" — which the caller turns into a retryable rejection
-   * frame — and rethrows every other failure so it reaches the internal-error path.
-   *
-   * Deliberately not `withDeadline`: that exposes neither the timed-out flag nor the signal
-   * outside its `op`, and both are needed here.
-   */
-  private async provision(id: number, contact: FormationContactMessage): Promise<ResponderProvisionOutcome | undefined> {
-    const controller = new AbortController();
-    let timedOut = false;
-    const pending = this.options.provisionStrand(contact, controller.signal);
-    try {
-      return await withTimeout(
-        this.provisionWorkMs,
-        `Formation provisioning#${id}`,
-        () => pending,
-        () => { timedOut = true; controller.abort(); }
-      );
-    } catch (err) {
-      if (!timedOut) throw err;
-      log(
-        'formation session #%d provisioning work budget expired after %dms; aborted, settling up to %dms',
-        id, this.provisionWorkMs, this.provisionGraceMs
-      );
-      return await this.settleWithinGrace(id, pending);
-    }
-  }
-
-  /**
-   * Wait out the settle grace for an ABORTED provisioning, adopting a late success.
-   *
-   * A hook that observed the abort before issuing its `FormationUsage` insert rejects (with
-   * `FormationAbortedError`) and leaves the invite unspent → reported as a timeout. A hook
-   * that had already written cannot be un-written (the table is append-only), so if it lands
-   * inside the grace its outcome is ADOPTED — the joiner is told the truth (approved, or the
-   * hook's own rejection reason) rather than "timed out" over a spent invite.
-   *
-   * The grace is derived to contain one seat read plus one commit at the declared link
-   * ({@link formationDeadlines}), which is exactly what runs after the insert attempt passes
-   * its abort check, so at that link the late outcome lands inside it.
-   *
-   * NOTE: a commit that outlasts even the derived grace (a link slower than declared, a
-   * configured `provisionTimeoutMs` whose half-cap shrank the grace, or a commit phase that
-   * re-picks an unanswering coordinator, which Optimystic lets run to its transaction budget,
-   * 170 s at the default declared link) still tells the joiner
-   * 'timed out' while its one-time invite is in fact spent, and since every retry mints a
-   * fresh keypair no recovery path can match it. Nothing can un-spend an append-only row, so
-   * the late-settle logging below is the observability for it; if it is seen in the wild,
-   * raise the declared link rather than this grace.
-   */
-  private async settleWithinGrace(
-    id: number,
-    pending: Promise<ResponderProvisionOutcome>
-  ): Promise<ResponderProvisionOutcome | undefined> {
-    let stillPending = false;
-    try {
-      const outcome = await withTimeout(
-        this.provisionGraceMs,
-        `Formation settle#${id}`,
-        () => pending,
-        () => { stillPending = true; }
-      );
-      log('formation session #%d provisioning settled within its grace: approved=%s — adopting', id, outcome.approved);
-      return outcome;
-    } catch (err) {
-      if (!stillPending) {
-        log('formation session #%d provisioning failed after its abort: %o', id, err);
-        return undefined;
-      }
-      log('formation session #%d provisioning still pending after its %dms grace', id, this.provisionGraceMs);
-      // Log how it eventually settled so a late failure is not swallowed by the two
-      // abandoned `withTimeout` calls.
-      void pending.then(
-        (late) => log('formation session #%d provisioning settled after its grace: approved=%s', id, late.approved),
-        (err2) => log('formation session #%d provisioning failed after its grace: %o', id, err2)
-      );
-      return undefined;
-    }
-  }
-
-  /**
-   * Joiner-consent pre-check — the legibility twin of the schema's
-   * `FormationUsage.PeerConsented` CHECK, exactly as `verifyFormationApproval` is for the
-   * approver's vouch. The database constraint stays the authority; this turns a bad consent
-   * into a clean 'Invalid joiner consent' rejection instead of an opaque CHECK failure at
-   * commit. Runs BEFORE token/disclosure validation: it is the cheapest check (pure local
-   * crypto, no DB read) and a rejection discloses nothing.
-   *
-   * Also pins `partyId` to `peerKey`: an ed25519 peer id is an identity multihash of the
-   * very key, and this is the ONLY layer that can check the match — SQL cannot unwrap a
-   * multihash, and `partyId` itself is never stored.
-   */
-  private isJoinerConsentValid(id: number, contact: FormationContactMessage): boolean {
-    try {
-      requireEd25519PublicKeyB64(contact.peerKey, 'joiner peer key');
-    } catch {
-      // Deliberately not rethrown or echoed: the helper's error message embeds the whole
-      // rejected value, and this one arrived from a remote peer (the cap-the-echo case its
-      // own NOTE warns about). Log without the raw value instead.
-      log('formation session #%d: joiner peer key is not a base64url ed25519 public key', id);
-      return false;
-    }
-    const embedded = ed25519PublicKeyB64FromPeerId(contact.partyId);
-    if (!embedded || embedded !== contact.peerKey) {
-      log('formation session #%d: partyId does not embed the presented peer key', id);
-      return false;
-    }
-    const consentOk = verifyFormationConsent({
-      token: contact.token,
-      usageStampId: contact.usageStampId,
-      peerKey: contact.peerKey,
-      disclosure: canonicalJson(contact.disclosure),
-      peerSig: contact.peerSignature
-    });
-    if (!consentOk) {
-      log('formation session #%d: joiner consent signature failed verification', id);
-      return false;
-    }
-    return true;
-  }
-
-  /**
-   * The strand addresses to disclose for an APPROVED provisioning, sanitized and capped.
-   *
-   * Never throws: a hook that fails (a strand runtime torn down mid-session) costs the
-   * joiner its cross-party seed, not the formation it has already earned — the seed is
-   * an optimization, the consent row is the commitment.
-   */
-  private strandAddrsFor(id: number, strandId: string): string[] {
-    if (!this.options.resolveStrandAddrs) return [];
-    try {
-      return sanitizeStrandAddrs(this.options.resolveStrandAddrs(strandId));
-    } catch (err) {
-      log('formation session #%d: strand-addr lookup for %s failed (continuing): %o', id, strandId, err);
-      return [];
-    }
-  }
-
-  private async runSession(id: number, stream: ControlStream): Promise<void> {
-    // Track whether ANY frame has been written so the catch below can convert an
-    // unexpected internal error into a non-disclosing rejection ONLY when nothing has
-    // gone out yet. This closes the "stream closed with no result frame" class of bug.
-    let wroteFrame = false;
-    const send = (msg: FormationRejection | ApprovedResultMessage): void => {
-      writeFrame(stream, msg);
-      wroteFrame = true;
-    };
-
-    try {
-      const reader = new FrameReader(stream);
-      const contact = await withTimeout(this.awaitContactMs, `Formation await-contact#${id}`, () => reader.read<FormationContactMessage>());
-      log('formation session #%d contact: token=%s party=%s', id, contact.token, contact.partyId);
-
-      if (!this.isJoinerConsentValid(id, contact)) {
-        send({ approved: false, code: 'consent-invalid', reason: 'Invalid joiner consent' });
-        return;
-      }
-
-      const tokenResult = await this.options.validateToken(contact.token);
-      if (!tokenResult.valid) {
-        send({ approved: false, code: tokenResult.code, reason: INVALID_TOKEN_REASON });
-        return;
-      }
-
-      const disclosureOk = await this.options.validateDisclosure(contact.token, contact.disclosure);
-      if (!disclosureOk) {
-        send({ approved: false, code: 'disclosure-invalid', reason: 'Invalid disclosure' });
-        return;
-      }
-
-      const outcome = await this.provision(id, contact);
-      if (!outcome) {
-        // Reported as its own retryable reason rather than falling through to the generic
-        // catch below, which would report the misleading 'Internal formation error'.
-        send({ approved: false, code: 'provisioning-timeout', reason: 'Formation provisioning timed out' });
-        return;
-      }
-      if (!outcome.approved) {
-        // A post-validation rejection still discloses NEITHER identity NOR cadre, exactly
-        // like the token/disclosure rejections above — copied field by field so nothing else
-        // a hook put on its outcome reaches the wire.
-        send({ approved: false, code: outcome.code, reason: outcome.reason });
-        return;
-      }
-      // Validation + provisioning passed → safe to disclose responder identity/cadre.
-      const identity = this.options.getResponderIdentity();
-      const strandAddrs = this.strandAddrsFor(id, outcome.result.strand.strandId);
-      send({
-        approved: true,
-        partyId: identity.partyId,
-        cadrePeerAddrs: identity.cadrePeerAddrs,
-        // Omitted rather than sent empty: an absent field and an empty list mean the same
-        // thing to the initiator, and omitting keeps every rejection-parity assertion a
-        // plain `toBeUndefined()`.
-        ...(strandAddrs.length > 0 ? { strandAddrs } : {}),
-        provisionResult: outcome.result
-      });
-    } catch (err) {
-      // Defense-in-depth: if an unexpected internal error escapes BEFORE any frame was
-      // written (e.g. a future provisionStrand-hook bug), convert it into a non-disclosing
-      // protocol rejection so the initiator sees a clean error instead of a read-error/
-      // timeout. If a frame was already sent, leave the stream as-is and let handleStream
-      // log + close. Re-throw either way so the failure is still recorded — this is a
-      // deliberate, logged conversion, not silent.
-      if (!wroteFrame) {
-        const internalError: FormationRejection = { approved: false, code: 'internal', reason: 'Internal formation error' };
-        try { writeFrame(stream, internalError); } catch { /* stream already broken */ }
-      }
-      throw err;
-    }
-  }
-}
-
-// ── Initiator (dialer) ───────────────────────────────────────────────────────
-
-export interface FormationDialOptions {
-  /** The contact message to send (real token, partyId, disclosure, initiator cadre). */
-  contact: FormationContactMessage;
-  /**
-   * Responder multiaddrs to dial, normally the invitation's bootstrap list. Every entry that
-   * parses is tried, in the order libp2p's default address sorter picks (loopback last, then
-   * public before private, then circuit after direct), until one connects, all under one
-   * dial-connect budget (`dialTimeoutMs`); an entry that does not parse is skipped.
-   *
-   * {@link dialFormation} dials ONE machine, so every entry must name the same trailing peer
-   * id (or none). An invitation names several machines of the inviting party; hand it to
-   * {@link dialFormationByMachine}, which splits the list by trailing peer id, drops entries
-   * that name no peer, and runs one {@link dialFormation} session per machine, in the order
-   * each machine first appears. Each session keeps its own deadline ladder, so a machine that
-   * cannot be dialled costs one `dialTimeoutMs` and one that accepts the contact and then
-   * stalls costs up to one `sessionTimeoutMs`; `CadreNode.createOpenInvitation` names at most
-   * four machines.
-   */
-  responderAddrs: string[];
-  /** Validate the responder's result; a false return aborts the formation. */
-  validateResponse(response: FormationResultMessage): Promise<boolean>;
-  /**
-   * This machine's declared link round trip (`NetworkConfig.linkRoundTripMs`), from which
-   * every deadline below takes its default ({@link formationDeadlines}). The default
-   * declaration when omitted.
-   */
-  linkRoundTripMs?: number;
-  /** Whole-session budget; default `sessionMs` of the derived ladder. */
-  sessionTimeoutMs?: number;
-  /**
-   * Budget for `dial-connect`: opening the connection, through a relay if need be, and
-   * negotiating the formation protocol. Default `dialMs` of the derived ladder.
-   */
-  dialTimeoutMs?: number;
-  /**
-   * Budget for the `await-response` read only (the responder's provisioning plus the reply's
-   * travel time). Default `initiatorAwaitResponseMs` of the derived ladder; `0`/unset uses
-   * the default; a value that would outlive the session is clamped. See
-   * {@link formationDeadlines} for the ordering.
-   */
-  provisionTimeoutMs?: number;
-  protocolId?: string;
-}
-
-/**
- * What one successful formation dial yields the initiator.
- *
- * The provisioned strand travels in {@link FormationProvisionResult}, but the responder's
- * strand-network addresses are NOT part of that structure — they are a disclosure of the
- * responder's live runtime, alongside `partyId`/`cadrePeerAddrs`, not a property of the
- * strand row. Returning them beside the provision result keeps that separation while
- * still handing the caller the one thing it needs to seed a cross-party mesh.
- *
- * `strandAddrs` is always an array and is frequently EMPTY — see
- * {@link FormationResultMessage.strandAddrs}.
- */
-export interface FormationDialResult {
-  provision: FormationProvisionResult;
-  /** Sanitized + capped ({@link sanitizeStrandAddrs}); `[]` when the responder sent none. */
-  strandAddrs: string[];
-}
-
-/**
- * Open the formation stream under the dial deadline, cancelling the dial when it expires.
- *
- * The deadline's signal goes into `dialProtocol`, so an expired dial is abandoned by libp2p
- * rather than left running. A dial that settles in the same tick the deadline fires loses
- * the race to the timeout rejection and would leave its stream open with nobody to close
- * it, so a stream that arrives after the signal aborted is reset here — the same treatment
- * `exchangeFrame` (`control-stream.ts`) gives a stream dialed past its deadline. A late
- * rejection is the abort itself, or reaches the caller through the awaited copy, so the
- * handler below only stops it being reported as unhandled.
- *
- * NOTE: libp2p tries `addrs` one after another, and they all share this one dial budget. Its
- * per-address limit (`addressDialTimeout`: ten link round trips plus two admission decisions, as
- * `optimysticDialLimits` states it) is longer than `dialTimeoutMs` (`formationDeadlines().dialMs`:
- * five round trips plus one decision) at every declaration, so it never cuts off an address
- * inside this dial. An address that hangs without answering (a black-holed relay host) uses the
- * whole budget, and the join moves on to the party's next machine
- * ({@link dialFormationByMachine}) rather than to this machine's next address; an address that is
- * refused fails fast and still hands over to the next. A budget per address here would overrun
- * the session or shrink the await-response budget ({@link formationDeadlines}). If joins through a
- * hung first address are seen in practice, give each address a sub-budget or dial them in parallel.
- */
-function openFormationStream(node: Libp2p, addrs: Multiaddr[], protocolId: string, dialTimeoutMs: number): Promise<ControlStream> {
-  return withDeadline(dialTimeoutMs, 'Formation dial-connect', async (signal) => {
-    const pending = node.dialProtocol(addrs, protocolId, { signal });
-    void pending.then(
-      (stream) => {
-        if (signal.aborted) {
-          (stream as unknown as ControlStream).abort(new Error('Formation dial-connect resolved after its deadline'));
-        }
-      },
-      () => { /* surfaced through the awaited copy, or the abort itself */ }
-    );
-    try {
-      return await pending as unknown as ControlStream;
-    } catch (error) {
-      throw describeAllAddressesFailed(error);
-    }
-  });
-}
-
-const NO_RESPONDER_ADDRS = 'No responder addresses available for formation';
-
-/**
- * Parse the responder addresses, skipping any entry that does not parse: the list comes from
- * a stranger's invitation, and one bad entry must not fail an otherwise good list. Entries
- * naming different peers are left for libp2p to refuse; {@link dialFormationByMachine} hands
- * this one machine's addresses at a time.
- */
-function parseResponderAddrs(addrs: string[]): Multiaddr[] {
-  const parsed: Multiaddr[] = [];
-  for (const addr of addrs) {
-    const ma = parseResponderAddr(addr);
-    if (ma) parsed.push(ma);
-  }
-  if (parsed.length === 0) {
-    throw new FormationUnreachableError(NO_RESPONDER_ADDRS);
-  }
-  return parsed;
-}
-
-function parseResponderAddr(addr: string): Multiaddr | null {
-  try {
-    return multiaddr(addr);
-  } catch (error) {
-    log('responderAddrs: skipping unparsable entry: %o', error);
-    return null;
-  }
-}
-
-/** One machine of the inviting party, and the invitation's addresses for it. */
-interface ResponderMachine {
-  peerId: string;
-  addrs: string[];
-}
-
-/**
- * Split the responder addresses by the machine each reaches (its trailing peer id), keeping
- * the order in which each machine first appears. An entry that does not parse, or names no
- * peer, is dropped: every address an inviter mints (`getMultiaddrs()`, `resolvePeerAddrs`)
- * names its machine, and libp2p refuses one dial that mixes named and unnamed addresses.
- */
-function groupResponderAddrsByMachine(addrs: string[]): ResponderMachine[] {
-  const machines = new Map<string, string[]>();
-  for (const addr of addrs) {
-    const ma = parseResponderAddr(addr);
-    if (!ma) continue;
-    const peerId = trailingPeerId(ma);
-    if (!peerId) {
-      log('responderAddrs: skipping %s — it names no machine', addr);
-      continue;
-    }
-    const group = machines.get(peerId);
-    if (group) group.push(addr);
-    else machines.set(peerId, [addr]);
-  }
-  return [...machines].map(([peerId, group]) => ({ peerId, addrs: group }));
-}
-
-/**
- * Worth asking the next machine of the inviting party: it could not be reached, or it answered
- * with a refusal a sibling may not repeat (the invitation not replicated to it yet, the host
- * strand not running there, …). A final refusal is the party's answer, not one machine's.
- */
-function shouldTryNextMachine(error: unknown): error is FormationUnreachableError | FormationRejectedError {
-  return error instanceof FormationUnreachableError || (error instanceof FormationRejectedError && error.retryable);
-}
-
-/**
- * Every machine failed without a refusal. A single machine's error already names each address
- * it tried, so it is thrown as is; several are restated as one error naming each machine.
- */
-function noMachineReached(failures: Array<{ peerId: string; error: FormationUnreachableError }>): FormationUnreachableError {
-  if (failures.length === 1) return failures[0].error;
-  const errors = failures.map((failure) => failure.error);
-  return new FormationUnreachableError(
-    `Formation could not reach any of the inviter's ${failures.length} machines: ` +
-      failures.map((failure) => `${failure.peerId}: ${failure.error.message}`).join('; '),
-    { cause: new AggregateError(errors, 'Every inviting machine was unreachable') }
-  );
-}
-
-/**
- * libp2p reports a dial in which every address failed as `AggregateError('All multiaddr dials
- * failed')`, which names none of them; restate it with each address's own error, which names
- * its host and port. A dial that tried only one address already surfaces that address's own
- * error, so anything else passes through unchanged.
- */
-function describeAllAddressesFailed(error: unknown): unknown {
-  if (!(error instanceof AggregateError)) return error;
-  const reasons = error.errors.map((reason: unknown) => reason instanceof Error ? reason.message : String(reason));
-  return new FormationUnreachableError(
-    `Formation could not reach the inviter at any of the ${reasons.length} addresses tried: ${reasons.join('; ')}`,
-    { cause: error }
-  );
-}
-
-/** Report a failure that came before any answer as {@link FormationUnreachableError}, keeping its message. */
-function asUnreachable(error: unknown): FormationUnreachableError {
-  if (error instanceof FormationUnreachableError) return error;
-  return new FormationUnreachableError(error instanceof Error ? error.message : String(error), { cause: error });
-}
-
-/**
- * Open the formation stream, send the contact, and read back the one result frame, closing
- * the stream either way. Nothing here has an answer from the responder yet, so the caller
- * reports any failure as {@link FormationUnreachableError} — a frame too large or not JSON
- * included, since it is not an answer either.
- */
-async function exchangeContact(
-  node: Libp2p,
-  addrs: Multiaddr[],
-  contact: FormationContactMessage,
-  budgets: { protocolId: string; dialTimeoutMs: number; awaitResponseMs: number }
-): Promise<FormationResultMessage> {
-  const stream = await openFormationStream(node, addrs, budgets.protocolId, budgets.dialTimeoutMs);
-  try {
-    const reader = new FrameReader(stream);
-    writeFrame(stream, contact);
-    return await withTimeout(budgets.awaitResponseMs, 'Formation await-response', () => reader.read<FormationResultMessage>());
-  } finally {
-    try { await stream.close(); } catch { /* ignore */ }
-  }
-}
-
-/**
- * Turn the responder's answer into the dial's result. A refusal throws
- * {@link FormationRejectedError}; an approval that fails validation throws a plain `Error`,
- * since that is a misbehaving responder rather than a refusal.
- */
-async function acceptResult(
-  response: FormationResultMessage,
-  validateResponse: FormationDialOptions['validateResponse']
-): Promise<FormationDialResult> {
-  if (!response.approved) {
-    throw new FormationRejectedError(response.code, response.reason);
-  }
-  if (!(await validateResponse(response))) throw new Error('Responder result failed validation');
-
-  if (!response.provisionResult) throw new Error('Missing provision result for responderCreates mode');
-  // Sanitized HERE — the wire boundary — so nothing above this call ever handles an
-  // unvalidated, unbounded address list from a remote peer.
-  return { provision: response.provisionResult, strandAddrs: sanitizeStrandAddrs(response.strandAddrs) };
-}
-
-/**
- * Initiator side of the native formation protocol. Dials the responder, sends the
- * contact (carrying the real disclosure/token/cadre), validates the responder's
- * result, and returns the strand the responder provisioned plus the responder's
- * strand-network addresses (see {@link FormationDialResult}).
- *
- * Throws {@link FormationUnreachableError} for every failure before a result frame is read
- * (including the session deadline passing first), {@link FormationRejectedError} when the
- * responder refuses, and a plain `Error` for an approval that fails validation.
- */
-export async function dialFormation(node: Libp2p, options: FormationDialOptions): Promise<FormationDialResult> {
-  const addrs = parseResponderAddrs(options.responderAddrs);
-  const protocolId = options.protocolId ?? FORMATION_PROTOCOL;
-  const deadlines = formationDeadlines(options.linkRoundTripMs);
-  const sessionTimeoutMs = options.sessionTimeoutMs ?? deadlines.sessionMs;
-  const dialTimeoutMs = options.dialTimeoutMs ?? deadlines.dialMs;
-  const awaitResponseMs = resolveProvisionTimeoutMs(
-    options.provisionTimeoutMs, deadlines.initiatorAwaitResponseMs,
-    sessionTimeoutMs, dialTimeoutMs, 'dialFormation'
-  );
-
-  let answered = false;
-  try {
-    return await withTimeout(sessionTimeoutMs, 'Formation dial', async () => {
-      const response = await exchangeContact(node, addrs, options.contact, { protocolId, dialTimeoutMs, awaitResponseMs });
-      answered = true;
-      return await acceptResult(response, options.validateResponse);
-    });
-  } catch (error) {
-    throw answered ? error : asUnreachable(error);
-  }
-}
-
-/**
- * Initiator side for a whole invitation: one {@link dialFormation} session per machine of the
- * inviting party the bootstrap list names (see {@link FormationDialOptions.responderAddrs}), in
- * order, until one approves.
- *
- * A machine that cannot be reached, or that refuses retryably, hands over to the next. A final
- * refusal, or an approval that fails validation, is thrown at once: another machine of the
- * same party would answer the same, and an approval may already have spent the invitation.
- * With no machine left, throws the last retryable refusal when any machine answered (the party
- * is reachable but not ready, which says more than "unreachable"), otherwise one
- * {@link FormationUnreachableError} naming each machine's failure.
- *
- * Every session sends the SAME contact. `FormationUsage` is keyed by the contact's
- * `usageStampId`, so at most one machine of the inviting party can record this redemption,
- * even when one the joiner gave up on was still committing it.
- */
-export async function dialFormationByMachine(node: Libp2p, options: FormationDialOptions): Promise<FormationDialResult> {
-  const machines = groupResponderAddrsByMachine(options.responderAddrs);
-  if (machines.length === 0) {
-    throw new FormationUnreachableError(NO_RESPONDER_ADDRS);
-  }
-  const unreached: Array<{ peerId: string; error: FormationUnreachableError }> = [];
-  let refusal: FormationRejectedError | undefined;
-  for (const machine of machines) {
-    try {
-      return await dialFormation(node, { ...options, responderAddrs: machine.addrs });
-    } catch (error) {
-      if (!shouldTryNextMachine(error)) throw error;
-      log('formation via %s failed (%s), trying the next inviting machine', machine.peerId, error.message);
-      if (error instanceof FormationRejectedError) refusal = error;
-      else unreached.push({ peerId: machine.peerId, error });
-    }
-  }
-  throw refusal ?? noMachineReached(unreached);
-}
+/**
+ * Native cadre-core strand-formation transport.
+ *
+ * Mirrors the `seed-bootstrap.ts` protocol service: a dedicated
+ * libp2p protocol id, length-prefixed JSON frames, and small single-purpose
+ * session helpers. It replaces the removed `@serfab/strand-proto` package's transport,
+ * carrying the caller's REAL invitation token + disclosure and BOTH parties'
+ * real cadre peer addresses end-to-end (no `{ partyId: sessionId }` / `cadre-*.local`
+ * placeholders), and validating the responder's result on the initiator side.
+ *
+ * Provisioning flow (`responderCreates`, 2 messages): the responder provisions (or, for
+ * provision-then-record, resolves + records consent against) the strand and returns the
+ * result on approval.
+ *
+ * Cadre-disclosure timing: the responder reveals its own party id + cadre addresses
+ * — and, for a closed strand returned via provision-then-record, that strand's
+ * membership key — ONLY after the token and disclosure validate; a rejection
+ * discloses none of them.
+ */
+
+import debug from 'debug';
+import { multiaddr, type Multiaddr } from '@multiformats/multiaddr';
+import type { Libp2p } from '@libp2p/interface';
+import type { StrandFormationDisclosure, StrandMembershipInvite } from './types.js';
+import { type ControlStream, writeFrame, withDeadline, withTimeout } from './control-stream.js';
+import { canonicalJson } from './canonical-json.js';
+import { requireEd25519PublicKeyB64 } from './ed25519-key.js';
+import { verifyFormationConsent } from './peer-authorization.js';
+// seed-bootstrap imports neither this protocol nor the manager/solicitation layers,
+// so this import introduces no cycle.
+import { ed25519PublicKeyB64FromPeerId } from './ed25519-key.js';
+import { trailingPeerId } from './peer-dial.js';
+import {
+  formationDeadlines,
+  resolveProvisionTimeoutMs,
+  responderClampReserveMs,
+  splitProvisionBudget
+} from './strand-formation-deadlines.js';
+import {
+  FormationRejectedError,
+  FormationUnreachableError,
+  type FormationRejectionCode
+} from './strand-formation-rejection.js';
+
+const log = debug('sereus:cadre:formation-proto');
+
+/** Protocol id for the native formation transport (parallel to `/sereus/seed/1.0.0`). */
+export const FORMATION_PROTOCOL = '/sereus/formation/1.0.0';
+
+/**
+ * Rejection reason for an invitation that cannot be redeemed — unknown here
+ * (`'token-unknown'`), or expired or fully spent (`'token-spent'`); the code tells them
+ * apart. Shared with `StrandFormationManager`, which reports an `InvitationExhaustedError`
+ * (an invite spent out from under a redemption already in flight) with this SAME wording and
+ * code on purpose: a joiner that lost the race must be indistinguishable from a non-racing
+ * latecomer, so the two sites must never drift apart.
+ */
+export const INVALID_TOKEN_REASON = 'Invalid token';
+
+/** Maximum formation message size (1MB). */
+const MAX_FORMATION_MSG_SIZE = 1024 * 1024;
+
+/**
+ * Default cap on concurrent inbound formation sessions.
+ *
+ * NOTE: a session holds its slot for its whole provisioning budget, 171 s at the default
+ * declared link ({@link formationDeadlines}), so a slow hook or commit holds slots for
+ * minutes. Only a caller holding a valid token AND a valid consent signature reaches
+ * provisioning — a stranger is cut at the contact wait (7 s at the default) or at the first
+ * validation read — so the exposure is one invitee opening many sessions with one token. If
+ * invitation tokens are ever published where untrusted parties can read them, cap in-flight
+ * sessions per token rather than lowering this.
+ */
+const DEFAULT_MAX_CONCURRENT_SESSIONS = 100;
+
+/**
+ * Cap on the strand-network addresses a formation result carries
+ * ({@link FormationResultMessage.strandAddrs}). A node's own strand multiaddrs are a
+ * handful of entries (one per listen transport, plus a circuit-relay reservation), so
+ * 16 is generous for the honest case while keeping the result frame bounded against a
+ * peer that would pad it — either direction, since both sides run the list through
+ * {@link sanitizeStrandAddrs}. The initiator's kept copy is one arriving list, replaced by
+ * the next formation against the same strand, so the same bound holds there.
+ */
+const MAX_STRAND_ADDRS = 16;
+
+// ── Roles ────────────────────────────────────────────────────────────────────
+
+export type FormationParty = 'initiator' | 'responder';
+
+// ── Wire messages (length-prefixed JSON frames) ──────────────────────────────
+
+export interface FormationStrandInfo {
+  strandId: string;
+  createdBy: FormationParty;
+}
+
+export interface FormationDbConnectionInfo {
+  endpoint: string;
+  credentialsRef: string;
+}
+
+export interface FormationProvisionResult {
+  strand: FormationStrandInfo;
+  /**
+   * The strand's membership key (closed-strand read-gating secret), delivered to a
+   * validated invitee for provision-then-record formation. Disclosed only AFTER token
+   * + disclosure validation, exactly like the responder identity/cadre — a rejected or
+   * already-used token discloses neither identity nor key. Absent for open strands.
+   */
+  memberPrivateKey?: string;
+  /**
+   * The joiner's single-use membership invitation into the (closed, bound) host
+   * strand — issued by the responder's live strand runtime against `Strand.Invite`
+   * just before the consent row was recorded. Same disclosure timing as
+   * {@link memberPrivateKey}: present only on an approved result, absent for open
+   * strands and the responder-provisions path. Bounded and shape-checked on the
+   * initiator side ({@link isWellFormedMembershipInvite}) — a hostile responder's
+   * malformed field fails validation rather than crashing the initiator.
+   */
+  membershipInvite?: StrandMembershipInvite;
+  dbConnectionInfo: FormationDbConnectionInfo;
+}
+
+/**
+ * Outcome of the responder's provisioning hook.
+ *
+ * Distinct from a bare {@link FormationProvisionResult} so the hook can REJECT a
+ * formation AFTER token + disclosure validation — e.g. a bound invite naming a host
+ * strand this responder has not yet converged on, or a concurrent-redemption collision.
+ * Without this channel such cases threw inside provisioning, the stream closed with no
+ * result frame, and the initiator saw a read-error/timeout instead of a clean
+ * `approved: false`. A rejection still discloses NO responder identity/cadre.
+ */
+export type ResponderProvisionOutcome =
+  | { approved: true; result: FormationProvisionResult }
+  | FormationRejection;
+
+/**
+ * A refusal as the responder sends it: never without a code. Carries nothing else — no
+ * identity, addresses or keys — so a rejection discloses nothing about the responder.
+ */
+export interface FormationRejection {
+  approved: false;
+  code: FormationRejectionCode;
+  /** Human-facing text for logs; joiners branch on `code`. */
+  reason: string;
+}
+
+/** What the responder's token check yields; an invalid token names which way it failed. */
+export type FormationTokenCheck =
+  | { valid: true }
+  | { valid: false; code: Extract<FormationRejectionCode, 'token-unknown' | 'token-spent'> };
+
+/** Initiator → Responder: carries the real token + disclosure + initiator cadre. */
+export interface FormationContactMessage {
+  /** The real invitation token. */
+  token: string;
+  /** Initiator's member key (peer id) — human-facing identity in logs and `FormStrandResult.memberKey`. */
+  partyId: string;
+  /**
+   * Initiator's base64url ed25519 public key — the key behind `partyId`, written to
+   * `FormationUsage.PeerKey` and covered by BOTH signed digests.
+   */
+  peerKey: string;
+  /** Joiner-minted single-use nonce for THIS redemption; both signed digests cover it. */
+  usageStampId: string;
+  /**
+   * The joiner's signature over the `'consent'` digest (see `formationConsentMessage`
+   * in control-database.ts) — proof the named peer agreed to this redemption.
+   */
+  peerSignature: string;
+  /** The real disclosure, carried verbatim. */
+  disclosure: StrandFormationDisclosure;
+  /** Initiator's real multiaddrs. */
+  cadrePeerAddrs: string[];
+}
+
+/** Responder → Initiator: responder identity/cadre disclosed only after validation. */
+export interface FormationResultMessage {
+  approved: boolean;
+  /**
+   * Why the responder refused; present iff `approved === false`. Optional on this wire type
+   * only because a frame from another version may omit it — the responder always sends one
+   * ({@link FormationRejection}), and the joiner reads a missing one as `'unrecognized'`.
+   */
+  code?: FormationRejectionCode;
+  /** Human-facing text; present iff `approved === false`. */
+  reason?: string;
+  /** Responder's real party id (disclosed only after validation). */
+  partyId?: string;
+  /** Responder's real multiaddrs (omitted on rejection). */
+  cadrePeerAddrs?: string[];
+  /**
+   * The responder's live STRAND-network multiaddrs for the provisioned strand — the
+   * initiator's only cross-party discovery seed, since the strand-addr RPC that resolves
+   * a sibling's strand addrs is membership-gated and answers own-party callers only.
+   *
+   * Disclosed on the same terms as `partyId`/`cadrePeerAddrs`: only after token +
+   * disclosure validation AND an approving provisioning outcome; a rejection carries
+   * none. Signaling-first, each entry ending in `/p2p/<responder strand transport
+   * peerId>` so the initiator can attribute it. OMITTED when the responder holds no live
+   * strand node for the provisioned strand (the responder-provisions path mints a strand
+   * that has not launched yet) — an absent or empty list is legal and means "no
+   * cross-party seed", never a protocol error.
+   */
+  strandAddrs?: string[];
+  /** The provisioned strand/db result (always present on approval). */
+  provisionResult?: FormationProvisionResult;
+}
+
+/** An approving result frame as the responder builds it. */
+type ApprovedResultMessage = FormationResultMessage & { approved: true };
+
+/**
+ * Normalize a strand-address list arriving from — or heading to — the wire: keep only
+ * parsable multiaddr strings, drop duplicates, and cap at {@link MAX_STRAND_ADDRS}.
+ * Order is preserved, so the responder's signaling-first ordering survives.
+ *
+ * Applied on BOTH sides on purpose. The responder bounds what it sends; the initiator
+ * bounds what it stores, because a peer is free to ignore the cap. A malformed entry is
+ * SKIPPED rather than fatal — these are runtime-discovered addresses (same posture as
+ * `extractCircuitRelayTargets` in `delegate-admission.ts`), and one bad entry must not
+ * cost a formation that has otherwise succeeded.
+ */
+export function sanitizeStrandAddrs(addrs: unknown): string[] {
+  if (!Array.isArray(addrs)) return [];
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const entry of addrs) {
+    if (out.length >= MAX_STRAND_ADDRS) break;
+    if (typeof entry !== 'string' || entry.length === 0) {
+      log('strandAddrs: skipping non-string entry %o', entry);
+      continue;
+    }
+    if (seen.has(entry)) continue;
+    try {
+      multiaddr(entry);
+    } catch (error) {
+      // Deliberately not echoing the raw value at error level: it arrived from a remote
+      // peer. The log line below is the observability for a responder announcing junk.
+      log('strandAddrs: skipping unparsable entry: %o', error);
+      continue;
+    }
+    seen.add(entry);
+    out.push(entry);
+  }
+  return out;
+}
+
+// ── Stream framing helpers ───────────────────────────────────────────────────
+
+/**
+ * Reads length-prefixed JSON frames from a libp2p stream one frame at a time.
+ *
+ * Unlike seed delivery (which reads a stream to EOF then parses once), formation
+ * is request/response on a single live stream, so reading must stop at each frame
+ * boundary. The reader buffers across chunk boundaries and retains any overflow
+ * (a following frame coalesced into the same chunk) for the next read.
+ */
+class FrameReader {
+  private readonly iterator: AsyncIterator<Uint8Array>;
+  private readonly maxLength: number;
+  private buffer = new Uint8Array(0);
+
+  constructor(stream: AsyncIterable<Uint8Array>, maxLength = MAX_FORMATION_MSG_SIZE) {
+    this.iterator = stream[Symbol.asyncIterator]();
+    this.maxLength = maxLength;
+  }
+
+  private append(chunk: Uint8Array): void {
+    const next = new Uint8Array(this.buffer.length + chunk.length);
+    next.set(this.buffer, 0);
+    next.set(chunk, this.buffer.length);
+    this.buffer = next;
+  }
+
+  /** Pull chunks until the buffer holds ≥ `need` bytes; false if the stream ended first. */
+  private async fill(need: number): Promise<boolean> {
+    while (this.buffer.length < need) {
+      const { value, done } = await this.iterator.next();
+      if (done) return false;
+      const bytes = value instanceof Uint8Array
+        ? value
+        : (value as { subarray(): Uint8Array }).subarray();
+      this.append(bytes);
+    }
+    return true;
+  }
+
+  async read<T>(): Promise<T> {
+    if (!(await this.fill(4))) {
+      throw new Error('Formation stream closed before length prefix');
+    }
+    const length = new DataView(this.buffer.buffer, this.buffer.byteOffset, this.buffer.byteLength).getUint32(0, false);
+    if (length > this.maxLength) {
+      throw new Error(`Formation frame declares length ${length} exceeding max ${this.maxLength}`);
+    }
+    if (!(await this.fill(4 + length))) {
+      throw new Error(`Formation frame declares length ${length} but stream ended early`);
+    }
+    const json = new TextDecoder().decode(this.buffer.subarray(4, 4 + length));
+    this.buffer = this.buffer.subarray(4 + length);
+    return JSON.parse(json) as T;
+  }
+}
+
+// ── Result validation ────────────────────────────────────────────────────────
+
+/** Matches the placeholder cadre addrs (`cadre-a-1.local`, …) of the removed strand-proto transport. */
+const PLACEHOLDER_CADRE_ADDR = /^cadre-[ab]-\d+\.local$/;
+
+/**
+ * Both halves of a {@link StrandMembershipInvite} are base64url ed25519 key encodings —
+ * 43 chars for 32 bytes. The bound is deliberately loose (a future encoding change must
+ * not silently strand joiners) while still capping what a hostile responder can make the
+ * initiator retain.
+ */
+const MAX_MEMBERSHIP_INVITE_KEY_LENGTH = 256;
+const BASE64URL_KEY = /^[A-Za-z0-9_-]+$/;
+
+/**
+ * Is `value` a well-formed {@link StrandMembershipInvite} — exactly two bounded
+ * base64url strings? The initiator-side shape check for the one attacker-influenced
+ * OBJECT the formation result carries (`strandAddrs` gets the equivalent treatment in
+ * {@link sanitizeStrandAddrs}): a malformed field from a hostile responder must fail
+ * validation, never crash the initiator or be carried into the joiner's invite cache.
+ * `undefined` is NOT well-formed — absence is legal on the result and callers gate on
+ * presence first.
+ */
+export function isWellFormedMembershipInvite(value: unknown): value is StrandMembershipInvite {
+  if (typeof value !== 'object' || value === null) return false;
+  const { inviteKey, invitePrivateKey } = value as Record<string, unknown>;
+  const wellFormedKey = (key: unknown): boolean =>
+    typeof key === 'string' && key.length > 0 && key.length <= MAX_MEMBERSHIP_INVITE_KEY_LENGTH && BASE64URL_KEY.test(key);
+  return wellFormedKey(inviteKey) && wellFormedKey(invitePrivateKey);
+}
+
+/**
+ * Structural check on a `responderCreates` result: the responder must have approved,
+ * disclosed a non-empty real identity + cadre (not the legacy `cadre-*.local`
+ * placeholders), and returned a strand vouched for by the responder party with a real id.
+ *
+ * `createdBy: 'responder'` means "the responder party vouches for / returns this strand."
+ * Under provision-then-record that strand was minted owner-signed earlier (not created
+ * in-session), but it is still the responder party returning its own strand, so the marker
+ * — and this structural validator — stay unchanged.
+ *
+ * The behavioral floor for the initiator: a responder that returns an arbitrary/empty
+ * `strandId` or omits its disclosed identity is rejected, not silently accepted.
+ */
+export function isValidResponderCreatesResult(response: FormationResultMessage): boolean {
+  if (!response.approved) return false;
+  if (!response.partyId) return false;
+  const addrs = response.cadrePeerAddrs;
+  if (!addrs || addrs.length === 0) return false;
+  if (addrs.some((a) => PLACEHOLDER_CADRE_ADDR.test(a))) return false;
+  const provision = response.provisionResult;
+  if (!provision?.strand?.strandId) return false;
+  if (provision.strand.createdBy !== 'responder') return false;
+  // Optional, but when present it must be well-formed: a malformed invitation is a
+  // membership the joiner can never redeem, so reject the result rather than accept a
+  // formation that would leave a half-member.
+  if (provision.membershipInvite !== undefined && !isWellFormedMembershipInvite(provision.membershipInvite)) {
+    return false;
+  }
+  return true;
+}
+
+// ── Responder (listener) ─────────────────────────────────────────────────────
+
+export interface FormationListenerOptions {
+  /** Validate the invitation token; an invalid one says whether it is unknown here or spent. */
+  validateToken(token: string): Promise<FormationTokenCheck>;
+  /** Validate the initiator's disclosure with the REAL token + disclosure. */
+  validateDisclosure(token: string, disclosure: StrandFormationDisclosure): Promise<boolean>;
+  /**
+   * Provision (or, for provision-then-record, resolve + record consent against) the
+   * strand (`responderCreates`) for the given initiator. The WHOLE contact message is
+   * threaded in: the hook needs the REAL token to map the bound host strand, and the
+   * joiner's `peerKey`/`usageStampId`/`peerSignature` to write the consent columns.
+   *
+   * Returns a {@link ResponderProvisionOutcome}: the hook may REJECT post-validation
+   * (e.g. an unconverged host strand) and the listener turns that into a clean,
+   * non-disclosing `approved: false` reply rather than dropping the result frame.
+   *
+   * `signal` is aborted when the listener's work budget expires: a hook that observes it
+   * BEFORE writing abandons the redemption and leaves the invite unspent. Optional so
+   * signal-unaware hooks (tests, mocks) stay assignable.
+   */
+  provisionStrand(contact: FormationContactMessage, signal?: AbortSignal): Promise<ResponderProvisionOutcome>;
+  /** Responder identity, disclosed only AFTER token + disclosure validation passes. */
+  getResponderIdentity(): { partyId: string; cadrePeerAddrs: string[] };
+  /**
+   * This node's live STRAND-network multiaddrs for a provisioned strand, read on the
+   * approval path only (same disclosure timing as {@link getResponderIdentity}) and
+   * carried back as {@link FormationResultMessage.strandAddrs}.
+   *
+   * Optional, and an empty answer is legal: the strand may not be running here yet (the
+   * responder-provisions path mints it during this very session). The listener cannot
+   * reach the strand runtime itself, so this is the seam `CadreNode` wires to its own
+   * per-strand address lookup.
+   */
+  resolveStrandAddrs?(strandId: string): string[];
+  /**
+   * This machine's declared link round trip (`NetworkConfig.linkRoundTripMs`), from which
+   * every deadline below takes its default ({@link formationDeadlines}). The default
+   * declaration when omitted.
+   */
+  linkRoundTripMs?: number;
+  /** Whole-session budget; default `sessionMs` of the derived ladder. */
+  sessionTimeoutMs?: number;
+  /** Budget for the contact-frame read; default `awaitContactMs` of the derived ladder. */
+  stepTimeoutMs?: number;
+  /**
+   * Budget for the `provisionStrand` hook call, work plus settle grace — distinct from
+   * `stepTimeoutMs` because provisioning is real work, not a bare wire read. Default
+   * `provisionWorkMs + provisionGraceMs` of the derived ladder (171 s at the default
+   * declaration); `0`/unset uses the default; a value that would outlive the session is
+   * clamped ({@link resolveProvisionTimeoutMs}). See {@link formationDeadlines} for the ordering.
+   */
+  provisionTimeoutMs?: number;
+  maxConcurrentSessions?: number;
+}
+
+/**
+ * Responder side of the native formation protocol. Registers a libp2p handler and
+ * drives each inbound stream through token + disclosure validation, provisioning,
+ * and result delivery — enforcing the cadre-disclosure timing rule (responder cadre
+ * is revealed only after validation; rejections disclose nothing).
+ */
+export class FormationListener {
+  private readonly options: FormationListenerOptions;
+  private readonly sessionTimeoutMs: number;
+  private readonly awaitContactMs: number;
+  private readonly provisionWorkMs: number;
+  private readonly provisionGraceMs: number;
+  private readonly maxConcurrentSessions: number;
+  private readonly registered = new Set<Libp2p>();
+  private activeSessions = 0;
+  private sessionCounter = 0;
+
+  constructor(options: FormationListenerOptions) {
+    this.options = options;
+    const deadlines = formationDeadlines(options.linkRoundTripMs);
+    this.sessionTimeoutMs = options.sessionTimeoutMs ?? deadlines.sessionMs;
+    this.awaitContactMs = options.stepTimeoutMs ?? deadlines.awaitContactMs;
+    const split = splitProvisionBudget(resolveProvisionTimeoutMs(
+      options.provisionTimeoutMs, deadlines.provisionWorkMs + deadlines.provisionGraceMs,
+      this.sessionTimeoutMs, this.awaitContactMs + deadlines.validationMs, 'FormationListener',
+      responderClampReserveMs(deadlines, this.awaitContactMs)
+    ), deadlines.provisionGraceMs);
+    this.provisionWorkMs = split.workMs;
+    this.provisionGraceMs = split.graceMs;
+    this.maxConcurrentSessions = options.maxConcurrentSessions ?? DEFAULT_MAX_CONCURRENT_SESSIONS;
+  }
+
+  /** Number of in-flight inbound sessions. */
+  get activeCount(): number {
+    return this.activeSessions;
+  }
+
+  /** Register the formation handler on `node`. Rejects when libp2p refuses the registration. */
+  async register(node: Libp2p, protocolId: string = FORMATION_PROTOCOL): Promise<void> {
+    if (this.registered.has(node)) {
+      log('node already registered');
+      return;
+    }
+    await node.handle(protocolId, async (rawStream: unknown, _connection: unknown) => {
+      await this.handleStream(rawStream as ControlStream);
+    });
+    this.registered.add(node);
+    log('formation listener registered (%s)', protocolId);
+  }
+
+  async unregister(node: Libp2p, protocolId: string = FORMATION_PROTOCOL): Promise<void> {
+    if (!this.registered.has(node)) return;
+    await node.unhandle(protocolId);
+    this.registered.delete(node);
+    log('formation listener unregistered (%s)', protocolId);
+  }
+
+  private async handleStream(stream: ControlStream): Promise<void> {
+    if (this.activeSessions >= this.maxConcurrentSessions) {
+      const rejection: FormationRejection = { approved: false, code: 'busy', reason: 'Too many concurrent formation sessions' };
+      try { writeFrame(stream, rejection); } catch { /* best effort */ }
+      try { await stream.close(); } catch { /* ignore */ }
+      return;
+    }
+    const id = ++this.sessionCounter;
+    this.activeSessions++;
+    try {
+      await withTimeout(this.sessionTimeoutMs, `Formation session#${id}`, () => this.runSession(id, stream));
+    } catch (err) {
+      log('formation session #%d failed: %o', id, err);
+    } finally {
+      this.activeSessions--;
+      try { await stream.close(); } catch { /* ignore */ }
+    }
+  }
+
+  /**
+   * Run the provisioning hook under its WORK budget — the provisioning budget minus the
+   * trailing settle grace ({@link splitProvisionBudget}).
+   *
+   * When the work budget expires the hook's signal is aborted, then
+   * {@link settleWithinGrace} waits out the grace for the aborted work to settle anyway.
+   * Returns `undefined` for "timed out" — which the caller turns into a retryable rejection
+   * frame — and rethrows every other failure so it reaches the internal-error path.
+   *
+   * Deliberately not `withDeadline`: that exposes neither the timed-out flag nor the signal
+   * outside its `op`, and both are needed here.
+   */
+  private async provision(id: number, contact: FormationContactMessage): Promise<ResponderProvisionOutcome | undefined> {
+    const controller = new AbortController();
+    let timedOut = false;
+    const pending = this.options.provisionStrand(contact, controller.signal);
+    try {
+      return await withTimeout(
+        this.provisionWorkMs,
+        `Formation provisioning#${id}`,
+        () => pending,
+        () => { timedOut = true; controller.abort(); }
+      );
+    } catch (err) {
+      if (!timedOut) throw err;
+      log(
+        'formation session #%d provisioning work budget expired after %dms; aborted, settling up to %dms',
+        id, this.provisionWorkMs, this.provisionGraceMs
+      );
+      return await this.settleWithinGrace(id, pending);
+    }
+  }
+
+  /**
+   * Wait out the settle grace for an ABORTED provisioning, adopting a late success.
+   *
+   * A hook that observed the abort before issuing its `FormationUsage` insert rejects (with
+   * `FormationAbortedError`) and leaves the invite unspent → reported as a timeout. A hook
+   * that had already written cannot be un-written (the table is append-only), so if it lands
+   * inside the grace its outcome is ADOPTED — the joiner is told the truth (approved, or the
+   * hook's own rejection reason) rather than "timed out" over a spent invite.
+   *
+   * The grace is derived to contain one seat read plus one commit at the declared link
+   * ({@link formationDeadlines}), which is exactly what runs after the insert attempt passes
+   * its abort check, so at that link the late outcome lands inside it.
+   *
+   * NOTE: a commit that outlasts even the derived grace (a link slower than declared, a
+   * configured `provisionTimeoutMs` whose half-cap shrank the grace, or a commit phase that
+   * re-picks an unanswering coordinator, which Optimystic lets run to its transaction budget,
+   * 170 s at the default declared link) still tells the joiner
+   * 'timed out' while its one-time invite is in fact spent, and since every retry mints a
+   * fresh keypair no recovery path can match it. Nothing can un-spend an append-only row, so
+   * the late-settle logging below is the observability for it; if it is seen in the wild,
+   * raise the declared link rather than this grace.
+   */
+  private async settleWithinGrace(
+    id: number,
+    pending: Promise<ResponderProvisionOutcome>
+  ): Promise<ResponderProvisionOutcome | undefined> {
+    let stillPending = false;
+    try {
+      const outcome = await withTimeout(
+        this.provisionGraceMs,
+        `Formation settle#${id}`,
+        () => pending,
+        () => { stillPending = true; }
+      );
+      log('formation session #%d provisioning settled within its grace: approved=%s — adopting', id, outcome.approved);
+      return outcome;
+    } catch (err) {
+      if (!stillPending) {
+        log('formation session #%d provisioning failed after its abort: %o', id, err);
+        return undefined;
+      }
+      log('formation session #%d provisioning still pending after its %dms grace', id, this.provisionGraceMs);
+      // Log how it eventually settled so a late failure is not swallowed by the two
+      // abandoned `withTimeout` calls.
+      void pending.then(
+        (late) => log('formation session #%d provisioning settled after its grace: approved=%s', id, late.approved),
+        (err2) => log('formation session #%d provisioning failed after its grace: %o', id, err2)
+      );
+      return undefined;
+    }
+  }
+
+  /**
+   * Joiner-consent pre-check — the legibility twin of the schema's
+   * `FormationUsage.PeerConsented` CHECK, exactly as `verifyFormationApproval` is for the
+   * approver's vouch. The database constraint stays the authority; this turns a bad consent
+   * into a clean 'Invalid joiner consent' rejection instead of an opaque CHECK failure at
+   * commit. Runs BEFORE token/disclosure validation: it is the cheapest check (pure local
+   * crypto, no DB read) and a rejection discloses nothing.
+   *
+   * Also pins `partyId` to `peerKey`: an ed25519 peer id is an identity multihash of the
+   * very key, and this is the ONLY layer that can check the match — SQL cannot unwrap a
+   * multihash, and `partyId` itself is never stored.
+   */
+  private isJoinerConsentValid(id: number, contact: FormationContactMessage): boolean {
+    try {
+      requireEd25519PublicKeyB64(contact.peerKey, 'joiner peer key');
+    } catch {
+      // Deliberately not rethrown or echoed: the helper's error message embeds the whole
+      // rejected value, and this one arrived from a remote peer (the cap-the-echo case its
+      // own NOTE warns about). Log without the raw value instead.
+      log('formation session #%d: joiner peer key is not a base64url ed25519 public key', id);
+      return false;
+    }
+    const embedded = ed25519PublicKeyB64FromPeerId(contact.partyId);
+    if (!embedded || embedded !== contact.peerKey) {
+      log('formation session #%d: partyId does not embed the presented peer key', id);
+      return false;
+    }
+    const consentOk = verifyFormationConsent({
+      token: contact.token,
+      usageStampId: contact.usageStampId,
+      peerKey: contact.peerKey,
+      disclosure: canonicalJson(contact.disclosure),
+      peerSig: contact.peerSignature
+    });
+    if (!consentOk) {
+      log('formation session #%d: joiner consent signature failed verification', id);
+      return false;
+    }
+    return true;
+  }
+
+  /**
+   * The strand addresses to disclose for an APPROVED provisioning, sanitized and capped.
+   *
+   * Never throws: a hook that fails (a strand runtime torn down mid-session) costs the
+   * joiner its cross-party seed, not the formation it has already earned — the seed is
+   * an optimization, the consent row is the commitment.
+   */
+  private strandAddrsFor(id: number, strandId: string): string[] {
+    if (!this.options.resolveStrandAddrs) return [];
+    try {
+      return sanitizeStrandAddrs(this.options.resolveStrandAddrs(strandId));
+    } catch (err) {
+      log('formation session #%d: strand-addr lookup for %s failed (continuing): %o', id, strandId, err);
+      return [];
+    }
+  }
+
+  private async runSession(id: number, stream: ControlStream): Promise<void> {
+    // Track whether ANY frame has been written so the catch below can convert an
+    // unexpected internal error into a non-disclosing rejection ONLY when nothing has
+    // gone out yet. This closes the "stream closed with no result frame" class of bug.
+    let wroteFrame = false;
+    const send = (msg: FormationRejection | ApprovedResultMessage): void => {
+      writeFrame(stream, msg);
+      wroteFrame = true;
+    };
+
+    try {
+      const reader = new FrameReader(stream);
+      const contact = await withTimeout(this.awaitContactMs, `Formation await-contact#${id}`, () => reader.read<FormationContactMessage>());
+      log('formation session #%d contact: token=%s party=%s', id, contact.token, contact.partyId);
+
+      if (!this.isJoinerConsentValid(id, contact)) {
+        send({ approved: false, code: 'consent-invalid', reason: 'Invalid joiner consent' });
+        return;
+      }
+
+      const tokenResult = await this.options.validateToken(contact.token);
+      if (!tokenResult.valid) {
+        send({ approved: false, code: tokenResult.code, reason: INVALID_TOKEN_REASON });
+        return;
+      }
+
+      const disclosureOk = await this.options.validateDisclosure(contact.token, contact.disclosure);
+      if (!disclosureOk) {
+        send({ approved: false, code: 'disclosure-invalid', reason: 'Invalid disclosure' });
+        return;
+      }
+
+      const outcome = await this.provision(id, contact);
+      if (!outcome) {
+        // Reported as its own retryable reason rather than falling through to the generic
+        // catch below, which would report the misleading 'Internal formation error'.
+        send({ approved: false, code: 'provisioning-timeout', reason: 'Formation provisioning timed out' });
+        return;
+      }
+      if (!outcome.approved) {
+        // A post-validation rejection still discloses NEITHER identity NOR cadre, exactly
+        // like the token/disclosure rejections above — copied field by field so nothing else
+        // a hook put on its outcome reaches the wire.
+        send({ approved: false, code: outcome.code, reason: outcome.reason });
+        return;
+      }
+      // Validation + provisioning passed → safe to disclose responder identity/cadre.
+      const identity = this.options.getResponderIdentity();
+      const strandAddrs = this.strandAddrsFor(id, outcome.result.strand.strandId);
+      send({
+        approved: true,
+        partyId: identity.partyId,
+        cadrePeerAddrs: identity.cadrePeerAddrs,
+        // Omitted rather than sent empty: an absent field and an empty list mean the same
+        // thing to the initiator, and omitting keeps every rejection-parity assertion a
+        // plain `toBeUndefined()`.
+        ...(strandAddrs.length > 0 ? { strandAddrs } : {}),
+        provisionResult: outcome.result
+      });
+    } catch (err) {
+      // Defense-in-depth: if an unexpected internal error escapes BEFORE any frame was
+      // written (e.g. a future provisionStrand-hook bug), convert it into a non-disclosing
+      // protocol rejection so the initiator sees a clean error instead of a read-error/
+      // timeout. If a frame was already sent, leave the stream as-is and let handleStream
+      // log + close. Re-throw either way so the failure is still recorded — this is a
+      // deliberate, logged conversion, not silent.
+      if (!wroteFrame) {
+        const internalError: FormationRejection = { approved: false, code: 'internal', reason: 'Internal formation error' };
+        try { writeFrame(stream, internalError); } catch { /* stream already broken */ }
+      }
+      throw err;
+    }
+  }
+}
+
+// ── Initiator (dialer) ───────────────────────────────────────────────────────
+
+export interface FormationDialOptions {
+  /** The contact message to send (real token, partyId, disclosure, initiator cadre). */
+  contact: FormationContactMessage;
+  /**
+   * Responder multiaddrs to dial, normally the invitation's bootstrap list. Every entry that
+   * parses is tried, in the order libp2p's default address sorter picks (loopback last, then
+   * public before private, then circuit after direct), until one connects, all under one
+   * dial-connect budget (`dialTimeoutMs`); an entry that does not parse is skipped.
+   *
+   * {@link dialFormation} dials ONE machine, so every entry must name the same trailing peer
+   * id (or none). An invitation names several machines of the inviting party; hand it to
+   * {@link dialFormationByMachine}, which splits the list by trailing peer id, drops entries
+   * that name no peer, and runs one {@link dialFormation} session per machine, in the order
+   * each machine first appears. Each session keeps its own deadline ladder, so a machine that
+   * cannot be dialled costs one `dialTimeoutMs` and one that accepts the contact and then
+   * stalls costs up to one `sessionTimeoutMs`; `CadreNode.createOpenInvitation` names at most
+   * four machines.
+   */
+  responderAddrs: string[];
+  /** Validate the responder's result; a false return aborts the formation. */
+  validateResponse(response: FormationResultMessage): Promise<boolean>;
+  /**
+   * This machine's declared link round trip (`NetworkConfig.linkRoundTripMs`), from which
+   * every deadline below takes its default ({@link formationDeadlines}). The default
+   * declaration when omitted.
+   */
+  linkRoundTripMs?: number;
+  /** Whole-session budget; default `sessionMs` of the derived ladder. */
+  sessionTimeoutMs?: number;
+  /**
+   * Budget for `dial-connect`: opening the connection, through a relay if need be, and
+   * negotiating the formation protocol. Default `dialMs` of the derived ladder.
+   */
+  dialTimeoutMs?: number;
+  /**
+   * Budget for the `await-response` read only (the responder's provisioning plus the reply's
+   * travel time). Default `initiatorAwaitResponseMs` of the derived ladder; `0`/unset uses
+   * the default; a value that would outlive the session is clamped. See
+   * {@link formationDeadlines} for the ordering.
+   */
+  provisionTimeoutMs?: number;
+  protocolId?: string;
+}
+
+/**
+ * What one successful formation dial yields the initiator.
+ *
+ * The provisioned strand travels in {@link FormationProvisionResult}, but the responder's
+ * strand-network addresses are NOT part of that structure — they are a disclosure of the
+ * responder's live runtime, alongside `partyId`/`cadrePeerAddrs`, not a property of the
+ * strand row. Returning them beside the provision result keeps that separation while
+ * still handing the caller the one thing it needs to seed a cross-party mesh.
+ *
+ * `strandAddrs` is always an array and is frequently EMPTY — see
+ * {@link FormationResultMessage.strandAddrs}.
+ */
+export interface FormationDialResult {
+  provision: FormationProvisionResult;
+  /** Sanitized + capped ({@link sanitizeStrandAddrs}); `[]` when the responder sent none. */
+  strandAddrs: string[];
+}
+
+/**
+ * Open the formation stream under the dial deadline, cancelling the dial when it expires.
+ *
+ * The deadline's signal goes into `dialProtocol`, so an expired dial is abandoned by libp2p
+ * rather than left running. A dial that settles in the same tick the deadline fires loses
+ * the race to the timeout rejection and would leave its stream open with nobody to close
+ * it, so a stream that arrives after the signal aborted is reset here — the same treatment
+ * `exchangeFrame` (`control-stream.ts`) gives a stream dialed past its deadline. A late
+ * rejection is the abort itself, or reaches the caller through the awaited copy, so the
+ * handler below only stops it being reported as unhandled.
+ *
+ * NOTE: libp2p tries `addrs` one after another, and they all share this one dial budget. Its
+ * per-address limit (`addressDialTimeout`: ten link round trips plus two admission decisions, as
+ * `optimysticDialLimits` states it) is longer than `dialTimeoutMs` (`formationDeadlines().dialMs`:
+ * five round trips plus one decision) at every declaration, so it never cuts off an address
+ * inside this dial. An address that hangs without answering (a black-holed relay host) uses the
+ * whole budget, and the join moves on to the party's next machine
+ * ({@link dialFormationByMachine}) rather than to this machine's next address; an address that is
+ * refused fails fast and still hands over to the next. A budget per address here would overrun
+ * the session or shrink the await-response budget ({@link formationDeadlines}). If joins through a
+ * hung first address are seen in practice, give each address a sub-budget or dial them in parallel.
+ * The same dial can also be joined to another dial of the responder in flight (the queue keys
+ * jobs by peer id — see `peer-dial.ts` → `dialAddr`), which then holds this one on that job's
+ * address; the remedy, when that is seen, is the same per-address dial.
+ */
+function openFormationStream(node: Libp2p, addrs: Multiaddr[], protocolId: string, dialTimeoutMs: number): Promise<ControlStream> {
+  return withDeadline(dialTimeoutMs, 'Formation dial-connect', async (signal) => {
+    const pending = node.dialProtocol(addrs, protocolId, { signal });
+    void pending.then(
+      (stream) => {
+        if (signal.aborted) {
+          (stream as unknown as ControlStream).abort(new Error('Formation dial-connect resolved after its deadline'));
+        }
+      },
+      () => { /* surfaced through the awaited copy, or the abort itself */ }
+    );
+    try {
+      return await pending as unknown as ControlStream;
+    } catch (error) {
+      throw describeAllAddressesFailed(error);
+    }
+  });
+}
+
+const NO_RESPONDER_ADDRS = 'No responder addresses available for formation';
+
+/**
+ * Parse the responder addresses, skipping any entry that does not parse: the list comes from
+ * a stranger's invitation, and one bad entry must not fail an otherwise good list. Entries
+ * naming different peers are left for libp2p to refuse; {@link dialFormationByMachine} hands
+ * this one machine's addresses at a time.
+ */
+function parseResponderAddrs(addrs: string[]): Multiaddr[] {
+  const parsed: Multiaddr[] = [];
+  for (const addr of addrs) {
+    const ma = parseResponderAddr(addr);
+    if (ma) parsed.push(ma);
+  }
+  if (parsed.length === 0) {
+    throw new FormationUnreachableError(NO_RESPONDER_ADDRS);
+  }
+  return parsed;
+}
+
+function parseResponderAddr(addr: string): Multiaddr | null {
+  try {
+    return multiaddr(addr);
+  } catch (error) {
+    log('responderAddrs: skipping unparsable entry: %o', error);
+    return null;
+  }
+}
+
+/** One machine of the inviting party, and the invitation's addresses for it. */
+interface ResponderMachine {
+  peerId: string;
+  addrs: string[];
+}
+
+/**
+ * Split the responder addresses by the machine each reaches (its trailing peer id), keeping
+ * the order in which each machine first appears. An entry that does not parse, or names no
+ * peer, is dropped: every address an inviter mints (`getMultiaddrs()`, `resolvePeerAddrs`)
+ * names its machine, and libp2p refuses one dial that mixes named and unnamed addresses.
+ */
+function groupResponderAddrsByMachine(addrs: string[]): ResponderMachine[] {
+  const machines = new Map<string, string[]>();
+  for (const addr of addrs) {
+    const ma = parseResponderAddr(addr);
+    if (!ma) continue;
+    const peerId = trailingPeerId(ma);
+    if (!peerId) {
+      log('responderAddrs: skipping %s — it names no machine', addr);
+      continue;
+    }
+    const group = machines.get(peerId);
+    if (group) group.push(addr);
+    else machines.set(peerId, [addr]);
+  }
+  return [...machines].map(([peerId, group]) => ({ peerId, addrs: group }));
+}
+
+/**
+ * Worth asking the next machine of the inviting party: it could not be reached, or it answered
+ * with a refusal a sibling may not repeat (the invitation not replicated to it yet, the host
+ * strand not running there, …). A final refusal is the party's answer, not one machine's.
+ */
+function shouldTryNextMachine(error: unknown): error is FormationUnreachableError | FormationRejectedError {
+  return error instanceof FormationUnreachableError || (error instanceof FormationRejectedError && error.retryable);
+}
+
+/**
+ * Every machine failed without a refusal. A single machine's error already names each address
+ * it tried, so it is thrown as is; several are restated as one error naming each machine.
+ */
+function noMachineReached(failures: Array<{ peerId: string; error: FormationUnreachableError }>): FormationUnreachableError {
+  if (failures.length === 1) return failures[0].error;
+  const errors = failures.map((failure) => failure.error);
+  return new FormationUnreachableError(
+    `Formation could not reach any of the inviter's ${failures.length} machines: ` +
+      failures.map((failure) => `${failure.peerId}: ${failure.error.message}`).join('; '),
+    { cause: new AggregateError(errors, 'Every inviting machine was unreachable') }
+  );
+}
+
+/**
+ * libp2p reports a dial in which every address failed as `AggregateError('All multiaddr dials
+ * failed')`, which names none of them; restate it with each address's own error, which names
+ * its host and port. A dial that tried only one address already surfaces that address's own
+ * error, so anything else passes through unchanged.
+ */
+function describeAllAddressesFailed(error: unknown): unknown {
+  if (!(error instanceof AggregateError)) return error;
+  const reasons = error.errors.map((reason: unknown) => reason instanceof Error ? reason.message : String(reason));
+  return new FormationUnreachableError(
+    `Formation could not reach the inviter at any of the ${reasons.length} addresses tried: ${reasons.join('; ')}`,
+    { cause: error }
+  );
+}
+
+/** Report a failure that came before any answer as {@link FormationUnreachableError}, keeping its message. */
+function asUnreachable(error: unknown): FormationUnreachableError {
+  if (error instanceof FormationUnreachableError) return error;
+  return new FormationUnreachableError(error instanceof Error ? error.message : String(error), { cause: error });
+}
+
+/**
+ * Open the formation stream, send the contact, and read back the one result frame, closing
+ * the stream either way. Nothing here has an answer from the responder yet, so the caller
+ * reports any failure as {@link FormationUnreachableError} — a frame too large or not JSON
+ * included, since it is not an answer either.
+ */
+async function exchangeContact(
+  node: Libp2p,
+  addrs: Multiaddr[],
+  contact: FormationContactMessage,
+  budgets: { protocolId: string; dialTimeoutMs: number; awaitResponseMs: number }
+): Promise<FormationResultMessage> {
+  const stream = await openFormationStream(node, addrs, budgets.protocolId, budgets.dialTimeoutMs);
+  try {
+    const reader = new FrameReader(stream);
+    writeFrame(stream, contact);
+    return await withTimeout(budgets.awaitResponseMs, 'Formation await-response', () => reader.read<FormationResultMessage>());
+  } finally {
+    try { await stream.close(); } catch { /* ignore */ }
+  }
+}
+
+/**
+ * Turn the responder's answer into the dial's result. A refusal throws
+ * {@link FormationRejectedError}; an approval that fails validation throws a plain `Error`,
+ * since that is a misbehaving responder rather than a refusal.
+ */
+async function acceptResult(
+  response: FormationResultMessage,
+  validateResponse: FormationDialOptions['validateResponse']
+): Promise<FormationDialResult> {
+  if (!response.approved) {
+    throw new FormationRejectedError(response.code, response.reason);
+  }
+  if (!(await validateResponse(response))) throw new Error('Responder result failed validation');
+
+  if (!response.provisionResult) throw new Error('Missing provision result for responderCreates mode');
+  // Sanitized HERE — the wire boundary — so nothing above this call ever handles an
+  // unvalidated, unbounded address list from a remote peer.
+  return { provision: response.provisionResult, strandAddrs: sanitizeStrandAddrs(response.strandAddrs) };
+}
+
+/**
+ * Initiator side of the native formation protocol. Dials the responder, sends the
+ * contact (carrying the real disclosure/token/cadre), validates the responder's
+ * result, and returns the strand the responder provisioned plus the responder's
+ * strand-network addresses (see {@link FormationDialResult}).
+ *
+ * Throws {@link FormationUnreachableError} for every failure before a result frame is read
+ * (including the session deadline passing first), {@link FormationRejectedError} when the
+ * responder refuses, and a plain `Error` for an approval that fails validation.
+ */
+export async function dialFormation(node: Libp2p, options: FormationDialOptions): Promise<FormationDialResult> {
+  const addrs = parseResponderAddrs(options.responderAddrs);
+  const protocolId = options.protocolId ?? FORMATION_PROTOCOL;
+  const deadlines = formationDeadlines(options.linkRoundTripMs);
+  const sessionTimeoutMs = options.sessionTimeoutMs ?? deadlines.sessionMs;
+  const dialTimeoutMs = options.dialTimeoutMs ?? deadlines.dialMs;
+  const awaitResponseMs = resolveProvisionTimeoutMs(
+    options.provisionTimeoutMs, deadlines.initiatorAwaitResponseMs,
+    sessionTimeoutMs, dialTimeoutMs, 'dialFormation'
+  );
+
+  let answered = false;
+  try {
+    return await withTimeout(sessionTimeoutMs, 'Formation dial', async () => {
+      const response = await exchangeContact(node, addrs, options.contact, { protocolId, dialTimeoutMs, awaitResponseMs });
+      answered = true;
+      return await acceptResult(response, options.validateResponse);
+    });
+  } catch (error) {
+    throw answered ? error : asUnreachable(error);
+  }
+}
+
+/**
+ * Initiator side for a whole invitation: one {@link dialFormation} session per machine of the
+ * inviting party the bootstrap list names (see {@link FormationDialOptions.responderAddrs}), in
+ * order, until one approves.
+ *
+ * A machine that cannot be reached, or that refuses retryably, hands over to the next. A final
+ * refusal, or an approval that fails validation, is thrown at once: another machine of the
+ * same party would answer the same, and an approval may already have spent the invitation.
+ * With no machine left, throws the last retryable refusal when any machine answered (the party
+ * is reachable but not ready, which says more than "unreachable"), otherwise one
+ * {@link FormationUnreachableError} naming each machine's failure.
+ *
+ * Every session sends the SAME contact. `FormationUsage` is keyed by the contact's
+ * `usageStampId`, so at most one machine of the inviting party can record this redemption,
+ * even when one the joiner gave up on was still committing it.
+ */
+export async function dialFormationByMachine(node: Libp2p, options: FormationDialOptions): Promise<FormationDialResult> {
+  const machines = groupResponderAddrsByMachine(options.responderAddrs);
+  if (machines.length === 0) {
+    throw new FormationUnreachableError(NO_RESPONDER_ADDRS);
+  }
+  const unreached: Array<{ peerId: string; error: FormationUnreachableError }> = [];
+  let refusal: FormationRejectedError | undefined;
+  for (const machine of machines) {
+    try {
+      return await dialFormation(node, { ...options, responderAddrs: machine.addrs });
+    } catch (error) {
+      if (!shouldTryNextMachine(error)) throw error;
+      log('formation via %s failed (%s), trying the next inviting machine', machine.peerId, error.message);
+      if (error instanceof FormationRejectedError) refusal = error;
+      else unreached.push({ peerId: machine.peerId, error });
+    }
+  }
+  throw refusal ?? noMachineReached(unreached);
+}