Sync Repo-docs-INSTITUTIONAL-GOVERNANCE-TARGET-ARCHITECTURE from project files

Repo-docs-INSTITUTIONAL-GOVERNANCE-TARGET-ARCHITECTURE.-.md

@@ -1,4 +1,4 @@
-<!-- codex-wiki-sync:b69ec174cdf58e1ed7d06d7f -->
+<!-- codex-wiki-sync:1e1ef481f23c7d0c43f4d250 -->
 
 > Mirrored from `/mnt/DATA/git/govoplan/docs/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md`.
 > Origin: `repository`.
@@ -17,7 +17,7 @@ concepts prepared outside the repositories:
 
 The source concepts describe GovOPlaN as an operational governance platform for
 public institutions. This document merges that direction with the implemented
-platform state as of 2026-07-31. It is the canonical repository version of the
+platform state as of 2026-08-01. It is the canonical repository version of the
 direction. Gitea issues remain the source of truth for delivery state.
 
 Read this together with:
@@ -86,15 +86,16 @@ were proven now have independent persistent owners:
 
 | Area | Implemented state | Remaining rollout |
 | --- | --- | --- |
-| Module portfolio metadata | Core validates versioned architecture layer/kind, maturity evidence, known limits, ownership boundaries, authority modes, reference packages, target-tested providers, and migration/upgrade/recovery/security/operations documentation. | Complete for all 60 source manifests. Focused and release checks enforce `--require-architecture`; a new module cannot enter the workspace without truthful declaration and repository-local evidence. |
+| Module portfolio metadata | Core validates versioned architecture layer/kind, maturity evidence, known limits, ownership boundaries, authority modes, reference packages, target-tested providers, and migration/upgrade/recovery/security/operations documentation. | Complete for all 62 source manifests. Focused and release checks enforce `--require-architecture`; a new module cannot enter the workspace without truthful declaration and repository-local evidence. |
 | External providers | Core validates provider objects/field groups, operations, integration maturity, source authority, bounded reads, freshness/health, idempotency, conflicts, outcome-unknown handling, evidence, correction, reconciliation, outage, classification, purpose, retention, and secret handling. Addresses/CardDAV, Files remote storage, Mail SMTP/IMAP, Calendar CalDAV/ICS/Graph/EWS, and Connectors tabular/sanctions providers declare the contract and tenant-bounded secret-free runtime state. | Registry validation rejects any declared external provider without a sanitized state provider. Future adapters must cross the same gate before activation. |
 | Institutional context | Core provides versioned temporal, actor/representation, institution/unit/function/task/mandate/jurisdiction/service/case/party/work-item/workflow/approval/decision/record, legal-basis, evidence, information-governance, external-source, presentation, and geographic references. Events, automation actions, audit records, and the transactional Audit outbox preserve the envelope. | Owning modules must progressively require the relevant subset for consequential operations. |
 | Semantic provider contracts | Provider-neutral DTOs and protocols cover Mandate resolution, versioned Service definitions, procedure Parties/representation, and formal Decisions. `govoplan-mandates`, `govoplan-services`, `govoplan-parties`, and `govoplan-decisions` now persist immutable revisions behind those contracts with tenant isolation, bounded reads, replay safety, OCC, migrations, uninstall guards, permissions, APIs, capability documentation, and recovery documentation. | The owners are deliberately headless. Procedure-specific UI remains with consuming modules. |
