feat: implement institutional governance and recovery architecture

2026-08-01 17:46:53 +02:00
parent 3c658fa32d
commit d78b13f9d3
45 changed files with 4388 additions and 262 deletions
@@ -0,0 +1,32 @@
+# Governed Communication Product Package
+
+This package composes Campaign, Mail, Postbox, Files, Templates, Policy, Audit,
+and Access into one governed-delivery capability. Modules retain their own
+tables and lifecycle. The package declares installation and configuration
+expectations; it does not import module internals.
+
+## Reference journey
+
+1. Select governed recipient and attachment data.
+2. Build and review an immutable Campaign version.
+3. Apply attachment, access, and delivery policy.
+4. Deliver through Mail and/or function-bound Postbox targets.
+5. Reconcile outcomes, acknowledgements, correction, and reports against Audit
+   evidence.
+
+## Reference-readiness gates
+
+The artifact remains a `product` package. Promotion to `reference` requires:
+
+- target-environment delivery and reconciliation tests, including an
+  outcome-unknown transport result;
+- backup/restore and interrupted-dispatch recovery evidence;
+- security evidence for recipient, attachment, and postbox isolation;
+- operator runbooks for queue health, retry, reconciliation, and retirement;
+- keyboard, focus, screen-reader, and responsive workflow evidence;
+- privacy evidence for minimization, purpose, retention, redaction, and report
+  access; and
+- version-pinned user and administrator documentation.
+
+Optional Notifications, Portal, Reporting, and Workflow Engine integrations do
+not change the package boundary when absent.
@@ -0,0 +1,34 @@
+{
+  "package_id": "product.governed-communication",
+  "name": "Governed Communication",
+  "version": "0.1.0",
+  "package_class": "product",
+  "description": "Compose evidence-backed campaigns, mail and function-bound postboxes without merging their domain ownership.",
+  "publisher": "GovOPlaN",
+  "category": "communication",
+  "license": "AGPL-3.0-or-later",
+  "required_modules": [
+    {"module_id": "access"},
+    {"module_id": "audit"},
+    {"module_id": "campaign"},
+    {"module_id": "files"},
+    {"module_id": "mail"},
+    {"module_id": "policy"},
+    {"module_id": "postbox"},
+    {"module_id": "templates"}
+  ],
+  "optional_modules": [
+    {"module_id": "notifications"},
+    {"module_id": "portal"},
+    {"module_id": "reporting"},
+    {"module_id": "workflow_engine"}
+  ],
+  "evidence": [
+    {
+      "kind": "documentation",
+      "reference": "packages/product/governed-communication/README.md",
+      "summary": "Defines the package boundary, journey, and reference-readiness gates."
+    }
+  ],
+  "tags": ["campaign", "mail", "postbox", "public-sector"]
+}
@@ -0,0 +1,41 @@
+# Governed Data and Assurance Product Package
+
+This package composes Datasources, Dataflow, Reporting, Search, Risk
+Compliance, Policy, Audit, and Access. Connectors may acquire external data,
+but Datasources owns the governed catalogue and immutable snapshots; Dataflow
+owns transformation definitions and runs; Reporting owns measures and
+presentation; Risk Compliance owns controls, findings, and effectiveness
+review.
+
+## Reference journey
+
+1. Register a typed datasource with source authority, purpose, classification,
+   owner, freshness, and correction policy.
+2. Acquire or upload an immutable source state.
+3. execute a versioned flow and retain intermediate materializations and
+   provenance;
+4. publish a report or decision input against exact source and flow revisions;
+5. link obligation, governed object, risk, control, evidence, finding,
+   corrective measure, and effectiveness review; and
+6. search current authorized objects while preserving ownership and access
+   rechecks.
+
+## Reference-readiness gates
+
+The artifact remains a `product` package. Promotion to `reference` requires:
+
+- a target-tested monthly-data and sanctions-screening fixture with expected
+  outputs and complete provenance;
+- database/object-storage backup and restore plus interrupted-run recovery;
+- security evidence for datasource credentials, staged data, intermediate
+  states, search documents, and assurance references;
+- operator runbooks for stale sources, failed runs, index rebuilds, and graph
+  reconciliation;
+- accessibility evidence for the catalogue, graph editors, result inspection,
+  reports, and assurance graph;
+- privacy evidence for minimization, purpose, retention, field visibility, and
+  aggregate disclosure; and
+- version-pinned user and administrator documentation.
+
+Optional Connectors, Files, Notifications, and Workflow Engine integrations
+must remain capability-based and absence-safe.
@@ -0,0 +1,34 @@
+{
+  "package_id": "product.governed-data-assurance",
+  "name": "Governed Data and Assurance",
+  "version": "0.1.0",
+  "package_class": "product",
+  "description": "Compose governed sources, transformations, reports, search, controls and assurance evidence through stable contracts.",
+  "publisher": "GovOPlaN",
+  "category": "data-governance",
+  "license": "AGPL-3.0-or-later",
+  "required_modules": [
+    {"module_id": "access"},
+    {"module_id": "audit"},
+    {"module_id": "dataflow"},
+    {"module_id": "datasources"},
+    {"module_id": "policy"},
+    {"module_id": "reporting"},
+    {"module_id": "risk_compliance"},
+    {"module_id": "search"}
+  ],
+  "optional_modules": [
+    {"module_id": "connectors"},
+    {"module_id": "files"},
+    {"module_id": "notifications"},
+    {"module_id": "workflow_engine"}
+  ],
+  "evidence": [
+    {
+      "kind": "documentation",
+      "reference": "packages/product/governed-data-assurance/README.md",
+      "summary": "Defines the package boundary, provenance chain, and reference-readiness gates."
+    }
+  ],
+  "tags": ["datasources", "dataflow", "reporting", "assurance"]
+}
@@ -0,0 +1,42 @@
+# Governed Service To Decision
+
+This product package composes independently owned institutional semantics into
+one reconstructable administrative journey:
+
+```text
+Service discovery -> Case intake -> Party and representation -> Mandate
+resolution -> approval/deliberation -> formal Decision -> observed delivery
+effect -> record and review references
+```
+
+An installed Forms and Forms Runtime pair adds an alternative governed entry
+path before case/workflow handoff:
+
+```text
+Service discovery -> exact Form revision -> validated draft/submission
+                  -> receipt and handoff evidence -> Case or Workflow owner
+```
+
+Services, Cases, Parties, Mandates, Committee, and Decisions retain immutable
+provider-owned revisions for the parts they own. Portal, Cases, and Committee
+consume capabilities for cross-module semantics only. The package does not
+grant cross-module table access and can omit optional presentation, work,
+deliberation, delivery, or records modules while retaining explicit references
+to externally performed steps.
+
+## Security And Recovery
+
+Every provider is tenant-bound. Missing or conflicting authority fails closed.
+Protected Decision content has a separate permission. Writes are replay-safe
+and OCC-guarded. Database restore is the semantic-state recovery unit; file and
+communication effects remain governed by their owning providers and are linked
+through requested/observed effect, evidence, and audit references.
+
+The executable fixture in
+`tests/test_institutional_governance_journey.py` proves SQL-backed Service,
+Case, Party, Mandate, Committee meeting/agendum/vote/minute, and Decision state.
+`tests/test_institutional_service_journey.py` separately proves exact Portal
+Form launch, persisted submission provenance, and idempotent replay.
+Target-environment accessibility, security, operator, privacy,
+delivery-provider, and recovery evidence are still required before this product
+package may claim `reference_ready` maturity.
@@ -0,0 +1,59 @@
+{
+  "package_id": "product.service-to-decision",
+  "name": "Governed Service To Decision",
+  "version": "0.1.0",
+  "package_class": "product",
+  "description": "Carry one exact institutional context from service discovery and case intake through parties, authority, formal outcome, communication evidence, and review.",
+  "publisher": "GovOPlaN",
+  "category": "institutional-governance",
+  "license": "AGPL-3.0-or-later",
+  "required_modules": [
+    {"module_id": "audit"},
+    {"module_id": "cases"},
+    {"module_id": "decisions"},
+    {"module_id": "mandates"},
+    {"module_id": "parties"},
+    {"module_id": "policy"},
+    {"module_id": "portal"},
+    {"module_id": "services"}
+  ],
+  "required_capabilities": [
+    "cases.party_context",
+    "cases.service_intake",
+    "decisions.registry",
+    "mandates.resolver",
+    "parties.resolver",
+    "portal.service_directory",
+    "services.availability",
+    "services.definitions"
+  ],
+  "optional_modules": [
+    {"module_id": "approvals"},
+    {"module_id": "committee"},
+    {"module_id": "files"},
+    {"module_id": "forms"},
+    {"module_id": "forms_runtime"},
+    {"module_id": "postbox"},
+    {"module_id": "records"},
+    {"module_id": "tasks"},
+    {"module_id": "workflow_engine"}
+  ],
+  "evidence": [
+    {
+      "kind": "documentation",
+      "reference": "packages/product/service-to-decision/README.md",
+      "summary": "Defines the package boundary, authority path, recovery contract, and known operational limits."
+    },
+    {
+      "kind": "target_test",
+      "reference": "tests/test_institutional_governance_journey.py",
+      "summary": "Executes the SQL-backed provider composition from service discovery through persisted formal Decision reconstruction."
+    },
+    {
+      "kind": "target_test",
+      "reference": "tests/test_institutional_service_journey.py",
+      "summary": "Executes Portal delegation from an exact Service revision through an exact immutable Form revision to a replay-safe persisted submission."
+    }
+  ],
+  "tags": ["service", "case", "mandate", "party", "decision", "public-sector"]
+}