vyre-conform 0.1.0

//! Engine-as-op composition bridge.
//!
//! Stage 1 does not mutate existing `EngineSpec` consumers. It adapts each
//! registered engine into the same composable surface used by operation specs
//! and rejects unsafe pairs before any CPU or GPU dispatch can happen.

#[cfg(test)]
pub use catalog::{
    deferred_engine_specs, engine_op_specs, migration_report, DeferredEngine, EngineMigrationReport,
};
pub use harness::{run_pairwise_bridge_harness, PairOutcome, PairStatus};
pub use op::{
    can_compose, compose_cpu, ComposableOp, CompositionError, EngineMigrationStage, EngineOpSpec,
    WireFormat,
};

mod op {
    /// Unified composable operation surface for L1/L2 ops and L3 engines.
    use crate::spec::types::conform::CpuReferenceFn;
    use crate::spec::types::OpSpec;
    use crate::spec::types::{DataType, OpSignature};

    /// Semantic wire format carried by an operation output or accepted as input.
    ///
    /// `DataType::Bytes` is intentionally too broad for engine composition: a DFA
    /// match stream and a serialized eval request are both byte buffers, but feeding
    /// one into the other corrupts semantics. This tag is the minimum bridge needed
    /// until engine request and response schemas become typed u32 records.
    #[derive(Clone, Copy, Debug, Eq, PartialEq)]
    pub enum WireFormat {
        /// A single fixed-width scalar or vector value.
        Scalar,
        /// An unstructured byte buffer from an ordinary op.
        Bytes,
        /// Serialized DFA engine request.
        DfaRequest,
        /// DFA match triples: pattern_id, start, end as u32 words.
        DfaMatches,
        /// Serialized bytecode eval engine request.
        EvalRequest,
        /// Eval fired flags widened to u32 words.
        EvalFiredWords,
        /// Serialized scatter engine request.
        ScatterRequest,
        /// Scatter rule bitmap as u32 words.
        RuleBitmapWords,
    }

    /// Migration state for an engine adapted onto the composable op surface.
    #[derive(Clone, Copy, Debug, Eq, PartialEq)]
    pub enum EngineMigrationStage {
        /// The engine has an op-like CPU reference and type signature, but its
        /// public wire boundary is not yet a valid downstream engine input.
        BridgeOnly {
            /// Actionable reason composition must be rejected.
            reason: &'static str,
        },
        /// The engine can participate in direct engine-op composition.
        Composable,
    }

    /// Unified trait for anything that can participate in an op chain.
    ///
    /// Existing primitive specs implement this directly. Engines implement it
    /// through [`EngineOpSpec`] so their old `EngineSpec` API remains stable.
    pub trait ComposableOp {
        /// Stable operation or engine id.
        fn id(&self) -> &str;

        /// Type-level signature checked before composition.
        fn signature(&self) -> &OpSignature;

        /// Semantic input wire format.
        fn input_wire_format(&self) -> WireFormat;

        /// Semantic output wire format.
        fn output_wire_format(&self) -> WireFormat;

        /// CPU reference that defines this op's behavior.
        fn cpu_reference(&self) -> CpuReferenceFn;

        /// Engine migration state.
        fn migration_stage(&self) -> EngineMigrationStage {
            EngineMigrationStage::Composable
        }
    }

    impl ComposableOp for OpSpec {
        fn id(&self) -> &str {
            self.id
        }

        fn signature(&self) -> &OpSignature {
            &self.signature
        }

        fn input_wire_format(&self) -> WireFormat {
            self.signature
                .inputs
                .first()
                .map(wire_format_for_data_type)
                .unwrap_or(WireFormat::Bytes)
        }

        fn output_wire_format(&self) -> WireFormat {
            wire_format_for_data_type(&self.signature.output)
        }

        fn cpu_reference(&self) -> CpuReferenceFn {
            self.cpu_fn
        }
    }

    /// Engine adapted as a first-class composable op.
    #[derive(Clone)]
    pub struct EngineOpSpec {
        id: &'static str,
        description: &'static str,
        signature: OpSignature,
        input_wire_format: WireFormat,
        output_wire_format: WireFormat,
        cpu_reference: CpuReferenceFn,
        migration_stage: EngineMigrationStage,
    }

    impl EngineOpSpec {
        /// Construct an engine-op adapter from explicit metadata.
        #[inline]
        pub fn new(
            id: &'static str,
            description: &'static str,
            signature: OpSignature,
            wire_formats: (WireFormat, WireFormat),
            cpu_reference: CpuReferenceFn,
            migration_stage: EngineMigrationStage,
        ) -> Self {
            Self {
                id,
                description,
                signature,
                input_wire_format: wire_formats.0,
                output_wire_format: wire_formats.1,
                cpu_reference,
                migration_stage,
            }
        }

