fix(layout): seat an orphaned half-pitch branch on a full grid row

A half-pitch offset draws a two-way symmetric fork as one compact grid
unit, so both members are placed together and each only reads as
deliberate because it balances the other across the trunk.  When Stage
6.10's _align_terminus_to_upstream pulls a terminus member onto its
producer's trunk Y, the surviving member holds an offset that straddles
nothing and renders as a branch stranded between two grid rows.

Add Stage 6.18, _expand_orphaned_half_grid_stations: mirror each marked
station's offset about the section's LR/RL port anchor and, with the
opposite slot empty, seat the branch one full row from the anchor on the
side it already sits.  Gated to stations at a genuine half pitch, since
the marker set also carries members already a whole number of rows out.

An earlier gate cannot do this.  _layout_once runs up to seven times per
render and the motivating section carries two structurally identical
half-pitch pairs, only one of them broken, so every predicate tried
inside _recenter_full_bundle_columns or _align_terminus_to_upstream
flipped the section into a different fixpoint and bent the trunk.

_half_grid_frame and _straddles_nothing are shared with the invariant
test, as _iter_symmetric_diamonds already does, so the oracle and the fix
cannot disagree about which stations are legitimately half-pitch.

Rename the exercising fixture to paired_input_fan_branch_tree and give it
generic labels and station ids.  The replacements are width-matched to
what they replace, so its geometry is coordinate-for-coordinate identical
and the three regressions it locks all still reproduce: the input-fan
bypass-V band, the reconverging-diamond entry-port centring, and the new
half-pitch straddle.  Its stage_a4 branch now sits level with the out_a1
branch instead of half a row above the trunk.

Register the resulting off-track reanchor divergence, tracked in #1566.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: pinin4fjords

examples/topologies/paired_input_fan_branch_tree.mmd

@@ -0,0 +1,69 @@
+%%metro title: Paired-track demo
+%%metro diamond_style: symmetric
+%%metro style: dark
+%%metro legend: bl
+%%metro files: pairs_in | FILE | Input set
+%%metro files: out_a1 | OUT | Track A
+%%metro file: out_a2 | OUT | Output A2
+%%metro file: out_a3 | OUT | Output three
+%%metro file: out_b | OUT | Probe value
+%%metro files: out_c | OUT | Chain out
+%%metro line: track_a | Track A | #0570b0
+%%metro line: track_b | Track B | #d94801
+
+graph LR
+    subgraph input_sec [Inputs]
+        pairs_in[ ]
+        convert_a[Convert one\ntrack a]
+        convert_b[Convert two\ntrack b]
+
+        pairs_in -->|track_a| convert_a
+        pairs_in -->|track_b| convert_b
+    end
+
+    subgraph branch_sec [Branching stage]
+        stage_a1[Upstream\nprimary stage]
+        stage_a2[Filter step]
+        stage_a3[Fork\nannotation]
+        stage_a4[Terminal\nsegment]
+        out_a1[ ]
+        out_a2[ ]
+        out_a3[ ]
+
+        pairs_in -->|track_a| stage_a1
+        pairs_in -->|track_b| stage_a1
+        stage_a1 -->|track_a,track_b| stage_a2
+        stage_a2 -->|track_a,track_b| out_a1
+        stage_a2 -->|track_a,track_b| stage_a3
+        stage_a3 -->|track_a,track_b| out_a2
+        stage_a3 -->|track_a,track_b| stage_a4
+        stage_a4 -->|track_a,track_b| out_a3
+    end
+
+    subgraph probe_sec [Hub]
+        stage_b1[merge node]
+        out_b[ ]
+
+        convert_a -->|track_a| stage_b1
+        convert_b -->|track_b| stage_b1
+        stage_b1 -->|track_a,track_b| out_b
+    end
+
+    subgraph chain_sec [Downstream chain]
+        split_a[Region split\ntrack a]
+        split_b[Region split\ntrack b]
+        stage_c1[Assemble\nstage]
+        stage_c2[Collate\nmerge step]
+        stage_c3[Fit and rank\nstage]
+        stage_c4[Adjust to\nscale]
+        out_c[ ]
+
+        convert_a -->|track_a| split_a
+        convert_b -->|track_b| split_b
+        split_a -->|track_a| stage_c1
+        split_b -->|track_b| stage_c1
+        stage_c1 -->|track_a,track_b| stage_c2
+        stage_c2 -->|track_a,track_b| stage_c3
+        stage_c3 -->|track_a,track_b| stage_c4
+        stage_c4 -->|track_a,track_b| out_c
+    end

examples/topologies/tn_wes_input_fan_somatic_tree.mmd

@@ -1833,13 +1833,13 @@ gallery:
       station. The output's branch peels off between the two rather than
       overrunning the successor's column, so the icon clears the downstream
       stations and their labels."
