[Ranjna-G]

Summary

Z→z spends on staging TZEC failed with CapNodeMissing because the persisted cap was the shardtree crate's internal cache (two bootstrap ommer hashes, never updated) rather than a complete, consumer-walkable structure. This PR makes extract_state materialize a full cap on every save — completed-shard roots as single cached leaves, bootstrap ommers reused verbatim, the in-progress shard embedded as live structure — and verifies it hashes standalone, exactly the way the witness builder walks it, against the tree's current root.

Linear: CSHLD-1419

Changes

• materialize_cap / rebuild_cap_node: build the persisted-state cap — completed shards cached as single Leaf roots, in-progress shard embedded as a live tree copy, Nil beyond the tip — reusing valid cached entries (bootstrap ommers are the only record of never-retained shard ranges)
• verify_cap_root: new save-time assertion — the cap must hash standalone, truncated at leaf_count, to the root at the most recent checkpoint; fails with a precise error if the latest checkpoint is not at the tip
• sanitize_store_cap / restore_state: strip sub-shard structure from the cap before installing it as the store cap (sub-shard structure made reorgs panic inside shardtree's root_internal leaf-split branch); completed-shard roots and ommers are kept as valid cache
• refresh_store_cap / truncate_to_checkpoint: heal the store cap after a reorg rewind — stale completed-shard roots would otherwise make a divergent chain's saves silently persist pre-reorg roots (the reference root goes through the same poisoned cache)
• rebuild_cap_node: annotations are dropped on re-derived (straddling) subtrees so stale cached hashes can never be persisted
• .gitignore: ignore .DS_Store and *.tgz
• Tests: sanitizer shape contract; reorg lifecycle across a completed-shard boundary (shallow reorg, deep reorg into a previously-completed shard, divergent re-fill with an independent true-root reference); production-type test pinning that restore strips sub-shard structure while the persisted cap keeps it

Test Plan

• cargo test --manifest-path packages/wasm-privacy-coin/Cargo.toml --lib — 14 passed, 1 ignored (14/14 relevant)
• The ignored staging fixture test (ZEC_STAGING_STATE_JSON=<exported PersistedShardTreeState>) should be run once against the staging indexer export before merge — it replays the exact production failure state through the fixed save path
• Deploy to staging TZEC and confirm the first z→z spend succeeds (the failing wallets' notes are in shards 3, 5, 12)

[linear-code]

CSHLD-1419

[Ranjna-G]

@claude review for logical correctness

[claude]

I reviewed this PR and didn't find any bugs. It changes how the Zcash Orchard commitment-tree cap is saved, restored and repaired after a reorg, and @ BitGo/coinsshield owns that path, so a human look from them would still be worthwhile.

What was reviewed:

• materialize_cap/rebuild_cap_node: completed shards become single leaves, bootstrap ommers are kept as-is, the in-progress shard is embedded, and ranges past leaf_count stay Nil.
• verify_cap_root: the cap is hashed on its own, truncated at leaf_count, and checked against the latest checkpoint root. extract_state now returns an error when the latest checkpoint is not at the tip, which is a change to a public function's behavior.
• sanitize_store_cap in restore_state, and the new refresh_store_cap call in truncate_to_checkpoint: I checked the reorg path. Truncation leaves the checkpoint at the tip, so the verify step there holds.

Extended reasoning...

The change adds about 900 lines to packages/wasm-privacy-coin/src/zcash/tree.rs, most of them new tests, plus two .gitignore entries. It changes how the Orchard note-commitment tree cap is persisted, restored and repaired after reorgs. That state feeds witness building for shielded spends, so a wrong cap could break spends or quietly persist stale roots. There is no injection, auth or data-exposure surface. I deferred because the change is large and sits on a cryptographic state path that a CODEOWNERS team (coinsshield) owns, and the PR's own test plan still lists an ignored staging-fixture test that should be run before merge.

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review for a one-time review, or @claude review always to subscribe this PR to a review on every future push.

_{Tip: disable this comment in your organization's Code Review settings.}