nucleation 0.5.1

//! Redstone simulation: MCHPRS world, typed circuit executor and its
//! Value/IoType/LayoutFunction/ExecutionMode/OutputCondition/SortStrategy
//! companions, plus the redstone logic graph. Port of `ffi/simulation.rs`.
//!
//! Porting notes (see `PORTING.md`):
//! - Payload-carrying Rust enums (`Value`, `IoType`, `LayoutFunction`,
//!   `OutputCondition`, `ExecutionMode`, `SortStrategy`) keep the old manual
//!   pattern (rule 10): opaque + `from_*`/factory constructors + fallible
//!   `as_*` accessors + `type_name`/`name` writing a discriminant string.
//! - Block positions cross as flat `[x,y,z, x,y,z, ...]` `&[i32]` slices.
//! - The `*_from_region` / `with_*` methods that took a `DefinitionRegion`
//!   opaque take the region's blocks as a flat position slice instead: the
//!   `definition_region` bridge module is owned by a separate port, and
//!   `DefinitionRegion::from_positions` reconstructs the region losslessly for
//!   IO-layout purposes. Region-opaque overloads can be added once that module
//!   lands.
//! - `schematic_simulate_use_block` wrote the simulated state back into the
//!   input schematic pointer; the bridge version returns a new `Schematic`
//!   instead of mutating in place.
//!
//! Omitted from port: `mchprs_world_free`, `value_free`, `io_type_free`,
//! `layout_function_free`, `output_condition_free`, `execution_mode_free`,
//! `sort_strategy_free`, `io_layout_builder_free`, `io_layout_free`,
//! `circuit_builder_free`, `typed_executor_free`, `redstonegraph_free` —
//! destructors are generated by Diplomat.
//! Omitted from port: `redstonegraph_features_json` — documented alias of
//! `redstonegraph_features`; ported once as `RedstoneGraph::features_json`.

use crate::simulation::typed_executor::{ExecutionResult, LayoutInfo, StateMode, Value};
use crate::simulation::CustomIoChange;
use std::collections::HashMap;

/// Parse a flat `[x,y,z,x,y,z,...]` slice into position triples. Any trailing
/// partial triple is ignored (matches the old `count * 3` contract).
pub(crate) fn positions_from_flat(flat: &[i32]) -> Vec<(i32, i32, i32)> {
    flat.chunks_exact(3).map(|c| (c[0], c[1], c[2])).collect()
}

/// Parse a state mode string ("stateless" | "stateful" | "manual").
pub(crate) fn parse_state_mode(s: &str) -> Option<StateMode> {
    match s.to_lowercase().as_str() {
        "stateless" => Some(StateMode::Stateless),
        "stateful" => Some(StateMode::Stateful),
        "manual" => Some(StateMode::Manual),
        _ => None,
    }
}

/// Parse inputs JSON to `HashMap<String, Value>`.
/// Format: `{"name": {"type": "u32", "value": 42}, ...}` (or shorthand values).
pub(crate) fn parse_inputs_json(json: &str) -> Result<HashMap<String, Value>, String> {
    let parsed: serde_json::Value =
        serde_json::from_str(json).map_err(|e| format!("Invalid JSON: {}", e))?;

    let obj = parsed
        .as_object()
        .ok_or_else(|| "Inputs must be a JSON object".to_string())?;

    let mut inputs = HashMap::new();
    for (name, val) in obj {
        let value = parse_json_value(val)?;
        inputs.insert(name.clone(), value);
    }
    Ok(inputs)
}

/// Parse a single JSON value to a `Value`.
/// Supports `{"type": "u32", "value": 42}` or shorthand (`42`, `true`, `"s"`).
pub(crate) fn parse_json_value(v: &serde_json::Value) -> Result<Value, String> {
    if let Some(obj) = v.as_object() {
        if let (Some(type_val), Some(value_val)) = (obj.get("type"), obj.get("value")) {
            if let Some(type_str) = type_val.as_str() {
                return match type_str {
                    "u32" => {
                        let n = value_val
                            .as_u64()
                            .ok_or("Expected unsigned integer for u32")?;
                        Ok(Value::U32(n as u32))
                    }
                    "i32" => {
                        let n = value_val.as_i64().ok_or("Expected integer for i32")?;
                        Ok(Value::I32(n as i32))
                    }
                    "f32" => {
                        let n = value_val.as_f64().ok_or("Expected number for f32")?;
                        Ok(Value::F32(n as f32))
                    }
                    "bool" => {
                        let b = value_val.as_bool().ok_or("Expected boolean for bool")?;
                        Ok(Value::Bool(b))
                    }
                    "string" => {
                        let s = value_val.as_str().ok_or("Expected string for string")?;
                        Ok(Value::String(s.to_string()))
                    }
                    _ => Err(format!("Unknown value type: {}", type_str)),
                };
            }
        }
    }

    match v {
        serde_json::Value::Bool(b) => Ok(Value::Bool(*b)),
        serde_json::Value::Number(n) => {
            if let Some(i) = n.as_i64() {
                if i >= 0 {
                    Ok(Value::U32(i as u32))
                } else {
                    Ok(Value::I32(i as i32))
                }
            } else if let Some(f) = n.as_f64() {
                Ok(Value::F32(f as f32))
            } else {
                Err("Cannot parse number".to_string())
            }
        }
        serde_json::Value::String(s) => Ok(Value::String(s.clone())),
        _ => Err(format!("Cannot convert JSON value to Value: {}", v)),
    }
}

/// Serialize a `Value` to a `serde_json::Value`.
pub(crate) fn value_to_json(v: &Value) -> serde_json::Value {
    match v {
        Value::U32(n) => serde_json::json!({"type": "u32", "value": n}),
        Value::U64(n) => serde_json::json!({"type": "u64", "value": n}),
        Value::I32(n) => serde_json::json!({"type": "i32", "value": n}),
        Value::I64(n) => serde_json::json!({"type": "i64", "value": n}),
        Value::F32(n) => serde_json::json!({"type": "f32", "value": n}),
        Value::Bool(b) => serde_json::json!({"type": "bool", "value": b}),
        Value::String(s) => serde_json::json!({"type": "string", "value": s}),
        Value::BitArray(bits) => serde_json::json!({"type": "bit_array", "value": bits}),
        Value::Bytes(bytes) => serde_json::json!({"type": "bytes", "value": bytes}),
        Value::Array(arr) => {
            let vals: Vec<serde_json::Value> = arr.iter().map(value_to_json).collect();
            serde_json::json!({"type": "array", "value": vals})
        }
        Value::Struct(fields) => {
            let obj: serde_json::Map<String, serde_json::Value> = fields
                .iter()
                .map(|(k, v)| (k.clone(), value_to_json(v)))
                .collect();
            serde_json::json!({"type": "struct", "value": obj})
        }
    }
}

/// Serialize an `ExecutionResult` to a JSON string.
pub(crate) fn serialize_execution_result(result: &ExecutionResult) -> String {
    let mut outputs = serde_json::Map::new();
    for (name, value) in &result.outputs {
        outputs.insert(name.clone(), value_to_json(value));
    }
    let json = serde_json::json!({
        "outputs": outputs,
        "ticks_elapsed": result.ticks_elapsed,
        "condition_met": result.condition_met,
    });
    serde_json::to_string(&json).unwrap_or_else(|_| "{}".to_string())
}

