research(layout): preserve corridor cohort planning checkpoint

scripts/build_gallery.py

@@ -397,7 +397,7 @@ def render_test_fixtures() -> None:
         mmd_path = TEST_FIXTURES_DIR / f"{stem}.mmd"
         if not mmd_path.exists():
             continue
-        svg_path = RENDERS_DIR / f"{stem}.svg"
+        svg_path = RENDERS_DIR / f"{Path(stem).name}.svg"
         if _skip_render(mmd_path):
             _manifest[svg_path.name] = section
             continue

scripts/gallery.yaml

@@ -2187,6 +2187,10 @@ render_only:
     - { id: variant_calling_tuned, output: nf_variant_calling_tuned_icons }
   # Stems from tests/fixtures/ rendered into the "Test Fixtures" render-diff section.
   test_fixtures:
+    - hash_seed_determinism/seed_15
+    - hash_seed_determinism/seed_41
+    - hash_seed_determinism/seed_72
+    - hash_seed_determinism/seed_77
     - multiline_labels
     - rnaseq_simple
     - genomeassembly_organellar

scripts/routing_gate_coverage.py

@@ -163,19 +163,22 @@ def _collect_corpus() -> list[tuple[Path, bool]]:
 
     Mirrors ``tests/conftest.py``'s ``content_corpus``: the ``examples/`` tree
     (``rglob`` already subsumes ``examples/topologies`` and ``examples/guide``),
