feat: read check evidence through the control API

benchmarks/duckshop/edge_cases/orchestration/check_identity.json

@@ -1,14 +1,59 @@
 {
   "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"}
+    {
+      "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"}
+    {
+      "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' 🧾 */",
+      "evidence_json": "[{\"amount\":1.5,\"order_id\":\"o-1\"},{\"is_late\":true,\"order_id\":\"o-2\"}]",
+      "evidence_count": 2,
+      "evidence_truncated": "false"
+    },
+    {
+      "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",
+      "evidence_json": "[\"o-9 malformed\"]"
+    }
   ]
 }

clients/typescript/src/schema.d.ts

@@ -242,6 +242,22 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/control/locations/{location_id}/targets/{target}/checks/{binding_key}/results/{event_id}/evidence": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["readPersonCheckEvidence"];
+        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;
@@ -817,6 +833,17 @@ export interface components {
         ChangeNotice: {
             topic: string;
         };
+        /** @description One result's stored evidence rows; `view.evidence` reads them, audited. */
+        CheckEvidence: {
+            binding_key: string;
+            /** @description Every row key, in sorted order; the warehouse stores rows with sorted keys. */
+            columns: string[];
+            /** Format: uuid */
+            event_id: string;
+            /** @description Scalar cells aligned to `columns`; a row without a key holds null there. */
+            rows: Record<string, never>[][];
+            truncated?: string | null;
+        };
         /** @description One stored check result. Its SQL, error texts and evidence rows need their own permissions. */
         CheckResult: {
             attached_column_name?: string | null;
@@ -2301,6 +2328,45 @@ export interface operations {
             };
         };
     };
