feat(realism): operator-tunable planner weights via realism_config

New realism_config table (uuid PK + unique key) + two repo methods
(get/set) backs an admin-only GET/PUT /api/v1/realism/config surface.

The planner now exposes apply_payload(payload) / current_payload() /
reset_to_defaults() and reads its weights through mutable module
globals; pick() resolves the live values each call. Validation
catches negative weights, zero totals, out-of-range canary_probability,
unknown content_class names, and silently drops cross-list entries
(canary class on the user list, etc).

The orchestrator worker calls _refresh_realism_config(repo) on
startup and every 5 ticks (~5min at 60s interval). Operator changes
land within one refresh window with no bus signal — the simpler path
for a knob whose latency tolerance is minutes.

tests/api/realism/test_config_api.py

@@ -0,0 +1,109 @@
+"""GET/PUT /api/v1/realism/config — operator-tunable weights."""
+from __future__ import annotations
+
+import json
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from fastapi import HTTPException
+
+from decnet.realism import planner
+
+
+@pytest.fixture(autouse=True)
+def _reset_planner():
+    yield
+    planner.reset_to_defaults()
+
+
+@pytest.mark.asyncio
+async def test_get_returns_defaults_when_no_row():
+    from decnet.web.router.realism.api_config import get_config
+
+    with patch("decnet.web.router.realism.api_config.repo") as mock_repo:
+        mock_repo.get_realism_config = AsyncMock(return_value=None)
+
+        result = await get_config(user={"uuid": "u", "role": "viewer"})
+
+    assert result["canary_probability"] == pytest.approx(0.03)
+    assert result["user_class_weights"]
+
+
+@pytest.mark.asyncio
+async def test_get_hydrates_from_db_row():
+    from decnet.web.router.realism.api_config import get_config
+
+    stored = json.dumps({"canary_probability": 0.10})
+    with patch("decnet.web.router.realism.api_config.repo") as mock_repo:
+        mock_repo.get_realism_config = AsyncMock(
+            return_value={"key": "weights", "value": stored},
+        )
+        result = await get_config(user={"uuid": "u", "role": "viewer"})
+
+    assert result["canary_probability"] == pytest.approx(0.10)
+
+
+@pytest.mark.asyncio
+async def test_get_serves_defaults_when_stored_payload_invalid():
+    """Stored JSON parsed but failed planner validation: log + serve
+    defaults rather than 500."""
+    from decnet.web.router.realism.api_config import get_config
+
+    stored = json.dumps({"canary_probability": 9.0})
+    with patch("decnet.web.router.realism.api_config.repo") as mock_repo:
+        mock_repo.get_realism_config = AsyncMock(
+            return_value={"key": "weights", "value": stored},
+        )
+        result = await get_config(user={"uuid": "u", "role": "viewer"})
+
+    assert result["canary_probability"] == pytest.approx(0.03)
+
+
+@pytest.mark.asyncio
+async def test_put_persists_and_returns_snapshot():
+    from decnet.web.router.realism.api_config import put_config
+
+    with patch("decnet.web.router.realism.api_config.repo") as mock_repo:
+        mock_repo.set_realism_config = AsyncMock()
+
+        result = await put_config(
+            body={"canary_probability": 0.20},
+            user={"uuid": "u", "role": "admin", "username": "anti"},
+        )
+
+    assert result["canary_probability"] == pytest.approx(0.20)
+    mock_repo.set_realism_config.assert_awaited_once()
+    args, _ = mock_repo.set_realism_config.call_args
+    assert args[0] == "weights"
+    persisted = json.loads(args[1])
+    assert persisted["canary_probability"] == pytest.approx(0.20)
+
+
+@pytest.mark.asyncio
+async def test_put_returns_400_on_invalid_payload():
+    from decnet.web.router.realism.api_config import put_config
+
+    with patch("decnet.web.router.realism.api_config.repo") as mock_repo:
+        mock_repo.set_realism_config = AsyncMock()
+
+        with pytest.raises(HTTPException) as exc:
+            await put_config(
+                body={"canary_probability": 9.0},
+                user={"uuid": "u", "role": "admin", "username": "anti"},
+            )
+
+    assert exc.value.status_code == 400
+    # No DB write on validation failure.
+    mock_repo.set_realism_config.assert_not_called()
+
+
+@pytest.mark.asyncio
+async def test_put_rejects_non_dict_body():
+    from decnet.web.router.realism.api_config import put_config
+
+    with pytest.raises(HTTPException) as exc:
+        await put_config(
+            body=[1, 2, 3],  # type: ignore[arg-type]
+            user={"uuid": "u", "role": "admin", "username": "anti"},
+        )
+    assert exc.value.status_code == 400

