HablaYa Data Retention Schedule

Version: 1.1 Effective date: 20 May 2026 Last updated: 22 May 2026

This document is the single source of truth for retention periods across backend, legal documents, and operations. Periods here must match the actual technical implementation (TTL, cron jobs, cascade delete). In case of mismatch, the actual implementation prevails — discrepancies are recorded as bugs and resolved within one sprint.

Legal precedence: This English version is authoritative. In case of conflict between language versions, this English text prevails.

1. Purpose and principles

Core retention principles in HablaYa:

1. Storage minimization (GDPR Art. 5(1)(c)) — store data only as long as needed for a specific purpose, and no longer.
2. Defined storage limitation (GDPR Art. 5(1)(e)) — each data category has a concrete, finite retention period. "Indefinite" is allowed only where deletion is technically impossible (e.g., hash values in audit logs), with separate justification.
3. Right to erasure (GDPR Art. 17) — account deletion triggers a cascade procedure of deletion/PII scrubbing across all related tables and file storage.
4. Technical enforcement mechanism is mandatory — every retention period must be implemented: scheduled job, TTL, on-delete cascade. "Done manually" is not accepted.
5. Deletion audit — we record the fact of deletion (what and when), without retaining the content of deleted data.

2. Full retention table

3. Configuration env-variables

All retention periods are configurable via env-variables on the VPS (/home/hablaya/app/.env.production). This allows adapting periods without code changes and applying regional overrides if needed.

# Retention in days
RETENTION_PROVIDER_AUDIO_DAYS=30
RETENTION_PROVIDER_CALL_LOG_DAYS=90
RETENTION_SESSION_TURN_DAYS=365
RETENTION_HELP_REQUEST_DAYS=90
RETENTION_USAGE_LEDGER_DAYS=730
RETENTION_SECURITY_LOGS_DAYS=180
RETENTION_TTS_CACHE_DAYS=90
RETENTION_RETENTION_AUDIT_LOG_DAYS=1095
RETENTION_DSAR_LOG_DAYS=1095
RETENTION_DELETE_ACCOUNT_GRACE_DAYS=30

# Future
RETENTION_BILLING_EVENTS_DAYS=2190

Principle: shortening periods is allowed without approval and applied immediately. Extending periods requires Privacy Policy revision and user notification (see Privacy Policy §12).

4. Cascade on account deletion

When a user requests account deletion (via Mini App → Settings → Privacy → "Delete account and data" or via DELETE /api/v1/profile/account), the following sequence applies:

1. Request confirmation (typed confirmation in UI).
2. Grace period: account marked pending_deletion for 30 days. During grace, user can cancel deletion (sign in with same Telegram ID). After expiry — proceed to step 3.
3. PG cascade deletion:
   • DELETE FROM saved_words, language_profiles, help_requests, session_turns, normalized_messages, sessions WHERE user_id = X.
   • UPDATE provider_call_log SET request_payload = NULL, response_payload = NULL WHERE user_id = X — scrub PII, retain metadata.
   • UPDATE provider_audio_store SET audio_evicted = TRUE, audio_path = NULL WHERE user_id = X.
4. Filesystem:
   • Unlink audio files in PROVIDER_AUDIO_STORE_PATH (via BackgroundTasks, idempotent).
   • Unlink files in TTS_STORAGE_PATH linked to the deleted user.
5. Retained:
   • users.id (as an anonymous "tombstone" for FK integrity);
   • subscriptions, usage_ledger — for financial and tax reporting (see rows 7, 10);
   • dsar_log entry on the fact of deletion (no PII).
6. Audit: retention_audit_log entry (user_id, action='account_purge', timestamp, counts of affected rows).
7. Notification: email to the address tied to the request (if provided), confirming completion.

Procedure SLA: no more than 30 days from grace expiry to step 6 completion.

5. Retention enforcement mechanisms

6. Deletion audit

All mass deletions and scrub operations are recorded in a new retention_audit_log table:

CREATE TABLE retention_audit_log (
    id BIGSERIAL PRIMARY KEY,
    executed_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    operation TEXT NOT NULL,
    category TEXT NOT NULL,
    rows_affected INTEGER NOT NULL,
    files_affected INTEGER NOT NULL DEFAULT 0,
    user_id BIGINT,
    extra JSONB,
    duration_ms INTEGER
);

CREATE INDEX idx_retention_audit_executed_at ON retention_audit_log (executed_at DESC);
CREATE INDEX idx_retention_audit_user_id ON retention_audit_log (user_id) WHERE user_id IS NOT NULL;

Important: this table records the fact of deletion (what and when), but not the content of deleted data. This allows:

• proving compliance during audit/user DSAR;
• tracking that cron is working (rows_affected > 0 in a real DB with traffic);
• investigating anomalies (e.g., sudden mass deletion of a million rows).

The audit table itself is subject to retention: see row 12 (3 years).

7. Incident hold

In case of a significant incident (security breach, legal request, investigation), an administrator may suspend retention for a specific user or time range:

• retention_hold = TRUE flag on users or specific rows;
• Mandatory hold review date (retention_hold_review_at TIMESTAMPTZ NOT NULL) — no more than 90 days; extension requires explicit action and is logged.
• retention_sweeper skips rows under hold.

Currently, incident hold is a prepared mechanism that will be activated upon the first real incident. The code contains a stub/no-op for now.

8. Regional overrides

The current version (1.0) applies a single retention policy to all users regardless of region. Regional overrides (e.g., shorter periods for residents of Germany or longer for US billing) are not implemented.

If a regional regime is required in the future (e.g., upon AEPD request after the first real EU DSAR), it will be implemented via:

• column users.retention_profile ('eu_default' | 'us_default' | 'strict_min');
• override logic in retention_sweeper prioritizing the stricter period.

9. Open questions

Topics that may require revision as the service grows or new requirements emerge:

1. Anonymization vs hard delete for category 3 (dialog history): currently hard delete planned after 12 months. Alternative — anonymization (strip user_id, retain texts for training datasets). Decision deferred until training data is actually needed.
2. Period for voice (category 4): 30 days — OpenAI standard. For strict GDPR-minimum, 7–14 days was considered. 30 days was chosen as a balance between incident investigation and minimization.
3. Regional overrides — see §8.
4. Tombstone vs full delete for users.id: currently retained as tombstone. Under strict GDPR Art. 17 interpretation, even tombstone should be deleted — this would require FK schema redesign.
5. Periods for DSAR log (category 13): 3 years — our choice for statistics and compliance evidence. AEPD practice minimum — 1 year.

These questions are recorded here so that during the next audit it is clear which trade-offs were made consciously.

10. Relation to other documents

• PRIVACY_POLICY.md — user-facing version of retention (§5 in Privacy);
• TOS.md — retention mention in termination context (§11);
• CONSENT_COPY.md — UI copies for users in Mini App;
• docs/runbooks/retention.md — operations runbook (to be created in plan Session 2);
• docs/open-questions/2026-05-04_provider-audit-gdpr-retention.md — original open question that this document closes.

11. Change history

Author: Claude | Model: Claude Opus 4.7 (1M context) | Mode: implementation (Paddle migration Phase 6 prep — legal-docs fix after quality review) | Reasoning: not reported by system | Timestamp: 23 May 2026, 00:00 (Europe/Madrid) [2026-05-23T00:00:53+0200]