feat(realism): synthetic_files table + planner wiring + scheduler swap

Stage 3 of the realism migration. Replaces orchestrator/scheduler.py's
hardcoded _FILE_TEMPLATES/_USERS (3 templates emitting epoch-suffixed
filenames like notes-1777315854.txt with identical bodies per
template) with a persona-driven realism engine.

New surface:

- SyntheticFile SQLModel (synthetic_files table, UNIQUE on
  decky_uuid+path) — per-(decky, path) state for the future
  edit-in-place flow. Pre-v1, no _migrate_* helper.
- BaseRepository methods: record_synthetic_file,
  update_synthetic_file, list_synthetic_files,
  pick_random_synthetic_file_for_edit (used by stage 3b).
- realism/naming.py: per-content-class filename templates,
  persona-conditioned. /var/log/cron.log + logrotate skeleton for
  system-class; /home/<persona>/TODO.md, scratch.md, etc. for
  user-class. Anti-regression test pins "no 8+ digit decimals in
  basenames" (the realism failure today).
- realism/bodies.py: deterministic body templates per content_class.
  TODO body uses checkbox markdown, script body has a shebang, cron
  body matches syslog cron shape ("CRON[PID]: (user) CMD (...)").
- realism/planner.py: pick(deckies, now, rng) returns a Plan.
  Diurnal-gated, weighted user/system content split (70/30 user
  bias). Create-only in stage 3; edit branch lands in stage 3b.

Scheduler split:

- scheduler.pick is now traffic-only (sync).
- scheduler.pick_file is async, takes a repo, resolves personas
  (Topology.email_personas for topology-source deckies; global
  realism.personas_pool otherwise), and maps Plan -> FileAction.
- FileAction gains persona/content_class/mtime fields.

Worker:

- _one_tick rolls 50/50 between traffic and file each tick. After a
  successful FileAction plant, _record_synthetic_file persists or
  patches the synthetic_files row (catching the unique-constraint
  collision on re-plant of the same path).
- SSHDriver._run_file passes action.mtime through to plant_file so
  files don't all stamp at wall-clock-now.

tests/realism/test_bodies.py

@@ -0,0 +1,68 @@
+"""Body templates produce realistic, non-empty output per content class."""
+from __future__ import annotations
+
+import secrets
+
+import pytest
+
+from decnet.realism.bodies import make_body
+from decnet.realism.taxonomy import ContentClass
+
+
+_INERT_CLASSES = (
+    ContentClass.NOTE,
+    ContentClass.TODO,
+    ContentClass.DRAFT,
+    ContentClass.SCRIPT,
+    ContentClass.LOG_CRON,
+    ContentClass.LOG_DAEMON,
+    ContentClass.CACHE_TMP,
+)
+
+
+@pytest.mark.parametrize("cls", _INERT_CLASSES)
+def test_body_is_nonempty(cls: ContentClass) -> None:
+    body = make_body(cls, "admin", rand=secrets.SystemRandom())
+    assert isinstance(body, str)
+    assert body.strip()
+
+
+def test_todo_body_uses_checkbox_markdown() -> None:
+    body = make_body(ContentClass.TODO, "admin")
+    # Each line should look like a markdown checkbox; we don't pin the
+    # exact distribution because the % checked is randomised.
+    for line in body.strip().splitlines():
+        assert line.startswith("- [")
+
+
+def test_script_body_starts_with_shebang() -> None:
+    seen_shebangs: set[str] = set()
+    rng = secrets.SystemRandom()
+    for _ in range(20):
+        body = make_body(ContentClass.SCRIPT, "admin", rand=rng)
+        assert body.startswith("#!")
+        seen_shebangs.add(body.splitlines()[0])
+    # We should pick from at least two interpreter shebangs across 20
+    # trials; if not, the template list collapsed.
+    assert len(seen_shebangs) >= 2
+
+
+def test_log_cron_body_has_cron_syslog_shape() -> None:
+    body = make_body(ContentClass.LOG_CRON, "admin", rand=secrets.SystemRandom())
+    for line in body.strip().splitlines():
+        assert "CRON[" in line
+        assert "CMD (" in line
+
+
+@pytest.mark.parametrize(
+    "cls",
+    [c for c in ContentClass if c.value.startswith("canary_")],
+)
+def test_canary_classes_raise_in_bodies(cls: ContentClass) -> None:
+    with pytest.raises(NotImplementedError, match="canary"):
+        make_body(cls, "admin")
+
+
+def test_email_class_raises_in_bodies() -> None:
+    with pytest.raises(NotImplementedError, match="email"):
+        make_body(ContentClass.EMAIL, "admin")

