# Step-07 - Bounded telemetry recording and archive readback ## STEP IDENTIFIER Step-07. Corrected Step-06/06A was accepted on 2026-10-30. This is the sole active implementation assignment. Replay is Step-08 and blocked. ## STEP TITLE Capture real session diagnostic observations independently of widgets, then explicitly save and reopen a source-faithful bounded archive. ## OBJECTIVE One user outcome: record an explicit static/dynamic session's diagnostic activity and verify the saved capture through real local readback. One primary new contract: a bounded session-owned capture window, independent of live widget lifetime and faithful to actual diagnostic observations. This is bounded in-memory capture plus save after Stop, not live disk streaming, crash durability, unlimited history or playback. The former recording/replay envelope was split prospectively; do not implement Step-08 controls here. Read [STATE.md](STATE.md), [ROADMAP.md](ROADMAP.md) and [WORKER-QUALITY-GATE.md](WORKER-QUALITY-GATE.md), establish the frozen matrix before coding, self-review after the first green run, write `prompts/Step-07-Report.md`, and STOP. ## ARCHITECTURAL CONTEXT Keep all nine projects and one native Client. Diagnostics may expose a narrowly scoped read-only operation-observation port; Application owns capture/archive use cases and validation; UI owns the reusable recording/inspection controls. Client composes real app-local storage. Components stays generic and independent. No new project, dependency, host, general event bus or storage framework. Use built-in .NET JSON/I/O/time primitives and existing helpers. All source/tests remain under `src`, tests under `src/tests`. No root artifacts/test directory, protected-file edit, staging/commit/push or automatic worker handoff. ## CURRENT IMPLEMENTATION STATE Accepted features already provide immutable session identity, actual synthetic protocol v1/v2 results, static/dynamic signals, strict source validation, raw trace snapshots, one dashboard acquisition owner, real shared UI and Imperial/ Metric display preferences. Worker baseline: 179 unit + 105 integration passes (284 total, zero failed/skipped), clean full Release build and native evidence. The orchestrator did not execute those commands. - [DiagnosticSession](../src/AutoForge.Application/Features/Vehicles/Diagnostics/DiagnosticSessionService.cs) owns source lifetime resources and actual protocol operations. - [ProviderContracts](../src/AutoForge.Diagnostics/ProviderContracts.cs) defines source/signal/trace contracts; its UI trace buffer retains only 200 entries. - [SyntheticDiagnosticProtocolClient](../src/AutoForge.Diagnostics/SyntheticDiagnosticProtocolClient.cs) validates replies/typed results before committing an operation's trace. - Existing diagnostics/simulation hosts and dashboard feed supply explicit sessions; no recording/archive implementation exists yet. Inspect Git and prior art before editing. Preserve all accepted behavior, existing dirty work, original assignments/reports and orchestration files. ## REQUIRED IMPLEMENTATION ### Frozen contract matrix | ID | Input/precondition | Required result | |---|---|---| | C-01 | Start on an open actual session with prior trace history; no new operations | New empty capture with explicit source; prior history is excluded. Start/Stop never discover, poll, step or change the source. Empty stopped capture is valid. | | C-02 | At least 225 real operations occur after Start while UI trace capacity is 200 | All in-window operations appear exactly once in capture order with matching correlation/outcome/raw bytes; UI trace still drops old entries normally. No trace polling or post-hoc dropped-record reconstruction. | | C-03 | Paused v2 source, actual reads, controlled capture time, unit toggles/hide/unmount | Capture elapsed time, diagnostic ticks and model step/time stay distinct; actual source values/units/config/run are retained. Widget/unit changes add no reads, owner or physics steps. Static v1 also works. | | C-04 | Positive, negative, timeout, no response, cancellation and malformed reply | Actual outcome/error and received raw bytes are preserved. No response bytes or decoded successful signals are invented for failed operations. Existing source operation results remain unchanged by recording. | | C-05 | Repeated Start, competing Start/Stop, pending observation during Stop | Same active owner/capture on repeated Start; Stop defines a drainable cutover. Conflicting Start rejects before mutation during drain; no old callback enters a later capture. | | C-06 | Source close/reset/scope disposal; then a new session/capture | Old capture stops/detaches and remains inspectable/saveable with old source context; new capture starts empty. Unsaved data is not silently discarded and old responses never appear as new-source data. | | C-07 | Count/encoded-byte/header/file limits below, including exact boundary and one over | At the limit the valid prefix is retained; exceeding capture capacity explicitly faults/stops with Incomplete/LimitExceeded, never silent truncation/healthy completion. Oversized header/start/load rejects before mutation. | | C-08 | Explicit save of stopped capture, then new process/service/store readback | Real persisted archive returns byte-identical raw payloads and value/type/unit/quality/time/context-identical decoded signals/counts. No reference to the original live session/profile catalog or in-memory object is required. | | C-09 | Invalid/truncated/unsupported/duplicate/unknown/incoherent archive data | Typed visible rejection before replacing a prior loaded capture. Valid intentionally incomplete captures remain visibly incomplete; a truncated file is not accepted as one. | | C-10 | Save collision, cancellation or I/O failure; stale completion after conflicting action | No existing archive overwritten, partial file published, false Saved state or newer capture marked saved. Prior data remains intact; pending commands and cleanup have an explicit safe policy. | | C-11 | Both real host workflows record/stop/save/close/load/inspect | Shared Application capture/storage and actual providers are used. Recording survives gauge invisibility; archived inspection is clearly not live data or playback. | | C-12 | Existing model/wire/UI/unit/source safety and full verification | All 284 cases/invariants preserved with meaningful new coverage, complete nine-project Release build/tests and native capture/save/readback smoke. No replay or hardware capability is introduced. | ### A. Observe actual operations, not the bounded UI trace Add the smallest provider-neutral read-only observation seam at the actual validated operation/trace commitment path. It must include the operation's trace identity/service/outcome/error/raw request/optional response and its actual decoded SignalSnapshot for a positive read.signals result. Every in-window trace-producing operation is captured once, including discovery exchanges/manual reads, not only dashboard cycles. No observing the UI buffer by periodic snapshots, hidden acquisition loop, guessed payload decoding or engine oracle. Preserve the existing 200-entry buffer and dropped count independently. Decoded signals must be attached to their own operation, not a later "latest" snapshot. A non-positive/non-read.signals operation has no successful signal snapshot. Original v1 nullable/non-numeric/Unknown values are legitimate captured data; v2 keeps its existing strict shape and actual model/config/run metadata. Record exact source units, not converted labels/rounded display strings. Publish immutable defensive snapshots with a defined observation order. Define Start/Stop subscription cutover and in-flight draining explicitly; do not reorder by model time, infer simultaneous modules or expose arbitrary command access. Recorder capacity/failure must be visible to its caller without corrupting the diagnostic operation result/trace or blocking cleanup under a shared gate. ### B. One bounded capture owner per actual session Use the existing explicit session, not a new active-vehicle registry/open workflow. Repeated acquisition shares one capture owner or rejects duplicate ownership before mutation; repeated Start on that active owner is idempotent. Use the session lifetime/resource mechanism for close/reset/disposal. Capture only the interval after Start commits and before Stop's defined cutover. Stop drains accepted callbacks and freezes an immutable result; it never pauses/ steps/resets physics or stops the existing dashboard feed. Close/reset ends the old capture and preserves its frozen data for explicit save/inspection. Keep at most one unsaved capture in the owning feature: new capture/replacement requires explicit save or discard of that unsaved result. A new source never inherits old values. Widget hiding/unmounting affects only view subscriptions. Save/load results are capture-ID/generation-bound; reject conflicting pending commands before mutation or serialize them without deadlocking source cleanup. Fixed first-slice limits, not new user settings: - At most 4,096 observations. - At most 16 MiB total compact UTF-8 encoded observation bytes, measured by the actual archive observation encoding, not an approximate raw-payload count. - At most 1 MiB encoded header; at most 32 MiB complete archive input/output. MiB means 1,048,576 bytes. Bound archive parsing depth at 128. Test exact boundaries. A rejected next observation stops/faults capture with a visible limit reason; retain the valid prefix as Incomplete, never pretend it covers later traffic. Allow explicit **Save partial capture**, distinctly labeled. Do not silently drop, overwrite oldest records, claim unknown later loss counts, or make a source request fail merely because recording reached its limit. Use a small controllable time seam (existing .NET TimeProvider is sufficient) for nonnegative nondecreasing captureElapsedTicks in TimeSpan ticks since Start. Keep this observational timeline separate from diagnostic/model clocks; paused models may have repeated model time, and real resets must not be "repaired." ### C. Strict source-faithful archive and actual local persistence Define/document schema v1 before implementation. Root fields are exactly schemaVersion, header, observations and completion in camelCase. The header carries capture identity, original session/profile/revision/vehicle/ provider/target identity, actual synthetic protocol name/version, optional dynamics config/run identity, source endpoint identities and start UTC metadata. Completion carries stop UTC/reason, complete-versus-incomplete/error state and actual observation count. Unknown nullable metadata is explicit null. Each observation has contiguous capture sequence, captureElapsedTicks, its original trace metadata/logical ticks/raw request/nullable response and the associated decoded signals or explicit null. Store raw bytes reversibly (base64) and JSON signal values without coercion/rounding; retain unit/quality/origin and actual per-sample diagnostic/model/config/run context. The reader validates required/version/duplicate/unknown schema properties, defined enums, strict types/base64, lengths/counts/order/times, source/context coherence and positive-read/raw/decoded associations before publishing a result. Reuse/extract existing pure validators where useful, not new wire semantics. Schema-object rules do not reject arbitrary properties inside an opaque v1 signal's JSON value. Preserve malformed reply bytes for recorded ProtocolError; they are evidence, not a reason to reinterpret the operation as successful. Use complete explicit-offset UTC timestamps, not ambient date/time inference. Never backfill identities/units/model time from current profiles/configuration. File readback establishes archive consistency, not manufacturer truth, current vehicle state or cryptographic authenticity. Persist only after capture stops, on an explicit Save. Use an Application storage port with a real local filesystem implementation rooted in the app's recordings directory; Client supplies app-local root/composition. Portable tests use actual isolated files through that implementation, not a mock archive store. Use generated/validated opaque capture IDs for filenames, never source strings or arbitrary paths. Write a task-owned temporary file, flush/close, then publish without overwriting an existing final archive. On failure/cancel leave prior archives intact and surface typed errors; incomplete temporary files are not catalogued as successful captures. Corrupt matching archives/read failures are visible, not silently skipped as an empty successful list. No SQLite/package, file-dialog framework, live streaming or crash-recovery engine is assigned. Capturing data is memory-only until explicit successful save, and the UI/docs must say so. No user-data directory reset or unrelated file cleanup. ### D. Real reusable UI and inspection Compose shared recording controls into the existing static and dynamic workflows without replacing their session/dashboard controls. Provide explicit Start/Stop, counts/bytes/limits/unsaved status, Save (or clearly partial Save), explicit in-memory Discard, saved-capture selection/load and source/raw/decoded inspection. Frozen data remains reachable for Save after source close; do not hide the only copy with the live-session panel. Show the archive source, completion/loss reason, count/timing and selected observation's raw/decoded facts. Empty captures have an explicit empty state. A loaded capture must not rebind the live source or appear as live gauges; playback is not implemented here. Keep large payload details on demand rather than rendering all records on every source event. Preserve accepted Imperial/Metric preferences; archive/source inspectors expose original units. Captures may contain sensitive vehicle/source data: remain local, with no external upload, AI use, telemetry transmission or new hardware access. ## FILES OR PROJECTS EXPECTED TO CHANGE Minimal Diagnostics observation contracts/client tap, narrow session-lifetime exposure, Application telemetry recording/archive/storage, shared UI controls/ inspection, Client storage DI, focused tests and related README/docs. No new project/dependency or Simulation/Core physics/oracle implementation change. Under `prompts`, create only `Step-07-Report.md`. ## INTERFACE AND DEPENDENCY REQUIREMENTS Keep the nine-project graph, one Client, pure Components and Application/UI -> Diagnostics ports. Preserve exact v1/v2 wire/profile/config contracts, partial discovery/verified clear, raw trace semantics, source isolation, model clock and single advancement/acquisition owners. Recording cannot authorize operations. No display-unit values in source archives, broad catches/silent fallbacks, hidden source substitution or success-shaped loss/I/O handling. No workload/system restore/install/update/repair/rollback or destructive Git. Do not edit assignments, ROADMAP, STATE, shared gate, history or protected files. ## TESTING REQUIREMENTS Implement C-01..C-12 with named meaningful assertions: - Actual v1/v2 protocol/session and observation/capture integration; verify more than 200 real operations, exact once/order/raw bytes and positive signal binding. - Controlled time, limits and pending callback/Stop/close/reset interleavings; failure-safe finally cleanup; no sleeps/polling as correctness proof. Boundary tests may drive the real capture accumulator through its observation port; do not mock away the recorder. - Actual temporary filesystem save/new-instance readback, strict invalid-archive vectors, collision/write/read/cancel failure and no published partial archive. Compare raw bytes, JSON value kinds/data, all identity/unit/quality/time metadata and complete/incomplete counts, not merely a filename or successful parse. - Real DI/rendered controls in both hosts, unsaved old-source retention, visible limit/I/O errors and no hidden reads/model changes; all source/unit regressions. 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 284-case baseline (179 unit, 105 integration) plus meaningful new coverage. Map intentional UI assertion changes without deleting safety checks. Build all nine projects/native Client. Install/restore nothing absent a real missing-dependency failure. Native smoke: real static and paused dynamic sessions, record actual activity while gauges hide, stop, save, close/reopen app and load/inspect the saved capture; confirm source/raw/decoded context and unchanged model/unit preferences. Check source close/reset leaves a stopped inspectable capture and old routes still work. Native need not force all limit/fault vectors; distinguish controlled proof. Use/clean only exact task-owned test files/profiles, not unrelated saved captures. ## DOCUMENTATION REQUIREMENTS Update README/index/architecture/build guide and a concise archive-v1/recording guide: exact schema/limits/capture cutover, complete/incomplete states, three time concepts, local source-sensitive storage, explicit Save and memory/crash limitations, failure/corrupt-file behavior and actual verification evidence. Step-06/06A is accepted; Step-07 worker status stays pending orchestrator review. Step-08 replay, long streaming, hardware and manufacturer validity are not claimed. ## ACCEPTANCE CRITERIA | ID | Criterion | Evidence | |---|---|---| | AC-01 | C-01..C-04 actual source-faithful observation capture beyond bounded trace, with no hidden acquisition/model effects | Real v1/v2/raw/decoded/outcome/time tests and exact counts | | AC-02 | C-05..C-07 one bounded owner, explicit cutover/loss/limits/close and retained unsaved source | Controlled lifecycle/exact-boundary/state-preservation tests | | AC-03 | C-08..C-10 strict consistent archives and real atomic source-faithful save/readback | New-instance filesystem round trips, invalid data and I/O/collision/cancel assertions | | AC-04 | C-11 actual shared UI/native recording/inspection with honest saved/partial/source labels | Real DI/rendered/provider and native restart/readback evidence | | AC-05 | C-12 all 284 cases/invariants, new coverage, complete nine-project Release/native build and required smoke pass | Exact commands/exits/warnings/per-project counts; native/control distinction | | AC-06 | Frozen matrix/self-review/schema/docs/README match actual behavior and limits | Named executed cases, exact threshold/output shapes and own post-green source-path review | | AC-07 | History/protection/dependencies/manual workflow preserved; complete report saved and worker stops | Preservation review and `prompts/Step-07-Report.md` | ## OUT-OF-SCOPE WORK Playback/seek/speed/replay provider or clock, resimulation, live disk streaming/ crash durability/unlimited capture, charts/layout persistence, calibration/AI/ hardware, database/new package/project/host and unrelated cleanup. No future assignment, agents, automatic handoff, orchestration/shared-gate edit, stage, commit or push. ## REPORTING REQUIREMENTS Save `prompts/Step-07-Report.md` wholly inside exactly one plain triple-backtick fence, no language tag/outside text/nested fences. Include identifier/title/status, functions/files/interfaces, C-01..C-12/AC-01..AC-07 matrix with named executed evidence, exact archive shapes/limit/lifecycle/I/O results, commands/exits/ warnings/per-project counts, native versus controlled coverage, docs/README, own source-path self-review after first green, limitations/deviations/blockers and preservation review. COMPLETE requires all assigned checks; otherwise use INCOMPLETE/BLOCKED with the precise unmet criterion. Save and STOP for manual review. Do not begin Step-08.