Files
FreeCADWasmDev/docs/current/EFFICIENCY_STALL_RECOVERY.md
wangdequan 9a7c4f0335 Save FreeCAD Web workspace sources and user validation evidence
IFC native binding remains incomplete; preserve accurate test results.
2026-09-15 22:01:58 +08:00

66 lines
3.0 KiB
Markdown

# Effective-Work Stall Recovery v20
## Baseline
`efficiency-v19-baseline.md` and `.json` contain the fixed 20-cycle per-step
report. It recorded 9 budget-exceeded cycles, zero resumed sessions and:
| Phase | Seconds | Share |
|---|---:|---:|
| First activity wait | 654.3 | 25.8% |
| Post-read interval | 513.6 | 20.3% |
| Initial decision | 365.0 | 14.4% |
| Idle stop | 207.2 | 8.2% |
| Editing | 184.4 | 7.3% |
| Other decision | 137.4 | 5.4% |
| Provider backoff | 118.2 | 4.7% |
| Builds | 101.4 | 4.0% |
| Actual source-read commands | 2.0 | 0.1% |
Post-read intervals include model and service time, not just local computation.
No global speedup is inferred from reducing a timeout or changing the window.
## Confirmed Problems
The same 12 TechDraw commands were repeatedly selected without new results.
The old resize rule required the current manifest to be old enough and the
latest pipeline to belong to that manifest. Replanning regenerated the timestamp;
module handoffs replaced the latest pipeline. These operations hid accumulated
ineffective work from the resize decision.
Business failures also embedded long SVG/geometry output ahead of the useful
exception. String compaction could make the JSON invalid and push the exception
out of the recovery prompt.
## Repairs
- Sum effective no-progress work for the prospective batch across handoffs and
replanning, using bounded existing history rather than repeating source reads.
- Exclude provider-only waits. Reset at relevant progress, including progress
achieved by a smaller batch. Do not shrink ready native work away from its
build/receipt path or apply an old batch's limit to a different candidate.
- Keep all pending records in the queue. Add effective work seconds and the
original candidate identity to batch sizing metadata.
- Share the resize decision between the planner and continuation entry point.
- Parse structured business errors before output compaction. Prioritize the
real error, stack location and failure IDs over geometry payloads, retaining
the original exit code and bounded stdout.
## Actual Replay
`stall-history-replay.json` replays the actual history of batch
`ba7f47d606c45e7f3d5a1645` with a freshly generated manifest timestamp.
It found 541.264 seconds of ineffective work, excluded 393.142 seconds of
provider waits, and chose a four-record limit instead of twelve in 0.002819
seconds. No live queue, progress or completion record was changed by the replay.
Tests verify persistence across handoffs, reset on real progress, provider-wait
exclusion, retention of all 12 pending records, restoration of normal batch size
and preservation of concrete errors despite large geometry output. This proves
the scheduling and diagnosis fixes, not completion of the CAD features.
The combined regression run passed 181 tests. The live planner selected four
TechDraw records with `effectiveNoProgressSeconds=541.264` and retained the
original candidate identity. Scheduler PID 1966768 subsequently loaded v20
with a matching source fingerprint and continued at cycle 5059.