tests/orchestrator/test_realism_config_refresh.py

@@ -0,0 +1,74 @@
+"""The orchestrator pulls operator-tuned weights from realism_config.
+
+§3c contract: the planner reads in-memory module globals, but the
+operator's tuning lives in the DB (admin PUT /api/v1/realism/config).
+The orchestrator worker bridges the two by calling
+``_refresh_realism_config(repo)`` at startup and every Nth tick.
+"""
+from __future__ import annotations
+
+import json
+from unittest.mock import AsyncMock
+
+import pytest
+
+from decnet.orchestrator.worker import _refresh_realism_config
+from decnet.realism import planner
+
+
+@pytest.fixture(autouse=True)
+def _reset_planner():
+    yield
+    planner.reset_to_defaults()
+
+
+@pytest.mark.asyncio
+async def test_refresh_no_row_keeps_defaults():
+    repo = AsyncMock()
+    repo.get_realism_config = AsyncMock(return_value=None)
+    await _refresh_realism_config(repo)
+    assert planner.current_payload()["canary_probability"] == pytest.approx(0.03)
+
+
+@pytest.mark.asyncio
+async def test_refresh_applies_stored_payload():
+    repo = AsyncMock()
+    repo.get_realism_config = AsyncMock(return_value={
+        "key": "weights",
+        "value": json.dumps({"canary_probability": 0.12}),
+    })
+    await _refresh_realism_config(repo)
+    assert planner.current_payload()["canary_probability"] == pytest.approx(0.12)
+
+
+@pytest.mark.asyncio
+async def test_refresh_swallows_db_error():
+    """A wedged DB must not bring down the orchestrator's tick loop."""
+    repo = AsyncMock()
+    repo.get_realism_config = AsyncMock(side_effect=RuntimeError("boom"))
+    await _refresh_realism_config(repo)  # does not raise
+    # planner unchanged
+    assert planner.current_payload()["canary_probability"] == pytest.approx(0.03)
+
+
+@pytest.mark.asyncio
+async def test_refresh_swallows_malformed_json():
+    repo = AsyncMock()
+    repo.get_realism_config = AsyncMock(return_value={
+        "key": "weights",
+        "value": "not-json",
+    })
+    await _refresh_realism_config(repo)
+    assert planner.current_payload()["canary_probability"] == pytest.approx(0.03)
+
+
+@pytest.mark.asyncio
+async def test_refresh_swallows_invalid_payload():
+    repo = AsyncMock()
+    repo.get_realism_config = AsyncMock(return_value={
+        "key": "weights",
+        "value": json.dumps({"canary_probability": 9.0}),
+    })
+    await _refresh_realism_config(repo)
+    # Planner config not corrupted by a bad refresh.
+    assert planner.current_payload()["canary_probability"] == pytest.approx(0.03)

tests/realism/test_planner_config.py

