Data model and migrations

The authoritative description of the data model lives in the repository at docs/data-model.md. That document owns the state machines and the derivations; this page is a map of what is there, so you know where to look and do not rely on a copy that could drift.

Migrations

Schema changes are forward-only migrations, applied by peart migrate, all-or-none and safe to run again. The serving process checks the schema version at startup and refuses to run against an outdated database rather than migrating silently at boot.

The state machines that matter

Several pieces of state are derived, not set by hand, which is what keeps them from ever contradicting the record. Understanding these is most of understanding the model.

• Finding publication is two columns, not a flag: a published_revision_id and a has_pending_changes marker, from which draft / published / published-with-pending-edit is derived. The portal only ever reads the published revision.
• Finding verification (open, fixed, partially_fixed, reopened) is derived from the finding's retests in date order, written only by the retest service, never editable.
• Disposition is a declared decision, with who set it and when, and a required reason when it is anything but the default.
• Report generation (pending, ready, failed) and release (released_at) are two independent axes; release freezes the report's published revisions, compliance mappings and remediation due dates.
• The audit trail is an insert-only table that records identifiers and never content values, so it can never become a second, unencrypted copy of the most sensitive asset.

For the exact columns, constraints and the full state diagrams, read docs/data-model.md.