AutoForge/prompts/Step-03A.md

343 lines
19 KiB
Markdown

# Step-03A - Synthetic wire integrity and verified virtual DTC clear
## STEP IDENTIFIER
Step-03A, corrective assignment for Step-03. Step-03 is NOT ACCEPTED.
This is the sole active assignment. Step-04 is blocked and not assigned.
R-01/R-02/R-03 below are Step-03 findings, not the closed Step-02 findings.
## STEP TITLE
Reject incomplete/ambiguous frames, validate replies before success/trace, and
distinguish a virtual-clear acknowledgement from verified state change.
## OBJECTIVE
Correct three coupled integrity/verification defects in the existing synthetic
diagnostics path, add actual failing-before/passing-after regressions and preserve
the normal workflow and architecture. Do not start dynamics or redesign providers.
You are the WORKER. Execute only this correction, write
`prompts/Step-03A-Report.md`, and STOP for manual orchestrator review.
## ARCHITECTURAL CONTEXT
Read [STATE.md](STATE.md), [ROADMAP.md](ROADMAP.md), original
[Step-03](Step-03.md), its [report](Step-03-Report.md), the
[protocol guide](../docs/synthetic-diagnostics-v1.md),
[simulation guide](../docs/simulation.md) and
[ADR-0004](../docs/adr-0004-synthetic-diagnostics.md).
Keep the nine-project .NET 10 modular monolith, Client -> UI -> Components,
Application -> Core/Diagnostics and Simulation -> Core/Diagnostics. Client is
the sole executable and composes the actual Simulation provider. Normal
Application/UI paths cannot access the internal state oracle.
Only `docs`, `src`, `prompts` are top-level project directories; application/test
projects stay under `src`, tests under `src/tests`. Handoffs remain manual.
Do not invoke agents, automate communication or modify orchestration files.
## CURRENT IMPLEMENTATION STATE
Step-03 added actual provider/session/transport interfaces, a UTF-8 JSON synthetic
protocol, virtual module definitions/state, typed outcomes, static signals,
logical fault timing, bounded trace and the existing UI's `/diagnostics` route.
The provider is `autoforge.simulation.synthetic`, kind Simulation. Explicit
profile/revision/provider/kind opening is separate from target metadata resolution.
The engine virtual module supports DTC clear; its default state contains
`SYN-P0123`. Other modules/session state and profile metadata must remain isolated.
The internal IntegrationTests-only oracle supports independent state assertions.
Worker evidence reports complete nine-project/native Release build with zero
warnings/errors, 108 unit + 53 integration cases passed (161 total, zero failed/
skipped), plus actual native workflow/trace smoke. These covered normal paths and
configured faults, not the vectors identified below.
Findings are from source/contract inspection. The orchestrator did not run
application code/tests. Reproduce them yourself before changing behavior and
report exact evidence; do not label static counterexamples as executed tests.
Inspect Git/instructions and preserve pre-existing dirty implementation, previous
assignments/reports and accepted profile timestamp/evidence fixes. Use existing
SDK/package/runner conventions. No new package, project, workload action,
environment installation/repair/rollback or physical operation is authorized.
## REQUIRED IMPLEMENTATION
### R-01 - Reject incomplete and ambiguous requests before dispatch
Location:
[SyntheticProtocolV1.cs](../src/AutoForge.Diagnostics/SyntheticProtocolV1.cs),
Version at line 45 and TryDecodeRequest at line 82; dispatch occurs in
[SimulationProvider.cs](../src/AutoForge.Simulation/SimulationProvider.cs).
Current deserialization leaves Version at its initializer value 1 if omitted.
Omitted logicalTimeTicks can become zero, and duplicate JSON properties are not
rejected before dispatch. With otherwise valid session/address/service fields,
these frames can reach a state-changing virtual service.
Required behavior:
- Require the explicit wire fields documented for protocol v1. Omitted version
or logical time is malformed, not an instruction to supply a default.
An explicitly supplied zero logical tick remains valid.
- Reject duplicate/ambiguous dispatch or binding fields rather than letting
last-value deserialization select version, service, session, correlation,
address, timing or profile/configuration.
- Preserve request unknown-member rejection and document the field-name/
unknown-field policy. Define consistent presence/ambiguity checks for received
response envelopes and interpreted service objects as well.
- Malformed requests must not dispatch any service or mutate virtual state.
Use the existing explicit malformed/no-response or negative policy consistently;
do not fabricate trustworthy correlation from an ambiguous frame.
- Preserve explicit unsupported-version, unknown-address, service/session mismatch
behavior. A structurally complete version-2 request still receives the existing
unsupported-version failure; it must not be executed or silently treated as v1.
Keep programmatic request construction convenient if useful, but a C# initializer
is not permission to infer a missing wire field. Do not introduce a new schema/
protocol version merely to fix invalid input accepted by the stated v1 contract.
Minimum counterexamples for worker reproduction:
1. Encode an otherwise valid clear.dtcs request for a bound session and remove
version. Current code defaults it to 1 and can clear virtual state.
2. Remove logicalTimeTicks from an otherwise valid request.
3. Use duplicate service properties with conflicting read/clear values, or
duplicate version/correlation fields. Invalid/ambiguous bytes must not decide
an operation by last-value parsing.
Use the real simulation transport and independent oracle to prove that rejected
requests leave DTC state unchanged.
### R-02 - Complete response validation before positive results or trace
Location:
[SyntheticDiagnosticProtocolClient.cs](../src/AutoForge.Diagnostics/SyntheticDiagnosticProtocolClient.cs),
probe decoding/check around lines 35-65, static signal decoding at line 143,
and positive trace/result commitment around line 289.
There are two related gaps:
- Well-formed JSON service payloads can contain semantically invalid data and
still become successful results. For example negative signal logicalTimeTicks
or blank signal identifier/unit are copied into record results. DTC text and
advertised service lists also need appropriate semantic checks.
- A probe naming the wrong module is marked ProtocolError by DiscoverAsync only
after ExchangeAsync has traced it PositiveResponse. Trace and returned result
disagree for the same received bytes.
Required behavior:
- Validate the envelope and complete interpreted service payload before returning
or recording success. Duplicate/ambiguous response properties cannot select a
different meaning through last-property lookup.
- Enforce required nonblank identifiers/text, uniqueness where required by v1,
valid service/quality tokens, source/module identity and valid logical timing.
Static reply time must follow the documented request-time semantics; negative/
inconsistent ticks cannot become a valid snapshot. Preserve explicit unknown
values and legitimate empty DTC collections.
- Validate success/error/data consistency against the documented positive and
negative v1 contract. Contradictory or invalid positive data is ProtocolError,
not successful empty or partially populated data.
- Perform probe identity and service-list validation inside the same validated
exchange path as other decoders. Exactly one truthful exchange trace must show
the failure, retain the actual raw request/reply, and agree with the returned
outcome. Do not leave a positive record then append a contradictory error.
- Preserve actual timeout/no-response/cancelled behavior and no fabricated replies.
Surface expected validation failures as typed, actionable protocol failures;
do not add a blanket catch that hides unrelated implementation bugs.
Use small shared validation helpers only where useful. Do not duplicate alternative
parsers/identity checks in UI or weaken existing profile validation.
Minimum counterexamples: a valid-envelope read.signals reply with a negative tick
or blank ID/unit; a valid-envelope probe naming another module; duplicate response
binding/service fields. Assert no success result/value and no positive trace for
those exchanges. Also cover malformed DTC/service metadata and valid empty data.
### R-03 - Separate acknowledgement from verified clear
Location:
[DiagnosticPageViewModel.cs](../src/AutoForge.UI/Features/Vehicles/Diagnostics/DiagnosticPageViewModel.cs),
line 261. It tests only readback.IsSuccess and announces cleared state even when
that successful readback still contains DTCs.
Required behavior:
- A positive clear response is an acknowledgement, not proof of state change.
The logical clear-and-verify use case succeeds only when a fresh valid readback
confirms the expected empty virtual DTC set.
- Enforce verification in the existing Application/use-case boundary, with UI
adapting its result. Keep low-level protocol acknowledgement distinct from the
verified operation; use the smallest cohesive change, not a generic workflow engine.
- Nonempty readback, failed/malformed/negative readback, timeout, cancellation or
closed session must not produce a verified/cleared success message.
- Report explicit verification failure/uncertainty. If a valid readback returned
remaining codes, retain them as observed data with the failure visible; do not
replace them with a success-shaped empty collection or misleading stale success.
- Acknowledgement count alone must not determine verification. Already-empty
valid modules may clear/read back empty successfully.
- Preserve Simulation-only restriction, exact module/session binding, isolated
state, unsupported-service outcomes, metadata-only profile semantics and the
explicit statement that no physical write occurs.
Reproduce a positive clear acknowledgement that does not change virtual state,
followed by a successful nonempty readback. Use a deterministic faulty transport/
module below the real protocol/application boundary and the independent oracle.
The real UI must show verification failure, not "was cleared and re-read".
## FILES OR PROJECTS EXPECTED TO CHANGE
- Correct existing Diagnostics request/reply validation and trace commitment.
- Add the narrow Application clear-and-verify behavior/result as needed; adapt the
existing UI view model/page without duplicating business verification logic.
- Extend existing unit/integration/rendered tests and minimal deterministic fault
helpers/definitions where needed. No new assembly, host, backend or package.
- Update protocol/simulation/ADR/build guidance, documentation index as needed,
and root README for actual corrective status/contracts/results.
- Create only `prompts/Step-03A-Report.md` under `prompts`.
Do not modify assignments, ROADMAP, STATE, previous reports or protected Copilot
instructions. Do not create override instruction files, initialize/reset Git,
stage, commit, push or discard unrelated changes.
## INTERFACE AND DEPENDENCY REQUIREMENTS
Preserve the nine-project boundaries, actual wire path, explicit provider/profile/
revision/session selection and lack of fallback. Keep normal Application/UI
consumers outside Simulation internals; the test oracle remains internal to
IntegrationTests.
Keep raw immutable payloads, bounded trace/loss, logical reproducibility, state
isolation and accepted profile/schema behavior. Preserve valid v1 exchanges and
error distinctions; document any necessary public contract change precisely.
No clock redesign, physical adapter, dynamics engine or arbitrary packet console.
## TESTING REQUIREMENTS
### Before/after reproduction
Add focused regressions and execute them against the current code before the
fixes. Record actual failing assertions/results, then correct the implementation
and rerun. If a proposed vector behaves differently, investigate and report the
actual evidence rather than inventing a failure.
### Unit and protocol regressions
- Valid v1 round trips still preserve all fields, including explicitly zero ticks.
- Each required field missing/invalid is rejected as specified; exact duplicate/
ambiguous properties cannot select dispatch or response meaning.
- Missing version/tick and conflicting duplicate service/version/correlation
requests do not cause virtual DTC mutation.
- Valid unsupported-version/address/service cases retain their intended failures.
- Semantically invalid signal time/identifier/unit/source/quality, malformed DTC
text and probe metadata, inconsistent positive/error/data and duplicate reply
fields yield typed protocol failures, not positive or partial data.
- Wrong probe module yields matching discovery and trace failure; retain actual
raw reply, exactly one exchange record and no positive record for that exchange.
- Valid identity, DTC empty/nonempty, static signals, negative responses and
bounded trace/outcome/cancellation behavior remain unchanged.
### Real Application/UI integration
Use the actual protocol client, application/session use cases and rendered UI.
Faults may be injected by a small transport/factory decorator around the actual
Simulation transport or a focused supported fault definition. Do not mock the
feature/component under test, bypass the encoded path or add a fake app host.
Verify:
1. Invalid/ambiguous clear frames leave independent oracle state unchanged.
2. Invalid positive/probe replies return failure and trace that same failure.
3. Clear acknowledgement with no state change produces nonempty readback and
explicit verification failure; codes remain visible and unrelated state is intact.
4. Genuine clear plus empty readback is verified; readback failure/timeout/cancel/
protocol error is never verified. Acknowledgement and verification are distinct.
5. Session/target/profile isolation, reset, close, old routes and all accepted
timestamp/optional-evidence behavior remain.
Use robust JSON mutation helpers and assertions that prove the intended field was
changed/removed. Duplicate-field tests must really contain duplicate properties,
not lose the duplication while reconstructing a JSON object in the test helper.
### Full regression and native verification
Preserve the current 161-case baseline (108 unit, 53 integration), add substantive
coverage for all findings, and run sequential complete Release verification:
- `dotnet build .\src\AutoForge.slnx --configuration Release --no-restore`
- `dotnet test .\src\AutoForge.slnx --configuration Release --no-build`
Restore packages only when needed; no workload-changing command is authorized.
The complete build must include the actual Windows Client and all nine projects.
Record exact commands/exit outcomes, warnings and per-project discovered/passed/
failed/skipped counts; no required skip or headless subset reported as full success.
Launch the actual native Client and recheck explicit import/open/probe/read,
successful virtual clear/verified empty readback, trace, an existing visible
failure, reset/close and old routes. New malformed-wire and failed-verification
vectors must be covered through real automated DI/rendered UI tests. If the
existing safe fault composition permits a native failed-verification case,
exercise it too; otherwise explicitly distinguish that rendered fault evidence
from native baseline smoke. Do not add a raw-frame UI/test executable merely
to manufacture native coverage. Report missing prerequisites honestly.
## DOCUMENTATION REQUIREMENTS
Update README and directly related protocol/simulation/ADR/testing guidance:
- Required request/reply presence, field-name/unknown-field policy, duplicate/
ambiguity rejection and no-dispatch/no-state-change for malformed requests.
- Semantic reply validation, failure/value rules and trace/result consistency.
- Clear acknowledgement versus verified empty readback, failure/uncertainty
presentation and Simulation-only limits.
- Actual before/after/full-suite/native versus rendered evidence and Step-03A
worker status versus pending orchestrator acceptance.
Preserve historical reports and LF Markdown conventions. Do not claim the
original 161-case run covered these new vectors. Keep the synthetic/non-vehicle,
static-signal, no-physical-programming limitations clear.
## ACCEPTANCE CRITERIA
| ID | Criterion | Required evidence |
|---|---|---|
| AC-01 | Explicit required/unambiguous v1 request fields enforced before dispatch; invalid frames never mutate virtual state | Missing/default/duplicate vectors through real transport and independent oracle |
| AC-02 | Reply envelope/service semantics validate fully before success, with typed failure and no positive/partial values for malformed data | Valid/invalid response matrix and exact outcome/value assertions |
| AC-03 | Probe identity and other semantic failures produce one truthful exchange trace matching returned outcome and retaining raw bytes | Correlation-specific trace assertions and real discovery integration |
| AC-04 | Logical verified clear distinguishes acknowledgement from empty fresh readback; failed/nonempty/unknown readback cannot be reported verified | Application/real UI fault tests, oracle state and valid positive cases |
| AC-05 | All prior state/session/target/profile/clock/trace/architecture invariants and 161 baseline cases retained | Regression mapping, actual graph/source review and per-project results |
| AC-06 | Actual pre-fix failures, corrected focused/full nine-project build/test and native baseline smoke recorded honestly | Exact commands, outcomes, counts, native/rendered coverage distinction |
| AC-07 | README/protocol/simulation/ADR/test docs accurately describe contract, verification and corrective lifecycle | Changed document list and policy/results summary |
| AC-08 | Scope/protected/orchestration/history/manual handoff preserved; complete report written and worker stops | Preservation/Git review and `prompts/Step-03A-Report.md` |
Map every criterion to PASSED, FAILED, NOT EXECUTED or BLOCKED with evidence.
COMPLETE requires all required correction/regression/native checks.
Do not begin Step-04; acceptance belongs to the orchestrator.
## OUT-OF-SCOPE WORK
Vehicle dynamics/scenarios, real hardware/protocol/driver integration, telemetry
recording/replay, calibration/firmware/programming/backups, AI/research, persistence,
new hosts/projects/packages, clock/scheduling redesign, unrestricted raw-frame UI
and unrelated cleanup. Physical safety/prohibited-operation restrictions remain.
## REPORTING REQUIREMENTS
Create `prompts/Step-03A-Report.md` entirely inside exactly one plain triple-backtick
code fence, without language tag or outside content. Use no nested fences.
Use the same copy-window format for the final chat report.
Include step/title and COMPLETE/INCOMPLETE/BLOCKED status; implemented functions;
files created/modified; R-01/R-02/R-03 root causes/fixes; architectural/interface
changes; unit/integration tests and actual before/after evidence; exact build/test
commands/results and per-project counts; native versus rendered fault observations;
AC-01 through AC-08 mapping; documentation and README updates; limitations/issues;
deviations/recommendations; and protected/scope/Git preservation review.
No unexecuted case may be called passed. Save the report and STOP. Do not modify
assignments/roadmap/state, create or begin Step-04, invoke agents, automate handoff,
stage, commit or push.