Runtime vs Export Boundary
==========================

Purpose
-------

This note defines the current storage boundary for the standalone server repo.

Rule
----

PostgreSQL is authoritative for runtime operational state.

The filesystem is limited to:

- uploaded artifact bytes
- generated outputs
- exported debug/compatibility copies

Runtime authority
-----------------

The following state is DB-backed and must not be reconstructed from exported
JSON files on disk:

- devices, tokens, and assignments
- customers, billing profiles, operators, and trees
- jobs and job shell metadata
- rounds and round status
- round manifest payloads
- round review payloads
- runtime profile state
- recording metadata and processed/transcript state
- image metadata
- finals, corrections, and GeoJSON rows

Artifact storage
----------------

The filesystem remains the storage location for artifact bytes and generated
outputs, including:

- uploaded audio files
- uploaded image files
- generated report images
- generated PDFs and DOCX

Export/debug copies
-------------------

The server may still write compatibility or inspection-oriented files under the
storage root. These files are not authoritative runtime state.

Examples:

- ``local_data/jobs/<job_id>/job_record.json``
- ``local_data/jobs/<job_id>/rounds/<round_id>/manifest.json``
- ``local_data/jobs/<job_id>/rounds/<round_id>/review.json``
- ``local_data/jobs/<job_id>/sections/<section_id>/recordings/<recording_id>.meta.json``
- ``local_data/jobs/<job_id>/sections/<section_id>/images/<image_id>.meta.json``

Operational rule
----------------

If a DB row and an exported JSON file disagree:

- the DB row wins for runtime behavior
- the exported file is treated as stale debug output

Why this matters
----------------

This boundary is required for:

- cloud migration of operational state
- predictable device/client behavior
- avoiding split-brain bugs between in-memory, DB, and disk JSON
- keeping local storage focused on artifacts rather than workflow authority