stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity

Refactor ElkSharp hybrid routing and document speed path

Browse Source
This commit is contained in:
master
2026-03-29 19:33:46 +03:00
parent 7d6bc2b0ab
commit e8f7ad7652
89 changed files with 13280 additions and 10732 deletions
Download Patch File Download Diff File Expand all files Collapse all files

92
docs/implplan/SPRINT_20260329_007_ElkSharp_document_render_speed.md Normal file
View File

@@ -0,0 +1,92 @@
# Sprint 20260329-007 - ElkSharp Document Render Speed
## Topic & Scope
- Reduce the actual document-processing render path to a sub-15-second generation target for the current document fixture.
- Promote the deterministic hybrid iterative router into the real `LeftToRight` workflow-rendering path without changing Sugiyama-owned node geometry.
- Increase safe parallel repair-candidate construction to use all available CPU cores while preserving deterministic commit order.
- Working directory: `src/__Libraries/StellaOps.ElkSharp/`.
- Expected evidence: renderer-path config changes, focused speed measurements on the document-processing tests, and updated sprint execution logs.
## Dependencies & Concurrency
- Depends on `docs/implplan/SPRINT_20260329_006_ElkSharp_hybrid_iterative_routing.md` for the hybrid router baseline.
- Safe cross-module edits for this sprint are limited to:
- `src/Workflow/__Libraries/StellaOps.Workflow.Renderer.ElkSharp/`
- `src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/`
- `docs/workflow/`
- `docs/implplan/`
## Documentation Prerequisites
- `docs/code-of-conduct/CODE_OF_CONDUCT.md`
- `docs/code-of-conduct/TESTING_PRACTICES.md`
- `docs/workflow/ENGINE.md`
- `src/__Libraries/StellaOps.ElkSharp/AGENTS.md`
- `docs/implplan/SPRINT_20260329_006_ElkSharp_hybrid_iterative_routing.md`
## Delivery Tracker
### TASK-001 - Route actual document renders through the hybrid deterministic path
Status: DONE
Dependency: none
Owners: Implementer
Task description:
- Make the workflow renderer use the hybrid iterative router by default for `LeftToRight` document renders so real document-processing output stops paying the legacy multi-strategy brute-force cost.
- Preserve `TopToBottom` behavior and keep Sugiyama-owned geometry contracts unchanged.
Completion criteria:
- [x] `ElkSharpWorkflowRenderLayoutEngine` explicitly configures hybrid deterministic iterative routing for `LeftToRight` renders
- [x] `TopToBottom` stays on the legacy path
- [x] Focused hybrid parity tests still pass after the renderer-path change
### TASK-002 - Use full-core parallel repair-candidate builds safely
Status: DONE
Dependency: TASK-001
Owners: Implementer
Task description:
- Remove the artificial low CPU cap in iterative local-repair candidate building.
- Keep build work parallel only for independent candidate construction; merge/apply order must remain deterministic.
Completion criteria:
- [x] Iterative config accepts a full-core parallel repair-build budget
- [x] Parallel repair-build scheduling honors the requested budget up to available processor count
- [x] Deterministic hybrid parity tests still pass with the higher parallelism budget
### TASK-003 - Reduce the remaining winner-terminal speed hotspot
Status: DOING
Dependency: TASK-002
Owners: Implementer
Task description:
- Re-measure the actual document-processing layout path after the hybrid/default and full-core changes.
- If the document is still above target, optimize the winner post-slot hard-rule fallback and terminal-closure path without weakening hard-rule quality gates.
Completion criteria:
- [x] The layout-only document-processing test completes in under 15 seconds
- [x] Any new winner-terminal/finalization optimization keeps deterministic ordering and focused regression coverage intact
- [ ] The rendered document artifact test passes on the same fast-path configuration
- [x] Sprint execution log records before/after timings for the document-processing path
## Execution Log
| Date (UTC) | Update | Owner |
| --- | --- | --- |
| 2026-03-29 | Sprint created to track actual document-processing render speed work after hybrid routing landed behind an opt-in flag. | Implementer |
| 2026-03-29 | Workflow renderer now defaults `LeftToRight` document renders to hybrid deterministic iterative routing with `MaxRepairWaves=1` and `MaxParallelRepairBuilds=Environment.ProcessorCount`; focused hybrid/renderer tests stayed green (`5/5`). | Implementer |
| 2026-03-29 | Real layout-only document test hit `14.49s` wall time (`15.12s` total test time) on the reverted low-wave hybrid path, meeting the raw layout-only speed target for that fixture. | Implementer |
| 2026-03-29 | Document-quality checks still failed on the same low-wave path: `DocumentProcessingWorkflow_WhenLaidOutWithElkSharp_ShouldNotBacktrackIntoCheckResult`, `...ShouldKeepDecisionSourceExitsOnDiscreteBoundarySlots`, and `...ShouldProducePngWithZeroNodeCrossings` due to residual entry-angle / target-approach / boundary-slot defects. | Implementer |
| 2026-03-29 | Added hybrid attempt diagnostics so artifact tests now observe targeted local-repair attempts in hybrid mode; experimental exact-restabilization speed fixes were reverted after they pushed layout-only runtime back above target without clearing the geometry regressions. | Implementer |
| 2026-03-29 | Narrowed the hybrid low-wave winner-refinement path: focused terminal closure now caps rounds for restricted passes, shared-lane polish uses lean hybrid cleanup in low-wave mode, hybrid post-slot focus sets are capped deterministically, and tiny restricted boundary-slot repairs now stop after normalization instead of paying full detour closure. | Implementer |
| 2026-03-29 | Current speed gate on the actual document fixture is `13.81s` wall time (`14.36s` total test time) for `DocumentProcessingWorkflow_WhenLayoutOnly_ShouldProduceFinitePositions`; focused guards `...ShouldNotBacktrackIntoCheckResult` and `...ShouldKeepDecisionSourceExitsOnDiscreteBoundarySlots` both still pass on the same fast path. | Implementer |
| 2026-03-29 | The rendered artifact regression is faster on the same configuration (optimize phase ~`11.4s`, total test `16.27s`) but still fails with the pre-existing geometry defects: entry angles `2`, boundary angles on `edge/7` and `edge/27`, target join `edge/32+edge/33`, shared lane `edge/3+edge/4`, and under-node `edge/15`, `edge/20`, `edge/25`. | Implementer |
## Decisions & Risks
- The speed target is for the real document-processing render path, not synthetic hybrid-only stress tests.
- Hybrid mode may become the default only for `LeftToRight` workflow renders in this sprint; `TopToBottom` remains on the legacy path until parity is explicitly proven.
- Full-core usage applies to candidate construction only. Candidate commits and final route application must remain single-threaded and deterministic.
- The current best-performing configuration uses one hybrid wave and full-core candidate builds. That path is fast enough on the layout-only document test but still violates boundary-slot, target-approach backtracking, and entry-angle quality checks on the document fixture.
- The current best-performing configuration now meets the `<15s` layout-only document gate by using a narrower low-wave winner-refinement path, but the rendered artifact test still fails on the same entry-angle, target-join, shared-lane, and under-node offenders.
- Attempt-level hybrid diagnostics are now emitted into `ElkLayoutDiagnostics.IterativeStrategies`, restoring visibility into targeted local-repair activity for artifact tests.
- Reintroducing broader exact restabilization in the winner-terminal path raised the real document runtime into the `34s+` range without clearing the remaining geometry regressions, so that branch was reverted rather than left in the workspace.
- Tiny focused boundary-slot repairs now use an ultra-lean restricted path that stops after normalization. This is acceptable for the speed gate because the remaining quality failures are unchanged, but it is still a tradeoff that should be revisited once the artifact-quality defects are fixed.
## Next Checkpoints
- Keep the single-wave hybrid renderer path and full-core local-repair budget in place while targeting the residual artifact offenders `edge/7`, `edge/27`, `edge/32+edge/33`, `edge/3+edge/4`, and `edge/15`/`edge/20`/`edge/25` with narrower exact repairs.
- Re-run the rendered artifact regression together with the layout-only speed gate and the two focused document guards after each targeted fix.
- Only close the sprint once the document fixture satisfies both the `<15s` layout-only gate and the document-quality checks under the same configuration.