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

# Automatic layout investigation

Issue [32](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/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](experiments/auto-layout-20260925/results-01.md)
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](experiments/auto-layout-20260925/results-j.md)
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](experiments/auto-layout-20260925/results-lanes.md)
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](experiments/routing-independent-20260925/results.md)
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](experiments/auto-layout-20260925/source-evaluator-map.md)
identifies the actual callers and preserved input/source/API contracts. The
[primary-source research](experiments/auto-layout-20260925/research.md) compares
Sirius/Capella workflows, ELK and reuse of the existing Rust router. The
[candidate critique](experiments/auto-layout-20260925/candidate-critique.md)
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](experiments/auto-layout-20260925/probe-notes.md) covers
nine small SA FunctionalDataflow fixtures. Its [independent source review](
experiments/auto-layout-20260925/probe-review.md) 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](experiments/connection-layout-reference-20260925/results.md)
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](experiments/placement-clearance-20260925/results.md)
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](experiments/scc-placement-20260925/results.md)
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.