@did-btcr2/method 0.36.0 → 0.37.0

package/dist/browser.js

@@ -93180,9 +93180,11 @@ a=end-of-candidates
     DEFAULT_ADVERT_REPEAT_INTERVAL_MS: () => DEFAULT_ADVERT_REPEAT_INTERVAL_MS,
     DEFAULT_BROADCAST_LOOKBACK_MS: () => DEFAULT_BROADCAST_LOOKBACK_MS,
     DEFAULT_CLOCK_SKEW_SEC: () => DEFAULT_CLOCK_SKEW_SEC,
+    DEFAULT_FUNDING_MODEL: () => DEFAULT_FUNDING_MODEL,
     DEFAULT_MAX_UPDATE_SIZE_BYTES: () => DEFAULT_MAX_UPDATE_SIZE_BYTES,
     DEFAULT_NONCE_LEN_BYTES: () => DEFAULT_NONCE_LEN_BYTES,
     DEFAULT_NOSTR_RELAYS: () => DEFAULT_NOSTR_RELAYS,
+    DEFAULT_RECOVERY_SEQUENCE: () => DEFAULT_RECOVERY_SEQUENCE,
     DID_REGEX: () => DID_REGEX,
     DISTRIBUTE_AGGREGATED_DATA: () => DISTRIBUTE_AGGREGATED_DATA,
     DidBtcr2: () => DidBtcr2,
@@ -93191,6 +93193,8 @@ a=end-of-candidates
     DidDocumentBuilder: () => DidDocumentBuilder,
     DidVerificationMethod: () => DidVerificationMethod,
     Document: () => Document,
+    FALLBACK_AUTHORIZATION_REQUEST: () => FALLBACK_AUTHORIZATION_REQUEST,
+    FALLBACK_SIGNATURE: () => FALLBACK_SIGNATURE,
     GenesisDocument: () => GenesisDocument,
     HTTP_ENVELOPE_VERSION: () => HTTP_ENVELOPE_VERSION,
     HTTP_ROUTE: () => HTTP_ROUTE,
@@ -93204,7 +93208,9 @@ a=end-of-candidates
     InMemoryTransport: () => InMemoryTransport,
     InboxBuffer: () => InboxBuffer,
     KNOWN_BEACON_TYPES: () => KNOWN_BEACON_TYPES,
+    KNOWN_FUNDING_MODELS: () => KNOWN_FUNDING_MODELS,
     KeyPairAggregationSigner: () => KeyPairAggregationSigner,
+    MAX_RECOVERY_SEQUENCE: () => MAX_RECOVERY_SEQUENCE,
     NONCE_CONTRIBUTION: () => NONCE_CONTRIBUTION,
     NonceCache: () => NonceCache,
     NostrTransport: () => NostrTransport,
@@ -93221,6 +93227,7 @@ a=end-of-candidates
     SMTBeacon: () => SMTBeacon,
     SMTBeaconError: () => SMTBeaconError,
     SSE_EVENT: () => SSE_EVENT,
+    SUBMIT_NONINCLUDED: () => SUBMIT_NONINCLUDED,
     SUBMIT_UPDATE: () => SUBMIT_UPDATE,
     ServiceCohortPhase: () => ServiceCohortPhase,
     SigningSessionError: () => SigningSessionError,
@@ -93229,6 +93236,7 @@ a=end-of-candidates
     SingletonBeacon: () => SingletonBeacon,
     SingletonBeaconError: () => SingletonBeaconError,
     StaticFeeEstimator: () => StaticFeeEstimator,
+    TAPROOT_LEAF_VERSION: () => TAPROOT_LEAF_VERSION,
     TransportAdapterError: () => TransportAdapterError,
     TransportError: () => TransportError,
     TransportFactory: () => TransportFactory,
@@ -93236,6 +93244,11 @@ a=end-of-candidates
     Updater: () => Updater,
     VALIDATION_ACK: () => VALIDATION_ACK,
     buildAggregationBeaconTx: () => buildAggregationBeaconTx,
+    buildFallbackLeaf: () => buildFallbackLeaf,
+    buildFallbackSpend: () => buildFallbackSpend,
+    buildRecoveryLeaves: () => buildRecoveryLeaves,
+    buildRecoveryScript: () => buildRecoveryScript,
+    buildRecoverySpend: () => buildRecoverySpend,
     buildRequestAuth: () => buildRequestAuth,
     createAggregatedNonceMessage: () => createAggregatedNonceMessage,
     createAuthorizationRequestMessage: () => createAuthorizationRequestMessage,
@@ -93244,13 +93257,17 @@ a=end-of-candidates
     createCohortOptInMessage: () => createCohortOptInMessage,
     createCohortReadyMessage: () => createCohortReadyMessage,
     createDistributeAggregatedDataMessage: () => createDistributeAggregatedDataMessage,
+    createFallbackAuthorizationRequestMessage: () => createFallbackAuthorizationRequestMessage,
+    createFallbackSignatureMessage: () => createFallbackSignatureMessage,
     createNonceContributionMessage: () => createNonceContributionMessage,
     createSignatureAuthorizationMessage: () => createSignatureAuthorizationMessage,
+    createSubmitNonIncludedMessage: () => createSubmitNonIncludedMessage,
     createSubmitUpdateMessage: () => createSubmitUpdateMessage,
     createValidationAckMessage: () => createValidationAckMessage,
     defaultReconnectBackoff: () => defaultReconnectBackoff,
     deriveSingletonAddress: () => deriveSingletonAddress,
     detectSingletonScriptKind: () => detectSingletonScriptKind,
+    fallbackSighash: () => fallbackSighash,
     formatSseComment: () => formatSseComment,
     formatSseEvent: () => formatSseEvent,
     getBeaconStrategy: () => getBeaconStrategy,
@@ -93262,10 +93279,13 @@ a=end-of-candidates
     isCohortOptInMessage: () => isCohortOptInMessage,
     isCohortReadyMessage: () => isCohortReadyMessage,
     isDistributeAggregatedDataMessage: () => isDistributeAggregatedDataMessage,
+    isFallbackAuthorizationRequestMessage: () => isFallbackAuthorizationRequestMessage,
+    isFallbackSignatureMessage: () => isFallbackSignatureMessage,
     isKeygenMessageType: () => isKeygenMessageType,
     isNonceContributionMessage: () => isNonceContributionMessage,
     isSignMessageType: () => isSignMessageType,
     isSignatureAuthorizationMessage: () => isSignatureAuthorizationMessage,
+    isSubmitNonIncludedMessage: () => isSubmitNonIncludedMessage,
     isSubmitUpdateMessage: () => isSubmitUpdateMessage,
     isUpdateMessageType: () => isUpdateMessageType,
     isValidationAckMessage: () => isValidationAckMessage,
@@ -93274,8 +93294,10 @@ a=end-of-candidates
     parseRequestAuth: () => parseRequestAuth,
     parseSseStream: () => parseSseStream,
     registerBeaconStrategy: () => registerBeaconStrategy,
+    resolveFallbackThreshold: () => resolveFallbackThreshold,
     reviveFromWire: () => reviveFromWire,
     signEnvelope: () => signEnvelope,
+    tapLeafHash: () => tapLeafHash2,
     validateCohortConditions: () => validateCohortConditions,
     verifyEnvelope: () => verifyEnvelope,
     verifyRequestAuth: () => verifyRequestAuth