/// Serialize `LayoutInfo` to a JSON string.
pub(crate) fn serialize_layout_info(info: &LayoutInfo) -> String {
    fn side(
        map: &HashMap<String, crate::simulation::typed_executor::IoLayoutInfo>,
    ) -> serde_json::Value {
        let mut out = serde_json::Map::new();
        for (name, li) in map {
            let positions: Vec<Vec<i32>> = li
                .positions
                .iter()
                .map(|&(x, y, z)| vec![x, y, z])
                .collect();
            out.insert(
                name.clone(),
                serde_json::json!({
                    "io_type": li.io_type,
                    "positions": positions,
                    "bit_count": li.bit_count,
                }),
            );
        }
        serde_json::Value::Object(out)
    }
    let json = serde_json::json!({
        "inputs": side(&info.inputs),
        "outputs": side(&info.outputs),
    });
    serde_json::to_string(&json).unwrap_or_else(|_| "{}".to_string())
}

/// Serialize custom IO changes to a JSON array string.
pub(crate) fn serialize_custom_io_changes(changes: &[CustomIoChange]) -> String {
    let arr: Vec<serde_json::Value> = changes
        .iter()
        .map(|c| {
            serde_json::json!({
                "x": c.x,
                "y": c.y,
                "z": c.z,
                "old_power": c.old_power,
                "new_power": c.new_power,
            })
        })
        .collect();
    serde_json::to_string(&arr).unwrap_or_else(|_| "[]".to_string())
}

#[diplomat::bridge]
pub mod ffi {
    use super::super::schematic::ffi::Schematic;
    use super::super::shared::ffi::NucleationError;
    use crate::definition_region::DefinitionRegion;
    use crate::simulation::circuit_builder::CircuitBuilder as InnerCircuitBuilder;
    use crate::simulation::typed_executor::{
        ExecutionMode as InnerExecutionMode, IoLayout as InnerIoLayout,
        IoLayoutBuilder as InnerIoLayoutBuilder, IoType as InnerIoType,
        LayoutFunction as InnerLayoutFunction, OutputCondition as InnerOutputCondition,
        SortStrategy as InnerSortStrategy, TypedCircuitExecutor as InnerTypedCircuitExecutor,
        Value as InnerValue,
    };
    use crate::simulation::SimulationOptions;
    use diplomat_runtime::DiplomatWrite;
    use mchprs_blocks::BlockPos as MPos;
    use std::fmt::Write;

    // ─── MchprsWorld ─────────────────────────────────────────────────────────

    /// A running MCHPRS redstone simulation. Wraps [`crate::simulation::MchprsWorld`].
    #[diplomat::opaque_mut]
    pub struct MchprsWorld(pub(crate) crate::simulation::MchprsWorld);

    impl MchprsWorld {
        /// Create a simulation world from a schematic with default options.
        pub fn create(schematic: &Schematic) -> Result<Box<MchprsWorld>, NucleationError> {
            crate::simulation::MchprsWorld::new(schematic.0.clone())
                .map(|w| Box::new(MchprsWorld(w)))
                .map_err(|_| NucleationError::Simulation)
        }

        /// Create a simulation world with explicit options.
        pub fn create_with_options(
            schematic: &Schematic,
            optimize: bool,
            io_only: bool,
        ) -> Result<Box<MchprsWorld>, NucleationError> {
            let options = SimulationOptions {
                optimize,
                io_only,
                custom_io: Vec::new(),
            };
            crate::simulation::MchprsWorld::with_options(schematic.0.clone(), options)
                .map(|w| Box::new(MchprsWorld(w)))
                .map_err(|_| NucleationError::Simulation)
        }

        /// Create a simulation world with custom IO positions
        /// (`custom_io_positions` is flat `[x,y,z, x,y,z, ...]`).
        pub fn create_with_custom_io(
            schematic: &Schematic,
            optimize: bool,
            io_only: bool,
            custom_io_positions: &[i32],
        ) -> Result<Box<MchprsWorld>, NucleationError> {
            let custom_io = custom_io_positions
                .chunks_exact(3)
                .map(|c| MPos::new(c[0], c[1], c[2]))
                .collect();
            let options = SimulationOptions {
                optimize,
                io_only,
                custom_io,
            };
            crate::simulation::MchprsWorld::with_options(schematic.0.clone(), options)
                .map(|w| Box::new(MchprsWorld(w)))
                .map_err(|_| NucleationError::Simulation)
        }

        /// One-shot convenience (old ABI: `schematic_simulate_use_block`):
        /// build a world from `schematic`, fire an `on_use_block` event per
        /// triple in `events_xyz`, run `ticks` ticks, and return the simulated
        /// schematic. Unlike the old ABI (which mutated in place), this returns
        /// a new `Schematic`.
        pub fn simulate_use_block(
            schematic: &Schematic,
            ticks: u32,
            events_xyz: &[i32],
        ) -> Result<Box<Schematic>, NucleationError> {
            let mut world = crate::simulation::MchprsWorld::new(schematic.0.clone())
                .map_err(|_| NucleationError::Simulation)?;
            for ev in events_xyz.chunks_exact(3) {
                world.on_use_block(MPos::new(ev[0], ev[1], ev[2]));
            }
            world.tick(ticks);
            world.sync_to_schematic();
            Ok(Box::new(Schematic(world.into_schematic())))
        }

        /// Advance the simulation by `ticks` ticks.
        pub fn tick(&mut self, ticks: u32) {
            self.0.tick(ticks);
        }

        /// Flush pending changes from the compiler to the world.
        pub fn flush(&mut self) {
            self.0.flush();
        }

        /// Set the power state of a lever.
        pub fn set_lever_power(&mut self, x: i32, y: i32, z: i32, powered: bool) {
            self.0.set_lever_power(MPos::new(x, y, z), powered);
        }

        /// Get the power state of a lever.
        pub fn get_lever_power(&self, x: i32, y: i32, z: i32) -> bool {
            self.0.get_lever_power(MPos::new(x, y, z))
        }

        /// Whether a redstone lamp is lit at the given position.
        pub fn is_lit(&self, x: i32, y: i32, z: i32) -> bool {
            self.0.is_lit(MPos::new(x, y, z))
        }

        /// Set the signal strength (0-15) at a custom IO position.
        pub fn set_signal_strength(&mut self, x: i32, y: i32, z: i32, strength: u8) {
            self.0.set_signal_strength(MPos::new(x, y, z), strength);
        }

        /// Get the signal strength (0-15) at a position.
        pub fn get_signal_strength(&self, x: i32, y: i32, z: i32) -> u8 {
            self.0.get_signal_strength(MPos::new(x, y, z))
        }

        /// Simulate a right-click on a block (typically a lever).
        pub fn on_use_block(&mut self, x: i32, y: i32, z: i32) {
            self.0.on_use_block(MPos::new(x, y, z));
        }

        /// Sync the simulation state back to the internal schematic.
        pub fn sync_to_schematic(&mut self) {
            self.0.sync_to_schematic();
        }

        /// A clone of the world's schematic.
        pub fn get_schematic(&self) -> Box<Schematic> {
            Box::new(Schematic(self.0.get_schematic().clone()))
        }

        /// The redstone power level (0-15) at a position.
        pub fn get_redstone_power(&self, x: i32, y: i32, z: i32) -> u8 {
            self.0.get_redstone_power(MPos::new(x, y, z))
        }

        /// Check for custom IO changes since the last check. Call before
        /// `poll_custom_io_changes_json`.
        pub fn check_custom_io_changes(&mut self) {
            self.0.check_custom_io_changes();
        }

