bvandeusen/FabledScribe
1
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases 53 Wiki Activity

docs(6205): retrieval_registry comments state the reason, not the instance that taught it

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
bvandeusen
2026-10-21 20:25:48 -04:00
co-authored by Claude Opus 5.5
parent 502ecf6743
commit 16367b02d2
1 changed files with 27 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/scribe/services/retrieval_registry.py
+27 -29
View File
@@ -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=<expression>)": (