@@ -100261,7 +100283,7 @@ a=end-of-candidates
      * @readonly
      * Get signing ability of the Multikey: true if a local Secp256k1SecretKey
      * is present (note: the SchnorrKeyPair.secretKey getter throws when absent;
-     * that throw is the historical error contract — see multikey tests) or if
+     * that throw is the historical error contract - see multikey tests) or if
      * an external signer is available.
      */
     get signer() {
@@ -100366,6 +100388,7 @@ a=end-of-candidates
   init_shim();
 
   // src/core/aggregation/service.ts
+  init_secp256k1();
   init_utils();
 
   // src/core/aggregation/beacon-strategy.ts
@@ -100666,9 +100689,12 @@ a=end-of-candidates
     getDistributePayload(cohort) {
       return { casAnnouncement: cohort.casAnnouncement };
     },
-    validateParticipantView({ participantDid, expectedHash, body }) {
+    validateParticipantView({ participantDid, included, expectedHash, body }) {
       const casAnnouncement = body.casAnnouncement;
       if (!casAnnouncement) return { matches: false };
+      if (!included) {
+        return { matches: !(participantDid in casAnnouncement), casAnnouncement };
+      }
       return {
         matches: casAnnouncement[participantDid] === expectedHash,
         casAnnouncement
@@ -100684,15 +100710,20 @@ a=end-of-candidates
       const proof = cohort.smtProofs?.get(participantDid);
       return { smtProof: proof };
     },
-    validateParticipantView({ participantDid, submittedUpdate, body }) {
+    validateParticipantView({ participantDid, included, submittedUpdate, body }) {
       const smtProof = body.smtProof;
-      if (!smtProof?.updateId || !smtProof?.nonce) return { matches: false };
+      const index = didToIndex(participantDid);
+      if (!included) {
+        if (!smtProof?.nonce || smtProof?.updateId) return { matches: false, smtProof };
+        const candidateHash2 = blockHash(blockHash(base64UrlToHash(smtProof.nonce)));
+        return { matches: verifySerializedProof(smtProof, index, candidateHash2), smtProof };
+      }
+      if (!smtProof?.updateId || !smtProof?.nonce || !submittedUpdate) return { matches: false, smtProof };
       const canonicalBytes = new TextEncoder().encode(canonicalize2(submittedUpdate));
       const expectedUpdateId = hashToBase64Url(blockHash(canonicalBytes));
       if (smtProof.updateId !== expectedUpdateId) {
         return { matches: false, smtProof };
       }
-      const index = didToIndex(participantDid);
       const candidateHash = blockHash(blockHash(base64UrlToHash(smtProof.nonce)), base64UrlToHash(smtProof.updateId));
       return {
         matches: verifySerializedProof(smtProof, index, candidateHash),
@@ -101691,6 +101722,15 @@ a=end-of-candidates
         checkWSH(r2, witnessScript);
     }
   }
+  function uniqPubkey(pubkeys) {
+    const map3 = {};
+    for (const pub of pubkeys) {
+      const key = hex.encode(pub);
+      if (map3[key])
+        throw new Error(`Multisig: non-uniq pubkey: ${pubkeys.map(hex.encode)}`);
+      map3[key] = true;
+    }
+  }
   var p2pkh = (publicKey2, network = NETWORK) => {
     if (!isValidPubkey(publicKey2, PubT.ecdsa))
       throw new Error("P2PKH: invalid publicKey");
@@ -101863,6 +101903,14 @@ a=end-of-candidates
       };
     }
   }
+  function p2tr_ms(m2, pubkeys, allowSamePubkeys = false) {
+    if (!allowSamePubkeys)
+      uniqPubkey(pubkeys);
+    return {
+      type: "tr_ms",
+      script: OutScript.encode({ type: "tr_ms", pubkeys, m: m2 })
+    };
+  }
   var base58check = createBase58check(sha256);
   function validateWitness(version3, data) {
     if (data.length < 2 || data.length > 40)
@@ -103338,6 +103386,104 @@ a=end-of-candidates
     }
   };
 
+  // src/core/aggregation/recovery-policy.ts
+  init_shim();
+  init_secp256k1();
+  init_utils();
+  var DEFAULT_FUNDING_MODEL = "operator-funded";
+  var DEFAULT_RECOVERY_SEQUENCE = 144;
+  var MAX_RECOVERY_SEQUENCE = 65535;
+  var TAPROOT_LEAF_VERSION = 192;
+  function compactSize(n2) {
+    if (n2 < 253) return new Uint8Array([n2]);
+    if (n2 <= 65535) return new Uint8Array([253, n2 & 255, n2 >> 8 & 255]);
+    return new Uint8Array([254, n2 & 255, n2 >> 8 & 255, n2 >> 16 & 255, n2 >> 24 & 255]);
+  }
+  function tapLeafHash2(script, leafVersion = TAPROOT_LEAF_VERSION) {
+    return schnorr2.utils.taggedHash(
+      "TapLeaf",
+      concatBytes(new Uint8Array([leafVersion]), compactSize(script.length), script)
+    );
+  }
+  function resolveFallbackThreshold(advertised, n2) {
+    return advertised ?? Math.max(1, n2 - 1);
+  }
+  function assertFallbackParams({ cohortKeys, fallbackThreshold }) {
+    const n2 = cohortKeys.length;
+    if (n2 === 0) {
+      throw new AggregationCohortError(
+        "Cannot build fallback leaf: no cohort keys.",
+        "NO_COHORT_KEYS"
+      );
+    }
+    for (const key of cohortKeys) {
+      if (key.length !== 33) {
+        throw new AggregationCohortError(
+          `Cohort key must be a 33-byte compressed public key, got ${key.length} bytes.`,
+          "INVALID_COHORT_KEY",
+          { length: key.length }
+        );
+      }
+    }
+    if (!Number.isInteger(fallbackThreshold) || fallbackThreshold < 1 || fallbackThreshold > n2) {
+      throw new AggregationCohortError(
+        `Fallback threshold must be an integer in [1, ${n2}] (k-of-n), got ${fallbackThreshold}.`,
+        "INVALID_FALLBACK_THRESHOLD",
+        { fallbackThreshold, n: n2 }
+      );
+    }
+  }
+  function buildFallbackLeaf(params) {
+    assertFallbackParams(params);
+    const xOnlyKeys = sortKeys(params.cohortKeys).map((k) => k.slice(1));
+    return p2tr_ms(params.fallbackThreshold, xOnlyKeys).script;
+  }
+  function assertRecoveryParams({ recoveryKey, recoverySequence }) {
+    if (recoveryKey.length !== 32) {
+      throw new AggregationCohortError(
+        `Recovery key must be a 32-byte x-only public key, got ${recoveryKey.length} bytes.`,
+        "INVALID_RECOVERY_KEY"
+      );
+    }
+    if (!Number.isInteger(recoverySequence) || recoverySequence < 1 || recoverySequence > MAX_RECOVERY_SEQUENCE) {
+      throw new AggregationCohortError(
+        `Recovery sequence must be a block-based BIP-68 relative timelock in [1, ${MAX_RECOVERY_SEQUENCE}], got ${recoverySequence}.`,
+        "INVALID_RECOVERY_SEQUENCE"
+      );
+    }
+  }
+  function buildRecoveryScript(params) {
+    assertRecoveryParams(params);
+    return Script.encode([
+      params.recoverySequence,
+      "CHECKSEQUENCEVERIFY",
+      "DROP",
+      params.recoveryKey,
+      "CHECKSIG"
+    ]);
+  }
+  function buildRecoveryLeaves(fundingModel, params) {
+    switch (fundingModel) {
+      case "operator-funded":
+        return [
+          { script: buildFallbackLeaf(params) },
+          { script: buildRecoveryScript(params) }
+        ];
+      case "participant-funded":
+        throw new AggregationCohortError(
+          "Funding model 'participant-funded' is reserved and not yet implemented.",
+          "UNSUPPORTED_FUNDING_MODEL",
+          { fundingModel }
+        );
+      default:
+        throw new AggregationCohortError(
+          `Unknown funding model: ${fundingModel}.`,
+          "UNKNOWN_FUNDING_MODEL",
+          { fundingModel }
+        );
+    }
+  }
+
   // src/core/aggregation/cohort.ts
   var AggregationCohort = class {
     /** Unique identifier for the cohort. */
@@ -103353,8 +103499,8 @@ a=end-of-candidates
     /** List of participant DIDs that have been accepted into the cohort. */
     participants = [];
     /**
-     * Mapping from participant DID → their compressed secp256k1 public key.
-     * Distinct from {@link cohortKeys} (which is sorted per BIP-327) — this lets
+     * Mapping from participant DID to their compressed secp256k1 public key.
+     * Distinct from {@link cohortKeys} (which is sorted per BIP-327): this lets
      * callers look up a participant's key without knowing their position in the
      * sorted array. Populated by the service at `acceptParticipant` time.
      */
@@ -103362,16 +103508,41 @@ a=end-of-candidates
     /** Sorted list of cohort participants' compressed public keys. */
     #cohortKeys = [];
     /**
-     * BIP-341 TapTweak — `taggedHash("TapTweak", internalPubkey)` for a key-path-only
-     * Taproot output. Despite prior naming, this is NOT a Merkle root: key-path-only
-     * spends have no script tree.
+     * BIP-341 TapTweak scalar: `taggedHash("TapTweak", internalPubkey || tapMerkleRoot)`.
+     * The beacon output is an internal key (the MuSig2 aggregate) plus a script
+     * tree (the recovery leaves), so the tweak commits to the tree's Merkle root.
+     * The MuSig2 signing session applies this as an x-only tweak; a value that does
+     * not match the root the funded address was derived from silently yields an
+     * invalid key-path signature.
      */
     tapTweak = new Uint8Array();
-    /** The n-of-n MuSig2 Taproot beacon address. */
+    /** The n-of-n MuSig2 aggregate internal key, x-only (32 bytes), set by computeBeaconAddress(). */
+    internalKey = new Uint8Array();
+    /** BIP-341 Taproot Merkle root of the recovery script tree, set by computeBeaconAddress(). */
+    tapMerkleRoot = new Uint8Array();
+    /** Operator recovery key, x-only (32 bytes). Used to build the CSV recovery leaf. */
+    recoveryKey;
+    /** Relative-timelock (BIP-68 nSequence) before the recovery leaf is spendable. */
+    recoverySequence;
+    /** Funding model governing the recovery leaves (default 'operator-funded'). */
+    fundingModel;
+    /**
+     * Advertised k of the k-of-n fallback leaf, or undefined to default to n-1 at
+     * address computation. Read the resolved value via {@link effectiveFallbackThreshold}.
+     */
+    fallbackThreshold;
+    /** The Taproot beacon address: key path is the MuSig2 aggregate, script path is fallback + recovery. */
     beaconAddress = "";
     /** Pending DID updates submitted by participants, keyed by DID. */
     pendingUpdates = /* @__PURE__ */ new Map();
-    /** CAS Beacon Announcement Map (DID → updateHash), set by buildCASAnnouncement(). */
+    /**
+     * Participant DIDs that explicitly declined to submit an update this round
+     * (cooperative non-inclusion). A decliner is absent from the CAS Announcement
+     * Map and carries a non-inclusion leaf in the SMT, yet still signs. Kept
+     * disjoint from {@link pendingUpdates} so CAS correctness holds by construction.
+     */
+    nonIncluded = /* @__PURE__ */ new Set();
+    /** CAS Beacon Announcement Map (DID to updateHash), set by buildCASAnnouncement(). */
     casAnnouncement;
     /** Per-participant SMT proofs, set by buildSMTTree(). */
     smtProofs;
@@ -103381,12 +103552,16 @@ a=end-of-candidates
     validationAcks = /* @__PURE__ */ new Set();
     /** Set of participant DIDs that have rejected the aggregated data. */
     validationRejections = /* @__PURE__ */ new Set();
-    constructor({ id, minParticipants, serviceDid, network, beaconType }) {
+    constructor({ id, minParticipants, serviceDid, network, beaconType, recoveryKey, recoverySequence, fundingModel, fallbackThreshold }) {
       this.id = id || crypto.randomUUID();
       this.minParticipants = minParticipants ?? 2;
       this.serviceDid = serviceDid || "";
       this.network = network;
       this.beaconType = beaconType || "CASBeacon";
+      this.recoveryKey = recoveryKey;
+      this.recoverySequence = recoverySequence;
+      this.fundingModel = fundingModel ?? DEFAULT_FUNDING_MODEL;
+      this.fallbackThreshold = fallbackThreshold;
     }
     /** Sorted cohort keys (sorted on assignment per BIP-327). */
     get cohortKeys() {
@@ -103396,8 +103571,26 @@ a=end-of-candidates
       this.#cohortKeys = sortKeys(keys);
     }
     /**
-     * Computes the n-of-n MuSig2 Taproot beacon address from cohort keys.
-     * Sets `tapTweak` to the BIP-341 key-path-only tweak.
+     * The resolved k of the k-of-n fallback leaf: the advertised
+     * {@link fallbackThreshold}, or n-1 (floored at 1) when unadvertised, where n is
+     * the current cohort size. This is the value the beacon address commits to and
+     * the spend builders must reproduce. Returns 0 before any cohort keys are set.
+     */
+    get effectiveFallbackThreshold() {
+      if (this.#cohortKeys.length === 0) return 0;
+      return resolveFallbackThreshold(this.fallbackThreshold, this.#cohortKeys.length);
+    }
+    /**
+     * Computes the Taproot beacon address from the cohort keys and recovery params.
+     *
+     * The output's key path is the n-of-n MuSig2 aggregate of the cohort keys; its
+     * script path is the recovery tree (a CSV recovery leaf so a missing signer
+     * cannot permanently lock the UTXO). Sets `internalKey`, `tapMerkleRoot`, and
+     * the `tapTweak` the MuSig2 session must apply for the key-path spend.
+     *
+     * The tweak is derived from the Merkle root the address was built with (read
+     * back from the payment), never recomputed by hand, so the MuSig2 key-path
+     * signature is guaranteed to validate against the funded address.
      */
     computeBeaconAddress() {
       if (this.#cohortKeys.length === 0) {
@@ -103407,10 +103600,25 @@ a=end-of-candidates
           { cohortId: this.id }
         );
       }
+      if (!this.recoveryKey || this.recoveryKey.length === 0 || this.recoverySequence === void 0) {
+        throw new AggregationCohortError(
+          "Cannot compute beacon address: missing recovery key or sequence.",
+          "NO_RECOVERY_PARAMS",
+          { cohortId: this.id }
+        );
+      }
       const keyAggContext = keyAggregate(this.#cohortKeys);
       const aggPubkey = keyAggExport(keyAggContext);
-      const payment = p2tr(aggPubkey, void 0, getNetwork(this.network));
-      this.tapTweak = schnorr2.utils.taggedHash("TapTweak", aggPubkey);
+      const leaves = buildRecoveryLeaves(this.fundingModel, {
+        recoveryKey: this.recoveryKey,
+        recoverySequence: this.recoverySequence,
+        cohortKeys: this.#cohortKeys,
+        fallbackThreshold: resolveFallbackThreshold(this.fallbackThreshold, this.#cohortKeys.length)
+      });
+      const payment = p2tr(aggPubkey, leaves, getNetwork(this.network), true);
+      this.internalKey = aggPubkey;
+      this.tapMerkleRoot = payment.tapMerkleRoot;
+      this.tapTweak = schnorr2.utils.taggedHash("TapTweak", concatBytes(aggPubkey, payment.tapMerkleRoot));
       if (!payment.address) {
         throw new AggregationCohortError(
           "Failed to compute Taproot address",
@@ -103466,20 +103674,54 @@ a=end-of-candidates
       }
       this.pendingUpdates.set(participantDid, signedUpdate);
     }
+    /**
+     * Record that a participant declined to submit an update this round
+     * (cooperative non-inclusion). The member stays in the cohort and still signs.
+     */
+    addNonInclusion(participantDid) {
+      if (!this.participants.includes(participantDid)) {
+        throw new AggregationCohortError(
+          `Participant ${participantDid} is not in cohort ${this.id}.`,
+          "UNKNOWN_PARTICIPANT",
+          { cohortId: this.id, participantDid }
+        );
+      }
+      if (this.pendingUpdates.has(participantDid)) {
+        throw new AggregationCohortError(
+          `Participant ${participantDid} already submitted an update; cannot also decline.`,
+          "CONFLICTING_RESPONSE",
+          { cohortId: this.id, participantDid }
+        );
+      }
+      this.nonIncluded.add(participantDid);
+    }
     hasAllUpdates() {
       return this.pendingUpdates.size === this.participants.length;
     }
+    /**
+     * True when every participant has responded for this round, either with an
+     * update or with an explicit non-inclusion. This is the aggregation gate when
+     * non-inclusion is in play; it generalizes {@link hasAllUpdates} the same way
+     * {@link hasAllValidationResponses} generalizes a unanimous ack.
+     */
+    hasAllResponses() {
+      return this.pendingUpdates.size + this.nonIncluded.size === this.participants.length;
+    }
     /**
      * Builds a CAS Announcement Map from collected updates.
-     * Maps each participant DID → base64url canonical hash of their signed update.
+     * Maps each participant DID to base64url canonical hash of their signed update.
      * Computes signal bytes as SHA-256 of canonicalized announcement.
+     *
+     * Members who declined (cooperative non-inclusion) are naturally absent from
+     * the map: the body iterates {@link pendingUpdates}, which never holds a
+     * decliner. Absence from the map is exactly the CAS non-inclusion signal.
      */
     buildCASAnnouncement() {
-      if (!this.hasAllUpdates()) {
+      if (!this.hasAllResponses()) {
         throw new AggregationCohortError(
-          "Cannot build CAS Announcement: not all updates collected.",
-          "INCOMPLETE_UPDATES",
-          { cohortId: this.id, collected: this.pendingUpdates.size, total: this.participants.length }
+          "Cannot build CAS Announcement: not all participants have responded.",
+          "INCOMPLETE_RESPONSES",
+          { cohortId: this.id, updates: this.pendingUpdates.size, declined: this.nonIncluded.size, total: this.participants.length }
         );
       }
       const announcement = {};
@@ -103491,31 +103733,41 @@ a=end-of-candidates
       return announcement;
     }
     /**
-     * Builds an SMT tree from collected updates.
-     * Each entry uses a random 32-byte nonce + canonicalized signed update bytes.
-     * Stores per-participant proofs and the SMT root as signalBytes.
+     * Builds an SMT tree with one leaf per participant.
+     *
+     * A member who submitted an update gets an inclusion leaf
+     * (SHA-256(SHA-256(nonce) || SHA-256(update))); a member who declined gets a
+     * non-inclusion leaf (SHA-256(SHA-256(nonce)), the `signedUpdate` entry field
+     * omitted). The cohort mints each member's nonce and returns it inside that
+     * member's serialized proof, so a decliner can self-validate its own
+     * non-inclusion slot and the resolver can recompute the leaf. Stores
+     * per-participant proofs and the SMT root as signalBytes.
      */
     buildSMTTree() {
-      if (!this.hasAllUpdates()) {
+      if (!this.hasAllResponses()) {
         throw new AggregationCohortError(
-          "Cannot build SMT tree: not all updates collected.",
-          "INCOMPLETE_UPDATES",
-          { cohortId: this.id }
+          "Cannot build SMT tree: not all participants have responded.",
+          "INCOMPLETE_RESPONSES",
+          { cohortId: this.id, updates: this.pendingUpdates.size, declined: this.nonIncluded.size, total: this.participants.length }
         );
       }
       const tree2 = new BTCR2MerkleTree();
       const entries = [];
       const encoder4 = new TextEncoder();
-      for (const [did, signedUpdate] of this.pendingUpdates) {
-        const canonicalBytes = encoder4.encode(canonicalize2(signedUpdate));
+      for (const did of this.participants) {
         const nonce = randomBytes(32);
-        entries.push({ did, nonce, signedUpdate: canonicalBytes });
+        const signedUpdate = this.pendingUpdates.get(did);
+        if (signedUpdate) {
+          entries.push({ did, nonce, signedUpdate: encoder4.encode(canonicalize2(signedUpdate)) });
+        } else {
+          entries.push({ did, nonce });
+        }
       }
       tree2.addEntries(entries);
       tree2.finalize();
       this.signalBytes = tree2.rootHash;
       this.smtProofs = /* @__PURE__ */ new Map();
-      for (const [did] of this.pendingUpdates) {
+      for (const did of this.participants) {
         this.smtProofs.set(did, tree2.proof(did));
       }
       return this.smtProofs;
@@ -103541,7 +103793,7 @@ a=end-of-candidates
       return this.validationAcks.size + this.validationRejections.size === this.participants.length;
     }
     /**
-     * True when all participants approved. Note: differs from {@link hasAllValidationResponses} —
+     * True when all participants approved. Note: differs from {@link hasAllValidationResponses},
      * this returns false if any participant rejected, even if all responses are in.
      */
     isFullyValidated() {
@@ -103552,6 +103804,7 @@ a=end-of-candidates
   // src/core/aggregation/conditions.ts
   init_shim();
   var KNOWN_BEACON_TYPES = ["CASBeacon", "SMTBeacon"];
+  var KNOWN_FUNDING_MODELS = ["operator-funded", "participant-funded"];
   function checkPair(problems, label, min, max) {
     if (min !== void 0 && (!Number.isInteger(min) || min < 0)) {
       problems.push(`min${label} must be an integer >= 0`);
@@ -103595,11 +103848,128 @@ a=end-of-candidates
     if (c2.pendingUpdateTrigger !== void 0 && (!Number.isInteger(c2.pendingUpdateTrigger) || c2.pendingUpdateTrigger < 1)) {
       problems.push("pendingUpdateTrigger must be an integer >= 1");
     }
+    if (c2.fallbackThreshold !== void 0) {
+      if (!Number.isInteger(c2.fallbackThreshold) || c2.fallbackThreshold < 1) {
+        problems.push("fallbackThreshold must be an integer >= 1");
+      } else if (c2.maxParticipants !== void 0 && Number.isInteger(c2.maxParticipants) && c2.fallbackThreshold > c2.maxParticipants) {
+        problems.push("fallbackThreshold must be <= maxParticipants");
+      }
+    }
     checkCost(problems, "costOfEnrollment", c2.costOfEnrollment);
     checkCost(problems, "costPerAnnouncement", c2.costPerAnnouncement);
+    if (typeof c2.recoveryKey !== "string" || !/^[0-9a-fA-F]{64}$/.test(c2.recoveryKey)) {
+      problems.push("recoveryKey must be a 64-character hex string (x-only public key)");
+    }
+    if (!Number.isInteger(c2.recoverySequence) || c2.recoverySequence < 1 || c2.recoverySequence > MAX_RECOVERY_SEQUENCE) {
+      problems.push(`recoverySequence must be a block-based BIP-68 relative timelock in [1, ${MAX_RECOVERY_SEQUENCE}]`);
+    }
+    if (c2.fundingModel !== void 0 && !KNOWN_FUNDING_MODELS.includes(c2.fundingModel)) {
+      problems.push(`fundingModel must be one of ${KNOWN_FUNDING_MODELS.join(", ")}`);
+    }
     return problems;
   }
 
+  // src/core/aggregation/fallback-spend.ts
+  init_shim();
+  init_secp256k1();
+  function bytesEqual(a2, b) {
+    return a2.length === b.length && a2.every((x, i4) => x === b[i4]);
+  }
+  function fallbackSighash(tx, inputIndex, prevOutScript, prevOutValue, fallbackLeafScript) {
+    return tx.preimageWitnessV1(
+      inputIndex,
+      [prevOutScript],
+      SigHash.DEFAULT,
+      [prevOutValue],
+      void 0,
+      fallbackLeafScript,
+      TAPROOT_LEAF_VERSION
+    );
+  }
+  function buildFallbackSpend(params) {
+    const {
+      pendingTx,
+      cohortKeys,
+      recoveryKey,
+      recoverySequence,
+      fundingModel,
+      network,
+      prevOutScript,
+      prevOutValue,
+      signatures
+    } = params;
+    const inputIndex = params.inputIndex ?? 0;
+    if (cohortKeys.length === 0) {
+      throw new AggregationCohortError(
+        "Cannot build fallback spend: no cohort keys.",
+        "NO_COHORT_KEYS"
+      );
+    }
+    const fallbackThreshold = resolveFallbackThreshold(params.fallbackThreshold, cohortKeys.length);
+    const internalKey = keyAggExport(keyAggregate(sortKeys(cohortKeys)));
+    const leaves = buildRecoveryLeaves(fundingModel ?? DEFAULT_FUNDING_MODEL, {
+      recoveryKey,
+      recoverySequence,
+      cohortKeys,
+      fallbackThreshold
+    });
+    const net = getNetwork(network);
+    const payment = p2tr(internalKey, leaves, net, true);
+    if (!bytesEqual(payment.script, prevOutScript)) {
+      throw new AggregationCohortError(
+        "Reconstructed beacon output script does not match the spent prevout script.",
+        "PREVOUT_SCRIPT_MISMATCH"
+      );
+    }
+    const fallbackLeaf = buildFallbackLeaf({ cohortKeys, fallbackThreshold });
+    const leafEntry = payment.tapLeafScript?.find(([, scriptVer]) => {
+      const script = scriptVer.slice(0, scriptVer.length - 1);
+      return bytesEqual(script, fallbackLeaf);
+    });
+    if (!leafEntry) {
+      throw new AggregationCohortError(
+        "Could not locate the fallback leaf in the reconstructed beacon output.",
+        "FALLBACK_LEAF_NOT_FOUND"
+      );
+    }
+    const cohortXOnly = sortKeys(cohortKeys).map((k) => k.slice(1));
+    const tx = pendingTx;
+    const sighash = fallbackSighash(tx, inputIndex, prevOutScript, prevOutValue, fallbackLeaf);
+    const leafHash = tapLeafHash2(fallbackLeaf);
+    const accepted = /* @__PURE__ */ new Map();
+    for (const { pubKey, signature } of signatures) {
+      if (pubKey.length !== 32 || signature.length !== 64) continue;
+      const isCohortKey = cohortXOnly.some((k) => bytesEqual(k, pubKey));
+      if (!isCohortKey) continue;
+      const hex2 = Array.from(pubKey, (b) => b.toString(16).padStart(2, "0")).join("");
+      if (accepted.has(hex2)) continue;
+      let ok = false;
+      try {
+        ok = schnorr2.verify(signature, sighash, pubKey);
+      } catch {
+        ok = false;
+      }
+      if (ok) accepted.set(hex2, signature);
+    }
+    if (accepted.size < fallbackThreshold) {
+      throw new AggregationCohortError(
+        `Not enough valid fallback signatures: have ${accepted.size}, need ${fallbackThreshold}.`,
+        "NOT_ENOUGH_FALLBACK_SIGNATURES",
+        { have: accepted.size, need: fallbackThreshold }
+      );
+    }
+    const chosen = cohortXOnly.filter((k) => accepted.has(Array.from(k, (b) => b.toString(16).padStart(2, "0")).join(""))).slice(0, fallbackThreshold);
+    tx.updateInput(inputIndex, {
+      tapLeafScript: [leafEntry],
+      tapScriptSig: chosen.map((pubKey) => {
+        const hex2 = Array.from(pubKey, (b) => b.toString(16).padStart(2, "0")).join("");
+        return [{ pubKey, leafHash }, accepted.get(hex2)];
+      })
+    });
+    tx.finalize();
+    return tx;
+  }
+
   // src/core/aggregation/messages/base.ts
   init_shim();
   var AGGREGATION_WIRE_VERSION = 1;
@@ -103639,12 +104009,15 @@ a=end-of-candidates
   var COHORT_OPT_IN_ACCEPT = `${AGGREGATION_MESSAGE_PREFIX}/keygen/cohort_opt_in_accept`;
   var COHORT_READY = `${AGGREGATION_MESSAGE_PREFIX}/keygen/cohort_ready`;
   var SUBMIT_UPDATE = `${AGGREGATION_MESSAGE_PREFIX}/update/submit_update`;
+  var SUBMIT_NONINCLUDED = `${AGGREGATION_MESSAGE_PREFIX}/update/submit_nonincluded`;
   var DISTRIBUTE_AGGREGATED_DATA = `${AGGREGATION_MESSAGE_PREFIX}/update/distribute_aggregated_data`;
   var VALIDATION_ACK = `${AGGREGATION_MESSAGE_PREFIX}/update/validation_ack`;
   var AUTHORIZATION_REQUEST = `${AGGREGATION_MESSAGE_PREFIX}/sign/authorization_request`;
   var NONCE_CONTRIBUTION = `${AGGREGATION_MESSAGE_PREFIX}/sign/nonce_contribution`;
   var AGGREGATED_NONCE = `${AGGREGATION_MESSAGE_PREFIX}/sign/aggregated_nonce`;
   var SIGNATURE_AUTHORIZATION = `${AGGREGATION_MESSAGE_PREFIX}/sign/signature_authorization`;
+  var FALLBACK_AUTHORIZATION_REQUEST = `${AGGREGATION_MESSAGE_PREFIX}/sign/fallback_authorization_request`;
+  var FALLBACK_SIGNATURE = `${AGGREGATION_MESSAGE_PREFIX}/sign/fallback_signature`;
 
   // src/core/aggregation/messages/factories.ts
   init_shim();
@@ -103668,6 +104041,10 @@ a=end-of-candidates
     const { from: from8, to, ...body } = fields;
     return new BaseMessage({ type: SUBMIT_UPDATE, from: from8, to, body });
   }
+  function createSubmitNonIncludedMessage(fields) {
+    const { from: from8, to, ...body } = fields;
+    return new BaseMessage({ type: SUBMIT_NONINCLUDED, from: from8, to, body });
+  }
   function createDistributeAggregatedDataMessage(fields) {
     const { from: from8, to, ...body } = fields;
     return new BaseMessage({ type: DISTRIBUTE_AGGREGATED_DATA, from: from8, to, body });
@@ -103692,6 +104069,14 @@ a=end-of-candidates
     const { from: from8, to, ...body } = fields;
     return new BaseMessage({ type: SIGNATURE_AUTHORIZATION, from: from8, to, body });
   }
+  function createFallbackAuthorizationRequestMessage(fields) {
+    const { from: from8, to, ...body } = fields;
+    return new BaseMessage({ type: FALLBACK_AUTHORIZATION_REQUEST, from: from8, to, body });
+  }
+  function createFallbackSignatureMessage(fields) {
+    const { from: from8, to, ...body } = fields;
+    return new BaseMessage({ type: FALLBACK_SIGNATURE, from: from8, to, body });
+  }
 
   // src/core/aggregation/phases.ts
   init_shim();
@@ -103706,6 +104091,7 @@ a=end-of-candidates
     ServiceCohortPhase2["SigningStarted"] = "SigningStarted";
     ServiceCohortPhase2["NoncesCollected"] = "NoncesCollected";
     ServiceCohortPhase2["AwaitingPartialSigs"] = "AwaitingPartialSigs";
+    ServiceCohortPhase2["FallbackRequested"] = "FallbackRequested";
     ServiceCohortPhase2["Complete"] = "Complete";
     ServiceCohortPhase2["Failed"] = "Failed";
     return ServiceCohortPhase2;
@@ -103715,11 +104101,13 @@ a=end-of-candidates
     ParticipantCohortPhase2["OptedIn"] = "OptedIn";
     ParticipantCohortPhase2["CohortReady"] = "CohortReady";
     ParticipantCohortPhase2["UpdateSubmitted"] = "UpdateSubmitted";
+    ParticipantCohortPhase2["NonIncluded"] = "NonIncluded";
     ParticipantCohortPhase2["AwaitingValidation"] = "AwaitingValidation";
     ParticipantCohortPhase2["ValidationSent"] = "ValidationSent";
     ParticipantCohortPhase2["AwaitingSigning"] = "AwaitingSigning";
     ParticipantCohortPhase2["NonceSent"] = "NonceSent";
     ParticipantCohortPhase2["AwaitingPartialSig"] = "AwaitingPartialSig";
+    ParticipantCohortPhase2["AwaitingFallbackSig"] = "AwaitingFallbackSig";
     ParticipantCohortPhase2["Complete"] = "Complete";
     ParticipantCohortPhase2["Failed"] = "Failed";
     return ParticipantCohortPhase2;
@@ -103747,11 +104135,11 @@ a=end-of-candidates
     prevOutScripts;
     /** Previous output values for Taproot sighash computation. */
     prevOutValues;
-    /** Map of participant publicKey-hex → public nonce contribution. */
+    /** Map of participant publicKey-hex to public nonce contribution. */
     nonceContributions = /* @__PURE__ */ new Map();
     /** Aggregated MuSig2 nonce (66 bytes). */
     aggregatedNonce;
-    /** Map of participant DID → partial signature. */
+    /** Map of participant DID to partial signature. */
     partialSignatures = /* @__PURE__ */ new Map();
     /** Final 64-byte Schnorr signature. */
     signature;
@@ -103934,7 +104322,7 @@ a=end-of-candidates
         throw new SigningSessionError("Aggregated nonce not available.", "MISSING_AGGREGATED_NONCE");
       }
       if (!this.#secretNonce) {
-        throw new SigningSessionError("Secret nonce not available \u2014 generateNonceContribution() must be called first.", "MISSING_SECRET_NONCE");
+        throw new SigningSessionError("Secret nonce not available - generateNonceContribution() must be called first.", "MISSING_SECRET_NONCE");
       }
       const session = new Session(
         this.aggregatedNonce,
@@ -104004,6 +104392,9 @@ a=end-of-candidates
         case SUBMIT_UPDATE:
           this.#handleSubmitUpdate(message2);
           break;
+        case SUBMIT_NONINCLUDED:
+          this.#handleSubmitNonInclusion(message2);
+          break;
         case VALIDATION_ACK:
           this.#handleValidationAck(message2);
           break;
@@ -104013,6 +104404,9 @@ a=end-of-candidates
         case SIGNATURE_AUTHORIZATION:
           this.#handleSignatureAuthorization(message2);
           break;
+        case FALLBACK_SIGNATURE:
+          this.#handleFallbackSignature(message2);
+          break;
         default:
           break;
       }
@@ -104031,7 +104425,7 @@ a=end-of-candidates
     }
     /**
      * Create a new cohort with the given config. Returns the cohort ID.
-     * Cohort starts in `Created` phase — call `advertise()` to broadcast.
+     * Cohort starts in `Created` phase - call `advertise()` to broadcast.
      */
     createCohort(config) {
       const problems = validateCohortConditions(config);
@@ -104046,7 +104440,11 @@ a=end-of-candidates
         serviceDid: this.did,
         minParticipants: config.minParticipants,
         network: config.network,
-        beaconType: config.beaconType
+        beaconType: config.beaconType,
+        recoveryKey: hexToBytes(config.recoveryKey),
+        recoverySequence: config.recoverySequence,
+        fundingModel: config.fundingModel,
+        fallbackThreshold: config.fallbackThreshold
       });
       this.#cohortStates.set(cohort.id, {
         phase: "Created" /* Created */,
@@ -104247,11 +104645,64 @@ a=end-of-candidates
         });
         return;
       }
+      if (state.cohort.nonIncluded.has(message2.from)) {
+        state.rejections.push({
+          from: message2.from,
+          code: "UPDATE_MALFORMED",
+          reason: "Participant already declined this round; cannot also submit an update"
+        });
+        return;
+      }
+      if (state.cohort.pendingUpdates.has(message2.from)) {
+        state.rejections.push({
+          from: message2.from,
+          code: "UPDATE_MALFORMED",
+          reason: "Participant already submitted an update this round; cannot resubmit"
+        });
+        return;
+      }
       state.cohort.addUpdate(message2.from, signedUpdate);
       if (state.phase === "CohortSet" /* CohortSet */) {
         state.phase = "CollectingUpdates" /* CollectingUpdates */;
       }
-      if (state.cohort.hasAllUpdates()) {
+      if (state.cohort.hasAllResponses()) {
+        state.phase = "UpdatesCollected" /* UpdatesCollected */;
+      }
+    }
+    /**
+     * Handle an incoming SUBMIT_NONINCLUDED message: a member declares it has no
+     * update this round (cooperative non-inclusion). Membership is proven by the
+     * signed transport envelope, so the body carries only the cohortId. The member
+     * stays in the cohort and still signs; it is absent from the CAS map and
+     * carries a non-inclusion leaf in the SMT.
+     */
+    #handleSubmitNonInclusion(message2) {
+      const cohortId = message2.body?.cohortId;
+      if (!cohortId) return;
+      const state = this.#cohortStates.get(cohortId);
+      if (!state) return;
+      if (state.phase !== "CohortSet" /* CohortSet */ && state.phase !== "CollectingUpdates" /* CollectingUpdates */) return;
+      if (!state.cohort.participants.includes(message2.from)) {
+        state.rejections.push({
+          from: message2.from,
+          code: "UPDATE_MALFORMED",
+          reason: "Sender is not a member of this cohort"
+        });
+        return;
+      }
+      if (state.cohort.pendingUpdates.has(message2.from) || state.cohort.nonIncluded.has(message2.from)) {
+        state.rejections.push({
+          from: message2.from,
+          code: "UPDATE_MALFORMED",
+          reason: "Participant already responded this round"
+        });
+        return;
+      }
+      state.cohort.addNonInclusion(message2.from);
+      if (state.phase === "CohortSet" /* CohortSet */) {
+        state.phase = "CollectingUpdates" /* CollectingUpdates */;
+      }
+      if (state.cohort.hasAllResponses()) {
         state.phase = "UpdatesCollected" /* UpdatesCollected */;
       }
     }
@@ -104361,7 +104812,7 @@ a=end-of-candidates
     }
     /**
      * Start a signing session by creating auth requests for all participants.
-     * The caller provides the transaction data — typically built via
+     * The caller provides the transaction data - typically built via
      * `buildBeaconTransaction()` against a Bitcoin connection.
      */
     startSigning(cohortId, txData) {
@@ -104468,11 +104919,144 @@ a=end-of-candidates
         state.result = {
           cohortId,
           signature,
-          signedTx: state.signingSession.pendingTx
+          signedTx: state.signingSession.pendingTx,
+          path: "key-path"
         };
         state.phase = "Complete" /* Complete */;
       }
     }
+    /**
+     * Abandon the optimistic n-of-n key path and ask members to authorize the
+     * k-of-n fallback (script-path) spend of the SAME beacon transaction (graceful
+     * liveness, ADR 042). Reuses the in-flight signing session's transaction and
+     * spent output, so the announcement and its outputs are unchanged: only the
+     * witness path differs. Returns one FALLBACK_AUTHORIZATION_REQUEST per
+     * participant.
+     *
+     * Callable once optimistic signing has started (the session and its tx exist)
+     * and before it completes. A cohort can take exactly one of the two paths: the
+     * caller (runner) must commit to fallback and stop driving the optimistic path.
+     */
+    startFallbackSigning(cohortId) {
+      const state = this.#cohortStates.get(cohortId);
+      if (!state) {
+        throw new AggregationServiceError(`Cohort ${cohortId} not found.`, "COHORT_NOT_FOUND", { cohortId });
+      }
+      if (!state.signingSession) {
+        throw new AggregationServiceError(
+          `Cannot start fallback for cohort ${cohortId}: no signing session.`,
+          "NO_SIGNING_SESSION",
+          { cohortId }
+        );
+      }
+      const signingPhases = [
+        "SigningStarted" /* SigningStarted */,
+        "NoncesCollected" /* NoncesCollected */,
+        "AwaitingPartialSigs" /* AwaitingPartialSigs */
+      ];
+      if (!signingPhases.includes(state.phase)) {
+        throw new AggregationServiceError(
+          `Cannot start fallback for cohort ${cohortId}: phase is ${state.phase}.`,
+          "INVALID_PHASE",
+          { cohortId, phase: state.phase }
+        );
+      }
+      const session = state.signingSession;
+      const prevOutScript = session.prevOutScripts[0];
+      const prevOutValue = session.prevOutValues[0];
+      if (!prevOutScript || prevOutValue === void 0) {
+        throw new AggregationServiceError(
+          `Cannot start fallback for cohort ${cohortId}: signing session missing prevout data.`,
+          "MISSING_PREV_OUT",
+          { cohortId }
+        );
+      }
+      const fallbackLeaf = buildFallbackLeaf({
+        cohortKeys: state.cohort.cohortKeys,
+        fallbackThreshold: state.cohort.effectiveFallbackThreshold
+      });
+      state.fallbackSignatures = /* @__PURE__ */ new Map();
+      state.phase = "FallbackRequested" /* FallbackRequested */;
+      const messages2 = [];
+      for (const participantDid of state.cohort.participants) {
+        messages2.push(createFallbackAuthorizationRequestMessage({
+          from: this.did,
+          to: participantDid,
+          cohortId,
+          sessionId: session.id,
+          pendingTx: session.pendingTx.hex,
+          prevOutScriptHex: bytesToHex(prevOutScript),
+          prevOutValue: prevOutValue.toString(),
+          fallbackLeafScriptHex: bytesToHex(fallbackLeaf)
+        }));
+      }
+      return messages2;
+    }
+    /**
+     * Handle an incoming FALLBACK_SIGNATURE: a member's standalone BIP-340
+     * signature over the fallback script-path sighash. The signature is
+     * authenticated to the sender (its `signerPk` must be the sender's own cohort
+     * key and the signature must verify against the sighash) and collected. Once k
+     * valid signatures are in, the k-of-n fallback spend is assembled and the
+     * cohort completes via the script path.
+     */
+    #handleFallbackSignature(message2) {
+      const cohortId = message2.body?.cohortId;
+      if (!cohortId) return;
+      const state = this.#cohortStates.get(cohortId);
+      if (!state || !state.signingSession || !state.fallbackSignatures) return;
+      if (state.phase !== "FallbackRequested" /* FallbackRequested */) return;
+      const sessionId = message2.body?.sessionId;
+      if (sessionId !== state.signingSession.id) return;
+      const signerPk = message2.body?.signerPk;
+      const fallbackSignature = message2.body?.fallbackSignature;
+      if (!signerPk || !fallbackSignature) return;
+      const prevOutScript = state.signingSession.prevOutScripts[0];
+      const prevOutValue = state.signingSession.prevOutValues[0];
+      if (!prevOutScript || prevOutValue === void 0) return;
+      const memberKey = state.cohort.participantKeys.get(message2.from);
+      if (!memberKey) {
+        state.rejections.push({ from: message2.from, code: "UPDATE_MALFORMED", reason: "Fallback signature from a non-member" });
+        return;
+      }
+      const memberXOnly = memberKey.slice(1);
+      if (signerPk.length !== 32 || !memberXOnly.every((b, i4) => b === signerPk[i4])) {
+        state.rejections.push({ from: message2.from, code: "UPDATE_MALFORMED", reason: "Fallback signerPk does not match the sender cohort key" });
+        return;
+      }
+      const fallbackLeaf = buildFallbackLeaf({
+        cohortKeys: state.cohort.cohortKeys,
+        fallbackThreshold: state.cohort.effectiveFallbackThreshold
+      });
+      const sighash = fallbackSighash(state.signingSession.pendingTx, 0, prevOutScript, prevOutValue, fallbackLeaf);
+      let valid = false;
+      try {
+        valid = fallbackSignature.length === 64 && schnorr2.verify(fallbackSignature, sighash, signerPk);
+      } catch {
+        valid = false;
+      }
+      if (!valid) {
+        state.rejections.push({ from: message2.from, code: "UPDATE_VERIFICATION_FAILED", reason: "Fallback signature failed verification" });
+        return;
+      }
+      state.fallbackSignatures.set(message2.from, { pubKey: signerPk, signature: fallbackSignature });
+      if (state.fallbackSignatures.size >= state.cohort.effectiveFallbackThreshold) {
+        const signedTx = buildFallbackSpend({
+          pendingTx: state.signingSession.pendingTx,
+          cohortKeys: state.cohort.cohortKeys,
+          fallbackThreshold: state.cohort.effectiveFallbackThreshold,
+          recoveryKey: state.cohort.recoveryKey,
+          recoverySequence: state.cohort.recoverySequence,
+          fundingModel: state.cohort.fundingModel,
+          network: state.cohort.network,
+          prevOutScript,
+          prevOutValue,
+          signatures: [...state.fallbackSignatures.values()]
+        });
+        state.result = { cohortId, signature: new Uint8Array(), signedTx, path: "script-path" };
+        state.phase = "Complete" /* Complete */;
+      }
+    }
     getResult(cohortId) {
       return this.#cohortStates.get(cohortId)?.result;
     }
@@ -104504,6 +105088,7 @@ a=end-of-candidates
 
   // src/core/aggregation/participant.ts
   init_shim();
+  init_secp256k1();
   init_utils();
 
   // src/core/aggregation/messages/bodies.ts
@@ -104517,6 +105102,14 @@ a=end-of-candidates
     const v = b ? b[k] : void 0;
     return v === void 0 || typeof v === "number" && Number.isInteger(v) && v >= min;
   };
+  var intInRange = (b, k, min, max) => {
+    const v = b ? b[k] : void 0;
+    return typeof v === "number" && Number.isInteger(v) && v >= min && v <= max;
+  };
+  var optStrOneOf = (b, k, allowed) => {
+    const v = b ? b[k] : void 0;
+    return v === void 0 || typeof v === "string" && allowed.includes(v);
+  };
   var hasBool = (b, k) => !!b && typeof b[k] === "boolean";
   var hasBytes = (b, k) => !!b && b[k] instanceof Uint8Array;
   var hasBytesArray = (b, k) => {
@@ -104524,7 +105117,7 @@ a=end-of-candidates
     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");
+    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") && hasStr(m2.body, "recoveryKey") && intInRange(m2.body, "recoverySequence", 1, MAX_RECOVERY_SEQUENCE) && optStrOneOf(m2.body, "fundingModel", KNOWN_FUNDING_MODELS) && optIntMin(m2.body, "fallbackThreshold", 1) && 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");
@@ -104538,6 +105131,9 @@ a=end-of-candidates
   function isSubmitUpdateMessage(m2) {
     return m2.type === SUBMIT_UPDATE && hasStr(m2.body, "cohortId") && !!m2.body && typeof m2.body.signedUpdate === "object";
   }
+  function isSubmitNonIncludedMessage(m2) {
+    return m2.type === SUBMIT_NONINCLUDED && hasStr(m2.body, "cohortId");
+  }
   function isDistributeAggregatedDataMessage(m2) {
     return m2.type === DISTRIBUTE_AGGREGATED_DATA && hasStr(m2.body, "cohortId") && hasStr(m2.body, "beaconType") && hasStr(m2.body, "signalBytesHex");
   }
@@ -104556,8 +105152,38 @@ a=end-of-candidates
   function isSignatureAuthorizationMessage(m2) {
     return m2.type === SIGNATURE_AUTHORIZATION && hasStr(m2.body, "cohortId") && hasStr(m2.body, "sessionId") && hasBytes(m2.body, "partialSignature");
   }
+  function isFallbackAuthorizationRequestMessage(m2) {
+    return m2.type === FALLBACK_AUTHORIZATION_REQUEST && hasStr(m2.body, "cohortId") && hasStr(m2.body, "sessionId") && hasStr(m2.body, "pendingTx") && hasStr(m2.body, "prevOutScriptHex") && hasStr(m2.body, "prevOutValue") && hasStr(m2.body, "fallbackLeafScriptHex");
+  }
+  function isFallbackSignatureMessage(m2) {
+    return m2.type === FALLBACK_SIGNATURE && hasStr(m2.body, "cohortId") && hasStr(m2.body, "sessionId") && hasBytes(m2.body, "signerPk") && hasBytes(m2.body, "fallbackSignature");
+  }
 
   // src/core/aggregation/participant.ts
+  function txEmbedsSignal(tx, signalHex) {
+    let expected;
+    try {
+      expected = hexToBytes(signalHex);
+    } catch {
+      return false;
+    }
+    if (expected.length === 0) return false;
+    for (let i4 = 0; i4 < tx.outputsLength; i4++) {
+      const script = tx.getOutput(i4)?.script;
+      if (!script) continue;
+      let decoded;
+      try {
+        decoded = Script.decode(script);
+      } catch {
+        continue;
+      }
+      if (decoded.length === 2 && decoded[0] === "RETURN" && decoded[1] instanceof Uint8Array) {
+        const payload = decoded[1];
+        if (payload.length === expected.length && payload.every((b, j) => b === expected[j])) return true;
+      }
+    }
+    return false;
+  }
   var AggregationParticipant = class {
     did;
     /** MuSig2 signing capability. The raw secret never lives as a field here. */
@@ -104574,7 +105200,7 @@ a=end-of-candidates
     }
     /**
      * Process an incoming message. Updates internal state but never produces
-     * outgoing messages — those come exclusively from action methods.
+     * outgoing messages: those come exclusively from action methods.
      */
     receive(message2) {
       if (message2.version === void 0 || message2.version !== AGGREGATION_WIRE_VERSION) {
@@ -104600,6 +105226,9 @@ a=end-of-candidates
         case AGGREGATED_NONCE:
           this.#handleAggregatedNonce(message2);
           break;
+        case FALLBACK_AUTHORIZATION_REQUEST:
+          this.#handleFallbackAuthorizationRequest(message2);
+          break;
         default:
           break;
       }
@@ -104645,12 +105274,17 @@ a=end-of-candidates
           { cohortId, phase: state?.phase }
         );
       }
