Module models 

Row types mirroring the tables in migrations/.

These are deliberately typed, not raw-column, shapes: wherever a table’s columns are a clean 1:1 match for an existing bhtune-core type (DcsTemplate, LoopTags, LoopConfig, Tick + MrftState), the row struct holds that type directly rather than re-declaring its fields — one less place for the two to drift apart. Where a table combines fields from two bhtune-core types that both carry their own overlapping field (TuningResult/PidParameters both carry response_level; InitialReadings/PvRange don’t nest cleanly with the extra controller_direction column), the row struct is flat instead, matching the table exactly and avoiding a redundant, only-sometimes-consistent duplicate field.

DemoSessionRow, DcsTemplateRow, and TuneRunRow/TuneSampleRow/TuneResultRow/ TuneMvActuationRow/TuneWriteRow have full repository methods (insert, lifecycle transitions, filtering, pagination). LoopRow deliberately has no repository methods: full CRUD for saved loops (list/update/delete) is separate from run history, which is about runs, not the loops they reference. Tests construct loops rows with raw SQL (see tests/schema.rs’s seed_loop helper) purely as foreign-key setup.

TuneRunRow::list/TuneRunRow::count build their WHERE clause dynamically with sqlx::QueryBuilder, since TuneRunFilter’s fields are all optional and the set of active conditions varies per call — a fixed query! string can’t express that, and bhtune-db uses runtime query/query_as throughout anyway (see Cargo.toml), so this doesn’t introduce a new query style, just the first dynamic one.

Structs

CompleteRecoveryUpdate

DcsTemplateRow

One row of dcs_templates: a [DcsTemplate] plus the database bookkeeping fields that don’t belong on the pure domain type itself.

DemoSessionRow

A short-lived anonymous owner for simulator-only public demo runs. The raw bearer token is never stored; callers pass its lowercase hexadecimal SHA-256 hash to the repository.

EffectiveTuning

Concrete tune timing values after configuration defaults have been resolved.

LiveMutationStepRow

LiveOwnershipRow

LoopRow

One row of loops: a saved, named tag mapping plus default MRFT parameters.

NewLiveMutationStep

NewLiveOwnership

NewTuneMvActuation

Input for TuneMvActuationRow::insert_pending.

NewTuneWrite

Everything needed to record one write-back attempt, successful or not. Built up by the caller through the sequential pre-read / write-and-verify / rollback steps, then persisted in a single TuneWriteRow::insert call so partial writes and rollback outcomes are represented alongside complete success or pre-read failure.

OrphanOwnerUpdate

Pagination

A page of TuneRunRow::list results: limit rows starting at offset, ordered newest first.

PollLatencyMetrics

Operation-latency diagnostics captured while a run is polling.

RestartRecoveryUpdate

SettingRow

One row of settings: an app-wide key/value pair (e.g. the history retention policy).

TimingMetrics

Polling-cadence diagnostics captured over one run’s successful PV samples.

TimingSummary

Summary statistics for one class of measured polling work.

TuneMvActuationRow

One row of tune_mv_actuations: durable evidence for an accepted OPC DA MV write.

TuneRecoveryAttemptRow

TuneResultRow

One row of tune_results: the calculated PID result for one [ResponseLevel] of one run.

TuneRunFilter

Filter criteria for TuneRunRow::list/TuneRunRow::count. Every field is optional; the all-None default matches every run. Build one with TuneRunFilter::default and the with_* methods, e.g. TuneRunFilter::default().with_outcome(TuneOutcome::Failed).

TuneRunInitialReadings

The initial-readings snapshot for a TuneRunRow — known only once the driver’s initial read actually succeeds (ReadInitialOPCvalues in the legacy app); None for a run that failed before or during that step. Combines [bhtune_core::mrft::InitialReadings]/[bhtune_core::range::PvRange] with the resolved [ControllerDirection] core-tuning-math needs alongside them, as one bespoke type, since gluing the two existing structs together with one extra field isn’t any simpler than a purpose-built one here.

TuneRunRow

One row of tune_runs: a single MRFT (or future Step Test) execution against a loop.

TuneSampleRow

One row of tune_samples: a single tick’s [Tick] input and resulting [MrftState].

TuneWriteRow

One row of tune_writes: an audit record of PID constants actually written back to the DCS for one [ResponseLevel] of one run, distinct from what was merely calculated (TuneResultRow). Flattened for the same reason as TuneResultRow.

UnrecoverableOwnerUpdate

WriteReadback

A triple of proportional/integral/derivative values, read from the driver before any write is attempted (TuneWriteRow::previous). Not a bhtune-core type like bhtune_core::tuning_math::OpcWriteValues: this is a raw observation, not a calculated/intended value.

Enums

LiveOperationKind

LiveOwnershipState

MutationStepStatus

MvActuationKind

The physical purpose of one accepted manipulated-variable command.

MvActuationStatus

Lifecycle state of one accepted manipulated-variable command.

RecoveryAttemptStatus

RestoreStatus

The outcome of a best-effort loop-restore attempt made after a run ended – safety-restore-guard (finding 3 of the live-plant safety review). Recorded via TuneRunRow::record_restore_status; NULL in the database (mapped to None on TuneRunRow::restore_status) means no restore was ever attempted – either the run never mutated the loop at all, or it hasn’t ended yet.

RollbackState

Whether a best-effort rollback of a partially-completed PID write was attempted and, if so, whether it succeeded. See TuneWriteRow::rollback_state for when this is None.

SampleQuality

How much a TuneSampleRow’s sample.pv reading should be trusted, as recorded at the moment it was read (finding 5 of the live-plant safety review).

SamplingAdequacy

Advisory assessment of whether the recorded samples provide enough observations per oscillation period for a trustworthy extrema measurement.

TemplateOrigin

Where a dcs_templates row came from, and – since TuneRunRow snapshots a copy of one at TuneRunRow::start time – where a run’s snapshotted template came from too. Kept as one definition reused by both tables (dcs_templates.origin, tune_runs.template_origin) rather than two, so they can never drift on what the possible origins even are, and so a run’s history never needs to look the original row back up to know its provenance – which matters precisely because that row might no longer exist, or might have been re-imported under a different origin since.

TimingBasis

The clock basis used for a run’s persisted polling-cadence diagnostics.

TuneDriver

Which crate-agnostic I/O driver a run used. Lives in bhtune-db rather than bhtune-core because it’s a persistence/orchestration concept (which adapter drove this run), not a domain concept the pure MRFT engine itself needs to know about.

TuneOutcome

A run’s lifecycle state.

TuneRecoveryState

The durable eligibility and outcome state for bhtune restore-loop.

WriteKind

Distinguishes a normal write-back from bhtune history revert undoing an earlier one. Both share TuneWriteRow’s exact shape – pre-read, write-and-verify each constant, audit the outcome – so they live in the same table rather than a second near-duplicate one; kind is the one column that tells them apart.

Constants

DEMO_RESTART_INTERRUPTED_REASON

Failure reason persisted when startup recovery terminates an owned demo run that was still marked as running.