diff --git a/crates/tracedecay-contracts/src/request_identity.rs b/crates/tracedecay-contracts/src/request_identity.rs index 0fc7ce53702..8ebef70eba9 100644 --- a/crates/tracedecay-contracts/src/request_identity.rs +++ b/crates/tracedecay-contracts/src/request_identity.rs @@ -66,7 +66,6 @@ impl GlobalRequestSurface { #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum GlobalOpaqueIdentityKind { DashboardPayloadGcPreview, - ExplorerRun, GitIndexPreview, MemoryOperation, } @@ -75,7 +74,6 @@ impl GlobalOpaqueIdentityKind { const fn prefix(self) -> &'static str { match self { Self::DashboardPayloadGcPreview => "payload-gc", - Self::ExplorerRun => "explorer-run", Self::GitIndexPreview => "preview", Self::MemoryOperation => "generated", } diff --git a/crates/tracedecay-dashboard-api/src/authority_tests.rs b/crates/tracedecay-dashboard-api/src/authority_tests.rs index cd757b67f8e..77b9c181f74 100644 --- a/crates/tracedecay-dashboard-api/src/authority_tests.rs +++ b/crates/tracedecay-dashboard-api/src/authority_tests.rs @@ -1605,7 +1605,7 @@ async fn unavailable_savings_is_an_enveloped_unknown_read() { } #[test] -fn a_selected_project_answers_feedback_and_work_reads_and_nothing_else_by_post() { +fn a_selected_project_answers_application_reads_without_mutations() { assert!(is_selected_project_event_delivery_ack( &Method::POST, "events/delivery-ack" @@ -1696,3 +1696,75 @@ fn a_selected_project_answers_feedback_and_work_reads_and_nothing_else_by_post() } } } + +#[tokio::test] +async fn foreign_project_explorer_stream_is_refused() { + use std::sync::atomic::AtomicUsize; + + struct CountedSessions(Arc); + impl DashboardLcmReadPortV1 for CountedSessions { + fn read( + &self, + _control: DashboardHttpRequestControlV1, + _project_id: Option<&str>, + _request: DashboardLcmReadRequestV1, + ) -> DashboardLcmReadFutureV1<'_> { + self.0.fetch_add(1, Ordering::SeqCst); + Box::pin(async { + DashboardLcmReadOutcomeV1::NotReady { + state: crate::DashboardLcmReadStateV1::Unavailable, + reason: "source is not mounted".to_owned(), + } + }) + } + } + + let mut fixture = DashboardStateFixture::open("project.dashboard-explorer-gateway").await; + let reads = Arc::new(AtomicUsize::new(0)); + fixture.state.lcm_read_authority = Some(Arc::new(CountedSessions(Arc::clone(&reads)))); + let app = router_with_active_application(fixture.state, None, Router::new()); + let body = json!({ "query": "fixture", "limit": 1, "offset": 0 }).to_string(); + let request = |project: &str| { + Request::builder() + .method(Method::POST) + .uri(format!("/api/projects/{project}/explorer/queries")) + .header(header::CONTENT_TYPE, "application/json") + .extension(DashboardHttpRequestControlV1::test_fixture( + "explorer-gateway", + )) + .body(Body::from(body.clone())) + .expect("explorer POST") + }; + let foreign = app + .clone() + .oneshot(request("project.dashboard-foreign")) + .await + .expect("gateway"); + assert_eq!(foreign.status(), StatusCode::OK); + let payload = axum::body::to_bytes(foreign.into_body(), 1 << 20) + .await + .expect("refusal"); + assert!(!String::from_utf8_lossy(&payload).contains("data:")); + let denial: Value = serde_json::from_slice(&payload).expect("typed registry denial"); + assert_eq!(denial["domain_state"], "unknown"); + assert_eq!( + reads.load(Ordering::SeqCst), + 0, + "foreign scope never reads active sessions" + ); + + let admitted = app + .oneshot(request("project.dashboard-explorer-gateway")) + .await + .expect("active project route"); + assert_eq!(admitted.status(), StatusCode::OK); + let frames = axum::body::to_bytes(admitted.into_body(), 1 << 20) + .await + .expect("SSE body"); + assert!(String::from_utf8_lossy(&frames).contains("\"kind\":\"source\"")); + assert_eq!( + reads.load(Ordering::SeqCst), + 1, + "positive control reaches source read" + ); +} diff --git a/crates/tracedecay-dashboard-api/src/contract_schema.rs b/crates/tracedecay-dashboard-api/src/contract_schema.rs index 723cc82be6b..d648948491c 100644 --- a/crates/tracedecay-dashboard-api/src/contract_schema.rs +++ b/crates/tracedecay-dashboard-api/src/contract_schema.rs @@ -55,7 +55,7 @@ use super::automation_skills_api::AutomationSkillsPayloadV1; use super::code_read_api::RevisionPairUnionLayoutV1; use super::delivery_api::{DeliveryInboxV1, DeliveryOverviewV1}; use super::doctor_findings_api::DoctorFindingsPayloadV1; -use super::explorer_api::{ExplorerQueryRunV1, ExplorerReadContextV1, ExplorerSessionSizeV1}; +use super::explorer_api::{ExplorerQueryEventV1, ExplorerReadContextV1, ExplorerSessionSizeV1}; use super::graph_service::{ GraphNeighborsPayloadV1, GraphNodePayloadV1, GraphOverviewPayloadV1, GraphPathPayloadV1, GraphSearchPayloadV1, GraphSubgraphPayloadV1, @@ -96,7 +96,7 @@ struct DashboardContractCatalogV1 { storage_telemetry: StorageTelemetryPayloadV1, doctor_findings: DoctorFindingsPayloadV1, remote_operational_status: RemoteOperationalStatusPayloadV1, - explorer_query_run: ExplorerQueryRunV1, + explorer_query_event: ExplorerQueryEventV1, explorer_session_size: DashboardEnvelopeV1>, explorer_read_context: DashboardEnvelopeV1>, projects: DashboardEnvelopeV1, diff --git a/crates/tracedecay-dashboard-api/src/explorer_api.rs b/crates/tracedecay-dashboard-api/src/explorer_api.rs index 7d7cdf16aa8..517233c5de5 100644 --- a/crates/tracedecay-dashboard-api/src/explorer_api.rs +++ b/crates/tracedecay-dashboard-api/src/explorer_api.rs @@ -1,28 +1,22 @@ -//! Explorer planner/coordinator and session-context HTTP binding. -//! -//! The coordinator composes existing graph, session, and memory authorities. -//! It preserves source-local ordering and coverage instead of manufacturing a -//! cross-source rank. Query cancellation is bound to the opaque run identity -//! stored here and reaches the live work through `CancellationToken`. +//! Request-owned Explorer source stream and session-context HTTP binding. -use std::collections::HashMap; +use std::collections::VecDeque; use std::panic::AssertUnwindSafe; -use std::sync::{Arc, Mutex, OnceLock}; use axum::extract::{Path, Query, State}; use axum::http::StatusCode; +use axum::response::sse::{Event, Sse}; use axum::response::{IntoResponse, Json, Response}; -use futures_util::FutureExt; -use futures_util::stream::{FuturesUnordered, StreamExt}; +use futures_util::future::{BoxFuture, FutureExt}; +use futures_util::stream::{self, FuturesUnordered, StreamExt}; use schemars::JsonSchema; use serde::{Deserialize, Serialize}; use serde_json::{Value, json}; -use tokio::sync::RwLock; mod knowledge; mod lifecycle; -use lifecycle::{admitted_deadline_elapsed, mark_cancelled, mark_timed_out}; +use lifecycle::admitted_deadline_elapsed; use super::lcm_api::{ DashboardLcmCanonicalMessageV1, DashboardLcmCanonicalPageV1, DashboardLcmCanonicalStatsV1, @@ -31,21 +25,18 @@ use super::lcm_api::{ message_tool_use_id, }; use super::read_model::{ - DashboardCoverageV1, DashboardDomainStateV1, DashboardEnvelopeV1, DashboardFreshnessV1, - DashboardLegalActionKindV1, DashboardLegalActionRefV1, now_micros, scope_from_state, + DashboardCoverageCompletenessV1, DashboardCoverageV1, DashboardEnvelopeV1, now_micros, + scope_from_state, }; use super::util::json_error; use super::{DashboardHttpRequestControlV1, DashboardState, RequestControl, graph_service}; -use crate::request_identity::{GlobalOpaqueIdentityKind, mint_global_opaque_id}; use tracedecay_runtime_core::cancellation::CancellationToken; -use tracedecay_runtime_core::native_runtime; const SOURCE_IDS: [ExplorerSourceIdV1; 3] = [ ExplorerSourceIdV1::CodeGraph, ExplorerSourceIdV1::Sessions, ExplorerSourceIdV1::Knowledge, ]; -const MAX_QUERY_RUNS: usize = 256; const QUERY_LIMIT_DEFAULT: i64 = 25; const QUERY_LIMIT_MAX: i64 = 100; @@ -84,7 +75,6 @@ impl ExplorerSourceIdV1 { #[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, JsonSchema)] #[serde(rename_all = "snake_case")] pub(super) enum ExplorerRunStateV1 { - Pending, Completed, Partial, Cancelled, @@ -92,26 +82,6 @@ pub(super) enum ExplorerRunStateV1 { Error, } -#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, JsonSchema)] -#[serde(rename_all = "snake_case")] -pub(super) enum ExplorerFinalityV1 { - Pending, - Complete, - Partial, - Cancelled, - TimedOut, - Error, -} - -#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, JsonSchema)] -#[serde(rename_all = "snake_case")] -pub(super) enum ExplorerSourcePhaseV1 { - Queued, - Reading, - Completed, - Cancelled, -} - /// What one source truthfully concluded for this run. Every member has a real /// producer; none is speculative: /// - `Partial`: the source answered with rows but its own read reported @@ -122,7 +92,6 @@ pub(super) enum ExplorerSourcePhaseV1 { #[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, JsonSchema)] #[serde(rename_all = "snake_case")] pub(super) enum ExplorerSourceOutcomeV1 { - Pending, Ready, Partial, Stale, @@ -146,7 +115,6 @@ pub(super) struct ExplorerResultPageV1 { pub(super) struct ExplorerSourceProgressV1 { source_id: ExplorerSourceIdV1, source_label: &'static str, - phase: ExplorerSourcePhaseV1, outcome: ExplorerSourceOutcomeV1, completed_units: Option, total_units: Option, @@ -159,23 +127,6 @@ pub(super) struct ExplorerSourceProgressV1 { } impl ExplorerSourceProgressV1 { - fn pending(source_id: ExplorerSourceIdV1) -> Self { - Self { - source_id, - source_label: source_id.label(), - phase: ExplorerSourcePhaseV1::Queued, - outcome: ExplorerSourceOutcomeV1::Pending, - completed_units: None, - total_units: None, - coverage: DashboardCoverageV1::unknown(), - freshness: "unknown", - watermark: None, - error_code: None, - message: None, - page: None, - } - } - fn unavailable( source_id: ExplorerSourceIdV1, error_code: &'static str, @@ -184,7 +135,6 @@ impl ExplorerSourceProgressV1 { Self { source_id, source_label: source_id.label(), - phase: ExplorerSourcePhaseV1::Completed, outcome: ExplorerSourceOutcomeV1::Unavailable, completed_units: None, total_units: None, @@ -232,63 +182,21 @@ impl ExplorerSourceProgressV1 { } #[derive(Clone, Debug, Serialize, JsonSchema)] -pub(super) struct ExplorerQueryRunV1 { - run_id: String, - request: ExplorerQueryRequestV1, - request_revision: &'static str, - plan_revision: &'static str, - merge_revision: &'static str, - required_source_ids: [ExplorerSourceIdV1; 3], - ordering_policy: &'static str, - explanation: &'static str, - submitted_at_micros: i64, - completed_at_micros: Option, - elapsed_micros: i64, - state: ExplorerRunStateV1, - finality: ExplorerFinalityV1, - sources: Vec, -} - -#[derive(Clone)] -struct StoredExplorerRun { - owner: String, - cancellation: CancellationToken, - run: Arc>, -} - -static QUERY_RUNS: OnceLock>> = OnceLock::new(); - -fn query_runs() -> &'static Mutex> { - QUERY_RUNS.get_or_init(|| Mutex::new(HashMap::new())) -} - -fn run_owner(state: &DashboardState) -> Option { - state - .resolved_scope - .as_ref() - .map(|scope| scope.scope_digest.to_string()) -} - -fn new_run_id() -> Option { - mint_global_opaque_id(GlobalOpaqueIdentityKind::ExplorerRun).ok() +#[serde(tag = "kind", rename_all = "snake_case")] +pub(super) enum ExplorerQueryEventV1 { + Source { + source: Box, + }, + Final { + state: ExplorerRunStateV1, + elapsed_micros: i64, + }, } fn bad_request(message: impl Into) -> Response { json_error(StatusCode::BAD_REQUEST, message).into_response() } -fn not_found(run_id: &str) -> Response { - json_error( - StatusCode::NOT_FOUND, - format!("explorer query run not found: {run_id}"), - ) - .into_response() -} - -fn internal_error(message: impl Into) -> Response { - json_error(StatusCode::INTERNAL_SERVER_ERROR, message).into_response() -} - fn validate_query(request: &mut ExplorerQueryRequestV1) -> Result<(), &'static str> { request.query = request.query.trim().to_owned(); if request.query.is_empty() { @@ -303,342 +211,178 @@ fn validate_query(request: &mut ExplorerQueryRequestV1) -> Result<(), &'static s Ok(()) } -fn initial_run(run_id: String, request: ExplorerQueryRequestV1) -> ExplorerQueryRunV1 { - ExplorerQueryRunV1 { - run_id, - request, - request_revision: "explorer-query-request-v1", - plan_revision: "explorer-query-plan-v1", - merge_revision: "source-local-no-merge-v1", - required_source_ids: SOURCE_IDS, - ordering_policy: "source_local_no_cross_source_merge", - explanation: "Search the code graph, active-project session store, and bounded project fact authority in parallel; preserve each source's own order and coverage.", - submitted_at_micros: now_micros(), - completed_at_micros: None, - elapsed_micros: 0, - state: ExplorerRunStateV1::Pending, - finality: ExplorerFinalityV1::Pending, - sources: SOURCE_IDS - .into_iter() - .map(ExplorerSourceProgressV1::pending) - .collect(), - } +struct ExplorerStream { + control: DashboardHttpRequestControlV1, + cancellation: CancellationToken, + tasks: FuturesUnordered>, + sources: Vec, + frames: VecDeque, + started_at: i64, + terminal: bool, } -fn envelope_for_run( - state: &DashboardState, - run: ExplorerQueryRunV1, -) -> DashboardEnvelopeV1 { - let complete_sources = run - .sources - .iter() - .filter(|source| source.coverage.is_complete()) - .count() as u64; - let coverage = if complete_sources == SOURCE_IDS.len() as u64 { - DashboardCoverageV1::complete(SOURCE_IDS.len() as u64, "sources") - } else { - DashboardCoverageV1::partial( - SOURCE_IDS.len() as u64, - complete_sources, - "sources", - vec!["one or more required sources has unknown or partial coverage".to_owned()], - ) - }; - let domain_state = match run.state { - ExplorerRunStateV1::Pending => DashboardDomainStateV1::Loading, - ExplorerRunStateV1::Completed => DashboardDomainStateV1::Ready, - ExplorerRunStateV1::Partial => DashboardDomainStateV1::Partial, - ExplorerRunStateV1::Cancelled => DashboardDomainStateV1::Cancelled, - ExplorerRunStateV1::TimedOut => DashboardDomainStateV1::TimedOut, - ExplorerRunStateV1::Error => DashboardDomainStateV1::Error, - }; - let mut envelope = DashboardEnvelopeV1::new( - scope_from_state(state), - domain_state, - coverage, - DashboardFreshnessV1::unknown(), - run, - ); - if envelope.payload.state == ExplorerRunStateV1::Pending { - envelope = envelope.with_legal_actions(vec![DashboardLegalActionRefV1::new( - DashboardLegalActionKindV1::RequestCancel, - "dashboard.explorer.query.cancel", - )]); +impl Drop for ExplorerStream { + fn drop(&mut self) { + self.cancellation.cancel(); + let _ = self + .control + .cancellation() + .cancel(tracedecay_session_memory::context::application_observed_at()); } - envelope } -fn remember_run(run: StoredExplorerRun, run_id: String) -> Result<(), &'static str> { - let mut runs = query_runs() - .lock() - .unwrap_or_else(std::sync::PoisonError::into_inner); - if runs.contains_key(&run_id) { - return Err("explorer query run identity collision"); +impl ExplorerStream { + fn finish(&mut self, state: ExplorerRunStateV1) { + if self.terminal { + return; + } + if matches!( + state, + ExplorerRunStateV1::TimedOut | ExplorerRunStateV1::Cancelled + ) { + for source_id in SOURCE_IDS { + if self + .sources + .iter() + .any(|source| source.source_id == source_id) + { + continue; + } + let source = match state { + ExplorerRunStateV1::TimedOut => ExplorerSourceProgressV1::timed_out( + source_id, + "request_deadline_elapsed", + "dashboard request deadline elapsed", + ), + _ => ExplorerSourceProgressV1::cancelled( + source_id, + "request_cancelled", + "dashboard request was cancelled", + ), + }; + self.frames.push_back(ExplorerQueryEventV1::Source { + source: Box::new(source), + }); + } + } + self.frames.push_back(ExplorerQueryEventV1::Final { + state, + elapsed_micros: now_micros().saturating_sub(self.started_at), + }); + self.terminal = true; } - if runs.len() >= MAX_QUERY_RUNS { - let oldest_terminal = runs - .iter() - .filter(|(_, stored)| { - stored - .run - .try_read() - .is_ok_and(|run| run.state != ExplorerRunStateV1::Pending) - }) - .min_by_key(|(_, stored)| { - stored - .run - .try_read() - .map_or(i64::MIN, |run| run.submitted_at_micros) - }) - .map(|(run_id, _)| run_id.clone()); - let Some(oldest_terminal) = oldest_terminal else { - return Err("explorer query run capacity is exhausted"); + + fn finish_from_sources(&mut self) { + let complete = self.sources.len() == SOURCE_IDS.len() + && self.sources.iter().all(|source| { + source.outcome == ExplorerSourceOutcomeV1::Ready + && source.coverage.completeness == DashboardCoverageCompletenessV1::Complete + }); + let state = if complete { + ExplorerRunStateV1::Completed + } else if self.sources.iter().any(|source| { + matches!( + source.outcome, + ExplorerSourceOutcomeV1::Ready | ExplorerSourceOutcomeV1::Partial + ) + }) { + ExplorerRunStateV1::Partial + } else { + ExplorerRunStateV1::Error }; - runs.remove(&oldest_terminal); + self.finish(state); } - runs.insert(run_id, run); - Ok(()) } -fn find_run(state: &DashboardState, run_id: &str) -> Option { - let runs = query_runs() - .lock() - .unwrap_or_else(std::sync::PoisonError::into_inner); - runs.get(run_id) - .filter(|stored| run_owner(state).as_ref() == Some(&stored.owner)) - .cloned() +fn frame(event: ExplorerQueryEventV1) -> Result { + serde_json::to_string(&event) + .map(|data| Event::default().data(data)) + .map_err(std::io::Error::other) } -pub async fn create_query( +#[tracing::instrument(name = "dashboard_api.query.stream", level = "trace", skip_all)] +pub async fn stream_query( State(state): State, RequestControl(control): RequestControl, Json(mut request): Json, ) -> Response { - tracing::Instrument::instrument( - async move { - if let Err(message) = validate_query(&mut request) { - return bad_request(message); - } - let Some(owner) = run_owner(&state) else { - return json_error( - StatusCode::SERVICE_UNAVAILABLE, - "exact registered project scope is unavailable", - ) - .into_response(); - }; - let Some(run_id) = new_run_id() else { - return internal_error("could not allocate explorer query run identity"); - }; - let run = Arc::new(RwLock::new(initial_run(run_id.clone(), request.clone()))); - let cancellation = CancellationToken::new(); - if let Err(message) = remember_run( - StoredExplorerRun { - owner, - cancellation: cancellation.clone(), - run: Arc::clone(&run), - }, - run_id.clone(), - ) { - return internal_error(message); - } - let initial = run.read().await.clone(); - let response = envelope_for_run(&state, initial); - if let Err(error) = native_runtime::NativeTask::spawn(execute_query( - state, - request, - Arc::clone(&run), - cancellation, - control, - )) { - query_runs() - .lock() - .unwrap_or_else(std::sync::PoisonError::into_inner) - .remove(&run_id); - return json_error( - StatusCode::SERVICE_UNAVAILABLE, - format!("explorer query could not start: {error}"), - ) - .into_response(); - } - (StatusCode::ACCEPTED, Json(response)).into_response() - }, - tracing::trace_span!("dashboard_api.query.create"), - ) - .await -} - -pub async fn query_status( - State(state): State, - Path(run_id): Path, -) -> Response { - tracing::Instrument::instrument( - async move { - let Some(stored) = find_run(&state, &run_id) else { - return not_found(&run_id); - }; - let mut run = stored.run.read().await.clone(); - run.elapsed_micros = run - .completed_at_micros - .unwrap_or_else(now_micros) - .saturating_sub(run.submitted_at_micros); - Json(envelope_for_run(&state, run)).into_response() - }, - tracing::trace_span!("dashboard_api.query.status"), - ) - .await -} - -#[tracing::instrument(name = "dashboard_api.query.cancel", level = "trace", skip_all)] -pub async fn cancel_query( - State(state): State, - Path(run_id): Path, -) -> Response { - let Some(stored) = find_run(&state, &run_id) else { - return not_found(&run_id); - }; - let mut run = stored.run.write().await; - if run.state != ExplorerRunStateV1::Pending { + if let Err(message) = validate_query(&mut request) { + return bad_request(message); + } + if state.resolved_scope.is_none() { return json_error( - StatusCode::CONFLICT, - format!("explorer query run is already terminal: {run_id}"), + StatusCode::SERVICE_UNAVAILABLE, + "exact registered project scope is unavailable", ) .into_response(); } - stored.cancellation.cancel(); - mark_cancelled(&mut run); - Json(envelope_for_run(&state, run.clone())).into_response() -} - -#[tracing::instrument(name = "dashboard_api.query.execute", level = "trace", skip_all)] -async fn execute_query( - state: DashboardState, - request: ExplorerQueryRequestV1, - run: Arc>, - cancellation: CancellationToken, - control: DashboardHttpRequestControlV1, -) { - let request_cancellation = control.cancellation().clone(); - let deadline = control.deadline(); - let deadline_wait = admitted_deadline_elapsed(deadline.clone()); - tokio::pin!(deadline_wait); - { - let mut current = run.write().await; - for source in &mut current.sources { - source.phase = ExplorerSourcePhaseV1::Reading; - } - } - - // Polled in place, so dropping `tasks` on any exit cancels the - // unfinished reads. - let mut tasks: FuturesUnordered<_> = SOURCE_IDS + let cancellation = CancellationToken::new(); + let tasks: FuturesUnordered> = SOURCE_IDS .into_iter() .map(|source_id| { - let source = execute_source( + let read = execute_source( state.clone(), request.clone(), source_id, control.clone(), cancellation.clone(), ); - AssertUnwindSafe(source).catch_unwind().map(move |outcome| { - outcome.unwrap_or_else(|_| { - ExplorerSourceProgressV1::error( - source_id, - "source_task_failed", - "explorer source read panicked", - ) + AssertUnwindSafe(read) + .catch_unwind() + .map(move |outcome| { + outcome.unwrap_or_else(|_| { + ExplorerSourceProgressV1::error( + source_id, + "source_task_failed", + "explorer source read panicked", + ) + }) }) - }) + .boxed() }) .collect(); - - let mut completed = 0; - while completed < SOURCE_IDS.len() { + let stream_state = ExplorerStream { + control, + cancellation, + tasks, + sources: Vec::with_capacity(SOURCE_IDS.len()), + frames: VecDeque::new(), + started_at: now_micros(), + terminal: false, + }; + Sse::new(stream::unfold(stream_state, |mut stream| async move { + if let Some(event) = stream.frames.pop_front() { + return Some((frame(event), stream)); + } + if stream.terminal { + return None; + } + let admitted = stream.control.cancellation().clone(); + let deadline = stream.control.deadline(); tokio::select! { biased; - () = &mut deadline_wait => { - let mut current = run.write().await; - if current.state == ExplorerRunStateV1::Pending { - mark_timed_out(&mut current); - } - return; - } - () = cancellation.cancelled() => { - let mut current = run.write().await; - if current.state == ExplorerRunStateV1::Pending { - mark_cancelled(&mut current); - } - return; - } - () = request_cancellation.cancelled() => { - let mut current = run.write().await; - if current.state == ExplorerRunStateV1::Pending { - mark_cancelled(&mut current); - } - return; - } - source = tasks.next() => { - let Some(source) = source else { - break; - }; - completed += 1; - let mut current = run.write().await; - if current.state != ExplorerRunStateV1::Pending { - return; - } - if let Some(slot) = current - .sources - .iter_mut() - .find(|slot| slot.source_id == source.source_id) - { - *slot = source; + () = admitted_deadline_elapsed(deadline) => stream.finish(ExplorerRunStateV1::TimedOut), + () = admitted.cancelled() => stream.finish(ExplorerRunStateV1::Cancelled), + source = stream.tasks.next() => { + if let Some(source) = source { + stream.sources.push(source.clone()); + stream.frames.push_back(ExplorerQueryEventV1::Source { + source: Box::new(source), + }); + if stream.sources.len() == SOURCE_IDS.len() { + stream.finish_from_sources(); + } + } else { + stream.finish_from_sources(); } - current.elapsed_micros = now_micros().saturating_sub(current.submitted_at_micros); } } - } - - let mut current = run.write().await; - if current.state != ExplorerRunStateV1::Pending { - return; - } - if deadline.is_elapsed_at(tracedecay_session_memory::context::application_observed_at()) { - mark_timed_out(&mut current); - return; - } - if cancellation.is_cancelled() || request_cancellation.is_cancelled() { - mark_cancelled(&mut current); - return; - } - let every_concluded = current - .sources - .iter() - .all(|source| matches!(source.outcome, ExplorerSourceOutcomeV1::Ready)); - let complete = every_concluded - && current - .sources - .iter() - .all(|source| source.coverage.is_complete()); - current.completed_at_micros = Some(now_micros()); - current.elapsed_micros = current - .completed_at_micros - .unwrap_or(current.submitted_at_micros) - .saturating_sub(current.submitted_at_micros); - if complete { - current.state = ExplorerRunStateV1::Completed; - current.finality = ExplorerFinalityV1::Complete; - } else if current.sources.iter().any(|source| { - matches!( - source.outcome, - ExplorerSourceOutcomeV1::Ready | ExplorerSourceOutcomeV1::Partial - ) - }) { - current.state = ExplorerRunStateV1::Partial; - current.finality = ExplorerFinalityV1::Partial; - } else { - current.state = ExplorerRunStateV1::Error; - current.finality = ExplorerFinalityV1::Error; - } + stream + .frames + .pop_front() + .map(|event| (frame(event), stream)) + })) + .into_response() } async fn execute_source( @@ -733,16 +477,11 @@ fn code_graph_error(error: crate::graph::CodeGraphReadError) -> ExplorerSourcePr "graph_generation_stale", detail, ), - CodeGraphReadError::Cancelled => { - let mut source = ExplorerSourceProgressV1::unavailable( - ExplorerSourceIdV1::CodeGraph, - "graph_read_cancelled", - "the graph read was cancelled", - ); - source.phase = ExplorerSourcePhaseV1::Cancelled; - source.outcome = ExplorerSourceOutcomeV1::Cancelled; - source - } + CodeGraphReadError::Cancelled => ExplorerSourceProgressV1::cancelled( + ExplorerSourceIdV1::CodeGraph, + "graph_read_cancelled", + "the graph read was cancelled", + ), CodeGraphReadError::TimedOut => ExplorerSourceProgressV1::timed_out( ExplorerSourceIdV1::CodeGraph, "graph_read_timed_out", @@ -897,7 +636,6 @@ fn ready_source( ExplorerSourceProgressV1 { source_id, source_label: source_id.label(), - phase: ExplorerSourcePhaseV1::Completed, outcome: ExplorerSourceOutcomeV1::Ready, completed_units: Some(completed), total_units: total, @@ -1311,27 +1049,164 @@ const fn explorer_lcm_error_code(state: DashboardLcmReadStateV1) -> &'static str #[cfg(test)] #[allow(clippy::expect_used)] mod native_tests { - use std::time::{Duration, Instant}; + use std::pin::Pin; + use std::sync::Arc; + use std::sync::atomic::{AtomicBool, Ordering}; + use std::time::Duration; + + use axum::body::HttpBody; + use tokio::sync::Notify; + use tracedecay_domain::{Confidence, FactCategoryV1, ProvenanceId}; + use tracedecay_privacy::{MemoryFactSanitizationV1, sanitize_memory_fact_payload}; + use tracedecay_runtime_core::native_runtime; + use tracedecay_session_memory::fact_store::DatabaseFactStore; + use tracedecay_store::{ + FactWriteControl, ProjectMemoryFactAddMaterialV1, ProjectMemoryFactStore, + }; use super::*; - #[test] - fn explorer_query_settles_on_the_process_runtime() { - if !crate::test_support::alone_with_storage_wait_counters() { - return; + struct HeldSessions { + started: Arc, + release: Arc, + dropped: Arc, + } + + impl super::super::lcm_api::DashboardLcmReadPortV1 for HeldSessions { + fn read( + &self, + _control: DashboardHttpRequestControlV1, + _project_id: Option<&str>, + _request: DashboardLcmReadRequestV1, + ) -> super::super::lcm_api::DashboardLcmReadFutureV1<'_> { + struct DropMarker(Arc); + impl Drop for DropMarker { + fn drop(&mut self) { + self.0.store(true, Ordering::SeqCst); + } + } + Box::pin(async { + let _marker = DropMarker(Arc::clone(&self.dropped)); + self.started.notify_one(); + self.release.notified().await; + DashboardLcmReadOutcomeV1::NotReady { + state: super::super::lcm_api::DashboardLcmReadStateV1::Unavailable, + reason: "held session read unavailable".to_owned(), + } + }) + } + } + + struct StaleSessions; + impl super::super::lcm_api::DashboardLcmReadPortV1 for StaleSessions { + fn read( + &self, + _control: DashboardHttpRequestControlV1, + _project_id: Option<&str>, + _request: DashboardLcmReadRequestV1, + ) -> super::super::lcm_api::DashboardLcmReadFutureV1<'_> { + Box::pin(async { + DashboardLcmReadOutcomeV1::NotReady { + state: super::super::lcm_api::DashboardLcmReadStateV1::Stale, + reason: "session projection is stale".to_owned(), + } + }) + } + } + + async fn seed_fast_knowledge_row(state: &DashboardState) { + let payload = json!({ + "content": "fixture memory row", + "category": "project", + "tags": ["explorer"], + "entities": ["Fixture"], + "metadata": {}, + }); + let receipt = + match sanitize_memory_fact_payload(payload).expect("sanitize fixture knowledge row") { + MemoryFactSanitizationV1::Durable { receipt, .. } => receipt, + MemoryFactSanitizationV1::Quarantined => panic!("fixture fact must be durable"), + }; + let command = ProjectMemoryFactAddMaterialV1::new( + state.memory_owner.clone(), + "fixture memory row".to_owned(), + FactCategoryV1::Project, + None, + vec!["explorer".to_owned()], + vec!["Fixture".to_owned()], + json!({}), + receipt, + None, + Confidence::new(0.8).expect("fixture confidence"), + None, + ) + .and_then(|material| { + material.into_command( + ProvenanceId::new("dashboard.explorer.stream.fixture".to_owned()) + .expect("fixture provenance"), + ) + }) + .expect("fixture fact command"); + DatabaseFactStore::new(&state.mem_db) + .add_project_memory_fact( + command, + &FactWriteControl::new(Arc::new(|| false), Arc::new(|| true)), + ) + .await + .expect("seed fixture knowledge row"); + } + + async fn next_frame(body: &mut axum::body::Body) -> Value { + let frame = native_runtime::timeout(Duration::from_secs(15), async { + std::future::poll_fn(|cx| Pin::new(&mut *body).poll_frame(cx)).await + }) + .await + .expect("stream frame before deadline") + .expect("stream has next frame") + .expect("stream frame reads") + .into_data() + .expect("SSE data"); + let text = String::from_utf8(frame.to_vec()).expect("utf8 frame"); + text.lines() + .find_map(|line| line.strip_prefix("data: ")) + .map(|data| serde_json::from_str(data).expect("event JSON")) + .unwrap_or(Value::Null) + } + + fn assert_knowledge_coverage(source: &Value) { + let omissions = source["coverage"]["omission_reasons"] + .as_array() + .expect("knowledge coverage reasons"); + match source["coverage"]["completeness"].as_str() { + Some("complete") => assert!(omissions.is_empty(), "complete coverage has no gaps"), + Some("unknown") => assert!( + omissions + .iter() + .any(|reason| reason == "verified memory graph coverage is incomplete"), + "unknown knowledge coverage names its missing graph: {source}" + ), + other => panic!("ready knowledge did not account for its coverage: {other:?}"), } + } + + #[test] + fn fast_explorer_source_precedes_held_source() { let fixture = tokio::runtime::Runtime::new().expect("fixture runtime"); - let (_project, dash) = fixture.block_on(crate::events_api::dashboard_state_fixture( - "project.dashboard-explorer-native", + let (_project, mut dash) = fixture.block_on(crate::events_api::dashboard_state_fixture( + "project.dashboard-explorer-stream", )); - let writer_waits = native_runtime::native_thread_writer_waits(); - let process_runtime = native_runtime::handle().expect("process runtime").id(); - let state = native_runtime::block_on(async move { - assert_eq!(tokio::runtime::Handle::current().id(), process_runtime); - let response = create_query( - State(dash.clone()), + fixture.block_on(seed_fast_knowledge_row(&dash)); + let held = Arc::new(HeldSessions { + started: Arc::new(Notify::new()), + release: Arc::new(Notify::new()), + dropped: Arc::new(AtomicBool::new(false)), + }); + dash.lcm_read_authority = Some(held.clone()); + let response = native_runtime::block_on(async { + stream_query( + State(dash), RequestControl(DashboardHttpRequestControlV1::test_fixture( - "dashboard-explorer-native", + "dashboard-explorer-stream", )), Json(ExplorerQueryRequestV1 { query: "fixture".to_owned(), @@ -1339,36 +1214,295 @@ mod native_tests { offset: 0, }), ) + .await + }) + .expect("native block_on"); + native_runtime::block_on(async { + let mut body = response.into_body(); + let first = next_frame(&mut body).await; + assert_eq!( + first["kind"], "source", + "the first explorer frame was not a source frame" + ); + assert_ne!(first["source"]["source_id"], "sessions"); + let mut fast = first; + while fast["source"]["source_id"] != "knowledge" { + fast = next_frame(&mut body).await; + assert_ne!(fast["source"]["source_id"], "sessions"); + } + assert!( + fast["source"]["page"]["rows"] + .as_array() + .is_some_and(|rows| rows + .iter() + .any(|row| { row["content"] == "fixture memory row" })), + "knowledge rows arrived before the held session read: {fast}" + ); + assert_knowledge_coverage(&fast["source"]); + assert_eq!(fast["source"]["outcome"], "ready"); + held.release.notify_one(); + let mut saw_sessions = false; + loop { + let event = next_frame(&mut body).await; + if event["kind"] == "final" { + assert!( + saw_sessions, + "released source emitted before terminal event" + ); + break; + } + saw_sessions |= event["source"]["source_id"] == "sessions"; + } + }) + .expect("native block_on"); + } + + #[test] + fn disconnect_drops_unfinished_explorer_sources() { + let fixture = tokio::runtime::Runtime::new().expect("fixture runtime"); + let (_project, mut dash) = fixture.block_on(crate::events_api::dashboard_state_fixture( + "project.dashboard-explorer-disconnect", + )); + let held = Arc::new(HeldSessions { + started: Arc::new(Notify::new()), + release: Arc::new(Notify::new()), + dropped: Arc::new(AtomicBool::new(false)), + }); + dash.lcm_read_authority = Some(held.clone()); + native_runtime::block_on(async { + let control = DashboardHttpRequestControlV1::test_fixture("explorer-disconnect"); + let cancellation = control.cancellation().clone(); + let response = stream_query( + State(dash), + RequestControl(control), + Json(ExplorerQueryRequestV1 { + query: "fixture".to_owned(), + limit: 1, + offset: 0, + }), + ) .await; - assert_eq!(response.status(), StatusCode::ACCEPTED); - let body = axum::body::to_bytes(response.into_body(), 1024 * 1024) - .await - .expect("accepted body"); - let accepted: Value = serde_json::from_slice(&body).expect("accepted json"); - let run_id = accepted["payload"]["run_id"] - .as_str() - .expect("accepted run id") - .to_owned(); - let run = find_run(&dash, &run_id).expect("remembered run").run; - native_runtime::timeout(Duration::from_secs(60), async { - loop { - let state = run.read().await.state; - if state != ExplorerRunStateV1::Pending { - return state; - } - let _ = native_runtime::sleep_until(Instant::now() + Duration::from_millis(10)) - .await; + let mut body = response.into_body(); + let first = next_frame(&mut body).await; + assert_eq!(first["kind"], "source"); + let second = next_frame(&mut body).await; + assert_eq!(second["kind"], "source"); + assert_ne!(first["source"]["source_id"], second["source"]["source_id"]); + assert_ne!(first["source"]["source_id"], "sessions"); + assert_ne!(second["source"]["source_id"], "sessions"); + { + let next = next_frame(&mut body); + tokio::pin!(next); + tokio::select! { + () = held.started.notified() => {} + event = &mut next => panic!("held source finished before disconnect: {event}"), + } + } + drop(body); + assert!( + cancellation.is_cancelled(), + "body drop cancels admitted request" + ); + assert!( + held.dropped.load(Ordering::SeqCst), + "body drop releases held source" + ); + }) + .expect("native block_on"); + } + + #[test] + fn admitted_cancellation_concludes_each_source_once() { + let fixture = tokio::runtime::Runtime::new().expect("fixture runtime"); + let (_project, mut dash) = fixture.block_on(crate::events_api::dashboard_state_fixture( + "project.dashboard-explorer-cancellation", + )); + fixture.block_on(seed_fast_knowledge_row(&dash)); + dash.lcm_read_authority = Some(Arc::new(HeldSessions { + started: Arc::new(Notify::new()), + release: Arc::new(Notify::new()), + dropped: Arc::new(AtomicBool::new(false)), + })); + let frames = native_runtime::block_on(async { + let control = DashboardHttpRequestControlV1::test_fixture("explorer-cancellation"); + let cancellation = control.cancellation().clone(); + let response = stream_query( + State(dash), + RequestControl(control), + Json(ExplorerQueryRequestV1 { + query: "fixture".to_owned(), + limit: 1, + offset: 0, + }), + ) + .await; + let mut body = response.into_body(); + let first = next_frame(&mut body).await; + let second = next_frame(&mut body).await; + assert_eq!(first["kind"], "source"); + assert_eq!(second["kind"], "source"); + assert_ne!(first["source"]["source_id"], "sessions"); + assert_ne!(second["source"]["source_id"], "sessions"); + cancellation.cancel(tracedecay_session_memory::context::application_observed_at()); + let third = next_frame(&mut body).await; + let final_frame = next_frame(&mut body).await; + let eof = native_runtime::timeout(Duration::from_secs(15), async { + std::future::poll_fn(|cx| Pin::new(&mut body).poll_frame(cx)).await + }) + .await + .expect("stream ends after terminal frame"); + assert!(eof.is_none(), "stream emitted more than one terminal frame"); + [first, second, third, final_frame] + }) + .expect("native block_on"); + assert_eq!(frames[2]["source"]["source_id"], "sessions"); + assert_eq!(frames[2]["source"]["outcome"], "cancelled"); + assert_eq!(frames[3]["kind"], "final"); + assert_eq!(frames[3]["state"], "cancelled"); + } + + #[test] + fn request_deadline_concludes_each_missing_source_once() { + let fixture = tokio::runtime::Runtime::new().expect("fixture runtime"); + let (_project, mut dash) = fixture.block_on(crate::events_api::dashboard_state_fixture( + "project.dashboard-explorer-deadline", + )); + dash.lcm_read_authority = Some(Arc::new(HeldSessions { + started: Arc::new(Notify::new()), + release: Arc::new(Notify::new()), + dropped: Arc::new(AtomicBool::new(false)), + })); + let frames = native_runtime::block_on(async { + let control = DashboardHttpRequestControlV1::test_fixture_with( + "explorer-deadline", + tracedecay_contracts::CancellationSignal::active("cancel.explorer-deadline") + .expect("test cancellation"), + tracedecay_domain::UtcMicros(1), + tracedecay_domain::UtcMicros(1), + ); + let response = stream_query( + State(dash), + RequestControl(control), + Json(ExplorerQueryRequestV1 { + query: "fixture".to_owned(), + limit: 1, + offset: 0, + }), + ) + .await; + let mut body = response.into_body(); + let mut frames = Vec::new(); + loop { + let frame = next_frame(&mut body).await; + let final_frame = frame["kind"] == "final"; + frames.push(frame); + if final_frame { + break; } + } + let eof = native_runtime::timeout(Duration::from_secs(15), async { + std::future::poll_fn(|cx| Pin::new(&mut body).poll_frame(cx)).await }) .await - .expect("the explorer run settles") + .expect("stream ends after terminal frame"); + assert!(eof.is_none(), "stream emitted more than one terminal frame"); + frames + }) + .expect("native block_on"); + assert_eq!(frames.len(), 4, "three sources then one terminal frame"); + assert_eq!( + frames + .iter() + .filter(|frame| frame["kind"] == "final") + .count(), + 1 + ); + let sources: Vec<&Value> = frames + .iter() + .filter(|frame| frame["kind"] == "source") + .collect(); + assert_eq!(sources.len(), 3); + for source_id in ["code_graph", "sessions", "knowledge"] { + let source = sources + .iter() + .find(|frame| frame["source"]["source_id"] == source_id) + .map(|frame| &frame["source"]) + .unwrap_or_else(|| panic!("deadline must conclude {source_id}")); + assert_eq!(source["outcome"], "timed_out", "{source}"); + assert_eq!(source["error_code"], "request_deadline_elapsed"); + assert!(source["page"].is_null()); + } + assert_eq!(frames[3]["state"], "timed_out"); + } + + #[test] + fn explorer_source_outcomes_remain_distinct() { + let fixture = tokio::runtime::Runtime::new().expect("fixture runtime"); + let (_project, mut dash) = fixture.block_on(crate::events_api::dashboard_state_fixture( + "project.dashboard-explorer-outcomes", + )); + dash.lcm_read_authority = Some(Arc::new(StaleSessions)); + let frames = native_runtime::block_on(async { + let response = stream_query( + State(dash), + RequestControl(DashboardHttpRequestControlV1::test_fixture( + "explorer-outcomes", + )), + Json(ExplorerQueryRequestV1 { + query: "fixture".to_owned(), + limit: 1, + offset: 0, + }), + ) + .await; + let mut body = response.into_body(); + let mut frames = Vec::new(); + loop { + let frame = next_frame(&mut body).await; + let final_frame = frame["kind"] == "final"; + frames.push(frame); + if final_frame { + break; + } + } + frames }) .expect("native block_on"); - assert_eq!(state, ExplorerRunStateV1::Partial); + assert_eq!(frames.len(), 4); + assert_eq!( + frames.last().map(|frame| &frame["state"]), + Some(&json!("partial")) + ); + assert_eq!( + frames + .iter() + .filter(|frame| frame["kind"] == "final") + .count(), + 1 + ); + let sources: Vec<&Value> = frames + .iter() + .filter(|frame| frame["kind"] == "source") + .collect(); + assert_eq!(sources.len(), 3); + let source = |id| { + sources + .iter() + .find(|frame| frame["source"]["source_id"] == id) + .map(|frame| &frame["source"]) + .expect("required source frame") + }; + assert_eq!(source("code_graph")["outcome"], "unavailable"); + assert_eq!(source("code_graph")["error_code"], "missing_registry"); + assert!(source("code_graph")["page"].is_null()); + assert_eq!(source("sessions")["outcome"], "stale"); assert_eq!( - native_runtime::native_thread_writer_waits(), - writer_waits, - "the explorer run parked no native thread on a writer" + source("sessions")["error_code"], + "lcm_temporal_projection_stale" ); + assert!(source("sessions")["page"].is_null()); + assert_eq!(source("knowledge")["outcome"], "ready"); + assert_eq!(source("knowledge")["page"]["rows"], json!([])); + assert_knowledge_coverage(source("knowledge")); } } diff --git a/crates/tracedecay-dashboard-api/src/explorer_api/lifecycle.rs b/crates/tracedecay-dashboard-api/src/explorer_api/lifecycle.rs index 40d490199df..0583f20a6df 100644 --- a/crates/tracedecay-dashboard-api/src/explorer_api/lifecycle.rs +++ b/crates/tracedecay-dashboard-api/src/explorer_api/lifecycle.rs @@ -1,14 +1,11 @@ -//! Exact terminal transitions for admitted Explorer query runs. +//! Source cancellation and admitted request deadline for Explorer streams. use std::time::{Duration, Instant}; use tracedecay_contracts::Deadline; use tracedecay_runtime_core::native_runtime; -use super::{ - ExplorerFinalityV1, ExplorerQueryRunV1, ExplorerRunStateV1, ExplorerSourceIdV1, - ExplorerSourceOutcomeV1, ExplorerSourcePhaseV1, ExplorerSourceProgressV1, now_micros, -}; +use super::{ExplorerSourceIdV1, ExplorerSourceOutcomeV1, ExplorerSourceProgressV1}; impl ExplorerSourceProgressV1 { pub(super) fn cancelled( @@ -17,7 +14,6 @@ impl ExplorerSourceProgressV1 { message: impl Into, ) -> Self { Self { - phase: ExplorerSourcePhaseV1::Cancelled, outcome: ExplorerSourceOutcomeV1::Cancelled, ..Self::unavailable(source_id, error_code, message) } @@ -28,83 +24,8 @@ pub(super) async fn admitted_deadline_elapsed(deadline: Deadline) { let observed_at = tracedecay_session_memory::context::application_observed_at(); let remaining_micros = deadline.expires_at.0.saturating_sub(observed_at.0).max(0) as u64; let due = Instant::now() + Duration::from_micros(remaining_micros); - // A run without a timer times out at once rather than run unbounded. + // A missing timer fails closed instead of leaving the request unbounded. if let Err(error) = native_runtime::sleep_until(due).await { tracing::error!(%error, "dashboard explorer deadline timer unavailable"); } } - -pub(super) fn mark_cancelled(run: &mut ExplorerQueryRunV1) { - let completed_at = now_micros(); - run.state = ExplorerRunStateV1::Cancelled; - run.finality = ExplorerFinalityV1::Cancelled; - run.completed_at_micros = Some(completed_at); - run.elapsed_micros = completed_at.saturating_sub(run.submitted_at_micros); - for source in &mut run.sources { - if source.outcome == ExplorerSourceOutcomeV1::Pending { - source.phase = ExplorerSourcePhaseV1::Cancelled; - source.outcome = ExplorerSourceOutcomeV1::Cancelled; - source.error_code = Some("request_cancelled"); - source.message = Some("dashboard request was cancelled".to_owned()); - } - } -} - -pub(super) fn mark_timed_out(run: &mut ExplorerQueryRunV1) { - let completed_at = now_micros(); - run.state = ExplorerRunStateV1::TimedOut; - run.finality = ExplorerFinalityV1::TimedOut; - run.completed_at_micros = Some(completed_at); - run.elapsed_micros = completed_at.saturating_sub(run.submitted_at_micros); - for source in &mut run.sources { - if source.outcome == ExplorerSourceOutcomeV1::Pending { - source.phase = ExplorerSourcePhaseV1::Completed; - source.outcome = ExplorerSourceOutcomeV1::TimedOut; - source.error_code = Some("request_deadline_elapsed"); - source.message = Some("dashboard request deadline elapsed".to_owned()); - } - } -} - -#[cfg(test)] -mod tests { - use super::*; - use crate::explorer_api::{ExplorerQueryRequestV1, initial_run}; - - fn pending_run() -> ExplorerQueryRunV1 { - initial_run( - "explorer-run.fixture".to_owned(), - ExplorerQueryRequestV1 { - query: "cache".to_owned(), - limit: 1, - offset: 0, - }, - ) - } - - #[test] - fn cancellation_is_terminal_for_run_and_pending_sources() { - let mut run = pending_run(); - mark_cancelled(&mut run); - - assert_eq!(run.state, ExplorerRunStateV1::Cancelled); - assert_eq!(run.finality, ExplorerFinalityV1::Cancelled); - assert!(run.sources.iter().all(|source| { - source.outcome == ExplorerSourceOutcomeV1::Cancelled - && source.error_code == Some("request_cancelled") - })); - } - - #[test] - fn deadline_is_terminal_for_run_and_pending_sources() { - let mut run = pending_run(); - mark_timed_out(&mut run); - - assert_eq!(run.state, ExplorerRunStateV1::TimedOut); - assert_eq!(run.finality, ExplorerFinalityV1::TimedOut); - assert!(run.sources.iter().all(|source| { - source.outcome == ExplorerSourceOutcomeV1::TimedOut - && source.error_code == Some("request_deadline_elapsed") - })); - } -} diff --git a/crates/tracedecay-dashboard-api/src/lib.rs b/crates/tracedecay-dashboard-api/src/lib.rs index 6ac69e3d79c..89f83c9648b 100644 --- a/crates/tracedecay-dashboard-api/src/lib.rs +++ b/crates/tracedecay-dashboard-api/src/lib.rs @@ -144,7 +144,6 @@ pub use http_admission::{ DashboardHttpRequestControlV1, RequestControl, RequestControlMissing, with_dashboard_http_admission, }; -pub use request_deadline::dashboard_http_request_deadline_micros; pub use routes::router; pub use server::{bind_dashboard, serve_http_connection, serve_loopback, validate_dashboard_host}; pub use state::{ diff --git a/crates/tracedecay-dashboard-api/src/project_gateway.rs b/crates/tracedecay-dashboard-api/src/project_gateway.rs index 2d4eb25fcdf..7c9a96aa37b 100644 --- a/crates/tracedecay-dashboard-api/src/project_gateway.rs +++ b/crates/tracedecay-dashboard-api/src/project_gateway.rs @@ -49,10 +49,12 @@ pub(super) async fn project_scoped_api_gateway( } let application_read = selected_project_application_read(req.method(), &tail); let event_delivery_ack = is_selected_project_event_delivery_ack(req.method(), &tail); + let explorer_read = req.method() == Method::POST && tail == "explorer/queries"; if runtime.active_project_id().as_deref() != Some(project_id.as_str()) && !matches!(req.method(), &Method::GET | &Method::HEAD) && application_read.is_none() && !event_delivery_ack + && !explorer_read { return gateway_problem( StatusCode::METHOD_NOT_ALLOWED, diff --git a/crates/tracedecay-dashboard-api/src/request_deadline.rs b/crates/tracedecay-dashboard-api/src/request_deadline.rs index dee670f1c56..1ed1266edd8 100644 --- a/crates/tracedecay-dashboard-api/src/request_deadline.rs +++ b/crates/tracedecay-dashboard-api/src/request_deadline.rs @@ -2,9 +2,8 @@ pub(super) const DASHBOARD_CODE_GRAPH_REQUEST_DEADLINE_MICROS: i64 = 30_000_000; pub(super) const DASHBOARD_AUTOMATION_RUN_REQUEST_DEADLINE_MICROS: i64 = 300_000_000; /// The deadline the admission layer binds to a request for `path`, in micros -/// from admission. Exposed so a caller polling a deferred run can wait for the -/// contract the runtime enforces instead of guessing a budget. -pub fn dashboard_http_request_deadline_micros(path: &str) -> i64 { +/// from admission. +pub(super) fn dashboard_http_request_deadline_micros(path: &str) -> i64 { let automation_run = path == "/api/application/retained/fact_store_curate" || one_segment_then( path, diff --git a/crates/tracedecay-dashboard-api/src/routes.rs b/crates/tracedecay-dashboard-api/src/routes.rs index d59da34ee1b..1e8505cfe32 100644 --- a/crates/tracedecay-dashboard-api/src/routes.rs +++ b/crates/tracedecay-dashboard-api/src/routes.rs @@ -297,11 +297,7 @@ pub(super) fn project_api_router() -> Router { "/api/settings/user/code-index-workers", patch(settings_api::patch_code_index_worker_settings), ) - .route("/api/explorer/queries", post(explorer_api::create_query)) - .route( - "/api/explorer/queries/{run_id}", - get(explorer_api::query_status).delete(explorer_api::cancel_query), - ) + .route("/api/explorer/queries", post(explorer_api::stream_query)) .route( "/api/explorer/sessions/{session_id}/size", get(explorer_api::session_size), diff --git a/crates/tracedecay/tests/dashboard_api_test/dashboard_api_support.rs b/crates/tracedecay/tests/dashboard_api_test/dashboard_api_support.rs index 5e9a0b1a57d..83e04b3db0a 100644 --- a/crates/tracedecay/tests/dashboard_api_test/dashboard_api_support.rs +++ b/crates/tracedecay/tests/dashboard_api_test/dashboard_api_support.rs @@ -910,6 +910,27 @@ pub(crate) fn post_json_body(agent: &ureq::Agent, url: &str, body: &Value) -> (u response_to_json(response) } +pub(crate) fn post_explorer_stream( + agent: &ureq::Agent, + url: &str, + body: &Value, +) -> (u16, Vec) { + let mut response = crate::common::http_call_with_retry(&format!("POST {url} (stream)"), || { + agent.post(url).send_json(body) + }); + let status = response.status().as_u16(); + let text = response + .body_mut() + .read_to_string() + .expect("explorer stream body"); + let frames = text + .lines() + .filter_map(|line| line.strip_prefix("data: ")) + .map(|data| serde_json::from_str(data).expect("explorer event JSON")) + .collect(); + (status, frames) +} + /// Binds `codex_bin` as the project's configured `codex` summarizer through /// the dashboard's application configuration routes: the automation backend /// spawns only the executable `lcm.summarizer_executables.v1` names. diff --git a/crates/tracedecay/tests/dashboard_api_test/explorer.rs b/crates/tracedecay/tests/dashboard_api_test/explorer.rs index 92e7bf2c956..546fd4927a4 100644 --- a/crates/tracedecay/tests/dashboard_api_test/explorer.rs +++ b/crates/tracedecay/tests/dashboard_api_test/explorer.rs @@ -1,38 +1,8 @@ -use std::time::{Duration, Instant}; - use crate::dashboard_api_support::*; use serde_json::{Value, json}; const EXPLORER_QUERY_ROUTE: &str = "/api/explorer/queries"; -/// A run reaches a terminal state by the deadline admission binds to its -/// create request, so the poll waits for that contract instead of a guess. -fn wait_for_query(agent: &ureq::Agent, base_url: &str, run_id: &str) -> Value { - let started = Instant::now(); - let deadline_micros = u64::try_from( - tracedecay_dashboard_api::dashboard_http_request_deadline_micros(EXPLORER_QUERY_ROUTE), - ) - .expect("dashboard admission deadlines are positive"); - let limit = Duration::from_micros(deadline_micros) + Duration::from_secs(5); - loop { - let (status, body) = get_json(agent, &format!("{base_url}{EXPLORER_QUERY_ROUTE}/{run_id}")); - assert_eq!(status, 200, "query status should resolve: {body}"); - if matches!( - body["payload"]["state"].as_str(), - Some("completed" | "partial" | "cancelled" | "timed_out" | "error") - ) { - return body; - } - let elapsed = started.elapsed(); - if elapsed >= limit { - panic!( - "explorer query {run_id} did not reach a terminal state after {elapsed:?}; last response: {body:?}" - ); - } - std::thread::sleep(Duration::from_millis(10)); - } -} - #[test] fn explorer_query_coordinates_real_sources_without_inventing_a_merge() { let runtime = create_runtime(); @@ -40,44 +10,27 @@ fn explorer_query_coordinates_real_sources_without_inventing_a_merge() { let fixture = start_dashboard_fixture(true).await; let agent = http_agent(); - let (status, accepted) = post_json_body( + let (status, frames) = post_explorer_stream( &agent, &format!("{}{EXPLORER_QUERY_ROUTE}", fixture.base_url), &json!({"query": "cache", "limit": 25, "offset": 0}), ); - assert_eq!(status, 202, "query should be admitted: {accepted}"); - assert_eq!(accepted["schema_revision"], 1); - assert_eq!(accepted["domain_state"], "loading"); - assert_eq!(accepted["payload"]["state"], "pending"); - assert_eq!( - accepted["payload"]["required_source_ids"], - json!(["code_graph", "sessions", "knowledge"]) - ); - assert_eq!( - accepted["payload"]["ordering_policy"], - "source_local_no_cross_source_merge" - ); - let run_id = accepted["payload"]["run_id"] - .as_str() - .unwrap_or_else(|| panic!("accepted query needs a run id: {accepted}")); - - let completed = wait_for_query(&agent, &fixture.base_url, run_id); + assert_eq!(status, 200, "query should stream: {frames:?}"); + assert_eq!(frames.len(), 4, "three sources and one terminal event"); + assert!(frames[..3].iter().all(|frame| frame["kind"] == "source")); + let completed = &frames[3]; // Every source answers, but the canonical temporal search carries no // denominator, so the run truthfully stays partial rather than // claiming complete coverage it cannot account for. - assert_eq!(completed["domain_state"], "partial", "{completed}"); - assert_eq!(completed["payload"]["state"], "partial"); - assert_eq!(completed["payload"]["finality"], "partial"); - let sources = completed["payload"]["sources"] - .as_array() - .unwrap_or_else(|| panic!("query sources missing: {completed}")); + assert_eq!(completed["kind"], "final"); + assert_eq!(completed["state"], "partial"); + let sources: Vec<&Value> = frames[..3].iter().map(|frame| &frame["source"]).collect(); assert_eq!(sources.len(), 3); for source_id in ["code_graph", "sessions", "knowledge"] { let source = sources .iter() .find(|source| source["source_id"] == source_id) .unwrap_or_else(|| panic!("missing {source_id} source: {completed}")); - assert_eq!(source["phase"], "completed"); assert_eq!( source["outcome"], "ready", "{source_id} source must be ready: {source}" @@ -132,7 +85,7 @@ fn explorer_query_coordinates_real_sources_without_inventing_a_merge() { "knowledge page should contain the seeded cache fact: {knowledge}" ); assert!( - completed["payload"].get("merged_results").is_none(), + completed.get("merged_results").is_none(), "the coordinator must not invent a cross-source merge" ); }); diff --git a/crates/tracedecay/tests/dashboard_api_test/graph.rs b/crates/tracedecay/tests/dashboard_api_test/graph.rs index a931114c718..ff878af7d44 100644 --- a/crates/tracedecay/tests/dashboard_api_test/graph.rs +++ b/crates/tracedecay/tests/dashboard_api_test/graph.rs @@ -5,7 +5,7 @@ use crate::common::{ canonicalize_test_dir, create_runtime, get_json, http_agent, isolated_profile_under_home, tempdir_or_panic, wait_for_dashboard, }; -use crate::dashboard_api_support::{post_json_body, rg_word_paths, write_file}; +use crate::dashboard_api_support::{post_explorer_stream, rg_word_paths, write_file}; use crate::runtime::DashboardTestRuntimeV1; use serde_json::Value; use tempfile::TempDir; @@ -1382,38 +1382,17 @@ fn graph_reads_answer_a_generation_larger_than_a_whole_census_page() { "the seeded slice reaches the seed's callee: {seeded}" ); - let (status, accepted) = post_json_body( + let (status, frames) = post_explorer_stream( &agent, &format!("{}/api/explorer/queries", fixture.base_url), &serde_json::json!({"query": "bulk_symbol", "limit": 25, "offset": 0}), ); - assert_eq!(status, 202, "{accepted}"); - let run_id = accepted["payload"]["run_id"] - .as_str() - .unwrap_or_else(|| panic!("accepted query needs a run id: {accepted}")) - .to_owned(); - let code_lane = (0..500) - .find_map(|_| { - let (status, body) = get_json( - &agent, - &format!("{}/api/explorer/queries/{run_id}", fixture.base_url), - ); - assert_eq!(status, 200, "{body}"); - let lane = body["payload"]["sources"] - .as_array() - .and_then(|sources| { - sources - .iter() - .find(|source| source["source_id"] == "code_graph") - }) - .filter(|source| source["phase"] == "completed") - .cloned(); - if lane.is_none() { - std::thread::sleep(std::time::Duration::from_millis(10)); - } - lane - }) - .unwrap_or_else(|| panic!("explorer code lane never completed")); + assert_eq!(status, 200, "{frames:?}"); + let code_lane = frames + .iter() + .filter_map(|frame| frame.get("source")) + .find(|source| source["source_id"] == "code_graph") + .unwrap_or_else(|| panic!("explorer code lane never completed: {frames:?}")); assert_eq!(code_lane["outcome"], "ready", "{code_lane}"); assert_eq!( code_lane["page"]["rows"].as_array().map(Vec::len), diff --git a/crates/tracedecay/tests/dashboard_api_test/projects.rs b/crates/tracedecay/tests/dashboard_api_test/projects.rs index 560e31d0131..ac1c7c9bc01 100644 --- a/crates/tracedecay/tests/dashboard_api_test/projects.rs +++ b/crates/tracedecay/tests/dashboard_api_test/projects.rs @@ -261,6 +261,92 @@ fn project_scoped_plugin_routes_read_selected_project_store() { }), "graph fact identities must remain canonical strings: {selected_payload}" ); + + let query = serde_json::json!({"query": "selector", "limit": 10, "offset": 0}); + let (selected_status, selected_frames) = post_explorer_stream( + &agent, + &format!( + "{}/api/projects/{target_project_id}/explorer/queries", + fixture.base_url + ), + &query, + ); + assert_eq!(selected_status, 200, "{selected_frames:?}"); + let selected_knowledge = selected_frames + .iter() + .filter_map(|frame| frame.get("source")) + .find(|source| source["source_id"] == "knowledge") + .expect("selected project knowledge frame"); + assert!( + selected_knowledge["page"]["rows"].as_array().is_some_and(|rows| { + rows.iter().any(|row| row["fact_id"] == target_fact_id.as_str()) + }), + "selected Explorer stream must use the selected store: {selected_frames:?}" + ); + + let (active_status, active_frames) = post_explorer_stream( + &agent, + &format!("{}/api/explorer/queries", fixture.base_url), + &query, + ); + assert_eq!(active_status, 200); + let active_knowledge = active_frames + .iter() + .filter_map(|frame| frame.get("source")) + .find(|source| source["source_id"] == "knowledge") + .expect("active project knowledge frame"); + assert!( + active_knowledge["page"]["rows"].as_array().is_some_and(|rows| { + rows.iter().all(|row| row["fact_id"] != target_fact_id.as_str()) + }), + "active store must not alias selected knowledge: {active_frames:?}" + ); + + let selected_source = |source_id: &str| { + selected_frames + .iter() + .filter_map(|frame| frame.get("source")) + .find(|source| source["source_id"] == source_id) + .unwrap_or_else(|| panic!("selected project {source_id} frame: {selected_frames:?}")) + }; + let selected_code = selected_source("code_graph"); + assert_eq!(selected_code["outcome"], "unavailable", "{selected_frames:?}"); + assert_eq!(selected_code["error_code"], "missing_registry"); + assert!(selected_code["page"].is_null()); + let selected_sessions = selected_source("sessions"); + assert_eq!( + selected_sessions["outcome"], "unavailable", + "{selected_frames:?}" + ); + assert_eq!( + selected_sessions["error_code"], + "lcm_daemon_authority_unavailable" + ); + assert!(selected_sessions["page"].is_null()); + + let (settings_status, settings_body) = patch_json_body( + &agent, + &format!( + "{}/api/projects/{target_project_id}/settings/project", + fixture.base_url + ), + &serde_json::json!({ "patch": {} }), + ); + assert_eq!(settings_status, 405, "{settings_body}"); + assert_eq!(settings_body["status"], "read_only_project"); + + let foreign = crate::common::http_call_with_retry("foreign Explorer POST", || { + agent + .post(&format!( + "{}/api/projects/dashboard_fixture_unregistered/explorer/queries", + fixture.base_url + )) + .send_json(&query) + }); + let (foreign_status, foreign_body) = crate::common::response_to_json(foreign); + assert_eq!(foreign_status, 404, "{foreign_body}"); + assert_eq!(foreign_body["status"], "not_found"); + assert!(!foreign_body.to_string().contains(&target_fact_id.to_string())); }); } diff --git a/dashboard/codegen/schemas/dashboard-contracts.schema.json b/dashboard/codegen/schemas/dashboard-contracts.schema.json index 9c94dde7ee3..ea507c3ae14 100644 --- a/dashboard/codegen/schemas/dashboard-contracts.schema.json +++ b/dashboard/codegen/schemas/dashboard-contracts.schema.json @@ -13555,117 +13555,46 @@ ], "type": "string" }, - "ExplorerFinalityV1": { - "enum": [ - "pending", - "complete", - "partial", - "cancelled", - "timed_out", - "error" - ], - "type": "string" - }, - "ExplorerQueryRequestV1": { - "additionalProperties": false, - "properties": { - "limit": { - "default": 25, - "format": "int64", - "type": "integer" - }, - "offset": { - "default": 0, - "format": "int64", - "type": "integer" - }, - "query": { - "type": "string" - } - }, - "required": [ - "query", - "limit", - "offset" - ], - "type": "object" - }, - "ExplorerQueryRunV1": { - "properties": { - "completed_at_micros": { - "format": "int64", - "type": [ - "integer", - "null" - ] - }, - "elapsed_micros": { - "format": "int64", - "type": "integer" - }, - "explanation": { - "type": "string" - }, - "finality": { - "$ref": "#/$defs/ExplorerFinalityV1" - }, - "merge_revision": { - "type": "string" - }, - "ordering_policy": { - "type": "string" - }, - "plan_revision": { - "type": "string" - }, - "request": { - "$ref": "#/$defs/ExplorerQueryRequestV1" - }, - "request_revision": { - "type": "string" - }, - "required_source_ids": { - "items": { - "$ref": "#/$defs/ExplorerSourceIdV1" + "ExplorerQueryEventV1": { + "oneOf": [ + { + "properties": { + "kind": { + "const": "source", + "type": "string" + }, + "source": { + "$ref": "#/$defs/ExplorerSourceProgressV1" + } }, - "maxItems": 3, - "minItems": 3, - "type": "array" - }, - "run_id": { - "type": "string" + "required": [ + "kind", + "source" + ], + "type": "object" }, - "sources": { - "items": { - "$ref": "#/$defs/ExplorerSourceProgressV1" + { + "properties": { + "elapsed_micros": { + "format": "int64", + "type": "integer" + }, + "kind": { + "const": "final", + "type": "string" + }, + "state": { + "$ref": "#/$defs/ExplorerRunStateV1" + } }, - "type": "array" - }, - "state": { - "$ref": "#/$defs/ExplorerRunStateV1" - }, - "submitted_at_micros": { - "format": "int64", - "type": "integer" + "required": [ + "kind", + "state", + "elapsed_micros" + ], + "type": "object" } - }, - "required": [ - "run_id", - "request", - "request_revision", - "plan_revision", - "merge_revision", - "required_source_ids", - "ordering_policy", - "explanation", - "submitted_at_micros", - "completed_at_micros", - "elapsed_micros", - "state", - "finality", - "sources" - ], - "type": "object" + ] }, "ExplorerReadContextV1": { "properties": { @@ -13769,7 +13698,6 @@ }, "ExplorerRunStateV1": { "enum": [ - "pending", "completed", "partial", "cancelled", @@ -13855,7 +13783,6 @@ "ExplorerSourceOutcomeV1": { "description": "What one source truthfully concluded for this run. Every member has a real\nproducer; none is speculative:\n- `Partial`: the source answered with rows but its own read reported\n omitted records (LCM temporal reads).\n- `Stale`: the source's store exists but does not match the current\n generation (verified graph stale reads, LCM stale projections).\n- `TimedOut`: the source's own read exceeded the admitted deadline.", "enum": [ - "pending", "ready", "partial", "stale", @@ -13866,15 +13793,6 @@ ], "type": "string" }, - "ExplorerSourcePhaseV1": { - "enum": [ - "queued", - "reading", - "completed", - "cancelled" - ], - "type": "string" - }, "ExplorerSourceProgressV1": { "properties": { "completed_units": { @@ -13916,9 +13834,6 @@ } ] }, - "phase": { - "$ref": "#/$defs/ExplorerSourcePhaseV1" - }, "source_id": { "$ref": "#/$defs/ExplorerSourceIdV1" }, @@ -13943,7 +13858,6 @@ "required": [ "source_id", "source_label", - "phase", "outcome", "completed_units", "total_units", @@ -37006,8 +36920,8 @@ "envelope": { "$ref": "#/$defs/DashboardEnvelopeV1" }, - "explorer_query_run": { - "$ref": "#/$defs/ExplorerQueryRunV1" + "explorer_query_event": { + "$ref": "#/$defs/ExplorerQueryEventV1" }, "explorer_read_context": { "$ref": "#/$defs/DashboardEnvelopeV13" @@ -37378,7 +37292,7 @@ "storage_telemetry", "doctor_findings", "remote_operational_status", - "explorer_query_run", + "explorer_query_event", "explorer_session_size", "explorer_read_context", "projects", diff --git a/dashboard/src/contracts/decoders.ts b/dashboard/src/contracts/decoders.ts index c7f0aa755f0..b38a8a66daa 100644 --- a/dashboard/src/contracts/decoders.ts +++ b/dashboard/src/contracts/decoders.ts @@ -314,9 +314,7 @@ import type { ExecutionTopologyMetricsV1, ExecutionTopologyViewV1, ExecutionWidthBucketV1, - ExplorerFinalityV1, - ExplorerQueryRequestV1, - ExplorerQueryRunV1, + ExplorerQueryEventV1, ExplorerReadContextV1, ExplorerResultPageV1, ExplorerRunStateV1, @@ -324,7 +322,6 @@ import type { ExplorerSessionSizeV1, ExplorerSourceIdV1, ExplorerSourceOutcomeV1, - ExplorerSourcePhaseV1, ExplorerSourceProgressV1, FactArmCoverageV1, FactAssertionId, @@ -4737,49 +4734,14 @@ export const ExecutionTopologyViewV1Schema: z.ZodType = z.enum(["from17_to32", "from33_to64", "from3_to4", "from5_to8", "from9_to16", "one", "over64", "two", "zero"]); -export const ExplorerFinalityV1Schema: z.ZodEnum<{ "cancelled": "cancelled"; "complete": "complete"; "error": "error"; "partial": "partial"; "pending": "pending"; "timed_out": "timed_out" }> = z.enum(["cancelled", "complete", "error", "partial", "pending", "timed_out"]); - -export const ExplorerQueryRequestV1Schema: z.ZodObject<{ - limit: z.ZodType; - offset: z.ZodType; - query: z.ZodType; -}, z.core.$strict> = z.object({ - limit: z.number().int(), - offset: z.number().int(), - query: z.string(), -}).strict(); - -export const ExplorerQueryRunV1Schema: z.ZodObject<{ - completed_at_micros: z.ZodType; - elapsed_micros: z.ZodType; - explanation: z.ZodType; - finality: z.ZodType; - merge_revision: z.ZodType; - ordering_policy: z.ZodType; - plan_revision: z.ZodType; - request: z.ZodType; - request_revision: z.ZodType; - required_source_ids: z.ZodType, unknown>; - run_id: z.ZodType; - sources: z.ZodType, unknown>; - state: z.ZodType; - submitted_at_micros: z.ZodType; -}> = z.object({ - completed_at_micros: z.number().int().nullable(), +export const ExplorerQueryEventV1Schema: z.ZodType = z.discriminatedUnion("kind", [z.object({ elapsed_micros: z.number().int(), - explanation: z.string(), - finality: z.lazy(() => ExplorerFinalityV1Schema), - merge_revision: z.string(), - ordering_policy: z.string(), - plan_revision: z.string(), - request: z.lazy(() => ExplorerQueryRequestV1Schema), - request_revision: z.string(), - required_source_ids: z.array(z.lazy(() => ExplorerSourceIdV1Schema)), - run_id: z.string(), - sources: z.array(z.lazy(() => ExplorerSourceProgressV1Schema)), + kind: z.literal("final"), state: z.lazy(() => ExplorerRunStateV1Schema), - submitted_at_micros: z.number().int(), -}); +}), z.object({ + kind: z.literal("source"), + source: z.lazy(() => ExplorerSourceProgressV1Schema), +})]); export const ExplorerReadContextV1Schema: z.ZodObject<{ counts: z.ZodType; @@ -4823,7 +4785,7 @@ export const ExplorerResultPageV1Schema: z.ZodObject<{ total: z.number().int().min(0).nullable(), }); -export const ExplorerRunStateV1Schema: z.ZodEnum<{ "cancelled": "cancelled"; "completed": "completed"; "error": "error"; "partial": "partial"; "pending": "pending"; "timed_out": "timed_out" }> = z.enum(["cancelled", "completed", "error", "partial", "pending", "timed_out"]); +export const ExplorerRunStateV1Schema: z.ZodEnum<{ "cancelled": "cancelled"; "completed": "completed"; "error": "error"; "partial": "partial"; "timed_out": "timed_out" }> = z.enum(["cancelled", "completed", "error", "partial", "timed_out"]); export const ExplorerSessionCountsV1Schema: z.ZodObject<{ message_count: z.ZodType; @@ -4860,9 +4822,7 @@ producer; none is speculative: - `Stale`: the source's store exists but does not match the current generation (verified graph stale reads, LCM stale projections). - `TimedOut`: the source's own read exceeded the admitted deadline. */ -export const ExplorerSourceOutcomeV1Schema: z.ZodEnum<{ "cancelled": "cancelled"; "error": "error"; "partial": "partial"; "pending": "pending"; "ready": "ready"; "stale": "stale"; "timed_out": "timed_out"; "unavailable": "unavailable" }> = z.enum(["cancelled", "error", "partial", "pending", "ready", "stale", "timed_out", "unavailable"]); - -export const ExplorerSourcePhaseV1Schema: z.ZodEnum<{ "cancelled": "cancelled"; "completed": "completed"; "queued": "queued"; "reading": "reading" }> = z.enum(["cancelled", "completed", "queued", "reading"]); +export const ExplorerSourceOutcomeV1Schema: z.ZodEnum<{ "cancelled": "cancelled"; "error": "error"; "partial": "partial"; "ready": "ready"; "stale": "stale"; "timed_out": "timed_out"; "unavailable": "unavailable" }> = z.enum(["cancelled", "error", "partial", "ready", "stale", "timed_out", "unavailable"]); export const ExplorerSourceProgressV1Schema: z.ZodObject<{ completed_units: z.ZodType; @@ -4872,7 +4832,6 @@ export const ExplorerSourceProgressV1Schema: z.ZodObject<{ message: z.ZodType; outcome: z.ZodType; page: z.ZodType; - phase: z.ZodType; source_id: z.ZodType; source_label: z.ZodType; total_units: z.ZodType; @@ -4885,7 +4844,6 @@ export const ExplorerSourceProgressV1Schema: z.ZodObject<{ message: z.string().nullable(), outcome: z.lazy(() => ExplorerSourceOutcomeV1Schema), page: z.union([z.lazy(() => ExplorerResultPageV1Schema), z.null()]), - phase: z.lazy(() => ExplorerSourcePhaseV1Schema), source_id: z.lazy(() => ExplorerSourceIdV1Schema), source_label: z.string(), total_units: z.number().int().min(0).nullable(), diff --git a/dashboard/src/contracts/types.ts b/dashboard/src/contracts/types.ts index ba47628bb41..febb095caae 100644 --- a/dashboard/src/contracts/types.ts +++ b/dashboard/src/contracts/types.ts @@ -2483,30 +2483,16 @@ export type ExecutionTopologyViewV1 = export type ExecutionWidthBucketV1 = "from17_to32" | "from33_to64" | "from3_to4" | "from5_to8" | "from9_to16" | "one" | "over64" | "two" | "zero"; -export type ExplorerFinalityV1 = "cancelled" | "complete" | "error" | "partial" | "pending" | "timed_out"; - -export type ExplorerQueryRequestV1 = { - limit: number; - offset: number; - query: string; -}; - -export type ExplorerQueryRunV1 = { - completed_at_micros: number | null; - elapsed_micros: number; - explanation: string; - finality: ExplorerFinalityV1; - merge_revision: string; - ordering_policy: string; - plan_revision: string; - request: ExplorerQueryRequestV1; - request_revision: string; - required_source_ids: Array; - run_id: string; - sources: Array; - state: ExplorerRunStateV1; - submitted_at_micros: number; -}; +export type ExplorerQueryEventV1 = + | { + elapsed_micros: number; + kind: "final"; + state: ExplorerRunStateV1; + } + | { + kind: "source"; + source: ExplorerSourceProgressV1; + }; export type ExplorerReadContextV1 = { counts: ExplorerSessionCountsV1; @@ -2531,7 +2517,7 @@ export type ExplorerResultPageV1 = { total: number | null; }; -export type ExplorerRunStateV1 = "cancelled" | "completed" | "error" | "partial" | "pending" | "timed_out"; +export type ExplorerRunStateV1 = "cancelled" | "completed" | "error" | "partial" | "timed_out"; export type ExplorerSessionCountsV1 = { message_count: number; @@ -2550,9 +2536,7 @@ export type ExplorerSessionSizeV1 = { export type ExplorerSourceIdV1 = "code_graph" | "knowledge" | "sessions"; -export type ExplorerSourceOutcomeV1 = "cancelled" | "error" | "partial" | "pending" | "ready" | "stale" | "timed_out" | "unavailable"; - -export type ExplorerSourcePhaseV1 = "cancelled" | "completed" | "queued" | "reading"; +export type ExplorerSourceOutcomeV1 = "cancelled" | "error" | "partial" | "ready" | "stale" | "timed_out" | "unavailable"; export type ExplorerSourceProgressV1 = { completed_units: number | null; @@ -2562,7 +2546,6 @@ export type ExplorerSourceProgressV1 = { message: string | null; outcome: ExplorerSourceOutcomeV1; page: ExplorerResultPageV1 | null; - phase: ExplorerSourcePhaseV1; source_id: ExplorerSourceIdV1; source_label: string; total_units: number | null; diff --git a/dashboard/src/data/scope/store.test.ts b/dashboard/src/data/scope/store.test.ts index 5e06dd12339..875dca4ff37 100644 --- a/dashboard/src/data/scope/store.test.ts +++ b/dashboard/src/data/scope/store.test.ts @@ -20,6 +20,7 @@ import { READ_ONLY_SCOPE_STATUS, UNSCOPED_CACHE_KEY, activationFor, + explorerReadScope, launchBindingCaption, readOnlyScopeRefusal, reconciledLabel, @@ -104,6 +105,14 @@ describe('scopeWritable', () => { expect(writability.reason).toContain('Switch scope'); }); + it('admits only a registered selected Explorer read without granting a write', () => { + const selected = project('proj_b', 'selected'); + expect(scopeWritable(selected).state).toBe('read_only'); + expect(explorerReadScope(selected)).toEqual({ state: 'writable', target: 'label-proj_b' }); + expect(explorerReadScope(project('proj_b', 'unresolved')).state).toBe('unknown'); + expect(explorerReadScope(project('proj_ghost', 'absent')).state).toBe('read_only'); + }); + // Guessing either way is a defect: `writable` offers a write that will be // refused, `read_only` withdraws one that would have worked. it('reports an unresolved deep-link scope as unknown, neither writable nor read-only', () => { diff --git a/dashboard/src/data/scope/store.ts b/dashboard/src/data/scope/store.ts index 657cd32f61c..d9d9397bf2a 100644 --- a/dashboard/src/data/scope/store.ts +++ b/dashboard/src/data/scope/store.ts @@ -5,8 +5,8 @@ import { z } from 'zod'; * Whether the selected project is the one the daemon is actually serving. * * This is a scope fact, not a cosmetic one: the project gateway - * (`src/dashboard/mod.rs` `project_scoped_api_gateway`) refuses every - * non-GET/HEAD request for a project that is not the active one. So a control + * (`crates/tracedecay-dashboard-api/src/project_gateway.rs`) refuses mutations + * for a project that is not the active one. So a control * that can write under one selected project cannot write under another, and * the difference is invisible from the project id alone. * @@ -214,10 +214,9 @@ export function scopedWorkspacePath(scope: DashboardScope, path: string): string * reading with its own sentence, so a control can stay disabled while saying * that the reason is a pending registry read rather than a refusal. * - * The question is specifically whether a *mutation* is accepted. Three - * POST-shaped reads (`feedback/get|expand|list`) are exempt in the gateway - * because they change nothing, so a panel that only reads must not consult - * this and disable itself against a refusal that will not happen. + * The question is specifically whether a mutation is accepted. POST-shaped + * reads, including Explorer queries, have their own gateway admission and + * must not use this predicate to decide whether they can read. */ export type ScopeWritability = | { state: 'writable'; target: string } @@ -266,6 +265,14 @@ export function scopeWritable(scope: DashboardScope): ScopeWritability { } } +/** Explorer's POST starts a read and is admitted for an exact registered project. */ +export function explorerReadScope(scope: DashboardScope): ScopeWritability { + if (scope.kind === 'project' && scope.activation === 'selected') { + return { state: 'writable', target: scope.label }; + } + return scopeWritable(scope); +} + /** * The sentence a control carries about what this scope means for it. * diff --git a/dashboard/src/workspaces/explorer/ExplorerPage.dom.test.tsx b/dashboard/src/workspaces/explorer/ExplorerPage.dom.test.tsx index a156acf9eff..cbf45e103c6 100644 --- a/dashboard/src/workspaces/explorer/ExplorerPage.dom.test.tsx +++ b/dashboard/src/workspaces/explorer/ExplorerPage.dom.test.tsx @@ -1,5 +1,5 @@ import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; -import { render, screen, waitFor, within } from '@testing-library/react'; +import { act, render, screen, waitFor, within } from '@testing-library/react'; import userEvent from '@testing-library/user-event'; import { MemoryRouter, Route, Routes, useLocation } from 'react-router'; import { afterEach, describe, expect, it, vi } from 'vitest'; @@ -10,10 +10,27 @@ import { ExplorerPage } from './ExplorerPage.tsx'; type Route = { status: number; body: unknown }; function serve(routes: Record) { - return vi.fn(async (input: RequestInfo | URL, _init?: RequestInit) => { + return vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => { const url = String(input); const hit = Object.entries(routes).find(([path]) => url.includes(path)); const response = hit?.[1] ?? { status: 404, body: { error: 'not found' } }; + if (url.includes('/explorer/queries') && init?.method === 'POST' && response.status === 200) { + const body = response.body as ReturnType; + const encoder = new TextEncoder(); + return new Response(new ReadableStream({ + start(controller) { + for (const item of body.sources) { + controller.enqueue(encoder.encode(`data: ${JSON.stringify({ kind: 'source', source: item })}\n\n`)); + } + if (body.state !== 'pending') { + controller.enqueue(encoder.encode(`data: ${JSON.stringify({ + kind: 'final', state: body.state, elapsed_micros: 9, + })}\n\n`)); + controller.close(); + } + }, + }), { status: 200, headers: { 'content-type': 'text/event-stream' } }); + } return { ok: response.status >= 200 && response.status < 300, status: response.status, @@ -98,7 +115,6 @@ function source(sourceId: SourceId, rows: Record[], total: numb return { source_id: sourceId, source_label: SOURCE_LABELS[sourceId], - phase: 'completed', outcome: 'ready', completed_units: rows.length, total_units: total, @@ -130,80 +146,30 @@ function source(sourceId: SourceId, rows: Record[], total: numb }; } -/** A source the coordinator is still reading. */ -function reading(sourceId: SourceId) { - const base = source(sourceId, [], null); - return { - ...base, - phase: 'reading', - outcome: 'pending', - completed_units: null, - total_units: null, - page: null, - }; -} - -type RunState = 'pending' | 'partial' | 'completed'; +/** A source the coordinator is still reading is expressed by its absence: the + * stream carries no frame for it until it concludes. */ +type StreamState = 'pending' | 'partial' | 'completed'; -function plannerEnvelope( - sources: unknown[] = [ +function streamFixture( + sources: Array | ReturnType> = [ source('code_graph', [CODE_ROW], 1), source('sessions', [MESSAGE_ROW, SUMMARY_ROW], 2), source('knowledge', [FACT_ROW], null), ], - state: RunState = 'partial', + state: StreamState = 'partial', query = 'graph', ) { - const domainState = state === 'completed' ? 'ready' : state === 'pending' ? 'loading' : 'partial'; + return { query, state, sources }; +} + +function temporalRetrievalUnavailableEnvelope() { return { schema_revision: 1, - scope: { - project_id: 'project.explorer', - storage_mode: 'profile_sharded', - store_root: '/data/project', - }, + scope: { project_id: 'project.explorer', storage_mode: 'profile_sharded', store_root: '/data/project' }, version: { entity_version: null, graph_version: null }, time: { valid_time_micros: null, observation_time_micros: 10 }, source_watermark: null, authorization: { outcome: 'authorized' }, - coverage: { - completeness: state === 'completed' ? 'complete' : 'partial', - eligible: 4, - examined: state === 'completed' ? 4 : 3, - matched: null, - excluded: null, - omitted: state === 'completed' ? 0 : 1, - unknown: null, - denominator: 4, - unit: 'sources', - omission_reasons: state === 'completed' ? [] : ['knowledge coverage is unknown'], - }, - freshness: { state: 'unknown', observed_at_micros: null, watermark: null }, - domain_state: domainState, - legal_actions: [], - payload: { - run_id: 'explorer-run-fixture', - request: { query, limit: 50, offset: 0 }, - request_revision: 'explorer-query-request-v1', - plan_revision: 'explorer-query-plan-v1', - merge_revision: 'source-local-no-merge-v1', - required_source_ids: ['code_graph', 'sessions', 'knowledge'], - ordering_policy: 'source_local_no_cross_source_merge', - explanation: - 'Search the code graph, active-project session store, and bounded project fact authority in parallel; preserve each source own order and coverage.', - submitted_at_micros: 1, - completed_at_micros: state === 'pending' ? null : 10, - elapsed_micros: 9, - state, - finality: state === 'completed' ? 'complete' : state === 'pending' ? 'pending' : 'partial', - sources, - }, - }; -} - -function temporalRetrievalUnavailableEnvelope() { - return { - ...plannerEnvelope(), coverage: { completeness: 'unknown', eligible: null, @@ -218,6 +184,7 @@ function temporalRetrievalUnavailableEnvelope() { }, freshness: { state: 'unknown', observed_at_micros: null, watermark: null }, domain_state: 'unknown', + legal_actions: [], payload: null, }; } @@ -233,7 +200,7 @@ const SEARCH_ROUTES = { }, '/api/explorer/queries': { status: 200, - body: plannerEnvelope(), + body: streamFixture(), }, // Browse reads are the same canonical overview envelopes the visual-audit // fixtures serve, so a browse row here is one the daemon's contract admits. @@ -259,7 +226,7 @@ afterEach(() => { /** A source that reached a terminal outcome without returning a page. */ function withoutAnswer( sourceId: SourceId, - outcome: 'unavailable' | 'cancelled' | 'error', + outcome: 'unavailable' | 'cancelled' | 'error' | 'stale', code: string, message: string, ) { @@ -267,6 +234,8 @@ function withoutAnswer( return { ...base, outcome, + freshness: 'unknown', + watermark: null, completed_units: null, total_units: null, coverage: { @@ -274,7 +243,13 @@ function withoutAnswer( completeness: 'unknown', eligible: null, examined: null, + matched: null, + excluded: null, + omitted: null, + unknown: null, denominator: null, + unit: sourceId === 'sessions' ? 'messages' : sourceId === 'knowledge' ? 'facts' : 'symbols', + omission_reasons: [message], }, error_code: code, message, @@ -298,12 +273,56 @@ async function search(query = 'graph') { } describe('ExplorerPage independent lane lifecycle', () => { + it('explorer_partial_source_remains_visible_during_other_read', async () => { + let finish!: () => void; + const base = serve(SEARCH_ROUTES); + const fetchImpl = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => { + if (!String(input).endsWith('/api/explorer/queries') || init?.method !== 'POST') { + return base(input, init); + } + const encoder = new TextEncoder(); + return new Response(new ReadableStream({ + start(controller) { + const send = (event: unknown) => + controller.enqueue(encoder.encode(`data: ${JSON.stringify(event)}\n\n`)); + send({ kind: 'source', source: source('code_graph', [CODE_ROW], 1) }); + finish = () => { + send({ + kind: 'source', + source: withoutAnswer('sessions', 'stale', 'session_projection_stale', 'session projection is stale'), + }); + send({ + kind: 'source', + source: unavailable('knowledge', 'fact_store_unavailable', 'facts are unavailable'), + }); + send({ kind: 'final', state: 'partial', elapsed_micros: 9000 }); + controller.close(); + }; + }, + }), { status: 200, headers: { 'content-type': 'text/event-stream' } }); + }); + mount(fetchImpl); + await search(); + await screen.findByRole('button', { name: /graph_search/ }); + expect(lane('Sessions').getAttribute('data-lane-state')).toBe('pending'); + expect(screen.getByRole('img', { name: '1 of 3 sources concluded' })).toBeTruthy(); + expect(document.querySelector('[data-run-register]')?.textContent).not.toMatch(/\d+ ms/); + await act(async () => { finish(); }); + await waitFor(() => { + expect(lane('Sessions').getAttribute('data-lane-state')).toBe('stale'); + expect(lane('Knowledge').getAttribute('data-lane-state')).toBe('unavailable'); + expect(document.querySelector('[data-run-register]')?.getAttribute('data-run-state')).toBe('partial'); + }); + expect(document.querySelector('[data-run-register]')?.textContent).toMatch(/9 ms/); + expect(screen.getByRole('button', { name: /graph_search/ })).toBeTruthy(); + }); + it('draws three lanes, and a ready lane never makes an unavailable neighbour look ready', async () => { renderExplorer({ ...SEARCH_ROUTES, '/api/explorer/queries': { status: 200, - body: plannerEnvelope( + body: streamFixture( [ source('code_graph', [CODE_ROW], 1), source('sessions', [MESSAGE_ROW, SUMMARY_ROW], 2), @@ -343,8 +362,8 @@ describe('ExplorerPage independent lane lifecycle', () => { ...SEARCH_ROUTES, '/api/explorer/queries': { status: 200, - body: plannerEnvelope( - [source('code_graph', [CODE_ROW], 1), reading('sessions'), reading('knowledge')], + body: streamFixture( + [source('code_graph', [CODE_ROW], 1)], 'pending', ), }, @@ -354,7 +373,7 @@ describe('ExplorerPage independent lane lifecycle', () => { expect(lane('Code').getAttribute('data-lane-state')).toBe('ready'); expect(lane('Sessions').getAttribute('data-lane-state')).toBe('pending'); - expect(within(lane('Sessions')).getByText('Reading')).toBeTruthy(); + expect(within(lane('Sessions')).getAllByText('Loading').length).toBeGreaterThan(0); // Progress is counted in sources concluded, the only figure with a real // denominator, and the explicit cancel is offered while the run is live. expect(screen.getByRole('img', { name: '1 of 3 sources concluded' })).toBeTruthy(); @@ -366,8 +385,8 @@ describe('ExplorerPage independent lane lifecycle', () => { ...SEARCH_ROUTES, '/api/explorer/queries': { status: 200, - body: plannerEnvelope( - [source('code_graph', [CODE_ROW], 1), reading('sessions'), reading('knowledge')], + body: streamFixture( + [source('code_graph', [CODE_ROW], 1)], 'pending', ), }, @@ -385,49 +404,36 @@ describe('ExplorerPage independent lane lifecycle', () => { await user.click(cancel); await waitFor(() => { - expect( - fetchImpl.mock.calls.some( - ([input, init]) => - String(input).includes('/api/explorer/queries/explorer-run-fixture') && - init?.method === 'DELETE', - ), - ).toBe(true); + expect(screen.queryByRole('button', { name: 'Cancel' })).toBeNull(); }); + expect(fetchImpl.mock.calls.find(([, init]) => init?.method === 'POST')?.[1]?.signal?.aborted).toBe(true); }); }); describe('ExplorerPage scope truth', () => { - it('refuses to run a query under a selected non-active project and dispatches nothing', async () => { + it('selected_project_stream_does_not_use_active_project', async () => { useScope.getState().selectProject('proj_other', 'Other project', 'selected'); - const fetchImpl = serve(SEARCH_ROUTES); + const fetchImpl = serve({ + ...SEARCH_ROUTES, + '/api/projects/proj_other/explorer/queries': { + status: 200, + body: streamFixture([source('code_graph', [{ ...CODE_ROW, name: 'selected_graph' }], 1)]), + }, + }); mount(fetchImpl); await search(); - - // Every source lane carries the scope authority's own refusal; nothing - // was asked of the gateway that would have refused it. - await waitFor(() => { - expect(lane('Code').getAttribute('data-lane-state')).toBe('locked'); - }); - expect(lane('Sessions').getAttribute('data-lane-state')).toBe('locked'); - expect(lane('Knowledge').getAttribute('data-lane-state')).toBe('locked'); - expect( - within(lane('Code')).getAllByText(/Other project is not the active project/).length, - ).toBeGreaterThan(0); - expect(within(lane('Code')).getByText('Read-only scope')).toBeTruthy(); - // The run register carries the same refusal rather than a pending admission. - const register = document.querySelector('[data-run-register]'); - expect(register?.getAttribute('data-run-state')).toBe('locked'); - expect(within(register as HTMLElement).getByText(/no run created/)).toBeTruthy(); - expect( - fetchImpl.mock.calls.some(([input]) => String(input).includes('/api/explorer/queries')), - ).toBe(false); + await screen.findByRole('button', { name: /selected_graph/ }); + const calls = fetchImpl.mock.calls.filter(([input]) => String(input).includes('explorer/queries')); + expect(calls.map(([input, init]) => [String(input), init?.method])).toEqual([ + ['/api/projects/proj_other/explorer/queries', 'POST'], + ]); }); it('routes the run through the project gateway for an active selected project', async () => { useScope.getState().selectProject('proj_active', 'Active project', 'active'); const fetchImpl = serve({ ...SEARCH_ROUTES, - '/api/projects/proj_active/explorer/queries': { status: 200, body: plannerEnvelope() }, + '/api/projects/proj_active/explorer/queries': { status: 200, body: streamFixture() }, }); mount(fetchImpl); await search(); @@ -499,7 +505,7 @@ describe('ExplorerPage inspection', () => { ...SEARCH_ROUTES, '/api/explorer/queries': { status: 200, - body: plannerEnvelope([ + body: streamFixture([ source('code_graph', [rowWithoutDegree], 1), source('sessions', [], 0), source('knowledge', [], 0), @@ -531,7 +537,7 @@ describe('ExplorerPage inspection', () => { ...SEARCH_ROUTES, '/api/explorer/queries': { status: 200, - body: plannerEnvelope([ + body: streamFixture([ source('code_graph', [{ ...CODE_ROW, degree: 0 }], 1), source('sessions', [MESSAGE_ROW, SUMMARY_ROW], 2), source('knowledge', [FACT_ROW], null), diff --git a/dashboard/src/workspaces/explorer/ExplorerPage.tsx b/dashboard/src/workspaces/explorer/ExplorerPage.tsx index ad28abd07c7..2651abd9928 100644 --- a/dashboard/src/workspaces/explorer/ExplorerPage.tsx +++ b/dashboard/src/workspaces/explorer/ExplorerPage.tsx @@ -128,7 +128,7 @@ export function ExplorerPage() { /> {explorer.searching ? ( = return { source_id: id, source_label: SOURCE_LABELS[id], - phase: 'completed', - outcome: 'ready', + outcome: 'ready', completed_units: 0, total_units: 5, coverage: coverage(), @@ -50,22 +49,12 @@ function source(id: keyof typeof SOURCE_LABELS, over: Record = /** Parsed through the real schema, so a fixture that the contract would reject * cannot quietly prove anything here. */ function run(sources: unknown[], finality: 'complete' | 'partial' = 'complete') { - return ExplorerQueryRunV1Schema.parse({ - run_id: 'run-1', - request: { query: 'missing', limit: 50, offset: 0 }, - request_revision: 'explorer-query-request-v1', - plan_revision: 'explorer-query-plan-v1', - merge_revision: 'source-local-no-merge-v1', - required_source_ids: ['code_graph', 'sessions', 'knowledge'], - ordering_policy: 'source_local_no_cross_source_merge', - explanation: 'test', - submitted_at_micros: 1, - completed_at_micros: 2, + return { + query: 'missing', elapsed_micros: 1, - state: finality === 'complete' ? 'completed' : 'partial', - finality, - sources, - }); + state: finality === 'complete' ? 'completed' as const : 'partial' as const, + sources: sources.map((item) => ExplorerSourceProgressV1Schema.parse(item)), + }; } describe('absenceVerdict', () => { @@ -211,17 +200,17 @@ describe('absenceVerdict', () => { ); }); - it('refuses absence while the coordinator withholds canonical finality', () => { + it('refuses absence until the stream completes', () => { const verdict = absenceVerdict( run([source('code_graph'), source('sessions'), source('knowledge')], 'partial'), ); expect(verdict.confirmed).toBe(false); expect(verdict.confirmed === false && verdict.reason).toBe( - 'the coordinator has not declared canonical finality', + 'the stream has not completed with complete coverage', ); }); - it('refuses absence when no run has answered', () => { + it('refuses absence when no stream has answered', () => { expect(absenceVerdict(undefined).confirmed).toBe(false); }); }); diff --git a/dashboard/src/workspaces/explorer/absence.ts b/dashboard/src/workspaces/explorer/absence.ts index ca1dccbd7db..caf37edd8b6 100644 --- a/dashboard/src/workspaces/explorer/absence.ts +++ b/dashboard/src/workspaces/explorer/absence.ts @@ -1,5 +1,7 @@ import type { EvidenceQuality } from '../../ui/EvidencePattern.tsx'; -import type { ExplorerQueryRunV1, ExplorerSourceProgressV1 } from '../../contracts/generated.ts'; +import type { ExplorerSourceProgressV1 } from '../../contracts/generated.ts'; +import type { ExplorerStreamSnapshot } from './laneModel.ts'; +import { LANES } from './model.ts'; /** * Whether Explorer has earned the right to say a term is absent from the index. @@ -48,7 +50,6 @@ function coverageBlocker(source: ExplorerSourceProgressV1): string | null { return `${label} answered from a stale store`; case 'timed_out': return `${label} timed out before answering`; - case 'pending': case 'unavailable': case 'error': case 'cancelled': @@ -94,36 +95,35 @@ function coverageBlocker(source: ExplorerSourceProgressV1): string | null { } /** - * The verdict for a whole coordinator run. + * The verdict for one submitted stream. * - * Sources are checked before finality, because a source's own numbers are - * evidence the surface can see, whereas finality is the coordinator's summary of - * them, and when the two disagree the surface sides with the evidence. + * A terminal frame alone cannot confirm absence: each source must report + * complete coverage and an accounted denominator. */ -export function absenceVerdict(run: ExplorerQueryRunV1 | undefined): AbsenceVerdict { +export function absenceVerdict(run: ExplorerStreamSnapshot | undefined): AbsenceVerdict { if (run === undefined) { return { confirmed: false, quality: 'unknown', - reason: 'no coordinator run has answered for this query', + reason: 'no stream has answered for this query', }; } - if (run.sources.length === 0) { + if (run.sources.length !== LANES.length) { return { confirmed: false, quality: 'unknown', - reason: 'the coordinator named no required sources', + reason: 'not all required sources have answered', }; } for (const source of run.sources) { const blocker = coverageBlocker(source); if (blocker !== null) return { confirmed: false, quality: 'unknown', reason: blocker }; } - if (run.finality !== 'complete') { + if (run.state !== 'completed') { return { confirmed: false, quality: 'unknown', - reason: 'the coordinator has not declared canonical finality', + reason: 'the stream has not completed with complete coverage', }; } return { confirmed: true, quality: 'measured' }; diff --git a/dashboard/src/workspaces/explorer/controller.ts b/dashboard/src/workspaces/explorer/controller.ts index 5e53978856f..f8a0aa1bfcb 100644 --- a/dashboard/src/workspaces/explorer/controller.ts +++ b/dashboard/src/workspaces/explorer/controller.ts @@ -1,34 +1,30 @@ -/** - * Explorer's orchestration: every route it calls, every piece of query state it - * holds, and the typed lane read models it hands to the views. - * - * Kept apart from the JSX so the surface has exactly one place that knows a - * coordinator run is created, polled, and cancelled, and so the views below it - * render a lane condition rather than deciding one. - */ -import { useMutation, useQuery } from '@tanstack/react-query'; +/** Explorer source reads and abort ownership, apart from lane presentation. */ +import { useQuery } from '@tanstack/react-query'; import { useEffect, useMemo, useRef, useState } from 'react'; +import { z } from 'zod'; import { - ExplorerQueryRunV1Schema, + DashboardEnvelopeV1Schema, + ExplorerQueryEventV1Schema, ExplorerReadContextV1Schema, ExplorerSessionSizeV1Schema, GraphOverviewPayloadV1Schema, LcmOverviewPayloadV1Schema, MemoryOverviewPayloadV1Schema, type DashboardDomainStateV1, - type ExplorerQueryRunV1, + type ExplorerQueryEventV1, type ExplorerReadContextV1, type ExplorerSessionSizeV1, } from '../../contracts/generated.ts'; +import { dashboardFetch } from '../../data/auth/credential.ts'; import { fetchEnvelope, type EnvelopeResult } from '../../data/query/envelope.ts'; +import { decodeJsonBody, isRecord } from '../../data/query/responseBody.ts'; import { useEnvelope } from '../../data/query/useEnvelope.ts'; import { scopeKey, - scopeWritable, + explorerReadScope, scopedUrl, useScope, type DashboardScope, - type ScopeWritability, } from '../../data/scope/store.ts'; import { queryTerms } from '../../ui/search/terms.ts'; import { absenceVerdict, type AbsenceVerdict } from './absence.ts'; @@ -38,9 +34,9 @@ import { laneFromScope, laneHits, lanePending, - runIsTerminal, searchLane, type ExplorerLaneReadModel, + type ExplorerStreamSnapshot, } from './laneModel.ts'; import { LANES, type Hit, type LaneId } from './model.ts'; @@ -48,45 +44,106 @@ import { LANES, type Hit, type LaneId } from './model.ts'; const QUERIES_ROUTE = '/api/explorer/queries'; -/** - * Every Explorer route is rewritten for the current scope. A selected project - * routes through the project gateway so the run is created against THAT - * project's state; the all-projects default and the active project stay - * unprefixed. Without this a query under a selected scope would silently be - * answered by the active project, and the lanes would attribute one - * project's rows to another's name in the scope register. - */ -function runRoute(scope: DashboardScope, runId?: string): string { - const path = runId === undefined ? QUERIES_ROUTE : `${QUERIES_ROUTE}/${encodeURIComponent(runId)}`; - return scopedUrl(scope, path); +class ExplorerHttpError extends Error { + constructor( + readonly state: DashboardDomainStateV1, + status: number, + detail?: string, + ) { + super(detail ?? `HTTP ${status}`); + } } -function createPlannerQuery( +/** The daemon's own sentence from a non-envelope problem body, so a refusal + * keeps its exact reason instead of collapsing to the HTTP status. */ +function problemDetail(body: unknown): string | undefined { + if (!isRecord(body)) return undefined; + const detail = body.detail; + return typeof detail === 'string' && detail !== '' ? detail : undefined; +} + +export async function readExplorerStream( scope: DashboardScope, query: string, -): Promise> { - return fetchEnvelope(runRoute(scope), ExplorerQueryRunV1Schema, { + signal: AbortSignal, + onEvent: (event: ExplorerQueryEventV1) => void, +): Promise { + const response = await dashboardFetch(scopedUrl(scope, QUERIES_ROUTE), { method: 'POST', headers: { - accept: 'application/json', + accept: 'text/event-stream', 'content-type': 'application/json', }, body: JSON.stringify({ query, limit: 50, offset: 0 }), + signal, }); -} - -function readPlannerQuery( - scope: DashboardScope, - runId: string, -): Promise> { - return fetchEnvelope(runRoute(scope, runId), ExplorerQueryRunV1Schema); -} - -function cancelPlannerQuery( - scope: DashboardScope, - runId: string, -): Promise> { - return fetchEnvelope(runRoute(scope, runId), ExplorerQueryRunV1Schema, { method: 'DELETE' }); + const contentType = response.headers.get('content-type') ?? ''; + let body: unknown; + if (contentType.includes('application/json')) { + body = await decodeJsonBody(response, signal); + const parsed = DashboardEnvelopeV1Schema(z.unknown()).safeParse(body); + if (parsed.success && parsed.data.domain_state !== 'ready') { + throw new ExplorerHttpError( + parsed.data.domain_state, + response.status, + parsed.data.coverage.omission_reasons[0], + ); + } + } + if (!response.ok) { + throw new ExplorerHttpError( + response.status === 401 ? 'unauthorized' : response.status === 403 ? 'denied' : 'error', + response.status, + problemDetail(body), + ); + } + if (!contentType.startsWith('text/event-stream')) { + throw new ExplorerHttpError('unsupported_schema', response.status, 'Explorer response is not an event stream'); + } + if (!response.body) throw new Error('Explorer response has no stream'); + const reader = response.body.getReader(); + const decoder = new TextDecoder(); + let buffer = ''; + let final = false; + let failure: unknown; + try { + while (!final) { + const { done, value } = await reader.read(); + if (done) break; + buffer = (buffer + decoder.decode(value, { stream: true })).replaceAll('\r\n', '\n'); + let boundary = buffer.indexOf('\n\n'); + while (boundary !== -1) { + const frame = buffer.slice(0, boundary); + buffer = buffer.slice(boundary + 2); + const data = frame.split('\n') + .filter((line) => line.startsWith('data:')) + .map((line) => line.slice(5).trimStart()) + .join('\n'); + if (data !== '') { + const event = ExplorerQueryEventV1Schema.parse(JSON.parse(data)); + onEvent(event); + if (event.kind === 'final') { + final = true; + break; + } + } + boundary = buffer.indexOf('\n\n'); + } + } + if (!final && !signal.aborted) throw new Error('Explorer stream ended without a final frame'); + } catch (error) { + failure = error; + } + try { + await reader.cancel(); + } catch (error) { + if (error !== failure) { + console.warn('Explorer stream cleanup failed', error); + } + } finally { + reader.releaseLock(); + } + if (failure !== undefined) throw failure; } function readSessionSize( @@ -112,44 +169,6 @@ function readSessionContext( ); } -/* ------------------------------------------------------- run-status polling */ - -/** - * Transport states a repeat read can clear on its own: the daemon was - * unreachable, answered a bare non-2xx, or said it had nothing ready yet. - * - * Every other transport state is a standing condition, a refusal - * (`unauthorized`, `denied`), a scope that will not serve the read (`locked`), - * a body this client cannot read (`unsupported_schema`), and re-asking gets - * the same answer, so the poll stops and the state is rendered. - */ -const RETRYABLE_TRANSPORT_STATES: ReadonlySet = new Set< - DashboardDomainStateV1 ->(['offline', 'error', 'loading']); - -/** - * How long a retried status read waits, by how many consecutive transport - * failures precede it: 1 s, 2 s, 5 s, 10 s, and then the ceiling below for as - * long as the failure lasts. - * - * A ladder rather than an attempt budget. An admitted run does not stop - * existing because the daemon blinked, and this poll is the only thing that - * can ever resolve it, so a budget strands every run that outlives it, the - * daemon comes back, the run completes, and the surface never finds out. - * Backing off instead keeps the run reachable while making a dead daemon cost - * two reads a minute, and the failing reads stay on screen the whole time - * because `fetchEnvelope` reports them as data the lanes render. - */ -const TRANSPORT_BACKOFF_MS: readonly number[] = [1000, 2000, 5000, 10_000]; - -/** The slowest the poll ever ticks, held until the run terminates or the - * surface goes away. */ -const TRANSPORT_BACKOFF_CEILING_MS = 30_000; - -function transportBackoffMs(consecutiveFailures: number): number { - return TRANSPORT_BACKOFF_MS[consecutiveFailures - 1] ?? TRANSPORT_BACKOFF_CEILING_MS; -} - /* -------------------------------------------------------------- controller */ interface ExplorerFacet { @@ -157,18 +176,6 @@ interface ExplorerFacet { readonly value: string; } -/** The request owns its admission scope, regardless of later UI selections. */ -interface PlannerRequest { - readonly scope: DashboardScope; - readonly query: string; - readonly generation: number; -} - -interface AcceptedPlannerRun { - readonly scope: DashboardScope; - readonly id: string; -} - /** How far the coordinator has got, counted in sources rather than in a * percentage: sources have incommensurable units, so "2 of 3 concluded" is the * only progress figure with a real denominator. */ @@ -182,9 +189,9 @@ export interface ExplorerController { readonly submitted: string; readonly searching: boolean; readonly terms: readonly string[]; - /** Whether the current scope accepts a query run, from the scope authority. - * Anything but `writable` means no run was, or will be, dispatched. */ - readonly writability: ScopeWritability; + /** Whether the current scope accepts an Explorer read, from the scope authority. + * Anything but `writable` means no request is dispatched. */ + readonly writability: ReturnType; /** One read model per lane, in `LANES` order. */ readonly lanes: readonly ExplorerLaneReadModel[]; /** The lanes the current lane filter admits. */ @@ -196,9 +203,8 @@ export interface ExplorerController { readonly unansweredLanes: readonly ExplorerLaneReadModel[]; readonly answeredLaneCount: number; readonly absence: AbsenceVerdict; - readonly runResult: EnvelopeResult | undefined; - /** The coordinator run for the submitted query, when one has answered. */ - readonly run: ExplorerQueryRunV1 | undefined; + readonly transport: { state: DashboardDomainStateV1; detail?: string } | undefined; + readonly run: ExplorerStreamSnapshot | undefined; readonly runProgress: RunProgress | null; readonly cancelling: boolean; /** Present only while a cancellable run is in flight. */ @@ -222,115 +228,32 @@ export interface ExplorerController { export function useExplorerController(): ExplorerController { const scope = useScope((s) => s.scope); - const writability = useMemo(() => scopeWritable(scope), [scope]); + const writability = useMemo(() => explorerReadScope(scope), [scope]); const [query, setQuery] = useState(''); const [submitted, setSubmitted] = useState(''); - const [activeRunId, setActiveRunId] = useState(null); + const [run, setRun] = useState(); + const [transport, setTransport] = useState<{ state: DashboardDomainStateV1; detail?: string }>(); + const [cancelling, setCancelling] = useState(false); const [laneFilter, setLaneFilter] = useState(null); const [facet, setFacet] = useState(null); const [selected, setSelected] = useState(null); const [peeked, setPeeked] = useState(null); const searching = submitted !== ''; const terms = useMemo(() => queryTerms(submitted), [submitted]); - // A superseded POST can still be admitted after a newer search or after - // unmount. Its accepted run must be explicitly cancelled, not orphaned. const requestGeneration = useRef(0); - const acceptedRun = useRef(null); - const retireAcceptedRun = () => { - const previous = acceptedRun.current; - acceptedRun.current = null; - if (previous !== null) void cancelPlannerQuery(previous.scope, previous.id); + const activeRequest = useRef(null); + const retireRequest = () => { + activeRequest.current?.abort(); + activeRequest.current = null; }; useEffect(() => { return () => { requestGeneration.current += 1; - const previous = acceptedRun.current; - acceptedRun.current = null; - if (previous !== null) void cancelPlannerQuery(previous.scope, previous.id); + activeRequest.current?.abort(); + activeRequest.current = null; }; }, []); - const planner = useMutation({ - mutationFn: async (request: PlannerRequest) => { - const result = await createPlannerQuery(request.scope, request.query); - if (result.outcome === 'envelope') { - const run = result.envelope.payload; - const live = !runIsTerminal(run.state); - // Record ownership as soon as the daemon admits the request. The - // observer can unmount before React Query runs its success callbacks. - if (request.generation === requestGeneration.current) { - acceptedRun.current = live ? { id: run.run_id, scope: request.scope } : null; - setActiveRunId(run.run_id); - } else if (live) { - void cancelPlannerQuery(request.scope, run.run_id); - } - } - return result; - }, - }); - const activeRunIdForQuery = activeRunId ?? ''; - // `fetchEnvelope` reports a transport failure as data rather than throwing, - // so react-query's own failure count never moves and cannot pace the retry - // below. This is that count, how far down the backoff ladder the poll has - // walked, reset by the first read that lands an envelope. - const transportFailures = useRef(0); - const runStatus = useQuery({ - queryKey: ['explorer', 'query-run', scopeKey(scope), activeRunIdForQuery], - queryFn: async () => { - const result = await readPlannerQuery(scope, activeRunIdForQuery); - transportFailures.current = result.outcome === 'transport' ? transportFailures.current + 1 : 0; - return result; - }, - enabled: activeRunIdForQuery !== '', - refetchInterval: (queryState) => { - const result = queryState.state.data; - // No data yet: the first read has not landed, keep the fast tick. - if (result === undefined) return 250; - if (result.outcome === 'transport') { - // This poll is the only thing that resolves an admitted run, run - // completion publishes no targeted invalidation, so a transport - // failure a repeat read could clear must not end it, at any count: a - // run whose daemon blinks more times than some budget allows is still - // a live run, and abandoning it is the stuck surface this poll exists - // to prevent. What is bounded is the rate, not the attempts. A - // standing refusal still stops immediately, because re-asking it only - // ever gets the same answer. - if (!RETRYABLE_TRANSPORT_STATES.has(result.state)) return false; - return transportBackoffMs(transportFailures.current); - } - if (runIsTerminal(result.envelope.payload.state)) return false; - // A long-pending run escalates off the fast tick rather than holding - // 250 ms for its whole life: 250 ms → 1 s → 2 s. - const reads = queryState.state.dataUpdateCount; - if (reads <= 4) return 250; - return reads <= 8 ? 1000 : 2000; - }, - }); - const cancelRun = useMutation({ - mutationFn: (runId: string) => cancelPlannerQuery(scope, runId), - onSuccess: () => { - void runStatus.refetch(); - }, - }); - const runResult = runStatus.data ?? planner.data; - const run = - runResult?.outcome === 'envelope' && runResult.envelope.payload.request.query === submitted - ? runResult.envelope.payload - : undefined; - const currentRunId = run?.run_id; - const currentRunState = run?.state; - useEffect(() => { - // A completed read no longer needs an explicit cancel on unmount/reset. - if ( - currentRunId !== undefined && - currentRunState !== undefined && - runIsTerminal(currentRunState) && - acceptedRun.current?.id === currentRunId - ) { - acceptedRun.current = null; - } - }, [currentRunId, currentRunState]); - const graphBrowse = useEnvelope( ['explorer', 'graph-overview'], '/api/plugins/graph/overview', @@ -360,14 +283,9 @@ export function useExplorerController(): ExplorerController { () => LANES.map((spec): ExplorerLaneReadModel => { if (searching) { - // A run is created with a POST, and the project gateway refuses - // writes for every project but the active one. The gate is read - // here, before any request, so a refused scope is rendered from the - // scope authority's own reason and nothing is asked of a daemon that - // would have to say no. const refused = laneFromScope(spec.id, writability); if (refused !== null) return refused; - return searchLane(spec.id, runResult, submitted, terms); + return searchLane(spec.id, run, transport, submitted, terms); } switch (spec.id) { case 'code': @@ -407,7 +325,8 @@ export function useExplorerController(): ExplorerController { lcmBrowsePending, memoryData, memoryPending, - runResult, + run, + transport, searching, submitted, terms, @@ -431,23 +350,46 @@ export function useExplorerController(): ExplorerController { const dispatch = (nextQuery: string) => { requestGeneration.current += 1; - retireAcceptedRun(); - setActiveRunId(null); - // A fresh run starts at the top of the backoff ladder: the previous - // run's failures are not this one's, and must not slow its first reads. - transportFailures.current = 0; - planner.reset(); - // Nothing is dispatched under a scope that will refuse it; the lanes - // render the refusal instead. - if (writability.state === 'writable') { - planner.mutate({ query: nextQuery, scope, generation: requestGeneration.current }); - } + retireRequest(); + setRun(undefined); + setTransport(undefined); + setCancelling(false); + if (writability.state !== 'writable') return; + const generation = requestGeneration.current; + const controller = new AbortController(); + activeRequest.current = controller; + setRun({ query: nextQuery, state: 'pending', elapsed_micros: null, sources: [] }); + void readExplorerStream(scope, nextQuery, controller.signal, (event) => { + if (controller.signal.aborted || generation !== requestGeneration.current) return; + setRun((current) => { + if ( + controller.signal.aborted || + generation !== requestGeneration.current || + current?.query !== nextQuery + ) return current; + if (event.kind === 'final') { + return { ...current, state: event.state, elapsed_micros: event.elapsed_micros }; + } + return { + ...current, + sources: [ + ...current.sources.filter((source) => source.source_id !== event.source.source_id), + event.source, + ], + }; + }); + }).catch((error: unknown) => { + if (controller.signal.aborted || generation !== requestGeneration.current) return; + setTransport({ + state: error instanceof ExplorerHttpError ? error.state + : error instanceof TypeError ? 'offline' : 'error', + detail: error instanceof Error ? error.message : 'Explorer stream failed', + }); + }).finally(() => { + if (activeRequest.current === controller) activeRequest.current = null; + }); }; - // The rows on screen must belong to the scope in the register. When the - // scope changes under a submitted query, a project selected, a deep link - // resolving from `unresolved` to `active`, the run is re-created against - // the new scope rather than left showing the old project's answer. const requestScope = `${scopeKey(scope)}:${writability.state}`; const lastRequestScope = useRef(requestScope); useEffect(() => { @@ -457,30 +399,28 @@ export function useExplorerController(): ExplorerController { setSelected(null); setPeeked(null); dispatch(submitted); - // `dispatch` closes over the current planner and writability; the scope - // key is the only trigger this effect is meant to have. // eslint-disable-next-line react-hooks/exhaustive-deps }, [requestScope]); const reset = () => { requestGeneration.current += 1; - retireAcceptedRun(); + retireRequest(); setQuery(''); setSubmitted(''); - setActiveRunId(null); - transportFailures.current = 0; - planner.reset(); + setRun(undefined); + setTransport(undefined); + setCancelling(false); setFacet(null); setSelected(null); setPeeked(null); }; const runProgress: RunProgress | null = - run === undefined || run.sources.length === 0 + run === undefined ? null : { - concluded: run.sources.filter((source) => source.outcome !== 'pending').length, - total: run.sources.length, + concluded: run.sources.length, + total: LANES.length, }; return { @@ -495,18 +435,19 @@ export function useExplorerController(): ExplorerController { anyPending: lanes.some((lane) => lanePending(lane)), unansweredLanes: lanes.filter((lane) => !laneAnswered(lane) && !lanePending(lane)), answeredLaneCount: lanes.filter((lane) => laneAnswered(lane)).length, - // A confirmed global absence is a claim about the whole index, so it is - // re-derived from the coordinator's own unit accounting rather than - // reprinted from the `finality` scalar. See `absence.ts`. absence: absenceVerdict(run), - runResult, + transport, run, runProgress, - cancelling: cancelRun.isPending, - cancel: - activeRunId !== null && run?.state === 'pending' - ? () => cancelRun.mutate(activeRunId) - : undefined, + cancelling, + cancel: activeRequest.current !== null && run?.state === 'pending' + ? () => { + requestGeneration.current += 1; + retireRequest(); + setCancelling(true); + setRun((current) => current ? { ...current, state: 'cancelled' } : current); + } + : undefined, laneFilter, facet, selected, diff --git a/dashboard/src/workspaces/explorer/controllerPolling.dom.test.tsx b/dashboard/src/workspaces/explorer/controllerPolling.dom.test.tsx deleted file mode 100644 index f8e6bc2f294..00000000000 --- a/dashboard/src/workspaces/explorer/controllerPolling.dom.test.tsx +++ /dev/null @@ -1,403 +0,0 @@ -/** - * The run-status poll is the only thing that resolves an admitted Explorer run: - * the coordinator publishes no targeted SSE invalidation for query completion, - * so whatever ends this poll ends the run's visible life in the UI. - * - * These cases pin the outcomes that must stay distinct, a transient transport - * failure keeps polling however many times it repeats, a standing refusal stops - * it at once, a failure that never clears backs off to a slow tick instead of - * either hammering or abandoning the run, and the poll ends with the surface , - * by driving the real controller against a scripted daemon on a fake clock. - */ -import { MutationCache, QueryClient, QueryClientProvider } from '@tanstack/react-query'; -import { act, renderHook } from '@testing-library/react'; -import { createElement, type ReactNode } from 'react'; -import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'; - -import { useExplorerController } from './controller.ts'; - -const RUN_ID = 'explorer-run-poll'; -const QUERY = 'graph'; - -/** The status route for the admitted run, as the controller spells it. */ -const STATUS_PATH = `/api/explorer/queries/${RUN_ID}`; - -type RunState = 'pending' | 'completed'; - -function runEnvelope(state: RunState, runId = RUN_ID, query = QUERY) { - return { - schema_revision: 1, - scope: { - project_id: 'project.explorer', - storage_mode: 'profile_sharded', - store_root: '/data/project', - }, - version: { entity_version: null, graph_version: null }, - time: { valid_time_micros: null, observation_time_micros: 10 }, - source_watermark: null, - authorization: { outcome: 'authorized' }, - coverage: { - completeness: state === 'completed' ? 'complete' : 'partial', - eligible: 0, - examined: 0, - matched: null, - excluded: null, - omitted: null, - unknown: null, - denominator: 0, - unit: 'sources', - omission_reasons: [], - }, - freshness: { state: 'unknown', observed_at_micros: null, watermark: null }, - domain_state: state === 'completed' ? 'ready' : 'partial', - legal_actions: [], - payload: { - run_id: runId, - request: { query, limit: 50, offset: 0 }, - request_revision: 'explorer-query-request-v1', - plan_revision: 'explorer-query-plan-v1', - merge_revision: 'source-local-no-merge-v1', - required_source_ids: [], - ordering_policy: 'source_local_no_cross_source_merge', - explanation: 'poll fixture', - submitted_at_micros: 1, - completed_at_micros: state === 'completed' ? 10 : null, - elapsed_micros: 9, - state, - finality: state === 'completed' ? 'complete' : 'pending', - sources: [], - }, - }; -} - -function jsonResponse(status: number, body: unknown): Response { - return { - ok: status >= 200 && status < 300, - status, - json: async () => body, - } as Response; -} - -/** One scripted status read: what the daemon does on the Nth poll. */ -type StatusStep = - | { kind: 'run'; state: RunState } - /** The browser could not reach the daemon at all, `fetch` rejects. */ - | { kind: 'unreachable' } - | { kind: 'status'; code: number }; - -/** - * A daemon that admits the run, then answers each status read from `script`, - * repeating the final step once the script runs out. Every status read is - * counted so a case can prove the poll stopped rather than merely that the - * last value looked wrong. - */ -function scriptedDaemon(script: readonly StatusStep[]) { - const statusReads: StatusStep[] = []; - const fetchMock = vi.fn(async (input: RequestInfo | URL, init?: RequestInit): Promise => { - const url = String(input); - if (url.includes(STATUS_PATH) && init?.method === 'DELETE') { - return jsonResponse(200, runEnvelope('completed')); - } - if (url.includes(STATUS_PATH)) { - const step = script[Math.min(statusReads.length, script.length - 1)]; - if (step === undefined) throw new Error('scripted daemon has no status step'); - statusReads.push(step); - if (step.kind === 'unreachable') throw new TypeError('Failed to fetch'); - if (step.kind === 'status') return jsonResponse(step.code, { error: 'refused' }); - return jsonResponse(200, runEnvelope(step.state)); - } - if (url.includes('/api/explorer/queries')) { - return jsonResponse(200, runEnvelope('pending')); - } - return jsonResponse(404, { error: 'not found' }); - }); - return { fetchMock, statusReads }; -} - -function wrapper({ children }: { children: ReactNode }) { - const client = new QueryClient({ - defaultOptions: { queries: { retry: false, gcTime: 0 } }, - }); - return createElement(QueryClientProvider, { client }, children); -} - -beforeEach(() => { - vi.useFakeTimers(); -}); - -afterEach(() => { - vi.useRealTimers(); - vi.unstubAllGlobals(); -}); - -/** Submits `QUERY` and lets the create + first status read settle. */ -async function submitQuery() { - const view = renderHook(() => useExplorerController(), { wrapper }); - await act(async () => { - view.result.current.setQuery(QUERY); - }); - await act(async () => { - view.result.current.submit(); - await vi.advanceTimersByTimeAsync(0); - }); - return view; -} - -/** Runs the poll clock long enough for every scripted step to be reached. */ -async function runPollClock(ms: number) { - await act(async () => { - await vi.advanceTimersByTimeAsync(ms); - }); -} - -describe('explorer run-status polling', () => { - it('keeps polling after one transient transport failure and resolves the run', async () => { - // Read 1 finds the run pending, read 2 cannot reach the daemon at all, and - // read 3 would find the completed run. Only read 2 is a failure, and it is - // the kind a repeat read clears by itself. - const { fetchMock, statusReads } = scriptedDaemon([ - { kind: 'run', state: 'pending' }, - { kind: 'unreachable' }, - { kind: 'run', state: 'completed' }, - ]); - vi.stubGlobal('fetch', fetchMock); - - const view = await submitQuery(); - await runPollClock(30_000); - - expect(statusReads.length).toBeGreaterThanOrEqual(3); - expect(view.result.current.runResult?.outcome).toBe('envelope'); - expect(view.result.current.run?.state).toBe('completed'); - }); - - it('stops polling on a standing refusal and leaves it on screen', async () => { - // A 403 is not something a repeat read clears: the answer is the same until - // the operator changes something, so the poll must stop and show it. - const { fetchMock, statusReads } = scriptedDaemon([ - { kind: 'run', state: 'pending' }, - { kind: 'status', code: 403 }, - ]); - vi.stubGlobal('fetch', fetchMock); - - const view = await submitQuery(); - await runPollClock(30_000); - const afterRefusal = statusReads.length; - await runPollClock(60_000); - - expect(statusReads.length).toBe(afterRefusal); - expect(afterRefusal).toBe(2); - const result = view.result.current.runResult; - expect(result?.outcome).toBe('transport'); - expect(result?.outcome === 'transport' ? result.state : null).toBe('denied'); - }); - - it('resolves the run after more than four consecutive transient failures', async () => { - // The failure budget is the bug: a run whose daemon blinks six times and - // then answers is still a live run, and the only thing that can surface it - // is this poll. Six unreachable reads is deliberately past any small cap. - const { fetchMock, statusReads } = scriptedDaemon([ - { kind: 'run', state: 'pending' }, - { kind: 'unreachable' }, - { kind: 'unreachable' }, - { kind: 'unreachable' }, - { kind: 'unreachable' }, - { kind: 'unreachable' }, - { kind: 'unreachable' }, - { kind: 'run', state: 'completed' }, - ]); - vi.stubGlobal('fetch', fetchMock); - - const view = await submitQuery(); - await runPollClock(300_000); - - expect(statusReads.filter((step) => step.kind === 'unreachable').length).toBe(6); - expect(view.result.current.runResult?.outcome).toBe('envelope'); - expect(view.result.current.run?.state).toBe('completed'); - }); - - it('backs off to a slow tick on a transport failure that never clears, and shows it', async () => { - // What is bounded is the rate, not the attempts. A daemon that never comes - // back must cost a couple of reads a minute rather than four a second, and - // the reader must be looking at the failure the whole time, an offline - // lane, not a spinner that hides it. - const { fetchMock, statusReads } = scriptedDaemon([ - { kind: 'run', state: 'pending' }, - { kind: 'unreachable' }, - ]); - vi.stubGlobal('fetch', fetchMock); - - const view = await submitQuery(); - await runPollClock(300_000); - const afterFirstWindow = statusReads.length; - await runPollClock(300_000); - const secondWindow = statusReads.length - afterFirstWindow; - - // Still asking, so a daemon that returns is still found. - expect(secondWindow).toBeGreaterThan(0); - // And asking at the 30 s ceiling: five minutes buys about ten reads, never - // the hundreds a fast tick would. - expect(secondWindow).toBeLessThanOrEqual(11); - const result = view.result.current.runResult; - expect(result?.outcome).toBe('transport'); - expect(result?.outcome === 'transport' ? result.state : null).toBe('offline'); - // The failure is on screen, and no lane is pretending to still be working. - const byLane = new Map(view.result.current.lanes.map((lane) => [lane.lane, lane.state])); - expect(byLane.get('code')).toBe('offline'); - expect(byLane.get('sessions')).toBe('offline'); - expect(byLane.get('knowledge')).toBe('offline'); - expect(view.result.current.anyPending).toBe(false); - }); - - it('stops polling when the surface unmounts', async () => { - // Slow polling is only affordable because it ends with the surface: an - // unmounted Explorer must not leave a timer asking about a dead run. - const { fetchMock, statusReads } = scriptedDaemon([ - { kind: 'run', state: 'pending' }, - { kind: 'unreachable' }, - ]); - vi.stubGlobal('fetch', fetchMock); - - const view = await submitQuery(); - await runPollClock(60_000); - const afterUnmount = statusReads.length; - view.unmount(); - await runPollClock(300_000); - - expect(statusReads.length).toBe(afterUnmount); - }); - - it('cancels an accepted run when unmounted before mutation callbacks finish', async () => { - let releaseCallbacks!: () => void; - const pending = new Promise((resolve) => { releaseCallbacks = resolve; }); - const afterAdmission = vi.fn(() => pending); - const client = new QueryClient({ mutationCache: new MutationCache({ onSuccess: afterAdmission }) }); - const { fetchMock } = scriptedDaemon([{ kind: 'run', state: 'pending' }]); - vi.stubGlobal('fetch', fetchMock); - const view = renderHook(() => useExplorerController(), { - wrapper: ({ children }) => createElement(QueryClientProvider, { client }, children), - }); - try { - await act(async () => { - view.result.current.submit(QUERY); - await vi.advanceTimersByTimeAsync(0); - }); - expect(afterAdmission).toHaveBeenCalledOnce(); - view.unmount(); - expect(fetchMock.mock.calls.filter(([url, init]) => - String(url).endsWith(STATUS_PATH) && init?.method === 'DELETE', - )).toHaveLength(1); - } finally { - releaseCallbacks(); - client.clear(); - } - }); - - it('stops polling when the search is reset', async () => { - // Reset drops the active run, so the poll it was the only reader of ends - // with it rather than surviving into the next search. - const { fetchMock, statusReads } = scriptedDaemon([ - { kind: 'run', state: 'pending' }, - { kind: 'unreachable' }, - ]); - vi.stubGlobal('fetch', fetchMock); - - const view = await submitQuery(); - await runPollClock(60_000); - await act(async () => { - view.result.current.reset(); - await vi.advanceTimersByTimeAsync(0); - }); - const afterReset = statusReads.length; - await runPollClock(300_000); - - expect(statusReads.length).toBe(afterReset); - }); -}); - -/** A held admission POST can complete after a newer query or an unmount. - * The result must cancel its exact server run rather than reclaim the UI. */ -describe('explorer query admission ownership', () => { - it.each(['pending', 'completed'] as const)('keeps the newer query after a late %s admission', async (state) => { - let finishOlder!: (response: Response) => void; - const heldOlder = new Promise((resolve) => { - finishOlder = resolve; - }); - const cancellations: string[] = []; - const fetchMock = vi.fn((input: RequestInfo | URL, init?: RequestInit): Promise => { - const url = String(input); - if (init?.method === 'POST' && url.endsWith('/api/explorer/queries')) { - const { query } = JSON.parse(String(init.body)) as { query: string }; - if (query === 'older') return heldOlder; - return Promise.resolve(jsonResponse(202, runEnvelope('pending', 'run-newer', 'newer'))); - } - if (init?.method === 'DELETE') { - cancellations.push(url); - return Promise.resolve(jsonResponse(200, runEnvelope('completed', 'run-newer', 'newer'))); - } - if (url.endsWith('/api/explorer/queries/run-newer')) { - return Promise.resolve(jsonResponse(200, runEnvelope('pending', 'run-newer', 'newer'))); - } - return Promise.resolve(jsonResponse(404, { error: 'unknown run' })); - }); - vi.stubGlobal('fetch', fetchMock); - const view = renderHook(() => useExplorerController(), { wrapper }); - - await act(async () => { - view.result.current.submit('older'); - await vi.advanceTimersByTimeAsync(0); - }); - await act(async () => { - view.result.current.submit('newer'); - await vi.advanceTimersByTimeAsync(0); - }); - expect(view.result.current.run?.run_id).toBe('run-newer'); - - await act(async () => { - finishOlder(jsonResponse(202, runEnvelope(state, 'run-older', 'older'))); - await vi.advanceTimersByTimeAsync(0); - }); - expect(cancellations).toEqual(state === 'pending' ? ['/api/explorer/queries/run-older'] : []); - expect(view.result.current.run?.run_id).toBe('run-newer'); - view.unmount(); - }); - - it('cancels the old run on supersession and the live run on unmount', async () => { - const cancellations: string[] = []; - const fetchMock = vi.fn((input: RequestInfo | URL, init?: RequestInit): Promise => { - const url = String(input); - if (init?.method === 'POST' && url.endsWith('/api/explorer/queries')) { - const { query } = JSON.parse(String(init.body)) as { query: string }; - return Promise.resolve(jsonResponse(202, runEnvelope('pending', `run-${query}`, query))); - } - if (init?.method === 'DELETE') { - cancellations.push(url); - return Promise.resolve(jsonResponse(200, runEnvelope('completed'))); - } - if (url.includes('/api/explorer/queries/run-')) { - const query = url.substring(url.lastIndexOf('run-') + 4); - return Promise.resolve(jsonResponse(200, runEnvelope('pending', `run-${query}`, query))); - } - return Promise.resolve(jsonResponse(404, { error: 'unknown run' })); - }); - vi.stubGlobal('fetch', fetchMock); - const view = renderHook(() => useExplorerController(), { wrapper }); - - await act(async () => { - view.result.current.submit('first'); - await vi.advanceTimersByTimeAsync(0); - }); - expect(view.result.current.run?.run_id).toBe('run-first'); - await act(async () => { - view.result.current.submit('second'); - await vi.advanceTimersByTimeAsync(0); - }); - expect(cancellations).toEqual(['/api/explorer/queries/run-first']); - expect(view.result.current.run?.run_id).toBe('run-second'); - - view.unmount(); - expect(cancellations).toEqual([ - '/api/explorer/queries/run-first', - '/api/explorer/queries/run-second', - ]); - }); -}); diff --git a/dashboard/src/workspaces/explorer/controllerStream.dom.test.tsx b/dashboard/src/workspaces/explorer/controllerStream.dom.test.tsx new file mode 100644 index 00000000000..b6f0501498e --- /dev/null +++ b/dashboard/src/workspaces/explorer/controllerStream.dom.test.tsx @@ -0,0 +1,312 @@ +import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; +import { act, renderHook } from '@testing-library/react'; +import { createElement, type ReactNode } from 'react'; +import { afterEach, beforeEach, expect, it, vi } from 'vitest'; +import { useScope } from '../../data/scope/store.ts'; +import { useExplorerController } from './controller.ts'; + +function jsonResponse(status: number, body: unknown): Response { + return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } }); +} + +function wrapper({ children }: { children: ReactNode }) { + const client = new QueryClient({ + defaultOptions: { queries: { retry: false, gcTime: 0 } }, + }); + return createElement(QueryClientProvider, { client }, children); +} + +beforeEach(() => { + vi.useFakeTimers(); +}); + +afterEach(() => { + useScope.getState().selectAllProjects(); + vi.useRealTimers(); + vi.unstubAllGlobals(); + vi.restoreAllMocks(); +}); + +it('aborts exact requests on reset, scope change, and unmount', async () => { + const diagnostic = vi.spyOn(console, 'warn').mockImplementation(() => {}); + const requests: Array<{ url: string; signal: AbortSignal }> = []; + vi.stubGlobal('fetch', vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => { + if (init?.method !== 'POST' || !String(input).endsWith('/explorer/queries')) { + return jsonResponse(404, { error: 'not found' }); + } + const signal = init.signal; + if (!signal) throw new Error('Explorer read needs an abort signal'); + requests.push({ url: String(input), signal }); + return new Response(new ReadableStream({ + start(controller) { + signal.addEventListener('abort', () => controller.error(new DOMException('aborted', 'AbortError')), { once: true }); + }, + }), { status: 200, headers: { 'content-type': 'text/event-stream' } }); + })); + const view = renderHook(() => useExplorerController(), { wrapper }); + await act(async () => { + view.result.current.submit('first'); + await vi.advanceTimersByTimeAsync(0); + }); + expect(requests).toHaveLength(1); + await act(async () => { view.result.current.reset(); }); + expect(requests[0]?.signal.aborted).toBe(true); + await act(async () => { + view.result.current.submit('second'); + await vi.advanceTimersByTimeAsync(0); + }); + expect(requests).toHaveLength(2); + await act(async () => { + useScope.getState().selectProject('proj_other', 'Other project', 'selected'); + await vi.advanceTimersByTimeAsync(0); + }); + expect(requests[1]?.signal.aborted).toBe(true); + expect(requests[2]?.url).toBe('/api/projects/proj_other/explorer/queries'); + view.unmount(); + expect(requests[2]?.signal.aborted).toBe(true); + await act(async () => { await vi.advanceTimersByTimeAsync(0); }); + expect(diagnostic).not.toHaveBeenCalled(); +}); + +it('superseded_explorer_stream_cannot_replace_new_results', async () => { + const requests: string[] = []; + let releaseOld!: () => void; + const oldFrame = new Promise((resolve) => { releaseOld = resolve; }); + let oldSignal: AbortSignal | undefined; + const source = (query: string) => ({ + kind: 'source', + source: { + source_id: 'code_graph', source_label: 'Code graph', outcome: 'ready', completed_units: 1, total_units: 1, + coverage: { completeness: 'complete', eligible: 1, examined: 1, matched: 1, + excluded: 0, omitted: 0, unknown: 0, denominator: 1, unit: 'symbols', + omission_reasons: [] }, + freshness: 'fresh', watermark: query, error_code: null, message: null, + page: { offset: 0, limit: 50, total: 1, next_offset: null, + rows: [{ name: query }], metadata: {} }, + }, + }); + vi.stubGlobal('fetch', vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => { + const url = String(input); + if (!url.endsWith('/api/explorer/queries')) { + requests.push(url); + return jsonResponse(404, { error: 'retired polling route' }); + } + const { query } = JSON.parse(String(init?.body)) as { query: string }; + requests.push(`${init?.method} ${query}`); + if (query === 'older') oldSignal = init?.signal ?? undefined; + const encoder = new TextEncoder(); + const body = new ReadableStream({ + async start(controller) { + if (query === 'older') await oldFrame; + controller.enqueue(encoder.encode(`data: ${JSON.stringify(source(query))}\n\n`)); + controller.enqueue(encoder.encode('data: {"kind":"final","state":"completed","elapsed_micros":1}\n\n')); + controller.close(); + }, + }); + return new Response(body, { status: 200, headers: { 'content-type': 'text/event-stream' } }); + })); + const view = renderHook(() => useExplorerController(), { wrapper }); + try { + await act(async () => { + view.result.current.submit('older'); + await vi.advanceTimersByTimeAsync(0); + }); + await act(async () => { + view.result.current.submit('newer'); + await vi.advanceTimersByTimeAsync(0); + }); + expect(requests.filter((url) => url.includes('/api/explorer/queries') || url.startsWith('POST ')), + 'controller polled a run id instead of reading the stream').toEqual(['POST older', 'POST newer']); + expect(oldSignal?.aborted, 'controller polled a run id instead of reading the stream').toBe(true); + expect(view.result.current.run?.sources[0]?.watermark).toBe('newer'); + await act(async () => { + releaseOld(); + await vi.advanceTimersByTimeAsync(0); + }); + expect(view.result.current.run?.sources[0]?.watermark).toBe('newer'); + } finally { + releaseOld(); + view.unmount(); + } +}); + +it('reports premature EOF without hiding a delivered source', async () => { + const source = { + kind: 'source', + source: { + source_id: 'code_graph', source_label: 'Code graph', outcome: 'ready', completed_units: 0, total_units: 0, + coverage: { completeness: 'complete', eligible: 0, examined: 0, matched: 0, + excluded: 0, omitted: 0, unknown: 0, denominator: 0, unit: 'symbols', + omission_reasons: [] }, + freshness: 'fresh', watermark: 'partial-result', error_code: null, message: null, + page: { offset: 0, limit: 50, total: 0, next_offset: null, rows: [], metadata: {} }, + }, + }; + vi.stubGlobal('fetch', vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => { + if (init?.method === 'POST' && String(input).endsWith('/api/explorer/queries')) { + return new Response(`data: ${JSON.stringify(source)}\n\n`, { + status: 200, headers: { 'content-type': 'text/event-stream' }, + }); + } + return jsonResponse(404, { error: 'not found' }); + })); + const view = renderHook(() => useExplorerController(), { wrapper }); + try { + await act(async () => { + view.result.current.submit('graph'); + await vi.advanceTimersByTimeAsync(0); + }); + expect(view.result.current.run?.sources[0]?.watermark).toBe('partial-result'); + expect(view.result.current.transport).toMatchObject({ + state: 'error', + detail: 'Explorer stream ended without a final frame', + }); + expect(view.result.current.absence.confirmed).toBe(false); + } finally { + view.unmount(); + } +}); + +it('keeps a terminal outcome when stream cleanup fails', async () => { + const diagnostic = vi.spyOn(console, 'warn').mockImplementation(() => {}); + const encoder = new TextEncoder(); + vi.stubGlobal('fetch', vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => { + if (init?.method !== 'POST' || !String(input).endsWith('/api/explorer/queries')) { + return jsonResponse(404, { error: 'not found' }); + } + return new Response(new ReadableStream({ + start(controller) { + controller.enqueue(encoder.encode('data: {"kind":"final","state":"completed","elapsed_micros":7}\n\n')); + }, + cancel() { + throw new Error('cleanup failed'); + }, + }), { status: 200, headers: { 'content-type': 'text/event-stream' } }); + })); + const view = renderHook(() => useExplorerController(), { wrapper }); + try { + await act(async () => { + view.result.current.submit('graph'); + await vi.advanceTimersByTimeAsync(0); + }); + expect(view.result.current.run?.state).toBe('completed'); + expect(view.result.current.run?.elapsed_micros).toBe(7); + expect(view.result.current.transport).toBeUndefined(); + expect(diagnostic).toHaveBeenCalledWith('Explorer stream cleanup failed', expect.any(Error)); + } finally { + view.unmount(); + diagnostic.mockRestore(); + } +}); + +it('preserves the read error when stream cleanup also fails', async () => { + const diagnostic = vi.spyOn(console, 'warn').mockImplementation(() => {}); + const encoder = new TextEncoder(); + vi.stubGlobal('fetch', vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => { + if (init?.method !== 'POST' || !String(input).endsWith('/api/explorer/queries')) { + return jsonResponse(404, { error: 'not found' }); + } + return new Response(new ReadableStream({ + start(controller) { + controller.enqueue(encoder.encode('data: not-json\n\n')); + }, + cancel() { + throw new Error('cleanup failed'); + }, + }), { status: 200, headers: { 'content-type': 'text/event-stream' } }); + })); + const view = renderHook(() => useExplorerController(), { wrapper }); + try { + await act(async () => { + view.result.current.submit('graph'); + await vi.advanceTimersByTimeAsync(0); + }); + expect(view.result.current.transport?.state).toBe('error'); + expect(view.result.current.transport?.detail).not.toBe('cleanup failed'); + expect(diagnostic).toHaveBeenCalledWith('Explorer stream cleanup failed', expect.any(Error)); + } finally { + view.unmount(); + diagnostic.mockRestore(); + } +}); + +it('keeps the daemon sentence from a non-envelope refusal', async () => { + vi.stubGlobal('fetch', vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => + init?.method === 'POST' && String(input).endsWith('/api/explorer/queries') + ? jsonResponse(503, { detail: 'exact registered project scope is unavailable' }) + : jsonResponse(404, { error: 'not found' }), + )); + const view = renderHook(() => useExplorerController(), { wrapper }); + try { + await act(async () => { + view.result.current.submit('graph'); + await vi.advanceTimersByTimeAsync(0); + }); + expect(view.result.current.transport).toMatchObject({ + state: 'error', + detail: 'exact registered project scope is unavailable', + }); + } finally { + view.unmount(); + } +}); + +it('keeps HTTP authorization refusal distinct from a source failure', async () => { + vi.stubGlobal('fetch', vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => + init?.method === 'POST' && String(input).endsWith('/api/explorer/queries') + ? jsonResponse(403, { status: 'denied' }) + : jsonResponse(404, { error: 'not found' }), + )); + const view = renderHook(() => useExplorerController(), { wrapper }); + try { + await act(async () => { + view.result.current.submit('forbidden'); + await vi.advanceTimersByTimeAsync(0); + }); + expect(view.result.current.transport).toMatchObject({ state: 'denied', detail: 'HTTP 403' }); + expect(view.result.current.lanes.map((lane) => lane.state)).toEqual(['denied', 'denied', 'denied']); + } finally { + view.unmount(); + } +}); + +it('preserves a typed registry-unavailable refusal before any source frame', async () => { + const registry = { + schema_revision: 1, + scope: { project_id: 'proj_active', storage_mode: 'profile_sharded', store_root: '/data/active' }, + version: { entity_version: null, graph_version: null }, + time: { valid_time_micros: null, observation_time_micros: 1 }, + source_watermark: null, + authorization: { outcome: 'authorized' }, + coverage: { completeness: 'unknown', eligible: null, examined: null, matched: null, + excluded: null, omitted: null, unknown: null, denominator: null, unit: null, + omission_reasons: ['missing_registry'] }, + freshness: { state: 'unknown', observed_at_micros: null, watermark: null }, + domain_state: 'unknown', + legal_actions: [], + payload: { status: 'registry_unavailable' }, + }; + const fetchImpl = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => + init?.method === 'POST' + ? jsonResponse(200, registry) + : jsonResponse(404, { error: 'not found' }), + ); + vi.stubGlobal('fetch', fetchImpl); + useScope.getState().selectProject('proj_other', 'Other project', 'selected'); + const view = renderHook(() => useExplorerController(), { wrapper }); + try { + await act(async () => { + view.result.current.submit('fixture'); + await vi.advanceTimersByTimeAsync(0); + }); + expect(view.result.current.transport).toMatchObject({ + state: 'unknown', + detail: 'missing_registry', + }); + expect(fetchImpl.mock.calls.filter(([, init]) => init?.method === 'POST') + .map(([input]) => String(input))).toEqual(['/api/projects/proj_other/explorer/queries']); + expect(view.result.current.run?.sources).toEqual([]); + } finally { + view.unmount(); + } +}); diff --git a/dashboard/src/workspaces/explorer/evidence.test.ts b/dashboard/src/workspaces/explorer/evidence.test.ts index 7819cc5f4ed..bf5fac90a9b 100644 --- a/dashboard/src/workspaces/explorer/evidence.test.ts +++ b/dashboard/src/workspaces/explorer/evidence.test.ts @@ -37,7 +37,7 @@ describe('laneGrade', () => { watermark: null, }; const stale: ExplorerLaneReadModel = { state: 'stale', lane: 'code', errorCode: null, detail: null }; - const pending: ExplorerLaneReadModel = { state: 'pending', lane: 'code', phase: 'reading' }; + const pending: ExplorerLaneReadModel = { state: 'pending', lane: 'code' }; const locked: ExplorerLaneReadModel = { state: 'locked', lane: 'code', detail: 'read-only' }; expect(laneGrade(ready)).toBe('EXACT'); diff --git a/dashboard/src/workspaces/explorer/laneModel.test.ts b/dashboard/src/workspaces/explorer/laneModel.test.ts index 4280a6b54bc..70b4f1a9f80 100644 --- a/dashboard/src/workspaces/explorer/laneModel.test.ts +++ b/dashboard/src/workspaces/explorer/laneModel.test.ts @@ -1,10 +1,9 @@ import { describe, expect, it } from 'vitest'; +import { z } from 'zod'; import { DashboardEnvelopeV1Schema, - ExplorerQueryRunV1Schema, ExplorerSourceProgressV1Schema, type DashboardEnvelopeV1, - type ExplorerQueryRunV1, type ExplorerSourceProgressV1, } from '../../contracts/generated.ts'; import type { EnvelopeResult } from '../../data/query/envelope.ts'; @@ -23,6 +22,7 @@ import { runStateKind, searchLane, type ExplorerLaneReadModel, + type ExplorerStreamSnapshot, } from './laneModel.ts'; const KNOWLEDGE_FACT_ID = `fact.${'a'.repeat(64)}.${'7'.padStart(64, '0')}`; @@ -35,8 +35,7 @@ function progress(over: Record): ExplorerSourceProgressV1 { return ExplorerSourceProgressV1Schema.parse({ source_id: 'code_graph', source_label: 'Code graph', - phase: 'completed', - outcome: 'ready', + outcome: 'ready', completed_units: 0, total_units: 0, coverage: { @@ -60,30 +59,20 @@ function progress(over: Record): ExplorerSourceProgressV1 { }); } -function run(over: Record = {}): ExplorerQueryRunV1 { - return ExplorerQueryRunV1Schema.parse({ - run_id: 'run-1', - request: { query: 'graph', limit: 50, offset: 0 }, - request_revision: 'explorer-query-request-v1', - plan_revision: 'explorer-query-plan-v1', - merge_revision: 'source-local-no-merge-v1', - required_source_ids: ['code_graph', 'sessions', 'knowledge'], - ordering_policy: 'source_local_no_cross_source_merge', - explanation: 'test', - submitted_at_micros: 1, - completed_at_micros: 2, +function run(over: Partial = {}): ExplorerStreamSnapshot { + return { + query: 'graph', elapsed_micros: 1, state: 'completed', - finality: 'complete', sources: [], ...over, - }); + }; } -function answered(payload: ExplorerQueryRunV1): EnvelopeResult { +function browseAnswered(payload: T): EnvelopeResult { return { outcome: 'envelope', - envelope: DashboardEnvelopeV1Schema(ExplorerQueryRunV1Schema).parse({ + envelope: DashboardEnvelopeV1Schema(z.unknown()).parse({ schema_revision: 1, scope: { project_id: 'p', storage_mode: 'profile_sharded', store_root: '/data' }, version: { entity_version: null, graph_version: null }, @@ -106,45 +95,32 @@ function answered(payload: ExplorerQueryRunV1): EnvelopeResult, }; } -function browseAnswered(payload: T): EnvelopeResult { - const result = answered(run()); - if (result.outcome !== 'envelope') throw new Error('test envelope must be accepted'); - const envelope = result.envelope; - return { outcome: 'envelope', envelope: { ...envelope, payload } as DashboardEnvelopeV1 }; -} - describe('laneFromSourceProgress', () => { - // Moved from model.test.ts, where these two shapes covered `plannerLaneState`. - // Both invariants are unchanged: a source that is still reading contributes - // no rows and no total, and a source that reports no matching total gets - // `null` rather than a stand-in zero. - it('retains pending and unknown-total source states without inventing rows or zero totals', () => { - expect( - laneFromSourceProgress( - 'code', - progress({ - phase: 'reading', - outcome: 'pending', - completed_units: null, - total_units: null, - page: null, - }), - [], - ), - ).toEqual({ state: 'pending', lane: 'code', phase: 'reading' }); - + it('retains unknown-total source states without inventing zero totals', () => { expect( laneFromSourceProgress( 'knowledge', progress({ source_id: 'knowledge', source_label: 'Knowledge', - completed_units: 2, + completed_units: 1, total_units: null, + coverage: { + completeness: 'unknown', + eligible: null, + examined: 1, + matched: null, + excluded: null, + omitted: null, + unknown: null, + denominator: null, + unit: 'facts', + omission_reasons: ['verified memory graph coverage is incomplete'], + }, page: { offset: 0, limit: 25, @@ -360,11 +336,10 @@ describe('laneFromSourceProgress', () => { describe('searchLane', () => { it('keeps a client that cannot reach the daemon apart from an unavailable source', () => { - const clientOffline = searchLane('code', { outcome: 'transport', state: 'offline' }, 'graph', []); + const clientOffline = searchLane('code', undefined, { state: 'offline' }, 'graph', []); const sourceUnavailable = searchLane( 'code', - answered( - run({ + run({ sources: [ progress({ outcome: 'unavailable', @@ -374,7 +349,7 @@ describe('searchLane', () => { }), ], }), - ), + undefined, 'graph', [], ); @@ -418,63 +393,58 @@ describe('searchLane', () => { }); it('says a terminal run never named a source instead of showing it as reading', () => { - expect(searchLane('sessions', answered(run({ state: 'completed' })), 'graph', [])).toEqual({ + expect(searchLane('sessions', run({ state: 'completed' }), undefined, 'graph', [])).toEqual({ state: 'unanswered', lane: 'sessions', }); - expect(searchLane('sessions', answered(run({ state: 'pending' })), 'graph', [])).toEqual({ + expect(searchLane('sessions', run({ state: 'pending' }), undefined, 'graph', [])).toEqual({ state: 'pending', lane: 'sessions', - phase: null, }); }); it('does not attribute an earlier query\u2019s answer to the query on screen', () => { - const earlier = answered( - run({ - request: { query: 'other', limit: 50, offset: 0 }, - sources: [progress({})], - }), - ); + const earlier = run({ query: 'other', sources: [progress({})] }); - expect(searchLane('code', earlier, 'graph', [])).toEqual({ + expect(searchLane('code', earlier, undefined, 'graph', [])).toEqual({ state: 'pending', lane: 'code', - phase: null, }); }); it('waits rather than guessing before any coordinator answer', () => { - expect(searchLane('code', undefined, 'graph', [])).toEqual({ + expect(searchLane('code', undefined, undefined, 'graph', [])).toEqual({ state: 'pending', lane: 'code', - phase: null, }); }); it('keeps every lane condition distinct end to end', () => { const conditions: ExplorerLaneReadModel[] = [ - searchLane('code', { outcome: 'transport', state: 'offline' }, 'graph', []), + searchLane('code', undefined, { state: 'offline' }, 'graph', []), searchLane( 'code', - answered(run({ sources: [progress({ outcome: 'unavailable', page: null })] })), + run({ sources: [progress({ outcome: 'unavailable', page: null })] }), + undefined, 'graph', [], ), searchLane( 'code', - answered(run({ sources: [progress({ outcome: 'cancelled', page: null })] })), + run({ sources: [progress({ outcome: 'cancelled', page: null })] }), + undefined, 'graph', [], ), searchLane( 'code', - answered(run({ sources: [progress({ outcome: 'error', page: null })] })), + run({ sources: [progress({ outcome: 'error', page: null })] }), + undefined, 'graph', [], ), - searchLane('code', answered(run({ sources: [progress({})] })), 'graph', []), - searchLane('code', answered(run({ state: 'completed' })), 'graph', []), + searchLane('code', run({ sources: [progress({})] }), undefined, 'graph', []), + searchLane('code', run({ state: 'completed' }), undefined, 'graph', []), ]; expect(conditions.map((read) => read.state)).toEqual([ @@ -621,7 +591,7 @@ describe('laneEvidence', () => { describe('laneHits', () => { it('yields nothing for every lane that did not answer', () => { const notReady: ExplorerLaneReadModel[] = [ - { state: 'pending', lane: 'code', phase: null }, + { state: 'pending', lane: 'code' }, { state: 'unavailable', lane: 'code', errorCode: null, detail: null }, { state: 'cancelled', lane: 'code', errorCode: null, detail: null }, { state: 'error', lane: 'code', errorCode: null, detail: null }, diff --git a/dashboard/src/workspaces/explorer/laneModel.ts b/dashboard/src/workspaces/explorer/laneModel.ts index 839d5e3993f..3a30442f374 100644 --- a/dashboard/src/workspaces/explorer/laneModel.ts +++ b/dashboard/src/workspaces/explorer/laneModel.ts @@ -17,11 +17,9 @@ import type { EvidenceQuality } from '../../ui/EvidencePattern.tsx'; import type { DomainStateKind } from '../../ui/StateChip'; import type { - ExplorerQueryRunV1, ExplorerResultPageV1, ExplorerRunStateV1, ExplorerSourceIdV1, - ExplorerSourcePhaseV1, ExplorerSourceProgressV1, DashboardDomainStateV1, } from '../../contracts/generated.ts'; @@ -42,6 +40,16 @@ const LANE_SOURCE_ID: Record = { knowledge: 'knowledge', }; +export interface ExplorerStreamSnapshot { + readonly query: string; + readonly state: ExplorerRunStateV1 | 'pending'; + /** The coordinator's own terminal timing, or `null` until the terminal frame + * arrives. A pending or client-cancelled run has no measured duration, so it + * reports none rather than a fabricated zero. */ + readonly elapsed_micros: number | null; + readonly sources: readonly ExplorerSourceProgressV1[]; +} + /** * One lane's condition, as a closed union. * @@ -51,16 +59,13 @@ const LANE_SOURCE_ID: Record = { * and every `switch` over `state` is `never`-checked, so a new wire outcome * fails the build instead of silently rendering as an error. * - * A lane that is still working is `pending`, and it carries the wire's `phase` - * so `queued` and `reading` stay apart. + * A lane is pending until its source's completed event arrives. */ export type ExplorerLaneReadModel = - /** Still working. `phase` is the source's own; `null` when the pendingness - * is the client's (no coordinator answer yet, or a browse read in flight). */ + /** No source event has concluded for this lane yet. */ | { readonly state: 'pending'; readonly lane: LaneId; - readonly phase: ExplorerSourcePhaseV1 | null; } /** The source answered. Zero `hits` here means "answered with nothing", * which is a different fact from every other member of this union. */ @@ -139,9 +144,8 @@ export type ExplorerLaneReadModel = | { readonly state: 'unauthorized'; readonly lane: LaneId } /** The daemon knows the identity and will not serve this scope. */ | { readonly state: 'denied'; readonly lane: LaneId } - /** The project gateway serves the selected scope read-only, so the query - * run this lane needs cannot be created there. Nothing was dispatched; - * `detail` is the scope authority's own sentence. */ + /** The scope authority refuses this read, so nothing was dispatched; + * `detail` is the authority's own sentence. */ | { readonly state: 'locked'; readonly lane: LaneId; readonly detail: string } /** The response did not decode against the contract. */ | { readonly state: 'unsupported_schema'; readonly lane: LaneId } @@ -157,14 +161,15 @@ export type ExplorerLaneReadModel = }; /** - * The lane's condition when the current scope will not accept the query run. + * The lane's condition when the current scope will not accept the query read. * - * Creating a run is a POST, and the project gateway refuses every non-read - * request for a project that is not the active one. The controller consults - * the scope authority before dispatching, so a refused scope is rendered from - * its reason rather than from a 405 the daemon would have had to send back , - * and a scope the registry has not yet resolved is `unknown`, not refused. - * Returns `null` when the scope is writable and the run may proceed. + * The exact selected-project Explorer POST is admitted, so a registered + * selected project is writable here. The scope authority still refuses a scope + * it cannot resolve, such as a link naming a project the registry no longer + * holds. The controller consults it before dispatching, so a refused scope is + * rendered from its reason rather than from a daemon refusal, and a scope the + * registry has not yet resolved is `unknown`, not refused. Returns `null` when + * the scope is writable and the read may proceed. */ export function laneFromScope( lane: LaneId, @@ -236,7 +241,7 @@ function hitsForLane( } /** Whether the coordinator has stopped working on this run. */ -export function runIsTerminal(state: ExplorerRunStateV1): boolean { +export function runIsTerminal(state: ExplorerRunStateV1 | 'pending'): boolean { switch (state) { case 'pending': return false; @@ -269,8 +274,6 @@ export function laneFromSourceProgress( return { state: 'unanswered', lane }; } switch (source.outcome) { - case 'pending': - return { state: 'pending', lane, phase: source.phase }; case 'ready': { // `page` is nullable on every outcome in the Rust type, so a `ready` // source that arrived without one has genuinely returned nothing to @@ -350,7 +353,7 @@ export function laneFromTransport( ): ExplorerLaneReadModel { switch (domainState) { case 'loading': - return { state: 'pending', lane, phase: null }; + return { state: 'pending', lane }; case 'offline': return { state: 'offline', lane }; case 'unauthorized': @@ -363,10 +366,6 @@ export function laneFromTransport( return { state: 'cancelled', lane, errorCode: null, detail }; case 'error': return { state: 'error', lane, errorCode: null, detail }; - // The gateway refused the run as a write against a read-only scope. The - // controller normally catches this before dispatch, so reaching it here - // means the scope changed under an in-flight read; the daemon's sentence - // is carried as the detail either way. case 'locked': return { state: 'locked', @@ -399,23 +398,21 @@ export function laneFromTransport( */ export function searchLane( lane: LaneId, - result: EnvelopeResult | undefined, + snapshot: ExplorerStreamSnapshot | undefined, + transport: { state: DashboardDomainStateV1; detail?: string } | undefined, submittedQuery: string, terms: readonly string[], ): ExplorerLaneReadModel { - if (result === undefined) return { state: 'pending', lane, phase: null }; - if (result.outcome === 'transport') { - return laneFromTransport(lane, result.state, result.detail ?? null); + if (snapshot?.query !== submittedQuery) { + return transport + ? laneFromTransport(lane, transport.state, transport.detail ?? null) + : { state: 'pending', lane }; } - const run = result.envelope.payload; - if (run.request.query !== submittedQuery) return { state: 'pending', lane, phase: null }; - const source = run.sources.find((candidate) => candidate.source_id === LANE_SOURCE_ID[lane]); + const source = snapshot.sources.find((candidate) => candidate.source_id === LANE_SOURCE_ID[lane]); if (source !== undefined) return laneFromSourceProgress(lane, source, terms); - // The coordinator has finished and never named this source. Leaving the lane - // on `pending` would show a spinner for a read that will never arrive. - return runIsTerminal(run.state) - ? { state: 'unanswered', lane } - : { state: 'pending', lane, phase: null }; + if (transport) return laneFromTransport(lane, transport.state, transport.detail ?? null); + if (snapshot.state === 'cancelled') return { state: 'cancelled', lane, errorCode: null, detail: null }; + return runIsTerminal(snapshot.state) ? { state: 'unanswered', lane } : { state: 'pending', lane }; } /** @@ -432,7 +429,7 @@ export function browseLane( rowsOf: (data: T) => readonly Record[], terms: readonly string[], ): ExplorerLaneReadModel { - if (isPending) return { state: 'pending', lane, phase: null }; + if (isPending) return { state: 'pending', lane }; if (result === undefined) return { state: 'unanswered', lane }; if (result.outcome === 'transport') { return laneFromTransport(lane, result.state, result.detail ?? null); @@ -520,7 +517,7 @@ export function laneStateKind(read: ExplorerLaneReadModel): DomainStateKind { } /** The chip for the coordinator's own reading of a whole run. */ -export function runStateKind(state: ExplorerRunStateV1): DomainStateKind { +export function runStateKind(state: ExplorerRunStateV1 | 'pending'): DomainStateKind { switch (state) { case 'pending': return 'loading'; @@ -553,7 +550,7 @@ export function runStateKind(state: ExplorerRunStateV1): DomainStateKind { export function laneStateDetail(read: ExplorerLaneReadModel): string | undefined { switch (read.state) { case 'pending': - return read.phase ?? undefined; + return undefined; case 'ready': return undefined; case 'partial': @@ -575,7 +572,7 @@ export function laneStateDetail(read: ExplorerLaneReadModel): string | undefined case 'locked': return read.detail; case 'unanswered': - return 'the run never named this source'; + return 'the stream ended without this source'; case 'indeterminate': return read.detail ?? read.domainState; default: { diff --git a/dashboard/src/workspaces/explorer/panels.tsx b/dashboard/src/workspaces/explorer/panels.tsx index 0763322ce6a..00ded7c2871 100644 --- a/dashboard/src/workspaces/explorer/panels.tsx +++ b/dashboard/src/workspaces/explorer/panels.tsx @@ -1,31 +1,27 @@ -/** Explorer's query register chrome: the coordinator run's own state, drawn - * beside the query it answers, with the one explicit cancel control. Every - * value is the run's; the lanes below render each source's condition. */ +/** Explorer stream state and source progress beside the submitted query. */ import { StateChip, type DomainStateKind } from '../../ui/StateChip'; import { cn } from '../../ui/cn'; import { Meter } from '../../ui/instrument.tsx'; -import type { ExplorerQueryRunV1 } from '../../contracts/generated.ts'; -import type { EnvelopeResult } from '../../data/query/envelope.ts'; +import type { DashboardDomainStateV1 } from '../../contracts/generated.ts'; import type { ScopeWritability } from '../../data/scope/store.ts'; import type { RunProgress } from './controller.ts'; import { runStateKind } from './laneModel.ts'; +import type { ExplorerStreamSnapshot } from './laneModel.ts'; -/** What the register says while no run exists: the scope's refusal when the - * scope authority declined to dispatch one, otherwise the plan being admitted - * or the transport failure that answered instead. */ +/** A refused scope or failed response before any source frame arrives. */ function noRunReading( writability: ScopeWritability, - result: EnvelopeResult | undefined, + transport: { state: DashboardDomainStateV1; detail?: string } | undefined, ): { kind: DomainStateKind; detail: string } { switch (writability.state) { case 'read_only': - return { kind: 'locked', detail: 'no run created: the scope is read-only' }; + return { kind: 'locked', detail: writability.reason }; case 'unknown': - return { kind: 'unknown', detail: 'no run created until the scope is checked' }; + return { kind: 'unknown', detail: writability.reason }; case 'writable': - return result?.outcome === 'transport' - ? { kind: result.state, detail: result.detail ?? 'coordinator response unavailable' } - : { kind: 'loading', detail: 'admitting the source plan' }; + return transport + ? { kind: transport.state, detail: transport.detail ?? 'coordinator response unavailable' } + : { kind: 'loading', detail: 'reading sources' }; default: { const exhaustive: never = writability; return exhaustive; @@ -43,7 +39,7 @@ function noRunReading( * act is not shown pretending it might. */ export function RunRegister({ - result, + transport, run, writability, progress, @@ -51,8 +47,8 @@ export function RunRegister({ onCancel, className, }: { - result: EnvelopeResult | undefined; - run: ExplorerQueryRunV1 | undefined; + transport: { state: DashboardDomainStateV1; detail?: string } | undefined; + run: ExplorerStreamSnapshot | undefined; writability: ScopeWritability; progress: RunProgress | null; cancelling: boolean; @@ -60,7 +56,7 @@ export function RunRegister({ className?: string; }) { if (!run) { - const blocked = noRunReading(writability, result); + const blocked = noRunReading(writability, transport); return (
Run - + {progress !== null ? ( sources concluded ) : null} - - {Math.round(run.elapsed_micros / 1_000).toLocaleString()} ms - - - {run.run_id} - - {run.ordering_policy} + {run.elapsed_micros !== null ? ( + + {Math.round(run.elapsed_micros / 1_000).toLocaleString()} ms + + ) : null} {onCancel ? (