+      const advert = state.advert;
       const cohort = new AggregationCohort({
         id: cohortId,
         serviceDid: state.serviceDid,
-        minParticipants: state.advert.minParticipants,
-        network: state.advert.network,
-        beaconType: state.advert.beaconType
+        minParticipants: advert.minParticipants,
+        network: advert.network,
+        beaconType: advert.beaconType,
+        recoveryKey: advert.recoveryKey ? hexToBytes(advert.recoveryKey) : void 0,
+        recoverySequence: advert.recoverySequence,
+        fundingModel: advert.fundingModel,
+        fallbackThreshold: advert.fallbackThreshold
       });
       state.cohort = cohort;
       state.phase = "OptedIn" /* OptedIn */;
@@ -104665,7 +105299,7 @@ a=end-of-candidates
     }
     #handleOptInAccept(message2) {
     }
-    /** Cohorts that have been finalized — beacon address available. */
+    /** Cohorts that have been finalized: beacon address available. */
     get joinedCohorts() {
       const map3 = /* @__PURE__ */ new Map();
       for (const [id, state] of this.#cohortStates) {
@@ -104708,6 +105342,7 @@ a=end-of-candidates
         );
       }
       state.submittedUpdate = signedUpdate;
+      state.included = true;
       state.phase = "UpdateSubmitted" /* UpdateSubmitted */;
       const message2 = createSubmitUpdateMessage({
         from: this.did,
@@ -104717,6 +105352,30 @@ a=end-of-candidates
       });
       return [message2];
     }
