soma-som-ring 0.1.0

// SPDX-License-Identifier: LGPL-3.0-only

//! The ring execution engine: cycle lifecycle, extension registration,
//! boundary mediation.
//!
//! [`RingEngine`] owns the complete cycle lifecycle (genesis + standard
//! cycles) and exposes the registration API for the five extension
//! relationships (BEFORE / THROUGH / AFTER / AROUND / WITHIN).
//!
//! ## Spec traceability — OPUS paper
//!
//! | Reference | Topic |
//! |---|---|
//! | OPUS §3 | Five ring relationships |
//! | OPUS §10 | Genesis protocol |
//! | OPUS §11 | Twelve crossings + boundary attestation |
//! | OPUS §13.1 | Pluggable governance trait interfaces |

use crate::boundary::{Boundary, CrossingResult};
use soma_som_core::timing::TimingConfig;
use soma_som_core::NoopSigner;
use std::collections::HashSet;
use std::sync::Arc;
use tracing::{instrument, warn};

use soma_som_core::extension::{
    AfterRing, AroundRing, BeforeRing, CommandSchema, RegistrationError, SiblingManifest,
    ThroughRing, ViewRing,
};
use soma_som_core::fingerprint::{ring_awareness_fingerprint, ring_fingerprint, ring_system_fingerprint};
use soma_som_core::genesis::{Genesis, GenesisResult};
use soma_som_core::ledger::{LedgerEntry, TemporalLedger};
use soma_som_core::lexicon::{
    LexiconEntry, LexiconProvider, Medium, RenderingPack, ResolvedRendering, TermDescription,
};
use soma_som_core::perspectival::{PerspectivalChain, cross_verification_digest, unit_state_hash};
use soma_som_core::quad::{Quad, Tree};
use soma_som_core::ring::Ring;
use soma_som_core::ring_store::RingStore;
use soma_som_core::authorization::PermissionRequirement;
use soma_som_core::traceability::{CycleKind as CycleClass, CycleContext};
use soma_som_core::types::{CrossingType, Layer, UnitId};
use soma_som_core::world::{OrganEntry, WorldRegistry};

// ── Command Registry ────────────────────────────────────────────────────────

/// A registered command handler with its permission metadata.
#[derive(Debug, Clone)]
pub struct CommandRegistryEntry {
    /// Name of the ThroughRing delegate that handles this command.
    pub delegate_name: String,
    /// Permission requirements declared by the delegate.
    pub permissions: Vec<PermissionRequirement>,
    /// Command-type prefixes this delegate claims (e.g., `["user.", "role."]`).
    ///
    /// Populated from `ThroughRing::claimed_prefixes()` at registration time.
    /// Used for prefix-overlap collision detection.
    pub prefixes: Vec<String>,
    /// Payload schemas declared by the delegate.
    ///
    /// Populated from `ThroughRing::command_schemas()` at registration time.
    /// Used for payload validation at FU.Data injection.
    pub schemas: Vec<CommandSchema>,
}

/// Registry of all ThroughRing command handlers, built at registration time.
///
/// Provides bulk enumeration and single-command lookup — the developer-facing
/// counterpart to `probe_namespace()` (which only returns the delegate name).
#[derive(Debug, Clone, Default)]
pub struct CommandRegistry {
    entries: Vec<CommandRegistryEntry>,
}

impl CommandRegistry {
    /// Create an empty registry.
    pub fn new() -> Self {
        Self::default()
    }

    /// Record a delegate, its permission requirements, claimed prefixes, and schemas.
    pub fn register_entry(
        &mut self,
        delegate_name: &str,
        permissions: Vec<PermissionRequirement>,
        prefixes: Vec<String>,
        schemas: Vec<CommandSchema>,
    ) {
        self.entries.push(CommandRegistryEntry {
            delegate_name: delegate_name.to_string(),
            permissions,
            prefixes,
            schemas,
        });
    }

    /// Look up which delegate handles a command type and its permission requirements.
    ///
    /// Searches permission entries for an exact match on the command string.
    /// Returns the entry containing the match. For commands not declared in
    /// any delegate's `permission_requirements()`, returns `None` — the
    /// command may still be handled (via `handles()`) but has no declared
    /// permission metadata.
    pub fn lookup(&self, command_type: &str) -> Option<&CommandRegistryEntry> {
        self.entries
            .iter()
            .find(|e| e.permissions.iter().any(|p| p.command == command_type))
    }

    /// All registered entries (for bulk enumeration).
    pub fn entries(&self) -> &[CommandRegistryEntry] {
        &self.entries
    }

    /// Total number of registered delegates.
    pub fn len(&self) -> usize {
        self.entries.len()
    }

    /// Returns `true` if no delegates are registered.
    pub fn is_empty(&self) -> bool {
        self.entries.is_empty()
    }

    /// Total number of declared permission requirements across all delegates.
    pub fn permission_count(&self) -> usize {
        self.entries.iter().map(|e| e.permissions.len()).sum()
    }

    /// Look up the schema for a specific command type.
    ///
    /// Returns `None` if no schema is declared for this command (no validation).
    pub fn lookup_schema(&self, command_type: &str) -> Option<&CommandSchema> {
        self.entries
            .iter()
            .flat_map(|e| &e.schemas)
            .find(|s| s.command_type == command_type)
    }

    /// Total number of declared schemas across all delegates.
    pub fn schema_count(&self) -> usize {
        self.entries.iter().map(|e| e.schemas.len()).sum()
    }

    /// Check if a new set of prefixes overlaps with any already-registered prefix.
    ///
    /// Two prefixes overlap if either is a prefix of the other (e.g., `"store."`
    /// overlaps with `"store.artifact."`, and `"user."` overlaps with `"user."`).
    /// Returns `Some((new_prefix, existing_delegate))` on first collision.
    pub fn find_prefix_collision<'a>(&'a self, new_prefixes: &'a [String]) -> Option<(&'a str, &'a str)> {
        for new_prefix in new_prefixes {
            for entry in &self.entries {
                for existing in &entry.prefixes {
                    if new_prefix.starts_with(existing.as_str())
                        || existing.starts_with(new_prefix.as_str())
                    {
                        return Some((new_prefix.as_str(), entry.delegate_name.as_str()));
                    }
                }
            }
        }
        None
    }
}
use soma_som_core::crossing::CrossingRecord;
use soma_som_core::envelope::Envelope;

use crate::error::{RingEngineError, RingEngineResult};
use crate::processor::RingProcessor;

// ── Cycle Observer ──────────────────────────────────────────────────────

/// Observer trait for per-unit cycle progress notifications.
///
/// The observer is structurally neutral — it never inspects or modifies
/// payloads, consistent with the engine's role as boundary mediator
/// (per the boundary orchestrator pattern).
pub trait CycleObserver: Send {
    /// Called immediately before a unit begins processing.
    /// `step` is 1-based: 1=FU, 2=MU, 3=CU, 4=OU, 5=SU, 6=HU.
    fn on_unit_enter(&self, unit: UnitId, cycle_index: u64, step: u32);

    /// Called immediately after a unit completes processing.
    fn on_unit_exit(&self, unit: UnitId, cycle_index: u64, step: u32, elapsed_ms: u64);
}

/// No-op observer used by the default `cycle()` method.
pub struct NoOpObserver;

impl CycleObserver for NoOpObserver {
    #[inline(always)]
    fn on_unit_enter(&self, _unit: UnitId, _cycle_index: u64, _step: u32) {}
    #[inline(always)]
    fn on_unit_exit(&self, _unit: UnitId, _cycle_index: u64, _step: u32, _elapsed_ms: u64) {}
}

// ── Reports ─────────────────────────────────────────────────────────────

/// Result of a completed genesis cycle.
#[derive(Debug, Clone)]
pub struct GenesisReport {
    /// Ledger entry produced by the genesis cycle.
    pub genesis: GenesisResult,
    /// Attested boundary crossings recorded during genesis.
    pub crossing_records: Vec<CrossingRecord>,
    /// Ed25519 verifying key for boundary crossing verification.
    pub boundary_verifying_key: [u8; 32],
    /// BLAKE3 digest over all crossing records from genesis.
    pub cross_verification_digest: [u8; 32],
    /// Ring identity for federation — BLAKE3(b"ring:" || system_fp || boundary_key).
    pub ring_fingerprint: [u8; 32],
}

/// Result of a completed standard cycle.
#[derive(Debug, Clone)]
pub struct CycleReport {
    /// Sequential index of this cycle (1-based after genesis).
    pub cycle_index: u64,
    /// BLAKE3 fingerprint of all awareness-layer envelopes in this cycle.
    pub awareness_fingerprint: [u8; 32],
    /// BLAKE3 fingerprint of all system-layer envelopes in this cycle.
    pub system_fingerprint: [u8; 32],
    /// Cumulative chain hash linking this cycle to prior state.
    pub chain_hash: [u8; 32],
    /// BLAKE3 digest over all crossing records from this cycle.
    pub cross_verification_digest: [u8; 32],
    /// Wall-clock duration of the cycle in milliseconds.
    pub elapsed_ms: u64,
    /// Attested boundary crossings recorded during this cycle.
    pub crossing_records: Vec<CrossingRecord>,
    /// Semantic cycle context extracted from ring state after cycle completion.
    pub context: CycleContext,
    /// Ring identity for federation — BLAKE3(b"ring:" || system_fp || boundary_key).
    pub ring_fingerprint: [u8; 32],
}

// ── RingEngine ──────────────────────────────────────────────────────────

/// The standalone ring execution engine.
///
/// ## Extension lifecycle
///
/// Standard cycle:
/// 1. BEFORE gates evaluate (short-circuit on first rejection)
/// 2. AROUND extensions inject into FU.Data
/// 3. Ring traversal (6 units, 12 crossings)
/// 4. WITHIN store persists
/// 5. AFTER observers + AROUND observers notified
/// 6. BEFORE gates receive feedback
pub struct RingEngine {
    // ── Ring state ──
    ring: Ring,
    boundary: Boundary,
    ledger: TemporalLedger,
    perspectival_chains: [PerspectivalChain; 6],
    genesis_seed: Vec<u8>,
    latest_cross_verification: Option<[u8; 32]>,
    genesis_complete: bool,
    /// Ring identity derived at genesis — stable across cycles.
    genesis_ring_fingerprint: [u8; 32],

    // ── Processors ──
    processors: [Option<Box<dyn RingProcessor>>; 6],

    // ── Extensions (P2 traits) ──
    before_gates: Vec<Box<dyn BeforeRing>>,
    through_delegates: Vec<Arc<dyn ThroughRing>>,
    view_delegates: Vec<Arc<dyn ViewRing>>,
    after_observers: Vec<Box<dyn AfterRing>>,
    around_extensions: Vec<Box<dyn AroundRing>>,
    within_store: Option<Box<dyn RingStore>>,

    // ── Lexicon providers ──
    lexicon_providers: Vec<Box<dyn LexiconProvider>>,

    // ── Rendering packs ──
    rendering_packs: Vec<RenderingPack>,

    // ── World registry ──
    // Built incrementally during register_lexicon(). Each organ declares
    // its constitutive world position — frozen at startup, not recomputed.
    world_registry: WorldRegistry,

    // ── Command registry ──
    command_registry: CommandRegistry,

    // ── Extension name registry ──
    registered_names: HashSet<String>,
}

#[allow(missing_docs)]
impl RingEngine {
    // ── Construction ────────────────────────────────────────────────────

    pub fn new(timing_config: TimingConfig) -> Self {
        Self {
            ring: Ring::new(),
            boundary: Boundary::new(Box::new(NoopSigner), timing_config),
            ledger: TemporalLedger::new(),
            perspectival_chains: [
                PerspectivalChain::new(UnitId::FU),
                PerspectivalChain::new(UnitId::MU),
                PerspectivalChain::new(UnitId::CU),
                PerspectivalChain::new(UnitId::OU),
                PerspectivalChain::new(UnitId::SU),
                PerspectivalChain::new(UnitId::HU),
            ],
            genesis_seed: Vec::new(),
            latest_cross_verification: None,
            genesis_complete: false,
            genesis_ring_fingerprint: [0u8; 32],
            processors: [None, None, None, None, None, None],
            before_gates: Vec::new(),
            through_delegates: Vec::new(),
            view_delegates: Vec::new(),
            after_observers: Vec::new(),
            around_extensions: Vec::new(),
            within_store: None,
            lexicon_providers: Vec::new(),
            rendering_packs: Vec::new(),
            command_registry: CommandRegistry::new(),
            world_registry: WorldRegistry::new(),
            registered_names: HashSet::new(),
        }
    }

    pub fn with_test_config(_boundary_secret: &[u8; 32]) -> Self {
        Self {
            ring: Ring::new(),
            boundary: Boundary::new(Box::new(NoopSigner), TimingConfig::default()),
            ledger: TemporalLedger::new(),
            perspectival_chains: [
                PerspectivalChain::new(UnitId::FU),
                PerspectivalChain::new(UnitId::MU),
                PerspectivalChain::new(UnitId::CU),
                PerspectivalChain::new(UnitId::OU),
                PerspectivalChain::new(UnitId::SU),
                PerspectivalChain::new(UnitId::HU),
            ],
            genesis_seed: Vec::new(),
            latest_cross_verification: None,
            genesis_complete: false,
            genesis_ring_fingerprint: [0u8; 32],
            processors: [None, None, None, None, None, None],
            before_gates: Vec::new(),
            through_delegates: Vec::new(),
            view_delegates: Vec::new(),
            after_observers: Vec::new(),
            around_extensions: Vec::new(),
            within_store: None,
            lexicon_providers: Vec::new(),
            rendering_packs: Vec::new(),
            command_registry: CommandRegistry::new(),
            world_registry: WorldRegistry::new(),
            registered_names: HashSet::new(),
        }
    }

    // ── Processor management ────────────────────────────────────────────

    pub fn set_processor(&mut self, unit: UnitId, processor: Box<dyn RingProcessor>) {
        self.processors[unit.index()] = Some(processor);
    }

    pub fn set_all_processors<F>(&mut self, factory: F)
    where
        F: Fn() -> Box<dyn RingProcessor>,
    {
        for &unit in &UnitId::ALL {
            self.processors[unit.index()] = Some(factory());
        }
    }

    pub fn disable(&mut self, unit: UnitId) {
        self.processors[unit.index()] = None;
    }

    pub fn is_unit_enabled(&self, unit: UnitId) -> bool {
        self.processors[unit.index()].is_some()
    }

