core/docs/decisions/ADR-0072-register-telemetry-operator-surface.md

ADR-0072 — Register telemetry + operator surface (Plan Phase R5)

Status: Accepted Date: 2026-05-19 Ratified: 2026-05-19 Author: Shay Phase: Plan Phase R5 (operator-visible register) Builds on: ADR-0068 (register pack class), ADR-0069 (realizer register parameter), ADR-0070 (terse_v1), ADR-0071 (convivial_v1 + seeded variation)

---

Context

R1–R4 built the register subsystem inside-out: pack class (R1), realizer wiring (R2), first non-neutral knob (R3), seeded variation (R4). At R4 the system can produce visibly different surfaces across turns while staying bit-for-bit reproducible, but the register is invisible to operators:

• TurnEvent carries grounding_source but not register_id.
• The audit JSONL stream has no field that distinguishes a neutral-register turn from a convivial-register turn that happens to have selected the empty closing.
• The CLI has no way to drive a register at all — every core chat invocation runs unregistered.
• There is no narrative demo showing the seam holding under variation the way core demo audit-tour shows it holding under identity / safety / ethics.

R5 closes those gaps. The register-pack architecture becomes operator-observable, operator-driven, and demo-falsifiable. After R5, the presentation axis is feature-complete enough to compose against the substantive axis (Greek/Hebrew anchor lens) without further plumbing.

---

Decision

R5 ships three artifacts:

1. Telemetry extension — TurnEvent gains register_id and register_variant_id; the telemetry serializer surfaces them in every audit line.
2. Operator surface — core chat --register <id> CLI flag wires into RuntimeConfig.register_pack_id.
3. Narrative demo — core demo register-tour walks the same prompt sequence under {default_neutral_v1, terse_v1, convivial_v1} and prints a grid with per-cell (surface, grounding_source, trace_hash, register_id, register_variant_id). The demo asserts the load-bearing seam claim — grounding_source and trace_hash are byte-identical across registers, only surface varies — and exits non-zero if it fails.

Telemetry — TurnEvent shape extension

# core/physics/identity.py
@dataclass(frozen=True)
class TurnEvent:
    ...
    grounding_source: str = "none"
    # ADR-0072 (R5) — operator-visible register identity per turn.
    register_id: str = ""
    register_variant_id: str = ""

• register_id: the loaded pack's register_id, or "" for the in-memory UNREGISTERED sentinel. Pre-R4 deployments stay byte-identical (empty string is the default).
• register_variant_id: a stable 12-char SHA-256 digest of the selected (opening, closing) marker pair. Empty ("") when no decoration was applied (empty buckets, or empty surface). Different turns under the same register that select the same marker pair share the same variant_id — useful for "how many distinct variants did this register actually produce across N turns?"

The variant_id is intentionally a digest, not the literal strings:

• The literal markers are operator-authored content already on disk in packs/register/<id>.json; reproducing them inline in every TurnEvent is redundant.
• A digest is content-addressed: two different turns with the same variant_id provably picked the same marker pair without storing the pair twice.
• 12 chars (48 bits) is far more than enough to distinguish among at most len(openings) × len(closings) variants per register (currently ≤ 9 for convivial_v1).

Decoration return type widens

Today decorate_surface(surface, register, *, turn_idx, seed_text=None) -> str. R5 needs the variant_id alongside the surface. Two options:

• (A) Return a small frozen dataclass DecorationResult(surface, opening, closing, variant_id).
• (B) Add a parallel compute_decoration(...) -> DecorationResult and leave decorate_surface as a thin wrapper.

R5 chooses (A) — a single source of truth for what decoration happened. The R4 call sites in chat/runtime.py already expect a string; they will be updated to read .surface. decorate_surface gains a slim decorate_surface_str alias preserving the old return type for off-runtime callers (tests, ad-hoc CLI tools).

@dataclass(frozen=True, slots=True)
class DecorationResult:
    surface: str            # post-decoration string
    opening: str            # marker chosen for the opening bucket
    closing: str            # marker chosen for the closing bucket
    variant_id: str         # 12-char sha256(f"{opening}|{closing}") prefix

def decorate_surface(
    surface: str,
    register: RegisterPack,
    *,
    turn_idx: int,
    seed_text: str | None = None,
) -> DecorationResult: ...