-| Formal-outcome proof | Committee resolves effective Mandate authority and records a reconstructable formal Decision through `decisions.registry` when installed, while retaining an optional local projection when it is absent. Decision corrections, revocations, supersession, protected reads, and stale updates use the shared immutable revision rules. | Committee meeting/agendum/vote persistence remains Committee product depth, not a missing Decisions architecture primitive. |
-| Service-to-case proof | Services owns the persistent exact definitions consumed by Portal discovery and Cases intake. Publication and availability remain separate, restrictive derivation cannot widen parent constraints, and the provider hides draft/retired definitions from general discovery. | Portal and Cases remain headless vertical slices; their later WebUI/persistence depth does not alter Service ownership. |
+| Formal-outcome proof | Committee persists bodies, meetings, agenda items, votes, minutes, lifecycle events, and an optional protected local Decision projection. It resolves effective Mandate authority and records reconstructable formal Decisions through `decisions.registry` when installed. OCC, replay safety, tenant isolation, bounded reads, closure guards, and a full-height body/meeting/agenda/vote/minutes WebUI cover the aggregate. Provider-bound external or secret ballots use dynamic adapter capabilities; Committee validates and retains only aggregate counts, receipt/hash, and evidence, and rejects generic manual closure. | Concrete ballot-provider packages remain integration work because their protocol, custody, credentials, and operator evidence depend on the selected provider. This does not leave a Committee-owned ballot contract unspecified. |
+| Service-to-case proof | Services owns the persistent exact definitions consumed by Portal discovery and Cases intake. Forms owns immutable form schemas and Forms Runtime owns definition-aware drafts, validation, submission receipts, status/evidence history, and handoff references. Portal exposes a tenant-scoped service-directory WebUI whose audiences derive from trusted principal/function state, re-fetches the exact Service revision, and delegates URL, Case, Form, or Workflow launch to an installed owner. Cases and Forms Runtime retain exact Service and binding provenance, enforce tenant isolation, replay safety and OCC, and expose bounded owner/manager APIs and WebUI. | Anonymous intake, concrete attachment/signature adapters, conditional multi-page authoring, and automatic domain handoff execution are product depth on established contracts. Portal still fails closed and explains any absent launcher or runtime prerequisite. |
 | Procedure-party proof | Parties persists effective procedure roles, frozen contact snapshots, and representation powers. Existing powers cannot disappear or be silently rewritten; explicit OCC-guarded revocation is required. Cases resolves the provider capability and excludes expired/revoked authority from downstream delivery. | Procedure modules still decide which contextual fields and actions to present. |
-| Integrated institutional journey | The executable `product.service-to-decision` fixture uses real SQL-backed Services, Parties, Mandates, and Decisions providers. It carries one exact Service version through Portal discovery, Case intake, representation and frozen delivery authority, effective Mandate resolution, approval context, a persisted formal Committee Decision, confirmed Postbox effect, Audit/record evidence, remedy/review, and protected reconstruction. | This is architecture and composition evidence. Target accessibility, privacy, operator, delivery-provider, and recovery-drill evidence is still required before the package may claim `reference_ready`. |
-| Governed data catalogue | Datasources stores typed governance metadata, exposes bounded tenant-scoped filters and update APIs/UI, carries governance through staging, and snapshots it into immutable materializations. | Rich dependency/impact traversal and policy-specific field visibility can grow on the catalogue contract without moving connector or transformation ownership. |
+| Integrated institutional journey | The executable `product.service-to-decision` fixture uses real SQL-backed Services, Cases, Parties, Mandates, Committee, and Decisions providers. It carries one exact Service version through persisted Case intake, representation and frozen delivery authority, effective Mandate resolution, a body/meeting/agendum/vote/minute sequence, a persisted formal Decision, confirmed Postbox effect, Audit/record evidence, remedy/review, and protected reconstruction. A second executable path proves Portal to exact Form revision, persisted submission, and idempotent replay. | This is architecture and composition evidence. Signed, release-bound target accessibility, privacy, security, operator, delivery-provider, and recovery-drill evidence is still required before the package may claim `reference_ready`. |
+| Governed data catalogue | Datasources stores typed governance metadata, exposes bounded tenant-scoped filters and update APIs/UI, carries governance through staging, and snapshots it into immutable materializations. Reporting now persists immutable dataset, semantic-model, report, quality-plan, saved-view, and schedule revisions; executes typed semantic queries with quality gates, access checks, replay, pivoting, export/import assessment, and provenance; and exposes the governed analytical WebUI. | Rich dependency/impact traversal, additional expression functions, and policy-specific field visibility can grow on the established contracts without moving connector, transformation, or source ownership. |
+| Portfolio and change governance | Projects now persists tenant-safe, immutable portfolio/project/milestone revisions with OCC, replay, lifecycle rules, restricted memberships, Search ACL indexing, outcomes, benefits, dependencies, capacity assumptions, change impact, and institutional references. Its WebUI exposes the planning catalogue and core planning fields. | Advanced planning structures already accepted by the API can receive deeper specialized editors without creating a second Policy, Reporting, Resources, or Goals owner. |
 | Product/package governance | Signed configuration packages distinguish reference, product, sector, deployment, and integration classes; preserve parent/evidence provenance; prevent derived packages from loosening constraints; and preflight provider authority, maturity, exact binding, health, freshness, and recovery expectations. Executable product manifests now exist for governed communication and governed data/assurance and are checked in the module matrix. | Both artifacts deliberately remain product-class until target, accessibility, privacy, security, operations, and recovery evidence justifies reference readiness. |
 | Projection and release | Platform metadata, signed module catalogs, release synthesis, Ops, and role-aware Docs retain and display architecture/provider declarations. Module-owned state providers add bounded configured/active, authority, health, freshness, conflict, recovery, and observation state; ordinary-user Docs omits binding detail. Static checks validate evidence paths, and the WebUI build verifies consuming types. | Runtime-state adoption and broader portfolio presentation follow truthful provider declaration rollout. |
 
