Rename the metric triple and the parameter set field (#1009)

## The renames

Three renames and the migration one of them needs. No behavior change.

### `JsonMetric` -> `JsonMetricTriple`

A `JsonMetric` is a value with its two bounds: the triple a metric row
used to be
before named values existed. The plain name read like the whole of what
a metric is,
which it is not any more. This is a type rename only. Every serde field
that carries
one keeps its own name (`JsonAlert.metric`, `JsonPerfMetric.metric`, and
the rest), so
not one response byte changes. The OpenAPI component and the TypeScript
type follow.

### `JsonReportParameter.parameters` -> `set`

The object is already named `parameter` where a report result carries
it, so the field
spelled its parent again. It now spells what it holds:

```json
"parameter": { "uuid": "...", "set": { "size_mb": 16 } }
```

This one does change report response bytes. It is free right now: no
released CLI
deserializes the report `parameter` object, so nothing in the wild reads
the old
spelling. Once the next release ships a client that does, the same
rename becomes a
break. The type name `JsonReportParameter` is unchanged.

The BMF v1 **input** format is untouched. A report still submits
`"parameters"` on each
entry, and every adapter fixture stays as it was.

### `JsonParameters` -> `ParameterSet`

The type has been called a parameter set in its own prose since it was
written. It is
an internal newtype with a hand written `JsonSchema` impl, so the
component name is
renamed there as well, and the typeshare mapping follows.

## The migration

`2026-08-23-120000_parameter_set` renames the `parameter.parameters`
column to
`parameter.set`, and the model fields follow it (`QueryParameter.set`,
`InsertParameter.set`, `UpdateParameter.set`).

`set` is an SQL keyword, so the migration and the raw SQL that reads the
column quote
it. Diesel quotes identifiers of its own accord, so the DSL needs
nothing.

The migration is metadata only:

```sql
ALTER TABLE parameter RENAME COLUMN parameters TO "set";
```

SQLite rewrites the stored DDL in place, `UNIQUE(benchmark_id, "set")`
and the index
that backs it included, without reading a row. `down.sql` is the
reverse, and just as
cheap.

Migrations already written keep the spelling that was true when they
ran: the
migrations that create and read `parameter.parameters` are history and
are left alone.
The one seed in the migration tests that hand writes a `parameter` row
below this
layer now does so in raw SQL under the old column name, which is what
the schema at
that point in the chain has; the chain renames it on the way back up.

## Gates

- `cargo fmt -- --check`
- `cargo clippy --no-deps --all-targets --all-features -- -Dwarnings`
- `cargo nextest run --all-features --profile ci`, `cargo test --doc
--all-features`
- `cargo check --no-default-features`
- `cargo gen-types`, with the regenerated spec and TypeScript types
committed

Author: epompeii

lib/api_projects/tests/benchmarks.rs

@@ -7,7 +7,7 @@
 //! Integration tests for project benchmark endpoints.
 
 use bencher_api_tests::{TestServer, helpers::create_empty_parameter};
-use bencher_json::{JsonBenchmark, JsonBenchmarks, JsonParameters};
+use bencher_json::{JsonBenchmark, JsonBenchmarks, ParameterSet};
 use bencher_schema::schema;
 use diesel::{
     ExpressionMethods as _, QueryDsl as _, RunQueryDsl as _, connection::SimpleConnection as _,
@@ -149,14 +149,14 @@ fn assert_benchmark_birth_invariant(server: &TestServer) {
     );
 
     for benchmark_id in benchmark_ids {
-        let parameters: Vec<JsonParameters> = schema::parameter::table
+        let parameters: Vec<ParameterSet> = schema::parameter::table
             .filter(schema::parameter::benchmark_id.eq(benchmark_id))
-            .select(schema::parameter::parameters)
+            .select(schema::parameter::set)
             .load(&mut conn)
             .expect("Failed to load parameters");
         assert_eq!(
             parameters,
-            vec![JsonParameters::default()],
+            vec![ParameterSet::default()],
             "benchmark {benchmark_id} must have exactly one empty parameter set"
         );
     }
@@ -196,12 +196,12 @@ async fn benchmarks_create_empty_parameter_set() {
         .select(schema::benchmark::id)
         .first(&mut conn)
         .expect("Failed to get benchmark ID");
-    let parameters: Vec<JsonParameters> = schema::parameter::table
+    let parameters: Vec<ParameterSet> = schema::parameter::table
         .filter(schema::parameter::benchmark_id.eq(benchmark_id))
-        .select(schema::parameter::parameters)
+        .select(schema::parameter::set)
         .load(&mut conn)
         .expect("Failed to load parameters");
-    assert_eq!(parameters, vec![JsonParameters::default()]);
+    assert_eq!(parameters, vec![ParameterSet::default()]);
 
     assert_benchmark_birth_invariant(&server);
 }
@@ -221,7 +221,7 @@ async fn benchmarks_create_rolls_back_with_parameter_set() {
 
     // Poison the empty parameter set that the next benchmark will be born with.
     // SQLite hands an `INTEGER PRIMARY KEY` the next rowid after the largest in
-    // use, so the row below collides on `UNIQUE(benchmark_id, parameters)` with
+    // use, so the row below collides on `UNIQUE(benchmark_id, "set")` with
     // the set created inside the benchmark's own transaction. Foreign keys are
     // off on this connection, so it may point at a benchmark that does not exist yet.
     let mut conn = server.db_conn();

lib/api_projects/tests/metric_migration.rs

@@ -19,12 +19,12 @@
 
 use bencher_api_tests::{
     TestServer,
-    helpers::{base_timestamp, create_empty_parameter, get_project_id},
+    helpers::{base_timestamp, get_project_id},
 };
 use bencher_json::{
     AlertUuid, BenchmarkUuid, BoundaryUuid, BranchUuid, HeadUuid, MeasureUuid, MetricName,
-    MetricUuid, ModelUuid, ReportBenchmarkUuid, ReportUuid, TestbedUuid, ThresholdUuid,
-    VersionUuid, project::alert::AlertStatus, project::boundary::BoundaryLimit,
+    MetricUuid, ModelUuid, ParameterUuid, ReportBenchmarkUuid, ReportUuid, TestbedUuid,
+    ThresholdUuid, VersionUuid, project::alert::AlertStatus, project::boundary::BoundaryLimit,
 };
 use bencher_schema::{MIGRATIONS, context::DbConnection, schema};
 use diesel::{
@@ -710,6 +710,36 @@ fn revert_migration(conn: &mut DbConnection) {
         .expect("Failed to enable foreign keys");
 }
 
+/// Seed a benchmark's empty parameter set at the reverted schema point.
+///
+/// Benchmarks inserted directly into the database bypass `QueryBenchmark::create`,
+/// so they need the birth invariant applied by hand. The migrations are reverted
+/// when this runs, so the column is still spelled `parameters`: the rename to `set`
+/// is a layer above, and the chain puts it back on the way up. That is why this is
+/// raw SQL rather than `create_empty_parameter`, for the same reason the metric rows
+/// below are.
+fn seed_empty_parameter(conn: &mut DbConnection, benchmark_id: i32) -> i32 {
+    let now = base_timestamp();
+
+    let parameter_uuid = ParameterUuid::new();
+    diesel::sql_query(
+        "INSERT INTO parameter (uuid, benchmark_id, parameters, created, modified)
+         VALUES (?, ?, jsonb('{}'), ?, ?)",
+    )
+    .bind::<Text, _>(parameter_uuid.to_string())
+    .bind::<Integer, _>(benchmark_id)
+    .bind::<BigInt, _>(now)
+    .bind::<BigInt, _>(now)
+    .execute(&mut *conn)
+    .expect("Failed to seed the empty parameter set");
+
+    schema::parameter::table
+        .filter(schema::parameter::uuid.eq(&parameter_uuid))
+        .select(schema::parameter::id)
+        .first(&mut *conn)
+        .expect("Failed to get the parameter id")
+}
+
 /// The `metric_boundary` column list, in the order `view.rs` declares it.
 const VIEW_COLUMNS: [&str; 14] = [
     "metric_id",
@@ -904,7 +934,7 @@ async fn seed_legacy_project(server: &TestServer, label: &str) -> Fixture {
         .select(schema::benchmark::id)
         .first(&mut conn)
         .expect("Failed to get the benchmark id");
-    let parameter_id = create_empty_parameter(&mut conn, benchmark_id);
+    let parameter_id = seed_empty_parameter(&mut conn, benchmark_id);
 
     // Two measures, so a pivot that joins on the report benchmark alone pulls a
     // bound across measures and fails.

lib/api_projects/tests/parameters.rs

@@ -17,7 +17,7 @@ use bencher_api_tests::{
     TestServer,
     helpers::{base_timestamp, get_project_id},
 };
-use bencher_json::{DateTime, JsonParameters, MetricName, Slug};
+use bencher_json::{DateTime, MetricName, ParameterSet, Slug};
 use bencher_schema::{
     context::DbConnection,
     model::{organization::OrganizationId, project::metric::QueryMetric},
@@ -140,12 +140,12 @@ fn organization_id(conn: &mut DbConnection, project_id: i32) -> OrganizationId {
 
 /// Every parameter set stored under a project, with the number of `report_benchmark`
 /// rows pointing at it.
-fn parameter_sets(conn: &mut DbConnection, project_id: i32) -> Vec<(JsonParameters, i64)> {
-    let parameters: Vec<(i32, JsonParameters)> = schema::parameter::table
+fn parameter_sets(conn: &mut DbConnection, project_id: i32) -> Vec<(ParameterSet, i64)> {
+    let parameters: Vec<(i32, ParameterSet)> = schema::parameter::table
         .inner_join(schema::benchmark::table)
         .filter(schema::benchmark::project_id.eq(project_id))
         .order(schema::parameter::id.asc())
-        .select((schema::parameter::id, schema::parameter::parameters))
+        .select((schema::parameter::id, schema::parameter::set))
         .load(&mut *conn)
         .expect("Failed to load the parameter sets");
 
@@ -163,7 +163,7 @@ fn parameter_sets(conn: &mut DbConnection, project_id: i32) -> Vec<(JsonParamete
 }
 
 /// Every metric name stored for a project, with its value, keyed by parameter set.
-fn named_values(conn: &mut DbConnection, project_id: i32) -> Vec<(JsonParameters, String, f64)> {
+fn named_values(conn: &mut DbConnection, project_id: i32) -> Vec<(ParameterSet, String, f64)> {
     schema::metric::table
         .inner_join(
             schema::report_benchmark::table
@@ -173,19 +173,19 @@ fn named_values(conn: &mut DbConnection, project_id: i32) -> Vec<(JsonParameters
         .filter(schema::benchmark::project_id.eq(project_id))
         .order((schema::parameter::id.asc(), schema::metric::name.asc()))
         .select((
-            schema::parameter::parameters,
+            schema::parameter::set,
             schema::metric::name,
             schema::metric::value,
         ))
-        .load::<(JsonParameters, MetricName, f64)>(&mut *conn)
+        .load::<(ParameterSet, MetricName, f64)>(&mut *conn)
         .expect("Failed to load the metric rows")
         .into_iter()
         .map(|(parameters, name, value)| (parameters, name.to_string(), value))
         .collect()
 }
 
 /// The parameter set and metric name of every alert in a project.
-fn alerts(conn: &mut DbConnection, project_id: i32) -> Vec<(JsonParameters, String)> {
+fn alerts(conn: &mut DbConnection, project_id: i32) -> Vec<(ParameterSet, String)> {
     schema::alert::table
         .inner_join(
             schema::boundary::table.inner_join(
@@ -198,8 +198,8 @@ fn alerts(conn: &mut DbConnection, project_id: i32) -> Vec<(JsonParameters, Stri
         )
         .filter(schema::benchmark::project_id.eq(project_id))
         .order(schema::alert::id.asc())
-        .select((schema::parameter::parameters, schema::metric::name))
-        .load::<(JsonParameters, MetricName)>(&mut *conn)
+        .select((schema::parameter::set, schema::metric::name))
+        .load::<(ParameterSet, MetricName)>(&mut *conn)
         .expect("Failed to load the alerts")
         .into_iter()
         .map(|(parameters, name)| (parameters, name.to_string()))
@@ -239,7 +239,7 @@ fn series_measures(conn: &mut DbConnection, project_id: i32) -> Vec<String> {
         .collect()
 }
 
-fn parameters(canonical: &str) -> JsonParameters {
+fn parameters(canonical: &str) -> ParameterSet {
     canonical.parse().expect("Failed to parse the parameters")
 }
 
@@ -279,7 +279,7 @@ async fn v1_report_lands_grid_points_and_named_values() {
     assert_eq!(
         parameter_sets(&mut conn, project_id),
         vec![
-            (JsonParameters::default(), 0),
+            (ParameterSet::default(), 0),
             (parameters(r#"{"size_mb": 16}"#), 1),
             (parameters(r#"{"size_mb": 32}"#), 1),
         ],
@@ -499,7 +499,7 @@ async fn bare_threshold_gates_only_the_value_name() {
     let alerts = alerts(&mut conn, project_id);
     assert_eq!(
         alerts,
-        vec![(JsonParameters::default(), "value".to_owned())],
+        vec![(ParameterSet::default(), "value".to_owned())],
         "the alert is on the point estimate"
     );
 }
@@ -534,7 +534,7 @@ async fn absent_parameters_land_on_the_empty_set() {
 
     assert_eq!(
         parameter_sets(&mut conn, project_id),
-        vec![(JsonParameters::default(), 1)],
+        vec![(ParameterSet::default(), 1)],
         "an absent parameter set and an explicit empty one are one grid point"
     );
 }
@@ -595,7 +595,7 @@ async fn v1_entry_without_measures_mints_nothing() {
     assert_eq!(benchmark_count(&mut conn, project_id), 1);
     assert_eq!(
         parameter_sets(&mut conn, project_id),
-        vec![(JsonParameters::default(), 0)],
+        vec![(ParameterSet::default(), 0)],
         "only the empty set the benchmark was born with, pointed at by nothing"
     );
     assert_eq!(named_values(&mut conn, project_id), vec![]);
@@ -623,7 +623,7 @@ async fn v1_benchmark_without_entries_mints_nothing() {
     assert_eq!(benchmark_count(&mut conn, project_id), 1);
     assert_eq!(
         parameter_sets(&mut conn, project_id),
-        vec![(JsonParameters::default(), 0)],
+        vec![(ParameterSet::default(), 0)],
     );
     assert_eq!(named_values(&mut conn, project_id), vec![]);
     assert_eq!(series_measures(&mut conn, project_id), Vec::<String>::new());
@@ -655,7 +655,7 @@ async fn v0_benchmark_without_measures_is_unchanged() {
     assert_eq!(benchmark_count(&mut conn, project_id), 1);
     assert_eq!(
         parameter_sets(&mut conn, project_id),
-        vec![(JsonParameters::default(), 1)],
+        vec![(ParameterSet::default(), 1)],
         "the v0 row still lands on the empty parameter set"
     );
     assert_eq!(named_values(&mut conn, project_id), vec![]);
@@ -684,7 +684,7 @@ async fn archived_parameter_set_is_unarchived_on_report() {
         let mut conn = server.db_conn();
         let updated = diesel::update(
             schema::parameter::table
-                .filter(schema::parameter::parameters.eq(parameters(r#"{"size_mb": 16}"#))),
+                .filter(schema::parameter::set.eq(parameters(r#"{"size_mb": 16}"#))),
         )
         .set(schema::parameter::archived.eq(Some(1_000_000_000i64)))
         .execute(&mut conn)
@@ -698,7 +698,7 @@ async fn archived_parameter_set_is_unarchived_on_report() {
     let archived: Vec<Option<i64>> = schema::parameter::table
         .inner_join(schema::benchmark::table)
         .filter(schema::benchmark::project_id.eq(project_id))
-        .filter(schema::parameter::parameters.eq(parameters(r#"{"size_mb": 16}"#)))
+        .filter(schema::parameter::set.eq(parameters(r#"{"size_mb": 16}"#)))
         .select(schema::parameter::archived)
         .load(&mut conn)
         .expect("Failed to load the parameter set");
@@ -978,12 +978,12 @@ async fn report_response_echoes_named_values_and_separates_grid_points() {
         Some(&serde_json::json!({ "benchmarks": 2, "measures": 2 })),
     );
 
-    let grid_points: Vec<JsonParameters> = results
+    let grid_points: Vec<ParameterSet> = results
         .iter()
         .map(|result| {
             serde_json::from_value(
                 result
-                    .pointer("/parameter/parameters")
+                    .pointer("/parameter/set")
                     .expect("each result names its parameter set")
                     .clone(),
             )

lib/api_projects/tests/reports.rs

@@ -16,8 +16,8 @@ use bencher_api_tests::{
     },
 };
 use bencher_json::{
-    BenchmarkUuid, BoundaryUuid, JsonParameters, JsonReport, JsonReports, MeasureUuid, MetricName,
-    MetricUuid, ModelUuid, ReportBenchmarkUuid, ThresholdUuid,
+    BenchmarkUuid, BoundaryUuid, JsonReport, JsonReports, MeasureUuid, MetricName, MetricUuid,
+    ModelUuid, ParameterSet, ReportBenchmarkUuid, ThresholdUuid,
 };
 use bencher_schema::{
     context::DbConnection,
@@ -626,14 +626,14 @@ async fn reports_ingest_empty_parameter_sets() {
     assert_eq!(benchmark_ids.len(), 2, "two benchmarks were ingested");
 
     for benchmark_id in benchmark_ids {
-        let parameters: Vec<JsonParameters> = schema::parameter::table
+        let parameters: Vec<ParameterSet> = schema::parameter::table
             .filter(schema::parameter::benchmark_id.eq(benchmark_id))
-            .select(schema::parameter::parameters)
+            .select(schema::parameter::set)
             .load(&mut conn)
             .expect("Failed to load parameters");
         assert_eq!(
             parameters,
-            vec![JsonParameters::default()],
+            vec![ParameterSet::default()],
             "benchmark {benchmark_id} must have exactly one empty parameter set"
         );
     }

lib/bencher_adapter/src/adapters/json/v0.rs

@@ -1,6 +1,6 @@
 use std::collections::HashMap;
 
-use bencher_json::{BenchmarkNameId, JsonNewMetric, JsonParameters, MeasureNameId};
+use bencher_json::{BenchmarkNameId, JsonNewMetric, MeasureNameId, ParameterSet};
 
 use crate::{
     Adaptable, Settings,
@@ -39,7 +39,7 @@ fn from_wire(results: JsonV0Results) -> AdapterResults {
                 .collect::<HashMap<_, _>>();
             (
                 benchmark,
-                std::iter::once((JsonParameters::default(), metrics.into())).collect(),
+                std::iter::once((ParameterSet::default(), metrics.into())).collect(),
             )
         })
         .collect::<ResultsMap>()

lib/bencher_adapter/src/adapters/json/v1.rs

@@ -1,6 +1,6 @@
 use std::collections::HashMap;
 
-use bencher_json::{BenchmarkNameId, JsonParameters, MeasureNameId};
+use bencher_json::{BenchmarkNameId, MeasureNameId, ParameterSet};
 use serde::Deserialize;
 
 use crate::{
@@ -21,7 +21,7 @@ pub struct JsonV1Entry {
     /// Optional. An entry without it resolves to the benchmark's empty parameter set,
     /// which is exactly what an explicit `{}` resolves to.
     #[serde(default)]
-    pub parameters: JsonParameters,
+    pub parameters: ParameterSet,
     pub measures: HashMap<MeasureNameId, JsonV1Measure>,
 }
 
@@ -86,7 +86,7 @@ fn from_wire(results: JsonV1Results) -> AdapterResults {
 
 #[cfg(test)]
 pub(crate) mod test_json_v1 {
-    use bencher_json::{BenchmarkNameId, JsonParameters, MAX_PARAMETER_KEYS, MetricName};
+    use bencher_json::{BenchmarkNameId, MAX_PARAMETER_KEYS, MetricName, ParameterSet};
     use ordered_float::OrderedFloat;
     use pretty_assertions::assert_eq;
 
@@ -125,7 +125,7 @@ pub(crate) mod test_json_v1 {
             .parse::<BenchmarkNameId>()
             .expect("Failed to parse benchmark name");
         let parameters = parameters
-            .parse::<JsonParameters>()
+            .parse::<ParameterSet>()
             .expect("Failed to parse parameters");
         results
             .inner
@@ -217,7 +217,7 @@ pub(crate) mod test_json_v1 {
         let merged = "tests::merged".parse::<BenchmarkNameId>().unwrap();
         let entries = &results.inner[&merged];
         assert_eq!(entries.len(), 1);
-        let metrics = &entries[&JsonParameters::default()];
+        let metrics = &entries[&ParameterSet::default()];
         assert_eq!(named(metrics, "latency", "value"), Some(1.0.into()));
         assert_eq!(named(metrics, "throughput", "value"), Some(2.0.into()));
     }