Skip to content

Direct snapshot notifications

Implemented October 20, 2026. A web publisher can now react to each native publication without adding a polling interval. The experimental server uses this path for real stdin and followed files; fixture replay keeps its synthetic timer. The production web server and embedded dashboard use this notification path.

API and ownership

Running::snapshot_reader() returns an owned, read-only SnapshotReader that can outlive ingestion. latest() clones a PublishedSnapshot containing the current generation and snapshot. Generation zero is initial state; each native publication advances it. This metadata does not change CLI JSON schema 2.

Cargo feature snapshot-notifications enables the asynchronous subscription and is also included by default through web:

let mut publications = running.snapshot_reader().subscribe()?;
while let Some(publication) = publications.changed().await {
    // Encode publication.snapshot and fan out the owned frame here.
}
running.join()?;
  • The first call returns current state immediately, including a final snapshot when ingestion has already completed. Later calls wait for a new generation.
  • Intermediate publications coalesce. A slow receiver obtains the latest complete snapshot; there is no queue to grow or replay. Alert evaluation still sees the existing native publication path.
  • One asynchronous publisher can subscribe at a time. A second subscription returns io::ErrorKind::AlreadyExists. Fan out serialized frames from the one publisher to browser clients. Dropping a subscription permits replacement, even when a previous notification is in flight.
  • Cancelling a pending changed() wait does not consume an unseen generation. Dropping a reader/subscription does not stop ingestion.
  • The worker closes publication on normal exit and unwinding. An unseen last publication is delivered before None. A panic does not invent a final state; use Running::join() to propagate the worker result.

The existing snapshot mutex protects generation, state, and registration together. Publication releases it before calling Notify::notify_one. Notification permits coalesce; generation checks handle publication before/during wait registration and discard stale permits. Encoding and network I/O receive owned snapshots with no ingestion lock retained. The worker still publishes approximately every 100 ms, plus immediate final state; this change adds no per-record work.

The standalone --no-default-features --features snapshot-notifications build enables only Tokio's sync primitives. The subscription starts no runtime; the caller supplies the executor. Default builds now include web support, whose runtime starts only in web mode. --no-default-features excludes Tokio from the active normal dependency graph. The asynchronous subscription adds one weak registration and one notifier for the active publisher, independent of browser-client count.

Bounded presentation data (unreleased additions)

Current main adds two fields to the owned Rust Snapshot:

  • severity_history: Vec<SeverityCounts> contains up to 60 completed seconds, aligned with history. Each point has warn: u64 and error: u64, where error includes fatal. The engine keeps a fixed ring and clones only this bounded view at publication; changing --window does not extend history.
  • activity: Activity contains Option<f64> ages for the last record and last error/fatal record, computed from monotonic processing time at publication. None means no matching record observed. A retained snapshot's ages do not change as wall time advances.

The engine also attaches optional parsing session evidence with six fixed rule counters and two issue counters; see format diagnostics. These fields, like the bounded recent_errors, have #[serde(skip)]. Serializing Snapshot directly therefore preserves CLI JSON schema 2. The web encoder explicitly adds presentation fields at the envelope level under web schema 1; see the field types, validation, and compatibility rules. Library callers constructing snapshots must keep total and severity history lengths aligned and counts consistent before calling WebFrame::encode.

Coverage adds no stored history or serialized field. Counts::recognized_records() returns records minus unknowns (saturating), and recognized_ratio() returns None for an empty denominator. Use the rolling window's counts for the same scope as the dashboard, rather than session totals.

These additions do not introduce a publication queue, persistence, an inference worker, or per-client ingestion work. A caller retaining arbitrarily many owned snapshots can still grow its own memory; built-in consumers retain bounded current state. Display freeze retains a snapshot while ingestion and alert evaluation continue. Read time scopes and interpretation before using these measurements as a health signal.

Historical local freshness validation (October 20, 2026)

The measurement record contains the tested source revision, binary hash, host/toolchain, audit identity, and all eight input scenarios. There are 25 host-monotonic producer-write-to-DOM trials per scenario, with exact injected counts and automation overhead included.

The table compares p95 milliseconds with the earlier polling run. These are separate local runs on the same Apple M3/Chromium setup, not randomized paired trials or physical screen-paint measurements.

Source / load SSE polling → notifications WebSocket polling → notifications
Stdin / idle 218.7 → 136.1 191.1 → 135.9
Stdin / paced 20K records/s 205.8 → 107.5 183.7 → 103.1
File / idle 183.6 → 109.4 188.6 → 108.0
File / paced 20K records/s 190.3 → 106.6 189.1 → 105.6

All final counts matched. Maximum per-scenario p99 was 150.8 ms, and maximum observed real-input server shutdown was 78.9 ms. This removes the web publisher's extra timer; input readiness, native publication cadence, scheduling, and browser rendering still contribute latency. Maximum ingestion overhead and long-duration resource gates have not been established by this paced workload.

Verification passed: 55 default Rust tests, 61 with notifications enabled, two experiment Rust tests, and 11 Node/network/browser checks including native hidden-tab resume. Clippy passes with warnings denied in default and notification modes. Tests cover slow/cancelled receivers, replacement, publication/closure races, idle-window expiry, EOF without the replay timer, a quiet retained final stream, and exact live-input totals with an unread web client. CI is configured for both feature modes on macOS and Linux; the new CI configuration has not been executed remotely here.

Reproduce after building the release experiment:

cargo test --locked
cargo test --features snapshot-notifications --locked
node experiments/web-transport/pipeline.mjs --samples 25 \
  --output experiments/web-transport/results/pipeline-notifications.json