ARCADIA-Studio/harness/auto-layout-investigation-20260925.md

Automatic layout investigation

Issue 32 owns scope, ownership, milestones and integration status. This is an experiment record above released 715036e132677dd2bc2fb37ed316d93dc9987aec, not an accepted replacement layout contract or a completed fix. User-owned requirements remain in PROJECT_GOAL.md and the issue.

The first executed experiment records nine Windows fixtures at e7deea70: hierarchy/label improvements, repeat stability, and two shared-connector regressions. The candidate remains experimental; successful execution is not acceptance of a replacement command.

The target-join experiment isolates a routing score correction with fixed Projects/nodes/ports/endpoints. Its 185 regression checks pass, but an original-scene overlap regression and additional bipartite T contacts prevent a general readability acceptance.

The completed scoring/lane comparison records J/P/PL/L and closes this fixture-tuning experiment. L passes 188 selected checks and strict core Clippy, but residual ambiguity and a runtime cost signal require broader, independently selected evidence before production adoption.

The frozen independent corpus comparison passes its optimized timing screen but exposes additional ID-order and label tradeoffs. Retain released routing for the separate route-reset work; J/L remain experiments without native traceability acceptance. Its complete inputs, raw receipts, corrected evaluator and independent reviews are recorded together.

Question and existing evidence

Can explicit Auto-layout produce a readable arrangement that accounts for connections and their labels, including removal of stale bends, while preserving semantic endpoints, containment/allocation, source parity and reversible editing?

The current session::layout sizes the containment forest, sorts roots using directed edges and alias tie breaks, places four roots per row, and translates authored route points only when both actual endpoints move equally. Its authored route preservation is deliberate and tested in tests/release_routing.rs and tests/state_diagrams.rs; the user's requested automatic bend replacement needs an explicit amendment, not a silently weakened test.

The source map identifies the actual callers and preserved input/source/API contracts. The primary-source research compares Sirius/Capella workflows, ELK and reuse of the existing Rust router. The candidate critique records unresolved design gaps before any production choice.

The existing routing module already supplies bounded deterministic orthogonal search, node/header obstacles, fixed semantic port endpoints, crossing/shared-run costs and automatic label collision search. Automatic elbows are derived, not persisted. The investigation should reuse this capability unless experiments show a concrete reason to replace it. Process topology rendering is a different path; its reported overlapping routes do not alone prove an Auto-layout defect.

Candidate decisions, not yet accepted

Compare these materially different choices against visible route/label quality, semantic conservation, predictable user control, runtime/dependency cost, determinism, model size and maintainability:

1. Retain node arrangement and only reset effective visible route/label constraints. This is a useful control, but cannot by itself optimize poor node ordering.
2. Use a hierarchy-aware layered node arrangement and the existing router, with label-aware spacing and bounded crossing-reduction sweeps. Explicit Auto-layout can replace effective visible pins/label offsets; ordinary drag keeps its existing preservation rules. This is a candidate, not a chosen implementation.
3. Adopt a mature external layout engine, accounting for ports, labels, nested containers, runtime packaging and coordinate conversion. Evidence must justify the integration/dependency cost over reusing the current router.

Open contract questions include hidden/folded routes, authored attachment and port anchors, undirected and cyclic graphs, nested cross-boundary edges, repeated layout stability, and the observable treatment of exhausted search/poor results. No option may change semantic endpoints, ownership, allocation, expressions, relation kind or source identity to improve a drawing. Other views must remain unchanged, and one Undo on clean input must recover the complete pre-layout project. Existing application behavior applies an unrelated pending property draft first; that separate Apply is not silently folded into Layout's history.

The initial experiment retains the current command as the baseline and compares reset-only with a layered prototype isolated under examples/auto_layout_probe. Neither prototype changes production behavior. Effective reset eligibility must come from the pre-layout projection and actual endpoint identities; merely being drawn does not make a promoted route's dormant metadata eligible. Explicit label reset means both fraction and offset, while semantic text and endpoint/port attachments remain fixed. Production adoption remains conditional on the critic's hierarchy, stability, direction, measurement and global-work checks.

The first probe recipe covers nine small SA FunctionalDataflow fixtures. Its independent source review found no blocker to that finite diagnostic run and lists important evaluator limitations. After that review, the parent inspected the added ten-call prototype stability loop and formatted the examples; the loop reports every differing/error result without a quality pass. No production file was changed. The experiment intentionally does not establish folded/filtered, State, Allocation, source-bundle or native acceptance.

Evaluator before implementation

Use independently specified small graphs and real project views. Separate proper crossings, collinear shared runs, obstacle collisions, label/card collisions, label/label collisions, routing warnings, bends, length and occupied area. A low crossing count alone can hide coincident edges or enormous drawings. Exempt only explicitly documented intentional containment and common endpoint geometry; never discard a failure because it is inconvenient to the proposed algorithm.

Compare the current command and the reset-only control before choosing a design. Include a chain longer than the current four-column row, diamond/bipartite cases, nested cross-boundary exchanges, stale authored detours/labels, fixed ports, cycles/self-loops and disconnected components. Check deterministic repeat calls, idempotence, model/source round trips and complete Undo/Redo. A probe is evidence about its named fixtures, not universal graph quality or native usability.

Actual representative Windows workflows, including meaningful window/zoom sizes, selection and saved reopen, follow an implemented candidate. Linux remains excluded by the current user instruction. The separately published State label candidate in issue36 is not silently treated as integrated into this base.

Placement/reference compatibility checkpoint

The fixed external placement comparison tests the old native prototype and elkjs0.12.0 positions through the released router on the same independent corpus. Mixed placement metrics improve, but automatic ports differ from the engine's assumptions; the sparse candidate violates mandatory port-exit clearance and falls back before path search. Both workshop reference cases reject an unsupported undirected edge. Neither candidate is adopted. The next interface must account for final automatic ports and mandatory leads, not only node/label boxes. All results remain branch-specific; Gitea holds publication and integration status.

The follow-up mandatory-lead separation experiment supplies that necessary check using the router's actual endpoint choices. One bounded flat repair removes the sparse hard routing failure, but worsens crossing, shared-run and label/stroke measures. Preserve the compatibility result without adopting this repair as Arrange. Initial connection ordering and reserved routing/ label space, with compound handling, remain the next planner questions; more repair iterations or router penalty tuning are not supported by this evidence.

The coherent cyclic-group experiment then isolates the old native candidate's rank-stretching problem. Sparse sharing falls from 40,522 to 32 with unchanged released routing. A corrected importer preserves requested effective container minima after child movement; all 14 frozen cases complete and the 13 previously successful results remain exact. This is useful structural evidence, not an Arrange replacement. Cross-boundary child ordering, local label conflicts and folded backtracking remain explicit witnesses. Source, failed/successful runs, conservation and independent reviews are linked from the result. Gitea remains authoritative for live ownership and publication status; no integrated checkpoint or release change is implied.