# Personalization Vector Privacy Controls

**Document Version**: 1.0  
**Last Updated**: 2025-10-03  
**Owners**: Identity Engineering & Privacy Office

This document outlines how the Auth service manages personalization vectors,
privacy budgets, and retention lifecycles.

## Vector Storage

- Supported vector types: `content_preferences`, `interaction_patterns`,
  `private_preferences`, `temporary_interaction`, `audit_test`.
- Privacy levels align with budget cost tiers:
  - `minimal` (cost 5, retention 30 days, high anonymization)
  - `aggregated` (cost 10, retention 90 days, partial anonymization)
  - `detailed` (cost 25, retention 180 days, no anonymization)
- Vector payloads are restricted to ≤512 dimensions and metadata is PII scrubbed
  by schema policy.

## Privacy Budgets

- Default budget: 100 units per rolling 30-day period per user.
- Each operation records consumption history with operation name, timestamp, and
  metadata.
- Exceeding budget returns `personalization.privacy_budget_exceeded` with
  remaining amount and next reset.
- Budgets auto-reset at period boundaries and can be reset manually by
  administrators via `/v1/users/:id/personalization/privacy-budget/reset`.

## Retention & Cleanup

- Default retention is derived from privacy level; vectors store an explicit
  `expires_at` timestamp.
- Expired vectors are removed via `/v1/personalization/cleanup/expired`
  (supports dry-run and force modes).
- Users can request targeted cleanup using
  `/v1/users/:id/personalization/cleanup`, which also reclaims consumed budget.

## Audit Logging

- All personalization operations append to
  `/v1/users/:id/personalization/audit-logs` with privacy impact metadata.
- Logs cap at the 500 most recent entries to balance observability and storage.

## API Overview

| Endpoint                                                     | Description                                               |
| ------------------------------------------------------------ | --------------------------------------------------------- |
| `POST /v1/users/:id/personalization/vectors`                 | Create vector with privacy-level aware budget consumption |
| `GET /v1/users/:id/personalization/vectors`                  | List active vectors for user (owner/admin only)           |
| `PUT /v1/users/:id/personalization/vectors/:vectorId`        | Update vector dimensions/metadata                         |
| `DELETE /v1/users/:id/personalization/vectors/:vectorId`     | Soft-delete vector and reclaim budget                     |
| `GET /v1/users/:id/personalization/privacy-budget`           | Current budget snapshot                                   |
| `POST /v1/users/:id/personalization/privacy-budget/consume`  | Custom budget consumption logging                         |
| `POST /v1/users/:id/personalization/privacy-budget/reset`    | Manual reset for support workflows                        |
| `GET /v1/users/:id/personalization/privacy-budget/analytics` | Returns breakdown and trend metrics                       |
| `POST /v1/personalization/cleanup/expired`                   | Global retention cleanup                                  |

Refer to `tests/auth.personalization-vectors.spec.ts` for full compliance
coverage.
