AutoForge/prompts/Step-07A.md

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.