AutoForge/prompts/Step-04B.md

9.2 KiB

Step-04B - Reject lifecycle starts before mutating an undrained run

STEP IDENTIFIER

Step-04B, focused follow-up to existing Step-04A R-03 / AC-04. Step-04 remains NOT ACCEPTED. This is the sole active assignment; Step-05 is blocked.

STEP TITLE

Make Start/Resume during pending owner cleanup side-effect-free.

OBJECTIVE

Fix one existing lifecycle ordering defect. Do not redo the corrected physics, reference, progress, failure, protocol or UI-generation work. Preserve all 202 current cases and the original numerical thresholds.

Execute only this assignment, write prompts/Step-04B-Report.md, and STOP.

ARCHITECTURAL CONTEXT

Read STATE.md, Step-04A, its report and the prospective WORKER-QUALITY-GATE.md.

Keep the nine-project .NET 10 modular monolith, sole native Client/two RCLs, Simulation-owned implementation and normal Application/UI ports. No new project, package, host, backend or physical capability.

The new shared gate applies to this new work, not retroactively to Step-04A. The defect below is already within that assignment's overlap/one-owner criterion.

CURRENT IMPLEMENTATION STATE

Step-04A corrected R-01 reference errors, R-02 coupling/limits, progress/fault handling and most R-03 ownership/UI issues. The worker reports 122 unit + 80 integration passes (202 total, zero failed/skipped), a zero-warning/error complete Release build, unchanged numerical baseline and native smoke.

One ordering issue remains in DynamicsEngine.cs:

  • StartOrResumeAsync (around line 772) mutates engine lifecycle first.
  • StartRunnerLocked (around line 936) then rejects a still-active task.
  • Pause/Stop/Reset cancel and await that task after releasing the command gate.

A Start/Resume arriving while the prior task is still draining can therefore throw after setting Running. The cancelled old task then exits, leaving a rejected operation's Running state without an owner.

This is source-review evidence; the orchestrator did not execute a reproduction. Reinspect Git/instructions and preserve pre-existing dirty implementation/history.

REQUIRED IMPLEMENTATION

Use the smallest clear ordering/transition guard that validates owner eligibility before any engine lifecycle mutation. During prior-owner drain, this assignment's default policy is explicit side-effect-free rejection; a correctly serialized wait policy is acceptable only if documented/tested and does not deadlock cleanup.

Do not hold a gate across an await if the old runner needs it to finish. Do not paper over the issue with a catch that leaves mutated state, remove the one-owner check, force a second runner or introduce sleeps.

Frozen contract matrix

ID Precondition/action Required outcome
C-01 Stopped/Paused, old owner fully settled, valid Start/Resume Running with exactly one new owner and unchanged configuration
C-02 Pause has cancelled an owner but its cleanup is pending; Resume arrives Rejection before mutation (or documented serialization); no orphan Running state
C-03 Stop or Reset has cancelled an owner but cleanup is pending; Start arrives Same side-effect-free policy; time/step/progress/configuration remain unchanged by a rejected action
C-04 Old cleanup completes, then caller retries normally Valid start/resume works once; no revived old task, extra tick or lost cancellation
C-05 Closed/disposed or invalid lifecycle/duplicate start Existing explicit rejection and intact state/ownership; previous regressions preserved

Audit both Start and Resume through the shared helper and any equivalent start path touched by the fix. All relevant entry points must follow the same ordering rule. Do not expand this into a controller redesign.

FILES OR PROJECTS EXPECTED TO CHANGE

  • Existing DynamicsRunControl guard/ordering in Simulation.
  • Existing unit/real integration tests and narrowly needed test-only pacer helper.
  • Directly related lifecycle/build/README text only if changed or status needs it.
  • Only prompts/Step-04B-Report.md under prompts.

No physics equations/parameters, config/wire schema, provider, feature UI, dependency or project changes are assigned. Do not modify assignments, ROADMAP, STATE, previous reports or protected instructions. No stage/commit/push or destructive Git.

INTERFACE AND DEPENDENCY REQUIREMENTS

Keep existing public control semantics except the corrected failed-transition side effect. Preserve exact run/config/session binding, source/oracle boundaries, single advancement owner, cancellation, progress/failure handling and static/ dynamic diagnostics. No broad catches, fallback states or unauthorized workload install/update/restore/repair/rollback.

