Skip to content
nautilus nautilus nautilus

Verified: Streaming and data quality

Each claim the Streaming and data quality page makes, with the tests that prove it in the last green CI run: 25 of 38 verified, 6 with no test yet. The claims live in docs/claims/streaming.yaml.

Last green CI run 16 Oct 2026, 14:48 UTC on c7618d3 · all runtime claims

STR-001 verified

With ?delta=1 the first frame is a complete snapshot (full true, seq 1) and every later frame carries only the tags whose value changed since the previous frame sent to that client; a quiet tick carries no tags.

where the docs say so

  • pass TestDeltaStreamSendsOnlyWhatChanged in server

STR-002 verified

Rewriting a tag with the same value is not a change and produces no delta.

where the docs say so

  • pass TestDeltaStreamSendsOnlyWhatChanged in server

STR-003 partly verified

seq is the client's own frame counter, starting at 1 for each new connection.

where the docs say so · Counting from 1 and incrementing are asserted; reset on a new connection is not asserted separately (TestDeltaIsPerClient covers a second connection's first frame being full).

  • pass TestDeltaStreamSendsOnlyWhatChanged in server

STR-004 verified

Deltas are per client: two clients at different points in the stream each receive their own correct delta.

where the docs say so · Client A is a change behind when B connects; one broadcast then gives B only the new change and A both.

  • pass TestDeltaIsPerClient in server

STR-005 verified

A full frame (replace, not merge) is sent when the controller's set of tag names changes, and the stream then returns to deltas.

where the docs say so

  • pass TestDeltaResyncsWhenTheTagSetChanges in server

STR-006 partly verified

A full resync frame is sent periodically (30 s by default, configurable via ResyncInterval) and a negative interval disables it.

where the docs say so · The 30 s default value is not asserted.

  • pass TestDeltaPeriodicResync in server
  • pass TestResyncCanBeDisabled in server

STR-007 verified

A delta client's merged state always equals the controller's store, even with writes running concurrently with broadcasts; no update is lost.

where the docs say so

  • pass TestDeltaMergedStateMatchesTheStore in server

STR-008 no test yet

A frame dropped for a slow client costs latency, never content: the client's generation advances only when a frame is enqueued, so the next frame carries what the dropped one would have.

where the docs say so · No test fills a client's queue to force a dropped frame and checks the next frame catches up; the concurrent-writes test covers ordering but not drops.

STR-009 verified

A client that asks for nothing gets the stream as it always was: whole frames, no seq, no full marker.

where the docs say so

  • pass TestDefaultStreamIsUnchanged in server

STR-010 verified

?full=1 forces whole frames even alongside ?delta=1.

where the docs say so

  • pass TestFullParamOverridesDelta in server

STR-011 verified

A delta frame keeps the headline diagnostics (ts, scans) on every tick.

where the docs say so · Checked on a later delta frame and on a frame whose scan block is gated out (?blocks=delta).

  • pass TestDeltaFrameKeepsDiagnostics in server

STR-012 no test yet

A delta frame is about 51x, 17x and 4.8x smaller than a full frame at 1 percent, 5 percent and 20 percent churn on 10,000 tags.

where the docs say so · Measured by a benchmark (FrameBytes), not asserted by any test; the ratios are not CI-checked.

STR-013 verified

With ?blocks=delta, the drivers, alarms and scan blocks are absent from a delta frame unless they changed: drivers when their hash of operator visible fields moves, alarms when rev moves, scan on a cadence.

where the docs say so

  • pass TestDeltaStreamGatesNonTagBlocks in server
  • pass TestScanBlockRidesItsCadence in server

STR-014 verified

The driver block is hashed over everything an operator would call a change and nothing that free-runs: a message counter climbing (DriverMetric.Volatile), an age ticking or the server's own observation stamp does not change the hash, while a real change (state, message, a device) does.

where the docs say so

  • pass TestHashDriversIgnoresWhatFreeRuns in server

STR-015 partly verified

DriverStatus.VolatileExtra excludes protocol-specific fields from the driver hash by key or by path (with * matching any key or list element), so `nodes.*.lastMsgMs` excludes the nested churn while the rest of the roster is still watched.

where the docs say so · `*` is only exercised over list elements (extra.nodes is a list); `*` matching any key of a nested map is not asserted.

  • pass TestHashDriversHonoursVolatileExtra in server
  • pass TestHashDriversIgnoresNestedChurn in server
  • pass TestVolatileExtraPathForms in server

STR-016 partly verified

The scan block rides a cadence (DiagnosticsInterval, 3 s by default) while the headline rides every frame; a negative interval sends the scan block on every frame.

where the docs say so · The 3 s default is not asserted, and neither cadence test checks that the headline (ts, scans) is present on the frames where the scan block is absent.

  • pass TestScanBlockRidesItsCadence in server
  • pass TestScanBlockOnEveryFrameWhenDisabled in server

STR-017 verified

A full frame carries all blocks (scan, drivers, alarms), so a client is never more than one resync from a block it can vouch for.

where the docs say so

  • pass TestDeltaResyncCarriesEveryBlock in server

STR-018 no test yet

A client's record of which blocks it holds advances only when a frame is enqueued, so a dropped frame re-offers the block rather than losing it.

where the docs say so · Only the connect-repeat superset is tested; no test drops a frame and checks the block is re-offered.

STR-019 verified

quality is not gated; it is sent whole on every delta frame, and clears when the entries return to good.

where the docs say so · An unchanged Bad quality is on the next delta frame too, and the map clears when the tag returns to Good.

  • pass TestDeltaFrameCarriesQuality in server

STR-020 no test yet

A frame floor of 4.3 MB a minute drops to about 0.15 MB (about 28x less) for a client subscribed to no tags against a 55-node driver status.

where the docs say so · Benchmark figure (FrameFloor); not asserted by a test.

STR-021 partly verified

Driver freshness travels as moments: metrics[].atMs and a server-stamped asOfMs on the status, so a client renders age as asOfMs minus atMs.

where the docs say so · Only asserts asOfMs is stamped on a driver status; atMs is not asserted on a real adapter, and the client-side age rendering is not a Go test.

  • pass TestDeltaStreamGatesNonTagBlocks in server

STR-022 verified

Merging blocks is opt-in: a delta client that did not send ?blocks=delta still gets every block on every frame, and a plain stream does too.

where the docs say so

  • pass TestDeltaStreamWithoutOptInCarriesEveryBlock in server
  • pass TestPlainStreamCarriesEveryBlockEveryFrame in server

STR-023 no test yet

/api/meta reports blockDeltas true on a controller that understands ?blocks=delta.

where the docs say so · TestMetaAdvertisesQualityAndDeltas checks quality and deltas only, not blockDeltas.

STR-024 verified

?tags= takes comma-separated globs matched with path.Match against the whole dotted tag name, so Tank* matches Tank101 and Tank101.Level and *.Level matches member addresses.

where the docs say so

  • pass TestMatchAnySpansDottedNames in server
  • pass TestTagFilterParsing in server

STR-025 verified

The tag filter applies to every frame including the first (plain and delta streams alike), and to /api/state.

where the docs say so

  • pass TestStreamTagFilter in server
  • pass TestFilteredDeltaStream in server
  • pass TestStateTagFilter in server

STR-026 partly verified

Diagnostics, driver status and alarm counts are never filtered by a tag filter.

where the docs say so · Asserts only that scan stats survive a filtered /api/state; drivers and alarms are not checked.

  • pass TestStateTagFilter in server

STR-027 verified

A tag pattern path.Match cannot compile is a 400, not a silent match-nothing.

where the docs say so

  • pass TestBadTagPatternIsRejected in server

STR-028 verified

Frames carry a quality map holding only non-good entries (good is absent), and a healthy plant omits the field entirely.

where the docs say so

  • pass TestFrameOmitsQualityWhenEverythingIsGood in server
  • pass TestFrameCarriesQuality in server
  • pass TestQualityDropsGoodEntries in runtime
  • pass TestQualityIsEmptyWhenHealthy in runtime

STR-029 verified

A name in quality need not be in tags: a notConnected source with no value is still reported without inventing a tag value.

where the docs say so

  • pass TestFrameCarriesQuality in server

STR-030 verified

The quality wire tokens are good, stale, bad and notConnected.

where the docs say so

  • pass TestQualityTokensAreStableWireFormat in io

STR-031 verified

The quality map is filtered by the same tag filter, so a filtered stream never carries quality for a tag it is not sending.

where the docs say so · Asserted on /api/state and on /api/stream: a filter keeps exactly the kept tag's quality and drops the others'.

  • pass TestQualityIsFiltered in server

STR-032 verified

A driver implementing io.QualityReporter is authoritative: whatever it reports about a tag stands, including over the runtime's derived staleness; io.Memory implements it.

where the docs say so

  • pass TestQualityFromDriverWins in runtime
  • pass TestMemoryReportsQuality in io

STR-033 verified

For tags the driver said nothing about, a failed (or not yet happened) input read makes every driver-bound input stale, and it clears when reads recover.

where the docs say so

  • pass TestQualityDerivesStaleFromFailedReads in runtime
  • pass TestQualityBeforeFirstScan in runtime

STR-034 verified

A failed output write does not mark inputs stale.

where the docs say so

  • pass TestQualityIgnoresFailedWrites in runtime

STR-035 verified

The Sparkplug host driver reports quality from what it knows: which edge node died (its tags stale) and which has never birthed (notConnected).

where the docs say so

STR-036 verified

/api/meta reports quality true when the controller can report quality at all (and false when nothing could ever be non-good), and deltas true.

where the docs say so · /api/meta reports quality true on a driver-bound controller and false on a driverless one with no inputs.

  • pass TestMetaAdvertisesQualityAndDeltas in server
  • pass TestReportsQuality in runtime

STR-037 partly verified

A dotted member path resolves to its root tag's quality; an unknown tag is good.

where the docs say so · The client-side RealtimeClient.quality() and delta merge (hmi/src/lib/delta.ts) are TypeScript and not covered by a Go test; the Go test covers the runtime resolution only, and "an exact entry for the full path still wins" is not asserted.

  • pass TestTagQualityResolvesDottedPathsToTheirRoot in runtime

STR-038 no test yet

The HMI client's delta merge keeps frame.tags complete and retains the last scan, drivers and alarms blocks, and falls back to pass-through against a controller without deltas.

where the docs say so · Client-side TypeScript behaviour with its own non-Go tests (hmi/src/lib/delta.ts); not in the Go or naut test results.