polyc-eventlog-host 2026.9.0

//! Durable turn persistence host: a Commonware-runtime event log bridged to the
//! tokio control plane.
//!
//! `commonware-runtime` cannot be nested inside tokio —
//! `commonware_runtime::tokio::Runner::start` builds *its own* multi-threaded
//! tokio runtime and would panic on a nested `block_on` if called from within
//! a live tokio runtime. So the event log runs on a **dedicated OS thread**
//! that owns a Commonware tokio runtime; the tokio control plane talks to it
//! over channels. That generic bridge (thread spawn, ready handshake, command
//! loop, post-cancel drain) is [`polyc_host`] — the same shape
//! `polyc_persona::PersonaHost` uses. This host is sharded (`NUM_SHARDS`
//! independent `polyc_host::HostHandle`s, one per shard) rather than a single
//! dedicated thread — see [`EventLogHost`]'s own doc for why, and its [`Drop`]
//! impl for the one place this host layers something on top of `polyc-host`'s
//! generic drop-tx-then-join semantics.
//!
//! # Bridge shape
//!
//! ```text
//! tokio control plane                       dedicated OS thread
//! ───────────────────                       ───────────────────
//! EventLogHost::append_batch(..) ── Command ──▶ commonware tokio Runner.start(|ctx| {
//!   (tokio mpsc send)                            EventLog::open(ctx, ..)
//!         ◀── oneshot ack ──                     loop { rx.recv() -> appends + commit }
//! ```
//!
//! On startup [`EventLogHost::spawn`] launches every shard's thread and blocks
//! (briefly, off the async path) until each has reported readiness.
//! [`EventLogHost::append_batch`] is `async` and callable from tokio: it
//! enqueues one `Command` (a whole turn's events) and awaits a `oneshot` ack.
//! Dropping the host (or cancelling its [`CancellationToken`]) cancels every
//! shard, which drains its loop, syncs its logs, lets `Runner::start` return,
//! and joins its thread — clean shutdown.

use std::{collections::HashMap, path::PathBuf, sync::Arc};

use commonware_runtime::{Spawner as _, Supervisor as _};
use polyc_eventlog::{
    BoundedReplay, Event, EventLog, EventLogConfig, EventLogError, QuarantinedItem,
};
use polyc_host::{Body, HostHandle, HostOptions};
use tokio::sync::{mpsc, oneshot};
use tokio_util::sync::CancellationToken;

use polyc_crypto::signing_role::JournalAttestationSigner;
use polyc_proto::kinds::{
    COMPACTION_CHECKPOINT as BASE_COMPACTION_CHECKPOINT, parse as parse_kind,
};

mod metrics;
mod observer;
mod partition_name;

/// Pre-create every journal-attestation metric series, so each appears in a
/// `/metrics` scrape before any batch commits.
///
/// A binary that serves this host's metrics must call this once at startup.
/// Without it the failure series do not exist until a failure happens, and the
/// unattested-share query returns no data rather than zero — which reads the
/// same as a build where the counter was never wired.
pub fn init_metrics() {
    metrics::force();
}

pub use observer::{AppendNotification, EventLogObserver, MutationKind, MutationNotification};
pub use partition_name::{
    EncodedPartitionName, MAX_ENCODED_PARTITION_BYTES, PartitionNameError, PartitionRef,
    decode as decode_partition, encode as encode_partition,
};

/// Deterministic physical-fault seams for downstream storage recovery tests.
///
/// This module is absent unless the non-default `test-util` feature is enabled.
#[cfg(feature = "test-util")]
pub mod test_util {
    /// Makes the next signed-root marker append for `partition` fail after the
    /// semantic events have been appended. The host commits that prefix and
    /// reports an ambiguous attestation outcome.
    pub fn arm_root_append_failure(partition: &str) {
        super::arm_root_append_failure(partition);
    }

    /// Makes the event at `event_index` of `partition`'s next batch fail as if
    /// the journal append itself had.
    ///
    /// The host best-effort commits whatever prefix it already appended and
    /// reports an ambiguous APPEND outcome, which is a different window from
    /// [`arm_root_append_failure`]'s.
    pub fn arm_append_failure(partition: &str, event_index: usize) {
        super::arm_append_failure_at(partition, event_index);
    }
}

/// The latest compaction checkpoint for a partition plus the events appended after it.
///
/// Folding [`tail`](Self::tail) onto the checkpoint's captured state
/// reproduces a full replay; when no checkpoint exists, `checkpoint` is `None`
/// and `tail` is the whole log.
pub struct CheckpointReplay {
    /// The latest checkpoint frame, or `None` if the partition has none yet.
    pub checkpoint: Option<CheckpointFrame>,
    /// Events appended strictly after the checkpoint (the whole log when none).
    pub tail: Vec<Event>,
}

/// A located compaction checkpoint: the journal position the tail resumes at and
/// the raw `CompactionCheckpointEvent` payload the caller decodes.
pub struct CheckpointFrame {
    /// First tail position — the checkpoint event's own position + 1.
    pub tail_offset: u64,
    /// Raw checkpoint payload bytes.
    pub payload: Vec<u8>,
}

/// What a `Command::RewritePartition` predicate decides for one event.
///
/// A plain keep/drop predicate cannot honor
/// `CascadeOutcome::Retained` (a `polyc-persona-memory` concept this crate has no dependency on):
/// a surviving fact whose erased source was only a *corroborator* must keep the
/// fact but shed that corroborator's pointer, which is neither dropping the
/// whole event nor keeping it unchanged. [`Replace`](Self::Replace) is that
/// third disposition — the event survives under its existing kind with a
/// rewritten payload (the erased conversation scrubbed out of the provenance
/// union), still inside the one atomic host rewrite (#860).
pub enum RewriteDecision {
    /// Retain the event unchanged.
    Keep,
    /// Drop the event entirely.
    Drop,
    /// Keep the event under its existing kind but with this payload — the scrub
    /// path a keep/drop predicate can't express (INV-P25/P28).
    ///
    /// The payload is the ONLY thing this replaces. The event's kind and its
    /// [`TrustTag`](polyc_eventlog::TrustTag) both survive, so scrubbing
    /// quarantined content cannot hand a policy reader untainted bytes where
    /// quarantined ones were durably stored.
    Replace(Vec<u8>),
}

/// What durable storage survives for one partition name.
///
/// Three outcomes, and they stay apart. A partition nobody wrote and one whose
/// erasure completed are both **absent**: a caller may read them as an empty
/// history. A partition whose journal data is gone while an authoritative
/// remnant of it survives is **damaged**: its history is unreadable, not
/// empty, and reporting it as absence would serve a destroyed conversation as
/// a legitimately empty one.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum PartitionPresence {
    /// No durable artifact of this partition holds content.
    Absent,
    /// The partition's own journal data is present.
    Present,
    /// A durable remnant survives with no journal data behind it.
    ///
    /// Carries what was observed, for an operator. It names artifacts, never
    /// content.
    Damaged {
        /// Which surviving remnant contradicts the missing journal data.
        remnant: String,
    },
}

/// The storage suffixes one logical partition owns.
///
/// Measured against the pinned implementation rather than assumed: a commit
/// leaves `_data`, `_offsets-blobs`, `_offsets-metadata`, and the event-count
/// checkpoint. A completed destroy removes the first three. It clears the
/// fourth in place. So a surviving checkpoint is normal, and a surviving
/// checkpoint that still counts events is not.
const OFFSETS_SUFFIXES: [&str; 2] = ["_offsets-blobs", "_offsets-metadata"];

/// The storage suffix the event-count checkpoint occupies.
///
/// Mirrors `polyc_eventlog`'s own naming. A destroy clears this store in place,
/// so the directory outliving a partition is expected.
const CHECKPOINT_STORAGE_SUFFIX: &str = "__eventcount_checkpoint";

/// A request to the dedicated runtime thread, with a channel to report the
/// outcome.
enum Command {
    /// Replay `partition`'s log in order, to reconstruct conversation state.
    Replay {
        /// Storage partition to replay.
        partition: PartitionRef,
        /// Reports the ordered events, or the error.
        ack: oneshot::Sender<Result<Vec<Event>, EventLogError>>,
    },
    /// Replay `partition` with each event's durable journal position — the
    /// stable identity a taint-excision marker (`#590`) names.
    ReplayWithPositions {
        /// Storage partition to replay.
        partition: PartitionRef,
        /// Reports the position-ordered `(position, event)` pairs, or the error.
        ack: oneshot::Sender<Result<Vec<(u64, Event)>, EventLogError>>,
    },
    /// Bounded replay (issue #1541): the same position-ordered pairs
    /// [`Command::ReplayWithPositions`] returns, but STOPS pulling further
    /// items from the journal stream the instant the cumulative payload
    /// bytes read exceed `max_bytes` — the early-abort primitive a Fleet
    /// query's byte budget
    /// (`polyc_query::engine::QueryLimits::max_source_bytes`) is enforced
    /// through, so a single oversized partition can't be fully materialized
    /// before that budget is ever consulted.
    ReplayWithPositionsBounded {
        /// Storage partition to replay.
        partition: PartitionRef,
        /// Byte budget: replay stops early once the cumulative payload
        /// bytes read exceed this.
        max_bytes: u64,
        /// Reports the bounded replay outcome (including whether the budget
        /// tripped), or the journal error.
        ack: oneshot::Sender<Result<BoundedReplay, EventLogError>>,
    },
    /// Bounded replay: return the latest compaction checkpoint (if any) plus
    /// only the events appended after it, so a caller folds the tail instead of
    /// re-reading the whole partition.
    ReplayTailFromCheckpoint {
        /// Storage partition to replay.
        partition: PartitionRef,
        /// Reports the checkpoint frame + tail, or the error.
        ack: oneshot::Sender<Result<CheckpointReplay, EventLogError>>,
    },
    /// Replay `partition` starting at journal position `start` (inclusive),
    /// keeping each event's durable position — the primitive a caller-held
    /// watermark (e.g. `polyc_query`'s decode cache) resumes from instead of
    /// re-reading a partition's whole history. Mirrors
    /// [`polyc_eventlog::EventLog::replay_from_with_positions`] exactly; see
    /// that method's own doc for the exact clamping/empty-range rules.
    ReplayFromWithPositions {
        /// Storage partition to replay.
        partition: PartitionRef,
        /// Journal position to resume from (inclusive), clamped up to the
        /// partition's own pruning boundary.
        start: u64,
        /// Reports the position-ordered `(position, event)` pairs from
        /// `start` onward, or the error.
        ack: oneshot::Sender<Result<Vec<(u64, Event)>, EventLogError>>,
    },
    /// Bounded tail replay: [`Command::ReplayFromWithPositions`]'s resume
    /// semantics (skip everything before `start`) combined with
    /// [`Command::ReplayWithPositionsBounded`]'s early-abort semantics (stop
    /// mid-stream once `max_bytes` would be exceeded) — the primitive that
    /// closes the gap neither of those two alone could: a caller resuming
    /// from its own cached watermark whose TAIL is itself large (a single
    /// oversized append landing after the last cache) used to have no way
    /// to cap that tail's own replay short of materializing it in full.
    ReplayFromWithPositionsBounded {
        /// Storage partition to replay.
        partition: PartitionRef,
        /// Journal position to resume from (inclusive), clamped up to the
        /// partition's own pruning boundary.
        start: u64,
        /// Byte budget: replay stops early once the cumulative payload
        /// bytes read (from `start` onward) exceed this.
        max_bytes: u64,
        /// Reports the bounded replay outcome (including whether the budget
        /// tripped), or the journal error.
        ack: oneshot::Sender<Result<BoundedReplay, EventLogError>>,
    },
    /// Replay a bounded, half-open position RANGE — the only command here
    /// carrying an UPPER bound. Every other replay drains to the tail, so a
    /// caller wanting one known span had to read to the tail and discard the
    /// rest.
    ReplayRangeWithPositionsBounded {
        /// Storage partition to replay.
        partition: PartitionRef,
        /// First position to read (inclusive), clamped up to the partition's
        /// own pruning boundary.
        start: u64,
        /// First position NOT to read (exclusive), clamped down to the
        /// journal's tail.
        end: u64,
        /// Byte budget: replay stops early once the cumulative payload bytes
        /// read within the range exceed this.
        max_bytes: u64,
        /// Reports the bounded replay outcome (including whether the budget
        /// tripped), or the journal error.
        ack: oneshot::Sender<Result<BoundedReplay, EventLogError>>,
    },
    /// Cheap count of events appended since the latest compaction checkpoint —
    /// the journal size (`len`, O(1)) minus the cached checkpoint's tail offset.
    /// Used by the emission gate to avoid a full tail replay every turn on short
    /// (sub-interval) conversations. Never scans the log.
    EventsSinceCheckpoint {
        /// Storage partition to measure.
        partition: PartitionRef,
        /// Reports the event count since the latest checkpoint, or the error.
        ack: oneshot::Sender<Result<u64, EventLogError>>,
    },
    /// Cheap total event count for `partition` — the journal size (`len`,
    /// O(1)), never checkpoint-relative and never a scan. Unlike every other
    /// read command this must NOT create the partition when it has never
    /// been written: opening it (the path `EventsSinceCheckpoint`/`Replay`
    /// take) always creates the on-disk journal as a side effect, which would
    /// make a mere count probe destructive, so an unlisted partition
    /// short-circuits to `0` via the same directory enumeration
    /// [`Command::ListPartitions`] uses.
    PartitionEventCount {
        /// Storage partition to measure.
        partition: PartitionRef,
        /// Reports the total event count, or the error.
        ack: oneshot::Sender<Result<u64, AppendError>>,
    },
    /// Destroy `partition` wholesale: evict any cached handle, remove the
    /// underlying blobs, and forget the checkpoint frame. The #216 erasure
    /// primitive — a subsequent open of the same name starts empty. Runs on
    /// the single command loop, so it serializes against every append and
    /// replay (no handle can race the destruction).
    DestroyPartition {
        /// Storage partition to destroy.
        partition: PartitionRef,
        /// Reports completion, or the error.
        ack: oneshot::Sender<Result<(), EventLogError>>,
    },
    /// Append a batch of events to `partition`'s log in one round-trip,
    /// committing once at the end. If any append fails the batch stops
    /// (subsequent events — including any commit marker the caller put last
    /// — are NOT appended), the partial writes are committed best-effort, and
    /// an error is returned. The marker pattern (`turn_complete` last) then
    /// guarantees that an interrupted batch is dropped on replay.
    AppendBatch {
        /// Storage partition to append to.
        partition: PartitionRef,
        /// Events to append in order.
        events: Vec<Event>,
        /// Reports the assigned positions for the events that were appended,
        /// or the error from the failing append.
        ack: oneshot::Sender<Result<Vec<u64>, AppendError>>,
    },
    /// Ensures the current non-root leaf prefix has a committed signed-root
    /// marker, without appending a second marker when one already covers it.
    EnsurePartitionAttested {
        partition: PartitionRef,
        ack: oneshot::Sender<Result<Option<Event>, AppendError>>,
    },
    /// Atomically (w.r.t. every other host command, since the loop is
    /// single-threaded) rewrite `partition`, applying `decide` to each event to
    /// keep it, drop it, or replace its payload in place — the
    /// crash-window-narrowed, race-free erasure rewrite (#216/#860). Unlike a
    /// caller-side replay→destroy→append (three interleavable commands), the
    /// fresh replay + rewrite + destroy + re-append all happen inside ONE
    /// handler, so a concurrent append can't land between the replay and the
    /// destroy and be lost. Returns how many events were dropped (a replaced
    /// event is neither kept unchanged nor dropped, so it is not counted).
    /// Finishes a rewrite a previous attempt staged, and nothing else.
    ResumeRewritePartition {
        /// Storage partition whose rewrite may be unfinished.
        partition: PartitionRef,
        /// Identity of the excision that staged it.
        command_id: String,
        /// Reports the records that rewrite dropped, or `None` when no stage
        /// was waiting, or the error.
        ack: oneshot::Sender<Result<Option<usize>, AppendError>>,
    },
    RewritePartition {
        /// Storage partition to rewrite in place.
        partition: PartitionRef,
        /// Identity of the excision this rewrite serves.
        ///
        /// Names the durable stage, so a later attempt at the same command can
        /// finish a rewrite a crash interrupted (`#2323`). State mints it and
        /// records it before dialing, so it survives the destroy.
        command_id: String,
        /// Per-event disposition: [`Keep`](RewriteDecision::Keep),
        /// [`Drop`](RewriteDecision::Drop), or
        /// [`Replace`](RewriteDecision::Replace).
        #[allow(clippy::type_complexity)]
        decide: Box<dyn Fn(&Event) -> RewriteDecision + Send + Sync>,
        /// Reports the number of events dropped, or the error.
        ack: oneshot::Sender<Result<usize, EventLogError>>,
    },
    /// Inspect one exact rewrite without changing the partition.
    InspectRewrite {
        partition: PartitionRef,
        command_id: String,
        #[allow(clippy::type_complexity)]
        decide: Box<dyn Fn(&Event) -> RewriteDecision + Send + Sync>,
        ack: oneshot::Sender<Result<RewritePlan, EventLogError>>,
    },
    /// Apply an exact prior rewrite plan or reconcile its durable stage.
    ApplyRewrite {
        partition: PartitionRef,
        command_id: String,
        before: [u8; 32],
        after: [u8; 32],
        stage_binding: [u8; 32],
        #[allow(clippy::type_complexity)]
        decide: Box<dyn Fn(&Event) -> RewriteDecision + Send + Sync>,
        ack: oneshot::Sender<Result<RewriteApplication, EventLogError>>,
    },
    /// Enumerate every logical partition present in the storage directory —
    /// the discovery primitive (#490) behind maintenance sweeps: without it,
    /// a partition whose name is no longer derivable from live state (e.g. a
    /// memory partition orphaned by a merge whose migration never ran) is
    /// unreachable. Runs on the single command loop, so the listing can't
    /// race a concurrent destroy into naming a half-removed partition.
    ListPartitions {
        /// Stops before retaining more logical names than this ceiling.
        max_entries: usize,
        /// Stops before retaining more logical name bytes than this ceiling.
        max_name_bytes: usize,
        /// One logical name omitted before either bound is accounted.
        excluded: Option<String>,
        /// Reports the logical partition names, or why the listing could
        /// not be produced whole.
        ack: oneshot::Sender<Result<Vec<String>, ListPartitionsError>>,
    },
    /// Report when `partition`'s storage last changed — the operational fact
    /// behind a retention policy's idle axis. Answered from the same storage
    /// directory [`Command::ListPartitions`] enumerates, so a partition that
    /// was never written reports nothing and, like that enumeration, no
    /// partition is opened (and therefore none is created) to answer.
    ///
    /// Reports [`None`] for a partition this host holds nothing for and for
    /// storage that will not say — an absent answer, never a very old one, so a
    /// caller cannot read a storage fault as "idle since the epoch".
    PartitionLastModified {
        /// Storage partition to report on.
        partition: PartitionRef,
        /// Reports the newest modification time in milliseconds since the Unix
        /// epoch, or [`None`].
        ack: oneshot::Sender<Option<u64>>,
    },
    /// Reports what durable storage survives for `partition`, without opening it.
    ///
    /// Directory tests on the requested key alone, never an enumeration: a
    /// caller asking about one partition does not read every other
    /// partition's identity, and the answer costs the same whatever the fleet
    /// holds.
    ProbePartition {
        /// Storage partition to test for.
        partition: PartitionRef,
        /// Reports what durable storage survives, or why the volume could not
        /// say.
        ack: oneshot::Sender<Result<PartitionPresence, ListPartitionsError>>,
    },
    /// Move `from`'s events into `to` and destroy `from`.
    ///
    /// One handler invocation per partition (`#2653`). `from`'s replay and
    /// destroy run in this one, so no append can land between them and be
    /// silently lost — the same discipline as [`Command::RewritePartition`].
    /// `to`'s read, dedup, re-root, and append run in their own, dispatched as
    /// [`Command::MigrateAppendInto`], so nothing lands between the decision
    /// and the write there either. The dedup (an event already present in
    /// `to` byte-for-byte is not appended again) makes the move idempotent at
    /// the JOURNAL level, so a retry after a destroy failure — or a second
    /// racing migration — cannot grow `to` unboundedly.
    MigratePartition {
        /// Source partition; destroyed once its events are in `to`.
        from: PartitionRef,
        /// Destination partition.
        to: PartitionRef,
        /// Reports what happened, or the error — including
        /// [`AppendError::Closed`] if `to` is routed to a different, no
        /// longer reachable shard (see [`Command::MigrateAppendInto`]).
        ack: oneshot::Sender<Result<PartitionMigration, AppendError>>,
    },
    /// Decide and append this migration's events on `partition`'s own worker,
    /// then evict any cached MMR for it and refresh its durable event-count
    /// checkpoint.
    ///
    /// The destination dedups the candidates, re-roots over what it will hold,
    /// and appends — all inside this one command, so nothing can land between
    /// the decision and the write (`#2653`).
    ///
    /// Exists so [`migrate_one`] can route the destination-side write of a
    /// cross-shard migration through `partition`'s OWN shard, instead of
    /// opening an independent `EventLog` handle to it from the source
    /// shard's thread — two independent handles over the same on-disk
    /// partition is the hazard the sharding docs on [`Command::MigratePartition`]
    /// used to accept as a rare, unfixed race.
    MigrateAppendInto {
        /// Destination partition (always local to the shard handling this
        /// command).
        partition: PartitionRef,
        /// Candidate events to append, in order, with the source's signed
        /// roots already removed.
        ///
        /// NOT deduped. The destination dedups these itself, inside this one
        /// command, so nothing can land between the read that decides what is
        /// new and the append that adds it (`#2653`).
        events: Vec<Event>,
        /// Source partition these events were migrated from — carried only so
        /// a post-mutation observer notification
        /// ([`crate::MutationKind::MigrationDestination`]) can name it; it
        /// plays no role in the append itself.
        from: PartitionRef,
        /// Reports how many events were appended after dedup, or the error.
        ack: oneshot::Sender<Result<usize, EventLogError>>,
    },
    /// Replay `partition` and verify its tamper-evidence (`#799`): rebuild
    /// the per-partition MMR from the replayed events and check every
    /// signed-root marker found along the way against the host's signer
    /// public key. Returns the replayed events on success (so a caller
    /// doesn't need a second, unverified replay), or the first integrity
    /// violation found.
    ReplayVerified {
        /// Storage partition to replay and verify.
        partition: PartitionRef,
        /// Reports the verified events, or the integrity/journal error.
        ack: oneshot::Sender<Result<Vec<Event>, VerifyError>>,
    },
    /// Recover `partition` from a corrupted item (`#799`): replay every
    /// position independently (so one bad item doesn't block the rest),
    /// then — if anything was unreadable — rewrite the partition retaining
    /// only what decoded. The quarantine primitive backing `polychrome
    /// conversation repair`. A partition with nothing corrupted is a no-op
    /// (empty quarantine list, nothing rewritten).
    RepairPartition {
        /// Storage partition to repair.
        partition: PartitionRef,
        /// Reports every quarantined (dropped) item, or the journal error.
        ack: oneshot::Sender<Result<Vec<QuarantinedItem>, EventLogError>>,
    },
    /// Inspect a repair without changing the partition.
    InspectRepair {
        partition: PartitionRef,
        replacement: Option<RepairEventReplacement>,
        ack: oneshot::Sender<Result<RepairPlan, EventLogError>>,
    },
    /// Apply a previously inspected repair only to the same physical state.
    ApplyRepair {
        partition: PartitionRef,
        before: [u8; 32],
        after: [u8; 32],
        replacement: Option<RepairEventReplacement>,
        ack: oneshot::Sender<Result<RepairApplication, EventLogError>>,
    },
    /// Ask whether a repair's destructive half is still in flight.
    RepairSettled {
        partition: PartitionRef,
        before: [u8; 32],
        after: [u8; 32],
        ack: oneshot::Sender<Result<bool, AppendError>>,
    },
    /// Remove the survivor stage one repair of `partition` may have left.
    DestroyRepairStage {
        partition: PartitionRef,
        before: [u8; 32],
        ack: oneshot::Sender<Result<(), AppendError>>,
    },
    /// Remove the survivor stage one rewrite of `partition` may have left.
    DestroyRewriteStage {
        partition: PartitionRef,
        command_id: String,
        ack: oneshot::Sender<Result<(), AppendError>>,
    },
}

/// A non-mutating repair inspection and the fingerprints that fence its apply.
#[derive(Debug, Clone)]
pub struct RepairPlan {
    /// Physical-state fingerprint before quarantine.
    pub before: [u8; 32],
    /// Physical-state fingerprint after the planned survivors are rewritten.
    pub after: [u8; 32],
    /// Whether applying this plan rewrites the partition's content.
    ///
    /// True when the repair quarantines a position, and ALSO when it only
    /// re-roots: a re-root strips every signed root and appends a fresh one,
    /// which changes the physical content and therefore the fingerprint. A
    /// caller that derived this from the quarantine list alone would record an
    /// `after` the host never produces, and the stage it later looks for could
    /// not be named.
    pub will_rewrite: bool,
    /// Every readable event, in original order, for premise inspection.
    pub readable: Vec<Event>,
    /// Every unreadable or truncated position the repair will quarantine.
    pub quarantined: Vec<QuarantinedItem>,
}

/// One exact event payload a content-changing repair replaces atomically.
#[derive(Debug, Clone)]
pub struct RepairEventReplacement {
    kind: String,
    payload: Vec<u8>,
}

impl RepairEventReplacement {
    /// Replaces the payload of the sole readable event named by `kind`.
    #[must_use]
    pub fn new(kind: impl Into<String>, payload: Vec<u8>) -> Self {
        Self {
            kind: kind.into(),
            payload,
        }
    }
}

/// What a fingerprint-conditioned repair apply did.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RepairApplication {
    /// The inspected state still matched and the repair ran.
    Applied,
    /// The repaired fingerprint already matched, so this was an exact retry.
    AlreadyApplied,
    /// Neither fingerprint matched; another physical state now occupies it.
    Changed,
}

/// A non-mutating exact rewrite inspection.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct RewritePlan {
    /// Exact ordered physical-state fingerprint before rewriting.
    pub before: [u8; 32],
    /// Exact ordered physical-state fingerprint after rewriting and re-rooting.
    pub after: [u8; 32],
    /// Domain-separated binding carried by the durable survivor stage.
    pub stage_binding: [u8; 32],
}

/// What a fingerprint-conditioned rewrite apply did.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RewriteApplication {
    /// The admitted physical state matched and the rewrite ran.
    Applied {
        /// Number of physical events removed rather than replaced.
        dropped: usize,
    },
    /// The exact post-rewrite state already occupied the partition.
    AlreadyApplied,
    /// Neither admitted state nor a valid bound stage could be found.
    Changed,
}

/// What the migrate-partition command did.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PartitionMigration {
    /// Events were appended to the destination (deduped count carried) and
    /// the source destroyed. A destroy failure after the copy is reported by
    /// [`Self::CopiedSourceRemains`] instead, never silently.
    Migrated(usize),
    /// The source was empty; it was destroyed and nothing was appended.
    EmptyDestroyed,
    /// The events are in the destination (deduped count carried) but the
    /// source destroy failed; a re-run appends nothing (dedup) and retries
    /// the destroy.
    CopiedSourceRemains(usize),
}

/// Failure from a verified replay: either the replay itself
/// couldn't be read, it returned fewer events than the durable checkpoint
/// expected, or it read fine but failed tamper-evidence.
#[derive(Debug, thiserror::Error)]
pub enum VerifyError {
    /// The underlying journal replay failed.
    #[error(transparent)]
    Journal(#[from] EventLogError),
    /// The replay returned fewer events than the durable event-count
    /// checkpoint (`#799` hardening — see `polyc_eventlog::checkpoint`)
    /// recorded as last durably committed. `commonware-storage`'s journal
    /// treats corruption in the active (still-open) section identically to
    /// an ordinary crash and silently rewinds it on open — re-deriving item
    /// boundaries by streaming the section from byte zero, so it cannot tell
    /// "one item mid-section is corrupt" apart from "this whole section may
    /// be an in-flight torn write"; ANY internal inconsistency it hits can
    /// invalidate the section back to its last confirmed CLOSED boundary
    /// (in the common case of everything living in one still-open section,
    /// that is zero — even events that precede the corrupted one are lost).
    /// Without this check, that made a truncated replay look
    /// indistinguishable from a legitimately short (or empty) conversation
    /// and reported `verified=true` over data that was actually lost.
    ///
    /// A rewrite interrupted before its terminal count record reports this
    /// too, and means something different by it: the content is correct and
    /// the floor is stale (`#2323`). The message names both causes, because
    /// this type cannot tell them apart. `finish_pending_excisions` resolves
    /// the second one, and State runs it on the failing read (`#2567`).
    #[error(
        "replay returned {actual} event(s) but the durable checkpoint expects at least \
         {expected}: either the storage layer silently truncated the active section (a torn \
         write or corruption/tampering), or a rewrite was interrupted before it lowered the \
         count — see docs/operations/eventlog-disaster-recovery.md"
    )]
    TruncatedReplay {
        /// Last durably recorded expected event count.
        expected: u64,
        /// Event count the replay actually returned.
        actual: u64,
    },
    /// The replay is readable but does not verify against its signed MMR
    /// roots — a tampered event, a forged marker, or a root signed under an
    /// unexpected key.
    #[error(transparent)]
    Integrity(#[from] polyc_eventlog::IntegrityError),
}

/// Number of independent dedicated-thread shards (`#799`). Each partition is
/// routed to exactly one shard (by [`EventLogHost::shard_for`]) for the process's
/// life, so a slow replay of a partition on one shard cannot delay an append
/// to a partition routed to a different shard — the cross-shard half of the
/// single-command-loop bottleneck the `#799` audit named. Picked as a fixed,
/// modest fan-out; not meant to scale with conversation count — WITHIN one
/// shard, [`ShardRouter`] multiplexes many partitions by routing each to its
/// own lazily-spawned worker task (`#1711`), not by sharing one sequential
/// loop across them, so partition-level concurrency scales with conversation
/// count independently of `NUM_SHARDS`.
const NUM_SHARDS: usize = 4;

/// Pure hash-routing function shared by [`EventLogHost::shard_for`] and its
/// test helpers: which of `num_shards` shards `partition` belongs to.
fn shard_index(partition: &str, num_shards: usize) -> usize {
    use std::hash::{Hash as _, Hasher as _};
    let mut hasher = std::collections::hash_map::DefaultHasher::new();
    partition.hash(&mut hasher);
    // `num_shards` is always small (see `NUM_SHARDS`), so the modulo result
    // fits `usize` on every supported target regardless of the 64-bit hash
    // input; truncation on a hypothetical 32-bit target only changes WHICH
    // shard a partition lands on; it can never be out of range.
    #[allow(clippy::cast_possible_truncation)]
    let hash = hasher.finish() as usize;
    hash % num_shards
}

/// Handle to the event-log host: `NUM_SHARDS` independent command loops, each
/// on its own dedicated Commonware-runtime thread.
///
/// Clone-free by design: share it behind an `Arc` if multiple callers need
/// it. Dropping it (after the control plane cancels) joins every shard's
/// thread.
pub struct EventLogHost {
    /// One entry per shard — each a `polyc-host` bridge over its own
    /// dedicated Commonware-runtime thread; see [`NUM_SHARDS`].
    shards: Vec<HostHandle<Command>>,
    /// A child of the caller's `shutdown` token, cancelled unconditionally on
    /// [`Drop`]. Every shard now holds a live [`Command`] sender to every
    /// OTHER shard for cross-shard migration routing (see [`migrate_one`]),
    /// so a shard's channel never sees its sender count reach zero just
    /// because this host dropped its own copies — cancellation, not channel
    /// closure, is what `Drop` can actually rely on to end every shard's
    /// command loop. Being a child token (not a fresh one) preserves the
    /// pre-existing contract that the caller's own `shutdown.cancel()` also
    /// ends every shard.
    host_shutdown: CancellationToken,
    /// Encoded public key of the [`JournalAttestationSigner`] this host uses
    /// for new MMR roots. Approval-family artifacts use independent custody;
    /// callers must not treat this identity as approval trust.
    journal_attestation_public_key: Vec<u8>,
    /// Current and retired journal-attestation identities accepted on replay.
    journal_attestation_trust: polyc_crypto::signing_role::RoleTrustSet<
        polyc_crypto::signing_role::JournalAttestationRole,
    >,
    /// Registered post-append/post-mutation observers ([`EventLogObserver`])
    /// plus per-partition mutation epochs, bundled and shared with every
    /// shard's dedicated thread so a registration or a bump is visible
    /// regardless of which shard next durably commits. See `src/observer.rs`
    /// for the ordering and failure-containment contract.
    write_observers: observer::WriteObservers,
}

/// Bounded backlog of in-flight append commands before `append` applies
/// back-pressure. Persistence is best-effort and off the turn's critical path,
/// so a modest buffer is plenty.
const COMMAND_BACKLOG: usize = 256;

impl EventLogHost {
    /// Spawn `NUM_SHARDS` dedicated Commonware-runtime threads, each
    /// hosting an independent command loop over [`EventLog`]s rooted at
    /// `storage_dir`, returning one tokio-callable handle over all of them.
    ///
    /// Each thread runs until `shutdown` is cancelled (or the handle is
    /// dropped), at which point its command channel closes, its logs sync,
    /// and its runtime returns.
    ///
    /// Signing key (`#799`, `#784`, `#1171`): the per-conversation MMR root
    /// signer is the caller-supplied journal-attestation signer — there is no
    /// deterministic fallback. Production State loads its private role key
    /// from dedicated custody; the temporary Control-owned persona-memory
    /// journal loads a separate role key. Only tests construct one from a
    /// seed, and only `polyc-crypto`'s `test-util` feature makes that seed
    /// constructor reachable at all.
    ///
    /// # Errors
    ///
    /// Returns [`HostError`] if a shard's dedicated runtime thread fails
    /// before reporting readiness (`Body::open` is trivially `Ok(())` for
    /// every shard — individual partitions open lazily inside command
    /// handling — so only that failure mode is reachable here). Shards
    /// already started are cleanly shut down in that case (this host's
    /// `host_shutdown` is cancelled before the partially-built `shards` list
    /// is dropped, so no already-running shard's `HostHandle::drop` can
    /// block joining a thread that never observes shutdown); the caller
    /// aborts the process on this error path in practice regardless.
    ///
    /// # Panics
    ///
    /// Panics if the OS refuses to spawn a shard's dedicated thread (out of
    /// resources) — a condition this host cannot recover from, so it aborts
    /// rather than leaving a shard silently missing.
    // Each of the `NUM_SHARDS` threads needs its OWN owned clone of both
    // arguments (a fresh `PathBuf`/`CancellationToken` moved into that
    // shard's thread closure), so accepting them by value here — rather
    // than by reference plus an internal `.clone()` — keeps call sites
    // exactly as they were before sharding (`spawn(dir.clone(),
    // shutdown.clone())`). `journal_attestation_signer` is a distinct role
    // and custody reference; approval/session/grant keys cannot be supplied
    // here by type.
    #[allow(clippy::needless_pass_by_value)]
    pub fn spawn(
        storage_dir: PathBuf,
        shutdown: CancellationToken,
        journal_attestation_signer: JournalAttestationSigner,
    ) -> Result<Self, HostError> {
        let trust = polyc_crypto::signing_role::RoleTrustSet::current(&journal_attestation_signer);
        Self::spawn_with_trust(storage_dir, shutdown, journal_attestation_signer, trust)
    }

    /// Spawns a host that accepts the current and retired attestation keys.
    ///
    /// # Errors
    ///
    /// Refuses a trust set that omits the active signer, or a runtime thread
    /// that cannot start.
    // The host owns the storage location and cancellation lifetime. Preserve
    // the established value-taking spawn contract while this overload adds
    // only an explicit public trust set.
    #[allow(clippy::needless_pass_by_value)]
    pub fn spawn_with_trust(
        storage_dir: PathBuf,
        shutdown: CancellationToken,
        journal_attestation_signer: JournalAttestationSigner,
        journal_attestation_trust: polyc_crypto::signing_role::RoleTrustSet<
            polyc_crypto::signing_role::JournalAttestationRole,
        >,
    ) -> Result<Self, HostError> {
        let signer = journal_attestation_signer;
        let journal_attestation_public_key = signer.public_key_bytes();
        if !journal_attestation_trust
            .keys()
            .iter()
            .any(|identity| identity == &signer.identity())
        {
            return Err(HostError::ActiveSignerNotTrusted);
        }
        // A child of the caller's token: cancelling `shutdown` cancels this
        // too, but `EventLogHost`'s own `Drop` can also cancel just this
        // child directly — see the field doc on `host_shutdown` for why
        // that is now load-bearing, not merely a courtesy.
        let host_shutdown = shutdown.child_token();
        // Every shard's sender, handed to every OTHER shard too: a shard
        // whose command needs to touch a partition routed elsewhere (only
        // `Command::MigratePartition`, today) dispatches a
        // [`Command::MigrateAppendInto`] to the owning shard through this
        // list instead of opening an independent handle
        // to it — see [`migrate_one`]. Created before any thread spawns
        // (`polyc_host::spawn_host_with_channel`, INV-H6) so every shard's
        // peer list is complete from the start — the chicken-and-egg an
        // internally-created channel (`polyc_host::spawn_host`) cannot
        // resolve, since shard 0's peers need shard 1..3's senders, which
        // wouldn't exist yet if each shard built its own channel on spawn.
        let channels: Vec<(mpsc::Sender<Command>, mpsc::Receiver<Command>)> = (0..NUM_SHARDS)
            .map(|_| mpsc::channel::<Command>(COMMAND_BACKLOG))
            .collect();
        let peer_senders: Vec<mpsc::Sender<Command>> =
            channels.iter().map(|(tx, _)| tx.clone()).collect();
        // Shared with every shard's dedicated thread (cloned `Arc`s inside),
        // so a `register_observer` call or a mutation-epoch bump/read on ANY
        // shard's behalf is visible to every other shard immediately — see
        // `src/observer.rs`.
        let write_observers = observer::WriteObservers::new();
        // Every shard's `ShardRouter` — and every partition worker it spawns,
        // all the way down to `partition_worker_loop` — needs the exact same
        // four pieces of state, so build them once here and hand each shard
        // its own clone, rather than threading four separate values through
        // every hop below.
        let shard_ctx = ShardContext {
            storage_dir: storage_dir.clone(),
            signer,
            journal_attestation_trust: journal_attestation_trust.clone(),
            peer_senders,
            write_observers: write_observers.clone(),
        };

        let mut shards = Vec::with_capacity(NUM_SHARDS);
        for (idx, (tx, rx)) in channels.into_iter().enumerate() {
            let body = ShardRouter {
                ctx: shard_ctx.clone(),
                workers: PartitionWorkers::new(),
            };
            // `HostOptions::thread_name` needs a `&'static str`, but every
            // shard needs its OWN distinct name (`eventlog-host-{idx}`) for
            // `top`/panic-backtrace legibility — leaked once per shard
            // (bounded by `NUM_SHARDS`, a fixed, tiny, one-time cost over the
            // process lifetime), the same interning idiom `OpenLogs::get_or_open`
            // already uses for per-partition supervision labels.
            let thread_name: &'static str =
                Box::leak(format!("eventlog-host-{idx}").into_boxed_str());
            let opts = HostOptions {
                thread_name,
                storage_dir: storage_dir.clone(),
                command_backlog: COMMAND_BACKLOG,
            };
            let spawned =
                polyc_host::spawn_host_with_channel(opts, host_shutdown.clone(), body, tx, rx);
            match spawned {
                Ok(handle) => shards.push(handle),
                Err(_err) => {
                    // `Body::open` never fails here (see this method's
                    // `# Errors`), so only `SpawnError::RuntimeStart` is
                    // reachable — matching this host's own single-variant
                    // `HostError`.
                    //
                    // Cancel BEFORE returning: `shards` (already-spawned
                    // `HostHandle`s) is dropped when this function returns,
                    // and unlike the pre-`polyc-host` `Shard` (which had no
                    // `Drop`), `HostHandle::drop` joins its thread. Every
                    // already-running shard still holds a live peer sender
                    // to every OTHER shard (including itself), so channel
                    // closure alone would never end its loop — without this
                    // cancellation, that join would block forever instead of
                    // returning this error.
                    host_shutdown.cancel();
                    return Err(HostError::RuntimeStart);
                }
            }
        }
        Ok(Self {
            shards,
            host_shutdown,
            journal_attestation_public_key,
            journal_attestation_trust,
            write_observers,
        })
    }

    /// Encoded public key used to mint new journal-root attestations.
    ///
    /// Historical root verification uses [`Self::journal_attestation_trust`].
    /// Approval readers receive their separate role trust from Control's
    /// custody loader rather than deriving it from the journal writer.
    #[must_use]
    pub fn journal_attestation_public_key(&self) -> Vec<u8> {
        self.journal_attestation_public_key.clone()
    }

    /// Current and retired public journal-attestation identities.
    #[must_use]
    pub fn journal_attestation_trust(
        &self,
    ) -> polyc_crypto::signing_role::RoleTrustSet<polyc_crypto::signing_role::JournalAttestationRole>
    {
        self.journal_attestation_trust.clone()
    }

    /// Register `observer` to be called after every durable append or
    /// partition mutation this host performs from now on, on whichever
    /// shard's dedicated thread durably commits it. Callable any number of
    /// times to register multiple observers; each is retained for the host's
    /// lifetime and there is no way to unregister one.
    ///
    /// See [`EventLogObserver`] for the ordering guarantee and the
    /// failure-containment policy this host enforces around every call — in
    /// particular, a panicking or slow observer never affects the write path,
    /// but a slow one does delay every OTHER command routed to the same
    /// shard, so `observer` must be cheap. Safe to call from inside another
    /// observer's own callback: callbacks run with the registration lock
    /// already released, so this never reenters it.
    ///
    /// # Panics
    ///
    /// Panics if the internal observer-list lock is poisoned (a prior panic
    /// while it was held). This cannot happen through this crate's own code:
    /// every call into observer code runs inside [`std::panic::catch_unwind`]
    /// and never runs while this lock is held.
    pub fn register_observer(&self, observer: Arc<dyn EventLogObserver>) {
        self.write_observers.register(observer);
    }

    /// This partition's mutation epoch: a process-local counter bumped once
    /// for every durably successful [`destroy_partition`](Self::destroy_partition),
    /// [`rewrite_partition`](Self::rewrite_partition), [`repair_partition`](Self::repair_partition)
    /// that quarantines anything, or one side of a
    /// [`migrate_partition`](Self::migrate_partition) — never by
    /// [`append_batch`](Self::append_batch). Starts at `0` for a partition
    /// this process has never mutated.
    ///
    /// **Process-local, not durable**: this counter resets to `0` on every
    /// restart. That is by design, not a gap — its only sanctioned consumer
    /// is an in-process cache that itself dies with the process, so a stale
    /// epoch value can never outlive the process that produced it. It is not
    /// a substitute for a durable version number and must never be persisted
    /// or compared across a restart.
    ///
    /// # Panics
    ///
    /// Panics if the internal epoch-map lock is poisoned (a prior panic while
    /// it was held). This cannot happen through this crate's own code: every
    /// call into observer code runs inside [`std::panic::catch_unwind`] and
    /// never runs while this lock is held.
    #[must_use]
    pub fn mutation_epoch(&self, partition: &str) -> u64 {
        // The epoch map keys on the LOGICAL name, exactly as every observer
        // notification reports one. The map is a process-local cache, so all
        // it needs is one consistent key — and a caller that holds an epoch
        // holds it for the id it asked about.
        self.write_observers.epoch(partition)
    }

    /// Whether this host has begun shutting down.
    ///
    /// [`AppendError::Closed`] has two producers, and a caller that cannot tell
    /// them apart has to guess wrong on one of them. A shutdown says nothing
    /// about the partition that happened to be in flight, so a derived
    /// projection must leave its state alone and resume after the restart. A
    /// partition worker that PANICKED closes its own receiver
    /// (the shard router's dropped-command path) and answers the same
    /// `Closed` while the process runs on perfectly healthily — and a caller
    /// that reads that as a shutdown freezes that one partition behind a
    /// watermark nothing will ever revisit.
    ///
    /// The token is cancelled by [`EventLogHost::drop`] and by the caller's own
    /// `shutdown`, so `false` here means the process still intends to serve.
    #[must_use]
    pub fn is_shutting_down(&self) -> bool {
        self.host_shutdown.is_cancelled()
    }

    /// Route `partition` to its shard, deterministically for the life of
    /// this host (a partition is never re-homed while the process runs, so
    /// per-partition ordering and the single-open-handle invariant hold
    /// exactly as they did before sharding). The hash need not be stable
    /// across process restarts: each shard's [`OpenLogs`] cache starts cold
    /// and lazily opens whatever partitions land on it.
    fn shard_for(&self, partition: &str) -> &HostHandle<Command> {
        &self.shards[shard_index(partition, self.shards.len())]
    }

    /// This host's shard count, for tests that need to find two partitions
    /// routed to different shards.
    #[cfg(test)]
    #[must_use]
    pub const fn num_shards(&self) -> usize {
        self.shards.len()
    }

    /// Which shard index `partition` is routed to, for tests that need to
    /// find two partitions routed to different shards.
    #[cfg(test)]
    #[must_use]
    pub fn shard_index_for(&self, partition: &str) -> usize {
        shard_index(partition, self.shards.len())
    }

    /// Enumerate every logical partition in the storage directory (#490) —
    /// conversations, memory partitions, audit logs alike. The discovery
    /// primitive for maintenance sweeps over partitions whose names can no
    /// longer be derived from live state. Serialized on the host's single
    /// command loop, so it never observes a partition mid-destruction.
    ///
    /// # Errors
    ///
    /// Returns [`AppendError::Closed`] if the host has shut down, or
    /// [`AppendError::Listing`] if the storage directory cannot be read or
    /// does not describe one fleet.
    pub async fn list_partitions(&self) -> Result<Vec<String>, AppendError> {
        self.list_partitions_bounded(usize::MAX, usize::MAX).await
    }

    /// Enumerates logical partitions without retaining more than either bound.
    ///
    /// # Errors
    ///
    /// Returns the errors from [`Self::list_partitions`]. It also returns a
    /// typed listing error when either transient allocation ceiling is crossed.
    pub async fn list_partitions_bounded(
        &self,
        max_entries: usize,
        max_name_bytes: usize,
    ) -> Result<Vec<String>, AppendError> {
        self.list_partitions_bounded_excluding(max_entries, max_name_bytes, None)
            .await
    }

    /// Enumerates logical partitions, omitting `excluded` before accounting.
    ///
    /// # Errors
    ///
    /// Returns the same typed errors as [`Self::list_partitions_bounded`].
    pub async fn list_partitions_bounded_excluding(
        &self,
        max_entries: usize,
        max_name_bytes: usize,
        excluded: Option<String>,
    ) -> Result<Vec<String>, AppendError> {
        let (ack, ack_rx) = oneshot::channel();
        // Directory enumeration, not partition-keyed: any shard can serve it
        // (it only reads `storage_dir`, never an `OpenLogs` entry), so this
        // pins to shard 0 rather than hashing.
        self.shards[0]
            .sender()
            .ok_or(AppendError::Closed)?
            .send(Command::ListPartitions {
                max_entries,
                max_name_bytes,
                excluded,
                ack,
            })
            .await
            .map_err(|_| AppendError::Closed)?;
        ack_rx
            .await
            .map_err(|_| AppendError::Closed)?
            .map_err(AppendError::Listing)
    }

    /// Report when `partition`'s storage last changed, in milliseconds since
    /// the Unix epoch — the operational fact a retention policy's idle axis is
    /// decided on.
    ///
    /// Partition-level, not event-level: an [`Event`] carries no common
    /// timestamp to sort by (each payload that has one names its own field), so
    /// "idle since" is read off the storage this host owns.
    ///
    /// Answering it here is what lets a caller decide retention without
    /// inspecting the storage directory itself. Nothing is opened to answer, so
    /// asking about a partition this host has never written creates none —
    /// the same property [`Self::partition_event_count`] holds.
    ///
    /// Returns [`None`] for a partition with no storage and for storage that
    /// will not say. Both are "nothing to answer with" rather than a very old
    /// time, so a caller cannot read a storage fault as an idle partition.
    ///
    /// # Errors
    ///
    /// Returns [`AppendError::Closed`] if the host has shut down.
    /// Returns [`AppendError::PartitionName`] for a name that cannot be
    /// stored.
    pub async fn partition_last_modified_ms(
        &self,
        partition: String,
    ) -> Result<Option<u64>, AppendError> {
        let partition = PartitionRef::new(&partition)?;
        let (ack, ack_rx) = oneshot::channel();
        // Directory read, not partition-keyed: it touches `storage_dir` and no
        // `OpenLogs` entry, so it pins to shard 0 exactly as the enumeration
        // it shares that directory read with does.
        self.shards[0]
            .sender()
            .ok_or(AppendError::Closed)?
            .send(Command::PartitionLastModified { partition, ack })
            .await
            .map_err(|_| AppendError::Closed)?;
        ack_rx.await.map_err(|_| AppendError::Closed)
    }

    /// Returns what durable storage survives for `partition`, without opening it.
    ///
    /// The question a caller must ask before a replay, because opening a
    /// partition CREATES it: replaying an unknown name would durably register
    /// a partition that nothing ever wrote to.
    ///
    /// Bounded to the requested key, never an enumeration. A caller asking
    /// about one partition has no business reading every other partition's
    /// identity, and this answer costs the same whatever the fleet holds.
    ///
    /// [`PartitionPresence::Absent`] is the only answer a caller may read as
    /// an empty history. Storage that will not answer reports its error, and a
    /// remnant with no journal data behind it reports
    /// [`PartitionPresence::Damaged`], so a caller cannot mistake a lost
    /// conversation for one that was never written.
    ///
    /// # Errors
    ///
    /// Returns [`AppendError::Closed`] if the host has shut down,
    /// [`AppendError::Listing`] if the volume will not answer, and
    /// [`AppendError::PartitionName`] for a name that cannot be stored.
    pub async fn partition_presence(
        &self,
        partition: String,
    ) -> Result<PartitionPresence, AppendError> {
        let partition = PartitionRef::new(&partition)?;
        let (ack, ack_rx) = oneshot::channel();
        // Directory read, not partition-keyed: pinned to shard 0 exactly as
        // the enumeration and the time probe it shares that directory with.
        self.shards[0]
            .sender()
            .ok_or(AppendError::Closed)?
            .send(Command::ProbePartition { partition, ack })
            .await
            .map_err(|_| AppendError::Closed)?;
        ack_rx
            .await
            .map_err(|_| AppendError::Closed)?
            .map_err(AppendError::Listing)
    }

    /// Move `from`'s events into `to` and destroy `from` (#490 sweep +
    /// merge-ceremony migration).
    ///
    /// Two handler invocations, one per partition, and that split is
    /// deliberate (`#2653`). `from`'s replay and destroy share one invocation
    /// on `from`'s worker. `to`'s read, dedup, re-root, and append share one
    /// on `to`'s own worker. Each partition therefore decides and writes with
    /// nothing landing in between. Reading `to` from `from`'s side cannot give
    /// that. It needs a second round trip, and `to` services other commands
    /// between the two. The append is deduped, so a re-run copies no event
    /// twice. A re-run can still append one signed root, if an earlier
    /// attempt left `to`'s tail unattested. `from == to` is a pure
    /// no-op reported as [`PartitionMigration::Migrated`] with count 0 —
    /// nothing is ever destroyed in that case.
    ///
    /// # Errors
    ///
    /// Returns [`AppendError::Closed`] if the host has shut down, or
    /// [`AppendError::Log`] on a replay or append failure (the source is
    /// left intact). A destroy failure AFTER the copy is not an error — it
    /// reports as [`PartitionMigration::CopiedSourceRemains`] so the caller
    /// can retry the cleanup without re-copying.
    ///
    /// Sharding (`#799`): this routes to `from`'s shard, so the source keeps
    /// the single-handler atomicity described above. The destination side
    /// always routes through `to`'s OWN worker as one internal command —
    /// unconditionally, not only across shards — rather than opening an
    /// independent handle to it from here. Two independent `EventLog` handles
    /// over one on-disk partition could otherwise race, and reading `to` from
    /// this side would need a second round trip that `to` services other
    /// commands between (`#2653`).
    pub async fn migrate_partition(
        &self,
        from: String,
        to: String,
    ) -> Result<PartitionMigration, AppendError> {
        let from = PartitionRef::new(&from)?;
        let to = PartitionRef::new(&to)?;
        let (ack, ack_rx) = oneshot::channel();
        self.shard_for(from.logical())
            .sender()
            .ok_or(AppendError::Closed)?
            .send(Command::MigratePartition { from, to, ack })
            .await
            .map_err(|_| AppendError::Closed)?;
        ack_rx.await.map_err(|_| AppendError::Closed)?
    }

    /// Destroy `partition` wholesale (the #216 erasure primitive): the
    /// cached handle is evicted, the underlying blobs are removed, and a
    /// subsequent open of the same name starts empty. Serialized on the
    /// host's single command loop, so no in-flight append or replay can
    /// race the destruction or resurrect the handle.
    ///
    /// # Errors
    ///
    /// Returns [`AppendError::Closed`] if the host has shut down, or
    /// [`AppendError::Log`] if the blob removal fails.
    /// Returns [`AppendError::PartitionName`] for a name that cannot be
    /// stored.
    pub async fn destroy_partition(&self, partition: String) -> Result<(), AppendError> {
        let partition = PartitionRef::new(&partition)?;
        let (ack, ack_rx) = oneshot::channel();
        self.shard_for(partition.logical())
            .sender()
            .ok_or(AppendError::Closed)?
            .send(Command::DestroyPartition { partition, ack })
            .await
            .map_err(|_| AppendError::Closed)?;
        ack_rx
            .await
            .map_err(|_| AppendError::Closed)?
            .map_err(AppendError::Log)
    }

    /// Rewrite `partition` in place, applying `decide` to each event to keep
    /// it, drop it, or replace its payload (#216/#860 erasure). Race-free
    /// against concurrent appends: the replay, rewrite, destroy, and re-append
    /// all run inside the single host command handler, so nothing interleaves.
    /// Returns the number of events dropped (a replaced event is not counted —
    /// it survives with a new payload).
    ///
    /// `decide` is offered the partition's content events only. Every signed
    /// root the partition carried covered content this rewrite changes, so the
    /// host drops all of them and signs one fresh root over the survivors — see
    /// `rewrite_one`. A rewrite that changes no content is a no-op and leaves
    /// the partition, its roots included, exactly as it was.
    ///
    /// A [`RewriteDecision::Replace`] changes the payload and nothing else: the
    /// event keeps its kind and its trust tag, so a scrub of quarantined
    /// content stays quarantined in the durable record.
    ///
    /// # Errors
    ///
    /// Returns [`AppendError::Closed`] if the host has shut down, or
    /// [`AppendError::Log`] on a replay/destroy/append failure, or when the
    /// fresh root cannot be built or signed.
    /// Returns [`AppendError::PartitionName`] for a name that cannot be
    /// stored.
    /// [`Self::rewrite_partition`] under a command identity derived from the
    /// partition.
    ///
    /// Test-only. A production rewrite carries the excision identity State
    /// recorded before dialing, which is what lets a later attempt find the
    /// stage. A test driving one rewrite to completion has no such record, and
    /// deriving the identity keeps every such test on one stage name.
    #[cfg(test)]
    pub async fn rewrite_partition_for_test(
        &self,
        partition: String,
        decide: Box<dyn Fn(&Event) -> RewriteDecision + Send + Sync>,
    ) -> Result<usize, AppendError> {
        let command_id = format!("test-rewrite-{partition}");
        self.rewrite_partition(partition, command_id, decide).await
    }

    /// Finishes a rewrite of `partition` that `command_id` staged, if one is
    /// waiting.
    ///
    /// Returns the records that rewrite dropped, or `None` when no complete
    /// stage exists. A caller runs this before excising a partition again, so
    /// an excision a crash interrupted is completed rather than decided over
    /// (`#2323`).
    ///
    /// # Errors
    ///
    /// Returns [`AppendError::Closed`] if the host has shut down, or
    /// [`AppendError::Log`] when the stage cannot be read or the restore fails.
    /// Returns [`AppendError::PartitionName`] for a name that cannot be stored.
    pub async fn resume_rewrite_partition(
        &self,
        partition: String,
        command_id: String,
    ) -> Result<Option<usize>, AppendError> {
        let partition = PartitionRef::new(&partition)?;
        let (ack, ack_rx) = oneshot::channel();
        self.shard_for(partition.logical())
            .sender()
            .ok_or(AppendError::Closed)?
            .send(Command::ResumeRewritePartition {
                partition,
                command_id,
                ack,
            })
            .await
            .map_err(|_| AppendError::Closed)?;
        ack_rx.await.map_err(|_| AppendError::Closed)?
    }

    /// Rewrites `partition` in place under the excision identity `command_id`.
    ///
    /// The identity names the durable stage the survivors are written to before
    /// the destroy, so a later attempt at the same command can finish a rewrite
    /// a crash interrupted (`#2323`).
    ///
    /// # Errors
    ///
    /// Returns [`AppendError::Closed`] if the host has shut down, or
    /// [`AppendError::Log`] on a replay/destroy/append failure, or when the
    /// fresh root cannot be built or signed. Returns
    /// [`AppendError::PartitionName`] for a name that cannot be stored.
    pub async fn rewrite_partition(
        &self,
        partition: String,
        command_id: String,
        decide: Box<dyn Fn(&Event) -> RewriteDecision + Send + Sync>,
    ) -> Result<usize, AppendError> {
        let partition = PartitionRef::new(&partition)?;
        let (ack, ack_rx) = oneshot::channel();
        self.shard_for(partition.logical())
            .sender()
            .ok_or(AppendError::Closed)?
            .send(Command::RewritePartition {
                partition,
                command_id,
                decide,
                ack,
            })
            .await
            .map_err(|_| AppendError::Closed)?;
        ack_rx
            .await
            .map_err(|_| AppendError::Closed)?
            .map_err(AppendError::Log)
    }

    /// Plans an exact rewrite without changing `partition`.
    ///
    /// # Errors
    ///
    /// Returns a typed host error when replay, root rebuilding, or signing
    /// fails. No physical state is changed.
    pub async fn inspect_rewrite_partition(
        &self,
        partition: String,
        command_id: String,
        decide: Box<dyn Fn(&Event) -> RewriteDecision + Send + Sync>,
    ) -> Result<RewritePlan, AppendError> {
        let partition = PartitionRef::new(&partition)?;
        let (ack, ack_rx) = oneshot::channel();
        self.shard_for(partition.logical())
            .sender()
            .ok_or(AppendError::Closed)?
            .send(Command::InspectRewrite {
                partition,
                command_id,
                decide,
                ack,
            })
            .await
            .map_err(|_| AppendError::Closed)?;
        ack_rx
            .await
            .map_err(|_| AppendError::Closed)?
            .map_err(AppendError::Log)
    }

    /// Applies one previously inspected exact rewrite.
    ///
    /// # Errors
    ///
    /// Returns a typed host error for storage failures. A physical state that
    /// matches neither the plan nor its bound durable stage reports
    /// [`RewriteApplication::Changed`] instead of being overwritten.
    #[allow(clippy::too_many_arguments)]
    pub async fn apply_rewrite_partition(
        &self,
        partition: String,
        command_id: String,
        before: [u8; 32],
        after: [u8; 32],
        stage_binding: [u8; 32],
        decide: Box<dyn Fn(&Event) -> RewriteDecision + Send + Sync>,
    ) -> Result<RewriteApplication, AppendError> {
        let partition = PartitionRef::new(&partition)?;
        let (ack, ack_rx) = oneshot::channel();
        self.shard_for(partition.logical())
            .sender()
            .ok_or(AppendError::Closed)?
            .send(Command::ApplyRewrite {
                partition,
                command_id,
                before,
                after,
                stage_binding,
                decide,
                ack,
            })
            .await
            .map_err(|_| AppendError::Closed)?;
        ack_rx
            .await
            .map_err(|_| AppendError::Closed)?
            .map_err(AppendError::Log)
    }

    /// Replay `partition`'s log in order — the events that reconstruct a
    /// conversation's state when resuming.
    ///
    /// # Errors
    ///
    /// Returns [`AppendError::Closed`] if the host has shut down, or
    /// [`AppendError::Log`] if opening/replaying the log failed.
    /// Returns [`AppendError::PartitionName`] for a name that cannot be
    /// stored.
    pub async fn replay(&self, partition: String) -> Result<Vec<Event>, AppendError> {
        let partition = PartitionRef::new(&partition)?;
        let (ack, ack_rx) = oneshot::channel();
        self.shard_for(partition.logical())
            .sender()
            .ok_or(AppendError::Closed)?
            .send(Command::Replay { partition, ack })
            .await
            .map_err(|_| AppendError::Closed)?;
        ack_rx
            .await
            .map_err(|_| AppendError::Closed)?
            .map_err(AppendError::Log)
    }

    /// Replay `partition` with each event's durable journal position — the
    /// stable identity a taint-excision marker (`#590`) names. Positions are
    /// the journal's own ordinals, so they survive filtering and projection
    /// (unlike a `Vec` index).
    ///
    /// # Errors
    ///
    /// Returns [`AppendError::Closed`] if the host has shut down, or
    /// [`AppendError::Log`] if opening/replaying the log failed.
    /// Returns [`AppendError::PartitionName`] for a name that cannot be
    /// stored.
    pub async fn replay_with_positions(
        &self,
        partition: String,
    ) -> Result<Vec<(u64, Event)>, AppendError> {
        let partition = PartitionRef::new(&partition)?;
        let (ack, ack_rx) = oneshot::channel();
        self.shard_for(partition.logical())
            .sender()
            .ok_or(AppendError::Closed)?
            .send(Command::ReplayWithPositions { partition, ack })
            .await
            .map_err(|_| AppendError::Closed)?;
        ack_rx
            .await
            .map_err(|_| AppendError::Closed)?
            .map_err(AppendError::Log)
    }

    /// Replay `partition` with each event's durable journal position, same
    /// as [`EventLogHost::replay_with_positions`], but stop reading from the
    /// journal the instant the cumulative payload bytes read exceed
    /// `max_bytes` (issue #1541) — the returned [`BoundedReplay::budget_exceeded`]
    /// reports whether that happened. Unlike [`EventLogHost::replay_tail_from_checkpoint`]'s
    /// "bounded", this bound is a caller-chosen BYTE budget over the
    /// replayed payload, not a checkpoint-relative event range.
    ///
    /// # Errors
    ///
    /// Returns [`AppendError::Closed`] if the host has shut down, or
    /// [`AppendError::Log`] if opening/replaying the log failed.
    /// Returns [`AppendError::PartitionName`] for a name that cannot be
    /// stored.
    pub async fn replay_with_positions_bounded(
        &self,
        partition: String,
        max_bytes: u64,
    ) -> Result<BoundedReplay, AppendError> {
        let partition = PartitionRef::new(&partition)?;
        let (ack, ack_rx) = oneshot::channel();
        self.shard_for(partition.logical())
            .sender()
            .ok_or(AppendError::Closed)?
            .send(Command::ReplayWithPositionsBounded {
                partition,
                max_bytes,
                ack,
            })
            .await
            .map_err(|_| AppendError::Closed)?;
        ack_rx
            .await
            .map_err(|_| AppendError::Closed)?
            .map_err(AppendError::Log)
    }

    /// Replay `partition` starting at journal position `start` (inclusive),
    /// keeping each event's durable position — the primitive a caller-held
    /// watermark resumes from, without re-reading a partition's whole
    /// history. `polyc_query`'s per-partition decode cache is the first
    /// consumer: on a cache hit whose event count has only grown (same
    /// mutation epoch, more events than last seen), it resumes here at its
    /// own cached watermark rather than paying a full replay again.
    ///
    /// Mirrors [`polyc_eventlog::EventLog::replay_from_with_positions`]
    /// exactly: `start` is clamped up to the partition's own pruning
    /// boundary, and a `start` at or past the partition's end yields an
    /// empty `Vec`, not an error.
    ///
    /// # Errors
    ///
    /// Returns [`AppendError::Closed`] if the host has shut down, or
    /// [`AppendError::Log`] if opening/replaying the log failed.
    /// Returns [`AppendError::PartitionName`] for a name that cannot be
    /// stored.
    pub async fn replay_from_with_positions(
        &self,
        partition: String,
        start: u64,
    ) -> Result<Vec<(u64, Event)>, AppendError> {
        let partition = PartitionRef::new(&partition)?;
        let (ack, ack_rx) = oneshot::channel();
        self.shard_for(partition.logical())
            .sender()
            .ok_or(AppendError::Closed)?
            .send(Command::ReplayFromWithPositions {
                partition,
                start,
                ack,
            })
            .await
            .map_err(|_| AppendError::Closed)?;
        ack_rx
            .await
            .map_err(|_| AppendError::Closed)?
            .map_err(AppendError::Log)
    }

    /// Bounded tail replay: [`EventLogHost::replay_from_with_positions`]'s
    /// resume-at-`start` semantics combined with
    /// [`EventLogHost::replay_with_positions_bounded`]'s byte-budget
    /// early-abort, in one call — the primitive `polyc_query`'s per-partition
    /// decode cache uses to resume from its own cached watermark on a cache
    /// tail lookup, without risking an unbounded allocation if the tail
    /// since that watermark turns out to be large (a single oversized
    /// append landing after the partition was last cached). Neither of the
    /// other two methods can express this alone: the bounded replay always
    /// starts at `0`, and the resume-from replay has no byte cap.
    ///
    /// Same clamping/empty-range rule as
    /// [`EventLogHost::replay_from_with_positions`]: `start` is clamped up to
    /// the partition's own pruning boundary, and a `start` at or past the
    /// partition's end yields an empty, `budget_exceeded: false`
    /// [`BoundedReplay`], not an error. Same early-abort rule as
    /// [`EventLogHost::replay_with_positions_bounded`]: replay stops the
    /// instant cumulative payload bytes read (from `start` onward) exceed
    /// `max_bytes`.
    ///
    /// # Errors
    ///
    /// Returns [`AppendError::Closed`] if the host has shut down, or
    /// [`AppendError::Log`] if opening/replaying the log failed.
    /// Returns [`AppendError::PartitionName`] for a name that cannot be
    /// stored.
    pub async fn replay_from_with_positions_bounded(
        &self,
        partition: String,
        start: u64,
        max_bytes: u64,
    ) -> Result<BoundedReplay, AppendError> {
        let partition = PartitionRef::new(&partition)?;
        let (ack, ack_rx) = oneshot::channel();
        self.shard_for(partition.logical())
            .sender()
            .ok_or(AppendError::Closed)?
            .send(Command::ReplayFromWithPositionsBounded {
                partition,
                start,
                max_bytes,
                ack,
            })
            .await
            .map_err(|_| AppendError::Closed)?;
        ack_rx
            .await
            .map_err(|_| AppendError::Closed)?
            .map_err(AppendError::Log)
    }

    /// Replay the half-open position range `[start, end)` — end EXCLUSIVE —
    /// under the same byte budget the sibling bounded replays apply.
    ///
    /// The only replay on this host that accepts an UPPER bound. The others
    /// drain to the journal's tail, capping bytes at most, so a caller that
    /// knows the exact span it wants — one turn's events, located by a prior
    /// index — had to read from `start` to the tail and discard the
    /// remainder. That makes reading a span near the beginning of a long
    /// partition cost the whole partition.
    ///
    /// Delegates verbatim to
    /// [`polyc_eventlog::EventLog::replay_range_with_positions_bounded`]:
    /// `start` clamps up to the pruning boundary and `end` down to the tail,
    /// an empty or inverted range yields an empty
    /// `budget_exceeded: false` [`BoundedReplay`] rather than an error, and
    /// the event that trips the byte budget is included with
    /// `budget_exceeded` set.
    ///
    /// # Errors
    ///
    /// Returns [`AppendError::Closed`] if the host has shut down, or
    /// [`AppendError::Log`] if opening/replaying the log failed.
    /// Returns [`AppendError::PartitionName`] for a name that cannot be
    /// stored.
    pub async fn replay_range_with_positions_bounded(
        &self,
        partition: String,
        start: u64,
        end: u64,
        max_bytes: u64,
    ) -> Result<BoundedReplay, AppendError> {
        let partition = PartitionRef::new(&partition)?;
        let (ack, ack_rx) = oneshot::channel();
        self.shard_for(partition.logical())
            .sender()
            .ok_or(AppendError::Closed)?
            .send(Command::ReplayRangeWithPositionsBounded {
                partition,
                start,
                end,
                max_bytes,
                ack,
            })
            .await
            .map_err(|_| AppendError::Closed)?;
        ack_rx
            .await
            .map_err(|_| AppendError::Closed)?
            .map_err(AppendError::Log)
    }

    /// Bounded replay: the latest compaction checkpoint for `partition` (if any)
    /// plus only the events appended after it. The host caches the latest
    /// checkpoint offset per partition, so the warm path seeks to it (cheap,
    /// position-indexed) instead of re-reading the whole log; a cold partition
    /// pays one full replay to locate the checkpoint, then caches it.
    ///
    /// # Errors
    ///
    /// Returns [`AppendError::Closed`] if the host has shut down, or
    /// [`AppendError::Log`] if opening/replaying the log failed.
    pub async fn replay_tail_from_checkpoint(
        &self,
        partition: String,
    ) -> Result<CheckpointReplay, AppendError> {
        // Normalize identically to `replay`/`append_batch` so a namespaced id
        // (`web:<uuid>`) maps to the same legal on-disk partition. Without this,
        // the raw `:` reaches storage and a fresh conversation's first turn fails
        // with `PartitionNameInvalid` — read as a 503 instead of an empty history.
        let partition = PartitionRef::new(&partition)?;
        let (ack, ack_rx) = oneshot::channel();
        self.shard_for(partition.logical())
            .sender()
            .ok_or(AppendError::Closed)?
            .send(Command::ReplayTailFromCheckpoint { partition, ack })
            .await
            .map_err(|_| AppendError::Closed)?;
        ack_rx
            .await
            .map_err(|_| AppendError::Closed)?
            .map_err(AppendError::Log)
    }

    /// Cheap count of events appended to `partition` since the latest compaction
    /// checkpoint. Reads the journal size (O(1)) and subtracts the cached
    /// checkpoint offset; when no checkpoint is cached the whole log is the tail,
    /// so the count is the journal size. Never scans the log, so the emission
    /// gate can skip the (full) tail replay until the partition is long enough to
    /// possibly need a checkpoint.
    ///
    /// When no checkpoint is cached but a durable one exists (a cold partition
    /// not yet bounded-replayed this process), this OVER-estimates (returns the
    /// whole size). That only matters once the size crosses the gate, at which
    /// point the caller confirms against the real tail (which locates and caches
    /// the durable checkpoint) — so the gate decision stays correct.
    ///
    /// # Errors
    ///
    /// Returns [`AppendError::Closed`] if the host has shut down, or
    /// [`AppendError::Log`] if opening the log failed.
    pub async fn events_since_checkpoint(&self, partition: String) -> Result<u64, AppendError> {
        // Same normalization as the replay/append paths so the checkpoint cache
        // is keyed identically — otherwise a namespaced (`web:<uuid>`) partition
        // misses the cache the bounded replay populates and the cheap gate never
        // fires, leaving those conversations to grow their replay unbounded.
        let partition = PartitionRef::new(&partition)?;
        let (ack, ack_rx) = oneshot::channel();
        self.shard_for(partition.logical())
            .sender()
            .ok_or(AppendError::Closed)?
            .send(Command::EventsSinceCheckpoint { partition, ack })
            .await
            .map_err(|_| AppendError::Closed)?;
        ack_rx
            .await
            .map_err(|_| AppendError::Closed)?
            .map_err(AppendError::Log)
    }

    /// Total number of events durably appended to `partition` — the
    /// journal's tracked length (O(1) via the journal's own size counter),
    /// never a scan. Unlike
    /// [`events_since_checkpoint`](Self::events_since_checkpoint), which is
    /// checkpoint-relative, this counts every event the partition has ever
    /// held, from position `0`; it matches the length a full
    /// [`replay`](Self::replay) would return, without decoding a single
    /// payload to get there.
    ///
    /// Every other read on this host opens the partition first, and opening
    /// a partition creates its on-disk journal even when nothing has ever
    /// been appended (`EventLog::open` is create-or-recover, not
    /// create-if-absent) — which would make a mere count probe destructive.
    /// So a partition with no on-disk journal is never given one just to be
    /// counted: this checks the storage directory first, the same
    /// enumerate-what-already-exists discipline
    /// [`list_partitions`](Self::list_partitions) uses, and reports `0` for
    /// a partition that was never created.
    ///
    /// # Errors
    ///
    /// Returns [`AppendError::Closed`] if the host has shut down,
    /// [`AppendError::Log`] if opening a known partition's log failed,
    /// [`AppendError::Listing`] if the existence check could not answer, or
    /// [`AppendError::PartitionName`] for a name that cannot be stored.
    pub async fn partition_event_count(&self, partition: String) -> Result<u64, AppendError> {
        // Same normalization as every other partition-keyed command, so this
        // checks/opens the exact on-disk name the append path wrote under.
        let partition = PartitionRef::new(&partition)?;
        let (ack, ack_rx) = oneshot::channel();
        self.shard_for(partition.logical())
            .sender()
            .ok_or(AppendError::Closed)?
            .send(Command::PartitionEventCount { partition, ack })
            .await
            .map_err(|_| AppendError::Closed)?;
        ack_rx.await.map_err(|_| AppendError::Closed)?
    }

    /// Appends a batch of events to `partition`'s log in one round trip, and
    /// commits at the end.
    ///
    /// Atomic as a PROTOCOL guarantee, not a storage one. On partial failure
    /// the signed root marker never lands, so the batch does not complete. It
    /// does not follow that the batch left nothing behind: a best-effort commit
    /// can make the prefix already written durable, and a raw replay returns
    /// that prefix unattested. Only the State fold withholds pending records
    /// from logical publication.
    ///
    /// # Errors
    ///
    /// Returns [`AppendError::PayloadTooLarge`] when an event's payload exceeds
    /// the shared decode cap, [`AppendError::Closed`] when the host has shut
    /// down, and [`AppendError::PartitionName`] for a name that cannot be
    /// stored. Each is definite.
    ///
    /// Returns [`AppendError::Log`] when a step BEFORE any mutation fails: the
    /// open, the validation, or the root preparation. Nothing of the batch is
    /// durable.
    ///
    /// Returns [`AppendError::AppendOutcomeUnknown`] when one event's append
    /// fails, and [`AppendError::AttestationOutcomeUnknown`] when the root
    /// marker or the final commit fails. Both are ambiguous: retry the same
    /// higher-level command identity to reconcile.
    pub async fn append_batch(
        &self,
        partition: String,
        events: Vec<Event>,
    ) -> Result<Vec<u64>, AppendError> {
        let partition = PartitionRef::new(&partition)?;
        // Write/read symmetry for the decode cap: every reader rejects
        // payloads over MAX_EVENT_PAYLOAD_BYTES, so persisting one would
        // create a durable entry no replay can ever see (a handoff that
        // "vanishes" from lineage, a message missing from transcripts).
        // Refuse loudly at the single choke point all writers go through.
        // Aggregates (e.g. a Handoff carrying many wire messages, each
        // individually wire-legal) are exactly what can exceed the cap.
        for event in &events {
            if event.payload.len() > polyc_proto::events_decode::MAX_EVENT_PAYLOAD_BYTES {
                return Err(AppendError::PayloadTooLarge {
                    kind: event.kind.clone(),
                    len: event.payload.len(),
                });
            }
        }
        let (ack, ack_rx) = oneshot::channel();
        self.shard_for(partition.logical())
            .sender()
            .ok_or(AppendError::Closed)?
            .send(Command::AppendBatch {
                partition,
                events,
                ack,
            })
            .await
            .map_err(|_| AppendError::Closed)?;
        ack_rx.await.map_err(|_| AppendError::Closed)?
    }

    /// Returns a committed signed-root marker that exactly covers the
    /// partition's current non-root leaf prefix, appending one idempotently
    /// when the newest valid marker is behind it.
    ///
    /// # Errors
    ///
    /// Returns [`AppendError`] when the partition cannot be opened or verified,
    /// evidence cannot be prepared, or publishing new evidence has an
    /// ambiguous storage outcome.
    pub async fn ensure_partition_attested(
        &self,
        partition: String,
    ) -> Result<Option<Event>, AppendError> {
        let partition = PartitionRef::new(&partition)?;
        let (ack, ack_rx) = oneshot::channel();
        self.shard_for(partition.logical())
            .sender()
            .ok_or(AppendError::Closed)?
            .send(Command::EnsurePartitionAttested { partition, ack })
            .await
            .map_err(|_| AppendError::Closed)?;
        ack_rx.await.map_err(|_| AppendError::Closed)?
    }

    /// Replay `partition` and verify its tamper-evidence (`#799`): every
    /// signed MMR root recorded along the way must match the tree replay
    /// itself recomputes, and must be signed by this host's signer key. On
    /// success returns the same events [`Self::replay`] would.
    ///
    /// # Errors
    ///
    /// Returns [`AppendError::Closed`] if the host has shut down, or
    /// [`AppendError::Verify`] if the replay is unreadable or fails
    /// tamper-evidence (a tampered event, a forged marker, or a root signed
    /// under an unexpected key).
    /// Returns [`AppendError::PartitionName`] for a name that cannot be
    /// stored.
    pub async fn replay_verified(&self, partition: String) -> Result<Vec<Event>, AppendError> {
        let partition = PartitionRef::new(&partition)?;
        let (ack, ack_rx) = oneshot::channel();
        self.shard_for(partition.logical())
            .sender()
            .ok_or(AppendError::Closed)?
            .send(Command::ReplayVerified { partition, ack })
            .await
            .map_err(|_| AppendError::Closed)?;
        ack_rx
            .await
            .map_err(|_| AppendError::Closed)?
            .map_err(AppendError::Verify)
    }

    /// Recover `partition` from a corrupted item (`#799`, the `polychrome
    /// conversation repair` quarantine verb): replay every position
    /// independently so one bad item cannot block the rest, then rewrite the
    /// partition retaining only what decoded.
    ///
    /// The rewrite runs when anything was unreadable, and also when the
    /// partition's own signed roots cover events that no longer survive
    /// (`#2561`). The second case returns an EMPTY quarantine list over a
    /// partition that was destroyed, rewritten and re-signed, so an empty list
    /// is not a report that nothing happened. `RepairApplication` and the
    /// mutation epoch are what say whether the partition changed.
    ///
    /// A partition whose roots hold and whose events all decode is a no-op.
    ///
    /// # Errors
    ///
    /// Returns [`AppendError::Closed`] if the host has shut down, or
    /// [`AppendError::Log`] if the replay/destroy/re-append fails.
    /// Returns [`AppendError::PartitionName`] for a name that cannot be
    /// stored.
    pub async fn repair_partition(
        &self,
        partition: String,
    ) -> Result<Vec<QuarantinedItem>, AppendError> {
        let partition = PartitionRef::new(&partition)?;
        let (ack, ack_rx) = oneshot::channel();
        self.shard_for(partition.logical())
            .sender()
            .ok_or(AppendError::Closed)?
            .send(Command::RepairPartition { partition, ack })
            .await
            .map_err(|_| AppendError::Closed)?;
        ack_rx
            .await
            .map_err(|_| AppendError::Closed)?
            .map_err(AppendError::Log)
    }

    /// Inspects a repair without changing the partition.
    ///
    /// The returned fingerprints let a caller durably record the outcome it
    /// must report before asking [`Self::apply_repair_partition`] to perform
    /// the irreversible rewrite.
    ///
    /// # Errors
    ///
    /// Returns [`AppendError::Closed`] if the host stopped, or
    /// [`AppendError::Log`] if storage inspection fails.
    /// Returns [`AppendError::PartitionName`] for a name that cannot be
    /// stored.
    pub async fn inspect_repair_partition(
        &self,
        partition: String,
        replacement: Option<RepairEventReplacement>,
    ) -> Result<RepairPlan, AppendError> {
        let partition = PartitionRef::new(&partition)?;
        let (ack, ack_rx) = oneshot::channel();
        self.shard_for(partition.logical())
            .sender()
            .ok_or(AppendError::Closed)?
            .send(Command::InspectRepair {
                partition,
                replacement,
                ack,
            })
            .await
            .map_err(|_| AppendError::Closed)?;
        ack_rx
            .await
            .map_err(|_| AppendError::Closed)?
            .map_err(AppendError::Log)
    }

    /// Applies a prior repair inspection only if the physical state still
    /// matches its before/after fingerprints.
    ///
    /// # Errors
    ///
    /// Returns [`AppendError::Closed`] if the host stopped, or
    /// [`AppendError::Log`] if storage inspection or repair fails.
    /// Returns [`AppendError::PartitionName`] for a name that cannot be
    /// stored.
    pub async fn apply_repair_partition(
        &self,
        partition: String,
        before: [u8; 32],
        after: [u8; 32],
        replacement: Option<RepairEventReplacement>,
    ) -> Result<RepairApplication, AppendError> {
        let partition = PartitionRef::new(&partition)?;
        let (ack, ack_rx) = oneshot::channel();
        self.shard_for(partition.logical())
            .sender()
            .ok_or(AppendError::Closed)?
            .send(Command::ApplyRepair {
                partition,
                before,
                after,
                replacement,
                ack,
            })
            .await
            .map_err(|_| AppendError::Closed)?;
        ack_rx
            .await
            .map_err(|_| AppendError::Closed)?
            .map_err(AppendError::Log)
    }

    /// Reports whether the repair fenced by `before`/`after` has left the
    /// partition's content in a state a reader may trust.
    ///
    /// A durable repair intent says a repair was admitted. It does not say
    /// how far the repair got. `apply_repair_scan` destroys the target and
    /// then restores it, so a crash inside that window leaves an empty or
    /// partial partition and a zeroed count floor. That partition verifies
    /// trivially and reports healthy (`#2568`).
    ///
    /// This answers the question the intent alone cannot. `false` means the
    /// destructive half is in flight or was abandoned, so the content on disk
    /// is not what the repair promised. A caller must report damage rather
    /// than serve it. `apply_repair_partition` with the same fingerprints
    /// finishes the repair from its durable stage.
    ///
    /// # Errors
    ///
    /// Returns [`AppendError::Closed`] if the host stopped, or
    /// [`AppendError::Log`] if storage inspection fails.
    /// Returns [`AppendError::PartitionName`] for a name that cannot be
    /// stored.
    pub async fn repair_settled(
        &self,
        partition: String,
        before: [u8; 32],
        after: [u8; 32],
    ) -> Result<bool, AppendError> {
        let partition = PartitionRef::new(&partition)?;
        let (ack, ack_rx) = oneshot::channel();
        self.shard_for(partition.logical())
            .sender()
            .ok_or(AppendError::Closed)?
            .send(Command::RepairSettled {
                partition,
                before,
                after,
                ack,
            })
            .await
            .map_err(|_| AppendError::Closed)?;
        ack_rx.await.map_err(|_| AppendError::Closed)?
    }

    /// Removes the survivor stage a rewrite of `partition` under `command_id`
    /// may have left on this storage.
    ///
    /// The rewrite twin of [`Self::destroy_repair_stage`], and it exists for
    /// the same reason: a stage holds a full copy of a conversation, so an
    /// erasure that removes only the named partition is not an erasure. An
    /// excision stages the survivors under its own command identity, which the
    /// caller holds and this storage cannot derive.
    ///
    /// Removing a stage that is not there is not an error, and this never
    /// creates one.
    ///
    /// # Errors
    ///
    /// Returns [`AppendError::Closed`] if the host has shut down,
    /// [`AppendError::PartitionName`] for a name that cannot be stored, or
    /// [`AppendError::Log`] if the removal fails.
    pub async fn destroy_rewrite_stage(
        &self,
        partition: String,
        command_id: String,
    ) -> Result<(), AppendError> {
        let partition = PartitionRef::new(&partition)?;
        let (ack, ack_rx) = oneshot::channel();
        self.shard_for(partition.logical())
            .sender()
            .ok_or(AppendError::Closed)?
            .send(Command::DestroyRewriteStage {
                partition,
                command_id,
                ack,
            })
            .await
            .map_err(|_| AppendError::Closed)?;
        ack_rx.await.map_err(|_| AppendError::Closed)?
    }

    /// Removes the survivor stage a repair of `partition` fingerprinted
    /// `before` may have left on this storage.
    ///
    /// A stage holds a full copy of a conversation, so an erasure that removes
    /// only the named partition is not an erasure. The stage's storage name is
    /// derived from `partition` and `before` and cannot be recovered from the
    /// partition alone, so the caller — which holds the repair record that
    /// names `before` — has to ask for it by both.
    ///
    /// Removing a stage that is not there is not an error, and this never
    /// creates one.
    ///
    /// # Errors
    ///
    /// Returns [`AppendError::Closed`] if the host has shut down,
    /// [`AppendError::PartitionName`] for a name that cannot be stored, or
    /// [`AppendError::Log`] if the removal fails.
    pub async fn destroy_repair_stage(
        &self,
        partition: String,
        before: [u8; 32],
    ) -> Result<(), AppendError> {
        let partition = PartitionRef::new(&partition)?;
        let (ack, ack_rx) = oneshot::channel();
        self.shard_for(partition.logical())
            .sender()
            .ok_or(AppendError::Closed)?
            .send(Command::DestroyRepairStage {
                partition,
                before,
                ack,
            })
            .await
            .map_err(|_| AppendError::Closed)?;
        ack_rx.await.map_err(|_| AppendError::Closed)?
    }
}

impl Drop for EventLogHost {
    fn drop(&mut self) {
        // Cancel first: every shard now holds a live `Command` sender to
        // every OTHER shard (cross-shard migration routing, see
        // `migrate_one`), so dropping only this host's OWN sender copies
        // below no longer closes any channel — each shard's `peer_senders`
        // keeps every channel's sender count above zero for as long as any
        // shard thread is alive. Cancellation is therefore the only
        // shutdown signal `Drop` can rely on.
        //
        // `polyc-host`'s generic `HostHandle::drop` (drop-tx-then-join,
        // INV-H1) is necessary but NOT sufficient on its own here — it is
        // still correct (and still lets a shard's `rx.recv()` return early
        // if it somehow is the last sender), just not what actually ends the
        // loop in the common case, which is why cancellation must happen
        // FIRST, before any `HostHandle` is dropped below.
        self.host_shutdown.cancel();
        // Each `HostHandle`'s own `Drop` drops that shard's sender then
        // joins its thread; by now every shard has already observed
        // `host_shutdown` and is exiting (or has exited), so this can't
        // block waiting on a thread that never gets a shutdown signal.
        self.shards.clear();
    }
}

/// Error appending to the event log from the tokio side.
#[derive(Debug, thiserror::Error)]
pub enum AppendError {
    /// The host has shut down; the event was not persisted.
    #[error("event-log host is shut down")]
    Closed,
    /// The underlying journal open, append, or commit failed.
    #[error(transparent)]
    Log(#[from] EventLogError),
    /// A semantic event append failed after the batch began, so this batch's
    /// outcome is unknown.
    ///
    /// Unknown, and not merely "the failing event did not land". Commonware
    /// reports a mutating operation's error without promising that the
    /// operation left storage untouched, so the append that returned an error
    /// may itself have written bytes. The best-effort commit that follows can
    /// also make an earlier prefix durable. A raw replay exposes that prefix
    /// even with no covering root marker, so the bytes are readable rather
    /// than provably absent.
    ///
    /// An error on the FIRST event is unknown for the same reason. Nothing
    /// here can prove that an errored append recovered its own bytes.
    ///
    /// Reopen and retry the same higher-level command identity to reconcile
    /// the exact prefix.
    #[error("event append outcome is unknown: {0}")]
    AppendOutcomeUnknown(EventLogError),
    /// A signed-root marker append or commit may have reached durable storage,
    /// but the host could not prove its outcome. Reopen and retry the same
    /// higher-level command identity to settle it.
    #[error("signed-root completion outcome is unknown: {0}")]
    AttestationOutcomeUnknown(EventLogError),
    /// A partition listing or existence check could not answer.
    ///
    /// Two failures a caller must keep apart, and
    /// [`ListPartitionsError`] keeps them apart: the volume would not answer,
    /// or it answered and what it holds does not describe one fleet.
    #[error(transparent)]
    Listing(#[from] ListPartitionsError),
    /// A verified replay (`#799`) failed — either the replay itself, or
    /// tamper-evidence over it.
    #[error(transparent)]
    Verify(#[from] VerifyError),
    /// The partition name cannot be stored.
    ///
    /// The adapter's own guard, independent of whatever validated the name
    /// upstream. It runs before any filesystem change, so an unstorable name is
    /// a typed refusal and never a directory create that fails part-way through
    /// a commit.
    #[error(transparent)]
    PartitionName(#[from] PartitionNameError),
    /// An event payload exceeds the shared decode cap
    /// ([`polyc_proto::events_decode::MAX_EVENT_PAYLOAD_BYTES`]) and
    /// would be unreadable by every replay path if persisted.
    #[error("event `{kind}` payload is {len} bytes, over the decode cap")]
    PayloadTooLarge {
        /// Stored kind of the offending event.
        kind: String,
        /// Encoded payload length in bytes.
        len: usize,
    },
}

/// Error starting the event-log host.
#[derive(Debug, thiserror::Error)]
pub enum HostError {
    /// The dedicated Commonware-runtime thread failed before reporting it was
    /// ready (it panicked during runtime startup).
    #[error("event-log runtime thread failed to start")]
    RuntimeStart,
    /// The active signer was not present in the supplied public history.
    #[error("active journal-attestation signer is absent from its trust history")]
    ActiveSignerNotTrusted,
}

/// [`Body`] for one shard: a ROUTER, not a place that itself holds any
/// partition's state (`#1711`). Before this, a shard's `Body` held the
/// per-partition open logs, compaction checkpoints, running MMRs, and
/// durable event-count checkpoints directly (four maps kept in lockstep by
/// hand) and `handle` fully awaited each command against them before
/// dequeuing the next — so two commands for two DIFFERENT partitions routed
/// to the same shard serialized behind each other's full disk-commit
/// latency, even though the k8s `Lease` already guarantees only one writer
/// per CONVERSATION, never per shard.
///
/// Now `handle` only ever does two things: the two storage-directory reads
/// ([`Command::ListPartitions`], a shard-wide filesystem scan, and
/// [`Command::PartitionLastModified`], one directory's times — neither
/// partition-keyed, both answered directly) are handled inline; every other
/// command is forwarded
/// (`.send(cmd).await`, backpressure only, never waiting for the command to
/// actually run) to that command's OWN partition's worker — a lazily
/// spawned, LRU-capped [`tokio` task](commonware_runtime::Spawner::spawn)
/// (see [`PartitionWorkers`]) running on this shard's own already
/// multi-worker-thread Commonware runtime. That worker's own loop
/// (`partition_worker_loop`) is what now holds the four state pieces this
/// struct used to hold directly, and its single sequential
/// `while let Some(cmd) = rx.recv().await` consumer is what gives every
/// command for ONE partition FIFO order and mutual exclusion against every
/// other command for that SAME partition — with zero locks, and with
/// different partitions' workers running as genuinely concurrent tasks.
///
/// `Body::open` is trivially `Ok(())`: this shard has no single "the store"
/// to open eagerly or lazily — individual partitions (via their own worker)
/// open on demand, exactly as they did before this migration.
struct ShardRouter {
    /// Every piece of state this shard's workers need regardless of which
    /// partition they serve — see [`ShardContext`].
    ctx: ShardContext,
    /// This shard's lazily-spawned, LRU-capped partition workers.
    workers: PartitionWorkers,
}

/// The state a shard's [`ShardRouter`] and every partition worker it spawns
/// need, regardless of which partition a given command is for. Bundled into
/// one value — rather than threaded through [`EventLogHost::spawn`],
/// [`ShardRouter`]'s own fields, [`PartitionWorkers::get_or_spawn`], and
/// [`partition_worker_loop`] as four separate parameters — because all four
/// pieces always travel together: every worker on every shard needs the same
/// storage root, the same signer, the same full peer-sender list, and the
/// same observer registry.
#[derive(Clone)]
struct ShardContext {
    /// This shard's storage root — needed by the two directory reads
    /// ([`Command::ListPartitions`] and [`Command::PartitionLastModified`])
    /// [`ShardRouter`] answers directly, and handed to every spawned worker for
    /// its own [`Command::PartitionEventCount`] existence check.
    storage_dir: PathBuf,
    /// Signs this shard's per-partition MMR roots (`#799`/`#784`) — handed to
    /// every spawned worker.
    signer: JournalAttestationSigner,
    /// Current and retired journal-attestation identities accepted on replay.
    journal_attestation_trust: polyc_crypto::signing_role::RoleTrustSet<
        polyc_crypto::signing_role::JournalAttestationRole,
    >,
    /// Every shard's command sender, including this shard's own — see
    /// [`EventLogHost::spawn`]'s doc on why these must all exist before any
    /// shard's thread starts. Handed to every spawned worker so a
    /// [`Command::MigratePartition`] handler ([`migrate_one`]) can always
    /// reach its destination partition's OWN worker this way, whether that
    /// worker lives on this shard or a different one — see [`migrate_one`]'s
    /// doc for why there is no longer a same-shard fast path.
    peer_senders: Vec<mpsc::Sender<Command>>,
    /// Shared, cross-shard write-observation state (registered observers +
    /// per-partition mutation epochs) — see `src/observer.rs`. Handed to
    /// every spawned worker.
    write_observers: observer::WriteObservers,
}

#[async_trait::async_trait]
impl Body for ShardRouter {
    type Cmd = Command;

    async fn open(&mut self, _ctx: &commonware_runtime::tokio::Context) -> Result<(), String> {
        // Lazy: no single "the store" exists at the shard level — individual
        // partitions open on demand inside a worker's own `handle_command`
        // call, exactly like the pre-`polyc-host` `run_dedicated`'s deferred
        // first open.
        Ok(())
    }

    async fn handle(&mut self, ctx: &commonware_runtime::tokio::Context, cmd: Command) {
        // Shard-wide filesystem enumeration, not partition-keyed: answered
        // directly, no worker involved — exactly as `ListPartitions` always
        // was. Every other variant is keyed by a partition (see
        // `partition_key`) and routed to that partition's own worker.
        if let Command::ListPartitions {
            max_entries,
            max_name_bytes,
            excluded,
            ack,
        } = cmd
        {
            let _ = ack.send(list_partitions_bounded_in(
                &self.ctx.storage_dir,
                max_entries,
                max_name_bytes,
                excluded.as_deref(),
            ));
            return;
        }
        // Also a directory read rather than a partition's log: answered here
        // for the same reason, and so that asking about a partition this host
        // has never written neither spawns a worker for it nor opens it.
        if let Command::PartitionLastModified { partition, ack } = cmd {
            let _ = ack.send(last_modified_ms_in(&self.ctx.storage_dir, &partition));
            return;
        }
        if let Command::ProbePartition { partition, ack } = cmd {
            let _ = ack.send(
                partition_presence_in(ctx, &self.ctx.storage_dir, partition.storage_key()).await,
            );
            return;
        }
        let partition = partition_key(&cmd).to_owned();
        let tx = self.workers.get_or_spawn(ctx, &self.ctx, &partition).await;
        // Backpressure on a full per-partition queue only — never await the
        // command's actual processing, so this shard's own loop can
        // immediately dequeue its next inbound command regardless of how
        // long `cmd` takes to run on `partition`'s worker.
        if tx.send(cmd).await.is_err() {
            // The worker we just looked up/spawned closed its receiver
            // between `get_or_spawn` returning and this send (it can only
            // have panicked — a worker never voluntarily closes its own
            // receiver while registered in `self.workers`). Dropping `cmd`
            // here drops its embedded `ack` sender too, so the caller sees
            // exactly the same `Closed`/channel-dropped outcome any other
            // shutdown race already produces — nothing silently hangs.
            tracing::warn!(
                partition = %partition,
                "partition worker channel closed immediately after dispatch; command dropped"
            );
        }
    }

    /// Retire every still-running partition worker: close its channel (which
    /// lets its own loop finish draining whatever was already queued, then
    /// sync its still-open log and return) and await its task. Replaces what
    /// used to be a direct `for log in self.logs.values() { log.sync().await }`
    /// over this shard's own maps — those maps no longer exist here; each
    /// worker now owns and syncs its own state.
    async fn on_drain_complete(&mut self, _ctx: &commonware_runtime::tokio::Context) {
        self.workers.retire_all().await;
    }
}

/// Extract the routing key — the partition [`ShardRouter::handle`] forwards
/// a command to that partition's own worker by — from every [`Command`]
/// variant except the two storage-directory reads,
/// [`Command::ListPartitions`] and [`Command::PartitionLastModified`] (neither
/// is partition-keyed; callers must handle both before reaching here — the
/// second names a partition but is answered from the directory, so routing it
/// to that partition's worker would open a partition a mere probe must not
/// create).
///
/// [`Command::MigratePartition`] routes by its `from` field (the side this
/// handler's own atomicity guarantee covers — see [`migrate_one`]);
/// [`Command::MigrateAppendInto`] routes by its `partition` field (always the
/// LOCAL destination side of a migration, dispatched here by
/// [`remote_migrate_append_into`]).
///
/// # Panics
///
/// Panics if called with [`Command::ListPartitions`],
/// [`Command::PartitionLastModified`] or [`Command::ProbePartition`] — none
/// has a partition key, and none must ever reach this function.
fn partition_key(cmd: &Command) -> &str {
    match cmd {
        Command::Replay { partition, .. }
        | Command::ReplayWithPositions { partition, .. }
        | Command::ReplayWithPositionsBounded { partition, .. }
        | Command::ReplayTailFromCheckpoint { partition, .. }
        | Command::ReplayFromWithPositions { partition, .. }
        | Command::ReplayFromWithPositionsBounded { partition, .. }
        | Command::ReplayRangeWithPositionsBounded { partition, .. }
        | Command::EventsSinceCheckpoint { partition, .. }
        | Command::PartitionEventCount { partition, .. }
        | Command::DestroyPartition { partition, .. }
        | Command::AppendBatch { partition, .. }
        | Command::EnsurePartitionAttested { partition, .. }
        | Command::RewritePartition { partition, .. }
        | Command::InspectRewrite { partition, .. }
        | Command::ApplyRewrite { partition, .. }
        | Command::ResumeRewritePartition { partition, .. }
        | Command::ReplayVerified { partition, .. }
        | Command::RepairPartition { partition, .. }
        | Command::InspectRepair { partition, .. }
        | Command::ApplyRepair { partition, .. }
        | Command::RepairSettled { partition, .. }
        | Command::DestroyRepairStage { partition, .. }
        | Command::DestroyRewriteStage { partition, .. }
        | Command::MigrateAppendInto { partition, .. } => partition.logical(),
        Command::MigratePartition { from, .. } => from.logical(),
        Command::ListPartitions { .. }
        | Command::PartitionLastModified { .. }
        | Command::ProbePartition { .. } => {
            unreachable!(
                "the storage-directory reads are not partition-keyed; each is handled \
                 before this is called"
            )
        }
    }
}

/// Cap on concurrently-running partition worker tasks per shard — the
/// worker-task-level analog of [`LOGS_CAP`] (which bounds open [`EventLog`]
/// handles the same way, one level below this). Picked to match `LOGS_CAP`:
/// a worker holds at most one open log handle, so bounding live workers at
/// the same number bounds open file handles and resident memory the same
/// way the old shard-wide [`OpenLogs`] cache did.
const PARTITION_WORKERS_CAP: usize = LOGS_CAP;

/// One partition's live worker task: the channel to reach it, and the
/// supervised task handle so eviction/shutdown can await it fully retiring
/// (draining its queue and syncing its state) before considering it gone.
struct PartitionWorker {
    /// Forward a [`Command`] for this worker's own partition here. The
    /// worker's single-consumer loop gives every command sent here FIFO
    /// order and mutual exclusion against every other command for the SAME
    /// partition.
    tx: mpsc::Sender<Command>,
    /// The worker's own supervised task ([`commonware_runtime::Spawner::spawn`]),
    /// running `partition_worker_loop` on this shard's Commonware runtime.
    task: commonware_runtime::utils::Handle<()>,
}
/// A metric-label body for `partition`, valid for the runtime's registry.
///
/// The registry ASSERTS that a label matches `[a-zA-Z][a-zA-Z0-9_]*`, so a
/// label that does not is a panic on a shard worker thread, not a bad name.
/// Two things can break the leading character: a partition whose own name
/// starts with a digit, and — since #1748 — an ENCODED name whose first byte
/// was escaped, because an escape starts with `_`. A logical name beginning
/// with an uppercase letter encodes to `_41...`, which is exactly that case.
///
/// This is the metric alphabet, NOT the storage codec. It stays many-to-one on
/// purpose: two partitions may legitimately share a metric label, and the
/// registry shares one metric for a duplicate name rather than failing.
fn metric_label_body(partition: &str) -> String {
    let sanitized: String = partition
        .chars()
        .map(|c| if c.is_ascii_alphanumeric() { c } else { '_' })
        .collect();
    if sanitized.starts_with(|c: char| c.is_ascii_alphabetic()) {
        sanitized
    } else {
        format!("p{sanitized}")
    }
}

/// Bounded LRU cache of spawned partition worker tasks, mirroring
/// [`OpenLogs`]'s shape at the worker-task level instead of the
/// open-log-handle level: each partition gets its OWN worker, spawned
/// lazily on first command, evicted (LRU) once live workers would exceed
/// [`PARTITION_WORKERS_CAP`].
struct PartitionWorkers {
    /// Live workers keyed by partition.
    workers: HashMap<String, PartitionWorker>,
    /// Access order; front = least recently used.
    order: std::collections::VecDeque<String>,
    /// Each distinct partition's supervision-tree/metrics label, leaked once
    /// and reused for every subsequent respawn of that SAME partition (an
    /// LRU eviction followed by a new command for the same partition spawns
    /// a fresh worker, but must not leak a fresh label to name it) — see
    /// [`Self::worker_label`]. Unlike [`PARTITION_WORKERS_CAP`], which bounds
    /// concurrently-LIVE workers, this map is bounded only by the number of
    /// DISTINCT partitions ever seen on this shard over the process
    /// lifetime — the same bound `#1713` fixed for `OpenLogs::log_labels`,
    /// its sibling per-partition leak.
    worker_labels: HashMap<String, &'static str>,
}

impl PartitionWorkers {
    fn new() -> Self {
        Self {
            workers: HashMap::new(),
            order: std::collections::VecDeque::new(),
            worker_labels: HashMap::new(),
        }
    }

    /// This partition's `_worker`-suffixed supervision-tree label, interning
    /// (leaking) it on the first call for a given `partition` and reusing
    /// that same leaked `&'static str` on every later call — including every
    /// respawn after an LRU eviction of the SAME partition. Without this
    /// reuse, `get_or_spawn` would leak a fresh label on every respawn, not
    /// just once per distinct partition name, growing unboundedly under
    /// eviction churn rather than staying bounded by the number of distinct
    /// partitions this shard has ever seen.
    fn worker_label(&mut self, partition: &str) -> &'static str {
        if let Some(label) = self.worker_labels.get(partition) {
            return label;
        }
        let label: &'static str =
            Box::leak(format!("{}_worker", metric_label_body(partition)).into_boxed_str());
        self.worker_labels.insert(partition.to_owned(), label);
        label
    }

    /// Mark `partition`'s worker as most-recently-used.
    fn touch(&mut self, partition: &str) {
        // Linear in `order.len()` (bounded by `PARTITION_WORKERS_CAP`); fine
        // at this size — the exact same trade-off `OpenLogs::touch` makes.
        self.order.retain(|p| p != partition);
        self.order.push_back(partition.to_owned());
    }

    /// Look up `partition`'s worker, lazily spawning a fresh one if none
    /// exists yet (evicting the least-recently-touched worker first if that
    /// would exceed [`PARTITION_WORKERS_CAP`]), and return an owned clone of
    /// its sender.
    async fn get_or_spawn(
        &mut self,
        ctx: &commonware_runtime::tokio::Context,
        shard_ctx: &ShardContext,
        partition: &str,
    ) -> mpsc::Sender<Command> {
        if let Some(worker) = self.workers.get(partition) {
            let tx = worker.tx.clone();
            self.touch(partition);
            return tx;
        }

        let (tx, rx) = mpsc::channel::<Command>(COMMAND_BACKLOG);
        // A distinct supervision-tree/metrics label per worker — a `_worker`
        // suffix keeps this from colliding with `OpenLogs::get_or_open`'s own
        // per-partition label or with `get_or_open_count_checkpoint`'s
        // `_ckpt` one, since a worker's own state nests both underneath this
        // child. Interned per DISTINCT partition name (`#1712`'s sibling fix
        // — see `worker_label`'s doc) rather than leaked fresh on every
        // spawn, so an LRU-evict-then-respawn cycle for the same partition
        // reuses the one label already leaked for it instead of leaking
        // another.
        let label = self.worker_label(partition);
        let worker_ctx = ctx.child(label);
        let shard_ctx = shard_ctx.clone();
        let task =
            worker_ctx.spawn(move |worker_ctx| partition_worker_loop(worker_ctx, rx, shard_ctx));
        self.workers.insert(
            partition.to_owned(),
            PartitionWorker {
                tx: tx.clone(),
                task,
            },
        );
        self.touch(partition);

        while self.workers.len() > PARTITION_WORKERS_CAP {
            let Some(evict) = self.order.pop_front() else {
                break;
            };
            if let Some(worker) = self.workers.remove(&evict) {
                Self::retire(&evict, worker).await;
            }
        }

        tx
    }

    /// Close `worker`'s channel (its own loop drains whatever was already
    /// queued, syncs its state, then returns) and await its task — used both
    /// by LRU eviction and by full shutdown ([`Self::retire_all`]).
    async fn retire(partition: &str, worker: PartitionWorker) {
        drop(worker.tx);
        if let Err(err) = worker.task.await {
            tracing::warn!(
                partition,
                error = %err,
                "partition worker task ended with an error while retiring"
            );
        }
    }

    /// Retire every still-running worker — the router's shutdown epilogue.
    async fn retire_all(&mut self) {
        self.order.clear();
        for (partition, worker) in self.workers.drain() {
            Self::retire(&partition, worker).await;
        }
    }
}

/// One partition worker's whole life: owns this partition's [`OpenLogs`]
/// (holding at most this ONE partition's log, since only commands for this
/// partition are ever routed here), compaction checkpoint, durable
/// event-count checkpoint, and running MMR — what a shard's [`ShardRouter`]
/// used to hold directly for EVERY partition it saw (`#1711`). Runs until
/// its `rx` closes (the router dropped this worker's sender, either evicting
/// it under LRU pressure or retiring every worker at shutdown), then syncs
/// whatever log it still has open before returning — the same epilogue
/// `ShardRouter::on_drain_complete` used to run directly, now run by each
/// worker for its own single partition.
async fn partition_worker_loop(
    ctx: commonware_runtime::tokio::Context,
    mut rx: mpsc::Receiver<Command>,
    shard_ctx: ShardContext,
) {
    let mut logs = OpenLogs::new();
    let mut checkpoints = HashMap::new();
    let mut count_checkpoints = CountCheckpoints::new();
    let mut mmr_logs = HashMap::new();

    while let Some(cmd) = rx.recv().await {
        handle_command(
            &ctx,
            &shard_ctx.storage_dir,
            &mut logs,
            &mut checkpoints,
            &mut count_checkpoints,
            &mut mmr_logs,
            &shard_ctx.signer,
            &shard_ctx.journal_attestation_trust,
            &shard_ctx.peer_senders,
            &shard_ctx.write_observers,
            cmd,
        )
        .await;
    }

    for log in logs.values() {
        if let Err(err) = log.sync().await {
            tracing::warn!(error = %err, "partition worker: event-log sync on retirement failed");
        }
    }
}

/// Maximum number of `EventLog`s the host keeps open concurrently. Picked to
/// comfortably cover live-conversation working sets while bounding open file
/// handles and resident memory.
const LOGS_CAP: usize = 256;

/// Bounded LRU cache of open `EventLog`s, keyed by partition.
///
/// Access (open / reuse) moves the partition to the back of `order`; insertion
/// past `LOGS_CAP` syncs and drops the partition at the front (least recently
/// used). Every append batch already ends in an explicit `commit()` (data
/// blobs fsynced — see [`append_batch_one`]), so there are no unflushed data
/// bytes left by the time a partition reaches the front of the LRU. The
/// eviction/shutdown `sync()` here adds a different guarantee: it advances
/// the offsets recovery watermark, so the next open needs no recovery work
/// to rebuild the position index — belt-and-braces durability, not a rescue
/// of unflushed bytes.
struct OpenLogs<E>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    /// Open logs keyed by partition name.
    map: std::collections::HashMap<String, EventLog<E>>,
    /// Access order; front = least recently used.
    order: std::collections::VecDeque<String>,
    /// Each distinct partition's supervision-tree/metrics label, leaked once
    /// and reused for every subsequent reopen of that SAME partition (an LRU
    /// eviction followed by a later `get_or_open` for the same partition
    /// reopens a fresh [`EventLog`], but must not leak a fresh label to name
    /// it) — see [`Self::log_label`]. Unlike [`LOGS_CAP`], which bounds
    /// concurrently-OPEN handles, this map is bounded only by the number of
    /// DISTINCT partitions ever seen on this shard over the process
    /// lifetime — the exact defect `#1713` tracked, mirroring
    /// [`PartitionWorkers::worker_label`]'s already-fixed sibling leak.
    log_labels: HashMap<String, &'static str>,
}

impl<E> OpenLogs<E>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    fn new() -> Self {
        Self {
            map: std::collections::HashMap::new(),
            order: std::collections::VecDeque::new(),
            log_labels: HashMap::new(),
        }
    }

    /// This partition's supervision-tree/metrics label, interning (leaking)
    /// it on the first call for a given `partition` and reusing that same
    /// leaked `&'static str` on every later call — including every reopen
    /// after an LRU eviction of the SAME partition. Without this reuse,
    /// `get_or_open` would leak a fresh label on every reopen, not just once
    /// per distinct partition name, growing unboundedly under eviction churn
    /// rather than staying bounded by the number of distinct partitions this
    /// shard has ever seen (`#1713`).
    fn log_label(&mut self, partition: &str) -> &'static str {
        if let Some(label) = self.log_labels.get(partition) {
            return label;
        }
        // `Supervisor::child` (2026.5) requires a `&'static str` that matches
        // `[a-zA-Z][a-zA-Z0-9_]*` — see [`metric_label_body`], which also
        // guarantees the leading character the registry asserts on.
        let label: &'static str = Box::leak(metric_label_body(partition).into_boxed_str());
        self.log_labels.insert(partition.to_owned(), label);
        label
    }

    fn values(&self) -> impl Iterator<Item = &EventLog<E>> {
        self.map.values()
    }

    /// Whether `partition` already has an open handle cached — true only if
    /// some earlier `get_or_open` already created its on-disk journal, so a
    /// caller can skip a redundant existence check for the warm-cache case.
    fn contains(&self, partition: &str) -> bool {
        self.map.contains_key(partition)
    }

    /// Remove `partition`'s handle from the cache entirely (destruction
    /// path): after this, only a fresh `get_or_open` can reach the name.
    fn take(&mut self, partition: &str) -> Option<EventLog<E>> {
        self.order.retain(|p| p != partition);
        self.map.remove(partition)
    }

    /// Mark `partition` as most-recently-used.
    fn touch(&mut self, partition: &str) {
        // Linear in `order.len()` (bounded by `LOGS_CAP`); fine at this size.
        self.order.retain(|p| p != partition);
        self.order.push_back(partition.to_owned());
    }

    /// Open or recover `partition`'s log, touching it as most-recently-used.
    /// Evicts the least-recently-used log (syncing it first) if the cache is
    /// over capacity.
    async fn get_or_open(
        &mut self,
        context: &E,
        partition: &str,
    ) -> Result<&EventLog<E>, EventLogError> {
        if self.map.contains_key(partition) {
            self.touch(partition);
            return Ok(self
                .map
                .get(partition)
                .expect("present per the contains check"));
        }
        // A distinct supervision-tree node per partition keeps the
        // Commonware metric registry from colliding across conversations.
        // Interned per DISTINCT partition name (`#1713` — see
        // `log_label`'s doc) rather than leaked fresh on every open, so an
        // LRU-evict-then-reopen cycle for the same partition reuses the one
        // label already leaked for it instead of leaking another. Bounded by
        // the number of distinct partitions this shard has ever seen, not by
        // `LOGS_CAP` (which only bounds concurrently-open handles).
        let label = self.log_label(partition);
        let ctx = context.child(label);
        let log = EventLog::open(ctx, EventLogConfig::for_partition(partition)).await?;
        self.map.insert(partition.to_owned(), log);
        self.order.push_back(partition.to_owned());
        while self.map.len() > LOGS_CAP {
            let Some(evict) = self.order.pop_front() else {
                break;
            };
            if let Some(log) = self.map.remove(&evict) {
                if let Err(err) = log.sync().await {
                    tracing::warn!(partition = %evict, error = %err, "LRU evict: sync failed");
                }
                tracing::debug!(partition = %evict, "LRU-evicted open eventlog");
            }
        }
        Ok(self.map.get(partition).expect("just inserted"))
    }
}

/// Dispatch one [`Command`] against the per-partition logs, acking the caller.
#[allow(clippy::too_many_arguments, clippy::too_many_lines)]
async fn handle_command<E>(
    context: &E,
    storage_dir: &std::path::Path,
    logs: &mut OpenLogs<E>,
    checkpoints: &mut HashMap<String, CheckpointFrame>,
    count_checkpoints: &mut CountCheckpoints<E>,
    mmr_logs: &mut HashMap<String, polyc_mmr::VerifiableLog>,
    signer: &JournalAttestationSigner,
    journal_attestation_trust: &polyc_crypto::signing_role::RoleTrustSet<
        polyc_crypto::signing_role::JournalAttestationRole,
    >,
    peer_senders: &[mpsc::Sender<Command>],
    write_observers: &observer::WriteObservers,
    cmd: Command,
) where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    // The ack receiver may have dropped (caller gave up); ignoring the send
    // result is intentional.
    match cmd {
        Command::Replay { partition, ack } => {
            let result = replay_one(context, logs, partition.storage_key()).await;
            let _ = ack.send(result);
        }
        Command::ReplayWithPositions { partition, ack } => {
            let result = replay_with_positions_one(context, logs, partition.storage_key()).await;
            let _ = ack.send(result);
        }
        Command::ReplayWithPositionsBounded {
            partition,
            max_bytes,
            ack,
        } => {
            let result = replay_with_positions_bounded_one(
                context,
                logs,
                partition.storage_key(),
                max_bytes,
            )
            .await;
            let _ = ack.send(result);
        }
        Command::ReplayTailFromCheckpoint { partition, ack } => {
            let result = replay_tail_one(context, logs, checkpoints, partition.storage_key()).await;
            let _ = ack.send(result);
        }
        Command::ReplayFromWithPositions {
            partition,
            start,
            ack,
        } => {
            let result =
                replay_from_with_positions_one(context, logs, partition.storage_key(), start).await;
            let _ = ack.send(result);
        }
        Command::ReplayFromWithPositionsBounded {
            partition,
            start,
            max_bytes,
            ack,
        } => {
            let result = replay_from_with_positions_bounded_one(
                context,
                logs,
                partition.storage_key(),
                start,
                max_bytes,
            )
            .await;
            let _ = ack.send(result);
        }
        Command::ReplayRangeWithPositionsBounded {
            partition,
            start,
            end,
            max_bytes,
            ack,
        } => {
            let result = replay_range_with_positions_bounded_one(
                context,
                logs,
                partition.storage_key(),
                start,
                end,
                max_bytes,
            )
            .await;
            let _ = ack.send(result);
        }
        Command::EventsSinceCheckpoint { partition, ack } => {
            let result =
                events_since_checkpoint_one(context, logs, checkpoints, partition.storage_key())
                    .await;
            let _ = ack.send(result);
        }
        Command::PartitionEventCount { partition, ack } => {
            let result =
                partition_event_count_one(context, storage_dir, logs, partition.storage_key())
                    .await;
            let _ = ack.send(result);
        }
        Command::AppendBatch {
            partition,
            events,
            ack,
        } => {
            let result = append_batch_one(
                context,
                logs,
                checkpoints,
                count_checkpoints,
                mmr_logs,
                signer,
                partition.storage_key(),
                &events,
            )
            .await;
            if let Ok(positions) = &result {
                write_observers.notify_append(partition.logical(), &events, positions);
            }
            let _ = ack.send(result);
        }
        Command::EnsurePartitionAttested { partition, ack } => {
            let result = ensure_partition_attested_one(
                context,
                storage_dir,
                logs,
                count_checkpoints,
                mmr_logs,
                signer,
                journal_attestation_trust,
                partition.storage_key(),
            )
            .await;
            let _ = ack.send(result);
        }
        Command::DestroyPartition { partition, ack } => {
            // A name with nothing durable behind it is erased already, and
            // opening one to remove it would MINT the storage this command
            // exists to remove — a data directory and a checkpoint store for a
            // conversation that never had either. So the probe decides first.
            //
            // It has to be presence, not just the data directory. An erase
            // that emptied the journal and then failed to reclaim it leaves a
            // present-but-empty partition, and an erase interrupted inside the
            // reclaim leaves a bare index remnant. Both are `Present` or
            // `Damaged` here, so both fall through to the destruction below
            // and converge on absence when this command is redriven. Only
            // `Absent` is already the end state.
            //
            // A probe that cannot read the volume falls through rather than
            // deciding: the destruction below reports the real storage
            // failure, which is the same rule `repair_settled_one` follows.
            let already_erased = matches!(
                Box::pin(partition_presence_in(
                    context,
                    storage_dir,
                    partition.storage_key()
                ))
                .await,
                Ok(PartitionPresence::Absent)
            );
            let result = if already_erased {
                // Announced by whoever actually erased it, not here. The
                // observer contract is that a notification follows a mutation
                // that landed on disk, and this branch changed nothing.
                //
                // The state plane makes this ordinary rather than rare: one
                // logical destruction stages its intent and then completes it,
                // and both halves reconcile the same intent against the host.
                // The second reaches an already-erased partition. Bumping the
                // epoch here would announce every destruction twice.
                Ok(())
            } else {
                let destroyed = destroy_one(
                    context,
                    logs,
                    checkpoints,
                    count_checkpoints,
                    mmr_logs,
                    partition.storage_key(),
                    DestroyCheckpoint::Clear,
                )
                .await;
                // The volume decides whether the erasure happened, not the
                // removal's own return value.
                //
                // Commonware's runtime maps EVERY `remove_dir_all` failure to
                // `PartitionMissing`, and both `Partition::remove_all` and
                // `Metadata::destroy` read that as success. A real I/O failure
                // part-way through a removal therefore answers `Ok` over a
                // remnant it did not remove. Acking that would have the state
                // plane write a completion receipt and retire its destruction
                // intent, leaving a remnant no workflow comes back for — and
                // every later read of that conversation refuses it as damage,
                // permanently.
                //
                // Four `symlink_metadata` calls, and the same probe the fast
                // path above already runs, to make the answer honest. The
                // refusal is retryable by the same command: it reopens the
                // remnant, resets it, and reclaims again.
                let verified = match destroyed {
                    Err(error) => Err(error),
                    Ok(()) => {
                        if matches!(
                            Box::pin(partition_presence_in(
                                context,
                                storage_dir,
                                partition.storage_key()
                            ))
                            .await,
                            Ok(PartitionPresence::Absent)
                        ) {
                            Ok(())
                        } else {
                            tracing::error!(
                                partition = %partition.storage_key(),
                                runbook = "docs/operations/eventlog-disaster-recovery.md",
                                "erasure reported success while durable storage survived it; \
                                 the partition is not erased and the command is retryable"
                            );
                            Err(EventLogError::EraseIncomplete)
                        }
                    }
                };
                if verified.is_ok() {
                    write_observers.notify_mutation_bumping_epoch(
                        partition.logical(),
                        &MutationKind::Destroyed,
                    );
                }
                verified
            };
            let _ = ack.send(result);
        }
        Command::ResumeRewritePartition {
            partition,
            command_id,
            ack,
        } => {
            let stage = rewrite_stage_partition(partition.storage_key(), &command_id);
            let result = resume_rewrite(
                context,
                storage_dir,
                logs,
                checkpoints,
                count_checkpoints,
                mmr_logs,
                partition.storage_key(),
                &stage,
            )
            .await
            .map_err(AppendError::Log);
            if let Ok(Some(dropped)) = &result {
                write_observers.notify_mutation_bumping_epoch(
                    partition.logical(),
                    &MutationKind::Rewritten { dropped: *dropped },
                );
            }
            let _ = ack.send(result);
        }
        Command::RewritePartition {
            partition,
            command_id,
            decide,
            ack,
        } => {
            let result = rewrite_one(
                context,
                storage_dir,
                logs,
                checkpoints,
                count_checkpoints,
                mmr_logs,
                signer,
                &command_id,
                partition.storage_key(),
                decide.as_ref(),
            )
            .await;
            if let Ok(dropped) = &result {
                write_observers.notify_mutation_bumping_epoch(
                    partition.logical(),
                    &MutationKind::Rewritten { dropped: *dropped },
                );
            }
            let _ = ack.send(result);
        }
        Command::InspectRewrite {
            partition,
            command_id,
            decide,
            ack,
        } => {
            let result = async {
                let all = {
                    let log = logs.get_or_open(context, partition.storage_key()).await?;
                    log.replay().await?
                };
                inspect_exact_rewrite(
                    partition.storage_key(),
                    &command_id,
                    &all,
                    signer,
                    decide.as_ref(),
                )
                .map(|(plan, _, _)| plan)
            }
            .await;
            let _ = ack.send(result);
        }
        Command::ApplyRewrite {
            partition,
            command_id,
            before,
            after,
            stage_binding,
            decide,
            ack,
        } => {
            let result = apply_exact_rewrite(
                context,
                logs,
                checkpoints,
                count_checkpoints,
                mmr_logs,
                signer,
                partition.storage_key(),
                &command_id,
                RewritePlan {
                    before,
                    after,
                    stage_binding,
                },
                decide.as_ref(),
            )
            .await;
            if let Ok(RewriteApplication::Applied { dropped }) = &result {
                write_observers.notify_mutation_bumping_epoch(
                    partition.logical(),
                    &MutationKind::Rewritten { dropped: *dropped },
                );
            }
            let _ = ack.send(result);
        }
        Command::ListPartitions {
            max_entries,
            max_name_bytes,
            excluded,
            ack,
        } => {
            let _ = ack.send(list_partitions_bounded_in(
                storage_dir,
                max_entries,
                max_name_bytes,
                excluded.as_deref(),
            ));
        }
        Command::PartitionLastModified { partition, ack } => {
            let _ = ack.send(last_modified_ms_in(storage_dir, &partition));
        }
        Command::ProbePartition { partition, ack } => {
            let _ = ack
                .send(partition_presence_in(context, storage_dir, partition.storage_key()).await);
        }
        Command::MigratePartition { from, to, ack } => {
            let result = migrate_one(
                context,
                logs,
                checkpoints,
                count_checkpoints,
                mmr_logs,
                peer_senders,
                &from,
                &to,
                write_observers,
            )
            .await;
            let _ = ack.send(result);
        }
        Command::MigrateAppendInto {
            partition,
            events,
            from,
            ack,
        } => {
            let result = migrate_append_into(
                context,
                logs,
                count_checkpoints,
                mmr_logs,
                signer,
                &partition,
                &events,
                write_observers,
                &from,
            )
            .await;
            let _ = ack.send(result);
        }
        Command::ReplayVerified { partition, ack } => {
            let result = replay_verified_one(
                context,
                logs,
                count_checkpoints,
                journal_attestation_trust,
                partition.storage_key(),
            )
            .await;
            let _ = ack.send(result);
        }
        Command::RepairPartition { partition, ack } => {
            let result = repair_one(
                context,
                logs,
                checkpoints,
                count_checkpoints,
                mmr_logs,
                signer,
                journal_attestation_trust,
                partition.storage_key(),
            )
            .await;
            // On the rewrite, never on the quarantine count. A stale-root
            // repair rewrites the partition and drops nothing (`#2561`), and a
            // cache keyed on this epoch would keep serving the pre-repair
            // decode of a partition whose positions and roots just changed.
            if let Ok(effect) = &result
                && effect.rewrote
            {
                write_observers.notify_mutation_bumping_epoch(
                    partition.logical(),
                    &MutationKind::Repaired {
                        quarantined: effect.quarantined.len(),
                    },
                );
            }
            let _ = ack.send(result.map(|effect| effect.quarantined));
        }
        Command::InspectRepair {
            partition,
            replacement,
            ack,
        } => {
            let result = inspect_repair_one(
                context,
                logs,
                count_checkpoints,
                signer,
                journal_attestation_trust,
                partition.storage_key(),
                replacement.as_ref(),
            )
            .await
            .map(|scan| scan.plan());
            let _ = ack.send(result);
        }
        Command::ApplyRepair {
            partition,
            before,
            after,
            replacement,
            ack,
        } => {
            let result = apply_repair_conditionally(
                context,
                logs,
                checkpoints,
                count_checkpoints,
                mmr_logs,
                signer,
                journal_attestation_trust,
                partition.storage_key(),
                RepairFingerprints { before, after },
                replacement.as_ref(),
            )
            .await;
            if let Ok((RepairApplication::Applied, quarantined)) = &result {
                write_observers.notify_mutation_bumping_epoch(
                    partition.logical(),
                    &MutationKind::Repaired {
                        quarantined: *quarantined,
                    },
                );
            }
            let _ = ack.send(result.map(|(application, _)| application));
        }
        Command::DestroyRewriteStage {
            partition,
            command_id,
            ack,
        } => {
            let stage = rewrite_stage_partition(partition.storage_key(), &command_id);
            let result = destroy_stage_if_present(
                context,
                storage_dir,
                logs,
                checkpoints,
                count_checkpoints,
                mmr_logs,
                &stage,
            )
            .await;
            let _ = ack.send(result);
        }
        Command::DestroyRepairStage {
            partition,
            before,
            ack,
        } => {
            let stage = repair_stage_partition(partition.storage_key(), &before);
            let result = destroy_stage_if_present(
                context,
                storage_dir,
                logs,
                checkpoints,
                count_checkpoints,
                mmr_logs,
                &stage,
            )
            .await;
            let _ = ack.send(result);
        }
        Command::RepairSettled {
            partition,
            before,
            after,
            ack,
        } => {
            let result = repair_settled_one(
                context,
                storage_dir,
                logs,
                count_checkpoints,
                signer,
                journal_attestation_trust,
                partition.storage_key(),
                RepairFingerprints { before, after },
            )
            .await;
            let _ = ack.send(result);
        }
    }
}

/// This shard's resident durable event-count checkpoints, and the only place
/// one is mutated.
///
/// Caches handles exactly like [`OpenLogs`] caches journal handles (see
/// `polyc_eventlog::checkpoint` for what this store guards against), with one
/// rule this type exists to enforce.
///
/// # Poisoning
///
/// Commonware states that an error from a mutable storage operation — `put`,
/// `delete`, or `sync` — is unrecoverable, and the caller must not use that
/// database instance again. `Metadata::sync` advances its in-memory cursor and
/// next version before the writes that can fail, so a failed instance
/// describes a durable state that does not exist. Reusing one would report
/// that phantom state as the partition's floor.
///
/// So every mutation here TAKES the handle out of the map, and puts it back
/// only if the mutation succeeded. `EventCountCheckpoint::record` and `clear`
/// consume the store and return it, so a failure has nothing to put back:
/// there is no code path that can reinsert a poisoned instance, rather than a
/// rule saying not to. The next attempt reopens from durable storage.
///
/// This type is also why no accessor hands out a `&mut` into the map. A
/// borrow that outlives the mutation would make the poisoned instance
/// impossible to remove.
struct CountCheckpoints<E>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    /// Resident handles, keyed by partition storage name. A handle is here
    /// only while Commonware still vouches for it.
    map: HashMap<String, polyc_eventlog::EventCountCheckpoint<E>>,
    /// Each distinct partition's supervision-tree label, interned once and
    /// reused for every later reopen of that SAME partition.
    ///
    /// Interning is load-bearing now rather than tidy: a mutation reopens the
    /// store whenever the handle is not resident, so a label leaked per open
    /// would grow with mutation traffic instead of with the number of distinct
    /// partitions this shard has seen — the `#1713` leak, in the one map that
    /// evicts most often. [`OpenLogs::log_label`] does the same for journals.
    labels: HashMap<String, &'static str>,
}

impl<E> CountCheckpoints<E>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    fn new() -> Self {
        Self {
            map: HashMap::new(),
            labels: HashMap::new(),
        }
    }

    /// This partition's supervision-tree label, interned on first use.
    ///
    /// A DISTINCT label from the partition's own [`EventLog`] child
    /// ([`OpenLogs::log_label`]), so the two Commonware metric registrations
    /// under the same shard root never collide.
    fn label(&mut self, partition: &str) -> &'static str {
        if let Some(label) = self.labels.get(partition) {
            return label;
        }
        let sanitized: String = partition
            .chars()
            .map(|c| if c.is_ascii_alphanumeric() { c } else { '_' })
            .collect();
        let label: &'static str = Box::leak(format!("{sanitized}_ckpt").into_boxed_str());
        self.labels.insert(partition.to_owned(), label);
        label
    }

    /// Whether `partition`'s handle is resident.
    #[cfg(test)]
    fn contains(&self, partition: &str) -> bool {
        self.map.contains_key(partition)
    }

    /// Drop `partition`'s resident handle, if any.
    ///
    /// For a partition whose storage is gone: the handle describes a store
    /// that no longer exists.
    fn forget(&mut self, partition: &str) {
        self.map.remove(partition);
    }

    /// Take `partition`'s handle out of the map, opening it cold if it is not
    /// resident.
    ///
    /// The caller owns what comes back. It returns to the map only through
    /// [`Self::keep`], and only after the operation that may have poisoned it
    /// succeeded.
    async fn take(
        &mut self,
        context: &E,
        partition: &str,
    ) -> Result<polyc_eventlog::EventCountCheckpoint<E>, EventLogError> {
        if let Some(checkpoint) = self.map.remove(partition) {
            return Ok(checkpoint);
        }
        let label = self.label(partition);
        // Boxed, like every other Commonware `Metadata` future in this type.
        //
        // They are fat — a `Metadata` open carries its whole recovery, and a
        // sync carries its rotation — and this type is awaited from
        // `handle_command`, `apply_repair_scan`, and their callers, whose own
        // state machines would each carry a copy inline. Measured: boxing the
        // three of them takes `handle_command`'s future from 17,856 bytes to
        // 8,648, under `clippy::large_futures`' 16 KiB budget and under what
        // it was before this type existed. A checkpoint operation is I/O
        // bound, so one heap allocation per call costs nothing at this rate.
        Box::pin(polyc_eventlog::EventCountCheckpoint::open(
            context.child(label),
            partition,
        ))
        .await
    }

    /// Return a handle Commonware still vouches for to the map.
    fn keep(&mut self, partition: &str, checkpoint: polyc_eventlog::EventCountCheckpoint<E>) {
        self.map.insert(partition.to_owned(), checkpoint);
    }

    /// The durable floor `partition` records, opening the store if needed.
    ///
    /// A read cannot poison the instance — only a mutable operation can — so
    /// the handle goes straight back.
    ///
    /// # Errors
    ///
    /// Returns [`EventLogError::Checkpoint`] if the store cannot be opened.
    async fn expected_count(&mut self, context: &E, partition: &str) -> Result<u64, EventLogError> {
        let checkpoint = self.take(context, partition).await?;
        let count = checkpoint.expected_count();
        self.keep(partition, checkpoint);
        Ok(count)
    }

    /// Durably record `count` as `partition`'s floor.
    ///
    /// # Errors
    ///
    /// Returns [`EventLogError::Checkpoint`] if the store cannot be opened or
    /// the durable sync fails. A failed sync leaves no resident handle.
    async fn record(
        &mut self,
        context: &E,
        partition: &str,
        count: u64,
    ) -> Result<(), EventLogError> {
        let checkpoint = self.take(context, partition).await?;
        // `record` consumes the store. On failure it is dropped with the
        // error and never reaches `keep`, which is the whole eviction
        // mechanism: there is nothing here that could put it back.
        let checkpoint = Box::pin(checkpoint.record(count)).await?;
        self.keep(partition, checkpoint);
        Ok(())
    }

    /// Durably clear `partition`'s floor.
    ///
    /// # Errors
    ///
    /// Returns [`EventLogError::Checkpoint`] if the store cannot be opened or
    /// the durable sync fails. A failed sync leaves no resident handle, for
    /// the reason [`Self::record`] gives.
    async fn clear(&mut self, context: &E, partition: &str) -> Result<(), EventLogError> {
        let checkpoint = self.take(context, partition).await?;
        let checkpoint = Box::pin(checkpoint.clear()).await?;
        self.keep(partition, checkpoint);
        Ok(())
    }

    /// Drop every resident handle, modelling a cold process.
    ///
    /// Test-only: production evicts one partition at a time.
    #[cfg(test)]
    fn evict_all(&mut self) {
        self.map.clear();
    }
}

/// Move one partition's events into another and destroy the source.
///
/// The source side stays in this one handler invocation. The replay and the
/// destroy therefore cannot be split, so no append to the source can land
/// between them and be lost. The destination side is a SEPARATE command on
/// `to`'s own worker ([`Command::MigrateAppendInto`]). That command reads,
/// dedups, re-roots, and appends together, so no append to the destination
/// can land inside ITS window either (`#2653`).
///
/// The append is deduplicated against the destination's existing events by
/// exact `(kind, payload)` bytes, which makes the move idempotent at the
/// journal level: a retry after a destroy failure, or a second racing
/// migration of the same source, copies no event twice. Such a retry can
/// still append ONE signed root, if an earlier attempt left the
/// destination's tail unattested. That is bounded. The root attests the
/// tail, so the retry after it appends nothing at all. Byte-identical
/// duplicates cannot arise legitimately in memory partitions (every event
/// kind there carries a distinguishing id or timestamp), so the dedup never
/// collapses genuine content.
///
/// Each event is carried whole, so its trust tag round-trips. The set is not
/// whole: the source's signed roots are dropped, because a root commits to
/// positions the destination will not reproduce (`#2653`). A destroy
/// failure after the copy is reported as
/// [`PartitionMigration::CopiedSourceRemains`], never an error the caller
/// could mistake for "nothing happened".
///
/// This fixes FORWARD. A partition that a migration from before `#2653`
/// already poisoned stays poisoned. Nothing here repairs it, because the bad
/// root is already durable and `verify_replay` checks every marker it walks.
/// Neither recovery primitive repairs it either: `repair_one` rewrites only
/// an unreadable position, and a poisoned root reads fine; `rewrite_one`
/// returns early when its predicate changes no content, so a keep-everything
/// rewrite does not re-root. Acceptable because production data here is a
/// wipeable test instance.
///
/// `to` is ALWAYS reached the same way now (`#1711`): as a command
/// ([`Command::MigrateAppendInto`]) dispatched through
/// `peer_senders` to `to`'s own shard's ROUTER — never by touching `logs`
/// (this handler's OWN partition worker's state) directly, even when `to`
/// happens to hash to this same shard. Before the per-partition-worker
/// refactor, a same-shard `to` was read and appended directly against the
/// shard's own (then shard-wide) maps as a "local fast path"; that path is
/// gone because those maps no longer exist at the shard level — `logs` here
/// is `from`'s worker's own state, which never holds `to`'s entry, so
/// reaching `to` locally would mean opening a SECOND, independent `EventLog`
/// handle over `to`'s on-disk partition from the wrong worker, race with
/// whatever worker `to`'s own commands are routed to. Always going through
/// `peer_senders[to_shard]` — including when `to_shard` equals this handler's
/// own shard — routes to `to`'s own worker exactly like a genuinely
/// cross-shard call always did, so there is only one path, not two to keep
/// in sync.
///
/// This never deadlocks, same-shard included: `from`'s worker (this
/// function) is one tokio task; the shard-level router it sends into via
/// `peer_senders[to_shard]` — even when `to_shard` is the shard `from`'s
/// worker itself lives on — is a DIFFERENT, independently-scheduled task
/// that only ever forwards a command and immediately loops back for its next
/// one. It is never blocked waiting on any one worker, so this self-send is
/// serviced the same way any other inbound command is. Migrations are rare,
/// operator-triggered moves (merge ceremonies, `#490` sweeps) that never call
/// back into the originating partition, so this cannot deadlock against
/// itself; two migrations racing in opposite directions at the same
/// instant is a theoretical residual risk this accepts rather than adding a
/// global migration lock for.
#[allow(clippy::too_many_arguments)]
async fn migrate_one<E>(
    context: &E,
    logs: &mut OpenLogs<E>,
    checkpoints: &mut HashMap<String, CheckpointFrame>,
    count_checkpoints: &mut CountCheckpoints<E>,
    mmr_logs: &mut HashMap<String, polyc_mmr::VerifiableLog>,
    peer_senders: &[mpsc::Sender<Command>],
    from: &PartitionRef,
    to: &PartitionRef,
    write_observers: &observer::WriteObservers,
) -> Result<PartitionMigration, AppendError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    // A same-partition "move" must never destroy anything — a genuine no-op,
    // so it fires no observer notification and bumps no epoch: nothing about
    // either partition's durable content changed.
    if from == to {
        return Ok(PartitionMigration::Migrated(0));
    }
    let source = {
        let log = logs.get_or_open(context, from.storage_key()).await?;
        log.replay().await?
    };
    if source.is_empty() {
        destroy_one(
            context,
            logs,
            checkpoints,
            count_checkpoints,
            mmr_logs,
            from.storage_key(),
            DestroyCheckpoint::Clear,
        )
        .await?;
        write_observers.notify_mutation_bumping_epoch(
            from.logical(),
            &MutationKind::MigrationSource {
                to: to.logical().to_owned(),
            },
        );
        return Ok(PartitionMigration::EmptyDestroyed);
    }

    let to_shard = shard_index(to.logical(), peer_senders.len());
    // The source's signed roots must NOT travel (`#2653`). A root commits to a
    // leaf sequence at ITS OWN positions — `polyc_mmr::leaf_digest` takes the
    // position — so the same events landing at different positions in `to`
    // cannot reproduce it. A carried root therefore describes a sequence the
    // destination does not have, and the destination reports tamper for good.
    //
    // This is the defect `#2322` fixed for `repair_one`, in the sibling that
    // fix did not reach. `repaired_content` is the shape mirrored below.
    //
    // The DESTINATION's own roots stay. Each covers a prefix this migration
    // does not disturb: those leaves keep their positions and their content,
    // so each marker still verifies where it sits.
    let carried: Vec<Event> = source
        .into_iter()
        .filter(|ev| ev.kind != polyc_eventlog::MMR_SIGNED_ROOT_KIND)
        .collect();
    // Dedup and the re-root happen on `to`'s own worker, not here (`#2653`).
    // Deciding either from this side needs a read of `to` in a separate
    // round trip, and `to` services other commands in between.
    let appended = if carried.is_empty() {
        0
    } else {
        // The destination-side notification (`MigrationDestination`) fires
        // from inside `migrate_append_into` itself, which this always
        // reaches through `to`'s own shard's router now — see this
        // function's own doc for why there is no longer a local/remote
        // split to keep in sync.
        remote_migrate_append_into(peer_senders, to_shard, to, carried, from).await?
    };
    match destroy_one(
        context,
        logs,
        checkpoints,
        count_checkpoints,
        mmr_logs,
        from.storage_key(),
        DestroyCheckpoint::Clear,
    )
    .await
    {
        Ok(()) => {
            write_observers.notify_mutation_bumping_epoch(
                from.logical(),
                &MutationKind::MigrationSource {
                    to: to.logical().to_owned(),
                },
            );
            Ok(PartitionMigration::Migrated(appended))
        }
        Err(err) => {
            tracing::warn!(%from, %to, error = %err, "partition migration: events copied but the source destroy failed; a re-run retries the destroy without re-copying");
            Ok(PartitionMigration::CopiedSourceRemains(appended))
        }
    }
}

/// Decide and append this migration's candidate `events` into `to`'s log, then
/// evict `to`'s cached MMR and refresh its durable
/// event-count checkpoint. This is the [`Command::MigrateAppendInto`]
/// handler — the ONE place a migration's destination-side write lands,
/// whether `to` happens to be on the same shard as `from` or a different
/// one, since [`migrate_one`] always reaches `to` the same way now (as a
/// dispatched command, through `to`'s own worker) rather than through a
/// same-shard fast path that touched `to`'s state directly.
///
/// Also fires the destination-side observer notification
/// ([`MutationKind::MigrationDestination`]) once the events are durably
/// appended — putting the notification here (rather than at the call site)
/// keeps it to one implementation regardless of which shard `from` lived on.
/// `from` is carried only for that notification; it plays no role in the
/// append itself.
///
/// `#1741`: gives `to`'s write the same "fatal for the current handle" shape
/// [`append_batch_one`] has (`#1712`) — on a per-event append error,
/// best-effort commits whatever already landed and evicts `to`'s cached
/// handle before returning the error; a final-commit error evicts the
/// handle directly. `migrate_one`'s own dedup-on-retry keeps a subsequent
/// retry idempotent once the handle is force-reopened cleanly.
// Nine parameters, two over clippy's default threshold of seven.
// `write_observers` already bundles what used to be two loose parameters.
// `from` names the source for the observer notification. `signer` arrived
// when this function took over the re-root (`#2653`).
#[allow(clippy::too_many_arguments)]
async fn migrate_append_into<E>(
    context: &E,
    logs: &mut OpenLogs<E>,
    count_checkpoints: &mut CountCheckpoints<E>,
    mmr_logs: &mut HashMap<String, polyc_mmr::VerifiableLog>,
    signer: &JournalAttestationSigner,
    to: &PartitionRef,
    events: &[Event],
    write_observers: &observer::WriteObservers,
    from: &PartitionRef,
) -> Result<usize, EventLogError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    if events.is_empty() {
        return Ok(0);
    }
    let log = logs.get_or_open(context, to.storage_key()).await?;

    // Read, dedup, re-root, and append in ONE command on this partition's own
    // worker (`#2653`). The caller cannot do this: it would read `to` in one
    // round trip and append in another, and this worker services other
    // commands in between. An `AppendBatch` landing in that window shifts
    // every later leaf position, so a root minted against the earlier read
    // describes content `to` does not have — the same unrepairable mismatch a
    // carried root produces, just minted here instead of imported.
    let existing = log.replay().await?;
    let present: std::collections::HashSet<(&str, &[u8])> = existing
        .iter()
        .map(|ev| (ev.kind.as_str(), ev.payload.as_slice()))
        .collect();
    let fresh: Vec<Event> = events
        .iter()
        .filter(|ev| !present.contains(&(ev.kind.as_str(), ev.payload.as_slice())))
        .cloned()
        .collect();
    // Nothing new to move is NOT the same as nothing to do (`#2653`).
    //
    // A previous attempt can land every event and then fail on the marker
    // itself — the best-effort commit below makes those events durable, and
    // the caller retries. On that retry dedup finds everything present, so
    // returning here would destroy the source and leave the destination
    // holding migrated content with nothing attesting it. `replay_verified`
    // passes on that partition, because an unattested tail verifies trivially.
    //
    // So the question is not "is there anything new" but "does this partition
    // end in a root". Re-root when it does not.
    //
    // This checks the tail's KIND only. Requiring the tail root's leaf count
    // to match the leaves present looks stronger, and was measured: it detects
    // a partition poisoned before `#2653`, but it repairs nothing. A root
    // already in the log stays in the log, `verify_replay` checks EVERY
    // marker, and the caller destroys the source either way. Repair needs
    // `rewrite_one`, not an append. See
    // `a_re_root_cannot_repair_a_root_that_covers_the_wrong_leaves`.
    let tail_is_attested = existing
        .last()
        .is_some_and(|ev| ev.kind == polyc_eventlog::MMR_SIGNED_ROOT_KIND);
    if fresh.is_empty() && tail_is_attested {
        return Ok(0);
    }
    let appended = fresh.len();

    // Re-root over what this partition will hold, the way `repaired_content`
    // does after a repair. Signed BEFORE anything is written, so a signing
    // failure leaves `to` untouched and the caller's source intact.
    let mut settled = existing;
    settled.extend(fresh.iter().cloned());
    let tree = polyc_eventlog::rebuild_from_events(&settled)?;
    let marker = polyc_eventlog::extend_and_sign(&tree, &[], signer)?;
    // Named apart from the `events` parameter on purpose. The observer below
    // reports how many events came FROM the source, and the marker was minted
    // here — shadowing made `events.len()` silently include it (`#2653`).
    let mut to_write: Vec<Event> = fresh;
    to_write.push(marker);
    for (idx, event) in to_write.iter().enumerate() {
        // `#1712`-style fault-injection hook, reused here for `#1741` — see
        // `maybe_inject_append_failure`'s doc. Always `None` outside test
        // builds.
        let append_result = match maybe_inject_append_failure(to.storage_key(), idx) {
            Some(err) => Err(err),
            None => log.append(event).await,
        };
        if let Err(err) = append_result {
            // Best-effort: commit what we've written so the journal stays
            // healthy for the next command touching `to`.
            if let Err(commit_err) = log.commit().await {
                tracing::warn!(error = %commit_err, "commit of partial migration batch failed");
            }
            // `#1741`/`#1712`: this handle is now "fatal" per Commonware's
            // own contract — evict it so the next command touching `to`
            // reopens (and replays) fresh instead of reusing possibly
            // -inconsistent in-memory state.
            logs.take(to.storage_key());
            // `#1788`, same hazard as `append_batch_one`'s per-event failure:
            // the best-effort commit just above can land events, pushing `to`'s
            // journal ahead of what its cached tree has seen. Leaving the cache
            // means the next batch signs a root over a tree shorter than disk,
            // and that marker can never verify. Evict it.
            mmr_logs.remove(to.storage_key());
            return Err(err);
        }
    }
    // Same fault-injection hook as the per-event loop above, but for the
    // FINAL commit. Always `None` outside test builds.
    let commit_result = match maybe_inject_commit_failure(to.storage_key()) {
        Some(err) => Err(err),
        None => log.commit().await,
    };
    if let Err(err) = commit_result {
        // `#1741`/`#1712`: same reasoning as the per-event append error
        // above — a failed commit is just as "fatal for the current handle".
        logs.take(to.storage_key());
        // `#1740`, same hazard as `append_batch_one`'s commit failure: the
        // re-root above already built a tree over content this failed commit
        // did not land. Evict, so the next batch rebuilds from what is durable.
        mmr_logs.remove(to.storage_key());
        return Err(err);
    }
    // The fresh root above extended a tree this function built locally from a
    // replay, not `to`'s cached running MMR (`#2653`). So that cache no longer
    // matches this partition's journal content. Evict it; the next
    // `AppendBatch` on `to` rebuilds fresh from a full replay, which covers
    // the migrated events and the root just written.
    mmr_logs.remove(to.storage_key());
    // Durable event-count checkpoint (`#799` hardening): `to` now durably
    // contains its pre-migration content, the events that moved, and the root
    // minted over the result, so raise its
    // expected count to match — otherwise a subsequent verify would
    // (falsely) see the migrated-in events as unexpected shrink relative to
    // whatever `to`'s OWN checkpoint last claimed, or (more importantly)
    // never learn about growth it should now assert. This is likewise
    // best-effort: see `append_batch_one`.
    let new_len = log.len().await;
    // Best-effort, and the handle is gone either way: `record` evicts a store
    // whose durable sync failed, so the next attempt reopens from disk rather
    // than trusting an instance Commonware no longer vouches for.
    if let Err(err) = count_checkpoints
        .record(context, to.storage_key(), new_len)
        .await
    {
        tracing::warn!(%to, error = %err, "event-count checkpoint record failed after migration (#799)");
    }
    write_observers.notify_mutation_bumping_epoch(
        to.logical(),
        &MutationKind::MigrationDestination {
            from: from.logical().to_owned(),
            appended,
        },
    );
    Ok(appended)
}

/// Ask `to`'s own shard to decide and append this migration's events (see
/// [`migrate_one`] and [`Command::MigrateAppendInto`]).
///
/// The destination dedups and re-roots inside that one command, so the count
/// it returns is what it actually appended. `from` is carried through only for
/// that shard's own observer notification.
async fn remote_migrate_append_into(
    peer_senders: &[mpsc::Sender<Command>],
    shard: usize,
    partition: &PartitionRef,
    events: Vec<Event>,
    from: &PartitionRef,
) -> Result<usize, AppendError> {
    let (ack, ack_rx) = oneshot::channel();
    peer_senders[shard]
        .send(Command::MigrateAppendInto {
            partition: partition.clone(),
            events,
            from: from.clone(),
            ack,
        })
        .await
        .map_err(|_| AppendError::Closed)?;
    ack_rx
        .await
        .map_err(|_| AppendError::Closed)?
        .map_err(AppendError::Log)
}

/// Enumerate the logical partitions under `storage_dir`.
///
/// The journal lays each logical partition out as a `{name}_data` directory
/// (events) plus a `{name}_offsets` sibling (index), so the logical names are
/// recovered by taking directories with the data suffix and stripping it. That
/// layout is the storage engine's convention, not ours — the host test pins it
/// through the real stack (append → list), so an engine upgrade that changes
/// it fails loudly there instead of silently listing nothing.
///
/// A missing storage directory means no partition was ever created (the
/// engine creates it lazily on first write), so it lists as empty rather than
/// erroring. Names come back sorted for deterministic sweeps and tests.
#[cfg(test)]
fn list_partitions_in(storage_dir: &std::path::Path) -> Result<Vec<String>, ListPartitionsError> {
    list_partitions_bounded_in(storage_dir, usize::MAX, usize::MAX, None)
}

/// Lists a whole logical directory while bounding its transient name vector.
fn list_partitions_bounded_in(
    storage_dir: &std::path::Path,
    max_entries: usize,
    max_name_bytes: usize,
    excluded: Option<&str>,
) -> Result<Vec<String>, ListPartitionsError> {
    const DATA_SUFFIX: &str = "_data";
    let entries = match std::fs::read_dir(storage_dir) {
        Ok(entries) => entries,
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(Vec::new()),
        Err(e) => return Err(ListPartitionsError::Storage(e)),
    };
    let mut partitions = Vec::new();
    let mut name_bytes = 0_usize;
    // Every partition-shaped remnant this scan walks past, so a partition
    // whose journal data is gone cannot be silently dropped from a listing
    // that then calls itself complete. Resolved after the loop, against the
    // data directories the same pass found.
    let mut data_dirs: std::collections::BTreeSet<String> = std::collections::BTreeSet::new();
    let mut remnants: Vec<String> = Vec::new();
    for entry in entries {
        let entry = entry.map_err(ListPartitionsError::Storage)?;
        if !entry
            .file_type()
            .map_err(ListPartitionsError::Storage)?
            .is_dir()
        {
            continue;
        }
        let name = entry.file_name();
        // Shape first, identity second. A directory this listing does not
        // claim is not its business, whatever its bytes are — an OS artifact,
        // an operator's copy, a restored snapshot. Demanding a decodable name
        // before checking the shape would fail the WHOLE page for one of
        // those, and this listing fails whole by design, so that is a
        // deployment-wide read outage until somebody removes the directory.
        let Some(physical) = name.as_encoded_bytes().strip_suffix(DATA_SUFFIX.as_bytes()) else {
            // Not a data directory. It may still be a remnant of one, which is
            // this listing's business precisely because it has no `_data` to
            // list it under.
            if let Some(remnant) = partition_shaped_remnant(&name) {
                remnants.push(remnant);
            }
            continue;
        };
        // Partition-shaped and not UTF-8 is corruption, exactly like a name
        // that will not decode: this deployment writes every partition through
        // the codec, so nothing legitimate lands here.
        let Some(physical) = std::str::from_utf8(physical).ok() else {
            return Err(ListPartitionsError::Corrupt {
                entry: name.to_string_lossy().into_owned(),
            });
        };
        // Registered BEFORE every filter below. A partition this listing hides
        // — a repair stage, the administrative partition a caller excluded —
        // still owns its index siblings. A remnant check that could not see
        // its `_data` would call those siblings orphans and fail the whole
        // fleet listing over storage that is perfectly intact.
        data_dirs.insert(physical.to_owned());
        // Repair stages are valid internal state that this listing owns and
        // hides. They are not corruption, and the codec refuses the namespace
        // at the boundary, so a caller cannot mint one.
        if physical.starts_with(REPAIR_STAGE_PREFIX)
            || physical.starts_with(REWRITE_STAGE_PREFIX)
            || physical.starts_with(EXACT_REWRITE_STAGE_PREFIX)
        {
            continue;
        }
        let logical =
            partition_name::decode(physical).map_err(|_| ListPartitionsError::Corrupt {
                entry: name.to_string_lossy().into_owned(),
            })?;
        if excluded == Some(logical.as_str()) {
            continue;
        }
        let requested_entries =
            partitions
                .len()
                .checked_add(1)
                .ok_or(ListPartitionsError::EntriesExceeded {
                    limit: max_entries,
                    requested: usize::MAX,
                })?;
        if requested_entries > max_entries {
            return Err(ListPartitionsError::EntriesExceeded {
                limit: max_entries,
                requested: requested_entries,
            });
        }
        let requested_name_bytes = name_bytes.checked_add(logical.len()).ok_or(
            ListPartitionsError::NameBytesExceeded {
                limit: max_name_bytes,
                requested: usize::MAX,
            },
        )?;
        if requested_name_bytes > max_name_bytes {
            return Err(ListPartitionsError::NameBytesExceeded {
                limit: max_name_bytes,
                requested: requested_name_bytes,
            });
        }
        name_bytes = requested_name_bytes;
        partitions.push(logical);
    }
    refuse_orphan_remnants(remnants, &data_dirs)?;
    // Logical order, because a caller pages through this listing with a
    // LOGICAL cursor. Physical order does not agree with logical order: an
    // escape reorders a name against its unescaped neighbours.
    partitions.sort_unstable();
    // Two directories that decode to one logical name cannot both be
    // authoritative for it. The codec is injective, so this is unreachable
    // through it — which is exactly why it is reported rather than resolved.
    if let Some(duplicate) = partitions.windows(2).find(|pair| pair[0] == pair[1]) {
        // Both physical spellings, because an operator quarantines a
        // directory. The logical name they share names neither of them.
        let physical = partition_name::encode_any_namespace(&duplicate[0]).map_or_else(
            |_| duplicate[0].clone(),
            partition_name::EncodedPartitionName::into_string,
        );
        return Err(ListPartitionsError::Corrupt {
            entry: format!(
                "two directories decode to `{}`, one of them `{physical}_data`",
                duplicate[0]
            ),
        });
    }
    Ok(partitions)
}

/// Why a partition listing cannot be produced.
///
/// The listing fails whole rather than short. Every fleet-wide read pages
/// through it — the conversation listing, the retention sweep, the usage
/// rebuild, and the projector rebuild — and each folds over what it receives.
/// A listing that dropped an entry would let a projector report complete
/// coverage of a fleet it did not see, and it would leave retention unable to
/// act on durable data whose identity it cannot read.
#[derive(Debug, thiserror::Error)]
pub enum ListPartitionsError {
    /// Reading the storage directory failed.
    #[error("storage directory read failed: {0}")]
    Storage(std::io::Error),
    /// A directory has the shape of a partition and no readable identity.
    #[error("`{entry}` has the shape of a partition directory and no logical name")]
    Corrupt {
        /// The physical directory entry, for the operator who must quarantine
        /// it.
        entry: String,
    },
    /// The listing crossed its transient logical-name count ceiling.
    #[error("partition listing requested {requested} names, above the limit {limit}")]
    EntriesExceeded {
        /// The configured transient entry ceiling.
        limit: usize,
        /// The first entry count that crossed the ceiling.
        requested: usize,
    },
    /// The listing crossed its transient logical-name byte ceiling.
    #[error("partition listing requested {requested} name bytes, above the limit {limit}")]
    NameBytesExceeded {
        /// The configured transient byte ceiling.
        limit: usize,
        /// The first byte count that crossed the ceiling.
        requested: usize,
    },
}

/// Refuses a remnant that no data directory stands behind.
///
/// A remnant with no `_data` is a partition the listing cannot describe and
/// must not omit. Omitting it would report a fleet as complete while one
/// conversation's storage is half gone, and a caller computing over "every
/// partition" would be wrong with nothing saying so.
///
/// `data_dirs` holds every partition-shaped `_data` directory the scan walked
/// past, INCLUDING the ones it hides — a repair stage, an excluded
/// administrative partition. Each still owns its index siblings, so a set
/// built from the returned names alone would call them orphans.
///
/// # Errors
///
/// Returns [`ListPartitionsError::Corrupt`] naming the first orphan found.
fn refuse_orphan_remnants(
    remnants: Vec<String>,
    data_dirs: &std::collections::BTreeSet<String>,
) -> Result<(), ListPartitionsError> {
    for remnant in remnants {
        let Some(base) = remnant_base(&remnant) else {
            continue;
        };
        if data_dirs.contains(base)
            || base.starts_with(REPAIR_STAGE_PREFIX)
            || base.starts_with(REWRITE_STAGE_PREFIX)
            || base.starts_with(EXACT_REWRITE_STAGE_PREFIX)
        {
            continue;
        }
        if remnant.ends_with(CHECKPOINT_STORAGE_SUFFIX) {
            // A cleared checkpoint is what a completed destroy leaves. This
            // scan cannot read it without a runtime context, and it must not
            // fail a whole fleet listing for the ordinary case, so a
            // checkpoint-only remnant is left to the exact per-partition probe
            // that can read it.
            continue;
        }
        return Err(ListPartitionsError::Corrupt { entry: remnant });
    }
    Ok(())
}

/// The storage name of a partition-shaped remnant, if this entry is one.
///
/// A remnant is an index or checkpoint directory. Anything else a volume holds
/// is not this listing's business, which is the same rule the data-directory
/// scan above follows.
fn partition_shaped_remnant(name: &std::ffi::OsStr) -> Option<String> {
    let name = name.to_str()?;
    OFFSETS_SUFFIXES
        .iter()
        .chain(std::iter::once(&CHECKPOINT_STORAGE_SUFFIX))
        .any(|suffix| name.ends_with(suffix))
        .then(|| name.to_owned())
}

/// The partition storage key a remnant name belongs to.
fn remnant_base(remnant: &str) -> Option<&str> {
    OFFSETS_SUFFIXES
        .iter()
        .chain(std::iter::once(&CHECKPOINT_STORAGE_SUFFIX))
        .find_map(|suffix| remnant.strip_suffix(suffix))
}

/// Reads what durable storage survives for one exact key.
///
/// Bounded to that key: at most four `symlink_metadata` calls plus, only when a
/// checkpoint directory is actually there, one read of that checkpoint. It
/// never enumerates and never creates.
///
/// The order matters. Journal data present is the ordinary answer and is
/// decided first. With it gone, an index sibling or a checkpoint that still
/// counts events is a remnant of content that existed, so the partition is
/// damaged rather than absent. A completed destroy leaves the checkpoint
/// cleared to zero and removes everything else, which is what separates it
/// from a lost data directory.
///
/// # Errors
///
/// Returns [`ListPartitionsError::Storage`] for a read that fails for any
/// reason other than absence, and [`ListPartitionsError::Corrupt`] when a name
/// is taken by something that is not a directory.
async fn partition_presence_in<E>(
    context: &E,
    storage_dir: &std::path::Path,
    encoded: &str,
) -> Result<PartitionPresence, ListPartitionsError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    if partition_data_dir_exists(storage_dir, encoded)? {
        return Ok(PartitionPresence::Present);
    }
    // The journal data is gone. Anything else of this partition that survives
    // is a remnant of content, and content is what the data directory held.
    for suffix in OFFSETS_SUFFIXES {
        if directory_present(storage_dir, &format!("{encoded}{suffix}"))? {
            return Ok(PartitionPresence::Damaged {
                remnant: format!("{encoded}{suffix}"),
            });
        }
    }
    let checkpoint = format!("{encoded}{CHECKPOINT_STORAGE_SUFFIX}");
    if directory_present(storage_dir, &checkpoint)? {
        // Present is ordinary: a destroy clears this in place rather than
        // removing it. A count still standing is not — it says this partition
        // held that many events and its journal no longer does.
        //
        // The store is already on the volume, so opening it creates nothing.
        // A name with no checkpoint directory never reaches this line, which
        // is what keeps a typo from minting one.
        if recorded_event_count(context, encoded).await? > 0 {
            return Ok(PartitionPresence::Damaged {
                remnant: checkpoint,
            });
        }
    }
    Ok(PartitionPresence::Absent)
}

/// Whether one exact storage name is a present directory.
///
/// `symlink_metadata`, never `exists` or `is_dir`. Those collapse every
/// failure into `false`, which would report a partition absent because its
/// volume was unreadable. It also does not follow a link, so a link planted at
/// a partition's name is reported instead of silently answering for whatever
/// it points at.
///
/// A missing directory is the only `false`. A name taken by something that is
/// not a directory is a fault the caller is owed, because it named this one
/// partition — a listing that fails whole must not fall over for a stray file,
/// which is why discovery skips what this reports.
fn directory_present(
    storage_dir: &std::path::Path,
    name: &str,
) -> Result<bool, ListPartitionsError> {
    match std::fs::symlink_metadata(storage_dir.join(name)) {
        Ok(metadata) if metadata.is_dir() => Ok(true),
        Ok(_) => Err(ListPartitionsError::Corrupt {
            entry: name.to_owned(),
        }),
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(false),
        Err(e) => Err(ListPartitionsError::Storage(e)),
    }
}

/// The event count a surviving checkpoint still records.
///
/// Called only when the checkpoint directory is already on the volume, so
/// opening the store adds nothing to it. A caller that reached here for a name
/// with no checkpoint would mint one, which is why the directory test comes
/// first.
///
/// Only the question "does this still record content" decides damage, but the
/// exact count is what the store answers, so that is what travels.
async fn recorded_event_count<E>(context: &E, encoded: &str) -> Result<u64, ListPartitionsError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    polyc_eventlog::EventCountCheckpoint::open(context.child(presence_label(encoded)), encoded)
        .await
        .map(|checkpoint| checkpoint.expected_count())
        .map_err(|error| ListPartitionsError::Storage(std::io::Error::other(error.to_string())))
}

/// This probe's supervision-tree label for `encoded`, interned on first use.
///
/// The same bound [`PartitionWorkers::worker_label`] keeps, for the same
/// reason: a damaged partition is read repeatedly while an operator works on
/// it, so a label leaked per CALL would grow without bound. Interned, the leak
/// is bounded by the number of distinct partition names this process has
/// probed. The label is also `_presence`-suffixed rather than shared with the
/// worker's or the checkpoint cache's, so the two metric registrations under
/// one shard root never collide.
fn presence_label(encoded: &str) -> &'static str {
    static LABELS: std::sync::OnceLock<std::sync::Mutex<HashMap<String, &'static str>>> =
        std::sync::OnceLock::new();
    let mut labels = LABELS
        .get_or_init(|| std::sync::Mutex::new(HashMap::new()))
        .lock()
        .unwrap_or_else(std::sync::PoisonError::into_inner);
    if let Some(label) = labels.get(encoded) {
        return label;
    }
    let label: &'static str =
        Box::leak(format!("{}_presence", metric_label_body(encoded)).into_boxed_str());
    labels.insert(encoded.to_owned(), label);
    label
}

/// Reports whether `partition` holds journal data, without opening it.
///
/// One directory test, not a listing. A caller asking about one partition has
/// no business reading the identities of every other partition on the volume,
/// and a listing makes each such question cost the whole directory.
///
/// The answer is anchored on the `_data` directory, as discovery is. So this
/// alone cannot tell a partition that never existed from one whose data is
/// gone while a remnant of it survives — [`partition_presence_in`] is what
/// separates those two.
fn partition_data_dir_exists(
    storage_dir: &std::path::Path,
    encoded: &str,
) -> Result<bool, ListPartitionsError> {
    directory_present(storage_dir, &format!("{encoded}_data"))
}

/// The newest modification time, in milliseconds since the Unix epoch, among
/// the files of `partition`'s data directory under `storage_dir`.
///
/// The same `{name}_data` layout [`list_partitions_bounded_in`] recovers logical names
/// from, read for its times instead of its names — so a partition that is
/// listed is a partition this can answer for, and one that is not reports
/// [`None`].
///
/// [`None`] for a directory that is missing, that will not be read, or whose
/// files will not report a time. An absent answer rather than a very old one:
/// the caller deciding retention on it must not read a storage fault as an idle
/// partition.
fn last_modified_ms_in(storage_dir: &std::path::Path, partition: &PartitionRef) -> Option<u64> {
    let data_dir = storage_dir.join(format!("{}_data", partition.storage_key()));
    let mut newest: Option<std::time::SystemTime> = None;
    for entry in std::fs::read_dir(&data_dir).ok()?.flatten() {
        let Ok(modified) = entry.metadata().and_then(|m| m.modified()) else {
            continue;
        };
        newest = Some(match newest {
            Some(current) if current >= modified => current,
            _ => modified,
        });
    }
    let duration = newest?
        .duration_since(std::time::SystemTime::UNIX_EPOCH)
        .ok()?;
    u64::try_from(duration.as_millis()).ok()
}

/// Rewrite one partition, applying `decide` to each event to keep it, drop it,
/// or replace its payload. Fresh replay + rewrite + destroy + re-append + one
/// fresh signed root, all within this single handler (so no other command
/// interleaves). Returns the dropped count; a replaced event survives (with its
/// new payload) and is not counted as dropped.
///
/// # The rewritten partition is re-rooted, always
///
/// Every [`MMR_SIGNED_ROOT_KIND`](polyc_eventlog::MMR_SIGNED_ROOT_KIND) marker
/// the partition carried was signed over content this rewrite is changing, so
/// none of them describes what survives. They are dropped before `decide` ever
/// sees them — a predicate written for content kinds would otherwise `Keep`
/// them — and one root signed over the survivors replaces the lot. Two
/// properties rest on that:
///
/// - the rewritten partition still verifies
///   ([`polyc_eventlog::verify_replay_with_trust`]). Re-appending a stale root
///   beside content it does not cover is a self-inflicted integrity violation.
/// - a reader pinned to the partition's head sees the rewrite. A persona-memory
///   snapshot is pinned to a journal head — position plus the root committed at
///   it — and `polyc_state::persona_memory::MemorySnapshot::standing` compares
///   the two. A rewrite that only REPLACED payloads used to keep the length,
///   every marker position, and every old root, so the pin could not see it.
///
/// The fresh root is built and signed BEFORE anything is destroyed, so a
/// partition this cannot re-root is left exactly as it was rather than
/// half-rebuilt.
///
/// # A rewrite never launders provenance
///
/// A [`RewriteDecision::Replace`] carries a payload and only a payload: the
/// survivor is rebuilt with the original event's
/// [`TrustTag`](polyc_eventlog::TrustTag), never a default one. The scrub
/// that narrows quarantined tool output is still quarantined output afterwards,
/// so a data-flow policy reading the durable record cannot be handed untainted
/// where quarantined was stored. The re-root above also depends on it: MMR
/// leaves are `(kind, payload)`, so a survivor sequence differing from the
/// original only in its tags would re-sign a byte-identical root at an
/// identical leaf count, leaving a pinned reader unable to see the rewrite —
/// the very failure the re-root closes. Preserving the tag keeps such a rewrite
/// out of the destructive path entirely: it settles as the no-op it is.
/// Finishes a rewrite a previous attempt staged, if one is waiting.
///
/// Returns the number of records that rewrite dropped, or `None` when no
/// complete stage exists and the caller must decide the rewrite itself.
///
/// The stage is authoritative here. The live partition may already be
/// destroyed, so re-running the caller's predicate against it would decide
/// against content that is no longer there (`#2323`).
///
/// # Errors
///
/// Returns [`EventLogError`] if the stage cannot be read, or if the restore
/// fails. The stage survives a failure, so a later attempt can try again.
#[allow(clippy::too_many_arguments)]
async fn resume_rewrite<E>(
    context: &E,
    storage_dir: &std::path::Path,
    logs: &mut OpenLogs<E>,
    checkpoints: &mut HashMap<String, CheckpointFrame>,
    count_checkpoints: &mut CountCheckpoints<E>,
    mmr_logs: &mut HashMap<String, polyc_mmr::VerifiableLog>,
    partition: &str,
    stage: &str,
) -> Result<Option<usize>, EventLogError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    // Directory test first: opening the stage is what would create it, and a
    // read that recovers a staged rewrite (`#2567`) reaches this for every
    // intent it finds, including ones a prior process already retired.
    // `unwrap_or(true)` — a volume this cannot read falls through to the open
    // below, which reports the real failure. The test exists to keep an
    // ordinary read from CREATING the stage in the common case where there is
    // none, not to become a second place a storage failure is decided.
    if !logs.contains(stage) && !partition_data_dir_exists(storage_dir, stage).unwrap_or(true) {
        return Ok(None);
    }
    let staged = {
        let log = logs.get_or_open(context, stage).await?;
        let held = log.replay().await?;
        staged_rewrite(&held)
    };
    let Some((restored, dropped)) = staged else {
        return Ok(None);
    };
    restore_rewrite(
        context,
        logs,
        checkpoints,
        count_checkpoints,
        mmr_logs,
        partition,
        &restored,
    )
    .await?;
    destroy_one(
        context,
        logs,
        checkpoints,
        count_checkpoints,
        mmr_logs,
        stage,
        DestroyCheckpoint::Clear,
    )
    .await?;
    tracing::info!(
        partition = %partition,
        dropped,
        "partition rewrite resumed from its durable stage (#2323)"
    );
    Ok(Some(usize::try_from(dropped).unwrap_or(usize::MAX)))
}

/// Destroys `partition` and writes `restored` in its place, then lowers the
/// durable count to what really landed.
///
/// Shared by a first rewrite attempt and by one resuming from a stage, so both
/// leave the identical end state. The destroy retains the pre-rewrite count, so
/// the whole window between it and the record below measures against the older,
/// higher floor — a crash inside reports a truncated replay instead of a
/// healthy empty partition (`#2323`).
///
/// # Errors
///
/// Returns [`EventLogError`] if the destroy, the restore, or the count record
/// fails. The stage outlives all three, so a later attempt can try again.
#[allow(clippy::too_many_arguments)]
async fn restore_rewrite<E>(
    context: &E,
    logs: &mut OpenLogs<E>,
    checkpoints: &mut HashMap<String, CheckpointFrame>,
    count_checkpoints: &mut CountCheckpoints<E>,
    mmr_logs: &mut HashMap<String, polyc_mmr::VerifiableLog>,
    partition: &str,
    restored: &[Event],
) -> Result<u64, EventLogError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    destroy_one(
        context,
        logs,
        checkpoints,
        count_checkpoints,
        mmr_logs,
        partition,
        DestroyCheckpoint::Retain,
    )
    .await?;
    let new_len = if restored.is_empty() {
        0
    } else {
        append_repair_copy(context, logs, partition, restored).await?;
        let log = logs.get_or_open(context, partition).await?;
        log.len().await
    };
    // Durable event-count checkpoint (`#799` hardening): a deliberate
    // narrowing (erasure/retention) is a legitimate mutation, so record the
    // new, SMALLER count as the expected minimum — otherwise the next verify
    // would misread this intentional shrink as corruption.
    //
    // This is the TERMINAL durable step. Every earlier moment still measures
    // against the pre-rewrite floor, so a crash before here reports a truncated
    // replay rather than a healthy empty partition. A resumed rewrite reaches
    // this same step, which is what closes that window rather than leaving it
    // reporting a partition that is now correct as damaged.
    //
    // A failure here PROPAGATES (`#2567`). It used to be logged and swallowed,
    // on the reasoning that recording never blocks a mutation. That reasoning
    // does not hold for the terminal step: the caller reads a success and tears
    // the stage down, which destroys the only thing that could ever lower the
    // floor. The partition then reports a truncated replay forever, with no
    // remedy left on any path. Failing instead keeps the stage, so the next
    // attempt finishes what this one could not.
    match maybe_inject_count_record_failure(partition) {
        Some(error) => return Err(error),
        None => {
            count_checkpoints
                .record(context, partition, new_len)
                .await?;
        }
    }
    Ok(new_len)
}

#[allow(clippy::too_many_arguments)]
async fn rewrite_one<E>(
    context: &E,
    storage_dir: &std::path::Path,
    logs: &mut OpenLogs<E>,
    checkpoints: &mut HashMap<String, CheckpointFrame>,
    count_checkpoints: &mut CountCheckpoints<E>,
    mmr_logs: &mut HashMap<String, polyc_mmr::VerifiableLog>,
    signer: &JournalAttestationSigner,
    command_id: &str,
    partition: &str,
    decide: &(dyn Fn(&Event) -> RewriteDecision + Send + Sync),
) -> Result<usize, EventLogError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    let stage = rewrite_stage_partition(partition, command_id);

    // A complete stage means a previous attempt at THIS command already decided
    // and may already have destroyed the target. Finish from the stage rather
    // than deciding again: the live partition may now be empty, so re-running
    // the predicate against it would produce a different, wrong answer
    // (`#2323`).
    if let Some(dropped) = resume_rewrite(
        context,
        storage_dir,
        logs,
        checkpoints,
        count_checkpoints,
        mmr_logs,
        partition,
        &stage,
    )
    .await?
    {
        return Ok(dropped);
    }

    let all = {
        let log = logs.get_or_open(context, partition).await?;
        log.replay().await?
    };
    let mut survivors: Vec<Event> = Vec::with_capacity(all.len());
    let mut dropped = 0usize;
    for event in &all {
        if event.kind == polyc_eventlog::MMR_SIGNED_ROOT_KIND {
            continue;
        }
        match decide(event) {
            RewriteDecision::Keep => survivors.push(event.clone()),
            RewriteDecision::Drop => dropped += 1,
            // A `Replace` rewrites the payload and NOTHING else. The trust tag
            // is the event's provenance capability, not part of the content
            // being rewritten: a corroborator scrub that narrows quarantined
            // tool output leaves it quarantined. `Event::new` would hardcode
            // `TrustTag::Unspecified` and launder every tagged event the
            // predicate touches.
            RewriteDecision::Replace(payload) => {
                survivors.push(Event::with_trust(event.kind.clone(), payload, event.trust));
            }
        }
    }
    // A rewrite that changes no content is a no-op — skip the destroy +
    // re-append (and the checkpoint churn) entirely, exactly as the keep-only
    // path did when nothing was dropped. Compared against the content rather
    // than counted from the decisions, so a `Replace` that hands back the bytes
    // it was given settles here too: past this point the survivors really are a
    // different sequence, so the fresh root below really is a different root.
    // The comparison is full [`Event`] equality, trust tag included, which only
    // says what it means because the `Replace` arm above carries the tag
    // forward — rebuilding survivors with a default tag would make every tagged
    // event compare unequal to itself and defeat the guard.
    if dropped == 0
        && survivors
            .iter()
            .zip(
                all.iter()
                    .filter(|e| e.kind != polyc_eventlog::MMR_SIGNED_ROOT_KIND),
            )
            .all(|(after, before)| after == before)
    {
        return Ok(0);
    }
    // Sign first, destroy second: an integrity failure here leaves the
    // partition untouched instead of stripped of its roots.
    let restored = if survivors.is_empty() {
        Vec::new()
    } else {
        let tree = polyc_eventlog::rebuild_from_events(&survivors)?;
        let marker = polyc_eventlog::extend_and_sign(&tree, &[], signer)?;
        let mut sequence = survivors;
        sequence.push(marker);
        sequence
    };

    // Stage the final content durably before the destructive half begins
    // (`#2323`). The survivors otherwise live only in this call's memory, so a
    // crash after the destroy loses them for good. The sentinel separates a
    // stage a crash left half-written from one that can authorize a restore.
    destroy_one(
        context,
        logs,
        checkpoints,
        count_checkpoints,
        mmr_logs,
        &stage,
        DestroyCheckpoint::Clear,
    )
    .await?;
    let mut staged = restored.clone();
    staged.push(rewrite_stage_complete(
        restored.len() as u64,
        dropped as u64,
    ));
    append_repair_copy(context, logs, &stage, &staged).await?;

    restore_rewrite(
        context,
        logs,
        checkpoints,
        count_checkpoints,
        mmr_logs,
        partition,
        &restored,
    )
    .await?;
    // The target is durable and the count is lowered, so the stage has nothing
    // left to protect.
    destroy_one(
        context,
        logs,
        checkpoints,
        count_checkpoints,
        mmr_logs,
        &stage,
        DestroyCheckpoint::Clear,
    )
    .await?;
    tracing::info!(partition = %partition, dropped, "partition rewritten (erasure)");
    Ok(dropped)
}

fn exact_rewrite_content(
    all: &[Event],
    signer: &JournalAttestationSigner,
    decide: &(dyn Fn(&Event) -> RewriteDecision + Send + Sync),
) -> Result<(Vec<Event>, usize), EventLogError> {
    let mut survivors = Vec::with_capacity(all.len());
    let mut dropped = 0_usize;
    for event in all {
        if event.kind == polyc_eventlog::MMR_SIGNED_ROOT_KIND {
            continue;
        }
        match decide(event) {
            RewriteDecision::Keep => survivors.push(event.clone()),
            RewriteDecision::Drop => dropped = dropped.saturating_add(1),
            RewriteDecision::Replace(payload) => {
                survivors.push(Event::with_trust(event.kind.clone(), payload, event.trust));
            }
        }
    }
    if survivors.is_empty() {
        return Ok((Vec::new(), dropped));
    }
    let tree = polyc_eventlog::rebuild_from_events(&survivors)?;
    let root = polyc_eventlog::extend_and_sign(&tree, &[], signer)?;
    survivors.push(root);
    Ok((survivors, dropped))
}

fn inspect_exact_rewrite(
    partition: &str,
    command_id: &str,
    all: &[Event],
    signer: &JournalAttestationSigner,
    decide: &(dyn Fn(&Event) -> RewriteDecision + Send + Sync),
) -> Result<(RewritePlan, Vec<Event>, usize), EventLogError> {
    let before = physical_fingerprint(all);
    let (restored, dropped) = exact_rewrite_content(all, signer, decide)?;
    let after = physical_fingerprint(&restored);
    let stage_binding = exact_rewrite_binding(partition, command_id, &before, &after);
    Ok((
        RewritePlan {
            before,
            after,
            stage_binding,
        },
        restored,
        dropped,
    ))
}

#[allow(clippy::too_many_arguments)]
async fn apply_exact_rewrite<E>(
    context: &E,
    logs: &mut OpenLogs<E>,
    checkpoints: &mut HashMap<String, CheckpointFrame>,
    count_checkpoints: &mut CountCheckpoints<E>,
    mmr_logs: &mut HashMap<String, polyc_mmr::VerifiableLog>,
    signer: &JournalAttestationSigner,
    partition: &str,
    command_id: &str,
    expected: RewritePlan,
    decide: &(dyn Fn(&Event) -> RewriteDecision + Send + Sync),
) -> Result<RewriteApplication, EventLogError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    let RewritePlan {
        before,
        after,
        stage_binding,
    } = expected;
    if exact_rewrite_binding(partition, command_id, &before, &after) != stage_binding {
        return Ok(RewriteApplication::Changed);
    }
    let stage = exact_rewrite_stage_partition(partition, &stage_binding);
    let current = {
        let log = logs.get_or_open(context, partition).await?;
        log.replay().await?
    };
    let current_fingerprint = physical_fingerprint(&current);
    if current_fingerprint == after {
        destroy_one(
            context,
            logs,
            checkpoints,
            count_checkpoints,
            mmr_logs,
            &stage,
            DestroyCheckpoint::Clear,
        )
        .await?;
        return Ok(RewriteApplication::AlreadyApplied);
    }

    let (restored, dropped) = if current_fingerprint == before {
        let (observed, restored, dropped) =
            inspect_exact_rewrite(partition, command_id, &current, signer, decide)?;
        if observed
            != (RewritePlan {
                before,
                after,
                stage_binding,
            })
        {
            return Ok(RewriteApplication::Changed);
        }
        destroy_one(
            context,
            logs,
            checkpoints,
            count_checkpoints,
            mmr_logs,
            &stage,
            DestroyCheckpoint::Clear,
        )
        .await?;
        let mut staged = restored.clone();
        staged.push(exact_rewrite_stage_complete(
            before,
            after,
            stage_binding,
            restored.len() as u64,
            dropped as u64,
        ));
        append_repair_copy(context, logs, &stage, &staged).await?;
        (restored, dropped)
    } else {
        let held = {
            let log = logs.get_or_open(context, &stage).await?;
            log.replay().await?
        };
        let Some((restored, dropped)) =
            exact_staged_rewrite(&held, &before, &after, &stage_binding)
        else {
            return Ok(RewriteApplication::Changed);
        };
        (restored, usize::try_from(dropped).unwrap_or(usize::MAX))
    };

    restore_rewrite(
        context,
        logs,
        checkpoints,
        count_checkpoints,
        mmr_logs,
        partition,
        &restored,
    )
    .await?;
    destroy_one(
        context,
        logs,
        checkpoints,
        count_checkpoints,
        mmr_logs,
        &stage,
        DestroyCheckpoint::Clear,
    )
    .await?;
    Ok(RewriteApplication::Applied { dropped })
}

/// Empties one partition and removes its storage. The function opens a cold
/// handle. It pulls that handle into the cache. It removes the handle. Nothing
/// can resurrect it. It then resets the journal to empty and reclaims the
/// emptied storage. After that succeeds, it forgets the checkpoint frame and
/// cached running MMR (`#799`). The tree no longer matches anything after the
/// partition is gone. The function also clears the durable event-count
/// checkpoint (`#799` hardening). Otherwise, a future partition with the same
/// name would inherit an excessive stale count. Verification would fail.
///
/// [`DestroyCheckpoint`] selects that behaviour, because a rewrite's internal
/// destruction needs the opposite.
///
/// The two-step reset-then-reclaim is what makes an interrupted destruction
/// safe rather than ambiguous; the body says why at the call.
///
/// The fallible destruction runs before the caches clear (`#1742`). Clearing
/// them first could leave the on-disk blobs in place. The destruction would
/// then look complete in this process's memory. `rewrite_one` and `repair_one`
/// inherit this ordering through their calls to `destroy_one`.
/// What a destroy leaves in the partition's durable event-count checkpoint.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum DestroyCheckpoint {
    /// Clear it. The partition really will hold nothing, so zero is a count
    /// already durably observed.
    Clear,
    /// Leave the pre-destroy count in place.
    ///
    /// A rewrite destroys its target and then restores the survivors. Clearing
    /// here would drop the expected count to zero for that whole window. The
    /// truncation guard compares `actual < expected`. An interrupted rewrite
    /// would then leave an empty partition that verifies as healthy (`#2323`).
    /// Retaining the old, higher count makes that window report a truncated replay
    /// instead. The rewrite lowers it to the true count as its terminal durable
    /// step.
    Retain,
}

#[allow(clippy::too_many_arguments)]
async fn destroy_one<E>(
    context: &E,
    logs: &mut OpenLogs<E>,
    checkpoints: &mut HashMap<String, CheckpointFrame>,
    count_checkpoints: &mut CountCheckpoints<E>,
    mmr_logs: &mut HashMap<String, polyc_mmr::VerifiableLog>,
    partition: &str,
    checkpoint: DestroyCheckpoint,
) -> Result<(), EventLogError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    // BEFORE the destroy, not after it, and the order is the whole point.
    //
    // A zeroed floor is what tells a later reader that this partition's
    // content was deliberately removed rather than lost. Clearing it after the
    // destroy makes that signal unreliable exactly when it matters: a destroy
    // that faults part-way leaves a fragment beside a floor that still
    // describes the whole partition, and nothing on disk says which of the two
    // happened. `repair_settled_one` reads this to tell a repair still inside
    // its destructive window from a partition that has since moved on, and
    // that question has no honest answer from content alone (`#2568`).
    //
    // Clearing early is safe on its own terms. A floor of zero asserts no
    // minimum, so it can never turn a healthy partition into a reported
    // truncation — the failure it risks is permissive, and the destroy that
    // follows is retried.
    if checkpoint == DestroyCheckpoint::Clear {
        // Propagated, not logged, and this changed with the ordering above.
        // While the floor was cleared AFTER the destroy it was bookkeeping,
        // and a failure to update bookkeeping should not fail an erasure. Now
        // it is the record that the content is deliberately gone, and
        // `repair_settled_one` reads it. Swallow the failure and the destroy
        // proceeds anyway: the partition is emptied while its floor still
        // describes the old content, and the next read serves it as a healthy
        // empty conversation over destroyed events — the `#2568` misreport
        // this branch exists to prevent.
        //
        // Failing here leaves the partition intact and the destroy retryable,
        // which is the safe direction.
        count_checkpoints.clear(context, partition).await?;
    }
    logs.get_or_open(context, partition).await?;
    let label = logs.log_label(partition);
    let log = logs.take(partition).expect("just opened via get_or_open");
    // `#1742` fault-injection hook — see `maybe_inject_destroy_failure`'s
    // doc. Always `None` outside test builds.
    if let Some(err) = maybe_inject_destroy_failure(partition) {
        return Err(err);
    }
    {
        // Reset first, reclaim second, and the split is the whole correction.
        //
        // Commonware's own contract calls its `destroy` final teardown that
        // "is not crash-safe", and says reopening interrupted storage "may
        // observe partially removed state" — a partition holding some of its
        // blobs and not others, which reads as a short history rather than as
        // damage. This code used to reach for exactly that primitive and then
        // reopen the same logical partition, which is what `#2568` describes.
        //
        // `reset` is Commonware's recoverable replacement: it stages the
        // offsets reset intent durably BEFORE clearing data, so an interrupted
        // reset is finished by the next open rather than left half-applied.
        // `reclaim` then removes storage that is by then provably empty — it
        // refuses outright if it is not — so the removal that is still not
        // crash-safe can no longer leave a partial HISTORY behind. The worst
        // it leaves is a content-free remnant, which the presence classifier
        // already reports as damage and which a retry of this same command
        // converges to absence.
        //
        // A failed reset or reclaim returns with the handle already taken out
        // of `logs` and dropped, which is what Commonware's rule for a failed
        // mutable operation requires.
        let emptied = Box::pin(log.reset(context.child(label))).await?;
        Box::pin(emptied.reclaim()).await?;
    }
    checkpoints.remove(partition);
    mmr_logs.remove(partition);
    count_checkpoints.forget(partition);
    tracing::info!(partition = %partition, "partition erased (reset, then reclaimed)");
    Ok(())
}

/// `#1712` test seam: substitutes a test-armed [`EventLogError`] for the
/// outcome of one specific event's append within [`append_batch_one`]'s
/// per-event loop, so a test can force that failure without a genuinely
/// reproducible commonware-storage-level fault on an already-open handle
/// (see `tests::arm_append_failure`'s doc for why). Always `None` in a release
/// build: the seam compiles only under `cfg(test)` or the non-default
/// `test-util` feature, and neither is reachable from a production dependency
/// edge.
#[cfg(test)]
fn maybe_inject_append_failure(partition: &str, event_index: usize) -> Option<EventLogError> {
    tests::take_armed_append_failure(partition, event_index)
        .or_else(|| take_armed_append_failure_at(partition, event_index))
}

/// Downstream-armable twin, present whenever `test-util` is on without this
/// crate's own test build.
#[cfg(all(not(test), feature = "test-util"))]
fn maybe_inject_append_failure(partition: &str, event_index: usize) -> Option<EventLogError> {
    take_armed_append_failure_at(partition, event_index)
}

/// Production twin of the seam-bearing [`maybe_inject_append_failure`] above:
/// always `None`, so `append_batch_one`'s real append always runs.
#[cfg(not(any(test, feature = "test-util")))]
const fn maybe_inject_append_failure(
    _partition: &str,
    _event_index: usize,
) -> Option<EventLogError> {
    None
}

/// `#1712` test seam, sibling of [`maybe_inject_append_failure`] for
/// [`append_batch_one`]'s FINAL commit instead of a per-event append. Always
/// `None` outside test builds.
#[cfg(test)]
fn maybe_inject_commit_failure(partition: &str) -> Option<EventLogError> {
    tests::take_armed_commit_failure(partition)
}

/// The per-event append seam, armed by partition and 0-based index within one
/// batch.
///
/// Module scope and gated the same way as the root seam below, because a
/// downstream crate must be able to arm it. A `cfg(test)` hook would compile
/// away in every build but this crate's own, so a State-level test could arm it
/// and silently observe the real append succeeding.
#[cfg(any(test, feature = "test-util"))]
static ARMED_APPEND_FAILURES_AT: std::sync::OnceLock<
    std::sync::Mutex<std::collections::HashMap<String, usize>>,
> = std::sync::OnceLock::new();

/// Arms `partition`'s next batch so the event at `event_index` fails as if the
/// journal append itself had.
///
/// Gated on the feature alone, not on `test`. This crate's own tests arm
/// through `tests::arm_append_failure`; this one exists for the downstream
/// `test_util` re-export, so under a plain `cargo test` nothing would call it.
#[cfg(feature = "test-util")]
fn arm_append_failure_at(partition: &str, event_index: usize) {
    ARMED_APPEND_FAILURES_AT
        .get_or_init(|| std::sync::Mutex::new(std::collections::HashMap::new()))
        .lock()
        .expect("lock poisoned")
        .insert(partition.to_owned(), event_index);
}

/// Disarms and returns the synthetic error when `event_index` is the armed one.
#[cfg(any(test, feature = "test-util"))]
fn take_armed_append_failure_at(partition: &str, event_index: usize) -> Option<EventLogError> {
    let lock = ARMED_APPEND_FAILURES_AT.get()?;
    let matched = {
        let mut armed = lock.lock().expect("lock poisoned");
        if armed.get(partition) == Some(&event_index) {
            armed.remove(partition);
            true
        } else {
            false
        }
    };
    matched.then(|| {
        EventLogError::Journal(commonware_storage::journal::Error::Corruption(
            "injected test failure (#1712 fault-injection seam)".to_owned(),
        ))
    })
}

#[cfg(any(test, feature = "test-util"))]
static ARMED_ROOT_APPEND_FAILURES: std::sync::OnceLock<
    std::sync::Mutex<std::collections::HashMap<String, usize>>,
> = std::sync::OnceLock::new();

#[cfg(any(test, feature = "test-util"))]
fn arm_root_append_failure(partition: &str) {
    ARMED_ROOT_APPEND_FAILURES
        .get_or_init(|| std::sync::Mutex::new(std::collections::HashMap::new()))
        .lock()
        .expect("lock poisoned")
        .entry(partition.to_owned())
        .and_modify(|count| *count = count.saturating_add(1))
        .or_insert(1);
}

#[cfg(any(test, feature = "test-util"))]
fn take_armed_root_append_failure(partition: &str) -> Option<EventLogError> {
    let lock = ARMED_ROOT_APPEND_FAILURES.get()?;
    let matched = {
        let mut armed = lock.lock().expect("lock poisoned");
        match armed.get_mut(partition) {
            Some(count) if *count > 1 => {
                *count -= 1;
                true
            }
            Some(_) => {
                armed.remove(partition);
                true
            }
            None => false,
        }
    };
    matched.then(|| {
        EventLogError::Journal(commonware_storage::journal::Error::Corruption(
            "injected root-append failure".to_owned(),
        ))
    })
}

#[cfg(any(test, feature = "test-util"))]
fn maybe_inject_root_append_failure(partition: &str) -> Option<EventLogError> {
    take_armed_root_append_failure(partition)
}

#[cfg(test)]
fn maybe_inject_mmr_preparation_failure(partition: &str) -> Option<EventLogError> {
    tests::take_armed_mmr_preparation_failure(partition)
}

#[cfg(not(any(test, feature = "test-util")))]
const fn maybe_inject_root_append_failure(_partition: &str) -> Option<EventLogError> {
    None
}

#[cfg(not(test))]
const fn maybe_inject_mmr_preparation_failure(_partition: &str) -> Option<EventLogError> {
    None
}

/// Non-test twin of the `#[cfg(test)]` [`maybe_inject_commit_failure`] above:
/// always `None`, so `append_batch_one`'s real commit always runs.
#[cfg(not(test))]
const fn maybe_inject_commit_failure(_partition: &str) -> Option<EventLogError> {
    None
}

/// `#2567` test seam, sibling of [`maybe_inject_append_failure`] for
/// [`restore_rewrite`]'s TERMINAL event-count record. That record is the step
/// whose failure used to be swallowed, so a test needs to fail exactly it to
/// prove the stage now survives. Always `None` outside test builds.
#[cfg(test)]
fn maybe_inject_count_record_failure(partition: &str) -> Option<EventLogError> {
    tests::take_armed_count_record_failure(partition)
}

/// Non-test twin of the `#[cfg(test)]` [`maybe_inject_count_record_failure`]
/// above: always `None`, so `restore_rewrite`'s real record always runs.
#[cfg(not(test))]
const fn maybe_inject_count_record_failure(_partition: &str) -> Option<EventLogError> {
    None
}

/// `#1742` test seam, sibling of [`maybe_inject_append_failure`] for
/// [`destroy_one`]'s reset-then-reclaim. Always `None` outside test builds —
/// both halves consume the handle, so there is no portable way to make a
/// genuinely real commonware-storage reset or removal fail on demand; this
/// substitutes a real [`EventLogError`] for their outcome instead. It fires
/// before the reset, so it models the whole destruction failing, which is the
/// state `#1742` is about.
#[cfg(test)]
fn maybe_inject_destroy_failure(partition: &str) -> Option<EventLogError> {
    tests::take_armed_destroy_failure(partition)
}

/// Non-test twin of the `#[cfg(test)]` [`maybe_inject_destroy_failure`]
/// above: always `None`, so [`destroy_one`]'s real `destroy()` always runs.
#[cfg(not(test))]
const fn maybe_inject_destroy_failure(_partition: &str) -> Option<EventLogError> {
    None
}

/// Append `events` in order to `partition`'s log; commit once at the end. If
/// any append fails, stops the batch (subsequent events — including any
/// caller-supplied commit marker — are NOT appended), best-effort commits the
/// partial writes (so the journal advances and the next batch isn't
/// destabilized), and returns the error. Combined with the caller convention
/// of "marker last", this gives the marker-based atomic-batch property:
/// `turn_complete` is present iff the whole turn made it through.
///
/// `#1712`: commonware-storage documents storage errors from mutable journal
/// operations as "fatal for the current handle" — its in-memory state may no
/// longer agree with what's on disk. So on EITHER failure path here (a
/// per-event append error, or the final `commit()` below failing) this also
/// evicts `partition`'s cached [`EventLog`] handle from `logs` before
/// returning the error, forcing the next command that touches this partition
/// to reopen (and replay) it fresh rather than keep reusing a handle
/// Commonware itself no longer vouches for. The per-event append error path
/// leaves `checkpoints`/`count_checkpoints` alone — independent in-memory
/// bookkeeping that failing operation never touched, since the checkpoint
/// recording below only runs once the append loop has already succeeded.
/// `mmr_logs` is different: root preparation has already extended the cached
/// tree with the whole proposed batch before the first append. A per-event
/// failure may durably land only a prefix, while a final-commit failure may
/// land all or none. The prepared cache cannot match either outcome reliably.
/// Both paths evict it. The next successful append rebuilds from retained storage.
/// Broader hazards found in the same area (`migrate_append_into` having no
/// commit-on-error at all, and early cache clearing) were out of scope for
/// `#1712`. They have since been fixed (`#1741`, `#1742`).
///
/// Before the first physical append of a non-empty batch, this function rebuilds
/// the running MMR where necessary. It extends the MMR with the proposed events.
/// It signs the resulting root. A replay, rebuild, or signing failure is definite:
/// no event from this batch has reached storage. The events and prepared root
/// marker are then appended together. They are committed together. A marker append or commit
/// failure is ambiguous. The content may already be durable. The function evicts
/// both cached handles. Exact attestation recovery must settle the outcome before
/// State exposes the commit.
///
/// On a fully committed batch, refreshes the per-partition checkpoint cache when
/// the batch lands a [`BASE_COMPACTION_CHECKPOINT`] event. The next bounded
/// replay can then seek to its tail without a cold scan.
///
/// Also records the new journal length in the durable event-count checkpoint
/// (`#799` hardening — see `polyc_eventlog::checkpoint`) once the commit has
/// actually landed, so a later `ReplayVerified`/`RepairPartition` can tell a
/// self-healed truncation of already-committed data apart from an ordinary
/// crash. This checkpoint write is best-effort: unlike mandatory MMR
/// preparation and root publication, its failure does not make signed commit
/// evidence incomplete. Recording never blocks or fails the append; it only
/// strengthens future truncation detection.
#[allow(clippy::too_many_arguments)]
async fn append_batch_one<E>(
    context: &E,
    logs: &mut OpenLogs<E>,
    checkpoints: &mut HashMap<String, CheckpointFrame>,
    count_checkpoints: &mut CountCheckpoints<E>,
    mmr_logs: &mut HashMap<String, polyc_mmr::VerifiableLog>,
    signer: &JournalAttestationSigner,
    partition: &str,
    events: &[Event],
) -> Result<Vec<u64>, AppendError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    let log = logs
        .get_or_open(context, partition)
        .await
        .map_err(AppendError::Log)?;
    let prepared_root = if events.is_empty() {
        None
    } else {
        match prepare_signed_root(log, mmr_logs, signer, partition, events).await {
            Ok(marker) => Some(marker),
            Err(error) => {
                // Definite, and before any append: nothing of this batch is
                // durable, so the counter names the stage that failed and the
                // caller sees a plain log error rather than an ambiguity.
                metrics::record_attestation(error.outcome());
                logs.take(partition);
                mmr_logs.remove(partition);
                return Err(AppendError::Log(error.into_eventlog_error()));
            }
        }
    };

    let mut positions = Vec::with_capacity(events.len());
    for (idx, event) in events.iter().enumerate() {
        // `#1712` fault-injection hook — see `maybe_inject_append_failure`'s
        // doc. Always `None` outside test builds.
        let append_result = match maybe_inject_append_failure(partition, idx) {
            Some(err) => Err(err),
            None => log.append(event).await,
        };
        match append_result {
            Ok(pos) => positions.push(pos),
            Err(err) => {
                // Best-effort: commit what we've written so the journal stays
                // healthy for the next batch.
                //
                // The missing root marker leaves this prefix UNATTESTED. It
                // does not hide it: a raw replay returns an unattested prefix,
                // and only the State fold withholds pending records from
                // logical publication. So this is not an atomicity boundary,
                // and nothing here may report the batch as provably absent.
                match log.commit().await {
                    // Only when something actually landed. A failure on the
                    // FIRST event appends nothing, and the commit of nothing
                    // still succeeds — counting that would report unattested
                    // content that does not exist.
                    Ok(()) if !positions.is_empty() => {
                        metrics::record_attestation(
                            metrics::AttestationOutcome::UnattestedPartialBatch,
                        );
                    }
                    Ok(()) => {}
                    Err(commit_err) => {
                        tracing::warn!(error = %commit_err, "commit of partial batch failed");
                    }
                }
                // `#1712`: this handle is now "fatal" per Commonware's own
                // contract — evict it so the next command touching
                // `partition` reopens (and replays) fresh instead of reusing
                // possibly-inconsistent in-memory state.
                logs.take(partition);
                // Root preparation already extended the cached tree with the
                // whole proposed batch. The best-effort commit may land only
                // the prefix before this failure, so the prepared tree cannot
                // remain beside the partial durable journal.
                mmr_logs.remove(partition);
                // UNKNOWN. Nothing reached here can prove the batch left no
                // recoverable bytes: the errored append carries no rollback
                // guarantee, and the best-effort commit above may have made an
                // earlier prefix durable and readable. A definite class would
                // tell the caller its command did not take effect and that
                // retrying changes nothing, which would strand an unattested
                // prefix that a raw replay still returns.
                return Err(AppendError::AppendOutcomeUnknown(err));
            }
        }
    }
    // Held, not recorded yet (`#1386` risk 9). The marker append runs BEFORE
    // this batch's commit, so counting here would report a batch that never
    // landed, and would count twice on a caller's retry of the same logical
    // commit. Both bias the failure ratio downward.
    let attestation = prepared_root
        .is_some()
        .then_some(metrics::AttestationOutcome::Signed);
    if let Some(marker) = prepared_root
        && let Err(error) = append_prepared_root(log, partition, &marker).await
    {
        logs.take(partition);
        mmr_logs.remove(partition);
        return Err(AppendError::AttestationOutcomeUnknown(error));
    }
    // Same fault-injection hook as the per-event loop above, but for the
    // FINAL commit — the issue's other named error path. Always `None`
    // outside test builds.
    let commit_result = match maybe_inject_commit_failure(partition) {
        Some(err) => Err(err),
        None => log.commit().await,
    };
    if let Err(err) = commit_result {
        // `#1712`: same reasoning as the per-event append error above — a
        // failed commit is just as "fatal for the current handle".
        logs.take(partition);
        // Root preparation ran before the first append and mutated the cached
        // tree. This failed commit does not reveal which appended events and
        // root marker became durable, so the prepared tree cannot be reused.
        mmr_logs.remove(partition);
        return Err(AppendError::AttestationOutcomeUnknown(err));
    }
    // The batch is durable now, so its attestation outcome is a fact about
    // something that exists.
    if let Some(outcome) = attestation {
        metrics::record_attestation(outcome);
    }
    if !events.is_empty() {
        record_event_count_floor(context, count_checkpoints, partition, log.len().await).await;
    }
    // Cache the latest checkpoint landed in this batch (last one wins), keyed to
    // the tail right after it (its position + 1).
    if let Some((pos, event)) = events
        .iter()
        .zip(&positions)
        .rev()
        .find(|(event, _)| parse_kind(&event.kind).0 == BASE_COMPACTION_CHECKPOINT)
        .map(|(event, pos)| (*pos, event))
    {
        checkpoints.insert(
            partition.to_owned(),
            CheckpointFrame {
                tail_offset: pos + 1,
                payload: event.payload.clone(),
            },
        );
    }
    Ok(positions)
}

/// Records the durable event-count floor this batch left behind.
///
/// Best effort, and logged rather than propagated (`#799`): the batch is
/// already durable, so a floor that could not be written costs truncation
/// detection its freshness, not the commit its receipt. The floor stays at its
/// last recorded value until the next successful commit moves it.
async fn record_event_count_floor<E>(
    context: &E,
    count_checkpoints: &mut CountCheckpoints<E>,
    partition: &str,
    new_len: u64,
) where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    match count_checkpoints.record(context, partition, new_len).await {
        Ok(()) => {}
        Err(err) => {
            // Best-effort for the FLOOR, never for the handle. `record` drops
            // a store whose durable sync failed, so this leaves nothing
            // resident and the next commit reopens from durable storage. The
            // batch's own receipt stands: it was durable before this ran.
            tracing::warn!(
                partition = %partition,
                error = %err,
                "event-count checkpoint record failed (#799); truncation detection stays at its last recorded value until the next successful commit"
            );
        }
    }
}

/// Definite failure preparing a partition's next signed root before storage is
/// mutated by [`append_batch_one`].
#[derive(Debug, thiserror::Error)]
enum MmrPreparationError {
    /// Rebuilding the cold-start tree (a full replay) failed.
    #[error("mmr rebuild: {0}")]
    Rebuild(EventLogError),
    /// Extending the tree or signing the root failed.
    #[error("mmr extend/sign: {0}")]
    ExtendSign(polyc_eventlog::IntegrityError),
}

impl MmrPreparationError {
    fn into_eventlog_error(self) -> EventLogError {
        match self {
            Self::Rebuild(error) => error,
            Self::ExtendSign(error) => EventLogError::Integrity(error),
        }
    }

    /// Which stage of the signed-root step this failure came from.
    ///
    /// Named beside the error rather than inside the metric, so a new variant
    /// fails to compile here instead of silently counting as something else.
    const fn outcome(&self) -> metrics::AttestationOutcome {
        match self {
            Self::Rebuild(_) => metrics::AttestationOutcome::RebuildFailed,
            Self::ExtendSign(_) => metrics::AttestationOutcome::ExtendSignFailed,
        }
    }
}

/// Appends the prepared signed-root marker, reporting an uncertain outcome.
///
/// The marker is the last element of the batch. An append that fails here has
/// already left every event of the batch written, and the best-effort commit it
/// then runs may make them durable, so the outcome is genuinely unknown rather
/// than a clean failure. The caller learns that from the error and evicts both
/// caches: the prepared tree describes a batch this journal may hold only part
/// of, and the handle is fatal per Commonware's own contract.
async fn append_prepared_root<E>(
    log: &polyc_eventlog::EventLog<E>,
    partition: &str,
    marker: &Event,
) -> Result<(), EventLogError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    let append_result = match maybe_inject_root_append_failure(partition) {
        Some(error) => Err(error),
        None => log.append(marker).await.map(|_| ()),
    };
    let Err(error) = append_result else {
        return Ok(());
    };
    if let Err(commit_error) = log.commit().await {
        tracing::warn!(
            error = %commit_error,
            "commit after uncertain root-marker append failed"
        );
    }
    // The root was signed and its marker did not land. That is the one outcome
    // this label names, and it is a fact about content the best-effort commit
    // above may well have made durable.
    metrics::record_attestation(metrics::AttestationOutcome::MarkerAppendFailed);
    Err(error)
}

/// Rebuilds `partition`'s MMR on first touch, extends it with `events`, and
/// returns the signed-root marker to append with those events.
///
/// This runs before the first append, so every failure is definite. A warm
/// partition uses its process-local tree and does no replay; only a cold cache
/// pays the existing full-replay cost.
async fn prepare_signed_root<E>(
    log: &EventLog<E>,
    mmr_logs: &mut HashMap<String, polyc_mmr::VerifiableLog>,
    signer: &JournalAttestationSigner,
    partition: &str,
    events: &[Event],
) -> Result<Event, MmrPreparationError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler,
{
    if let Some(error) = maybe_inject_mmr_preparation_failure(partition) {
        return Err(MmrPreparationError::Rebuild(error));
    }
    if !mmr_logs.contains_key(partition) {
        let all = log.replay().await.map_err(MmrPreparationError::Rebuild)?;
        let rebuilt =
            polyc_eventlog::rebuild_from_events(&all).map_err(MmrPreparationError::ExtendSign)?;
        mmr_logs.insert(partition.to_owned(), rebuilt);
    }
    let mmr_log = mmr_logs.get(partition).expect("just ensured present above");
    polyc_eventlog::extend_and_sign(mmr_log, events, signer)
        .map_err(MmrPreparationError::ExtendSign)
}

enum EnsureFailure {
    Definite(EventLogError),
    Ambiguous(EventLogError),
}

#[allow(clippy::too_many_arguments)]
async fn ensure_partition_attested_one<E>(
    context: &E,
    storage_dir: &std::path::Path,
    logs: &mut OpenLogs<E>,
    count_checkpoints: &mut CountCheckpoints<E>,
    mmr_logs: &mut HashMap<String, polyc_mmr::VerifiableLog>,
    signer: &JournalAttestationSigner,
    trust: &polyc_crypto::signing_role::RoleTrustSet<
        polyc_crypto::signing_role::JournalAttestationRole,
    >,
    partition: &str,
) -> Result<Option<Event>, AppendError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    if !logs.contains(partition)
        && !partition_data_dir_exists(storage_dir, partition).map_err(AppendError::Listing)?
    {
        return Ok(None);
    }

    let result = async {
        let log = logs
            .get_or_open(context, partition)
            .await
            .map_err(EnsureFailure::Definite)?;
        let events = log.replay().await.map_err(EnsureFailure::Definite)?;
        polyc_eventlog::verify_replay_with_trust(&events, trust)
            .map_err(EventLogError::from)
            .map_err(EnsureFailure::Definite)?;
        let rebuilt = polyc_eventlog::rebuild_from_events(&events)
            .map_err(EventLogError::from)
            .map_err(EnsureFailure::Definite)?;
        let leaf_count = rebuilt
            .leaf_count()
            .map_err(polyc_eventlog::IntegrityError::from)
            .map_err(EventLogError::from)
            .map_err(EnsureFailure::Definite)?;
        if leaf_count == 0 {
            return Ok((None, rebuilt, log.len().await));
        }
        let exact = events.iter().rev().find_map(|event| {
            if event.kind != polyc_eventlog::MMR_SIGNED_ROOT_KIND {
                return None;
            }
            serde_json::from_slice::<polyc_mmr::SignedRoot>(&event.payload)
                .ok()
                .filter(|root| root.leaf_count == leaf_count)
                .map(|_| event.clone())
        });
        let marker = if let Some(marker) = exact {
            marker
        } else {
            let marker = polyc_eventlog::extend_and_sign(&rebuilt, &[], signer)
                .map_err(EventLogError::from)
                .map_err(EnsureFailure::Definite)?;
            match maybe_inject_root_append_failure(partition) {
                Some(error) => return Err(EnsureFailure::Ambiguous(error)),
                None => log
                    .append(&marker)
                    .await
                    .map_err(EnsureFailure::Ambiguous)?,
            };
            match maybe_inject_commit_failure(partition) {
                Some(error) => return Err(EnsureFailure::Ambiguous(error)),
                None => log.commit().await.map_err(EnsureFailure::Ambiguous)?,
            }
            marker
        };
        let new_len = log.len().await;
        Ok::<_, EnsureFailure>((Some(marker), rebuilt, new_len))
    }
    .await;

    let (marker, rebuilt, new_len) = match result {
        Ok(value) => value,
        Err(EnsureFailure::Definite(error)) => {
            logs.take(partition);
            mmr_logs.remove(partition);
            return Err(AppendError::Log(error));
        }
        Err(EnsureFailure::Ambiguous(error)) => {
            logs.take(partition);
            mmr_logs.remove(partition);
            return Err(AppendError::AttestationOutcomeUnknown(error));
        }
    };
    mmr_logs.insert(partition.to_owned(), rebuilt);
    // Best-effort, and the failed store is evicted rather than kept: see
    // [`CountCheckpoints`].
    if let Err(error) = count_checkpoints.record(context, partition, new_len).await {
        tracing::warn!(
            partition = %partition,
            error = %error,
            "event-count checkpoint record failed after attestation completion"
        );
    }
    Ok(marker)
}

/// Replay `partition` and verify its tamper-evidence (`#799`): first checks
/// the replay against the durable event-count checkpoint (`#799` hardening —
/// see `polyc_eventlog::checkpoint` and [`VerifyError::TruncatedReplay`]),
/// which catches a storage-layer self-healed truncation of already-committed
/// data before it can masquerade as a legitimately short replay, then checks
/// every signed MMR root — see [`polyc_eventlog::verify_replay`] for what
/// that checks.
async fn replay_verified_one<E>(
    context: &E,
    logs: &mut OpenLogs<E>,
    count_checkpoints: &mut CountCheckpoints<E>,
    journal_attestation_trust: &polyc_crypto::signing_role::RoleTrustSet<
        polyc_crypto::signing_role::JournalAttestationRole,
    >,
    partition: &str,
) -> Result<Vec<Event>, VerifyError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    let log = logs.get_or_open(context, partition).await?;
    let events = log.replay().await?;

    let expected = count_checkpoints.expected_count(context, partition).await?;
    let actual = events.len() as u64;
    if actual < expected {
        return Err(VerifyError::TruncatedReplay { expected, actual });
    }

    polyc_eventlog::verify_replay_with_trust(&events, journal_attestation_trust)?;
    Ok(events)
}

/// Recover `partition` from a corrupted item (`#799`): replay every position
/// independently (so one bad item cannot block the rest — see
/// [`EventLog::replay_quarantining`]), and — if anything was unreadable —
/// destroy and re-append only what decoded. A partition with nothing
/// corrupted is a no-op.
///
/// The re-appended content is RE-ROOTED (`#2322`). The stale signed roots are
/// filtered out. One fresh root is signed over the survivors. A repair drops
/// positions, so a retained root would describe more leaves than remain, and
/// the repaired partition would fail its own verification for good. The cached
/// running MMR takes the tree that root was built from, so the next
/// `AppendBatch` extends it instead of paying for a cold rebuild. A repair
/// resumed from a durable stage leaves the cache cold instead.
///
/// Also consults the durable event-count checkpoint (`#799` hardening — see
/// `polyc_eventlog::checkpoint`): [`EventLog::replay_quarantining`] can only
/// see positions the journal's own OPEN-time self-heal left in bounds, so a
/// corruption in the active/pre-allocated section — which that self-heal
/// silently truncates away, per `commonware-storage`'s own repair docs on
/// `variable::Journal` — never surfaces as an in-bounds decode failure at
/// all; `replay_quarantining` alone reports a clean, empty quarantine list
/// even though committed events are gone (the false negative this hardens
/// against). When the checkpoint expects more events than the journal
/// currently has in bounds, the gap is reported as synthetic
/// [`QuarantinedItem`]s (positions past what the journal can still see) with
/// an error explaining the content is unrecoverable, so a repair caller
/// always sees SOMETHING flagged instead of a silent "nothing to fix". The
/// checkpoint is then re-recorded against the true (possibly smaller)
/// surviving count, so a later verify judges the partition against reality
/// instead of re-flagging the same, already-reported gap forever.
/// What a repair actually did to a partition.
///
/// The quarantine list stopped being a proxy for "the partition changed" when
/// a stale root became repairable (`#2561`): a re-root destroys and rewrites
/// the partition while dropping nothing. Every caller that keys on change —
/// the mutation epoch that invalidates decoded caches, and
/// `RepairApplication` — has to read this instead.
#[derive(Debug)]
struct RepairEffect {
    /// Every position the repair dropped. Empty for a pure re-root.
    quarantined: Vec<QuarantinedItem>,
    /// Whether the partition was destroyed and rewritten.
    rewrote: bool,
}

#[derive(Clone)]
struct RepairScan {
    readable: Vec<(u64, Event)>,
    quarantined: Vec<QuarantinedItem>,
    before: [u8; 32],
    after: [u8; 32],
    /// How the readable events' own signed roots stand against them.
    ///
    /// Deliberately NOT folded into `quarantined`. A stale root is not a
    /// dropped position, and the quarantine list is what State durably records
    /// and reports to an operator. Adding synthetic entries to it would change
    /// what every caller reads out of a repair.
    ///
    /// It is also outside `before` and `after`. Both fingerprint content, and
    /// a partition's standing is derived from that same content, so folding it
    /// in would add nothing and would change fingerprints this build must keep
    /// comparable with the ones a prior inspection recorded.
    standing: polyc_eventlog::RootStanding,
}

/// Prefix for the private, durable survivor staging journals used by repair.
///
/// State rejects and hides this namespace; it is not a domain partition. A
/// stage remains until the repaired target fingerprint is durable, so a crash
/// after target destruction can reconstruct the survivors without relying on
/// process memory.
pub(crate) const REPAIR_STAGE_PREFIX: &str = "state-repair-stage-";

/// Prefix for the private, durable survivor staging journals used by rewrite.
///
/// A separate namespace from repair's, because the two name their stages from
/// different things. Sharing one prefix would let a rewrite and a repair of the
/// same partition compute the same stage name and read each other's content.
pub(crate) const REWRITE_STAGE_PREFIX: &str = "state-rewrite-stage-";
const EXACT_REWRITE_STAGE_PREFIX: &str = "state-exact-rewrite-stage-";
const EXACT_REWRITE_STAGE_COMPLETE_KIND: &str = "__polyc_state_exact_rewrite_stage_complete";
const REWRITE_STAGE_COMPLETE_KIND: &str = "__polyc_state_rewrite_stage_complete";

/// Names the durable stage a rewrite of `partition` writes under `command_id`.
///
/// Keyed on the command identity, never on content. A rewrite destroys its
/// target before restoring it, so after a crash there is no content left to
/// derive a name from — a content-keyed stage would be unfindable exactly when
/// it is needed (`#2323`). The identity is minted by State before the host is
/// dialed, and it is durable in the excision intent.
fn rewrite_stage_partition(partition: &str, command_id: &str) -> String {
    use sha2::Digest as _;

    let mut hash = sha2::Sha256::new();
    hash.update(b"polychrome/eventlog-rewrite-stage/v1");
    hash.update((partition.len() as u64).to_be_bytes());
    hash.update(partition.as_bytes());
    hash.update((command_id.len() as u64).to_be_bytes());
    hash.update(command_id.as_bytes());
    format!("{REWRITE_STAGE_PREFIX}{}", hex::encode(hash.finalize()))
}

/// The sentinel closing a complete rewrite stage.
///
/// Its presence is what separates a stage a crash left half-written from one
/// that holds every survivor. Only a complete stage may authorize restoring
/// over a destroyed target.
///
/// It also carries the number of records the rewrite dropped, so a resumed
/// rewrite reports the same outcome the interrupted one would have.
fn rewrite_stage_complete(count: u64, dropped: u64) -> Event {
    let mut payload = Vec::with_capacity(16);
    payload.extend_from_slice(&count.to_be_bytes());
    payload.extend_from_slice(&dropped.to_be_bytes());
    Event::new(REWRITE_STAGE_COMPLETE_KIND, payload)
}

/// Reads the survivors and the drop count back out of a complete rewrite stage.
///
/// Returns `None` for an absent, partial, or internally inconsistent stage. All
/// three mean the same thing to a caller: the stage cannot authorize a restore,
/// so the rewrite must be built again from the live partition.
fn staged_rewrite(events: &[Event]) -> Option<(Vec<Event>, u64)> {
    let (marker, survivors) = events.split_last()?;
    if marker.kind != REWRITE_STAGE_COMPLETE_KIND || marker.payload.len() != 16 {
        return None;
    }
    let count = u64::from_be_bytes(marker.payload[..8].try_into().ok()?);
    let dropped = u64::from_be_bytes(marker.payload[8..].try_into().ok()?);
    (count == survivors.len() as u64).then(|| (survivors.to_vec(), dropped))
}

fn physical_fingerprint(events: &[Event]) -> [u8; 32] {
    let indexed = events
        .iter()
        .cloned()
        .enumerate()
        .map(|(position, event)| (position as u64, event))
        .collect::<Vec<_>>();
    repair_fingerprint(&indexed, &[], events.len() as u64)
}

fn exact_rewrite_binding(
    partition: &str,
    command_id: &str,
    before: &[u8; 32],
    after: &[u8; 32],
) -> [u8; 32] {
    use sha2::Digest as _;

    let mut hash = sha2::Sha256::new();
    hash.update(b"polychrome/exact-rewrite-stage/v1");
    hash.update((partition.len() as u64).to_be_bytes());
    hash.update(partition.as_bytes());
    hash.update((command_id.len() as u64).to_be_bytes());
    hash.update(command_id.as_bytes());
    hash.update(before);
    hash.update(after);
    hash.finalize().into()
}

fn exact_rewrite_stage_partition(partition: &str, binding: &[u8; 32]) -> String {
    use sha2::Digest as _;

    let mut hash = sha2::Sha256::new();
    hash.update(b"polychrome/exact-rewrite-stage-name/v1");
    hash.update((partition.len() as u64).to_be_bytes());
    hash.update(partition.as_bytes());
    hash.update(binding);
    format!(
        "{EXACT_REWRITE_STAGE_PREFIX}{}",
        hex::encode(hash.finalize())
    )
}

fn exact_rewrite_stage_complete(
    before: [u8; 32],
    after: [u8; 32],
    binding: [u8; 32],
    count: u64,
    dropped: u64,
) -> Event {
    let mut payload = Vec::with_capacity(112);
    payload.extend_from_slice(&before);
    payload.extend_from_slice(&after);
    payload.extend_from_slice(&binding);
    payload.extend_from_slice(&count.to_be_bytes());
    payload.extend_from_slice(&dropped.to_be_bytes());
    Event::new(EXACT_REWRITE_STAGE_COMPLETE_KIND, payload)
}

fn exact_staged_rewrite(
    events: &[Event],
    before: &[u8; 32],
    after: &[u8; 32],
    binding: &[u8; 32],
) -> Option<(Vec<Event>, u64)> {
    let (marker, survivors) = events.split_last()?;
    if marker.kind != EXACT_REWRITE_STAGE_COMPLETE_KIND || marker.payload.len() != 112 {
        return None;
    }
    if marker.payload[..32] != before[..]
        || marker.payload[32..64] != after[..]
        || marker.payload[64..96] != binding[..]
        || marker.payload[96..104] != (survivors.len() as u64).to_be_bytes()
        || physical_fingerprint(survivors) != *after
    {
        return None;
    }
    let dropped = u64::from_be_bytes(marker.payload[104..112].try_into().ok()?);
    Some((survivors.to_vec(), dropped))
}
const REPAIR_STAGE_COMPLETE_KIND: &str = "__polyc_state_repair_stage_complete";

fn repair_stage_partition(partition: &str, before: &[u8; 32]) -> String {
    use sha2::Digest as _;

    let mut hash = sha2::Sha256::new();
    hash.update(b"polychrome/eventlog-repair-stage/v1");
    hash.update((partition.len() as u64).to_be_bytes());
    hash.update(partition.as_bytes());
    hash.update(before);
    format!("{REPAIR_STAGE_PREFIX}{}", hex::encode(hash.finalize()))
}

fn repair_stage_complete(before: [u8; 32], after: [u8; 32], count: u64) -> Event {
    let mut payload = Vec::with_capacity(72);
    payload.extend_from_slice(&before);
    payload.extend_from_slice(&after);
    payload.extend_from_slice(&count.to_be_bytes());
    Event::new(REPAIR_STAGE_COMPLETE_KIND, payload)
}

/// Reports whether a repair is still inside the window where it holds the
/// only complete copy of a partition.
///
/// True from the moment the destroy begins until the terminal count record
/// lands. In that window the partition on disk is missing content the stage
/// holds, so a reader must be refused and a retry must restore.
///
/// # Why this reads the floor and not the content
///
/// The obvious test is to compare what the partition holds against the staged
/// survivors. It cannot work, and this branch has three abandoned attempts to
/// prove it. A destroy that faults part-way leaves a readable SUFFIX of the
/// pre-repair content at its original positions; a restore that faults leaves
/// a PREFIX of the survivors with holes where frames did not decode; and a
/// partition that a later repair or excision rewrote holds its own content at
/// its own positions. The first two must resume and the third must never be
/// resumed over, yet all three are "some events, and not the staged ones".
/// Every shape test told two of the three apart and lost the other.
///
/// The floor is a fact somebody recorded. `destroy_one` clears it before it
/// removes anything and `apply_repair_scan` raises it only after the content
/// is back, so zero means "this partition's content was deliberately taken
/// away and has not been put back" — which is the question, exactly.
///
/// A partition that moved on closes the window rather than leaving it open:
/// growth, a second repair and an excision each record a floor above zero.
///
/// Read the direction of that carefully — it is not a claim that a nonzero
/// floor is unforgeable. `append_batch_one` logs rather than propagates a
/// failed record, and a repair whose survivors are empty records zero, so a
/// floor can read zero over content. The stage test above is what keeps those
/// harmless: a partition with no stage is never asked this question, and one
/// with a stage and matching fingerprints settles before it is asked.
async fn repair_window_is_open<E>(
    context: &E,
    count_checkpoints: &mut CountCheckpoints<E>,
    partition: &str,
) -> Result<bool, EventLogError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    Ok(count_checkpoints.expected_count(context, partition).await? == 0)
}

fn staged_survivors(events: &[Event], before: &[u8; 32], after: &[u8; 32]) -> Option<Vec<Event>> {
    let (marker, survivors) = events.split_last()?;
    if marker.kind != REPAIR_STAGE_COMPLETE_KIND || marker.payload.len() != 72 {
        return None;
    }
    if marker.payload[..32] != before[..]
        || marker.payload[32..64] != after[..]
        || marker.payload[64..] != (survivors.len() as u64).to_be_bytes()
    {
        return None;
    }
    let indexed = survivors
        .iter()
        .enumerate()
        .map(|(position, event)| (position as u64, event.clone()))
        .collect::<Vec<_>>();
    (repair_fingerprint(&indexed, &[], survivors.len() as u64) == *after)
        .then(|| survivors.to_vec())
}

impl RepairScan {
    /// Whether this repair rewrites the partition's content.
    ///
    /// Delegates to [`repair_rewrites`], which is the only place the question
    /// is decided. This method exists so a caller holding a scan can ask
    /// without restating the inputs.
    const fn will_rewrite(&self) -> bool {
        repair_rewrites(self.quarantined.is_empty(), self.standing)
    }

    fn plan(&self) -> RepairPlan {
        RepairPlan {
            before: self.before,
            after: self.after,
            will_rewrite: self.will_rewrite(),
            readable: self
                .readable
                .iter()
                .map(|(_, event)| event.clone())
                .collect(),
            quarantined: self.quarantined.clone(),
        }
    }
}

/// Decides whether a repair rewrites the partition's content.
///
/// Quarantining a record rewrites it. So does a root that no longer holds,
/// even with nothing to quarantine (`#2561`). A re-root strips every signed
/// root and appends a fresh one, which changes the physical content.
///
/// This is the only place the question is decided, because four phases must
/// agree on the answer. Inspection asks it before it applies the replacement
/// and computes the `after` fingerprint. The durable plan asks it to record
/// whether the repair rotates the lineage. Application asks it to decide
/// whether to apply the replacement that performs that rotation. Any retry or
/// collision path that asks the same question asks it here.
///
/// A second formula lets those phases disagree. That is what happened: a
/// stale-root re-root promised an `after` it never produced, and the partition
/// was restored carrying a lineage its own intent had already refused.
///
/// An empty partition answers [`polyc_eventlog::RootStanding::Holds`], so it
/// reports false. There is no marker to rewrite, and `repaired_content` fails
/// closed on a replacement it cannot apply exactly once.
const fn repair_rewrites(
    quarantine_is_empty: bool,
    standing: polyc_eventlog::RootStanding,
) -> bool {
    !quarantine_is_empty || !matches!(standing, polyc_eventlog::RootStanding::Holds)
}

fn repair_fingerprint(
    readable: &[(u64, Event)],
    quarantined: &[QuarantinedItem],
    expected: u64,
) -> [u8; 32] {
    use sha2::Digest as _;

    let mut hash = sha2::Sha256::new();
    hash.update(b"polychrome/eventlog-repair-state/v1");
    hash.update(expected.to_be_bytes());
    hash.update((readable.len() as u64).to_be_bytes());
    for (position, event) in readable {
        hash.update(position.to_be_bytes());
        hash.update((event.kind.len() as u64).to_be_bytes());
        hash.update(event.kind.as_bytes());
        hash.update([event.trust.as_u8()]);
        hash.update((event.payload.len() as u64).to_be_bytes());
        hash.update(&event.payload);
    }
    hash.update((quarantined.len() as u64).to_be_bytes());
    for item in quarantined {
        hash.update(item.position.to_be_bytes());
    }
    hash.finalize().into()
}

/// The content a repair restores: every readable event except the stale signed
/// roots, then one fresh root over exactly those events.
///
/// A repair drops the quarantined positions. The roots the partition already
/// carries describe more leaves than survive that drop. Re-appending them
/// verbatim leaves a partition whose own verification fails for good. The
/// repair then breaks the tamper-evidence it exists to preserve (`#2322`).
/// This rebuilds the tree over the survivors and signs one root for it.
/// [`rewrite_one`] already does the same for the erasure path (`#2301`).
///
/// Signing is deterministic: [`polyc_mmr::SignedRoot`] carries no clock and no
/// nonce, so the same survivors and the same signer always produce identical
/// bytes. The inspection that promises `after` and the apply that writes it
/// therefore agree without sharing any state, and re-signing content that was
/// already signed converges rather than drifting.
///
/// Returns an empty vector when nothing survives. An empty partition carries no
/// root and verifies trivially.
///
/// # Errors
///
/// Returns [`EventLogError`] if the tree cannot be rebuilt or the root cannot
/// be signed. Both leave the partition untouched, because every caller runs
/// this before its destructive half.
///
/// [`inspect_repair_one`] calls this to compute what a repair would leave. So
/// an inspection, which reads and never writes, can now fail for a signing
/// reason. Nothing else holds the throwaway tree, so this is unreachable in
/// practice.
fn repaired_content(
    readable: &[Event],
    signer: &JournalAttestationSigner,
    replacement: Option<&RepairEventReplacement>,
) -> Result<(Vec<Event>, Option<polyc_mmr::VerifiableLog>), EventLogError> {
    let mut survivors: Vec<Event> = readable
        .iter()
        .filter(|event| event.kind != polyc_eventlog::MMR_SIGNED_ROOT_KIND)
        .cloned()
        .collect();
    if let Some(replacement) = replacement {
        let mut replaced = 0_u8;
        for event in &mut survivors {
            if event.kind == replacement.kind {
                event.payload.clone_from(&replacement.payload);
                replaced = replaced.saturating_add(1);
            }
        }
        if replaced != 1 {
            return Err(EventLogError::RepairReplacement(format!(
                "expected one {} event, found {replaced}",
                replacement.kind
            )));
        }
    }
    if survivors.is_empty() {
        return Ok((Vec::new(), None));
    }
    let tree = polyc_eventlog::rebuild_from_events(&survivors)?;
    let marker = polyc_eventlog::extend_and_sign(&tree, &[], signer)?;
    let mut content = survivors;
    content.push(marker);
    Ok((content, Some(tree)))
}

async fn inspect_repair_one<E>(
    context: &E,
    logs: &mut OpenLogs<E>,
    count_checkpoints: &mut CountCheckpoints<E>,
    signer: &JournalAttestationSigner,
    trust: &polyc_crypto::signing_role::RoleTrustSet<
        polyc_crypto::signing_role::JournalAttestationRole,
    >,
    partition: &str,
    replacement: Option<&RepairEventReplacement>,
) -> Result<RepairScan, EventLogError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    let (ok, mut quarantined) = {
        let log = logs.get_or_open(context, partition).await?;
        log.replay_quarantining().await?
    };

    // Positions the journal can still see (readable or in-bounds-but-broken)
    // versus what the durable checkpoint says SHOULD exist. A gap here means
    // the active section was silently truncated by the journal's own
    // self-heal before `replay_quarantining` ever got a chance to see it.
    let visible = (ok.len() + quarantined.len()) as u64;
    let expected = count_checkpoints.expected_count(context, partition).await?;
    if visible < expected {
        for position in visible..expected {
            quarantined.push(QuarantinedItem {
                position,
                error: "position lost to the storage layer's silent truncation of the active \
                        section (torn write or corruption/tampering); original content is \
                        unrecoverable — see docs/operations/eventlog-disaster-recovery.md"
                    .to_owned(),
            });
        }
    }

    let before = repair_fingerprint(&ok, &quarantined, expected);
    // `after` promises the fingerprint of what the repair will actually leave
    // on disk, which since `#2322` is the RE-ROOTED content, not the readable
    // events verbatim. `apply_repair_conditionally` reads a later inspection's
    // `before` back against this value to recognize a repair that already
    // succeeded, so a promise made over the pre-repair bytes would never match
    // and every retry-after-success would be misread as a concurrent mutation.
    let raw: Vec<Event> = ok.iter().map(|(_, event)| event.clone()).collect();
    // Read the standing BEFORE the replacement decision, because that decision
    // depends on it. It reads `raw` and `trust` only, and nothing between here
    // and its old position touched either.
    let standing = polyc_eventlog::root_standing_with_trust(&raw, trust)?;
    // The replacement carries the new incarnation marker, and
    // `repaired_content` rewrites the matching event among the readable ones.
    // It never consults the quarantine list. So the question is not whether
    // this repair quarantined anything. It is whether this repair rewrites.
    //
    // Gating on the quarantine list made a stale-root re-root suppress the
    // marker it had promised to write. The partition was then restored
    // carrying its old lineage. The completion check refused the result after
    // the destructive half had already run.
    let replacement = repair_rewrites(quarantined.is_empty(), standing)
        .then_some(replacement)
        .flatten();
    let (restored, _) = repaired_content(&raw, signer, replacement)?;
    let survivors: Vec<(u64, Event)> = restored
        .iter()
        .enumerate()
        .map(|(position, event)| (position as u64, event.clone()))
        .collect();
    let survivor_count = survivors.len() as u64;
    let after = repair_fingerprint(&survivors, &[], survivor_count);
    Ok(RepairScan {
        readable: ok,
        quarantined,
        before,
        after,
        standing,
    })
}

/// Writes a raw repair copy and leaves no poisoned handle cached on either a
/// per-event or final-commit failure. The caller decides whether the copy is a
/// private stage or the restored target; both need identical crash semantics.
async fn append_repair_copy<E>(
    context: &E,
    logs: &mut OpenLogs<E>,
    partition: &str,
    events: &[Event],
) -> Result<(), EventLogError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    let log = logs.get_or_open(context, partition).await?;
    for (index, event) in events.iter().enumerate() {
        let append = match maybe_inject_append_failure(partition, index) {
            Some(error) => Err(error),
            None => log.append(event).await.map(|_| ()),
        };
        if let Err(error) = append {
            let _ = log.commit().await;
            logs.take(partition);
            return Err(error);
        }
    }
    let commit = match maybe_inject_commit_failure(partition) {
        Some(error) => Err(error),
        None => log.commit().await,
    };
    if let Err(error) = commit {
        logs.take(partition);
        return Err(error);
    }
    Ok(())
}

#[allow(clippy::too_many_arguments)]
async fn apply_repair_scan<E>(
    context: &E,
    logs: &mut OpenLogs<E>,
    checkpoints: &mut HashMap<String, CheckpointFrame>,
    count_checkpoints: &mut CountCheckpoints<E>,
    mmr_logs: &mut HashMap<String, polyc_mmr::VerifiableLog>,
    signer: &JournalAttestationSigner,
    partition: &str,
    scan: RepairScan,
    replacement: Option<&RepairEventReplacement>,
) -> Result<RepairEffect, EventLogError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    // Repair converts a verification failure into a success: it deletes every
    // root the partition holds and signs one fresh root under the trusted key.
    // So the set of failures it may run against is a security decision, not an
    // ergonomic one. A contradicted root says the surviving content is not
    // what a trusted key attested. Re-rooting would sign that contradiction
    // here and destroy the evidence rather than report it.
    //
    // This gate also covers the decode-failure path, which had none. But read
    // its reach precisely, because it is narrow.
    //
    // The standing is computed over the READABLE events. A root whose frame
    // `replay_quarantining` dropped contributes nothing to it, and every root
    // after the first dropped position over-claims its leaf count and so reads
    // as stale. `RootStanding`'s own doc gives the second half of the same
    // limit: the tree is running, so one lost leaf hides every later change.
    //
    // So this refuses exactly one thing: a trusted root, still readable, that
    // is contradicted at the leaf count it claims, before the first lost
    // position. It is not a proof that a repaired partition was untampered.
    // Past the first loss a repair is a trust reset over what follows, and the
    // runbook tells an operator so.
    if scan.standing == polyc_eventlog::RootStanding::Contradicted {
        return Err(EventLogError::RepairRefused);
    }
    // A stale root is work even with nothing to quarantine (`#2561`). The
    // partition decodes cleanly, so `replay_quarantining` reports nothing, and
    // this used to return before `repaired_content` re-rooted anything —
    // leaving an operator re-running the verb a no-op every time.
    //
    // The trigger is the ACTUAL standing of the roots, never "what is on disk
    // differs from what a repair would leave". `repaired_content` collapses
    // every root into one, so the second predicate is true of every healthy
    // partition with more than one batch and would rewrite the whole fleet.
    if !repair_rewrites(scan.quarantined.is_empty(), scan.standing) {
        return Ok(RepairEffect {
            quarantined: scan.quarantined,
            rewrote: false,
        });
    }
    // Re-root before anything is destroyed, so a partition this cannot re-root
    // is left exactly as it was (`#2322`, mirroring `rewrite_one`'s own
    // sign-first discipline). The re-root is unconditional: a resumed repair
    // re-signs content that already carries a fresh root, and determinism makes
    // that converge on identical bytes rather than drift.
    //
    // The replacement passes through unfiltered, because the early return above
    // already sent every non-rewriting repair back. Filtering it again here on
    // the same predicate reads as a decision and is not one. Inspection applied
    // the replacement under `repair_rewrites` when it computed the `after` it
    // promised, so applying it here is what produces that exact `after`.
    debug_assert!(
        repair_rewrites(scan.quarantined.is_empty(), scan.standing),
        "a non-rewriting repair returned above, so this point implies a rewrite"
    );
    let raw: Vec<Event> = scan.readable.into_iter().map(|(_, event)| event).collect();
    let (survivors, tree) = repaired_content(&raw, signer, replacement)?;
    let survivor_count = survivors.len() as u64;

    // Stage every survivor durably before the destructive half begins. The
    // final sentinel makes a partial stage distinguishable from a complete
    // one after a crash; an incomplete stage is safe to rebuild because the
    // target remains intact until this function observes the sentinel.
    let stage = repair_stage_partition(partition, &scan.before);
    let staged = {
        let log = logs.get_or_open(context, &stage).await?;
        let held = log.replay().await?;
        staged_survivors(&held, &scan.before, &scan.after)
    };
    // The cached tree travels only with the content this call built. A stage
    // that fingerprints to `scan.after` holds byte-identical content, so
    // reusing the tree across that branch would also be correct — but only by
    // an argument that lives outside the code. Dropping it instead keeps the
    // cache honest by construction: a resumed repair pays one cold rebuild on
    // its next append, and no future change to how content is derived can
    // silently leave a tree describing something else.
    let (survivors, tree) = if let Some(staged) = staged {
        (staged, None)
    } else {
        destroy_one(
            context,
            logs,
            checkpoints,
            count_checkpoints,
            mmr_logs,
            &stage,
            DestroyCheckpoint::Clear,
        )
        .await?;
        let mut staged = survivors.clone();
        staged.push(repair_stage_complete(
            scan.before,
            scan.after,
            survivor_count,
        ));
        append_repair_copy(context, logs, &stage, &staged).await?;
        (survivors, tree)
    };

    // `Clear`, not `Retain`, and that is a deliberate scope line rather than a
    // conclusion that this window is safe.
    //
    // Repair carries the same window a rewrite does: a crash between here and
    // the record below leaves an empty partition measured against a zeroed
    // floor, which verifies trivially and reports healthy. The survivors are
    // durably staged above, so a repair RETRY recovers them — repair resumes on
    // content fingerprints, not on the checkpoint, so it self-heals whatever the
    // count says. That is why a retry is safe here and why a rewrite needed a
    // retained floor instead.
    //
    // Retaining the floor here is not a free change: `inspect_repair_one` reads
    // the checkpoint to detect a silently truncated active section
    // (`visible < expected`, `#799`'s hardening), so a retained value would feed
    // that detection a number it did not mean. Closing this window belongs in a
    // change that reasons about both, not in this one. Tracked by #2568.
    destroy_one(
        context,
        logs,
        checkpoints,
        count_checkpoints,
        mmr_logs,
        partition,
        DestroyCheckpoint::Clear,
    )
    .await?;
    // Counted off the sequence actually written, not derived from how many
    // markers were filtered. The staged branch above returns content whose
    // fingerprint already matched `scan.after`, so both branches agree here.
    let restored_count = survivors.len() as u64;
    if !survivors.is_empty() {
        append_repair_copy(context, logs, partition, &survivors).await?;
        // The tree describes exactly what is now on disk, so the next append
        // extends it instead of paying for a cold rebuild — the same handoff
        // `rewrite_one` makes.
        if let Some(tree) = tree {
            mmr_logs.insert(partition.to_owned(), tree);
        }
    }
    // Re-baseline the checkpoint against what's actually left, so a
    // subsequent verify judges the repaired partition on reality rather than
    // re-reporting the gap this repair just surfaced.
    count_checkpoints
        .record(context, partition, restored_count)
        .await?;
    // Logged, not propagated, and the asymmetry with the record above is the
    // point. That record is what makes the repair durable, so its failure has
    // to fail the repair (`#2567`). This is cleanup after the repair is
    // already durable: propagating here would report a completed repair as
    // failed, State would write no completion receipt, and the partition would
    // carry an unfinished repair for good.
    if let Err(error) = destroy_one(
        context,
        logs,
        checkpoints,
        count_checkpoints,
        mmr_logs,
        &stage,
        DestroyCheckpoint::Clear,
    )
    .await
    {
        tracing::warn!(
            partition = %partition,
            %error,
            "a completed repair could not remove its survivor stage; the stage is inert now that \
             the partition is whole, and the window test keeps it from being replayed over one \
             that has moved on"
        );
    }
    tracing::warn!(
        partition = %partition,
        quarantined = scan.quarantined.len(),
        "partition repaired (#799): corrupted events quarantined so the rest replays again"
    );
    Ok(RepairEffect {
        quarantined: scan.quarantined,
        rewrote: true,
    })
}

/// Removes `stage` if it is on this storage, and reports success if it is not.
///
/// A directory test comes first because OPENING the stage is what would create
/// it. An erasure sweeps every repair and excision record naming a
/// conversation, and most of those left no stage behind.
///
/// # Errors
///
/// Returns [`AppendError::Log`] if the removal fails. A failed sweep fails the
/// erasure that asked for it, which is retried.
async fn destroy_stage_if_present<E>(
    context: &E,
    storage_dir: &std::path::Path,
    logs: &mut OpenLogs<E>,
    checkpoints: &mut HashMap<String, CheckpointFrame>,
    count_checkpoints: &mut CountCheckpoints<E>,
    mmr_logs: &mut HashMap<String, polyc_mmr::VerifiableLog>,
    stage: &str,
) -> Result<(), AppendError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    // Propagated, NOT `unwrap_or`. `partition_data_dir_exists` says it in its
    // own doc: an unreadable volume is not an absent partition, and a caller
    // that destroys on `false` must not act on a storage fault. Swallowing it
    // here would report a sweep that never looked, so the erasure would be
    // recorded complete with the staged copy still on the volume — and that
    // stage would then be read as a repair still in flight, sending every
    // later reader to a retry that restores the erased conversation.
    //
    // `unwrap_or(true)` is not the alternative either: it would open, and so
    // CREATE, a stage that is not there. The erasure fails and is retried.
    if !logs.contains(stage) && !partition_data_dir_exists(storage_dir, stage)? {
        return Ok(());
    }
    destroy_one(
        context,
        logs,
        checkpoints,
        count_checkpoints,
        mmr_logs,
        stage,
        DestroyCheckpoint::Clear,
    )
    .await
    .map_err(AppendError::Log)
}

/// Body of [`Command::RepairSettled`]: reports whether the repair fenced by
/// `expected` left content a reader may trust.
///
/// Three states, and only the middle one is damage:
///
/// - The partition already fingerprints to `after`. The repair landed. Trust
///   it.
/// - A COMPLETE stage exists and the partition does not match `after`. The
///   destructive half is in flight or a crash abandoned it. Do not trust the
///   content.
/// - Anything else. Either no repair ever crossed the destructive boundary, or
///   one crossed it, finished, and the partition grew past what it left.
///
/// Two recorded facts decide it, and neither is the content.
///
/// The stage says a repair reached its destructive half at all. It is written
/// before the destroy, so a partition with no stage was never at risk.
///
/// The count floor says whether that half finished. `destroy_one` clears the
/// floor before it removes anything and `apply_repair_scan` raises it only
/// once the content is back, so zero means the content is deliberately absent.
///
/// Content answers neither, and three predicates over it each got a different
/// population wrong before this one. A destroy that faults part-way leaves a
/// readable SUFFIX of the old content; a restore that faults leaves a PREFIX
/// with holes; a partition a later repair or excision rewrote holds its own
/// content at its own positions. The first two must resume and the third must
/// never be resumed over, and all three are "some events, not the staged
/// ones".
///
/// The floor alone is not enough either, which is why the stage is still
/// consulted: an ERASURE clears the floor too, so an erased partition and one
/// mid-repair are identical on disk. `CommonwareJournal::apply_destruction`
/// removes the stages naming a partition AFTER it erases the partition — the
/// erasure is what refuses a partition whose repair is genuinely unfinished,
/// so sweeping first would delete the stage that refusal depends on. A stage
/// therefore never outlives the conversation it copies.
///
/// An INCOMPLETE stage reads as settled. `append_repair_copy` writes the
/// stage's sentinel last, so a stage without one proves the destroy never ran
/// and the target is untouched.
#[allow(clippy::too_many_arguments)]
async fn repair_settled_one<E>(
    context: &E,
    storage_dir: &std::path::Path,
    logs: &mut OpenLogs<E>,
    count_checkpoints: &mut CountCheckpoints<E>,
    signer: &JournalAttestationSigner,
    trust: &polyc_crypto::signing_role::RoleTrustSet<
        polyc_crypto::signing_role::JournalAttestationRole,
    >,
    partition: &str,
    expected: RepairFingerprints,
) -> Result<bool, AppendError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    let RepairFingerprints { before, after } = expected;
    // The stage decides, so the stage is what this looks at — and it looks at
    // nothing else until the stage says there is something to look at.
    //
    // Order matters twice over. A directory test comes first because OPENING
    // the stage is what would create it, and this probe runs on an ordinary
    // read path. The target is inspected last, and only past both stage tests,
    // because `inspect_repair_one` opens the target too: probing it up front
    // would let an ordinary read recreate the storage of a partition that was
    // destroyed while an old repair record still named it.
    let stage = repair_stage_partition(partition, &before);
    // `unwrap_or(true)`, matching `resume_rewrite`. A volume this cannot read
    // falls through to the open below, which reports the real failure. This
    // probe runs on an ordinary read path, so deciding a storage failure here
    // would take a partition offline for a question about a directory entry.
    if !logs.contains(&stage) && !partition_data_dir_exists(storage_dir, &stage).unwrap_or(true) {
        // No stage, so no repair ever crossed the destructive boundary — or
        // one crossed it, finished, and removed its stage. Either way the
        // content on disk is the content a reader should have.
        return Ok(true);
    }
    let held = {
        let log = logs
            .get_or_open(context, &stage)
            .await
            .map_err(AppendError::Log)?;
        log.replay().await.map_err(AppendError::Log)?
    };
    // An incomplete stage. `append_repair_copy` writes the sentinel last, so a
    // stage without one proves the destroy never ran.
    if staged_survivors(&held, &before, &after).is_none() {
        return Ok(true);
    }
    let scan = inspect_repair_one(
        context,
        logs,
        count_checkpoints,
        signer,
        trust,
        partition,
        None,
    )
    .await
    .map_err(AppendError::Log)?;
    // Three ways a complete stage sits beside content a reader may trust. The
    // repair finished and the partition holds what it promised; the repair died
    // between writing the stage and destroying the target, so the target is
    // still byte-for-byte what every reader already had; or the stage outlived
    // the repair that wrote it and the partition has moved on since.
    //
    // The third is why the window test is here rather than a count comparison.
    // A stale stage over a grown partition looks exactly like an interrupted
    // repair to any test built on the fingerprints alone, and refusing it
    // would take a healthy partition offline permanently.
    let window_open = repair_window_is_open(context, count_checkpoints, partition)
        .await
        .map_err(AppendError::Log)?;
    Ok(scan.before == after || scan.before == before || !window_open)
}

/// Removes the survivor stage a finished repair left behind.
///
/// Logged, not propagated, for the reason `apply_repair_scan` gives at its own
/// terminal cleanup: the partition already holds what the repair promised, so
/// failing here would report a finished repair as failed and leave it
/// unreceiptable for good. Retrying the same command is what an operator uses
/// to clear a stage an earlier cleanup could not remove.
#[allow(clippy::too_many_arguments)]
async fn sweep_finished_repair_stage<E>(
    context: &E,
    logs: &mut OpenLogs<E>,
    checkpoints: &mut HashMap<String, CheckpointFrame>,
    count_checkpoints: &mut CountCheckpoints<E>,
    mmr_logs: &mut HashMap<String, polyc_mmr::VerifiableLog>,
    partition: &str,
    before: &[u8; 32],
) where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    let stage = repair_stage_partition(partition, before);
    if let Err(error) = destroy_one(
        context,
        logs,
        checkpoints,
        count_checkpoints,
        mmr_logs,
        &stage,
        DestroyCheckpoint::Clear,
    )
    .await
    {
        tracing::warn!(
            partition = %partition,
            %error,
            "a finished repair could not remove its survivor stage"
        );
    }
}

/// Applies a fingerprint-fenced repair, resuming from a durable survivor stage
/// when a prior process died after destroying or partially restoring the
/// target.
#[derive(Clone, Copy)]
struct RepairFingerprints {
    before: [u8; 32],
    after: [u8; 32],
}

#[allow(clippy::too_many_arguments)]
async fn apply_repair_conditionally<E>(
    context: &E,
    logs: &mut OpenLogs<E>,
    checkpoints: &mut HashMap<String, CheckpointFrame>,
    count_checkpoints: &mut CountCheckpoints<E>,
    mmr_logs: &mut HashMap<String, polyc_mmr::VerifiableLog>,
    signer: &JournalAttestationSigner,
    trust: &polyc_crypto::signing_role::RoleTrustSet<
        polyc_crypto::signing_role::JournalAttestationRole,
    >,
    partition: &str,
    expected: RepairFingerprints,
    replacement: Option<&RepairEventReplacement>,
) -> Result<(RepairApplication, usize), EventLogError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    let RepairFingerprints { before, after } = expected;
    let scan = inspect_repair_one(
        context,
        logs,
        count_checkpoints,
        signer,
        trust,
        partition,
        replacement,
    )
    .await?;
    // `AlreadyApplied` only for a partition whose roots actually hold. An
    // intent written before `#2559` promised an `after` over the survivors
    // verbatim, stale roots included, so a fresh scan of the partition it
    // left matches that promise and this branch used to report the repair
    // done over a partition that does not verify (`#2561`).
    if scan.before == after && scan.standing == polyc_eventlog::RootStanding::Holds {
        // Logged, not propagated, for the reason `apply_repair_scan` gives at
        // its own terminal cleanup: the partition already holds what the
        // repair promised, so failing here would report a finished repair as
        // failed and leave it unreceiptable for good. This is also the branch
        // that sweeps a stage an earlier cleanup could not remove, so a retry
        // of the same command is what an operator uses to clear one.
        sweep_finished_repair_stage(
            context,
            logs,
            checkpoints,
            count_checkpoints,
            mmr_logs,
            partition,
            &before,
        )
        .await;
        return Ok((RepairApplication::AlreadyApplied, 0));
    }
    if scan.before == before {
        let quarantined = scan.quarantined.len();
        // From the effect, never from the quarantine count. A stale-root
        // repair rewrites the partition and drops nothing, so a count-based
        // verdict would report `AlreadyApplied` over a partition that was just
        // destroyed and re-signed — and the caller bumps the mutation epoch on
        // exactly this verdict.
        let effect = apply_repair_scan(
            context,
            logs,
            checkpoints,
            count_checkpoints,
            mmr_logs,
            signer,
            partition,
            scan,
            replacement,
        )
        .await?;
        return Ok((
            if effect.rewrote {
                RepairApplication::Applied
            } else {
                RepairApplication::AlreadyApplied
            },
            quarantined,
        ));
    }

    // Neither fingerprint matches. This is a concurrent mutation unless a
    // complete stage proves a prior repair crossed the destructive boundary
    // AND the target is still inside the window that repair opened. Resume
    // from that durable copy only then.
    let stage = repair_stage_partition(partition, &before);
    let held = {
        let log = logs.get_or_open(context, &stage).await?;
        log.replay().await?
    };
    let Some(survivors) = staged_survivors(&held, &before, &after) else {
        return Ok((RepairApplication::Changed, 0));
    };
    // A complete stage is NOT on its own a license to restore it. The stage is
    // destroyed after the terminal count record, so one that outlived its own
    // repair sits beside a partition that is already whole and may since have
    // taken new commits. Restoring over that partition would destroy events
    // that were committed, receipted and acknowledged — and the runbook sends
    // an operator here, so it would do it on instruction.
    //
    // The floor answers it. A partition that took a commit, or that a later
    // repair or excision rewrote, recorded a floor above zero and is refused.
    // A repair still inside its destructive window recorded zero and resumes,
    // which is this branch's whole purpose.
    let window_open = repair_window_is_open(context, count_checkpoints, partition).await?;
    drop(scan);
    if !window_open {
        return Ok((RepairApplication::Changed, 0));
    }
    let staged_events = survivors.clone();
    let readable = survivors
        .into_iter()
        .enumerate()
        .map(|(position, event)| (position as u64, event))
        .collect::<Vec<_>>();
    let effect = apply_repair_scan(
        context,
        logs,
        checkpoints,
        count_checkpoints,
        mmr_logs,
        signer,
        partition,
        RepairScan {
            readable,
            // Non-empty only to select the rewrite path. State's durable
            // intent owns the real quarantine outcome returned to callers.
            quarantined: vec![QuarantinedItem {
                position: 0,
                error: "repair resumed from durable survivor stage".to_owned(),
            }],
            before,
            after,
            // Computed, not assumed. The stage fingerprints to `after`, so it
            // holds one fresh root over the survivors and its standing is
            // `Holds` by construction — but "by construction" is an argument
            // that lives outside the code, and the gate this feeds is a
            // security gate.
            standing: polyc_eventlog::root_standing_with_trust(&staged_events, trust)?,
        },
        replacement,
    )
    .await?;
    // Read, not assumed. The fabricated quarantine entry above forces the
    // rewrite path, so this is `Applied` today — but that is an argument
    // living outside the code, and this file rejects those elsewhere.
    Ok((
        if effect.rewrote {
            RepairApplication::Applied
        } else {
            RepairApplication::AlreadyApplied
        },
        0,
    ))
}

#[allow(clippy::too_many_arguments)]
async fn repair_one<E>(
    context: &E,
    logs: &mut OpenLogs<E>,
    checkpoints: &mut HashMap<String, CheckpointFrame>,
    count_checkpoints: &mut CountCheckpoints<E>,
    mmr_logs: &mut HashMap<String, polyc_mmr::VerifiableLog>,
    signer: &JournalAttestationSigner,
    trust: &polyc_crypto::signing_role::RoleTrustSet<
        polyc_crypto::signing_role::JournalAttestationRole,
    >,
    partition: &str,
) -> Result<RepairEffect, EventLogError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    let scan = inspect_repair_one(
        context,
        logs,
        count_checkpoints,
        signer,
        trust,
        partition,
        None,
    )
    .await?;
    apply_repair_scan(
        context,
        logs,
        checkpoints,
        count_checkpoints,
        mmr_logs,
        signer,
        partition,
        scan,
        None,
    )
    .await
}

/// Open-on-first-use and replay `partition`'s log in order.
async fn replay_one<E>(
    context: &E,
    logs: &mut OpenLogs<E>,
    partition: &str,
) -> Result<Vec<Event>, EventLogError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    #[cfg(test)]
    maybe_pause_replay(partition).await;
    let log = logs.get_or_open(context, partition).await?;
    log.replay().await
}

#[cfg(test)]
async fn maybe_pause_replay(partition: &str) {
    if let Some(pause) = tests::take_replay_pause(partition) {
        pause.entered.notify_one();
        pause.release.notified().await;
    }
}

/// Body of [`Command::ReplayWithPositions`]: the same ordered replay, keeping
/// each event's durable journal position.
async fn replay_with_positions_one<E>(
    context: &E,
    logs: &mut OpenLogs<E>,
    partition: &str,
) -> Result<Vec<(u64, Event)>, EventLogError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    let log = logs.get_or_open(context, partition).await?;
    log.replay_with_positions().await
}

/// Body of [`Command::ReplayWithPositionsBounded`]: the same ordered
/// replay, stopping early once `max_bytes` of cumulative payload has been
/// read — see [`polyc_eventlog::EventLog::replay_with_positions_bounded`]'s
/// doc for the early-abort mechanics.
async fn replay_with_positions_bounded_one<E>(
    context: &E,
    logs: &mut OpenLogs<E>,
    partition: &str,
    max_bytes: u64,
) -> Result<BoundedReplay, EventLogError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    let log = logs.get_or_open(context, partition).await?;
    log.replay_with_positions_bounded(max_bytes).await
}

/// Body of [`Command::ReplayFromWithPositions`]: resume replay at journal
/// position `start`, keeping each event's durable position — see
/// [`polyc_eventlog::EventLog::replay_from_with_positions`]'s own doc for the
/// clamping/empty-range rules this delegates to verbatim.
async fn replay_from_with_positions_one<E>(
    context: &E,
    logs: &mut OpenLogs<E>,
    partition: &str,
    start: u64,
) -> Result<Vec<(u64, Event)>, EventLogError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    let log = logs.get_or_open(context, partition).await?;
    log.replay_from_with_positions(start).await
}

/// Body of [`Command::ReplayFromWithPositionsBounded`]: resume replay at
/// journal position `start`, stopping early once `max_bytes` of cumulative
/// payload has been read — see
/// [`polyc_eventlog::EventLog::replay_from_with_positions_bounded`]'s doc for
/// the exact clamping/early-abort mechanics this delegates to verbatim.
async fn replay_from_with_positions_bounded_one<E>(
    context: &E,
    logs: &mut OpenLogs<E>,
    partition: &str,
    start: u64,
    max_bytes: u64,
) -> Result<BoundedReplay, EventLogError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    let log = logs.get_or_open(context, partition).await?;
    log.replay_from_with_positions_bounded(start, max_bytes)
        .await
}

/// Body of [`Command::ReplayRangeWithPositionsBounded`]: replay the half-open
/// position range `[start, end)` under a byte budget — see
/// [`polyc_eventlog::EventLog::replay_range_with_positions_bounded`]'s doc for
/// the exact clamping, end-exclusion, and early-abort mechanics this delegates
/// to verbatim.
async fn replay_range_with_positions_bounded_one<E>(
    context: &E,
    logs: &mut OpenLogs<E>,
    partition: &str,
    start: u64,
    end: u64,
    max_bytes: u64,
) -> Result<BoundedReplay, EventLogError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    let log = logs.get_or_open(context, partition).await?;
    log.replay_range_with_positions_bounded(start, end, max_bytes)
        .await
}

/// Body of [`Command::EventsSinceCheckpoint`]: the journal size minus the
/// cached checkpoint's tail offset (O(1), no scan). No cached checkpoint ⇒ the
/// whole log is the tail, so the count is the size. See the public method for
/// the cold-partition over-estimate note.
async fn events_since_checkpoint_one<E>(
    context: &E,
    logs: &mut OpenLogs<E>,
    checkpoints: &HashMap<String, CheckpointFrame>,
    partition: &str,
) -> Result<u64, EventLogError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    let log = logs.get_or_open(context, partition).await?;
    let len = log.len().await;
    let since = checkpoints
        .get(partition)
        .map_or(len, |frame| len.saturating_sub(frame.tail_offset));
    Ok(since)
}

/// Body of [`Command::PartitionEventCount`]: the journal's total size
/// (O(1)), without opening (and thereby creating) a partition that has
/// never been written.
///
/// `get_or_open` unconditionally creates the on-disk journal for an unknown
/// name (`EventLog::open` is create-or-recover), so this checks
/// [`list_partitions_bounded_in`] first — the same raw filesystem read
/// [`Command::ListPartitions`] answers from — and returns `0` without ever
/// calling `get_or_open` when `partition` isn't among the on-disk names. A
/// partition already cached in `logs` is by definition already on disk (it
/// could only have gotten into the cache via a prior `get_or_open`), so the
/// existence check is skipped for the warm-cache case rather than paying a
/// redundant directory read.
async fn partition_event_count_one<E>(
    context: &E,
    storage_dir: &std::path::Path,
    logs: &mut OpenLogs<E>,
    partition: &str,
) -> Result<u64, AppendError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    if !logs.contains(partition) {
        // One directory test, shared with the module's own existence probe.
        // A listing here would read every other partition's identity to
        // answer a question about this one.
        if !partition_data_dir_exists(storage_dir, partition)? {
            return Ok(0);
        }
    }
    let log = logs
        .get_or_open(context, partition)
        .await
        .map_err(AppendError::Log)?;
    Ok(log.len().await)
}

/// Body of [`Command::ReplayTailFromCheckpoint`]: return the latest checkpoint
/// for `partition` plus the events after it. On a warm cache, seek straight to
/// the cached tail offset; on a cold partition, replay fully, locate the last
/// checkpoint event, populate the cache, and return its tail.
async fn replay_tail_one<E>(
    context: &E,
    logs: &mut OpenLogs<E>,
    checkpoints: &mut HashMap<String, CheckpointFrame>,
    partition: &str,
) -> Result<CheckpointReplay, EventLogError>
where
    E: commonware_storage::Context + commonware_runtime::BufferPooler + commonware_runtime::Metrics,
{
    if let Some(frame) = checkpoints.get(partition) {
        let tail_offset = frame.tail_offset;
        let payload = frame.payload.clone();
        let log = logs.get_or_open(context, partition).await?;
        let tail = log.replay_from(tail_offset).await?;
        return Ok(CheckpointReplay {
            checkpoint: Some(CheckpointFrame {
                tail_offset,
                payload,
            }),
            tail,
        });
    }
    // Cold partition: full replay, find the latest checkpoint, cache it.
    let log = logs.get_or_open(context, partition).await?;
    let all = log.replay_with_positions().await?;
    let latest = all
        .iter()
        .rev()
        .find(|(_, ev)| parse_kind(&ev.kind).0 == BASE_COMPACTION_CHECKPOINT)
        .map(|(pos, ev)| (*pos, ev.payload.clone()));
    match latest {
        Some((pos, payload)) => {
            let tail_offset = pos + 1;
            checkpoints.insert(
                partition.to_owned(),
                CheckpointFrame {
                    tail_offset,
                    payload: payload.clone(),
                },
            );
            let tail = all
                .into_iter()
                .filter_map(|(p, ev)| (p >= tail_offset).then_some(ev))
                .collect();
            Ok(CheckpointReplay {
                checkpoint: Some(CheckpointFrame {
                    tail_offset,
                    payload,
                }),
                tail,
            })
        }
        None => Ok(CheckpointReplay {
            checkpoint: None,
            tail: all.into_iter().map(|(_, ev)| ev).collect(),
        }),
    }
}

#[cfg(test)]
mod tests {
    use super::{
        AppendError, CheckpointFrame, EventLogError, EventLogHost, ListPartitionsError,
        PartitionMigration, RepairApplication, RewriteDecision, arm_root_append_failure,
    };
    use polyc_eventlog::Event;
    use std::{
        collections::{HashMap, HashSet},
        sync::{Arc, Mutex, OnceLock},
    };
    use tokio_util::sync::CancellationToken;

    /// Shortens every backing blob under one of `partition`'s storage
    /// directories to `raw_len` bytes, and reports how many it shortened.
    fn shorten_backing_blobs(
        dir: &std::path::Path,
        partition: &str,
        suffix: &str,
        raw_len: u64,
    ) -> usize {
        let mut shortened = 0;
        let entries = std::fs::read_dir(dir.join(format!("{partition}{suffix}")))
            .expect("partition storage directory");
        for entry in entries {
            let path = entry.expect("directory entry").path();
            if !path.is_file() {
                continue;
            }
            let file = std::fs::OpenOptions::new()
                .write(true)
                .open(&path)
                .expect("open the backing blob");
            file.set_len(raw_len).expect("shorten below the header");
            file.sync_all().expect("make the truncation durable");
            shortened += 1;
        }
        shortened
    }

    /// The durable event-count floor is what turns Commonware's partial-header
    /// recovery back into damage.
    ///
    /// Commonware 2026.7.1 treats every backing blob shorter than its
    /// eight-byte runtime header as an interrupted creation: it truncates the
    /// file to zero, writes a valid empty header, and syncs. For a DATA blob
    /// that means an established conversation reopens as a healthy, empty
    /// journal with no error — `polyc-eventlog`'s own
    /// `a_backing_blob_below_the_runtime_header_never_reopens_short` pins that
    /// exact behaviour for all eight prefix lengths.
    ///
    /// The primitive cannot do better; it has no evidence separating an
    /// interrupted first creation from an established blob someone shortened.
    /// This host does, and this test is that claim: the floor still records
    /// what was committed, so a verified replay reports a truncation rather
    /// than serving an empty conversation, and presence still answers
    /// `Present` rather than `Absent`.
    #[tokio::test]
    async fn a_data_blob_below_the_runtime_header_reads_as_truncation_not_an_empty_conversation() {
        for raw_len in 0..8u64 {
            let dir = std::env::temp_dir().join(format!(
                "polychrome-eventlog-partial-header-{}-{raw_len}",
                std::process::id()
            ));
            let _ = std::fs::remove_dir_all(&dir);
            let partition = "conv-partial-header".to_owned();

            let shutdown = CancellationToken::new();
            let host = EventLogHost::spawn(
                dir.clone(),
                shutdown.clone(),
                polyc_crypto::signing_role::JournalAttestationSigner::from_seed(23),
            )
            .expect("spawn host");
            host.append_batch(
                partition.clone(),
                vec![
                    Event::new("user_msg", b"one".to_vec()),
                    Event::new("output_msg", b"two".to_vec()),
                    Event::new("tool_call", b"three".to_vec()),
                ],
            )
            .await
            .expect("seed");
            let committed = host
                .partition_event_count(partition.clone())
                .await
                .expect("count");
            assert!(committed >= 3, "the batch and its signed root are durable");
            drop(host);
            shutdown.cancel();

            let shortened = shorten_backing_blobs(&dir, &partition, "_data", raw_len);
            assert!(shortened > 0, "the case must actually shorten a data blob");

            let shutdown = CancellationToken::new();
            let host = EventLogHost::spawn(
                dir.clone(),
                shutdown.clone(),
                polyc_crypto::signing_role::JournalAttestationSigner::from_seed(23),
            )
            .expect("respawn host");

            let error = host
                .replay_verified(partition.clone())
                .await
                .expect_err("a shortened data blob must not verify as a short conversation");
            match error {
                AppendError::Verify(super::VerifyError::TruncatedReplay { expected, actual }) => {
                    assert_eq!(expected, committed, "the floor still names what committed");
                    assert_eq!(
                        actual, 0,
                        "Commonware reset the blob to empty; the floor is what catches it"
                    );
                }
                other => panic!(
                    "a data blob shortened to {raw_len} byte(s) reported {other} rather than a \
                     truncated replay"
                ),
            }

            assert_eq!(
                host.partition_presence(partition.clone())
                    .await
                    .expect("presence"),
                super::PartitionPresence::Present,
                "storage that lost its header is still present; reporting absence would let a \
                 caller read the conversation as one that never held anything"
            );

            drop(host);
            shutdown.cancel();
            let _ = std::fs::remove_dir_all(&dir);
        }
    }

    /// An interrupted reclaim converges to absence when the same command runs
    /// again, from every partial-removal state the removal can stop in.
    ///
    /// `reclaim` is still Commonware's final-teardown `destroy`, and that is
    /// three partition removals in sequence — data blobs, then the offsets
    /// blobs, then the offsets checkpoint — each one a `remove_dir_all` that
    /// can itself stop after some files. The emptiness refusal in front of it
    /// proves no HISTORY can be stranded, because there is none left to
    /// strand. It does not by itself prove the leftovers can be finished.
    ///
    /// This is the proof that they can. Every subset of the three directories
    /// is deleted, and then the erase command runs again through the real
    /// host. Each case must reopen without error and reach `Absent`.
    ///
    /// The retry path is what is under test: `destroy_one` opens the partition
    /// before it removes anything, so a leftover that could not be mounted
    /// would strand the erase instead of finishing it. An empty partition is
    /// what makes that safe — a missing data partition reads as empty, a
    /// missing offsets partition reads as empty, and a missing checkpoint
    /// reads as fresh — so every leftover here is mountable by construction.
    #[tokio::test]
    async fn an_interrupted_reclaim_converges_to_absence_on_the_next_attempt() {
        // Every subset of the three directories a reclaim removes.
        let suffixes = ["_data", "_offsets-blobs", "_offsets-metadata"];
        for mask in 0..8u8 {
            let dir = std::env::temp_dir().join(format!(
                "polychrome-eventlog-partial-reclaim-{}-{mask}",
                std::process::id()
            ));
            let _ = std::fs::remove_dir_all(&dir);
            let partition = "conv-partial-reclaim".to_owned();

            let shutdown = CancellationToken::new();
            let host = EventLogHost::spawn(
                dir.clone(),
                shutdown.clone(),
                polyc_crypto::signing_role::JournalAttestationSigner::from_seed(26),
            )
            .expect("spawn host");
            host.append_batch(
                partition.clone(),
                vec![Event::new("user_msg", b"one".to_vec())],
            )
            .await
            .expect("seed");
            drop(host);
            shutdown.cancel();

            // Stand in for a reclaim that stopped part-way. The journal is
            // already empty at that point in the real sequence, so emptying it
            // here first is what makes this the same state rather than a
            // harsher one.
            {
                let shutdown = CancellationToken::new();
                let host = EventLogHost::spawn(
                    dir.clone(),
                    shutdown.clone(),
                    polyc_crypto::signing_role::JournalAttestationSigner::from_seed(26),
                )
                .expect("spawn host to empty");
                host.rewrite_partition_for_test(
                    partition.clone(),
                    Box::new(|_: &Event| RewriteDecision::Drop),
                )
                .await
                .expect("empty the partition");
                drop(host);
                shutdown.cancel();
            }

            let mut removed = Vec::new();
            for (index, suffix) in suffixes.iter().enumerate() {
                if mask & (1 << index) == 0 {
                    continue;
                }
                let path = dir.join(format!("{partition}{suffix}"));
                if path.exists() {
                    std::fs::remove_dir_all(&path).expect("remove a partition directory");
                    removed.push(*suffix);
                }
            }

            // The same command, run again.
            let shutdown = CancellationToken::new();
            let host = EventLogHost::spawn(
                dir.clone(),
                shutdown.clone(),
                polyc_crypto::signing_role::JournalAttestationSigner::from_seed(26),
            )
            .expect("respawn host");
            host.destroy_partition(partition.clone())
                .await
                .unwrap_or_else(|error| {
                    panic!(
                        "a retry after a reclaim that stopped having removed {removed:?} must \
                         finish rather than strand the erase, got {error}"
                    )
                });
            assert_eq!(
                host.partition_presence(partition.clone())
                    .await
                    .expect("presence"),
                super::PartitionPresence::Absent,
                "the erase must converge to absence after stopping with {removed:?} removed"
            );

            drop(host);
            shutdown.cancel();
            let _ = std::fs::remove_dir_all(&dir);
        }
    }

    /// What the durable floor survives, and where it stops.
    ///
    /// The floor lives in a Commonware `Metadata` store, which keeps two
    /// copies and rotates between them. `Metadata::load` at this release
    /// normalizes a copy it cannot read to an empty one, so the number of
    /// unreadable copies decides the answer:
    ///
    /// - ONE copy unreadable: the surviving copy answers, and the floor is
    ///   intact. That rotation is the reason the store has two.
    /// - BOTH copies unreadable, or the store missing entirely: the map loads
    ///   EMPTY and the floor reads zero.
    ///
    /// The second row is a real limit, and this test states it rather than
    /// hiding it. A floor of zero asserts no minimum, so it can never turn a
    /// healthy partition into a reported truncation — the failure direction is
    /// permissive. What it costs is the truncation detection itself: with the
    /// floor gone, a partition that also lost records reads as legitimately
    /// short.
    ///
    /// Closing that needs a durable high-water bound to the exact source, not
    /// a bigger floor. It is tracked as separate work and is a prerequisite
    /// before physical conversation-feed history may be deleted. Until it
    /// lands, a floor that agrees with a replay is not proof that nothing was
    /// lost from the end.
    #[tokio::test]
    async fn one_damaged_event_count_copy_survives_and_two_do_not() {
        for (label, damage_all) in [("one copy", false), ("both copies", true)] {
            let dir = std::env::temp_dir().join(format!(
                "polychrome-eventlog-count-damage-{}-{}",
                std::process::id(),
                label.replace(' ', "-")
            ));
            let _ = std::fs::remove_dir_all(&dir);
            let partition = "conv-count-damage".to_owned();

            let shutdown = CancellationToken::new();
            let host = EventLogHost::spawn(
                dir.clone(),
                shutdown.clone(),
                polyc_crypto::signing_role::JournalAttestationSigner::from_seed(25),
            )
            .expect("spawn host");
            host.append_batch(
                partition.clone(),
                vec![
                    Event::new("user_msg", b"one".to_vec()),
                    Event::new("output_msg", b"two".to_vec()),
                ],
            )
            .await
            .expect("seed");
            let committed = host
                .partition_event_count(partition.clone())
                .await
                .expect("count");
            assert!(committed >= 2, "the batch and its signed root are durable");
            drop(host);
            shutdown.cancel();

            // The checkpoint store's own blobs, not the journal's.
            let store = dir.join(format!("{partition}__eventcount_checkpoint"));
            let mut copies: Vec<std::path::PathBuf> = std::fs::read_dir(&store)
                .expect("checkpoint store directory")
                .map(|entry| entry.expect("directory entry").path())
                .filter(|path| path.is_file())
                .collect();
            copies.sort();
            assert_eq!(copies.len(), 2, "the metadata store keeps two copies");
            let damaged = if damage_all {
                &copies[..]
            } else {
                &copies[..1]
            };
            for copy in damaged {
                let file = std::fs::OpenOptions::new()
                    .write(true)
                    .open(copy)
                    .expect("open a checkpoint copy");
                file.set_len(0).expect("shorten below the header");
                file.sync_all().expect("make the truncation durable");
            }

            // Shorten the records too. Damaging the floor alone is invisible
            // while the journal still answers for itself; it is the two
            // together that show what the floor was buying.
            let shortened = shorten_backing_blobs(&dir, &partition, "_data", 0);
            assert!(shortened > 0, "the case must actually shorten a data blob");

            let shutdown = CancellationToken::new();
            let host = EventLogHost::spawn(
                dir.clone(),
                shutdown.clone(),
                polyc_crypto::signing_role::JournalAttestationSigner::from_seed(25),
            )
            .expect("respawn host");
            let outcome = host.replay_verified(partition.clone()).await;
            if damage_all {
                // The limit, stated. Both copies gone means no floor, and with
                // no floor the emptied journal reads as a conversation that
                // legitimately holds nothing.
                let events =
                    outcome.expect("with no floor left, nothing contradicts the emptied journal");
                assert!(
                    events.is_empty(),
                    "the records are gone; only the floor could have said so"
                );
            } else {
                // The rotation did its job: one surviving copy still names
                // what committed, and that is what catches the loss.
                match outcome {
                    Err(AppendError::Verify(super::VerifyError::TruncatedReplay {
                        expected,
                        actual,
                    })) => {
                        assert_eq!(expected, committed, "the surviving copy holds the floor");
                        assert_eq!(actual, 0);
                    }
                    other => {
                        panic!("one damaged copy must leave the floor readable, got {other:?}")
                    }
                }
            }

            drop(host);
            shutdown.cancel();
            let _ = std::fs::remove_dir_all(&dir);
        }
    }

    /// The offsets half fails closed inside Commonware, and stays that way
    /// through the host.
    ///
    /// Unlike the data blob above, a shortened offsets blob is REFUSED at the
    /// mount: Commonware will not open a journal whose offsets it cannot
    /// reconcile against the data. The host must carry that refusal out as an
    /// error rather than convert it into an empty history.
    #[tokio::test]
    async fn an_offsets_blob_below_the_runtime_header_refuses_rather_than_reading_empty() {
        for raw_len in 0..8u64 {
            let dir = std::env::temp_dir().join(format!(
                "polychrome-eventlog-partial-offsets-{}-{raw_len}",
                std::process::id()
            ));
            let _ = std::fs::remove_dir_all(&dir);
            let partition = "conv-partial-offsets".to_owned();

            let shutdown = CancellationToken::new();
            let host = EventLogHost::spawn(
                dir.clone(),
                shutdown.clone(),
                polyc_crypto::signing_role::JournalAttestationSigner::from_seed(24),
            )
            .expect("spawn host");
            host.append_batch(
                partition.clone(),
                vec![Event::new("user_msg", b"one".to_vec())],
            )
            .await
            .expect("seed");
            drop(host);
            shutdown.cancel();

            let shortened = shorten_backing_blobs(&dir, &partition, "_offsets-blobs", raw_len);
            assert!(
                shortened > 0,
                "the case must actually shorten an offsets blob"
            );

            let shutdown = CancellationToken::new();
            let host = EventLogHost::spawn(
                dir.clone(),
                shutdown.clone(),
                polyc_crypto::signing_role::JournalAttestationSigner::from_seed(24),
            )
            .expect("respawn host");
            let outcome = host.replay_verified(partition.clone()).await;
            assert!(
                outcome.is_err(),
                "a shortened offsets blob answered {outcome:?}; an empty history over storage \
                 Commonware cannot reconcile is the one answer this must never give"
            );

            drop(host);
            shutdown.cancel();
            let _ = std::fs::remove_dir_all(&dir);
        }
    }

    /// A mandatory checkpoint mutation that fails inside Commonware leaves no
    /// resident handle, and the next attempt reopens from durable storage.
    ///
    /// The fault is a real one: the deterministic runtime fails every storage
    /// `sync`, so the error comes out of `Metadata::sync` rather than out of a
    /// seam that returned before Commonware wrote anything. Commonware's rule
    /// is that such an instance is unrecoverable, and this is the eviction
    /// that honours it.
    #[test]
    fn a_failed_checkpoint_sync_evicts_the_handle_and_the_next_attempt_reopens() {
        use commonware_runtime::{Runner as _, deterministic, deterministic::FaultConfig};

        let executor = deterministic::Runner::default();
        executor.start(|context| async move {
            let partition = "conv-poisoned-floor";
            let mut count_checkpoints = super::CountCheckpoints::new();
            count_checkpoints
                .record(&context, partition, 5)
                .await
                .unwrap();
            assert!(
                count_checkpoints.contains(partition),
                "a successful mutation keeps a healthy handle resident"
            );

            *context.storage_fault_config().write() = FaultConfig::default().sync(1.0);
            let error = count_checkpoints
                .record(&context, partition, 9)
                .await
                .expect_err("the durable sync must fail");
            assert!(
                matches!(error, EventLogError::Checkpoint(_)),
                "expected a checkpoint storage error, got {error}"
            );
            assert!(
                !count_checkpoints.contains(partition),
                "a failed mutation must leave no handle for a later call to reuse"
            );

            *context.storage_fault_config().write() = FaultConfig::default();
            assert_eq!(
                count_checkpoints
                    .expected_count(&context, partition)
                    .await
                    .unwrap(),
                5,
                "the next attempt reopens from durable storage, so it reads the last count                  that actually synced rather than the one the failed instance held"
            );
        });
    }

    /// The best-effort floor record is best-effort about the FLOOR, never
    /// about the handle.
    ///
    /// `record_event_count_floor` swallows its failure so an already-durable
    /// append batch keeps its receipt. It must still evict: a swallowed error
    /// that left the poisoned instance resident would have every later commit
    /// on this partition write through a store Commonware stopped vouching
    /// for.
    #[test]
    fn a_best_effort_floor_failure_still_evicts_the_handle() {
        use commonware_runtime::{Runner as _, deterministic, deterministic::FaultConfig};

        let executor = deterministic::Runner::default();
        executor.start(|context| async move {
            let partition = "conv-best-effort-floor";
            let mut count_checkpoints = super::CountCheckpoints::new();
            count_checkpoints
                .record(&context, partition, 3)
                .await
                .unwrap();

            *context.storage_fault_config().write() = FaultConfig::default().sync(1.0);
            // Returns `()`: the failure is logged, not propagated.
            super::record_event_count_floor(&context, &mut count_checkpoints, partition, 8).await;
            assert!(
                !count_checkpoints.contains(partition),
                "the swallowed failure still evicts the handle"
            );

            *context.storage_fault_config().write() = FaultConfig::default();
            assert_eq!(
                count_checkpoints
                    .expected_count(&context, partition)
                    .await
                    .unwrap(),
                3,
                "the floor stays at its last durable value"
            );
        });
    }

    /// One-shot fault-injection seam for `append_batch_one`'s per-event
    /// append (`#1712`). Keyed by partition name, so tests never interfere
    /// with each other even if `cargo-nextest`'s per-test process isolation
    /// were ever off; consumed on first match so a later, valid append to the
    /// same partition never gets re-armed by accident.
    ///
    /// This exists because there is no portable, root-safe way to make a
    /// genuinely real commonware-storage operation fail on an
    /// ALREADY-OPEN, already-cached journal handle from outside the storage
    /// backend: `append_batch_surfaces_error_when_storage_dir_is_unwritable`'s
    /// structural-conflict trick only works because it blocks the partition's
    /// directory from ever being CREATED in the first place, so the handle
    /// never gets cached at all — exactly the case that can't reproduce
    /// `#1712`'s hazard (a failure on a handle that is *already* open and
    /// cached). This hook instead substitutes a real
    /// [`super::EventLogError`] for the outcome of one specific
    /// `EventLog::append`/`EventLog::commit` call, so the rest of
    /// `append_batch_one` runs its genuine error-handling path.
    static ARMED_APPEND_FAILURES: OnceLock<Mutex<HashMap<String, usize>>> = OnceLock::new();

    /// Sibling of [`ARMED_APPEND_FAILURES`] for `append_batch_one`'s FINAL
    /// `commit()` call instead of a per-event append.
    static ARMED_COMMIT_FAILURES: OnceLock<Mutex<HashSet<String>>> = OnceLock::new();

    static ARMED_MMR_PREPARATION_FAILURES: OnceLock<Mutex<HashSet<String>>> = OnceLock::new();

    /// One-shot deterministic pause at the start of a partition replay. It
    /// proves cross-partition scheduling without comparing wall-clock timings
    /// under an arbitrarily loaded test runner.
    #[derive(Clone)]
    pub(crate) struct ReplayPause {
        pub(crate) entered: Arc<tokio::sync::Notify>,
        pub(crate) release: Arc<tokio::sync::Notify>,
    }

    static ARMED_REPLAY_PAUSES: OnceLock<Mutex<HashMap<String, ReplayPause>>> = OnceLock::new();

    #[test]
    fn exact_rewrite_fingerprints_bind_lineage_payload_and_deterministic_root() {
        let signer = polyc_crypto::signing_role::JournalAttestationSigner::from_seed(91);
        let events = vec![
            Event::new("__state_journal_incarnation__", vec![1; 33]),
            Event::new("record", vec![2, 3]),
        ];
        let decision = |event: &Event| {
            if event.kind == "__state_journal_incarnation__" {
                RewriteDecision::Replace(vec![9; 33])
            } else if event.kind == "record" {
                RewriteDecision::Replace(vec![4, 5])
            } else {
                RewriteDecision::Keep
            }
        };
        let (first, restored, _) =
            super::inspect_exact_rewrite("conv", "excise", &events, &signer, &decision)
                .expect("plan");
        let (retry, retry_restored, _) =
            super::inspect_exact_rewrite("conv", "excise", &events, &signer, &decision)
                .expect("retry plan");
        assert_eq!(first, retry, "the same signed result is deterministic");
        assert_eq!(restored, retry_restored);

        let changed_payload = |event: &Event| {
            if event.kind == "__state_journal_incarnation__" {
                RewriteDecision::Replace(vec![9; 33])
            } else if event.kind == "record" {
                RewriteDecision::Replace(vec![4, 6])
            } else {
                RewriteDecision::Keep
            }
        };
        let (payload_plan, _, _) =
            super::inspect_exact_rewrite("conv", "excise", &events, &signer, &changed_payload)
                .expect("changed payload plan");
        assert_ne!(first.after, payload_plan.after);
        assert_ne!(first.stage_binding, payload_plan.stage_binding);

        let changed_lineage = |event: &Event| {
            if event.kind == "__state_journal_incarnation__" {
                RewriteDecision::Replace(vec![8; 33])
            } else if event.kind == "record" {
                RewriteDecision::Replace(vec![4, 5])
            } else {
                RewriteDecision::Keep
            }
        };
        let (lineage_plan, _, _) =
            super::inspect_exact_rewrite("conv", "excise", &events, &signer, &changed_lineage)
                .expect("changed lineage plan");
        assert_ne!(first.after, lineage_plan.after);
        assert_ne!(first.stage_binding, lineage_plan.stage_binding);
    }

    #[test]
    fn root_append_fault_arms_are_counted_per_partition() {
        let partition = "root-fault-count";
        arm_root_append_failure(partition);
        arm_root_append_failure(partition);
        assert!(super::take_armed_root_append_failure(partition).is_some());
        assert!(super::take_armed_root_append_failure(partition).is_some());
        assert!(super::take_armed_root_append_failure(partition).is_none());
    }

    fn arm_replay_pause(partition: &str) -> ReplayPause {
        let pause = ReplayPause {
            entered: Arc::new(tokio::sync::Notify::new()),
            release: Arc::new(tokio::sync::Notify::new()),
        };
        ARMED_REPLAY_PAUSES
            .get_or_init(|| Mutex::new(HashMap::new()))
            .lock()
            .expect("lock poisoned")
            .insert(partition.to_owned(), pause.clone());
        pause
    }

    pub(crate) fn take_replay_pause(partition: &str) -> Option<ReplayPause> {
        ARMED_REPLAY_PAUSES
            .get_or_init(|| Mutex::new(HashMap::new()))
            .lock()
            .expect("lock poisoned")
            .remove(partition)
    }

    /// Synthesize the error an armed injection reports — a real,
    /// legitimately-constructible [`commonware_storage::journal::Error`]
    /// variant (not a fabricated type), wrapped exactly as a genuine journal
    /// failure would be.
    fn injected_error() -> EventLogError {
        EventLogError::Journal(commonware_storage::journal::Error::Corruption(
            "injected test failure (#1712 fault-injection seam)".to_owned(),
        ))
    }

    /// Arm `partition`'s NEXT `append_batch` call so its event at
    /// `event_index` (0-based within that one batch) fails as if the
    /// underlying journal append itself had.
    pub(crate) fn arm_append_failure(partition: &str, event_index: usize) {
        ARMED_APPEND_FAILURES
            .get_or_init(|| Mutex::new(HashMap::new()))
            .lock()
            .expect("lock poisoned")
            .insert(partition.to_owned(), event_index);
    }

    /// Consumed by `append_batch_one`'s per-event append loop: if
    /// `partition`'s armed index matches `event_index`, disarms it and
    /// returns the synthetic error; otherwise `None` (the real append runs
    /// unmodified).
    pub(crate) fn take_armed_append_failure(
        partition: &str,
        event_index: usize,
    ) -> Option<EventLogError> {
        let lock = ARMED_APPEND_FAILURES.get()?;
        let matched = {
            let mut armed = lock.lock().expect("lock poisoned");
            if armed.get(partition) == Some(&event_index) {
                armed.remove(partition);
                true
            } else {
                false
            }
        };
        matched.then(injected_error)
    }

    /// Arm `partition`'s NEXT `append_batch` call so its FINAL commit fails
    /// as if the underlying journal commit itself had.
    pub(crate) fn arm_commit_failure(partition: &str) {
        ARMED_COMMIT_FAILURES
            .get_or_init(|| Mutex::new(HashSet::new()))
            .lock()
            .expect("lock poisoned")
            .insert(partition.to_owned());
    }

    /// Consumed by `append_batch_one`'s final commit: if `partition` is
    /// armed, disarms it and returns the synthetic error; otherwise `None`
    /// (the real commit runs unmodified).
    pub(crate) fn take_armed_commit_failure(partition: &str) -> Option<EventLogError> {
        let lock = ARMED_COMMIT_FAILURES.get()?;
        let matched = lock.lock().expect("lock poisoned").remove(partition);
        matched.then(injected_error)
    }

    /// Sibling of [`ARMED_COMMIT_FAILURES`] for `restore_rewrite`'s terminal
    /// event-count record (`#2567`).
    static ARMED_COUNT_RECORD_FAILURES: OnceLock<Mutex<HashSet<String>>> = OnceLock::new();

    /// Arm `partition`'s NEXT `restore_rewrite` so its terminal event-count
    /// record fails as if the durable sync itself had.
    pub(crate) fn arm_count_record_failure(partition: &str) {
        ARMED_COUNT_RECORD_FAILURES
            .get_or_init(|| Mutex::new(HashSet::new()))
            .lock()
            .expect("lock poisoned")
            .insert(partition.to_owned());
    }

    /// Take `partition`'s armed terminal count-record failure, if one is set.
    pub(crate) fn take_armed_count_record_failure(partition: &str) -> Option<EventLogError> {
        let lock = ARMED_COUNT_RECORD_FAILURES.get()?;
        let matched = lock.lock().expect("lock poisoned").remove(partition);
        matched.then(injected_error)
    }

    fn arm_mmr_preparation_failure(partition: &str) {
        ARMED_MMR_PREPARATION_FAILURES
            .get_or_init(|| Mutex::new(HashSet::new()))
            .lock()
            .expect("lock poisoned")
            .insert(partition.to_owned());
    }

    pub(crate) fn take_armed_mmr_preparation_failure(partition: &str) -> Option<EventLogError> {
        let lock = ARMED_MMR_PREPARATION_FAILURES.get()?;
        let matched = lock.lock().expect("lock poisoned").remove(partition);
        matched.then(injected_error)
    }

    /// Sibling of [`ARMED_COMMIT_FAILURES`] for `destroy_one`'s
    /// reset-then-reclaim (`#1742`).
    static ARMED_DESTROY_FAILURES: OnceLock<Mutex<HashSet<String>>> = OnceLock::new();

    /// Arm `partition`'s NEXT `destroy_one` call so its destruction fails as
    /// if the underlying storage reset itself had.
    pub(crate) fn arm_destroy_failure(partition: &str) {
        ARMED_DESTROY_FAILURES
            .get_or_init(|| Mutex::new(HashSet::new()))
            .lock()
            .expect("lock poisoned")
            .insert(partition.to_owned());
    }

    /// Consumed by `destroy_one`: if `partition` is armed, disarms it and
    /// returns the synthetic error; otherwise `None` (the real destroy runs
    /// unmodified).
    pub(crate) fn take_armed_destroy_failure(partition: &str) -> Option<EventLogError> {
        let lock = ARMED_DESTROY_FAILURES.get()?;
        let matched = lock.lock().expect("lock poisoned").remove(partition);
        matched.then(injected_error)
    }

    /// Issue #1541's early-abort primitive, through the real actor/oneshot-
    /// channel plumbing (not just `polyc_eventlog::EventLog`'s own unit
    /// test): a partition with 10,000 bytes of payload, replayed with a
    /// 3,500 byte budget, comes back truncated — `budget_exceeded` is
    /// `true` and fewer than all 10 events are returned — proving the
    /// `Command::ReplayWithPositionsBounded` round trip doesn't quietly
    /// materialize the whole partition before handing back the result.
    #[tokio::test]
    async fn replay_with_positions_bounded_stops_early_through_the_host() {
        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-bounded-host-{}",
            std::process::id()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let shutdown = CancellationToken::new();
        let host = EventLogHost::spawn(
            dir.clone(),
            shutdown.clone(),
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
        )
        .expect("spawn host");

        let events: Vec<Event> = (0..10)
            .map(|i| Event::new(format!("k{i}"), vec![0u8; 1_000]))
            .collect();
        host.append_batch("conv-bounded-host".to_owned(), events)
            .await
            .expect("seed");

        let bounded = host
            .replay_with_positions_bounded("conv-bounded-host".to_owned(), 3_500)
            .await
            .expect("bounded replay");

        assert!(
            bounded.budget_exceeded,
            "a 3,500 byte budget over 10,000 bytes of payload must trip"
        );
        assert!(
            bounded.events.len() < 10,
            "the host must not hand back every event once the budget trips: got {}",
            bounded.events.len()
        );
        assert_eq!(
            bounded.events.len(),
            4,
            "stops right after the 4th 1,000-byte event"
        );

        // The unbounded twin still returns everything — the new command
        // does not change existing behavior. (Not asserted as exactly 10:
        // `append_batch` also appends its own MMR signed-root marker event
        // (#799) after the 10 real ones, so the true partition length is
        // 11 — the bounded call above stops well before even reaching
        // that marker.)
        let unbounded = host
            .replay_with_positions("conv-bounded-host".to_owned())
            .await
            .expect("unbounded replay");
        assert!(
            bounded.events.len() < unbounded.len(),
            "the bounded replay must return strictly fewer events than the unbounded one: \
             bounded={} unbounded={}",
            bounded.events.len(),
            unbounded.len()
        );

        drop(host);
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// [`EventLogHost::replay_range_with_positions_bounded`]'s own proof,
    /// through the real actor/oneshot-channel plumbing: the upper bound
    /// survives the command round trip, the end stays exclusive, and the byte
    /// budget still applies within the range.
    ///
    /// The end-exclusion half is what a caller fetching one indexed span
    /// depends on; an inclusive end would leak the next span's first event
    /// into every read, and that is not the kind of bug a fetch surfaces
    /// loudly.
    #[tokio::test]
    async fn replay_range_with_positions_bounded_through_the_host() {
        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-range-bounded-host-{}",
            std::process::id()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let shutdown = CancellationToken::new();
        let host = EventLogHost::spawn(
            dir.clone(),
            shutdown.clone(),
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
        )
        .expect("spawn host");

        let events: Vec<Event> = (0..10)
            .map(|i| Event::new(format!("k{i}"), vec![0u8; 1_000]))
            .collect();
        host.append_batch("conv-range-bounded-host".to_owned(), events)
            .await
            .expect("seed");

        // The range, not the budget, stops this one.
        let ranged = host
            .replay_range_with_positions_bounded(
                "conv-range-bounded-host".to_owned(),
                3,
                6,
                u64::MAX,
            )
            .await
            .expect("range replay");
        let positions: Vec<u64> = ranged.events.iter().map(|(p, _)| *p).collect();
        assert_eq!(
            positions,
            vec![3, 4, 5],
            "[3, 6) is 3, 4, 5 — position 6 is outside the range"
        );
        assert!(
            !ranged.budget_exceeded,
            "a complete range must not report itself truncated"
        );
        assert_eq!(ranged.bytes_read, 3_000);

        // The budget still bites inside a range, and says so.
        let capped = host
            .replay_range_with_positions_bounded("conv-range-bounded-host".to_owned(), 2, 9, 2_500)
            .await
            .expect("range replay under a budget");
        assert!(capped.budget_exceeded);
        let capped_positions: Vec<u64> = capped.events.iter().map(|(p, _)| *p).collect();
        assert_eq!(capped_positions, vec![2, 3, 4]);

        // An end past the tail clamps; an empty range is empty, not an error.
        let clamped = host
            .replay_range_with_positions_bounded(
                "conv-range-bounded-host".to_owned(),
                8,
                9_999,
                u64::MAX,
            )
            .await
            .expect("range replay past the tail");
        let clamped_positions: Vec<u64> = clamped.events.iter().map(|(p, _)| *p).collect();
        assert_eq!(
            clamped_positions,
            vec![8, 9, 10],
            "clamped to the REAL tail, which is 11 events rather than the 10 seeded: \
             `append_batch` also writes the host's own per-commit `__mmr_signed_root__` \
             tamper-evidence marker at position 10. A range clamp has to land on what the \
             journal actually holds, not on what the caller appended"
        );

        let empty = host
            .replay_range_with_positions_bounded("conv-range-bounded-host".to_owned(), 5, 5, 1)
            .await
            .expect("empty range");
        assert!(empty.events.is_empty());
        assert!(!empty.budget_exceeded);

        drop(host);
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// [`EventLogHost::replay_from_with_positions_bounded`]'s own proof,
    /// through the real actor/oneshot-channel plumbing: it honors BOTH a
    /// resume position AND a byte budget in the same call. Ten 1,000-byte
    /// events; resuming at position 4 (skipping the first four) under a
    /// 2,500-byte budget must stop after the third event it actually reads
    /// (positions 4, 5, 6 — 3,000 bytes tips it over after the third),
    /// never reaching position 7, and never re-reading positions 0..4 —
    /// proving the combined command does not fall back to materializing the
    /// whole tail before checking the budget.
    #[tokio::test]
    async fn replay_from_with_positions_bounded_honors_both_through_the_host() {
        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-tail-bounded-host-{}",
            std::process::id()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let shutdown = CancellationToken::new();
        let host = EventLogHost::spawn(
            dir.clone(),
            shutdown.clone(),
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
        )
        .expect("spawn host");

        let events: Vec<Event> = (0..10)
            .map(|i| Event::new(format!("k{i}"), vec![0u8; 1_000]))
            .collect();
        host.append_batch("conv-tail-bounded-host".to_owned(), events)
            .await
            .expect("seed");

        let bounded = host
            .replay_from_with_positions_bounded("conv-tail-bounded-host".to_owned(), 4, 2_500)
            .await
            .expect("bounded tail replay");

        assert!(
            bounded.budget_exceeded,
            "a 2,500 byte budget over the 6,000-byte tail (positions 4..10) must trip"
        );
        let positions: Vec<u64> = bounded.events.iter().map(|(p, _)| *p).collect();
        assert_eq!(
            positions,
            vec![4, 5, 6],
            "must resume at position 4 (never re-reading 0..4) and stop the instant \
             cumulative bytes (3,000 after the 3rd tail event) cross the 2,500 budget"
        );
        assert_eq!(bounded.bytes_read, 3_000);

        // A `start` past the partition's real end is empty, never an error
        // and never a spurious `budget_exceeded` — the same rule
        // `replay_from_with_positions` already honors.
        let past_end = host
            .replay_from_with_positions_bounded("conv-tail-bounded-host".to_owned(), 999, 1)
            .await
            .expect("bounded tail replay past the end");
        assert!(past_end.events.is_empty());
        assert!(!past_end.budget_exceeded);

        drop(host);
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// Partition enumeration through the real storage stack (#490): appended
    /// partitions list by their LOGICAL names, a destroyed partition drops
    /// off the list, and a fresh host lists nothing. This test also pins the
    /// engine's on-disk `{name}_data` layout that `list_partitions_in` peels
    /// — an engine upgrade that changes it fails here, loudly.
    #[tokio::test]
    async fn list_partitions_returns_logical_names_and_tracks_destroy() {
        let dir =
            std::env::temp_dir().join(format!("polychrome-eventlog-list-{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        let shutdown = CancellationToken::new();
        let host = EventLogHost::spawn(
            dir.clone(),
            shutdown.clone(),
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
        )
        .expect("spawn host");

        assert!(
            host.list_partitions().await.expect("list empty").is_empty(),
            "a fresh host has no partitions"
        );

        for partition in ["conv-c1", "persona-p1-mem", "erasure-audit"] {
            host.append_batch(
                partition.to_owned(),
                vec![Event::new("output_msg", b"x".to_vec())],
            )
            .await
            .expect("seed");
        }
        assert_eq!(
            host.list_partitions().await.expect("list"),
            vec!["conv-c1", "erasure-audit", "persona-p1-mem"],
            "logical names, sorted — no storage-layout suffixes"
        );
        assert!(matches!(
            host.list_partitions_bounded(2, usize::MAX).await,
            Err(AppendError::Listing(ListPartitionsError::EntriesExceeded {
                limit: 2,
                requested: 3,
            }))
        ));
        assert!(matches!(
            host.list_partitions_bounded(3, "conv-c1".len()).await,
            Err(AppendError::Listing(
                ListPartitionsError::NameBytesExceeded { .. }
            ))
        ));

        host.destroy_partition("persona-p1-mem".to_owned())
            .await
            .expect("destroy");
        assert_eq!(
            host.list_partitions().await.expect("list after destroy"),
            vec!["conv-c1", "erasure-audit"],
            "a destroyed partition no longer lists"
        );

        drop(host);
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn a_corrupt_partition_shaped_entry_refuses_the_whole_listing() {
        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-corrupt-list-{}",
            std::process::id()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(dir.join("good_data")).expect("valid partition directory");
        // `_61` decodes to `a`, but `a` is its only canonical encoding.
        std::fs::create_dir_all(dir.join("_61_data")).expect("corrupt partition directory");

        assert!(matches!(
            crate::list_partitions_bounded_in(&dir, usize::MAX, usize::MAX, None),
            Err(ListPartitionsError::Corrupt { entry }) if entry == "_61_data"
        ));
    }

    /// `#2653`: a retry after a failed MARKER append still re-roots.
    ///
    /// The marker is the last element written. If the append fails on exactly
    /// that element, the best-effort commit makes every migrated event
    /// durable and no root covers them. The caller retries, dedup finds
    /// everything already present, and a naive "nothing new, nothing to do"
    /// would then let the source be destroyed while the destination holds
    /// migrated content that nothing attests.
    ///
    /// `replay_verified` cannot catch that: an unattested tail verifies
    /// trivially. So this asserts the root directly.
    #[test]
    fn a_retry_after_a_failed_marker_append_still_re_roots() {
        use commonware_runtime::{Runner as _, tokio as cw_tokio};

        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-marker-retry-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let to = "conv-marker-retry-to".to_owned();
        let from = "conv-marker-retry-from".to_owned();
        let to_ref = super::PartitionRef::new(&to).expect("the name encodes");
        let from_ref = super::PartitionRef::new(&from).expect("the name encodes");

        let runner =
            cw_tokio::Runner::new(cw_tokio::Config::default().with_storage_directory(dir.clone()));
        runner.start(move |context| async move {
            let mut logs = super::OpenLogs::new();
            let mut count_checkpoints = super::CountCheckpoints::new();
            let mut mmr_logs = HashMap::new();
            let write_observers = super::observer::WriteObservers::new();
            let signer = polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1);
            let candidates = [
                Event::new("memory_added", b"one".to_vec()),
                Event::new("memory_added", b"two".to_vec()),
            ];

            // Index 2 is the marker: two candidates, then the minted root.
            arm_append_failure(&to, 2);
            super::migrate_append_into(
                &context,
                &mut logs,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &to_ref,
                &candidates,
                &write_observers,
                &from_ref,
            )
            .await
            .expect_err("the armed marker append fails the first attempt");

            // The retry: every candidate is already durable, so dedup finds
            // nothing new. It must still re-root.
            let appended = super::migrate_append_into(
                &context,
                &mut logs,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &to_ref,
                &candidates,
                &write_observers,
                &from_ref,
            )
            .await
            .expect("the retry succeeds");
            assert_eq!(appended, 0, "nothing new moved on the retry");

            let log = logs.get_or_open(&context, &to).await.expect("reopen");
            let replayed = log.replay().await.expect("replay");
            assert!(
                replayed
                    .iter()
                    .any(|ev| ev.kind == polyc_eventlog::MMR_SIGNED_ROOT_KIND),
                "the retry must leave a signed root over the migrated events"
            );
            assert_eq!(
                replayed.last().map(|ev| ev.kind.as_str()),
                Some(polyc_eventlog::MMR_SIGNED_ROOT_KIND),
                "and it must cover everything, so it is last"
            );
        });

        let _ = std::fs::remove_dir_all(&dir);
    }

    /// `#2653`: the same retry, into a destination that already holds a root.
    ///
    /// The sibling test above starts from an EMPTY destination, so the
    /// partition never holds a root of its own and the re-root only has to
    /// cover migrated events. This is the shape the issue actually names: the
    /// destination already holds `[seed, R0]`, so the attested tail flips
    /// true, then false when the marker append fails, then true again on the
    /// retry.
    ///
    /// It also pins what a re-root must NOT break. `R0` commits to one leaf.
    /// The retry mints `R1` over three. Both must still verify in the same
    /// replay, which is what `verify_replay_with_trust` walks marker by
    /// marker.
    #[test]
    fn a_retry_re_roots_a_destination_that_already_holds_a_root() {
        use commonware_runtime::{Runner as _, tokio as cw_tokio};

        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-marker-retry-nonempty-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let to = "conv-marker-retry-nonempty-to".to_owned();
        let from = "conv-marker-retry-nonempty-from".to_owned();
        let to_ref = super::PartitionRef::new(&to).expect("the name encodes");
        let from_ref = super::PartitionRef::new(&from).expect("the name encodes");

        let runner =
            cw_tokio::Runner::new(cw_tokio::Config::default().with_storage_directory(dir.clone()));
        runner.start(move |context| async move {
            let mut logs = super::OpenLogs::new();
            let mut count_checkpoints = super::CountCheckpoints::new();
            let mut mmr_logs = HashMap::new();
            let write_observers = super::observer::WriteObservers::new();
            let signer = polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1);
            let seed = [Event::new("memory_added", b"seed".to_vec())];
            let candidates = [
                Event::new("memory_added", b"one".to_vec()),
                Event::new("memory_added", b"two".to_vec()),
            ];

            // Give the destination a root of its own first: `[seed, R0]`.
            super::migrate_append_into(
                &context,
                &mut logs,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &to_ref,
                &seed,
                &write_observers,
                &from_ref,
            )
            .await
            .expect("the seeding migration succeeds");

            // Armed only now, so the seeding migration's own marker (at index
            // 1 of a two-element write) cannot consume the arm.
            arm_append_failure(&to, 2);
            super::migrate_append_into(
                &context,
                &mut logs,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &to_ref,
                &candidates,
                &write_observers,
                &from_ref,
            )
            .await
            .expect_err("the armed marker append fails the first attempt");

            let log = logs.get_or_open(&context, &to).await.expect("reopen");
            let mid = log.replay().await.expect("replay");
            assert_eq!(
                mid.last().map(|ev| ev.kind.as_str()),
                Some("memory_added"),
                "the failed attempt must leave the tail unattested, or this \
                 test proves nothing about the retry"
            );

            let appended = super::migrate_append_into(
                &context,
                &mut logs,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &to_ref,
                &candidates,
                &write_observers,
                &from_ref,
            )
            .await
            .expect("the retry succeeds");
            assert_eq!(appended, 0, "nothing new moved on the retry");

            let log = logs.get_or_open(&context, &to).await.expect("reopen");
            let replayed = log.replay().await.expect("replay");
            assert_eq!(
                replayed.last().map(|ev| ev.kind.as_str()),
                Some(polyc_eventlog::MMR_SIGNED_ROOT_KIND),
                "the retry must re-root, and the root must be last"
            );
            assert_eq!(
                replayed
                    .iter()
                    .filter(|ev| ev.kind == polyc_eventlog::MMR_SIGNED_ROOT_KIND)
                    .count(),
                2,
                "the destination's own root survives the re-root"
            );
            let trust = polyc_crypto::signing_role::RoleTrustSet::current(&signer);
            polyc_eventlog::verify_replay_with_trust(&replayed, &trust)
                .expect("both roots verify: R0 over one leaf, R1 over three");
        });

        let _ = std::fs::remove_dir_all(&dir);
    }

    /// `#2653`: this fix is forward-only, and an append cannot repair a
    /// partition an earlier migration already poisoned.
    ///
    /// A review round proposed strengthening the tail check: require the tail
    /// root's leaf count to equal the leaves present, not just the tail's
    /// kind. That detects this partition. It repairs nothing, which is why
    /// the check stayed on the kind. The bad root is already durable, and
    /// `verify_replay` checks EVERY marker it walks, so a correct root
    /// appended after a wrong one still leaves the replay failing at the
    /// wrong one. `migrate_one` destroys the source in both designs, so the
    /// stronger check does not even save the source.
    ///
    /// This test exists to keep that measured, not argued. Repair belongs to
    /// `rewrite_one`, which can drop the bad marker; an append cannot.
    #[test]
    fn a_re_root_cannot_repair_a_root_that_covers_the_wrong_leaves() {
        use commonware_runtime::{Runner as _, tokio as cw_tokio};

        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-foreign-root-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let to = "conv-foreign-root-to".to_owned();
        let from = "conv-foreign-root-from".to_owned();
        let to_ref = super::PartitionRef::new(&to).expect("the name encodes");
        let from_ref = super::PartitionRef::new(&from).expect("the name encodes");

        let runner =
            cw_tokio::Runner::new(cw_tokio::Config::default().with_storage_directory(dir.clone()));
        runner.start(move |context| async move {
            let mut logs = super::OpenLogs::new();
            let mut count_checkpoints = super::CountCheckpoints::new();
            let mut mmr_logs = HashMap::new();
            let write_observers = super::observer::WriteObservers::new();
            let signer = polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1);
            let carried = [
                Event::new("memory_added", b"one".to_vec()),
                Event::new("memory_added", b"two".to_vec()),
                Event::new("memory_added", b"three".to_vec()),
            ];

            // Build the poisoned shape by hand: three events, then a root that
            // covers only the first. This is what the pre-fix migration
            // produced when it carried the source's own root across.
            {
                let log = logs.get_or_open(&context, &to).await.expect("open");
                for event in &carried {
                    log.append(event).await.expect("append");
                }
                let short = polyc_eventlog::rebuild_from_events(&carried[..1]).expect("rebuild");
                let foreign = polyc_eventlog::extend_and_sign(&short, &[], &signer).expect("sign");
                log.append(&foreign).await.expect("append the foreign root");
                log.commit().await.expect("commit");
            }
            let trust = polyc_crypto::signing_role::RoleTrustSet::current(&signer);
            {
                let log = logs.get_or_open(&context, &to).await.expect("reopen");
                let poisoned = log.replay().await.expect("replay");
                assert_eq!(
                    poisoned.last().map(|ev| ev.kind.as_str()),
                    Some(polyc_eventlog::MMR_SIGNED_ROOT_KIND),
                    "the setup must end in a marker, or it does not model the case"
                );
                assert!(
                    polyc_eventlog::verify_replay_with_trust(&poisoned, &trust).is_err(),
                    "the setup must actually be poisoned, or this test proves nothing"
                );
            }

            // Every candidate is already present, so dedup finds nothing new,
            // and the tail IS a marker. The migration takes the early return.
            let appended = super::migrate_append_into(
                &context,
                &mut logs,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &to_ref,
                &carried,
                &write_observers,
                &from_ref,
            )
            .await
            .expect("the migration succeeds");
            assert_eq!(appended, 0, "nothing new moved");

            let log = logs.get_or_open(&context, &to).await.expect("reopen");
            let replayed = log.replay().await.expect("replay");
            let still_broken = polyc_eventlog::verify_replay_with_trust(&replayed, &trust)
                .expect_err("a poisoned partition stays poisoned; this fix is forward-only");
            assert!(
                matches!(
                    still_broken,
                    polyc_eventlog::IntegrityError::RootMismatch { leaf_count: 3, .. }
                ),
                "it must fail on the bad root it already holds, over the three \
                 leaves present, not on something new: {still_broken:?}"
            );
        });

        let _ = std::fs::remove_dir_all(&dir);
    }

    /// `#2653`: a concurrent append cannot poison the migrated destination.
    ///
    /// The first fix for this issue read the destination in one round trip and
    /// appended in another. The destination's worker services other commands
    /// between the two, so an `AppendBatch` landing in that window shifted
    /// every later leaf position, and the root minted against the earlier read
    /// described content the destination did not have. That is the same
    /// unrepairable mismatch a carried root produces — minted here rather than
    /// imported, which is worse, because the fix caused it.
    ///
    /// Read, dedup, re-root, and append now happen in ONE command on the
    /// destination's own worker, so nothing can interleave.
    ///
    /// The source is large so the migration takes long enough for the
    /// concurrent append to land inside the old window. On the pre-fix code
    /// this failed at every delay from 5 ms to 40 ms.
    #[tokio::test(flavor = "multi_thread", worker_threads = 4)]
    async fn a_concurrent_append_cannot_poison_a_migration() {
        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-migrate-race-{}",
            std::process::id()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let shutdown = CancellationToken::new();
        let host = std::sync::Arc::new(
            EventLogHost::spawn(
                dir.clone(),
                shutdown.clone(),
                polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
            )
            .expect("spawn host"),
        );

        host.append_batch(
            "conv-race-dest".to_owned(),
            vec![Event::new("output_msg", b"dest-one".to_vec())],
        )
        .await
        .expect("seed destination");

        let bulk: Vec<Event> = (0..2000)
            .map(|i| Event::new("output_msg", format!("src-{i}").into_bytes()))
            .collect();
        host.append_batch("conv-race-source".to_owned(), bulk)
            .await
            .expect("seed source");

        let racer = {
            let host = std::sync::Arc::clone(&host);
            tokio::spawn(async move {
                tokio::time::sleep(std::time::Duration::from_millis(10)).await;
                host.append_batch(
                    "conv-race-dest".to_owned(),
                    vec![Event::new("output_msg", b"concurrent".to_vec())],
                )
                .await
            })
        };

        host.migrate_partition("conv-race-source".to_owned(), "conv-race-dest".to_owned())
            .await
            .expect("migrate");
        racer
            .await
            .expect("the racing task ran")
            .expect("racing append");

        // The destination must verify no matter which order the two landed in.
        host.replay_verified("conv-race-dest".to_owned())
            .await
            .expect("a concurrent append must not poison the destination");

        shutdown.cancel();
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// `#2653`: a migration re-roots its destination, and carries no root in.
    ///
    /// The source's signed roots commit to a leaf sequence at the SOURCE's
    /// positions — `polyc_mmr::leaf_digest` takes the position — so the same
    /// events landing at different positions in the destination can never
    /// reproduce them. Carrying one in leaves the destination reporting tamper
    /// on a log nobody tampered with, and a verification pass finds nothing to
    /// quarantine, so a repair cannot fix it either.
    ///
    /// The destination is seeded NON-EMPTY on purpose. That is the case the
    /// issue names, and the one an empty-destination test would miss: the
    /// carried root then describes a prefix that no longer matches the tree it
    /// lands in.
    #[tokio::test]
    async fn a_migrated_partition_verifies_at_its_destination() {
        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-migrate-reroot-{}",
            std::process::id()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let shutdown = CancellationToken::new();
        let host = EventLogHost::spawn(
            dir.clone(),
            shutdown.clone(),
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
        )
        .expect("spawn host");

        // Both partitions complete a turn, so each carries a genuine signed
        // root rather than a hand-built stand-in.
        host.append_batch(
            "conv-migrate-source".to_owned(),
            vec![Event::new("output_msg", b"source-one".to_vec())],
        )
        .await
        .expect("seed source");
        host.append_batch(
            "conv-migrate-dest".to_owned(),
            vec![Event::new("output_msg", b"dest-one".to_vec())],
        )
        .await
        .expect("seed destination");

        host.replay_verified("conv-migrate-dest".to_owned())
            .await
            .expect("the destination verifies before the migration");

        host.migrate_partition(
            "conv-migrate-source".to_owned(),
            "conv-migrate-dest".to_owned(),
        )
        .await
        .expect("migrate");

        // The whole point. Before `#2653` this failed with a `RootMismatch`
        // naming the expected and the computed root.
        let verified = host
            .replay_verified("conv-migrate-dest".to_owned())
            .await
            .expect("the destination must still verify after the migration");

        let payloads: Vec<&[u8]> = verified.iter().map(|ev| ev.payload.as_slice()).collect();
        assert!(
            payloads.contains(&b"source-one".as_slice()),
            "the migrated event must arrive"
        );
        assert!(
            payloads.contains(&b"dest-one".as_slice()),
            "the destination's own event must survive"
        );

        // Verifying is NOT enough on its own, and this is the half a
        // verification assertion cannot reach. An unattested tail verifies
        // trivially: the destination's own marker still covers its unchanged
        // prefix, and a migrated event sitting past it is simply not attested
        // by anything. So a migration that carried no root but also signed no
        // fresh one would pass the check above while leaving everything it
        // moved outside tamper evidence.
        //
        // Pin the root instead: the LAST event is a signed-root marker, so it
        // covers every migrated event before it.
        let last = verified.last().expect("the destination is not empty");
        assert_eq!(
            last.kind,
            polyc_eventlog::MMR_SIGNED_ROOT_KIND,
            "a migration must re-root its destination over what it now holds"
        );

        shutdown.cancel();
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// The atomic partition move: events land in the destination, the source
    /// is destroyed, and a RE-RUN against a re-created source holding the
    /// same events appends nothing (journal-level dedup) — the idempotence
    /// that makes migration retries and racing sweeps safe.
    #[tokio::test]
    #[allow(clippy::too_many_lines)]
    async fn migrate_partition_moves_dedups_and_destroys() {
        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-migrate-{}",
            std::process::id()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let shutdown = CancellationToken::new();
        let host = EventLogHost::spawn(
            dir.clone(),
            shutdown.clone(),
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
        )
        .expect("spawn host");

        let a = Event::new("memory_added", b"fact-a".to_vec());
        let b = Event::new("memory_added", b"fact-b".to_vec());
        let s = Event::new("memory_added", b"fact-s".to_vec());
        host.append_batch(
            "persona-absorbed-mem".to_owned(),
            vec![a.clone(), b.clone()],
        )
        .await
        .expect("seed source");
        host.append_batch("persona-survivor-mem".to_owned(), vec![s])
            .await
            .expect("seed destination");

        let outcome = host
            .migrate_partition(
                "persona-absorbed-mem".to_owned(),
                "persona-survivor-mem".to_owned(),
            )
            .await
            .expect("migrate");
        // 2, not 3 (`#2653`). Each `append_batch` also lands its own MMR
        // signed-root marker (#799), and this counts the events that MOVED.
        // The source's marker is not one of them: a root commits to a leaf
        // sequence at its own positions, so it cannot describe the same events
        // sitting at different positions here.
        assert_eq!(outcome, PartitionMigration::Migrated(2));
        assert_eq!(
            host.replay("persona-survivor-mem".to_owned())
                .await
                .expect("replay survivor")
                .len(),
            5,
            "survivor holds its own event + marker, the two moved events, and \
             one fresh root over the result"
        );
        assert!(
            host.replay("persona-absorbed-mem".to_owned())
                .await
                .expect("replay source")
                .is_empty(),
            "the source is destroyed"
        );

        // Re-create the source with the SAME events (the retry / racing-sweep
        // shape): the move dedups to zero appends and destroys again.
        host.append_batch("persona-absorbed-mem".to_owned(), vec![a, b])
            .await
            .expect("re-seed source");
        let again = host
            .migrate_partition(
                "persona-absorbed-mem".to_owned(),
                "persona-survivor-mem".to_owned(),
            )
            .await
            .expect("re-migrate");
        assert_eq!(
            again,
            PartitionMigration::Migrated(0),
            "dedup: no re-append"
        );
        assert_eq!(
            host.replay("persona-survivor-mem".to_owned())
                .await
                .expect("replay survivor again")
                .len(),
            5,
            "the survivor journal did not grow"
        );

        // An empty source is destroyed outright.
        host.append_batch(
            "persona-empty-mem".to_owned(),
            vec![Event::new("memory_added", b"x".to_vec())],
        )
        .await
        .expect("seed empty candidate");
        host.rewrite_partition_for_test(
            "persona-empty-mem".to_owned(),
            Box::new(|_| RewriteDecision::Drop),
        )
        .await
        .expect("empty it out");
        assert_eq!(
            host.migrate_partition(
                "persona-empty-mem".to_owned(),
                "persona-survivor-mem".to_owned()
            )
            .await
            .expect("migrate empty"),
            PartitionMigration::EmptyDestroyed
        );

        // Same-partition "move" is a pure no-op — nothing destroyed.
        assert_eq!(
            host.migrate_partition(
                "persona-survivor-mem".to_owned(),
                "persona-survivor-mem".to_owned()
            )
            .await
            .expect("self-migrate"),
            PartitionMigration::Migrated(0)
        );
        assert_eq!(
            host.replay("persona-survivor-mem".to_owned())
                .await
                .expect("replay after self-migrate")
                .len(),
            5,
            "a self-move destroys nothing"
        );

        drop(host);
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// `rewrite_partition` can REPLACE an event's payload in place (#860): the
    /// predicate keeps some events, drops others, and rewrites one — the
    /// survivor count includes the replaced event, its payload is the new
    /// bytes, and the returned dropped count excludes it. A replace-only
    /// rewrite (nothing dropped) still rewrites the partition.
    #[tokio::test]
    async fn rewrite_partition_replaces_a_payload_in_place() {
        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-rewrite-replace-{}",
            std::process::id()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let shutdown = CancellationToken::new();
        let host = EventLogHost::spawn(
            dir.clone(),
            shutdown.clone(),
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(3),
        )
        .expect("spawn host");

        host.append_batch(
            "persona-rw-mem".to_owned(),
            vec![
                Event::new("memory_added", b"keep".to_vec()),
                Event::new("memory_corroborated", b"has conv-2 and conv-3".to_vec()),
                Event::new("memory_added", b"drop-me".to_vec()),
            ],
        )
        .await
        .expect("seed");

        let dropped = host
            .rewrite_partition_for_test(
                "persona-rw-mem".to_owned(),
                Box::new(|e: &Event| {
                    if e.payload == b"drop-me" {
                        RewriteDecision::Drop
                    } else if e.payload.starts_with(b"has ") {
                        RewriteDecision::Replace(b"has conv-3".to_vec())
                    } else {
                        RewriteDecision::Keep
                    }
                }),
            )
            .await
            .expect("rewrite");
        assert_eq!(dropped, 1, "a replaced event is not counted as dropped");

        // Ignore the MMR signed-root marker the host writes on commit — the
        // real content is the memory events.
        let content = |raw: &[Event]| -> Vec<Vec<u8>> {
            raw.iter()
                .filter(|e| e.kind != "__mmr_signed_root__")
                .map(|e| e.payload.clone())
                .collect()
        };
        let raw = host
            .replay("persona-rw-mem".to_owned())
            .await
            .expect("replay");
        let payloads = content(&raw);
        assert_eq!(
            payloads.len(),
            2,
            "one dropped, one replaced-in-place, one kept: {payloads:?}"
        );
        assert!(payloads.iter().any(|p| p == b"keep"));
        assert!(
            payloads.iter().any(|p| p == b"has conv-3"),
            "the replaced payload is the new bytes, with conv-2 scrubbed"
        );
        assert!(
            !payloads.iter().any(|p| p == b"has conv-2 and conv-3"),
            "the old payload is physically gone"
        );

        // A replace-only rewrite (nothing dropped) still applies.
        let dropped = host
            .rewrite_partition_for_test(
                "persona-rw-mem".to_owned(),
                Box::new(|e: &Event| {
                    if e.payload == b"has conv-3" {
                        RewriteDecision::Replace(b"has nothing".to_vec())
                    } else {
                        RewriteDecision::Keep
                    }
                }),
            )
            .await
            .expect("replace-only rewrite");
        assert_eq!(dropped, 0, "replace-only rewrite drops nothing");
        let raw = host
            .replay("persona-rw-mem".to_owned())
            .await
            .expect("replay again");
        assert!(
            content(&raw).iter().any(|p| p == b"has nothing"),
            "the replace-only rewrite took effect"
        );

        drop(host);
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// A `Replace` rewrites the payload and NOTHING else: each survivor comes
    /// back under its original kind AND its original [`TrustTag`].
    ///
    /// Rebuilding survivors with the default tag would launder provenance on a
    /// live path — the erasure cascade's corroborator scrub is a `Replace`, and
    /// the State journal reads an event's tag straight into the contract
    /// record, so quarantined tool output would come back untainted to any
    /// data-flow policy reading it.
    #[tokio::test]
    async fn rewrite_partition_preserves_each_event_trust_tag() {
        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-rewrite-trust-{}",
            std::process::id()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let shutdown = CancellationToken::new();
        let host = EventLogHost::spawn(
            dir.clone(),
            shutdown.clone(),
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(11),
        )
        .expect("spawn host");

        let partition = "persona-trust-mem".to_owned();
        host.append_batch(
            partition.clone(),
            vec![
                Event::trusted("user_msg", b"a".to_vec()),
                Event::quarantined("tool_result", b"has conv-2 and conv-3".to_vec()),
            ],
        )
        .await
        .expect("seed");

        // A real scrub: the quarantined event's payload is narrowed, which is
        // a content change, so this takes the destroy + re-append path rather
        // than settling as a no-op.
        let dropped = host
            .rewrite_partition_for_test(
                partition.clone(),
                Box::new(|e: &Event| {
                    if e.payload.starts_with(b"has ") {
                        RewriteDecision::Replace(b"has conv-3".to_vec())
                    } else {
                        RewriteDecision::Keep
                    }
                }),
            )
            .await
            .expect("scrub");
        assert_eq!(dropped, 0);

        let survivors: Vec<(String, polyc_eventlog::TrustTag, Vec<u8>)> = host
            .replay(partition.clone())
            .await
            .expect("replay")
            .into_iter()
            .filter(|e| e.kind != polyc_eventlog::MMR_SIGNED_ROOT_KIND)
            .map(|e| (e.kind, e.trust, e.payload))
            .collect();
        assert_eq!(
            survivors,
            vec![
                (
                    "user_msg".to_owned(),
                    polyc_eventlog::TrustTag::TrustedUser,
                    b"a".to_vec()
                ),
                (
                    "tool_result".to_owned(),
                    polyc_eventlog::TrustTag::QuarantinedContent,
                    b"has conv-3".to_vec()
                ),
            ],
            "the scrubbed event keeps its kind and its quarantine, and only its \
             payload changed"
        );

        drop(host);
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// An identity `Replace` over TAGGED events settles as a no-op: same root,
    /// same marker, nothing destroyed and rebuilt.
    ///
    /// The no-op guard compares full [`Event`] equality, trust tag included.
    /// Rebuilding survivors with a default tag would make every tagged event
    /// compare unequal to itself, so the guard could never fire for them — and
    /// the destructive path it guards would re-sign a root that is byte-
    /// identical anyway (MMR leaves are `(kind, payload)`), leaving a reader
    /// pinned to the head unable to see that the partition was rewritten.
    #[tokio::test]
    async fn an_identity_rewrite_over_tagged_events_is_a_no_op() {
        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-rewrite-identity-{}",
            std::process::id()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let shutdown = CancellationToken::new();
        let host = EventLogHost::spawn(
            dir.clone(),
            shutdown.clone(),
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(12),
        )
        .expect("spawn host");

        let partition = "persona-identity-mem".to_owned();
        host.append_batch(
            partition.clone(),
            vec![
                Event::trusted("user_msg", b"a".to_vec()),
                Event::quarantined("tool_result", b"b".to_vec()),
            ],
        )
        .await
        .expect("seed");

        let roots = |raw: &[Event]| -> Vec<Vec<u8>> {
            raw.iter()
                .filter(|e| e.kind == polyc_eventlog::MMR_SIGNED_ROOT_KIND)
                .map(|e| e.payload.clone())
                .collect()
        };
        let before = host.replay(partition.clone()).await.expect("replay before");
        assert_eq!(roots(&before).len(), 1, "the seed committed one root");

        let dropped = host
            .rewrite_partition_for_test(
                partition.clone(),
                Box::new(|e: &Event| RewriteDecision::Replace(e.payload.clone())),
            )
            .await
            .expect("identity rewrite");
        assert_eq!(dropped, 0);

        let after = host.replay(partition.clone()).await.expect("replay after");
        assert_eq!(
            after, before,
            "an identity rewrite leaves the partition byte-for-byte as it was — \
             same events, same tags, same single root at the same position"
        );

        drop(host);
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// Drive the bridge end to end from a live tokio runtime: spawn the host
    /// (which runs the Commonware runtime on its own thread), batch-append
    /// events from tokio, and read them back via replay. This proves the
    /// dedicated-thread + channel bridge works without nesting one runtime in
    /// the other, and that an atomic batch round-trips.
    /// Destroy over the bridge: the cached handle cannot resurrect the
    /// partition — a post-destroy append starts a FRESH log at position 0
    /// with none of the old events (#216 erasure).
    #[tokio::test]
    async fn destroy_partition_evicts_the_handle_and_erases() {
        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-destroy-{}",
            std::process::id()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let shutdown = CancellationToken::new();
        let host = EventLogHost::spawn(
            dir.clone(),
            shutdown.clone(),
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
        )
        .expect("spawn host");

        let partition = "persona-p1-mem".to_owned();
        host.append_batch(
            partition.clone(),
            vec![
                Event::new("memory_added", b"secret fact".to_vec()),
                Event::new("memory_added", b"another".to_vec()),
            ],
        )
        .await
        .expect("seed");
        // The handle is now cached (hot) — exactly the resurrection hazard.
        // 3, not 2: `append_batch` also lands its own MMR signed-root
        // marker (#799) alongside the two content events.
        assert_eq!(
            host.replay(partition.clone()).await.expect("replay").len(),
            3
        );

        host.destroy_partition(partition.clone())
            .await
            .expect("destroy");
        assert!(
            host.replay(partition.clone())
                .await
                .expect("replay after destroy")
                .is_empty(),
            "a destroyed partition replays empty"
        );

        let positions = host
            .append_batch(
                partition.clone(),
                vec![Event::new("memory_added", b"fresh".to_vec())],
            )
            .await
            .expect("append after destroy");
        assert_eq!(positions, vec![0], "the fresh partition starts at zero");
        let events = host.replay(partition).await.expect("replay fresh");
        assert_eq!(
            events.len(),
            2,
            "the content event plus its signed-root marker"
        );
        assert_eq!(events[0].payload, b"fresh", "no old event survives");

        drop(host);
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[tokio::test]
    async fn append_batch_and_replay_over_the_bridge() {
        let dir =
            std::env::temp_dir().join(format!("polychrome-eventlog-test-{}", std::process::id()));
        let shutdown = CancellationToken::new();
        let host = EventLogHost::spawn(
            dir.clone(),
            shutdown.clone(),
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
        )
        .expect("spawn host");

        let partition = "conv-test-e1".to_owned();
        let positions = host
            .append_batch(
                partition.clone(),
                vec![
                    Event::new("output_msg", b"one".to_vec()),
                    Event::new("output_msg", b"two".to_vec()),
                ],
            )
            .await
            .expect("batch append");
        assert_eq!(positions, vec![0, 1], "positions in append order");

        let events = host.replay(partition).await.expect("replay");
        assert_eq!(
            events.len(),
            3,
            "both content events plus the batch's signed-root marker (#799)"
        );
        assert_eq!(events[0].payload, b"one");
        assert_eq!(events[1].payload, b"two");

        // A different partition is isolated.
        let other = host
            .replay("conv-other".to_owned())
            .await
            .expect("replay other");
        assert!(other.is_empty(), "untouched partition replays empty");

        // Clean shutdown: dropping the host joins the dedicated runtime thread.
        drop(host);
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// #818 cross-process split-brain, event-log half. Two independent
    /// [`EventLogHost`]s over ONE shared storage dir model two control-plane
    /// replicas backed by one `ReadWriteMany` volume. Replica B first touches a
    /// conversation's partition while it is still empty — the routine case for
    /// a replica that has never served that conversation — which caches a
    /// journal handle frozen at "empty". Replica A then writes the whole
    /// conversation. B, reading through that frozen handle, keeps reporting
    /// ZERO events: it never re-scans the directory for the section A created.
    /// This is the `raw_events: 0` in the #818 field report — a replica that
    /// did not do the write cannot see it.
    ///
    /// This is a CHARACTERIZATION test: it pins the current single-writer
    /// reality. It passes while the limitation exists and MUST start failing
    /// only once reads gain cross-process coherence — at which point the
    /// deployment can safely go multi-replica and this test, the `replicas: 1`
    /// pin in `manifests/base/control-plane-deployment.yaml`, and the
    /// admission-gate comment (`crate::admission`) get revisited together. Do
    /// not silence it by loosening the assert; it guards against a premature
    /// "multi-replica works" claim. The Kubernetes `Lease` (`crate::lease`)
    /// serializes WRITERS per conversation but grants no reader coherence, so
    /// it does not close this gap.
    #[tokio::test]
    async fn two_host_shared_dir_cold_reader_never_sees_another_writers_events() {
        // Count only the conversation's own content events, ignoring the
        // per-commit `__mmr_signed_root__` tamper-evidence marker (#799) the
        // journal appends alongside each batch — `raw_events` in the field
        // report is content, and counting content keeps the assertion robust
        // to the marker's bookkeeping.
        fn content(events: &[Event]) -> usize {
            events.iter().filter(|e| e.kind == "output_msg").count()
        }

        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-818-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let _ = std::fs::remove_dir_all(&dir);

        // Two replicas, one shared volume, sharing one deployment's journal
        // attestation key (as real replicas of the same deployment do).
        let signer = polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1);
        let host_a = EventLogHost::spawn(dir.clone(), CancellationToken::new(), signer.clone())
            .expect("spawn A");
        let host_b = EventLogHost::spawn(dir.clone(), CancellationToken::new(), signer.clone())
            .expect("spawn B");

        let partition = "conv-818".to_owned();

        // B touches the partition first, while it is still empty (a replica that
        // has never served this conversation). This caches a handle frozen at
        // "no such section on disk".
        assert_eq!(
            content(
                &host_b
                    .replay(partition.clone())
                    .await
                    .expect("B cold replay")
            ),
            0,
            "the conversation has no events yet"
        );

        // A now writes and commits the entire conversation.
        host_a
            .append_batch(
                partition.clone(),
                vec![
                    Event::new("output_msg", b"one".to_vec()),
                    Event::new("output_msg", b"two".to_vec()),
                ],
            )
            .await
            .expect("A append");

        // B reads again through its frozen handle: it still reports ZERO. B
        // never re-scans the directory for the section A created, so a replica
        // that did not do the write serves `raw_events: 0` for a conversation
        // that demonstrably has events — the #818 split-brain.
        assert_eq!(
            content(&host_b.replay(partition.clone()).await.expect("B replay")),
            0,
            "#818: B's frozen handle never observes A's writes — split-brain \
             `raw_events: 0` on a non-writer replica"
        );

        // Contrast: a FRESH host opened AFTER A's writes replays the full,
        // correct history — proving the writes ARE durable on disk and the bug
        // is the per-process frozen open-handle, not lost data.
        let host_c =
            EventLogHost::spawn(dir.clone(), CancellationToken::new(), signer).expect("spawn C");
        assert_eq!(
            content(&host_c.replay(partition.clone()).await.expect("C replay")),
            2,
            "a fresh open reads the full on-disk history — every write is durable"
        );

        drop(host_a);
        drop(host_b);
        drop(host_c);
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[tokio::test]
    async fn namespaced_partition_round_trips() {
        // Conversation ids are namespaced as `namespace:uuid` (the public API
        // mints `web:<uuid>`); the `:` is not a legal storage partition
        // character, so without normalization the log open fails with
        // `PartitionNameInvalid` and the conversation's history is silently never
        // persisted — the same silent data-loss class as #283. Both append AND
        // replay must normalize identically so a namespaced conversation
        // round-trips.
        let dir =
            std::env::temp_dir().join(format!("polychrome-eventlog-ns-{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        let shutdown = CancellationToken::new();
        let host = EventLogHost::spawn(
            dir.clone(),
            shutdown.clone(),
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
        )
        .expect("spawn host");

        let partition = "conv-web:019f0a8a-0aca-7410-b1bf-9f644ea1bfe8".to_owned();
        host.append_batch(
            partition.clone(),
            vec![Event::new("output_msg", b"hi".to_vec())],
        )
        .await
        .expect("append to a namespaced partition must succeed");

        let events = host
            .replay(partition)
            .await
            .expect("replay of a namespaced partition must succeed");
        assert_eq!(
            events.len(),
            2,
            "the namespaced conversation persisted, plus its signed-root marker (#799)"
        );
        assert_eq!(events[0].payload, b"hi");

        drop(host);
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// A never-written namespaced partition is a VALID EMPTY conversation, not a
    /// failure. The bounded replay (`reconstruct_full`'s first read) must normalize
    /// the `:` just like `replay`/`append` do, so a fresh `web:<uuid>`'s opening
    /// turn resolves to `Ok(empty)` rather than `PartitionNameInvalid` — the latter
    /// surfaced as a 503 on a conversation's first message.
    #[tokio::test]
    async fn bounded_replay_of_fresh_namespaced_partition_is_empty_not_an_error() {
        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-ns-tail-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let shutdown = CancellationToken::new();
        let host = EventLogHost::spawn(
            dir.clone(),
            shutdown,
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
        )
        .expect("spawn host");

        let replay = host
            .replay_tail_from_checkpoint("conv-web:019f0a8a-0aca-7410-b1bf-9f644ea1bfe8".to_owned())
            .await
            .expect("bounded replay of a fresh namespaced partition must succeed");
        assert!(replay.checkpoint.is_none(), "no checkpoint on a fresh log");
        assert!(replay.tail.is_empty(), "a never-written partition is empty");

        drop(host);
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// If the manifest points the event-log host at a path it can't write to
    /// (typo, wrong PVC mount, missing permission), the host must surface that
    /// as a real error rather than silently no-op. The runtime opens the
    /// storage backend lazily — first append is where the partition directory
    /// is created — so a bogus `storage_dir` bubbles up from `append_batch` as
    /// `AppendError::Log`, not from `spawn`. Guards against a misconfigured
    /// PVC mount swallowing turn persistence.
    #[tokio::test]
    async fn append_batch_surfaces_error_when_storage_dir_is_unwritable() {
        // A real, valid storage root (commonware 2026.7's own startup
        // filesystem sync needs one — an invalid root now panics `spawn`
        // itself instead of failing lazily on first use, which is a
        // different case than this test wants: see
        // `EventLogHost::migrate_partition`'s sibling test doc for that
        // panic). Instead, a plain FILE pre-created at the exact path the
        // partition's data directory would occupy blocks the create with
        // ENOTDIR — a structural conflict, not a permission check, so this
        // works identically whether the test runs as root (CI's Rust image
        // has no non-root `USER`) or not, unlike a chmod-based read-only
        // directory.
        const PARTITION: &str = "conv-test-bad-dir";
        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-blocked-{}",
            std::process::id()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).expect("create root");
        std::fs::write(
            dir.join(format!("{PARTITION}_data")),
            b"blocks the partition dir",
        )
        .expect("write blocking file");
        let shutdown = CancellationToken::new();
        let host = EventLogHost::spawn(
            dir.clone(),
            shutdown,
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
        )
        .expect("spawn ok (open is lazy)");

        let err = host
            .append_batch(
                PARTITION.to_owned(),
                vec![Event::new("output_msg", b"never persisted".to_vec())],
            )
            .await
            .expect_err("append must fail when storage is unusable");

        match err {
            AppendError::Log(_) => {}
            AppendError::Closed
            | AppendError::AppendOutcomeUnknown(_)
            | AppendError::AttestationOutcomeUnknown(_)
            | AppendError::Listing(_)
            | AppendError::PartitionName(_)
            | AppendError::PayloadTooLarge { .. }
            | AppendError::Verify(_) => {
                panic!("expected a Log error, got: {err}")
            }
        }
        drop(host);
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[tokio::test]
    async fn ensuring_an_absent_partition_creates_nothing() {
        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-ensure-absent-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let host = EventLogHost::spawn(
            dir.clone(),
            CancellationToken::new(),
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
        )
        .expect("spawn host");

        assert!(
            host.ensure_partition_attested("conv-absent".to_owned())
                .await
                .expect("absence is an answered state")
                .is_none()
        );
        assert!(
            !host
                .list_partitions()
                .await
                .expect("list after absence probe")
                .contains(&"conv-absent".to_owned())
        );
        drop(host);
        let _ = std::fs::remove_dir_all(dir);
    }

    #[tokio::test]
    async fn mmr_preparation_failure_is_definite_and_appends_no_content() {
        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-mmr-prepare-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let partition = "conv-mmr-prepare";
        let host = EventLogHost::spawn(
            dir.clone(),
            CancellationToken::new(),
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
        )
        .expect("spawn host");
        arm_mmr_preparation_failure(partition);

        let error = host
            .append_batch(
                partition.to_owned(),
                vec![Event::new("output_msg", b"must-not-land".to_vec())],
            )
            .await
            .expect_err("preparation failure is reported before append");
        assert!(
            matches!(error, AppendError::Log(_)),
            "pre-storage preparation is a definite failure: {error}"
        );
        assert!(
            host.replay(partition.to_owned())
                .await
                .expect("empty replay")
                .is_empty(),
            "neither content nor a root marker may land"
        );

        host.append_batch(
            partition.to_owned(),
            vec![Event::new("output_msg", b"retry".to_vec())],
        )
        .await
        .expect("a clean retry succeeds");
        host.replay_verified(partition.to_owned())
            .await
            .expect("retry evidence verifies");
        drop(host);
        let _ = std::fs::remove_dir_all(dir);
    }

    #[tokio::test]
    async fn root_append_ambiguity_retries_to_exactly_one_attestation() {
        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-root-recovery-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let partition = "conv-root-recovery";
        let host = EventLogHost::spawn(
            dir.clone(),
            CancellationToken::new(),
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
        )
        .expect("spawn host");
        arm_root_append_failure(partition);

        let error = host
            .append_batch(
                partition.to_owned(),
                vec![Event::new("output_msg", b"durable content".to_vec())],
            )
            .await
            .expect_err("root failure leaves the command outcome ambiguous");
        assert!(matches!(error, AppendError::AttestationOutcomeUnknown(_)));

        arm_root_append_failure(partition);
        let ensure_error = host
            .ensure_partition_attested(partition.to_owned())
            .await
            .expect_err("an uncertain ensure append remains ambiguous");
        assert!(matches!(
            ensure_error,
            AppendError::AttestationOutcomeUnknown(_)
        ));

        let recovered = host
            .ensure_partition_attested(partition.to_owned())
            .await
            .expect("reopen and recovery succeed")
            .expect("the non-empty prefix receives evidence");
        let replayed = host.replay(partition.to_owned()).await.expect("replay");
        assert!(
            replayed
                .iter()
                .any(|event| event.payload == b"durable content")
        );
        assert_eq!(
            replayed
                .iter()
                .filter(|event| event.kind == polyc_eventlog::MMR_SIGNED_ROOT_KIND)
                .count(),
            1
        );
        let repeated = host
            .ensure_partition_attested(partition.to_owned())
            .await
            .expect("repeat recovery succeeds")
            .expect("existing evidence is returned");
        assert_eq!(repeated.kind, recovered.kind);
        assert_eq!(repeated.payload, recovered.payload);
        host.replay_verified(partition.to_owned())
            .await
            .expect("recovered evidence verifies");
        drop(host);
        let _ = std::fs::remove_dir_all(dir);
    }

    #[test]
    fn ambiguous_ensure_evicts_both_cached_handles_before_recovery() {
        use commonware_runtime::{Runner as _, tokio as cw_tokio};

        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-ensure-cache-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let storage_dir = dir.clone();
        let partition = "conv-ensure-cache".to_owned();
        let runner =
            cw_tokio::Runner::new(cw_tokio::Config::default().with_storage_directory(dir.clone()));
        runner.start(move |context| async move {
            let mut logs = super::OpenLogs::new();
            let mut checkpoints = HashMap::new();
            let mut count_checkpoints = super::CountCheckpoints::new();
            let mut mmr_logs = HashMap::new();
            let signer = polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1);
            let trust = polyc_crypto::signing_role::RoleTrustSet::from_public_keys(vec![
                signer.public_key_bytes(),
            ])
            .expect("test journal key is encoded ed25519");

            arm_root_append_failure(&partition);
            assert!(matches!(
                super::append_batch_one(
                    &context,
                    &mut logs,
                    &mut checkpoints,
                    &mut count_checkpoints,
                    &mut mmr_logs,
                    &signer,
                    &partition,
                    &[Event::new("output_msg", b"durable content".to_vec())],
                )
                .await,
                Err(AppendError::AttestationOutcomeUnknown(_))
            ));
            assert!(!logs.contains(&partition));
            assert!(!mmr_logs.contains_key(&partition));

            arm_root_append_failure(&partition);
            assert!(matches!(
                super::ensure_partition_attested_one(
                    &context,
                    &storage_dir,
                    &mut logs,
                    &mut count_checkpoints,
                    &mut mmr_logs,
                    &signer,
                    &trust,
                    &partition,
                )
                .await,
                Err(AppendError::AttestationOutcomeUnknown(_))
            ));
            assert!(
                !logs.contains(&partition),
                "an ambiguous ensure must not retain the possibly-fatal journal handle"
            );
            assert!(
                !mmr_logs.contains_key(&partition),
                "an ambiguous ensure must not retain the rebuilt MMR beside an uncertain append"
            );

            super::ensure_partition_attested_one(
                &context,
                &storage_dir,
                &mut logs,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &trust,
                &partition,
            )
            .await
            .expect("a fresh reopen finishes attestation")
            .expect("the durable content receives evidence");
            let replayed = logs
                .get_or_open(&context, &partition)
                .await
                .expect("reopen after recovery")
                .replay()
                .await
                .expect("replay after recovery");
            assert_eq!(
                replayed
                    .iter()
                    .filter(|event| event.kind == polyc_eventlog::MMR_SIGNED_ROOT_KIND)
                    .count(),
                1
            );
        });
        let _ = std::fs::remove_dir_all(dir);
    }

    #[tokio::test]
    async fn ensure_commit_ambiguity_settles_after_restart_without_a_second_root() {
        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-ensure-commit-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let partition = "conv-ensure-commit";
        let signer = polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1);
        let host = EventLogHost::spawn(dir.clone(), CancellationToken::new(), signer.clone())
            .expect("spawn host");
        arm_root_append_failure(partition);
        assert!(matches!(
            host.append_batch(
                partition.to_owned(),
                vec![Event::new("output_msg", b"durable content".to_vec())],
            )
            .await,
            Err(AppendError::AttestationOutcomeUnknown(_))
        ));
        arm_commit_failure(partition);
        assert!(matches!(
            host.ensure_partition_attested(partition.to_owned()).await,
            Err(AppendError::AttestationOutcomeUnknown(_))
        ));
        drop(host);

        let reopened = EventLogHost::spawn(dir.clone(), CancellationToken::new(), signer)
            .expect("restart host");
        reopened
            .ensure_partition_attested(partition.to_owned())
            .await
            .expect("same recovery settles after restart")
            .expect("non-empty content is attested");
        let replayed = reopened.replay(partition.to_owned()).await.expect("replay");
        assert_eq!(
            replayed
                .iter()
                .filter(|event| event.kind == polyc_eventlog::MMR_SIGNED_ROOT_KIND)
                .count(),
            1
        );
        reopened
            .replay_verified(partition.to_owned())
            .await
            .expect("the sole recovered root verifies");
        drop(reopened);
        let _ = std::fs::remove_dir_all(dir);
    }

    /// Which honest outcome class a poisoned append must report.
    ///
    /// Three, not two. The old boolean could not tell a per-event append
    /// failure from a final-commit failure, and they are different facts about
    /// different windows.
    #[derive(Clone, Copy, Debug)]
    enum ExpectedOutcome {
        /// A per-event append failed. The errored append carries no rollback
        /// guarantee, and the best-effort commit may have made an earlier
        /// prefix durable and readable, so the batch outcome is unknown. True
        /// for an error on the FIRST event as much as a later one.
        AppendUnknown,
        /// The root marker append or the final commit failed, so content and
        /// evidence may both already be durable.
        AttestationUnknown,
    }

    fn assert_expected_append_error(error: &AppendError, expected: ExpectedOutcome) {
        match expected {
            ExpectedOutcome::AppendUnknown => assert!(
                matches!(error, AppendError::AppendOutcomeUnknown(_)),
                "a failed event append cannot prove it left no recoverable bytes: {error}"
            ),
            ExpectedOutcome::AttestationUnknown => assert!(
                matches!(error, AppendError::AttestationOutcomeUnknown(_)),
                "a final commit may already have made content and evidence durable: {error}"
            ),
        }
    }

    /// Shared shape behind `append_error_evicts_the_partitions_cached_handle`
    /// and `commit_error_evicts_the_partitions_cached_handle` (`#1712`): seed
    /// a real, successful append so `partition_name`'s journal handle is
    /// already open and cached, arm exactly one injected failure via
    /// `arm_failure`, run `failing_batch` and confirm [`append_batch_one`]
    /// surfaces the operation's honest definite/ambiguous classification and
    /// evicts the partition's cached handle, then confirm a further append
    /// (`recovery_payload`) recovers
    /// cleanly through a freshly reopened handle. Returns every payload
    /// replayed off the recovered log, so each caller asserts its own
    /// expectations about exactly which of `failing_batch`'s events made it
    /// to disk before the injected failure hit.
    ///
    /// This calls [`append_batch_one`] directly against a real
    /// `commonware_runtime::tokio` context (bypassing `EventLogHost`'s actor
    /// plumbing) for two reasons: first, only a direct call gives this
    /// access to `logs.contains(..)`, the one place the fix is actually
    /// observable — going through the public host API, a synthetic injected
    /// failure never actually corrupts the real journal, so a SUBSEQUENT
    /// append or replay through that same public API succeeds identically
    /// whether or not the stale handle was evicted, and could never have
    /// gone red here. Second, there is no portable, root-safe way to make a
    /// genuinely real commonware-storage operation fail on an ALREADY-open,
    /// already-cached handle from outside the storage backend:
    /// `append_batch_surfaces_error_when_storage_dir_is_unwritable`'s
    /// structural-conflict trick only works because it blocks the
    /// partition's directory from ever being created in the first place, so
    /// the handle is never cached at all — exactly the case that can't
    /// reproduce `#1712`'s hazard. `arm_failure` (either `arm_append_failure`
    /// or `arm_commit_failure`) substitutes a real [`EventLogError`] for one
    /// specific append/commit outcome instead, so the rest of
    /// `append_batch_one` runs its genuine error-handling path.
    ///
    /// `dir_prefix` keeps each caller's temp directory distinct from the
    /// other's; `partition_name` does the same for the fault-injection
    /// registry key (both are keyed globally, per-process — see
    /// `ARMED_APPEND_FAILURES`/`ARMED_COMMIT_FAILURES`).
    fn poisoned_append_then_recovers(
        dir_prefix: &str,
        partition_name: &str,
        failing_batch: Vec<Event>,
        arm_failure: impl FnOnce(&str) + Send + 'static,
        expected_outcome: ExpectedOutcome,
        recovery_payload: &'static [u8],
    ) -> PoisonedAppendOutcome {
        use commonware_runtime::{Runner as _, tokio as cw_tokio};

        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-{dir_prefix}-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let partition = partition_name.to_owned();

        let runner =
            cw_tokio::Runner::new(cw_tokio::Config::default().with_storage_directory(dir.clone()));
        let outcome = runner.start(move |context| async move {
            let mut logs = super::OpenLogs::new();
            let mut checkpoints = HashMap::new();
            let mut count_checkpoints = super::CountCheckpoints::new();
            let mut mmr_logs = HashMap::new();
            let signer = polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1);
            let trust = polyc_crypto::signing_role::RoleTrustSet::from_public_keys(vec![
                signer.public_key_bytes(),
            ])
            .expect("test journal key is encoded ed25519");

            // Seed a real, successful append first, so the partition's
            // journal handle is already open and cached before the injected
            // failure.
            super::append_batch_one(
                &context,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &partition,
                &[Event::new("output_msg", b"seed".to_vec())],
            )
            .await
            .expect("seed append");
            assert!(
                logs.contains(&partition),
                "the seed append must have cached the handle"
            );
            let mmr_cached_after_seed = mmr_logs.contains_key(&partition);

            arm_failure(&partition);
            let err = super::append_batch_one(
                &context,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &partition,
                &failing_batch,
            )
            .await
            .expect_err("the armed failure must surface");
            assert_expected_append_error(&err, expected_outcome);

            // The crux of `#1712`: the handle must no longer be cached.
            assert!(
                !logs.contains(&partition),
                "an injected failure must evict the partition's cached handle (#1712)"
            );
            let mmr_cached_after_failure = mmr_logs.contains_key(&partition);

            // Recovery genuinely works afterward: a further valid append
            // succeeds and round-trips through the freshly reopened handle.
            super::append_batch_one(
                &context,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &partition,
                &[Event::new("output_msg", recovery_payload.to_vec())],
            )
            .await
            .expect("a later append to the same partition must succeed cleanly");
            let mmr_cached_after_recovery = mmr_logs.contains_key(&partition);

            let log = logs
                .get_or_open(&context, &partition)
                .await
                .expect("reopen");
            let replayed = log.replay().await.expect("replay after recovery");
            let replayed_payloads = replayed
                .iter()
                .map(|e| e.payload.clone())
                .collect::<Vec<_>>();

            // The real tamper-evidence check (`#799`) over `partition`'s
            // FULL durable history, at the same level `append_batch_one`
            // itself operates at — see `PoisonedAppendOutcome`'s doc for why
            // this is deliberately returned rather than asserted here.
            let verified_after_recovery = super::replay_verified_one(
                &context,
                &mut logs,
                &mut count_checkpoints,
                &trust,
                &partition,
            )
            .await;

            PoisonedAppendOutcome {
                replayed_payloads,
                mmr_cached_after_seed,
                mmr_cached_after_failure,
                mmr_cached_after_recovery,
                verified_after_recovery,
            }
        });

        let _ = std::fs::remove_dir_all(&dir);
        outcome
    }

    /// [`poisoned_append_then_recovers`]'s result: the recovered journal
    /// content, the running-MMR cache (`mmr_logs`) state at each checkpoint
    /// around the injected failure, and a real tamper-evidence verification
    /// of the partition's full history after recovery. Every field beyond
    /// `replayed_payloads` is deliberately returned unasserted by the helper
    /// itself — computed once, so each caller picks only the state its own
    /// scenario actually cares about, rather than the shared scaffolding
    /// enforcing an opinion that only fits one of its callers.
    ///
    /// `verified_after_recovery` is deliberately returned unasserted here
    /// for the same reason as every other field: `commit_failure_evicts_the_mmr_cache`
    /// and `append_error_evicts_the_mmr_cache` each assert it for their own
    /// scenario (`#1740`'s final-commit path and `#1788`'s per-event-append
    /// path, respectively — both now evict `mmr_logs` on failure, so both
    /// verify cleanly). Asserting it unconditionally in the helper would bake
    /// one caller's opinion into shared scaffolding the other callers don't
    /// need.
    struct PoisonedAppendOutcome {
        /// Every event's payload replayed from `partition` after the
        /// recovery append, in journal order.
        replayed_payloads: Vec<Vec<u8>>,
        /// Whether `partition`'s running MMR (`mmr_logs`) was cached right
        /// after the seed append, before the injected failure.
        mmr_cached_after_seed: bool,
        /// Whether `partition`'s running MMR was STILL cached right after
        /// the injected failure. Both a per-event append failure
        /// (`arm_append_failure`, `#1788`) and a final-commit failure
        /// (`arm_commit_failure`, `#1740`) must evict it, so this is `false`
        /// for either.
        mmr_cached_after_failure: bool,
        /// Whether `partition`'s running MMR was cached again after the
        /// recovery append.
        mmr_cached_after_recovery: bool,
        /// [`super::replay_verified_one`]'s result over `partition`'s FULL
        /// history after the recovery append — see this struct's own doc
        /// for why it is exposed unasserted rather than checked here.
        verified_after_recovery: Result<Vec<Event>, super::VerifyError>,
    }

    /// `#1712`: a per-event append error must not leave `partition`'s cached
    /// journal handle in the `logs` cache — Commonware's own docs call a
    /// storage error from a mutable journal operation "fatal for the current
    /// handle", so a handle left cached after one is a possibly-inconsistent
    /// handle every later command for this partition would keep reusing.
    ///
    /// Before the fix: RED — `logs.contains(&partition)` stays `true` after
    /// the injected error, since nothing evicts it. After the fix: GREEN —
    /// the failing append evicts the handle, and a further, valid append
    /// still round-trips correctly through a freshly reopened handle. See
    /// [`poisoned_append_then_recovers`] for the shared scaffolding.
    #[test]
    fn append_error_evicts_the_partitions_cached_handle() {
        let outcome = poisoned_append_then_recovers(
            "poison-append",
            "conv-poison-append",
            vec![
                Event::new("output_msg", b"a".to_vec()),
                // Arm the SECOND event (index 1) of this batch to fail.
                Event::new("output_msg", b"b".to_vec()),
            ],
            |partition| arm_append_failure(partition, 1),
            ExpectedOutcome::AppendUnknown,
            b"c",
        );
        let payloads: Vec<&[u8]> = outcome
            .replayed_payloads
            .iter()
            .map(Vec::as_slice)
            .collect();
        assert!(
            payloads.contains(&b"seed".as_slice()),
            "the pre-existing seed event must survive"
        );
        assert!(
            payloads.contains(&b"a".as_slice()),
            "the first event of the failed batch was committed best-effort \
             before the injected failure"
        );
        assert!(
            !payloads.contains(&b"b".as_slice()),
            "the event AT the injected failure must never have been appended"
        );
        assert!(
            payloads.contains(&b"c".as_slice()),
            "the recovery append must round-trip"
        );
    }

    /// A batch whose final commit fails is not counted as attested.
    ///
    /// The signing step runs BEFORE the commit, so recording the outcome at
    /// the signing site would report a batch that never landed, and would
    /// count again on the caller's retry. Both bias the failure ratio
    /// downward, which is the direction that hides a problem.
    ///
    /// Without this test that placement reverts silently: moving the record
    /// back beside the signing call leaves every other test passing.
    #[tokio::test]
    async fn a_failed_commit_counts_no_attestation() {
        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-commit-fail-attest-{}",
            std::process::id()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let shutdown = CancellationToken::new();
        let host = EventLogHost::spawn(
            dir.clone(),
            shutdown.clone(),
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
        )
        .expect("spawn host");

        // Open the handle first: the seam fires on an already-open log.
        host.append_batch(
            "conv-commit-fail-attest".to_owned(),
            vec![Event::new("output_msg", b"seed".to_vec())],
        )
        .await
        .expect("seed");

        let before = crate::metrics::attestation_count(crate::metrics::AttestationOutcome::Signed);

        arm_commit_failure("conv-commit-fail-attest");
        host.append_batch(
            "conv-commit-fail-attest".to_owned(),
            vec![Event::new("output_msg", b"never-lands".to_vec())],
        )
        .await
        .expect_err("the armed commit failure refuses the batch");

        assert_eq!(
            crate::metrics::attestation_count(crate::metrics::AttestationOutcome::Signed),
            before,
            "a batch whose commit failed must not count as attested"
        );

        shutdown.cancel();
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// A batch that fails on its FIRST event counts nothing.
    ///
    /// Nothing appended, so nothing is durable and nothing is unattested. The
    /// best-effort commit still succeeds — committing nothing works fine — so
    /// without a guard this counts content that does not exist, inflating both
    /// halves of the ratio with phantom batches.
    ///
    /// The guard is one `if`, and one `if` is exactly what reverts silently:
    /// the two `Ok(())` arms look redundant, and collapsing them leaves every
    /// other test green.
    #[tokio::test]
    async fn a_batch_that_fails_on_its_first_event_counts_nothing() {
        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-first-event-fail-{}",
            std::process::id()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let shutdown = CancellationToken::new();
        let host = EventLogHost::spawn(
            dir.clone(),
            shutdown.clone(),
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
        )
        .expect("spawn host");

        // Open the handle first: the seam fires on an already-open log.
        host.append_batch(
            "conv-first-event-fail".to_owned(),
            vec![Event::new("output_msg", b"seed".to_vec())],
        )
        .await
        .expect("seed");

        let before = crate::metrics::attestation_count(
            crate::metrics::AttestationOutcome::UnattestedPartialBatch,
        );

        // Index 0: the batch dies before anything is written.
        arm_append_failure("conv-first-event-fail", 0);
        host.append_batch(
            "conv-first-event-fail".to_owned(),
            vec![
                Event::new("output_msg", b"never".to_vec()),
                Event::new("output_msg", b"lands".to_vec()),
            ],
        )
        .await
        .expect_err("the armed failure refuses the batch");

        assert_eq!(
            crate::metrics::attestation_count(
                crate::metrics::AttestationOutcome::UnattestedPartialBatch
            ),
            before,
            "a batch where nothing landed leaves nothing unattested"
        );

        shutdown.cancel();
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// A committed partial batch counts as unattested (`#1386` risk 9).
    ///
    /// When an append fails partway, the events that already landed are
    /// committed best-effort and this path returns BEFORE the signing step
    /// ever runs. They are durable and attested by nothing, and a partition
    /// holding no marker over them verifies trivially — so nothing else in the
    /// system can report this.
    ///
    /// Without this test no failure label is proven reachable at runtime, and
    /// a label that never fires reads exactly like a label that never fails.
    #[tokio::test]
    async fn a_committed_partial_batch_counts_as_unattested() {
        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-partial-unattested-{}",
            std::process::id()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let shutdown = CancellationToken::new();
        let host = EventLogHost::spawn(
            dir.clone(),
            shutdown.clone(),
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
        )
        .expect("spawn host");

        // Open the handle first: the seam fires on an already-open log.
        host.append_batch(
            "conv-partial-unattested".to_owned(),
            vec![Event::new("output_msg", b"seed".to_vec())],
        )
        .await
        .expect("seed");

        let before = crate::metrics::attestation_count(
            crate::metrics::AttestationOutcome::UnattestedPartialBatch,
        );

        // Fail the SECOND event, so the first is committed best-effort.
        arm_append_failure("conv-partial-unattested", 1);
        host.append_batch(
            "conv-partial-unattested".to_owned(),
            vec![
                Event::new("output_msg", b"lands".to_vec()),
                Event::new("output_msg", b"fails".to_vec()),
            ],
        )
        .await
        .expect_err("the armed failure refuses the batch");

        assert_eq!(
            crate::metrics::attestation_count(
                crate::metrics::AttestationOutcome::UnattestedPartialBatch
            ),
            before + 1,
            "a durable partial batch that never reached signing must be counted"
        );

        shutdown.cancel();
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// Proves the batch-order semantics the control plane's bounded
    /// forced-progress fix (`#1783` review) relies on: `append_batch_one`
    /// commits partial writes rather than rolling back, so of a two-element
    /// batch, only the FIRST element is guaranteed durable when a failure
    /// hits the second. The control plane orders its forced-admission batch
    /// as `[admission_event, summary_event]` for exactly this reason — an
    /// admission decision surviving alone is safe (the prior anchor stays
    /// authoritative), whereas a summary surviving alone with no paired
    /// admission event would be silent loss (INV-C2). This test does not
    /// touch `polyc-control-plane` at all: it reproduces the same
    /// two-element, fail-on-the-second-element shape directly against
    /// `append_batch_one`, which is the shared mechanism both crates depend
    /// on, and is the layer this repo's existing `arm_append_failure` seam
    /// is already wired for (see [`poisoned_append_then_recovers`]'s doc for
    /// why a cross-crate injection point was not added instead).
    #[test]
    fn batch_order_first_element_survives_a_failure_on_the_second() {
        let outcome = poisoned_append_then_recovers(
            "poison-batch-order",
            "conv-poison-batch-order",
            vec![
                Event::new("summary_gate_admitted", b"admission".to_vec()),
                // Arm the SECOND event (index 1, the load-bearing one) of
                // this batch to fail.
                Event::new("summary", b"summary".to_vec()),
            ],
            |partition| arm_append_failure(partition, 1),
            ExpectedOutcome::AppendUnknown,
            b"next-turn",
        );
        let payloads: Vec<&[u8]> = outcome
            .replayed_payloads
            .iter()
            .map(Vec::as_slice)
            .collect();
        assert!(
            payloads.contains(&b"admission".as_slice()),
            "the admission event (ordered first) must survive the partial write"
        );
        assert!(
            !payloads.contains(&b"summary".as_slice()),
            "the summary event (ordered last) must never land without its \
             paired admission — a partial write here must never leave a \
             summary durable with no admission event anywhere in the log"
        );
        assert!(
            payloads.contains(&b"next-turn".as_slice()),
            "the partition recovers cleanly on the next append"
        );
    }

    /// `#1712`'s other named error path: the FINAL `commit()` failing (as
    /// opposed to a per-event append). Same shape and same reasoning as
    /// `append_error_evicts_the_partitions_cached_handle` — every event in
    /// the batch appends successfully, only the trailing `commit()` is made
    /// to fail (see `arm_commit_failure`), and the fix must still evict the
    /// handle. See [`poisoned_append_then_recovers`] for the shared
    /// scaffolding.
    #[test]
    fn commit_error_evicts_the_partitions_cached_handle() {
        let outcome = poisoned_append_then_recovers(
            "poison-commit",
            "conv-poison-commit",
            vec![Event::new("output_msg", b"never-committed".to_vec())],
            arm_commit_failure,
            ExpectedOutcome::AttestationUnknown,
            b"after-recovery",
        );
        let payloads: Vec<&[u8]> = outcome
            .replayed_payloads
            .iter()
            .map(Vec::as_slice)
            .collect();
        assert!(
            payloads.contains(&b"seed".as_slice()),
            "the pre-existing seed event must survive"
        );
        assert!(
            payloads.contains(&b"after-recovery".as_slice()),
            "the recovery append must round-trip"
        );
    }

    /// `#1740`: root preparation mutates the cached `VerifiableLog` before the
    /// first physical append. A FINAL-commit failure cannot establish which
    /// proposed events and root marker became durable, and does not undo the
    /// prepared tree. `append_batch_one` must therefore evict
    /// `partition`'s `mmr_logs` entry on this path (mirroring what
    /// `destroy_one` and `migrate_append_into` already do for their own
    /// commit/destroy failures), so the next successful append rebuilds the
    /// MMR fresh from a full replay of what's actually durable, instead of
    /// continuing to extend a tree that's now ahead of disk. Same shape and
    /// same reasoning as `commit_error_evicts_the_partitions_cached_handle`
    /// — only the asserted cache differs (`mmr_logs` vs `logs`). See
    /// [`poisoned_append_then_recovers`] for the shared scaffolding.
    ///
    /// Before the fix: RED — `mmr_logs.contains_key(&partition)` stayed
    /// `true` after the injected commit failure, since nothing evicted it.
    /// After the fix: GREEN.
    ///
    /// Eviction alone only proves the stale cache entry is gone, not that
    /// the danger `#1740`'s problem statement actually names is resolved: "a
    /// later `ReplayVerified`/tamper-evidence check over the real
    /// (rolled-back) journal content could then fail against a signed root
    /// that was computed over events the disk never durably kept." So this
    /// also runs the real tamper-evidence check
    /// ([`super::replay_verified_one`], the same one
    /// `EventLogHost::replay_verified`/`ApprovalService`'s RPC handler
    /// calls) over the partition's FULL history after the recovery append,
    /// and asserts it succeeds — proving the signed root the rebuilt MMR
    /// produced genuinely verifies against what's actually durable, not
    /// just that the cache map looks right.
    #[test]
    fn commit_failure_evicts_the_mmr_cache() {
        let outcome = poisoned_append_then_recovers(
            "poison-commit-mmr",
            "conv-poison-commit-mmr",
            vec![Event::new("output_msg", b"never-committed".to_vec())],
            arm_commit_failure,
            ExpectedOutcome::AttestationUnknown,
            b"after-recovery",
        );

        assert!(
            outcome.mmr_cached_after_seed,
            "seed append must populate the running MMR"
        );
        // The crux of `#1740`: the MMR cache must no longer hold this
        // partition's now-stale-ahead-of-disk tree.
        assert!(
            !outcome.mmr_cached_after_failure,
            "#1740: a failed final commit must evict the partition's cached MMR"
        );
        assert!(
            outcome.mmr_cached_after_recovery,
            "#1740: a subsequent successful append must repopulate the MMR cache"
        );

        // The actual harm `#1740` cares about: prove the post-recovery
        // state is genuinely tamper-evidence-verifiable, not just that the
        // cache key transitioned correctly.
        let verified = outcome.verified_after_recovery.expect(
            "#1740: the partition's full history after a commit-failure-triggered \
             MMR rebuild must still pass real tamper-evidence verification — a \
             signed root computed post-recovery must check out against what \
             actually landed on disk, not a phantom pre-failure tree",
        );
        assert!(
            verified
                .iter()
                .any(|event| event.kind == polyc_eventlog::MMR_SIGNED_ROOT_KIND),
            "the recovery append must have landed its own signed-root marker \
             for the verification above to be meaningful"
        );
    }

    /// `#1788`: root preparation extends the cached tree with the full proposed
    /// batch before any physical append. A per-event failure followed by the
    /// best-effort commit can land only a prefix, leaving the cache ahead of
    /// the durable journal. `append_batch_one` must evict
    /// `partition`'s `mmr_logs` entry here too, so the next successful append
    /// rebuilds it fresh from a full replay. Same shape and same reasoning as
    /// `commit_failure_evicts_the_mmr_cache` — only the injected failure
    /// differs (`arm_append_failure` vs `arm_commit_failure`). See
    /// [`poisoned_append_then_recovers`] for the shared scaffolding.
    ///
    /// Before the fix: RED — `mmr_logs.contains_key(&partition)` stayed
    /// `true` after the injected per-event append failure, since nothing
    /// evicted it. After the fix: GREEN.
    #[test]
    fn append_error_evicts_the_mmr_cache() {
        let outcome = poisoned_append_then_recovers(
            "poison-append-mmr",
            "conv-poison-append-mmr",
            vec![
                Event::new("output_msg", b"a".to_vec()),
                // Arm the SECOND event (index 1) of this batch to fail —
                // the first event still lands via the best-effort commit,
                // pushing the on-disk journal ahead of the cached MMR tree.
                Event::new("output_msg", b"b".to_vec()),
            ],
            |partition| arm_append_failure(partition, 1),
            ExpectedOutcome::AppendUnknown,
            b"after-recovery",
        );

        assert!(
            outcome.mmr_cached_after_seed,
            "seed append must populate the running MMR"
        );
        // The crux of `#1788`: the MMR cache must no longer hold this
        // partition's now-stale-behind-disk tree.
        assert!(
            !outcome.mmr_cached_after_failure,
            "#1788: a failed per-event append must evict the partition's cached MMR"
        );
        assert!(
            outcome.mmr_cached_after_recovery,
            "#1788: a subsequent successful append must repopulate the MMR cache"
        );

        // The actual harm `#1788` cares about: prove the post-recovery
        // state is genuinely tamper-evidence-verifiable, not just that the
        // cache key transitioned correctly.
        let verified = outcome.verified_after_recovery.expect(
            "#1788: the partition's full history after a per-event-append-failure-triggered \
             MMR rebuild must still pass real tamper-evidence verification — a \
             signed root computed post-recovery must check out against what \
             actually landed on disk, not a phantom pre-failure tree",
        );
        assert!(
            verified
                .iter()
                .any(|event| event.kind == polyc_eventlog::MMR_SIGNED_ROOT_KIND),
            "the recovery append must have landed its own signed-root marker \
             for the verification above to be meaningful"
        );
    }

    /// `#1742`: `destroy_one` must not clear a partition's compaction
    /// checkpoint frame, running MMR, or durable event-count checkpoint
    /// until the fallible destruction has actually succeeded — an
    /// erasure that fails to remove the on-disk blobs must not look, from
    /// this process's own in-memory perspective, like it succeeded.
    ///
    /// Before the fix: RED — the injected destroy failure still finds every
    /// cache wiped, since they were cleared before `destroy()` ran. After
    /// the fix: GREEN — a failed destroy leaves the caches intact.
    #[test]
    fn destroy_failure_leaves_caches_intact() {
        use commonware_runtime::{Runner as _, tokio as cw_tokio};

        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-poison-destroy-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let partition = "conv-poison-destroy".to_owned();

        let runner =
            cw_tokio::Runner::new(cw_tokio::Config::default().with_storage_directory(dir.clone()));
        runner.start(move |context| async move {
            let mut logs = super::OpenLogs::new();
            let mut checkpoints = HashMap::new();
            let mut count_checkpoints = super::CountCheckpoints::new();
            let mut mmr_logs = HashMap::new();
            let signer = polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1);

            // Seed a real, successful append so the partition has a real
            // running MMR and durable count-checkpoint to protect — exactly
            // the state a genuine erasure would otherwise be discarding.
            super::append_batch_one(
                &context,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &partition,
                &[Event::new("output_msg", b"seed".to_vec())],
            )
            .await
            .expect("seed append");
            assert!(
                mmr_logs.contains_key(&partition),
                "seed append must populate the running MMR"
            );
            assert!(
                count_checkpoints.contains(&partition),
                "seed append must populate the durable count checkpoint"
            );

            // The compaction checkpoint frame is the third cache
            // `destroy_one` must protect; insert it directly rather than via
            // a real `BASE_COMPACTION_CHECKPOINT` event, since only its
            // presence in the map matters here.
            checkpoints.insert(
                partition.clone(),
                CheckpointFrame {
                    tail_offset: 1,
                    payload: b"checkpoint".to_vec(),
                },
            );

            arm_destroy_failure(&partition);
            let err = super::destroy_one(
                &context,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &partition,
                super::DestroyCheckpoint::Clear,
            )
            .await
            .expect_err("the armed destroy failure must surface");
            assert!(
                matches!(err, EventLogError::Journal(_)),
                "expected a Journal error, got: {err}"
            );

            assert!(
                checkpoints.contains_key(&partition),
                "#1742: a failed destroy must not clear the compaction checkpoint frame"
            );
            assert!(
                mmr_logs.contains_key(&partition),
                "#1742: a failed destroy must not clear the running MMR"
            );
            assert!(
                count_checkpoints.contains(&partition),
                "#1742: a failed destroy must not clear the durable event-count checkpoint"
            );
        });

        let _ = std::fs::remove_dir_all(&dir);
    }

    /// `#1741`: `migrate_append_into` must give the migration destination's
    /// write the same "fatal for the current handle" shape `append_batch_one`
    /// has (`#1712`) — a per-event append failure must best-effort commit
    /// whatever already landed and evict `to`'s cached handle, not leave
    /// uncommitted events sitting in the journal's write buffer with a stale
    /// handle cached for the very next command touching `to` to reuse.
    ///
    /// Before the fix: RED — the injected append failure propagates with no
    /// best-effort commit and no eviction, so `logs.contains(&to)` stays
    /// `true` and the survivor event is never committed. After the fix:
    /// GREEN.
    #[test]
    fn migrate_append_failure_evicts_the_handle_and_commits_partial_writes() {
        use commonware_runtime::{Runner as _, tokio as cw_tokio};

        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-poison-migrate-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let to = "conv-poison-migrate-to".to_owned();
        let from = "conv-poison-migrate-from".to_owned();
        let to_ref = super::PartitionRef::new(&to).expect("the name encodes");
        let from_ref = super::PartitionRef::new(&from).expect("the name encodes");

        let runner =
            cw_tokio::Runner::new(cw_tokio::Config::default().with_storage_directory(dir.clone()));
        runner.start(move |context| async move {
            let mut logs = super::OpenLogs::new();
            let mut count_checkpoints = super::CountCheckpoints::new();
            let mut mmr_logs = HashMap::new();
            let write_observers = super::observer::WriteObservers::new();

            // Populate `to`'s cached tree first, so the eviction assertion
            // below is not vacuous. `mmr_logs` starts empty in this test, and
            // an absent key proves nothing about whether anything removed it.
            let mut checkpoints = HashMap::new();
            super::append_batch_one(
                &context,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
                &to,
                &[Event::new("output_msg", b"seed".to_vec())],
            )
            .await
            .expect("seed the destination so its tree is cached");
            assert!(
                mmr_logs.contains_key(&to),
                "the seed must leave a cached tree, or the assertion below is vacuous"
            );

            // Arm the SECOND event (index 1) of this batch to fail.
            arm_append_failure(&to, 1);
            let err = super::migrate_append_into(
                &context,
                &mut logs,
                &mut count_checkpoints,
                &mut mmr_logs,
                &polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
                &to_ref,
                &[
                    Event::new("memory_added", b"a".to_vec()),
                    Event::new("memory_added", b"b".to_vec()),
                ],
                &write_observers,
                &from_ref,
            )
            .await
            .expect_err("the armed failure must surface");
            assert!(
                matches!(err, EventLogError::Journal(_)),
                "expected a Journal error, got: {err}"
            );

            assert!(
                !logs.contains(&to),
                "#1741: an injected append failure must evict `to`'s cached handle"
            );

            // The survivor event was committed best-effort, and a fresh
            // handle for `to` genuinely reopens and replays it.
            let recovered = logs.get_or_open(&context, &to).await.expect("reopen");
            let replayed = recovered.replay().await.expect("replay");
            let payloads: Vec<&[u8]> = replayed.iter().map(|e| e.payload.as_slice()).collect();
            assert!(
                payloads.contains(&b"a".as_slice()),
                "the first event of the failed batch was committed best-effort"
            );
            assert!(
                !payloads.contains(&b"b".as_slice()),
                "the event AT the injected failure must never have been appended"
            );

            // `#2653`: the cached TREE must go too, not only the handle.
            //
            // The best-effort commit above landed an event, so `to`'s journal
            // is now ahead of whatever tree the cache holds. A surviving cache
            // makes the next batch sign a root over a tree shorter than disk,
            // and that marker can never verify — the same unrepairable
            // mismatch this issue exists to remove, arrived by another route.
            // `append_batch_one` evicts on both its failure paths for exactly
            // this reason (`#1788`, `#1740`).
            assert!(
                !mmr_logs.contains_key(&to),
                "an injected append failure must evict `to`'s cached MMR too"
            );
        });

        let _ = std::fs::remove_dir_all(&dir);
    }

    /// `#1741`'s other named error path: the FINAL `commit()` failing (as
    /// opposed to a per-event append). Same shape and reasoning as
    /// `migrate_append_failure_evicts_the_handle_and_commits_partial_writes`
    /// — every event in the batch appends successfully, only the trailing
    /// `commit()` is made to fail, and the fix must still evict the handle.
    #[test]
    fn migrate_commit_failure_evicts_the_handle() {
        use commonware_runtime::{Runner as _, tokio as cw_tokio};

        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-poison-migrate-commit-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let to = "conv-poison-migrate-commit-to".to_owned();
        let from = "conv-poison-migrate-commit-from".to_owned();
        let to_ref = super::PartitionRef::new(&to).expect("the name encodes");
        let from_ref = super::PartitionRef::new(&from).expect("the name encodes");

        let runner =
            cw_tokio::Runner::new(cw_tokio::Config::default().with_storage_directory(dir.clone()));
        runner.start(move |context| async move {
            let mut logs = super::OpenLogs::new();
            let mut count_checkpoints = super::CountCheckpoints::new();
            let mut mmr_logs = HashMap::new();
            let write_observers = super::observer::WriteObservers::new();

            // Populate `to`'s cached tree first, so the eviction assertion
            // below is not vacuous — `mmr_logs` starts empty here.
            let mut checkpoints = HashMap::new();
            super::append_batch_one(
                &context,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
                &to,
                &[Event::new("output_msg", b"seed".to_vec())],
            )
            .await
            .expect("seed the destination so its tree is cached");
            assert!(
                mmr_logs.contains_key(&to),
                "the seed must leave a cached tree, or the assertion below is vacuous"
            );

            arm_commit_failure(&to);
            let err = super::migrate_append_into(
                &context,
                &mut logs,
                &mut count_checkpoints,
                &mut mmr_logs,
                &polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
                &to_ref,
                &[Event::new("memory_added", b"never-committed".to_vec())],
                &write_observers,
                &from_ref,
            )
            .await
            .expect_err("the armed commit failure must surface");
            assert!(
                matches!(err, EventLogError::Journal(_)),
                "expected a Journal error, got: {err}"
            );
            assert!(
                !logs.contains(&to),
                "#1741: an injected commit failure must evict `to`'s cached handle"
            );
            // `#2653`: the cached TREE must go too. The re-root above built a
            // tree over content this failed commit did not land, so a
            // surviving cache is ahead of disk and the next batch's marker
            // could never verify.
            assert!(
                !mmr_logs.contains_key(&to),
                "an injected commit failure must evict `to`'s cached MMR too"
            );
        });

        let _ = std::fs::remove_dir_all(&dir);
    }

    /// The worker-label leak this diff introduced, now fixed: every
    /// respawn of the SAME partition (an LRU-evict-then-respawn cycle in
    /// `PartitionWorkers::get_or_spawn`) must reuse the ONE supervision-tree
    /// label already leaked for that partition name, not leak a fresh
    /// `&'static str` on every spawn — the same defect class `#1713` tracks
    /// for `OpenLogs::get_or_open`'s own per-partition leak, but freshly
    /// introduced HERE by this diff's own `#1711` commit.
    ///
    /// Before the fix (inlining `Box::leak(format!("{sanitized}_worker")..)`
    /// directly in `get_or_spawn`, with no interning map): calling the
    /// equivalent of `worker_label` twice for the SAME partition would
    /// return two DIFFERENT leaked pointers, and the number of live-forever
    /// allocations would grow without bound across repeated evict/respawn
    /// cycles for one partition, not just once per DISTINCT partition name
    /// over the process lifetime. After the fix: GREEN — every respawn
    /// reuses the identical leaked pointer, and `worker_labels` grows only
    /// with the number of distinct partitions ever seen, never with the
    /// number of times any one of them respawns.
    #[test]
    fn worker_label_interns_per_partition_and_is_reused_across_respawns() {
        let mut workers = super::PartitionWorkers::new();

        // Two distinct partitions get two DISTINCT interned labels.
        let a1 = workers.worker_label("conv-a");
        let b1 = workers.worker_label("conv-b");
        assert!(
            !std::ptr::eq(a1, b1),
            "distinct partitions must get distinct labels"
        );

        // Respawning the SAME partition any number of times (simulating
        // repeated LRU-evict-then-respawn cycles) must keep reusing that
        // ONE already-leaked label rather than leaking a fresh one on every
        // call — this loop is what would have grown `worker_labels`'s
        // backing allocation count unboundedly before the fix.
        for _ in 0..50 {
            assert!(
                std::ptr::eq(a1, workers.worker_label("conv-a")),
                "respawning `conv-a` must reuse its one interned label"
            );
            assert!(
                std::ptr::eq(b1, workers.worker_label("conv-b")),
                "respawning `conv-b` must reuse its one interned label"
            );
        }

        assert_eq!(
            workers.worker_labels.len(),
            2,
            "exactly one leaked label per DISTINCT partition, however many \
             times each has been (re)spawned — not one per spawn"
        );
    }

    /// `#1713`: `OpenLogs::get_or_open` must intern its per-partition
    /// supervision-tree label the same way `PartitionWorkers::worker_label`
    /// already interns its own sibling label — reusing the ONE label
    /// already leaked for a partition on every later reopen, rather than
    /// leaking a fresh one on every LRU-eviction-then-reopen cycle for the
    /// SAME partition. Unlike `worker_label_interns_per_partition_and_is_
    /// reused_across_respawns` (a pure, synchronous helper), `OpenLogs`
    /// opens a genuine on-disk `EventLog`, so this drives the real, async
    /// `get_or_open` against a real Commonware runtime and temp directory,
    /// evicting the SAME partition's cached handle via `OpenLogs::take`
    /// (its own doc: "after this, only a fresh `get_or_open` can reach the
    /// name" — exactly what an LRU eviction past `LOGS_CAP` does) and
    /// reopening it many times.
    ///
    /// Before the fix: RED — `get_or_open` inlined a fresh
    /// `Box::leak(sanitized.into_boxed_str())` on every call that found no
    /// cached handle and there was no `log_labels` map at all, so this test
    /// fails to compile against the pre-fix code (`OpenLogs` has no
    /// `log_labels` field/`log_label` method), and — reasoning about what
    /// the equivalent inlined-leak code would have done — the loop below
    /// would have observed a DIFFERENT leaked pointer on every reopen. After
    /// the fix: GREEN — every reopen of `partition` reuses the identical
    /// leaked pointer, and `log_labels` grows only with the number of
    /// distinct partitions ever seen (one, here), never with the number of
    /// times that one partition is evicted and reopened.
    #[test]
    fn get_or_open_label_interns_per_partition_and_is_reused_across_reopens() {
        use commonware_runtime::{Runner as _, tokio as cw_tokio};

        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-label-intern-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let partition = "conv-label-intern".to_owned();

        let runner =
            cw_tokio::Runner::new(cw_tokio::Config::default().with_storage_directory(dir.clone()));
        let distinct_labels = runner.start(move |context| async move {
            let mut logs = super::OpenLogs::new();

            logs.get_or_open(&context, &partition)
                .await
                .expect("first open");
            let first_label = *logs
                .log_labels
                .get(&partition)
                .expect("label recorded on first open");

            // Simulate 50 LRU-evict-then-reopen cycles for the SAME
            // partition — `OpenLogs::take` removes the cached handle exactly
            // as an LRU eviction would, so each iteration forces a genuine
            // reopen rather than a cache hit.
            for _ in 0..50 {
                logs.take(&partition);
                logs.get_or_open(&context, &partition)
                    .await
                    .expect("reopen after simulated eviction");
                let label = *logs
                    .log_labels
                    .get(&partition)
                    .expect("label recorded on reopen");
                assert!(
                    std::ptr::eq(first_label, label),
                    "reopening the SAME partition must reuse its one \
                     interned label"
                );
            }

            logs.log_labels.len()
        });

        let _ = std::fs::remove_dir_all(&dir);
        assert_eq!(
            distinct_labels, 1,
            "exactly one leaked label for the one distinct partition \
             reopened, however many times it was evicted and reopened — \
             not one per reopen"
        );
    }

    /// Write/read symmetry: a payload over the shared decode cap is refused
    /// at append time — persisting it would create an entry no replay path
    /// could ever decode.
    #[tokio::test]
    async fn append_rejects_payload_over_decode_cap() {
        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-cap-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let shutdown = CancellationToken::new();
        let host = EventLogHost::spawn(
            dir.clone(),
            shutdown,
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
        )
        .expect("spawn host");

        let oversized = vec![0u8; polyc_proto::events_decode::MAX_EVENT_PAYLOAD_BYTES + 1];
        let err = host
            .append_batch(
                "conv-cap-test".to_owned(),
                vec![Event::new("output_msg", oversized)],
            )
            .await
            .expect_err("over-cap payload must be refused");
        assert!(
            matches!(err, AppendError::PayloadTooLarge { ref kind, .. } if kind == "output_msg"),
            "expected PayloadTooLarge, got: {err}"
        );

        drop(host);
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// The cheap emission gate: `events_since_checkpoint` counts only the events
    /// appended AFTER the latest checkpoint, not the whole log. Before any
    /// checkpoint the whole log is the tail; once a checkpoint lands the count
    /// resets to the post-checkpoint tail (so a long conversation doesn't re-fire
    /// the gate every turn). It must agree with the materialized tail length from
    /// `replay_tail_from_checkpoint`, while never scanning the log.
    #[tokio::test]
    async fn events_since_checkpoint_counts_only_the_post_checkpoint_tail() {
        use polyc_proto::kinds::{
            COMPACTION_CHECKPOINT as BASE_COMPACTION_CHECKPOINT, tagged as tagged_kind,
        };

        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-since-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let shutdown = CancellationToken::new();
        let host = EventLogHost::spawn(
            dir.clone(),
            shutdown,
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
        )
        .expect("spawn host");
        let partition = "conv-since".to_owned();

        // No checkpoint yet: the whole log is the tail.
        host.append_batch(
            partition.clone(),
            vec![
                Event::new("output_msg", b"a".to_vec()),
                Event::new("output_msg", b"b".to_vec()),
                Event::new("output_msg", b"c".to_vec()),
            ],
        )
        .await
        .expect("append prefix");
        assert_eq!(
            host.events_since_checkpoint(partition.clone())
                .await
                .expect("count"),
            4,
            "no checkpoint ⇒ count is the whole log (3 content events + \
             the batch's signed-root marker, #799)"
        );

        // A checkpoint lands (cache warms on append), then two more events.
        host.append_batch(
            partition.clone(),
            vec![Event::new(
                tagged_kind(BASE_COMPACTION_CHECKPOINT, &uuid::Uuid::now_v7()),
                b"ckpt".to_vec(),
            )],
        )
        .await
        .expect("append checkpoint");
        host.append_batch(
            partition.clone(),
            vec![
                Event::new("output_msg", b"d".to_vec()),
                Event::new("output_msg", b"e".to_vec()),
            ],
        )
        .await
        .expect("append tail");

        let since = host
            .events_since_checkpoint(partition.clone())
            .await
            .expect("count after checkpoint");
        // 4, not 2: the checkpoint batch's own signed-root marker (#799)
        // lands AFTER the checkpoint event, so it counts as part of the
        // tail too, alongside the checkpoint batch's marker + d + e + the
        // tail batch's own marker.
        assert_eq!(since, 4, "count resets to the post-checkpoint tail, not 9");

        // It agrees with the materialized tail the bounded replay returns.
        let replay = host
            .replay_tail_from_checkpoint(partition)
            .await
            .expect("replay tail");
        assert_eq!(since, replay.tail.len() as u64);

        drop(host);
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// `partition_event_count` reports the partition's TOTAL size (unlike
    /// `events_since_checkpoint`, it never resets at a compaction checkpoint)
    /// and tracks every append, content and marker alike — it must match
    /// what a full `replay` returns, without decoding anything to get there.
    #[tokio::test]
    async fn partition_event_count_tracks_total_appends_across_a_checkpoint() {
        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-count-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let shutdown = CancellationToken::new();
        let host = EventLogHost::spawn(
            dir.clone(),
            shutdown,
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
        )
        .expect("spawn host");
        let partition = "conv-count".to_owned();

        // 3 content events + the batch's own signed-root marker (#799) = 4.
        host.append_batch(
            partition.clone(),
            vec![
                Event::new("output_msg", b"a".to_vec()),
                Event::new("output_msg", b"b".to_vec()),
                Event::new("output_msg", b"c".to_vec()),
            ],
        )
        .await
        .expect("append prefix");
        assert_eq!(
            host.partition_event_count(partition.clone())
                .await
                .expect("count"),
            4,
        );
        assert_eq!(
            host.replay(partition.clone()).await.expect("replay").len() as u64,
            4,
            "partition_event_count must agree with a full replay's length"
        );

        // A checkpoint lands, then two more content events. Unlike
        // `events_since_checkpoint` (which would reset to the post-checkpoint
        // tail), the total keeps growing: 4 (prefix) + 1 (checkpoint event) +
        // 1 (that batch's own marker) + 2 (tail) + 1 (tail batch's marker) = 9.
        host.append_batch(
            partition.clone(),
            vec![Event::new(
                polyc_proto::kinds::tagged(
                    polyc_proto::kinds::COMPACTION_CHECKPOINT,
                    &uuid::Uuid::now_v7(),
                ),
                b"ckpt".to_vec(),
            )],
        )
        .await
        .expect("append checkpoint");
        host.append_batch(
            partition.clone(),
            vec![
                Event::new("output_msg", b"d".to_vec()),
                Event::new("output_msg", b"e".to_vec()),
            ],
        )
        .await
        .expect("append tail");

        let total = host
            .partition_event_count(partition.clone())
            .await
            .expect("count after checkpoint");
        assert_eq!(total, 9, "total keeps growing across a checkpoint");
        let since = host
            .events_since_checkpoint(partition.clone())
            .await
            .expect("since checkpoint, for contrast");
        assert_ne!(
            total, since,
            "the two primitives measure different things once a checkpoint exists"
        );

        drop(host);
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// The read-time counterpart to `list_partitions`' own creation
    /// discipline: counting a partition that was never appended to must
    /// report `0` WITHOUT creating it on disk — opening it (the path every
    /// other read takes) would otherwise mint an empty journal as a side
    /// effect of a mere probe.
    #[tokio::test]
    async fn partition_event_count_of_unknown_partition_is_zero_and_creates_nothing() {
        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-count-unknown-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let shutdown = CancellationToken::new();
        let host = EventLogHost::spawn(
            dir.clone(),
            shutdown,
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
        )
        .expect("spawn host");

        let count = host
            .partition_event_count("conv-never-touched".to_owned())
            .await
            .expect("count of unknown partition");
        assert_eq!(count, 0, "an unwritten partition counts as empty");
        assert!(
            !dir.join("conv-never-touched_data").exists(),
            "a mere count probe must not create the partition's journal"
        );
        assert!(
            !dir.join("conv-never-touched_offsets").exists(),
            "a mere count probe must not create the partition's offsets index either"
        );

        drop(host);
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// The operational fact behind a retention policy's idle axis, on the real
    /// on-disk layout: a written partition reports a time, an unwritten one
    /// reports nothing and is not created by asking, and a backdated partition
    /// reports the backdated time — which is what makes the answer usable as
    /// "idle since".
    #[tokio::test]
    async fn partition_last_modified_reports_storage_time_and_creates_nothing() {
        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-lastmod-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let shutdown = CancellationToken::new();
        let host = EventLogHost::spawn(
            dir.clone(),
            shutdown,
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
        )
        .expect("spawn host");

        // A namespaced name, so the codec every other entry point applies is
        // applied here too — the caller names the logical partition, and the
        // directory carries the encoded one.
        host.append_batch(
            "conv-app:one".to_owned(),
            vec![Event::new("k", b"v".to_vec())],
        )
        .await
        .expect("seed");

        let written = host
            .partition_last_modified_ms("conv-app:one".to_owned())
            .await
            .expect("last-modified of a written partition")
            .expect("a written partition has a storage time");
        let now = u64::try_from(
            std::time::SystemTime::now()
                .duration_since(std::time::SystemTime::UNIX_EPOCH)
                .expect("clock")
                .as_millis(),
        )
        .expect("a millisecond clock reading fits");
        assert!(
            now.saturating_sub(written) < 60_000,
            "a partition written moments ago reports a recent time: {written} against {now}"
        );

        assert_eq!(
            host.partition_last_modified_ms("conv-never-touched".to_owned())
                .await
                .expect("last-modified of an unknown partition"),
            None,
            "a partition this host holds nothing for reports nothing"
        );
        assert!(
            !dir.join("conv-never-touched_data").exists(),
            "a mere time probe must not create the partition's journal"
        );

        // Backdating the files behind the partition moves the answer, which is
        // the whole of what the idle axis decides on.
        let long_ago = std::time::SystemTime::now() - std::time::Duration::from_hours(1);
        // Derived, never spelled out: the contract is that storage holds the
        // ENCODED name, so a literal here would pin one spelling of the codec
        // rather than the contract itself.
        let data_dir = dir.join(format!(
            "{}_data",
            super::encode_partition("conv-app:one").expect("the name encodes")
        ));
        for entry in std::fs::read_dir(&data_dir).expect("read data dir") {
            let entry = entry.expect("dir entry");
            std::fs::File::options()
                .write(true)
                .open(entry.path())
                .expect("open for mtime set")
                .set_modified(long_ago)
                .expect("set_modified");
        }
        let backdated = host
            .partition_last_modified_ms("conv-app:one".to_owned())
            .await
            .expect("last-modified after backdating")
            .expect("a backdated partition still has a storage time");
        assert!(
            backdated < written,
            "the reported time follows the storage it is read from: {backdated} against {written}"
        );

        drop(host);
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// Production MMR wiring end-to-end (`#799`), on real on-disk files:
    /// `append_batch` extends the partition's running MMR and lands a
    /// signed-root marker in the SAME commit as the content it covers (two
    /// separate turns each get their own marker), and `replay_verified`
    /// accepts the result across a fresh reopen (proving the running MMR
    /// rebuilds correctly from a cold partition, not just within one
    /// process). The tamper-DETECTION half of this — flipping a byte in a
    /// persisted event and asserting `verify_replay` catches it — is pinned
    /// directly against `polyc_eventlog::integrity` (the pure function this
    /// wiring delegates to), which is the right level for it: this test's
    /// job is proving the host correctly PERSISTS and REBUILDS the signed
    /// roots on the real journal, not re-deriving the detection logic.
    #[tokio::test]
    async fn mmr_append_batch_signs_root_and_replay_verified_survives_reopen() {
        let dir =
            std::env::temp_dir().join(format!("polychrome-eventlog-mmr-{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        let shutdown = CancellationToken::new();
        let host = EventLogHost::spawn(
            dir.clone(),
            shutdown.clone(),
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
        )
        .expect("spawn");

        let partition = "conv-mmr-wiring".to_owned();
        host.append_batch(
            partition.clone(),
            vec![Event::new("user_msg", b"turn one".to_vec())],
        )
        .await
        .expect("append turn 1");
        host.append_batch(
            partition.clone(),
            vec![Event::new("output_msg", b"turn two".to_vec())],
        )
        .await
        .expect("append turn 2");

        let verified = host
            .replay_verified(partition.clone())
            .await
            .expect("both turns verify within the same process");
        let marker_count = verified
            .iter()
            .filter(|e| e.kind == polyc_eventlog::MMR_SIGNED_ROOT_KIND)
            .count();
        assert_eq!(
            verified.len(),
            4,
            "2 content events + 2 signed-root markers"
        );
        assert_eq!(marker_count, 2, "one marker per turn's append_batch");

        drop(host);

        // Reopen: the running MMR (memory-only) must rebuild correctly from
        // the full replay before it can keep signing — proven by a THIRD
        // turn verifying together with the first two after the restart.
        let shutdown2 = CancellationToken::new();
        let host2 = EventLogHost::spawn(
            dir.clone(),
            shutdown2,
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
        )
        .expect("respawn");
        host2
            .append_batch(
                partition.clone(),
                vec![Event::new("tool_call", b"turn three".to_vec())],
            )
            .await
            .expect("append turn 3 after reopen");
        let verified_after_reopen = host2
            .replay_verified(partition)
            .await
            .expect("all three turns verify after a cold rebuild");
        assert_eq!(
            verified_after_reopen.len(),
            6,
            "3 content events + 3 signed-root markers, across the reopen"
        );

        drop(host2);
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[tokio::test]
    async fn repair_apply_refuses_a_partition_changed_after_inspection() {
        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-repair-fence-{}",
            std::process::id()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let partition = "conv-repair-fence".to_owned();
        let host = EventLogHost::spawn(
            dir.clone(),
            CancellationToken::new(),
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
        )
        .expect("spawn");
        host.append_batch(
            partition.clone(),
            vec![Event::new("user_msg", b"before".to_vec())],
        )
        .await
        .expect("seed");
        let stale = host
            .inspect_repair_partition(partition.clone(), None)
            .await
            .expect("inspect");
        host.append_batch(
            partition.clone(),
            vec![Event::new("user_msg", b"after".to_vec())],
        )
        .await
        .expect("concurrent append");

        assert_eq!(
            host.apply_repair_partition(partition.clone(), stale.before, stale.after, None)
                .await
                .expect("conditioned apply"),
            RepairApplication::Changed
        );
        assert_eq!(
            host.replay_verified(partition)
                .await
                .expect("changed partition remains intact")
                .iter()
                .filter(|event| event.kind == "user_msg")
                .count(),
            2
        );

        drop(host);
        let _ = std::fs::remove_dir_all(dir);
    }

    // Kept as one narrative because the same durable stage must cross all
    // three failure boundaries; splitting it would silently replace the
    // restart proof with three independent fixtures.
    #[allow(clippy::too_many_lines)]
    #[test]
    fn repair_resumes_from_staged_survivors_after_restore_fails() {
        use commonware_runtime::{Runner as _, tokio as cw_tokio};

        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-repair-stage-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let partition = "conv-repair-stage".to_owned();
        let run_dir = dir.clone();
        let runner =
            cw_tokio::Runner::new(cw_tokio::Config::default().with_storage_directory(dir.clone()));
        runner.start(move |context| async move {
            let mut logs = super::OpenLogs::new();
            let mut checkpoints = HashMap::new();
            let mut count_checkpoints = super::CountCheckpoints::new();
            let mut mmr_logs = HashMap::new();
            let signer = polyc_crypto::signing_role::JournalAttestationSigner::from_seed(7);
            let trust = polyc_crypto::signing_role::RoleTrustSet::current(&signer);
            let original = [
                Event::new("user_msg", b"survivor".to_vec()),
                Event::new("broken", b"quarantine".to_vec()),
            ];
            {
                let log = logs.get_or_open(&context, &partition).await.unwrap();
                for event in &original {
                    log.append(event).await.unwrap();
                }
                log.commit().await.unwrap();
            }
            count_checkpoints
                .record(&context, &partition, 2)
                .await
                .unwrap();

            let inspected = super::inspect_repair_one(
                &context,
                &mut logs,
                &mut count_checkpoints,
                &signer,
                &trust,
                &partition,
                None,
            )
            .await
            .unwrap();
            let survivor = inspected.readable[0].clone();
            // `after` promises what the repair actually leaves on disk, which
            // since `#2322` is the re-rooted content: the survivor plus one
            // fresh signed root over it.
            let (restored_content, _) =
                super::repaired_content(std::slice::from_ref(&survivor.1), &signer, None)
                    .expect("re-root");
            let indexed: Vec<(u64, Event)> = restored_content
                .iter()
                .enumerate()
                .map(|(position, event)| (position as u64, event.clone()))
                .collect();
            let after = super::repair_fingerprint(&indexed, &[], restored_content.len() as u64);
            let scan = super::RepairScan {
                readable: vec![survivor],
                quarantined: vec![polyc_eventlog::QuarantinedItem {
                    position: 1,
                    error: "injected unreadable frame".to_owned(),
                }],
                before: inspected.before,
                after,
                standing: inspected.standing,
            };

            // A partial survivor stage never permits target destruction. Its
            // missing sentinel makes the next attempt discard and rebuild it.
            let stage = super::repair_stage_partition(&partition, &inspected.before);
            arm_append_failure(&stage, 1);
            super::apply_repair_scan(
                &context,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &partition,
                scan.clone(),
                None,
            )
            .await
            .expect_err("the armed staging failure surfaces");
            assert_eq!(
                logs.get_or_open(&context, &partition)
                    .await
                    .unwrap()
                    .replay()
                    .await
                    .unwrap(),
                original,
                "a stage without its sentinel cannot authorize target destruction"
            );

            // Fail the first survivor append after the target has been
            // destroyed. The stage must remain complete and private.
            arm_append_failure(&partition, 0);
            super::apply_repair_scan(
                &context,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &partition,
                scan,
                None,
            )
            .await
            .expect_err("the armed restore failure surfaces");
            assert!(
                super::list_partitions_in(&run_dir)
                    .unwrap()
                    .iter()
                    .all(|name| !name.starts_with(super::REPAIR_STAGE_PREFIX)),
                "repair staging is never a caller-visible partition"
            );

            // New caches model a process restart. The target is empty or
            // partial, but the durable stage is sufficient to finish exactly
            // the inspected rewrite.
            logs = super::OpenLogs::new();
            checkpoints.clear();
            count_checkpoints.evict_all();
            mmr_logs.clear();
            let (application, _) = super::apply_repair_conditionally(
                &context,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &trust,
                &partition,
                super::RepairFingerprints {
                    before: inspected.before,
                    after,
                },
                None,
            )
            .await
            .expect("restart resumes from the durable stage");
            assert_eq!(application, RepairApplication::Applied);
            let restored = logs
                .get_or_open(&context, &partition)
                .await
                .unwrap()
                .replay()
                .await
                .unwrap();
            assert_eq!(
                restored, restored_content,
                "a resumed repair restores the re-rooted content, marker included"
            );
            assert_eq!(
                restored.len(),
                2,
                "one survivor plus exactly one fresh signed root"
            );
            assert_eq!(restored[0], original[0]);
            assert_eq!(restored[1].kind, polyc_eventlog::MMR_SIGNED_ROOT_KIND);
            assert!(
                super::list_partitions_in(&run_dir)
                    .unwrap()
                    .iter()
                    .all(|name| !name.starts_with(super::REPAIR_STAGE_PREFIX)),
                "the completed repair removes its private stage"
            );
        });

        let _ = std::fs::remove_dir_all(dir);
    }

    /// One decision drives inspection, the durable plan, and application.
    ///
    /// The premise is the shape that broke: a stale root with NOTHING to
    /// quarantine. Inspection must apply the replacement before it computes
    /// the `after` it promises, the plan must record that the repair rewrites,
    /// and application must apply the same replacement so it produces exactly
    /// that `after`.
    ///
    /// This runs the real dispatch for both halves, so a second formula is
    /// observable, and the assertion that catches it depends on the direction.
    /// If application stops applying the replacement, it cannot produce the
    /// `after` inspection promised and the conditioned apply reports
    /// [`RepairApplication::Changed`]. If inspection stops applying it while
    /// application still does, `before` still matches and the apply succeeds,
    /// so the rotation and settlement assertions below are what fail. Either
    /// way the case fails. The hand-built `RepairScan` truth table cannot see
    /// either direction: it never runs inspection.
    #[test]
    #[allow(clippy::too_many_lines)]
    fn one_decision_drives_inspection_the_plan_and_application() {
        use commonware_runtime::{Runner as _, tokio as cw_tokio};

        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-one-decision-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let run_dir = dir.clone();
        let runner =
            cw_tokio::Runner::new(cw_tokio::Config::default().with_storage_directory(dir.clone()));
        runner.start(move |context| async move {
            let mut logs = super::OpenLogs::new();
            let mut checkpoints = HashMap::new();
            let mut count_checkpoints = super::CountCheckpoints::new();
            let mut mmr_logs = HashMap::new();
            let signer = polyc_crypto::signing_role::JournalAttestationSigner::from_seed(7);
            let trust = polyc_crypto::signing_role::RoleTrustSet::current(&signer);
            let observers = super::observer::WriteObservers::new();
            let partition = "conv-one-decision";

            // A lineage marker the replacement rewrites, plus one ordinary
            // event. The root is signed over three leaves but only two are
            // written, so the root is stale with nothing unreadable.
            let content = [
                Event::new("journal_lineage", b"old-incarnation".to_vec()),
                Event::new("user_msg", b"one".to_vec()),
                Event::new("output_msg", b"two".to_vec()),
            ];
            let marker = polyc_eventlog::extend_and_sign(
                &polyc_mmr::VerifiableLog::new(),
                &content,
                &signer,
            )
            .expect("sign over three leaves");
            {
                let log = logs.get_or_open(&context, partition).await.unwrap();
                for event in [&content[0], &content[1], &marker] {
                    log.append(event).await.unwrap();
                }
                log.commit().await.unwrap();
            }
            count_checkpoints
                .record(&context, partition, 3)
                .await
                .unwrap();

            let replacement =
                super::RepairEventReplacement::new("journal_lineage", b"new-incarnation".to_vec());

            let (ack, ack_rx) = tokio::sync::oneshot::channel();
            super::handle_command(
                &context,
                &run_dir,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &trust,
                &[],
                &observers,
                super::Command::InspectRepair {
                    partition: super::PartitionRef::new(partition).expect("a storable name"),
                    replacement: Some(replacement.clone()),
                    ack,
                },
            )
            .await;
            let plan = ack_rx.await.expect("the arm acks").expect("inspectable");

            assert!(
                plan.quarantined.is_empty(),
                "the premise is a stale root with nothing unreadable: {:?}",
                plan.quarantined
            );
            assert!(
                plan.will_rewrite,
                "a stale root re-roots, so the durable plan must record a rewrite even with an \
                 empty quarantine list"
            );

            let (ack, ack_rx) = tokio::sync::oneshot::channel();
            super::handle_command(
                &context,
                &run_dir,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &trust,
                &[],
                &observers,
                super::Command::ApplyRepair {
                    partition: super::PartitionRef::new(partition).expect("a storable name"),
                    before: plan.before,
                    after: plan.after,
                    replacement: Some(replacement.clone()),
                    ack,
                },
            )
            .await;
            assert_eq!(
                ack_rx.await.expect("the arm acks").expect("appliable"),
                super::RepairApplication::Applied,
                "application must produce exactly the `after` inspection promised. `Changed` here \
                 means the two phases decided the rewrite differently"
            );

            let restored = super::replay_verified_one(
                &context,
                &mut logs,
                &mut count_checkpoints,
                &trust,
                partition,
            )
            .await
            .expect("the repaired partition verifies");
            let lineages: Vec<Vec<u8>> = restored
                .iter()
                .filter(|event| event.kind == "journal_lineage")
                .map(|event| event.payload.clone())
                .collect();
            assert_eq!(
                lineages,
                vec![b"new-incarnation".to_vec()],
                "the replacement applies exactly once, so the partition carries the rotated \
                 lineage and not the old one"
            );

            let (ack, ack_rx) = tokio::sync::oneshot::channel();
            super::handle_command(
                &context,
                &run_dir,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &trust,
                &[],
                &observers,
                super::Command::RepairSettled {
                    partition: super::PartitionRef::new(partition).expect("a storable name"),
                    before: plan.before,
                    after: plan.after,
                    ack,
                },
            )
            .await;
            assert!(
                ack_rx.await.expect("the arm acks").expect("settled reads"),
                "the destructive half is complete, so the repair reads as settled"
            );
        });
        let _ = std::fs::remove_dir_all(&dir);
    }
    /// `#2561`: a partition already carrying a stale signed root is repairable,
    /// and repair leaves it verifying.
    ///
    /// This is the state the pre-`#2559` repair left behind: the survivors and
    /// their old roots, so each root attests more leaves than precede it. The
    /// content decodes cleanly, so `replay_quarantining` reports nothing, and
    /// `apply_repair_scan` used to return before re-rooting anything. An
    /// operator re-running the verb got a no-op every time.
    ///
    /// The other two partitions here are the guard rails. A healthy one must
    /// stay untouched — `repaired_content` collapses every root into one, so a
    /// trigger built on "what is on disk differs from what a repair would
    /// leave" is true of every multi-batch partition and would rewrite the
    /// whole fleet. A tampered one must be refused — the same change that lets
    /// repair run on a root mismatch is what would let it sign one.
    #[test]
    #[allow(clippy::too_many_lines)]
    fn repair_re_roots_a_stale_root_leaves_a_healthy_partition_alone_and_refuses_a_tampered_one() {
        use commonware_runtime::{Runner as _, tokio as cw_tokio};

        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-stale-root-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let run_dir = dir.clone();
        let runner =
            cw_tokio::Runner::new(cw_tokio::Config::default().with_storage_directory(dir.clone()));
        runner.start(move |context| async move {
            let mut logs = super::OpenLogs::new();
            let mut checkpoints = HashMap::new();
            let mut count_checkpoints = super::CountCheckpoints::new();
            let mut mmr_logs = HashMap::new();
            let signer = polyc_crypto::signing_role::JournalAttestationSigner::from_seed(3);
            let trust = polyc_crypto::signing_role::RoleTrustSet::current(&signer);

            // One root over three leaves, then only two of them written. That
            // is exactly what a repair that dropped a leaf and kept the root
            // leaves on disk.
            let content = [
                Event::new("user_msg", b"one".to_vec()),
                Event::new("output_msg", b"two".to_vec()),
                Event::new("output_msg", b"three".to_vec()),
            ];
            let marker = polyc_eventlog::extend_and_sign(
                &polyc_mmr::VerifiableLog::new(),
                &content,
                &signer,
            )
            .expect("sign over three leaves");

            let seed = async |logs: &mut super::OpenLogs<_>,
                              count_checkpoints: &mut super::CountCheckpoints<_>,
                              partition: &str,
                              events: &[Event]| {
                {
                    let log = logs.get_or_open(&context, partition).await.unwrap();
                    for event in events {
                        log.append(event).await.unwrap();
                    }
                    log.commit().await.unwrap();
                }
                count_checkpoints
                    .record(&context, partition, events.len() as u64)
                    .await
                    .unwrap();
            };

            let stale = "conv-stale-root";
            seed(
                &mut logs,
                &mut count_checkpoints,
                stale,
                &[content[0].clone(), content[1].clone(), marker.clone()],
            )
            .await;
            super::replay_verified_one(&context, &mut logs, &mut count_checkpoints, &trust, stale)
                .await
                .expect_err("the seeded partition does not verify — that is the premise");

            // Through `handle_command`, not `repair_one`, and that is the
            // point. The epoch bump and the `Repaired` notification live in
            // the dispatch arm, and both used to key on a non-empty quarantine
            // list — which a stale-root repair never produces even though it
            // destroys and rewrites the partition. A test that stopped at
            // `repair_one` would pass over a cache still serving the
            // pre-repair decode.
            let observers = super::observer::WriteObservers::new();
            let recorder =
                std::sync::Arc::new(super::observer::tests::RecordingObserver::default());
            observers.register(recorder.clone());
            assert_eq!(observers.epoch(stale), 0);
            let (ack, ack_rx) = tokio::sync::oneshot::channel();
            super::handle_command(
                &context,
                &run_dir,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &trust,
                &[],
                &observers,
                super::Command::RepairPartition {
                    partition: super::PartitionRef::new(stale).expect("a storable name"),
                    ack,
                },
            )
            .await;
            let quarantined = ack_rx.await.expect("the arm acks").expect("repairable");
            assert!(
                quarantined.is_empty(),
                "nothing was unreadable, so nothing is dropped: {quarantined:?}"
            );
            assert_eq!(
                observers.epoch(stale),
                1,
                "a repair that only re-roots still changed the partition, so every cache keyed \
                 on this epoch must be invalidated"
            );
            let notified = recorder
                .mutations
                .lock()
                .expect("poison")
                .iter()
                .map(|mutation| mutation.1.clone())
                .collect::<Vec<_>>();
            assert_eq!(
                notified,
                vec![super::MutationKind::Repaired { quarantined: 0 }],
                "one notification for the re-root, and it reports nothing dropped"
            );
            let repaired = super::replay_verified_one(
                &context,
                &mut logs,
                &mut count_checkpoints,
                &trust,
                stale,
            )
            .await
            .expect("the repaired partition verifies");
            assert_eq!(
                repaired
                    .iter()
                    .filter(|event| event.kind != polyc_eventlog::MMR_SIGNED_ROOT_KIND)
                    .count(),
                2,
                "re-rooting keeps every readable event"
            );

            // A healthy partition, two batches, so its on-disk roots and the
            // single root a repair would write are different by construction.
            let healthy = "conv-healthy";
            let first = [Event::new("user_msg", b"a".to_vec())];
            let first_marker = super::append_batch_one(
                &context,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                healthy,
                &first,
            )
            .await
            .expect("first batch");
            let _ = first_marker;
            super::append_batch_one(
                &context,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                healthy,
                &[Event::new("output_msg", b"b".to_vec())],
            )
            .await
            .expect("second batch");
            let before = logs
                .get_or_open(&context, healthy)
                .await
                .unwrap()
                .replay()
                .await
                .unwrap();
            assert_eq!(
                before
                    .iter()
                    .filter(|event| event.kind == polyc_eventlog::MMR_SIGNED_ROOT_KIND)
                    .count(),
                2,
                "two batches, two roots — the state a naive trigger would rewrite"
            );
            // Through the dispatch arm too, and asserting the NEGATIVE. A test
            // that only pinned the bump would still pass if the arm bumped
            // unconditionally, which would invalidate every cache on every
            // repair of a sound partition.
            let (healthy_ack, healthy_rx) = tokio::sync::oneshot::channel();
            super::handle_command(
                &context,
                &run_dir,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &trust,
                &[],
                &observers,
                super::Command::RepairPartition {
                    partition: super::PartitionRef::new(healthy).expect("a storable name"),
                    ack: healthy_ack,
                },
            )
            .await;
            healthy_rx
                .await
                .expect("the arm acks")
                .expect("a healthy partition repairs to a no-op");
            assert_eq!(
                observers.epoch(healthy),
                0,
                "a repair that changed nothing must not invalidate a single cache"
            );
            assert_eq!(
                logs.get_or_open(&context, healthy)
                    .await
                    .unwrap()
                    .replay()
                    .await
                    .unwrap(),
                before,
                "a healthy partition is left byte-identical"
            );

            // Every leaf the root claims is present, and one of them changed.
            let tampered = "conv-tampered";
            let mut altered = content[0].clone();
            altered.payload[0] ^= 0xFF;
            let pair = [content[0].clone(), content[1].clone()];
            let pair_marker =
                polyc_eventlog::extend_and_sign(&polyc_mmr::VerifiableLog::new(), &pair, &signer)
                    .expect("sign over two leaves");
            seed(
                &mut logs,
                &mut count_checkpoints,
                tampered,
                &[altered, content[1].clone(), pair_marker],
            )
            .await;
            super::repair_one(
                &context,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &trust,
                tampered,
            )
            .await
            .expect_err("repair must not re-sign content a trusted root contradicts");
        });

        let _ = std::fs::remove_dir_all(dir);
    }

    /// A destroy that fails still leaves the floor cleared.
    ///
    /// This is the ordering `repair_settled_one` rests on. A cleared floor is
    /// how a later reader knows a partition's content was deliberately taken
    /// away rather than lost, and a repair inside its destructive window is
    /// exactly that state. Clear the floor after the destroy instead, and a
    /// destroy that faults part-way leaves a fragment beside a floor that
    /// still describes the whole partition — so nothing on disk says which of
    /// the two happened, and the settlement probe has to guess from content.
    /// Three attempts to guess from content each got a different population
    /// wrong, which is why this order is load-bearing rather than tidy.
    ///
    /// Clearing early is safe on its own: a floor of zero asserts no minimum,
    /// so it can never turn a healthy partition into a reported truncation.
    #[test]
    fn a_destroy_that_fails_still_records_that_it_started() {
        use commonware_runtime::{Runner as _, tokio as cw_tokio};

        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-destroy-order-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let runner =
            cw_tokio::Runner::new(cw_tokio::Config::default().with_storage_directory(dir.clone()));
        runner.start(move |context| async move {
            let mut logs = super::OpenLogs::new();
            let mut checkpoints = HashMap::new();
            let mut count_checkpoints = super::CountCheckpoints::new();
            let mut mmr_logs = HashMap::new();
            let partition = "conv-destroy-order";

            {
                let log = logs.get_or_open(&context, partition).await.unwrap();
                log.append(&Event::new("user_msg", b"content".to_vec()))
                    .await
                    .unwrap();
                log.commit().await.unwrap();
            }
            count_checkpoints
                .record(&context, partition, 1)
                .await
                .unwrap();

            super::tests::arm_destroy_failure(partition);
            let outcome = super::destroy_one(
                &context,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                partition,
                super::DestroyCheckpoint::Clear,
            )
            .await;
            assert!(outcome.is_err(), "the armed destroy failure surfaces");

            assert_eq!(
                count_checkpoints
                    .expected_count(&context, partition)
                    .await
                    .unwrap(),
                0,
                "the floor is cleared before anything is removed, so a destroy that failed \
                 part-way still says it started"
            );
            assert!(
                super::repair_window_is_open(&context, &mut count_checkpoints, partition)
                    .await
                    .unwrap(),
                "and a settlement probe reads that record rather than guessing from content"
            );
        });

        let _ = std::fs::remove_dir_all(dir);
    }

    /// The floor decides the window, and no arrangement of content forges it.
    ///
    /// Three shape tests came before this one and each lost a different
    /// population. A destroy that faults part-way leaves a readable suffix of
    /// the old content. A restore that faults leaves a prefix with holes. A
    /// partition a later repair or excision rewrote holds its own content at
    /// its own positions. The first two must resume. The third must never be
    /// resumed over. All three look alike from the bytes.
    ///
    /// So the window is read from the floor, which somebody recorded.
    #[test]
    fn only_the_recorded_floor_decides_whether_a_repair_is_still_in_its_window() {
        use commonware_runtime::{Runner as _, tokio as cw_tokio};

        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-window-floor-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let runner =
            cw_tokio::Runner::new(cw_tokio::Config::default().with_storage_directory(dir.clone()));
        runner.start(move |context| async move {
            let mut count_checkpoints = super::CountCheckpoints::new();
            let partition = "conv-window-floor";

            // A partition nobody destroyed: the window is shut.
            count_checkpoints
                .record(&context, partition, 7)
                .await
                .unwrap();
            assert!(
                !super::repair_window_is_open(&context, &mut count_checkpoints, partition)
                    .await
                    .unwrap(),
                "a recorded floor is a record that content is present"
            );

            // `destroy_one` clears the floor BEFORE it removes anything, so
            // this is what every state inside the window reads — whether the
            // destroy finished or faulted part-way through.
            count_checkpoints.clear(&context, partition).await.unwrap();
            assert!(
                super::repair_window_is_open(&context, &mut count_checkpoints, partition)
                    .await
                    .unwrap(),
                "a cleared floor is the destroy's own record that content was taken away"
            );

            // The terminal count record is what shuts it again.
            count_checkpoints
                .record(&context, partition, 2)
                .await
                .unwrap();
            assert!(
                !super::repair_window_is_open(&context, &mut count_checkpoints, partition)
                    .await
                    .unwrap(),
                "the terminal record closes the window"
            );
        });

        let _ = std::fs::remove_dir_all(dir);
    }

    /// The erasure sweep removes a planted stage, and asking twice is safe.
    ///
    /// A stage holds a full copy of a conversation. Its cleanup runs after the
    /// repair is already durable, so a crash or a storage failure there leaves
    /// the copy behind — and an erasure that removed only the named partition
    /// would report itself complete with every erased event still on the
    /// volume.
    ///
    /// The second call is not padding. A destruction is retried, and a sweep
    /// that errored or CREATED a stage on the retry would turn the erasure's
    /// own idempotence into a failure or into fresh storage.
    #[test]
    #[allow(clippy::too_many_lines)]
    fn the_erasure_sweep_removes_a_stage_and_is_safe_to_repeat() {
        use commonware_runtime::{Runner as _, tokio as cw_tokio};

        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-sweep-stage-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let partition = "conv-sweep-stage".to_owned();
        let run_dir = dir.clone();
        let runner =
            cw_tokio::Runner::new(cw_tokio::Config::default().with_storage_directory(dir.clone()));
        runner.start(move |context| async move {
            let mut logs = super::OpenLogs::new();
            let mut checkpoints = HashMap::new();
            let mut count_checkpoints = super::CountCheckpoints::new();
            let mut mmr_logs = HashMap::new();
            let signer = polyc_crypto::signing_role::JournalAttestationSigner::from_seed(31);
            let trust = polyc_crypto::signing_role::RoleTrustSet::current(&signer);
            let observers = super::observer::WriteObservers::new();
            let before = [9_u8; 32];
            let after = [11_u8; 32];
            let stage = super::repair_stage_partition(&partition, &before);
            let other = super::repair_stage_partition(&partition, &[7_u8; 32]);

            let staged = vec![
                Event::new("user_msg", b"private".to_vec()),
                super::repair_stage_complete(before, after, 1),
            ];
            super::append_repair_copy(&context, &mut logs, &stage, &staged)
                .await
                .expect("plant the stage");
            super::append_repair_copy(&context, &mut logs, &other, &staged)
                .await
                .expect("plant a second repair's stage");
            assert!(
                super::partition_data_dir_exists(&run_dir, &stage).unwrap(),
                "the planted stage is on the volume for this test to mean anything"
            );

            macro_rules! sweep {
                () => {{
                    let (ack, ack_rx) = tokio::sync::oneshot::channel();
                    super::handle_command(
                        &context,
                        &run_dir,
                        &mut logs,
                        &mut checkpoints,
                        &mut count_checkpoints,
                        &mut mmr_logs,
                        &signer,
                        &trust,
                        &[],
                        &observers,
                        super::Command::DestroyRepairStage {
                            partition: super::PartitionRef::new(&partition)
                                .expect("a storable name"),
                            before,
                            ack,
                        },
                    )
                    .await;
                    ack_rx.await.expect("the arm acks")
                }};
            }

            sweep!().expect("the sweep runs");
            assert!(
                !super::partition_data_dir_exists(&run_dir, &stage).unwrap(),
                "the erased conversation's staged copy is gone from the volume"
            );

            sweep!().expect("a repeated sweep is not an error");
            assert!(
                !super::partition_data_dir_exists(&run_dir, &stage).unwrap(),
                "and it does not create the stage it was asked to remove"
            );

            assert!(
                super::partition_data_dir_exists(&run_dir, &other).unwrap(),
                "a sweep removes the stage it names and no other"
            );

            // The rewrite twin. An excision stages its survivors the same way
            // and its cleanup can leak the same way, so an erasure has to
            // remove both kinds or it is not an erasure.
            let rewrite = super::rewrite_stage_partition(&partition, "cmd-excise");
            super::append_repair_copy(&context, &mut logs, &rewrite, &staged)
                .await
                .expect("plant an excision's stage");
            let (ack, ack_rx) = tokio::sync::oneshot::channel();
            super::handle_command(
                &context,
                &run_dir,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &trust,
                &[],
                &observers,
                super::Command::DestroyRewriteStage {
                    partition: super::PartitionRef::new(&partition).expect("a storable name"),
                    command_id: "cmd-excise".to_owned(),
                    ack,
                },
            )
            .await;
            ack_rx
                .await
                .expect("the arm acks")
                .expect("the rewrite sweep runs");
            assert!(
                !super::partition_data_dir_exists(&run_dir, &rewrite).unwrap(),
                "an excision's staged copy is gone from the volume too"
            );
        });

        let _ = std::fs::remove_dir_all(dir);
    }

    /// A survivor stage that outlives its own repair must never take a whole
    /// partition offline, and must never be replayed over one that moved on.
    ///
    /// The stage is destroyed AFTER the terminal count record, so a crash or a
    /// failed cleanup in that window leaves a complete stage beside a partition
    /// that is already repaired. The partition then takes new commits, and both
    /// fingerprints stop matching. Every test built on the fingerprints alone
    /// reads that as an interrupted repair.
    ///
    /// Two things would follow, and the second is worse. The settlement probe
    /// would refuse a healthy partition on every cold load, for good. And the
    /// runbook sends the operator to retry the repair, which would restore the
    /// staged survivors over the grown partition — destroying events that were
    /// committed, receipted and acknowledged, on instruction.
    #[test]
    #[allow(clippy::too_many_lines)]
    fn a_stage_that_outlived_its_repair_neither_refuses_nor_rolls_back_the_partition() {
        use commonware_runtime::{Runner as _, tokio as cw_tokio};

        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-stale-stage-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let partition = "conv-stale-stage".to_owned();
        let run_dir = dir.clone();
        let runner =
            cw_tokio::Runner::new(cw_tokio::Config::default().with_storage_directory(dir.clone()));
        runner.start(move |context| async move {
            let mut logs = super::OpenLogs::new();
            let mut checkpoints = HashMap::new();
            let mut count_checkpoints = super::CountCheckpoints::new();
            let mut mmr_logs = HashMap::new();
            let signer = polyc_crypto::signing_role::JournalAttestationSigner::from_seed(17);
            let trust = polyc_crypto::signing_role::RoleTrustSet::current(&signer);

            let original = [
                Event::new("user_msg", b"survivor".to_vec()),
                Event::new("broken", b"quarantine".to_vec()),
            ];
            {
                let log = logs.get_or_open(&context, &partition).await.unwrap();
                for event in &original {
                    log.append(event).await.unwrap();
                }
                log.commit().await.unwrap();
            }
            count_checkpoints
                .record(&context, &partition, 2)
                .await
                .unwrap();

            let inspected = super::inspect_repair_one(
                &context,
                &mut logs,
                &mut count_checkpoints,
                &signer,
                &trust,
                &partition,
                None,
            )
            .await
            .unwrap();
            let survivor = inspected.readable[0].clone();
            let (restored_content, _) =
                super::repaired_content(std::slice::from_ref(&survivor.1), &signer, None)
                    .expect("re-root");
            let indexed: Vec<(u64, Event)> = restored_content
                .iter()
                .enumerate()
                .map(|(position, event)| (position as u64, event.clone()))
                .collect();
            let after = super::repair_fingerprint(&indexed, &[], restored_content.len() as u64);
            let fingerprints = super::RepairFingerprints {
                before: inspected.before,
                after,
            };

            // Run the repair to completion, then put its stage back. That is
            // the state a crash between the terminal count record and the
            // stage cleanup leaves.
            super::apply_repair_scan(
                &context,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &partition,
                super::RepairScan {
                    readable: vec![survivor],
                    quarantined: vec![polyc_eventlog::QuarantinedItem {
                        position: 1,
                        error: "injected unreadable frame".to_owned(),
                    }],
                    before: inspected.before,
                    after,
                    standing: inspected.standing,
                },
                None,
            )
            .await
            .expect("the repair completes");
            let stage = super::repair_stage_partition(&partition, &inspected.before);
            let mut staged = restored_content.clone();
            staged.push(super::repair_stage_complete(
                inspected.before,
                after,
                restored_content.len() as u64,
            ));
            super::append_repair_copy(&context, &mut logs, &stage, &staged)
                .await
                .expect("the stage is put back exactly as the repair wrote it");

            // While the partition still matches what the repair promised, the
            // stale stage is harmless and the probe already said so.
            assert!(
                super::repair_settled_one(
                    &context,
                    &run_dir,
                    &mut logs,
                    &mut count_checkpoints,
                    &signer,
                    &trust,
                    &partition,
                    fingerprints,
                )
                .await
                .expect("probe"),
                "a repaired partition is settled even with its stage still on disk"
            );

            // The partition is healthy, so it keeps taking commits. Now neither
            // fingerprint matches and only the window test can tell this from
            // an interrupted repair.
            super::append_batch_one(
                &context,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &partition,
                &[Event::new("user_msg", b"after the repair".to_vec())],
            )
            .await
            .expect("a repaired partition takes new commits");
            let grown = logs
                .get_or_open(&context, &partition)
                .await
                .unwrap()
                .replay()
                .await
                .unwrap();

            assert!(
                super::repair_settled_one(
                    &context,
                    &run_dir,
                    &mut logs,
                    &mut count_checkpoints,
                    &signer,
                    &trust,
                    &partition,
                    fingerprints,
                )
                .await
                .expect("probe"),
                "a partition that grew past its repair is settled, stale stage or not — \
                 refusing it would take a healthy conversation offline for good"
            );

            // And the remedy the runbook prescribes must not roll it back.
            let (application, _) = super::apply_repair_conditionally(
                &context,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &trust,
                &partition,
                fingerprints,
                None,
            )
            .await
            .expect("the retry answers rather than failing");
            assert_eq!(
                application,
                RepairApplication::Changed,
                "the partition moved on, so the retry reports that rather than resuming"
            );
            assert_eq!(
                logs.get_or_open(&context, &partition)
                    .await
                    .unwrap()
                    .replay()
                    .await
                    .unwrap(),
                grown,
                "every committed event survives the retry"
            );

            // And once a LATER repair rewrites the partition, the stale stage
            // still decides nothing. This is the shape every content test got
            // wrong: a second repair rebuilds from position zero and collapses
            // the roots, so the partition stops resembling the stage in any
            // way a shape test could read — while being perfectly healthy.
            //
            // The floor is lowered first so the second repair has something to
            // do. Without that the partition verifies clean, `repair_one`
            // early-returns, and this block would assert over a partition
            // nothing touched — which is how the previous version of this test
            // passed under the predicate it was written to reject.
            count_checkpoints
                .record(&context, &partition, grown.len() as u64 + 2)
                .await
                .unwrap();
            let second = super::repair_one(
                &context,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &trust,
                &partition,
            )
            .await
            .expect("a second repair runs on a healthy partition");
            assert!(
                second.rewrote,
                "this block is only meaningful if the second repair actually rewrote the \
                 partition: {second:?}"
            );
            let rewritten = logs
                .get_or_open(&context, &partition)
                .await
                .unwrap()
                .replay()
                .await
                .unwrap();

            assert!(
                super::repair_settled_one(
                    &context,
                    &run_dir,
                    &mut logs,
                    &mut count_checkpoints,
                    &signer,
                    &trust,
                    &partition,
                    fingerprints,
                )
                .await
                .expect("probe"),
                "a partition a later repair rewrote is settled — the first repair's stage \
                 describes none of it"
            );
            let (application, _) = super::apply_repair_conditionally(
                &context,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &trust,
                &partition,
                fingerprints,
                None,
            )
            .await
            .expect("the retry answers rather than failing");
            assert_eq!(
                application,
                RepairApplication::Changed,
                "the first repair's stage must not be restored over a later repair's work"
            );
            assert_eq!(
                logs.get_or_open(&context, &partition)
                    .await
                    .unwrap()
                    .replay()
                    .await
                    .unwrap(),
                rewritten,
                "the later repair's content survives the stale stage's retry"
            );
        });

        let _ = std::fs::remove_dir_all(dir);
    }

    /// The durable half of `#2568`: a repair that crossed its destructive
    /// boundary and did not come back must be distinguishable from a healthy
    /// partition, and the distinction must survive the partition growing.
    ///
    /// State asks this question on every read of a partition that carries an
    /// unfinished repair intent. So the probe has to be right in four places,
    /// and this walks all four in one narrative because they are four points
    /// on ONE partition's life. Splitting them would let each fixture start
    /// from a state the previous step never actually produced.
    #[test]
    #[allow(clippy::too_many_lines)]
    fn a_repair_that_crossed_its_destructive_boundary_reads_as_unsettled() {
        use commonware_runtime::{Runner as _, tokio as cw_tokio};

        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-repair-settled-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let partition = "conv-repair-settled".to_owned();
        let run_dir = dir.clone();
        let runner =
            cw_tokio::Runner::new(cw_tokio::Config::default().with_storage_directory(dir.clone()));
        runner.start(move |context| async move {
            let mut logs = super::OpenLogs::new();
            let mut checkpoints = HashMap::new();
            let mut count_checkpoints = super::CountCheckpoints::new();
            let mut mmr_logs = HashMap::new();
            let signer = polyc_crypto::signing_role::JournalAttestationSigner::from_seed(11);
            let trust = polyc_crypto::signing_role::RoleTrustSet::current(&signer);
            let original = [
                Event::new("user_msg", b"survivor".to_vec()),
                Event::new("broken", b"quarantine".to_vec()),
            ];
            {
                let log = logs.get_or_open(&context, &partition).await.unwrap();
                for event in &original {
                    log.append(event).await.unwrap();
                }
                log.commit().await.unwrap();
            }
            count_checkpoints
                .record(&context, &partition, 2)
                .await
                .unwrap();

            let inspected = super::inspect_repair_one(
                &context,
                &mut logs,
                &mut count_checkpoints,
                &signer,
                &trust,
                &partition,
                None,
            )
            .await
            .unwrap();
            let survivor = inspected.readable[0].clone();
            let (restored_content, _) =
                super::repaired_content(std::slice::from_ref(&survivor.1), &signer, None)
                    .expect("re-root");
            let indexed: Vec<(u64, Event)> = restored_content
                .iter()
                .enumerate()
                .map(|(position, event)| (position as u64, event.clone()))
                .collect();
            let after = super::repair_fingerprint(&indexed, &[], restored_content.len() as u64);
            let fingerprints = super::RepairFingerprints {
                before: inspected.before,
                after,
            };
            // A macro, not a closure: an async closure that borrows the caches
            // mutably cannot express the lifetime its future needs.
            macro_rules! settled {
                () => {
                    super::repair_settled_one(
                        &context,
                        &run_dir,
                        &mut logs,
                        &mut count_checkpoints,
                        &signer,
                        &trust,
                        &partition,
                        fingerprints,
                    )
                    .await
                    .expect("the probe reads the stage")
                };
            }

            // 1. An admitted repair that never touched the partition. There is
            //    no stage, so there is no window, and the content on disk is
            //    the content every reader already had. Refusing here would
            //    take a healthy partition offline for a crash that happened
            //    before anything was at risk.
            assert!(
                settled!(),
                "a repair that never staged anything leaves nothing to distrust"
            );

            // 1b. A complete stage over a target the destroy never reached.
            //     `apply_repair_scan` writes the stage BEFORE it destroys, so
            //     a crash between them leaves this. Every reader may still
            //     have the partition, and refusing it would take a readable
            //     conversation offline for a crash that risked nothing.
            {
                let scan = super::inspect_repair_one(
                    &context,
                    &mut logs,
                    &mut count_checkpoints,
                    &signer,
                    &trust,
                    &partition,
                    None,
                )
                .await
                .unwrap();
                assert_eq!(scan.before, fingerprints.before, "the target is untouched");
                let (restored, _) =
                    super::repaired_content(std::slice::from_ref(&original[0]), &signer, None)
                        .unwrap();
                let mut planted = restored.clone();
                planted.push(super::repair_stage_complete(
                    scan.before,
                    after,
                    restored.len() as u64,
                ));
                let stage = super::repair_stage_partition(&partition, &fingerprints.before);
                super::append_repair_copy(&context, &mut logs, &stage, &planted)
                    .await
                    .expect("plant a complete stage beside an untouched target");
            }
            assert!(
                settled!(),
                "a complete stage over an untouched target is not a window: the partition is \
                 byte-for-byte what every reader already had"
            );
            {
                let stage = super::repair_stage_partition(&partition, &fingerprints.before);
                super::destroy_one(
                    &context,
                    &mut logs,
                    &mut checkpoints,
                    &mut count_checkpoints,
                    &mut mmr_logs,
                    &stage,
                    super::DestroyCheckpoint::Clear,
                )
                .await
                .expect("clear the planted stage before the real run");
            }

            // 2. The window itself: the target is destroyed and the stage
            //    holds the survivors. Nothing on disk is what any reader
            //    expects, and the count floor cannot say so — the destroy
            //    zeroed it.
            let scan = super::RepairScan {
                readable: vec![survivor],
                quarantined: vec![polyc_eventlog::QuarantinedItem {
                    position: 1,
                    error: "injected unreadable frame".to_owned(),
                }],
                before: inspected.before,
                after,
                standing: inspected.standing,
            };
            arm_append_failure(&partition, 0);
            super::apply_repair_scan(
                &context,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &partition,
                scan,
                None,
            )
            .await
            .expect_err("the armed restore failure surfaces");
            // New caches model the process restart that follows the crash.
            logs = super::OpenLogs::new();
            checkpoints.clear();
            count_checkpoints.evict_all();
            mmr_logs.clear();
            assert_eq!(
                super::partition_event_count_one(&context, &run_dir, &mut logs, &partition)
                    .await
                    .unwrap(),
                0,
                "the interrupted repair leaves nothing readable — this is the state \
                 State used to serve as a legitimately empty conversation"
            );
            assert!(
                !settled!(),
                "a complete stage over a partition that does not match `after` is damage"
            );

            // 3. The repair finishes. The stage is gone and the partition
            //    holds exactly what the repair promised.
            let (application, _) = super::apply_repair_conditionally(
                &context,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &trust,
                &partition,
                fingerprints,
                None,
            )
            .await
            .expect("the resume finishes the repair from its stage");
            assert_eq!(application, RepairApplication::Applied);
            assert!(settled!(), "a finished repair is settled");

            // 4. The partition takes new commits. This is what a probe built
            //    on the count floor or on the `after` fingerprint alone gets
            //    wrong: both stop matching the moment the partition grows, so
            //    the next restart would refuse a healthy partition forever.
            //    The stage is the only signal that does not drift, because it
            //    is destroyed exactly when the window closes.
            super::append_batch_one(
                &context,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &partition,
                &[Event::new("user_msg", b"after the repair".to_vec())],
            )
            .await
            .expect("the repaired partition takes new commits");
            assert!(
                settled!(),
                "a partition that grew past its repair is still settled"
            );
        });

        let _ = std::fs::remove_dir_all(dir);
    }

    /// Corrupt one byte in a partition's ONLY (still-active, never-rolled)
    /// journal section and confirm the real `verify_conversation` path
    /// (`EventLogHost::replay_verified`, exactly what `ApprovalService`'s
    /// RPC handler calls) reports the failure rather than a false pass.
    ///
    /// Before the `#799` hardening this landed in, `commonware-storage`'s
    /// `variable::Journal` self-heals ANY decode failure in its active
    /// section the same way it self-heals a real torn write: on open it
    /// re-derives the section's item boundaries by re-parsing from byte
    /// zero, and silently rewinds on the first item it can't decode (see
    /// that crate's own `# Repair` docs on `variable::Journal`). For a small
    /// conversation where every event lives in section 0 (still active —
    /// `items_per_section` defaults to 1024), corrupting the VERY FIRST
    /// event wipes the whole section:
    /// `replay()` silently returns zero events, and unmodified
    /// `verify_replay` — "no signed roots at all verifies trivially" — would
    /// report `verified=true, event_count=0` over a genuinely 8-item
    /// (7 content events + 1 signed-root marker) conversation. This test
    /// pins that the durable event-count checkpoint (`polyc_eventlog::checkpoint`)
    /// now catches exactly this and hard-fails instead.
    #[tokio::test]
    #[allow(clippy::too_many_lines)]
    async fn active_section_kind_corruption_is_a_hard_verify_failure_not_a_false_pass() {
        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-active-corrupt-kind-{}",
            std::process::id()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let partition = "conv-corrupt-kind".to_owned();

        // Write a real 7-event conversation (all in section 0, still active)
        // through the real host/journal, exactly like production.
        {
            let shutdown = CancellationToken::new();
            let host = EventLogHost::spawn(
                dir.clone(),
                shutdown.clone(),
                polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
            )
            .expect("spawn");
            host.append_batch(
                partition.clone(),
                vec![
                    Event::new("user_msg", b"hello".to_vec()),
                    Event::new("output_msg", b"hi there".to_vec()),
                    Event::new("tool_call", b"lookup".to_vec()),
                    Event::new("output_msg", b"tool result".to_vec()),
                    Event::new("user_msg", b"thanks".to_vec()),
                    Event::new("output_msg", b"you're welcome".to_vec()),
                    Event::new("turn_complete", Vec::new()),
                ],
            )
            .await
            .expect("append 7-event turn");

            // Sanity: BEFORE corruption, this conversation genuinely verifies
            // (7 content events + 1 signed-root marker).
            let verified = host
                .replay_verified(partition.clone())
                .await
                .expect("uncorrupted conversation verifies");
            assert_eq!(verified.len(), 8, "7 content events + 1 signed-root marker");
            drop(host);
        }

        // Corrupt the FIRST byte of the first event's `kind` string
        // ("user_msg") in section 0's data file — a decode-breaking
        // corruption (0xFF is not a valid UTF-8 lead byte anywhere), located
        // by finding the known kind bytes rather than hand-computed offsets
        // so this test doesn't silently rot if the on-disk framing changes.
        let data_file = dir
            .join(format!("{partition}_data"))
            .join("0000000000000000");
        let mut bytes = std::fs::read(&data_file).expect("read section 0");
        let kind_at = bytes
            .windows(b"user_msg".len())
            .position(|w| w == b"user_msg")
            .expect("the first event's kind bytes are present on disk");
        bytes[kind_at] = 0xFF;
        std::fs::write(&data_file, &bytes).expect("write corrupted section 0");

        // Reopen (a fresh host, simulating a restart / a separate admin
        // process running `polychrome conversation verify`) and call the
        // REAL verify_conversation path.
        let shutdown2 = CancellationToken::new();
        let host2 = EventLogHost::spawn(
            dir.clone(),
            shutdown2,
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
        )
        .expect("reopen");

        let err = host2.replay_verified(partition.clone()).await.expect_err(
            "a truncated replay of already-committed data must never report verified=true",
        );
        let AppendError::Verify(verify_err) = err else {
            panic!("expected AppendError::Verify, got {err:?}");
        };
        match verify_err {
            super::VerifyError::TruncatedReplay { expected, actual } => {
                assert_eq!(expected, 8, "checkpoint recorded all 8 events as committed");
                assert_eq!(
                    actual, 0,
                    "the journal's self-heal wiped the whole (only) active section"
                );
            }
            other => panic!("expected TruncatedReplay, got {other:?}"),
        }

        // The `polychrome conversation repair` path must likewise stop
        // reporting an empty quarantine list over this: it cannot recover
        // WHICH byte was corrupted (the journal already erased that detail),
        // but it must flag that content is missing rather than staying silent.
        let plan = host2
            .inspect_repair_partition(partition.clone(), None)
            .await
            .expect("repair inspection completes");
        let quarantined = plan.quarantined.clone();
        assert_eq!(
            quarantined.len(),
            8,
            "repair must flag the full gap between the checkpoint and what's visible, not report nothing"
        );
        let positions: Vec<u64> = quarantined.iter().map(|q| q.position).collect();
        assert_eq!(positions, (0..8).collect::<Vec<_>>());
        assert_eq!(
            host2
                .apply_repair_partition(partition.clone(), plan.before, plan.after, None)
                .await
                .expect("repair apply completes"),
            RepairApplication::Applied
        );
        assert_eq!(
            host2
                .apply_repair_partition(partition.clone(), plan.before, plan.after, None)
                .await
                .expect("response-loss retry reconciles"),
            RepairApplication::AlreadyApplied
        );

        // After repair, the checkpoint is re-baselined to reality (0 — every
        // event in this partition was actually lost), so a follow-up verify
        // reports cleanly instead of re-flagging the same, already-surfaced gap.
        let reverified = host2
            .replay_verified(partition)
            .await
            .expect("post-repair verify judges the partition against its new, honest baseline");
        assert!(
            reverified.is_empty(),
            "everything was unrecoverable in this reproduction; repair's job is honesty, not magic"
        );

        drop(host2);
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// `#2323`: a rewrite that crashed after restoring, but before lowering the
    /// count, is healed rather than left reporting damage forever.
    ///
    /// This is the window the retained floor creates. The content is already
    /// correct and durable, but it is still measured against the pre-rewrite
    /// count, so every read reports a truncated replay. The stage is still
    /// there, because it is destroyed only once the count is lowered — so a
    /// resume finishes the job and the partition verifies again.
    ///
    /// Without healing this the fix would be worse than the defect: a correct
    /// partition that nothing can read.
    #[test]
    fn a_rewrite_that_crashed_before_lowering_the_count_is_healed() {
        use commonware_runtime::{Runner as _, tokio as cw_tokio};

        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-rewrite-count-window-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let partition = "conv-rewrite-count-window".to_owned();
        let command_id = "excise-count-window".to_owned();
        let run_dir = dir.clone();
        let runner =
            cw_tokio::Runner::new(cw_tokio::Config::default().with_storage_directory(dir.clone()));
        runner.start(move |context| async move {
            let mut logs = super::OpenLogs::new();
            let mut checkpoints = HashMap::new();
            let mut count_checkpoints = super::CountCheckpoints::new();
            let mut mmr_logs = HashMap::new();
            let signer = polyc_crypto::signing_role::JournalAttestationSigner::from_seed(29);
            let trust = polyc_crypto::signing_role::RoleTrustSet::current(&signer);

            // The state a crash in that window leaves: the restored content is
            // durable and correct, the stage still holds it, and the count is
            // still the pre-rewrite one.
            let survivors = vec![Event::new("user_msg", b"kept".to_vec())];
            let tree = polyc_eventlog::rebuild_from_events(&survivors).expect("tree");
            let root = polyc_eventlog::extend_and_sign(&tree, &[], &signer).expect("sign");
            let restored: Vec<Event> = survivors
                .iter()
                .cloned()
                .chain(std::iter::once(root))
                .collect();
            {
                let log = logs.get_or_open(&context, &partition).await.unwrap();
                for event in &restored {
                    log.append(event).await.unwrap();
                }
                log.commit().await.unwrap();
            }
            // The pre-rewrite floor: three events lived here before the drop.
            count_checkpoints
                .record(&context, &partition, 3)
                .await
                .unwrap();
            let stage = super::rewrite_stage_partition(&partition, &command_id);
            {
                let mut staged = restored.clone();
                staged.push(super::rewrite_stage_complete(restored.len() as u64, 1));
                let log = logs.get_or_open(&context, &stage).await.unwrap();
                for event in &staged {
                    log.append(event).await.unwrap();
                }
                log.commit().await.unwrap();
            }

            // The false positive: correct content, reported as damaged.
            logs = super::OpenLogs::new();
            count_checkpoints.evict_all();
            let before = super::replay_verified_one(
                &context,
                &mut logs,
                &mut count_checkpoints,
                &trust,
                &partition,
            )
            .await;
            assert!(
                matches!(before, Err(super::VerifyError::TruncatedReplay { .. })),
                "the retained floor reports this correct partition as damaged: {before:?}"
            );

            // The resume finishes the job the crash interrupted.
            let dropped = super::resume_rewrite(
                &context,
                &run_dir,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &partition,
                &stage,
            )
            .await
            .expect("the stage finishes")
            .expect("a stage was waiting");
            assert_eq!(dropped, 1);

            let verified = super::replay_verified_one(
                &context,
                &mut logs,
                &mut count_checkpoints,
                &trust,
                &partition,
            )
            .await
            .expect("the healed partition verifies");
            assert_eq!(
                verified, restored,
                "the content never changed, only the floor"
            );
        });
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// `#2323`: a DIFFERENT excision finishes one a crash left staged.
    ///
    /// The retention sweep derives its command identity from the content it is
    /// trimming, and a crash destroys that content — so the next sweep computes
    /// a different identity and would never retry the interrupted command. The
    /// recovery therefore cannot depend on the same identity coming back. This
    /// pins the host half: a resume asks only for the staged command, and it
    /// answers `None` once nothing is staged.
    #[allow(clippy::too_many_lines)]
    #[test]
    fn a_staged_rewrite_is_finishable_by_a_later_unrelated_caller() {
        use commonware_runtime::{Runner as _, tokio as cw_tokio};

        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-rewrite-foreign-resume-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let partition = "conv-rewrite-foreign".to_owned();
        let interrupted = "excise-interrupted".to_owned();
        let run_dir = dir.clone();
        let runner =
            cw_tokio::Runner::new(cw_tokio::Config::default().with_storage_directory(dir.clone()));
        runner.start(move |context| async move {
            let mut logs = super::OpenLogs::new();
            let mut checkpoints = HashMap::new();
            let mut count_checkpoints = super::CountCheckpoints::new();
            let mut mmr_logs = HashMap::new();
            let signer = polyc_crypto::signing_role::JournalAttestationSigner::from_seed(23);

            let content = vec![
                Event::new("user_msg", b"alpha".to_vec()),
                Event::new("secret", b"omega".to_vec()),
            ];
            let tree = polyc_eventlog::rebuild_from_events(&content).expect("tree");
            let root = polyc_eventlog::extend_and_sign(&tree, &[], &signer).expect("sign");
            {
                let log = logs.get_or_open(&context, &partition).await.unwrap();
                for event in content.iter().chain(std::iter::once(&root)) {
                    log.append(event).await.unwrap();
                }
                log.commit().await.unwrap();
            }
            count_checkpoints
                .record(&context, &partition, 3)
                .await
                .unwrap();

            // Interrupt a rewrite after its destroy.
            arm_append_failure(&partition, 0);
            super::rewrite_one(
                &context,
                &run_dir,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &interrupted,
                &partition,
                &|event: &Event| {
                    if event.kind == "secret" {
                        RewriteDecision::Drop
                    } else {
                        RewriteDecision::Keep
                    }
                },
            )
            .await
            .expect_err("the armed restore failure surfaces");

            // A caller that knows only the staged identity finishes it. This is
            // what the excision path does before starting its own rewrite.
            logs = super::OpenLogs::new();
            checkpoints.clear();
            count_checkpoints.evict_all();
            mmr_logs.clear();
            let stage = super::rewrite_stage_partition(&partition, &interrupted);
            let dropped = super::resume_rewrite(
                &context,
                &run_dir,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &partition,
                &stage,
            )
            .await
            .expect("the stage finishes")
            .expect("a stage was waiting");
            assert_eq!(dropped, 1);

            let restored = logs
                .get_or_open(&context, &partition)
                .await
                .unwrap()
                .replay()
                .await
                .unwrap();
            assert_eq!(restored.len(), 2, "one survivor plus one fresh root");
            assert_eq!(restored[0], content[0]);

            // Asked again, there is nothing staged and nothing to do.
            let second = super::resume_rewrite(
                &context,
                &run_dir,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &partition,
                &stage,
            )
            .await
            .expect("a second resume is a no-op");
            assert!(
                second.is_none(),
                "a finished excision leaves no stage, so recovery costs one call"
            );
        });
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// `#2323`: a rewrite interrupted after its destroy does not report healthy,
    /// and a later attempt at the same command finishes it from the stage.
    ///
    /// Before the fix the survivors lived only in memory, and the destroy
    /// cleared the count checkpoint. So an interrupted rewrite left an empty
    /// partition whose expected count was zero, and the truncation guard could
    /// never fire. This pins both halves: the window fails loud, and the resume
    /// restores exactly what the interrupted rewrite intended.
    #[test]
    #[allow(clippy::too_many_lines)]
    fn an_interrupted_rewrite_fails_loud_and_resumes_from_its_stage() {
        use commonware_runtime::{Runner as _, tokio as cw_tokio};

        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-rewrite-resume-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let partition = "conv-rewrite-resume".to_owned();
        let command_id = "excise-resume-1".to_owned();
        let run_dir = dir.clone();
        let runner =
            cw_tokio::Runner::new(cw_tokio::Config::default().with_storage_directory(dir.clone()));
        runner.start(move |context| async move {
            let mut logs = super::OpenLogs::new();
            let mut checkpoints = HashMap::new();
            let mut count_checkpoints = super::CountCheckpoints::new();
            let mut mmr_logs = HashMap::new();
            let signer = polyc_crypto::signing_role::JournalAttestationSigner::from_seed(21);
            let trust = polyc_crypto::signing_role::RoleTrustSet::current(&signer);

            let content = vec![
                Event::new("user_msg", b"keep-one".to_vec()),
                Event::new("secret", b"drop-me".to_vec()),
                Event::new("user_msg", b"keep-two".to_vec()),
            ];
            let tree = polyc_eventlog::rebuild_from_events(&content).expect("tree");
            let root = polyc_eventlog::extend_and_sign(&tree, &[], &signer).expect("sign");
            let seeded: Vec<Event> = content
                .iter()
                .cloned()
                .chain(std::iter::once(root))
                .collect();
            {
                let log = logs.get_or_open(&context, &partition).await.unwrap();
                for event in &seeded {
                    log.append(event).await.unwrap();
                }
                log.commit().await.unwrap();
            }
            count_checkpoints
                .record(&context, &partition, seeded.len() as u64)
                .await
                .unwrap();

            let decide = |event: &Event| {
                if event.kind == "secret" {
                    RewriteDecision::Drop
                } else {
                    RewriteDecision::Keep
                }
            };

            // Crash after the target is destroyed, before anything is restored.
            arm_append_failure(&partition, 0);
            super::rewrite_one(
                &context,
                &run_dir,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &command_id,
                &partition,
                &decide,
            )
            .await
            .expect_err("the armed restore failure surfaces");

            // Fresh caches model a restart. The partition is empty, and that
            // must NOT read as healthy.
            logs = super::OpenLogs::new();
            checkpoints.clear();
            count_checkpoints.evict_all();
            mmr_logs.clear();
            let verdict = super::replay_verified_one(
                &context,
                &mut logs,
                &mut count_checkpoints,
                &trust,
                &partition,
            )
            .await;
            match verdict {
                Err(super::VerifyError::TruncatedReplay { expected, actual }) => {
                    assert_eq!(expected, 4, "the pre-rewrite count is still the floor");
                    assert_eq!(actual, 0, "the destroy really did empty the partition");
                }
                other => panic!("an interrupted rewrite must report damage, got {other:?}"),
            }

            // A later attempt at the SAME command finishes from the stage.
            let dropped = super::rewrite_one(
                &context,
                &run_dir,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &command_id,
                &partition,
                &decide,
            )
            .await
            .expect("the retry resumes from the durable stage");
            assert_eq!(
                dropped, 1,
                "the resume reports what the interrupted run dropped"
            );

            let restored = logs
                .get_or_open(&context, &partition)
                .await
                .unwrap()
                .replay()
                .await
                .unwrap();
            assert_eq!(
                restored.len(),
                3,
                "two surviving records plus one fresh root"
            );
            assert_eq!(restored[0], content[0]);
            assert_eq!(restored[1], content[2]);
            assert_eq!(restored[2].kind, polyc_eventlog::MMR_SIGNED_ROOT_KIND);

            // And the resumed partition verifies against its own fresh root.
            let verified = super::replay_verified_one(
                &context,
                &mut logs,
                &mut count_checkpoints,
                &trust,
                &partition,
            )
            .await
            .expect("a resumed rewrite leaves a verifying partition");
            assert_eq!(verified.len(), 3);

            // The stage is gone, and never was a caller-visible partition.
            assert!(
                super::list_partitions_in(&dir)
                    .unwrap()
                    .iter()
                    .all(|name| !name.starts_with(super::REWRITE_STAGE_PREFIX)),
                "rewrite staging is never a caller-visible partition"
            );
        });
    }

    /// `#2567`: a rewrite whose terminal count record fails keeps its stage.
    ///
    /// That record is the only step that lowers the floor a rewrite raised. It
    /// used to be logged and swallowed, so `rewrite_one` read a success and
    /// tore the stage down. The partition then reported a truncated replay on
    /// every read, and the one thing that could ever fix it was gone — no
    /// excision, no retry, and no operator command could recover it.
    ///
    /// This pins the whole chain: the failure surfaces, the stage survives it,
    /// the partition reports damage rather than health, and a later attempt
    /// finishes the rewrite from that stage.
    #[test]
    #[allow(clippy::too_many_lines)]
    fn a_rewrite_whose_terminal_count_record_fails_keeps_its_stage() {
        use commonware_runtime::{Runner as _, tokio as cw_tokio};

        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-rewrite-record-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let partition = "conv-rewrite-record".to_owned();
        let command_id = "excise-record-1".to_owned();
        let run_dir = dir.clone();
        let runner =
            cw_tokio::Runner::new(cw_tokio::Config::default().with_storage_directory(dir.clone()));
        runner.start(move |context| async move {
            let mut logs = super::OpenLogs::new();
            let mut checkpoints = HashMap::new();
            let mut count_checkpoints = super::CountCheckpoints::new();
            let mut mmr_logs = HashMap::new();
            let signer = polyc_crypto::signing_role::JournalAttestationSigner::from_seed(31);
            let trust = polyc_crypto::signing_role::RoleTrustSet::current(&signer);

            let content = vec![
                Event::new("user_msg", b"keep-one".to_vec()),
                Event::new("secret", b"drop-me".to_vec()),
                Event::new("user_msg", b"keep-two".to_vec()),
            ];
            let tree = polyc_eventlog::rebuild_from_events(&content).expect("tree");
            let root = polyc_eventlog::extend_and_sign(&tree, &[], &signer).expect("sign");
            let seeded: Vec<Event> = content
                .iter()
                .cloned()
                .chain(std::iter::once(root))
                .collect();
            {
                let log = logs.get_or_open(&context, &partition).await.unwrap();
                for event in &seeded {
                    log.append(event).await.unwrap();
                }
                log.commit().await.unwrap();
            }
            count_checkpoints
                .record(&context, &partition, seeded.len() as u64)
                .await
                .unwrap();

            let decide = |event: &Event| {
                if event.kind == "secret" {
                    RewriteDecision::Drop
                } else {
                    RewriteDecision::Keep
                }
            };

            // The content is restored; only the step that lowers the floor
            // fails. This is the narrowest window a rewrite has.
            arm_count_record_failure(&partition);
            super::rewrite_one(
                &context,
                &run_dir,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &command_id,
                &partition,
                &decide,
            )
            .await
            .expect_err("the terminal count record's failure must surface");

            // Fresh caches model a restart.
            logs = super::OpenLogs::new();
            checkpoints.clear();
            count_checkpoints.evict_all();
            mmr_logs.clear();

            // The partition holds the right content and still reports damage,
            // because the floor it is measured against was never lowered.
            match super::replay_verified_one(
                &context,
                &mut logs,
                &mut count_checkpoints,
                &trust,
                &partition,
            )
            .await
            {
                Err(super::VerifyError::TruncatedReplay { expected, actual }) => {
                    assert_eq!(expected, 4, "the pre-rewrite count is still the floor");
                    assert_eq!(actual, 3, "two survivors plus one fresh root did land");
                }
                other => panic!("a rewrite short of its record must report damage, got {other:?}"),
            }

            // The stage the failure preserved is the remedy. Before `#2567`
            // the swallowed record let `rewrite_one` destroy it here. The
            // listing hides stages by design, so this reads the directory the
            // storage layer actually writes.
            assert!(
                stage_dirs_in(&run_dir) > 0,
                "the stage must outlive a failed terminal record"
            );

            let dropped = super::rewrite_one(
                &context,
                &run_dir,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &command_id,
                &partition,
                &decide,
            )
            .await
            .expect("the retry finishes the rewrite from its stage");
            assert_eq!(
                dropped, 1,
                "the resume reports what the interrupted run dropped"
            );

            let verified = super::replay_verified_one(
                &context,
                &mut logs,
                &mut count_checkpoints,
                &trust,
                &partition,
            )
            .await
            .expect("the resumed rewrite leaves a partition that reads clean");
            assert_eq!(verified.len(), 3, "two survivors plus one fresh root");
            assert_eq!(verified[0], content[0]);
            assert_eq!(verified[1], content[2]);
            assert_eq!(
                stage_dirs_in(&run_dir),
                0,
                "the finished rewrite removes its private stage"
            );
        });

        let _ = std::fs::remove_dir_all(dir);
    }

    /// Counts the rewrite-stage journals `storage_dir` actually holds.
    ///
    /// `list_partitions_in` deliberately hides them, so a test that wants to
    /// know whether a stage survived has to read the directory itself. A
    /// destroyed stage still leaves its own (empty) event-count checkpoint
    /// directory behind, which is not the stage and does not answer for it.
    fn stage_dirs_in(storage_dir: &std::path::Path) -> usize {
        std::fs::read_dir(storage_dir)
            .expect("the storage directory exists")
            .filter_map(Result::ok)
            .filter(|entry| {
                let name = entry.file_name().to_string_lossy().into_owned();
                name.starts_with(super::REWRITE_STAGE_PREFIX)
                    && !name.contains("__eventcount_checkpoint")
            })
            .count()
    }

    /// `#2322`, resume path: a repair that crashes after destroying the target
    /// finishes from its durable stage, and the partition still verifies.
    ///
    /// The existing resume test seeds with raw appends, so no signed root ever
    /// exists and the re-root step is never exercised through the stage. This
    /// one seeds a genuine stale root, forces the crash, resumes, and then
    /// appends another batch. That last step is the point: it fails if the
    /// cached MMR tree does not describe what the resume actually left on disk.
    #[test]
    #[allow(clippy::too_many_lines)]
    fn a_resumed_repair_re_roots_and_leaves_an_extendable_tree() {
        use commonware_runtime::{Runner as _, tokio as cw_tokio};

        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-repair-resume-reroot-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let partition = "conv-repair-resume-reroot".to_owned();
        let runner =
            cw_tokio::Runner::new(cw_tokio::Config::default().with_storage_directory(dir.clone()));
        runner.start(move |context| async move {
            let mut logs = super::OpenLogs::new();
            let mut checkpoints = HashMap::new();
            let mut count_checkpoints = super::CountCheckpoints::new();
            let mut mmr_logs = HashMap::new();
            let signer = polyc_crypto::signing_role::JournalAttestationSigner::from_seed(11);
            let trust = polyc_crypto::signing_role::RoleTrustSet::current(&signer);

            let content = vec![
                Event::new("user_msg", b"alpha".to_vec()),
                Event::new("output_msg", b"beta".to_vec()),
                Event::new("tool_call", b"gamma".to_vec()),
            ];
            let tree = polyc_eventlog::rebuild_from_events(&content).expect("tree");
            let stale_root = polyc_eventlog::extend_and_sign(&tree, &[], &signer).expect("sign");
            let seeded: Vec<Event> = content
                .iter()
                .cloned()
                .chain(std::iter::once(stale_root.clone()))
                .collect();
            {
                let log = logs.get_or_open(&context, &partition).await.unwrap();
                for event in &seeded {
                    log.append(event).await.unwrap();
                }
                log.commit().await.unwrap();
            }
            count_checkpoints
                .record(&context, &partition, seeded.len() as u64)
                .await
                .unwrap();

            // Position 1 did not decode. The stale root survives into the scan.
            let readable: Vec<(u64, Event)> = seeded
                .iter()
                .enumerate()
                .filter(|(position, _)| *position != 1)
                .map(|(position, event)| (position as u64, event.clone()))
                .collect();
            let quarantined = vec![polyc_eventlog::QuarantinedItem {
                position: 1,
                error: "injected unreadable frame".to_owned(),
            }];
            let raw: Vec<Event> = readable.iter().map(|(_, event)| event.clone()).collect();
            let (expected_content, _) =
                super::repaired_content(&raw, &signer, None).expect("re-root");
            let indexed: Vec<(u64, Event)> = expected_content
                .iter()
                .enumerate()
                .map(|(position, event)| (position as u64, event.clone()))
                .collect();
            let before = super::repair_fingerprint(&readable, &quarantined, seeded.len() as u64);
            let after = super::repair_fingerprint(&indexed, &[], expected_content.len() as u64);
            let scan = super::RepairScan {
                readable,
                quarantined,
                before,
                after,
                standing: polyc_eventlog::RootStanding::Stale,
            };

            // Crash after the target is destroyed, before it is restored.
            arm_append_failure(&partition, 0);
            super::apply_repair_scan(
                &context,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &partition,
                scan,
                None,
            )
            .await
            .expect_err("the armed restore failure surfaces");

            // Fresh caches model a restart. The stage finishes the repair.
            logs = super::OpenLogs::new();
            checkpoints.clear();
            count_checkpoints.evict_all();
            mmr_logs.clear();
            let (application, _) = super::apply_repair_conditionally(
                &context,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &trust,
                &partition,
                super::RepairFingerprints { before, after },
                None,
            )
            .await
            .expect("the restart resumes from the durable stage");
            assert_eq!(application, RepairApplication::Applied);

            let restored = logs
                .get_or_open(&context, &partition)
                .await
                .unwrap()
                .replay()
                .await
                .unwrap();
            assert_eq!(
                restored, expected_content,
                "a resumed repair restores the re-rooted content"
            );
            let roots: Vec<&Event> = restored
                .iter()
                .filter(|event| event.kind == polyc_eventlog::MMR_SIGNED_ROOT_KIND)
                .collect();
            assert_eq!(roots.len(), 1, "exactly one root survives the resume");
            assert_ne!(*roots[0], stale_root, "and it is not the stale one");

            // The partition verifies, and it still verifies after another
            // batch — which is what catches a cached tree describing something
            // other than what the resume left behind.
            super::replay_verified_one(
                &context,
                &mut logs,
                &mut count_checkpoints,
                &trust,
                &partition,
            )
            .await
            .expect("a resumed repair leaves a verifying partition");

            super::append_batch_one(
                &context,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &partition,
                &[Event::new("user_msg", b"delta".to_vec())],
            )
            .await
            .expect("the repaired partition accepts another batch");
            let verified = super::replay_verified_one(
                &context,
                &mut logs,
                &mut count_checkpoints,
                &trust,
                &partition,
            )
            .await
            .expect("the partition still verifies after extending it");
            assert!(
                verified.len() > restored.len(),
                "the extending batch landed on top of the repaired content"
            );
        });
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// `#2322`: a repair that drops a position must RE-ROOT what survives.
    ///
    /// The partition's existing signed root describes every leaf the repair is
    /// about to drop. Re-appending it verbatim leaves a partition whose own
    /// verification fails for good, and a second repair cannot fix it: a stale
    /// root is a semantic failure, not a decode failure, so `replay_quarantining`
    /// reports nothing to quarantine and the repair short-circuits.
    ///
    /// The existing repair tests cannot see this. They either seed with raw
    /// appends (so no marker ever exists) or corrupt the active section, which
    /// the journal's self-heal wipes whole — leaving zero survivors, and no
    /// survivor means no stale root to strip.
    #[test]
    #[allow(clippy::too_many_lines)]
    fn a_repair_that_drops_a_position_re_roots_what_survives() {
        use commonware_runtime::{Runner as _, tokio as cw_tokio};

        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-repair-reroot-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let partition = "conv-repair-reroot".to_owned();
        let runner =
            cw_tokio::Runner::new(cw_tokio::Config::default().with_storage_directory(dir.clone()));
        runner.start(move |context| async move {
            let mut logs = super::OpenLogs::new();
            let mut checkpoints = HashMap::new();
            let mut count_checkpoints = super::CountCheckpoints::new();
            let mut mmr_logs = HashMap::new();
            let signer = polyc_crypto::signing_role::JournalAttestationSigner::from_seed(9);
            let trust = polyc_crypto::signing_role::RoleTrustSet::current(&signer);

            // A partition the real append path would produce: content plus one
            // signed root over all of it.
            let content = vec![
                Event::new("user_msg", b"one".to_vec()),
                Event::new("output_msg", b"two".to_vec()),
                Event::new("tool_call", b"three".to_vec()),
                Event::new("output_msg", b"four".to_vec()),
            ];
            let tree = polyc_eventlog::rebuild_from_events(&content).expect("tree");
            let original_root = polyc_eventlog::extend_and_sign(&tree, &[], &signer).expect("sign");
            let seeded: Vec<Event> = content
                .iter()
                .cloned()
                .chain(std::iter::once(original_root.clone()))
                .collect();
            {
                let log = logs.get_or_open(&context, &partition).await.unwrap();
                for event in &seeded {
                    log.append(event).await.unwrap();
                }
                log.commit().await.unwrap();
            }
            count_checkpoints
                .record(&context, &partition, seeded.len() as u64)
                .await
                .unwrap();

            // Position 2 did not decode. Everything else survives, INCLUDING
            // the now-stale root, which is exactly the shape the bug needs.
            let readable: Vec<(u64, Event)> = seeded
                .iter()
                .enumerate()
                .filter(|(position, _)| *position != 2)
                .map(|(position, event)| (position as u64, event.clone()))
                .collect();
            assert!(
                readable
                    .iter()
                    .any(|(_, event)| event.kind == polyc_eventlog::MMR_SIGNED_ROOT_KIND),
                "the fixture must carry a stale root into the repair"
            );
            let quarantined = vec![polyc_eventlog::QuarantinedItem {
                position: 2,
                error: "injected unreadable frame".to_owned(),
            }];
            let raw: Vec<Event> = readable.iter().map(|(_, event)| event.clone()).collect();
            let (expected_content, _) =
                super::repaired_content(&raw, &signer, None).expect("re-root");
            let indexed: Vec<(u64, Event)> = expected_content
                .iter()
                .enumerate()
                .map(|(position, event)| (position as u64, event.clone()))
                .collect();
            let scan = super::RepairScan {
                before: super::repair_fingerprint(&readable, &quarantined, seeded.len() as u64),
                after: super::repair_fingerprint(&indexed, &[], expected_content.len() as u64),
                readable,
                quarantined,
                standing: polyc_eventlog::RootStanding::Stale,
            };

            super::apply_repair_scan(
                &context,
                &mut logs,
                &mut checkpoints,
                &mut count_checkpoints,
                &mut mmr_logs,
                &signer,
                &partition,
                scan,
                None,
            )
            .await
            .expect("the repair applies");

            let restored = logs
                .get_or_open(&context, &partition)
                .await
                .unwrap()
                .replay()
                .await
                .unwrap();
            let roots: Vec<&Event> = restored
                .iter()
                .filter(|event| event.kind == polyc_eventlog::MMR_SIGNED_ROOT_KIND)
                .collect();
            assert_eq!(roots.len(), 1, "exactly one root survives a repair");
            assert_ne!(
                *roots[0], original_root,
                "the surviving root is freshly signed, not the stale one"
            );
            assert_eq!(
                restored.len(),
                4,
                "three surviving content events plus one fresh root"
            );

            // The point of the fix: the repaired partition verifies. Before
            // `#2322` this returned RootMismatch, permanently.
            let verified = super::replay_verified_one(
                &context,
                &mut logs,
                &mut count_checkpoints,
                &trust,
                &partition,
            )
            .await
            .expect("a repaired partition verifies against its own fresh root");
            assert_eq!(verified.len(), 4);
        });
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// The second reproduction shape from the same corruption class: a
    /// CONTENT-only tamper that still decodes cleanly (unlike the `kind`
    /// corruption above, which breaks UTF-8 validity) — the case the PR's
    /// MMR check claims to catch. It never gets that far: `commonware-storage`'s
    /// active-section revalidation on open re-derives the section's item
    /// boundaries by sequentially streaming from byte zero (see
    /// `align_journals` in that crate's `journal::contiguous::variable`), so
    /// it cannot tell "this specific item is corrupt" apart from "the whole
    /// section may be an in-flight torn write" — empirically (see this
    /// module's git history for the investigation), a payload-only tamper
    /// ANYWHERE in the active section — even in an event that PRECEDES the
    /// corrupted one — invalidates the section back to zero items, not just
    /// a truncated tail. That is a starker false pass than "shorter than
    /// expected": corrupting the LAST event in a long active section can
    /// silently erase every earlier one too. `verify_replay` never gets a
    /// chance to see (and reject) the tampered content at all.
    #[tokio::test]
    async fn active_section_payload_content_tamper_is_a_hard_verify_failure_not_a_false_pass() {
        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-active-corrupt-payload-{}",
            std::process::id()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let partition = "conv-corrupt-payload".to_owned();

        {
            let shutdown = CancellationToken::new();
            let host = EventLogHost::spawn(
                dir.clone(),
                shutdown.clone(),
                polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
            )
            .expect("spawn");
            host.append_batch(
                partition.clone(),
                vec![
                    Event::new("user_msg", b"what is 2+2?".to_vec()),
                    Event::new("output_msg", b"the reply is four".to_vec()),
                ],
            )
            .await
            .expect("append 2-event turn");

            let verified = host
                .replay_verified(partition.clone())
                .await
                .expect("uncorrupted conversation verifies");
            assert_eq!(verified.len(), 3, "2 content events + 1 signed-root marker");
            drop(host);
        }

        // Flip a byte INSIDE the second event's payload content — not its
        // `kind` — so the tampered bytes are still a well-formed UTF-8-free
        // `Vec<u8>` payload (a plain content tamper, not a decode-breaking
        // one). Located the same way: find the known payload bytes on disk
        // rather than hand-computing offsets.
        let data_file = dir
            .join(format!("{partition}_data"))
            .join("0000000000000000");
        let mut bytes = std::fs::read(&data_file).expect("read section 0");
        let payload_at = bytes
            .windows(b"the reply is four".len())
            .position(|w| w == b"the reply is four")
            .expect("the second event's payload bytes are present on disk");
        bytes[payload_at] ^= 0xFF;
        std::fs::write(&data_file, &bytes).expect("write corrupted section 0");

        let shutdown2 = CancellationToken::new();
        let host2 = EventLogHost::spawn(
            dir.clone(),
            shutdown2,
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
        )
        .expect("reopen");

        let err = host2
            .replay_verified(partition.clone())
            .await
            .expect_err("a content-only tamper must still be caught, not silently truncated");
        let AppendError::Verify(verify_err) = err else {
            panic!("expected AppendError::Verify, got {err:?}");
        };
        match verify_err {
            super::VerifyError::TruncatedReplay { expected, actual } => {
                assert_eq!(expected, 3, "checkpoint recorded all 3 events as committed");
                assert_eq!(
                    actual, 0,
                    "the storage layer's active-section revalidation invalidates the WHOLE \
                     section on any internal inconsistency, not just a truncated tail — even \
                     the untouched first event is lost"
                );
            }
            other => panic!("expected TruncatedReplay, got {other:?}"),
        }

        let quarantined = host2
            .repair_partition(partition.clone())
            .await
            .expect("repair completes");
        assert_eq!(
            quarantined.len(),
            3,
            "repair must flag the full gap between the checkpoint and what's visible, not report nothing"
        );
        let positions: Vec<u64> = quarantined.iter().map(|q| q.position).collect();
        assert_eq!(positions, vec![0, 1, 2]);

        // After repair, the checkpoint is re-baselined to reality (0 —
        // nothing in this partition survived), so a follow-up verify reports
        // cleanly instead of re-flagging the same, already-surfaced gap.
        let reverified = host2
            .replay_verified(partition)
            .await
            .expect("post-repair verify judges the partition against its new, honest baseline");
        assert!(
            reverified.is_empty(),
            "everything was unrecoverable in this reproduction; repair's job is honesty, not magic"
        );

        drop(host2);
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// Sharding (`#799`): a slow, large replay on one partition must not
    /// delay appends to another partition routed to a different shard. Picks
    /// two partitions that hash to different shards, kicks off a big replay
    /// on the first in the background, and while it's still in flight,
    /// races a batch of appends against the second — those appends must
    /// complete quickly, proving they were not queued behind the slow
    /// replay on a shared single command loop.
    #[tokio::test(flavor = "multi_thread")]
    async fn shard_slow_replay_on_one_partition_does_not_block_appends_on_another() {
        /// Events seeded on the "slow" partition so a full replay of it
        /// takes measurable time.
        const SLOW_PARTITION_EVENTS: usize = 20_000;

        let dir =
            std::env::temp_dir().join(format!("polychrome-eventlog-shard-{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        let shutdown = CancellationToken::new();
        let host = std::sync::Arc::new(
            EventLogHost::spawn(
                dir.clone(),
                shutdown.clone(),
                polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
            )
            .expect("spawn"),
        );
        assert!(
            host.num_shards() > 1,
            "sharding requires more than one shard"
        );

        // Find two partition names that hash to different shards (with
        // NUM_SHARDS > 1 this is virtually guaranteed within a handful of
        // tries, but search deterministically rather than assume the first
        // pair collides).
        let mut partition_a = None;
        let mut partition_b = None;
        for i in 0..64u32 {
            let name = format!("conv-shard-{i}");
            let idx = host.shard_index_for(&name);
            match (&partition_a, &partition_b) {
                (None, _) => partition_a = Some((name, idx)),
                (Some((_, idx_a)), None) if idx != *idx_a => partition_b = Some((name, idx)),
                _ => {}
            }
        }
        let (partition_a, _) = partition_a.expect("found a first partition");
        let (partition_b, _) = partition_b.expect("found a partition on a different shard");

        // Seed partition A with a large number of sizable events so a full
        // replay of it takes measurable time.
        let mut batch = Vec::with_capacity(SLOW_PARTITION_EVENTS);
        for i in 0..SLOW_PARTITION_EVENTS {
            batch.push(Event::new(format!("k{i}"), vec![b'x'; 512]));
        }
        host.append_batch(partition_a.clone(), batch)
            .await
            .expect("seed the slow partition");

        // Kick off the slow replay in the background, without awaiting it.
        let replay_host = host.clone();
        let replay_partition = partition_a.clone();
        let replay_handle = tokio::spawn(async move { replay_host.replay(replay_partition).await });

        // While that replay is (almost certainly) still in flight, race a
        // batch of appends against partition B on a different shard and
        // time them. If sharding worked, this finishes quickly; on the old
        // single-loop design these would queue behind the entire slow
        // replay above.
        let start = std::time::Instant::now();
        for i in 0..20u32 {
            host.append_batch(
                partition_b.clone(),
                vec![Event::new(format!("b{i}"), b"fast".to_vec())],
            )
            .await
            .expect("append to the other shard");
        }
        let elapsed = start.elapsed();

        replay_handle
            .await
            .expect("replay task")
            .expect("slow replay itself succeeds");

        // Each fast append_batch also lands its own MMR signed-root marker
        // (#799), so count only the content events, not the markers.
        let content_events = host
            .replay(partition_b)
            .await
            .expect("replay b")
            .into_iter()
            .filter(|e| e.kind != polyc_eventlog::MMR_SIGNED_ROOT_KIND)
            .count();
        assert_eq!(content_events, 20, "all 20 fast appends landed");
        assert!(
            elapsed < std::time::Duration::from_secs(5),
            "appends to a different shard took {elapsed:?} — too slow to plausibly be \
             running concurrently with the other shard's big replay"
        );

        drop(host);
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// `#1711`: the sibling of `shard_slow_replay_on_one_partition_does_not_block_appends_on_another`
    /// — that test proves a slow replay on one shard doesn't delay an append
    /// routed to a DIFFERENT shard; this proves the gap it doesn't cover: a
    /// replay deliberately paused inside one partition must not delay an
    /// append to a DIFFERENT partition that hashes to the SAME shard. Before
    /// the per-partition-worker fix, every partition on a shard shared one
    /// sequential command loop, so the append could not complete until the
    /// paused replay was released.
    #[tokio::test(flavor = "multi_thread")]
    async fn a_paused_replay_on_one_partition_does_not_block_appends_on_another_partition_on_the_same_shard()
     {
        const FAST_APPENDS: u32 = 4;

        let dir = std::env::temp_dir().join(format!(
            "polychrome-eventlog-same-shard-{}",
            std::process::id()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        let shutdown = CancellationToken::new();
        let host = std::sync::Arc::new(
            EventLogHost::spawn(
                dir.clone(),
                shutdown.clone(),
                polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
            )
            .expect("spawn"),
        );

        // Find two partition names that hash to the SAME shard (searched
        // deterministically rather than assumed — with NUM_SHARDS == 4 this
        // is virtually guaranteed within a handful of tries).
        let mut partition_a = None;
        let mut partition_b = None;
        for i in 0..64u32 {
            let name = format!("conv-same-shard-{i}");
            let idx = host.shard_index_for(&name);
            match (&partition_a, &partition_b) {
                (None, _) => partition_a = Some((name, idx)),
                (Some((_, idx_a)), None) if idx == *idx_a => partition_b = Some((name, idx)),
                _ => {}
            }
        }
        let (partition_a, _) = partition_a.expect("found a first partition");
        let (partition_b, _) = partition_b.expect("found a partition on the SAME shard");

        host.append_batch(
            partition_a.clone(),
            vec![Event::new("seed", b"one".to_vec())],
        )
        .await
        .expect("seed the paused partition");

        let pause = arm_replay_pause(&partition_a);
        let replay_host = host.clone();
        let replay_partition = partition_a.clone();
        let replay_handle = tokio::spawn(async move { replay_host.replay(replay_partition).await });
        tokio::time::timeout(std::time::Duration::from_secs(30), pause.entered.notified())
            .await
            .expect("the replay reached its deterministic pause");

        // Store the timeout result before asserting, then always release the
        // paused worker. A regression fails cleanly instead of leaving a task
        // blocked while the runtime tears down.
        let append_result = tokio::time::timeout(std::time::Duration::from_secs(30), async {
            for i in 0..FAST_APPENDS {
                host.append_batch(
                    partition_b.clone(),
                    vec![Event::new(format!("b{i}"), b"fast".to_vec())],
                )
                .await
                .expect("append to the other partition on the same shard");
            }
        })
        .await;
        pause.release.notify_one();

        replay_handle
            .await
            .expect("replay task")
            .expect("slow replay itself succeeds");

        let content_events = host
            .replay(partition_b)
            .await
            .expect("replay b")
            .into_iter()
            .filter(|e| e.kind != polyc_eventlog::MMR_SIGNED_ROOT_KIND)
            .count();
        assert_eq!(
            content_events, FAST_APPENDS as usize,
            "all fast appends landed"
        );
        append_result.expect(
            "appends to another partition on the SAME shard must complete while the first \
             partition's replay is deliberately paused (#1711)",
        );

        drop(host);
        let _ = std::fs::remove_dir_all(&dir);
    }
}

#[cfg(test)]
mod presence_tests {
    #![allow(
        clippy::pedantic,
        clippy::nursery,
        missing_docs,
        reason = "a test module: panics are the failure mode"
    )]

    use super::*;
    use tokio_util::sync::CancellationToken;

    fn scratch(name: &str) -> std::path::PathBuf {
        let dir = std::env::temp_dir().join(format!(
            "polyc-presence-{name}-{}-{}",
            std::process::id(),
            uuid::Uuid::now_v7().as_simple()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        dir
    }

    fn spawn_host(dir: &std::path::Path, shutdown: &CancellationToken) -> EventLogHost {
        EventLogHost::spawn(
            dir.to_path_buf(),
            shutdown.clone(),
            polyc_crypto::signing_role::JournalAttestationSigner::from_seed(1),
        )
        .expect("spawn the host")
    }

    /// A name nothing ever wrote is absent, and asking creates nothing.
    #[tokio::test]
    async fn a_never_written_partition_is_absent_and_asking_creates_nothing() {
        let dir = scratch("never-written");
        std::fs::create_dir_all(&dir).unwrap();
        let shutdown = CancellationToken::new();
        let host = spawn_host(&dir, &shutdown);

        assert_eq!(
            host.partition_presence("conv-typo".to_owned())
                .await
                .unwrap(),
            PartitionPresence::Absent
        );
        assert!(
            std::fs::read_dir(&dir).unwrap().next().is_none(),
            "asking about a typo must leave the volume empty"
        );

        shutdown.cancel();
        let _ = std::fs::remove_dir_all(dir);
    }

    /// A completed destroy leaves a cleared checkpoint, which is still absence.
    #[tokio::test]
    async fn a_destroyed_partition_is_absent_after_its_checkpoint_is_cleared() {
        let dir = scratch("destroyed");
        let shutdown = CancellationToken::new();
        let host = spawn_host(&dir, &shutdown);

        host.append_batch("conv-gone".to_owned(), vec![Event::new("k", b"v".to_vec())])
            .await
            .unwrap();
        assert_eq!(
            host.partition_presence("conv-gone".to_owned())
                .await
                .unwrap(),
            PartitionPresence::Present
        );
        host.destroy_partition("conv-gone".to_owned())
            .await
            .unwrap();

        // The checkpoint directory outlives the destroy by design; it records
        // nothing, so the partition is absent rather than damaged.
        assert!(
            dir.join("conv-gone__eventcount_checkpoint").exists(),
            "a destroy clears the checkpoint in place rather than removing it"
        );
        assert_eq!(
            host.partition_presence("conv-gone".to_owned())
                .await
                .unwrap(),
            PartitionPresence::Absent
        );

        shutdown.cancel();
        let _ = std::fs::remove_dir_all(dir);
    }

    /// A lost data directory with a surviving index is damage, not absence.
    ///
    /// The removal is physical: the durable artifacts are deleted off the
    /// volume between two host lifetimes, which is the shape an operator or a
    /// partial volume loss actually leaves.
    #[tokio::test]
    async fn a_lost_data_directory_with_a_surviving_index_is_damaged() {
        let dir = scratch("lost-data");
        let shutdown = CancellationToken::new();
        let host = spawn_host(&dir, &shutdown);
        host.append_batch("conv-lost".to_owned(), vec![Event::new("k", b"v".to_vec())])
            .await
            .unwrap();
        shutdown.cancel();
        drop(host);

        // Only the authoritative data directory goes. The index siblings and
        // the count checkpoint stay exactly where the commit left them.
        std::fs::remove_dir_all(dir.join("conv-lost_data")).unwrap();
        assert!(dir.join("conv-lost_offsets-blobs").exists());

        let shutdown = CancellationToken::new();
        let host = spawn_host(&dir, &shutdown);
        match host
            .partition_presence("conv-lost".to_owned())
            .await
            .unwrap()
        {
            PartitionPresence::Damaged { remnant } => {
                // The exact remnant, not a prefix. `conv-lost` also prefixes the
                // checkpoint remnant, so a prefix match would stay green if the
                // index branch this case is named for stopped reporting.
                assert_eq!(remnant, "conv-lost_offsets-blobs");
            }
            other => panic!("a lost data directory is damage, got: {other:?}"),
        }

        shutdown.cancel();
        let _ = std::fs::remove_dir_all(dir);
    }

    /// A checkpoint that still counts events without journal data is damage.
    #[tokio::test]
    async fn a_surviving_nonzero_count_checkpoint_without_journal_data_is_damaged() {
        let dir = scratch("lost-all-but-count");
        let shutdown = CancellationToken::new();
        let host = spawn_host(&dir, &shutdown);
        host.append_batch(
            "conv-count".to_owned(),
            vec![Event::new("k", b"v".to_vec())],
        )
        .await
        .unwrap();
        shutdown.cancel();
        drop(host);

        // Everything but the checkpoint goes, so the checkpoint's own recorded
        // count is the only thing left that says this conversation existed.
        std::fs::remove_dir_all(dir.join("conv-count_data")).unwrap();
        std::fs::remove_dir_all(dir.join("conv-count_offsets-blobs")).unwrap();
        std::fs::remove_dir_all(dir.join("conv-count_offsets-metadata")).unwrap();

        let shutdown = CancellationToken::new();
        let host = spawn_host(&dir, &shutdown);
        match host
            .partition_presence("conv-count".to_owned())
            .await
            .unwrap()
        {
            PartitionPresence::Damaged { remnant } => {
                assert_eq!(remnant, "conv-count__eventcount_checkpoint");
            }
            other => panic!("a surviving nonzero count is damage, got: {other:?}"),
        }

        shutdown.cancel();
        let _ = std::fs::remove_dir_all(dir);
    }

    /// An error on the FIRST event is unknown, exactly like a later one.
    ///
    /// The tempting shortcut is that nothing appended before the failure, so
    /// nothing landed and the outcome is definite. It does not hold.
    /// Commonware reports a mutating operation's error without promising the
    /// operation left storage untouched, so the append that returned an error
    /// may itself have written bytes. Nothing in this process can prove it did
    /// not, and a definite class would tell the caller not to reconcile.
    ///
    /// This pins the classification for index 0. The prefix-survival and
    /// cache-eviction cases cover a later index.
    #[tokio::test]
    async fn an_error_on_the_first_event_is_unknown_too() {
        let dir = scratch("first-event-unknown");
        let shutdown = CancellationToken::new();
        let host = spawn_host(&dir, &shutdown);
        crate::tests::arm_append_failure("conv-first-unknown", 0);
        let error = host
            .append_batch(
                "conv-first-unknown".to_owned(),
                vec![
                    Event::new("output_msg", b"only".to_vec()),
                    Event::new("output_msg", b"second".to_vec()),
                ],
            )
            .await
            .expect_err("the first event was armed to fail");
        assert!(
            matches!(error, AppendError::AppendOutcomeUnknown(_)),
            "an errored append proves nothing about what it wrote: {error:?}"
        );
        shutdown.cancel();
        let _ = std::fs::remove_dir_all(dir);
    }

    /// `will_rewrite` decides the replacement, and a stale root is a rewrite.
    ///
    /// Three shapes, because three decisions read this one predicate: the
    /// `after` the inspection promises, whether the durable intent records a
    /// rotated lineage, and whether the application applies the replacement
    /// that performs the rotation.
    ///
    /// The middle shape is the one that was wrong. A stale root with an empty
    /// quarantine list rewrites, so its intent promises a rotation — but the
    /// replacement was gated on the quarantine list, so the marker that
    /// performs it was suppressed. The partition came back carrying its OLD
    /// lineage and the completion check refused the result, after the
    /// destructive half had already run.
    ///
    /// The empty shape must keep answering false. With no readable events
    /// there is no marker to rewrite, and `repaired_content` fails closed on a
    /// replacement it cannot apply exactly once.
    #[test]
    fn will_rewrite_follows_the_root_standing_not_the_quarantine_list() {
        let scan = |quarantined: Vec<polyc_eventlog::QuarantinedItem>,
                    standing: polyc_eventlog::RootStanding,
                    readable: Vec<(u64, Event)>| RepairScan {
            readable,
            quarantined,
            before: [1; 32],
            after: [2; 32],
            standing,
        };
        let one = || vec![(0_u64, Event::new("user_msg", b"alpha".to_vec()))];
        let quarantined = || {
            vec![polyc_eventlog::QuarantinedItem {
                position: 1,
                error: "unreadable".to_owned(),
            }]
        };

        assert!(
            scan(Vec::new(), polyc_eventlog::RootStanding::Stale, one()).will_rewrite(),
            "a stale root is repair work even with nothing to quarantine"
        );
        assert!(
            scan(quarantined(), polyc_eventlog::RootStanding::Holds, one()).will_rewrite(),
            "quarantining a record rewrites the partition"
        );
        assert!(
            !scan(Vec::new(), polyc_eventlog::RootStanding::Holds, Vec::new()).will_rewrite(),
            "an empty partition holds, and has no marker a replacement could rewrite"
        );
    }

    /// Probing the same damaged partition twice answers the same, twice.
    ///
    /// An operator reads a damaged conversation more than once: the failing
    /// read, then a verify, then the read again after a restore attempt. The
    /// checkpoint probe opens a durable store under a metrics label, so a
    /// second probe of one name is where a per-call label would leak and where
    /// a colliding registration would panic. Both are refusals this must not
    /// turn into.
    #[tokio::test]
    async fn probing_one_damaged_partition_twice_answers_the_same() {
        let dir = scratch("probe-twice");
        let shutdown = CancellationToken::new();
        let host = spawn_host(&dir, &shutdown);
        host.append_batch(
            "conv-twice".to_owned(),
            vec![Event::new("k", b"v".to_vec())],
        )
        .await
        .unwrap();
        shutdown.cancel();
        drop(host);

        std::fs::remove_dir_all(dir.join("conv-twice_data")).unwrap();
        std::fs::remove_dir_all(dir.join("conv-twice_offsets-blobs")).unwrap();
        std::fs::remove_dir_all(dir.join("conv-twice_offsets-metadata")).unwrap();

        let shutdown = CancellationToken::new();
        let host = spawn_host(&dir, &shutdown);
        let first = host
            .partition_presence("conv-twice".to_owned())
            .await
            .unwrap();
        let second = host
            .partition_presence("conv-twice".to_owned())
            .await
            .unwrap();
        assert_eq!(first, second, "a probe is a read and does not change state");
        assert!(
            matches!(first, PartitionPresence::Damaged { .. }),
            "got: {first:?}"
        );

        shutdown.cancel();
        let _ = std::fs::remove_dir_all(dir);
    }

    /// Discovery refuses a damaged remnant rather than omitting it.
    #[tokio::test]
    async fn discovery_refuses_a_partition_shaped_remnant_rather_than_omitting_it() {
        let dir = scratch("listing-remnant");
        let shutdown = CancellationToken::new();
        let host = spawn_host(&dir, &shutdown);
        host.append_batch("conv-keep".to_owned(), vec![Event::new("k", b"v".to_vec())])
            .await
            .unwrap();
        host.append_batch("conv-half".to_owned(), vec![Event::new("k", b"v".to_vec())])
            .await
            .unwrap();
        shutdown.cancel();
        drop(host);

        // A listing that skipped this would report one partition and call the
        // fleet complete, with a second conversation's storage half gone.
        std::fs::remove_dir_all(dir.join("conv-half_data")).unwrap();

        match crate::list_partitions_bounded_in(&dir, usize::MAX, usize::MAX, None) {
            Err(ListPartitionsError::Corrupt { entry }) => {
                assert!(entry.starts_with("conv-half"), "got: {entry}");
            }
            other => panic!("discovery must fail whole on a remnant, got: {other:?}"),
        }

        let _ = std::fs::remove_dir_all(dir);
    }

    /// A partition the listing hides still shields its own index siblings.
    ///
    /// Discovery excludes the administrative partition and hides repair
    /// stages. Each still writes the same index directories every partition
    /// writes. A remnant check that registered a data directory only for the
    /// partitions it RETURNS would read those siblings as orphans and refuse
    /// the whole fleet over storage that is intact.
    #[tokio::test]
    async fn an_excluded_partition_does_not_look_like_a_remnant() {
        let dir = scratch("listing-excluded");
        let shutdown = CancellationToken::new();
        let host = spawn_host(&dir, &shutdown);
        host.append_batch("conv-keep".to_owned(), vec![Event::new("k", b"v".to_vec())])
            .await
            .unwrap();
        host.append_batch(
            "conv-hidden".to_owned(),
            vec![Event::new("k", b"v".to_vec())],
        )
        .await
        .unwrap();
        shutdown.cancel();
        drop(host);
        assert!(dir.join("conv-hidden_offsets-blobs").exists());

        let listed =
            crate::list_partitions_bounded_in(&dir, usize::MAX, usize::MAX, Some("conv-hidden"))
                .expect("an excluded partition is not a remnant");
        assert_eq!(listed, vec!["conv-keep".to_owned()]);

        let _ = std::fs::remove_dir_all(dir);
    }

    /// A completed destroy does not make a later listing fail.
    #[tokio::test]
    async fn discovery_accepts_the_cleared_checkpoint_a_destroy_leaves() {
        let dir = scratch("listing-destroyed");
        let shutdown = CancellationToken::new();
        let host = spawn_host(&dir, &shutdown);
        host.append_batch("conv-keep".to_owned(), vec![Event::new("k", b"v".to_vec())])
            .await
            .unwrap();
        host.append_batch("conv-gone".to_owned(), vec![Event::new("k", b"v".to_vec())])
            .await
            .unwrap();
        host.destroy_partition("conv-gone".to_owned())
            .await
            .unwrap();
        shutdown.cancel();
        drop(host);

        let listed =
            crate::list_partitions_bounded_in(&dir, usize::MAX, usize::MAX, None).expect("lists");
        assert_eq!(listed, vec!["conv-keep".to_owned()]);

        let _ = std::fs::remove_dir_all(dir);
    }
}