Adds safety case tracing facility in copper's macros

Cargo.toml

@@ -193,6 +193,7 @@ erased-serde = { version = "0.4", default-features = false, features = [
 ] }
 serde_derive = { version = "1.0", features = ["default"] }
 pyo3 = { version = "0.28", default-features = false, features = ["macros"] }
+inventory = "0.3"
 
 # External CLI
 clap = { version = "4.5", default-features = false, features = [

api/v1/cu29-derive.txt

@@ -3,3 +3,4 @@ pub proc macro cu29_derive::bundle_resources!()
 pub proc macro cu29_derive::#[copper_runtime]
 pub proc macro cu29_derive::gen_cumsgs!()
 pub proc macro cu29_derive::resources!()
+pub proc macro cu29_derive::#[safety_case]

api/v1/cu29.txt

@@ -27,6 +27,7 @@ pub use cu29::replay
 pub use cu29::resource
 pub use cu29::resources
 pub use cu29::rx_channels
+pub use cu29::safety_case
 pub use cu29::simulation
 pub use cu29::tx_channels
 pub use cu29::units
@@ -100,6 +101,7 @@ pub use cu29::prelude::observed_encode_bytes
 pub use cu29::prelude::output_msg
 pub use cu29::prelude::record_observed_encode_bytes
 pub use cu29::prelude::rx_channels
+pub use cu29::prelude::safety_case
 pub use cu29::prelude::to_value
 pub use cu29::prelude::tx_channels
 pub use cu29::prelude::units
@@ -108,6 +110,8 @@ pub macro cu29::prelude::defmt_debug!
 pub macro cu29::prelude::defmt_error!
 pub macro cu29::prelude::defmt_info!
 pub macro cu29::prelude::defmt_warn!
+pub macro cu29::prelude::safety_check!
+pub macro cu29::prelude::safety_check_eq!
 pub mod cu29::rtsan
 pub struct cu29::rtsan::ScopedDisabler
 pub struct cu29::rtsan::ScopedSanitizeRealtime
@@ -121,3 +125,5 @@ pub macro cu29::defmt_debug!
 pub macro cu29::defmt_error!
 pub macro cu29::defmt_info!
 pub macro cu29::defmt_warn!
+pub macro cu29::safety_check!
+pub macro cu29::safety_check_eq!

core/cu29/Cargo.toml

@@ -32,6 +32,8 @@ bevy_reflect_derive = { workspace = true, optional = true }
 bincode = { workspace = true }
 serde = { workspace = true }
 serde_derive = { workspace = true }
+inventory = { workspace = true, optional = true }
+serde_json = { workspace = true, optional = true, default-features = true }
 
 # only std
 rayon = { workspace = true, optional = true }
@@ -82,3 +84,4 @@ std = [
   "cu29-value/std",
 ]
 rtsan = ["dep:rtsan-standalone", "cu29-derive/rtsan"]
+safety-ids = ["std", "dep:inventory", "dep:serde_json"]

core/cu29/src/lib.rs

@@ -29,6 +29,7 @@
 //! - `high-precision-limiter`: std-only hybrid sleep/spin loop limiter for tighter `rate_target_hz` cadence
 //! - `async-cl-io`: offload CopperList serialization/logging to a dedicated std thread
 //! - `parallel-rt`: prepare the runtime for a future multi-threaded deterministic executor
+//! - `safety-ids`: std-only safety-case metadata collection and JSON export helpers
 //!
 //! ## Concepts behind Copper
 //!
@@ -52,7 +53,7 @@
 //!
 //! ## V1 API status
 //!
-//! The V1 public contract is defined in `docs/v1-api-surface.md`. The prelude is the
+//! The V1 public contract is defined in `doc/v1-api-surface.md`. The prelude is the
 //! canonical application import surface; lower-level modules remain addressable by
 //! module path when needed, but are not implicitly part of the prelude contract.
 //!
@@ -66,7 +67,7 @@ compile_error!("feature `parallel-rt` requires `std`");
 #[cfg(not(feature = "std"))]
 extern crate alloc;
 
-pub use cu29_derive::{bundle_resources, resources};
+pub use cu29_derive::{bundle_resources, resources, safety_case};
 pub use cu29_runtime::app;
 pub use cu29_runtime::config;
 pub use cu29_runtime::context;
@@ -100,6 +101,8 @@ pub use cu29_runtime::rx_channels;
 #[cfg(feature = "std")]
 pub use cu29_runtime::simulation;
 pub use cu29_runtime::tx_channels;
+#[cfg(feature = "safety-ids")]
+pub mod safety;
 
 #[cfg(feature = "rtsan")]
 pub mod rtsan {
@@ -207,6 +210,20 @@ macro_rules! defmt_error {
     ($($tt:tt)*) => {{}};
 }
 
+#[macro_export]
+macro_rules! safety_check {
+    ($check_id:literal, $requirement_id:literal, $description:literal, $condition:expr $(,)?) => {
+        assert!($condition, "{}", $description);
+    };
+}
+
+#[macro_export]
+macro_rules! safety_check_eq {
+    ($check_id:literal, $requirement_id:literal, $description:literal, $left:expr, $right:expr $(,)?) => {
+        assert_eq!($left, $right, "{}", $description);
+    };
+}
+
 /// Canonical imports for Copper applications.
 ///
 /// This module intentionally re-exports each stable application-facing group once.
@@ -217,6 +234,7 @@ pub mod prelude {
     #[cfg(feature = "units")]
     pub use crate::units;
     pub use crate::{defmt_debug, defmt_error, defmt_info, defmt_warn};
+    pub use crate::{safety_case, safety_check, safety_check_eq};
     #[cfg(feature = "reflect")]
     pub use bevy_reflect_derive::Reflect;
     #[cfg(feature = "signal-handler")]

core/cu29/src/safety.rs

@@ -0,0 +1,107 @@
+use serde::Serialize;
+use std::fs;
+use std::path::Path;
+
+pub use inventory;
+
+#[derive(Debug, Clone, Copy, Serialize)]
+pub struct SafetyCheckRef {
+    pub check_id: &'static str,
+    pub requirement_id: &'static str,
+    pub description: &'static str,
+    pub kind: &'static str,
+}
+
+#[derive(Debug, Clone, Copy, Serialize)]
+pub struct SafetyCaseRef {
+    pub package: &'static str,
+    pub case_id: &'static str,
+    pub function: &'static str,
+    pub module_path: &'static str,
+    pub file: &'static str,
+    pub checks: &'static [SafetyCheckRef],
+}
+
+inventory::collect!(SafetyCaseRef);
+
+#[derive(Debug, Clone, Serialize)]
+pub struct PackageSafetyIndex {
+    pub package: String,
+    pub cases: Vec<CollectedSafetyCase>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct CollectedSafetyCase {
+    pub package: String,
+    pub case_id: String,
+    pub function: String,
+    pub test_name: String,
+    pub file: String,
+    pub checks: Vec<CollectedSafetyCheck>,
+}
+
+#[derive(Debug, Clone, Serialize)]
+pub struct CollectedSafetyCheck {
+    pub check_id: String,
+    pub requirement_id: String,
+    pub description: String,
+    pub kind: String,
+}
+
+pub fn collect_package_index(package: &str) -> PackageSafetyIndex {
+    let mut cases: Vec<_> = inventory::iter::<SafetyCaseRef>
+        .into_iter()
+        .filter(|case_ref| case_ref.package == package)
+        .map(|case_ref| CollectedSafetyCase {
+            package: case_ref.package.to_string(),
+            case_id: case_ref.case_id.to_string(),
+            function: case_ref.function.to_string(),
+            test_name: libtest_name(case_ref.module_path, case_ref.function),
+            file: case_ref.file.to_string(),
+            checks: case_ref
+                .checks
+                .iter()
+                .map(|check| CollectedSafetyCheck {
+                    check_id: check.check_id.to_string(),
+                    requirement_id: check.requirement_id.to_string(),
+                    description: check.description.to_string(),
+                    kind: check.kind.to_string(),
+                })
+                .collect(),
+        })
+        .collect();
+
+    cases.sort_by(|left, right| left.case_id.cmp(&right.case_id));
+    for case in &mut cases {
+        case.checks
+            .sort_by(|left, right| left.check_id.cmp(&right.check_id));
+    }
+
+    PackageSafetyIndex {
+        package: package.to_string(),
+        cases,
+    }
+}
+
+pub fn write_package_index_json(
+    path: impl AsRef<Path>,
+    index: &PackageSafetyIndex,
+) -> std::io::Result<()> {
+    let path = path.as_ref();
+    if let Some(parent) = path.parent() {
+        fs::create_dir_all(parent)?;
+    }
+    let json = serde_json::to_vec_pretty(index).expect("safety index should serialize");
+    fs::write(path, json)
+}
+
+fn libtest_name(module_path: &str, function: &str) -> String {
+    let mut segments = module_path.split("::");
+    let _crate_name = segments.next();
+    let rest: Vec<_> = segments.collect();
+    if rest.is_empty() {
+        function.to_string()
+    } else {
+        format!("{}::{}", rest.join("::"), function)
+    }
+}