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.

decnet/orchestrator/worker.py

@@ -39,6 +39,7 @@ from decnet.orchestrator.emailgen import (
     scheduler as email_scheduler,
 )
 from decnet.orchestrator.emailgen.scheduler import EmailAction
+from decnet.realism import planner as realism_planner
 from decnet.realism.llm.circuit import LLMCircuitBreaker
 from decnet.web.db.repository import BaseRepository
 
@@ -52,6 +53,12 @@ _PRUNE_EVERY_TICKS = 100
 _PRUNE_PER_DST_CAP = 10000
 _PRUNE_PER_MAIL_DECKY_CAP = 5000
 
+# Refresh planner weights from realism_config every N ticks. Operator
+# tunables drift slowly; ~minute-scale latency between PUT and effect
+# is fine. No bus signal — keeps the path simple and the orchestrator
+# self-contained.
+_REALISM_CONFIG_REFRESH_TICKS = 5
+
 # Action-kind weights for the per-tick roll.  Email is rare because
 # each LLM round-trip is expensive (~seconds) and the prior emailgen
 # worker only ticked every 5 minutes.  At a 60s orchestrator interval,
@@ -115,6 +122,12 @@ async def orchestrator_worker(
         )
         bus = None
 
+    # Initial load — pulls the operator-tuned weights from
+    # realism_config so the orchestrator starts ticking with the
+    # operator's intent rather than the baked-in defaults. A failure
+    # here logs and falls through; the planner already holds defaults.
+    await _refresh_realism_config(repo)
+
     shutdown = asyncio.Event()
     heartbeat_task = asyncio.create_task(
         run_health_heartbeat(
@@ -141,6 +154,8 @@ async def orchestrator_worker(
             tick_n += 1
             if tick_n % _PRUNE_EVERY_TICKS == 0:
                 await _periodic_prune(repo)
+            if tick_n % _REALISM_CONFIG_REFRESH_TICKS == 0:
+                await _refresh_realism_config(repo)
     finally:
         for t in (heartbeat_task, control_task):
             t.cancel()
@@ -174,6 +189,35 @@ async def _periodic_prune(repo: BaseRepository) -> None:
         logger.error("orchestrator emails prune failed: %s", exc)
 
 
+async def _refresh_realism_config(repo: BaseRepository) -> None:
+    """Pull operator-tuned weights from realism_config into the planner.
+
+    Failure modes (DB unreachable, malformed JSON, validation reject)
+    log and leave the planner's current weights in place. The orchestrator
+    keeps ticking with whatever it had — never blocks on config.
+    """
+    try:
+        row = await repo.get_realism_config("weights")
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("realism config refresh: DB read failed: %s", exc)
+        return
+    if row is None:
+        return  # no overrides set; defaults stand
+    import json
+    try:
+        payload = json.loads(row.get("value") or "{}")
+    except json.JSONDecodeError as exc:
+        logger.warning("realism config refresh: malformed JSON: %s", exc)
+        return
+    if not isinstance(payload, dict):
+        logger.warning("realism config refresh: payload not an object")
+        return
+    try:
+        realism_planner.apply_payload(payload)
+    except ValueError as exc:
+        logger.warning("realism config refresh: rejected payload: %s", exc)
+
+
 def _roll_action_kind(rng: secrets.SystemRandom) -> str:
     total = sum(w for _, w in _ACTION_WEIGHTS)
     target = rng.randint(1, total)

decnet/realism/planner.py

@@ -29,27 +29,31 @@ from decnet.realism.personas import EmailPersona
 from decnet.realism.taxonomy import ContentClass, Plan, PlanAction  # noqa: F401
 
 
-# Stage-3 weighted sampling:
+# Stage-3 weighted sampling defaults:
 #   * User content (notes/todo/draft/script) gets the bulk — those are
 #     the realism win when a persona "looks busy."
 #   * System content (cron/daemon/cache) is plausible filler.
 #   * Email + canary are owned by other paths and not picked here.
-_USER_CLASS_WEIGHTS: tuple[tuple[ContentClass, int], ...] = (
+#   * Canary classes are picked rarely. Each plant materialises a real
+#     CanaryToken row + DNS slug + HTTP URL — flooding the fleet makes
+#     the dashboard noisy. ~3% of file picks land here.
+#
+# These are the *defaults*. Operator-tuned overrides arrive via
+# :func:`apply_payload` (admin PUT /api/v1/realism/config). The
+# orchestrator worker periodically refreshes the in-process state from
+# the ``realism_config`` table; pick() reads the live globals each call.
+_DEFAULT_USER_CLASS_WEIGHTS: tuple[tuple[ContentClass, int], ...] = (
     (ContentClass.NOTE, 30),
     (ContentClass.TODO, 20),
     (ContentClass.DRAFT, 15),
     (ContentClass.SCRIPT, 10),
 )
-_SYSTEM_CLASS_WEIGHTS: tuple[tuple[ContentClass, int], ...] = (
+_DEFAULT_SYSTEM_CLASS_WEIGHTS: tuple[tuple[ContentClass, int], ...] = (
     (ContentClass.LOG_CRON, 12),
     (ContentClass.LOG_DAEMON, 8),
     (ContentClass.CACHE_TMP, 5),
 )
-# Canary classes are picked rarely.  Each plant materialises a real
-# CanaryToken row + DNS slug + HTTP URL — flooding the fleet with
-# canaries makes the dashboard noisy and the per-decky alert surface
-# explode.  ~3% of file picks land here.
-_CANARY_CLASS_WEIGHTS: tuple[tuple[ContentClass, int], ...] = (
+_DEFAULT_CANARY_CLASS_WEIGHTS: tuple[tuple[ContentClass, int], ...] = (
     (ContentClass.CANARY_AWS_CREDS, 1),
     (ContentClass.CANARY_ENV_FILE, 1),
     (ContentClass.CANARY_GIT_CONFIG, 1),
@@ -59,7 +63,139 @@ _CANARY_CLASS_WEIGHTS: tuple[tuple[ContentClass, int], ...] = (
     (ContentClass.CANARY_HONEYDOC_PDF, 1),
     (ContentClass.CANARY_MYSQL_DUMP, 1),
 )
-_CANARY_PROBABILITY = 0.03
+_DEFAULT_CANARY_PROBABILITY = 0.03
+
+# Live (mutable) globals — reassigned by :func:`apply_payload`. pick()
+# reads these. Reset to defaults via :func:`reset_to_defaults` (used by
+# tests + the API DELETE path).
+_USER_CLASS_WEIGHTS: tuple[tuple[ContentClass, int], ...] = _DEFAULT_USER_CLASS_WEIGHTS
+_SYSTEM_CLASS_WEIGHTS: tuple[tuple[ContentClass, int], ...] = _DEFAULT_SYSTEM_CLASS_WEIGHTS
+_CANARY_CLASS_WEIGHTS: tuple[tuple[ContentClass, int], ...] = _DEFAULT_CANARY_CLASS_WEIGHTS
+_CANARY_PROBABILITY: float = _DEFAULT_CANARY_PROBABILITY
+
+
+def _serialize_weights(
+    weights: tuple[tuple[ContentClass, int], ...],
+) -> list[dict[str, Any]]:
+    return [{"content_class": cls.value, "weight": w} for cls, w in weights]
+
+
+def _parse_weights(
+    raw: Any, allowed: set[ContentClass],
+) -> tuple[tuple[ContentClass, int], ...]:
+    """Parse ``[{"content_class": "...", "weight": N}, ...]`` into the
+    planner's internal tuple shape. Drops entries whose ``content_class``
+    isn't in *allowed* (defends against an operator pasting in a canary
+    class on the user list, which would skew sampling without the
+    canary-probability gate).
+
+    Raises ``ValueError`` on structural problems (non-list, non-int
+    weight, negative weight, empty result) so the API can return 400.
+    """
+    if not isinstance(raw, list):
+        raise ValueError("weights must be a list")
+    out: list[tuple[ContentClass, int]] = []
+    for entry in raw:
+        if not isinstance(entry, dict):
+            raise ValueError("each weight entry must be an object")
+        cls_name = entry.get("content_class")
+        weight = entry.get("weight")
+        if not isinstance(weight, int) or weight < 0:
+            raise ValueError(
+                f"weight for {cls_name!r} must be a non-negative integer"
+            )
+        try:
+            cls = ContentClass(cls_name)
+        except (ValueError, TypeError):
+            raise ValueError(f"unknown content_class: {cls_name!r}")
+        if cls not in allowed:
+            # Silently drop — a class that doesn't belong on this list
+            # (e.g. a canary class on the user list) is operator error,
+            # but we don't want to fail the whole save over one stray
+            # entry. The roundtrip in current_payload() will show the
+            # operator their entry didn't land.
+            continue
+        out.append((cls, weight))
+    if not out:
+        raise ValueError("weights list resolved to zero valid entries")
+    if sum(w for _, w in out) <= 0:
+        raise ValueError("weights must sum to a positive number")
+    return tuple(out)
+
+
+_USER_CLASSES: set[ContentClass] = {
+    ContentClass.NOTE, ContentClass.TODO, ContentClass.DRAFT, ContentClass.SCRIPT,
+}
+_SYSTEM_CLASSES: set[ContentClass] = {
+    ContentClass.LOG_CRON, ContentClass.LOG_DAEMON, ContentClass.CACHE_TMP,
+}
+_CANARY_CLASSES: set[ContentClass] = {
+    ContentClass.CANARY_AWS_CREDS, ContentClass.CANARY_ENV_FILE,
+    ContentClass.CANARY_GIT_CONFIG, ContentClass.CANARY_SSH_KEY,
+    ContentClass.CANARY_HONEYDOC, ContentClass.CANARY_HONEYDOC_DOCX,
+    ContentClass.CANARY_HONEYDOC_PDF, ContentClass.CANARY_MYSQL_DUMP,
+}
+
+
+def current_payload() -> dict[str, Any]:
+    """Export the live planner config as a JSON-safe dict.
+
+    Wire shape returned by ``GET /api/v1/realism/config``."""
+    return {
+        "user_class_weights": _serialize_weights(_USER_CLASS_WEIGHTS),
+        "system_class_weights": _serialize_weights(_SYSTEM_CLASS_WEIGHTS),
+        "canary_class_weights": _serialize_weights(_CANARY_CLASS_WEIGHTS),
+        "canary_probability": _CANARY_PROBABILITY,
+    }
+
+
+def apply_payload(payload: dict[str, Any]) -> None:
+    """Override the planner's live globals from a wire payload.
+
+    Validates structurally and rebinds module-level names atomically
+    per field — partial failures don't leave the planner in a torn
+    state because validation happens before any rebind.
+
+    Unknown fields are ignored (forward-compat); fields not present
+    leave the corresponding global untouched."""
+    global _USER_CLASS_WEIGHTS, _SYSTEM_CLASS_WEIGHTS
+    global _CANARY_CLASS_WEIGHTS, _CANARY_PROBABILITY
+
+    new_user = _USER_CLASS_WEIGHTS
+    new_system = _SYSTEM_CLASS_WEIGHTS
+    new_canary = _CANARY_CLASS_WEIGHTS
+    new_prob = _CANARY_PROBABILITY
+
+    if "user_class_weights" in payload:
+        new_user = _parse_weights(payload["user_class_weights"], _USER_CLASSES)
+    if "system_class_weights" in payload:
+        new_system = _parse_weights(
+            payload["system_class_weights"], _SYSTEM_CLASSES,
+        )
+    if "canary_class_weights" in payload:
+        new_canary = _parse_weights(
+            payload["canary_class_weights"], _CANARY_CLASSES,
+        )
+    if "canary_probability" in payload:
+        prob = payload["canary_probability"]
+        if not isinstance(prob, (int, float)) or not (0.0 <= prob <= 1.0):
+            raise ValueError("canary_probability must be in [0.0, 1.0]")
+        new_prob = float(prob)
+
+    _USER_CLASS_WEIGHTS = new_user
+    _SYSTEM_CLASS_WEIGHTS = new_system
+    _CANARY_CLASS_WEIGHTS = new_canary
+    _CANARY_PROBABILITY = new_prob
+
+
+def reset_to_defaults() -> None:
+    """Restore hardcoded defaults. Used by tests and the API reset path."""
+    global _USER_CLASS_WEIGHTS, _SYSTEM_CLASS_WEIGHTS
+    global _CANARY_CLASS_WEIGHTS, _CANARY_PROBABILITY
+    _USER_CLASS_WEIGHTS = _DEFAULT_USER_CLASS_WEIGHTS
+    _SYSTEM_CLASS_WEIGHTS = _DEFAULT_SYSTEM_CLASS_WEIGHTS
+    _CANARY_CLASS_WEIGHTS = _DEFAULT_CANARY_CLASS_WEIGHTS
+    _CANARY_PROBABILITY = _DEFAULT_CANARY_PROBABILITY
 
 
 def _weighted_pick(

decnet/web/db/models/__init__.py

@@ -78,6 +78,7 @@ from .orchestrator import (
     OrchestratorEventsResponse,
 )
 from .realism import (
+    RealismConfig,
     SyntheticFile,
     SyntheticFilesResponse,
 )
@@ -231,6 +232,7 @@ __all__ = [
     "OrchestratorEvent",
     "OrchestratorEventsResponse",
     # realism
+    "RealismConfig",
     "SyntheticFile",
     "SyntheticFilesResponse",
     # logs

decnet/web/db/models/realism.py

@@ -83,3 +83,25 @@ class SyntheticFilesResponse(BaseModel):
     limit: int
     offset: int
     data: List[dict[str, Any]]
+
+
+class RealismConfig(SQLModel, table=True):
+    """Operator-tunable realism knobs.
+
+    Single-row-per-key schema: each row carries one piece of operator
+    config (today: ``key="weights"`` → JSON encoding the planner's
+    user/system/canary weights and canary probability). The planner
+    reads in-memory module globals; the orchestrator worker refreshes
+    those globals from this table on a periodic tick.
+
+    UUID PK + unique key per ``feedback_uuid_over_natural_keys.md``.
+    """
+    __tablename__ = "realism_config"
+    uuid: str = Field(default_factory=lambda: str(uuid4()), primary_key=True)
+    key: str = Field(max_length=64, unique=True, index=True)
+    value: str = Field(
+        sa_column=Column("value", Text, nullable=False, default="{}"),
+    )
+    updated_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+    )

decnet/web/db/repository.py

@@ -1159,6 +1159,28 @@ class BaseRepository(ABC):
         """Single synthetic_files row by uuid, or ``None``."""
         raise NotImplementedError
 
+    async def get_realism_config(
+        self, key: str,
+    ) -> Optional[dict[str, Any]]:
+        """Read one ``realism_config`` row by key.
+
+        Today only ``key="weights"`` is used; the schema is
+        single-row-per-key so future tunables can land without a new
+        table. Returns ``None`` when the key has never been set —
+        callers fall back to hardcoded defaults in
+        :mod:`decnet.realism.planner`.
+        """
+        raise NotImplementedError
+
+    async def set_realism_config(
+        self, key: str, value: str,
+    ) -> None:
+        """Upsert one ``realism_config`` row. Last-write-wins.
+
+        *value* is opaque JSON text; validation belongs to the API
+        layer (the planner only reads what landed)."""
+        raise NotImplementedError
+
     async def pick_random_synthetic_file_for_edit(
         self,
         decky_uuid: str,

decnet/web/db/sqlmodel_repo.py

@@ -53,6 +53,7 @@ from decnet.web.db.models import (
     TopologyMutation,
     OrchestratorEmail,
     OrchestratorEvent,
+    RealismConfig,
     SyntheticFile,
     WebhookSubscription,
     CanaryBlob,
@@ -3415,6 +3416,39 @@ class SQLModelRepository(BaseRepository):
                 return None
             return row.model_dump(mode="json")
 
+    async def get_realism_config(
+        self, key: str,
+    ) -> Optional[dict[str, Any]]:
+        async with self._session() as session:
+            stmt = select(RealismConfig).where(RealismConfig.key == key)
+            result = await session.execute(stmt)
+            row = result.scalars().first()
+            if row is None:
+                return None
+            return row.model_dump(mode="json")
+
+    async def set_realism_config(
+        self, key: str, value: str,
+    ) -> None:
+        """Upsert one realism_config row. Last-write-wins."""
+        async with self._session() as session:
+            stmt = select(RealismConfig).where(RealismConfig.key == key)
+            result = await session.execute(stmt)
+            row = result.scalars().first()
+            if row is None:
+                session.add(RealismConfig(
+                    key=key, value=value,
+                    updated_at=datetime.now(timezone.utc),
+                ))
+            else:
+                upd = (
+                    update(RealismConfig)
+                    .where(RealismConfig.uuid == row.uuid)
+                    .values(value=value, updated_at=datetime.now(timezone.utc))
+                )
+                await session.execute(upd)
+            await session.commit()
+
     async def pick_random_synthetic_file_for_edit(
         self,
         decky_uuid: str,

decnet/web/router/__init__.py

@@ -31,6 +31,7 @@ from .campaigns.api_list_campaign_identities import router as campaign_identitie
 from .campaigns.api_events import router as campaign_events_router
 from .orchestrator.api_list_events import router as orchestrator_list_router
 from .orchestrator.api_events import router as orchestrator_events_router
+from .realism.api_config import router as realism_config_router
 from .realism.api_personas import router as realism_personas_router
 from .realism.api_synthetic_files import router as realism_synthetic_files_router
 from .transcripts import transcripts_router
@@ -117,6 +118,7 @@ api_router.include_router(orchestrator_events_router)
 # on-disk JSON file directly (see decnet.realism.personas_pool).
 api_router.include_router(realism_personas_router)
 api_router.include_router(realism_synthetic_files_router)
+api_router.include_router(realism_config_router)
 
 # Observability
 api_router.include_router(stats_router)

decnet/web/router/realism/api_config.py

@@ -0,0 +1,115 @@
+"""GET/PUT ``/api/v1/realism/config`` — operator-tunable realism knobs.
+
+Today only the planner's content-class weights + canary probability
+are exposed. The wire shape mirrors what
+:func:`decnet.realism.planner.current_payload` produces and
+:func:`decnet.realism.planner.apply_payload` consumes.
+
+Reads accept viewer; writes are admin (writes mutate sampling
+behaviour across the whole orchestrator fleet, same trust level as
+the persona-pool surface).
+
+The orchestrator worker periodically re-loads from the
+``realism_config`` table; the API process applies overrides locally
+on PUT so the GET-after-PUT round-trip reflects the change without
+waiting for the orchestrator's next refresh tick.
+"""
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from decnet.logging import get_logger
+from decnet.realism import planner
+from decnet.telemetry import traced as _traced
+from decnet.web.dependencies import repo, require_admin, require_viewer
+
+router = APIRouter()
+log = get_logger("api.realism.config")
+
+_CONFIG_KEY = "weights"
+
+
+@router.get(
+    "/realism/config",
+    tags=["Realism"],
+    responses={
+        401: {"description": "Could not validate credentials"},
+        403: {"description": "Insufficient permissions"},
+    },
+)
+@_traced("api.realism.get_config")
+async def get_config(
+    user: dict = Depends(require_viewer),
+) -> dict[str, Any]:
+    """Return the live planner config in this API process.
+
+    Note: the API process and the orchestrator worker each carry their
+    own in-memory copy of the planner config. After a fresh API
+    restart the ``realism_config`` row is loaded into this process the
+    first time GET is called; subsequent reads are local.
+    """
+    # Lazy hydration — first call after restart pulls from DB so the
+    # admin sees what the orchestrator is actually using, not the
+    # baked-in defaults.
+    row = await repo.get_realism_config(_CONFIG_KEY)
+    if row is not None:
+        try:
+            stored = json.loads(row.get("value") or "{}")
+            if isinstance(stored, dict):
+                planner.apply_payload(stored)
+        except (json.JSONDecodeError, ValueError) as exc:
+            log.warning(
+                "api.realism.get_config: stored payload invalid, "
+                "serving defaults: %s", exc,
+            )
+    return planner.current_payload()
+
+
+@router.put(
+    "/realism/config",
+    tags=["Realism"],
+    responses={
+        400: {"description": "Invalid config payload"},
+        401: {"description": "Could not validate credentials"},
+        403: {"description": "Insufficient permissions"},
+    },
+)
+@_traced("api.realism.put_config")
+async def put_config(
+    body: dict[str, Any],
+    user: dict = Depends(require_admin),
+) -> dict[str, Any]:
+    """Replace (partial) planner config and persist to ``realism_config``.
+
+    Body shape (all fields optional — unset fields keep current value):
+
+    * ``user_class_weights``: ``[{"content_class": "note", "weight": 30}, ...]``
+    * ``system_class_weights``: same shape
+    * ``canary_class_weights``: same shape
+    * ``canary_probability``: float in [0.0, 1.0]
+
+    Validation: any structural failure raises 400 *before* the rebind,
+    so the live config never goes torn.
+    """
+    if not isinstance(body, dict):
+        raise HTTPException(status_code=400, detail="body must be an object")
+
+    try:
+        planner.apply_payload(body)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    # Persist what the planner now reflects (keeps DB in sync with the
+    # in-memory state — partial bodies merge into prior config).
+    snapshot = planner.current_payload()
+    await repo.set_realism_config(_CONFIG_KEY, json.dumps(snapshot))
+
+    log.info(
+        "api.realism.put_config user=%s canary_probability=%.4f",
+        user.get("username", user.get("uuid")),
+        snapshot["canary_probability"],
+    )
+    return snapshot

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