core/docs/decisions/ADR-0073d-anchor-lens-telemetry-tour.md

ADR-0073d — Anchor-lens telemetry, CLI, and tour demo (Plan Phase L1.4)

Status: Accepted Date: 2026-05-19 Ratified: 2026-05-19 Author: Shay Phase: Plan Phase L1.4 (operator-visible anchor lens, falsifiable demo) Parent: ADR-0073 (umbrella) Builds on: ADR-0073a, ADR-0073b, ADR-0073c Pattern: mirrors ADR-0072 (register R5 — telemetry + tour demo)

---

Context

L1.1–L1.3 built the anchor-lens subsystem inside-out: substrate content (L1.1), pack class + loader (L1.2), composer wiring with surface lift on cognition lemmas (L1.3). The lens is loaded, engages on its intended pack lemmas via the alignment graph, and appends [lens(<id>):<mode>] to the surface when engaged.

L1.4 closes the architectural arc by making the lens operator-observable, operator-driven, and demo-falsifiable — exactly what R5 did for the register subsystem. After L1.4 the substantive axis is feature-complete enough to compose against the register axis in operator-visible demos and audit pipelines.

The load-bearing claim L1.4 ships is the opposite of register-tour's:

register-tour    : per prompt, fix lens, vary register → trace_hash CONSTANT
anchor-lens-tour : per prompt, fix register, vary lens → trace_hash DISTINCT

Both invariants must continue to hold turn-by-turn. L1.4 packages the second one into a falsifiable demo.

---

Decision

L1.4 ships three artifacts:

1. Telemetry extension — TurnEvent + ChatResponse gain anchor_lens_id (loaded pack id, empty for UNANCHORED) and anchor_lens_mode_label (engaged mode label this turn, empty when the lens didn't engage on this turn's lemma).
2. Operator surface — core chat --anchor-lens <id> CLI flag wires into RuntimeConfig.anchor_lens_id. Invalid id fails fast at ChatRuntime.__init__ (mirrors --register).
3. Narrative demo — core demo anchor-lens-tour walks a fixed 2-prompt sequence under {default_unanchored_v1, grc_logos_v1, he_logos_v1} and asserts the three load-bearing claims.

Telemetry — TurnEvent shape extension

# core/physics/identity.py
@dataclass(frozen=True)
class TurnEvent:
    ...
    register_id: str = ""
    register_variant_id: str = ""
    # ADR-0073d (L1.4) — operator-visible anchor-lens identity per turn.
    anchor_lens_id: str = ""
    anchor_lens_mode_label: str = ""

• anchor_lens_id: the loaded pack's lens_id, or "" for the in-memory UNANCHORED sentinel. Pre-L1.4 callers stay byte-identical (empty string is the default).
• anchor_lens_mode_label: the engaged cognitive_mode_label when the lens fired on this turn's lemma, or "" when the lens was loaded but did not engage (different lemma than its alignment scope), or when no lens was loaded at all.

Reading this pair tells operators three things at a glance:

• (id="", mode="") — no lens loaded
• (id="<x>", mode="") — lens loaded, did not engage on this turn
• (id="<x>", mode="<label>") — lens loaded, engaged, surface carries [lens(<x>):<label>]

Mode-label extraction

The composer (L1.3) embeds the engaged mode label in the surface string as [lens(<lens_id>):<mode_label>]. At telemetry-build time, the runtime extracts the mode label by reading that annotation from the pre-decoration surface. A small deterministic parser:

# chat/runtime.py
_ANCHOR_LENS_ANNOTATION_RE = re.compile(
    r"\[lens\(([^):]+)\):([^\]]+)\]"
)

def _extract_anchor_lens_mode_label(surface: str, lens_id: str) -> str:
    """Return the engaged mode_label if surface carries an annotation
    for ``lens_id``, else ``""``.  Pure read; no side effects."""
    if not surface or not lens_id:
        return ""
    for match in _ANCHOR_LENS_ANNOTATION_RE.finditer(surface):
        if match.group(1) == lens_id:
            return match.group(2)
    return ""

This keeps L1.4 a read-only telemetry pass over the L1.3 surface. The composer remains the only source of truth for engagement; the runtime simply mirrors what the composer emitted.

