Add hierarchical policy simulation helpers

docs/POLICY_DECISION_PROVENANCE.md

@@ -9,6 +9,13 @@ Privacy retention implementation lives in this module at
 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.
@@ -47,6 +54,18 @@ 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