-  - id: tn_wes_input_fan_somatic_tree
+  - id: paired_input_fan_branch_tree
     source_dir: examples/topologies
     category: Feature Showcase
     description:
-      "A tumour/normal WES map: the input source fans to two CRAM->BAM
-      converters and threads the germline+tumour bundle cleanly between them to
-      the somatic caller, whose dead-end VCF outputs peel off without crowding
+      "A paired-input map: the source fans to two stacked converters and
+      threads the two-track bundle cleanly between them to the branch tree,
+      whose dead-end outputs peel off onto full grid rows without crowding
       their neighbours."
   - id: single_line_dual_source_stacked_exit
     source_dir: examples/topologies

scripts/gallery.yaml

@@ -247,9 +247,10 @@ pass:
   grid snap (6.4).
 - `graph.half_grid_station_ids` - written by Stage 6.3 (`center_ports` only)
   and Stage 6.17 (`diamond_style='symmetric'`); read by the Stage 6.4 grid
-  snap, which must skip these half-pitch stations. Stage 6.17 runs after the
-  last snap, so its writes mark branches for the invariant tests / straddle
-  guard rather than feeding a later snap.
+  snap, which must skip these half-pitch stations. Stage 6.18 both reads the
+  set and clears the marking off any station it seats back on a full row, so
+  the post-layout readers (the straddle guard, the co-fanned drop-clearance
+  rule in `routing/intra_handlers.py`) see only stations still at half pitch.
 - `graph.symfan_trunk_station_ids` - written by Stage 6.3 (`center_ports` only);
   read by the Stage 6.4 grid snap, which must skip these source/trunk stations
   so they stay on the symfan's local frame instead of snapping to a rowspan
@@ -878,7 +879,8 @@ in pipeline order.
 - **Related tests**: `test_symfan_pairs_share_y`.
 - **Lifecycle:** invariant - 2-branch symfan pairs keep their half-pitch
   offsets at the final boundary (Stage 6.4 skips
-  `graph.half_grid_station_ids`).
+  `graph.half_grid_station_ids`); only Stage 6.18 may seat one on a full
+  row, and only once its straddling partner has moved away.
 
 ### Stage 6.4: snap all Y to grid (engine.py)
 - **Purpose**: Final pass snapping every station and port Y to the
@@ -959,7 +961,9 @@ in pipeline order.
   are temporarily broken; both are restored before leaving the
   `if center_ports:` block.
 - **Lifecycle:** invariant - full-bundle columns are symmetric around
-  the row's final trunk Y at the boundary; no later stage re-fans them.
+  the row's final trunk Y at the boundary; no later stage re-fans them,
+  though Stage 6.18 seats a half-pitch member on a full row once its
+  straddling partner has moved away.
   *liftable:* no - one-shot, order-dependent (computes against the final
   trunk Y, so a premature run is wrong).
 
@@ -1223,10 +1227,10 @@ in pipeline order.
   Per-diamond, so a diamond compacts even when it shares a section with a
   wider fan (which keeps its full-pitch slots) and regardless of
   `center_ports`. Records the branches on
-  `MetroGraph.half_grid_station_ids`. Runs last, after every
-  trunk-settling pass, so the branches straddle the section trunk's final
-  Y exactly; the compaction only moves them inward toward the trunk, so it
-  never breaks bbox containment.
+  `MetroGraph.half_grid_station_ids`. Runs after every trunk-settling
+  pass, so the branches straddle the section trunk's final Y exactly; the
+  compaction only moves them inward toward the trunk, so it never breaks
+  bbox containment.
 - **Helper**: `_apply_half_grid_symmetric_diamonds`.
 - **Precondition**: Trunk Ys settled (post-6.16); `diamond_style`
   is `symmetric`.
@@ -1239,7 +1243,41 @@ in pipeline order.
   `test_symmetric_diamond_both_branches_deviate`,
   `_guard_symmetric_diamond_branches_straddle_trunk`.
 - **Lifecycle:** invariant - symmetric diamond branches keep their
