@did-btcr2/method 0.35.0 → 0.36.1

package/dist/browser.js

@@ -93203,6 +93203,7 @@ a=end-of-candidates
     InMemoryRateLimitStore: () => InMemoryRateLimitStore,
     InMemoryTransport: () => InMemoryTransport,
     InboxBuffer: () => InboxBuffer,
+    KNOWN_BEACON_TYPES: () => KNOWN_BEACON_TYPES,
     KeyPairAggregationSigner: () => KeyPairAggregationSigner,
     NONCE_CONTRIBUTION: () => NONCE_CONTRIBUTION,
     NonceCache: () => NonceCache,
@@ -93275,6 +93276,7 @@ a=end-of-candidates
     registerBeaconStrategy: () => registerBeaconStrategy,
     reviveFromWire: () => reviveFromWire,
     signEnvelope: () => signEnvelope,
+    validateCohortConditions: () => validateCohortConditions,
     verifyEnvelope: () => verifyEnvelope,
     verifyRequestAuth: () => verifyRequestAuth
   });
@@ -103381,7 +103383,7 @@ a=end-of-candidates
     validationRejections = /* @__PURE__ */ new Set();
     constructor({ id, minParticipants, serviceDid, network, beaconType }) {
       this.id = id || crypto.randomUUID();
-      this.minParticipants = minParticipants || 2;
+      this.minParticipants = minParticipants ?? 2;
       this.serviceDid = serviceDid || "";
       this.network = network;
       this.beaconType = beaconType || "CASBeacon";
@@ -103547,6 +103549,57 @@ a=end-of-candidates
     }
   };
 
+  // src/core/aggregation/conditions.ts
+  init_shim();
+  var KNOWN_BEACON_TYPES = ["CASBeacon", "SMTBeacon"];
+  function checkPair(problems, label, min, max) {
+    if (min !== void 0 && (!Number.isInteger(min) || min < 0)) {
+      problems.push(`min${label} must be an integer >= 0`);
+    }
+    if (max !== void 0 && (!Number.isInteger(max) || max < 0)) {
+      problems.push(`max${label} must be an integer >= 0`);
+    }
+    if (min !== void 0 && max !== void 0 && Number.isInteger(min) && Number.isInteger(max) && max < min) {
+      problems.push(`max${label} must be >= min${label}`);
+    }
+  }
+  function checkCost(problems, label, cost) {
+    if (cost === void 0) return;
+    if (typeof cost.amount !== "number" || !Number.isFinite(cost.amount) || cost.amount < 0) {
+      problems.push(`${label}.amount must be a finite number >= 0`);
+    }
+    if (typeof cost.unit !== "string" || cost.unit.length === 0) {
+      problems.push(`${label}.unit must be a non-empty string`);
+    }
+    if (cost.basis !== void 0 && cost.basis !== "per-did" && cost.basis !== "per-participant") {
+      problems.push(`${label}.basis must be 'per-did' or 'per-participant'`);
+    }
+  }
+  function validateCohortConditions(c2) {
+    const problems = [];
+    if (!KNOWN_BEACON_TYPES.includes(c2.beaconType)) {
+      problems.push(`beaconType must be one of ${KNOWN_BEACON_TYPES.join(", ")}`);
+    }
+    if (!Number.isInteger(c2.minParticipants) || c2.minParticipants < 1) {
+      problems.push("minParticipants must be an integer >= 1");
+    }
+    if (c2.maxParticipants !== void 0) {
+      if (!Number.isInteger(c2.maxParticipants) || c2.maxParticipants < 1) {
+        problems.push("maxParticipants must be an integer >= 1");
+      } else if (Number.isInteger(c2.minParticipants) && c2.maxParticipants < c2.minParticipants) {
+        problems.push("maxParticipants must be >= minParticipants");
+      }
+    }
+    checkPair(problems, "DidsPerParticipant", c2.minDidsPerParticipant, c2.maxDidsPerParticipant);
+    checkPair(problems, "SecondsBetweenAnnouncements", c2.minSecondsBetweenAnnouncements, c2.maxSecondsBetweenAnnouncements);
+    if (c2.pendingUpdateTrigger !== void 0 && (!Number.isInteger(c2.pendingUpdateTrigger) || c2.pendingUpdateTrigger < 1)) {
+      problems.push("pendingUpdateTrigger must be an integer >= 1");
+    }
+    checkCost(problems, "costOfEnrollment", c2.costOfEnrollment);
+    checkCost(problems, "costPerAnnouncement", c2.costPerAnnouncement);
+    return problems;
+  }
+
   // src/core/aggregation/messages/base.ts
   init_shim();
   var AGGREGATION_WIRE_VERSION = 1;
