160 lines
8.5 KiB
Markdown
160 lines
8.5 KiB
Markdown
# 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.
|