From 8d0f20ebc25d0308207792bd5b978e4c7d2bd38a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tomasz=20Go=C5=82embiewski?= <tgolembiewski@gmail.com>
Date: Tue, 22 Sep 2026 11:43:47 +0200
Subject: [PATCH] fix: place a merge, a lane and the next statement where the
 measurer says

Three fixed-size disagreements between what measureStatements predicts and where
the builder puts things. Every merge, every following statement and every branch
lane is positioned from the first and drawn by the second, so a few pixels of
disagreement is an overlap rather than a cosmetic difference. Measured on
mdl-examples/doctype-tests/02c-complex-layout-examples.mdl: 15 overlapping pairs
in 3 of its 6 flows, down to none. mx check reports 0 errors either way, which is
why none of this was visible to anything automatic.

- A split was measured to its branch rather than to the merge that closes it -
  25px short of what a following element has to clear. splitWidthWithMerge now
  measures from the split's left edge to the merge's right edge.
- The advance past a merge came from its centre by what an activity's half width
  needs: half a pitch is 80px and a merge is 40 wide against an activity's 120, so
  the next element's left edge landed on the merge's right edge. The enum split's
  own merge and `merge <label>` now clear the merge first and then leave the
  ordinary gap, which is what addIfStatement has always done.
- A branch lane was placed half the branch's measured HEIGHT below the line, which
  is only right for content centred on that line. A branch holding a nested IF
  hangs entirely below its own: measured 160 tall it occupies 30 above and 130
  below, so the lane landed 50px inside it. The branch above is already built when
  the next lane is placed, so lowestBetween measures it instead - the same move
  separateRows already makes for wrapped rows. Its range is bounded at both ends,
  because a split's shared merge is appended among its branches.

Two tests hold the invariant rather than the pixel values: one asks the measurer
and the builder the same question about the same run and compares them, the other
asserts directly that no two elements of a built flow overlap, over eight shapes.
Each fix was reverted in turn to confirm they fail with the reported symptom.

TestEnumSplitGeometryIsUnchanged pinned the advance these fixes change; it is now
TestEnumSplitAdvanceClearsItsMerge and pins the gap, with the reason in its
comment. Its other half - that the merge does not drift with branch count - is
unchanged.

Closes #1158

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../fix-issue/findings/mdl-executor.jsonl     |   1 +
 CHANGELOG.md                                  |   8 +
 .../cmd_microflows_builder_actions.go         |  17 +-
 .../cmd_microflows_builder_control.go         |   8 +-
 mdl/executor/cmd_microflows_builder_merge.go  |   6 +-
 ..._microflows_builder_split_geometry_test.go |  25 +-
 mdl/executor/layout.go                        |  52 ++--
 mdl/executor/layout_agreement_test.go         | 241 ++++++++++++++++++
 mdl/executor/layout_lanes.go                  |  43 +++-
 9 files changed, 361 insertions(+), 40 deletions(-)
 create mode 100644 mdl/executor/layout_agreement_test.go

