[Feature] Define shared institutional-context and governed reference primitives #280

New Issue

2026-07-31T23:59:08+02:00

zemion commented

2026-07-31 23:59:08 +02:00

Outcome

Let modules preserve institutional context and evidence consistently without sharing domain tables or creating parallel DTO families.

Parent: GovOPlaN/govoplan#29

Scope

Inventory and extend existing Core actor/access, references, policy provenance, external references, events, automation effects, ownership, and evidence contracts with the smallest compatible primitives for:

tenant/institution, organization unit, function, mandate/jurisdiction, service, case, party, and decision references;
legal or organizational basis and effective rule/version references;
real actor, represented function/party, delegation or power, and system/service account provenance;
valid/recorded/superseded time, revision, change reason, evidence, classification, purpose, retention, and inspection links;
a common geo reference for coordinates/geometry, administrative area, CRS, source, accuracy, validity, and external GIS identity.

Guardrails

Core owns DTOs/protocols only, never Mandate, Service, Party, Decision, or GIS records.
Existing stable contracts are extended or adapted; no duplicate generic-reference hierarchy.
Fields are optional by domain, but consequential actions can declare which context is mandatory.

Acceptance criteria

Contract tests cover serialization, versioning, invalid cross-tenant references, effective-time context, and redaction.
Audit/event/action envelopes can carry the references without leaking protected payloads.
One Case/Committee/Workflow path proves end-to-end reconstruction.
Documentation states which owning module resolves each reference.

## Outcome Let modules preserve institutional context and evidence consistently without sharing domain tables or creating parallel DTO families. Parent: https://git.add-ideas.de/GovOPlaN/govoplan/issues/29 ## Scope Inventory and extend existing Core actor/access, references, policy provenance, external references, events, automation effects, ownership, and evidence contracts with the smallest compatible primitives for: - tenant/institution, organization unit, function, mandate/jurisdiction, service, case, party, and decision references; - legal or organizational basis and effective rule/version references; - real actor, represented function/party, delegation or power, and system/service account provenance; - valid/recorded/superseded time, revision, change reason, evidence, classification, purpose, retention, and inspection links; - a common geo reference for coordinates/geometry, administrative area, CRS, source, accuracy, validity, and external GIS identity. ## Guardrails - Core owns DTOs/protocols only, never Mandate, Service, Party, Decision, or GIS records. - Existing stable contracts are extended or adapted; no duplicate generic-reference hierarchy. - Fields are optional by domain, but consequential actions can declare which context is mandatory. ## Acceptance criteria - Contract tests cover serialization, versioning, invalid cross-tenant references, effective-time context, and redaction. - Audit/event/action envelopes can carry the references without leaking protected payloads. - One Case/Committee/Workflow path proves end-to-end reconstruction. - Documentation states which owning module resolves each reference.

zemion added the area/governance area/docs

area/api module/core labels 2026-07-31 23:59:08 +02:00

zemion referenced this issue from GovOPlaN/govoplan

2026-08-01 00:00:54 +02:00

[Epic] Adopt the institutional governance target architecture #29

zemion commented

2026-08-01 03:31:57 +02:00

Codex State: done

Summary

Added versioned institutional, temporal, actor/representation, legal-basis, evidence, information-governance, external-source, presentation, and geographic reference primitives.
Events, automation actions, Audit records, and the transactional Audit outbox preserve the governed context without importing optional module tables.
Provider-neutral Mandate, Service, Party, and formal Decision DTO/protocol contracts have strict validation, protected-field serialization, and portable round trips.
Committee now proves a capability-based mandate-to-formal-decision path with reconstructable authority, approval, legal basis, evidence, reasoning, and operative result.

Changed Files

src/govoplan_core/core/institutional.py
src/govoplan_core/core/events.py
src/govoplan_core/core/automation.py
docs/INSTITUTIONAL_CONTEXT_CONTRACT.md
/mnt/DATA/git/govoplan-committee/src/govoplan_committee/backend/decision_path.py

Verification

Core institutional contract tests: 7 passed
Audit outbox delivery tests: 7 passed
Committee module tests: 3 passed

## Codex State: done ### Summary - Added versioned institutional, temporal, actor/representation, legal-basis, evidence, information-governance, external-source, presentation, and geographic reference primitives. - Events, automation actions, Audit records, and the transactional Audit outbox preserve the governed context without importing optional module tables. - Provider-neutral Mandate, Service, Party, and formal Decision DTO/protocol contracts have strict validation, protected-field serialization, and portable round trips. - Committee now proves a capability-based mandate-to-formal-decision path with reconstructable authority, approval, legal basis, evidence, reasoning, and operative result. ### Changed Files - `src/govoplan_core/core/institutional.py` - `src/govoplan_core/core/events.py` - `src/govoplan_core/core/automation.py` - `docs/INSTITUTIONAL_CONTEXT_CONTRACT.md` - `/mnt/DATA/git/govoplan-committee/src/govoplan_committee/backend/decision_path.py` ### Verification - `Core institutional contract tests: 7 passed` - `Audit outbox delivery tests: 7 passed` - `Committee module tests: 3 passed`

zemion closed this issue

2026-08-01 03:31:57 +02:00

zemion removed the

status

ready

codex/ready labels 2026-08-01 03:36:50 +02:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: GovOPlaN/govoplan-core#280