core/docs/decisions/ADR-0069-realizer-register-parameter.md

ADR-0069 — Realizer register parameter (Plan Phase R2)

Status: Accepted (amended 2026-05-19) Date: 2026-05-19 Ratified: 2026-05-19 Amended: 2026-05-19 — composer parameter defaults to RegisterPack.unregistered(); runtime-threading lint test replaces the "required keyword-only" rule. See Amendment section. Author: Shay Phase: Plan Phase R2 (presentation-axis wiring) Builds on: ADR-0068 (register pack class)

---

Context

ADR-0068 landed the register pack class — frozen dataclass, loader, ratification script, default_neutral_v1 null register, and an architectural seam test asserting that no upstream module imports packs.register. At R1 the realizer is untouched and the seam is machine-enforced.

R2 is the first wiring step. Two questions the ADR answers:

1. Where does the register enter the runtime? At realizer call time — after intent classification, propagation, grounding-source selection, chain resolution, and articulation-target construction. Never earlier.
2. What happens when register is consumed but the pack is null? Byte-identical output to the unregistered path. This is the load-bearing CI gate for R2.

R2 ships plumbing only. No composer changes its template choice. No discourse marker is inserted. The realizer entry points learn to accept a register parameter; the runtime learns to load and pass it; the gate asserts that doing so changes nothing. R3 is where the first non-neutral register starts consuming overrides.

This phasing matters because it lets us prove the seam against the trace-hash and grounding-source invariants before any visible behaviour change rides on top.

---

Decision

Widen the realizer call signature to accept a RegisterPack parameter and thread it through every surface composer entry point in chat/runtime.py. Add RuntimeConfig.register_pack_id: str | None, defaulting to None. Pin three byte-identity invariants in CI.

The three byte-identity invariants

R2 ships only if all three hold across the full cognition lane (public + holdout splits):

invariant_A:  register_pack_id=None
              ≡ pre-R2 unregistered output  (byte-for-byte)

invariant_B:  register_pack_id="default_neutral_v1"
              ≡ register_pack_id=None       (byte-for-byte)

invariant_C:  trace_hash(turn) is invariant under register_pack_id
              for every turn in the cognition lane

Invariant A proves R2 is a no-op for existing callers. Invariant B proves the null register is structurally equivalent to "no register." Invariant C proves register cannot leak into the truth path.

Files

chat/runtime.py                                              EDIT
  - RuntimeConfig gains register_pack_id: str | None = None
  - ChatRuntime.__init__ loads the register pack (or unregistered sentinel)
  - Every realizer call site passes the register through

generate/realizer.py                                         EDIT
  - Public entry points accept register: RegisterPack parameter
  - At R2, register is accepted and discarded (no-op consumption)

generate/templates.py                                        UNCHANGED
  (R3 will start dispatching on register.realizer_overrides;
   R2 leaves templates alone)

chat/pack_grounded_*.py / chat/teaching_grounding.py /       EDIT (parameter only)
chat/cross_pack_grounding.py / chat/narrative_surface.py /
chat/example_surface.py
  - Accept register parameter; do not consume it at R2

tests/test_register_pack_seam.py                             REPLACE
  - R1 version asserted no upstream module imports packs.register;
    R2 narrows the forbidden list (see "Updated seam" below)

tests/test_register_null_lift.py                             NEW
  - Pins invariants A, B, C across the cognition lane

tests/test_runtime_config_register.py                        NEW
  - RuntimeConfig field shape; load behaviour; invalid id rejection

docs/decisions/ADR-0069-realizer-register-parameter.md       NEW (this file)

Wiring shape

# RuntimeConfig (chat/runtime.py)
@dataclass(frozen=True)
class RuntimeConfig:
    ...
    register_pack_id: str | None = None  # NEW (ADR-0069)


# ChatRuntime.__init__
class ChatRuntime:
    def __init__(self, config: RuntimeConfig, ...):
        ...
        if config.register_pack_id is None:
            self._register = RegisterPack.unregistered()
        else:
            self._register = load_register_pack(config.register_pack_id)


# Realizer entry point
def realize_surface(
    target: ArticulationTarget,
    *,
    register: RegisterPack,
) -> str:
    # R2: register is accepted, validated, discarded.
    # R3: register.realizer_overrides[target.intent] selects template family.
    ...

Composer signature widening

Every existing surface composer that the runtime calls — pack-grounded, teaching-grounded, cross-pack, narrative, example, composed, correction, procedure — gains a register: RegisterPack keyword-only parameter. At R2 the parameter is required (no default) so call sites fail loudly if they forget to thread it through. The composer body is unchanged.

Default arguments are avoided deliberately: silent fall-through to RegisterPack.unregistered() would let R3 sites quietly skip the register lookup. Required keyword-only parameter forces explicit threading.

Updated seam

The R1 seam test forbade packs.register imports in every upstream module. R2 replaces it with a narrowed forbidden list:

Still forbidden at R2 (truth-path modules):
  core/cognition/trace.py
  core/cognition/pipeline.py
  core/cognition/result.py
  generate/graph_planner.py
  generate/intent.py
  field/propagate.py
  vault/store.py
  algebra/versor.py

Allowed at R2 (realizer side):
  generate/realizer.py
  generate/templates.py
  chat/runtime.py
  chat/pack_grounded_*.py
  chat/teaching_grounding.py
  chat/cross_pack_grounding.py
  chat/narrative_surface.py
  chat/example_surface.py

The structural commitment from R1 is preserved: register is consumed at realizer call time only. Trace, pipeline, intent classification, propagation, vault recall, and algebra remain free of register imports.

