refactor(realism): move emailgen LLM/personas/prompt into shared library

Lift the format-agnostic pieces from decnet/orchestrator/emailgen/
into the new decnet/realism/ library so file-class content generation
(stage 3 of the realism migration) can reuse them. Email-specific
delivery (RFC 2822 EML, IMAP/POP3 spool, thread chains) stays in
orchestrator/.

Renames (history-preserving git mv):
  emailgen/personas.py     -> realism/personas.py
  emailgen/prompt.py       -> realism/prompts/email.py
  emailgen/global_pool.py  -> realism/personas_pool.py
  emailgen/llm/            -> realism/llm/

Env-var clean break (pre-v1, no aliases):
  DECNET_EMAILGEN_LLM      -> DECNET_REALISM_LLM
  DECNET_EMAILGEN_MODEL    -> DECNET_REALISM_MODEL
  DECNET_EMAILGEN_TIMEOUT  -> DECNET_REALISM_TIMEOUT
  DECNET_EMAILGEN_PERSONAS -> DECNET_REALISM_PERSONAS
  DECNET_EMAILGEN_FAKE_OUTPUT -> DECNET_REALISM_FAKE_OUTPUT

Importers rewritten in: orchestrator/emailgen/scheduler.py,
orchestrator/drivers/email.py, web/router/{emailgen,topology}/
api_personas.py, cli/emailgen.py. Tests for moved modules relocated
to tests/realism/; tests for stay-put modules updated in place.

API URL `/api/v1/emailgen/personas` and CLI `decnet emailgen
import-personas` keep their public names until the service-collapse
commit (stage 5).

decnet/realism/__init__.py

@@ -13,8 +13,8 @@ import from here.  This package owns:
   ``mtime`` sampler so planted files don't all stamp at wall-clock-now.
 * :mod:`decnet.realism.planner` — picks ``(decky, persona, class,
   action, mtime)`` tuples for the orchestrator's tick loop.
-* :mod:`decnet.realism.personas` — persona schema (lifted from
-  ``orchestrator.emailgen.personas`` in stage 2 of the migration).
+* :mod:`decnet.realism.personas` — persona schema (the
+  :class:`EmailPersona` record describing each fictional employee).
 * :mod:`decnet.realism.prompts` — prompt builders, one per content
   class, sharing an em-dash-suppression style helper.
 * :mod:`decnet.realism.llm` — :class:`LLMBackend` ABC + factory + impl

decnet/realism/diurnal.py

@@ -38,8 +38,7 @@ def _parse_window(window: str) -> tuple[int, int, int, int] | None:
 
     Returns ``None`` for malformed input — callers treat that as
     "always-on" so a single config typo never silences the whole fleet
-    (mirrors :func:`decnet.orchestrator.emailgen.personas.in_active_hours`
-    semantics).
+    (mirrors :func:`decnet.realism.personas.in_active_hours` semantics).
     """
     try:
         start_s, end_s = window.split("-")

decnet/realism/llm/__init__.py

@@ -1,8 +1,17 @@
-"""LLM backend ABC + factory + impls.
+"""LLM backend for the realism library.
 
-Populated in stage 2 of the realism migration: lifts the existing
-``orchestrator.emailgen.llm`` subpackage as-is (``base``, ``factory``,
-``impl/ollama``, ``impl/fake``).  Stage 6 adds ``circuit.py`` for
-cross-call breaker behaviour.
+Pluggable per the provider-subpackages convention (mirrors
+:mod:`decnet.web.db` and :mod:`decnet.bus`): consumers depend on
+:class:`LLMBackend` from :mod:`base`; concrete transports live under
+:mod:`impl` and are selected by :func:`get_llm`.
+
+This is the seam to pull on when swapping local Ollama for the
+Anthropic API, llama.cpp, vLLM, or any other inference server — change
+``DECNET_REALISM_LLM`` (or pass ``llm=`` directly), no caller rewrite.
 """
 from __future__ import annotations
+
+from decnet.realism.llm.base import LLMBackend, LLMResult, LLMTimeout
+from decnet.realism.llm.factory import get_llm
+
+__all__ = ["LLMBackend", "LLMResult", "LLMTimeout", "get_llm"]

decnet/realism/llm/base.py

