feat(indicators): integrate versioned reporting contracts

[Duvet05]

Outcome and scope

Integrate Anderson's pending reportes-sql work with the indicators frontend: immutable definitions, catalogue filters, goals, canonical/history results, annual recalculation and consistent aggregate series. A changed nested filter creates a new version; multiple matching diagnoses count a single encounter; a failed version/metadata write rolls back the whole operation. Concurrent calculations preserve history and select one current result per indicator/month.

Related to https://github.com/sihsalus/sihsalus-frontend.tasktree/issues/36 (partial implementation; do not close). Coordinated frontend draft: sihsalus/sihsalus-frontend#1069 (head fe587e2c1; technical CI passed).

Functional source: dev through 3f5fd70eae2184920b3063d0deda5ea416207460, with Anderson credited as co-author. Excludes later local debugging configuration, private agent state and unrelated dependency cleanup. Existing main behavior is the base; this branch introduces no hospital access or deployment.

Contracts and data

• Business routes revalidate the OpenMRS session, use the existing app:indicadores module privilege, and additionally require a configured institutional privilege for mutations/recalculation. An unset write privilege denies writes.
• Same-origin gateway /openmrs/services/reportes-sql, separate catalogue service account and SELECT-only source MySQL account. No roles are created or assigned.
• PostgreSQL gets additive ledger/metadata tables. Canonical backfill v2 preserves all rows, never reactivates explicit history, chooses one winner across versions and records its marker in the same locked transaction. Startup fails and rolls back if the marker fails.
• Quarterly/annual series are sums of monthly values, not unique patients across months; versiones is a number array. Windowed-patient attribution and indicator definitions require institutional approval.

Validation evidence

Status	Command/case	Result	Scope
PASSED	yarn install --immutable	Exit 0, own worktree dependencies	Local Node 24
PASSED	yarn test --runInBand	22 suites, 509 tests	Synthetic unit/router tests on this diff
PASSED	yarn build	Exit 0	Production TypeScript
PASSED	node --check scripts/test-database-contract.mjs and git diff --check origin/main...HEAD	Exit 0	Harness syntax and diff
PASSED	PostgreSQL and MariaDB contract CI job	All contract groups passed; synthetic cleanup completed	Head cce6230e: https://github.com/sihsalus/reportes-sql/actions/runs/35677413338 — real SQL counts, source read-only grants, migration failure/restart, 8 concurrent calculations, CRUD rollback and HTTP series shape
BLOCKED	DEV/QLTY integration and functional acceptance	Institutional session representation, effective privileges, gateway, content/catalogues, expected calculations and management users remain unvalidated	No authorized DEV/QLTY fixtures or configured institutional write policy in this iteration

Regression cases reproduced before fixes: nested definition changes, encounter-type validation and all count modes with repeated diagnoses. Real database tests refuse nonempty databases and remove synthetic fixtures on completion. The final CI run also passes Node 22 unit tests/build. The first database run exposed an incorrectly shaped synthetic privilege object; the fixture now uses the OpenMRS display representation. No production guard or assertion was relaxed.

Rollout and rollback

High risk: calculations and PostgreSQL canonical metadata change. Keep draft until database CI and institutional acceptance pass. Rehearse startup on a recoverable de-identified PostgreSQL copy; retain the existing PostgreSQL volume and OpenMRS database, disable automatic seeding, configure the approved write privilege/catalogue account and deploy coordinated pinned versions through the gateway. The distribution configuration still needs that coordination.

Stop on changed source data, lost history, duplicate canonical rows or mismatched approved calculations. Reverting an image alone does not reverse canonical metadata; PostgreSQL recovery requires the verified pre-upgrade backup. No merge or deployment is requested by this PR.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}