@did-btcr2/method 0.36.0 → 0.36.1

package/dist/browser.js

@@ -104727,6 +104727,17 @@ a=end-of-candidates
       }
       return map3;
     }
+    /**
+     * The validated aggregated data retained for a cohort, regardless of phase.
+     * Unlike {@link pendingValidations} (which lists only cohorts still awaiting
+     * the validate decision), this returns the stored validation — including the
+     * participant's sidecar (the CAS Announcement map or its SMT inclusion proof)
+     * — so it is still readable once the cohort reaches Complete. Returns
+     * undefined before aggregated data has been received.
+     */
+    getValidation(cohortId) {
+      return this.#cohortStates.get(cohortId)?.validation;
+    }
     #handleDistributeAggregatedData(message2) {
       const cohortId = message2.body?.cohortId;
       if (!cohortId) return;
@@ -111603,35 +111614,22 @@ ${value2}`;
     session;
     #transport;
     #did;
-    #config;
+    #defaultConfig;
     #onOptInReceived;
     #onReadyToFinalize;
     #onProvideTxData;
     #cohortTtlMs;
     #phaseTimeoutMs;
     #advertRepeatIntervalMs;
-    #cohortId;
+    /** Per-cohort run state, keyed by cohortId. */
+    #contexts = /* @__PURE__ */ new Map();
     #handlersRegistered = false;
     #stopped = false;
-    /**
-     * Guard against the async race where two concurrent #handleOptIn invocations
-     * 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 = false;
-    #resolveRun;
-    #rejectRun;
-    #cohortTtlTimer;
-    #phaseTimer;
-    #lastObservedPhase;
-    /** Stop handle for the repeating COHORT_ADVERT publish loop. */
-    #stopAdvertRepeat;
     constructor(options2) {
       super();
       this.#transport = options2.transport;
       this.#did = options2.did;
-      this.#config = options2.config;
+      this.#defaultConfig = options2.config;
       this.#onOptInReceived = options2.onOptInReceived ?? (async () => ({ accepted: true }));
       this.#onReadyToFinalize = options2.onReadyToFinalize ?? (async ({ acceptedCount, minRequired }) => ({
         finalize: acceptedCount >= minRequired
@@ -111649,55 +111647,126 @@ ${value2}`;
         maxUpdateSizeBytes: options2.maxUpdateSizeBytes
       });
     }
+    /** Resolve the {@link RunContext} an inbound message belongs to, by cohortId. */
+    #contextFor(msg) {
+      const cohortId = msg.body?.cohortId;
+      if (!cohortId) return void 0;
+      return this.#contexts.get(cohortId);
+    }
     /**
-     * Drain any silent rejections the state machine recorded during the most
-     * recent receive() and surface them as `message-rejected` events. Safe to
-     * call even before a cohortId is assigned.
+     * Drain any silent rejections the state machine recorded for a cohort during
+     * the most recent receive() and surface them as `message-rejected` events.
      */