diff --git a/.claude/skills/fix-issue/findings/mdl-executor.jsonl b/.claude/skills/fix-issue/findings/mdl-executor.jsonl
index 3a491f5698..d91bb2b36c 100644
--- a/.claude/skills/fix-issue/findings/mdl-executor.jsonl
+++ b/.claude/skills/fix-issue/findings/mdl-executor.jsonl
@@ -670,3 +670,4 @@
 {"area": "mdl/executor", "date": "2026-09-21", "symptom": "`create or modify entity` drops an attribute a LATER script added, silently. Reported shape: entity created in 01-domain-core.mdl, a calculated attribute added in 03-logic.mdl (its microflow does not exist until then); re-running slice 01 ALONE rebuilt the entity from its own statement and removed the attribute, with `Modified entity: ServiceCore.LithoSystem` as the only output. It surfaced two slices later as `[CE1613] \"The selected attribute 'ServiceCore.LithoSystem.OpenRequestCount' no longer exists.\" at Text 'dtOpen'` — an error naming the PAGE, never the script that removed the attribute. `mxcli check … -p app.mpr --references` said \"Check passed!\".", "ce": "CE1613", "rules": ["MDL087"], "cause": "Half the ask was already shipped and half was not, and the report could not tell them apart. exec's warning (droppedEntityMembers, findings #24, landed 320a304 two weeks before the report) DOES fire — measured on a real 11.6.6 project re-running the reporter's slice 01, it prints the attribute by name — so the reporter was on an older binary. What genuinely did not exist was the issue's second ask: `check` had no project-aware pass for member loss at all, so the one command that runs BEFORE anything is written was the silent one. Added CheckEntityMemberDrops (MDL087, warning) to cmd_check.go's catalog-backed tier, and refactored droppedEntityMembers to share its comparison.", "file": "`mdl/executor/validate_entity_member_drops.go` (new: entityMemberSet, droppedMembers, CheckEntityMemberDrops), `mdl/executor/cmd_entities.go` (droppedEntityMembers now delegates), `cmd/mxcli/cmd_check.go` (projectViolations)", "insight": "**Reproduce before theorising when the report predates a fix in the same area** — exec already printed the exact line the issue asks for, so reading the issue text alone leads either to 'already fixed, close it' or to reimplementing the shipped half. Running the reporter's own sequence against a real project separated the two halves in one command each, and the isolated-slice check printing `Check passed!` is what identified the actual gap. **A check-time twin of an exec-time warning must NOT be the same computation.** exec is per-statement because it is applying statements; check sees the whole script, so it has to be the NET effect — a script that rebuilds an entity and then `alter entity … add attribute`s the members back loses nothing, and that is the IDIOMATIC full-script order, so a per-statement port would warn on every correct script and be switched off within a day. **Intent has to be tracked, not inferred from the outcome**: `drop attribute` / `rename attribute` / `drop entity` produce the same before/after diff as the accident, and a pure diff cannot separate them. Both of those are separate controls, and the naive implementation fails each one specifically (measured: stubbing the net/intent logic fails TestMDL087_ExplicitRemovalIsSilent on 3 of 4 spellings while the positive test still passes — so the positive test alone proves nothing). **One comparison, two layers**: the audit system fields and an omitted `extends` were reported by exec and would have been missed by a second hand-written diff, which is why droppedEntityMembers was refactored onto the shared entityMemberSet rather than copied. An audit pseudo-type (`AutoOwner`) is a FLAG, not an attribute — exec `continue`s past it — so counting it as one makes a faithful restatement read as a drop.", "refs": ["ako/mxcli#562", "findings #24", "findings #13"]}
 {"area": "mdl/executor", "date": "2026-09-21", "symptom": "`retrieve $AccountList from Administration.Account sort by System.Language.Code asc;` — MDL that `mxcli describe` had just emitted — passed `mxcli check` and was refused by `mxcli exec`: \"sort by attribute 'System.Language.Code' does not belong to entity 'Administration.Account'\". Reported as a check/exec inconsistency (mendixlabs/mxcli#1152); the real defect is that the round trip cannot replay its own output for any sort over an association reached from an ANCESTOR.", "cause": "inferSortEntityRefSteps searched ONE domain model — the retrieved entity's own module — for associations whose parent was the retrieved entity ITSELF, and qualified the association it found with the retrieved entity's module. All three assumptions hold only when the hop starts on the retrieved entity in its own module. Administration.Account reaches System.Language through System.User_Language, declared on System.User and stored in the System module: parent is an ancestor, the domain model is another module's, and the qualified name carries THAT module. Rewritten as a generalization-chain walk that looks each ancestor up in its own module and qualifies the association with the module storing it; the destination end is matched with entityIsSubtypeOf rather than by equality, since an association may point at a specialization of the entity that declares the attribute.", "file": "`mdl/executor/cmd_microflows_builder_actions.go` (inferSortEntityRefSteps); tests `mdl/executor/cmd_microflows_sort_association_test.go`, `mdl/backend/modelsdk/microflow_retrievesort_test.go`; example `mdl-examples/bug-tests/microflow-1152-sort-over-association.mdl`", "insight": "**The second control is the one that pays.** Reverting the fix reproduces the refusal, which only proves the test fires. The control that taught something was building a binary that DERIVES the hop and does not WRITE it — exec succeeds and mxbuild 11.12.3 answers CE7247 \"Cannot sort on attribute 'System.Language.Code'. Attribute 'System.Language.Code' is not an attribute of entity 'Administration.Account'\" — the executor's refusal message almost word for word, from the other end of the pipeline. That is what fixes the qualified name as load-bearing: the stored EntityRefStep must read System.User_Language, and the pre-existing code would have written Administration.User_Language had it found anything at all. **Skip the theory that check is missing a rule**: check has no sort-attribute rule at all and resolves no hops, so it was never going to disagree with exec here — the inconsistency in the report is a symptom of the false refusal, not a second defect. **Known residue, stated because the round trip rests on it**: DESCRIBE emits only the attribute's qualified name, so where several associations reach one entity the replay picks the nearest ancestor's first and can silently land on the other hop. Spelling the hop needs grammar (sortColumn is qualifiedName|IDENTIFIER, no `/` path) and is a language change, not a fix."}
 {"area": "mdl/executor", "date": "2026-09-21", "symptom": "Follow-up to the sort-hop inference fix: with the hop derivable but not SAYABLE, `describe → exec` still silently changed the program wherever two associations reach the same entity. Measured on 11.12.3 with Order_ShipTo and Order_BillTo (both Order -> Address): a microflow sorting by the BILLING address came back sorting by the SHIPPING one, `mx check` 0 errors on both sides. Same for a page datasource's sort bar.", "cause": "DESCRIBE emitted only the sort attribute's qualified name and the reader never looked at the hop at all — `sortItemsFromRaw` read AttributeRef.Attribute and skipped AttributeRef.EntityRef, so the association was written and never read back. MDL had no spelling for it either (`sortColumn : (qualifiedName | IDENTIFIER)`). Closed end to end: sortColumn takes `qualifiedName (SLASH qualifiedName)*` (the shape MDLCatalog.g4 already uses for Association/Entity), SortColumnDef/OrderByItemV3 carry the hops, the executor resolves the NAMED association instead of inferring, both readers reconstruct EntityRef.Steps, both describers emit `Assoc/.../Attr`, and the page writers moved from attributeRefToGen to inputAttributeRefToGen. Inference stays as the fallback, so every script written before still works.", "file": "`mdl/grammar/domains/MDLPage.g4` (sortColumn) + `mdl/ast/ast_page.go`/`ast_page_v3.go` + `mdl/visitor/visitor_microflow_statements.go` (sortColumnHops) + `visitor_page_v3.go` + `mdl/executor/cmd_microflows_builder_actions.go` (resolveSortAssociationPath, lookupSortHop, entityChainModules) + `cmd_microflows_format_action.go` + `cmd_pages_builder_v3.go` (resolveAssociationAttributePathForEntity) + `cmd_pages_describe_datasource.go` (sortAttributeHops, sortColumnPath) + `mdl/backend/modelsdk/microflow_read_actions.go` (entityRefStepsFromRaw) + `widget_write.go` + `sdk/pages/pages_datasources.go` (GridSort.AttributeRefSteps)", "insight": "**The measurement that decides whether a lossy describer is worth a language change is a CONSTRUCTED one.** The corpus agrees with the inference rule by construction — every document mxcli itself wrote stores the association inference would have picked, so the round trip is a fixed point on everything to hand and looks faithful. The case that matters had to be built: two associations to one entity, then the stored hop edited to the one inference does NOT pick. Byte-patching the .mxunit is enough and takes a minute — `Order_ShipTo` and `Order_BillTo` are the same length, so a `sed` on the BSON needs no resize — and the replay flipped it back immediately. **Control on a binary that drops the hop, not just on one that reverts the fix**: reverting only proves the test fires, while dropping the hop gets mxbuild to say CE7247 \"Cannot sort on attribute … is not an attribute of entity …\" — the executor's own refusal message from the other end of the pipeline, which is what proves the EntityRef load-bearing rather than cosmetic. **Two reads were missing, not one**: the microflow reader and the page reader each drop the hop separately, and fixing only the half named in the report would have shipped a describer that emits the path for microflows and silently drops it for pages. **The strongest round-trip evidence is 'Unchanged'** — with identity preservation and write elision, replaying DESCRIBE output on a correct implementation elides the write entirely, so `Unchanged microflow: …` is a stronger result than any byte comparison."}
