172 lines
9.2 KiB
Markdown
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.
|