    pub fn active_units(&self) -> Vec<UnitId> {
        UnitId::ALL
            .iter()
            .filter(|&&u| self.is_unit_enabled(u))
            .copied()
            .collect()
    }

    // ── Extension registration ────────────────────────────────

    pub fn register_before(&mut self, ext: Box<dyn BeforeRing>) {
        self.registered_names.insert(ext.name().to_string());
        self.before_gates.push(ext);
    }

    pub fn register_after(&mut self, ext: Box<dyn AfterRing>) {
        self.registered_names.insert(ext.name().to_string());
        self.after_observers.push(ext);
    }

    /// Register a ThroughRing delegate with prefix-overlap collision detection.
    ///
    /// If the delegate declares `claimed_prefixes()`, each prefix is checked
    /// against all previously registered prefixes. Two prefixes overlap if
    /// either is a prefix of the other — this catches both identical claims
    /// and subset/superset conflicts.
    ///
    /// Returns `Err(RegistrationError::NamespaceConflict)` on collision.
    /// Delegates with empty `claimed_prefixes()` skip the check (backward compat).
    pub fn register_through(
        &mut self,
        ext: Arc<dyn ThroughRing>,
    ) -> Result<(), RegistrationError> {
        let prefixes = ext.claimed_prefixes();

        // Prefix-overlap collision detection
        if !prefixes.is_empty() {
            if let Some((prefix, claimed_by)) =
                self.command_registry.find_prefix_collision(&prefixes)
            {
                return Err(RegistrationError::NamespaceConflict {
                    prefix: prefix.to_string(),
                    claimed_by: claimed_by.to_string(),
                });
            }
        }

        let schemas = ext.command_schemas();
        self.registered_names.insert(ext.name().to_string());
        self.command_registry
            .register_entry(ext.name(), ext.permission_requirements(), prefixes, schemas);
        self.through_delegates.push(ext);
        Ok(())
    }

    pub fn register_around(&mut self, ext: Box<dyn AroundRing>) {
        self.registered_names.insert(ext.name().to_string());
        self.around_extensions.push(ext);
    }

    /// Register a ViewRing delegate.
    ///
    /// Parallel to [`Self::register_through`] but for view projection. Each delegate
    /// claims view-id prefixes via `claimed_view_prefixes()`; collisions raise
    /// `RegistrationError::NamespaceConflict`. Delegates with empty prefix
    /// lists register unconditionally (backward compatible — no collision
    /// check).
    pub fn register_view(
        &mut self,
        ext: Arc<dyn ViewRing>,
    ) -> Result<(), RegistrationError> {
        let prefixes = ext.claimed_view_prefixes();

        if !prefixes.is_empty() {
            // Linear scan: view_delegates is O(few), not a hot path.
            for existing in &self.view_delegates {
                for existing_prefix in existing.claimed_view_prefixes() {
                    for new_prefix in &prefixes {
                        if existing_prefix.starts_with(new_prefix.as_str())
                            || new_prefix.starts_with(existing_prefix.as_str())
                        {
                            return Err(RegistrationError::NamespaceConflict {
                                prefix: new_prefix.clone(),
                                claimed_by: existing.name().to_string(),
                            });
                        }
                    }
                }
            }
        }

        self.registered_names.insert(ext.name().to_string());
        self.view_delegates.push(ext);
        Ok(())
    }

    pub fn register_within(&mut self, store: Box<dyn RingStore>) {
        self.within_store = Some(store);
    }

    // ── Lexicon registration ──────────────────────────────────

    /// Register a lexicon provider for organ vocabulary discovery.
    ///
    /// Also registers the organ in the world registry using its declared
    /// `primary_world()` — the organ's constitutive world position.
    ///
    /// Registration is idempotent: re-registering the same domain replaces
    /// the previous provider and world registry entry.
    ///
    /// Returns `Err(RegistrationError::CoordinateValidation)` if any vocabulary
    /// entry's unit coordinate does not match the organ's declared unit.
    pub fn register_lexicon(
        &mut self,
        provider: Box<dyn LexiconProvider>,
    ) -> Result<(), RegistrationError> {
        let domain = provider.domain().to_string();
        provider.validate_coordinates().map_err(|e| {
            RegistrationError::CoordinateValidation(format!("domain '{domain}': {e:?}"))
        })?;
        let world = provider.primary_world();
        // Collect rendering packs before borrowing provider
        let new_packs = provider.renderings();
        self.lexicon_providers.retain(|p| p.domain() != domain);
        // Remove old packs for this domain scope
        let organ_scope = format!("organ:{domain}");
        self.rendering_packs.retain(|p| p.scope != organ_scope);
        self.rendering_packs.extend(new_packs);
        self.world_registry.register(
            world,
            OrganEntry {
                name: domain.to_uppercase(),
                namespace: domain.clone(),
            },
        );
        self.lexicon_providers.push(provider);
        Ok(())
    }

    /// Query all registered vocabulary entries across all providers.
    pub fn lexicon_vocabulary(&self) -> Vec<LexiconEntry> {
        self.lexicon_providers
            .iter()
            .flat_map(|p| p.vocabulary())
            .collect()
    }

    /// Describe a term by key, searching across all providers.
    ///
    /// The key prefix determines which provider is queried. Returns
    /// `None` if no provider claims the term.
    pub fn lexicon_describe(&self, key: &str) -> Option<TermDescription> {
        for provider in &self.lexicon_providers {
            let domain = provider.domain();
            if key.starts_with(&format!("{domain}.")) {
                return provider.describe(key);
            }
        }
        None
    }

    /// List all registered lexicon domains.
    pub fn lexicon_domains(&self) -> Vec<&str> {
        self.lexicon_providers.iter().map(|p| p.domain()).collect()
    }

    /// All registered rendering packs (Layer 2).
    pub fn lexicon_rendering_packs(&self) -> &[RenderingPack] {
        &self.rendering_packs
    }

    /// Resolve a term to rendered content using the 6-step fallback chain.
    ///
    /// Delegates to [`soma_som_core::lexicon::resolve_rendering`] with the
    /// engine's accumulated packs and vocabulary.
    pub fn lexicon_resolve(
        &self,
        term_key: &str,
        medium: Medium,
        locale: &str,
    ) -> ResolvedRendering {
        let vocabulary = self.lexicon_vocabulary();
        soma_som_core::lexicon::resolve_rendering(
            term_key,
            medium,
            locale,
            &self.rendering_packs,
            &vocabulary,
        )
    }

    /// The world registry — organ→world mapping built at registration time.
    ///
    /// Returns a reference to the frozen registry. Zero allocation.
    /// Each organ declared its primary world during `register_lexicon()`.
    pub fn world_registry(&self) -> &WorldRegistry {
        &self.world_registry
    }

    // ── Sibling registration ────────────────────────────────────

    /// The current ring version for manifest compatibility checks.
    pub const RING_VERSION: &'static str = "1.0.0";

    /// Register a hosted solitaire (sibling) through the four-stage lifecycle:
    ///
    /// 1. **Validate:** Check name uniqueness, namespace collision, version compat
    /// 2. **Provision:** Call the provisioner callback for STORE domain creation
    /// 3. **Register:** Add extension trait objects to the engine
    /// 4. **Activate:** Sibling is live and receiving commands
    ///
    /// The `provisioner` callback bridges to STORE without the engine depending
    /// on soma-store. Pass `None` if the sibling has no persistence domains.
    ///
    /// On failure, no partial state is left — registration is atomic.
    pub fn register_sibling<F>(
        &mut self,
        manifest: &dyn SiblingManifest,
        provisioner: Option<F>,
    ) -> Result<(), RegistrationError>
    where
        F: FnMut(&soma_som_core::extension::DomainRequest) -> Result<(), String>,
    {
        // ── Stage 1: Validate ──────────────────────────────────────
        let sibling_id = manifest.id();

        // 1a. Duplicate ID check
        if self.registered_names.contains(sibling_id) {
            return Err(RegistrationError::DuplicateId(sibling_id.to_string()));
        }

        // 1b. Version compatibility
        let min_version = manifest.min_ring_version();
        if !Self::version_compatible(min_version, Self::RING_VERSION) {
            return Err(RegistrationError::IncompatibleVersion {
                required: min_version.to_string(),
                running: Self::RING_VERSION.to_string(),
            });
        }

        // 1c. Namespace collision detection (Gap G2)
        // Probe existing ThroughRing delegates with sibling.{id}.__probe__
        let prefix = format!("sibling.{sibling_id}.");
        let probe = format!("{prefix}__probe__");
        for delegate in &self.through_delegates {
            if delegate.handles(&probe) {
                return Err(RegistrationError::NamespaceConflict {
                    prefix,
                    claimed_by: delegate.name().to_string(),
                });
            }
        }

        // Also check if the manifest's through_handler would collide with
        // existing delegates' namespaces (reverse collision).
        if let Some(ref handler) = manifest.through_handler() {
            for delegate in &self.through_delegates {
                let existing_name = delegate.name();
                let existing_probe = format!("sibling.{existing_name}.__probe__");
                if handler.handles(&existing_probe) {
                    return Err(RegistrationError::NamespaceConflict {
                        prefix: prefix.clone(),
                        claimed_by: existing_name.to_string(),
                    });
                }
            }
        }

        // ── Stage 2: Provision ─────────────────────────────────────
        let domains = manifest.persistence_domains();
        if !domains.is_empty() {
            if let Some(mut prov) = provisioner {
                for domain in &domains {
                    prov(domain).map_err(RegistrationError::ProvisionFailed)?;
                }
            }
        }

        // ── Stage 3: Register ──────────────────────────────────────
        // Extract all extensions first, then register. If through_handler
        // was already borrowed for validation, call it again.
        if let Some(through) = manifest.through_handler() {
            self.registered_names.insert(through.name().to_string());
            let prefixes = through.claimed_prefixes();
            let schemas = through.command_schemas();
            self.command_registry
                .register_entry(through.name(), through.permission_requirements(), prefixes, schemas);
            self.through_delegates.push(through);
        }
        if let Some(before) = manifest.before_gate() {
            self.registered_names.insert(before.name().to_string());
            self.before_gates.push(before);
        }
        if let Some(after) = manifest.after_observer() {
            self.registered_names.insert(after.name().to_string());
            self.after_observers.push(after);
        }
        if let Some(around) = manifest.around_extension() {
            self.registered_names.insert(around.name().to_string());
            self.around_extensions.push(around);
        }

        // ── Stage 4: Activate ──────────────────────────────────────
        // Track the sibling ID itself for duplicate detection.
        self.registered_names.insert(sibling_id.to_string());

        Ok(())
    }

    /// Simple semver major.minor compatibility: running >= required.
    fn version_compatible(required: &str, running: &str) -> bool {
        let parse = |s: &str| -> (u32, u32, u32) {
            let mut parts = s.split('.');
            let major = parts.next().and_then(|p| p.parse().ok()).unwrap_or(0);
            let minor = parts.next().and_then(|p| p.parse().ok()).unwrap_or(0);
            let patch = parts.next().and_then(|p| p.parse().ok()).unwrap_or(0);
            (major, minor, patch)
        };
        let req = parse(required);
        let run = parse(running);
        run >= req
    }

    // ── Accessors ───────────────────────────────────────────────────────

    pub fn ring(&self) -> &Ring {
        &self.ring
    }

    pub fn ring_mut(&mut self) -> &mut Ring {
        &mut self.ring
    }

    pub fn ledger(&self) -> &TemporalLedger {
        &self.ledger
    }

    pub fn boundary_verifying_key(&self) -> [u8; 32] {
        self.boundary.verifying_key_bytes()
    }

    pub fn is_genesis_complete(&self) -> bool {
        self.genesis_complete
    }

    pub fn cycle_index(&self) -> u64 {
        self.ring.cycle_index
    }

    pub fn persist_store(&self) -> Option<&dyn RingStore> {
        self.within_store.as_deref()
    }

    pub fn has_persistence(&self) -> bool {
        self.within_store.is_some()
    }

    pub fn perspectival_chain(&self, unit: UnitId) -> &PerspectivalChain {
        &self.perspectival_chains[unit.index()]
    }

    pub fn cross_verification_digest(&self) -> Option<[u8; 32]> {
        self.latest_cross_verification
    }

    pub fn awareness_fingerprint(&self) -> [u8; 32] {
        ring_awareness_fingerprint(&self.ring)
    }

    pub fn system_fingerprint(&self) -> [u8; 32] {
        ring_system_fingerprint(&self.ring)
    }

    /// Ring identity derived at genesis — stable across cycles.
    pub fn ring_fingerprint(&self) -> [u8; 32] {
        self.genesis_ring_fingerprint
    }

    pub fn before_gate_count(&self) -> usize {
        self.before_gates.len()
    }
    pub fn after_observer_count(&self) -> usize {
        self.after_observers.len()
    }
    /// Returns the number of registered ThroughRing delegates.
    pub fn through_delegate_count(&self) -> usize {
        self.through_delegates.len()
    }

    /// Probe whether any registered ThroughRing delegate claims a command type.
    ///
    /// Returns the name of the claiming delegate, or `None` if no delegate
    /// handles this command type.
    ///
    /// This is the **only** external access to ThroughRing delegates.
    /// The dispatch surface (`dispatch()`) is internal to the ring cycle —
    /// OU calls it during ring traversal. External code cannot dispatch
    /// commands directly; they must enter through FU.Data and be mediated
    /// by the ring (BEFORE gates, CU authorization, crossing attestation).
    pub fn probe_namespace(&self, command_type: &str) -> Option<&str> {
        for delegate in &self.through_delegates {
            if delegate.handles(command_type) {
                return Some(delegate.name());
            }
        }
        None
    }

    /// Returns the command registry — all registered ThroughRing delegates
    /// with their permission metadata. Built incrementally at registration time.
    pub fn command_registry(&self) -> &CommandRegistry {
        &self.command_registry
    }

    pub fn around_extension_count(&self) -> usize {
        self.around_extensions.len()
    }

    /// Names of all registered extensions.
    pub fn registered_names(&self) -> &HashSet<String> {
        &self.registered_names
    }

    /// Returns true if an extension with this name is already registered.
    pub fn has_registered_name(&self, name: &str) -> bool {
        self.registered_names.contains(name)
    }

    // ── Genesis cycle (t = 0) ───────────────────────────────────────────

