orchestrator: Say platform driver, not shell, in the SM docs PR #357 renamed the effect-executing layer to platform driver; the SM doc comments still said shell. Wording only. Assisted-by: Claude:claude-fable-5 Signed-off-by: Christina Quast <christina.quast@9elements.com>
diff --git a/services/orchestrator/sm/src/lib.rs b/services/orchestrator/sm/src/lib.rs index 5a872f4..e8adb99 100644 --- a/services/orchestrator/sm/src/lib.rs +++ b/services/orchestrator/sm/src/lib.rs
@@ -4,9 +4,9 @@ //! `openprot_orchestrator_sm` — the eRoT boot-sequence state machine. //! //! This is the pure decision core: it describes side effects as [`Effect`] -//! values rather than performing them; the surrounding OpenPRoT shell carries -//! them out via a [`Platform`] impl. No concrete hardware appears here — the -//! machine is generic over an opaque [`ComponentId`]. +//! values rather than performing them; the surrounding OpenPRoT platform +//! driver carries them out via a [`Platform`] impl. No concrete hardware +//! appears here — the machine is generic over an opaque [`ComponentId`]. //! //! Three invariants define the boundary: //! 1. **Effects flow through [`Sink`]** — fresh per event, drained afterward. @@ -151,7 +151,7 @@ retry: u8, /// Set while this component has been released from reset but has not yet /// reported its boot-progress signal ([`Event::ComponentReady`] for an - /// `Active` component, [`Event::Booted`] for a `Passive` one). The shell + /// `Active` component, [`Event::Booted`] for a `Passive` one). The platform driver /// arms a per-component watchdog on release; this bit is what a later /// [`Event::Timeout`] consults to tell a real boot failure from a stale or /// spurious timeout. Orthogonal to `lifecycle`: a gated component owes no @@ -315,7 +315,7 @@ } /// Record that `id` has been released and now owes a boot-progress signal. - /// Paired with the `ReleaseReset` emitted at each release site: the shell + /// Paired with the `ReleaseReset` emitted at each release site: the platform driver /// arms its per-component boot watchdog there, and this arms ours. Also /// marks the component *live* (`released`), which a later re-entry to /// [`State::PreSupervision`] uses to quiesce it before re-verifying. @@ -877,13 +877,13 @@ } } -/// Signals that the shell could not carry out an [`Effect`]. The machine does -/// not need the shell's error detail — **every** actuation failure is treated +/// Signals that the platform driver could not carry out an [`Effect`]. The machine does +/// not need the driver's error detail — **every** actuation failure is treated /// the same, fail-closed: the driver injects [`Event::EffectFailed`] and the /// machine latches to [`State::Locked`]. This blanket policy is deliberate and /// is what lets the failure signal stay a payload-less marker; a future design /// that needs per-effect recovery must add a *new*, descriptive event rather -/// than widen this type. The shell logs the specifics on its side. +/// than widen this type. The driver logs the specifics on its side. #[derive(Clone, Copy, PartialEq, Eq, Debug)] pub struct EffectError; @@ -894,7 +894,7 @@ /// `Ok(Some(event))` feeds back what the effect produced synchronously (e.g. /// a verification verdict); the driver queues it and settles it in the same /// dispatch run. At most one event per effect. Synchronous results belong -/// here, not in a shell-side queue — one feedback path keeps ordering honest. +/// here, not in a driver-side queue — one feedback path keeps ordering honest. /// Never block in `execute`: results that arrive later (boot progress, timer /// expiry) are delivered as their own outside events via `dispatch`. /// @@ -904,7 +904,7 @@ /// /// Contract the state machine relies on: /// - **Honest, complete feedback.** The core's correctness rests entirely on -/// the event stream the shell feeds back; dropping, reordering, or +/// the event stream the driver feeds back; dropping, reordering, or /// synthesizing events silently breaks the state machine's invariants. /// - **Returned events quiesce.** Every returned event reports a result the /// reducer consumes (its retry budgets bound re-verification cycles). An @@ -919,7 +919,7 @@ /// component resume before verification and void that guarantee. /// - **A failed [`Effect::LatchLockdown`] is a hard fault.** Lockdown is the top /// of the escalation ladder — the core has nothing stronger to emit and -/// will *believe* it is `Locked`. The shell must treat that failure as +/// will *believe* it is `Locked`. The driver must treat that failure as /// terminal (halt/reset), not a recoverable error. pub trait Platform { fn execute(&mut self, effect: Effect) -> Result<Option<Event>, EffectError>;
diff --git a/services/orchestrator/sm/src/model.rs b/services/orchestrator/sm/src/model.rs index b4f5074..f921269 100644 --- a/services/orchestrator/sm/src/model.rs +++ b/services/orchestrator/sm/src/model.rs
@@ -67,7 +67,7 @@ /// Opaque recovery-region key supplied by the board at chain-build time. /// Components sharing a `RegionId` are restored together: when any region -/// member enters [`State::Recovering`], the shell resolves and restores the +/// member enters [`State::Recovering`], the platform driver resolves and restores the /// whole region. The core treats this as an equality key only and never /// inspects membership itself. #[derive(Clone, Copy, PartialEq, Eq, Debug)] @@ -182,7 +182,7 @@ /// Everything the outside world can tell the state machine. #[derive(Clone, Copy, PartialEq, Eq, Debug)] pub enum Event { - /// Power-on, carrying the shell's self-verification and provisioning result. + /// Power-on, carrying the platform driver's self-verification and provisioning result. PowerGood(PowerOnResult), /// The eRoT's signature + SVN check on this component passed. VerificationPassed(ComponentId), @@ -215,7 +215,7 @@ Restored(ComponentId), /// A required component's recovery was exhausted. RecoveryFailed, - /// The shell's boot-progress watchdog fired: `id` did not report its + /// The platform driver's boot-progress watchdog fired: `id` did not report its /// boot-progress signal ([`Event::ComponentReady`] for an `Active` /// component, [`Event::Booted`] for a `Passive` one) within its configured /// boot timeout. Treated as a verification failure — a component still @@ -236,7 +236,7 @@ /// when it executes [`Effect::ActivateUpdate`] and cancels it on /// [`Effect::CommitSvnFloor`]. CommitTimeout, - /// The shell could not carry out an emitted [`Effect`]; fail-closed, it + /// The platform driver could not carry out an emitted [`Effect`]; fail-closed, it /// latches to [`State::Locked`] from any state. Injected by the driver when /// a [`Platform::execute`](crate::Platform::execute) call fails; never /// produced by a handler.
diff --git a/services/orchestrator/sm/src/tests.rs b/services/orchestrator/sm/src/tests.rs index b574c4c..bc739fe 100644 --- a/services/orchestrator/sm/src/tests.rs +++ b/services/orchestrator/sm/src/tests.rs
@@ -1682,7 +1682,7 @@ assert!(plat.recorded.contains(&Effect::LatchLockdown)); } -/// A failed recovery actuation is fail-closed too: if the shell cannot even +/// A failed recovery actuation is fail-closed too: if the platform driver cannot even /// recover a required component, the platform latches rather /// than continuing with an unrecovered component. #[test]