datastores: loadPhraseMap warms an empty map on a zero-row read — status/priority names can silently blank again

[SyniRon]

This was generated by AI — surfaced during the #194 swarm review (follow-up to #189).

Observation

datastores.(*Mysql).loadPhraseMap returns (emptyMap, nil) whenever the xf_phrase query succeeds but matches zero rows — no Warn, no error. The reference cache then warms a fully-empty status/priority map and every statusName/priorityName resolves to "" on 200s, with nothing surfaced anywhere.

This is the exact failure mode #189 just fixed (a wrong title prefix matched zero rows → empty map → blank names), still latent one layer down: the prefix is now correct, but any future drift that makes the query return zero rows reproduces it silently.

Why it matters

The status and priority phrase families are never legitimately empty in production. A zero-row read for those families therefore means something has drifted — e.g. another NF Tickets add-on phrase rename, a collation/charset change, or a language_id regression — and the symptom would again be blank statusName/priorityName on otherwise-healthy 200s, invisible to logs, metrics, and the golden corpus (which records over the fake datastore and never touches phrase tables).

Same silent-degradation class as the open cluster #145 / #154 / #155 (datastore reads degrading to empty/blank on fault without surfacing).

Possible directions (for triage to rule — deliberately not deciding here)

• Warn (and/or fail the cache refresh) when a must-be-populated reference family loads zero rows.
• Decide which families are "must be non-empty": status and priority almost certainly; prefix may be legitimately sparse.
• Whether this lands standalone or folds into the ValidateApiKey's fire-and-forget last_used_date UPDATE discards its error #145/datastores: collectSecondaryPositions discards the First() result — blank positions silently appended on outage #154/datastores: getLatestForumPostDates degrades to empty map on query error — lastForumPostDate silently blank on 200s #155 remediation.

Surfaced by the silent-failure review on PR #194. No fix attempted yet — needs-triage.

[SyniRon]

This was generated by AI during triage.

Agent Brief

Category: bug
Summary: The Mysql datastore warms a fully-empty status/priority phrase map on a zero-row read, silently blanking statusName/priorityName on healthy 200s.

Current behavior:
The phrase-map loader behind LoadStatusNames / LoadPriorityNames / LoadPrefixNames returns an empty map[uint32]string with a nil error whenever the underlying xf_phrase query succeeds but matches zero rows. The reference cache then warms a fully-empty status/priority map, and every statusName/priorityName resolves to "" on otherwise-healthy responses — with nothing surfaced in logs, metrics, or errors. This is the same failure mode #189 fixed at the title-prefix level, still latent one layer down: the prefix is correct now, but any future drift that makes the query return zero rows (another NF Tickets phrase rename, a collation/charset change, a language_id regression) reproduces blank names silently. Same silent-degradation class as the open cluster #145 / #154 / #155.

Note the intentional design: the reference cache deliberately holds individual missing records as empty-string/nil and never as an error, because new add-on-side records can appear before our next refresh. The bug is specifically the wholly-empty must-be-populated family case — not per-id misses.

Desired behavior:
A zero-row read for a reference family that is never legitimately empty (status and priority) is surfaced loudly instead of warming a blank map in silence. The prefix family may be legitimately sparse and stays exempt (at most informational). The existing tolerance for individual missing ids resolving to empty string is preserved — this is about the all-or-nothing empty-family case only.

Key interfaces:

• The Loader phrase-map methods on the Mysql datastore (LoadStatusNames / LoadPriorityNames return (map[uint32]string, error)) and the shared loader they delegate to — it currently cannot distinguish "a must-be-populated family came back empty" from "legitimately empty."
• referencecache.Loader / Cache.Refresh — Refresh already propagates loader errors. Decide whether a must-be-populated empty family should (a) emit a loud warning and still return the empty map, or (b) return an error that fails the refresh. Recommended default: (a) — warn loudly, naming the family, and do not hard-fail, so a single drifted family can't take down the rest of the reference cache (categories etc.). If you choose to fail, scope it so it cannot silently blank.
• The datastores package logger — the signal must reach the logs at minimum (a metric is welcome, not required).

Acceptance criteria:

• A zero-row read for the status family is surfaced at warning (or higher) severity, naming the family, rather than warming a blank map with no signal.
• Same for the priority family.
• The prefix family is not treated as a warning/error when empty (it may be legitimately sparse) — at most informational.
• A status/priority family that returns rows behaves exactly as today (no change on the healthy path).
• Individual missing ids within a populated family still resolve to empty string (the intentional new-add-on-record tolerance is preserved).
• A test exercises the zero-row case for a must-be-populated family and asserts the signal is emitted (the existing fake-Loader / cache tests are the natural home).

Out of scope:

• The ValidateApiKey's fire-and-forget last_used_date UPDATE discards its error #145 / datastores: collectSecondaryPositions discards the First() result — blank positions silently appended on outage #154 / datastores: getLatestForumPostDates degrades to empty map on query error — lastForumPostDate silently blank on 200s #155 remediations — sibling silent-failure issues; this one stands alone, do not fold them in.
• Changing the xf_phrase query, the LIKE prefix, or the documented status/priority/prefix title asymmetry (that asymmetry is correct per tickets: statusName/priorityName blank against real data — phrase loader queries wrong xf_phrase title prefixes #189 and the in-code CAUTION note — do not "normalise" it).
• Alerting/metrics beyond a log signal.

---

Dependency / sequencing (graph around #134):

• Independent of Phase 3 cutover: single listener, datastore type-swap, Keycloak removal, deliberate breaks live #134 — no blocking edge in either direction. The loader returns a plain map[uint32]string, which Phase 3 cutover: single listener, datastore type-swap, Keycloak removal, deliberate breaks live #134's proto→types datastore swap does not touch.
• Lands before Phase 3 cutover: single listener, datastore type-swap, Keycloak removal, deliberate breaks live #134. Same silent-degradation class as ValidateApiKey's fire-and-forget last_used_date UPDATE discards its error #145/datastores: collectSecondaryPositions discards the First() result — blank positions silently appended on outage #154/datastores: getLatestForumPostDates degrades to empty map on query error — lastForumPostDate silently blank on 200s #155, and it edits the same datastore source the Phase 3 type-swap rewrites — landing this small guard first keeps it out of the high-risk cutover diff and carries the hardening through. It does not gate Phase 3 cutover: single listener, datastore type-swap, Keycloak removal, deliberate breaks live #134.