-    the loose ``tests/fixtures/`` fixtures, and the Nextflow-DAG fixtures under
-    ``tests/fixtures/nextflow/`` (which need ``convert_nextflow_dag`` before
-    parsing). Widening past the original ``examples/``-only scope lets the test
-    fixtures retire gate arms the gallery never reaches. Unlike
-    ``content_corpus`` this keeps the ``rails`` fixtures -- their rail router is
-    a routing path the matrix should measure, not skip.
+    the loose ``tests/fixtures/`` fixtures, the stable hash-seed regression
+    fixtures, and the Nextflow-DAG fixtures under ``tests/fixtures/nextflow/``
+    (which need ``convert_nextflow_dag`` before parsing). Widening past the
+    original ``examples/``-only scope lets the test fixtures retire gate arms the
+    gallery never reaches. Unlike ``content_corpus`` this keeps the ``rails``
+    fixtures -- their rail router is a routing path the matrix should measure,
+    not skip.
     """
     examples = PROJECT_ROOT / "examples"
     fixtures = PROJECT_ROOT / "tests" / "fixtures"
+    hash_seed_determinism = fixtures / "hash_seed_determinism"
     nextflow = fixtures / "nextflow"
     sources: list[tuple[list[Path], bool]] = [
         (sorted(examples.rglob("*.mmd")), False),
         (sorted(fixtures.glob("*.mmd")), False),
+        (sorted(hash_seed_determinism.glob("*.mmd")), False),
         (sorted(nextflow.glob("*.mmd")), True),
     ]
     candidates = [(p, is_nextflow) for paths, is_nextflow in sources for p in paths]

src/nf_metro/api.py

@@ -44,10 +44,7 @@
     metrics_face_context,
     metrics_face_for_portability,
 )
-from nf_metro.themes import DEFAULT_MODE, THEME_MODES, THEMES
-
-# `style: dark` predates theme names; alias it onto the nfcore brand.
-_STYLE_THEME_ALIASES = {"dark": "nfcore"}
+from nf_metro.themes import resolve_theme
 
 
 @dataclass
@@ -103,31 +100,6 @@ def apply_layout_overrides(graph: MetroGraph, opts: Mapping[str, object]) -> Non
                 graph.layout_provenance.record_caller_line_order(value)
 
 
-def resolve_theme(
-    theme: str | None, graph: MetroGraph, mode: str | None = None
-) -> Theme:
-    """Resolve a concrete theme from independent brand and mode axes.
-
-    Brand comes from the explicit ``theme`` name (``--theme``) or the
-    ``%%metro style:`` directive (``dark`` aliases to ``nfcore``). Mode comes
-    from the explicit ``mode`` argument (``--mode``), then the ``%%metro mode:``
-    directive, then ``DEFAULT_MODE``. No brand carries its own mode: a known
-    brand always resolves through its light/dark family for the chosen mode.
-    """
-    if theme is not None:
-        brand = theme
-    else:
-        name = graph.style.strip().lower()
-        brand = _STYLE_THEME_ALIASES.get(name, name)
-
-    resolved_mode = (mode or graph.mode).strip().lower() or DEFAULT_MODE
-    family = THEME_MODES.get(brand)
-    if family and resolved_mode in family:
-        return family[resolved_mode]
-
-    return THEMES.get(brand, THEMES["nfcore"])
-
-
 @dataclass(frozen=True)
 class RenderResult:
     """Rendered content and the immutable plan used to create it."""

src/nf_metro/candidate_executor.py

@@ -627,7 +627,11 @@ def collect(stage: CandidateStage) -> bool:
         try:
             begin(CandidateStage.ROUTE_PLAN)
             offsets = compute_station_offsets(graph)
-            observation = observe_route_edges(graph, station_offsets=offsets)
+            observation = observe_route_edges(
+                graph,
+                station_offsets=offsets,
+                allow_convergence_clearance_requirements=True,
+            )
             build_route_plan_query(observation.plan)
             route_evidence = _route_evidence(observation.plan)
             route_findings = observation.plan.diagnostics

src/nf_metro/cli.py

@@ -759,12 +759,7 @@ def validate(input_file: Path, with_layout: bool, strict: bool) -> None:
         if with_layout:
             try:
                 compute_layout(graph, validate=True)
-            except (
-                CyclicGraphError,
-                BackwardFlowError,
-                MixedEntryDirectionError,
-                PhaseInvariantError,
-            ) as e:
+            except (ValueError, FoldThresholdError, PhaseInvariantError) as e:
                 issues.append(ValidationIssue(ERROR, str(e)))
 
     issues.extend(ValidationIssue(WARNING, str(w.message)) for w in caught)

src/nf_metro/layout/CONTRACT.md

@@ -194,6 +194,13 @@ frames armed on every fixture. That count is a function of how many systems
 make ownership claims, so a tree that plans more systems shows more mid-pass
 disagreement without its geometry being worse; it is not a quality metric.
 
+If the final observation requires render-time envelope settlement, its
+route-dependent guards defer within the layout engine. Before a successful
+`compute_layout(validate=True)` returns, the engine builds the settled render
+plan and runs those guards against the geometry that would be drawn. This is a
+property of the validated layout API, not an extra obligation placed on CLI or
+embedding callers.
+
 ## Anchor invariant
 
 The **anchors** of a section are its port stations: synthetic points on the
@@ -1584,15 +1591,26 @@ They are design evidence, not part of this specification.
   interchange idiom rather than the declared section gap, and widening one of
   their boundaries to that gap turns a flat inter-row run into a staircase --
   a decision change, which `_assert_settlement_decisions_frozen` refuses.
+- **Clearance grants form a fixed prerequisite DAG, not a retry loop.** Render
+  discovery can publish `GENERAL` convergence requirements. Those are settled
+  first because their translation can change carrier orientation, making any
+  corridor-cohort ledger captured beforehand invalid. One re-observation then
+  builds corridor-cohort intent from the settled convergence geometry. It can
+  publish at most one `CORRIDOR_COHORT_APERTURE` requirement set, which is
+  settled once before the final strict replay and freeze. Each transition is
+  validated against its own requirement kind; neither stage iterates or accepts
+  requirements owned by the other.
 - **The two demands can cover either axis.** The reservation ledger is settled
   on both: `_settle_axis` runs once per axis and every row-gap and column-gap
   claim is measured. Generic box-growth clearance remains row-only because
   `measure_row_gap_clearance` represents `push_lower_rows_after_bbox_grow`.
   Column demands are route-published and narrowly scoped: a
-  `BoundaryClearanceRequirement` grants runway only for a provisional
-  `NO_APPROACH_SETTLEMENT_ROOM` convergence, while a drawn-corridor demand pays
-  positive-side containment measured from the strict post-grant route. Label
-  wrapping does not independently create a column demand.
+  A `GENERAL` `BoundaryClearanceRequirement` grants runway only for a
+  provisional `NO_APPROACH_SETTLEMENT_ROOM` convergence. A
+  `CORRIDOR_COHORT_APERTURE` requirement grants only the typed, solver-measured
+  deficit of an otherwise atomic cohort allocation. A drawn-corridor demand
+  pays positive-side containment measured from the strict post-grant route.
+  Label wrapping does not independently create a column demand.
 - **Precondition**: `compute_layout` has finished, routing has published the
   reservation ledger, render-time label wrapping has taken its bbox growth, and
   the header-collision reconcile has run. Local station geometry, section bbox

src/nf_metro/layout/engine.py

@@ -503,6 +503,7 @@ def compute_layout(
 
     require_resolved_edge_endpoints(graph)
     require_resolved_port_sections(graph)
+    graph._final_route_guards_deferred = False
 
     if x_spacing is None:
         x_spacing = graph.x_spacing
@@ -571,6 +572,13 @@ def _layout_pass(validate_pass: bool) -> None:
         elif validate and graph._after_final_deferred:
             _run_after_final_checkpoint(graph, section_y_gap, section_y_padding)
 
+        if validate and graph._final_route_guards_deferred:
+            from nf_metro.render.svg import build_render_plan
+            from nf_metro.themes import resolve_theme
+
+            build_render_plan(graph, resolve_theme(None, graph))
+            graph._final_route_guards_deferred = False
+
 
 def _compute_layout_scaled(
     graph: MetroGraph,

src/nf_metro/layout/envelope_settlement.py

@@ -50,11 +50,12 @@
 Re-routing the settled geometry can produce a *different* ledger -- corridors
 appear, vanish, and change their required width -- so this function never
 iterates over successive ledgers.  Each invocation settles exactly the ledger
-it was handed.  The renderer has one bounded exception around a provisional
-convergence-clearance grant: it performs a strict fresh observation after the
-grant, measures that observation's drawn containment once, and settles that
-final ledger before a consuming re-route.  No clearance requirement may be
-published by either strict observation.
+it was handed.  The renderer has one bounded exception around strict drawn
+geometry.  After a provisional convergence-clearance grant, or when the
+consuming re-route places a drawn corridor past its frozen edge, it freezes the
+strict observation's measured containment and settles that final demand before
+one consuming re-route.  No clearance requirement may be published by the final
+strict observation.
 
 Every row- and column-gap claim this stage is handed is therefore allocatable:
 the measurement bounds a boundary by the sections that lie wholly on each side
@@ -94,6 +95,7 @@
 from nf_metro.layout.geometry import measured_distance, shift_section
 from nf_metro.layout.phases.guards import PhaseInvariantError
 from nf_metro.layout.route_plan import (
+    ConvergenceDisposition,
     DemandAxis,
     EmissionMemberId,
     RoutePlan,
@@ -114,6 +116,7 @@
 from nf_metro.layout.settlement_demand import (
     BoundaryClearanceDemand,
     BoundaryClearanceRequirement,
+    BoundaryClearanceRequirementKind,
     ClearanceMeasurement,
     SettlementAxis,
 )
@@ -124,6 +127,7 @@
     "ROW_AXIS",
     "BoundaryClearanceDemand",
     "BoundaryClearanceRequirement",
+    "BoundaryClearanceRequirementKind",
     "ClearanceMeasurement",
     "DrawnCorridorClearanceRequirement",
     "EnvelopeSettlement",
@@ -190,6 +194,14 @@ def drawn_corridor_clearance_requirements(
 ) -> tuple[DrawnCorridorClearanceRequirement, ...]:
     """Freeze widths owed by strict routes drawn past a corridor edge."""
     requirements: list[DrawnCorridorClearanceRequirement] = []
+    fixed_member_ids = {
+        member_id
+        for convergence in (
+            plan.convergence_plans if isinstance(plan, RoutePlan) else ()
+        )
+        if convergence.disposition is ConvergenceDisposition.PLANNED
+        for member_id in convergence.member_ids
+    }
     for reservation in plan.reservations:
         region = reservation.region
         if not isinstance(region, RowGapRegion | ColumnGapRegion):
@@ -200,12 +212,21 @@ def drawn_corridor_clearance_requirements(
         containment = drawn_corridor_containment(
             reservation, realised, route_polylines, reservation.claims
         )
-        deficit = -containment.positive_side_slack
+        negative_deficit = -containment.negative_side_slack
+        positive_deficit = -containment.positive_side_slack
+        deficit = max(negative_deficit, positive_deficit)
         if deficit <= COORD_TOLERANCE:
             continue
+        recentres = not reservation.claims or any(
+            claim.member_id not in fixed_member_ids for claim in reservation.claims
+        )
+        # Boundary settlement moves the positive side. A fixed run past the
+        # negative edge needs matching room on the positive edge to recenter.
+        recentres = recentres or negative_deficit >= positive_deficit
         requirements.append(
             DrawnCorridorClearanceRequirement(
-                reservation, realised.available_width + deficit
+                reservation,
+                realised.available_width + deficit * (2 if recentres else 1),
             )
         )
     return tuple(requirements)
@@ -455,11 +476,32 @@ def _reservation_coordinate_translation(
     coordinates at or beyond the band's start move.
     """
     section_ids = frozenset(translation.section_ids)
