[Architecture] Define versioned institutional service semantics #31

New Issue

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

zemion commented

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

Outcome

Model the institutional service promise independently from the Portal surface that presents and starts it.

Parent: #29

Service definition

Include stable key/version/effective interval, audience, prerequisites, legal/organizational basis, required evidence, fees, deadlines, channels, responsible organization/function, mandate/jurisdiction, form/case/workflow/result/decision/output bindings, remedies, service levels, publication, and availability explanation.

Boundary and migration

Portal owns discovery, presentation, entry, and channel UX. Forms, Cases, Workflow Engine, Decisions, Reporting, Records, and external publication consume stable service references through capabilities. Existing module-contributed Portal service entries remain a compatibility input.

Do not create govoplan-services until definitions require independent persistence/lifecycle and are used outside Portal by another procedure or publication consumer.

Acceptance criteria

One service definition drives a Portal entry and at least one downstream Case/Form/Workflow or publication binding.
Availability explains missing module, capability, mandate, policy, connector, maintenance, or audience requirements.
Versions and effective dates preserve what promise applied to an existing case.
Tenant/package inheritance cannot silently widen system constraints.
Docs distinguish visible services, unavailable-but-explainable services, and undiscoverable services.

## Outcome Model the institutional service promise independently from the Portal surface that presents and starts it. Parent: https://git.add-ideas.de/GovOPlaN/govoplan/issues/29 ## Service definition Include stable key/version/effective interval, audience, prerequisites, legal/organizational basis, required evidence, fees, deadlines, channels, responsible organization/function, mandate/jurisdiction, form/case/workflow/result/decision/output bindings, remedies, service levels, publication, and availability explanation. ## Boundary and migration Portal owns discovery, presentation, entry, and channel UX. Forms, Cases, Workflow Engine, Decisions, Reporting, Records, and external publication consume stable service references through capabilities. Existing module-contributed Portal service entries remain a compatibility input. Do not create `govoplan-services` until definitions require independent persistence/lifecycle and are used outside Portal by another procedure or publication consumer. ## Acceptance criteria - One service definition drives a Portal entry and at least one downstream Case/Form/Workflow or publication binding. - Availability explains missing module, capability, mandate, policy, connector, maintenance, or audience requirements. - Versions and effective dates preserve what promise applied to an existing case. - Tenant/package inheritance cannot silently widen system constraints. - Docs distinguish visible services, unavailable-but-explainable services, and undiscoverable services.

zemion added the module/cases module/forms module/portal area/docs area/governance module/workflow

area/api module/services labels 2026-07-31 23:59:09 +02:00

zemion referenced this issue

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

[Epic] Adopt the institutional governance target architecture #29

zemion referenced this issue from GovOPlaN/govoplan-portal

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

Model role-based service directory and availability explanations #1

zemion commented

2026-08-01 03:33:17 +02:00

Codex State: progress

Summary

Core now defines a versioned ServiceDefinition and provider protocol covering audience, legal basis, channels, responsibility, mandate/jurisdiction, bindings, availability, remedies, service levels, publication state, and effective time.

Verification

Semantic DTO validation and serialization round-trip tests pass.

Next / Blocked

Prove one definition through Portal plus a downstream Case/Form/Workflow or publication consumer, then add inherited constraint and availability-projection tests.

Suggested status label: status/in-progress

## Codex State: progress ### Summary - Core now defines a versioned ServiceDefinition and provider protocol covering audience, legal basis, channels, responsibility, mandate/jurisdiction, bindings, availability, remedies, service levels, publication state, and effective time. ### Verification - `Semantic DTO validation and serialization round-trip tests pass.` ### Next / Blocked - Prove one definition through Portal plus a downstream Case/Form/Workflow or publication consumer, then add inherited constraint and availability-projection tests. Suggested status label: `status/in-progress`

zemion added

and removed

labels 2026-08-01 03:35:41 +02:00

zemion referenced this issue

2026-08-01 08:21:48 +02:00

[Epic] Adopt the institutional governance target architecture #29

zemion commented

2026-08-01 08:46:03 +02:00

Codex State: progress

Summary

Portal now exposes a provider-neutral service directory with available, explainably unavailable, and hidden states; it fails reduced compositions to an empty directory.
Cases consumes the exact same published/effective Service version into a governed intake plan retaining responsibility, Mandate, jurisdiction, legal basis, evidence, deadline, form, workflow, case, and result bindings.

