telltale_machine/
architecture.rs

1//! Runtime architecture contract.
2//!
3//! This module defines the canonical semantic engine and the role of each
4//! runtime surface.
5
6/// Runtime engine role classification during migration.
7#[derive(Debug, Clone, Copy, PartialEq, Eq)]
8pub enum EngineRole {
9    /// Canonical semantic owner.
10    Canonical,
11    /// Adapter/runtime surface that must not redefine semantics.
12    AdapterOnly,
13}
14
15/// Semantic ownership contract for runtime execution surfaces.
16#[derive(Debug, Clone, Copy, PartialEq, Eq)]
17pub struct EngineOwnership {
18    /// Runtime surface name.
19    pub engine: &'static str,
20    /// Canonical/adaptor role.
21    pub role: EngineRole,
22    /// Who owns instruction semantics.
23    pub instruction_semantics_owner: &'static str,
24    /// Who owns scheduler policy interpretation.
25    pub scheduler_policy_owner: &'static str,
26    /// Who owns observable trace emission semantics.
27    pub trace_semantics_owner: &'static str,
28}
29
30/// Canonical semantic owner for ProtocolMachine execution.
31pub const CANONICAL_ENGINE: &str = "ProtocolMachineKernel";
32
33/// Cross-target semantic contract.
34///
35/// Native single-threaded, native threaded, and wasm cooperative runtimes
36/// must agree on canonical ProtocolMachine observables, modulo effect-policy differences.
37pub const CROSS_TARGET_CONTRACT: &str =
38    "NativeThreaded ~= NativeSingleThreaded ~= WasmCooperative (modulo effects)";
39
40/// Equivalence surfaces checked by cross-target validation.
41pub const EQUIVALENCE_SURFACES: &[&str] = &[
42    "normalized_vm_observable_trace",
43    "normalized_scheduler_step_trace",
44    "effect_trace",
45];
46
47/// Declared runtime ownership for all ProtocolMachine execution surfaces.
48pub const ENGINE_OWNERSHIP: &[EngineOwnership] = &[
49    EngineOwnership {
50        engine: "ProtocolMachineKernel",
51        role: EngineRole::Canonical,
52        instruction_semantics_owner: "ProtocolMachineKernel + exec::*",
53        scheduler_policy_owner: "ProtocolMachineKernel + scheduler::Scheduler",
54        trace_semantics_owner: "ProtocolMachineKernel commit path",
55    },
56    EngineOwnership {
57        engine: "ProtocolMachine",
58        role: EngineRole::AdapterOnly,
59        instruction_semantics_owner: "ProtocolMachineKernel + exec::*",
60        scheduler_policy_owner: "ProtocolMachineKernel + scheduler::Scheduler",
61        trace_semantics_owner: "ProtocolMachineKernel commit path",
62    },
63    EngineOwnership {
64        engine: "ThreadedProtocolMachine",
65        role: EngineRole::AdapterOnly,
66        instruction_semantics_owner: "ProtocolMachineKernel + exec::*",
67        scheduler_policy_owner: "ProtocolMachineKernel + scheduler::Scheduler",
68        trace_semantics_owner: "ProtocolMachineKernel commit path",
69    },
70    EngineOwnership {
71        engine: "WasmCooperativeDriver",
72        role: EngineRole::AdapterOnly,
73        instruction_semantics_owner: "ProtocolMachineKernel + exec::*",
74        scheduler_policy_owner: "ProtocolMachineKernel + scheduler::Scheduler",
75        trace_semantics_owner: "ProtocolMachineKernel commit path",
76    },
77];
78
79#[cfg(test)]
80mod tests {
81    use super::{
82        EngineRole, CANONICAL_ENGINE, CROSS_TARGET_CONTRACT, ENGINE_OWNERSHIP, EQUIVALENCE_SURFACES,
83    };
84
85    #[test]
86    fn canonical_engine_is_declared_once() {
87        let canon = ENGINE_OWNERSHIP
88            .iter()
89            .filter(|o| o.role == EngineRole::Canonical)
90            .collect::<Vec<_>>();
91        assert_eq!(canon.len(), 1);
92        assert_eq!(canon[0].engine, CANONICAL_ENGINE);
93    }
94
95    #[test]
96    fn cross_target_contract_declares_required_surfaces() {
97        assert!(CROSS_TARGET_CONTRACT.contains("modulo effects"));
98        assert_eq!(EQUIVALENCE_SURFACES.len(), 3);
99        assert!(EQUIVALENCE_SURFACES.contains(&"normalized_vm_observable_trace"));
100        assert!(EQUIVALENCE_SURFACES.contains(&"normalized_scheduler_step_trace"));
101        assert!(EQUIVALENCE_SURFACES.contains(&"effect_trace"));
102    }
103}
telltale_machine/architecture.rs

telltale_machine/
architecture.rs