+    /**
+     * User action: decline to submit an update this round (cooperative
+     * non-inclusion). The member stays in the cohort and still signs; it will be
+     * absent from the CAS Announcement Map, or carry a non-inclusion leaf in the
+     * SMT. Returns the SUBMIT_NONINCLUDED message to send.
+     */
+    declineUpdate(cohortId) {
+      const state = this.#cohortStates.get(cohortId);
+      if (!state || state.phase !== "CohortReady" /* CohortReady */) {
+        throw new AggregationParticipantError(
+          `Cannot decline in cohort ${cohortId}: not in CohortReady phase.`,
+          "INVALID_PHASE",
+          { cohortId, phase: state?.phase }
+        );
+      }
+      state.included = false;
+      state.phase = "NonIncluded" /* NonIncluded */;
+      const message2 = createSubmitNonIncludedMessage({
+        from: this.did,
+        to: state.serviceDid,
+        cohortId
+      });
+      return [message2];
+    }
     /** Aggregated data awaiting user validation. */
     get pendingValidations() {
       const map3 = /* @__PURE__ */ new Map();
@@ -104727,22 +105386,35 @@ 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;
       const state = this.#cohortStates.get(cohortId);
-      if (!state || state.phase !== "UpdateSubmitted" /* UpdateSubmitted */) return;
-      if (!state.submittedUpdate) return;
+      if (!state || state.phase !== "UpdateSubmitted" /* UpdateSubmitted */ && state.phase !== "NonIncluded" /* NonIncluded */) return;
+      const declined = state.included === false;
+      if (!declined && !state.submittedUpdate) return;
       const beaconType = message2.body?.beaconType;
       if (!beaconType) return;
       const strategy = getBeaconStrategy(beaconType);
       if (!strategy) return;
       const signalBytesHex = message2.body?.signalBytesHex ?? "";
-      const expectedHash = canonicalHash(state.submittedUpdate);
+      const expectedHash = declined ? "" : canonicalHash(state.submittedUpdate);
       const result = strategy.validateParticipantView({
         participantDid: this.did,
-        submittedUpdate: state.submittedUpdate,
-        expectedHash,
+        included: !declined,
+        submittedUpdate: declined ? void 0 : state.submittedUpdate,
+        expectedHash: declined ? void 0 : expectedHash,
         body: message2.body
       });
       state.validation = {
@@ -104752,7 +105424,8 @@ a=end-of-candidates
         expectedHash,
         matches: result.matches,
         casAnnouncement: result.casAnnouncement,
-        smtProof: result.smtProof
+        smtProof: result.smtProof,
+        included: !declined
       };
       state.phase = "AwaitingValidation" /* AwaitingValidation */;
     }
