ARCADIA-Studio/harness/scenario-group-reorder-policy-20260924.md

Scenario group reorder policy

Derived from issue 29 and the multiple-selection contract. Accepted design for the next Scenario adapter; this document alone establishes no implementation, native, integration or release acceptance. The original decision inspected 495464e84b5bae8ddad93e9fc69ef353e7f1c884; the post-prerelease port additionally inspects the combined base 897d9f049406d5be597543eb0a6755b796259302 and preserves its saved Scenario presentation model.

Operation and identity

This semantic reorder operation moves the exact selected local occurrences as one stable block inside their common immediate Scenario or Branch parent. It does not edit free XY positions, migrate operands, change a referenced definition or automatically select dependencies. Saved-view body drags already adjust presentation spacing; this policy does not redefine their default meaning.

Saved Scenario layouts are separate presentation records. Semantic reorder preserves all authored lane/message coordinates, metadata and other views exactly, even when the changed order requires derived presentation to accommodate those preferences. Saved group presentation movement is now separately implemented on this branch; semantic reorder must not reinterpret stored coordinates as sequence order or replace that default body/header drag. App admission must distinguish the active saved/derived representation and its visit lifetime, including a same-owner representation round trip.

Eligible bodies are Exchange (including lifecycle and timer messages), Action, State, ScenarioUse and Fragment. A Fragment moves as one occurrence; its branches and descendant lists remain unchanged. Lifelines, Branch headers, Process-only occurrence bodies and other typed targets are unsupported movement members. Cross-parent sets and a Fragment plus one of its descendants refuse as a whole. These objects may still be selected and inspected; selection is not movement permission.

Every original target must exist, have its actual eligible body, belong to the same immediate parent and occur exactly once in that parent's list. Check the entire edited list, including unselected entries, for duplicate/missing IDs, body and parent mismatches. The selected parent must be reachable from the active Scenario through the actual sequence lists and Fragment branch lists. An ancestor pointer alone cannot authorize a hidden Branch omitted from its Fragment. The App must also admit against exact current rendered visibility.

An unlisted child is a supported warning-only authoring state: leave it unlisted and unchanged. Integrity of the edited list does not require every parented element to appear in it. Missing optional reference/binding information or loop warnings must not become blanket movement errors. The existing full-project error validator remains authoritative.

Stable-block transformation

Let S be the original parent list and T the exact selected set. Form B by retaining members of T in their order in S; form R from the other members. The destination is an exact Slot { parent, before }.

1. Complete typed/list/reachability admission and validate the unchanged baseline before any no-op result.
2. Require the destination's same parent and an existing exact anchor, or append.
3. If the anchor is selected, leave S exactly unchanged. Do not normalize to a neighboring row or compact a noncontiguous selection.
4. Otherwise insert all of B before the anchor in R, or append. Exact unchanged order is a no-op.
5. Validate the complete executed candidate. On success use one SetSteps transaction; on error change nothing.

For S=[A,B,C,D], selecting C then A and dropping before D produces [B,A,C,D], regardless of primary or pressed member. Dropping that same set before C leaves [A,B,C,D]. Selecting [Call,Reply] preserves that internal order; it never implicitly selects another reply or expands a referenced Scenario.

Full candidate validation includes unselected descendants. Moving a Fragment ahead of an external Call can invalidate a nested Reply; moving an occurrence with local lifeline use before Create or after a possibly coexecuting Delete must be refused. ALT exclusivity and PAR coexecution cannot be inferred from painted row order. Opaque ScenarioUse bindings remain local lifetime uses under the existing validator, without interprocedural expansion.

Gesture and transaction requirements

Capture immutable model and exact selection identity before movement. Cache proposals by distinct Slot, not pointer pixels. Before release, verify document, surface, revision, epoch, selection generation and complete membership; refuse a stale set before reconciliation can prune it. Recompute against the same accepted snapshot and execute once through Document. Successful source updates, Undo and Redo each remain one transaction. Refusal and no-op preserve model, source, history branch, selection and primary.

Use the nearest displayed slot, then apply parent admission. A farther legal slot must not replace a nearer invalid operand destination. Feedback identifies the selected count, destination/parent and refusal or no-change reason. A Fragment's interior can contain invalid operand slots even when a header anchor would be a no-op. Pointer/camera/focus lifetime, real selection modifiers and native readability need separate adapter verification; a passing pure planner does not establish them.

This nearest-slot rule governs a geometric drag input, not a direct semantic destination chooser. An explicit chooser may offer exact before-anchor/end identities from the named common immediate parent, including selected anchors as no-change choices. It must retain the entire original selected set and expose temporal refusal instead of silently skipping invalid same-parent candidates. The destination experiment proves that valid saved slots can have identical Y, making one identity unreachable through unmodified nearest-Y input. That picker alone is therefore rejected as a complete group reorder interaction. An exact semantic chooser, order strip or explicit tie disambiguator must provide the missing reachability; this negative decision does not accept a particular UI.

