Live sampled-domain protocol (experimental, version 2)

Run viewalyzer-cli domain-stream. This probe-independent process reads NDJSON requests on stdin and writes NDJSON replies on stdout. It does not run sidecars. Closing stdin exits. The current interface replaces version 1; no legacy path is implemented.

{"type":"ready","protocol":2,"domain_api":1,"capabilities":["sampled-domains","samples","reset","structured-dwarf","presentation","sampling-settings","typed-actions-v1","domain-validation-v1"]}

Every request has an unsigned id and an op. Replies echo the ID with ok: true, result: ... or ok: false, error: .... Unknown fields are rejected.

{"id":2,"op":"samples","domain":"com.vendor.device","t_us":50000,"samples":[{"channel":"temperature","t_us":42000,"value":-0.75}],"unavailable":[]}

t_us is the host analysis clock in microseconds, strictly increasing within a segment. Each sample retains its acquisition timestamp; timestamps increase per channel and cannot exceed analysis time. Different channels need not be sampled atomically. Types are u8, u16, u32, i8, i16, i32, and f32. Samples must be finite and fit the declared type. Invalid batches change no history. Send every acquired point, including zeros and transient clear-on-read counts; do not resample a held latest value on each analysis tick.

Missing from a batch means no new observation. Explicit unavailable inputs end their segments. A per-input gap greater than three requested periods (minimum 250 ms) also ends its segment. Hosts reset at pause/resume, target reset, and input rebinding. Halted time never contributes to duration rules.

Results contain domain, t_us, latest values with labels/metadata, newly emitted per-channel samples, rules, and findings. Derived sample timestamps retain the source observation time. Empty analysis ticks do not replay points. Rules are unavailable, collecting, or ready (evaluable, not passed). Findings carry rule identity, severity, explanation, time span, peak and channel evidence. Hosts merge overlapping spans by rule ID to retain session history. The shared derivations and verdict evaluator also interpret saved recordings.

Acquisition contract

The host resolves register names through SVD, exact symbols through the matching ELF, bounds member offsets to that symbol, and bounds ring reads to the declared fixed-stride symbol layout. Ring ownership reduction yields a u32 count. SVD is optional for variables/rings without register preconditions. Missing sources remain unavailable with reasons. Unsupported/intrusive rows are not read. Declared clear-on-read counters allow consuming reads when SVD read effects are clear; write-only and other destructive effects remain refused. Preconditions are checked continuously by BKPT Debug using its existing polling channel.

The schema's coalesce_gap_bytes permits a host to merge safe ranged reads; it does not require merging. BKPT Debug currently issues separate bounded source reads and shares identical reads within a sweep. Requested rates remain intact; actual rates and analysis failures are reported in Trace Health. Changes between reads cannot be counted as known lost events. Cache-coherence notes belong to the domain and remain visible beside the input.

Bounds

Requests: 1 MiB per line; 16 domains; 1–64 inputs per domain; 60-second maximum rule window; 65,536 retained actual samples per domain. Requested rate is not silently reduced. Buffer overflow explicitly invalidates the analysis history. Names beginning with @ are reserved for acquisition guards. Instrument sidecars are outside this live debugger interface. Hosts bound pending requests, reply size, timeouts, and finding history. Retry starts fresh observation windows.

The resolve operation uses transport protocol 2. Trace Domain v1 structured sources require an engine advertising structured-dwarf and domain_api: 1. A plan contains a root address, scalar size, ordered offset/deref steps and writable allocated ELF ranges. It is a bounded acquisition plan, not permission to read arbitrary memory. Adapters recheck pointers per sample and report unavailable on null, replacement, bounds failure or incomplete reads. Acquisition owns the probe; this process only reads the descriptor/ELF and evaluates observations.

Typed actions

These additive operations retain protocol 2 and require typed-actions-v1. load returns { "revision": N, ... }. Replacing or unloading a domain makes old action revisions invalid. An action lookup always uses the currently loaded descriptor; callers cannot submit a replacement action body to encode or resolve. No action request performs target IO in this process.

The host supplies register metadata from its own SVD, never from webview input. Its shape and strict planner are defined in va-domain/src/register_actions.rs; it includes register size/access/read/write effects, fields, write constraints, write enumerations and ambiguity flags. RAM plans use the structured acquisition shape; mailbox plans contain the verified ABI address/size/capacity. These plans are host-internal. The editor receives only action identity, input metadata, availability, binding and result. See typed actions for encoding, execution, concurrency and completion rules.

Authoring diagnostics

The domain-validation-v1 capability supports passing original JSON as text to validate. Prefer this form for files: it preserves duplicate keys and syntax locations. Invalid descriptors return ok: false, the existing readable error, and an errors array with path, JSON Pointer pointer, message, and optional syntax line and column. These are the same diagnostics as viewalyzer-cli parse-trace-domain and desktop parsing. The older descriptor form remains supported; it cannot recover duplicate keys already lost by the client's JSON decoder. Validation accepts all domain kinds. Live observation capability checks remain part of load; Debug requires a sampled-state domain.