CLI — core chat --anchor-lens <id>

chat.add_argument(
    "--anchor-lens",
    metavar="LENS_ID",
    default=None,
    help=(
        "optional anchor-lens pack id (ADR-0073+); default: no "
        "lens (unanchored sentinel, byte-identical to "
        "default_unanchored_v1).  Examples: default_unanchored_v1, "
        "grc_logos_v1, he_logos_v1.  Invalid ids fail-fast at "
        "runtime init before the REPL starts."
    ),
)

Threads into _runtime_config_from_args as RuntimeConfig(anchor_lens_id=args.anchor_lens). Invalid id ⇒ AnchorLensError at ChatRuntime.__init__ — the CLI catches and surfaces it as _die("invalid --anchor-lens pack id: ...", code=2) before the REPL launches, exactly as --register does.

Demo — core demo anchor-lens-tour

A narrative demo that walks a fixed two-prompt sequence under each ratified lens, prints a lens × prompt grid, and emits a structured JSON record with the three load-bearing claims:

Lenses exercised:
  - default_unanchored_v1   (engagement baseline; no annotation expected)
  - grc_logos_v1            (engages on knowledge via ἐπιστήμη)
  - he_logos_v1             (engages on truth via אמת)

Prompt sequence (2 prompts; deterministic order):
  P1: "What is knowledge?"
  P2: "What is truth?"

Per cell, the demo records:
  surface, grounding_source, trace_hash, anchor_lens_id, anchor_lens_mode_label.

Load-bearing claims (asserted before exit):
  lens_ids_recorded_per_turn               : True
  trace_hashes_distinct_across_lenses      : True (≥ 2 distinct hashes per prompt)
  surface_propositions_distinct_across_lenses: True (≥ 2 distinct surfaces per prompt)
  no_substrate_glyph_leak                  : True (surfaces stay ASCII at the lens block)

Exit code 0 iff every claim holds. Schema mirrors core demo register-tour --json.

Files

core/physics/identity.py                                      EDIT
  - TurnEvent gains anchor_lens_id + anchor_lens_mode_label

chat/runtime.py                                               EDIT
  - _extract_anchor_lens_mode_label helper
  - both stub + main paths populate the two new fields on
    TurnEvent and ChatResponse
  - ChatResponse mirrors the two fields

chat/telemetry.py                                             EDIT
  - serialize_turn_event surfaces both fields

core/cli.py                                                   EDIT
  - cmd_chat adds --anchor-lens flag with fail-fast handler
  - _runtime_config_from_args threads anchor_lens_id
  - demo target choices add "anchor-lens-tour"
  - cmd_demo handler wires evals/anchor_lens_tour/run_tour
  - EPILOG gains "core demo anchor-lens-tour"

evals/anchor_lens_tour/__init__.py                            NEW
evals/anchor_lens_tour/run_tour.py                            NEW

tests/test_anchor_lens_telemetry.py                           NEW
  - TurnEvent default empty / populated under each lens
  - serialize_turn_event surfaces both fields
  - mode_label is "" when lens loaded but no engagement this turn
  - ChatResponse mirrors event fields

tests/test_anchor_lens_cli.py                                 NEW
  - _runtime_config_from_args threading
  - --anchor-lens parser wiring + default None
  - Invalid id ⇒ AnchorLensError at ChatRuntime init

tests/test_anchor_lens_tour_demo.py                           NEW
  - Three seam claims pinned individually
  - all_claims_supported overall
  - Per-cell anchor_lens_id recorded correctly
  - No substrate glyphs in the surfaces

docs/decisions/ADR-0073d-anchor-lens-telemetry-tour.md        NEW (this file)

Invariants pinned at L1.4

anchor_lens_byte_identity_null_lift (L1.2)        — preserved
anchor_lens_lifts_proposition (L1.3)              — preserved
anchor_lens_no_glyph_leak (L1.3)                  — preserved
register-tour seam (R5)                            — preserved

invariant_anchor_lens_telemetry_visible (NEW):
  serialize_turn_event(event) always contains
  anchor_lens_id and anchor_lens_mode_label keys; the values
  reflect the runtime's loaded lens and the engaged mode label
  on this turn (or empty when no engagement).

