12 — GDPR & Compliance Operations (DSGVO)

Purpose

Operational playbook for handling personal data (Mandanten-Stammdaten, Fragebogen-Antworten, Original-Dokumente, AI-derived artifacts) across the Knoll Analyzer stack and the GRAG platform: what lives where, how long it lives, how to export it (Auskunft, Art. 15 DSGVO), how to delete it end-to-end (Löschung, Art. 17 DSGVO), which processors need an AVV (Art. 28), how German PII reaches LLM providers today, and which technical/organisational measures (TOMs) the platform provides vs. what Knoll must add. This is plan task 7.5 groundwork; the go/no-go gate before any real Mandanten data is plan 0.11.

Not legal advice. This document is an engineering/operations checklist. Retention periods, AVV wording, and the lawful-basis analysis must be confirmed by the Kanzlei's counsel/DSB. Where a statutory period is mentioned it is context, not a determination.

Status / verified against: 2026-07-06, repo document-processing-pipelines @ db63a95, live instance https://app.grag.ai. Cross-references: 01-architecture.md, 03-id-conventions.md, 04-provisioning-runbook.md, 05-verification-runbook.md, 10-document-pipeline.md, 13-platform-gaps-issues.md.

Roles in DSGVO terms (to be confirmed by counsel): the Kanzlei is Verantwortlicher for Mandanten data; Knoll Analyzer (the product/operator) acts as Auftragsverarbeiter; the GRAG host operator, LLM providers (via BYOK), and the e-mail provider are Unterauftragsverarbeiter and need to appear in the AVV chain (§4 below).

1. Data inventory — what lives where

Env placeholders used throughout: $GRAG_URL=https://app.grag.ai, $GRAG_API_KEY (Knoll runtime key), $GRAG_TENANT (knoll in prod, knoll-dev in dev).

Key takeaway: Knoll Postgres + Knoll file store are the masters; everything in GRAG is a derived projection except conversations (which are primary records of chat content) and the cost ledger (pseudonymous). The Löschung procedure must therefore fan out from grag_refs (plan 2.1), which maps every Knoll object to its GRAG ids.

2. Auskunft (Art. 15) — export procedure

