Merge pull request #1567 from seqeralabs/fix/symfan-terminus-half-pitch

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

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",
     ),