tests/realism/test_naming.py

@@ -0,0 +1,95 @@
+"""Filename realism contracts.
+
+The pre-realism orchestrator emitted ``notes-1777315854.txt`` —
+unix-epoch suffix, instant tell.  This file pins the anti-regression:
+no namer is allowed to drop a raw decimal timestamp into a filename.
+"""
+from __future__ import annotations
+
+import re
+import secrets
+
+import pytest
+
+from decnet.realism.naming import make_path
+from decnet.realism.taxonomy import ContentClass
+
+
+_USER_CLASSES = (
+    ContentClass.NOTE,
+    ContentClass.TODO,
+    ContentClass.DRAFT,
+    ContentClass.SCRIPT,
+)
+_SYSTEM_CLASSES = (
+    ContentClass.LOG_CRON,
+    ContentClass.LOG_DAEMON,
+    ContentClass.CACHE_TMP,
+)
+
+
+@pytest.mark.parametrize("cls", _USER_CLASSES)
+def test_user_class_paths_live_under_persona_home(cls: ContentClass) -> None:
+    p = make_path(cls, "admin", rand=secrets.SystemRandom())
+    assert p.startswith("/home/admin/"), p
+
+
+@pytest.mark.parametrize("cls", _SYSTEM_CLASSES)
+def test_system_class_paths_have_no_epoch_suffix(cls: ContentClass) -> None:
+    rng = secrets.SystemRandom()
+    for _ in range(20):
+        p = make_path(cls, "admin", rand=rng)
+        # The realism failure today: filenames carry raw unix epochs.
+        # 8+ consecutive digits in the basename is the tell.
+        basename = p.rsplit("/", 1)[-1]
+        assert not re.search(r"\d{8,}", basename), (
+            f"epoch-shaped suffix found in {p!r}"
+        )
+
+
+def test_log_cron_uses_logrotate_skeleton() -> None:
+    seen: set[str] = set()
+    rng = secrets.SystemRandom()
+    for _ in range(40):
+        seen.add(make_path(ContentClass.LOG_CRON, "admin", rand=rng))
+    # Real cron only ever writes a fixed set of names; anything outside
+    # the logrotate cycle is a realism bug.
+    expected = {"/var/log/cron.log", "/var/log/cron.log.1", "/var/log/cron.log.2.gz"}
+    assert seen <= expected
+    # And we should see at least the canonical name across 40 trials.
+    assert "/var/log/cron.log" in seen
+
+
+def test_cache_tmp_uses_mkstemp_shape() -> None:
+    p = make_path(ContentClass.CACHE_TMP, "admin")
+    assert re.match(r"^/tmp/\.cache-[a-z0-9]{6}$", p), p
+
+
+@pytest.mark.parametrize(
+    "cls",
+    [c for c in ContentClass if c.value.startswith("canary_")],
+)
+def test_canary_classes_raise_in_naming(cls: ContentClass) -> None:
+    with pytest.raises(NotImplementedError, match="canary"):
+        make_path(cls, "admin")
+
+
+def test_email_class_raises_in_naming() -> None:
+    with pytest.raises(NotImplementedError, match="email"):
+        make_path(ContentClass.EMAIL, "admin")
+
+
+def test_persona_with_spaces_normalises_to_login() -> None:
+    # "John Smith" → "johnsmith" is a plausible login, so the namer
+    # collapses spaces rather than falling back. This pins that
+    # behaviour against a future overcorrection.
+    p = make_path(ContentClass.NOTE, "John Smith")
+    assert p.startswith("/home/johnsmith/")
+
+
+def test_persona_with_punctuation_falls_back_to_user_home() -> None:
+    # A persona name with punctuation (or non-ASCII letters) can't
+    # cleanly become a username; the namer must fall back to
+    # /home/user rather than leak weird chars onto the filesystem.
+    p = make_path(ContentClass.NOTE, "C-3PO!")
+    assert p.startswith("/home/user/")

