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