AutoForge/prompts/Step-04A-Report.md

127 lines
13 KiB
Markdown

```
# Step-04A - Dynamics input, drivetrain and lifecycle integrity
Status: COMPLETE (worker implementation and verification; manual orchestrator acceptance remains pending)
Step-04 was returned for correction and remains NOT ACCEPTED until the orchestrator reviews it. This report records only the Step-04A corrective work. No Step-05 work was started.
## Summary
Corrected the dynamics configuration reference contract, drivetrain coupling/rev-limit behavior, scenario progress and failure presentation, and asynchronous lifecycle ownership. Added independent numerical, controlled-scheduler, rendered UI, and diagnostic-protocol tests. The original Step-04 scenario thresholds and all 190 existing tests were retained. No project, package, host, backend, or physical-vehicle capability was added.
## Root causes and corrections
### R-01 - Typed and atomic configuration-reference validation
The configuration importer allowed unavailable profile/revision and module references to escape through catalog/dictionary exceptions rather than the normal typed configuration-validation contract. `DynamicsConfigurationService.Import` now translates those reference and calibration-conflict failures into `DynamicsConfigurationException` before registration. A rejected import does not alter the catalog. `SimulationPageViewModel.ImportConfiguration` presents that typed error and preserves the selected valid configuration and existing active session/run binding.
Tests cover unknown profile, unknown revision, missing engine/transmission modules, and conflicting calibration references. Rendered integration and native Client checks confirmed visible errors without partial registration or selection/session mutation.
### R-02 - Coupled RPM, launch slip and rev-limit envelope
The old runtime independently capped engine RPM while leaving vehicle speed unchanged, permitting a healthy-looking locked state that violated the wheel/gear equation. Launch torque transfer could also differ from the reported slip, yielding mismatched engine/wheel RPM with reported zero slip.
Running initial in-gear states now require a locked wheel/gear RPM relation within `1e-8` rpm; unsupported initial states and scenario targets outside the top-gear redline envelope are rejected. Upshift thresholds must be within the engine speed limit. The runtime no longer independently clamps healthy locked RPM: scenario throttle is bounded against the target-speed/redline envelope. Launch torque-transfer factor is separate from the reported slip metric, which reflects actual engine/wheel RPM discrepancy. A finite but extreme accepted configuration that overflows model power rolls back to its last valid sample and faults explicitly.
Independent checks cover initial and runtime RPM equations, a high-torque/high-speed variant, a low launch-slip threshold, and a constant-torque force/mass/acceleration calculation. The force-balance and speed-step acceleration comparisons use `1e-10` tolerance.
### R-03 - Truthful progress, terminal failures and lifecycle ownership
Overall progress now retains completed phase duration; current-phase progress is exposed separately and rendered separately. Both are bounded to `[0,1]`, reset to zero, and reach one on successful completion. A missed phase deadline remains Faulted with its reason intact.
Faulted dynamic `read.signals` requests return correlated protocol-v2 negative response `DYNAMICS_RUN_FAULTED`; no zero/empty healthy fallback is serialized. Arithmetic/domain failures roll back state and sample output to the last valid fixed-step snapshot before faulting. UI fault handling clears previously displayed good telemetry rows, preserves the failure notice through refresh, and does not present failure as scenario success.
The run controller owns one cancellable advancement task. Start/resume advances the first fixed step and then waits on the configured pacer. Pause, stop, reset, and disposal cancel and await that owner. A narrow `IDynamicsPacer` seam permits deterministic scheduling tests. UI run reentrancy retains the first cancellation owner; session/run generations invalidate stale results from reset/close/reopen and a close during a pending open disposes the stale session.
## Files touched for Step-04A
- `README.md`
- `docs/README.md`
- `docs/build-and-test.md`
- `docs/simulation.md`
- `docs/synthetic-diagnostics-v2.md`
- `src/AutoForge.Core/Simulation/DynamicsConfiguration.cs`
- `src/AutoForge.Core/Simulation/DynamicsRunStatus.cs`
- `src/AutoForge.Application/Features/Vehicles/Simulation/DynamicsConfigurationService.cs`
- `src/AutoForge.Simulation/DynamicsEngine.cs`
- `src/AutoForge.Simulation/DynamicsDiagnosticProvider.cs`
- `src/AutoForge.UI/Features/Vehicles/Simulation/SimulationPage.razor`
- `src/AutoForge.UI/Features/Vehicles/Simulation/SimulationPageViewModel.cs`
- `src/tests/AutoForge.UnitTests/DynamicsEngineTests.cs`
- `src/tests/AutoForge.IntegrationTests/DynamicsWorkflowTests.cs`
- `prompts/Step-04A-Report.md` (created)
## Before/after regression evidence
Focused pre-fix reproductions were run before the corresponding corrections. They exposed:
- `ConfigurationImport_ReferencesFailThroughTypedValidationWithoutRegistration`: an unknown profile escaped as `VehicleProfileCatalogException` rather than the expected `DynamicsConfigurationException`.
- `DynamicsConfiguration_RejectsInconsistentInitialCouplingAndOverRevStates`: 10 m/s, first gear and 650 rpm was accepted despite inconsistent coupling.
- `DynamicsRuntime_DoesNotReportFalseLockedOrZeroSlipState`: an accepted high-torque/high-speed variant could report locked RPM inconsistent with wheel speed, and a low launch-slip threshold could produce RPM discrepancy with zero reported slip.
- `ScenarioProgress_IsMonotonicAcrossPhasesAndDeadlineFailureIsTerminal`: overall progress moved backward at four phase boundaries; the 0.1-second acceleration deadline did not satisfy the required terminal-failure assertion.
The UI owner-slot defect was traced to assigning a second run's cancellation source before the controller rejected duplicate advancement, allowing the rejected request's cleanup to clear the active owner's slot. The corrected owner/reentrancy behavior is covered by controlled post-fix integration tests.
Corrected focused selections passed:
- Unit selection covering typed import, initial/runtime coupling, progress/deadline, independent force, baseline reproducibility, controlled lifecycle/pacing and non-finite rollback: 8 passed before the final non-finite case was added; final focused follow-up of non-finite rollback, constant-torque force and baseline: 3 passed.
- Integration selection covering typed/atomic UI import, deadline and non-finite failures through v2 diagnostics, overlapping run/cancel, pending open/close, reset/close stale-result suppression, and the original rendered workflow: 6 passed in the final selection.
The full final Release regression retained the 190 Step-04 cases and added 7 unit and 5 integration cases: 122 unit tests and 80 integration tests passed (202 total, zero failed/skipped).
## Numerical and lifecycle evidence
The original warm-baseline thresholds and trajectory remained unchanged and reproducible across equal configurations:
- 3,361 samples / 336.1 virtual seconds.
- Warm idle: 100 samples / 10.0 seconds, final 650.000 rpm.
- Acceleration: 20.1473 m/s reached in 10.3 seconds with four shifts.
- Cruise: all 3,000 samples retained and in the original 45-MPH +/- 1-MPH band while coupled.
- Braking: 0.0000 m/s in 5.8 seconds; return-idle: 10.0 seconds stationary.
- Total modeled fuel: 0.518387 kg; sampled quantities finite and cumulative fuel monotonic.
- Independent locked RPM equation tolerance: `1e-8` rpm. Constant 300 N*m torque force-balance and speed-step equation tolerance: `1e-10` m/s2.
Controlled-pacer tests compared equivalent full virtual sample sequences at 0.25x and 1000x; only delay requests changed. Tests actively paused and proved no step change while a delay was pending, resumed, stopped, reset, restarted, canceled and disposed. UI integration covered duplicate run/cancel, stale reset/close work, delayed open followed by close, and exact original configuration rebinding. A finite but extreme torque/ratio vector produced a Faulted lifecycle with the last valid state/sample retained and a negative v2 diagnostic response.
## Full Release verification
Commands were run sequentially after the final code/test edits:
- `dotnet build .\src\AutoForge.slnx --configuration Release --no-restore` — succeeded, 0 warnings, 0 errors; all nine solution projects built, including the native Windows Client. The MAUI XAML source-generation notice was informational.
- `dotnet test .\src\AutoForge.slnx --configuration Release --no-build` — succeeded: `AutoForge.UnitTests` 122 passed / 0 failed / 0 skipped; `AutoForge.IntegrationTests` 80 passed / 0 failed / 0 skipped; total 202.
No dependency restore or workload change was needed.
## Native Client observations
The rebuilt Windows Client was launched from `src/AutoForge.Client/bin/Release/net10.0-windows10.0.26100.0/win-x64/AutoForge.Client.exe`; its `AutoForge` window responded and its WebView2 page was exercised over a worker-local debugging endpoint. The actual native `/simulation` route:
- Loaded and explicitly selected profile `autoforge.synthetic.test-truck` revision 1, provider `autoforge.simulation.dynamics`, and the warm-baseline configuration `sha256:v1:e8991ae139b54959ec53a4fe64b08dc9bfc03feb533496cf741f2c9f3a2342da`.
- Rejected unknown profile, revision and module JSON references with visible recoverable errors while preserving the original selected configuration.
- Ran a 0.1-second acceleration deadline variant (`sha256:v1:5f0d61a046321131bc5f0c464b8e28082717cc81668c06c1d8c5127e542c422d`). It remained visibly Faulted at step 101 / 10.1 virtual seconds after diagnostic refresh; the failure notice remained and prior telemetry rows were cleared.
- Completed the valid accelerated baseline at step 3,361 / 336.1 virtual seconds. The active runner was separately paused at step 1 and held there while waiting, resumed, stopped, explicitly stepped, and reset into a new step-0 session.
- Read 17 protocol-v2 `SYNTHETIC_DYNAMIC` values at step 0, exported and re-imported the valid configuration, confirmed its active session binding stayed exact, and closed the session.
- Loaded `/diagnostics`, `/vehicle-profiles`, `/execution-targets`, `/`, and an unmatched not-found route. The static route check was a route/render smoke; the prior Step-04 report retains its earlier static diagnostics operational evidence.
The worker-launched Client, its child WebView process and local DevTools listener were closed; follow-up process/listener checks found none. Native observations are distinct from the numerical and controlled-scheduler proof above.
## Acceptance criteria
| ID | Status | Evidence |
|---|---|---|
| AC-01 | PASSED | Typed direct/service validation, atomic catalog behavior, rendered/native errors for profile/revision/module references, and preservation of selected configuration and active run binding. |
| AC-02 | PASSED | Initial and runtime coupling checks, redline rejection/enforcement, independent wheel/RPM and constant-torque force equations, accepted boundary variant, and v2 fault/signal reads. |
| AC-03 | PASSED | Monotonic overall and phase progress, deadline and non-finite terminal faults, rollback/negative telemetry policy, persistent UI error, and explicit cancel/stop/close outcomes. |
| AC-04 | PASSED | Controlled real-pacer tests and UI integration for active freeze/resume/stop/reset/restart/dispose/cancel, overlapping calls, delayed open, and stale-result suppression. |
| AC-05 | PASSED | Original full numerical gates and 190-case regression preserved; final 122-unit/80-integration suite passed; native legacy route smoke and unchanged project graph. |
| AC-06 | PASSED | Actual pre-fix typed-reference, coupling/slip and progress/deadline findings recorded above; corrected focused/full build/test outcomes and required native paths recorded. |
| AC-07 | PASSED | README, documentation index, build/test guide, model/configuration/lifecycle guide, and protocol-v2 fault contract updated. |
| AC-08 | PASSED | Only the required Step-04A report was created under `prompts`; protected assignments, ROADMAP, STATE and prior reports were not edited; no project/dependency/workload or out-of-scope change, stage, commit, push or Step-05 work. |
## Documentation, limitations and preservation
Updated README and directly related configuration/model, protocol-v2, build/test and lifecycle documentation. The model remains synthetic and is not validated real-world prediction, manufacturer calibration, safe tuning advice, vehicle compatibility, physical access or authorization. No ADR was needed because the nine-project architecture and dependency directions were unchanged.
The original Step-04 report remains historical and unmodified. `prompts/Step-04A.md`, `prompts/ROADMAP.md`, and `prompts/STATE.md` were preserved. No agent, handoff automation, Git staging, commit, push, reset or unrelated cleanup was used. Full regression/build passed and the worker stops here; Step-04 acceptance remains the orchestrator's responsibility.
```