feat(decisions): add governed DSAR coverage

2026-08-21 12:06:09 +02:00
parent 3845e068de
commit e6ea0d6b72
3 changed files with 524 additions and 0 deletions
@@ -0,0 +1,268 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from sqlalchemy.orm import Session
+
+from govoplan_core.core.dsar import (
+    DsarErasureActionRef,
+    DsarExecutionResultRef,
+    DsarRecordRef,
+    DsarSubjectRef,
+    dsar_capability_name,
+)
+from govoplan_decisions.backend.db.models import FormalDecisionRevision
+
+
+DECISIONS_DSAR_CAPABILITY = dsar_capability_name("decisions")
+_MAX_RECORDS = 5_000
+_CONFLICT = object()
+
+
+@dataclass(frozen=True, slots=True)
+class _SubjectSelectors:
+    actor_ids: tuple[str, ...]
+    decision_id: str | None
+
+
+class DecisionsDsarProvider:
+    provider_id = "decisions"
+    module_id = "decisions"
+
+    def search_subject(
+        self,
+        session: object,
+        *,
+        tenant_id: str,
+        subject: DsarSubjectRef,
+    ) -> Sequence[DsarRecordRef]:
+        db = _session(session)
+        selectors = _subject_selectors(subject)
+        if selectors is None:
+            return ()
+        query = db.query(FormalDecisionRevision).filter(
+            FormalDecisionRevision.tenant_id == tenant_id,
+            FormalDecisionRevision.created_by.in_(selectors.actor_ids),
+        )
+        if selectors.decision_id:
+            query = query.filter(
+                FormalDecisionRevision.decision_id == selectors.decision_id
+            )
+        rows = (
+            query.order_by(
+                FormalDecisionRevision.recorded_at,
+                FormalDecisionRevision.id,
+            )
+            .limit(_MAX_RECORDS + 1)
+            .all()
+        )
+        if len(rows) > _MAX_RECORDS:
+            raise ValueError(
+                "Decisions DSAR result limit exceeded; narrow the selectors."
+            )
+        return tuple(_decision_attribution(row) for row in rows)
+
+    def plan_erasure(
+        self,
+        session: object,
+        *,
+        tenant_id: str,
+        subject: DsarSubjectRef,
+        records: Sequence[DsarRecordRef],
+    ) -> Sequence[DsarErasureActionRef]:
+        del tenant_id
+        _session(session)
+        if _subject_selectors(subject) is None:
+            raise ValueError("Decisions DSAR subject selectors conflict.")
+        actions: list[DsarErasureActionRef] = []
+        for record in records:
+            _validate_record(record)
+            actions.append(
+                DsarErasureActionRef(
+                    action_id=(
+                        f"decisions:retain:formal_decision_actor_attribution:"
+                        f"{record.resource_id}"
+                    ),
+                    provider_id=self.provider_id,
+                    module_id=self.module_id,
+                    kind="retain",
+                    resource_type=record.resource_type,
+                    resource_id=record.resource_id,
+                    title=f"Retain {record.title}",
+                    rationale=record.retention_reason
+                    or "Formal Decision attribution is immutable evidence.",
+                    executable=False,
+                )
+            )
+        return tuple(actions)
+
+    def execute_erasure(
+        self,
+        session: object,
+        *,
+        tenant_id: str,
+        subject: DsarSubjectRef,
+        actions: Sequence[DsarErasureActionRef],
+        request_id: str,
+    ) -> Sequence[DsarExecutionResultRef]:
+        del tenant_id
+        _session(session)
+        if _subject_selectors(subject) is None:
+            raise ValueError("Decisions DSAR subject selectors conflict.")
+        results: list[DsarExecutionResultRef] = []
+        for action in actions:
+            _validate_action(action)
+            if action.executable or action.kind != "retain":
+                raise ValueError("Decisions DSAR publishes retain-only actions.")
+            results.append(
+                DsarExecutionResultRef(
+                    action_id=action.action_id,
+                    status="blocked",
+                    summary=(
+                        "Formal Decision attribution remains immutable institutional "
+                        "and legal evidence."
+                    ),
+                    evidence={"request_id": request_id},
+                )
+            )
+        return tuple(results)
+
+
+def _subject_selectors(subject: DsarSubjectRef) -> _SubjectSelectors | None:
+    references = subject.external_references
+    values = {
+        "account_id": _coalesce(
+            subject.account_id,
+            references.get("decisions.account"),
+            references.get("access.account"),
+        ),
+        "membership_id": _coalesce(
+            subject.membership_id,
+            references.get("decisions.membership"),
+            references.get("tenancy.membership"),
+        ),
+        "identity_id": _coalesce(
+            subject.identity_id,
+            references.get("decisions.identity"),
+            references.get("identity.id"),
+        ),
+        "actor_id": _coalesce(
+            references.get("decisions.actor"),
+            references.get("decisions.created_by"),
+        ),
+        "decision_id": _coalesce(
+            references.get("decisions.decision"),
+            references.get("decisions.decision_id"),
+        ),
+    }
+    if any(value is _CONFLICT for value in values.values()):
+        return None
+    actor_ids = tuple(
+        dict.fromkeys(
+            value
+            for value in (
+                _optional_string(values["account_id"]),
+                _prefixed("account", values["account_id"]),
+                _optional_string(values["membership_id"]),
+                _prefixed("membership", values["membership_id"]),
+                _optional_string(values["identity_id"]),
+                _prefixed("identity", values["identity_id"]),
+            )
+            if value
+        )
+    )
+    direct_actor = _optional_string(values["actor_id"])
+    if direct_actor:
+        if actor_ids and direct_actor not in actor_ids:
+            return None
+        if not actor_ids:
+            actor_ids = (direct_actor,)
+    if not actor_ids:
+        return None
+    return _SubjectSelectors(
+        actor_ids=actor_ids,
+        decision_id=_optional_string(values["decision_id"]),
+    )
+
+
+def _decision_attribution(row: FormalDecisionRevision) -> DsarRecordRef:
+    return DsarRecordRef(
+        provider_id="decisions",
+        module_id="decisions",
+        resource_type="formal_decision_actor_attribution",
+        resource_id=row.id,
+        category="formal_decision_accountability",
+        title="Formal Decision creator attribution",
+        data={
+            "decision_id": row.decision_id,
+            "revision": row.revision,
+            "decision_type": row.decision_type,
+            "state": row.state,
+            "valid_from": _iso(row.valid_from),
+            "valid_to": _iso(row.valid_to),
+            "recorded_at": _iso(row.recorded_at),
+            "superseded_at": _iso(row.superseded_at),
+            "activity": "recorded_formal_decision_revision",
+        },
+        observed_at=_aware(row.recorded_at),
+        immutable_evidence=True,
+        retention_reason=(
+            "Formal Decision creator attribution is immutable institutional and "
+            "legal accountability evidence."
+        ),
+    )
+
+
+def _coalesce(*values: str | None) -> str | None | object:
+    normalized = {str(value).strip() for value in values if str(value or "").strip()}
+    if len(normalized) > 1:
+        return _CONFLICT
+    return next(iter(normalized), None)
+
+
+def _optional_string(value: object) -> str | None:
+    return value if isinstance(value, str) and value else None
+
+
+def _prefixed(prefix: str, value: object) -> str | None:
+    normalized = _optional_string(value)
+    return f"{prefix}:{normalized}" if normalized else None
+
+
+def _iso(value: datetime | None) -> str | None:
+    aware = _aware(value)
+    return aware.isoformat() if aware else None
+
+
+def _aware(value: datetime | None) -> datetime | None:
+    if value is None or value.tzinfo is not None:
+        return value
+    return value.replace(tzinfo=timezone.utc)
+
+
+def _session(value: object) -> Session:
+    if not isinstance(value, Session):
+        raise TypeError("Decisions DSAR requires a SQLAlchemy Session.")
+    return value
+
+
+def _validate_record(record: DsarRecordRef) -> None:
+    if record.provider_id != "decisions" or record.module_id != "decisions":
+        raise ValueError("Decisions DSAR cannot plan a foreign provider record.")
+    if (
+        record.resource_type != "formal_decision_actor_attribution"
+        or not record.resource_id
+    ):
+        raise ValueError("Decisions DSAR record identity is invalid.")
+
+
+def _validate_action(action: DsarErasureActionRef) -> None:
+    if action.provider_id != "decisions" or action.module_id != "decisions":
+        raise ValueError("Decisions DSAR cannot execute a foreign provider action.")
+    if not action.action_id.startswith("decisions:retain:"):
+        raise ValueError("Decisions DSAR action identity is invalid.")
+
+
+__all__ = ["DECISIONS_DSAR_CAPABILITY", "DecisionsDsarProvider"]
@@ -22,6 +22,10 @@ from govoplan_core.core.provider_governance import declared_module_architecture
 from govoplan_core.core.search import SearchSourceProviderRegistration
 from govoplan_core.db.base import Base
 from govoplan_decisions.backend.db import models as decision_models