Alternatives and acceptance

Contiguous-only selection rejects useful sibling groups without simplifying nested temporal validation. Stable semantic ordering is therefore preferred. Parent/child normalization silently drops selected intent, while automatic call/reply expansion has no unique closure in the presence of alternative replies, loops and nested fragments. Strict refusal keeps this first increment precise. Revisit these decisions only with an explicit user workflow and a compatible whole-set specification.

Discriminating evaluators include literal whole-Project transformations at root and operand levels, noncontiguous order versus click order, selected-anchor/unchanged no-op with existing redo, malformed unselected entries, omitted Branch reachability, warning-only unlisted children, nested reply/lifetime failures and legal nested-fragment movement. Successful cases must preserve every other sequence, binding, relation, value, ID and metadata record. Use independent source round trips and one-step Document history, not preview/commit agreement alone.

Aggregate removal remains separate required work. Until it exists, an interface displaying a group must refuse legacy primary-only Remove/Delete/reorder actions. Live ownership and progress remain in issue 29.

Adapter decision boundary after combined-source review

Use the existing shared Selection/Snapshot with a full Scenario Context envelope. Map a derived representation to Surface::Scenario(owner) and a saved representation to Surface::Saved(diagram). Representation navigation clears the group; the envelope additionally admits document, owner, representation, visit, revision and epoch, including A-to-B-to-A visits. Exact visibility comes from the actual presented scene. This choice preserves existing selection semantics without adding Scenario-specific fields to every generic adapter.

At this historical review boundary, the saved-view gesture remained open. The initial adapter mapping proposed a one-shot arm; the independent critique identified a simpler group handle and an operation-local order preview worth comparing first. Authored coordinates may remain visually unchanged after semantic reorder, so an arm label alone cannot establish observable success. The later destination experiment and implemented chooser decision below supersede that open choice for this increment; the earlier alternatives remain historical evidence. Preserve the active saved representation and captured group during preview; do not transfer selection across representation navigation.

Before enabling group input, specify a consumed gesture identity (or prove equivalent epoch retirement) so canceled, completed/no-op and duplicate packets cannot affect a newer gesture on the same unchanged selection. Match captured selection identity on spacing packets too; group-size checks alone miss selection ABA. If returning to the original press position promises no change, define that screen-space rule separately from nearest-slot selection; the nearest slot need not be the pressed occurrence's anchor. Close raw Details arrows, menus and singleton removal/reorder paths before they can apply to only the primary of a visible group.

The planner's verification record establishes the bounded semantic foundation. It does not accept any of these future UI choices or claim group gestures are implemented.

Implemented successor: explicit semantic destination chooser

The App implementation and Windows evidence at 1c4099a9ef76dd28d17ef892e95edf89e860569f promotes the shared frozen session into production input. The header Reorder control offers exact same-parent before-anchor/end identities with search, paging, and a before/after semantic-order preview. This is the selected bounded implementation following the tied-Y counterexample; no one-shot arm or nearest-Y-only group drag is enabled. Ordinary Saved body/header spacing retains its meaning. Future graphical access must preserve exact identity reachability and the same whole-set semantics.

Begin retires captured input before acquiring the new full Context/Snapshot/token. Every proposal retains the requested representation, complete selection and primary. Apply/Finish captures the exact displayed Slot; queued Apply for another preview is inert. No default destination exists. Enter previews a unique match; nonrepeated Ctrl+Enter applies an eligible displayed proposal after child-overlay precedence; Escape cancels. Stale token-specific focus tasks cannot disturb newer focus. The current Slot alone is cached, bounding retained scene memory.

Baseline Fallback admits semantic choice only when every selected target is visible. Candidate Fallback may commit after an explicit adjacent warning, retaining the requested Saved view and all authored layout records. Candidate Unavailable or loss of any selected rendered target blocks commit. These are explicit App policies, not implicit permissions from semantic validation. The completed result shows actual semantic order with full aliases; its lifetime tolerates camera/diagnostic input-epoch changes but remains bound to document/revision/view/visit and exact selection generation. Subsequent spacing commits retire that explanation.

Scenario tests, formatting, strict lint and build pass at this source with exact 818-input source proofs. Windows native run 2 exercises tied/distant identity destinations, ordinary/compact preview readability, cancellation/no-op Redo retention, semantic result feedback and keyboard entry; fresh-process run 3 verifies exact saved-source reopen. Native selection used contextual Add, not demonstrated Shift-click; F6 followed by six reverse Tab steps is reachable but remains a discoverability limitation. Real App source-write failure remains a runtime coverage gap. These scoped results do not claim default-branch integration, a new release, aggregate removal or full issue-29 completion. The linked report retains failed attempts and evidence boundaries.