Module canonicalize 

BIP 388 placeholder-ordering canonicalization per spec v0.13 §6.1, plus per-@N canonical-fill expansion per §5.3 / §6.3.

BIP 388 wallet policies require placeholder indices @0..@{N-1} to be introduced in the descriptor template in canonical first-occurrence order: the first new placeholder encountered in document-order pre-order traversal must be @0, the next new one @1, etc.

canonicalize_placeholder_indices reshapes a Descriptor in place so this invariant holds, atomically permuting:

• the tree’s KeyArg.index and Tr.key_index fields;
• the PathDecl’s Divergent paths vector (one path per @N);
• per-@N TLV maps: use_site_path_overrides, fingerprints, pubkeys, origin_path_overrides.

After canonicalization, the post-conditions are:

1. Each TLV map’s (idx, _) keys are strictly ascending and < n.
2. The tree’s first-occurrence sequence is exactly [0, 1, ..., n-1] (verified via crate::validate::validate_placeholder_usage).

Idempotent: calling on an already-canonical descriptor is a no-op (identity-permutation fast path).

The decoder side does not call this routine: v0.11’s crate::validate::validate_placeholder_usage rejects non-canonical wires up-front via Error::PlaceholderFirstOccurrenceOutOfOrder.

expand_per_at_n resolves each @N to a fully-populated ExpandedKey (origin, use-site, optional fp/xpub) by composing the per-@N TLV overrides with the descriptor-level baselines. Used by Phase 4’s WalletPolicyId construction and Phase 5’s decoder validation.

Structs

ExpandedKey

Fully-resolved per-@N key record produced by expand_per_at_n.

Functions

canonicalize_placeholder_indices

Canonicalize placeholder indices in d so the first-occurrence sequence in d.tree is exactly [0, 1, ..., d.n - 1].

expand_per_at_n

Expand a Descriptor into a vector of ExpandedKey records — one per @N in 0..d.n — by composing per-@N TLV overrides with the descriptor-level baselines (spec v0.13 §5.3 / §6.3, “Option A”).