146 lines
15 KiB
Markdown
146 lines
15 KiB
Markdown
```
|
|
# Step-04 - Deterministic vehicle dynamics and scenario execution
|
|
|
|
Status: COMPLETE (worker implementation and verification; pending manual orchestrator acceptance)
|
|
|
|
## Summary
|
|
|
|
Implemented the explicit, deterministic synthetic dynamics workflow without changing the nine-project .NET 10 modular-monolith shape or adding an executable, backend, service, or project. The existing static diagnostics provider and strict protocol v1 remain available; the dynamics provider is separately selected and uses protocol v2. Configuration selection, run/session identity, lifecycle control, numerical output, and diagnostic telemetry are covered by unit, integration, rendered-route, and native Client checks.
|
|
|
|
The complete Release build and test suites passed, and the required Windows native smoke completed. No Step-05 work was started. Manual orchestrator acceptance remains pending.
|
|
|
|
## Implementation and boundaries
|
|
|
|
- Added immutable format-version-1/model-version-1 `DynamicsConfiguration`, validated model inputs, copied scenario/gear/curve collections, and an exact profile/revision/module/calibration binding. The stable configuration fingerprint is `sha256:v1:` plus lowercase SHA-256 over stable camelCase JSON with the derived fingerprint omitted. Operational run and diagnostic-session IDs are separate.
|
|
- Added the Application configuration catalog/import/export service. Import checks exact required, duplicate, and unknown JSON members and validates compatibility with the selected profile before registration. Export/import preserves the configuration fingerprint. Invalid JSON is reported visibly; it does not become a successful fallback.
|
|
- Added the separate `autoforge.simulation.dynamics` provider, run-control capability, coupled fixed-step engine, scenario runner, and encoded dynamic diagnostic transport. Static `autoforge.simulation.synthetic` continues to provide fixed protocol-v1 data and cannot acquire dynamics control through the static-open path.
|
|
- Added protocol v2 validation and run/configuration/model-time binding while retaining strict v1 static semantics. Paused and stepped module reads identify the same model step; dynamic signals carry source, unit, quality, `SYNTHETIC_DYNAMIC`, step/time, configuration fingerprint, and run identity. Diagnostic capture ticks remain separate from virtual model time.
|
|
- Added `/simulation` for explicit profile/revision/provider/configuration selection, import/export, open/start/pause/resume/stop/reset/step, scenario execution, pacing, visible errors, and a telemetry table populated through actual diagnostic frames. Loading an example does not open or start a run.
|
|
- Reset reopens the original immutable configuration, independent of later catalog selection. Closing/resetting waits for active work and releases the prior run. A disposal/cancellation race found during the final full-suite run was corrected so an in-flight scenario exits cleanly when its controller is disposed; post-disposal control calls still fail explicitly.
|
|
- Corrected the rendered model-version and phase-progress expressions and added integration assertions for their output. Updated the home status notice to describe the now-available synthetic dynamics workflow.
|
|
|
|
Production dependency boundaries remain:
|
|
|
|
- Diagnostics -> Core.
|
|
- Simulation -> Core and Diagnostics.
|
|
- Application -> Core and Diagnostics; it does not reference Simulation implementation.
|
|
- UI -> Application, Components, and Diagnostics.
|
|
- Client -> Application, UI, and Simulation; it composes both providers.
|
|
- Core and Components have no AutoForge project dependencies.
|
|
|
|
The two test projects remain under `src/tests`. No project, shell, backend, or external runtime dependency was added.
|
|
|
|
## Model, clock, and scenario
|
|
|
|
The engine uses SI units and a fixed 0.1-second virtual step (validated supported interval: 0.01-0.5 seconds). Virtual time is derived from integer step count. Pacing from 0.25x through 1000x changes scheduling only. The warmed example uses:
|
|
|
|
- 1,800 kg mass; 0.34 m wheel radius; CdA 0.68 m2; rolling coefficient 0.012; air density 1.2 kg/m3; gravity 9.80665 m/s2.
|
|
- 0.9 drivetrain efficiency; 3.6 final drive; maximum braking force 10,000 N.
|
|
- 650 rpm idle/warm target; 5,000 rpm maximum; 2.5 m/s first-gear launch-slip end speed.
|
|
- Forward ratios 3.5, 2.2, 1.4, 0.9; 4,000 rpm upshift and 1,450 rpm downshift schedules.
|
|
- Torque curve (rpm, N*m): (650,240), (1000,300), (2000,360), (3200,350), (4200,300), (5000,180).
|
|
- Idle fuel flow 0.00045 kg/s; fuel mass per joule 1.2e-7 kg/J; ambient/initial/equilibrium temperature 20/88/90 degC; thermal response rate 0.015 per second.
|
|
|
|
Torque is interpolated linearly between curve points. Wheel force is engine torque times gear ratio, final drive, efficiency, and coupling factor divided by wheel radius. Rolling and aerodynamic loads are `m*g*Crr` and `0.5*rho*CdA*v^2`; braking is bounded by configured maximum force; longitudinal acceleration is net force divided by mass. Speed uses fixed-step forward Euler with a zero lower bound; distance uses trapezoidal integration. Fuel derives from engine power and configured fuel parameters. Temperature uses a documented first-order approximation. When coupled, engine RPM is derived from vehicle speed, wheel radius, gear ratio, and final drive; the explicit launch-slip model avoids claiming locked idle-speed coupling.
|
|
|
|
The ordered baseline is 10 seconds warm idle, acceleration to 20.1168 m/s (45 MPH) with a 60-second limit, the full 300-second cruise hold, braking to at most 0.1 m/s within 60 seconds, and at least 10 seconds stationary return-idle. Scenario controllers bound throttle/brake commands and never assign vehicle speed directly. Non-finite/domain failures fault the run explicitly. Fuel remains finite/nonnegative and cumulative consumption is monotonic.
|
|
|
|
This is a simplified deterministic behavioral model, not firmware emulation, manufacturer prediction, real fuel-economy evidence, emissions analysis, calibration advice, a safe tune recommendation, compatibility evidence, or physical vehicle access.
|
|
|
|
## Numerical and test evidence
|
|
|
|
Exact full Release commands:
|
|
|
|
- `dotnet build .\src\AutoForge.slnx --configuration Release --no-restore`
|
|
- `dotnet test .\src\AutoForge.slnx --configuration Release --no-build`
|
|
|
|
The Release build succeeded with zero warnings and zero errors. It compiled all nine projects: AutoForge.Core, AutoForge.Components, AutoForge.Diagnostics, AutoForge.Simulation, AutoForge.Application, AutoForge.UnitTests, AutoForge.UI, AutoForge.IntegrationTests, and the Windows-targeted AutoForge.Client. Portable projects/tests target `net10.0`; Client targets `net10.0-windows10.0.26100.0`/`win-x64`.
|
|
|
|
The complete test command passed 115 unit tests and 75 integration tests (190 total; zero failed and zero skipped), preserving the Step-03B 183-test baseline. The final focused lifecycle-disposal regression passed, the changed rendered home-route regression passed, and the detailed numerical baseline test passed.
|
|
|
|
The numerical test ran two equal immutable configurations and compared every sampled state (`SequenceEqual`), including lifecycle/scenario outcomes. Actual test output:
|
|
|
|
- 3,361 samples at 0.1 seconds; the full run completed in 336.1 virtual seconds.
|
|
- Warm idle: 100 samples / 10.0 seconds; final engine speed 650.000 rpm, within the 650 +/- 5 rpm gate.
|
|
- Acceleration: target 20.1168 m/s reached at 10.3 seconds and 20.1473 m/s; four scheduled shifts. The test also rejects a per-step speed jump of 0.5 m/s or more.
|
|
- Cruise: all 3,000 required samples retained; 3,000/3,000 (100.000%) within +/-0.44704 m/s (45-MPH +/-1-MPH band); all 3,000 were in the defined coupled regime. Coupled RPM was independently checked against the gear/wheel-radius equation to 1e-8 rpm.
|
|
- Braking: 58 samples / 5.8 seconds; final speed 0.0000 m/s, bounded nonnegative and within the 0.1 m/s limit.
|
|
- Return-idle: 100 samples / 10.0 seconds, all stationary.
|
|
- Final modeled fuel: 0.518387 kg; every sampled rate/value was finite, rates nonnegative, and cumulative fuel monotonic.
|
|
|
|
Relevant regression coverage includes configuration required/unknown/duplicate/version/range/profile validation, fingerprint and interchange behavior, immutability, numerical equations, phase thresholds, coupling and shifts, protocol-v1 preservation and v2 binding/time/origin validation, paused multi-module snapshots, read-without-advance, separate sessions/configurations, reset identity, lifecycle transitions, cancellation/disposal, and rendered real-provider UI workflows.
|
|
|
|
## Native Windows Client evidence
|
|
|
|
Environment: .NET SDK 10.0.402; .NET runtime 10.0.13; Windows SDK target 10.0.26100.0; MAUI Windows workload manifest 10.0.110; WebView2 Runtime 155.0.4283.62. The actual rebuilt Client executable was launched from `src\AutoForge.Client\bin\Release\net10.0-windows10.0.26100.0\win-x64\AutoForge.Client.exe` with a task-local WebView debug port for inspection. It was stopped after verification; PID 33312 exited and port 9335 was no longer listening.
|
|
|
|
Native `/simulation` observations on the rebuilt binary:
|
|
|
|
- Initial page had no selected profile/configuration and no open session. User-triggered profile loading added the synthetic truck but left the profile selection blank.
|
|
- Explicit profile/revision/provider/configuration selection used `autoforge.synthetic.test-truck` revision 1, `autoforge.simulation.dynamics`, and fingerprint `sha256:v1:e8991ae139b54959ec53a4fe64b08dc9bfc03feb533496cf741f2c9f3a2342da`.
|
|
- The rendered model identity showed `autoforge.synthetic.longitudinal v1`; stopped progress showed `WarmIdle (0.0%)`, and after four explicit steps it showed 0.4 seconds / step 4 and `WarmIdle (0.1%)`.
|
|
- Start/pause/step then read 17 protocol-v2 telemetry rows across the engine and transmission at the same paused step/time. All rows showed `SYNTHETIC_DYNAMIC`, units, quality, configuration fingerprint, and run ID.
|
|
- At 1000x pacing the native full scenario completed at step 3361 / 336.1 seconds with 17 telemetry values, four shifts, 0 m/s, and 650 rpm. This native display smoke supplements, but does not replace, the headless numerical proof.
|
|
- Native configuration export produced 2,789 JSON characters. An invalid `{}` import visibly reported the missing required `formatVersion`. Reset then opened a new run/session on the exact same fingerprint at step 0 with `WarmIdle (0.0%)`. Export/import fingerprint preservation was also exercised during the earlier native smoke in this task.
|
|
- The native session was closed.
|
|
|
|
Native `/diagnostics` regression on the rebuilt binary selected the unchanged `autoforge.simulation.synthetic` provider. Discovery showed three expected endpoints, two positive probes/verified identities, and the configured transmission no-response. The engine returned its synthetic DTC `SYN-P0123` and static 850-rpm / 12.6-V values with `SYNTHETIC_STATIC`; the bounded trace retained seven correlated v1 records. The static session was closed.
|
|
|
|
The existing `/execution-targets`, `/vehicle-profiles`, `/`, and unmatched not-found route were visited on the rebuilt Client. Both providers remained visible as metadata; selection did not open a session. The updated home notice accurately describes the available synthetic dynamics scope.
|
|
|
|
## Files created
|
|
|
|
- `docs/synthetic-diagnostics-v2.md`
|
|
- `src/AutoForge.Application/Features/Vehicles/Simulation/DynamicsConfigurationService.cs`
|
|
- `src/AutoForge.Core/Simulation/DynamicsConfiguration.cs`
|
|
- `src/AutoForge.Core/Simulation/DynamicsRunStatus.cs`
|
|
- `src/AutoForge.Simulation/AssemblyInfo.cs`
|
|
- `src/AutoForge.Simulation/DynamicsDiagnosticProvider.cs`
|
|
- `src/AutoForge.Simulation/DynamicsEngine.cs`
|
|
- `src/AutoForge.UI/Features/Vehicles/Simulation/SimulationPage.razor`
|
|
- `src/AutoForge.UI/Features/Vehicles/Simulation/SimulationPageViewModel.cs`
|
|
- `src/tests/AutoForge.IntegrationTests/DynamicsWorkflowTests.cs`
|
|
- `src/tests/AutoForge.UnitTests/DynamicsEngineTests.cs`
|
|
- `prompts/Step-04-Report.md`
|
|
|
|
## Files modified
|
|
|
|
- `README.md`
|
|
- `docs/README.md`
|
|
- `docs/architecture.md`
|
|
- `docs/build-and-test.md`
|
|
- `docs/simulation.md`
|
|
- `docs/synthetic-diagnostics-v1.md`
|
|
- `src/AutoForge.Application/Features/Vehicles/Diagnostics/DiagnosticSessionService.cs`
|
|
- `src/AutoForge.Client/MauiProgram.cs`
|
|
- `src/AutoForge.Diagnostics/ProviderContracts.cs`
|
|
- `src/AutoForge.Diagnostics/SyntheticDiagnosticProtocolClient.cs`
|
|
- `src/AutoForge.Diagnostics/SyntheticProtocolV1.cs`
|
|
- `src/AutoForge.UI/Features/Foundation/AddAutoForgeUi.cs`
|
|
- `src/AutoForge.UI/Features/Foundation/Home.razor`
|
|
- `src/AutoForge.UI/Layout/MainLayout.razor`
|
|
- `src/AutoForge.UI/_Imports.razor`
|
|
- `src/tests/AutoForge.IntegrationTests/UiCompositionTests.cs`
|
|
|
|
## Acceptance criteria
|
|
|
|
| ID | Status | Evidence |
|
|
|---|---|---|
|
|
| AC-01 | PASSED | Immutable exact profile/config/model/scenario inputs, strict interchange validation, stable fingerprint, compatibility checks, and configuration tests/docs. |
|
|
| AC-02 | PASSED | Integer fixed-step time, lifecycle/step/pacing controls, controlled cancellation/disposal regressions, and no diagnostic-read advancement. |
|
|
| AC-03 | PASSED | Separate static-v1 and dynamics-v2 provider/control paths; actual session/config identity, isolation, exact reset, and wrong-path regressions. |
|
|
| AC-04 | PASSED | Coupled force/RPM/gear/road-load/fuel/thermal model, independent coupled-RPM equation check, bounded/nonnegative finite evolution, and shift/idle/brake tests. |
|
|
| AC-05 | PASSED | All 3,361 samples reproduced exactly; 10.0 s idle, 10.3 s acceleration, full 3,000-sample cruise at 100% in tolerance/coupled, 5.8 s stop, and 10.0 s return-idle. |
|
|
| AC-06 | PASSED | Actual encoded v2 requests/responses, run/config/time/source/unit/origin validation, paused shared-step reads, static-v1 regression, and malformed-binding tests. |
|
|
| AC-07 | PASSED | Real Application/UI controls and telemetry, corrected rendered model/progress, explicit user selection, real-provider integration tests, and rebuilt native interaction. |
|
|
| AC-08 | PASSED | Nine-project Release build, 115 unit + 75 integration tests, numerical evidence, rebuilt Windows Client smoke, static regression and preserved routes. |
|
|
| AC-09 | PASSED | README, documentation index, architecture, build/test guide, simulation and protocol-v1/v2 documentation updated with behavior and limitations. |
|
|
| AC-10 | PASSED | Only the Step-04 report was created under `prompts`; protected assignments/state/roadmap/historical reports remained unchanged; no stage/commit/push/Step-05/agent/handoff action. Git whitespace check passed and native helper/listener was stopped. |
|
|
|
|
## Documentation, limitations, and handoff
|
|
|
|
Updated README/index, architecture, build/test evidence, simulation equations/configuration/limitations, and protocol v1/v2 separation. The static diagnostics provider and protocol v1 remain separate from dynamic output. All imported metadata and outputs remain synthetic and process/session-local. No actual vehicle, manufacturer model, physical write, replay, calibration editor, AI, persistence, or hardware adapter is included.
|
|
|
|
No unresolved implementation or verification failure remains. Manual orchestrator acceptance is pending and is not claimed. Protected files were absent from the changed-path list; `git diff --check` passed. No files were staged, committed, or pushed, and no Step-05 or automated handoff was started.
|
|
```
|