Summary
hotspot_family_ready is set true if the family_key and container_qualified_name columns exist and the metadata version stamp matches. It does not sample any rows to verify they actually carry non-null, current family_key values. A maintenance pass that adds the columns and writes the stamp but only partially restamps rows leaves ready=true while half the symbols carry stale or null values.
Evidence
src/CodeIndex/Database/DbReader.cs:395-415 — LoadHotspotFamilyReadyLanguages():
- Line 398: checks column existence.
- Lines 403-408: checks metadata stamp.
- No row-sampling to verify data.
Impact
- Hotspot family queries return inconsistent grouping for languages where the data is partially restamped.
- Status JSON falsely advertises readiness; users cannot tell their hotspot data is incomplete.
Proposed direction
- After the metadata stamp check passes, sample a small number of rows (e.g. 10) per language and verify their
family_key is non-null. If any sampled row is null, mark the language as not-ready and emit a degraded_reason: "partial_family_key_population".
- Bonus: store a row-count of "stamped vs total" alongside the readiness bit so UIs can show progress.
Repro env
- Branch:
main @ 2ee912d (release v1.21.0)
Summary
hotspot_family_readyis set true if thefamily_keyandcontainer_qualified_namecolumns exist and the metadata version stamp matches. It does not sample any rows to verify they actually carry non-null, currentfamily_keyvalues. A maintenance pass that adds the columns and writes the stamp but only partially restamps rows leavesready=truewhile half the symbols carry stale or null values.Evidence
src/CodeIndex/Database/DbReader.cs:395-415—LoadHotspotFamilyReadyLanguages():Impact
Proposed direction
family_keyis non-null. If any sampled row is null, mark the language as not-ready and emit adegraded_reason: "partial_family_key_population".Repro env
main@ 2ee912d (release v1.21.0)