def decorate_surface_str(...) -> str:
    return decorate_surface(...).surface

When both opening and closing are empty, variant_id is "" (the "no decoration applied" sentinel). This means UNREGISTERED, default_neutral_v1, and terse_v1 all emit variant_id="" — they don't pollute the audit stream with a no-op digest.

CLI — core chat --register <id>

# core/cli.py — cmd_chat argparser
chat_parser.add_argument(
    "--register",
    metavar="REGISTER_ID",
    default=None,
    help=(
        "Optional register pack ID (ADR-0068+).  Default: no register "
        "(unregistered sentinel, byte-identical to default_neutral_v1)."
    ),
)

Threads into _runtime_config_from_args as RuntimeConfig(register_pack_id=args.register). An invalid register_id raises RegisterPackError at ChatRuntime.__init__ — the CLI catches and surfaces it as a clear error before the chat REPL starts, not on the first turn.

Demo — core demo register-tour

A narrative demo that walks a fixed prompt sequence under each ratified register, prints a register × prompt grid of surfaces, and emits a JSON record with the load-bearing claim:

Registers exercised:
  - default_neutral_v1
  - terse_v1
  - convivial_v1

Prompt sequence (4 prompts; deterministic order):
  P1: "What is light?"
  P2: "Define knowledge."
  P3: "What is truth?"
  P4: "Light reveals truth, right?"

Per cell, the demo records:
  surface, grounding_source, trace_hash, register_id, register_variant_id.

Load-bearing claim (asserted before exit):
  all_grounding_sources_identical: True
  all_trace_hashes_identical:      True
  surfaces_vary_at_least_once:     True (convivial vs neutral)

The demo prints a human-readable grid to stdout and a structured JSON record (matching core demo audit-tour --json shape) for downstream consumption. Exit code 0 iff every claim holds.

Files

core/physics/identity.py                                     EDIT
  - TurnEvent gains register_id and register_variant_id
    (both default "" — pre-R4 byte-identical)

chat/register_variation.py                                   EDIT
  - DecorationResult dataclass added
  - decorate_surface return type widened
  - decorate_surface_str alias added for old callers

chat/runtime.py                                              EDIT
  - Both call sites of decorate_surface updated to read .surface
  - TurnEvent construction gains register_id + register_variant_id
    from the decoration result
  - Stub path also fills the two new fields

chat/telemetry.py                                            EDIT
  - serialize_turn_event adds register_id and register_variant_id
    to the output dict (always — pre-R4 emit "" for both)

core/cli.py                                                  EDIT
  - cmd_chat adds --register flag
  - _runtime_config_from_args reads args.register

evals/register_tour/run_tour.py                              NEW
  - Narrative demo runner; mirrors evals/audit_tour/run_tour.py shape
evals/register_tour/__init__.py                              NEW

core/cli.py                                                  EDIT
  - cmd_demo_register_tour subcommand wires to evals.register_tour
  - EPILOG gains "core demo register-tour" example

tests/test_register_telemetry.py                             NEW
  - TurnEvent fields populated on every chat() turn
  - serialize_turn_event surfaces both fields
  - register_id="" when register_pack_id=None
  - register_variant_id="" for null/empty-bucket registers
  - register_variant_id is a 12-char hex digest under convivial_v1

tests/test_register_cli.py                                   NEW
  - core chat --register convivial_v1 boots successfully
  - core chat --register bogus_v999 exits with clear error
  - flag default (no --register) preserves R4 behaviour

tests/test_register_tour_demo.py                             NEW
  - core demo register-tour exits 0 under all three registers
  - all_grounding_sources_identical == True
  - all_trace_hashes_identical == True
  - surfaces_vary_at_least_once == True
  - JSON output schema is stable (snapshot pin)

docs/decisions/ADR-0072-register-telemetry-operator-surface.md  NEW (this file)

Invariants pinned in CI at R5

invariants A, B, C (ADR-0069)                       — preserved
invariant_register_grounding (ADR-0070)             — extended
invariant_seeded_variation_replay (ADR-0071)        — preserved
invariant_seeded_variation_turn_distinct (ADR-0071) — preserved

invariant_telemetry_register_visible (NEW):
  serialize_turn_event(event) always contains
  register_id and register_variant_id keys; the values reflect the
  runtime's loaded register at turn-emit time.

