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,