# Design — add-export-download-handler

## Goal

Close the deferred `GET /:id/download` endpoint without expanding scope into §4 streaming /
S3 / signed-URL work. The handler reads the persisted job, re-runs the registered
`DataProvider`, re-renders through the existing writer, and streams the result back. Errors
flow through a per-package RFC 7807 problem-details renderer so consumers branch on the
existing `EXPORT.*` codes.

## File layout

```
packages/api/api-plugin-export/src/
  error-codes/
    error-codes.ts                   ← add JOB_NOT_READY
  otel/
    instruments.ts                   ← add downloadServed / downloadFailed
  routes/
    download/
      download.ts                    ← runDownloadExport(deps, jobId)
      download.md
      download.test.ts
    exports/
      exports.ts                     ← extend deps + mount /:id/download
    problem-json/
      problem-json.ts                ← RFC 7807 renderer (per-package)
      problem-json.md
      problem-json.test.ts
  plugin/
    plugin.ts                        ← thread exportJobStore through to routes
```

## Discriminated outcome

`runDownloadExport(...)` returns a union so the route registration call site stays free of
`c.json(...)` typing. The four failure variants each carry the data the renderer needs:

```ts
type DownloadOutcome =
  | { kind: "ok"; body: string; contentType: string; filename: string; format: ExportFormat }
  | { kind: "not-found"; id: string }
  | { kind: "not-ready"; id: string; status: ExportStatus }
  | { kind: "provider-not-found"; resource: string }
  | { kind: "failed"; reason: string; cause: unknown };
```

Every branch throws / instantiates an `ExportError` so the spec-conformance pin keeps every
`EXPORT_*` code reachable from a production path.

## `jobStore` injection vs the in-memory `jobs` Map

`ExportRoutesDeps.jobStore?` is added as an optional dependency. When absent, the download
handler builds an inline `ExportJobStore` adapter over `deps.jobs` so the route works in
lightweight tests and host apps that opt out of SurrealDB. When present, the handler routes
all reads through the store — consistent with the persistence narrative in
`2026-05-19-wire-surreal-export-store`.

## OTel labels

- `export.download.served{format}` — labelled with `format: csv | json | xlsx`.
- `export.download.failed{reason}` — labelled with `reason: not-found | not-ready | provider-not-found | failed`.

Tests assert via `flushTestMetrics()` against the existing in-memory `MeterProvider` in
`tests/setup/polyfills.ts`.

## Status-code mapping

| Outcome | HTTP | Code |
|---|---|---|
| `ok` | 200 | n/a |
| `not-found` | 404 | `EXPORT.JOB_NOT_FOUND` |
| `not-ready` | 409 | `EXPORT.JOB_NOT_READY` |
| `provider-not-found` | 404 | `EXPORT.PROVIDER_NOT_FOUND` |
| `failed` | 502 | `EXPORT.PROVIDER_FETCH_FAILED` |

The mapping lives in the per-package `problem-json` renderer via `context.statusCode`
attached at throw time.