P3: add sustained Sampled Values stream analysis

[masarray]

P3 — Sampled Values Analysis

This advances ROADMAP.md Priority 2 on top of the merged P0-P2 baseline.

Implemented

• bounded sustained SV stream registry using the existing SvObservedStreamKey identity;
• incremental smpCnt continuity, wrap, missing-sample, duplicate and out-of-order evidence;
• observed frame/sample-rate, arrival-jitter and large-interval/dropout evidence without retaining packet payload history;
• explicit timestamp-evidence claim boundaries and smpSynch observations;
• deterministic RMS/fundamental-phasor primitive for already mapped/scaled windows;
• SvSustainedObservationSession as one parsed-frame intake for the existing observation/SCL-comparison path plus sustained analysis;
• source-neutral equivalence for already parsed LiveCapture and PcapReplay frames;
• fail-closed admission: a frame rejected by the canonical observation path does not advance sustained state;
• bounded 10,000-frame synthetic ingestion regression;
• SvSclBoundMeasurementProjector, reusing the existing SCL payload layout and decoder rather than adding a second decoder;
• exact APPID/destination/VLAN/svID/DataSet/confRev gating before SCL-backed payload projection;
• evidence-backed engineering scaling only for the explicitly supported fixed 4-current/4-voltage value-quality protection layout;
• optional explicit CT/VT measurement context with stream-key/svID validation before primary/secondary-equivalent conversion;
• raw-only preservation when SCL binding exists but an approved engineering scale is not established;
• SvEngineeringWindowAnalyzer: bounded per-stream/per-channel one-cycle engineering windows feeding the existing RMS/phasor primitive only from successfully scaled SCL-bound samples;
• explicit sample-rate/fundamental-frequency provenance; unknown/profile-inferred frequency is rejected so 50/60 Hz is never guessed;
• one-cycle sample-count validation with bounded samples-per-cycle and a theoretical 64 MiB retained-buffer configuration guard;
• reuse of SvSampleCounterTracker for engineering-window continuity; gap/duplicate/out-of-order/restart evidence discards partial cycles instead of bridging corrupted windows;
• channel metadata/timebase evidence changes reset partial state before new RMS/phasor results are emitted;
• regression coverage for clean cycle phasor/RMS, raw-only exclusion, gap/duplicate reset, normal wrap, metadata rebinding, non-integral/inferred timebase rejection, and bounded engineering registries.

Architecture / evidence boundary

The existing SV parser, payload decoder, SCL/profile binding and publisher remain authoritative. P3 consumes SampledValuesFrame after decode; it does not add a raw capture parser, guess DataSet order from word positions, guess engineering units, silently invent CT/VT ratios, or choose a nominal 50/60 Hz frequency. Ordinary arrival timestamps and gaps remain observation evidence, not automatic proof of PTP quality or physical-network loss.

SvEngineeringWindowAnalyzer consumes only the fail-closed SvSclBoundMeasurementProjection. Raw-only projected values never enter engineering RMS/phasor state. Sample rate, nominal frequency, and optional counter-wrap evidence are explicit inputs with provenance; partial windows are discarded whenever continuity, channel identity, or timebase evidence changes.

Documentation: docs/P3_SAMPLED_VALUES_ANALYSIS.md.

Remaining before P3 completion

• application live-capture and PCAP byte-source integration through the established parser/session;
• carrying explicit timebase/frequency evidence from the application/session boundary into SvEngineeringWindowAnalyzer;
• sanitized real/replay validation fixtures and longer bounded soak evidence;
• evidence/export contracts suitable for applications without retaining customer/live-network identifiers.

PR remains Draft until those integration/validation items are complete.