        /// Human-readable engine description.
        #[inline]
        pub fn description(&self) -> &'static str {
            self.description
        }

        /// Stable engine id with static lifetime.
        #[inline]
        pub fn stable_id(&self) -> &'static str {
            self.id
        }
    }

    impl ComposableOp for EngineOpSpec {
        fn id(&self) -> &str {
            self.id
        }

        fn signature(&self) -> &OpSignature {
            &self.signature
        }

        fn input_wire_format(&self) -> WireFormat {
            self.input_wire_format
        }

        fn output_wire_format(&self) -> WireFormat {
            self.output_wire_format
        }

        fn cpu_reference(&self) -> CpuReferenceFn {
            self.cpu_reference
        }

        fn migration_stage(&self) -> EngineMigrationStage {
            self.migration_stage
        }
    }

    /// Composition validation failure.
    #[derive(Clone, Debug, Eq, PartialEq)]
    pub enum CompositionError {
        /// An engine is explicitly marked bridge-only.
        StageBlocked {
            /// Engine id that blocked direct composition.
            engine_id: String,
            /// Actionable reason.
            reason: &'static str,
        },
        /// The outer op has no declared input slot.
        MissingInput {
            /// Outer operation id.
            op_id: String,
        },
        /// Type signatures do not align.
        TypeMismatch {
            /// First operation id.
            first_id: String,
            /// First output type.
            first_output: DataType,
            /// Second operation id.
            second_id: String,
            /// Second first input type.
            second_input: DataType,
        },
        /// Byte-level data types match, but their semantic wire formats do not.
        WireMismatch {
            /// First operation id.
            first_id: String,
            /// First output wire format.
            first_output: WireFormat,
            /// Second operation id.
            second_id: String,
            /// Second input wire format.
            second_input: WireFormat,
        },
        /// CPU references produced different bytes for identical composed input.
        CpuNondeterministic {
            /// First operation id.
            first_id: String,
            /// Second operation id.
            second_id: String,
        },
    }

    impl std::fmt::Display for CompositionError {
        fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
            match self {
                Self::StageBlocked { engine_id, reason } => {
                    write!(f, "{engine_id} is bridge-only. Fix: {reason}")
                }
                Self::MissingInput { op_id } => {
                    write!(
                        f,
                        "{op_id} has no input slot. Fix: declare an input type before composing"
                    )
                }
                Self::TypeMismatch {
                    first_id,
                    first_output,
                    second_id,
                    second_input,
                } => write!(
                    f,
                    "{first_id} outputs {first_output}, but {second_id} accepts {second_input}. \
                 Fix: insert a typed adapter op or change one signature"
                ),
                Self::WireMismatch {
                    first_id,
                    first_output,
                    second_id,
                    second_input,
                } => write!(
                f,
                "{first_id} outputs {first_output:?}, but {second_id} accepts {second_input:?}. \
                 Fix: compose only engines with the same typed wire schema"
            ),
                Self::CpuNondeterministic {
                    first_id,
                    second_id,
                } => write!(
                    f,
                    "{first_id} then {second_id} produced nondeterministic CPU output. \
                 Fix: make both CPU references pure and deterministic"
                ),
            }
        }
    }

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

    /// Check whether two composable specs can be chained.
    #[inline]
    pub fn can_compose<A, B>(first: &A, second: &B) -> Result<(), CompositionError>
    where
        A: ComposableOp,
        B: ComposableOp,
    {
        ensure_composable_stage(first)?;
        ensure_composable_stage(second)?;
        let Some(second_input) = second.signature().inputs.first() else {
            return Err(CompositionError::MissingInput {
                op_id: second.id().to_string(),
            });
        };
        if &first.signature().output != second_input {
            return Err(CompositionError::TypeMismatch {
                first_id: first.id().to_string(),
                first_output: first.signature().output.clone(),
                second_id: second.id().to_string(),
                second_input: second_input.clone(),
            });
        }
        if first.output_wire_format() != second.input_wire_format() {
            return Err(CompositionError::WireMismatch {
                first_id: first.id().to_string(),
                first_output: first.output_wire_format(),
                second_id: second.id().to_string(),
                second_input: second.input_wire_format(),
            });
        }
        Ok(())
    }

    /// Run two CPU references as a composed chain after compatibility checking.
    #[inline]
    pub fn compose_cpu<A, B>(
        first: &A,
        second: &B,
        input: &[u8],
    ) -> Result<Vec<u8>, CompositionError>
    where
        A: ComposableOp,
        B: ComposableOp,
    {
        can_compose(first, second)?;
        let first_out = (first.cpu_reference())(input);
        Ok((second.cpu_reference())(&first_out))
    }

    fn ensure_composable_stage<T: ComposableOp>(op: &T) -> Result<(), CompositionError> {
        match op.migration_stage() {
            EngineMigrationStage::Composable => Ok(()),
            EngineMigrationStage::BridgeOnly { reason } => Err(CompositionError::StageBlocked {
                engine_id: op.id().to_string(),
                reason,
            }),
        }
    }

    fn wire_format_for_data_type(data_type: &DataType) -> WireFormat {
        match data_type {
            DataType::Bytes | DataType::Array { .. } | DataType::Tensor => WireFormat::Bytes,
            DataType::U32
            | DataType::I32
            | DataType::U64
            | DataType::Vec2U32
            | DataType::Vec4U32
            | DataType::Bool
            | DataType::F16
            | DataType::BF16
            | DataType::F32
            | DataType::F64 => WireFormat::Scalar,
        }
    }
}