invariant_register_tour_seam (NEW):
  evals/register_tour/run_tour.py asserts:
    - grounding_source identical across registers per prompt
    - trace_hash identical across registers per prompt
    - surface differs at least once (convivial vs neutral)
  Exits non-zero on any violation.  Pinned by
  tests/test_register_tour_demo.py.

The tour demo is the load-bearing R5 artifact. It is the operator-visible answer to "does the seam actually hold?" and it exits non-zero if it doesn't — turning the architectural claim into a falsifiable CI check.

---

Consequences

Capability unlocked at R5

• An operator can drive any ratified register from the CLI.
• Every audit JSONL line names which register was active and which variant fired — the audit trail can answer "did the operator's --register flag actually take effect?" without inferring it.
• A single demo proves end-to-end that switching registers does not move trace_hash or grounding_source, only surface text.

Cognition lane — unchanged

Empty defaults on the new TurnEvent fields preserve byte-identical output. The R1–R4 invariants continue to hold. The cognition eval public/holdout numbers stay byte-identical.

Backwards compatibility

• TurnEvent fields default to "" — pre-R5 callers that construct TurnEvent(...) without the new fields keep working.
• decorate_surface signature is widening from -> str to -> DecorationResult. The two runtime call sites are updated in the same PR. Off-runtime callers (tests, ad-hoc CLI) use the new decorate_surface_str alias when they only want the string.
• Existing telemetry consumers that read JSONL by key access continue to work; consumers that snapshot the exact set of keys may need to update — register_id and register_variant_id are added. Snapshot tests in tests/test_register_telemetry.py document the new shape.

Performance

One additional SHA-256 per turn (for variant_id), one new dict entry in the telemetry payload. Negligible.

Trust boundaries

• --register flag does not bypass ratification. The flag value is passed through _validate_pack_id (already in the loader) and through the ratify gate at load time. An unratified pack id raises RegisterPackError exactly as a config-driven load would.
• Variant_id is content-addressed. Two operators staring at the same variant_id are looking at the same marker pair, full stop. No content rendering required; no info leak beyond what register_id already implies.
• CLI value sanitization. args.register is a user-controlled string entering the trust boundary. Path traversal and unsafe ids are rejected by the loader's existing _find_pack guard.
• Telemetry stays redact-safe. Neither register_id nor register_variant_id carries content; both are pack identifiers / digests. include_content=False paths surface them unconditionally because they're not content.
• No new mutation surface. Pack files on disk are not modified by anything in R5.

---

Verification

tests/test_register_telemetry.py                             N passed
tests/test_register_cli.py                                   N passed
tests/test_register_tour_demo.py                             N passed
Curated lanes (must remain green):
  smoke / cognition / teaching / packs / runtime / algebra
Cognition eval byte-identical:
  public 100 / 100 / 91.7 / 100
  holdout 100 / 100 / 83.3 / 100
core demo register-tour                                      exit 0
core demo register-tour --json                               stable schema

The tour exit code is the canonical R5 gate — if it ever exits non-zero in CI, the register subsystem has regressed.

---

Open questions deferred to later phases

• TurnVerdicts integration. Should TurnVerdicts carry the register identity alongside safety/ethics/identity? Probably yes for a fully unified audit bundle, but R5 keeps the field on TurnEvent itself for now. Future ADR may consolidate.
• Variant_id collision space. A 12-char hex prefix is 48 bits. Two distinct (opening, closing) pairs collide with probability ~2^-48 — effectively zero across any realistic operator-authored bucket. If buckets ever grow to thousands of entries, widen to 16 or 20 chars. Not an R5 concern.
• Operator-driven register switching mid-session. Today the register is loaded once at ChatRuntime.__init__. A runtime.set_ register(<id>) API would let an operator switch live. Deferred — needs careful thinking about replay equivalence across the switch.

---

Future ADRs unlocked

• ADR-0073+ (post-R5) — anchor lens / substantive variation (Greek/Hebrew). The presentation axis is now operator-visible, CI-falsifiable, and audit-traceable. Anchor lens composes against it as an orthogonal axis (content variation, not surface variation). See [[greek-hebrew-pack-scout-2026-05-19]] for the content prerequisites (distinction-bearing lemmas, alignment files on cognition-tier packs, reviewed teaching corpus in non- English).