Where the register pack loads

ChatRuntime.__init__ loads it once and stores it on the instance. Per-turn lookup is not needed — RuntimeConfig is frozen and the register pack is content-addressed and immutable after load. Reloading per turn would be wasted work and would obscure the "register is session-scoped" mental model.

When register_pack_id is None, the sentinel RegisterPack.unregistered() is used. This is structurally identical to default_neutral_v1 (both null registers) and the invariant-B test proves it.

---

Consequences

Capability unlocked at R2

None visible at runtime. R2 lands the wiring and the byte-identity gate. Capability unlocks at R3 (second ratified register pack).

Cognition lane — byte-identical

Required and CI-pinned by test_register_null_lift.py:

public:  intent 100% / surface 100% / term 91.7% / closure 100%
holdout: intent 100% / surface 100% / term 83.3% / closure 100%

must hold post-merge across all three invariants (None, default_neutral_v1, unregistered sentinel).

Test coverage

• test_register_null_lift.py — runs the cognition lane three ways and asserts surfaces are byte-identical pairwise. Also asserts grounding_source and trace_hash are invariant across registers.
• test_runtime_config_register.py — RuntimeConfig.register_pack_id default is None; invalid id raises RegisterPackError at runtime init; default_neutral_v1 loads cleanly.
• test_register_pack_seam.py (replaces R1 version) — narrowed forbidden list; loader-side import constraints unchanged.

Performance

Negligible. One pack load on ChatRuntime.__init__; the loaded pack is a frozen dataclass passed by reference per turn. No new allocations in the hot path.

---

Trust boundaries

• Register cannot mutate truth. Realizer is the only consumer. grounding_source, chain resolution, trace hash, and proposition graph are computed before realizer is called. Invariant C CI-enforces this.
• Required keyword-only parameter. No composer accepts a default register; missing it raises TypeError at call time. This catches R3 wiring mistakes early.
• Load-time validation. Invalid register_pack_id raises RegisterPackError at ChatRuntime.__init__, not at first turn. Fail-fast on session start.
• No mutation surface. ADR-0068 doctrine preserved: register packs are operator-authored and ratified through scripts/ratify_register_packs.py. R2 adds no runtime write path to packs/register/.
• Telemetry stays redact-safe. R2 does not extend TurnEvent. Adding register_id to telemetry is an R5 task (ADR-0072) — out of scope here.

---

Verification

tests/test_register_null_lift.py                             N passed
tests/test_runtime_config_register.py                        N passed
tests/test_register_pack_seam.py                             updated, N passed
Curated lanes (must remain green):
  smoke / cognition / teaching / packs / runtime / algebra
Cognition eval byte-identical across:
  register_pack_id=None
  register_pack_id="default_neutral_v1"
Full lane: zero new failures.

The invariant-A/B/C test is the load-bearing artifact. If it lands and passes, R2 has shipped its full promise.

---

Open questions deferred to later phases

• How do composers consult realizer_overrides? R3 question. R2 only proves the parameter threads cleanly.
• Where do discourse markers attach to surfaces? R4 question. Likely a post-composer wrapper that consults register.discourse_markers and the seeded selection function. Not part of R2.
• Should RegisterPack.unregistered() be replaced with the loaded default_neutral_v1 by default? Open. Two arguments:
  • Replace: simpler mental model; one canonical null register.
  • Keep separate: sentinel doesn't require disk presence; works in minimal/test environments where packs/register/ is absent. Lean toward keep-separate; revisit if it causes confusion in R3.
• Should the realizer signature change to accept a richer RealizerContext object (register + future fields) instead of bare RegisterPack? Probably yes by R4, but premature at R2. Deferred.

---

Amendment (2026-05-19)

The original ADR required composers to take register as a required keyword-only parameter, on the principle that defaults would let R3 sites silently fall through to RegisterPack.unregistered(). R2 implementation scouting found that rule lands on 167 call sites across 15 test files. Each of those sites calls a composer as a bare function (e.g. teaching_grounded_surface("light", IntentTag.CAUSE)) and would need a register keyword added.

That cost was not measured in the original ADR. Updated decision:

• Composers accept register: RegisterPack = RegisterPack.unregistered() as a keyword-only argument with a default. Existing test call sites remain valid.
• A new lint test, test_register_runtime_threading.py, AST-parses chat/runtime.py and asserts that every call to a composer function passes register explicitly. This is the runtime-side enforcement that R3 cannot silently drop the register lookup.
• The default is the unregistered sentinel, not a loaded pack. A composer called without register= from a non-runtime caller (test, ad-hoc CLI) defaults to the same in-memory shape that runtime would use when register_pack_id=None. Byte-identity invariants A/B/C still hold trivially because the runtime path always threads explicitly.

The seam intent — "R3 cannot quietly skip the register lookup" — is preserved by the lint test rather than by the function signature. The trade is: signature-level rigour for blast-radius reduction, with the seam guarantee re-located one level up.

This amendment supersedes the "Composer signature widening" subsection above where it conflicts.

---

Future ADRs unlocked

• ADR-0070 (Phase R3) — second ratified register pack. First non-neutral register (terse_v1 candidate). Composers start consulting realizer_overrides. New CI metric: register_invariant_grounding=True (grounding source identical across registers for every prompt; only surface wording varies).
• ADR-0071 (Phase R4) — seeded surface variation. (trace_hash, register, turn_idx) → template_variant. Discourse markers gain bounded variants pulled by deterministic seed.
• ADR-0072 (Phase R5) — telemetry + operator surface. TurnEvent gains register_id and template_variant_id. core chat --register <id> flag. core demo register-tour.