@serfab/cadre-core 0.7.1 → 0.9.0

package/src/hibernation-manager.ts

@@ -16,6 +16,17 @@ export interface HibernationCallbacks {
   onIdle: (strandId: string) => Promise<void>;
   onHibernate: (strandId: string) => Promise<void>;
   onWake: (strandId: string) => Promise<void>;
+  /**
+   * Perform a real cohort check-in for a hibernating strand. The implementation
+   * (`CadreNode.handleStrandCheckIn`) resumes the strand, gives it a bounded
+   * window to connect to reachable cohort peers and surface pending activity,
+   * then re-hibernates if still idle. The manager AWAITS this before scheduling
+   * the next (longer-delayed) check-in, so a slow check-in never overlaps the
+   * next tick. After it resolves the manager inspects `instance.status`: a
+   * strand left non-`hibernating` is treated as woken (backoff resets on the
+   * next hibernation); a strand left `hibernating` escalates the backoff.
+   */
+  onCheckIn: (strandId: string) => Promise<void>;
 }
 
 /**
@@ -31,7 +42,20 @@ export class HibernationManager {
   private readonly config: HibernationConfig;
   private readonly callbacks: HibernationCallbacks;
   private readonly timers: Map<string, ReturnType<typeof setTimeout>> = new Map();
-  private readonly checkInTimers: Map<string, ReturnType<typeof setInterval>> = new Map();
+  /**
+   * Pending check-in timers, one per hibernating strand. Unlike the old fixed
+   * `setInterval`, these are single-shot `setTimeout`s rescheduled by
+   * {@link runCheckIn} with an escalating delay — so a long-running `onCheckIn`
+   * can never overlap the next tick, and the period adapts to the backoff.
+   */
+  private readonly checkInTimers: Map<string, ReturnType<typeof setTimeout>> = new Map();
+  /**
+   * In-flight wake promises keyed by strandId. Coalesces overlapping wake
+   * triggers (two near-simultaneous activities, or activity racing a force wake)
+   * so `onWake` — and the libp2p-node rebuild it drives — runs at most once per
+   * concurrent wake.
+   */
+  private readonly wakePromises: Map<string, Promise<void>> = new Map();
   private running = false;
 
   constructor(config: HibernationConfig, callbacks: HibernationCallbacks) {
@@ -48,11 +72,13 @@ export class HibernationManager {
     const custom = this.config.customTimeouts?.[hint];
     
     if (!custom) return defaults;
-    
+
     return {
       idleTimeout: custom.idleTimeout ?? defaults.idleTimeout,
       hibernateTimeout: custom.hibernateTimeout ?? defaults.hibernateTimeout,
-      checkInInterval: custom.checkInInterval ?? defaults.checkInInterval
+      checkInInterval: custom.checkInInterval ?? defaults.checkInInterval,
+      checkInBackoffFactor: custom.checkInBackoffFactor ?? defaults.checkInBackoffFactor,
+      checkInMaxInterval: custom.checkInMaxInterval ?? defaults.checkInMaxInterval
     };
   }
 
@@ -79,13 +105,58 @@ export class HibernationManager {
     this.timers.clear();
     
     for (const timer of this.checkInTimers.values()) {
-      clearInterval(timer);
+      clearTimeout(timer);
     }
     this.checkInTimers.clear();
-    
+
+    // In-flight wakes clean themselves up via their finally; drop the references
+    // so a fresh start coalesces cleanly.
+    this.wakePromises.clear();
+
     log('HibernationManager stopped');
   }
 
+  /**
+   * Whether a strand with this instance's latency hint ever hibernates — `false`
+   * for realtime (Infinity idle timeout, see {@link HIBERNATION_TIMEOUTS}), also
+   * honouring any per-hint `customTimeouts` override. Imperative callers
+   * (`CadreNode.hibernateStrand` / `hibernateAll`) use this as the single source
+   * of truth for "skip realtime", consistent with {@link trackStrand} declining
+   * to track Infinity-timeout strands.
+   */
+  hibernates(instance: StrandInstance): boolean {
+    return this.getTimeouts(instance.latencyHint).idleTimeout !== Infinity;
+  }
+
+  /**
+   * Imperatively hibernate a tracked strand now, bypassing the idle/hibernate
+   * timers — the mobile background-entry path. Cancels the strand's pending
+   * idle/hibernate AND check-in timers so none can later re-fire `onHibernate`
+   * on the already-quiesced strand or resurrect one the caller means to keep
+   * down, then invokes `onHibernate` (quiesce + mark hibernating).
+   *
+   * Unlike the timer path ({@link handleHibernateTimeout}) it deliberately does
+   * NOT re-arm the check-in chain: a force-hibernate keeps the strand down until
+   * the caller drives the next wake on demand (push-delivered on mobile), so a
+   * stray check-in timer must not bring it back up.
+   *
+   * @returns `true` if the strand was hibernated, `false` (no-op) for a realtime
+   *   strand that never hibernates.
+   */
+  async forceHibernate(instance: StrandInstance): Promise<boolean> {
+    if (!this.hibernates(instance)) {
+      log('forceHibernate: strand %s is realtime; no-op', instance.strandId);
+      return false;
+    }
+    // Cancel idle/hibernate + check-in timers BEFORE quiescing so nothing fights
+    // the imperative hibernate (a stale hibernate timer firing on the quiesced
+    // strand, or a check-in resuming a strand the caller wants kept down).
+    this.clearTimers(instance.strandId);
+    await this.callbacks.onHibernate(instance.strandId);
+    log('forceHibernate: strand %s hibernated (timers cancelled, not re-armed)', instance.strandId);
+    return true;
+  }
+
   /**
    * Register a strand for hibernation management
    */
@@ -122,13 +193,33 @@ export class HibernationManager {
     const { strandId, status, latencyHint } = instance;
     instance.lastActivity = new Date();
     
-    // If idle or hibernating, wake up
+    // If idle or hibernating, wake up. Coalesce so two near-simultaneous
+    // activities don't each fire onWake (which would rebuild two libp2p nodes).
     if (status === 'idle' || status === 'hibernating') {
       log('Activity on %s strand %s - waking', status, strandId);
       this.clearTimers(strandId);
-      void this.callbacks.onWake(strandId);
+      // Fire-and-forget; force-wake awaiters see errors, so swallow (and log)
+      // here to avoid an unhandled rejection on this best-effort path.
+      //
+      // Once the wake settles (CadreNode rebuilds the runtime and marks the
+      // strand `active`), re-arm the idle→hibernate→check-in cycle. Without this
+      // a strand that wakes then goes quiet stays `active` forever and never
+      // re-hibernates — so the check-in backoff could never restart at base.
+      // Guarded on `active` so a wake that did not transition (a coalesced
+      // no-op, or a still-mid-flight rebuild) never arms a stray timer.
+      void this.beginWake(strandId).then(() => {
+        if (this.running && instance.status === 'active') {
+          const timeouts = this.getTimeouts(instance.latencyHint);
+          if (timeouts.idleTimeout !== Infinity) {
+            this.scheduleIdleTransition(instance);
+          }
+        }
+      }).catch((err) => {
+        log('Activity-driven wake failed for strand %s: %o', strandId, err);
+      });
+      return;
     }
-    
+
     // Reschedule idle transition if active
     if (status === 'active') {
       const timeouts = this.getTimeouts(latencyHint);
@@ -143,7 +234,30 @@ export class HibernationManager {
    */
   async wakeStrand(strandId: string): Promise<void> {
     this.clearTimers(strandId);
-    await this.callbacks.onWake(strandId);
+    await this.beginWake(strandId);
+  }
+
+  /**
+   * Begin a wake for a strand, or coalesce with one already in flight. Ensures
+   * `onWake` runs at most once per concurrent wake — the returned promise is
+   * shared by all overlapping callers and cleared once it settles. Force-wake
+   * callers await it; activity-driven callers fire-and-forget.
+   */
+  private beginWake(strandId: string): Promise<void> {
+    const existing = this.wakePromises.get(strandId);
+    if (existing) {
+      return existing;
+    }
+
+    const wake = (async () => {
+      try {
+        await this.callbacks.onWake(strandId);
+      } finally {
+        this.wakePromises.delete(strandId);
+      }
+    })();
+    this.wakePromises.set(strandId, wake);
+    return wake;
   }
 
   private scheduleIdleTransition(instance: StrandInstance): void {
@@ -168,13 +282,16 @@ export class HibernationManager {
 
     log('Idle timeout for strand %s', strandId);
 
-    // Transition to idle
+    // Transition to idle. The callback can reject (e.g. a future idle handler
+    // that releases resources); catch so the timer chain never unhandled-rejects.
     void this.callbacks.onIdle(strandId).then(() => {
       // Schedule hibernate transition
       const timeouts = this.getTimeouts(latencyHint);
       if (timeouts.hibernateTimeout !== Infinity) {
         this.scheduleHibernateTransition(instance);
       }
+    }).catch((err) => {
+      log('onIdle failed for strand %s: %o', strandId, err);
     });
   }
 
@@ -200,42 +317,94 @@ export class HibernationManager {
 
     log('Hibernate timeout for strand %s', strandId);
 
-    // Transition to hibernating
+    // Transition to hibernating. onHibernate now releases strand-network
+    // resources (quiesce), so its close()/stop() can reject — catch so a failed
+    // hibernate logs instead of producing an unhandled rejection.
     void this.callbacks.onHibernate(strandId).then(() => {
       // Schedule periodic check-ins
       const timeouts = this.getTimeouts(latencyHint);
       if (timeouts.checkInInterval !== Infinity) {
         this.scheduleCheckIn(instance);
       }
+    }).catch((err) => {
+      log('onHibernate failed for strand %s: %o', strandId, err);
     });
   }
 
-  private scheduleCheckIn(instance: StrandInstance): void {
+  /**
+   * Arm the next check-in for a hibernating strand. Each call is a single-shot
+   * `setTimeout` (not a fixed `setInterval`) so the period escalates per
+   * {@link runCheckIn} and a slow `onCheckIn` never overlaps the next tick.
+   *
+   * `delay` is omitted by the chain start ({@link handleHibernateTimeout}),
+   * defaulting to the base `checkInInterval` — which is why backoff naturally
+   * resets to base each fresh hibernation cycle, with no per-strand counter to
+   * clear on wake. Subsequent ticks pass the escalated, capped delay.
+   */
+  private scheduleCheckIn(instance: StrandInstance, delay?: number): void {
     const { strandId, latencyHint } = instance;
     const timeouts = this.getTimeouts(latencyHint);
+    const currentDelay = delay ?? timeouts.checkInInterval;
 
-    // Clear existing check-in timer
+    // Replace any existing check-in timer (no-op if the firing timer rescheduled us).
     const existing = this.checkInTimers.get(strandId);
     if (existing) {
-      clearInterval(existing);
+      clearTimeout(existing);
     }
 
-    // Schedule periodic check-ins
-    const timer = setInterval(() => {
-      if (!this.running) {
-        clearInterval(timer);
-        return;
-      }
+    const timer = setTimeout(() => {
+      void this.runCheckIn(instance, currentDelay);
+    }, currentDelay);
+
+    this.checkInTimers.set(strandId, timer);
+    instance.nextCheckIn = new Date(Date.now() + currentDelay);
+  }
+
+  /**
+   * Run a single check-in tick: invoke `onCheckIn` (a real resume → bounded
+   * sync window → re-hibernate-if-idle cycle in `CadreNode`) and AWAIT it before
+   * deciding the next step.
+   *
+   * - If the strand woke during the check-in (`onCheckIn` left it non-
+   *   `hibernating`), stop the chain — the activity path has re-armed the
+   *   idle/hibernate timers, and the next hibernation restarts the chain at the
+   *   base delay (backoff reset).
+   * - Otherwise escalate the delay by `checkInBackoffFactor`, capped at
+   *   `checkInMaxInterval`, and reschedule.
+   */
+  private async runCheckIn(instance: StrandInstance, currentDelay: number): Promise<void> {
+    const { strandId, latencyHint } = instance;
+    if (!this.running) return;
 
-      log('Check-in for hibernating strand %s', strandId);
-      instance.nextCheckIn = new Date(Date.now() + timeouts.checkInInterval);
+    log('Check-in for hibernating strand %s (delay=%dms)', strandId, currentDelay);
 
-      // In a real implementation, this would query the cohort for pending activity
-      // For now, we just update the nextCheckIn timestamp
-    }, timeouts.checkInInterval);
+    try {
+      await this.callbacks.onCheckIn(strandId);
+    } catch (err) {
+      // A failed check-in (e.g. resume threw) must not break the chain — log and
+      // fall through to reschedule the next, longer-delayed attempt.
+      log('onCheckIn failed for strand %s: %o', strandId, err);
+    }
 
-    this.checkInTimers.set(strandId, timer);
-    instance.nextCheckIn = new Date(Date.now() + timeouts.checkInInterval);
+    if (!this.running) return;
+
+    // The check-in either woke the strand (CadreNode left it active) or left it
+    // hibernating. Inspect the shared instance the callback just mutated.
+    if (instance.status !== 'hibernating') {
+      log('Check-in woke strand %s; backoff resets on next hibernation', strandId);
+      this.checkInTimers.delete(strandId);
+      // The chain is stopping; drop the now-stale next-check-in advertisement so
+      // `getStrand` doesn't report a phantom check-in for a strand that is awake.
+      instance.nextCheckIn = undefined;
+      return;
+    }
+
+    const timeouts = this.getTimeouts(latencyHint);
+    const nextDelay = Math.min(
+      currentDelay * timeouts.checkInBackoffFactor,
+      timeouts.checkInMaxInterval
+    );
+    this.scheduleCheckIn(instance, nextDelay);
   }
 
   private clearTimer(strandId: string): void {
@@ -251,7 +420,7 @@ export class HibernationManager {
 
     const checkInTimer = this.checkInTimers.get(strandId);
     if (checkInTimer) {
-      clearInterval(checkInTimer);
+      clearTimeout(checkInTimer);
       this.checkInTimers.delete(strandId);
     }
   }

package/src/index.ts

@@ -1,79 +1,275 @@
-// Core types
-export * from './types.js';
-
-// Main CadreNode class
-export { CadreNode } from './cadre-node.js';
-
-// Control database
-export { ControlDatabase, type ControlDatabaseConfig } from './control-database.js';
-
-// Strand database
-export { StrandDatabase, type StrandDatabaseConfig } from './strand-database.js';
-
-// Strand management
-export {
-  StrandWatcher,
-  type StrandWatcherCallbacks,
-  type StrandQueryable,
-  type SAppIdLookup,
-  type StrandRowWithApp
-} from './strand-watcher.js';
-export {
-  StrandInstanceManager,
-  type StartStrandConfig,
-  getStrandStoragePath
-} from './strand-instance-manager.js';
-
-// Hibernation
-export {
-  HibernationManager,
-  type HibernationCallbacks
-} from './hibernation-manager.js';
-
-// Arachnode (stub)
-export {
-  ArachnodeStub,
-  createArachnodeStub,
-  type RingConfig
-} from './arachnode-stub.js';
-
-// Enrollment
-export {
-  EnrollmentService,
-  type MemberVerifier,
-  type MemberRegistry
-} from './enrollment.js';
-
-// Strand Solicitation
-export {
-  StrandSolicitationService,
-  type DisclosureValidator,
-  type FormationUsageRecorder,
-  type StrandProvisioner,
-  type FormationSigner,
-  type StrandSolicitationServiceOptions
-} from './strand-solicitation.js';
-
-// Seed Bootstrap
-export {
-  SeedBootstrapService,
-  SEED_PROTOCOL,
-  type SeedBootstrapConfig,
-  type SeedEventCallbacks
-} from './seed-bootstrap.js';
-
-// Schema Verification
-export {
-  signSchema,
-  verifySchema,
-  assertSchemaSignature,
-  SchemaVerificationError
-} from './schema-verification.js';
-
-// Strand Formation (strand-proto integration)
-export {
-  StrandFormationManager,
-  createStrandFormationManager,
-  type StrandFormationManagerConfig,
-  type StrandFormationManagerOptions
-} from './strand-formation-manager.js';
+// Core types
+export * from './types.js';
+
+// Canonical JSON serialization (shared signing payload format)
+export { canonicalJson } from './canonical-json.js';
+
+// Main CadreNode class
+export { CadreNode } from './cadre-node.js';
+
+// Control database
+export { ControlDatabase, buildAuthorizationMessage, type ControlDatabaseConfig, type ControlTable } from './control-database.js';
+
+// Ed25519 key bridge (libp2p Ed25519 -> base64url keypair)
+export { ed25519KeyPairFromLibp2p, ed25519PublicKeyFromPrivate, type Ed25519KeyPair } from './ed25519-key.js';
+
+// Pluggable key store (backend-agnostic identity/owner key material seam).
+// Dependency-free: the interface, error, default slot id, and in-memory backend
+// are safe in every (RN/browser/Node) entry graph. The Node FileKeyStore is a
+// separate subpath module ('@serfab/cadre-core/key-store-file') so its node:fs
+// import never lands here.
+export {
+  InMemoryKeyStore,
+  KeyStoreAccessError,
+  DEFAULT_IDENTITY_KEY_ID,
+  type KeyStore,
+  type KeyId
+} from './key-store.js';
+
+// Strand database
+export { StrandDatabase, type StrandDatabaseConfig } from './strand-database.js';
+
+// Strand management
+export {
+  StrandWatcher,
+  type StrandWatcherCallbacks,
+  type StrandQueryable,
+  type SAppIdLookup,
+  type StrandRowWithApp
+} from './strand-watcher.js';
+export {
+  StrandInstanceManager,
+  type StartStrandConfig,
+  type ResumeStrandOverrides,
+  getStrandStoragePath
+} from './strand-instance-manager.js';
+
+// Hibernation
+export {
+  HibernationManager,
+  type HibernationCallbacks
+} from './hibernation-manager.js';
+
+// Arachnode (stub)
+export {
+  ArachnodeStub,
+  createArachnodeStub,
+  type RingConfig
+} from './arachnode-stub.js';
+
+// Enrollment
+export {
+  EnrollmentService,
+  type MemberVerifier,
+  type MemberRegistry
+} from './enrollment.js';
+
+// Strand Solicitation
+export {
+  StrandSolicitationService,
+  createDefaultFormationResponseValidator,
+  type DisclosureValidator,
+  type FormationUsageRecorder,
+  type ResolvedHostStrand,
+  type StrandProvisioner,
+  type FormationSigner,
+  type FormationResponseValidator,
+  type StrandSolicitationServiceOptions
+} from './strand-solicitation.js';
+
+// DB-backed FormationUsageRecorder (reads/writes the real CadreControl tables)
+export { ControlFormationUsageRecorder } from './control-formation-recorder.js';
+
+// Closed-strand member key generation (ed25519 protobuf, base64) + the
+// protobuf->base64url bridge that derives the founding Member/Manager key.
+export { generateStrandMemberKey, strandMemberKeyPair } from './strand-member-key.js';
+
+// Strand membership writer (founder bootstrap, invite issuance/consumption,
+// manager-admit, member-peer registration, manager rotation, + shared signing
+// primitives reused across the flows).
+export {
+  signStrandPayload,
+  verifyStrandPayload,
+  bootstrapFounderMembership,
+  issueInvite,
+  consumeInvite,
+  addMemberByManager,
+  registerMemberPeer,
+  addManager,
+  removeManager,
+  STRAND_ENGINE,
+  STRAND_ENGINE_VERSION,
+  type FounderBootstrapParams,
+  type IssueInviteParams,
+  type IssuedInvite,
+  type ConsumeInviteParams,
+  type AddMemberByManagerParams,
+  type RegisterMemberPeerParams,
+  type AddManagerParams,
+  type RemoveManagerParams
+} from './strand-membership-writer.js';
+
+// Engine-canonical datetime helper (shared by control + strand signed-write flows
+// so a signed timestamp byte-matches the datetime-coerced column the CHECK sees).
+export { canonicalDatetime } from './canonical-datetime.js';
+
+// Strand-DB-backed EnrollmentService backing: concrete MemberRegistry +
+// MemberVerifier that write/read the real Strand.* membership tables.
+export {
+  StrandMemberRegistry,
+  StrandMemberVerifier,
+  memberRegistrationPayload,
+  type StrandAdmission
+} from './strand-member-registry.js';
+
+// Seed Bootstrap
+export {
+  SeedBootstrapService,
+  SEED_PROTOCOL,
+  ed25519PublicKeyB64FromPeerId,
+  type SeedBootstrapConfig,
+  type SeedEventCallbacks
+} from './seed-bootstrap.js';
+
+// Peer Authorization (shared owner-signature digest + offline verifier)
+export {
+  peerAuthorizationDigest,
+  cadrePeerVoucherDigest,
+  cadrePeerRemoveDigest,
+  verifyPeerAuthorization
+} from './peer-authorization.js';
+
+// Strand Wake (control-network push-wake protocol)
+export {
+  StrandWakeService,
+  dialWake,
+  WAKE_PROTOCOL,
+  type StrandWakeServiceOptions,
+  type DialWakeOptions
+} from './strand-wake-protocol.js';
+
+// Strand Address (control-network strand-address RPC) — wire types come via
+// `export * from './types.js'` (StrandAddrRequest / StrandAddrResponse).
+export {
+  StrandAddrService,
+  collectStrandAddrs,
+  STRAND_ADDR_PROTOCOL,
+  type StrandAddrServiceOptions,
+  type StrandAddrPeer,
+  type CollectStrandAddrsOptions
+} from './strand-addr-protocol.js';
+
+// Peer-address record (self-published, signed, freshness-stamped CadrePeer row)
+export {
+  peerRecordSignedPayload,
+  signPeerRecord,
+  verifyPeerRecordSignature,
+  isPeerRecordFresh,
+  isSignalingAddr,
+  orderSignalingFirst,
+  currentMemberTrustPolicy,
+  DEFAULT_PEER_RECORD_MAX_AGE_MS,
+  DEFAULT_PEER_RECORD_HEARTBEAT_MS
+} from './peer-record.js';
+
+// Device-token record (self-published, signed FCM/APNs push token — CadrePeer sibling)
+export {
+  deviceTokenSignedPayload,
+  signDeviceTokenRecord,
+  verifyDeviceTokenSignature,
+  isPushPlatform
+} from './device-token.js';
+
+// Strand-wake payload contract (canonical; shared by the server sender + RN receiver)
+export { STRAND_WAKE_TYPE, type StrandWakePayload } from './strand-wake-payload.js';
+
+// Platform push delivery — the cross-platform `PushNotifier` *contract* only.
+// The FCM/APNs implementations (node:http2/node:crypto) and the
+// `createPushNotifier` router that builds them live behind the Node-only subpath
+// `@serfab/cadre-core/push-node` (`push-node.ts`), never in this graph. A Node
+// host constructs a notifier from that subpath and injects the instance into
+// `CadreNodeConfig.push.notifier`. These re-exports are type-only (erased at
+// emit), so the RN/browser entry graph never pulls the Node modules in.
+export type { PushNotifier, PushMessage, PushSendResult } from './push-notifier.js';
+
+// Push-credential validation + log redaction. Dependency-free (type-only imports),
+// so a provisioner (cadre-host / cadre-provider) can reject a partial credential
+// set and produce a key-safe log view without pulling the FCM/APNs sender graph.
+export { validatePushCredentials, redactPushCredentials, REDACTED } from './push-credentials.js';
+
+// Server-side push-wake trigger policy + fan-out (who/when to wake). Cross-platform
+// clean — it imports only the PushNotifier *type*, so exporting it as a runtime
+// value pulls no node:http2/node:crypto edge into the RN/browser graph.
+export {
+  PushFanoutService,
+  DEFAULT_PUSH_COOLDOWN_MS,
+  DEFAULT_PUSH_DEBOUNCE_MS,
+  type PushFanoutOptions,
+  type FanoutMember
+} from './push-fanout.js';
+
+// Control-cohort dial selection (backbone-preferential, bounded out-degree) +
+// the cadence/degree defaults the proactive reconcile routine reads.
+export {
+  selectControlCohortDials,
+  DEFAULT_CONTROL_COHORT_RECONCILE_MS,
+  DEFAULT_CONTROL_COHORT_TARGET_DEGREE,
+  type ControlCohortSelection
+} from './control-cohort.js';
+
+// Seed trust policy (trust anchor for incoming seeds)
+export {
+  dbAnchoredTrustPolicy,
+  pinnedKeyTrustPolicy,
+  tofuTrustPolicy,
+  type SeedTrustPolicy,
+  type SeedTrustContext,
+  type SeedTrustDecision
+} from './seed-trust-policy.js';
+
+// Schema Verification
+export {
+  signSchema,
+  verifySchema,
+  assertSchemaSignature,
+  SchemaVerificationError
+} from './schema-verification.js';
+
+// Strand Formation transport (native cadre-core protocol)
+export {
+  FormationListener,
+  dialFormation,
+  isValidResponderCreatesResult,
+  FORMATION_PROTOCOL,
+  type FormationParty,
+  type FormationContactMessage,
+  type FormationResultMessage,
+  type FormationProvisionResult,
+  type FormationStrandInfo,
+  type FormationDbConnectionInfo,
+  type FormationListenerOptions,
+  type FormationDialOptions,
+  type ResponderProvisionOutcome
+} from './strand-formation-protocol.js';
+
+// Strand Formation manager (drives the native transport)
+export {
+  StrandFormationManager,
+  createStrandFormationManager,
+  type StrandFormationManagerConfig,
+  type StrandFormationManagerOptions
+} from './strand-formation-manager.js';
+
+// Connection-path diagnostics (relayed vs direct classification + summary)
+export {
+  classifyTransport,
+  classifyConnectionPath,
+  summarizeConnectionPaths,
+  emptyConnectionPathSummary,
+  DEFAULT_SETTLE_WINDOW_MS,
+  type ConnectionPathKind,
+  type ConnectionTransport,
+  type ConnectionPath,
+  type ConnectionPathSummary,
+  type ConnectionLike
+} from './diagnostics/connection-path.js';