+    readPersonCheckEvidence: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                location_id: string;
+                target: string;
+                binding_key: string;
+                event_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": null | components["schemas"]["CheckEvidence"];
+                };
+            };
+            /** @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;

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

@@ -121,6 +121,10 @@ pub(crate) fn person_routes() -> Router<ControlStore> {
             "/api/control/locations/{location_id}/targets/{target}/checks/{binding_key}/sql",
             get(crate::api::_helpers::resources::person_checks::sql),
         )
+        .route(
+            "/api/control/locations/{location_id}/targets/{target}/checks/{binding_key}/results/{event_id}/evidence",
+            get(crate::api::_helpers::resources::person_checks::evidence),
+        )
         .layer(DefaultBodyLimit::max(PASSWORD_BODY_BYTES))
 }
 

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

@@ -1,17 +1,18 @@
-//! Check reads use live person grants; SQL needs its own permission and is audited.
+//! Check reads use live person grants; SQL and evidence need their own permissions and are 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::api::models::{CheckResultPath, 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_evidence::read_person_check_evidence;
 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};
+use crate::warehouse_metadata::models::{CheckEvidence, 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)),
@@ -79,3 +80,23 @@ pub(crate) async fn sql(
         .await?,
     ))
 }
+
+#[utoipa::path(get, path = "/api/control/locations/{location_id}/targets/{target}/checks/{binding_key}/results/{event_id}/evidence", operation_id = "readPersonCheckEvidence",
+    params(("location_id" = Uuid, Path), ("target" = String, Path), ("binding_key" = String, Path), ("event_id" = Uuid, Path)),
+    responses((status = 200, body = Option<CheckEvidence>), (status = 401, description = "Session rejected"),
+        (status = 403, body = crate::api::models::ApiErrorBody)), security(("session" = []), ("cliSession" = [])))]
+pub(crate) async fn evidence(
+    (State(store), Extension(context)): (State<ControlStore>, Extension<AuditContext>),
+    Path(path): Path<CheckResultPath>,
+    Extension(AuthenticatedPerson(principal, _)): Extension<AuthenticatedPerson>,
+) -> Result<Json<Option<CheckEvidence>>, ApiError> {
+    Ok(Json(
+        read_person_check_evidence(
+            &store,
+            (&context, principal),
+            (path.location_id, &path.target, &path.binding_key),
+            path.event_id,
+        )
+        .await?,
+    ))
+}

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

@@ -27,6 +27,7 @@ use crate::api::_helpers::resources::{
     person_checks::list,
     person_checks::history,
     person_checks::sql,
+    person_checks::evidence,
     person_location_work::request,
     person_location_work::result,
     person_node_sql::read,
@@ -86,6 +87,14 @@ pub(crate) struct RunRecallQuery {
     pub(crate) limit: Option<u32>,
 }
 
+#[derive(Debug, Deserialize)]
+pub(crate) struct CheckResultPath {
+    pub(crate) location_id: uuid::Uuid,
+    pub(crate) target: String,
+    pub(crate) binding_key: String,
+    pub(crate) event_id: uuid::Uuid,
+}
+
 #[derive(Debug, Deserialize)]
 pub(crate) struct RunRecallPath {
     pub(crate) location_id: uuid::Uuid,

crates/sqlbuild-orchestration/src/warehouse_metadata/_helpers/checks.rs

@@ -3,13 +3,16 @@
 use std::collections::BTreeSet;
 
 use serde::Deserialize;
+use serde_json::json;
 use uuid::Uuid;
 
-use crate::credentials::models::{Action, PermissionScope};
+use crate::authorization::main::authorize_person::authorize_person;
+use crate::credentials::main::audit::append_audit::append_audit;
+use crate::credentials::models::{Action, AuditContext, DefaultRole, PermissionScope};
 use crate::store::errors::ControlError;
-use crate::store::main::{query::query, query_records::query_records};
+use crate::store::main::{commit::commit, query::query, query_records::query_records};
 use crate::store::models::{ControlTransaction, Parameter};
-use crate::warehouse_metadata::models::WarehouseAuditRecord;
+use crate::warehouse_metadata::models::{CheckEvidence, WarehouseAuditRecord};
 
 #[derive(Deserialize)]
 pub(crate) struct AuditRow {
@@ -31,6 +34,62 @@ pub(crate) async fn latest_results(
         vec![Parameter::Id(location_id), Parameter::Text(target.into())]).await
 }
 
+/// One result of one check.
+pub(crate) async fn check_result(
+    transaction: ControlTransaction,
+    (location_id, target, binding_key): (Uuid, &str, &str),
+    event_id: Uuid,
+) -> Result<(ControlTransaction, Option<AuditRow>), ControlError> {
+    let (transaction, mut rows) = query_records(
+        transaction,
+        "SELECT event_id,record_json AS record FROM sqb_warehouse_audit_results \
+         WHERE location_id=$1 AND target=$2 AND binding_key=$3 AND event_id=$4",
+        vec![
+            Parameter::Id(location_id),
+            Parameter::Text(target.into()),
+            Parameter::Text(binding_key.into()),
+            Parameter::Id(event_id),
+        ],
+    )
+    .await?;
+    Ok((transaction, rows.pop()))
+}
+
+/// Stored evidence rows as columns in sorted key order and aligned cells.
+pub(crate) fn evidence(row: AuditRow) -> Result<CheckEvidence, ControlError> {
+    let objects: Vec<serde_json::Map<String, serde_json::Value>> = row
+        .record
+        .evidence_json
+        .as_deref()
+        .map(serde_json::from_str)
+        .transpose()
+        .map_err(|_| {
+            ControlError::Schema("stored check evidence is not an array of objects".into())
+        })?
+        .unwrap_or_default();
+    let columns: Vec<String> = objects
+        .iter()
+        .flat_map(|object| object.keys().cloned())
+        .collect::<BTreeSet<String>>()
+        .into_iter()
+        .collect();
+    let mut rows: Vec<Vec<serde_json::Value>> = Vec::with_capacity(objects.len());
+    for object in &objects {
+        let mut cells: Vec<serde_json::Value> = Vec::with_capacity(columns.len());
+        for column in &columns {
+            cells.push(object.get(column).cloned().unwrap_or_default());
+        }
+        rows.push(cells);
+    }
+    Ok(CheckEvidence {
+        event_id: row.event_id,
+        binding_key: row.record.binding_key,
+        columns,
+        rows,
+        truncated: row.record.evidence_truncated,
+    })
+}
+
 /// One check's results, newest first.
 pub(crate) async fn check_results(
     transaction: ControlTransaction,
@@ -44,8 +103,39 @@ pub(crate) async fn check_results(
             Parameter::Integer(i64::from(limit.clamp(1, 1000)))]).await
 }
 
+/// Authorizes `action` on the row's check, projects the row, and audits the read before commit.
+pub(crate) async fn sensitive_check_read<T>(
+    (transaction, credentials): (ControlTransaction, (&AuditContext, Uuid)),
+    (location_id, target, binding_key): (Uuid, &str, &str),
+    (row, action, audit_action): (Option<AuditRow>, Action, &str),
+    project: impl FnOnce(AuditRow) -> Result<T, ControlError>,
+) -> Result<Option<T>, ControlError> {
+    let attached = row
+        .as_ref()
+        .and_then(|row| row.record.attached_target_name.as_deref());
+    let (transaction, scope) =
+        check_scope(transaction, (location_id, target, attached), action).await?;
+    let (transaction, context) =
+        authorize_person(transaction, credentials, &scope, DefaultRole::None).await?;
+    let event_id = row.as_ref().map(|row| row.event_id);
+    let result = row.map(project).transpose()?;
+    let transaction = append_audit(
+        transaction,
+        &context,
+        (Uuid::now_v7(), audit_action),
+        (
+            json!(scope),
+            json!(null),
+            json!({"binding_key": binding_key, "event_id": event_id, "found": result.is_some()}),
+        ),
+    )
+    .await?;
+    commit(transaction).await?;
+    Ok(result)
+}
+
 /// The check's own node when the current snapshot has it, otherwise every current node.
-pub(crate) async fn check_scope(
+async fn check_scope(
     transaction: ControlTransaction,
     (location_id, target, attached): (Uuid, &str, Option<&str>),
     action: Action,

crates/sqlbuild-orchestration/src/warehouse_metadata/main/mod.rs

@@ -10,6 +10,7 @@ pub mod ingest_statistics;
 pub(crate) mod prune_statistics;
 pub mod read_person_catalog;
 pub mod read_person_check;
+pub mod read_person_check_evidence;
 pub mod read_person_check_sql;
 pub mod read_person_checks;
 pub mod read_person_fingerprint;

crates/sqlbuild-orchestration/src/warehouse_metadata/main/read_person_check_evidence.rs

@@ -0,0 +1,27 @@
+//! Live evidence permission on the check's node, one result's rows and the sensitive-read audit share one writer fence.
+
+use uuid::Uuid;
+
+use crate::credentials::models::{Action, AuditContext};
+use crate::store::errors::ControlError;
+use crate::store::main::begin::begin;
+use crate::store::models::{ControlStore, TransactionMode};
+use crate::warehouse_metadata::_helpers::checks::{check_result, evidence, sensitive_check_read};
+use crate::warehouse_metadata::models::CheckEvidence;
+
+pub async fn read_person_check_evidence(
+    store: &ControlStore,
+    credentials: (&AuditContext, Uuid),
+    check: (Uuid, &str, &str),
+    event_id: Uuid,
+) -> Result<Option<CheckEvidence>, ControlError> {
+    let (transaction, row) =
+        check_result(begin(store, TransactionMode::Write).await?, check, event_id).await?;
+    sensitive_check_read(
+        (transaction, credentials),
+        check,
+        (row, Action::ViewEvidence, "evidence.read"),
+        evidence,
+    )
+    .await
+}