tests/realism/test_planner.py

@@ -0,0 +1,101 @@
+"""Realism planner — picks (decky, persona, class, action, mtime).
+
+Stage 3 ships create-only plans; the edit branch lands in 3b.  Tests
+pin the diurnal gate, the eligibility filter, and the create
+contract.
+"""
+from __future__ import annotations
+
+import random
+from datetime import datetime, timezone
+
+import pytest
+
+from decnet.realism.personas import EmailPersona
+from decnet.realism.planner import pick
+from decnet.realism.taxonomy import ContentClass
+
+
+def _persona(name: str = "admin", window: str = "00:00-00:00") -> EmailPersona:
+    return EmailPersona(
+        name=name,
+        email=f"{name}@corp.com",
+        role="ops",
+        tone="direct",
+        active_hours=window,
+    )
+
+
+def _decky(uuid: str = "u1", name: str = "decky-01", personas=None) -> dict:
+    return {
+        "uuid": uuid,
+        "name": name,
+        "_realism_personas": personas or [_persona()],
+    }
+
+
+_NOW = datetime(2026, 4, 27, 14, 0, tzinfo=timezone.utc)
+
+
+def test_pick_returns_none_when_no_deckies() -> None:
+    assert pick([], _NOW) is None
+
+
+def test_pick_returns_none_when_decky_has_no_personas() -> None:
+    assert pick([{"uuid": "u1", "name": "d", "_realism_personas": []}], _NOW) is None
+
+
+def test_pick_filters_personas_outside_window() -> None:
+    # A persona pegged to 01:00-02:00 with now=14:00 must not be picked.
+    out_of_hours = _persona(window="01:00-02:00")
+    deckies = [_decky(personas=[out_of_hours])]
+    assert pick(deckies, _NOW) is None
+
+
+def test_pick_returns_create_plan_with_mtime_in_past() -> None:
+    deckies = [_decky()]
+    plan = pick(deckies, _NOW, rand=random.Random(0))
+    assert plan is not None
+    assert plan.action == "create"
+    assert plan.decky_uuid == "u1"
+    assert plan.persona == "admin"
+    assert plan.target_path.startswith("/")
+    assert plan.body_hint
+    assert plan.mtime < _NOW
+
+
+def test_pick_distributes_across_user_and_system_classes() -> None:
+    deckies = [_decky()]
+    seen: set[ContentClass] = set()
+    for seed in range(80):
+        plan = pick(deckies, _NOW, rand=random.Random(seed))
+        if plan is not None:
+            seen.add(plan.content_class)
+    # Across 80 seeds we should hit both buckets — at least one user
+    # class and at least one system class — otherwise the weights or
+    # the 70/30 split is broken.
+    user_classes = {c for c in seen if c.is_user_class()}
+    system_classes = {c for c in seen if c.is_system_class()}
+    assert user_classes, f"no user-class plans in 80 trials: {seen}"
+    assert system_classes, f"no system-class plans in 80 trials: {seen}"
+
+
+def test_pick_never_returns_canary_class_in_stage3() -> None:
+    deckies = [_decky()]
+    for seed in range(40):
+        plan = pick(deckies, _NOW, rand=random.Random(seed))
+        if plan is None:
+            continue
+        assert not plan.content_class.is_canary(), (
+            "canary class slipped into the realism planner; cultivator "
+            "lands in stage 7"
+        )
+
+
+def test_pick_persists_persona_window_in_notes() -> None:
+    plan = pick([_decky()], _NOW, rand=random.Random(0))
+    assert plan is not None
+    # The plan's notes carry the persona name and the window — useful
+    # for the dashboard's "why this file" inspector.
+    assert any("persona=admin" in n for n in plan.notes)
+    assert any("window=" in n for n in plan.notes)

tests/realism/test_synthetic_files_repo.py

