@feltdb/core 0.8.8 → 0.9.1

package/dist/create/server-source/crates/feltdb-server/src/main.rs

@@ -62,7 +62,7 @@ use feltdb::{
     },
     workload::{CreateWorkload, WorkloadStore},
     AtomicMutation, DatabaseSnapshot, FeltDb, FlowError, JsonCasResult, Operation,
-    PeerAdvertisement, PeerId, RecordPrecondition, StateTriggerStore, StoredRow,
+    PeerAdvertisement, PeerId, RecordPrecondition, StateRevision, StateTriggerStore, StoredRow,
 };
 use feltdb_server::{
     app_state::{AppState, BoundedQueryCursor},
@@ -82,13 +82,14 @@ use feltdb_server::{
     cluster::{ClusterConfig, ClusterStore, MembershipProposal, ProposalPhase},
     connections::{ConnectionProvider, ConnectionStatus, ConnectionStore, SecretReference},
     content::ContentStore,
+    control_plane,
     identity::IdentityStore,
     key_management::{create_key, list_keys, revoke_key},
     key_provider::provider_from_environment,
     leases::LeaseStore,
     metrics::Metrics,
     portable_bundle::{BundleArtifact, BundleStore, ExportOptions, ImportMode, PortableBundle},
-    principals::{PrincipalKind, PrincipalStore},
+    principals::{PrincipalKind, PrincipalStatus, PrincipalStore},
     providers::{ProviderManifest, ProviderStatus, ProviderStore},
     releases::{
         provider_for, AuthorizedDeploymentContext, DeploymentPlan, DeploymentProfile,
@@ -7512,17 +7513,29 @@ async fn get_state_version(
         json!({"application_id":target.application_id,"revision_id":contract.revision_id,"schema_version":contract.state.schema.schema_version,"state_version":state.db.sequence()?,"causal_cursor":state.db.operation_versions()?,"state_namespace":contract.environment.state_namespace}),
     ))
 }
+fn require_bound_tenant(headers: &HeaderMap, tenant: &str) -> Result<(), ApiError> {
+    let Some(bound) = headers.get("feltdb-tenant-id") else { return Ok(()); };
+    if bound.to_str().ok() == Some(tenant) { return Ok(()); }
+    Err(ApiError(StatusCode::FORBIDDEN, json!({
+        "code":"AUTHORITY_SCOPE_MISMATCH",
+        "message":"request tenant does not match the authenticated application authority",
+        "http_status":403
+    }).to_string()))
+}
+
 async fn execute_canonical_query(
     State(state): State<AppState>,
     Extension(principal): Extension<Principal>,
+    headers: HeaderMap,
     Json(input): Json<CanonicalQueryRequest>,
 ) -> Result<Json<Value>, ApiError> {
-    let _ = application_scope(
+    let tenant = application_scope(
         &state,
         &principal.key_id,
         &input.application_id,
         "state:read",
     )?;
+    require_bound_tenant(&headers, &tenant)?;
     let contract = revision_contract(
         &state,
         &principal.key_id,
@@ -7717,6 +7730,7 @@ async fn execute_revision_recovery(
 async fn execute_canonical_transaction(
     State(state): State<AppState>,
     Extension(principal): Extension<Principal>,
+    headers: HeaderMap,
     Json(mut input): Json<CanonicalTransactionRequest>,
 ) -> Result<Json<Value>, ApiError> {
     let tenant = application_scope(
@@ -7725,6 +7739,7 @@ async fn execute_canonical_transaction(
         &input.application_id,
         "state:write",
     )?;
+    require_bound_tenant(&headers, &tenant)?;
     let contract = revision_contract(
         &state,
         &principal.key_id,
@@ -7732,6 +7747,13 @@ async fn execute_canonical_transaction(
         &input.revision_id,
         &input.environment,
     )?;
+    if !input.transaction.tenant_id.is_empty() && input.transaction.tenant_id != tenant {
+        return Err(ApiError(StatusCode::FORBIDDEN, json!({
+            "code":"AUTHORITY_SCOPE_MISMATCH",
+            "message":"transaction tenant does not match the bound authority",
+            "http_status":403
+        }).to_string()));
+    }
     input.transaction.tenant_id = tenant.clone();
     input.transaction.application_id = input.application_id.clone();
     input.transaction.revision_id = contract.revision_id.clone();
@@ -8675,6 +8697,60 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
         )
         .route("/v1/schema", get(get_state_schema))
         .route("/v1/application", get(discover_application))
+        .route(
+            "/v1/control-plane/capabilities",
+            get(control_plane_capabilities),
+        )
+        .route("/v1/control-plane/overview", get(control_plane_overview))
+        .route("/v1/control-plane/actions", get(control_plane_actions))
+        .route("/v1/control-plane/indexes", get(control_plane_indexes))
+        .route(
+            "/v1/control-plane/indexes/rebuild",
+            axum::routing::post(control_plane_rebuild_index),
+        )
+        .route(
+            "/v1/control-plane/operations",
+            get(control_plane_operations),
+        )
+        .route(
+            "/v1/control-plane/replication",
+            get(control_plane_replication),
+        )
+        .route(
+            "/v1/control-plane/applications",
+            get(control_plane_applications),
+        )
+        .route("/v1/control-plane/developer", get(control_plane_developer))
+        .route(
+            "/v1/control-plane/transactions",
+            get(control_plane_transactions),
+        )
+        .route(
+            "/v1/control-plane/transactions/{transaction_id}",
+            get(control_plane_transaction),
+        )
+        .route(
+            "/v1/control-plane/provenance/{collection}/{id}",
+            get(control_plane_record_provenance),
+        )
+        .route("/v1/control-plane/agents", get(control_plane_agents))
+        .route("/v1/control-plane/agents/{agent_id}", get(control_plane_agent))
+        .route("/v1/state/resources", get(state_resources))
+        .route(
+            "/v1/state/resources/{resource}/history",
+            get(state_resource_history),
+        )
+        .route("/v1/state/revisions/{id}", get(state_revision))
+        .route("/v1/state/diff", axum::routing::post(state_diff))
+        .route("/v1/state/conflicts", axum::routing::post(state_conflicts))
+        .route(
+            "/v1/state/reconciliation/plan",
+            axum::routing::post(state_reconciliation_plan),
+        )
+        .route(
+            "/v1/state/reconciliation/execute",
+            axum::routing::post(state_reconciliation_execute),
+        )
         .route("/v1/application/schema", get(inspect_application_schema))
         .route("/v1/data/{collection}", get(inspect_collection))
         .route("/v1/data/{collection}/{id}", get(inspect_record))
@@ -9329,6 +9405,16 @@ async fn authenticate(
     let path = request.uri().path();
     let required = if path == "/events" {
         "events:read"
+    } else if path == "/v1/state/diff"
+        || path == "/v1/state/conflicts"
+        || path == "/v1/state/reconciliation/plan"
+    {
+        // Describing state is reading it. These are POSTs because they take
+        // three revision identities and a plan, not because they change
+        // anything: the diff, the classification and the plan preview are all
+        // pure. Letting the method decide the capability would make inspecting
+        // a conflict require permission to resolve one.
+        "state:read"
     } else if path == "/sync/pull" || path == "/sync/snapshot" {
         "sync:read"
     } else if path == "/sync/push" {
@@ -13554,6 +13640,1285 @@ fn record_response(row: StoredRow) -> RecordResponse {
     }
 }
 
+// ============================================================================
+// The human control plane
+// ============================================================================
+//
+// Studio is FeltDB's human surface. It is not a second implementation of
+// FeltDB, and these routes are what make that possible: every one of them is a
+// public, authorized FeltDB capability that an application or an agent may call
+// on exactly the same terms. Nothing here reads a state file, reaches into
+// storage, or offers a mutation path Studio alone can use.
+//
+// The rule this section exists to hold: **if Studio can perform it, the
+// operation is a FeltDB capability**. When it is not one, the capability
+// declaration says so, and the interface renders it unavailable rather than
+// drawing a control that cannot work.
+
+/// The state store, opened through the canonical facade.
+///
+/// Deliberately the facade rather than `StateStore::with_feltdb`: the state
+/// subsystem names one way in, and a second entry point here would be the first
+/// step toward the control plane growing its own copy of the state model.
+fn control_plane_state_store(state: &AppState) -> Result<feltdb::StateStore, ApiError> {
+    feltdb::FeltDBStateSystem::create_store(&Arc::new(state.db.clone()))
+        .map_err(|error| ApiError(StatusCode::INTERNAL_SERVER_ERROR, error))
+}
+
+fn control_plane_error(status: StatusCode, code: &str, message: impl Into<String>) -> ApiError {
+    ApiError::structured(status, json!({"code": code, "message": message.into()}))
+}
+
+/// Reads a revision, or says precisely which one was missing.
+fn control_plane_revision(
+    store: &feltdb::StateStore,
+    label: &str,
+    id: &str,
+) -> Result<StateRevision, ApiError> {
+    store
+        .get(&feltdb::StateId::from_hex(id.to_string()))
+        .ok_or_else(|| {
+            control_plane_error(
+                StatusCode::NOT_FOUND,
+                "revision_not_found",
+                format!("the {label} revision {id} is not held by this instance"),
+            )
+        })
+}
+
+/// A revision's content as JSON, redacted the same way inspected records are.
+///
+/// Revision content is record content. It reaches a human through the same
+/// redaction the data browser applies, because a secret does not stop being a
+/// secret by being historical.
+fn control_plane_revision_content(revision: &StateRevision) -> Value {
+    let mut content =
+        serde_json::from_str::<Value>(&revision.content).unwrap_or(Value::String(String::new()));
+    redact_inspection_value(&mut content);
+    content
+}
+
+/// What the whole control plane declares it can do.
+async fn control_plane_capabilities() -> Json<Value> {
+    Json(control_plane::capabilities())
+}
+
+#[derive(Deserialize)]
+struct ControlPlaneScope {
+    #[serde(default)]
+    application_id: Option<String>,
+    #[serde(default = "production_environment")]
+    environment: String,
+}
+
+/// Instance, authority, runtime, storage and activity in one document.
+///
+/// One request rather than eight, because an overview whose panels arrive
+/// independently shows eight moments and calls them one instant.
+async fn control_plane_overview(State(state): State<AppState>) -> Result<Json<Value>, ApiError> {
+    let db = state.db.clone();
+    let (state_version, authority_revision, instance_id, cardinalities, log) =
+        tokio::task::spawn_blocking(move || {
+            Ok::<_, FlowError>((
+                db.sequence()?,
+                db.current_revision()?,
+                db.instance_id()?,
+                db.list_cardinalities()?,
+                db.log_recovery(),
+            ))
+        })
+        .await
+        .map_err(|error| ApiError(StatusCode::INTERNAL_SERVER_ERROR, error.to_string()))??;
+    let namespace = state.namespace.to_string();
+    let prefix = format!("{namespace}:");
+    let collections = cardinalities
+        .iter()
+        .filter(|(capability, _)| !capability.starts_with('_') && *capability != "state")
+        .map(|(capability, count)| {
+            json!({
+                "capability": capability,
+                "collection": capability.strip_prefix(&prefix).unwrap_or(capability),
+                "records": count,
+            })
+        })
+        .collect::<Vec<_>>();
+    let records: u64 = collections
+        .iter()
+        .filter_map(|entry| entry["records"].as_u64())
+        .sum();
+    let revisions = cardinalities
+        .iter()
+        .find(|(capability, _)| capability == "state")
+        .map(|(_, count)| *count)
+        .unwrap_or(0);
+    Ok(Json(json!({
+        "instance": {
+            "instance_id": instance_id,
+            "namespace": namespace,
+            "engine_version": env!("CARGO_PKG_VERSION"),
+            "protocol_version": PROTOCOL_VERSION,
+            "uptime_seconds": state.started_at.elapsed().as_secs(),
+            "authentication_enabled": state.auth_enabled,
+        },
+        "authority": {
+            "authority_revision": authority_revision,
+            "state_version": state_version,
+            "lease_clock_healthy": state.lease_clock.is_healthy(),
+            "advertise_url": state.advertise_url.as_ref().map(|value| value.to_string()),
+        },
+        "storage": {
+            "records": records,
+            "state_revisions": revisions,
+            "collections": collections,
+            // Reported as the two distinct facts the type carries: a clean
+            // open, and an open that discarded an incomplete final append.
+            // Flattening them to a boolean would hide the second, which is the
+            // one an operator needs to see.
+            "log_recovery": match log {
+                feltdb::LogRecovery::Clean => json!({"status": "clean"}),
+                feltdb::LogRecovery::RecoveredTornTail { byte_offset, discarded_bytes } => json!({
+                    "status": "recovered-torn-tail",
+                    "byte_offset": byte_offset,
+                    "discarded_bytes": discarded_bytes,
+                }),
+            },
+            "audit": serde_json::to_value(state.audit.health()).unwrap_or(Value::Null),
+        },
+        "runtime": {
+            "worker_enabled": state.worker_enabled,
+            "request_deadline_ms": state.request_deadline.as_millis() as u64,
+            "admission_permits_available": state.admission.available_permits(),
+        },
+        "activity": serde_json::to_value(state.metrics.snapshot()).unwrap_or(Value::Null),
+    })))
+}
+
+/// The write operations this application declares, per collection.
+///
+/// Studio binds its create, update and delete controls to this. A collection
+/// that declares no action for an operation gets no control for it — which is
+/// the same answer any other caller gets, because there is no other way in.
+async fn control_plane_actions(
+    State(state): State<AppState>,
+    Extension(principal): Extension<Principal>,
+    Query(scope): Query<ControlPlaneScope>,
+) -> Result<Json<Value>, ApiError> {
+    let application_id = scope.application_id.clone().ok_or_else(|| {
+        control_plane_error(
+            StatusCode::BAD_REQUEST,
+            "application_required",
+            "application_id is required",
+        )
+    })?;
+    let contract =
+        active_inspection_contract(&state, &principal, &application_id, &scope.environment)?;
+    let collections = contract
+        .state
+        .collections
+        .iter()
+        .map(|collection| {
+            let actions = contract
+                .actions
+                .definitions
+                .iter()
+                .filter(|action| action.collection == collection.name)
+                .map(|action| {
+                    json!({
+                        "name": action.name,
+                        "operation": match action.operation {
+                            ActionOperation::Create => "create",
+                            ActionOperation::Update => "update",
+                            ActionOperation::Delete => "delete",
+                        },
+                        "input_fields": action.input_fields,
+                        "required_capabilities": action.required_capabilities,
+                        "audit": action.audit,
+                    })
+                })
+                .collect::<Vec<_>>();
+            json!({"collection": collection.name, "actions": actions})
+        })
+        .collect::<Vec<_>>();
+    Ok(Json(json!({
+        "application": {"application_id": application_id, "environment": scope.environment},
+        "revision_id": contract.revision_id,
+        "route": "/api/applications/{application_id}/revisions/{revision_id}/actions/{action}",
+        "collections": collections,
+    })))
+}
+
+/// Declared indexes, and whether the running instance actually has them.
+///
+/// The two are separate questions and are answered separately. A contract can
+/// declare an index the runtime has not built, and the runtime can hold an
+/// equality index no contract declares; showing only one number would hide
+/// exactly the case an operator opened this page to find.
+async fn control_plane_indexes(
+    State(state): State<AppState>,
+    Extension(principal): Extension<Principal>,
+    Query(scope): Query<ControlPlaneScope>,
+) -> Result<Json<Value>, ApiError> {
+    let application_id = scope.application_id.clone().ok_or_else(|| {
+        control_plane_error(
+            StatusCode::BAD_REQUEST,
+            "application_required",
+            "application_id is required",
+        )
+    })?;
+    let contract =
+        active_inspection_contract(&state, &principal, &application_id, &scope.environment)?;
+    let namespace = contract.environment.state_namespace.clone();
+    let runtime = state.db.equality_indexes()?;
+    let backed = |collection: &str, field: &str| {
+        let capability = format!("{namespace}:{collection}");
+        runtime
+            .iter()
+            .any(|(indexed, indexed_field)| *indexed == capability && indexed_field == field)
+    };
+    let indexes = contract
+        .state
+        .indexes
+        .iter()
+        .map(|index| {
+            let fields = index
+                .fields
+                .iter()
+                .map(|field| json!({"field": field, "backed": backed(&index.collection, field)}))
+                .collect::<Vec<_>>();
+            let all_backed = fields.iter().all(|field| field["backed"] == json!(true));
+            json!({
+                "name": index.name,
+                "collection": index.collection,
+                "fields": fields,
+                "unique": index.unique,
+                "sparse": index.sparse,
+                "version": index.version,
+                "state": if all_backed { "backed" } else { "declared" },
+            })
+        })
+        .collect::<Vec<_>>();
+    // Which equality filters the server can serve from an index. A field that
+    // is not here is still filterable; it is filterable by scanning, and saying
+    // so is the difference between a usable browser and a surprising one.
+    let access_paths = contract
+        .state
+        .collections
+        .iter()
+        .map(|collection| {
+            json!({
+                "collection": collection.name,
+                "fields": collection.fields.iter().map(|field| json!({
+                    "field": field.name,
+                    "access_method": if backed(&collection.name, &field.name) { "index" } else { "scan" },
+                })).collect::<Vec<_>>(),
+            })
+        })
+        .collect::<Vec<_>>();
+    Ok(Json(json!({
+        "application": {"application_id": application_id, "environment": scope.environment},
+        "state_namespace": namespace,
+        "declared": indexes,
+        "runtime_equality_indexes": runtime.iter().map(|(capability, field)| json!({
+            "capability": capability, "field": field,
+        })).collect::<Vec<_>>(),
+        "access_paths": access_paths,
+    })))
+}
+
+#[derive(Deserialize)]
+struct IndexRebuildRequest {
+    application_id: String,
+    #[serde(default = "production_environment")]
+    environment: String,
+    collection: String,
+    field: String,
+}
+
+/// Rebuilds one declared equality index from authoritative state.
+///
+/// Restricted to a field the application's contract declares an index on.
+/// Rebuilding is a maintenance operation on a declared index, not a way to
+/// create indexes the contract never asked for.
+async fn control_plane_rebuild_index(
+    State(state): State<AppState>,
+    Extension(principal): Extension<Principal>,
+    Json(request): Json<IndexRebuildRequest>,
+) -> Result<Json<Value>, ApiError> {
+    let contract = active_inspection_contract(
+        &state,
+        &principal,
+        &request.application_id,
+        &request.environment,
+    )?;
+    let declared = contract.state.indexes.iter().any(|index| {
+        index.collection == request.collection && index.fields.iter().any(|f| *f == request.field)
+    });
+    if !declared {
+        return Err(control_plane_error(
+            StatusCode::UNPROCESSABLE_ENTITY,
+            "index_not_declared",
+            format!(
+                "the contract declares no index on {}.{}",
+                request.collection, request.field
+            ),
+        ));
+    }
+    let capability = format!(
+        "{}:{}",
+        contract.environment.state_namespace, request.collection
+    );
+    let created = state.db.create_equality_index(&capability, &request.field)?;
+    Ok(Json(json!({
+        "collection": request.collection,
+        "field": request.field,
+        "capability": capability,
+        "created": created,
+        "state": "backed",
+    })))
+}
+
+#[derive(Deserialize)]
+struct OperationsQuery {
+    #[serde(default)]
+    collection: Option<String>,
+    #[serde(default)]
+    kind: Option<String>,
+    #[serde(default)]
+    limit: Option<usize>,
+}
+
+const CONTROL_PLANE_OPERATION_LIMIT: usize = 200;
+
+/// Recent writes, newest first, without the values they wrote.
+///
+/// The change log is what the instance retains for replication, so this is a
+/// window on recent activity rather than an operation archive; the response
+/// says so rather than letting an empty tail read as a quiet system.
+async fn control_plane_operations(
+    State(state): State<AppState>,
+    Query(query): Query<OperationsQuery>,
+) -> Result<Json<Value>, ApiError> {
+    let limit = query
+        .limit
+        .unwrap_or(50)
+        .clamp(1, CONTROL_PLANE_OPERATION_LIMIT);
+    let db = state.db.clone();
+    let (mut operations, retained_from) = tokio::task::spawn_blocking(move || {
+        Ok::<_, FlowError>((
+            db.operations_since(&HashMap::new())?,
+            db.retained_operation_floors()?,
+        ))
+    })
+    .await
+    .map_err(|error| ApiError(StatusCode::INTERNAL_SERVER_ERROR, error.to_string()))??;
+    operations.sort_by(|left, right| right.op_id.cmp(&left.op_id));
+    let matched = operations
+        .iter()
+        .filter(|operation| {
+            query
+                .collection
+                .as_deref()
+                .is_none_or(|collection| control_plane::collection_of(&operation.capability) == collection)
+        })
+        .filter(|operation| {
+            query.kind.as_deref().is_none_or(|kind| {
+                matches!(
+                    (kind, &operation.op_type),
+                    ("insert", feltdb::OperationType::Insert)
+                        | ("update", feltdb::OperationType::Update)
+                        | ("delete", feltdb::OperationType::Delete)
+                )
+            })
+        })
+        .take(limit)
+        .map(control_plane::operation_summary_to_json)
+        .collect::<Vec<_>>();
+    Ok(Json(json!({
+        "operations": matched,
+        "retained": {
+            "operations_held": operations.len(),
+            "floors": retained_from,
+            "note": "The change log is bounded by retention and compaction. Operations older than the floors above are no longer held by this instance.",
+        },
+    })))
+}
+
+/// Peers, causal position, and what replication still owes.
+async fn control_plane_replication(
+    State(state): State<AppState>,
+) -> Result<Json<Value>, ApiError> {
+    let db = state.db.clone();
+    let namespace = state.namespace.to_string();
+    let scan_namespace = namespace.clone();
+    let (peers, positions, floors, instance_id) = tokio::task::spawn_blocking(move || {
+        Ok::<_, FlowError>((
+            db.peers_for_namespace(&scan_namespace)?,
+            db.operation_versions()?,
+            db.retained_operation_floors()?,
+            db.instance_id()?,
+        ))
+    })
+    .await
+    .map_err(|error| ApiError(StatusCode::INTERNAL_SERVER_ERROR, error.to_string()))??;
+    let metrics = state.metrics.snapshot();
+    let membership = state.cluster.get();
+    Ok(Json(json!({
+        "local": {"instance_id": instance_id, "namespace": namespace},
+        "membership": membership,
+        "peers": peers,
+        "causal_position": positions,
+        "retained_operation_floors": floors,
+        "health": {
+            "peer_sync_successes": metrics.peer_sync_successes,
+            "peer_sync_failures": metrics.peer_sync_failures,
+            "operations_sent": metrics.sync_operations_sent,
+            "operations_received": metrics.sync_operations_received,
+            "operations_compacted": metrics.operations_compacted,
+        },
+    })))
+}
+
+/// Applications this instance runs, and whether their runtimes are up.
+///
+/// Scoped by the caller's own tenant and application memberships, exactly as
+/// `GET /api/tenants/{id}/applications` is. Studio sees the applications its
+/// operator may see, not the applications the instance happens to hold.
+async fn control_plane_applications(
+    State(state): State<AppState>,
+    Extension(principal): Extension<Principal>,
+) -> Result<Json<Value>, ApiError> {
+    let mut applications = Vec::new();
+    for tenant in state.tenancy.tenants_for(&principal.key_id) {
+        for application in state
+            .tenancy
+            .applications_for(&principal.key_id, &tenant.id)
+        {
+            let pointers = state.applications.pointers(&application.id);
+            let instances = state.runtimes.list(&tenant.id, &application.id);
+            let environments = pointers
+                .iter()
+                .map(|(environment, revision_id)| {
+                    let instance = instances.iter().find(|instance| {
+                        instance.environment == *environment
+                            && instance.revision_id == *revision_id
+                    });
+                    json!({
+                        "environment": environment,
+                        "revision_id": revision_id,
+                        "runtime": instance.map(|instance| json!({
+                            "runtime_id": instance.runtime_id,
+                            "status": instance.status,
+                            "state_namespace": instance.state_namespace,
+                            "contract_hash": instance.contract_hash,
+                            "started_at": instance.started_at,
+                            "started_by": instance.started_by,
+                        })),
+                    })
+                })
+                .collect::<Vec<_>>();
+            applications.push(json!({
+                "application_id": application.id,
+                "application_name": application.name,
+                "tenant_id": tenant.id,
+                "tenant_name": tenant.name,
+                "namespace": application.namespace,
+                "status": application.status,
+                "environments": environments,
+            }));
+        }
+    }
+    Ok(Json(json!({"applications": applications})))
+}
+
+/// What a developer needs to talk to this instance from code.
+async fn control_plane_developer(
+    State(state): State<AppState>,
+    Query(scope): Query<ControlPlaneScope>,
+) -> Result<Json<Value>, ApiError> {
+    let endpoint = state
+        .advertise_url
+        .as_ref()
+        .map(|value| value.to_string())
+        .unwrap_or_default();
+    let application = scope.application_id.clone().unwrap_or_default();
+    Ok(Json(json!({
+        "endpoint": endpoint,
+        "namespace": state.namespace.to_string(),
+        "protocol_version": PROTOCOL_VERSION,
+        "authentication": if state.auth_enabled { "bearer-api-key" } else { "disabled" },
+        "openapi": "/v1/openapi.json",
+        "sdk": {
+            "package": "@feltdb/core",
+            "install": "npm install @feltdb/core",
+            "snippet": "import { createFeltDB } from '@feltdb/core';\nconst db = createFeltDB({ namespace: 'NAMESPACE', remoteUrl: 'ENDPOINT', token: 'API_KEY' });",
+        },
+        "cli": {
+            "package": "@feltdb/core",
+            "snippet": "npx feltdb --url ENDPOINT --token API_KEY collections list",
+        },
+        "environment": {
+            "FELTDB_URL": endpoint,
+            "FELTDB_NAMESPACE": state.namespace.to_string(),
+            "FELTDB_APPLICATION_ID": application,
+        },
+    })))
+}
+
+// ---------------------------------------------------------------------------
+// Attribution: who caused a change
+// ---------------------------------------------------------------------------
+//
+// The invariant these routes exist to hold: **there is no invisible mutation**.
+// Whatever wrote a record — a person, an application, an agent, replication —
+// the same question is answerable about it, through the same durable model.
+
+#[derive(Deserialize)]
+struct TransactionsQuery {
+    #[serde(default)]
+    subject: Option<String>,
+    #[serde(default)]
+    collection: Option<String>,
+    #[serde(default)]
+    limit: Option<usize>,
+}
+
+const CONTROL_PLANE_TRANSACTION_LIMIT: usize = 200;
+
+/// Recent commits and who made them.
+///
+/// The window is bounded and says so. An operator reading this must be able to
+/// tell "nothing happened" from "it happened before what this instance still
+/// holds in memory", so the window's size and occupancy are part of the answer.
+async fn control_plane_transactions(
+    State(state): State<AppState>,
+    Query(query): Query<TransactionsQuery>,
+) -> Result<Json<Value>, ApiError> {
+    let limit = query
+        .limit
+        .unwrap_or(50)
+        .clamp(1, CONTROL_PLANE_TRANSACTION_LIMIT);
+    let db = state.db.clone();
+    let (attributions, window) = tokio::task::spawn_blocking(move || {
+        Ok::<_, FlowError>((
+            db.recent_transactions(CONTROL_PLANE_TRANSACTION_LIMIT)?,
+            db.transaction_attribution_window()?,
+        ))
+    })
+    .await
+    .map_err(|error| ApiError(StatusCode::INTERNAL_SERVER_ERROR, error.to_string()))??;
+    let matched = attributions
+        .into_iter()
+        .filter(|attribution| {
+            query
+                .subject
+                .as_deref()
+                .is_none_or(|subject| attribution.subject.as_deref() == Some(subject))
+        })
+        .filter(|attribution| {
+            query.collection.as_deref().is_none_or(|collection| {
+                attribution.keys.iter().any(|key| {
+                    key.rsplit_once(':')
+                        .map(|(capability, _)| control_plane::collection_of(capability))
+                        == Some(collection)
+                })
+            })
+        })
+        .take(limit)
+        .map(|attribution| serde_json::to_value(&attribution).unwrap_or(Value::Null))
+        .collect::<Vec<_>>();
+    Ok(Json(json!({
+        "transactions": matched,
+        "window": {
+            "held": window.0,
+            "capacity": window.1,
+            "note": "Attribution is answered from a bounded in-memory window over recent commits. Commits older than the window are in the durable transaction log, which this route does not read.",
+        },
+    })))
+}
+
+/// One transaction: who committed it, what it touched, and whether it applied.
+///
+/// Two different facts, deliberately both reported. *Applied* comes from the
+/// database's own idempotency record and is true for as long as the database
+/// holds the transaction id — it is what makes a retried commit a no-op rather
+/// than a second write. *Attribution* comes from the bounded recent-commit
+/// window. A transaction that applied and has no attribution is one that
+/// committed longer ago than the window keeps, which is a different thing from
+/// one that never committed, and collapsing the two would make a replayed
+/// transaction id read as new.
+async fn control_plane_transaction(
+    State(state): State<AppState>,
+    Path(transaction_id): Path<String>,
+) -> Result<Json<Value>, ApiError> {
+    let db = state.db.clone();
+    let id = transaction_id.clone();
+    let (applied, attribution) = tokio::task::spawn_blocking(move || {
+        Ok::<_, FlowError>((
+            db.has_applied_transaction(&id)?,
+            db.transaction_attribution(&id)?,
+        ))
+    })
+    .await
+    .map_err(|error| ApiError(StatusCode::INTERNAL_SERVER_ERROR, error.to_string()))??;
+    if !applied && attribution.is_none() {
+        return Err(control_plane_error(
+            StatusCode::NOT_FOUND,
+            "transaction_not_found",
+            "this instance has not applied a transaction with that id",
+        ));
+    }
+    Ok(Json(json!({
+        "transaction_id": transaction_id,
+        "applied": applied,
+        "idempotent_replay": if applied {
+            "A commit repeating this id with the same payload is a no-op; with a different payload it is refused."
+        } else {
+            "This instance holds no idempotency record for this id."
+        },
+        "attribution": attribution,
+        "attribution_available": attribution.is_some(),
+    })))
+}
+
+/// Everything this instance can say about how one record came to be as it is.
+///
+/// Four sources, joined and labelled rather than merged: the row's own
+/// operation provenance, the transactions that named it, the state revisions of
+/// its resource, and — when the record belongs to an application — the agent or
+/// principal each transaction names. They answer different parts of the same
+/// question and disagree in informative ways, so none of them is collapsed into
+/// the others.
+async fn control_plane_record_provenance(
+    State(state): State<AppState>,
+    Extension(principal): Extension<Principal>,
+    Path((collection, id)): Path<(String, String)>,
+    Query(scope): Query<ControlPlaneScope>,
+) -> Result<Json<Value>, ApiError> {
+    let capability = match scope.application_id.as_deref() {
+        Some(application_id) => {
+            let contract =
+                active_inspection_contract(&state, &principal, application_id, &scope.environment)?;
+            inspectable_collection(&contract, &collection)?;
+            format!("{}:{}", contract.environment.state_namespace, collection)
+        }
+        // Without an application the record is a direct-authority record, whose
+        // capability is the collection itself.
+        None => {
+            validate_segment(&collection)?;
+            collection.clone()
+        }
+    };
+    validate_segment(&id)?;
+    // The two write paths key their rows differently, and the revision resource
+    // is the row key in both cases. An application transaction stores
+    // `{state_namespace}:{collection}` / `{id}`; a direct-authority write stores
+    // `{collection}` / `{collection}:{id}`. Getting this wrong reads as "no such
+    // record" rather than as a bug, so it is derived once, here.
+    let row_key = if capability == collection {
+        record_key(&collection, &id)?
+    } else {
+        id.clone()
+    };
+    let resource = row_key.clone();
+    let db = state.db.clone();
+    let lookup_capability = capability.clone();
+    let lookup_id = row_key.clone();
+    let lookup_resource = resource.clone();
+    let (row, transactions, revisions) = tokio::task::spawn_blocking(move || {
+        let store = feltdb::FeltDBStateSystem::create_store(&Arc::new(db.clone()))
+            .map_err(FlowError::CapabilityError)?;
+        Ok::<_, FlowError>((
+            db.get_collection_record(&lookup_capability, &lookup_id)?,
+            db.transactions_touching(&lookup_capability, &lookup_id, 20)?,
+            store.history_of(&lookup_resource),
+        ))
+    })
+    .await
+    .map_err(|error| ApiError(StatusCode::INTERNAL_SERVER_ERROR, error.to_string()))??;
+    let row = row.ok_or_else(|| {
+        control_plane_error(
+            StatusCode::NOT_FOUND,
+            "record_not_found",
+            "no record with that identity",
+        )
+    })?;
+    Ok(Json(json!({
+        "record": {"collection": collection, "id": id, "capability": capability, "key": row_key, "resource": resource},
+        // What the storage row itself records: the operation that last wrote it.
+        "operation": row.operation.as_ref().map(|operation| json!({
+            "type": match operation.op_type {
+                feltdb::OperationType::Insert => "insert",
+                feltdb::OperationType::Update => "update",
+                feltdb::OperationType::Delete => "delete",
+            },
+            "instance_id": operation.instance_id,
+            "sequence": operation.sequence,
+            "vector_clock": operation.vector_clock,
+            "state_id": operation.revision.as_ref().map(|revision| revision.id.clone()),
+        })),
+        "content_hash": row.content_hash,
+        "updated_ms": row.unix_ms,
+        // Who asked for the changes: the actor each transaction authenticated as.
+        "transactions": transactions,
+        // What the state model recorded: the resource's revision chain, if the
+        // write path that produced it mints revisions.
+        "revisions": revisions.iter().map(control_plane::revision_summary_to_json).collect::<Vec<_>>(),
+        "attribution": {
+            "actor": transactions.first().and_then(|attribution| attribution.subject.clone()),
+            "authority": row.operation.as_ref().map(|operation| operation.instance_id.clone()),
+            "source": if transactions.first().is_some() { "transaction" } else if row.operation.is_some() { "authority" } else { "unknown" },
+        },
+    })))
+}
+
+// ---------------------------------------------------------------------------
+// Agents
+// ---------------------------------------------------------------------------
+//
+// An agent is a principal. It is not a separate identity system, it does not
+// get a private write path, and its changes are the same operations,
+// transactions and revisions every other writer produces. What the control
+// plane adds is the human's view of it: what it may do, what it has done, and
+// what it is doing now.
+
+/// What an agent principal may reach in an application's contract.
+///
+/// Computed from the two things that actually decide it: the capabilities the
+/// principal holds, and the actions and policies the contract declares. Nothing
+/// is inferred from the agent's name or history.
+fn agent_access(
+    contract: &ApplicationRuntimeContract,
+    capabilities: &[String],
+) -> Vec<Value> {
+    let holds = |required: &[String]| required.iter().all(|value| capabilities.contains(value));
+    contract
+        .state
+        .collections
+        .iter()
+        .map(|collection| {
+            let policy = matching_state_policy(contract, &collection.name);
+            let actions = contract
+                .actions
+                .definitions
+                .iter()
+                .filter(|action| action.collection == collection.name)
+                .map(|action| {
+                    json!({
+                        "name": action.name,
+                        "operation": match action.operation {
+                            ActionOperation::Create => "create",
+                            ActionOperation::Update => "update",
+                            ActionOperation::Delete => "delete",
+                        },
+                        "required_capabilities": action.required_capabilities,
+                        "permitted": holds(&action.required_capabilities),
+                    })
+                })
+                .collect::<Vec<_>>();
+            json!({
+                "collection": collection.name,
+                "read": {
+                    "policy": policy.and_then(|value| value.read.clone()),
+                    "capabilities": policy.map(|value| value.capabilities.clone()).unwrap_or_default(),
+                },
+                "write": {
+                    "policy": policy.and_then(|value| value.write.clone()),
+                    "actions": actions,
+                },
+            })
+        })
+        .collect()
+}
+
+fn principal_kind_name(kind: &PrincipalKind) -> &'static str {
+    match kind {
+        PrincipalKind::Agent => "agent",
+        PrincipalKind::Workload => "workload",
+        PrincipalKind::Service => "service",
+        PrincipalKind::Worker => "worker",
+        PrincipalKind::Connection => "connection",
+    }
+}
+
+/// Agents registered against an application, with what each has been doing.
+async fn control_plane_agents(
+    State(state): State<AppState>,
+    Extension(principal): Extension<Principal>,
+    Query(scope): Query<ControlPlaneScope>,
+) -> Result<Json<Value>, ApiError> {
+    let application_id = scope.application_id.clone().ok_or_else(|| {
+        control_plane_error(
+            StatusCode::BAD_REQUEST,
+            "application_required",
+            "application_id is required",
+        )
+    })?;
+    let principals = state
+        .principals
+        .list(&principal.key_id, &state.tenancy, &application_id)
+        .map_err(control_error)?;
+    let db = state.db.clone();
+    let attributions = tokio::task::spawn_blocking(move || {
+        db.recent_transactions(CONTROL_PLANE_TRANSACTION_LIMIT)
+    })
+    .await
+    .map_err(|error| ApiError(StatusCode::INTERNAL_SERVER_ERROR, error.to_string()))??;
+    let agents = principals
+        .iter()
+        .filter(|record| record.kind == PrincipalKind::Agent)
+        .map(|agent| {
+            let sessions = principals
+                .iter()
+                .filter(|record| record.parent_id.as_deref() == Some(agent.id.as_str()))
+                .collect::<Vec<_>>();
+            let commits = attributions
+                .iter()
+                .filter(|attribution| attribution.subject.as_deref() == Some(agent.id.as_str()))
+                .collect::<Vec<_>>();
+            json!({
+                "agent_id": agent.id,
+                "name": agent.name,
+                "status": agent.status,
+                "capabilities": agent.capabilities,
+                "created_by": agent.created_by,
+                "created_at": agent.created_at,
+                "version": agent.version,
+                "application_id": agent.application_id,
+                "sessions": {
+                    "total": sessions.len(),
+                    "running": sessions
+                        .iter()
+                        .filter(|record| record.status == PrincipalStatus::Running)
+                        .count(),
+                },
+                "activity": {
+                    "recent_transactions": commits.len(),
+                    "records_changed": commits.iter().map(|attribution| attribution.operations).sum::<usize>(),
+                    "last_activity_ms": commits.first().map(|attribution| attribution.unix_ms as u64),
+                },
+            })
+        })
+        .collect::<Vec<_>>();
+    Ok(Json(json!({
+        "application": {"application_id": application_id, "environment": scope.environment},
+        "agents": agents,
+    })))
+}
+
+/// One agent: identity, access, what it has done, what it is doing now.
+async fn control_plane_agent(
+    State(state): State<AppState>,
+    Extension(principal): Extension<Principal>,
+    Path(agent_id): Path<String>,
+    Query(scope): Query<ControlPlaneScope>,
+) -> Result<Json<Value>, ApiError> {
+    let application_id = scope.application_id.clone().ok_or_else(|| {
+        control_plane_error(
+            StatusCode::BAD_REQUEST,
+            "application_required",
+            "application_id is required",
+        )
+    })?;
+    let principals = state
+        .principals
+        .list(&principal.key_id, &state.tenancy, &application_id)
+        .map_err(control_error)?;
+    let agent = principals
+        .iter()
+        .find(|record| record.id == agent_id && record.kind == PrincipalKind::Agent)
+        .ok_or_else(|| {
+            control_plane_error(
+                StatusCode::NOT_FOUND,
+                "agent_not_found",
+                "no agent principal with that identity in this application",
+            )
+        })?;
+    let contract =
+        active_inspection_contract(&state, &principal, &application_id, &scope.environment)?;
+    let db = state.db.clone();
+    let attributions = tokio::task::spawn_blocking(move || {
+        db.recent_transactions(CONTROL_PLANE_TRANSACTION_LIMIT)
+    })
+    .await
+    .map_err(|error| ApiError(StatusCode::INTERNAL_SERVER_ERROR, error.to_string()))??;
+    let commits = attributions
+        .iter()
+        .filter(|attribution| attribution.subject.as_deref() == Some(agent.id.as_str()))
+        .collect::<Vec<_>>();
+    let sessions = principals
+        .iter()
+        .filter(|record| record.parent_id.as_deref() == Some(agent.id.as_str()))
+        .map(|session| {
+            json!({
+                "session_id": session.id,
+                "kind": principal_kind_name(&session.kind),
+                "name": session.name,
+                "status": session.status,
+                "capabilities": session.capabilities,
+                "worker_id": session.worker_id,
+                "started_at": session.started_at,
+                "completed_at": session.completed_at,
+                "created_by": session.created_by,
+            })
+        })
+        .collect::<Vec<_>>();
+    let tenant = state
+        .tenancy
+        .application_tenant(&application_id)
+        .unwrap_or_default();
+    let work = state
+        .workloads
+        .lock()
+        .map_err(|_| {
+            ApiError(
+                StatusCode::INTERNAL_SERVER_ERROR,
+                "workload store unavailable".into(),
+            )
+        })?
+        .list(&tenant, &application_id)
+        .into_iter()
+        .filter(|workload| {
+            serde_json::to_value(&workload.requested_by)
+                .map(|value| value.to_string().contains(&agent.id))
+                .unwrap_or(false)
+        })
+        .map(|workload| {
+            json!({
+                "workload_id": workload.workload_id,
+                "definition_id": workload.definition_id,
+                "state": workload.state,
+                "trigger": workload.trigger,
+                "attempts": workload.attempt_count,
+                "created_at": workload.created_at,
+                "updated_at": workload.updated_at,
+                "next_attempt_at": workload.next_attempt_at,
+                "last_failure": workload.last_failure,
+                "capabilities": workload.capability_snapshot,
+            })
+        })
+        .collect::<Vec<_>>();
+    let decisions = state
+        .principals
+        .audit_for(
+            &principal.key_id,
+            &state.tenancy,
+            &application_id,
+            Some(&agent.id),
+            50,
+        )
+        .map_err(control_error)?;
+    Ok(Json(json!({
+        "identity": {
+            "agent_id": agent.id,
+            "name": agent.name,
+            "kind": principal_kind_name(&agent.kind),
+            "status": agent.status,
+            "application_id": agent.application_id,
+            "environment": scope.environment,
+            "application_revision": contract.revision_id,
+            "created_by": agent.created_by,
+            "created_at": agent.created_at,
+            "version": agent.version,
+        },
+        "access": {
+            "capabilities": agent.capabilities,
+            "collections": agent_access(&contract, &agent.capabilities),
+        },
+        // Every change this agent made, as the same durable facts every other
+        // writer produces: a transaction, the records it named, and the state
+        // revisions those records carry.
+        "did": {
+            "transactions": commits,
+            "records_changed": commits.iter().map(|attribution| attribution.operations).sum::<usize>(),
+            "last_activity_ms": commits.first().map(|attribution| attribution.unix_ms as u64),
+        },
+        "doing": {
+            "sessions": sessions,
+            "work": work,
+        },
+        "authorization_decisions": decisions,
+    })))
+}
+
+// ---------------------------------------------------------------------------
+// State: history, diff, conflict, reconciliation
+// ---------------------------------------------------------------------------
+
+#[derive(Deserialize)]
+struct StateResourceQuery {
+    #[serde(default)]
+    prefix: Option<String>,
+    #[serde(default)]
+    limit: Option<usize>,
+}
+
+/// Every resource with history, and the newest revision of each.
+async fn state_resources(
+    State(state): State<AppState>,
+    Query(query): Query<StateResourceQuery>,
+) -> Result<Json<Value>, ApiError> {
+    let store = control_plane_state_store(&state)?;
+    let limit = query.limit.unwrap_or(100).clamp(1, 500);
+    let prefix = query.prefix.unwrap_or_default();
+    let names = tokio::task::spawn_blocking(move || {
+        let names: Vec<String> = store
+            .resources()
+            .into_iter()
+            .filter(|resource| resource.starts_with(&prefix))
+            .take(limit)
+            .collect();
+        names
+            .into_iter()
+            .map(|resource| {
+                let history = store.history_of(&resource);
+                let head = store.head_of(&resource);
+                json!({
+                    "resource": resource,
+                    "revisions": history.len(),
+                    "head": head.as_ref().map(control_plane::revision_summary_to_json),
+                })
+            })
+            .collect::<Vec<_>>()
+    })
+    .await
+    .map_err(|error| ApiError(StatusCode::INTERNAL_SERVER_ERROR, error.to_string()))?;
+    Ok(Json(json!({"resources": names})))
+}
+
+/// One resource's history, oldest first, with its retention horizon.
+///
+/// The horizon is reported because it is the difference between "this is where
+/// the resource began" and "this is as far back as we still keep".
+async fn state_resource_history(
+    State(state): State<AppState>,
+    Path(resource): Path<String>,
+) -> Result<Json<Value>, ApiError> {
+    let store = control_plane_state_store(&state)?;
+    let document = tokio::task::spawn_blocking(move || {
+        let history = store.history_of(&resource);
+        json!({
+            "resource": resource,
+            "retention": {
+                "keep_last": store.retention_policy(&resource).keep_last,
+                "horizon": store.retention_horizon(&resource),
+            },
+            "revisions": history.iter().map(control_plane::revision_summary_to_json).collect::<Vec<_>>(),
+        })
+    })
+    .await
+    .map_err(|error| ApiError(StatusCode::INTERNAL_SERVER_ERROR, error.to_string()))?;
+    Ok(Json(document))
+}
+
+/// One revision, with its content and what its parent link found.
+async fn state_revision(
+    State(state): State<AppState>,
+    Path(id): Path<String>,
+) -> Result<Json<Value>, ApiError> {
+    let store = control_plane_state_store(&state)?;
+    let revision = control_plane_revision(&store, "requested", &id)?;
+    let parent = match store.parent_of(&revision.id) {
+        None | Some(feltdb::state_model::ParentLookup::Root) => json!({"status": "root"}),
+        Some(feltdb::state_model::ParentLookup::Revision(parent)) => json!({
+            "status": "retained",
+            "revision": control_plane::revision_summary_to_json(&parent),
+        }),
+        Some(feltdb::state_model::ParentLookup::Expired(id)) => {
+            json!({"status": "expired", "state_id": id.as_hex()})
+        }
+        Some(feltdb::state_model::ParentLookup::Missing(id)) => {
+            json!({"status": "missing", "state_id": id.as_hex()})
+        }
+    };
+    let mut document =
+        control_plane::revision_to_json(&revision, control_plane_revision_content(&revision));
+    if let Some(object) = document.as_object_mut() {
+        object.insert("parent".into(), parent);
+    }
+    Ok(Json(document))
+}
+
+#[derive(Deserialize)]
+struct StateDiffRequest {
+    from: String,
+    to: String,
+}
+
+/// The semantic difference between two revisions.
+async fn state_diff(
+    State(state): State<AppState>,
+    Json(request): Json<StateDiffRequest>,
+) -> Result<Json<Value>, ApiError> {
+    let store = control_plane_state_store(&state)?;
+    let from = control_plane_revision(&store, "from", &request.from)?;
+    let to = control_plane_revision(&store, "to", &request.to)?;
+    let diff = feltdb::SemanticDiff::compute(
+        &serde_json::from_str(&from.content).unwrap_or(Value::Null),
+        &serde_json::from_str(&to.content).unwrap_or(Value::Null),
+    );
+    let mut document = control_plane::diff_to_json(&diff);
+    if let Some(object) = document.as_object_mut() {
+        object.insert(
+            "from".into(),
+            control_plane::revision_summary_to_json(&from),
+        );
+        object.insert("to".into(), control_plane::revision_summary_to_json(&to));
+        object.insert(
+            "relationship".into(),
+            json!(match (from.resource == to.resource, to.parent_id.as_ref() == Some(&from.id)) {
+                (true, true) => "parent",
+                (true, false) => "same-resource",
+                (false, _) => "cross-resource",
+            }),
+        );
+    }
+    Ok(Json(document))
+}
+
+#[derive(Deserialize)]
+struct StateConflictRequest {
+    base: String,
+    left: String,
+    right: String,
+}
+
+/// How two branches of one resource interact, path by path.
+async fn state_conflicts(
+    State(state): State<AppState>,
+    Json(request): Json<StateConflictRequest>,
+) -> Result<Json<Value>, ApiError> {
+    let store = control_plane_state_store(&state)?;
+    let base = control_plane_revision(&store, "base", &request.base)?;
+    let left = control_plane_revision(&store, "left", &request.left)?;
+    let right = control_plane_revision(&store, "right", &request.right)?;
+    let classification = feltdb::ConflictClassification::classify(&base, &left, &right);
+    let mut document = control_plane::classification_to_json(&classification);
+    if let Some(object) = document.as_object_mut() {
+        object.insert(
+            "revisions".into(),
+            json!({
+                "base": control_plane::revision_summary_to_json(&base),
+                "left": control_plane::revision_summary_to_json(&left),
+                "right": control_plane::revision_summary_to_json(&right),
+            }),
+        );
+    }
+    Ok(Json(document))
+}
+
+/// Loads the three revisions a reconciliation plan names.
+fn control_plane_reconciliation_inputs(
+    store: &feltdb::StateStore,
+    request: &control_plane::ReconciliationPlanRequest,
+) -> Result<(StateRevision, StateRevision, StateRevision, feltdb::ReconciliationPlan), ApiError> {
+    let plan = request.to_plan().map_err(|message| {
+        control_plane_error(StatusCode::UNPROCESSABLE_ENTITY, "invalid_plan", message)
+    })?;
+    Ok((
+        control_plane_revision(store, "base", &request.base)?,
+        control_plane_revision(store, "left", &request.left)?,
+        control_plane_revision(store, "right", &request.right)?,
+        plan,
+    ))
+}
+
+/// What this plan would produce, without producing it.
+///
+/// Pure: `apply_reconciliation_plan` reads no clock and writes nothing, so a
+/// human can see the resulting state before deciding to commit it.
+async fn state_reconciliation_plan(
+    State(state): State<AppState>,
+    Json(request): Json<control_plane::ReconciliationPlanRequest>,
+) -> Result<Json<Value>, ApiError> {
+    let store = control_plane_state_store(&state)?;
+    let (base, left, right, plan) = control_plane_reconciliation_inputs(&store, &request)?;
+    let classification = feltdb::ConflictClassification::classify(&base, &left, &right);
+    let preview = feltdb::apply_reconciliation_plan(&base, &left, &right, &plan).map_err(
+        |message| {
+            control_plane_error(StatusCode::UNPROCESSABLE_ENTITY, "plan_refused", message)
+        },
+    )?;
+    let mut content = serde_json::from_str::<Value>(&preview).unwrap_or(Value::Null);
+    redact_inspection_value(&mut content);
+    Ok(Json(json!({
+        "plan": control_plane::plan_to_json(&plan),
+        "classification": control_plane::classification_to_json(&classification),
+        "preview": {
+            "content": content,
+            "content_id": feltdb::StateId::compute(&preview).as_hex(),
+            "parent": control_plane::revision_summary_to_json(plan.selected_parent(&left, &right)),
+        },
+        "unresolved": classification
+            .path_conflicts
+            .iter()
+            .filter(|conflict| matches!(conflict.classification, feltdb::ConflictClass::Conflict))
+            .filter(|conflict| !plan.path_overrides.contains_key(&conflict.path))
+            .map(|conflict| control_plane::path_to_json(&conflict.path))
+            .collect::<Vec<_>>(),
+    })))
+}
+
+/// Applies a plan and commits the revision it produces.
+///
+/// The result is committed to the resource's history like any other revision:
+/// reconciliation produces history, it does not rewrite it.
+async fn state_reconciliation_execute(
+    State(state): State<AppState>,
+    Extension(principal): Extension<Principal>,
+    Json(request): Json<control_plane::ReconciliationPlanRequest>,
+) -> Result<Json<Value>, ApiError> {
+    let store = control_plane_state_store(&state)?;
+    let (base, left, right, plan) = control_plane_reconciliation_inputs(&store, &request)?;
+    let authority = format!("studio:{}", principal.key_id);
+    let outcome = feltdb::reconcile(&base, &left, &right, &plan, authority).map_err(|message| {
+        control_plane_error(StatusCode::UNPROCESSABLE_ENTITY, "plan_refused", message)
+    })?;
+    // `reconcile` produces the revision; the store is what makes it durable.
+    // Committing its content through the store's own `commit` rather than
+    // inserting the value directly keeps one minting path, so the revision a
+    // human sees in history was created the way every other revision was.
+    let parent = plan.selected_parent(&left, &right).clone();
+    let committed = store
+        .commit(
+            outcome.materialized_state.content.clone(),
+            &parent,
+            outcome.materialized_state.authority.clone(),
+        )
+        .map_err(|error| {
+            control_plane_error(
+                StatusCode::CONFLICT,
+                "revision_refused",
+                error.to_string(),
+            )
+        })?;
+    // The two must agree. They are computed by the same constructor from the
+    // same content, parent and authority, so a disagreement means the store and
+    // `reconcile` have drifted apart — which would put a revision in history
+    // that is not the one the plan was previewed as producing.
+    if committed.id != outcome.materialized_state.id {
+        return Err(control_plane_error(
+            StatusCode::INTERNAL_SERVER_ERROR,
+            "revision_identity_mismatch",
+            "the committed revision is not the revision the plan produced",
+        ));
+    }
+    audit(
+        &state,
+        &principal.key_id,
+        "state:reconcile",
+        &committed.resource,
+        "allowed",
+        200,
+    );
+    Ok(Json(json!({
+        "plan": control_plane::plan_to_json(&plan),
+        "revision": control_plane::revision_to_json(
+            &committed,
+            control_plane_revision_content(&committed),
+        ),
+    })))
+}
+
 fn record_key(collection: &str, id: &str) -> Result<String, ApiError> {
     validate_segment(collection)?;
     validate_segment(id)?;
@@ -13658,8 +15023,8 @@ mod worker_identity_tests {
 
 #[cfg(test)]
 mod authority_gate_tests {
-    use super::{api_error_body, authorize_transaction_collections, state_authorization};
-    use axum::http::StatusCode;
+    use super::{api_error_body, authorize_transaction_collections, require_bound_tenant, state_authorization};
+    use axum::http::{HeaderMap, HeaderValue, StatusCode};
     use feltdb::{
         application::{
             manifest_hash, ApplicationManifest, ApplicationRevision, PolicyDefinition,
@@ -13767,6 +15132,17 @@ mod authority_gate_tests {
         assert!(!allowed);
     }
 
+    #[test]
+    fn bound_tenant_header_fails_closed_on_mismatch() {
+        let mut headers = HeaderMap::new();
+        headers.insert("feltdb-tenant-id", HeaderValue::from_static("tenant-a"));
+        assert!(require_bound_tenant(&headers, "tenant-a").is_ok());
+        let error = require_bound_tenant(&headers, "tenant-b").unwrap_err();
+        assert_eq!(error.0, StatusCode::FORBIDDEN);
+        let body: serde_json::Value = serde_json::from_str(&error.1).unwrap();
+        assert_eq!(body.get("code").and_then(serde_json::Value::as_str), Some("AUTHORITY_SCOPE_MISMATCH"));
+    }
+
     #[test]
     fn every_forbidden_error_uses_the_canonical_wire_contract() {
         for internal_message in [