feat: add maintenance history endpoint (#1318)

* feat: read check evidence through the control API

People with view.evidence on a check's model can read the sample rows stored with one of its results. Columns are the rows' keys in sorted order, the order the warehouse stores them in, and a row without a key holds null there. Every read is audited, and a read whose audit cannot be written discloses nothing. The SQL and evidence reads now share one authorize, read and audit path.

* feat: read maintenance history through the control API

People with view on a target can read its recorded model moves, every step of their old-name views, and janitor cleanups, newest moves first. Filtering by model returns only moves into that model and their views, using new indexes on the destination model and the move's event. Check and maintenance reads now live in their own warehouse-history domain, apart from metadata ingestion.

* test: keep the worker contract's scheduler lease alive

The worker contract held one 30 second scheduler lease without renewing it,
so on a slow runner its second claim came after expiry and was fenced.
Renew it in the background, as a running scheduler does.

Author: kvlonge

benchmarks/duckshop/edge_cases/orchestration/maintenance_history.json

@@ -0,0 +1,81 @@
+{
+  "migrations": [
+    {
+      "event_id": "move-orders-1",
+      "destination_model": "orders",
+      "origin_model": "orders_v1",
+      "origin_name": "orders_v1",
+      "decision": "migrate",
+      "created_at": "2026-02-01T04:05:06Z"
+    },
+    {
+      "event_id": "move-orders-2",
+      "destination_model": "orders",
+      "origin_model": null,
+      "origin_name": "orders_🧾",
+      "decision": "renamed",
+      "discovery": "automatic",
+      "created_at": "2026-02-03T04:05:06Z"
+    },
+    {
+      "event_id": "move-customers-1",
+      "destination_model": "customers",
+      "origin_model": "clients",
+      "origin_name": "clients",
+      "decision": "superseded_replace",
+      "created_at": "2026-02-02T04:05:06Z"
+    }
+  ],
+  "old_name_views": [
+    {
+      "event_id": "view-orders-1",
+      "migration_event_id": "move-orders-2",
+      "destination_model": "orders",
+      "event_type": "required",
+      "created_at": "2026-02-03T04:05:06Z"
+    },
+    {
+      "event_id": "view-orders-2",
+      "migration_event_id": "move-orders-2",
+      "destination_model": "orders",
+      "event_type": "view_created",
+      "created_at": "2026-02-03T04:05:07Z",
+      "column_aliases": "{\"order_id\":\"legacy_order_id\"}"
+    },
+    {
+      "event_id": "view-customers-1",
+      "migration_event_id": "move-customers-1",
+      "destination_model": "customers",
+      "event_type": "required",
+      "created_at": "2026-02-02T04:05:06Z"
+    },
+    {
+      "event_id": "view-orders-old-1",
+      "migration_event_id": "move-orders-1",
+      "destination_model": "orders",
+      "event_type": "required",
+      "created_at": "2026-02-01T04:05:06Z"
+    }
+  ],
+  "janitor_events": [
+    {
+      "event_id": "cleanup-1",
+      "event_type": "archive",
+      "occurred_at": "2026-02-01T05:05:06Z"
+    },
+    {
+      "event_id": "cleanup-2",
+      "event_type": "delete",
+      "occurred_at": "2026-02-04T05:05:06Z"
+    }
+  ],
+  "preview_old_name_views": [
+    {
+      "event_id": "view-preview-1",
+      "migration_event_id": "move-orders-2",
+      "destination_model": "orders",
+      "event_type": "view_dropped",
+      "created_at": "2026-02-05T04:05:06Z"
+    }
+  ]
+}

clients/typescript/src/schema.d.ts

@@ -322,6 +322,22 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/control/locations/{location_id}/targets/{target}/maintenance": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get: operations["readPersonMaintenance"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/control/locations/{location_id}/targets/{target}/node-status": {
         parameters: {
             query?: never;
@@ -1121,6 +1137,14 @@ export interface components {
             /** Format: uuid */
             session_id: string;
         };
+        /** @description Recorded moves, their old-name view steps and janitor cleanups, newest moves first. */
+        MaintenanceHistory: {
+            /** @description Empty when the history is for one model; cleanups are not tied to models. */
+            janitor_events: components["schemas"]["WarehouseJanitorRecord"][];
+            migrations: components["schemas"]["WarehouseMigrationRecord"][];
+            /** @description Every step recorded for the listed moves, oldest first; same-time steps are not in step order. */
+            old_name_views: components["schemas"]["WarehouseOldNameRecord"][];
+        };
         /** @description One bounded page of one state table from the registered reader of a published generation. */
         MetadataBatch: {
             /** Format: int64 */
@@ -1731,12 +1755,81 @@ export interface components {
          * @enum {string}
          */
         WarehouseHistoryKind: "fingerprints" | "source_freshness" | "audit_results" | "janitor_events" | "migrations" | "old_name_views" | "microbatches" | "catalog" | "statistics";
+        /** @description Warehouse cleanup facts do not authorize control-plane deletion or worker recovery. */
+        WarehouseJanitorRecord: {
+            archive_name: string;
+            archive_qualified_name: string;
+            /** Format: date-time */
+            archived_at: string;
+            event_id: string;
+            event_type: string;
+            /** Format: date-time */
+            occurred_at: string;
+            original_name?: string | null;
+            original_qualified_name?: string | null;
+            relation_database?: string | null;
+            relation_schema: string;
+            relation_type?: string | null;
+            run_id: string;
+            /** Format: int64 */
+            schema_version: number;
+            state_database?: string | null;
+            state_schema: string;
+        };
+        /** @description Model-move history is evidence, not authority to migrate a warehouse relation. */
+        WarehouseMigrationRecord: {
+            /** Format: date-time */
+            created_at: string;
+            decision: string;
+            destination_database?: string | null;
+            destination_model: string;
+            destination_name: string;
+            destination_schema: string;
+            discovery: string;
+            event_id: string;
+            origin_database?: string | null;
+            origin_model?: string | null;
+            origin_name: string;
+            origin_schema?: string | null;
+            origin_version_hash: string;
+            run_id: string;
+            state_database?: string | null;
+            state_schema: string;
+            target_name?: string | null;
+        };
         WarehouseMirrorCursor: {
             /** Format: uuid */
             event_id: string;
             /** Format: date-time */
             observed_at: string;
         };
+        /** @description Preserve nullable compatibility-view facts without projecting live warehouse existence. */
+        WarehouseOldNameRecord: {
+            archive_name?: string | null;
+            column_aliases?: string | null;
+            /** Format: date-time */
+            created_at: string;
+            destination_model: string;
+            drop_reason?: string | null;
+            event_id: string;
+            event_type: string;
+            /** Format: date-time */
+            expires_at?: string | null;
+            grants_copied?: string | null;
+            migration_event_id: string;
+            new_database?: string | null;
+            new_name: string;
+            new_schema: string;
+            old_database?: string | null;
+            old_name: string;
+            old_schema?: string | null;
+            run_id: string;
+            state_database?: string | null;
+            state_schema: string;
+            target_name?: string | null;
+            view_retention?: string | null;
+            view_sql?: string | null;
+        };
         /** @description Physical namespace of SQLBuild's source-freshness state table, never a source query. */
         WarehouseStateLocation: {
             database?: string | null;
@@ -2547,6 +2640,48 @@ export interface operations {
             };
         };
     };
+    readPersonMaintenance: {
+        parameters: {
+            query?: {
+                /** @description Only moves into this model, and no janitor events */
+                node?: string;
+                /** @description Maximum moves and janitor events each; defaults to 100, capped at 1000 */
+                limit?: number;
+            };
+            header?: never;
+            path: {
+                location_id: string;
+                target: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["MaintenanceHistory"];
+                };
+            };
+            /** @description Session rejected */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiErrorBody"];
+                };
+            };
+        };
+    };
     readPersonNodeStatus: {
         parameters: {
             query: {

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

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

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

@@ -7,6 +7,7 @@ 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_maintenance;
 pub(crate) mod person_node_sql;
 pub(crate) mod person_operations;
 pub(crate) mod router;

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

@@ -8,11 +8,11 @@ use crate::api::errors::ApiError;
 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::{CheckEvidence, CheckResult, CheckSql};
+use crate::warehouse_history::main::read_person_check::read_person_check;
+use crate::warehouse_history::main::read_person_check_evidence::read_person_check_evidence;
+use crate::warehouse_history::main::read_person_check_sql::read_person_check_sql;
+use crate::warehouse_history::main::read_person_checks::read_person_checks;
+use crate::warehouse_history::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)),

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

@@ -0,0 +1,34 @@
+//! Maintenance history reads use live person grants over the whole target.
+
+use axum::extract::{Path, Query, State};
+use axum::{Extension, Json};
+use uuid::Uuid;
+
+use crate::api::errors::ApiError;
+use crate::credentials::models::{AuditContext, AuthenticatedPerson, DefaultRole};
+use crate::store::models::ControlStore;
+use crate::warehouse_history::main::read_person_maintenance::read_person_maintenance;
+use crate::warehouse_history::models::{MaintenanceHistory, MaintenanceQuery};
+
+#[utoipa::path(get, path = "/api/control/locations/{location_id}/targets/{target}/maintenance", operation_id = "readPersonMaintenance",
+    params(("location_id" = Uuid, Path), ("target" = String, Path),
+        ("node" = Option<String>, Query, description = "Only moves into this model, and no janitor events"),
+        ("limit" = Option<u32>, Query, description = "Maximum moves and janitor events each; defaults to 100, capped at 1000")),
+    responses((status = 200, body = MaintenanceHistory), (status = 401, description = "Session rejected"),
+        (status = 403, body = crate::api::models::ApiErrorBody)), security(("session" = []), ("cliSession" = [])))]
+pub(crate) async fn read(
+    (State(store), Extension(context)): (State<ControlStore>, Extension<AuditContext>),
+    Extension(default_role): Extension<DefaultRole>,
+    (Path((location_id, target)), Query(options)): (Path<(Uuid, String)>, Query<MaintenanceQuery>),
+    Extension(AuthenticatedPerson(principal, _)): Extension<AuthenticatedPerson>,
+) -> Result<Json<MaintenanceHistory>, ApiError> {
+    Ok(Json(
+        read_person_maintenance(
+            &store,
+            (&context, principal),
+            (location_id, &target, &options),
+            default_role,
+        )
+        .await?,
+    ))
+}

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