+    endpoint_section_by_group = {
+        group.id: group.section_id for group in plan.endpoint_groups
+    }
+    hidden_endpoint_sections = {
+        divergence.junction_id: endpoint_section_by_group[divergence.exit_group_id]
+        for divergence in plan.divergences
+    }
+    hidden_endpoint_sections.update(
+        {
+            convergence.junction_id: endpoint_section_by_group[
+                convergence.entry_group_id
+            ]
+            for convergence in plan.convergences
+        }
+    )
     fully_owned: list[EmissionMemberId] = []
     crossing: list[EmissionMemberId] = []
     for member in plan.members:
-        source_owned = member.source.section_id in section_ids
-        target_owned = member.target.section_id in section_ids
+        source_section = member.source.section_id or hidden_endpoint_sections.get(
+            member.source.station_id
+        )
+        target_section = member.target.section_id or hidden_endpoint_sections.get(
+            member.target.station_id
+        )
+        source_owned = source_section in section_ids
+        target_owned = target_section in section_ids
         if source_owned and target_owned:
             fully_owned.append(member.id)
         elif source_owned != target_owned:
@@ -800,6 +842,13 @@ def _box_extents(section: Section) -> tuple[tuple[float, float], tuple[float, fl
     )
 
 
+def _drawn_against_the_grid(
+    axis: SettlementAxisGeometry, ahead: Section, behind: Section
+) -> bool:
+    """*ahead* is drawn before *behind* while indexed strictly after it."""
+    return axis.start_index(behind) + axis.span(behind) <= axis.start_index(ahead)
+
+
 def _axis_gaps(
     graph: MetroGraph, axis: SettlementAxisGeometry
 ) -> dict[tuple[str, str], float]:
@@ -809,6 +858,13 @@ def _axis_gaps(
     translation.  Boxes that do not overlap across the axis never face each
     other, so the distance between them is not a separation this stage owes
     anything to.
+
+    Neither does a pair drawn in the reverse of the grid order it is filed
+    under.  A widening carries the bands from its boundary onward and leaves
+    the rest, so it opens the distance between two boxes where that distance
+    runs the way their indices do, and closes it where it runs against them.
+    Boxes sharing an index move together under every translation, so their
+    separation is held and stays comparable.
     """
     along_index = 1 if axis.axis is SettlementAxis.ROW else 0
     across_index = 1 - along_index
@@ -826,9 +882,13 @@ def _axis_gaps(
                 continue
             first_start, first_end = first_extents[along_index]
             second_start, second_end = second_extents[along_index]
-            if first_end <= second_start:
+            if first_end <= second_start and not _drawn_against_the_grid(
+                axis, first, second
+            ):
                 gaps[first_key, second_key] = second_start - first_end
-            elif second_end <= first_start:
+            elif second_end <= first_start and not _drawn_against_the_grid(
+                axis, second, first
+            ):
                 gaps[second_key, first_key] = first_start - second_end
     return gaps
 

src/nf_metro/layout/geometry.py

@@ -24,6 +24,16 @@
 _Box = tuple[float, float, float, float]
 
 
+def section_bbox_edges(section: Section) -> _Box:
+    """Return ``(left, top, right, bottom)`` for one section box."""
+    return (
+        section.bbox_x,
+        section.bbox_y,
+        section.bbox_x + section.bbox_w,
+        section.bbox_y + section.bbox_h,
+    )
+
+
 def quantize_coord(value: float, ndigits: int) -> float:
     """Round *value* to *ndigits* decimal places for use as a grouping key.
 

src/nf_metro/layout/ordering.py

@@ -353,10 +353,29 @@ def _place_single_node(
     if node in continuation_nodes:
         return pred_avg
 
+    # Sole-successor chain: every drawn stroke into this node comes from its
+    # single predecessor, and that predecessor feeds nothing else, so the two
+    # form one unbranched run that reads as a straight track.  Lines that
+    # merely begin or end at either station add no incoming geometry, so a
+    # changed line set alone is no reason to hop tracks.  Falls through when
+    # the predecessor's track is already taken at this layer.
+    preds = list(G.predecessors(node))
+    node_layer = layers.get(node, 0) if layers else 0
+    if (
+        len(preds) == 1
+        and preds[0] in tracks
+        and list(G.successors(preds[0])) == [node]
+        and not _is_track_occupied_at_layer(
+            tracks[preds[0]],
+            node_layer,
+            layer_occupancy if layer_occupancy is not None else {},
+            node,
+        )
+    ):
+        return tracks[preds[0]]
+
     # Detect divergence: predecessor has more lines than this node
     if graph is not None:
-        preds = list(G.predecessors(node))
-        node_layer = layers.get(node, 0) if layers else 0
         node_lines = set(graph.station_lines(node))
         pred_lines: set[str] = set()
         for p in preds: