feat!: read checks through the control API

People can list a target's checks with their newest results, read one check's recent results, and, with view.sql, read its SQL. Checks are keyed by binding_key, now a typed, indexed column on the audit-result mirror, because one audit name such as not_null covers many models and columns. A model rename or a severity or threshold change starts a new check history, and the old one stays readable. SQL reads are audited like node SQL.

BREAKING CHANGE: control stores created by 0.188.x are not upgraded. The server refuses them with an error saying to recreate the control store; create a new one when upgrading.

Author: kvlonge

benchmarks/duckshop/edge_cases/orchestration/check_identity.json

@@ -0,0 +1,14 @@
+{
+  "audit_name": "not_null",
+  "checks": [
+    {"binding_key": "6f1c0e2a-orders-order-id", "attached_target_name": "orders", "attached_column_name": "order_id"},
+    {"binding_key": "0b9d4c71-customers-customer-id", "attached_target_name": "customers", "attached_column_name": "customer_id"},
+    {"binding_key": "9a3e5d10-archived-orders-order-id", "attached_target_name": "archived_orders", "attached_column_name": "order_id"}
+  ],
+  "results": [
+    {"check": 0, "result_id": "orders-not-null-1", "occurred_at": "2026-02-03T04:05:06Z", "outcome": "fail", "violation_count": 3, "executed_sql": "SELECT order_id FROM orders WHERE order_id IS NULL /* first 'run' 🧾 */"},
+    {"check": 0, "result_id": "orders-not-null-2", "occurred_at": "2026-02-04T04:05:06Z", "outcome": "pass", "violation_count": 0, "executed_sql": "SELECT order_id FROM orders WHERE order_id IS NULL /* second 'run' 🧾 */"},
+    {"check": 1, "result_id": "customers-not-null-1", "occurred_at": "2026-02-03T05:05:06Z", "outcome": "error", "violation_count": null, "executed_sql": "SELECT customer_id FROM customers WHERE customer_id IS NULL", "execution_error": "Binder Error: Referenced column \"customer_id\" not found\n\nLINE 1: SELECT customer_id FROM customers WHERE email = 'private@example.com'"},
+    {"check": 2, "result_id": "archived-orders-not-null-1", "occurred_at": "2026-02-02T04:05:06Z", "outcome": "pass", "violation_count": 0, "executed_sql": "SELECT order_id FROM archived_orders WHERE order_id IS NULL"}
+  ]
+}

clients/typescript/src/schema.d.ts

