@did-btcr2/method 0.36.0 → 0.37.0

package/dist/cjs/index.js

@@ -63,9 +63,11 @@ __export(index_exports, {
   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,
@@ -74,6 +76,8 @@ __export(index_exports, {
   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,
@@ -87,7 +91,9 @@ __export(index_exports, {
   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,
@@ -104,6 +110,7 @@ __export(index_exports, {
   SMTBeacon: () => SMTBeacon,
   SMTBeaconError: () => SMTBeaconError,
   SSE_EVENT: () => SSE_EVENT,
+  SUBMIT_NONINCLUDED: () => SUBMIT_NONINCLUDED,
   SUBMIT_UPDATE: () => SUBMIT_UPDATE,
   ServiceCohortPhase: () => ServiceCohortPhase,
   SigningSessionError: () => SigningSessionError,
@@ -112,6 +119,7 @@ __export(index_exports, {
   SingletonBeacon: () => SingletonBeacon,
   SingletonBeaconError: () => SingletonBeaconError,
   StaticFeeEstimator: () => StaticFeeEstimator,
+  TAPROOT_LEAF_VERSION: () => TAPROOT_LEAF_VERSION,
   TransportAdapterError: () => TransportAdapterError,
   TransportError: () => TransportError,
   TransportFactory: () => TransportFactory,
@@ -119,6 +127,11 @@ __export(index_exports, {
   Updater: () => Updater,
   VALIDATION_ACK: () => VALIDATION_ACK,
   buildAggregationBeaconTx: () => buildAggregationBeaconTx,
+  buildFallbackLeaf: () => buildFallbackLeaf,
+  buildFallbackSpend: () => buildFallbackSpend,
+  buildRecoveryLeaves: () => buildRecoveryLeaves,
+  buildRecoveryScript: () => buildRecoveryScript,
+  buildRecoverySpend: () => buildRecoverySpend,
   buildRequestAuth: () => buildRequestAuth,
   createAggregatedNonceMessage: () => createAggregatedNonceMessage,
   createAuthorizationRequestMessage: () => createAuthorizationRequestMessage,
@@ -127,13 +140,17 @@ __export(index_exports, {
   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,
@@ -145,10 +162,13 @@ __export(index_exports, {
   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,
@@ -157,8 +177,10 @@ __export(index_exports, {
   parseRequestAuth: () => parseRequestAuth,
   parseSseStream: () => parseSseStream,
   registerBeaconStrategy: () => registerBeaconStrategy,
+  resolveFallbackThreshold: () => resolveFallbackThreshold,
   reviveFromWire: () => reviveFromWire,
   signEnvelope: () => signEnvelope,
+  tapLeafHash: () => tapLeafHash,
   validateCohortConditions: () => validateCohortConditions,
   verifyEnvelope: () => verifyEnvelope,
   verifyRequestAuth: () => verifyRequestAuth
@@ -168,7 +190,8 @@ module.exports = __toCommonJS(index_exports);
 // src/core/aggregation/service.ts
 var import_common4 = require("@did-btcr2/common");
 var import_cryptosuite = require("@did-btcr2/cryptosuite");
-var import_utils2 = require("@noble/hashes/utils");
+var import_secp256k14 = require("@noble/curves/secp256k1.js");
+var import_utils3 = require("@noble/hashes/utils");
 
 // src/core/aggregation/beacon-strategy.ts
 var import_common = require("@did-btcr2/common");
@@ -181,9 +204,12 @@ var CAS_STRATEGY = {
   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
@@ -199,15 +225,20 @@ var SMT_STRATEGY = {
     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 = (0, import_smt.didToIndex)(participantDid);
+    if (!included) {
+      if (!smtProof?.nonce || smtProof?.updateId) return { matches: false, smtProof };
+      const candidateHash2 = (0, import_smt.blockHash)((0, import_smt.blockHash)((0, import_smt.base64UrlToHash)(smtProof.nonce)));
+      return { matches: (0, import_smt.verifySerializedProof)(smtProof, index, candidateHash2), smtProof };
+    }
+    if (!smtProof?.updateId || !smtProof?.nonce || !submittedUpdate) return { matches: false, smtProof };
     const canonicalBytes = new TextEncoder().encode((0, import_common.canonicalize)(submittedUpdate));
     const expectedUpdateId = (0, import_smt.hashToBase64Url)((0, import_smt.blockHash)(canonicalBytes));
     if (smtProof.updateId !== expectedUpdateId) {
       return { matches: false, smtProof };
     }
-    const index = (0, import_smt.didToIndex)(participantDid);
     const candidateHash = (0, import_smt.blockHash)((0, import_smt.blockHash)((0, import_smt.base64UrlToHash)(smtProof.nonce)), (0, import_smt.base64UrlToHash)(smtProof.updateId));
     return {
       matches: (0, import_smt.verifySerializedProof)(smtProof, index, candidateHash),
@@ -230,10 +261,10 @@ function getBeaconStrategy(type) {
 var import_bitcoin = require("@did-btcr2/bitcoin");
 var import_common3 = require("@did-btcr2/common");
 var import_smt2 = require("@did-btcr2/smt");
-var import_secp256k1 = require("@noble/curves/secp256k1.js");
-var import_utils = require("@noble/hashes/utils");
-var import_btc_signer = require("@scure/btc-signer");
-var import_musig2 = require("@scure/btc-signer/musig2");
+var import_secp256k12 = require("@noble/curves/secp256k1.js");
+var import_utils2 = require("@noble/hashes/utils");
+var import_btc_signer2 = require("@scure/btc-signer");
+var import_musig22 = require("@scure/btc-signer/musig2");
 
 // src/core/aggregation/errors.ts
 var import_common2 = require("@did-btcr2/common");
@@ -258,6 +289,105 @@ var SigningSessionError = class extends import_common2.MethodError {
   }
 };
 
+// src/core/aggregation/recovery-policy.ts
+var import_secp256k1 = require("@noble/curves/secp256k1.js");
+var import_utils = require("@noble/hashes/utils");
+var import_btc_signer = require("@scure/btc-signer");
+var import_musig2 = require("@scure/btc-signer/musig2");
+var DEFAULT_FUNDING_MODEL = "operator-funded";
+var DEFAULT_RECOVERY_SEQUENCE = 144;
+var MAX_RECOVERY_SEQUENCE = 65535;
+var TAPROOT_LEAF_VERSION = 192;
+function compactSize(n) {
+  if (n < 253) return new Uint8Array([n]);
+  if (n <= 65535) return new Uint8Array([253, n & 255, n >> 8 & 255]);
+  return new Uint8Array([254, n & 255, n >> 8 & 255, n >> 16 & 255, n >> 24 & 255]);
+}
+function tapLeafHash(script, leafVersion = TAPROOT_LEAF_VERSION) {
+  return import_secp256k1.schnorr.utils.taggedHash(
+    "TapLeaf",
+    (0, import_utils.concatBytes)(new Uint8Array([leafVersion]), compactSize(script.length), script)
+  );
+}
+function resolveFallbackThreshold(advertised, n) {
+  return advertised ?? Math.max(1, n - 1);
+}
+function assertFallbackParams({ cohortKeys, fallbackThreshold }) {
+  const n = cohortKeys.length;
+  if (n === 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 > n) {
+    throw new AggregationCohortError(
+      `Fallback threshold must be an integer in [1, ${n}] (k-of-n), got ${fallbackThreshold}.`,
+      "INVALID_FALLBACK_THRESHOLD",
+      { fallbackThreshold, n }
+    );
+  }
+}
+function buildFallbackLeaf(params) {
+  assertFallbackParams(params);
+  const xOnlyKeys = (0, import_musig2.sortKeys)(params.cohortKeys).map((k) => k.slice(1));
+  return (0, import_btc_signer.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 import_btc_signer.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. */
@@ -273,8 +403,8 @@ var AggregationCohort = class {
   /** 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.
    */
@@ -282,16 +412,41 @@ var AggregationCohort = class {
   /** 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;
@@ -301,23 +456,45 @@ var AggregationCohort = class {
   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() {
     return this.#cohortKeys;
   }
   set cohortKeys(keys) {
-    this.#cohortKeys = (0, import_musig2.sortKeys)(keys);
+    this.#cohortKeys = (0, import_musig22.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) {
@@ -327,10 +504,25 @@ var AggregationCohort = class {
         { cohortId: this.id }
       );
     }
-    const keyAggContext = (0, import_musig2.keyAggregate)(this.#cohortKeys);
-    const aggPubkey = (0, import_musig2.keyAggExport)(keyAggContext);
-    const payment = (0, import_btc_signer.p2tr)(aggPubkey, void 0, (0, import_bitcoin.getNetwork)(this.network));
-    this.tapTweak = import_secp256k1.schnorr.utils.taggedHash("TapTweak", aggPubkey);
+    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 = (0, import_musig22.keyAggregate)(this.#cohortKeys);
+    const aggPubkey = (0, import_musig22.keyAggExport)(keyAggContext);
+    const leaves = buildRecoveryLeaves(this.fundingModel, {
+      recoveryKey: this.recoveryKey,
+      recoverySequence: this.recoverySequence,
+      cohortKeys: this.#cohortKeys,
+      fallbackThreshold: resolveFallbackThreshold(this.fallbackThreshold, this.#cohortKeys.length)
+    });
+    const payment = (0, import_btc_signer2.p2tr)(aggPubkey, leaves, (0, import_bitcoin.getNetwork)(this.network), true);
+    this.internalKey = aggPubkey;
+    this.tapMerkleRoot = payment.tapMerkleRoot;
+    this.tapTweak = import_secp256k12.schnorr.utils.taggedHash("TapTweak", (0, import_utils2.concatBytes)(aggPubkey, payment.tapMerkleRoot));
     if (!payment.address) {
       throw new AggregationCohortError(
         "Failed to compute Taproot address",
@@ -354,7 +546,7 @@ var AggregationCohort = class {
         { cohortId: this.id, participantPkHex }
       );
     }
-    this.cohortKeys = cohortKeysHex.map((k) => (0, import_utils.hexToBytes)(k));
+    this.cohortKeys = cohortKeysHex.map((k) => (0, import_utils2.hexToBytes)(k));
     const computed = this.computeBeaconAddress();
     if (computed !== expectedBeaconAddress) {
       throw new AggregationCohortError(
@@ -386,20 +578,54 @@ var AggregationCohort = class {
     }
     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 = {};
@@ -411,31 +637,41 @@ var AggregationCohort = class {
     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 tree = new import_smt2.BTCR2MerkleTree();
     const entries = [];
     const encoder = new TextEncoder();
-    for (const [did, signedUpdate] of this.pendingUpdates) {
-      const canonicalBytes = encoder.encode((0, import_common3.canonicalize)(signedUpdate));
-      const nonce = (0, import_utils.randomBytes)(32);
-      entries.push({ did, nonce, signedUpdate: canonicalBytes });
+    for (const did of this.participants) {
+      const nonce = (0, import_utils2.randomBytes)(32);
+      const signedUpdate = this.pendingUpdates.get(did);
+      if (signedUpdate) {
+        entries.push({ did, nonce, signedUpdate: encoder.encode((0, import_common3.canonicalize)(signedUpdate)) });
+      } else {
+        entries.push({ did, nonce });
+      }
     }
     tree.addEntries(entries);
     tree.finalize();
     this.signalBytes = tree.rootHash;
     this.smtProofs = /* @__PURE__ */ new Map();
-    for (const [did] of this.pendingUpdates) {
+    for (const did of this.participants) {
       this.smtProofs.set(did, tree.proof(did));
     }
     return this.smtProofs;
@@ -461,7 +697,7 @@ var AggregationCohort = class {
     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() {
@@ -471,6 +707,7 @@ var AggregationCohort = class {
 
 // src/core/aggregation/conditions.ts
 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`);
@@ -514,11 +751,130 @@ function validateCohortConditions(c) {
   if (c.pendingUpdateTrigger !== void 0 && (!Number.isInteger(c.pendingUpdateTrigger) || c.pendingUpdateTrigger < 1)) {
     problems.push("pendingUpdateTrigger must be an integer >= 1");
   }
+  if (c.fallbackThreshold !== void 0) {
+    if (!Number.isInteger(c.fallbackThreshold) || c.fallbackThreshold < 1) {
+      problems.push("fallbackThreshold must be an integer >= 1");
+    } else if (c.maxParticipants !== void 0 && Number.isInteger(c.maxParticipants) && c.fallbackThreshold > c.maxParticipants) {
+      problems.push("fallbackThreshold must be <= maxParticipants");
+    }
+  }
   checkCost(problems, "costOfEnrollment", c.costOfEnrollment);
   checkCost(problems, "costPerAnnouncement", c.costPerAnnouncement);
+  if (typeof c.recoveryKey !== "string" || !/^[0-9a-fA-F]{64}$/.test(c.recoveryKey)) {
+    problems.push("recoveryKey must be a 64-character hex string (x-only public key)");
+  }
+  if (!Number.isInteger(c.recoverySequence) || c.recoverySequence < 1 || c.recoverySequence > MAX_RECOVERY_SEQUENCE) {
+    problems.push(`recoverySequence must be a block-based BIP-68 relative timelock in [1, ${MAX_RECOVERY_SEQUENCE}]`);
+  }
+  if (c.fundingModel !== void 0 && !KNOWN_FUNDING_MODELS.includes(c.fundingModel)) {
+    problems.push(`fundingModel must be one of ${KNOWN_FUNDING_MODELS.join(", ")}`);
+  }
   return problems;
 }
 
+// src/core/aggregation/fallback-spend.ts
+var import_bitcoin2 = require("@did-btcr2/bitcoin");
+var import_secp256k13 = require("@noble/curves/secp256k1.js");
+var import_btc_signer3 = require("@scure/btc-signer");
+var import_musig23 = require("@scure/btc-signer/musig2");
+function bytesEqual(a, b) {
+  return a.length === b.length && a.every((x, i) => x === b[i]);
+}
+function fallbackSighash(tx, inputIndex, prevOutScript, prevOutValue, fallbackLeafScript) {
+  return tx.preimageWitnessV1(
+    inputIndex,
+    [prevOutScript],
+    import_btc_signer3.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 = (0, import_musig23.keyAggExport)((0, import_musig23.keyAggregate)((0, import_musig23.sortKeys)(cohortKeys)));
+  const leaves = buildRecoveryLeaves(fundingModel ?? DEFAULT_FUNDING_MODEL, {
+    recoveryKey,
+    recoverySequence,
+    cohortKeys,
+    fallbackThreshold
+  });
+  const net = (0, import_bitcoin2.getNetwork)(network);
+  const payment = (0, import_btc_signer3.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 = (0, import_musig23.sortKeys)(cohortKeys).map((k) => k.slice(1));
+  const tx = pendingTx;
+  const sighash = fallbackSighash(tx, inputIndex, prevOutScript, prevOutValue, fallbackLeaf);
+  const leafHash = tapLeafHash(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 hex = Array.from(pubKey, (b) => b.toString(16).padStart(2, "0")).join("");
+    if (accepted.has(hex)) continue;
+    let ok = false;
+    try {
+      ok = import_secp256k13.schnorr.verify(signature, sighash, pubKey);
+    } catch {
+      ok = false;
+    }
+    if (ok) accepted.set(hex, 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 hex = Array.from(pubKey, (b) => b.toString(16).padStart(2, "0")).join("");
+      return [{ pubKey, leafHash }, accepted.get(hex)];
+    })
+  });
+  tx.finalize();
+  return tx;
+}
+
 // src/core/aggregation/messages/base.ts
 var AGGREGATION_WIRE_VERSION = 1;
 var BaseMessage = class {
@@ -556,12 +912,15 @@ var COHORT_OPT_IN = `${AGGREGATION_MESSAGE_PREFIX}/keygen/cohort_opt_in`;
 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
 function createCohortAdvertMessage(fields) {
@@ -584,6 +943,10 @@ function createSubmitUpdateMessage(fields) {
   const { from: from2, to, ...body } = fields;
   return new BaseMessage({ type: SUBMIT_UPDATE, from: from2, to, body });
 }
+function createSubmitNonIncludedMessage(fields) {
+  const { from: from2, to, ...body } = fields;
+  return new BaseMessage({ type: SUBMIT_NONINCLUDED, from: from2, to, body });
+}
 function createDistributeAggregatedDataMessage(fields) {
   const { from: from2, to, ...body } = fields;
   return new BaseMessage({ type: DISTRIBUTE_AGGREGATED_DATA, from: from2, to, body });
@@ -608,6 +971,14 @@ function createSignatureAuthorizationMessage(fields) {
   const { from: from2, to, ...body } = fields;
   return new BaseMessage({ type: SIGNATURE_AUTHORIZATION, from: from2, to, body });
 }
+function createFallbackAuthorizationRequestMessage(fields) {
+  const { from: from2, to, ...body } = fields;
+  return new BaseMessage({ type: FALLBACK_AUTHORIZATION_REQUEST, from: from2, to, body });
+}
+function createFallbackSignatureMessage(fields) {
+  const { from: from2, to, ...body } = fields;
+  return new BaseMessage({ type: FALLBACK_SIGNATURE, from: from2, to, body });
+}
 
 // src/core/aggregation/phases.ts
 var ServiceCohortPhase = /* @__PURE__ */ ((ServiceCohortPhase2) => {
@@ -621,6 +992,7 @@ var ServiceCohortPhase = /* @__PURE__ */ ((ServiceCohortPhase2) => {
   ServiceCohortPhase2["SigningStarted"] = "SigningStarted";
   ServiceCohortPhase2["NoncesCollected"] = "NoncesCollected";
   ServiceCohortPhase2["AwaitingPartialSigs"] = "AwaitingPartialSigs";
+  ServiceCohortPhase2["FallbackRequested"] = "FallbackRequested";
   ServiceCohortPhase2["Complete"] = "Complete";
   ServiceCohortPhase2["Failed"] = "Failed";
   return ServiceCohortPhase2;
@@ -630,11 +1002,13 @@ var ParticipantCohortPhase = /* @__PURE__ */ ((ParticipantCohortPhase2) => {
   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;
@@ -651,7 +1025,7 @@ var SigningSessionPhase = /* @__PURE__ */ ((SigningSessionPhase2) => {
 
 // src/core/aggregation/signing-session.ts
 var import_keypair = require("@did-btcr2/keypair");
-var import_btc_signer2 = require("@scure/btc-signer");
+var import_btc_signer4 = require("@scure/btc-signer");
 var musig2 = __toESM(require("@scure/btc-signer/musig2"), 1);
 var BeaconSigningSession = class {
   /** Unique identifier for this signing session. */
@@ -664,11 +1038,11 @@ var BeaconSigningSession = class {
   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;
@@ -703,7 +1077,7 @@ var BeaconSigningSession = class {
     return this.pendingTx.preimageWitnessV1(
       0,
       this.prevOutScripts,
-      import_btc_signer2.SigHash.DEFAULT,
+      import_btc_signer4.SigHash.DEFAULT,
       this.prevOutValues
     );
   }
@@ -851,7 +1225,7 @@ var BeaconSigningSession = class {
       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 musig2.Session(
       this.aggregatedNonce,
@@ -921,6 +1295,9 @@ var AggregationService = class {
       case SUBMIT_UPDATE:
         this.#handleSubmitUpdate(message);
         break;
+      case SUBMIT_NONINCLUDED:
+        this.#handleSubmitNonInclusion(message);
+        break;
       case VALIDATION_ACK:
         this.#handleValidationAck(message);
         break;
@@ -930,6 +1307,9 @@ var AggregationService = class {
       case SIGNATURE_AUTHORIZATION:
         this.#handleSignatureAuthorization(message);
         break;
+      case FALLBACK_SIGNATURE:
+        this.#handleFallbackSignature(message);
+        break;
       default:
         break;
     }
@@ -948,7 +1328,7 @@ var AggregationService = class {
   }
   /**
    * 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);
@@ -963,7 +1343,11 @@ var AggregationService = class {
       serviceDid: this.did,
       minParticipants: config.minParticipants,
       network: config.network,
-      beaconType: config.beaconType
+      beaconType: config.beaconType,
+      recoveryKey: (0, import_utils3.hexToBytes)(config.recoveryKey),
+      recoverySequence: config.recoverySequence,
+      fundingModel: config.fundingModel,
+      fallbackThreshold: config.fallbackThreshold
     });
     this.#cohortStates.set(cohort.id, {
       phase: "Created" /* Created */,
@@ -1164,11 +1548,64 @@ var AggregationService = class {
       });
       return;
     }
+    if (state.cohort.nonIncluded.has(message.from)) {
+      state.rejections.push({
+        from: message.from,
+        code: "UPDATE_MALFORMED",
+        reason: "Participant already declined this round; cannot also submit an update"
+      });
+      return;
+    }
+    if (state.cohort.pendingUpdates.has(message.from)) {
+      state.rejections.push({
+        from: message.from,
+        code: "UPDATE_MALFORMED",
+        reason: "Participant already submitted an update this round; cannot resubmit"
+      });
+      return;
+    }
     state.cohort.addUpdate(message.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(message) {
+    const cohortId = message.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(message.from)) {
+      state.rejections.push({
+        from: message.from,
+        code: "UPDATE_MALFORMED",
+        reason: "Sender is not a member of this cohort"
+      });
+      return;
+    }
+    if (state.cohort.pendingUpdates.has(message.from) || state.cohort.nonIncluded.has(message.from)) {
+      state.rejections.push({
+        from: message.from,
+        code: "UPDATE_MALFORMED",
+        reason: "Participant already responded this round"
+      });
+      return;
+    }
+    state.cohort.addNonInclusion(message.from);
+    if (state.phase === "CohortSet" /* CohortSet */) {
+      state.phase = "CollectingUpdates" /* CollectingUpdates */;
+    }
+    if (state.cohort.hasAllResponses()) {
       state.phase = "UpdatesCollected" /* UpdatesCollected */;
     }
   }
@@ -1227,7 +1664,7 @@ var AggregationService = class {
       );
     }
     strategy.buildAggregatedData(state.cohort);
-    const signalBytesHex = (0, import_utils2.bytesToHex)(state.cohort.signalBytes);
+    const signalBytesHex = (0, import_utils3.bytesToHex)(state.cohort.signalBytes);
     state.phase = "DataDistributed" /* DataDistributed */;
     const messages = [];
     for (const participantDid of state.cohort.participants) {
@@ -1278,7 +1715,7 @@ var AggregationService = class {
   }
   /**
    * 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) {
@@ -1317,7 +1754,7 @@ var AggregationService = class {
         cohortId,
         sessionId: session.id,
         pendingTx: txData.tx.hex,
-        prevOutScriptHex: (0, import_utils2.bytesToHex)(prevOutScript),
+        prevOutScriptHex: (0, import_utils3.bytesToHex)(prevOutScript),
         prevOutValue: txData.prevOutValues[0]?.toString() ?? "0"
       }));
     }
@@ -1385,11 +1822,144 @@ var AggregationService = class {
       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 messages = [];
+    for (const participantDid of state.cohort.participants) {
+      messages.push(createFallbackAuthorizationRequestMessage({
+        from: this.did,
+        to: participantDid,
+        cohortId,
+        sessionId: session.id,
+        pendingTx: session.pendingTx.hex,
+        prevOutScriptHex: (0, import_utils3.bytesToHex)(prevOutScript),
+        prevOutValue: prevOutValue.toString(),
+        fallbackLeafScriptHex: (0, import_utils3.bytesToHex)(fallbackLeaf)
+      }));
+    }
+    return messages;
+  }
+  /**
+   * 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(message) {
+    const cohortId = message.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 = message.body?.sessionId;
+    if (sessionId !== state.signingSession.id) return;
+    const signerPk = message.body?.signerPk;
+    const fallbackSignature = message.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(message.from);
+    if (!memberKey) {
+      state.rejections.push({ from: message.from, code: "UPDATE_MALFORMED", reason: "Fallback signature from a non-member" });
+      return;
+    }
+    const memberXOnly = memberKey.slice(1);
+    if (signerPk.length !== 32 || !memberXOnly.every((b, i) => b === signerPk[i])) {
+      state.rejections.push({ from: message.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 && import_secp256k14.schnorr.verify(fallbackSignature, sighash, signerPk);
+    } catch {
+      valid = false;
+    }
+    if (!valid) {
+      state.rejections.push({ from: message.from, code: "UPDATE_VERIFICATION_FAILED", reason: "Fallback signature failed verification" });
+      return;
+    }
+    state.fallbackSignatures.set(message.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;
   }
@@ -1421,8 +1991,9 @@ var AggregationService = class {
 
 // src/core/aggregation/participant.ts
 var import_common5 = require("@did-btcr2/common");
-var import_utils3 = require("@noble/hashes/utils");
-var import_btc_signer3 = require("@scure/btc-signer");
+var import_secp256k15 = require("@noble/curves/secp256k1.js");
+var import_utils4 = require("@noble/hashes/utils");
+var import_btc_signer5 = require("@scure/btc-signer");
 
 // src/core/aggregation/messages/bodies.ts
 var hasStr = (b, k) => !!b && typeof b[k] === "string";
@@ -1434,6 +2005,14 @@ var optIntMin = (b, k, min) => {
   const v = b ? b[k] : void 0;
   return v === void 0 || typeof v === "number" && Number.isInteger(v) && v >= min;
 };
+var 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) => {
@@ -1441,7 +2020,7 @@ var hasBytesArray = (b, k) => {
   return Array.isArray(v) && v.every((x) => x instanceof Uint8Array);
 };
 function isCohortAdvertMessage(m) {
-  return m.type === COHORT_ADVERT && hasStr(m.body, "cohortId") && hasIntMin(m.body, "minParticipants", 1) && optIntMin(m.body, "maxParticipants", 1) && hasStr(m.body, "beaconType") && hasStr(m.body, "network") && hasBytes(m.body, "communicationPk");
+  return m.type === COHORT_ADVERT && hasStr(m.body, "cohortId") && hasIntMin(m.body, "minParticipants", 1) && optIntMin(m.body, "maxParticipants", 1) && hasStr(m.body, "beaconType") && hasStr(m.body, "network") && hasStr(m.body, "recoveryKey") && intInRange(m.body, "recoverySequence", 1, MAX_RECOVERY_SEQUENCE) && optStrOneOf(m.body, "fundingModel", KNOWN_FUNDING_MODELS) && optIntMin(m.body, "fallbackThreshold", 1) && hasBytes(m.body, "communicationPk");
 }
 function isCohortOptInMessage(m) {
   return m.type === COHORT_OPT_IN && hasStr(m.body, "cohortId") && hasBytes(m.body, "participantPk") && hasBytes(m.body, "communicationPk");
@@ -1455,6 +2034,9 @@ function isCohortReadyMessage(m) {
 function isSubmitUpdateMessage(m) {
   return m.type === SUBMIT_UPDATE && hasStr(m.body, "cohortId") && !!m.body && typeof m.body.signedUpdate === "object";
 }
+function isSubmitNonIncludedMessage(m) {
+  return m.type === SUBMIT_NONINCLUDED && hasStr(m.body, "cohortId");
+}
 function isDistributeAggregatedDataMessage(m) {
   return m.type === DISTRIBUTE_AGGREGATED_DATA && hasStr(m.body, "cohortId") && hasStr(m.body, "beaconType") && hasStr(m.body, "signalBytesHex");
 }
@@ -1473,8 +2055,38 @@ function isAggregatedNonceMessage(m) {
 function isSignatureAuthorizationMessage(m) {
   return m.type === SIGNATURE_AUTHORIZATION && hasStr(m.body, "cohortId") && hasStr(m.body, "sessionId") && hasBytes(m.body, "partialSignature");
 }
+function isFallbackAuthorizationRequestMessage(m) {
+  return m.type === FALLBACK_AUTHORIZATION_REQUEST && hasStr(m.body, "cohortId") && hasStr(m.body, "sessionId") && hasStr(m.body, "pendingTx") && hasStr(m.body, "prevOutScriptHex") && hasStr(m.body, "prevOutValue") && hasStr(m.body, "fallbackLeafScriptHex");
+}
+function isFallbackSignatureMessage(m) {
+  return m.type === FALLBACK_SIGNATURE && hasStr(m.body, "cohortId") && hasStr(m.body, "sessionId") && hasBytes(m.body, "signerPk") && hasBytes(m.body, "fallbackSignature");
+}
 
 // src/core/aggregation/participant.ts
+function txEmbedsSignal(tx, signalHex) {
+  let expected;
+  try {
+    expected = (0, import_utils4.hexToBytes)(signalHex);
+  } catch {
+    return false;
+  }
+  if (expected.length === 0) return false;
+  for (let i = 0; i < tx.outputsLength; i++) {
+    const script = tx.getOutput(i)?.script;
+    if (!script) continue;
+    let decoded;
+    try {
+      decoded = import_btc_signer5.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. */
@@ -1491,7 +2103,7 @@ var AggregationParticipant = class {
   }
   /**
    * 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(message) {
     if (message.version === void 0 || message.version !== AGGREGATION_WIRE_VERSION) {
@@ -1517,6 +2129,9 @@ var AggregationParticipant = class {
       case AGGREGATED_NONCE:
         this.#handleAggregatedNonce(message);
         break;
+      case FALLBACK_AUTHORIZATION_REQUEST:
+        this.#handleFallbackAuthorizationRequest(message);
+        break;
       default:
         break;
     }
@@ -1562,12 +2177,17 @@ var AggregationParticipant = class {
         { 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 ? (0, import_utils4.hexToBytes)(advert.recoveryKey) : void 0,
+      recoverySequence: advert.recoverySequence,
+      fundingModel: advert.fundingModel,
+      fallbackThreshold: advert.fallbackThreshold
     });
     state.cohort = cohort;
     state.phase = "OptedIn" /* OptedIn */;
@@ -1583,7 +2203,7 @@ var AggregationParticipant = class {
   #handleOptInAccept(message) {
     void message;
   }
-  /** Cohorts that have been finalized — beacon address available. */
+  /** Cohorts that have been finalized: beacon address available. */
   get joinedCohorts() {
     const map = /* @__PURE__ */ new Map();
     for (const [id, state] of this.#cohortStates) {
@@ -1607,8 +2227,8 @@ var AggregationParticipant = class {
     const beaconAddress = message.body?.beaconAddress;
     const cohortKeys = message.body?.cohortKeys;
     if (!beaconAddress || !cohortKeys) return;
-    const participantPkHex = (0, import_utils3.bytesToHex)(this.publicKey);
-    const cohortKeysHex = cohortKeys.map((k) => (0, import_utils3.bytesToHex)(new Uint8Array(k)));
+    const participantPkHex = (0, import_utils4.bytesToHex)(this.publicKey);
+    const cohortKeysHex = cohortKeys.map((k) => (0, import_utils4.bytesToHex)(new Uint8Array(k)));
     state.cohort.validateMembership(participantPkHex, cohortKeysHex, beaconAddress);
     state.phase = "CohortReady" /* CohortReady */;
   }
@@ -1626,6 +2246,7 @@ var AggregationParticipant = class {
       );
     }
     state.submittedUpdate = signedUpdate;
+    state.included = true;
     state.phase = "UpdateSubmitted" /* UpdateSubmitted */;
     const message = createSubmitUpdateMessage({
       from: this.did,
@@ -1635,6 +2256,30 @@ var AggregationParticipant = class {
     });
     return [message];
   }
+  /**
+   * 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 message = createSubmitNonIncludedMessage({
+      from: this.did,
+      to: state.serviceDid,
+      cohortId
+    });
+    return [message];
+  }
   /** Aggregated data awaiting user validation. */
   get pendingValidations() {
     const map = /* @__PURE__ */ new Map();
@@ -1645,22 +2290,35 @@ var AggregationParticipant = class {
     }
     return map;
   }
+  /**
+   * The validated aggregated data retained for a cohort, regardless of phase.
+   * Unlike {@link pendingValidations} (which lists only cohorts still awaiting
+   * the validate decision), this returns the stored validation, including the
+   * participant's sidecar (the CAS Announcement map or its SMT inclusion proof),
+   * so it is still readable once the cohort reaches Complete. Returns
+   * undefined before aggregated data has been received.
+   */
+  getValidation(cohortId) {
+    return this.#cohortStates.get(cohortId)?.validation;
+  }
   #handleDistributeAggregatedData(message) {
     const cohortId = message.body?.cohortId;
     if (!cohortId) return;
     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 = message.body?.beaconType;
     if (!beaconType) return;
     const strategy = getBeaconStrategy(beaconType);
     if (!strategy) return;
     const signalBytesHex = message.body?.signalBytesHex ?? "";
-    const expectedHash = (0, import_common5.canonicalHash)(state.submittedUpdate);
+    const expectedHash = declined ? "" : (0, import_common5.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: message.body
     });
     state.validation = {
@@ -1670,7 +2328,8 @@ var AggregationParticipant = class {
       expectedHash,
       matches: result.matches,
       casAnnouncement: result.casAnnouncement,
-      smtProof: result.smtProof
+      smtProof: result.smtProof,
+      included: !declined
     };
     state.phase = "AwaitingValidation" /* AwaitingValidation */;
   }
@@ -1744,6 +2403,31 @@ var AggregationParticipant = class {
     };
     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.
    */
@@ -1763,8 +2447,9 @@ var AggregationParticipant = class {
         { cohortId }
       );
     }
-    const tx = import_btc_signer3.Transaction.fromRaw((0, import_utils3.hexToBytes)(state.signingRequest.pendingTxHex));
-    const prevOutScripts = [(0, import_utils3.hexToBytes)(state.signingRequest.prevOutScriptHex)];
+    const tx = import_btc_signer5.Transaction.fromRaw((0, import_utils4.hexToBytes)(state.signingRequest.pendingTxHex), { allowUnknownOutputs: true });
+    this.#assertTxAnchorsValidatedSignal(cohortId, state, tx);
+    const prevOutScripts = [(0, import_utils4.hexToBytes)(state.signingRequest.prevOutScriptHex)];
     const prevOutValues = [BigInt(state.signingRequest.prevOutValue)];
     const session = new BeaconSigningSession({
       id: state.signingRequest.sessionId,
@@ -1799,7 +2484,7 @@ var AggregationParticipant = class {
   }
   /**
    * 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) {
@@ -1831,6 +2516,83 @@ var AggregationParticipant = class {
       partialSignature: partialSig
     })];
   }
+  /** Fallback signing requests awaiting user approval (UI: review the fallback spend). */
+  get pendingFallbackRequests() {
+    const map = /* @__PURE__ */ new Map();
+    for (const [id, state] of this.#cohortStates) {
+      if (state.phase === "AwaitingFallbackSig" /* AwaitingFallbackSig */ && state.fallbackRequest) {
+        map.set(id, state.fallbackRequest);
+      }
+    }
+    return map;
+  }
+  #handleFallbackAuthorizationRequest(message) {
+    const cohortId = message.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 = message.body?.sessionId;
+    const pendingTxHex = message.body?.pendingTx;
+    const prevOutScriptHex = message.body?.prevOutScriptHex;
+    const prevOutValue = message.body?.prevOutValue;
+    const fallbackLeafScriptHex = message.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 = import_btc_signer5.Transaction.fromRaw((0, import_utils4.hexToBytes)(req.pendingTxHex), { allowUnknownOutputs: true });
+    const prevOutScript = (0, import_utils4.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) => import_secp256k15.schnorr.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;
   }
@@ -1867,6 +2629,87 @@ var KeyPairAggregationSigner = class {
   }
 };
 
+// src/core/aggregation/recovery-spend.ts
+var import_bitcoin3 = require("@did-btcr2/bitcoin");
+var import_secp256k16 = require("@noble/curves/secp256k1.js");
+var import_btc_signer6 = require("@scure/btc-signer");
+var import_musig24 = require("@scure/btc-signer/musig2");
+var DUST_LIMIT_SATS = 546n;
+function bytesEqual2(a, b) {
+  return a.length === b.length && a.every((x, i) => x === b[i]);
+}
+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 = import_secp256k16.schnorr.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 = (0, import_musig24.keyAggExport)((0, import_musig24.keyAggregate)((0, import_musig24.sortKeys)(cohortKeys)));
+  const leaves = buildRecoveryLeaves(fundingModel ?? DEFAULT_FUNDING_MODEL, {
+    recoveryKey,
+    recoverySequence,
+    cohortKeys,
+    fallbackThreshold: resolveFallbackThreshold(fallbackThreshold, cohortKeys.length)
+  });
+  const net = (0, import_bitcoin3.getNetwork)(network);
+  const payment = (0, import_btc_signer6.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 import_btc_signer6.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
 var CONSOLE_LOGGER = {
   debug: (msg, ...args) => console.debug(msg, ...args),
@@ -1894,6 +2737,7 @@ var KEYGEN_VALUES = /* @__PURE__ */ new Set([
 ]);
 var UPDATE_VALUES = /* @__PURE__ */ new Set([
   SUBMIT_UPDATE,
+  SUBMIT_NONINCLUDED,
   DISTRIBUTE_AGGREGATED_DATA,
   VALIDATION_ACK
 ]);
@@ -1901,7 +2745,9 @@ var SIGN_VALUES = /* @__PURE__ */ new Set([
   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);
@@ -2129,7 +2975,7 @@ var Identifier = class _Identifier {
 
 // src/core/aggregation/transport/http/envelope.ts
 var import_common8 = require("@did-btcr2/common");
-var import_utils4 = require("@noble/hashes/utils");
+var import_utils5 = require("@noble/hashes/utils");
 
 // src/core/aggregation/transport/http/errors.ts
 var HttpTransportError = class extends TransportAdapterError {
@@ -2157,7 +3003,7 @@ var DEFAULT_NONCE_LEN_BYTES = 16;
 // src/core/aggregation/transport/http/envelope.ts
 function signEnvelope(message, sender, opts = {}) {
   const timestamp = opts.timestamp ?? Math.floor(Date.now() / 1e3);
-  const nonce = opts.nonce ?? (0, import_utils4.bytesToHex)((0, import_utils4.randomBytes)(DEFAULT_NONCE_LEN_BYTES));
+  const nonce = opts.nonce ?? (0, import_utils5.bytesToHex)((0, import_utils5.randomBytes)(DEFAULT_NONCE_LEN_BYTES));
   const messageJson = normalizeForWire(normalizeMessage(message));
   const unsigned = {
     v: HTTP_ENVELOPE_VERSION,
@@ -2169,7 +3015,7 @@ function signEnvelope(message, sender, opts = {}) {
   };
   const digest = (0, import_common8.canonicalHashBytes)(unsigned);
   const sig = sender.keys.secretKey.sign(digest, { scheme: "schnorr" });
-  return { ...unsigned, sig: (0, import_utils4.bytesToHex)(sig) };
+  return { ...unsigned, sig: (0, import_utils5.bytesToHex)(sig) };
 }
 function verifyEnvelope(envelope, senderPk, opts = {}) {
   if (envelope.v !== HTTP_ENVELOPE_VERSION) {
@@ -2206,7 +3052,7 @@ function verifyEnvelope(envelope, senderPk, opts = {}) {
   }
   let sigBytes;
   try {
-    sigBytes = (0, import_utils4.hexToBytes)(envelope.sig);
+    sigBytes = (0, import_utils5.hexToBytes)(envelope.sig);
   } catch {
     throw new HttpTransportError(
       "Envelope signature is not valid hex",
@@ -2239,7 +3085,7 @@ function normalizeMessage(message) {
 }
 function normalizeForWire(value) {
   if (value instanceof Uint8Array) {
-    return { __bytes: (0, import_utils4.bytesToHex)(value) };
+    return { __bytes: (0, import_utils5.bytesToHex)(value) };
   }
   if (Array.isArray(value)) {
     return value.map((v) => normalizeForWire(v));
@@ -2258,7 +3104,7 @@ function reviveFromWire(value) {
     const rec = value;
     const keys = Object.keys(rec);
     if (keys.length === 1 && keys[0] === "__bytes" && typeof rec.__bytes === "string") {
-      return (0, import_utils4.hexToBytes)(rec.__bytes);
+      return (0, import_utils5.hexToBytes)(rec.__bytes);
     }
     const out = {};
     for (const [k, v] of Object.entries(rec)) out[k] = reviveFromWire(v);
@@ -2272,11 +3118,11 @@ function reviveFromWire(value) {
 
 // src/core/aggregation/transport/http/request-auth.ts
 var import_common9 = require("@did-btcr2/common");
-var import_utils5 = require("@noble/hashes/utils");
+var import_utils6 = require("@noble/hashes/utils");
 var REQUEST_AUTH_SCHEME = "BTCR2-Sig";
 function buildRequestAuth(did, keys, path, opts = {}) {
   const ts = opts.timestamp ?? Math.floor(Date.now() / 1e3);
-  const nonce = opts.nonce ?? (0, import_utils5.bytesToHex)((0, import_utils5.randomBytes)(DEFAULT_NONCE_LEN_BYTES));
+  const nonce = opts.nonce ?? (0, import_utils6.bytesToHex)((0, import_utils6.randomBytes)(DEFAULT_NONCE_LEN_BYTES));
   const digest = (0, import_common9.canonicalHashBytes)({
     v: HTTP_ENVELOPE_VERSION,
     did,
@@ -2285,7 +3131,7 @@ function buildRequestAuth(did, keys, path, opts = {}) {
     path
   });
   const sig = keys.secretKey.sign(digest, { scheme: "schnorr" });
-  return `${REQUEST_AUTH_SCHEME} v=${HTTP_ENVELOPE_VERSION},did=${did},ts=${ts},nonce=${nonce},sig=${(0, import_utils5.bytesToHex)(sig)}`;
+  return `${REQUEST_AUTH_SCHEME} v=${HTTP_ENVELOPE_VERSION},did=${did},ts=${ts},nonce=${nonce},sig=${(0, import_utils6.bytesToHex)(sig)}`;
 }
 function parseRequestAuth(headerValue) {
   const prefix = `${REQUEST_AUTH_SCHEME} `;
@@ -2336,7 +3182,7 @@ function verifyRequestAuth(headerValue, expectedPath, senderPk, opts = {}) {
   }
   let sigBytes;
   try {
-    sigBytes = (0, import_utils5.hexToBytes)(parsed.sig);
+    sigBytes = (0, import_utils6.hexToBytes)(parsed.sig);
   } catch {
     throw new HttpTransportError("Auth signature is not valid hex", "REQUEST_AUTH_SIG_HEX");
   }
@@ -3315,7 +4161,7 @@ function flattenMessage2(msg) {
 
 // src/core/aggregation/transport/nostr.ts
 var import_keypair6 = require("@did-btcr2/keypair");
-var import_utils6 = require("@noble/hashes/utils");
+var import_utils7 = require("@noble/hashes/utils");
 var import_nostr_tools = require("nostr-tools");
 var import_pool = require("nostr-tools/pool");
 var DEFAULT_NOSTR_RELAYS = [
@@ -3513,14 +4359,14 @@ var NostrTransport = class _NostrTransport {
     }
     const senderKeys = actor.keys;
     const tags = [
-      ["p", (0, import_utils6.bytesToHex)(senderKeys.publicKey.x)],
+      ["p", (0, import_utils7.bytesToHex)(senderKeys.publicKey.x)],
       ["t", type]
     ];
     if (to) {
       const recipientPkBytes = this.#peerRegistry.get(to);
       if (recipientPkBytes) {
         const recipientPk = new import_keypair6.CompressedSecp256k1PublicKey(recipientPkBytes);
-        tags.push(["p", (0, import_utils6.bytesToHex)(recipientPk.x)]);
+        tags.push(["p", (0, import_utils7.bytesToHex)(recipientPk.x)]);
       }
     }
     if (isKeygenMessageType(type)) {
@@ -3553,7 +4399,7 @@ var NostrTransport = class _NostrTransport {
       const recipientPk = new import_keypair6.CompressedSecp256k1PublicKey(recipientPkBytes);
       const conversationKey = import_nostr_tools.nip44.v2.utils.getConversationKey(
         senderKeys.secretKey.bytes,
-        (0, import_utils6.bytesToHex)(recipientPk.x)
+        (0, import_utils7.bytesToHex)(recipientPk.x)
       );
       const content = import_nostr_tools.nip44.v2.encrypt(JSON.stringify(message, _NostrTransport.#jsonReplacer), conversationKey);
       const event = (0, import_nostr_tools.finalizeEvent)({
@@ -3576,7 +4422,7 @@ var NostrTransport = class _NostrTransport {
    * 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(message, sender, intervalMs, recipient) {
@@ -3607,7 +4453,7 @@ var NostrTransport = class _NostrTransport {
    */
   #subscribeDirected(did, entry) {
     if (!this.pool) return;
-    const pkHex = (0, import_utils6.bytesToHex)(entry.keys.publicKey.x);
+    const pkHex = (0, import_utils7.bytesToHex)(entry.keys.publicKey.x);
     const sub = this.pool.subscribeMany(this.#relays, { kinds: [1, 1059], "#p": [pkHex] }, {
       onclose: (reasons) => this.#logger.debug(`Nostr directed subscription closed for ${did}`, reasons),
       onevent: this.#makeActorEventHandler(did)
@@ -3625,7 +4471,7 @@ var NostrTransport = class _NostrTransport {
     return async (event) => {
       const actor = this.#actors.get(actorDid);
       if (!actor) return;
-      if (event.pubkey === (0, import_utils6.bytesToHex)(actor.keys.publicKey.x)) return;
+      if (event.pubkey === (0, import_utils7.bytesToHex)(actor.keys.publicKey.x)) return;
       let message;
       try {
         if (event.kind === 1) {
@@ -3738,7 +4584,7 @@ var NostrTransport = class _NostrTransport {
    */
   static #jsonReplacer(_key, value) {
     if (value instanceof Uint8Array) {
-      return { __bytes: (0, import_utils6.bytesToHex)(value) };
+      return { __bytes: (0, import_utils7.bytesToHex)(value) };
     }
     return value;
   }
@@ -3756,7 +4602,7 @@ var NostrTransport = class _NostrTransport {
    */
   static #jsonReviver(_key, value) {
     if (value && typeof value === "object" && "__bytes" in value) {
-      return (0, import_utils6.hexToBytes)(value.__bytes);
+      return (0, import_utils7.hexToBytes)(value.__bytes);
     }
     return value;
   }
@@ -3791,7 +4637,7 @@ var TransportFactory = class {
 };
 
 // src/core/aggregation/transport/in-memory.ts
-var import_utils7 = require("@noble/hashes/utils");
+var import_utils8 = require("@noble/hashes/utils");
 var InMemoryBus = class {
   #transports = /* @__PURE__ */ new Set();
   /** Attach a transport to this bus. Called by the transport's constructor. */
@@ -3810,8 +4656,8 @@ var InMemoryBus = class {
   async deliver(message, _sender, recipient) {
     const type = message.type;
     if (!type) return;
-    const replacer = (_k, v) => v instanceof Uint8Array ? { __bytes: (0, import_utils7.bytesToHex)(v) } : v;
-    const reviver = (_k, v) => v && typeof v === "object" && "__bytes" in v ? (0, import_utils7.hexToBytes)(v.__bytes) : v;
+    const replacer = (_k, v) => v instanceof Uint8Array ? { __bytes: (0, import_utils8.bytesToHex)(v) } : v;
+    const reviver = (_k, v) => v && typeof v === "object" && "__bytes" in v ? (0, import_utils8.hexToBytes)(v.__bytes) : v;
     const raw = JSON.parse(JSON.stringify(message, replacer), reviver);
     const serialized = { ...raw, ...raw.body ?? {} };
     if (!recipient) {
@@ -4017,35 +4863,29 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
   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(options) {
     super();
     this.#transport = options.transport;
     this.#did = options.did;
-    this.#config = options.config;
+    this.#defaultConfig = options.config;
     this.#onOptInReceived = options.onOptInReceived ?? (async () => ({ accepted: true }));
     this.#onReadyToFinalize = options.onReadyToFinalize ?? (async ({ acceptedCount, minRequired }) => ({
       finalize: acceptedCount >= minRequired
@@ -4054,6 +4894,7 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
     this.#cohortTtlMs = options.cohortTtlMs;
     this.#phaseTimeoutMs = options.phaseTimeoutMs;
     this.#advertRepeatIntervalMs = options.advertRepeatIntervalMs ?? DEFAULT_ADVERT_REPEAT_INTERVAL_MS;
+    this.#autoFallbackOnStall = options.autoFallbackOnStall ?? false;
     this.session = new AggregationService({
       // The coordinator never signs, so the state machine receives only the
       // public half of the operator's keypair (see ADR 038). The full keypair
@@ -4063,55 +4904,126 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
       maxUpdateSizeBytes: options.maxUpdateSizeBytes
     });
   }
+  /** Resolve the {@link RunContext} an inbound message belongs to, by cohortId. */
+  #contextFor(msg) {
+    const cohortId = msg.body?.cohortId;
+    if (!cohortId) return void 0;
+    return this.#contexts.get(cohortId);
+  }
+  /**
+   * Drain any silent rejections the state machine recorded for a cohort during
+   * the most recent receive() and surface them as `message-rejected` events.
+   */
+  #drainRejections(ctx) {
+    for (const r of this.session.drainRejections(ctx.cohortId)) {
+      this.emit("message-rejected", { cohortId: ctx.cohortId, ...r });
+    }
+  }
   /**
-   * 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.
+   * 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`).
    */
-  #drainRejections() {
-    if (!this.#cohortId) return;
-    for (const r of this.session.drainRejections(this.#cohortId)) {
-      this.emit("message-rejected", { cohortId: this.#cohortId, ...r });
+  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 the protocol to completion. Resolves with the final aggregation result
-   * (signature + signed transaction) once signing is complete.
+   * Run a single cohort to completion using the `config` supplied in the
+   * runner options. Thin convenience over {@link advertiseCohort} for the
+   * single-cohort case (and the path {@link AggregationRunner.solo} rides).
    *
    * @returns {Promise<AggregationResult>} The final result with signature and signed tx.
    */
   run() {
-    return new Promise((resolve, reject) => {
-      this.#resolveRun = resolve;
-      this.#rejectRun = reject;
-      try {
-        this.#registerHandlers();
-        this.#cohortId = this.session.createCohort(this.#config);
-        this.#startTimers();
-        const advertMsgs = this.session.advertise(this.#cohortId);
-        this.#onPhaseMaybeChanged();
-        this.emit("cohort-advertised", { cohortId: this.#cohortId });
-        if (this.#advertRepeatIntervalMs > 0) {
-          this.#startAdvertRepeat(advertMsgs);
-        } else {
-          this.#sendAll(advertMsgs).catch((err) => this.#fail(err));
-        }
-      } catch (err) {
-        this.#fail(err);
+    if (!this.#defaultConfig) {
+      return Promise.reject(new AggregationServiceError(
+        "run() requires `config` in the runner options; use advertiseCohort(config) to drive cohorts explicitly.",
+        "MISSING_COHORT_CONFIG",
+        {}
+      ));
+    }
+    try {
+      return this.advertiseCohort(this.#defaultConfig).completion;
+    } catch (err) {
+      return Promise.reject(err);
+    }
+  }
+  /**
+   * Wait for every currently-outstanding cohort to settle and return the
+   * successful results. Dynamic drain: cohorts advertised while this is pending
+   * are included, and it resolves only once no cohorts remain. Failed cohorts
+   * are surfaced via `error` / `cohort-failed` events and their rejected
+   * `completion` promises; they are omitted from the returned array (this
+   * method does not throw). Bound long-running cohorts with `cohortTtlMs` /
+   * `phaseTimeoutMs` or this may never resolve.
+   *
+   * @returns {Promise<AggregationResult[]>} Results of the cohorts that completed.
+   */
+  async runAll() {
+    const collected = /* @__PURE__ */ new Map();
+    const onComplete = (result) => {
+      collected.set(result.cohortId, result);
+    };
+    this.on("signing-complete", onComplete);
+    try {
+      while (this.#contexts.size > 0) {
+        await Promise.allSettled([...this.#contexts.values()].map((c) => c.completion));
       }
-    });
+    } finally {
+      this.off("signing-complete", onComplete);
+    }
+    return [...collected.values()];
   }
   /**
-   * Begin publishing the cohort advert immediately and on a repeating interval
-   * until {@link #stopAdvertRepeating} is called. Each advert is broadcast
-   * (no recipient) via the transport's `publishRepeating` primitive.
+   * Begin publishing a cohort's advert immediately and on a repeating interval
+   * until the cohort's advert loop is stopped. Each advert is broadcast (no
+   * recipient) via the transport's `publishRepeating` primitive.
    */
-  #startAdvertRepeat(advertMsgs) {
+  #startAdvertRepeat(ctx, advertMsgs) {
     const stops = [];
     for (const msg of advertMsgs) {
       stops.push(this.#transport.publishRepeating(msg, this.#did, this.#advertRepeatIntervalMs));
     }
-    this.#stopAdvertRepeat = () => {
+    ctx.stopAdvertRepeat = () => {
       for (const stop of stops) {
         try {
           stop();
@@ -4120,81 +5032,176 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
       }
     };
   }
-  /** Stop the advert republish loop. Idempotent. */
-  #stopAdvertRepeating() {
-    if (!this.#stopAdvertRepeat) return;
-    const stop = this.#stopAdvertRepeat;
-    this.#stopAdvertRepeat = void 0;
+  /** Stop a cohort's advert republish loop. Idempotent. */
+  #stopAdvertRepeating(ctx) {
+    if (!ctx.stopAdvertRepeat) return;
+    const stop = ctx.stopAdvertRepeat;
+    ctx.stopAdvertRepeat = void 0;
     stop();
   }
-  /** Schedule cohort TTL + phase timeout at the start of a run. */
-  #startTimers() {
+  /** Schedule a cohort's TTL + phase timeout when it is advertised. */
+  #startTimers(ctx) {
     if (this.#cohortTtlMs !== void 0) {
-      this.#cohortTtlTimer = setTimeout(() => {
-        const reason = `Cohort ${this.#cohortId ?? ""} exceeded TTL of ${this.#cohortTtlMs}ms`;
-        this.emit("cohort-failed", { cohortId: this.#cohortId ?? "", reason });
-        this.#fail(new Error(reason));
+      ctx.cohortTtlTimer = setTimeout(() => {
+        const reason = `Cohort ${ctx.cohortId} exceeded TTL of ${this.#cohortTtlMs}ms`;
+        this.emit("cohort-failed", { cohortId: ctx.cohortId, reason });
+        this.#failCohort(ctx, new Error(reason));
       }, this.#cohortTtlMs);
     }
-    this.#resetPhaseTimer();
+    this.#resetPhaseTimer(ctx);
   }
-  /** Reset the per-phase stall timer. Called when a phase transition is observed. */
-  #resetPhaseTimer() {
-    if (this.#phaseTimer) clearTimeout(this.#phaseTimer);
-    this.#phaseTimer = void 0;
+  /** Reset a cohort's per-phase stall timer. Called when a phase transition is observed. */
+  #resetPhaseTimer(ctx) {
+    if (ctx.phaseTimer) clearTimeout(ctx.phaseTimer);
+    ctx.phaseTimer = void 0;
     if (this.#phaseTimeoutMs === void 0) return;
-    this.#phaseTimer = setTimeout(() => {
-      const reason = `Cohort ${this.#cohortId ?? ""} stalled in phase ${this.#lastObservedPhase ?? "?"} for ${this.#phaseTimeoutMs}ms`;
-      this.emit("cohort-failed", { cohortId: this.#cohortId ?? "", reason });
-      this.#fail(new Error(reason));
+    ctx.phaseTimer = setTimeout(() => {
+      const 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 messages = this.session.startFallbackSigning(cohortId);
+    ctx.committedPath = "fallback";
+    this.#stopAdvertRepeating(ctx);
+    this.#onPhaseMaybeChanged(ctx);
+    const sessionId = this.session.getSigningSessionId(cohortId) ?? "";
+    this.emit("fallback-started", { cohortId, sessionId });
+    await this.#sendAll(messages);
+  }
+  /** Detect a phase change for a cohort since the last observation and reset its phase timer. */
+  #onPhaseMaybeChanged(ctx) {
+    const phase = this.session.getCohortPhase(ctx.cohortId);
+    if (phase !== ctx.lastObservedPhase) {
+      ctx.lastObservedPhase = phase;
+      this.#resetPhaseTimer(ctx);
+    }
+  }
+  /** Clear a cohort's timers. Called on completion, stop, and failure. */
+  #clearTimers(ctx) {
+    if (ctx.cohortTtlTimer) clearTimeout(ctx.cohortTtlTimer);
+    if (ctx.phaseTimer) clearTimeout(ctx.phaseTimer);
+    ctx.cohortTtlTimer = void 0;
+    ctx.phaseTimer = void 0;
+  }
+  /**
+   * Reclaim one cohort's runner-layer bookkeeping: stop its advert loop, clear
+   * its timers, and drop its {@link RunContext}. Does NOT touch sibling cohorts
+   * and does NOT detach the shared transport handlers. Leaves the cohort in the
+   * state machine; whether that cohort's `session` state is also removed is the
+   * caller's choice (see {@link #completeCohort} vs {@link #failCohort}).
+   */
+  #disposeCohort(ctx) {
+    this.#stopAdvertRepeating(ctx);
+    this.#clearTimers(ctx);
+    this.#contexts.delete(ctx.cohortId);
+  }
+  /**
+   * Settle one cohort successfully. Reclaims the runner context but leaves the
+   * completed cohort in `session` so callers can read its beaconAddress / cohort
+   * via `session.getCohort(result.cohortId)`; reclaim it with
+   * `session.removeCohort(cohortId)` when done. Idempotent via `ctx.settled`.
+   */
+  #completeCohort(ctx, result) {
+    if (ctx.settled) return;
+    ctx.settled = true;
+    this.#disposeCohort(ctx);
+    this.emit("signing-complete", result);
+    ctx.resolve(result);
+  }
+  /**
+   * Fail one cohort. Reclaims its runner context, drops its now-dead state from
+   * the state machine, and rejects only its completion; siblings keep running
+   * and the shared transport handlers stay registered. Idempotent via
+   * `ctx.settled`.
+   */
+  #failCohort(ctx, err) {
+    if (ctx.settled) return;
+    ctx.settled = true;
+    this.#disposeCohort(ctx);
+    this.session.removeCohort(ctx.cohortId);
+    this.emit("error", err);
+    ctx.reject(err);
   }
-  /** Clear both timers. Called on successful completion, stop(), and #fail. */
-  #clearTimers() {
-    if (this.#cohortTtlTimer) clearTimeout(this.#cohortTtlTimer);
-    if (this.#phaseTimer) clearTimeout(this.#phaseTimer);
-    this.#cohortTtlTimer = void 0;
-    this.#phaseTimer = void 0;
+  /**
+   * Stop a single cohort early without affecting the rest of the runner. Drops
+   * the cohort's state machine state; its `completion` promise rejects with a
+   * stopped error.
+   */
+  stopCohort(cohortId) {
+    const ctx = this.#contexts.get(cohortId);
+    if (!ctx || ctx.settled) return;
+    ctx.settled = true;
+    this.#disposeCohort(ctx);
+    this.session.removeCohort(cohortId);
+    ctx.reject(new AggregationServiceError(`Cohort ${cohortId} stopped.`, "COHORT_STOPPED", { cohortId }));
   }
   /**
-   * Stop the runner early. Marks the runner stopped and detaches transport
-   * handlers so a restart or a new runner doesn't inherit stale dispatch.
+   * Stop the whole runner. Fails every outstanding cohort, then detaches the
+   * shared transport handlers so a restart or a new runner doesn't inherit
+   * stale dispatch. Safe to call repeatedly.
    */
   stop() {
     this.#stopped = true;
-    this.#stopAdvertRepeating();
-    this.#clearTimers();
+    for (const ctx of [...this.#contexts.values()]) {
+      if (ctx.settled) continue;
+      ctx.settled = true;
+      this.#disposeCohort(ctx);
+      this.session.removeCohort(ctx.cohortId);
+      ctx.reject(new AggregationServiceError("Service runner stopped.", "RUNNER_STOPPED", { cohortId: ctx.cohortId }));
+    }
+    this.#contexts.clear();
     this.#unregisterHandlers();
-    if (this.#cohortId) this.session.removeCohort(this.#cohortId);
   }
   /** Message types this runner listens for on the transport. */
   static #HANDLED_MESSAGE_TYPES = [
     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() {
@@ -4206,23 +5213,25 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
   }
   /**
    * Internal: message handlers for each protocol step. Each handler:
-   * 1) feeds the message into the state machine via session.receive()
-   * 2) emits a high-level event for external observers
-   * 3) checks if the new state triggers any automatic next steps, and if so:
+   * 1) resolves the cohort the message belongs to (by cohortId); ignores it if unknown
+   * 2) feeds the message into the state machine via session.receive()
+   * 3) emits a high-level event (carrying cohortId) for external observers
+   * 4) checks if the new state triggers any automatic next steps, and if so:
    *    a) calls the appropriate decision callback(s)
    *    b) sends any resulting messages from the state machine
+   * Errors fail only the owning cohort. A stopped runner ignores messages.
    * @param {BaseMessage} msg - The incoming message to handle.
    * @returns {Promise<void>} Resolves when handling is complete.
-    * @throws {Error} If any step of handling fails, the error is emitted and the run promise is rejected.
-    * Note: if the runner has been stopped, handlers will ignore incoming messages.
    */
   async #handleOptIn(msg) {
     if (this.#stopped) return;
+    const ctx = this.#contextFor(msg);
+    if (!ctx) return;
     try {
       this.session.receive(msg);
-      this.#drainRejections();
-      this.#onPhaseMaybeChanged();
-      const optIn = this.session.pendingOptIns(this.#cohortId).get(msg.from);
+      this.#drainRejections(ctx);
+      this.#onPhaseMaybeChanged(ctx);
+      const optIn = this.session.pendingOptIns(ctx.cohortId).get(msg.from);
       if (!optIn) return;
       this.emit("opt-in-received", optIn);
       if (optIn.communicationPk) {
@@ -4230,34 +5239,34 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
       }
       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);
     }
   }
   /**
@@ -4265,23 +5274,23 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
    * and distributes the data for validation.
    * @param {BaseMessage} msg - The incoming message to handle.
    * @returns {Promise<void>} Resolves when handling is complete.
-   * @throws {Error} If any step of handling fails, the error is emitted and the run promise is rejected.
-   * Note: if the runner has been stopped, handlers will ignore incoming messages.
    */
   async #handleSubmitUpdate(msg) {
     if (this.#stopped) return;
+    const ctx = this.#contextFor(msg);
+    if (!ctx) return;
     try {
       this.session.receive(msg);
-      this.#drainRejections();
-      this.#onPhaseMaybeChanged();
-      this.emit("update-received", { participantDid: msg.from });
-      if (this.session.getCohortPhase(this.#cohortId) === "UpdatesCollected" /* UpdatesCollected */) {
-        const distributeMsgs = this.session.buildAndDistribute(this.#cohortId);
-        this.emit("data-distributed", { cohortId: this.#cohortId });
+      this.#drainRejections(ctx);
+      this.#onPhaseMaybeChanged(ctx);
+      this.emit("update-received", { cohortId: ctx.cohortId, participantDid: msg.from });
+      if (this.session.getCohortPhase(ctx.cohortId) === "UpdatesCollected" /* UpdatesCollected */) {
+        const distributeMsgs = this.session.buildAndDistribute(ctx.cohortId);
+        this.emit("data-distributed", { cohortId: ctx.cohortId });
         await this.#sendAll(distributeMsgs);
       }
     } catch (err) {
-      this.#fail(err);
+      this.#failCohort(ctx, err);
     }
   }
   /**
@@ -4289,111 +5298,121 @@ var AggregationServiceRunner = class _AggregationServiceRunner extends TypedEven
    * automatically requests tx data and starts signing.
    * @param {BaseMessage} msg - The incoming message to handle.
    * @returns {Promise<void>} Resolves when handling is complete.
-   * @throws {Error} If any step of handling fails, the error is emitted and the run promise is rejected.
-   * Note: if the runner has been stopped, handlers will ignore incoming messages.
    */
   async #handleValidationAck(msg) {
     if (this.#stopped) return;
+    const ctx = this.#contextFor(msg);
+    if (!ctx) return;
     try {
       this.session.receive(msg);
-      this.#drainRejections();
-      this.#onPhaseMaybeChanged();
+      this.#drainRejections(ctx);
+      this.#onPhaseMaybeChanged(ctx);
       const approved = !!msg.body?.approved;
-      this.emit("validation-received", { participantDid: msg.from, approved });
-      const phase = this.session.getCohortPhase(this.#cohortId);
+      this.emit("validation-received", { cohortId: ctx.cohortId, participantDid: msg.from, approved });
+      const phase = this.session.getCohortPhase(ctx.cohortId);
       if (phase === "Failed" /* Failed */) {
         const reason = `Validation rejected by participant ${msg.from}`;
-        this.emit("cohort-failed", { cohortId: this.#cohortId, reason });
-        this.#fail(new Error(reason));
+        this.emit("cohort-failed", { cohortId: ctx.cohortId, reason });
+        this.#failCohort(ctx, new Error(reason));
         return;
       }
       if (phase === "Validated" /* Validated */) {
-        const cohort = this.session.getCohort(this.#cohortId);
+        const cohort = this.session.getCohort(ctx.cohortId);
         const txData = await this.#onProvideTxData({
-          cohortId: this.#cohortId,
+          cohortId: ctx.cohortId,
           beaconAddress: cohort.beaconAddress,
           signalBytes: cohort.signalBytes
         });
-        const authMsgs = this.session.startSigning(this.#cohortId, txData);
-        const sessionId = this.session.getSigningSessionId(this.#cohortId) ?? "";
-        this.emit("signing-started", { sessionId });
+        const authMsgs = this.session.startSigning(ctx.cohortId, txData);
+        const sessionId = this.session.getSigningSessionId(ctx.cohortId) ?? "";
+        this.emit("signing-started", { cohortId: ctx.cohortId, sessionId });
         await this.#sendAll(authMsgs);
       }
     } catch (err) {
-      this.#fail(err);
+      this.#failCohort(ctx, err);
     }
   }
   /**
-   * Handler for receiving nonce contributions and signature authorizations. When all nonces or
-   * signatures are received,
+   * Handler for receiving nonce contributions. When all nonces are received, sends the aggregated
+   * nonce back to the cohort.
    * @param {BaseMessage} msg - The incoming message to handle.
    * @returns {Promise<void>} Resolves when handling is complete.
-   * @throws {Error} If any step of handling fails, the error is emitted and the run promise is rejected.
-   * Note: if the runner has been stopped, handlers will ignore incoming messages.
    */
   async #handleNonceContribution(msg) {
     if (this.#stopped) return;
+    const ctx = this.#contextFor(msg);
+    if (!ctx) return;
     try {
       this.session.receive(msg);
-      this.#drainRejections();
-      this.#onPhaseMaybeChanged();
-      this.emit("nonce-received", { participantDid: msg.from });
-      if (this.session.getCohortPhase(this.#cohortId) === "NoncesCollected" /* NoncesCollected */) {
-        await this.#sendAll(this.session.sendAggregatedNonce(this.#cohortId));
+      this.#drainRejections(ctx);
+      this.#onPhaseMaybeChanged(ctx);
+      this.emit("nonce-received", { cohortId: ctx.cohortId, participantDid: msg.from });
+      if (this.session.getCohortPhase(ctx.cohortId) === "NoncesCollected" /* NoncesCollected */) {
+        await this.#sendAll(this.session.sendAggregatedNonce(ctx.cohortId));
       }
     } catch (err) {
-      this.#fail(err);
+      this.#failCohort(ctx, err);
     }
   }
   /**
    * Handler for receiving signature authorizations. When all partial signatures are received, the
-   * session automatically completes and the final result is emitted and the run() promise is resolved.
+   * session automatically completes; the final result is emitted and the cohort's completion
+   * promise resolves.
    * @param {BaseMessage} msg - The incoming message to handle.
    * @returns {Promise<void>} Resolves when handling is complete.
-   * @throws {Error} If any step of handling fails, the error is emitted and the run promise is rejected.
-   * Note: if the runner has been stopped, handlers will ignore incoming messages.
    */
   async #handleSignatureAuthorization(msg) {
     if (this.#stopped) return;
+    const ctx = this.#contextFor(msg);
+    if (!ctx) return;
     try {
       this.session.receive(msg);
-      this.#drainRejections();
-      this.#onPhaseMaybeChanged();
-      const result = this.session.getResult(this.#cohortId);
+      this.#drainRejections(ctx);
+      this.#onPhaseMaybeChanged(ctx);
+      if (ctx.committedPath === "fallback") return;
+      const result = this.session.getResult(ctx.cohortId);
       if (result) {
-        this.#clearTimers();
-        this.#unregisterHandlers();
-        this.emit("signing-complete", result);
-        this.#resolveRun?.(result);
+        ctx.committedPath = "optimistic";
+        this.#completeCohort(ctx, result);
       }
     } catch (err) {
-      this.#fail(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(ctx);
+      this.#onPhaseMaybeChanged(ctx);
+      const result = this.session.getResult(ctx.cohortId);
+      if (result) {
+        this.#completeCohort(ctx, result);
+      }
+    } catch (err) {
+      this.#failCohort(ctx, err);
     }
   }
   /**
    * Internal: helper to send all messages sequentially. Catches and propagates errors.
    * @param {BaseMessage[]} msgs - The messages to send.
    * @returns {Promise<void>} Resolves when all messages have been sent.
-   * @throws {Error} If sending any message fails, the error is emitted and the run promise is
-   * rejected.
    */
   async #sendAll(msgs) {
     for (const m of msgs) {
       await this.#transport.sendMessage(m, this.#did, m.to);
     }
   }
-  /**
-   * Internal: helper to handle errors. Emits an 'error' event and rejects the run promise.
-   * @param {Error} err - The error to handle.
-   */
-  #fail(err) {
-    this.#stopAdvertRepeating();
-    this.#clearTimers();
-    this.#unregisterHandlers();
-    if (this.#cohortId) this.session.removeCohort(this.#cohortId);
-    this.emit("error", err);
-    this.#rejectRun?.(err);
-  }
 };
 
 // src/core/aggregation/runner/participant-runner.ts
@@ -4441,7 +5460,8 @@ var AggregationParticipantRunner = class _AggregationParticipantRunner extends T
     COHORT_READY,
     DISTRIBUTE_AGGREGATED_DATA,
     AUTHORIZATION_REQUEST,
-    AGGREGATED_NONCE
+    AGGREGATED_NONCE,
+    FALLBACK_AUTHORIZATION_REQUEST
   ];
   /** Internal: detach from the transport. Safe to call repeatedly. */
   #unregisterHandlers() {
@@ -4453,7 +5473,8 @@ var AggregationParticipantRunner = class _AggregationParticipantRunner extends T
   }
   /**
    * Single-shot helper: start, join the first cohort that passes `shouldJoin`,
-   * drive it to completion, and resolve. Convenient for tests and demos.
+   * drive it to completion, and resolve. Convenient for tests and demos. The
+   * single-cohort special case of {@link joinMatching} (count = 1).
    */
   static async joinFirst(options) {
     return new Promise((resolve, reject) => {
@@ -4466,6 +5487,37 @@ var AggregationParticipantRunner = class _AggregationParticipantRunner extends T
       runner.start().catch(reject);
     });
   }
+  /**
+   * Multi-cohort helper: start, join EVERY cohort whose advert passes
+   * `shouldJoin`, drive each to completion in parallel, and resolve once
+   * `count` cohorts have completed (the runner stops at that point). The
+   * N-cohort generalization of {@link joinFirst}, for a participant that joins
+   * several cohorts advertised by one service.
+   *
+   * For an open-ended, long-lived subscriber (no fixed count), construct an
+   * {@link AggregationParticipantRunner} directly, set `shouldJoin`, call
+   * `start()`, and listen for `cohort-complete` - the runner already drives
+   * any number of cohorts concurrently.
+   *
+   * @param options Participant runner options (set `shouldJoin` to select cohorts).
+   * @param count Number of completed cohorts to collect before resolving.
+   * @returns The {@link CohortCompleteInfo} for each completed cohort, in completion order.
+   */
+  static async joinMatching(options, count) {
+    return new Promise((resolve, reject) => {
+      const runner = new _AggregationParticipantRunner(options);
+      const completed = [];
+      runner.on("cohort-complete", (info) => {
+        completed.push(info);
+        if (completed.length >= count) {
+          runner.stop();
+          resolve(completed);
+        }
+      });
+      runner.on("error", reject);
+      runner.start().catch(reject);
+    });
+  }
   /**
    * Internal: handler registration with the transport. Idempotent and safe to call multiple times,
    * but only registers handlers once.
@@ -4479,6 +5531,7 @@ var AggregationParticipantRunner = class _AggregationParticipantRunner extends T
     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.
@@ -4534,8 +5587,13 @@ var AggregationParticipantRunner = class _AggregationParticipantRunner extends T
         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);
     }
@@ -4611,23 +5669,62 @@ var AggregationParticipantRunner = class _AggregationParticipantRunner extends T
       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.
@@ -4643,6 +5740,7 @@ var AggregationParticipantRunner = class _AggregationParticipantRunner extends T
 };
 
 // src/core/aggregation/runner/aggregation-runner.ts
+var import_utils9 = require("@noble/hashes/utils");
 var AggregationRunner = class {
   /**
    * Run a cohort of ONE participant entirely in-process and return the
@@ -4650,8 +5748,8 @@ var AggregationRunner = class {
    *
    * 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
@@ -4669,11 +5767,13 @@ var AggregationRunner = class {
     transport.registerPeer(options.participant.did, options.participant.keys.publicKey.compressed);
     transport.registerPeer(options.service.did, options.service.keys.publicKey.compressed);
     transport.start();
+    const recoveryKey = options.config.recoveryKey ?? (0, import_utils9.bytesToHex)(options.service.keys.publicKey.compressed.slice(1));
+    const recoverySequence = options.config.recoverySequence ?? DEFAULT_RECOVERY_SEQUENCE;
     const service = new AggregationServiceRunner({
       transport,
       did: options.service.did,
       keys: options.service.keys,
-      config: { minParticipants: 1, network: options.config.network, beaconType: options.config.beaconType },
+      config: { minParticipants: 1, network: options.config.network, beaconType: options.config.beaconType, recoveryKey, recoverySequence, fundingModel: DEFAULT_FUNDING_MODEL },
       onProvideTxData: options.onProvideTxData,
       cohortTtlMs: options.cohortTtlMs,
       phaseTimeoutMs: options.phaseTimeoutMs,
@@ -4699,8 +5799,8 @@ var AggregationRunner = class {
 };
 
 // src/core/beacon/beacon.ts
-var import_utils8 = require("@noble/hashes/utils.js");
-var import_btc_signer4 = require("@scure/btc-signer");
+var import_utils10 = require("@noble/hashes/utils.js");
+var import_btc_signer7 = require("@scure/btc-signer");
 
 // src/core/beacon/error.ts
 var import_common12 = require("@did-btcr2/common");
@@ -4761,7 +5861,7 @@ var SINGLETON_BEACON_TX_VSIZE = {
   p2tr: P2TR_BEACON_TX_VSIZE
 };
 function detectSingletonScriptKind(bitcoinAddress, network) {
-  const decoded = (0, import_btc_signer4.Address)(network).decode(bitcoinAddress);
+  const decoded = (0, import_btc_signer7.Address)(network).decode(bitcoinAddress);
   if (decoded.type === "pkh") return "p2pkh";
   if (decoded.type === "wpkh") return "p2wpkh";
   if (decoded.type === "tr") return "p2tr";
@@ -4772,12 +5872,12 @@ function detectSingletonScriptKind(bitcoinAddress, network) {
   );
 }
 function deriveSingletonAddress(kind, pubkey, network) {
-  if (kind === "p2pkh") return (0, import_btc_signer4.p2pkh)(pubkey, network).address;
-  if (kind === "p2wpkh") return (0, import_btc_signer4.p2wpkh)(pubkey, network).address;
-  return (0, import_btc_signer4.p2tr)(pubkey.slice(1, 33), void 0, network).address;
+  if (kind === "p2pkh") return (0, import_btc_signer7.p2pkh)(pubkey, network).address;
+  if (kind === "p2wpkh") return (0, import_btc_signer7.p2wpkh)(pubkey, network).address;
+  return (0, import_btc_signer7.p2tr)(pubkey.slice(1, 33), void 0, network).address;
 }
 function opReturnScript(signalBytes) {
-  return import_btc_signer4.Script.encode(["RETURN", signalBytes]);
+  return import_btc_signer7.Script.encode(["RETURN", signalBytes]);
 }
 async function fetchSpendableUtxo(bitcoinAddress, bitcoin) {
   const utxos = await bitcoin.rest.address.getUtxos(bitcoinAddress);
@@ -4797,13 +5897,12 @@ async function fetchSpendableUtxo(bitcoinAddress, bitcoin) {
     );
   }
   const prevTxHex = await bitcoin.rest.transaction.getHex(utxo.txid);
-  return { utxo, prevTxBytes: (0, import_utils8.hexToBytes)(prevTxHex) };
+  return { utxo, prevTxBytes: (0, import_utils10.hexToBytes)(prevTxHex) };
 }
 async function buildAggregationBeaconTx(opts) {
   const feeEstimator = opts.feeEstimator ?? DEFAULT_FEE_ESTIMATOR;
   const { utxo, prevTxBytes } = await fetchSpendableUtxo(opts.beaconAddress, opts.bitcoin);
-  const tapOut = (0, import_btc_signer4.p2tr)(opts.internalPubkey, void 0, opts.network);
-  const witnessScript = tapOut.script;
+  const witnessScript = import_btc_signer7.OutScript.encode((0, import_btc_signer7.Address)(opts.network).decode(opts.beaconAddress));
   const feeSats = await feeEstimator.estimateFee(P2TR_BEACON_TX_VSIZE);
   if (BigInt(utxo.value) <= feeSats) {
     throw new BeaconError(
@@ -4812,7 +5911,7 @@ async function buildAggregationBeaconTx(opts) {
       { address: opts.beaconAddress, valueSats: utxo.value, feeSats }
     );
   }
-  const tx = new import_btc_signer4.Transaction({ allowUnknownOutputs: true });
+  const tx = new import_btc_signer7.Transaction({ allowUnknownOutputs: true });
   tx.addInput({
     txid: utxo.txid,
     index: utxo.vout,
@@ -4835,16 +5934,16 @@ async function buildAggregationBeaconTx(opts) {
 async function signSingletonInput(tx, inputIdx, kind, signer, prevOutScript, amount) {
   const pubkey = signer.publicKey;
   if (kind === "p2pkh") {
-    const sighashType = import_btc_signer4.SigHash.ALL;
+    const sighashType = import_btc_signer7.SigHash.ALL;
     const sighash2 = tx.preimageLegacy(inputIdx, prevOutScript, sighashType);
     const sig2 = signer.sign(sighash2, "ecdsa");
-    const sigWithType = (0, import_utils8.concatBytes)(sig2, new Uint8Array([sighashType]));
+    const sigWithType = (0, import_utils10.concatBytes)(sig2, new Uint8Array([sighashType]));
     tx.updateInput(inputIdx, { partialSig: [[pubkey, sigWithType]] }, true);
     tx.finalize();
     return tx.hex;
   }
   if (kind === "p2wpkh") {
-    const decoded = import_btc_signer4.OutScript.decode(prevOutScript);
+    const decoded = import_btc_signer7.OutScript.decode(prevOutScript);
     if (decoded.type !== "wpkh") {
       throw new BeaconError(
         `Expected P2WPKH prev-output script, got "${decoded.type}".`,
@@ -4852,16 +5951,16 @@ async function signSingletonInput(tx, inputIdx, kind, signer, prevOutScript, amo
         { kind, observedScriptType: decoded.type }
       );
     }
-    const sighashScript = import_btc_signer4.OutScript.encode({ type: "pkh", hash: decoded.hash });
-    const sighashType = import_btc_signer4.SigHash.ALL;
+    const sighashScript = import_btc_signer7.OutScript.encode({ type: "pkh", hash: decoded.hash });
+    const sighashType = import_btc_signer7.SigHash.ALL;
     const sighash2 = tx.preimageWitnessV0(inputIdx, sighashScript, sighashType, amount);
     const sig2 = signer.sign(sighash2, "ecdsa");
-    const sigWithType = (0, import_utils8.concatBytes)(sig2, new Uint8Array([sighashType]));
+    const sigWithType = (0, import_utils10.concatBytes)(sig2, new Uint8Array([sighashType]));
     tx.updateInput(inputIdx, { partialSig: [[pubkey, sigWithType]] }, true);
     tx.finalize();
     return tx.hex;
   }
-  const sighash = tx.preimageWitnessV1(inputIdx, [prevOutScript], import_btc_signer4.SigHash.DEFAULT, [amount]);
+  const sighash = tx.preimageWitnessV1(inputIdx, [prevOutScript], import_btc_signer7.SigHash.DEFAULT, [amount]);
   const sig = signer.sign(sighash, "bip341");
   tx.updateInput(inputIdx, { tapKeySig: sig });
   tx.finalize();
@@ -4882,7 +5981,7 @@ var SinglePartyBeacon = class {
    *
    * 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.
    *
@@ -4914,7 +6013,7 @@ var SinglePartyBeacon = class {
    *
    * 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.
@@ -4940,17 +6039,17 @@ var SinglePartyBeacon = class {
         { address: opts.beaconAddress, valueSats: opts.utxo.value, feeSats }
       );
     }
-    const tx = new import_btc_signer4.Transaction({ allowUnknownOutputs: true });
+    const tx = new import_btc_signer7.Transaction({ allowUnknownOutputs: true });
     let prevOutScript;
     if (kind === "p2pkh") {
-      prevOutScript = (0, import_btc_signer4.p2pkh)(pubkey, network).script;
+      prevOutScript = (0, import_btc_signer7.p2pkh)(pubkey, network).script;
       tx.addInput({
         txid: opts.utxo.txid,
         index: opts.utxo.vout,
         nonWitnessUtxo: opts.prevTxBytes
       });
     } else if (kind === "p2wpkh") {
-      prevOutScript = (0, import_btc_signer4.p2wpkh)(pubkey, network).script;
+      prevOutScript = (0, import_btc_signer7.p2wpkh)(pubkey, network).script;
       tx.addInput({
         txid: opts.utxo.txid,
         index: opts.utxo.vout,
@@ -4959,7 +6058,7 @@ var SinglePartyBeacon = class {
       });
     } else {
       const internalKey = pubkey.slice(1, 33);
-      prevOutScript = (0, import_btc_signer4.p2tr)(internalKey, void 0, network).script;
+      prevOutScript = (0, import_btc_signer7.p2tr)(internalKey, void 0, network).script;
       tx.addInput({
         txid: opts.utxo.txid,
         index: opts.utxo.vout,
@@ -5148,7 +6247,7 @@ var SingletonBeacon = class extends SinglePartyBeacon {
 // src/core/beacon/smt-beacon.ts
 var import_common15 = require("@did-btcr2/common");
 var import_smt3 = require("@did-btcr2/smt");
-var import_utils9 = require("@noble/hashes/utils");
+var import_utils11 = require("@noble/hashes/utils");
 var SMTBeacon = class extends SinglePartyBeacon {
   /**
    * Creates an instance of SMTBeacon.
@@ -5237,7 +6336,7 @@ var SMTBeacon = class extends SinglePartyBeacon {
   async broadcastSignal(signedUpdate, signer, bitcoin, options) {
     const did = this.service.id.split("#")[0];
     const canonicalBytes = new TextEncoder().encode((0, import_common15.canonicalize)(signedUpdate));
-    const nonce = (0, import_utils9.randomBytes)(32);
+    const nonce = (0, import_utils11.randomBytes)(32);
     const tree = new import_smt3.BTCR2MerkleTree();
     tree.addEntries([{ did, nonce, signedUpdate: canonicalBytes }]);
     tree.finalize();
@@ -5268,13 +6367,13 @@ var BeaconFactory = class {
 };
 
 // src/core/beacon/signal-discovery.ts
-var import_bitcoin3 = require("@did-btcr2/bitcoin");
+var import_bitcoin5 = require("@did-btcr2/bitcoin");
 var import_common18 = require("@did-btcr2/common");
 
 // src/core/beacon/utils.ts
-var import_bitcoin2 = require("@did-btcr2/bitcoin");
+var import_bitcoin4 = require("@did-btcr2/bitcoin");
 var import_common17 = require("@did-btcr2/common");
-var import_btc_signer5 = require("@scure/btc-signer");
+var import_btc_signer8 = require("@scure/btc-signer");
 
 // src/utils/appendix.ts
 var import_dids = require("@web5/dids");
@@ -6379,10 +7478,10 @@ var BeaconUtils = class {
   static createBeaconService(did, addressType, beaconType) {
     try {
       const components = Identifier.decode(did);
-      const network = (0, import_bitcoin2.getNetwork)(components.network);
+      const network = (0, import_bitcoin4.getNetwork)(components.network);
       const pubkey = components.genesisBytes;
       const id = `${did}#initial${addressType.toUpperCase()}`;
-      const address = addressType === "p2tr" ? (0, import_btc_signer5.p2tr)(pubkey.slice(1, 33), void 0, network).address : addressType === "p2wpkh" ? (0, import_btc_signer5.p2wpkh)(pubkey, network).address : (0, import_btc_signer5.p2pkh)(pubkey, network).address;
+      const address = addressType === "p2tr" ? (0, import_btc_signer8.p2tr)(pubkey.slice(1, 33), void 0, network).address : addressType === "p2wpkh" ? (0, import_btc_signer8.p2wpkh)(pubkey, network).address : (0, import_btc_signer8.p2pkh)(pubkey, network).address;
       const serviceEndpoint = `bitcoin:${address}`;
       return { id, type: beaconType, serviceEndpoint };
     } catch (error) {
@@ -6401,9 +7500,9 @@ var BeaconUtils = class {
    */
   static generateBeaconServices({ id, publicKey, network, beaconType }) {
     try {
-      const p2pkhAddr = (0, import_btc_signer5.p2pkh)(publicKey, network).address;
-      const p2wpkhAddr = (0, import_btc_signer5.p2wpkh)(publicKey, network).address;
-      const p2trAddr = (0, import_btc_signer5.p2tr)(publicKey.slice(1, 33), void 0, network).address;
+      const p2pkhAddr = (0, import_btc_signer8.p2pkh)(publicKey, network).address;
+      const p2wpkhAddr = (0, import_btc_signer8.p2wpkh)(publicKey, network).address;
+      const p2trAddr = (0, import_btc_signer8.p2tr)(publicKey.slice(1, 33), void 0, network).address;
       if (!p2pkhAddr || !p2wpkhAddr || !p2trAddr) {
         throw new import_common17.DidMethodError("Failed to generate bitcoin addresses");
       }
@@ -6530,14 +7629,14 @@ var BeaconSignalDiscovery = class {
     console.info(`Searching for beacon signals, please wait ...`);
     while (block.height <= targetHeight) {
       for (const tx of block.tx) {
-        if (tx.txid === import_bitcoin3.GENESIS_TX_ID) {
+        if (tx.txid === import_bitcoin5.GENESIS_TX_ID) {
           continue;
         }
         for (const vin of tx.vin) {
           if (vin.coinbase) {
             continue;
           }
-          if (vin.txinwitness && vin.txinwitness.length === 1 && vin.txinwitness[0] === import_bitcoin3.TXIN_WITNESS_COINBASE) {
+          if (vin.txinwitness && vin.txinwitness.length === 1 && vin.txinwitness[0] === import_bitcoin5.TXIN_WITNESS_COINBASE) {
             continue;
           }
           if (!vin.txid) {
@@ -6591,7 +7690,7 @@ var BeaconSignalDiscovery = class {
 };
 
 // src/core/resolver.ts
-var import_bitcoin5 = require("@did-btcr2/bitcoin");
+var import_bitcoin7 = require("@did-btcr2/bitcoin");
 var import_common22 = require("@did-btcr2/common");
 var import_cryptosuite3 = require("@did-btcr2/cryptosuite");
 var import_keypair8 = require("@did-btcr2/keypair");
@@ -6605,11 +7704,11 @@ var import_common20 = require("@did-btcr2/common");
 var import_cryptosuite2 = require("@did-btcr2/cryptosuite");
 
 // src/utils/did-document.ts
-var import_bitcoin4 = require("@did-btcr2/bitcoin");
+var import_bitcoin6 = require("@did-btcr2/bitcoin");
 var import_common19 = require("@did-btcr2/common");
 var import_keypair7 = require("@did-btcr2/keypair");
-var import_utils11 = require("@web5/dids/utils");
-var import_btc_signer6 = require("@scure/btc-signer");
+var import_utils13 = require("@web5/dids/utils");
+var import_btc_signer9 = require("@scure/btc-signer");
 var BTCR2_DID_DOCUMENT_CONTEXT = [
   "https://www.w3.org/ns/did/v1.1",
   "https://btcr2.dev/context/v1"
@@ -6818,7 +7917,7 @@ var DidDocument = class _DidDocument {
    * @returns {boolean} True if the services are valid.
    */
   static isValidServices(service) {
-    return Array.isArray(service) && service.every(import_utils11.isDidService);
+    return Array.isArray(service) && service.every(import_utils13.isDidService);
   }
   /**
    * Validates verification relationships (authentication, assertionMethod, capabilityInvocation, capabilityDelegation).
@@ -6931,7 +8030,7 @@ var GenesisDocument = class _GenesisDocument extends DidDocument {
   static fromPublicKey(publicKey, network) {
     const pk = new import_keypair7.CompressedSecp256k1PublicKey(publicKey);
     const id = ID_PLACEHOLDER_VALUE;
-    const address = (0, import_btc_signer6.p2pkh)(pk.compressed, (0, import_bitcoin4.getNetwork)(network)).address;
+    const address = (0, import_btc_signer9.p2pkh)(pk.compressed, (0, import_bitcoin6.getNetwork)(network)).address;
     const services = [{
       id: `${id}#service-0`,
       serviceEndpoint: `bitcoin:${address}`,
@@ -6980,7 +8079,7 @@ var Updater = class _Updater {
   #verificationMethod;
   #beaconService;
   /**
-   * @internal — Use {@link DidBtcr2.update} to create instances.
+   * @internal Use {@link DidBtcr2.update} to create instances.
    */
   constructor(params) {
     this.#sourceDocument = params.sourceDocument;
@@ -7017,7 +8116,7 @@ var Updater = class _Updater {
     const targetDocument = import_common20.JSONPatch.apply(sourceDocument, patches);
     if (targetDocument.id !== sourceDocument.id) {
       throw new import_common20.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}").`,
         import_common20.INVALID_DID_UPDATE,
         { sourceId: sourceDocument.id, targetId: targetDocument.id }
       );
@@ -7101,8 +8200,8 @@ var Updater = class _Updater {
   }
   /**
    * 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) {
@@ -7115,7 +8214,7 @@ var Updater = class _Updater {
           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",
@@ -7298,8 +8397,8 @@ var DidBtcr2 = class {
    *
    * 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
@@ -7398,7 +8497,7 @@ var DidBtcr2 = class {
 };
 
 // src/core/resolver.ts
-var import_utils13 = require("@noble/curves/utils.js");
+var import_utils15 = require("@noble/curves/utils.js");
 var Resolver = class _Resolver {
   // --- Immutable inputs ---
   #didComponents;
@@ -7417,7 +8516,7 @@ var Resolver = class _Resolver {
   #unsortedUpdates = [];
   #resolvedResponse = null;
   /**
-   * @internal — Use {@link DidBtcr2.resolve} to create instances.
+   * @internal Use {@link DidBtcr2.resolve} to create instances.
    */
   constructor(didComponents, sidecarData, currentDocument, options) {
     this.#didComponents = didComponents;
@@ -7442,7 +8541,7 @@ var Resolver = class _Resolver {
     const service = BeaconUtils.generateBeaconServices({
       id: did,
       publicKey: genesisBytes,
-      network: (0, import_bitcoin5.getNetwork)(didComponents.network),
+      network: (0, import_bitcoin7.getNetwork)(didComponents.network),
       beaconType: "SingletonBeacon"
     });
     return new DidDocument({
@@ -7465,7 +8564,7 @@ var Resolver = class _Resolver {
    */
   static external(didComponents, genesisDocument) {
     const genesisDocumentHash = (0, import_common22.canonicalHashBytes)(genesisDocument);
-    if (!(0, import_utils13.equalBytes)(didComponents.genesisBytes, genesisDocumentHash)) {
+    if (!(0, import_utils15.equalBytes)(didComponents.genesisBytes, genesisDocumentHash)) {
       throw new import_common22.ResolveError(
         `Initial document mismatch: genesisBytes !== genesisDocumentHash`,
         import_common22.INVALID_DID_DOCUMENT,
@@ -7542,7 +8641,7 @@ var Resolver = class _Resolver {
         this.confirmDuplicate(update, updateHashHistory);
       } else if (update.targetVersionId === currentVersionId + 1) {
         const sourceHashBytes = (0, import_common22.decode)(update.sourceHash, "base64urlnopad");
-        if (!(0, import_utils13.equalBytes)(sourceHashBytes, currentDocumentHash)) {
+        if (!(0, import_utils15.equalBytes)(sourceHashBytes, currentDocumentHash)) {
           throw new import_common22.ResolveError(
             `Hash mismatch: update.sourceHash !== currentDocumentHash`,
             import_common22.INVALID_DID_UPDATE,
@@ -7589,7 +8688,7 @@ var Resolver = class _Resolver {
     const { proof: _, ...unsignedUpdate } = update;
     const unsignedUpdateHash = (0, import_common22.canonicalHashBytes)(unsignedUpdate);
     const historicalUpdateHash = updateHashHistory[update.targetVersionId - 2];
-    if (!(0, import_utils13.equalBytes)(historicalUpdateHash, unsignedUpdateHash)) {
+    if (!(0, import_utils15.equalBytes)(historicalUpdateHash, unsignedUpdateHash)) {
       throw new import_common22.ResolveError(
         `Invalid duplicate: unsigned update hash does not match historical hash`,
         import_common22.LATE_PUBLISHING_ERROR,
@@ -7642,7 +8741,7 @@ var Resolver = class _Resolver {
     DidDocument.validate(updatedDocument);
     const currentDocumentHash = (0, import_common22.canonicalHashBytes)(updatedDocument);
     const updateTargetHash = (0, import_common22.decode)(update.targetHash);
-    if (!(0, import_utils13.equalBytes)(updateTargetHash, currentDocumentHash)) {
+    if (!(0, import_utils15.equalBytes)(updateTargetHash, currentDocumentHash)) {
       throw new import_common22.ResolveError(
         `Invalid update: update.targetHash !== currentDocumentHash`,
         import_common22.INVALID_DID_UPDATE,
@@ -7653,8 +8752,8 @@ var Resolver = class _Resolver {
   }
   /**
    * 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()`.
    */
@@ -7892,9 +8991,11 @@ var DidDocumentBuilder = class {
   DEFAULT_ADVERT_REPEAT_INTERVAL_MS,
   DEFAULT_BROADCAST_LOOKBACK_MS,
   DEFAULT_CLOCK_SKEW_SEC,
+  DEFAULT_FUNDING_MODEL,
   DEFAULT_MAX_UPDATE_SIZE_BYTES,
   DEFAULT_NONCE_LEN_BYTES,
   DEFAULT_NOSTR_RELAYS,
+  DEFAULT_RECOVERY_SEQUENCE,
   DID_REGEX,
   DISTRIBUTE_AGGREGATED_DATA,
   DidBtcr2,
@@ -7903,6 +9004,8 @@ var DidDocumentBuilder = class {
   DidDocumentBuilder,
   DidVerificationMethod,
   Document,
+  FALLBACK_AUTHORIZATION_REQUEST,
+  FALLBACK_SIGNATURE,
   GenesisDocument,
   HTTP_ENVELOPE_VERSION,
   HTTP_ROUTE,
@@ -7916,7 +9019,9 @@ var DidDocumentBuilder = class {
   InMemoryTransport,
   InboxBuffer,
   KNOWN_BEACON_TYPES,
+  KNOWN_FUNDING_MODELS,
   KeyPairAggregationSigner,
+  MAX_RECOVERY_SEQUENCE,
   NONCE_CONTRIBUTION,
   NonceCache,
   NostrTransport,
@@ -7933,6 +9038,7 @@ var DidDocumentBuilder = class {
   SMTBeacon,
   SMTBeaconError,
   SSE_EVENT,
+  SUBMIT_NONINCLUDED,
   SUBMIT_UPDATE,
   ServiceCohortPhase,
   SigningSessionError,
@@ -7941,6 +9047,7 @@ var DidDocumentBuilder = class {
   SingletonBeacon,
   SingletonBeaconError,
   StaticFeeEstimator,
+  TAPROOT_LEAF_VERSION,
   TransportAdapterError,
   TransportError,
   TransportFactory,
@@ -7948,6 +9055,11 @@ var DidDocumentBuilder = class {
   Updater,
   VALIDATION_ACK,
   buildAggregationBeaconTx,
+  buildFallbackLeaf,
+  buildFallbackSpend,
+  buildRecoveryLeaves,
+  buildRecoveryScript,
+  buildRecoverySpend,
   buildRequestAuth,
   createAggregatedNonceMessage,
   createAuthorizationRequestMessage,
@@ -7956,13 +9068,17 @@ var DidDocumentBuilder = class {
   createCohortOptInMessage,
   createCohortReadyMessage,
   createDistributeAggregatedDataMessage,
+  createFallbackAuthorizationRequestMessage,
+  createFallbackSignatureMessage,
   createNonceContributionMessage,
   createSignatureAuthorizationMessage,
+  createSubmitNonIncludedMessage,
   createSubmitUpdateMessage,
   createValidationAckMessage,
   defaultReconnectBackoff,
   deriveSingletonAddress,
   detectSingletonScriptKind,
+  fallbackSighash,
   formatSseComment,
   formatSseEvent,
   getBeaconStrategy,
@@ -7974,10 +9090,13 @@ var DidDocumentBuilder = class {
   isCohortOptInMessage,
   isCohortReadyMessage,
   isDistributeAggregatedDataMessage,
+  isFallbackAuthorizationRequestMessage,
+  isFallbackSignatureMessage,
   isKeygenMessageType,
   isNonceContributionMessage,
   isSignMessageType,
   isSignatureAuthorizationMessage,
+  isSubmitNonIncludedMessage,
   isSubmitUpdateMessage,
   isUpdateMessageType,
   isValidationAckMessage,
@@ -7986,8 +9105,10 @@ var DidDocumentBuilder = class {
   parseRequestAuth,
   parseSseStream,
   registerBeaconStrategy,
+  resolveFallbackThreshold,
   reviveFromWire,
   signEnvelope,
+  tapLeafHash,
   validateCohortConditions,
   verifyEnvelope,
   verifyRequestAuth