Refactor ElkSharp routing sources into partial modules

docs/implplan/SPRINT_20260323_002_ElkSharp_bounded_edge_refinement.md

@@ -147,6 +147,19 @@ Completion criteria:
 - [x] Left-to-right placement spacing derives from an average-node-size placement grid rather than the edge-routing lattice alone
 - [x] The document-processing artifact render revalidates with zero selected shared-lane violations and no new boundary-angle or target-join regressions
 
+### TASK-011 - Decompose oversized ElkSharp sources
+Status: DONE
+Dependency: TASK-010
+Owners: Implementer
+Task description:
+Split the oversized active ElkSharp implementation files and the directly coupled Elk-specific renderer test files into concern-based partial classes so the routing logic stays behaviorally stable while the code tree becomes easier to navigate and extend.
+
+Completion criteria:
+- [x] `ElkEdgePostProcessor` is decomposed into concern-based partial files under `src/__Libraries/StellaOps.ElkSharp/`
+- [x] `ElkEdgeRouterIterative` is decomposed into concern-based partial files under `src/__Libraries/StellaOps.ElkSharp/`
+- [x] The oversized Elk-specific renderer tests are decomposed into partial classes without renaming tests
+- [x] Elk-focused validation is rerun and the regenerated document-processing artifact is visually reviewed for regressions
+
 ## Execution Log
 | Date (UTC) | Update | Owner |
 | --- | --- | --- |
@@ -163,6 +176,9 @@ Completion criteria:
 | 2026-03-23 | Re-enabled highway processing, added a blocking `TargetApproachJoinViolations` rule with maximum score penalty to stop non-applicable shared arrival rails from being silently selected, updated variant artifact labels to expose the new metric, and re-ran `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~DocumentProcessingWorkflow_WhenRenderedWithElkSharp_ShouldProducePngWithZeroNodeCrossings" -v minimal` (1/1, 87s). The best fallback render improved the `End`-side collapse from 4 join violations in baseline to 1 remaining join violation, while keeping `FinalBrokenShortHighwayCount=0`. | Implementer |
 | 2026-03-23 | Expanded the iterative-router pressure path from the accidental 2-attempt/4-strategy clamp to bounded multi-attempt retries with a wider finite strategy sweep, added stagnation cutoffs to avoid blind repetition, and wired the document-processing artifact test to emit `elksharp.progress.log` plus in-memory progress diagnostics so long-running strategy searches can be inspected while they are still running. A live run confirmed the new path executed `Strategy 1 attempt 1`, `attempt 2`, `attempt 3`, then advanced to `Strategy 2` instead of stopping after two attempts. | Implementer |
 | 2026-03-24 | Added per-attempt phase timings and route-pass counters to the iterative diagnostics JSON, regenerated the document-processing artifact with `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~DocumentProcessingWorkflow_WhenRenderedWithElkSharp_ShouldProducePngWithZeroNodeCrossings" -v minimal` (1/1, 50s), and confirmed the runtime hotspot is overwhelmingly `route-all-edges`: for the selected `reverse` strategy the three attempts spent about `45.3s` in `route-all-edges` versus about `15.9ms` in all post-processing/scoring phases combined. The same run still reported `ExcessiveDetourViolations=1` for `edge/33`, so the shortest-path issue remains unresolved and requires a local detour-repair path rather than more full-graph retries. | Implementer |
