ARCADIA-Studio/harness/release-selective-views-design.md

# Selective views and exchange categories — candidate contract

2026-09-06, root design investigation while current native acceptance is rebuilding.
This is a proposal awaiting independent criticism and implementation, not an
implemented schema or release claim. Keep the existing source-v5 contract unchanged
until the combined source/schema6 admission boundary is deliberately frozen.

## Engineering need and primary evidence

Engineers need several readable views of one architecture, selected by an explicit
engineering concern, without changing its exchanges or losing their authored layout.
The official [Arcadia Q&A](https://mbse-capella.org/arcadia-qna.html) describes
representation-only synthesis when leaf functions are hidden and grouping exchanges
by category. It distinguishes the possible dataflow from the particular uses of
that dataflow in behavior. Category display must therefore not imply a new flow,
execution path, or semantic allocation.

Capella's [FunctionalAnalysis schema](https://raw.githubusercontent.com/eclipse-capella/capella/master/m2/plugins/org.polarsys.capella.core.data.def/model/FunctionalAnalysis.ecore)
defines named ExchangeCategory and ComponentExchangeCategory records, each referring
to existing exchanges. This supports reusable explicit category membership. It does
not establish the Studio filter-combination policy proposed below. Eclipse's
[Sirius/Capella description](https://www.eclipse.org/community/eclipse_newsletter/2017/december/article2.php)
identifies contextual diagrams, filters and layers as complexity-management tools.

Current repository evidence: Diagram stores projection, placements and per-edge
routes. project_diagram derives nodes/edges from the whole model and visible
placements; ProjectedEdge retains one actual semantic ID. These are useful seams.
Do not invent a second graph model to implement selection or categories.

## Alternatives and proposed choice

| Candidate | Assessment |
| --- | --- |
| Ephemeral checkboxes plus manual hiding | Small but lost on reopen, absent from source/REST and unsuitable for shared engineering views. |
| Arbitrary query language per diagram | Flexible but adds a second language, difficult reproducibility and opaque hidden content. No demonstrated first-release need. |
| Closed persisted view options plus reusable named categories | Clear meanings, typed graphical/source/API parity and bounded computation. Recommended. |

Use explicit typed options, not arbitrary JSON paths or user-authored predicates.
Separate the semantic category membership from a view's chosen visibility and label
settings. A view filter never edits a category or any engineering relation.

## Proposed model contract

One shared `ExchangeCategory` element body has `family` (Work or Participant) and
an unordered distinct list of same-layer exchange relation IDs. Work admits OA
Interaction or SA FunctionalExchange. Participant admits OA CommunicationMean or
SA BoundaryExchange. Already-valid legacy OA BoundaryExchange is also an eligible
Participant member; that does not convert its ports or reinterpret it as a means.
New OA authoring follows the CommunicationMean contract. Category membership conveys a named concern,
not ownership, transport allocation, item compatibility, mutual exclusion or order.
The same exchange may belong to several categories. Empty categories are valid.
Keep categories as layer-root records initially; hierarchy needs separate evidence
and cycle/transition semantics. Artifact links can address categories normally.

A Diagram acquires a `ViewOptions` value with legacy-equivalent defaults:

- `hidden_edges`: distinct relation/trace IDs belonging to the view layer (including
  applicable cross-layer realization traces). This is an authored hide set, not
  deletion; routes remain retained. Missing references reject on source/API input
  and ordinary Delete cleans live references through the core transaction.
- `relation_kinds`: All or Only(explicit distinct kinds). Only([]) means no relation
  kinds, not All. Label this "No relationship lines": allocation nesting and typed
  state/action rows still express relationships independently of these graph edges.
- `work_categories` and `participant_categories`: independently All or
  Any(explicit distinct category IDs of that family). All includes categorized
  and uncategorized exchanges of its family. Any includes an exchange exactly
  when it belongs to at least one selected category; uncategorized exchanges
  fail that predicate. Any([]) includes none of that family. Neither selector
  constrains the other family or non-exchange relationships.
- `coverage`: All, InBehavior, or OutsideBehavior, applying to Work exchanges using
  the same actual occurrence/reuse reachability as coverage diagnostics. Participant
  exchanges must not inherit coverage from unrelated allocated exchanges silently;
  a later explicit transport-coverage option can define that quantifier separately.
- `work_contexts`: All or Any(explicit Process/Chain/Scenario context IDs from the
  same layer). Any requires an actual Work exchange occurrence reachable from at
  least one selected context through the same explicit reuse walk as coverage.
  Any([]) matches no Work exchanges. This is distinct from global coverage:
  "used anywhere" does not mean "used in the selected startup scenario".
  Participant exchanges and non-exchange relations are unaffected. Contexts do
  not include descendants merely because they share a semantic container.
- `exchange_labels`: Name, Items, or NameAndItems. Labels refer to declared carried
  item names; an empty set remains visibly empty when Items is selected. Label
  choice changes no selection, hide set, route, category or engineering content.

Saved node selection remains the existing explicit placement bank. Do not combine
filters with automatic semantic deletion, automatic layout or automatic insertion of
new placements. A duplicate-view command creates a new diagram and placement IDs,
copies options/routes, and retains the same semantic element/relation references.

## Exact combination and projection order

First project placement eligibility and parent/fold promotion using current rules.
Compute automatic port placement from the eligible pre-filter edge set, then retain
that baseline geometry while filtering the drawable edge set. Current port_layout
uses peer edges, so feeding it already-filtered edges could move automatic ports
when a user only changes visibility. Manual anchors remain exact. Verify this with
opposite-side peer edges and independent per-view routes; filtering must not silently
become a layout action.
For each actual eligible relationship, require its kind to be allowed, require
category membership under that exchange family's selector, require both the explicit
Work coverage and chosen-context predicates when applicable, and require absence
from hidden_edges. These restrictions combine by intersection. Category Any combines
selected categories by union. Apply these predicates to actual IDs before any
optional visual grouping. A category change never clears hidden_edges.

An edge whose endpoint has no visible placement/ancestor remains absent by ordinary
projection rules. Filters never fabricate endpoint placement. A folded internal edge
whose endpoints resolve to the same visible node stays suppressed under the existing
rule; its original semantic record remains navigable from a contextual list.

Expose a compact "View content" panel with current restrictions and a searchable
list of omitted records with the reason (explicit hide, kind, category, coverage,
or endpoint not shown). Display all contributing reasons when useful. "Show" removes
only explicit hide; if another restriction still suppresses it, show that reason and
offer an explicit filter edit. "Reset filters" is one undoable view edit, never a
semantic edit. Preserve pending property/source guards and exact undo history.

Initially display separate real edges with category membership in the inspector and
filter controls. If grouped category lines are needed to achieve readable acceptance,
add a distinct presentation result with `members: Vec<Id>` and an explicitly marked
summary label. Never assign a category ID as though it were an exchange. Picking a
summary opens its actual members; it cannot create/reconnect/delete a synthetic
exchange. Group only compatible promoted endpoint pairs/orientation/family and show
the member count. A member in multiple selected categories needs a deterministic
nonduplicating policy before this optional grouping can be accepted. Do not claim
grouped-summary functionality from filtering alone.

## Editing, lifecycle and parity

View options use EditDiagram and the current Document transaction. Source syntax
must distinguish All from empty selected sets, retain explicit options during
lexical edits, and reject unknown values. Schema6 migration adds default options
without changing old projection results or routes. Older envelopes must reject new
constructs rather than using current live Diagram/Element types accidentally.

Category edits use normal typed element creation/properties. Core reference visitors
cover all members and selected categories; reidentification changes every live
reference. Delete category removes the ID from selected category sets but leaves
Any([]) explicitly empty rather than widening to All. Deleting a selected context
similarly removes only that context ID and retains Any([]). Delete an exchange removes
only its membership and live view references, preserving independent exchanges and
routes. Preview the resulting effects through the existing deletion contract.

Category transition maps explicit members through reviewed exchange counterparts;
it cannot imply that a missing exchange is unnecessary or fabricate one merely to
fill the category. Members/order/source facets and artifact links need closed
semantic-review support. A view is presentation data, not a realization-trace target.
Duplicating across layers requires explicit counterpart placement decisions and
cannot reuse old layer IDs blindly.

The same pure filter/projection implementation feeds native Canvas, SVG, REST view
queries and inspectable diagnostics. GUI controls expose every persisted option.
No per-pixel model-wide coverage scan: build the reachability index once per accepted
revision and reuse it across requested views. Establish an actual sparse/dense timing
measurement before optimizing beyond that boundary.

## Falsification and next action

Use a fixture with two OA participants, three activities, two processes sharing one
Interaction, an uncovered Interaction, two overlapping categories, a non-exchange
relation and a folded owner. Save two views with different restrictions and routes.
Hide one shared-category edge, change labels/categories, reopen, undo/redo and compare
exact source/projection. It must stay hidden. Verify Only([]), Any([]), category
deletion, ID swaps, edge deletion/recreation, same-name categories, hidden endpoints,
two unrelated view geometries, source migration and atomic REST rejection/restart.
Add a context truth table with one globally covered exchange outside the selected
process, one shared by both processes, and one uncovered exchange. Verify category
selectors independently across both families, including uncategorized members.
Add forty exchanges between the same visible endpoint pair in one category. If
filtered separate edges remain unreadable, grouped presentation is required before
claiming the category complexity-management workflow accepted; the sparse fixture
cannot establish that result. Keep original member navigation and hide persistence
as mandatory acceptance in any grouped alternative.
Behavior coverage changes should update visibility without silently altering saved
options or emitting view-history transactions.

Independent review should challenge the category family shape, legacy admission,
meaning of uncategorized exchanges and non-Work coverage, omitted-record UX, and
whether separate edges plus filtering satisfy the initial user task. Freeze those
answers alongside CommunicationMean/source6 before production edits.