AutoForge/prompts/Step-04B.md

172 lines
9.2 KiB
Markdown

# 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](STATE.md), [Step-04A](Step-04A.md), its
[report](Step-04A-Report.md) and the prospective
[WORKER-QUALITY-GATE.md](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](../src/AutoForge.Simulation/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.