@@ -104826,6 +105499,31 @@ a=end-of-candidates
       };
       state.phase = "AwaitingSigning" /* AwaitingSigning */;
     }
+    /**
+     * Bind a signing approval to the announcement the member validated: a beacon
+     * transaction MUST carry an OP_RETURN with the exact 32-byte signal stored when
+     * the aggregated data was distributed. Both the optimistic nonce approval and
+     * the fallback approval sign with SIGHASH_DEFAULT (committing to every output)
+     * while the coordinator drives output selection, so without this check a
+     * coordinator could anchor a different signal under the member's signature.
+     */
+    #assertTxAnchorsValidatedSignal(cohortId, state, tx) {
+      const signalHex = state.validation?.signalBytesHex;
+      if (!signalHex) {
+        throw new AggregationParticipantError(
+          `Cohort ${cohortId} has no validated signal to bind the signature to.`,
+          "MISSING_STATE",
+          { cohortId }
+        );
+      }
+      if (!txEmbedsSignal(tx, signalHex)) {
+        throw new AggregationParticipantError(
+          `Transaction for cohort ${cohortId} does not anchor the validated signal.`,
+          "SIGNAL_MISMATCH",
+          { cohortId }
+        );
+      }
+    }
     /**
      * User action: approve signing and generate nonce contribution.
      */
