Dual Execution Domain en

中文 | English

Dual Execution Domain

Maintained version: v0.51.2 ｜ Last updated: 2026-07-06

Power systems have rigid real-time requirements — protection actions must complete in milliseconds, and switching commands must be issued within deterministic deadlines. A general-purpose OS kernel cannot provide hard real-time guarantees, while a pure real-time system cannot host AI inference and Agent orchestration. EnerOS's answer is the dual execution domain.

See ADR-0015 and README §Real-time Dual Execution Domain.

---

Domain Comparison

Dimension	General Domain	Real-Time Domain
Kernel mode	Standard kernel	Real-time extended kernel
Scheduling	Fair scheduling	SCHED_FIFO priority preemption
Typical tasks	Agent orchestration, AI inference, powerflow	Protection, switching, fault isolation, frequency regulation
Response latency	Seconds ~ minutes	Microseconds ~ milliseconds (P99 < 1ms)
Memory	Heap allocation allowed	Heap allocation banned (NoAlloc)
Locks	Mutex/RwLock allowed	Banned (clippy::disallowed_types)
IPC	Any	Lockfree SPSC channel

---

Core Design Principles

1. Safety domain cannot be blocked by general domain — RT tasks have the highest priority; general domain must not affect RT determinism
2. Unidirectional trust — RT domain can read general domain decision commands; general domain cannot directly interfere with RT scheduling
3. Cross-domain via SafetyGateway — all general → RT commands must pass through gateway constraint validation + priority arbitration
4. Fail-safe degradation — on general domain failure, RT domain automatically switches to local protection logic; grid safety does not depend on AI

---

RT Type-Level Guarantees (v0.49.0, v0.50.0 true seal)

RT domain safety rules are upgraded from "documentation conventions" to compile-time + runtime dual guarantees:

1. Validated<Command> newtype

SafetyGateway is type-level unbypassable:

// Compile-time guarantee: execute_validated only accepts Validated<Command>
pub fn execute_validated(&self, cmd: &Validated<Command>) -> Result<()>;

// Validated::new is pub(crate), external crates cannot construct it directly
// Must go through gateway.validate(&cmd)? to get Validated<Command>

External crates calling Validated::new directly trigger compile error error[E0624]: associated function 'new' is private. trybuild compile_fail/bypass_safety_gateway.rs locks the error pattern.

2. clippy::disallowed_types RT lock ban

crates/eneros-gateway/clippy.toml declares Mutex/RwLock as RT-disallowed at crate level; the rt.rs module enforces via #![cfg_attr(feature = "rt_check", deny)].

CI rt-check job enforces validation with --features rt_check on every commit.

3. NoAlloc marker trait + AllocTracker

eneros-perf/src/no_alloc.rs:

• NoAlloc marker trait (v0.50.0 moved to eneros-core::no_alloc)
• AllocTracker GlobalAlloc wrapper
• RT threads panic on heap allocation via RtThreadGuard
• Enabled via #[cfg(feature = "rt_check")]

4. lockfree by default

SafetyGateway::new() enables lockfree by default; v0.49.0 BREAKING: removed with_lockfree_state(), added with_locking_state() as opt-out.

5. WCET framework

pub struct RtTask {
    command: Validated<Command>,
    budget: WcetBudget,
}

// execute_with_wcet budget constraint
// - Over budget: warning
// - 2× over budget: error + trigger watchdog fallback

WCET violations written to audit: AuditAction::WcetViolation (v0.50.0).

6. RepositoryAuditSink HMAC chain (v0.51.0)

AuditSinkFactory::from_config() supports "memory" / "repository" sinks. RepositoryAuditSink writes asynchronously to AuditRepository via tokio::spawn; the HMAC chain is maintained by AuditRepository.

---

Real-Time Infrastructure

Technology	Purpose
SCHED_FIFO	Priority preemption scheduling
isolcpus	CPU isolation, avoiding preemption by general tasks
mlockall	Memory locking, banning paging
Lockfree SPSC IPC	Cross-domain communication without lock contention
Hardware watchdog (/dev/watchdog)	Timeout reset
huge pages	Reduce TLB misses

eneros-os::rt module encapsulates the above; HardwareWatchdog (v0.51.0 connected to actual /dev/watchdog).

---

CI Enforcement

.github/workflows/ci.yml rt-check job:

rt-check:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - name: RT clippy + test
      run: |
        cargo clippy --workspace --features rt_check -- -D warnings
        cargo test --workspace --features rt_check

RT type-level rules are enforced on every commit.

---

Next Steps

• Safety Gateway — Full Validated<Command> workflow
• ADR-0015 — Full RT type-level decision record
• README §Real-time Dual Execution Domain