    /// Run the genesis cycle.
    ///
    /// ## SAD §5.1: Genesis Cycle
    ///
    /// 1. Initialize ring with seed s₀.
    /// 2. Drive the pipeline: FU → MU → CU → OU → SU → HU.
    /// 3. Compute F_system^(0) from all 90 positions.
    /// 4. Close ring: transition from pipeline to ring mode.
    /// 5. Record genesis in the temporal ledger.
    #[instrument(skip_all, name = "ring.genesis")]
    pub fn genesis(&mut self, seed: &[u8]) -> RingEngineResult<GenesisReport> {
        if self.genesis_complete {
            return Err(RingEngineError::GenesisAlreadyComplete);
        }

        for &unit in &UnitId::ALL {
            if !self.is_unit_enabled(unit) {
                return Err(RingEngineError::UnitDisabled { unit });
            }
        }

        let mut genesis = Genesis::new(seed.to_vec());
        genesis.initialize_ring(&mut self.ring)?;

        let seed_hash = *blake3::hash(seed).as_bytes();
        self.boundary.begin_cycle(0, seed_hash)?;

        let mut current_quad = self.build_genesis_input_quad(seed);

        for &unit in &UnitId::ALL {
            let successor = unit.successor();

            self.boundary.start_unit_timer(unit)?;
            let output_quad = self.run_processor(unit, 0, &current_quad)?;
            self.boundary.end_unit_timer(unit)?;

            self.deposit_server_output(unit, &output_quad);

            let envelope = Envelope::new(0, unit, output_quad.clone());
            let crossing_result = self.boundary.process_crossing(&envelope, unit, successor)?;

            let h_envelope = Envelope::with_crossing_type(
                0,
                unit,
                CrossingType::Horizontal,
                output_quad.clone(),
            );
            let h_crossing = self.boundary.process_crossing(&h_envelope, unit, unit)?;
            self.run_horizontal_path(unit, 0, &h_crossing)?;

            genesis.mark_completed(unit)?;
            current_quad = crossing_result.delivery_envelope.quad;
        }

        let (_final_chain_hash, crossing_records) = self.boundary.end_cycle()?;
        let genesis_result = genesis.close_ring(&mut self.ring)?;

        // Perspectival chain genesis
        let mut persp_hashes = [[0u8; 32]; 6];
        for (i, &unit) in UnitId::ALL.iter().enumerate() {
            let state_hash = unit_state_hash(self.ring.unit(unit));
            let entry = self.perspectival_chains[i].commit_genesis(state_hash, seed)?;
            persp_hashes[i] = entry.perspectival_hash;
        }
        let xv_digest = cross_verification_digest(&persp_hashes);
        self.latest_cross_verification = Some(xv_digest);
        self.genesis_seed = seed.to_vec();

        let fu_data = self.ring.unit_mut(UnitId::FU).som_quad_mut(Layer::Data);
        fu_data.tree.insert(
            "perspectival.cross_verification_digest".into(),
            xv_digest.to_vec(),
        );

        let awareness_fp = ring_awareness_fingerprint(&self.ring);
        self.ledger.record_genesis(
            awareness_fp,
            genesis_result.system_fingerprint,
            genesis_result.genesis_hash,
            CycleContext::genesis(),
        )?;

        self.genesis_complete = true;
        self.persist_after_genesis(&crossing_records, seed);

        self.genesis_ring_fingerprint = ring_fingerprint(
            &genesis_result.system_fingerprint,
            &self.boundary.verifying_key_bytes(),
        );

        Ok(GenesisReport {
            genesis: genesis_result,
            crossing_records,
            boundary_verifying_key: self.boundary.verifying_key_bytes(),
            cross_verification_digest: xv_digest,
            ring_fingerprint: self.genesis_ring_fingerprint,
        })
    }

    // ── Standard ring cycle (t > 0) ─────────────────────────────────────

    #[instrument(skip_all, name = "ring.cycle")]
    pub fn cycle(&mut self) -> RingEngineResult<CycleReport> {
        self.cycle_observed(&NoOpObserver)
    }

    /// Run a standard ring cycle with per-unit observer notifications
    /// and the full extension lifecycle.
    #[instrument(skip_all, name = "ring.cycle_observed")]
    pub fn cycle_observed(
        &mut self,
        observer: &dyn CycleObserver,
    ) -> RingEngineResult<CycleReport> {
        if !self.genesis_complete {
            return Err(RingEngineError::NotInitialized);
        }

        let cycle_index = self.ring.cycle_index + 1;

        // ── Phase 1: BEFORE gates evaluate ──────────────────────────
        let fu_data_tree = &self.ring.unit(UnitId::FU).som_quad(Layer::Data).tree;
        for gate in &self.before_gates {
            gate.evaluate(fu_data_tree)?;
        }

        // ── Phase 2: AROUND inject ──────────────────────────────────
        {
            let fu_data = &mut self
                .ring
                .unit_mut(UnitId::FU)
                .som_quad_mut(Layer::Data)
                .tree;
            for around in &self.around_extensions {
                around.inject(fu_data);
            }
        }

        let prev_chain_hash = self
            .ledger
            .chain_head()
            .ok_or(RingEngineError::NotInitialized)?;

        self.boundary.begin_cycle(cycle_index, prev_chain_hash)?;

        let fu_data = self.ring.unit(UnitId::FU).som_quad(Layer::Data).clone();
        let mut current_quad = fu_data;

        // ── Phase 3: Ring traversal (12 crossings) ──────────────────
        for (step_idx, &unit) in UnitId::ALL.iter().enumerate() {
            let step = (step_idx as u32) + 1;
            let successor = unit.successor();

            if !self.is_unit_enabled(unit) {
                let _ = self.boundary.end_cycle();
                return Err(RingEngineError::UnitDisabled { unit });
            }

            observer.on_unit_enter(unit, cycle_index, step);
            let unit_start = std::time::Instant::now();

            self.boundary.start_unit_timer(unit)?;
            let server_output = self.run_processor(unit, cycle_index, &current_quad)?;
            self.boundary.end_unit_timer(unit)?;

            self.deposit_server_output(unit, &server_output);

            // Vertical crossing: u.Server → σ(u).Server
            let v_envelope = Envelope::with_crossing_type(
                cycle_index,
                unit,
                CrossingType::Vertical,
                server_output.clone(),
            );
            let v_crossing = self
                .boundary
                .process_crossing(&v_envelope, unit, successor)?;
            current_quad = v_crossing.delivery_envelope.quad;

            // Horizontal crossing: u.Server → u.Client
            let h_envelope = Envelope::with_crossing_type(
                cycle_index,
                unit,
                CrossingType::Horizontal,
                server_output.clone(),
            );
            let h_crossing = self.boundary.process_crossing(&h_envelope, unit, unit)?;
            self.run_horizontal_path(unit, cycle_index, &h_crossing)?;

            let unit_elapsed_ms = unit_start.elapsed().as_millis() as u64;
            observer.on_unit_exit(unit, cycle_index, step, unit_elapsed_ms);
        }

        let (_final_chain_hash, crossing_records) = self.boundary.end_cycle()?;

        let elapsed_ms = match (crossing_records.first(), crossing_records.last()) {
            (Some(first), Some(last)) => {
                last.timestamp_ns.saturating_sub(first.timestamp_ns) / 1_000_000
            }
            _ => 0,
        };

        let pre_deposit_awareness = ring_awareness_fingerprint(&self.ring);
        let pre_deposit_system = ring_system_fingerprint(&self.ring);

        // Perspectival chain commits
        let mut persp_hashes = [[0u8; 32]; 6];
        for (i, &unit) in UnitId::ALL.iter().enumerate() {
            let state_hash = unit_state_hash(self.ring.unit(unit));
            let entry = self.perspectival_chains[i].commit(state_hash)?;
            persp_hashes[i] = entry.perspectival_hash;
        }

        let xv_digest = cross_verification_digest(&persp_hashes);
        self.latest_cross_verification = Some(xv_digest);

        // Extract semantic context from ring state after cycle execution.
        let cycle_context = self.extract_cycle_context();

        let entry: LedgerEntry = self.ledger.record_cycle(
            pre_deposit_awareness,
            pre_deposit_system,
            cycle_context.clone(),
        )?;

        self.deposit_cycle_result(cycle_index, &entry);

        let fu_data = self.ring.unit_mut(UnitId::FU).som_quad_mut(Layer::Data);
        fu_data.tree.insert(
            "perspectival.cross_verification_digest".into(),
            xv_digest.to_vec(),
        );

        self.ring.cycle_index = cycle_index;

        let awareness_fp = ring_awareness_fingerprint(&self.ring);
        let system_fp = ring_system_fingerprint(&self.ring);

        // ── Phase 4: WITHIN persist ─────────────────────────────────
        self.persist_after_cycle(cycle_index, &crossing_records);

        // ── Phase 5: AFTER + AROUND observe ─────────────────────────
        {
            let ou_output = &self.ring.unit(UnitId::OU).som_quad(Layer::Server).tree;
            let su_output = &self.ring.unit(UnitId::SU).som_quad(Layer::Server).tree;

            for after in &self.after_observers {
                after.on_cycle_complete(cycle_index, ou_output);
                after.on_crossings(cycle_index, &crossing_records);
            }
            for around in &self.around_extensions {
                around.observe(cycle_index, ou_output, su_output);
            }
        }

        // ── Phase 6: BEFORE feedback ────────────────────────────────
        {
            let ou_output = &self.ring.unit(UnitId::OU).som_quad(Layer::Server).tree;
            for gate in &self.before_gates {
                gate.feedback(cycle_index, ou_output);
            }
        }

        Ok(CycleReport {
            cycle_index,
            awareness_fingerprint: awareness_fp,
            system_fingerprint: system_fp,
            chain_hash: entry.chain_hash,
            cross_verification_digest: xv_digest,
            elapsed_ms,
            crossing_records,
            context: cycle_context,
            ring_fingerprint: self.genesis_ring_fingerprint,
        })
    }

    pub fn run_cycles(&mut self, count: u32) -> Vec<RingEngineResult<CycleReport>> {
        (0..count).map(|_| self.cycle()).collect()
    }

    // ── Verification ────────────────────────────────────────────────────

    pub fn verify_chain(&self) -> RingEngineResult<()> {
        self.ledger.verify_chain()?;
        Ok(())
    }

    pub fn verify_perspectival_chains(&self) -> RingEngineResult<()> {
        for chain in &self.perspectival_chains {
            chain.verify_chain(&self.genesis_seed)?;
        }
        Ok(())
    }

    // ── Internal helpers ────────────────────────────────────────────────

    /// Extract semantic context from ring state after cycle execution.
    ///
    /// Reads well-known key prefixes from FU.Data and OU.Server trees
    /// to classify the cycle and capture its semantic identity.
    ///
    /// ## Key mapping
    ///
    /// | FU.Data key       | CycleContext field       |
    /// |-------------------|--------------------------|
    /// | `command.type`    | cycle_class + command_type|
    /// | `command.admin`   | actor                    |
    /// | `command.request_id` | request_id            |
    /// | `event.type`      | cycle_class (login/hb)   |
    /// | `event.source`    | actor (login)            |
    /// | `gate.name`       | detail (gate transitions)|
    ///
    /// | OU.Server key          | CycleContext field        |
    /// |------------------------|---------------------------|
    /// | `authorization.status` | authorization_outcome     |
    /// | `result.status`        | authorization_outcome (fb)|
    fn extract_cycle_context(&self) -> CycleContext {
        let fu_tree = &self.ring.unit(UnitId::FU).som_quad(Layer::Data).tree;
        let ou_tree = &self.ring.unit(UnitId::OU).som_quad(Layer::Server).tree;

        // Helper: read a UTF-8 string from a Tree key.
        let read = |tree: &Tree, key: &str| -> Option<String> {
            tree.get(key)
                .and_then(|v| String::from_utf8(v.clone()).ok())
        };

        let command_type = read(fu_tree, "command.type");
        let event_type = read(fu_tree, "event.type");

        // Determine cycle class and build context.
        match command_type.as_deref() {
            Some("session.logout") => {
                let actor = read(fu_tree, "command.admin");
                let request_id = read(fu_tree, "command.request_id");
                CycleContext {
                    cycle_class: CycleClass::Logout,
                    command_type: Some("session.logout".into()),
                    actor,
                    request_id,
                    authorization_outcome: Some("invalidated".into()),
                    detail: None,
                }
            }
            Some("gate.transition") => {
                let actor =
                    read(fu_tree, "command.admin").or_else(|| read(fu_tree, "gate.requesting_wp"));
                let request_id = read(fu_tree, "command.request_id");
                let auth_outcome = read(ou_tree, "authorization.status")
                    .or_else(|| read(ou_tree, "result.status"));
                let gate_name = read(fu_tree, "gate.name");

                // Build detail: gate name + evidence count
                let evidence_count = fu_tree
                    .keys()
                    .filter(|k| k.starts_with("gate.evidence."))
                    .count();
                let detail = match gate_name {
                    Some(name) => format!("gate={name} evidence={evidence_count}"),
                    None => format!("evidence={evidence_count}"),
                };

                CycleContext {
                    cycle_class: CycleClass::GateTransition,
                    command_type: Some("gate.transition".into()),
                    actor,
                    request_id,
                    authorization_outcome: auth_outcome,
                    detail: Some(detail),
                }
            }
            Some(cmd) => {
                // Command cycle (user.create, user.delete, etc.)
                let actor = read(fu_tree, "command.admin");
                let request_id = read(fu_tree, "command.request_id");
                let auth_outcome = read(ou_tree, "authorization.status")
                    .or_else(|| read(ou_tree, "result.status"));

                CycleContext {
                    cycle_class: CycleClass::Command,
                    command_type: Some(cmd.into()),
                    actor,
                    request_id,
                    authorization_outcome: auth_outcome,
                    detail: None,
                }
            }
            None => {
                // No command.type — check event.type for login/heartbeat
                match event_type.as_deref() {
                    Some("login_attempt") => {
                        let actor = read(fu_tree, "event.source");
                        // Login outcome is determined by CU's grading,
                        // visible in OU as authorization.status or via
                        // the server.view key in SU output.
                        let auth_outcome = read(ou_tree, "authorization.status")
                            .or_else(|| read(ou_tree, "result.status"));

                        CycleContext {
                            cycle_class: CycleClass::Login,
                            command_type: Some("login".into()),
                            actor,
                            request_id: None,
                            authorization_outcome: auth_outcome,
                            detail: None,
                        }
                    }
                    _ => {
                        // Heartbeat or unknown event type
                        CycleContext::heartbeat()
                    }
                }
            }
        }
    }

