297 lines
20 KiB
Markdown
297 lines
20 KiB
Markdown
# 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.
|