agentplane 0.47.0

//! The executor: admission, step dispatch, sealing, and replay.
//!
//! M0 executes a single step. The DAG scheduler, plan contract, and topology
//! checks slot in above this without changing the effect protocol below it —
//! which is the point of putting the determinism boundary at the effect rather
//! than at the plan.

#[cfg(feature = "manifest")]
use std::collections::HashSet;
use std::collections::{BTreeMap, BTreeSet, HashMap};
use std::sync::Arc;
use std::time::Duration;

use serde_json::Value;

use crate::case::{CaseStore, EventStore, TaskStore, TimerStore};
use crate::core::{
    ArgSource, Budget, Calendar, Capability, Consumed, CorrelationKey, Delivery, Digest,
    InboundEvent, Ledger, Outcome, Phase, PlanIR, PlanNode, PolicyBundleIdentity, RunId,
    RuntimeError, Skill, SkillDescriptor, Spend, StepId, Tainted, WallClock,
};
use crate::journal::{Append, JournalStore, Record, RecordKind, ReplayCursor, StepCursor};
use crate::runtime::BuildError;

use super::ctx::{CaseContext, Mode, StepCtx};
use super::metrics;
use super::telemetry;
use tracing::Instrument;

#[derive(Debug, Clone)]
pub(crate) enum CaseBinding {
    Correlate {
        kind: String,
        keys: Vec<CorrelationKey>,
    },
    Existing(crate::core::CaseId),
}

/// What a caller asks admission for, beyond the capability and the input.
///
/// The named `run`/`spawn` methods each fix one combination of these; this is
/// the general form, for a caller that needs a combination they do not name —
/// above all a chain **per run**. A front door that authenticates many callers
/// admits each one's run under the chain that caller presented, and there is
/// no fixed method for "in this case, once, acting as her", nor should there
/// be: the axes multiply, the methods would not.
///
/// ```ignore
/// let terms = RunTerms::default()
///     .correlated("order", &keys)
///     .once(&message.dedup_key())
///     .acting_as(caller_chain);
/// let admission = runtime.run_under("order.settle", input, terms).await?;
/// ```
#[derive(Debug, Clone, Default)]
pub struct RunTerms {
    /// Which matter this run belongs to, if any.
    case: Option<CaseBinding>,
    /// The admission key to claim. Travels to the `RunAdmitted` record, because
    /// that is where the store claims it — see
    /// [`JournalStore::admitted_as`](crate::journal::JournalStore::admitted_as).
    idempotency_key: Option<String>,
    /// On whose authority this run acts.
    acting_as: Acting,
    /// Who asked for this run, when a person or peer did. Journaled on
    /// `RunAdmitted`, and barred from deciding the run's own tasks.
    admitted_by: Option<String>,
    /// The declaration revision the caller reviewed, when it pinned one.
    expected_declaration: Option<Digest>,
    /// Data subjects the embedder names for this run, beside any its
    /// declaration binds.
    subjects: Vec<String>,
}

/// On whose authority a run acts.
///
/// Three answers, not two, because "no chain was presented" means different
/// things at different doors. An in-process embedder that names no chain is
/// the plane itself, and acts under the plane's
/// ([`RuntimeBuilder::acting_as`]). A served caller whose credential carried
/// none is **somebody else** — and falling back to the plane's chain for them
/// would make the operator's authority an ambient credential every
/// authenticated peer holds.
///
/// Acting under a chain and being bounded by one are separate questions. A
/// served caller with no chain acts under none, and is still bounded by the
/// plane's: that chain is the most this plane may do for anybody, so its
/// scope and its admissibility gate the plan
/// ([`ceiling`](Self::ceiling)) while nothing of it reaches the policy
/// context, the journal or a withdrawal lookup.
#[derive(Debug, Clone, Default)]
enum Acting {
    /// The plane's own chain, if it has one: a run the embedder started.
    #[default]
    Plane,
    /// The chain an authenticated caller presented.
    Caller(crate::core::Delegation),
    /// A served caller that presented no chain: this run acts under none.
    Nobody,
    /// A chain delegated from the plane's own, for a run the plane's run
    /// commissioned: it acts under that chain, and as the plane, so a peer
    /// it calls is presented the plane's credential rather than one naming
    /// the plane's owner as if a person had asked.
    PlaneDelegate(crate::core::Delegation),
}

impl Acting {
    /// The chain this run acts under, given the plane's own.
    const fn resolve<'a>(
        &'a self,
        plane: Option<&'a crate::core::Delegation>,
    ) -> Option<&'a crate::core::Delegation> {
        match self {
            Self::Plane => plane,
            Self::Caller(chain) | Self::PlaneDelegate(chain) => Some(chain),
            Self::Nobody => None,
        }
    }

    /// The chain that bounds what this run may be admitted for: the one it
    /// acts under, or — for a served caller that presented none — the
    /// plane's, which it does not act under.
    const fn ceiling<'a>(
        &'a self,
        plane: Option<&'a crate::core::Delegation>,
    ) -> Option<&'a crate::core::Delegation> {
        match self {
            Self::Plane | Self::Nobody => plane,
            Self::Caller(chain) | Self::PlaneDelegate(chain) => Some(chain),
        }
    }
}

impl RunTerms {
    fn bound(case: CaseBinding) -> Self {
        Self {
            case: Some(case),
            idempotency_key: None,
            acting_as: Acting::Plane,
            admitted_by: None,
            expected_declaration: None,
            subjects: Vec::new(),
        }
    }

    /// Run inside a case that already exists.
    #[must_use]
    pub fn in_case(mut self, case: crate::core::CaseId) -> Self {
        self.case = Some(CaseBinding::Existing(case));
        self
    }

    /// Join or open a case by business key before running.
    #[must_use]
    pub fn correlated(mut self, kind: &str, keys: &[CorrelationKey]) -> Self {
        self.case = Some(CaseBinding::Correlate {
            kind: kind.to_owned(),
            keys: keys.to_vec(),
        });
        self
    }

    /// Admit at most once under this key — see [`Runtime::run_once`].
    #[must_use]
    pub fn once(mut self, idempotency_key: &str) -> Self {
        self.idempotency_key = Some(idempotency_key.to_owned());
        self
    }

    /// Act under this chain rather than the plane's own.
    ///
    /// Checked at admission exactly as the plane's chain is: the plan must be
    /// inside its scope, and [`Delegation::admissible`] must accept this
    /// plane at this instant. Journaled as the run's `IdentityBound`, so
    /// "on whose behalf" names the caller and not the plane.
    ///
    /// [`Delegation::admissible`]: crate::core::Delegation::admissible
    #[must_use]
    pub fn acting_as(mut self, chain: crate::core::Delegation) -> Self {
        self.acting_as = Acting::Caller(chain);
        self
    }

    /// Act under `chain` as the plane: a commission from a run the plane
    /// itself admitted, whose sub-run is the plane's work one link down.
    pub(crate) fn acting_as_plane(mut self, chain: crate::core::Delegation) -> Self {
        self.acting_as = Acting::PlaneDelegate(chain);
        self
    }

    /// Act for a served caller: under the chain its credential carried, or
    /// under **none** — never the plane's.
    ///
    /// The door every surface that admits work for somebody else goes through.
    /// [`acting_as`](Self::acting_as) alone cannot say "this caller presented
    /// nothing", and leaving it unset means the plane's own chain.
    #[must_use]
    pub fn served(mut self, chain: Option<crate::core::Delegation>) -> Self {
        self.acting_as = chain.map_or(Acting::Nobody, Acting::Caller);
        self
    }

    /// Record who asked for this run: the authenticated caller a served
    /// surface admitted it for, or the operator an embedder started it on
    /// behalf of.
    ///
    /// Journaled as `RunAdmitted.admitted_by`, and excluded from deciding
    /// every task the run opens — the four-eyes control, applied to the one
    /// actor a declarative agent's approvals could not otherwise name. A
    /// caller who could approve the call their own request produced would be
    /// one person on both sides of the review.
    #[must_use]
    pub fn admitted_by(mut self, actor: impl Into<String>) -> Self {
        self.admitted_by = Some(actor.into());
        self
    }

    /// Attribute what this run takes in to a data subject.
    ///
    /// Recorded in the run's `DataSubjectBound` after any subjects its
    /// declaration binds, so `agentplane subject` follows the run's input,
    /// events and case state to the effects they reached. Attribution only:
    /// no gate reads it.
    #[must_use]
    pub fn subject(mut self, subject: impl Into<String>) -> Self {
        self.subjects.push(subject.into());
        self
    }

    /// Admit only if this declaration revision governs the capability.
    ///
    /// For a caller that reviewed one revision and schedules runs against a
    /// plane it does not control: another revision — or no declaration at
    /// all, including on a build without the `manifest` feature — is refused
    /// as [`RuntimeError::DeclarationPinMismatch`] before authorization, and
    /// nothing is recorded.
    #[must_use]
    pub const fn expect_declaration(mut self, digest: Digest) -> Self {
        self.expected_declaration = Some(digest);
        self
    }

    fn keyed(self, key: &str) -> Self {
        self.once(key)
    }
}

/// Default lease duration. A crashed owner's runs become claimable this long
/// after its last heartbeat.
///
/// This bounds how long a *dead* owner's runs are stranded, not how long a run
/// may take: a live run renews while it executes. Set per plane with
/// [`RuntimeBuilder::lease_ttl`].
pub const LEASE_TTL: Duration = Duration::from_secs(30);

/// The shortest lease a live run can actually hold.
///
/// Both stores keep expiry in whole seconds and lapse on `expires_at <= now`, so
/// a one-second lease is expired for part of every second it exists. Two is the
/// smallest value a renewal can stay ahead of.
pub const MIN_LEASE_TTL: Duration = Duration::from_secs(2);

/// What a run produced.
#[derive(Debug, Clone)]
pub struct RunOutcome {
    pub run_id: RunId,
    pub status: RunStatus,
    /// What this run consumed — steps, effects, spend, elapsed, refusals.
    ///
    /// Reported rather than left in the ledger because "what did the settlement
    /// run cost" has to be answerable per item, and a batch sums its items. A
    /// figure that only exists inside a dropped `Ledger` is a figure nobody can
    /// bill against.
    ///
    /// The whole tally rather than only the money: the counts are what a
    /// ceiling is sized against, and an operator raising `max_effects` after a
    /// run stopped short is asking exactly the question this answers.
    pub consumed: Consumed,
    /// Terminal hash of the run's chain — what a signature would cover.
    pub chain_head: Digest,
    /// What the run produced, **with its label**.
    ///
    /// Labelled rather than bare, and the difference is not cosmetic: a
    /// caller acting on a run's answer needs to know whether a model, a peer
    /// or a person wrote it. The label was stripped here until an A2A reply
    /// projection read a marker key out of an untrusted answer and let a
    /// remote peer choose the envelope its own reply arrived in — a
    /// confused-deputy reachable because the one fact that would have refused
    /// it had been dropped at the boundary.
    pub output: Option<Tainted<Value>>,
}

impl RunOutcome {
    /// What this run spent, in metered units — the money half of
    /// [`consumed`](Self::consumed).
    #[must_use]
    pub const fn spend(&self) -> Spend {
        self.consumed.spend
    }

    /// Why this run ended — [`RunStatus::reason`] without the match.
    ///
    /// `None` for a success. The accessor is here as well as on the status
    /// because this is the type an embedder holds after `run(..)`, and a
    /// summary field that silently stays empty is the shape this exists to
    /// prevent.
    #[must_use]
    pub fn reason(&self) -> Option<std::borrow::Cow<'_, str>> {
        self.status.reason()
    }

    /// The output if the run succeeded, or a [`RunFailure`] saying why not.
    ///
    /// Every caller that acts on a run's answer asks the same two questions —
    /// did it work, and what did it say — and pattern-matching
    /// [`status`](Self::status) to learn the first is how the second gets read
    /// off a run that quarantined. This folds the pair into one `?`:
    ///
    /// ```ignore
    /// let answer = runtime.run("greet", input).await?.success()?;
    /// ```
    ///
    /// `status` stays public for the callers whose branches genuinely differ —
    /// a suspended run is not a failed one, and an operator surface treats
    /// them differently. This is for the caller to whom anything short of an
    /// answer is an error.
    ///
    /// # Errors
    ///
    /// [`RunFailure`] for every non-succeeded status, carrying the run id and
    /// the status itself.
    pub fn success(self) -> Result<Tainted<Value>, RunFailure> {
        match self.status {
            // A succeeded run's answer; `Null` for the degenerate run that
            // finished without producing one, which is still a success.
            RunStatus::Succeeded => {
                Ok(self.output.unwrap_or_else(|| Tainted::trusted(Value::Null)))
            }
            status => Err(RunFailure {
                run_id: self.run_id,
                status,
            }),
        }
    }
}

/// What an idempotent admission did.
///
/// A duplicate comes back as an answer rather than an error: a caller that
/// retried wants the original run, not a conflict it has to interpret.
///
/// Exhaustive, unlike the error types: a key is unused, or held by a run that
/// has rested, or held by one that has not. There is no fourth state to leave
/// room for, and `#[non_exhaustive]` would cost every caller a `_` arm that
/// means nothing.
#[derive(Debug, Clone)]
pub enum Admission {
    /// The key was unused. This run is the one it admitted.
    Fresh(RunOutcome),
    /// The key already admitted a run that has reached a resting point —
    /// concluded, or suspended waiting for something. Its answer, again.
    ///
    /// A suspension counts, and that is the case this exists for: a run parked
    /// on a four-eyes decision has already opened the task, so a redelivery
    /// that admitted would put a second identical approval in front of a
    /// reviewer.
    ///
    /// Carries no `output`. A step's result is reconstructed by replay rather
    /// than stored, so what the journal answers is *what happened* — status,
    /// reason, chain head. Re-derive the value with [`replay`](Runtime::replay)
    /// under [`Mode::Strict`], which performs no external effect.
    Replayed(RunOutcome),
    /// The key already admitted a run that has not rested yet — still
    /// executing, or abandoned and awaiting the recovery sweep.
    ///
    /// The honest answer to an emitter is *accepted, already in progress* — a
    /// 200 or 202 naming this run, never a retry-provoking failure.
    InFlight(RunId),
}

impl Admission {
    /// The run this key admitted, whichever of the three this is.
    #[must_use]
    pub const fn run_id(&self) -> RunId {
        match self {
            Self::Fresh(outcome) | Self::Replayed(outcome) => outcome.run_id,
            Self::InFlight(run) => *run,
        }
    }

    /// Whether this call is the one that admitted the run.
    #[must_use]
    pub const fn is_fresh(&self) -> bool {
        matches!(self, Self::Fresh(_))
    }

    /// What the run produced, if it has produced anything yet.
    #[must_use]
    pub const fn outcome(&self) -> Option<&RunOutcome> {
        match self {
            Self::Fresh(outcome) | Self::Replayed(outcome) => Some(outcome),
            Self::InFlight(_) => None,
        }
    }

    /// What the run produced, owned, if it has produced anything yet.
    #[must_use]
    pub fn into_outcome(self) -> Option<RunOutcome> {
        match self {
            Self::Fresh(outcome) | Self::Replayed(outcome) => Some(outcome),
            Self::InFlight(_) => None,
        }
    }
}

/// What an idempotent [`spawn_correlated_once`](Runtime::spawn_correlated_once)
/// did.
///
/// Separate from [`Admission`] because a spawn returns before the work happens,
/// so it has no outcome to report.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Spawned {
    /// The run holding the key: the one just started, or the one that already
    /// held it.
    pub run: RunId,
    /// False when the key was already held, so nothing new was started.
    pub fresh: bool,
}

/// The stores a full plane runs on, as handles rather than as one type.
///
/// [`Runtime::builder_on`] is the shorthand for one backend implementing all
/// of them, and is the wrong shape for a caller that picks its backend at **run
/// time** — an operator naming either a file or a connection string holds
/// `Arc<dyn JournalStore>`, and unsizing a generic parameter needs it `Sized`,
/// so the wiring is a value that `builder_on` builds.
///
/// Here rather than in [`store`](crate::store) because that module is the
/// backends, gated on `redb` or `postgres`, while this exists whether or not
/// either is compiled in.
#[derive(Clone)]
pub struct Stores {
    pub journal: std::sync::Arc<dyn crate::journal::JournalStore>,
    pub cases: std::sync::Arc<dyn crate::case::CaseStore>,
    pub tasks: std::sync::Arc<dyn crate::case::TaskStore>,
    pub events: std::sync::Arc<dyn crate::case::EventStore>,
    pub timers: std::sync::Arc<dyn crate::case::TimerStore>,
    pub memory: std::sync::Arc<dyn crate::memory::MemoryStore>,
    /// Where halts, subject withdrawals, rate windows and tenant ceilings live.
    pub quotas: std::sync::Arc<dyn crate::quota::QuotaStore>,
    /// Where disclosures of a matter are recorded.
    pub disclosures: std::sync::Arc<dyn crate::disclosure::DisclosureRegister>,
}

impl std::fmt::Debug for Stores {
    /// The handles are trait objects with no identity to print, so what a reader
    /// wants here is *that the set is complete*, which it is by construction.
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str("Stores { journal, cases, tasks, events, timers, memory, quotas, disclosures }")
    }
}

impl Stores {
    /// Every store from one backend that implements all of them.
    #[must_use]
    pub fn on<B: FullBackend + 'static>(store: std::sync::Arc<B>) -> Self {
        Self {
            journal: std::sync::Arc::clone(&store) as _,
            cases: std::sync::Arc::clone(&store) as _,
            tasks: std::sync::Arc::clone(&store) as _,
            events: std::sync::Arc::clone(&store) as _,
            timers: std::sync::Arc::clone(&store) as _,
            memory: std::sync::Arc::clone(&store) as _,
            quotas: std::sync::Arc::clone(&store) as _,
            disclosures: store as _,
        }
    }
}

/// How far into a run's history [`Runtime::running_runs`] reads to attribute it.
///
/// `RunAdmitted` is seq 1 and `IdentityBound` follows it when the caller
/// presented a chain, with the quota pass and the frozen plan between them — so
/// a handful of records carries both and a long-running agent's history is not
/// scanned to answer *who is this*.
const ATTRIBUTION_RECORDS: usize = 8;

/// One run this tenant currently holds an admission slot for.
///
/// What [`Runtime::running_runs`] answers with. The ids alone would be a listing
/// an operator reads out; the attribution is what makes it one they can act on.
#[derive(Debug, Clone)]
pub struct LiveRun {
    pub run: RunId,
    /// The declared agent governing it, when a declared one does.
    ///
    /// `None` for a skill registered directly on the plane — a legitimate shape,
    /// and one an incident about *a bad revision* can therefore rule out.
    pub governed_by: Option<crate::journal::AgentIdentity>,
    /// Who this run acts for: the root of the delegation chain bound at
    /// admission, when the caller presented one.
    pub subject: Option<String>,
    /// The slot is held by a run whose lease has lapsed, so no process is
    /// executing it.
    ///
    /// Not a cancellation candidate: the recovery sweep resumes these, and
    /// cancelling one unwinds work that was about to continue.
    pub stranded: bool,
}

/// A run that stopped short of an answer, as an error a caller can `?`.
///
/// Carries the [`RunStatus`] whole rather than a flattened string, so a caller
/// that started with [`RunOutcome::success`] and later needs to tell a
/// suspension from a quarantine can match on [`status`](Self::status) without
/// re-plumbing the call site.
#[derive(Debug, Clone)]
pub struct RunFailure {
    pub run_id: RunId,
    pub status: RunStatus,
}

/// **Total, including over the status this type is not supposed to hold.**
///
/// `status` is public and `RunStatus` carries `Succeeded`, so a
/// `RunFailure { status: Succeeded }` is a value any caller can build. Asserting
/// that away would make *formatting an error* the operation that panics, and a
/// `Display` impl runs wherever an error is logged — disproportionately during
/// an incident. So it prints the contradiction instead.
impl std::fmt::Display for RunFailure {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        if matches!(self.status, RunStatus::Succeeded) {
            return write!(
                f,
                "run {} is recorded as a failure carrying a success — \
                 whatever built this value did so wrongly",
                self.run_id
            );
        }
        write!(f, "run {} did not succeed: ", self.run_id)?;
        match &self.status {
            RunStatus::Succeeded => write!(f, "it succeeded"),
            RunStatus::Failed(reason) => write!(f, "it failed — {reason}"),
            RunStatus::Suspended(reason) => write!(f, "it is suspended — {reason:?}"),
            RunStatus::Exhausted(limit) => write!(f, "a budget stopped it — {limit}"),
            RunStatus::Quarantined(reason) => write!(f, "it is quarantined — {reason}"),
            RunStatus::Replanning(reason) => write!(f, "it asked to replan — {reason}"),
            RunStatus::Observed => write!(
                f,
                "it is a session this plane observed rather than executed, so it \
                 neither succeeded nor failed"
            ),
            RunStatus::Cancelled { actor, reason } => {
                write!(f, "{actor} cancelled it — {reason}")
            }
            RunStatus::Swept => write!(f, "the plane recorded a pass over its own state"),
            RunStatus::BrokeGlass { actor, reason } => {
                write!(f, "{actor} crossed into this tenant — {reason}")
            }
            RunStatus::HaltLifted { actor } => write!(f, "{actor} lifted an emergency stop"),
            RunStatus::HoldReleased { actor } => write!(f, "{actor} released a legal hold"),
            RunStatus::Abandoned { actor, reason } => {
                write!(
                    f,
                    "{actor} abandoned it, unresolved and not unwound — {reason}"
                )
            }
            RunStatus::Withheld { subject, reason } => {
                write!(
                    f,
                    "the authority it acts for — '{subject}' — was withdrawn: {reason}"
                )
            }
        }
    }
}

impl std::error::Error for RunFailure {}

#[derive(Debug, Clone, PartialEq)]
pub enum RunStatus {
    /// All terminal work completed.
    ///
    /// Structural, never self-reported: a skill saying "done" is not what makes
    /// a run succeed. Agents confidently announce success on unmet objectives,
    /// so completion is determined by the runtime, not claimed by the workload.
    Succeeded,
    Failed(String),
    /// Waiting for something that has not happened. The frame is persisted and
    /// the task is gone: a suspended run costs disk, not a thread.
    Suspended(crate::core::SuspendReason),
    /// A limit stopped it. Not a fault — the run did what it was told, and what
    /// it was told included a ceiling.
    Exhausted(crate::core::BudgetExceeded),
    /// Needs human resolution before anything else may happen to it.
    Quarantined(String),
    /// A step asked for a different plan.
    ///
    /// Never observed by a caller: the executor either produces a successor and
    /// keeps going, or turns this into a failure with the reason it refused.
    /// It exists as a status so a step's request travels the same path every
    /// other outcome does.
    Replanning(String),
    /// An operator stopped it.
    ///
    /// Distinct from `Failed` on purpose. A failure is the run discovering it
    /// cannot proceed; a cancellation is a human deciding it should not. They
    /// call for different responses — one is investigated, the other was
    /// intended — and an operator scanning for failures should not have to
    /// mentally subtract their own interventions.
    ///
    /// Completed steps are unwound exactly as they are for a failure: stopping a
    /// run that has moved money and leaving the movement in place is not
    /// stopping it.
    Cancelled {
        actor: crate::core::Operator,
        reason: String,
    },
    /// An operator closed a run whose outcome could never be established.
    ///
    /// The end of the road for a quarantine nobody can answer. Distinct from
    /// `Cancelled` in the one way that matters to whoever reads it next:
    /// **nothing was unwound**. A cancellation puts the world back; this leaves
    /// it exactly as the run left it, because compensating around an unknown
    /// outcome is the single thing quarantine exists to forbid, and an
    /// operator's patience running out is not new evidence.
    ///
    /// So the doubt does not go away when the run does. It stops being a
    /// *status* — which is a mutable thing a later action can overwrite — and
    /// becomes an `agentplane audit` finding, which is derived from the journal
    /// and outlives every status the run will ever have.
    Abandoned {
        actor: crate::core::Operator,
        reason: String,
    },
    /// A pass this plane made over its own state, journaled as a run of its own.
    ///
    /// The sweep records what it decided — which obligations breached, which
    /// tasks it escalated, which runs it took over — rather than logging it, so
    /// *who decided what* is answerable from the chain six weeks later. It is
    /// not `Succeeded` because nothing asked for it and there is no answer to
    /// hand back: a sweep is the plane reporting on itself.
    Swept,
    /// An operator crossed into this tenant deliberately, and the reason they
    /// gave for it.
    ///
    /// The one exception to tenant isolation, and the exception's entire value
    /// is this record. Both halves are carried because an incident review asks
    /// two questions and neither is worth less than the other: `actor` is read
    /// back from the crossing record, `reason` from the conclusion, and a
    /// crossing cannot be recorded without one.
    BrokeGlass {
        actor: crate::core::Operator,
        reason: String,
    },
    /// An operator lifted an emergency stop, recorded as a run of its own.
    ///
    /// `actor` is read back from the run's
    /// [`HaltLifted`](crate::journal::RecordKind::HaltLifted) record, which
    /// also holds the stop it ended.
    HaltLifted {
        actor: crate::core::Operator,
    },
    /// An operator released a legal hold, recorded as a run of its own.
    ///
    /// `actor` is read back from the run's
    /// [`HoldReleased`](crate::journal::RecordKind::HoldReleased) record.
    HoldReleased {
        actor: crate::core::Operator,
    },
    /// The authority this run acts under was withdrawn while it was running.
    ///
    /// **A pause, not a fault**, for the reason exhaustion is one: the run did
    /// nothing wrong. Its mutations stand and it stays resumable — lift the halt
    /// and it continues. Unwinding would reverse correct work for a reason
    /// unrelated to it; cancelling is the verb for that.
    ///
    /// Carries the subject, because *whose* authority is what an operator
    /// matches against the withdrawal they made.
    Withheld {
        subject: String,
        reason: String,
    },
    /// A session this plane **observed** rather than executed, closed.
    ///
    /// The one status that is not about work this runtime did. A seat beside
    /// somebody else's agent produces records at the *asserted* rung
    /// ([`RecordKind::Observed`](crate::journal::RecordKind::Observed)), in a
    /// run of their own with no admission — the shape a sweep's run already
    /// takes — so that they share the chain, the Merkle log and the witness
    /// while sharing no record kind with a dispatched effect.
    ///
    /// **It carries nothing, and the absence is the design.** There is no
    /// reason to give: the session ended because the party running it ended
    /// it, and this plane is in no position to say why. The session's own
    /// identifier is on every observation record rather than here, so a plane
    /// that stopped mid-session still leaves evidence that says which session
    /// it describes.
    ///
    /// Sealed like any other ending, so an external verifier checks it without
    /// being taught what an observation is. Never resumable: there is nothing
    /// to resume onto, because nothing here was executing.
    Observed,
}

impl RunStatus {
    /// Why the run ended, whatever kind of ending it was.
    ///
    /// `None` only for [`Succeeded`](Self::Succeeded), which has no reason to
    /// give. Every other conclusion carries one, and the point of gathering
    /// them here is that an embedder mapping outcomes onto its own wire type
    /// should not have to match every variant to find the sentence, and an
    /// embedder that reads only the status ships an empty summary on failure.
    ///
    /// Borrowed where the variant already holds a string and formatted where
    /// it holds a typed value: a suspension names what it waits for and an
    /// exhaustion names the ceiling it hit, and both are worth more than the
    /// word "suspended". `Cancelled` yields the operator's reason; the actor
    /// who gave it stays on the variant, because *why* and *who* are two
    /// questions and only one of them is the reason.
    #[must_use]
    pub fn reason(&self) -> Option<std::borrow::Cow<'_, str>> {
        use std::borrow::Cow;
        match self {
            // Nothing to say, for three different reasons and one answer: a
            // success has no why, a sweep's records carry theirs, and an
            // observed session ended because somebody else ended it.
            // A lift's record carries what it ended; the lifter gave no reason.
            Self::Succeeded
            | Self::Swept
            | Self::Observed
            | Self::HaltLifted { .. }
            | Self::HoldReleased { .. } => None,
            Self::Failed(reason)
            | Self::Quarantined(reason)
            | Self::Replanning(reason)
            | Self::Cancelled { reason, .. }
            | Self::Abandoned { reason, .. }
            | Self::BrokeGlass { reason, .. }
            | Self::Withheld { reason, .. } => Some(Cow::Borrowed(reason.as_str())),
            Self::Suspended(reason) => Some(Cow::Owned(reason.to_string())),
            Self::Exhausted(exceeded) => Some(Cow::Owned(exceeded.to_string())),
        }
    }

    /// The run's **own** account of why it ended, for the journal.
    ///
    /// [`reason`](Self::reason) answers *what should a person be shown*, which
    /// includes the words an operator typed when they stopped the run. This
    /// answers the narrower question the conclusion record asks: *is there a
    /// sentence here that nothing else on the chain already records?*
    ///
    /// `None` for every ending a person caused. Those write their own record —
    /// [`RunCancelled`](crate::journal::RecordKind::RunCancelled),
    /// [`QuarantineDecided`](crate::journal::RecordKind::QuarantineDecided),
    /// [`BreakGlass`](crate::journal::RecordKind::BreakGlass),
    /// [`AuthorityWithheld`](crate::journal::RecordKind::AuthorityWithheld) —
    /// carrying the actor and the reason together, in the clear. Repeating the
    /// reason on the conclusion would make one sentence two facts, and seal the
    /// copy that an erasure then destroys.
    ///
    /// `None` for an exhaustion too: the typed ceiling verdict is the record,
    /// and the prose was a rendering of it.
    #[must_use]
    pub fn own_account(&self) -> Option<std::borrow::Cow<'_, str>> {
        use std::borrow::Cow;
        match self {
            // The runtime's own endings: a skill's words, a provider's words,
            // a divergence this build found. Nothing else on the chain says it.
            Self::Failed(reason) | Self::Quarantined(reason) | Self::Replanning(reason) => {
                Some(Cow::Borrowed(reason.as_str()))
            }
            // Nothing to add, for two different reasons and one answer. The
            // first four are somebody's doing and their own record already
            // carries both halves. The rest either write no conclusion with a
            // why — a success, a sweep, a suspension — or carry it typed
            // instead, which is what `exhaustion` is.
            //
            // Enumerated rather than left to a wildcard: a status added later
            // must be made to answer this question, and `_ => None` would
            // answer it silently and wrongly for anything a person causes.
            Self::Cancelled { .. }
            | Self::Abandoned { .. }
            | Self::BrokeGlass { .. }
            | Self::HaltLifted { .. }
            | Self::HoldReleased { .. }
            | Self::Withheld { .. }
            | Self::Succeeded
            | Self::Swept
            // The account is the observation records themselves, and this plane
            // has none of its own to add: it did not run the session.
            | Self::Observed
            | Self::Suspended(_)
            | Self::Exhausted(_) => None,
        }
    }

    /// Whether the run stopped without reaching a conclusion.
    #[must_use]
    pub fn is_suspended(&self) -> bool {
        matches!(self, Self::Suspended(_))
    }

    /// Whether the recorded history can no longer be trusted to describe this
    /// code, so a human must look before anything else happens.
    #[must_use]
    pub fn is_quarantined(&self) -> bool {
        matches!(self, Self::Quarantined(_))
    }

    #[must_use]
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::Succeeded => "succeeded",
            Self::Failed(_) => "failed",
            Self::Suspended(_) => "suspended",
            Self::Exhausted(_) => "exhausted",
            Self::Quarantined(_) => "quarantined",
            Self::Replanning(_) => "replanning",
            Self::Cancelled { .. } => "cancelled",
            Self::Abandoned { .. } => "abandoned",
            Self::Swept => super::sweeper::SWEEP_OUTCOME,
            Self::BrokeGlass { .. } => BREAK_GLASS_OUTCOME,
            Self::HaltLifted { .. } => HALT_LIFTED_OUTCOME,
            Self::HoldReleased { .. } => HOLD_RELEASED_OUTCOME,
            Self::Withheld { .. } => WITHHELD_OUTCOME,
            Self::Observed => OBSERVED_OUTCOME,
        }
    }

    /// Who brought this run to this state, where a person did.
    ///
    /// `None` for every ending the runtime reached on its own, which is most of
    /// them. One accessor rather than three `matches!` at each surface, because
    /// *who* is the question an operator asks immediately after *what* — and a
    /// surface that reads the reason and drops the actor answers half of it.
    #[must_use]
    pub fn actor(&self) -> Option<&crate::core::Operator> {
        match self {
            Self::Cancelled { actor, .. }
            | Self::Abandoned { actor, .. }
            | Self::BrokeGlass { actor, .. }
            | Self::HaltLifted { actor }
            | Self::HoldReleased { actor } => Some(actor),
            // A withdrawal names a *subject*, not an actor: the operator who
            // threw the halt and the credential it covers are different
            // parties, and answering "who" with the subject would report the
            // person whose authority was taken as the one who took it.
            Self::Succeeded
            | Self::Failed(_)
            | Self::Suspended(_)
            | Self::Exhausted(_)
            | Self::Quarantined(_)
            | Self::Replanning(_)
            | Self::Withheld { .. }
            | Self::Swept
            // Somebody was at the keyboard, and it was not this plane's
            // operator. Naming the observed party's user here would report a
            // person this runtime never authenticated as one of its own.
            | Self::Observed => None,
        }
    }

    /// Whether an operator stopped this run.
    #[must_use]
    pub fn is_cancelled(&self) -> bool {
        matches!(self, Self::Cancelled { .. })
    }

    /// Whether this conclusion freezes the journal and enters the Merkle log.
    ///
    /// Only conclusions that nothing may resume seal. A failed run may be
    /// resumed — its completed effects are read back from history rather than
    /// performed again, which is the point of having a journal — and an
    /// exhausted run may continue once somebody raises the ceiling. Sealing
    /// either would commit the Merkle log to a leaf its own resume is then
    /// permitted to grow past: the checkpoint would attest a prefix of a
    /// history that kept moving, and the store's refusal of appends after a
    /// seal would turn every legitimate resume into an error.
    ///
    /// **A quarantine does not seal**, and that follows from the same rule
    /// rather than being an exception to it. A quarantine is the runtime saying
    /// it does not know, which is a story that is not over; a Merkle leaf is a
    /// claim that a history is complete. Sealing one published a proof of
    /// completeness over an admittedly incomplete record, and — the practical
    /// half — froze the journal against the one record that answers it, so
    /// "a human must resolve it before it can run again" named a resolution the
    /// format made impossible. It enters the log when it reaches a real ending,
    /// including [`Abandoned`](Self::Abandoned), which is a person deciding
    /// there will never be one.
    ///
    /// This is the **one** implementation of that rule. `resume_is_closed`
    /// refuses exactly the outcomes this method seals — a test pins the
    /// agreement — because two copies of one rule agree everywhere except the
    /// boundary nobody probed.
    #[must_use]
    pub fn seals(&self) -> bool {
        matches!(
            self,
            Self::Succeeded
                | Self::Cancelled { .. }
                | Self::Abandoned { .. }
                | Self::Swept
                | Self::BrokeGlass { .. }
                | Self::HaltLifted { .. }
                | Self::HoldReleased { .. }
                | Self::Observed
        )
    }
}

/// Every outcome a sealed run can carry, as the outcome index spells them.
///
/// The store indexes runs *by* outcome and deliberately has no "all runs"
/// query — a backlog listing is a range read rather than a table scan — so any
/// caller that wants every sealed run has to name the outcomes one by one. This
/// is the list to name them from, and it lives beside [`RunStatus::seals`]
/// because it is the same rule in its other spelling: exactly the statuses that
/// seal, with no exception clause. A sweep (`swept`) and a break-glass crossing
/// (`broke-glass`) are sealed at birth with no goal to have succeeded or failed
/// at, and they are statuses all the same — an ending this plane writes and its
/// own reader cannot name is an ending it reports as unrecognised.
///
/// It lived in the CLI first, as string literals — two implementations of one
/// rule, where a new sealing outcome would have been exported by nobody and
/// the export that silently omitted it would have dropped exactly the runs an
/// auditor came for. A test holds this list to `RunStatus::seals` variant by
/// variant, which the literals in a binary could never be held to.
pub const SEALED_OUTCOMES: &[&str] = &[
    "succeeded",
    "cancelled",
    "abandoned",
    super::sweeper::SWEEP_OUTCOME,
    BREAK_GLASS_OUTCOME,
    HALT_LIFTED_OUTCOME,
    HOLD_RELEASED_OUTCOME,
    OBSERVED_OUTCOME,
];

/// What an offline verb sweeps when the operator names no outcome.
///
/// Every ending — [`SEALED_OUTCOMES`] — **plus `quarantined`**, which is not an
/// ending and is exactly why it belongs: a run set aside for a person is the
/// plane's outstanding unresolved risk, and an artifact holding everything that
/// finished and nothing that did not is not the one an auditor came for. It is
/// also the outcome most likely to be the reason they came.
///
/// Failed and exhausted runs are deliberately absent, and the distinction is
/// not sealing but *whether anything is waiting on a person*. Those two are
/// work in progress that a resume moves on its own; a quarantine moves only
/// when somebody decides, so it can sit for weeks and still be current.
///
/// A test holds this to [`SEALED_OUTCOMES`] rather than restating it, so a new
/// ending is swept here the day it exists.
pub const OUTCOMES_OF_RECORD: &[&str] = &[
    "succeeded",
    "cancelled",
    "abandoned",
    "quarantined",
    super::sweeper::SWEEP_OUTCOME,
    BREAK_GLASS_OUTCOME,
    HALT_LIFTED_OUTCOME,
    HOLD_RELEASED_OUTCOME,
    OBSERVED_OUTCOME,
];

/// How a resume came to hold its lease, which decides what a failure does
/// with it.
///
/// A lease that lapses while still naming an owner is what the recovery sweep
/// lists, so keeping one on failure is how a run stays findable; releasing it
/// is right only where the run is findable without it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Claim {
    /// Claimed by the resume itself, over a run whose journal already lists
    /// it — failed, exhausted, withheld, quarantined, waiting.
    Standing,
    /// Handed over by a wake or a delivery that recorded the awaited result
    /// under it, which took the run off the waiting listing.
    Unlisted,
    /// Claimed by the recovery sweep over a lease its owner died holding.
    Recovering,
}

/// A run that exists but has not run.
///
/// Produced by admission and consumed by execution, so the two can happen in
/// different places — the same request for a blocking call, and a background
/// task for a non-blocking one.
struct Admitted {
    run: RunId,
    epoch: crate::core::Epoch,
    quota: QuotaPass,
    budget: Budget,
    agent: String,
    plan: PlanIR,
    input: Tainted<Value>,
    case: Option<CaseContext>,
    /// The chain admission bound — the caller's where one was presented,
    /// the plane's otherwise — and what every step of this run acts under.
    identity: Option<crate::core::Delegation>,
    /// The references its `DataSubjectBound` record makes available.
    subjects: BTreeSet<crate::core::SubjectRef>,
}

/// The quota identity of one live execution pass.
///
/// Captured once at admission or resume and carried to settlement. Computing
/// the period again after the work finishes can cross a day or month boundary,
/// authorizing against one ledger and charging another.
#[derive(Debug, Clone, Default)]
struct QuotaPass {
    period: Option<String>,
    enabled: bool,
    release_slot: bool,
    /// How many steps this pass may dispatch at once, when the tenant bounds
    /// spend: the width the run's reservation was sized for. `None` leaves
    /// the run's own budget as the only bound.
    width: Option<usize>,
}

impl QuotaPass {
    fn at(
        quota: &crate::quota::TenantQuota,
        at: crate::core::Timestamp,
        release_slot: bool,
    ) -> Self {
        Self {
            period: quota.bounds_spend().then(|| quota.period.key_for(at)),
            enabled: true,
            release_slot,
            width: None,
        }
    }

    const fn disabled() -> Self {
        Self {
            period: None,
            enabled: false,
            release_slot: false,
            width: None,
        }
    }

    /// Held to the width a spend reservation was sized for, whenever the
    /// tenant bounds spend.
    fn sized_for(mut self, width: usize) -> Self {
        if self.period.is_some() {
            self.width = Some(width);
        }
        self
    }

    /// How wide this pass may dispatch: the budget's own width, narrowed to
    /// the one its reservation was sized for. A replan may widen the plan; it
    /// does not widen what the period holds for it.
    fn parallelism(&self, budget: &Budget) -> usize {
        self.width
            .map_or_else(|| budget.parallelism(), |w| budget.parallelism().min(w))
    }

    fn period(&self) -> Option<&str> {
        self.period.as_deref()
    }

    fn started(&self) -> Option<RecordKind> {
        self.enabled.then(|| RecordKind::QuotaPassStarted {
            period: self.period.clone(),
            release_slot: self.release_slot,
        })
    }

    fn settlement(
        &self,
        run: RunId,
        epoch: crate::core::Epoch,
        spend: Spend,
        concludes: bool,
    ) -> Option<crate::quota::QuotaSettlement> {
        self.enabled.then(|| crate::quota::QuotaSettlement {
            run,
            epoch,
            period: self.period.clone(),
            spend,
            release_slot: self.release_slot,
            concludes,
        })
    }
}

/// How many steps a run may have in flight: its budget's width, or its
/// admitted plan's node count when that is narrower or nothing narrows it.
///
/// What a spend reservation multiplies the per-call bound by, since each step
/// in flight may hold one operation the ledger admitted and has not billed.
fn reserved_width(budget: &Budget, plan: &PlanIR) -> usize {
    budget.parallelism().min(plan.nodes.len()).max(1)
}

/// The peers a plane may call, and how it reaches them.
///
/// One value because the two are one decision: a registry says what each
/// peer is granted and which credential reaches it, and the client is the
/// transport those grants are spent over. Held by the plane and handed to
/// every step, so a skill calling a peer reaches it through the same checked
/// registry a declarative agent does — never one it carries itself.
#[derive(Debug)]
pub(crate) struct PeerWiring {
    pub(crate) registry: crate::peers::PeerRegistry,
    pub(crate) client: Arc<dyn crate::peers::PeerClient>,
}

/// Keeps a run's lease alive for as long as it is executing.
///
/// A lease answers one question — *is this owner dead?* — and it answers by
/// expiry. Without renewal it also answers a question it was never asked: a
/// healthy run that outlives its TTL looks exactly like a crashed one, and agent
/// runs routinely outlive a lease because a single model call can. Another
/// instance then takes the run over, bumps the epoch, and the original is fenced
/// on its next append: killed mid-flight, having already done real work.
///
/// Renewing while executing separates the two. The TTL then bounds how long a
/// *crashed* owner strands its runs, which is what it is for, and stops bounding
/// how long a run may take, which it should never have bounded.
///
/// Aborted on drop, so the renewal stops the moment execution returns — by any
/// path, including a panic unwinding through it. A heartbeat that outlived its
/// run would hold a lease nobody is using and strand it for a full TTL after a
/// crash, which is the failure this exists to prevent, arriving late.
struct Heartbeat(tokio::task::JoinHandle<()>);

impl Drop for Heartbeat {
    fn drop(&mut self) {
        self.0.abort();
    }
}

/// The runtime.
#[derive(Debug, Clone)]
pub struct Runtime {
    store: Arc<dyn JournalStore>,
    skills: HashMap<String, Arc<dyn Skill>>,
    by_capability: HashMap<Capability, String>,
    /// A handle to this plane, for steps that commission other agents on it.
    ///
    /// Weak, and that is not an optimisation: a strong self-reference would
    /// leak every runtime ever built. It exists because commissioning belongs to
    /// the *runtime* — a skill holding an `Arc<Runtime>` cannot work, since the
    /// runtime needs the skill before the skill can have the runtime.
    self_ref: std::sync::Weak<Self>,
    /// The declaration governing each skill, by skill name.
    ///
    /// Per skill rather than per runtime, because a plane runs several agents
    /// and a step must be judged against *its own* agent's manifest.
    #[cfg(feature = "manifest")]
    governed_by: HashMap<String, Arc<crate::manifest::Manifest>>,
    /// Which tenant this plane runs as.
    ///
    /// One plane serves one tenant; a **process** may run several and serve
    /// them all, because `api::Planes` resolves a plane from the authenticated
    /// caller's tenant. That is what the composite keys on both backends bought:
    /// the tenant leads every key, lease, correlation and blob path, so a query
    /// that forgets it misses rather than returning somebody else's rows.
    tenant: crate::core::TenantId,
    /// Who vouched for each declaration, by agent name.
    ///
    /// Separate from the manifest because it is *not* in it: a document cannot
    /// state who signed it. It arrives beside the manifest from a verified
    /// registry resolution, and an absent entry means nobody vouched.
    #[cfg(feature = "manifest")]
    published_by: HashMap<String, crate::core::KeyId>,
    /// Model drivers by the name a manifest calls them.
    ///
    /// Kept after build — not only consumed by it — so a *hand-written* skill
    /// can reach the driver its manifest's model role names through
    /// [`StepCtx::complete`], instead of smuggling an `Arc<dyn ModelProvider>`
    /// field past the declaration.
    #[cfg(feature = "manifest")]
    providers: HashMap<String, Arc<dyn crate::model::ModelProvider>>,
    owner: String,
    /// How long a run's lease lasts, and how long a crashed owner's runs stay
    /// unclaimable.
    lease_ttl: Duration,
    /// Where this plane's agents remember things, when a deployment wires one.
    memories: Option<Arc<dyn crate::memory::MemoryStore>>,
    semantic: Option<Arc<super::SemanticMemory>>,
    authorities: Option<Arc<dyn crate::authority::AuthorityStore>>,
    /// The peers this plane may call, and the transport that reaches them.
    peers: Option<Arc<PeerWiring>>,
    /// The catalogue and transport a **skill** reaches tools through.
    ///
    /// Held by the plane rather than handed to each skill, and that is the
    /// point. A skill that built its own [`ToolCatalog`] could declare a tool
    /// read-only that its manifest calls mutating — and `ToolSafety::read_only`
    /// carries `Recovery::Retry`, so a timed-out money-moving call gets sent
    /// again. `check_catalogue_not_laxer_than_grants` refuses exactly that for
    /// the plane's catalogue at build; a hand-built one never passed under it.
    /// `StepCtx::call_tool` is the path that cannot.
    #[cfg(feature = "manifest")]
    tools: Option<(
        Arc<crate::tools::ToolCatalog>,
        Arc<dyn crate::tools::ToolClient>,
    )>,
    /// The highest sensitivity this plane will write into an append-only
    /// record, when it says.
    journal_ceiling: Option<crate::core::Sensitivity>,
    /// Where this plane's tool transports may connect.
    ///
    /// Behind `manifest` because the tool path is.
    ///
    /// Here rather than on each `ToolClient` because it is a **plane**
    /// decision: the client owns the connection, the plane owns the
    /// destination, exactly as it does for a model driver's base URL. Absent
    /// means no egress control on the tool path, spelled the same way an
    /// absent policy engine is.
    #[cfg(feature = "manifest")]
    egress: Option<Arc<crate::core::Egress>>,
    #[cfg(feature = "manifest")]
    checkers: crate::content::Checkers,
    /// Where live model output is forwarded, when anything listens.
    streams: Option<Arc<dyn RunStreamObserver>>,
    /// How this plane attributes its metrics.
    meter: super::metrics::Meter,
    /// Durable per-tenant ceilings, when a deployment wires them.
    quotas: Option<Arc<dyn crate::quota::QuotaStore>>,
    /// The rate ceilings this plane's declarations state, and the quota store
    /// that counts them. `None` when no grant declares one.
    #[cfg(feature = "manifest")]
    rates: Option<Arc<super::ctx::Rates>>,
    quota: crate::quota::TenantQuota,
    budget: Budget,
    /// Whether every plan this runtime admits must carry a verifier.
    require_verifier: bool,

    cases: Option<Arc<dyn CaseStore>>,
    events: Option<Arc<dyn EventStore>>,
    tasks: Option<Arc<dyn TaskStore>>,
    timers: Option<Arc<dyn TimerStore>>,
    blobs: Option<Arc<dyn crate::blob::BlobStore>>,
    /// Where disclosures are recorded, read by a retention pass so it names
    /// the copies of what it erased.
    disclosures: Option<Arc<dyn crate::disclosure::DisclosureRegister>>,
    /// Where webhook registrations and their cursors live.
    ///
    /// Held by the plane rather than only by whoever delivers, because the
    /// registrations that stop being delivered are a **backlog**, and a backlog
    /// is answered by an operator on the plane's own surface — not by the
    /// worker that gave up on it.
    #[cfg(feature = "push")]
    push: Option<Arc<dyn crate::push::PushStore>>,
    /// Where data keys live, when payload bytes are sealed.
    #[cfg(feature = "keyring")]
    keyring: Option<Arc<dyn crate::keyring::KeyRing>>,
    batches: Option<Arc<dyn crate::batch::BatchStore>>,
    policy: Option<Arc<dyn crate::core::PolicyEngine>>,
    identity: Option<crate::core::Delegation>,
    replanner: Option<Arc<dyn crate::plan::Replanner>>,
    calendar: Arc<dyn Calendar>,
    signer: Option<Arc<dyn crate::core::Signer>>,
    /// Where this plane sends its own events, when a deployment configures it.
    ///
    /// Registered per run **at admission**, and again by every resume that
    /// executes: a destination attached after the first record would silently
    /// miss it, and "the journal is the outbox" only holds if the cursor starts
    /// at sequence one.
    #[cfg(feature = "push")]
    outbox: Option<Arc<crate::push::Outbox>>,
    /// The parties this plane submits its checkpoints to, and how many must
    /// answer.
    ///
    /// The one control here whose whole value is that it is **not** this
    /// plane: the chain, the signatures and the Merkle log all verify against
    /// inputs the operator supplies, so none of them detects a run removed or
    /// two histories shown to two auditors. Absent means the plane's history
    /// is anchored nowhere outside itself, which is a deployment decision and
    /// is reported as one by `audit`.
    witnesses: Option<Arc<Witnessing>>,
    /// The runs this instance put on a background task, and the gate that
    /// closes admission when it is asked to stop.
    ///
    /// Process-local on purpose: it answers *what is this instance executing
    /// right now*, which no other instance can be told and no store can hold.
    /// The durable cousin is [`Runtime::set_halt`], which stops a tenant
    /// everywhere and survives a restart — a different question with a
    /// different audience.
    inflight: Arc<super::drain::InFlight>,
}

/// The witness set and the bar a submission round is held to.
#[derive(Debug)]
pub(crate) struct Witnessing {
    pub(crate) witnesses: Vec<Arc<dyn crate::journal::Witness>>,
    pub(crate) quorum: crate::journal::WitnessQuorum,
    /// The size last submitted under a **met** quorum.
    ///
    /// In memory, deliberately. It exists only to keep a periodic pass from
    /// re-submitting a log that has not grown, and the authority on where a
    /// witness actually is has always been the witness — which answers `409`
    /// with its own size and gets a proof built from there. So a restart
    /// re-submits once and the protocol absorbs it; a durable copy would be a
    /// second answer to a question the counterparty already answers.
    pub(crate) submitted: std::sync::atomic::AtomicU64,
    /// The declared maximum time between submissions of an unchanged log;
    /// `None` never re-submits one.
    pub(crate) interval: Option<std::time::Duration>,
    /// The sweep instant of the last round that met quorum, in memory for the
    /// reason `submitted` is.
    pub(crate) last_met: std::sync::Mutex<Option<crate::core::Timestamp>>,
}

/// Where a run is entering this plane from.
///
/// The one thing the drain gate needs to know, and it cannot be derived at the
/// gate: by the time admission runs, an agent commissioning another one and a
/// peer sending a message look identical. The difference is whose work it is —
/// a commission is a step of a run this process is *already* executing and has
/// promised to finish, so refusing it would make the drain manufacture the
/// undecided effects it exists to prevent.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum Entry {
    /// A caller outside this process: an embedder, an operator, a peer, a batch
    /// pass. Refused while draining.
    Outside,
    /// A run already executing here, ordering work it needs in order to
    /// conclude. Never refused for draining — the parent is what the drain is
    /// waiting for.
    Nested,
}

/// A backend that implements every store a full plane runs on.
///
/// Blanket-implemented, so it is a *description* rather than an obligation:
/// any type providing the store traits — journal, cases, tasks, events,
/// timers, memory, quotas, disclosures — is a `FullBackend` without saying so, and both
/// shipped backends are. The quota store is in the set because halts live
/// there: a plane without it would admit past every emergency stop. What it buys is [`Runtime::builder_on`], where the
/// alternative was a cast of one `Arc` per store that every deployment spelled out
/// and none could get differently.
pub trait FullBackend:
    JournalStore
    + CaseStore
    + TaskStore
    + EventStore
    + TimerStore
    + crate::memory::MemoryStore
    + crate::quota::QuotaStore
    + crate::disclosure::DisclosureRegister
{
}

impl<B> FullBackend for B where
    B: JournalStore
        + CaseStore
        + TaskStore
        + EventStore
        + TimerStore
        + crate::memory::MemoryStore
        + crate::quota::QuotaStore
        + crate::disclosure::DisclosureRegister
{
}

impl Runtime {
    /// A builder with the whole case layer wired to one backend.
    ///
    /// The one-call form of the seven-cast litany: journal, cases, tasks,
    /// events, timers, memory and quotas all backed by `store`, which is what a
    /// deployment on a single `RedbStore` or `PostgresStore` means anyway. The
    /// à-la-carte methods remain — [`cases`](RuntimeBuilder::cases) and
    /// friends override an individual store afterwards, and
    /// [`builder`](Self::builder) still starts from the journal alone for a
    /// plane that wants nothing else.
    ///
    /// Blob storage is deliberately not included: bytes routinely live in a
    /// different system than rows, so [`blobs`](RuntimeBuilder::blobs) stays
    /// an explicit decision.
    #[must_use]
    pub fn builder_on<B: FullBackend + 'static>(store: Arc<B>) -> RuntimeBuilder {
        Self::builder_with(Stores::on(store))
    }

    /// A builder with the whole case layer wired from handles.
    ///
    /// What [`builder_on`](Self::builder_on) is in terms of: the seven casts live
    /// in one place, so a deployment that chose its backend at run time — an
    /// operator naming either a file or a connection string — wires exactly what
    /// a deployment on one concrete type wires, rather than a hand-written
    /// approximation of it that drifts the day an eighth store is added.
    #[must_use]
    pub fn builder_with(stores: Stores) -> RuntimeBuilder {
        Self::builder(stores.journal)
            .cases(stores.cases)
            .tasks(stores.tasks)
            .events(stores.events)
            .timers(stores.timers)
            .memory(stores.memory)
            .quota(stores.quotas, crate::quota::TenantQuota::default())
            .disclosures(stores.disclosures)
    }

    #[must_use]
    pub fn builder(store: Arc<dyn JournalStore>) -> RuntimeBuilder {
        RuntimeBuilder {
            store,
            signer: None,
            skills: Vec::new(),
            owner: None,
            lease_ttl: LEASE_TTL,
            memories: None,
            semantic: None,
            authorities: None,
            peers: None,
            tenant_label: super::telemetry::TenantLabel::default(),
            quotas: None,
            quota: crate::quota::TenantQuota::default(),
            budget: Budget::unlimited(),
            require_verifier: false,
            cases: None,
            events: None,
            tasks: None,
            timers: None,
            blobs: None,
            disclosures: None,
            #[cfg(feature = "push")]
            push: None,
            #[cfg(feature = "keyring")]
            keyring: None,
            #[cfg(feature = "manifest")]
            tools: None,
            journal_ceiling: None,
            #[cfg(feature = "manifest")]
            egress: None,
            #[cfg(feature = "manifest")]
            checkers: crate::content::Checkers::default(),
            streams: None,
            tenant: crate::core::TenantId::default(),
            batches: None,
            policy: None,
            identity: None,
            replanner: None,
            calendar: None,
            #[cfg(feature = "manifest")]
            toolbox: None,
            #[cfg(feature = "manifest")]
            tool_servers: Vec::new(),
            #[cfg(feature = "manifest")]
            agents: Vec::new(),
            #[cfg(feature = "manifest")]
            providers: HashMap::new(),
            #[cfg(feature = "push")]
            outbox: None,
            witnesses: Vec::new(),
            quorum: None,
            witness_interval: None,
        }
    }

    /// The driver registered under a manifest's name for it, if any.
    #[cfg(feature = "manifest")]
    pub(crate) fn model_provider(
        &self,
        name: &str,
    ) -> Option<Arc<dyn crate::model::ModelProvider>> {
        self.providers.get(name).map(Arc::clone)
    }

    /// The case store, if this runtime has one.
    #[must_use]
    pub fn cases(&self) -> Option<&Arc<dyn CaseStore>> {
        self.cases.as_ref()
    }

    /// The worklist, if this runtime has one.
    #[must_use]
    pub fn tasks(&self) -> Option<&Arc<dyn TaskStore>> {
        self.tasks.as_ref()
    }

    /// The inbound-event store, if this runtime has one.
    #[must_use]
    pub fn events(&self) -> Option<&Arc<dyn EventStore>> {
        self.events.as_ref()
    }

    /// The ceilings every run under this runtime starts with.
    ///
    /// Readable because "what is this plane allowed to spend" is a question an
    /// operator asks of a running system, and answering it by re-reading the
    /// config that *should* have been applied is how a misapplied budget stays
    /// invisible.
    #[must_use]
    pub const fn budget(&self) -> &Budget {
        &self.budget
    }

    /// The blob store, if this runtime has one.
    #[must_use]
    pub fn blobs(&self) -> Option<&Arc<dyn crate::blob::BlobStore>> {
        self.blobs.as_ref()
    }

    /// Run the live half of the case-layer drill with this plane's own stores.
    ///
    /// The wiring is the point of this method existing: the drill's value is
    /// holding each case's references against the stores the plane *actually
    /// runs with*, and an embedder assembling `drill::Stores` by hand could
    /// hand it a different blob store than the one their runs write to —
    /// a drill that passes over the wrong bucket. Stores this runtime does
    /// not have are reported as unchecked by the drill itself, which is a
    /// different and better answer than an error: a plane with no blob store
    /// has no bytes to lose.
    ///
    /// **The clock is the caller's**, the same decision
    /// [`attention`](Self::attention) and the push sweep make. A rehearsal's
    /// instant is a fact about the outside world rather than a journaled
    /// observation, and taking it here would be a fourth ambient-clock escape
    /// inside the deterministic zone for a value the caller already has. A
    /// fixed instant also makes the recorded verdict testable.
    ///
    /// # Errors
    ///
    /// If this runtime has no case store — the drill walks cases, so there is
    /// nothing to drill — or if the case layer cannot be enumerated.
    pub async fn drill(
        &self,
        at: crate::core::Timestamp,
    ) -> Result<crate::drill::DrillReport, RuntimeError> {
        let cases = self.cases().ok_or_else(|| {
            RuntimeError::PlanContract(
                "this runtime has no case store — the drill walks cases, so there is \
                 nothing to drill; build it with `.cases(store)`"
                    .into(),
            )
        })?;
        let stores = crate::drill::Stores {
            cases,
            blobs: self.blobs(),
            #[cfg(feature = "keyring")]
            keys: self.keyring.as_ref(),
            tenant: &self.tenant,
        };
        let report = crate::drill::drill(&stores)
            .await
            .map_err(RuntimeError::from_store)?;

        // **The verdict is recorded, not only returned.** What an audit asks
        // is *when did you last rehearse, and did it pass* — and left to the
        // caller that answer lives in whatever ran the verb, which is a CI log
        // or a wiki page. The checkpoint pins which store it ran against, so a
        // drill over a restored copy cannot be read as one over production.
        let checkpoint = self
            .store
            .checkpoint()
            .await
            .map_err(RuntimeError::from_store)?;
        cases
            .record_drill(&crate::case::DrillRecord {
                at,
                sound: report.is_sound(),
                cases: report.cases as u64,
                findings: report.findings.len() as u64,
                not_checked: report.not_checked.len() as u64,
                origin: checkpoint.origin.clone(),
                size: checkpoint.size,
            })
            .await
            .map_err(RuntimeError::from_store)?;
        Ok(report)
    }

    /// The last recovery rehearsal this plane ran, or `None` if it never has.
    ///
    /// The half that makes `drill` evidence rather than a command: an audit
    /// asks *when did you last rehearse and did it pass*, and that answer has
    /// to come from the plane rather than from the thing that scheduled it.
    ///
    /// # Errors
    ///
    /// [`RuntimeError::PlanContract`] when this plane has no case store — the
    /// same condition that makes a drill impossible in the first place — and
    /// [`RuntimeError`] for a store failure.
    pub async fn last_drill(&self) -> Result<Option<crate::case::DrillRecord>, RuntimeError> {
        self.cases()
            .ok_or_else(|| {
                RuntimeError::PlanContract(
                    "this runtime has no case store, so it has never drilled one".into(),
                )
            })?
            .last_drill()
            .await
            .map_err(RuntimeError::from_store)
    }

    /// Erase every closed case opened before `older_than`. The retention verb.
    ///
    /// The wiring is the point, exactly as it is for [`drill`](Self::drill):
    /// erasure derives blob addresses and key scopes from the tenant and the
    /// case, so a caller assembling the stores by hand could tombstone
    /// addresses no run ever wrote and report a clean pass over nothing.
    ///
    /// `reason` lands on every tombstone and on each key destruction, so a
    /// later read says *expired, on this date, for this reason* rather than
    /// *missing* — the distinction the drill's three-way verdict turns on.
    ///
    /// `at` is a parameter rather than a clock read, for the reason the
    /// sweeper's is: a pass that read the clock could not be tested against a
    /// year of ageing cases.
    ///
    /// Read [`RetentionReport::not_erasable`](crate::retention::RetentionReport::not_erasable)
    /// before concluding anything. Without a key ring this expires blob
    /// tombstones in the live store and **journal payloads stay verbatim**,
    /// which is the residual the erasure page names and the one an erasure
    /// request actually turns on.
    ///
    /// # Errors
    ///
    /// If this runtime has no case store, or the case layer cannot be walked.
    /// A store that fails on one case is a report entry, not an error.
    pub async fn retain(
        &self,
        older_than: crate::core::Timestamp,
        at: crate::core::Timestamp,
        reason: &str,
    ) -> Result<crate::retention::RetentionReport, RuntimeError> {
        let cases = self.cases().ok_or_else(|| {
            RuntimeError::PlanContract(
                "this runtime has no case store — retention walks cases, so there is \
                 nothing to retain; build it with `.cases(store)`"
                    .into(),
            )
        })?;
        let stores = crate::retention::Stores {
            cases,
            blobs: self.blobs(),
            #[cfg(feature = "keyring")]
            keys: self.keyring.as_ref(),
            tenant: &self.tenant,
            disclosures: self.disclosures.as_ref(),
        };
        crate::retention::retain(&stores, self.store.as_ref(), older_than, at, reason)
            .await
            .map_err(RuntimeError::from_store)
    }

    /// The timer store, if this runtime has one.
    #[must_use]
    pub fn timers(&self) -> Option<&Arc<dyn TimerStore>> {
        self.timers.as_ref()
    }

    #[must_use]
    pub fn batches(&self) -> Option<&Arc<dyn crate::batch::BatchStore>> {
        self.batches.as_ref()
    }

    #[cfg(feature = "push")]
    #[must_use]
    pub fn push(&self) -> Option<&Arc<dyn crate::push::PushStore>> {
        self.push.as_ref()
    }

    /// Re-arm a webhook registration a delivery worker gave up on.
    ///
    /// A parked registration is not delivered and not deleted: it keeps its
    /// cursor, so re-arming resumes at the first record the receiver never
    /// acknowledged rather than at the head of the run. That is the whole
    /// reason parking exists, and the reason this verb is on the plane — a
    /// backlog nobody can empty is a warning line in yesterday's logs.
    ///
    /// The clock is read here rather than taken from the caller, unlike the
    /// delivery worker's: a worker's schedule has to be assertable in a test,
    /// and an operator asking for *now* means now.
    ///
    /// Returns whether a parked registration was found. `false` is an answer —
    /// already live, or never existed — and is told rather than swallowed,
    /// because an operator left waiting for a sweep with nothing to do has no
    /// way to tell the difference.
    ///
    /// # Errors
    ///
    /// [`RuntimeError::PlanContract`] if this plane has no push store, and
    /// [`RuntimeError::Store`] if it is unreachable.
    #[cfg(feature = "push")]
    pub async fn rearm_push(&self, task: RunId, id: &str) -> Result<bool, RuntimeError> {
        let push = self
            .push
            .as_ref()
            .ok_or_else(|| RuntimeError::PlanContract("this plane has no push store".into()))?;
        let at = now_for_admission().unix_timestamp().max(0).unsigned_abs();
        push.unpark(task, id, at)
            .await
            .map_err(RuntimeError::from_store)
    }

    /// Ask a run to stop, and drive the stop if nothing else will.
    ///
    /// The request is durable before this returns, so an operator who gets an
    /// acknowledgement has one whether or not the run was reachable. What
    /// happens next depends on where the run is:
    ///
    /// * **Suspended** — nothing is executing, so this resumes the run itself.
    ///   It observes the request at its first step boundary and unwinds.
    /// * **Running here or elsewhere** — the owner observes the request at its
    ///   next step boundary. Nothing is interrupted mid-effect, deliberately:
    ///   stopping between "announced" and "recorded" manufactures the in-doubt
    ///   case the effect protocol exists to avoid.
    /// * **Quarantined** — refused with [`RuntimeError::CannotUnwind`]: the
    ///   unwind a stop promises is what a quarantine forbids, and reopening or
    ///   abandoning it are the verbs that apply.
    /// * **Concluded and closed** (succeeded, abandoned, cancelled) — refused
    ///   with [`RuntimeError::AlreadyConcluded`] and nothing is recorded; a run
    ///   somebody already stopped answers `false`. A failed or exhausted run is
    ///   resumable, and stopping it unwinds its work.
    /// * **Held by no provider on this plane** — an operator's terminal: the
    ///   request is recorded and not driven, and the plane that holds the run's
    ///   agent observes it on its next resume.
    ///
    /// Returns whether *this* call recorded the request. A second caller gets
    /// `false`: the first asker stays on the record, because "who intervened"
    /// must not be rewritten by a retry.
    ///
    /// # Errors
    ///
    /// [`RuntimeError::PlanContract`] for a blank reason,
    /// [`RuntimeError::CannotUnwind`] for a quarantined run,
    /// [`RuntimeError::AlreadyConcluded`] for a closed one, and
    /// [`RuntimeError`] if the store is unreachable or resuming a suspended run
    /// fails.
    pub async fn request_cancel(
        &self,
        run: RunId,
        actor: &crate::core::Operator,
        reason: &str,
    ) -> Result<bool, RuntimeError> {
        // An intervention with no stated reason documents nobody's judgement,
        // and it is the one field of the record the requester writes.
        if reason.trim().is_empty() {
            return Err(RuntimeError::PlanContract(
                "stopping a run needs a reason — what the person stopping it saw".to_owned(),
            ));
        }
        // Checked before recording. Writing first and failing afterwards leaves a
        // request standing against an id that does not exist, and the operator's
        // retry then comes back "somebody else already asked" — which is a
        // confusing way to say "you mistyped".
        let records = self
            .store
            .read(run, 1)
            .await
            .map_err(RuntimeError::from_store)?;
        if records.is_empty() {
            return Err(RuntimeError::Store(crate::core::StoreError::NotFound(
                run.to_string(),
            )));
        }

        // A quarantine is refused here rather than recorded and ignored. The
        // stop this verb promises is *unwind and put the world back*, and that
        // is the one thing a quarantined run may not do — so the request landed
        // durably, answered the operator `recorded: true`, and the resume then
        // walked straight past it. An operator who believes they stopped a run
        // holding an unresolved payment is worse off than one who was told no.
        //
        // Read from the recorded conclusion, not from a live status: a run that
        // quarantines *after* this call is a genuine race the standing request
        // loses, and that is correct — the request was made about a run nobody
        // had given up on.
        if recorded_conclusion(&records).as_deref() == Some("quarantined") {
            return Err(RuntimeError::CannotUnwind {
                run: run.to_string(),
            });
        }
        // Refused only where the conclusion closes the run. A failed or an
        // exhausted run is resumable and its work stands, so stopping it is the
        // operator's remedy — the unwind it asks for is exactly what those
        // conclusions left undone. Read from the latest conclusion, not the
        // last record: an answer to a doubt may follow a conclusion, and the
        // run is no less closed for it. A run already stopped answers `false`
        // rather than an error, so a second asker is told the intervention of
        // record is somebody else's.
        if let Some(status) = resume_is_closed(&records) {
            if self.cancellation(run).await?.is_some() {
                return Ok(false);
            }
            return Err(RuntimeError::AlreadyConcluded {
                run: run.to_string(),
                outcome: recorded_conclusion(&records)
                    .unwrap_or_else(|| status.as_str().to_owned()),
            });
        }

        let fresh = self
            .store
            .request_cancel(run, actor, reason)
            .await
            .map_err(RuntimeError::from_store)?;

        // Drive it. A suspended run has no thread to notice anything, so an
        // operator's stop would sit unobserved until the deadline swept it —
        // which for a run waiting on a six-week obligation is not a stop.
        //
        // Resuming a run that has already concluded is a no-op inside `replay`,
        // which reads the recorded status back rather than re-executing — so
        // there is no "is it finished?" check to race with here.
        //
        // Driven **only when the run is genuinely idle**: `replay` claims the
        // lease before it reads, and a `LeaseHeld` refusal means somebody is
        // executing the run right now — here or on another instance. That is
        // not a failure of this call. The request is already durable, and the
        // live owner checks for it at every step boundary (the cancellation
        // read at the top of the executor's ready-set loop), so the stop
        // arrives without a second executor ever touching the run. Resuming
        // anyway would, on the owner's own instance, hand the resume the *same
        // epoch* the live execution is writing under — two executors on one
        // chain that fencing, by construction, cannot tell apart.
        //
        // A plane holding no provider, case store or key ring for the run — an
        // operator's terminal, a library plane — records the request and
        // leaves the driving to the plane that does: that plane's next resume
        // finds the request standing.
        if fresh {
            match self.replay(run, Mode::Resume).await {
                Ok(_)
                | Err(
                    RuntimeError::LeaseHeld { .. }
                    | RuntimeError::NoProvider { .. }
                    | RuntimeError::NoCaseStore { .. }
                    | RuntimeError::PayloadsSealed { .. },
                ) => {}
                Err(e) => return Err(e),
            }
        }
        Ok(fresh)
    }

    /// Answer a quarantine, and let the runtime decide the run again.
    ///
    /// A quarantine is this runtime saying it does not know, and the one
    /// conclusion it cannot reach past on its own. Everything else that stops a
    /// run has a party who can move it — a resume for a crash, a raised ceiling
    /// for an exhaustion, a reviewer for a suspension. This is the party for
    /// this one.
    ///
    /// # What this does and does not decide
    ///
    /// The person decides *whether the run may be judged again*, or that it
    /// never will be. They do not decide the outcome. A
    /// [`Reopen`](crate::core::QuarantineDecision::Reopen) hands the run back
    /// to the executor, which re-derives its verdict from a history that now
    /// holds whatever the person established with
    /// [`reconcile_effect`](Self::reconcile_effect) — and quarantines it again,
    /// on the record, if the answer was wrong or incomplete. An
    /// [`Abandon`](crate::core::QuarantineDecision::Abandon) closes it where it
    /// stands, unwinding nothing.
    ///
    /// The decision is journaled **before** it is acted on, so a crash between
    /// the two leaves the instruction standing rather than lost: the next
    /// resume finds it and finishes the job.
    ///
    /// Returns the outcome of the pass this drove — so an operator who reopens
    /// a run learns immediately whether it got any further, rather than having
    /// to go and look.
    ///
    /// # Errors
    ///
    /// [`RuntimeError::NotQuarantined`] if the run's last conclusion is
    /// anything else, [`RuntimeError::LeaseHeld`] if somebody is executing it,
    /// and [`RuntimeError`] for a store failure or a refused resume.
    ///
    /// # Panics
    ///
    /// Never: the `expect` covers a lease this function has just acquired.
    pub async fn decide_quarantine(
        &self,
        run: RunId,
        decider: &crate::core::Operator,
        reason: &str,
        decision: crate::core::QuarantineDecision,
    ) -> Result<RunOutcome, RuntimeError> {
        // The whole weight of this record is that a named person took
        // responsibility for a fact the runtime could not establish, and
        // "unknown decided this for no stated reason" documents nothing while
        // looking like process. Only the reason is checked here: `Operator` has
        // no empty value, so the decider is guaranteed by the type on every
        // path that builds one rather than by a check on this one.
        if reason.trim().is_empty() {
            return Err(RuntimeError::PlanContract(
                "answering a quarantine needs a decider and a reason — who looked, and what they \
                 found"
                    .to_owned(),
            ));
        }

        let lease = self
            .store
            .acquire(run, &self.owner, self.lease_ttl)
            .await
            .map_err(RuntimeError::from_store)?;
        let appended = self
            .record_decision(run, &lease, decider, reason, decision)
            .await;
        if let Err(e) = appended {
            // The lease was claimed by this call and never handed to a resume,
            // so it is this call's to give back. Leaving it would strand the
            // run for a TTL and hand it to the recovery sweep, which would
            // "recover" a run nobody was running.
            let _ = self.store.release_lease(run, lease.epoch).await;
            return Err(e);
        }
        // Handed over rather than released and re-taken: the same window a wake
        // path closes. Both decisions travel this path — an abandonment is
        // concluded inside the resume, from the record just written. The run
        // still stands quarantined on the record, so it keeps its listing
        // whatever this pass does.
        self.replay_releasing(run, Mode::Resume, Some(lease), Claim::Standing)
            .await
    }

    /// Answer a quarantine **without driving the run**.
    ///
    /// [`decide_quarantine`](Self::decide_quarantine) records the decision and
    /// then hands the run to the executor, which is what an operator on a
    /// running plane wants: they learn immediately whether a reopened run got
    /// any further.
    ///
    /// A terminal holding a store cannot do the second half. It has the
    /// journal and not the agent — a declarative run's program is a manifest
    /// this process was not given — so driving the run would mean refusing the
    /// verb for want of an argument the operator may not have during an
    /// incident.
    ///
    /// **That is a supported state rather than a lesser one.** The decision is
    /// journaled before it is acted on precisely so a crash between the two
    /// leaves the instruction standing, and this is the same position reached
    /// deliberately: the next resume finds the record and finishes the job —
    /// so what the caller must not do is report the run as moved.
    ///
    /// # Errors
    ///
    /// As [`decide_quarantine`](Self::decide_quarantine), minus everything the
    /// resume could have raised.
    pub async fn record_quarantine_decision(
        &self,
        run: RunId,
        decider: &crate::core::Operator,
        reason: &str,
        decision: crate::core::QuarantineDecision,
    ) -> Result<(), RuntimeError> {
        if reason.trim().is_empty() {
            return Err(RuntimeError::PlanContract(
                "answering a quarantine needs a decider and a reason — who looked, and what they \
                 found"
                    .to_owned(),
            ));
        }
        let lease = self
            .store
            .acquire(run, &self.owner, self.lease_ttl)
            .await
            .map_err(RuntimeError::from_store)?;
        let appended = self
            .record_decision(run, &lease, decider, reason, decision)
            .await;
        // Always given back: this verb never executes the run, so the lease is
        // held only for the width of one append — the rule
        // `reconcile_effect` follows.
        let _ = self.store.release_lease(run, lease.epoch).await;
        appended
    }

    /// Append the decision, once the run is known to be asking for one.
    async fn record_decision(
        &self,
        run: RunId,
        lease: &crate::journal::Lease,
        decider: &crate::core::Operator,
        reason: &str,
        decision: crate::core::QuarantineDecision,
    ) -> Result<(), RuntimeError> {
        let records = self
            .store
            .read(run, 1)
            .await
            .map_err(RuntimeError::from_store)?;
        if records.is_empty() {
            return Err(RuntimeError::Store(crate::core::StoreError::NotFound(
                run.to_string(),
            )));
        }
        let status = recorded_conclusion(&records);
        // A run whose payloads were erased is asking the same question a
        // quarantine asks — *the runtime cannot go on, and a person must
        // decide* — so it is answered by the same verb whatever outcome it was
        // left under. Without this it has no verb at all: it cannot be
        // resumed, and a cancellation promises an unwind that erased arguments
        // make impossible. Abandonment is the honest ending and this is the
        // door to it.
        if status.as_deref() != Some("quarantined") && !payloads_erased(&records) {
            return Err(RuntimeError::NotQuarantined {
                run: run.to_string(),
                status: status.unwrap_or_else(|| "still running".to_owned()),
            });
        }
        let mut append = Append::new(
            run,
            RecordKind::QuarantineDecided {
                decider: decider.clone(),
                reason: reason.to_owned(),
                decision,
            },
        );
        if let Some(case) = records.iter().find_map(|r| r.body.case) {
            append = append.case(case);
        }
        self.store
            .append(lease.epoch, vec![append])
            .await
            .map_err(RuntimeError::from_store)?;
        Ok(())
    }

    /// Supply, out of band, the outcome of an effect the journal cannot decide.
    ///
    /// The manual twin of [`Effect::reconcile`](crate::core::Effect::reconcile),
    /// and it produces the same record for the same reason: an operator who
    /// looks the charge up in the provider's console is answering exactly the
    /// question a probe asks, so the answer belongs in the place a probe's
    /// answer goes, where replay reads it back and nothing re-derives it.
    ///
    /// What separates the two is on the record too. A probe's verdict is
    /// attributed to the run; this one names the person, because "the provider
    /// told us" and "somebody asserted it" are different evidence.
    ///
    /// **It supplies a missing fact and never replaces a recorded one.** Only
    /// an effect [`undecided_effects`](crate::journal::undecided_effects) names
    /// may be answered. Without that rule an operator could talk a run out of
    /// compensating work that is standing in the world, and the journal would
    /// show an orderly reconciliation while it happened.
    ///
    /// This changes no status by itself: the run stays quarantined until
    /// [`decide_quarantine`](Self::decide_quarantine) hands it back. Several
    /// doubts can be answered before the run is judged again, and answering one
    /// of three is not a decision.
    ///
    /// # Errors
    ///
    /// [`RuntimeError::NotUndecided`] if that effect's outcome is already on
    /// the record, [`RuntimeError::LeaseHeld`] if somebody is executing the
    /// run, and [`RuntimeError`] for a store failure.
    pub async fn reconcile_effect(
        &self,
        run: RunId,
        effect: crate::core::EffectKey,
        assertion: crate::core::Assertion,
        asserted_by: &crate::core::Operator,
        note: &str,
    ) -> Result<(), RuntimeError> {
        // `asserted_by` needs no emptiness check: `Operator` has none to fail.
        if note.trim().is_empty() {
            return Err(RuntimeError::PlanContract(
                "an assertion about an effect needs a name and a note — who established this, and \
                 how"
                .to_owned(),
            ));
        }
        let lease = self
            .store
            .acquire(run, &self.owner, self.lease_ttl)
            .await
            .map_err(RuntimeError::from_store)?;
        let result = self
            .record_assertion(run, &lease, effect, assertion, asserted_by, note)
            .await;
        // Always given back: this verb never executes the run, so the lease is
        // held only for the width of one append.
        let _ = self.store.release_lease(run, lease.epoch).await;
        result
    }

    async fn record_assertion(
        &self,
        run: RunId,
        lease: &crate::journal::Lease,
        effect: crate::core::EffectKey,
        assertion: crate::core::Assertion,
        asserted_by: &crate::core::Operator,
        note: &str,
    ) -> Result<(), RuntimeError> {
        let records = self
            .store
            .read(run, 1)
            .await
            .map_err(RuntimeError::from_store)?;
        if records.is_empty() {
            return Err(RuntimeError::Store(crate::core::StoreError::NotFound(
                run.to_string(),
            )));
        }
        let Some(undecided) = crate::journal::undecided_effects(&records)
            .into_iter()
            .find(|u| u.effect == effect)
        else {
            return Err(RuntimeError::NotUndecided {
                run: run.to_string(),
                effect: effect.to_string(),
            });
        };

        let output = match &assertion {
            crate::core::Assertion::Landed(value) => Some(value.clone()),
            crate::core::Assertion::DidNotHappen => None,
        };
        let mut append = Append::new(
            run,
            RecordKind::EffectReconciled {
                disposition: assertion.disposition(),
                // Stated on the record rather than left to a reader's default.
                // A durable format that does not say what it means is one a
                // later build guesses about, and the guess here is the label on
                // a value the run is about to act on.
                declared: output
                    .is_some()
                    .then(crate::core::DeclaredOutput::untrusted),
                output,
                // A person's assertion costs nothing. What the call itself
                // consumed, if it consumed anything, is already on the record
                // of the attempt this answers.
                spend: Spend::ZERO,
                // No probe ran: this is a person's assertion, so the
                // provider-facing field stays empty and their account goes in
                // the field that is read without a key.
                detail: None,
                note: Some(note.to_owned()),
                asserted_by: Some(asserted_by.clone()),
            },
        )
        .step(undecided.step)
        .phase(undecided.phase)
        .effect(effect);
        if let Some(case) = records.iter().find_map(|r| r.body.case) {
            append = append.case(case);
        }
        self.store
            .append(lease.epoch, vec![append])
            .await
            .map_err(RuntimeError::from_store)?;
        tracing::info!(
            target: telemetry::RECONCILED,
            %run,
            step = %undecided.step,
            verdict = ?assertion.disposition(),
            actor = %asserted_by,
        );
        self.meter
            .count(metrics::RECONCILIATIONS, assertion.disposition().as_str());
        Ok(())
    }

    /// Every mutating effect this run's journal cannot decide the outcome of.
    ///
    /// What an operator holding a quarantine has to go and look up, and the
    /// keys they quote back to [`reconcile_effect`](Self::reconcile_effect).
    ///
    /// # Errors
    ///
    /// If the store is unreachable.
    pub async fn undecided(&self, run: RunId) -> Result<Vec<crate::core::Undecided>, RuntimeError> {
        let records = self
            .store
            .read(run, 1)
            .await
            .map_err(RuntimeError::from_store)?;
        Ok(crate::journal::undecided_effects(&records))
    }

    /// Stop this tenant from starting new work, or let it start again.
    ///
    /// The emergency stop. `Some(reason)` halts, `None` lifts, and the reason is
    /// required because the next person to look will be somebody else, possibly
    /// at three in the morning, and *why* is the whole question.
    ///
    /// **What it stops, precisely.** New admissions, across every instance,
    /// because the flag is in the store rather than in this process — a switch
    /// that stops only the instance it was thrown on is the in-process-counter
    /// failure arriving during an incident. Refusals are their own error, not a
    /// ceiling: a ceiling means *not right now* and invites a retry, which is
    /// exactly what somebody pulling this switch is trying to stop.
    ///
    /// **What a workload-scoped halt does not stop, deliberately.** Runs
    /// already executing, and suspended runs resuming. Those are existing work,
    /// and refusing to let them continue would strand them mid-saga with
    /// reversals unrun — turning an incident into a second one. To stop work in
    /// flight, cancel it: that unwinds what it did and records who asked. This
    /// is the front door, not a power cut, and saying so is the difference
    /// between a control an operator can reason about and one they discover the
    /// shape of during an outage.
    ///
    /// **How wide it reaches** is the [`HaltScope`](crate::quota::HaltScope),
    /// and the scopes divide on *which axis they name* rather than on how
    /// broad they are. Three name a workload — the tenant, every revision of
    /// one declared agent, or one exact reviewed digest — and stop admission.
    /// The fourth names an **authority**, any principal on the delegation
    /// chain a run was admitted under, and is the one that reaches work
    /// already running:
    /// there the incident *is* the credential, so a run carrying on under it is
    /// the harm rather than a side effect, and it pauses at its next step
    /// boundary with its completed work standing
    /// ([`withdraws_from`](crate::quota::HaltScope::withdraws_from) is the
    /// predicate, so the distinction is checked rather than remembered).
    /// Scopes are independent rows — lifting a narrow halt leaves a broad one
    /// standing. An ungoverned run, with no manifest, is stopped only by a
    /// tenant halt; there is nothing narrower to key it on.
    ///
    /// `at` is the caller's, never a clock read here: every lifecycle instant in
    /// this crate is supplied for the reason a hold's is — a pass that reads its
    /// own clock cannot be tested against an ageing plane, and [`I1`] forbids the
    /// runtime an ambient clock outside the effect protocol.
    ///
    /// Requires a quota store; without one there is nowhere durable to keep the
    /// flag, and an emergency stop that a restart forgets is not one.
    ///
    /// [`I1`]: crate::journal
    ///
    /// # Errors
    ///
    /// If no quota store is wired, or the store is unreachable.
    pub async fn set_halt(
        &self,
        scope: &crate::quota::HaltScope,
        by: &crate::core::Operator,
        at: crate::core::Timestamp,
        reason: &str,
    ) -> Result<(), RuntimeError> {
        let quotas = self.quota_store()?;
        quotas
            .set_halt(scope, by, at, reason)
            .await
            .map_err(RuntimeError::Store)?;
        self.forget_credentials(scope);
        Ok(())
    }

    /// Drop the peer credentials held for a subject a halt names, when it is
    /// thrown and when it is lifted — not only when a hop next meets it, which
    /// may never happen while the halt stands.
    fn forget_credentials(&self, scope: &crate::quota::HaltScope) {
        if let (crate::quota::HaltScope::Subject { id }, Some(wiring)) =
            (scope, self.peers.as_ref())
        {
            wiring.registry.forget(id);
        }
    }

    /// Lift one, and let work at that scope start again — recording who did.
    ///
    /// Answers the run holding the lift record and whether this call removed
    /// the row, or `None` when nothing was standing at `scope`: an operator who
    /// lifts a scope nobody halted is told so rather than told *done*, and
    /// nothing is written.
    ///
    /// **The record comes first, then the row goes.** The lift is written as
    /// the sole [`HaltLifted`](crate::journal::RecordKind::HaltLifted) record
    /// of a sealed run of its own, carrying `by`, `at` and the whole stop it
    /// ended; only then is the register's row removed. The journal and the
    /// register share no transaction, so a lift that cannot be recorded does
    /// not happen, and a removal that fails after the record is written is an
    /// error naming the record's run — the halt still stands, the register is
    /// the answer to what is in force, and lifting again writes a second
    /// record. The record attests the instruction and the row as read, not
    /// that the removal succeeded.
    ///
    /// **Only the row the record names goes.** The removal is
    /// [`QuotaStore::lift_halt_if`](crate::quota::QuotaStore::lift_halt_if)
    /// with that row, so a halt re-thrown between the read and the removal is
    /// left standing and the call fails naming the record's run. A row another
    /// lift already removed answers `removed: false`.
    ///
    /// [`QuotaStore::lift_halt`](crate::quota::QuotaStore::lift_halt) is the
    /// raw register verb; a direct call to it is unrecorded.
    ///
    /// # Errors
    ///
    /// If no quota store is wired, the store is unreachable, or the record
    /// cannot be written; [`RuntimeError::ControlStands`] if the row cannot be
    /// removed after the record was written, or was re-thrown in between.
    pub async fn lift_halt(
        &self,
        scope: &crate::quota::HaltScope,
        by: &crate::core::Operator,
        at: crate::core::Timestamp,
    ) -> Result<Option<ControlLifted>, RuntimeError> {
        let quotas = self.quota_store()?;
        let standing = quotas.halts().await.map_err(RuntimeError::Store)?;
        let Some(halt) = standing.into_iter().find(|h| &h.scope == scope) else {
            return Ok(None);
        };
        let run = self
            .seal_operator_record(
                RecordKind::HaltLifted {
                    scope: scope.key(),
                    by: by.clone(),
                    at,
                    reason: halt.reason.clone(),
                    thrown_by: halt.by.clone(),
                    thrown_at: halt.at,
                },
                None,
                HALT_LIFTED_OUTCOME,
                None,
            )
            .await?;
        let removed = quotas
            .lift_halt_if(&halt)
            .await
            .map_err(|e| removal_failed(run, &e))?;
        self.forget_credentials(scope);
        if !removed {
            let now = quotas.halts().await.map_err(|e| removal_failed(run, &e))?;
            if now.iter().any(|h| &h.scope == scope) {
                return Err(RuntimeError::ControlStands {
                    run: run.to_string(),
                    detail: format!(
                        "the halt on '{}' was re-thrown after this lift read it, and the new \
                         halt still stands",
                        scope.key()
                    ),
                });
            }
        }
        Ok(Some(ControlLifted {
            record: run,
            removed,
        }))
    }

    /// Release the legal hold on `case` — recording who did.
    ///
    /// The hold's counterpart of [`lift_halt`](Self::lift_halt), in the same
    /// order for the same reason: the
    /// [`HoldReleased`](crate::journal::RecordKind::HoldReleased) record is
    /// written, stamped with `case`, before the row goes. It names the releaser
    /// and the hold's placing operator and instant, and not the hold's reason,
    /// so the erasure the release permits leaves its authorization readable.
    ///
    /// `None` when the matter is not held, with nothing written; `removed:
    /// false` when another release removed the row first.
    ///
    /// **Only the hold the record names goes.** The removal is
    /// [`CaseStore::release_hold_if`](crate::case::CaseStore::release_hold_if)
    /// with that hold, so a hold placed again between the read and the removal
    /// is left standing and the call fails naming the record's run.
    /// [`CaseStore::release_hold`](crate::case::CaseStore::release_hold) is the
    /// raw register verb; a direct call to it is unrecorded.
    ///
    /// # Errors
    ///
    /// [`StoreError::NotFound`](crate::core::StoreError::NotFound) if the case
    /// does not exist; [`RuntimeError::ControlStands`] if the row cannot be
    /// removed after the record was written, or was placed again in between;
    /// otherwise if no case store is
    /// wired, the store is unreachable, or the record cannot be written.
    pub async fn release_hold(
        &self,
        case: crate::core::CaseId,
        by: &crate::core::Operator,
        at: crate::core::Timestamp,
    ) -> Result<Option<ControlLifted>, RuntimeError> {
        let cases = self.cases.as_ref().ok_or_else(|| {
            RuntimeError::PlanContract("releasing a hold needs a case store".to_owned())
        })?;
        let Some(standing) = cases.hold(case).await.map_err(RuntimeError::Store)? else {
            return match cases.case(case).await.map_err(RuntimeError::Store)? {
                Some(_) => Ok(None),
                None => Err(RuntimeError::Store(crate::core::StoreError::NotFound(
                    format!("case {case}"),
                ))),
            };
        };
        let run = self
            .seal_operator_record(
                RecordKind::HoldReleased {
                    by: by.clone(),
                    at,
                    placed_by: standing.by.clone(),
                    placed_at: standing.placed_at,
                },
                Some(case),
                HOLD_RELEASED_OUTCOME,
                None,
            )
            .await?;
        let removed = cases
            .release_hold_if(case, &standing)
            .await
            .map_err(|e| removal_failed(run, &e))?;
        if !removed
            && cases
                .hold(case)
                .await
                .map_err(|e| removal_failed(run, &e))?
                .is_some()
        {
            return Err(RuntimeError::ControlStands {
                run: run.to_string(),
                detail: format!(
                    "the hold on case {case} was placed again after this release read it, \
                     and the new hold still stands"
                ),
            });
        }
        Ok(Some(ControlLifted {
            record: run,
            removed,
        }))
    }

    /// Every recorded halt lift, newest first: the one record of each run.
    ///
    /// # Errors
    ///
    /// If the journal is unreachable, or a lift run does not hold a lift record.
    pub async fn lifted_halts(&self, limit: usize) -> Result<Vec<Record>, RuntimeError> {
        self.operator_records(HALT_LIFTED_OUTCOME, limit).await
    }

    /// Every recorded hold release, newest first: the one record of each run.
    ///
    /// # Errors
    ///
    /// If the journal is unreachable, or a release run does not hold a release
    /// record.
    pub async fn released_holds(&self, limit: usize) -> Result<Vec<Record>, RuntimeError> {
        self.operator_records(HOLD_RELEASED_OUTCOME, limit).await
    }

    /// The first record of each run sealed under `outcome`, in the index's
    /// newest-first order. A run whose first record is not the act its outcome
    /// names is a store error, never skipped: a history that silently thins is
    /// one that reads as complete.
    async fn operator_records(
        &self,
        outcome: &str,
        limit: usize,
    ) -> Result<Vec<Record>, RuntimeError> {
        let runs = self
            .store
            .runs_by_outcome(outcome, limit)
            .await
            .map_err(RuntimeError::from_store)?;
        let mut found = Vec::with_capacity(runs.len());
        for run in runs {
            let first = self
                .store
                .read_page(run, 1, 1)
                .await
                .map_err(RuntimeError::from_store)?
                .into_iter()
                .next();
            match first {
                Some(record)
                    if matches!(
                        (outcome, record.kind()),
                        (HALT_LIFTED_OUTCOME, RecordKind::HaltLifted { .. })
                            | (HOLD_RELEASED_OUTCOME, RecordKind::HoldReleased { .. })
                    ) =>
                {
                    found.push(record);
                }
                _ => {
                    return Err(RuntimeError::Store(crate::core::StoreError::Corrupt {
                        seq: 1,
                        detail: format!(
                            "run {run} is sealed as '{outcome}' but holds no such record"
                        ),
                    }));
                }
            }
        }
        Ok(found)
    }

    /// The quota store, when one is wired.
    pub(crate) fn quota_store_if_wired(&self) -> Option<&Arc<dyn crate::quota::QuotaStore>> {
        self.quotas.as_ref()
    }

    /// Every run holding spend against this tenant's periods, and how much.
    ///
    /// The runs a [`QuotaError::SpentOut`](crate::quota::QuotaError::SpentOut)
    /// refusal counts as *reserved*. A run holds its reservation until it
    /// concludes, so the ones that stopped waiting on a person — quarantined,
    /// exhausted, withheld, failed — hold it until that person acts;
    /// [`attention`](Self::attention) names those.
    ///
    /// # Errors
    ///
    /// If no quota store is wired, or it is unreachable.
    pub async fn reservations(
        &self,
        limit: usize,
    ) -> Result<Vec<crate::quota::Held>, RuntimeError> {
        let quotas = self.quotas.as_ref().ok_or_else(|| {
            RuntimeError::Store(crate::core::StoreError::Backend(
                "no quota store is wired, so no run holds spend against a period".to_owned(),
            ))
        })?;
        quotas
            .reservations(limit)
            .await
            .map_err(RuntimeError::Store)
    }

    /// The quota store, or the refusal that says why an emergency stop needs one.
    fn quota_store(&self) -> Result<&std::sync::Arc<dyn crate::quota::QuotaStore>, RuntimeError> {
        self.quotas.as_ref().ok_or_else(|| {
            RuntimeError::Store(crate::core::StoreError::Backend(
                "an emergency stop needs a quota store to keep the flag in — an \
                 in-process one is forgotten by a restart and never seen by a \
                 second instance"
                    .to_owned(),
            ))
        })
    }

    /// Every standing emergency stop on this tenant, and why.
    ///
    /// The operator's question — *what is stopped right now?* — which a
    /// per-scope lookup cannot answer without already knowing what to ask
    /// about.
    ///
    /// # Errors
    ///
    /// If no quota store is wired, or the store is unreachable.
    pub async fn halts(&self) -> Result<Vec<crate::quota::Halt>, RuntimeError> {
        let quotas = self.quotas.as_ref().ok_or_else(|| {
            RuntimeError::Store(crate::core::StoreError::Backend(
                "no quota store is wired, so no emergency stop can be set or read".to_owned(),
            ))
        })?;
        quotas.halts().await.map_err(RuntimeError::Store)
    }

    /// Which runs are executing **right now**, and under whose authority.
    ///
    /// [`runs_by_outcome`](crate::journal::JournalStore::runs_by_outcome)
    /// answers from the journal's index, which only *concluded* runs are in; the
    /// live set is the tenant's admission slots.
    ///
    /// **The join is the point, not the ids.** An incident is rarely *cancel
    /// this run* but a revoked credential or a bad revision, so each entry
    /// carries the declared agent and the delegation subject it was admitted
    /// under.
    ///
    /// A slot whose lease has lapsed is marked `stranded` rather than omitted:
    /// the recovery sweep resumes those, and cancelling one undoes work that was
    /// about to continue.
    ///
    /// Bounded by `limit`, and reads a page of each run's header records to
    /// attribute it — an operator question rather than a hot path.
    ///
    /// # Errors
    ///
    /// If no quota store is wired, or either store is unreachable.
    pub async fn running_runs(&self, limit: usize) -> Result<Vec<LiveRun>, RuntimeError> {
        let quotas = self.quotas.as_ref().ok_or_else(|| {
            RuntimeError::Store(crate::core::StoreError::Backend(
                "no quota store is wired, so nothing tracks which runs hold this \
                 tenant's admission slots"
                    .to_owned(),
            ))
        })?;
        let live = quotas
            .running_runs(limit)
            .await
            .map_err(RuntimeError::Store)?;
        // One read, not one per run: the stranded set is small and the whole of
        // it is needed to answer any entry.
        let stranded: std::collections::BTreeSet<RunId> = self
            .store
            .abandoned_runs(limit)
            .await
            .map_err(RuntimeError::Store)?
            .into_iter()
            .collect();

        let mut out = Vec::with_capacity(live.len());
        for run in live {
            // The header records only. `RunAdmitted` is the first and
            // `IdentityBound` follows it when the caller presented a chain, so a
            // short page carries both without reading a run's whole history —
            // which on a long-running agent is the difference between an
            // operator listing and a scan.
            let head = self
                .store
                .read_page(run, 1, ATTRIBUTION_RECORDS)
                .await
                .map_err(RuntimeError::Store)?;
            let governed_by = head.iter().find_map(|r| match r.kind() {
                crate::journal::RecordKind::RunAdmitted { governed_by, .. } => {
                    governed_by.as_ref().map(|id| (**id).clone())
                }
                _ => None,
            });
            let subject = head.iter().find_map(|r| match r.kind() {
                crate::journal::RecordKind::IdentityBound { chain } => {
                    chain.first().map(|p| p.id.clone())
                }
                _ => None,
            });
            out.push(LiveRun {
                stranded: stranded.contains(&run),
                run,
                governed_by,
                subject,
            });
        }
        Ok(out)
    }

    /// The runs that are waiting, and what each one waits for.
    ///
    /// The third listing, beside concluded runs and running ones: a suspended
    /// run has no outcome and holds no admission slot, so neither of the others
    /// names it. Re-arming these is the recovery runbook's last step, and until
    /// this existed that step named a verb with no argument an operator could
    /// obtain.
    ///
    /// Soonest due first, bounded by `limit`. Straight through to the store's
    /// maintained index — no page of records is read, because what a run waits
    /// for is on the suspension itself.
    ///
    /// # Errors
    ///
    /// If the store is unreachable.
    pub async fn waiting_runs(
        &self,
        limit: usize,
    ) -> Result<Vec<crate::journal::WaitingRun>, RuntimeError> {
        self.store
            .waiting_runs(limit)
            .await
            .map_err(RuntimeError::from_store)
    }

    /// Stop this instance taking on work, then wait for what it is already
    /// doing.
    ///
    /// A process killed mid-step leaves an announced effect with no terminal
    /// record, so its declared [`Recovery`](crate::core::Recovery) has to
    /// decide whether it happened — the right answer to an accident, and an
    /// expensive one to schedule on every deploy.
    ///
    /// Admission closes **first**: every later [`run`](Self::run),
    /// [`spawn`](Self::spawn) and plan is refused
    /// [`RuntimeError::Draining`](crate::core::RuntimeError::Draining), leaving
    /// no lease, no slot and no journal. Then this waits up to `grace` for the
    /// runs it put on a background task to reach a journaled resting point.
    /// Closing first is what makes the answer worth having — a wait alone
    /// reports about an instant — and it is also the only signal a long-lived
    /// read gets, so an open A2A subscription ends rather than holding a
    /// graceful shutdown for as long as the run it watches.
    ///
    /// **Run it beside a server's own graceful shutdown, not after it** —
    /// `tokio::join!` of the two. Serialising deadlocks one on the other in
    /// whichever order you pick: a run awaited inside a request handler is
    /// finished by the server, and an open subscription is ended by this.
    ///
    /// Three things it deliberately does not do. It does not wait for runs on
    /// somebody else's task; those belong to that caller's own shutdown. It
    /// does not gate resumes or an agent commissioning another one — both
    /// continue work this plane already owns, and a commission is a step of a
    /// run this is waiting for. And it does not hand back the leases of runs it
    /// did not finish: a release says takeover is safe, and for a run still
    /// inside `perform` the next owner would re-perform the call beside the one
    /// in flight. Left to expire, the lease is the signal the recovery sweep
    /// reads as *an instance died holding this run* — which is what a
    /// drained-out run is.
    ///
    /// Idempotent: draining an instance that is already draining waits again.
    pub async fn drain(&self, grace: std::time::Duration) -> super::DrainReport {
        self.inflight.drain(grace).await
    }

    /// Whether this instance has stopped admitting runs.
    ///
    /// For an embedder whose server keeps its listener open while it drains and
    /// therefore needs something to answer a readiness probe with. The shipped
    /// server needs none: it closes its listeners first, so a probe that
    /// connects already fails — which is why this crate's HTTP surface has no
    /// `/health` route to flip. See [`crate::api`] on why it has none at all.
    #[must_use]
    pub fn is_draining(&self) -> bool {
        self.inflight.is_draining()
    }

    /// The cancellation recorded against a run, if one was.
    ///
    /// Reads the journal rather than a flag: a cancellation is a record, so
    /// this answers the same thing after a restart and on another instance.
    ///
    /// # Errors
    ///
    /// If the store is unreachable.
    pub async fn cancellation(
        &self,
        run: RunId,
    ) -> Result<Option<crate::journal::Cancellation>, RuntimeError> {
        self.store
            .cancellation(run)
            .await
            .map_err(RuntimeError::from_store)
    }

    /// The policy engine, if this runtime has one.
    ///
    /// Exposed because a surface that faces strangers has to be able to ask
    /// whether one exists at all. Inside the process the caller is the
    /// embedder's own code and an absent engine is a choice; on a socket it is
    /// a hole, and the HTTP surface refuses to start without one.
    #[must_use]
    pub fn policy(&self) -> Option<&Arc<dyn crate::core::PolicyEngine>> {
        self.policy.as_ref()
    }

    /// Which tenant this plane runs as.
    #[must_use]
    pub fn tenant(&self) -> &crate::core::TenantId {
        &self.tenant
    }

    /// What this plane's policy engine cannot evaluate for a served caller
    /// that presented no chain.
    ///
    /// The build probes the chain shapes this plane's own runs take: its own
    /// chain where it has one, and both shapes where it has none. A served
    /// surface adds the one the build cannot know about — a caller acting
    /// under no chain on a plane that has one — so every surface that admits
    /// work for a stranger asks this before it starts.
    #[cfg(any(feature = "a2a-server", feature = "mcp-server"))]
    pub(crate) fn served_policy_problems(&self) -> Vec<String> {
        match (&self.policy, &self.identity) {
            (Some(engine), Some(_)) => runtime_policy_problems(engine.as_ref(), None),
            _ => Vec::new(),
        }
    }

    /// How far from its owner the plane's own chain is, or zero without one.
    ///
    /// The depth a run bound by the plane's chain but acting under none starts
    /// from: acting under no chain does not put a served caller closer to the
    /// owner than the plane that serves it.
    pub(crate) fn own_depth(&self) -> usize {
        self.identity
            .as_ref()
            .map_or(0, crate::core::Delegation::depth)
    }

    /// The journal, under the name the batch driver reads it by.
    #[must_use]
    pub(crate) fn meter(&self) -> &super::metrics::Meter {
        &self.meter
    }

    /// Write an operator act as the sole record of a sealed run of its own.
    ///
    /// The act, then its conclusion, then the seal — so it carries the chain,
    /// the signature, Merkle inclusion and the witness, and an offline reader
    /// checks it without being taught what the act was. `case` stamps the
    /// record onto a matter's history; `reason` is the conclusion's, for the
    /// one act whose reason lives there.
    async fn seal_operator_record(
        &self,
        kind: RecordKind,
        case: Option<crate::core::CaseId>,
        outcome: &str,
        reason: Option<&str>,
    ) -> Result<RunId, RuntimeError> {
        let run = RunId::generate();
        let epoch = BREAK_GLASS_EPOCH;
        let mut act = Append::new(run, kind);
        if let Some(case) = case {
            act = act.case(case);
        }
        self.store
            .append(epoch, vec![act])
            .await
            .map_err(RuntimeError::from_store)?;
        let head = self
            .store
            .head(run)
            .await
            .map_err(RuntimeError::from_store)?;
        self.store
            .append(
                epoch,
                vec![Append::new(
                    run,
                    RecordKind::RunConcluded {
                        outcome: outcome.to_owned(),
                        reason: reason.map(str::to_owned),
                        exhaustion: None,
                        live_spend: Spend::default(),
                        chain_head: head.hash,
                    },
                )],
            )
            .await
            .map_err(RuntimeError::from_store)?;
        self.store
            .seal(run, epoch, outcome)
            .await
            .map_err(RuntimeError::from_store)?;
        Ok(run)
    }

    /// Record an operator deliberately crossing into this tenant, and return
    /// the run that holds the record.
    ///
    /// Every other tenancy control keeps a cross-tenant read from being reached
    /// by accident. This is the designed exception, and the rule for it is that an
    /// exception without a record is indistinguishable from the breach it is
    /// meant to be. So the access is written into **this** tenant's journal —
    /// the one whose data is about to be reached — in a sealed run of its own,
    /// exactly as a sweep writes its decisions. It therefore inherits the hash
    /// chain, the per-record signature and the Merkle inclusion, and the
    /// offline audit tool reports it without being taught that break-glass
    /// exists.
    ///
    /// **The record is written before any data is served, and a failure to
    /// write it is a failure to access.** That direction is the whole control:
    /// the alternative — serve first, record best-effort — is a break-glass
    /// that works exactly as well when its own evidence is lost.
    ///
    /// # Errors
    ///
    /// If `reason` is blank, or if the record cannot be written. An
    /// unexplained exception is the thing this record exists to prevent, so it
    /// is refused rather than stored empty.
    pub async fn record_break_glass(
        &self,
        actor: &crate::core::Operator,
        roles: &[String],
        reason: &str,
    ) -> Result<RunId, RuntimeError> {
        if reason.trim().is_empty() {
            return Err(RuntimeError::PlanContract(
                "break-glass needs a reason: an unexplained crossing of the tenant \
                 boundary is what this record exists to prevent"
                    .to_owned(),
            ));
        }
        let run = self
            .seal_operator_record(
                RecordKind::BreakGlass {
                    actor: actor.clone(),
                    roles: roles.to_vec(),
                    reason: reason.to_owned(),
                },
                None,
                BREAK_GLASS_OUTCOME,
                Some(reason),
            )
            .await?;
        tracing::warn!(
            tenant = %self.tenant(),
            %actor,
            %run,
            reason,
            "break-glass: an operator crossed the tenant boundary"
        );
        Ok(run)
    }

    /// The journal, for reads the runtime does not mediate.
    ///
    /// This is also the embedder's **resumable output stream**:
    /// [`JournalStore::read`] is a seq-cursored read over a run's records, so
    /// polling from the last sequence seen is a durable, reconnect-safe
    /// progress feed that any instance can serve — the exact mechanism the
    /// A2A streaming surface is built on. There is deliberately no curated
    /// event type between an embedder and the records: a third vocabulary
    /// beside the journal's and the wire's would be a second truth wearing
    /// ergonomics, and the records are already the history the stream must
    /// agree with.
    pub fn journal(&self) -> &Arc<dyn JournalStore> {
        &self.store
    }

    /// Which case a run belongs to, or `None` if it belongs to none.
    ///
    /// Read from the **journal**, not from a column beside it. The binding is
    /// stamped on the run's own records at admission, so answering from there
    /// is answering from the plan of record — a case-store column saying the
    /// same thing would be a second copy of one fact, and the two could
    /// disagree about a run the case layer never saw.
    ///
    /// It is the first question an operator surface asks, which is why it is a
    /// method rather than a documented one-liner: every caller was otherwise
    /// going to reach for the first record and read `body.case` off it, and a
    /// caller who reached for the *last* one instead would still be right today
    /// and wrong the moment a run is admitted before its case is known.
    ///
    /// # Errors
    ///
    /// If the journal cannot be read. An unknown run is `Ok(None)` rather than
    /// an error: *no such run* and *a run in no case* are both honest answers
    /// to this question, and neither is a fault.
    pub async fn case_of(&self, run: RunId) -> Result<Option<crate::core::CaseId>, RuntimeError> {
        Ok(self
            .store
            .read(run, 1)
            .await
            .map_err(RuntimeError::from_store)?
            .first()
            .and_then(|record| record.body.case))
    }

    #[must_use]
    /// The witness set and quorum this plane was built with, if any.
    pub(crate) fn witnessing(&self) -> Option<&Arc<Witnessing>> {
        self.witnesses.as_ref()
    }

    pub fn store(&self) -> &Arc<dyn JournalStore> {
        &self.store
    }

    /// This **process instance's** identity, as it appears in run leases.
    ///
    /// Not the agent's name. Several instances of one agent are normal, and a
    /// lease is renewed without a fencing bump only when the holder is the same
    /// owner — so two instances sharing this string would each renew the other's
    /// lease and both write to one run. See
    /// [`RuntimeBuilder::owner`].
    ///
    /// Public because "which instance holds this run" is a question an operator
    /// asks of a stuck system, and the answer is otherwise only in a store row.
    #[must_use]
    pub fn owner_id(&self) -> &str {
        &self.owner
    }

    /// The input as the declared admission rules leave it: refused with no
    /// record, as an admission policy denial is, or with its sensitivity
    /// raised to every matched classification — which `RunAdmitted` then
    /// records as the input's label.
    #[cfg(feature = "manifest")]
    fn admit_content(
        &self,
        agent: &str,
        input: Tainted<Value>,
    ) -> Result<Tainted<Value>, RuntimeError> {
        let Some(manifest) = self
            .resolve(agent)
            .ok()
            .and_then(|skill| self.governing(skill.as_ref()))
        else {
            return Ok(input);
        };
        let outcome = super::ctx::judged(
            manifest.spec.security.content.as_ref(),
            crate::content::At::Admission,
            input.peek(),
        )
        .map_err(RuntimeError::PolicyDenied)?;
        if let Some(hit) = outcome.refused.first() {
            return Err(RuntimeError::PolicyDenied(
                crate::core::PolicyError::Content {
                    rule: hit.rule.clone(),
                    pointer: hit.pointer.clone(),
                },
            ));
        }
        let raised = outcome.raise(input.label().sensitivity);
        if raised == input.label().sensitivity {
            return Ok(input);
        }
        Ok(input.raised_to(raised))
    }

    #[cfg(not(feature = "manifest"))]
    #[allow(clippy::unused_self, clippy::unnecessary_wraps)]
    fn admit_content(
        &self,
        _agent: &str,
        input: Tainted<Value>,
    ) -> Result<Tainted<Value>, RuntimeError> {
        Ok(input)
    }

    /// The content rules' verdict on an event delivered to a suspended run,
    /// under the declaration governing the run's skill; `None` where no rule
    /// matched or none is declared.
    #[cfg(feature = "manifest")]
    fn delivered_verdict(
        &self,
        history: &[crate::journal::Record],
        payload: &serde_json::Value,
    ) -> Option<crate::core::ContentVerdict> {
        let capability = history.iter().find_map(|r| match r.kind() {
            RecordKind::RunAdmitted { capability, .. } => Some(capability.clone()),
            _ => None,
        })?;
        let manifest = self.governing(self.resolve(&capability).ok()?.as_ref())?;
        super::ctx::verdict(super::ctx::judged(
            manifest.spec.security.content.as_ref(),
            crate::content::At::Source(super::ctx::AWAIT_KIND),
            payload,
        ))
    }

    #[cfg(not(feature = "manifest"))]
    #[allow(clippy::unused_self)]
    fn delivered_verdict(
        &self,
        _history: &[crate::journal::Record],
        _payload: &serde_json::Value,
    ) -> Option<crate::core::ContentVerdict> {
        None
    }

    /// The declaration governing a skill, if its agent has one.
    ///
    /// Per skill, not per plane: a runtime runs several agents, and a step must
    /// be judged against the manifest of the agent whose skill it is. Looking up
    /// one plane-wide manifest would apply another agent's ceilings.
    #[cfg(feature = "manifest")]
    fn governing(&self, skill: &dyn Skill) -> Option<Arc<crate::manifest::Manifest>> {
        self.governed_by.get(&skill.descriptor().name).cloned()
    }

    /// Renew this run's lease until the returned guard is dropped.
    ///
    /// Requires a Tokio runtime, as the rest of this crate's timing does.
    fn heartbeat(&self, run: RunId, epoch: crate::core::Epoch) -> Heartbeat {
        let store = Arc::clone(&self.store);
        let owner = self.owner.clone();
        let ttl = self.lease_ttl;
        // A third of the TTL, so two renewals can be lost to a slow store before
        // the lease lapses. Renewing *at* the TTL would mean any hesitation
        // leaves it expired, and an expired lease is one anybody may take —
        // including, per `acquire`, this caller, which would fence the run with
        // its own heartbeat.
        let period = ttl / 3;
        Heartbeat(tokio::spawn(async move {
            loop {
                tokio::time::sleep(period).await;
                // `renew`, never `acquire`. A renewal extends only a lease
                // still held by exactly this `(owner, epoch)`; it cannot
                // claim. That distinction is load-bearing here: this task
                // races the run's own conclusion, and an acquire arriving
                // just after `conclude` released the lease would re-take it —
                // a live, never-released lease over a concluded run, which
                // the recovery sweep then "recovers" forever.
                //
                // Stop only when the store says the lease is gone — released
                // by the conclusion, lapsed and reclaimed, or taken over: the
                // run's next append will be fenced, which is the correct
                // outcome, and claiming now would only resurrect ownership
                // this instance no longer has. Any other failure is the store
                // not answering, and giving up then would let a run that is
                // still executing lapse into somebody else's recovery.
                match store.renew(run, &owner, epoch, ttl).await {
                    Ok(_) => {}
                    Err(crate::core::StoreError::LeaseNotHeld { .. }) => return,
                    Err(error) => tracing::warn!(
                        target: "agentplane::lease",
                        run = %run,
                        error = %error,
                        "a lease renewal failed; the next one retries"
                    ),
                }
            }
        }))
    }

    /// The standing withdrawal that reaches `identity`, if one does.
    ///
    /// The one predicate the step boundary and a subject-bound hop both ask,
    /// so the two cannot disagree about whose authority is withdrawn. Read on
    /// a live pass only — a halt thrown today must not decide what a run did
    /// last year — and an unreachable store propagates, because carrying on
    /// would leave a withdrawal unenforced exactly while accounting is down.
    pub(crate) async fn withdrawal_against(
        &self,
        identity: Option<&crate::core::Delegation>,
    ) -> Result<Option<Withdrawal>, crate::core::StoreError> {
        let (Some(quotas), Some(chain)) = (self.quotas.as_ref(), identity) else {
            return Ok(None);
        };
        let halts = quotas.halts().await?;
        Ok(halts.into_iter().find_map(|halt| {
            let subject = halt.scope.withdraws_from(chain)?.to_owned();
            Some(Withdrawal {
                subject,
                reason: halt.reason,
                by: halt.by,
            })
        }))
    }

    /// Stop a run because the authority it acts under was withdrawn.
    ///
    /// A **pause**: `stop` is reached with a status `maybe_unwind` passes
    /// straight through, so the run's mutations stand and it stays resumable.
    /// That is the treatment exhaustion gets and for the same reason — the run
    /// did nothing wrong, and reversing correct work because a credential lapsed
    /// would be a second incident.
    ///
    /// `record` is false on a resume that finds the withdrawal still standing:
    /// the withholding already on the chain says so, and a second one per resume
    /// attempt would turn a queue of retries into a queue of records.
    #[allow(clippy::too_many_arguments)]
    async fn withhold(
        &self,
        cx: Unwind<'_>,
        withdrawal: Withdrawal,
        record: bool,
        completed: &[(StepId, Capability)],
        outputs: &BTreeMap<StepId, Tainted<Value>>,
        cursor: &mut ReplayCursor,
        case_id: Option<crate::core::CaseId>,
        quota: &QuotaPass,
    ) -> Result<RunOutcome, RuntimeError> {
        let Withdrawal {
            subject,
            reason,
            by,
        } = withdrawal;
        if record {
            let stamped = (cx.stamp)(Append::new(
                cx.run,
                RecordKind::AuthorityWithheld {
                    subject: subject.clone(),
                    reason: reason.clone(),
                    by: by.clone(),
                },
            ));
            self.store
                .append(cx.epoch, vec![stamped])
                .await
                .map_err(RuntimeError::from_store)?;
        }
        self.stop(
            cx,
            RunStatus::Withheld { subject, reason },
            completed,
            outputs,
            cursor,
            case_id,
            quota,
        )
        .await
    }

    /// Refuse a run whose tenant is at a ceiling.
    ///
    /// Fails **closed**: an unreachable quota store refuses rather than admits,
    /// because a ceiling that yields when its accounting is down is a ceiling an
    /// attacker removes by taking the accounting down.
    ///
    /// Live admission only, and replay and resume are skipped for **different**
    /// reasons. Re-checking during replay would let a run that happened produce
    /// a different history when it is re-read: a ceiling crossed since admission
    /// would rewrite the past into a refusal. Resume is not that — it decides
    /// only what happens next — and it is ungated because refusing it strands a
    /// run mid-saga with its reversals unrun. What that costs the ceiling is
    /// stated where the ceiling is defined ([`crate::quota`]); it is a real cost
    /// rather than an absent one.
    async fn check_quota(
        &self,
        run: RunId,
        governed_by: Option<&crate::journal::AgentIdentity>,
        chain: Option<&crate::core::Delegation>,
        at: crate::core::Timestamp,
        (budget, width): (&Budget, usize),
    ) -> Result<QuotaPass, RuntimeError> {
        let Some(quotas) = self.quotas.as_ref() else {
            return Ok(QuotaPass::disabled());
        };
        let pass = QuotaPass::at(&self.quota, at, true).sized_for(width);

        // The halt is checked **before** the unlimited shortcut, because an
        // emergency stop is not a ceiling and a tenant with no ceilings is
        // exactly the one an operator is most likely to need to stop. Reading it
        // fails closed for the same reason the ceilings do: a switch that yields
        // when its store is unreachable is a switch an attacker throws by taking
        // the store down.
        //
        // Every standing halt in one read, and the **narrowest match wins the
        // message**: an operator who stopped one agent and whoever is refused
        // are looking for different sentences, and "the tenant is halted" told
        // to the caller of agent 12 sends them to the wrong incident. Ordering
        // the scopes puts `Subject` before `Revision` before `Agent` before
        // `Tenant`, so the reason reported is the most specific one that
        // actually covers this run — and a withdrawn authority outranks every
        // workload scope, because it is the answer that tells the caller their
        // credential is the problem rather than the agent.
        match quotas.halts().await {
            Ok(halts) => {
                if let Some(halt) = halts
                    .into_iter()
                    .filter(|halt| halt.scope.covers(governed_by, chain))
                    .max_by(|a, b| a.scope.cmp(&b.scope))
                {
                    return Err(RuntimeError::QuotaExceeded(
                        crate::quota::QuotaError::Halted {
                            tenant: self.tenant.as_str().to_owned(),
                            scope: halt.scope,
                            reason: halt.reason,
                        },
                    ));
                }
            }
            Err(e) => {
                return Err(RuntimeError::QuotaExceeded(
                    crate::quota::QuotaError::Unavailable(e.to_string()),
                ));
            }
        }

        // What the run can cost at most, held against the period in the same
        // store transaction that checks the ceiling and takes the slot. A run
        // that leaves a bounded unit unbounded is refused here: admitted, it
        // would hold nothing against a period it can spend without limit.
        let hold = match crate::quota::reservation(&self.quota, budget, width as u64) {
            Ok(amount) => {
                amount
                    .zip(pass.period())
                    .map(|(amount, period)| crate::quota::SpendHold {
                        period: period.to_owned(),
                        amount,
                    })
            }
            Err(field) => {
                return Err(RuntimeError::QuotaExceeded(
                    crate::quota::QuotaError::Unbounded {
                        tenant: self.tenant.as_str().to_owned(),
                        unit: if field.contains("minor") {
                            "money"
                        } else {
                            "tokens"
                        },
                        field,
                    },
                ));
            }
        };

        quotas
            .reserve(run, &self.quota, hold.as_ref(), at)
            .await
            .map_err(RuntimeError::QuotaExceeded)?;
        Ok(pass)
    }

    /// Atomically settle this pass's spend and admission slot.
    ///
    /// Required before physical sealing and lease release. A failure keeps the
    /// lease owned so the abandonment sweep retries from journal evidence; a
    /// best-effort write here would turn a transient store outage into permanent
    /// under-accounting. The period is the one captured when this pass started,
    /// never recomputed here.
    async fn settle_quota(
        &self,
        run: RunId,
        epoch: crate::core::Epoch,
        spend: Spend,
        pass: &QuotaPass,
        concludes: bool,
    ) -> Result<(), RuntimeError> {
        let Some(quotas) = self.quotas.as_ref() else {
            return Ok(());
        };
        let pending = |error: crate::core::StoreError| RuntimeError::QuotaSettlementPending {
            run: run.to_string(),
            epoch,
            detail: error.to_string(),
        };
        if !pass.enabled {
            // A conclusion no pass opened — an abandonment decided while the
            // run was stopped — still ends the run, and a run that has ended
            // holds nothing against the period.
            if concludes {
                quotas.release(run).await.map_err(pending)?;
            }
            return Ok(());
        }
        let settlement = pass
            .settlement(run, epoch, spend, concludes)
            .expect("an enabled quota pass has a settlement");
        quotas.settle(&settlement).await.map_err(pending)
    }

    /// Release a reservation for an admission whose journal never existed.
    pub(crate) async fn release_empty_quota_reservation(
        &self,
        run: RunId,
    ) -> Result<(), crate::core::StoreError> {
        match self.quotas.as_ref() {
            Some(quotas) => quotas.release(run).await,
            None => Ok(()),
        }
    }

    /// Settle and release the admission slots sealed runs still hold.
    ///
    /// A plane with no quota store may seal a run whose admission holds a
    /// slot in this ledger, and no resume or recovery selects a sealed run
    /// again. Settlement is idempotent, so a slot another path already settled
    /// is not billed twice. Returns how many slots were given back.
    pub(crate) async fn release_sealed_slots(&self, limit: usize) -> Result<usize, RuntimeError> {
        let Some(quotas) = self.quotas.as_ref() else {
            return Ok(0);
        };
        let held = quotas
            .running_runs(limit)
            .await
            .map_err(RuntimeError::Store)?;
        let positions = self
            .store
            .log_positions(&held)
            .await
            .map_err(RuntimeError::from_store)?;
        let mut released = 0;
        for (run, sealed) in held.into_iter().zip(positions) {
            if sealed.is_none() {
                continue;
            }
            let records = self
                .store
                .read(run, 1)
                .await
                .map_err(RuntimeError::from_store)?;
            match self.settle_recorded_quota_passes(run, &records).await {
                Ok(()) => released += 1,
                Err(error) => tracing::warn!(
                    %run,
                    %error,
                    "a sealed run's admission slot could not be released; the next sweep retries"
                ),
            }
        }
        Ok(released)
    }

    /// Seal the lease-free runs whose sealing conclusion is written and whose
    /// seal is not.
    ///
    /// Each [`LEASE_FREE_OUTCOMES`] writer appends its conclusion and then
    /// seals in a second call, and holds no lease, so recovery never selects
    /// a run whose writer died between the two. The conclusion alone already
    /// lists the run under its outcome, so a history reads it as done while
    /// the audit finds it in no log. The conclusion is what was decided; the
    /// seal adds nothing to it but the log position, so finishing it here
    /// writes no decision the writer did not make.
    ///
    /// Looks at the newest `limit` runs of each outcome. Returns how many it
    /// sealed.
    pub(crate) async fn seal_unsealed_conclusions(
        &self,
        limit: usize,
    ) -> Result<usize, RuntimeError> {
        let mut sealed = 0;
        for &outcome in LEASE_FREE_OUTCOMES {
            let runs = self
                .store
                .runs_by_outcome(outcome, limit)
                .await
                .map_err(RuntimeError::from_store)?;
            let positions = self
                .store
                .log_positions(&runs)
                .await
                .map_err(RuntimeError::from_store)?;
            for (run, position) in runs.into_iter().zip(positions) {
                if position.is_some() {
                    continue;
                }
                match self.store.seal(run, LEASE_FREE_EPOCH, outcome).await {
                    Ok(_) => sealed += 1,
                    Err(error) => tracing::warn!(
                        %run,
                        %error,
                        "a concluded run's seal could not be finished; the next sweep retries"
                    ),
                }
            }
        }
        Ok(sealed)
    }

    /// Settle every quota pass present in history, idempotently.
    ///
    /// Reached before a resume can dispatch. A normally settled pass is a cheap
    /// receipt lookup; a pass whose process died is accrued here. Conclusions
    /// carry the exact in-memory live total, including a known outcome whose
    /// terminal effect record failed before a later append recovered. An
    /// unconcluded crash has only durable terminal effect records to sum.
    async fn settle_recorded_quota_passes(
        &self,
        run: RunId,
        records: &[Record],
    ) -> Result<(), RuntimeError> {
        // A plane with no ledger resumes a run only when no pass of it accrued
        // spend to a period, which would otherwise go unbilled. It cannot give
        // back the concurrency slot of an admission whose process died
        // mid-pass; the ledger's own plane does, on its next sweep once the
        // run is sealed.
        let Some(quotas) = self.quotas.as_ref() else {
            if records.iter().any(|record| {
                matches!(
                    record.kind(),
                    RecordKind::QuotaPassStarted {
                        period: Some(_),
                        ..
                    }
                )
            }) {
                return Err(RuntimeError::PlanContract(
                    "this run has passes that accrued spend to a quota period, and the resuming \
                     plane has no quota store to settle them"
                        .to_owned(),
                ));
            }
            return Ok(());
        };

        for record in records {
            let RecordKind::QuotaPassStarted {
                period,
                release_slot,
            } = record.kind()
            else {
                continue;
            };
            let epoch = record.body.epoch;
            let spend = records
                .iter()
                .rev()
                .find_map(|candidate| (candidate.body.epoch == epoch).then_some(candidate.kind()))
                .and_then(|kind| match kind {
                    RecordKind::RunConcluded { live_spend, .. } => Some(*live_spend),
                    _ => None,
                })
                .unwrap_or_else(|| spend_recorded_in_epoch(records, epoch));
            quotas
                .settle(&crate::quota::QuotaSettlement {
                    run,
                    epoch,
                    period: period.clone(),
                    spend,
                    release_slot: *release_slot,
                    concludes: concluded_in(records, epoch),
                })
                .await
                .map_err(|error| RuntimeError::QuotaSettlementPending {
                    run: run.to_string(),
                    epoch,
                    detail: error.to_string(),
                })?;
        }
        // A run whose history has ended holds nothing against the period,
        // whichever path ended it — including one no pass marker opened.
        if records.iter().any(is_sealing_conclusion) {
            quotas
                .release(run)
                .await
                .map_err(|error| RuntimeError::QuotaSettlementPending {
                    run: run.to_string(),
                    epoch: records.last().map_or(0, |r| r.body.epoch),
                    detail: error.to_string(),
                })?;
        }
        Ok(())
    }

    /// Repair quota receipts, and finish a conclusion an owner died after.
    ///
    /// Under recovery, a run whose last record is a conclusion lost its owner
    /// between concluding and handing the lease back. What remains is the seal and the release, never the business
    /// work: recovery is not permission to retry a failure, with or without a
    /// quota store. A run that crashed before concluding continues through
    /// replay.
    async fn recover_quota_before_resume(
        &self,
        run: RunId,
        records: &[Record],
        lease: &crate::journal::Lease,
        recovering: bool,
    ) -> Result<Option<RunOutcome>, RuntimeError> {
        self.settle_recorded_quota_passes(run, records).await?;
        if !recovering {
            return Ok(None);
        }
        let Some(last) = records.last() else {
            return Ok(None);
        };
        let RecordKind::RunConcluded {
            outcome,
            reason,
            exhaustion,
            ..
        } = last.kind()
        else {
            return Ok(None);
        };

        let status = recorded_status(outcome, reason.as_deref(), exhaustion.as_ref(), records);
        let chain_head = if SEALED_OUTCOMES.contains(&outcome.as_str()) {
            let head = self
                .store
                .seal(run, lease.epoch, outcome)
                .await
                .map_err(RuntimeError::from_store)?;
            // A repaired seal is a conclusion like any other.
            self.retire_waits(run).await;
            head
        } else {
            self.store
                .head(run)
                .await
                .map_err(RuntimeError::from_store)?
                .hash
        };
        Ok(Some(RunOutcome {
            run_id: run,
            status,
            chain_head,
            consumed: Consumed::default(),
            output: None,
        }))
    }

    /// Return a closed run without continuing it, repairing a missing physical
    /// seal when a crash landed after the conclusion append.
    async fn closed_resume_outcome(
        &self,
        run: RunId,
        records: &[Record],
        lease: &crate::journal::Lease,
    ) -> Result<Option<RunOutcome>, RuntimeError> {
        let Some(status) = resume_is_closed(records) else {
            return Ok(None);
        };
        let outcome = recorded_conclusion(records).unwrap_or_else(|| status.as_str().to_owned());
        let chain_head = if SEALED_OUTCOMES.contains(&outcome.as_str()) {
            let head = self
                .store
                .seal(run, lease.epoch, &outcome)
                .await
                .map_err(RuntimeError::from_store)?;
            // The crash this repairs may have landed before the conclusion
            // retired the run's waits; retiring twice is harmless.
            self.retire_waits(run).await;
            head
        } else {
            self.store
                .head(run)
                .await
                .map_err(RuntimeError::from_store)?
                .hash
        };
        Ok(Some(RunOutcome {
            run_id: run,
            status,
            chain_head,
            output: None,
            consumed: Consumed::default(),
        }))
    }

    /// Finish an abandonment a decision asked for and a crash interrupted.
    ///
    /// The instruction is journaled before it is acted on, so this is what
    /// makes the ending arrive whatever happened in between — and it is the
    /// same path the verb itself takes, rather than a repair beside it.
    ///
    /// Nothing is unwound and no step runs: the run seals holding whatever it
    /// left in the world, which is the whole content of the decision.
    async fn abandon_if_decided(
        &self,
        run: RunId,
        records: &[Record],
        lease: &crate::journal::Lease,
    ) -> Result<Option<RunOutcome>, RuntimeError> {
        let Some(status) = pending_abandonment(records) else {
            return Ok(None);
        };
        self.conclude(
            run,
            lease.epoch,
            status,
            None,
            true,
            recorded_case_id(records),
            Consumed::default(),
            Spend::ZERO,
            &QuotaPass::disabled(),
        )
        .await
        .map(Some)
    }

    /// This plane, writing through a journal that puts `quota`'s marker on
    /// the pass's first append — so a pass that writes nothing leaves no
    /// marker. `None` for a pass with no marker.
    fn marking_pass(&self, run: RunId, quota: &QuotaPass) -> Option<Self> {
        let marker = quota.started()?;
        Some(Self {
            store: Arc::new(super::pass_journal::PassJournal::new(
                Arc::clone(&self.store),
                run,
                marker,
            )),
            ..self.clone()
        })
    }

    /// Open the quota identity of the live tail a resume is about to execute.
    ///
    /// Its marker is not written here: it rides the pass's first append (see
    /// [`super::pass_journal`]), so a resume that writes nothing leaves none.
    async fn start_replay_quota_pass(
        &self,
        run: RunId,
        mode: Mode,
        width: usize,
    ) -> Result<QuotaPass, RuntimeError> {
        let (Mode::Resume, Some(quotas)) = (mode, self.quotas.as_ref()) else {
            return Ok(QuotaPass::disabled());
        };
        let pass = QuotaPass::at(&self.quota, now_for_admission(), false).sized_for(width);
        // The run spends in the period it resumes in, so what it still holds
        // moves there — never refused, because a resume is not.
        if let Some(period) = pass.period() {
            quotas
                .carry(run, period)
                .await
                .map_err(RuntimeError::Store)?;
        }
        Ok(pass)
    }

    /// The ceilings a run gets: its agent's, or the plane's if it has no agent.
    ///
    /// Per agent, because that is who declared them. A plane-wide budget would
    /// let one agent's generosity bound another's runs, which is the whole
    /// reason a declaration belongs to an identity rather than to a process.
    fn budget_for(&self, target: &str) -> Budget {
        #[cfg(feature = "manifest")]
        if let Ok(skill) = self.resolve(target)
            && let Some(m) = self.governing(skill.as_ref())
        {
            return m.budget();
        }
        let _ = target;
        self.budget
    }

    /// Which declaration governs runs of this capability, if a declared agent
    /// does.
    ///
    /// Resolved the same way the budget is, and for the same reason: a run is
    /// governed by the agent that answers its entry capability. A commissioned
    /// sub-run opens its own run and records its own governor, so every run in a
    /// room has exactly one — there is no case where this has to pick.
    ///
    /// A manifest that cannot produce a digest is one that could not have been
    /// published; recording `None` would claim the run was ungoverned, so the
    /// failure is surfaced as an absent identity rather than a false one.
    #[cfg(feature = "manifest")]
    fn identity_for(&self, target: &str) -> Option<crate::journal::AgentIdentity> {
        let skill = self.resolve(target).ok()?;
        self.identity_of(self.governing(skill.as_ref())?.as_ref())
    }

    /// What the agent answering `capability` may do, as its declaration says.
    ///
    /// `None` when nothing on this plane answers it; a reach with no
    /// declaration when something does and no declaration governs it.
    #[cfg(feature = "manifest")]
    pub(crate) fn reach_of(&self, capability: &str) -> Option<crate::core::Reach> {
        let skill = self.resolve(capability).ok()?;
        let declaration = self.governing(skill.as_ref()).and_then(|manifest| {
            let digest = manifest.digest().ok()?;
            Some(super::reach::declared(&manifest, digest, |server| {
                self.peers.as_ref().is_some_and(|wiring| {
                    wiring
                        .registry
                        .grant(&crate::peers::PeerId::new(server))
                        .is_some()
                })
            }))
        });
        Some(crate::core::Reach {
            capability: capability.to_owned(),
            declaration,
        })
    }

    /// The declaration's identity, as every gate reports it.
    ///
    /// One construction, because admission and each effect gate must name the
    /// same revision the same way: two spellings of *which agent is acting*
    /// would let a rule permitted at the door mean something else at the sink.
    #[cfg(feature = "manifest")]
    fn identity_of(&self, m: &crate::manifest::Manifest) -> Option<crate::journal::AgentIdentity> {
        Some(crate::journal::AgentIdentity {
            name: m.metadata.name.clone(),
            version: m.metadata.version.clone(),
            digest: m.digest().ok()?,
            publisher: self.published_by.get(&m.metadata.name).cloned(),
        })
    }

    /// Whether anything on this plane answers `target`.
    ///
    /// For a catalogue built before the first call: a surface that advertises a
    /// capability nothing provides offers a caller — often a model — a verb
    /// that fails at admission every time, and the failure names the plane
    /// rather than the catalogue that lied about it.
    ///
    /// Gated on the feature that builds a catalogue, so a build without one
    /// answers *this question is not asked here* rather than carrying a method
    /// nothing reaches.
    #[cfg(feature = "mcp-server")]
    pub(crate) fn provides(&self, target: &str) -> bool {
        self.resolve(target).is_ok()
    }

    /// Whether a grant's server component names a registered A2A peer — a
    /// call the run may wait on.
    #[cfg(feature = "mcp-server")]
    pub(crate) fn wires_peer(&self, server: &str) -> bool {
        self.peers.as_ref().is_some_and(|wiring| {
            wiring
                .registry
                .grant(&crate::peers::PeerId::new(server))
                .is_some()
        })
    }

    fn resolve(&self, target: &str) -> Result<Arc<dyn Skill>, RuntimeError> {
        if let Some(s) = self.skills.get(target) {
            return Ok(Arc::clone(s));
        }
        let cap = Capability::new(target);
        if let Some(name) = self.by_capability.get(&cap)
            && let Some(s) = self.skills.get(name)
        {
            return Ok(Arc::clone(s));
        }
        // Capabilities rather than skill names: `run` is documented to take the
        // capability, and listing the names would answer a question nobody
        // asked with vocabulary that does not work in the call that failed.
        let mut available: Vec<String> = self
            .by_capability
            .keys()
            .map(std::string::ToString::to_string)
            .collect();
        available.sort();
        Err(RuntimeError::NoProvider {
            target: target.to_owned(),
            available,
        })
    }

    /// Execute a fresh run with no case attached.
    ///
    /// The input arrives **labelled**, and that is the whole of the decision.
    /// [`Tainted::trusted`](crate::core::Tainted::trusted) is what an operator
    /// writes for a literal, a constant or a configuration value they vouch for;
    /// anything that came from outside — an inbound event, a queue message, a
    /// counterparty's payload — keeps the label it arrived with.
    ///
    /// This took a bare `Value` and admitted it as `Trusted` by default. A
    /// deployment whose runs are started by inbound events passed counterparty
    /// data straight in, and three controls went quiet at once: `require_trusted`
    /// protected fields were satisfied by attacker-chosen values, the egress
    /// ceiling had nothing untrusted to join with, and the journal recorded no
    /// contact with outside data. Nothing failed and the suite stayed green,
    /// which is the profile of every other default this crate declines to offer.
    ///
    /// A `run_trusted`/`run_tainted` pair was tried first and is worse: it
    /// doubles every shape, puts `run_trusted_in_case` one word away from
    /// `run_tainted_in_case`, and still lets `run_trusted(cap, payload)` compile
    /// over data nobody vouched for. A label is a **value** — it can be
    /// computed, threaded through an adapter, or derived from where a message
    /// arrived, none of which a method name can do. [`spawn`](Self::spawn)
    /// already worked this way; `run` was the outlier.
    ///
    /// # Errors
    ///
    /// [`RuntimeError::NoProvider`] when no skill provides `target`, and
    /// whatever admission refuses — policy, quota, a halted tenant, an instance
    /// draining, a lease.
    pub async fn run(
        &self,
        target: &str,
        input: Tainted<Value>,
    ) -> Result<RunOutcome, RuntimeError> {
        self.admit(target, input, RunTerms::default()).await
    }

    /// Admit a run and let it proceed in the background, returning its id.
    ///
    /// The asynchronous counterpart to [`run`](Self::run), for
    /// callers that want a handle rather than an answer — A2A's
    /// `return_immediately`, a queue worker, an operator kicking something off.
    ///
    /// **Admission happens before this returns.** The policy gate, the lease and
    /// the admission records are all written first, so a refusal is an error
    /// here and not a task that never appears, and the id handed back can be
    /// read immediately. What continues in the background is the *work*.
    ///
    /// The run is durable, so a process that dies mid-flight leaves a journal
    /// another instance resumes; the background task is where the work happens,
    /// not where it is kept.
    ///
    /// # Panics
    ///
    /// Outside a Tokio runtime, as the rest of this crate's timing does.
    ///
    /// # Errors
    ///
    /// As [`run`](Self::run) — anything admission itself refuses.
    pub async fn spawn(
        self: &Arc<Self>,
        target: &str,
        input: Tainted<Value>,
    ) -> Result<RunId, RuntimeError> {
        self.spawn_bound(target, input, RunTerms::default()).await
    }

    async fn spawn_bound(
        self: &Arc<Self>,
        target: &str,
        input: Tainted<Value>,
        terms: RunTerms,
    ) -> Result<RunId, RuntimeError> {
        // Resolved before the id is minted: an unknown capability is the
        // caller's mistake and must be an error, not a run that exists and
        // immediately fails.
        let skill = self.resolve(target)?;
        let capability = first_capability(&skill.descriptor());

        let run = RunId::generate();
        // Registered before admission, not after. Admission is several store
        // writes, and a drain beginning inside them would take its snapshot
        // without this run, report a complete stop, and let the process exit
        // while the run was still being admitted. Registered first, both orders
        // work out: a drain that starts after this waits for the run, and one
        // that starts before it is seen by the gate inside `admit_only`, which
        // refuses and drops the ticket on the way out.
        let ticket = self.inflight.enter(run);
        let admitted = self
            .admit_only(
                run,
                PlanIR::single(capability),
                input,
                terms,
                Entry::Outside,
            )
            .await?;

        let plane = Arc::clone(self);
        tokio::spawn(async move {
            let _ticket = ticket;
            plane.execute_admitted(admitted).await
        });
        Ok(run)
    }

    /// Start a new immutable run inside a case that already exists.
    pub async fn run_in_case(
        &self,
        target: &str,
        input: Tainted<Value>,
        case: crate::core::CaseId,
    ) -> Result<RunOutcome, RuntimeError> {
        self.admit(target, input, RunTerms::bound(CaseBinding::Existing(case)))
            .await
    }

    /// Join or open a case by business key, then run.
    ///
    /// Correlation happens **before planning**, because which case a message
    /// belongs to is a question of fact, not of judgement: it is a deterministic
    /// lookup on business keys, never a model call. If an open case matches any
    /// key the run joins it; otherwise a case is opened.
    pub async fn run_correlated(
        &self,
        target: &str,
        input: Tainted<Value>,
        case_kind: &str,
        keys: &[CorrelationKey],
    ) -> Result<RunOutcome, RuntimeError> {
        self.admit(
            target,
            input,
            RunTerms::default().correlated(case_kind, keys),
        )
        .await
    }

    /// Run under an admission key, at most once per tenant.
    ///
    /// The entry point for an at-least-once emitter: a bus that retries until it
    /// sees a 2xx, a webhook fan-out, a queue with redelivery. The store claims
    /// the key in the same transaction that writes the run's first record, so a
    /// second call under it cannot admit a second run — not on a retry, not
    /// across a restart, not from another instance sharing the store.
    ///
    /// # The key must carry its producer
    ///
    /// An id is unique only within one emitter, so a bare message id lets two
    /// counterparties swallow each other's messages as apparent retries.
    /// [`InboundEvent::dedup_key`](crate::core::InboundEvent::dedup_key) is the
    /// ready-made spelling, and the same identity the event buffer uses.
    ///
    /// # Not the event buffer
    ///
    /// [`EventStore::buffer`](crate::case::EventStore::buffer) also reports
    /// "already seen" for a `(source, id)` over the same store, and looks like
    /// the primitive. It is not: an event nobody subscribes to is dead-lettered
    /// by [`sweep`](Self::sweep), and a non-empty dead-letter list means a
    /// correlation key is wrong somewhere. Using the buffer as an idempotency
    /// ledger would dead-letter nearly every message admitted directly, spending
    /// that signal to buy deduplication. Two concerns can share an identity
    /// without sharing a table.
    ///
    /// # Errors
    ///
    /// As [`run`](Self::run). A key already held is not an error — it comes back
    /// as [`Admission::Replayed`] or [`Admission::InFlight`].
    pub async fn run_once(
        &self,
        target: &str,
        input: Tainted<Value>,
        idempotency_key: &str,
    ) -> Result<Admission, RuntimeError> {
        self.admit_once(target, input, RunTerms::default().keyed(idempotency_key))
            .await
    }

    /// Join or open a case by business key and run, at most once per admission
    /// key.
    ///
    /// The shape an inbound message actually has: it names a matter by business
    /// key *and* carries its own identity. Correlation decides **which case**,
    /// the admission key decides **whether at all** — correlation alone would
    /// join the duplicate to the right case and start a second run inside it.
    ///
    /// # Errors
    ///
    /// As [`run_correlated`](Self::run_correlated).
    pub async fn run_correlated_once(
        &self,
        target: &str,
        input: Tainted<Value>,
        case_kind: &str,
        keys: &[CorrelationKey],
        idempotency_key: &str,
    ) -> Result<Admission, RuntimeError> {
        self.admit_once(
            target,
            input,
            RunTerms::default()
                .correlated(case_kind, keys)
                .keyed(idempotency_key),
        )
        .await
    }

    /// Correlate and spawn, at most once per admission key.
    ///
    /// # Panics
    ///
    /// Outside a Tokio runtime, as [`spawn`](Self::spawn) does.
    ///
    /// # Errors
    ///
    /// As [`spawn`](Self::spawn).
    pub async fn spawn_correlated_once(
        self: &Arc<Self>,
        target: &str,
        input: Tainted<Value>,
        case_kind: &str,
        keys: &[CorrelationKey],
        idempotency_key: &str,
    ) -> Result<Spawned, RuntimeError> {
        self.spawn_bound_once(
            target,
            input,
            RunTerms::default()
                .correlated(case_kind, keys)
                .keyed(idempotency_key),
        )
        .await
    }

    /// Execute an explicit multi-step plan.
    ///
    /// The plan is validated and frozen *before the first step runs*: one that
    /// would fail at step seven must not begin at step one.
    pub async fn run_plan(
        &self,
        plan: PlanIR,
        input: Tainted<Value>,
    ) -> Result<RunOutcome, RuntimeError> {
        self.admit_plan(plan, input, RunTerms::default()).await
    }

    /// Execute an explicit plan inside a long-lived case.
    pub async fn run_plan_correlated(
        &self,
        plan: PlanIR,
        input: Tainted<Value>,
        case_kind: &str,
        keys: &[CorrelationKey],
    ) -> Result<RunOutcome, RuntimeError> {
        self.admit_plan(plan, input, RunTerms::default().correlated(case_kind, keys))
            .await
    }

    /// Run under explicit [`RunTerms`] — the general form of every `run_*`.
    ///
    /// Keyed terms behave as [`run_once`](Self::run_once): a duplicate comes
    /// back as [`Admission::Replayed`] or [`Admission::InFlight`]. Unkeyed
    /// terms always admit, and the answer is [`Admission::Fresh`].
    ///
    /// # Errors
    ///
    /// As [`run`](Self::run), plus [`RuntimeError::Delegation`] when the terms
    /// carry a chain this plane may not act under now.
    pub async fn run_under(
        &self,
        target: &str,
        input: Tainted<Value>,
        terms: RunTerms,
    ) -> Result<Admission, RuntimeError> {
        if terms.idempotency_key.is_some() {
            self.admit_once(target, input, terms).await
        } else {
            self.admit(target, input, terms).await.map(Admission::Fresh)
        }
    }

    /// Spawn under explicit [`RunTerms`] — the general form of every `spawn_*`.
    ///
    /// # Panics
    ///
    /// Outside a Tokio runtime, as [`spawn`](Self::spawn) does.
    ///
    /// # Errors
    ///
    /// As [`run_under`](Self::run_under).
    pub async fn spawn_under(
        self: &Arc<Self>,
        target: &str,
        input: Tainted<Value>,
        terms: RunTerms,
    ) -> Result<Spawned, RuntimeError> {
        if terms.idempotency_key.is_some() {
            self.spawn_bound_once(target, input, terms).await
        } else {
            let run = self.spawn_bound(target, input, terms).await?;
            Ok(Spawned { run, fresh: true })
        }
    }

    /// Execute an explicit plan under [`RunTerms`].
    ///
    /// Keyed terms admit once, as every `_once` entry point does: the key is
    /// validated, and a redelivery is answered by the run it already admitted.
    ///
    /// # Errors
    ///
    /// As [`run_plan`](Self::run_plan) and [`run_under`](Self::run_under).
    pub async fn run_plan_under(
        &self,
        plan: PlanIR,
        input: Tainted<Value>,
        terms: RunTerms,
    ) -> Result<Admission, RuntimeError> {
        let Some(key) = terms.idempotency_key.clone() else {
            return Ok(Admission::Fresh(self.admit_plan(plan, input, terms).await?));
        };
        validate_admission_key(&key)?;
        if let Some(held) = self.holder_of(&key).await? {
            return self.answer_with(held).await;
        }
        match self.admit_plan(plan, input, terms).await {
            Ok(outcome) => Ok(Admission::Fresh(outcome)),
            Err(RuntimeError::Store(crate::core::StoreError::DuplicateAdmission {
                run, ..
            })) => self.answer_with(parse_holder(&run)?).await,
            Err(e) => Err(e),
        }
    }

    /// Admission under a key, for the blocking `_once` entry points.
    ///
    /// Two gates, and only the second arbitrates. The read below is an
    /// optimisation — it saves a redelivery the cost of a policy evaluation, a
    /// quota reservation, a lease and a correlation lookup — and settles
    /// nothing, since two instances racing both see nothing here. The
    /// constraint inside `append` decides, on the same division
    /// `CaseStore::correlate_or_open` runs on.
    async fn admit_once(
        &self,
        target: &str,
        input: Tainted<Value>,
        terms: RunTerms,
    ) -> Result<Admission, RuntimeError> {
        let key = terms
            .idempotency_key
            .clone()
            .expect("admit_once is only reached with a key");
        validate_admission_key(&key)?;
        if let Some(held) = self.holder_of(&key).await? {
            return self.answer_with(held).await;
        }
        match self.admit(target, input, terms).await {
            Ok(outcome) => Ok(Admission::Fresh(outcome)),
            Err(RuntimeError::Store(crate::core::StoreError::DuplicateAdmission {
                run, ..
            })) => self.answer_with(parse_holder(&run)?).await,
            Err(e) => Err(e),
        }
    }

    /// [`admit_once`](Self::admit_once) for the non-blocking pair.
    async fn spawn_bound_once(
        self: &Arc<Self>,
        target: &str,
        input: Tainted<Value>,
        terms: RunTerms,
    ) -> Result<Spawned, RuntimeError> {
        let key = terms
            .idempotency_key
            .clone()
            .expect("spawn_bound_once is only reached with a key");
        validate_admission_key(&key)?;
        if let Some(run) = self.holder_of(&key).await? {
            return Ok(Spawned { run, fresh: false });
        }
        match self.spawn_bound(target, input, terms).await {
            Ok(run) => Ok(Spawned { run, fresh: true }),
            Err(RuntimeError::Store(crate::core::StoreError::DuplicateAdmission {
                run, ..
            })) => Ok(Spawned {
                run: parse_holder(&run)?,
                fresh: false,
            }),
            Err(e) => Err(e),
        }
    }

    /// Which run holds this admission key, if any.
    async fn holder_of(&self, key: &str) -> Result<Option<RunId>, RuntimeError> {
        self.store
            .admitted_as(key)
            .await
            .map_err(RuntimeError::from_store)
    }

    /// Answer a duplicate with what the original run has on the record.
    async fn answer_with(&self, held: RunId) -> Result<Admission, RuntimeError> {
        Ok(match self.recorded_outcome(held).await? {
            Some(outcome) => Admission::Replayed(outcome),
            None => Admission::InFlight(held),
        })
    }

    /// What a run has recorded, **without resuming it**.
    ///
    /// `None` while the run is still working — it has records but has reached
    /// neither a conclusion nor a suspension.
    ///
    /// No lease is taken and nothing is appended. The original is frequently
    /// live when its redelivery lands, and a read that acquired a lease would
    /// fence a healthy run mid-step in order to report on it.
    ///
    /// The **last** record decides, never any record: a run that suspended, was
    /// resumed and carried on has a suspension in its history and is not
    /// suspended now. Same rule as the A2A status projection, so the two
    /// surfaces cannot disagree about one run.
    ///
    /// # Errors
    ///
    /// If the journal cannot be read.
    pub async fn recorded_outcome(&self, run: RunId) -> Result<Option<RunOutcome>, RuntimeError> {
        let records = self
            .store
            .read(run, 1)
            .await
            .map_err(RuntimeError::from_store)?;
        let Some(last) = records.last() else {
            return Ok(None);
        };
        let Some(status) = observed_status(&records) else {
            return Ok(None);
        };
        Ok(Some(RunOutcome {
            run_id: run,
            status,
            chain_head: last.hash,
            // Reading a record performs nothing, so it consumes nothing — the
            // same answer the closed-run path gives, and for the same reason:
            // the spend belongs to the pass that did the work.
            consumed: Consumed::default(),
            // A step's result is reconstructed by replay rather than stored, so
            // there is none to hand back here. See `Admission::Replayed`.
            output: None,
        }))
    }

    /// Rebuild a run's case binding **from its history**, never by re-deriving.
    ///
    /// Two facts are read back rather than recomputed, and each has its own
    /// failure if it is not.
    ///
    /// The **case id**, because re-correlating could land on a different case if
    /// the keys were since released — silently rewriting which business fact the
    /// run belongs to.
    ///
    /// The **business keys**, because a case accumulates them over months. A run
    /// that resolved `memory.formation.subject: $correlation/meter` would
    /// otherwise resolve it against a set the live run never saw, write a second
    /// memory under a second subject, and produce a history that disagrees with
    /// itself with nothing on the record explaining why.
    fn recorded_case(&self, records: &[Record]) -> Option<CaseContext> {
        let (case_id, correlation) = records.iter().find_map(|r| match r.kind() {
            RecordKind::CaseBound { correlation, .. } => {
                r.body.case.map(|case_id| (case_id, correlation.clone()))
            }
            _ => None,
        })?;
        self.cases.as_ref().map(|cases| CaseContext {
            cases: Arc::clone(cases),
            tasks: self.tasks.clone(),
            events: self.events.clone(),
            calendar: Arc::clone(&self.calendar),
            case_id,
            correlation,
        })
    }

    /// The contract this runtime enforces on every plan.
    pub(crate) fn contract(&self) -> crate::plan::Contract {
        let contract = crate::plan::Contract::new(self.by_capability.keys().cloned());
        if self.require_verifier {
            contract.require_verifier()
        } else {
            contract
        }
    }

    async fn admit(
        &self,
        target: &str,
        input: Tainted<Value>,
        terms: RunTerms,
    ) -> Result<RunOutcome, RuntimeError> {
        // A bare target is the degenerate plan: one node, terminal.
        let skill = self.resolve(target)?;
        let capability = first_capability(&skill.descriptor());
        self.admit_plan(PlanIR::single(capability), input, terms)
            .await
    }

    async fn admit_plan(
        &self,
        plan: PlanIR,
        input: Tainted<Value>,
        terms: RunTerms,
    ) -> Result<RunOutcome, RuntimeError> {
        self.admit_plan_as(RunId::generate(), plan, input, terms, Entry::Outside)
            .await
    }

    /// Admit the run one already-executing run ordered from another agent.
    ///
    /// Apart from every other entry point for one reason: a commission is a
    /// *step* of a run this process is executing, so the drain gate must not
    /// see it. A drain that refused here would fail the commissioning step of
    /// exactly the runs it is waiting for — and that step's failure is
    /// `Interrupted`, the in-doubt classification, because a commissioning
    /// caller cannot know what the agent it ordered from managed to do. The
    /// drain would manufacture the state it exists to prevent.
    pub(crate) async fn commission_run(
        &self,
        target: &str,
        input: Tainted<Value>,
        terms: RunTerms,
    ) -> Result<RunOutcome, RuntimeError> {
        let skill = self.resolve(target)?;
        let capability = first_capability(&skill.descriptor());
        self.admit_plan_as(
            RunId::generate(),
            PlanIR::single(capability),
            input,
            terms,
            Entry::Nested,
        )
        .await
    }

    /// Record the chain this run acts under, beside the plan it authorizes.
    ///
    /// The two are read back together: a chain without its plan says nothing
    /// about what it was allowed to do, and a plan without its chain says
    /// nothing about who was allowed to run it.
    fn bind_identity(
        run: RunId,
        chain: Option<&crate::core::Delegation>,
        records: &mut Vec<Append>,
    ) {
        if let Some(chain) = chain {
            records.push(Append::new(
                run,
                RecordKind::IdentityBound {
                    chain: chain.links().cloned().collect(),
                },
            ));
        }
    }

    /// Check the plan against the delegation chain's authority.
    ///
    /// The plan is the authorization graph, so this is where authority belongs:
    /// a plan that names a capability outside the chain's scope must never
    /// start, rather than failing at whichever step happens to reach it first.
    /// Checking here also makes the refusal deterministic — it depends only on
    /// the frozen plan and the chain, both of which are recorded.
    ///
    /// The chain's other two bounds are checked beside it, and only here: a
    /// chain issued for another plane or past its validity is refused before
    /// the run exists, and a run admitted under a live chain is never re-judged
    /// — replay reads the recorded chain back.
    ///
    /// `acts_under` is whether the run acts under `ceiling` or is only bounded
    /// by it. A refusal names the chain's subject only in the first case: a
    /// caller bounded by the plane's chain is not its subject, and a denial
    /// naming the operator would say the operator was refused.
    fn authorize_scope(
        &self,
        plan: &PlanIR,
        ceiling: Option<&crate::core::Delegation>,
        acts_under: bool,
    ) -> Result<(), RuntimeError> {
        let Some(chain) = ceiling else {
            return Ok(());
        };
        chain.admissible(self.tenant.as_str(), now_for_admission())?;
        let scope = chain.effective_scope();
        for node in &plan.nodes {
            if !scope.permits(&node.capability) {
                return Err(RuntimeError::PolicyDenied(
                    crate::core::PolicyError::Denied {
                        principal: if acts_under {
                            chain.subject().id.clone()
                        } else {
                            node.capability.to_string()
                        },
                        action: crate::core::ACTION_ADMIT.to_owned(),
                        resource: node.capability.to_string(),
                    },
                ));
            }
        }
        Ok(())
    }

    /// Authorize starting a run, before the run exists.
    ///
    /// A denial here leaves no journal at all, which is correct: nothing
    /// happened, and a run record for something that was never allowed to start
    /// would be a run nobody can explain.
    fn authorize_admission(
        &self,
        capability: &str,
        governed_by: Option<&crate::journal::AgentIdentity>,
        chain: Option<&crate::core::Delegation>,
        input: &Value,
    ) -> Result<(), RuntimeError> {
        let Some(engine) = self.policy.as_ref() else {
            return Ok(());
        };
        // Who is acting, and what is being asked for. Passing one string as both
        // made every admission rule a tautology — `principal == resource` cannot
        // express "this agent may not run that capability", which is the whole
        // question at admission on a plane hosting several agents.
        //
        // The principal is an **authenticated** identity or it is nothing. The
        // scope check a few lines above already denies under the delegation
        // subject, so anything else here would give one refused run two answers
        // to "who was refused" in the same error type.
        //
        // The agent's `metadata.name` is deliberately *not* used, tempting as it
        // is. A name is self-asserted — a manifest is a file, and its name is
        // whatever the author typed — so a rule granting authority to a name
        // grants it to any file claiming that name. Worse, a fallback would be
        // *silent*: `principal == X` would mean an authenticated identity in a
        // deployment with a delegation chain and a self-asserted label in one
        // without, so the same rule would change meaning with the wiring.
        //
        // Rules that need to bind to the agent bind to `context.agent.digest`,
        // which is content-addressed and pins what the declaration actually
        // said — so "this exact declaration may admit, and an edited one may
        // not" is expressible. The capability is the fallback principal because
        // it claims nothing: it is what was asked for, not who asked.
        //
        // Built by the function `policy check` also calls, from the values
        // `RunAdmitted` and `IdentityBound` record.
        let request = crate::policy::requests::admission(
            &crate::policy::requests::Acting {
                tenant: self.tenant.as_str(),
                capability,
                agent: governed_by,
                chain,
            },
            input,
        );
        // Every refusal, not only a rule's. `let … else` over `Deny` alone
        // admits the run for every other decision, so a policy set that cannot
        // be evaluated would open the door it exists to hold — the fail-open a
        // widened vocabulary creates for free unless the permit is the arm that
        // has to be named.
        let decision = engine.authorize(&request.as_request());
        let malformed = decision.is_malformed();
        let Some(reason) = decision.reason().map(ToOwned::to_owned) else {
            return Ok(());
        };

        tracing::error!(
            target: telemetry::POLICY_DENIED,
            action = crate::core::ACTION_ADMIT,
            resource = %capability,
            policy_error = malformed,
            %reason,
        );
        self.meter
            .count(metrics::POLICY_DENIALS, crate::core::ACTION_ADMIT);
        Err(RuntimeError::PolicyDenied(
            crate::core::PolicyError::Denied {
                principal: request.principal,
                action: crate::core::ACTION_ADMIT.to_owned(),
                resource: capability.to_owned(),
            },
        ))
    }

    /// The record that opens a run.
    ///
    /// Its own function because the label matters: journaled rather than
    /// recomputed, so a replay reaches the same verdict at every taint gate as
    /// the run it reproduces.
    fn admission(
        &self,
        capability: &str,
        governed_by: Option<crate::journal::AgentIdentity>,
        input: &Tainted<Value>,
        idempotency_key: Option<String>,
        admitted_by: Option<String>,
        acting_as: &Acting,
    ) -> RecordKind {
        RecordKind::RunAdmitted {
            capability: capability.to_owned(),
            governed_by: governed_by.map(Box::new),
            input: input.peek().clone(),
            input_label: input.label().clone(),
            policy_bundle: self.policy.as_ref().map(|p| Box::new(p.bundle())),
            canon: crate::core::canon::VERSION,
            idempotency_key,
            admitted_by,
            served_unchained: matches!(acting_as, Acting::Nobody),
            plane_chain: match acting_as {
                Acting::Plane => self.identity.is_some(),
                Acting::PlaneDelegate(_) => true,
                Acting::Caller(_) | Acting::Nobody => false,
            },
        }
    }

    /// Everything up to and including the admission records, and no work.
    ///
    /// The seam a non-blocking submit needs. Admission is what makes a run
    /// *exist*: the policy gate, the lease, and the records that say what is
    /// about to happen. Splitting there means a caller can be told the run was
    /// accepted — or refused — before any of it runs, and a refusal stays an
    /// immediate answer rather than becoming a task that silently never appears.
    #[allow(clippy::too_many_lines)]
    async fn admit_only(
        &self,
        run: RunId,
        plan: PlanIR,
        input: Tainted<Value>,
        terms: RunTerms,
        entry: Entry,
    ) -> Result<Admitted, RuntimeError> {
        // First, and before the plan is even read: a draining instance is going
        // away, and everything below this line takes on work it may not be able
        // to finish. Refusing here leaves no lease, no quota slot and no
        // journal — the same nothing a policy denial leaves.
        if entry == Entry::Outside && self.inflight.is_draining() {
            return Err(RuntimeError::Draining);
        }
        crate::plan::validate(&plan, &self.contract())
            .map_err(|e| RuntimeError::PlanContract(e.to_string()))?;

        let agent = plan
            .nodes
            .first()
            .map_or_else(|| "plan".to_owned(), |n| n.capability.to_string());

        // Resolved once: the gate and the record must agree about which
        // declaration governs this run, and computing it twice is how they
        // start disagreeing.
        #[cfg(feature = "manifest")]
        let governed_by = self.identity_for(&agent);
        #[cfg(not(feature = "manifest"))]
        let governed_by: Option<crate::journal::AgentIdentity> = None;

        if let Some(expected) = terms.expected_declaration {
            let found = governed_by.as_ref().map(|id| id.digest);
            if found != Some(expected) {
                return Err(RuntimeError::DeclarationPinMismatch {
                    agent,
                    expected,
                    found,
                });
            }
        }

        // The caller's chain where one was presented, the plane's otherwise —
        // one choice, made once, so the gate, the policy context and the
        // record cannot disagree about whom this run acts for.
        let chain = terms.acting_as.resolve(self.identity.as_ref());
        self.authorize_scope(
            &plan,
            terms.acting_as.ceiling(self.identity.as_ref()),
            chain.is_some(),
        )?;
        self.authorize_admission(&agent, governed_by.as_ref(), chain, input.peek())?;
        let input = self.admit_content(&agent, input)?;

        self.admit_reserved(run, plan, input, terms, agent, governed_by)
            .await
    }

    /// Admission past the quota reservation: the lease, the records, the case
    /// binding, the outbox.
    ///
    /// Every error path hands the lease back. A lease left standing over a
    /// failed admission is not idle bookkeeping: it expires unreleased, which
    /// is the exact signature the recovery sweep reads as "an instance died
    /// holding this run" — so a half-admitted run (records appended, outbox
    /// registration failed) would be *executed* by the sweeper a TTL later,
    /// having never been admitted. The one error that concludes rather than
    /// merely unwinding is the post-append one, where records already exist:
    /// the run is concluded `failed` in its own chain first, so nothing later
    /// reads an open journal as work in progress.
    async fn admit_reserved(
        &self,
        run: RunId,
        plan: PlanIR,
        input: Tainted<Value>,
        terms: RunTerms,
        agent: String,
        governed_by: Option<crate::journal::AgentIdentity>,
    ) -> Result<Admitted, RuntimeError> {
        // Ownership precedes reservation. A process can die between any two
        // store calls; with this order, a slot reserved before the admission
        // batch always has an owned lease beside it, and the abandonment sweep
        // can release both. Reserving first could strand a slot over no run and
        // no lease — invisible to every recovery query.
        let lease = self
            .store
            .acquire(run, &self.owner, self.lease_ttl)
            .await
            .map_err(RuntimeError::from_store)?;

        let budget = self.budget_for(&agent);
        // Boxed: the quota decision holds its store round trips across awaits,
        // and inlined it pushes every admission future past the size clippy
        // allows on the served surfaces that await one.
        let quota = match Box::pin(self.check_quota(
            run,
            governed_by.as_ref(),
            // **The chain this run acts under, not the plane's.** A served
            // surface admits each run under its caller's chain, so reading
            // the plane's here would check a withdrawal against the
            // operator's own subject and never match the caller's — a
            // refusal that does not happen, which leaves no trace anywhere.
            terms.acting_as.resolve(self.identity.as_ref()),
            now_for_admission(),
            (&budget, reserved_width(&budget, &plan)),
        ))
        .await
        {
            Ok(pass) => pass,
            Err(error) => {
                let _ = self.store.release_lease(run, lease.epoch).await;
                return Err(error);
            }
        };

        let out = self
            .admit_under_lease(run, &lease, plan, input, terms, &agent, governed_by, quota)
            .await;
        if out.is_err() {
            if let Some(quotas) = self.quotas.as_ref()
                && let Err(error) = quotas.release(run).await
            {
                tracing::debug!(%run, %error, "could not release the quota slot of a failed admission");
            }
            if let Err(error) = self.store.release_lease(run, lease.epoch).await {
                tracing::debug!(
                    %run,
                    %error,
                    "could not release the lease of a failed admission; it will expire on its own"
                );
            }
        }
        out
    }

    #[allow(clippy::too_many_arguments, clippy::too_many_lines)]
    async fn admit_under_lease(
        &self,
        run: RunId,
        lease: &crate::journal::Lease,
        plan: PlanIR,
        input: Tainted<Value>,
        terms: RunTerms,
        agent: &str,
        governed_by: Option<crate::journal::AgentIdentity>,
        quota: QuotaPass,
    ) -> Result<Admitted, RuntimeError> {
        let RunTerms {
            case,
            idempotency_key,
            acting_as,
            admitted_by,
            expected_declaration: _,
            subjects,
        } = terms;
        let chain = acting_as.resolve(self.identity.as_ref());
        let mut records = vec![
            Append::new(
                run,
                self.admission(
                    agent,
                    governed_by,
                    &input,
                    idempotency_key,
                    admitted_by,
                    &acting_as,
                ),
            ),
            // From here the plan is an authorization graph: compiled from
            // trusted input, frozen before anything untrusted was read, and
            // recorded so the journal that follows can be checked against it.
            Append::new(
                run,
                RecordKind::PlanFrozen {
                    steps: plan
                        .nodes
                        .iter()
                        .map(|n| n.capability.to_string())
                        .collect(),
                    plan: serde_json::to_value(&plan)?,
                },
            ),
        ];

        Self::bind_identity(run, chain, &mut records);
        if let Some(started) = quota.started() {
            records.push(Append::new(run, started));
        }

        #[cfg(feature = "manifest")]
        let declared: Vec<crate::journal::SubjectBinding> = self
            .resolve(agent)
            .ok()
            .and_then(|skill| self.governing(skill.as_ref()))
            .map(|m| {
                m.spec
                    .data_subjects
                    .iter()
                    .map(crate::manifest::DataSubject::binding)
                    .collect()
            })
            .unwrap_or_default();
        #[cfg(not(feature = "manifest"))]
        let declared: Vec<crate::journal::SubjectBinding> = Vec::new();
        // Before correlation, because `correlate_or_open` commits a case: a
        // binding that refuses the run must refuse it before anything outside
        // the journal names it. `$case` alone needs the case, and the case is
        // bound whenever the run asked for one, so it cannot refuse later.
        let bound = bind_subjects(&declared, subjects, &input, case.is_some())?;

        // Correlation is deterministic and runs before planning: which case a
        // message belongs to is a matter of fact, settled by a lookup.
        let case_ctx = match (case, self.cases.as_ref()) {
            (Some(CaseBinding::Correlate { kind, keys }), Some(cases)) => {
                let correlation = cases
                    .correlate_or_open(&kind, &keys, now_for_admission())
                    .await
                    .map_err(RuntimeError::from_store)?;
                let case_id = correlation.case_id();
                // The case's own keys, not the ones this message carried. A run
                // that *joined* an existing case may have been admitted with one
                // key while the case holds three, and a binding naming any of
                // them must resolve — which is the difference between "the keys
                // in this request" and "the business facts this matter is
                // identified by".
                let bound_keys = case_correlation(cases.as_ref(), case_id, &keys).await?;
                // Stamp the case on the records already queued as well: every
                // record of a case-bound run carries its case, which is what
                // makes "show me everything about this matter" one range scan.
                for r in &mut records {
                    r.case = Some(case_id);
                }
                records.push(
                    Append::new(
                        run,
                        RecordKind::CaseBound {
                            case_kind: kind,
                            opened: correlation.is_new(),
                            correlation: bound_keys.clone(),
                        },
                    )
                    .case(case_id),
                );
                Some(CaseContext {
                    cases: Arc::clone(cases),
                    tasks: self.tasks.clone(),
                    events: self.events.clone(),
                    calendar: Arc::clone(&self.calendar),
                    case_id,
                    correlation: bound_keys,
                })
            }
            (Some(CaseBinding::Existing(case_id)), Some(cases)) => {
                let existing = cases
                    .case(case_id)
                    .await
                    .map_err(RuntimeError::from_store)?
                    .ok_or_else(|| {
                        RuntimeError::PlanContract(format!("no such case: {case_id}"))
                    })?;
                if existing.status.is_closed() {
                    return Err(RuntimeError::PlanContract(format!(
                        "case '{case_id}' is closed and cannot accept another run"
                    )));
                }
                for record in &mut records {
                    record.case = Some(case_id);
                }
                records.push(
                    Append::new(
                        run,
                        RecordKind::CaseBound {
                            case_kind: existing.kind,
                            opened: false,
                            correlation: existing.correlation.clone(),
                        },
                    )
                    .case(case_id),
                );
                Some(CaseContext {
                    cases: Arc::clone(cases),
                    tasks: self.tasks.clone(),
                    events: self.events.clone(),
                    calendar: Arc::clone(&self.calendar),
                    case_id,
                    correlation: existing.correlation,
                })
            }
            (Some(_), None) => {
                return Err(RuntimeError::PlanContract(
                    "this run was admitted with correlation keys but the runtime has no case \
                     store — build it with `.cases(store)`"
                        .into(),
                ));
            }
            (None, _) => None,
        };

        let bound = fill_case_subjects(bound, case_ctx.as_ref());
        let subject_refs = subject_refs(run, &bound);
        if !bound.is_empty() {
            let mut append = Append::new(run, RecordKind::DataSubjectBound { bindings: bound });
            append.case = case_ctx.as_ref().map(CaseContext::id);
            records.push(append);
        }

        // The append claims the admission key, so a key already held is refused
        // here, before anything outside the journal names the run.
        self.store
            .append(lease.epoch, records)
            .await
            .map_err(RuntimeError::from_store)?;

        // Registered before the run is handed back, and its failure fails
        // admission: a case that does not list the run, or destinations that
        // never see its history.
        //
        // After the append rather than before: a registration written for a
        // run whose admission then failed — or whose process died — would name
        // a run no journal holds, and nothing could tell which case to take it
        // off. The price of that order is paid here instead: the admission
        // records above are already durable, so a registration failure must
        // **conclude** the run rather than merely return — an open journal
        // under a lease that then lapses is exactly what the recovery sweep
        // reads as a crashed run, and it would execute a run whose admission
        // failed. Concluded `failed`, in the chain, with the reason beside it;
        // the caller's cleanup then releases the lease, and a resume registers
        // again before it executes.
        if let Err(open_failed) = self
            .register(run, case_ctx.as_ref().map(CaseContext::id))
            .await
        {
            let head = self
                .store
                .head(run)
                .await
                .map_err(RuntimeError::from_store)?;
            self.store
                .append(
                    lease.epoch,
                    vec![Append::new(
                        run,
                        RecordKind::RunConcluded {
                            outcome: RunStatus::Failed(String::new()).as_str().to_owned(),
                            reason: Some(format!(
                                "the run's registration was refused ({open_failed}), so this \
                                 run was concluded without ever executing"
                            )),
                            exhaustion: None,
                            live_spend: Spend::default(),
                            chain_head: head.hash,
                        },
                    )],
                )
                .await
                .map_err(RuntimeError::from_store)?;
            return Err(RuntimeError::from_store(open_failed));
        }

        Ok(Admitted {
            run,
            epoch: lease.epoch,
            quota,
            budget: self.budget_for(agent),
            agent: agent.to_owned(),
            plan,
            input,
            case: case_ctx,
            identity: chain.cloned(),
            subjects: subject_refs,
        })
    }

    /// Execute a run that has already been admitted.
    async fn execute_admitted(&self, a: Admitted) -> Result<RunOutcome, RuntimeError> {
        let mut cursor = ReplayCursor::default();
        // Named, not `_`: `let _ = ` drops immediately, which would renew
        // nothing at all while looking exactly like this.
        let _heartbeat = self.heartbeat(a.run, a.epoch);
        self.execute(
            Execution {
                run: a.run,
                epoch: a.epoch,
                quota: a.quota,
                plan: &a.plan,
                input: a.input,
                mode: Mode::Live,
                case: a.case,
                budget: a.budget,
                agent: a.agent,
                identity: a.identity,
                subjects: a.subjects,
                refusal: None,
                withheld_subject: None,
                successors: Vec::new(),
                started: BTreeSet::new(),
                finished: BTreeSet::new(),
                succeeded: BTreeSet::new(),
                recorded_groups: BTreeMap::new(),
            },
            &mut cursor,
        )
        .await
    }

    /// Admit and execute, which is what every blocking entry point does.
    ///
    /// The run id is the caller's rather than minted here, for batches: an
    /// item's run id is written to the batch store *before* the run starts, so
    /// that a crash leaves a reservation pointing at a journal that can be
    /// replayed rather than an item that must be guessed about.
    pub(crate) async fn admit_plan_as(
        &self,
        run: RunId,
        plan: PlanIR,
        input: Tainted<Value>,
        terms: RunTerms,
        entry: Entry,
    ) -> Result<RunOutcome, RuntimeError> {
        let admitted = self.admit_only(run, plan, input, terms, entry).await?;
        self.execute_admitted(admitted).await
    }

    /// Why an open run may not cross its history frontier on this plane, if it
    /// may not.
    ///
    /// Two facts recorded at admission are compared with what this plane holds:
    /// the policy bundle (who may authorize an effect) and, for a declarative
    /// agent, the declaration (what the agent *is*). A resume under either one
    /// changed would continue one run's journal under another's rules. The
    /// answer is a refusal to journal rather than an error to raise; the caller
    /// decides where it goes.
    fn resume_refusal(&self, records: &[Record]) -> Result<Option<RuntimeError>, RuntimeError> {
        if let Some(refusal) = self.policy_bundle_refusal(records)? {
            return Ok(Some(refusal));
        }
        #[cfg(feature = "manifest")]
        if let Some(refusal) = self.declaration_refusal(records)? {
            return Ok(Some(refusal));
        }
        Ok(None)
    }

    /// [`RuntimeError::NoProvider`] when a capability any of the run's plans
    /// names resolves to nothing on this plane.
    ///
    /// Every plan the run froze is checked, not only the one in force: an
    /// unwind resolves the steps that ran, and those may belong to a plan a
    /// replan replaced.
    fn refuse_undrivable<'p>(
        &self,
        plans: impl IntoIterator<Item = &'p PlanIR>,
    ) -> Result<(), RuntimeError> {
        for node in plans.into_iter().flat_map(|p| &p.nodes) {
            self.resolve(&node.capability.0)?;
        }
        Ok(())
    }

    /// Name the run where it is watched from outside its journal: on its case,
    /// and to every outbox destination.
    ///
    /// Only after the admission's append, and idempotent — an existing case
    /// row and an existing delivery cursor are kept — so every writing resume
    /// repeats it.
    async fn register(
        &self,
        run: RunId,
        case: Option<crate::core::CaseId>,
    ) -> Result<(), crate::core::StoreError> {
        if let (Some(case), Some(cases)) = (case, self.cases.as_ref()) {
            cases.attach_run(case, run).await?;
        }
        #[cfg(feature = "push")]
        if let Some(outbox) = &self.outbox {
            outbox.open(run).await?;
        }
        Ok(())
    }

    /// [`RuntimeError::NoCaseStore`] when the run is bound to a case and this
    /// plane has no case store.
    ///
    /// Everything a resume writes belongs to the case, and without the store
    /// it would land under the run alone, where erasing the case misses it.
    /// About this plane rather than the run, so another plane may resume it.
    fn refuse_caseless(&self, run: RunId, records: &[Record]) -> Result<(), RuntimeError> {
        match recorded_case_id(records) {
            Some(case) if self.cases.is_none() => Err(RuntimeError::NoCaseStore {
                run: run.to_string(),
                case: case.to_string(),
            }),
            _ => Ok(()),
        }
    }

    /// Journal a resume refusal as the run's quarantine, naming what moved.
    async fn quarantine_refused(
        &self,
        run: RunId,
        records: &[Record],
        lease: &crate::journal::Lease,
        refusal: &RuntimeError,
    ) -> Result<RunOutcome, RuntimeError> {
        self.conclude(
            run,
            lease.epoch,
            RunStatus::Quarantined(refusal.to_string()),
            None,
            true,
            recorded_case_id(records),
            Consumed::default(),
            Spend::ZERO,
            &QuotaPass::disabled(),
        )
        .await
    }

    /// The bundle half of [`resume_refusal`](Self::resume_refusal).
    ///
    /// Resume can dispatch new effects after it reaches the end of history.
    /// They must be judged by the same complete bundle recorded at admission,
    /// or one run would claim one policy while later effects were authorized
    /// by another.
    fn policy_bundle_refusal(
        &self,
        records: &[Record],
    ) -> Result<Option<RuntimeError>, RuntimeError> {
        let recorded = records
            .iter()
            .find_map(|record| match record.kind() {
                RecordKind::RunAdmitted { policy_bundle, .. } => {
                    Some(policy_bundle.as_deref().cloned())
                }
                _ => None,
            })
            .ok_or_else(|| {
                RuntimeError::PlanContract("journal has no RunAdmitted record".into())
            })?;
        let configured = self.policy.as_ref().map(|policy| policy.bundle());
        if recorded != configured {
            return Ok(Some(RuntimeError::PolicyBundleChanged {
                recorded: recorded.as_ref().map(PolicyBundleIdentity::digest),
                configured: configured.as_ref().map(PolicyBundleIdentity::digest),
            }));
        }
        Ok(None)
    }

    /// The declaration half of [`resume_refusal`](Self::resume_refusal).
    ///
    /// For a declarative agent the manifest is the whole behaviour, and a resume
    /// under an edited one runs a different program over the first one's
    /// journal — which replay would eventually catch as a key mismatch, several
    /// effects in and without being able to say what changed. The digest is
    /// already on the record at admission, so refusing here costs a comparison
    /// and turns a late diagnosis into a named remedy.
    ///
    /// **Silent in two cases, and deliberately.** A run admitted with no
    /// declaration is a coded skill, whose behaviour is the embedder's binary:
    /// this crate cannot identify that and will not pretend to. And a plane that
    /// holds no manifest under the recorded name cannot run the agent
    /// declaratively at all, so the refusal it needs is the one plan resolution
    /// already gives.
    #[cfg(feature = "manifest")]
    fn declaration_refusal(
        &self,
        records: &[Record],
    ) -> Result<Option<RuntimeError>, RuntimeError> {
        let Some(recorded) = records.iter().find_map(|record| match record.kind() {
            RecordKind::RunAdmitted { governed_by, .. } => governed_by.as_deref().cloned(),
            _ => None,
        }) else {
            return Ok(None);
        };
        let Some(current) = self
            .governed_by
            .values()
            .find(|m| m.metadata.name == recorded.name)
        else {
            return Ok(None);
        };
        let configured = current
            .digest()
            .map_err(|e| RuntimeError::PlanContract(e.to_string()))?;
        if configured != recorded.digest {
            return Ok(Some(RuntimeError::DeclarationChanged {
                agent: recorded.name,
                recorded: recorded.digest,
                configured,
            }));
        }
        Ok(None)
    }

    /// A plan left sealed is erased only where a key ring could have opened
    /// it.
    ///
    /// A wired ring opens every payload whose key still exists and fails the
    /// read when it cannot be reached, so a payload still sealed behind one was
    /// erased. Behind no ring it says nothing about the key at all: the data
    /// is intact, and telling a reader it is gone sends them to the wrong
    /// remedy.
    fn sealed_or_erased(&self, error: RuntimeError) -> RuntimeError {
        match error {
            RuntimeError::PayloadsErased { run } if !self.holds_key_ring() => {
                RuntimeError::PayloadsSealed { run }
            }
            other => other,
        }
    }

    /// Whether this plane was handed a key ring to open sealed payloads with.
    #[cfg_attr(not(feature = "keyring"), allow(clippy::unused_self))]
    const fn holds_key_ring(&self) -> bool {
        #[cfg(feature = "keyring")]
        {
            self.keyring.is_some()
        }
        #[cfg(not(feature = "keyring"))]
        {
            false
        }
    }

    /// Re-execute a recorded run from its journal.
    ///
    /// * [`Mode::Strict`] verifies determinism: every effect must match, and the
    ///   run must not want any effect the journal lacks.
    /// * [`Mode::Resume`] recovers a crashed run: history is replayed, then
    ///   execution continues live from wherever the record ends.
    ///
    /// Either way no external effect is performed for anything already in the
    /// journal. That is the whole point — a resumed run does not re-issue the
    /// invoice it already issued.
    pub async fn replay(&self, run: RunId, mode: Mode) -> Result<RunOutcome, RuntimeError> {
        // ── Ownership before observation ───────────────────────────────────
        //
        // Resume writes, so it takes the lease *before* it reads. The old
        // order — snapshot the records, then acquire — left a window in which
        // a live owner could append past the snapshot; the resume then
        // replayed a prefix of the true history and continued live from a
        // frontier that was not the frontier, re-deriving keys the owner had
        // already written. Claiming first means the snapshot below is taken
        // under this instance's own fence. Strict verifies and never writes,
        // so it needs no lease — and must not take one, or every regression
        // check would fence a run somebody may be legitimately running.
        let lease = if mode == Mode::Resume {
            Some(
                self.store
                    .acquire(run, &self.owner, self.lease_ttl)
                    .await
                    .map_err(RuntimeError::from_store)?,
            )
        } else {
            None
        };

        self.replay_releasing(run, mode, lease, Claim::Standing)
            .await
    }

    /// Replay a recorded run strictly and say what it found.
    ///
    /// [`replay`](Self::replay) with [`Mode::Strict`], answered as a
    /// [`Verdict`](super::Verdict) rather than a status: *verified* when every
    /// recorded effect was asked for again and the run reached the ending it
    /// recorded, whatever that ending was; *diverged* at the first effect this
    /// build asked for differently; *cannot replay* when the run cannot be
    /// re-derived here, for a reason that is not the declaration. Both
    /// revisions are named on every answer — the one the run was admitted
    /// under and the one this plane holds by that name.
    ///
    /// Writes nothing, takes no lease and dispatches nothing, as a strict
    /// replay never does. It is the question an author asks of an edited
    /// manifest: replayed under the edit, this run's history either reaches
    /// nothing it changed or names the first effect it did.
    ///
    /// # Errors
    ///
    /// If the run does not exist or its journal does not verify, or on a store
    /// failure — never for a divergence or a reason the verdict names.
    pub async fn verify(&self, run: RunId) -> Result<super::Verdict, RuntimeError> {
        use super::{CannotReplay, Finding};

        let records = self
            .store
            .read(run, 1)
            .await
            .map_err(RuntimeError::from_store)?;
        if records.is_empty() {
            return Err(RuntimeError::Store(crate::core::StoreError::NotFound(
                run.to_string(),
            )));
        }
        let recorded = records.iter().find_map(|r| match r.kind() {
            RecordKind::RunAdmitted { governed_by, .. } => governed_by.as_deref().cloned(),
            _ => None,
        });
        let candidate = self.candidate_revision(recorded.as_ref());
        let verdict = |finding| super::Verdict {
            run,
            recorded: recorded.clone(),
            candidate: candidate.clone(),
            finding,
        };

        // A property of the history rather than of how it ended, so it is
        // named whatever the run's state: every key moves under another rule.
        if let Err(RuntimeError::CanonicalizationChanged {
            recorded,
            implemented,
        }) = ensure_replayable_canon(&records)
        {
            return Ok(verdict(Finding::CannotReplay(
                CannotReplay::CanonicalizationChanged {
                    recorded,
                    implemented,
                },
            )));
        }
        let Some(ending) = recorded_ending(&records) else {
            return Ok(verdict(Finding::CannotReplay(CannotReplay::NotConcluded)));
        };
        if ended_by_an_act(&ending) {
            return Ok(verdict(Finding::CannotReplay(CannotReplay::EndedByAnAct {
                outcome: ending,
            })));
        }

        let mut dispatched = false;
        let mut divergence = None;
        let replayed = self
            .replay_under(
                run,
                Mode::Strict,
                None,
                Claim::Standing,
                &mut dispatched,
                &mut divergence,
            )
            .await;
        let finding = match (replayed, divergence) {
            (Ok(_), Some(d)) => Finding::Diverged(d),
            (Ok(outcome), None) if outcome.status.as_str() == ending => {
                Finding::Verified { outcome: ending }
            }
            (Ok(outcome), None) => Finding::OutcomeDiffers {
                recorded: ending,
                replayed: outcome.status.as_str().to_owned(),
            },
            (Err(RuntimeError::PayloadsErased { .. }), _) => {
                Finding::CannotReplay(CannotReplay::Erased)
            }
            (Err(RuntimeError::PayloadsSealed { .. }), _) => {
                Finding::CannotReplay(CannotReplay::KeyAbsent)
            }
            (Err(RuntimeError::NoProvider { target, .. }), _) => {
                Finding::CannotReplay(CannotReplay::EntryPointRemoved { capability: target })
            }
            (Err(other), _) => return Err(other),
        };
        Ok(verdict(finding))
    }

    /// The declaration this plane holds under the recorded agent's name.
    #[cfg(feature = "manifest")]
    fn candidate_revision(
        &self,
        recorded: Option<&crate::journal::AgentIdentity>,
    ) -> Option<crate::journal::AgentIdentity> {
        let name = &recorded?.name;
        let held = self
            .governed_by
            .values()
            .find(|m| &m.metadata.name == name)?;
        self.identity_of(held)
    }

    /// Without the manifest there are no declarations to name.
    #[cfg(not(feature = "manifest"))]
    #[allow(clippy::unused_self)]
    const fn candidate_revision(
        &self,
        _recorded: Option<&crate::journal::AgentIdentity>,
    ) -> Option<crate::journal::AgentIdentity> {
        None
    }

    /// Resume a run under a lease the caller already holds.
    ///
    /// The wake path's handover: a timer or event delivery records the wake
    /// under its own lease and then resumes the run. Releasing that lease and
    /// letting the resume acquire a fresh one opened a window — a crash
    /// between the two left a *released* lease over a run whose timer was
    /// disarmed and whose subscription was retired, which no queue in the
    /// system names: the abandonment sweep looks only for leases that expired
    /// while still holding an owner. Handing the lease over closes the window;
    /// the run is owned continuously from wake to conclusion, and a crash
    /// anywhere in between leaves an expired *owned* lease the sweep drains.
    ///
    /// A resume that fails does the same thing a crash does, and for the same
    /// reason: the recorded wake took the run off the waiting listing, so the
    /// lease is the only thing left that names it.
    pub(crate) async fn resume_holding(
        &self,
        run: RunId,
        lease: crate::journal::Lease,
    ) -> Result<RunOutcome, RuntimeError> {
        self.replay_releasing(run, Mode::Resume, Some(lease), Claim::Unlisted)
            .await
    }

    /// Recover an owner-abandoned run without turning settlement repair into
    /// an operator-requested retry of a recorded conclusion.
    ///
    /// A recovery that fails for a reason no retry changes — the journal, not
    /// the moment, is what refuses — quarantines the run under the lease the
    /// failed pass kept, naming the reason. Left alone it would lapse owned
    /// and be recovered, and refused, every lease period for ever; a
    /// quarantine is listed, counted, and answered by a person.
    pub(crate) async fn recover_abandoned_run(
        &self,
        run: RunId,
    ) -> Result<RunOutcome, RuntimeError> {
        let lease = self
            .store
            .acquire(run, &self.owner, self.lease_ttl)
            .await
            .map_err(RuntimeError::from_store)?;
        match self
            .replay_releasing(run, Mode::Resume, Some(lease.clone()), Claim::Recovering)
            .await
        {
            Err(error) if recurs_on_every_resume(&error) => {
                let records = self
                    .store
                    .read(run, 1)
                    .await
                    .map_err(RuntimeError::from_store)?;
                let refusal = RuntimeError::PlanContract(format!(
                    "recovery refused, and would be refused the same way on every attempt: \
                     {error}"
                ));
                self.quarantine_refused(run, &records, &lease, &refusal)
                    .await
            }
            other => other,
        }
    }

    async fn replay_releasing(
        &self,
        run: RunId,
        mode: Mode,
        lease: Option<crate::journal::Lease>,
        claim: Claim,
    ) -> Result<RunOutcome, RuntimeError> {
        let mut dispatched = false;
        let outcome = self
            .replay_under(run, mode, lease.as_ref(), claim, &mut dispatched, &mut None)
            .await;

        // Idempotent: a resume that reached a conclusion already handed its
        // lease back in `conclude`, and re-releasing the same epoch changes
        // nothing. Released on success, and on a failure only where the run
        // is still listed somewhere else: the caller claimed a run whose
        // journal already says where it stands, and the refusal came before
        // anything past the frontier was written. Every other failure keeps
        // the lease so it lapses owned, which is what puts the run on the
        // abandonment listing the recovery sweep drains. A wake or a delivery
        // has already recorded the awaited result, so the run is off the
        // waiting listing; a recovery holds a run nothing else lists; and a
        // pass that failed mid-flight wrote records past a conclusion that no
        // longer describes it. Releasing any of those strands the run with no
        // driver and on no listing.
        let release = match &outcome {
            Ok(_) => true,
            // Settlement is retried by recovery, which finds the run through
            // this lease.
            Err(RuntimeError::QuotaSettlementPending { .. }) => false,
            Err(_) => claim == Claim::Standing && !dispatched,
        };
        if release
            && let Some(lease) = &lease
            && let Err(e) = self.store.release_lease(run, lease.epoch).await
        {
            tracing::debug!(
                %run,
                error = %e,
                "could not hand back the resume lease; it will expire on its own"
            );
        }
        outcome
    }

    #[allow(clippy::too_many_lines)]
    async fn replay_under(
        &self,
        run: RunId,
        mode: Mode,
        lease: Option<&crate::journal::Lease>,
        claim: Claim,
        dispatched: &mut bool,
        divergence: &mut Option<crate::journal::Divergence>,
    ) -> Result<RunOutcome, RuntimeError> {
        let records = self
            .store
            .read(run, 1)
            .await
            .map_err(RuntimeError::from_store)?;
        if records.is_empty() {
            return Err(RuntimeError::Store(crate::core::StoreError::NotFound(
                run.to_string(),
            )));
        }

        // Never trust a journal that does not verify. A tampered or truncated
        // history would let replay "confirm" something that never happened.
        //
        // Per-record hashes are already checked on read, so a single altered
        // record fails before we get here; this catches the structural attacks
        // that survive individually-valid records — deletion, reordering, and
        // splicing history from another run.
        Record::verify_chain(&records, Digest::ZERO).map_err(RuntimeError::from_store)?;

        ensure_replayable_canon(&records)?;

        if mode == Mode::Resume
            && let Some(outcome) = self
                .recover_quota_before_resume(
                    run,
                    &records,
                    lease.expect("resume holds a lease"),
                    claim == Claim::Recovering,
                )
                .await?
        {
            return Ok(outcome);
        }

        if mode == Mode::Resume
            && let Some(outcome) = self
                .closed_resume_outcome(run, &records, lease.expect("resume holds a lease"))
                .await?
        {
            return Ok(outcome);
        }

        // Placed *before* the compensation guard below on purpose: a run that
        // quarantined partway through an unwind is exactly the one an operator
        // has no other way to close, and it must not be the one this refuses to
        // close.
        if mode == Mode::Resume
            && let Some(outcome) = self
                .abandon_if_decided(run, &records, lease.expect("resume holds a lease"))
                .await?
        {
            return Ok(outcome);
        }

        if mode == Mode::Resume {
            refuse_resume_over_undone_work(run, &records)?;
        }

        // **Read after the conclusions above, and that ordering is the rule.**
        // A plan is what a run needs to *execute*; concluding one needs no
        // plan, and a cancellation and an abandonment are recorded in the
        // clear. Reading here rather than at the top of this function is what
        // leaves an operator a verb when the plan can no longer be read at all
        // — which is an ordinary state, because erasing a case's key erases
        // the plan of every run in it.
        let input = records.iter().find_map(recorded_input).ok_or_else(|| {
            RuntimeError::PlanContract("journal has no RunAdmitted record".into())
        })?;
        let (plan, successors) =
            frozen_plans(run, &records).map_err(|e| self.sealed_or_erased(e))?;

        // Only a plane that can drive the run judges it. A plane holding no
        // provider for the run's steps — an operator's terminal, a fleet
        // member serving other agents — answers `NoProvider` before comparing
        // its policy or declarations with the run's: a mismatch there says
        // nothing about the run, and quarantining it would stop a run this
        // plane could never have continued.
        if mode == Mode::Resume {
            self.refuse_undrivable(std::iter::once(&plan).chain(&successors))?;
            self.refuse_caseless(run, &records)?;
        }

        // Resume can dispatch new effects past the end of history, so it is
        // held to the bundle and the declaration recorded at admission. Strict
        // replay performs no effects and remains usable as an offline verifier
        // without loading the historical engine.
        //
        // A refusal here is journaled as a quarantine rather than returned. The
        // callers that reach this unattended — a wake, a delivery, the recovery
        // sweep — have already recorded the result that took the run off its
        // waiting listing, and an error there reaches nobody: the run would
        // sit on no listing, or be retried every tick into the same refusal.
        // A quarantine is the state that already means *the runtime cannot go
        // on and a person must decide*, it is listed and counted, and both of
        // its answers work here — reopen on a plane holding the recorded
        // revision, or abandon.
        if mode == Mode::Resume
            && let Some(refusal) = self.resume_refusal(&records)?
        {
            let lease = lease.expect("resume holds a lease");
            return self
                .quarantine_refused(run, &records, lease, &refusal)
                .await;
        }

        // A resume executes the run, so it registers it first: what it adds is
        // whatever an admission that failed or died partway never wrote.
        if mode == Mode::Resume {
            self.register(run, recorded_case_id(&records))
                .await
                .map_err(RuntimeError::from_store)?;
        }

        *dispatched = true;
        // The agent recorded at admission, so a replay is bounded by the
        // ceilings the run actually had — and dispatched no wider than the
        // width its reservation was sized for.
        let budget = self.budget_for(&recorded_agent(&records));
        let quota = self
            .start_replay_quota_pass(run, mode, reserved_width(&budget, &plan))
            .await?;
        let through = self.marking_pass(run, &quota);
        let this = through.as_ref().unwrap_or(self);

        let case_ctx = self.recorded_case(&records);

        let mut cursor = ReplayCursor::from_records(&records);

        // Strict verification must not write, and it does not: it holds no
        // lease, and appends happen only past the end of history, which
        // Strict mode refuses to reach. Resume writes under the lease it
        // claimed before reading.
        let epoch = lease.map_or_else(|| records.last().map_or(1, |r| r.body.epoch), |l| l.epoch);

        // Strict verification never writes, so it holds no lease to renew.
        let _heartbeat = lease.map(|l| self.heartbeat(run, l.epoch));
        this.execute(
            Execution {
                run,
                epoch,
                quota,
                plan: &plan,
                input,
                mode,
                case: case_ctx,
                budget,
                agent: recorded_agent(&records),
                identity: recorded_chain(&records)?,
                subjects: recorded_subjects(run, &records),
                // A step-level refusal has no effect key, so it cannot ride the
                // replay cursor like an effect's does. It is lifted here from
                // the records `replay` has already read.
                refusal: recorded_step_refusal(&records),
                withheld_subject: standing_withholding(&records),
                successors,
                started: recorded_started_steps(&records),
                finished: recorded_finished_steps(&records),
                succeeded: recorded_succeeded_steps(&records),
                recorded_groups: recorded_groups(&records),
            },
            &mut cursor,
        )
        .await
        .inspect(|_| *divergence = cursor.divergence().cloned())
    }

    /// The trace root. Every span below is a child, so "what did this run do"
    /// is one query rather than a correlation exercise across logs.
    ///
    /// Instrumented rather than entered: an `Entered` guard held across an
    /// `.await` belongs to the thread, and with concurrent dispatch that
    /// reparents whatever runs next onto this span.
    async fn execute(
        &self,
        plan: Execution<'_>,
        cursor: &mut ReplayCursor,
    ) -> Result<RunOutcome, RuntimeError> {
        let span = tracing::info_span!(
            telemetry::RUN_SPAN,
            { telemetry::GEN_AI_OPERATION } = telemetry::GEN_AI_INVOKE_AGENT,
            { telemetry::RUN_ID } = tracing::field::display(plan.run),
            // Which declaration this run is executing. A plane serving several
            // agents cannot otherwise separate them, and separating them is
            // the first thing an operator does.
            { telemetry::GEN_AI_AGENT_NAME } = plan.agent.as_str(),
            { telemetry::MODE } = telemetry::mode_str(plan.mode),
            { telemetry::GEN_AI_CONVERSATION_ID } = plan
                .case
                .as_ref()
                .map(|c| super::ctx::CaseContext::id(c).to_string()),
            // Empty under the default policy, which is what `Omitted` means.
            // Recorded rather than declared so the attribute is absent rather
            // than blank — a collector cannot read *not disclosed* as *no
            // tenant* if there is no field at all.
            { telemetry::TENANT } = tracing::field::Empty,
            { telemetry::OUTCOME } = tracing::field::Empty,
            { telemetry::SEMCONV } = telemetry::SEMCONV_VERSION,
        );
        if !self.meter.tenant().is_empty() {
            span.record(telemetry::TENANT, self.meter.tenant());
        }
        self.execute_inner(plan, cursor).instrument(span).await
    }

    /// The driver loop: ready set, admit, dispatch, apply, repeat.
    ///
    /// Long by line count and deliberately not split further. Every *step* is
    /// already its own method — `admit_ready`, `dispatch`, `collect`, `apply`,
    /// `adopt_successor`, `stop`. What is left is the order they happen in, and
    /// that order is the algorithm. Breaking it up again would scatter one
    /// readable sequence across functions that exist only to satisfy a line
    /// count, which is the opposite of the thing the lint is protecting.
    #[allow(clippy::too_many_lines)]
    async fn execute_inner(
        &self,
        plan: Execution<'_>,
        cursor: &mut ReplayCursor,
    ) -> Result<RunOutcome, RuntimeError> {
        let Execution {
            run,
            epoch,
            quota,
            plan: ir,
            input,
            mode,
            case,
            budget,
            agent,
            identity,
            subjects,
            refusal: recorded_refusal,
            withheld_subject,
            successors,
            started,
            finished,
            succeeded,
            recorded_groups,
        } = plan;
        // Every value derived from what the run took in carries its subjects.
        let input = input.attributed(&subjects);
        let writing = !matches!(mode, Mode::Strict);
        let case_id = case.as_ref().map(super::ctx::CaseContext::id);
        let stamp = |a: Append| match case_id {
            Some(c) => a.case(c),
            None => a,
        };

        // The plan in force. Owned rather than borrowed, because a replan
        // replaces it and a reference into the version list could not
        // survive that. `recorded_successors` is empty on a live run and seeded
        // from the journal on a replay, so a successor is read back rather than
        // re-synthesised.
        let mut current: PlanIR = ir.clone();
        let mut replans: u32 = 0;
        // A withholding the recorded history left standing, if it did. Seeded
        // from the records for the same reason the step refusal is: it is a fact
        // about *this* run that a resume has to answer, and asking the journal
        // again at every boundary would be a read per ready set for a question
        // whose answer only this loop can change.
        let mut withheld: Option<String> = withheld_subject;
        let recorded_successors = successors;

        // One ledger for the run. A step never gets its own allowance to blow.
        let ledger = Arc::new(std::sync::Mutex::new(Ledger::new(budget)));

        // Steps already completed, and what they produced. Rebuilt from the
        // journal on replay so a resumed run knows where it got to.
        let mut done: BTreeSet<StepId> = BTreeSet::new();

        // The same steps as `done`, in the order they finished, **with the
        // capability that actually ran**. Unwinding needs both: a set has no
        // order to reverse, and after a replan the current plan may have
        // different work — or nothing at all — at a completed step's id.
        // Resolving the compensation from the live plan then undoes something
        // that never ran, which is a refund for a charge nobody made.
        let mut completed: Vec<(StepId, Capability)> = Vec::new();
        // The node each completed step ran as. A successor may carry a
        // completed step over only as this exact node: `done` is by id, so a
        // redeclared node would count as done on the strength of other work.
        let mut ran: BTreeMap<StepId, PlanNode> = BTreeMap::new();
        let mut outputs: BTreeMap<StepId, Tainted<Value>> = BTreeMap::new();

        // ── Ready-set scheduling ───────────────────────────────────────────
        //
        // Dispatch order is a deterministic total order (ascending step id), so
        // replay reproduces it exactly. A plan with parallelism that
        // dispatched in completion order would replay differently every time.
        // The new work of a ready set whose recorded successes replay first.
        let mut deferred: Option<Vec<StepId>> = None;
        loop {
            let mut ready = current.ready(&done);
            if let Some(rest) = deferred.take() {
                let held: Vec<StepId> =
                    ready.iter().copied().filter(|s| rest.contains(s)).collect();
                if !held.is_empty() {
                    ready = held;
                }
            }
            // A resume's ready set can hold a step the record shows succeeding
            // beside one it does not — parallel work cut off mid-flight. The
            // recorded steps replay as a set of their own first, so the checks
            // below meet the frontier with their outputs already restored; the
            // rest is the next set, with nothing their replay made ready
            // joining it.
            if writing
                && ready.iter().any(|s| succeeded.contains(s))
                && ready.iter().any(|s| !succeeded.contains(s))
            {
                let (recorded, rest) = ready.into_iter().partition(|s| succeeded.contains(s));
                ready = recorded;
                deferred = Some(rest);
            }
            // ── The stop check, at a step boundary and nowhere else ────────
            //
            // Between boundaries an effect may be announced and not yet
            // recorded, and interrupting there manufactures the in-doubt case
            // the whole protocol exists to avoid. Checking here costs one
            // store read per ready set and buys a cancellation that can never
            // strand an effect.
            //
            // Skipped while replaying: a recorded run's history already
            // contains whatever stop it received, and re-reading the live
            // request would let a cancellation arriving *today* rewrite what a
            // run did last year.
            //
            // A resume asks only at its frontier — once the ready set holds a
            // step the record does not show succeeding. Before that, the
            // replayed steps have not yet refilled `completed` and `outputs`,
            // and an unwind from there would hand each compensation nothing
            // and walk the steps in id order rather than in reverse of the
            // order they finished.
            let at_frontier = ready.is_empty() || ready.iter().any(|s| !succeeded.contains(s));
            if writing
                && at_frontier
                && let Some(c) = self
                    .store
                    .cancellation(run)
                    .await
                    .map_err(RuntimeError::from_store)?
            {
                let status = RunStatus::Cancelled {
                    actor: c.actor.clone(),
                    reason: c.reason.clone(),
                };
                // Journaled *before* unwinding, so the reason the run stopped is
                // in the chain even if compensation then fails and quarantines
                // it. An operator reading a half-unwound run must be able to see
                // that somebody asked for this.
                self.store
                    .append(
                        epoch,
                        vec![stamp(Append::new(
                            run,
                            RecordKind::RunCancelled {
                                actor: c.actor,
                                reason: c.reason,
                            },
                        ))],
                    )
                    .await
                    .map_err(RuntimeError::from_store)?;
                // A step that paused with its group open holds work only that
                // step can take back: its reversals are built from the members'
                // outputs as the step runs. Re-run it once to abandon the group
                // — members read back, the pause aborts instead of waiting —
                // and only then unwind the steps before it.
                let abandon: Vec<StepId> = ready
                    .iter()
                    .copied()
                    .filter(|&s| {
                        recorded_groups.iter().any(|((step, phase, _), g)| {
                            *step == s && *phase == Phase::Forward && g.opened > g.settled
                        })
                    })
                    .collect();
                if !abandon.is_empty() {
                    let dispatched = self
                        .dispatch(
                            &abandon,
                            cursor,
                            Batch {
                                agent: &agent,
                                identity: identity.as_ref(),
                                subjects: &subjects,
                                run,
                                epoch,
                                ir: &current,
                                mode,
                                case: &case,
                                ledger: &ledger,
                                writing,
                                stamp: &stamp,
                                input: &input,
                                outputs: &outputs,
                                started: &started,
                                finished: &finished,
                                recorded_groups: &recorded_groups,
                                parallelism: 1,
                                abandoning: true,
                            },
                        )
                        .await;
                    collect(dispatched, &abandon, cursor)?;
                }
                return self
                    .stop(
                        Unwind {
                            agent: &agent,
                            identity: identity.as_ref(),
                            subjects: &subjects,
                            run,
                            epoch,
                            ir: &current,
                            mode,
                            case: case.clone(),
                            ledger: &ledger,
                            writing,
                            stamp: &stamp,
                        },
                        status,
                        &completed,
                        &outputs,
                        cursor,
                        case_id,
                        &quota,
                    )
                    .await;
            }

            // ── The withdrawal check, at the same boundary ─────────────────
            //
            // Beside the stop check and for its reasons. Unlike a cancellation
            // this is a **pause**: `stop` is reached with a status
            // `maybe_unwind` passes straight through, as exhaustion is.
            if writing && at_frontier {
                let standing = self
                    .withdrawal_against(identity.as_ref())
                    .await
                    .map_err(RuntimeError::Store)?;
                match (standing, withheld.take()) {
                    // Lifted since the run was withheld: that decision is a
                    // fact about the run and goes on the record, beside the
                    // withholding it supersedes rather than instead of it.
                    // Without it a strict replay would stop at the old pause and
                    // report `withheld` about a run whose own later records show
                    // it finishing.
                    (None, Some(prior)) => {
                        self.store
                            .append(
                                epoch,
                                vec![stamp(Append::new(
                                    run,
                                    RecordKind::AuthorityRestored { subject: prior },
                                ))],
                            )
                            .await
                            .map_err(RuntimeError::from_store)?;
                    }
                    // Still withdrawn. The standing record already says so — no
                    // second one, for the reason a re-exhausted run writes no
                    // second refusal.
                    // The prior is dropped rather than restored: this pass
                    // returns, and the *records* are what a later resume reads
                    // its standing state from.
                    (Some(withdrawal), Some(_prior)) => {
                        return self
                            .withhold(
                                Unwind {
                                    agent: &agent,
                                    identity: identity.as_ref(),
                                    subjects: &subjects,
                                    run,
                                    epoch,
                                    ir: &current,
                                    mode,
                                    case: case.clone(),
                                    ledger: &ledger,
                                    writing,
                                    stamp: &stamp,
                                },
                                withdrawal,
                                false,
                                &completed,
                                &outputs,
                                cursor,
                                case_id,
                                &quota,
                            )
                            .await;
                    }
                    (Some(withdrawal), None) => {
                        return self
                            .withhold(
                                Unwind {
                                    agent: &agent,
                                    identity: identity.as_ref(),
                                    subjects: &subjects,
                                    run,
                                    epoch,
                                    ir: &current,
                                    mode,
                                    case: case.clone(),
                                    ledger: &ledger,
                                    writing,
                                    stamp: &stamp,
                                },
                                withdrawal,
                                true,
                                &completed,
                                &outputs,
                                cursor,
                                case_id,
                                &quota,
                            )
                            .await;
                    }
                    (None, None) => {}
                }
            }
            if ready.is_empty() {
                break;
            }

            // Admission first, and deliberately not concurrent: which step a
            // ceiling refuses must be a property of the plan, not of which
            // future happened to poll first.
            let (admitted, refused) = self
                .admit_ready(
                    &ready,
                    &ledger,
                    mode,
                    recorded_refusal.as_ref(),
                    cursor,
                    Journalling {
                        run,
                        epoch,
                        writing,
                        stamp: &stamp,
                    },
                )
                .await?;

            let dispatched = self
                .dispatch(
                    &admitted,
                    cursor,
                    Batch {
                        agent: &agent,
                        identity: identity.as_ref(),
                        subjects: &subjects,
                        run,
                        epoch,
                        ir: &current,
                        mode,
                        case: &case,
                        ledger: &ledger,
                        writing,
                        stamp: &stamp,
                        input: &input,
                        outputs: &outputs,
                        started: &started,
                        finished: &finished,
                        recorded_groups: &recorded_groups,
                        parallelism: quota.parallelism(&budget),
                        abandoning: false,
                    },
                )
                .await;
            let outcomes = collect(dispatched, &ready, cursor)?;

            // ── Strict verification consumes everything, per step ──────────
            //
            // Divergence has two directions, and the ordered key comparison
            // only sees one of them. A build that asks for a *different*
            // effect fails at the mismatch; a build that asks for **fewer**
            // effects than the record sails past the remainder and would
            // report the step verified — a false confirmation about exactly
            // the history a verification pass exists to check. So a step that
            // finished with journaled effects still unread is the same
            // quarantine-grade finding as a key mismatch, named by the first
            // effect nothing requested.
            if mode == Mode::Strict {
                for &(step, ref status, _) in &outcomes {
                    // A step that stopped — suspended, failed, refused — ended
                    // where its history says it ended, and the stop itself is
                    // the verified finding. Only a step that claims to have
                    // *finished* owes a fully consumed slice.
                    if !matches!(status, RunStatus::Succeeded) {
                        continue;
                    }
                    if let Some(missing) = cursor.unconsumed_in(step, Phase::Forward) {
                        cursor.note_divergence(crate::journal::Divergence::unconsumed(
                            step,
                            Phase::Forward,
                            &missing,
                        ));
                        self.meter.count(metrics::DIVERGENCES, "");
                        tracing::error!(
                            target: telemetry::NONDETERMINISM,
                            %step, key = %missing.key, unconsumed = true,
                        );
                        return self
                            .conclude(
                                run,
                                epoch,
                                RunStatus::Quarantined(format!(
                                    "strict replay verified less than the run recorded: \
                                     step {step} finished with journaled effect {missing} \
                                     never requested — this build performs fewer effects than the \
                                     recorded one"
                                )),
                                None,
                                writing,
                                case_id,
                                Consumed::default(),
                                Spend::default(),
                                &quota,
                            )
                            .await;
                    }
                }
            }

            // A step that stops for any reason stops the run: whatever remains
            // either depended on it, or will be dispatched when it resumes.
            // Anything already done may need undoing first.
            let mut stopped = apply(
                &current,
                outcomes,
                &mut done,
                &mut completed,
                &mut ran,
                &mut outputs,
            )
            .or_else(|| refused.map(RunStatus::Exhausted));

            if let Some(RunStatus::Replanning(reason)) = &stopped {
                let recorded = recorded_successors.get(replans as usize);
                let journal = Journalling {
                    run,
                    epoch,
                    writing: writing && recorded.is_none(),
                    stamp: &stamp,
                };
                let cx = Replan {
                    run,
                    current: &current,
                    ran: &ran,
                    reason,
                    already_replanned: replans,
                    max_replans: budget.max_replans,
                    recorded,
                };
                match self
                    .adopt_successor(cx, journal, &outputs, &completed)
                    .await?
                {
                    Ok(next) => {
                        replans += 1;
                        current = next;
                        continue;
                    }
                    Err(refusal) => stopped = Some(refusal),
                }
            }

            if let Some(status) = stopped {
                return self
                    .stop(
                        Unwind {
                            agent: &agent,
                            identity: identity.as_ref(),
                            subjects: &subjects,
                            run,
                            epoch,
                            ir: &current,
                            mode,
                            case: case.clone(),
                            ledger: &ledger,
                            writing,
                            stamp: &stamp,
                        },
                        status,
                        &completed,
                        &outputs,
                        cursor,
                        case_id,
                        &quota,
                    )
                    .await;
            }
        }

        // ── Strict verification consumes everything, at the end ────────────
        //
        // The per-batch check above covers steps this build dispatched; this
        // covers the ones it never asked for at all — a step a changed plan no
        // longer reaches, a compensation slice nothing requested. Either way the
        // record holds work this build cannot account for, and "verified" must
        // not be the answer.
        if mode == Mode::Strict
            && let Some((step, phase, missing)) = cursor.first_unconsumed()
        {
            cursor.note_divergence(crate::journal::Divergence::unconsumed(
                step, phase, &missing,
            ));
            self.meter.count(metrics::DIVERGENCES, "");
            tracing::error!(
                target: telemetry::NONDETERMINISM,
                %step, key = %missing.key, unconsumed = true,
            );
            return self
                .conclude(
                    run,
                    epoch,
                    RunStatus::Quarantined(format!(
                        "strict replay verified less than the run recorded: journaled \
                         effect {missing} at step {step}, {phase:?} phase, was never \
                         requested — this build performs fewer effects than the recorded one"
                    )),
                    None,
                    writing,
                    case_id,
                    Consumed::default(),
                    Spend::default(),
                    &quota,
                )
                .await;
        }

        // Read into a value first. A `MutexGuard` built inline as an argument
        // lives until the end of the full expression — which here is *after*
        // the await — so the lock would be held across a suspension. That is
        // the same shape as the `Span::enter()` bug: a guard whose
        // scope is wider than it looks, and invisible until something else
        // needs the lock.
        let (consumed, live_spend) = {
            let l = ledger.lock().expect("budget mutex");
            (l.consumed(), l.live_spend())
        };
        self.conclude(
            run,
            epoch,
            completion(&current, &done),
            run_output(&current, &outputs),
            writing,
            case_id,
            consumed,
            live_spend,
            &quota,
        )
        .await
    }

    /// Read the clock into the ledger, when a wall-clock ceiling is declared.
    ///
    /// Separate so the guard's scope is two statements that cannot span the
    /// await between them, and so the condition is asked once rather than
    /// spelled at the caller.
    async fn observe_clock(
        cx: &mut StepCtx<'_>,
        ledger: &Arc<std::sync::Mutex<Ledger>>,
    ) -> Result<(), crate::core::StepError> {
        if !ledger.lock().expect("budget mutex").tracks_wallclock() {
            return Ok(());
        }
        let at = cx.now().await?;
        ledger.lock().expect("budget mutex").observe_clock(at);
        Ok(())
    }

    /// Run a ready set concurrently, at most `max_parallel_steps` at a time.
    ///
    /// The ready set is every node whose predecessors are done, so nothing in
    /// it depends on anything else in it — running them one at a time is a
    /// choice, and the wrong one when steps are waiting on models and networks.
    ///
    /// Each step takes its own slice of history, which is what makes this sound:
    /// a step touches only its own effects, so no shared mutable state is left
    /// between them, and the per-step replay cursor verifies each one's order
    /// independently of how the journal happened to interleave them.
    ///
    /// The width is bounded because it is not otherwise bounded by anything:
    /// a fan-out is as wide as its author wrote it, and every step in flight
    /// holds a connection, a provider's rate limit and one operation's worth
    /// of spend the metered ceilings have checked and not yet billed. Ordered
    /// rather than completion-ordered — `buffered`, not `buffer_unordered` —
    /// so the outcomes still apply in ready order and a plan's dispatch is a
    /// property of the plan rather than of which future finished first.
    async fn dispatch(
        &self,
        admitted: &[StepId],
        cursor: &mut ReplayCursor,
        batch: Batch<'_>,
    ) -> Vec<Dispatched> {
        use futures_util::StreamExt;

        let slices: Vec<(StepId, StepCursor)> = admitted
            .iter()
            .map(|&s| (s, cursor.take(s, Phase::Forward)))
            .collect();
        // Floored at one because a width of zero would poll nothing forever.
        // A zero ceiling is refused at parse and at build, so this is the
        // second half of a rule rather than the only half — and the failure it
        // guards against is a hang, which is the one shape a later reader
        // cannot diagnose from the outside.
        let width = batch.parallelism.max(1);

        futures_util::stream::iter(slices.into_iter().map(|(step, slice)| async move {
            let node = batch
                .ir
                .node(step)
                .ok_or_else(|| RuntimeError::PlanContract(format!("no node {step}")))?;
            let (status, out, slice) = self
                .run_step(
                    StepRun {
                        agent: batch.agent,
                        identity: batch.identity,
                        subjects: batch.subjects,
                        run: batch.run,
                        epoch: batch.epoch,
                        node,
                        phase: Phase::Forward,
                        mode: batch.mode,
                        case: batch.case.clone(),
                        ledger: batch.ledger,
                        writing: batch.writing,
                        stamp: batch.stamp,
                        already_started: batch.started.contains(&step),
                        already_finished: batch.finished.contains(&step),
                        recorded_groups: batch
                            .recorded_groups
                            .iter()
                            .filter(|((s, p, _), _)| *s == step && *p == Phase::Forward)
                            .map(|((_, _, name), n)| (name.clone(), *n))
                            .collect(),
                        abandoning: batch.abandoning,
                    },
                    batch.input,
                    batch.outputs,
                    slice,
                )
                .await?;
            Ok((step, status, out, slice))
        }))
        .buffered(width)
        .collect()
        .await
    }

    /// Take the successor a step asked for: check it, record it, announce it.
    ///
    /// The nested result separates two failures. The outer `RuntimeError` is the
    /// runtime itself failing — the journal would not accept the plan — and is
    /// never recoverable. The inner `RunStatus` is the *request* being refused,
    /// which is an ordinary outcome the run reports.
    async fn adopt_successor(
        &self,
        cx: Replan<'_>,
        journal: Journalling<'_>,
        outputs: &BTreeMap<StepId, Tainted<Value>>,
        completed: &[(StepId, Capability)],
    ) -> Result<Result<PlanIR, RunStatus>, RuntimeError> {
        // What each step that started and journaled an effect ran as, read
        // from the journal only when a successor is about to be checked — a
        // replay reads the successor back instead.
        let started = if cx.recorded.is_none() {
            let records = self
                .store
                .read(cx.run, 1)
                .await
                .map_err(RuntimeError::from_store)?;
            let effectful: BTreeSet<StepId> = records
                .iter()
                .filter(|r| r.body.phase.is_forward())
                .filter_map(|r| match r.kind() {
                    RecordKind::EffectStarted { .. } => r.body.step,
                    _ => None,
                })
                .collect();
            let mut started = started_skills(&records);
            started.retain(|step, _| effectful.contains(step));
            started
        } else {
            BTreeMap::new()
        };
        let next = match self.successor(cx, outputs, completed, &started).await {
            Ok(next) => next,
            Err(refusal) => return Ok(Err(refusal)),
        };
        if journal.writing {
            self.freeze(journal.run, journal.epoch, &next, journal.stamp)
                .await?;
        }
        announce_replan(
            &self.meter,
            journal.run,
            &next,
            next.reason.as_deref().unwrap_or(""),
        );
        Ok(Ok(next))
    }

    /// Record a plan version in the journal.
    ///
    /// A successor is frozen exactly as a first plan is, so replay reads it back
    /// rather than asking a planner that may since have changed its mind.
    async fn freeze(
        &self,
        run: RunId,
        epoch: u64,
        plan: &PlanIR,
        stamp: &(dyn Fn(Append) -> Append + Send + Sync),
    ) -> Result<(), RuntimeError> {
        self.store
            .append(
                epoch,
                vec![stamp(Append::new(
                    run,
                    RecordKind::PlanFrozen {
                        steps: plan.nodes.iter().map(|n| n.capability.0.clone()).collect(),
                        plan: serde_json::to_value(plan)?,
                    },
                ))],
            )
            .await
            .map_err(RuntimeError::from_store)?;
        Ok(())
    }

    /// Produce the successor plan a step asked for, or say why not.
    ///
    /// Three gates, and the first is not negotiable.
    ///
    /// **Provenance.** The frozen plan is an authorization graph compiled from
    /// trusted input only. A replan *changes that graph*, so once any
    /// untrusted value has reached working memory, anything shaping the new plan
    /// may be attacker-chosen — and choosing the authorization graph is the
    /// whole game. `plan-then-execute` is enforced here, structurally. A run
    /// that wants a different plan after reading untrusted input is describing
    /// exactly the attack.
    ///
    /// **Budget.** A run that replans without bound has stopped making progress
    /// and started thrashing.
    ///
    /// **On replay, the successor is read back, never re-synthesised.** A
    /// planner asked twice can answer differently — a changed router, a
    /// different model — and replay would then verify the run against a plan
    /// that never governed it. Same rule as the first plan, for the same
    /// reason.
    async fn successor(
        &self,
        cx: Replan<'_>,
        outputs: &BTreeMap<StepId, Tainted<Value>>,
        completed: &[(StepId, Capability)],
        started: &BTreeMap<StepId, String>,
    ) -> Result<PlanIR, RunStatus> {
        if let Some(source) = untrusted_in(outputs) {
            return Err(RunStatus::Failed(format!(
                "replanning refused: untrusted data from {source} is already in working memory, and the plan is an authorization graph — letting it change now would let that data choose what runs next ({})",
                cx.reason
            )));
        }

        let spent = cx.already_replanned;
        if let Some(max) = cx.max_replans
            && spent >= max
        {
            return Err(RunStatus::Exhausted(crate::core::BudgetExceeded::Replans {
                allowed: max,
            }));
        }

        // Replay: the successor is in the journal, at the position this replan
        // reached. Reading it back is what keeps a re-planned run replayable.
        if let Some(recorded) = cx.recorded {
            return Ok(recorded.clone());
        }

        let replanner = self.replanner.as_ref().ok_or_else(|| {
            RunStatus::Failed(format!(
                "a step asked to replan and this runtime has no planner — build it with `.replanner(..)` ({})",
                cx.reason
            ))
        })?;

        let next = replanner
            .replan(cx.current, cx.reason, completed)
            .await
            .map_err(|e| RunStatus::Failed(format!("replanning failed: {e}")))?;

        // A successor faces the same contract a first plan does. One that fails
        // validation stops the run rather than half-applying.
        crate::plan::validate(&next, &self.contract())
            .map_err(|e| RunStatus::Failed(format!("the successor plan is invalid: {e}")))?;

        // A completed step carries over only as the node it ran as, or not at
        // all. Other work at its id breaks replay — effect keys derive from the
        // step id — and has the saga undo something that never ran. The same
        // capability redeclared is refused too: `done` is by id, so a node with
        // new arguments, dependencies or flags would count as done on the
        // strength of work done before any of them held — a terminal verifier
        // satisfied without ever seeing what it verifies.
        for (step, node_ran) in cx.ran {
            let Some(node) = next.node(*step) else {
                continue;
            };
            if node.capability != node_ran.capability {
                return Err(RunStatus::Failed(format!(
                    "the successor plan reuses step {step} — which already ran \
                     as '{}' — for '{}'. Keep a completed step's node or leave \
                     the step out; effect keys are derived from the step id, so \
                     new work at a used id cannot be replayed",
                    node_ran.capability.0, node.capability.0
                )));
            }
            if node != node_ran {
                return Err(RunStatus::Failed(format!(
                    "the successor plan redeclares completed step {step} ('{}') \
                     with different arguments, dependencies or flags. A \
                     completed step counts as done by its id, so the new node \
                     would be satisfied by work done under the old one — carry \
                     it over unchanged, or give the new work a fresh id",
                    node.capability.0
                )));
            }
        }

        // A step that started, journaled an effect and did not complete holds
        // keys derived from its id just the same — it may have charged before
        // asking to replan — so its id may not be reused for work another
        // skill would do. One that journaled nothing, the step that asked for
        // a fallback before touching anything, leaves its id free.
        for (step, skill) in started {
            if cx.ran.contains_key(step) {
                continue;
            }
            let Some(node) = next.node(*step) else {
                continue;
            };
            let resolved = self
                .resolve(&node.capability.0)
                .map(|s| s.descriptor().name)
                .ok();
            if resolved.as_deref() != Some(skill.as_str()) {
                return Err(RunStatus::Failed(format!(
                    "the successor plan reuses step {step} — which already \
                     started as '{skill}' and journaled effects — for '{}'. Keep the step's \
                     capability or leave the step out; effect keys are derived \
                     from the step id, and the unwind undoes a started step as \
                     the skill that ran",
                    node.capability.0
                )));
            }
        }

        if next.derived_from != Some(cx.current.digest()) {
            return Err(RunStatus::Failed(
                "the successor plan does not name its predecessor — use `PlanIR::succeed_with`, or the audit trail has a hole where the lineage should be"
                    .into(),
            ));
        }

        // The third leg of the lineage `succeed_with` sets. A successor with
        // no reason would freeze into the journal as a plan that replaced
        // another with nothing on the record saying why — the half of an
        // incident (*what changed the run's mind*) that versioned replanning
        // exists to keep.
        if next.reason.as_deref().is_none_or(str::is_empty) {
            return Err(RunStatus::Failed(
                "the successor plan carries no reason — use `PlanIR::succeed_with`, or the \
                 journal freezes a plan that replaced another with nothing saying why"
                    .into(),
            ));
        }

        Ok(next)
    }

    /// Decide which of a ready set may start, in ready order.
    ///
    /// Three regimes, one per mode, and the middle one is the subtle case:
    ///
    /// * **Strict** consumes recorded verdicts and recomputes none. A run
    ///   replayed under a larger budget stopped where it stopped; recomputing
    ///   made a step-limited run replay as *succeeded* — a false audit result.
    /// * **Resume** takes each verdict from wherever the truth lives. A step
    ///   with unconsumed history was admitted by the run that recorded it,
    ///   and the history *is* the verdict. A step at the frontier is about to
    ///   run **live**, and every live step is metered — keying this on "is
    ///   the mode a replay" instead of "will this step dispatch live" let a
    ///   resumed run cross `max_steps` unmetered for as long as it kept
    ///   running. A *recorded refusal* is re-evaluated against the ledger now
    ///   in force: exhaustion is a pause, and raising the ceiling and
    ///   resuming is how it un-pauses.
    /// * **Live** asks the ledger, which is the ordinary case.
    async fn admit_ready(
        &self,
        ready: &[StepId],
        ledger: &Arc<std::sync::Mutex<Ledger>>,
        mode: Mode,
        recorded: Option<&(StepId, String, String)>,
        cursor: &ReplayCursor,
        journal: Journalling<'_>,
    ) -> Result<(Vec<StepId>, Option<crate::core::BudgetExceeded>), RuntimeError> {
        let mut admitted = Vec::new();

        for &step in ready {
            // ── A recorded step refusal at this step ───────────────────────
            if let Some((at, limit, used)) = recorded
                && *at == step
            {
                if mode == Mode::Strict {
                    // Verbatim: the recorded run stopped here, and a
                    // verification pass reaches the same conclusion without
                    // consulting today's ledger.
                    return Ok((
                        admitted,
                        Some(crate::core::BudgetExceeded::Recorded {
                            limit: limit.clone(),
                            used: used.clone(),
                        }),
                    ));
                }
                // Resume: the replayed prefix has already billed the journaled
                // historical usage into this ledger, so the question is "does
                // the budget now in force admit one more step over what the
                // run already spent". Still no → the run concludes exhausted
                // again, and the standing refusal already says so — no second
                // record. Yes → the re-admission is its own record, beside
                // the refusal it supersedes, so a strict replay of this
                // history reads refusal-then-continuation as a decision
                // somebody made rather than as divergence.
                if let Err(exceeded) = ledger
                    .lock()
                    .expect("budget mutex")
                    .admit_step(admitted.len())
                {
                    return Ok((admitted, Some(exceeded)));
                }
                if journal.writing {
                    self.store
                        .append(
                            journal.epoch,
                            vec![(journal.stamp)(
                                Append::new(
                                    journal.run,
                                    RecordKind::BudgetReadmitted {
                                        limit: limit.clone(),
                                    },
                                )
                                .step(step),
                            )],
                        )
                        .await
                        .map_err(RuntimeError::from_store)?;
                }
                admitted.push(step);
                continue;
            }

            let verdict = match mode {
                Mode::Strict => Ok(()),
                Mode::Resume if !cursor.exhausted(step, Phase::Forward) => Ok(()),
                Mode::Live | Mode::Resume => ledger
                    .lock()
                    .expect("budget mutex")
                    .admit_step(admitted.len()),
            };

            let Err(exceeded) = verdict else {
                admitted.push(step);
                continue;
            };

            if journal.writing {
                // The refusal goes in the journal under the step it refused, so
                // replay reads the verdict rather than recomputing it.
                let used = format!("{:?}", ledger.lock().expect("budget mutex").consumed());
                self.store
                    .append(
                        journal.epoch,
                        vec![(journal.stamp)(
                            Append::new(
                                journal.run,
                                RecordKind::BudgetRefused {
                                    limit: exceeded.to_string(),
                                    used,
                                },
                            )
                            .step(step),
                        )],
                    )
                    .await
                    .map_err(RuntimeError::from_store)?;
            }
            return Ok((admitted, Some(exceeded)));
        }

        Ok((admitted, None))
    }

    /// End a run that stopped early: undo what warrants undoing, then seal.
    ///
    /// Both places a run can stop short go through here, so the unwind can never
    /// be attached to one of them and forgotten on the other.
    #[allow(clippy::too_many_arguments)]
    async fn stop(
        &self,
        cx: Unwind<'_>,
        status: RunStatus,
        completed: &[(StepId, Capability)],
        outputs: &BTreeMap<StepId, Tainted<Value>>,
        cursor: &mut ReplayCursor,
        case_id: Option<crate::core::CaseId>,
        quota: &QuotaPass,
    ) -> Result<RunOutcome, RuntimeError> {
        let (run, epoch, writing, ir) = (cx.run, cx.epoch, cx.writing, cx.ir);
        let output = run_output(ir, outputs);
        // Cloned before `maybe_unwind` consumes `cx`; read *after* it, because an
        // item's cost is what the whole attempt consumed, compensation included.
        let ledger = cx.ledger.clone();
        let unwound = self
            .maybe_unwind(cx, status, completed, outputs, cursor)
            .await?;
        // A strict pass that stops early is still a verification, and its
        // verdict must not outrun what it consumed. The ready loop's
        // unconsumed-effects check runs only when the loop drains normally,
        // and every early conclusion — a failure, an unwind, a recorded
        // suspension — comes through here instead; without this check a build
        // that performs fewer effects than the record (a compensation that
        // shrank, a step that now suspends earlier) would return the recorded
        // status as "verified" over effects it never requested. Checked after
        // `maybe_unwind` because a strict pass consumes recorded compensation
        // slices there, and what remains after that is genuinely unclaimed.
        //
        // A run that already quarantined keeps its own reason. Divergence
        // leaves history unconsumed as a matter of course — the step stopped
        // where it disagreed — so reporting the leftovers here would replace
        // the precise finding ("expected this effect, recomputed that one")
        // with a vaguer restatement of its consequence, and an operator would
        // be told the build performs fewer effects when what it actually did
        // was perform a different one.
        if !writing
            && !matches!(unwound, RunStatus::Quarantined(_))
            && let Some((step, phase, missing)) = cursor.first_unconsumed()
        {
            cursor.note_divergence(crate::journal::Divergence::unconsumed(
                step, phase, &missing,
            ));
            self.meter.count(metrics::DIVERGENCES, "");
            tracing::error!(
                target: telemetry::NONDETERMINISM,
                %step, key = %missing.key, unconsumed = true,
            );
            return self
                .conclude(
                    run,
                    epoch,
                    RunStatus::Quarantined(format!(
                        "strict replay verified less than the run recorded: journaled \
                         effect {missing} at step {step}, {phase:?} phase, was never \
                         requested — this build performs fewer effects than the recorded one"
                    )),
                    None,
                    writing,
                    case_id,
                    Consumed::default(),
                    Spend::default(),
                    quota,
                )
                .await;
        }
        // Scoped before the await — see `execute_inner` on why an inline guard
        // outlives the call it is passed to.
        let (consumed, live_spend) = {
            let l = ledger.lock().expect("budget mutex");
            (l.consumed(), l.live_spend())
        };
        self.conclude(
            run, epoch, unwound, output, writing, case_id, consumed, live_spend, quota,
        )
        .await
    }

    /// Undo the completed steps, if the way the run stopped calls for it.
    ///
    /// # When a run does *not* unwind
    ///
    /// * **Quarantined.** The run holds an effect whose outcome is unknown, and
    ///   you cannot safely undo around one: compensating a payment that may
    ///   never have gone out creates a refund for money nobody took. Everything
    ///   stays exactly where it is until a person supplies the fact the journal
    ///   lacks — [`Runtime::reconcile_effect`](super::Runtime::reconcile_effect)
    ///   and [`decide_quarantine`](super::Runtime::decide_quarantine) — and
    ///   giving up
    ///   ([`Abandon`](crate::core::QuarantineDecision::Abandon)) still unwinds
    ///   nothing, because impatience is not evidence. This is the rule that
    ///   separates a saga that is honest about distributed systems from one that
    ///   tidies up and hopes.
    /// * **Suspended.** The run is healthy and waiting. Nothing has failed.
    ///
    /// A failure *after the pivot* also stops the unwind at the pivot: once the
    /// business has committed, reversing the decisions leading up to it would
    /// contradict something the outside world has already acted on.
    ///
    /// # Two rules every unwind takes
    ///
    /// **It must not unwind around an unknown outcome.** The same rule
    /// quarantine already enforces, applied at the unwind's own door. For a
    /// cancelled run the check is unconditional — cancellation gets no second
    /// pass, so an unresolved outcome stays unresolved forever. For a failed
    /// run it is conditional on the unwind list: an orphan under a failure is
    /// resolvable, because the announcement is journaled, the effect declared
    /// a `Recovery`, and resuming resolves it — but only while nothing was
    /// compensated, since compensation closes the run to resume. A failure
    /// that would compensate around doubt therefore quarantines instead; a
    /// failure with nothing to unwind stays a failure and keeps its resume.
    ///
    /// **It must undo the steps it interrupted.** Compensation walks
    /// *completed* steps, which covers the step that failed only if it never
    /// mutated. A stop arrives from outside while a step is typically
    /// suspended — holding effects it performed and never completing — and a
    /// failure in one concurrent sibling interrupts the others the same way:
    /// severity ordering can conclude the run while a suspended sibling holds
    /// a landed mutation. Unwinding only completed steps would leave exactly
    /// that work standing — a run that posted to a ledger and then suspended
    /// for approval would conclude with the posting still in the world and,
    /// once anything else was compensated, no resume left to finish it.
    async fn maybe_unwind(
        &self,
        cx: Unwind<'_>,
        status: RunStatus,
        completed: &[(StepId, Capability)],
        outputs: &BTreeMap<StepId, Tainted<Value>>,
        cursor: &mut ReplayCursor,
    ) -> Result<RunStatus, RuntimeError> {
        match status {
            // A cancelled run unwinds exactly as a failed one does. Stopping a
            // run that has already moved money and leaving the movement in
            // place is not stopping it — and the operator who asked is entitled
            // to assume "stop" means the world is put back, not that the
            // process merely exited.
            //
            // **Exhausted is deliberately not here.** Exhaustion is a pause,
            // not a fault: the run did what it was told, and what it was told
            // included a ceiling. Its mutations stand, because the operator's
            // two honest options both need them standing — raise the ceiling
            // and resume (which continues *over* the completed work), or
            // cancel (which unwinds through this same function under a status
            // that does). Unwinding on exhaustion would make the three ends of
            // an exhausted run contradict each other: the work reversed, the
            // run still resumable, and the resume reporting success over a
            // world where the work no longer stands.
            RunStatus::Failed(_) | RunStatus::Cancelled { .. } => {}
            other => return Ok(other),
        }

        let (list, evidence) = match self.gated_unwind_list(&cx, &status, completed).await? {
            Ok(scope) => scope,
            Err(quarantine) => return Ok(quarantine),
        };
        let UnwindEvidence {
            mutated,
            started: _,
            undone: already_undone,
            recorded_groups,
            failed: _,
        } = evidence;
        let completed = &list[..];

        for (step, capability) in completed.iter().rev().cloned() {
            // Resolved from what ran, not from the plan in force. After a replan
            // the two can differ, and undoing whatever now occupies that slot is
            // how a saga compensates work that never happened.
            let skill = self.resolve(&capability.0)?;
            let declared = skill.compensation();

            match declared {
                // The point of no return. Everything from here back stays.
                crate::core::Compensation::Pivot => break,
                crate::core::Compensation::Unnecessary => continue,
                crate::core::Compensation::Undeclared => {
                    if !mutated.contains(&step) {
                        // Nothing to undo, and the journal proves it.
                        continue;
                    }
                    return Ok(RunStatus::Quarantined(format!(
                        "step {step} ('{}') changed external state and declares no \
                         compensation, so the run cannot be safely unwound — \
                         declare Compensation on it, or resolve this by hand",
                        capability.0
                    )));
                }
                crate::core::Compensation::Compensatable => {}
            }

            let result = self
                .run_compensation(
                    &cx,
                    step,
                    skill.as_ref(),
                    outputs,
                    cursor,
                    recorded_groups
                        .iter()
                        .filter(|((s, p, _), _)| *s == step && *p == Phase::Compensating)
                        .map(|((_, _, name), n)| (name.clone(), *n))
                        .collect(),
                )
                .await;

            // A compensation may legitimately need to wait — a refund that needs
            // four eyes is still a refund. Suspension is not failure: the run is
            // healthy, its frame is durable, and it will finish unwinding when
            // the answer arrives. Reporting it as a failure would quarantine a
            // run doing exactly the right thing and tell the operator the
            // compensation had broken.
            if let Err(crate::core::SkillError::Step(crate::core::StepError::Suspended(reason))) =
                &result
            {
                return Ok(RunStatus::Suspended(reason.clone()));
            }

            let outcome = match &result {
                Ok(()) => "compensated".to_owned(),
                Err(e) => e.to_string(),
            };

            // Re-run but do not re-record. On resume the compensation executes
            // again with every effect served from the journal, which is what
            // keeps strict verification meaningful — but a second
            // `StepCompensated` would report one compensation as two.
            if result.is_ok() {
                tracing::info!(target: telemetry::COMPENSATED, run = %cx.run, %step);
                self.meter.count(metrics::COMPENSATIONS, "done");
            }
            if cx.writing && !already_undone.contains(&step) {
                self.store
                    .append(
                        cx.epoch,
                        vec![(cx.stamp)(
                            Append::new(
                                cx.run,
                                RecordKind::StepCompensated {
                                    compensation: declared,
                                    outcome: outcome.clone(),
                                },
                            )
                            .step(step)
                            .phase(Phase::Compensating),
                        )],
                    )
                    .await
                    .map_err(RuntimeError::from_store)?;
            }

            if let Err(fault) = &result {
                tracing::error!(
                    target: telemetry::COMPENSATION_FAILED,
                    run = %cx.run,
                    %step,
                    error_type = fault.class(),
                    reason_digest = %telemetry::reason_digest(&outcome),
                );
                self.meter.count(metrics::COMPENSATIONS, "failed");
                // Not a problem more compensation solves. Unwinding further
                // would undo steps *before* one that is now in an unknown
                // state, which is strictly worse than stopping and saying so.
                return Ok(RunStatus::Quarantined(format!(
                    "compensation failed for step {step} ('{}'): {outcome} — the run is \
                     partially unwound and needs an operator",
                    capability.0
                )));
            }
        }

        Ok(status)
    }

    /// Whether `run`'s journal holds a landed mutation no compensation undid.
    ///
    /// The attention roll-up's question about a failed run: `failed` alone may
    /// be cleared by a resume, but one standing on landed work leaves that
    /// work in the world until somebody finishes or unwinds it.
    pub(super) async fn holds_landed_work(&self, run: RunId) -> Result<bool, RuntimeError> {
        let evidence = self.unwind_evidence(run).await?;
        Ok(!evidence.mutated.is_subset(&evidence.undone))
    }

    /// What the journal knows about an unwind before it starts:
    /// `(steps that changed something, steps already compensated)`.
    ///
    /// Evidence, not bookkeeping. The journal already knows both, it knows the
    /// same thing on replay, and nothing has to be threaded through the executor
    /// to keep a parallel copy honest.
    ///
    /// **A mutating effect that provably did not happen does not mark its
    /// step.** The announcement alone is not the evidence: an effect whose
    /// terminal record classifies it `DidNotHappen` — a peer that refused
    /// before acting, a call that never left — changed nothing, and
    /// compensating it is a refund for money nobody took. Everything else
    /// counts, and the defaults lean that way: an announcement with no
    /// terminal record is an orphan and therefore in doubt, and each new
    /// attempt starts from doubt again, so a retry that lands after a refusal
    /// is still evidence the step touched the world.
    ///
    /// **Nor does a member of a group that settled `Aborted`.** That settlement
    /// is written only once every landed member was reversed, so the group's
    /// effects — members and reversals alike — left nothing standing, and
    /// counting them marked a cleanly aborted step as mutated: a quarantine for
    /// a step declaring no compensation, a second undo for one that did.
    ///
    /// What this does **not** establish is that a `DidNotHappen` classification
    /// is true — that is the driver's claim, and a driver that mislabels a
    /// landed call leaves a mutation nothing here will undo.
    async fn unwind_evidence(&self, run: RunId) -> Result<UnwindEvidence, RuntimeError> {
        let records = self
            .store
            .read(run, 1)
            .await
            .map_err(RuntimeError::from_store)?;

        // Per mutating forward effect: the step it belongs to, and whether the
        // record leaves it capable of having touched the world.
        let mut touching: BTreeMap<crate::core::EffectKey, (StepId, bool)> = BTreeMap::new();
        // The mutating effects of the group each step has open. A step holds
        // at most one open group, so the step is the key.
        let mut grouped: BTreeMap<StepId, Vec<crate::core::EffectKey>> = BTreeMap::new();
        let mut undone = BTreeSet::new();
        let mut failed = BTreeSet::new();
        for r in &records {
            let Some(step) = r.body.step else { continue };
            let key = r.effect_key();
            match r.kind() {
                RecordKind::StepFinished { outcome } if r.body.phase.is_forward() => {
                    if outcome == RunStatus::Succeeded.as_str() {
                        failed.remove(&step);
                    } else {
                        failed.insert(step);
                    }
                }
                RecordKind::EffectStarted { mutates: true, .. } if r.body.phase.is_forward() => {
                    if let Some(key) = key {
                        // A fresh attempt is undecided until its own terminal
                        // record says otherwise, so it supersedes whatever the
                        // previous attempt concluded.
                        touching.insert(key, (step, true));
                        if let Some(members) = grouped.get_mut(&step) {
                            members.push(key);
                        }
                    }
                }
                RecordKind::GroupOpened { .. } if r.body.phase.is_forward() => {
                    grouped.insert(step, Vec::new());
                }
                RecordKind::GroupSettled { outcome, .. } if r.body.phase.is_forward() => {
                    let members = grouped.remove(&step).unwrap_or_default();
                    if *outcome == crate::core::GroupOutcome::Aborted {
                        for member in members {
                            touching.remove(&member);
                        }
                    }
                }
                RecordKind::EffectFailed { disposition, .. }
                | RecordKind::EffectReconciled { disposition, .. } => {
                    if let Some(entry) = key.and_then(|k| touching.get_mut(&k)) {
                        entry.1 = *disposition != crate::core::Disposition::DidNotHappen;
                    }
                }
                RecordKind::StepCompensated { .. } => {
                    undone.insert(step);
                }
                _ => {}
            }
        }
        let mutated = touching
            .into_values()
            .filter_map(|(step, touched)| touched.then_some(step))
            .collect();
        Ok(UnwindEvidence {
            mutated,
            started: started_skills(&records),
            undone,
            recorded_groups: recorded_groups(&records),
            failed,
        })
    }

    /// The half of a step's frame that belongs to the **plane** rather than to
    /// the step.
    ///
    /// One place, for both a forward step and a compensation: a plane
    /// capability wired into one of the two and not the other is a control
    /// that applies going forward and not while unwinding.
    fn plane_frame(&self, step: StepFrame) -> super::ctx::Frame {
        let StepFrame {
            run,
            epoch,
            step,
            phase,
            mode,
            case,
            ledger,
            identity,
            subjects,
            agent,
            #[cfg(feature = "manifest")]
            manifest,
            recorded_groups,
        } = step;
        super::ctx::Frame {
            run,
            epoch,
            step,
            phase,
            mode,
            case,
            timers: self.timers.clone(),
            blobs: self.blobs.clone(),
            memories: self.memories.clone(),
            semantic: self.semantic.clone(),
            authorities: self.authorities.clone(),
            peers: self.peers.clone(),
            #[cfg(feature = "manifest")]
            tools: self.tools.clone(),
            journal_ceiling: self.journal_ceiling,
            #[cfg(feature = "manifest")]
            egress: self.egress.clone(),
            #[cfg(feature = "manifest")]
            checkers: self.checkers.clone(),
            streams: self.streams.clone(),
            #[cfg(feature = "manifest")]
            rates: self.rates.clone(),
            meter: self.meter.clone(),
            #[cfg(feature = "keyring")]
            keyring: self.keyring.clone(),
            tenant: self.tenant.clone(),
            ledger,
            policy: self.policy.clone(),
            identity,
            subjects,
            agent,
            plane: self.self_ref.clone(),
            #[cfg(feature = "manifest")]
            declaration: manifest.as_deref().and_then(|m| self.identity_of(m)),
            #[cfg(feature = "manifest")]
            manifest,
            signer: self.signer.clone(),
            recorded_groups,
        }
    }

    /// Run one step's `compensate`, in its own phase and cursor slice.
    ///
    /// Split out so the unwind reads as the policy it is. The step gets a full
    /// `StepCtx` on purpose: compensating effects are journaled, retried,
    /// reconciled and replayed exactly like forward ones, and may suspend for a
    /// human — a refund that needs four eyes is still a refund.
    async fn run_compensation(
        &self,
        cx: &Unwind<'_>,
        step: StepId,
        skill: &dyn Skill,
        outputs: &BTreeMap<StepId, Tainted<Value>>,
        cursor: &mut ReplayCursor,
        recorded_groups: BTreeMap<String, super::ctx::RecordedGroup>,
    ) -> Result<(), crate::core::SkillError> {
        // A step with no recorded output still gets compensated: the absence of
        // a result says nothing about whether it changed anything, and the
        // compensation is what knows.
        let output = outputs
            .get(&step)
            .cloned()
            .unwrap_or_else(|| Tainted::trusted(Value::Null));

        let mut ctx = StepCtx::new(
            &self.store,
            cursor.take(step, Phase::Compensating),
            self.plane_frame(StepFrame {
                run: cx.run,
                epoch: cx.epoch,
                step,
                phase: Phase::Compensating,
                mode: cx.mode,
                case: cx.case.clone(),
                ledger: Arc::clone(cx.ledger),
                identity: cx.identity.cloned(),
                subjects: cx.subjects.clone(),
                agent: cx.agent.to_owned(),
                #[cfg(feature = "manifest")]
                manifest: self.governing(skill),
                recorded_groups,
            }),
        );

        let result = skill.compensate(&mut ctx, &output).await;
        let mut slice = ctx.into_cursor();
        if let Err(crate::core::SkillError::Step(error)) = &result
            && let Some(divergence) =
                crate::journal::Divergence::of(step, Phase::Compensating, error, &slice)
        {
            slice.note_divergence(divergence);
        }
        cursor.restore(step, Phase::Compensating, slice);
        result
    }

    /// What the unwind walks, gated — or the quarantine that replaces it.
    ///
    /// Reads the journal's evidence and applies the stop gates. The gates run
    /// exactly when this conclusion closes the run to resume: always for a
    /// cancellation (it gets no second pass), and for a failure precisely
    /// when the unwind will compensate something — compensation is what
    /// closes resume, and a failure that compensates nothing stays open, so
    /// its orphans resolve and its suspended siblings re-register on the
    /// resume instead of being unwound around.
    async fn gated_unwind_list(
        &self,
        cx: &Unwind<'_>,
        status: &RunStatus,
        completed: &[(StepId, Capability)],
    ) -> Result<Result<(Vec<(StepId, Capability)>, UnwindEvidence), RunStatus>, RuntimeError> {
        // Which steps actually changed something outside. Read from the
        // journal rather than tracked in memory: it is the same evidence live
        // and on replay, and it is what lets an *undeclared* step be judged
        // on what it did instead of on what nobody said about it.
        let evidence = self.unwind_evidence(cx.run).await?;
        // The question is asked of the interrupted siblings too: a sibling
        // holding landed work the failure stranded is work the unwind must
        // reach, and asked of completed steps alone, a failure with nothing
        // completed to compensate left it standing. The failing step itself
        // is not asked — its own landed work leaves the run resumable.
        let candidates = Self::with_interrupted_siblings(completed, &evidence);
        let list = if status.is_cancelled() || self.will_compensate(&candidates, &evidence.mutated)
        {
            match self
                .stop_list(cx.run, completed, &evidence.started, &evidence.mutated)
                .await?
            {
                Ok(list) => list,
                Err(quarantine) => return Ok(Err(quarantine)),
            }
        } else {
            completed.to_vec()
        };
        Ok(Ok((list, evidence)))
    }

    /// The unwind list for a stop, or the quarantine that replaces it.
    ///
    /// Both rules in `maybe_unwind`'s doc comment, applied in order: refuse to
    /// unwind while an outcome is unknown, and extend the list with the steps
    /// the stop interrupted. Called only for a conclusion that closes the run
    /// to resume — a cancellation, or a failure whose unwind will compensate
    /// — so doubt quarantines unconditionally here: there is no later pass on
    /// which an unresolved outcome could still resolve, and compensating
    /// around the one call nobody can account for would destroy the evidence
    /// an operator needs to resolve it by hand.
    async fn stop_list(
        &self,
        run: RunId,
        completed: &[(StepId, Capability)],
        started: &BTreeMap<StepId, String>,
        mutated: &BTreeSet<StepId>,
    ) -> Result<Result<Vec<(StepId, Capability)>, RunStatus>, RuntimeError> {
        if let Some(step) = self.undecided_effect(run).await? {
            return Ok(Err(RunStatus::Quarantined(format!(
                "step {step} holds a mutating effect whose outcome is unknown — it \
                 was announced and never concluded, or concluded in doubt with no \
                 reconciliation — so the run cannot be unwound: compensating around \
                 it would undo everything except the one thing nobody can account for"
            ))));
        }
        Ok(Ok(Self::with_interrupted_steps(
            completed, started, mutated,
        )))
    }

    /// Whether an unwind over these completed steps would compensate anything.
    ///
    /// The question that decides whether a failure closes its run: a declared
    /// `Compensatable` step will be compensated, and an `Undeclared` step
    /// that provably mutated quarantines inside the loop — either way the
    /// conclusion is not one a resume can reopen. `Pivot` and `Unnecessary`
    /// steps compensate nothing. Deliberately conservative on a capability
    /// that no longer resolves: an unresolvable skill is treated as
    /// compensating, so the unwind path — which will surface the resolution
    /// error loudly — is taken rather than silently skipped.
    fn will_compensate(
        &self,
        completed: &[(StepId, Capability)],
        mutated: &BTreeSet<StepId>,
    ) -> bool {
        completed.iter().any(|(step, capability)| {
            self.resolve(&capability.0)
                .map_or(true, |skill| match skill.compensation() {
                    crate::core::Compensation::Compensatable => true,
                    crate::core::Compensation::Undeclared => mutated.contains(step),
                    crate::core::Compensation::Pivot | crate::core::Compensation::Unnecessary => {
                        false
                    }
                })
        })
    }

    /// The completed steps, plus every sibling a failure interrupted holding
    /// landed work: a step that mutated, never completed, and did not itself
    /// fail. Undone as the skill its `StepStarted` names, as
    /// [`with_interrupted_steps`](Self::with_interrupted_steps) undoes it.
    fn with_interrupted_siblings(
        completed: &[(StepId, Capability)],
        evidence: &UnwindEvidence,
    ) -> Vec<(StepId, Capability)> {
        let mut out = completed.to_vec();
        let done: BTreeSet<StepId> = out.iter().map(|(s, _)| *s).collect();
        for step in evidence
            .mutated
            .iter()
            .filter(|s| !done.contains(s) && !evidence.failed.contains(s))
        {
            if let Some(skill) = evidence.started.get(step) {
                out.push((*step, Capability::new(skill.as_str())));
            }
        }
        out
    }

    /// The unwind list for a stop: completed steps, plus any step that mutated
    /// without completing — the one a cancellation interrupted, or the sibling
    /// a failure stranded mid-suspension. The interrupted steps go last, so
    /// the caller's reverse walk undoes them first.
    ///
    /// An interrupted step is undone as the skill its `StepStarted` names —
    /// the capability that ran — never as whatever the plan in force has at
    /// its id. A step that charged and then asked to replan is interrupted
    /// under a successor that may drop it or put other work at its id, and
    /// either reading would leave the charge standing or refund it through a
    /// skill that never ran.
    ///
    /// A step whose compensation is already on the record stays in the list,
    /// exactly as a completed step does. The walk re-runs its compensation
    /// with every effect served from the journal and the `StepCompensated`
    /// dedup keeps the record single — while filtering it out here made a
    /// *replayed* unwind walk fewer steps than the recorded one, so a strict
    /// pass over an honestly-unwound run left the interrupted step's
    /// compensation slice unconsumed and quarantined a history that was
    /// telling the truth.
    fn with_interrupted_steps(
        completed: &[(StepId, Capability)],
        started: &BTreeMap<StepId, String>,
        mutated: &BTreeSet<StepId>,
    ) -> Vec<(StepId, Capability)> {
        let mut out = completed.to_vec();
        let done: BTreeSet<StepId> = out.iter().map(|(s, _)| *s).collect();
        for step in mutated.iter().filter(|s| !done.contains(s)) {
            if let Some(skill) = started.get(step) {
                out.push((*step, Capability::new(skill.as_str())));
            }
        }
        out
    }

    /// The lowest step holding an effect this journal cannot decide, if any.
    ///
    /// Ordinarily the run is already `Quarantined` when this is true, and a
    /// quarantined run never unwinds. Cancellation opens a second door into the
    /// unwind, and it has to be shut the same way — otherwise an operator's
    /// stop compensates every step *around* the one nobody can account for,
    /// which is precisely the refund for money nobody took, arriving through a
    /// control meant to make things safer.
    ///
    /// The rule itself is [`undecided_effects`](crate::journal::undecided_effects),
    /// shared with the operator API and the offline audit. This adds only the
    /// question the unwind asks of it: *how far back does the doubt reach*.
    async fn undecided_effect(&self, run: RunId) -> Result<Option<StepId>, RuntimeError> {
        let records = self
            .store
            .read(run, 1)
            .await
            .map_err(RuntimeError::from_store)?;
        Ok(crate::journal::undecided_effects(&records)
            .into_iter()
            .map(|u| u.step)
            .min())
    }

    /// Execute one plan node.
    async fn run_step(
        &self,
        ctx: StepRun<'_>,
        run_input: &Tainted<Value>,
        outputs: &BTreeMap<StepId, Tainted<Value>>,
        cursor: crate::journal::StepCursor,
    ) -> Result<
        (
            RunStatus,
            Option<Tainted<Value>>,
            crate::journal::StepCursor,
        ),
        RuntimeError,
    > {
        let span = tracing::info_span!(
            telemetry::STEP_SPAN,
            { telemetry::STEP } = tracing::field::display(ctx.node.id),
            { telemetry::CAPABILITY } = tracing::field::display(&ctx.node.capability.0),
            { telemetry::PHASE } = ctx.phase.as_str(),
            { telemetry::MODE } = telemetry::mode_str(ctx.mode),
            { telemetry::OUTCOME } = tracing::field::Empty,
        );
        self.run_step_inner(ctx, run_input, outputs, cursor)
            .instrument(span)
            .await
    }

    #[allow(clippy::too_many_lines)]
    async fn run_step_inner(
        &self,
        ctx: StepRun<'_>,
        run_input: &Tainted<Value>,
        outputs: &BTreeMap<StepId, Tainted<Value>>,
        cursor: crate::journal::StepCursor,
    ) -> Result<
        (
            RunStatus,
            Option<Tainted<Value>>,
            crate::journal::StepCursor,
        ),
        RuntimeError,
    > {
        let StepRun {
            identity,
            subjects,
            run,
            epoch,
            node,
            phase,
            mode,
            case,
            ledger,
            writing,
            stamp,
            agent,
            already_started,
            already_finished,
            recorded_groups,
            abandoning,
        } = ctx;
        let step = node.id;
        let skill = self.resolve(&node.capability.0)?;

        // Assemble this step's input from its declared sources. Labels join, so
        // provenance flows through the graph without anyone threading it by hand.
        let step_input = assemble(node, run_input, outputs)?;

        // Announce a step doing new work, once: always in `Live`, and on a
        // resume only for a step the journal never announced — a frontier
        // step running for the first time. Keying this on the mode alone got
        // both directions wrong: resumed frontier steps went unannounced, and
        // the `!Strict` finish gate below duplicated `StepFinished` for every
        // fully replayed step on every resume.
        let announce = writes_step_record(mode, !already_started);
        if announce {
            self.store
                .append(
                    epoch,
                    vec![stamp(
                        Append::new(
                            run,
                            RecordKind::StepStarted {
                                skill: skill.descriptor().name,
                            },
                        )
                        .step(step),
                    )],
                )
                .await
                .map_err(RuntimeError::from_store)?;
        }

        let mut cx = StepCtx::new(
            &self.store,
            cursor,
            self.plane_frame(StepFrame {
                run,
                epoch,
                step,
                phase,
                mode,
                case,
                ledger: Arc::clone(ledger),
                identity: identity.cloned(),
                subjects: subjects.clone(),
                agent: agent.to_owned(),
                #[cfg(feature = "manifest")]
                manifest: self.governing(skill.as_ref()),
                recorded_groups,
            }),
        );
        cx.abandoning = abandoning;
        // The one place elapsed time is measured, and it is measured with a
        // journaled clock read like every other observation — a wall-clock
        // ceiling decided from an ambient clock would give a replayed run a
        // different verdict every time it was looked at.
        //
        // Paid only by a run that asked for the ceiling, which is why the
        // step's first effect is this one when a wall-clock budget is declared
        // and the skill's own when it is not. The consequence is worth stating:
        // that history can be replayed under a *raised* wall-clock ceiling, and
        // not under a build that removed it, because the recorded run performs
        // a read this one would not request.
        let result = match Self::observe_clock(&mut cx, ledger).await {
            Ok(()) => skill.invoke(&mut cx, step_input).await,
            Err(e) => Err(crate::core::SkillError::Step(e)),
        };
        let result = settle_abandoned_group(&mut cx, result).await;
        let wrote = cx.wrote_records();
        let mut cursor = cx.into_cursor();
        if let Err(crate::core::SkillError::Step(error)) = &result
            && let Some(divergence) = crate::journal::Divergence::of(step, phase, error, &cursor)
        {
            cursor.note_divergence(divergence);
        }
        ledger.lock().expect("budget mutex").record_step();

        let fault = result.as_ref().err().map(crate::core::SkillError::class);
        let (status, output) = classify(&self.meter, result);
        tracing::Span::current().record(telemetry::OUTCOME, status.as_str());
        if let RunStatus::Quarantined(why) = &status {
            tracing::error!(
                target: telemetry::QUARANTINED,
                %run,
                %step,
                error_type = fault.unwrap_or("quarantined"),
                reason_digest = %telemetry::reason_digest(why),
            );
        }

        // Record the ending only where the journal does not already hold it:
        // every live step; a resumed step that did new work; and a resumed
        // step reaching an ending the record never captured — how a suspended
        // step that finishes purely from replayed history (its awaited event
        // recorded by the delivery) still gets its one `StepFinished`. What
        // this rules out is a duplicate ending for every fully replayed
        // completed step, appended on every resume of a run doing nothing new.
        let record_ending = writes_step_record(mode, announce || wrote || !already_finished);
        if writing && record_ending {
            // A suspended step has not finished, so it records why it stopped
            // rather than claiming an outcome.
            let record = match &status {
                RunStatus::Suspended(reason) => RecordKind::RunSuspended {
                    reason: reason.clone(),
                },
                other => RecordKind::StepFinished {
                    outcome: other.as_str().to_owned(),
                },
            };
            self.store
                .append(epoch, vec![stamp(Append::new(run, record).step(step))])
                .await
                .map_err(RuntimeError::from_store)?;
        }

        Ok((status, output, cursor))
    }

    /// Whether the chain's last record is already this conclusion. `head` is
    /// the chain's last sequence.
    async fn last_is_conclusion(
        &self,
        run: RunId,
        head: crate::core::Seq,
        status: &RunStatus,
    ) -> Result<bool, RuntimeError> {
        if head < 1 {
            return Ok(false);
        }
        let page = self
            .store
            .read_page(run, head, 1)
            .await
            .map_err(RuntimeError::from_store)?;
        Ok(matches!(
            page.first().map(Record::kind),
            Some(RecordKind::RunConcluded { outcome, .. }) if outcome == status.as_str()
        ))
    }

    /// Seal the run and report.
    /// Eight arguments, and each is a distinct fact about how the run ended
    /// that the caller already holds. Bundling them into a struct would move the
    /// same fields one indirection away without removing a single one.
    #[allow(clippy::too_many_arguments)]
    async fn conclude(
        &self,
        run: RunId,
        epoch: u64,
        status: RunStatus,
        output: Option<Tainted<Value>>,
        writing: bool,
        case: Option<crate::core::CaseId>,
        consumed: Consumed,
        live_spend: Spend,
        quota: &QuotaPass,
    ) -> Result<RunOutcome, RuntimeError> {
        // Loud toward the operator, ordinary toward the caller. A failed run is
        // a conclusion a resume can honestly answer, so it is not an incident —
        // but without this event nothing says why one failed except the
        // journal and an index that needs the HTTP surface mounted.
        if let RunStatus::Failed(reason) = &status {
            tracing::warn!(
                target: telemetry::RUN_FAILED,
                %run,
                error_type = "failed",
                reason_digest = %telemetry::reason_digest(reason),
            );
        }

        // A suspended run is not sealed: its chain is going to be extended the
        // moment whatever it waits for arrives.
        let chain_head = if writing && !status.is_suspended() {
            // The conclusion goes *in* the chain — before the chain is closed
            // over it, where the conclusion is one that closes it. Two things
            // follow, and both were missing while the outcome lived only in a
            // side table: tamper detection covers how the run ended, and a
            // resumed run can read that fact from the same history it verifies
            // rather than inferring it from the last step that happened to
            // finish. The stores also derive the outcome index from this
            // record, last conclusion wins — which is what keeps a
            // failed-then-resumed-then-succeeded run from being listed as
            // failed forever.
            let before = self
                .store
                .head(run)
                .await
                .map_err(RuntimeError::from_store)?;
            // A resume that did nothing new reaches the same open conclusion
            // the record already carries, and appending it again would grow
            // the journal by one identical conclusion per resume. The chain's
            // own last record is the authority: only when it already *is*
            // this conclusion is the append skipped. A resume that worked and then concluded the same way
            // has its work between the two conclusions, so both are kept.
            // Scoped to open conclusions, because a sealing one is
            // unreachable twice: the seal refuses further appends and a
            // sealed run's replay is a no-op long before here.
            let repeated =
                !status.seals() && self.last_is_conclusion(run, before.seq, &status).await?;
            if repeated {
                before.hash
            } else {
                let mut sealed = Append::new(
                    run,
                    RecordKind::RunConcluded {
                        outcome: status.as_str().to_owned(),
                        reason: status.own_account().map(std::borrow::Cow::into_owned),
                        exhaustion: match &status {
                            RunStatus::Exhausted(limit) => Some(limit.clone()),
                            _ => None,
                        },
                        live_spend,
                        chain_head: before.hash,
                    },
                );
                if let Some(c) = case {
                    sealed = sealed.case(c);
                }
                let concluded = self
                    .store
                    .append(epoch, vec![sealed])
                    .await
                    .map_err(RuntimeError::from_store)?;

                concluded.last().map_or(before.hash, |r| r.hash)
            }
        } else {
            self.store
                .head(run)
                .await
                .map_err(RuntimeError::from_store)?
                .hash
        };

        // Hand the lease back rather than letting it time out.
        //
        // Whatever the outcome — sealed, suspended, exhausted — this instance is
        // finished with the run. Holding the lease until expiry would make every
        // failover wait out the TTL for nothing, and that wait is precisely the
        // pressure that tempts a deployment into giving all its replicas one
        // owner string, which silently disables fencing.
        //
        // Best-effort on purpose. A release that fails costs a TTL of patience;
        // turning it into a run failure would convert a tidiness problem into a
        // correctness one, after the work is already done and journaled.
        //
        // Only when this pass held a lease at all. A strict pass acquires
        // nothing — it is a read — and both stores release on epoch match
        // alone, so a strict verification of a run whose owner is live under
        // that same epoch would mark the *owner's* lease released: its
        // heartbeat stops renewing and any delivery or sweep may fence a
        // healthy run mid-step. The same guard keeps a read-only pass out of
        // the quota ledger and the metrics: a verification is not work the
        // tenant did today, and accruing a historical run's spend into the
        // current period on every audit would bill the past once per look.
        if writing {
            // Settlement precedes both physical sealing and lease release. If
            // it fails, the conclusion remains open under an owned lease; once
            // that lease expires, recovery derives this pass from the journal
            // and retries the idempotent receipt.
            //
            // Whatever the outcome this instance is finished with the run, so
            // a **suspended** run gives its slot back too — it costs a row,
            // not a thread, and holding the slot would mean a tenant waiting
            // on a hundred approvals could start nothing. The figure accrued
            // is what *this pass* dispatched, not the run's cumulative spend,
            // which would bill the replayed prefix once per resume.
            self.settle_quota(run, epoch, live_spend, quota, status.seals())
                .await?;

            let chain_head = if status.seals() {
                let head = self
                    .store
                    .seal(run, epoch, status.as_str())
                    .await
                    .map_err(RuntimeError::from_store)?;
                self.retire_waits(run).await;
                head
            } else {
                chain_head
            };

            if let Err(e) = self.store.release_lease(run, epoch).await {
                tracing::debug!(
                    %run,
                    error = %e,
                    "could not hand back the lease; it will expire on its own"
                );
            }

            announce(&self.meter, run, &status);

            return Ok(RunOutcome {
                run_id: run,
                status,
                chain_head,
                consumed,
                output,
            });
        }

        Ok(RunOutcome {
            run_id: run,
            status,
            chain_head,
            consumed,
            // The caller is outside the lattice, so the label is dropped at the
            // boundary rather than inside the graph.
            output,
        })
    }
}

/// The run's result: the terminal step's output.
///
/// Not "whichever step finished last". That coincides with the terminal step
/// only while dispatch is sequential, and stops being well-defined the moment
/// two steps run at once. Lowest id wins when a plan has several terminals, so
/// the answer is a property of the plan rather than of the schedule.
fn run_output(ir: &PlanIR, outputs: &BTreeMap<StepId, Tainted<Value>>) -> Option<Tainted<Value>> {
    ir.nodes
        .iter()
        .filter(|n| n.terminal)
        .map(|n| n.id)
        .min()
        .and_then(|id| outputs.get(&id).cloned())
        // A run that stopped before any terminal step still has something to
        // report: the furthest output it did produce.
        .or_else(|| outputs.iter().next_back().map(|(_, v)| v.clone()))
}

/// Effects a run announced and never recorded an outcome for — the waits a
/// closed run leaves behind.
fn unanswered_waits(records: &[Record]) -> Vec<crate::core::EffectKey> {
    let settled: BTreeSet<_> = records
        .iter()
        .filter(|r| {
            matches!(
                r.kind(),
                RecordKind::EffectDone { .. }
                    | RecordKind::EffectFailed { .. }
                    | RecordKind::EffectReconciled { .. }
            )
        })
        .filter_map(Record::effect_key)
        .collect();
    records
        .iter()
        .filter(|r| matches!(r.kind(), RecordKind::EffectStarted { .. }))
        .filter_map(Record::effect_key)
        .filter(|k| !settled.contains(k))
        .collect()
}

/// Whether `epoch` holds the conclusion that sealed the run — the pass whose
/// settlement releases what the run still held.
fn concluded_in(records: &[Record], epoch: crate::core::Epoch) -> bool {
    records
        .iter()
        .any(|r| r.body.epoch == epoch && is_sealing_conclusion(r))
}

fn is_sealing_conclusion(record: &Record) -> bool {
    matches!(
        record.kind(),
        RecordKind::RunConcluded { outcome, .. } if SEALED_OUTCOMES.contains(&outcome.as_str())
    )
}

/// Spend durably recorded by effects written under one live pass epoch.
fn spend_recorded_in_epoch(records: &[Record], epoch: crate::core::Epoch) -> Spend {
    records
        .iter()
        .filter(|record| record.body.epoch == epoch)
        .fold(Spend::default(), |total, record| {
            let spend = match record.kind() {
                RecordKind::EffectDone { spend, .. }
                | RecordKind::EffectFailed { spend, .. }
                | RecordKind::EffectReconciled { spend, .. } => *spend,
                _ => Spend::default(),
            };
            total.plus(spend)
        })
}

/// Whether the plan actually finished.
///
/// Structural, never self-reported: a workload asserting it is done is not
/// evidence, so the runtime checks that every terminal node ran.
fn completion(ir: &PlanIR, done: &BTreeSet<StepId>) -> RunStatus {
    if ir.is_complete(done) {
        return RunStatus::Succeeded;
    }
    let missing: Vec<String> = ir
        .nodes
        .iter()
        .filter(|n| n.terminal && !done.contains(&n.id))
        .map(|n| n.id.to_string())
        .collect();
    RunStatus::Failed(format!(
        "plan did not complete: terminal step(s) {} never ran",
        missing.join(", ")
    ))
}

/// Say that a run changed its plan, and what it changed from.
fn announce_replan(meter: &super::metrics::Meter, run: RunId, next: &PlanIR, reason: &str) {
    tracing::info!(
        target: telemetry::REPLANNED,
        %run,
        from = next.derived_from.map(Digest::to_hex),
        version = next.version,
        reason_digest = %telemetry::reason_digest(reason),
    );
    meter.count(metrics::REPLANS, "");
}

/// Say how a run ended, on the run span and — for the loud ones — as an event.
fn announce(meter: &super::metrics::Meter, run: RunId, status: &RunStatus) {
    // Counted here and nowhere else. A step that quarantines also fails its run,
    // so counting at both levels would report one incident as two — and the
    // terminal status is the fact an operator is counting.
    meter.count(metrics::RUNS, status.as_str());
    match status {
        RunStatus::Quarantined(why) => {
            tracing::error!(
                target: telemetry::QUARANTINED,
                %run,
                error_type = "quarantined",
                reason_digest = %telemetry::reason_digest(why),
            );
            meter.count(metrics::QUARANTINES, "");
        }
        // Loud, though a person asked for it. The operator who decided already
        // knows; this reaches whoever answers for what the run left standing.
        RunStatus::Abandoned { actor, reason } => {
            tracing::error!(
                target: telemetry::ABANDONED,
                %run,
                %actor,
                reason_digest = %telemetry::reason_digest(reason),
            );
        }
        RunStatus::Exhausted(limit) => {
            tracing::warn!(target: telemetry::BUDGET_REFUSED, %run, %limit);
        }
        _ => {}
    }
    tracing::Span::current().record(telemetry::OUTCOME, status.as_str());
}

/// Record a batch's successes, then report the first step that stopped.
///
/// **Every** success is recorded, including those of siblings dispatched
/// alongside the one that stopped. Returning early on the first failure loses
/// them — and a sibling that already performed a mutating effect would then
/// never be compensated, because `completed` is what the unwind reverses. The
/// work happened; the saga has to know about it.
///
/// When siblings stop for different reasons, **severity wins over ready order**.
/// A suspension is the run working; a failure is the run over. Letting one
/// sibling's wait mask another's failure would defer the unwind until an event
/// that may never arrive — leaving the failed sibling's mutations in place
/// indefinitely. Within one severity, ready order decides, so the choice stays a
/// property of the plan rather than of the schedule.
fn apply(
    plan: &PlanIR,
    outcomes: Vec<StepOutcome>,
    done: &mut BTreeSet<StepId>,
    completed: &mut Vec<(StepId, Capability)>,
    ran: &mut BTreeMap<StepId, PlanNode>,
    outputs: &mut BTreeMap<StepId, Tainted<Value>>,
) -> Option<RunStatus> {
    let mut stopped: Option<RunStatus> = None;
    for (step, status, output) in outcomes {
        let RunStatus::Succeeded = status else {
            if stopped
                .as_ref()
                .is_none_or(|held| severity(&status) > severity(held))
            {
                stopped = Some(status);
            }
            continue;
        };
        if let Some(v) = output {
            outputs.insert(step, v);
        }
        done.insert(step);
        if let Some(node) = plan.node(step) {
            completed.push((step, node.capability.clone()));
            ran.insert(step, node.clone());
        }
    }
    stopped
}

/// How much a stop reason dominates a competing one.
///
/// `Quarantined` is highest because it is the only one that must *not* unwind:
/// something is undecidable, and compensating around it can make the damage
/// worse. `Suspended` is lowest because it is not a stop at all — the run is
/// healthy and waiting.
fn severity(status: &RunStatus) -> u8 {
    match status {
        RunStatus::Quarantined(_) => 3,
        // A stop ranks with a failure, not above it: both end the run, both
        // unwind, and when they arrive together the run is over either way.
        // Abandonment is not produced by a step and never competes here; it is
        // named so a new stop reason cannot be given a rank by omission.
        RunStatus::Cancelled { .. } | RunStatus::Abandoned { .. } | RunStatus::Failed(_) => 2,
        // A withdrawal ranks with exhaustion for the same reason: both pause a
        // healthy run, neither unwinds, and a sibling that actually failed has
        // decided more about the run than either.
        RunStatus::Exhausted(_) | RunStatus::Withheld { .. } => 1,
        // A replan request is the weakest signal in a batch: a sibling that
        // failed outright has already decided the run, and re-planning around a
        // failure is not what the requesting step was asking for.
        // Neither is reachable here at all — a sweep, a crossing and a lift are
        // sealed at birth with no steps to compete — and both are named for the reason
        // abandonment is: a rank given by omission is a decision nobody made.
        RunStatus::Replanning(_)
        | RunStatus::Suspended(_)
        | RunStatus::Succeeded
        | RunStatus::Swept
        // Unreachable for the same reason, and named rather than left to a
        // wildcard: an observed session has no steps of this plane's to
        // compete, because this plane ran none of it.
        | RunStatus::Observed
        | RunStatus::BrokeGlass { .. }
        | RunStatus::HaltLifted { .. }
        | RunStatus::HoldReleased { .. } => 0,
    }
}

/// Gather a dispatched batch back into ready order.
///
/// Not completion order. `completed` is what the unwind reverses, and a saga
/// whose compensation order depended on which future finished first would undo
/// a plan differently on every run.
type Dispatched = Result<(StepId, RunStatus, Option<Tainted<Value>>, StepCursor), RuntimeError>;

/// One step's result, once its history has been handed back.
type StepOutcome = (StepId, RunStatus, Option<Tainted<Value>>);

fn collect(
    dispatched: Vec<Dispatched>,
    ready: &[StepId],
    cursor: &mut ReplayCursor,
) -> Result<Vec<StepOutcome>, RuntimeError> {
    let mut outcomes = Vec::with_capacity(dispatched.len());
    for result in dispatched {
        let (step, status, out, slice) = result?;
        cursor.restore(step, Phase::Forward, slice);
        outcomes.push((step, status, out));
    }
    // The key is an `Option`, and `None` would sort *first* — so the invariant
    // that makes this total is worth naming rather than trusting: every
    // dispatched step came from `admit_ready(&ready, ..)`, which returns a
    // subset of `ready`. A future that dispatched a step outside the ready set
    // would silently re-order this batch rather than fail, and the order is what
    // an unwind reverses.
    outcomes.sort_by_key(|(step, _, _)| ready.iter().position(|r| r == step));
    Ok(outcomes)
}

/// What one ready set's dispatch needs.
struct Batch<'a> {
    agent: &'a str,
    identity: Option<&'a crate::core::Delegation>,
    subjects: &'a BTreeSet<crate::core::SubjectRef>,
    run: RunId,
    epoch: u64,
    ir: &'a PlanIR,
    mode: Mode,
    case: &'a Option<CaseContext>,
    ledger: &'a Arc<std::sync::Mutex<Ledger>>,
    writing: bool,
    stamp: &'a (dyn Fn(Append) -> Append + Send + Sync),
    input: &'a Tainted<Value>,
    outputs: &'a BTreeMap<StepId, Tainted<Value>>,
    /// Steps whose `StepStarted` the journal already holds. Empty on a live
    /// run.
    started: &'a BTreeSet<StepId>,
    /// Steps whose `StepFinished` the journal already holds. Empty on a live
    /// run.
    finished: &'a BTreeSet<StepId>,
    /// Group records the journal already holds, by writing step and phase.
    /// Empty on a live run.
    recorded_groups: &'a BTreeMap<(StepId, Phase, String), super::ctx::RecordedGroup>,
    /// How many of this ready set may be in flight at once.
    parallelism: usize,
    /// Re-running steps only to abandon groups a pause left open.
    abandoning: bool,
}

/// A standing withdrawal, as the step boundary meets it.
///
/// Carries the operator from the halt rather than only its reason: the
/// withholding record is the one durable trace of this act on the run it
/// stopped, and a pause nobody is named on cannot be asked about afterwards.
pub(crate) struct Withdrawal {
    pub(crate) subject: String,
    pub(crate) reason: String,
    pub(crate) by: crate::core::Operator,
}

/// What the journal proves about a run an unwind is deciding over.
struct UnwindEvidence {
    /// Steps that announced a mutating forward effect.
    mutated: BTreeSet<StepId>,
    /// The skill each step that started ran as, from its `StepStarted`.
    started: BTreeMap<StepId, String>,
    /// Steps whose compensation is already on the record.
    undone: BTreeSet<StepId>,
    /// Group records already on the journal, by writing step and phase.
    recorded_groups: BTreeMap<(StepId, Phase, String), super::ctx::RecordedGroup>,
    /// Steps whose last forward ending is not a success: the failing step,
    /// which stays resumable, as opposed to a sibling the failure interrupted.
    failed: BTreeSet<StepId>,
}

/// What producing a successor plan needs.
struct Replan<'a> {
    run: RunId,
    current: &'a PlanIR,
    /// The node each completed step ran as.
    ran: &'a BTreeMap<StepId, PlanNode>,
    reason: &'a str,
    already_replanned: u32,
    max_replans: Option<u32>,
    /// The successor this run produced when it first ran, if this is a replay.
    recorded: Option<&'a PlanIR>,
}

/// The first untrusted value in working memory, if any.
///
/// Returns the source so the refusal can name it: "replanning refused" without
/// saying *what* made it unsafe sends an operator looking through the whole run.
fn untrusted_in(outputs: &BTreeMap<StepId, Tainted<Value>>) -> Option<String> {
    outputs.values().find_map(|v| {
        let label = v.label();
        label.is_untrusted().then(|| {
            label
                .provenance
                .first()
                .map_or_else(|| "an untrusted source".to_owned(), ToString::to_string)
        })
    })
}

/// Where a refusal is recorded, when one is.
struct Journalling<'a> {
    run: RunId,
    epoch: u64,
    writing: bool,
    stamp: &'a (dyn Fn(Append) -> Append + Send + Sync),
}

/// What unwinding a run needs.
struct Unwind<'a> {
    identity: Option<&'a crate::core::Delegation>,
    subjects: &'a BTreeSet<crate::core::SubjectRef>,
    run: RunId,
    epoch: u64,
    ir: &'a PlanIR,
    mode: Mode,
    case: Option<CaseContext>,
    ledger: &'a Arc<std::sync::Mutex<Ledger>>,
    writing: bool,
    stamp: &'a (dyn Fn(Append) -> Append + Send + Sync),
    agent: &'a str,
}

/// What one step's execution needs.
// Each flag is an independent fact about this dispatch; no combination is
// invalid, so an enum over them would satisfy the lint at the reader's expense.
#[allow(clippy::struct_excessive_bools)]
struct StepRun<'a> {
    identity: Option<&'a crate::core::Delegation>,
    subjects: &'a BTreeSet<crate::core::SubjectRef>,
    run: RunId,
    epoch: u64,
    node: &'a PlanNode,
    phase: Phase,
    mode: Mode,
    case: Option<CaseContext>,
    ledger: &'a Arc<std::sync::Mutex<Ledger>>,
    writing: bool,
    stamp: &'a (dyn Fn(Append) -> Append + Send + Sync),
    agent: &'a str,
    /// Whether the journal already announced this step. Always `false` live.
    already_started: bool,
    /// Whether the journal already records this step finishing. Always
    /// `false` live.
    already_finished: bool,
    /// Group records this step and phase already wrote. Always empty live.
    recorded_groups: BTreeMap<String, super::ctx::RecordedGroup>,
    /// Whether this step is re-run only to abandon a group a pause left
    /// open, because the run was cancelled while paused.
    abandoning: bool,
}

/// The half of a `StepCtx`'s frame that belongs to the **step**.
///
/// A struct rather than a dozen positional arguments, for the reason
/// [`StepRun`] is one: the other half comes from the plane, and a caller who
/// transposed `phase` and `mode` positionally would compile.
struct StepFrame {
    run: RunId,
    epoch: crate::core::Epoch,
    step: StepId,
    phase: Phase,
    mode: Mode,
    case: Option<CaseContext>,
    ledger: Arc<std::sync::Mutex<Ledger>>,
    identity: Option<crate::core::Delegation>,
    subjects: BTreeSet<crate::core::SubjectRef>,
    agent: String,
    #[cfg(feature = "manifest")]
    manifest: Option<Arc<crate::manifest::Manifest>>,
    recorded_groups: BTreeMap<String, super::ctx::RecordedGroup>,
}

/// Where the recorded run was refused by a *step* limit, if the refusal still
/// stands.
///
/// A step-level refusal has no effect key, so it cannot ride the replay cursor
/// the way an effect's does; it is lifted from the records instead.
///
/// **The last word wins.** An exhausted run may be resumed under a raised
/// ceiling; when the resume re-admits the refused step it journals a
/// `BudgetReadmitted` beside the old refusal, and from then on the refusal is
/// history that was *superseded*, not a verdict to re-serve. Without this, a
/// strict replay of the resumed history would stop at the old refusal and
/// report `Exhausted` about a run whose own later records show it finishing —
/// the refusal followed by the continuation would read as divergence.
fn recorded_step_refusal(records: &[Record]) -> Option<(StepId, String, String)> {
    let mut standing: Option<(StepId, String, String)> = None;
    for r in records {
        match r.kind() {
            RecordKind::BudgetRefused { limit, used } if r.effect_key().is_none() => {
                if let Some(step) = r.body.step {
                    standing = Some((step, limit.clone(), used.clone()));
                }
            }
            RecordKind::BudgetReadmitted { .. }
                if standing
                    .as_ref()
                    .is_some_and(|(s, _, _)| Some(*s) == r.body.step) =>
            {
                standing = None;
            }
            _ => {}
        }
    }
    standing
}

/// The subject of a withholding the records left standing, if one stands.
///
/// **The last word wins**, exactly as it does for a step refusal: a withheld run
/// resumes once somebody lifts the halt, and the resume journals an
/// `AuthorityRestored` beside the withholding. From then on the withholding is
/// history that was *superseded* rather than a verdict to re-serve — without
/// this, a resumed run would be treated as still withheld and would conclude
/// that way forever, with each resume adding nothing.
fn standing_withholding(records: &[Record]) -> Option<String> {
    let mut standing: Option<String> = None;
    for r in records {
        match r.kind() {
            RecordKind::AuthorityWithheld { subject, .. } => standing = Some(subject.clone()),
            RecordKind::AuthorityRestored { .. } => standing = None,
            _ => {}
        }
    }
    standing
}

/// The run's most recent recorded conclusion, if it has one.
///
/// `None` for a run that has only ever suspended — a suspension is not a
/// conclusion, and `conclude` writes no `RunSealed` for it.
fn recorded_conclusion(records: &[Record]) -> Option<String> {
    records.iter().rev().find_map(|r| match r.kind() {
        RecordKind::RunConcluded { outcome, .. } => Some(outcome.clone()),
        _ => None,
    })
}

/// Whether this pass writes a step-level record: always live, never under
/// strict verification, and on a resume only when `new_fact` — the record is
/// not already in the journal, or the step did new work.
const fn writes_step_record(mode: Mode, new_fact: bool) -> bool {
    match mode {
        Mode::Live => true,
        Mode::Resume => new_fact,
        Mode::Strict => false,
    }
}

/// The steps whose start is already on the record.
///
/// Read back so a resume neither re-announces a step history already announced
/// nor forgets to announce one it is starting for the first time.
fn recorded_started_steps(records: &[Record]) -> BTreeSet<StepId> {
    records
        .iter()
        .filter_map(|r| match r.kind() {
            RecordKind::StepStarted { .. } => r.body.step,
            _ => None,
        })
        .collect()
}

/// The skill each step started as, from its forward `StepStarted`.
///
/// The capability that actually ran, which after a replan the plan in force
/// may no longer name at that id — or may name as other work.
fn started_skills(records: &[Record]) -> BTreeMap<StepId, String> {
    records
        .iter()
        .filter(|r| r.body.phase.is_forward())
        .filter_map(|r| match (r.kind(), r.body.step) {
            (RecordKind::StepStarted { skill }, Some(step)) => Some((step, skill.clone())),
            _ => None,
        })
        .collect()
}

/// The steps whose ending is already on the record.
///
/// Read back so a resume records a `StepFinished` exactly for the steps that
/// reach an ending the journal does not yet hold: a fully replayed completed
/// step keeps its one record, and a suspended step that finally finishes —
/// even purely from replayed history, its awaited event having been recorded
/// by the delivery — gets the one it never had.
fn recorded_finished_steps(records: &[Record]) -> BTreeSet<StepId> {
    records
        .iter()
        .filter_map(|r| match r.kind() {
            RecordKind::StepFinished { .. } => r.body.step,
            _ => None,
        })
        .collect()
}

/// The case the run is bound to, read from its `CaseBound` record.
fn recorded_case_id(records: &[Record]) -> Option<crate::core::CaseId> {
    records.iter().find_map(|r| match r.kind() {
        RecordKind::CaseBound { .. } => r.body.case,
        _ => None,
    })
}

/// The steps whose latest forward ending on the record is a success.
fn recorded_succeeded_steps(records: &[Record]) -> BTreeSet<StepId> {
    let mut succeeded = BTreeSet::new();
    for r in records.iter().filter(|r| r.body.phase.is_forward()) {
        if let (RecordKind::StepFinished { outcome }, Some(step)) = (r.kind(), r.body.step) {
            if outcome == RunStatus::Succeeded.as_str() {
                succeeded.insert(step);
            } else {
                succeeded.remove(&step);
            }
        }
    }
    succeeded
}

/// The group records already on the journal, by writing step and phase.
///
/// Read back for the same reason the step sets are: group records are not
/// effects, so the cursor cannot dedup them, and a resumed step that re-opens
/// its group or reaches its end at the frontier — cursor exhausted, writes
/// enabled — would otherwise write the same record a second time.
fn recorded_groups(
    records: &[Record],
) -> BTreeMap<(StepId, Phase, String), super::ctx::RecordedGroup> {
    let mut recorded: BTreeMap<(StepId, Phase, String), super::ctx::RecordedGroup> =
        BTreeMap::new();
    for r in records {
        let (group, opened) = match r.kind() {
            RecordKind::GroupOpened { group, .. } => (group, true),
            RecordKind::GroupSettled { group, .. } => (group, false),
            _ => continue,
        };
        let Some(step) = r.body.step else { continue };
        let entry = recorded
            .entry((step, r.body.phase, group.clone()))
            .or_default();
        if opened {
            entry.opened += 1;
        } else {
            entry.settled += 1;
        }
    }
    recorded
}

/// Every capability an agent advertises is provided by one of **its own**
/// skills.
///
/// An agent advertising a capability none of its skills provide is a card that
/// lies, and the caller who believed it finds out at dispatch — in production —
/// rather than here at startup.
///
/// This checked a plane-wide map, and the difference is not pedantry. A skill
/// registered on the *builder* rather than on the agent — `.agent(Agent::new(&m))`
/// followed by `.skill(s)` — satisfied a plane-wide check while being
/// **ungoverned**: `governed_by` is keyed from the agent's own skills, so that
/// skill gets no manifest. It runs under the plane's default budget instead of
/// the declared one, and `StepCtx::gate` never refuses a model or tool the file
/// did not list, because there is no file.
///
/// The plane built cleanly and the assertion's own message said "its skills",
/// so the only signal was a `None` from `cx.manifest()` that a skill has no
/// reason to check. That is a declaration reading as a control while governing
/// nothing, which is the one shape this codebase refuses everywhere.
#[cfg(feature = "manifest")]
fn check_declaration_matches_skills(
    m: &crate::manifest::Manifest,
    mine: &HashSet<Capability>,
) -> Result<(), BuildError> {
    let missing: Vec<String> = m
        .spec
        .capabilities
        .provides
        .iter()
        .filter(|c| !mine.contains(&Capability::new(c.as_str())))
        .cloned()
        .collect();
    if !missing.is_empty() {
        return Err(BuildError::AdvertisesWhatItCannotProvide {
            agent: m.metadata.name.clone(),
            missing,
        });
    }

    // And the other direction, which is the one that leaves no trace. A skill
    // registered under a manifest is *governed* by it — the manifest's budget,
    // model grants, egress ceiling and policy identity all apply — so a
    // capability the skill answers and the declaration never names is a
    // reviewed surface with an unreviewed door in it. The declaration is the
    // artifact that gets read, digested and pinned, and the A2A card is built
    // from it, so the extra capability is served and advertised nowhere.
    //
    // It is the same argument the manifest already makes about prompts: a
    // system prompt composed in the deployer's code has no version, changes in
    // a deploy, and nothing connects the change to the runs it affected. A
    // capability added in code does the same to the agent's surface.
    let undeclared: Vec<String> = {
        let declared: HashSet<Capability> = m
            .spec
            .capabilities
            .provides
            .iter()
            .map(|c| Capability::new(c.as_str()))
            .collect();
        let mut extra: Vec<String> = mine
            .iter()
            .filter(|c| !declared.contains(c))
            .map(|c| c.0.clone())
            .collect();
        // Deterministic, so the message does not depend on hash order.
        extra.sort();
        extra
    };
    if !undeclared.is_empty() {
        return Err(BuildError::ProvidesWhatItDoesNotAdvertise {
            agent: m.metadata.name.clone(),
            undeclared,
        });
    }
    Ok(())
}

/// Add one skill to the plane's two lookup tables, refusing a collision.
///
/// Both maps are plane-wide, and a bare `insert` would take a second
/// registration silently. That was tolerable when a plane was one agent and is
/// not now: dispatch resolves a capability to a skill *and to the manifest
/// governing it*, so a silent overwrite does not merely shadow the loser — it
/// moves work the loser still advertises out from under the loser's budget,
/// model grants and egress ceiling. Nothing in the journal would show it,
/// because the winner looks like the only claimant that ever existed.
///
/// Returns the skill's name, which is the key governance is recorded under.
///
/// # Errors
///
/// If another skill already holds this name, or another skill already claims one
/// of its capabilities.
fn register_skill(
    skill: Arc<dyn Skill>,
    caps: &mut HashMap<Capability, String>,
    skills: &mut HashMap<String, Arc<dyn Skill>>,
) -> Result<String, BuildError> {
    let d = skill.descriptor();
    if let Some(existing) = skills.get(&d.name)
        // Registering the *same* `Arc` twice is idempotent rather than a
        // mistake; two distinct skills under one name is the collision.
        && !Arc::ptr_eq(existing, &skill)
    {
        return Err(BuildError::DuplicateSkillName { name: d.name });
    }
    // `capabilities()`, not the raw field: a descriptor that declared nothing
    // answers its own name, and registering that here is what makes
    // `run("greet")` and an `agent/greet` grant resolve without a hello-world
    // program inventing a second name for its one skill.
    for cap in d.capabilities() {
        if let Some(first) = caps.get(&cap)
            && first != &d.name
        {
            return Err(BuildError::CapabilityClaimedTwice {
                capability: cap.0,
                first: first.clone(),
                second: d.name,
            });
        }
        caps.insert(cap, d.name.clone());
    }
    skills.insert(d.name.clone(), skill);
    Ok(d.name)
}

/// The capability a bare `run(target, ..)` admits: the first declared, or the
/// skill's own name — [`SkillDescriptor::capabilities`] is never empty.
fn first_capability(descriptor: &SkillDescriptor) -> Capability {
    descriptor
        .capabilities()
        .into_iter()
        .next()
        .unwrap_or_else(|| Capability::new(descriptor.name.clone()))
}

/// The business keys a case is identified by, for the binding record.
///
/// Read from the case rather than taken from the request, because a run joining
/// an existing case is admitted with whichever key its message carried while the
/// case may be identified by several — and a manifest binding naming any of them
/// must resolve.
///
/// Falls back to the admitted keys if the case cannot be read back. That is not
/// defensive padding: `correlate_or_open` has already committed the binding, so
/// a failure here is a read that lost a race with nothing, and the keys the run
/// was admitted with are a true subset of the case's. Recording them is strictly
/// better than recording none, and *nothing* is what would silently make a
/// binding unresolvable for a run whose case is perfectly well identified.
async fn case_correlation(
    cases: &dyn CaseStore,
    case_id: crate::core::CaseId,
    admitted: &[CorrelationKey],
) -> Result<Vec<CorrelationKey>, RuntimeError> {
    let stored = cases
        .case(case_id)
        .await
        .map_err(RuntimeError::from_store)?
        .map(|case| case.correlation)
        .unwrap_or_default();
    let mut keys = if stored.is_empty() {
        admitted.to_vec()
    } else {
        stored
    };
    // Canonical order, so the record is byte-stable for a given set and two
    // stores that answer in different orders produce the same journal.
    keys.sort();
    keys.dedup();
    Ok(keys)
}

/// A lease owner that no other process will accidentally share.
///
/// The previous default was the constant `"agentplane"`, which every replica and
/// every restart used. Two consequences, both silent:
///
/// * Two replicas each saw the other's lease as their own and renewed it
///   without bumping the epoch — two writers on one run, which is the exact
///   situation fencing exists to make impossible.
/// * A process restarting after a crash "renewed" the dead process's lease
///   instead of waiting for expiry and fencing it, so a zombie still holding a
///   socket could keep writing under the same epoch as its replacement.
///
/// A per-process random identity turns both into the correct behaviour: a
/// different owner cannot renew, so it waits for expiry and takes over with
/// `epoch + 1`.
///
/// Not derived from a hostname or PID: containers reuse both. Randomness is the
/// property that matters; readability is what the `owner` override is for, and a
/// deployment with a real instance identity — a pod name — should pass it.
fn default_owner() -> String {
    use std::collections::hash_map::RandomState;
    use std::hash::{BuildHasher, Hasher};
    use std::sync::atomic::{AtomicU64, Ordering};

    // OS entropy, and deliberately *not* the clock: this crate forbids reading
    // the wall clock outside a journaled effect, and rightly — a lease owner is
    // a poor reason to make an exception to a rule that keeps replay honest.
    // `RandomState` is seeded by the operating system, so two processes differ
    // even where a container has reused a PID.
    static SEED: std::sync::OnceLock<u64> = std::sync::OnceLock::new();
    // A counter beside it, so two runtimes built in one process — which tests do
    // constantly — never alias each other either.
    static SEQ: AtomicU64 = AtomicU64::new(0);

    let seed = *SEED.get_or_init(|| RandomState::new().build_hasher().finish());
    let n = SEQ.fetch_add(1, Ordering::Relaxed);
    format!("agentplane-{seed:016x}-{n}")
}

/// Resolve a run's data-subject bindings against its input, before the run
/// is bound to a case.
///
/// Declared bindings first, in declaration order, then the subjects the
/// embedder named; each entry's position is the index every reference to it
/// names. A binding that resolves to nothing refuses the run rather than
/// attributing its data to nobody. A `$case` binding is refused when the run
/// asked for no case, and otherwise left for [`fill_case_subjects`].
fn bind_subjects(
    declared: &[crate::journal::SubjectBinding],
    named: Vec<String>,
    input: &Tainted<Value>,
    in_case: bool,
) -> Result<Vec<crate::journal::BoundSubject>, RuntimeError> {
    use crate::journal::SubjectBinding;
    let refuse = |binding: &SubjectBinding, reason: &str| RuntimeError::SubjectUnbound {
        binding: binding.to_string(),
        reason: reason.to_owned(),
    };
    let mut resolved = Vec::new();
    let named = named
        .into_iter()
        .map(|subject| (SubjectBinding::Named, Some(subject)));
    for (position, (binding, given)) in declared
        .iter()
        .cloned()
        .map(|binding| (binding, None))
        .chain(named)
        .enumerate()
    {
        let (subject, trusted) = match (&binding, given) {
            (_, Some(subject)) => (subject, true),
            (SubjectBinding::Input { pointer }, None) => {
                let Some(selected) = input.project_pointer(pointer) else {
                    return Err(refuse(&binding, "it selects nothing in the run's input"));
                };
                let subject = match selected.peek() {
                    Value::String(text) => text.clone(),
                    Value::Number(number) => number.to_string(),
                    _ => {
                        return Err(refuse(&binding, "it selects neither a string nor a number"));
                    }
                };
                (
                    subject,
                    selected.label().trust == crate::core::Trust::Trusted,
                )
            }
            (SubjectBinding::Case, None) => {
                if !in_case {
                    return Err(refuse(&binding, "the run belongs to no case"));
                }
                (CASE_PENDING.to_owned(), true)
            }
            (SubjectBinding::Named, None) => {
                return Err(refuse(&binding, "no subject was named"));
            }
        };
        if subject.trim().is_empty() {
            return Err(refuse(&binding, "it resolves to an empty subject"));
        }
        let index = u16::try_from(position)
            .map_err(|_| refuse(&binding, "a run binds at most 65536 subjects"))?;
        resolved.push(crate::journal::BoundSubject {
            index,
            binding,
            trusted,
            subject,
        });
    }
    Ok(resolved)
}

/// What a `$case` binding holds between [`bind_subjects`] and
/// [`fill_case_subjects`]: never journaled.
const CASE_PENDING: &str = "$case";

/// Give each `$case` binding the id of the case the run was bound to.
fn fill_case_subjects(
    mut bound: Vec<crate::journal::BoundSubject>,
    case: Option<&CaseContext>,
) -> Vec<crate::journal::BoundSubject> {
    if let Some(case) = case {
        for entry in &mut bound {
            if entry.binding == crate::journal::SubjectBinding::Case {
                entry.subject = case.case_id.to_string();
            }
        }
    }
    bound
}

/// The references a run's `DataSubjectBound` record makes available to every
/// value it reads.
fn subject_refs(
    run: RunId,
    bound: &[crate::journal::BoundSubject],
) -> BTreeSet<crate::core::SubjectRef> {
    bound
        .iter()
        .map(|b| crate::core::SubjectRef {
            run,
            index: b.index,
        })
        .collect()
}

/// The references a recorded run's `DataSubjectBound` names, read back so a
/// resume attributes exactly as the live run did.
fn recorded_subjects(run: RunId, records: &[Record]) -> BTreeSet<crate::core::SubjectRef> {
    records
        .iter()
        .find_map(|r| match r.kind() {
            RecordKind::DataSubjectBound { bindings } => Some(subject_refs(run, bindings)),
            _ => None,
        })
        .unwrap_or_default()
}

/// The admitted input, label and all.
///
/// Read back rather than recomputed: a replay that re-labelled would reach a
/// different verdict at every taint gate than the run it reproduces.
fn recorded_input(r: &Record) -> Option<Tainted<Value>> {
    match r.kind() {
        RecordKind::RunAdmitted {
            input, input_label, ..
        } => Some(Tainted::with_label(input.clone(), input_label.clone())),
        _ => None,
    }
}

/// Refuse a history this build cannot re-derive.
///
/// Before recomputing anything, because every effect key a replay derives comes
/// out of the canonicalizer: a run written under another rule recomputes
/// different keys and would be quarantined as *non-determinism* — the most
/// serious conclusion this runtime reaches, reported for a healthy run because
/// the rule moved underneath it.
///
/// The chain itself is fine and always was: it hashes the bytes it stored rather
/// than re-canonicalizing them. What moved is everything *derived*, which is
/// exactly the class replay compares.
fn ensure_replayable_canon(records: &[Record]) -> Result<(), RuntimeError> {
    if let Some(recorded) = records.iter().find_map(recorded_canon)
        && recorded != crate::core::canon::VERSION
    {
        return Err(RuntimeError::CanonicalizationChanged {
            recorded,
            implemented: crate::core::canon::VERSION,
        });
    }
    Ok(())
}

/// Which canonicalization rule wrote this run's derived digests.
fn recorded_canon(r: &Record) -> Option<u16> {
    match r.kind() {
        RecordKind::RunAdmitted { canon, .. } => Some(*canon),
        _ => None,
    }
}

/// The principal a run was admitted as.
///
/// Read back rather than recomputed, for the same reason the plan is: the
/// principal a run was authorized as is a fact *about that run*, and deriving it
/// again from a plan that may since have been edited would silently re-attribute
/// history.
/// The chain a recorded run acted under, re-checked structurally on the way
/// back — never re-verified as a credential, for the reason `core::identity`
/// gives. `None` for a run admitted without one.
fn recorded_chain(records: &[Record]) -> Result<Option<crate::core::Delegation>, RuntimeError> {
    records
        .iter()
        .find_map(|r| match r.kind() {
            RecordKind::IdentityBound { chain } => Some(chain.clone()),
            _ => None,
        })
        .map(crate::core::Delegation::rehydrate)
        .transpose()
        .map_err(RuntimeError::Delegation)
}

/// Whether a resume refused with `error` would be refused the same way on
/// every attempt: the journal it read is what refuses, not the store, a lease,
/// a quota or this plane's configuration.
///
/// Named rather than negated: a failure not listed here is retried, so a
/// transient one added later costs a retry loop rather than a quarantine.
/// `PlanContract`, `NoProvider` and `NoCaseStore` are not listed because they
/// are about this plane — a quota store, an agent or a case store it lacks —
/// and another plane may settle what this one cannot.
const fn recurs_on_every_resume(error: &RuntimeError) -> bool {
    matches!(
        error,
        RuntimeError::Encoding(_)
            | RuntimeError::ChainBroken { .. }
            | RuntimeError::CanonicalizationChanged { .. }
            | RuntimeError::Delegation(_)
    )
}

fn recorded_agent(records: &[Record]) -> String {
    records
        .iter()
        .find_map(|r| match r.kind() {
            RecordKind::RunAdmitted { capability, .. } => Some(capability.clone()),
            _ => None,
        })
        .unwrap_or_default()
}

/// Build a step's input from its declared argument sources.
///
/// Labels join across sources, so a step reading anything untrusted produces an
/// untrusted input without the plan author having to say so.
fn assemble(
    node: &PlanNode,
    run_input: &Tainted<Value>,
    outputs: &BTreeMap<StepId, Tainted<Value>>,
) -> Result<Tainted<Value>, RuntimeError> {
    // The common case — a single argument — passes the value through rather than
    // wrapping it in a one-key object, so simple plans stay legible.
    if node.args.len() == 1
        && let Some((_, only)) = node.args.iter().next()
    {
        return resolve_arg(node, only, run_input, outputs);
    }

    let mut fields = Vec::with_capacity(node.args.len());
    for (name, source) in &node.args {
        let v = resolve_arg(node, source, run_input, outputs)?;
        fields.push((name.clone(), v));
    }
    Ok(Tainted::object(fields))
}

fn resolve_arg(
    node: &PlanNode,
    source: &ArgSource,
    run_input: &Tainted<Value>,
    outputs: &BTreeMap<StepId, Tainted<Value>>,
) -> Result<Tainted<Value>, RuntimeError> {
    let pick = |v: &Value, field: &Option<String>| match field {
        Some(f) => v.get(f).cloned().unwrap_or(Value::Null),
        None => v.clone(),
    };

    Ok(match source {
        // Picking a field inherits the whole value's label: the parts of an
        // untrusted document are untrusted.
        ArgSource::RunInput { field } => {
            Tainted::with_label(pick(run_input.peek(), field), run_input.label().clone())
        }
        ArgSource::Const { value } => Tainted::trusted(value.clone()),
        ArgSource::Node { step, field } => {
            // The contract already proved this is upstream, so a miss here means
            // the scheduler dispatched out of order — a bug worth naming rather
            // than papering over with a null.
            let upstream = outputs.get(step).ok_or_else(|| {
                RuntimeError::PlanContract(format!(
                    "step {} read step {step}, which has not produced a value",
                    node.id
                ))
            })?;
            match field {
                Some(field) => upstream
                    .project_field(field)
                    .unwrap_or_else(|| Tainted::with_label(Value::Null, upstream.label().clone())),
                None => upstream.clone(),
            }
        }
    })
}

/// Settle a group the skill left open, because `Drop` cannot.
///
/// A skill that fails with `?` never reaches `commit` or `abort`, so the handle
/// is dropped with members standing. Reversing them is async and `Drop` is not,
/// which is why the group lives on the context and the executor finishes what
/// the handle abandoned — the same relationship the executor already has with a
/// step's compensation.
///
/// Three situations, and they are not the same:
///
/// * **suspended** — the step has not ended. Its frame is persisted and it will
///   re-run from the top, rebuilding the group from the journal as it replays
///   the members. Reversing here would undo a run that is merely waiting.
/// * **failed** — abort, unless the failure leaves the world in doubt. Doubt is
///   the one condition under which nothing may be reversed.
/// * **succeeded with a group still open** — an author bug, and the safe
///   reading is that the group was never meant to take. It is reversed and the
///   step fails loudly, because a group that commits by being forgotten is
///   worse than one that does not commit at all.
async fn settle_abandoned_group(
    cx: &mut StepCtx<'_>,
    result: Result<Outcome, crate::core::SkillError>,
) -> Result<Outcome, crate::core::SkillError> {
    use crate::core::{SkillError, StepError};

    let Some(name) = cx.open_group().map(|g| g.name.clone()) else {
        return result;
    };
    // A pause leaves the group open for the resumed step to settle — unless
    // the run was cancelled while paused and this pass exists to abandon it.
    if !cx.abandoning
        && matches!(&result, Err(SkillError::Step(e)) if crate::runtime::group::is_pause(e))
    {
        return result;
    }

    // A member whose failure may have reached the world travels no further.
    // Reversing around a call that may have — or did — happen leaves the world
    // holding a write no `Aborted` settlement can honestly claim to have undone.
    let doubt = match &result {
        Err(SkillError::Step(e)) => crate::runtime::group::may_have_externalised(e),
        _ => false,
    };
    if doubt {
        let detail = match &result {
            Err(e) => e.to_string(),
            Ok(_) => String::new(),
        };
        let settled = cx
            .settle_open_group(crate::core::GroupOutcome::Quarantined, Some(&detail))
            .await;
        return match settled {
            Ok(()) => result,
            Err(e) => Err(SkillError::Step(e)),
        };
    }

    match cx
        .abort_open_group("the step ended without settling the group")
        .await
    {
        // The abort itself could not be completed. That outranks whatever the
        // step was reporting: a partly unwound group is the more dangerous fact.
        Err(e) => Err(SkillError::Step(e)),
        Ok(()) => match result {
            // A reported failure keeps its own reason. `Outcome::Fail` is an
            // `Ok` at the type level and a failure in fact: leaving the group
            // to the runtime is the ordinary path there, not an author bug, and
            // overwriting the reason would tell an operator the step "returned
            // successfully" while hiding why it actually stopped.
            Err(e) => Err(e),
            failed @ Ok(Outcome::Fail { .. }) => failed,
            // Anything else claimed to make progress while leaving a group
            // unsettled.
            Ok(_) => Err(SkillError::Step(StepError::GroupAborted {
                what: format!(
                    "step made progress with group '{name}' still open — it was \
                     reversed, because a group that commits by being forgotten is worse \
                     than one that does not commit at all"
                ),
            })),
        },
    }
}

/// Turn a step's result into a run status.
///
/// The distinction that matters is between an ordinary failure and a run whose
/// *history can no longer be trusted*. Divergence and orphaned effects are the
/// latter: they mean the journal no longer describes what this code does, so a
/// human has to look before anything else happens. Folding them into `Failed`
/// would put them in the same bucket as "the invoice was rejected", and they
/// would be retried like one.
fn classify(
    meter: &super::metrics::Meter,
    result: Result<Outcome, crate::core::SkillError>,
) -> (RunStatus, Option<Tainted<Value>>) {
    use crate::core::{SkillError, StepError};

    match result {
        // The label travels with the value. Stripping it here would silently
        // launder provenance at every step boundary: a downstream step reading
        // an untrusted upstream output would receive it marked trusted, and the
        // taint gates further on would have nothing to act on.
        Ok(Outcome::Done(v)) => (RunStatus::Succeeded, Some(v)),
        Ok(Outcome::Fail { reason }) => (RunStatus::Failed(reason), None),
        // Not a failure: the executor decides whether a new plan is allowed,
        // because the answer depends on the run's provenance and budget, which
        // a step cannot see.
        Ok(Outcome::Replan { reason }) => (RunStatus::Replanning(reason), None),
        // Suspension is not a failure: the run is healthy and waiting. It
        // reaches here as an error only because that is how control leaves a
        // skill.
        Err(SkillError::Step(StepError::Suspended(reason))) => (RunStatus::Suspended(reason), None),
        // The ceiling did its job. Reporting this as a failure would have
        // operators debugging a system that behaved exactly as instructed.
        Err(SkillError::Step(StepError::Budget(exceeded))) => {
            (RunStatus::Exhausted(exceeded), None)
        }
        // A withdrawal found at a hop is the boundary's pause, reached
        // mid-step: the hop recorded the withholding before refusing.
        Err(SkillError::Step(StepError::Withheld { subject, reason })) => {
            (RunStatus::Withheld { subject, reason }, None)
        }
        Err(e) => {
            let msg = e.to_string();
            // Matched structurally, never on the message: a match on the word
            // "quarantined" would let a reworded error silently downgrade a run
            // to `Failed` — history kept, the flag that said not to trust it
            // lost.
            // Each of these is a failure P7 exists to make loud, and each gets
            // its own event so "did this happen" is a query rather than a grep.
            match &e {
                SkillError::Step(StepError::NonDeterminism {
                    seq,
                    expected,
                    actual,
                    detail,
                }) => {
                    tracing::error!(
                        target: telemetry::NONDETERMINISM,
                        %seq, %expected, %actual,
                        error_type = "nondeterminism",
                        reason_digest = %telemetry::reason_digest(detail),
                    );
                    meter.count(metrics::DIVERGENCES, "");
                }
                SkillError::Step(StepError::ReplayOverrun { actual, kind }) => {
                    tracing::error!(
                        target: telemetry::NONDETERMINISM,
                        %actual, %kind, overrun = true,
                    );
                    meter.count(metrics::DIVERGENCES, "");
                }
                SkillError::Step(StepError::Undecidable { key, detail, .. }) => {
                    tracing::error!(
                        target: telemetry::UNDECIDABLE,
                        %key,
                        error_type = "undecidable",
                        reason_digest = %telemetry::reason_digest(detail),
                    );
                    meter.count(metrics::UNDECIDABLE, "");
                }
                SkillError::Step(StepError::Unreproducible { what, detail }) => {
                    tracing::error!(
                        target: telemetry::UNREPRODUCIBLE,
                        error_type = "unreproducible",
                        reason_digest = %telemetry::reason_digest(&format!("{what}: {detail}")),
                    );
                    meter.count(metrics::UNREPRODUCIBLE, "");
                }
                _ => {}
            }

            let untrustworthy = matches!(
                e,
                SkillError::Step(
                    StepError::NonDeterminism { .. }
                        | StepError::ReplayOverrun { .. }
                        | StepError::Undecidable { .. }
                        | StepError::GroupUnsettled { .. }
                        | StepError::Unreproducible { .. }
                )
            );
            if untrustworthy {
                (RunStatus::Quarantined(msg), None)
            } else {
                (RunStatus::Failed(msg), None)
            }
        }
    }
}

/// Everything one execution needs, gathered so the executor is not called with
/// eight positional arguments — two of which are `u64`-shaped and would swap
/// silently.
struct Execution<'a> {
    /// Where the recorded run was refused by a step limit, if it was. `None`
    /// for a live run, which has no history to consult.
    refusal: Option<(StepId, String, String)>,
    /// The subject of a withholding the recorded history left standing. `None`
    /// for a live run, and for a resumed one whose withdrawal was already
    /// lifted and recorded.
    withheld_subject: Option<String>,
    /// Successor plans the recorded run produced, oldest first. Empty on a live
    /// run. Read back rather than re-synthesised, because a planner asked twice
    /// can answer differently.
    successors: Vec<PlanIR>,
    /// Steps whose `StepStarted` is already on the record. Empty on a live
    /// run. Read back so a resume neither re-announces a step nor forgets to
    /// announce one it starts for the first time.
    started: BTreeSet<StepId>,
    /// Steps whose `StepFinished` is already on the record. Empty on a live
    /// run.
    finished: BTreeSet<StepId>,
    /// Steps whose latest forward ending on the record is a success. Empty on
    /// a live run. A resume replays these before it asks whether to stop, so
    /// an unwind sees their outputs and the order they finished in.
    succeeded: BTreeSet<StepId>,
    /// Group records already on the journal, keyed by the step and phase
    /// that wrote them. Empty on a live run. Read back for the same reason
    /// `finished` is: group records are not effects, so the cursor cannot
    /// dedup them, and a resumed step that re-opens or re-settles its group
    /// at the frontier — where its cursor is exhausted and writes are
    /// enabled — would report one group as two.
    recorded_groups: BTreeMap<(StepId, Phase, String), super::ctx::RecordedGroup>,
    run: RunId,
    epoch: u64,
    quota: QuotaPass,
    plan: &'a PlanIR,
    input: Tainted<Value>,
    mode: Mode,
    case: Option<CaseContext>,
    budget: Budget,
    /// The run's data-subject references: from the `DataSubjectBound` just
    /// written on a live run, read back from it on a replay.
    subjects: BTreeSet<crate::core::SubjectRef>,
    /// Who is acting, for the policy principal. Read back from `RunAdmitted` on
    /// a replay rather than recomputed, for the same reason the plan is: the
    /// principal a run was authorized as is a fact about that run.
    agent: String,
    /// On whose behalf, for the policy context and for what this run
    /// commissions. Read back from `IdentityBound` on a replay for the same
    /// reason: a resumed run acting under the plane's chain instead of the one
    /// recorded for it would reach different verdicts than the live run did.
    identity: Option<crate::core::Delegation>,
}

/// What a conclusion says when nothing on the chain says who ended the run.
///
/// Quarantine rather than a placeholder name, for the reason the exhausted arm
/// beside it quarantines when the typed ceiling verdict is missing: the record
/// is not trustworthy, and *not trustworthy* is a different bucket from *try
/// again*. A name invented here would be served through the operator API as the
/// person who did it.
const UNATTRIBUTED: &str = "the chain records this ending and not who asked for it — an \
                            operator act with nobody on it cannot be answered by reading further";

/// The recorded status of a run that must not be resumed.
///
/// The outcomes that close a run to recovery:
///
/// * **Succeeded** — there is nothing outstanding. Re-executing would repeat
///   work that is not an effect (a case-state write, say), which is the same
///   class of bug the effect protocol prevents, arriving through a side door.
/// * **Cancelled** — a stopped run stays stopped, or the next inbound event
///   resumes it and it carries on doing the thing somebody intervened to
///   prevent.
/// * **Abandoned** — a person already decided there will never be an answer.
/// * **Quarantined, until a person answers it.** Resuming an unanswered
///   quarantine would re-hit whatever could not be decided, and burying that in
///   a retry loop is exactly how an undecidable situation becomes an unnoticed
///   one. A recorded [`QuarantineDecided`](RecordKind::QuarantineDecided)
///   lifts it — the *precondition* is that a named person looked, and the
///   verdict is still the runtime's: a reopened run re-decides from a history
///   that now holds whatever they established, and reaches the same quarantine
///   again if they were wrong or incomplete.
///
/// A **failed** run is deliberately *not* terminal here: a process that died
/// mid-flight records a failure, and recovering it is the entire point.
///
/// # Why the seal, and not the last step
///
/// Scanning backwards for a `StepFinished` and reading its outcome is wrong
/// twice, and the second is severe:
///
/// * A step's outcome is not the run's. They coincide only in a one-step plan.
/// * `find_map` **skips** a record it does not recognise and keeps looking. A
///   run whose last step failed after earlier steps succeeded would match an
///   *earlier* `StepFinished { outcome: "succeeded" }` and be reported
///   closed-and-succeeded: every multi-step run suspended after a failure —
///   every saga waiting on an approval to finish unwinding — could never be
///   resumed, and would report success while stuck.
///
/// `RunSealed` is written by `conclude` for exactly the runs that reached a
/// conclusion, and never for a suspended one. That is the fact this needs, so
/// it is the fact it reads.
pub(crate) fn resume_is_closed(records: &[Record]) -> Option<RunStatus> {
    let outcome = records.iter().rev().find_map(|r| match r.kind() {
        RecordKind::RunConcluded { outcome, .. } => Some(outcome.as_str()),
        _ => None,
    })?;

    match outcome {
        "succeeded" => Some(RunStatus::Succeeded),
        "quarantined" => quarantine_decision(records).is_none().then(|| {
            RunStatus::Quarantined(
                "recorded as quarantined; a named person has to answer it before it can run \
                 again — reopen it once the doubt is resolved, or abandon it"
                    .into(),
            )
        }),
        // A conclusion whose attribution record is missing is **quarantined**,
        // not attributed to a person called "unknown". The arm for an exhausted
        // run with no typed ceiling verdict already reads this way; these three
        // fabricated a name instead, and a fabricated one is worse than a
        // missing one because it is indistinguishable from a real operator with
        // that name and it is served through the operator API as fact.
        //
        // The reason is the one the person gave, from the record that holds
        // it, rather than a sentence written here: an operator refused a
        // resume is asking *why this run is closed*, and a canned restatement
        // of the outcome answers a question they did not ask.
        "abandoned" => Some(recorded_abandonment(records).map_or_else(
            || RunStatus::Quarantined(UNATTRIBUTED.to_owned()),
            |(actor, reason)| RunStatus::Abandoned { actor, reason },
        )),
        // A stopped run stays stopped. Otherwise the next inbound event resumes
        // it and it carries on doing the thing somebody intervened to prevent —
        // and the intervention would look, from the journal, like it worked.
        "cancelled" => Some(recorded_cancellation(records).map_or_else(
            || RunStatus::Quarantined(UNATTRIBUTED.to_owned()),
            |(actor, reason)| RunStatus::Cancelled { actor, reason },
        )),
        // The two conclusions that deliberately do not close a run: a failed
        // run resumes with its completed effects read back from history, and an
        // exhausted one continues once somebody raises the ceiling.
        //
        // Their relationship to [`RunStatus::seals`] is the load-bearing part
        // and is pinned by `a_sealing_conclusion_is_never_resumable`. The
        // direction that matters is *no sealing status may be resumable*: a
        // status that seals froze the journal and published a Merkle leaf, so
        // resuming it would grow the history past the leaf every later
        // checkpoint attests. The reverse direction is deliberately **not** an
        // equality — `Suspended` and `Replanning` also do not seal, and never
        // reach here at all, because neither is ever a recorded conclusion.
        // Stating that as "the two that do not seal" was wrong; there are four,
        // and only two of them can be a `RunSealed` outcome.
        // A withdrawal joins them, and is the clearest case of the three: the
        // run did nothing wrong, its mutations stand, and lifting the halt is
        // what continues it. Closing it would turn *stop acting under this
        // credential* into *destroy this work*, which is not what an operator
        // withdrawing a credential asked for — the operator who wants that
        // cancels, and cancelling unwinds.
        "failed" | "exhausted" | WITHHELD_OUTCOME => None,
        // Fail closed. An outcome this build does not recognise — a sweep's
        // `swept`, a future variant, a corrupted string — is not permission to
        // resume; it is a run whose recorded ending this code cannot interpret,
        // and continuing it would graft new behaviour onto a history that says
        // it ended.
        other => Some(RunStatus::Quarantined(format!(
            "recorded as '{other}', which this build does not recognise as resumable"
        ))),
    }
}

/// Refuse a resume that would report success over work its own history reversed.
///
/// A run whose journal holds compensation-phase records is not resumable once it
/// stands concluded. The unwind *reversed* work — a hold released, a refund
/// issued — and a resume that replays the forward history and continues would
/// conclude success over a world where the work was undone: the journal would
/// say "done" about effects its own later records say were taken back.
///
/// Scoped to runs with a standing conclusion, deliberately: a run that is
/// mid-unwind (a compensation suspended for four eyes, a crash between
/// reversals) has concluded nothing, and resuming it is how the unwind finishes.
fn refuse_resume_over_undone_work(run: RunId, records: &[Record]) -> Result<(), RuntimeError> {
    let Some(outcome) = recorded_conclusion(records) else {
        return Ok(());
    };
    if !records
        .iter()
        .any(|r| matches!(r.kind(), RecordKind::StepCompensated { .. }))
    {
        return Ok(());
    }
    Err(RuntimeError::PlanContract(format!(
        "run {run} concluded '{outcome}' after compensating completed steps — the work was \
         reversed, and resuming over undone work would report success about a world where it no \
         longer stands. Start a fresh run"
    )))
}

/// The person's answer standing against this run's quarantine, if there is one.
///
/// Scoped to what follows the **last** conclusion, so an answer is spent by the
/// pass it authorized. A reopened run that quarantines again is quarantined
/// again: the earlier decision was made about a history that has since moved,
/// and reading it as standing would turn one person's judgement into a
/// permanent licence to retry.
fn quarantine_decision(records: &[Record]) -> Option<(crate::core::QuarantineDecision, &Record)> {
    records
        .iter()
        .rev()
        .take_while(|r| !matches!(r.kind(), RecordKind::RunConcluded { .. }))
        .find_map(|r| match r.kind() {
            RecordKind::QuarantineDecided { decision, .. } => Some((*decision, r)),
            _ => None,
        })
}

/// The abandonment this run's history asks for but has not yet recorded.
///
/// A decision is written before it is acted on, so a crash in between leaves
/// the instruction standing rather than lost. This is what the next resume
/// reads to finish the job — and it is why abandonment is not simply performed
/// inline by the verb that requests it.
fn pending_abandonment(records: &[Record]) -> Option<RunStatus> {
    let (decision, record) = quarantine_decision(records)?;
    if decision != crate::core::QuarantineDecision::Abandon {
        return None;
    }
    match record.kind() {
        RecordKind::QuarantineDecided {
            decider, reason, ..
        } => Some(RunStatus::Abandoned {
            actor: decider.clone(),
            reason: reason.clone(),
        }),
        _ => None,
    }
}

/// The longest admission key this runtime accepts.
///
/// Bounded because the key is a **counterparty-controlled** string that becomes
/// part of a storage key: unbounded, it is an index entry an emitter chooses the
/// size of. 512 bytes is far above what an identity needs — a `CloudEvents`
/// `source` and `id` together are tens of bytes — and far below what a btree
/// index refuses, so the refusal is this crate's with a reason rather than the
/// backend's with an error code.
pub const MAX_ADMISSION_KEY_BYTES: usize = 512;

/// Refuse a key that cannot mean what the caller thinks it means.
///
/// An **empty** key is the important one, and it is refused rather than
/// accepted as a value. A missing header or an unset variable arrives here as
/// `""`, and `""` is a perfectly good key: the first message claims it and every
/// later message — a *different* message — is answered with the first one's run.
/// That is silent, total message loss produced by a configuration mistake, and
/// it is exactly what an at-most-once control must not do quietly.
fn validate_admission_key(key: &str) -> Result<(), RuntimeError> {
    if key.trim().is_empty() {
        return Err(RuntimeError::PlanContract(
            "an admission key is empty — an unset header or variable arrives here as \
             an empty string, and accepting it would answer every later message with \
             the first one's run. Use the message's own identity, such as \
             `InboundEvent::dedup_key()`"
                .into(),
        ));
    }
    if key.len() > MAX_ADMISSION_KEY_BYTES {
        return Err(RuntimeError::PlanContract(format!(
            "an admission key of {} bytes exceeds the {MAX_ADMISSION_KEY_BYTES}-byte \
             limit — the key is chosen by the emitter and becomes part of a storage \
             key, so its size is not theirs to decide",
            key.len()
        )));
    }
    Ok(())
}

/// The run id a store named as an admission key's holder.
///
/// An unparseable holder is corruption in a derived index. Refused rather than
/// admitted around: "the index is unreadable" is not evidence the key is free.
fn parse_holder(run: &str) -> Result<RunId, RuntimeError> {
    RunId::parse(run).map_err(|e| {
        RuntimeError::PlanContract(format!(
            "an admission key is held by run '{run}', which does not parse ({e}) — refusing rather than admitting a second run under a key whose holder this build cannot read"
        ))
    })
}

/// What a run's history says its state is, if it says anything.
///
/// **One reader, for every surface that answers the question.** Idempotent
/// admission, the operator API and the A2A projection are three views of one
/// fact, and three copies of this match agree right up until somebody adds a
/// record kind or a conclusion arrives that this build cannot read — after
/// which a caller polling and the same caller streaming are told different
/// things about one run, which is worse than either answer being wrong. The
/// laxest copy is the one that decides what an operator sees, so there is one.
///
/// `None` means the run is still going: the last record is neither a suspension
/// nor a conclusion. It is not this function's business whether that means
/// *running* or *never existed* — an empty history answers `None` too, and the
/// caller knows which it asked for.
///
/// **The last record, not any record.** A run that waited, was resumed and
/// carried on has a suspension in its history and is not suspended now.
pub(crate) fn observed_status(records: &[Record]) -> Option<RunStatus> {
    Some(match records.last()?.kind() {
        RecordKind::RunSuspended { reason } => RunStatus::Suspended(reason.clone()),
        RecordKind::RunConcluded {
            outcome,
            reason,
            exhaustion,
            ..
        } => recorded_status(outcome, reason.as_deref(), exhaustion.as_ref(), records),
        _ => return None,
    })
}

/// A sealed run's status, rebuilt from its recorded conclusion.
///
/// Distinct from `resume_is_closed`, which asks the narrower *may this run be
/// resumed* and returns `None` for the conclusions that stay resumable. Every
/// conclusion has an answer here: a failed run reported as "still working"
/// would send a redelivery into a second admission.
fn recorded_status(
    outcome: &str,
    reason: Option<&str>,
    exhaustion: Option<&crate::core::BudgetExceeded>,
    records: &[Record],
) -> RunStatus {
    // A conclusion that carries no reason gets a statement of that fact rather
    // than an empty string: the empty summary is what `RunStatus::reason`
    // exists to prevent, and this is the surface a retried delivery reads.
    let said = || {
        reason.map_or_else(
            || "concluded without a recorded reason".to_owned(),
            ToOwned::to_owned,
        )
    };
    match outcome {
        "succeeded" => RunStatus::Succeeded,
        "failed" => RunStatus::Failed(said()),
        "replanning" => RunStatus::Replanning(said()),
        "exhausted" => exhaustion.cloned().map_or_else(
            || {
                RunStatus::Quarantined(
                    "recorded as exhausted without the typed ceiling verdict".to_owned(),
                )
            },
            RunStatus::Exhausted,
        ),
        "quarantined" => RunStatus::Quarantined(said()),
        "cancelled" => recorded_cancellation(records).map_or_else(
            || RunStatus::Quarantined(UNATTRIBUTED.to_owned()),
            |(actor, reason)| RunStatus::Cancelled { actor, reason },
        ),
        "abandoned" => recorded_abandonment(records).map_or_else(
            || RunStatus::Quarantined(UNATTRIBUTED.to_owned()),
            |(actor, reason)| RunStatus::Abandoned { actor, reason },
        ),
        // A withdrawal, read from the record that holds both halves. Without
        // this arm the catch-all answered *quarantined, and this build does
        // not recognise 'withheld'* — the plane calling its own record
        // foreign, on the surface an operator uses to decide whether to lift a
        // halt or to cancel.
        WITHHELD_OUTCOME => recorded_withholding(records).map_or_else(
            || RunStatus::Quarantined(UNATTRIBUTED.to_owned()),
            |(subject, reason)| RunStatus::Withheld { subject, reason },
        ),
        super::sweeper::SWEEP_OUTCOME => RunStatus::Swept,
        // Read back as itself, like every other ending this build writes. The
        // catch-all below would answer `Quarantined` — this plane calling its
        // own record foreign, on a run whose whole point is that somebody else
        // ran it.
        OBSERVED_OUTCOME => RunStatus::Observed,
        BREAK_GLASS_OUTCOME => recorded_crossing(records).map_or_else(
            || RunStatus::Quarantined(UNATTRIBUTED.to_owned()),
            |(actor, reason)| RunStatus::BrokeGlass { actor, reason },
        ),
        HALT_LIFTED_OUTCOME => recorded_halt_lift(records).map_or_else(
            || RunStatus::Quarantined(UNATTRIBUTED.to_owned()),
            |actor| RunStatus::HaltLifted { actor },
        ),
        HOLD_RELEASED_OUTCOME => recorded_hold_release(records).map_or_else(
            || RunStatus::Quarantined(UNATTRIBUTED.to_owned()),
            |actor| RunStatus::HoldReleased { actor },
        ),
        // Fail closed, as the resume path does: a conclusion this build cannot
        // interpret is not permission to treat the run as ordinary. Every
        // outcome this build *writes* has an arm above, and a guard holds the
        // two lists together — an ending answered here as unrecognised would be
        // this plane calling its own record foreign, and the surface it reaches
        // is the one an operator uses to read a break-glass crossing.
        other => RunStatus::Quarantined(format!(
            "recorded as '{other}', which this build does not recognise"
        )),
    }
}

/// Whether this value is a sealed payload rather than a readable one.
///
/// Always false without `keyring`: nothing seals, so nothing can be sealed, and
/// a build with no key ring must not carry a dependency on the module that
/// defines the wrapper.
fn sealed_payload(value: &serde_json::Value) -> bool {
    #[cfg(feature = "keyring")]
    {
        crate::journal::payload::is_sealed(value)
    }
    #[cfg(not(feature = "keyring"))]
    {
        let _ = value;
        false
    }
}

/// How the run's history says it last ended, or that it is waiting.
///
/// The last conclusion or suspension on the record, as the outcome word a
/// replay's own status reports, so the two compare directly. `None` for a run
/// that has neither: it is still in flight, and a strict replay of it would
/// stop at its frontier and call that divergence.
fn recorded_ending(records: &[Record]) -> Option<String> {
    records.iter().rev().find_map(|r| match r.kind() {
        RecordKind::RunConcluded { outcome, .. } => Some(outcome.clone()),
        RecordKind::RunSuspended { .. } => Some("suspended".to_owned()),
        _ => None,
    })
}

/// Whether an ending was an act rather than something the run's steps reached.
///
/// A cancellation, an abandonment, a sweep, a break-glass crossing, a lift, a
/// withdrawal and an observation are each recorded by whoever took them; a
/// strict replay re-derives steps, and no step decided these.
fn ended_by_an_act(outcome: &str) -> bool {
    matches!(outcome, "cancelled" | "abandoned")
        || [
            super::sweeper::SWEEP_OUTCOME,
            BREAK_GLASS_OUTCOME,
            HALT_LIFTED_OUTCOME,
            HOLD_RELEASED_OUTCOME,
            WITHHELD_OUTCOME,
            OBSERVED_OUTCOME,
        ]
        .contains(&outcome)
}

/// The plan the run was admitted under, and each successor a replan produced,
/// oldest first. Read back rather than recompiled, which could produce a graph
/// that never governed the run.
///
/// All or nothing. Successors are walked by position, so skipping one this
/// build cannot read would put every later replan on the wrong plan.
///
/// # Errors
///
/// [`RuntimeError::PayloadsErased`] when a plan is still sealed, named before
/// it is parsed: a sealed payload deserialises into a *missing field*, and that
/// sentence sends an operator looking for a corrupt journal rather than telling
/// them the data was erased on request.
fn frozen_plans(run: RunId, records: &[Record]) -> Result<(PlanIR, Vec<PlanIR>), RuntimeError> {
    let mut plans = records
        .iter()
        .filter_map(|r| match r.kind() {
            RecordKind::PlanFrozen { plan, .. } => Some(plan),
            _ => None,
        })
        .map(|plan| {
            if sealed_payload(plan) {
                return Err(RuntimeError::PayloadsErased {
                    run: run.to_string(),
                });
            }
            serde_json::from_value(plan.clone()).map_err(RuntimeError::Encoding)
        })
        .collect::<Result<Vec<PlanIR>, _>>()?
        .into_iter();
    let admitted = plans
        .next()
        .ok_or_else(|| RuntimeError::PlanContract("journal has no PlanFrozen record".into()))?;
    Ok((admitted, plans.collect()))
}

/// Whether this run's history is sealed to a key that no longer exists.
///
/// Read from the frozen plan, which every admitted run has and which is sealed
/// under the run's own erasure scope — so it is gone exactly when the run's
/// data is gone. Checking a payload rather than asking the key ring keeps this
/// a property of the records in hand: the same answer offline, on a restored
/// copy, and in a build with no ring wired.
fn payloads_erased(records: &[Record]) -> bool {
    records.iter().any(|r| match r.kind() {
        RecordKind::PlanFrozen { plan, .. } => sealed_payload(plan),
        _ => false,
    })
}

/// Who asked for the stop, read back from the chain.
///
/// Read rather than remembered, for the same reason every other fact about a run
/// is: the journal gives the same answer on every subsequent read, and an
/// operator asking "who stopped this?" six weeks later is asking history.
///
/// **Both halves, from the one record that holds them.** The conclusion does
/// not repeat the reason — see [`RecordKind::RunConcluded`]'s `reason` for why
/// a second copy of it would be the worse copy.
fn recorded_cancellation(records: &[Record]) -> Option<(crate::core::Operator, String)> {
    records.iter().rev().find_map(|r| match r.kind() {
        RecordKind::RunCancelled { actor, reason } => Some((actor.clone(), reason.clone())),
        _ => None,
    })
}

/// Who answered the quarantine and what they said, read back from the chain.
fn recorded_abandonment(records: &[Record]) -> Option<(crate::core::Operator, String)> {
    records.iter().rev().find_map(|r| match r.kind() {
        RecordKind::QuarantineDecided {
            decider, reason, ..
        } => Some((decider.clone(), reason.clone())),
        _ => None,
    })
}

/// Who crossed into this tenant and why, read back from the chain.
fn recorded_crossing(records: &[Record]) -> Option<(crate::core::Operator, String)> {
    records.iter().rev().find_map(|r| match r.kind() {
        RecordKind::BreakGlass { actor, reason, .. } => Some((actor.clone(), reason.clone())),
        _ => None,
    })
}

/// Who lifted the halt this run records, read back from its lift record.
fn recorded_halt_lift(records: &[Record]) -> Option<crate::core::Operator> {
    records.iter().rev().find_map(|r| match r.kind() {
        RecordKind::HaltLifted { by, .. } => Some(by.clone()),
        _ => None,
    })
}

/// Who released the hold this run records, read back from its release record.
fn recorded_hold_release(records: &[Record]) -> Option<crate::core::Operator> {
    records.iter().rev().find_map(|r| match r.kind() {
        RecordKind::HoldReleased { by, .. } => Some(by.clone()),
        _ => None,
    })
}

/// Whose authority was withdrawn, and what the operator said when withdrawing
/// it — read back from the withholding record.
///
/// The last one standing: a withdrawal may be lifted and thrown again within a
/// run's history, and the conclusion is about the one that stopped it.
fn recorded_withholding(records: &[Record]) -> Option<(String, String)> {
    records.iter().rev().find_map(|r| match r.kind() {
        RecordKind::AuthorityWithheld {
            subject, reason, ..
        } => Some((subject.clone(), reason.clone())),
        _ => None,
    })
}

/// Wall-clock read for the case's `opened_at` stamp, and for a rate
/// reservation's instant.
///
/// Admission happens before any step exists, so there is no `StepCtx` to
/// journal through. Both values are store metadata and never participate in
/// replay: a rate refusal is journaled on the run and read back, never
/// re-counted — run-visible time still goes through `StepCtx::now`, which
/// journals it.
#[allow(clippy::disallowed_methods)]
pub(super) fn now_for_admission() -> crate::core::Timestamp {
    crate::core::Timestamp::now_utc()
}

/// A lift was recorded in `run` and the register's row was not removed.
///
/// The control still stands; the operator is told the lift failed and which
/// run recorded the attempt.
fn removal_failed(run: RunId, e: &crate::core::StoreError) -> RuntimeError {
    RuntimeError::ControlStands {
        run: run.to_string(),
        detail: e.to_string(),
    }
}

/// An operator's lift or release that found a control standing and recorded
/// ending it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ControlLifted {
    /// The run holding the record.
    pub record: RunId,
    /// Whether this call removed the register row. `false` when another lift
    /// or release removed it between this call's read and its removal: the
    /// control is gone either way, and the record still stands.
    pub removed: bool,
}

/// The epoch an operator act's own run is written under.
///
/// Such a run has no competing writer to fence against — it is created,
/// written and sealed in one call — so a constant is honest here for the same
/// reason it is in the sweeper.
const BREAK_GLASS_EPOCH: crate::core::Epoch = LEASE_FREE_EPOCH;

/// How a break-glass run ends. Not a run status: it neither succeeded nor
/// failed at a goal, which is why a sweep seals as `swept` rather than
/// borrowing one.
const BREAK_GLASS_OUTCOME: &str = "broke-glass";

/// How a run recording an operator lifting a halt ends.
pub const HALT_LIFTED_OUTCOME: &str = "halt-lifted";

/// How a run recording an operator releasing a legal hold ends.
pub const HOLD_RELEASED_OUTCOME: &str = "hold-released";

/// How a run ends when the authority it acts under is withdrawn under it.
///
/// Resumable, so it is deliberately absent from both
/// [`SEALED_OUTCOMES`] and [`OUTCOMES_OF_RECORD`]: the run has not ended, it is
/// waiting for somebody to lift a halt or to cancel it properly.
pub const WITHHELD_OUTCOME: &str = "withheld";

/// The outcome a session this plane only **observed** is sealed under.
///
/// Its own word, and not `succeeded`: a session this runtime did not execute
/// has no success to report, and answering with one would put somebody else's
/// agent's work in the column an operator reads as *this plane did it*. The
/// distinction is the whole reason the status exists.
pub const OBSERVED_OUTCOME: &str = "observed";

/// The epoch every run written without a lease is written under: a sweep's
/// record, an operator act's, an observed session's. Nothing takes such a run
/// over, so there is no ownership for the epoch to arbitrate, and one constant
/// lets the pass that finishes their seals use the epoch they were written at.
pub(crate) const LEASE_FREE_EPOCH: crate::core::Epoch = 1;

/// The sealing outcomes whose runs are written without a lease.
///
/// Recovery selects a run by its lapsed lease, so it never finds one of these
/// whose writer died between conclusion and seal;
/// [`Runtime::seal_unsealed_conclusions`] is what finishes them.
pub(crate) const LEASE_FREE_OUTCOMES: &[&str] = &[
    super::sweeper::SWEEP_OUTCOME,
    BREAK_GLASS_OUTCOME,
    HALT_LIFTED_OUTCOME,
    HOLD_RELEASED_OUTCOME,
    OBSERVED_OUTCOME,
];

/// One governed identity: a declaration and the skills that serve it.
///
/// A runtime **runs** agents; it is not one. It owns the journal, the stores,
/// the model drivers and the policy engine — infrastructure, shared. An agent
/// owns a manifest and its skills — governance, per-identity. Several agents on
/// one plane share a journal and are still separately declared, separately
/// bounded, and separately answerable.
///
/// Conflating the two forced a runtime per agent, which meant a lease owner per
/// agent for what is one process, a model driver registered once per agent, and
/// nowhere in the journal to record *which* agent governed a run.
#[cfg(feature = "manifest")]
#[derive(Debug, Default)]
pub struct Agent {
    manifest: Option<Arc<crate::manifest::Manifest>>,
    /// Who vouched for the declaration, when it came from a verified resolution.
    publisher: Option<crate::core::KeyId>,
    skills: Vec<Arc<dyn Skill>>,
}

#[cfg(feature = "manifest")]
impl Agent {
    /// An agent governed by this declaration.
    ///
    /// Nobody has vouched for it. Prefer [`Agent::published_by`] where the
    /// manifest came from a verified registry resolution.
    #[must_use]
    pub fn new(manifest: &crate::manifest::Manifest) -> Self {
        Self {
            manifest: Some(Arc::new(manifest.clone())),
            publisher: None,
            skills: Vec::new(),
        }
    }

    /// Record who vouched for this declaration.
    ///
    /// Takes the [`KeyId`](crate::core::KeyId) that
    /// [`Registry::resolve_verified`](crate::manifest::Registry::resolve_verified)
    /// returned beside the manifest — which is otherwise dropped on the floor,
    /// so a verified resolution and a parsed file become indistinguishable the
    /// moment they reach the runtime.
    ///
    /// # Why this is the grouping a policy wants
    ///
    /// A rule has to name *a set of agents*, and the obvious candidates do not
    /// survive contact with a deployment:
    ///
    /// * the **workload identity** is per-instance, so a rule naming one is a
    ///   rule rewritten on every deploy;
    /// * the agent **name**, its **role**, or any group label in the manifest is
    ///   self-asserted — a file claims it, so a rule granting authority to one
    ///   grants it to any file that types the same string;
    /// * the **digest** is unforgeable but names exactly one revision, so every
    ///   edit is a policy change.
    ///
    /// A publisher key is the only one that is both a group — many agents, many
    /// versions — and impossible to claim without holding the key. Bind the rule
    /// to the publisher, keep the digest for "this exact revision", and leave
    /// the name for humans reading logs.
    #[must_use]
    pub fn published_by(mut self, key_id: impl Into<crate::core::KeyId>) -> Self {
        self.publisher = Some(key_id.into());
        self
    }

    /// Give it a skill.
    #[must_use]
    pub fn skill(mut self, skill: impl Skill + 'static) -> Self {
        self.skills.push(Arc::new(skill));
        self
    }
}

/// Receives every model call's live output, with the run it belongs to.
///
/// What [`ModelStreamObserver`](crate::model::ModelStreamObserver) receives for
/// one call, for every call a plane makes — so a surface can show a run's model
/// writing while the journal holds only the finished answer.
pub trait RunStreamObserver: Send + Sync + std::fmt::Debug {
    /// Delivery is advisory and must not block the call.
    fn event(&self, run: RunId, event: Tainted<crate::model::ModelStreamEvent>);
}

/// Assembles a [`Runtime`].
#[derive(Debug)]
pub struct RuntimeBuilder {
    store: Arc<dyn JournalStore>,
    /// The witnesses this plane submits checkpoints to, and the bar a round
    /// is held to. Both or neither: a witness list with no declared quorum is
    /// witnessing whose evidence is whatever happened to arrive.
    witnesses: Vec<Arc<dyn crate::journal::Witness>>,
    quorum: Option<crate::journal::WitnessQuorum>,
    witness_interval: Option<std::time::Duration>,
    signer: Option<Arc<dyn crate::core::Signer>>,
    skills: Vec<Arc<dyn Skill>>,
    #[cfg(feature = "manifest")]
    tools: Option<(
        Arc<crate::tools::ToolCatalog>,
        Arc<dyn crate::tools::ToolClient>,
    )>,
    #[cfg(feature = "manifest")]
    egress: Option<Arc<crate::core::Egress>>,
    #[cfg(feature = "manifest")]
    checkers: crate::content::Checkers,
    streams: Option<Arc<dyn RunStreamObserver>>,
    journal_ceiling: Option<crate::core::Sensitivity>,
    tenant: crate::core::TenantId,
    owner: Option<String>,
    lease_ttl: Duration,
    memories: Option<Arc<dyn crate::memory::MemoryStore>>,
    semantic: Option<Arc<super::SemanticMemory>>,
    authorities: Option<Arc<dyn crate::authority::AuthorityStore>>,
    peers: Option<Arc<PeerWiring>>,
    tenant_label: super::telemetry::TenantLabel,
    quotas: Option<Arc<dyn crate::quota::QuotaStore>>,
    quota: crate::quota::TenantQuota,
    budget: Budget,
    require_verifier: bool,
    /// Typed tools whose coherence with every agent is checked at `build`.
    #[cfg(feature = "manifest")]
    toolbox: Option<crate::tools::ToolBox>,
    /// Tool servers reached by some transport other than the box, by name.
    #[cfg(feature = "manifest")]
    tool_servers: Vec<(String, Arc<dyn crate::tools::ToolClient>)>,
    /// Agents registered on this plane, each with its own declaration.
    #[cfg(feature = "manifest")]
    agents: Vec<Agent>,
    /// Drivers by the name a manifest calls them.
    #[cfg(feature = "manifest")]
    providers: HashMap<String, Arc<dyn crate::model::ModelProvider>>,
    cases: Option<Arc<dyn CaseStore>>,
    events: Option<Arc<dyn EventStore>>,
    tasks: Option<Arc<dyn TaskStore>>,
    timers: Option<Arc<dyn TimerStore>>,
    blobs: Option<Arc<dyn crate::blob::BlobStore>>,
    disclosures: Option<Arc<dyn crate::disclosure::DisclosureRegister>>,
    #[cfg(feature = "push")]
    push: Option<Arc<dyn crate::push::PushStore>>,
    #[cfg(feature = "keyring")]
    keyring: Option<Arc<dyn crate::keyring::KeyRing>>,
    batches: Option<Arc<dyn crate::batch::BatchStore>>,
    policy: Option<Arc<dyn crate::core::PolicyEngine>>,
    identity: Option<crate::core::Delegation>,
    replanner: Option<Arc<dyn crate::plan::Replanner>>,
    calendar: Option<Arc<dyn Calendar>>,
    /// Destinations this deployment sends its own run events to.
    #[cfg(feature = "push")]
    outbox: Option<Arc<crate::push::Outbox>>,
}

impl RuntimeBuilder {
    #[must_use]
    pub fn skill(mut self, s: impl Skill) -> Self {
        self.skills.push(Arc::new(s));
        self
    }

    /// The workload identity this plane signs its outward claims with.
    ///
    /// What it buys is that a tool or peer can *check* who called it. Without a
    /// signer the provenance block still travels — a server can correlate on it
    /// — but it is an assertion any intermediary could have written, and a
    /// callee must not authorize on it.
    ///
    /// Give the store the same signer ([`signing_as`] there) so records and
    /// outward claims carry one identity. They are separate settings because a
    /// plane can legitimately have one without the other.
    ///
    /// [`signing_as`]: crate::store::RedbStore::signing_as
    #[must_use]
    pub fn signing_as(mut self, signer: Arc<dyn crate::core::Signer>) -> Self {
        self.signer = Some(signer);
        self
    }

    /// How long this plane's run leases last.
    ///
    /// The trade is recovery speed against tolerance for a slow instance: a
    /// crashed owner's runs stay unclaimable for this long, and a live owner
    /// must renew within it. The runtime heartbeats while a run executes, so
    /// this bounds *crash* detection rather than how long a run may take.
    ///
    /// A TTL below [`MIN_LEASE_TTL`] is refused at
    /// [`build`](Self::build)/[`try_build`](Self::try_build) as
    /// [`BuildError::LeaseUnrenewable`](crate::runtime::BuildError::LeaseUnrenewable).
    /// Both stores keep lease expiry in **whole seconds** and treat
    /// `expires_at <= now` as lapsed, so a one-second lease expires the moment
    /// the clock ticks past the second it was written in — no matter how often
    /// it is renewed. Such a lease cannot be held by a live run, and a run that
    /// cannot hold its lease is one any instance may take away mid-flight.
    /// Refused where a manifest-serving plane can report it as a diagnostic
    /// rather than left as a panic in a setter, which `try_build`'s callers
    /// could never see as a value.
    #[must_use]
    pub fn lease_ttl(mut self, ttl: Duration) -> Self {
        self.lease_ttl = ttl;
        self
    }

    /// Put this plane's tenant on what it reports about itself.
    ///
    /// Off by default, and one policy for both signals: the `tenant` field of
    /// every metric event, and `agentplane.tenant` on the run span. Read
    /// [`telemetry::TenantLabel`](super::telemetry::TenantLabel) before turning
    /// it on — a tenant name is often a customer name, and an observability
    /// backend is usually the least protected system in a deployment.
    ///
    /// Cardinality is bounded by construction — the label is *this plane's*
    /// tenant, so the number of streams is the number of planes configured, and
    /// no request can grow it.
    #[must_use]
    pub const fn tenant_label(mut self, label: super::telemetry::TenantLabel) -> Self {
        self.tenant_label = label;
        self
    }

    /// Give this plane's agents a memory.
    ///
    /// Optional, and absent by default: an agent with no memory is a normal
    /// agent, and one that quietly gained persistent state because a store was
    /// wired for something else would be a surprise.
    ///
    /// Read [`crate::memory`] before wiring one. Writable memory is delayed
    /// code: what is written today is read into a context window tomorrow, where
    /// a model treats it as established fact.
    #[must_use]
    pub fn memory(mut self, memories: Arc<dyn crate::memory::MemoryStore>) -> Self {
        self.memories = Some(memories);
        self
    }

    /// Give this plane a semantic index, and the embedder that speaks its
    /// language.
    ///
    /// Both together, never one at a time: `build` holds
    /// [`Embedder::revision`] to the [`IndexIdentity::query_revision`] the
    /// index declares it accepts, and refuses the pair otherwise
    /// ([`BuildError::EmbeddingSpaceMismatch`] says what a mismatch costs).
    ///
    /// Also needs [`memory`](Self::memory): the index holds only commitments,
    /// and every hit is materialised from the authoritative store before its
    /// content is exposed.
    ///
    /// [`Embedder::revision`]: crate::memory::Embedder::revision
    /// [`IndexIdentity::query_revision`]: crate::memory::IndexIdentity::query_revision
    /// [`BuildError::EmbeddingSpaceMismatch`]: crate::runtime::BuildError::EmbeddingSpaceMismatch
    #[must_use]
    pub fn semantic_memory(
        mut self,
        embedder: Arc<dyn crate::memory::Embedder>,
        retriever: Arc<dyn crate::memory::SemanticRetriever>,
    ) -> Self {
        self.semantic = Some(Arc::new(super::SemanticMemory {
            embedder,
            retriever,
        }));
        self
    }

    /// Whether the plane's budget, or any registered agent's, caps money.
    fn states_a_money_ceiling(&self) -> bool {
        #[cfg(feature = "manifest")]
        if self
            .agents
            .iter()
            .filter_map(|agent| agent.manifest.as_ref())
            .any(|manifest| manifest.budget().max_minor_units.is_some())
        {
            return true;
        }
        self.budget.max_minor_units.is_some()
    }

    /// Attach durable standing-authority accounting.
    ///
    /// The ceiling neither of the other two can express. A budget bounds one
    /// run; a quota bounds a tenant over a billing period. A standing authority
    /// bounds *an authorization* — what one customer approved, spanning as many
    /// runs as it takes, revocable when they change their mind.
    ///
    /// Without one, [`StepCtx::draw`](crate::runtime::StepCtx::draw) refuses
    /// rather than falling back to an in-process counter. That fallback would
    /// fail **open** the moment a second instance started, which is exactly when
    /// a shared ceiling was needed.
    #[must_use]
    pub fn authorities(mut self, authorities: Arc<dyn crate::authority::AuthorityStore>) -> Self {
        self.authorities = Some(authorities);
        self
    }

    /// Bound what this tenant may consume, durably.
    ///
    /// Budgets bound one run; this bounds the tenant. Both are needed: a caller
    /// that can start runs can start a thousand, each within its own ceiling.
    ///
    /// The accounting lives in the store, so the ceiling survives a second
    /// instance — an in-process counter would silently double the moment
    /// somebody scales out, which is exactly when it was needed.
    ///
    /// Read [`crate::quota`] for what each ceiling does and does not bound; a
    /// limit believed to bound something it does not is worse than none.
    #[must_use]
    pub fn quota(
        mut self,
        quotas: Arc<dyn crate::quota::QuotaStore>,
        quota: crate::quota::TenantQuota,
    ) -> Self {
        self.quotas = Some(quotas);
        self.quota = quota;
        self
    }

    /// This **process instance's** identity, as it appears in run leases.
    ///
    /// Not the agent's name, and the distinction is load-bearing. A lease is
    /// renewed without bumping the epoch when the holder is *the same owner*, so
    /// two processes sharing an owner string each read the other's lease as
    /// their own: no fencing, no epoch bump, and two writers on one run. That is
    /// precisely the failure the epoch exists to prevent.
    ///
    /// So it must be unique per running process, which is what the default is —
    /// override it only if you have a better instance identity than a random
    /// one, such as a pod name. An agent's *name* is
    /// [`Manifest::metadata`](crate::manifest::Metadata::name); several
    /// instances of one agent are normal and must not share this.
    ///
    /// The owner lives in the lease table and never in the chain, so it has no
    /// bearing on replay.
    #[must_use]
    pub fn owner(mut self, o: impl Into<String>) -> Self {
        self.owner = Some(o.into());
        self
    }

    /// Cap what a run may consume.
    ///
    /// Defaults to [`Budget::unlimited`], which is right for a runtime whose
    /// effects are all free and local, and wrong the moment one of them calls a
    /// metered API.
    #[must_use]
    pub fn budget(mut self, budget: Budget) -> Self {
        self.budget = budget;
        self
    }

    /// Refuse a plan in which nothing checks the work.
    ///
    /// A node that declares [`verifies`](crate::core::PlanNode::verifies) must
    /// already depend on what it checks; this makes carrying one a condition of
    /// admission. It binds every plan this runtime validates, and the one that
    /// matters is the one the embedder did not write: a
    /// [`Replanner`](crate::plan::Replanner)'s successor is a graph proposed
    /// mid-run, and a control that held for the first plan and not for its
    /// replacement is a control a replan removes.
    #[must_use]
    pub fn require_verifier(mut self) -> Self {
        self.require_verifier = true;
        self
    }

    /// Attach long-lived case storage, enabling correlation and deadlines.
    #[must_use]
    pub fn cases(mut self, cases: Arc<dyn CaseStore>) -> Self {
        self.cases = Some(cases);
        self
    }

    /// Send this plane's own events to destinations the deployment configured.
    ///
    /// Every run registers each destination **at admission**, so there is no
    /// window in which a run exists and nothing is watching it. Delivery is a
    /// separate, operator-scheduled sweep — see
    /// [`DeliveryWorker`](crate::push::DeliveryWorker) — reading each run's
    /// journal past a cursor that advances only on 2xx.
    ///
    /// This is the mirror image of A2A push, and the mirror is the point: there
    /// the *caller* names a URL and three controls exist because of it. Here the
    /// deployment names it, and the run's own history is the outbox rather than
    /// a queue that can fall out of sync with it.
    #[cfg(feature = "push")]
    #[must_use]
    pub fn outbox(mut self, outbox: Arc<crate::push::Outbox>) -> Self {
        self.outbox = Some(outbox);
        self
    }

    /// Attach the webhook registration store.
    ///
    /// The same handle the A2A server and the [`Outbox`](crate::push::Outbox)
    /// are given: this is the *durable* half of push, and it belongs to the
    /// plane because its failures do. A receiver that answers permanently, or
    /// stays silent past the retry ceiling, has its registration
    /// [parked](crate::push::PushStore::park) rather than deleted — the cursor
    /// is the only record of how far that receiver got — and a parked row is a
    /// backlog an operator reads and re-arms on the operator API. Without this
    /// the plane serves the delivery and cannot answer for it.
    #[cfg(feature = "push")]
    #[must_use]
    pub fn push(mut self, push: Arc<dyn crate::push::PushStore>) -> Self {
        self.push = Some(push);
        self
    }

    /// Attach inbound-event storage, enabling durable waits.
    #[must_use]
    pub fn events(mut self, events: Arc<dyn EventStore>) -> Self {
        self.events = Some(events);
        self
    }

    /// Attach a worklist, enabling human tasks.
    #[must_use]
    pub fn tasks(mut self, tasks: Arc<dyn TaskStore>) -> Self {
        self.tasks = Some(tasks);
        self
    }

    /// Supply the planner that produces successor plans.
    ///
    /// Without one, a step asking to replan fails with that as the reason —
    /// which is the honest outcome, not a silent no-op.
    #[must_use]
    pub fn replanner(mut self, r: Arc<dyn crate::plan::Replanner>) -> Self {
        self.replanner = Some(r);
        self
    }

    /// Supply the durable-timer store.
    ///
    /// Needed by `StepCtx::sleep` and `sleep_until`, and by the sweep that wakes
    /// them. A runtime without one refuses to sleep rather than falling back to
    /// an in-process wait that a restart would forget.
    #[must_use]
    pub fn timers(mut self, timers: Arc<dyn TimerStore>) -> Self {
        self.timers = Some(timers);
        self
    }

    /// Register an agent on this plane.
    ///
    /// A runtime runs agents; it is not one. This is where a declaration and
    /// its skills arrive together, so several agents can share one journal, one
    /// set of drivers and one process identity while each stays separately
    /// governed.
    ///
    /// The declaration **binds** for that agent's steps: an effect naming a
    /// model or tool its manifest never listed is refused before dispatch and
    /// journaled, and the egress and delegation ceilings combine with the sink's
    /// own — the stricter wins. Its budget bounds its runs. Architectural
    /// injection patterns are deliberately absent from the schema, because this
    /// runtime cannot prove that arbitrary skill code follows one.
    ///
    /// An agent declaring `spec.execution` needs no skill: the runtime supplies
    /// the behaviour. See [`provider`](Self::provider) for the driver mapping it
    /// needs.
    ///
    /// It does **not** set the lease owner. That identifies a *process*, and one
    /// plane running four agents is still one process — see
    /// [`owner`](Self::owner).
    ///
    /// # This call never fails
    ///
    /// It records the agent and returns. Every refusal an agent can cause — a
    /// capability none of its skills provide, a provider no driver is registered
    /// for, oversight with nowhere to put a decision — is raised at
    /// [`build`](Self::build), which panics, or returned by
    /// [`try_build`](Self::try_build), which does not.
    ///
    /// That split matters for a daemon assembling a plane from files it did not
    /// write: a bad manifest is an *input* there, and a panic takes down every
    /// other tenant in the process to report it. A `# Panics` section here,
    /// describing `build`'s refusals, would send readers looking for a
    /// fallible variant of the wrong call — the refusals are documented where
    /// they fire.
    #[cfg(feature = "manifest")]
    #[must_use]
    pub fn agent(mut self, agent: Agent) -> Self {
        self.agents.push(agent);
        self
    }

    /// Register a model driver under the name a manifest uses for it.
    ///
    /// The seam a declarative agent needs. A manifest says `provider: anthropic`
    /// — a string a reviewer can read — and something has to map that to a
    /// driver holding a credential. That mapping is deployment wiring, not a
    /// property of the agent, which is exactly why it lives here and not in the
    /// file: an agent's declaration should not change when its API key does.
    ///
    /// Required only for [`ExecutionKind::Completion`] and the other declarative
    /// kinds. A hand-written skill constructs its own `ModelCall` and never
    /// consults this.
    ///
    /// [`ExecutionKind::Completion`]: crate::manifest::ExecutionKind::Completion
    #[cfg(feature = "manifest")]
    #[must_use]
    pub fn provider(
        mut self,
        name: impl Into<String>,
        provider: Arc<dyn crate::model::ModelProvider>,
    ) -> Self {
        self.providers.insert(name.into(), provider);
        self
    }

    /// Supply content-addressed blob storage.
    ///
    /// Needed by `StepCtx::store_blob`, which is how bytes too large for a
    /// journal record get somewhere durable while the chain keeps only their
    /// digest. A runtime without one refuses rather than silently inlining
    /// megabytes into an append-only chain that can never take them back.
    #[must_use]
    pub fn blobs(mut self, blobs: Arc<dyn crate::blob::BlobStore>) -> Self {
        self.blobs = Some(blobs);
        self
    }

    /// Where disclosures of a matter are recorded, so a retention pass names
    /// the copies of what it erased.
    #[must_use]
    pub fn disclosures(mut self, register: Arc<dyn crate::disclosure::DisclosureRegister>) -> Self {
        self.disclosures = Some(register);
        self
    }

    /// The operator's tool catalogue, and the client that reaches those tools.
    ///
    /// Required by a `tool-calling` agent and by nothing else: a skill that
    /// calls tools builds its own [`ToolCall`](crate::tools::ToolCall), because
    /// it knows which client it means. A declarative agent has no code to make
    /// that choice, so the plane makes it once.
    ///
    /// The catalogue is the authority. A manifest grants a subset of it, the
    /// model is offered exactly that subset, and a name the model returns is
    /// matched against it byte for byte.
    #[cfg(feature = "manifest")]
    #[must_use]
    pub fn tools(
        mut self,
        catalog: Arc<crate::tools::ToolCatalog>,
        client: Arc<dyn crate::tools::ToolClient>,
    ) -> Self {
        self.tools = Some((catalog, client));
        self
    }

    /// Typed tools, with their catalogue derived and their coherence enforced.
    ///
    /// The one-call form, and the reason it exists is not brevity. Deriving the
    /// catalogue and checking it against every agent's manifest were both
    /// possible before and both **optional**, and a control a caller may forget
    /// is not a control — it is advice that reads like one.
    ///
    /// So this does three things that were three things:
    ///
    /// * derives the catalogue from each agent's declaration, so a grant, its
    ///   ceiling and its protected fields are stated once;
    /// * refuses to build if the tools this binary implements and the manifests
    ///   a reviewer approved have drifted apart;
    /// * wires the box as the client.
    ///
    /// The work happens in [`build`](Self::build) rather than here, and that is
    /// the whole reason it is trustworthy: checking on this call would check
    /// against the agents registered *so far*, so `.toolbox(..).agent(..)` would
    /// pass by having nothing to disagree with. An enforcement that depends on
    /// the order a builder was written is not one.
    #[cfg(feature = "manifest")]
    #[must_use]
    pub fn toolbox(mut self, tools: crate::tools::ToolBox) -> Self {
        self.toolbox = Some(tools);
        self
    }

    /// A tool server this plane reaches over some transport of its own.
    ///
    /// An MCP connection is the usual one. Registering it does three things:
    ///
    /// * a plane may reach **several** servers, because the router resolves the
    ///   `tool://server/name` a grant carries rather than handing every id to one
    ///   client;
    /// * typed in-process tools and remote servers can be used by the *same*
    ///   agent, which is the ordinary shape;
    /// * a grant naming a server nobody wired is refused at build, in the same
    ///   breath as a grant nothing implements — both mean the model would be
    ///   offered a tool that fails when chosen.
    ///
    /// Composes with [`toolbox`](Self::toolbox); the box answers for the servers
    /// its own tools name and these answer for theirs. A server claimed twice is
    /// a panic, because registration order deciding which transport carries a
    /// call is the defect [`ToolRouter`](crate::tools::ToolRouter) exists to
    /// remove.
    #[cfg(feature = "manifest")]
    #[must_use]
    pub fn tool_server(
        mut self,
        name: impl Into<String>,
        client: Arc<dyn crate::tools::ToolClient>,
    ) -> Self {
        self.tool_servers.push((name.into(), client));
        self
    }

    /// Where this plane's **tool transports** may connect.
    ///
    /// A `ToolClient` is the embedder's code, and the split is the one every
    /// other outbound path here makes: **the client owns the connection, the
    /// plane owns the destination.** A transport says where it goes with
    /// [`ToolClient::destination`](crate::tools::ToolClient::destination), and
    /// this decides whether that is somewhere it may go — before the effect
    /// exists, so nothing leaves, nothing is journaled and nothing is metered.
    ///
    /// A [`Destination::Local`](crate::tools::Destination::Local) transport is
    /// not judged: tools compiled into the binary and a stdio child process
    /// contact no host of this plane's choosing, so there is nothing for an
    /// allowlist to decide. What that does not claim is that the far side
    /// reaches nothing — the same residual a compromised allowlisted endpoint
    /// carries.
    ///
    /// Unset means no egress control on the tool path, spelled the way an
    /// absent policy engine is: by configuring nothing, rather than by
    /// configuring something that looks like a control and is not.
    ///
    /// ```ignore
    /// let plane = Runtime::builder(store)
    ///     .tool_server("tickets", mcp_over_https)
    ///     .egress(Egress::new().allow("mcp.tickets.example"))
    ///     .build();
    /// ```
    #[cfg(feature = "manifest")]
    #[must_use]
    pub fn egress(mut self, egress: crate::core::Egress) -> Self {
        self.egress = Some(Arc::new(egress));
        self
    }

    /// Forward every model call's live output, with the run it belongs to.
    ///
    /// Advisory and live-only: the journal's completion stays the canonical
    /// answer, a replay performs no call and so streams nothing, and an
    /// observer that drops events changes nothing a run does.
    #[must_use]
    pub fn observe_model_streams(mut self, observer: Arc<dyn RunStreamObserver>) -> Self {
        self.streams = Some(observer);
        self
    }

    /// Register a content checker, by its [`name`](crate::content::ContentChecker::name).
    ///
    /// A manifest check naming a checker no builder registered, or mapping a
    /// category the checker does not declare, refuses the build: a declared
    /// check nothing could run is a control a reviewer approved that does not
    /// exist.
    #[cfg(feature = "manifest")]
    #[must_use]
    pub fn content_checker(mut self, checker: Arc<dyn crate::content::ContentChecker>) -> Self {
        Arc::make_mut(&mut self.checkers).insert(checker.name().to_owned(), checker);
        self
    }

    /// The highest sensitivity this plane will write into an append-only record.
    ///
    /// # What this is, and what the key ring is
    ///
    /// Two different answers to *this data must be erasable*, and they compose.
    /// [`keyring`](Self::keyring) is the **seal it** half: payloads become
    /// ciphertext whose key an erasure destroys, which reaches every replica
    /// and every backup at once. This is the **refuse it** half: an argument
    /// more sensitive than the deployment is willing to make permanent is
    /// refused at dispatch, before it reaches the chain.
    ///
    /// The plane-level twin of `spec.security.max_sensitivity_journaled`, for
    /// a plane of hand-written skills that runs under no manifest. The default
    /// is the unsafe one — a journal keeps everything, indefinitely — so a
    /// plane must be able to state the ceiling whether or not it is
    /// declarative. It is an enforcement point at the same gate the manifest's
    /// field reaches, not a warning; where both are present **the stricter
    /// wins**, as a reviewed tool grant may only tighten what the operator's
    /// catalogue allows.
    ///
    /// Absent means no ceiling, spelled the way an absent policy engine is.
    ///
    /// ```ignore
    /// let plane = Runtime::builder(store)
    ///     // Personal data goes in a blob and the chain gets the digest.
    ///     .max_sensitivity_journaled(Sensitivity::Internal)
    ///     .skill(Triage)
    ///     .build();
    /// ```
    #[must_use]
    pub const fn max_sensitivity_journaled(mut self, ceiling: crate::core::Sensitivity) -> Self {
        self.journal_ceiling = Some(ceiling);
        self
    }

    /// Which tenant this plane runs as.
    ///
    /// **One plane, one tenant — but one process, many planes.** A plane is the
    /// unit that is bound to a tenant; serving several is
    /// [`Planes`](crate::api::Planes)' job, and it resolves the plane from the
    /// authenticated caller's tenant rather than from the request, so a handler
    /// cannot reach a store it did not resolve. An unregistered tenant is
    /// refused rather than defaulted.
    ///
    /// The name scopes **data keys**, so one tenant's cryptographic erasure
    /// cannot reach another's bytes, and it reaches the **policy request**, so a
    /// rule can be written per tenant.
    ///
    /// It does **not** scope the store — that is a separate handle, scoped by
    /// `RedbStore::for_tenant` or `PostgresStore::for_tenant`. Two tenants may
    /// share one store, because the tenant is a key component of every row on
    /// both backends rather than a filter. Setting one and not the other is
    /// refused at [`build`](Self::build) rather than discovered later: a plane
    /// whose store is scoped elsewhere works perfectly and writes its runs into
    /// somebody else's keyspace.
    ///
    /// Defaults to `default`, which is a real tenant rather than an absence: the
    /// single-tenant path is then the same code as the multi-tenant one, and a
    /// special "no tenant" case is a second path that would not get tested.
    #[must_use]
    pub fn tenant(mut self, tenant: crate::core::TenantId) -> Self {
        self.tenant = tenant;
        self
    }

    /// Seal payload bytes, and make erasure reach copies deletion cannot.
    ///
    /// With a key ring configured, everything written through
    /// [`StepCtx::blobs`](crate::runtime::StepCtx::blobs) — including
    /// [`store_blob`](crate::runtime::StepCtx::store_blob) and governed media —
    /// is encrypted under a data key belonging to the run's **case**. Erasing
    /// that case destroys the key, so every copy of those bytes becomes
    /// unreadable at once: the live store, the replicas, and every backup ever
    /// taken. Expiring blobs only reaches the first of those.
    ///
    /// The case is the erasure unit because it is already the retention unit —
    /// bytes are linked to their case at write time, and a second, differently
    /// shaped unit for keys would let the two disagree about what an erasure
    /// covered.
    ///
    /// It also seals the stores the plane holds — the journal's payloads, case
    /// state, task proposals and buffered event payloads — at
    /// [`build`](Self::build), so the order they were registered in cannot lose
    /// the guarantee — a store registered after this call is sealed just the
    /// same.
    ///
    /// **Governed memory is the one store this does not reach.**
    /// [`EncryptedMemoryStore`](crate::keyring::EncryptedMemoryStore)
    /// serialises subject erasure against writes and legal-hold changes with a
    /// process-local mutex, so it holds its contract on a single-writer
    /// deployment and nowhere else; wrapping it here would hand that adapter to
    /// an active-active `PostgreSQL` plane, where the mutex coordinates nothing
    /// and the hold race it exists to prevent is the result. Its erasure unit
    /// is one item version (`memory-item/<id>@<version>`) and outlives every
    /// case, so `erase_case` is not the act that reaches it either. Wrap it
    /// yourself, where the deployment's topology is visible:
    ///
    /// ```ignore
    /// let memories = EncryptedMemoryStore::new(inner, keys.clone(), tenant.clone());
    /// Runtime::builder(store).memory(Arc::new(memories)).keyring(keys).build()
    /// ```
    ///
    /// Without one, bytes are stored as given and erasure remains deletion.
    #[cfg(feature = "keyring")]
    #[must_use]
    pub fn keyring(mut self, keyring: Arc<dyn crate::keyring::KeyRing>) -> Self {
        self.keyring = Some(keyring);
        self
    }

    /// Wrap every store a key ring can seal, at **build** time.
    ///
    /// One call, one guarantee. Before this, `keyring` sealed blob payloads
    /// and nothing else — which was honest when blobs were the only sealable
    /// surface and became a trap the moment they were not: a deployer who
    /// configured a key ring would reasonably read it as *this plane is
    /// encrypted* while the journal, the case store, the worklist and the
    /// event buffer stayed in the clear. Five independent wrapping calls is a
    /// control that can be forgotten four times, and forgetting looks exactly
    /// like remembering.
    ///
    /// Wrapped here rather than inside `keyring()` for the reason the tool
    /// catalogue is checked here: a wrap applied when the ring is supplied
    /// would cover only the stores registered so far, so `keyring(..)` before
    /// `cases(..)` would silently seal less than `keyring(..)` after it. An
    /// enforcement a reordering can lose is one a reformatter can delete.
    ///
    /// Every decorator is handed `self.tenant` rather than reading a name back
    /// out of the store it wraps, so all four derive the erasure scope from one
    /// value. `keyring()`'s own documentation names the one store deliberately
    /// left out, and why.
    #[cfg(feature = "keyring")]
    fn seal_stores(&mut self) {
        let Some(keys) = self.keyring.clone() else {
            return;
        };
        let tenant = self.tenant.clone();
        self.store = crate::keyring::SealedJournal::wrap(
            Arc::clone(&self.store),
            Arc::clone(&keys),
            tenant.clone(),
        );
        if let Some(cases) = self.cases.take() {
            self.cases = Some(crate::keyring::SealedCases::wrap(
                cases,
                Arc::clone(&keys),
                tenant.clone(),
            ));
        }
        if let Some(events) = self.events.take() {
            self.events = Some(crate::keyring::SealedEvents::wrap(
                events,
                Arc::clone(&keys),
                tenant.clone(),
            ));
        }
        // The outbox's store keeps the operator destinations' bearer tokens —
        // credentials like any caller's, and the one store here reached through
        // a handle the embedder built rather than registered. Sealing it in the
        // same sweep is what keeps `keyring()` one decision rather than five
        // and a sixth.
        #[cfg(feature = "push")]
        if let Some(outbox) = self.outbox.take() {
            self.outbox = Some(Arc::new(
                outbox
                    .as_ref()
                    .clone()
                    .sealed(Arc::clone(&keys), tenant.clone()),
            ));
        }
        if let Some(tasks) = self.tasks.take() {
            self.tasks = Some(crate::keyring::SealedTasks::wrap(tasks, keys, tenant));
        }
    }

    /// Without the `keyring` feature there is nothing to seal.
    ///
    /// `&mut self` matches the sealing arm above, which does mutate. Taking
    /// `&self` here would make the signature depend on a feature flag, and
    /// every caller with it.
    #[cfg(not(feature = "keyring"))]
    #[allow(clippy::unused_self, clippy::needless_pass_by_ref_mut)]
    fn seal_stores(&mut self) {}

    /// Supply the store that tracks batch items.
    ///
    /// Only needed for [`Runtime::run_batch`]; a plane that runs no batches does
    /// not need one, and asking for it unconditionally would make the common
    /// case carry the uncommon one's setup.
    #[must_use]
    pub fn batches(mut self, batches: Arc<dyn crate::batch::BatchStore>) -> Self {
        self.batches = Some(batches);
        self
    }

    /// Supply the authorization engine.
    ///
    /// Without one there is no policy layer — the information-flow gates still
    /// apply, but nothing asks whether the principal was allowed. That is a
    /// deliberate absence rather than a permissive default: see `core::policy`
    /// on why there is no `AllowAll` to configure by mistake.
    ///
    /// The engine's complete immutable bundle identity is recorded at admission,
    /// so both whether policy was on and exactly which executable semantics
    /// governed the run are answerable from the journal. An open run may resume
    /// only under that same identity.
    #[must_use]
    pub fn policy(mut self, policy: Arc<dyn crate::core::PolicyEngine>) -> Self {
        self.policy = Some(policy);
        self
    }

    /// The chain this plane's own runs act under.
    ///
    /// The identity of a run the embedder starts in-process — checked against
    /// the plan at admission (the plan is the authorization graph, so one that
    /// exceeds the chain's authority never starts), held to the chain's
    /// audience and validity, and journaled, so "on whose behalf" is
    /// answerable from history rather than reconstructed from timestamps.
    ///
    /// It is **not** the identity of a run a served surface admits for a
    /// caller: those act under the chain the caller presented, or under none
    /// when it presented none ([`RunTerms::served`]). A plane that bound its own
    /// chain to every peer's run would be an ambient credential.
    ///
    /// Verification of the *credential* belongs to whatever authenticates the
    /// caller; what arrives here is already a chain, and its attenuation is
    /// guaranteed by its own constructors however it was obtained.
    #[must_use]
    pub fn acting_as(mut self, chain: crate::core::Delegation) -> Self {
        self.identity = Some(chain);
        self
    }

    /// The peers this plane may call, and the transport that reaches them.
    ///
    /// The registry is wiring — what each peer is granted, which credential
    /// reaches it, how a failed call recovers. What a run may *ask* a peer
    /// for is a manifest grant, `tool://<peer>/<capability>`, dispatched
    /// through [`StepCtx::call_peer`](crate::runtime::StepCtx::call_peer).
    /// Refused at build: a peer named `agent` or like a wired tool server,
    /// and a grant naming a capability outside the peer's registry scope.
    #[must_use]
    pub fn peers(
        mut self,
        registry: crate::peers::PeerRegistry,
        client: Arc<dyn crate::peers::PeerClient>,
    ) -> Self {
        self.peers = Some(Arc::new(PeerWiring { registry, client }));
        self
    }

    /// Submit this plane's checkpoints to witnesses, and hold each round to a
    /// quorum.
    ///
    /// This is the only control here whose value comes from *not* being this
    /// plane. The hash chain proves no record was edited, the signatures say
    /// which workload wrote them, and the Merkle log proves no sealed run was
    /// removed — but every input to all three comes from the party an auditor
    /// is being asked to trust. None of them detects a whole run deleted
    /// before anyone took a checkpoint, or two internally perfect histories
    /// shown to two auditors. A witness keeps the last checkpoint it saw and
    /// cosigns only a checkpoint that provably extends it, so those two stop
    /// being invisible.
    ///
    /// Availability never waits on it: submission runs on
    /// [`sweep`](Runtime::sweep), after sealing and off the run path, and a
    /// round that falls short is a report rather than a refusal. A run whose
    /// witnesses are unreachable finished long ago, and making the plane's
    /// availability depend on a third party is the wrong trade for evidence
    /// that is read after the fact.
    ///
    /// Point it at witnesses somebody else runs. A witness hosted beside the
    /// history it vouches for is an anchor one compromise removes, and
    /// [`MemoryWitness`](crate::journal::MemoryWitness) says so at its own
    /// definition.
    ///
    /// # Errors
    ///
    /// [`build`](RuntimeBuilder::build) refuses a quorum larger than the
    /// number of witnesses configured, and a witness list with no quorum.
    #[must_use]
    pub fn witnesses(
        mut self,
        witnesses: Vec<Arc<dyn crate::journal::Witness>>,
        quorum: crate::journal::WitnessQuorum,
    ) -> Self {
        self.witnesses = witnesses;
        self.quorum = Some(quorum);
        self
    }

    /// Declare the maximum time between checkpoint submissions to each
    /// witness: [`sweep`](Runtime::sweep) re-submits an unchanged checkpoint
    /// once it has passed since the last round that met quorum, so an idle
    /// plane still carries a fresh witness timestamp. Without it an unchanged
    /// log is never re-submitted.
    ///
    /// The interval is kept only as often as `sweep` runs; a deployment
    /// sweeping on its own scheduler owns that cadence.
    ///
    /// # Errors
    ///
    /// [`build`](RuntimeBuilder::build) refuses an interval with no witnesses.
    #[must_use]
    pub fn witness_interval(mut self, interval: std::time::Duration) -> Self {
        self.witness_interval = Some(interval);
        self
    }

    /// Supply the calendar that resolves deadline descriptions to instants.
    ///
    /// Defaults to [`WallClock`], which understands plain offsets and refuses
    /// anything it does not know rather than approximating it. Domain calendars
    /// — working days, holidays, cut-off hours — are the adapter's job.
    #[must_use]
    pub fn calendar(mut self, calendar: Arc<dyn Calendar>) -> Self {
        self.calendar = Some(calendar);
        self
    }

    /// Derive the tool catalogue from the agents and refuse a disagreement.
    ///
    /// Every agent, not the first: a plane may host several, and a tool granted
    /// to none of them is still a tool this binary can be asked for.
    ///
    /// # Errors
    ///
    /// If the box and any agent's manifest disagree. A build-time
    /// misconfiguration has a fix and no recovery, and it is refused the way the
    /// tenant mismatch beside it is: before anything runs.
    #[cfg(feature = "manifest")]
    fn settle_toolbox(&mut self) -> Result<(), BuildError> {
        let servers = std::mem::take(&mut self.tool_servers);
        let tools = self.toolbox.take();
        // A peer's name is a server name a grant can carry, so it must mean
        // exactly one thing on this plane: not `agent`, and not a name some
        // tool transport also answers for.
        let peer_names: std::collections::BTreeSet<String> = self
            .peers
            .as_ref()
            .map(|wiring| wiring.registry.peers().map(ToString::to_string).collect())
            .unwrap_or_default();
        if peer_names.contains(crate::tools::AGENT_SERVER) {
            return Err(BuildError::ReservedToolServer);
        }
        for name in &peer_names {
            if servers.iter().any(|(server, _)| server == name)
                || tools
                    .as_ref()
                    .is_some_and(|t| t.servers().any(|s| s == name))
            {
                return Err(BuildError::PeerIsAlsoAToolServer {
                    server: name.clone(),
                });
            }
        }
        if tools.is_none() && servers.is_empty() {
            return Ok(());
        }
        let tools = tools.unwrap_or_default();
        let remote_servers: std::collections::BTreeSet<String> =
            servers.iter().map(|(name, _)| name.clone()).collect();
        // What a grant may name without this box implementing it: a wired
        // transport, or a registered peer.
        let reachable_elsewhere: std::collections::BTreeSet<String> =
            remote_servers.union(&peer_names).cloned().collect();
        // `agent` names agents on this plane, and only them. A transport or a
        // typed tool under that name would let a deployment decide whether a
        // reviewed grant means "an agent here" or "somebody's server".
        if remote_servers.contains(crate::tools::AGENT_SERVER)
            || tools
                .servers()
                .any(|server| server == crate::tools::AGENT_SERVER)
        {
            return Err(BuildError::ReservedToolServer);
        }
        if remote_servers.len() != servers.len() {
            // The set lost an entry, so some name appears twice. Naming it beats
            // reporting a count a reader then has to go and diff by hand.
            let mut seen = std::collections::BTreeSet::new();
            let duplicate = servers
                .iter()
                .map(|(name, _)| name)
                .find(|name| !seen.insert((*name).clone()))
                .cloned()
                .unwrap_or_default();
            return Err(BuildError::DuplicateToolServer { server: duplicate });
        }
        // Both forms wired is not a merge and must not silently be one. The
        // hand-built catalogue is the operator saying something deliberate; the
        // derived one is the agent's declaration. Overwriting either with the
        // other would run a plane under grants nobody chose.
        if self.tools.is_some() {
            return Err(BuildError::ToolsWiredTwice);
        }
        let mut catalog = crate::tools::ToolCatalog::new();
        let mut declared = 0usize;
        // Which agent's declaration a tool's catalogue entry came from, so a
        // second agent declaring the same tool *differently* is a build-time
        // refusal rather than a silent overwrite.
        //
        // A plane has one catalogue and its agents have one manifest each, so
        // two agents granting `tool://ledger/read` with different protected
        // fields cannot both be satisfied. Merging by last-writer would resolve
        // it by **registration order** — the one thing this builder already
        // says an enforcement must never depend on — and it fails at a
        // distance: `declared` compares each agent's manifest against the
        // catalogue-derived descriptor exactly, so the agent that lost the race
        // is refused *every* call to that tool, in production, with a message
        // blaming a code-versus-manifest drift that neither file exhibits.
        let mut source: BTreeMap<crate::tools::ToolId, (String, crate::tools::ToolSafety)> =
            BTreeMap::new();
        for agent in &self.agents {
            let Some(manifest) = agent.manifest.as_ref() else {
                continue;
            };
            declared += 1;
            tools
                .check_against(manifest, &reachable_elsewhere)
                .map_err(|problems| BuildError::ToolDrift {
                    agent: manifest.metadata.name.clone(),
                    problems,
                })?;
            for (id, safety) in crate::tools::ToolCatalog::from_manifest(manifest).entries() {
                if let Some((first, existing)) = source.get(&id) {
                    if existing != &safety {
                        return Err(BuildError::ToolDeclaredTwoWays {
                            tool: id.reference(),
                            first: first.clone(),
                            second: manifest.metadata.name.clone(),
                        });
                    }
                    continue;
                }
                source.insert(id.clone(), (manifest.metadata.name.clone(), safety.clone()));
                catalog = catalog.allow(id, safety);
            }
        }
        // A box with nothing to be coherent *with* is the same defect one step
        // earlier: tools wired to a plane where no declaration admits them, so
        // nothing a reviewer reads describes what this binary can reach.
        if declared == 0 {
            return Err(BuildError::ToolsWithoutDeclaration);
        }
        // The typed argument type is the schema source. Overlay its
        // presentation only after every manifest has been checked, so the
        // model sees exactly what the body will deserialize rather than the
        // old permissive `{ type: object }` fallback.
        for id in tools.ids() {
            let (description, schema, _) = tools
                .declared(id)
                .expect("every registered typed tool has a declaration");
            let reviewed_description = catalog
                .declaration(id)
                .map_or_else(|| description.to_owned(), |(text, _)| text.to_owned());
            catalog = catalog.declare(id.clone(), reviewed_description, schema.clone());
        }
        // One client per server, resolved by the name a grant carries. A single
        // client handed every id could not tell `tool://ledger/read` from
        // `tool://tickets/read`, and a transport that never reads the server
        // component answers both — from whichever server it happens to hold.
        let router = servers.into_iter().fold(
            crate::tools::ToolRouter::new().toolbox(&Arc::new(tools)),
            |router, (name, client)| router.server(name, client),
        );
        self.tools = Some((
            Arc::new(catalog),
            Arc::new(router) as Arc<dyn crate::tools::ToolClient>,
        ));
        Ok(())
    }

    /// Settle the tool catalogue: derive it if asked, then hold it to the
    /// declarations.
    ///
    /// One call because the two halves are one decision seen from either side.
    /// [`settle_toolbox`](Self::settle_toolbox) covers the derived catalogue,
    /// where code and manifest could disagree; the check after it covers the
    /// stated one, where operator and manifest could. Whichever way the
    /// catalogue arrived, it is checked before anything runs.
    #[cfg(feature = "manifest")]
    fn settle_tools(&mut self) -> Result<(), BuildError> {
        self.settle_toolbox()?;
        self.check_catalogue_not_laxer_than_grants()
    }

    /// Refuse a stated catalogue that is **laxer** than a reviewed grant.
    ///
    /// `toolbox(..)` derives the catalogue from the manifests, so the two
    /// cannot drift. `tools(..)` states it by hand, and there the operator's
    /// entry and the agent's declaration are two copies of one decision — with
    /// nothing, until this, that noticed them disagreeing.
    ///
    /// Only one direction is a defect, the same one
    /// [`ToolBox::check_against`](crate::tools::ToolBox::check_against) refuses.
    /// An operator being **more** cautious than the declaration is fine and
    /// often right. An operator being **less** cautious is not, and it changes
    /// two things at once:
    ///
    /// * the whole-value taint gate stops firing, so model-chosen arguments
    ///   reach something that changes the world;
    /// * `ToolSafety::read_only` carries `Recovery::Retry`, so a timed-out call
    ///   to a money-moving tool is sent a second time.
    ///
    /// The dispatch gates already take the stricter `mutates` of the two, so
    /// the first is contained at runtime. The second is not — recovery is read
    /// from the catalogue alone — and neither should have to be, because this
    /// is a wiring mistake with a fix and no recovery. It is refused here,
    /// beside the rest of them.
    #[cfg(feature = "manifest")]
    fn check_catalogue_not_laxer_than_grants(&self) -> Result<(), BuildError> {
        let Some((catalog, _)) = self.tools.as_ref() else {
            return Ok(());
        };
        let mut problems = Vec::new();
        for agent in &self.agents {
            let Some(manifest) = agent.manifest.as_ref() else {
                continue;
            };
            for grant in &manifest.spec.tools {
                if !grant.mutates {
                    continue;
                }
                let Some(id) = crate::tools::ToolId::parse(&grant.reference) else {
                    continue;
                };
                if catalog.safety(&id).is_some_and(|s| !s.mutates) {
                    problems.push(format!(
                        "agent '{}' grants '{}' as mutating and the stated catalogue \
                         calls it read-only",
                        manifest.metadata.name, grant.reference
                    ));
                }
            }
        }
        if problems.is_empty() {
            Ok(())
        } else {
            Err(BuildError::CatalogueLaxerThanGrant { problems })
        }
    }

    /// Assemble the runtime, or panic naming the wiring mistake.
    ///
    /// The ordinary entry point. Every refusal below is a bug in code the author
    /// is looking at, so propagating it through `?` to a `main` that prints it
    /// is ceremony around an abort — and each is caught here at startup rather
    /// than at dispatch, in production, where the cost is a run that has already
    /// begun.
    ///
    /// Use [`try_build`](Self::try_build) where a manifest arrives at *runtime*
    /// — read from disk, pinned by a registry, or supplied per tenant. There a
    /// bad declaration is an input rather than a bug, and a panic would take
    /// every other tenant in the process down to report it.
    ///
    /// # Panics
    ///
    /// On any [`BuildError`]:
    ///
    /// * A manifest declares a capability in `spec.capabilities.provides` that
    ///   no registered skill provides. **An agent has skills**, so a declaration
    ///   advertising one it cannot perform is a card that lies.
    /// * Two agents claim the same capability. Dispatch resolves a capability to
    ///   one skill *and to the manifest governing it*, so a second claim would
    ///   silently take the first's work out from under the first's budget,
    ///   model grants and egress ceiling.
    /// * Two skills share a name. A name is what a capability resolves to and
    ///   what governance is keyed on; two of them make both lookups arbitrary.
    /// * A stated catalogue calls a tool read-only that a reviewed manifest
    ///   grants as mutating. That exemption drops the whole-value taint gate
    ///   and makes a timed-out money-moving call retryable — the one direction
    ///   an operator cannot be right about.
    /// * A declarative agent names a provider no driver is registered for, or
    ///   declares `spec.execution` without a privileged model to call.
    /// * A plane and its store — or its blob store — are scoped to different
    ///   tenants. The two are set
    ///   separately — this builder's tenant scopes data keys and the policy
    ///   request, `for_tenant` scopes the store's keys — and the mismatch does
    ///   not show up at runtime. It *works*, and writes this tenant's runs into
    ///   another's keyspace while every erasure and every policy request names
    ///   the right one.
    ///
    /// # Long-running services want [`try_build`](Self::try_build)
    ///
    /// This panics, which is the honest answer for a binary wiring its own
    /// skills: every variant above is a bug in code the author is looking at,
    /// and aborting reports it at the moment it can be fixed. A daemon is a
    /// different case — it wants to exit with a diagnostic, and a plane
    /// assembled from a manifest that arrived at runtime is handling an *input*,
    /// where a panic reports one tenant's typo by killing every other tenant's
    /// in-flight run. `try_build` returns the same `BuildError` instead. One
    /// implementation underneath both, so they cannot disagree about what is
    /// refused.
    #[must_use]
    pub fn build(self) -> Arc<Runtime> {
        // Not `expect`. That formats the error with `Debug`, which would print
        // `AdvertisesWhatItCannotProvide { agent: "…", missing: [...] }` — the
        // variant's *shape* — while the sentence explaining what to do about it
        // lives in `Display`. Panicking with `{error}` keeps the two entry
        // points telling one story, which is the whole point of `build` being
        // `try_build` underneath.
        match self.try_build() {
            Ok(runtime) => runtime,
            Err(error) => panic!("{error}"),
        }
    }

    /// The driver for a declarative agent's privileged model — named rather
    /// than defaulted, because falling back to some other registered driver
    /// would run the agent on a model its own declaration does not name.
    /// Every declared content check names a registered checker, and maps only
    /// categories that checker declares.
    #[cfg(feature = "manifest")]
    fn check_content_checkers(
        checkers: &crate::content::Checkers,
        m: &crate::manifest::Manifest,
    ) -> Result<(), BuildError> {
        let Some(content) = m.spec.security.content.as_ref() else {
            return Ok(());
        };
        for check in &content.checks {
            let refused = |detail: String| BuildError::ContentCheck {
                agent: m.metadata.name.clone(),
                check: check.id.clone(),
                detail,
            };
            let Some(checker) = checkers.get(&check.checker) else {
                return Err(refused(format!(
                    "no checker named '{}' is registered on this plane",
                    check.checker
                )));
            };
            if let Some(unknown) = check
                .on
                .keys()
                .find(|category| !checker.categories().contains(*category))
            {
                return Err(refused(format!(
                    "'{unknown}' is not a category checker '{}' declares",
                    check.checker
                )));
            }
        }
        Ok(())
    }

    #[cfg(feature = "manifest")]
    fn declared_provider(
        providers: &HashMap<String, Arc<dyn crate::model::ModelProvider>>,
        m: &crate::manifest::Manifest,
    ) -> Result<Arc<dyn crate::model::ModelProvider>, BuildError> {
        let model = m
            .spec
            .models
            .as_ref()
            .and_then(|x| x.privileged.as_ref())
            .ok_or_else(|| BuildError::DeclarativeWithoutModel {
                agent: m.metadata.name.clone(),
            })?;
        providers
            .get(&model.provider)
            .map(Arc::clone)
            .ok_or_else(|| BuildError::UnknownProvider {
                agent: m.metadata.name.clone(),
                provider: model.provider.clone(),
            })
    }

    /// Assemble the runtime, or say why it cannot be.
    ///
    /// The same checks as [`build`](Self::build), returned rather than raised.
    /// One implementation behind both, so they cannot come to disagree about
    /// what is refused.
    ///
    /// # Errors
    ///
    /// Any [`BuildError`] — see [`build`](Self::build) for what each means.
    // `mut` is for `settle_toolbox`, which only exists when manifests do.
    #[cfg_attr(not(feature = "manifest"), allow(unused_mut))]
    #[allow(clippy::too_many_lines)]
    pub fn try_build(mut self) -> Result<Arc<Runtime>, BuildError> {
        if self.lease_ttl < MIN_LEASE_TTL {
            return Err(BuildError::LeaseUnrenewable {
                ttl: self.lease_ttl,
                minimum: MIN_LEASE_TTL,
            });
        }
        // A ceiling of zero is a budget already spent, and it refuses the
        // first effect of every run this plane will ever make. The manifest
        // refuses one at parse; a plane wired in Rust reaches the same `Budget`
        // without passing a parser, so the rule is applied at both doors from
        // the one definition in `Budget::bricked_ceiling`.
        if let Some(field) = self.budget.bricked_ceiling() {
            return Err(BuildError::BudgetPermitsNothing { field });
        }
        if let Some(engine) = self.policy.as_ref() {
            preflight_policy(engine.as_ref(), self.identity.as_ref())?;
        }
        // Before `seal_stores`, necessarily: sealing wraps each handle in one
        // scoped to the *plane's* tenant, after which every store agrees with
        // the plane and the question cannot be asked.
        // Both halves of push, because either can be wired to another
        // tenant's rows and the consequence is the same: registrations,
        // cursors and credentials filed under a scope this plane's erasure
        // never names.
        #[cfg(feature = "push")]
        let push = self
            .push
            .as_ref()
            .map(|s| s.tenant())
            .or_else(|| self.outbox.as_ref().map(|o| o.store_tenant()));
        #[cfg(not(feature = "push"))]
        let push: Option<&str> = None;
        check_same_tenant(
            self.store.as_ref(),
            self.blobs.as_ref(),
            self.memories.as_ref(),
            &[
                ("case", self.cases.as_ref().map(|s| s.tenant())),
                ("event", self.events.as_ref().map(|s| s.tenant())),
                ("task", self.tasks.as_ref().map(|s| s.tenant())),
                ("memory", self.memories.as_ref().map(|s| s.tenant())),
                ("quota", self.quotas.as_ref().map(|s| s.tenant())),
                ("timer", self.timers.as_ref().map(|s| s.tenant())),
                ("batch", self.batches.as_ref().map(|s| s.tenant())),
                ("authority", self.authorities.as_ref().map(|s| s.tenant())),
                ("push", push),
            ],
            &self.tenant,
        )?;
        // The one wiring mistake here that would otherwise never fail: a
        // cross-space query ranks rather than refusing.
        if let Some(semantic) = &self.semantic {
            let embedder = semantic.embedder.revision();
            let index = semantic.retriever.index().query_revision;
            if embedder != index {
                return Err(BuildError::EmbeddingSpaceMismatch { embedder, index });
            }
            if semantic.embedder.pricing().is_none() && self.states_a_money_ceiling() {
                return Err(BuildError::UnpricedEmbedder { embedder });
            }
            let Some(memories) = self.memories.take() else {
                return Err(BuildError::SemanticMemoryWithoutStore);
            };
            // Every erasure through the plane's store — and through a sealed
            // store's own subject erasure — reaches the index built from it.
            let reached = memories.erasure_index();
            let indexed: Arc<dyn crate::memory::MemoryStore> = match reached {
                Some(index) if Arc::ptr_eq(&index, &semantic.retriever) => memories,
                Some(_) => return Err(BuildError::MemoryIndexedElsewhere),
                None if memories.seals() => {
                    return Err(BuildError::SealedMemoryMissesIndex);
                }
                None => Arc::new(crate::memory::IndexedMemoryStore::new(
                    Arc::clone(&memories),
                    Arc::clone(&semantic.retriever),
                )),
            };
            self.memories = Some(indexed);
        }
        self.seal_stores();
        #[cfg(feature = "manifest")]
        self.settle_tools()?;

        let mut skills = HashMap::new();
        let mut by_capability = HashMap::new();
        #[cfg(feature = "manifest")]
        let mut governed_by: HashMap<String, Arc<crate::manifest::Manifest>> = HashMap::new();
        #[cfg(feature = "manifest")]
        let mut published_by: HashMap<String, crate::core::KeyId> = HashMap::new();

        // Skills registered directly belong to the plane's anonymous agent: no
        // declaration, so nothing to enforce against them beyond the runtime's
        // own budget. That is a legitimate shape — not every agent needs a
        // manifest — and it is why `skill()` still exists beside `agent()`.
        for s in self.skills {
            register_skill(s, &mut by_capability, &mut skills)?;
        }

        #[cfg(feature = "manifest")]
        for agent in self.agents {
            if let (Some(m), Some(key)) = (agent.manifest.as_ref(), agent.publisher.clone()) {
                published_by.insert(m.metadata.name.clone(), key);
            }
            let Some(m) = agent.manifest.clone() else {
                for s in agent.skills {
                    register_skill(s, &mut by_capability, &mut skills)?;
                }
                continue;
            };

            // The capabilities this agent's *own* skills provide, which is what
            // its declaration is checked against below.
            let mut mine: HashSet<Capability> = HashSet::new();
            for s in agent.skills {
                mine.extend(s.descriptor().capabilities());
                let name = register_skill(s, &mut by_capability, &mut skills)?;
                governed_by.insert(name, Arc::clone(&m));
            }

            // A declarative agent needs no skill: the runtime supplies the
            // behaviour its manifest asked for.
            if let Some(execution) = &m.spec.execution {
                // A `call` calls no model, so it needs no provider.
                let provider = if execution.kind == crate::manifest::ExecutionKind::Call {
                    None
                } else {
                    Some(Self::declared_provider(&self.providers, &m)?)
                };
                if m.spec.capabilities.provides.is_empty() {
                    return Err(BuildError::DeclarativeProvidesNothing {
                        agent: m.metadata.name.clone(),
                    });
                }
                // A plane whose only tools are agents needs no toolbox and no
                // transport: the catalogue is derived from the declaration and
                // dispatch is `commission`. The empty router is deliberate —
                // an agent-server call never reaches it, and anything else
                // arriving there is refused as unreachable rather than
                // silently absorbed.
                let tools = self.tools.clone().or_else(|| {
                    // Agents on this plane and registered peers: both
                    // dispatch through the runtime's own effects rather than
                    // a tool transport, so a declaration made only of them
                    // needs no box and no router.
                    let all_agent = !m.spec.tools.is_empty()
                        && m.spec.tools.iter().all(|g| {
                            crate::tools::ToolId::parse(&g.reference).is_some_and(|id| {
                                id.server == crate::tools::AGENT_SERVER
                                    || self.peers.as_ref().is_some_and(|wiring| {
                                        wiring
                                            .registry
                                            .grant(&crate::peers::PeerId::new(&id.server))
                                            .is_some()
                                    })
                            })
                        });
                    all_agent.then(|| {
                        (
                            Arc::new(crate::tools::ToolCatalog::from_manifest(&m)),
                            Arc::new(crate::tools::ToolRouter::new())
                                as Arc<dyn crate::tools::ToolClient>,
                        )
                    })
                });
                // A tool loop with nothing to reach fails on every run with the
                // same sentence, and the manifest that says so was read at
                // build. `planned` only needs a catalogue when it has grants;
                // `tool-calling` needs one to exist at all, since offering a
                // model no tools is not a tool loop.
                if tools.is_none() {
                    let needs = match execution.kind {
                        crate::manifest::ExecutionKind::ToolCalling => {
                            Some(if m.spec.tools.is_empty() {
                                "no tool grants".to_owned()
                            } else {
                                format!("{} tool grant(s)", m.spec.tools.len())
                            })
                        }
                        crate::manifest::ExecutionKind::Planned
                        | crate::manifest::ExecutionKind::Call
                            if !m.spec.tools.is_empty() =>
                        {
                            Some(format!("{} tool grant(s)", m.spec.tools.len()))
                        }
                        _ => None,
                    };
                    if let Some(grants) = needs {
                        return Err(BuildError::DeclarativeToolsUnreachable {
                            agent: m.metadata.name.clone(),
                            kind: execution.kind.as_str(),
                            grants,
                        });
                    }
                }

                // Oversight needs somewhere to put the decision, and both
                // halves are known here. Left to run time it surfaces at the
                // first real approval — a person already waiting, on the code
                // path a test suite is least likely to reach.
                let declared = if m.spec.oversight.is_some() {
                    Some("`spec.oversight`".to_owned())
                } else if m.spec.tools.iter().any(|g| g.requires_approval) {
                    Some("a grant with `requires_approval: true`".to_owned())
                } else {
                    None
                };
                if let Some(declared) = declared {
                    // Ordered by what a reader fixes first: without a case
                    // there is nothing for a task to hang off.
                    //
                    // Timers are deliberately **not** required, and the test
                    // suite is why: four approval tests wire a case store and a
                    // worklist, no timers, and run an approval end to end. A
                    // task is opened, the run suspends, a person decides. What
                    // a timer store adds is the sweeper firing `on_expiry`, and
                    // refusing a configuration that works would be this check
                    // asserting more than it knows — the failure mode it exists
                    // to prevent, arriving from the other side.
                    let missing = if self.cases.is_none() {
                        Some(("case store", "cases"))
                    } else if self.tasks.is_none() {
                        Some(("worklist", "tasks"))
                    } else {
                        None
                    };
                    if let Some((missing, remedy)) = missing {
                        return Err(BuildError::OversightUnreachable {
                            agent: m.metadata.name.clone(),
                            declared,
                            missing,
                            remedy,
                        });
                    }
                }

                // A recall reads before the first model call and formation
                // writes after the answer, so a missing store costs a run its
                // first effect or its whole budget depending on which half was
                // declared. Both facts are here: the file says memories are
                // reached, the plane says there is nowhere to reach.
                if let Some(memory) = &m.spec.memory {
                    let declared: [(&'static str, Option<&crate::manifest::MemorySubject>); 2] = [
                        (
                            "spec.memory.recall",
                            memory.recall.as_ref().map(|r| &r.subject),
                        ),
                        (
                            "spec.memory.formation",
                            memory.formation.as_ref().map(|f| &f.subject),
                        ),
                    ];
                    for (field, subject) in declared {
                        let Some(subject) = subject else { continue };
                        if self.memories.is_none() {
                            return Err(BuildError::MemoryWithoutStore {
                                agent: m.metadata.name.clone(),
                                declared: field,
                            });
                        }
                        if subject.needs_case() && self.cases.is_none() {
                            return Err(BuildError::MemorySubjectUnbindable {
                                agent: m.metadata.name.clone(),
                                subject: subject.as_written(),
                            });
                        }
                    }
                }

                for cap in &m.spec.capabilities.provides {
                    let skill: Arc<dyn Skill> = Arc::new(super::declarative::Declarative::new(
                        execution.kind,
                        cap.clone(),
                        m.metadata.name.clone(),
                        provider.clone(),
                        tools.clone(),
                        execution.max_turns,
                    ));
                    mine.insert(Capability::new(cap.as_str()));
                    let name = register_skill(skill, &mut by_capability, &mut skills)?;
                    governed_by.insert(name, Arc::clone(&m));
                }
            }

            check_declaration_matches_skills(&m, &mine)?;
        }

        // Agent grants are validated against the finished plane, because the
        // capability they name may belong to an agent registered *later* — a
        // check inside the loop would pass or fail on registration order.
        #[cfg(feature = "manifest")]
        {
            let mut checked = std::collections::BTreeSet::new();
            for m in governed_by.values() {
                if !checked.insert(m.metadata.name.clone()) {
                    continue;
                }
                Self::check_content_checkers(&self.checkers, m)?;
                for grant in &m.spec.tools {
                    let Some(id) = crate::tools::ToolId::parse(&grant.reference) else {
                        continue;
                    };
                    // A grant naming a registered peer is a delegating hop,
                    // and both things that would refuse it on every run are
                    // knowable here: a capability the registry never gave the
                    // peer, and a granting agent whose own ceiling is zero.
                    if let Some(wiring) = self.peers.as_ref()
                        && let Some(peer_grant) = wiring
                            .registry
                            .grant(&crate::peers::PeerId::new(&id.server))
                    {
                        if !peer_grant.scope.permits(&Capability::new(id.tool.as_str())) {
                            return Err(BuildError::PeerGrantOutsideScope {
                                agent: m.metadata.name.clone(),
                                peer: id.server,
                                capability: id.tool,
                            });
                        }
                        let cannot_delegate = m
                            .spec
                            .topology
                            .as_ref()
                            .is_some_and(|t| t.role == crate::manifest::Role::Specialist)
                            || m.spec.security.max_delegation_depth == Some(0);
                        if cannot_delegate {
                            return Err(BuildError::PeerGrantOnASpecialist {
                                agent: m.metadata.name.clone(),
                                peer: id.server,
                            });
                        }
                        continue;
                    }
                    if id.server != crate::tools::AGENT_SERVER {
                        continue;
                    }
                    if m.spec.capabilities.provides.contains(&id.tool) {
                        return Err(BuildError::AgentToolSelfReference {
                            agent: m.metadata.name.clone(),
                            capability: id.tool,
                        });
                    }
                    if !by_capability.contains_key(&Capability::new(id.tool.as_str())) {
                        return Err(BuildError::AgentToolUnknownCapability {
                            agent: m.metadata.name.clone(),
                            capability: id.tool,
                        });
                    }
                }
            }
        }

        // Every ceiling any declaration on this plane states, by tool: the
        // count is per tool, so the tightest binds every agent calling it.
        #[cfg(feature = "manifest")]
        let rates = {
            let mut declarations: Vec<&Arc<crate::manifest::Manifest>> =
                governed_by.values().collect();
            declarations.sort_by(|a, b| a.metadata.name.cmp(&b.metadata.name));
            let mut ceilings: BTreeMap<String, Vec<crate::quota::RateCeiling>> = BTreeMap::new();
            let mut first = None;
            for m in declarations {
                for grant in &m.spec.tools {
                    let Some(rate) = grant.rate_limit else {
                        continue;
                    };
                    first.get_or_insert_with(|| (m.metadata.name.clone(), grant.reference.clone()));
                    let stated = ceilings.entry(grant.reference.clone()).or_default();
                    let ceiling = crate::quota::RateCeiling::from(rate);
                    if !stated.contains(&ceiling) {
                        stated.push(ceiling);
                        stated.sort();
                    }
                }
            }
            if ceilings.is_empty() {
                None
            } else if let Some(store) = self.quotas.clone() {
                Some(Arc::new(super::ctx::Rates { store, ceilings }))
            } else {
                let (agent, grant) = first.unwrap_or_default();
                return Err(BuildError::RateLimitWithoutQuotaStore { agent, grant });
            }
        };

        // Both or neither, checked here because a builder cannot see the other
        // half at the moment either is set.
        if self.witness_interval.is_some() && self.witnesses.is_empty() {
            return Err(BuildError::IntervalWithoutWitnesses);
        }
        let witnesses = match (self.witnesses.is_empty(), self.quorum) {
            (true, None) => None,
            (false, Some(quorum)) if quorum.required() <= self.witnesses.len() => {
                Some(Arc::new(Witnessing {
                    witnesses: self.witnesses,
                    quorum,
                    submitted: std::sync::atomic::AtomicU64::new(0),
                    interval: self.witness_interval,
                    last_met: std::sync::Mutex::new(None),
                }))
            }
            (empty, quorum) => {
                return Err(BuildError::WitnessQuorumUnreachable {
                    declared: quorum.map_or(0, |q| q.required()),
                    configured: if empty { 0 } else { self.witnesses.len() },
                });
            }
        };

        Ok(Arc::new_cyclic(|self_ref| Runtime {
            self_ref: self_ref.clone(),
            witnesses,
            inflight: Arc::default(),
            signer: self.signer,
            store: self.store,
            skills,
            by_capability,
            #[cfg(feature = "manifest")]
            published_by,
            #[cfg(feature = "manifest")]
            providers: self.providers,
            meter: super::metrics::Meter::new(self.tenant_label, &self.tenant),
            tenant: self.tenant,
            owner: self.owner.unwrap_or_else(default_owner),
            lease_ttl: self.lease_ttl,
            memories: self.memories,
            semantic: self.semantic,
            authorities: self.authorities,
            peers: self.peers,
            #[cfg(feature = "manifest")]
            tools: self.tools,
            journal_ceiling: self.journal_ceiling,
            #[cfg(feature = "manifest")]
            egress: self.egress,
            #[cfg(feature = "manifest")]
            checkers: self.checkers,
            streams: self.streams,
            quotas: self.quotas,
            #[cfg(feature = "manifest")]
            rates,
            quota: self.quota,
            budget: self.budget,
            require_verifier: self.require_verifier,
            cases: self.cases,
            events: self.events,
            tasks: self.tasks,
            timers: self.timers,
            blobs: self.blobs,
            disclosures: self.disclosures,
            #[cfg(feature = "keyring")]
            keyring: self.keyring,
            batches: self.batches,
            policy: self.policy,
            identity: self.identity,
            replanner: self.replanner,
            calendar: self.calendar.unwrap_or_else(|| Arc::new(WallClock)),
            #[cfg(feature = "push")]
            push: self.push,
            #[cfg(feature = "push")]
            outbox: self.outbox,
            #[cfg(feature = "manifest")]
            governed_by,
        }))
    }
}

/// Ask the policy set the questions this plane will ask, before it asks them
/// for real.
///
/// Cedar evaluates **every** rule against **every** request, so a rule reading
/// an attribute a request does not carry does not quietly fail to match — it
/// errors, and an unevaluable rule may be the `forbid` that would have stopped
/// the call, so the gate refuses. One unguarded rule therefore denies every
/// effect of every run, from a policy set that compiled cleanly and validated
/// against its schema.
///
/// The probes cover every shape a runtime request takes: an effect that reads
/// and one that mutates, each with and without a label (only `sink` carries
/// one), a release, and an admission. `mutates` matters on its own: `&&`
/// short-circuits, so `context.mutates && context.label.trust == ..` evaluates
/// cleanly on a read and errors on every mutating call that carries no label.
///
/// The delegation attributes follow the plane. A plane with a chain carries
/// `owner`, `scope` and `delegation_depth` on every request, and a rule reading
/// them unguarded is correct there. A plane without one never carries them on
/// its own runs — and still admits runs under a caller's chain from a served
/// surface, so both shapes are asked.
///
/// What this does **not** establish: that the rules are *right*. A set that
/// permits everything passes here, as does one whose rules error only on a
/// shape carrying an attribute of an unexpected type. It answers one question
/// — can this plane's own requests be evaluated at all — which is the question
/// whose wrong answer looks like a working plane that refuses everything. The
/// served surfaces ask their own actions with their own contexts, and check
/// those where they are built.
#[cfg_attr(not(feature = "manifest"), allow(dead_code))]
fn preflight_policy(
    engine: &dyn crate::core::PolicyEngine,
    identity: Option<&crate::core::Delegation>,
) -> Result<(), BuildError> {
    let problems = runtime_policy_problems(engine, identity);
    if problems.is_empty() {
        return Ok(());
    }
    Err(BuildError::PolicyUnevaluable {
        problems: problems.join("; "),
    })
}

/// The runtime tier's probes, answered by `engine`.
fn runtime_policy_problems(
    engine: &dyn crate::core::PolicyEngine,
    identity: Option<&crate::core::Delegation>,
) -> Vec<String> {
    use crate::policy::requests;

    // Values are placeholders shaped like the real ones: a rule reading
    // `context.label.trust` on a release must find a label there, or the probe
    // reports a defect the real request would never hit. Nulls are absent for
    // the same reason — no gate sends one, and the adapter strips them.
    let run = RunId(ulid::Ulid::nil());
    let step = StepId(0);
    let label = crate::core::Label::untrusted(crate::core::SourceId::new("preflight"));
    let release = crate::core::Release::whole(
        crate::core::ReleaseScope::trust(),
        "preflight",
        "tool://preflight/probe",
        ["preflight"],
    );
    // A tool call's arguments are the one shape the runtime fixes for a kind,
    // so a rule scoped to `tool.call` may read `context.args.server` as-is.
    let tool_args = serde_json::json!({
        "server": "preflight",
        "tool": "preflight",
        "arguments": {},
        "protected_fields": [],
    });

    // The chain shapes this plane's requests take. A chain of the plane's own
    // is on every request; without one, a run may still carry its caller's.
    let caller = crate::core::Delegation::root(crate::core::Principal::new(
        "preflight",
        crate::core::Scope::root(),
    ));
    let chains: Vec<Option<&crate::core::Delegation>> = match identity {
        Some(chain) => vec![Some(chain)],
        None => vec![None, Some(&caller)],
    };

    // Built by the gates' own builders, so a probe cannot drift from the
    // shape it stands in for: an effect that reads and one that mutates, each
    // with and without a label (only `sink` carries one), a release, and an
    // admission.
    let mut built = Vec::new();
    for chain in chains {
        let acting = requests::Acting {
            tenant: "preflight",
            capability: "preflight.capability",
            agent: None,
            chain,
        };
        for (kind, args) in [
            ("preflight.effect", serde_json::json!({})),
            ("tool.call", tool_args.clone()),
        ] {
            for (mutates, labelled) in [(false, false), (true, false), (false, true), (true, true)]
            {
                built.push(requests::effect(
                    &acting,
                    run,
                    step,
                    kind,
                    &args,
                    mutates,
                    labelled.then_some(&label),
                ));
            }
        }
        built.push(requests::release(&acting, run, step, &release, &label));
        built.push(requests::admission(&acting, &serde_json::json!({})));
    }
    let requests: Vec<crate::core::PolicyRequest<'_>> = built
        .iter()
        .map(requests::GatedRequest::as_request)
        .collect();

    // Asked through the engine's own preflight rather than by calling
    // `authorize` here. An engine written as Rust code has no missing-attribute
    // trap and nothing to report; the engine that has the trap implements the
    // method, and knows which resources its own rules name.
    let mut problems = engine.preflight(&requests);
    problems.sort();
    problems.dedup();
    problems
}

/// Refuse a plane whose stores answer for somebody else.
///
/// The plane's tenant scopes its data keys and names its policy requests; each
/// store handle is scoped separately. Nothing at runtime looks wrong when the
/// two disagree — the work is written into another tenant's keyspace while
/// every erasure and every policy request names the right one — so the mismatch
/// is easy to make and invisible once made. Asking each store who it serves is
/// what turns it into a startup refusal.
///
/// **A store that does not override its accessor answers `default`.** That is
/// the honest answer for a single-tenant deployment and the reason the check
/// can be unconditional, but it is also why this catches a wiring mistake
/// rather than proving isolation: an implementation that is scoped to `acme`
/// and never overrode the accessor reports `default` and is refused, which is
/// the safe direction — the unsafe one would be an implementation that claims a
/// tenant it does not enforce, and no build-time question can settle that.
fn check_same_tenant(
    store: &dyn JournalStore,
    blobs: Option<&Arc<dyn crate::blob::BlobStore>>,
    memories: Option<&Arc<dyn crate::memory::MemoryStore>>,
    state: &[(&'static str, Option<&str>)],
    tenant: &crate::core::TenantId,
) -> Result<(), BuildError> {
    if let Some(blobs) = blobs
        && blobs.tenant() != tenant.as_str()
    {
        return Err(BuildError::BlobStoreTenant {
            plane: tenant.to_string(),
            store: blobs.tenant().to_owned(),
        });
    }
    if store.tenant() != tenant.as_str() {
        return Err(BuildError::JournalStoreTenant {
            plane: tenant.to_string(),
            store: store.tenant().to_owned(),
        });
    }

    // The stores whose state a key ring seals, in the caller's fixed order so a
    // plane with two mismatches reports the same one every build — an error
    // that varies between runs of the same wiring sends an operator looking for
    // a race that is not there.
    for &(store, serves) in state {
        if let Some(serves) = serves
            && serves != tenant.as_str()
        {
            return Err(BuildError::StateStoreTenant {
                store,
                plane: tenant.to_string(),
                tenant: serves.to_owned(),
            });
        }
    }

    // After the tenant checks, deliberately: a store scoped to the wrong tenant
    // is the more basic fault, and reporting the erasure lock first would send
    // an operator to fix the second-most-wrong thing.
    //
    // A process-local erasure lock beside a store two instances can write is a
    // control that reads as present and is not. The window it fails to close is
    // between an erasure's legal-hold check and its key destruction: the other
    // instance writes an item, that item is sealed under a scope about to stop
    // existing, and the erasure reports success. Both facts are here, so the
    // refusal is here.
    if store.is_shared() && memories.is_some_and(|m| m.erasure_is_distributed() == Some(false)) {
        return Err(BuildError::ErasureCoordinatorNotShared);
    }
    Ok(())
}

/// Refuse an event from outside whose kind this plane mints for itself.
fn refuse_reserved_kind(event: &InboundEvent) -> Result<(), RuntimeError> {
    if crate::core::is_reserved_kind(&event.kind) {
        return Err(RuntimeError::ReservedEventKind {
            kind: event.kind.clone(),
        });
    }
    Ok(())
}

/// Inbound event delivery.
impl Runtime {
    /// Deliver an inbound event, resuming whichever run was waiting for it.
    ///
    /// # Ordering
    ///
    /// The event is **stored before** anyone looks for a waiter. That ordering
    /// is the whole reason this works: a message can arrive before its run
    /// reaches the wait, and one that is matched-then-discarded leaves that run
    /// waiting forever for something that already happened.
    ///
    /// A [`Delivery::Buffered`] result is therefore normal and not an error —
    /// it means "held until someone asks". Only the sweep
    /// ([`EventStore::sweep_unclaimed`](crate::case::EventStore::sweep_unclaimed))
    /// decides an event is genuinely unroutable, because that is a claim about
    /// the future rather than about this instant.
    ///
    /// # Errors
    ///
    /// [`RuntimeError::ReservedEventKind`] for a kind in the `agentplane.`
    /// namespace, which only this plane mints; [`RuntimeError`] for a store
    /// failure or a refused resume.
    pub async fn deliver(&self, event: &InboundEvent) -> Result<Delivery, RuntimeError> {
        refuse_reserved_kind(event)?;
        self.deliver_buffered(event, true).await
    }

    /// Deliver an event this plane minted itself — a worklist decision.
    ///
    /// The one path into the reserved namespace [`deliver`](Self::deliver)
    /// refuses from outside.
    pub(crate) async fn deliver_minted(
        &self,
        event: &InboundEvent,
    ) -> Result<Delivery, RuntimeError> {
        self.deliver_buffered(event, false).await
    }

    /// Store `event`, then offer it to the oldest eligible waiter.
    ///
    /// `rematch` offers a duplicate again: the buffer and the match are two
    /// writes, and a counterparty's retry is the one chance to repair a crash
    /// between them. A minted decision is never re-offered, because its
    /// duplicate is the answer *already on record*, and offering that stored
    /// answer under a second decider's call would report it as theirs.
    async fn deliver_buffered(
        &self,
        event: &InboundEvent,
        rematch: bool,
    ) -> Result<Delivery, RuntimeError> {
        let events = self.events.as_ref().ok_or_else(|| {
            RuntimeError::PlanContract(
                "this runtime has no event store — build it with `.events(store)`".into(),
            )
        })?;

        let now = now_for_admission();

        // Durable first. Deduplication by event id makes a counterparty's retry
        // — and they all retry — harmless.
        let fresh = events
            .buffer(event, now)
            .await
            .map_err(RuntimeError::from_store)?;

        // The match claims only an unclaimed, live row, so a retry of a
        // message already consumed matches nothing.
        if !fresh && !rematch {
            return Ok(Delivery::Duplicate);
        }
        let Some(sub) = events
            .match_waiter(event, now)
            .await
            .map_err(RuntimeError::from_store)?
        else {
            return Ok(if fresh {
                Delivery::Buffered
            } else {
                Delivery::Duplicate
            });
        };

        self.resume_subscription(events, sub, event).await
    }

    /// Deliver an inbound event to exactly `run`.
    ///
    /// This is the task-addressed counterpart to [`Runtime::deliver`]. It is
    /// used by protocols such as A2A where a follow-up carries a concrete task
    /// id. Correlation alone is insufficient there: two tasks may wait on the
    /// same business key, and resuming the oldest would violate the request.
    ///
    /// The event store atomically inserts and claims the event for this run. A
    /// run that is not waiting leaves no buffered event behind for another run.
    ///
    /// # Errors
    ///
    /// As [`deliver`](Self::deliver), and [`RuntimeError::PlanContract`] when
    /// `run` is not waiting for this input. Addressing a run by id is no way
    /// around the reserved namespace: a run waiting on a human task is waiting
    /// for exactly the kind this refuses.
    pub async fn deliver_to(
        &self,
        run: RunId,
        event: &InboundEvent,
    ) -> Result<Delivery, RuntimeError> {
        refuse_reserved_kind(event)?;
        let events = self.events.as_ref().ok_or_else(|| {
            RuntimeError::PlanContract(
                "this runtime has no event store — build it with `.events(store)`".into(),
            )
        })?;
        match events
            .deliver_to(run, event, now_for_admission())
            .await
            .map_err(RuntimeError::from_store)?
        {
            crate::case::TargetedDelivery::Duplicate => Ok(Delivery::Duplicate),
            crate::case::TargetedDelivery::NotWaiting => Err(RuntimeError::PlanContract(format!(
                "run {run} is not waiting for this input"
            ))),
            crate::case::TargetedDelivery::Matched(sub) => {
                self.resume_subscription(events, sub, event).await
            }
        }
    }

    async fn resume_subscription(
        &self,
        events: &Arc<dyn crate::case::EventStore>,
        sub: crate::core::Subscription,
        event: &InboundEvent,
    ) -> Result<Delivery, RuntimeError> {
        // Record the event as the awaited effect's result, then let replay do
        // the rest: the resumed run reads it back like any other completed
        // effect, and none of the suspension machinery exists twice.
        //
        // The lease may be briefly held: an event can arrive in the window
        // between the run registering its subscription and its owner finishing
        // the suspension bookkeeping — the owner is *concluding*, and will
        // release within milliseconds. Failing that race would be fatal in the
        // quietest possible way: the delivery fails `LeaseHeld` **after** the
        // event is durably claimed for this run, the counterparty's retry
        // deduplicates against the claimed event, and nothing ever resumes the
        // run — a message that arrived in time, parked forever. So the claim
        // is retried under a bounded backoff; if the owner is genuinely
        // stalled past the bound, the event is *left claimed* for this run
        // and reported as buffered — the sweep's redelivery pass finds a
        // waiting subscription with a claimed event and finishes the job on a
        // later tick, so the bound bounds latency, never delivery.
        let mut backoff = Duration::from_millis(25);
        let lease = loop {
            match self
                .store
                .acquire(sub.run, &self.owner, self.lease_ttl)
                .await
            {
                Ok(lease) => break lease,
                Err(crate::core::StoreError::LeaseHeld { .. })
                    if backoff < Duration::from_secs(1) =>
                {
                    tokio::time::sleep(backoff).await;
                    backoff *= 2;
                }
                Err(crate::core::StoreError::LeaseHeld { .. }) => {
                    // The claim retired the subscription, so nothing lists
                    // this run as waiting any more — and the claimed event
                    // blocks every dedup'd retry of itself. Parking the pair
                    // is what keeps it findable: the sweep's redelivery pass
                    // walks parked waits, re-claims (a claim by the same run
                    // is returned, not filtered), and finishes the delivery
                    // once the owner concludes.
                    events
                        .park_wait(&sub, now_for_admission())
                        .await
                        .map_err(RuntimeError::from_store)?;
                    tracing::warn!(
                        run = %sub.run,
                        event = %event.id,
                        "an event was claimed for a run whose owner did not conclude \
                         within the retry window; the sweep will deliver it"
                    );
                    return Ok(Delivery::Buffered);
                }
                Err(e) => return Err(RuntimeError::from_store(e)),
            }
        };

        let history = self
            .store
            .read(sub.run, 1)
            .await
            .map_err(RuntimeError::from_store)?;
        let already_recorded = history.iter().any(|record| {
            record.effect_key() == Some(sub.effect)
                && matches!(record.kind(), RecordKind::EffectDone { .. })
        });
        // A run whose conclusion is durable consumes nothing. An answer
        // appended after `RunConcluded` is one the run never acted on, and it
        // leaves a run its seal refuses forever. The resume below finishes it
        // instead — seals it and retires its waits, which hands this message,
        // still unconsumed, to the next waiter on its key.
        let closed = resume_is_closed(&history).is_some();
        if !already_recorded && !closed {
            // Judged here, where the output is recorded, under the run's own
            // declaration: the step that resumes reads the verdict back.
            let content = self.delivered_verdict(&history, &event.payload);
            self.store
                .append(
                    lease.epoch,
                    vec![{
                        let mut a = Append::new(
                            sub.run,
                            RecordKind::EffectDone {
                                output: event.payload.clone(),
                                // The sender, so a replayed run rebuilds the same
                                // provenance this delivery gave the value.
                                source: Some(event.source.clone()),
                                // And the operator who minted it, where one
                                // did: the same record on the same path, so a
                                // decision that resumes a suspended run is
                                // attributed exactly as one consumed inline.
                                by: event.by.clone(),
                                spend: crate::core::Spend::default(),
                                // An inbound payload is another party's data,
                                // which is exactly the point this lattice value
                                // names — the same one the run's own delivery
                                // path records.
                                declared: crate::core::DeclaredOutput::untrusted(),
                                content,
                                elapsed_ms: None,
                            },
                        )
                        .effect(sub.effect)
                        .step(sub.step)
                        .phase(sub.phase);
                        // Every record of a case-bound run carries its case, and a
                        // record written from outside the run is no exception.
                        if let Some(c) = sub.case {
                            a = a.case(c);
                        }
                        a
                    }],
                )
                .await
                .map_err(RuntimeError::from_store)?;
        }

        if !closed {
            events
                .unsubscribe(sub.run, sub.effect)
                .await
                .map_err(RuntimeError::from_store)?;
        }

        // The event is recorded as the awaited effect's result, and the resume
        // continues under the *same* lease. Releasing here and letting the
        // resume re-acquire opened the window this function's own doc names —
        // a crash between the release and the acquire left a released lease
        // over a run whose subscription was just retired: no driver, and
        // invisible to the abandonment queue, which lists only leases that
        // expired while still naming an owner. The handover keeps the run
        // owned continuously from delivery to conclusion.
        match self.resume_holding(sub.run, lease).await {
            // A `Fenced` means this lease lapsed mid-resume and somebody
            // claimed the run — a concurrent delivery, a recovery sweep. The
            // event is durably recorded, so whoever holds the lease replays
            // it; this delivery still delivered, and a sender told otherwise
            // retries into a duplicate.
            Ok(_) | Err(RuntimeError::Fenced { .. }) => {}
            // This plane holds no agent for the run — an operator's terminal
            // recording a decision. The answer is durable, and the lease is
            // kept so it lapses owned: that puts the run on the abandonment
            // listing, where the plane that runs the agent recovers it from
            // the recorded answer. Failing here would leave a recorded
            // decision reported as lost and the task it answers still claimed.
            // A plane holding no key ring for a sealed run, or no case store
            // for a case-bound one, is the same terminal: the plane that holds
            // it continues the run.
            Err(
                RuntimeError::NoProvider { .. }
                | RuntimeError::NoCaseStore { .. }
                | RuntimeError::PayloadsSealed { .. },
            ) => {
                return Ok(Delivery::Buffered);
            }
            Err(e) => return Err(e),
        }
        if closed {
            return Ok(Delivery::Buffered);
        }
        Ok(Delivery::Resumed { run: sub.run })
    }

    /// Retire everything a run that concluded closed was still waiting on:
    /// its timers, its event subscriptions and its unanswered tasks.
    ///
    /// A sealed run can record nothing, so each of these left behind is work
    /// the plane keeps doing for nobody — a timer claimed and failed every
    /// lease period, the oldest waiter on a key taking the next event from a
    /// live run behind it, a task offered for a decision no answer reaches.
    ///
    /// Called after every seal of a concluded run — the conclusion's own and
    /// the one resume writes to repair a crash between conclusion and seal —
    /// and idempotent, so retiring twice is harmless.
    ///
    /// After the seal, and best-effort: the conclusion is already durable, and
    /// the stores pass over a sealed run's timers and subscriptions on their
    /// own, so a retirement that fails here costs clutter rather than a
    /// delivery. A task left pending by that failure is withdrawn by nothing
    /// else, which is why the failure is logged loudly.
    async fn retire_waits(&self, run: RunId) {
        if let Some(timers) = &self.timers
            && let Err(error) = timers.disarm_run(run).await
        {
            tracing::error!(%run, %error, "a closed run's timers could not be retired");
        }
        // The waits the run announced and never had answered: a message
        // claimed for one of them reached nobody and goes to the next waiter,
        // and a task opened for one is withdrawn. A task opened beside an
        // answer completes its own effect and is not among them: it is a
        // finding for a desk, and outlives the run by design.
        let unanswered = match self.store.read(run, 1).await {
            Ok(records) => unanswered_waits(&records),
            Err(error) => {
                tracing::error!(%run, %error, "a closed run's waits could not be read to retire them");
                return;
            }
        };
        if let Some(events) = &self.events {
            match events.unsubscribe_run(run, &unanswered).await {
                Ok(retired) => {
                    for event in retired.released {
                        self.offer_released(events, &event).await;
                    }
                }
                Err(error) => {
                    tracing::error!(%run, %error, "a closed run's subscriptions could not be retired");
                }
            }
        }
        if let Some(tasks) = &self.tasks {
            let awaited: Vec<_> = unanswered
                .iter()
                .map(|effect| crate::core::TaskId::derive(run, *effect))
                .collect();
            if let Err(error) = tasks.withdraw_run(run, &awaited).await {
                tracing::error!(%run, %error, "a closed run's open tasks could not be withdrawn");
            }
        }
    }

    /// Offer a message a closed run held, and never consumed, to the next
    /// waiter on its key — the delivery it would have had if that run had not
    /// concluded first. Best effort, like the retirement that released it: a
    /// message no waiter takes now stays buffered for the next one.
    async fn offer_released(
        &self,
        events: &Arc<dyn crate::case::EventStore>,
        event: &InboundEvent,
    ) {
        let sub = match events.match_waiter(event, now_for_admission()).await {
            Ok(Some(sub)) => sub,
            Ok(None) => return,
            Err(error) => {
                tracing::error!(event = %event.id, %error, "a released message could not be offered");
                return;
            }
        };
        if let Err(error) = Box::pin(self.resume_subscription(events, sub, event)).await {
            tracing::error!(event = %event.id, %error, "a released message could not be delivered");
        }
    }

    /// Finish deliveries that died between the claim and the resume.
    ///
    /// A delivery that raced a live owner leaves an event durably claimed for
    /// a run nothing resumed, and the counterparty's retries deduplicate
    /// against that claim — so no future delivery drives the run, and a
    /// message that arrived in time is stranded. The giving-up delivery parks
    /// the pair precisely so it stays findable; this pass walks the parked
    /// waits — never every registered wait, whose long legitimate members
    /// would fill the page ahead of a pair parked after them — re-claims
    /// (idempotently: a claim by the same run is returned, not filtered), and
    /// finishes the delivery. Runs whose owner is *still* live are skipped and
    /// found again next tick, so the delivery's retry bound bounds latency,
    /// never delivery.
    ///
    /// What this does **not** cover, honestly: a crash inside the store
    /// commit between an event's claim and the resume retires the
    /// subscription with nothing left to re-register it, and that window
    /// stays what it always was — recorded rather than closed, with later
    /// events for the same correlation dead-lettering as its symptom.
    pub(crate) async fn redeliver_claimed(
        &self,
        limit: usize,
    ) -> Result<crate::runtime::Redelivered, RuntimeError> {
        let Some(events) = self.events.as_ref() else {
            return Ok(crate::runtime::Redelivered::default());
        };
        let parked = events
            .parked_waits(limit)
            .await
            .map_err(RuntimeError::from_store)?;
        let examined = parked.len();
        let mut delivered = 0usize;
        for sub in parked {
            let Some(buffered) = events
                .claim_for(&sub, now_for_admission())
                .await
                .map_err(RuntimeError::from_store)?
            else {
                continue;
            };
            match self
                .resume_subscription(events, sub.clone(), &buffered.event)
                .await
            {
                Ok(Delivery::Resumed { .. }) => delivered += 1,
                // Still held live: the owner is working, and will either
                // consume the claim itself or conclude and be found next tick.
                Ok(_) => {}
                Err(error) => {
                    tracing::error!(
                        run = %sub.run,
                        %error,
                        "a claimed event's redelivery failed; retried next tick",
                    );
                }
            }
        }
        Ok(crate::runtime::Redelivered {
            finished: delivered,
            examined,
        })
    }

    /// Retire events that nobody claimed within `grace`.
    ///
    /// A non-empty dead-letter list means a correlation key is wrong somewhere:
    /// the message arrived, was held, and no run ever asked for it. That is the
    /// failure which otherwise presents as a process silently never completing,
    /// so it is worth alerting on rather than logging.
    /// `grace` is a `std::time::Duration` for the reason
    /// [`StepCtx::deadline`](crate::runtime::StepCtx::deadline)'s `warn_before`
    /// is: a negative grace window is meaningless, and the signed type could
    /// express it — a cutoff moved *forward* of now, retiring events that had
    /// not yet had their chance. It is also the `Duration` the caller has.
    pub async fn sweep_events(&self, grace: std::time::Duration) -> Result<usize, RuntimeError> {
        let events = self
            .events
            .as_ref()
            .ok_or_else(|| RuntimeError::PlanContract("this runtime has no event store".into()))?;
        // Saturating rather than fallible, at both steps: a grace window
        // beyond what the calendar can hold means "retire nothing", and
        // refusing the call would be a worse answer to a caller asking for a
        // longer hold. The subtraction has to saturate too — `time` panics on
        // underflow, so converting the window to `Duration::MAX` and then
        // subtracting it aborts the tick that also breaches obligations and
        // recovers abandoned runs. The first instant the calendar can name is
        // a cutoff nothing is older than, which is exactly "retire nothing".
        let grace = time::Duration::try_from(grace).unwrap_or(time::Duration::MAX);
        let cutoff = now_for_admission()
            .checked_sub(grace)
            .unwrap_or_else(crate::core::first_instant);
        let retired = events
            .sweep_unclaimed(cutoff, "no run claimed this event within the grace window")
            .await
            .map_err(RuntimeError::from_store)?;

        if retired > 0 {
            // A non-empty dead-letter list means a correlation key is wrong
            // somewhere: the message arrived, was held, and no run ever asked
            // for it. That is the failure which otherwise presents as a process
            // silently never completing.
            tracing::error!(target: telemetry::DEAD_LETTERED, count = retired, %cutoff);
            self.meter
                .count_by(metrics::DEAD_LETTERS, "", retired as u64);
        }
        Ok(retired)
    }
}

/// Every `RunStatus`, so adding one forces a decision everywhere one is owed.
///
/// Written out rather than derived, because Rust cannot enumerate a
/// data-carrying enum. What keeps it honest is **not** the count assertions in
/// its consumers: those fire when somebody edits this list, which is the case
/// that needs no help. A variant added to the enum and forgotten here changes
/// nothing they can see, and every agreement test then walks a list that no
/// longer describes the type — passing over the one variant nobody decided
/// about.
///
/// `every_run_status_variant_is_listed` in `tests/guards` is what closes that:
/// it reads the enum's variants and this function's arms out of the source and
/// holds them to each other, which is the only check available for a list a
/// language cannot derive.
///
/// Crate-visible so those consumers share **one** list. Two copies would be two
/// places to remember, and the second would be the one that went stale — which
/// is the same failure the tests using it exist to catch.
#[cfg(test)]
pub(crate) fn every_status() -> Vec<RunStatus> {
    use crate::core::{BudgetExceeded, CorrelationKey, SuspendReason, Timestamp};
    vec![
        RunStatus::Succeeded,
        RunStatus::Failed("because".into()),
        RunStatus::Suspended(SuspendReason::AwaitingEvent {
            kind: "reply".into(),
            correlation: vec![CorrelationKey::new("claim", "CLM-1")],
            until: Timestamp::from_unix_timestamp(1_760_000_000).expect("time"),
        }),
        RunStatus::Exhausted(BudgetExceeded::Steps { allowed: 1 }),
        RunStatus::Quarantined("unknown outcome".into()),
        RunStatus::Replanning("try again".into()),
        RunStatus::Cancelled {
            actor: crate::core::Operator::asserted("ops").expect("a name"),
            reason: "stop".into(),
        },
        RunStatus::Abandoned {
            actor: crate::core::Operator::asserted("ops").expect("a name"),
            reason: "nobody could establish what happened".into(),
        },
        RunStatus::Swept,
        RunStatus::BrokeGlass {
            actor: crate::core::Operator::asserted("ops").expect("a name"),
            reason: "INC-42".into(),
        },
        RunStatus::HaltLifted {
            actor: crate::core::Operator::asserted("ops").expect("a name"),
        },
        RunStatus::HoldReleased {
            actor: crate::core::Operator::asserted("ops").expect("a name"),
        },
        RunStatus::Withheld {
            subject: "alice".into(),
            reason: "credential withdrawn".into(),
        },
        RunStatus::Observed,
    ]
}

#[cfg(test)]
mod resume_agreement_tests {
    use super::{QuotaPass, RunStatus, resume_is_closed};
    use crate::journal::RecordKind;

    // Through the crate re-export rather than `super::`, so the one path both
    // consumers use is exercised in every build. Reaching it directly here
    // would leave the re-export unused whenever `a2a-server` is off — which is
    // a lint failure in exactly the feature configuration nobody runs locally.
    use crate::runtime::every_status;

    /// **A conclusion that sealed the journal may never be resumed.**
    ///
    /// `RunStatus::seals` decides whether a conclusion freezes the run and
    /// publishes a Merkle leaf; `resume_is_closed` decides whether a recorded
    /// conclusion may be continued. A status that did the first and permits the
    /// second would grow the history past the leaf every later checkpoint
    /// attests — the failure the "a conclusion is not a closure" work removed
    /// for `failed`, reachable again the moment the two disagree.
    ///
    /// The executor's own comment claimed "a test pins the agreement" while no
    /// such test existed, which is the unfalsifiable-guarantee shape this
    /// project treats as a defect in itself: the rule was real, checked by
    /// nobody, and deletable in silence.
    #[test]
    fn a_sealing_conclusion_is_never_resumable() {
        let statuses = every_status();
        assert_eq!(
            statuses.len(),
            14,
            "a RunStatus variant was added or removed — decide whether it seals \
             and whether a resume may continue from it, then update this list"
        );

        for status in &statuses {
            let records = sealed_as(status.as_str());
            let verdict = resume_is_closed(&records);
            if status.seals() {
                assert!(
                    verdict.is_some(),
                    "'{}' seals the journal and enters the Merkle log, yet a resume \
                     is permitted from it — the resume would grow the history past \
                     the leaf every later checkpoint attests",
                    status.as_str()
                );
            }
        }
    }

    /// The availability half: the conclusions that stay open really do.
    ///
    /// Asserted separately and by name rather than as the converse of the rule
    /// above, because the converse is false — `Suspended` and `Replanning` do
    /// not seal either, and neither is ever a recorded conclusion.
    ///
    /// `withheld` is here because it is a **pause**: the authority a run acts
    /// under was withdrawn, its mutations stand, and lifting the halt is what
    /// lets it continue. A withheld run that could not be resumed would make the
    /// withdrawal a destruction rather than a stop.
    #[test]
    fn a_failed_or_exhausted_run_may_still_be_resumed() {
        for outcome in ["failed", "exhausted", super::WITHHELD_OUTCOME] {
            assert!(
                resume_is_closed(&sealed_as(outcome)).is_none(),
                "'{outcome}' is a conclusion a resume must be able to continue \
                 from — its completed effects are read back from history, which \
                 is the point of having a journal"
            );
        }
    }

    /// `SEALED_OUTCOMES` and `RunStatus::seals` are one rule in two spellings,
    /// and this holds them together variant by variant.
    ///
    /// The list exists so a caller wanting every sealed run — the export CLI —
    /// does not restate the rule as string literals in a binary, which is where
    /// a new sealing outcome would have been silently dropped from exactly the
    /// artifact an auditor asks for. Both directions matter: a sealing status
    /// missing from the list loses runs, and a non-sealing status present in it
    /// makes the export ask the outcome index about a backlog that drains.
    #[test]
    fn the_sealed_outcome_list_agrees_with_the_sealing_rule() {
        for status in super::every_status() {
            assert_eq!(
                super::SEALED_OUTCOMES.contains(&status.as_str()),
                status.seals(),
                "'{}' disagrees between RunStatus::seals and SEALED_OUTCOMES — \
                 one rule, two spellings, and the export reads the list",
                status.as_str()
            );
        }
    }

    /// **Every outcome this build writes is one its own reader recognises.**
    ///
    /// The reader is a `match` over `&str` with a catch-all, so it goes on
    /// compiling forever while the writer's list grows — and the catch-all is
    /// not benign: it answers `Quarantined`, so a run this plane sealed itself
    /// reads back as *the runtime could not decide what happened*. Two endings
    /// sat there, `swept` and `broke-glass`, and a break-glass crossing — the
    /// one control whose entire content is who crossed and why — answered the
    /// operator surface with the words "this build does not recognise it" in
    /// place of the reason.
    ///
    /// Held from the writer's side, and the writer's side is
    /// [`every_status`](super::every_status) — every variant the type can
    /// take. `OUTCOMES_OF_RECORD` is the *export's* list and deliberately
    /// omits the endings that stay resumable, so a guard reading it asks about
    /// a subset of what the writer writes and passes while the rest fall
    /// through the catch-all. `withheld` sat there: the one ending whose whole
    /// content is *whose credential was withdrawn*, answering the operator API
    /// with "this build does not recognise it".
    #[test]
    fn every_outcome_this_build_writes_is_one_it_can_read_back() {
        for written in super::every_status() {
            // A suspension is not a conclusion; it has its own record and its
            // own arm in `observed_status`.
            if written.is_suspended() {
                continue;
            }
            let outcome = written.as_str();
            let status = super::recorded_status(
                outcome,
                written.own_account().as_deref(),
                match &written {
                    RunStatus::Exhausted(limit) => Some(limit),
                    _ => None,
                },
                &sealed_as(outcome),
            );
            assert_eq!(
                status.as_str(),
                outcome,
                "this build concludes runs as '{outcome}' and reads that back as \
                 '{}' — a catch-all answering `Quarantined` about a record this \
                 plane wrote itself",
                status.as_str()
            );
        }
    }

    /// **An ending a person caused reports the words that person gave.**
    ///
    /// The conclusion does not carry them: one sentence, one record. So the
    /// reader has to reach the attribution record for the reason exactly as it
    /// already does for the actor, and a reader that only learned the second
    /// half would answer an incident review with a blank where the operator
    /// wrote why.
    #[test]
    fn an_ending_a_person_caused_reports_their_own_words() {
        for (outcome, expected) in [
            ("cancelled", "stop"),
            ("abandoned", "nobody could establish what happened"),
            (super::BREAK_GLASS_OUTCOME, "INC-42"),
            (super::WITHHELD_OUTCOME, "credential withdrawn"),
        ] {
            // `None`, as the conclusion this build writes now carries.
            let status = super::recorded_status(outcome, None, None, &sealed_as(outcome));
            assert_eq!(
                status.reason().as_deref(),
                Some(expected),
                "'{outcome}' lost the reason the person gave: {status:?}"
            );
        }
    }

    /// **An ending nobody is named on is quarantined, not given a name.**
    ///
    /// The chain this build writes always carries the attribution record before
    /// the conclusion; a chain that carries only the conclusion is a crash
    /// between the two appends, or a chain somebody edited. Either way the
    /// record is not trustworthy, and *not trustworthy* is a different bucket
    /// from *an operator called unknown did this*.
    ///
    /// A fabricated actor would be worse than a missing one: indistinguishable
    /// from a real operator with that name, and served through the operator API
    /// as fact.
    #[test]
    fn an_ending_with_no_attribution_record_is_not_given_a_name() {
        for outcome in ["cancelled", "abandoned", super::BREAK_GLASS_OUTCOME] {
            let status =
                super::recorded_status(outcome, Some("why"), None, &concluded_only(outcome));
            assert!(
                matches!(status, RunStatus::Quarantined(_)),
                "'{outcome}' with no record of who asked read back as {status:?} — \
                 an operator act with nobody on it was given a name"
            );
        }
    }

    /// The offline sweep covers every ending, plus the backlog that is not one.
    ///
    /// Held to `SEALED_OUTCOMES` rather than restated, because the failure this
    /// prevents is silent in exactly the artifact nobody re-reads: an ending
    /// added to the runtime and not to the export drops those runs from the
    /// file an auditor is handed, and the file looks complete.
    #[test]
    fn the_offline_sweep_covers_every_ending_and_the_quarantine_backlog() {
        for outcome in super::SEALED_OUTCOMES {
            assert!(
                super::OUTCOMES_OF_RECORD.contains(outcome),
                "'{outcome}' is an ending this plane can reach and the export's \
                 default sweep would silently omit it"
            );
        }
        assert!(
            super::OUTCOMES_OF_RECORD.contains(&"quarantined"),
            "a quarantine is the plane's outstanding unresolved risk and the one \
             thing an auditor is most likely to have come for"
        );
        for open in ["failed", "exhausted", "suspended"] {
            assert!(
                !super::OUTCOMES_OF_RECORD.contains(&open),
                "'{open}' is work in progress that a resume moves on its own — \
                 exporting it is a snapshot of a moving target, not a record"
            );
        }
    }

    /// An outcome this build cannot interpret is never permission to resume.
    #[test]
    fn an_unrecognised_conclusion_fails_closed() {
        let verdict = resume_is_closed(&sealed_as("swept"));
        assert!(
            matches!(verdict, Some(RunStatus::Quarantined(_))),
            "an unrecognised conclusion must quarantine rather than resume: {verdict:?}"
        );
    }

    /// A chain carrying the conclusion and **not** the attribution record.
    ///
    /// The damaged shape, which no healthy write produces: a crash between the
    /// two appends, or an edit. Built by taking the real chain and dropping
    /// everything before the conclusion, so it cannot drift from what
    /// [`sealed_as`] produces.
    fn concluded_only(outcome: &str) -> Vec<crate::journal::Record> {
        let full = sealed_as(outcome);
        full.into_iter()
            .filter(|r| matches!(r.kind(), RecordKind::RunConcluded { .. }))
            .collect()
    }

    /// The chain this build actually writes for an ending.
    ///
    /// **Including the attribution record**, where the ending has one. A
    /// conclusion is never the only record of a cancellation, an abandonment or
    /// a crossing — the runtime appends who asked first — so a fixture holding
    /// the conclusion alone asserts a round trip over a chain this plane does
    /// not produce, and would keep passing if the reader began inventing a
    /// name for the missing half.
    fn sealed_as(outcome: &str) -> Vec<crate::journal::Record> {
        use crate::core::{Digest, Epoch};
        use crate::journal::{Record, RecordBody};

        let run = crate::core::RunId::generate();
        let who = || crate::core::Operator::asserted("ops").expect("a name");
        let mut kinds: Vec<RecordKind> = match outcome {
            "cancelled" => vec![RecordKind::RunCancelled {
                actor: who(),
                reason: "stop".into(),
            }],
            "abandoned" => vec![RecordKind::QuarantineDecided {
                decider: who(),
                reason: "nobody could establish what happened".into(),
                decision: crate::core::QuarantineDecision::Abandon,
            }],
            super::BREAK_GLASS_OUTCOME => vec![RecordKind::BreakGlass {
                actor: who(),
                roles: vec!["oncall".into()],
                reason: "INC-42".into(),
            }],
            super::HALT_LIFTED_OUTCOME => vec![RecordKind::HaltLifted {
                scope: "tenant".into(),
                by: who(),
                at: crate::core::Timestamp::UNIX_EPOCH,
                reason: "INC-42".into(),
                thrown_by: who(),
                thrown_at: crate::core::Timestamp::UNIX_EPOCH,
            }],
            super::HOLD_RELEASED_OUTCOME => vec![RecordKind::HoldReleased {
                by: who(),
                at: crate::core::Timestamp::UNIX_EPOCH,
                placed_by: who(),
                placed_at: crate::core::Timestamp::UNIX_EPOCH,
            }],
            super::WITHHELD_OUTCOME => vec![RecordKind::AuthorityWithheld {
                subject: "alice".into(),
                reason: "credential withdrawn".into(),
                by: who(),
            }],
            _ => Vec::new(),
        };
        kinds.push(RecordKind::RunConcluded {
            outcome: outcome.to_owned(),
            chain_head: Digest::of(b""),
            reason: None,
            exhaustion: None,
            live_spend: crate::core::Spend::default(),
        });

        let mut prev = Digest::of(b"");
        let mut out = Vec::new();
        for (i, kind) in kinds.into_iter().enumerate() {
            let body = RecordBody {
                seq: u64::try_from(i + 1).expect("a small fixture"),
                run,
                case: None,
                step: None,
                phase: super::Phase::Forward,
                epoch: Epoch::default(),
                v: 1,
                effect_key: None,
                kind,
            };
            let record = Record::seal(body, prev).expect("a sealed record");
            prev = record.hash;
            out.push(record);
        }
        out
    }

    /// One execution pass is authorized and accrued against one period even
    /// when it finishes after a billing boundary.
    #[test]
    fn a_quota_pass_keeps_the_period_it_started_in() {
        let quota = crate::quota::TenantQuota {
            max_tokens_per_period: Some(1_000),
            period: crate::quota::Period::Daily,
            ..crate::quota::TenantQuota::default()
        };
        let before_midnight = crate::core::Timestamp::from_unix_timestamp(86_399).unwrap();
        let after_midnight = crate::core::Timestamp::from_unix_timestamp(86_400).unwrap();

        let pass = QuotaPass::at(&quota, before_midnight, true);
        assert_eq!(
            pass.period(),
            Some(quota.period.key_for(before_midnight).as_str())
        );
        assert_ne!(
            pass.period(),
            Some(quota.period.key_for(after_midnight).as_str()),
            "settlement recomputed the period at completion, so this pass was \
             authorized against one ledger and charged to another"
        );
    }
}