Move the allocation watermark to descriptor's index so later
allocations cannot reissue it. Monotonic — a lower index is a no-op.
On a static wallet there is no watermark: the wallet's own descriptor
is accepted as a no-op.
Throws on a descriptor this wallet cannot derive, or an HD descriptor with no parseable trailing child index: silently mapping those to index 0 would move the watermark nowhere and let a restored artifact's index be handed out again.
The signing descriptor a new artifact (a swap, an invoice, a contract)
should bind to. The wallet decides what that means: an HD wallet
allocates a fresh index, advancing the watermark; a static wallet
answers with its one tr(pubkey) descriptor every time. Consumers must
not probe the wallet's shape or mint key material of their own — they
ask, and use what comes back with
HDWalletCapable.signerForDescriptor.
undefined only for implementations that genuinely cannot answer;
Wallet always answers. Callers that must work against such wallets
fall back to the identity key — never to a random one.
Distinct from HDWalletCapable.getCurrentSigningDescriptor, which peeks: on an HD wallet, two artifacts bound to a peek share a key. Whether the returned descriptor is unique per call is a property of the wallet, not of this method — anything deriving per-artifact secrets from the descriptor must check the descriptor's shape, not the wallet's.
Allocating a fresh index, which is strictly more than HDWalletCapable's descriptor awareness.
Deliberately a separate probe rather than three more methods on
HDWalletCapable: widening that guard would silently demote every wallet implementing only its original surface — including one built by an older SDK — from HD-capable to static, which is exactly the breakage it documents itself as avoiding. Consumers that only read descriptors keep the narrow probe; anything deriving per-artifact secrets asks for this one.