    fn build_genesis_input_quad(&self, seed: &[u8]) -> Quad {
        let seed_hash = *blake3::hash(seed).as_bytes();
        let mut tree = Tree::new();
        tree.insert("genesis.seed".into(), seed.to_vec());
        tree.insert("genesis.seed_hash".into(), seed_hash.to_vec());
        Quad::new(seed_hash, [0u8; 32], tree)
    }

    fn run_processor(
        &mut self,
        unit: UnitId,
        cycle_index: u64,
        input: &Quad,
    ) -> RingEngineResult<Quad> {
        // Read this unit's Data layer (resting memory from previous cycles)
        let data_quad = self.ring.unit(unit).som_quad(Layer::Data).clone();

        let processor = self.processors[unit.index()]
            .as_mut()
            .ok_or(RingEngineError::UnitDisabled { unit })?;
        let output = processor.process(unit, cycle_index, input, &data_quad)?;

        // Deposit externalized state into this unit's Data layer.
        // FU is special: its Data layer is also written by AroundRing.inject()
        // and deposit_cycle_result(). Merge externalized keys rather than replace.
        if let Some(new_data) = processor.externalize_state(unit) {
            if unit == UnitId::FU {
                let fu_data = self.ring.unit_mut(unit).som_quad_mut(Layer::Data);
                for (k, v) in new_data.tree {
                    fu_data.tree.insert(k, v);
                }
                // Update Root/Pointer only if they were non-zero
                if new_data.root != [0u8; 32] {
                    fu_data.root = new_data.root;
                }
                if new_data.pointer != [0u8; 32] {
                    fu_data.pointer = new_data.pointer;
                }
            } else {
                *self.ring.unit_mut(unit).som_quad_mut(Layer::Data) = new_data;
            }
        }

        Ok(output)
    }

    fn run_horizontal_path(
        &mut self,
        unit: UnitId,
        cycle_index: u64,
        h_crossing: &CrossingResult,
    ) -> RingEngineResult<()> {
        let stripped_h_quad = &h_crossing.delivery_envelope.quad;

        let client_quad = {
            let processor = self.processors[unit.index()]
                .as_mut()
                .ok_or(RingEngineError::UnitDisabled { unit })?;
            processor.process_layer(unit, cycle_index, Layer::Client, stripped_h_quad)?
        };

        *self.ring.unit_mut(unit).som_quad_mut(Layer::Client) = client_quad.clone();

        let interface_quad = {
            let processor = self.processors[unit.index()]
                .as_mut()
                .ok_or(RingEngineError::UnitDisabled { unit })?;
            processor.process_layer(unit, cycle_index, Layer::Interface, &client_quad)?
        };

        *self.ring.unit_mut(unit).som_quad_mut(Layer::Interface) = interface_quad;
        Ok(())
    }

    fn deposit_server_output(&mut self, unit: UnitId, server_output: &Quad) {
        let us = self.ring.unit_mut(unit);
        *us.som_quad_mut(Layer::Server) = server_output.clone();
        us.soma_quad = Quad::new(server_output.root, server_output.pointer, {
            let mut t = Tree::new();
            t.insert("soma.unit".into(), format!("{unit}").into_bytes());
            t.insert(
                "soma.root_hash".into(),
                server_output.content_hash().to_vec(),
            );
            t
        });
    }

    fn deposit_cycle_result(&mut self, cycle_index: u64, entry: &LedgerEntry) {
        let fu_data = self.ring.unit_mut(UnitId::FU).som_quad_mut(Layer::Data);
        fu_data
            .tree
            .insert("cycle.index".into(), cycle_index.to_le_bytes().to_vec());
        fu_data.tree.insert(
            "cycle.awareness_fingerprint".into(),
            entry.awareness_fingerprint.to_vec(),
        );
        fu_data.tree.insert(
            "cycle.system_fingerprint".into(),
            entry.system_fingerprint.to_vec(),
        );
        fu_data
            .tree
            .insert("cycle.chain_hash".into(), entry.chain_hash.to_vec());
        fu_data.root = entry.chain_hash;
    }

    // ── Persistence (WITHIN) ────────────────────────────────────────────

    fn persist_after_genesis(&self, crossing_records: &[CrossingRecord], seed: &[u8]) {
        if let Some(ref store) = self.within_store {
            let Some(ledger_entry) = self.ledger.genesis() else {
                warn!("persist_after_genesis called without ledger genesis entry");
                return;
            };
            if let Err(e) = store.persist_genesis(
                &self.ring,
                crossing_records,
                ledger_entry,
                seed,
                &self.boundary.verifying_key_bytes(),
            ) {
                warn!(error = %e, "failed to persist genesis");
            }
            self.persist_perspectival(0);
        }
    }

    fn persist_after_cycle(&self, cycle_index: u64, crossing_records: &[CrossingRecord]) {
        if let Some(ref store) = self.within_store {
            let Some(ledger_entry) = self.ledger.latest() else {
                warn!(cycle_index, "persist_after_cycle called without ledger entry");
                return;
            };
            if let Err(e) =
                store.persist_cycle(&self.ring, cycle_index, crossing_records, ledger_entry)
            {
                warn!(cycle_index, error = %e, "failed to persist cycle");
            }
            self.persist_perspectival(cycle_index);
        }
    }

    fn persist_perspectival(&self, cycle_index: u64) {
        if let Some(ref store) = self.within_store {
            let entries: Vec<(UnitId, _)> = UnitId::ALL
                .iter()
                .filter_map(|&unit| {
                    self.perspectival_chains[unit.index()]
                        .entry(cycle_index)
                        .map(|e| (unit, e.clone()))
                })
                .collect();
            if let Some(xv) = self.latest_cross_verification {
                if let Err(e) = store.persist_perspectival(cycle_index, &entries, &xv) {
                    warn!(cycle_index, error = %e, "failed to persist perspectival data");
                }
            }
        }
    }
}

impl std::fmt::Debug for RingEngine {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("RingEngine")
            .field("cycle_index", &self.ring.cycle_index)
            .field("genesis_complete", &self.genesis_complete)
            .field(
                "processors",
                &self
                    .processors
                    .iter()
                    .map(|p| p.is_some())
                    .collect::<Vec<_>>(),
            )
            .field("before_gates", &self.before_gates.len())
            .field("after_observers", &self.after_observers.len())
            .field("through_delegate_count", &self.through_delegates.len())
            .field("around_extensions", &self.around_extensions.len())
            .field("within_store", &self.within_store.is_some())
            .field("command_registry_entries", &self.command_registry.len())
            .field("registered_names", &self.registered_names)
            .finish()
    }
}

// ═══════════════════════════════════════════════════════════════════════════
// Tests
// ═══════════════════════════════════════════════════════════════════════════

// inline: exercises module-private items via super::*
#[cfg(test)]
mod tests {
    use super::*;
    use soma_som_core::extension::{Extension, GateRejection};
    use soma_som_core::lexicon::VocabCoord;
    use soma_som_core::ring::RingState;
    use soma_som_core::types::{Element, World};
    use std::sync::{Arc, Mutex};

    const TEST_SEED: &[u8] = b"soma-ring-engine-test-seed-v1";
    const TEST_SECRET: [u8; 32] = [42u8; 32];

    // ── StubRingProcessor ───────────────────────────────────────────────

    struct StubRingProcessor {
        invocation_count: u64,
    }

    impl StubRingProcessor {
        fn new() -> Self {
            Self {
                invocation_count: 0,
            }
        }
    }

    impl RingProcessor for StubRingProcessor {
        fn process(
            &mut self,
            unit: UnitId,
            cycle: u64,
            input: &Quad,
            _data: &Quad,
        ) -> Result<Quad, RingEngineError> {
            self.invocation_count += 1;
            let root = {
                let mut h = blake3::Hasher::new();
                h.update(&[unit as u8]);
                h.update(&cycle.to_le_bytes());
                h.update(&input.root);
                *h.finalize().as_bytes()
            };
            let pointer = {
                let mut h = blake3::Hasher::new();
                h.update(&[unit as u8]);
                h.update(b"pointer");
                h.update(&cycle.to_le_bytes());
                *h.finalize().as_bytes()
            };
            let mut tree = input.tree.clone();
            tree.insert("processor.unit".into(), format!("{unit}").into_bytes());
            tree.insert("processor.cycle".into(), cycle.to_le_bytes().to_vec());
            tree.insert("processor.name".into(), b"StubRingProcessor".to_vec());
            Ok(Quad::new(root, pointer, tree))
        }

        fn externalize_state(&self, unit: UnitId) -> Option<Quad> {
            let mut tree = Tree::new();
            tree.insert("stub.unit".into(), format!("{unit}").into_bytes());
            tree.insert(
                "stub.invocations".into(),
                self.invocation_count.to_le_bytes().to_vec(),
            );
            let root = {
                let mut h = blake3::Hasher::new();
                h.update(b"stub.data");
                h.update(&[unit as u8]);
                *h.finalize().as_bytes()
            };
            Some(Quad::new(root, [0u8; 32], tree))
        }

        fn process_layer(
            &mut self,
            unit: UnitId,
            cycle: u64,
            layer: Layer,
            input: &Quad,
        ) -> Result<Quad, RingEngineError> {
            let root = {
                let mut h = blake3::Hasher::new();
                h.update(&[unit as u8]);
                h.update(&[layer as u8]);
                h.update(&cycle.to_le_bytes());
                h.update(&input.root);
                *h.finalize().as_bytes()
            };
            let pointer = {
                let mut h = blake3::Hasher::new();
                h.update(&[unit as u8]);
                h.update(&[layer as u8]);
                h.update(b"layer-pointer");
                h.update(&cycle.to_le_bytes());
                *h.finalize().as_bytes()
            };
            let mut tree = Tree::new();
            tree.insert("layer".into(), format!("{layer:?}").into_bytes());
            tree.insert("unit".into(), format!("{unit}").into_bytes());
            Ok(Quad::new(root, pointer, tree))
        }
    }

    struct FailingRingProcessor {
        message: String,
    }
    impl FailingRingProcessor {
        fn new(msg: &str) -> Self {
            Self {
                message: msg.into(),
            }
        }
    }
    impl RingProcessor for FailingRingProcessor {
        fn process(
            &mut self,
            unit: UnitId,
            _cycle: u64,
            _input: &Quad,
            _data: &Quad,
        ) -> Result<Quad, RingEngineError> {
            Err(RingEngineError::ProcessorFailed {
                unit,
                reason: self.message.clone(),
            })
        }
    }

    fn make_engine() -> RingEngine {
        let mut engine = RingEngine::with_test_config(&TEST_SECRET);
        engine.set_all_processors(|| Box::new(StubRingProcessor::new()));
        engine
    }

    // ── Genesis ─────────────────────────────────────────────────────────

    #[test]
    fn genesis_succeeds() {
        let mut engine = make_engine();
        let report = engine.genesis(TEST_SEED).unwrap();
        assert_ne!(report.genesis.system_fingerprint, [0u8; 32]);
        assert_ne!(report.genesis.genesis_hash, [0u8; 32]);
        assert_eq!(report.crossing_records.len(), 12);
        assert!(engine.is_genesis_complete());
    }