@@ -104845,7 +105543,8 @@ a=end-of-candidates
           { cohortId }
         );
       }
-      const tx = Transaction.fromRaw(hexToBytes(state.signingRequest.pendingTxHex));
+      const tx = Transaction.fromRaw(hexToBytes(state.signingRequest.pendingTxHex), { allowUnknownOutputs: true });
+      this.#assertTxAnchorsValidatedSignal(cohortId, state, tx);
       const prevOutScripts = [hexToBytes(state.signingRequest.prevOutScriptHex)];
       const prevOutValues = [BigInt(state.signingRequest.prevOutValue)];
       const session = new BeaconSigningSession({
@@ -104881,7 +105580,7 @@ a=end-of-candidates
     }
     /**
      * User action: generate and return the partial signature.
-     * In most UIs this is automatic after AwaitingPartialSig — but exposing it
+     * In most UIs this is automatic after AwaitingPartialSig, but exposing it
      * as an explicit action lets the client UI confirm before signing if desired.
      */
     generatePartialSignature(cohortId) {
@@ -104913,6 +105612,83 @@ a=end-of-candidates
         partialSignature: partialSig
       })];
     }
+    /** Fallback signing requests awaiting user approval (UI: review the fallback spend). */
+    get pendingFallbackRequests() {
+      const map3 = /* @__PURE__ */ new Map();
+      for (const [id, state] of this.#cohortStates) {
+        if (state.phase === "AwaitingFallbackSig" /* AwaitingFallbackSig */ && state.fallbackRequest) {
+          map3.set(id, state.fallbackRequest);
+        }
+      }
+      return map3;
+    }
+    #handleFallbackAuthorizationRequest(message2) {
+      const cohortId = message2.body?.cohortId;
+      if (!cohortId) return;
+      const state = this.#cohortStates.get(cohortId);
+      if (!state || !state.cohort) return;
+      const acceptFrom = [
+        "ValidationSent" /* ValidationSent */,
+        "AwaitingSigning" /* AwaitingSigning */,
+        "NonceSent" /* NonceSent */,
+        "AwaitingPartialSig" /* AwaitingPartialSig */,
+        "Complete" /* Complete */
+      ];
+      if (!acceptFrom.includes(state.phase)) return;
+      const sessionId = message2.body?.sessionId;
+      const pendingTxHex = message2.body?.pendingTx;
+      const prevOutScriptHex = message2.body?.prevOutScriptHex;
+      const prevOutValue = message2.body?.prevOutValue;
+      const fallbackLeafScriptHex = message2.body?.fallbackLeafScriptHex;
+      if (!sessionId || !pendingTxHex || !prevOutScriptHex || !prevOutValue || !fallbackLeafScriptHex) return;
+      state.fallbackRequest = { cohortId, sessionId, pendingTxHex, prevOutScriptHex, prevOutValue, fallbackLeafScriptHex };
+      state.signingSession?.clearSecrets();
+      state.phase = "AwaitingFallbackSig" /* AwaitingFallbackSig */;
+    }
+    /**
+     * User action: authorize the fallback spend. Recomputes the k-of-n fallback
+     * leaf from the member's OWN cohort state (not the service-provided script),
+     * computes the BIP-341 script-path sighash over the requested transaction, and
+     * returns a standalone BIP-340 signature (no nonce round). The member completes
+     * once it has contributed; the service needs only k of these.
+     */
+    approveFallback(cohortId) {
+      const state = this.#cohortStates.get(cohortId);
+      if (!state || state.phase !== "AwaitingFallbackSig" /* AwaitingFallbackSig */) {
+        throw new AggregationParticipantError(
+          `Cannot approve fallback for cohort ${cohortId}: not in AwaitingFallbackSig phase.`,
+          "INVALID_PHASE",
+          { cohortId, phase: state?.phase }
+        );
+      }
+      if (!state.fallbackRequest || !state.cohort) {
+        throw new AggregationParticipantError(
+          `Cohort ${cohortId} missing fallback request or cohort state.`,
+          "MISSING_STATE",
+          { cohortId }
+        );
+      }
+      const req = state.fallbackRequest;
+      const tx = Transaction.fromRaw(hexToBytes(req.pendingTxHex), { allowUnknownOutputs: true });
+      const prevOutScript = hexToBytes(req.prevOutScriptHex);
+      const prevOutValue = BigInt(req.prevOutValue);
+      this.#assertTxAnchorsValidatedSignal(cohortId, state, tx);
+      const fallbackLeaf = buildFallbackLeaf({
+        cohortKeys: state.cohort.cohortKeys,
+        fallbackThreshold: state.cohort.effectiveFallbackThreshold
+      });
+      const sighash = fallbackSighash(tx, 0, prevOutScript, prevOutValue, fallbackLeaf);
+      const signature = this.#signer.withSecret((secretKey) => schnorr2.sign(sighash, secretKey));
+      state.phase = "Complete" /* Complete */;
+      return [createFallbackSignatureMessage({
+        from: this.did,
+        to: state.serviceDid,
+        cohortId,
+        sessionId: req.sessionId,
+        signerPk: this.publicKey.slice(1),
+        fallbackSignature: signature
+      })];
+    }
     getCohortPhase(cohortId) {
       return this.#cohortStates.get(cohortId)?.phase;
     }
@@ -104949,6 +105725,85 @@ a=end-of-candidates
     }
   };
 