invariant_anchor_lens_tour_seam (NEW):
  evals/anchor_lens_tour/run_tour.py asserts:
    - anchor_lens_id recorded per turn (matches runtime config)
    - trace_hash DISTINCT across lenses per prompt where lens engages
    - surface DISTINCT across lenses per prompt where lens engages
    - no substrate-block glyphs in any surface under any lens
  Exits non-zero on any violation.  Pinned by
  tests/test_anchor_lens_tour_demo.py.

---

Consequences

Capability unlocked at L1.4

• Operators drive any ratified lens from the CLI.
• Every audit JSONL line names which lens was active and whether it engaged on that turn.
• A single demo proves end-to-end that switching lenses moves trace_hash and surface — the opposite invariant from register-tour, asserted continuously.
• The anchor-lens × register matrix is now feature-complete enough to compose: any combination of --register × --anchor-lens is operator-driveable and audit-traceable.

Cognition lane — unchanged

Empty defaults on the new TurnEvent fields preserve byte-identical output. The L1.2 null-lift and L1.3 lift invariants continue to hold. The cognition eval public/holdout numbers stay byte-identical under the unanchored default.

Backwards compatibility

• TurnEvent fields default to "" — pre-L1.4 callers that construct TurnEvent(...) without the new fields keep working.
• ChatResponse defaults likewise.
• Existing telemetry consumers that read JSONL by key access continue to work; snapshot consumers may need to update — anchor_lens_id and anchor_lens_mode_label are added. Snapshot tests document the new shape.

Performance

One additional regex match per turn (for _extract_anchor_lens_ mode_label) when a lens is loaded. When unanchored, the helper early-exits on the empty lens_id. Negligible.

Trust boundaries

• --anchor-lens flag does not bypass ratification. The flag value is passed through _find_pack and the loader's ratification check (see ADR-0073b). An unratified pack id raises AnchorLensError exactly as a config-driven load would.
• Mode-label extraction is read-only. The regex parses a surface the composer already produced; nothing in L1.4 can forge a [lens(...):...] annotation that the composer didn't emit, because the regex anchors on the literal composer-emitted format.
• Telemetry stays redact-safe. Neither anchor_lens_id nor anchor_lens_mode_label carries surface content; both are pack identifiers / mode labels. 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 L1.4.

---

Verification

tests/test_anchor_lens_telemetry.py                           N passed
tests/test_anchor_lens_cli.py                                 N passed
tests/test_anchor_lens_tour_demo.py                           N passed
Curated lanes (must remain green):
  smoke / cognition / teaching / packs / runtime / algebra
Cognition eval byte-identical under default_unanchored_v1:
  public 100 / 100 / 91.7 / 100
core demo anchor-lens-tour                                    exit 0
core demo anchor-lens-tour --json                             stable schema
core demo register-tour                                       exit 0
                                                                (R5 seam still
                                                                 holds; both
                                                                 tours coexist)

The tour exit code is the canonical L1.4 gate — if anchor-lens-tour ever exits non-zero in CI, the substantive axis has regressed.

---

Composition with the register axis

core demo register-tour and core demo anchor-lens-tour test opposite invariants and both must pass continuously:

register-tour    : trace_hash CONSTANT across registers
anchor-lens-tour : trace_hash DISTINCT across lenses

A future two-axis tour (anchor-lens × register × prompts) is natural follow-on work but deferred — single-axis tours land first, composition tour after.

---

Open questions deferred

• Combined CLI flag composition. core chat --register X --anchor-lens Y already works at the wiring level (both flags thread into RuntimeConfig). A combined "audit view" demo showing the orthogonality matrix is a future ADR.
• TurnVerdicts integration. Should TurnVerdicts carry anchor_lens_id / register_id alongside safety/ethics? Yes eventually, but L1.4 keeps the fields on TurnEvent itself for now. A unifying ADR can consolidate later.
• Mid-session lens switching. Today the lens is loaded once at ChatRuntime.__init__. A runtime.set_anchor_lens(<id>) API would let an operator switch live. Deferred — needs careful thinking about replay equivalence across the switch (mirror of the same deferral for register).