# 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 `/` 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.