feat(inference): apply remote inference rules in client pipeline

RuleCache now holds two rule sets — the regex parser rules and the
declarative inference rules — both swapped together when a fresh
manifest lands. New helpers:

  * RuleCache::inference_snapshot() — Arc-clone of the current
    remote inference rule list.
  * RuleCache::combined_inference_rules() — Vec of built-ins
    followed by the manifest's remote rules; the natural input to
    starstats_core::infer_with_rules.

To make snapshot + combine cheap, CompiledInferenceRule's apply
closure moves from Box<dyn Fn> to Arc<dyn Fn>. That makes the rule
Clone (the closure is shared by reference behind the Arc), so the
client can hand a Vec into the inference pass without recompiling.

Compile-failure path in compile_inference_or_warn leaves the
inference cache empty rather than poisoning it — combined_inference_rules
still emits the three built-ins so the timeline degrades gracefully
when a remote rule has a bug.

Both new methods carry #[allow(dead_code)] tied to the open follow-up
"Inference engine not wired into client ingest" — the call site
that consumes combined_inference_rules lands separately.

4 new client tests cover the empty-cache + populated-cache shapes
and compile_inference_or_warn's two paths.

Author: Nigel Tatschner

crates/starstats-client/src/parser_defs.rs

@@ -17,7 +17,10 @@
 use crate::storage::Storage;
 use anyhow::{Context, Result};
 use parking_lot::RwLock;
-use starstats_core::{compile_rules, CompiledRemoteRule, Manifest};
+use starstats_core::{
+    built_in_inference_rules, compile_inference_rules, compile_rules, CompiledInferenceRule,
+    CompiledRemoteRule, Manifest,
+};
 use std::sync::Arc;
 use std::time::Duration;
 
@@ -27,25 +30,64 @@ const FETCH_PATH: &str = "/v1/parser-definitions";
 /// Active rules, swapped atomically when a fresh manifest lands.
 /// Wrapped in an `Arc` so the gamelog worker can hold a reader without
 /// keeping the lock for the duration of a tail iteration.
+///
+/// Holds two rule sets — the regex-based parser rules and the
+/// declarative inference rules. Both are swapped together when a
+/// fresh manifest lands; readers take cheap `Arc::clone` snapshots.
 #[derive(Clone, Default)]
 pub struct RuleCache {
     inner: Arc<RwLock<Arc<Vec<CompiledRemoteRule>>>>,
+    inference: Arc<RwLock<Arc<Vec<CompiledInferenceRule>>>>,
 }
 
 impl RuleCache {
     pub fn new() -> Self {
         Self::default()
     }
 
-    /// Returns a snapshot of the current rule list. Cheap — just an
-    /// `Arc::clone`.
+    /// Returns a snapshot of the current parser rule list. Cheap —
+    /// just an `Arc::clone`.
     pub fn snapshot(&self) -> Arc<Vec<CompiledRemoteRule>> {
         self.inner.read().clone()
     }
 
+    /// Returns a snapshot of the current inference rule list. Cheap.
+    /// Callers typically combine this with [`built_in_inference_rules`]
+    /// before invoking [`starstats_core::infer_with_rules`].
+    ///
+    /// `#[allow(dead_code)]` is currently load-bearing: the inference
+    /// pass is not yet wired into the live ingest path (tracked in
+    /// `docs/superpowers/follow-ups/2026-05-17-event-handling.md` —
+    /// "Inference engine not wired into client ingest"). Once the
+    /// call site lands this method becomes the read-side handle.
+    #[allow(dead_code)]
+    pub fn inference_snapshot(&self) -> Arc<Vec<CompiledInferenceRule>> {
+        self.inference.read().clone()
+    }
+
+    /// Build the full rule set to feed into the inference pass:
+    /// built-in rules followed by remote-manifest rules. The built-ins
+    /// run first so the timeline gets the locally-defined behaviour
+    /// even when the manifest hasn't been fetched yet (cold start).
+    ///
+    /// `CompiledInferenceRule` is `Clone` (the `apply` closure lives
+    /// behind an `Arc`), so this is cheap. `#[allow(dead_code)]` for
+    /// the same reason as `inference_snapshot`.
+    #[allow(dead_code)]
+    pub fn combined_inference_rules(&self) -> Vec<CompiledInferenceRule> {
+        let mut combined = built_in_inference_rules();
+        let snapshot = self.inference_snapshot();
+        combined.extend(snapshot.iter().cloned());
+        combined
+    }
+
     fn replace(&self, rules: Vec<CompiledRemoteRule>) {
         *self.inner.write() = Arc::new(rules);
     }
+
+    fn replace_inference(&self, rules: Vec<CompiledInferenceRule>) {
+        *self.inference.write() = Arc::new(rules);
+    }
 }
 
 /// Hydrate the cache from SQLite. Call this once at startup, before
