Compliance Centre v1 Handover

1. Overview

The Compliance Centre backend has reached a production-ready state for v1. All core privacy and data-retention workflows are implemented, policy-driven, RLS-enforced, and fully async with receipts and ledger audit trails.

This handover defines the completion bar for v1, outstanding final checks, and the definition of done for future features that may introduce new data domains.

---

2. Current Routes

Path	Verb	Purpose
/api/v1/compliance/jobs	GET, POST	List or enqueue compliance jobs
/api/v1/compliance/forget	POST	Hybrid scrub (user anonymisation + evidence delete + redaction)
/api/v1/compliance/restrict	POST	Place/lift processing holds
/api/v1/compliance/dsar-export	POST	Data-subject export (zip + receipt)
/api/v1/compliance/privacy-pack	POST	Generate consolidated Privacy Pack
/api/v1/compliance/unlink	POST	Remove org-user bindings
/api/v1/compliance/ledger	GET	Query compliance ledger entries
/api/v1/compliance/retention/incidents	GET	List blocked/failed retention incidents

---

3. v1 Goals

1. Secure by default – RLS, capability-based access, sanitised outputs.
2. Async & auditable – All heavy work via jobs; receipts & ledger hashes prove action completion.
3. Policy-driven retention – Required table, no silent fallbacks, blocked/partial semantics.
4. Frontend-friendly contracts – Stable DTOs that avoid client-side joins.
5. Regression-proof – Integration coverage locks behaviour across tenants and caps.

---

4. Final v1 Completion Checklist

A. Integration Coverage

Ensure each route has integration tests covering:

• 401/403/200 auth gating (cap checks).
• Tenant isolation.
• Core happy-path assertions (status + key fields).

Specific endpoints to lock:

• POST /compliance/privacy-pack → artifact + manifest + event emitted. ✅ (integration: pack artifact + ledger event)
• POST /compliance/dsar-export → cooldown + force=true. ✅ (integration: 201 → 429 → 201)
• POST /compliance/forget → hybrid scrub + hold-blocked case. ✅ (happy + explicit hold-block)
• POST /compliance/restrict → place/lift + block verification. ✅ (hold set/cleared, job processed)
• POST /compliance/unlink → org-safe, orphan behaviour. ✅ (org isolation + orphan path + tenant isolation)
• GET /compliance/jobs → pagination, SLA fields. ✅ (SLA fields asserted on completed forget job)
• GET /compliance/ledger → tenant isolation + sanitisation.
• GET /compliance/retention/incidents → filters, order, sanitisation. ✅ (filters/order/sanitisation covered)

B. Stable DTO Contracts

Lock and document the response shape (for OpenAPI + BFF):

Job item DTO id, job_type, status, subject_id, requested_by, created_at, started_at, completed_at, duration_ms, artifact_refs, partial, blocked

Ledger entry DTO id, event_type, subject_id, domain, policy_id, cutoff, counts, artifact_hash, created_at

Retention incident DTO id, eventType, domain, policyId, cutoff, blockedReason, candidate_count, createdAt

Privacy Pack manifest List of included artifacts (DSAR export, receipts, policies) with hashes and timestamps.

C. Ledger Semantics

Confirm:

• Ledger rows represent completed outcomes, or
• Include an explicit state (REQUESTED | COMPLETED | FAILED | BLOCKED) so enqueue events aren’t mistaken for completion.
• Idempotency enforced via (tenant_id, event_type, subject_id, job_id) uniqueness.

D. Abuse Controls

• DSAR export cooldown (15 min) + force=true override.
• Retention incidents throttling (3 req / 2 s).
• Sanitisation guards in ledger/incidents/pack manifest (no raw error or payload fields).

E. Documentation Alignment

Update docs/product/compliance-centre.md to include:

• Data domains currently covered (user/evidence/telemetry + submission free-text).
• Holds behaviour (blocked event + job completes, no retry churn).
• Meaning of receipts and hashes.

---

5. Immediate Next Task

Freeze v1 contracts + hand off to consumers

• Align OpenAPI/BFF with the stable DTOs above.
• Keep the incidents + jobs surfaces as the single “ops view” until a UI exists.
• If a frontend consumer is added, build against the frozen DTOs and don’t widen payloads without bumping docs.

---

6. Definition of Done for Future features

For every new table or module that may contain PII:

Checklist Item	Description
PII classification	Declare data type (Identity / Knowledge / Observation / Evidence / Telemetry).
DSAR inclusion	Decide if included in exports (and why).
Retention mapping	Assign or defer to a retention domain.
Sanitisation rules	Identify which fields require redaction before export or logging.

No new data-bearing module is considered complete until this checklist is satisfied.

---

7. Summary

Once the Privacy Pack integration test is added and DTO contracts are frozen, the Compliance Centre backend v1 is feature-complete and ready for frontend consumption. Subsequent work should follow Backend-for-Frontend principles: expose minimal, pre-shaped DTOs to the UI and keep compliance logic strictly backend-driven.