# 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.