feat: v3.5.0 commit 2 -- signal descriptors + validation

descriptors.py
  Descriptor gains signal_only: bool = False field. When True, the descriptor
  requires a signal-enabled rollout; the loop validates this at startup.

  RolloutTrace gains three optional signal history fields:
    signal_emission_history: (T,) mean emission activity per trace step
    signal_reception_history: (T,) mean |reception response| per trace step
    signal_retention: float  final_mass / initial_mass scalar
  slice() updated to preserve all three fields.

  Three new signal descriptor compute functions:
    compute_emission_activity: mean emission over trace tail, normalized by
      0.05 (max emission_rate). Measures dynamic emission, not just the
      emission_rate parameter. Zero for non-signal traces.
    compute_receptor_sensitivity: mean |reception response| over trace tail,
      normalized by 0.5. Measures chemical responsiveness. Zero for non-signal.
    compute_signal_retention: final_mass / initial_mass clipped to [0,1].
      High = conservative emitter, low = aggressive broadcaster. 1.0 for
      non-signal traces (no mass lost).

  All three registered in REGISTRY with signal_only=True.
  Ecological roles: broadcaster (high emit, low retain), listener (low emit,
  high sensitivity), predator candidate (high emit + high sensitivity + high alpha).

rollout.py
  emission_np and reception_np buffers allocated only for signal rollouts.
  Per-step: emission activity = G_pos_mean * rate; reception = |dot(signal_mean,
  receptor_profile)|. Both captured into trace tail. signal_retention_val
  computed as final_mass / initial_mass. All three passed to RolloutTrace.

loop.py
  After resolve_descriptors(), validate that no signal_only descriptor is
  active when signal_field=False. Raises ValueError with message pointing
  to --signal-field if violated.

tests
  test_descriptors.py: 15 new tests for all three signal descriptors covering
    zero-for-non-signal, zero-for-empty, scaling, clipping, unit interval.
  test_descriptor_registry.py: registry count updated 15→18; expected names
    set updated with emission_activity, receptor_sensitivity, signal_retention.
  test_loop.py: 3 new validation tests covering error-on-signal-only-without-
    signal-field, no-error-with-signal-field, no-error-for-standard-descriptors.

422 passed, 0 errors, 0 warnings

Author: rkv0id

src/biota/search/descriptors.py

@@ -112,6 +112,10 @@ class Descriptor:
     short_name: str
     direction_label: str
     compute: Callable[["RolloutTrace"], float]
+    signal_only: bool = False
+    """When True, this descriptor requires a signal-enabled rollout.
+    Passing a signal-only descriptor to a non-signal search raises a
+    ValueError at startup (enforced in loop.py)."""
 
 
 # === RolloutTrace ===
@@ -155,6 +159,19 @@ class RolloutTrace:
     point compactness term in the quality metric to penalise creatures that
     peak early and degrade. None when not captured (older code paths and
     rollout_batch, which does not support per-element midpoint capture)."""
+    signal_emission_history: np.ndarray | None = None
+    """Mean positive-growth emission activity per step in the trace tail.
+    Shape (T,) float32. Proportional to how much signal the creature
+    actually emitted at each step. None for non-signal rollouts."""
+    signal_reception_history: np.ndarray | None = None
+    """Mean absolute reception response |dot(convolved_signal, receptor)|
+    per step in the trace tail. Shape (T,) float32. Measures how strongly
+    the creature actually responded to the chemical environment.
+    None for non-signal rollouts."""
+    signal_retention: float | None = None
+    """final_mass / initial_mass for signal rollouts. Measures how much
+    mass the creature retained vs bled into the signal field.
+    None for non-signal rollouts."""
 
     def slice(self, start: int, end: int) -> "RolloutTrace":
         """Return a trace covering steps [start, end) within the original window.
@@ -171,6 +188,17 @@ def slice(self, start: int, end: int) -> "RolloutTrace":
             final_state=self.final_state,
             grid_size=self.grid_size,
             total_steps=self.total_steps,
+            signal_emission_history=(
+                self.signal_emission_history[start:end]
+                if self.signal_emission_history is not None
+                else None
+            ),
+            signal_reception_history=(
+                self.signal_reception_history[start:end]
+                if self.signal_reception_history is not None
+                else None
+            ),
+            signal_retention=self.signal_retention,
         )
 
 
@@ -653,6 +681,65 @@ def compute_spatial_entropy(trace: "RolloutTrace") -> float:
 # === registry ===
 
 