+| 2026-03-26 | Tightened the long-diagonal rule from two average node-shape lengths to one average node-shape length, mirrored the renderer artifact helper to the same threshold, added a direct `Evaluation Condition -> Internal Discussion` scoring regression, and revalidated the focused ElkSharp renderer tests. The full document-processing artifact rerun cleared long-diagonal and target-join offenders, but the selected layout still fails on a separate shared-lane pair (`edge/9+edge/22`). | Implementer |
+| 2026-03-26 | Added a final winner-refinement boundary-slot restabilization pass so late shared-lane cleanup cannot pull decision-source exits back off the discrete slot lattice, added a focused document-processing layout regression for boundary-slot pressure, and updated the ElkSharp docs to record the terminal slot re-snap requirement. | Implementer |
+| 2026-03-26 | Tightened the node-side slot lattice into a strict terminal rule: singleton source/target endpoints now must center on their resolved face slot, preserved repeat/corridor exits are no longer exempt from the final slot snap, and strict slot repairs may bypass the generic shared-lane validator when the centered repair is still obstacle-safe and boundary-valid. Revalidated with `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~BoundarySlotHelpers_When" -v minimal` (`5/5`). | Implementer |
 | 2026-03-24 | Reworked iterative retry attempts to repair only penalized edges after the first full strategy pass, made attempt 2 prioritize shortest-path detours, narrowed the protected-corridor exemption so ordinary forward overshoots still qualify for detour repair, and revalidated with `dotnet build src/__Libraries/StellaOps.ElkSharp/StellaOps.ElkSharp.sln`, `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~DocumentProcessingWorkflow_WhenRenderedWithElkSharp_ShouldProducePngWithZeroNodeCrossings" -v minimal` (1/1, 22s), and `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore` (20/20). The new artifact diagnostics show attempt 2+ `Mode=local-repair` with rerouted-edge counts below the full graph, and the `Set emailDispatchFailed -> End` path is now the direct L-shape instead of the previous deep outer detour. | Implementer |
 | 2026-03-24 | Added late local geometry repair for node-side entry/exit angles, repeat-collector return-lane stacking, and target-side slot spacing; narrowed repeat-collector target-join scoring so the shared outer collector column is not miscounted as a target-side join; updated the backward-family regression expectations; and revalidated with `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~ElkSharpWorkflowRenderLayoutEngineTests" -v minimal` (11/11) plus `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~DocumentProcessingWorkflow_WhenRenderedWithElkSharp_ShouldProducePngWithZeroNodeCrossings" -v minimal` (1/1, 32s). The regenerated document-processing artifact now reaches `NodeCrossings=0`, `BrokenShortHighways=0`, `RepeatCollectorCorridorViolations=0`, `EntryAngleViolations=0`, `TargetApproachJoinViolations=0`, and `ExcessiveDetourViolations=0`, with strategy `reverse` becoming a valid selected result. | Implementer |
 | 2026-03-24 | Added a blocking target-approach-backtracking metric plus local shortest-path repair so `Execute Batch -> Check Result` no longer curls past the target side before returning, kept attempt 2+ focused on penalized lanes only, and updated the backward-family collector regression to allow the nearest loop to take the new shorter direct return while the remaining outer-loop family still stacks on shared top collector lanes. Revalidated with `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~DocumentProcessingWorkflow_WhenLaidOutWithElkSharp_ShouldNotBacktrackIntoCheckResult" -v minimal` (1/1) and `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~LayoutAsync_WhenBackwardFamilySharesTarget_ShouldStackOuterCollectorLanes" -v minimal` (1/1). | Implementer |
@@ -175,10 +191,23 @@ Completion criteria:
 | 2026-03-25 | Tightened the iterative local-repair planner so attempt 2+ now selects only currently failing edges plus exact conflict peers instead of padding the repair set with generic ranked edges, and added a lock-aware parallel local builder that computes candidates concurrently but serializes overlapping source/target neighborhoods before merging deterministically. Revalidated with `dotnet build src/__Libraries/StellaOps.ElkSharp/StellaOps.ElkSharp.sln -v minimal` and `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~DocumentProcessingWorkflow_WhenRenderedWithElkSharp_ShouldProducePngWithZeroNodeCrossings" -v minimal` (still failing in ~20s on `SharedLaneViolations=1`, `UnderNodeViolations=2`; selected offender cluster remains `edge/15+edge/17`, `edge/9`, `edge/15`). | Implementer |
 | 2026-03-26 | Cleared the last document-processing handoff by letting gateway target peer-conflict candidates start from slotted feeder paths and reusing focused target-peer conflict polish during transactional final-detour repair. Revalidated with `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~Debug_DumpDocumentProcessingFinalDetourOffenders" -v normal --logger "console;verbosity=normal"` (1/1) and `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~DocumentProcessingWorkflow_WhenRenderedWithElkSharp_ShouldProducePngWithZeroNodeCrossings" -v minimal` (1/1, 2m42s). | Implementer |
 | 2026-03-26 | Tightened non-gateway target backtracking so a short orthogonal hook that reaches the boundary for less than one node depth is treated as a forbidden fake side entry, then added a focused `Load Configuration -> Setting configParameters` regression. | Implementer |