@@ -103981,6 +104034,14 @@ a=end-of-candidates
      * Cohort starts in `Created` phase — call `advertise()` to broadcast.
      */
     createCohort(config) {
+      const problems = validateCohortConditions(config);
+      if (problems.length > 0) {
+        throw new AggregationServiceError(
+          `Invalid cohort conditions: ${problems.join("; ")}`,
+          "INVALID_COHORT_CONDITIONS",
+          { problems }
+        );
+      }
       const cohort = new AggregationCohort({
         serviceDid: this.did,
         minParticipants: config.minParticipants,
@@ -104013,13 +104074,13 @@ a=end-of-candidates
           { cohortId, phase: state.phase }
         );
       }
+      const { network, ...conditions } = state.config;
       const message2 = createCohortAdvertMessage({
         from: this.did,
         cohortId,
-        cohortSize: state.config.minParticipants,
-        beaconType: state.config.beaconType,
-        network: state.config.network,
-        communicationPk: this.publicKey.compressed
+        network,
+        communicationPk: this.publicKey.compressed,
+        ...conditions
       });
       state.phase = "Advertised" /* Advertised */;
       return [message2];
@@ -104078,6 +104139,14 @@ a=end-of-candidates
           { cohortId, participantDid }
         );
       }
+      const maxParticipants = state.config.maxParticipants;
+      if (maxParticipants !== void 0 && state.acceptedParticipants.size >= maxParticipants) {
+        throw new AggregationServiceError(
+          `Cohort ${cohortId} is full: ${maxParticipants} participants already accepted.`,
+          "COHORT_FULL",
+          { cohortId, maxParticipants }
+        );
+      }
       state.acceptedParticipants.add(participantDid);
       state.cohort.participants.push(participantDid);
       state.cohort.participantKeys.set(participantDid, optIn.participantPk);
@@ -104111,6 +104180,14 @@ a=end-of-candidates
           { cohortId }
         );
       }
+      const maxParticipants = state.config.maxParticipants;
+      if (maxParticipants !== void 0 && state.acceptedParticipants.size > maxParticipants) {
+        throw new AggregationServiceError(
+          `Cohort ${cohortId} has ${state.acceptedParticipants.size} accepted participants, exceeds max ${maxParticipants}.`,
+          "TOO_MANY_PARTICIPANTS",
+          { cohortId, maxParticipants }
+        );
+      }
       const beaconAddress = state.cohort.computeBeaconAddress();
       state.phase = "CohortSet" /* CohortSet */;
       const messages2 = [];
@@ -104428,6 +104505,59 @@ a=end-of-candidates
   // src/core/aggregation/participant.ts
   init_shim();
   init_utils();
