AutoForge/prompts/Step-07.md

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.