@@ -395,7 +396,7 @@ submodule, configuration fragment, package, or profile.
 
 - This reconciliation is canonical in the meta repository and mirrored to the
   Gitea wiki.
-- All 60 source manifests carry validated evidence-based architecture metadata.
+- All 62 source manifests carry validated evidence-based architecture metadata.
 - External-reference, action/effect, operational-health, ownership, policy,
   audit, and documentation primitives compose into one enforced provider
   declaration and sanitized runtime-state contract.
@@ -409,8 +410,9 @@ submodule, configuration fragment, package, or profile.
   transitions, persistence providers, APIs, permissions, migrations, recovery,
   and tests are implemented.
 - Committee and the SQL-backed institutional fixture prove effective-time
-  authority, approval context, reasoning, evidence, observed effect,
-  correction/revision rules, protected reconstruction, and review references.
+  authority, persisted meeting/agendum/vote/minute context, approval context,
+  reasoning, evidence, observed effect, correction/revision rules, protected
+  reconstruction, and review references.
 - The independent Mandates and Decisions repositories were created only after
   persistence and reuse passed the repository threshold.
 
@@ -422,18 +424,22 @@ submodule, configuration fragment, package, or profile.
   representation/revocation authority; Cases consumes the common resolver.
 - `product.service-to-decision` proves both through a portable administrative
   service composition.
+- Forms owns immutable, versioned schemas while Forms Runtime owns drafts,
+  server validation, submission receipts, status/evidence history, and exact
+  Service/Form provenance. Portal delegates Form launch through the runtime
+  capability and fails closed when it is unavailable.
 
-### 3. Complete governed data and assurance - architecture complete
+### 3. Complete governed data, portfolio, and assurance - vertical slices complete
 
 - Datasources carries typed governance through staging and immutable
   materializations, with bounded catalogue filters and dependency references.
-- Reporting owns semantic presentation/provenance contracts without taking
-  source or transformation ownership; feature depth remains on its module
-  backlog.
+- Reporting owns immutable semantic definitions, safe execution, quality gates,
+  provenance, schedules, saved views, pivoting, and export/import assessment
+  without taking source or transformation ownership.
 - Risk Compliance persists the horizontal obligation/risk/control/evidence/
   finding/measure graph and projects sanctions runs idempotently.
-- Projects declares portfolio/outcome ownership as a consuming domain without
-  becoming a second policy or reporting engine.
+- Projects persists portfolio/outcome/change-governance revisions as a
+  consuming domain without becoming a second policy or reporting engine.
 
 ### 4. Package repeatable public-sector outcomes - complete at product maturity
 
