# OA communication means — independent design critique

Read-only production review, 2026-09-06. Recommendation: add a first-class
`CommunicationMean` relation over OA Entity/Actor endpoints and reuse the existing
`ExchangeAllocation` relation. Do not widen the meaning of existing boundary-port
records silently. Root retains the contract decision; no production edits made.

## Primary evidence

Capella's [OperationalAnalysis.ecore](https://raw.githubusercontent.com/eclipse-capella/capella/master/m2/plugins/org.polarsys.capella.core.data.def/model/OperationalAnalysis.ecore)
defines CommunicationMean as a specialization of ComponentExchange and exposes
sourceEntity/targetEntity as direct aliases of its endpoints (lines 1597–1632).
Entity includes actors in its documented operational meaning. The inherited
[FunctionalAnalysis.ecore](https://raw.githubusercontent.com/eclipse-capella/capella/master/m2/plugins/org.polarsys.capella.core.data.def/model/FunctionalAnalysis.ecore)
defines optional orientation, default false, and allocation of functional
exchanges (lines 2522–2545). ComponentExchange also participates in the event/
operation abstraction. These establish a useful shared exchange family, not a
requirement to force operational entities through SA typed ports.

## Why the smaller-looking BoundaryExchange change is risky

Current `RelationKind::permits` requires Port→Port. `ports::validate_relation`
checks participant ownership through each endpoint's parent, Legacy/Standard/Flow
contracts and carried interfaces. `validate_relation_context` rejects endpoints
with equal parents: applied directly to nested OA sibling entities it would reject
valid communication. `ports::validate_exchange_allocation` again treats endpoint
parents as performers and classifies Interaction allocation as legacy. Its legacy
branch warns OA users to introduce typed ports they cannot create, and checks only
the forward pairing even for an unoriented boundary.

Projection identifies BoundaryExchange endpoints as ports; endpoint picking,
reconnection, connection creation, interface checks and scenario participant
resolution all contain related assumptions. Changing only `permits` yields an
inconsistent product. A proper tagged endpoint sum could represent both semantics,
but it requires migrating every BoundaryExchange and all these consumers. A new
relation variant exposes each required exhaustive integration explicitly while
leaving old records, identities and authored source intact.

## Small explicit contract to freeze

- `CommunicationMean { source, target, oriented, items }`; distinct same-layer OA
  Entity or Actor endpoints, optional carried OA ExchangeItems, no child ports.
  Initial `oriented=false` follows the primary model; users can choose direction.
  Multiple named means between the same pair remain valid engineering alternatives.
- `ExchangeAllocation { source: mean, target: interaction }` is relation-to-relation
  allocation. Do not duplicate allocated-interaction IDs inside the mean. Preserve
  old BoundaryExchange→Interaction and BoundaryExchange→FunctionalExchange records.
- Match actual direct Activity Allocation owners. Missing/ambiguous allocation is
  an actionable incomplete-allocation warning; a known contradictory owner is an
  error. Role realization alone does not silently establish an actual allocation.
  For unoriented means consider both complete pairings; when one owner is unknown,
  the other known owner must still belong to at least one admissible pairing.
- The mean carries every allocated Interaction item, using existing item-type
  satisfaction rules. Editing either item list revalidates its allocations
  atomically. Means may be created before their Interactions; incomplete work must
  remain possible without inventing responsibilities or allocating parents.
- ParticipantInteraction scenarios may reference means; OperationalActivity
  scenarios/process exchange contributions continue to reference Interactions.
  An unoriented ordinary message resolves direction from explicit sender/receiver
  lifelines. A correlated same-mean Reply reverses the actual Call binding, including
  a reverse Call on an unoriented mean. Keep the existing operation-response
  convention rather than invent simplex hardware constraints from `oriented`.
  This direction convention is a Studio decision to specify, not established by
  the primary schema's orientation sentence alone.

## Compatibility and transition traps

`transitions::mapped_relation` currently clones BoundaryExchange into the other
layer. Direct OA participant endpoints mapped to SA participants are not component
ports. Two OA entities may also map to one System: their operational communication
need not become an external boundary exchange. Never auto-generate SA ports or
self-boundaries from that fact. A bounded first implementation should explicitly
report an unsupported/omitted counterpart until a user chooses the corresponding
SA boundary and its ports; preserve the OA mean and any existing manual trace.

Schema 5 is current. `migration_v4::Project4` embeds live Relation/Diagram types;
adding a live variant can accidentally make a schema-4 envelope accept a new
construct. Freeze a deliberate version policy and add negative old-version
source/JSON admission tests. Do not rewrite frozen migration fixtures or reinterpret
legacy ports as entities. An explicit future conversion must account for port-level
artifacts, interface roles, diagrams and endpoint references before removal.

Generic reference traversal must visit items; endpoint visitors alone are
insufficient. Deleting a mean removes its allocations, routes, trace links and
dependent occurrences, while preserving their Interaction definitions and
cross-layer counterparts. Deleting/reparenting an actual work allocation must
revalidate the new OA allocation contract without accidentally invoking the SA
port-allocation cascade.

## Required user journey and falsification tests

Start empty: place two OA entities/actors; create allocated activities and an
Interaction; draw/name a Communication means edge between participant cards;
select carried items and allocate existing Interactions using a filtered picker.
The inspector exposes both communication and activity layers with direct navigation.
Render the mean on participant boundaries, keep work allocation nested, and show
allocated Interactions as selectable rows rather than extra allocation arrows.
Endpoint reconnect preserves UUID/alias/prose/items/routes/artifact owners and
retains rejected edits. No OA Port form should appear in this journey.

Acceptance must falsify: mixed-layer/Role/Port/Activity endpoints; same endpoint;
wrong/unknown/role-only performer; forward/reverse/unoriented and partial-owner
allocation; missing carried items and later item changes; multiple means per pair;
reverse unoriented Call and correctly correlated Reply; forbidden process/viewpoint
use; folded containers and missing placements; sibling nested entities; exact
reconnect/undo/redo; remap/delete/reparent; no automatic SA boundary after participant
collapse. Source+JSON+REST must agree, reject atomically, and retain identity and
comments through reidentify, include movement and server restart. A standalone OA
mean plus later allocation must be usable without SA or LA/PA work.