-  half-pitch offsets at the final boundary (no later Y mutation).
+  half-pitch offsets at the final boundary; only Stage 6.18 may move one,
+  and only when its straddling partner is gone.
+
+### Stage 6.18: orphaned half-pitch expansion (engine.py)
+- **Purpose**: A half-pitch offset encodes one side of a symmetric pair
+  straddling the section trunk, so the pair reads as one compact grid
+  unit. Stage 6.10's `_align_terminus_to_upstream` may pull a terminus
+  member onto its producer's trunk Y, leaving the other member holding an
+  offset that straddles nothing and rendering as a branch stranded
+  between two grid rows. `_straddles_nothing` mirrors each marked
+  station's offset about the section's LR/RL port anchor; with no station
+  at the mirrored slot, the branch is seated one full row from the anchor
+  on the side it already sits, its half-grid marking cleared, and the
+  section bbox grown over the moved branch alone. Stations marked
+  half-grid whose settled Y is already a whole number of rows from the
+  anchor are left alone.
+- **Helper**: `_expand_orphaned_half_grid_stations`
+  (`phases/fan_bundles.py`), sharing `_half_grid_frame` /
+  `_straddles_nothing` with the invariant test.
+- **Precondition**: Every pass that places or dissolves a half-pitch pair
+  has run (post-6.17), so the half-grid marks are final.
+- **Postcondition**: No station in `graph.half_grid_station_ids` sits half
+  a pitch off its section's LR/RL port anchor with the mirrored slot
+  empty.
+- **Invariants preserved**: Trunk station Y, ports, bbox containment.
+  Deliberately not preserved: the half-grid marker set (the seated
+  station's id is discarded, so the post-layout readers see only stations
+  still at half pitch) and the section bbox extent, which grows over the
+  seated branch. No runtime `_guard_*` arms this postcondition:
+  `test_half_grid_stations_straddle_in_pairs` covers it across the corpus
+  without the abort risk a live guard would add to novel input.
+- **Related tests**: `test_half_grid_stations_straddle_in_pairs`.
+- **Lifecycle:** invariant - the expanded branch keeps its full-row Y at
+  the final boundary (no later Y mutation). The cleared marker reaches the
+  next `_layout_once` pass, which re-derives the marks from scratch.
 
 ## Unclear / structural-debt signals
 

src/nf_metro/layout/CONTRACT.md

@@ -110,6 +110,7 @@
     _center_lr_entry_ports_on_fork,
     _convergence_source_ys,
     _divergence_target_ys,
+    _expand_orphaned_half_grid_stations,
     _iter_symmetric_diamonds,
     _recenter_full_bundle_columns,
     _redistribute_fanout_siblings,
@@ -2007,6 +2008,13 @@ def _finalize_layout(
         _apply_half_grid_symmetric_diamonds(graph, y_spacing)
         _snap(graph, "6.17")
 
+    # Stage 6.18: Seat orphaned half-pitch stations on a full grid row (see
+    # _expand_orphaned_half_grid_stations and CONTRACT.md Stage 6.18).  Must
+    # follow every pass that places or dissolves a half-pitch pair, so the
+    # half-grid marks are final.
+    _expand_orphaned_half_grid_stations(graph, y_spacing, section_y_padding)
+    _snap(graph, "6.18")
+
     if validate:
         if graph._defer_final_guards:
             graph._after_final_deferred = True

src/nf_metro/layout/engine.py

@@ -63,7 +63,7 @@
     "4.1", "4.2", "4.3", "4.4", "4.5", "4.6", "4.7", "4.8", "4.9", "4.10",
     "5.1", "5.2", "5.3", "5.4", "5.5",
     "6.1", "6.2", "6.3", "6.4", "6.5", "6.6", "6.7", "6.8", "6.9", "6.10",
-    "6.11", "6.12", "6.13", "6.14", "6.15a", "6.15", "6.16", "6.17",
+    "6.11", "6.12", "6.13", "6.14", "6.15a", "6.15", "6.16", "6.17", "6.18",
 )  # fmt: skip
 
 
@@ -106,23 +106,24 @@ class PhaseFieldSpec:
     "_row_y_grid_info": PhaseFieldSpec(
         name="_row_y_grid_info",
         writer_stage="1.2",
-        reader_stages=("4.2", "6.3", "6.4"),
+        reader_stages=("4.2", "6.3", "6.4", "6.18"),
         enforcement=FieldEnforcement.REQUIRE_WRITER,
         why=(
             "row-grid metadata from Stage 1.2's _align_row_y_grids; the grid-group "
-            "port snap, fan re-centre, and grid snap read it to group same-row "
-            "sections onto a shared pitch"
+            "port snap, fan re-centre, grid snap and half-pitch expansion read it "
+            "to group same-row sections onto a shared pitch"
         ),
     ),
     "half_grid_station_ids": PhaseFieldSpec(
         name="half_grid_station_ids",
         writer_stage="6.3",
-        reader_stages=("6.4",),
+        reader_stages=("6.4", "6.18"),
         enforcement=FieldEnforcement.REQUIRE_WRITER,
         why=(
             "2-branch symfan stations Stage 6.3 places at half-pitch; Stage 6.4's "
             "grid snap must skip them or it snaps their intentional half-grid Y to "
-            "the full grid"
+            "the full grid, and Stage 6.18 reads the set to find members whose "
+            "pair partner moved to a full row"
         ),
         run_condition_attr="center_ports",
     ),