# Switching and data export

How to leave Bucker and take your data: the published statement, the export plan, the export itself
(`org_data.export`), and the download. This page is the reference for `/switching` on the website,
`GET /orgs/{org}/org-exports/*`, `data_retention_get` with `include: ["export_plan"]`, and the
"Switching" card under Settings, Compliance.

The statement is a **draft until counsel ratifies it (H-50)**. Nothing here is a legal claim until then.

## The statement

| | |
| --- | --- |
| Charges | None. Exporting, downloading and switching away are free. |
| Notice | None to export. 30 days to end the contract (the Data Act's ceiling is two months). |
| Retrieval | The data stays available 30 days after switching. A finished export bundle stays downloadable 14 days, then is deleted. |
| Formats | `bucker.yml`; JSON Lines; OTLP/JSON for spans and log records. |
| Not yet | Delivery to your own bucket (a WH-08 sink) and Parquet. |
| Data Act | Art. 23, 25, 26, 29 and 30. |

## The plan

`GET /orgs/{org}/org-exports/plan` (needs `governance:read`), or `GET .../retention/windows?include=export_plan`,
or the MCP tool `data_retention_get` with `include: ["export_plan"]` (+900 tokens), lists per stream:

- `rows`, **counted** over this organization's projects and its own audit log;
- `estimatedBytes` and `expectedSeconds`, **estimates** (the plan says so);
- `format` and the file names;
- `retention.cutoff`: rows older than this no longer exist and are not exported;
- the exports in flight with their progress.

The MCP block is compact and carries only Bucker's own strings. A project-pinned connection and a member
who cannot read the organization are refused it, because it counts every project's rows.

## The streams

| Stream | File | Format |
| --- | --- | --- |
| `configuration` | `bucker.yml` | YAML, what `GET /orgs/{org}/config` serves |
| `issues` | `issues-<nnnnn>.jsonl` | JSON Lines |
| `events` | `events-<nnnnn>.jsonl` | JSON Lines |
| `spans` | `spans-<nnnnn>.jsonl` | JSON Lines |
| `spans_otlp` | `spans.otlp-<nnnnn>.jsonl` | OTLP/JSON `ExportTraceServiceRequest`, one per line |
| `log_records` | `logs-<nnnnn>.jsonl` | JSON Lines |
| `log_records_otlp` | `logs.otlp-<nnnnn>.jsonl` | OTLP/JSON `ExportLogsServiceRequest`, one per line |
| `metric_points` | `metrics-<nnnnn>.jsonl` | JSON Lines (not OTLP: bucket layouts do not round-trip) |
| `audit_logs` | `audit-<nnnnn>.jsonl` | JSON Lines |
| `replay_transcripts` | `replay-transcripts-<nnnnn>.jsonl` | JSON Lines |

Not exported: session replay **recordings** (sealed to a per-session key; their transcripts are exported),
credentials and token hashes, and any other organization's data. Rows are exactly as Postgres renders them.

## Starting an export

`org_data.export` is a **human-only, CRITICAL, irreversible, dual-controlled act**. An agent, an OAuth
client and a service principal are refused by name; only a person on their own session holding
`org:admin` may file it, through `POST /orgs/{org}/operations/human-requester/org_data.export`
with `{ "input": { "reason": "...", "streams": [...]?, "resumeFrom": "<exportId>"? } }`.

1. The request is filed and the requester's step-up is asked for.
2. The request waits a **24-hour hold** (every owner is told when it starts and an hour before it ends, and
   any eligible person may reject it), and **two approvers outside the requester's chain** vote. An
   organization with fewer eligible people needs only those it has; a single-owner organization has the hold
   alone. The hold applies either way: it is the human-requester path's, not a substitute for the quorum.
3. The requester confirms with a fresh step-up; when the hold has ended the operations sweeper applies the act.
4. Only the apply creates the `OrgExport` row (`queued`). Before it, nothing exists for the worker to start.

One export may be queued or running per organization. A bucket destination is refused (`destination` accepts
only `download`).

## The bundle

`bucker-workers` writes the bundle under `exports/<orgId>/<exportId>/`, a file at a time (at most 20,000 rows or
8 MiB), and **`manifest.json` last**. The manifest lists, per stream, every file with its rows, bytes and SHA-256,
the snapshot edge (`asOf`: rows received later are not in it) and the frozen project list.

- **Resumable.** Each file is written before the row's running manifest names it, and the manifest keeps the
  keyset cursor after every file. A worker that dies is taken over after 10 minutes and continues from the last
  file; five failed attempts fail the export and keep its files.
- **Cancel** (`POST .../org-exports/{id}/cancel`, human-only, `org:admin`, no approval: stopping egress is never
  the dangerous direction) stops it and keeps the files. **Continuing** is a new `org_data.export` naming the
  stopped one in `resumeFrom`: a new egress needs a new approval. The carried files are re-read and checked
  against their digests, the snapshot edge is the original's, and the stream continues from the last good file.
- A finished bundle is deleted 14 days after it completes; organization deletion deletes every export by prefix.

## Downloading

`POST .../org-exports/{id}/download-links` mints one signed link per file and one for `manifest.json`, valid 15
minutes and **bound to you, the export and the file**. `GET .../files/{file}?token=...` (organization admin, and
the token) re-reads the file and checks it against the manifest's SHA-256 before a byte is served; a file that
differs is a 500, never a download of other bytes. The response carries `x-bucker-sha256`. Agents and OAuth
clients never get links.

## Audit

`org_data_export.queued`, `.started`, `.completed`, `.failed`, `.cancelled`, `.expired`, `.download_links` and
`.downloaded`, under the organization that asked, target type `org_export`; the act itself is the engine's
`operation.applied`.