+from govoplan_decisions.backend.dsar_provider import (
+    DECISIONS_DSAR_CAPABILITY,
+    DecisionsDsarProvider,
+)
 from govoplan_decisions.backend.record_source import (
    CAPABILITY_RECORD_SOURCE_DECISIONS,
    create_decisions_record_source,
@@ -63,6 +67,10 @@ def _registry(_context: ModuleContext) -> SqlDecisionRegistry:
    return SqlDecisionRegistry()


+def _dsar_provider(_context: ModuleContext) -> DecisionsDsarProvider:
+    return DecisionsDsarProvider()
+
+
 manifest = ModuleManifest(
    id=MODULE_ID,
    name=MODULE_NAME,
@@ -85,6 +93,7 @@ manifest = ModuleManifest(
        ModuleInterfaceProvider(
            name=CAPABILITY_RECORD_SOURCE_DECISIONS, version="1.0.0"
        ),
+        ModuleInterfaceProvider(name=DECISIONS_DSAR_CAPABILITY, version="0.1.0"),
    ),
    permissions=(
        _permission(
@@ -126,6 +135,7 @@ manifest = ModuleManifest(
    capability_factories={
        CAPABILITY_DECISION_REGISTRY: _registry,
        CAPABILITY_RECORD_SOURCE_DECISIONS: create_decisions_record_source,
+        DECISIONS_DSAR_CAPABILITY: _dsar_provider,
    },
    capability_documentation={
        CAPABILITY_DECISION_REGISTRY: CapabilityDocumentation(
@@ -138,6 +148,14 @@ manifest = ModuleManifest(
            summary="Resolves complete, currently authorized immutable Decision revisions for Records filing.",
            contract_version="1.0.0",
        ),
+        DECISIONS_DSAR_CAPABILITY: CapabilityDocumentation(
+            label="Decisions data-subject request provider",
+            summary=(
+                "Exports minimized formal-Decision creator attribution without "
+                "protected reasoning, outcomes, conditions, or payloads."
+            ),
+            contract_version="0.1.0",
+        ),
    },
    migration_spec=MigrationSpec(
        module_id=MODULE_ID,
@@ -161,6 +179,40 @@ manifest = ModuleManifest(
        ),
    ),
    documentation=(
+        DocumentationTopic(
+            id="decisions.data-subject-requests",
+            title="Formal Decision data-subject requests",
+            summary=(
+                "Export minimized creator attribution from immutable formal Decision "
+                "revisions without exposing protected Decision content."
+            ),
+            body=(
+                "Decisions searches exact account, membership, identity, or explicit "
+                "actor identifiers inside the active tenant. An optional Decision "
+                "identifier only narrows that verified actor search and cannot disclose "
+                "a Decision by itself. The access record contains revision, type, state, "
+                "valid-time, recorded-time, and creator activity only. Protected "
+                "reasoning, operative results, conditions, evidence payloads, and "
+                "digests remain excluded. Formal Decision history is immutable legal "
+                "and institutional evidence, so the provider publishes retain-only "
+                "erasure outcomes and never rewrites a revision."
+            ),
+            layer="configured",
+            documentation_types=("admin", "user"),
+            audience=("user", "operator", "module_admin", "auditor"),
+            related_modules=("core", "approvals", "committee", "records"),
+            metadata={
+                "help_contexts": ["privacy.data-subject-requests"],
+                "consequence_classes": {
+                    "export_creator_attribution": (
+                        "Returns lifecycle and creator context without protected payloads."
+                    ),
+                    "retain_formal_history": (
+                        "Preserves immutable institutional and legal evidence."
+                    ),
+                },
+            },
+        ),
        DocumentationTopic(
            id="decisions.formal-outcome",
            title="Formal institutional Decisions",