+| 2026-03-26 | Extended the same short-hook rule to gateway targets after `Internal Notification -> Has Recipients` still approached the decision from the left and only changed direction in the last few pixels. Gateway target repair/acceptance now rejects those fake face joins, and the focused workflow regression covers the decision-target case. | Implementer |
+| 2026-03-26 | Closed the remaining `Load Configuration -> End` detour follow-up by letting local obstacle-skirt repair reuse interior axes from the current route and try a zero-clearance fallback before keeping a high preserved overshoot. Revalidated with `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~ShortcutHelpers_WhenRectSourceCanPreserveRectTargetTopEntry_ShouldClearExcessiveDetour" -v minimal` (1/1) and `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~DocumentProcessingWorkflow_WhenRenderedWithElkSharp_ShouldProducePngWithZeroNodeCrossings" -v minimal` (1/1, 2m24s). | Implementer |
+| 2026-03-26 | Added a discrete node-side slot lattice so one input/output cannot silently stack on the same boundary point: gateway faces now resolve to `1` centered slot or `2` centered slots, rectangular `left`/`right` faces to at most `3` evenly spread slots, and rectangular `top`/`bottom` faces to at most `5` evenly spread slots. Wired the same capacity/assignment logic through scoring, highway/join detection, source-target slot repair, and mixed-face alternate-side repair, then revalidated `BoundarySlotHelpers_WhenNodeKindsResolveSideCapacities_ShouldSpreadSlotsEvenly`, `GatewayBoundaryHelpers_WhenGatewayJoinReceivesDirectAndElbowedLeftArrivals_ShouldSpreadTargetSlots`, `MixedNodeFaceHelpers_WhenMixedTopFaceEntriesAreOffLatticeWithoutLaneConflict_ShouldSnapToDiscreteSlots`, and `SourceDepartureHelpers_WhenOutgoingEdgesShareTheSameDepartureLane_ShouldSpreadOnlyTheConflictingPeer` (`4/4`). | Implementer |
+| 2026-03-27 | Reconciled gateway-source scoring with the resolved discrete slot lattice so late winner restabilization no longer re-flags compliant singleton gateway exits. Revalidated `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~BoundarySlotHelpers_WhenDecisionSourceSlotsNeedLateRestabilization_ShouldRepairGatewayExitsAndDefaultDetours" -v minimal` (1/1) and `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~BoundarySlotHelpers_When" -v minimal` (8/8). Fresh document-processing end-to-end reruns still stalled after entering the ElkSharp layout path and did not emit new progress-log updates or fresh artifacts, so full artifact revalidation remains pending. | Implementer |
+| 2026-03-28 | Added focused regressions for the remaining `edge/15`/`edge/35` target-join collapse and `edge/3`/`edge/4` shared-lane collapse, then updated final restabilization to preserve a direct shared-lane repair when it lowers shared-lane violations without increasing node crossings. Trimmed the compact terminal-closure path and the winner fast-terminal candidate builder down to local-only passes after live `elksharp.progress.log` inspection showed those supposedly cheap branches were still doing heavyweight work. Revalidated `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~FinalRestabilization_WhenForkDeparturesIntoProcessAndJoinShareALane_ShouldKeepTheSharedLaneRepair|FullyQualifiedName~FinalRestabilization_WhenRepeatRightFaceTerminalRailCollapses_ShouldKeepTheJoinRepair|FullyQualifiedName~SharedLaneHelpers_WhenForkDeparturesIntoProcessAndJoinShareALane_ShouldSeparateThem|FullyQualifiedName~TargetApproachHelpers_WhenRepeatRightFaceReturnsShareTerminalRail_ShouldPushOneArrivalFartherOut" -v minimal` (`4/4`, about `2s`). Full `DocumentProcessingWorkflow_WhenRenderedWithElkSharp_ShouldProducePngWithZeroNodeCrossings` revalidation is still running; the updated logs now pass the previous pseudo-hang point and reach the final winner fast-terminal focus instead of stalling before it. | Implementer |
+
+| 2026-03-28 | Decomposed `ElkEdgePostProcessor`, `ElkEdgeRouterIterative`, `ElkSharpEdgeRefinementTests`, and `DocumentProcessingWorkflowRenderingTests` into partial files. Rebuilt the Elk renderer test project successfully via `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj -v minimal`, regenerated the document-processing artifact set under `bin/Debug/net10.0/TestResults/workflow-renderings/20260328/DocumentProcessingWorkflow/`, and visually reviewed `elksharp.png` with no obvious regression from the file split. Follow-up focused `dotnet test` runs hit the existing long-lived `testhost` hang after artifact generation, so the validation evidence for this refactor is the clean rebuild plus the fresh artifact/log outputs rather than a new full-suite completion record. | Implementer |
 
 ## Decisions & Risks
 - 2026-03-26: The remaining document-processing defect was not another retry-budget issue. Gateway target peer-conflict candidate building needed a slotted feeder so focused peer-conflict polish could separate same-face arrivals without restoring the final excessive detour.
 - 2026-03-26 follow-up: the `Load Configuration -> Setting configParameters` edge exposed a different blind spot. The rectangular target-entry rule only validated the final boundary angle and true overshoot, so a `6px` vertical stub into the bottom face still passed as a valid `90`-degree entry. Non-gateway target backtracking now also rejects short orthogonal hooks whose final boundary-depth is less than one node shape depth, which lets the existing backtracking endpoint normalizer move the edge onto the honest side face instead of preserving the fake bottom join.
