@did-btcr2/method 0.35.0 → 0.36.1

package/dist/cjs/index.js

@@ -86,6 +86,7 @@ __export(index_exports, {
   InMemoryRateLimitStore: () => InMemoryRateLimitStore,
   InMemoryTransport: () => InMemoryTransport,
   InboxBuffer: () => InboxBuffer,
+  KNOWN_BEACON_TYPES: () => KNOWN_BEACON_TYPES,
   KeyPairAggregationSigner: () => KeyPairAggregationSigner,
   NONCE_CONTRIBUTION: () => NONCE_CONTRIBUTION,
   NonceCache: () => NonceCache,
@@ -158,6 +159,7 @@ __export(index_exports, {
   registerBeaconStrategy: () => registerBeaconStrategy,
   reviveFromWire: () => reviveFromWire,
   signEnvelope: () => signEnvelope,
+  validateCohortConditions: () => validateCohortConditions,
   verifyEnvelope: () => verifyEnvelope,
   verifyRequestAuth: () => verifyRequestAuth
 });
@@ -301,7 +303,7 @@ var AggregationCohort = class {
   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";
@@ -467,6 +469,56 @@ var AggregationCohort = class {
   }
 };
 
+// src/core/aggregation/conditions.ts
+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(c) {
+  const problems = [];
+  if (!KNOWN_BEACON_TYPES.includes(c.beaconType)) {
+    problems.push(`beaconType must be one of ${KNOWN_BEACON_TYPES.join(", ")}`);
+  }
+  if (!Number.isInteger(c.minParticipants) || c.minParticipants < 1) {
+    problems.push("minParticipants must be an integer >= 1");
+  }
+  if (c.maxParticipants !== void 0) {
+    if (!Number.isInteger(c.maxParticipants) || c.maxParticipants < 1) {
+      problems.push("maxParticipants must be an integer >= 1");
+    } else if (Number.isInteger(c.minParticipants) && c.maxParticipants < c.minParticipants) {
+      problems.push("maxParticipants must be >= minParticipants");
+    }
+  }
+  checkPair(problems, "DidsPerParticipant", c.minDidsPerParticipant, c.maxDidsPerParticipant);
+  checkPair(problems, "SecondsBetweenAnnouncements", c.minSecondsBetweenAnnouncements, c.maxSecondsBetweenAnnouncements);
+  if (c.pendingUpdateTrigger !== void 0 && (!Number.isInteger(c.pendingUpdateTrigger) || c.pendingUpdateTrigger < 1)) {
+    problems.push("pendingUpdateTrigger must be an integer >= 1");
+  }
+  checkCost(problems, "costOfEnrollment", c.costOfEnrollment);
+  checkCost(problems, "costPerAnnouncement", c.costPerAnnouncement);
+  return problems;
+}
+
 // src/core/aggregation/messages/base.ts
 var AGGREGATION_WIRE_VERSION = 1;
 var BaseMessage = class {
@@ -899,6 +951,14 @@ var AggregationService = class {
    * 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,
@@ -931,13 +991,13 @@ var AggregationService = class {
         { cohortId, phase: state.phase }
       );
     }
+    const { network, ...conditions } = state.config;
     const message = 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 [message];
@@ -996,6 +1056,14 @@ var AggregationService = class {
         { 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);
@@ -1029,6 +1097,14 @@ var AggregationService = class {
         { 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 messages = [];
@@ -1347,6 +1423,58 @@ var AggregationService = class {
 var import_common5 = require("@did-btcr2/common");
 var import_utils3 = require("@noble/hashes/utils");
 var import_btc_signer3 = require("@scure/btc-signer");
+
+// src/core/aggregation/messages/bodies.ts
+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(m) {
+  return m.type === COHORT_ADVERT && hasStr(m.body, "cohortId") && hasIntMin(m.body, "minParticipants", 1) && optIntMin(m.body, "maxParticipants", 1) && hasStr(m.body, "beaconType") && hasStr(m.body, "network") && hasBytes(m.body, "communicationPk");
+}
+function isCohortOptInMessage(m) {
+  return m.type === COHORT_OPT_IN && hasStr(m.body, "cohortId") && hasBytes(m.body, "participantPk") && hasBytes(m.body, "communicationPk");
+}
+function isCohortOptInAcceptMessage(m) {
+  return m.type === COHORT_OPT_IN_ACCEPT && hasStr(m.body, "cohortId");
+}
+function isCohortReadyMessage(m) {
+  return m.type === COHORT_READY && hasStr(m.body, "cohortId") && hasStr(m.body, "beaconAddress") && hasBytesArray(m.body, "cohortKeys");
+}
+function isSubmitUpdateMessage(m) {
+  return m.type === SUBMIT_UPDATE && hasStr(m.body, "cohortId") && !!m.body && typeof m.body.signedUpdate === "object";
+}
+function isDistributeAggregatedDataMessage(m) {
+  return m.type === DISTRIBUTE_AGGREGATED_DATA && hasStr(m.body, "cohortId") && hasStr(m.body, "beaconType") && hasStr(m.body, "signalBytesHex");
+}
+function isValidationAckMessage(m) {
+  return m.type === VALIDATION_ACK && hasStr(m.body, "cohortId") && hasBool(m.body, "approved");
+}
+function isAuthorizationRequestMessage(m) {
+  return m.type === AUTHORIZATION_REQUEST && hasStr(m.body, "cohortId") && hasStr(m.body, "sessionId") && hasStr(m.body, "pendingTx") && hasStr(m.body, "prevOutScriptHex") && hasStr(m.body, "prevOutValue");
+}
+function isNonceContributionMessage(m) {
+  return m.type === NONCE_CONTRIBUTION && hasStr(m.body, "cohortId") && hasStr(m.body, "sessionId") && hasBytes(m.body, "nonceContribution");
+}
+function isAggregatedNonceMessage(m) {
+  return m.type === AGGREGATED_NONCE && hasStr(m.body, "cohortId") && hasStr(m.body, "sessionId") && hasBytes(m.body, "aggregatedNonce");
+}
+function isSignatureAuthorizationMessage(m) {
+  return m.type === SIGNATURE_AUTHORIZATION && hasStr(m.body, "cohortId") && hasStr(m.body, "sessionId") && hasBytes(m.body, "partialSignature");
+}
+
+// src/core/aggregation/participant.ts
 var AggregationParticipant = class {
   did;
   /** MuSig2 signing capability. The raw secret never lives as a field here. */
@@ -1404,16 +1532,15 @@ var AggregationParticipant = class {
     return map;
   }
   #handleCohortAdvert(message) {
-    const cohortId = message.body?.cohortId;
-    if (!cohortId) return;
+    if (!isCohortAdvertMessage(message)) return;
+    const { cohortId, network, communicationPk, ...conditions } = message.body;
     if (this.#cohortStates.has(cohortId)) return;
     const advert = {
       cohortId,
       serviceDid: message.from,
-      cohortSize: message.body?.cohortSize ?? 0,
-      network: message.body?.network ?? "",
-      beaconType: message.body?.beaconType ?? "CASBeacon",
-      serviceCommunicationPk: message.body?.communicationPk ?? new Uint8Array()
+      network,
+      serviceCommunicationPk: communicationPk,
+      ...conditions
     };
     this.#cohortStates.set(cohortId, {
       phase: "Discovered" /* Discovered */,
@@ -1438,7 +1565,7 @@ var AggregationParticipant = class {
     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
     });
@@ -1518,6 +1645,17 @@ var AggregationParticipant = class {
     }
     return map;
   }
+  /**
+   * 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(message) {
     const cohortId = message.body?.cohortId;
     if (!cohortId) return;
@@ -1758,49 +1896,6 @@ var SILENT_LOGGER = {
   }
 };
 
-// src/core/aggregation/messages/bodies.ts
-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(m) {
-  return m.type === COHORT_ADVERT && hasStr(m.body, "cohortId") && hasNum(m.body, "cohortSize") && hasStr(m.body, "beaconType") && hasStr(m.body, "network") && hasBytes(m.body, "communicationPk");
-}
-function isCohortOptInMessage(m) {
-  return m.type === COHORT_OPT_IN && hasStr(m.body, "cohortId") && hasBytes(m.body, "participantPk") && hasBytes(m.body, "communicationPk");
-}
-function isCohortOptInAcceptMessage(m) {
-  return m.type === COHORT_OPT_IN_ACCEPT && hasStr(m.body, "cohortId");
-}
-function isCohortReadyMessage(m) {
-  return m.type === COHORT_READY && hasStr(m.body, "cohortId") && hasStr(m.body, "beaconAddress") && hasBytesArray(m.body, "cohortKeys");
-}
-function isSubmitUpdateMessage(m) {
-  return m.type === SUBMIT_UPDATE && hasStr(m.body, "cohortId") && !!m.body && typeof m.body.signedUpdate === "object";
-}
-function isDistributeAggregatedDataMessage(m) {
-  return m.type === DISTRIBUTE_AGGREGATED_DATA && hasStr(m.body, "cohortId") && hasStr(m.body, "beaconType") && hasStr(m.body, "signalBytesHex");
-}
-function isValidationAckMessage(m) {
-  return m.type === VALIDATION_ACK && hasStr(m.body, "cohortId") && hasBool(m.body, "approved");
-}
-function isAuthorizationRequestMessage(m) {
-  return m.type === AUTHORIZATION_REQUEST && hasStr(m.body, "cohortId") && hasStr(m.body, "sessionId") && hasStr(m.body, "pendingTx") && hasStr(m.body, "prevOutScriptHex") && hasStr(m.body, "prevOutValue");
-}
-function isNonceContributionMessage(m) {
-  return m.type === NONCE_CONTRIBUTION && hasStr(m.body, "cohortId") && hasStr(m.body, "sessionId") && hasBytes(m.body, "nonceContribution");
-}
-function isAggregatedNonceMessage(m) {
-  return m.type === AGGREGATED_NONCE && hasStr(m.body, "cohortId") && hasStr(m.body, "sessionId") && hasBytes(m.body, "aggregatedNonce");
-}
-function isSignatureAuthorizationMessage(m) {
-  return m.type === SIGNATURE_AUTHORIZATION && hasStr(m.body, "cohortId") && hasStr(m.body, "sessionId") && hasBytes(m.body, "partialSignature");
-}
-
 // src/core/aggregation/messages/guards.ts
 var KEYGEN_VALUES = /* @__PURE__ */ new Set([
   COHORT_ADVERT,
@@ -3933,35 +4028,22 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
   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(options) {
     super();
     this.#transport = options.transport;
     this.#did = options.did;
-    this.#config = options.config;
+    this.#defaultConfig = options.config;
     this.#onOptInReceived = options.onOptInReceived ?? (async () => ({ accepted: true }));
     this.#onReadyToFinalize = options.onReadyToFinalize ?? (async ({ acceptedCount, minRequired }) => ({
       finalize: acceptedCount >= minRequired
@@ -3979,55 +4061,126 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
       maxUpdateSizeBytes: options.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 r of this.session.drainRejections(this.#cohortId)) {
-      this.emit("message-rejected", { cohortId: this.#cohortId, ...r });
+  #drainRejections(ctx) {
+    for (const r of this.session.drainRejections(ctx.cohortId)) {
+      this.emit("message-rejected", { cohortId: ctx.cohortId, ...r });
     }
   }
   /**
-   * 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((c) => c.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 stop of stops) {
         try {
           stop();
@@ -4036,61 +4189,118 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
       }
     };
   }
-  /** Stop the advert republish loop. Idempotent. */
-  #stopAdvertRepeating() {
-    if (!this.#stopAdvertRepeat) return;
-    const stop = this.#stopAdvertRepeat;
-    this.#stopAdvertRepeat = void 0;
+  /** Stop a cohort's advert republish loop. Idempotent. */
+  #stopAdvertRepeating(ctx) {
+    if (!ctx.stopAdvertRepeat) return;
+    const stop = ctx.stopAdvertRepeat;
+    ctx.stopAdvertRepeat = void 0;
     stop();
   }
-  /** 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 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);
   }
-  /** 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;
+  /**
+   * 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 = [
@@ -4101,7 +4311,10 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
     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;
@@ -4122,23 +4335,25 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
   }
   /**
    * 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) {
@@ -4146,29 +4361,34 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
       }
       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);
     }
   }
   /**
@@ -4176,23 +4396,23 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
    * 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);
     }
   }
   /**
@@ -4200,111 +4420,95 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
    * 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 m of msgs) {
       await this.#transport.sendMessage(m, this.#did, m.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
@@ -4364,7 +4568,8 @@ var AggregationParticipantRunner = class _AggregationParticipantRunner extends T
   }
   /**
    * 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(options) {
     return new Promise((resolve, reject) => {
@@ -4377,6 +4582,37 @@ var AggregationParticipantRunner = class _AggregationParticipantRunner extends T
       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(options, count) {
+    return new Promise((resolve, reject) => {
+      const runner = new _AggregationParticipantRunner(options);
+      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.
@@ -4525,7 +4761,7 @@ var AggregationParticipantRunner = class _AggregationParticipantRunner extends T
       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,
@@ -7826,6 +8062,7 @@ var DidDocumentBuilder = class {
   InMemoryRateLimitStore,
   InMemoryTransport,
   InboxBuffer,
+  KNOWN_BEACON_TYPES,
   KeyPairAggregationSigner,
   NONCE_CONTRIBUTION,
   NonceCache,
@@ -7898,6 +8135,7 @@ var DidDocumentBuilder = class {
   registerBeaconStrategy,
   reviveFromWire,
   signEnvelope,
+  validateCohortConditions,
   verifyEnvelope,
   verifyRequestAuth
 });