        /// Queued custom IO changes as a JSON array
        /// (`[{"x":..,"y":..,"z":..,"old_power":..,"new_power":..}, ...]`),
        /// clearing the queue.
        pub fn poll_custom_io_changes_json(&mut self, out: &mut DiplomatWrite) {
            let changes = self.0.poll_custom_io_changes();
            let _ = write!(out, "{}", super::serialize_custom_io_changes(&changes));
        }

        /// Queued custom IO changes as JSON without clearing the queue.
        pub fn peek_custom_io_changes_json(&self, out: &mut DiplomatWrite) {
            let changes = self.0.peek_custom_io_changes();
            let _ = write!(out, "{}", super::serialize_custom_io_changes(changes));
        }

        /// Clear all queued custom IO changes.
        pub fn clear_custom_io_changes(&mut self) {
            self.0.clear_custom_io_changes();
        }

        /// Extract the compiled (post-optimization) redstone logic graph.
        pub fn export_graph(&self) -> Result<Box<RedstoneGraph>, NucleationError> {
            self.0
                .export_graph()
                .map(|g| Box::new(RedstoneGraph(g)))
                .map_err(|_| NucleationError::Simulation)
        }

        /// Extract the structural (pre-fold, as-built) redstone logic graph.
        pub fn export_graph_structural(&self) -> Result<Box<RedstoneGraph>, NucleationError> {
            self.0
                .export_graph_structural()
                .map(|g| Box::new(RedstoneGraph(g)))
                .map_err(|_| NucleationError::Simulation)
        }
    }

    // ─── Value ───────────────────────────────────────────────────────────────

    /// A typed circuit value (payload-carrying enum; PORTING rule 10).
    #[diplomat::opaque]
    pub struct Value(pub(crate) InnerValue);

    impl Value {
        /// Create an unsigned 32-bit integer value.
        pub fn from_u32(v: u32) -> Box<Value> {
            Box::new(Value(InnerValue::U32(v)))
        }

        /// Create a signed 32-bit integer value.
        pub fn from_i32(v: i32) -> Box<Value> {
            Box::new(Value(InnerValue::I32(v)))
        }

        /// Create a 32-bit IEEE 754 float value.
        pub fn from_f32(v: f32) -> Box<Value> {
            Box::new(Value(InnerValue::F32(v)))
        }

        /// Create a boolean value.
        pub fn from_bool(v: bool) -> Box<Value> {
            Box::new(Value(InnerValue::Bool(v)))
        }

        /// Create a string value. Fails if the bytes are not valid UTF-8.
        pub fn from_string(s: &DiplomatStr) -> Result<Box<Value>, NucleationError> {
            let s = std::str::from_utf8(s).map_err(|_| NucleationError::InvalidArgument)?;
            Ok(Box::new(Value(InnerValue::String(s.to_string()))))
        }

        /// The value as u32. Also accepts u64/non-negative signed ints that
        /// fit, and bool (false → 0, true → 1); fails otherwise.
        pub fn as_u32(&self) -> Result<u32, NucleationError> {
            self.0
                .as_u32()
                .map_err(|_| NucleationError::InvalidArgument)
        }

        /// The value as i32. Also accepts i64 values in i32 range; fails for
        /// other types.
        pub fn as_i32(&self) -> Result<i32, NucleationError> {
            self.0
                .as_i32()
                .map_err(|_| NucleationError::InvalidArgument)
        }

        /// The value as f32; fails if this is not an f32 value.
        pub fn as_f32(&self) -> Result<f32, NucleationError> {
            self.0
                .as_f32()
                .map_err(|_| NucleationError::InvalidArgument)
        }

        /// The value as bool; fails if this is not a bool value.
        pub fn as_bool(&self) -> Result<bool, NucleationError> {
            self.0
                .as_bool()
                .map_err(|_| NucleationError::InvalidArgument)
        }

        /// The string payload; fails if this is not a string value.
        pub fn as_string(&self, out: &mut DiplomatWrite) -> Result<(), NucleationError> {
            let s = self
                .0
                .as_str()
                .map_err(|_| NucleationError::InvalidArgument)?;
            let _ = write!(out, "{}", s);
            Ok(())
        }

        /// The type name (e.g. "u32", "bool", "string").
        pub fn type_name(&self, out: &mut DiplomatWrite) {
            let name = match &self.0 {
                InnerValue::U32(_) => "u32",
                InnerValue::U64(_) => "u64",
                InnerValue::I32(_) => "i32",
                InnerValue::I64(_) => "i64",
                InnerValue::F32(_) => "f32",
                InnerValue::Bool(_) => "bool",
                InnerValue::String(_) => "string",
                InnerValue::BitArray(_) => "bit_array",
                InnerValue::Bytes(_) => "bytes",
                InnerValue::Array(_) => "array",
                InnerValue::Struct(_) => "struct",
            };
            let _ = write!(out, "{}", name);
        }
    }

    // ─── IoType ──────────────────────────────────────────────────────────────

    /// The wire type of a circuit input/output (PORTING rule 10).
    #[diplomat::opaque]
    pub struct IoType(pub(crate) InnerIoType);

    impl IoType {
        /// Unsigned integer of `bits` bits (LSB-first bit order).
        pub fn unsigned_int(bits: u32) -> Box<IoType> {
            Box::new(IoType(InnerIoType::UnsignedInt {
                bits: bits as usize,
            }))
        }

        /// Signed integer of `bits` bits (two's complement, LSB-first).
        pub fn signed_int(bits: u32) -> Box<IoType> {
            Box::new(IoType(InnerIoType::SignedInt {
                bits: bits as usize,
            }))
        }

        /// 32-bit IEEE 754 float (crosses the wire as its 32 raw bits).
        pub fn float32() -> Box<IoType> {
            Box::new(IoType(InnerIoType::Float32))
        }

        /// Single boolean (1 bit).
        pub fn boolean() -> Box<IoType> {
            Box::new(IoType(InnerIoType::Boolean))
        }

        /// Fixed-length ASCII string of `chars` characters (8 bits per char;
        /// shorter strings are zero-padded, longer ones truncated).
        pub fn ascii(chars: u32) -> Box<IoType> {
            Box::new(IoType(InnerIoType::Ascii {
                chars: chars as usize,
            }))
        }
    }

    // ─── LayoutFunction ──────────────────────────────────────────────────────

    /// Maps logical bits to physical positions (PORTING rule 10).
    #[diplomat::opaque]
    pub struct LayoutFunction(pub(crate) InnerLayoutFunction);

    impl LayoutFunction {
        /// One bit per position: signal strength 0 = false, 15 = true.
        /// The most common layout for traditional redstone circuits.
        pub fn one_to_one() -> Box<LayoutFunction> {
            Box::new(LayoutFunction(InnerLayoutFunction::OneToOne))
        }

        /// Four bits per position, packed as a hex nibble (0-15) with the
        /// lowest bit first; uses `ceil(bits / 4)` positions (4x denser than
        /// one-to-one).
        pub fn packed4() -> Box<LayoutFunction> {
            Box::new(LayoutFunction(InnerLayoutFunction::Packed4))
        }

        /// Custom bit-to-position mapping.
        pub fn custom(mapping: &[u32]) -> Result<Box<LayoutFunction>, NucleationError> {
            if mapping.is_empty() {
                return Err(NucleationError::InvalidArgument);
            }
            Ok(Box::new(LayoutFunction(InnerLayoutFunction::Custom(
                mapping.iter().map(|&m| m as usize).collect(),
            ))))
        }

