From ab0fad07346443a674a972bb60552a868818d0fc Mon Sep 17 00:00:00 2001 From: Albrecht Degering Date: Tue, 28 Jul 2026 15:08:46 +0200 Subject: [PATCH] Sync wiki from project files --- Codex-Project-Index.md | 1 + Repo-README.md | 41 +++++++- Repo-docs-POLICY-DECISION-PROVENANCE.md | 132 ++++++++++++++++++++++++ 3 files changed, 169 insertions(+), 5 deletions(-) create mode 100644 Repo-docs-POLICY-DECISION-PROVENANCE.md diff --git a/Codex-Project-Index.md b/Codex-Project-Index.md index 25e505a..7d9c734 100644 --- a/Codex-Project-Index.md +++ b/Codex-Project-Index.md @@ -5,3 +5,4 @@ This page is generated from repository and product-directory project files. - [Repo-README](Repo-README) - `/mnt/DATA/git/govoplan-policy/README.md` +- [Repo-docs-POLICY-DECISION-PROVENANCE](Repo-docs-POLICY-DECISION-PROVENANCE) - `/mnt/DATA/git/govoplan-policy/docs/POLICY_DECISION_PROVENANCE.md` diff --git a/Repo-README.md b/Repo-README.md index d91e2c3..02af5a0 100644 --- a/Repo-README.md +++ b/Repo-README.md @@ -1,4 +1,4 @@ - + > Mirrored from `/mnt/DATA/git/govoplan-policy/README.md`. > Origin: `repository`. @@ -7,8 +7,39 @@ --- # GovOPlaN Policy -`govoplan-policy` owns policy and retention API route contributions during the -GovOPlaN module split. + +**Repository type:** module (platform). + -The current package delegates to the legacy access administration -implementation while route ownership is separated before model migration. +`govoplan-policy` owns policy and retention API route contributions and the +retention administration WebUI sections during the GovOPlaN module split. + +The `@govoplan/policy-webui` package contributes system, tenant, group, and +user retention sections through the shared `admin.sections` UI capability. The +admin shell does not render retention policy panels unless this module is +installed and enabled. + +Policy decision and provenance payloads use the shared kernel DTOs documented +in [docs/POLICY_DECISION_PROVENANCE.md](docs/POLICY_DECISION_PROVENANCE.md) +and `/mnt/DATA/git/govoplan-core/docs/POLICY_CONTRACTS.md`. + +Hierarchical policy evaluation, delegation ceilings, and write simulations are +implemented in `govoplan_policy.backend.hierarchy`. Privacy retention uses that +shared helper and exposes `/api/v1/admin/privacy-retention/policies/{scope}/simulate` +for preflight checks before saving lower-level policy changes. + +The module also provides the optional +`policy.schedulingParticipantPrivacy` capability. Scheduling owns each +request's participant-visibility setting; Policy can only preserve or narrow +it. The resolver reads an optional `maximum_visibility` ceiling from the +`scheduling_participant_privacy_policy` object in system and tenant settings. +Missing policy is unrestricted, while malformed explicit policy fails closed +to aggregate-only visibility. This resolver slice intentionally has no policy +management endpoint or UI yet. + +Policy also provides `policy.definitionGovernance` for Dataflow and Workflow +libraries. It evaluates view, edit, run/start, reuse, derive, and automation +actions across system, tenant, group, and user scopes. Templates cannot run or +be automated. Derived definitions retain ancestor ceilings, and every +decision includes the ordered Policy source path and effective limits so a UI +can explain why an action is available or blocked. diff --git a/Repo-docs-POLICY-DECISION-PROVENANCE.md b/Repo-docs-POLICY-DECISION-PROVENANCE.md new file mode 100644 index 0000000..570c303 --- /dev/null +++ b/Repo-docs-POLICY-DECISION-PROVENANCE.md @@ -0,0 +1,132 @@ + + +> Mirrored from `/mnt/DATA/git/govoplan-policy/docs/POLICY_DECISION_PROVENANCE.md`. +> Origin: `repository`. +> Active tasks and changing state belong in Gitea issues; this wiki page is durable project context. + +--- +# Policy Decision And Provenance Contract + +`govoplan-policy` owns policy and retention route contributions. Core keeps the +small shared DTOs that let policy decisions look the same across modules. + +Privacy retention implementation lives in this module at +`govoplan_policy.backend.retention`. It is also exposed as the +`policy.privacyRetention` capability so older core compatibility imports can +dispatch to the active policy module without owning policy logic in core. Core +does not import this implementation as a hidden fallback when policy is +disabled. + +Reusable hierarchical policy validation lives in +`govoplan_policy.backend.hierarchy`. Policy families should use that helper for +parent locks, lower-level override ceilings, "more restrictive only" checks, +and read-only simulations before destructive or limiting changes are saved. +Domain modules keep their own policy fields and restriction rules, but the +decision shape and simulation payload stay consistent. +When retention needs audit-log storage behavior, it requests the +`audit.retention` capability; it does not import audit module tables or +providers directly. + +## Scheduling Participant Privacy + +Policy exposes `policy.schedulingParticipantPrivacy` as an optional restriction +hook. Scheduling supplies the request-level visibility choice and remains +responsible for its secure fallback when Policy is absent. The provider never +broadens that choice. + +System and tenant settings may contain: + +```json +{ + "scheduling_participant_privacy_policy": { + "maximum_visibility": "aggregates_only" + } +} +``` + +`maximum_visibility` is either `aggregates_only` or `names_and_statuses`. +Omitted settings impose no additional restriction. Effective visibility is the +most restrictive of the Scheduling request, the system ceiling, and the tenant +ceiling. Explicit malformed policy fails closed to `aggregates_only` and is +reported in decision details without echoing the invalid stored value. Policy +sources include only explicitly configured or invalid system and tenant steps. + +The current slice is resolver-only. A managed write API and administration UI +must add validation, audit, parent-ceiling enforcement, and configuration +safety registration before operators can edit this setting through GovOPlaN. + +## Backend DTOs + +Use `govoplan_core.core.policy.PolicyDecision` for explainable policy results: + +- `allowed`: effective decision for the checked action. +- `reason`: compact operator-readable explanation. +- `source_path`: ordered policy sources that produced the decision. +- `requirements`: machine-readable blockers or prerequisites. +- `details`: domain-specific structured context, redacted when needed. + +Use `PolicySourceStep` or `policy_source_step()` for each provenance step: + +- `scope_type`: `system`, `tenant`, `user`, `group`, or `campaign`. +- `scope_id`: stable ID for non-system scopes. +- `path`: stable string path generated by `policy_source_path()`. +- `label`: concrete source label such as `System`, `Tenant`, `Owner user`, + `Group`, or `Campaign`. +- `applied_fields`: field names affected by that step. +- `policy`: local policy fragment that explains the applied fields. + +Do not build or split provenance paths manually. Use +`policy_source_path()` and `parse_policy_source_path()` so IDs are URL-encoded +consistently. + +## Retention Explain Endpoint + +Retention policy exposes the shared shape through: + +```text +GET /api/v1/admin/privacy-retention/policies/{scope_type}/explain +``` + +The response contains `decision`, `effective_policy`, `parent_policy`, +`effective_policy_sources`, `parent_policy_sources`, and `blocked_fields`. + +Retention policy also exposes a write-preflight endpoint: + +```text +POST /api/v1/admin/privacy-retention/policies/{scope}/simulate +``` + +The request body is the same as the write endpoint. The response contains a +`simulation` object with `allowed`, `changed_fields`, `issues`, +`before_policy`, `requested_policy`, and a shared `PolicyDecision` payload. +The endpoint never writes policy state and is intended for UI validation before +operators attempt destructive or limiting changes. +Clients can use `blocked_fields` to disable controls before a save attempt. + +## UI Expectations + +Policy UIs should render provenance close to the effective column or field it +explains. The display path should use concrete source labels and local values, +for example: + +```text +System: Allow +> Tenant: Deny without override +``` + +If all lower levels still inherit, continue the path until the effective local +decision: + +```text +System: Allow +> Tenant: Inherit +> Group: Inherit +> Campaign: Deny +``` + +When a parent disallows lower-level limits or changes, the UI should disable +the affected controls and avoid sending those fields in the save payload. + +The shared core WebUI helper `PolicySourcePath` renders the source path shape +for module UIs. Modules may use their own field layout, but the data contract +should remain this shape.