20 KiB
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, ROADMAP.md and
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 owns source lifetime resources and actual protocol operations.
- ProviderContracts defines source/signal/trace contracts; its UI trace buffer retains only 200 entries.
- SyntheticDiagnosticProtocolClient 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-restoredotnet 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.