234 lines
15 KiB
Markdown
234 lines
15 KiB
Markdown
# Step-07A - Source-faithful archives, bounded cleanup and visible failures
|
|
|
|
## STEP IDENTIFIER
|
|
|
|
Step-07A, consolidated correction of original Step-07 R-01 through R-04.
|
|
Step-07 is NOT ACCEPTED. Corrected Step-06 and earlier work remain accepted.
|
|
This is the sole active assignment; Step-08 replay is blocked and not assigned.
|
|
|
|
## STEP TITLE
|
|
|
|
Make valid captures round-trip, invalid archives fail closed with typed errors,
|
|
released capture ownership stay bounded, and storage failures remain visible.
|
|
|
|
## OBJECTIVE
|
|
|
|
Close the existing Step-07 fidelity/validation/lifetime/I/O requirements.
|
|
Preserve the working observation tap, limits, source-close retention, file
|
|
publication and native recording workflow. No format expansion, recorder
|
|
redesign, playback or newly planned feature is assigned.
|
|
|
|
Read [STATE.md](STATE.md), [Step-07](Step-07.md), its preserved
|
|
[report](Step-07-Report.md), [archive guide](../docs/telemetry-archive-v1.md) and
|
|
[WORKER-QUALITY-GATE.md](WORKER-QUALITY-GATE.md). Reproduce the actual failures,
|
|
fix and self-review inside this assignment, write `prompts/Step-07A-Report.md`,
|
|
then STOP.
|
|
|
|
## ARCHITECTURAL CONTEXT
|
|
|
|
Keep all nine projects, one Client, independent Components and existing read-only
|
|
Diagnostics observation -> Application capture/archive -> UI/native storage
|
|
boundaries. No new dependency, host, general lifetime/event framework or
|
|
Simulation oracle. All source/tests stay under `src`, tests under `src/tests`.
|
|
|
|
The source protocol and its comparison/type/unit rules remain authoritative.
|
|
Archive consistency is not authenticity, but that caveat does not waive its
|
|
required shape/coherence validation. No display-unit values replace source data.
|
|
|
|
## CURRENT IMPLEMENTATION STATE
|
|
|
|
Worker-reported Step-07 evidence: clean complete Release build; 179 unit +
|
|
124 integration passes (303 total, zero failed/skipped), exact limit tests,
|
|
225 actual operations beyond the UI trace and native static/dynamic save/
|
|
restart/load/unmount smoke. Retain all of it and all 284 earlier cases.
|
|
|
|
The source review below did not execute a reproduction, application build/test
|
|
or native command. Reinspect Git and preserve existing worker changes/history.
|
|
|
|
## REQUIRED IMPLEMENTATION
|
|
|
|
### R-01 - Accept and preserve observations that the real source accepts
|
|
|
|
[ValidateObservation](../src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/TelemetryArchiveCodec.cs:215)
|
|
requires response bytes for ProtocolError. A real TransportOutcome.Response
|
|
with an empty payload produces ProtocolError and null bytes in the existing
|
|
DiagnosticTraceEntry representation, so that legitimate stopped capture cannot
|
|
serialize/save. Preserve that exact representation; do not invent placeholder
|
|
response bytes or change diagnostic trace semantics to satisfy the codec.
|
|
|
|
Archive snapshot/module/envelope association also uses Ordinal comparisons
|
|
where the source client accepts case-insensitive identities. For example an
|
|
accepted uppercase endpoint module can have an uppercase trace identifier and
|
|
the provider's canonical lowercase decoded module; the codec rejects the pair.
|
|
|
|
Reproduce both with real protocol/session observations and actual archive save/
|
|
new-instance readback. Apply each field's existing source comparison rule,
|
|
preserving all original spellings/bytes. Do not blanket-normalize strings or
|
|
weaken exact unit/signal-ID/version checks.
|
|
|
|
### R-02 - Validate associations before dereference and enforce existing v2 shape
|
|
|
|
Positive read.signals with signalSnapshot null reaches
|
|
[ValidateSignalResponse](../src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/TelemetryArchiveCodec.cs:392)
|
|
before the required association guard, dereferencing null. This must be a typed
|
|
InvalidArchive error that leaves prior inspection intact, never an escaping
|
|
NullReferenceException or a broad catch masking a programming error.
|
|
|
|
The codec compares raw and decoded v2 values to each other but does not fully
|
|
apply the already-defined v2 known-ID/unit/JSON-kind/finite/duplicate/nonnegative
|
|
model-time rules. Editing both sides consistently can therefore load data the
|
|
actual v2 client rejects.
|
|
|
|
Reuse/extract the applicable existing pure validators rather than duplicating a
|
|
second protocol specification. Keep source/trace/context coherence and exact
|
|
known units/types; reject unknown v2 IDs, duplicate signal IDs and negative model
|
|
time. Preserve legitimate v1 nullable/non-numeric/opaque/Unknown values.
|
|
Do not infer missing context from labels/current catalogues or relax v2 itself.
|
|
No archive version bump or new payload format is needed to bypass validation.
|
|
|
|
For semantic regression inputs, adjust raw and decoded data and all necessary
|
|
count/encoded-byte bookkeeping coherently. A rejection caused only by a stale
|
|
byte count is not proof that the intended semantic guard works.
|
|
|
|
### R-03 - Release obsolete capture registrations and make teardown failure-safe
|
|
|
|
[SessionTelemetryCapture.Start](../src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/SessionTelemetryCapture.cs:105)
|
|
registers each capture in
|
|
[DiagnosticSession](../src/AutoForge.Application/Features/Vehicles/Diagnostics/DiagnosticSessionService.cs:100).
|
|
That list retains every capture and its observation buffer until the session
|
|
closes. Stop/discard/replacement do not unregister obsolete owners; repeating
|
|
captures on one still-open source therefore retains unbounded old history.
|
|
|
|
Release obsolete lifetime registrations/subscriptions using the smallest
|
|
existing-boundary change. Cover normal Stop, limit/error stop, discard, saved
|
|
replacement and CloseInspection as appropriate. Do not clear the current stopped
|
|
data still owed to save/inspection, remove source-close draining, or replace
|
|
bounded capture with streaming. Returned immutable snapshots may remain readable;
|
|
the source/workspace must not retain discarded/replaced owners unnecessarily.
|
|
|
|
The controlled Stop-drain test currently releases its blocking observer only
|
|
after assertions. A failure can unwind into subscription disposal while the
|
|
observer still holds the dispatch gate, deadlocking teardown.
|
|
Release barriers in finally before disposing observers/awaiting draining work.
|
|
Audit equivalent new recording-test cleanup paths, not unrelated old suites.
|
|
|
|
Prove release deterministically through actual ownership/registration assertions
|
|
over repeated captures on the same open session, not a timing/memory benchmark
|
|
or sleep-based GC test. Preserve the active dashboard and source behavior.
|
|
|
|
### R-04 - Keep catalogue and actual-panel save failures explicit
|
|
|
|
[ListAsync](../src/AutoForge.Application/Features/Vehicles/Telemetry/Recording/FileTelemetryArchiveStore.cs:112)
|
|
returns empty when Directory.Exists is false, including when its root is an
|
|
existing file. Missing first-use storage may be empty; an invalid/inaccessible
|
|
root or listing I/O failure must be a typed visible failure, not healthy zero
|
|
archives. Test with task-owned files rather than changing user permissions.
|
|
|
|
The [panel SaveAsync](../src/AutoForge.UI/Features/Vehicles/Telemetry/Recording/TelemetryRecordingPanel.razor:256)
|
|
always refreshes after workspace SaveAsync returns. The workspace catches a
|
|
save error into Error/Status, then refresh clears it and can report a healthy
|
|
catalogue. Preserve the save failure through the full actual handler/render path.
|
|
|
|
Refresh automatically only after a genuinely successful save, or use an equally
|
|
explicit typed outcome that cannot erase failure. Do not mark a failed capture
|
|
saved, overwrite the existing archive, silently swallow I/O, or redesign the UI.
|
|
Keep existing pending-command/capture-ID safeguards and successful save/list flow.
|
|
|
|
### Frozen corrective matrix
|
|
|
|
| ID | Input/precondition | Required result |
|
|
|---|---|---|
|
|
| C-01 | Actual empty reply recorded as ProtocolError with null trace response | Stop/save/new-store readback succeeds and preserves the exact error/raw representation, with no decoded successful signals or invented bytes |
|
|
| C-02 | Case-variant endpoint/envelope identities accepted by the existing client | Actual positive result and archive round trip both succeed; original trace/raw/decoded spellings and values are retained using field-specific equality rules |
|
|
| C-03 | Positive read.signals archive with null signalSnapshot | Typed InvalidArchive before dereference/publication; no NullReferenceException, prior workspace inspection remains unchanged |
|
|
| C-04 | Otherwise coherent v2 raw/decoded edits: wrong unit/JSON kind, unknown or duplicate signal ID, or negative model time | Typed rejection at archive boundary, not a mismatched bookkeeping proxy; existing source protocol is not weakened |
|
|
| C-05 | Normal v1 null/non-numeric/opaque/Unknown data, normal v2, nonempty malformed-reply evidence | Original valid capture/readback behavior and all source/raw/context/limit invariants stay intact |
|
|
| C-06 | Repeated stop/save/new and stop/discard on one still-open session; close inspection/source | Obsolete capture registrations/handlers/buffers are not source/workspace-retained; current unsaved stopped data remains saveable and source close still drains |
|
|
| C-07 | Assertion/command failure while a controlled observer is held | Finally releases the barrier before observer disposal/drain; no stranded source/owner/test or unsafe gate wait |
|
|
| C-08 | Catalogue root is a task-owned file; missing directory; controlled list failure | Bad root/I/O is typed and visible, missing first-use directory remains a legitimate empty result; prior valid inspection/catalogue is not falsely replaced |
|
|
| C-09 | Actual panel save event hits write failure or collision; list itself can succeed | Save error remains visible, current capture stays unsaved, existing file stays unchanged; successful retry/save/refresh still works |
|
|
| C-10 | Full existing capture/source/unit/model/native workflow | All 303 baseline cases plus new meaningful coverage, exact original limits and nine-project Release/native baseline pass; replay remains unimplemented |
|
|
|
|
## FILES OR PROJECTS EXPECTED TO CHANGE
|
|
|
|
Existing archive codec and applicable shared Diagnostics validators, narrow
|
|
capture/session registration release, workspace/panel save outcome, catalogue
|
|
I/O classification, focused tests and directly related docs/README.
|
|
Only `prompts/Step-07A-Report.md` under `prompts`.
|
|
No assignment, roadmap/state, gate, historical report or protected-file edit.
|
|
|
|
## INTERFACE AND DEPENDENCY REQUIREMENTS
|
|
|
|
Preserve all source protocol/profile/configuration contracts, immutable snapshots,
|
|
exact source bytes/units/time, one capture owner/cutover, source-close retention,
|
|
single acquisition/physics owners, verified clear and partial discovery.
|
|
Keep 4,096 observations, 16 MiB observation bytes, 1 MiB header, 32 MiB archive
|
|
and depth 128 limits; do not raise limits to hide a failure.
|
|
No new package/project/host, general resource framework, database or replay clock.
|
|
No workload/system restore/install/update/repair/rollback or destructive Git.
|
|
Install/restore nothing absent a genuine chosen-command missing dependency.
|
|
|
|
## TESTING REQUIREMENTS
|
|
|
|
Run actual pre-fix behavioral regressions for R-01..R-04 and report observed
|
|
failures, then corrected results. No compilation failure or invented runtime
|
|
observation counts. The orchestrator's source review is not an executed test.
|
|
|
|
Use real v1/v2 sessions/protocol/observation/capture paths for valid-source cases,
|
|
the real codec and temporary filesystem for archive cases, and actual panel
|
|
event/render evidence for failure visibility. Faults may be injected below the
|
|
feature boundary, not by replacing the recording feature with a mock.
|
|
Exercise coherent invalid archives and deterministic resource-release assertions.
|
|
Release all barriers/files/source subscriptions in finally.
|
|
|
|
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 303 baseline cases (179 unit, 124 integration) plus meaningful new
|
|
assertions. Map necessary presentation-only changes without deleting safety/
|
|
error/source checks. Record exact commands/exits/warnings/per-project counts.
|
|
|
|
Recheck the rebuilt native static/dynamic record/stop/save/restart/load/close
|
|
baseline. Controlled codec/lifetime/I/O tests establish injected edge cases, not
|
|
a claim of native fault injection. Clean only exact task-owned captures/profiles;
|
|
do not reset app data or modify unrelated files/preferences.
|
|
|
|
## DOCUMENTATION REQUIREMENTS
|
|
|
|
Align strict archive/source comparison rules, typed invalid-data behavior,
|
|
bounded registration ownership and visible save/list errors with the actual
|
|
implementation. Preserve original Step-07 results as history; do not downgrade
|
|
the original contract or claim playback/new format/Step-07 acceptance.
|
|
|
|
## ACCEPTANCE CRITERIA
|
|
|
|
| ID | Criterion | Evidence |
|
|
|---|---|---|
|
|
| AC-01 | R-01/C-01/C-02 valid source observations round-trip without data fabrication | Actual pre-fix failures and real protocol/file corrected assertions |
|
|
| AC-02 | R-02/C-03..C-05 invalid data rejects with typed errors and existing v2 semantics, while valid v1/v2 remain supported | Coherent negative vectors, unchanged prior inspection and source/codec regressions |
|
|
| AC-03 | R-03/C-06/C-07 obsolete ownership releases and controlled failure cleanup cannot strand resources | Deterministic repeated-capture registration assertions and finally/drain evidence |
|
|
| AC-04 | R-04/C-08/C-09 I/O failures remain typed/visible through actual store/workspace/panel | Bad-root and actual handler failure/retry/collision tests, no false Saved/empty-success state |
|
|
| AC-05 | C-10 existing 303 cases/limits/source/model behavior, full Release build/tests and native baseline pass | Exact complete worker results and native/control distinction |
|
|
| AC-06 | Original mapping/docs/self-review/history/protection/manual gate satisfied; report saved and worker stops | R-01..R-04 matrix, own post-green source-path review and `prompts/Step-07A-Report.md` |
|
|
|
|
## OUT-OF-SCOPE WORK
|
|
|
|
Playback/seek/speed controls, live disk streaming/crash durability, new archive
|
|
version/unit family, charts/layouts, calibration/AI/hardware, new project/package/
|
|
host and unrelated cleanup. No future assignment, agents, automatic handoff,
|
|
orchestration/shared-gate edit, staging/commit/push or destructive Git.
|
|
|
|
## REPORTING REQUIREMENTS
|
|
|
|
Save `prompts/Step-07A-Report.md` entirely inside exactly one plain triple-backtick
|
|
fence, no language tag/outside content/nested fences. Include identifier/title/
|
|
status, implementation/files/interfaces, R-01..R-04 and C-01..C-10/AC-01..AC-06
|
|
mapping, named actual pre/post results and coherent archive/resource/panel
|
|
assertions, commands/exits/warnings/per-project counts, native versus controlled
|
|
coverage, docs/README, self-review after first green, limitations/deviations/
|
|
blockers and preservation review.
|
|
COMPLETE requires all assigned checks; otherwise report INCOMPLETE/BLOCKED with
|
|
the precise missing criterion. Save and STOP; do not begin Step-08.
|