diff --git a/src/client/api.rs b/src/client/api.rs index e885301..07c991d 100644 --- a/src/client/api.rs +++ b/src/client/api.rs @@ -724,6 +724,11 @@ pub struct SyncContentRequest { /// `GET /v1/jobs/{id}` — an index job's progress. `completed_at` is the /// terminal signal (set once the worker finishes, success or fail); /// `error` is set only on failure. +/// +/// The server embeds nothing itself: docstore derives the chunks and the +/// embeddings of the staged snapshot. `files_embedded` counts the files that +/// docstore reports ready, so it grows while docstore derives, not while the +/// client uploads. The job completes after the code graph of the snapshot. #[derive(Debug, Deserialize)] #[serde(rename_all = "camelCase")] pub struct JobStatus { @@ -735,10 +740,21 @@ pub struct JobStatus { #[serde(default)] pub files_deleted: i64, pub files_failed: i64, + /// The chunk count of the copy's published snapshot. Set when docstore + /// completed the derivations of the job. #[serde(default)] pub chunk_count: Option, #[serde(default)] pub error: Option, + /// The worker stage: `Deriving` while docstore derives the staged files, + /// `Graph` while the published snapshot waits for its code graph. Absent + /// from a server older than these stages. + #[serde(default)] + pub current_stage: Option, + /// Files per second: the latest sample while docstore derives, then the + /// average of the job. + #[serde(default)] + pub operations_per_second: Option, /// Set once the worker picks the job up (i.e. it's running). #[serde(default)] pub started_at: Option, diff --git a/src/commands/index.rs b/src/commands/index.rs index 34b5b65..31cce5a 100644 --- a/src/commands/index.rs +++ b/src/commands/index.rs @@ -145,6 +145,18 @@ fn poll_interval(elapsed: std::time::Duration) -> std::time::Duration { } } +/// The phase that the heartbeat names. Docstore derives the staged files while +/// the server reports `Deriving`; their count grows only then. In `Graph` the +/// files are searchable and the job waits for the code graph of the snapshot. +fn phase(job: &api::JobStatus) -> &'static str { + match job.current_stage.as_deref() { + Some("Graph") => "building graph", + Some("Paused") => "paused", + _ if job.started_at.is_some() => "embedding", + _ => "queued", + } +} + /// Poll the index job until the worker finishes embedding, reporting the /// outcome. The job runs server-side regardless of whether we keep waiting, so /// a timeout here isn't a failure — just stop watching. @@ -161,6 +173,7 @@ async fn wait_for_job(client: &Client, job_id: &str) -> Result<()> { embedded = job.files_embedded, failed = job.files_failed, chunks = job.chunk_count.unwrap_or(0), + files_per_sec = job.operations_per_second.unwrap_or(0.0), "indexed", ); return Ok(()); @@ -169,7 +182,8 @@ async fn wait_for_job(client: &Client, job_id: &str) -> Result<()> { info!( %job_id, secs = JOB_WAIT.as_secs(), - "still embedding; continues server-side — check back with search", + "still {}; continues server-side — check back with search", + phase(&job), ); return Ok(()); } @@ -177,18 +191,15 @@ async fn wait_for_job(client: &Client, job_id: &str) -> Result<()> { let now = std::time::Instant::now(); if now >= next_progress { let progress = JobProgress::from(&job); - let phase = if job.started_at.is_some() { - "embedding" - } else { - "queued" - }; info!( %job_id, elapsed_secs = start.elapsed().as_secs(), embedded = progress.embedded, deleted = progress.deleted, failed = progress.failed, - "{phase}: {}/{} processed", + files_per_sec = job.operations_per_second.unwrap_or(0.0), + "{}: {}/{} processed", + phase(&job), progress.processed, progress.total, ); @@ -201,7 +212,7 @@ async fn wait_for_job(client: &Client, job_id: &str) -> Result<()> { #[cfg(test)] mod tests { - use super::{JobProgress, api, poll_interval, terminal_result}; + use super::{JobProgress, api, phase, poll_interval, terminal_result}; #[test] fn polling_is_responsive_for_fast_jobs_then_backs_off() { @@ -228,6 +239,8 @@ mod tests { files_failed: failed, chunk_count: Some(21), error: error.map(str::to_owned), + current_stage: Some("Deriving".into()), + operations_per_second: Some(1.5), started_at: Some("2026-07-14T00:00:00Z".into()), completed_at: completed.then(|| "2026-07-14T00:01:00Z".into()), } @@ -238,6 +251,17 @@ mod tests { assert!(!terminal_result("job-1", &job(false, 0, None)).unwrap()); } + #[test] + fn heartbeat_names_the_native_stage_of_the_job() { + let mut deriving = job(false, 0, None); + assert_eq!(phase(&deriving), "embedding"); + deriving.current_stage = Some("Graph".into()); + assert_eq!(phase(&deriving), "building graph"); + deriving.current_stage = None; + deriving.started_at = None; + assert_eq!(phase(&deriving), "queued"); + } + #[test] fn completed_worker_error_fails_the_command_as_embedding() { let error = terminal_result("job-2", &job(true, 12, Some("store unavailable"))) diff --git a/src/engine/coordinator/tests.rs b/src/engine/coordinator/tests.rs index c29a1a5..d803876 100644 --- a/src/engine/coordinator/tests.rs +++ b/src/engine/coordinator/tests.rs @@ -747,6 +747,8 @@ fn job(completed: bool, failed: i64, error: Option<&str>) -> api::JobStatus { files_failed: failed, chunk_count: completed.then_some(12), error: error.map(str::to_string), + current_stage: None, + operations_per_second: None, started_at: Some("2026-07-31T00:00:00Z".into()), completed_at: completed.then(|| "2026-07-31T00:00:01Z".into()), } diff --git a/src/query/render.rs b/src/query/render.rs index 727c246..9e5edd5 100644 --- a/src/query/render.rs +++ b/src/query/render.rs @@ -740,6 +740,8 @@ mod tests { files_failed: 3, chunk_count: None, error: None, + current_stage: None, + operations_per_second: None, started_at: Some("2026-07-14T00:00:00Z".into()), completed_at: None, };