    #[test]
    fn genesis_populates_ledger() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        assert_eq!(engine.ledger().len(), 1);
        assert_eq!(engine.ledger().genesis().unwrap().cycle_index, 0);
    }

    #[test]
    fn genesis_transitions_ring_to_ring_mode() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        assert_eq!(engine.ring().state, RingState::Ring);
    }

    #[test]
    fn double_genesis_fails() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        assert!(matches!(
            engine.genesis(TEST_SEED),
            Err(RingEngineError::GenesisAlreadyComplete)
        ));
    }

    #[test]
    fn genesis_without_processors_fails() {
        let mut engine = RingEngine::with_test_config(&TEST_SECRET);
        assert!(matches!(
            engine.genesis(TEST_SEED),
            Err(RingEngineError::UnitDisabled { .. })
        ));
    }

    #[test]
    fn different_seeds_produce_different_genesis() {
        let mut e1 = make_engine();
        let r1 = e1.genesis(b"seed-alpha").unwrap();
        let mut e2 = make_engine();
        let r2 = e2.genesis(b"seed-beta").unwrap();
        assert_ne!(r1.genesis.genesis_hash, r2.genesis.genesis_hash);
    }

    // ── Standard cycles ─────────────────────────────────────────────────

    #[test]
    fn cycle_after_genesis_succeeds() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        let report = engine.cycle().unwrap();
        assert_eq!(report.cycle_index, 1);
        assert_ne!(report.awareness_fingerprint, [0u8; 32]);
        assert_eq!(report.crossing_records.len(), 12);
    }

    #[test]
    fn cycle_without_genesis_fails() {
        let mut engine = make_engine();
        assert!(matches!(
            engine.cycle(),
            Err(RingEngineError::NotInitialized)
        ));
    }

    #[test]
    fn multiple_cycles_build_chain() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        let r1 = engine.cycle().unwrap();
        let r2 = engine.cycle().unwrap();
        let r3 = engine.cycle().unwrap();
        assert_eq!(r1.cycle_index, 1);
        assert_eq!(r2.cycle_index, 2);
        assert_eq!(r3.cycle_index, 3);
        assert_ne!(r1.chain_hash, r2.chain_hash);
        assert_eq!(engine.ledger().len(), 4);
    }

    #[test]
    fn ledger_chain_is_verifiable_after_cycles() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        for _ in 0..10 {
            engine.cycle().unwrap();
        }
        assert!(engine.verify_chain().is_ok());
        assert_eq!(engine.ledger().len(), 11);
    }

    #[test]
    fn consecutive_cycles_produce_different_fingerprints() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        let r1 = engine.cycle().unwrap();
        let r2 = engine.cycle().unwrap();
        assert_ne!(r1.awareness_fingerprint, r2.awareness_fingerprint);
    }

    // ── Fault injection (Criterion 1) ───────────────────────────────────

    #[test]
    fn disabled_unit_causes_cycle_failure() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        engine.disable(UnitId::CU);
        match engine.cycle().unwrap_err() {
            RingEngineError::UnitDisabled { unit } => assert_eq!(unit, UnitId::CU),
            other => panic!("Expected UnitDisabled, got {other:?}"),
        }
    }

    #[test]
    fn criterion_1_all_six_units() {
        for &target in &UnitId::ALL {
            let mut engine = make_engine();
            engine.genesis(TEST_SEED).unwrap();
            engine.disable(target);
            assert!(engine.cycle().is_err(), "Disabling {target} must fail");
        }
    }

    #[test]
    fn failing_processor_causes_explicit_error() {
        let mut engine = make_engine();
        engine.set_processor(
            UnitId::MU,
            Box::new(FailingRingProcessor::new("MU crashed")),
        );
        engine.genesis(TEST_SEED).unwrap_err();

        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        engine.set_processor(
            UnitId::MU,
            Box::new(FailingRingProcessor::new("MU crashed")),
        );
        assert!(matches!(
            engine.cycle(),
            Err(RingEngineError::ProcessorFailed {
                unit: UnitId::MU,
                ..
            })
        ));
    }

    // ── Crossing records ────────────────────────────────────────────────

    #[test]
    fn crossing_records_form_valid_chain() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        let report = engine.cycle().unwrap();
        let records = &report.crossing_records;
        assert_eq!(records.len(), 12);
        for r in records {
            assert!(r.verify_chain_hash());
        }
        for i in 1..records.len() {
            assert_eq!(records[i].prev_hash, records[i - 1].chain_hash);
        }
    }

    #[test]
    fn crossing_records_have_correct_routing() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        let report = engine.cycle().unwrap();
        let expected: Vec<(UnitId, UnitId, CrossingType)> = vec![
            (UnitId::FU, UnitId::MU, CrossingType::Vertical),
            (UnitId::FU, UnitId::FU, CrossingType::Horizontal),
            (UnitId::MU, UnitId::CU, CrossingType::Vertical),
            (UnitId::MU, UnitId::MU, CrossingType::Horizontal),
            (UnitId::CU, UnitId::OU, CrossingType::Vertical),
            (UnitId::CU, UnitId::CU, CrossingType::Horizontal),
            (UnitId::OU, UnitId::SU, CrossingType::Vertical),
            (UnitId::OU, UnitId::OU, CrossingType::Horizontal),
            (UnitId::SU, UnitId::HU, CrossingType::Vertical),
            (UnitId::SU, UnitId::SU, CrossingType::Horizontal),
            (UnitId::HU, UnitId::FU, CrossingType::Vertical),
            (UnitId::HU, UnitId::HU, CrossingType::Horizontal),
        ];
        for (i, (record, (src, dst, ct))) in report
            .crossing_records
            .iter()
            .zip(expected.iter())
            .enumerate()
        {
            assert_eq!(record.source, *src, "Record {} source", i + 1);
            assert_eq!(record.destination, *dst, "Record {} dest", i + 1);
            assert_eq!(record.crossing_type, *ct, "Record {} type", i + 1);
        }
    }

    #[test]
    fn twelve_crossings_alternate_v_h() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        let report = engine.cycle().unwrap();
        for (i, record) in report.crossing_records.iter().enumerate() {
            let expected = if (i + 1) % 2 == 1 {
                CrossingType::Vertical
            } else {
                CrossingType::Horizontal
            };
            assert_eq!(record.crossing_type, expected, "nseq {}", i + 1);
        }
    }

    #[test]
    fn horizontal_crossings_are_self_referential() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        let report = engine.cycle().unwrap();
        let h: Vec<_> = report
            .crossing_records
            .iter()
            .filter(|r| r.crossing_type == CrossingType::Horizontal)
            .collect();
        assert_eq!(h.len(), 6);
        for r in &h {
            assert_eq!(r.source, r.destination);
        }
    }

    // ── Ring state ──────────────────────────────────────────────────────

    #[test]
    fn ring_is_populated_after_genesis() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        assert!(engine.ring().is_populated());
    }

    #[test]
    fn fingerprint_accessors_match_report() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        let report = engine.cycle().unwrap();
        assert_eq!(engine.awareness_fingerprint(), report.awareness_fingerprint);
        assert_eq!(engine.system_fingerprint(), report.system_fingerprint);
    }

    #[test]
    fn criterion_2_different_units_different_fingerprints() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        engine.cycle().unwrap();
        let mut roots: Vec<_> = UnitId::ALL
            .iter()
            .map(|&u| engine.ring().unit(u).som_quad(Layer::Server).root)
            .collect();
        roots.sort();
        roots.dedup();
        assert_eq!(roots.len(), 6);
    }

    // ── Horizontal path ─────────────────────────────────────────────────

    #[test]
    fn client_and_interface_populated_after_cycle() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        engine.cycle().unwrap();
        for &unit in &UnitId::ALL {
            assert!(!engine.ring().unit(unit).som_quad(Layer::Client).is_empty());
            assert!(
                !engine
                    .ring()
                    .unit(unit)
                    .som_quad(Layer::Interface)
                    .is_empty()
            );
        }
    }

    #[test]
    fn all_72_som_positions_populated_after_cycle() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        engine.cycle().unwrap();
        for &unit in &UnitId::ALL {
            for &layer in &[Layer::Server, Layer::Client, Layer::Interface] {
                assert!(
                    !engine.ring().unit(unit).som_quad(layer).is_empty(),
                    "{unit}.{layer:?} non-empty"
                );
            }
        }
    }

    #[test]
    fn all_30_quads_populated_after_cycle() {
        // 30-Quad completeness: all 6 units × 4 layers (Data, Server, Client, Interface)
        // must be non-empty after genesis + one cycle. This is the state-of-mind
        // diagram fidelity test — the ring's cognitive model is structurally complete.
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        engine.cycle().unwrap();
        for &unit in &UnitId::ALL {
            for &layer in &Layer::ALL {
                assert!(
                    !engine.ring().unit(unit).som_quad(layer).is_empty(),
                    "{unit}.{layer:?} must be non-empty (30-Quad completeness)",
                );
            }
        }
    }

    #[test]
    fn fu_data_merge_preserves_around_injected_keys() {
        // Verify that externalize_state() for FU merges into FU.Data
        // rather than replacing it, so AROUND-injected keys survive.
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();

        // Inject a command key into FU.Data (simulating AROUND inject)
        {
            let fu_data = &mut engine
                .ring_mut()
                .unit_mut(UnitId::FU)
                .som_quad_mut(Layer::Data)
                .tree;
            fu_data.insert("command.type".into(), b"user.create".to_vec());
        }

        engine.cycle().unwrap();

        // After cycle, FU.Data should contain BOTH:
        // - The externalized stub keys (from StubRingProcessor.externalize_state)
        // - The cycle metadata (from deposit_cycle_result)
        let fu_data = &engine.ring().unit(UnitId::FU).som_quad(Layer::Data).tree;
        assert!(
            fu_data.contains_key("stub.unit"),
            "FU.Data must contain externalized stub keys"
        );
        assert!(
            fu_data.contains_key("cycle.index"),
            "FU.Data must contain cycle metadata from deposit_cycle_result"
        );
    }

    // ── Perspectival ledger ─────────────────────────────────────────────

    #[test]
    fn genesis_initializes_perspectival_chains() {
        let mut engine = make_engine();
        let report = engine.genesis(TEST_SEED).unwrap();
        for &unit in &UnitId::ALL {
            assert_eq!(engine.perspectival_chain(unit).len(), 1);
        }
        assert_ne!(report.cross_verification_digest, [0u8; 32]);
        assert_eq!(
            engine.cross_verification_digest(),
            Some(report.cross_verification_digest)
        );
    }

    #[test]
    fn perspectival_chains_verify_after_cycles() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        for _ in 0..10 {
            engine.cycle().unwrap();
        }
        assert!(engine.verify_perspectival_chains().is_ok());
    }

    #[test]
    fn cross_verification_changes_each_cycle() {
        let mut engine = make_engine();
        let gr = engine.genesis(TEST_SEED).unwrap();
        let mut prev = gr.cross_verification_digest;
        for _ in 1..=5 {
            let r = engine.cycle().unwrap();
            assert_ne!(r.cross_verification_digest, prev);
            prev = r.cross_verification_digest;
        }
    }

    #[test]
    fn cross_verification_deposited_in_fu_data() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        let report = engine.cycle().unwrap();
        let deposited = engine
            .ring()
            .unit(UnitId::FU)
            .som_quad(Layer::Data)
            .tree
            .get("perspectival.cross_verification_digest")
            .unwrap();
        assert_eq!(deposited.as_slice(), &report.cross_verification_digest[..]);
    }

    #[test]
    fn both_ledgers_verify_after_extended_run() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        for _ in 0..20 {
            engine.cycle().unwrap();
        }
        assert!(engine.verify_chain().is_ok());
        assert!(engine.verify_perspectival_chains().is_ok());
        assert_eq!(engine.ledger().len(), 21);
    }

    // ── CycleObserver ───────────────────────────────────────────────────

    struct RecordingObserver {
        entries: Arc<Mutex<Vec<String>>>,
    }
    impl RecordingObserver {
        fn new() -> (Self, Arc<Mutex<Vec<String>>>) {
            let e = Arc::new(Mutex::new(Vec::new()));
            (Self { entries: e.clone() }, e)
        }
    }
    impl CycleObserver for RecordingObserver {
        fn on_unit_enter(&self, unit: UnitId, ci: u64, step: u32) {
            self.entries
                .lock()
                .unwrap()
                .push(format!("enter:{unit}:{ci}:{step}"));
        }
        fn on_unit_exit(&self, unit: UnitId, ci: u64, step: u32, ms: u64) {
            self.entries
                .lock()
                .unwrap()
                .push(format!("exit:{unit}:{ci}:{step}:{ms}ms"));
        }
    }

    #[test]
    fn cycle_observed_records_all_unit_events() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        let (obs, entries) = RecordingObserver::new();
        let report = engine.cycle_observed(&obs).unwrap();
        let log = entries.lock().unwrap();
        assert_eq!(log.len(), 12);
        for i in 0..6 {
            assert!(log[i * 2].starts_with("enter:"));
            assert!(log[i * 2 + 1].starts_with("exit:"));
        }
        assert_eq!(report.cycle_index, 1);
    }

    #[test]
    fn noop_observer_produces_same_result() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        let r1 = engine.cycle_observed(&NoOpObserver).unwrap();
        let r2 = engine.cycle().unwrap();
        assert_eq!(r1.cycle_index, 1);
        assert_eq!(r2.cycle_index, 2);
    }

    // ── Extension lifecycle ─────────────────────────────────────────────

    struct TestGate {
        reject: bool,
        feedback_log: Arc<Mutex<Vec<u64>>>,
    }
    impl TestGate {
        fn new(reject: bool) -> (Self, Arc<Mutex<Vec<u64>>>) {
            let log = Arc::new(Mutex::new(Vec::new()));
            (
                Self {
                    reject,
                    feedback_log: log.clone(),
                },
                log,
            )
        }
    }
    impl Extension for TestGate {
        fn name(&self) -> &str {
            "test-gate"
        }
    }
    impl BeforeRing for TestGate {
        fn evaluate(&self, _ctx: &Tree) -> Result<(), GateRejection> {
            if self.reject {
                Err(GateRejection {
                    source: "test".into(),
                    reason: "rejected".into(),
                })
            } else {
                Ok(())
            }
        }
        fn feedback(&self, ci: u64, _output: &Tree) {
            self.feedback_log.lock().unwrap().push(ci);
        }
    }

    #[test]
    fn before_gate_rejects_cycle() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        let (gate, _) = TestGate::new(true);
        engine.register_before(Box::new(gate));
        assert!(matches!(
            engine.cycle(),
            Err(RingEngineError::GateRejected(_))
        ));
    }

    #[test]
    fn before_gate_allows_and_receives_feedback() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        let (gate, log) = TestGate::new(false);
        engine.register_before(Box::new(gate));
        engine.cycle().unwrap();
        assert_eq!(*log.lock().unwrap(), vec![1]);
    }

    #[test]
    fn before_gate_short_circuits_on_first_rejection() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        let (pass, pass_log) = TestGate::new(false);
        let (reject, _) = TestGate::new(true);
        engine.register_before(Box::new(pass));
        engine.register_before(Box::new(reject));
        assert!(engine.cycle().is_err());
        assert!(pass_log.lock().unwrap().is_empty());
    }

    struct TestAround {
        key: String,
        val: Vec<u8>,
        log: Arc<Mutex<Vec<u64>>>,
    }
    impl TestAround {
        fn new(k: &str, v: &[u8]) -> (Self, Arc<Mutex<Vec<u64>>>) {
            let log = Arc::new(Mutex::new(Vec::new()));
            (
                Self {
                    key: k.into(),
                    val: v.to_vec(),
                    log: log.clone(),
                },
                log,
            )
        }
    }
    impl Extension for TestAround {
        fn name(&self) -> &str {
            "test-around"
        }
    }
    impl AroundRing for TestAround {
        fn inject(&self, fu: &mut Tree) {
            fu.insert(self.key.clone(), self.val.clone());
        }
        fn observe(&self, ci: u64, _ou: &Tree, _su: &Tree) {
            self.log.lock().unwrap().push(ci);
        }
    }

    #[test]
    fn around_injects_and_observes() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        let (around, log) = TestAround::new("test.injected", b"hello");
        engine.register_around(Box::new(around));
        engine.cycle().unwrap();
        assert_eq!(*log.lock().unwrap(), vec![1]);
    }

    #[test]
    fn multiple_around_compose_additively() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        let (a1, l1) = TestAround::new("test.k1", b"v1");
        let (a2, l2) = TestAround::new("test.k2", b"v2");
        engine.register_around(Box::new(a1));
        engine.register_around(Box::new(a2));
        engine.cycle().unwrap();
        assert_eq!(*l1.lock().unwrap(), vec![1]);
        assert_eq!(*l2.lock().unwrap(), vec![1]);
    }

    struct TestAfter {
        log: Arc<Mutex<Vec<u64>>>,
    }
    impl TestAfter {
        fn new() -> (Self, Arc<Mutex<Vec<u64>>>) {
            let log = Arc::new(Mutex::new(Vec::new()));
            (Self { log: log.clone() }, log)
        }
    }
    impl Extension for TestAfter {
        fn name(&self) -> &str {
            "test-after"
        }
    }
    impl AfterRing for TestAfter {
        fn on_cycle_complete(&self, ci: u64, _output: &Tree) {
            self.log.lock().unwrap().push(ci);
        }
    }

    #[test]
    fn after_observer_notified() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        let (after, log) = TestAfter::new();
        engine.register_after(Box::new(after));
        engine.cycle().unwrap();
        engine.cycle().unwrap();
        assert_eq!(*log.lock().unwrap(), vec![1, 2]);
    }

    #[test]
    fn full_extension_lifecycle() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        let (gate, gate_fb) = TestGate::new(false);
        let (around, around_log) = TestAround::new("ext.d", b"x");
        let (after, after_log) = TestAfter::new();
        engine.register_before(Box::new(gate));
        engine.register_around(Box::new(around));
        engine.register_after(Box::new(after));
        engine.cycle().unwrap();
        engine.cycle().unwrap();
        assert_eq!(*gate_fb.lock().unwrap(), vec![1, 2]);
        assert_eq!(*around_log.lock().unwrap(), vec![1, 2]);
        assert_eq!(*after_log.lock().unwrap(), vec![1, 2]);
    }

    // ── run_cycles ──────────────────────────────────────────────────────

    #[test]
    fn run_cycles_batch() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        let results = engine.run_cycles(5);
        assert_eq!(results.len(), 5);
        for (i, r) in results.iter().enumerate() {
            assert_eq!(r.as_ref().unwrap().cycle_index, (i + 1) as u64);
        }
    }

    #[test]
    fn debug_format() {
        let engine = make_engine();
        let debug = format!("{engine:?}");
        assert!(debug.contains("RingEngine"));
    }

    // ── WP-M1D: Semantic context extraction ─────────────────────────

    #[test]
    fn cycle_report_carries_context() {
        let mut engine = make_engine();
        engine.genesis(b"m1d-seed").unwrap();
        let report = engine.cycle().unwrap();

        // Bare cycle (no command injected) → Heartbeat context
        assert_eq!(report.context.cycle_class, CycleClass::Heartbeat);
        assert!(report.context.command_type.is_none());
        assert!(report.context.actor.is_none());
    }

    #[test]
    fn genesis_report_context_does_not_affect_chain_hash() {
        // Genesis chain_hash is computed from seed, not semantic context.
        // Two engines with same seed must produce identical genesis hash.
        let mut e1 = make_engine();
        let mut e2 = make_engine();
        let r1 = e1.genesis(b"same-seed").unwrap();
        let r2 = e2.genesis(b"same-seed").unwrap();
        assert_eq!(r1.genesis.genesis_hash, r2.genesis.genesis_hash);
    }

    #[test]
    fn different_semantic_contexts_produce_different_chain_hashes() {
        // Two engines with same seed and same cycle fingerprints but
        // different FU.Data content should produce different chain hashes
        // (because extract_cycle_context reads different keys).
        let mut e1 = make_engine();
        e1.genesis(b"seed-diff-ctx").unwrap();
        let r1 = e1.cycle().unwrap();

        // Inject a command into FU.Data before cycle
        let mut e2 = make_engine();
        e2.genesis(b"seed-diff-ctx").unwrap();
        {
            let fu_data = &mut e2
                .ring_mut()
                .unit_mut(UnitId::FU)
                .som_quad_mut(Layer::Data)
                .tree;
            fu_data.insert("command.type".into(), b"user.create".to_vec());
            fu_data.insert("command.admin".into(), b"testuser".to_vec());
            fu_data.insert("command.request_id".into(), b"req-42".to_vec());
        }
        let r2 = e2.cycle().unwrap();

        // Different contexts → different chain hashes
        assert_ne!(r1.chain_hash, r2.chain_hash);
        assert_eq!(r1.context.cycle_class, CycleClass::Heartbeat);
        assert_eq!(r2.context.cycle_class, CycleClass::Command);
        assert_eq!(r2.context.command_type.as_deref(), Some("user.create"));
        assert_eq!(r2.context.actor.as_deref(), Some("testuser"));
    }

    #[test]
    fn login_event_extraction() {
        let mut engine = make_engine();
        engine.genesis(b"login-seed").unwrap();
        {
            let fu_data = &mut engine
                .ring_mut()
                .unit_mut(UnitId::FU)
                .som_quad_mut(Layer::Data)
                .tree;
            fu_data.insert("event.type".into(), b"login_attempt".to_vec());
            fu_data.insert("event.source".into(), b"alice".to_vec());
        }
        let report = engine.cycle().unwrap();
        assert_eq!(report.context.cycle_class, CycleClass::Login);
        assert_eq!(report.context.command_type.as_deref(), Some("login"));
        assert_eq!(report.context.actor.as_deref(), Some("alice"));
    }

    #[test]
    fn gate_transition_extraction() {
        let mut engine = make_engine();
        engine.genesis(b"gate-seed").unwrap();
        {
            let fu_data = &mut engine
                .ring_mut()
                .unit_mut(UnitId::FU)
                .som_quad_mut(Layer::Data)
                .tree;
            fu_data.insert("command.type".into(), b"gate.transition".to_vec());
            fu_data.insert("command.admin".into(), b"operator1".to_vec());
            fu_data.insert("command.request_id".into(), b"req-gate".to_vec());
            fu_data.insert("gate.name".into(), b"G1".to_vec());
            fu_data.insert("gate.evidence.design_review".into(), b"present".to_vec());
            fu_data.insert("gate.evidence.test_report".into(), b"present".to_vec());
        }
        let report = engine.cycle().unwrap();
        assert_eq!(report.context.cycle_class, CycleClass::GateTransition);
        assert_eq!(
            report.context.command_type.as_deref(),
            Some("gate.transition")
        );
        assert_eq!(report.context.actor.as_deref(), Some("operator1"));
        assert!(report.context.detail.as_ref().unwrap().contains("gate=G1"));
        assert!(
            report
                .context
                .detail
                .as_ref()
                .unwrap()
                .contains("evidence=2")
        );
    }

    // ═══════════════════════════════════════════════════════════════════
    // register_sibling() tests
    // ═══════════════════════════════════════════════════════════════════

    use soma_som_core::extension::{
        DelegationError, DomainRequest, RegistrationError, SiblingManifest,
    };

    /// Minimal test sibling: THROUGH only, claims `sibling.{id}.*` namespace.
    struct TestSiblingManifest {
        id: String,
        min_ring_version: String,
        domains: Vec<DomainRequest>,
    }

    impl TestSiblingManifest {
        fn new(id: &str) -> Self {
            Self {
                id: id.to_string(),
                min_ring_version: "1.0.0".into(),
                domains: vec![],
            }
        }

        fn with_min_version(mut self, v: &str) -> Self {
            self.min_ring_version = v.to_string();
            self
        }

        fn with_domain(mut self, id: &str) -> Self {
            self.domains.push(DomainRequest {
                sibling_id: id.to_string(),
                display_name: id.to_string(),
                version: "1.0.0".into(),
                max_capacity_bytes: None,
            });
            self
        }
    }

    impl SiblingManifest for TestSiblingManifest {
        fn id(&self) -> &str {
            &self.id
        }
        fn display_name(&self) -> &str {
            &self.id
        }
        fn version(&self) -> &str {
            "1.0.0"
        }
        fn min_ring_version(&self) -> &str {
            &self.min_ring_version
        }
        fn through_handler(&self) -> Option<Arc<dyn ThroughRing>> {
            let id = self.id.clone();
            Some(Arc::new(TestSiblingThrough { id }))
        }
        fn persistence_domains(&self) -> Vec<DomainRequest> {
            self.domains.clone()
        }
    }

    /// Stub ThroughRing for test siblings.
    struct TestSiblingThrough {
        id: String,
    }

    impl Extension for TestSiblingThrough {
        fn name(&self) -> &str {
            &self.id
        }
    }

    impl ThroughRing for TestSiblingThrough {
        fn handles(&self, command_type: &str) -> bool {
            command_type.starts_with(&format!("sibling.{}.", self.id))
        }
        fn dispatch(&self, input: &Tree) -> Result<Tree, DelegationError> {
            let mut result = Tree::new();
            result.insert("result.status".into(), b"ok".to_vec());
            result.insert("result.source".into(), self.id.as_bytes().to_vec());
            if let Some(req_id) = input.get("command.request_id") {
                result.insert("result.request_id".into(), req_id.clone());
            }
            Ok(result)
        }
    }

    #[test]
    fn register_sibling_happy_path() {
        let mut engine = RingEngine::new(TimingConfig::default());
        let manifest = TestSiblingManifest::new("qi");

        let result =
            engine.register_sibling(&manifest, None::<fn(&DomainRequest) -> Result<(), String>>);
        assert!(result.is_ok());

        // Sibling ID tracked
        assert!(engine.has_registered_name("qi"));
        // ThroughRing delegate registered (verified via probe, not direct access)
        assert_eq!(engine.through_delegate_count(), 1);
        assert_eq!(engine.probe_namespace("sibling.qi.analyze"), Some("qi"));
    }

    #[test]
    fn register_sibling_duplicate_rejected() {
        let mut engine = RingEngine::new(TimingConfig::default());
        let m1 = TestSiblingManifest::new("qi");
        let m2 = TestSiblingManifest::new("qi");

        engine
            .register_sibling(&m1, None::<fn(&DomainRequest) -> Result<(), String>>)
            .unwrap();
        let result = engine.register_sibling(&m2, None::<fn(&DomainRequest) -> Result<(), String>>);

        assert!(matches!(result, Err(RegistrationError::DuplicateId(ref id)) if id == "qi"));
    }

    #[test]
    fn register_sibling_namespace_collision_detected() {
        let mut engine = RingEngine::new(TimingConfig::default());

        // Pre-register a ThroughRing delegate that claims sibling.project.*
        // using a different name so it doesn't trigger DuplicateId.
        struct ProjectLegacyThrough;
        impl Extension for ProjectLegacyThrough {
            fn name(&self) -> &str {
                "project-legacy"
            }
        }
        impl ThroughRing for ProjectLegacyThrough {
            fn handles(&self, cmd: &str) -> bool {
                cmd.starts_with("sibling.project.")
            }
            fn dispatch(&self, _input: &Tree) -> Result<Tree, DelegationError> {
                Ok(Tree::new())
            }
        }

        engine.register_through(Arc::new(ProjectLegacyThrough)).unwrap();

        // Now try to register sibling "project" — its probe hits the legacy delegate
        let manifest = TestSiblingManifest::new("project");
        let result =
            engine.register_sibling(&manifest, None::<fn(&DomainRequest) -> Result<(), String>>);
        assert!(matches!(
            result,
            Err(RegistrationError::NamespaceConflict { .. })
        ));
    }

    #[test]
    fn register_sibling_incompatible_version_rejected() {
        let mut engine = RingEngine::new(TimingConfig::default());
        let manifest = TestSiblingManifest::new("future").with_min_version("99.0.0");

        let result =
            engine.register_sibling(&manifest, None::<fn(&DomainRequest) -> Result<(), String>>);
        assert!(matches!(
            result,
            Err(RegistrationError::IncompatibleVersion { .. })
        ));
    }

    #[test]
    fn register_sibling_provision_called() {
        let mut engine = RingEngine::new(TimingConfig::default());
        let manifest = TestSiblingManifest::new("qi").with_domain("qi");

        let provisioned = Arc::new(Mutex::new(Vec::new()));
        let prov_clone = Arc::clone(&provisioned);

        let result = engine.register_sibling(
            &manifest,
            Some(move |req: &DomainRequest| {
                prov_clone.lock().unwrap().push(req.sibling_id.clone());
                Ok(())
            }),
        );
        assert!(result.is_ok());
        assert_eq!(provisioned.lock().unwrap().as_slice(), &["qi"]);
    }

    #[test]
    fn register_sibling_provision_failure_rolls_back() {
        let mut engine = RingEngine::new(TimingConfig::default());
        let manifest = TestSiblingManifest::new("qi").with_domain("qi");

        let result = engine.register_sibling(
            &manifest,
            Some(|_: &DomainRequest| Err("disk full".to_string())),
        );
        assert!(matches!(result, Err(RegistrationError::ProvisionFailed(_))));

        // Engine should not have registered anything
        assert!(!engine.has_registered_name("qi"));
        assert_eq!(engine.through_delegate_count(), 0);
    }

    #[test]
    fn register_multiple_siblings() {
        let mut engine = RingEngine::new(TimingConfig::default());

        for id in &["qi", "project", "work", "ai"] {
            let manifest = TestSiblingManifest::new(id);
            engine
                .register_sibling(&manifest, None::<fn(&DomainRequest) -> Result<(), String>>)
                .unwrap();
        }

        assert_eq!(engine.through_delegate_count(), 4);
        assert!(engine.has_registered_name("qi"));
        assert!(engine.has_registered_name("project"));
        assert!(engine.has_registered_name("work"));
        assert!(engine.has_registered_name("ai"));
    }

    #[test]
    fn registered_names_tracks_all_extension_types() {
        let mut engine = RingEngine::new(TimingConfig::default());

        // Register a BEFORE gate directly (reuse existing TestGate)
        let (gate, _) = TestGate::new(false);
        engine.register_before(Box::new(gate));
        assert!(engine.has_registered_name("test-gate"));

        // Register a THROUGH delegate directly
        engine.register_through(Arc::new(TestSiblingThrough {
            id: "direct-through".into(),
        })).unwrap();
        assert!(engine.has_registered_name("direct-through"));
    }

    #[test]
    fn version_compatible_checks() {
        assert!(RingEngine::version_compatible("1.0.0", "1.0.0"));
        assert!(RingEngine::version_compatible("1.0.0", "1.1.0"));
        assert!(RingEngine::version_compatible("1.0.0", "2.0.0"));
        assert!(!RingEngine::version_compatible("2.0.0", "1.0.0"));
        assert!(!RingEngine::version_compatible("1.1.0", "1.0.0"));
        assert!(RingEngine::version_compatible("0.1.0", "1.0.0"));
    }

    #[test]
    fn validation_failure_prevents_provision() {
        // Namespace collision in Stage 1 should prevent Stage 2 (provision)
        // from ever being called.
        let mut engine = RingEngine::new(TimingConfig::default());

        // Pre-register a delegate claiming sibling.qi.*
        struct QiLegacy;
        impl Extension for QiLegacy {
            fn name(&self) -> &str {
                "qi-legacy"
            }
        }
        impl ThroughRing for QiLegacy {
            fn handles(&self, cmd: &str) -> bool {
                cmd.starts_with("sibling.qi.")
            }
            fn dispatch(&self, _: &Tree) -> Result<Tree, DelegationError> {
                Ok(Tree::new())
            }
        }
        engine.register_through(Arc::new(QiLegacy)).unwrap();

        // Try to register "qi" with a provisioner that panics if called
        let manifest = TestSiblingManifest::new("qi").with_domain("qi");
        let result = engine.register_sibling(
            &manifest,
            Some(|_: &DomainRequest| {
                panic!("provisioner should never be called when validation fails");
            }),
        );
        assert!(matches!(
            result,
            Err(RegistrationError::NamespaceConflict { .. })
        ));
    }

    #[test]
    fn probe_namespace_returns_none_for_unclaimed() {
        let mut engine = RingEngine::new(TimingConfig::default());
        let manifest = TestSiblingManifest::new("qi");
        engine
            .register_sibling(&manifest, None::<fn(&DomainRequest) -> Result<(), String>>)
            .unwrap();

        // Claimed namespace returns the delegate name
        assert_eq!(engine.probe_namespace("sibling.qi.analyze"), Some("qi"));
        // Unclaimed namespace returns None
        assert_eq!(engine.probe_namespace("sibling.project.create"), None);
        // Non-sibling namespace returns None
        assert_eq!(engine.probe_namespace("user.create"), None);
        // Probe pattern itself returns None (not a real command)
        assert_eq!(engine.probe_namespace("unrelated"), None);
    }

    #[test]
    fn register_sibling_then_dispatch_through_ring_cycle() {
        // End-to-end: register a sibling's ThroughRing, run a ring cycle
        // with a command targeting that sibling, verify the delegate handled it.
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();

        // Register sibling "qi"
        let manifest = TestSiblingManifest::new("qi");
        engine
            .register_sibling(&manifest, None::<fn(&DomainRequest) -> Result<(), String>>)
            .unwrap();

        // Inject a command targeting sibling.qi.* into FU.Data
        {
            let fu_data = &mut engine
                .ring_mut()
                .unit_mut(UnitId::FU)
                .som_quad_mut(Layer::Data)
                .tree;
            fu_data.insert("command.type".into(), b"sibling.qi.analyze".to_vec());
            fu_data.insert("command.payload".into(), b"{}".to_vec());
            fu_data.insert("command.request_id".into(), b"test-001".to_vec());
            fu_data.insert("command.admin".into(), b"operator".to_vec());
        }

        // Run a ring cycle — the command flows through the ring
        let report = engine.cycle().unwrap();
        assert!(report.cycle_index > 0);
        // The ring processed the cycle (crossing records prove traversal)
        assert!(!report.crossing_records.is_empty());
    }

    #[test]
    fn before_gate_blocks_sibling_command() {
        // A BEFORE gate should block commands targeting siblings just like
        // any other command — proving ring mediation gates everything.
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();

        // Register sibling
        let manifest = TestSiblingManifest::new("qi");
        engine
            .register_sibling(&manifest, None::<fn(&DomainRequest) -> Result<(), String>>)
            .unwrap();

        // Register a BEFORE gate that rejects everything
        let (gate, _) = TestGate::new(true);
        engine.register_before(Box::new(gate));

        // Inject sibling command
        {
            let fu_data = &mut engine
                .ring_mut()
                .unit_mut(UnitId::FU)
                .som_quad_mut(Layer::Data)
                .tree;
            fu_data.insert("command.type".into(), b"sibling.qi.analyze".to_vec());
            fu_data.insert("command.admin".into(), b"operator".to_vec());
        }

        // Cycle should be rejected by the BEFORE gate
        assert!(matches!(
            engine.cycle(),
            Err(RingEngineError::GateRejected(_))
        ));
    }

    // ── Lexicon provider tests ────────────────────────────────────────────

    struct TestLexiconProvider {
        domain: &'static str,
        unit: UnitId,
    }

    impl LexiconProvider for TestLexiconProvider {
        fn domain(&self) -> &str {
            self.domain
        }

        fn declared_unit(&self) -> UnitId {
            self.unit
        }

        fn primary_world(&self) -> World {
            World::from_unit(self.unit)
        }

        fn vocabulary(&self) -> Vec<LexiconEntry> {
            vec![LexiconEntry {
                key: format!("{}.term.one", self.domain),
                coordinate: VocabCoord { unit: self.unit, layer: Layer::Data, element: Element::Root },
                default_en: "Term One".into(),
                related: vec![],
                ordinal: None,
                invariant: false,
            }]
        }

        fn describe(&self, key: &str) -> Option<TermDescription> {
            if key == format!("{}.term.one", self.domain) {
                Some(TermDescription {
                    summary: "The first term".into(),
                    explanation: "A test term for validation.".into(),
                    examples: vec![],
                    constraints: vec![],
                })
            } else {
                None
            }
        }
    }

    #[test]
    fn lexicon_register_and_query_vocabulary() {
        let mut engine = make_engine();
        engine.register_lexicon(Box::new(TestLexiconProvider { domain: "alpha", unit: UnitId::FU })).unwrap();

        let vocab = engine.lexicon_vocabulary();
        assert_eq!(vocab.len(), 1);
        assert_eq!(vocab[0].key, "alpha.term.one");
    }

    #[test]
    fn lexicon_multiple_providers() {
        let mut engine = make_engine();
        engine.register_lexicon(Box::new(TestLexiconProvider { domain: "alpha", unit: UnitId::FU })).unwrap();
        engine.register_lexicon(Box::new(TestLexiconProvider { domain: "beta", unit: UnitId::CU })).unwrap();

        let vocab = engine.lexicon_vocabulary();
        assert_eq!(vocab.len(), 2);

        let domains = engine.lexicon_domains();
        assert_eq!(domains.len(), 2);
        assert!(domains.contains(&"alpha"));
        assert!(domains.contains(&"beta"));
    }

    #[test]
    fn lexicon_describe_routes_to_correct_provider() {
        let mut engine = make_engine();
        engine.register_lexicon(Box::new(TestLexiconProvider { domain: "alpha", unit: UnitId::FU })).unwrap();
        engine.register_lexicon(Box::new(TestLexiconProvider { domain: "beta", unit: UnitId::CU })).unwrap();

        let desc = engine.lexicon_describe("alpha.term.one").unwrap();
        assert_eq!(desc.summary, "The first term");

        let desc = engine.lexicon_describe("beta.term.one").unwrap();
        assert_eq!(desc.summary, "The first term");

        assert!(engine.lexicon_describe("gamma.term.one").is_none());
    }

    #[test]
    fn lexicon_idempotent_registration_replaces_provider() {
        let mut engine = make_engine();
        engine.register_lexicon(Box::new(TestLexiconProvider { domain: "alpha", unit: UnitId::FU })).unwrap();
        engine.register_lexicon(Box::new(TestLexiconProvider { domain: "alpha", unit: UnitId::FU })).unwrap();

        // Should have exactly one provider, not two
        let vocab = engine.lexicon_vocabulary();
        assert_eq!(vocab.len(), 1);
        assert_eq!(engine.lexicon_domains().len(), 1);
    }

    #[test]
    fn lexicon_empty_by_default() {
        let engine = make_engine();
        assert!(engine.lexicon_vocabulary().is_empty());
        assert!(engine.lexicon_domains().is_empty());
        assert!(engine.lexicon_describe("any.key").is_none());
    }

    #[test]
    fn lexicon_register_wrong_unit_rejects_mount() {
        struct WrongUnitProvider;
        impl LexiconProvider for WrongUnitProvider {
            fn domain(&self) -> &str { "bad" }
            fn declared_unit(&self) -> UnitId { UnitId::FU }
            fn primary_world(&self) -> World { World::WAI }
            fn vocabulary(&self) -> Vec<LexiconEntry> {
                vec![LexiconEntry {
                    key: "bad.term".into(),
                    coordinate: VocabCoord { unit: UnitId::MU, layer: Layer::Data, element: Element::Root },
                    default_en: "bad".into(),
                    related: vec![],
                    ordinal: None,
                    invariant: false,
                }]
            }
            fn describe(&self, _key: &str) -> Option<TermDescription> { None }
        }
        let mut engine = make_engine();
        let result = engine.register_lexicon(Box::new(WrongUnitProvider));
        assert!(matches!(result, Err(RegistrationError::CoordinateValidation(_))));
    }

    // ── World registry tests ─────────────────────────────────────────────

    #[test]
    fn world_registry_empty_by_default() {
        let engine = make_engine();
        let reg = engine.world_registry();
        assert!(reg.organs().is_empty());
        assert!(reg.active_worlds().is_empty());
        assert_eq!(reg.vacant_worlds().len(), 6);
    }

    #[test]
    fn world_registry_built_during_registration() {
        let mut engine = make_engine();
        engine.register_lexicon(Box::new(TestLexiconProvider { domain: "alpha", unit: UnitId::FU })).unwrap();

        let reg = engine.world_registry();
        assert_eq!(reg.organs().len(), 1);
        assert_eq!(reg.organs()[0].namespace, "alpha");
        assert_eq!(reg.organs()[0].name, "ALPHA");
        assert_eq!(reg.organs_by_world(World::WAI).len(), 1);
        assert_eq!(reg.organs_by_world(World::WCN).len(), 0);
        assert_eq!(reg.active_worlds().len(), 1);
        assert_eq!(reg.vacant_worlds().len(), 5);
    }

    #[test]
    fn world_registry_multiple_organs_different_worlds() {
        let mut engine = make_engine();
        engine.register_lexicon(Box::new(TestLexiconProvider { domain: "alpha", unit: UnitId::FU })).unwrap();
        engine.register_lexicon(Box::new(TestLexiconProvider { domain: "beta", unit: UnitId::CU })).unwrap();

        let reg = engine.world_registry();
        assert_eq!(reg.organs().len(), 2);
        assert_eq!(reg.organs_by_world(World::WAI).len(), 1);
        assert_eq!(reg.organs_by_world(World::WCN).len(), 1);
        assert_eq!(reg.active_worlds().len(), 2);
        assert_eq!(reg.vacant_worlds().len(), 4);
    }

    #[test]
    fn world_registry_two_organs_same_world() {
        let mut engine = make_engine();
        engine.register_lexicon(Box::new(TestLexiconProvider { domain: "wall", unit: UnitId::OU })).unwrap();
        engine.register_lexicon(Box::new(TestLexiconProvider { domain: "store", unit: UnitId::OU })).unwrap();

        let reg = engine.world_registry();
        assert_eq!(reg.organs().len(), 2);
        assert_eq!(reg.organs_by_world(World::WAY).len(), 2);
        assert_eq!(reg.active_worlds().len(), 1);
    }

    #[test]
    fn world_registry_is_reference_not_allocation() {
        let mut engine = make_engine();
        engine.register_lexicon(Box::new(TestLexiconProvider { domain: "alpha", unit: UnitId::FU })).unwrap();

        // Two calls return references to the same data — no recomputation
        let reg1 = engine.world_registry();
        let reg2 = engine.world_registry();
        assert_eq!(reg1.organs().len(), reg2.organs().len());
        assert!(std::ptr::eq(reg1.organs(), reg2.organs()));
    }

    // ── Rendering resolution tests ────────────────────────────

    struct TestLexiconWithRenderings;

    impl LexiconProvider for TestLexiconWithRenderings {
        fn domain(&self) -> &str {
            "guard"
        }

        fn declared_unit(&self) -> UnitId {
            UnitId::OU
        }

        fn primary_world(&self) -> World {
            World::WAY
        }

        fn vocabulary(&self) -> Vec<LexiconEntry> {
            vec![LexiconEntry {
                key: "guard.severity.critical".into(),
                default_en: "Critical".into(),
                coordinate: VocabCoord { unit: UnitId::OU, layer: Layer::Data, element: Element::Root },
                related: vec![],
                ordinal: Some(3),
                invariant: false,
            }]
        }

        fn describe(&self, _key: &str) -> Option<TermDescription> {
            None
        }

        fn renderings(&self) -> Vec<RenderingPack> {
            let mut text_de = RenderingPack::new("organ:guard", Medium::Text, "de");
            text_de.insert("guard.severity.critical", "Kritisch");
            let mut voice_de = RenderingPack::new("organ:guard", Medium::Voice, "de");
            voice_de.insert(
                "guard.severity.critical",
                "<emphasis>Kritisch</emphasis>",
            );
            vec![text_de, voice_de]
        }
    }

    #[test]
    fn engine_resolve_with_rendering_pack() {
        let mut engine = make_engine();
        engine.register_lexicon(Box::new(TestLexiconWithRenderings)).unwrap();

        let result = engine.lexicon_resolve("guard.severity.critical", Medium::Text, "de");
        assert_eq!(result.content, "Kritisch");
        assert!(result.pack_used);
    }

    #[test]
    fn engine_resolve_fallback_to_default_en() {
        let mut engine = make_engine();
        engine.register_lexicon(Box::new(TestLexiconWithRenderings)).unwrap();

        let result = engine.lexicon_resolve("guard.severity.critical", Medium::Text, "ja");
        assert_eq!(result.content, "Critical");
        assert!(!result.pack_used);
    }

    #[test]
    fn engine_resolve_voice_medium() {
        let mut engine = make_engine();
        engine.register_lexicon(Box::new(TestLexiconWithRenderings)).unwrap();

        let result = engine.lexicon_resolve("guard.severity.critical", Medium::Voice, "de");
        assert_eq!(result.content, "<emphasis>Kritisch</emphasis>");
        assert_eq!(result.medium, Medium::Voice);
    }

    #[test]
    fn engine_rendering_packs_collected() {
        let mut engine = make_engine();
        engine.register_lexicon(Box::new(TestLexiconWithRenderings)).unwrap();
        assert_eq!(engine.lexicon_rendering_packs().len(), 2);
    }

    #[test]
    fn engine_rendering_packs_replaced_on_re_registration() {
        let mut engine = make_engine();
        engine.register_lexicon(Box::new(TestLexiconWithRenderings)).unwrap();
        assert_eq!(engine.lexicon_rendering_packs().len(), 2);
        engine.register_lexicon(Box::new(TestLexiconWithRenderings)).unwrap();
        assert_eq!(engine.lexicon_rendering_packs().len(), 2);
    }

    #[test]
    fn engine_rendering_packs_empty_by_default() {
        let engine = make_engine();
        assert!(engine.lexicon_rendering_packs().is_empty());
    }

    // ── Command Registry tests ─────────────────────────────────────────

    /// ThroughRing delegate with declared permission requirements.
    struct DeclaredThrough {
        name: String,
        prefix: String,
        perms: Vec<PermissionRequirement>,
    }

    impl Extension for DeclaredThrough {
        fn name(&self) -> &str {
            &self.name
        }
    }

    impl ThroughRing for DeclaredThrough {
        fn handles(&self, command_type: &str) -> bool {
            command_type.starts_with(&self.prefix)
        }
        fn dispatch(
            &self,
            _input: &Tree,
        ) -> Result<Tree, soma_som_core::extension::DelegationError> {
            Ok(Tree::new())
        }
        fn claimed_prefixes(&self) -> Vec<String> {
            vec![self.prefix.clone()]
        }
        fn permission_requirements(&self) -> Vec<PermissionRequirement> {
            self.perms.clone()
        }
    }

    fn make_store_through() -> Arc<DeclaredThrough> {
        Arc::new(DeclaredThrough {
            name: "store".into(),
            prefix: "store.".into(),
            perms: vec![
                PermissionRequirement::new(
                    "store.artifact.create",
                    "auth.role.operator",
                    "A2",
                    "significant",
                    "A1",
                ),
                PermissionRequirement::new(
                    "store.artifact.read",
                    "auth.role.viewer",
                    "A1",
                    "routine",
                    "A1",
                ),
            ],
        })
    }

    fn make_guard_through() -> Arc<DeclaredThrough> {
        Arc::new(DeclaredThrough {
            name: "guard".into(),
            prefix: "guard.".into(),
            perms: vec![PermissionRequirement::new(
                "guard.policy.evaluate",
                "auth.role.admin",
                "A3",
                "critical",
                "A2",
            )],
        })
    }

    #[test]
    fn command_registry_empty_by_default() {
        let engine = RingEngine::new(TimingConfig::default());
        assert!(engine.command_registry().is_empty());
        assert_eq!(engine.command_registry().len(), 0);
        assert_eq!(engine.command_registry().permission_count(), 0);
    }

    #[test]
    fn command_registry_populated_on_register_through() {
        let mut engine = RingEngine::new(TimingConfig::default());
        engine.register_through(make_store_through()).unwrap();

        assert_eq!(engine.command_registry().len(), 1);
        assert_eq!(engine.command_registry().permission_count(), 2);

        let entry = &engine.command_registry().entries()[0];
        assert_eq!(entry.delegate_name, "store");
        assert_eq!(entry.permissions.len(), 2);
    }

    #[test]
    fn command_registry_multiple_delegates() {
        let mut engine = RingEngine::new(TimingConfig::default());
        engine.register_through(make_store_through()).unwrap();
        engine.register_through(make_guard_through()).unwrap();

        assert_eq!(engine.command_registry().len(), 2);
        assert_eq!(engine.command_registry().permission_count(), 3);
    }

    #[test]
    fn command_registry_lookup_exact_match() {
        let mut engine = RingEngine::new(TimingConfig::default());
        engine.register_through(make_store_through()).unwrap();
        engine.register_through(make_guard_through()).unwrap();

        let result = engine.command_registry().lookup("store.artifact.create");
        assert!(result.is_some());
        assert_eq!(result.unwrap().delegate_name, "store");

        let result = engine.command_registry().lookup("guard.policy.evaluate");
        assert!(result.is_some());
        assert_eq!(result.unwrap().delegate_name, "guard");
    }

    #[test]
    fn command_registry_lookup_no_match() {
        let mut engine = RingEngine::new(TimingConfig::default());
        engine.register_through(make_store_through()).unwrap();

        assert!(engine.command_registry().lookup("nonexistent.command").is_none());
    }

    #[test]
    fn command_registry_delegate_with_no_permissions() {
        let mut engine = RingEngine::new(TimingConfig::default());
        let bare = Arc::new(DeclaredThrough {
            name: "bare".into(),
            prefix: "bare.".into(),
            perms: vec![],
        });
        engine.register_through(bare).unwrap();

        assert_eq!(engine.command_registry().len(), 1);
        assert_eq!(engine.command_registry().permission_count(), 0);
        // Delegate is registered but has no permission metadata
        assert!(engine.command_registry().lookup("bare.something").is_none());
    }

    #[test]
    fn command_registry_sibling_registration() {
        use soma_som_core::extension::DomainRequest;
        let mut engine = RingEngine::new(TimingConfig::default());
        let manifest = TestSiblingManifest::new("qi");

        engine
            .register_sibling(&manifest, None::<fn(&DomainRequest) -> Result<(), String>>)
            .unwrap();

        // TestSiblingThrough has no permission_requirements (default = empty)
        assert_eq!(engine.command_registry().len(), 1);
        assert_eq!(engine.command_registry().entries()[0].delegate_name, "qi");
        assert_eq!(engine.command_registry().permission_count(), 0);
    }

    #[test]
    fn command_registry_entries_order_matches_registration() {
        let mut engine = RingEngine::new(TimingConfig::default());
        engine.register_through(make_guard_through()).unwrap();
        engine.register_through(make_store_through()).unwrap();

        let names: Vec<&str> = engine
            .command_registry()
            .entries()
            .iter()
            .map(|e| e.delegate_name.as_str())
            .collect();
        assert_eq!(names, vec!["guard", "store"]);
    }

    #[test]
    fn command_registry_lookup_returns_correct_permissions() {
        let mut engine = RingEngine::new(TimingConfig::default());
        engine.register_through(make_store_through()).unwrap();

        let entry = engine.command_registry().lookup("store.artifact.read").unwrap();
        let perm = entry.permissions.iter().find(|p| p.command == "store.artifact.read").unwrap();
        assert_eq!(perm.min_role_key, "auth.role.viewer");
    }

    // ── Prefix collision detection tests ────────────────────────────

    #[test]
    fn register_through_identical_prefix_collision() {
        let mut engine = RingEngine::new(TimingConfig::default());
        engine.register_through(make_store_through()).unwrap();

        // Second delegate claiming "store." should fail.
        let dup = Arc::new(DeclaredThrough {
            name: "store-dup".into(),
            prefix: "store.".into(),
            perms: vec![],
        });
        let result = engine.register_through(dup);
        assert!(matches!(
            result,
            Err(RegistrationError::NamespaceConflict { .. })
        ));
    }

    #[test]
    fn register_through_subset_prefix_collision() {
        let mut engine = RingEngine::new(TimingConfig::default());
        engine.register_through(make_store_through()).unwrap();

        // "store.artifact." is a subset of "store." — collision.
        let subset = Arc::new(DeclaredThrough {
            name: "store-artifact-only".into(),
            prefix: "store.artifact.".into(),
            perms: vec![],
        });
        let result = engine.register_through(subset);
        assert!(matches!(
            result,
            Err(RegistrationError::NamespaceConflict { .. })
        ));
    }

    #[test]
    fn register_through_superset_prefix_collision() {
        let mut engine = RingEngine::new(TimingConfig::default());

        // Register narrow prefix first.
        let narrow = Arc::new(DeclaredThrough {
            name: "store-narrow".into(),
            prefix: "store.artifact.".into(),
            perms: vec![],
        });
        engine.register_through(narrow).unwrap();

        // Broader "store." overlaps with "store.artifact." — collision.
        let broad = Arc::new(DeclaredThrough {
            name: "store-broad".into(),
            prefix: "store.".into(),
            perms: vec![],
        });
        let result = engine.register_through(broad);
        assert!(matches!(
            result,
            Err(RegistrationError::NamespaceConflict { .. })
        ));
    }

    #[test]
    fn register_through_disjoint_prefixes_ok() {
        let mut engine = RingEngine::new(TimingConfig::default());
        engine.register_through(make_store_through()).unwrap();
        engine.register_through(make_guard_through()).unwrap();

        // "store." and "guard." are disjoint — both succeed.
        assert_eq!(engine.command_registry().len(), 2);
    }

    #[test]
    fn register_through_empty_prefixes_skips_check() {
        let mut engine = RingEngine::new(TimingConfig::default());
        engine.register_through(make_store_through()).unwrap();

        // A delegate with no claimed_prefixes() (default empty) skips collision check.
        // This preserves backward compatibility with legacy delegates.
        let legacy = Arc::new(TestSiblingThrough {
            id: "legacy-no-prefixes".into(),
        });
        engine.register_through(legacy).unwrap();
        assert_eq!(engine.command_registry().len(), 2);
    }

    #[test]
    fn register_through_prefixes_stored_in_registry() {
        let mut engine = RingEngine::new(TimingConfig::default());
        engine.register_through(make_store_through()).unwrap();

        let entry = &engine.command_registry().entries()[0];
        assert_eq!(entry.prefixes, vec!["store.".to_string()]);
    }

    #[test]
    fn command_registry_find_prefix_collision_direct() {
        let mut registry = CommandRegistry::new();
        registry.register_entry(
            "store",
            vec![],
            vec!["store.".to_string()],
            vec![],
        );

        // Exact match.
        assert!(registry
            .find_prefix_collision(&["store.".to_string()])
            .is_some());

        // Subset.
        assert!(registry
            .find_prefix_collision(&["store.artifact.".to_string()])
            .is_some());

        // Superset (not possible in practice, but the check is symmetric).
        // "st" is a prefix of "store." — collision.
        // Actually "st" is NOT a prefix of "store." in the starts_with sense.
        // Let me test a real superset: checking if "store." starts with "s"
        // — "s" is a prefix of "store.", so collision.

        // Disjoint.
        assert!(registry
            .find_prefix_collision(&["guard.".to_string()])
            .is_none());
    }

    // ── Schema registration tests ────────────────────────────────────

    #[test]
    fn schema_captured_on_register_through() {
        use soma_som_core::extension::{CommandSchema, SchemaField, SchemaFieldType};

        struct SchemaThrough;
        impl Extension for SchemaThrough {
            fn name(&self) -> &str { "schema-test" }
        }
        impl ThroughRing for SchemaThrough {
            fn handles(&self, cmd: &str) -> bool { cmd.starts_with("test.") }
            fn dispatch(&self, _: &Tree) -> Result<Tree, DelegationError> { Ok(Tree::new()) }
            fn claimed_prefixes(&self) -> Vec<String> { vec!["test.".into()] }
            fn command_schemas(&self) -> Vec<CommandSchema> {
                vec![
                    CommandSchema::new("test.create")
                        .field(SchemaField::required("name", SchemaFieldType::String)),
                ]
            }
        }

        let mut engine = RingEngine::new(TimingConfig::default());
        engine.register_through(Arc::new(SchemaThrough)).unwrap();

        let entry = &engine.command_registry().entries()[0];
        assert_eq!(entry.schemas.len(), 1);
        assert_eq!(entry.schemas[0].command_type, "test.create");
        assert_eq!(entry.schemas[0].fields.len(), 1);
    }

    #[test]
    fn schema_lookup_by_command_type() {
        use soma_som_core::extension::{CommandSchema, SchemaField, SchemaFieldType};

        let mut registry = CommandRegistry::new();
        registry.register_entry(
            "store",
            vec![],
            vec!["store.".into()],
            vec![
                CommandSchema::new("store.artifact.create")
                    .field(SchemaField::required("name", SchemaFieldType::String)),
                CommandSchema::new("store.artifact.delete")
                    .field(SchemaField::required("artifact_id", SchemaFieldType::String)),
            ],
        );

        let schema = registry.lookup_schema("store.artifact.create");
        assert!(schema.is_some());
        assert_eq!(schema.unwrap().fields.len(), 1);

        let schema = registry.lookup_schema("store.artifact.delete");
        assert!(schema.is_some());

        // No schema declared.
        assert!(registry.lookup_schema("store.artifact.list").is_none());
    }

    #[test]
    fn schema_count() {
        use soma_som_core::extension::{CommandSchema, SchemaField, SchemaFieldType};

        let mut registry = CommandRegistry::new();
        registry.register_entry(
            "store",
            vec![],
            vec![],
            vec![
                CommandSchema::new("store.create")
                    .field(SchemaField::required("name", SchemaFieldType::String)),
                CommandSchema::new("store.delete"),
            ],
        );
        registry.register_entry("guard", vec![], vec![], vec![CommandSchema::new("guard.eval")]);

        assert_eq!(registry.schema_count(), 3);
    }

    #[test]
    fn empty_schemas_backward_compatible() {
        let mut engine = RingEngine::new(TimingConfig::default());
        engine.register_through(make_store_through()).unwrap();

        let entry = &engine.command_registry().entries()[0];
        assert!(entry.schemas.is_empty());
    }

    // ── ring_fingerprint in reports ────────────────────────────────────

    // S5 — CycleReport includes ring_fingerprint field
    #[test]
    fn cycle_report_includes_ring_fingerprint() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        let report = engine.cycle().unwrap();
        assert_ne!(report.ring_fingerprint, [0u8; 32]);
    }

    // S6 — GenesisReport includes ring_fingerprint field
    #[test]
    fn genesis_report_includes_ring_fingerprint() {
        let mut engine = make_engine();
        let report = engine.genesis(TEST_SEED).unwrap();
        assert_ne!(report.ring_fingerprint, [0u8; 32]);
    }

    // S7 — CycleReport ring_fingerprint matches genesis-derived computation
    #[test]
    fn cycle_report_ring_fingerprint_matches_genesis_derivation() {
        use soma_som_core::fingerprint::ring_fingerprint;

        let mut engine = make_engine();
        let genesis = engine.genesis(TEST_SEED).unwrap();
        let report = engine.cycle().unwrap();
        // ring_fingerprint is derived from genesis system_fingerprint, not the evolving one
        let expected = ring_fingerprint(
            &genesis.genesis.system_fingerprint,
            &engine.boundary_verifying_key(),
        );
        assert_eq!(report.ring_fingerprint, expected);
        assert_eq!(report.ring_fingerprint, genesis.ring_fingerprint);
    }

    // S8 — ring_fingerprint is stable across cycles
    #[test]
    fn ring_fingerprint_stable_across_cycles() {
        let mut engine = make_engine();
        engine.genesis(TEST_SEED).unwrap();
        let r1 = engine.cycle().unwrap();
        let r2 = engine.cycle().unwrap();
        let r3 = engine.cycle().unwrap();
        // Boundary key doesn't change; system_fingerprint may evolve
        // but with StubRingProcessor deterministic processing, the
        // ring_fingerprint derivation is consistent.
        assert_eq!(r1.ring_fingerprint, r2.ring_fingerprint);
        assert_eq!(r2.ring_fingerprint, r3.ring_fingerprint);
    }
}