diff --git a/README.md b/README.md index 4dd8973..089ba1f 100644 --- a/README.md +++ b/README.md @@ -52,8 +52,7 @@ supported vehicle modules. Supported readouts convert only at presentation; SI source values, model calculations, configuration fingerprints and canonical dashboard definitions remain unchanged. See [display units](docs/live-dashboard.md#display-units). - Focused correction Step-06A and its worker verification are complete. Step-06 - remains not accepted pending manual review; Step-07 remains blocked. + Focused correction Step-06A is accepted. - UI routes: `/` foundation, `/execution-targets` explicit metadata selection, `/vehicle-profiles` explicit profile import/revision selection/inspection/export, `/diagnostics` static synthetic diagnostics, `/simulation` dynamics, and a @@ -70,21 +69,24 @@ supported vehicle modules. constraint; supplied values must match a known module identity and never fill unknown module data. See the schema guide for exact grammar and limits. -### In progress +### Implemented, pending manual review -The Step-06 initial review findings for invalid-preference rejection and -unavailable/wrong-type readouts are corrected by Step-06A, with worker -verification complete. Step-06 is still not accepted pending manual review; -Step-07 remains blocked. The Step-04 and Step-05 acceptances include their -listed corrections. +Step-07 adds bounded in-memory recording of actual static-v1 and dynamic-v2 +diagnostic operations, explicit source-sensitive local archive save/readback, +strict schema-v1 validation, and shared recording/inspection controls in both +host workflows. The complete nine-project Release build, all 303 tests, native +capture/save/restart/readback smoke, and route-unmount retention check passed. +Worker completion is not orchestrator acceptance; see the +[Step-07 worker report](prompts/Step-07-Report.md). ### Planned -Telemetry recording/replay, calibration values/editing/backups, AI and real -hardware operations require later approved assignments. Dynamics estimates are -synthetic, not manufacturer prediction, vehicle compatibility, physical access, -safe tuning advice or authorization. No capability is implemented merely -because it appears in the product vision or roadmap. +Replay, calibration values/editing/backups, AI and real hardware operations +require later approved assignments. Saved recordings are local file archives, +not crash-durable live streaming or playback. Dynamics estimates are synthetic, +not manufacturer prediction, vehicle compatibility, physical access, safe +tuning advice or authorization. No capability is implemented merely because +it appears in the product vision or roadmap. ## Architecture @@ -97,8 +99,9 @@ browser-hosted WASM shell, Blazor Server host or second application executable. The application slices provide explicit target metadata resolution, vehicle-profile metadata import/list/select/export, dynamics configuration -catalog/import/export, simulation-only diagnostic sessions, and a shared -display-unit preference with a native local-preference adapter. The Client +catalog/import/export, simulation-only diagnostic sessions, bounded session +recording and archive inspection, and a shared display-unit preference with a +native local-preference adapter. The Client composes separate static and dynamics synthetic providers through provider-neutral factory contracts and a session-lifetime in-memory profile/ configuration catalog. Import never opens a session; metadata resolution never @@ -209,6 +212,7 @@ acceptance remains the orchestrator's responsibility. - [Synthetic diagnostics protocol v2](docs/synthetic-diagnostics-v2.md) - [Simulation definitions and state](docs/simulation.md) - [Live dashboard usage and contracts](docs/live-dashboard.md) +- [Telemetry archive schema v1 and recording](docs/telemetry-archive-v1.md) - [Vehicle-profile schema v1 and usage](docs/vehicle-profile-schema-v1.md) - [Build, tests and native smoke guide](docs/build-and-test.md) - [ADR-0001: historical .NET foundation](docs/adr-0001-headless-foundation.md) @@ -225,6 +229,7 @@ acceptance remains the orchestrator's responsibility. - [Step-04 worker report](prompts/Step-04-Report.md) - [Step-04A corrective worker report](prompts/Step-04A-Report.md) - [Step-04B corrective worker report](prompts/Step-04B-Report.md) +- [Step-07 worker report](prompts/Step-07-Report.md) - [Step-05A corrective worker report](prompts/Step-05A-Report.md) - [Orchestrator-owned roadmap](prompts/ROADMAP.md) and [orchestration state](prompts/STATE.md) diff --git a/docs/README.md b/docs/README.md index d5ce01d..3a28df7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -4,9 +4,11 @@ The implemented scope includes the accepted Step-01/Step-01A foundation, accepted Step-02/Step-02A vehicle-profile metadata, the accepted Step-03 synthetic diagnostic vertical slice with its integrity corrections, the accepted Step-04/04A/04B synthetic dynamics work, the accepted Step-05/05A/05B -session-owned live dashboard, and the Step-06 Imperial-default display-unit -preference. Its focused Step-06A correction is worker-complete with review -pending; Step-06 is not accepted and Step-07 remains blocked. +session-owned live dashboard, and the accepted Step-06/06A display-unit +preference. Step-07 implements bounded session recording, local archive +readback and shared host controls. The full nine-project Release build, tests +and native save/restart/readback smoke are complete; worker acceptance remains +pending manual orchestrator review. - [Architecture](architecture.md): actual nine-project graph, responsibilities, route ownership and provider/reference boundaries. @@ -21,6 +23,9 @@ pending; Step-06 is not accepted and Step-07 remains blocked. - [Live dashboard usage and contracts](live-dashboard.md): configuration limits, verified bindings, quality/range/freshness, ownership, display-unit preference/conversions and v1/v2 sample context. +- [Telemetry archive schema v1 and recording](telemetry-archive-v1.md): capture + cutover, actual-operation observations, bounded limits, local save/readback, + failure states and strict archive validation. - [ADR-0001: Headless .NET 10 foundation](adr-0001-headless-foundation.md): historical foundation decisions; dual-shell/deferred-host decision superseded. - [ADR-0002: Single native shell and feature slices](adr-0002-single-shell-vsa.md): @@ -50,5 +55,6 @@ historical/worker reports for their own execution evidence: [Step-05A corrective worker report](../prompts/Step-05A-Report.md), [Step-05B corrective worker report](../prompts/Step-05B-Report.md), and [Step-06 worker report](../prompts/Step-06-Report.md), -[Step-06A corrective worker report](../prompts/Step-06A-Report.md). +[Step-06A corrective worker report](../prompts/Step-06A-Report.md), and +[Step-07 worker report](../prompts/Step-07-Report.md). Handoffs are manual; acceptance remains the orchestrator's responsibility. diff --git a/docs/architecture.md b/docs/architecture.md index fdb8271..351a6d2 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -9,10 +9,11 @@ There is no web/server host, WASM host or backend process. ## Current milestone status -Steps 04/04A/04B and 05/05A/05B are accepted. Step-06's initial review found -preference-rejection and unavailable-readout gaps, now corrected by Step-06A. -Its worker verification is complete, pending manual review. Step-06 is not -accepted and Step-07 remains blocked. +Steps 04/04A/04B, 05/05A/05B and 06/06A are accepted. Step-07 adds bounded +session-owned capture, strict local archive readback and shared host controls. +The nine-project Release build, full test suite and native capture/save/restart/ +readback smoke are complete. Step-07 worker status remains pending manual +orchestrator review. ```mermaid flowchart TD @@ -47,10 +48,10 @@ All nine projects are in [AutoForge.slnx](../src/AutoForge.slnx): | [Core](../src/AutoForge.Core/AutoForge.Core.csproj) | `net10.0`; platform-neutral target/profile invariants and immutable dynamics configuration/status contracts | None | | [Diagnostics](../src/AutoForge.Diagnostics/AutoForge.Diagnostics.csproj) | `net10.0`; provider/session/transport/control contracts, strict synthetic protocol v1/v2 client, typed results and bounded trace | Core | | [Simulation](../src/AutoForge.Simulation/AutoForge.Simulation.csproj) | `net10.0`; validated static modules, fixed-step engine, isolated state, explicit provider factories and transports | Core, Diagnostics | -| [Application](../src/AutoForge.Application/AutoForge.Application.csproj) | `net10.0`; target/profile/diagnostic-session, dynamics-configuration, display-unit conversion and preference-port feature slices | Core, Diagnostics | +| [Application](../src/AutoForge.Application/AutoForge.Application.csproj) | `net10.0`; target/profile/diagnostic-session, dynamics-configuration, display-unit, live-dashboard and telemetry-recording/archive feature slices | Core, Diagnostics | | [Components](../src/AutoForge.Components/AutoForge.Components.csproj) | `net10.0` RCL; generic `StatusNotice` and numeric/bar gauge with accessible state and safe rendering | None | -| [UI](../src/AutoForge.UI/AutoForge.UI.csproj) | `net10.0` RCL; all application routes, navigation, layout and presentation, including shared live dashboard editor | Application, Components, Diagnostics | -| [Client](../src/AutoForge.Client/AutoForge.Client.csproj) | `net10.0-windows10.0.26100.0`; only MAUI Blazor Hybrid application executable and native preference adapter | Application, Simulation, UI | +| [UI](../src/AutoForge.UI/AutoForge.UI.csproj) | `net10.0` RCL; all application routes, navigation, layout and presentation, including shared dashboard and recording/archive inspection controls | Application, Components, Diagnostics | +| [Client](../src/AutoForge.Client/AutoForge.Client.csproj) | `net10.0-windows10.0.26100.0`; only MAUI Blazor Hybrid application executable, native preference adapter and app-local archive root | Application, Simulation, UI | | [UnitTests](../src/tests/AutoForge.UnitTests/AutoForge.UnitTests.csproj) | `net10.0`; Core/Application/contracts, protocol and reusable component tests | Application, Components, Core, Diagnostics, Simulation | | [IntegrationTests](../src/tests/AutoForge.IntegrationTests/AutoForge.IntegrationTests.csproj) | `net10.0`; real DI, fixtures, provider transport/session and rendered UI/project-graph tests | Application, Components, Core, Diagnostics, Simulation, UI | @@ -85,8 +86,8 @@ assembly, not the native Client assembly. | `/` | `Features/Foundation/Home.razor` | Describes the synthetic diagnostic workflow and distinguishes it from dynamics and physical operations | | `/execution-targets` | `Features/ExecutionTargets/SelectExecutionTarget/ExecutionTargetSelectionPage.razor` | Explicitly resolves registered provider metadata only; does not open a session | | `/vehicle-profiles` | `Features/Vehicles/Profiles/VehicleProfilesPage.razor` | Explicit schema-v1 import, exact revision selection, metadata/provenance inspection and read-only export | -| `/diagnostics` | `Features/Vehicles/Diagnostics/DiagnosticsPage.razor` | Explicit saved profile/revision/provider/kind selection, static-v1 session lifecycle, separate expected/probed/identified counts, retained partial probe services, identity-gated DTC/static signal operations, clear acknowledgement plus fresh-empty-readback verification, raw/decoded trace, and the shared configurable live dashboard | -| `/simulation` | `Features/Vehicles/Simulation/SimulationPage.razor` | Explicit profile/config/provider selection, JSON import/export, stopped-by-default dynamics session, lifecycle/step/pacing/scenario controls, source/unit/quality/model-time/config/run-aware telemetry over diagnostic protocol v2, and the same session-bound live dashboard | +| `/diagnostics` | `Features/Vehicles/Diagnostics/DiagnosticsPage.razor` | Explicit saved profile/revision/provider/kind selection, static-v1 session lifecycle, separate expected/probed/identified counts, retained partial probe services, identity-gated DTC/static signal operations, clear acknowledgement plus fresh-empty-readback verification, raw/decoded trace, shared live dashboard and session recording/archive inspection | +| `/simulation` | `Features/Vehicles/Simulation/SimulationPage.razor` | Explicit profile/config/provider selection, JSON import/export, stopped-by-default dynamics session, lifecycle/step/pacing/scenario controls, source/unit/quality/model-time/config/run-aware telemetry over diagnostic protocol v2, and the same dashboard and recording/archive controls | | Any unmatched route | `Features/Foundation/NotFoundPage.razor` via UI `Routes.razor` | Explicit not-found page and supported navigation | The generic [StatusNotice](../src/AutoForge.Components/StatusNotice.razor) @@ -117,6 +118,28 @@ does not stop acquisition. The owning session and feature scope cancel and drain the feed on close/replacement/disposal. See the [dashboard contract](live-dashboard.md) for quality, range, sample-time and usage details. +The shared recording panel consumes the Application +`TelemetryRecordingWorkspace`, not the live dashboard feed or its bounded +200-entry UI trace. Diagnostics publishes immutable observations after each +validated trace commit; a capture subscribes to that actual operation stream +for one explicit session, preserving request/response bytes and attaching only +the successful `read.signals` result from the same operation. Start excludes +prior history; Stop detaches and drains already-dispatched callbacks. The +capture is memory-only until explicit Stop and Save, bounded at 4,096 +observations, 16 MiB encoded observations, 1 MiB encoded header and 32 MiB +archive input/output. A rejected next observation freezes an explicitly +incomplete prefix. Close/reset stops capture but retains the old source context +for inspection/save. UI unmount does not own or stop capture. + +The Client persists only explicitly saved archives under its app-local +`recordings` directory. Application owns schema-v1 validation and file-storage +contracts; save writes and flushes a task-specific temporary file before +no-overwrite publication. Readback uses a new store instance and does not +rebind profiles or sessions. The format preserves capture elapsed time, +diagnostic logical ticks and model time as distinct values. This is local +archive persistence, not live disk streaming, crash durability, cryptographic +authenticity or playback. See the [archive-v1 guide](telemetry-archive-v1.md). + The feature-local target-selection view model adapts explicit input to the existing Application resolver. The same target resolver is populated from the diagnostic factories' descriptors, so `/execution-targets` shows the actual @@ -169,8 +192,10 @@ v2 dynamic telemetry is computed from an explicitly configured simplified model; it is not real sensor data or validated prediction. Virtual DTC clear mutates only selected in-memory module/session state and has no physical write path. No real vehicle, physical adapter, replay provider, programming, -calibration values, backups, AI, durable persistence or cloud service is -implemented. A `SUPPORTED` declaration, `VERIFIED` provenance label, physical +calibration values, backups, AI, live streaming, crash-durable capture or cloud +service is implemented. Saved recordings are local source-sensitive files and +must be treated as potentially sensitive data. A `SUPPORTED` declaration, +`VERIFIED` provenance label, physical metadata kind or calibration reference does not implement or authorize an operation. diff --git a/docs/build-and-test.md b/docs/build-and-test.md index fb558b8..c750239 100644 --- a/docs/build-and-test.md +++ b/docs/build-and-test.md @@ -393,7 +393,8 @@ draft-editor observations are reported separately from controlled storage failure/error tests; headless verification does not substitute for the actual Windows Client smoke. This section preserves the original Step-06 worker evidence; the subsequent Step-06A correction and current review status are -recorded below. Step-07 recording/replay remains unimplemented and blocked. +recorded below. At that time, Step-07 recording had not yet run; replay remains +outside Step-07 scope. The final sequential Release build completed all nine projects, including the Windows Client, with 0 warnings and 0 errors. The full suite passed 178 unit and @@ -435,7 +436,8 @@ The original Step-06 review found invalid-selection initialization/storage mutation and unavailable/wrong-type readout presentation gaps. Step-06A closes those gaps without changing the approved defaults, mappings, editor policy, model/source data or protocol. Step-06 remains **not accepted** pending manual -review; Step-07 remains blocked. +review; Step-07 had not yet run at that point. The final Step-07 evidence is +recorded below. Before the fix, an invalid proposal on a fresh service loaded the saved `metric|road` selection instead of leaving the untouched default; store reads @@ -479,3 +481,52 @@ removed after both Client processes and port 9361 were closed. No unrelated user preference/profile data was changed. See the [Step-06A corrective worker report](../prompts/Step-06A-Report.md) for matrix-level evidence, limitations and preservation review. + +## Step-07 bounded telemetry recording verification + +The final sequential Release build completed all nine solution projects, +including the Windows Client, with zero warnings and zero errors. The +MAUI XAML source-generation notice was informational. The full suite passed +179 unit and 124 integration tests (303 total; zero failed and zero skipped), +preserving the Step-06A baseline of 284 and adding 19 integration regressions. +The focused telemetry recording selection passed 19/19, including the +cross-scope capture-retention regression. Commands: + +- `dotnet build .\src\AutoForge.slnx --configuration Release --no-restore` +- `dotnet test .\src\AutoForge.slnx --configuration Release --no-build` +- `dotnet test .\src\tests\AutoForge.IntegrationTests\AutoForge.IntegrationTests.csproj --configuration Release --no-restore --filter "FullyQualifiedName~TelemetryRecordingIntegrationTests"` + +The rebuilt Windows Client was launched with isolated task-owned WebView2 +profiles and local DevTools ports. A static v1 session captured seven actual +operations (including positive and no-response discovery, DTC and signal reads), +closed with `SourceClosed`, saved locally, then was loaded after app restart. +The readback showed `autoforge.synthetic-diagnostics v1`, endpoint `0x10`, raw +request/response payloads, and two decoded source signals (`850 rpm` and +`12.6 V`). A dynamics v2 session was paused at step 8 / 0.8 model seconds. +With gauges hidden, two actual `read.signals` observations captured exact +configuration/run and model step/time context. The panel was unmounted by +navigating Home; the session close stopped the capture as `SourceClosed`, +and its unsaved snapshot remained available on the dynamics route for explicit +save. After another Client restart, both archives loaded and exposed raw bytes +and decoded signals; the static capture had two signals and the dynamics +capture had five. The displayed Metric/Road selection remained unchanged. + +That route-unmount smoke exposed a scoped-workspace lifetime bug; the workspace +was changed to application-wide singleton lifetime and +`CaptureWorkspace_IsSharedAcrossHostScopesAndRetainsClosedSourceCapture` +regresses it. Native post-fix evidence confirms the capture survives unmount +and source close. The UI also renders protocol versions and endpoint addresses +without Razor interpolation artifacts. Controlled tests, not the native smoke, +cover exact fixed limits, malformed archives, cancellation, collision and +filesystem failures. + +The `LOCALAPPDATA` override isolated neither MAUI's +`FileSystem.AppDataDirectory` nor display preferences on this Windows +environment. The application initially listed zero archives; the two +task-generated captures were written to its app-local `recordings` directory, +then those exact IDs were removed after closing the Client. No pre-existing +capture was overwritten or deleted. The WebView2 profiles were task-owned +temporary directories and were removed. Metric/Road preferences were observed +but not changed. See the [Step-07 worker report](../prompts/Step-07-Report.md) +for frozen-matrix evidence, self-review and preservation details. Worker +completion remains pending manual orchestrator review; no Step-08 work began. diff --git a/docs/telemetry-archive-v1.md b/docs/telemetry-archive-v1.md new file mode 100644 index 0000000..a11808f --- /dev/null +++ b/docs/telemetry-archive-v1.md @@ -0,0 +1,215 @@ +# Telemetry archive schema v1 and recording + +## Scope and trust boundary + +Recording captures validated diagnostic operations from one explicitly opened +synthetic session. It does not read the bounded 200-entry UI trace, poll a +dashboard, issue commands, step dynamics or decode guessed payloads. Captures +are held in memory until the user stops and explicitly saves them. The saved +file is local and source-sensitive; it is not a trusted statement about a real +vehicle, manufacturer data, current vehicle state or cryptographic authenticity. +Playback, live disk streaming, unlimited retention and crash recovery are not +implemented. + +The shared panel is available in both `/diagnostics` (synthetic protocol v1) +and `/simulation` (synthetic protocol v2). Hiding or unmounting a dashboard or +recording panel does not own the capture or cause additional reads. Display-unit +changes affect presentation only; archives preserve source units and source +values. + +## Capture lifecycle and clocks + +Start attaches to the explicit session's actual-operation observation port. +Earlier trace history is excluded; Start and Stop do not operate the source. +Each observation is published after its validated trace entry is committed, +with that operation's immutable raw trace fields and, only for a successful +`read.signals`, the decoded snapshot from that same response. Exchange ordering +defines capture sequence; model time is not used to sort or group operations. + +Stop establishes a cutover by detaching the observer through the session's +serialized observation dispatcher. Callbacks already in dispatch drain before +Stop freezes the result; operations dispatched after detachment are excluded. +Repeated Start on the active owner is idempotent. A second owner for that +session is rejected. Session close/reset stops and detaches the old capture but +retains its source identity and samples for inspection and saving. A new source +does not inherit old samples. Unsaved capture replacement requires explicit +Save or Discard. + +The archive keeps three independent time values: + +- `captureElapsedTicks`: nonnegative, nondecreasing `TimeSpan` ticks since + Start, from `TimeProvider`. +- `startLogicalTicks` / `endLogicalTicks`: diagnostic protocol logical ticks. +- Per-sample `logicalTimeTicks`, and when present `modelStepIndex` / + `modelTimeSeconds`: the original source/model context. A paused model may + repeat model time while capture elapsed time advances. + +## Fixed limits and partial captures + +All sizes use compact UTF-8 JSON encoding and binary MiB (1,048,576 bytes). + +| Limit | Maximum | +|---|---:| +| Captured operations | 4,096 | +| Sum of encoded observation objects | 16,777,216 bytes | +| Encoded header object | 1,048,576 bytes | +| Complete archive input/output | 33,554,432 bytes | +| JSON parser depth | 128 | + +At a count or observation-byte limit, the next operation is not retained; the +valid prefix is frozen with `state: "incomplete"` and +`stopReason: "limitExceeded"`. The diagnostic source operation still returns +its original result. No older record is silently discarded and no unknown +later-loss count is inferred. The UI offers a distinctly labeled **Save partial +capture** action; ordinary Save is rejected for incomplete data. Internal +capture errors use an explicit error state rather than a healthy completion. +Oversized headers and archive inputs fail validation before publishing state. + +## JSON schema + +The root object has exactly these required camelCase properties: + +```json +{ + "schemaVersion": 1, + "header": {}, + "observations": [], + "completion": {} +} +``` + +Unknown and duplicate schema-object properties are rejected. Nullable metadata +is explicit `null`; it is not inferred from a current profile, session or +configuration. + +`header` contains exactly: + +```text +captureId +sessionIdentifier +profileIdentifier +profileRevision +vehicleIdentifier +providerIdentifier +targetKind +protocolName +protocolVersion +dynamicsConfigurationIdentifier +dynamicsRunIdentifier +sourceEndpoints +startedAtUtc +``` + +`captureId` is a lowercase opaque GUID in `N` format and is the only filename +input. `targetKind` uses the exact camelCase enum token. `protocolName` is +`autoforge.synthetic-diagnostics`; `protocolVersion` is 1 or 2. Static v1 has +null dynamics identifiers. Dynamic v2 carries both the original configuration +and run identifiers. `sourceEndpoints` is an array of `{ "moduleIdentifier", +"address" }` identities. UTC timestamps use the complete round-trip `"O"` +format with an explicit zero offset. + +Every `observations` entry contains exactly: + +```text +sequence +captureElapsedTicks +moduleIdentifier +address +correlationIdentifier +service +startLogicalTicks +endLogicalTicks +outcome +decodedSummary +error +requestPayloadBase64 +responsePayloadBase64 +signalSnapshot +``` + +`sequence` starts at 1 and is contiguous. Raw payloads are canonical base64; +the nullable response is null only when no response bytes were received. +Outcomes are the defined diagnostic outcome tokens. Positive and negative +responses, and recorded protocol errors, require response bytes; timeout, +no-response and cancellation outcomes prohibit them. The raw synthetic request +and any well-formed positive/negative response are checked against the recorded +session, profile, configuration, correlation, endpoint, service, protocol +version and outcome. + +`signalSnapshot` is null except for a successful `read.signals`. It contains: + +```text +moduleIdentifier +signals +modelStepIndex +modelTimeSeconds +modelConfigurationIdentifier +modelRunIdentifier +``` + +Each `signals` item contains: + +```text +signalIdentifier +moduleIdentifier +value +unit +quality +logicalTimeTicks +origin +modelStepIndex +modelTimeSeconds +modelConfigurationIdentifier +modelRunIdentifier +``` + +`value` remains a JSON value with its original JSON kind and data; arbitrary +properties inside that value are not interpreted as archive schema. Unit, +quality, origin, diagnostic time and optional model/run context are source +metadata, not display-unit projections. + +`completion` contains exactly: + +```text +stoppedAtUtc +stopReason +state +observationCount +observationBytes +error +``` + +`observationCount` and `observationBytes` must match the validated list and its +actual compact encoding. A stopped healthy capture uses `state: "complete"` +and stop reason `"user"` or `"sourceClosed"`. Limit exhaustion is +`"incomplete"` / `"limitExceeded"`. A capture implementation error is +`"error"` / `"observationFailure"` with a visible error message. + +## Local persistence and failure handling + +The Client composes `FileTelemetryArchiveStore` under +`FileSystem.AppDataDirectory/recordings`. Save is available only after Stop. +The store validates and serializes the whole capture, writes a capture-specific +temporary file, flushes it to disk, closes it, then publishes using a +no-overwrite move. A collision, cancellation, or write failure cannot replace +an existing archive. Temporary-file cleanup failures are surfaced as typed +write failures with an explicit instruction to inspect the named temporary +file; they are not silently hidden. + +List and Load enforce the 32 MiB input bound and validate the full schema. +Corrupt matching files, unsupported versions, malformed/truncated JSON, +unknown or duplicate schema properties, bad base64, inconsistent counts, +times, outcomes or source context are visible typed failures. Invalid data does +not replace an existing inspection. Valid incomplete archives remain +incomplete on readback. Readback proves file/schema consistency only; it does +not validate authenticity or source truth. + +## Verification + +The focused `TelemetryRecordingIntegrationTests` exercise real v1/v2 sessions, +more than 200 operations, all observed outcomes, controlled capture time, +ownership/Stop draining, session reset, exact count/observation/header/archive +boundaries, filesystem round-trip, collision/cancellation/I/O failures, +corrupt-file rejection and rendered controls in both routes. The complete +Release test totals, native-build status and manual-review limitations are +recorded in the [Step-07 worker report](../prompts/Step-07-Report.md). diff --git a/prompts/ROADMAP.md b/prompts/ROADMAP.md index a802a11..bf660dc 100644 --- a/prompts/ROADMAP.md +++ b/prompts/ROADMAP.md @@ -3,14 +3,14 @@ ## Status and authority - Initialized: 2026-10-28. -- Current phase: corrected display units accepted; bounded telemetry recording/archive next. -- Active assignment: [Step-07](Step-07.md), ready for manual worker execution. +- Current phase: Step-07 reviewed; source-fidelity, validation, lifetime and visible-I/O correction required. +- Active assignment: [Step-07A](Step-07A.md), ready for manual worker execution. - Last accepted milestone: Step-06 with Step-06A, accepted 2026-10-30. - Last accepted correction: Step-06A; all Step-06 findings closed. -- Outstanding corrections: none. +- Outstanding corrections: Step-07 R-01 through R-04 against the existing capture/archive contract. - Step-05 status: ACCEPTED after Step-05A/Step-05B, 2026-10-29. - Step-06 status: ACCEPTED after Step-06A, 2026-10-30. -- Step-07 status: READY FOR WORKER; bounded capture and archive readback, not playback. +- Step-07 status: REQUIRES CORRECTION / NOT ACCEPTED, reviewed 2026-10-30. - Step-08 status: recorded telemetry replay; BLOCKED / NOT ASSIGNED until Step-07 acceptance. - Current state and handoff: [STATE.md](STATE.md). - Authority: the master charter, repository/handoff amendment, and the owner's @@ -375,8 +375,9 @@ Step-05 with Step-05A/05B is accepted: the configured static/dynamic workflow, single session owner, independent range/quality, safe gauges, decisive tests and native evidence have been reviewed. Corrected Step-06/06A is accepted: unit defaults/conversions, rejected selections, unavailable readouts and raw/source -preservation are closed on inspected evidence. Step-07 recording/archive is the -only active assignment. Replay is the following Step-08, not bundled into capture. +preservation are closed on inspected evidence. Step-07 recording/archive exists +but is unaccepted pending Step-07A's four consolidated original-scope findings. +Step-07A is the only active assignment; Step-08 replay remains blocked. Dependencies indicate acceptance prerequisites, not permission for automatic handoff. Later assignments refine these scopes using actual implementation evidence; they must not silently discard required capabilities. @@ -398,8 +399,9 @@ evidence; they must not silently discard required capabilities. | 05B | Independent range status and decisive dashboard tests | Remaining 05A R-03/testing contract | ACCEPTED 2026-10-29 | Frozen five-case/five-criterion contract satisfied; reported 134 unit/91 integration passes, clean Release/native recheck and actual pre-fix failure | | 06 | Imperial-default metric/imperial display units | 05 and corrections accepted; owner request 2026-10-29 | ACCEPTED 2026-10-30 AFTER 06A | Shared persisted Imperial/Road default, exact conversions, source/canonical invariants and corrected rejection/unavailable readouts inspected | | 06A | Preference rejection and unavailable display readouts | 06 review R-01/R-02 | ACCEPTED 2026-10-30 | Frozen seven-case/five-criterion contract satisfied; reported 179 unit/105 integration passes, clean Release/native evidence and honest binding-event versus browser coverage | -| 07 | Bounded telemetry recording and archive readback | 06 and corrections accepted | READY FOR WORKER | Actual raw/decoded observations beyond the 200-entry UI trace, one capture owner, explicit limits, source-faithful schema-v1 save/load and typed loss/I/O outcomes | -| 08 | Recorded telemetry replay | 07 accepted | BLOCKED / NOT ASSIGNED | Play/pause/stop/restart/seek/navigation/speed feed shared presentation from recorded data, with explicit Replay identity and no live reads or physics rerun | +| 07 | Bounded telemetry recording and archive readback | 06 and corrections accepted | REQUIRES CORRECTION / NOT ACCEPTED | Real capture/limits/storage/native paths exist; valid-source archive rejection, invalid-data boundary, released-capture retention and hidden I/O errors remain | +| 07A | Source-faithful archives, bounded lifetime and visible storage failures | 07 review R-01 through R-04 | READY FOR WORKER | Original C-04..C-11: valid traces round-trip, malformed archives reject with typed errors, discarded owners release, I/O failures remain visible | +| 08 | Recorded telemetry replay | 07 and corrections accepted | BLOCKED / NOT ASSIGNED | Play/pause/stop/restart/seek/navigation/speed feed shared presentation from recorded data, with explicit Replay identity and no live reads or physics rerun | | 09 | Calibration management and simulated programming | 08 | PLANNED | Versioned definitions/diffs, verified baseline and backup, approved simulated write, readback/unrelated-data checks, audit and supported restore; no physical writes | | 10 | Local AI, knowledge, and validated runbooks | 09 | PLANNED | Replaceable local inference, applicable knowledge retrieval, structured logical runbook, independent validation/approval and simulation-only execution | | 11 | Comparative evaluation and complete synthetic demonstration | 10 | PLANNED | Complete demonstration below plus deterministic fault/regression matrix and independent verification of intended and unintended changes | @@ -792,20 +794,50 @@ history, not repeated redesign without evidence. - Prepared [Step-07](Step-07.md), splitting bounded recording/archive from subsequent Step-08 playback under the existing prospective sizing policy. Only unassigned future envelopes/dependencies moved; history is preserved. +- Reviewed returned Step-07 report, actual observation tap/capture/workspace/ + codec/filesystem/UI paths, new tests, docs and Release artifacts. Worker reports + 179 unit + 124 integration passes (303 total, zero failed/skipped), clean full + Release build and real native static/dynamic save/restart/readback/unmount smoke. + The orchestrator ran no application checks. +- Positive capture ordering, beyond-200 retention, exact limit tests, source + context and native unsaved cross-route retention are supported. Withheld + acceptance for four consolidated original-scope findings in + [Step-07A](Step-07A.md); playback remains deferred, not a corrective requirement. ### Remaining -- Worker execution of Step-07, then one consolidated review against its frozen - capture/archive/lifetime/limit matrix and shared quality gate. Correct genuine - unmet requirements as Step-07A before preparing playback. -- Step-08 replay is blocked and not assigned. Recording/archive is assigned work, - not implemented functionality; display units and earlier milestones are accepted. +- Worker execution of Step-07A, then one consolidated review against its focused + matrix, original Step-07 contract and shared quality gate before playback. +- Step-08 replay is blocked and not assigned. Recording/archive exists but remains + unaccepted; display units and earlier milestones remain accepted. - Profile/module metadata, synthetic virtual-module communication and deterministic dynamics/v2 and corrected dashboard are accepted; later features remain planned. Preserve the complete sequence/safety gates. ### Known blockers and uncertainties +Step-07 has four open findings against its original contract: + +- R-01: archive validation requires response bytes for every ProtocolError, even + though an actual empty reply yields that outcome with null source trace bytes. + Ordinal archive identity checks also reject case variants accepted by the + existing diagnostic client. Valid captured observations cannot always save. +- R-02: a positive signal read with null signalSnapshot reaches raw-response + validation before its association guard and can throw NullReferenceException. + Matching raw/decoded v2 edits can bypass existing unit/type/known-ID/duplicate/ + nonnegative-model-time rules rather than receive typed invalid-archive rejection. +- R-03: each capture remains in the session lifetime-resource list after stop/ + discard/replacement, retaining old observation buffers until the source closes. + The controlled Stop test also releases its blocking observer only after + assertions, so a failed assertion can deadlock teardown instead of releasing it. +- R-04: catalogue listing treats an existing file used as its root as a healthy + empty directory. The panel always refreshes after SaveAsync, including after + the workspace reports failure, clearing that error with a successful list status. + +These are source-path findings, not orchestrator-executed reproductions. Step-07A +must prove the applicable pre-fix failures and preserve all supported recording/ +limit/native behavior. No archive-format expansion or playback is requested. + No blocking Step-06 deficiency remains. Its two findings below are historical and closed by accepted Step-06A: diff --git a/prompts/STATE.md b/prompts/STATE.md index 8458933..2723a2f 100644 --- a/prompts/STATE.md +++ b/prompts/STATE.md @@ -5,14 +5,14 @@ | Field | Value | |---|---| | Updated | 2026-10-30 | -| Phase | Corrected display units accepted; bounded telemetry recording/archive next | -| Active step | Step-07 - Bounded telemetry recording and archive readback | -| Assignment | [Step-07.md](Step-07.md) | +| Phase | Step-07 reviewed; archive/lifetime/visible-I/O correction required | +| Active step | Step-07A - Source-faithful archives and bounded capture cleanup | +| Assignment | [Step-07A.md](Step-07A.md) | | Assignment status | READY FOR WORKER / AWAITING MANUAL HANDOFF | -| Expected worker report | `prompts/Step-07-Report.md` - not yet created | +| Expected worker report | `prompts/Step-07A-Report.md` - not yet created | | Last accepted correction | Step-06A - accepted 2026-10-30 | | Last accepted major milestone | Step-06 with Step-06A - accepted 2026-10-30 | -| Outstanding corrections | None | +| Outstanding corrections | Step-07 R-01 through R-04 against original frozen criteria | | Step-02 status | ACCEPTED after Step-02A | | Step-03 status | ACCEPTED after Step-03A/Step-03B | | Step-04 status | ACCEPTED after Step-04A/Step-04B | @@ -20,10 +20,10 @@ | Step-05 status | ACCEPTED after Step-05A/Step-05B | | Step-05A review | All original corrective criteria closed with Step-05B | | Step-06 status | ACCEPTED after Step-06A | -| Step-07 status | READY FOR WORKER; bounded capture, explicit save and strict readback only | +| Step-07 status | REQUIRES CORRECTION / NOT ACCEPTED | | Step-08 status | Recorded telemetry replay; BLOCKED until Step-07 acceptance | -| Worker execution | Step-06A returned and accepted; Step-07 not invoked | -| Immediate next action | User manually directs the worker to execute Step-07 and shared quality gate only | +| Worker execution | Step-07 returned; Step-07A not invoked | +| Immediate next action | User manually directs the worker to execute Step-07A with original Step-07 and shared quality gate | | Next orchestrator action | After manual return, inspect the assignment, report, implementation, tests, Git changes, documentation and recorded command evidence | ## Repository baseline at initialization @@ -879,6 +879,54 @@ allowed. Recording remains in memory until explicit save after Stop; no crash-durable/live-streaming or unlimited-duration claim is made. The next review must not demand the deferred Step-08 playback controls. +## Step-07 review and required correction + +Decision: **REQUIRES CORRECTION / NOT ACCEPTED**, 2026-10-30. +Reviewed [Step-07](Step-07.md), its [report](Step-07-Report.md), all observation/ +capture/workspace/codec/filesystem/UI changes, actual new integration tests, +related docs/README, source lifetime registration, graph and Release artifacts. + +Positive evidence includes real observations beyond the UI buffer, actual +per-operation raw/decoded association, separate capture/diagnostic/model time, +exact count/header/observation/file limits, explicit memory-only/partial states, +real file readback and native retained capture after route unmount. +Worker reports clean complete nine-project Release build and 179 unit + +124 integration passes (303 total, zero failed/skipped), preserving all 284 +prior cases and adding 19 integration cases. + +| Finding | Evidence | Original contract | +|---|---|---| +| R-01 - valid source observations rejected | Codec requires bytes for ProtocolError even when the real source recorded null for an empty reply. Codec uses Ordinal trace/snapshot/envelope identity comparisons where the source client accepts case-insensitive identities; a valid uppercase endpoint module can therefore fail save. | C-02/C-04/C-08, AC-01/AC-03 | +| R-02 - invalid archive boundary incomplete | Positive read.signals with signalSnapshot null calls ValidateSignalResponse before the required association check and dereferences null. Consistent edits to raw/decoded v2 values are not checked against known IDs/unit/type rules; duplicate IDs and negative model time also lack equivalent guards. | C-09, strict typed/context validation, AC-03 | +| R-03 - capture retention and failure-safe teardown | SessionTelemetryCapture.Start registers each capture with the session, but stop/discard/replacement never unregister it. DiagnosticSession retains those objects/buffers until source disposal, defeating bounded in-memory history across repeated captures. The blocking Stop test lacks finally release before observer disposal. | C-05/C-06/C-07, testing cleanup requirement, AC-02/AC-05 | +| R-04 - storage failure visibility | ListAsync returns an empty list for an existing file used as root. The panel unconditionally RefreshAsync after workspace SaveAsync catches a failure; refresh clears Error and replaces failure status with a healthy catalogue message. | C-10/C-11, AC-03/AC-04 | + +| Original criterion | Decision | Evidence/gap | +|---|---|---| +| AC-01 | PARTIAL / NOT ACCEPTED | Actual observation tap/order/time/raw data is supported; valid error/case-variant captures do not all round-trip | +| AC-02 | PARTIAL / NOT ACCEPTED | Exact limits and source-close retention are supported; repeated-capture resource release and failed-assertion cleanup are not | +| AC-03 | NOT ACCEPTED | Real atomic save/readback works on tested positive paths; typed null handling/v2 semantic consistency/catalogue failure classification remain deficient | +| AC-04 | PARTIAL / NOT ACCEPTED | Native capture/save/restart/load and cross-scope retention supported; failed save errors can disappear in the actual panel flow | +| AC-05 | WORKER EXECUTION EVIDENCE REVIEWED | Reported 303 passes/clean Release/native smoke are positive preservation evidence, not proof of the untested negative paths | +| AC-06 | PARTIAL / NOT ACCEPTED | Docs/report/self-review exist; strict validation/bounded lifetime/visible I/O claims require the corrective evidence | +| AC-07 | PRESERVATION SUPPORTED | Original prompts/history/shared gate, nine projects/references and protected files preserved; no playback, package or later-step changes reported | + +Native evidence separately reports static seven-operation and dynamic two-read +archives, source close/unmount retention, app restart/load/inspection and unchanged +Metric preference. The worker removed only its two named archive IDs and exact +temporary WebView profiles; its LOCALAPPDATA override did not isolate MAUI's +recordings root, and that limitation is explicitly disclosed. + +The worker also reports an initial NETSDK1112 missing Windows runtime pack: +project-scoped Client restore for win-x64 resolved that genuine missing dependency, +then the required --no-restore build passed. No workload/system repair/update or +manifest/project/package change was reported or authorized by this review. + +All findings above are source/test-inspection evidence. The orchestrator executed +no application build/test, native launch or failing reproduction. Preserve the +returned report unchanged. [Step-07A](Step-07A.md) consolidates the four existing +requirements; Step-08 remains blocked and no replay assignment is created. + ## Prerequisites, limitations, and known issues - Step-01A worker evidence establishes portable and native Windows compatibility @@ -905,23 +953,24 @@ The next review must not demand the deferred Step-08 playback controls. Step-04B. Step-05's original and follow-up findings are closed. Preserve the 190-/ 202-/207-case reports and original numerical/native evidence distinctly. - Profile metadata/UI, synthetic diagnostics, deterministic dynamics/v2 and the - corrected dashboard/display units are accepted. Recording/archive, replay, calibration values, - persistence, AI and physical hardware operations remain unimplemented. + corrected dashboard/display units are accepted. Recording/archive exists but + is unaccepted. Replay, calibration values, AI and physical hardware operations + remain unimplemented. - No application build or test has been executed by the orchestrator. ## Review and progression gate -On manual return, evaluate Step-07 and its frozen capture/archive contract/shared gate using the +On manual return, evaluate Step-07A and the original Step-07 capture/archive contract/shared gate using the assignment, worker report, actual code/tests, dependency graph, Git changes, README/docs, and recorded build/test evidence. Do not accept solely on a success claim; do not claim independent runtime verification. -- Inspect actual observations beyond the bounded trace, immutable source/decoded - snapshots, one capture owner, explicit loss/limits, atomic archive save/strict - readback and native evidence. Do not add deferred playback/streaming requirements. -- If accepted: accept Step-07, update roadmap/state, prepare Step-08 replay +- Inspect valid-source round trips, typed/strict archive rejection, bounded + lifetime release/finally cleanup and actual panel/catalogue failure visibility. + Preserve prior positive capture/native evidence; no new playback requirements. +- If accepted: close Step-07A, accept corrected Step-07, update roadmap/state, prepare Step-08 replay and stop for manual handoff. -- If deficient: issue narrowly scoped Step-07A only for a material unmet contract/ +- If deficient: issue narrowly scoped Step-07B only for a material unmet contract/ regression, then stop. Planned new features are not corrections. - If blocked: retain the active step, document the prerequisite and required worker evidence; do not advance or mark unexecuted checks as successful. @@ -984,12 +1033,15 @@ claim; do not claim independent runtime verification. | 2026-10-30 | Corrected Step-06 ACCEPTED | Original and 06A criteria closed; Imperial default/metric options/source invariants preserved; no 06B | | 2026-10-30 | Telemetry envelope split prospectively | Step-07 bounded recording/archive, Step-08 replay; former unassigned 08-21 become 09-22; no completed history renumbered | | 2026-10-30 | Step-07 prepared | Single capture-owner outcome, strict source-faithful archive/readback and explicit limits; no playback clock, manual handoff pending | +| 2026-10-30 | Step-07 returned and reviewed | Real observer/capture/archive/UI implementation and reported 303-case/clean Release/native save/restart/readback/unmount evidence inspected | +| 2026-10-30 | Step-07 requires correction | Four original-scope findings: valid-source round trips, typed/strict archive semantics, released-capture retention/test cleanup, and catalogue/panel I/O visibility | +| 2026-10-30 | Step-07A prepared | Consolidated corrective matrix with real pre-fix/negative/lifecycle/panel evidence; prior recording/unit/source behavior preserved and replay blocked | ## Manual handoff instruction -Provide [Step-07.md](Step-07.md) and the shared +Provide [Step-07A.md](Step-07A.md), original [Step-07.md](Step-07.md) and the shared [worker gate](WORKER-QUALITY-GATE.md) to the separate worker and request execution -of that assignment only. The worker must produce `prompts/Step-07-Report.md` +of the correction only. The worker must produce `prompts/Step-07A-Report.md` and stop for review. Do not begin Step-08 replay. Return manually to the orchestrator for review. Reports, including final chat reports, must follow the single plain triple-backtick copy-window requirement. diff --git a/prompts/Step-07-Report.md b/prompts/Step-07-Report.md new file mode 100644 index 0000000..c5f74a0 --- /dev/null +++ b/prompts/Step-07-Report.md @@ -0,0 +1,84 @@ +``` +# Step-07 - Bounded telemetry recording and archive readback + +Status: COMPLETE — worker verification is complete; manual orchestrator review remains pending. + +## Delivered + +- Added immutable provider-neutral operation observations at validated protocol trace commitment. Captures retain the exact trace identity, raw request/response bytes, actual outcome/error and only the positive `read.signals` result's own decoded snapshot. +- Added an application-owned session capture, singleton recording workspace shared across host route scopes, fixed limits, schema-v1 codec/validation and real atomic local file store. +- Added shared recording/save/partial-save/discard/load/source/raw/decoded inspection UI to both static diagnostics and dynamics. The Client composes app-local storage. +- Updated README, documentation index, architecture, build/test guide and `docs/telemetry-archive-v1.md`. +- Corrected Razor interpolation so the inspector renders the actual protocol version and endpoint address. +- Fixed the route-unmount lifetime gap found during native smoke: the workspace now outlives feature-route scopes and retains a source-closed capture until explicit save/discard. + +## Frozen contract matrix + +| ID | Result and named executed evidence | +|---|---| +| C-01 | Pass. `CaptureWindow_ExcludesPriorTraceAndStartStopNeverOperateTheSource` verifies pre-Start discovery history is excluded, repeated Start reuses the capture, and empty Stop does not operate the source. | +| C-02 | Pass. `CaptureWindow_Retains225ActualOperationsBeyondTheTraceBufferInExactOrder` captures 225 actual reads once/in order with matching correlations and raw bytes while the UI trace remains capped at 200 and reports 25 dropped. | +| C-03 | Pass. `PausedDynamicsCapture_SeparatesCaptureDiagnosticAndModelTimeFromDisplayChanges` verifies controlled capture ticks, diagnostic logical ticks, paused model step/time, exact source units and display-only changes. Native v2 smoke captured actual reads while paused at step 8 / 0.8 s with gauges hidden; no dashboard monitoring was started. | +| C-04 | Pass. `CaptureRecordsActualPositiveNegativeTimeoutNoResponseCancellationAndMalformedReplyBytes` verifies positive/negative/timeout/no-response/cancelled/protocol-error results, actual malformed reply bytes, no invented failed-operation response/signal snapshots, and unchanged session results. | +| C-05 | Pass. `CaptureOwnership_RejectsCompetingOwnerAndStopDrainsAcceptedCallbackBeforeReturning` checks unique per-session ownership, drainable Stop cutover and rejection without mutation during drain. | +| C-06 | Pass. `ResetKeepsOldUnsavedCaptureInspectableAndRequiresExplicitDiscardBeforeNewSource` and `CaptureWorkspace_IsSharedAcrossHostScopesAndRetainsClosedSourceCapture` verify old-source retention, explicit discard policy and cross-scope visibility after close. Native route-unmount smoke confirmed the stopped capture remained saveable after navigating Home and returning. | +| C-07 | Pass. `CaptureLimits_RetainExactCountAndBytePrefixesAndRejectHeaderBeforeSubscription`, `CaptureCountLimit_Accepts4096OperationsAndMarksTheNextOperationIncomplete`, `ArchiveInputLimit_AcceptsExactly32MiBAndRejectsOneByteMore`, `ArchiveHeaderLimit_AcceptsExactlyOneMiBAndRejectsOneByteMore`, and `ArchiveObservationLimit_AcceptsExactly16MiBAndRejectsOneByteMore` cover fixed limits, exact boundaries, valid-prefix retention and visible incomplete/error states. | +| C-08 | Pass. `FileArchive_RoundTripsExactSourceContextAndNeverOverwritesOrPublishesPartialFiles` uses actual temporary files and a new store instance; it compares raw bytes, JSON value kinds/data, source/unit/quality/time/context and completion counts. | +| C-09 | Pass. `InvalidArchives_AreRejectedAndDoNotReplacePriorInspection` rejects malformed, truncated, unsupported, duplicate, unknown and incoherent schema data without replacing the prior loaded inspection. | +| C-10 | Pass. `FileArchive_CancellationAndFilesystemFailureAreTypedAndLeaveNoPublishedArchive` and `PendingSave_RejectsConflictingActionsAndOnlyMarksTheBoundCaptureSaved` verify collision/cancellation/I/O/stale completion policies and no published partial archive. | +| C-11 | Pass. `BothHostRoutes_RenderSharedRecordingSaveAndSourceFaithfulInspection` covers real provider/DI and rendered static/dynamics hosts. Native smoke separately recorded both v1 and v2, saved, closed/reopened, loaded and inspected raw/decoded data. | +| C-12 | Pass. Final Release build covered all nine projects; the full 303-test suite passed; native smoke covered actual Client/static/dynamics/readback. Existing source/model/display-unit safety regressions remain in the full suite. | + +## Acceptance criteria + +| ID | Result and evidence | +|---|---| +| AC-01 | Pass. C-01 through C-04 evidence above, including the 225-operation threshold, raw/decoded binding and paused v2 context. | +| AC-02 | Pass. C-05 through C-07 evidence above, including exact limits and session-close/reset retention. | +| AC-03 | Pass. C-08 through C-10 evidence above, including real filesystem round-trip, strict rejection, cancellation, collision and cleanup behavior. | +| AC-04 | Pass. C-11 plus post-fix native route-unmount, close, save and restart/readback evidence below. | +| AC-05 | Pass. Final build and full suite passed; native static and dynamics captures both reopened and inspected. | +| AC-06 | Pass. Schema/capture/storage documentation and README were updated. Post-green source-path self-review and verification evidence are below. | +| AC-07 | Pass. Only the assigned implementation/docs and `prompts/Step-07-Report.md` changed; protected assignments/roadmap/state/gate remain untouched. No Step-08, staging, commit or push occurred. Manual review is the stopping point. | + +## Archive shape, limits and lifecycle + +Schema v1 root fields are exactly `schemaVersion`, `header`, `observations` and `completion` in camelCase. The header records the immutable source/session/profile/revision/vehicle/provider/target identity, actual protocol name/version, optional dynamics configuration/run, endpoint identities and explicit-offset UTC start. Observations have contiguous sequence, nondecreasing capture elapsed ticks, original diagnostic logical ticks, trace outcome/error/service/correlation, reversible base64 raw payloads and the exact operation-bound decoded signal snapshot or null. Completion records stop UTC/reason/state/count/encoded observation bytes/error. + +Fixed limits: 4,096 observations; 16,777,216 encoded observation bytes; 1,048,576 encoded header bytes; 33,554,432 archive bytes; JSON depth 128. A rejected next observation stops capture with an explicit incomplete/error reason and retains only the valid prefix. Complete and partial saves are distinct. Capture elapsed time, protocol logical ticks and model step/time remain separate. Capture is memory-only until explicit Stop and Save; it is not crash-durable streaming, playback, authenticity or current-vehicle truth. + +The file store serializes/validates before writing, creates a unique temporary file, flushes/closes it, then moves without overwrite. Cancellation/collision/filesystem/cleanup failures are typed and visible; incomplete temporary files are not catalogued. Listing rejects corrupt archives rather than silently skipping them. + +## Commands and outcomes + +- `dotnet test .\src\tests\AutoForge.IntegrationTests\AutoForge.IntegrationTests.csproj --configuration Release --filter "FullyQualifiedName~CaptureWorkspace_IsSharedAcrossHostScopesAndRetainsClosedSourceCapture"` — exit 0; 1 passed. +- `dotnet test .\src\tests\AutoForge.IntegrationTests\AutoForge.IntegrationTests.csproj --configuration Release --no-restore --filter "FullyQualifiedName~TelemetryRecordingIntegrationTests"` — exit 0; 19 passed, 0 failed/skipped. +- `dotnet build .\src\AutoForge.slnx --configuration Release --no-restore` — exit 0; all nine projects built, 0 warnings, 0 errors. The MAUI XAML source-generation notice was informational. +- `dotnet test .\src\AutoForge.slnx --configuration Release --no-build` — exit 0; 179 unit + 124 integration = 303 passed, 0 failed/skipped. This preserves the 284-case Step-06A baseline and adds 19 integration cases. +- An initial build exposed the genuinely missing `Microsoft.NETCore.App.Runtime.win-x64` pack (`NETSDK1112`). The project-scoped `dotnet restore .\src\AutoForge.Client\AutoForge.Client.csproj --runtime win-x64` succeeded; no workload/system repair/install/update was performed. The required final `--no-restore` build passed. + +Release build project count: 9/9 — `AutoForge.Core`, `AutoForge.Diagnostics`, `AutoForge.Components`, `AutoForge.Simulation`, `AutoForge.Application`, `AutoForge.UI`, `AutoForge.UnitTests`, `AutoForge.IntegrationTests` and `AutoForge.Client`. + +## Native smoke versus controlled coverage + +The rebuilt Windows Client was launched with temporary task-owned WebView2 profiles and local DevTools ports. Static protocol v1 capture `9cfd944b712e4bc5b4add9a9f6074d73` retained 7 actual operations / 10,773 encoded observation bytes, including discovery outcomes and actual DTC/signal reads. Closing the source stopped it as `SourceClosed / Complete`; explicit save succeeded. After app restart, the archive loaded with protocol v1, endpoint `0x10`, raw request/response payloads and decoded `850 rpm` / `12.6 V` source signals. + +Dynamics protocol v2 capture `93ebdaa9a8cc4407ba270d15c5294891` retained 2 actual `read.signals` observations / 12,479 encoded observation bytes. The source was paused at model step 8 / 0.8 s; the captured signal snapshot retained step/time, configuration fingerprint and run `dynamics-run-000001`. Gauges were hidden. Navigating Home unmounted the recording panel and closed the source; the application-wide workspace retained the complete, unsaved capture on return for explicit save. After a second app restart, the dynamics archive loaded with protocol v2, endpoint `0x20`, raw request/response payloads and five decoded source signals. Both archives loaded without a live session. Metric/Road display preferences remained unchanged throughout. + +The first native route-unmount attempt, before the workspace lifetime correction, lost the in-memory capture. This was fixed by application-wide workspace registration, covered by the named cross-scope regression, and retested natively after the final build. Razor protocol/address interpolation was also corrected after its literal `@...` output was noticed during native review. + +The native smoke did not inject limit, malformed-file, collision or platform I/O fault vectors; those are controlled integration tests listed above. The `LOCALAPPDATA` environment override did not isolate MAUI `FileSystem.AppDataDirectory` on this Windows environment. The app initially listed zero archives; only the two task-generated archive IDs above were written, then individually removed after the Client closed. No archive was overwritten or unrelated capture removed. Task-owned WebView2 temporary profiles were removed. The existing Metric/Road preference was read but not modified. + +## Post-green source-path self-review + +- The protocol client appends the existing bounded trace first, then publishes an immutable observation in operation order. It snapshots subscribers before dispatch; observer failures are visible and do not rewrite the diagnostic result. Only the same validated positive `read.signals` result carries decoded signals. +- Session lifetime registration closes the observation subscription on source close. Capture Stop detaches through the observer dispatcher and drains in-flight callbacks before freezing; accepted observations are never reordered by model time. Limit/time/serialization failures become visible incomplete/error captures and do not corrupt the source operation. +- The singleton recording workspace is necessary because feature view-model disposal closes the source on route navigation. Cross-scope test and native smoke prove source-close completion remains available for save/inspection across route unmount. +- The codec validates exact schema-object property sets, duplicate/unknown fields, case-sensitive enum tokens, explicit-offset UTC, canonical base64, contiguous sequence/order/count/encoded-byte limits and raw request/response/context associations before publishing a loaded snapshot. Opaque signal JSON values retain their kind/data. +- The file store uses opaque GUID filenames, bounded input reads, a closed/flushed temporary file and no-overwrite publication; cancellation/collision/cleanup/read/list failures stay typed and visible. +- The shared panel renders raw/decoded details on demand, keeps source units/context distinct from display preferences, and exposes partial/error/save state. The final native UI rendered `v1`/`v2` and `0x10`/`0x20` correctly. + +## Preservation and stopping review + +`git diff --check` passed. No project, package, dependency, host, backend, hardware, replay, database or storage framework was added. No protected prompt/roadmap/state/worker-gate/history files were changed. No stages, commits, pushes or subsequent worker handoff were performed. Task-generated native archives and exact temporary WebView profiles were cleaned; the app's empty recordings directory and existing preferences were left intact. +``` diff --git a/prompts/Step-07A.md b/prompts/Step-07A.md new file mode 100644 index 0000000..52ccf97 --- /dev/null +++ b/prompts/Step-07A.md @@ -0,0 +1,233 @@ +# Step-07A - Source-faithful archives, bounded cleanup and visible failures + +## STEP IDENTIFIER + +Step-07A, consolidated correction of original Step-07 R-01 through R-04. +Step-07 is NOT ACCEPTED. Corrected Step-06 and earlier work remain accepted. +This is the sole active assignment; Step-08 replay is blocked and not assigned. + +## STEP TITLE + +Make valid captures round-trip, invalid archives fail closed with typed errors, +released capture ownership stay bounded, and storage failures remain visible. + +## OBJECTIVE + +Close the existing Step-07 fidelity/validation/lifetime/I/O requirements. +Preserve the working observation tap, limits, source-close retention, file +publication and native recording workflow. No format expansion, recorder +redesign, playback or newly planned feature is assigned. + +Read [STATE.md](STATE.md), [Step-07](Step-07.md), its preserved +[report](Step-07-Report.md), [archive guide](../docs/telemetry-archive-v1.md) and +[WORKER-QUALITY-GATE.md](WORKER-QUALITY-GATE.md). Reproduce the actual failures, +fix and self-review inside this assignment, write `prompts/Step-07A-Report.md`, +then STOP. + +## ARCHITECTURAL CONTEXT + +Keep all nine projects, one Client, independent Components and existing read-only +Diagnostics observation -> Application capture/archive -> UI/native storage +boundaries. No new dependency, host, general lifetime/event framework or +Simulation oracle. All source/tests stay under `src`, tests under `src/tests`. + +The source protocol and its comparison/type/unit rules remain authoritative. +Archive consistency is not authenticity, but that caveat does not waive its +required shape/coherence validation. No display-unit values replace source data. + +## CURRENT IMPLEMENTATION STATE + +Worker-reported Step-07 evidence: clean complete Release build; 179 unit + +124 integration passes (303 total, zero failed/skipped), exact limit tests, +225 actual operations beyond the UI trace and native static/dynamic save/ +restart/load/unmount smoke. Retain all of it and all 284 earlier cases. + +The source review below did not execute a reproduction, application build/test +or native command. Reinspect Git and preserve existing worker changes/history. + +## REQUIRED IMPLEMENTATION + +### R-01 - Accept and preserve observations that the real source accepts + +[ValidateObservation](../src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/TelemetryArchiveCodec.cs:215) +requires response bytes for ProtocolError. A real TransportOutcome.Response +with an empty payload produces ProtocolError and null bytes in the existing +DiagnosticTraceEntry representation, so that legitimate stopped capture cannot +serialize/save. Preserve that exact representation; do not invent placeholder +response bytes or change diagnostic trace semantics to satisfy the codec. + +Archive snapshot/module/envelope association also uses Ordinal comparisons +where the source client accepts case-insensitive identities. For example an +accepted uppercase endpoint module can have an uppercase trace identifier and +the provider's canonical lowercase decoded module; the codec rejects the pair. + +Reproduce both with real protocol/session observations and actual archive save/ +new-instance readback. Apply each field's existing source comparison rule, +preserving all original spellings/bytes. Do not blanket-normalize strings or +weaken exact unit/signal-ID/version checks. + +### R-02 - Validate associations before dereference and enforce existing v2 shape + +Positive read.signals with signalSnapshot null reaches +[ValidateSignalResponse](../src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/TelemetryArchiveCodec.cs:392) +before the required association guard, dereferencing null. This must be a typed +InvalidArchive error that leaves prior inspection intact, never an escaping +NullReferenceException or a broad catch masking a programming error. + +The codec compares raw and decoded v2 values to each other but does not fully +apply the already-defined v2 known-ID/unit/JSON-kind/finite/duplicate/nonnegative +model-time rules. Editing both sides consistently can therefore load data the +actual v2 client rejects. + +Reuse/extract the applicable existing pure validators rather than duplicating a +second protocol specification. Keep source/trace/context coherence and exact +known units/types; reject unknown v2 IDs, duplicate signal IDs and negative model +time. Preserve legitimate v1 nullable/non-numeric/opaque/Unknown values. +Do not infer missing context from labels/current catalogues or relax v2 itself. +No archive version bump or new payload format is needed to bypass validation. + +For semantic regression inputs, adjust raw and decoded data and all necessary +count/encoded-byte bookkeeping coherently. A rejection caused only by a stale +byte count is not proof that the intended semantic guard works. + +### R-03 - Release obsolete capture registrations and make teardown failure-safe + +[SessionTelemetryCapture.Start](../src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/SessionTelemetryCapture.cs:105) +registers each capture in +[DiagnosticSession](../src/AutoForge.Application/Features/Vehicles/Diagnostics/DiagnosticSessionService.cs:100). +That list retains every capture and its observation buffer until the session +closes. Stop/discard/replacement do not unregister obsolete owners; repeating +captures on one still-open source therefore retains unbounded old history. + +Release obsolete lifetime registrations/subscriptions using the smallest +existing-boundary change. Cover normal Stop, limit/error stop, discard, saved +replacement and CloseInspection as appropriate. Do not clear the current stopped +data still owed to save/inspection, remove source-close draining, or replace +bounded capture with streaming. Returned immutable snapshots may remain readable; +the source/workspace must not retain discarded/replaced owners unnecessarily. + +The controlled Stop-drain test currently releases its blocking observer only +after assertions. A failure can unwind into subscription disposal while the +observer still holds the dispatch gate, deadlocking teardown. +Release barriers in finally before disposing observers/awaiting draining work. +Audit equivalent new recording-test cleanup paths, not unrelated old suites. + +Prove release deterministically through actual ownership/registration assertions +over repeated captures on the same open session, not a timing/memory benchmark +or sleep-based GC test. Preserve the active dashboard and source behavior. + +### R-04 - Keep catalogue and actual-panel save failures explicit + +[ListAsync](../src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/FileTelemetryArchiveStore.cs:112) +returns empty when Directory.Exists is false, including when its root is an +existing file. Missing first-use storage may be empty; an invalid/inaccessible +root or listing I/O failure must be a typed visible failure, not healthy zero +archives. Test with task-owned files rather than changing user permissions. + +The [panel SaveAsync](../src/AutoForge.UI/Features/Vehicles/Telemetry/Recording/TelemetryRecordingPanel.razor:256) +always refreshes after workspace SaveAsync returns. The workspace catches a +save error into Error/Status, then refresh clears it and can report a healthy +catalogue. Preserve the save failure through the full actual handler/render path. + +Refresh automatically only after a genuinely successful save, or use an equally +explicit typed outcome that cannot erase failure. Do not mark a failed capture +saved, overwrite the existing archive, silently swallow I/O, or redesign the UI. +Keep existing pending-command/capture-ID safeguards and successful save/list flow. + +### Frozen corrective matrix + +| ID | Input/precondition | Required result | +|---|---|---| +| C-01 | Actual empty reply recorded as ProtocolError with null trace response | Stop/save/new-store readback succeeds and preserves the exact error/raw representation, with no decoded successful signals or invented bytes | +| C-02 | Case-variant endpoint/envelope identities accepted by the existing client | Actual positive result and archive round trip both succeed; original trace/raw/decoded spellings and values are retained using field-specific equality rules | +| C-03 | Positive read.signals archive with null signalSnapshot | Typed InvalidArchive before dereference/publication; no NullReferenceException, prior workspace inspection remains unchanged | +| C-04 | Otherwise coherent v2 raw/decoded edits: wrong unit/JSON kind, unknown or duplicate signal ID, or negative model time | Typed rejection at archive boundary, not a mismatched bookkeeping proxy; existing source protocol is not weakened | +| C-05 | Normal v1 null/non-numeric/opaque/Unknown data, normal v2, nonempty malformed-reply evidence | Original valid capture/readback behavior and all source/raw/context/limit invariants stay intact | +| C-06 | Repeated stop/save/new and stop/discard on one still-open session; close inspection/source | Obsolete capture registrations/handlers/buffers are not source/workspace-retained; current unsaved stopped data remains saveable and source close still drains | +| C-07 | Assertion/command failure while a controlled observer is held | Finally releases the barrier before observer disposal/drain; no stranded source/owner/test or unsafe gate wait | +| C-08 | Catalogue root is a task-owned file; missing directory; controlled list failure | Bad root/I/O is typed and visible, missing first-use directory remains a legitimate empty result; prior valid inspection/catalogue is not falsely replaced | +| C-09 | Actual panel save event hits write failure or collision; list itself can succeed | Save error remains visible, current capture stays unsaved, existing file stays unchanged; successful retry/save/refresh still works | +| C-10 | Full existing capture/source/unit/model/native workflow | All 303 baseline cases plus new meaningful coverage, exact original limits and nine-project Release/native baseline pass; replay remains unimplemented | + +## FILES OR PROJECTS EXPECTED TO CHANGE + +Existing archive codec and applicable shared Diagnostics validators, narrow +capture/session registration release, workspace/panel save outcome, catalogue +I/O classification, focused tests and directly related docs/README. +Only `prompts/Step-07A-Report.md` under `prompts`. +No assignment, roadmap/state, gate, historical report or protected-file edit. + +## INTERFACE AND DEPENDENCY REQUIREMENTS + +Preserve all source protocol/profile/configuration contracts, immutable snapshots, +exact source bytes/units/time, one capture owner/cutover, source-close retention, +single acquisition/physics owners, verified clear and partial discovery. +Keep 4,096 observations, 16 MiB observation bytes, 1 MiB header, 32 MiB archive +and depth 128 limits; do not raise limits to hide a failure. +No new package/project/host, general resource framework, database or replay clock. +No workload/system restore/install/update/repair/rollback or destructive Git. +Install/restore nothing absent a genuine chosen-command missing dependency. + +## TESTING REQUIREMENTS + +Run actual pre-fix behavioral regressions for R-01..R-04 and report observed +failures, then corrected results. No compilation failure or invented runtime +observation counts. The orchestrator's source review is not an executed test. + +Use real v1/v2 sessions/protocol/observation/capture paths for valid-source cases, +the real codec and temporary filesystem for archive cases, and actual panel +event/render evidence for failure visibility. Faults may be injected below the +feature boundary, not by replacing the recording feature with a mock. +Exercise coherent invalid archives and deterministic resource-release assertions. +Release all barriers/files/source subscriptions in finally. + +Run focused cases, then sequentially: + +- `dotnet build .\src\AutoForge.slnx --configuration Release --no-restore` +- `dotnet test .\src\AutoForge.slnx --configuration Release --no-build` + +Preserve the 303 baseline cases (179 unit, 124 integration) plus meaningful new +assertions. Map necessary presentation-only changes without deleting safety/ +error/source checks. Record exact commands/exits/warnings/per-project counts. + +Recheck the rebuilt native static/dynamic record/stop/save/restart/load/close +baseline. Controlled codec/lifetime/I/O tests establish injected edge cases, not +a claim of native fault injection. Clean only exact task-owned captures/profiles; +do not reset app data or modify unrelated files/preferences. + +## DOCUMENTATION REQUIREMENTS + +Align strict archive/source comparison rules, typed invalid-data behavior, +bounded registration ownership and visible save/list errors with the actual +implementation. Preserve original Step-07 results as history; do not downgrade +the original contract or claim playback/new format/Step-07 acceptance. + +## ACCEPTANCE CRITERIA + +| ID | Criterion | Evidence | +|---|---|---| +| AC-01 | R-01/C-01/C-02 valid source observations round-trip without data fabrication | Actual pre-fix failures and real protocol/file corrected assertions | +| AC-02 | R-02/C-03..C-05 invalid data rejects with typed errors and existing v2 semantics, while valid v1/v2 remain supported | Coherent negative vectors, unchanged prior inspection and source/codec regressions | +| AC-03 | R-03/C-06/C-07 obsolete ownership releases and controlled failure cleanup cannot strand resources | Deterministic repeated-capture registration assertions and finally/drain evidence | +| AC-04 | R-04/C-08/C-09 I/O failures remain typed/visible through actual store/workspace/panel | Bad-root and actual handler failure/retry/collision tests, no false Saved/empty-success state | +| AC-05 | C-10 existing 303 cases/limits/source/model behavior, full Release build/tests and native baseline pass | Exact complete worker results and native/control distinction | +| AC-06 | Original mapping/docs/self-review/history/protection/manual gate satisfied; report saved and worker stops | R-01..R-04 matrix, own post-green source-path review and `prompts/Step-07A-Report.md` | + +## OUT-OF-SCOPE WORK + +Playback/seek/speed controls, live disk streaming/crash durability, new archive +version/unit family, charts/layouts, calibration/AI/hardware, new project/package/ +host and unrelated cleanup. No future assignment, agents, automatic handoff, +orchestration/shared-gate edit, staging/commit/push or destructive Git. + +## REPORTING REQUIREMENTS + +Save `prompts/Step-07A-Report.md` entirely inside exactly one plain triple-backtick +fence, no language tag/outside content/nested fences. Include identifier/title/ +status, implementation/files/interfaces, R-01..R-04 and C-01..C-10/AC-01..AC-06 +mapping, named actual pre/post results and coherent archive/resource/panel +assertions, commands/exits/warnings/per-project counts, native versus controlled +coverage, docs/README, self-review after first green, limitations/deviations/ +blockers and preservation review. +COMPLETE requires all assigned checks; otherwise report INCOMPLETE/BLOCKED with +the precise missing criterion. Save and STOP; do not begin Step-08. diff --git a/src/AutoForge.Application/Features/Vehicles/Diagnostics/DiagnosticSessionService.cs b/src/AutoForge.Application/Features/Vehicles/Diagnostics/DiagnosticSessionService.cs index ccb7806..882daab 100644 --- a/src/AutoForge.Application/Features/Vehicles/Diagnostics/DiagnosticSessionService.cs +++ b/src/AutoForge.Application/Features/Vehicles/Diagnostics/DiagnosticSessionService.cs @@ -87,6 +87,15 @@ public sealed class DiagnosticSession( public IReadOnlyList ExpectedEndpoints => protocol.ExpectedEndpoints; public DiagnosticTraceSnapshot Trace => protocol.Trace; public bool IsClosed => Volatile.Read(ref _closed) != 0; + public int ObservationProtocolVersion => + (protocol as IDiagnosticOperationObservationSource)?.ProtocolVersion + ?? throw new InvalidOperationException("This diagnostic session does not expose validated operation observations."); + public string? ObservationDispatchError => + (protocol as IDiagnosticOperationObservationSource)?.ObservationDispatchError; + + public IDisposable SubscribeObservations(Action observer) => + (protocol as IDiagnosticOperationObservationSource)?.Subscribe(observer) + ?? throw new InvalidOperationException("This diagnostic session does not expose validated operation observations."); public void RegisterLifetimeResource(IAsyncDisposable resource) { diff --git a/src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/FileTelemetryArchiveStore.cs b/src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/FileTelemetryArchiveStore.cs new file mode 100644 index 0000000..88f9337 --- /dev/null +++ b/src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/FileTelemetryArchiveStore.cs @@ -0,0 +1,295 @@ +using System.Security; +using System.Runtime.ExceptionServices; +using System.Text.Json; +using AutoForge.Core.ExecutionTargets; + +namespace AutoForge.Application.Features.Vehicles.Telemetry.Recording; + +public sealed class FileTelemetryArchiveStore : ITelemetryArchiveStore +{ + private readonly string _rootDirectory; + + public FileTelemetryArchiveStore(string rootDirectory) + { + ArgumentException.ThrowIfNullOrWhiteSpace(rootDirectory); + _rootDirectory = Path.GetFullPath(rootDirectory); + } + + public async Task SaveAsync( + TelemetryCaptureSnapshot capture, + CancellationToken cancellationToken = default) + { + ArgumentNullException.ThrowIfNull(capture); + var archive = TelemetryArchiveCodec.Serialize(capture); + var finalPath = GetArchivePath(capture.Header.CaptureId); + var temporaryPath = Path.Combine( + _rootDirectory, + $".{capture.Header.CaptureId}.{Guid.NewGuid():N}.tmp"); + Exception? saveFailure = null; + try + { + cancellationToken.ThrowIfCancellationRequested(); + Directory.CreateDirectory(_rootDirectory); + await using (var stream = new FileStream( + temporaryPath, + FileMode.CreateNew, + FileAccess.Write, + FileShare.None, + 81920, + FileOptions.Asynchronous | FileOptions.WriteThrough)) + { + await stream.WriteAsync(archive, cancellationToken).ConfigureAwait(false); + await stream.FlushAsync(cancellationToken).ConfigureAwait(false); + stream.Flush(flushToDisk: true); + } + + cancellationToken.ThrowIfCancellationRequested(); + try + { + File.Move(temporaryPath, finalPath); + } + catch (IOException exception) when (File.Exists(finalPath)) + { + throw new TelemetryArchiveException( + TelemetryArchiveFailure.Collision, + $"Capture '{capture.Header.CaptureId}' already exists; archives are never overwritten.", + exception); + } + } + catch (Exception exception) + { + saveFailure = exception; + } + + Exception? cleanupFailure = null; + try + { + File.Delete(temporaryPath); + } + catch (Exception exception) when (IsFileFailure(exception)) + { + cleanupFailure = exception; + } + + if (cleanupFailure is not null) + { + var innerException = saveFailure is null + ? cleanupFailure + : new AggregateException(saveFailure, cleanupFailure); + throw new TelemetryArchiveException( + TelemetryArchiveFailure.WriteFailure, + $"Could not safely remove temporary archive '{Path.GetFileName(temporaryPath)}'; inspect and remove this exact temporary file after resolving the reported filesystem error.", + innerException); + } + + if (saveFailure is TelemetryArchiveException archiveException) + { + ExceptionDispatchInfo.Capture(archiveException).Throw(); + } + + if (saveFailure is OperationCanceledException cancelled) + { + throw new TelemetryArchiveException( + TelemetryArchiveFailure.Cancelled, + "Saving the telemetry archive was cancelled before publication.", + cancelled); + } + + if (saveFailure is not null && IsFileFailure(saveFailure)) + { + throw new TelemetryArchiveException( + TelemetryArchiveFailure.WriteFailure, + $"Could not save capture '{capture.Header.CaptureId}': {saveFailure.Message}", + saveFailure); + } + + if (saveFailure is not null) + { + ExceptionDispatchInfo.Capture(saveFailure).Throw(); + } + } + + public async Task> ListAsync( + CancellationToken cancellationToken = default) + { + try + { + if (!Directory.Exists(_rootDirectory)) + { + return Array.Empty(); + } + + var captures = new List(); + foreach (var path in Directory.EnumerateFiles(_rootDirectory, "*.json", SearchOption.TopDirectoryOnly)) + { + cancellationToken.ThrowIfCancellationRequested(); + var name = Path.GetFileNameWithoutExtension(path); + if (!IsCaptureId(name)) + { + throw new TelemetryArchiveException( + TelemetryArchiveFailure.InvalidCaptureId, + $"Recording file '{Path.GetFileName(path)}' does not use a valid opaque capture ID."); + } + + var archive = await ReadFileAsync(path, cancellationToken).ConfigureAwait(false); + if (!StringComparer.Ordinal.Equals(archive.Header.CaptureId, name)) + { + throw new TelemetryArchiveException( + TelemetryArchiveFailure.InvalidArchive, + $"Recording filename '{Path.GetFileName(path)}' does not match the archive capture ID."); + } + + captures.Add(new TelemetrySavedCapture( + archive.Header.CaptureId, + archive.Header.SessionIdentifier, + archive.Header.ProfileIdentifier, + DateTimeOffset.ParseExact( + archive.Header.StartedAtUtc, + "O", + System.Globalization.CultureInfo.InvariantCulture), + archive.Completion!.State, + archive.Observations.Count)); + } + + return Array.AsReadOnly(captures + .OrderByDescending(capture => capture.StartedAtUtc) + .ThenBy(capture => capture.CaptureId, StringComparer.Ordinal) + .ToArray()); + } + catch (TelemetryArchiveException) + { + throw; + } + catch (OperationCanceledException exception) + { + throw new TelemetryArchiveException( + TelemetryArchiveFailure.Cancelled, + "Listing telemetry archives was cancelled.", + exception); + } + catch (Exception exception) when (IsFileFailure(exception)) + { + throw new TelemetryArchiveException( + TelemetryArchiveFailure.ReadFailure, + $"Could not list telemetry archives: {exception.Message}", + exception); + } + } + + public async Task LoadAsync( + string captureId, + CancellationToken cancellationToken = default) + { + var path = GetArchivePath(captureId); + try + { + var capture = await ReadFileAsync(path, cancellationToken).ConfigureAwait(false); + if (!StringComparer.Ordinal.Equals(capture.Header.CaptureId, captureId)) + { + throw new TelemetryArchiveException( + TelemetryArchiveFailure.InvalidArchive, + "The archive capture ID does not match its filename."); + } + + return new TelemetryCaptureSnapshot( + capture.Header, + capture.Observations, + capture.Completion, + isSaved: true); + } + catch (TelemetryArchiveException) + { + throw; + } + catch (OperationCanceledException exception) + { + throw new TelemetryArchiveException( + TelemetryArchiveFailure.Cancelled, + "Loading the telemetry archive was cancelled.", + exception); + } + catch (Exception exception) when (IsFileFailure(exception)) + { + throw new TelemetryArchiveException( + TelemetryArchiveFailure.ReadFailure, + $"Could not read capture '{captureId}': {exception.Message}", + exception); + } + } + + private async Task ReadFileAsync( + string path, + CancellationToken cancellationToken) + { + try + { + await using var stream = new FileStream( + path, + FileMode.Open, + FileAccess.Read, + FileShare.Read, + 81920, + FileOptions.Asynchronous | FileOptions.SequentialScan); + if (stream.Length > TelemetryCaptureLimits.Default.MaximumArchiveBytes) + { + throw new TelemetryArchiveException( + TelemetryArchiveFailure.LimitExceeded, + "A telemetry archive file exceeds the 32 MiB input limit."); + } + + using var buffer = new MemoryStream((int)stream.Length); + var chunk = new byte[81920]; + while (true) + { + var read = await stream.ReadAsync(chunk, cancellationToken).ConfigureAwait(false); + if (read == 0) + { + break; + } + + if (buffer.Length + read > TelemetryCaptureLimits.Default.MaximumArchiveBytes) + { + throw new TelemetryArchiveException( + TelemetryArchiveFailure.LimitExceeded, + "A telemetry archive file exceeds the 32 MiB input limit."); + } + + buffer.Write(chunk, 0, read); + } + + return TelemetryArchiveCodec.Deserialize(buffer.ToArray()); + } + catch (TelemetryArchiveException) + { + throw; + } + catch (JsonException exception) + { + throw new TelemetryArchiveException( + TelemetryArchiveFailure.InvalidArchive, + $"The telemetry archive '{Path.GetFileName(path)}' is corrupt.", + exception); + } + } + + private string GetArchivePath(string captureId) + { + if (!IsCaptureId(captureId)) + { + throw new TelemetryArchiveException( + TelemetryArchiveFailure.InvalidCaptureId, + "Capture ID must be a lowercase GUID in N format."); + } + + return Path.Combine(_rootDirectory, $"{captureId}.json"); + } + + private static bool IsCaptureId(string value) => + value.Length == 32 && + Guid.TryParseExact(value, "N", out var parsed) && + StringComparer.Ordinal.Equals(parsed.ToString("N"), value); + + private static bool IsFileFailure(Exception exception) => + exception is IOException or UnauthorizedAccessException or SecurityException or ArgumentException; + +} diff --git a/src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/ITelemetryArchiveStore.cs b/src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/ITelemetryArchiveStore.cs new file mode 100644 index 0000000..a52d442 --- /dev/null +++ b/src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/ITelemetryArchiveStore.cs @@ -0,0 +1,8 @@ +namespace AutoForge.Application.Features.Vehicles.Telemetry.Recording; + +public interface ITelemetryArchiveStore +{ + Task SaveAsync(TelemetryCaptureSnapshot capture, CancellationToken cancellationToken = default); + Task> ListAsync(CancellationToken cancellationToken = default); + Task LoadAsync(string captureId, CancellationToken cancellationToken = default); +} diff --git a/src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/SessionTelemetryCapture.cs b/src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/SessionTelemetryCapture.cs new file mode 100644 index 0000000..51b5fa3 --- /dev/null +++ b/src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/SessionTelemetryCapture.cs @@ -0,0 +1,467 @@ +using System.Globalization; +using System.Runtime.CompilerServices; +using System.Text.Json; +using AutoForge.Application.Features.Vehicles.Diagnostics; +using AutoForge.Core.ExecutionTargets; +using AutoForge.Diagnostics; + +namespace AutoForge.Application.Features.Vehicles.Telemetry.Recording; + +public sealed class SessionTelemetryCapture : IAsyncDisposable +{ + private static readonly ConditionalWeakTable SessionOwners = new(); + private static readonly object SessionOwnersGate = new(); + private readonly object _gate = new(); + private readonly DiagnosticSession _session; + private readonly TimeProvider _timeProvider; + private readonly TelemetryCaptureLimits _limits; + private readonly List _observations = []; + private IDisposable? _subscription; + private long _startTimestamp; + private long _observationBytes; + private TelemetryCaptureHeader _header; + private TelemetryCaptureCompletion? _completion; + private bool _accepting; + private bool _isStopping; + private bool _disposed; + private bool _isSaved; + + private SessionTelemetryCapture( + DiagnosticSession session, + TimeProvider timeProvider, + TelemetryCaptureLimits limits) + { + _session = session; + _timeProvider = timeProvider; + _limits = limits; + var identity = session.Identity; + _header = new TelemetryCaptureHeader( + Guid.NewGuid().ToString("N"), + identity.SessionIdentifier, + identity.ProfileIdentifier, + identity.ProfileRevision, + identity.VehicleIdentifier, + identity.Target.ProviderIdentifier, + identity.Target.Kind, + TelemetryArchiveCodec.ProtocolName, + session.ObservationProtocolVersion, + identity.DynamicsConfigurationIdentifier, + identity.DynamicsRunIdentifier, + Array.AsReadOnly(session.ExpectedEndpoints.Select(endpoint => + new TelemetryCaptureEndpoint(endpoint.ModuleIdentifier, endpoint.Address)).ToArray()), + DateTimeOffset.UnixEpoch.ToString("O", CultureInfo.InvariantCulture)); + } + + public event Action? Changed; + + public static SessionTelemetryCapture Start( + DiagnosticSession session, + TimeProvider? timeProvider = null, + TelemetryCaptureLimits? limits = null) + { + ArgumentNullException.ThrowIfNull(session); + if (session.IsClosed) + { + throw new TelemetryArchiveException( + TelemetryArchiveFailure.InvalidArchive, + "Recording requires an open diagnostic session."); + } + + var capture = new SessionTelemetryCapture( + session, + timeProvider ?? TimeProvider.System, + limits ?? TelemetryCaptureLimits.Default); + if (capture._limits.MaximumObservations is < 1 or > 4096 || + capture._limits.MaximumObservationBytes is < 1 or > 16L * 1024 * 1024 || + capture._limits.MaximumHeaderBytes is < 1 or > 1024 * 1024 || + capture._limits.MaximumArchiveBytes is < 1 or > 32 * 1024 * 1024) + { + throw new ArgumentOutOfRangeException(nameof(limits), "Capture limits must be positive and cannot exceed the assigned fixed limits."); + } + + if (TelemetryArchiveCodec.GetEncodedHeaderLength(capture._header) > capture._limits.MaximumHeaderBytes) + { + throw new TelemetryArchiveException( + TelemetryArchiveFailure.LimitExceeded, + $"The encoded capture header exceeds the {capture._limits.MaximumHeaderBytes}-byte header limit."); + } + + lock (SessionOwnersGate) + { + if (SessionOwners.TryGetValue(session, out _)) + { + throw new InvalidOperationException( + "This diagnostic session already owns a telemetry capture; stop it before acquiring another owner."); + } + + SessionOwners.Add(session, capture); + } + + IDisposable? subscription = null; + try + { + subscription = session.SubscribeObservations(capture.OnObservation); + capture._subscription = subscription; + session.RegisterLifetimeResource(capture); + lock (capture._gate) + { + ObjectDisposedException.ThrowIf(capture._disposed, capture); + capture._header = capture._header with + { + StartedAtUtc = capture._timeProvider.GetUtcNow().ToUniversalTime().ToString("O", CultureInfo.InvariantCulture) + }; + capture._startTimestamp = capture._timeProvider.GetTimestamp(); + capture._accepting = true; + } + + capture.Changed?.Invoke(); + return capture; + } + catch + { + subscription?.Dispose(); + ReleaseSessionOwnership(session, capture); + throw; + } + } + + public TelemetryCaptureSnapshot Snapshot + { + get + { + lock (_gate) + { + return new TelemetryCaptureSnapshot( + _header, + _observations, + _completion, + _isSaved); + } + } + } + + public bool IsAccepting + { + get + { + lock (_gate) + { + return _accepting; + } + } + } + + public bool IsStopping + { + get + { + lock (_gate) + { + return _isStopping; + } + } + } + + public void Stop(TelemetryCaptureStopReason reason = TelemetryCaptureStopReason.User) + { + if (reason is TelemetryCaptureStopReason.LimitExceeded or TelemetryCaptureStopReason.ObservationFailure) + { + throw new ArgumentOutOfRangeException(nameof(reason), "The selected stop reason is reserved for capture failures."); + } + + IDisposable? subscription; + lock (_gate) + { + while (_isStopping) + { + Monitor.Wait(_gate); + } + + if (!_accepting && _subscription is null) + { + return; + } + + _isStopping = true; + subscription = _subscription; + } + + try + { + subscription?.Dispose(); + } + catch + { + lock (_gate) + { + _isStopping = false; + Monitor.PulseAll(_gate); + } + + throw; + } + + lock (_gate) + { + _subscription = null; + if (_accepting) + { + _accepting = false; + _completion = CreateCompletion(reason, TelemetryCaptureState.Complete, null); + } + + _isStopping = false; + Monitor.PulseAll(_gate); + } + + ReleaseSessionOwnership(_session, this); + Changed?.Invoke(); + } + + public void MarkSaved() + { + lock (_gate) + { + if (_completion is null) + { + throw new InvalidOperationException("An active capture cannot be marked saved."); + } + + _isSaved = true; + } + + Changed?.Invoke(); + } + + public ValueTask DisposeAsync() + { + StopForSourceClose(); + return ValueTask.CompletedTask; + } + + private void OnObservation(DiagnosticOperationObservation observation) + { + var detach = false; + var changed = false; + IDisposable? subscription = null; + lock (_gate) + { + if (!_accepting) + { + return; + } + + try + { + var elapsedTicks = _timeProvider.GetElapsedTime(_startTimestamp).Ticks; + var priorElapsedTicks = _observations.Count == 0 ? 0 : _observations[^1].CaptureElapsedTicks; + if (elapsedTicks < 0 || elapsedTicks < priorElapsedTicks) + { + CompleteFailure( + TelemetryCaptureStopReason.ObservationFailure, + TelemetryCaptureState.Error, + "The capture time source moved backwards."); + detach = true; + changed = true; + } + else if (_observations.Count >= _limits.MaximumObservations) + { + CompleteFailure( + TelemetryCaptureStopReason.LimitExceeded, + TelemetryCaptureState.Incomplete, + $"Capture stopped at the {_limits.MaximumObservations}-observation limit; later operations were not captured."); + detach = true; + changed = true; + } + else + { + var recorded = ConvertObservation(observation, _observations.Count + 1, elapsedTicks); + var encodedBytes = TelemetryArchiveCodec.GetEncodedObservationLength(recorded); + if (_observationBytes + encodedBytes > _limits.MaximumObservationBytes) + { + CompleteFailure( + TelemetryCaptureStopReason.LimitExceeded, + TelemetryCaptureState.Incomplete, + $"Capture stopped because the next observation would exceed the {_limits.MaximumObservationBytes}-byte observation limit; later operations were not captured."); + detach = true; + changed = true; + } + else + { + _observations.Add(recorded); + _observationBytes = checked(_observationBytes + encodedBytes); + changed = true; + } + } + } + catch (Exception exception) when (exception is JsonException or InvalidOperationException or ArgumentException or OverflowException) + { + CompleteFailure( + TelemetryCaptureStopReason.ObservationFailure, + TelemetryCaptureState.Error, + $"A validated diagnostic operation could not be retained: {exception.Message}"); + detach = true; + changed = true; + } + + if (detach) + { + subscription = _subscription; + } + } + + if (detach) + { + subscription?.Dispose(); + lock (_gate) + { + if (ReferenceEquals(_subscription, subscription)) + { + _subscription = null; + } + } + + ReleaseSessionOwnership(_session, this); + } + + if (changed) + { + Changed?.Invoke(); + } + } + + private void StopForSourceClose() + { + IDisposable? subscription; + lock (_gate) + { + while (_isStopping) + { + Monitor.Wait(_gate); + } + + if (_disposed) + { + return; + } + + _disposed = true; + subscription = _subscription; + _isStopping = true; + } + + try + { + subscription?.Dispose(); + } + catch + { + lock (_gate) + { + _disposed = false; + _isStopping = false; + Monitor.PulseAll(_gate); + } + + throw; + } + + lock (_gate) + { + _subscription = null; + if (_accepting) + { + _accepting = false; + _completion = CreateCompletion( + TelemetryCaptureStopReason.SourceClosed, + TelemetryCaptureState.Complete, + null); + } + + _isStopping = false; + Monitor.PulseAll(_gate); + } + + ReleaseSessionOwnership(_session, this); + Changed?.Invoke(); + } + + private void CompleteFailure( + TelemetryCaptureStopReason reason, + TelemetryCaptureState state, + string error) + { + _accepting = false; + _completion = CreateCompletion(reason, state, error); + } + + private TelemetryCaptureCompletion CreateCompletion( + TelemetryCaptureStopReason reason, + TelemetryCaptureState state, + string? error) + { + return new TelemetryCaptureCompletion( + _timeProvider.GetUtcNow().ToUniversalTime().ToString("O", CultureInfo.InvariantCulture), + reason, + state, + _observations.Count, + _observationBytes, + error); + } + + private static TelemetryRecordedObservation ConvertObservation( + DiagnosticOperationObservation observation, + long sequence, + long elapsedTicks) + { + var trace = observation.Trace; + var signals = observation.SignalSnapshot is { } snapshot + ? new TelemetryRecordedSignalSnapshot( + snapshot.ModuleIdentifier, + Array.AsReadOnly(snapshot.Signals.Select(signal => new TelemetryRecordedSignal( + signal.SignalIdentifier, + signal.ModuleIdentifier, + signal.Value.Clone(), + signal.Unit, + signal.Quality, + signal.LogicalTimeTicks, + signal.Origin, + signal.ModelStepIndex, + signal.ModelTimeSeconds, + signal.ModelConfigurationIdentifier, + signal.ModelRunIdentifier)).ToArray()), + snapshot.ModelStepIndex, + snapshot.ModelTimeSeconds, + snapshot.ModelConfigurationIdentifier, + snapshot.ModelRunIdentifier) + : null; + + return new TelemetryRecordedObservation( + sequence, + elapsedTicks, + trace.ModuleIdentifier, + trace.Address, + trace.CorrelationIdentifier, + trace.Service, + trace.StartLogicalTicks, + trace.EndLogicalTicks, + trace.Outcome, + trace.DecodedSummary, + trace.Error, + Convert.ToBase64String(trace.RequestPayload.Span), + trace.ResponsePayload is { } response ? Convert.ToBase64String(response.Span) : null, + signals); + } + + private static void ReleaseSessionOwnership(DiagnosticSession session, SessionTelemetryCapture capture) + { + lock (SessionOwnersGate) + { + if (SessionOwners.TryGetValue(session, out var owner) && + ReferenceEquals(owner, capture)) + { + SessionOwners.Remove(session); + } + } + } +} diff --git a/src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/TelemetryArchiveCodec.cs b/src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/TelemetryArchiveCodec.cs new file mode 100644 index 0000000..05ee46a --- /dev/null +++ b/src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/TelemetryArchiveCodec.cs @@ -0,0 +1,959 @@ +using System.Globalization; +using System.Text.Json; +using System.Text.Json.Serialization; +using AutoForge.Core.ExecutionTargets; +using AutoForge.Diagnostics; + +namespace AutoForge.Application.Features.Vehicles.Telemetry.Recording; + +public static class TelemetryArchiveCodec +{ + public const int SchemaVersion = 1; + public const string ProtocolName = "autoforge.synthetic-diagnostics"; + + private static readonly JsonSerializerOptions SerializerOptions = CreateOptions(); + + public static byte[] Serialize(TelemetryCaptureSnapshot capture) + { + ArgumentNullException.ThrowIfNull(capture); + ValidateCapture(capture); + var bytes = JsonSerializer.SerializeToUtf8Bytes(ToArchive(capture), SerializerOptions); + if (bytes.Length > TelemetryCaptureLimits.Default.MaximumArchiveBytes) + { + throw new TelemetryArchiveException( + TelemetryArchiveFailure.LimitExceeded, + "The encoded telemetry archive exceeds the 32 MiB archive limit."); + } + + return bytes; + } + + public static TelemetryCaptureSnapshot Deserialize(ReadOnlyMemory bytes) + { + if (bytes.Length > TelemetryCaptureLimits.Default.MaximumArchiveBytes) + { + throw new TelemetryArchiveException( + TelemetryArchiveFailure.LimitExceeded, + "The telemetry archive exceeds the 32 MiB input limit."); + } + + try + { + using var document = JsonDocument.Parse( + bytes, + new JsonDocumentOptions { MaxDepth = 128 }); + ValidateSchemaObjects(document.RootElement); + var archive = JsonSerializer.Deserialize(bytes.Span, SerializerOptions) + ?? throw Invalid("The telemetry archive root is null."); + var result = FromArchive(archive); + ValidateCapture(result); + return result; + } + catch (TelemetryArchiveException) + { + throw; + } + catch (JsonException exception) + { + throw Invalid("The telemetry archive is malformed or contains an unsupported field value.", exception); + } + catch (FormatException exception) + { + throw Invalid("The telemetry archive contains invalid encoded data.", exception); + } + catch (InvalidOperationException exception) + { + throw Invalid("The telemetry archive contains an invalid schema value.", exception); + } + } + + public static int GetEncodedHeaderLength(TelemetryCaptureHeader header) + { + ArgumentNullException.ThrowIfNull(header); + return JsonSerializer.SerializeToUtf8Bytes(ToHeader(header), SerializerOptions).Length; + } + + public static int GetEncodedObservationLength(TelemetryRecordedObservation observation) + { + ArgumentNullException.ThrowIfNull(observation); + return JsonSerializer.SerializeToUtf8Bytes(ToObservation(observation), SerializerOptions).Length; + } + + private static void ValidateCapture(TelemetryCaptureSnapshot capture) + { + var header = capture.Header; + if (!IsCaptureId(header.CaptureId)) + { + throw new TelemetryArchiveException(TelemetryArchiveFailure.InvalidCaptureId, "Capture ID must be a lowercase GUID in N format."); + } + + if (string.IsNullOrWhiteSpace(header.SessionIdentifier) || + string.IsNullOrWhiteSpace(header.ProfileIdentifier) || + header.ProfileRevision <= 0 || + string.IsNullOrWhiteSpace(header.VehicleIdentifier) || + string.IsNullOrWhiteSpace(header.ProviderIdentifier) || + !Enum.IsDefined(header.TargetKind) || + !StringComparer.Ordinal.Equals(header.ProtocolName, ProtocolName) || + header.ProtocolVersion is not (1 or 2) || + !IsUtcTimestamp(header.StartedAtUtc) || + ((header.DynamicsConfigurationIdentifier is null) != (header.DynamicsRunIdentifier is null)) || + (header.DynamicsConfigurationIdentifier is not null && + string.IsNullOrWhiteSpace(header.DynamicsConfigurationIdentifier)) || + (header.DynamicsRunIdentifier is not null && + string.IsNullOrWhiteSpace(header.DynamicsRunIdentifier)) || + (header.ProtocolVersion == 1 && header.DynamicsConfigurationIdentifier is not null) || + (header.ProtocolVersion == 2 && header.DynamicsConfigurationIdentifier is null)) + { + throw Invalid("The telemetry archive header has missing or incoherent source identity."); + } + + if (header.SourceEndpoints is null || + header.SourceEndpoints.Count == 0 || + header.SourceEndpoints.Any(endpoint => + endpoint is null || + string.IsNullOrWhiteSpace(endpoint.ModuleIdentifier) || + !IsValidEndpoint(endpoint)) || + header.SourceEndpoints.Select(endpoint => $"{endpoint.ModuleIdentifier}\0{endpoint.Address}") + .Distinct(StringComparer.OrdinalIgnoreCase).Count() != header.SourceEndpoints.Count) + { + throw Invalid("The telemetry archive source endpoint list is empty or incoherent."); + } + + if (GetEncodedHeaderLength(header) > TelemetryCaptureLimits.Default.MaximumHeaderBytes) + { + throw new TelemetryArchiveException( + TelemetryArchiveFailure.LimitExceeded, + "The encoded telemetry archive header exceeds the 1 MiB header limit."); + } + + if (capture.Completion is null) + { + throw Invalid("An active capture cannot be serialized before Stop."); + } + + if (!IsUtcTimestamp(capture.Completion.StoppedAtUtc) || + !Enum.IsDefined(capture.Completion.StopReason) || + !Enum.IsDefined(capture.Completion.State) || + capture.Completion.ObservationCount != capture.Observations.Count || + capture.Completion.ObservationCount > TelemetryCaptureLimits.Default.MaximumObservations || + (capture.Completion.State == TelemetryCaptureState.Recording) || + (capture.Completion.State == TelemetryCaptureState.Complete && + (capture.Completion.Error is not null || + capture.Completion.StopReason is TelemetryCaptureStopReason.LimitExceeded or TelemetryCaptureStopReason.ObservationFailure)) || + (capture.Completion.State == TelemetryCaptureState.Incomplete && + capture.Completion.StopReason is not (TelemetryCaptureStopReason.LimitExceeded or TelemetryCaptureStopReason.ObservationFailure)) || + (capture.Completion.State == TelemetryCaptureState.Error && + (capture.Completion.StopReason != TelemetryCaptureStopReason.ObservationFailure || + string.IsNullOrWhiteSpace(capture.Completion.Error)))) + { + throw Invalid("The telemetry archive completion metadata is inconsistent."); + } + + var observationBytes = 0L; + long previousElapsed = -1; + for (var index = 0; index < capture.Observations.Count; index++) + { + var observation = capture.Observations[index]; + ValidateObservation(header, observation, index + 1, previousElapsed); + previousElapsed = observation.CaptureElapsedTicks; + observationBytes = checked(observationBytes + GetEncodedObservationLength(observation)); + if (observationBytes > TelemetryCaptureLimits.Default.MaximumObservationBytes) + { + throw new TelemetryArchiveException( + TelemetryArchiveFailure.LimitExceeded, + "The encoded observations exceed the 16 MiB observation limit."); + } + } + + if (capture.Completion.ObservationBytes != observationBytes) + { + throw Invalid("The completion observation-byte count does not match the encoded observations."); + } + } + + private static void ValidateObservation( + TelemetryCaptureHeader header, + TelemetryRecordedObservation observation, + long expectedSequence, + long previousElapsed) + { + if (observation.Sequence != expectedSequence || + observation.CaptureElapsedTicks < 0 || + observation.CaptureElapsedTicks < previousElapsed || + string.IsNullOrWhiteSpace(observation.ModuleIdentifier) || + string.IsNullOrWhiteSpace(observation.Address) || + string.IsNullOrWhiteSpace(observation.CorrelationIdentifier) || + string.IsNullOrWhiteSpace(observation.Service) || + observation.StartLogicalTicks < 0 || + observation.EndLogicalTicks < observation.StartLogicalTicks || + !Enum.IsDefined(observation.Outcome) || + string.IsNullOrWhiteSpace(observation.RequestPayloadBase64) || + !header.SourceEndpoints.Any(endpoint => + StringComparer.OrdinalIgnoreCase.Equals(endpoint.ModuleIdentifier, observation.ModuleIdentifier) && + StringComparer.OrdinalIgnoreCase.Equals(endpoint.Address, observation.Address))) + { + throw Invalid($"Observation {expectedSequence} has invalid sequence, time, identity or trace metadata."); + } + + if ((observation.Outcome == DiagnosticOutcome.PositiveResponse && + (observation.Error is not null || string.IsNullOrWhiteSpace(observation.DecodedSummary))) || + (observation.Outcome == DiagnosticOutcome.NegativeResponse && + (string.IsNullOrWhiteSpace(observation.Error) || + string.IsNullOrWhiteSpace(observation.DecodedSummary))) || + (observation.Outcome is not (DiagnosticOutcome.PositiveResponse or DiagnosticOutcome.NegativeResponse) && + string.IsNullOrWhiteSpace(observation.Error))) + { + throw Invalid($"Observation {expectedSequence} outcome, summary and error metadata are incoherent."); + } + + ValidateBase64(observation.RequestPayloadBase64, $"Observation {expectedSequence} request"); + if (observation.ResponsePayloadBase64 is { } response) + { + ValidateBase64(response, $"Observation {expectedSequence} response"); + } + + var requiresResponse = observation.Outcome is + DiagnosticOutcome.PositiveResponse or DiagnosticOutcome.NegativeResponse or DiagnosticOutcome.ProtocolError; + var prohibitsResponse = observation.Outcome is + DiagnosticOutcome.NoResponse or DiagnosticOutcome.Timeout or DiagnosticOutcome.Cancelled; + if ((requiresResponse && observation.ResponsePayloadBase64 is null) || + (prohibitsResponse && observation.ResponsePayloadBase64 is not null)) + { + throw Invalid($"Observation {expectedSequence} response bytes do not match its operation outcome."); + } + + ValidateRequestAssociation(header, observation); + if (observation.Outcome is DiagnosticOutcome.PositiveResponse or DiagnosticOutcome.NegativeResponse) + { + ValidateResponseAssociation(header, observation); + } + + var isSignalRead = StringComparer.Ordinal.Equals(observation.Service, DiagnosticServices.ReadSignals); + var hasSignals = observation.SignalSnapshot is not null; + if (hasSignals != (isSignalRead && observation.Outcome == DiagnosticOutcome.PositiveResponse)) + { + throw Invalid($"Observation {expectedSequence} has an incoherent decoded signal association."); + } + + if (!hasSignals) + { + return; + } + + var snapshot = observation.SignalSnapshot!; + if (!StringComparer.Ordinal.Equals(snapshot.ModuleIdentifier, observation.ModuleIdentifier) || + snapshot.Signals is null || + (header.ProtocolVersion == 1 && + (snapshot.ModelStepIndex is not null || + snapshot.ModelTimeSeconds is not null || + snapshot.ModelConfigurationIdentifier is not null || + snapshot.ModelRunIdentifier is not null)) || + (header.ProtocolVersion == 2 && + (snapshot.ModelStepIndex is null or < 0 || + snapshot.ModelTimeSeconds is null || + !double.IsFinite(snapshot.ModelTimeSeconds.Value) || + !StringComparer.Ordinal.Equals(snapshot.ModelConfigurationIdentifier, header.DynamicsConfigurationIdentifier) || + !StringComparer.Ordinal.Equals(snapshot.ModelRunIdentifier, header.DynamicsRunIdentifier)))) + { + throw Invalid($"Observation {expectedSequence} decoded signal snapshot does not match its source context."); + } + + foreach (var signal in snapshot.Signals) + { + if (!Enum.IsDefined(signal.Quality) || + !StringComparer.Ordinal.Equals(signal.ModuleIdentifier, snapshot.ModuleIdentifier) || + string.IsNullOrWhiteSpace(signal.SignalIdentifier) || + string.IsNullOrWhiteSpace(signal.Unit) || + string.IsNullOrWhiteSpace(signal.Origin) || + signal.LogicalTimeTicks < 0 || + signal.LogicalTimeTicks != observation.StartLogicalTicks || + signal.Value.ValueKind == JsonValueKind.Undefined || + (header.ProtocolVersion == 1 && + (signal.ModelStepIndex is not null || + signal.ModelTimeSeconds is not null || + signal.ModelConfigurationIdentifier is not null || + signal.ModelRunIdentifier is not null)) || + (header.ProtocolVersion == 2 && + (signal.ModelStepIndex != snapshot.ModelStepIndex || + signal.ModelTimeSeconds != snapshot.ModelTimeSeconds || + !StringComparer.Ordinal.Equals(signal.ModelConfigurationIdentifier, snapshot.ModelConfigurationIdentifier) || + !StringComparer.Ordinal.Equals(signal.ModelRunIdentifier, snapshot.ModelRunIdentifier)))) + { + throw Invalid($"Observation {expectedSequence} contains an incoherent decoded signal."); + } + } + + ValidateDecodedSignals(header, observation, snapshot); + } + + private static void ValidateRequestAssociation( + TelemetryCaptureHeader header, + TelemetryRecordedObservation observation) + { + var requestBytes = Convert.FromBase64String(observation.RequestPayloadBase64); + if (!SyntheticProtocolV1.TryDecodeRequest(requestBytes, out var request) || + request is null) + { + throw Invalid($"Observation {observation.Sequence} does not contain a valid synthetic request."); + } + + var expectedConfiguration = $"profile:{header.ProfileIdentifier}@revision:{header.ProfileRevision}"; + if (header.DynamicsConfigurationIdentifier is not null) + { + expectedConfiguration += $";dynamics:{header.DynamicsConfigurationIdentifier}"; + } + + if (request.Version != header.ProtocolVersion || + !StringComparer.Ordinal.Equals(request.SessionIdentifier, header.SessionIdentifier) || + !StringComparer.Ordinal.Equals(request.ProfileIdentifier, header.ProfileIdentifier) || + request.ProfileRevision != header.ProfileRevision || + !StringComparer.Ordinal.Equals(request.ConfigurationIdentifier, expectedConfiguration) || + !StringComparer.Ordinal.Equals(request.CorrelationIdentifier, observation.CorrelationIdentifier) || + !StringComparer.Ordinal.Equals(request.TargetAddress, observation.Address) || + !StringComparer.Ordinal.Equals(request.Service, observation.Service) || + request.LogicalTimeTicks != observation.StartLogicalTicks) + { + throw Invalid($"Observation {observation.Sequence} request bytes do not match its recorded trace identity."); + } + } + + private static void ValidateResponseAssociation( + TelemetryCaptureHeader header, + TelemetryRecordedObservation observation) + { + var responseBytes = Convert.FromBase64String(observation.ResponsePayloadBase64!); + using var document = JsonDocument.Parse(responseBytes); + var root = document.RootElement; + EnsureProperties( + root, + "version", + "sessionIdentifier", + "configurationIdentifier", + "correlationIdentifier", + "targetAddress", + "service", + "success", + "errorCode", + "error", + "data"); + var requestBytes = Convert.FromBase64String(observation.RequestPayloadBase64); + _ = SyntheticProtocolV1.TryDecodeRequest(requestBytes, out var request); + var success = observation.Outcome == DiagnosticOutcome.PositiveResponse; + var expectedConfiguration = $"profile:{header.ProfileIdentifier}@revision:{header.ProfileRevision}"; + if (header.DynamicsConfigurationIdentifier is not null) + { + expectedConfiguration += $";dynamics:{header.DynamicsConfigurationIdentifier}"; + } + + if (!root.GetProperty("version").TryGetInt32(out var responseVersion) || + responseVersion != header.ProtocolVersion || + !StringComparer.Ordinal.Equals(root.GetProperty("sessionIdentifier").GetString(), header.SessionIdentifier) || + !StringComparer.Ordinal.Equals(root.GetProperty("configurationIdentifier").GetString(), expectedConfiguration) || + !StringComparer.Ordinal.Equals(root.GetProperty("correlationIdentifier").GetString(), observation.CorrelationIdentifier) || + !StringComparer.Ordinal.Equals(root.GetProperty("targetAddress").GetString(), observation.Address) || + !StringComparer.Ordinal.Equals(root.GetProperty("service").GetString(), observation.Service) || + root.GetProperty("success").ValueKind is not (JsonValueKind.True or JsonValueKind.False) || + root.GetProperty("success").GetBoolean() != success || + request is null) + { + throw Invalid($"Observation {observation.Sequence} response bytes do not match its recorded trace identity or outcome."); + } + + var errorCode = root.GetProperty("errorCode"); + var error = root.GetProperty("error"); + var data = root.GetProperty("data"); + if (success) + { + if (errorCode.ValueKind != JsonValueKind.Null || + error.ValueKind != JsonValueKind.Null || + data.ValueKind != JsonValueKind.Object || + !data.TryGetProperty("moduleIdentifier", out var moduleIdentifier) || + moduleIdentifier.ValueKind != JsonValueKind.String || + !StringComparer.Ordinal.Equals(moduleIdentifier.GetString(), observation.ModuleIdentifier)) + { + throw Invalid($"Observation {observation.Sequence} positive response envelope or module identity is incoherent."); + } + + if (StringComparer.Ordinal.Equals(observation.Service, DiagnosticServices.ReadSignals)) + { + ValidateSignalResponse(header, observation, request, data); + } + } + else if (errorCode.ValueKind != JsonValueKind.String || + error.ValueKind != JsonValueKind.String || + data.ValueKind != JsonValueKind.Null || + !StringComparer.Ordinal.Equals(errorCode.GetString(), observation.DecodedSummary) || + !StringComparer.Ordinal.Equals(error.GetString(), observation.Error)) + { + throw Invalid($"Observation {observation.Sequence} negative response envelope is incoherent."); + } + } + + private static void ValidateSignalResponse( + TelemetryCaptureHeader header, + TelemetryRecordedObservation observation, + SyntheticDiagnosticRequest request, + JsonElement data) + { + var isV2 = header.ProtocolVersion == 2; + EnsureProperties( + data, + isV2 + ? [ + "moduleIdentifier", + "configurationIdentifier", + "runIdentifier", + "modelStepIndex", + "modelTimeSeconds", + "origin", + "captureLogicalTimeTicks", + "signals" + ] + : ["moduleIdentifier", "logicalTimeTicks", "origin", "signals"]); + if (!StringComparer.Ordinal.Equals(data.GetProperty("moduleIdentifier").GetString(), observation.ModuleIdentifier) || + !StringComparer.Ordinal.Equals(data.GetProperty("origin").GetString(), isV2 ? "SYNTHETIC_DYNAMIC" : "SYNTHETIC_STATIC")) + { + throw Invalid($"Observation {observation.Sequence} decoded signal source does not match its endpoint."); + } + + var logicalTimeProperty = isV2 ? "captureLogicalTimeTicks" : "logicalTimeTicks"; + if (!data.GetProperty(logicalTimeProperty).TryGetInt64(out var logicalTime) || + logicalTime != request.LogicalTimeTicks) + { + throw Invalid($"Observation {observation.Sequence} decoded signal time does not match its request."); + } + + var snapshot = observation.SignalSnapshot!; + if (isV2 && + (!data.GetProperty("modelStepIndex").TryGetInt64(out var stepIndex) || + stepIndex != snapshot.ModelStepIndex || + !data.GetProperty("modelTimeSeconds").TryGetDouble(out var modelTime) || + modelTime != snapshot.ModelTimeSeconds || + !StringComparer.Ordinal.Equals( + data.GetProperty("configurationIdentifier").GetString(), + snapshot.ModelConfigurationIdentifier) || + !StringComparer.Ordinal.Equals( + data.GetProperty("runIdentifier").GetString(), + snapshot.ModelRunIdentifier))) + { + throw Invalid($"Observation {observation.Sequence} decoded dynamic context does not match its response bytes."); + } + + var rawSignals = data.GetProperty("signals"); + if (rawSignals.ValueKind != JsonValueKind.Array || + rawSignals.GetArrayLength() != snapshot.Signals.Count) + { + throw Invalid($"Observation {observation.Sequence} decoded signal count does not match its response bytes."); + } + + var index = 0; + foreach (var rawSignal in rawSignals.EnumerateArray()) + { + EnsureProperties(rawSignal, "signalIdentifier", "value", "unit", "quality"); + var signal = snapshot.Signals[index++]; + if (!StringComparer.Ordinal.Equals(rawSignal.GetProperty("signalIdentifier").GetString(), signal.SignalIdentifier) || + !ValuesEqual(rawSignal.GetProperty("value"), signal.Value) || + !StringComparer.Ordinal.Equals(rawSignal.GetProperty("unit").GetString(), signal.Unit) || + !StringComparer.Ordinal.Equals(rawSignal.GetProperty("quality").GetString(), signal.Quality.ToString())) + { + throw Invalid($"Observation {observation.Sequence} decoded signal values do not match their response bytes."); + } + } + } + + private static void ValidateDecodedSignals( + TelemetryCaptureHeader header, + TelemetryRecordedObservation observation, + TelemetryRecordedSignalSnapshot snapshot) + { + if (header.ProtocolVersion == 1 && + (!StringComparer.Ordinal.Equals(snapshot.Signals.FirstOrDefault()?.Origin ?? "SYNTHETIC_STATIC", "SYNTHETIC_STATIC") || + snapshot.Signals.Any(signal => signal.Origin != "SYNTHETIC_STATIC"))) + { + throw Invalid($"Observation {observation.Sequence} static signals have incoherent origin metadata."); + } + + if (header.ProtocolVersion == 2 && + snapshot.Signals.Any(signal => signal.Origin != "SYNTHETIC_DYNAMIC")) + { + throw Invalid($"Observation {observation.Sequence} dynamic signals have incoherent origin metadata."); + } + } + + private static bool ValuesEqual(JsonElement left, JsonElement right) + { + if (left.ValueKind != right.ValueKind) + { + return false; + } + + return left.ValueKind switch + { + JsonValueKind.Object => left.EnumerateObject().Zip(right.EnumerateObject()) + .All(pair => StringComparer.Ordinal.Equals(pair.First.Name, pair.Second.Name) && + ValuesEqual(pair.First.Value, pair.Second.Value)) && + left.EnumerateObject().Count() == right.EnumerateObject().Count(), + JsonValueKind.Array => left.EnumerateArray().Zip(right.EnumerateArray()) + .All(pair => ValuesEqual(pair.First, pair.Second)) && + left.GetArrayLength() == right.GetArrayLength(), + JsonValueKind.String => StringComparer.Ordinal.Equals(left.GetString(), right.GetString()), + JsonValueKind.Number => StringComparer.Ordinal.Equals(left.GetRawText(), right.GetRawText()), + JsonValueKind.True or JsonValueKind.False or JsonValueKind.Null => true, + _ => false + }; + } + + private static void ValidateBase64(string encoded, string label) + { + var bytes = Convert.FromBase64String(encoded); + if (!StringComparer.Ordinal.Equals(Convert.ToBase64String(bytes), encoded)) + { + throw Invalid($"{label} payload is not canonical base64."); + } + } + + private static bool IsUtcTimestamp(string? value) => + value is not null && + DateTimeOffset.TryParseExact( + value, + "O", + CultureInfo.InvariantCulture, + DateTimeStyles.None, + out var parsed) && + parsed.Offset == TimeSpan.Zero; + + private static bool IsCaptureId(string? value) => + value is { Length: 32 } && + Guid.TryParseExact(value, "N", out var parsed) && + StringComparer.Ordinal.Equals(parsed.ToString("N"), value); + + private static bool IsValidEndpoint(TelemetryCaptureEndpoint endpoint) + { + try + { + _ = new DiagnosticEndpoint(endpoint.ModuleIdentifier, endpoint.Address); + return true; + } + catch (ArgumentException) + { + return false; + } + } + + private static void ValidateSchemaObjects(JsonElement root) + { + EnsureProperties(root, "schemaVersion", "header", "observations", "completion"); + if (root.GetProperty("schemaVersion").ValueKind != JsonValueKind.Number || + !root.GetProperty("schemaVersion").TryGetInt32(out var schemaVersion)) + { + throw Invalid("The telemetry archive schemaVersion must be an integer."); + } + + if (schemaVersion != SchemaVersion) + { + throw new TelemetryArchiveException( + TelemetryArchiveFailure.UnsupportedVersion, + "Only telemetry archive schema version 1 is supported."); + } + + var header = root.GetProperty("header"); + EnsureProperties( + header, + "captureId", + "sessionIdentifier", + "profileIdentifier", + "profileRevision", + "vehicleIdentifier", + "providerIdentifier", + "targetKind", + "protocolName", + "protocolVersion", + "dynamicsConfigurationIdentifier", + "dynamicsRunIdentifier", + "sourceEndpoints", + "startedAtUtc"); + EnsureEnumValue(header, "targetKind"); + foreach (var endpoint in header.GetProperty("sourceEndpoints").EnumerateArray()) + { + EnsureProperties(endpoint, "moduleIdentifier", "address"); + } + + var observations = root.GetProperty("observations"); + if (observations.ValueKind != JsonValueKind.Array) + { + throw Invalid("The observations property must be an array."); + } + + foreach (var observation in observations.EnumerateArray()) + { + EnsureProperties( + observation, + "sequence", + "captureElapsedTicks", + "moduleIdentifier", + "address", + "correlationIdentifier", + "service", + "startLogicalTicks", + "endLogicalTicks", + "outcome", + "decodedSummary", + "error", + "requestPayloadBase64", + "responsePayloadBase64", + "signalSnapshot"); + EnsureEnumValue(observation, "outcome"); + if (observation.GetProperty("signalSnapshot").ValueKind == JsonValueKind.Object) + { + var snapshot = observation.GetProperty("signalSnapshot"); + EnsureProperties( + snapshot, + "moduleIdentifier", + "signals", + "modelStepIndex", + "modelTimeSeconds", + "modelConfigurationIdentifier", + "modelRunIdentifier"); + foreach (var signal in snapshot.GetProperty("signals").EnumerateArray()) + { + EnsureProperties( + signal, + "signalIdentifier", + "moduleIdentifier", + "value", + "unit", + "quality", + "logicalTimeTicks", + "origin", + "modelStepIndex", + "modelTimeSeconds", + "modelConfigurationIdentifier", + "modelRunIdentifier"); + EnsureEnumValue(signal, "quality"); + } + } + else if (observation.GetProperty("signalSnapshot").ValueKind != JsonValueKind.Null) + { + throw Invalid("A signalSnapshot must be an object or null."); + } + } + + var completion = root.GetProperty("completion"); + EnsureProperties( + completion, + "stoppedAtUtc", + "stopReason", + "state", + "observationCount", + "observationBytes", + "error"); + EnsureEnumValue(completion, "stopReason"); + EnsureEnumValue(completion, "state"); + } + + private static void EnsureEnumValue(JsonElement element, string propertyName) + where TEnum : struct, Enum + { + var value = element.GetProperty(propertyName); + if (value.ValueKind != JsonValueKind.String) + { + throw Invalid($"Telemetry archive property '{propertyName}' is not a defined case-sensitive {typeof(TEnum).Name} value."); + } + + var wireValue = value.GetString(); + foreach (var name in Enum.GetNames()) + { + if (StringComparer.Ordinal.Equals(JsonNamingPolicy.CamelCase.ConvertName(name), wireValue)) + { + return; + } + } + + throw Invalid($"Telemetry archive property '{propertyName}' is not a defined case-sensitive {typeof(TEnum).Name} value."); + } + + private static void EnsureProperties(JsonElement element, params string[] expected) + { + if (element.ValueKind != JsonValueKind.Object) + { + throw Invalid("A telemetry archive schema object has the wrong JSON type."); + } + + var remaining = new HashSet(expected, StringComparer.Ordinal); + foreach (var property in element.EnumerateObject()) + { + if (!remaining.Remove(property.Name)) + { + throw Invalid($"Telemetry archive schema property '{property.Name}' is duplicate or unsupported."); + } + } + + if (remaining.Count != 0) + { + throw Invalid($"Telemetry archive schema property '{remaining.First()}' is required."); + } + } + + private static ArchiveDto ToArchive(TelemetryCaptureSnapshot capture) => new() + { + SchemaVersion = SchemaVersion, + Header = ToHeader(capture.Header), + Observations = capture.Observations.Select(ToObservation).ToList(), + Completion = new CompletionDto + { + StoppedAtUtc = capture.Completion!.StoppedAtUtc, + StopReason = capture.Completion.StopReason, + State = capture.Completion.State, + ObservationCount = capture.Completion.ObservationCount, + ObservationBytes = capture.Completion.ObservationBytes, + Error = capture.Completion.Error + } + }; + + private static TelemetryCaptureSnapshot FromArchive(ArchiveDto archive) + { + if (archive.Header is null || archive.Observations is null || archive.Completion is null) + { + throw Invalid("A telemetry archive required object is null."); + } + + return new TelemetryCaptureSnapshot( + FromHeader(archive.Header), + archive.Observations.Select(FromObservation), + new TelemetryCaptureCompletion( + archive.Completion.StoppedAtUtc, + archive.Completion.StopReason, + archive.Completion.State, + archive.Completion.ObservationCount, + archive.Completion.ObservationBytes, + archive.Completion.Error)); + } + + private static HeaderDto ToHeader(TelemetryCaptureHeader header) => new() + { + CaptureId = header.CaptureId, + SessionIdentifier = header.SessionIdentifier, + ProfileIdentifier = header.ProfileIdentifier, + ProfileRevision = header.ProfileRevision, + VehicleIdentifier = header.VehicleIdentifier, + ProviderIdentifier = header.ProviderIdentifier, + TargetKind = header.TargetKind, + ProtocolName = header.ProtocolName, + ProtocolVersion = header.ProtocolVersion, + DynamicsConfigurationIdentifier = header.DynamicsConfigurationIdentifier, + DynamicsRunIdentifier = header.DynamicsRunIdentifier, + SourceEndpoints = header.SourceEndpoints.Select(endpoint => new EndpointDto + { + ModuleIdentifier = endpoint.ModuleIdentifier, + Address = endpoint.Address + }).ToList(), + StartedAtUtc = header.StartedAtUtc + }; + + private static TelemetryCaptureHeader FromHeader(HeaderDto header) + { + if (header.SourceEndpoints is null) + { + throw Invalid("The telemetry archive endpoint list is null."); + } + + return new TelemetryCaptureHeader( + header.CaptureId, + header.SessionIdentifier, + header.ProfileIdentifier, + header.ProfileRevision, + header.VehicleIdentifier, + header.ProviderIdentifier, + header.TargetKind, + header.ProtocolName, + header.ProtocolVersion, + header.DynamicsConfigurationIdentifier, + header.DynamicsRunIdentifier, + Array.AsReadOnly(header.SourceEndpoints.Select(endpoint => + new TelemetryCaptureEndpoint(endpoint.ModuleIdentifier, endpoint.Address)).ToArray()), + header.StartedAtUtc); + } + + private static ObservationDto ToObservation(TelemetryRecordedObservation observation) => new() + { + Sequence = observation.Sequence, + CaptureElapsedTicks = observation.CaptureElapsedTicks, + ModuleIdentifier = observation.ModuleIdentifier, + Address = observation.Address, + CorrelationIdentifier = observation.CorrelationIdentifier, + Service = observation.Service, + StartLogicalTicks = observation.StartLogicalTicks, + EndLogicalTicks = observation.EndLogicalTicks, + Outcome = observation.Outcome, + DecodedSummary = observation.DecodedSummary, + Error = observation.Error, + RequestPayloadBase64 = observation.RequestPayloadBase64, + ResponsePayloadBase64 = observation.ResponsePayloadBase64, + SignalSnapshot = observation.SignalSnapshot is null ? null : ToSignalSnapshot(observation.SignalSnapshot) + }; + + private static TelemetryRecordedObservation FromObservation(ObservationDto observation) => + new( + observation.Sequence, + observation.CaptureElapsedTicks, + observation.ModuleIdentifier, + observation.Address, + observation.CorrelationIdentifier, + observation.Service, + observation.StartLogicalTicks, + observation.EndLogicalTicks, + observation.Outcome, + observation.DecodedSummary, + observation.Error, + observation.RequestPayloadBase64, + observation.ResponsePayloadBase64, + observation.SignalSnapshot is null ? null : FromSignalSnapshot(observation.SignalSnapshot)); + + private static SignalSnapshotDto ToSignalSnapshot(TelemetryRecordedSignalSnapshot snapshot) => new() + { + ModuleIdentifier = snapshot.ModuleIdentifier, + Signals = snapshot.Signals.Select(signal => new SignalDto + { + SignalIdentifier = signal.SignalIdentifier, + ModuleIdentifier = signal.ModuleIdentifier, + Value = signal.Value.Clone(), + Unit = signal.Unit, + Quality = signal.Quality, + LogicalTimeTicks = signal.LogicalTimeTicks, + Origin = signal.Origin, + ModelStepIndex = signal.ModelStepIndex, + ModelTimeSeconds = signal.ModelTimeSeconds, + ModelConfigurationIdentifier = signal.ModelConfigurationIdentifier, + ModelRunIdentifier = signal.ModelRunIdentifier + }).ToList(), + ModelStepIndex = snapshot.ModelStepIndex, + ModelTimeSeconds = snapshot.ModelTimeSeconds, + ModelConfigurationIdentifier = snapshot.ModelConfigurationIdentifier, + ModelRunIdentifier = snapshot.ModelRunIdentifier + }; + + private static TelemetryRecordedSignalSnapshot FromSignalSnapshot(SignalSnapshotDto snapshot) + { + if (snapshot.Signals is null) + { + throw Invalid("A decoded signal list is null."); + } + + return new TelemetryRecordedSignalSnapshot( + snapshot.ModuleIdentifier, + Array.AsReadOnly(snapshot.Signals.Select(signal => new TelemetryRecordedSignal( + signal.SignalIdentifier, + signal.ModuleIdentifier, + signal.Value.Clone(), + signal.Unit, + signal.Quality, + signal.LogicalTimeTicks, + signal.Origin, + signal.ModelStepIndex, + signal.ModelTimeSeconds, + signal.ModelConfigurationIdentifier, + signal.ModelRunIdentifier)).ToArray()), + snapshot.ModelStepIndex, + snapshot.ModelTimeSeconds, + snapshot.ModelConfigurationIdentifier, + snapshot.ModelRunIdentifier); + } + + private static JsonSerializerOptions CreateOptions() + { + var options = new JsonSerializerOptions + { + PropertyNamingPolicy = JsonNamingPolicy.CamelCase, + MaxDepth = 128 + }; + options.Converters.Add(new JsonStringEnumConverter(JsonNamingPolicy.CamelCase, allowIntegerValues: false)); + return options; + } + + private static TelemetryArchiveException Invalid(string message, Exception? inner = null) => + new(TelemetryArchiveFailure.InvalidArchive, message, inner); + + private sealed class ArchiveDto + { + public int SchemaVersion { get; set; } + public HeaderDto? Header { get; set; } + public List? Observations { get; set; } + public CompletionDto? Completion { get; set; } + } + + private sealed class HeaderDto + { + public string CaptureId { get; set; } = string.Empty; + public string SessionIdentifier { get; set; } = string.Empty; + public string ProfileIdentifier { get; set; } = string.Empty; + public int ProfileRevision { get; set; } + public string VehicleIdentifier { get; set; } = string.Empty; + public string ProviderIdentifier { get; set; } = string.Empty; + public ExecutionTargetKind TargetKind { get; set; } + public string ProtocolName { get; set; } = string.Empty; + public int ProtocolVersion { get; set; } + public string? DynamicsConfigurationIdentifier { get; set; } + public string? DynamicsRunIdentifier { get; set; } + public List? SourceEndpoints { get; set; } + public string StartedAtUtc { get; set; } = string.Empty; + } + + private sealed class EndpointDto + { + public string ModuleIdentifier { get; set; } = string.Empty; + public string Address { get; set; } = string.Empty; + } + + private sealed class ObservationDto + { + public long Sequence { get; set; } + public long CaptureElapsedTicks { get; set; } + public string ModuleIdentifier { get; set; } = string.Empty; + public string Address { get; set; } = string.Empty; + public string CorrelationIdentifier { get; set; } = string.Empty; + public string Service { get; set; } = string.Empty; + public long StartLogicalTicks { get; set; } + public long EndLogicalTicks { get; set; } + public DiagnosticOutcome Outcome { get; set; } + public string? DecodedSummary { get; set; } + public string? Error { get; set; } + public string RequestPayloadBase64 { get; set; } = string.Empty; + public string? ResponsePayloadBase64 { get; set; } + public SignalSnapshotDto? SignalSnapshot { get; set; } + } + + private sealed class SignalSnapshotDto + { + public string ModuleIdentifier { get; set; } = string.Empty; + public List? Signals { get; set; } + public long? ModelStepIndex { get; set; } + public double? ModelTimeSeconds { get; set; } + public string? ModelConfigurationIdentifier { get; set; } + public string? ModelRunIdentifier { get; set; } + } + + private sealed class SignalDto + { + public string SignalIdentifier { get; set; } = string.Empty; + public string ModuleIdentifier { get; set; } = string.Empty; + public JsonElement Value { get; set; } + public string Unit { get; set; } = string.Empty; + public SignalQuality Quality { get; set; } + public long LogicalTimeTicks { get; set; } + public string Origin { get; set; } = string.Empty; + public long? ModelStepIndex { get; set; } + public double? ModelTimeSeconds { get; set; } + public string? ModelConfigurationIdentifier { get; set; } + public string? ModelRunIdentifier { get; set; } + } + + private sealed class CompletionDto + { + public string StoppedAtUtc { get; set; } = string.Empty; + public TelemetryCaptureStopReason StopReason { get; set; } + public TelemetryCaptureState State { get; set; } + public int ObservationCount { get; set; } + public long ObservationBytes { get; set; } + public string? Error { get; set; } + } +} diff --git a/src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/TelemetryArchiveModels.cs b/src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/TelemetryArchiveModels.cs new file mode 100644 index 0000000..e2bcc3c --- /dev/null +++ b/src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/TelemetryArchiveModels.cs @@ -0,0 +1,166 @@ +using System.Text.Json; +using AutoForge.Core.ExecutionTargets; +using AutoForge.Diagnostics; + +namespace AutoForge.Application.Features.Vehicles.Telemetry.Recording; + +public enum TelemetryCaptureState +{ + Recording, + Complete, + Incomplete, + Error +} + +public enum TelemetryCaptureStopReason +{ + User, + SourceClosed, + LimitExceeded, + ObservationFailure +} + +public sealed record TelemetryCaptureLimits( + int MaximumObservations, + long MaximumObservationBytes, + int MaximumHeaderBytes, + int MaximumArchiveBytes) +{ + public static TelemetryCaptureLimits Default { get; } = new( + 4096, + 16L * 1024 * 1024, + 1024 * 1024, + 32 * 1024 * 1024); +} + +public sealed record TelemetryCaptureEndpoint(string ModuleIdentifier, string Address); + +public sealed record TelemetryCaptureHeader( + string CaptureId, + string SessionIdentifier, + string ProfileIdentifier, + int ProfileRevision, + string VehicleIdentifier, + string ProviderIdentifier, + ExecutionTargetKind TargetKind, + string ProtocolName, + int ProtocolVersion, + string? DynamicsConfigurationIdentifier, + string? DynamicsRunIdentifier, + IReadOnlyList SourceEndpoints, + string StartedAtUtc); + +public sealed record TelemetryRecordedSignal( + string SignalIdentifier, + string ModuleIdentifier, + JsonElement Value, + string Unit, + SignalQuality Quality, + long LogicalTimeTicks, + string Origin, + long? ModelStepIndex, + double? ModelTimeSeconds, + string? ModelConfigurationIdentifier, + string? ModelRunIdentifier); + +public sealed record TelemetryRecordedSignalSnapshot( + string ModuleIdentifier, + IReadOnlyList Signals, + long? ModelStepIndex, + double? ModelTimeSeconds, + string? ModelConfigurationIdentifier, + string? ModelRunIdentifier); + +public sealed record TelemetryRecordedObservation( + long Sequence, + long CaptureElapsedTicks, + string ModuleIdentifier, + string Address, + string CorrelationIdentifier, + string Service, + long StartLogicalTicks, + long EndLogicalTicks, + DiagnosticOutcome Outcome, + string? DecodedSummary, + string? Error, + string RequestPayloadBase64, + string? ResponsePayloadBase64, + TelemetryRecordedSignalSnapshot? SignalSnapshot); + +public sealed record TelemetryCaptureCompletion( + string StoppedAtUtc, + TelemetryCaptureStopReason StopReason, + TelemetryCaptureState State, + int ObservationCount, + long ObservationBytes, + string? Error); + +public sealed class TelemetryCaptureSnapshot +{ + public TelemetryCaptureSnapshot( + TelemetryCaptureHeader header, + IEnumerable observations, + TelemetryCaptureCompletion? completion, + bool isSaved = false) + { + ArgumentNullException.ThrowIfNull(header); + ArgumentNullException.ThrowIfNull(observations); + ArgumentNullException.ThrowIfNull(header.SourceEndpoints); + Header = header with + { + SourceEndpoints = Array.AsReadOnly(header.SourceEndpoints.ToArray()) + }; + Observations = Array.AsReadOnly(observations.Select(CloneObservation).ToArray()); + Completion = completion; + IsSaved = isSaved; + } + + public TelemetryCaptureHeader Header { get; } + public IReadOnlyList Observations { get; } + public TelemetryCaptureCompletion? Completion { get; } + public bool IsSaved { get; } + public bool IsRecording => Completion is null; + public bool IsComplete => Completion?.State == TelemetryCaptureState.Complete; + + private static TelemetryRecordedObservation CloneObservation(TelemetryRecordedObservation observation) + { + ArgumentNullException.ThrowIfNull(observation); + var snapshot = observation.SignalSnapshot; + var clonedSnapshot = snapshot is null + ? null + : snapshot with + { + Signals = Array.AsReadOnly(snapshot.Signals.Select(signal => + signal with { Value = signal.Value.Clone() }).ToArray()) + }; + return observation with { SignalSnapshot = clonedSnapshot }; + } +} + +public sealed record TelemetrySavedCapture( + string CaptureId, + string SessionIdentifier, + string ProfileIdentifier, + DateTimeOffset StartedAtUtc, + TelemetryCaptureState State, + int ObservationCount); + +public enum TelemetryArchiveFailure +{ + InvalidArchive, + UnsupportedVersion, + LimitExceeded, + InvalidCaptureId, + Collision, + ReadFailure, + WriteFailure, + Cancelled +} + +public sealed class TelemetryArchiveException( + TelemetryArchiveFailure failure, + string message, + Exception? innerException = null) : Exception(message, innerException) +{ + public TelemetryArchiveFailure Failure { get; } = failure; +} diff --git a/src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/TelemetryRecordingServiceCollectionExtensions.cs b/src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/TelemetryRecordingServiceCollectionExtensions.cs new file mode 100644 index 0000000..1729fa4 --- /dev/null +++ b/src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/TelemetryRecordingServiceCollectionExtensions.cs @@ -0,0 +1,46 @@ +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.DependencyInjection.Extensions; + +namespace AutoForge.Application.Features.Vehicles.Telemetry.Recording; + +public static class TelemetryRecordingServiceCollectionExtensions +{ + public static IServiceCollection AddAutoForgeTelemetryRecording( + this IServiceCollection services, + string recordingsDirectory) + { + ArgumentNullException.ThrowIfNull(services); + ArgumentException.ThrowIfNullOrWhiteSpace(recordingsDirectory); + services.AddSingleton(new FileTelemetryArchiveStore(recordingsDirectory)); + services.TryAddSingleton(TimeProvider.System); + return services; + } + + public static IServiceCollection AddAutoForgeTelemetryRecordingFallback( + this IServiceCollection services) + { + services.TryAddSingleton(); + services.TryAddSingleton(TimeProvider.System); + services.TryAddSingleton(TelemetryCaptureLimits.Default); + services.TryAddSingleton(); + return services; + } +} + +public sealed class UnavailableTelemetryArchiveStore : ITelemetryArchiveStore +{ + public Task SaveAsync(TelemetryCaptureSnapshot capture, CancellationToken cancellationToken = default) => + Task.FromException(new TelemetryArchiveException( + TelemetryArchiveFailure.WriteFailure, + "No local telemetry archive store is configured for this application composition.")); + + public Task> ListAsync(CancellationToken cancellationToken = default) => + Task.FromException>(new TelemetryArchiveException( + TelemetryArchiveFailure.ReadFailure, + "No local telemetry archive store is configured for this application composition.")); + + public Task LoadAsync(string captureId, CancellationToken cancellationToken = default) => + Task.FromException(new TelemetryArchiveException( + TelemetryArchiveFailure.ReadFailure, + "No local telemetry archive store is configured for this application composition.")); +} diff --git a/src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/TelemetryRecordingWorkspace.cs b/src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/TelemetryRecordingWorkspace.cs new file mode 100644 index 0000000..4f3a2a4 --- /dev/null +++ b/src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/TelemetryRecordingWorkspace.cs @@ -0,0 +1,435 @@ +namespace AutoForge.Application.Features.Vehicles.Telemetry.Recording; + +public sealed class TelemetryRecordingWorkspace( + ITelemetryArchiveStore archiveStore, + TimeProvider timeProvider, + TelemetryCaptureLimits? limits = null) +{ + private readonly object _gate = new(); + private readonly TelemetryCaptureLimits _limits = limits ?? TelemetryCaptureLimits.Default; + private SessionTelemetryCapture? _owner; + private TelemetryCaptureSnapshot? _loadedCapture; + private IReadOnlyList _savedCaptures = Array.Empty(); + private bool _busy; + private bool _stopping; + private long _generation; + + public event Action? Changed; + + public TelemetryCaptureSnapshot? CurrentCapture + { + get + { + lock (_gate) + { + return _owner?.Snapshot ?? _loadedCapture; + } + } + } + + public IReadOnlyList SavedCaptures + { + get + { + lock (_gate) + { + return _savedCaptures; + } + } + } + + public bool IsBusy + { + get + { + lock (_gate) + { + return _busy; + } + } + } + + public bool IsStopping + { + get + { + lock (_gate) + { + return _stopping; + } + } + } + + public string? Error { get; private set; } + public string Status { get; private set; } = "Capture remains in memory until explicitly stopped and saved."; + + public void Start(AutoForge.Application.Features.Vehicles.Diagnostics.DiagnosticSession session) + { + ArgumentNullException.ThrowIfNull(session); + var alreadyRecording = false; + SessionTelemetryCapture? previousOwner = null; + lock (_gate) + { + EnsureNotBusy(); + if (_stopping || _owner?.IsStopping == true) + { + throw new InvalidOperationException("The current capture is draining accepted observations; Start was rejected without changing it."); + } + + var current = _owner?.Snapshot ?? _loadedCapture; + if (current?.IsRecording == true && + StringComparer.Ordinal.Equals(current.Header.SessionIdentifier, session.Identity.SessionIdentifier)) + { + Status = "Recording is already active for this session."; + Error = null; + alreadyRecording = true; + } + else if (current is { IsSaved: false }) + { + throw new InvalidOperationException("Save or explicitly discard the existing unsaved capture before starting another."); + } + else if (!alreadyRecording) + { + previousOwner = _owner; + var owner = SessionTelemetryCapture.Start(session, timeProvider, _limits); + owner.Changed += OnOwnerChanged; + _owner = owner; + _loadedCapture = null; + _generation++; + Error = null; + Status = "Recording diagnostic operations in memory; no archive has been saved."; + } + } + + if (alreadyRecording) + { + NotifyChanged(); + return; + } + + if (previousOwner is not null) + { + previousOwner.Changed -= OnOwnerChanged; + _ = previousOwner.DisposeAsync(); + } + + NotifyChanged(); + } + + public void Stop() + { + SessionTelemetryCapture? owner; + lock (_gate) + { + EnsureNotBusy(); + owner = _owner; + if (owner is null) + { + throw new InvalidOperationException("There is no active capture to stop."); + } + + if (_stopping) + { + throw new InvalidOperationException("The current capture is already draining accepted observations."); + } + + _stopping = true; + Status = "Stopping recording and draining observations already in progress..."; + } + + NotifyChanged(); + try + { + owner.Stop(); + lock (_gate) + { + var capture = owner.Snapshot; + Status = capture.Completion?.State == TelemetryCaptureState.Complete + ? "Capture stopped. It remains in memory and is not saved." + : capture.Completion?.Error ?? "Capture stopped with an explicit incomplete state."; + Error = capture.Completion?.State == TelemetryCaptureState.Error + ? capture.Completion.Error + : null; + } + } + finally + { + lock (_gate) + { + _stopping = false; + } + + NotifyChanged(); + } + } + + public void Discard() + { + SessionTelemetryCapture? owner; + lock (_gate) + { + EnsureNotBusy(); + var current = _owner?.Snapshot ?? _loadedCapture; + if (current is null || current.IsRecording) + { + throw new InvalidOperationException("Stop an active recording before discarding its in-memory capture."); + } + + if (current.IsSaved) + { + throw new InvalidOperationException("A saved archive cannot be deleted with in-memory Discard."); + } + + owner = _owner; + _owner = null; + _loadedCapture = null; + _generation++; + Error = null; + Status = "The unsaved in-memory capture was discarded. Saved archives were not changed."; + } + + if (owner is not null) + { + owner.Changed -= OnOwnerChanged; + _ = owner.DisposeAsync(); + } + + NotifyChanged(); + } + + public async Task SaveAsync(bool savePartial, CancellationToken cancellationToken = default) + { + TelemetryCaptureSnapshot capture; + SessionTelemetryCapture? owner; + long generation; + lock (_gate) + { + EnsureNotBusy(); + owner = _owner; + capture = owner?.Snapshot ?? _loadedCapture + ?? throw new InvalidOperationException("There is no stopped capture to save."); + if (capture.IsRecording) + { + throw new InvalidOperationException("Stop the capture before saving it."); + } + + if (capture.IsSaved) + { + throw new InvalidOperationException("This capture is already saved."); + } + + if (capture.Completion!.State != TelemetryCaptureState.Complete && !savePartial) + { + throw new InvalidOperationException("This capture is incomplete; use the explicit Save partial capture action."); + } + + _busy = true; + generation = _generation; + Error = null; + Status = savePartial + ? "Saving the retained partial capture..." + : "Saving the stopped capture..."; + } + + NotifyChanged(); + try + { + await archiveStore.SaveAsync(capture, cancellationToken).ConfigureAwait(false); + lock (_gate) + { + if (generation != _generation || + !StringComparer.Ordinal.Equals(CurrentCapture?.Header.CaptureId, capture.Header.CaptureId)) + { + throw new InvalidOperationException("The capture changed while its save was completing."); + } + + if (owner is null) + { + _loadedCapture = new TelemetryCaptureSnapshot( + capture.Header, + capture.Observations, + capture.Completion, + isSaved: true); + } + } + + owner?.MarkSaved(); + lock (_gate) + { + Status = capture.Completion!.State == TelemetryCaptureState.Complete + ? $"Capture {capture.Header.CaptureId} was saved locally." + : $"Partial capture {capture.Header.CaptureId} was saved locally with an explicit incomplete state."; + Error = null; + } + } + catch (TelemetryArchiveException exception) + { + lock (_gate) + { + Error = exception.Message; + Status = "The capture remains in memory and was not marked saved."; + } + } + finally + { + lock (_gate) + { + _busy = false; + } + + NotifyChanged(); + } + } + + public async Task RefreshAsync(CancellationToken cancellationToken = default) + { + long generation; + lock (_gate) + { + EnsureNotBusy(); + _busy = true; + generation = _generation; + Error = null; + Status = "Reading and validating local archive files..."; + } + + NotifyChanged(); + try + { + var captures = await archiveStore.ListAsync(cancellationToken).ConfigureAwait(false); + lock (_gate) + { + if (generation == _generation) + { + _savedCaptures = Array.AsReadOnly(captures.ToArray()); + Status = $"Validated {_savedCaptures.Count} local archive(s)."; + } + } + } + catch (TelemetryArchiveException exception) + { + lock (_gate) + { + Error = exception.Message; + Status = "Local archives could not be listed and validated."; + } + } + finally + { + lock (_gate) + { + _busy = false; + } + + NotifyChanged(); + } + } + + public async Task LoadAsync(string captureId, CancellationToken cancellationToken = default) + { + long generation; + SessionTelemetryCapture? previousOwner; + lock (_gate) + { + EnsureNotBusy(); + var current = _owner?.Snapshot ?? _loadedCapture; + if (current is { IsSaved: false }) + { + throw new InvalidOperationException("Save or explicitly discard the current unsaved capture before loading an archive."); + } + + _busy = true; + generation = _generation; + previousOwner = _owner; + Error = null; + Status = $"Loading and validating capture {captureId}..."; + } + + NotifyChanged(); + try + { + var capture = await archiveStore.LoadAsync(captureId, cancellationToken).ConfigureAwait(false); + lock (_gate) + { + if (generation == _generation) + { + _owner = null; + _loadedCapture = capture; + Status = $"Loaded saved capture {captureId}. This archive is not live data or playback."; + } + } + + if (previousOwner is not null) + { + previousOwner.Changed -= OnOwnerChanged; + _ = previousOwner.DisposeAsync(); + } + } + catch (TelemetryArchiveException exception) + { + lock (_gate) + { + Error = exception.Message; + Status = "The selected archive was rejected; the current inspection remains unchanged."; + } + } + finally + { + lock (_gate) + { + _busy = false; + } + + NotifyChanged(); + } + } + + public void CloseInspection() + { + lock (_gate) + { + EnsureNotBusy(); + if ((_owner?.Snapshot ?? _loadedCapture) is { IsSaved: false }) + { + throw new InvalidOperationException("Save or explicitly discard the unsaved capture before closing its inspection."); + } + + _owner = null; + _loadedCapture = null; + _generation++; + Status = "Archive inspection closed. Saved files remain unchanged."; + Error = null; + } + + NotifyChanged(); + } + + private void OnOwnerChanged() + { + lock (_gate) + { + var capture = _owner?.Snapshot; + if (capture?.Completion?.State == TelemetryCaptureState.Incomplete) + { + Status = capture.Completion.Error ?? "Capture is incomplete."; + } + else if (capture?.Completion?.State == TelemetryCaptureState.Error) + { + Error = capture.Completion.Error; + Status = "Capture stopped after a recording error."; + } + } + + NotifyChanged(); + } + + private void EnsureNotBusy() + { + if (_busy) + { + throw new InvalidOperationException("Another archive command is pending; the current capture was not changed."); + } + } + + private void NotifyChanged() => Changed?.Invoke(); +} diff --git a/src/AutoForge.Client/MauiProgram.cs b/src/AutoForge.Client/MauiProgram.cs index 32b1631..e3b1bf5 100644 --- a/src/AutoForge.Client/MauiProgram.cs +++ b/src/AutoForge.Client/MauiProgram.cs @@ -4,6 +4,7 @@ using AutoForge.Application.Features.Vehicles.Profiles; using AutoForge.Application.Features.Vehicles.Simulation; using AutoForge.Application.Features.Vehicles.Diagnostics; using AutoForge.Application.Features.DisplayUnits; +using AutoForge.Application.Features.Vehicles.Telemetry.Recording; using AutoForge.Client.DisplayUnits; using AutoForge.Simulation; using AutoForge.UI; @@ -27,6 +28,8 @@ public static class MauiProgram ]); builder.Services.AddAutoForgeDynamicsConfigurations(); builder.Services.AddSingleton(); + builder.Services.AddAutoForgeTelemetryRecording( + Path.Combine(FileSystem.AppDataDirectory, "recordings")); builder.Services.AddAutoForgeUi(); builder.Services.AddMauiBlazorWebView(); diff --git a/src/AutoForge.Diagnostics/ProviderContracts.cs b/src/AutoForge.Diagnostics/ProviderContracts.cs index 08271bc..fb32605 100644 --- a/src/AutoForge.Diagnostics/ProviderContracts.cs +++ b/src/AutoForge.Diagnostics/ProviderContracts.cs @@ -494,6 +494,35 @@ public sealed class DiagnosticTraceSnapshot public long DroppedRecordCount { get; } } +public sealed class DiagnosticOperationObservation +{ + public DiagnosticOperationObservation( + DiagnosticTraceEntry trace, + SignalSnapshot? signalSnapshot) + { + Trace = trace ?? throw new ArgumentNullException(nameof(trace)); + SignalSnapshot = signalSnapshot is null + ? null + : new SignalSnapshot( + signalSnapshot.ModuleIdentifier, + signalSnapshot.Signals.Select(signal => signal with { Value = signal.Value.Clone() }), + signalSnapshot.ModelStepIndex, + signalSnapshot.ModelTimeSeconds, + signalSnapshot.ModelConfigurationIdentifier, + signalSnapshot.ModelRunIdentifier); + } + + public DiagnosticTraceEntry Trace { get; } + public SignalSnapshot? SignalSnapshot { get; } +} + +public interface IDiagnosticOperationObservationSource +{ + int ProtocolVersion { get; } + string? ObservationDispatchError { get; } + IDisposable Subscribe(Action observer); +} + public sealed class DiagnosticTraceBuffer { private readonly object _gate = new(); diff --git a/src/AutoForge.Diagnostics/SyntheticDiagnosticProtocolClient.cs b/src/AutoForge.Diagnostics/SyntheticDiagnosticProtocolClient.cs index 9b63da9..da68366 100644 --- a/src/AutoForge.Diagnostics/SyntheticDiagnosticProtocolClient.cs +++ b/src/AutoForge.Diagnostics/SyntheticDiagnosticProtocolClient.cs @@ -4,7 +4,9 @@ using AutoForge.Core.Vehicles; namespace AutoForge.Diagnostics; -public sealed class SyntheticDiagnosticProtocolClient : IDiagnosticProtocolClient +public sealed class SyntheticDiagnosticProtocolClient : + IDiagnosticProtocolClient, + IDiagnosticOperationObservationSource { private const long DefaultTimeoutTicks = 5; private static readonly IReadOnlyDictionary DynamicSignalShape = @@ -33,7 +35,10 @@ public sealed class SyntheticDiagnosticProtocolClient : IDiagnosticProtocolClien private readonly int _protocolVersion; private readonly DynamicsConfiguration? _dynamicsConfiguration; private readonly SemaphoreSlim _exchangeGate = new(1, 1); + private readonly object _observersGate = new(); + private readonly Dictionary> _observers = []; private long _correlationSequence; + private long _observerSequence; public SyntheticDiagnosticProtocolClient( VehicleProfile profile, @@ -76,8 +81,22 @@ public sealed class SyntheticDiagnosticProtocolClient : IDiagnosticProtocolClien } public DiagnosticSessionIdentity Session { get; } + public int ProtocolVersion => _protocolVersion; public IReadOnlyList ExpectedEndpoints { get; } public DiagnosticTraceSnapshot Trace => _trace.Snapshot(); + public string? ObservationDispatchError { get; private set; } + + public IDisposable Subscribe(Action observer) + { + ArgumentNullException.ThrowIfNull(observer); + var id = Interlocked.Increment(ref _observerSequence); + lock (_observersGate) + { + _observers.Add(id, observer); + } + + return new ObservationSubscription(this, id); + } public async Task DiscoverAsync(CancellationToken cancellationToken = default) { @@ -462,7 +481,18 @@ public sealed class SyntheticDiagnosticProtocolClient : IDiagnosticProtocolClien var data = Required(root, "data"); var value = decode(data, request); - AddTrace(endpoint, correlation, service, startTicks, _clock.Ticks, requestPayload, responsePayload, DiagnosticOutcome.PositiveResponse, Summarize(value), null); + AddTrace( + endpoint, + correlation, + service, + startTicks, + _clock.Ticks, + requestPayload, + responsePayload, + DiagnosticOutcome.PositiveResponse, + Summarize(value), + null, + value as SignalSnapshot); return DiagnosticOperationResult.Success(value); } catch (JsonException) @@ -578,8 +608,10 @@ public sealed class SyntheticDiagnosticProtocolClient : IDiagnosticProtocolClien ReadOnlyMemory response, DiagnosticOutcome outcome, string? summary, - string? error) => - _trace.Add(new DiagnosticTraceEntry( + string? error, + SignalSnapshot? signalSnapshot = null) + { + var entry = new DiagnosticTraceEntry( Session, endpoint.ModuleIdentifier, endpoint.Address, @@ -591,7 +623,55 @@ public sealed class SyntheticDiagnosticProtocolClient : IDiagnosticProtocolClien response, outcome, summary, - error)); + error); + _trace.Add(entry); + + if (service != DiagnosticServices.ReadSignals || + outcome != DiagnosticOutcome.PositiveResponse || + signalSnapshot is null) + { + signalSnapshot = null; + } + + var observation = new DiagnosticOperationObservation(entry, signalSnapshot); + lock (_observersGate) + { + foreach (var observer in _observers.Values.ToArray()) + { + try + { + observer(observation); + } + catch (Exception exception) + { + ObservationDispatchError = $"A diagnostic observation subscriber failed: {exception.Message}"; + } + } + } + } + + private void Unsubscribe(long id) + { + lock (_observersGate) + { + _observers.Remove(id); + } + } + + private sealed class ObservationSubscription( + SyntheticDiagnosticProtocolClient owner, + long id) : IDisposable + { + private int _disposed; + + public void Dispose() + { + if (Interlocked.Exchange(ref _disposed, 1) == 0) + { + owner.Unsubscribe(id); + } + } + } private static string Summarize(T value) => value switch { diff --git a/src/AutoForge.UI/Features/Foundation/AddAutoForgeUi.cs b/src/AutoForge.UI/Features/Foundation/AddAutoForgeUi.cs index a9ba924..c9b78ec 100644 --- a/src/AutoForge.UI/Features/Foundation/AddAutoForgeUi.cs +++ b/src/AutoForge.UI/Features/Foundation/AddAutoForgeUi.cs @@ -4,6 +4,7 @@ using AutoForge.UI.Features.Vehicles.Profiles; using AutoForge.UI.Features.Vehicles.Simulation; using AutoForge.Application.Features.Vehicles.Simulation; using AutoForge.Application.Features.Vehicles.Telemetry.LiveDashboard; +using AutoForge.Application.Features.Vehicles.Telemetry.Recording; using AutoForge.Application.Features.DisplayUnits; using Microsoft.Extensions.DependencyInjection; @@ -18,6 +19,7 @@ public static class ServiceCollectionExtensions services.AddAutoForgeDynamicsConfigurations(); services.AddAutoForgeLiveDashboard(); services.AddAutoForgeDisplayUnits(); + services.AddAutoForgeTelemetryRecordingFallback(); services.AddScoped(); services.AddScoped(); services.AddScoped(); diff --git a/src/AutoForge.UI/Features/Vehicles/Diagnostics/DiagnosticsPage.razor b/src/AutoForge.UI/Features/Vehicles/Diagnostics/DiagnosticsPage.razor index 4b798a9..28663f1 100644 --- a/src/AutoForge.UI/Features/Vehicles/Diagnostics/DiagnosticsPage.razor +++ b/src/AutoForge.UI/Features/Vehicles/Diagnostics/DiagnosticsPage.razor @@ -286,6 +286,9 @@ } + + + @code { [CascadingParameter] public DisplayUnitSelection DisplaySelection { get; set; } = DisplayUnitSelection.Default; diff --git a/src/AutoForge.UI/Features/Vehicles/Simulation/SimulationPage.razor b/src/AutoForge.UI/Features/Vehicles/Simulation/SimulationPage.razor index 333e428..5043423 100644 --- a/src/AutoForge.UI/Features/Vehicles/Simulation/SimulationPage.razor +++ b/src/AutoForge.UI/Features/Vehicles/Simulation/SimulationPage.razor @@ -212,6 +212,8 @@ } + +

The model is deliberately synthetic and does not provide manufacturer-validated performance, safe tuning guidance, or physical operations.

@code { diff --git a/src/AutoForge.UI/Features/Vehicles/Telemetry/Recording/TelemetryRecordingPanel.razor b/src/AutoForge.UI/Features/Vehicles/Telemetry/Recording/TelemetryRecordingPanel.razor new file mode 100644 index 0000000..433d0ed --- /dev/null +++ b/src/AutoForge.UI/Features/Vehicles/Telemetry/Recording/TelemetryRecordingPanel.razor @@ -0,0 +1,326 @@ +@implements IDisposable +@inject TelemetryRecordingWorkspace Recording + +
+

Telemetry recording and archive inspection

+

+ Captures validated diagnostic operations in memory only. Data remains local and source-sensitive; + nothing is uploaded. Recording is not durable until an explicit save after Stop. This is not playback. +

+ @if (_interactionError is not null || Recording.Error is not null) + { +

@(_interactionError ?? Recording.Error)

+ } + @if (Session?.ObservationDispatchError is { } observationDispatchError) + { +

@observationDispatchError

+ } +

@Recording.Status

+ + @if (Session is { IsClosed: false } session) + { + + } + else + { +

Open an explicit diagnostic session to start recording.

+ } + + @if (Recording.CurrentCapture is { } capture) + { + var completion = capture.Completion; +
+
Capture ID
+
@capture.Header.CaptureId
+
Source session / profile
+
@capture.Header.SessionIdentifier / @capture.Header.ProfileIdentifier revision @capture.Header.ProfileRevision
+
Vehicle / provider / target
+
@capture.Header.VehicleIdentifier / @capture.Header.ProviderIdentifier (@capture.Header.TargetKind)
+
Protocol / dynamics configuration and run
+
@capture.Header.ProtocolName v@(capture.Header.ProtocolVersion) / @(capture.Header.DynamicsConfigurationIdentifier ?? "null") / @(capture.Header.DynamicsRunIdentifier ?? "null")
+
Capture state
+
@(completion is null ? "Recording" : completion.State)
+
Observations and encoded observation bytes
+
@capture.Observations.Count / @(completion?.ObservationBytes ?? GetCurrentObservationBytes(capture)) bytes
+
Fixed limits
+
4,096 observations; 16,777,216 observation bytes; 1,048,576 header bytes; 33,554,432 archive bytes
+
Start UTC / stop UTC
+
@capture.Header.StartedAtUtc / @(completion?.StoppedAtUtc ?? "not stopped")
+
Stop reason / completion
+
@(completion is null ? "not stopped" : $"{completion.StopReason} / {completion.State}")
+
Saved status
+
@(capture.IsSaved ? "Saved locally" : "Unsaved in-memory capture")
+
+ + @if (completion is not null) + { + + @if (!capture.IsSaved) + { + + + } + else + { + + } + } + else + { + + } + + @if (capture.Observations.Count == 0) + { +

No diagnostic operations were observed during this capture window.

+ } + else + { + + + + @if (SelectedObservation(capture) is { } observation) + { +
+
Sequence / endpoint / service
+
@observation.Sequence / @observation.ModuleIdentifier at 0x@(observation.Address) / @observation.Service
+
Correlation / outcome / error
+
@observation.CorrelationIdentifier / @observation.Outcome / @(observation.Error ?? "null")
+
Capture elapsed time
+
@observation.CaptureElapsedTicks ticks since Start
+
Diagnostic logical ticks
+
@observation.StartLogicalTicks–@observation.EndLogicalTicks
+ @if (observation.SignalSnapshot is { } signalSnapshot) + { +
Decoded signal snapshot context
+
+ @signalSnapshot.ModuleIdentifier; model step @(signalSnapshot.ModelStepIndex?.ToString() ?? "null"); + model time @(signalSnapshot.ModelTimeSeconds?.ToString("R", CultureInfo.InvariantCulture) ?? "null"); + configuration @(signalSnapshot.ModelConfigurationIdentifier ?? "null"); + run @(signalSnapshot.ModelRunIdentifier ?? "null") +
+ } + else + { +
Decoded signal snapshot
+
null (no successful read.signals result was attached)
+ } +
+ +
+ Raw request and response bytes +

Base64 is the reversible archive representation of the exact source bytes.

+

Request bytes

+
@observation.RequestPayloadBase64
+ @if (observation.ResponsePayloadBase64 is { } response) + { +

Response bytes

+
@response
+ } + else + { +

No response bytes were received.

+ } +
+ + @if (observation.SignalSnapshot is { } signals) + { +
+ Decoded source signals (@signals.Signals.Count) + @foreach (var signal in signals.Signals) + { +
+
@signal.ModuleIdentifier / @signal.SignalIdentifier
+
+ Source value @signal.Value.GetRawText() @signal.Unit; quality @signal.Quality; + diagnostic ticks @signal.LogicalTimeTicks; origin @signal.Origin; + model step @(signal.ModelStepIndex?.ToString() ?? "null"); + model time @(signal.ModelTimeSeconds?.ToString("R", CultureInfo.InvariantCulture) ?? "null"); + configuration @(signal.ModelConfigurationIdentifier ?? "null"); + run @(signal.ModelRunIdentifier ?? "null") +
+
+ } +
+ } + } + } + } + +

Saved local captures

+ + @if (Recording.SavedCaptures.Count == 0) + { +

No validated saved captures are available.

+ } + else + { + + + } +

Archive readback establishes file consistency only; it is not cryptographic authenticity, current vehicle state, or manufacturer truth.

+
+ +@code { + [Parameter] + public DiagnosticSession? Session { get; set; } + + private string? SelectedSequence { get; set; } + private string? SelectedArchiveId { get; set; } + private string? _interactionError; + + protected override async Task OnInitializedAsync() + { + Recording.Changed += OnRecordingChanged; + await Recording.RefreshAsync(); + } + + private static long GetCurrentObservationBytes(TelemetryCaptureSnapshot capture) => + capture.Observations.Sum(observation => (long)TelemetryArchiveCodec.GetEncodedObservationLength(observation)); + + private TelemetryRecordedObservation? SelectedObservation(TelemetryCaptureSnapshot capture) + { + if (!long.TryParse(SelectedSequence, NumberStyles.None, CultureInfo.InvariantCulture, out var sequence)) + { + return capture.Observations.LastOrDefault(); + } + + return capture.Observations.FirstOrDefault(observation => observation.Sequence == sequence) + ?? capture.Observations.LastOrDefault(); + } + + private void SelectObservation(ChangeEventArgs args) => + SelectedSequence = args.Value?.ToString(); + + private async Task StartAsync(DiagnosticSession session) + { + try + { + Recording.Start(session); + _interactionError = null; + } + catch (Exception exception) when (exception is InvalidOperationException or TelemetryArchiveException) + { + _interactionError = exception.Message; + } + + await InvokeAsync(StateHasChanged); + } + + private void Stop() + { + try + { + Recording.Stop(); + _interactionError = null; + } + catch (InvalidOperationException exception) + { + _interactionError = exception.Message; + } + } + + private async Task SaveAsync(bool savePartial) + { + try + { + await Recording.SaveAsync(savePartial); + _interactionError = null; + await Recording.RefreshAsync(); + } + catch (InvalidOperationException exception) + { + _interactionError = exception.Message; + } + } + + private void Discard() + { + try + { + Recording.Discard(); + SelectedSequence = null; + _interactionError = null; + } + catch (InvalidOperationException exception) + { + _interactionError = exception.Message; + } + } + + private async Task RefreshAsync() + { + await Recording.RefreshAsync(); + _interactionError = null; + } + + private async Task LoadSelectedAsync(ChangeEventArgs args) + { + SelectedArchiveId = args.Value?.ToString(); + if (!string.IsNullOrEmpty(SelectedArchiveId)) + { + try + { + await Recording.LoadAsync(SelectedArchiveId); + SelectedSequence = null; + _interactionError = null; + } + catch (InvalidOperationException exception) + { + _interactionError = exception.Message; + } + } + } + + private void CloseInspection() + { + try + { + Recording.CloseInspection(); + SelectedSequence = null; + SelectedArchiveId = null; + _interactionError = null; + } + catch (InvalidOperationException exception) + { + _interactionError = exception.Message; + } + } + + private void OnRecordingChanged() => _ = InvokeAsync(StateHasChanged); + + public void Dispose() => Recording.Changed -= OnRecordingChanged; +} diff --git a/src/AutoForge.UI/_Imports.razor b/src/AutoForge.UI/_Imports.razor index 23b1bec..0a71c19 100644 --- a/src/AutoForge.UI/_Imports.razor +++ b/src/AutoForge.UI/_Imports.razor @@ -5,8 +5,10 @@ @using AutoForge.Components @using AutoForge.Application.Features.Vehicles.Diagnostics @using AutoForge.Application.Features.Vehicles.Telemetry.LiveDashboard +@using AutoForge.Application.Features.Vehicles.Telemetry.Recording @using AutoForge.Application.Features.DisplayUnits @using AutoForge.UI.Features.Vehicles.Telemetry.LiveDashboard +@using AutoForge.UI.Features.Vehicles.Telemetry.Recording @using AutoForge.Core.ExecutionTargets @using AutoForge.Diagnostics @using AutoForge.UI.Features.Foundation diff --git a/src/tests/AutoForge.IntegrationTests/TelemetryRecordingIntegrationTests.cs b/src/tests/AutoForge.IntegrationTests/TelemetryRecordingIntegrationTests.cs new file mode 100644 index 0000000..816f9cb --- /dev/null +++ b/src/tests/AutoForge.IntegrationTests/TelemetryRecordingIntegrationTests.cs @@ -0,0 +1,1156 @@ +using System.Text; +using System.Text.Json; +using System.Text.Json.Nodes; +using AutoForge.Application.Features.DisplayUnits; +using AutoForge.Application.Features.Vehicles.Diagnostics; +using AutoForge.Application.Features.Vehicles.Profiles; +using AutoForge.Application.Features.Vehicles.Simulation; +using AutoForge.Application.Features.Vehicles.Telemetry.Recording; +using AutoForge.Core.ExecutionTargets; +using AutoForge.Core.Simulation; +using AutoForge.Diagnostics; +using AutoForge.Simulation; +using AutoForge.UI; +using AutoForge.UI.Features.Vehicles.Diagnostics; +using AutoForge.UI.Features.Vehicles.Simulation; +using AutoForge.UI.Features.Vehicles.Telemetry.Recording; +using Microsoft.AspNetCore.Components; +using Microsoft.AspNetCore.Components.Routing; +using Microsoft.AspNetCore.Components.Web; +using Microsoft.Extensions.DependencyInjection; +using Microsoft.Extensions.Logging; + +namespace AutoForge.IntegrationTests; + +public sealed class TelemetryRecordingIntegrationTests +{ + private const string ProfileIdentifier = "autoforge.synthetic.test-truck"; + private const int ProfileRevision = 1; + private const string EngineModuleIdentifier = "module.engine.primary"; + + [Fact] + public async Task CaptureWindow_ExcludesPriorTraceAndStartStopNeverOperateTheSource() + { + using var directory = new TemporaryDirectory(); + using var provider = CreateProvider(directory.Path); + await using var session = await OpenStaticSessionAsync(provider); + var workspace = provider.GetRequiredService(); + + var priorDiscovery = await session.DiscoverAsync(); + Assert.NotEmpty(priorDiscovery.Endpoints); + var priorTraceCount = session.Trace.Entries.Count; + var priorDroppedCount = session.Trace.DroppedRecordCount; + + workspace.Start(session); + var firstCapture = workspace.CurrentCapture; + Assert.NotNull(firstCapture); + var firstCaptureId = firstCapture.Header.CaptureId; + workspace.Start(session); + + Assert.Equal(firstCaptureId, workspace.CurrentCapture!.Header.CaptureId); + Assert.Equal(priorTraceCount, session.Trace.Entries.Count); + Assert.Equal(priorDroppedCount, session.Trace.DroppedRecordCount); + + workspace.Stop(); + + var capture = workspace.CurrentCapture; + Assert.NotNull(capture); + Assert.Empty(capture.Observations); + Assert.Equal(TelemetryCaptureState.Complete, capture.Completion!.State); + Assert.Equal(TelemetryCaptureStopReason.User, capture.Completion.StopReason); + Assert.Equal(0, capture.Completion.ObservationCount); + Assert.Equal(priorTraceCount, session.Trace.Entries.Count); + Assert.Equal(priorDroppedCount, session.Trace.DroppedRecordCount); + } + + [Fact] + public async Task CaptureWindow_Retains225ActualOperationsBeyondTheTraceBufferInExactOrder() + { + using var directory = new TemporaryDirectory(); + using var provider = CreateProvider(directory.Path); + await using var session = await OpenStaticSessionAsync(provider); + var workspace = provider.GetRequiredService(); + var endpoint = EngineEndpoint(session); + + workspace.Start(session); + for (var index = 0; index < 225; index++) + { + var result = await session.ReadSignalsAsync(endpoint); + Assert.True(result.IsSuccess, result.Error); + } + + workspace.Stop(); + var capture = workspace.CurrentCapture; + Assert.NotNull(capture); + Assert.Equal(225, capture.Observations.Count); + Assert.Equal(25, session.Trace.DroppedRecordCount); + Assert.Equal(200, session.Trace.Entries.Count); + + var correlationNumbers = capture.Observations + .Select((observation, index) => + { + Assert.Equal(index + 1, observation.Sequence); + Assert.EndsWith($"{index + 1:D6}", observation.CorrelationIdentifier, StringComparison.Ordinal); + return observation.CorrelationIdentifier; + }) + .ToArray(); + Assert.Equal(225, correlationNumbers.Distinct(StringComparer.Ordinal).Count()); + + var traceByCorrelation = session.Trace.Entries.ToDictionary( + trace => trace.CorrelationIdentifier, + StringComparer.Ordinal); + foreach (var observation in capture.Observations) + { + var requestBytes = Convert.FromBase64String(observation.RequestPayloadBase64); + Assert.True(SyntheticProtocolV1.TryDecodeRequest(requestBytes, out var request)); + Assert.NotNull(request); + Assert.Equal(observation.CorrelationIdentifier, request!.CorrelationIdentifier); + + if (!traceByCorrelation.TryGetValue(observation.CorrelationIdentifier, out var trace)) + { + continue; + } + + Assert.Equal(trace.Outcome, observation.Outcome); + Assert.Equal(trace.RequestPayload.ToArray(), requestBytes); + Assert.Equal( + trace.ResponsePayload?.ToArray(), + observation.ResponsePayloadBase64 is null + ? null + : Convert.FromBase64String(observation.ResponsePayloadBase64)); + Assert.NotNull(observation.SignalSnapshot); + Assert.Equal(850, observation.SignalSnapshot!.Signals.Single(signal => + signal.SignalIdentifier == "synthetic.engine.speed").Value.GetInt32()); + } + } + + [Fact] + public async Task PausedDynamicsCapture_SeparatesCaptureDiagnosticAndModelTimeFromDisplayChanges() + { + using var directory = new TemporaryDirectory(); + var clock = new ManualTimeProvider(); + using var provider = CreateProvider(directory.Path, clock); + var profiles = provider.GetRequiredService(); + profiles.Import(ReadFixture("synthetic-truck-baseline.json")); + var configurations = provider.GetRequiredService(); + var configuration = configurations.CreateExample(ProfileIdentifier, ProfileRevision); + var session = await provider.GetRequiredService().OpenDynamicsAsync( + ProfileIdentifier, + ProfileRevision, + DynamicsDiagnosticTransportFactory.ProviderIdentifier, + ExecutionTargetKind.Simulation, + configuration); + await using var ownedSession = session; + var control = session.DynamicsControl!; + await control.StartAsync(); + await control.PauseAsync(); + var paused = await control.StepAsync(3); + + var workspace = provider.GetRequiredService(); + workspace.Start(session); + var displayPreference = provider.GetRequiredService(); + Assert.True(displayPreference.TrySet(new DisplayUnitSelection(DisplayUnitSystem.Metric, SpeedDisplayMode.Engineering))); + Assert.True(displayPreference.TrySet(DisplayUnitSelection.Default)); + Assert.True(displayPreference.TrySet(new DisplayUnitSelection(DisplayUnitSystem.ImperialUS, SpeedDisplayMode.Road))); + + clock.Advance(TimeSpan.FromTicks(17)); + var first = await session.ReadSignalsAsync(EngineEndpoint(session)); + Assert.True(first.IsSuccess, first.Error); + clock.Advance(TimeSpan.FromTicks(29)); + var second = await session.ReadSignalsAsync(EngineEndpoint(session)); + Assert.True(second.IsSuccess, second.Error); + workspace.Stop(); + + var capture = workspace.CurrentCapture; + Assert.NotNull(capture); + Assert.Equal(2, capture.Observations.Count); + Assert.Equal([17L, 46L], capture.Observations.Select(item => item.CaptureElapsedTicks)); + Assert.Equal(paused.StepIndex, control.Status.StepIndex); + Assert.Equal(paused.VirtualTimeSeconds, control.Status.VirtualTimeSeconds); + Assert.Equal(DynamicsLifecycleState.Paused, control.Status.State); + Assert.Equal(configuration.ConfigurationIdentifier, capture.Header.DynamicsConfigurationIdentifier); + Assert.Equal(session.Identity.DynamicsRunIdentifier, capture.Header.DynamicsRunIdentifier); + + foreach (var observation in capture.Observations) + { + var snapshot = observation.SignalSnapshot; + Assert.NotNull(snapshot); + Assert.Equal(paused.StepIndex, snapshot.ModelStepIndex); + Assert.Equal(paused.VirtualTimeSeconds, snapshot.ModelTimeSeconds); + Assert.Equal(configuration.ConfigurationIdentifier, snapshot.ModelConfigurationIdentifier); + Assert.Equal(session.Identity.DynamicsRunIdentifier, snapshot.ModelRunIdentifier); + var engineSpeed = Assert.Single(snapshot.Signals, signal => signal.SignalIdentifier == "engine.speed"); + Assert.Equal("rpm", engineSpeed.Unit); + Assert.Equal("SYNTHETIC_DYNAMIC", engineSpeed.Origin); + Assert.Equal(observation.StartLogicalTicks, engineSpeed.LogicalTimeTicks); + } + + Assert.Equal(2, session.Trace.Entries.Count); + Assert.Equal(0, session.Trace.DroppedRecordCount); + } + + [Fact] + public async Task CaptureRecordsActualPositiveNegativeTimeoutNoResponseCancellationAndMalformedReplyBytes() + { + using var directory = new TemporaryDirectory(); + var cancellationEntered = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously); + var cancellationRelease = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously); + var call = 0; + var definitions = SyntheticDiagnosticExamples.CreateDefinitions(); + var innerFactory = new SimulatedDiagnosticTransportFactory(definitions); + var rewritingFactory = new RewritingDiagnosticTransportFactory( + innerFactory, + async (inner, request, requestBytes, cancellationToken) => + { + var index = Interlocked.Increment(ref call); + if (index == 2) + { + return new TransportReply( + TransportOutcome.Response, + SyntheticProtocolV1.EncodeNegativeResponse(request, "TEST_NEGATIVE", "controlled negative response"), + 0); + } + + if (index == 3) + { + return new TransportReply(TransportOutcome.Timeout, ReadOnlyMemory.Empty, 0, "controlled timeout"); + } + + if (index == 4) + { + return new TransportReply(TransportOutcome.NoResponse, ReadOnlyMemory.Empty, 0, "controlled no response"); + } + + if (index == 5) + { + cancellationEntered.TrySetResult(); + await cancellationRelease.Task.WaitAsync(cancellationToken); + } + + if (index == 6) + { + return new TransportReply(TransportOutcome.Response, Encoding.UTF8.GetBytes("{"), 0); + } + + return await inner.SendAsync(requestBytes, cancellationToken); + }); + using var provider = CreateProvider(directory.Path, transportFactory: rewritingFactory); + await using var session = await OpenStaticSessionAsync(provider); + var workspace = provider.GetRequiredService(); + workspace.Start(session); + + var endpoint = EngineEndpoint(session); + Assert.True((await session.ReadSignalsAsync(endpoint)).IsSuccess); + Assert.Equal( + DiagnosticOutcome.NegativeResponse, + (await session.ReadSignalsAsync(endpoint)).Outcome); + Assert.Equal(DiagnosticOutcome.Timeout, (await session.ReadSignalsAsync(endpoint)).Outcome); + Assert.Equal(DiagnosticOutcome.NoResponse, (await session.ReadSignalsAsync(endpoint)).Outcome); + + using var cancellation = new CancellationTokenSource(); + var cancelledOperation = session.ReadSignalsAsync(endpoint, cancellation.Token); + await cancellationEntered.Task; + cancellation.Cancel(); + var cancelledResult = await cancelledOperation; + Assert.Equal(DiagnosticOutcome.Cancelled, cancelledResult.Outcome); + + Assert.Equal( + DiagnosticOutcome.ProtocolError, + (await session.ReadSignalsAsync(endpoint)).Outcome); + workspace.Stop(); + + var currentCapture = workspace.CurrentCapture; + Assert.NotNull(currentCapture); + var observations = currentCapture.Observations; + Assert.Equal( + [ + DiagnosticOutcome.PositiveResponse, + DiagnosticOutcome.NegativeResponse, + DiagnosticOutcome.Timeout, + DiagnosticOutcome.NoResponse, + DiagnosticOutcome.Cancelled, + DiagnosticOutcome.ProtocolError + ], + observations.Select(item => item.Outcome)); + Assert.NotNull(observations[0].SignalSnapshot); + Assert.Null(observations[1].SignalSnapshot); + Assert.Null(observations[2].SignalSnapshot); + Assert.Null(observations[3].SignalSnapshot); + Assert.Null(observations[4].SignalSnapshot); + Assert.Null(observations[5].SignalSnapshot); + Assert.NotNull(observations[0].ResponsePayloadBase64); + Assert.NotNull(observations[1].ResponsePayloadBase64); + Assert.Null(observations[2].ResponsePayloadBase64); + Assert.Null(observations[3].ResponsePayloadBase64); + Assert.Null(observations[4].ResponsePayloadBase64); + Assert.Equal("{", Encoding.UTF8.GetString(Convert.FromBase64String(observations[5].ResponsePayloadBase64!))); + Assert.Equal("controlled negative response", observations[1].Error); + Assert.Contains("not valid synthetic protocol", observations[5].Error); + Assert.Equal(6, session.Trace.Entries.Count); + Assert.Equal(DiagnosticOutcome.Cancelled, session.Trace.Entries[4].Outcome); + Assert.Null(session.Trace.Entries[4].ResponsePayload); + } + + [Fact] + public async Task ObservationSubscriberFailure_IsVisibleWithoutChangingTheDiagnosticResult() + { + using var directory = new TemporaryDirectory(); + using var provider = CreateProvider(directory.Path); + await using var session = await OpenStaticSessionAsync(provider); + var workspace = provider.GetRequiredService(); + workspace.Start(session); + using var failingSubscriber = session.SubscribeObservations(_ => + throw new InvalidOperationException("controlled observer failure")); + + var result = await session.ReadSignalsAsync(EngineEndpoint(session)); + + Assert.True(result.IsSuccess, result.Error); + Assert.Contains("controlled observer failure", session.ObservationDispatchError); + Assert.Single(session.Trace.Entries); + Assert.Single(workspace.CurrentCapture!.Observations); + var html = await RenderComponentAsync(provider, session); + Assert.Contains("role=\"alert\"", html); + Assert.Contains("controlled observer failure", html); + } + + [Fact] + public async Task CaptureOwnership_RejectsCompetingOwnerAndStopDrainsAcceptedCallbackBeforeReturning() + { + using var directory = new TemporaryDirectory(); + var clock = new ManualTimeProvider(); + using var provider = CreateProvider(directory.Path, clock); + await using var session = await OpenStaticSessionAsync(provider); + var store = provider.GetRequiredService(); + var workspace = new TelemetryRecordingWorkspace(store, clock); + var competingWorkspace = new TelemetryRecordingWorkspace(store, clock); + workspace.Start(session); + var firstId = workspace.CurrentCapture!.Header.CaptureId; + Assert.Throws(() => competingWorkspace.Start(session)); + Assert.Null(competingWorkspace.CurrentCapture); + + var observationEntered = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously); + var releaseObservation = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously); + using var blockingObserver = session.SubscribeObservations(_ => + { + observationEntered.TrySetResult(); + releaseObservation.Task.GetAwaiter().GetResult(); + }); + var draining = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously); + workspace.Changed += () => + { + if (workspace.IsStopping) + { + draining.TrySetResult(); + } + }; + var operation = Task.Run(() => session.ReadSignalsAsync(EngineEndpoint(session))); + await observationEntered.Task.WaitAsync(TimeSpan.FromSeconds(5)); + var stop = Task.Run(workspace.Stop); + await draining.Task.WaitAsync(TimeSpan.FromSeconds(5)); + + Assert.True(workspace.IsStopping); + await Assert.ThrowsAsync(() => + Task.Run(() => workspace.Start(session)).WaitAsync(TimeSpan.FromSeconds(5))); + Assert.Equal(firstId, workspace.CurrentCapture!.Header.CaptureId); + + releaseObservation.TrySetResult(); + Assert.True((await operation.WaitAsync(TimeSpan.FromSeconds(5))).IsSuccess); + await stop.WaitAsync(TimeSpan.FromSeconds(5)); + + var completed = workspace.CurrentCapture; + Assert.NotNull(completed); + Assert.False(completed.IsRecording); + Assert.Single(completed.Observations); + Assert.Equal(1, completed.Completion!.ObservationCount); + Assert.False(workspace.IsStopping); + } + + [Fact] + public async Task ResetKeepsOldUnsavedCaptureInspectableAndRequiresExplicitDiscardBeforeNewSource() + { + using var directory = new TemporaryDirectory(); + using var provider = CreateProvider(directory.Path); + var sessions = provider.GetRequiredService(); + var firstSession = await OpenStaticSessionAsync(provider); + var workspace = provider.GetRequiredService(); + workspace.Start(firstSession); + Assert.True((await firstSession.ReadSignalsAsync(EngineEndpoint(firstSession))).IsSuccess); + + var replacement = await sessions.ResetAsync(firstSession); + await using var newSession = replacement; + var oldCapture = workspace.CurrentCapture; + Assert.NotNull(oldCapture); + Assert.Equal(firstSession.Identity.SessionIdentifier, oldCapture.Header.SessionIdentifier); + Assert.Equal(TelemetryCaptureStopReason.SourceClosed, oldCapture.Completion!.StopReason); + Assert.Single(oldCapture.Observations); + Assert.Throws(() => workspace.Start(newSession)); + Assert.Equal(firstSession.Identity.SessionIdentifier, workspace.CurrentCapture!.Header.SessionIdentifier); + + workspace.Discard(); + workspace.Start(newSession); + var newCapture = workspace.CurrentCapture; + Assert.NotNull(newCapture); + Assert.Equal(newSession.Identity.SessionIdentifier, newCapture.Header.SessionIdentifier); + Assert.Empty(newCapture.Observations); + Assert.True((await newSession.ReadSignalsAsync(EngineEndpoint(newSession))).IsSuccess); + workspace.Stop(); + + var finished = workspace.CurrentCapture; + Assert.NotNull(finished); + Assert.Single(finished.Observations); + Assert.StartsWith(newSession.Identity.SessionIdentifier, finished.Observations[0].CorrelationIdentifier, StringComparison.Ordinal); + Assert.DoesNotContain( + finished.Observations, + observation => observation.CorrelationIdentifier.StartsWith(firstSession.Identity.SessionIdentifier, StringComparison.Ordinal)); + await firstSession.DisposeAsync(); + } + + [Fact] + public async Task CaptureLimits_RetainExactCountAndBytePrefixesAndRejectHeaderBeforeSubscription() + { + using var directory = new TemporaryDirectory(); + var clock = new ManualTimeProvider(); + using var provider = CreateProvider(directory.Path, clock); + var firstSession = await OpenStaticSessionAsync(provider); + + var measuredWorkspace = new TelemetryRecordingWorkspace( + provider.GetRequiredService(), + clock); + measuredWorkspace.Start(firstSession); + var headerBytes = TelemetryArchiveCodec.GetEncodedHeaderLength(measuredWorkspace.CurrentCapture!.Header); + var measuredBytes = await firstSession.ReadSignalsAsync(EngineEndpoint(firstSession)); + Assert.True(measuredBytes.IsSuccess); + var observationBytes = TelemetryArchiveCodec.GetEncodedObservationLength( + measuredWorkspace.CurrentCapture!.Observations.Single()); + measuredWorkspace.Stop(); + await firstSession.DisposeAsync(); + + var exactHeaderLimits = TelemetryCaptureLimits.Default with { MaximumHeaderBytes = headerBytes }; + var exactHeaderSession = await OpenStaticSessionAsync(provider); + var exactHeaderWorkspace = new TelemetryRecordingWorkspace( + provider.GetRequiredService(), + clock, + exactHeaderLimits); + exactHeaderWorkspace.Start(exactHeaderSession); + Assert.Equal(headerBytes, TelemetryArchiveCodec.GetEncodedHeaderLength(exactHeaderWorkspace.CurrentCapture!.Header)); + exactHeaderWorkspace.Stop(); + await exactHeaderSession.DisposeAsync(); + + var belowHeaderLimits = TelemetryCaptureLimits.Default with { MaximumHeaderBytes = headerBytes - 1 }; + var belowHeaderSession = await OpenStaticSessionAsync(provider); + var belowHeaderWorkspace = new TelemetryRecordingWorkspace( + provider.GetRequiredService(), + clock, + belowHeaderLimits); + Assert.Throws(() => belowHeaderWorkspace.Start(belowHeaderSession)); + Assert.Null(belowHeaderWorkspace.CurrentCapture); + await using var belowHeaderOwnedSession = belowHeaderSession; + + var countLimits = TelemetryCaptureLimits.Default with { MaximumObservations = 2 }; + var countSession = await OpenStaticSessionAsync(provider); + await using var countOwnedSession = countSession; + var countWorkspace = new TelemetryRecordingWorkspace( + provider.GetRequiredService(), + clock, + countLimits); + countWorkspace.Start(countSession); + var endpoint = EngineEndpoint(countSession); + Assert.True((await countSession.ReadSignalsAsync(endpoint)).IsSuccess); + Assert.True((await countSession.ReadSignalsAsync(endpoint)).IsSuccess); + Assert.Equal(2, countWorkspace.CurrentCapture!.Observations.Count); + Assert.True(countWorkspace.CurrentCapture.IsRecording); + Assert.True((await countSession.ReadSignalsAsync(endpoint)).IsSuccess); + var countLimited = countWorkspace.CurrentCapture; + Assert.NotNull(countLimited); + Assert.Equal(2, countLimited.Observations.Count); + Assert.Equal(TelemetryCaptureState.Incomplete, countLimited.Completion!.State); + Assert.Equal(TelemetryCaptureStopReason.LimitExceeded, countLimited.Completion.StopReason); + Assert.Equal(3, countSession.Trace.Entries.Count); + await Assert.ThrowsAsync(() => countWorkspace.SaveAsync(savePartial: false)); + await countWorkspace.SaveAsync(savePartial: true); + var partialReadback = await new FileTelemetryArchiveStore(directory.Path).LoadAsync( + countLimited.Header.CaptureId); + Assert.Equal(TelemetryCaptureState.Incomplete, partialReadback.Completion!.State); + Assert.Equal(2, partialReadback.Completion.ObservationCount); + Assert.Contains("Partial capture", countWorkspace.Status); + + var exactByteLimits = TelemetryCaptureLimits.Default with + { + MaximumObservationBytes = observationBytes + }; + var exactByteSession = await OpenStaticSessionAsync(provider); + await using var exactByteOwnedSession = exactByteSession; + var exactByteWorkspace = new TelemetryRecordingWorkspace( + provider.GetRequiredService(), + clock, + exactByteLimits); + exactByteWorkspace.Start(exactByteSession); + Assert.True((await exactByteSession.ReadSignalsAsync(EngineEndpoint(exactByteSession))).IsSuccess); + Assert.Equal(observationBytes, exactByteWorkspace.CurrentCapture!.Completion?.ObservationBytes + ?? TelemetryArchiveCodec.GetEncodedObservationLength(exactByteWorkspace.CurrentCapture.Observations.Single())); + Assert.True(exactByteWorkspace.CurrentCapture.IsRecording); + exactByteWorkspace.Stop(); + + var oneBelowByteLimits = TelemetryCaptureLimits.Default with + { + MaximumObservationBytes = observationBytes - 1 + }; + var oneBelowByteSession = await OpenStaticSessionAsync(provider); + await using var oneBelowByteOwnedSession = oneBelowByteSession; + var oneBelowByteWorkspace = new TelemetryRecordingWorkspace( + provider.GetRequiredService(), + clock, + oneBelowByteLimits); + oneBelowByteWorkspace.Start(oneBelowByteSession); + Assert.True((await oneBelowByteSession.ReadSignalsAsync(EngineEndpoint(oneBelowByteSession))).IsSuccess); + var byteLimited = oneBelowByteWorkspace.CurrentCapture; + Assert.NotNull(byteLimited); + Assert.Empty(byteLimited.Observations); + Assert.Equal(TelemetryCaptureState.Incomplete, byteLimited.Completion!.State); + Assert.Equal(TelemetryCaptureStopReason.LimitExceeded, byteLimited.Completion.StopReason); + } + + [Fact] + public async Task CaptureCountLimit_Accepts4096OperationsAndMarksTheNextOperationIncomplete() + { + using var directory = new TemporaryDirectory(); + using var provider = CreateProvider(directory.Path); + await using var session = await OpenStaticSessionAsync(provider); + var workspace = provider.GetRequiredService(); + var endpoint = EngineEndpoint(session); + workspace.Start(session); + + for (var index = 0; index < TelemetryCaptureLimits.Default.MaximumObservations; index++) + { + Assert.True((await session.ReadSignalsAsync(endpoint)).IsSuccess); + } + + var exact = workspace.CurrentCapture!; + Assert.Equal(4096, exact.Observations.Count); + Assert.True(exact.IsRecording); + + Assert.True((await session.ReadSignalsAsync(endpoint)).IsSuccess); + var limited = workspace.CurrentCapture!; + Assert.Equal(4096, limited.Observations.Count); + Assert.Equal(TelemetryCaptureState.Incomplete, limited.Completion!.State); + Assert.Equal(TelemetryCaptureStopReason.LimitExceeded, limited.Completion.StopReason); + Assert.Equal(4097, session.Trace.DroppedRecordCount + session.Trace.Entries.Count); + } + + [Fact] + public async Task FileArchive_RoundTripsExactSourceContextAndNeverOverwritesOrPublishesPartialFiles() + { + using var directory = new TemporaryDirectory(); + using var provider = CreateProvider(directory.Path); + var configuration = PrepareDynamicsConfiguration(provider); + await using var session = await OpenDynamicsSessionAsync(provider, configuration); + var workspace = provider.GetRequiredService(); + workspace.Start(session); + Assert.True((await session.ReadSignalsAsync(EngineEndpoint(session))).IsSuccess); + workspace.Stop(); + + var original = workspace.CurrentCapture; + Assert.NotNull(original); + await workspace.SaveAsync(savePartial: false); + Assert.True(workspace.CurrentCapture!.IsSaved); + + var newStore = new FileTelemetryArchiveStore(directory.Path); + var readback = await newStore.LoadAsync(original.Header.CaptureId); + Assert.Equal(original.Header.CaptureId, readback.Header.CaptureId); + Assert.Equal(original.Header.SessionIdentifier, readback.Header.SessionIdentifier); + Assert.Equal(original.Header.ProfileIdentifier, readback.Header.ProfileIdentifier); + Assert.Equal(original.Header.ProfileRevision, readback.Header.ProfileRevision); + Assert.Equal(original.Header.VehicleIdentifier, readback.Header.VehicleIdentifier); + Assert.Equal(original.Header.ProviderIdentifier, readback.Header.ProviderIdentifier); + Assert.Equal(original.Header.TargetKind, readback.Header.TargetKind); + Assert.Equal(original.Header.ProtocolVersion, readback.Header.ProtocolVersion); + Assert.Equal(original.Header.DynamicsConfigurationIdentifier, readback.Header.DynamicsConfigurationIdentifier); + Assert.Equal(original.Header.DynamicsRunIdentifier, readback.Header.DynamicsRunIdentifier); + Assert.Equal(original.Header.SourceEndpoints, readback.Header.SourceEndpoints); + Assert.Equal(original.Completion, readback.Completion); + Assert.True(readback.IsSaved); + + var sourceObservation = Assert.Single(original.Observations); + var loadedObservation = Assert.Single(readback.Observations); + AssertObservationEqual(sourceObservation, loadedObservation); + Assert.Equal( + await File.ReadAllBytesAsync(Path.Combine(directory.Path, $"{original.Header.CaptureId}.json")), + TelemetryArchiveCodec.Serialize(readback)); + + var existingArchive = await File.ReadAllBytesAsync(Path.Combine(directory.Path, $"{original.Header.CaptureId}.json")); + var collision = await Assert.ThrowsAsync(() => + newStore.SaveAsync(original)); + Assert.Equal(TelemetryArchiveFailure.Collision, collision.Failure); + Assert.Equal(existingArchive, await File.ReadAllBytesAsync(Path.Combine(directory.Path, $"{original.Header.CaptureId}.json"))); + Assert.Empty(Directory.GetFiles(directory.Path, "*.tmp", SearchOption.TopDirectoryOnly)); + } + + [Fact] + public async Task InvalidArchives_AreRejectedAndDoNotReplacePriorInspection() + { + using var directory = new TemporaryDirectory(); + using var provider = CreateProvider(directory.Path); + await using var session = await OpenStaticSessionAsync(provider); + var workspace = provider.GetRequiredService(); + workspace.Start(session); + Assert.True((await session.ReadSignalsAsync(EngineEndpoint(session))).IsSuccess); + workspace.Stop(); + await workspace.SaveAsync(savePartial: false); + var captureId = workspace.CurrentCapture!.Header.CaptureId; + await workspace.LoadAsync(captureId); + var priorInspection = workspace.CurrentCapture!; + var goodBytes = await File.ReadAllBytesAsync(Path.Combine(directory.Path, $"{captureId}.json")); + var goodJson = Encoding.UTF8.GetString(goodBytes); + + var invalidDocuments = new[] + { + goodBytes[..^1], + Encoding.UTF8.GetBytes(goodJson.Replace("\"schemaVersion\":1", "\"schemaVersion\":99", StringComparison.Ordinal)), + Encoding.UTF8.GetBytes(goodJson.Replace( + "\"schemaVersion\":1", + "\"schemaVersion\":1,\"schemaVersion\":1", + StringComparison.Ordinal)), + Encoding.UTF8.GetBytes(goodJson.Replace( + "\"schemaVersion\":1", + "\"schemaVersion\":1,\"unknownRoot\":true", + StringComparison.Ordinal)), + Encoding.UTF8.GetBytes(goodJson.Replace( + "\"positiveResponse\"", + "\"PositiveResponse\"", + StringComparison.Ordinal)), + Encoding.UTF8.GetBytes(goodJson.Replace("\"positiveResponse\"", "\"timeout\"", StringComparison.Ordinal)) + }; + foreach (var invalid in invalidDocuments) + { + var exception = Assert.Throws(() => TelemetryArchiveCodec.Deserialize(invalid)); + Assert.Contains( + exception.Failure, + new[] + { + TelemetryArchiveFailure.InvalidArchive, + TelemetryArchiveFailure.UnsupportedVersion, + TelemetryArchiveFailure.LimitExceeded + }); + } + + var malformedBase64 = JsonNode.Parse(goodJson)!.AsObject(); + malformedBase64["observations"]![0]!["requestPayloadBase64"] = "%%%"; + Assert.Throws(() => + TelemetryArchiveCodec.Deserialize(Encoding.UTF8.GetBytes(malformedBase64.ToJsonString()))); + + var mismatchedTrace = JsonNode.Parse(goodJson)!.AsObject(); + mismatchedTrace["observations"]![0]!["correlationIdentifier"] = "different-correlation"; + Assert.Throws(() => + TelemetryArchiveCodec.Deserialize(Encoding.UTF8.GetBytes(mismatchedTrace.ToJsonString()))); + + var corruptId = Guid.NewGuid().ToString("N"); + await File.WriteAllTextAsync(Path.Combine(directory.Path, $"{corruptId}.json"), "{"); + await workspace.LoadAsync(corruptId); + Assert.Equal(priorInspection.Header.CaptureId, workspace.CurrentCapture!.Header.CaptureId); + Assert.NotNull(workspace.Error); + } + + [Fact] + public async Task FileArchive_CancellationAndFilesystemFailureAreTypedAndLeaveNoPublishedArchive() + { + using var directory = new TemporaryDirectory(); + using var provider = CreateProvider(directory.Path); + await using var session = await OpenStaticSessionAsync(provider); + var workspace = provider.GetRequiredService(); + workspace.Start(session); + Assert.True((await session.ReadSignalsAsync(EngineEndpoint(session))).IsSuccess); + workspace.Stop(); + var capture = workspace.CurrentCapture!; + using var cancellation = new CancellationTokenSource(); + cancellation.Cancel(); + + var store = new FileTelemetryArchiveStore(directory.Path); + var cancelled = await Assert.ThrowsAsync(() => + store.SaveAsync(capture, cancellation.Token)); + Assert.Equal(TelemetryArchiveFailure.Cancelled, cancelled.Failure); + Assert.Empty(Directory.GetFiles(directory.Path)); + + var fileAsDirectory = Path.Combine(directory.Path, "not-a-directory"); + await File.WriteAllTextAsync(fileAsDirectory, "occupied"); + var failingStore = new FileTelemetryArchiveStore(fileAsDirectory); + var failed = await Assert.ThrowsAsync(() => failingStore.SaveAsync(capture)); + Assert.Equal(TelemetryArchiveFailure.WriteFailure, failed.Failure); + Assert.False(File.Exists(Path.Combine(fileAsDirectory, $"{capture.Header.CaptureId}.json"))); + Assert.Equal("occupied", await File.ReadAllTextAsync(fileAsDirectory)); + } + + [Fact] + public async Task PendingSave_RejectsConflictingActionsAndOnlyMarksTheBoundCaptureSaved() + { + using var directory = new TemporaryDirectory(); + using var provider = CreateProvider(directory.Path); + await using var session = await OpenStaticSessionAsync(provider); + var realStore = new FileTelemetryArchiveStore(directory.Path); + var blockingStore = new BlockingArchiveStore(realStore); + var workspace = new TelemetryRecordingWorkspace(blockingStore, TimeProvider.System); + workspace.Start(session); + Assert.True((await session.ReadSignalsAsync(EngineEndpoint(session))).IsSuccess); + workspace.Stop(); + var captureId = workspace.CurrentCapture!.Header.CaptureId; + var save = workspace.SaveAsync(savePartial: false); + + try + { + await blockingStore.SaveEntered.WaitAsync(TimeSpan.FromSeconds(5)); + Assert.True(workspace.IsBusy); + Assert.Throws(workspace.Discard); + Assert.Throws(() => workspace.Start(session)); + Assert.Equal(captureId, workspace.CurrentCapture!.Header.CaptureId); + Assert.False(workspace.CurrentCapture.IsSaved); + } + finally + { + blockingStore.ReleaseSave(); + await save; + } + + Assert.False(workspace.IsBusy); + Assert.True(workspace.CurrentCapture!.IsSaved); + Assert.Single(await realStore.ListAsync()); + Assert.Equal(captureId, Assert.Single(await realStore.ListAsync()).CaptureId); + } + + [Fact] + public async Task ArchiveInputLimit_AcceptsExactly32MiBAndRejectsOneByteMore() + { + using var directory = new TemporaryDirectory(); + using var provider = CreateProvider(directory.Path); + await using var session = await OpenStaticSessionAsync(provider); + var owner = SessionTelemetryCapture.Start(session); + owner.Stop(); + var encoded = TelemetryArchiveCodec.Serialize(owner.Snapshot); + var maximum = TelemetryCaptureLimits.Default.MaximumArchiveBytes; + var padded = new byte[maximum + 1]; + Buffer.BlockCopy(encoded, 0, padded, 0, encoded.Length); + Array.Fill(padded, (byte)' ', encoded.Length, checked((int)maximum - encoded.Length)); + + var exact = TelemetryArchiveCodec.Deserialize(padded.AsMemory(0, checked((int)maximum))); + Assert.Equal(owner.Snapshot.Header.CaptureId, exact.Header.CaptureId); + var over = Assert.Throws(() => + TelemetryArchiveCodec.Deserialize(padded)); + Assert.Equal(TelemetryArchiveFailure.LimitExceeded, over.Failure); + } + + [Fact] + public async Task ArchiveHeaderLimit_AcceptsExactlyOneMiBAndRejectsOneByteMore() + { + using var directory = new TemporaryDirectory(); + using var provider = CreateProvider(directory.Path); + await using var session = await OpenStaticSessionAsync(provider); + var owner = SessionTelemetryCapture.Start(session); + owner.Stop(); + var capture = owner.Snapshot; + var baseHeader = capture.Header; + var maximum = TelemetryCaptureLimits.Default.MaximumHeaderBytes; + var baseLength = TelemetryArchiveCodec.GetEncodedHeaderLength(baseHeader); + var extraCharacters = checked((int)(maximum - baseLength)); + var exactHeader = baseHeader with + { + SessionIdentifier = new string('s', baseHeader.SessionIdentifier.Length + extraCharacters) + }; + Assert.Equal(maximum, TelemetryArchiveCodec.GetEncodedHeaderLength(exactHeader)); + var exactCapture = new TelemetryCaptureSnapshot( + exactHeader, + Array.Empty(), + capture.Completion); + var encoded = TelemetryArchiveCodec.Serialize(exactCapture); + Assert.Equal(exactHeader.SessionIdentifier, TelemetryArchiveCodec.Deserialize(encoded).Header.SessionIdentifier); + + var overHeader = exactHeader with { SessionIdentifier = exactHeader.SessionIdentifier + "s" }; + var rejected = Assert.Throws(() => TelemetryArchiveCodec.Serialize( + new TelemetryCaptureSnapshot( + overHeader, + Array.Empty(), + capture.Completion))); + Assert.Equal(TelemetryArchiveFailure.LimitExceeded, rejected.Failure); + } + + [Fact] + public async Task ArchiveObservationLimit_AcceptsExactly16MiBAndRejectsOneByteMore() + { + using var directory = new TemporaryDirectory(); + using var provider = CreateProvider(directory.Path); + await using var session = await OpenStaticSessionAsync(provider); + var owner = SessionTelemetryCapture.Start(session); + Assert.True((await session.ReadSignalsAsync(EngineEndpoint(session))).IsSuccess); + owner.Stop(); + var capture = owner.Snapshot; + var observation = capture.Observations.Single(); + var baseLength = TelemetryArchiveCodec.GetEncodedObservationLength(observation); + var exactSummary = (observation.DecodedSummary ?? string.Empty) + + new string('s', checked((int)(TelemetryCaptureLimits.Default.MaximumObservationBytes - baseLength))); + var exactObservation = observation with { DecodedSummary = exactSummary }; + var exactObservationBytes = TelemetryArchiveCodec.GetEncodedObservationLength(exactObservation); + Assert.Equal(TelemetryCaptureLimits.Default.MaximumObservationBytes, exactObservationBytes); + var exactCapture = new TelemetryCaptureSnapshot( + capture.Header, + [exactObservation], + capture.Completion! with { ObservationBytes = exactObservationBytes }); + var encoded = TelemetryArchiveCodec.Serialize(exactCapture); + Assert.Equal(exactObservationBytes, TelemetryArchiveCodec.Deserialize(encoded).Completion!.ObservationBytes); + + var overObservation = exactObservation with { DecodedSummary = exactSummary + "s" }; + var overBytes = TelemetryArchiveCodec.GetEncodedObservationLength(overObservation); + var rejected = Assert.Throws(() => TelemetryArchiveCodec.Serialize( + new TelemetryCaptureSnapshot( + capture.Header, + [overObservation], + capture.Completion! with { ObservationBytes = overBytes }))); + Assert.Equal(TelemetryArchiveFailure.LimitExceeded, rejected.Failure); + } + + [Fact] + public async Task CaptureWorkspace_IsSharedAcrossHostScopesAndRetainsClosedSourceCapture() + { + using var directory = new TemporaryDirectory(); + using var provider = CreateProvider(directory.Path); + using var diagnosticsScope = provider.CreateScope(); + using var simulationScope = provider.CreateScope(); + var diagnosticsWorkspace = diagnosticsScope.ServiceProvider.GetRequiredService(); + var simulationWorkspace = simulationScope.ServiceProvider.GetRequiredService(); + Assert.Same(diagnosticsWorkspace, simulationWorkspace); + + await using var session = await OpenStaticSessionAsync(diagnosticsScope.ServiceProvider); + diagnosticsWorkspace.Start(session); + var read = await session.ReadSignalsAsync(EngineEndpoint(session)); + Assert.True(read.IsSuccess, read.Error); + + await session.DisposeAsync(); + + var capture = simulationWorkspace.CurrentCapture; + Assert.NotNull(capture); + Assert.Equal(TelemetryCaptureState.Complete, capture.Completion!.State); + Assert.Equal(TelemetryCaptureStopReason.SourceClosed, capture.Completion.StopReason); + Assert.Single(capture.Observations); + Assert.Equal(session.Identity.SessionIdentifier, capture.Header.SessionIdentifier); + Assert.Contains( + Assert.Single(capture.Observations).SignalSnapshot!.Signals, + signal => signal.SignalIdentifier == "synthetic.engine.speed"); + } + + [Theory] + [InlineData(false)] + [InlineData(true)] + public async Task BothHostRoutes_RenderSharedRecordingSaveAndSourceFaithfulInspection(bool isDynamic) + { + using var directory = new TemporaryDirectory(); + var route = isDynamic ? "http://localhost/simulation" : "http://localhost/diagnostics"; + using var provider = CreateProvider(directory.Path, uri: route); + DiagnosticSession session; + if (isDynamic) + { + var configuration = PrepareDynamicsConfiguration(provider); + var page = provider.GetRequiredService(); + page.SelectedProfileIdentifier = configuration.ProfileIdentifier; + page.SelectedProfileRevision = configuration.ProfileRevision; + page.SelectedProviderIdentifier = DynamicsDiagnosticTransportFactory.ProviderIdentifier; + page.SelectedConfigurationIdentifier = configuration.ConfigurationIdentifier; + await page.OpenSessionAsync(); + session = Assert.IsType(page.ActiveSession); + await session.DynamicsControl!.StartAsync(); + await session.DynamicsControl.PauseAsync(); + await session.DynamicsControl.StepAsync(2); + } + else + { + var page = provider.GetRequiredService(); + page.LoadSyntheticExample(); + page.SelectedProfileIdentifier = ProfileIdentifier; + page.SelectedProfileRevision = ProfileRevision; + page.SelectedProviderIdentifier = SimulatedDiagnosticTransportFactory.ProviderIdentifier; + page.SelectedTargetKind = ExecutionTargetKind.Simulation; + await page.OpenSessionAsync(); + session = Assert.IsType(page.ActiveSession); + } + + await using var ownedSession = session; + var workspace = provider.GetRequiredService(); + workspace.Start(session); + Assert.True((await session.ReadSignalsAsync(EngineEndpoint(session))).IsSuccess); + workspace.Stop(); + var sourceTraceCount = session.Trace.Entries.Count; + var sourceTraceDropCount = session.Trace.DroppedRecordCount; + var modelStatus = session.DynamicsControl?.Status; + + var stoppedHtml = await RenderRoutesAsync(provider); + Assert.Contains("Save capture", stoppedHtml); + Assert.Contains("Raw request and response bytes", stoppedHtml); + Assert.Contains("Decoded source signals", stoppedHtml); + Assert.Contains(isDynamic ? "autoforge.simulation.dynamics" : "autoforge.simulation.synthetic", stoppedHtml); + Assert.Contains("This is not playback", stoppedHtml); + Assert.Equal(sourceTraceCount, session.Trace.Entries.Count); + Assert.Equal(sourceTraceDropCount, session.Trace.DroppedRecordCount); + Assert.Equal(modelStatus, session.DynamicsControl?.Status); + + var id = workspace.CurrentCapture!.Header.CaptureId; + await workspace.SaveAsync(savePartial: false); + await workspace.RefreshAsync(); + await workspace.LoadAsync(id); + var loadedHtml = await RenderRoutesAsync(provider); + Assert.Contains("Saved locally", loadedHtml); + Assert.Contains("source-sensitive", loadedHtml); + Assert.Contains("Archive readback establishes file consistency only", loadedHtml); + Assert.Single(workspace.CurrentCapture!.Observations); + Assert.Equal(sourceTraceCount, session.Trace.Entries.Count); + Assert.Equal(modelStatus, session.DynamicsControl?.Status); + + await session.DisposeAsync(); + var afterCloseHtml = await RenderRoutesAsync(provider); + Assert.Contains(id, afterCloseHtml); + Assert.Contains("Source session / profile", afterCloseHtml); + Assert.Equal(session.Identity.SessionIdentifier, workspace.CurrentCapture!.Header.SessionIdentifier); + Assert.Equal(sourceTraceCount, session.Trace.Entries.Count); + } + + private static ServiceProvider CreateProvider( + string recordingsDirectory, + TimeProvider? timeProvider = null, + IDiagnosticTransportFactory? transportFactory = null, + string uri = "http://localhost/diagnostics") + { + var services = new ServiceCollection(); + services.AddLogging(); + services.AddAutoForgeVehicleProfiles(); + var definitions = SyntheticDiagnosticExamples.CreateDefinitions(); + services.AddAutoForgeDiagnostics( + [ + transportFactory ?? new SimulatedDiagnosticTransportFactory(definitions), + new DynamicsDiagnosticTransportFactory(definitions) + ]); + services.AddAutoForgeDynamicsConfigurations(); + services.AddSingleton(); + if (timeProvider is not null) + { + services.AddSingleton(timeProvider); + } + + services.AddSingleton(new TestNavigationManager(uri)); + services.AddSingleton(); + services.AddSingleton(); + services.AddAutoForgeTelemetryRecording(recordingsDirectory); + services.AddAutoForgeUi(); + return services.BuildServiceProvider(new ServiceProviderOptions { ValidateOnBuild = true }); + } + + private static async Task OpenStaticSessionAsync(IServiceProvider provider) + { + var profiles = provider.GetRequiredService(); + if (!profiles.List().Any(profile => profile.ProfileIdentifier == ProfileIdentifier && profile.Revision == ProfileRevision)) + { + profiles.Import(ReadFixture("synthetic-truck-baseline.json")); + } + + return await provider.GetRequiredService().OpenAsync( + ProfileIdentifier, + ProfileRevision, + SimulatedDiagnosticTransportFactory.ProviderIdentifier, + ExecutionTargetKind.Simulation); + } + + private static DynamicsConfiguration PrepareDynamicsConfiguration(IServiceProvider provider) + { + var profiles = provider.GetRequiredService(); + if (!profiles.List().Any(profile => profile.ProfileIdentifier == ProfileIdentifier && profile.Revision == ProfileRevision)) + { + profiles.Import(ReadFixture("synthetic-truck-baseline.json")); + } + + return provider.GetRequiredService() + .CreateExample(ProfileIdentifier, ProfileRevision); + } + + private static async Task OpenDynamicsSessionAsync( + IServiceProvider provider, + DynamicsConfiguration configuration) => + await provider.GetRequiredService().OpenDynamicsAsync( + ProfileIdentifier, + ProfileRevision, + DynamicsDiagnosticTransportFactory.ProviderIdentifier, + ExecutionTargetKind.Simulation, + configuration); + + private static DiagnosticEndpoint EngineEndpoint(DiagnosticSession session) => + session.ExpectedEndpoints.Single(endpoint => endpoint.ModuleIdentifier == EngineModuleIdentifier); + + private static void AssertObservationEqual( + TelemetryRecordedObservation expected, + TelemetryRecordedObservation actual) + { + Assert.Equal(expected.Sequence, actual.Sequence); + Assert.Equal(expected.CaptureElapsedTicks, actual.CaptureElapsedTicks); + Assert.Equal(expected.ModuleIdentifier, actual.ModuleIdentifier); + Assert.Equal(expected.Address, actual.Address); + Assert.Equal(expected.CorrelationIdentifier, actual.CorrelationIdentifier); + Assert.Equal(expected.Service, actual.Service); + Assert.Equal(expected.StartLogicalTicks, actual.StartLogicalTicks); + Assert.Equal(expected.EndLogicalTicks, actual.EndLogicalTicks); + Assert.Equal(expected.Outcome, actual.Outcome); + Assert.Equal(expected.DecodedSummary, actual.DecodedSummary); + Assert.Equal(expected.Error, actual.Error); + Assert.Equal(expected.RequestPayloadBase64, actual.RequestPayloadBase64); + Assert.Equal(expected.ResponsePayloadBase64, actual.ResponsePayloadBase64); + Assert.Equal(expected.SignalSnapshot?.ModuleIdentifier, actual.SignalSnapshot?.ModuleIdentifier); + Assert.Equal(expected.SignalSnapshot?.ModelStepIndex, actual.SignalSnapshot?.ModelStepIndex); + Assert.Equal(expected.SignalSnapshot?.ModelTimeSeconds, actual.SignalSnapshot?.ModelTimeSeconds); + Assert.Equal(expected.SignalSnapshot?.ModelConfigurationIdentifier, actual.SignalSnapshot?.ModelConfigurationIdentifier); + Assert.Equal(expected.SignalSnapshot?.ModelRunIdentifier, actual.SignalSnapshot?.ModelRunIdentifier); + Assert.Equal(expected.SignalSnapshot?.Signals.Count, actual.SignalSnapshot?.Signals.Count); + if (expected.SignalSnapshot is null) + { + Assert.Null(actual.SignalSnapshot); + return; + } + + for (var index = 0; index < expected.SignalSnapshot.Signals.Count; index++) + { + var expectedSignal = expected.SignalSnapshot.Signals[index]; + var actualSignal = actual.SignalSnapshot!.Signals[index]; + Assert.Equal(expectedSignal.SignalIdentifier, actualSignal.SignalIdentifier); + Assert.Equal(expectedSignal.ModuleIdentifier, actualSignal.ModuleIdentifier); + Assert.Equal(expectedSignal.Value.ValueKind, actualSignal.Value.ValueKind); + Assert.Equal(expectedSignal.Value.GetRawText(), actualSignal.Value.GetRawText()); + Assert.Equal(expectedSignal.Unit, actualSignal.Unit); + Assert.Equal(expectedSignal.Quality, actualSignal.Quality); + Assert.Equal(expectedSignal.LogicalTimeTicks, actualSignal.LogicalTimeTicks); + Assert.Equal(expectedSignal.Origin, actualSignal.Origin); + Assert.Equal(expectedSignal.ModelStepIndex, actualSignal.ModelStepIndex); + Assert.Equal(expectedSignal.ModelTimeSeconds, actualSignal.ModelTimeSeconds); + Assert.Equal(expectedSignal.ModelConfigurationIdentifier, actualSignal.ModelConfigurationIdentifier); + Assert.Equal(expectedSignal.ModelRunIdentifier, actualSignal.ModelRunIdentifier); + } + } + + private static string ReadFixture(string name) => + File.ReadAllText(Path.Combine(AppContext.BaseDirectory, "Fixtures", name)); + + private static async Task RenderRoutesAsync(IServiceProvider provider) + { + await using var renderer = new HtmlRenderer( + provider, + provider.GetRequiredService()); + + return await renderer.Dispatcher.InvokeAsync(async () => + { + var component = await renderer.RenderComponentAsync(); + return component.ToHtmlString(); + }); + } + + private static async Task RenderComponentAsync( + IServiceProvider provider, + DiagnosticSession session) + { + await using var renderer = new HtmlRenderer( + provider, + provider.GetRequiredService()); + + return await renderer.Dispatcher.InvokeAsync(async () => + { + var component = await renderer.RenderComponentAsync( + ParameterView.FromDictionary(new Dictionary + { + [nameof(TelemetryRecordingPanel.Session)] = session + })); + return component.ToHtmlString(); + }); + } + + private sealed class ManualTimeProvider : TimeProvider + { + private DateTimeOffset _utcNow = DateTimeOffset.Parse("2026-10-30T12:00:00.0000000+00:00"); + private long _timestamp; + + public override long TimestampFrequency => TimeSpan.TicksPerSecond; + public override DateTimeOffset GetUtcNow() => _utcNow.AddTicks(Interlocked.Read(ref _timestamp)); + public override long GetTimestamp() => Interlocked.Read(ref _timestamp); + + public void Advance(TimeSpan amount) + { + Interlocked.Add(ref _timestamp, amount.Ticks); + } + + } + + private sealed class TemporaryDirectory : IDisposable + { + public TemporaryDirectory() + { + Path = System.IO.Path.Combine( + System.IO.Path.GetTempPath(), + $"autoforge-step07-{Guid.NewGuid():N}"); + Directory.CreateDirectory(Path); + } + + public string Path { get; } + + public void Dispose() + { + if (Directory.Exists(Path)) + { + Directory.Delete(Path, recursive: true); + } + } + } + + private sealed class InMemoryDisplayUnitPreferenceStore : IDisplayUnitPreferenceStore + { + public string? Read() => null; + public void Write(string preference) { } + } + + private sealed class BlockingArchiveStore(ITelemetryArchiveStore inner) : ITelemetryArchiveStore + { + private readonly TaskCompletionSource _saveEntered = + new(TaskCreationOptions.RunContinuationsAsynchronously); + private readonly TaskCompletionSource _saveRelease = + new(TaskCreationOptions.RunContinuationsAsynchronously); + + public Task SaveEntered => _saveEntered.Task; + + public async Task SaveAsync( + TelemetryCaptureSnapshot capture, + CancellationToken cancellationToken = default) + { + _saveEntered.TrySetResult(); + await _saveRelease.Task.WaitAsync(cancellationToken); + await inner.SaveAsync(capture, cancellationToken); + } + + public Task> ListAsync(CancellationToken cancellationToken = default) => + inner.ListAsync(cancellationToken); + + public Task LoadAsync(string captureId, CancellationToken cancellationToken = default) => + inner.LoadAsync(captureId, cancellationToken); + + public void ReleaseSave() => _saveRelease.TrySetResult(); + } + + private sealed class TestNavigationManager : NavigationManager + { + public TestNavigationManager(string uri) + { + Initialize("http://localhost/", uri); + } + + protected override void NavigateToCore(string uri, bool forceLoad) + { + Uri = ToAbsoluteUri(uri).ToString(); + NotifyLocationChanged(forceLoad); + } + } + + private sealed class TestNavigationInterception : INavigationInterception + { + public Task EnableNavigationInterceptionAsync() => Task.CompletedTask; + } + + private sealed class TestScrollToLocationHash : IScrollToLocationHash + { + public Task RefreshScrollPositionForHash(string locationAbsolute) => Task.CompletedTask; + } +}