@serfab/cadre-core 1.6.0 → 1.8.0

package/src/strand-formation-manager.ts

@@ -1,647 +1,700 @@
-import debug from 'debug';
-import { fromString as uint8ArrayFromString } from 'uint8arrays';
-import type { Libp2p } from '@libp2p/interface';
-import type {
-  OpenInvitation,
-  FormStrandResult,
-  StrandFormationDisclosure,
-  StrandMembershipInvite
-} from './types.js';
-import {
-  FormationApprovalError,
-  type FormationApprovalFailure
-} from './formation-approval.js';
-// control-database does not import this manager, so this import introduces no cycle.
-import { FormationAbortedError, InvitationExhaustedError } from './control-database.js';
-import { PreSplitStrandIdentityError } from './strand-membership-writer.js';
-import { mintPlaceholderStrandId } from './strand-id.js';
-import { canonicalJson } from './canonical-json.js';
-import type {
-  DisclosureValidator,
-  FormationUsageRecorder,
-  ResolvedHostStrand,
-  StrandProvisioner,
-  FormationResponseValidator
-} from './strand-solicitation.js';
-import {
-  FormationListener,
-  INVALID_TOKEN_REASON,
-  PROVISION_RESPONSE_TRAVEL_MARGIN_MS,
-  dialFormation,
-  isValidResponderCreatesResult,
-  isWellFormedMembershipInvite,
-  type FormationContactMessage,
-  type FormationProvisionResult,
-  type FormationResultMessage,
-  type ResponderProvisionOutcome
-} from './strand-formation-protocol.js';
-
-const log = debug('sereus:cadre:formation-manager');
-
-/**
- * Largest serialized disclosure a responder will accept (8 KiB). The disclosure is
- * attacker-influenced text destined for a replicated table (`FormationUsage.Disclosure`)
- * and for the approval hook's signed digest — the cap bounds both, and is enforced BEFORE
- * any database read or hook contact so an oversized blob costs nothing downstream.
- */
-const MAX_DISCLOSURE_BYTES = 8 * 1024;
-
-/**
- * How long a formation-issued strand membership invitation stays redeemable (7 days).
- * The responder's {@link StrandFormationManagerOptions.issueMembershipInvite} hook stamps
- * `now + this` as the `Strand.Invite.Expiration`. Long enough for a slow joiner to bring
- * its strand node up and redeem; short enough that a lost formation result does not leave
- * a live bearer credential in the strand forever. An expired invitation rolls the
- * redemption back cleanly (the schema's `NotExpired` gate) — the joiner's recovery is a
- * fresh formation, which issues a fresh invitation.
- */
-export const MEMBERSHIP_INVITE_TTL_MS = 7 * 24 * 3600_000;
-
-/**
- * Rejection reason for a bound CLOSED-strand redemption whose responder could not issue
- * the joiner's membership invitation — the host strand runtime not live on this
- * responder, no party identity key yet, or the strand DB refusing the `Strand.Invite`
- * write. Retryable on purpose, and rejected BEFORE the consent row is recorded, so the
- * formation token stays unspent: approving without an invitation would admit a joiner
- * that looks joined but can never become a member, and a responder not running the
- * strand cannot serve the joiner's sync anyway. The one permanent failure,
- * a pre-split host strand, gets {@link HOST_STRAND_MUST_BE_RECREATED_REASON} instead.
- */
-export const MEMBERSHIP_INVITE_UNAVAILABLE_REASON = 'Strand membership invitation unavailable, retry';
-
-/**
- * Rejection reason for a bound CLOSED-strand redemption whose host strand was founded
- * before the per-party identity split: the responder's founder launch refused it
- * (`PreSplitStrandIdentityError`), so no invitation can ever be issued into it. Not
- * retryable — the host must recreate the strand and issue a fresh invitation. Like
- * {@link MEMBERSHIP_INVITE_UNAVAILABLE_REASON}, rejected before consent is recorded, so
- * the formation token stays unspent.
- */
-export const HOST_STRAND_MUST_BE_RECREATED_REASON = 'Host strand must be recreated';
-
-/**
- * Rejection reason a would-be joiner is told for each approval-failure category
- * (see {@link FormationApprovalFailure}). Distinct per category on purpose: mapping any
- * of these onto the generic 'Formation conflict, retry' would tell an operator to retry
- * what retrying can never fix (e.g. a non-enrolled validation key).
- */
-const APPROVAL_REJECTION_REASONS: Record<FormationApprovalFailure, string> = {
-  refused: 'Formation approval refused',
-  unavailable: 'Formation approval unavailable, retry',
-  malformed: 'Formation approval invalid',
-  unenrolled: 'Formation approval key is not enrolled',
-  misconfigured: 'Formation approval misconfigured'
-};
-
-/**
- * Configuration for StrandFormationManager
- */
-export interface StrandFormationManagerConfig {
-  /** Session timeout in milliseconds */
-  sessionTimeoutMs?: number;
-  /** Step timeout in milliseconds */
-  stepTimeoutMs?: number;
-  /**
-   * Provisioning budget in milliseconds for the RESPONDER's `provisionStrand` hook call.
-   * The initiator's `await-response` wait is derived automatically from this value plus
-   * `PROVISION_RESPONSE_TRAVEL_MARGIN_MS` (`strand-formation-protocol.ts`) — never set
-   * directly — so the ordering documented there (approval hook < responder provisioning <
-   * initiator await-response < session) cannot collapse when this is configured.
-   */
-  provisionTimeoutMs?: number;
-  /** Maximum concurrent sessions */
-  maxConcurrentSessions?: number;
-  /** Enable debug logging */
-  enableDebugLogging?: boolean;
-  /** Protocol ID override */
-  protocolId?: string;
-}
-
-/**
- * Options for creating a StrandFormationManager
- */
-export interface StrandFormationManagerOptions {
-  /** Validates disclosures from initiators (responder side) */
-  disclosureValidator?: DisclosureValidator;
-  /** Records and validates token usage (responder side) */
-  formationUsageRecorder?: FormationUsageRecorder;
-  /** Provisions strands after validation (responder side) */
-  strandProvisioner?: StrandProvisioner;
-  /** Validates the responder's result (initiator side); defaults to a structural check */
-  formationResponseValidator?: FormationResponseValidator;
-  /** This party's ID for identification */
-  partyId: string;
-  /** This party's cadre peer addresses */
-  cadrePeerAddrs?: string[];
-  /**
-   * This node's live STRAND-network multiaddrs for a strand it is running (responder
-   * side). Wired by `CadreNode` to its own per-strand address lookup; the manager has no
-   * route to the strand runtime itself.
-   *
-   * A hook, not a `config` knob, so it sits with the other responder-side seams
-   * (`strandProvisioner`, `formationUsageRecorder`) rather than among the timeouts. Left
-   * unwired — every mock/transport test — the responder simply discloses no strand
-   * addresses and cross-party joiners fall back to an empty seed.
-   */
-  resolveStrandAddrs?: (strandId: string) => string[];
-  /**
-   * Issue a single-use `Strand.Invite` against the live host strand a BOUND redemption
-   * resolved to (responder side) — the seam that gets the JOINER its own membership.
-   * Like {@link resolveStrandAddrs}, the formation layer cannot reach the strand
-   * runtime itself, so `CadreNode` wires this to its own running-instance +
-   * `StrandPartyKey` lookup.
-   *
-   * Contract: return the issued invitation for a CLOSED host strand; return `null`
-   * for an open one (no members, nothing to invite into); THROW when a closed strand's
-   * invitation cannot be issued (runtime not live, no party key, strand DB write
-   * rejected) — the manager then rejects the whole redemption with
-   * {@link MEMBERSHIP_INVITE_UNAVAILABLE_REASON} BEFORE recording consent, so the
-   * formation token stays unspent and the joiner can retry. Throw a
-   * `PreSplitStrandIdentityError` for a host strand that can never issue one; that maps
-   * to the non-retryable {@link HOST_STRAND_MUST_BE_RECREATED_REASON}.
-   *
-   * Left unwired — mock/transport tests — the bound path approves with no invitation,
-   * mirroring the unwired {@link resolveStrandAddrs} posture. Production
-   * (`CadreNode.initializeStrandSolicitation`) always wires it.
-   */
-  issueMembershipInvite?: (strandId: string) => Promise<StrandMembershipInvite | null>;
-  /** Configuration options */
-  config?: StrandFormationManagerConfig;
-}
-
-/**
- * StrandFormationManager drives the native cadre-core formation transport
- * (`strand-formation-protocol.ts`) from cadre-core's strand-solicitation interfaces.
- *
- * Responder side: a {@link FormationListener} wires the inbound protocol to
- * {@link FormationUsageRecorder} (token), {@link DisclosureValidator} (identity),
- * and {@link StrandProvisioner} (provisioning), disclosing this party's real
- * identity + cadre only after validation.
- *
- * Initiator side: {@link formStrand} dials the responder carrying the real
- * disclosure/token/cadre, then validates the responder's result via the
- * {@link FormationResponseValidator} (or a built-in structural check).
- */
-export class StrandFormationManager {
-  private readonly disclosureValidator?: DisclosureValidator;
-  private readonly formationUsageRecorder?: FormationUsageRecorder;
-  private readonly strandProvisioner?: StrandProvisioner;
-  private readonly formationResponseValidator?: FormationResponseValidator;
-  private readonly partyId: string;
-  private readonly cadrePeerAddrs: string[];
-  private readonly resolveStrandAddrs?: (strandId: string) => string[];
-  private readonly issueMembershipInvite?: (strandId: string) => Promise<StrandMembershipInvite | null>;
-  private readonly config: StrandFormationManagerConfig;
-  private readonly listener: FormationListener;
-  private readonly registeredNodes = new Set<Libp2p>();
-  private dialerSessions = 0;
-
-  constructor(options: StrandFormationManagerOptions) {
-    this.disclosureValidator = options.disclosureValidator;
-    this.formationUsageRecorder = options.formationUsageRecorder;
-    this.strandProvisioner = options.strandProvisioner;
-    this.formationResponseValidator = options.formationResponseValidator;
-    this.partyId = options.partyId;
-    this.cadrePeerAddrs = options.cadrePeerAddrs ?? [];
-    this.resolveStrandAddrs = options.resolveStrandAddrs;
-    this.issueMembershipInvite = options.issueMembershipInvite;
-    this.config = options.config ?? {};
-
-    this.listener = new FormationListener({
-      validateToken: (token) => this.validateToken(token),
-      validateDisclosure: (token, disclosure) => this.validateDisclosure(token, disclosure),
-      provisionStrand: (contact, signal) =>
-        this.provisionAsResponder(contact, signal),
-      getResponderIdentity: () => ({ partyId: this.partyId, cadrePeerAddrs: this.cadrePeerAddrs }),
-      // Forwarded only when wired, so `FormationListenerOptions.resolveStrandAddrs`
-      // stays genuinely absent (and the listener short-circuits) for an unwired manager.
-      ...(this.resolveStrandAddrs && { resolveStrandAddrs: this.resolveStrandAddrs }),
-      sessionTimeoutMs: this.config.sessionTimeoutMs,
-      stepTimeoutMs: this.config.stepTimeoutMs,
-      provisionTimeoutMs: this.config.provisionTimeoutMs,
-      maxConcurrentSessions: this.config.maxConcurrentSessions
-    });
-
-    log('StrandFormationManager created for party: %s', this.partyId);
-  }
-
-  /**
-   * Register this manager as a protocol handler on a libp2p node.
-   * Call this on the control network node to handle incoming formation requests.
-   */
-  registerResponder(node: Libp2p, protocolId?: string): void {
-    if (this.registeredNodes.has(node)) {
-      log('Node already registered');
-      return;
-    }
-    this.listener.register(node, protocolId ?? this.config.protocolId);
-    this.registeredNodes.add(node);
-    log('Registered as responder on node');
-  }
-
-  /**
-   * Unregister the protocol handler from a libp2p node.
-   */
-  unregisterResponder(node: Libp2p, protocolId?: string): void {
-    if (!this.registeredNodes.has(node)) {
-      return;
-    }
-    this.listener.unregister(node, protocolId ?? this.config.protocolId);
-    this.registeredNodes.delete(node);
-    log('Unregistered from node');
-  }
-
-  /**
-   * Form a strand with a responder via an open invitation (initiator side).
-   *
-   * Builds a contact message carrying the real token + disclosure + this party's
-   * real cadre addresses + the joiner's consent (minted and signed by the
-   * solicitation layer — this manager only places it on the contact), dials the
-   * responder over the native protocol, and validates the responder's result
-   * before returning.
-   */
-  async formStrand(
-    invitation: OpenInvitation,
-    disclosure: StrandFormationDisclosure,
-    consent: { peerKey: string; usageStampId: string; peerSignature: string },
-    node: Libp2p
-  ): Promise<FormStrandResult> {
-    log('Forming strand with invitation token: %s', invitation.token);
-
-    const contact: FormationContactMessage = {
-      token: invitation.token,
-      partyId: disclosure.partyId ?? this.partyId,
-      peerKey: consent.peerKey,
-      usageStampId: consent.usageStampId,
-      peerSignature: consent.peerSignature,
-      disclosure,
-      cadrePeerAddrs: this.cadrePeerAddrs
-    };
-
-    this.dialerSessions++;
-    try {
-      const dialed = await dialFormation(node, {
-        contact,
-        responderAddrs: invitation.bootstrap,
-        validateResponse: (response) => this.validateResponse(invitation, disclosure, response),
-        sessionTimeoutMs: this.config.sessionTimeoutMs,
-        stepTimeoutMs: this.config.stepTimeoutMs,
-        provisionTimeoutMs: this.initiatorProvisionTimeoutMs(),
-        protocolId: this.config.protocolId
-      });
-
-      const provision = dialed.provision;
-      log('Strand formed: %s (%d cross-party strand addr(s))', provision.strand.strandId, dialed.strandAddrs.length);
-
-      return {
-        memberKey: contact.partyId,
-        invitePrivateKey: '',
-        strandId: provision.strand.strandId,
-        // The host strand's membership key, delivered through the protocol (provision-then-record).
-        // Undefined for an open strand. Kept separate from invitePrivateKey (the initiator's
-        // generated signing key), which is set by the StrandSolicitationService layer.
-        memberPrivateKey: provision.memberPrivateKey,
-        // Carried only when well-formed. The DEFAULT response validator already rejects
-        // a malformed one; this re-check keeps a custom validator that skips the shape
-        // check from feeding a hostile responder's object into the joiner's invite cache.
-        membershipInvite: this.membershipInviteFrom(provision),
-        // Possibly empty — the responder may hold no live strand node yet.
-        strandAddrs: dialed.strandAddrs
-      };
-    } finally {
-      this.dialerSessions--;
-    }
-  }
-
-  /**
-   * Get the number of active sessions
-   */
-  getActiveSessionCounts(): { listeners: number; dialers: number } {
-    return { listeners: this.listener.activeCount, dialers: this.dialerSessions };
-  }
-
-  /**
-   * The provision result's membership invitation, iff well-formed — a malformed one
-   * (possible only past a custom {@link FormationResponseValidator} that skipped the
-   * structural check) is dropped with a log rather than cached: it could never redeem
-   * anyway, and carrying an unbounded hostile object outlives the session.
-   */
-  private membershipInviteFrom(provision: FormationProvisionResult): StrandMembershipInvite | undefined {
-    if (provision.membershipInvite === undefined) {
-      return undefined;
-    }
-    if (!isWellFormedMembershipInvite(provision.membershipInvite)) {
-      log('formStrand: dropping malformed membershipInvite from responder for strand %s', provision.strand.strandId);
-      return undefined;
-    }
-    return { inviteKey: provision.membershipInvite.inviteKey, invitePrivateKey: provision.membershipInvite.invitePrivateKey };
-  }
-
-  /**
-   * Derive the initiator's await-response budget from the configured RESPONDER budget —
-   * never the same number (see `StrandFormationManagerConfig.provisionTimeoutMs`). Mirrors
-   * `resolveProvisionTimeoutMs`'s own "`0`/negative means unset" rule so an unset config
-   * still lets both sides fall back to their own independent defaults; must NOT hardcode
-   * `DEFAULT_PROVISION_TIMEOUT_MS` here, or the per-role clamping downstream is defeated.
-   * A value too large for the session is clamped per role, and the responder's ceiling holds
-   * the same margin back, so the ordering survives there too.
-   */
-  private initiatorProvisionTimeoutMs(): number | undefined {
-    const host = this.config.provisionTimeoutMs;
-    return host && host > 0 ? host + PROVISION_RESPONSE_TRAVEL_MARGIN_MS : undefined;
-  }
-
-  // ── Responder-side hooks ─────────────────────────────────────────────────────
-
-  private async validateToken(token: string): Promise<{ valid: boolean }> {
-    if (!this.formationUsageRecorder) {
-      // No recorder configured — accept all tokens.
-      return { valid: true };
-    }
-
-    const tokenCheck = await this.formationUsageRecorder.isTokenValid(token);
-    if (!tokenCheck.valid) {
-      log('Token invalid: %s', token);
-      return { valid: false };
-    }
-
-    if (await this.formationUsageRecorder.isTokenUsed(token)) {
-      log('Token already used: %s', token);
-      return { valid: false };
-    }
-
-    return { valid: true };
-  }
-
-  private async validateDisclosure(token: string, disclosure: StrandFormationDisclosure): Promise<boolean> {
-    if (!this.disclosureValidator) {
-      // No validator configured — accept all disclosures.
-      return true;
-    }
-    return this.disclosureValidator.validateDisclosure(token, disclosure);
-  }
-
-  /**
-   * Responder-side provisioning. Routes on how the invite resolves
-   * ({@link ResolvedHostStrand}), and can REJECT post-validation by returning a
-   * {@link ResponderProvisionOutcome} with `approved: false` — `runSession` turns that
-   * into a clean, non-disclosing reply instead of a dropped result frame.
-   *
-   * - **bound** (host strand present): provision-then-record — first issue the joiner's
-   *   single-use strand membership invitation via the wired `issueMembershipInvite` seam
-   *   ({@link issueBoundMembershipInvite}; a closed strand whose invitation cannot be
-   *   issued rejects retryably HERE, before any consent row spends the token), then write
-   *   the single `FormationUsage` consent row against the pre-existing strand
-   *   (record-only) and return it + its membership key + the invitation (all read-gating
-   *   secrets disclosed only here, behind the token + disclosure validation `runSession`
-   *   already enforced).
-   * - **missing** (invite names a host strand absent on this responder, e.g. unconverged):
-   *   reject cleanly + retryably, writing NO usage row — recording usage here would fail the
-   *   deferred `StrandExists` CHECK at commit and drop the frame.
-   * - **unbound** (no binding): the responder-provisions fallback — see {@link provisionUnbound}.
-   *
-   * Defense-in-depth: known provisioning/redeem failures are caught and mapped to a logged
-   * protocol rejection rather than a thrown insert + a silently-closed stream. The mapping is
-   * per-failure, NOT blanket retry-suggesting: an exhausted invitation
-   * ({@link InvitationExhaustedError}, raised by `ControlDatabase` when the count of recorded
-   * uses has reached the invite's seat budget — which is how the loser of a same-node race
-   * surfaces, the local write queue having serialized the two writes) is reported as
-   * `'Invalid token'`, because retrying it can never succeed. Concurrent redemptions never
-   * contend for a shared row key — each writes under its own `UsageStampId` — so there is no
-   * key collision to surface here at all. The LOG-before-reject keeps this a deliberate
-   * internal-error→protocol-rejection conversion (AGENTS.md: don't eat exceptions silently),
-   * not control-flow-by-exception.
-   */
-  private async provisionAsResponder(
-    contact: FormationContactMessage,
-    signal?: AbortSignal
-  ): Promise<ResponderProvisionOutcome> {
-    const token = contact.token;
-    // CANONICALLY serialized — both sides derive the identical string: this is the exact
-    // text the joiner signed (consent), the approver signs (vouch), and the recorder writes
-    // to `FormationUsage.Disclosure` — a re-serialization anywhere below would break the
-    // signature-over-stored-bytes invariant.
-    const disclosureText = canonicalJson(contact.disclosure);
-    if (uint8ArrayFromString(disclosureText, 'utf8').byteLength > MAX_DISCLOSURE_BYTES) {
-      log('Disclosure over %d bytes; rejecting token %s', MAX_DISCLOSURE_BYTES, token);
-      return { approved: false, reason: 'Disclosure too large' };
-    }
-
-    const recorder = this.formationUsageRecorder;
-    const resolved: ResolvedHostStrand = recorder?.resolveStrand
-      ? await recorder.resolveStrand(token)
-      : { kind: 'unbound' };
-
-    try {
-      switch (resolved.kind) {
-        case 'bound': {
-          // Issued BEFORE the consent row is recorded, so an issue failure rejects with
-          // the formation token still unspent (retryable). The inverse window — invite
-          // issued, then recordUsage fails/aborts — orphans a live `Strand.Invite` no
-          // joiner ever received; bounded deliberately by its expiry
-          // ({@link MEMBERSHIP_INVITE_TTL_MS}) rather than compensated, since nothing
-          // here can atomically un-issue a strand-DB row.
-          const issued = await this.issueBoundMembershipInvite(token, resolved.strandId);
-          if (!issued.ok) {
-            return { approved: false, reason: issued.reason };
-          }
-          // recorder is guaranteed non-null here: only resolveStrand can yield 'bound'.
-          await recorder!.recordUsage({
-            token,
-            peerKey: contact.peerKey,
-            peerSignature: contact.peerSignature,
-            usageStampId: contact.usageStampId,
-            strandId: resolved.strandId,
-            disclosure: disclosureText,
-            signal
-          });
-          return this.approve({
-            strand: { strandId: resolved.strandId, createdBy: 'responder' },
-            memberPrivateKey: resolved.memberPrivateKey ?? undefined,
-            // Omitted (not sent undefined-valued) so rejection-parity and open-strand
-            // assertions stay plain `toBeUndefined()` on the parsed frame.
-            ...(issued.invite ? { membershipInvite: issued.invite } : {}),
-            dbConnectionInfo: { endpoint: 'local', credentialsRef: '' }
-          });
-        }
-        case 'missing': {
-          log('Host strand %s not yet available on this responder; rejecting token %s', resolved.strandId, token);
-          return { approved: false, reason: 'Host strand not yet available on this responder' };
-        }
-        case 'unbound':
-          return await this.provisionUnbound(contact, disclosureText, signal);
-      }
-    } catch (err) {
-      if (err instanceof FormationAbortedError) {
-        // The listener's timeout path owns the reply for an abandoned provisioning; mapping
-        // this onto 'Formation conflict, retry' would misreport it as a conflict.
-        throw err;
-      }
-      if (err instanceof FormationApprovalError) {
-        log('approval failed (%s) for token %s: %o', err.failure, token, err);
-        return { approved: false, reason: APPROVAL_REJECTION_REASONS[err.failure] };
-      }
-      if (err instanceof InvitationExhaustedError) {
-        // Shares `INVALID_TOKEN_REASON` with the up-front `validateToken` rejection so the loser
-        // of the race that exposed the spent invite sees exactly what a non-racing latecomer
-        // sees. No wire-visible distinction between "invalid" and "exhausted" — the
-        // operator signal lives in this log line instead.
-        // NOTE: if a joining client ever has to tell "never valid" from "used up" WITHOUT node
-        // logs, that is a new protocol reason string, not a local change here.
-        log(
-          'invitation exhausted for token %s: %d of %d use(s) already recorded',
-          err.token,
-          err.usesRecorded,
-          err.totalUses
-        );
-        return { approved: false, reason: INVALID_TOKEN_REASON };
-      }
-      // An approval is never discarded to a lost key race: each redemption writes under its
-      // own `UsageStampId`, so no other writer can take its row key. Reaching this catch-all
-      // means the failure was never retryable at the database layer to begin with (or the
-      // transient-cluster retry inside `ControlDatabase.lockedWithRetry` ran out).
-      log('provisionAsResponder failed for token %s: %o', token, err);
-      return { approved: false, reason: 'Formation conflict, retry' };
-    }
-  }
-
-  /**
-   * Issue the joiner's membership invitation for a BOUND redemption via the wired
-   * {@link StrandFormationManagerOptions.issueMembershipInvite} seam.
-   *
-   * - Hook unwired (mock/transport tests): approve with no invitation, the same posture
-   *   as an unwired `resolveStrandAddrs`.
-   * - Hook returns an invitation (closed host strand): carry it on the approval.
-   * - Hook returns `null` (open host strand): approve with no invitation.
-   * - Hook throws (runtime not live, no party key, strand-DB write rejected): report
-   *   `ok: false` with {@link MEMBERSHIP_INVITE_UNAVAILABLE_REASON} — the caller rejects
-   *   BEFORE any consent row is written, so the formation token stays unspent.
-   * - Hook throws `PreSplitStrandIdentityError` (the host strand was founded before the
-   *   per-party identity split and can never issue one): same, but with the
-   *   non-retryable {@link HOST_STRAND_MUST_BE_RECREATED_REASON}.
-   *
-   * The LOG-before-reject keeps both a deliberate internal-error→protocol-rejection
-   * conversion, same as the catch-all in {@link provisionAsResponder}.
-   */
-  private async issueBoundMembershipInvite(
-    token: string,
-    strandId: string
-  ): Promise<{ ok: true; invite?: StrandMembershipInvite } | { ok: false; reason: string }> {
-    if (!this.issueMembershipInvite) {
-      return { ok: true };
-    }
-    try {
-      const invite = await this.issueMembershipInvite(strandId);
-      return { ok: true, invite: invite ?? undefined };
-    } catch (err) {
-      if (err instanceof PreSplitStrandIdentityError) {
-        log('host strand %s is pre-split (token %s); rejecting — it must be recreated: %o', strandId, token, err);
-        return { ok: false, reason: HOST_STRAND_MUST_BE_RECREATED_REASON };
-      }
-      log('membership-invite issue for strand %s failed (token %s); rejecting retryably: %o', strandId, token, err);
-      return { ok: false, reason: MEMBERSHIP_INVITE_UNAVAILABLE_REASON };
-    }
-  }
-
-  /**
-   * Responder-provisions fallback (invite binds no host strand). Precedence:
-   *
-   * 1. `recorder.provisionAndRecord` present (a real DB recorder) → atomic create-strand +
-   *    record-consent, so the unbound redemption is single-use just like the bound path.
-   *    Returns the new strand (+ key, null for an open responder-provisioned strand).
-   * 2. else `strandProvisioner` present → the mock/transport-test contract: provision a bare
-   *    strand, NO inline usage write (those callers record usage explicitly via
-   *    `recordFormationComplete`, or assert transport invariants only). Threads the invite's
-   *    REAL `sAppId`.
-   * 3. else → a structural placeholder (no recorder + no provisioner ⇒ no single-use semantics
-   *    exist to enforce).
-   *
-   * NOTE: accepted tradeoff — the plan chose (a) "record usage on the fallback" over (b)
-   * "remove the fallback", so arm 2 (`strandProvisioner`, no recorder) is kept. (a) closes the
-   * single-use hole with a targeted atomic create+record and leaves the `StrandProvisioner`
-   * mock-transport tests untouched; (b) would delete the provisioner surface and churn ~6 unit
-   * + ~6 integration sites for ZERO production benefit (production — `cadre-web.ts` /
-   * `cadre-phone.ts` — always publishes strand-BOUND invites and treats the
-   * responder-provisions placeholder as failure). Revisit if production starts publishing
-   * unbound invites, or the mock-transport tests go away.
-   */
-  private async provisionUnbound(
-    contact: FormationContactMessage,
-    disclosureText: string,
-    signal?: AbortSignal
-  ): Promise<ResponderProvisionOutcome> {
-    const token = contact.token;
-    const recorder = this.formationUsageRecorder;
-    if (recorder?.provisionAndRecord) {
-      const sAppId = await this.resolveInviteSAppId(token);
-      const provisioned = await recorder.provisionAndRecord({
-        token,
-        peerKey: contact.peerKey,
-        peerSignature: contact.peerSignature,
-        usageStampId: contact.usageStampId,
-        sAppId,
-        disclosure: disclosureText,
-        signal
-      });
-      return this.approve({
-        strand: { strandId: provisioned.strandId, createdBy: 'responder' },
-        memberPrivateKey: provisioned.memberPrivateKey ?? undefined,
-        dbConnectionInfo: { endpoint: 'local', credentialsRef: '' }
-      });
-    }
-
-    if (this.strandProvisioner) {
-      const sAppId = await this.resolveInviteSAppId(token);
-      const result = await this.strandProvisioner.provisionStrand(sAppId, contact.partyId, this.partyId);
-      return this.approve({
-        strand: { strandId: result.strandId, createdBy: 'responder' },
-        dbConnectionInfo: { endpoint: 'local', credentialsRef: '' }
-      });
-    }
-
-    // No recorder + no provisioner — a structural placeholder the initiator can still validate.
-    const strandId = mintPlaceholderStrandId();
-    return this.approve({
-      strand: { strandId, createdBy: 'responder' },
-      dbConnectionInfo: { endpoint: 'local', credentialsRef: '' }
-    });
-  }
-
-  /** Wrap a provision result as an approving {@link ResponderProvisionOutcome}. */
-  private approve(result: FormationProvisionResult): ResponderProvisionOutcome {
-    return { approved: true, result };
-  }
-
-  /**
-   * The invite's authoritative `sAppId` for the responder-provisions fallback, read back
-   * from the recorder's `isTokenValid` invitation (the real `FormationInvite.sAppId`).
-   * Empty string when no recorder is wired or the invitation omits it.
-   */
-  private async resolveInviteSAppId(token: string): Promise<string> {
-    if (!this.formationUsageRecorder) return '';
-    const check = await this.formationUsageRecorder.isTokenValid(token);
-    return check.invitation?.sAppId ?? '';
-  }
-
-  // ── Initiator-side result validation ─────────────────────────────────────────
-
-  private async validateResponse(
-    invitation: OpenInvitation,
-    disclosure: StrandFormationDisclosure,
-    response: FormationResultMessage
-  ): Promise<boolean> {
-    if (this.formationResponseValidator) {
-      return this.formationResponseValidator.validateResponse({ invitation, disclosure, response });
-    }
-    return isValidResponderCreatesResult(response);
-  }
-}
-
-/**
- * Create a StrandFormationManager with the given options
- */
-export function createStrandFormationManager(
-  options: StrandFormationManagerOptions
-): StrandFormationManager {
-  return new StrandFormationManager(options);
-}
+import debug from 'debug';
+import { fromString as uint8ArrayFromString } from 'uint8arrays';
+import type { Libp2p } from '@libp2p/interface';
+import type {
+  OpenInvitation,
+  FormStrandResult,
+  StrandFormationDisclosure,
+  StrandMembershipInvite
+} from './types.js';
+import {
+  FormationApprovalError,
+  type FormationApprovalFailure
+} from './formation-approval.js';
+// control-database does not import this manager, so this import introduces no cycle.
+import { FormationAbortedError, InvitationExhaustedError } from './control-database.js';
+import { PreSplitStrandIdentityError } from './strand-membership-writer.js';
+import { mintPlaceholderStrandId } from './strand-id.js';
+import { canonicalJson } from './canonical-json.js';
+import type {
+  AuthorizedFormationUsage,
+  DisclosureValidator,
+  FormationUsageParams,
+  FormationUsageRecorder,
+  ResolvedHostStrand,
+  StrandProvisioner,
+  FormationResponseValidator
+} from './strand-solicitation.js';
+import {
+  FormationListener,
+  INVALID_TOKEN_REASON,
+  dialFormation,
+  isValidResponderCreatesResult,
+  isWellFormedMembershipInvite,
+  type FormationContactMessage,
+  type FormationProvisionResult,
+  type FormationResultMessage,
+  type ResponderProvisionOutcome
+} from './strand-formation-protocol.js';
+import { formationDeadlines } from './strand-formation-deadlines.js';
+
+const log = debug('sereus:cadre:formation-manager');
+
+/**
+ * Largest serialized disclosure a responder will accept (8 KiB). The disclosure is
+ * attacker-influenced text destined for a replicated table (`FormationUsage.Disclosure`)
+ * and for the approval hook's signed digest — the cap bounds both, and is enforced BEFORE
+ * any database read or hook contact so an oversized blob costs nothing downstream.
+ */
+const MAX_DISCLOSURE_BYTES = 8 * 1024;
+
+/**
+ * How long a formation-issued strand membership invitation stays redeemable (7 days).
+ * The responder's {@link StrandFormationManagerOptions.issueMembershipInvite} hook stamps
+ * `now + this` as the `Strand.Invite.Expiration`. Long enough for a slow joiner to bring
+ * its strand node up and redeem; short enough that a lost formation result does not leave
+ * a live bearer credential in the strand forever. An expired invitation rolls the
+ * redemption back cleanly (the schema's `NotExpired` gate) — the joiner's recovery is a
+ * fresh formation, which issues a fresh invitation.
+ */
+export const MEMBERSHIP_INVITE_TTL_MS = 7 * 24 * 3600_000;
+
+/**
+ * Rejection reason for a bound CLOSED-strand redemption whose responder could not issue
+ * the joiner's membership invitation — the host strand runtime not live on this
+ * responder (never launched, mid-start, or a hibernating one that did not wake within the
+ * provisioning budget; a hibernating runtime is woken, not refused), no party identity key
+ * yet, or the strand DB refusing the `Strand.Invite` write. Retryable on purpose, and
+ * rejected BEFORE the consent row is recorded, so the formation token stays unspent:
+ * approving without an invitation would admit a joiner that looks joined but can never
+ * become a member, and a responder not running the strand cannot serve the joiner's sync
+ * anyway. The one permanent failure, a pre-split host strand, gets
+ * {@link HOST_STRAND_MUST_BE_RECREATED_REASON} instead.
+ */
+export const MEMBERSHIP_INVITE_UNAVAILABLE_REASON = 'Strand membership invitation unavailable, retry';
+
+/**
+ * Rejection reason for a bound CLOSED-strand redemption whose host strand was founded
+ * before the per-party identity split: the responder's founder launch refused it
+ * (`PreSplitStrandIdentityError`), so no invitation can ever be issued into it. Not
+ * retryable — the host must recreate the strand and issue a fresh invitation. Like
+ * {@link MEMBERSHIP_INVITE_UNAVAILABLE_REASON}, rejected before consent is recorded, so
+ * the formation token stays unspent.
+ */
+export const HOST_STRAND_MUST_BE_RECREATED_REASON = 'Host strand must be recreated';
+
+/**
+ * Rejection reason a would-be joiner is told for each approval-failure category
+ * (see {@link FormationApprovalFailure}). Distinct per category on purpose: mapping any
+ * of these onto the generic 'Formation conflict, retry' would tell an operator to retry
+ * what retrying can never fix (e.g. a non-enrolled validation key).
+ */
+const APPROVAL_REJECTION_REASONS: Record<FormationApprovalFailure, string> = {
+  refused: 'Formation approval refused',
+  unavailable: 'Formation approval unavailable, retry',
+  malformed: 'Formation approval invalid',
+  unenrolled: 'Formation approval key is not enrolled',
+  misconfigured: 'Formation approval misconfigured'
+};
+
+/**
+ * Responder-side seam that issues a bound joiner's membership invitation — see
+ * {@link StrandFormationManagerOptions.issueMembershipInvite} for the contract. `signal`
+ * is the responder's provisioning budget: the issuer stops waiting (and throws) once it
+ * aborts.
+ */
+export type MembershipInviteIssuer = (strandId: string, signal?: AbortSignal) => Promise<StrandMembershipInvite | null>;
+
+/**
+ * Configuration for StrandFormationManager
+ */
+export interface StrandFormationManagerConfig {
+  /**
+   * This machine's declared link round trip (`NetworkConfig.linkRoundTripMs`), from which
+   * every formation deadline is derived (`formationDeadlines` in
+   * `strand-formation-deadlines.ts`). `CadreNode` fills it from its network config; the
+   * fields below override single rungs of that ladder.
+   */
+  linkRoundTripMs?: number;
+  /** Whole-session budget, both roles, in milliseconds. */
+  sessionTimeoutMs?: number;
+  /** The responder's contact-frame read, in milliseconds. */
+  stepTimeoutMs?: number;
+  /** The initiator's dial-connect (open the connection, negotiate the protocol), in milliseconds. */
+  dialTimeoutMs?: number;
+  /**
+   * Provisioning budget in milliseconds for the RESPONDER's `provisionStrand` hook call.
+   * The initiator's `await-response` wait is derived automatically from this value plus the
+   * travel margin of the derived ladder (`responseTravelMarginMs`) — never set directly — so
+   * the ordering documented there (approval hook < responder provisioning < initiator
+   * await-response < session) cannot collapse when this is configured.
+   */
+  provisionTimeoutMs?: number;
+  /** Maximum concurrent sessions */
+  maxConcurrentSessions?: number;
+  /** Enable debug logging */
+  enableDebugLogging?: boolean;
+  /** Protocol ID override */
+  protocolId?: string;
+}
+
+/**
+ * Options for creating a StrandFormationManager
+ */
+export interface StrandFormationManagerOptions {
+  /** Validates disclosures from initiators (responder side) */
+  disclosureValidator?: DisclosureValidator;
+  /** Records and validates token usage (responder side) */
+  formationUsageRecorder?: FormationUsageRecorder;
+  /** Provisions strands after validation (responder side) */
+  strandProvisioner?: StrandProvisioner;
+  /** Validates the responder's result (initiator side); defaults to a structural check */
+  formationResponseValidator?: FormationResponseValidator;
+  /** This party's ID for identification */
+  partyId: string;
+  /** This party's cadre peer addresses */
+  cadrePeerAddrs?: string[];
+  /**
+   * This node's live STRAND-network multiaddrs for a strand it is running (responder
+   * side). Wired by `CadreNode` to its own per-strand address lookup; the manager has no
+   * route to the strand runtime itself.
+   *
+   * A hook, not a `config` knob, so it sits with the other responder-side seams
+   * (`strandProvisioner`, `formationUsageRecorder`) rather than among the timeouts. Left
+   * unwired — every mock/transport test — the responder simply discloses no strand
+   * addresses and cross-party joiners fall back to an empty seed.
+   */
+  resolveStrandAddrs?: (strandId: string) => string[];
+  /**
+   * Issue a single-use `Strand.Invite` against the live host strand a BOUND redemption
+   * resolved to (responder side) — the seam that gets the JOINER its own membership.
+   * Like {@link resolveStrandAddrs}, the formation layer cannot reach the strand
+   * runtime itself, so `CadreNode` wires this to its own running-instance +
+   * `StrandPartyKey` lookup.
+   *
+   * Contract: return the issued invitation for a CLOSED host strand; return `null`
+   * for an open one (no members, nothing to invite into); THROW when a closed strand's
+   * invitation cannot be issued (runtime not live, no party key, strand DB write
+   * rejected) — the manager then rejects the whole redemption with
+   * {@link MEMBERSHIP_INVITE_UNAVAILABLE_REASON} BEFORE recording consent, so the
+   * formation token stays unspent and the joiner can retry. Throw a
+   * `PreSplitStrandIdentityError` for a host strand that can never issue one; that maps
+   * to the non-retryable {@link HOST_STRAND_MUST_BE_RECREATED_REASON}.
+   *
+   * A hibernating host runtime is not a reason to throw: the issuer wakes it first,
+   * bounded by `signal` (the responder's provisioning budget), and throws only when the
+   * wake does not finish in time or fails.
+   *
+   * Left unwired — mock/transport tests — the bound path approves with no invitation,
+   * mirroring the unwired {@link resolveStrandAddrs} posture. Production
+   * (`CadreNode.initializeStrandSolicitation`) always wires it.
+   */
+  issueMembershipInvite?: MembershipInviteIssuer;
+  /** Configuration options */
+  config?: StrandFormationManagerConfig;
+}
+
+/**
+ * StrandFormationManager drives the native cadre-core formation transport
+ * (`strand-formation-protocol.ts`) from cadre-core's strand-solicitation interfaces.
+ *
+ * Responder side: a {@link FormationListener} wires the inbound protocol to
+ * {@link FormationUsageRecorder} (token), {@link DisclosureValidator} (identity),
+ * and {@link StrandProvisioner} (provisioning), disclosing this party's real
+ * identity + cadre only after validation.
+ *
+ * Initiator side: {@link formStrand} dials the responder carrying the real
+ * disclosure/token/cadre, then validates the responder's result via the
+ * {@link FormationResponseValidator} (or a built-in structural check).
+ */
+export class StrandFormationManager {
+  private readonly disclosureValidator?: DisclosureValidator;
+  private readonly formationUsageRecorder?: FormationUsageRecorder;
+  private readonly strandProvisioner?: StrandProvisioner;
+  private readonly formationResponseValidator?: FormationResponseValidator;
+  private readonly partyId: string;
+  private readonly cadrePeerAddrs: string[];
+  private readonly resolveStrandAddrs?: (strandId: string) => string[];
+  private readonly issueMembershipInvite?: MembershipInviteIssuer;
+  private readonly config: StrandFormationManagerConfig;
+  private readonly listener: FormationListener;
+  private readonly registeredNodes = new Set<Libp2p>();
+  private dialerSessions = 0;
+
+  constructor(options: StrandFormationManagerOptions) {
+    this.disclosureValidator = options.disclosureValidator;
+    this.formationUsageRecorder = options.formationUsageRecorder;
+    this.strandProvisioner = options.strandProvisioner;
+    this.formationResponseValidator = options.formationResponseValidator;
+    this.partyId = options.partyId;
+    this.cadrePeerAddrs = options.cadrePeerAddrs ?? [];
+    this.resolveStrandAddrs = options.resolveStrandAddrs;
+    this.issueMembershipInvite = options.issueMembershipInvite;
+    this.config = options.config ?? {};
+
+    this.listener = new FormationListener({
+      validateToken: (token) => this.validateToken(token),
+      validateDisclosure: (token, disclosure) => this.validateDisclosure(token, disclosure),
+      provisionStrand: (contact, signal) =>
+        this.provisionAsResponder(contact, signal),
+      getResponderIdentity: () => ({ partyId: this.partyId, cadrePeerAddrs: this.cadrePeerAddrs }),
+      // Forwarded only when wired, so `FormationListenerOptions.resolveStrandAddrs`
+      // stays genuinely absent (and the listener short-circuits) for an unwired manager.
+      ...(this.resolveStrandAddrs && { resolveStrandAddrs: this.resolveStrandAddrs }),
+      linkRoundTripMs: this.config.linkRoundTripMs,
+      sessionTimeoutMs: this.config.sessionTimeoutMs,
+      stepTimeoutMs: this.config.stepTimeoutMs,
+      provisionTimeoutMs: this.config.provisionTimeoutMs,
+      maxConcurrentSessions: this.config.maxConcurrentSessions
+    });
+
+    log('StrandFormationManager created for party: %s', this.partyId);
+  }
+
+  /**
+   * Register this manager as a protocol handler on a libp2p node.
+   * Call this on the control network node to handle incoming formation requests.
+   */
+  async registerResponder(node: Libp2p, protocolId?: string): Promise<void> {
+    if (this.registeredNodes.has(node)) {
+      log('Node already registered');
+      return;
+    }
+    await this.listener.register(node, protocolId ?? this.config.protocolId);
+    this.registeredNodes.add(node);
+    log('Registered as responder on node');
+  }
+
+  /**
+   * Unregister the protocol handler from a libp2p node.
+   */
+  async unregisterResponder(node: Libp2p, protocolId?: string): Promise<void> {
+    if (!this.registeredNodes.has(node)) {
+      return;
+    }
+    await this.listener.unregister(node, protocolId ?? this.config.protocolId);
+    this.registeredNodes.delete(node);
+    log('Unregistered from node');
+  }
+
+  /**
+   * Form a strand with a responder via an open invitation (initiator side).
+   *
+   * Builds a contact message carrying the real token + disclosure + this party's
+   * real cadre addresses + the joiner's consent (minted and signed by the
+   * solicitation layer — this manager only places it on the contact), dials the
+   * responder over the native protocol, and validates the responder's result
+   * before returning.
+   */
+  async formStrand(
+    invitation: OpenInvitation,
+    disclosure: StrandFormationDisclosure,
+    consent: { peerKey: string; usageStampId: string; peerSignature: string },
+    node: Libp2p
+  ): Promise<FormStrandResult> {
+    log('Forming strand with invitation token: %s', invitation.token);
+
+    const contact: FormationContactMessage = {
+      token: invitation.token,
+      partyId: disclosure.partyId ?? this.partyId,
+      peerKey: consent.peerKey,
+      usageStampId: consent.usageStampId,
+      peerSignature: consent.peerSignature,
+      disclosure,
+      cadrePeerAddrs: this.cadrePeerAddrs
+    };
+
+    this.dialerSessions++;
+    try {
+      const dialed = await dialFormation(node, {
+        contact,
+        responderAddrs: invitation.bootstrap,
+        validateResponse: (response) => this.validateResponse(invitation, disclosure, response),
+        linkRoundTripMs: this.config.linkRoundTripMs,
+        sessionTimeoutMs: this.config.sessionTimeoutMs,
+        dialTimeoutMs: this.config.dialTimeoutMs,
+        provisionTimeoutMs: this.initiatorProvisionTimeoutMs(),
+        protocolId: this.config.protocolId
+      });
+
+      const provision = dialed.provision;
+      log('Strand formed: %s (%d cross-party strand addr(s))', provision.strand.strandId, dialed.strandAddrs.length);
+
+      return {
+        memberKey: contact.partyId,
+        invitePrivateKey: '',
+        strandId: provision.strand.strandId,
+        // The host strand's membership key, delivered through the protocol (provision-then-record).
+        // Undefined for an open strand. Kept separate from invitePrivateKey (the initiator's
+        // generated signing key), which is set by the StrandSolicitationService layer.
+        memberPrivateKey: provision.memberPrivateKey,
+        // Carried only when well-formed. The DEFAULT response validator already rejects
+        // a malformed one; this re-check keeps a custom validator that skips the shape
+        // check from feeding a hostile responder's object into the joiner's invite cache.
+        membershipInvite: this.membershipInviteFrom(provision),
+        // Possibly empty — the responder may hold no live strand node yet.
+        strandAddrs: dialed.strandAddrs
+      };
+    } finally {
+      this.dialerSessions--;
+    }
+  }
+
+  /**
+   * Get the number of active sessions
+   */
+  getActiveSessionCounts(): { listeners: number; dialers: number } {
+    return { listeners: this.listener.activeCount, dialers: this.dialerSessions };
+  }
+
+  /**
+   * The provision result's membership invitation, iff well-formed — a malformed one
+   * (possible only past a custom {@link FormationResponseValidator} that skipped the
+   * structural check) is dropped with a log rather than cached: it could never redeem
+   * anyway, and carrying an unbounded hostile object outlives the session.
+   */
+  private membershipInviteFrom(provision: FormationProvisionResult): StrandMembershipInvite | undefined {
+    if (provision.membershipInvite === undefined) {
+      return undefined;
+    }
+    if (!isWellFormedMembershipInvite(provision.membershipInvite)) {
+      log('formStrand: dropping malformed membershipInvite from responder for strand %s', provision.strand.strandId);
+      return undefined;
+    }
+    return { inviteKey: provision.membershipInvite.inviteKey, invitePrivateKey: provision.membershipInvite.invitePrivateKey };
+  }
+
+  /**
+   * Derive the initiator's await-response budget from the configured RESPONDER budget —
+   * never the same number (see `StrandFormationManagerConfig.provisionTimeoutMs`): the
+   * configured value plus the travel margin the ladder derives at this machine's link.
+   * Mirrors `resolveProvisionTimeoutMs`'s own "`0`/negative means unset" rule so an unset
+   * config still lets both sides fall back to their own derived defaults; must NOT
+   * reproduce the derived default here, or the per-role clamping downstream is defeated.
+   * A value too large for the session is clamped per role, and the responder's ceiling holds
+   * the margin back, so the ordering survives there too.
+   */
+  private initiatorProvisionTimeoutMs(): number | undefined {
+    const host = this.config.provisionTimeoutMs;
+    return host && host > 0
+      ? host + formationDeadlines(this.config.linkRoundTripMs).responseTravelMarginMs
+      : undefined;
+  }
+
+  // ── Responder-side hooks ─────────────────────────────────────────────────────
+
+  private async validateToken(token: string): Promise<{ valid: boolean }> {
+    if (!this.formationUsageRecorder) {
+      // No recorder configured — accept all tokens.
+      return { valid: true };
+    }
+
+    const tokenCheck = await this.formationUsageRecorder.isTokenValid(token);
+    if (!tokenCheck.valid) {
+      log('Token invalid: %s', token);
+      return { valid: false };
+    }
+
+    if (await this.formationUsageRecorder.isTokenUsed(token)) {
+      log('Token already used: %s', token);
+      return { valid: false };
+    }
+
+    return { valid: true };
+  }
+
+  private async validateDisclosure(token: string, disclosure: StrandFormationDisclosure): Promise<boolean> {
+    if (!this.disclosureValidator) {
+      // No validator configured — accept all disclosures.
+      return true;
+    }
+    return this.disclosureValidator.validateDisclosure(token, disclosure);
+  }
+
+  /**
+   * Responder-side provisioning. Routes on how the invite resolves
+   * ({@link ResolvedHostStrand}), and can REJECT post-validation by returning a
+   * {@link ResponderProvisionOutcome} with `approved: false` — `runSession` turns that
+   * into a clean, non-disclosing reply instead of a dropped result frame.
+   *
+   * - **bound** (host strand present): provision-then-record, in three steps —
+   *   (1) authorize ({@link authorizeBoundUsage}: the outside approval when the invite
+   *   demands one, and a seat pre-check), so a refused join writes nothing into the host
+   *   strand; (2) issue the joiner's single-use strand membership invitation via the wired
+   *   `issueMembershipInvite` seam ({@link issueBoundMembershipInvite}; a closed strand whose
+   *   invitation cannot be issued rejects retryably HERE, before any consent row spends the
+   *   token); (3) write the single `FormationUsage` consent row against the pre-existing
+   *   strand (record-only) and return it + its membership key + the invitation (all
+   *   read-gating secrets disclosed only here, behind the token + disclosure validation
+   *   `runSession` already enforced).
+   * - **missing** (invite names a host strand absent on this responder, e.g. unconverged):
+   *   reject cleanly + retryably, writing NO usage row — recording usage here would fail the
+   *   deferred `StrandExists` CHECK at commit and drop the frame.
+   * - **unbound** (no binding): the responder-provisions fallback — see {@link provisionUnbound}.
+   *
+   * Defense-in-depth: known provisioning/redeem failures are caught and mapped to a logged
+   * protocol rejection rather than a thrown insert + a silently-closed stream. The mapping is
+   * per-failure, NOT blanket retry-suggesting: an exhausted invitation
+   * ({@link InvitationExhaustedError}, raised by `ControlDatabase` when the count of recorded
+   * uses has reached the invite's seat budget — which is how the loser of a same-node race
+   * surfaces, the local write queue having serialized the two writes) is reported as
+   * `'Invalid token'`, because retrying it can never succeed. Concurrent redemptions never
+   * contend for a shared row key — each writes under its own `UsageStampId` — so there is no
+   * key collision to surface here at all. The LOG-before-reject keeps this a deliberate
+   * internal-error→protocol-rejection conversion (AGENTS.md: don't eat exceptions silently),
+   * not control-flow-by-exception.
+   */
+  private async provisionAsResponder(
+    contact: FormationContactMessage,
+    signal?: AbortSignal
+  ): Promise<ResponderProvisionOutcome> {
+    const token = contact.token;
+    // CANONICALLY serialized — both sides derive the identical string: this is the exact
+    // text the joiner signed (consent), the approver signs (vouch), and the recorder writes
+    // to `FormationUsage.Disclosure` — a re-serialization anywhere below would break the
+    // signature-over-stored-bytes invariant.
+    const disclosureText = canonicalJson(contact.disclosure);
+    if (uint8ArrayFromString(disclosureText, 'utf8').byteLength > MAX_DISCLOSURE_BYTES) {
+      log('Disclosure over %d bytes; rejecting token %s', MAX_DISCLOSURE_BYTES, token);
+      return { approved: false, reason: 'Disclosure too large' };
+    }
+
+    const recorder = this.formationUsageRecorder;
+    const resolved: ResolvedHostStrand = recorder?.resolveStrand
+      ? await recorder.resolveStrand(token)
+      : { kind: 'unbound' };
+
+    try {
+      switch (resolved.kind) {
+        case 'bound': {
+          // recorder is guaranteed non-null here: only resolveStrand can yield 'bound'.
+          const authorized = await this.authorizeBoundUsage(recorder!, {
+            token,
+            peerKey: contact.peerKey,
+            peerSignature: contact.peerSignature,
+            usageStampId: contact.usageStampId,
+            strandId: resolved.strandId,
+            disclosure: disclosureText,
+            signal
+          });
+          // Issued only once authorized (a refused join writes nothing into the strand) and
+          // BEFORE consent is recorded (an issue failure leaves the token unspent, retryable).
+          // The remaining window — invite issued, then record() fails or aborts (a write that
+          // exhausted its retries, an abort, or the same-node seat race noted at
+          // `ControlFormationUsageRecorder.assertSeatFree`) — orphans a
+          // live `Strand.Invite` no joiner ever received; bounded deliberately by its expiry
+          // ({@link MEMBERSHIP_INVITE_TTL_MS}) rather than compensated, since nothing
+          // here can atomically un-issue a strand-DB row.
+          const issued = await this.issueBoundMembershipInvite(token, resolved.strandId, signal);
+          if (!issued.ok) {
+            return { approved: false, reason: issued.reason };
+          }
+          await authorized.record();
+          return this.approve({
+            strand: { strandId: resolved.strandId, createdBy: 'responder' },
+            memberPrivateKey: resolved.memberPrivateKey ?? undefined,
+            // Omitted (not sent undefined-valued) so rejection-parity and open-strand
+            // assertions stay plain `toBeUndefined()` on the parsed frame.
+            ...(issued.invite ? { membershipInvite: issued.invite } : {}),
+            dbConnectionInfo: { endpoint: 'local', credentialsRef: '' }
+          });
+        }
+        case 'missing': {
+          log('Host strand %s not yet available on this responder; rejecting token %s', resolved.strandId, token);
+          return { approved: false, reason: 'Host strand not yet available on this responder' };
+        }
+        case 'unbound':
+          return await this.provisionUnbound(contact, disclosureText, signal);
+      }
+    } catch (err) {
+      if (err instanceof FormationAbortedError) {
+        // The listener's timeout path owns the reply for an abandoned provisioning; mapping
+        // this onto 'Formation conflict, retry' would misreport it as a conflict.
+        throw err;
+      }
+      if (err instanceof FormationApprovalError) {
+        log('approval failed (%s) for token %s: %o', err.failure, token, err);
+        return { approved: false, reason: APPROVAL_REJECTION_REASONS[err.failure] };
+      }
+      if (err instanceof InvitationExhaustedError) {
+        // Shares `INVALID_TOKEN_REASON` with the up-front `validateToken` rejection so the loser
+        // of the race that exposed the spent invite sees exactly what a non-racing latecomer
+        // sees. No wire-visible distinction between "invalid" and "exhausted" — the
+        // operator signal lives in this log line instead.
+        // NOTE: if a joining client ever has to tell "never valid" from "used up" WITHOUT node
+        // logs, that is a new protocol reason string, not a local change here.
+        log(
+          'invitation exhausted for token %s: %d of %d use(s) already recorded',
+          err.token,
+          err.usesRecorded,
+          err.totalUses
+        );
+        return { approved: false, reason: INVALID_TOKEN_REASON };
+      }
+      // An approval is never discarded to a lost key race: each redemption writes under its
+      // own `UsageStampId`, so no other writer can take its row key. Reaching this catch-all
+      // means the failure was never retryable at the database layer to begin with (or the
+      // transient-cluster retry inside `ControlDatabase.lockedWithRetry` ran out).
+      log('provisionAsResponder failed for token %s: %o', token, err);
+      return { approved: false, reason: 'Formation conflict, retry' };
+    }
+  }
+
+  /**
+   * Authorize a BOUND redemption without writing it, through the recorder's optional
+   * {@link FormationUsageRecorder.authorizeUsage}. A recorder without it has nothing to ask up
+   * front, so its handle defers everything to `recordUsage`.
+   */
+  private async authorizeBoundUsage(
+    recorder: FormationUsageRecorder,
+    params: FormationUsageParams
+  ): Promise<AuthorizedFormationUsage> {
+    if (recorder.authorizeUsage) {
+      return await recorder.authorizeUsage(params);
+    }
+    return { record: () => recorder.recordUsage(params) };
+  }
+
+  /**
+   * Issue the joiner's membership invitation for a BOUND redemption via the wired
+   * {@link StrandFormationManagerOptions.issueMembershipInvite} seam. Runs after the
+   * redemption is authorized ({@link authorizeBoundUsage}) and before consent is recorded.
+   *
+   * - Hook unwired (mock/transport tests): approve with no invitation, the same posture
+   *   as an unwired `resolveStrandAddrs`.
+   * - Hook returns an invitation (closed host strand): carry it on the approval.
+   * - Hook returns `null` (open host strand): approve with no invitation.
+   * - Hook throws (runtime not live — including a hibernating one whose wake outran
+   *   `signal` — no party key, strand-DB write rejected): report
+   *   `ok: false` with {@link MEMBERSHIP_INVITE_UNAVAILABLE_REASON} — the caller rejects
+   *   BEFORE any consent row is written, so the formation token stays unspent.
+   * - Hook throws `PreSplitStrandIdentityError` (the host strand was founded before the
+   *   per-party identity split and can never issue one): same, but with the
+   *   non-retryable {@link HOST_STRAND_MUST_BE_RECREATED_REASON}.
+   *
+   * The LOG-before-reject keeps both a deliberate internal-error→protocol-rejection
+   * conversion, same as the catch-all in {@link provisionAsResponder}.
+   */
+  private async issueBoundMembershipInvite(
+    token: string,
+    strandId: string,
+    signal?: AbortSignal
+  ): Promise<{ ok: true; invite?: StrandMembershipInvite } | { ok: false; reason: string }> {
+    if (!this.issueMembershipInvite) {
+      return { ok: true };
+    }
+    try {
+      const invite = await this.issueMembershipInvite(strandId, signal);
+      return { ok: true, invite: invite ?? undefined };
+    } catch (err) {
+      if (err instanceof PreSplitStrandIdentityError) {
+        log('host strand %s is pre-split (token %s); rejecting — it must be recreated: %o', strandId, token, err);
+        return { ok: false, reason: HOST_STRAND_MUST_BE_RECREATED_REASON };
+      }
+      log('membership-invite issue for strand %s failed (token %s); rejecting retryably: %o', strandId, token, err);
+      return { ok: false, reason: MEMBERSHIP_INVITE_UNAVAILABLE_REASON };
+    }
+  }
+
+  /**
+   * Responder-provisions fallback (invite binds no host strand). Precedence:
+   *
+   * 1. `recorder.provisionAndRecord` present (a real DB recorder) → atomic create-strand +
+   *    record-consent, so the unbound redemption is single-use just like the bound path.
+   *    Returns the new strand (+ key, null for an open responder-provisioned strand).
+   * 2. else `strandProvisioner` present → the mock/transport-test contract: provision a bare
+   *    strand, NO inline usage write (those callers record usage explicitly via
+   *    `recordFormationComplete`, or assert transport invariants only). Threads the invite's
+   *    REAL `sAppId`.
+   * 3. else → a structural placeholder (no recorder + no provisioner ⇒ no single-use semantics
+   *    exist to enforce).
+   *
+   * NOTE: accepted tradeoff — the plan chose (a) "record usage on the fallback" over (b)
+   * "remove the fallback", so arm 2 (`strandProvisioner`, no recorder) is kept. (a) closes the
+   * single-use hole with a targeted atomic create+record and leaves the `StrandProvisioner`
+   * mock-transport tests untouched; (b) would delete the provisioner surface and churn ~6 unit
+   * + ~6 integration sites for ZERO production benefit (production — `cadre-web.ts` /
+   * `cadre-phone.ts` — always publishes strand-BOUND invites and treats the
+   * responder-provisions placeholder as failure). Revisit if production starts publishing
+   * unbound invites, or the mock-transport tests go away.
+   */
+  private async provisionUnbound(
+    contact: FormationContactMessage,
+    disclosureText: string,
+    signal?: AbortSignal
+  ): Promise<ResponderProvisionOutcome> {
+    const token = contact.token;
+    const recorder = this.formationUsageRecorder;
+    if (recorder?.provisionAndRecord) {
+      const sAppId = await this.resolveInviteSAppId(token);
+      const provisioned = await recorder.provisionAndRecord({
+        token,
+        peerKey: contact.peerKey,
+        peerSignature: contact.peerSignature,
+        usageStampId: contact.usageStampId,
+        sAppId,
+        disclosure: disclosureText,
+        signal
+      });
+      return this.approve({
+        strand: { strandId: provisioned.strandId, createdBy: 'responder' },
+        memberPrivateKey: provisioned.memberPrivateKey ?? undefined,
+        dbConnectionInfo: { endpoint: 'local', credentialsRef: '' }
+      });
+    }
+
+    if (this.strandProvisioner) {
+      const sAppId = await this.resolveInviteSAppId(token);
+      const result = await this.strandProvisioner.provisionStrand(sAppId, contact.partyId, this.partyId);
+      return this.approve({
+        strand: { strandId: result.strandId, createdBy: 'responder' },
+        dbConnectionInfo: { endpoint: 'local', credentialsRef: '' }
+      });
+    }
+
+    // No recorder + no provisioner — a structural placeholder the initiator can still validate.
+    const strandId = mintPlaceholderStrandId();
+    return this.approve({
+      strand: { strandId, createdBy: 'responder' },
+      dbConnectionInfo: { endpoint: 'local', credentialsRef: '' }
+    });
+  }
+
+  /** Wrap a provision result as an approving {@link ResponderProvisionOutcome}. */
+  private approve(result: FormationProvisionResult): ResponderProvisionOutcome {
+    return { approved: true, result };
+  }
+
+  /**
+   * The invite's authoritative `sAppId` for the responder-provisions fallback, read back
+   * from the recorder's `isTokenValid` invitation (the real `FormationInvite.sAppId`).
+   * Empty string when no recorder is wired or the invitation omits it.
+   */
+  private async resolveInviteSAppId(token: string): Promise<string> {
+    if (!this.formationUsageRecorder) return '';
+    const check = await this.formationUsageRecorder.isTokenValid(token);
+    return check.invitation?.sAppId ?? '';
+  }
+
+  // ── Initiator-side result validation ─────────────────────────────────────────
+
+  private async validateResponse(
+    invitation: OpenInvitation,
+    disclosure: StrandFormationDisclosure,
+    response: FormationResultMessage
+  ): Promise<boolean> {
+    if (this.formationResponseValidator) {
+      return this.formationResponseValidator.validateResponse({ invitation, disclosure, response });
+    }
+    return isValidResponderCreatesResult(response);
+  }
+}
+
+/**
+ * Create a StrandFormationManager with the given options
+ */
+export function createStrandFormationManager(
+  options: StrandFormationManagerOptions
+): StrandFormationManager {
+  return new StrandFormationManager(options);
+}