@@ -63,12 +105,15 @@ pub fn hydrate_from_storage(storage: &Storage, cache: &RuleCache) {
                         "some cached parser-def rules failed to compile"
                     );
                 }
+                let inference = compile_inference_or_warn(&manifest);
                 tracing::info!(
                     rules = compiled.len(),
+                    inference_rules = inference.len(),
                     manifest_version = manifest.version,
                     "hydrated parser-def cache from sqlite"
                 );
                 cache.replace(compiled);
+                cache.replace_inference(inference);
             }
             Err(e) => {
                 tracing::warn!(error = %e, "cached parser-def manifest is unparseable; ignoring");
@@ -83,6 +128,26 @@ pub fn hydrate_from_storage(storage: &Storage, cache: &RuleCache) {
     }
 }
 
+/// Compile a manifest's inference rules, or log + return empty on
+/// failure. Compile is strict (any invalid rule fails the whole
+/// batch), so we want both successful and failed paths to leave the
+/// client with a deterministic state — failures leave the inference
+/// cache empty; the built-in rules continue to run via
+/// `combined_inference_rules`'s built-in prefix.
+fn compile_inference_or_warn(manifest: &Manifest) -> Vec<CompiledInferenceRule> {
+    match compile_inference_rules(&manifest.inference_rules) {
+        Ok(rules) => rules,
+        Err(e) => {
+            tracing::warn!(
+                error = %e,
+                count = manifest.inference_rules.len(),
+                "remote inference rules failed to compile; keeping built-ins only"
+            );
+            Vec::new()
+        }
+    }
+}
+
 /// Background fetcher loop. Polls every 6h. The first iteration runs
 /// immediately so a cold-start client picks up the active manifest
 /// without waiting a quarter of a day.
@@ -129,11 +194,105 @@ async fn fetch_once(api_url: &str, storage: &Storage, cache: &RuleCache) -> Resu
             "some fetched parser-def rules failed to compile"
         );
     }
+    let inference = compile_inference_or_warn(&manifest);
     tracing::info!(
         rules = compiled.len(),
+        inference_rules = inference.len(),
         manifest_version = manifest.version,
         "applied fresh parser-def manifest"
     );
     cache.replace(compiled);
+    cache.replace_inference(inference);
     Ok(())
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use starstats_core::{EventPattern, EventTemplate, RemoteInferenceRule};
+    use std::collections::BTreeMap;
+
+    fn death_inference_rule() -> RemoteInferenceRule {
+        let mut fields = BTreeMap::new();
+        fields.insert("timestamp".into(), "${trigger.timestamp}".into());
+        fields.insert("body_class".into(), "inferred".into());
+        fields.insert(
+            "body_id".into(),
+            "inferred_${trigger.idempotency_key}".into(),
+        );
+        RemoteInferenceRule {
+            id: "manifest_test_rule".into(),
+            confidence: 0.85,
+            window_secs: 15,
+            trigger: EventPattern {
+                event_type: "vehicle_destruction".into(),
+                field_equals: BTreeMap::new(),
+            },
+            followups: vec![EventPattern {
+                event_type: "resolve_spawn".into(),
+                field_equals: BTreeMap::new(),
+            }],
+            emits: EventTemplate {
+                event_type: "player_death".into(),
+                fields,
+            },
+        }
+    }
+
+    #[test]
+    fn combined_inference_rules_includes_built_ins_only_when_cache_empty() {
+        let cache = RuleCache::new();
+        let combined = cache.combined_inference_rules();
+        // Three built-in rules (death, location, shop timeout).
+        assert_eq!(combined.len(), 3);
+        assert!(cache.inference_snapshot().is_empty());
+    }
+
+    #[test]
+    fn combined_inference_rules_appends_remote_rules_after_built_ins() {
+        let cache = RuleCache::new();
+        let compiled = compile_inference_rules(&[death_inference_rule()]).unwrap();
+        cache.replace_inference(compiled);
+        let combined = cache.combined_inference_rules();
+        // 3 built-ins + 1 remote.
+        assert_eq!(combined.len(), 4);
+        // Built-ins keep their canonical order; remote rule lands
+        // after them.
+        assert_eq!(combined[3].id, "manifest_test_rule");
+    }
+
+    #[test]
+    fn compile_inference_or_warn_returns_empty_on_invalid_rule() {
+        // confidence = 1.5 is outside [0.0, 1.0); compile rejects.
+        let mut bad = death_inference_rule();
+        bad.confidence = 1.5;
+        let manifest = Manifest {
+            version: 1,
+            schema_version: 1,
+            issued_at: "2026-05-18T00:00:00Z".into(),
+            rules: Vec::new(),
+            inference_rules: vec![bad],
+            signature: None,
+        };
+        let result = compile_inference_or_warn(&manifest);
+        assert!(
+            result.is_empty(),
+            "expected compile failure to produce empty vec"
+        );
+    }
+
+    #[test]
+    fn compile_inference_or_warn_passes_through_valid_rules() {
+        let manifest = Manifest {
+            version: 1,
+            schema_version: 1,
+            issued_at: "2026-05-18T00:00:00Z".into(),
+            rules: Vec::new(),
+            inference_rules: vec![death_inference_rule()],
+            signature: None,
+        };
+        let result = compile_inference_or_warn(&manifest);
+        assert_eq!(result.len(), 1);
+        assert_eq!(result[0].id, "manifest_test_rule");
+    }
+}