Operationalisiert (2026-08-21): apps/web/scripts/gdpr-auskunft.ts (core: lib/gdpr/auskunft.ts) implements steps 1–4 + 7 below as one audited bundle — pnpm exec tsx scripts/gdpr-auskunft.ts "<Mandant>" writes db/*.json, the file-store originals, GRAG document inventories + conversation transcripts and a manifest, then logs data_export. Verified live on knoll-dev (bundle incl. GRAG inventories). The manual curl steps below remain the reference for anything the script does not cover.

Trigger: Mandant (via the Kanzlei) requests a copy of their data. Target: one export bundle per Mandant. All GRAG reads are ordinary tenant-scoped calls with the Knoll runtime key. Reference plan 7.5.

Step 1 — Knoll DB export. Export all rows keyed to the client_id: clients, contacts, analyses (+ milestones, contracts, analysis_team), questionnaire_answers, checklist_items, expert_reports, projects, calculation_line_items, leads, activities, ai_runs, files, grag_refs, relevant audit_log entries. A parameterised export script/server action belongs in the Knoll backend (Partner/Admin-only, itself audit-logged).

Step 2 — File-store originals. For each files row of the client: fetch the object (originals + generated expert-report/offer PDFs) into the bundle. GRAG holds no binaries, so this is the only source of the actual files (plan 2.4).

Step 3 — GRAG document inventory (per analysis-KB, ids from grag_refs):

curl -s "$GRAG_URL/workspaces/api/v1/kbs/$KB_ID/documents" \
  -H "Authorization: Bearer $GRAG_API_KEY" \
  -H "X-Tenant-ID: $GRAG_TENANT"

Include the returned metadata (name, mime, size, status, timestamps) as the processing record for that Analyse.

Step 4 — Conversations export (KB-chat 5.2, KIU chat 5.1b). List, then page messages ascending:

# list conversations of the Analyse-KB
curl -s "$GRAG_URL/workspaces/api/v1/conversations?kb_id=$KB_ID" \
  -H "Authorization: Bearer $GRAG_API_KEY" \
  -H "X-Tenant-ID: $GRAG_TENANT"

# full transcript per conversation (limit 1..1000, order=asc)
curl -s "$GRAG_URL/workspaces/api/v1/conversations/$CONV_ID/messages?order=asc&limit=1000" \
  -H "Authorization: Bearer $GRAG_API_KEY" \
  -H "X-Tenant-ID: $GRAG_TENANT"

Note: assistant messages carry sources/trace/groundedness JSONB — the sources include chunk text from the Mandant's documents; include them (they are the Mandant's data anyway).

Step 5 — KG view of the client (kg-service additionally requires X-Workspace-ID):

curl -s "$GRAG_URL/kg-service/api/v1/entities/client:$CLIENT_SLUG" \
  -H "Authorization: Bearer $GRAG_API_KEY" \
  -H "X-Tenant-ID: $GRAG_TENANT" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

curl -s "$GRAG_URL/kg-service/api/v1/entities/client:$CLIENT_SLUG/neighborhood?depth=2" \
  -H "Authorization: Bearer $GRAG_API_KEY" \
  -H "X-Tenant-ID: $GRAG_TENANT" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

(These are projections of Knoll DB facts — step 1 already covers the content; include for completeness of the processing record.)

Step 6 — (optional) per-analysis cost record, if the firm passes costs through: GET $GRAG_URL/ledger/api/v1/ledger/totals?pipeline_id=$ANALYSIS_RUN_ID (same auth headers; per-analysis attribution requires the X-Pipeline-Id stamping from plan 7.3).

Step 7 — Log it. Write a data_export event to audit_log (who, when, scope, delivery channel). Deliver via a secure channel (not plain e-mail attachment).

3. Löschung (Art. 17) — ordered deletion checklist

Operationalisiert (2026-08-21): apps/web/scripts/gdpr-loeschung.ts (core: lib/gdpr/loeschung.ts) plans and executes the checklist below — DRY-RUN by default, destructive only with --execute; every run writes deletion_started/deletion_completed audit entries incl. residuals. Live finding on knoll-dev (2026-08-21, filed as platform issue #406): with the purge flags ineffective the deletes are metadata-level only — the KB vanished, but its document row stayed indexed and voyager kept serving its chunks. The verification probes below (step 11) caught this — treat them as mandatory, and treat the flags precondition as hard.

Scope variants: single document, single Analyse, full Mandant offboarding (shown here — the superset; plan 3.2). Work strictly from the grag_refs inventory.

⚠ Preconditions (current-state caveats — blocking, plan 0.11 / 1.4 / 1.13):

• WORKSPACES_DOCUMENT_PURGE_ENABLED and LINEAGE_CLEANUP_ENABLED are unset → compose defaults false as deployed: document/KB DELETE is soft-delete only — voyager points, kg segments, and lineage rows remain (deleted docs are merely hidden by the chat live-document filter). Flipping both is plan 1.4 and blocking for real data. Verify live state first (plan 0.9).
• Backups: deleted data persists in backups until backup retention expires (PITR retention is 14 days once enabled, §6). State this in the Löschkonzept.
• Statutory retention (HGB/AO) may forbid deleting some Knoll DB records (Verträge, Rechnungsdaten): pseudonymize instead of delete where counsel says retention applies.

Checklist (execute in this order, record each step in audit_log):

1. Freeze Knoll-side. Mark the client Blocked (no new runs, no chat), snapshot the grag_refs rows for this client (they are your deletion worklist and later the deletion log).

2. Per-document DELETE with purge fan-out. For every document in every analysis-KB of the client (list via GET /workspaces/api/v1/kbs/{kb}/documents):

   curl -s -X DELETE "$GRAG_URL/workspaces/api/v1/documents/$DOC_ID" \
     -H "Authorization: Bearer $GRAG_API_KEY" \
     -H "X-Tenant-ID: $GRAG_TENANT"
   

   With the purge flag on, the workspaces-worker then (per docs/runbooks/document-purge.md): deletes the voyager points from the document_points registry → soft-deletes kg segments (DELETE /kg-service/api/v1/documents/{id}) → cascade-deletes the lineage subtree (DELETE /lineage/api/v1/artifact/{docfold_id}?cascade=true) → drops registry rows. Fail-closed: 5xx leaves the job in the consumer group and it replays; watch workspaces_document_purge_total{tenant,outcome} and the t:{tenant}:document_purge_audit stream. Documents ingested before the points registry existed need the backfill/re-ingest path from the purge runbook before purge can find their points.

3. KB delete per analysis. DELETE $GRAG_URL/workspaces/api/v1/kbs/$KB_ID (same headers) — triggers the voyager/kg/lineage purge fan-out for the collection when the flag is on.

4. Conversations. DELETE $GRAG_URL/workspaces/api/v1/conversations/$CONV_ID for each — soft-delete only (cascade_delete_supported=false; message rows incl. embedded chunk text remain in Postgres). For Art.-17 finality an operator-level SQL hard delete on conversations/conversation_messages is currently required — tracked as a platform gap in 13-platform-gaps-issues.md.

5. Lineage belt-and-braces. For any grag_refs artifact ids not covered by step 2's fan-out (e.g. directly ingested questionnaire markdown, expert-report PDFs):

   curl -s -X DELETE "$GRAG_URL/lineage/api/v1/artifact/$ARTIFACT_ID?cascade=true" \
     -H "Authorization: Bearer $GRAG_API_KEY" \
     -H "X-Tenant-ID: $GRAG_TENANT"
   

   This marks the forward subtree; the destructive fan-out additionally requires LINEAGE_CLEANUP_ENABLED=true (1.4). Hard delete of lineage rows is admin-only with confirm token (operator action).

6. KG tombstoning — there is NO delete route. kg-service exposes no entity delete and no edge delete. Tombstone instead (plan 3.5/3.6):

   curl -s -X POST "$GRAG_URL/kg-service/api/v1/entities/upsert" \
     -H "Authorization: Bearer $GRAG_API_KEY" \
     -H "X-Tenant-ID: $GRAG_TENANT" \
     -H "X-Workspace-ID: $WORKSPACE_ID" \
     -H "Content-Type: application/json" \
     -d '{"entities":[{"entity_id":"client:'$CLIENT_SLUG'","entity_type":"Client","label":"[deleted]","aliases":[],"description":"","properties":{"status":"inactive","deleted_at":"2026-07-06"}}]}'
   

   Overwrite label/description/aliases with neutral values (the upsert replaces them) and tombstone every client-specific entity (recommendations, projects of this client). Residual: AGE edges (SCORES, RECOMMENDS, …) persist with their properties (scores, analysis ids — pseudonymous but present); all consumers must filter status="inactive". Documented platform limitation → 13-platform-gaps-issues.md; a real fix needs the plan 1.11 write route to grow a delete/retract counterpart.

7. Workspace delete. DELETE $GRAG_URL/workspaces/api/v1/workspaces/$WORKSPACE_ID?cascade=true — executable with the Knoll runtime key (NOT admin-gated; in workspaces only tenant create/patch/delete are). If cascade deletion should be operator-only, enforce that as Knoll-side policy. Tenant soft-delete has NO composite purge — do not rely on it.

8. Knoll file store. Delete all objects for the client's files rows (originals + generated PDFs).

9. Knoll Postgres. Delete/pseudonymize the client's rows (respecting statutory retention, see preconditions). Keep audit_log and a minimal grag_refs tombstone as the deletion proof.

10. PII vault (only if the firewall was ever enabled for tenant knoll): DELETE $GRAG_URL/anonymization/api/v1/vault/$VAULT_ID per recorded vault id (audit-logged hard delete).

11. Verification probe (also in 05-verification-runbook.md; make it part of the 7.2 canary where feasible):

    # (a) semantic probe: a distinctive phrase from a deleted document must return 0 hits
    curl -s -X POST "$GRAG_URL/ai-gateway/api/v1/retrieval/collections/$KB_ID/search" \
      -H "Authorization: Bearer $GRAG_API_KEY" \
      -H "X-Tenant-ID: $GRAG_TENANT" \
      -H "Content-Type: application/json" \
      -d '{"query_text":"<distinctive phrase from the deleted doc>","top_k":5}'
    # expect: no hit whose payload doc_id is the deleted document (or 404 if the collection was deleted)
    
    # (b) point count: collection info after KB purge
    curl -s "$GRAG_URL/ai-gateway/api/v1/retrieval/collections/$KB_ID/info" \
      -H "Authorization: Bearer $GRAG_API_KEY" -H "X-Tenant-ID: $GRAG_TENANT"
    
    # (c) kg segment gone (expect 404)
    curl -s "$GRAG_URL/kg-service/api/v1/documents/$DOC_ID/segments/0/text" \
      -H "Authorization: Bearer $GRAG_API_KEY" -H "X-Tenant-ID: $GRAG_TENANT" \
      -H "X-Workspace-ID: $WORKSPACE_ID"
    
    # (d) inventory shows deleted
    curl -s "$GRAG_URL/workspaces/api/v1/documents/$DOC_ID?include_deleted=true" \
      -H "Authorization: Bearer $GRAG_API_KEY" -H "X-Tenant-ID: $GRAG_TENANT"
    

    Plus operator-side: document_purge_audit stream entries show ok=1 with points_deleted/kg_deleted/lineage_cascaded counts.

12. Deletion log. Write a summarising deletion_completed event to audit_log (scope, ids, probe results, residuals: Redis TTL windows ≤30 d, backup retention, AGE edges tombstoned-not-deleted, LLM provider side per §5).

4. Processors & AVV (Art. 28)

Also required: Verzeichnis von Verarbeitungstätigkeiten (Art. 30) covering the flows in §1, and a Löschkonzept referencing §3 including the residuals (Redis TTLs, backups, AGE edges, provider side).

5. The German-PII-to-LLM problem (plan 1.10 — decide before pilot)

Current state (verified): every LLM call (chat, Gutachten pipeline, extraction) sends unredacted German text to the configured provider. The platform's anonymization firewall is (a) OFF in prod (GATEWAY_FIREWALL_ENABLED=false, .env.production.example:60; guardrail also off, :92) and (b) English-only at the API boundary (language: Literal["en"] in anonymization/src/anonymization/api/schemas/requests.py:24; ADR 0003 defers German to v2), even though the underlying GLiNER2 PII model is multilingual (42 labels × 7 languages incl. German).

Options from plan 1.10:

Recommendation: for the pilot (plan 8.3, which uses one anonymized Mandanten-Dossier anyway): option (b) — EU endpoints via BYOK + DPA + documented accepted risk, signed off by the Kanzlei as Verantwortlicher. Target end state before scaling beyond the pilot: option (a), gated on a German redaction-quality check against the 7.1 corpus. Keep (c) as fallback only if (a) stalls. Record the decision in plan 0.11's go/no-go list.

6. Backups (plan 1.13 — blocking for real data)

Current state (verified): the deploy workflow starts neither the pg_dump backup profile nor pitr/pitr-vault (COMPOSE_PROFILES: retrieval only, deploy.yml:108), despite the compose comment "Prod deployments MUST enable this profile or wire an equivalent external backup". The host-maintenance.yml schedule comment references live base-backup windows (02:00 platform / 04:00 vault), so an operator may have brought PITR up manually — ⚠ verify with docker compose ps on the box (plan 0.9/0.11). Until confirmed, assume: no automated backup of Mandanten-bearing data.

Required end state:

7. TOMs checklist (Art. 32) — platform-provided vs Knoll-owned

8. Knoll-side audit trail (audit_log, plan 2.1)

Write append-only events (actor user id, role, timestamp, ip/user-agent, object type + id, action, outcome, optional diff-summary — never document content). Events worth writing:

Retention of audit_log itself: keep beyond client deletion as deletion proof (pseudonymize actor references only if required) — confirm period with counsel.

9. Open items feeding plan 0.11 (GDPR go/no-go)

1. plan 1.8 BFF auth fixed + 401 probe green (0.10a).
2. plan 1.4 purge flags (WORKSPACES_DOCUMENT_PURGE_ENABLED, LINEAGE_CLEANUP_ENABLED) verified on live; §3 step 11 probe passes on a fixture document.
3. plan 1.13 backups running + first restore test done (§6), incl. TODO-VERIFY on the live PITR state.
4. §4 AVV chain signed, incl. TODO-VERIFY host location.
5. §5 German-PII decision recorded and implemented (1.10).
6. Conversation hard-delete gap and KG edge-deletion gap accepted as documented residual risks or fixed platform-side (13-platform-gaps-issues.md).