mod catalog {
    /// Engine-op migration catalog.
    use crate::spec::engine;
    use crate::spec::types::conform::CpuReferenceFn;
    use crate::spec::types::{DataType, OpSignature};

    use crate::enforce::enforcers::engine_composition::{
        ComposableOp, EngineMigrationStage, EngineOpSpec, WireFormat,
    };

    const DFA_BRIDGE_REASON: &str =
        "carry DFA match triples plus pattern-to-rule metadata in one typed u32 stream";
    const EVAL_BRIDGE_REASON: &str =
        "replace serialized eval requests with typed u32 request and fired-output records";
    const SCATTER_BRIDGE_REASON: &str =
        "split scatter request metadata from match triples so DFA output can feed it directly";

    /// Engine known to exist in `vyre::engine` but not yet registered as an
    /// executable conform `EngineSpec`.
    #[derive(Clone, Debug, Eq, PartialEq)]
    pub struct DeferredEngine {
        /// Stable engine id.
        pub id: &'static str,
        /// Actionable migration reason.
        pub reason: &'static str,
    }

    /// Current engine migration state.
    #[derive(Clone, Debug, Eq, PartialEq)]
    pub struct EngineMigrationReport {
        /// Engines adapted onto the op-like bridge.
        pub bridged: Vec<&'static str>,
        /// Engines fully composable with at least one other engine or op.
        pub composable: Vec<&'static str>,
        /// Engines still missing conform registration or typed wire schemas.
        pub deferred: Vec<DeferredEngine>,
    }

    /// Return all conform-registered engines as first-class op adapters.
    #[inline]
    pub fn engine_op_specs() -> Result<Vec<EngineOpSpec>, String> {
        let dfa = engine::dfa::spec();
        let eval = engine::eval::spec();
        let scatter = engine::scatter::spec();
        Ok(vec![
            EngineOpSpec::new(
                dfa.id,
                dfa.description,
                OpSignature {
                    inputs: vec![DataType::Bytes],
                    output: DataType::Array { element_size: 12 },
                },
                (WireFormat::DfaRequest, WireFormat::DfaMatches),
                required_cpu(dfa.id, dfa.cpu_fn)?,
                EngineMigrationStage::BridgeOnly {
                    reason: DFA_BRIDGE_REASON,
                },
            ),
            EngineOpSpec::new(
                eval.id,
                eval.description,
                OpSignature {
                    inputs: vec![DataType::Bytes],
                    output: DataType::Array { element_size: 4 },
                },
                (WireFormat::EvalRequest, WireFormat::EvalFiredWords),
                eval_u32_cpu,
                EngineMigrationStage::BridgeOnly {
                    reason: EVAL_BRIDGE_REASON,
                },
            ),
            EngineOpSpec::new(
                scatter.id,
                scatter.description,
                OpSignature {
                    inputs: vec![DataType::Bytes],
                    output: DataType::Array { element_size: 4 },
                },
                (WireFormat::ScatterRequest, WireFormat::RuleBitmapWords),
                required_cpu(scatter.id, scatter.cpu_fn)?,
                EngineMigrationStage::BridgeOnly {
                    reason: SCATTER_BRIDGE_REASON,
                },
            ),
        ])
    }

    /// Return engines that still need conform registration before bridge adapters
    /// can be built.
    #[inline]
    pub fn deferred_engine_specs() -> Vec<DeferredEngine> {
        vec![
            DeferredEngine {
                id: "engine.dataflow",
                reason: "add a conform EngineSpec with a deterministic u32 CPU reference",
            },
            DeferredEngine {
                id: "engine.decode",
                reason: "add a conform EngineSpec for the recursive decode pipeline",
            },
            DeferredEngine {
                id: "engine.prefix",
                reason: "promote prefix helpers from CPU-side helpers into a typed engine spec",
            },
            DeferredEngine {
                id: "engine.tokenize",
                reason: "promote tokenize helpers from host filtering into a typed engine spec",
            },
        ]
    }