-    #drainRejections() {
-      if (!this.#cohortId) return;
-      for (const r2 of this.session.drainRejections(this.#cohortId)) {
-        this.emit("message-rejected", { cohortId: this.#cohortId, ...r2 });
+    #drainRejections(ctx) {
+      for (const r2 of this.session.drainRejections(ctx.cohortId)) {
+        this.emit("message-rejected", { cohortId: ctx.cohortId, ...r2 });
       }
     }
     /**
-     * Run the protocol to completion. Resolves with the final aggregation result
-     * (signature + signed transaction) once signing is complete.
+     * 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) {
+      if (this.#stopped) {
+        throw new AggregationServiceError("Cannot advertise on a stopped runner.", "RUNNER_STOPPED", {});
+      }
+      this.#registerHandlers();
+      const cohortId = this.session.createCohort(config);
+      let resolve;
+      let reject;
+      const completion = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+      });
+      const ctx = {
+        cohortId,
+        config,
+        resolve,
+        reject,
+        completion,
+        finalizing: false,
+        settled: false
+      };
+      this.#contexts.set(cohortId, ctx);
+      try {
+        this.#startTimers(ctx);
+        const advertMsgs = this.session.advertise(cohortId);
+        this.#onPhaseMaybeChanged(ctx);
+        this.emit("cohort-advertised", { cohortId });
+        if (this.#advertRepeatIntervalMs > 0) {
+          this.#startAdvertRepeat(ctx, advertMsgs);
+        } else {
+          this.#sendAll(advertMsgs).catch((err) => this.#failCohort(ctx, err));
+        }
+      } catch (err) {
+        this.#failCohort(ctx, err);
+      }
+      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() {
-      return new Promise((resolve, reject) => {
-        this.#resolveRun = resolve;
-        this.#rejectRun = reject;
-        try {
-          this.#registerHandlers();
-          this.#cohortId = this.session.createCohort(this.#config);
-          this.#startTimers();
-          const advertMsgs = this.session.advertise(this.#cohortId);
-          this.#onPhaseMaybeChanged();
-          this.emit("cohort-advertised", { cohortId: this.#cohortId });
-          if (this.#advertRepeatIntervalMs > 0) {
-            this.#startAdvertRepeat(advertMsgs);
-          } else {
-            this.#sendAll(advertMsgs).catch((err) => this.#fail(err));
-          }
-        } catch (err) {
-          this.#fail(err);
+      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);
+      }
+    }
+    /**
+     * 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() {
+      const collected = /* @__PURE__ */ new Map();
+      const onComplete = (result) => {
+        collected.set(result.cohortId, result);
+      };
+      this.on("signing-complete", onComplete);
+      try {
+        while (this.#contexts.size > 0) {
+          await Promise.allSettled([...this.#contexts.values()].map((c2) => c2.completion));
         }
-      });
+      } finally {
+        this.off("signing-complete", onComplete);
+      }
+      return [...collected.values()];
     }
     /**
-     * Begin publishing the cohort advert immediately and on a repeating interval
-     * until {@link #stopAdvertRepeating} is called. Each advert is broadcast
-     * (no recipient) via the transport's `publishRepeating` primitive.
+     * 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(advertMsgs) {
+    #startAdvertRepeat(ctx, advertMsgs) {
       const stops = [];
       for (const msg of advertMsgs) {
         stops.push(this.#transport.publishRepeating(msg, this.#did, this.#advertRepeatIntervalMs));
       }
-      this.#stopAdvertRepeat = () => {
+      ctx.stopAdvertRepeat = () => {
         for (const stop2 of stops) {
           try {
             stop2();
@@ -111706,61 +111775,118 @@ ${value2}`;
         }
       };
     }
-    /** Stop the advert republish loop. Idempotent. */
-    #stopAdvertRepeating() {
-      if (!this.#stopAdvertRepeat) return;
-      const stop2 = this.#stopAdvertRepeat;
-      this.#stopAdvertRepeat = void 0;
+    /** Stop a cohort's advert republish loop. Idempotent. */
+    #stopAdvertRepeating(ctx) {
+      if (!ctx.stopAdvertRepeat) return;
+      const stop2 = ctx.stopAdvertRepeat;
+      ctx.stopAdvertRepeat = void 0;
       stop2();
     }
-    /** Schedule cohort TTL + phase timeout at the start of a run. */
-    #startTimers() {
+    /** Schedule a cohort's TTL + phase timeout when it is advertised. */
+    #startTimers(ctx) {
       if (this.#cohortTtlMs !== void 0) {
-        this.#cohortTtlTimer = setTimeout(() => {
-          const reason = `Cohort ${this.#cohortId ?? ""} exceeded TTL of ${this.#cohortTtlMs}ms`;
-          this.emit("cohort-failed", { cohortId: this.#cohortId ?? "", reason });
-          this.#fail(new Error(reason));
+        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();
+      this.#resetPhaseTimer(ctx);
     }
-    /** Reset the per-phase stall timer. Called when a phase transition is observed. */
-    #resetPhaseTimer() {
-      if (this.#phaseTimer) clearTimeout(this.#phaseTimer);
-      this.#phaseTimer = void 0;
+    /** Reset a cohort's per-phase stall timer. Called when a phase transition is observed. */
+    #resetPhaseTimer(ctx) {
+      if (ctx.phaseTimer) clearTimeout(ctx.phaseTimer);
+      ctx.phaseTimer = void 0;
       if (this.#phaseTimeoutMs === void 0) return;
-      this.#phaseTimer = setTimeout(() => {
-        const reason = `Cohort ${this.#cohortId ?? ""} stalled in phase ${this.#lastObservedPhase ?? "?"} for ${this.#phaseTimeoutMs}ms`;
-        this.emit("cohort-failed", { cohortId: this.#cohortId ?? "", reason });
-        this.#fail(new Error(reason));
+      ctx.phaseTimer = setTimeout(() => {
+        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);
     }
-    /** Detect a phase change since the last observation and reset the phase timer. */
-    #onPhaseMaybeChanged() {
-      if (!this.#cohortId) return;
-      const phase = this.session.getCohortPhase(this.#cohortId);
-      if (phase !== this.#lastObservedPhase) {
-        this.#lastObservedPhase = phase;
-        this.#resetPhaseTimer();
+    /** Detect a phase change for a cohort since the last observation and reset its phase timer. */
+    #onPhaseMaybeChanged(ctx) {
+      const phase = this.session.getCohortPhase(ctx.cohortId);
+      if (phase !== ctx.lastObservedPhase) {
+        ctx.lastObservedPhase = phase;
+        this.#resetPhaseTimer(ctx);
       }
     }
-    /** Clear both timers. Called on successful completion, stop(), and #fail. */
-    #clearTimers() {
-      if (this.#cohortTtlTimer) clearTimeout(this.#cohortTtlTimer);
-      if (this.#phaseTimer) clearTimeout(this.#phaseTimer);
-      this.#cohortTtlTimer = void 0;
-      this.#phaseTimer = void 0;
+    /** Clear a cohort's timers. Called on completion, stop, and failure. */
+    #clearTimers(ctx) {
+      if (ctx.cohortTtlTimer) clearTimeout(ctx.cohortTtlTimer);
+      if (ctx.phaseTimer) clearTimeout(ctx.phaseTimer);
+      ctx.cohortTtlTimer = void 0;
+      ctx.phaseTimer = void 0;
+    }
+    /**
+     * 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) {
+      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, result) {
+      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, err) {
+      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) {
+      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 runner early. Marks the runner stopped and detaches transport
-     * handlers so a restart or a new runner doesn't inherit stale dispatch.
+     * 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() {
       this.#stopped = true;
-      this.#stopAdvertRepeating();
-      this.#clearTimers();
+      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();
-      if (this.#cohortId) this.session.removeCohort(this.#cohortId);
     }
     /** Message types this runner listens for on the transport. */
     static #HANDLED_MESSAGE_TYPES = [
@@ -111771,7 +111897,10 @@ ${value2}`;
       SIGNATURE_AUTHORIZATION
     ];
     /**
-     * Internal: handler registration with the transport. Idempotent.
+     * 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() {
       if (this.#handlersRegistered) return;
@@ -111792,23 +111921,25 @@ ${value2}`;
     }
     /**
      * Internal: message handlers for each protocol step. Each handler:
-     * 1) feeds the message into the state machine via session.receive()
-     * 2) emits a high-level event for external observers
-     * 3) checks if the new state triggers any automatic next steps, and if so:
+     * 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.
-      * @throws {Error} If any step of handling fails, the error is emitted and the run promise is rejected.
-      * Note: if the runner has been stopped, handlers will ignore incoming messages.
      */
     async #handleOptIn(msg) {
       if (this.#stopped) return;
+      const ctx = this.#contextFor(msg);
+      if (!ctx) return;
       try {
         this.session.receive(msg);
-        this.#drainRejections();
-        this.#onPhaseMaybeChanged();
-        const optIn = this.session.pendingOptIns(this.#cohortId).get(msg.from);
+        this.#drainRejections(ctx);
+        this.#onPhaseMaybeChanged(ctx);
+        const optIn = this.session.pendingOptIns(ctx.cohortId).get(msg.from);
         if (!optIn) return;
         this.emit("opt-in-received", optIn);
         if (optIn.communicationPk) {
@@ -111816,34 +111947,34 @@ ${value2}`;
         }
         const decision = await this.#onOptInReceived(optIn);
         if (!decision.accepted) return;
-        const maxParticipants = this.#config.maxParticipants;
-        const cohortNow = this.session.getCohort(this.#cohortId);
+        const maxParticipants = ctx.config.maxParticipants;
+        const cohortNow = this.session.getCohort(ctx.cohortId);
         if (maxParticipants !== void 0 && cohortNow && cohortNow.participants.length >= maxParticipants) {
           return;
         }
-        await this.#sendAll(this.session.acceptParticipant(this.#cohortId, msg.from));
-        this.emit("participant-accepted", { participantDid: msg.from });
-        const cohort = this.session.getCohort(this.#cohortId);
-        if (cohort.participants.length >= this.#config.minParticipants && !this.#finalizing) {
-          this.#finalizing = true;
+        await this.#sendAll(this.session.acceptParticipant(ctx.cohortId, msg.from));
+        this.emit("participant-accepted", { cohortId: ctx.cohortId, participantDid: msg.from });
+        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: this.#config.minParticipants
+            minRequired: ctx.config.minParticipants
           });
           if (!finalizeDecision.finalize) {
-            this.#finalizing = false;
+            ctx.finalizing = false;
             return;
           }
-          const readyMsgs = this.session.finalizeKeygen(this.#cohortId);
-          this.#stopAdvertRepeating();
+          const readyMsgs = this.session.finalizeKeygen(ctx.cohortId);
+          this.#stopAdvertRepeating(ctx);
           this.emit("keygen-complete", {
-            cohortId: this.#cohortId,
+            cohortId: ctx.cohortId,
             beaconAddress: cohort.beaconAddress
           });
           await this.#sendAll(readyMsgs);
         }
       } catch (err) {
-        this.#fail(err);
+        this.#failCohort(ctx, err);
       }
     }
     /**
@@ -111851,23 +111982,23 @@ ${value2}`;
      * and distributes the data for validation.
      * @param {BaseMessage} msg - The incoming message to handle.
      * @returns {Promise<void>} Resolves when handling is complete.
-     * @throws {Error} If any step of handling fails, the error is emitted and the run promise is rejected.
-     * Note: if the runner has been stopped, handlers will ignore incoming messages.
      */
     async #handleSubmitUpdate(msg) {
       if (this.#stopped) return;
+      const ctx = this.#contextFor(msg);
+      if (!ctx) return;
       try {
         this.session.receive(msg);
-        this.#drainRejections();
-        this.#onPhaseMaybeChanged();
-        this.emit("update-received", { participantDid: msg.from });
-        if (this.session.getCohortPhase(this.#cohortId) === "UpdatesCollected" /* UpdatesCollected */) {
-          const distributeMsgs = this.session.buildAndDistribute(this.#cohortId);
-          this.emit("data-distributed", { cohortId: this.#cohortId });
+        this.#drainRejections(ctx);
+        this.#onPhaseMaybeChanged(ctx);
+        this.emit("update-received", { cohortId: ctx.cohortId, participantDid: msg.from });
+        if (this.session.getCohortPhase(ctx.cohortId) === "UpdatesCollected" /* UpdatesCollected */) {
+          const distributeMsgs = this.session.buildAndDistribute(ctx.cohortId);
+          this.emit("data-distributed", { cohortId: ctx.cohortId });
           await this.#sendAll(distributeMsgs);
         }
       } catch (err) {
-        this.#fail(err);
+        this.#failCohort(ctx, err);
       }
     }
     /**
@@ -111875,111 +112006,95 @@ ${value2}`;
      * automatically requests tx data and starts signing.
      * @param {BaseMessage} msg - The incoming message to handle.
      * @returns {Promise<void>} Resolves when handling is complete.
-     * @throws {Error} If any step of handling fails, the error is emitted and the run promise is rejected.
-     * Note: if the runner has been stopped, handlers will ignore incoming messages.
      */
     async #handleValidationAck(msg) {
       if (this.#stopped) return;
+      const ctx = this.#contextFor(msg);
+      if (!ctx) return;
       try {
         this.session.receive(msg);
-        this.#drainRejections();
-        this.#onPhaseMaybeChanged();
+        this.#drainRejections(ctx);
+        this.#onPhaseMaybeChanged(ctx);
         const approved = !!msg.body?.approved;
-        this.emit("validation-received", { participantDid: msg.from, approved });
-        const phase = this.session.getCohortPhase(this.#cohortId);
+        this.emit("validation-received", { cohortId: ctx.cohortId, participantDid: msg.from, approved });
+        const phase = this.session.getCohortPhase(ctx.cohortId);
         if (phase === "Failed" /* Failed */) {
           const reason = `Validation rejected by participant ${msg.from}`;
-          this.emit("cohort-failed", { cohortId: this.#cohortId, reason });
-          this.#fail(new Error(reason));
+          this.emit("cohort-failed", { cohortId: ctx.cohortId, reason });
+          this.#failCohort(ctx, new Error(reason));
           return;
         }
         if (phase === "Validated" /* Validated */) {
-          const cohort = this.session.getCohort(this.#cohortId);
+          const cohort = this.session.getCohort(ctx.cohortId);
           const txData = await this.#onProvideTxData({
-            cohortId: this.#cohortId,
+            cohortId: ctx.cohortId,
             beaconAddress: cohort.beaconAddress,
             signalBytes: cohort.signalBytes
           });
-          const authMsgs = this.session.startSigning(this.#cohortId, txData);
-          const sessionId = this.session.getSigningSessionId(this.#cohortId) ?? "";
-          this.emit("signing-started", { sessionId });
+          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.#fail(err);
+        this.#failCohort(ctx, err);
       }
     }
     /**
-     * Handler for receiving nonce contributions and signature authorizations. When all nonces or
-     * signatures are received,
+     * 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.
-     * @throws {Error} If any step of handling fails, the error is emitted and the run promise is rejected.
-     * Note: if the runner has been stopped, handlers will ignore incoming messages.
      */
     async #handleNonceContribution(msg) {
       if (this.#stopped) return;
+      const ctx = this.#contextFor(msg);
+      if (!ctx) return;
       try {
         this.session.receive(msg);
-        this.#drainRejections();
-        this.#onPhaseMaybeChanged();
-        this.emit("nonce-received", { participantDid: msg.from });
-        if (this.session.getCohortPhase(this.#cohortId) === "NoncesCollected" /* NoncesCollected */) {
-          await this.#sendAll(this.session.sendAggregatedNonce(this.#cohortId));
+        this.#drainRejections(ctx);
+        this.#onPhaseMaybeChanged(ctx);
+        this.emit("nonce-received", { cohortId: ctx.cohortId, participantDid: msg.from });
+        if (this.session.getCohortPhase(ctx.cohortId) === "NoncesCollected" /* NoncesCollected */) {
+          await this.#sendAll(this.session.sendAggregatedNonce(ctx.cohortId));
         }
       } catch (err) {
-        this.#fail(err);
+        this.#failCohort(ctx, err);
       }
     }
     /**
      * Handler for receiving signature authorizations. When all partial signatures are received, the
-     * session automatically completes and the final result is emitted and the run() promise is resolved.
+     * 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.
-     * @throws {Error} If any step of handling fails, the error is emitted and the run promise is rejected.
-     * Note: if the runner has been stopped, handlers will ignore incoming messages.
      */
     async #handleSignatureAuthorization(msg) {
       if (this.#stopped) return;
+      const ctx = this.#contextFor(msg);
+      if (!ctx) return;
       try {
         this.session.receive(msg);
-        this.#drainRejections();
-        this.#onPhaseMaybeChanged();
-        const result = this.session.getResult(this.#cohortId);
+        this.#drainRejections(ctx);
+        this.#onPhaseMaybeChanged(ctx);
+        const result = this.session.getResult(ctx.cohortId);
         if (result) {
-          this.#clearTimers();
-          this.#unregisterHandlers();
-          this.emit("signing-complete", result);
-          this.#resolveRun?.(result);
+          this.#completeCohort(ctx, result);
         }
       } catch (err) {
-        this.#fail(err);
+        this.#failCohort(ctx, err);
       }
     }
     /**
      * 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.
-     * @throws {Error} If sending any message fails, the error is emitted and the run promise is
-     * rejected.
      */
     async #sendAll(msgs) {
       for (const m2 of msgs) {
         await this.#transport.sendMessage(m2, this.#did, m2.to);
       }
     }
-    /**
-     * Internal: helper to handle errors. Emits an 'error' event and rejects the run promise.
-     * @param {Error} err - The error to handle.
-     */
-    #fail(err) {
-      this.#stopAdvertRepeating();
-      this.#clearTimers();
-      this.#unregisterHandlers();
-      if (this.#cohortId) this.session.removeCohort(this.#cohortId);
-      this.emit("error", err);
-      this.#rejectRun?.(err);
-    }
   };
 
   // src/core/aggregation/runner/participant-runner.ts
@@ -112040,7 +112155,8 @@ ${value2}`;
     }
     /**
      * Single-shot helper: start, join the first cohort that passes `shouldJoin`,
-     * drive it to completion, and resolve. Convenient for tests and demos.
+     * drive it to completion, and resolve. Convenient for tests and demos. The
+     * single-cohort special case of {@link joinMatching} (count = 1).
      */
     static async joinFirst(options2) {
       return new Promise((resolve, reject) => {
@@ -112053,6 +112169,37 @@ ${value2}`;
         runner.start().catch(reject);
       });
     }
+    /**
+     * Multi-cohort helper: start, join EVERY cohort whose advert passes
+     * `shouldJoin`, drive each to completion in parallel, and resolve once
+     * `count` cohorts have completed (the runner stops at that point). The
+     * N-cohort generalization of {@link joinFirst}, for a participant that joins
+     * several cohorts advertised by one service.
+     *
+     * For an open-ended, long-lived subscriber (no fixed count), construct an
+     * {@link AggregationParticipantRunner} directly, set `shouldJoin`, call
+     * `start()`, and listen for `cohort-complete` — the runner already drives
+     * any number of cohorts concurrently.
+     *
+     * @param options Participant runner options (set `shouldJoin` to select cohorts).
+     * @param count Number of completed cohorts to collect before resolving.
+     * @returns The {@link CohortCompleteInfo} for each completed cohort, in completion order.
+     */
+    static async joinMatching(options2, count) {
+      return new Promise((resolve, reject) => {
+        const runner = new _AggregationParticipantRunner(options2);
+        const completed = [];
+        runner.on("cohort-complete", (info) => {
+          completed.push(info);
+          if (completed.length >= count) {
+            runner.stop();
+            resolve(completed);
+          }
+        });
+        runner.on("error", reject);
+        runner.start().catch(reject);
+      });
+    }
     /**
      * Internal: handler registration with the transport. Idempotent and safe to call multiple times,
      * but only registers handlers once.
@@ -112201,7 +112348,7 @@ ${value2}`;
         if (this.session.getCohortPhase(cohortId) === "Complete" /* Complete */) {
           const info = this.session.joinedCohorts.get(cohortId);
           if (info) {
-            const validation = this.session.pendingValidations.get(cohortId);
+            const validation = this.session.getValidation(cohortId);
             this.emit("cohort-complete", {
               cohortId,
               beaconAddress: info.beaconAddress,