From 32ebc2b1d41c365eb46d201068fcdc175374bd48 Mon Sep 17 00:00:00 2001 From: Bryan Van Deusen Date: Wed, 21 Oct 2026 20:29:52 -0400 Subject: [PATCH] docs(6205): retrieval_surfaces and family_adoption comments drop citations and the decision quote retrieval_surfaces' header states why the arms read their numbers from one table and why a floor is moved by reading the refused record, without the quoted decision, the retired arm or the declined-rule instance. family_adoption drops milestone/step labels from its section headers and states the no-ids reason instead of naming the trap. Co-Authored-By: Claude Opus 5.5 --- src/scribe/services/family_adoption.py | 17 +++--- src/scribe/services/retrieval_surfaces.py | 72 ++++++++--------------- 2 files changed, 33 insertions(+), 56 deletions(-) diff --git a/src/scribe/services/family_adoption.py b/src/scribe/services/family_adoption.py index 435b1a84..79a03701 100644 --- a/src/scribe/services/family_adoption.py +++ b/src/scribe/services/family_adoption.py @@ -1,4 +1,4 @@ -"""Family canon's adoption ledger (milestone 463 step 4). +"""Family canon's adoption ledger. Promotion (services/family.py) decides that an idea is canon for some platforms. This module decides what each project on those platforms does @@ -44,7 +44,7 @@ The losing side's reasoning is folded into the idea's note — as a trap, an alternative, or the branch for its condition — and is never dropped. The substance changed, so the version moves. -SHAPES (step 5). The shape ledger answers too: a shape classified against an +SHAPES. The shape ledger answers too: a shape classified against an idea's reference — in any language — is the project's code saying `adopted` (an instance) or `variant` (with the shape's reason). The two ledgers never disagree: a classification moves the row, an assessment or undo the shapes @@ -77,7 +77,7 @@ logger = logging.getLogger(__name__) # --- the assessment and the conflict order, as product text -------------------- # -# Judged on every install (rules 115, 119); the tool docstrings quote them. +# Judged on every install by the same text; the tool docstrings quote them. OUTCOMES = ( { @@ -241,8 +241,9 @@ def needs_recheck(row_status: str, row_version: int | None, idea_status: str, def _row_state(row: FamilyAdoption) -> dict: - """An answer as a decision's before/after. No ids (the #3182 trap): the - owed task is the row's column, not part of the snapshot.""" + """An answer as a decision's before/after. No ids, because an id inside + JSON cannot be remapped by a restore: the owed task is the row's column, + not part of the snapshot.""" return {"status": row.status, "reason": row.reason or "", "canon_version": row.canon_version} @@ -294,7 +295,7 @@ async def _project_languages(session, project_id: int) -> list[str]: return [r[0] for r in rows] -# --- the shape ledger as evidence (milestone 463 step 5) ---------------------------- +# --- the shape ledger as evidence --------------------------------------------------- # # A shape classified against an idea's reference IS an answer to the idea: an # `instance` — or the reference's own `canonical` location — says the project @@ -618,7 +619,7 @@ async def adoption_matrix( select(Note).where(Note.id.in_(task_ids), Note.deleted_at.is_(None)) )).scalars().all() } if task_ids else {} - # The code that answers each cell (step 5): live shapes classified + # The code that answers each cell: live shapes classified # against one of the idea's references. evidence: dict[tuple[int, int], list[dict]] = {} for iid, shape in (await session.execute( @@ -1215,7 +1216,7 @@ async def _shapes_follow(user_id: int, project_id: int, idea_id: int, outcome: s return int(result.get("classified") or 0) -# --- delivery (milestone 463 step 6) ------------------------------------------------- +# --- delivery ----------------------------------------------------------------------- # # The ledger reaches a session three ways: a count on entering a project, the # ideas themselves by retrieval, and the owed answers filed while a task was diff --git a/src/scribe/services/retrieval_surfaces.py b/src/scribe/services/retrieval_surfaces.py index ca997bc2..a2217e62 100644 --- a/src/scribe/services/retrieval_surfaces.py +++ b/src/scribe/services/retrieval_surfaces.py @@ -1,34 +1,19 @@ -"""One registry of the retrieval surfaces, and the two numbers each one has (#4102). +"""One registry of the retrieval surfaces, and the two numbers each one has. WHY THIS EXISTS -Six push arms each carried their own loose copy of the same shape: a settings -key, a default, and a limit that was usually a module constant nobody could -change. The read-and-clamp was written out separately in `plugin_context` (twice -over, for auto-inject and the write path), in three rule arms, and again in -the completion-report arm (since retired, milestone 500). That was survivable -while the numbers were shipped constants an operator occasionally edited. +Every push arm has the same shape: a settings key, a default, and a limit. A +floor is chosen and adjusted by the model that uses it, with the operator able +to touch it — and a tuning surface cannot be consistent for the model if every +arm spells its own configuration differently. So the arms do not own their +numbers; they read them from here, and the tuning tool, the routes and the +Settings UI all enumerate THIS table rather than hard-coding special cases. -It stops being survivable once the numbers are meant to MOVE. The operator's -decision for this step: - - "the floor should be chosen and adjusted by the model using it. we've come - back to something either fails or has to be looked at by the user we need a - model consistent surface for the adjustment of these floor values. the user - should be able to touch it but the model should be the thing handling it 9 - times out of 10." - -A tuning surface cannot be "model consistent" if every arm spells its own -configuration differently. So the arms stop owning their numbers and read them -from here instead, and the tuning tool, the routes and the Settings UI all -enumerate THIS table rather than hard-coding six special cases. - -WHAT A FLOOR IS NOW, AND WHAT IT IS NOT +WHAT A FLOOR IS, AND WHAT IT IS NOT It is not a relevance judgement. Relevance is decided by the reader, which is -the only participant that can read a trigger against a situation — that is the -milestone's whole argument, and the injected line has always said so out loud -("read it before deciding it does not apply"). +the only participant that can read a trigger against a situation — and the +injected line says so out loud ("read it before deciding it does not apply"). A floor answers the cheaper question: *is this worth ranking at all*. `k` is what binds, and `k` is a BUDGET — how much of this surface's attention a @@ -38,29 +23,21 @@ afford what an arm that fires once a turn can. WHY THE DEFAULTS BELOW ARE STARTING POINTS AND NOT ANSWERS A cosine score is a distance in BAAI/bge-small-en-v1.5's vector space, measured -against THIS corpus. It cannot transfer to an install with different records, -and rule 115 forbids defending a shipped default from this instance's -telemetry — which is what made the old design unbuildable: every number was a -guess everywhere except here, and there was no mechanism that could ever -improve it. - -The mechanism is the fix. Scribe ships a starting point and the means to -correct it, so the values below carry the measurement that motivated them (see -the long comments in `plugin_context.py`, which are kept where they are because -they record how each number was first arrived at) without claiming to be right -for anybody else. +against one corpus. It cannot transfer to an install with different records, +and a shipped default cannot be defended from any one install's telemetry. +Scribe ships a starting point and the means to correct it, so the values carry +the measurement that motivated them without claiming to be right for anybody +else. HOW A FLOOR SHOULD ACTUALLY BE MOVED By reading the records the floor refused — `retrieval_telemetry( near_miss_samples=N)` returns them by id — and never by the percentile alone. -That is not a style preference; it is the one case where the two disagreed and -was checked. `report_preference` logged 69 consecutive declines with the -refused score 0.0006 under the bar, and every percentile said "lower it". -Reading the refused record showed it was rule 77 "Extract intent from loose -phrasing", a false positive, so lowering the bar would have delivered that rule -on every completion report ever written. The statistic and the correct action -pointed in opposite directions, and only opening the record could tell. +An arm can log dozens of consecutive declines with the refused score a hair +under the bar while every percentile says "lower it", and the refused record, +once read, turns out to be a false positive that a lower bar would deliver on +every matching act. The statistic and the correct action can point in opposite +directions, and only opening the record tells them apart. """ from __future__ import annotations @@ -76,11 +53,10 @@ from scribe.services.retrieval_pipeline import ( # noqa: F401 - Surface re-expo MAX_BUDGET = 10 -# THE TABLE IS READ OFF THE SPECS (milestone 456 step 5). Each ranked arm in +# THE TABLE IS READ OFF THE SPECS. Each ranked arm in # `retrieval_pipeline` carries its own `Surface` — the floor and budget pair, # its settings keys and defaults, and the prose a tuner reads — so an arm added -# there is tunable by construction, and nothing here can drift from it. The -# keys and defaults are the ones this table held before the move, unchanged. +# there is tunable by construction, and nothing here can drift from it. SURFACES: dict[str, Surface] = { arm.tuning.name: arm.tuning for arm in TUNED_ARMS if arm.tuning is not None } @@ -88,10 +64,10 @@ SURFACES: dict[str, Surface] = { # Reserved slots are deliberately absent. `preference_slot`, `reuse_slot` and # `lesson_slot` borrow their parent arm's floor and are hard-limited to one hit # each, because their entire purpose is to guarantee a single line to a kind of -# record that keeps losing a general score contest (#2246, #3894) — or, for +# record that keeps losing a general score contest — or, for # `lesson_slot`, to a kind whose loss is total rather than merely a lost # convenience, since a lesson has no act arm to fall back on and nobody browses -# lessons looking for one (milestone 385). A budget of "1" is the feature; +# lessons looking for one. A budget of "1" is the feature; # exposing it as tunable would invite setting it to 0 and silently removing the # guarantee. #