//! Handoff primitive: signed state-transfer envelopes between agent runs.
//!
//! Distinct from `klieo-a2a` (in-flight RPC during one workflow) and
//! `klieo-runlog` replay (post-hoc inspection). See spec § 1.7.
//!
//! ## Usage
//!
//! 1. Call `KvHandoff::package` with pre-redacted, CBOR-serialised state
//!    and an Ed25519 `SigningKey`. A `HandoffEnvelope` is returned.
//! 2. Call `KvHandoff::deliver` to persist and route the envelope.
//! 3. The receiving agent calls `KvHandoff::verify` — the only way to
//!    obtain a `HandoffProof`, which grants access to the inner state.

mod envelope;
mod kv_handoff;
mod trait_;

pub use envelope::{EnvelopeSignature, HandoffEnvelope, HandoffProof, MerklePrefixProof};
pub use kv_handoff::KvHandoff;
pub use trait_::{Handoff, HandoffError, HandoffState};

/// Construct a [`KvHandoff`] with `with_audit` auto-wired from the active
/// `SupervisedAgent` run context. Outside a run scope, returns an unaudited
/// instance — no behavioural break.
pub fn audited_handoff(
    kv: std::sync::Arc<dyn klieo_core::KvStore>,
    trust_registry: std::sync::Arc<dyn crate::source_identity_registry::SourceIdentityRegistry>,
) -> KvHandoff {
    let base = KvHandoff::new(kv, trust_registry);
    if let Some(ctx) = crate::run_context::current_run_context() {
        base.with_audit(ctx.episodic, ctx.run_id)
    } else {
        base
    }
}
