# Step-08 - Recorded telemetry replay ## STEP IDENTIFIER Step-08. Corrected Step-07/07A/07B was accepted on 2026-10-30. This is the sole active implementation assignment. Step-09 calibration is blocked. ## STEP TITLE Replay validated saved captures through shared numeric/bar presentation with explicit recorded provenance, deterministic navigation and one playback owner. ## OBJECTIVE One user outcome: open a saved capture and inspect/replay its recorded signals without a vehicle session, original profile catalogue or running model. One primary new contract: a cancellable archive-only playback clock and exact observation-prefix projection. Read [STATE.md](STATE.md), [ROADMAP.md](ROADMAP.md), [archive v1](../docs/telemetry-archive-v1.md), [dashboard contracts](../docs/live-dashboard.md) and [WORKER-QUALITY-GATE.md](WORKER-QUALITY-GATE.md). Make the frozen matrix executable before coding, self-review after the first green run, write `prompts/Step-08-Report.md`, and STOP. ## ARCHITECTURAL CONTEXT Keep all nine projects, one native Client and pure generic Components. Application owns replay loading/control/reduction; UI owns a routed feature and shared presentation. Existing local archive storage and schema-v1 reader are the only data input. No new project, dependency, transport, protocol, schema, physics clock, generic timeline/event framework or global active-vehicle registry. Source/tests remain under `src`, tests under `src/tests`. Use the existing [ExecutionTargetKind.RecordedReplay](../src/AutoForge.Core/ExecutionTargets/ExecutionTargetKind.cs:3) for current replay context, plus a replay-instance identity and capture ID. Retain the archive's original provider/target/session/profile/config/run as original metadata, not a current Simulation/PhysicalHardware connection. Do not fabricate a DiagnosticSession, live provider/feed or verified identity. ## CURRENT IMPLEMENTATION STATE Accepted features supply strict bounded v1 archives, actual raw observations with positive-operation-bound decoded signals, complete/incomplete/error captures, local file list/load, source/diagnostic/model timing and shared unit preferences. Worker baseline: 179 unit + 134 integration passes (313 total, zero failed/ skipped), clean full Release build and native capture/save/restart/readback. The orchestrator did not run those commands. Useful current surfaces: - [ITelemetryArchiveStore](../src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/ITelemetryArchiveStore.cs) and [archive models](../src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/TelemetryArchiveModels.cs). - [Dashboard models](../src/AutoForge.Application/Features/Vehicles/Telemetry/LiveDashboard/LiveDashboardModels.cs) and [live projection](../src/AutoForge.Application/Features/Vehicles/Telemetry/LiveDashboard/LiveDashboardAcquisition.cs). - [Display-unit presentation](../src/AutoForge.UI/Features/DisplayUnits/DisplayUnitPresentation.cs), [generic gauge](../src/AutoForge.Components/LiveDashboardGauge.razor) and [current panel/editor](../src/AutoForge.UI/Features/Vehicles/Telemetry/LiveDashboard/LiveDashboardPanel.razor). Replay does not yet exist. Inspect Git/prior art and preserve accepted source, archive, lifetime, unit and safety behavior. Do not overwrite dirty work/history. ## REQUIRED IMPLEMENTATION ### Frozen contract matrix | ID | Input/precondition | Required result | |---|---|---| | C-01 | Valid saved archive, with original source/profile/model no longer available | Explicit user load produces RecordedReplay context, immutable original metadata and a stopped before-first cursor; no live source operation or autoplay | | C-02 | Four-observation fixture below | Exact recorded prefix/value/quality/error state at each applied count; recorded time is not inferred from diagnostic/model clocks | | C-03 | Time seek between records, backward seek, Next/Previous, First/Stop/Restart | Rebuild only the defined prefix; no future/previous-run cache leaks. Definitions survive same-archive navigation; Stop/First clear values to before-first, not retained future measurements. | | C-04 | Equal-time records, all timestamps zero, empty archive and non-signal operations | Time seek/timed play apply complete due-time groups in sequence; manual Next applies exactly one. Empty/zero duration has no division error or fabricated sample; non-signal records change cursor/inspection, not signal values. | | C-05 | 0.25x/1x/1000x, controlled waits and mid-interval pause/resume | Pacing scales captured elapsed intervals only; pause freezes the exact playhead and resume waits only the remaining interval. Replayed data/results are rate-independent. | | C-06 | Repeated Play, pending Pause/Stop cleanup, close/unmount, delayed old wake or scheduler fault | One owner; repeated active Play is idempotent; competing start/navigation rejects before mutation during drain; no stale publication. Fault is visible, cleanup still works and no orphan Playing state remains. | | C-07 | Invalid/unloaded/closed command, rate NaN/infinity/outside range, invalid seek/ordinal/definition | Typed visible rejection before mutation; previous data/context/definitions/position/rate/ownership intact. No clamping a bad request into success. | | C-08 | Incomplete/Error source capture or end of its retained data | Prominent original completion/reason remains; explicit per-load acknowledgement required before Play/Next/seek. Reaching playback end never turns the source capture Complete or invents lost samples. | | C-09 | Positive/failed read.signals, Unknown/Uncertain/non-numeric/missing/unit-change states | Shared accepted source/quality/range/last-Good rules apply; last-known data is clearly recorded Stale with original sample time. Only the affected module changes; no future fill, interpolation, false zero or fabricated reply. | | C-10 | Zero-to-eight numeric/bar gauges and global unit changes | Reuse shared validated configuration/projection/rendering and accepted conversion/draft rules; exact source units/bounds remain canonical, invalid edits atomic, hides/remounts do not own playback | | C-11 | Failed/cancelled/stale replacement load or overlapping command | Previous validated replay remains intact; replacement allowed only while quiescent. Old load/wake cannot publish after close or a newer generation. No failed load is disguised as a healthy empty replay. | | C-12 | Current Replay versus original archived Simulation/Physical metadata | All primary controls/readouts are clearly recorded, never live/current vehicle evidence; no diagnostic factories/controls, catalogue backfill, model rerun or recording-workspace rebind | | C-13 | Replay operations and live coexistence | Archive bytes/header/values/units/quality/times/raw payloads stay identical; store Save and live diagnostic/physics calls remain zero. Existing 313 regressions and nine-project Release build remain intact. | | C-14 | Actual Client route and saved static-v1/dynamic-v2 captures | Real storage/codec/Application/UI path supports load/play/pause/navigation/units/hide/end/close, including restart without original profiles; native observations distinguished from controlled timing/fault tests | ### A. Archive-only context and load lifetime Add a small factory/feature-owned replay session and a `/telemetry-replay` route with shared navigation. The page owns replay lifetime; closing/unmounting it cancels/drains playback and pending load. Individual gauge components do not. Re-entering the page can create a fresh replay session; no disposed scoped singleton must be reused accidentally. List/load by explicit saved capture ID through the existing real archive store and strict reader. Do not use the recording workspace's current live/unsaved capture as a substitute or change its binding. Loading never auto-plays. Ordinary live-host cleanup on route navigation stays as previously intended; replay actions themselves never operate a live source. A successful new load resets cursor/data/definitions/partial acknowledgement and establishes a new replay identity. Keep valid runtime speed and global display preference. Failed validation/I/O preserves the old replay and exposes the actual error. Loading/replacing while Playing or draining is explicitly rejected: pause/stop and finish cleanup first. Busy load rejects competing commands; cancellation/disposal invalidates its generation before late results. Loaded source completion must be visible throughout. For Incomplete or Error, require a clearly labeled explicit acknowledgement bound to that load/capture before data-producing playback/navigation; inspection/Stop/Close remain allowed. Do not rewrite completion, original target or origin to label replay. ### B. Deterministic recorded prefix and navigation Core playhead is integer TimeSpan ticks in [0, duration], where duration is the last observation's captureElapsedTicks, or zero when empty. UTC start/stop, diagnostic ticks and model time are original metadata, not playback duration. Do not invent an unrecorded trailing interval from UTC or model time. Expose applied observation count (0..N) separately from time. The loaded/rewound/ stopped cursor is **before first**: count 0, position 0, no published values. This differs intentionally from SeekTime(0) if zero-time observations exist. - Next applies exactly the next observation; Previous reconstructs one fewer applied observation. Ordinal navigation reconstructs exactly the requested count, including zero. Set playhead to that last record's elapsed time (or 0). - Time seek applies every observation with elapsed time <= the requested tick, including all ties, and preserves the exact requested playhead between records. - Time-driven play applies all due observations in archive sequence before publishing a coherent prefix. Equal-time records never reorder by module, diagnostic ticks or model time. - Manual navigation requires a fully quiescent Stopped/Paused/Completed player and leaves Paused unless the entire nonempty archive is applied, then Completed. - Stop cancels/drains, then resets to before-first while retaining definitions, loaded archive, speed and acknowledgement. First/Rewind performs the same data reset while already quiescent. Restart is rewind-plus-Play, also quiescent only. Play resumes Stopped/Paused; Completed requires explicit Restart or navigation. - Empty loaded archive has duration zero and no samples; Play/Restart completes immediately without a timer. Seek(0)/Stop/First remain an empty stopped cursor; Next/Previous has a visible no-records rejection. With all records at time zero, Play/Seek(0) applies all; manual Next can pause inside that group. Completion depends on applied count, not position==duration alone. Use prefix reconstruction/reduction bounded by the accepted maximum 4,096 observations. Backward seek resets current/last-Good/module-status caches before replaying the prefix. Never keep a later module value when earlier time has not supplied it. Pre-index binding metadata from actual positive snapshots in the loaded archive, using the same first-observed module/signal/unit/origin rules as accepted live data. This permits configuration before playback and keeps valid definitions editable across seeks. The immutable metadata index contains no current values and does not authorize publishing a future sample. Keep definitions across navigation but show no-sample state when the applied prefix has not supplied their data. Never infer values/bindings from the current vehicle catalogue. Decisive fixture (10,000,000 ticks = 1 second): | Sequence | Capture time | Actual archived operation | |---|---|---| | 1 | 1 s | module A read.signals: 850 rpm, Good | | 2 | 2 s | module B read.signals: 12.6 V, Good | | 3 | 2 s | module A read.signals: 1000 rpm, Uncertain | | 4 | 4 s | module A read.signals: Timeout, no decoded successful signals | Seek 1.5 s applies only #1: A=850 Good, B has no sample. Seek 2 s applies #1..#3: A=1000 Uncertain, B=12.6 Good. Seek 4 s applies all: A retains **850**, the last Good sample, visibly Stale with #1's time/reason; B remains 12.6 Good. Previous from #4 reconstructs #1..#3 and restores Uncertain 1000, not Stale. Before-first clears both. No interpolation/extrapolation/smoothing is assigned. Reduce failures only for the affected read.signals module; probe/identity/DTC/ clear observations advance inspection/time but do not manufacture signal data. Keep actual source quality/time/config/run and raw outcome. Unit/origin changes, missing/non-numeric/Unknown values and no-prior-Good errors follow accepted dashboard semantics. Archive facts themselves are never mutated. ### C. One cancellable playback owner Speed defaults to 1x, accepts finite 0.25x..1000x inclusively and is runtime-only. Change it only while quiescent; while Playing/draining, reject with visible "pause first" behavior and unchanged rate/control value. Use proper binding feedback for rejected UI changes, not a second uncommitted settings state. Use monotonic TimeProvider plus a small cancellable wait seam for deterministic tests; no new clock project/package. Elapsed wall time * selected speed advances the capture-time playhead. Publish states consistent with the applied prefix; smooth animation and a hard real-time SLA are not required. Pause freezes playhead at the request instant, applies the due prefix and cancels/drains the old wait without holding a gate needed by cleanup. Resume rebases from that position, not from the last sample timestamp. For example, from 1.5 s at 2x, the 2 s group is due after 0.25 wall seconds. Pausing after 0.10 wall seconds freezes at 1.7 s; resume needs 0.15 more seconds. Repeated Play while Playing shares the active owner. Any new owner/navigation/ replacement eligibility check precedes state mutation, including after end of data while prior owner cleanup is pending. Use generation/owner guards on every late wait/load publication; no orphan Playing state or duplicate frame. Preserve one shared cleanup completion for repeated Stop/Close as appropriate. Invalid inputs leave prior state intact except explicit error notification. Clock/wait failures become visible Faulted replay with the last committed prefix and original sample state intact, not successful end-of-data. Stop/Close still drains/releases resources; recovery is explicit after cleanup. Use overflow-safe tick arithmetic and bounded individual waits for large gaps, with responsive cancellation, not a negative wrap or silent tail truncation. ### D. Shared presentation and actual UI Reuse/extract small pure gauge definition-validation/projection/rendering helpers from the existing live feature; do not duplicate them or create a dummy live feed/session. Preserve live behavior through its existing tests. The replay context is distinct from live DiagnosticSessionIdentity even if shared value/ definition models are reused. Provide explicit archive selection, partial acknowledgement, Play/Pause/Stop/ Restart/First/Next/Previous, elapsed-time and ordinal seek, speed, playhead/count/ duration and source completion. Numeric/bar gauges retain the accepted in-memory 0..8 editor, exact unit binding, canonical bounds, precision and pinned draft rules. Global units project display only; no archive/layout/cursor persistence. All gauges say recorded/Replay, including Good quality, paused/completed state and last-known values. Show original capture/provider/profile/session/target/ config/run, observation ordinal/capture time and per-sample diagnostic/model time without implying simultaneous modules or a current live vehicle. Raw/decoded inspection shows the current applied observation, with explicit before-first/empty state. Navigation changes the replay prefix, not live state. Reaching the end of partial data means "end of retained data", not source Complete. Hiding/remounting gauges or unit changes cannot start/stop/seek/read the player. Only the replay feature owns its clock/lifetime. Keep keyboard/accessibility/ safe text/error presentation and the existing routes/controls intact. ## FILES OR PROJECTS EXPECTED TO CHANGE Application replay/context/controller/reduction, minimal pure shared gauge helper extraction, UI replay route/navigation and shared renderer/editor adaptation, composition only as needed, focused tests and related README/docs. No new project/dependency, Simulation/Core physics/oracle implementation change, diagnostic transport/provider or archive schema change. Under `prompts`, create only `Step-08-Report.md`. ## INTERFACE AND DEPENDENCY REQUIREMENTS Keep all nine project references and one Client, generic Components, archive-v1 strictness/limits, source bytes/types/units/quality/time, unit preferences, source capture lifetime and existing diagnostic/partial-discovery/verified-clear gates. Current kind is RecordedReplay; original source kind remains immutable metadata. No source/hardware permission, catalogue backfill, arbitrary raw-command execution, cloud/AI, broad catches/silent fallback, invented samples or success-shaped errors. No package/system/workload install/update/repair/rollback, staging/commit/push or destructive Git. Preserve protected/history/orchestration files and dirty work. ## TESTING REQUIREMENTS Map C-01..C-14 to named meaningful tests before handoff: - Build real validated saved v1/v2 archives through the accepted recorder/codec/ temporary filesystem. Then close the sources; replay without original profiles/ configurations. Use a spy/failing live-port composition and archive Save counter to prove zero live operations/model calls/file rewrites. - Assert the four-record fixture, between-time/backward/ordinal seeks, ties, all-zero duration, empty/non-signal data and cleared future value/status caches exactly. Verify metadata-only pre-indexing permits configuration before playback without publishing any future measurements. Test recorded reset/repeated model time without sorting or reconstructing it. - Controlled monotonic time/waits prove rates, mid-gap pause/resume, delayed old wakes, held cleanup, duplicate Play, generation replacement/unmount and faults. Barriers establish ordering; no sleeps/polling or elapsed-performance proxies. Release resources in finally and do not hold cleanup's gate across awaits. - Real DI/rendered controls/editor verify invalid requests/rejections are visible and atomic, partial acknowledgement/end labels, shared units/range/Unknown/ Uncertain/Stale/source context and no data/control action on gauge rerender. - Compare archive bytes and canonical source metadata/definitions before/after repeated playback/seek/unit operations. Preserve the 313 baseline cases; map necessary UI-only assertion changes without deleting safety/error checks. Run focused cases, then sequentially: - `dotnet build .\src\AutoForge.slnx --configuration Release --no-restore` - `dotnet test .\src\AutoForge.slnx --configuration Release --no-build` Build all nine projects/native Client. Install/restore nothing absent a genuine chosen-command missing dependency. Native smoke: real saved static/dynamic captures, no live source open, new route load/step/play/pause/seek/backward/units/gauges/speed/end/partial warning and route close/re-enter. Restart the app and replay again without reimporting profiles. Normal native timing is not controlled interleaving/fault proof. Verify the real app storage root; do not assume LOCALAPPDATA redirects MAUI app data. Clean only exact task-owned captures/profiles; preserve unrelated files/preferences. ## DOCUMENTATION REQUIREMENTS Update README/index/architecture/build guide and replay/dashboard usage: explicit RecordedReplay provenance, before-first versus zero-time seek, tie/prefix/last-Good rules, time sources, rate/owner/drain/replacement policy, partial acknowledgement, source immutability and actual native/controlled evidence. Step-07/07A/07B is accepted; Step-08 worker status stays pending orchestrator review. No interpolation, new recording durability, calibration/AI/hardware or physical vehicle verification is claimed. ## ACCEPTANCE CRITERIA | ID | Criterion | Evidence | |---|---|---| | AC-01 | C-01/C-11/C-12 explicit strict offline load and RecordedReplay provenance, immutable source and atomic replacement | Real file/store/context tests with no catalogue/live fallback and meaningful failed-load assertions | | AC-02 | C-02..C-04/C-08/C-09 exact prefix/navigation/ties/empty/partial/quality behavior | Independent fixture expected values/counts/times/states, no future fill or fabricated samples | | AC-03 | C-05..C-07 single cancellable owner, correct rate/pause/resume/drain/fault and rejection behavior | Controlled time/barrier lifecycle tests with exact playhead and prefix assertions | | AC-04 | C-10 shared gauges/editor/units and honest original/current context in the real UI | Real rendered command/editor failures, preserved canonical bounds/drafts/source fields | | AC-05 | C-13/C-14 all 313 regressions, meaningful new coverage, complete nine-project Release build/native playback pass | Exact commands/exits/warnings/per-project counts, zero-live/write spies and native/control distinction | | AC-06 | Frozen matrix/self-review/docs/README describe actual output/state/time semantics and limits | Named executed cases and own post-green source-path review across producers/consumers | | AC-07 | History/protection/dependencies/manual workflow preserved; report saved and worker stops | Preservation review and `prompts/Step-08-Report.md` | ## OUT-OF-SCOPE WORK Resimulation, live diagnosis/recording changes, hardware/programming/calibration/ AI, interpolation/extrapolation/charts, layout/config/cursor persistence, archive migration/edit/export or new schema/limits/streaming durability, new project/package/host and unrelated cleanup. No future assignment, agents, automatic handoff, orchestration/shared-gate edit, stage, commit or push. ## REPORTING REQUIREMENTS Save `prompts/Step-08-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-14/AC-01..AC-07 matrix with named executed evidence, exact prefix/playhead/rate/negative/lifecycle outcomes and zero-live/ write proof, commands/exits/warnings/per-project counts, native versus controlled coverage, docs/README, own post-green source-path self-review, limitations/ deviations/blockers and preservation review. COMPLETE requires all assigned checks; otherwise report INCOMPLETE/BLOCKED with the precise unmet criterion. Save and STOP; do not begin Step-09.