TESTING REQUIREMENTS

  1. Add a controlled pacer with a barrier that acknowledges cancellation but holds task cleanup until explicitly released. This is a test-only cancellation-drain interleaving, not a production delay. Release barriers in finally even if an assertion fails, so a failed pre-fix test cannot strand the runner.
  2. Reproduce C-02/C-03 against the current code. Record the actual rejection plus invalid state change, then apply the fix and show the prior state unchanged.
  3. Assert the complete relevant status snapshot and owner/tick behavior, not just exception type. After cleanup, prove C-01/C-04 and no old task revival.
  4. Exercise Pause->Resume, Stop->Start and Reset->Start overlaps; preserve C-05. No Thread.Sleep, Task.Delay polling or probabilistic race/stress assertions.
  5. Use actual control/engine behavior and the existing real service/UI path where affected. Do not mock away the controller under test. A rejected UI action must not be presented as a successful resumed/started run.

Follow the shared worker self-review gate: specifically walk validate-before- mutate and pending-cleanup paths after the first green run. Fix any finding inside this assignment before handoff.

Run focused regressions, then sequentially:

  • dotnet build .\src\AutoForge.slnx --configuration Release --no-restore
  • dotnet test .\src\AutoForge.slnx --configuration Release --no-build

Preserve all 202 baseline cases (122 unit, 80 integration), numerical gates and nine-project/native build. Record exact commands/exit results/warnings/counts. No new dependency or restore is expected absent a real missing-dependency failure.

Native baseline smoke: open the real Client, start an actual run, pause/resume, stop/restart, reset/close and confirm normal state/time/telemetry. The forced cleanup interleaving is controlled-test evidence; do not claim a human-timed click sequence proves it or add a runtime fault console just for native coverage. Stop only task-owned smoke helpers; report limitations honestly.

DOCUMENTATION REQUIREMENTS

Document the exact pending-transition reject/wait policy and side-effect-free failed command behavior in the existing lifecycle guide, plus current worker/ pending-acceptance status and new evidence in README/build guidance as appropriate. Preserve previous numerical metrics/reports and LF Markdown. No new planning file.

ACCEPTANCE CRITERIA

ID Criterion Evidence
AC-01 C-01 through C-05 hold for both Start/Resume and relevant pending-drain transitions; rejection cannot mutate lifecycle or orphan ownership Controlled pre-fix/post-fix status/owner/tick assertions
AC-02 Cleanup/retry/cancel/close remain correct without deadlock, duplicate owner, stale work or UI false success Real control/service coverage and unchanged baseline invariants
AC-03 All 202 cases, original numerical gates, complete Release/native build and required smoke pass Exact commands, warnings, per-project counts and native/test distinction
AC-04 Contract/evidence matrix and worker source-path self-review are complete; docs match the policy Report matrix, self-review summary and changed-document list
AC-05 Scope/protected/history/manual workflow preserved; report saved and worker stops Git/preservation review and prompts/Step-04B-Report.md

Use PASSED, FAILED, NOT EXECUTED or BLOCKED with actual evidence. COMPLETE requires all assigned checks. Do not add new acceptance conditions or features.

OUT-OF-SCOPE WORK

Physics/configuration/protocol redesign, new model features, dashboards, telemetry recording, hardware, tuning/programming, AI/persistence, new projects/packages and unrelated cleanup. All existing safety/prohibited-operation restrictions remain.

REPORTING REQUIREMENTS

Create prompts/Step-04B-Report.md entirely inside exactly one plain triple-backtick code fence, without language tag or outside content. Use no nested fences. Include identifier/title/status, implemented fix, files created/modified, architectural/interface changes (or none), unit/integration coverage and actual before/after results, C-01 through C-05 and AC-01 through AC-05 evidence, build/test commands with exit outcomes/warnings/per-project counts, native distinction, worker self-review, docs/README changes, limitations/outstanding issues/deviations/recommendations and preservation review.

Save the report and STOP. Do not change assignments/roadmap/state, create or begin Step-05, invoke agents, automate handoff, stage, commit or push.