feat: implement governed reporting vertical

2026-08-01 17:48:39 +02:00
parent 720959536b
commit eba35edd3c
35 changed files with 8414 additions and 33 deletions
@@ -0,0 +1,40 @@
+# 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.
+
+## 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.
+
+## 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.