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