13 KiB
13 KiB
# 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.