# Eve media

Eve stores media metadata, source aliases and import manifests in the
environment's Payload PostgreSQL database. Original bytes live in the private
Hetzner bucket `app-dev-server`, under `eve/content/<environment>/media/`.
Payload, Lexical and the AWS SDK are open source; this path requires no paid CMS
module.

Each SHA-256-addressed original has an `objects/` copy and a `recovery/` copy.
Uploads use conditional writes and read back both bodies before committing their
metadata. A failed database transaction can leave an immutable orphan; retrying
verifies the same objects and safely records the result. These two prefixes are
in the same bucket. PostgreSQL history and aliases use the existing pgBackRest
backup and continuous WAL archive.

The human workspace has a searchable media library, raster/audio previews,
original downloads, and an attachment picker in the rich-text editor. SVG, PDF
and other active file formats download as attachments with sandbox/nosniff
headers. Editable diagram files retain their original bytes. Mermaid documents
also have the existing source editor and strict preview.

## Worker API and MCP

Use the same scoped Eve worker credential as the task/document API. Readers need
`content:read`; uploads additionally need `content:write`. Send the bearer token
in the Authorization header, never in a URL. Human sessions use the equivalent
reader/editor roles and same-origin checks.

- `POST /v1/eve-content/media/query`: `search`, `get`, `sources`, or
  `references`. Search accepts filename/path text and an optional `documentId`
  for imported source references. `get` accepts an ID or legacy path, optionally
  pinned to a Git commit. Pagination uses `page` and `limit` (maximum 50).
- `POST /v1/eve-content/media/upload`: original binary body,
  `Content-Type: application/octet-stream`, URL-encoded `X-Eve-Filename`, and a
  UUID `Idempotency-Key`. Preserve the key and identical bytes/filename after a
  lost response. Files must contain 1 byte to 32 MiB.
- `GET /v1/eve-content/media/<id>/file`: authenticated original download with
  single byte-range support. Query responses provide a relative `downloadPath`
  to append to the content API prefix.
- MCP `eve_media_query`: the same bounded metadata, alias and reference reads.
  Binary uploads/downloads use the HTTP endpoints.

Document attachment links are preserved inside immutable document revisions. The
source-reference query describes imported links; extracting relations from newly
authored revisions remains part of the document-relations cutover.

## Migration and recovery

Run operator commands with the repository's pinned Node installation. Storage
configuration stays in mode-0600 files outside Git. Configure each environment
only after its separate CMS database/operator configuration exists:

```sh
python3 infra/hetzner/eve/provision-media-storage.py --environment dev
node tools/eve-content/inventory-media.mjs --root . \
  --documents /private/document-manifest.json --out /private/media-manifest.json
python3 infra/hetzner/eve/import-media.py --source . --environment dev \
  --node /root/.nvm/versions/node/v24.14.1/bin/node \
  --manifest /private/media-manifest.json --report /private/media-import.json
```

The inventory reads the frozen Git commit, resolves document-owned media, and
preserves presentation assets, narration and verification images. Operational
application assets and fixtures remain in Git. Referenced LFS objects require
the exact checksum-verified original; a pointer is never imported as an image.
Unresolved references remain visible in the manifest for reconciliation.

The importer is resumable. Choose a new report path for each attempt. An import
is marked verified only after every alias is read back and every unique primary
and recovery body matches its checksum. The complete manifest is also stored in
PostgreSQL so recovery does not depend on a surviving checkout.

After the import completes, take a PostgreSQL backup, then extend the existing
isolated restore drill with:

```sh
python3 infra/hetzner/eve/restore-drill.py --require-api --source . \
  --node /root/.nvm/versions/node/v24.14.1/bin/node \
  --content-manifest /private/document-manifest.json \
  --content-report /private/restored-content.json \
  --media-manifest-hash <verified-media-manifest-sha256> \
  --media-report /private/restored-media.json
```

The drill checks the restored manifest, every alias and document reference, and
every recovery object body, without using the primary media objects. It stops
and removes only its own temporary PostgreSQL cluster. Media/source retirement
remains forbidden until consumer conversion and final reconciliation pass.