crates/starstats-core/src/inference.rs

@@ -78,15 +78,22 @@ pub struct InferenceMatch {
 /// passing the post-trigger window each time. Rules that don't care
 /// about a particular trigger return `None` cheaply (typically a
 /// pattern-match on the event variant).
+///
+/// The `apply` callback lives behind an `Arc` so caches that hold
+/// rule snapshots can `Clone` the rule without re-compiling the
+/// closure. Closure invocation through `&Arc<dyn Fn>` is a single
+/// indirection — the same cost as `&Box<dyn Fn>`.
+#[derive(Clone)]
 pub struct CompiledInferenceRule {
     pub id: String,
     pub confidence: f32,
     pub window_secs: i64,
     /// Callback invoked once per envelope. Returns the inferred event
     /// payload (if any) plus the source event IDs used as inputs.
     #[allow(clippy::type_complexity)]
-    pub apply:
-        Box<dyn Fn(&EventEnvelope, &[EventEnvelope]) -> Option<InferenceMatch> + Send + Sync>,
+    pub apply: std::sync::Arc<
+        dyn Fn(&EventEnvelope, &[EventEnvelope]) -> Option<InferenceMatch> + Send + Sync,
+    >,
 }
 
 impl std::fmt::Debug for CompiledInferenceRule {
@@ -373,7 +380,7 @@ fn built_in_implicit_death_after_vehicle_destruction() -> CompiledInferenceRule
         id: RULE_ID_IMPLICIT_DEATH.to_string(),
         confidence: IMPLICIT_DEATH_CONFIDENCE,
         window_secs: IMPLICIT_DEATH_WINDOW_SECS,
-        apply: Box::new(|env, window| {
+        apply: std::sync::Arc::new(|env, window| {
             let veh = match env.event.as_ref()? {
                 GameEvent::VehicleDestruction(v) => v,
                 _ => return None,
@@ -431,7 +438,7 @@ fn built_in_implicit_location_change() -> CompiledInferenceRule {
         id: RULE_ID_IMPLICIT_LOCATION_CHANGE.to_string(),
         confidence: IMPLICIT_LOCATION_CHANGE_CONFIDENCE,
         window_secs: i64::MAX,
-        apply: Box::new(move |env, _window| {
+        apply: std::sync::Arc::new(move |env, _window| {
             let mut st = state.lock().expect("location-change state mutex poisoned");
             match env.event.as_ref() {
                 Some(GameEvent::PlanetTerrainLoad(planet_load)) => {
@@ -495,7 +502,7 @@ fn built_in_implicit_shop_request_timeout() -> CompiledInferenceRule {
         id: RULE_ID_IMPLICIT_SHOP_REQUEST_TIMEOUT.to_string(),
         confidence: IMPLICIT_SHOP_REQUEST_TIMEOUT_CONFIDENCE,
         window_secs: IMPLICIT_SHOP_REQUEST_TIMEOUT_SECS,
-        apply: Box::new(|env, window| {
+        apply: std::sync::Arc::new(|env, window| {
             let req = match env.event.as_ref()? {
                 GameEvent::ShopBuyRequest(r) => r,
                 _ => return None,

crates/starstats-core/src/inference_defs.rs

@@ -167,7 +167,7 @@ fn compile_one(rule: RemoteInferenceRule) -> CompiledInferenceRule {
         id,
         confidence,
         window_secs,
-        apply: Box::new(move |env, window| {
+        apply: std::sync::Arc::new(move |env, window| {
             let observed = env.event.as_ref()?;
             if event_type_key(observed) != trigger.event_type {
                 return None;