+# === signal descriptors ===
+
+
+def compute_emission_activity(trace: RolloutTrace) -> float:
+    """Mean emission activity over the trace tail, normalized to [0, 1].
+
+    Measures how much signal the creature actually emitted during its rollout,
+    not just what its emission_rate parameter is. A creature with high
+    emission_rate but low positive growth activity barely emits.
+
+    Returns 0.0 for non-signal rollouts (signal_emission_history is None).
+    Normalized against a typical peak of 0.02 (2x the max emission_rate).
+    """
+    if trace.signal_emission_history is None or len(trace.signal_emission_history) == 0:
+        return 0.0
+    mean_activity = float(trace.signal_emission_history.mean())
+    # Normalize: emission activity is bounded by emission_rate * G_peak.
+    # G_peak ~ 1.0, emission_rate max = 0.05, so peak activity ~ 0.05.
+    # Use 0.05 as normalizer to put typical values in [0, 1].
+    return float(np.clip(mean_activity / 0.05, 0.0, 1.0))
+
+
+def compute_receptor_sensitivity(trace: RolloutTrace) -> float:
+    """Mean absolute reception response over the trace tail, normalized to [0, 1].
+
+    Measures how strongly the creature actually responded to the chemical
+    environment it encountered during its solo rollout. High = the creature's
+    receptor profile was well-aligned with the signal it encountered and
+    produced strong growth modulation. Low = chemical mismatch or inert.
+
+    Returns 0.0 for non-signal rollouts.
+    Normalized against a typical peak of 0.5.
+    """
+    if trace.signal_reception_history is None or len(trace.signal_reception_history) == 0:
+        return 0.0
+    mean_response = float(np.abs(trace.signal_reception_history).mean())
+    return float(np.clip(mean_response / 0.5, 0.0, 1.0))
+
+
+def compute_signal_retention(trace: RolloutTrace) -> float:
+    """Mass retained vs bled into the signal field: final_mass / initial_mass.
+
+    High retention (near 1.0) = chemically conservative creature; keeps most
+    of its mass and emits sparingly. Low retention (near 0.0) = aggressive
+    emitter; broadcasts heavily at the cost of mass.
+
+    Together with emission_activity and receptor_sensitivity this creates a
+    three-axis chemical behavior space:
+      high emission + low retention = broadcaster
+      low emission + high sensitivity = listener
+      high emission + high sensitivity + high alpha = predator candidate
+
+    Returns 1.0 for non-signal rollouts (no mass was lost to signal field).
+    """
+    if trace.signal_retention is None:
+        return 1.0
+    return float(np.clip(trace.signal_retention, 0.0, 1.0))
+
+
 REGISTRY: dict[str, Descriptor] = {
     "velocity": Descriptor(
         name="velocity",
@@ -744,6 +831,28 @@ def compute_spatial_entropy(trace: "RolloutTrace") -> float:
         direction_label="more diffuse",
         compute=compute_spatial_entropy,
     ),
+    # --- signal-only descriptors ---
+    "emission_activity": Descriptor(
+        name="emission activity",
+        short_name="emit.act.",
+        direction_label="more active emission",
+        compute=compute_emission_activity,
+        signal_only=True,
+    ),
+    "receptor_sensitivity": Descriptor(
+        name="receptor sensitivity",
+        short_name="recep.sens.",
+        direction_label="more sensitive",
+        compute=compute_receptor_sensitivity,
+        signal_only=True,
+    ),
+    "signal_retention": Descriptor(
+        name="signal retention",
+        short_name="sig.ret.",
+        direction_label="more conservative",
+        compute=compute_signal_retention,
+        signal_only=True,
+    ),
 }
 
 DEFAULT_DESCRIPTORS: tuple[str, str, str] = ("velocity", "gyradius", "spectral_entropy")

src/biota/search/loop.py

