# GovOPlaN Policy Contracts

GovOPlaN has several policy families that are moving out of core into owning
modules. The shared kernel contract keeps their decision and provenance shape
consistent while each module still owns its domain rules.

## Current Policy Inventory

| Policy area | Current owner | Runtime surface | Notes |
| --- | --- | --- | --- |
| Privacy retention | `govoplan-policy` routes with compatibility helpers in core | `/api/v1/admin/privacy-retention/policies/{scope}` and `/explain` | System, tenant, user, group, and campaign sources merge into the effective retention policy. Parent locks block lower-level widening. |
| Mail profile policy | `govoplan-mail` | `/api/v1/mail/policies/{scope}` | Uses the same source-step path format for system, tenant, owner, and campaign provenance. |
| RBAC/access policy | `govoplan-access` | access capabilities in `govoplan_core.core.access` | Permission decisions should use access capability contracts. Explain responses should adopt `PolicyDecision` when an API-level explanation is added. |
| Governance defaults | `govoplan-admin` plus `govoplan-access` materializer | admin settings, governance template routes, access materialization capability | System governance can block tenant-local groups, roles, and API keys. |
| Delegation and ownership policy | access/campaign/mail/files modules | capability checks and owner-scoped APIs | Source provenance should use this contract when policies become externally explainable. |

## Policy Decision

The shared DTO lives in `govoplan_core.core.policy.PolicyDecision`.

```json
{
  "allowed": false,
  "reason": "Parent retention policy locks lower-level changes.",
  "source_path": [
    {
      "scope_type": "system",
      "scope_id": null,
      "path": "system",
      "label": "System",
      "applied_fields": ["allow_lower_level_limits"],
      "policy": {}
    }
  ],
  "requirements": ["raw_campaign_json_retention_days"],
  "details": {
    "blocked_fields": ["raw_campaign_json_retention_days"]
  }
}
```

`allowed` is the effective answer for the checked action. `reason` is a stable,
human-readable summary. `source_path` lists the policy sources that explain the
answer. `requirements` lists machine-readable blockers or prerequisites, and
`details` carries domain-specific structured context.

Every source step should be concrete enough for an operator to understand the
decision without knowing internal merge rules. Use real scope labels such as
`System`, `Tenant`, `Owner user`, `Group`, or a campaign/profile name. Include
the stable `path`, the fields applied by that step, and the local policy
fragment that caused them. This lets UIs render explanations like
`System: Allow > Tenant: Deny without override` without additional lookups.
If a policy family cannot expose the full local fragment for security reasons,
it must still include a redacted structured value that identifies the applied
field and the effective allow/deny or lock state.

## Source Path Format

Policy source paths are stable string identifiers for provenance steps:

- `system`
- `<scope_type>:<url-encoded-scope-id>`

Supported scope types are `system`, `tenant`, `user`, `group`, and `campaign`.
Examples:

- `tenant:4a45b4fe-1d86-43ce-9d10-6022333f4d4b`
- `campaign:campaign%2Fwith%20space`

Use `policy_source_path()` and `parse_policy_source_path()` instead of building
or splitting these strings manually.

## Retention Explain Endpoint

`GET /api/v1/admin/privacy-retention/policies/{scope_type}/explain` returns:

- `scope_type` and optional `scope_id`
- `decision`, using the shared `PolicyDecision` shape
- `effective_policy`
- optional `parent_policy`
- `effective_policy_sources`
- `parent_policy_sources`
- `blocked_fields`

The endpoint is read-only. Enforcement remains in the existing policy write
path. For lower-level scopes, `blocked_fields` is derived from the parent
policy's `allow_lower_level_limits`; clients can use it to disable local
controls before attempting a write.

## Frontend Contract

Policy UIs must:

- render effective source provenance when `effective_policy_sources` is present
- display a field-level path when the source data is shown next to a specific
  setting, using concrete source labels and stop at the first non-overridable
  deny/lock
- disable local field controls when the parent policy sets that field's
  lower-level limit to `false`
- avoid sending locked fields or re-enable attempts in save payloads
- show inherited values separately from local overrides

The core WebUI helper `privacyRetentionParentAllowsField()` centralizes the
field-lock decision used by the retention editor and its lightweight module
tests.