# Capella direct-manipulation gap review — 2026-09-11

Codex-956atf `/root/capella_process_gap`. Advisory source review under [root's issue 2 scope](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/2#issuecomment-419); no design ratification or runtime acceptance.

Reviewed Studio commit **638d06c4e33a1f54203b234d0b49c3ecf551d27d**, its actual desktop/core sources, the [prior native Capella benchmark](release-capella-scenario-benchmark-20260910.md), [canvas design](release-unified-behavior-canvas-design-20260911.md), and the isolated [R123 source handoff](http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/src/commit/fb1da912c9951f33feed2fad9ad689bc46cd20d0/harness/release-behavior-canvas-r123-source-20260911.md). Root is integrating changes while this report is written; Studio anchors below deliberately identify the published baseline. The R123 contribution changes presentation/input admission, not the persistent/domain contracts discussed here.

Actual Gitea default branch is `main`; its AGENTS was retrieved through MCP. Issues 1/2 confirm root's integration ownership and peers' B4/lifecycle/header and staged-source/navigation ownership. This review changed only this report, with no compiler, tests, native apps, Git/index changes, Wiki changes, Linux/WSL or VPN actions. Primary Capella source was read at **5537297b071fff809285bc63989f5067d675bc52**. It is a source snapshot, not a claim that the installed Capella 7.1 binary behaves identically.

## New evidence and distinctions

The prior benchmark established point-created activity lifelines and an empty dragged LOOP. It did not establish wrapping existing messages or transferring operands. Source inspection now adds these distinctions:

| Concept | Source-backed fact | Consequence for Studio |
| --- | --- | --- |
| Layout versus a domain edit | Capella exposes layout mode specifically to suppress operations that could change the semantic model, alongside automatic arrangement and pinning. [Diagram Editor][C1] | Preserve the engineer's ability to arrange a drawing confidently. A process node crossing another box or rank must not silently change precedence, decomposition, allocation or ownership. |
| Definition, use and responsibility | Capella's process/chain documentation distinguishes work involvements, involvement links and references to other chains. Allocation of activities to entities/actors and functions to system/actors/components is a separate relationship; the metamodel separately contains child functions. [Chains][C2], [Contextual allocations][C3], [FunctionalAnalysis.ecore][C4] | Four distinct operations exist: arrange a local use; move a definition under a same-kind definition; allocate work to a performer; move a local occurrence between behavioral owners. Nesting must advertise which operation it represents. A process use does not own the referenced activity/function definition. |
| Lane identity and order | Capella InstanceRole represents an instance. Its horizontal reorder handler moves entries in the scenario's `ownedInstanceRoles` list. It does not substitute represented identities. [Interaction.ecore][C5], [DoIRReorderExternalAction][C6] | Persisted view-owned x positions would be a deliberate Studio design choice. Do not call Capella's lane order wholly external to its model. In Studio, lane arrangement can remain behavior-neutral while being fully represented in source/REST. |
| Sequence order and operands | Capella's reorder service updates ordered interaction fragments and message ordering. Its scenario owns interaction fragments; CombinedFragment references operands and carries an operator, while covered lifelines are explicit references. [SequenceDiagramServices][C7], [Interaction.ecore][C5] | Studio's physically nested Fragment → Branch → Occurrence tree is a different representation. Implement Studio transfers against its own parent/list invariants; copying Capella's reorder calls would not be sufficient. A wider Studio frame cannot truthfully assert stored coverage that Studio does not have. |
| Function/activity edge endpoints | Capella involvement links point to specific function involvements, separately from the exchange they involve; sequence links have a different endpoint type. [FunctionalAnalysis.ecore][C4] | An exchange between work uses, a precedence arrow, a global work exchange, and a scenario message are distinct identities and edits. Repeated uses of one definition make this distinction observable. |

The inspected Capella source establishes model/handler behavior, not the usability of every drag path. In particular, no new native claim is made for cross-operand drag or range wrapping.

## Five representative engineering workflows

Run each applicable workflow in OA and SA. The engineering tasks below extend the existing design's falsifiers rather than reopening historical bugs.

| Workflow and intended result | Current observed capability | Remaining gap / boundary |
| --- | --- | --- |
| **1. Prepare a process/chain for a design review.** Place two work uses and a control node around a long alternate route; move one use across the computed rank; save, close, reopen and continue connecting it. | The graph is derived from sequence links/legacy order and fixed rank columns. Creation and guarded connect/reconnect exist. Drag reorder rejects a different column and produces `SetSteps`. [Graph][S1], [process gesture planners][S2] | Authored world placement is absent from this graph's input. Camera improvements do not preserve moved nodes. Movement must write presentation while leaving occurrence parents, ordered steps, guards and links unchanged. Existing layouts without stored positions still need a deterministic usable view. |
| **2. Explain who performs the work.** Show “Receive request” inside an operational entity or the system in an allocation view; separately show its subactivities/subfunctions; show two local uses in a process. | Core already distinguishes parent containment, allocation and represented Action use. Parent admission permits Activity → Activity and Function → Function, while scenario lifelines belong to scenarios. [parent rules][S3], [occurrence model][S4] | This is not evidence of missing allocation semantics. The direct-manipulation requirement is truthful nesting and a clear destination preview: “Arrange use”, “Allocate work” or “Move definition under …”. Dropping a process use over another use must not infer either allocation or decomposition. Full OA/SA acceptance still requires the architecture workflows; this report does not assess their current native usability. |
| **3. Put participants in the engineer's preferred order.** Place two scenario lifelines, name them for their roles, place two different lifelines representing the same work where admitted, and arrange the headers to minimize crossings. | Lifelines have separate IDs/represented references. Scene creation collects child lifelines and assigns uniformly spaced x positions; `Project::children` filters the element BTreeMap's ID order. [lane projection][S5], [children order][S6] | No authored lane order/spacing is consumed or persisted. Storage order should not dictate the only arrangement. Lane drag must retain each lifeline ID, its represented identity, every message endpoint and reuse binding. Changing x is not transferring an action to another lifeline. |
| **4. Refine a response sequence into alternatives.** Wrap a contiguous call/reply group in LOOP, add an alternate operand, move an entire nested fragment within its sequence, then deliberately move a selected sibling range to the other operand. | Clicked root/operand creation and same-parent reorder exist. The reorder planner explicitly rejects a different parent. Core already provides atomic `Batch`, `Reparent` and `SetSteps`, with branch ownership validation. [scenario planner][S7], [command primitives][S8], [branch validation][S9] | There is no range-wrap or explicit operand-transfer event/planner in this inspected canvas contract. This is an authoring gap over existing primitives, not proof that source/API cannot express it. Transfer must update parents and both ordered lists atomically, preserve moved UUIDs, and revalidate call/reply dominance, lifetime and reuse constraints. Copy/delete reconstruction would damage identity. |
| **5. Repair the exact communication use.** In a process, draw an existing OA interaction/SA functional exchange between two chosen work uses. In a scenario, reconnect a message to a compatible lifeline, keeping its values and call correlation. Open the underlying exchange only when changing its definition is intended. | Process direct reconnect edits only a SequenceLink. Exchange creation can produce an exchange contribution card. Crucially, `ContextualLinkPurpose::Exchange` already connects exact local or qualified Action addresses to a matching exchange, and its form creates/edits that relation. It is rendered as assembly incidence. [process planners][S2], [contextual planner][S10], [core endpoint validation][S11] | Do not report that work-to-work exchange edges are unrepresentable. The gap is a direct typed exchange/assembly gesture and endpoint manipulation using that existing contract. The scenario event enum has creation/reorder but no endpoint reconnect event. [scenario event contract][S12] Changing an occurrence endpoint must not silently edit the shared exchange or its correlated reply. |

For workflow 5, SA functional exchange definitions retain both work endpoints and functional port identities; OA interactions use activity endpoints. Participant lifelines resolve through compatible work allocation/roles rather than being interchangeable with function ports. Studio already encodes these distinctions in [the exchange body][S13] and [representation compatibility][S14]. A valid destination preview must use those validators, not merely node kind or screen proximity.

## Candidate approaches and smallest coherent next slice

Criteria follow the user's goal: predictable direct editing, low cognitive load, saved graphical/textual equivalence, exact identity/history, and maintainability.

| Candidate | Benefit | Material cost / rejection reason |
| --- | --- | --- |
| Keep rank/ID-derived arrangement; add more toolbar controls | Smallest implementation | Fails workflows 1 and 3: the chosen placement cannot be saved. Phase 1 is useful infrastructure, not this outcome. |
| Treat all dragging as semantic reorder/reparent | Reuses existing sequence commands | Wrong for a review layout; turns visual intention into behavioral edits. Also cannot express independent process x/y and lane spacing. Reject. |
| Desktop-only placement maps | Fast visible improvement | Loses source/REST parity and reliable reopen/history; two editing representations disagree. Reject. |
| **Owner-bound persisted behavior views** | Saves authored process placement and lane arrangement without changing behavioral order | Requires a reviewed core/source/API layout contract and integration with the in-flight schema work. Recommended. |

**Recommended next slice: make workflows 1 and 3 durable together.** Add an explicitly owner-bound process/chain view and scenario view, reuse the shared camera/admission shell, and provide whole-body process movement plus horizontal lifeline-header placement/movement. Persist only meaningful fields: process occurrence position/size, and scenario lane x/width or a defined lane-order/spacing representation. Do not introduce arbitrary scenario y coordinates in this slice.

The existing `Diagram`/`NodePlacement` machinery is a plausible home, but current [ProjectionKind][S15] lacks a process/scenario owner projection. Adding discriminated owner projections versus a specialized behavior-layout record requires core-owner review; this report does not choose a schema number or claim that every generic placement field has a valid scenario meaning. The contract must specify scope, identity, serialization, validation, delete/reidentify handling, and source/API construction. Multiple saved views must be able to arrange the same owner independently.

For an owner without an authored view, display a deterministic derived scene immediately. Merely opening, inspecting, panning or fitting stays clean. Materialize the view with the first accepted placement edit in one history entry. Automatic fallback handles newly added/unplaced uses; an explicit Auto arrange may replace hand placement as one undoable edit. Adding a semantic edge must not silently rearrange previously placed objects.

Repeated process references remain qualified by caller/reference path; start with moving the local reference block. A nested read-only preview must not become a placement keyed only by the shared definition UUID. Show the exact local occurrence identity in selection/details.

After that slice, workflow 4 is a bounded domain continuation using existing commands, and workflow 5 a typed endpoint continuation using existing contextual/communication validation. If the core layout contract cannot proceed immediately because of shared schema ownership, designing the atomic wrap/transfer planner is useful non-overlapping work; do not substitute a temporary persisted format. Additional Capella fragment operators/coverage semantics remain a separate capability assessment, not silently excluded from the full goal by this four-operator UI.

## Concrete acceptance and counterexamples

These are proposed gates, **not executed results**. Check whole accepted Project plus exact source/history, not only one position field. Exercise actual pointer/keyboard workflows at 1100×700 client and a larger window; readback assertions and screenshots alone do not establish editing usability.

| Case | Positive acceptance | Negative / invariant |
| --- | --- | --- |
| Process authored placement | Move a work-use body across at least two former rank columns, connect it, save/reopen, and observe the authored position. One release creates one layout history entry; Undo/Redo restores complete before/after states. | No step reorder, link/guard/parent/allocation change, implicit legacy-path conversion or shared-definition edit. A click below drag threshold adds no history. |
| View scope and identity | Arrange two saved views of the same owner differently; move two distinct references to the same process independently. Add a new contribution without displacing existing authored positions. | Wrong-owner/layer placements, duplicate placement identities, invalid dimensions/nonfinite coordinates, or bare nested-definition targets are rejected without partial writes. |
| Lane arrangement | Place a new lifeline at a previewed x; move its header past another lane; save/reopen. Same represented target on two lifelines retains two independently arranged lifeline identities where the scenario admits it. | Message senders/receivers, Action/State lifelines, branch steps, representations and ScenarioUse bindings remain identical. Alias/name edits must not reset authored arrangement. |
| Clean/invalid/stale operations | Open a legacy file and pan/Fit without source change. Cancel placement or encounter source-write failure while preserving the accepted model and usable retry state. | Release retained across owner/document/revision/view change, pending source draft or invalidated input lifetime commits nothing. Schema/source/API load/save preserve the same layout; invalid incoming layout is not silently discarded. |
| Wrapping/transfer continuation | Wrapping sibling IDs `[b,c]` within `[a,b,c,d]` yields `[a,fragment,d]`; its operand owns the original b/c IDs in order. Explicit transfer updates both lists/parents in one Batch, and moving a fragment carries its full subtree. | Refuse a partial child fragment, cross-parent range, ancestor into descendant, stale destination, or reply-before-call/branch/lifetime-invalid result. Ordinary drag crossing an operand does not silently transfer. All unrelated siblings, conditions, values and correlations remain identical. |
| Endpoint continuation | Drawing assembly from exact Action A to Action B offers matching exchanges; repeated definitions retain the chosen occurrence addresses. A compatible scenario endpoint edit preserves occurrence ID and all untouched payload fields. | Incompatible work/port/layer/represented participant, wrong message direction or broken call/reply correlation leaves the original intact with an actionable explanation. An assembly edit never creates a precedence relation, and occurrence repair never changes the global exchange implicitly. |

The release remains subject to the full [PROJECT_GOAL](../PROJECT_GOAL.md): OA/SA capability coverage, transitions, source/API parity, guidance, realistic failure recovery, platform verification and independent integrated acceptance. This report identifies the next useful slice and its semantic boundaries; it does not close issue 2 or ratify the whole product.

[C1]: https://github.com/eclipse-capella/capella/blob/5537297b071fff809285bc63989f5067d675bc52/doc/plugins/org.polarsys.capella.ui.doc/html/04.%20User%20Interface/4.05.%20Diagram%20Editor.mediawiki#L84-L105
[C2]: https://github.com/eclipse-capella/capella/blob/5537297b071fff809285bc63989f5067d675bc52/doc/plugins/org.polarsys.capella.ui.doc/html/05.%20Diagram%20Management/5.5.%20Creation%20of%20Functional%20Chains%20and%20Physical%20Paths.mediawiki
[C3]: https://github.com/eclipse-capella/capella/blob/5537297b071fff809285bc63989f5067d675bc52/doc/plugins/org.polarsys.capella.ui.doc/html/07.%20Modelling%20Wizards%20and%20Accelerators/7.2.%20Contextual%20Allocations.mediawiki#L10-L34
[C4]: https://github.com/eclipse-capella/capella/blob/5537297b071fff809285bc63989f5067d675bc52/m2/plugins/org.polarsys.capella.core.data.def/model/FunctionalAnalysis.ecore#L3381-L3469
[C5]: https://github.com/eclipse-capella/capella/blob/5537297b071fff809285bc63989f5067d675bc52/m2/plugins/org.polarsys.capella.core.data.def/model/Interaction.ecore
[C6]: https://github.com/eclipse-capella/capella/blob/5537297b071fff809285bc63989f5067d675bc52/core/plugins/org.polarsys.capella.core.sirius.analysis/src/org/polarsys/capella/core/sirius/analysis/actions/extensions/DoIRReorderExternalAction.java#L30-L54
[C7]: https://github.com/eclipse-capella/capella/blob/5537297b071fff809285bc63989f5067d675bc52/core/plugins/org.polarsys.capella.core.sirius.analysis/src/org/polarsys/capella/core/sirius/analysis/SequenceDiagramServices.java#L163-L291
[S1]: http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/src/commit/638d06c4e33a1f54203b234d0b49c3ecf551d27d/crates/oa-desktop/src/behavior/topology.rs#L988
[S2]: http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/src/commit/638d06c4e33a1f54203b234d0b49c3ecf551d27d/crates/oa-desktop/src/behavior/topology/direct.rs#L340
[S3]: http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/src/commit/638d06c4e33a1f54203b234d0b49c3ecf551d27d/crates/oa-core/src/validation.rs#L92
[S4]: http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/src/commit/638d06c4e33a1f54203b234d0b49c3ecf551d27d/crates/oa-core/src/model.rs#L550
[S5]: http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/src/commit/638d06c4e33a1f54203b234d0b49c3ecf551d27d/crates/oa-desktop/src/behavior.rs#L1304
[S6]: http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/src/commit/638d06c4e33a1f54203b234d0b49c3ecf551d27d/crates/oa-core/src/model.rs#L1828
[S7]: http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/src/commit/638d06c4e33a1f54203b234d0b49c3ecf551d27d/crates/oa-desktop/src/behavior/scenario.rs#L1067
[S8]: http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/src/commit/638d06c4e33a1f54203b234d0b49c3ecf551d27d/crates/oa-core/src/session.rs#L583
[S9]: http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/src/commit/638d06c4e33a1f54203b234d0b49c3ecf551d27d/crates/oa-core/src/validation.rs#L2284
[S10]: http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/src/commit/638d06c4e33a1f54203b234d0b49c3ecf551d27d/crates/oa-desktop/src/behavior/topology/contextual.rs#L149
[S11]: http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/src/commit/638d06c4e33a1f54203b234d0b49c3ecf551d27d/crates/oa-core/src/topology_context.rs#L269
[S12]: http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/src/commit/638d06c4e33a1f54203b234d0b49c3ecf551d27d/crates/oa-desktop/src/behavior/scenario.rs#L98
[S13]: http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/src/commit/638d06c4e33a1f54203b234d0b49c3ecf551d27d/crates/oa-core/src/model.rs#L1117
[S14]: http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/src/commit/638d06c4e33a1f54203b234d0b49c3ecf551d27d/crates/oa-core/src/validation.rs#L1284
[S15]: http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/src/commit/638d06c4e33a1f54203b234d0b49c3ecf551d27d/crates/oa-core/src/model.rs#L1431