        /// 2D matrix layout, elements laid out row by row; element bits are
        /// packed 4 per position (nibbles).
        pub fn row_major(rows: u32, cols: u32, bits_per_element: u32) -> Box<LayoutFunction> {
            Box::new(LayoutFunction(InnerLayoutFunction::RowMajor {
                rows: rows as usize,
                cols: cols as usize,
                bits_per_element: bits_per_element as usize,
            }))
        }

        /// 2D matrix layout, elements laid out column by column; element bits
        /// are packed 4 per position (nibbles).
        pub fn column_major(rows: u32, cols: u32, bits_per_element: u32) -> Box<LayoutFunction> {
            Box::new(LayoutFunction(InnerLayoutFunction::ColumnMajor {
                rows: rows as usize,
                cols: cols as usize,
                bits_per_element: bits_per_element as usize,
            }))
        }

        /// Screen layout: pixels laid out row by row, left to right; pixel
        /// bits are packed 4 per position (nibbles).
        pub fn scanline(width: u32, height: u32, bits_per_pixel: u32) -> Box<LayoutFunction> {
            Box::new(LayoutFunction(InnerLayoutFunction::Scanline {
                width: width as usize,
                height: height as usize,
                bits_per_pixel: bits_per_pixel as usize,
            }))
        }
    }

    // ─── OutputCondition ─────────────────────────────────────────────────────

    /// A condition on an output value, for `ExecutionMode::until_condition`
    /// (PORTING rule 10).
    #[diplomat::opaque]
    pub struct OutputCondition(pub(crate) InnerOutputCondition);

    impl OutputCondition {
        /// Met when the output equals `value`.
        pub fn equals(value: &Value) -> Box<OutputCondition> {
            Box::new(OutputCondition(InnerOutputCondition::Equals(
                value.0.clone(),
            )))
        }

        /// Met when the output does not equal `value`.
        pub fn not_equals(value: &Value) -> Box<OutputCondition> {
            Box::new(OutputCondition(InnerOutputCondition::NotEquals(
                value.0.clone(),
            )))
        }

        /// Met when the output is greater than `value`. Numeric only: both
        /// sides must be the same numeric type (u32/i32/f32), else never met.
        pub fn greater_than(value: &Value) -> Box<OutputCondition> {
            Box::new(OutputCondition(InnerOutputCondition::GreaterThan(
                value.0.clone(),
            )))
        }

        /// Met when the output is less than `value`. Numeric only: both sides
        /// must be the same numeric type (u32/i32/f32), else never met.
        pub fn less_than(value: &Value) -> Box<OutputCondition> {
            Box::new(OutputCondition(InnerOutputCondition::LessThan(
                value.0.clone(),
            )))
        }

        /// Met when `output & mask` is non-zero (flag checking). Integer
        /// outputs (u32/i32) only; never met for other types.
        pub fn bitwise_and(mask: u32) -> Box<OutputCondition> {
            Box::new(OutputCondition(InnerOutputCondition::BitwiseAnd(
                mask as u64,
            )))
        }
    }

    // ─── ExecutionMode ───────────────────────────────────────────────────────

    /// How long to run the circuit for one `execute` call (PORTING rule 10).
    #[diplomat::opaque]
    pub struct ExecutionMode(pub(crate) InnerExecutionMode);

    impl ExecutionMode {
        /// Run for exactly `ticks` ticks.
        pub fn fixed_ticks(ticks: u32) -> Box<ExecutionMode> {
            Box::new(ExecutionMode(InnerExecutionMode::FixedTicks { ticks }))
        }

        /// Run until the output named `output_name` meets `condition`,
        /// checking every `check_interval` ticks, giving up after `max_ticks`
        /// ticks (the result's `condition_met` reports which happened).
        pub fn until_condition(
            output_name: &DiplomatStr,
            condition: &OutputCondition,
            max_ticks: u32,
            check_interval: u32,
        ) -> Result<Box<ExecutionMode>, NucleationError> {
            let name =
                std::str::from_utf8(output_name).map_err(|_| NucleationError::InvalidArgument)?;
            Ok(Box::new(ExecutionMode(
                InnerExecutionMode::UntilCondition {
                    output_name: name.to_string(),
                    condition: condition.0.clone(),
                    max_ticks,
                    check_interval,
                },
            )))
        }

        /// Run until any output changes from its initial reading, checking
        /// every `check_interval` ticks, giving up after `max_ticks` ticks.
        pub fn until_change(max_ticks: u32, check_interval: u32) -> Box<ExecutionMode> {
            Box::new(ExecutionMode(InnerExecutionMode::UntilChange {
                max_ticks,
                check_interval,
            }))
        }

        /// Run (one tick at a time) until all outputs have been unchanged for
        /// `stable_ticks` consecutive ticks, giving up after `max_ticks`
        /// ticks (the result's `condition_met` reports stability).
        pub fn until_stable(stable_ticks: u32, max_ticks: u32) -> Box<ExecutionMode> {
            Box::new(ExecutionMode(InnerExecutionMode::UntilStable {
                stable_ticks,
                max_ticks,
            }))
        }
    }

    // ─── SortStrategy ────────────────────────────────────────────────────────

    /// Ordering applied to region positions before bit assignment
    /// (PORTING rule 10).
    #[diplomat::opaque]
    pub struct SortStrategy(pub(crate) InnerSortStrategy);

    impl SortStrategy {
        /// Sort by Y ascending, then X, then Z (default Minecraft layer
        /// order). The first position after sorting is bit 0 (LSB).
        pub fn yxz() -> Box<SortStrategy> {
            Box::new(SortStrategy(InnerSortStrategy::YXZ))
        }

        /// Sort by X ascending, then Y, then Z.
        pub fn xyz() -> Box<SortStrategy> {
            Box::new(SortStrategy(InnerSortStrategy::XYZ))
        }

        /// Sort by Z ascending, then Y, then X.
        pub fn zyx() -> Box<SortStrategy> {
            Box::new(SortStrategy(InnerSortStrategy::ZYX))
        }

        /// Sort by Y descending, then X ascending, then Z ascending.
        pub fn y_desc_xz() -> Box<SortStrategy> {
            Box::new(SortStrategy(InnerSortStrategy::YDescXZ))
        }

        /// Sort by X descending, then Y ascending, then Z ascending.
        pub fn x_desc_yz() -> Box<SortStrategy> {
            Box::new(SortStrategy(InnerSortStrategy::XDescYZ))
        }

        /// Sort by Z descending, then Y ascending, then X ascending.
        pub fn z_desc_yx() -> Box<SortStrategy> {
            Box::new(SortStrategy(InnerSortStrategy::ZDescYX))
        }

        /// Old ABI name: `sort_strategy_descending`.
        pub fn descending() -> Box<SortStrategy> {
            Box::new(SortStrategy(InnerSortStrategy::YXZDesc))
        }

        /// Sort by Euclidean distance from the reference point, closest
        /// first (ties broken by Y, X, Z ascending).
        pub fn distance_from(x: i32, y: i32, z: i32) -> Box<SortStrategy> {
            Box::new(SortStrategy(InnerSortStrategy::DistanceFrom {
                reference: (x, y, z),
            }))
        }

