333 lines
22 KiB
Markdown
333 lines
22 KiB
Markdown
# 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.
|