+- 2026-03-26 gateway follow-up: `Internal Notification -> Has Recipients` exposed the same cheat on a decision target. Gateway target repair previously enforced only polygon-boundary contact and a valid final angle, so a long horizontal approach plus a tiny vertical drop into the diamond still passed. Gateway target validation now rejects short orthogonal last-moment hooks as invalid face joins as well. Updated docs: `docs/workflow/ENGINE.md`.
+- 2026-03-26 detour follow-up: `Load Configuration -> End` exposed a separate shortest-path blind spot after the fake entry hooks were gone. Local obstacle-skirt repair sampled only expanded-obstacle edges, so it skipped the already-safe interior lane at `Y=216.59` and preserved a much higher overshoot instead. The repair now reuses usable interior axes from the current path and tries a zero-clearance fallback before settling on a preserved detour. Updated docs: `docs/workflow/ENGINE.md`, `src/__Libraries/StellaOps.ElkSharp/AGENTS.md`.
+- 2026-03-26 slot-lattice follow-up: node-boundary spreading had remained heuristic, so repeated source/target/mixed-face repairs could leave multiple edges effectively concentrated on the same face point even after join and lane conflicts were removed. Boundary-slot assignment is now explicit and shared across scoring and repair: gateways use `1` or `2` centered face slots, rectangular `left`/`right` faces use at most `3`, rectangular `top`/`bottom` faces use at most `5`, and no repair is accepted unless each edge lands on its assigned realizable slot. Updated docs: `docs/workflow/ENGINE.md`, `src/__Libraries/StellaOps.ElkSharp/AGENTS.md`.
+- 2026-03-26 winner-refinement follow-up: boundary-slot assignment was correct inside the terminal repair passes, but the extra winning-solution shared-lane polish could still move decision-source exits off their assigned face slots after a valid candidate had already been chosen. Winner refinement now ends with a slot-restabilization pass that re-snaps the final selected edges before return. Updated docs: `docs/workflow/ENGINE.md`, `src/__Libraries/StellaOps.ElkSharp/AGENTS.md`.
+- 2026-03-26 strict-slot follow-up: the earlier lattice still treated singleton entries and preserved repeat/corridor exits as effectively advisory, so the scorer could report concentrated/off-center endpoints that the final slot snap would skip. Final boundary-slot repair now uses the same all-endpoint lattice as scoring, with side-specific port exemptions only, and it accepts centered slot repairs when they remain obstacle-safe and boundary-valid even if the generic shared-lane validator is too conservative. Updated docs: `docs/workflow/ENGINE.md`, `src/__Libraries/StellaOps.ElkSharp/AGENTS.md`.
+- 2026-03-27 gateway-source follow-up: once singleton entries and exits were scored against the same centered lattice, gateway-source scoring still treated some final slotted singleton exits as invalid because it re-applied generic near-vertex / preferred-face heuristics after the slot resolver had already chosen the realizable boundary landing. Gateway-source scoring now defers to the resolved source-slot assignment for boundary-slot-compliant singleton gateway exits, while keeping hard backtracking defects blocking. Focused slot regressions are green again, but the document-processing end-to-end renderer still needs a clean non-stalled rerun before the artifact can be treated as fully revalidated.
 - 2026-03-25 follow-up: the selected document-processing artifact now enforces zero below-graph lanes and zero overlong 45-degree segments, and gateway source exits are no longer allowed to leave from fork/join tip vertices. Gateway target join detection/spreading now groups arrivals by their landed boundary band instead of letting gateway arrivals slip through as highway-like exemptions. Targeted evidence: `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --no-restore --filter "FullyQualifiedName~DocumentProcessingWorkflow_WhenRenderedWithElkSharp_ShouldProducePngWithZeroNodeCrossings" -v minimal` (1/1 pass, refreshed 20260325 artifact). That checkpoint still left TASK-010 open; the 2026-03-26 peer-conflict fix closes it.
 - There was no module-local `AGENTS.md` under `src/__Libraries/StellaOps.ElkSharp/`; this sprint adds one before code changes so the module is no longer undocumented.
 - Cross-module edits are limited to workflow renderer tests and workflow engine docs because the implementation changes a shared library used by those surfaces.