        /// Sort by Euclidean distance from the reference point, farthest
        /// first (ties broken by Y, X, Z descending).
        pub fn distance_from_desc(x: i32, y: i32, z: i32) -> Box<SortStrategy> {
            Box::new(SortStrategy(InnerSortStrategy::DistanceFromDesc {
                reference: (x, y, z),
            }))
        }

        /// Keep positions in the order they were added (no sorting). Useful
        /// when positions were ordered manually or box order matters.
        pub fn preserve() -> Box<SortStrategy> {
            Box::new(SortStrategy(InnerSortStrategy::Preserve))
        }

        /// Reverse of the order positions were added.
        pub fn reverse() -> Box<SortStrategy> {
            Box::new(SortStrategy(InnerSortStrategy::Reverse))
        }

        /// Parse from a name (e.g. "yxz", "descending", "preserve").
        pub fn from_string(s: &DiplomatStr) -> Result<Box<SortStrategy>, NucleationError> {
            let s = std::str::from_utf8(s).map_err(|_| NucleationError::InvalidArgument)?;
            InnerSortStrategy::from_str(s)
                .map(|st| Box::new(SortStrategy(st)))
                .ok_or(NucleationError::InvalidArgument)
        }

        /// The strategy name.
        pub fn name(&self, out: &mut DiplomatWrite) {
            let _ = write!(out, "{}", self.0.name());
        }
    }

    // ─── IoLayoutBuilder / IoLayout ──────────────────────────────────────────

    /// Builder for an [`IoLayout`]. `build` consumes it (PORTING rule 11).
    #[diplomat::opaque_mut]
    pub struct IoLayoutBuilder(pub(crate) Option<InnerIoLayoutBuilder>);

    impl IoLayoutBuilder {
        /// Create an empty layout builder.
        pub fn create() -> Box<IoLayoutBuilder> {
            Box::new(IoLayoutBuilder(Some(InnerIoLayoutBuilder::new())))
        }

        /// Add an input. `positions` is flat `[x,y,z, x,y,z, ...]`.
        pub fn add_input(
            &mut self,
            name: &DiplomatStr,
            io_type: &IoType,
            layout: &LayoutFunction,
            positions: &[i32],
        ) -> Result<(), NucleationError> {
            let name = std::str::from_utf8(name).map_err(|_| NucleationError::InvalidArgument)?;
            let inner = self.0.take().ok_or(NucleationError::AlreadyConsumed)?;
            match inner.add_input(
                name,
                io_type.0.clone(),
                layout.0.clone(),
                super::positions_from_flat(positions),
            ) {
                Ok(b) => {
                    self.0 = Some(b);
                    Ok(())
                }
                Err(_) => Err(NucleationError::InvalidArgument),
            }
        }

        /// Add an output. `positions` is flat `[x,y,z, x,y,z, ...]`.
        pub fn add_output(
            &mut self,
            name: &DiplomatStr,
            io_type: &IoType,
            layout: &LayoutFunction,
            positions: &[i32],
        ) -> Result<(), NucleationError> {
            let name = std::str::from_utf8(name).map_err(|_| NucleationError::InvalidArgument)?;
            let inner = self.0.take().ok_or(NucleationError::AlreadyConsumed)?;
            match inner.add_output(
                name,
                io_type.0.clone(),
                layout.0.clone(),
                super::positions_from_flat(positions),
            ) {
                Ok(b) => {
                    self.0 = Some(b);
                    Ok(())
                }
                Err(_) => Err(NucleationError::InvalidArgument),
            }
        }

        /// Add an input with automatic layout inference.
        pub fn add_input_auto(
            &mut self,
            name: &DiplomatStr,
            io_type: &IoType,
            positions: &[i32],
        ) -> Result<(), NucleationError> {
            let name = std::str::from_utf8(name).map_err(|_| NucleationError::InvalidArgument)?;
            let inner = self.0.take().ok_or(NucleationError::AlreadyConsumed)?;
            match inner.add_input_auto(
                name,
                io_type.0.clone(),
                super::positions_from_flat(positions),
            ) {
                Ok(b) => {
                    self.0 = Some(b);
                    Ok(())
                }
                Err(_) => Err(NucleationError::InvalidArgument),
            }
        }

        /// Add an output with automatic layout inference.
        pub fn add_output_auto(
            &mut self,
            name: &DiplomatStr,
            io_type: &IoType,
            positions: &[i32],
        ) -> Result<(), NucleationError> {
            let name = std::str::from_utf8(name).map_err(|_| NucleationError::InvalidArgument)?;
            let inner = self.0.take().ok_or(NucleationError::AlreadyConsumed)?;
            match inner.add_output_auto(
                name,
                io_type.0.clone(),
                super::positions_from_flat(positions),
            ) {
                Ok(b) => {
                    self.0 = Some(b);
                    Ok(())
                }
                Err(_) => Err(NucleationError::InvalidArgument),
            }
        }

        /// Add an input from a region given as flat block positions (sorted by
        /// the default YXZ strategy, matching the old region semantics).
        pub fn add_input_from_region(
            &mut self,
            name: &DiplomatStr,
            io_type: &IoType,
            layout: &LayoutFunction,
            region_positions: &[i32],
        ) -> Result<(), NucleationError> {
            let name = std::str::from_utf8(name).map_err(|_| NucleationError::InvalidArgument)?;
            let inner = self.0.take().ok_or(NucleationError::AlreadyConsumed)?;
            let region =
                DefinitionRegion::from_positions(&super::positions_from_flat(region_positions));
            match inner.add_input_from_region(name, io_type.0.clone(), layout.0.clone(), region) {
                Ok(b) => {
                    self.0 = Some(b);
                    Ok(())
                }
                Err(_) => Err(NucleationError::InvalidArgument),
            }
        }

        /// Add an input from a region (flat positions) with automatic layout
        /// inference.
        pub fn add_input_from_region_auto(
            &mut self,
            name: &DiplomatStr,
            io_type: &IoType,
            region_positions: &[i32],
        ) -> Result<(), NucleationError> {
            let name = std::str::from_utf8(name).map_err(|_| NucleationError::InvalidArgument)?;
            let inner = self.0.take().ok_or(NucleationError::AlreadyConsumed)?;
            let region =
                DefinitionRegion::from_positions(&super::positions_from_flat(region_positions));
            match inner.add_input_from_region_auto(name, io_type.0.clone(), region) {
                Ok(b) => {
                    self.0 = Some(b);
                    Ok(())
                }
                Err(_) => Err(NucleationError::InvalidArgument),
            }
        }

        /// Add an output from a region given as flat block positions.
        pub fn add_output_from_region(
            &mut self,
            name: &DiplomatStr,
            io_type: &IoType,
            layout: &LayoutFunction,
            region_positions: &[i32],
        ) -> Result<(), NucleationError> {
            let name = std::str::from_utf8(name).map_err(|_| NucleationError::InvalidArgument)?;
            let inner = self.0.take().ok_or(NucleationError::AlreadyConsumed)?;
            let region =
                DefinitionRegion::from_positions(&super::positions_from_flat(region_positions));
            match inner.add_output_from_region(name, io_type.0.clone(), layout.0.clone(), region) {
                Ok(b) => {
                    self.0 = Some(b);
                    Ok(())
                }
                Err(_) => Err(NucleationError::InvalidArgument),
            }
        }

