Add resource_tables_dirty(timestamp) diagnostic SQL function

[jason-p-pickering]

Summary

Adds a standalone, ops-only SQL diagnostic for DHIS2's analytics_rs_* resource tables, as a single
resource_tables_dirty.sql file:

• resource_tables_dirty(timestamp) RETURNS boolean — cheaply answers "do the resource tables need
  regenerating?" without running a full (expensive) /api/resourceTables build.
• resource_tables_dirty_detail(timestamp) RETURNS TABLE(resource_table text, reason text) — same
  checks, returns every reason that fired instead of a bare boolean, so a dirty result doesn't require
  guessing which table triggered it.

Each resource table has exactly one _rt_dirty_<name>(baseline) RETURNS TABLE(reason text) probe —
a single source of truth per table. resource_tables_dirty() is just
EXISTS (SELECT 1 FROM resource_tables_dirty_detail(baseline)). (An earlier revision split this
across two files with a parallel boolean checker and TABLE-returning checker per table; every fix
had to be applied twice, so they were merged.)

This is a diagnostic companion to dhis2_analytics_trigger.py, not wired into it yet. Longer-term
intent is to use this as the signal the Python trigger script checks before deciding whether to run
a full resource-table regen — this SQL function is the first step toward that.

Not a Flyway migration, not part of dhis2-core, no Java wiring — deploy manually via
psql -f resource_tables_dirty.sql.

Notable design points, found via live testing on a real 2.41 instance + tracing dhis2-core source

Several tables can be legitimately absent without meaning "stale" — each caused a permanent false
positive (resource_tables_dirty() reading TRUE forever, regardless of baseline) until traced to
its real cause instead of guessed at:

• analytics_rs_dataapprovalremaplevel / analytics_rs_dataapprovalminlevel: built by a separate
  generateDataApprovalResourceTables() method, never part of a plain /api/resourceTables call, and
  only invoked when isApprovalEnabled() — which traces down to
  keyIgnoreAnalyticsApprovalYearThreshold >= 0 (default -1 = disabled) AND approval levels existing.
  An earlier attempt assumed "usage" meant real dataapproval/dataapprovalworkflowlevels data
  existing — wrong; both "sl" and hmis have genuine approval data yet the tables still don't exist,
  because that data existing isn't the actual DHIS2 gate. Fixed to read the real setting.
• analytics_rs_dataset and analytics_rs_relationship: both version-gated. Neither exists in
  any DHIS2 2.41.x release — confirmed via GitHub compare against every 2.41.x tag — only from 2.42.0
  onward (dataset: commit 797fd1ed, DHIS2-16705; relationship: commit 7c7fb34e, merged
  2025-02-04). A missing table is only reported dirty when the schema is actually >= 2.42 (detected
  indirectly via flyway_schema_history, since this script has no DHIS2 API/Java dependency).

Test plan

• Deployed and validated against a local DHIS2 "sl" (Sierra Leone, schema 2.43.64) database.
• Mutation-tested each staleness type (BEGIN/ROLLBACK, never committed against test data):
  dataset.lastupdated change correctly flags all 3 dependent tables, then rolls back clean.
• Confirmed each false-positive fix flips to FALSE when the real DHIS2 gate condition isn't
  met, and correctly stays TRUE when there's genuine staleness or a table is missing at a
  schema version where it should exist (e.g. dropping analytics_rs_dataset on this 2.43.64
  schema in a rolled-back transaction still correctly reads dirty).
• Confirmed clean re-deploy over an already-deployed instance (old boolean-typed functions
  dropped before the new TABLE-returning ones are created, since Postgres refuses to change a
  function's return type via CREATE OR REPLACE).
• Deployed to hmis (2.41, live production) and confirmed clean baseline (1 genuine finding: indicatorgroupsetstructure staleness, a true positive) plus an end-to-end mutation test — inserting a new period (rolled back, never committed) correctly flipped analytics_rs_periodstructure dirty with reason "period row(s) missing from analytics_rs_periodstructure", confirming the exact scenario that originally motivated this script.

🤖 Generated with Claude Code