+  // src/core/aggregation/recovery-spend.ts
+  init_shim();
+  init_secp256k1();
+  var DUST_LIMIT_SATS = 546n;
+  function bytesEqual2(a2, b) {
+    return a2.length === b.length && a2.every((x, i4) => x === b[i4]);
+  }
+  function buildRecoverySpend(params) {
+    const {
+      cohortKeys,
+      recoverySecretKey,
+      recoveryKey,
+      recoverySequence,
+      fallbackThreshold,
+      fundingModel,
+      network,
+      utxo,
+      destinationAddress,
+      fee,
+      beaconAddress
+    } = params;
+    if (cohortKeys.length === 0) {
+      throw new AggregationCohortError(
+        "Cannot build recovery spend: no cohort keys.",
+        "NO_COHORT_KEYS"
+      );
+    }
+    const derivedPub = schnorr2.getPublicKey(recoverySecretKey);
+    if (!bytesEqual2(derivedPub, recoveryKey)) {
+      throw new AggregationCohortError(
+        "Recovery secret key does not correspond to the committed recovery key.",
+        "RECOVERY_KEY_MISMATCH"
+      );
+    }
+    const out = utxo.value - fee;
+    if (out <= 0n) {
+      throw new AggregationCohortError(
+        `Recovery fee ${fee} exceeds UTXO value ${utxo.value}.`,
+        "FEE_EXCEEDS_VALUE",
+        { fee: fee.toString(), value: utxo.value.toString() }
+      );
+    }
+    if (out < DUST_LIMIT_SATS) {
+      throw new AggregationCohortError(
+        `Recovered output ${out} is below the dust limit ${DUST_LIMIT_SATS}; the spend would not relay.`,
+        "DUST_OUTPUT",
+        { output: out.toString(), dustLimit: DUST_LIMIT_SATS.toString() }
+      );
+    }
+    const internalKey = keyAggExport(keyAggregate(sortKeys(cohortKeys)));
+    const leaves = buildRecoveryLeaves(fundingModel ?? DEFAULT_FUNDING_MODEL, {
+      recoveryKey,
+      recoverySequence,
+      cohortKeys,
+      fallbackThreshold: resolveFallbackThreshold(fallbackThreshold, cohortKeys.length)
+    });
+    const net = getNetwork(network);
+    const payment = p2tr(internalKey, leaves, net, true);
+    if (beaconAddress !== void 0 && payment.address !== beaconAddress) {
+      throw new AggregationCohortError(
+        `Reconstructed beacon address ${payment.address} does not match the cohort's funded address ${beaconAddress}.`,
+        "BEACON_ADDRESS_MISMATCH",
+        { reconstructed: payment.address, expected: beaconAddress }
+      );
+    }
+    const tx = new Transaction({ version: 2, allowUnknownInputs: true });
+    tx.addInput({
+      txid: utxo.txid,
+      index: utxo.vout,
+      witnessUtxo: { script: payment.script, amount: utxo.value },
+      tapLeafScript: payment.tapLeafScript,
+      sequence: recoverySequence
+    });
+    tx.addOutputAddress(destinationAddress, out, net);
+    tx.signIdx(recoverySecretKey, 0);
+    tx.finalize();
+    return tx;
+  }
+
   // src/core/aggregation/logger.ts
   init_shim();
   var CONSOLE_LOGGER = {
@@ -104981,6 +105836,7 @@ a=end-of-candidates
   ]);
   var UPDATE_VALUES = /* @__PURE__ */ new Set([
     SUBMIT_UPDATE,
+    SUBMIT_NONINCLUDED,
     DISTRIBUTE_AGGREGATED_DATA,
     VALIDATION_ACK
   ]);
@@ -104988,7 +105844,9 @@ a=end-of-candidates
     AUTHORIZATION_REQUEST,
     NONCE_CONTRIBUTION,
     AGGREGATED_NONCE,
-    SIGNATURE_AUTHORIZATION
+    SIGNATURE_AUTHORIZATION,
+    FALLBACK_AUTHORIZATION_REQUEST,
+    FALLBACK_SIGNATURE
   ]);
   function isAggregationMessageType(type) {
     return KEYGEN_VALUES.has(type) || UPDATE_VALUES.has(type) || SIGN_VALUES.has(type);
@@ -111149,7 +112007,7 @@ ${value2}`;
      * backfill historical events to late subscribers: republishing gives late
      * joiners a window to discover the message without requiring protocol
      * changes. Relay rate-limit / publish failures inside the interval are
-     * caught and logged rather than propagated — the caller should stop the
+     * caught and logged rather than propagated - the caller should stop the
      * repeater once the protocol condition is satisfied.
      */
     publishRepeating(message2, sender, intervalMs, recipient) {
@@ -111603,35 +112461,29 @@ ${value2}`;
     session;
     #transport;
     #did;
-    #config;
+    #defaultConfig;
     #onOptInReceived;
     #onReadyToFinalize;
     #onProvideTxData;
     #cohortTtlMs;
     #phaseTimeoutMs;
     #advertRepeatIntervalMs;
-    #cohortId;
+    #autoFallbackOnStall;
+    /** Phases during which a stall can be salvaged by the k-of-n fallback (ADR 042). */
+    static #SIGNING_PHASES = [
+      "SigningStarted" /* SigningStarted */,
+      "NoncesCollected" /* NoncesCollected */,
+      "AwaitingPartialSigs" /* AwaitingPartialSigs */
+    ];
+    /** 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
@@ -111640,6 +112492,7 @@ ${value2}`;
       this.#cohortTtlMs = options2.cohortTtlMs;
       this.#phaseTimeoutMs = options2.phaseTimeoutMs;
       this.#advertRepeatIntervalMs = options2.advertRepeatIntervalMs ?? DEFAULT_ADVERT_REPEAT_INTERVAL_MS;
+      this.#autoFallbackOnStall = options2.autoFallbackOnStall ?? false;
       this.session = new AggregationService({
         // The coordinator never signs, so the state machine receives only the
         // public half of the operator's keypair (see ADR 038). The full keypair
@@ -111649,55 +112502,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,81 +112630,176 @@ ${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 phase = this.session.getCohortPhase(ctx.cohortId);
+        const inSigning = phase !== void 0 && _AggregationServiceRunner.#SIGNING_PHASES.includes(phase);
+        if (this.#autoFallbackOnStall && inSigning && !ctx.committedPath && !ctx.settled) {
+          this.triggerFallback(ctx.cohortId).catch((err) => this.#failCohort(ctx, err));
+          return;
+        }
+        const reason = `Cohort ${ctx.cohortId} stalled in phase ${ctx.lastObservedPhase ?? "?"} for ${this.#phaseTimeoutMs}ms`;
+        this.emit("cohort-failed", { cohortId: ctx.cohortId, reason });
+        this.#failCohort(ctx, new Error(reason));
       }, this.#phaseTimeoutMs);
     }
-    /** 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();
-      }
+    /**
+     * Abandon the optimistic n-of-n key path for a cohort and collect k-of-n
+     * fallback (script-path) signatures instead (ADR 042). Idempotent and safe
+     * against the optimistic completion: it commits the cohort to the fallback
+     * path synchronously (the `committedPath` latch) before sending anything, so a
+     * late optimistic signature can no longer complete-and-broadcast a competing
+     * spend of the same UTXO. No-op if the cohort is unknown, already settled, or
+     * already committed to a path.
+     *
+     * Wired automatically to the phase-stall timer when `autoFallbackOnStall` is
+     * set; otherwise call it from an operator decision (a UI "fall back now"
+     * action). Throws only if the underlying state machine rejects the transition
+     * (e.g. signing has not started).
+     */
+    async triggerFallback(cohortId) {
+      const ctx = this.#contexts.get(cohortId);
+      if (!ctx || ctx.settled || ctx.committedPath) return;
+      const messages2 = this.session.startFallbackSigning(cohortId);
+      ctx.committedPath = "fallback";
+      this.#stopAdvertRepeating(ctx);
+      this.#onPhaseMaybeChanged(ctx);
+      const sessionId = this.session.getSigningSessionId(cohortId) ?? "";
+      this.emit("fallback-started", { cohortId, sessionId });
+      await this.#sendAll(messages2);
+    }
+    /** 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;
     }
-    /** 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;
+    /**
+     * 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 = [
       COHORT_OPT_IN,
       SUBMIT_UPDATE,
+      SUBMIT_NONINCLUDED,
       VALIDATION_ACK,
       NONCE_CONTRIBUTION,
-      SIGNATURE_AUTHORIZATION
+      SIGNATURE_AUTHORIZATION,
+      FALLBACK_SIGNATURE
     ];
     /**
-     * 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;
       this.#handlersRegistered = true;
       this.#transport.registerMessageHandler(this.#did, COHORT_OPT_IN, this.#handleOptIn.bind(this));
       this.#transport.registerMessageHandler(this.#did, SUBMIT_UPDATE, this.#handleSubmitUpdate.bind(this));
+      this.#transport.registerMessageHandler(this.#did, SUBMIT_NONINCLUDED, this.#handleSubmitUpdate.bind(this));
       this.#transport.registerMessageHandler(this.#did, VALIDATION_ACK, this.#handleValidationAck.bind(this));
       this.#transport.registerMessageHandler(this.#did, NONCE_CONTRIBUTION, this.#handleNonceContribution.bind(this));
       this.#transport.registerMessageHandler(this.#did, SIGNATURE_AUTHORIZATION, this.#handleSignatureAuthorization.bind(this));
+      this.#transport.registerMessageHandler(this.#did, FALLBACK_SIGNATURE, this.#handleFallbackSignature.bind(this));
     }
     /** Internal: detach from the transport. Safe to call repeatedly. */
     #unregisterHandlers() {
@@ -111792,23 +112811,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 +112837,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 +112872,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 +112896,121 @@ ${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(ctx);
+        this.#onPhaseMaybeChanged(ctx);
+        if (ctx.committedPath === "fallback") return;
+        const result = this.session.getResult(ctx.cohortId);
+        if (result) {
+          ctx.committedPath = "optimistic";
+          this.#completeCohort(ctx, result);
+        }
+      } catch (err) {
+        this.#failCohort(ctx, err);
+      }
+    }
+    /**
+     * Handler for receiving fallback (k-of-n script-path) signatures. The state
+     * machine assembles and finalizes the fallback spend once k valid signatures
+     * are in; the result is then emitted and the cohort's completion resolves. The
+     * cohort is already committed to the fallback path (via {@link triggerFallback}).
+     * @param {BaseMessage} msg - The incoming FALLBACK_SIGNATURE message.
+     * @returns {Promise<void>} Resolves when handling is complete.
+     */
+    async #handleFallbackSignature(msg) {
+      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
@@ -112028,7 +113059,8 @@ ${value2}`;
       COHORT_READY,
       DISTRIBUTE_AGGREGATED_DATA,
       AUTHORIZATION_REQUEST,
-      AGGREGATED_NONCE
+      AGGREGATED_NONCE,
+      FALLBACK_AUTHORIZATION_REQUEST
     ];
     /** Internal: detach from the transport. Safe to call repeatedly. */
     #unregisterHandlers() {
@@ -112040,7 +113072,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 +113086,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.
@@ -112066,6 +113130,7 @@ ${value2}`;
       this.#transport.registerMessageHandler(this.#did, DISTRIBUTE_AGGREGATED_DATA, this.#handleDistributeData.bind(this));
       this.#transport.registerMessageHandler(this.#did, AUTHORIZATION_REQUEST, this.#handleAuthorizationRequest.bind(this));
       this.#transport.registerMessageHandler(this.#did, AGGREGATED_NONCE, this.#handleAggregatedNonce.bind(this));
