@did-btcr2/method 0.38.0 → 0.40.0

package/src/core/aggregation/runner/service-runner.ts

@@ -1,888 +0,0 @@
-import type { SchnorrKeyPair } from '@did-btcr2/keypair';
-import { AggregationServiceError } from '../errors.js';
-import type { BaseMessage } from '../messages/base.js';
-import {
-  COHORT_OPT_IN,
-  FALLBACK_SIGNATURE,
-  NONCE_CONTRIBUTION,
-  SIGNATURE_AUTHORIZATION,
-  SUBMIT_NONINCLUDED,
-  SUBMIT_UPDATE,
-  VALIDATION_ACK,
-} from '../messages/constants.js';
-import { ServiceCohortPhase } from '../phases.js';
-import type { ServiceCohortPhaseType } from '../phases.js';
-import type {
-  AggregationResult,
-  CohortConfig,
-  PendingOptIn,
-  SigningTxData} from '../service.js';
-import {
-  AggregationService
-} from '../service.js';
-import type { Transport } from '../transport/transport.js';
-import { DEFAULT_FEE_ESTIMATOR } from '../../beacon/fee-estimator.js';
-import type { FeeEstimator } from '../../beacon/fee-estimator.js';
-import type { AggregationServiceEvents } from './events.js';
-import { TypedEventEmitter } from './typed-emitter.js';
-
-/** Decision callback: accept or reject a participant's opt-in. */
-export type OnOptInReceived = (optIn: PendingOptIn) => Promise<{ accepted: boolean }>;
-
-/** Decision callback: finalize keygen now, or wait for more participants. */
-export type OnReadyToFinalize = (info: {
-  acceptedCount: number;
-  minRequired: number;
-}) => Promise<{ finalize: boolean }>;
-
-/** Data callback: provide the Bitcoin transaction data to sign. */
-export type OnProvideTxData = (info: {
-  cohortId: string;
-  beaconAddress: string;
-  signalBytes: Uint8Array;
-  /**
-   * Fee estimator the runner is configured with (the runner's `feeEstimator`
-   * option, or a static 5 sat/vB default). Forward it to the beacon transaction
-   * builder so a dynamic rate injected at the runner is honored, rather than
-   * hard-coding a rate inside this callback (ADR 045).
-   */
-  feeEstimator: FeeEstimator;
-}) => Promise<SigningTxData>;
-
-export interface AggregationServiceRunnerOptions {
-  /** Underlying transport (NostrTransport, MockTransport, etc.). */
-  transport: Transport;
-
-  /** This service's identity. */
-  did: string;
-  keys: SchnorrKeyPair;
-
-  /**
-   * Default cohort configuration for the {@link AggregationServiceRunner.run}
-   * convenience path. Optional: omit it when driving the runner with
-   * {@link AggregationServiceRunner.advertiseCohort}, which takes a per-cohort
-   * config and can be called many times on one runner.
-   */
-  config?: CohortConfig;
-
-  /**
-   * Decide whether to accept a participant's opt-in.
-   * Default: auto-accept all opt-ins.
-   */
-  onOptInReceived?: OnOptInReceived;
-
-  /**
-   * Decide whether to finalize keygen now or wait for more participants.
-   * Called after each accepted opt-in once minParticipants is reached.
-   * Default: finalize as soon as minParticipants is reached.
-   */
-  onReadyToFinalize?: OnReadyToFinalize;
-
-  /**
-   * Provide the Bitcoin transaction data to sign.
-   * REQUIRED - no sensible default.
-   */
-  onProvideTxData: OnProvideTxData;
-
-  /**
-   * Fee estimator passed to {@link OnProvideTxData} so the beacon transaction the
-   * callback builds is sized at a chosen rate. Inject a dynamic estimator (a mempool
-   * API or Bitcoin Core `estimatesmartfee`) here as the single standard point for
-   * fee-rate selection, instead of hard-coding a rate inside the callback (ADR 045).
-   * Defaults to a static 5 sat/vB estimator.
-   */
-  feeEstimator?: FeeEstimator;
-
-  /**
-   * Maximum canonicalized byte-length of a signed update body. Submissions
-   * above this cap are rejected and surfaced via the `message-rejected` event.
-   * Defaults to {@link DEFAULT_MAX_UPDATE_SIZE_BYTES} (256 KiB).
-   */
-  maxUpdateSizeBytes?: number;
-
-  /**
-   * Overall wall-clock budget for each cohort, from advertise to
-   * signing-complete. On expiry the cohort is dropped, `cohort-failed` is
-   * emitted, and that cohort's completion rejects with a timeout error. Other
-   * cohorts on the same runner are unaffected. Leave undefined to disable.
-   */
-  cohortTtlMs?: number;
-
-  /**
-   * Maximum time allowed between phase transitions for a cohort. Protects
-   * against stalled cohorts (e.g. a participant vanishing mid-protocol). Reset
-   * automatically on every observed phase change. Applied per cohort. Leave
-   * undefined to disable.
-   */
-  phaseTimeoutMs?: number;
-
-  /**
-   * Re-publish COHORT_ADVERT on this interval until a cohort's keygen is
-   * finalized. Works around relays that don't backfill historical events to
-   * late subscribers - a republish gives late joiners a window to discover the
-   * advert without protocol changes. The first publish is immediate;
-   * subsequent publishes fire every `advertRepeatIntervalMs` until that
-   * cohort's keygen completes, fails, or is stopped. Defaults to
-   * {@link DEFAULT_ADVERT_REPEAT_INTERVAL_MS} (60 s). Set to 0 to publish
-   * once and never retry.
-   */
-  advertRepeatIntervalMs?: number;
-
-  /**
-   * When a cohort stalls (phase timeout) while the optimistic n-of-n signing
-   * round is in flight, fall back to the k-of-n script path instead of failing
-   * the cohort (graceful liveness, ADR 042). Off by default: enabling it trades a
-   * cheaper/private key-path spend for a larger script-path spend whenever the
-   * optimistic round does not complete in time. A stall outside the signing
-   * phases still fails the cohort. Operators can also drive the fallback
-   * explicitly via {@link AggregationServiceRunner.triggerFallback}.
-   */
-  autoFallbackOnStall?: boolean;
-}
-
-/** Default cadence for re-publishing COHORT_ADVERT until keygen completes: 60 seconds. */
-export const DEFAULT_ADVERT_REPEAT_INTERVAL_MS = 60_000;
-
-/**
- * Per-cohort runtime bookkeeping the runner keeps for each advertised cohort.
- * One {@link RunContext} per cohortId lives in the runner's `#contexts` map so
- * many cohorts run concurrently on a single runner, each with its own
- * completion promise, finalize guard, timers, and advert-republish loop. The
- * underlying {@link AggregationService} state machine is already keyed by
- * cohortId; this struct is the runner-layer counterpart (see ADR 040).
- */
-interface RunContext {
-  /** The cohort this context drives. */
-  cohortId: string;
-  /** The conditions this cohort was advertised with. */
-  config: CohortConfig;
-  /** Resolve this cohort's completion with its aggregation result. */
-  resolve: (result: AggregationResult) => void;
-  /** Reject this cohort's completion. */
-  reject: (err: Error) => void;
-  /** The promise handed back from {@link AggregationServiceRunner.advertiseCohort}. */
-  completion: Promise<AggregationResult>;
-  /**
-   * Guard against the async race where two concurrent #handleOptIn invocations
-   * for THIS cohort both pass the `participants.length >= minParticipants`
-   * check before either mutates the cohort phase. Set synchronously before any
-   * `await` so subsequent handlers observe it on their next resumption.
-   */
-  finalizing: boolean;
-  /** Once settled (resolved or rejected), late timers/messages must not re-settle. */
-  settled: boolean;
-  /**
-   * The spend path this cohort is committed to once signing reaches a decision:
-   * `optimistic` (n-of-n key path) or `fallback` (k-of-n script path). A cohort
-   * spends its single beacon UTXO exactly once, so this latch (set synchronously
-   * before any await) ensures the optimistic completion and the fallback never
-   * both finalize and broadcast the same UTXO (the ADR-042 double-spend hazard).
-   */
-  committedPath?: 'optimistic' | 'fallback';
-  cohortTtlTimer?: ReturnType<typeof setTimeout>;
-  phaseTimer?: ReturnType<typeof setTimeout>;
-  lastObservedPhase?: string;
-  /** Stop handle for THIS cohort's repeating COHORT_ADVERT publish loop. */
-  stopAdvertRepeat?: () => void;
-}
-
-/**
- * High-level facade for running an Aggregation Service over a Transport.
- *
- * Wires the {@link AggregationService} state machine to a {@link Transport},
- * encapsulating message handler registration, outgoing message dispatch,
- * and decision callback orchestration.
- *
- * A single runner is a long-lived multiplexer: it advertises and drives many
- * cohorts concurrently over one transport. Each advertised cohort owns an
- * independent completion promise and fails in isolation - a stalled or failed
- * cohort never settles its siblings (see ADR 040). Use
- * {@link AggregationServiceRunner.advertiseCohort} for the multi-cohort path;
- * {@link AggregationServiceRunner.run} is a thin single-cohort convenience over
- * it.
- *
- * @example
- * ```typescript
- * const transport = new NostrTransport({ relays: [RELAY] });
- * transport.registerActor(serviceDid, serviceKeys);
- *
- * const runner = new AggregationServiceRunner({
- *   transport,
- *   did: serviceDid,
- *   keys: serviceKeys,
- *   onProvideTxData: async ({ beaconAddress, signalBytes, feeEstimator }) => {
- *     // Forward feeEstimator so a dynamic rate injected at the runner is honored.
- *     return await buildBeaconTransaction(beaconAddress, signalBytes, bitcoin, feeEstimator);
- *   },
- * });
- *
- * runner.on('keygen-complete', ({ cohortId, beaconAddress }) => console.log(beaconAddress));
- * runner.on('signing-complete', ({ cohortId, signature }) => console.log('done', cohortId));
- *
- * // Multi-cohort: advertise several cohorts; each completion resolves independently.
- * const a = runner.advertiseCohort({ minParticipants: 2, network: 'mutinynet', beaconType: 'CASBeacon' });
- * const b = runner.advertiseCohort({ minParticipants: 3, network: 'mutinynet', beaconType: 'SMTBeacon' });
- * const [ra, rb] = await Promise.all([a.completion, b.completion]);
- *
- * // Single-cohort convenience (requires `config` in the options):
- * // const result = await runner.run();
- * ```
- *
- * For full manual control, drop down to the underlying state machine via
- * `runner.session`. The state machine has no transport coupling and exposes
- * every protocol decision as an explicit method.
- *
- * @class AggregationServiceRunner
- */
-export class AggregationServiceRunner extends TypedEventEmitter<AggregationServiceEvents> {
-  /** Direct access to the underlying state machine for advanced use. */
-  readonly session: AggregationService;
-
-  readonly #transport: Transport;
-  readonly #did: string;
-  readonly #defaultConfig?: CohortConfig;
-  readonly #onOptInReceived: OnOptInReceived;
-  readonly #onReadyToFinalize: OnReadyToFinalize;
-  readonly #onProvideTxData: OnProvideTxData;
-  readonly #feeEstimator: FeeEstimator;
-  readonly #cohortTtlMs?: number;
-  readonly #phaseTimeoutMs?: number;
-  readonly #advertRepeatIntervalMs: number;
-  readonly #autoFallbackOnStall: boolean;
-
-  /** Phases during which a stall can be salvaged by the k-of-n fallback (ADR 042). */
-  static readonly #SIGNING_PHASES: readonly ServiceCohortPhaseType[] = [
-    ServiceCohortPhase.SigningStarted,
-    ServiceCohortPhase.NoncesCollected,
-    ServiceCohortPhase.AwaitingPartialSigs,
-  ];
-
-  /** Per-cohort run state, keyed by cohortId. */
-  readonly #contexts: Map<string, RunContext> = new Map();
-  #handlersRegistered = false;
-  #stopped = false;
-
-  constructor(options: AggregationServiceRunnerOptions) {
-    super();
-    this.#transport = options.transport;
-    this.#did = options.did;
-    this.#defaultConfig = options.config;
-    this.#onOptInReceived = options.onOptInReceived ?? (async () => ({ accepted: true }));
-    this.#onReadyToFinalize = options.onReadyToFinalize ?? (async ({ acceptedCount, minRequired }) => ({
-      finalize : acceptedCount >= minRequired,
-    }));
-    this.#onProvideTxData = options.onProvideTxData;
-    this.#feeEstimator = options.feeEstimator ?? DEFAULT_FEE_ESTIMATOR;
-    this.#cohortTtlMs = options.cohortTtlMs;
-    this.#phaseTimeoutMs = options.phaseTimeoutMs;
-    this.#advertRepeatIntervalMs = options.advertRepeatIntervalMs ?? DEFAULT_ADVERT_REPEAT_INTERVAL_MS;
-    this.#autoFallbackOnStall = options.autoFallbackOnStall ?? false;
-
-    this.session = new AggregationService({
-      // The coordinator never signs, so the state machine receives only the
-      // public half of the operator's keypair (see ADR 038). The full keypair
-      // remains the operator's transport/communication identity.
-      did                : options.did,
-      publicKey          : options.keys.publicKey,
-      maxUpdateSizeBytes : options.maxUpdateSizeBytes,
-    });
-  }
-
-  /** Resolve the {@link RunContext} an inbound message belongs to, by cohortId. */
-  #contextFor(msg: BaseMessage): RunContext | undefined {
-    const cohortId = msg.body?.cohortId;
-    if(!cohortId) return undefined;
-    return this.#contexts.get(cohortId);
-  }
-
-  /**
-   * Drain any silent rejections the state machine recorded for a cohort during
-   * the most recent receive() and surface them as `message-rejected` events.
-   */
-  #drainRejections(ctx: RunContext): void {
-    for(const r of this.session.drainRejections(ctx.cohortId)) {
-      this.emit('message-rejected', { cohortId: ctx.cohortId, ...r });
-    }
-  }
-
-  /**
-   * Advertise a new cohort and begin driving it to completion. Callable many
-   * times on one runner; each cohort runs concurrently and independently.
-   *
-   * @param config Per-cohort conditions + network (see {@link CohortConfig}).
-   * @returns The new cohort's id and a `completion` promise that resolves with
-   *   that cohort's {@link AggregationResult} (or rejects if it fails/stalls).
-   * @throws If the runner has been stopped, or the config is invalid
-   *   (fail-fast via `createCohort`).
-   */
-  advertiseCohort(config: CohortConfig): { cohortId: string; completion: Promise<AggregationResult> } {
-    if(this.#stopped) {
-      throw new AggregationServiceError('Cannot advertise on a stopped runner.', 'RUNNER_STOPPED', {});
-    }
-    this.#registerHandlers();
-    // createCohort validates the conditions and throws on a bad config before
-    // any context exists - fail-fast, nothing to clean up.
-    const cohortId = this.session.createCohort(config);
-
-    let resolve!: (result: AggregationResult) => void;
-    let reject!: (err: Error) => void;
-    const completion = new Promise<AggregationResult>((res, rej) => { resolve = res; reject = rej; });
-    const ctx: RunContext = {
-      cohortId,
-      config,
-      resolve,
-      reject,
-      completion,
-      finalizing : false,
-      settled    : false,
-    };
-    this.#contexts.set(cohortId, ctx);
-
-    try {
-      this.#startTimers(ctx);
-      // Emit cohort-advertised BEFORE the send so the event fires before any downstream cascade.
-      const advertMsgs = this.session.advertise(cohortId);
-      this.#onPhaseMaybeChanged(ctx);
-      this.emit('cohort-advertised', { cohortId });
-      // Publish the advert. If advertRepeatIntervalMs > 0 we republish on that
-      // cadence until this cohort's keygen-complete / fail / stop - works around
-      // relays that don't backfill historical events to late subscribers.
-      // Otherwise fall back to a single send.
-      if(this.#advertRepeatIntervalMs > 0) {
-        this.#startAdvertRepeat(ctx, advertMsgs);
-      } else {
-        this.#sendAll(advertMsgs).catch(err => this.#failCohort(ctx, err as Error));
-      }
-    } catch(err) {
-      this.#failCohort(ctx, err as Error);
-    }
-
-    return { cohortId, completion };
-  }
-
-  /**
-   * Run a single cohort to completion using the `config` supplied in the
-   * runner options. Thin convenience over {@link advertiseCohort} for the
-   * single-cohort case (and the path {@link AggregationRunner.solo} rides).
-   *
-   * @returns {Promise<AggregationResult>} The final result with signature and signed tx.
-   */
-  run(): Promise<AggregationResult> {
-    if(!this.#defaultConfig) {
-      return Promise.reject(new AggregationServiceError(
-        'run() requires `config` in the runner options; use advertiseCohort(config) to drive cohorts explicitly.',
-        'MISSING_COHORT_CONFIG', {}
-      ));
-    }
-    try {
-      return this.advertiseCohort(this.#defaultConfig).completion;
-    } catch(err) {
-      return Promise.reject(err as Error);
-    }
-  }
-
-  /**
-   * Wait for every currently-outstanding cohort to settle and return the
-   * successful results. Dynamic drain: cohorts advertised while this is pending
-   * are included, and it resolves only once no cohorts remain. Failed cohorts
-   * are surfaced via `error` / `cohort-failed` events and their rejected
-   * `completion` promises; they are omitted from the returned array (this
-   * method does not throw). Bound long-running cohorts with `cohortTtlMs` /
-   * `phaseTimeoutMs` or this may never resolve.
-   *
-   * @returns {Promise<AggregationResult[]>} Results of the cohorts that completed.
-   */
-  async runAll(): Promise<AggregationResult[]> {
-    const collected = new Map<string, AggregationResult>();
-    // Capture every completion, including a cohort that is advertised and
-    // finishes entirely within one drain round (so it never appears in a
-    // snapshot below).
-    const onComplete = (result: AggregationResult): void => { collected.set(result.cohortId, result); };
-    this.on('signing-complete', onComplete);
-    try {
-      // Block until the live set empties; re-snapshot each round to pick up
-      // cohorts advertised mid-drain.
-      while(this.#contexts.size > 0) {
-        await Promise.allSettled([ ...this.#contexts.values() ].map(c => c.completion));
-      }
-    } finally {
-      this.off('signing-complete', onComplete);
-    }
-    return [ ...collected.values() ];
-  }
-
-  /**
-   * Begin publishing a cohort's advert immediately and on a repeating interval
-   * until the cohort's advert loop is stopped. Each advert is broadcast (no
-   * recipient) via the transport's `publishRepeating` primitive.
-   */
-  #startAdvertRepeat(ctx: RunContext, advertMsgs: BaseMessage[]): void {
-    // COHORT_ADVERT is always a single broadcast message in the current
-    // protocol, but iterate for generality.
-    const stops: Array<() => void> = [];
-    for(const msg of advertMsgs) {
-      stops.push(this.#transport.publishRepeating(msg, this.#did, this.#advertRepeatIntervalMs));
-    }
-    ctx.stopAdvertRepeat = () => {
-      for(const stop of stops) {
-        try { stop(); } catch { /* ignore */ }
-      }
-    };
-  }
-
-  /** Stop a cohort's advert republish loop. Idempotent. */
-  #stopAdvertRepeating(ctx: RunContext): void {
-    if(!ctx.stopAdvertRepeat) return;
-    const stop = ctx.stopAdvertRepeat;
-    ctx.stopAdvertRepeat = undefined;
-    stop();
-  }
-
-  /** Schedule a cohort's TTL + phase timeout when it is advertised. */
-  #startTimers(ctx: RunContext): void {
-    if(this.#cohortTtlMs !== undefined) {
-      ctx.cohortTtlTimer = setTimeout(() => {
-        const reason = `Cohort ${ctx.cohortId} exceeded TTL of ${this.#cohortTtlMs}ms`;
-        this.emit('cohort-failed', { cohortId: ctx.cohortId, reason });
-        this.#failCohort(ctx, new Error(reason));
-      }, this.#cohortTtlMs);
-    }
-    this.#resetPhaseTimer(ctx);
-  }
-
-  /** Reset a cohort's per-phase stall timer. Called when a phase transition is observed. */
-  #resetPhaseTimer(ctx: RunContext): void {
-    if(ctx.phaseTimer) clearTimeout(ctx.phaseTimer);
-    ctx.phaseTimer = undefined;
-    if(this.#phaseTimeoutMs === undefined) return;
-    ctx.phaseTimer = setTimeout(() => {
-      // A stall during the optimistic signing round can be salvaged by the k-of-n
-      // fallback rather than failing the whole cohort (graceful liveness, ADR
-      // 042) - but only if enabled and not already committed to a path.
-      const phase = this.session.getCohortPhase(ctx.cohortId);
-      const inSigning = phase !== undefined && AggregationServiceRunner.#SIGNING_PHASES.includes(phase);
-      if(this.#autoFallbackOnStall && inSigning && !ctx.committedPath && !ctx.settled) {
-        this.triggerFallback(ctx.cohortId).catch(err => this.#failCohort(ctx, err as Error));
-        return;
-      }
-      const reason = `Cohort ${ctx.cohortId} stalled in phase ${ctx.lastObservedPhase ?? '?'} for ${this.#phaseTimeoutMs}ms`;
-      this.emit('cohort-failed', { cohortId: ctx.cohortId, reason });
-      this.#failCohort(ctx, new Error(reason));
-    }, this.#phaseTimeoutMs);
-  }
-
-  /**
-   * Abandon the optimistic n-of-n key path for a cohort and collect k-of-n
-   * fallback (script-path) signatures instead (ADR 042). Idempotent and safe
-   * against the optimistic completion: it commits the cohort to the fallback
-   * path synchronously (the `committedPath` latch) before sending anything, so a
-   * late optimistic signature can no longer complete-and-broadcast a competing
-   * spend of the same UTXO. No-op if the cohort is unknown, already settled, or
-   * already committed to a path.
-   *
-   * Wired automatically to the phase-stall timer when `autoFallbackOnStall` is
-   * set; otherwise call it from an operator decision (a UI "fall back now"
-   * action). Throws only if the underlying state machine rejects the transition
-   * (e.g. signing has not started).
-   */
-  async triggerFallback(cohortId: string): Promise<void> {
-    const ctx = this.#contexts.get(cohortId);
-    if(!ctx || ctx.settled || ctx.committedPath) return;
-    // startFallbackSigning is synchronous and throws if the cohort is not in a
-    // signing phase (e.g. a premature operator call). Run it FIRST so a rejected
-    // transition cannot poison the latch: only after it commits the state machine
-    // to the fallback do we set committedPath. This still happens synchronously
-    // before any await, so a concurrent optimistic completion observes the latch
-    // and stands down - but a bad-phase call leaves the optimistic path intact.
-    const messages = this.session.startFallbackSigning(cohortId);
-    ctx.committedPath = 'fallback';
-    this.#stopAdvertRepeating(ctx);
-    this.#onPhaseMaybeChanged(ctx);
-    const sessionId = this.session.getSigningSessionId(cohortId) ?? '';
-    this.emit('fallback-started', { cohortId, sessionId });
-    await this.#sendAll(messages);
-  }
-
-  /** Detect a phase change for a cohort since the last observation and reset its phase timer. */
-  #onPhaseMaybeChanged(ctx: RunContext): void {
-    const phase = this.session.getCohortPhase(ctx.cohortId);
-    if(phase !== ctx.lastObservedPhase) {
-      ctx.lastObservedPhase = phase;
-      this.#resetPhaseTimer(ctx);
-    }
-  }
-
-  /** Clear a cohort's timers. Called on completion, stop, and failure. */
-  #clearTimers(ctx: RunContext): void {
-    if(ctx.cohortTtlTimer) clearTimeout(ctx.cohortTtlTimer);
-    if(ctx.phaseTimer) clearTimeout(ctx.phaseTimer);
-    ctx.cohortTtlTimer = undefined;
-    ctx.phaseTimer = undefined;
-  }
-
-  /**
-   * Reclaim one cohort's runner-layer bookkeeping: stop its advert loop, clear
-   * its timers, and drop its {@link RunContext}. Does NOT touch sibling cohorts
-   * and does NOT detach the shared transport handlers. Leaves the cohort in the
-   * state machine; whether that cohort's `session` state is also removed is the
-   * caller's choice (see {@link #completeCohort} vs {@link #failCohort}).
-   */
-  #disposeCohort(ctx: RunContext): void {
-    this.#stopAdvertRepeating(ctx);
-    this.#clearTimers(ctx);
-    this.#contexts.delete(ctx.cohortId);
-  }
-
-  /**
-   * Settle one cohort successfully. Reclaims the runner context but leaves the
-   * completed cohort in `session` so callers can read its beaconAddress / cohort
-   * via `session.getCohort(result.cohortId)`; reclaim it with
-   * `session.removeCohort(cohortId)` when done. Idempotent via `ctx.settled`.
-   */
-  #completeCohort(ctx: RunContext, result: AggregationResult): void {
-    if(ctx.settled) return;
-    ctx.settled = true;
-    this.#disposeCohort(ctx);
-    this.emit('signing-complete', result);
-    ctx.resolve(result);
-  }
-
-  /**
-   * Fail one cohort. Reclaims its runner context, drops its now-dead state from
-   * the state machine, and rejects only its completion; siblings keep running
-   * and the shared transport handlers stay registered. Idempotent via
-   * `ctx.settled`.
-   */
-  #failCohort(ctx: RunContext, err: Error): void {
-    if(ctx.settled) return;
-    ctx.settled = true;
-    this.#disposeCohort(ctx);
-    this.session.removeCohort(ctx.cohortId);
-    this.emit('error', err);
-    ctx.reject(err);
-  }
-
-  /**
-   * Stop a single cohort early without affecting the rest of the runner. Drops
-   * the cohort's state machine state; its `completion` promise rejects with a
-   * stopped error.
-   */
-  stopCohort(cohortId: string): void {
-    const ctx = this.#contexts.get(cohortId);
-    if(!ctx || ctx.settled) return;
-    ctx.settled = true;
-    this.#disposeCohort(ctx);
-    this.session.removeCohort(cohortId);
-    ctx.reject(new AggregationServiceError(`Cohort ${cohortId} stopped.`, 'COHORT_STOPPED', { cohortId }));
-  }
-
-  /**
-   * Stop the whole runner. Fails every outstanding cohort, then detaches the
-   * shared transport handlers so a restart or a new runner doesn't inherit
-   * stale dispatch. Safe to call repeatedly.
-   */
-  stop(): void {
-    this.#stopped = true;
-    for(const ctx of [ ...this.#contexts.values() ]) {
-      if(ctx.settled) continue;
-      ctx.settled = true;
-      this.#disposeCohort(ctx);
-      this.session.removeCohort(ctx.cohortId);
-      ctx.reject(new AggregationServiceError('Service runner stopped.', 'RUNNER_STOPPED', { cohortId: ctx.cohortId }));
-    }
-    this.#contexts.clear();
-    this.#unregisterHandlers();
-  }
-
-  /** Message types this runner listens for on the transport. */
-  static readonly #HANDLED_MESSAGE_TYPES: readonly string[] = [
-    COHORT_OPT_IN,
-    SUBMIT_UPDATE,
-    SUBMIT_NONINCLUDED,
-    VALIDATION_ACK,
-    NONCE_CONTRIBUTION,
-    SIGNATURE_AUTHORIZATION,
-    FALLBACK_SIGNATURE,
-  ];
-
-  /**
-   * Internal: handler registration with the transport. Idempotent. Handlers
-   * are DID-scoped and cohort-agnostic - one registration serves every cohort
-   * this runner drives; demux to the right {@link RunContext} happens in each
-   * handler via the inbound message's cohortId.
-   */
-  #registerHandlers(): void {
-    if(this.#handlersRegistered) return;
-    this.#handlersRegistered = true;
-
-    this.#transport.registerMessageHandler(this.#did, COHORT_OPT_IN, this.#handleOptIn.bind(this));
-    this.#transport.registerMessageHandler(this.#did, SUBMIT_UPDATE, this.#handleSubmitUpdate.bind(this));
-    // A non-inclusion (decline) is an update-phase response handled identically:
-    // session.receive() routes by type, and the response gate + distribute
-    // trigger are shared with SUBMIT_UPDATE.
-    this.#transport.registerMessageHandler(this.#did, SUBMIT_NONINCLUDED, this.#handleSubmitUpdate.bind(this));
-    this.#transport.registerMessageHandler(this.#did, VALIDATION_ACK, this.#handleValidationAck.bind(this));
-    this.#transport.registerMessageHandler(this.#did, NONCE_CONTRIBUTION, this.#handleNonceContribution.bind(this));
-    this.#transport.registerMessageHandler(this.#did, SIGNATURE_AUTHORIZATION, this.#handleSignatureAuthorization.bind(this));
-    this.#transport.registerMessageHandler(this.#did, FALLBACK_SIGNATURE, this.#handleFallbackSignature.bind(this));
-  }
-
-  /** Internal: detach from the transport. Safe to call repeatedly. */
-  #unregisterHandlers(): void {
-    if(!this.#handlersRegistered) return;
-    this.#handlersRegistered = false;
-    for(const type of AggregationServiceRunner.#HANDLED_MESSAGE_TYPES) {
-      this.#transport.unregisterMessageHandler(this.#did, type);
-    }
-  }
-
-  /**
-   * Internal: message handlers for each protocol step. Each handler:
-   * 1) resolves the cohort the message belongs to (by cohortId); ignores it if unknown
-   * 2) feeds the message into the state machine via session.receive()
-   * 3) emits a high-level event (carrying cohortId) for external observers
-   * 4) checks if the new state triggers any automatic next steps, and if so:
-   *    a) calls the appropriate decision callback(s)
-   *    b) sends any resulting messages from the state machine
-   * Errors fail only the owning cohort. A stopped runner ignores messages.
-   * @param {BaseMessage} msg - The incoming message to handle.
-   * @returns {Promise<void>} Resolves when handling is complete.
-   */
-  async #handleOptIn(msg: BaseMessage): Promise<void> {
-    if(this.#stopped) return;
-    const ctx = this.#contextFor(msg);
-    if(!ctx) return;
-    try {
-      this.session.receive(msg);
-      this.#drainRejections(ctx);
-      this.#onPhaseMaybeChanged(ctx);
-
-      const optIn = this.session.pendingOptIns(ctx.cohortId).get(msg.from);
-      if(!optIn) return;
-      // PendingOptIn already carries cohortId, so this event is cohort-identified.
-      this.emit('opt-in-received', optIn);
-
-      // Register peer key for encrypted messaging
-      if(optIn.communicationPk) {
-        this.#transport.registerPeer(msg.from, optIn.communicationPk);
-      }
-
-      const decision = await this.#onOptInReceived(optIn);
-      if(!decision.accepted) return;
-
-      // Don't accept past the advertised maxParticipants: acceptParticipant
-      // would throw COHORT_FULL and fail the cohort. Silently ignore the surplus
-      // opt-in (the cohort is full).
-      const maxParticipants = ctx.config.maxParticipants;
-      const cohortNow = this.session.getCohort(ctx.cohortId);
-      if(maxParticipants !== undefined && cohortNow && cohortNow.participants.length >= maxParticipants) {
-        return;
-      }
-
-      await this.#sendAll(this.session.acceptParticipant(ctx.cohortId, msg.from));
-      this.emit('participant-accepted', { cohortId: ctx.cohortId, participantDid: msg.from });
-
-      // Check if it's time to finalize. The per-cohort `finalizing` flag is set
-      // synchronously before the first await so concurrent opt-in handlers for
-      // the same cohort observe it and skip - otherwise two handlers could both
-      // pass the minParticipants check and both call finalizeKeygen, the second
-      // of which would throw (phase mismatch).
-      const cohort = this.session.getCohort(ctx.cohortId)!;
-      if(cohort.participants.length >= ctx.config.minParticipants && !ctx.finalizing) {
-        ctx.finalizing = true;
-        const finalizeDecision = await this.#onReadyToFinalize({
-          acceptedCount : cohort.participants.length,
-          minRequired   : ctx.config.minParticipants,
-        });
-        if(!finalizeDecision.finalize) {
-          // Operator declined - reset the flag so a later opt-in can retry.
-          ctx.finalizing = false;
-          return;
-        }
-        // finalizeKeygen() computes the beacon address synchronously
-        // emit BEFORE awaiting sendAll. Otherwise the downstream cascade
-        // (which can run all the way to signing-complete) would resolve the
-        // cohort's completion promise before this event fires.
-        const readyMsgs = this.session.finalizeKeygen(ctx.cohortId);
-        // Keygen done - stop re-advertising the cohort. New participants
-        // arriving after this point would be rejected anyway.
-        this.#stopAdvertRepeating(ctx);
-        this.emit('keygen-complete', {
-          cohortId      : ctx.cohortId,
-          beaconAddress : cohort.beaconAddress,
-        });
-        await this.#sendAll(readyMsgs);
-      }
-    } catch(err) {
-      this.#failCohort(ctx, err as Error);
-    }
-  }
-
-  /**
-   * Handler for receiving participant updates. When all updates are received, automatically builds
-   * and distributes the data for validation.
-   * @param {BaseMessage} msg - The incoming message to handle.
-   * @returns {Promise<void>} Resolves when handling is complete.
-   */
-  async #handleSubmitUpdate(msg: BaseMessage): Promise<void> {
-    if(this.#stopped) return;
-    const ctx = this.#contextFor(msg);
-    if(!ctx) return;
-    try {
-      this.session.receive(msg);
-      this.#drainRejections(ctx);
-      this.#onPhaseMaybeChanged(ctx);
-      this.emit('update-received', { cohortId: ctx.cohortId, participantDid: msg.from });
-
-      // When all updates collected, build and distribute
-      if(this.session.getCohortPhase(ctx.cohortId) === ServiceCohortPhase.UpdatesCollected) {
-        const distributeMsgs = this.session.buildAndDistribute(ctx.cohortId);
-        this.emit('data-distributed', { cohortId: ctx.cohortId });
-        await this.#sendAll(distributeMsgs);
-      }
-    } catch(err) {
-      this.#failCohort(ctx, err as Error);
-    }
-  }
-
-  /**
-   * Handler for receiving validation acknowledgments. When all validations are received,
-   * automatically requests tx data and starts signing.
-   * @param {BaseMessage} msg - The incoming message to handle.
-   * @returns {Promise<void>} Resolves when handling is complete.
-   */
-  async #handleValidationAck(msg: BaseMessage): Promise<void> {
-    if(this.#stopped) return;
-    const ctx = this.#contextFor(msg);
-    if(!ctx) return;
-    try {
-      this.session.receive(msg);
-      this.#drainRejections(ctx);
-      this.#onPhaseMaybeChanged(ctx);
-      const approved = !!msg.body?.approved;
-      this.emit('validation-received', { cohortId: ctx.cohortId, participantDid: msg.from, approved });
-
-      const phase = this.session.getCohortPhase(ctx.cohortId);
-
-      // A participant rejection flips the cohort to Failed. Emit a structured
-      // event so the runner/caller sees the failure instead of the cohort
-      // silently stalling.
-      if(phase === ServiceCohortPhase.Failed) {
-        const reason = `Validation rejected by participant ${msg.from}`;
-        this.emit('cohort-failed', { cohortId: ctx.cohortId, reason });
-        this.#failCohort(ctx, new Error(reason));
-        return;
-      }
-
-      // When all validations received, request tx data and start signing
-      if(phase === ServiceCohortPhase.Validated) {
-        const cohort = this.session.getCohort(ctx.cohortId)!;
-        const txData = await this.#onProvideTxData({
-          cohortId      : ctx.cohortId,
-          beaconAddress : cohort.beaconAddress,
-          signalBytes   : cohort.signalBytes!,
-          feeEstimator  : this.#feeEstimator,
-        });
-        const authMsgs = this.session.startSigning(ctx.cohortId, txData);
-        const sessionId = this.session.getSigningSessionId(ctx.cohortId) ?? '';
-        this.emit('signing-started', { cohortId: ctx.cohortId, sessionId });
-        await this.#sendAll(authMsgs);
-      }
-    } catch(err) {
-      this.#failCohort(ctx, err as Error);
-    }
-  }
-
-  /**
-   * Handler for receiving nonce contributions. When all nonces are received, sends the aggregated
-   * nonce back to the cohort.
-   * @param {BaseMessage} msg - The incoming message to handle.
-   * @returns {Promise<void>} Resolves when handling is complete.
-   */
-  async #handleNonceContribution(msg: BaseMessage): Promise<void> {
-    if(this.#stopped) return;
-    const ctx = this.#contextFor(msg);
-    if(!ctx) return;
-    try {
-      this.session.receive(msg);
-      this.#drainRejections(ctx);
-      this.#onPhaseMaybeChanged(ctx);
-      this.emit('nonce-received', { cohortId: ctx.cohortId, participantDid: msg.from });
-
-      // When all nonces collected, send aggregated nonce
-      if(this.session.getCohortPhase(ctx.cohortId) === ServiceCohortPhase.NoncesCollected) {
-        await this.#sendAll(this.session.sendAggregatedNonce(ctx.cohortId));
-      }
-    } catch(err) {
-      this.#failCohort(ctx, err as Error);
-    }
-  }
-
-  /**
-   * Handler for receiving signature authorizations. When all partial signatures are received, the
-   * session automatically completes; the final result is emitted and the cohort's completion
-   * promise resolves.
-   * @param {BaseMessage} msg - The incoming message to handle.
-   * @returns {Promise<void>} Resolves when handling is complete.
-   */
-  async #handleSignatureAuthorization(msg: BaseMessage): Promise<void> {
-    if(this.#stopped) return;
-    const ctx = this.#contextFor(msg);
-    if(!ctx) return;
-    try {
-      this.session.receive(msg);
-      this.#drainRejections(ctx);
-      this.#onPhaseMaybeChanged(ctx);
-
-      // If the cohort already committed to the fallback path, ignore a late
-      // optimistic completion: only one path may finalize the single beacon UTXO.
-      if(ctx.committedPath === 'fallback') return;
-
-      // The state machine auto-completes when all partial sigs received.
-      const result = this.session.getResult(ctx.cohortId);
-      if(result) {
-        ctx.committedPath = 'optimistic';
-        this.#completeCohort(ctx, result);
-      }
-    } catch(err) {
-      this.#failCohort(ctx, err as Error);
-    }
-  }
-
-  /**
-   * Handler for receiving fallback (k-of-n script-path) signatures. The state
-   * machine assembles and finalizes the fallback spend once k valid signatures
-   * are in; the result is then emitted and the cohort's completion resolves. The
-   * cohort is already committed to the fallback path (via {@link triggerFallback}).
-   * @param {BaseMessage} msg - The incoming FALLBACK_SIGNATURE message.
-   * @returns {Promise<void>} Resolves when handling is complete.
-   */
-  async #handleFallbackSignature(msg: BaseMessage): Promise<void> {
-    if(this.#stopped) return;
-    const ctx = this.#contextFor(msg);
-    if(!ctx) return;
-    try {
-      this.session.receive(msg);
-      this.#drainRejections(ctx);
-      this.#onPhaseMaybeChanged(ctx);
-
-      const result = this.session.getResult(ctx.cohortId);
-      if(result) {
-        this.#completeCohort(ctx, result);
-      }
-    } catch(err) {
-      this.#failCohort(ctx, err as Error);
-    }
-  }
-
-  /**
-   * Internal: helper to send all messages sequentially. Catches and propagates errors.
-   * @param {BaseMessage[]} msgs - The messages to send.
-   * @returns {Promise<void>} Resolves when all messages have been sent.
-   */
-  async #sendAll(msgs: BaseMessage[]): Promise<void> {
-    for(const m of msgs) {
-      await this.#transport.sendMessage(m, this.#did, m.to);
-    }
-  }
-}