feat(simulation): composable behavior engine — action+modifier+context primitives (#633)

Replaces flat culture×zone×role behavior strings with three-layer
composition: BehaviorAction (role-generic), BehaviorModifier (culture
coloring), BehaviorContext (situation gating). Assembly at NpcBlueprint
instantiation. Backward compatible — falls back to legacy behaviors
when primitives are empty. D-139 filed, Q-057 resolved.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

server/src/bin/generator_spike.rs

@@ -31,8 +31,9 @@ use rand::SeedableRng;
 use rand_chacha::ChaCha20Rng;
 
 use settled_reach_server::npc::blueprint::{
-    BlueprintRelationship, CultureProfile, CulturalMarkers, CulturalValues, NamingConventions,
-    NpcBlueprint, NpcWant, RoleSpec, SocialSiteSpec, SpeechPatterns, SpikeOutput, ZoneSpec,
+    assemble_behaviors, BlueprintRelationship, CultureProfile, CulturalMarkers, CulturalValues,
+    NamingConventions, NpcBlueprint, NpcWant, RoleSpec, SocialSiteSpec, SpeechPatterns,
+    SpikeOutput, ZoneSpec,
 };
 use settled_reach_server::npc::PersonalityTrait;
 use settled_reach_server::simulation::rng::SimRng;
@@ -93,6 +94,7 @@ fn hardcoded_rural_zone() -> ZoneSpec {
                     "repairs equipment by hand".into(),
                     "watches the horizon with a practiced eye".into(),
                 ],
+                behavior_primitives: vec![],
             },
             RoleSpec {
                 id: "mechanic".into(),
@@ -105,6 +107,7 @@ fn hardcoded_rural_zone() -> ZoneSpec {
                     "wipes grease on coveralls between tasks".into(),
                     "explains repairs in terse technical shorthand".into(),
                 ],
+                behavior_primitives: vec![],
             },
             RoleSpec {
                 id: "trader".into(),
@@ -117,6 +120,7 @@ fn hardcoded_rural_zone() -> ZoneSpec {
                     "haggles with quiet persistence".into(),
                     "watches foot traffic from market stall".into(),
                 ],
+                behavior_primitives: vec![],
             },
             RoleSpec {
                 id: "militia".into(),
@@ -129,6 +133,7 @@ fn hardcoded_rural_zone() -> ZoneSpec {
                     "checks credentials at the gate".into(),
                     "leans on rifle while scanning the horizon".into(),
                 ],
+                behavior_primitives: vec![],
             },
         ],
         social_sites: vec![
@@ -163,6 +168,7 @@ fn hardcoded_industrial_zone() -> ZoneSpec {
                     "waits at a loading bay with arms crossed".into(),
                     "calls out bay numbers to a colleague".into(),
                 ],
+                behavior_primitives: vec![],
             },
             RoleSpec {
                 id: "technician".into(),
@@ -175,6 +181,7 @@ fn hardcoded_industrial_zone() -> ZoneSpec {
                     "traces conduit runs along a ceiling with a flashlight".into(),
                     "replaces a component panel with practiced speed".into(),
                 ],
+                behavior_primitives: vec![],
             },
             RoleSpec {
                 id: "foreman".into(),
@@ -187,6 +194,7 @@ fn hardcoded_industrial_zone() -> ZoneSpec {
                     "walks the floor with a datapad under one arm".into(),
                     "pulls aside a worker for a quiet word".into(),
                 ],
+                behavior_primitives: vec![],
             },
             RoleSpec {
                 id: "security".into(),
@@ -199,6 +207,7 @@ fn hardcoded_industrial_zone() -> ZoneSpec {
                     "checks IDs at the freight elevator".into(),
                     "stands at post near restricted equipment bays".into(),
                 ],
+                behavior_primitives: vec![],
             },
         ],
         social_sites: vec![
@@ -251,6 +260,7 @@ fn hardcoded_krenn_culture() -> CultureProfile {
         voice_persona: None,
         voice_examples: vec![],
         occasional_injections: vec![],
+        behavior_modifiers: vec![],
     }
 }
 
