feat: add soften_forward (backtrack tolerance + tanh overshoot compression)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

tests/unit/test_postprocess.py

@@ -141,3 +141,44 @@ def test_sample_duration_uses_correct_bin() -> None:
     v = sample_duration(dist_dict, 150.0, rng)
     # exp(6) ~ 403, with tiny sigma we should land near there
     assert 350 < v < 460
+
+
+from ai_mouse._postprocess import soften_forward
+
+
+def test_soften_forward_tolerates_small_backtrack() -> None:
+    # A 0.01 dip is within the 0.02 tolerance and must survive untouched.
+    f = np.array([0.0, 0.30, 0.29, 0.60, 1.0])
+    out = soften_forward(f)
+    assert np.isclose(out[2], 0.29)
+
+
+def test_soften_forward_limits_large_backtrack() -> None:
+    # A 0.30 dip is noise; it gets pulled up to prev - tol.
+    f = np.array([0.0, 0.50, 0.20, 0.70, 1.0])
+    out = soften_forward(f)
+    assert np.isclose(out[2], 0.50 - 0.02)
+
+
+def test_soften_forward_allows_moderate_overshoot() -> None:
+    # Overshoot past 1.0 is natural; small overshoot survives (compressed
+    # but strictly > 1.0).
+    f = np.array([0.0, 0.5, 0.9, 1.04, 1.0])
+    out = soften_forward(f)
+    assert out[3] > 1.0
+
+
+def test_soften_forward_compresses_extreme_overshoot() -> None:
+    # tanh compression: no output value may exceed 1 + overshoot_span.
+    f = np.array([0.0, 0.5, 1.30, 1.50, 1.0])
+    out = soften_forward(f)
+    assert out.max() <= 1.0 + 0.08 + 1e-9
+    assert out[2] > 1.0  # still an overshoot, not clipped flat
+
+
+def test_soften_forward_no_lower_clip() -> None:
+    # Small wind-up behind the start is allowed (warp_endpoints pins
+    # the first point later; interior may be slightly negative).
+    f = np.array([0.0, -0.01, 0.30, 0.70, 1.0])
+    out = soften_forward(f)
+    assert out[1] < 0.0