ARCADIA-Studio/harness/release-oa-communication-design.md

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 Interactions. 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.

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, FunctionalAnalysis schema, ComponentExchange. 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:

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.