@@ -470,10 +480,29 @@ fn pick_role<'a>(rng: &mut SimRng, zone: &'a ZoneSpec) -> &'a RoleSpec {
 /// The pools are consumed as NPCs are generated: each NPC pops the front.
 /// When a pool is exhausted (more NPCs of that role than behaviors), `gen_behaviors`
 /// falls back to a random repeat with an eprintln warning — not a crash.
-fn build_behavior_pools(rng: &mut SimRng, zone: &ZoneSpec) -> BTreeMap<String, VecDeque<String>> {
+///
+/// When a role has non-empty `behavior_primitives`, uses `assemble_behaviors()`
+/// (D-139) to compose culture×role behaviors instead of flat `typical_behaviors`.
+/// Falls back to `typical_behaviors` when primitives are empty — backward compatible.
+fn build_behavior_pools(
+    rng: &mut SimRng,
+    zone: &ZoneSpec,
+    culture: &CultureProfile,
+) -> BTreeMap<String, VecDeque<String>> {
     let mut pools: BTreeMap<String, VecDeque<String>> = BTreeMap::new();
     for role in &zone.roles {
-        let mut behaviors: Vec<String> = role.typical_behaviors.clone();
+        let mut behaviors: Vec<String> = if !role.behavior_primitives.is_empty() {
+            // D-139: composable assembly — primitives + culture modifiers
+            assemble_behaviors(
+                &role.behavior_primitives,
+                &culture.behavior_modifiers,
+                None, // no context filter during pool building
+                rng,
+            )
+        } else {
+            // Legacy path: flat typical_behaviors strings
+            role.typical_behaviors.clone()
+        };
         let n = behaviors.len();
         // Fisher-Yates shuffle using the main RNG (deterministic order is zone-seeded).
         for i in 0..n {
@@ -1020,7 +1049,8 @@ fn main() {
     let name_pool = build_name_pool(args.seed, &args.zone, &culture, npc_count);
 
     // Pre-shuffle behavior pools per role (#629 fix: dedup within a zone run).
-    let mut behavior_pools = build_behavior_pools(&mut rng, &zone);
+    // D-139: uses assemble_behaviors() when behavior_primitives are present.
+    let mut behavior_pools = build_behavior_pools(&mut rng, &zone, &culture);
 
     // First pass: generate all NPCs (no relationships yet)
     let mut npcs: Vec<NpcBlueprint> = name_pool

server/src/npc/blueprint.rs

@@ -19,6 +19,7 @@
 //! RON (Rusty Object Notation) — struct-aware, supports enums and comments.
 //! Validate with: `tooling/validate-ron <file.ron>`
 
+use rand::Rng;
 use serde::{Deserialize, Serialize};
 
 use crate::npc::PersonalityTrait;
@@ -66,7 +67,15 @@ pub struct RoleSpec {
     /// Whether this role may have combat capability.
     pub combat_eligible: bool,
     /// Observable behaviors typical for this role (generator picks from these).
+    /// Legacy field — preserved for backward compatibility until composable
+    /// assembly produces verified-equivalent output.
     pub typical_behaviors: Vec<String>,
+    /// Composable behavior primitives (#633, Q-057).
+    /// Role-generic physical stage directions that get composed with culture
+    /// modifiers at NpcBlueprint instantiation time. When present, the assembly
+    /// function uses these instead of `typical_behaviors`.
+    #[serde(default)]
+    pub behavior_primitives: Vec<BehaviorPrimitive>,
 }
 
 /// A social site template within a zone.
@@ -84,6 +93,131 @@ pub struct SocialSiteSpec {
     pub max_npcs: u8,
 }
 
+// ---------------------------------------------------------------------------
+// Composable behavior primitives (#633, Q-057)
+// ---------------------------------------------------------------------------
+
+/// A composable behavior primitive — a role-generic stage direction.
+///
+/// The assembly function composes: `action_text` + optional culture modifier
+/// → final observable behavior string. Context tags gate when the behavior
+/// is eligible for selection.
+///
+/// Example:
+///   action_text: "moves freight containers"
+///   context: OnShift
+///   → assembled with Krenn modifier "with mechanical efficiency"
+///   → "moves freight containers with mechanical efficiency"
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct BehaviorPrimitive {
+    /// The action text — a role-generic physical stage direction.
+    /// Must be a complete sentence fragment that can stand alone or
+    /// accept a trailing modifier clause.
+    pub action: String,
+    /// Context tag gating when this behavior is eligible.
+    pub context: BehaviorContext,
+    /// Optional modifier slot hint. If set, the assembly function
+    /// prefers modifiers matching this category. If empty, any
+    /// compatible modifier may be selected.
+    #[serde(default)]
+    pub modifier_hint: Option<String>,
+}
+
+/// Context tags that gate when a behavior primitive is eligible.
+///
+/// The generator checks the NPC's current assignment against these tags
+/// to filter the behavior pool before selection.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub enum BehaviorContext {
+    /// Available during work shifts at the NPC's assigned zone.
+    OnShift,
+    /// Available when the NPC is off duty (break rooms, bars, quarters).
+    OffDuty,
+    /// Available at social sites (taverns, break rooms, cantinas).
+    Social,
+    /// Available anywhere — no context restriction.
+    Any,
+}
+
+impl Default for BehaviorContext {
+    fn default() -> Self {
+        Self::Any
+    }
+}
+
+/// A culture-specific behavior modifier clause.
+///
+/// Appended to a `BehaviorPrimitive.action` during assembly to add
+/// cultural flavor. The composition engine selects modifiers from the
+/// culture profile and concatenates them with the action text.
+///
+/// Example:
+///   category: "work_style"
+///   clause: "with mechanical efficiency"
+///   → "moves freight containers with mechanical efficiency"
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct BehaviorModifier {
+    /// Modifier category for matching against `BehaviorPrimitive.modifier_hint`.
+    /// Also used for dedup — at most one modifier per category per NPC.
+    pub category: String,
+    /// The modifier clause text. Concatenated to action text with a space.
+    pub clause: String,
+}
+
+/// Assemble observable behavior strings from primitives + culture modifiers.
+///
+/// This is the core composition function (#633). It replaces the flat
+/// `typical_behaviors` selection with a composable pipeline:
+///
+/// 1. Filter primitives by context (pass `None` for no filtering)
+/// 2. For each eligible primitive, select a culture modifier
+/// 3. Concatenate: `action + " " + modifier.clause`
+/// 4. If no modifier matches, use the action text as-is
+///
+/// Returns the assembled strings in the same order as the input primitives.
+pub fn assemble_behaviors(
+    primitives: &[BehaviorPrimitive],
+    modifiers: &[BehaviorModifier],
+    context_filter: Option<BehaviorContext>,
+    rng: &mut crate::simulation::rng::SimRng,
+) -> Vec<String> {
+    let eligible: Vec<&BehaviorPrimitive> = primitives
+        .iter()
+        .filter(|p| match context_filter {
+            Some(ctx) => p.context == ctx || p.context == BehaviorContext::Any,
+            None => true,
+        })
+        .collect();
+
+    let mut results = Vec::with_capacity(eligible.len());
+
+    for prim in &eligible {
+        // Find matching modifiers: prefer hint match, fall back to any
+        let matching: Vec<&BehaviorModifier> = if let Some(ref hint) = prim.modifier_hint {
+            let hinted: Vec<&BehaviorModifier> =
+                modifiers.iter().filter(|m| &m.category == hint).collect();
+            if hinted.is_empty() {
+                modifiers.iter().collect()
+            } else {
+                hinted
+            }
+        } else {
+            modifiers.iter().collect()
+        };
+
+        if matching.is_empty() {
+            // No modifiers available — use action text as-is
+            results.push(prim.action.clone());
+        } else {
+            let idx = rng.rng.random_range(0..matching.len());
+            let modifier = matching[idx];
+            results.push(format!("{} {}", prim.action, modifier.clause));
+        }
+    }
+
+    results
+}
+
 // ---------------------------------------------------------------------------
 // Culture profile (input — filled by copy team, ticket #610)
 // ---------------------------------------------------------------------------
@@ -116,6 +250,11 @@ pub struct CultureProfile {
     /// Some cultures have none, others several. No cap on count.
     #[serde(default)]
     pub occasional_injections: Vec<OccasionalInjection>,
+    /// Culture-specific behavior modifier clauses (#633, Q-057).
+    /// Composed with `BehaviorPrimitive` actions during NPC generation.
+    /// Empty means no cultural modifier — action text used as-is.
+    #[serde(default)]
+    pub behavior_modifiers: Vec<BehaviorModifier>,
 }
 
 /// Naming conventions for NPC name generation.
@@ -338,6 +477,7 @@ mod tests {
                 skill_focus: vec!["technical".into()],
                 combat_eligible: false,
                 typical_behaviors: vec!["tends crops".into()],
+                behavior_primitives: vec![],
             }],
             social_sites: vec![SocialSiteSpec {
                 site_type: "tavern".into(),
@@ -382,6 +522,7 @@ mod tests {
             voice_persona: None,
             voice_examples: vec![],
             occasional_injections: vec![],
+            behavior_modifiers: vec![],
         };
 
         let ron_str =
@@ -436,4 +577,146 @@ mod tests {
         assert_eq!(deserialized.zone_type, "rural");
         assert_eq!(deserialized.seed, 42);
     }
+
+    // -----------------------------------------------------------------------
+    // Composable behavior assembly tests (#633)
+    // -----------------------------------------------------------------------
+
+    #[test]
+    fn assemble_behaviors_with_modifiers() {
+        use crate::simulation::rng::SimRng;
+        let mut rng = SimRng::new(42);
+
+        let primitives = vec![
+            BehaviorPrimitive {
+                action: "moves freight containers".into(),
+                context: BehaviorContext::OnShift,
+                modifier_hint: Some("work_style".into()),
+            },
+            BehaviorPrimitive {
+                action: "patrols the perimeter".into(),
+                context: BehaviorContext::OnShift,
+                modifier_hint: None,
+            },
+        ];
+        let modifiers = vec![
+            BehaviorModifier {
+                category: "work_style".into(),
+                clause: "with mechanical efficiency".into(),
+            },
+            BehaviorModifier {
+                category: "demeanor".into(),
+                clause: "with a watchful eye".into(),
+            },
+        ];
+
+        let result = assemble_behaviors(&primitives, &modifiers, Some(BehaviorContext::OnShift), &mut rng);
+        assert_eq!(result.len(), 2);
+        // First primitive has hint "work_style" → should match the work_style modifier
+        assert_eq!(result[0], "moves freight containers with mechanical efficiency");
+        // Second primitive has no hint → either modifier is valid
+        assert!(result[1].starts_with("patrols the perimeter"));
+    }
+
+    #[test]
+    fn assemble_behaviors_no_modifiers_returns_action_text() {
+        use crate::simulation::rng::SimRng;
+        let mut rng = SimRng::new(42);
+
+        let primitives = vec![BehaviorPrimitive {
+            action: "tends crops in the field".into(),
+            context: BehaviorContext::Any,
+            modifier_hint: None,
+        }];
+
+        let result = assemble_behaviors(&primitives, &[], None, &mut rng);
+        assert_eq!(result.len(), 1);
+        assert_eq!(result[0], "tends crops in the field");
+    }
+
+    #[test]
+    fn assemble_behaviors_context_filter() {
+        use crate::simulation::rng::SimRng;
+        let mut rng = SimRng::new(42);
+
+        let primitives = vec![
+            BehaviorPrimitive {
+                action: "works shift".into(),
+                context: BehaviorContext::OnShift,
+                modifier_hint: None,
+            },
+            BehaviorPrimitive {
+                action: "drinks at bar".into(),
+                context: BehaviorContext::Social,
+                modifier_hint: None,
+            },
+            BehaviorPrimitive {
+                action: "stretches".into(),
+                context: BehaviorContext::Any,
+                modifier_hint: None,
+            },
+        ];
+
+        // OnShift filter: should return OnShift + Any
+        let on_shift = assemble_behaviors(&primitives, &[], Some(BehaviorContext::OnShift), &mut rng);
+        assert_eq!(on_shift.len(), 2);
+        assert_eq!(on_shift[0], "works shift");
+        assert_eq!(on_shift[1], "stretches");
+
+        // Social filter: should return Social + Any
+        let social = assemble_behaviors(&primitives, &[], Some(BehaviorContext::Social), &mut rng);
+        assert_eq!(social.len(), 2);
+        assert_eq!(social[0], "drinks at bar");
+        assert_eq!(social[1], "stretches");
+
+        // No filter: all three
+        let all = assemble_behaviors(&primitives, &[], None, &mut rng);
+        assert_eq!(all.len(), 3);
+    }
+
+    #[test]
+    fn assemble_behaviors_hint_fallback_to_any_modifier() {
+        use crate::simulation::rng::SimRng;
+        let mut rng = SimRng::new(42);
+
+        let primitives = vec![BehaviorPrimitive {
+            action: "runs diagnostics".into(),
+            context: BehaviorContext::Any,
+            modifier_hint: Some("nonexistent_category".into()),
+        }];
+        let modifiers = vec![BehaviorModifier {
+            category: "demeanor".into(),
+            clause: "with focused intensity".into(),
+        }];
+
+        // Hint doesn't match any modifier category → falls back to any modifier
+        let result = assemble_behaviors(&primitives, &modifiers, None, &mut rng);
+        assert_eq!(result[0], "runs diagnostics with focused intensity");
+    }
+
+    #[test]
+    fn behavior_primitive_round_trips_through_ron() {
+        let prim = BehaviorPrimitive {
+            action: "moves freight containers".into(),
+            context: BehaviorContext::OnShift,
+            modifier_hint: Some("work_style".into()),
+        };
+        let ron_str = ron::ser::to_string_pretty(&prim, ron::ser::PrettyConfig::default()).unwrap();
+        let deserialized: BehaviorPrimitive = ron::from_str(&ron_str).unwrap();
+        assert_eq!(deserialized.action, "moves freight containers");
+        assert_eq!(deserialized.context, BehaviorContext::OnShift);
+        assert_eq!(deserialized.modifier_hint, Some("work_style".into()));
+    }
+
+    #[test]
+    fn behavior_modifier_round_trips_through_ron() {
+        let modifier = BehaviorModifier {
+            category: "work_style".into(),
+            clause: "with mechanical efficiency".into(),
+        };
+        let ron_str = ron::ser::to_string_pretty(&modifier, ron::ser::PrettyConfig::default()).unwrap();
+        let deserialized: BehaviorModifier = ron::from_str(&ron_str).unwrap();
+        assert_eq!(deserialized.category, "work_style");
+        assert_eq!(deserialized.clause, "with mechanical efficiency");
+    }
 }

server/src/npc/mod.rs

@@ -117,6 +117,16 @@ impl Plugin for NpcPlugin {
 #[derive(Component, Debug)]
 pub struct Npc;
 
+/// Voice culture identifier for an NPC entity (D-138).
+///
+/// Stores the culture_id used to key the voice cache. Attached at spawn time
+/// by the content system or generator. Absent NPCs fall back to base text.
+#[derive(Component, Debug, Clone)]
+pub struct NpcVoiceProfile {
+    pub culture_id: String,
+}
+
+
 /// NPC animation tier (D-047).
 ///
 /// Tier 1 (clear): public daily activities — instantly readable.