110 lines
7.2 KiB
Markdown
110 lines
7.2 KiB
Markdown
# 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.
|