+
+  // src/core/aggregation/messages/bodies.ts
+  init_shim();
+  var hasStr = (b, k) => !!b && typeof b[k] === "string";
+  var hasIntMin = (b, k, min) => {
+    const v = b ? b[k] : void 0;
+    return typeof v === "number" && Number.isInteger(v) && v >= min;
+  };
+  var optIntMin = (b, k, min) => {
+    const v = b ? b[k] : void 0;
+    return v === void 0 || typeof v === "number" && Number.isInteger(v) && v >= min;
+  };
+  var hasBool = (b, k) => !!b && typeof b[k] === "boolean";
+  var hasBytes = (b, k) => !!b && b[k] instanceof Uint8Array;
+  var hasBytesArray = (b, k) => {
+    const v = b ? b[k] : void 0;
+    return Array.isArray(v) && v.every((x) => x instanceof Uint8Array);
+  };
+  function isCohortAdvertMessage(m2) {
+    return m2.type === COHORT_ADVERT && hasStr(m2.body, "cohortId") && hasIntMin(m2.body, "minParticipants", 1) && optIntMin(m2.body, "maxParticipants", 1) && hasStr(m2.body, "beaconType") && hasStr(m2.body, "network") && hasBytes(m2.body, "communicationPk");
+  }
+  function isCohortOptInMessage(m2) {
+    return m2.type === COHORT_OPT_IN && hasStr(m2.body, "cohortId") && hasBytes(m2.body, "participantPk") && hasBytes(m2.body, "communicationPk");
+  }
+  function isCohortOptInAcceptMessage(m2) {
+    return m2.type === COHORT_OPT_IN_ACCEPT && hasStr(m2.body, "cohortId");
+  }
+  function isCohortReadyMessage(m2) {
+    return m2.type === COHORT_READY && hasStr(m2.body, "cohortId") && hasStr(m2.body, "beaconAddress") && hasBytesArray(m2.body, "cohortKeys");
+  }
+  function isSubmitUpdateMessage(m2) {
+    return m2.type === SUBMIT_UPDATE && hasStr(m2.body, "cohortId") && !!m2.body && typeof m2.body.signedUpdate === "object";
+  }
+  function isDistributeAggregatedDataMessage(m2) {
+    return m2.type === DISTRIBUTE_AGGREGATED_DATA && hasStr(m2.body, "cohortId") && hasStr(m2.body, "beaconType") && hasStr(m2.body, "signalBytesHex");
+  }
+  function isValidationAckMessage(m2) {
+    return m2.type === VALIDATION_ACK && hasStr(m2.body, "cohortId") && hasBool(m2.body, "approved");
+  }
+  function isAuthorizationRequestMessage(m2) {
+    return m2.type === AUTHORIZATION_REQUEST && hasStr(m2.body, "cohortId") && hasStr(m2.body, "sessionId") && hasStr(m2.body, "pendingTx") && hasStr(m2.body, "prevOutScriptHex") && hasStr(m2.body, "prevOutValue");
+  }
+  function isNonceContributionMessage(m2) {
+    return m2.type === NONCE_CONTRIBUTION && hasStr(m2.body, "cohortId") && hasStr(m2.body, "sessionId") && hasBytes(m2.body, "nonceContribution");
+  }
+  function isAggregatedNonceMessage(m2) {
+    return m2.type === AGGREGATED_NONCE && hasStr(m2.body, "cohortId") && hasStr(m2.body, "sessionId") && hasBytes(m2.body, "aggregatedNonce");
+  }
+  function isSignatureAuthorizationMessage(m2) {
+    return m2.type === SIGNATURE_AUTHORIZATION && hasStr(m2.body, "cohortId") && hasStr(m2.body, "sessionId") && hasBytes(m2.body, "partialSignature");
+  }
+
+  // src/core/aggregation/participant.ts
   var AggregationParticipant = class {
     did;
     /** MuSig2 signing capability. The raw secret never lives as a field here. */
@@ -104485,16 +104615,15 @@ a=end-of-candidates
       return map3;
     }
     #handleCohortAdvert(message2) {
