From 0ca54dbe47c9227d63cad3c635f19e95dc1c71a6 Mon Sep 17 00:00:00 2001 From: zemion Date: Sat, 1 Aug 2026 08:56:08 +0200 Subject: [PATCH] Sync Repo-docs-INSTITUTIONAL-CONTEXT-CONTRACT from project files --- Repo-docs-INSTITUTIONAL-CONTEXT-CONTRACT.-.md | 133 ++++++++++++++++++ 1 file changed, 133 insertions(+) create mode 100644 Repo-docs-INSTITUTIONAL-CONTEXT-CONTRACT.-.md diff --git a/Repo-docs-INSTITUTIONAL-CONTEXT-CONTRACT.-.md b/Repo-docs-INSTITUTIONAL-CONTEXT-CONTRACT.-.md new file mode 100644 index 0000000..375eb69 --- /dev/null +++ b/Repo-docs-INSTITUTIONAL-CONTEXT-CONTRACT.-.md @@ -0,0 +1,133 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan-core/docs/INSTITUTIONAL_CONTEXT_CONTRACT.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# 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. + +## 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.