From caf12461d3e72417694c435099c1e5a182fc58ee Mon Sep 17 00:00:00 2001
From: mfw78 <mfw78@nxm.rs>
Date: Tue, 21 Jul 2026 23:43:06 +0000
Subject: [PATCH 1/2] docs(videre-host): note install mutex discipline

---
 crates/videre-host/src/registry.rs | 1 +
 1 file changed, 1 insertion(+)

diff --git a/crates/videre-host/src/registry.rs b/crates/videre-host/src/registry.rs
index 88a44392..5ba1ca90 100644
--- a/crates/videre-host/src/registry.rs
+++ b/crates/videre-host/src/registry.rs
@@ -353,6 +353,7 @@ impl VenueRegistry {
         liveness: Liveness,
         invoker: impl VenueInvoker + 'static,
     ) -> Result<(), DuplicateVenue> {
+        // Takes the adapter-map mutex only for the synchronous insert; never held across an await.
         let mut adapters = self.inner.adapters.lock().expect("adapter map poisoned");
         if adapters.get(&venue).is_some_and(|v| v.liveness.is_alive()) {
             return Err(DuplicateVenue { venue });

From dd71a37813575d7bf4fe850cbcf2c4a479652c1a Mon Sep 17 00:00:00 2001
From: mfw78 <mfw78@nxm.rs>
Date: Thu, 23 Jul 2026 14:52:54 +0000
Subject: [PATCH 2/2] refactor(videre-host): gate install to pub(crate)

Install is boot-time only; drop it off the shared public handle so a
post-boot clone cannot register with no compiler signal. Out-of-crate
tests reach a mock adapter through the test-utils install_for_test seam.
---
 Cargo.lock                           |  1 +
 crates/videre-host/Cargo.toml        | 11 +++++++++++
 crates/videre-host/src/registry.rs   | 19 +++++++++++++++++--
 crates/videre-host/tests/platform.rs |  2 +-
 4 files changed, 30 insertions(+), 3 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 1b2b7ece..6733e983 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -5959,6 +5959,7 @@ dependencies = [
  "tokio",
  "toml 1.1.2+spec-1.1.0",
  "tracing",
+ "videre-host",
  "videre-status-body",
  "wasmtime",
 ]
diff --git a/crates/videre-host/Cargo.toml b/crates/videre-host/Cargo.toml
index a8c6dd11..e45d28d3 100644
--- a/crates/videre-host/Cargo.toml
+++ b/crates/videre-host/Cargo.toml
@@ -26,7 +26,18 @@ tokio.workspace = true
 toml.workspace = true
 tracing.workspace = true
 
+[features]
+# Test-only helpers: the direct `VenueRegistry::install_for_test` seam, so an
+# out-of-crate test installs a mock adapter without the provider boot path.
+# Off by default; the self dev-dependency below turns it on for this crate's
+# own tests.
+test-utils = []
+
 [dev-dependencies]
+# Self dev-dependency enabling `test-utils` for this crate's own test targets,
+# so `cargo test -p videre-host` sees `install_for_test` without every
+# invocation passing `--features test-utils`.
+videre-host = { path = ".", features = ["test-utils"] }
 nexum-runtime = { path = "../nexum-runtime", features = ["test-utils"] }
 nexum-tasks = { path = "../nexum-tasks" }
 tempfile.workspace = true
diff --git a/crates/videre-host/src/registry.rs b/crates/videre-host/src/registry.rs
index 5ba1ca90..d62994d6 100644
--- a/crates/videre-host/src/registry.rs
+++ b/crates/videre-host/src/registry.rs
@@ -347,13 +347,17 @@ impl VenueRegistry {
     /// adapters answering the same venue would silently shadow one another,
     /// which is a config error worth failing boot over. A dead incumbent is
     /// replaced: that is the sweep restarting a trapped adapter.
-    pub fn install(
+    ///
+    /// Crate-internal: adapters install at provider boot, never post-boot
+    /// through a shared handle clone.
+    pub(crate) fn install(
         &self,
         venue: VenueId,
         liveness: Liveness,
         invoker: impl VenueInvoker + 'static,
     ) -> Result<(), DuplicateVenue> {
-        // Takes the adapter-map mutex only for the synchronous insert; never held across an await.
+        // Takes the adapter-map mutex only for the synchronous insert; never
+        // held across an await.
         let mut adapters = self.inner.adapters.lock().expect("adapter map poisoned");
         if adapters.get(&venue).is_some_and(|v| v.liveness.is_alive()) {
             return Err(DuplicateVenue { venue });
@@ -368,6 +372,17 @@ impl VenueRegistry {
         Ok(())
     }
 
+    /// Test-only direct install, bypassing the provider boot path.
+    #[cfg(feature = "test-utils")]
+    pub fn install_for_test(
+        &self,
+        venue: VenueId,
+        liveness: Liveness,
+        invoker: impl VenueInvoker + 'static,
+    ) -> Result<(), DuplicateVenue> {
+        self.install(venue, liveness, invoker)
+    }
+
     /// Resolve a venue id to its installed adapter slot. An uninstalled
     /// venue is `unknown-venue`; an installed but dead one is `unavailable`
     /// pending the supervisor's restart sweep, without touching its
diff --git a/crates/videre-host/tests/platform.rs b/crates/videre-host/tests/platform.rs
index ff3506f2..2385900a 100644
--- a/crates/videre-host/tests/platform.rs
+++ b/crates/videre-host/tests/platform.rs
@@ -281,7 +281,7 @@ impl VenueInvoker for ScriptedAdapter {
 fn scripted_registry(adapter: ScriptedAdapter) -> VenueRegistry {
     let registry = VenueRegistryBuilder::new(Default::default()).build();
     registry
-        .install(
+        .install_for_test(
             VenueId::from("cow"),
             nexum_runtime::host::actor::Liveness::default(),
             adapter,