Changed Files

govoplan-portal/src/govoplan_portal/backend/service_directory.py
govoplan-cases/src/govoplan_cases/backend/service_intake.py
govoplan/tests/test_institutional_service_journey.py

Verification

Portal suite: 5 tests passed
Cases suite: 6 tests passed
Cross-repository service journey: 1 test passed

Next / Blocked

Define and prove tenant/package Service inheritance rules that cannot widen parent constraints; keep persistence/provider extraction threshold-based.

Suggested status label: status/in-progress

## Codex State: progress ### Summary - Portal now exposes a provider-neutral service directory with available, explainably unavailable, and hidden states; it fails reduced compositions to an empty directory. - Cases consumes the exact same published/effective Service version into a governed intake plan retaining responsibility, Mandate, jurisdiction, legal basis, evidence, deadline, form, workflow, case, and result bindings. ### Changed Files - `govoplan-portal/src/govoplan_portal/backend/service_directory.py` - `govoplan-cases/src/govoplan_cases/backend/service_intake.py` - `govoplan/tests/test_institutional_service_journey.py` ### Verification - `Portal suite: 5 tests passed` - `Cases suite: 6 tests passed` - `Cross-repository service journey: 1 test passed` ### Next / Blocked - Define and prove tenant/package Service inheritance rules that cannot widen parent constraints; keep persistence/provider extraction threshold-based. Suggested status label: `status/in-progress`

zemion commented

2026-08-01 08:51:53 +02:00

Codex State: done

Summary

One versioned Service definition now drives Portal discovery and Cases intake through provider-neutral capabilities, with exact version/effective-time provenance.
Typed availability covers module, capability, Mandate, policy, connector, maintenance, audience, and configuration requirements; restrictive derivation prevents tenant/package widening.

Verification

Core institutional contract: 13 tests passed
Portal suite: 6 tests passed
Cases suite: 7 tests passed
Cross-repository service journey: 1 test passed

Next / Blocked

A persistent Services repository remains conditional on the documented independent-lifecycle and reuse threshold.

## Codex State: done ### Summary - One versioned Service definition now drives Portal discovery and Cases intake through provider-neutral capabilities, with exact version/effective-time provenance. - Typed availability covers module, capability, Mandate, policy, connector, maintenance, audience, and configuration requirements; restrictive derivation prevents tenant/package widening. ### Verification - `Core institutional contract: 13 tests passed` - `Portal suite: 6 tests passed` - `Cases suite: 7 tests passed` - `Cross-repository service journey: 1 test passed` ### Next / Blocked - A persistent Services repository remains conditional on the documented independent-lifecycle and reuse threshold.

zemion closed this issue

2026-08-01 08:51:53 +02:00

zemion commented

2026-08-01 10:34:51 +02:00

Codex State: done

govoplan-services now persists exact versioned service definitions and publication history, exposes services.definitions and services.availability, prevents restrictive derivations from widening parent constraints, and separates catalogue publication from runtime availability. Portal discovers and Cases freezes the exact provider-owned revision.

tools/checks/check-focused.sh: passed, including 35 WebUI permutations and full-product bundle budgets.
Architecture manifest gate: 60/60 declarations; static contract graph: 60 modules, 98 providers, 54 requirements.
Release migration audit: valid graph including the four new module heads.
SQL-backed institutional golden journey, configuration-package preflight, module tests, Ruff, and startup smoke: passed.

Source push/tagging remains a separate release action.

## Codex State: done `govoplan-services` now persists exact versioned service definitions and publication history, exposes `services.definitions` and `services.availability`, prevents restrictive derivations from widening parent constraints, and separates catalogue publication from runtime availability. Portal discovers and Cases freezes the exact provider-owned revision. - `tools/checks/check-focused.sh`: passed, including 35 WebUI permutations and full-product bundle budgets. - Architecture manifest gate: 60/60 declarations; static contract graph: 60 modules, 98 providers, 54 requirements. - Release migration audit: valid graph including the four new module heads. - SQL-backed institutional golden journey, configuration-package preflight, module tests, Ruff, and startup smoke: passed. Source push/tagging remains a separate release action.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: GovOPlaN/govoplan#31