@@ -0,0 +1,119 @@
+"""Operator-tunable planner knobs (apply_payload / current_payload).
+
+§3c of the realism handoff: the planner reads mutable module globals
+that an admin can override via PUT /api/v1/realism/config. These tests
+pin the validation surface and the payload roundtrip so a regression
+that breaks operator tunables surfaces here, not on a live fleet.
+"""
+from __future__ import annotations
+
+import pytest
+
+from decnet.realism import planner
+from decnet.realism.taxonomy import ContentClass
+
+
+@pytest.fixture(autouse=True)
+def _reset_after_each_test():
+    yield
+    planner.reset_to_defaults()
+
+
+def test_current_payload_returns_defaults_after_reset():
+    planner.reset_to_defaults()
+    payload = planner.current_payload()
+    assert payload["canary_probability"] == pytest.approx(0.03)
+    user = {e["content_class"]: e["weight"] for e in payload["user_class_weights"]}
+    assert user[ContentClass.NOTE.value] == 30
+    assert user[ContentClass.TODO.value] == 20
+
+
+def test_apply_payload_overrides_user_weights():
+    planner.apply_payload({
+        "user_class_weights": [
+            {"content_class": "note", "weight": 5},
+            {"content_class": "todo", "weight": 95},
+        ],
+    })
+    payload = planner.current_payload()
+    weights = {e["content_class"]: e["weight"] for e in payload["user_class_weights"]}
+    assert weights == {"note": 5, "todo": 95}
+    # System weights left untouched by a partial body.
+    assert payload["system_class_weights"]
+
+
+def test_apply_payload_overrides_canary_probability():
+    planner.apply_payload({"canary_probability": 0.15})
+    assert planner.current_payload()["canary_probability"] == pytest.approx(0.15)
+
+
+def test_apply_payload_rejects_bad_canary_probability():
+    with pytest.raises(ValueError, match="canary_probability"):
+        planner.apply_payload({"canary_probability": 1.5})
+    with pytest.raises(ValueError, match="canary_probability"):
+        planner.apply_payload({"canary_probability": -0.1})
+    with pytest.raises(ValueError, match="canary_probability"):
+        planner.apply_payload({"canary_probability": "high"})
+
+
+def test_apply_payload_rejects_negative_weight():
+    with pytest.raises(ValueError, match="non-negative integer"):
+        planner.apply_payload({
+            "user_class_weights": [{"content_class": "note", "weight": -1}],
+        })
+
+
+def test_apply_payload_rejects_unknown_content_class():
+    with pytest.raises(ValueError, match="unknown content_class"):
+        planner.apply_payload({
+            "user_class_weights": [{"content_class": "vibes", "weight": 1}],
+        })
+
+
+def test_apply_payload_drops_class_from_wrong_list():
+    """A canary class on the user list is silently dropped (operator
+    error), not raised — the partial save still applies the legit
+    entries. Roundtrip shows the operator their entry didn't land."""
+    planner.apply_payload({
+        "user_class_weights": [
+            {"content_class": "note", "weight": 10},
+            {"content_class": "canary_aws_creds", "weight": 100},
+        ],
+    })
+    weights = {
+        e["content_class"]: e["weight"]
+        for e in planner.current_payload()["user_class_weights"]
+    }
+    assert weights == {"note": 10}
+    # canary class did NOT bleed onto the user list.
+    assert "canary_aws_creds" not in weights
+
+
+def test_apply_payload_rejects_zero_total_weight():
+    with pytest.raises(ValueError, match="positive number"):
+        planner.apply_payload({
+            "user_class_weights": [{"content_class": "note", "weight": 0}],
+        })
+
+
+def test_apply_payload_partial_failure_leaves_state_intact():
+    """If validation rejects part of a payload, the planner's other
+    fields must not have been silently rebound."""
+    planner.apply_payload({"canary_probability": 0.10})
+    pre = planner.current_payload()
+
+    with pytest.raises(ValueError):
+        planner.apply_payload({
+            "user_class_weights": [{"content_class": "note", "weight": 5}],
+            "canary_probability": 9.0,  # invalid
+        })
+
+    post = planner.current_payload()
+    assert post == pre  # nothing rebound on failure
+
+
+def test_apply_payload_ignores_unknown_keys():
+    """Forward-compat: future fields land without breaking older clients."""
+    planner.apply_payload({"future_knob": "ignored"})
+    # Nothing changed.
+    assert planner.current_payload()["canary_probability"] == pytest.approx(0.03)

tests/realism/test_synthetic_files_repo.py

@@ -152,6 +152,29 @@ async def test_get_synthetic_file_returns_none_when_missing(repo):
     assert await repo.get_synthetic_file("does-not-exist") is None
 
 
+@pytest.mark.asyncio
+async def test_realism_config_get_returns_none_when_unset(repo):
+    assert await repo.get_realism_config("weights") is None
+
+
+@pytest.mark.asyncio
+async def test_realism_config_set_then_get_roundtrips(repo):
+    await repo.set_realism_config("weights", '{"canary_probability": 0.07}')
+    row = await repo.get_realism_config("weights")
+    assert row is not None
+    assert row["key"] == "weights"
+    assert row["value"] == '{"canary_probability": 0.07}'
+
+
+@pytest.mark.asyncio
+async def test_realism_config_set_is_upsert(repo):
+    await repo.set_realism_config("weights", '{"a": 1}')
+    await repo.set_realism_config("weights", '{"a": 2}')
+    row = await repo.get_realism_config("weights")
+    assert row is not None
+    assert row["value"] == '{"a": 2}'
+
+
 def test_path_max_length_fits_mysql_utf8mb4_index_limit():
     """The unique (decky_uuid, path) index has to fit MySQL's 3072-byte
     utf8mb4 cap: (decky_uuid_len + path_len) * 4 <= 3072. A regression