343 lines
19 KiB
Markdown
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.
|