        /// Add an output from a region (flat positions) with automatic layout
        /// inference.
        pub fn add_output_from_region_auto(
            &mut self,
            name: &DiplomatStr,
            io_type: &IoType,
            region_positions: &[i32],
        ) -> Result<(), NucleationError> {
            let name = std::str::from_utf8(name).map_err(|_| NucleationError::InvalidArgument)?;
            let inner = self.0.take().ok_or(NucleationError::AlreadyConsumed)?;
            let region =
                DefinitionRegion::from_positions(&super::positions_from_flat(region_positions));
            match inner.add_output_from_region_auto(name, io_type.0.clone(), region) {
                Ok(b) => {
                    self.0 = Some(b);
                    Ok(())
                }
                Err(_) => Err(NucleationError::InvalidArgument),
            }
        }

        /// Build the [`IoLayout`]. Consumes the builder (a second call returns
        /// `AlreadyConsumed`).
        pub fn build(&mut self) -> Result<Box<IoLayout>, NucleationError> {
            let inner = self.0.take().ok_or(NucleationError::AlreadyConsumed)?;
            Ok(Box::new(IoLayout(inner.build())))
        }
    }

    /// An immutable IO layout. Wraps
    /// [`crate::simulation::typed_executor::IoLayout`].
    #[diplomat::opaque]
    pub struct IoLayout(pub(crate) InnerIoLayout);

    impl IoLayout {
        /// Input names as a JSON array string.
        pub fn input_names_json(&self, out: &mut DiplomatWrite) {
            let names: Vec<&str> = self.0.input_names();
            let json = serde_json::to_string(&names).unwrap_or_else(|_| "[]".to_string());
            let _ = write!(out, "{}", json);
        }

        /// Output names as a JSON array string.
        pub fn output_names_json(&self, out: &mut DiplomatWrite) {
            let names: Vec<&str> = self.0.output_names();
            let json = serde_json::to_string(&names).unwrap_or_else(|_| "[]".to_string());
            let _ = write!(out, "{}", json);
        }
    }

    // ─── CircuitBuilder ──────────────────────────────────────────────────────

    /// High-level circuit builder. `build`/`build_validated` consume it
    /// (PORTING rule 11). Regions are given as flat `[x,y,z,...]` positions
    /// (see module notes).
    #[diplomat::opaque_mut]
    pub struct CircuitBuilder(pub(crate) Option<InnerCircuitBuilder>);

    impl CircuitBuilder {
        /// Create a builder for a schematic (cloned; no IO defined yet).
        pub fn create(schematic: &Schematic) -> Box<CircuitBuilder> {
            Box::new(CircuitBuilder(Some(InnerCircuitBuilder::new(
                schematic.0.clone(),
            ))))
        }

        /// Create a builder pre-populated from Insign annotations.
        pub fn from_insign(schematic: &Schematic) -> Result<Box<CircuitBuilder>, NucleationError> {
            InnerCircuitBuilder::from_insign(schematic.0.clone())
                .map(|b| Box::new(CircuitBuilder(Some(b))))
                .map_err(|_| NucleationError::Simulation)
        }

        /// Add an input with full control.
        pub fn with_input(
            &mut self,
            name: &DiplomatStr,
            io_type: &IoType,
            layout: &LayoutFunction,
            region_positions: &[i32],
        ) -> Result<(), NucleationError> {
            let name = std::str::from_utf8(name).map_err(|_| NucleationError::InvalidArgument)?;
            let inner = self.0.take().ok_or(NucleationError::AlreadyConsumed)?;
            let region =
                DefinitionRegion::from_positions(&super::positions_from_flat(region_positions));
            match inner.with_input(name, io_type.0.clone(), layout.0.clone(), region) {
                Ok(b) => {
                    self.0 = Some(b);
                    Ok(())
                }
                Err(_) => Err(NucleationError::InvalidArgument),
            }
        }

        /// Add an input with full control and a custom sort strategy.
        pub fn with_input_sorted(
            &mut self,
            name: &DiplomatStr,
            io_type: &IoType,
            layout: &LayoutFunction,
            region_positions: &[i32],
            sort: &SortStrategy,
        ) -> Result<(), NucleationError> {
            let name = std::str::from_utf8(name).map_err(|_| NucleationError::InvalidArgument)?;
            let inner = self.0.take().ok_or(NucleationError::AlreadyConsumed)?;
            let region =
                DefinitionRegion::from_positions(&super::positions_from_flat(region_positions));
            match inner.with_input_sorted(
                name,
                io_type.0.clone(),
                layout.0.clone(),
                region,
                sort.0.clone(),
            ) {
                Ok(b) => {
                    self.0 = Some(b);
                    Ok(())
                }
                Err(_) => Err(NucleationError::InvalidArgument),
            }
        }

        /// Add an input with automatic layout inference.
        pub fn with_input_auto(
            &mut self,
            name: &DiplomatStr,
            io_type: &IoType,
            region_positions: &[i32],
        ) -> Result<(), NucleationError> {
            let name = std::str::from_utf8(name).map_err(|_| NucleationError::InvalidArgument)?;
            let inner = self.0.take().ok_or(NucleationError::AlreadyConsumed)?;
            let region =
                DefinitionRegion::from_positions(&super::positions_from_flat(region_positions));
            match inner.with_input_auto(name, io_type.0.clone(), region) {
                Ok(b) => {
                    self.0 = Some(b);
                    Ok(())
                }
                Err(_) => Err(NucleationError::InvalidArgument),
            }
        }

        /// Add an input with automatic layout inference and a custom sort.
        pub fn with_input_auto_sorted(
            &mut self,
            name: &DiplomatStr,
            io_type: &IoType,
            region_positions: &[i32],
            sort: &SortStrategy,
        ) -> Result<(), NucleationError> {
            let name = std::str::from_utf8(name).map_err(|_| NucleationError::InvalidArgument)?;
            let inner = self.0.take().ok_or(NucleationError::AlreadyConsumed)?;
            let region =
                DefinitionRegion::from_positions(&super::positions_from_flat(region_positions));
            match inner.with_input_auto_sorted(name, io_type.0.clone(), region, sort.0.clone()) {
                Ok(b) => {
                    self.0 = Some(b);
                    Ok(())
                }
                Err(_) => Err(NucleationError::InvalidArgument),
            }
        }

        /// Add an output with full control.
        pub fn with_output(
            &mut self,
            name: &DiplomatStr,
            io_type: &IoType,
            layout: &LayoutFunction,
            region_positions: &[i32],
        ) -> Result<(), NucleationError> {
            let name = std::str::from_utf8(name).map_err(|_| NucleationError::InvalidArgument)?;
            let inner = self.0.take().ok_or(NucleationError::AlreadyConsumed)?;
            let region =
                DefinitionRegion::from_positions(&super::positions_from_flat(region_positions));
            match inner.with_output(name, io_type.0.clone(), layout.0.clone(), region) {
                Ok(b) => {
                    self.0 = Some(b);
                    Ok(())
                }
                Err(_) => Err(NucleationError::InvalidArgument),
            }
        }

        /// Add an output with full control and a custom sort strategy.
        pub fn with_output_sorted(
            &mut self,
            name: &DiplomatStr,
            io_type: &IoType,
            layout: &LayoutFunction,
            region_positions: &[i32],
            sort: &SortStrategy,
        ) -> Result<(), NucleationError> {
            let name = std::str::from_utf8(name).map_err(|_| NucleationError::InvalidArgument)?;
            let inner = self.0.take().ok_or(NucleationError::AlreadyConsumed)?;
            let region =
                DefinitionRegion::from_positions(&super::positions_from_flat(region_positions));
            match inner.with_output_sorted(
                name,
                io_type.0.clone(),
                layout.0.clone(),
                region,
                sort.0.clone(),
            ) {
                Ok(b) => {
                    self.0 = Some(b);
                    Ok(())
                }
                Err(_) => Err(NucleationError::InvalidArgument),
            }
        }

