govoplan-reporting/docs/OPERATIONS.md

Reporting Operations, Security, and Recovery

Runtime behavior

Reporting API nodes are stateless. Definitions, executions, schedules, publication evidence, and import/quality evidence live in the shared platform database. Dataset bytes remain with their source owner; large durable output files belong in a publication provider backed by shared object storage.

Run and schedule idempotency keys make retries replay-safe. Schedule workers claim bounded batches, retain success or failure state, and advance interval time from the claimed occurrence. Providers must use the same tenant and principal context and must enforce their source-side authorization.

Provider-report executions and exports are database evidence. Each execution stores the exact provider/report revision, request hash, source revisions, effective scope, applied privacy transforms, governance decision provenance, generation actor/time, retention expiry, and output hash. Export rows retain their own purpose, audience, actor/time, format, and hash. Expired provider results are rejected by retrieval and export paths; run the platform privacy retention process on schedule to remove or minimize expired stored detail in accordance with the active Policy.

Security controls

• The semantic engine never evaluates Python, browser code, raw SQL, stored procedures, or imported runtime scripts.
• Definition and execution APIs require explicit module scopes and a tenant-bound principal.
• Restricted access is normalized into grants and rechecked before definitions or execution history are returned.
• Row-policy providers may only reduce a dataset; returning more rows than the source read fails closed.
• Freshness, schema, fingerprints, quality gates, definition hashes, source provenance, actor, and output hash are retained with every run.
• CSV formula injection is neutralized before direct download.
• Provider exceptions are isolated in catalogue diagnostics; an unavailable optional provider cannot take down the global report catalogue.
• High re-identification-risk provider reports fail closed unless an installed Policy capability explicitly permits them.

Backup and restore

Back up the shared database and every object-storage publication target as one recovery set. Before destructive module retirement, take and verify a database snapshot; retirement removes definitions, result evidence, schedules, and publication records. Restore the database first, then target object storage, then reconcile provider publications by their idempotency/evidence references.

After restore, verify migrations, definition parent pins, schedule enablement, execution counts and hashes, and publication target health before dispatching due schedules. Do not claim successful recovery until an operator has run and recorded the deployment-specific drill.