docs: define explicit Arrange route reset and undo behavior

docs/language.rst

@@ -1255,6 +1255,55 @@ translates pins when both actual endpoint owners move by the same delta; label
 offsets remain relative. Raw ``EditNode`` and source position edits are exact
 record edits and do not implicitly translate pins.
 
+Explicit ``Layout(diagram)`` (Auto-layout / Arrange elements) is an exception to
+route-override preservation. Immediately before this operation changes geometry,
+it MUST determine eligibility from the staged Project's ordinary filtered
+projection. An edge is eligible only if it is visible, both actual endpoint-owner
+placements exist, both projected owner nodes exist, and its projected source and
+target equal those actual owners in stored orientation. A semantic Port belongs
+to its actual owning placement; hiding its marker does not make the edge
+ineligible. An endpoint promoted to a folded ancestor does. Missing owners MUST
+NOT be inferred. In a Batch, this input includes preceding staged operations;
+determining eligibility MUST NOT introduce separate validation of a batch prefix.
+
+For each existing eligible route entry, Layout MUST clear ``waypoints`` and the
+entire ``label`` override (both fraction and offset). It MUST retain the entry,
+its list position, edge identity, and both attachment values, including dormant
+attachments at semantic ports. Empty and attachments-only entries MUST NOT be
+removed. Layout MUST NOT create route entries merely to record generated elbows
+or automatic label placement. Node port-anchor records remain exact, although
+moving or resizing their owners can change their physical positions.
+
+Ineligible routes, including hidden, filtered and promoted edges, MUST NOT be
+reset. Their labels, attachments, identities and list order remain exact. Their
+waypoints follow the existing movement rule: translate only when both actual
+endpoint-owner placements receive the same nonzero original-to-final delta,
+subject also to the existing State boundary movement rule. For a State Entry/Exit
+endpoint whose owning State boundary has a placement, that boundary placement
+must move with the same delta before the stored pins translate. Otherwise retain
+the waypoint values.
+Promotion to a visible ancestor alone does not authorize translation. Eligibility
+limits route reset, not placement scope: ordinary Layout may still reposition or
+resize hidden and folded descendant placements. Other diagrams remain unchanged.
+
+Placement changes and eligible resets form one atomic Layout mutation. A changed
+standalone Layout creates one history entry; Layout within Batch or execute_many
+shares the enclosing transaction's entry, even when that transaction contains
+several Layout operations. Validate the complete candidate through the ordinary
+transaction path. Rejection leaves the accepted Project and history unchanged;
+an identical enclosing transaction creates no entry and preserves Redo. Undo
+restores the pre-transaction placement and route records. A separately applied
+desktop property draft retains its own history entry; Layout does not merge it.
+
+This exception does not change ordinary dragging, group movement, reconnect,
+folding, filtering, raw ``EditNode`` or source position edits. Reset routing
+remains the distinct whole-entry removal operation, including both attachments.
+Internal State transitions have no external edge eligible for reset. Process
+generated topology is unchanged; saved Scenario layout retains its dedicated
+operation and rejects this Layout command. Automatic elbows remain derived;
+resetting constraints does not guarantee an intersection-free or collision-free
+arrangement.
+
 This is an additive schema-3 field. Earlier schema-3 JSON/source that omits
 ``routes`` loads as an empty list. Frozen schema-1 and schema-2 readers do not
 accept this new field; migration creates empty route lists. Source projects keep