285 lines
20 KiB
Markdown
285 lines
20 KiB
Markdown
# OA communication means — bounded contract decision, 2026-09-06
|
||
|
||
Status: proposed for root synthesis. Production was read only. Investigation uses
|
||
HEAD c091f80 plus current integrated changes. No implementation, tests or native
|
||
acceptance are claimed. This closes the representation question raised by
|
||
release-current-coverage-20260906.md, not the feature itself.
|
||
|
||
## Recommendation and evidence
|
||
|
||
Add a first-class `CommunicationMean { source, target, oriented, items }` relation
|
||
between OA participants, retaining existing identified `ExchangeAllocation`
|
||
relations to its allocated `Interaction`s. Keep `BoundaryExchange`'s port endpoint
|
||
contract intact. Share exchange-item/allocation helpers where their semantics
|
||
agree, and use a dedicated OA validation branch where participant endpoints differ.
|
||
|
||
The official Arcadia activities reference describes operational Interactions
|
||
between activities and their allocation to communication means between
|
||
stakeholders. It also connects stakeholder scenarios to these exchanges. This
|
||
establishes the engineering need independently of a Capella UI convenience.
|
||
[Arcadia reference, activities 5.1.1.2.4–8, PDF page 21](https://www.eclipse.org/capella/resources/arcadia-reference/Arcadia%20Reference%20-%20Activities.pdf).
|
||
|
||
Capella's OA schema makes CommunicationMean a named relation specializing
|
||
ComponentExchange and gives it direct sourceEntity/targetEntity aliases. Its
|
||
inherited exchange contract includes orientation (default false) and allocations
|
||
to functional exchanges. These are conceptual evidence, not a requirement to copy
|
||
the whole EMF inheritance structure. [OperationalAnalysis schema](https://raw.githubusercontent.com/eclipse-capella/capella/master/m2/plugins/org.polarsys.capella.core.data.def/model/OperationalAnalysis.ecore),
|
||
[FunctionalAnalysis schema, ComponentExchange](https://raw.githubusercontent.com/eclipse-capella/capella/master/m2/plugins/org.polarsys.capella.core.data.def/model/FunctionalAnalysis.ecore).
|
||
The installed Capella benchmark also observed an OAB communication-means tool;
|
||
see release-capella-workflow-benchmark.md.
|
||
|
||
## Current facts that constrain the decision
|
||
|
||
- `BoundaryExchange` has port source/target, orientation and items.
|
||
`RelationKind::permits` accepts Port→Port; `ports.rs` uses each endpoint's
|
||
semantic parent as its participant. `projection.rs` treats these endpoint IDs
|
||
as ports, and validation rejects same participant-owner connections.
|
||
- OA ports admit only `Legacy`, which ordinary creation does not offer.
|
||
`app.rs::add_element` redirects all Port creation to SA typed port actions.
|
||
Thus new OA entity communication has no ordinary authoring path.
|
||
- Core `ExchangeAllocation` already accepts BoundaryExchange→Interaction in OA
|
||
(the language.rst table's SA-only statement is inaccurate). Its legacy branch
|
||
checks actual work Allocation, checks carried items, and emits a typed-port
|
||
resolution warning. That warning is inappropriate as guidance for OA.
|
||
- `ports.rs::actual_performer` uses an actual Allocation. Broader
|
||
`validation::effective_performer` can resolve role-based responsibility; those
|
||
functions must not be casually interchanged in a transport-allocation check.
|
||
- ParticipantInteraction scenarios permit Interaction and BoundaryExchange today.
|
||
`message_endpoints` mostly returns the stored relation tuple, with the tuple
|
||
reversed for a same-exchange Reply. It does not handle ordinary reverse messages
|
||
on an unoriented declaration.
|
||
- `transitions.rs::mapped_relation` clones BoundaryExchange, while
|
||
`sa_port_omissions` omits typed SA ports and dependent boundary relations on the
|
||
reverse transition. Merely adding another enum arm cannot provide a valid
|
||
bidirectional communication transition.
|
||
- `migration_v4::Project4` shares current `Relation` rather than freezing its
|
||
constructor set. Adding a live enum variant without old-version admission
|
||
checks would accidentally admit the new meaning under schema4.
|
||
|
||
## Alternatives compared
|
||
|
||
| Criterion | A. New CommunicationMean relation | B. BoundaryExchange with direct OA endpoints | C. First-class OA port contract |
|
||
|---|---|---|---|
|
||
| Engineering meaning | Constructor explicitly means OA participant communication | Same tag means participant→participant in OA and port→port otherwise; readers must inspect referenced records | Adds named OA endpoint objects beyond the established participant relation need |
|
||
| Existing source/API behavior | Additive tagged variant; old boundary shape/meaning stays fixed | Shape unchanged but endpoint semantics broaden; old tools cannot distinguish it from a malformed boundary | New port constructor and new endpoint workflow, plus existing boundary semantics |
|
||
| Allocation | Dedicated OA branch reuses ExchangeAllocation IDs and item validation | Allocation must branch on layer and endpoint kind before every owner/Legacy check | Reuses port parents, but needs new ownership/interface/direction rules |
|
||
| UI and nesting | Draw entity→entity; no extra boxes or hidden semantic records | Same visual result, but labels/tools/inspectors need contextual relabeling everywhere | Users create ports before communicating, or UI invents extra identities |
|
||
| Traceability | Independent means identity owns artifacts; explicit typed boundary counterpart | Existing relation tag is reusable, but actual counterpart conversion still changes endpoint families | OA port→SA port mapping appears tempting and can falsely imply technical design equivalence |
|
||
| Migration | Old data preserved; optional reviewed conversion is explicit | Old relation remains valid, but its constructor no longer identifies one endpoint family | Existing Legacy cannot be silently promoted; interface/direction meaning still needs review |
|
||
| Maintainability | More exhaustive matches initially; compiler exposes missing integration seams | Fewer enum edits but more hidden assumptions in port/scenario/projection/transition code | Largest permanent semantic surface and authoring burden |
|
||
|
||
A wins because it makes a real semantic distinction explicit without inventing
|
||
OA port design. B is viable only with a shared tagged endpoint abstraction used
|
||
throughout projection, validation, scenarios, transition and API documentation;
|
||
that is a larger architectural change than the apparent one-line permits edit.
|
||
C becomes attractive only if user studies establish independently named OA
|
||
communication endpoints, their distinct contracts and artifact references as a
|
||
primary modeling need. Current evidence establishes participants and means.
|
||
|
||
## Proposed minimum contract
|
||
|
||
The following are **Studio design choices** unless explicitly sourced above.
|
||
|
||
1. `CommunicationMean` is a Relation with ordinary immutable identity, alias,
|
||
exact name/description and body fields `source: Id`, `target: Id`,
|
||
`oriented: bool` and `items: Vec<Id>`. Source keyword: `communication_mean`.
|
||
Both endpoints must be different OA Entity or Actor elements. No System,
|
||
SystemActor, Activity, Role or Port endpoint is admitted. Nesting is not an
|
||
endpoint, allocation or deployment relationship.
|
||
2. Default `oriented false`, shown as “Bidirectional” in creation. `true` means
|
||
ordinary directed use follows source→target. Stored source/target order is
|
||
stable even when unoriented; reversing display does not rewrite identities.
|
||
Parallel means are valid: “Radio” and “Telephone” can join the same entities.
|
||
No physical medium, protocol, capacity or connection kind is inferred.
|
||
3. Items are distinct same-layer ExchangeItem references, using the existing
|
||
item-nature/mechanism/type contracts. `[]` is an explicit empty carried set,
|
||
not a wildcard for allocated interactions. Referenced external interface or
|
||
medium specifications can remain ordinary ArtifactLinks/Constraints; do not
|
||
add a protocol execution engine or fictitious contained physical equipment.
|
||
4. `ExchangeAllocation { source: means_id, target: interaction_id }` is a
|
||
separately identified same-layer relation. The target must be Interaction;
|
||
a CommunicationMean cannot allocate an SA FE or another communication means.
|
||
One means may allocate many Interactions; an Interaction may have several
|
||
explicitly modeled means (alternatives/redundancy). Do not collapse those
|
||
links or infer routing/execution exclusivity. Duplicate exact endpoint pairs
|
||
can be diagnosed as redundant but must not change historical admissibility
|
||
of other ExchangeAllocation kinds in this slice.
|
||
5. Let `(a,b)` be the actual allocated participants of an Interaction's activity
|
||
endpoints and `(s,t)` the means endpoints. For oriented means the only
|
||
admissible pair is `(s,t)`; for unoriented means either `(s,t)` or `(t,s)`.
|
||
Compare every known actual participant against these whole pair candidates.
|
||
If none survives, reject the allocation. If a participant is missing, retain
|
||
the allocation with a located incompleteness warning; do not guess through
|
||
a role or parent entity. A role-only assignment is intentionally unresolved
|
||
for this concrete allocation even if `effective_performer` can compute a
|
||
unique candidate. Help should offer adding/reviewing actual Allocation.
|
||
6. Every allocated Interaction item must satisfy at least one declared means
|
||
item, using the existing inheritance-aware `items_satisfy` direction. A
|
||
specialized carried item may satisfy its declared base, not conversely.
|
||
An allocation action may offer an explicit preview to add the missing item
|
||
declarations atomically; it must not silently widen the means contract.
|
||
7. Reconnect/reorient/edit of a means validates all dependent allocations and
|
||
scenario occurrences atomically. Invalid raw form edits remain recoverable.
|
||
Removing a means removes its incident allocation relations and follows normal
|
||
occurrence/reference deletion policy; it never deletes the global Interaction,
|
||
activities, participants or their unrelated ports. Removing an allocation
|
||
removes only that identified link. Reidentification updates every live
|
||
reference while preserving historical review semantics under existing rules.
|
||
|
||
### Participant scenarios and direction
|
||
|
||
Admit CommunicationMean for ParticipantInteraction and compatible MixedLegacy
|
||
scenarios. OperationalActivity scenarios and process contributions continue using
|
||
Interaction; SA BoundaryInterface scenarios use SA boundary/functional exchanges.
|
||
Messages refer to the existing means, not copied declarations. Each occurrence
|
||
retains its own ID, name, annotations and actual sender/receiver lifelines.
|
||
|
||
Provide a shared pure endpoint resolver used by core validation, direct-drawing
|
||
eligibility, form choices and renderer. For an unoriented means, test both ordered
|
||
endpoint pairs against explicit sender/receiver semantic representations. Exactly
|
||
one compatible pair resolves direction; missing bindings remain incomplete,
|
||
conflicting bindings reject, and two viable role-based pairings require explicit
|
||
participant binding rather than arbitrary tie breaking. All consumers must use
|
||
the same answer. Ordinary oriented messages allow only the stored ordered pair.
|
||
|
||
A correlated Reply follows the existing operation-response convention: when it
|
||
uses its Call's means, it reverses that Call's **resolved** endpoints, including
|
||
a Call traveling opposite the stored tuple on an unoriented means. It must not
|
||
blindly reverse the means tuple. Keep this response exception for oriented means
|
||
as well; orientation is not evidence of a physical simplex link. A separate reverse
|
||
means can also be selected and must match the correlation. No physical full-duplex
|
||
guarantee follows. This choice was criticized independently: a transport-level
|
||
Reply prohibition would impose hardware semantics absent from the primary OA
|
||
contract and conflict with current FE/Boundary operation conventions.
|
||
|
||
### Bidirectional OA↔SA transition and reviewed semantics
|
||
|
||
CommunicationMean↔BoundaryExchange is an explicit exchange correspondence, using
|
||
the existing `TraceKind::Exchange` broadened to this pair (or an explicitly named
|
||
new trace kind if root prefers); ordinary source/target/item/orientation facets
|
||
must participate in source-v5-style historical semantic review. A Manual trace
|
||
alone is insufficient if the UI claims meaningful counterpart updates.
|
||
|
||
OA→SA creation first requires reviewed participant counterparts. The communication
|
||
request then has **per-relation endpoint decisions** to reuse or explicitly create
|
||
compatible SA component ports on those selected owners. Port kinds, orientation,
|
||
items/interfaces and PortAllocations must be chosen/validated, never inferred from
|
||
“Radio” or from an OA entity. Keep entity→participant correspondence separate from
|
||
means-endpoint→port decisions; putting entity→port in the global reference map can
|
||
corrupt other participant mappings. Proposed defaults are inspectable drafts.
|
||
|
||
SA→OA maps the owners of selected boundary ports to OA participants and creates
|
||
or reuses the CommunicationMean with mapped items/orientation. Typed SA ports and
|
||
PortAllocations have no fabricated OA port counterparts. The reverse omission
|
||
closure must explicitly recognize this valid projection before removing the
|
||
boundary relation and its dependent ExchangeAllocations. If both owners map to
|
||
one OA participant, or a System-boundary decision remains unresolved, report a
|
||
conflict rather than making a self means or dropping the relation silently.
|
||
|
||
Endpoint review must show “OA participant” versus “SA port — participant owner”.
|
||
Keep/Candidate can retain or choose valid technical endpoints. Take of an OA
|
||
endpoint needs the explicit per-relation endpoint decision; it cannot paste the
|
||
mapped participant ID into the SA port field. Existing Source/Target baseline
|
||
facts remain exact identities, not silently normalized owner facts. Reusing the
|
||
current scalar facets is possible, but their transfer adapter must be explicit.
|
||
Orientation facet applicability and ExchangeItems membership must cover the new
|
||
constructor, including unknown/deleted historical references and exact resets.
|
||
|
||
## Concrete examples
|
||
|
||
Illustrative new-version source fragment, assuming OA declarations `rescue_boat`,
|
||
`control_centre`, `distress_report` and Interaction `report_distress` already exist:
|
||
|
||
```text
|
||
communication_mean rescue_radio "Rescue radio" id "00000000-0000-4000-8000-000000000601" {
|
||
source @rescue_boat;
|
||
target @control_centre;
|
||
oriented false;
|
||
items [@distress_report];
|
||
}
|
||
exchange_allocation radio_carries_report "Radio carries the distress report" id "00000000-0000-4000-8000-000000000602" {
|
||
source @rescue_radio;
|
||
target @report_distress;
|
||
}
|
||
```
|
||
|
||
Valid: report activity allocated to rescue_boat, receive activity allocated to
|
||
control_centre; both participants visible in one view. A second return Interaction
|
||
can share the means when its carried items are declared. Nested entities remain
|
||
their real semantic parents; a means to a nested rescue team attaches to that team,
|
||
even if folding later promotes its visual endpoint to the outer entity.
|
||
|
||
Invalid: replacing control_centre with an SA System; allocating an Interaction
|
||
whose known receiver performer is a third entity; allocating a nonempty item set
|
||
to an empty means contract; reversing an ordinary use after setting oriented true.
|
||
Incomplete but saveable: an allocated Interaction whose receiving activity has no
|
||
actual performer yet. A missing referenced entity is a structural error, not that
|
||
kind of incompleteness.
|
||
|
||
## Compatibility and implementation seams
|
||
|
||
Recommend one new explicit schema/source version for the upcoming persistent
|
||
OA/view additions (currently next would be 6), rather than accepting new contracts
|
||
under an old frozen grammar. New decoder reads existing v1–v5 with reports and no
|
||
disk writes; new exports advertise the new version. The frozen v5 reader can reuse
|
||
unchanged values only after an explicit old-constructor/field gate. Also fix the
|
||
shared live Relation admission in v4 and verify v3's closed constructor check.
|
||
If root elects an additive current-v5 evolution, it must explicitly version the
|
||
normative contract/API capability and document that old clients reject new
|
||
models; it cannot claim unchanged v5 semantics. A deliberate version bump is
|
||
cleaner and matches previous repository migrations.
|
||
|
||
Do not automatically convert old OA Legacy boundaries: port aliases, contracts,
|
||
interfaces, artifacts and historical references contain user data. An optional
|
||
reviewed “Convert to communication means” operation can retarget a boundary to
|
||
its OA participant owners while preserving the relation's UUID, alias, name,
|
||
items, orientation, routes, artifacts and incident allocations. Retain the ports
|
||
as independent legacy records; show obsolete references and invalid dependent
|
||
scenario/trace effects in the preview. No port deletion or equivalence assertion
|
||
is implicit. OA legacy warnings must explain preservation/conversion rather than
|
||
demanding impossible typed SA contracts.
|
||
|
||
| Integration seam | Required handling |
|
||
|---|---|
|
||
| model.rs, validation.rs and ports.rs | New kind/body/constructor helpers and OA endpoint validation; shared item logic, separate participant-allocation branch; no widening SA port contracts |
|
||
| references.rs, commands/delete/reidentify, artifacts | Live endpoints/items/dependent allocations, located references, exact identity/history behavior; failed batch remains unchanged |
|
||
| projection.rs, canvas hit/reconnect/context tools | Participant anchors, orientation, full identity/selectability; Allocation and suitable overview/capability views; FunctionalDataflow remains work-level; folding is presentation only |
|
||
| workflow.rs, forms.rs, source/API command forms | Draw/configure/edit/allocate means and items, valid owner choices, explicit reject messages; no raw JSON-only feature |
|
||
| validation.rs::message_endpoints, scenario.rs and direct scenario selection | Shared orientation resolver, actual-call reply reversal, same declaration used in participant scenario and architecture |
|
||
| transitions.rs and semantic catalog/mutate/review | Explicit new mapping, reverse omission exemption, owner/port endpoint adapter, complete orientation/item/source/target drift and review |
|
||
| language parser/writer/updater, persistence adapters, OpenAPI/API docs | Closed constructor, new version and accurate examples; current and old-version rejection; source trivia preservation |
|
||
| guide.rs, scope.md, engineering example | OA activity Interaction versus participant CommunicationMean, allocation, bidirectional use, no fake ports or deployment |
|
||
|
||
## Acceptance and falsification
|
||
|
||
Use one three-participant fixture with nested entities, two different means between
|
||
the same pair, direct work allocations, role-only unfinished work, forward/reverse
|
||
Interactions and inherited data items. Exercise the following through GUI, source
|
||
and REST, then native Windows/Linux default and minimum size:
|
||
|
||
1. Create/edit/allocate/reconnect means with explicit invalid raw draft retention;
|
||
reverse allocation only for unoriented; partial known wrong performer rejects;
|
||
role-only warns; the correct repair clears only its warning.
|
||
2. Two views/folding retain relation and allocation identities; line selection,
|
||
nested member navigation, item/member editing and artifact attachment work.
|
||
3. A reverse Call on an unoriented means and correlated Reply show opposite actual
|
||
lifeline directions; repeated/reused occurrence context remains independent;
|
||
ambiguous role bindings reject rather than silently reverse.
|
||
4. Source+JSON roundtrip, commented multi-file graphical update, Undo/Redo, Save
|
||
All/reopen, raw invalid recovery, REST dry-run/reject/ETag/restart; edits to the
|
||
means never duplicate or delete the underlying Interaction definitions.
|
||
5. OA→SA choices generate/reuse valid explicit typed endpoints; SA→OA retains the
|
||
communication correspondence without OA ports. Owner collapse and unavailable
|
||
mappings reject. Endpoint drift requires a genuine reviewed choice.
|
||
6. Old v1–v5 inputs remain exact under migration. New constructor under an old
|
||
version rejects. A reviewed legacy conversion preserves references/artifacts
|
||
and never executes from merely opening a file.
|
||
|
||
Revisit the design if representative engineering work needs independently named
|
||
OA endpoints with distinct contracts that this relation cannot express, if a
|
||
Capella/native comparison demonstrates that direct participants lose essential
|
||
role semantics, or if scoped endpoint decisions cannot represent a realistic
|
||
one-to-many system realization without corrupting correspondence. These would
|
||
justify a new endpoint or realization abstraction. They do not justify making
|
||
current port-based BoundaryExchange silently accept several incompatible meanings.
|