@@ -206,10 +235,14 @@ Completion criteria:
 - Gateway target repairs now use polygon-face slot projection instead of rectangular side slots. When only a penalized subset of edges is being repaired, target-slot spacing still considers the unchanged peer edges on that same target side so the repaired edge cannot collapse back into the existing arrival rail.
 - Repeat-collector edges with preserved outer corridors are no longer exempt from node-crossing repair. If the prefix that leads into the corridor crosses a node, that prefix is rerouted into the preserved corridor while the outer corridor segment remains intact.
 - Gateway-source dominant-axis scoring is now opportunity-gated: a gateway source is only treated as leaving on the wrong axis when a clean downstream-facing repair opportunity actually exists. Obstacle-blocked local exits can still take a short dogleg while the document-processing artifact assertions keep them clear of blockers and out of unrelated node clearance bands.
+- Long 45-degree segments are now capped at one average node-shape length instead of two. The scoring helper and the artifact-side offender detector use the same threshold so visually long diagonals cannot survive scoring while slipping past the renderer assertions.
+- Tightening the diagonal cap changes candidate selection pressure in the full document-processing artifact. The current worktree clears the long-diagonal and gateway-target join regressions, but the selected layout still exposes a separate shared-lane conflict (`edge/9+edge/22`) that needs another local repair pass before the full artifact test is green again.
 - The user-reported `Internal Notification` overlap was not a target-side highway issue. The previous rule set modeled target-side joins and repeat-corridor sharing, but not two edges leaving the same source face on the same departure lane. TASK-010 adds source-departure join spreading and blocking `SharedLaneViolations` for that case.
 - Node placement spacing now uses a separate placement grid derived from the average non-terminal node width/height (`ResolvePlacementGrid`) instead of depending only on the routing lattice. The focused helper/layout checks are green, but the end-to-end document-processing artifact still needs a clean rerun after the late boundary-angle / target-join regressions are resolved.
 - Iterative local repair now stays constrained to currently failing lanes and exact conflict peers. The planner no longer fills the repair budget with unrelated high-severity edges once the current failing rule set has been seeded.
 - Per-iteration local repair candidate building can now run in parallel, but builds that share a source or target neighborhood acquire the same lock and wait instead of racing through the same local conflict zone. Current measured document-processing renders still finish in about 20 seconds, so the remaining work is repair quality for the `edge/9` / `edge/15` cluster rather than retry churn.
+- 2026-03-28 runtime follow-up: the remaining slowdown was no longer in broad winner refinement. Live `elksharp.progress.log` traces showed the expensive branch had collapsed to the final winner fast-terminal focus `[edge/15, edge/3, edge/35, edge/4]`, where both the compact terminal-closure helper and the fast-terminal candidate builder were still doing heavyweight terminal/boundary work. Both paths are now restricted to local-only passes; focused geometry regressions are green again, but the full document-processing artifact still needs a completed rerun before the runtime drop and final artifact quality can be treated as revalidated.
+- 2026-03-28 decomposition follow-up: active ElkSharp code is now split into concern-based partials, and the regenerated document-processing artifact still renders cleanly after the move. The remaining validation nuisance is harness-related rather than routing-related: the renderer test host can stay resident after the artifact is written, so fresh decomposition evidence is the successful project rebuild, a new `elksharp.progress.log` ending with `ElkSharp layout optimize returned`, and visual review of the regenerated `elksharp.png`.
 - Optimization plan for the next pass:
   1. Build a reusable immutable per-strategy routing context so grid lines, blocked segment masks, and target-slot metadata are computed once per strategy instead of once per edge route.
   2. Replace global whole-graph retries for soft penalties with issue-focused repair passes: detour edge repair, target-side join repair, and proximity cluster repair.