Integrate release recovery, semantic review, coverage and Windows packaging

harness/release-oa-communication-design.md

@@ -0,0 +1,284 @@
+# 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.