    /// Build a report of migrated and deferred engines.
    #[inline]
    pub fn migration_report() -> Result<EngineMigrationReport, String> {
        let mut bridged = Vec::new();
        let mut composable = Vec::new();
        for spec in engine_op_specs()? {
            match spec.migration_stage() {
                EngineMigrationStage::Composable => composable.push(spec.stable_id()),
                EngineMigrationStage::BridgeOnly { .. } => bridged.push(spec.stable_id()),
            }
        }
        Ok(EngineMigrationReport {
            bridged,
            composable,
            deferred: deferred_engine_specs(),
        })
    }

    fn required_cpu(id: &str, cpu: Option<CpuReferenceFn>) -> Result<CpuReferenceFn, String> {
        match cpu {
            Some(cpu) => Ok(cpu),
            None => Err(format!(
                "{id} has no CPU reference. Fix: add a deterministic pure-Rust u32 reference"
            )),
        }
    }

    fn eval_u32_cpu(input: &[u8]) -> Vec<u8> {
        let raw = engine::eval::cpu_fn(input);
        if raw.len() == 4 && raw == u32::MAX.to_le_bytes() {
            return raw;
        }
        raw.into_iter()
            .flat_map(|byte| u32::from(byte).to_le_bytes())
            .collect()
    }
}

mod harness {
    /// Pairwise engine composition harness.
    use crate::enforce::enforcers::engine_composition::{
        can_compose, compose_cpu, CompositionError, EngineOpSpec,
    };

    /// Cross-product result for one engine pair.
    #[derive(Clone, Debug, Eq, PartialEq)]
    pub struct PairOutcome {
        /// First engine id.
        pub first_id: &'static str,
        /// Second engine id.
        pub second_id: &'static str,
        /// Pair verification status.
        pub status: PairStatus,
    }

    /// Verification status for one engine pair.
    #[derive(Clone, Debug, Eq, PartialEq)]
    pub enum PairStatus {
        /// The pair composed and the CPU chain was deterministic.
        Passed,
        /// The pair was rejected before dispatch with an actionable reason.
        Rejected {
            /// Compatibility error.
            reason: CompositionError,
        },
    }

    /// Run the Stage-1 pairwise bridge harness over `engines`.
    ///
    /// Compatible pairs execute their CPU chain twice and must return identical
    /// bytes. Incompatible pairs are accepted only when the compatibility checker
    /// produces a structured rejection.
    #[inline]
    pub fn run_pairwise_bridge_harness(engines: &[EngineOpSpec], input: &[u8]) -> Vec<PairOutcome> {
        let mut outcomes = Vec::new();
        for first in engines {
            for second in engines {
                let status = match can_compose(first, second) {
                    Ok(()) => deterministic_pair_status(first, second, input),
                    Err(reason) => PairStatus::Rejected { reason },
                };
                outcomes.push(PairOutcome {
                    first_id: first.stable_id(),
                    second_id: second.stable_id(),
                    status,
                });
            }
        }
        outcomes
    }

    fn deterministic_pair_status(
        first: &EngineOpSpec,
        second: &EngineOpSpec,
        input: &[u8],
    ) -> PairStatus {
        let first_run = compose_cpu(first, second, input);
        let second_run = compose_cpu(first, second, input);
        match (first_run, second_run) {
            (Ok(a), Ok(b)) if a == b => PairStatus::Passed,
            (Ok(_), Ok(_)) => PairStatus::Rejected {
                reason: CompositionError::CpuNondeterministic {
                    first_id: first.stable_id().to_string(),
                    second_id: second.stable_id().to_string(),
                },
            },
            (Err(reason), _) | (_, Err(reason)) => PairStatus::Rejected { reason },
        }
    }
}

/// Registry entry for `engine_composition` enforcement.
pub struct EngineCompositionEnforcer;

impl crate::enforce::EnforceGate for EngineCompositionEnforcer {
    fn id(&self) -> &'static str {
        "engine_composition"
    }

    fn name(&self) -> &'static str {
        "engine_composition"
    }

    fn run(&self, _ctx: &crate::enforce::EnforceCtx<'_>) -> Vec<crate::enforce::Finding> {
        let messages = match catalog::migration_report() {
            Ok(report) => report
                .deferred
                .into_iter()
                .map(|engine| {
                    format!(
                        "engine_composition({}): {}. Fix: complete the engine bridge registration.",
                        engine.id, engine.reason
                    )
                })
                .collect(),
            Err(error) => vec![error],
        };
        crate::enforce::finding_result(self.id(), messages)
    }
}

/// Auto-registered `engine_composition` enforcer.
pub const REGISTERED: EngineCompositionEnforcer = EngineCompositionEnforcer;