@@ -6,8 +6,8 @@ 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_checks,
-    person_location_work, person_node_sql, person_operations, run_reads, runs, snapshots,
-    trigger_reads, warehouse_metadata,
+    person_location_work, person_maintenance, person_node_sql, person_operations, run_reads, runs,
+    snapshots, trigger_reads, warehouse_metadata,
 };
 
 #[derive(Debug, utoipa::OpenApi)]
@@ -28,6 +28,7 @@ use crate::api::_helpers::resources::{
     person_checks::history,
     person_checks::sql,
     person_checks::evidence,
+    person_maintenance::read,
     person_location_work::request,
     person_location_work::result,
     person_node_sql::read,

crates/sqlbuild-orchestration/src/lib.rs

@@ -12,6 +12,7 @@ pub mod scheduler;
 pub mod sensors;
 pub mod snapshots;
 pub mod store;
+pub mod warehouse_history;
 pub mod warehouse_metadata;
 pub mod webhooks;
 pub mod worker;

crates/sqlbuild-orchestration/src/store/schema.sql

@@ -429,6 +429,7 @@ CREATE TABLE sqb_warehouse_migrations (
     scan_id {uuid}
 );
 CREATE INDEX sqb_migrations_namespace ON sqb_warehouse_migrations (location_id,target,state_database,state_schema,observed_at,event_id);
+CREATE INDEX sqb_migrations_destination ON sqb_warehouse_migrations (location_id,target,destination_model,observed_at,event_id);
 CREATE TABLE sqb_warehouse_old_name_views (
     event_id {uuid} PRIMARY KEY,
     location_id {uuid} NOT NULL REFERENCES sqb_locations(location_id),
@@ -444,6 +445,7 @@ CREATE TABLE sqb_warehouse_old_name_views (
     scan_id {uuid}
 );
 CREATE INDEX sqb_old_name_views_namespace ON sqb_warehouse_old_name_views (location_id,target,state_database,state_schema,observed_at,event_id);
+CREATE INDEX sqb_old_name_views_migration ON sqb_warehouse_old_name_views (location_id,target,migration_event_id,observed_at,event_id);
 CREATE TABLE sqb_warehouse_microbatches (
     event_id {uuid} PRIMARY KEY,
     location_id {uuid} NOT NULL REFERENCES sqb_locations(location_id),

…rc/warehouse_metadata/_helpers/checks.rs …src/warehouse_history/_helpers/checks.rscrates/sqlbuild-orchestration/src/warehouse_metadata/_helpers/checks.rs renamed to crates/sqlbuild-orchestration/src/warehouse_history/_helpers/checks.rs crates/sqlbuild-orchestration/src/warehouse_metadata/_helpers/checks.rs renamed to crates/sqlbuild-orchestration/src/warehouse_history/_helpers/checks.rs

@@ -12,7 +12,8 @@ use crate::credentials::models::{Action, AuditContext, DefaultRole, PermissionSc
 use crate::store::errors::ControlError;
 use crate::store::main::{commit::commit, query::query, query_records::query_records};
 use crate::store::models::{ControlTransaction, Parameter};
-use crate::warehouse_metadata::models::{CheckEvidence, WarehouseAuditRecord};
+use crate::warehouse_history::models::CheckEvidence;
+use crate::warehouse_metadata::models::WarehouseAuditRecord;
 
 #[derive(Deserialize)]
 pub(crate) struct AuditRow {