# Subject requests: access and erasure for end users

How an organization answers a request from one of its own customers' customers: "what do you hold about me" (GDPR
Art. 15 and 20) or "delete me" (Art. 17). One request drives every store, with a preview, a cancel window, a deadline
and a signed receipt that names no one. This page is about **end users inside your telemetry**. The data of a person
who has a Bucker *account* is a different request (`/compliance/dsr/export` and `/compliance/dsr/erasure`).

## The life of a request

| State | What it means |
| --- | --- |
| `DRAFT` | Filed with its reach report. The identifiers are sealed in the draft and nowhere else. |
| `PENDING_WINDOW` | A person executed the erasure. The cancel window is open (72 hours unless you chose 0 to 168). |
| `EXECUTING` | The window closed and the adapters are running, store by store. |
| `VERIFIED` | Every store was read again and held nothing for the person. The signed receipt exists. |
| `CANCELLED` | A person cancelled a draft, or an erasure inside its window. Nothing was executed. |
| `COMPLETED` | (Access requests.) The export is built and downloadable. |

Every request carries its **Art. 12(3) deadline**: one month from receipt, clamped to the last day of a shorter
month. Receipt is the moment the draft was filed unless the draft says `receivedAt` earlier. A request within seven
days of its deadline is `dueSoon` in the list.

## Who may do what

| Act | Who | Notes |
| --- | --- | --- |
| File a draft, run a dry run, list | Anyone holding `dsr:prepare`, **including an agent** | Changes no data. At most 20 unsubmitted drafts per organization; an agent files at most 10 a day. |
| Execute an erasure (`subject.erase`) | A person on their own session, `org:admin` | Step-up. Above 10,000 rows: dual control. |
| Execute an access request (`subject.export`) | A person on their own session, `org:admin` | Builds the bundle and returns a signed link. |
| Cancel (`subject_request.cancel`) | A person on their own session, `org:admin` | A draft, or an erasure inside its window. |
| Read the receipt, download the export | A person on their own session, `org:admin` | The link is bound to the person it was minted for. |

An agent, a service principal, an OAuth client and a delegated credential are refused on every human act before
anything is read. There is no MCP tool for them.

### Dual control above 10,000 rows

At or below 10,000 rows the person acts at once with a step-up, and the cancel window is the second look. Above it,
the request goes through the human-requester path: the requester votes with a step-up, two approvers outside the
requester's chain approve (or, in an organization with fewer eligible people, the quorum is lowered to the people who
exist), any human may reject during the 24-hour hold, and the requester confirms with a fresh step-up. Erasure is a
legal duty, so the shipped policy row is **ASK with two approvers**, never the registry's DENY default.

The person names the selection fingerprint and total they were shown. A different **selection** (the subject, or the
projects covered, such as a project added since the draft) **fails closed with 409**, at execution and again at the
apply after any hold; that needs a new draft. A different **total** for the same selection (the person kept using the
product) is a 409 at execution that carries the current total (`currentRows`) to acknowledge, and is not re-checked at
the apply: the purge erases whatever the selection holds when the window closes, so binding the count across a day's
hold would make an active person impossible to erase without making any erasure narrower. The receipt records what
was actually removed.

## What a request reaches

The dry run and the draft list every store. A store is either **reached** (an adapter with `reach`, `execute`,
`verify` and `export`) or **listed and not reached** with a reason from a closed list. The stores today:

| Store | Reached | Removal |
| --- | --- | --- |
| Session replays and transcripts | yes | Recording deleted before its row; both gone when the purge returns |
| Events, release sessions, spans, logs, the query log, other free-text rows | yes | Rows deleted at once; a partition is dropped later by retention (housekeeping, not the removal) |
| Metric series and points | yes | Series tombstoned, points deleted; another machine may write against it for up to a day |
| Feedback reports | yes | Deleted at once, by contact address |
| Cold archives and cold-tier objects | yes | Archive rewritten in place; cold object rewritten under a new key, the old shredded |
| Per-subject rollups and revenue rows | yes | Deleted at once |
| Sessions | yes | Row deleted at once; its partition is dropped by the session sweep |
| Subjects, links, device keys, property history, identity records | yes | One transaction |
| Status-page email subscribers | yes | Subscription removed |
| Warehouse sink objects | **no** | Listed `external_processor`: a row exported before the erasure stays in the sink's files until the sink is deleted |

A subject is matched by the keyed pseudonym of every identifier in every pseudonym generation the project has opened
(and the frozen v1), by the scoped hash events carry, and by the literal address, IP and identifiers in the stores
that scan text. A pseudonym generation opened under a previous secret cannot be computed and is named in the report.

### What hiding is today

Executing an erasure **holds** the matched rows: a hold is recorded for each project the request reaches
(`erasure_ledger`, readable through `heldProjectIds`), and a store that can hide its own rows implements `hide`.
No store has a per-row hide column yet, so **the rows stay readable until the purge** and the purge, not the hold, is
what removes them. This is stated in the report instead of implied.

## The receipt

A verified erasure writes a `subject_erasure` receipt, signed (DSSE over an in-toto statement, extension kind
`subject_erasure`) and appended to the organization's receipt log inside the transaction that marks the request
verified. Per store it says: rows reached, whether the verification pass found nothing left, when removal completed or
when it is expected, and why a store was not reached. It carries **no identifier**: the evidence schema is closed, the
selection is named by a keyed digest, and the receipt is scanned for every identifier before it is stored. Verify it
offline with `bucker-verify verify-log`.

## The access export

The bundle holds every store's rows for the subject, the stores that could not be read and why, and the **recipients**:
everyone in the organization who read person-level data, replay or survey responses in the covered projects, by
surface, count and first and last time (from the read ledger). The ledger records reads of a class, not of one
person, so this is an upper bound and says so.

The bundle is encrypted in the object store (per-organization key, bound to the request). The download is a signed
15-minute link bound to the organization, the request and the person it was minted for.

## REST

| Route | |
| --- | --- |
| `POST /orgs/:o/subject-requests` | File a draft. Body: `kind` (`ACCESS` or `ERASURE_END_USER`), `identifiers`, optional `projectSlug`, `receivedAt`. |
| `GET /orgs/:o/subject-requests` | List: states, deadlines, receipt summaries. No identifier. |
| `GET /orgs/:o/subject-requests/:id` | One request and its reach report. |
| `POST /orgs/:o/subject-requests/:id/execute` | The human act. Erasure: `reason`, `acknowledgeSelection`, `acknowledgeRows`, optional `windowHours`, `stepUp`. 202 while it waits. |
| `POST /orgs/:o/subject-requests/:id/cancel` | Cancel inside the window. |
| `GET /orgs/:o/subject-requests/:id/receipt` | The receipt. |
| `GET /orgs/:o/subject-requests/:id/export` | A signed link; with `?token=`, the bundle. |

## MCP

| Tool | |
| --- | --- |
| `erasure_dry_run` | Counts per store and the selection fingerprint. Writes a `data.read` ledger row. |
| `subject_request_draft_create` | Files a draft (governed: ELEVATED, ALLOW). A person executes it. |
| `subject_requests_list` | States, deadlines and receipt summaries. |

All three need `dsr:prepare` and are held until the OAuth security review closes (SG-059).

## Adding a store

A package that stores an end user's identifier exports a `SubjectStoreRuntime` from
`domain/src/modules/compliance/adapters/<store>.ts` and joins with `registerSubjectStore(...)` in its wiring line; a
store that cannot be reached declares `unreachable` with a reason and the sink or processor's retention. The registry
test fails a dataset that names neither.