@@ -208,6 +208,16 @@ def search(
     # Inject active descriptors into the rollout config so workers compute
     # the right three axes.
     active = resolve_descriptors(config.descriptor_names)
+
+    # Validate: signal-only descriptors require --signal-field.
+    signal_only_names = [d.name for d in active if d.signal_only]
+    if signal_only_names and not config.signal_field:
+        raise ValueError(
+            f"descriptor(s) {signal_only_names} require a signal-enabled search. "
+            f"Pass --signal-field (or set signal_field=True in SearchConfig) to "
+            f"activate the signal field, or choose non-signal descriptors instead."
+        )
+
     rollout_with_descriptors = dc_replace(config.rollout, active_descriptors=active)
     config = dc_replace(config, rollout=rollout_with_descriptors)
     state = _LoopState(

src/biota/search/rollout.py

@@ -293,6 +293,10 @@ def rollout(
     com_x_np = np.zeros(history_len, dtype=np.float32)
     bbox_np = np.zeros(history_len, dtype=np.float32)
     gyradius_np = np.zeros(history_len, dtype=np.float32)
+    # Signal history buffers -- only allocated for signal rollouts.
+    is_signal_rollout = signal is not None and sim_params.has_signal
+    emission_np = np.zeros(history_len, dtype=np.float32) if is_signal_rollout else None
+    reception_np = np.zeros(history_len, dtype=np.float32) if is_signal_rollout else None
     thumb_buf: list[torch.Tensor] = []
 
     # 5. Run the loop, capturing stats and frames as we go
@@ -304,6 +308,20 @@ def rollout(
         com_x_np[step] = com_x
         bbox_np[step] = bbox
         gyradius_np[step] = gyr
+        if (
+            emission_np is not None
+            and signal is not None
+            and sim_params.receptor_profile is not None
+        ):
+            # Emission activity: mean positive-growth signal emission this step.
+            g_pos_mean = float(state[:, :, 0].clamp(min=0.0).mean().item())
+            rate = sim_params.emission_rate if sim_params.emission_rate is not None else 0.0
+            emission_np[step] = g_pos_mean * rate
+            # Reception: mean |dot(signal_sum, receptor)| as a scalar.
+            if reception_np is not None:
+                sig_mean = signal.mean(dim=(0, 1))  # (C,)
+                rec_resp = float((sig_mean * sim_params.receptor_profile).sum().abs().item())
+                reception_np[step] = rec_resp
         if step in frame_indices:
             thumb_buf.append(_downsample_frame(state, thumbnail_size))
         if step == midpoint_step:
@@ -341,6 +359,11 @@ def rollout(
 
     # 7. Build the trace covering the last TRACE_TAIL_STEPS steps
     tail = min(TRACE_TAIL_STEPS, history_len)
+    # Signal retention scalar for the signal_retention descriptor.
+    signal_retention_val: float | None = None
+    if is_signal_rollout and initial_mass > 0:
+        signal_retention_val = float(np.clip(final_mass / initial_mass, 0.0, 1.0))
+
     trace = RolloutTrace(
         com_history=com_history[-tail:].astype(np.float32),
         bbox_fraction_history=bbox_np[-tail:].astype(np.float32),
@@ -349,6 +372,9 @@ def rollout(
         grid_size=config.sim.grid_h,
         total_steps=config.steps,
         midpoint_state=midpoint_state_np,
+        signal_emission_history=emission_np[-tail:] if emission_np is not None else None,
+        signal_reception_history=reception_np[-tail:] if reception_np is not None else None,
+        signal_retention=signal_retention_val,
     )
 
     # 8. Evaluate quality

tests/search/test_descriptor_registry.py

@@ -73,8 +73,8 @@ def _write_module(content: str) -> Path:
 # === REGISTRY ===
 
 
-def test_registry_has_fifteen_built_ins() -> None:
-    assert len(REGISTRY) == 15
+def test_registry_has_eighteen_built_ins() -> None:
+    assert len(REGISTRY) == 18
 
 
 def test_registry_contains_all_expected_names() -> None:
@@ -94,6 +94,9 @@ def test_registry_contains_all_expected_names() -> None:
         "morphological_instability",
         "activity",
         "spatial_entropy",
+        "emission_activity",
+        "receptor_sensitivity",
+        "signal_retention",
     }
     assert set(REGISTRY.keys()) == expected
 

tests/search/test_descriptors.py

@@ -37,9 +37,12 @@
     compute_angular_velocity,
     compute_descriptors,
     compute_displacement_ratio,
+    compute_emission_activity,
     compute_growth_gradient,
     compute_gyradius,
     compute_morphological_instability,
+    compute_receptor_sensitivity,
+    compute_signal_retention,
     compute_spatial_entropy,
     compute_spectral_entropy,
     compute_velocity,
@@ -533,3 +536,117 @@ def test_spatial_entropy_concentrated_less_than_diffuse() -> None:
 def test_spatial_entropy_in_unit_interval() -> None:
     state = np.random.default_rng(31).random((GRID, GRID)).astype(np.float32)
     assert 0.0 <= compute_spatial_entropy(_make_trace(final_state=state)) <= 1.0
+
+
+# ===========================================================================
+# Signal descriptors
+# ===========================================================================
+
+C = 16  # signal channels
+
+
+def _make_signal_trace(
+    emission_history: np.ndarray | None = None,
+    reception_history: np.ndarray | None = None,
+    retention: float | None = None,
+) -> RolloutTrace:
+    """Build a RolloutTrace with signal history fields populated."""
+    state = np.zeros((GRID, GRID), dtype=np.float32)
+    state[40:56, 40:56] = 1.0
+    return RolloutTrace(
+        com_history=np.full((TRACE_LEN, 2), 48.0, dtype=np.float32),
+        bbox_fraction_history=np.full(TRACE_LEN, 0.04, dtype=np.float32),
+        gyradius_history=np.zeros(TRACE_LEN, dtype=np.float32),
+        final_state=state,
+        grid_size=GRID,
+        total_steps=STEPS,
+        signal_emission_history=emission_history,
+        signal_reception_history=reception_history,
+        signal_retention=retention,
+    )
+
+
+# --- emission_activity ---
+
+
+def test_emission_activity_zero_for_non_signal() -> None:
+    trace = _make_trace()
+    assert compute_emission_activity(trace) == 0.0
+
+
+def test_emission_activity_zero_for_empty_history() -> None:
+    trace = _make_signal_trace(emission_history=np.array([], dtype=np.float32))
+    assert compute_emission_activity(trace) == 0.0
+
+
+def test_emission_activity_scales_with_emission() -> None:
+    low = _make_signal_trace(emission_history=np.full(TRACE_LEN, 0.005, dtype=np.float32))
+    high = _make_signal_trace(emission_history=np.full(TRACE_LEN, 0.04, dtype=np.float32))
+    assert compute_emission_activity(low) < compute_emission_activity(high)
+
+
+def test_emission_activity_clipped_to_unit() -> None:
+    # History above normalizer -> clips to 1.0
+    trace = _make_signal_trace(emission_history=np.full(TRACE_LEN, 1.0, dtype=np.float32))
+    assert compute_emission_activity(trace) == 1.0
+
+
+def test_emission_activity_in_unit_interval() -> None:
+    trace = _make_signal_trace(
+        emission_history=np.random.default_rng(7).random(TRACE_LEN).astype(np.float32) * 0.05
+    )
+    val = compute_emission_activity(trace)
+    assert 0.0 <= val <= 1.0
+
+
+# --- receptor_sensitivity ---
+
+
+def test_receptor_sensitivity_zero_for_non_signal() -> None:
+    trace = _make_trace()
+    assert compute_receptor_sensitivity(trace) == 0.0
+
+
+def test_receptor_sensitivity_zero_for_empty_history() -> None:
+    trace = _make_signal_trace(reception_history=np.array([], dtype=np.float32))
+    assert compute_receptor_sensitivity(trace) == 0.0
+
+
+def test_receptor_sensitivity_scales_with_response() -> None:
+    low = _make_signal_trace(reception_history=np.full(TRACE_LEN, 0.05, dtype=np.float32))
+    high = _make_signal_trace(reception_history=np.full(TRACE_LEN, 0.4, dtype=np.float32))
+    assert compute_receptor_sensitivity(low) < compute_receptor_sensitivity(high)
+
+
+def test_receptor_sensitivity_in_unit_interval() -> None:
+    trace = _make_signal_trace(
+        reception_history=np.random.default_rng(9).random(TRACE_LEN).astype(np.float32) * 0.3
+    )
+    val = compute_receptor_sensitivity(trace)
+    assert 0.0 <= val <= 1.0
+
+
+# --- signal_retention ---
+
+
+def test_signal_retention_one_for_non_signal() -> None:
+    """Non-signal rollout: no mass was lost, retention = 1.0."""
+    trace = _make_trace()
+    assert compute_signal_retention(trace) == 1.0
+
+
+def test_signal_retention_reflects_mass_loss() -> None:
+    # 70% retained -> 0.7
+    trace = _make_signal_trace(retention=0.7)
+    assert abs(compute_signal_retention(trace) - 0.7) < 1e-6
+
+
+def test_signal_retention_clipped_to_unit() -> None:
+    assert compute_signal_retention(_make_signal_trace(retention=1.5)) == 1.0
+    assert compute_signal_retention(_make_signal_trace(retention=-0.1)) == 0.0
+
+
+def test_signal_retention_high_beats_low() -> None:
+    high = _make_signal_trace(retention=0.95)
+    low = _make_signal_trace(retention=0.40)
+    assert compute_signal_retention(high) > compute_signal_retention(low)