        /// Add an output with automatic layout inference.
        pub fn with_output_auto(
            &mut self,
            name: &DiplomatStr,
            io_type: &IoType,
            region_positions: &[i32],
        ) -> Result<(), NucleationError> {
            let name = std::str::from_utf8(name).map_err(|_| NucleationError::InvalidArgument)?;
            let inner = self.0.take().ok_or(NucleationError::AlreadyConsumed)?;
            let region =
                DefinitionRegion::from_positions(&super::positions_from_flat(region_positions));
            match inner.with_output_auto(name, io_type.0.clone(), region) {
                Ok(b) => {
                    self.0 = Some(b);
                    Ok(())
                }
                Err(_) => Err(NucleationError::InvalidArgument),
            }
        }

        /// Add an output with automatic layout inference and a custom sort.
        pub fn with_output_auto_sorted(
            &mut self,
            name: &DiplomatStr,
            io_type: &IoType,
            region_positions: &[i32],
            sort: &SortStrategy,
        ) -> Result<(), NucleationError> {
            let name = std::str::from_utf8(name).map_err(|_| NucleationError::InvalidArgument)?;
            let inner = self.0.take().ok_or(NucleationError::AlreadyConsumed)?;
            let region =
                DefinitionRegion::from_positions(&super::positions_from_flat(region_positions));
            match inner.with_output_auto_sorted(name, io_type.0.clone(), region, sort.0.clone()) {
                Ok(b) => {
                    self.0 = Some(b);
                    Ok(())
                }
                Err(_) => Err(NucleationError::InvalidArgument),
            }
        }

        /// Set simulation options.
        pub fn with_options(
            &mut self,
            optimize: bool,
            io_only: bool,
        ) -> Result<(), NucleationError> {
            let inner = self.0.take().ok_or(NucleationError::AlreadyConsumed)?;
            let options = SimulationOptions {
                optimize,
                io_only,
                custom_io: Vec::new(),
            };
            self.0 = Some(inner.with_options(options));
            Ok(())
        }

        /// Set the state mode ("stateless" | "stateful" | "manual").
        pub fn with_state_mode(&mut self, mode: &DiplomatStr) -> Result<(), NucleationError> {
            let mode = std::str::from_utf8(mode).map_err(|_| NucleationError::InvalidArgument)?;
            let state_mode =
                super::parse_state_mode(mode).ok_or(NucleationError::InvalidArgument)?;
            let inner = self.0.take().ok_or(NucleationError::AlreadyConsumed)?;
            self.0 = Some(inner.with_state_mode(state_mode));
            Ok(())
        }

        /// Validate the configuration without consuming the builder.
        pub fn validate(&self) -> Result<(), NucleationError> {
            match &self.0 {
                Some(inner) => inner
                    .validate()
                    .map(|_| ())
                    .map_err(|_| NucleationError::Simulation),
                None => Err(NucleationError::AlreadyConsumed),
            }
        }

        /// Build the executor. Consumes the builder.
        pub fn build(&mut self) -> Result<Box<TypedCircuitExecutor>, NucleationError> {
            let inner = self.0.take().ok_or(NucleationError::AlreadyConsumed)?;
            inner
                .build()
                .map(|e| Box::new(TypedCircuitExecutor(e)))
                .map_err(|_| NucleationError::Simulation)
        }

        /// Build the executor with validation. Consumes the builder.
        pub fn build_validated(&mut self) -> Result<Box<TypedCircuitExecutor>, NucleationError> {
            let inner = self.0.take().ok_or(NucleationError::AlreadyConsumed)?;
            inner
                .build_validated()
                .map(|e| Box::new(TypedCircuitExecutor(e)))
                .map_err(|_| NucleationError::Simulation)
        }

        /// Number of inputs defined so far (0 if the builder was consumed).
        pub fn input_count(&self) -> u32 {
            match &self.0 {
                Some(inner) => inner.input_count() as u32,
                None => 0,
            }
        }

        /// Number of outputs defined so far (0 if the builder was consumed).
        pub fn output_count(&self) -> u32 {
            match &self.0 {
                Some(inner) => inner.output_count() as u32,
                None => 0,
            }
        }

        /// Input names as a JSON array string.
        pub fn input_names_json(&self, out: &mut DiplomatWrite) -> Result<(), NucleationError> {
            let inner = self.0.as_ref().ok_or(NucleationError::AlreadyConsumed)?;
            let names: Vec<&str> = inner.input_names();
            let json = serde_json::to_string(&names).unwrap_or_else(|_| "[]".to_string());
            let _ = write!(out, "{}", json);
            Ok(())
        }

        /// Output names as a JSON array string.
        pub fn output_names_json(&self, out: &mut DiplomatWrite) -> Result<(), NucleationError> {
            let inner = self.0.as_ref().ok_or(NucleationError::AlreadyConsumed)?;
            let names: Vec<&str> = inner.output_names();
            let json = serde_json::to_string(&names).unwrap_or_else(|_| "[]".to_string());
            let _ = write!(out, "{}", json);
            Ok(())
        }
    }

    // ─── TypedCircuitExecutor ────────────────────────────────────────────────

    /// A typed circuit executor. Wraps
    /// [`crate::simulation::typed_executor::TypedCircuitExecutor`].
    #[diplomat::opaque_mut]
    pub struct TypedCircuitExecutor(pub(crate) InnerTypedCircuitExecutor);

    impl TypedCircuitExecutor {
        /// Create from a world and layout. Builds a fresh world from the
        /// world's schematic (matches the old ABI, which cloned internally).
        pub fn from_layout(
            world: &MchprsWorld,
            layout: &IoLayout,
        ) -> Result<Box<TypedCircuitExecutor>, NucleationError> {
            let schematic = world.0.get_schematic().clone();
            let new_world = crate::simulation::MchprsWorld::new(schematic)
                .map_err(|_| NucleationError::Simulation)?;
            Ok(Box::new(TypedCircuitExecutor(
                InnerTypedCircuitExecutor::from_layout(new_world, layout.0.clone()),
            )))
        }

        /// Create from a world and layout with simulation options.
        pub fn from_layout_with_options(
            world: &MchprsWorld,
            layout: &IoLayout,
            optimize: bool,
            io_only: bool,
        ) -> Result<Box<TypedCircuitExecutor>, NucleationError> {
            let schematic = world.0.get_schematic().clone();
            let options = SimulationOptions {
                optimize,
                io_only,
                custom_io: Vec::new(),
            };
            let new_world =
                crate::simulation::MchprsWorld::with_options(schematic, options.clone())
                    .map_err(|_| NucleationError::Simulation)?;
            Ok(Box::new(TypedCircuitExecutor(
                InnerTypedCircuitExecutor::from_layout_with_options(
                    new_world,
                    layout.0.clone(),
                    options,
                ),
            )))
        }

        /// Create from Insign annotations in a schematic.
        pub fn from_insign(
            schematic: &Schematic,
        ) -> Result<Box<TypedCircuitExecutor>, NucleationError> {
            crate::simulation::circuit_builder::create_circuit_from_insign(&schematic.0)
                .map(|e| Box::new(TypedCircuitExecutor(e)))
                .map_err(|_| NucleationError::Simulation)
        }

