# Data access and the personal-data read ledger

Who may read which data, and the record that they did. Two things live here: **data access**
(who is allowed to read a restricted slice of a dataset) and the **read ledger** (one audit row for
every read of personal data). Both are enforced by the server; the dashboard only shows them.

## Data classes

| Class | What it is | Default | Needs `pii:read` |
| --- | --- | --- | --- |
| `person_level` | Who did what: subjects, their events, the identity ledger | **restricted** | yes |
| `replay` | Recorded sessions of a person | **restricted** | yes |
| `survey_response` | An answer someone gave, with the identity they gave | **restricted** | yes |
| `aggregate` | Counts and rates over a cohort at or above the project's floor | unrestricted | no |
| `telemetry` | Spans, logs, metrics and error events: about the software | unrestricted | no |

The defaults are the decision taken in code (OD-DP-07): person-level product data is restricted
until an organization says who may read it. An organization changes the **mode** of a class; it
cannot add a class or change what a class is.

## Who may read a person

Reading a person is a person's act. A call is refused **before the organization's policy is read**
when the caller is an agent, a service, an OAuth client (even for the person who authorized it), a
delegated call, or an organization CI token. A person whose token lacks the human-only `pii:read`
scope is refused with that scope named. After that, in order: the caller must be able to read the
project, the project's product analytics must be enabled (the PA-01 gate, answered `422
analytics_not_enabled` otherwise), and the organization's policy must admit them.

There is no MCP tool for person-level data. An agent that needs it asks the person to read it in
the dashboard.

## Modes and scopes

A **scope** names a slice of one class, by one attribute, and the people who may read it:

| Attribute | Example |
| --- | --- |
| `project` | `project = *` (every project) |
| `environment` | `environment = production` |
| `service.name` | `service.name = payments` (telemetry only) |
| `event_property:<name>` | `event_property:plan = enterprise` |
| `host_tag:<name>` | `host_tag:tier = db` (telemetry only) |

`*` as a value means every value of that attribute. A scope's people are users, teams of this
organization or organization roles. **Rows inside a scope's slice are readable only by its
people**, in whatever mode the class is. **Rows outside every scope** follow the class's mode:
`unrestricted` lets anyone who holds the right permission read them; `restricted` lets nobody until
a scope admits them. Two scopes that contain the same row are an OR.

An agent is judged as the person it acts for, so it can never read a slice that person cannot. An
agent with no person behind it is on nobody's list, even though it holds an organization role of
its own: a scope naming `role: MEMBER` admits the members who are people, and a scope's `user`
entries can name only people.

A restricted dataset that is not about a person (telemetry by `service.name`, aggregates by an
event property) is checked with `assertScopeAdmits`. For aggregates, which are product analytics,
it also takes the project, which must belong to the organization, and refuses with
`analytics_not_enabled` until that project's analytics gate is open.

A scope is versioned. Every change adds a version holding the state it produced, and
`restoreVersion` writes an exact earlier state back as a **new** version; history is never
rewritten. `expectedVersion` makes a write a compare-and-set (409 `stale_version`).

## Changing it

Creating or changing a scope, and setting a class's mode, are **human-only** acts (`org:admin`,
so an organization **owner**): a person's own signed-in session, not a token, an agent or an OAuth
client. Each writes an audit row with `before` and `after`, in the same transaction as the change,
and tells the owners afterwards.

| Route | Does | Who |
| --- | --- | --- |
| `GET /orgs/:o/data-access?project=` | What you may read of each class, in which tier, and the cohort floor | any member |
| `GET /orgs/:o/data-scopes` | Every scope | owner |
| `POST /orgs/:o/data-scopes` | Create a scope (`data_scope.create`) | owner, in a session |
| `GET /orgs/:o/data-scopes/:id` | One scope and its versions | owner |
| `PATCH /orgs/:o/data-scopes/:id` | Change principals, archive, or `restoreVersion` (`data_scope.update`) | owner, in a session |
| `GET /orgs/:o/data-access-defaults` | The mode of each class | owner |
| `PUT /orgs/:o/data-access-defaults` | Set one or more modes (`data_access_default.update`) | owner, in a session |

`data_access_get` (MCP, read, `project:read`) answers the same question as the first route for an
agent: the mode of each class, the tier it will be served (`stored`, `sampled_agent`, `aggregate`
or `refused`), the scopes that bind it, and the project's cohort floor. Scopes that carve a slice
out for **other** people are counted, never described. A scope's attribute text is untrusted data.

## The read ledger

Every read that returns personal data writes one audit row, `data.read`, **after** the read, and
**the read fails if the row cannot be written**: data that was taken but not recorded is not
handed over.

A row holds the surface (`dashboard`, `api`, `mcp`, `worker`, `cli`), the tool or route, the data
class, the tier the data was held in, the **categories** of personal data that came back with
their counts (`email`, `phone`, `ip_address`, `name`, `user_id`, `device_id`, `location`,
`payment_card`, `government_id`, `credential`, `free_text`, `other`), how many rows, the approval
it ran under when one applied, where it went next (`client` or `model_provider`), and the **digest**
of the query. It never holds a value, an identifier or the query text. The actor fields are the
same as every other audit row: who, in which mode, through which transport and credential, for
which client.

**Volume.** A read of the stored tier, or one that returned any category, is one row per call.
A read that returned only aggregates and no category is one row per principal, session and hour,
flushed every 60 seconds and on shutdown. It is never sampled.

`audit_read_counts` (how much each MCP principal read, by hour) also carries the categories.

## For a developer adding a person-level read

```ts
const { orgId, admission } = await assertPersonLevelRead(principal, 'person_level', { projectId })
return ledgeredRead(ctx, { orgId, projectId, dataClass: 'person_level', surface: 'api',
  route: 'GET /…', tier: 'stored', egress: 'client', query }, async () => {
    const rows = await read(admission)           // filter by admission.admitsRow / slices
    const { value, manifest } = scrubValue(rows, { tier: 'agent' })
    return { value, manifest, rowCount: rows.length }
  })
```

`api/test/data-access/ledger-coverage.test.ts` fails for a file that calls these and has no driver
there, so a reader cannot land without its row being checked.
