AutoForge/prompts/Step-04A.md

345 lines
19 KiB
Markdown

# Step-04A - Dynamics input, drivetrain and lifecycle integrity
## STEP IDENTIFIER
Step-04A, corrective assignment for Step-04. Step-04 is NOT ACCEPTED.
This is the sole active assignment. Step-05 is blocked and not assigned.
R-01/R-02/R-03 below are Step-04 findings; prior diagnostic findings remain closed.
## STEP TITLE
Make invalid references, drivetrain limits and run lifecycle/failure presentation
reliable, with independent numerical and controlled scheduling evidence.
## OBJECTIVE
Correct three coupled integrity gaps without discarding the useful default
numerical model or redesigning the product. Preserve exact run/config bindings,
static diagnostics, strict v1/v2 wire handling and all accepted profile/diagnostic
corrections. Keep the nine-project single-Client/two-RCL modular monolith.
You are the WORKER. Execute only this correction, write
`prompts/Step-04A-Report.md`, and STOP for manual orchestrator review.
## ARCHITECTURAL CONTEXT
Read [STATE.md](STATE.md), [ROADMAP.md](ROADMAP.md),
[Step-04](Step-04.md), its [report](Step-04-Report.md), current
[simulation documentation](../docs/simulation.md) and
[protocol v2](../docs/synthetic-diagnostics-v2.md).
Core/shared contracts own input invariants; Simulation owns physics/clock;
Application owns configuration/session features; UI adapts their typed outcomes.
Telemetry still crosses actual diagnostic frames, not a UI oracle shortcut.
No new project, host, backend, package or physical capability is assigned.
Keep application/tests under `src`, tests under `src/tests`, technical docs under
`docs` and all handoffs under `prompts`. Do not modify orchestration files or
historical reports. Handoffs remain manual.
## CURRENT IMPLEMENTATION STATE
Step-04 introduced immutable DynamicsConfiguration, fingerprinted JSON catalog,
coupled engine/transmission/longitudinal model, fixed steps, scenario/controller,
separate dynamics provider/protocol v2 and `/simulation` controls/table.
Static `autoforge.simulation.synthetic` and its v1 behavior remain separate.
Worker baseline evidence reports 115 unit + 75 integration passes (190 total,
zero failed/skipped), clean complete nine-project/native Release build and native
smoke. Its warmed example meets the original idle/acceleration/300-second hold/
stop gates and reproduces 3,361 sampled states. Preserve those meaningful tests
and thresholds; they do not cover the findings below.
The orchestrator inspected source/contracts/tests and reported evidence without
executing application code. Reproduce the actual failures before fixing them.
Inspect Git/instructions and preserve pre-existing dirty implementation/history.
No workload/system installation/update/repair/rollback or new dependency is
authorized. Use the existing supported SDK/runner and ordinary package restore
only when actually necessary.
## REQUIRED IMPLEMENTATION
### R-01 - Keep invalid configuration references in the normal error contract
Locations:
- [DynamicsConfigurationService.cs](../src/AutoForge.Application/Features/Vehicles/Simulation/DynamicsConfigurationService.cs),
Import around line 68.
- [DynamicsConfiguration.cs](../src/AutoForge.Core/Simulation/DynamicsConfiguration.cs),
ValidateAgainst around line 340.
- [SimulationPageViewModel.cs](../src/AutoForge.UI/Features/Vehicles/Simulation/SimulationPageViewModel.cs),
ImportConfiguration around line 106.
A complete JSON document referencing an absent profile/revision throws
VehicleProfileCatalogException outside the handled configuration exception path.
An absent engine/transmission module can throw KeyNotFoundException instead.
The import UI catches only DynamicsConfigurationException, so those input errors
can escape the visible/recoverable validation workflow.
Normalize or explicitly handle these known reference failures at the appropriate
Core/Application/UI boundary, following existing typed-error patterns:
- Missing profile/revision, missing engine/transmission module and conflicting
calibration/reference inputs produce actionable errors identifying the bad
reference. Do not expose a generic unhandled-error banner for ordinary input.
- Failed import cannot register a config, mutate an active run, change its exact
binding or discard the current valid selection/configuration.
- Preserve malformed/duplicate/unknown/member/numeric validation and valid imports.
- Do not add a blanket catch or repair references by choosing another profile,
module, revision, provider or example.
Use real service and rendered-page tests. Preserve the existing correctly typed
static-provider/dynamics-control rejection; do not change unrelated provider
semantics or infer model behavior from unverified vehicle metadata.
### R-02 - Validate and preserve actual drivetrain consistency
Locations:
[DynamicsConfiguration.cs](../src/AutoForge.Core/Simulation/DynamicsConfiguration.cs),
initial-condition/model checks, and
[DynamicsEngine.cs](../src/AutoForge.Simulation/DynamicsEngine.cs),
ResetState, slip reporting and coupled RPM calculation around lines 368/385.
Current code accepts redundant initial speed/gear/RPM without enforcing their
declared coupling relation. Reset publishes zero slip. Example: the default
model with engine running, 10 m/s, first gear and 650 rpm passes validation,
but a zero-slip snapshot requires a different RPM by the documented wheel ratio.
Reading before any step can expose that contradiction.
Runtime code independently caps coupled RPM with Math.Min while leaving
speed/gear/zero slip unchanged. Allowed high-speed/shift configurations can
therefore violate the same equation. A low allowed launch-slip threshold can
also yield reported zero slip while below-idle wheel RPM still uses an uncoupled
engine RPM.
Required behavior:
- Define valid independent initial inputs and supported coupling states; reject
inconsistent redundant inputs or derive them by an explicit documented rule.
Do not silently repair them during a diagnostic read or first tick.
- Across supported initial/runtime states, reported locked/zero-slip behavior
must satisfy `rpm = speed/(2*pi*radius)*60*gearRatio*finalDrive` within the
documented numerical tolerance.
- Handle rev/shift/engagement limits physically within the declared simplified
model or fail explicitly outside its operating envelope. Do not independently
clamp RPM while claiming a locked drivetrain at the unchanged speed.
- Validate necessary cross-parameter ranges or model actual slip consistently.
Do not report zero/locked slip when a different RPM is being imposed.
- Do not game the checks by always marking the drivetrain slipping, teleporting
vehicle speed, filtering bad samples or weakening the baseline cruise gate.
- Preserve valid neutral/engine-off/idle/launch/shift behavior, immutable inputs,
source/config bindings and the original full numerical scenario thresholds.
Reproduce the initial vector above and a reachable high-RPM/low-launch-threshold
case using accepted inputs. If a configuration is genuinely unsupported, reject
it clearly and document the support range rather than return healthy
contradictory telemetry.
Add independent force/mass/acceleration evidence as well as ratio tests. A
constant known torque case can avoid relying on the production interpolation
routine for expected values. Test boundary/variant inputs, not only the default
45-MPH cruise subset.
### R-03 - Truthful progress/failures and owned async lifecycle
Locations:
[DynamicsEngine.cs](../src/AutoForge.Simulation/DynamicsEngine.cs),
phase progress at line 486 and DynamicsRunControl;
[SimulationPageViewModel.cs](../src/AutoForge.UI/Features/Vehicles/Simulation/SimulationPageViewModel.cs),
RunScenarioAsync around line 204 and async controls/telemetry publication;
[DynamicsDiagnosticProvider.cs](../src/AutoForge.Simulation/DynamicsDiagnosticProvider.cs),
failed-state telemetry handling.
#### Progress
Cumulative completed scenario time is immediately reset to zero at each phase
transition. Fix progress so its documented overall/phase meaning is accurate
and monotonic across transitions, within [0,1], with completion/reset semantics
explicit. Reset cumulative counters on reset, not after every completed phase.
Distinguish overall scenario percentage from current-phase progress in the UI;
do not label one as the other.
#### Terminal model/scenario failures
The UI currently calls SetSuccess for a returned Faulted scenario, then a
telemetry read can overwrite the failure with another success notice.
For a simple pre-fix vector, keep the baseline target but set acceleration's
allowed duration to 0.1 seconds. It cannot reach 45 MPH and must remain a visible
failed scenario, never an overall success-shaped result.
- Preserve the terminal failure/reason through automatic telemetry refresh and
control completion; valid remaining/last-known data is not scenario success.
- A non-finite/out-of-domain model failure must not emit positive Good poisoned
telemetry or escape as an unhandled JSON serialization exception. Define a
typed negative or explicitly failed/stale last-valid-snapshot policy.
- Do not substitute zeros/empty success or erase failure to make the frame encode.
Keep model time/snapshot/failure state internally consistent.
- Closing/cancelling is not a successful completed scenario; label it accurately.
#### Async ownership, cancellation and reset
A second RunScenarioAsync call replaces the UI cancellation slot before the
controller rejects it. Its finally block clears the slot, so Cancel can lose
the still-running first operation. Guard reentrancy without losing that owner.
Post-await updates also need current-session/run guards; old work must not
publish status/telemetry into a reset/reopened/closed session.
Exercise and enforce one coherent advancement owner. Active pause/stop/reset/
resume/restart/close must not revive an old paced runner or let a pending delay
retain stale ownership. Reset/stop behavior must not depend on an uncontrolled
wall timer finishing before it can settle. Keep Start/Resume and actual
advancement semantics explicit and truthful rather than treating a state-only
assertion as proof that an active clock was paused.
Introduce the smallest injectable scheduling/time seam needed to test the actual
pacer and lifecycle deterministically. Use verified existing .NET facilities or
a local focused interface in an existing project. Do not create a clock framework
or use wall delays/poll-until-step loops as correctness evidence.
## FILES OR PROJECTS EXPECTED TO CHANGE
- Correct existing Core/Application input-reference/coupling validation.
- Correct Simulation's drivetrain/progress/fault/lifecycle paths as necessary.
- Adapt the existing simulation UI for typed errors, persistent failed outcomes,
reentrancy and current-session/run result publication.
- Extend actual unit/integration/rendered tests with independent numerical and
controlled scheduler cases; minimal test-only helpers are permitted.
- Update README, model/protocol/build documentation and a focused ADR if needed.
- Create only `prompts/Step-04A-Report.md` under `prompts`.
No new project/host/backend/package or unrelated refactor is expected. Do not
modify assignments, ROADMAP, STATE, prior reports or protected Copilot instructions,
or create override instructions. No staging, commit, push, Git initialization/
reset or unrelated worktree cleanup.
## INTERFACE AND DEPENDENCY REQUIREMENTS
Keep the nine-project graph, one Client/two RCLs, Simulation implementation
outside Application/UI, private test oracle and actual v2 diagnostic telemetry.
Preserve strict v1 static behavior, exact dynamics configuration/reset/session
binding, partial probe/identity states, verified DTC clear and all profile fixes.
Use strongly typed inputs/results, immutable configurations and bounded explicit
lifecycle ownership. Do not broaden parser/default/target behavior to hide errors,
or introduce physical/calibration/AI capability.
## TESTING REQUIREMENTS
### Actual pre-fix reproductions
Add focused tests for the findings and run them against the current code before
fixing it. Record actual failing assertions/commands, then corrected runs:
- Complete JSON with unknown profile/revision and missing module references:
actionable handled import UI failure, no partial config or active-run mutation.
- Initial coupled-state mismatch and runtime cap/false-slip vector: no healthy
contradictory state. Assert the independently computed wheel/RPM relation.
- Progress across phase boundaries and short acceleration deadline: progress
cannot jump backwards and Faulted must remain visibly failed.
- Double run/cancel and reset/close/reopen during pending work: active ownership
and current-session presentation remain correct.
If a suggested vector differs in practice, investigate and record real evidence,
not an invented failure or a weakened assertion.
### Numerical and controlled lifecycle matrix
- Valid/invalid direct construction plus JSON/open paths, preserving atomicity.
- Locked/neutral/slipping/limit states before the first tick and across phases,
shifts and parameter boundaries; finite state or explicit supported-domain failure.
- Independent force/mass/acceleration and RPM equations using known inputs;
expected answers must not call the same production functions under test.
- Original idle, <=60 s acceleration, full 300 s cruise >=95% in band, stop/
return-idle and repeatability gates unchanged. Record new actual metrics if
a justified model correction changes the baseline trajectory.
- Use a controlled scheduler to run the real pacer at more than one pacing factor
and compare equivalent virtual-step state sequences. Reads/renders never tick
physics. Pause an actually active runner; advance scheduled time and prove freeze.
- Active stop/reset/resume/restart/dispose/cancel, overlapping UI requests and
delayed old-run replies: no extra stale tick, revived worker, lost cancellation,
deadlock or old-run success in the new session.
- Faulted finite/out-of-domain runs produce explicit lifecycle/diagnostic/UI
outcomes and no healthy serialization fallback or unhandled bad-number encode.
Replace the existing fixed-delay/polling lifecycle correctness checks with
deterministic synchronization/clock control. Do not rely on arbitrary elapsed-
time thresholds or change machine date/time/time zone.
### Full regression and native evidence
Preserve the 190 current cases (115 unit, 75 integration), mapping intentional
contract/presentation changes and adding substantive coverage. Preserve all
accepted static/profile/wire/verification/partial-discovery invariants.
Run focused tests, then sequential full Release verification:
- `dotnet build .\src\AutoForge.slnx --configuration Release --no-restore`
- `dotnet test .\src\AutoForge.slnx --configuration Release --no-build`
The full build includes the real Windows Client/all nine projects. Record exact
commands/exit outcomes, warnings and per-project discovered/passed/failed/skipped
counts. Restore packages only when needed; no workload-changing action.
Launch the actual native Client: import invalid-reference JSON and verify a
recoverable visible error, run a finite deadline-failure scenario and verify its
persistent failure, then run the valid baseline with active pause/resume/step/
pacing/stop/reset, protocol-v2 telemetry, export/import and close. Recheck old
static diagnostics/profile/target/not-found routes. Clearly distinguish native
observations from headless numerical/controlled-scheduler proof.
## DOCUMENTATION REQUIREMENTS
Update README and directly related model/config/protocol/lifecycle/testing docs:
- Reference failure contract and preservation of valid selection/active run.
- Supported initial/coupling/rev-limit envelope, equations and no independent
healthy RPM cap or false locked/slip label.
- Progress definition, terminal-failure telemetry/UI policy, advancement ownership,
async cancellation/reset/current-run guards and scheduling test seam.
- Actual before/after/full-suite/numerical/native evidence and pending Step-04A/
parent Step-04 acceptance. Preserve the original 190-case report/metrics.
Keep LF Markdown and historical reports intact. All dynamics remain synthetic
and unvalidated for real-world prediction/tuning/physical programming.
## ACCEPTANCE CRITERIA
| ID | Criterion | Required evidence |
|---|---|---|
| AC-01 | Missing/conflicting profile/revision/module references are actionable typed/UI validation failures with atomic import and intact active binding | Direct/service/rendered negative and valid cases |
| AC-02 | Initial and runtime supported coupling/limit states are physically consistent or explicitly rejected/faulted, never healthy independent RPM caps/false lock | Boundary matrix, independent wheel/force equations and real v2 reads |
| AC-03 | Overall/phase progress and terminal failure/telemetry/UI outcomes are truthful; failed/closed/cancelled runs cannot become success notices | Phase-transition/deadline/domain-fault and real UI/diagnostic assertions |
| AC-04 | Actual paced lifecycle has one owner, retained cancellation and current-run publication, without stale tick/revival/deadlock across reset/close | Controlled scheduler and active-run/reentrant UI/session tests, no wall sleeps |
| AC-05 | Original numerical gates, repeatability, 190 baseline cases, static diagnostics/profile/wire/clear/discovery and project boundaries retained | Full scenario metrics/sample totals and per-project regression/reference evidence |
| AC-06 | Actual pre-fix failures, corrected focused/full build/test and required native paths recorded honestly | Exact commands, outcomes, counts and native versus headless proof |
| AC-07 | README/model/config/protocol/test documentation matches corrected support envelope and lifecycle | Changed document list and contract/limitations summary |
| AC-08 | Protected/history/manual workflow preserved, no unrelated capability/dependency/workload action; report complete and worker stops | Preservation/Git review and `prompts/Step-04A-Report.md` |
Map every criterion to PASSED, FAILED, NOT EXECUTED or BLOCKED with evidence.
COMPLETE requires all required correction, numerical, regression and native checks.
Do not begin Step-05; acceptance belongs to the orchestrator.
## OUT-OF-SCOPE WORK
Dashboard/gauge framework, telemetry recording/replay/comparison, physical adapters/
vehicles, real manufacturer definitions, firmware/calibration/programming/backups,
AI/research/persistence/cloud, extra hosts/projects/packages, broad architecture
replacement and unrelated cleanup. Physical safety/prohibited operations remain.
## REPORTING REQUIREMENTS
Create `prompts/Step-04A-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; R-01/R-02/R-03 root
causes/fixes; files created/modified; any interface/lifecycle changes; unit/
integration tests and actual before/after evidence; independent numeric metrics/
tolerances/sample totals; exact build/test commands/results with per-project
counts; controlled pacing and native observations; AC-01 through AC-08 mapping;
documentation/README changes; limitations/issues; deviations/recommendations;
and protected/scope/Git preservation review.
Save the report and STOP. Do not modify assignments/roadmap/state, create or begin
Step-05, invoke agents, automate handoff, stage, commit or push.