@@ -210,6 +210,54 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/control/locations/{location_id}/targets/{target}/checks": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["listPersonChecks"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/control/locations/{location_id}/targets/{target}/checks/{binding_key}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["readPersonCheckHistory"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/api/control/locations/{location_id}/targets/{target}/checks/{binding_key}/sql": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["readPersonCheckSql"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/control/locations/{location_id}/targets/{target}/connection-tests": {
         parameters: {
             query?: never;
@@ -769,6 +817,52 @@ export interface components {
         ChangeNotice: {
             topic: string;
         };
+        /** @description One stored check result. Its SQL, error texts and evidence rows need their own permissions. */
+        CheckResult: {
+            attached_column_name?: string | null;
+            attached_target_kind?: string | null;
+            attached_target_name?: string | null;
+            attachment_kind: string;
+            audit_definition_name: string;
+            audit_description?: string | null;
+            audit_name: string;
+            /** @description Identity of the check; a renamed model or changed severity or thresholds starts a new one. */
+            binding_key: string;
+            evaluation_mode: string;
+            /** Format: uuid */
+            event_id: string;
+            /** Format: int64 */
+            evidence_count?: number | null;
+            evidence_truncated?: string | null;
+            invocation_id: string;
+            measured_value?: string | null;
+            /** Format: int64 */
+            minimum_samples?: number | null;
+            /** Format: date-time */
+            occurred_at: string;
+            outcome: string;
+            reused: string;
+            run_id: string;
+            run_scope_phase: string;
+            /** Format: int64 */
+            sample_count?: number | null;
+            sample_unit?: string | null;
+            severity: string;
+            thresholds_json?: string | null;
+            /** Format: int64 */
+            violation_count?: number | null;
+        };
+        /** @description A check's latest SQL and error texts, which quote SQL; `view.sql` reads them, audited. */
+        CheckSql: {
+            binding_key: string;
+            /** Format: uuid */
+            event_id: string;
+            evidence_error?: string | null;
+            evidence_sql?: string | null;
+            executed_sql?: string | null;
+            execution_error?: string | null;
+            measurement_sql?: string | null;
+        };
         CliLoginApprovalRequest: {
             approve: boolean;
             browser_code: string;
@@ -2127,6 +2221,124 @@ export interface operations {
             };
         };
     };
+    listPersonChecks: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                location_id: string;
+                target: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The newest result of every check */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CheckResult"][];
+                };
+            };
+            /** @description Session rejected */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiErrorBody"];
+                };
+            };
+        };
+    };
+    readPersonCheckHistory: {
+        parameters: {
+            query?: {
+                /** @description Maximum results, newest first; defaults to 50, capped at 1000 */
+                limit?: number;
+            };
+            header?: never;
+            path: {
+                location_id: string;
+                target: string;
+                binding_key: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Empty for an unknown check */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CheckResult"][];
+                };
+            };
+            /** @description Session rejected */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiErrorBody"];
+                };
+            };
+        };
+    };
+    readPersonCheckSql: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                location_id: string;
+                target: string;
+                binding_key: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": null | components["schemas"]["CheckSql"];
+                };
+            };
+            /** @description Session rejected */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiErrorBody"];
+                };
+            };
+        };
+    };
     requestConnectionTest: {
         parameters: {
             query?: never;

crates/sqlbuild-orchestration/src/api/_helpers/authentication/password_sessions.rs

@@ -109,6 +109,18 @@ pub(crate) fn person_routes() -> Router<ControlStore> {
             "/api/control/locations/{location_id}/targets/{target}/nodes/{node_key}/sql",
             get(crate::api::_helpers::resources::person_node_sql::read),
         )
+        .route(
+            "/api/control/locations/{location_id}/targets/{target}/checks",
+            get(crate::api::_helpers::resources::person_checks::list),
+        )
+        .route(
+            "/api/control/locations/{location_id}/targets/{target}/checks/{binding_key}",
+            get(crate::api::_helpers::resources::person_checks::history),
+        )
+        .route(
+            "/api/control/locations/{location_id}/targets/{target}/checks/{binding_key}/sql",
+            get(crate::api::_helpers::resources::person_checks::sql),
+        )
         .layer(DefaultBodyLimit::max(PASSWORD_BODY_BYTES))
 }
 

crates/sqlbuild-orchestration/src/api/_helpers/resources/mod.rs

@@ -5,6 +5,7 @@ pub(crate) mod client;
 pub(crate) mod docker_image;
 pub(crate) mod location_health;
 pub(crate) mod location_work;
+pub(crate) mod person_checks;
 pub(crate) mod person_location_work;
 pub(crate) mod person_node_sql;
 pub(crate) mod person_operations;

crates/sqlbuild-orchestration/src/api/_helpers/resources/person_checks.rs

@@ -0,0 +1,81 @@
+//! Check reads use live person grants; SQL needs its own permission and is audited.
+
+use axum::extract::{Path, Query, State};
+use axum::{Extension, Json};
+use uuid::Uuid;
+
+use crate::api::errors::ApiError;
+use crate::api::models::ReadQuery;
+use crate::credentials::models::{AuditContext, AuthenticatedPerson, DefaultRole};
+use crate::store::models::ControlStore;
+use crate::warehouse_metadata::main::read_person_check::read_person_check;
+use crate::warehouse_metadata::main::read_person_check_sql::read_person_check_sql;
+use crate::warehouse_metadata::main::read_person_checks::read_person_checks;
+use crate::warehouse_metadata::models::{CheckResult, CheckSql};
+
+#[utoipa::path(get, path = "/api/control/locations/{location_id}/targets/{target}/checks", operation_id = "listPersonChecks",
+    params(("location_id" = Uuid, Path), ("target" = String, Path)),
+    responses((status = 200, body = Vec<CheckResult>, description = "The newest result of every check"),
+        (status = 401, description = "Session rejected"),
+        (status = 403, body = crate::api::models::ApiErrorBody)), security(("session" = []), ("cliSession" = [])))]
+pub(crate) async fn list(
+    (State(store), Extension(context)): (State<ControlStore>, Extension<AuditContext>),
+    Extension(default_role): Extension<DefaultRole>,
+    Path((location_id, target)): Path<(Uuid, String)>,
+    Extension(AuthenticatedPerson(principal, _)): Extension<AuthenticatedPerson>,
+) -> Result<Json<Vec<CheckResult>>, ApiError> {
+    Ok(Json(
+        read_person_checks(
+            &store,
+            (&context, principal),
+            (location_id, &target),
+            default_role,
+        )
+        .await?,
+    ))
+}
+
+#[utoipa::path(get, path = "/api/control/locations/{location_id}/targets/{target}/checks/{binding_key}", operation_id = "readPersonCheckHistory",
+    params(("location_id" = Uuid, Path), ("target" = String, Path), ("binding_key" = String, Path),
+        ("limit" = Option<u32>, Query, description = "Maximum results, newest first; defaults to 50, capped at 1000")),
+    responses((status = 200, body = Vec<CheckResult>, description = "Empty for an unknown check"),
+        (status = 401, description = "Session rejected"),
+        (status = 403, body = crate::api::models::ApiErrorBody)), security(("session" = []), ("cliSession" = [])))]
+pub(crate) async fn history(
+    (State(store), Extension(context)): (State<ControlStore>, Extension<AuditContext>),
+    Extension(default_role): Extension<DefaultRole>,
+    (Path((location_id, target, binding_key)), Query(options)): (
+        Path<(Uuid, String, String)>,
+        Query<ReadQuery>,
+    ),
+    Extension(AuthenticatedPerson(principal, _)): Extension<AuthenticatedPerson>,
+) -> Result<Json<Vec<CheckResult>>, ApiError> {
+    Ok(Json(
+        read_person_check(
+            &store,
+            (&context, principal),
+            (location_id, &target, &binding_key),
+            (options.limit.unwrap_or(50), default_role),
+        )
+        .await?,
+    ))
+}
+
+#[utoipa::path(get, path = "/api/control/locations/{location_id}/targets/{target}/checks/{binding_key}/sql", operation_id = "readPersonCheckSql",
+    params(("location_id" = Uuid, Path), ("target" = String, Path), ("binding_key" = String, Path)),
+    responses((status = 200, body = Option<CheckSql>), (status = 401, description = "Session rejected"),
+        (status = 403, body = crate::api::models::ApiErrorBody)), security(("session" = []), ("cliSession" = [])))]
+pub(crate) async fn sql(
+    (State(store), Extension(context)): (State<ControlStore>, Extension<AuditContext>),
+    Path((location_id, target, binding_key)): Path<(Uuid, String, String)>,
+    Extension(AuthenticatedPerson(principal, _)): Extension<AuthenticatedPerson>,
+) -> Result<Json<Option<CheckSql>>, ApiError> {
+    Ok(Json(
+        read_person_check_sql(
+            &store,
+            (&context, principal),
+            (location_id, &target, &binding_key),
+        )
+        .await?,
+    ))
+}

