feat: add institutional governance and recovery contracts
This commit is contained in:
@@ -99,6 +99,22 @@ The runner must never advance workflow state past a required side effect unless
|
||||
the action definition explicitly allows asynchronous completion and the pending
|
||||
state is visible.
|
||||
|
||||
For external and asynchronous effects, providers must preserve the distinction
|
||||
between:
|
||||
|
||||
1. requested intent;
|
||||
2. approved intent;
|
||||
3. dispatched command;
|
||||
4. possibly executed but unconfirmed outcome;
|
||||
5. confirmed observed effect;
|
||||
6. reconciled, corrected, or compensated outcome.
|
||||
|
||||
An API timeout after dispatch is not a failed effect and must not be retried as
|
||||
a fresh command. The actor context should retain the real identity/account,
|
||||
represented function or party, delegation or power, and mandate/jurisdiction
|
||||
references when applicable. Domain modules remain responsible for deciding
|
||||
which of those references are required for their action.
|
||||
|
||||
## Failure States
|
||||
|
||||
Automation should use explicit failure states:
|
||||
|
||||
@@ -49,6 +49,15 @@ The broad writable root reduces approval churn. The explicit project trust entri
|
||||
|
||||
Each active repository has an `AGENTS.md` file. These files define ownership, module boundaries, and focused commands for Codex. Keep durable project conventions there instead of repeating them in every prompt.
|
||||
|
||||
Documentation is part of the completion criteria for every behavior change. The
|
||||
owning module must update its manifest-driven `DocumentationTopic` contributions
|
||||
for affected user and administrator workflows, settings, permissions,
|
||||
limitations, and operational consequences. Feature documentation remains in the
|
||||
feature module; the optional `govoplan-docs` module projects those contributions
|
||||
without importing feature internals. Every module manifest must retain a static
|
||||
user and administrator baseline even when runtime providers add configured-state
|
||||
details.
|
||||
|
||||
Use `~/.codex/config.toml` for personal defaults, auth/runtime settings, writable roots, and trust decisions. Avoid checking in absolute-path writable roots or model preferences unless they are intentionally team-wide.
|
||||
|
||||
Use Gitea issues as the canonical backlog and state log. See `docs/GITEA_ISSUES.md` for label setup, TODO import, and Codex issue update commands. Durable docs should describe stable behavior; changing work state belongs on the issue.
|
||||
@@ -81,5 +90,6 @@ PATH=/mnt/DATA/git/govoplan-core/webui/node_modules/.bin:/home/zemion/.nvm/versi
|
||||
- Avoid broad recursive scans and full builds unless the change warrants them.
|
||||
- Keep generated build/test folders ignored.
|
||||
- Keep optional module behavior behind core registry/capability/module metadata boundaries.
|
||||
- Run `tools/checks/check-manifest-shapes.py` after module behavior or manifest changes so user/admin documentation coverage remains complete.
|
||||
- Create or update Gitea issues for TODOs, follow-ups, blockers, and feature requests instead of keeping local backlog files.
|
||||
- Do not start persistent dev servers unless the user asks.
|
||||
|
||||
@@ -48,6 +48,35 @@ interface = how configured parts connect
|
||||
data = what the operator must provide for this deployment
|
||||
```
|
||||
|
||||
## Package Classes
|
||||
|
||||
The same signed package mechanism supports several explicitly named classes:
|
||||
|
||||
| Class | Purpose |
|
||||
| --- | --- |
|
||||
| `reference` | Prove a bounded journey, degraded states, recovery, and target-environment acceptance. |
|
||||
| `product` | Provide a reusable operating capability such as governed communication, service-to-decision, procurement/contracts, or governed BI. |
|
||||
| `sector` | Specialize terminology, forms, rules, process baselines, controls, reports, and integrations for an institutional sector without forking modules. |
|
||||
| `deployment` | Declare a supported infrastructure topology, operational assumptions, health gates, and recovery evidence. |
|
||||
| `integration` | Declare external systems, provider bindings, source-authority modes, maturity, required health, and reconciliation behavior. |
|
||||
|
||||
Package class is metadata and validation context, not additional authority. A
|
||||
sector package does not become a module and cannot write another module's
|
||||
tables. Packages may extend other packages only through versioned fragments and
|
||||
must preserve provenance and parent constraints.
|
||||
|
||||
The contract enforces class-specific evidence. Reference packages require
|
||||
target, recovery, security, operations, accessibility, privacy, and
|
||||
documentation evidence. Deployment and integration packages require their
|
||||
corresponding target/recovery/operations evidence, while integration packages
|
||||
also name provider authority and minimum-maturity expectations. Preflight
|
||||
blocks a missing, incompatible, or unhealthy provider. A derived package may
|
||||
tighten parent module, capability, and provider requirements but cannot remove
|
||||
or loosen them. Every non-documentation claim made by reference, deployment, or
|
||||
integration packages carries a `sha256:<digest>` binding. Repository checks
|
||||
recompute those hashes, while signed package verification protects the declared
|
||||
manifest during transport.
|
||||
|
||||
## Package Model
|
||||
|
||||
A configuration package should be a signed, portable manifest plus module-owned
|
||||
@@ -68,6 +97,9 @@ Required package metadata:
|
||||
- preflight checks and post-import health checks
|
||||
- migration or transformation rules for older package versions
|
||||
- provenance, export source metadata, and signature metadata
|
||||
- package class and optional parent package/version constraints
|
||||
- source-authority bindings and provider-operation expectations for every
|
||||
external integration used by the package
|
||||
|
||||
Portable configuration schemas follow `COMPATIBILITY_POLICY.md`: providers
|
||||
write only their current schema version and read that version plus the previous
|
||||
|
||||
@@ -15,7 +15,10 @@ operator, and roadmap pages.
|
||||
| Policy decision DTOs and provenance | `POLICY_CONTRACTS.md` | Shared explain/provenance shape; module-specific policy docs should link here. |
|
||||
| Events and audit trace context | `EVENTS_AND_AUDIT.md` | Event dispatch semantics and audit payload conventions. |
|
||||
| Action/effect automation layer | `ACTION_EFFECT_AUTOMATION_LAYER.md` | Action/effect contracts, consequence preview, runner semantics, and module boundary for automation. |
|
||||
| External references and integration maturity | `EXTERNAL_REFERENCES_AND_INTEGRATION_MATURITY.md` | Stable external identity and cumulative connector maturity; configured source authority is defined by the meta target architecture. |
|
||||
| Institutional context and governed references | `INSTITUTIONAL_CONTEXT_CONTRACT.md` | Shared temporal, actor/representation, institution, mandate, service, party, decision, evidence, legal-basis, information-governance, presentation, and geo DTO/provider contracts. |
|
||||
| Postbox E2EE target architecture | `POSTBOX_E2EE_ARCHITECTURE.md` | Strategic encrypted postbox/mailbox model, key ownership, role mailbox semantics, and retraction limits. |
|
||||
| Shared state, runtime coordination, and recovery | `STATE_AND_RECOVERY_CONTRACT.md` | State profiles, object storage, node registration/drain, fenced leases, migration ordering, and recovery evidence. |
|
||||
|
||||
## Release And Operations
|
||||
|
||||
@@ -33,6 +36,7 @@ operator, and roadmap pages.
|
||||
| Topic | Canonical document | Notes |
|
||||
| --- | --- | --- |
|
||||
| Product roadmap and module routing | `GOVOPLAN_MASTER_ROADMAP.md` | Product-level sequencing, implementation gates, issue routing, and missing-module decisions. |
|
||||
| Institutional governance target | `govoplan/docs/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md` | Cross-product semantic layers, source-authority modes, candidate Mandates/Services/Parties/Decisions boundaries, and migration sequence. |
|
||||
| UI/UX decisions | `UI_UX_DECISION_LEDGER.md` | Binding guided-UI decisions, open decisions, impact index, and review checklist. |
|
||||
| Interface ethics and design doctrine | `INTERFACE_ETHICS_AND_DESIGN_DOCTRINE.md` | Product-level doctrine for context, decision, consequence, contestability, responsibility, and traceability. |
|
||||
| Public-sector integration posture | `PUBLIC_SECTOR_INTEGRATION_STRATEGY.md` | Strategy index; executable target inventory lives in `govoplan-connectors`. |
|
||||
|
||||
@@ -35,6 +35,26 @@ Connectors must declare and document the maturity they actually implement.
|
||||
handling, deletion semantics, and observable failures. A link-only connector
|
||||
must not imply that GovOPlaN holds an authoritative copy.
|
||||
|
||||
## Source Authority Is A Separate Dimension
|
||||
|
||||
Integration maturity states what an adapter is capable of doing. It does not
|
||||
decide which system owns truth for a configured object or field group. A
|
||||
binding separately selects one of the source-authority modes defined by the
|
||||
[institutional governance target architecture](../../govoplan/docs/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md):
|
||||
|
||||
- `native_authoritative`
|
||||
- `external_authoritative`
|
||||
- `external_mirror`
|
||||
- `governed_sync`
|
||||
- `governance_overlay`
|
||||
- `linked_reference`
|
||||
|
||||
A connector can therefore support `synchronize` while a tenant deliberately
|
||||
uses it only as an external mirror. Conversely, a native GovOPlaN object may
|
||||
retain link-only references to several external systems. Authority may be
|
||||
narrowed by tenant, organization, service, object type, object, field group, or
|
||||
process step and must be visible in provenance and configuration preflight.
|
||||
|
||||
## Domain Ownership
|
||||
|
||||
- Domain modules own native GovOPlaN objects and their authorization.
|
||||
|
||||
@@ -16,6 +16,9 @@ service and operating configurations, connected outcome stories, and
|
||||
capability horizons. The selected five-stage delivery sequence and its gates
|
||||
are in the meta repository's
|
||||
[Reference Journey Program](https://git.add-ideas.de/GovOPlaN/govoplan/src/branch/main/docs/REFERENCE_JOURNEY_PROGRAM.md).
|
||||
The semantic target, source-authority modes, and reconciliation with the
|
||||
implemented platform are in the meta repository's
|
||||
[Institutional Governance Target Architecture](https://git.add-ideas.de/GovOPlaN/govoplan/src/branch/main/docs/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md).
|
||||
Those product documents are canonical; this Core roadmap remains their
|
||||
technical sequencing and module-routing companion.
|
||||
|
||||
@@ -64,8 +67,9 @@ verify or reverse those effects.
|
||||
`INTERFACE_ETHICS_AND_DESIGN_DOCTRINE.md`.
|
||||
- Automation must use governed action/effect contracts, not hidden side
|
||||
effects. The first automation layer is defined in
|
||||
`ACTION_EFFECT_AUTOMATION_LAYER.md` and should start in `govoplan-workflow`
|
||||
unless a separate automation module becomes justified.
|
||||
`ACTION_EFFECT_AUTOMATION_LAYER.md`; its first runner lives in
|
||||
`govoplan-workflow-engine`. Create a separate automation module only if the
|
||||
scheduler/action runtime outgrows workflow coordination.
|
||||
- Encrypted postboxes are a strategic target. Early postbox, access, and
|
||||
identity-trust contracts should stay compatible with the E2EE architecture in
|
||||
`POSTBOX_E2EE_ARCHITECTURE.md`.
|
||||
@@ -144,8 +148,9 @@ pattern exists.
|
||||
| Structured forms and validation | `govoplan-forms` |
|
||||
| Uploaded files and managed storage | `govoplan-files` |
|
||||
| Case record and lifecycle | `govoplan-cases` |
|
||||
| Workflow transitions and automation | `govoplan-workflow` |
|
||||
| Action/effect catalogue and automation runner | first `govoplan-workflow`; possible future `govoplan-automation` if it outgrows workflow |
|
||||
| Workflow runtime, transitions, and automation | `govoplan-workflow-engine` |
|
||||
| Workflow definition editing | optional `govoplan-workflow` |
|
||||
| Action/effect catalogue and automation runner | first `govoplan-workflow-engine`; possible future `govoplan-automation` only if it outgrows workflow |
|
||||
| Internal work queues and tasks | `govoplan-tasks` |
|
||||
| Appointment proposals and booking | `govoplan-appointments`, `govoplan-calendar` |
|
||||
| Postbox, email, and notifications | `govoplan-postbox`, `govoplan-mail`, `govoplan-notifications` |
|
||||
@@ -153,13 +158,18 @@ pattern exists.
|
||||
| Organizational structures, units, and functions | `govoplan-organizations` |
|
||||
| Identity-to-function assignments and directory synchronization | `govoplan-idm` |
|
||||
| Identity trust, device keys, and encrypted postbox key contracts | `govoplan-identity-trust`, `govoplan-access`, `govoplan-postbox` |
|
||||
| Service directory/catalog | `govoplan-portal` |
|
||||
| Service directory presentation | `govoplan-portal` |
|
||||
| Versioned institutional service definition | shared service contract first; candidate `govoplan-services` after reuse proof |
|
||||
| Mandate, jurisdiction, and institutional authority | shared mandate contract first; candidate `govoplan-mandates` after reuse proof |
|
||||
| Procedure-local parties and representation | shared party contract first; candidate `govoplan-parties` after reuse proof |
|
||||
| Formal institutional decisions | shared decision contract first; candidate `govoplan-decisions` after reuse proof |
|
||||
| Permit/document generation | `govoplan-templates`, `govoplan-dms` |
|
||||
| Payment capture and accounting handoff | `govoplan-payments`, `govoplan-ledger` |
|
||||
| Authentication projection, roles, permissions, acting context | `govoplan-access` |
|
||||
| Tenants, policy, and audit | `govoplan-tenancy`, `govoplan-policy`, `govoplan-audit` |
|
||||
| External software integration | `govoplan-connectors` |
|
||||
| Recurring extraction and transformation | possible future `govoplan-datasources`, possible future `govoplan-dataflow` |
|
||||
| Governed data/register catalogue | `govoplan-datasources` |
|
||||
| Recurring extraction and transformation | `govoplan-dataflow` over Datasources and Connectors contracts |
|
||||
| Reports, BI, and management visibility | `govoplan-reporting` |
|
||||
|
||||
## Configuration And Safety Target
|
||||
@@ -204,8 +214,9 @@ an editor applies a high-impact configuration change.
|
||||
|
||||
## Reference Journeys
|
||||
|
||||
The active sequence is selected. Workflow remains deliberately deferred and is
|
||||
not a dependency of these journeys.
|
||||
The active sequence is selected. Workflow Engine and its optional editor are
|
||||
now available foundations, but a reference journey does not depend on Workflow
|
||||
unless its package explicitly composes and proves it.
|
||||
|
||||
### Journey 1: Campaign Demonstration Composition
|
||||
|
||||
@@ -256,9 +267,11 @@ The result must preserve official-key mappings, organizational and reporting
|
||||
date semantics, quality findings, quarantine/replay, transparent calculation,
|
||||
and reproducible promotion between development, test, and production.
|
||||
|
||||
Reporting consumes the product. Create `govoplan-datasources` or
|
||||
`govoplan-dataflow` only after the concrete path proves repeated ownership that
|
||||
does not belong to connectors, Reporting, or the producing domain module.
|
||||
Reporting consumes the product. Datasources owns the governed source and
|
||||
materialization lifecycle; Dataflow owns typed transformation/run lineage;
|
||||
Connectors owns external transport. The concrete path must now prove those
|
||||
implemented boundaries and expose any missing contracts instead of recreating
|
||||
them inside Reporting or a producing domain module.
|
||||
|
||||
### Journey 5: Collaborative Document Lifecycle
|
||||
|
||||
@@ -336,8 +349,9 @@ Create or refine in this order:
|
||||
access.
|
||||
4. `govoplan-cases`: case record, status, assignments, deadlines, and case
|
||||
evidence.
|
||||
5. `govoplan-workflow`: state machine, transitions, commands, and module
|
||||
handoff.
|
||||
5. `govoplan-workflow-engine`: state machine, transitions, commands, module
|
||||
handoff, and resumable execution; optional `govoplan-workflow` supplies the
|
||||
editor.
|
||||
6. `govoplan-tasks`: work queues, assignments, due dates, and follow-ups.
|
||||
7. `govoplan-templates`: permit/decision document generation.
|
||||
8. `govoplan-postbox`, `govoplan-mail`, `govoplan-notifications`: applicant and
|
||||
@@ -526,31 +540,34 @@ Refine:
|
||||
dashboard data.
|
||||
- `govoplan-search`: permissioned cross-module discovery.
|
||||
|
||||
Create only when justified:
|
||||
Refine the existing owners:
|
||||
|
||||
- `govoplan-datasources`: source catalog, connection profiles, schema discovery,
|
||||
freshness, provenance.
|
||||
- `govoplan-dataflow`: transformations, validation, lineage, scheduled runs,
|
||||
publication outputs.
|
||||
- `govoplan-projects`: only if OpenProject connectors and existing cases/tasks
|
||||
cannot cover the required semantics.
|
||||
- `govoplan-datasources`: governed data/register catalog, live/cached/static
|
||||
sources, staging, immutable materializations, freshness, quality, legal and
|
||||
organizational context, and provenance. Connector profiles and credentials
|
||||
remain in Connectors.
|
||||
- `govoplan-dataflow`: typed transformations, validation, lineage, manual,
|
||||
scheduled and event-triggered runs, reusable definitions, and publication
|
||||
outputs.
|
||||
- `govoplan-projects`: native projects, portfolios, milestones, goals,
|
||||
dependencies, capacity, outcomes, and external OpenProject references;
|
||||
Connectors owns OpenProject transport and synchronization.
|
||||
|
||||
Reference journey: monthly data extraction, transformation, validation, approval,
|
||||
publication, and reporting.
|
||||
|
||||
Recurring extraction/transformation should start as a configuration package
|
||||
across connectors, files, workflow, reporting, and templates. The package should
|
||||
register sources, declare schemas, define mapping/validation versions, schedule
|
||||
runs, produce previewable diffs, write governed outputs, and preserve lineage,
|
||||
hashes, operator actions, and audit evidence. Create `govoplan-datasources` or
|
||||
`govoplan-dataflow` only after this work exposes repeated contracts that do not
|
||||
belong to existing modules.
|
||||
Recurring extraction/transformation should be delivered as a configuration
|
||||
package across Connectors, Datasources, Dataflow, Workflow Engine, Reporting,
|
||||
Files, and Templates. The package should register sources, declare schemas,
|
||||
define mapping/validation versions, schedule runs, produce previewable diffs,
|
||||
write governed outputs, and preserve lineage, hashes, operator actions, and
|
||||
audit evidence.
|
||||
|
||||
Exit criteria:
|
||||
|
||||
- connector catalog exists before building many adapters
|
||||
- dataflow is created only after recurring transformation becomes product
|
||||
behavior
|
||||
- datasource and dataflow ownership remains provider-neutral and is proved by
|
||||
the recurring transformation package
|
||||
- reporting consumes governed sources with provenance
|
||||
|
||||
## Implementation Gates
|
||||
@@ -591,23 +608,25 @@ in the capability waves:
|
||||
4. Implement one data-backed Templates/Reporting path and safe HIS-style deep
|
||||
launch.
|
||||
5. Extend that concrete source into one governed university analytical data
|
||||
product before generalizing data-source or dataflow ownership.
|
||||
product and use it to harden the existing Datasources/Dataflow ownership,
|
||||
quality, lineage, and promotion contracts.
|
||||
6. Implement Files-backed DMS versions and one provider-neutral collaborative
|
||||
editing lifecycle, then connect Records handoff.
|
||||
7. Maintain already integrated Calendar/Scheduling/Poll and other foundations;
|
||||
activate another capability cluster only when the current journey needs it
|
||||
or the product roadmap explicitly reprioritizes it.
|
||||
8. Resume Workflow only by explicit product decision and constrain it with
|
||||
stable actions from one demonstrated package.
|
||||
8. Extend Workflow Engine and the optional editor only through stable actions
|
||||
and one demonstrated package at a time.
|
||||
|
||||
## Deliberate Deferrals
|
||||
|
||||
Defer these until a reference journey proves the need:
|
||||
|
||||
- full ERP replacement
|
||||
- native project management beyond connector support
|
||||
- an unbounded general-purpose dataflow platform; the bounded governed BI
|
||||
reference journey is selected
|
||||
- unsupported breadth in native project management before the Projects/OpenProject
|
||||
boundary is proved in a reference journey
|
||||
- unbounded Dataflow operators or execution engines without golden-flow,
|
||||
quality, lineage, resource-limit, and recovery evidence
|
||||
- every possible public-sector protocol adapter
|
||||
- rich LMS behavior beyond training administration
|
||||
- full qualified digital signing/trust services beyond the identity-trust and
|
||||
@@ -630,26 +649,26 @@ repositories or to explicit missing-module decisions.
|
||||
| Fully UI-managed configuration with safety controls | `govoplan-admin`, `govoplan-core`, `govoplan-policy`, `govoplan-access`, `govoplan-audit` | `GovOPlaN/govoplan-core#218` |
|
||||
| Access as a module | `govoplan-access` | `GovOPlaN/govoplan-access#7` |
|
||||
| Interface ethics and decision-consequence doctrine | `govoplan-core` plus all UI-owning modules | `GovOPlaN/govoplan-core#227` |
|
||||
| Action/effect automation layer | first `govoplan-workflow`; possible future `govoplan-automation` | `GovOPlaN/govoplan-workflow#1` |
|
||||
| Action/effect automation layer | `govoplan-workflow-engine`; possible future `govoplan-automation` only after boundary proof | `GovOPlaN/govoplan-workflow#1` |
|
||||
| E2EE role/function postbox architecture | `govoplan-postbox`, `govoplan-identity-trust`, `govoplan-access`, `govoplan-policy`, `govoplan-audit` | `GovOPlaN/govoplan-postbox#15`, `GovOPlaN/govoplan-identity-trust#1` |
|
||||
| Identity, account, function, role, right semantic model | `govoplan-access` | `GovOPlaN/govoplan-access#9` |
|
||||
| Role-based service directory/catalog | `govoplan-portal` | `GovOPlaN/govoplan-portal#1` |
|
||||
| Role-based service directory presentation | `govoplan-portal`; reusable service definition is a shared contract and candidate `govoplan-services` | `GovOPlaN/govoplan-portal#1` |
|
||||
| Unified inbox across tasks, postbox, notifications, and portal | `govoplan-core` coordination plus owning modules | `GovOPlaN/govoplan-tasks#1`, `GovOPlaN/govoplan-notifications#1` |
|
||||
| OpenProject API / project management connector | `govoplan-connectors` | `GovOPlaN/govoplan-connectors#1` |
|
||||
| Native project-management module decision | connector-first through `govoplan-connectors`; no native project module yet | `GovOPlaN/govoplan-core#196`, `GovOPlaN/govoplan-connectors#1` |
|
||||
| Datasources for databases, CSV, files, APIs | no repository yet; start with connectors/files/reporting and create `govoplan-datasources` only after the first package proves shared source-catalog ownership | `GovOPlaN/govoplan-core#197` |
|
||||
| Dataflow for pipelines, BI, publication | no repository yet; start with workflow/reporting/connectors and create `govoplan-dataflow` only after repeated pipeline/lineage contracts emerge | `GovOPlaN/govoplan-core#198` |
|
||||
| Monthly datasource and transformation workflows | first as configuration package across connectors, files, workflow, reporting, and templates | `GovOPlaN/govoplan-core#216` |
|
||||
| Native project-management module | `govoplan-projects`; OpenProject transport remains connector-owned | `GovOPlaN/govoplan-projects#1`, `GovOPlaN/govoplan-connectors#12` |
|
||||
| Datasources for databases, CSV, files, APIs | `govoplan-datasources`, with external protocol and credential ownership in Connectors | `GovOPlaN/govoplan-datasources#1` |
|
||||
| Dataflow for pipelines, BI, publication | `govoplan-dataflow` over Datasources and module-owned providers | `GovOPlaN/govoplan-dataflow#1` |
|
||||
| Monthly datasource and transformation workflows | configuration package across Connectors, Datasources, Dataflow, Workflow Engine, Reporting, Files, and Templates | `GovOPlaN/govoplan#8`, `GovOPlaN/govoplan-dataflow#17` |
|
||||
| Templates for letters, emails, forms, reports | `govoplan-templates`, separate from reporting | `GovOPlaN/govoplan-core#190`, `GovOPlaN/govoplan-templates#1` |
|
||||
| Reporting and BI | `govoplan-reporting`, separate from templates | `GovOPlaN/govoplan-core#190`, `GovOPlaN/govoplan-reporting#1` |
|
||||
| File connectors: Nextcloud, Seafile, SMB, NFS | `govoplan-files` | `GovOPlaN/govoplan-files#15` |
|
||||
| Public-sector software integration catalogue | `govoplan-connectors` with core strategy index | `GovOPlaN/govoplan-core#191`, `GovOPlaN/govoplan-connectors#2` |
|
||||
| Public-sector integration landscape catalogue | `govoplan-connectors` with core tracking | `GovOPlaN/govoplan-core#215` |
|
||||
| Cases module concept | `govoplan-cases` | `GovOPlaN/govoplan-core#174` |
|
||||
| Workflow module concept | `govoplan-workflow` | `GovOPlaN/govoplan-core#175` |
|
||||
| Workflow runtime/editor split | `govoplan-workflow-engine` runtime plus optional `govoplan-workflow` editor | `GovOPlaN/govoplan-workflow#12`, `GovOPlaN/govoplan-workflow#13` |
|
||||
| Connectors module concept | `govoplan-connectors` | `GovOPlaN/govoplan-core#176` |
|
||||
| Adrema-style address and distribution-list management | `govoplan-addresses` | `GovOPlaN/govoplan-addresses#1` |
|
||||
| Consume sources and become a governed source | `govoplan-connectors` plus possible future `govoplan-dataflow` | `GovOPlaN/govoplan-connectors#3`, `GovOPlaN/govoplan-core#198` |
|
||||
| Consume sources and become a governed source | Connectors acquires, Datasources governs/materializes, Dataflow transforms/publishes | `GovOPlaN/govoplan-connectors#3`, `GovOPlaN/govoplan-datasources#3` |
|
||||
| Governed connector configuration, dry-run, and simulation runtime | `govoplan-connectors` | `GovOPlaN/govoplan-connectors#6` |
|
||||
| Terminfindung and meeting scheduling polls | `govoplan-scheduling`; calendar primitives remain in calendar | `GovOPlaN/govoplan-core#193`, `GovOPlaN/govoplan-scheduling#1` |
|
||||
| Terminplaner and calendar primitives | `govoplan-calendar` | `GovOPlaN/govoplan-core#193`, `GovOPlaN/govoplan-calendar#1` |
|
||||
@@ -671,27 +690,23 @@ repositories or to explicit missing-module decisions.
|
||||
Boundary rationale lives in `MODULE_ARCHITECTURE.md`. Current decisions:
|
||||
|
||||
- templates and reporting are separate modules
|
||||
- RSS/source consume-publish starts in connectors; datasources/dataflow are not
|
||||
repositories yet
|
||||
- RSS/source consume-publish starts in Connectors; governed source identity and
|
||||
snapshots belong to Datasources and transformations belong to Dataflow
|
||||
- calendar, scheduling, and appointments are three separate modules
|
||||
- forms definitions and forms runtime are separate responsibilities
|
||||
- OpenDesk is an integration profile across modules, not a monolithic module
|
||||
- OpenProject is connector-first; no native projects module yet
|
||||
- OpenProject transport is connector-owned; native portfolio/project semantics
|
||||
belong to Projects
|
||||
- public-sector integration strategy stays in core; executable catalogue work
|
||||
lives in connectors
|
||||
- encrypted postbox and identity-trust are strategic contracts, not mail-module
|
||||
behavior
|
||||
- automation starts as workflow-owned action/effect execution and may split into
|
||||
a dedicated module only after the runner becomes broader than workflow
|
||||
|
||||
The following modules are intentionally not created yet:
|
||||
|
||||
- `govoplan-datasources`
|
||||
- `govoplan-dataflow`
|
||||
- `govoplan-projects`
|
||||
|
||||
Create a repository only after a concrete implementation package proves that
|
||||
existing connector, files, reporting, workflow, or task ownership is too narrow.
|
||||
- automation starts in Workflow Engine and may split into a dedicated module
|
||||
only after the runner becomes broader than workflow
|
||||
- Mandates, Services, Parties, and Decisions begin as shared semantic contracts;
|
||||
create repositories only after independent persistence, lifecycle, security,
|
||||
and multiple-consumer evidence passes the repository threshold in the
|
||||
institutional governance target architecture
|
||||
|
||||
Core keeps the strategy index in
|
||||
`PUBLIC_SECTOR_INTEGRATION_STRATEGY.md`: integration postures, default
|
||||
|
||||
@@ -0,0 +1,159 @@
|
||||
# Institutional Context And Governed References
|
||||
|
||||
GovOPlaN consequential work must retain enough context to answer who acted,
|
||||
for whom, through which function, under which mandate and jurisdiction, using
|
||||
which rule and evidence versions, and with which requested and observed effect.
|
||||
The shared contract lives in `govoplan_core.core.institutional`.
|
||||
|
||||
Core owns reference shapes and provider protocols only. It does not own shared
|
||||
Mandate, Service, Party, Decision, evidence, or geography tables. Domain modules
|
||||
own persistence and authorization; optional capabilities resolve the references.
|
||||
|
||||
## Envelope
|
||||
|
||||
`GovernedContextEnvelope` version 1 carries:
|
||||
|
||||
- a tenant and `TemporalRevision` with validity, recording, supersession, and
|
||||
change reason;
|
||||
- the real account or service account and represented account, function,
|
||||
procedure party, assignment, delegation/power, and mandate;
|
||||
- institution, organization unit, function, task, mandate, jurisdiction,
|
||||
service, case, party, work item, workflow, approval, decision, and record
|
||||
references;
|
||||
- versioned legal bases and evidence references;
|
||||
- information classification, purposes, retention/holds, minimization, and
|
||||
disclosure state;
|
||||
- external-source authority, maturity, freshness, health, and conflict state;
|
||||
- language, accessibility, channel, explanation, and availability references.
|
||||
|
||||
Every institutional reference includes the owner module, tenant, stable object
|
||||
identity, optional version/effective instant, and a protected display label.
|
||||
Cross-tenant references are rejected. Safe serialization omits labels,
|
||||
inspection URLs, formal reasoning, operative results, and conditions unless a
|
||||
caller explicitly requests the protected projection.
|
||||
|
||||
## Semantic Providers
|
||||
|
||||
The first provider-neutral capabilities are:
|
||||
|
||||
- `mandates.resolver`: resolve competence for a task/authority type at an
|
||||
effective instant and return the governing Mandate definition and evidence;
|
||||
- `services.definitions`: obtain versioned institutional service definitions;
|
||||
- `parties.resolver`: obtain effective procedure-local parties and powers of
|
||||
representation without copying Identity or Organizations subjects; and
|
||||
- `decisions.registry`: record and retrieve formal Decisions under optimistic
|
||||
revision control.
|
||||
|
||||
The Mandate, Service, Party/representation, and Decision DTOs have strict
|
||||
mapping round-trips so they can cross capability, event, package, and storage
|
||||
boundaries without shared ORM models. Their lifecycle states are explicit:
|
||||
Mandates distinguish draft/active/suspended/replaced/retired, Services retain
|
||||
publication state, Parties retain effective representation and revocation, and
|
||||
Decisions retain correction, revocation, and supersession references.
|
||||
|
||||
The DTOs are a repository threshold, not a mandate to create four modules.
|
||||
Independent persistence, lifecycle, security/operations behavior, release
|
||||
reason, reuse, and tests are still required before extraction.
|
||||
|
||||
Mandate resolution is deterministic: Core filters candidates by tenant,
|
||||
effective interval, active state, task and authority type, stable
|
||||
organization/function identity, jurisdiction coverage, and subject type. A
|
||||
result is competent only when exactly one matching Mandate remains and it has
|
||||
no unresolved conflicts. Evidence from matching definitions is deduplicated
|
||||
and retained in the explanation result. `revise_mandate_definition` applies
|
||||
optimistic concurrency and the allowed activation, suspension, replacement,
|
||||
and retirement transitions while leaving the previous revision immutable.
|
||||
|
||||
`revise_formal_decision` provides the equivalent lifecycle primitive for
|
||||
formal outcomes. Every accepted transition requires a new recorded revision
|
||||
and change reason, links `supersedes_ref` to the prior version, updates the
|
||||
authority envelope to the new version, and records explicit correction or
|
||||
revocation provenance. Terminal and backward transitions fail closed. Each
|
||||
Decision also records whether responsibility was human, human-reviewed
|
||||
automation, or an automated service account acting under mandate. Automation
|
||||
preparation/recommendation references remain inspectable without being
|
||||
mistaken for the responsible outcome.
|
||||
|
||||
Procedure-party corrections use `revise_procedure_party`: the stable party
|
||||
identity is retained, a new revision and reason are required, stale writes are
|
||||
rejected, and revoked/expired/superseded assignments are terminal.
|
||||
`revoke_party_representation` separately records when a limited power ceased
|
||||
to authorize actions. This allows consuming procedures to evaluate historical
|
||||
delivery or representation authority without rewriting Identity,
|
||||
Organizations, or Addresses records.
|
||||
|
||||
Service templates and package/tenant specializations use
|
||||
`derive_service_restriction`. The derived definition retains an explicit
|
||||
parent-version reference, cannot extend the parent's validity, audience,
|
||||
channels, or publication ceiling, and cannot remove inherited prerequisites,
|
||||
required evidence, legal bases, or bindings. This is the fail-closed semantic
|
||||
rule; configuration-package signature and provenance checks remain the package
|
||||
transport rule.
|
||||
|
||||
`ServiceAvailabilityRequirement` represents module, capability, mandate,
|
||||
policy, connector, maintenance, audience, and configuration prerequisites with
|
||||
an explicit unavailable-or-hidden failure mode and explanation reference. The
|
||||
optional `services.availability` evaluator returns policy-scoped boolean
|
||||
assessments, reason codes, and evidence. Unknown consequential requirements
|
||||
fail closed; a reference itself never grants access.
|
||||
|
||||
## Service Launch
|
||||
|
||||
`ServiceLaunchRequest` and `ServiceLaunchResult` define the owner-neutral
|
||||
boundary between Portal entry and a case, form, or workflow runtime effect.
|
||||
The request carries the exact published Service definition, exact selected
|
||||
binding, tenant, acting identity, timezone-aware request time, bounded
|
||||
parameters, and idempotency key. The result must retain that exact Service and
|
||||
binding, a same-tenant target reference, optional same-tenant evidence, and
|
||||
only a relative or credential-free HTTP(S) destination.
|
||||
|
||||
`service_launch_capability(kind)` maps bindings to owner capabilities:
|
||||
|
||||
- `case` -> `cases.service_launcher`
|
||||
- `form` -> `forms_runtime.service_launcher`
|
||||
- `workflow` -> `workflow_engine.service_launcher`
|
||||
|
||||
`FormDefinition`, `FormFieldDefinition`, and `forms.definitions` provide the
|
||||
owner-neutral exact-schema boundary used by Forms Runtime. Definitions carry an
|
||||
exact tenant/revision, field types/options/constraints/defaults, publication,
|
||||
draft, attachment, signature, policy, and handoff requirements. Forms owns
|
||||
those immutable definitions; Forms Runtime persists instances and validation
|
||||
evidence. A form Service binding uses `<form-id>/<revision>` and the launcher
|
||||
rejects missing, superseded, unpublished, cross-tenant, or invalid definitions.
|
||||
|
||||
Portal may discover and invoke those capabilities but cannot write owner
|
||||
tables. The owner must revalidate its definition/binding and current
|
||||
authorization, produce its normal audit/event state, and make replay after an
|
||||
ambiguous response safe. If the capability is absent, the service is
|
||||
explainably unavailable. URL-only entries pass through the same launch-time
|
||||
availability check and destination validation. Forms Runtime now supplies the
|
||||
definition-aware form launcher when both Forms and Forms Runtime are active;
|
||||
otherwise Portal continues to fail closed.
|
||||
|
||||
## Propagation
|
||||
|
||||
`PlatformEvent`, `ActionExecutionRequest`, and `AuditEvent` can carry the
|
||||
envelope. Audit persistence stores only its safe projection; platform-event
|
||||
outbox serialization preserves it across asynchronous delivery. A module must
|
||||
not invent a parallel context dictionary when the shared fields apply.
|
||||
|
||||
## First Proof
|
||||
|
||||
Committee's `committee.decision_path` capability is the first bounded proof. It
|
||||
requires one effective, conflict-free Mandate covering the organization unit
|
||||
function, and jurisdiction, an approval reference, fact evidence, versioned legal bases,
|
||||
operative result, and reasoning. It emits a reconstructable `FormalDecision`,
|
||||
including requested/observed effects and information governance. If a Decision
|
||||
registry is installed it persists there; Committee does not take ownership of
|
||||
the generic Decision lifecycle.
|
||||
|
||||
## Compatibility And Security
|
||||
|
||||
- Contract version changes follow Core compatibility policy.
|
||||
- Unknown tenant or reference-kind combinations fail closed.
|
||||
- Datetimes that affect authority must be timezone-aware.
|
||||
- Protected labels, reasoning, evidence inspection links, and source details
|
||||
remain subject to the owning module's access policy.
|
||||
- References do not grant access to their targets.
|
||||
- Evidence and audit payloads must contain stable references/checksums, not
|
||||
plaintext secrets.
|
||||
+149
-1
@@ -13,6 +13,10 @@ Policy decision, source provenance, and explain-response contracts are tracked
|
||||
in [`POLICY_CONTRACTS.md`](POLICY_CONTRACTS.md).
|
||||
The experimental remote WebUI bundle loading design is tracked in
|
||||
[`REMOTE_WEBUI_BUNDLES.md`](REMOTE_WEBUI_BUNDLES.md).
|
||||
The cross-product semantic layers, source-authority modes, and candidate
|
||||
Mandates, Services, Parties, and Decisions boundaries are canonical in the
|
||||
meta repository's
|
||||
[`INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md`](../../govoplan/docs/INSTITUTIONAL_GOVERNANCE_TARGET_ARCHITECTURE.md).
|
||||
|
||||
## Layer Model
|
||||
|
||||
@@ -24,6 +28,36 @@ The experimental remote WebUI bundle loading design is tracked in
|
||||
| Business modules | Public-sector workflows | campaigns, cases, forms, approvals, appointments |
|
||||
| Connector modules | External system integration | FIT-Connect, XÖV/XTA, DMS/eAkte, ERP, IDM |
|
||||
|
||||
This table is the technical composition model. The product portfolio uses a
|
||||
more detailed institutional layer model, but it does not change dependency
|
||||
direction: Core provides contracts and composition; modules own semantics;
|
||||
packages compose modules.
|
||||
|
||||
## Institutional Semantic Boundaries
|
||||
|
||||
Cross-module references must keep these answers distinct:
|
||||
|
||||
- Organizations owns where structures, units, and functions exist.
|
||||
- Identity owns who a subject is; Access owns accounts, roles, permissions,
|
||||
and authorization decisions; IDM owns effective function assignments.
|
||||
- A Mandates capability will answer why a unit or function is competent for a
|
||||
task, jurisdiction, subject, or period. It must not become another RBAC
|
||||
system.
|
||||
- A Services capability will own versioned institutional service definitions;
|
||||
Portal presents and starts them.
|
||||
- A Parties capability will own procedure-local participant roles,
|
||||
representation, and delivery authority; it must reference rather than copy
|
||||
Identity, Organizations, and Addresses subjects.
|
||||
- A Decisions capability will own formal institutional outcomes and their
|
||||
authority, facts, rules, reasoning, effects, correction, and review.
|
||||
Approvals owns review gates, Committee owns deliberation/votes, and Workflow
|
||||
Engine owns coordination.
|
||||
|
||||
Start each missing concept as a versioned DTO/provider contract used by a
|
||||
bounded journey. A repository is justified only when the concept gains
|
||||
independent persistence, lifecycle, security/operations behavior, release
|
||||
reason, and reuse. Core must not store these domain objects.
|
||||
|
||||
## Kernel Responsibilities
|
||||
|
||||
The kernel target owns:
|
||||
@@ -98,6 +132,11 @@ The following contracts are the baseline API that modules can rely on:
|
||||
- navigation metadata contract
|
||||
- command/event envelope contract
|
||||
- policy decision and source provenance contract in `govoplan_core.core.policy`
|
||||
- external object reference and integration-maturity contract in
|
||||
`govoplan_core.core.external_references`
|
||||
- action/effect preview and execution contract in
|
||||
`govoplan_core.core.automation`
|
||||
- workflow definition contribution and runtime-worker contracts
|
||||
|
||||
Changes to these contracts must be versioned or accompanied by compatibility shims.
|
||||
|
||||
@@ -115,6 +154,30 @@ may extend the kernel by adding explicit contracts, but existing contracts must
|
||||
remain source-compatible through the 0.1.x split line unless a migration shim
|
||||
and deprecation note are provided.
|
||||
|
||||
### Architecture Metadata
|
||||
|
||||
`ModuleManifest.architecture` is the backward-compatible, versioned product-
|
||||
portfolio declaration for:
|
||||
|
||||
- module kind and institutional architecture layer;
|
||||
- evidence-backed maturity claim (`concept`, `scaffold`, `vertical_slice`,
|
||||
`reference_ready`, `supported`, or `lts`);
|
||||
- owned and explicitly non-owned concepts;
|
||||
- supported source-authority modes;
|
||||
- reference packages, tested providers, and known limits;
|
||||
- migration, upgrade, recovery, security, operations, and documentation
|
||||
evidence references.
|
||||
|
||||
Core validates the claim and all provider references during registry startup.
|
||||
`reference_ready`, `supported`, and `lts` claims require a named reference
|
||||
package and the cumulative evidence set; target-tested providers additionally
|
||||
require provider evidence. A supported module with migrations must include
|
||||
migration evidence. Signed release catalogs retain and revalidate the
|
||||
declaration. The meta manifest check validates repository evidence paths and
|
||||
provides an opt-in `--require-architecture` rollout gate. Platform metadata,
|
||||
Docs, and Ops project the same declaration. A module cannot make itself
|
||||
supported solely by changing its maturity string.
|
||||
|
||||
Known access-related capability names are defined in
|
||||
`govoplan_core.core.access`, including:
|
||||
|
||||
@@ -180,6 +243,45 @@ intended for SemVer major-version lines. Missing optional interfaces are
|
||||
allowed, but an installed provider with an incompatible version blocks
|
||||
activation because the integration would otherwise bind to an unsafe API.
|
||||
|
||||
### Source Authority And Provider Operations
|
||||
|
||||
Integration maturity and configured authority are independent. The existing
|
||||
external-reference maturity ladder describes whether an adapter can discover,
|
||||
link, search, read, publish, synchronize, migrate, or replace. A binding must
|
||||
also state whether GovOPlaN is native authoritative, the external system is
|
||||
authoritative, GovOPlaN keeps a mirror, both sides use governed sync, GovOPlaN
|
||||
adds only a governance overlay, or the object is link-only.
|
||||
|
||||
`ModuleManifest.external_providers` composes existing contracts rather than
|
||||
replacing them. Each declaration describes owned object/field groups, authority modes,
|
||||
operations, revisions, freshness, health, limits, idempotency, conflicts,
|
||||
outcome-unknown handling, evidence, correction/compensation, reconciliation,
|
||||
outage behavior, classification, purpose, retention, and secret requirements.
|
||||
Core owns the typed declaration and validation. Connectors and domain modules
|
||||
own the actual protocol and domain behavior; configuration packages select the
|
||||
effective mode and block missing/incompatible/unhealthy providers; Docs and Ops
|
||||
explain the result. Effect-capable declarations fail validation unless their
|
||||
retry, concurrency, outcome-unknown, correction, reconciliation, evidence,
|
||||
audit, timeout, outage, classification, purpose, retention, and secret behavior
|
||||
is explicit.
|
||||
|
||||
Declarations are release-time capability claims. Configured state is projected
|
||||
separately through `ModuleManifest.external_provider_state_providers`. A state
|
||||
provider receives a bounded tenant context and returns one sanitized observation
|
||||
per configured binding: stable binding reference, effective authority mode,
|
||||
active/configured state, health, freshness, conflict, recovery readiness,
|
||||
observation/last-success time, and scalar metrics. Core validates and aggregates
|
||||
those observations, isolates provider failures, and never accepts URLs,
|
||||
credentials, or arbitrary nested metadata as runtime-state fields. Docs removes
|
||||
binding-level detail from ordinary-user projections; Ops may show the full
|
||||
sanitized operator projection.
|
||||
|
||||
Configuration-package preflight selects the exact requested binding from this
|
||||
runtime state before evaluating authority, health, freshness, and recovery. A
|
||||
healthy sibling binding therefore cannot mask an unhealthy required binding.
|
||||
Providers with multiple configurations must use non-secret, stable references
|
||||
such as `calendar:sync-source:<id>`.
|
||||
|
||||
Current named interfaces, generated from the source manifests by the workspace
|
||||
contract checks, are:
|
||||
|
||||
@@ -593,6 +695,39 @@ Rules:
|
||||
one migration run, and do not switch a database between tracks unless it is a
|
||||
disposable development database.
|
||||
|
||||
### Shared State And Runtime Ordering
|
||||
|
||||
Multi-host application roles use the `shared` state profile. In that profile,
|
||||
PostgreSQL, Redis, a stable installation identifier, and S3-compatible object
|
||||
storage are mandatory. Module durable artifacts must use Core's object-storage
|
||||
contract and module-owned opaque key namespaces; node-local paths are limited
|
||||
to temporary materialization. Same-host replicas may use the `host-shared`
|
||||
profile and one shared volume.
|
||||
|
||||
Only the migration command mutates schema. PostgreSQL migration runs acquire a
|
||||
deployment-wide advisory lock before module pre-tasks, Alembic, and post-tasks.
|
||||
API, worker, and scheduler roles wait for exact configured migration heads and
|
||||
fail closed instead of applying migrations during startup.
|
||||
|
||||
Runtime roles register identity, software/module composition, queues, heartbeat,
|
||||
and drain state in PostgreSQL. Singleton work must use a distributed lease and
|
||||
validate its monotonically increasing fencing token at the consequential
|
||||
commit. See `STATE_AND_RECOVERY_CONTRACT.md` for the complete contract.
|
||||
|
||||
### Recovery Evidence
|
||||
|
||||
Operations spanning transactions, object storage, queues, or external systems
|
||||
must choose an explicit Core recovery mode: atomic, compensation,
|
||||
snapshot-restore, forward-recovery, or irreversible. Plans require verification
|
||||
steps and mode-specific recovery material. Use idempotency keys, append-only
|
||||
evidence checkpoints, and a runtime fence where work may race across nodes.
|
||||
|
||||
The recovery ledger is a shared primitive, not automatic coverage. A module may
|
||||
claim its guarantees only after its operation records preconditions before side
|
||||
effects, transitions partial/unknown outcomes honestly, and records verified
|
||||
completion or recovery. Plaintext secrets must never enter recovery metadata or
|
||||
evidence.
|
||||
|
||||
## Install, Uninstall, And Catalogs
|
||||
|
||||
Core owns the install plan, signed catalog validation, license entitlement
|
||||
@@ -962,7 +1097,7 @@ from workflow semantics.
|
||||
- form definitions, schemas, validation rules, field visibility rules,
|
||||
localization, versioning, admin editing, and reusable form package fragments
|
||||
|
||||
`govoplan-forms-runtime` owns, when implemented:
|
||||
`govoplan-forms-runtime` owns:
|
||||
|
||||
- public/internal submissions, drafts, submitted values, validation evidence,
|
||||
attachment references, submission receipts, and handoff events
|
||||
@@ -975,6 +1110,16 @@ Boundary:
|
||||
- Reporting/dataflow may consume submitted data through governed DTOs or
|
||||
source lifecycle contracts.
|
||||
|
||||
Implemented contract:
|
||||
|
||||
- Core owns the provider-neutral `FormDefinition`/`FormFieldDefinition` DTOs.
|
||||
- Forms persists immutable exact definitions and provides `forms.definitions`.
|
||||
- Forms Runtime resolves that capability, persists revisioned instances and
|
||||
events, validates draft/final values, and provides
|
||||
`forms_runtime.service_launcher`.
|
||||
- Portal delegates exact `<form-id>/<revision>` bindings and never writes either
|
||||
owner's tables.
|
||||
|
||||
### OpenDesk Integration Profile
|
||||
|
||||
Tracking: `govoplan-core#195`, `govoplan-connectors#5`,
|
||||
@@ -1219,6 +1364,9 @@ the same restart/health set after restoring package and database snapshots.
|
||||
The installer preflight is intentionally conservative:
|
||||
|
||||
- maintenance mode must be active;
|
||||
- the `shared` state profile blocks in-place package mutation; clustered
|
||||
installations must roll one verified immutable module composition across all
|
||||
replicas;
|
||||
- installed module manifests must be compatible with the supported manifest
|
||||
contract and current core version;
|
||||
- uninstalling `tenancy`, `access`, or `admin` is blocked;
|
||||
|
||||
@@ -175,8 +175,10 @@ connector or module issue.
|
||||
queries, untraceable manual transformations.
|
||||
- MVP test path: publish one report/export as a governed file plus RSS/Atom
|
||||
entry with checksum, timestamp, and permission check.
|
||||
- Owner/priority: `govoplan-reporting`, `govoplan-connectors`, possible future
|
||||
`govoplan-datasources`/`govoplan-dataflow`, Wave 2.
|
||||
- Owner/priority: `govoplan-reporting`, `govoplan-connectors`,
|
||||
`govoplan-datasources`, and `govoplan-dataflow`, Wave 2. Reporting owns
|
||||
presentation/publication, Connectors owns transport, Datasources owns the
|
||||
governed source/materialization catalogue, and Dataflow owns transformations.
|
||||
|
||||
### Public-Sector Protocols And Registries
|
||||
|
||||
|
||||
@@ -0,0 +1,143 @@
|
||||
# State And Recovery Contract
|
||||
|
||||
## State Profiles
|
||||
|
||||
Core accepts three runtime state profiles:
|
||||
|
||||
| Profile | Runtime placement | Durable storage |
|
||||
| --- | --- | --- |
|
||||
| `local` | One development process set | Local filesystem is permitted. |
|
||||
| `host-shared` | Replicas on one host | One host-shared volume plus PostgreSQL and Redis. |
|
||||
| `shared` | Independent hosts | PostgreSQL, Redis, and S3-compatible object storage. |
|
||||
|
||||
All replicas in one installation use one stable
|
||||
`GOVOPLAN_INSTALLATION_ID`, one immutable module composition, and identical
|
||||
database, broker, encryption-key, and object-storage bindings. Core rejects
|
||||
replicas with the `local` profile and rejects `shared` without PostgreSQL,
|
||||
Redis, S3, and a non-default installation identifier.
|
||||
|
||||
`FILE_STORAGE_S3_ENDPOINT_TRUSTED=true` is an explicit deployment trust
|
||||
declaration for a clean HTTPS S3 origin. It does not authorize a
|
||||
user-controlled connector endpoint and it is separate from installer-managed
|
||||
Garage's exact endpoint trust.
|
||||
|
||||
## Object Storage
|
||||
|
||||
`govoplan_core.core.object_storage` is the shared backend contract for durable
|
||||
module artifacts. It provides bounded read/write/list/stat/delete operations
|
||||
for local and S3-compatible storage. Modules own their object-key namespace and
|
||||
business metadata; Core does not interpret module files.
|
||||
|
||||
Rules for modules:
|
||||
|
||||
- Store only opaque object keys in business records, never local absolute
|
||||
paths.
|
||||
- Use node-local directories only for temporary materialization.
|
||||
- Verify expected size and digest before consuming consequential artifacts.
|
||||
- If object creation precedes database commit, compensate successfully created
|
||||
objects on failure.
|
||||
- If object deletion fails, retain the database reference and report a retryable
|
||||
failure rather than claiming deletion.
|
||||
- Define an orphan-inventory strategy for hard process loss between object
|
||||
creation and metadata commit.
|
||||
|
||||
The Files module delegates its backend implementation to this Core contract.
|
||||
Campaign generated EML artifacts use a Campaign-owned object prefix and are
|
||||
read by workers through the same shared backend.
|
||||
|
||||
## Runtime Nodes And Leases
|
||||
|
||||
API and worker incarnations register in `core_runtime_nodes` with role,
|
||||
software version, module-composition hash, queues, start time, and heartbeat.
|
||||
The registration identity includes a process incarnation so a stale process
|
||||
cannot update a replacement's row.
|
||||
|
||||
Drain is durable operator intent:
|
||||
|
||||
- an API enters not-ready state after observing drain;
|
||||
- a worker cancels queue consumers after observing drain;
|
||||
- cancellation returns an eligible draining node to active state;
|
||||
- clean shutdown marks the matching incarnation stopped.
|
||||
|
||||
Coordination loss also fails closed. An API reports
|
||||
`coordination_unavailable` from `/health/ready` until a heartbeat succeeds
|
||||
again. A worker cancels its local queue consumers on any heartbeat or database
|
||||
failure and only resumes them after its existing incarnation heartbeats
|
||||
successfully. It never re-registers from the heartbeat path, so a stale worker
|
||||
cannot reclaim a node identity from its replacement.
|
||||
|
||||
`core_distributed_leases` provides installation/resource uniqueness, expiry,
|
||||
holder incarnation, and monotonically increasing fencing tokens. Lease expiry
|
||||
does not make an old process harmless by itself: code performing an effect must
|
||||
assert its exact fence before commit. `govoplan_core.commands.fenced_run`
|
||||
renews a lease around a subprocess and terminates the child when the lease is
|
||||
lost. The deployment profiles use it for the singleton scheduler.
|
||||
|
||||
## Migration Ordering
|
||||
|
||||
Only `govoplan_core.commands.init_db` mutates schema. On PostgreSQL it acquires
|
||||
a deterministic installation/track advisory lock before pre-migration tasks,
|
||||
Alembic, and post-migration tasks. The lock is session-scoped and therefore
|
||||
released if the migration process dies.
|
||||
|
||||
Runtime roles run `govoplan_core.commands.wait_for_database`. It waits until
|
||||
the database has exactly the configured Core/module Alembic heads and never
|
||||
upgrades schema. This permits a migration Job and runtime Deployments to be
|
||||
submitted together while keeping startup fail-closed.
|
||||
|
||||
## Recovery Ledger
|
||||
|
||||
`govoplan_core.core.recovery` provides a durable operation and evidence
|
||||
contract. Recovery modes are:
|
||||
|
||||
- `atomic`: one database transaction, no external effect;
|
||||
- `compensation`: explicit inverse actions;
|
||||
- `snapshot_restore`: separately verified backup reference;
|
||||
- `forward_recovery`: repair/resume the current version;
|
||||
- `irreversible`: explicit approval, no automated recovery claim.
|
||||
|
||||
Every plan requires verification steps. Mode-specific evidence is mandatory.
|
||||
Operations bind an idempotency key to a canonical request hash, may bind a
|
||||
runtime fencing token, and emit append-only hash-chained checkpoints. Backup
|
||||
and approval references are part of the hashed plan evidence. Every low-level
|
||||
state transition and checkpoint append revalidates the operation's recorded
|
||||
fence while holding the operation row lock. Plaintext secrets are rejected
|
||||
from metadata and evidence.
|
||||
|
||||
The state machine makes partial and uncertain outcomes visible. A non-atomic
|
||||
running operation cannot transition directly to ordinary failure, and success
|
||||
or recovery requires explicit verified checks. Ops projects states requiring
|
||||
attention, but module behavior gains this guarantee only after it adopts the
|
||||
ledger around its own side effects.
|
||||
|
||||
## Recovery Boundary
|
||||
|
||||
Application/configuration rollback and database rollback are not equivalent.
|
||||
Once an incompatible migration starts, old code may be unsafe even if its image
|
||||
is available. Deployment automation must switch to forward recovery unless a
|
||||
coordinated and verified database/object/key backup is restored.
|
||||
|
||||
Core does not create production database backups. The deployment owner must
|
||||
provide backup, retention, encryption, restore verification, and recovery-point
|
||||
coordination for PostgreSQL, object storage, and encryption keys. The canonical
|
||||
operator procedure is documented in
|
||||
`govoplan/docs/RECOVERY_AND_ROLLBACK_GUARANTEES.md`.
|
||||
|
||||
## Verification
|
||||
|
||||
Focused contracts are covered by:
|
||||
|
||||
```sh
|
||||
/mnt/DATA/git/govoplan/.venv/bin/python -m pytest -q \
|
||||
tests/test_object_storage.py \
|
||||
tests/test_runtime_coordination.py \
|
||||
tests/test_runtime_agents.py \
|
||||
tests/test_fenced_run.py \
|
||||
tests/test_migration_lock.py \
|
||||
tests/test_wait_for_database.py \
|
||||
tests/test_recovery_guarantees.py
|
||||
```
|
||||
|
||||
Production acceptance additionally requires multi-node failure and coordinated
|
||||
restore drills against the actual PostgreSQL, Redis, object-store, ingress, and
|
||||
secret-provider topology.
|
||||
Reference in New Issue
Block a user