shardtree: truncate exactly at an achievable boundary, never retaining data beyond the cut

truncate_to_checkpoint_internal swallowed the None that
LocatedPrunableTree::truncate_to_position returns when the requested
position falls inside a pruned hash leaf or a Nil region: shards, cap,
and checkpoints were all left untouched while the call reported success.
A caller that truncates after a chain reorg then re-inserts recomputed
subtrees over the retained stale hashes, and insert_subtree fails with
InsertionError::Conflict at the stale address, deterministically and
forever.

Truncation at a position inside a pruned region is not representable: a
single pruned hash commits to data on both sides of the cut. Truncation
is now total and honest instead: any node committing to data beyond the
cut is discarded, the boundary retreats to the position immediately
preceding the discarded node's range, cached annotations along the cut
path are cleared, shards and cap are truncated at the same achieved
boundary, checkpoints are always truncated, and checkpoints recording
positions beyond the achieved boundary (including the truncation target
itself) are removed. truncate_to_checkpoint and
truncate_to_checkpoint_depth report the achieved TreeState so callers
can re-insert data beyond the boundary, e.g. by rescanning the chain
from the achieved state.

Author: gustavovalverde

shardtree/CHANGELOG.md

@@ -44,6 +44,27 @@ and this project adheres to Rust's notion of
   within a single pruning window.
 
 
+### Changed
+- `shardtree::ShardTree::{truncate_to_checkpoint, truncate_to_checkpoint_depth}`
+  now return `Result<Option<shardtree::store::TreeState>, ...>` instead of
+  `Result<bool, ...>`. `None` replaces `false` (no such checkpoint); `Some`
+  reports the tree state actually achieved, which may be earlier than the
+  checkpointed position if pruning prevents an exact truncation. In that case
+  checkpoints beyond the achieved state (including the requested one) are
+  removed, and the caller must restore the missing range, e.g. by rescanning.
+- `shardtree::LocatedPrunableTree::truncate_to_position` now returns
+  `(Self, Option<Position>)` instead of `Option<Self>`. Truncation always
+  succeeds, retreating the boundary when pruning prevents an exact cut; the
+  returned position is the boundary actually achieved. Parent annotations
+  committing to discarded data are now also discarded.
+
+### Fixed
+- `shardtree::ShardTree::{truncate_to_checkpoint, truncate_to_checkpoint_depth}`
+  no longer silently leave the tree unmodified when the checkpointed position
+  falls within a pruned node. The stale retained hashes previously caused
+  persistent `InsertionError::Conflict` failures when re-inserting subtree
+  data after a chain reorg.
+
 ## [0.6.2] - 2026-02-20
 
 ### Added