crates/sqlbuild-orchestration/src/api/models.rs

@@ -5,9 +5,9 @@ use serde::{Deserialize, Serialize};
 use crate::api::_helpers::authentication::password_sessions;
 use crate::api::_helpers::authentication::{cli_login, oidc};
 use crate::api::_helpers::resources::{
-    administrators, audit, changes, location_health, location_work, person_location_work,
-    person_node_sql, person_operations, run_reads, runs, snapshots, trigger_reads,
-    warehouse_metadata,
+    administrators, audit, changes, location_health, location_work, person_checks,
+    person_location_work, person_node_sql, person_operations, run_reads, runs, snapshots,
+    trigger_reads, warehouse_metadata,
 };
 
 #[derive(Debug, utoipa::OpenApi)]
@@ -24,6 +24,9 @@ use crate::api::_helpers::resources::{
     person_operations::statistics,
     person_operations::fingerprint,
     person_operations::node_status,
+    person_checks::list,
+    person_checks::history,
+    person_checks::sql,
     person_location_work::request,
     person_location_work::result,
     person_node_sql::read,

crates/sqlbuild-orchestration/src/store/_helpers/migration.rs

@@ -20,7 +20,9 @@ pub(crate) fn verify_schema(rows: &[Row], digest: &str) -> Result<(), ControlErr
         .any(|row| row.get("checksum").and_then(|value| value.as_str()) != Some(digest))
     {
         return Err(ControlError::Schema(
-            "control store schema checksum mismatch".into(),
+            "control store schema checksum mismatch; recreate the control store, because \
+             pre-release schemas are not upgraded"
+                .into(),
         ));
     }
     Ok(())