@@ -445,6 +451,36 @@ submodule, configuration fragment, package, or profile.
   recovery, accessibility, privacy, security, and operator evidence. This is a
   maturity gate, not missing architecture implementation.
 
+## What remains after the executable architecture slice
+
+The remaining work is not another Core or cross-module architecture rewrite.
+It falls into two explicitly different categories, neither of which can be
+truthfully completed by adding generic platform code:
+
+1. **Concrete provider packages:** the Committee ballot adapter contract is
+   complete, but a real secret/electronic ballot provider requires a selected
+   protocol and product decisions for voter eligibility, custody, secrecy,
+   recount, challenge, retention, and operational assurance. Equivalent future
+   adapters must satisfy the declared provider and recovery gates.
+2. **Target-produced maturity evidence:** `reference_ready`, `supported`, and
+   `lts` cannot be generated from source code. An exact release and deployment
+   must produce signed, expiring accessibility, privacy, security, operator,
+   provider, backup/restore, rollback, and recovery-drill evidence. The verifier
+   and schemas are implemented; the actual claims require those real runs.
+
+Forms and Forms Runtime no longer constitute an architecture gap. Remaining
+depth includes anonymous/public identity profiles, concrete file and signature
+providers, conditional multi-page/localized authoring, and automatic handoff
+adapters. Those additions use the implemented immutable definition, runtime,
+policy, evidence, service-launch, and domain-owner boundaries rather than
+requiring another platform split.
+
+Everything else described as architecture in this document now has a
+repository owner, versioned contract, bounded implementation, migration and
+recovery boundary where state exists, documentation, and executable evidence.
+Further work in those modules is product breadth, UX depth, provider adoption,
+and evidence renewal.
+
 ## Delivery tracking
 
 The completed cross-repository architecture epic is
@@ -474,7 +510,11 @@ Its implementation work packages and resulting owners are:
 - [GovOPlaN #34](https://git.add-ideas.de/GovOPlaN/govoplan/issues/34):
   product and sector package classes; and
 - [Docs #19](https://git.add-ideas.de/GovOPlaN/govoplan-docs/issues/19):
-  configured architecture, maturity, and source-authority explanations.
+  configured architecture, maturity, and source-authority explanations;
+- [Forms #2](https://git.add-ideas.de/GovOPlaN/govoplan-forms/issues/2):
+  immutable reusable definitions and the designer surface; and
+- [Forms Runtime #1](https://git.add-ideas.de/GovOPlaN/govoplan-forms-runtime/issues/1):
+  definition-aware submissions and Portal service launch.
 
 Existing Projects #1, Reporting #4, Portal #1, Cases #1, Datasources #1,
 Risk Compliance #2, GovOPlaN #14, and GovOPlaN #19 carry product-depth and
@@ -487,9 +527,12 @@ The architecture direction is established by the following executable and
 machine-enforced evidence:
 
 - the `product.service-to-decision` composition and SQL-backed golden fixture
-  retain institutional context from service entry through case, party,
-  authority/work context, decision, observed communication effect, record, and
-  review references;
+  retain institutional context from service entry through a persisted case,
+  party, authority/work context, committee deliberation, decision, observed
+  communication effect, minute/record, and review references;
+- the Portal/Form journey retains the exact published Service and Form
+  revisions through persisted draft state, validates on the server, and returns
+  the same submission on an idempotent launch replay;
 - the system can answer who acted, for whom, in which function, under which
   mandate and jurisdiction, using which rule and evidence versions;
 - every implemented external binding declares authority mode, maturity,
@@ -506,3 +549,7 @@ machine-enforced evidence:
 These criteria complete the architecture contract at `vertical_slice` and
 `product` maturity. They do not waive the separately enforced evidence needed
 for a module or package to claim `reference_ready`, `supported`, or `lts`.
+The capability-fit verifier now computes that cumulative readiness gate from
+independently signed, expiring claims bound to the exact assessed release,
+installed payload, deployment subject, controls, and artifact hashes. Actual
+target runs and recovery drills remain operator-produced evidence.