feat: add governed DSAR workflow

docs/DATA_SUBJECT_REQUESTS.md

@@ -0,0 +1,91 @@
+# Data-Subject Request Contract
+
+This document defines the provider-neutral workflow for access and erasure
+requests. It is an operational control and evidence mechanism. It does not
+replace legal review, identity verification, retention policy, or the
+institution's statutory response process.
+
+## Ownership
+
+Core owns the request aggregate, lifecycle API, optimistic concurrency,
+provider discovery, export manifest, execution orchestration, and audit event
+names. Modules that store subject-related data own their search, explanation,
+retention, and mutation behavior through a `privacy.dsar.<module>` capability.
+Core never scans module tables or guesses how a foreign resource may be
+erased.
+
+Access owns the first provider. It finds tenant memberships plus safe account,
+identity, assignment, API-key, and session metadata. It does not export secret
+hashes, session tokens, IP addresses, or browser fingerprints. Tenant-local
+membership data can be anonymized and authentication material can be revoked.
+Global accounts and identities require manual system-level review because they
+may serve more than one tenant.
+
+## Lifecycle
+
+1. A privacy officer records a verified selector, purpose, legal basis, due
+   date, and internal reference.
+2. Search invokes every available tenant capability independently. A provider
+   failure is isolated and recorded; it cannot turn an incomplete search into
+   a successful one.
+3. The JSON export contains the request, records, provider runs, coverage,
+   retention reasons, execution evidence, and a SHA-256 manifest digest.
+4. An erasure request produces stable provider-owned actions. Immutable
+   evidence generates an explicit non-executable `retain` decision.
+5. Execution accepts only selected executable actions from the current plan.
+   It requires `If-Match`, the current resource revision, the dedicated erase
+   permission, and the exact `ERASE <request-id>` confirmation phrase.
+6. Provider execution is idempotent. Completed or unchanged effects remain
+   durable in the request's execution evidence.
+
+The API is rooted at
+`/api/v1/admin/privacy/data-subject-requests`. Access exposes the independent
+permissions `access:privacy:read`, `access:privacy:manage`,
+`access:privacy:export`, and `access:privacy:erase`; the built-in privacy
+officer role contains all four.
+
+## Provider Rules
+
+A provider must:
+
+- enforce tenant ownership for every record and action;
+- return stable, unique resource and action identities;
+- avoid credentials, hashes, tokens, unnecessary telemetry, and unrelated
+  third-party data;
+- distinguish mutable personal data from immutable institutional evidence;
+- state a retention reason for immutable evidence;
+- propose manual review instead of an automatic action when authority is
+  ambiguous or a resource spans tenants;
+- return exactly one execution result per requested action;
+- make execution idempotent and avoid committing the caller's transaction;
+- keep all actual mutations inside the owning module.
+
+Each active module without a DSAR provider is listed in coverage. This is a
+deliberate fail-visible state, not proof that the module stores personal data.
+An institution may call an export complete only after it has reviewed both the
+provider runs and that coverage list.
+
+## Retention And Evidence
+
+Erasure and retention are separate decisions. Stable object IDs, authorization
+history, function incumbency, formal decisions, delivery evidence, and audit
+records may remain necessary for accountability. Providers expose those items
+with a concrete reason and Core prevents them from being selected as executable
+actions. Policy may further restrict an action, but it must never silently
+loosen a provider's retention decision.
+
+All lifecycle mutations and exports produce tenant audit events. The request
+stores an evidence digest after every revision. This digest detects accidental
+or unauthorized mutation of the aggregate; it is not a digital signature or a
+substitute for signed recovery evidence.
+
+## Current Limits
+
+- Access is the first native provider. Other enabled modules appear in the
+  coverage list until they add a provider or an explicit no-subject-data
+  declaration is standardized.
+- Verification of the requester's identity and statutory deadline escalation
+  remain institutional workflows outside this API.
+- Global account or identity erasure is deliberately manual.
+- Exports are JSON. A human-readable signed response package remains a later
+  Reporting/Templates integration.