@@ -0,0 +1,47 @@
+"""Backend protocol shared by every LLM transport.
+
+Deliberately narrow: realism consumers need one async ``generate``
+call that takes a prompt string and returns the model's output text
+plus enough metadata to populate per-event payloads (model name,
+latency, success bit).  Streaming, embeddings, multi-turn chat — all
+out of scope here; realism only ever does one-shot single-prompt
+generations.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+
+class LLMTimeout(Exception):
+    """Raised when a generation exceeds the backend's wall-clock cap.
+
+    Backends MUST raise this rather than returning silently empty
+    output; the driver discriminates timeout from "model produced
+    nothing useful" so payloads carry the right ``stage`` value.
+    """
+
+
+@dataclass
+class LLMResult:
+    """Outcome of one ``generate`` call.
+
+    ``success`` is ``False`` when the backend ran cleanly but produced
+    no usable output (e.g. an empty stdout).  Hard failures (subprocess
+    crash, network error) raise; soft failures land here so the driver
+    can persist + log them as one event.
+    """
+    success: bool
+    text: str
+    model: str
+    latency_ms: int
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+class LLMBackend(Protocol):
+    """Minimal contract for a realism LLM provider."""
+
+    model: str
+    timeout: float
+
+    async def generate(self, prompt: str) -> LLMResult: ...

decnet/realism/llm/factory.py

@@ -0,0 +1,46 @@
+"""Backend dispatch.
+
+Reads ``DECNET_REALISM_LLM`` to pick a concrete :class:`LLMBackend`.
+Defaults to ``ollama`` because that's what the prototype proved out and
+what most dev boxes have on hand.
+
+Supported keys:
+
+* ``ollama`` — :class:`decnet.realism.llm.impl.ollama.OllamaBackend`
+* ``fake``   — :class:`decnet.realism.llm.impl.fake.FakeBackend`
+  (canned output, used by tests so they don't shell out)
+
+Anthropic / vLLM / llama.cpp slots in here as a third branch when the
+need shows up.  Per the provider-subpackages convention, do NOT collapse
+factory dispatch into the impl modules — keeps the ``__init__`` import
+graph cycle-free and the env contract auditable in one place.
+"""
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from decnet.realism.llm.base import LLMBackend
+
+
+def get_llm(*, model: str | None = None, **kwargs: Any) -> LLMBackend:
+    """Instantiate the LLM backend selected by environment.
+
+    *model* (when provided) overrides whatever the backend's own default
+    is — e.g. for :class:`OllamaBackend` that's ``llama3.1`` unless
+    ``DECNET_REALISM_MODEL`` says otherwise.  Lets the worker honour
+    ``decnet orchestrate --model gpt-oss`` without each backend having
+    to know about CLI flags.
+    """
+    backend_key = os.environ.get("DECNET_REALISM_LLM", "ollama").lower()
+
+    if backend_key == "ollama":
+        from decnet.realism.llm.impl.ollama import OllamaBackend
+        return OllamaBackend(model=model, **kwargs)
+    if backend_key == "fake":
+        from decnet.realism.llm.impl.fake import FakeBackend
+        return FakeBackend(model=model or "fake-model", **kwargs)
+    raise ValueError(
+        f"Unsupported DECNET_REALISM_LLM={backend_key!r}; "
+        "expected one of: ollama, fake"
+    )

decnet/realism/llm/impl/__init__.py

@@ -0,0 +1,6 @@
+"""Concrete LLM-backend implementations.
+
+Importers go through :func:`decnet.realism.llm.get_llm`, not these
+modules directly — same convention as :mod:`decnet.web.db.sqlite` and
+:mod:`decnet.bus.unix_client`.
+"""

decnet/realism/llm/impl/fake.py

@@ -0,0 +1,50 @@
+"""In-process fake backend for tests.
+
+Returns a canned string so the driver path can be exercised without an
+Ollama install.  Configurable via ``DECNET_REALISM_FAKE_OUTPUT`` (env)
+or the ``output`` constructor arg — the env-var path lets integration
+tests run the worker end-to-end with deterministic output.
+"""
+from __future__ import annotations
+
+import os
+import time
+from typing import Optional
+
+from decnet.realism.llm.base import LLMBackend, LLMResult
+
+
+_DEFAULT_OUTPUT = (
+    "Subject: Quick update\n\n"
+    "Hi,\n\nFollowing up on the topic.\n\nBest regards,\nFake Persona\n"
+)
+
+
+class FakeBackend(LLMBackend):
+    def __init__(
+        self,
+        *,
+        model: str = "fake-model",
+        timeout: float = 1.0,
+        output: Optional[str] = None,
+        success: bool = True,
+    ) -> None:
+        self.model = model
+        self.timeout = timeout
+        self._output = (
+            output
+            if output is not None
+            else os.environ.get("DECNET_REALISM_FAKE_OUTPUT", _DEFAULT_OUTPUT)
+        )
+        self._success = success
+
+    async def generate(self, prompt: str) -> LLMResult:    # noqa: ARG002
+        t0 = time.monotonic()
+        latency_ms = int((time.monotonic() - t0) * 1000)
+        return LLMResult(
+            success=self._success,
+            text=self._output if self._success else "",
+            model=self.model,
+            latency_ms=latency_ms,
+            extra={"rc": 0 if self._success else 1},
+        )

decnet/realism/llm/impl/ollama.py

@@ -0,0 +1,100 @@
+"""Ollama subprocess backend.
+
+Shells out to ``ollama run <model>`` with the prompt fed via stdin.
+
+Why subprocess and not the Ollama HTTP API:
+* No new dependency (``ollama`` Python lib is optional).
+* Works on hosts where Ollama is bound to a unix socket, an unusual TCP
+  port, or behind a remote-mount layer — `ollama run` resolves all that.
+* Same path the operator uses by hand (``ollama run llama3.1``); easier
+  to debug discrepancies between worker output and a console session.
+
+Cost: per-call process spawn (~50ms on a warm box).  Acceptable for
+realism tick rates (one body per ~5 minutes per persona by default).
+When that cost matters, swap to an HTTP-API backend; the seam is in
+:mod:`decnet.realism.llm.factory`.
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from typing import Optional
+
+from decnet.logging import get_logger
+from decnet.realism.llm.base import LLMBackend, LLMResult, LLMTimeout
+
+log = get_logger("realism.llm")
+
+_OLLAMA = "ollama"
+_DEFAULT_MODEL = os.environ.get("DECNET_REALISM_MODEL", "llama3.1")
+_DEFAULT_TIMEOUT = float(os.environ.get("DECNET_REALISM_TIMEOUT", "60"))
+
+
+class OllamaBackend(LLMBackend):
+    """Concrete :class:`LLMBackend` that shells out to ``ollama run``."""
+
+    def __init__(
+        self,
+        *,
+        model: Optional[str] = None,
+        timeout: Optional[float] = None,
+    ) -> None:
+        self.model = model or _DEFAULT_MODEL
+        self.timeout = timeout if timeout is not None else _DEFAULT_TIMEOUT
+
+    async def generate(self, prompt: str) -> LLMResult:
+        t0 = time.monotonic()
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                _OLLAMA, "run", self.model,
+                stdin=asyncio.subprocess.PIPE,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+        except FileNotFoundError as exc:
+            latency_ms = int((time.monotonic() - t0) * 1000)
+            return LLMResult(
+                success=False,
+                text="",
+                model=self.model,
+                latency_ms=latency_ms,
+                extra={"rc": 127, "stderr": f"argv[0] not found: {exc}"},
+            )
+        try:
+            stdout, stderr = await asyncio.wait_for(
+                proc.communicate(prompt.encode("utf-8")),
+                timeout=self.timeout,
+            )
+        except asyncio.TimeoutError as exc:
+            try:
+                proc.kill()
+            except ProcessLookupError:
+                pass
+            raise LLMTimeout(
+                f"ollama run {self.model} exceeded {self.timeout}s"
+            ) from exc
+
+        latency_ms = int((time.monotonic() - t0) * 1000)
+        rc = proc.returncode if proc.returncode is not None else -1
+        text = stdout.decode("utf-8", "replace")
+        stderr_s = stderr.decode("utf-8", "replace")
+        if rc != 0 or not text.strip():
+            log.warning(
+                "ollama backend non-zero / empty rc=%d model=%s stderr=%r",
+                rc, self.model, stderr_s[:200],
+            )
+            return LLMResult(
+                success=False,
+                text=text,
+                model=self.model,
+                latency_ms=latency_ms,
+                extra={"rc": rc, "stderr": stderr_s.strip()[:256]},
+            )
+        return LLMResult(
+            success=True,
+            text=text,
+            model=self.model,
+            latency_ms=latency_ms,
+            extra={"rc": rc},
+        )

decnet/realism/personas.py

@@ -1,9 +1,138 @@
-"""Persona schema — placeholder for stage 2.
+"""Persona schema for realism content generation.
 
-In stage 2 of the realism migration, this module receives the real
-persona schema currently living at
-``decnet.orchestrator.emailgen.personas`` (``EmailPersona``,
-``parse_personas``, ``in_active_hours``).  Stage 1 keeps it empty so
-the import path is reserved without behaviour.
+Stored as a JSON list on :attr:`Topology.email_personas`.  Each persona
+describes one fictional employee — sender of email *and* author of
+files (notes, TODOs, drafts, scripts) on the deckies they're sampled
+onto.  The schema deliberately stays narrow: the LLM gets *enough*
+differentiation to write distinct voices, no more.
+
+The class is still named :class:`EmailPersona` because every persona
+in the pool today carries a mandatory email address (used for IMAP/
+POP3 spool delivery).  Future per-decky personas without mailboxes
+would justify a rename / superclass; not in scope for the realism
+migration.
+
+Invalid entries are dropped with a warning (returned alongside the
+parsed list) rather than raising — a single typo in one persona must
+not stall the entire realism tick.
 """
 from __future__ import annotations
+
+import json
+from typing import Literal, Optional
+
+from pydantic import BaseModel, Field, ValidationError, field_validator, model_validator
+
+from decnet.logging import get_logger
+
+logger = get_logger("realism.personas")
+
+Tone = Literal["formal", "direct", "casual", "technical", "custom"]
+ReplyLatency = Literal["fast", "normal", "slow"]
+
+
+class EmailPersona(BaseModel):
+    """One fake mailbox owner.
+
+    ``language`` is ISO 639-1 (``en``, ``es``, ``pt``…); when unset on the
+    persona it falls back to the topology's ``language_default``.
+    ``uses_llms_heavily`` lifts the prompt-layer em-dash suppression for
+    that persona — em-dashes are an LLM tell, but a persona explicitly
+    pegged as a heavy LLM user should *naturally* produce them.
+    """
+    name: str = Field(min_length=1, max_length=128)
+    email: str = Field(min_length=3, max_length=255)
+    role: str = Field(min_length=1, max_length=128)
+    tone: Tone = "formal"
+    tone_custom: Optional[str] = Field(default=None, max_length=128)
+    mannerisms: list[str] = Field(default_factory=list, max_length=12)
+    language: Optional[str] = Field(default=None, max_length=8)
+    signature: Optional[str] = Field(default=None, max_length=512)
+    active_hours: str = Field(default="09:00-18:00", max_length=32)
+    reply_latency: ReplyLatency = "normal"
+    uses_llms_heavily: bool = False
+
+    @model_validator(mode="after")
+    def _custom_tone_requires_text(self) -> "EmailPersona":
+        # ``tone="custom"`` lets operators describe a voice the four canned
+        # tones don't capture (sarcastic, deadpan, terse, etc.).  The free
+        # text is interpolated into the prompt verbatim, so an empty
+        # value would just leave the LLM with the literal word "custom" —
+        # reject it loudly instead of silently producing a useless prompt.
+        if self.tone == "custom" and not (self.tone_custom and self.tone_custom.strip()):
+            raise ValueError("tone_custom is required when tone is 'custom'")
+        return self
+
+    @field_validator("email")
+    @classmethod
+    def _email_shape(cls, v: str) -> str:
+        # Cheap structural check — full RFC 5322 isn't worth the
+        # dependency.  We only need ``user@domain`` with non-empty parts
+        # for the prompt builder + Message-ID generator.
+        if "@" not in v:
+            raise ValueError("email must contain '@'")
+        local, _, domain = v.rpartition("@")
+        if not local or not domain or "." not in domain:
+            raise ValueError("email must look like user@domain.tld")
+        return v
+
+
+def parse_personas(
+    raw: str | list | None,
+    *,
+    language_default: str = "en",
+) -> list[EmailPersona]:
+    """Parse the JSON-or-list ``email_personas`` value into models.
+
+    Resolves ``language`` against *language_default* so downstream
+    consumers (prompt builder, scheduler) never need to know about
+    fallback semantics.
+    """
+    if not raw:
+        return []
+    if isinstance(raw, str):
+        try:
+            raw = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            logger.warning("realism personas: invalid JSON, skipping: %s", exc)
+            return []
+    if not isinstance(raw, list):
+        logger.warning(
+            "realism personas: expected list, got %s", type(raw).__name__
+        )
+        return []
+    out: list[EmailPersona] = []
+    for i, entry in enumerate(raw):
+        try:
+            persona = EmailPersona.model_validate(entry)
+        except ValidationError as exc:
+            logger.warning(
+                "realism personas: dropping invalid entry index=%d: %s",
+                i, exc.errors(include_url=False),
+            )
+            continue
+        if persona.language is None:
+            persona = persona.model_copy(update={"language": language_default})
+        out.append(persona)
+    return out
+
+
+def in_active_hours(persona: EmailPersona, now_hour: int) -> bool:
+    """Return True if *now_hour* (0–23) falls in the persona's window.
+
+    Format: ``"HH:MM-HH:MM"``. Wrap-around windows (``"22:00-06:00"``)
+    are supported. Invalid windows treat the persona as always-on so a
+    config typo never silences the whole fleet.
+    """
+    try:
+        start_s, end_s = persona.active_hours.split("-")
+        start_h = int(start_s.split(":")[0])
+        end_h = int(end_s.split(":")[0])
+    except (ValueError, IndexError):
+        return True
+    if start_h == end_h:
+        return True
+    if start_h < end_h:
+        return start_h <= now_hour < end_h
+    # Wrap-around (e.g. 22:00-06:00).
+    return now_hour >= start_h or now_hour < end_h

decnet/realism/personas_pool.py

@@ -0,0 +1,145 @@
+"""Global persona pool — non-topology deckies.
+
+DECNET runs in three deployment shapes that emit running deckies:
+
+* **MazeNET topologies**       — each topology owns its own
+  :attr:`Topology.email_personas` JSON list; consumers walk from the
+  decky back to its parent topology row.
+* **Unihost fleet**            — MACVLAN/IPVLAN deckies that have no
+  parent topology row at all.  They share one host-wide pool.
+* **SWARM shards**             — DeckyShard rows on enrolled workers.
+  Same shape as fleet for realism purposes (no parent topology row),
+  so they read the same global pool.
+
+This module owns the global pool: a JSON file on disk that operators
+populate via ``decnet realism import-personas <file>`` (or by editing
+the file directly).  The file is loaded lazily on first read and
+re-loaded on mtime change so a CLI import takes effect for the running
+worker without a restart.
+
+Path resolution order:
+
+1. ``DECNET_REALISM_PERSONAS`` environment variable — explicit override.
+2. ``/etc/decnet/email_personas.json`` — canonical master path; this is
+   what ``decnet init`` will eventually own.  Filename retained
+   (``email_personas.json``) because the on-disk schema hasn't changed
+   and operators may already have committed copies.
+3. ``~/.decnet/email_personas.json`` — dev fallback so a developer can
+   exercise consumers without root or ``decnet init``.
+
+When the file is missing / empty / unparseable, the pool is empty and
+consumers skip fleet/shard deckies the same way they skip a topology
+with too few personas.  No silent fallback to dummy personas; silence
+is correct when there's no opinion to convey.
+"""
+from __future__ import annotations
+
+import os
+import threading
+from pathlib import Path
+from typing import Optional
+
+from decnet.logging import get_logger
+from decnet.realism.personas import EmailPersona, parse_personas
+
+logger = get_logger("realism.personas_pool")
+
+_ENV_VAR = "DECNET_REALISM_PERSONAS"
+_SYSTEM_PATH = Path("/etc/decnet/email_personas.json")
+
+
+def _user_path() -> Path:
+    return Path(os.path.expanduser("~/.decnet/email_personas.json"))
+
+
+def resolve_path() -> Path:
+    """Return the path the global pool would load from right now.
+
+    The file may not exist; callers are expected to handle that.  The
+    function is pure (no I/O) so the ``decnet realism import-personas``
+    CLI can ask "where would I write to?" without touching the disk.
+    """
+    override = os.environ.get(_ENV_VAR, "").strip()
+    if override:
+        return Path(override)
+    if _SYSTEM_PATH.exists():
+        return _SYSTEM_PATH
+    # ``/etc/decnet`` exists on a fully-provisioned host (post ``decnet
+    # init``) but may be read-only for the API user on dev boxes — fall
+    # back to the user path when the directory isn't writable so a fresh
+    # PUT lands somewhere instead of erroring out.  We only do this when
+    # the system file doesn't exist yet; once it does, it's authoritative.
+    if _SYSTEM_PATH.parent.exists() and os.access(_SYSTEM_PATH.parent, os.W_OK):
+        return _SYSTEM_PATH
+    return _user_path()
+
+
+# ── Cache ────────────────────────────────────────────────────────────────────
+# Lock-protected because two scheduler ticks could race on the first load,
+# and the read path is hot enough (every tick, every fleet/shard mail
+# decky) that re-parsing on every call is wasteful.
+
+_lock = threading.Lock()
+_cache: list[EmailPersona] = []
+_cache_path: Optional[Path] = None
+_cache_mtime: float = 0.0
+
+
+def load(*, language_default: str = "en") -> list[EmailPersona]:
+    """Return the parsed global persona pool.
+
+    *language_default* fills in any persona missing a ``language`` field;
+    fleet/shard sources have no topology-level default, so callers
+    should pass the worker's best guess (typically ``"en"``).
+
+    Threadsafe and cheap on the steady state (mtime check + dict lookup);
+    expensive only when the file changed since the last call.
+    """
+    path = resolve_path()
+    try:
+        st = path.stat()
+    except OSError:
+        with _lock:
+            global _cache, _cache_path, _cache_mtime
+            _cache = []
+            _cache_path = path
+            _cache_mtime = 0.0
+        return []
+
+    with _lock:
+        if (
+            _cache_path == path
+            and _cache_mtime == st.st_mtime
+            and _cache  # non-empty cache; empty re-parses cheaply anyway
+        ):
+            return _cache
+
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        logger.warning("realism global pool: read failed path=%s: %s", path, exc)
+        return []
+
+    parsed = parse_personas(raw, language_default=language_default)
+    with _lock:
+        _cache = parsed
+        _cache_path = path
+        _cache_mtime = st.st_mtime
+    if parsed:
+        logger.info(
+            "realism global pool: loaded %d personas from %s", len(parsed), path,
+        )
+    return parsed
+
+
+def reset_cache() -> None:
+    """Clear the in-process cache.
+
+    Test-only helper — avoids stale state when several tests in the
+    same process exercise different on-disk pools.
+    """
+    global _cache, _cache_path, _cache_mtime
+    with _lock:
+        _cache = []
+        _cache_path = None
+        _cache_mtime = 0.0

decnet/realism/prompts/__init__.py

@@ -1,7 +1,9 @@
 """Prompt builders for LLM-enriched content.
 
-Populated in stage 2 (``email.py`` lifted from
-``orchestrator.emailgen.prompt``) and stage 6 (``filebody.py``,
-``filename.py``, ``_style.py`` for em-dash suppression).
+* :mod:`decnet.realism.prompts.email` — corporate-email body builder.
+
+Stage 6 of the realism migration adds ``filebody.py``, ``filename.py``,
+and a ``_style.py`` helper so em-dash suppression sits in one place
+across email + file-class prompts.
 """
 from __future__ import annotations

decnet/realism/prompts/email.py

@@ -0,0 +1,154 @@
+"""Prompt builder for the email content class.
+
+The LLM gets a tightly-scoped instruction and a small handful of
+deterministic constraints.  Persona mannerisms are *pre-selected* in
+Python (1–2 of the persona's full list) and injected as hard rules —
+small models otherwise treat the mannerism list as flavour text and
+ignore it, and the corpus collapses into one voice.
+
+**Em-dash suppression** is on by default; suppression is lifted only
+for personas that opt in via ``uses_llms_heavily``.  Em-dashes are a
+strong stylometric tell for LLM-authored prose, and a honeypot mailbox
+where every author uses them is a tell.  Stage 6 of the realism
+migration extracts the suppression block into a shared
+``decnet.realism.prompts._style`` helper so file-class prompts pick
+it up too.
+"""
+from __future__ import annotations
+
+import secrets
+from dataclasses import dataclass
+from typing import Optional
+
+from decnet.realism.personas import EmailPersona
+
+
+@dataclass(frozen=True)
+class PromptInputs:
+    sender: EmailPersona
+    recipient: EmailPersona
+    context_hint: str
+    parent_subject: Optional[str] = None      # set when replying
+    parent_excerpt: Optional[str] = None      # short snippet of last msg
+
+
+_LANGUAGE_NAMES = {
+    "en": "English",
+    "es": "Spanish",
+    "pt": "Portuguese",
+    "fr": "French",
+    "de": "German",
+    "it": "Italian",
+    "nl": "Dutch",
+    "ja": "Japanese",
+    "zh": "Chinese",
+}
+
+
+def _lang_label(code: str) -> str:
+    return _LANGUAGE_NAMES.get(code.lower(), code)
+
+
+def select_mannerisms(
+    persona: EmailPersona,
+    *,
+    rng: Optional[secrets.SystemRandom] = None,
+    n: int = 2,
+) -> list[str]:
+    """Pick *n* mannerisms deterministically given *rng*.
+
+    Returns up to *n*; falls back to the full list when the persona
+    declares fewer.  Determinism (under a seeded RNG) is what makes
+    tests practical — otherwise mannerism injection is unverifiable.
+    """
+    rnd = rng or secrets.SystemRandom()
+    pool = list(persona.mannerisms)
+    if not pool:
+        return []
+    if len(pool) <= n:
+        return pool
+    rnd.shuffle(pool)
+    return pool[:n]
+
+
+def build(
+    inputs: PromptInputs,
+    *,
+    rng: Optional[secrets.SystemRandom] = None,
+) -> tuple[str, list[str]]:
+    """Return ``(prompt, mannerisms_used)``.
+
+    ``mannerisms_used`` flows back into the persisted ``payload`` JSON
+    so an analyst can see *why* a given email reads the way it does.
+    """
+    sender = inputs.sender
+    recipient = inputs.recipient
+    language = _lang_label(sender.language or "en")
+    mannerisms = select_mannerisms(sender, rng=rng)
+    mannerism_block = (
+        "\n".join(f"- {m}" for m in mannerisms)
+        if mannerisms
+        else "- (no specific mannerisms; write in the persona's tone)"
+    )
+
+    if sender.uses_llms_heavily:
+        em_dash_rule = (
+            "Em-dashes are fine — this persona uses them naturally. "
+            "Write in your usual style."
+        )
+    else:
+        em_dash_rule = (
+            "Do NOT use em-dashes (—). Use commas, periods, or "
+            "parentheses instead. Em-dashes are a tell."
+        )
+
+    sig_block = (
+        f"Use this exact signature block:\n{sender.signature}"
+        if sender.signature
+        else "End with a short, plausible signature for the persona's role."
+    )
+
+    if inputs.parent_subject:
+        thread_block = (
+            f"This is a REPLY in an ongoing thread.\n"
+            f"- Parent subject: {inputs.parent_subject}\n"
+            f"- Parent excerpt: {inputs.parent_excerpt or '(no excerpt)'}\n"
+            f"- Begin the body assuming the recipient already read the parent.\n"
+        )
+        subject_rule = (
+            "Subject must be the parent subject prefixed with 'Re: ' "
+            "(no double 'Re: Re:')."
+        )
+    else:
+        thread_block = "This is a NEW thread (no prior context)."
+        subject_rule = (
+            "Generate a short, specific subject line (≤ 80 chars) "
+            "appropriate to the context."
+        )
+
+    prompt = f"""You are writing one corporate email, RFC 2822 plain-text body only.
+
+Persona — sender:
+- Name: {sender.name}
+- Role: {sender.role}
+- Tone: {sender.tone_custom if sender.tone == "custom" and sender.tone_custom else sender.tone}
+- Mannerisms (must show through):
+{mannerism_block}
+
+Persona — recipient:
+- Name: {recipient.name}
+- Role: {recipient.role}
+
+Context hint: {inputs.context_hint}
+
+Thread context:
+{thread_block}
+
+Hard rules:
+1. Write the email body in {language}. Do not translate or code-switch.
+2. {em_dash_rule}
+3. {subject_rule}
+4. {sig_block}
+5. Output ONLY the email — first line is "Subject: <subject>", then a blank line, then the body. No commentary, no markdown fences, no preamble.
+"""
+    return prompt.strip(), mannerisms