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/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