+      this.#transport.registerMessageHandler(this.#did, FALLBACK_AUTHORIZATION_REQUEST, this.#handleFallbackAuthorizationRequest.bind(this));
     }
     /**
      * Internal: handler for cohort adverts. Applies the `shouldJoin` filter and joins if approved.
@@ -112121,8 +113186,13 @@ ${value2}`;
           cohortId,
           beaconAddress: info.beaconAddress
         });
-        await this.#sendAll(this.session.submitUpdate(cohortId, signedUpdate));
-        this.emit("update-submitted", { cohortId });
+        if (signedUpdate === null) {
+          await this.#sendAll(this.session.declineUpdate(cohortId));
+          this.emit("update-declined", { cohortId });
+        } else {
+          await this.#sendAll(this.session.submitUpdate(cohortId, signedUpdate));
+          this.emit("update-submitted", { cohortId });
+        }
       } catch (err) {
         this.emit("error", err);
       }
@@ -112198,23 +113268,62 @@ ${value2}`;
         const cohortId = msg.body?.cohortId;
         if (!cohortId) return;
         await this.#sendAll(this.session.generatePartialSignature(cohortId));
-        if (this.session.getCohortPhase(cohortId) === "Complete" /* Complete */) {
-          const info = this.session.joinedCohorts.get(cohortId);
-          if (info) {
-            const validation = this.session.pendingValidations.get(cohortId);
-            this.emit("cohort-complete", {
-              cohortId,
-              beaconAddress: info.beaconAddress,
-              beaconType: validation?.beaconType ?? "",
-              casAnnouncement: validation?.casAnnouncement,
-              smtProof: validation?.smtProof
-            });
-          }
+        this.#emitCohortCompleteIfDone(cohortId);
+      } catch (err) {
+        this.emit("error", err);
+      }
+    }
+    /**
+     * Internal: handler for fallback authorization requests. The service abandoned
+     * the optimistic key path; the member authorizes the k-of-n script-path spend
+     * of the same beacon transaction (ADR 042). Reuses `onApproveSigning` to gate
+     * the decision, signs the fallback, and completes once it has contributed (the
+     * service needs only k members).
+     * @param {BaseMessage} msg - The received fallback authorization request message.
+     * @returns {Promise<void>} Resolves when processing is complete.
+     */
+    async #handleFallbackAuthorizationRequest(msg) {
+      if (this.#stopped) return;
+      try {
+        this.session.receive(msg);
+        const cohortId = msg.body?.cohortId;
+        if (!cohortId) return;
+        const req = this.session.pendingFallbackRequests.get(cohortId);
+        if (!req) return;
+        this.emit("fallback-requested", req);
+        const decision = await this.#onApproveSigning(req);
+        if (!decision.approved) {
+          this.emit("cohort-failed", { cohortId, reason: "Fallback signing rejected by participant" });
+          return;
         }
+        await this.#sendAll(this.session.approveFallback(cohortId));
+        this.#emitCohortCompleteIfDone(cohortId);
       } catch (err) {
         this.emit("error", err);
       }
     }
+    /**
+     * Internal: emit `cohort-complete` with the participant's retained sidecar once
+     * the cohort has reached the Complete phase. Surfaces the CAS Announcement map
+     * (CAS beacons) or the SMT proof (SMT beacons) the participant keeps for future
+     * DID resolution. Read via getValidation (not pendingValidations, which lists
+     * only the AwaitingValidation phase) so the sidecar is still available at
+     * Complete. Shared by the optimistic and fallback completion paths.
+     */
+    #emitCohortCompleteIfDone(cohortId) {
+      if (this.session.getCohortPhase(cohortId) !== "Complete" /* Complete */) return;
+      const info = this.session.joinedCohorts.get(cohortId);
+      if (!info) return;
+      const validation = this.session.getValidation(cohortId);
+      this.emit("cohort-complete", {
+        cohortId,
+        beaconAddress: info.beaconAddress,
+        beaconType: validation?.beaconType ?? "",
+        included: validation?.included ?? true,
+        casAnnouncement: validation?.casAnnouncement,
+        smtProof: validation?.smtProof
+      });
+    }
     /**
      * Internal: send helper to ensure messages are sent sequentially. This is important for protocol
      * correctness, as some transports may not guarantee message order if sent in parallel.
@@ -112231,6 +113340,7 @@ ${value2}`;
 
   // src/core/aggregation/runner/aggregation-runner.ts
   init_shim();
+  init_utils();
   var AggregationRunner = class {
     /**
      * Run a cohort of ONE participant entirely in-process and return the
@@ -112238,8 +113348,8 @@ ${value2}`;
      *
      * One party plays both the coordinating service and the lone participant,
      * connected over an {@link InMemoryTransport} (no relay or HTTP server). This
-     * makes the single-participant aggregate-beacon path — the N=1 corner of the
-     * two-axis beacon matrix (see ADR 037) — first-class, useful for generating
+     * makes the single-participant aggregate-beacon path (the N=1 corner of the
+     * two-axis beacon matrix, see ADR 037) first-class, useful for generating
      * and reproducing single-participant aggregate test vectors.
      *
      * The service advertises a cohort with `minParticipants: 1`; the participant
@@ -112257,11 +113367,13 @@ ${value2}`;
       transport.registerPeer(options2.participant.did, options2.participant.keys.publicKey.compressed);
       transport.registerPeer(options2.service.did, options2.service.keys.publicKey.compressed);
       transport.start();
+      const recoveryKey = options2.config.recoveryKey ?? bytesToHex(options2.service.keys.publicKey.compressed.slice(1));
+      const recoverySequence = options2.config.recoverySequence ?? DEFAULT_RECOVERY_SEQUENCE;
       const service = new AggregationServiceRunner({
         transport,
         did: options2.service.did,
         keys: options2.service.keys,
-        config: { minParticipants: 1, network: options2.config.network, beaconType: options2.config.beaconType },
+        config: { minParticipants: 1, network: options2.config.network, beaconType: options2.config.beaconType, recoveryKey, recoverySequence, fundingModel: DEFAULT_FUNDING_MODEL },
         onProvideTxData: options2.onProvideTxData,
         cohortTtlMs: options2.cohortTtlMs,
         phaseTimeoutMs: options2.phaseTimeoutMs,
@@ -112391,8 +113503,7 @@ ${value2}`;
   async function buildAggregationBeaconTx(opts) {
     const feeEstimator = opts.feeEstimator ?? DEFAULT_FEE_ESTIMATOR;
     const { utxo, prevTxBytes } = await fetchSpendableUtxo(opts.beaconAddress, opts.bitcoin);
-    const tapOut = p2tr(opts.internalPubkey, void 0, opts.network);
-    const witnessScript = tapOut.script;
+    const witnessScript = OutScript.encode(Address(opts.network).decode(opts.beaconAddress));
     const feeSats = await feeEstimator.estimateFee(P2TR_BEACON_TX_VSIZE);
     if (BigInt(utxo.value) <= feeSats) {
       throw new BeaconError(
@@ -112471,7 +113582,7 @@ ${value2}`;
      *
      * Composed from the three extracted phases ({@link buildSinglePartyTx},
      * {@link signSinglePartyTx}, {@link broadcastRawTx}) so each piece can be exercised
-     * in isolation. Aggregation beacons use {@link buildAggregationBeaconTx} instead —
+     * in isolation. Aggregation beacons use {@link buildAggregationBeaconTx} instead:
      * the multi-party path can't share the signing phase, but the tx-construction
      * plumbing (UTXO fetch + OP_RETURN output + change output) is shared.
      *
@@ -112503,7 +113614,7 @@ ${value2}`;
      *
      * Detects the beacon address script kind (P2PKH / P2WPKH / P2TR) and configures
      * the input accordingly. Validates that the signer's pubkey produces the beacon
-     * address under that script kind — without this check, a misconfigured caller
+     * address under that script kind: without this check, a misconfigured caller
      * would burn a real UTXO on a tx that fails at broadcast. Fees are computed from
      * the per-kind {@link SINGLETON_BEACON_TX_VSIZE} constant, avoiding any probe-sign
      * round-trip.
@@ -128390,7 +129501,7 @@ ${value2}`;
     #verificationMethod;
     #beaconService;
     /**
-     * @internal — Use {@link DidBtcr2.update} to create instances.
+     * @internal Use {@link DidBtcr2.update} to create instances.
      */
     constructor(params) {
       this.#sourceDocument = params.sourceDocument;
@@ -128427,7 +129538,7 @@ ${value2}`;
       const targetDocument = JSONPatch.apply(sourceDocument, patches);
       if (targetDocument.id !== sourceDocument.id) {
         throw new UpdateError(
-          `Patches must not change the DID document id (source "${sourceDocument.id}" \u2192 target "${targetDocument.id}").`,
+          `Patches must not change the DID document id (source "${sourceDocument.id}" to target "${targetDocument.id}").`,
           INVALID_DID_UPDATE,
           { sourceId: sourceDocument.id, targetId: targetDocument.id }
         );
@@ -128511,8 +129622,8 @@ ${value2}`;
     }
     /**
      * Advance the state machine. Returns either:
-     * - `{ status: 'action-required', needs }` — caller must provide data via {@link provide}
-     * - `{ status: 'complete', result }` — update is signed and broadcast
+     * - `{ status: 'action-required', needs }` caller must provide data via {@link provide}
+     * - `{ status: 'complete', result }` update is signed and broadcast
      */
     advance() {
       while (true) {
@@ -128525,7 +129636,7 @@ ${value2}`;
             continue;
           }
           // Phase: Sign
-          // Emit NeedSigningKey — the caller supplies the secret key (or a KMS signature).
+          // Emit NeedSigningKey: the caller supplies the secret key (or a KMS signature).
           case "Sign": {
             return {
               status: "action-required",
@@ -128708,8 +129819,8 @@ ${value2}`;
      *
      * Factory method that validates the update parameters and returns a sans-I/O
      * {@link Updater} state machine. The caller drives the updater through its
-     * phases (Construct → Sign → Broadcast → Complete) by calling `advance()` and
-     * `provide()`. The method package performs **zero I/O** — signing key retrieval
+     * phases (Construct -> Sign -> Broadcast -> Complete) by calling `advance()` and
+     * `provide()`. The method package performs **zero I/O**: signing key retrieval
      * (or KMS delegation) and the on-chain broadcast are the caller's responsibility.
      *
      * For a fully-wired version with Bitcoin broadcast and key handling, see
@@ -128827,7 +129938,7 @@ ${value2}`;
     #unsortedUpdates = [];
     #resolvedResponse = null;
     /**
-     * @internal — Use {@link DidBtcr2.resolve} to create instances.
+     * @internal Use {@link DidBtcr2.resolve} to create instances.
      */
     constructor(didComponents, sidecarData, currentDocument, options2) {
       this.#didComponents = didComponents;
@@ -129063,8 +130174,8 @@ ${value2}`;
     }
     /**
      * Advance the state machine. Returns either:
-     * - `{ status: 'action-required', needs }` — caller must provide data via {@link provide}
-     * - `{ status: 'resolved', result }` — resolution complete
+     * - `{ status: 'action-required', needs }` - caller must provide data via {@link provide}
+     * - `{ status: 'resolved', result }` - resolution complete
      *
      * Analogous to Rust's `Resolver::resolve()`.
      */