From 16367b02d2c6c008eda9edd92601bed0118ba438 Mon Sep 17 00:00:00 2001 From: Bryan Van Deusen Date: Wed, 21 Oct 2026 20:25:48 -0400 Subject: [PATCH] docs(6205): retrieval_registry comments state the reason, not the instance that taught it Record and milestone citations go. The logs_unconditionally docstring, the place arm's comment and the fan-out key note state the condition they guard rather than the bug that once hit it. Co-Authored-By: Claude Opus 5.5 --- src/scribe/services/retrieval_registry.py | 56 +++++++++++------------ 1 file changed, 27 insertions(+), 29 deletions(-) diff --git a/src/scribe/services/retrieval_registry.py b/src/scribe/services/retrieval_registry.py index 11d038c2..e683bcd3 100644 --- a/src/scribe/services/retrieval_registry.py +++ b/src/scribe/services/retrieval_registry.py @@ -1,12 +1,12 @@ -"""Every point that retrieves or surfaces a record, declared (#3431, #3432). +"""Every point that retrieves or surfaces a record, declared. WHY A DECLARED LIST WHEN THE ROWS ALREADY NAME THEIR SOURCE. Because the rows can only describe arms that FIRED. A surface that emits nothing writes no row, so it is indistinguishable from a surface that does not exist — and the two call for opposite responses. `retrieval_telemetry` could report perfect health -for a window in which half the arms never ran. #3430 hit exactly this: its -"silent surface" finding could only be made by a human who happened to know -which arms were supposed to be there. +for a window in which half the arms never ran, and a "silent surface" +finding could only be made by a human who happened to know which arms were +supposed to be there. This module is that knowledge, written down. It carries the two facts the rows structurally cannot: @@ -16,7 +16,7 @@ structurally cannot: for a week is an arm that has lost the ability to speak. Same row shape, opposite meanings, and only the caller's intent separates them. * **expected to emit, or deliberately quiet with a reason.** A justified - silence must not read as a gap (#2475). `rest_*` sources fire only when a + silence must not read as a gap. `rest_*` sources fire only when a person opens the web UI; on an install driven entirely through MCP their absence is correct and permanent, and reporting it every window would train the reader to ignore the list that also carries the real ones. @@ -31,15 +31,14 @@ reserved slots belong in it precisely because they are judgeable without being tunable. One is a control panel; the other is an inventory. A test asserts every tunable surface also appears here, so the two cannot drift apart. -ADDING A RANKED ARM MEANS WRITING ITS SPEC. Since milestone 456 step 5 the +ADDING A RANKED ARM MEANS WRITING ITS SPEC. The ranked rows are read off `retrieval_pipeline.RANKED`, each spec declaring its own (`Declared`). Any OTHER point — a lookup, an asked search, an ambient carrier, a pull — still means adding a row here. `tests/test_retrieval_registry.py` walks the call sites with the ast module and fails on a source it cannot find below — deliberately not a grep, because two of the sources in this file (`wide_net`, `preference_slot`) reach their recorder through a -module constant and a grep for `source="` misses both. That is the -narrowing #3191 warns about, caught here in the act. +module constant and a grep for `source="` misses both. """ from __future__ import annotations @@ -89,7 +88,7 @@ class Point: False means "this can be quiet forever and that is correct" — and then `quiet_because` must say why, so a reader meets a decision rather than a - hole (#2475). + hole. """ quiet_because: str = "" @@ -97,11 +96,11 @@ class Point: logs_unconditionally: bool = True """Whether this arm writes a row even when it returns NOTHING. - THE #3497 GUARD, and the reason this field is not merely documentation. - Both rule arms once logged only their hits, so their zero-result count was - structurally 0 — and a "cannot decline" warning computed over that would - have fired on a LOGGING BUG while reporting a ranking problem, sending the - reader to move a floor that was never involved. An arm whose logging has + The reason this field is not merely documentation: an arm that logs only + its hits has a zero-result count that is structurally 0, and a "cannot + decline" warning computed over that would fire on a LOGGING BUG while + reporting a ranking problem, sending the reader to move a floor that was + never involved. An arm whose logging has not been confirmed unconditional is not eligible for that warning; it is excluded from the check rather than trusted. """ @@ -114,8 +113,7 @@ def _p(source, kind, what, **kw) -> tuple[str, Point]: POINTS: dict[str, Point] = dict([ # ── Unbidden push arms ─────────────────────────────────────────────── # - # The RANKED ones are read off the pipeline's specs (milestone 456 step - # 5): every arm, and every stage that runs a query of its own and records + # The RANKED ones are read off the pipeline's specs: every arm, and every stage that runs a query of its own and records # under its own name, declares its row where it is defined. What stays # here is what no spec describes — the lookups below, and everything asked, # ambient or pulled. @@ -123,7 +121,7 @@ POINTS: dict[str, Point] = dict([ expects_traffic=not spec.declared.quiet_because, quiet_because=spec.declared.quiet_because) for spec in RANKED), - # A LOOKUP, not a ranker (#4796): a record the operator named by number + # A LOOKUP, not a ranker: a record the operator named by number # in the message, fetched by id. No score and no bar, so it writes no # retrieval_logs row and no score-shaped warning can apply; its rows are # in `note_usage_events`, where pull-through says whether naming a record @@ -133,7 +131,7 @@ POINTS: dict[str, Point] = dict([ expects_traffic=False, quiet_because="speaks only when a message names a record by its id; " "a window in which none did is correctly silent here"), - # The moment arm (milestone 458). A LOOKUP, not a ranker: a rule mounted on + # The moment arm. A LOOKUP, not a ranker: a rule mounted on # a moment arrives when that moment happens, with no score, so it writes no # retrieval_logs row and no score-shaped warning can apply. Its rows are in # `rule_usage_events`, each carrying the moment in `detail`. @@ -142,11 +140,11 @@ POINTS: dict[str, Point] = dict([ expects_traffic=False, quiet_because="speaks only once some rule is mounted on a moment; an " "install where none is mounted is correctly silent here"), - # The rulings arm (milestone 444). A LOOKUP, not a ranker: a path falls + # The rulings arm. A LOOKUP, not a ranker: a path falls # under a System's patterns or it does not, so nothing here writes to # retrieval_logs and no score-shaped warning can apply. Its rows are in # `system_usage_events`, read back as `retrieval_telemetry`'s - # `system_usage` block (#4769). + # `system_usage` block. _p("rulings_pre_tool", UNBIDDEN, "an area's rulings, shown because a command touched its files", expects_traffic=False, @@ -179,9 +177,9 @@ POINTS: dict[str, Point] = dict([ # ── The write-path menu's own arms ─────────────────────────────────── # # These are NOT in retrieval_logs. The place arm carries no score and so - # has no row there at all (#2085) — before it was split out, the arm - # firing on the strongest possible claim, "there is already a canonical - # helper in this exact file", was the one arm nobody could measure. + # has no row there at all; declaring it here is what lets the arm making + # the strongest possible claim, "there is already a canonical helper in + # this exact file", be measured. _p("write_path_place", AMBIENT, "a snippet already placed in this very file"), _p("write_path_semantic", AMBIENT, "prior art matched by meaning"), _p("write_path_sync", AMBIENT, @@ -225,12 +223,12 @@ POINTS: dict[str, Point] = dict([ # out would not fail here. What catches that is `assert_registered`, which the # recorders call as the row is written. # Keyed by the EXACT string the extractor produces, matched by equality rather -# than by prefix. A prefix match was the first spelling and it silently matched -# nothing, because the paths are relative to `src/` and so begin `scribe/` — -# every site sailed through a check that looked like it was running. +# than by prefix. The paths are relative to `src/` and so begin `scribe/`; a +# prefix spelled any other way silently matches nothing, and every site sails +# through a check that looks like it is running. FAN_OUT_SITES: dict[str, tuple[str, ...]] = { # The write path's two LOOKUPS. Its ranked arm (`write_path_semantic`) - # records through the pipeline's site below (milestone 456 step 4). + # records through the pipeline's site below. "scribe/services/plugin_context.py::record_surfaced(source=arm)": ( "write_path_place", "write_path_sync", ), @@ -241,7 +239,7 @@ FAN_OUT_SITES: dict[str, tuple[str, ...]] = { "enter_project", "start_planning", "get_task", "get_project", "get_milestone", ), - # The one retrieval pipeline (milestone 456): every ranked arm's call row + # The one retrieval pipeline: every ranked arm's call row # and surfacing rows — both corpora — are written by these sites, so # `source` arrives as a value. The values are the pipeline's own specs, # read rather than restated, so an arm added there is declared here by @@ -255,7 +253,7 @@ FAN_OUT_SITES: dict[str, tuple[str, ...]] = { "scribe/services/retrieval_pipeline.py::record_rule_surfaced(source=source)": ( tuple(arm.source for arm in RULE_ARMS) ), - # The reply moment's mounted half (milestone 458): it records under the + # The reply moment's mounted half: it records under the # moment arm's source, read from the pipeline's constant so the two doors # cannot drift apart on the name. "scribe/services/moment_delivery.py::record_rule_surfaced(source=)": (