Merge pull request #104 from dotindustries/feat/implement-threading-model-declaration-host-function-krt42xr96li73r05ad5ez1t2

feat: implement threading model declaration host function (US-118)

Author: tervezo-ai[bot]

crates/warpgrid-host/src/engine.rs

@@ -141,7 +141,22 @@ impl shim::threading::Host for HostState {
         &mut self,
         model: shim::threading::ThreadingModel,
     ) -> Result<(), String> {
-        tracing::info!(?model, "guest declared threading model");
+        if self.threading_model.is_some() {
+            return Err("threading model already declared".to_string());
+        }
+
+        match model {
+            shim::threading::ThreadingModel::ParallelRequired => {
+                tracing::warn!(
+                    ?model,
+                    "parallel threading requested but not supported; execution will use cooperative mode"
+                );
+            }
+            shim::threading::ThreadingModel::Cooperative => {
+                tracing::info!(?model, "cooperative threading model declared");
+            }
+        }
+
         self.threading_model = Some(model);
         Ok(())
     }
@@ -410,4 +425,58 @@ mod tests {
             Some(shim::threading::ThreadingModel::Cooperative)
         ));
     }
+
+    #[test]
+    fn threading_model_parallel_required_succeeds() {
+        let mut state = HostState {
+            filesystem: None,
+            dns: None,
+            db_proxy: None,
+            signal_queue: Vec::new(),
+            threading_model: None,
+            limiter: None,
+        };
+
+        shim::threading::Host::declare_threading_model(
+            &mut state,
+            shim::threading::ThreadingModel::ParallelRequired,
+        )
+        .unwrap();
+
+        assert!(matches!(
+            state.threading_model,
+            Some(shim::threading::ThreadingModel::ParallelRequired)
+        ));
+    }
+
+    #[test]
+    fn threading_model_double_declaration_errors() {
+        let mut state = HostState {
+            filesystem: None,
+            dns: None,
+            db_proxy: None,
+            signal_queue: Vec::new(),
+            threading_model: None,
+            limiter: None,
+        };
+
+        shim::threading::Host::declare_threading_model(
+            &mut state,
+            shim::threading::ThreadingModel::Cooperative,
+        )
+        .unwrap();
+
+        let result = shim::threading::Host::declare_threading_model(
+            &mut state,
+            shim::threading::ThreadingModel::ParallelRequired,
+        );
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("already declared"));
+
+        // Original model is preserved
+        assert!(matches!(
+            state.threading_model,
+            Some(shim::threading::ThreadingModel::Cooperative)
+        ));
+    }
 }

crates/warpgrid-host/src/threading.rs

