Sync Repo-docs-INSTITUTIONAL-CONTEXT-CONTRACT from project files
@@ -0,0 +1,133 @@
|
|||||||
|
<!-- codex-wiki-sync:42e1b7d33bbc9168ac2c37cf -->
|
||||||
|
|
||||||
|
> 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.
|
||||||
Reference in New Issue
Block a user