+{"area": "mdl/executor", "date": "2026-09-22", "symptom": "Elements of a generated microflow overlap wherever the shape needs a nested decision, a named `merge <label>` or a `case` with several branches (mendixlabs/mxcli#1158). Measured on mdl-examples/doctype-tests/02c-complex-layout-examples.mdl: 15 overlapping pairs in 3 of its 6 flows - an activity sitting on the merge that closes a split, a branch lane 50px inside the lane above it, and the first statement after a `merge` with its left edge on the merge's right edge. `mx check` reports 0 errors either way.", "cause": "Three fixed-size disagreements between layout.go's measurer and the builder, each harmless on its own and none caught by a test. (1) measureIfStatement/measureEnumSplitStatement stopped at `SplitWidth + HorizontalSpacing/2 + branchWidth + MergeSize`, which is the branch's extent plus a merge's width rather than the distance from the split's LEFT edge to the merge's RIGHT edge - 25px short. (2) `fb.posX = mergeX + HorizontalSpacing/2` (enum split) and `fb.posX += fb.spacing/2` (addMergeStatement) advance from the merge's CENTRE by what an activity's half-width needs; a merge is MergeSize=40 wide against ActivityWidth=120, so the gap came out 0. addIfStatement always used `mergeX + MergeSize + HorizontalSpacing/2` and was right. (3) `elseCenterY = centerY + thenH/2 + BranchGap + elseH/2` (and the same arithmetic stacking enum branches) treats a branch's measured HEIGHT as symmetric about its line, but a branch holding a nested IF hangs entirely below it: measured 160 tall, it occupies 30 above the line and 130 below, so the next lane landed 50px inside it.", "file": "`mdl/executor/layout.go` (splitWidthWithMerge, gapBetween), `mdl/executor/layout_lanes.go` (guardBranchInset, lowestBetween), `mdl/executor/cmd_microflows_builder_merge.go` (addMergeStatement), `mdl/executor/cmd_microflows_builder_actions.go` (addEnumSplit), `mdl/executor/cmd_microflows_builder_control.go` (addIfStatement)", "insight": "**A second number describing the same thing is a defect waiting for someone to tighten a constant.** These three were all present before the row/lane work and all hidden by slack in the spacing; removing the slack turned them into overlaps within a day. The lasting fix is not the arithmetic but the test shape: `TestMeasuredWidthMatchesWhatIsBuilt` asks the measurer and the builder the same question about the same run and compares, and `TestBuiltElementsDoNotOverlap` asserts the invariant directly, so the next constant that moves fails loudly instead of silently. **Reach for the real geometry over a model of it whenever the thing is already built** - the branch above a lane exists by the time the lane is placed (lowestBetween), exactly as separateRows already measures finished rows. Two traps when doing that: bound the range at BOTH ends, because a split's shared merge is appended among its branches and an open range measures it as part of whichever branch came before; and a control experiment must be run per fix - three of these tests passed with their fix reverted until the shapes were widened, because two elements can be vertically clear of each other simply by being in different columns.", "refs": ["mendixlabs/mxcli#1158", "mendixlabs/mxcli#1154", "mendixlabs/mxcli#1157"]}
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 32dc27fa18..b06f293695 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+### Fixed
+
+- **Elements overlapped where a microflow's layout needed a nested decision, a named merge or a wide `case`** (mendixlabs/mxcli#1158). Three fixed-size disagreements between what `measureStatements` predicts and where the builder actually places things — every merge, every following statement and every branch lane is positioned from the first and drawn by the second, so a few pixels of disagreement is an overlap rather than a cosmetic difference. Measured on `mdl-examples/doctype-tests/02c-complex-layout-examples.mdl`: **15 overlapping pairs in 3 of its 6 flows, down to none** (`mx check` 0 errors before and after).
+
+  - **A split was measured to its branch, not to the merge that closes it** — 25 px short, because the merge is what a following statement has to clear. Nothing noticed while an extra half pitch was still being added on top of every split's width.
+  - **The advance past a merge came from its centre as though a merge were an activity's width.** Half a pitch is 80 px; a merge is 40 wide against an activity's 120, so the next element's left edge landed exactly on the merge's right edge. Both the `case` statement's own merge and `merge <label>` now clear the merge first and then leave the ordinary gap, which is what `if` has always done.
+  - **A branch lane was placed half the branch's measured HEIGHT below the line.** That is only right for content centred on its line: a branch holding a nested `if` hangs entirely below its own, so a lane placed on the measurement landed 50 px inside it. The branch above is already built when the next lane is placed, so its real extent is measured instead of modelled.
+
 ### Changed
 
 - **Microflows written without `@position` are laid out to be read, not just to be valid** (mendixlabs/mxcli#1154). Geometry and connection sides only: no MDL syntax changes, a statement carrying `@position` is never moved, and `describe` → `exec` still reports `Unchanged microflow`. Measured on a generated app of 41 microflows, none with an `@position`: the widest flow went from 6930×160 px on one row to 3220 px, with 0 overlapping elements and `mx check` at 0 errors before and after.
diff --git a/mdl/executor/cmd_microflows_builder_actions.go b/mdl/executor/cmd_microflows_builder_actions.go
index ec6316e905..0cfc279953 100644
--- a/mdl/executor/cmd_microflows_builder_actions.go
+++ b/mdl/executor/cmd_microflows_builder_actions.go
@@ -475,6 +475,11 @@ func (fb *flowBuilder) addEnumSplit(s *ast.EnumSplitStmt) model.ID {
 		}
 	}
 