        /// Create from Insign annotations with options.
        pub fn from_insign_with_options(
            schematic: &Schematic,
            optimize: bool,
            io_only: bool,
        ) -> Result<Box<TypedCircuitExecutor>, NucleationError> {
            let options = SimulationOptions {
                optimize,
                io_only,
                custom_io: Vec::new(),
            };
            crate::simulation::circuit_builder::create_circuit_from_insign_with_options(
                &schematic.0,
                options,
            )
            .map(|e| Box::new(TypedCircuitExecutor(e)))
            .map_err(|_| NucleationError::Simulation)
        }

        /// Set the state mode ("stateless" | "stateful" | "manual").
        pub fn set_state_mode(&mut self, mode: &DiplomatStr) -> Result<(), NucleationError> {
            let mode = std::str::from_utf8(mode).map_err(|_| NucleationError::InvalidArgument)?;
            let state_mode =
                super::parse_state_mode(mode).ok_or(NucleationError::InvalidArgument)?;
            self.0.set_state_mode(state_mode);
            Ok(())
        }

        /// Reset the executor to its initial state.
        pub fn reset(&mut self) -> Result<(), NucleationError> {
            self.0.reset().map_err(|_| NucleationError::Simulation)
        }

        /// Advance the simulation by `ticks` ticks.
        pub fn tick(&mut self, ticks: u32) {
            self.0.tick(ticks);
        }

        /// Flush pending changes.
        pub fn flush(&mut self) {
            self.0.flush();
        }

        /// Set a single input value.
        pub fn set_input(
            &mut self,
            name: &DiplomatStr,
            value: &Value,
        ) -> Result<(), NucleationError> {
            let name = std::str::from_utf8(name).map_err(|_| NucleationError::InvalidArgument)?;
            self.0
                .set_input(name, &value.0)
                .map_err(|_| NucleationError::Simulation)
        }

        /// Read a single output value.
        pub fn read_output(&mut self, name: &DiplomatStr) -> Result<Box<Value>, NucleationError> {
            let name = std::str::from_utf8(name).map_err(|_| NucleationError::InvalidArgument)?;
            self.0
                .read_output(name)
                .map(|v| Box::new(Value(v)))
                .map_err(|_| NucleationError::Simulation)
        }

        /// Execute the circuit. `inputs_json` is a JSON object like
        /// `{"input_name": {"type": "u32", "value": 42}}`; writes a JSON
        /// object with `outputs`, `ticks_elapsed` and `condition_met`.
        pub fn execute(
            &mut self,
            inputs_json: &DiplomatStr,
            mode: &ExecutionMode,
            out: &mut DiplomatWrite,
        ) -> Result<(), NucleationError> {
            let json =
                std::str::from_utf8(inputs_json).map_err(|_| NucleationError::InvalidArgument)?;
            let inputs =
                super::parse_inputs_json(json).map_err(|_| NucleationError::InvalidArgument)?;
            let result = self
                .0
                .execute(inputs, mode.0.clone())
                .map_err(|_| NucleationError::Simulation)?;
            let _ = write!(out, "{}", super::serialize_execution_result(&result));
            Ok(())
        }

        /// Input names as a JSON array string.
        pub fn input_names_json(&self, out: &mut DiplomatWrite) {
            let names: Vec<&str> = self.0.input_names();
            let json = serde_json::to_string(&names).unwrap_or_else(|_| "[]".to_string());
            let _ = write!(out, "{}", json);
        }

        /// Output names as a JSON array string.
        pub fn output_names_json(&self, out: &mut DiplomatWrite) {
            let names: Vec<&str> = self.0.output_names();
            let json = serde_json::to_string(&names).unwrap_or_else(|_| "[]".to_string());
            let _ = write!(out, "{}", json);
        }

        /// Layout info as a JSON object string
        /// (old ABI: `typed_executor_get_layout_info`).
        pub fn layout_info_json(&self, out: &mut DiplomatWrite) {
            let info = self.0.get_layout_info();
            let _ = write!(out, "{}", super::serialize_layout_info(&info));
        }

        /// Sync the simulation state and return the schematic (cloned).
        pub fn sync_to_schematic(&mut self) -> Box<Schematic> {
            Box::new(Schematic(self.0.sync_and_get_schematic().clone()))
        }
    }

    // ─── RedstoneGraph ───────────────────────────────────────────────────────

    /// An extracted redstone logic graph. Wraps
    /// [`crate::simulation::graph::RedstoneGraph`].
    #[diplomat::opaque]
    pub struct RedstoneGraph(pub(crate) crate::simulation::graph::RedstoneGraph);

    impl RedstoneGraph {
        /// Number of nodes in the graph.
        pub fn node_count(&self) -> u32 {
            self.0.node_count() as u32
        }

        /// Total number of directed edges in the graph.
        pub fn edge_count(&self) -> u32 {
            self.0.edge_count() as u32
        }

        /// The nodes as a JSON array string.
        pub fn nodes_json(&self, out: &mut DiplomatWrite) -> Result<(), NucleationError> {
            let json = self
                .0
                .nodes_json()
                .map_err(|_| NucleationError::Serialize)?;
            let _ = write!(out, "{}", json);
            Ok(())
        }

        /// The directed edges as a JSON array string.
        pub fn edges_json(&self, out: &mut DiplomatWrite) -> Result<(), NucleationError> {
            let json = self
                .0
                .edges_json()
                .map_err(|_| NucleationError::Serialize)?;
            let _ = write!(out, "{}", json);
            Ok(())
        }

        /// Computed graph features as a JSON object string.
        pub fn features_json(&self, out: &mut DiplomatWrite) -> Result<(), NucleationError> {
            let json = self
                .0
                .features()
                .to_json()
                .map_err(|_| NucleationError::Serialize)?;
            let _ = write!(out, "{}", json);
            Ok(())
        }

        /// Fingerprint (hex string) for `preset` ("structural" | "functional" |
        /// "exact"; empty defaults to "structural").
        pub fn fingerprint(
            &self,
            preset: &DiplomatStr,
            out: &mut DiplomatWrite,
        ) -> Result<(), NucleationError> {
            let preset =
                std::str::from_utf8(preset).map_err(|_| NucleationError::InvalidArgument)?;
            let preset = if preset.is_empty() {
                "structural"
            } else {
                preset
            };
            let spec = crate::simulation::fingerprint::GraphFingerprintSpec::from_preset(preset)
                .ok_or(NucleationError::InvalidArgument)?;
            let _ = write!(out, "{}", self.0.fingerprint(&spec).to_hex());
            Ok(())
        }

        /// Serialize the whole graph to JSON.
        pub fn to_json(&self, out: &mut DiplomatWrite) -> Result<(), NucleationError> {
            let json = self.0.to_json().map_err(|_| NucleationError::Serialize)?;
            let _ = write!(out, "{}", json);
            Ok(())
        }

        /// Deserialize a graph from a JSON string.
        pub fn from_json(json: &DiplomatStr) -> Result<Box<RedstoneGraph>, NucleationError> {
            let json = std::str::from_utf8(json).map_err(|_| NucleationError::InvalidArgument)?;
            crate::simulation::graph::RedstoneGraph::from_json(json)
                .map(|g| Box::new(RedstoneGraph(g)))
                .map_err(|_| NucleationError::Parse)
        }
    }
}