Depends on: #261, #262, #263, #265 ### Goal Implement rare, explicit Placement Transitions that move an activated bucket between holder sets without changing document IDs, placement handles, strategy IDs, or bucket numbers. Ordinary map, label, weight, capacity, telemetry, or reachability changes must never move existing state. ### Scope - Store an immutable candidate-map epoch for each bucket's current Placement Activation. First use initializes it; only an authorized transition can replace it. - Preview affected buckets, bytes, old/new holders, failure domains, at-risk copies, and transfer limits before activation. - Admit a transition only under the configured per-strategy `max_incomplete_buckets` and per-node transfer, verification, outstanding-byte, and bandwidth limits. Overlapping transitions for a strategy are rejected while one is stalled. - On activation, fence old-entry writes at a causal Irokle barrier. Old holders reconcile every accepted pre-barrier event and produce one canonical checkpoint rooted at the frozen frontier. - Require every new holder to verify the checkpoint, complete causal closure, and post-barrier deltas before signing completion evidence bound to the exact transition, activations, frontier, checkpoint root, and holder identity. - Route reads across current and recorded previous holder sets while incomplete; route writes under the transition fence to the current write authority only. - Atomically advance Placement Activation only after all required completion evidence verifies. Do not infer completion from elapsed time, reachability, telemetry, or topic existence. - Keep old copies for exactly one hour after completion before release. Alert after 24 hours of incompleteness, but never use the alert deadline to delete, cut over, or fabricate proof. - Force-finalization requires an audited at-risk report and may never remove the last verified copy. - Preserve transition and release evidence for audit and future ID routing. ### Non-scope - Automatic rebalance from new maps, weights, labels, telemetry, full/draining observations, or connection loss. - ID rewriting, per-document rebucketing, schema migration, multi-predecessor chains, or arbitrary overlapping transitions. - Heartbeats, dead-node consensus, or timeout-based authority changes. - S3 home/replica movement unless an S3 operation explicitly invokes its own fenced mechanism. ### Definition of Done - [ ] Existing buckets remain on their activated candidate-map epoch until an explicit authorized transition completes. - [ ] Barrier, checkpoint, causal closure, per-holder completion, cutover, one-hour grace, and release are crash-safe and idempotent. - [ ] Reads and writes obey the exact active transition holder sets and never consult a mutable latest map as hidden authority. - [ ] Missing or conflicting proof produces a visible stalled transition, not guessed completion. - [ ] Configured integer concurrency/resource limits are enforced before work begins. - [ ] Full holder turnover preserves every accepted event and one topic history. ### Tests - Deterministic affected-bucket vectors for map/weight/status/affinity/location changes. - Concurrent causal mutations at every barrier/checkpoint/cutover boundary, with partition, reorder, duplicate delivery, restart, and late old-holder responses. - Forged, stale, wrong-holder, wrong-epoch, incomplete-closure, and corrupt-checkpoint rejection. - Exact one-hour release and 24-hour alert tests proving elapsed time alone never changes authority. - Limit boundaries for `max_incomplete_buckets`, transfer slots, bytes, verification, and bandwidth; empty-bucket behavior. - Repeated explicit transitions and complete holder turnover with no loss, fork, or ID change. ### Risks - Incorrect completion proof can delete the last good copy; proof validation and last-copy safety are the critical path. - Transition state must remain small and bounded even when document counts are large; enumerate buckets/manifests, not every realm document.