+	// The branch above's own objects, so a lane can be placed clear of what it really
+	// occupies. Bounded at both ends: the merge that closes the split is appended
+	// while the branches are being built, and it sits on the centre line, so an open
+	// range would measure it as part of whichever branch came before it.
+	prevBranchStart, prevBranchEnd := 0, 0
 	origins := enumSplitOriginAnchors(branchYs, centerY)
 	slot := func(i int) splitCaseSlot {
 		if origins == nil {
@@ -486,6 +491,15 @@ func (fb *flowBuilder) addEnumSplit(s *ast.EnumSplitStmt) model.ID {
 	savedEndsWithReturn := fb.endsWithReturn
 	allBranchesReturn := len(branches) > 0
 	for i, br := range branches {
+		if i > 0 {
+			// Clear of what the branch above actually occupies, not of half its
+			// measured height: a branch holding a nested IF hangs below its own line.
+			fallback := branchYs[i-1] + ActivityHeight/2
+			if below := fb.lowestBetween(prevBranchStart, prevBranchEnd, fallback) + BranchGap + branchHeights[i]/2; below > branchYs[i] {
+				branchYs[i] = below
+			}
+		}
+		prevBranchStart = len(fb.objects)
 		branchY := branchYs[i]
 		fb.posX = splitX + SplitWidth + HorizontalSpacing/2
 		fb.posY = branchY
@@ -554,6 +568,7 @@ func (fb *flowBuilder) addEnumSplit(s *ast.EnumSplitStmt) model.ID {
 				lastID = actID
 			}
 		}
+		prevBranchEnd = len(fb.objects)
 
 		if lastStmtIsReturn(br.body) {
 			continue
@@ -575,7 +590,7 @@ func (fb *flowBuilder) addEnumSplit(s *ast.EnumSplitStmt) model.ID {
 		}
 	}
 
-	fb.posX = mergeX + HorizontalSpacing/2
+	fb.posX = mergeX + MergeSize + HorizontalSpacing/2
 	fb.posY = centerY
 	fb.endsWithReturn = savedEndsWithReturn
 	if allBranchesReturn {
diff --git a/mdl/executor/cmd_microflows_builder_control.go b/mdl/executor/cmd_microflows_builder_control.go
index bd26a1bf42..e98712da46 100644
--- a/mdl/executor/cmd_microflows_builder_control.go
+++ b/mdl/executor/cmd_microflows_builder_control.go
@@ -149,6 +149,7 @@ func (fb *flowBuilder) addIfStatement(s *ast.IfStmt) model.ID {
 
 	if hasElseBody {
 		// IF WITH ELSE: TRUE path horizontal (happy path), FALSE path below
+		thenFirstObject := len(fb.objects)
 		fb.posX = thenStartX
 		fb.posY = centerY
 		fb.endsWithReturn = false
@@ -241,10 +242,15 @@ func (fb *flowBuilder) addIfStatement(s *ast.IfStmt) model.ID {
 			fb.addPendingErrorHandlerFlowTo(mergeID)
 		}
 
-		// Process ELSE body (below the THEN path)
+		// Process ELSE body (below the THEN path), clear of what the THEN path
+		// actually occupies — see lowestSince: a THEN that contains a nested IF hangs
+		// below its own line, and half its measured height does not reach that far.
 		thenH := max(thenBounds.Height, ActivityHeight)
 		elseH := max(elseBounds.Height, ActivityHeight)
 		elseCenterY := centerY + thenH/2 + BranchGap + elseH/2
+		if built := fb.lowestBetween(thenFirstObject, -1, centerY+ActivityHeight/2) + BranchGap + elseH/2; built > elseCenterY {
+			elseCenterY = built
+		}
 		fb.posX = thenStartX
 		fb.posY = elseCenterY
 		fb.endsWithReturn = false
diff --git a/mdl/executor/cmd_microflows_builder_merge.go b/mdl/executor/cmd_microflows_builder_merge.go
index 9c556a0e3f..6671cff3a4 100644
--- a/mdl/executor/cmd_microflows_builder_merge.go
+++ b/mdl/executor/cmd_microflows_builder_merge.go
@@ -109,7 +109,11 @@ func (fb *flowBuilder) addMergeStatement(s *ast.MergeStmt) model.ID {
 	// Adopt the declaration's position even when a forward `join` created the
 	// object earlier at whatever the cursor happened to be.
 	m.Position = model.Point{X: fb.posX, Y: fb.posY}
-	fb.posX += fb.spacing / 2
+	// A merge is MergeSize wide, not an activity's width, so half a pitch from its
+	// CENTRE put the next activity's edge exactly on the merge's. Clear the merge
+	// first, then leave the ordinary gap — the same arithmetic addIfStatement uses
+	// after the merge that closes a split.
+	fb.posX += MergeSize + fb.spacing/2
 	// A merge is a join point, not a terminator: whatever follows continues from
 	// it, so an end event is owed again even if the path that reached here
 	// arrived by `join`.
diff --git a/mdl/executor/cmd_microflows_builder_split_geometry_test.go b/mdl/executor/cmd_microflows_builder_split_geometry_test.go
index 19dfcfeb6a..05e097d6f9 100644
--- a/mdl/executor/cmd_microflows_builder_split_geometry_test.go
+++ b/mdl/executor/cmd_microflows_builder_split_geometry_test.go
@@ -149,10 +149,18 @@ func TestTypeSplitMergeDoesFollowBranchWidth(t *testing.T) {
 	}
 }
 
-// The enum split is the construct the field report compared against, and it was
-// already correct. Pinned here so a later attempt to unify the two cannot move
-// it silently: every existing enum split in every project would be re-laid out.
-func TestEnumSplitGeometryIsUnchanged(t *testing.T) {
+// The enum split is the construct the field report compared against. Pinned here so
+// a later attempt to unify the two cannot move it silently: every existing enum
+// split in every project would be re-laid out.
+//
+// Its merge still stands where one branch's width puts it, whatever the branch
+// count. What DID change, deliberately: the advance past that merge. Half a pitch
+// from the merge's CENTRE is 80px, and a merge is 40 wide against an activity's 120,
+// so the next activity's left edge landed exactly on the merge's right edge — two
+// touching elements on the main line of every enum split with a statement after it.
+// The advance now clears the merge first and then leaves the ordinary gap, which is
+// the arithmetic addIfStatement has always used after the merge that closes an IF.
+func TestEnumSplitAdvanceClearsItsMerge(t *testing.T) {
 	build := func(n int) (*microflows.ExclusiveMerge, int) {
 		s := &ast.EnumSplitStmt{Variable: "kind"}
 		for i := 0; i < n; i++ {
@@ -172,8 +180,11 @@ func TestEnumSplitGeometryIsUnchanged(t *testing.T) {
 	if two.Position.X != five.Position.X {
 		t.Errorf("enum split merge moved with branch count: x=%d then x=%d", two.Position.X, five.Position.X)
 	}
-	if want := two.Position.X + HorizontalSpacing/2; nextTwo != want {
-		t.Errorf("enum split next x = %d, want %d — this test pins existing behaviour; "+
-			"changing it re-lays-out every enum split ever written", nextTwo, want)
+	if want := two.Position.X + MergeSize + HorizontalSpacing/2; nextTwo != want {
+		t.Errorf("enum split next x = %d, want %d (clear the merge, then one gap)", nextTwo, want)
+	}
+	if gap := (nextTwo - ActivityWidth/2) - (two.Position.X + MergeSize/2); gap != laneGap {
+		t.Errorf("gap between the merge and the next activity is %d, want %d — the same "+
+			"space two activities have", gap, laneGap)
 	}
 }
diff --git a/mdl/executor/layout.go b/mdl/executor/layout.go
index 1ec4907c74..5e45238915 100644
--- a/mdl/executor/layout.go
+++ b/mdl/executor/layout.go
@@ -111,6 +111,17 @@ func (m *layoutMeasurer) measureBranch(stmts []ast.MicroflowStatement) Bounds {
 	return b
 }
 
+// splitWidthWithMerge is how wide a split and its branches really are: from the
+// split's left edge to the right edge of the merge that closes them. The branch
+// width is edge to edge and starts half an activity left of thenStartX.
+//
+// Measured to the MERGE, not to the branch: the merge is the element a following
+// statement has to clear, and a width that stopped at the branch left it 25px short
+// — which nothing noticed while an extra half pitch was being added on top.
+func splitWidthWithMerge(branchWidth int) int {
+	return SplitWidth/2 + SplitWidth + HorizontalSpacing/2 + branchWidth + MergeSize/2
+}
+
 // gapBetween is the empty space the builder actually leaves between two consecutive
 // elements of a run, edge to edge.
 //
@@ -125,31 +136,20 @@ func (m *layoutMeasurer) measureBranch(stmts []ast.MicroflowStatement) Bounds {
 // keeps the old, generous gap, because a merge placed short of its branch's content
 // is worse than a merge placed long.
 func gapBetween(prev, next ast.MicroflowStatement) int {
-	// Distance from prev's measured right edge to the centre the builder gives next.
-	var toNextCentre int
-	switch prev.(type) {
-	case *ast.IfStmt:
-		// After an IF, posX = (measured right edge) + HorizontalSpacing/2.
-		toNextCentre = HorizontalSpacing / 2
-	case *ast.EnumSplitStmt, *ast.InheritanceSplitStmt:
-		return HorizontalSpacing
-	default:
-		// A simple activity, or a loop box: after either, the builder centres the
-		// next element one activity-gap plus half an activity past the right edge.
-		// A simple activity: centre-to-centre pitch, less its own right half.
-		toNextCentre = HorizontalSpacing - ActivityWidth/2
+	// The builder leaves the same empty space after every element: it centres the
+	// next one laneGap past the previous right edge. The one exception is a guard,
+	// whose branch drops into the lane below and whose main line therefore resumes
+	// in the branch's own column, half a pitch past the split.
+	toNextCentre := ActivityWidth/2 + laneGap
+	if s, ok := prev.(*ast.IfStmt); ok && isGuard(s) {
+		toNextCentre = SplitWidth/2 + HorizontalSpacing/2
 	}
-	// How far next reaches left of the centre it is given.
-	var leftHalf int
-	switch next.(type) {
-	case *ast.IfStmt, *ast.EnumSplitStmt:
-		leftHalf = SplitWidth / 2
-	default:
-		// An activity — and a loop box, whose left edge the builder now puts where
-		// an activity's would be.
-		leftHalf = ActivityWidth / 2
+	if _, ok := prev.(*ast.InheritanceSplitStmt); ok {
+		// Its branches are still placed on a fixed vertical step and its advance is
+		// not derived here; keep the old, generous gap.
+		return HorizontalSpacing
 	}
-	return max(toNextCentre-leftHalf, 20)
+	return max(toNextCentre-leftHalfOf(next), 20)
 }
 
 // measureStatementsSpan returns the horizontal extent a statement run actually
@@ -237,7 +237,7 @@ func (m *layoutMeasurer) measureEnumSplitStatement(s *ast.EnumSplitStmt) Bounds
 	}
 	totalHeight += (len(branchHeights) - 1) * BranchGap
 
-	width := SplitWidth + HorizontalSpacing/2 + maxBranchWidth + MergeSize
+	width := splitWidthWithMerge(maxBranchWidth)
 	return Bounds{Width: width, Height: totalHeight}
 }
 
@@ -283,14 +283,14 @@ func (m *layoutMeasurer) measureIfStatement(s *ast.IfStmt) Bounds {
 		branchWidth = HorizontalSpacing / 2
 	}
 
-	totalWidth := SplitWidth + HorizontalSpacing/2 + branchWidth + MergeSize
+	totalWidth := splitWidthWithMerge(branchWidth)
 	// A guard — `if X then ...; return; end if` with no ELSE — has no merge: its
 	// branch ends in an end event and the main line resumes straight after the
 	// branch (addIfStatement's no-merge exit). Measuring a merge and its spacing
 	// that are never drawn left 120px of empty main line after every guard nested
 	// in a branch.
 	if isGuard(s) {
-		totalWidth = SplitWidth + HorizontalSpacing/2 + thenBounds.Width
+		totalWidth = guardBranchInset + thenBounds.Width
 	}
 
 	// Height depends on layout strategy
diff --git a/mdl/executor/layout_agreement_test.go b/mdl/executor/layout_agreement_test.go
new file mode 100644
index 0000000000..26a549e67f
--- /dev/null
+++ b/mdl/executor/layout_agreement_test.go
@@ -0,0 +1,241 @@
+// SPDX-License-Identifier: Apache-2.0
+
+// Package executor - the measurer and the builder have to agree.
+//
+// Two numbers describe the same element: what measureStatements predicts it will
+// occupy, and where the builder actually puts it. Everything that places an element
+// beside another one — a merge after its branch, the next statement on the main
+// line, a branch lane under the one above — is derived from the first and drawn by
+// the second, so a disagreement of a few pixels is not cosmetic: it is an overlap.
+//
+// Measured on mdl-examples/doctype-tests/02c-complex-layout-examples.mdl, whose six
+// flows carry nested decisions, named merges and backward jumps: 15 pairs of
+// overlapping elements in 3 of the 6 flows, all from three fixed-size disagreements.
+// A split was measured to its branch rather than to the merge that closes it (25px
+// short), the advance past a merge came from its centre as though it were an
+// activity's width (80px where 120 was needed), and a branch lane was placed half
+// the branch's measured HEIGHT below the line although a branch holding a nested IF
+// hangs entirely below its own line (50px short).
+//
+// These tests pin the agreement rather than the pixel values: each asks the builder
+// where an element ended up and the measurer what it predicted, and compares.
+package executor
+
+import (
+	"fmt"
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+	"github.com/mendixlabs/mxcli/model"
+	"github.com/mendixlabs/mxcli/sdk/microflows"
+)
+
+// box is an element's rectangle on the canvas.
+type box struct {
+	left, right, top, bottom int
+	what                     string
+}
+
+// boxesOf returns every object the builder placed, as rectangles. Loop children are
+// in their own coordinate space inside the box, so a LoopedActivity's contents are
+// not part of this list — they cannot collide with anything outside it.
+func boxesOf(objects []microflows.MicroflowObject) []box {
+	var out []box
+	for _, o := range objects {
+		if o == nil {
+			continue
+		}
+		w, h := ActivityWidth, ActivityHeight
+		switch o.(type) {
+		case *microflows.ExclusiveSplit, *microflows.InheritanceSplit:
+			w, h = SplitWidth, SplitHeight
+		case *microflows.ExclusiveMerge:
+			w, h = MergeSize, MergeSize
+		case *microflows.StartEvent, *microflows.EndEvent:
+			w, h = EventSize, EventSize
+		case *microflows.Annotation:
+			w, h = DefaultAnnotationSize.Width, DefaultAnnotationSize.Height
+		}
+		if ws, ok := o.(interface{ GetSize() model.Size }); ok {
+			if s := ws.GetSize(); s.Width > 0 && s.Height > 0 {
+				w, h = s.Width, s.Height
+			}
+		}
+		p := o.GetPosition()
+		out = append(out, box{p.X - w/2, p.X + w/2, p.Y - h/2, p.Y + h/2, fmt.Sprintf("%T at (%d,%d)", o, p.X, p.Y)})
+	}
+	return out
+}
+
+// buildFlow lays out a whole microflow the way exec does.
+func buildFlow(stmts []ast.MicroflowStatement) *flowBuilder {
+	fb := &flowBuilder{
+		posX: 200, posY: 200, baseY: 200, spacing: HorizontalSpacing, allowWrap: true,
+		varTypes: map[string]string{}, declaredVars: map[string]string{},
+		measurer: &layoutMeasurer{varTypes: map[string]string{}},
+	}
+	fb.buildFlowGraph(stmts, nil)
+	return fb
+}
+
+func ifElse(then, els []ast.MicroflowStatement) *ast.IfStmt {
+	return &ast.IfStmt{
+		Condition: &ast.LiteralExpr{Kind: ast.LiteralBoolean, Value: true},
+		ThenBody:  then,
+		ElseBody:  els,
+		HasElse:   true,
+	}
+}
+
+func casesOf(bodies ...[]ast.MicroflowStatement) *ast.EnumSplitStmt {
+	s := &ast.EnumSplitStmt{Variable: "Status"}
+	for i, b := range bodies {
+		s.Cases = append(s.Cases, ast.EnumSplitCase{Values: []string{fmt.Sprintf("V%d", i+1)}, Body: b})
+	}
+	return s
+}
+
+// TestBuiltElementsDoNotOverlap is the invariant the three fixes exist to keep. The
+// shapes are the ones the complex-layout examples are built from; each overlapped
+// before its fix.
+func TestBuiltElementsDoNotOverlap(t *testing.T) {
+	shapes := map[string][]ast.MicroflowStatement{
+		"an activity after a named merge": {
+			&ast.MergeStmt{Label: "rejoin"},
+			&ast.LogStmt{Level: ast.LogInfo, Message: &ast.LiteralExpr{Kind: ast.LiteralString, Value: "after"}},
+		},
+		"an activity after a decision": {
+			ifElse(logStatements(2), logStatements(1)),
+			&ast.LogStmt{Level: ast.LogInfo, Message: &ast.LiteralExpr{Kind: ast.LiteralString, Value: "after"}},
+		},
+		// The ELSE branch is several activities long on purpose: a nested decision's
+		// own else lane hangs below the THEN line one column further right, so a
+		// one-activity ELSE passes underneath it and collides with nothing. It is the
+		// SECOND activity of the ELSE that arrives in that column.
+		"a decision whose THEN holds another decision": {
+			ifElse(
+				[]ast.MicroflowStatement{ifElse(logStatements(1), logStatements(1))},
+				logStatements(3),
+			),
+			&ast.LogStmt{Level: ast.LogInfo, Message: &ast.LiteralExpr{Kind: ast.LiteralString, Value: "after"}},
+		},
+		"two decisions in a row": {
+			ifElse(logStatements(1), logStatements(1)),
+			ifElse(logStatements(1), logStatements(1)),
+		},
+		"an activity after a CASE": {
+			casesOf(logStatements(1), logStatements(1), logStatements(1)),
+			&ast.LogStmt{Level: ast.LogInfo, Message: &ast.LiteralExpr{Kind: ast.LiteralString, Value: "after"}},
+		},
+		"a CASE whose branches hold decisions": {
+			casesOf(
+				[]ast.MicroflowStatement{ifElse(logStatements(1), logStatements(1))},
+				logStatements(3),
+				[]ast.MicroflowStatement{ifElse(logStatements(1), logStatements(1))},
+			),
+			&ast.LogStmt{Level: ast.LogInfo, Message: &ast.LiteralExpr{Kind: ast.LiteralString, Value: "after"}},
+		},
+		"a guard, then a decision": {
+			guardStmt(),
+			ifElse(logStatements(1), logStatements(1)),
+		},
+		"a loop between two decisions": {
+			ifElse(logStatements(1), logStatements(1)),
+			&ast.LoopStmt{LoopVariable: "Item", ListVariable: "List", Body: logStatements(2)},
+			ifElse(logStatements(1), logStatements(1)),
+		},
+	}
+
+	for name, stmts := range shapes {
+		t.Run(name, func(t *testing.T) {
+			boxes := boxesOf(buildFlow(stmts).objects)
+			for i := 0; i < len(boxes); i++ {
+				for j := i + 1; j < len(boxes); j++ {
+					a, b := boxes[i], boxes[j]
+					if a.left < b.right && b.left < a.right && a.top < b.bottom && b.top < a.bottom {
+						t.Errorf("%s overlaps %s", a.what, b.what)
+					}
+				}
+			}
+		})
+	}
+}
+
+// TestMeasuredWidthMatchesWhatIsBuilt asks the two halves the same question. The
+// measurer's answer is what every merge and every following element is placed from,
+// so it may not be short — and a measure that is merely generous wastes the canvas.
+func TestMeasuredWidthMatchesWhatIsBuilt(t *testing.T) {
+	runs := map[string][]ast.MicroflowStatement{
+		"a decision":                 {ifElse(logStatements(2), logStatements(1))},
+		"a decision then a decision": {ifElse(logStatements(1), logStatements(1)), ifElse(logStatements(2), logStatements(1))},
+		"a decision then an activity": {
+			ifElse(logStatements(2), logStatements(1)),
+			&ast.LogStmt{Level: ast.LogInfo, Message: &ast.LiteralExpr{Kind: ast.LiteralString, Value: "after"}},
+		},
+		"a CASE then an activity": {
+			casesOf(logStatements(2), logStatements(1)),
+			&ast.LogStmt{Level: ast.LogInfo, Message: &ast.LiteralExpr{Kind: ast.LiteralString, Value: "after"}},
+		},
+		"a guard then an activity": {
+			guardStmt(),
+			&ast.LogStmt{Level: ast.LogInfo, Message: &ast.LiteralExpr{Kind: ast.LiteralString, Value: "after"}},
+		},
+	}
+
+	for name, stmts := range runs {
+		t.Run(name, func(t *testing.T) {
+			fb := buildFlow(stmts)
+			// Everything the statements drew: the flow's start event sits one spacing
+			// before the run and its final end event one after, so both are dropped —
+			// but an end event a BRANCH draws is part of that branch and stays.
+			objects := fb.objects
+			if len(objects) > 0 {
+				if _, isStart := objects[0].(*microflows.StartEvent); isStart {
+					objects = objects[1:]
+				}
+			}
+			if n := len(objects); n > 0 {
+				if _, isEnd := objects[n-1].(*microflows.EndEvent); isEnd {
+					objects = objects[:n-1]
+				}
+			}
+			left, right := 1<<30, -(1 << 30)
+			for _, b := range boxesOf(objects) {
+				left, right = min(left, b.left), max(right, b.right)
+			}
+			built := right - left
+			measured := (&layoutMeasurer{varTypes: map[string]string{}}).measureStatements(stmts).Width
+			if measured != built {
+				t.Errorf("measured %d, built %d — a short measure overlaps the next element, a long one wastes canvas",
+					measured, built)
+			}
+		})
+	}
+}
+
+// TestNamedMergeLeavesTheOrdinaryGap pins a distance, not an absence of overlap: a
+// zero gap puts two edges on top of each other without the rectangles intersecting,
+// so only a measurement catches it. `merge <label>` advanced half a pitch from the
+// merge's CENTRE, which is what an activity's width needs; a merge is 40 wide.
+func TestNamedMergeLeavesTheOrdinaryGap(t *testing.T) {
+	fb := buildFlow([]ast.MicroflowStatement{
+		&ast.MergeStmt{Label: "rejoin"},
+		&ast.LogStmt{Level: ast.LogInfo, Message: &ast.LiteralExpr{Kind: ast.LiteralString, Value: "after"}},
+	})
+	var merge, activity model.Point
+	for _, o := range fb.objects {
+		switch o.(type) {
+		case *microflows.ExclusiveMerge:
+			merge = o.GetPosition()
+		case *microflows.ActionActivity:
+			activity = o.GetPosition()
+		}
+	}
+	if merge.X == 0 || activity.X == 0 {
+		t.Fatal("expected a merge and an activity")
+	}
+	if gap := (activity.X - ActivityWidth/2) - (merge.X + MergeSize/2); gap != laneGap {
+		t.Errorf("gap between the merge and the activity after it is %d, want %d — the same "+
+			"space two activities have", gap, laneGap)
+	}
+}
diff --git a/mdl/executor/layout_lanes.go b/mdl/executor/layout_lanes.go
index 827efc98b2..27f5209c30 100644
--- a/mdl/executor/layout_lanes.go
+++ b/mdl/executor/layout_lanes.go
@@ -15,13 +15,16 @@
 // wait for it to clear; a plain activity does not.
 package executor
 
-import "github.com/mendixlabs/mxcli/mdl/ast"
+import (
+	"github.com/mendixlabs/mxcli/mdl/ast"
+	"github.com/mendixlabs/mxcli/model"
+)
 
 const (
 	// guardBranchInset is where a guard's branch starts, measured the way the
-	// measurer measures: from the split's x to the left edge of the branch's first
-	// activity (thenStartX - ActivityWidth/2).
-	guardBranchInset = SplitWidth + HorizontalSpacing/2 - ActivityWidth/2
+	// measurer measures: from the split's LEFT EDGE to the left edge of the branch's
+	// first activity (thenStartX - ActivityWidth/2).
+	guardBranchInset = SplitWidth/2 + SplitWidth + HorizontalSpacing/2 - ActivityWidth/2
 
 	// guardMainWidth is what a guard takes of the main line, in the measurer's terms:
 	// gapBetween adds HorizontalSpacing/2 after an IF, and the builder puts the next
@@ -87,3 +90,35 @@ func (fb *flowBuilder) clearLowerLane(stmt ast.MicroflowStatement) {
 		fb.posX = busy + half
 	}
 }
+
+// lowestBetween is the bottom edge of the objects in fb.objects[start:end], or the
+// fallback when that range holds none. end may be -1 for "everything since start".
+//
+// A branch's measured height says how TALL it is, and the builder places the next
+// lane half that height below the line — which is only right when the content is
+// centred on its line. A nested IF is not: its own else lane hangs entirely below,
+// so a branch measured 160 tall occupies 30 above its line and 130 below, and the
+// lane placed on the measurement landed 50px into it. The branch is already built by
+// the time the next lane is placed, so this measures it instead of modelling it.
+func (fb *flowBuilder) lowestBetween(start, end, fallback int) int {
+	if end < 0 || end > len(fb.objects) {
+		end = len(fb.objects)
+	}
+	bottom := fallback
+	for i := start; i < end; i++ {
+		o := fb.objects[i]
+		if o == nil {
+			continue
+		}
+		h := ActivityHeight
+		if ws, ok := o.(interface{ GetSize() model.Size }); ok {
+			if hh := ws.GetSize().Height; hh > 0 {
+				h = hh
+			}
+		}
+		if b := o.GetPosition().Y + h/2; b > bottom {
+			bottom = b
+		}
+	}
+	return bottom
+}