docs(adr): record D45 producer seam + ledger hygiene#708
Merged
Conversation
Rewrite ADR-D45 to the mechanism traced to code and data on 2026-07-10: a producer seam, not a value skew and not a storage problem. The six LAFA signals are declared in protea-contracts feature_schema.py yet _lafa_default_fields() in _leaf_record_builder.py emits classifier and association columns as a constant 0.0 because their producers were never wired into the export. The name-level fingerprint (compute_feature_schema_sha) matched throughout, so three declared families shipped semantically null with no check firing. Record the decisions: no silent default (emit NaN or refuse), an export degeneracy check, and per-family provenance via the signal store. Note what D45 is NOT: typing the six columns is a separate additive storage win that does not close the seam. Honest scope: the sealed 0.4063 champion was trained without those families, so the number is intact. Ledger hygiene: - index.rst intro: correct the stale ranges (implementation 001-009, strategic D1-D45) and note the D-series is a PROTEA-local ledger. - Add a cross-repo disambiguation note: PROTEA D39/D40/D41 collide with different decisions of the same number in protea-reranker-lab; not renumbered because the PROTEA numbers are already cited, so qualify the lab records as lab-D39 etc. - Mark D38 Superseded on its champion designation (learned encoder d8979601 at f_micro_w 0.4063 on the v227 to v230 frame supersedes the prostt5 0.7291 designation), using the existing :Superseded-by: field convention.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #708 +/- ##
===========================================
- Coverage 88.90% 88.85% -0.05%
===========================================
Files 237 245 +8
Lines 17692 18481 +789
===========================================
+ Hits 15729 16422 +693
- Misses 1963 2059 +96 🚀 New features to boost your workflow:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Docs-only. Writes ADR-D45 with the mechanism traced to code and data on
2026-07-10, and fixes three ledger-hygiene defects.
ADR-D45: the producer seam (rewritten)
D45 already existed (dated 2026-06-22) but framed the seam as a train/serve
value skew. On 2026-07-10 the mechanism was traced and is narrower: a
producer seam, not a value skew and not a storage problem.
compute_schema_sha(feature_schema.py:253) andcompute_feature_schema_sha(feature_schema.py:273) hash sorted column names / family membership through
short_sha(_hashing.py:29,sha256[:12]). Neither can see a value orwhether a producer ran.
feature_schema.py:NUMERIC_FEATURESlines 113, 114, 116, 119, 120, 121;FEATURE_FAMILIESclassifier(232),self_prior(233),association(234).0.0._lafa_default_fields()(
protea/core/_leaf_record_builder.py:342) returns them as0.0; itsdocstring: the
classifier_*andassociation_*columns "stay zero untillater lafa-integrate slices wire their producers. A well-defined zero, not
NaN, matching the lineage convention." (The prior note naming
_reranker_default_fields()was wrong; that method at line 34 fills the KNNblock, not the six LAFA columns.)
protea-reranker-lab/results/clean_227230/comparison.jsonhasfeature_exclusions= "association_* and classifier_* (zero-filled inexport) + ...".
go_prediction.featureson2026-07-10 shows 0.0% zeros for
association_totalandclassifier_score.Decisions adopted: no silent default (emit
NaNor refuse); an exportdegeneracy check (a constant declared family fails the job loudly); per-family
provenance (
SignalConfig.sourceof the signal store). Not D45: typing thesix columns is a ~2.5 GB additive storage win (drops the ~75 GB duplicated
featuresJSONB) that does not close the seam. Honest scope: thesealed champion (
f_micro_w0.4063, v227 to v230) was trained without theclassifier and association families, so the number is intact; the seam
silently removed three declared families from the model's reach.
Ledger hygiene
D1-D31while theseries runs to
D45(and the implementation range read001-008while009exists). Corrected both, and clarified thatD1-D31came from masterplan rev 3 while later records were added as the work progressed.
D39/D40/D41(destructive-opguards, leakage-free temporal eval, lean f32 refpool) collide with
protea-reranker-labD39/D40/D41(FAIR dataset packaging, IA-alignedtraining, universal booster).
D34is intentionally the same decision inboth. Resolved by a disambiguation note rather than renumbering, because the
PROTEA numbers (especially D40) are already cited across docs, memory, and
thesis; qualify the lab records as
lab-D39etc.prostt5k=5 binary, Fmax0.7291 on v226) is superseded by the sealed board (learned encoder
d8979601,f_micro_w0.4063 on the v227 to v230 frame under D40 + D43).Marked with the existing
:Superseded-by:field convention (as D09 uses) andStatus
Supersededin the index.Verification
check_no_em_dashes.py: OK, 0 violations.check_doc_refs.py: 199 broken refs before and after (all pre-existingautodoc
:module:/:func:/:class:roles on a cleandevelop; this PRadds none).
check_smells.py: OK, no new offenders.Note on the task premise
The task stated D45 "has never been written down." It existed with a
mis-stated (value-skew) mechanism; this PR corrects it in place rather than
creating a duplicate. Details in the agent report.