-      const cohortId = message2.body?.cohortId;
-      if (!cohortId) return;
+      if (!isCohortAdvertMessage(message2)) return;
+      const { cohortId, network, communicationPk, ...conditions } = message2.body;
       if (this.#cohortStates.has(cohortId)) return;
       const advert = {
         cohortId,
         serviceDid: message2.from,
-        cohortSize: message2.body?.cohortSize ?? 0,
-        network: message2.body?.network ?? "",
-        beaconType: message2.body?.beaconType ?? "CASBeacon",
-        serviceCommunicationPk: message2.body?.communicationPk ?? new Uint8Array()
+        network,
+        serviceCommunicationPk: communicationPk,
+        ...conditions
       };
       this.#cohortStates.set(cohortId, {
         phase: "Discovered" /* Discovered */,
@@ -104519,7 +104648,7 @@ a=end-of-candidates
       const cohort = new AggregationCohort({
         id: cohortId,
         serviceDid: state.serviceDid,
-        minParticipants: state.advert.cohortSize,
+        minParticipants: state.advert.minParticipants,
         network: state.advert.network,
         beaconType: state.advert.beaconType
       });
@@ -104598,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;
@@ -104842,50 +104982,6 @@ a=end-of-candidates
   // src/core/aggregation/messages/index.ts
   init_shim();
 
-  // src/core/aggregation/messages/bodies.ts
-  init_shim();
-  var hasStr = (b, k) => !!b && typeof b[k] === "string";
-  var hasNum = (b, k) => !!b && typeof b[k] === "number";
-  var hasBool = (b, k) => !!b && typeof b[k] === "boolean";
-  var hasBytes = (b, k) => !!b && b[k] instanceof Uint8Array;
-  var hasBytesArray = (b, k) => {
-    const v = b ? b[k] : void 0;
-    return Array.isArray(v) && v.every((x) => x instanceof Uint8Array);
-  };
-  function isCohortAdvertMessage(m2) {
-    return m2.type === COHORT_ADVERT && hasStr(m2.body, "cohortId") && hasNum(m2.body, "cohortSize") && hasStr(m2.body, "beaconType") && hasStr(m2.body, "network") && hasBytes(m2.body, "communicationPk");
-  }
-  function isCohortOptInMessage(m2) {
-    return m2.type === COHORT_OPT_IN && hasStr(m2.body, "cohortId") && hasBytes(m2.body, "participantPk") && hasBytes(m2.body, "communicationPk");
-  }
-  function isCohortOptInAcceptMessage(m2) {
-    return m2.type === COHORT_OPT_IN_ACCEPT && hasStr(m2.body, "cohortId");
-  }
-  function isCohortReadyMessage(m2) {
-    return m2.type === COHORT_READY && hasStr(m2.body, "cohortId") && hasStr(m2.body, "beaconAddress") && hasBytesArray(m2.body, "cohortKeys");
-  }
-  function isSubmitUpdateMessage(m2) {
-    return m2.type === SUBMIT_UPDATE && hasStr(m2.body, "cohortId") && !!m2.body && typeof m2.body.signedUpdate === "object";
-  }
-  function isDistributeAggregatedDataMessage(m2) {
-    return m2.type === DISTRIBUTE_AGGREGATED_DATA && hasStr(m2.body, "cohortId") && hasStr(m2.body, "beaconType") && hasStr(m2.body, "signalBytesHex");
-  }
-  function isValidationAckMessage(m2) {
-    return m2.type === VALIDATION_ACK && hasStr(m2.body, "cohortId") && hasBool(m2.body, "approved");
-  }
-  function isAuthorizationRequestMessage(m2) {
-    return m2.type === AUTHORIZATION_REQUEST && hasStr(m2.body, "cohortId") && hasStr(m2.body, "sessionId") && hasStr(m2.body, "pendingTx") && hasStr(m2.body, "prevOutScriptHex") && hasStr(m2.body, "prevOutValue");
-  }
-  function isNonceContributionMessage(m2) {
-    return m2.type === NONCE_CONTRIBUTION && hasStr(m2.body, "cohortId") && hasStr(m2.body, "sessionId") && hasBytes(m2.body, "nonceContribution");
-  }
-  function isAggregatedNonceMessage(m2) {
-    return m2.type === AGGREGATED_NONCE && hasStr(m2.body, "cohortId") && hasStr(m2.body, "sessionId") && hasBytes(m2.body, "aggregatedNonce");
-  }
-  function isSignatureAuthorizationMessage(m2) {
-    return m2.type === SIGNATURE_AUTHORIZATION && hasStr(m2.body, "cohortId") && hasStr(m2.body, "sessionId") && hasBytes(m2.body, "partialSignature");
-  }
-
   // src/core/aggregation/messages/guards.ts
   init_shim();
   var KEYGEN_VALUES = /* @__PURE__ */ new Set([
@@ -111518,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
@@ -111564,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();
@@ -111621,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 = [
@@ -111686,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;
@@ -111707,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) {
@@ -111731,29 +111947,34 @@ ${value2}`;
         }
         const decision = await this.#onOptInReceived(optIn);
         if (!decision.accepted) 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;
+        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(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);
       }
     }
     /**
@@ -111761,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);
       }
     }
     /**
@@ -111785,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
@@ -111950,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) => {
@@ -111963,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.
@@ -112111,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,