@@ -0,0 +1,116 @@
+"""record / update / list / pick-for-edit on the synthetic_files table.
+
+Stage 3 of the realism migration introduces the synthetic_files
+table for per-(decky, path) state.  Tests pin the contract on a
+real :class:`SQLiteRepository` so SQLModel schema bugs surface here
+rather than in production.
+"""
+from __future__ import annotations
+
+import hashlib
+from datetime import datetime, timedelta, timezone
+
+import pytest
+import pytest_asyncio
+
+from decnet.web.db.sqlite.repository import SQLiteRepository
+
+
+@pytest_asyncio.fixture
+async def repo(tmp_path):
+    r = SQLiteRepository(db_path=str(tmp_path / "decnet.db"))
+    await r.initialize()
+    yield r
+    await r.engine.dispose()
+
+
+def _row(
+    decky: str = "d1",
+    path: str = "/home/admin/TODO.md",
+    persona: str = "admin",
+    cls: str = "todo",
+    body: str = "- [ ] rotate keys\n",
+    ts: datetime | None = None,
+) -> dict:
+    now = ts or datetime.now(timezone.utc)
+    return {
+        "decky_uuid": decky,
+        "path": path,
+        "persona": persona,
+        "content_class": cls,
+        "created_at": now,
+        "last_modified": now,
+        "edit_count": 0,
+        "content_hash": hashlib.sha256(body.encode()).hexdigest(),
+        "last_body": body,
+    }
+
+
+@pytest.mark.asyncio
+async def test_record_returns_uuid(repo):
+    uuid = await repo.record_synthetic_file(_row())
+    assert isinstance(uuid, str) and uuid
+
+
+@pytest.mark.asyncio
+async def test_unique_constraint_on_decky_path(repo):
+    await repo.record_synthetic_file(_row())
+    with pytest.raises(Exception):
+        await repo.record_synthetic_file(_row())
+
+
+@pytest.mark.asyncio
+async def test_update_synthetic_file_patches_fields(repo):
+    uuid = await repo.record_synthetic_file(_row())
+    await repo.update_synthetic_file(
+        uuid,
+        {"edit_count": 1, "last_body": "- [x] rotate keys\n"},
+    )
+    listing = await repo.list_synthetic_files(decky_uuid="d1")
+    assert len(listing) == 1
+    assert listing[0]["edit_count"] == 1
+    assert listing[0]["last_body"].startswith("- [x]")
+
+
+@pytest.mark.asyncio
+async def test_list_filters_by_decky_and_persona(repo):
+    await repo.record_synthetic_file(_row(decky="d1", path="/a"))
+    await repo.record_synthetic_file(_row(decky="d1", path="/b", persona="ubuntu"))
+    await repo.record_synthetic_file(_row(decky="d2", path="/c"))
+
+    by_decky = await repo.list_synthetic_files(decky_uuid="d1")
+    assert {r["path"] for r in by_decky} == {"/a", "/b"}
+
+    by_persona = await repo.list_synthetic_files(decky_uuid="d1", persona="ubuntu")
+    assert {r["path"] for r in by_persona} == {"/b"}
+
+
+@pytest.mark.asyncio
+async def test_pick_random_returns_none_when_empty(repo):
+    assert await repo.pick_random_synthetic_file_for_edit("d-empty") is None
+
+
+@pytest.mark.asyncio
+async def test_pick_random_excludes_canary_classes(repo):
+    # Canary-class files are stored on the same table (stage 7) but
+    # the editor must skip them — their bodies are binary blobs.
+    await repo.record_synthetic_file(_row(cls="canary_aws_creds"))
+    picked = await repo.pick_random_synthetic_file_for_edit("d1")
+    assert picked is None
+
+
+@pytest.mark.asyncio
+async def test_pick_random_excludes_too_old_rows(repo):
+    old = datetime.now(timezone.utc) - timedelta(days=120)
+    await repo.record_synthetic_file(_row(ts=old))
+    picked = await repo.pick_random_synthetic_file_for_edit("d1", max_age_days=30)
+    assert picked is None
+
+
+@pytest.mark.asyncio
+async def test_pick_random_returns_eligible_row(repo):
+    await repo.record_synthetic_file(_row(cls="todo"))
+    picked = await repo.pick_random_synthetic_file_for_edit("d1")
+    assert picked is not None
+    assert picked["content_class"] == "todo"
+    assert picked["path"] == "/home/admin/TODO.md"