@@ -0,0 +1,166 @@
+//! Threading model declaration host functions.
+//!
+//! Implements the `warpgrid:shim/threading` [`Host`] trait, storing the
+//! guest-declared threading model and enforcing immutability (single
+//! declaration only).
+//!
+//! # Declaration flow
+//!
+//! ```text
+//! Guest calls declare_threading_model(model)
+//!   → ThreadingHost checks immutability (already declared?)
+//!     → Already declared → Err("threading model already declared")
+//!     → Not declared:
+//!       → ParallelRequired → warn (not supported, cooperative fallback)
+//!       → Cooperative      → info log
+//!       → Store model, return Ok(())
+//! ```
+
+use crate::bindings::warpgrid::shim::threading::{Host, ThreadingModel};
+
+/// Host-side implementation of the `warpgrid:shim/threading` interface.
+///
+/// Stores the guest-declared threading model and enforces that it can
+/// only be declared once per instance (immutability after first call).
+///
+/// The host can query the declared model via [`threading_model`] to
+/// adapt execution strategy.
+///
+/// [`threading_model`]: ThreadingHost::threading_model
+pub struct ThreadingHost {
+    model: Option<ThreadingModel>,
+}
+
+impl ThreadingHost {
+    /// Create a new `ThreadingHost` with no declared model.
+    pub fn new() -> Self {
+        Self { model: None }
+    }
+
+    /// Query the declared threading model.
+    ///
+    /// Returns `None` if the guest has not yet declared a model.
+    pub fn threading_model(&self) -> Option<&ThreadingModel> {
+        self.model.as_ref()
+    }
+}
+
+impl Default for ThreadingHost {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl Host for ThreadingHost {
+    fn declare_threading_model(&mut self, model: ThreadingModel) -> Result<(), String> {
+        if self.model.is_some() {
+            return Err("threading model already declared".to_string());
+        }
+
+        match model {
+            ThreadingModel::ParallelRequired => {
+                tracing::warn!(
+                    ?model,
+                    "parallel threading requested but not supported; execution will use cooperative mode"
+                );
+            }
+            ThreadingModel::Cooperative => {
+                tracing::info!(?model, "cooperative threading model declared");
+            }
+        }
+
+        self.model = Some(model);
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // ── Construction ────────────────────────────────────────────────
+
+    #[test]
+    fn new_host_has_no_model() {
+        let host = ThreadingHost::new();
+        assert!(host.threading_model().is_none());
+    }
+
+    #[test]
+    fn default_has_no_model() {
+        let host = ThreadingHost::default();
+        assert!(host.threading_model().is_none());
+    }
+
+    // ── Cooperative declaration ─────────────────────────────────────
+
+    #[test]
+    fn declare_cooperative_succeeds() {
+        let mut host = ThreadingHost::new();
+        let result = host.declare_threading_model(ThreadingModel::Cooperative);
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn declare_cooperative_is_queryable() {
+        let mut host = ThreadingHost::new();
+        host.declare_threading_model(ThreadingModel::Cooperative).unwrap();
+        assert!(matches!(
+            host.threading_model(),
+            Some(&ThreadingModel::Cooperative)
+        ));
+    }
+
+    // ── Parallel-required declaration ───────────────────────────────
+
+    #[test]
+    fn declare_parallel_required_succeeds() {
+        let mut host = ThreadingHost::new();
+        let result = host.declare_threading_model(ThreadingModel::ParallelRequired);
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    fn declare_parallel_required_is_queryable() {
+        let mut host = ThreadingHost::new();
+        host.declare_threading_model(ThreadingModel::ParallelRequired).unwrap();
+        assert!(matches!(
+            host.threading_model(),
+            Some(&ThreadingModel::ParallelRequired)
+        ));
+    }
+
+    // ── Immutability (double declaration) ───────────────────────────
+
+    #[test]
+    fn double_declaration_returns_error() {
+        let mut host = ThreadingHost::new();
+        host.declare_threading_model(ThreadingModel::Cooperative).unwrap();
+
+        let result = host.declare_threading_model(ThreadingModel::Cooperative);
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("already declared"));
+    }
+
+    #[test]
+    fn double_declaration_different_models_returns_error() {
+        let mut host = ThreadingHost::new();
+        host.declare_threading_model(ThreadingModel::Cooperative).unwrap();
+
+        let result = host.declare_threading_model(ThreadingModel::ParallelRequired);
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("already declared"));
+    }
+
+    #[test]
+    fn double_declaration_preserves_original_model() {
+        let mut host = ThreadingHost::new();
+        host.declare_threading_model(ThreadingModel::Cooperative).unwrap();
+
+        let _ = host.declare_threading_model(ThreadingModel::ParallelRequired);
+        assert!(matches!(
+            host.threading_model(),
+            Some(&ThreadingModel::Cooperative)
+        ));
+    }
+}

crates/warpgrid-host/src/threading/host.rs

@@ -0,0 +1,12 @@
+//! Threading model declaration shim.
+//!
+//! Allows guest modules to declare their threading expectations
+//! (cooperative, parallel-required) so the host can warn about
+//! incompatibilities.
+//!
+//! The [`host`] submodule provides the WIT `Host` trait implementation
+//! that validates and stores the declared threading model.
+
+pub mod host;
+
+pub use host::ThreadingHost;