ARCADIA-Studio/harness/release-semantics-audit.md

First release OA/SA semantic audit — 2026-09-05

Read-only review of the new first-release objective in 81e84f53-2b51-4151-9e34-59414bda8b2d/goal-objective.md, the current core, and official Arcadia/Capella references. This is a release planning audit, not a test pass or runtime assessment. No implementation files, builds, or native UI were touched. The old V2 scope exclusions are historical decisions, not authorization to omit OA/SA release functionality.

Conclusion

The current implementation has a useful coherent foundation, but its 27 element kinds and 15 relation kinds are not yet feature-complete OA/SA. The largest holes are contextual process/chain topology, capability/mission relationships, meaningful iterative semantic updates, reusable/typed scenario behavior, and fuller state/data contracts. Keeping those absent while changing the version number would preserve the prototype boundary rather than fulfill the new objective.

“System Architecture” is interpreted as the System Analysis perspective containing the System of Interest, external actors, functions, exchanges and interface contracts. Internal logical components, physical implementation and deployment belong to the explicitly deferred later perspectives. The new objective does not require copying every Capella implementation class or every Eclipse extension.

Already present, and worth retaining

• model.rs separates semantic elements, typed relationships, diagram placements, canonical cross-layer traces and artifact references. session.rs and references.rs centralize validation, identity remapping, deletion cleanup and undo. These are suitable release boundaries.
• OA entities/actors/roles, activity decomposition and allocation; SA System/actors/functions, missions/capabilities; typed items, records, ports/interfaces; basic nested scenarios and state machines are real model data, not presentation-only constructs.
• OA communication allocation already exists: validation.rs:969–986 accepts BoundaryExchange → Interaction as well as the SA FunctionalExchange case; 1357–1403 checks allocated endpoint performers and carried items. Earlier SA-only wording in RelationKind::hint and docs/language.rst:230 understates the implementation. This is a contract/discoverability correction, not grounds to add a duplicate OA relation.
• Work decomposition and performer allocation remain independent. Keep containment/allocation projections, stable placement identity and separate hide/delete operations. Do not introduce SA internal components just to make nesting more elaborate.

Release-critical additions

R1. Processes and chains must represent contextual paths, branching and reusable contributions

Evidence. Official Capella FunctionalAnalysis defines function involvements, chain references, control nodes and sequence links in OA and SA. Arcadia distinguishes the global dataflow from contextual paths. FunctionalAnalysis schema, Arcadia Q&A.

Current limitation. OaBody::Process and SaBody::FunctionalChain store only steps: Vec<Id> (model.rs:187–205). validation.rs:944–952 expressly rejects every direct sequence occurrence except Exchange. validate_sequence at 769 only walks a linear list, checking consecutive exchange endpoints. There is no explicit function involvement to hold a context-specific contribution, no guarded split/join, no chain reference, and no sequence topology independent of global exchanges. A rescue path with parallel position assessment and asset preparation cannot be modeled as one process/chain without inventing a false linear order or moving the engineering information into a scenario.

Minimal coherent design. Preserve durable involvement IDs. Add work involvement, control node and reusable sequence-reference variants; add explicit contextual links with guard text and optional referenced semantic exchange. Links belong to one process/chain and connect its involvement records, never raw functions. Keep a simple linear authoring action that generates this same topology. Validate scope, endpoint correspondence, dangling refs and recursive sequence references; diagnose unreachable or ambiguous starts/ends while allowing incomplete editing. A scenario remains a distinct time-oriented representation. A flat steps list can remain a presentation order, but must not masquerade as branch topology.

Release proof. OA parallel/alternative process with a reused subprocess; transition to SA chain; edit branch guard and per-function contribution; graph/text/save/reopen/delete/undo preserve all involvement identities. No implicit changes to global dataflow.

R2. Capability relationships and mission participation need first-class semantics

Evidence. Capella's Interaction schema has capability include, extend and generalization; ContextArchitecture has MissionInvolvement. Arcadia also names operational missions, although Capella's OA package does not expose a matching Mission class. Interaction schema, ContextArchitecture schema, Arcadia metamodel, missions/capabilities section.

Current limitation. The complete RelationKind catalog (model.rs:531–647) has none of the three capability relationships or participant→mission involvement. parent_permits allows capability containment, which is not a replacement for inclusion, conditional extension or specialization. OA lacks a mission kind entirely. Engineers cannot express reusable common capabilities, conditional degraded behavior at capability level, or who participates in a mission independently of a capability.

Minimal coherent design. Add typed CapabilityInclude, CapabilityExtend (condition), CapabilityGeneralization and MissionInvolvement. Define direction precisely in UI and reST; same-layer/same-capability-family endpoints, no self-reference, inheritance/include cycle checks, and explicit extension-condition diagnostics. Add OperationalMission with mission→capability and participant→mission links, clearly documented as Arcadia method support rather than byte-for-byte Capella OA conformance. Keep visual group containment distinct. Transition these relationships using mapped endpoints; do not turn include into parenthood.

Release proof. Build a mission map with actor participation, common included capability and conditional extension in both layers; demonstrate cycle rejection and readable diagram/source relationship navigation.

R3. Transition review must detect and handle semantic drift beyond names

Evidence. Capella documents conservative iterative transformations over ownership and related elements, with a proposed-result comparison against the target. The user additionally requires intuitive transitions in both directions. Iterative transition concepts.

Current limitation. TransitionField is only Name/Description (transitions.rs:31–35). trace_drift (127–140) reads Project::properties, which returns those same two strings. Existing typed bodies, referenced items, parentage, exchange endpoints, guards and sequence contents are not reviewed. Changing a traced data-field multiplicity or scenario body can leave the trace Unchanged. This is a material mismatch with an engineer's expectation of a reviewed model relationship, even though V2 documented the restriction.

Minimal coherent design. Extend baseline data to a normalized semantic snapshot, excluding diagram geometry and generated target IDs. Store mapped identity-aware references. Expose typed content, containment and relationship proposals separately, with Keep target/Take mapped source and explicit endpoint choices. Preserve the existing conflict gate, target-context resolution reset, stale-plan check, atomic undo and no cross-layer deletion cascade. Many-to-many merges and splits require engineer choices; never invent an automatic inverse. At minimum every supported semantic edit must mark drift, and every automatically mappable field must have a reviewed propagation path. Arbitrary structural replacement under an opaque “body” checkbox is insufficient if it can silently destroy independent target work.

Release proof. Change datatype, multiplicity, exchange items, parent, guard and process topology after initial transition. Show accurate drift and field/structure proposals both ways; keep one target divergence; repeat idempotently; undo; verify stale previews cannot apply.

R4. Reusable scenarios and explicit message semantics

Evidence. Capella's Interaction schema distinguishes scenario/message kinds and InteractionUse references. Interaction schema.

Current limitation. SharedBody::Scenario has context, pre/postconditions and steps; Exchange occurrence has one relation and two optional lifelines (model.rs:261–323). Existing generic lifelines do support functions or participants, and ALT/PAR/LOOP/OPTIONAL branches are already implemented. Missing are scenario reuse, message call/reply/asynchronous distinctions and a declared viewpoint contract. A reusable start-up sequence must be copied, losing its single identity; a request/reply looks like two indistinguishable arrows.

Minimal coherent design. Add scenario-use occurrences with explicit referenced scenario and lifeline mapping, with same-layer and recursive-use checks. Add message kind and correlation to a call when applicable; define safe defaults for migrated generic exchanges. Add clear scenario viewpoint selection (operational activity, participant interaction, functional, boundary/interface), or an equally precise inferred viewpoint with visible diagnostics. Define source/target representation compatibility once in core. Add contextual exchanged-value annotations bound to stable data-field IDs rather than relying exclusively on prose. Do not claim message execution or simulation.

Release proof. Reuse one scenario from two capabilities; change it once and navigate both uses. Model a request, reply and unsolicited event, including a guarded branch; reject a wrongly mapped lifeline. Show equivalent rendered/source semantics and transition the whole reference closure.

R5. State machines need more than four vertex kinds and string-only triggers

Evidence. CapellaCommon includes choice, junction, fork/join, shallow/deep history and entry/exit/terminate pseudostates, transition kinds and time/change events. CapellaCommon schema.

Current limitation. StateKind supports State/Mode/Initial/Final only; StateTransition stores trigger/guard/effect strings (model.rs:240–246, 704–711). Nested regions and linked state actions already exist and should be retained. Engineers cannot explicitly model conditional dispatch, parallel-state synchronization or resume-after-interruption history; a trigger naming an event is not a maintained semantic reference.

Minimal coherent design. Extend a single typed state-vertex enum with the standard pseudostates rather than separate unrelated frameworks. Add transition kind (external/local/internal), typed event references alongside optional descriptive expressions, and time/change event bodies. Validate each pseudostate's cardinality, region context, history fallback and initial/final direction rules. Rendering needs distinct readable symbols and nested-region visibility; a new enum shown as an ordinary state box does not meet the workflow.

Release proof. Degraded operation machine with choice, parallel regions/fork/join, recovery history and a timeout. Rename/reidentify the event without breaking triggers; test inappropriate endpoints; round-trip/transition/undo the nested machine.

R6. General-system data/interface contracts need explicit reusable semantics

Evidence. Capella Information provides exchange mechanisms, structured typed content, data inheritance/associations and value constraints/defaults. Information schema.

Current limitation. Current records/enum/primitive data and field multiplicity/unit are useful. But ExchangeItemKind mixes physical nature with Event and has no independent interaction mechanism; DataTypeDefinition lacks constrained numeric/string types, defaults, inheritance or association. A quantity range or input/output operation parameter can only be prose. Functional and participant ports share unrestricted InOut (model.rs:234–239); validation.rs:1082–1087 admits InOut on functional endpoints although Arcadia functional ports are exclusively input or output. Arcadia metamodel, function-port section.

Minimal coherent design. Keep nature (information/material/energy) separate from mechanism (flow/event/operation/shared data); preserve legacy Event by explicit migration. Add typed parameter direction for operation items, type-level bounds/default/unit, record specialization and association with multiplicity. Define own-versus-reference semantics and recursive type rules. Warn on existing bidirectional function ports, provide a split migration/editor action, and prevent new ambiguous function-port contracts. Keep participant bidirectionality. A typed property/value facility for units and measurable non-functional constraints is appropriate; a general plugin metamodel is not needed.

Release proof. Physical flow, energy transfer and request/reply interface with reusable bounded quantity/enum/record types. Invalid defaults/ranges and direction mismatches are diagnosed; semantic types survive API, source, GUI and cross-layer review.

Release usability and contract work tied to semantics

1. Exchange categories and selective diagrams. The official functional schema supports exchange categories; Arcadia recommends synthesis to reduce clutter. Current Diagram exposes four projections and nodes but no category/filter definitions. Add named exchange sets and persistent visible-layer/category/relation filters with equivalent text fields; optionally show aggregate edges with navigable members. Do not replace actual edges with fake semantic exchanges. This is strongly recommended for the user's explicit uncluttered-system-engineering requirement. FunctionalAnalysis schema.
2. Completeness diagnostics. Add actionable coverage for non-leaf work carrying exchanges, leaf work absent from capabilities/processes/scenarios, mission without capabilities and interface responsibilities. These are warnings during authoring, not a ban on incomplete projects. Current validation has allocation-leaf checks and sequence gaps, but no exchange-on-parent or path coverage diagnostic. Arcadia's leaf guidance is explicit. Arcadia Q&A.
3. Normative parity cannot be inherited. Correct the OA ExchangeAllocation table/hint now. For every added constructor/field, update language keywords, parsing, canonical writing, reference enumeration/remap/removal, schema migration, inspector creation/editing, diagrams, REST queries and OpenAPI examples together. schema_version and source version are currently 2; a deliberately versioned migration is safer than silently changing closed enum/record contracts under “arcadia 2”. Preserve all V2 UUIDs/aliases and explain generated involvement IDs.
4. Built-in guide is explicit release scope. The root/UI workstream must add navigable concepts, common workflows and application commands, including the distinction between dataflow, process/chain, scenario, containment, allocation and trace. A link to repository Markdown alone does not satisfy the requested in-app guide.

Reasonably future, without redefining OA/SA completion

• LA/PA/EPBS components, deployment and physical paths: explicitly later layers, not a missing SA internal hierarchy.
• Executable simulation, scheduling or code generation: modeling guards and time constraints need unambiguous descriptive semantics, not an execution engine.
• Byte-compatible native Capella import/export and every Eclipse metamodel implementation detail: valuable interoperability work, but the user asks a modern general tool, not an exact Capella file adapter.
• SysML v2 conformance, full expression-language theorem proving, complete Capella viewpoint/plugin ABI, replicated collaborative storage: neither necessary to encode the OA/SA semantics above nor explicitly required for first release.
• Advanced reusable model libraries and semantic Git merge can follow after stable identities, source parity and the direct editing workflows are complete. They must not be used as substitutes for basic scenario/process reuse in R1/R4.

Implementation order and acceptance boundary

1. Freeze additions in the normative reST and core interfaces. Keep the existing one-model/one-transaction design. Agree on the state/event, occurrence/topology and value representations before parallel desktop/API implementation.
2. Implement R2 as a small first observable milestone, alongside the existing OA allocation documentation correction and built-in help work.
3. Implement R1/R4 together because stable involvements, contextual references and reusable behavior share reference-maintenance requirements. Implement R5 and R6 as separately owned core modules/commits where practical; do not let several workers edit the same exhaustive match catalogs simultaneously.
4. Extend semantic transition snapshots/mapped proposals (R3) against the frozen typed bodies; prove drift coverage for all persistent semantic fields with a meaningful table-driven fixture, not only a rename test.
5. Integrate projection/filter/diagnostic polish, then exercise a complete general-system OA→SA workflow including degraded behavior, item/interface contracts, artifact links, source editing and REST transactions. All new persistent records must be graphically editable, safely deletable/reidentifiable, undoable, canonical and round-trip stable.

These findings identify necessary release work from inspected current source and primary semantics. They do not prove a specific implementation is correct and do not constitute permission to call the release complete before native runtime and independent verification.

Proposed concrete core interface for integration discussion

This is a proposal, not an agreed API or implemented contract. Prefer extending existing typed records over adding independent object registries. Freeze the exact names with the language/desktop owners before coding.

Existing location	Proposed addition/change	Key invariant
Kind, OaBody	OperationalMission; OaBody::Mission	OA-only; counterpart default is SA Mission, preserving an explicit Manual trace until a dedicated Mission trace is introduced.
RelationKind/RelationBody	CapabilityInclude { source, target }; CapabilityExtend { source, target, condition: String }; CapabilityGeneralization { source, target }	Include points including→included, Extend extending→extended, Generalization specific→general; same family/layer.
Mission links	MissionInvolvement { source, target }; widen existing MissionCapability to the corresponding OA/SA family	Involvement participant→mission; MissionCapability mission→capability.
OccurrenceBody::Action	Reuse its action reference as a work involvement in a process/chain; require lifeline == None outside scenarios	Avoid a redundant Work enum. The occurrence's existing description is its context-specific contribution.
OccurrenceBody	Control { kind: ControlKind } with Choice, Merge, Fork, Join, Loop; SequenceReference { sequence: Option<Id> }	Process/chain only; reuse target in same layer and sequence family; no recursive references.
RelationBody	SequenceLink { source, target, guard: String }	Both endpoints are occurrence records directly owned by the same process/chain. Contextual precedence never invents a global functional exchange. Exchange occurrences remain identifiable nodes between work/control nodes.
Existing steps vectors	Retain as stable presentation order/membership for all owned occurrences; explicit SequenceLinks encode topology	Migrating a linear V2 process preserves Exchange occurrence UUIDs, generates work occurrences and links deterministically, and does not renumber old references.
SharedBody::Scenario	viewpoint: ScenarioViewpoint (OperationalActivity, ParticipantInteraction, Functional, BoundaryInterface)	V2 generic scenarios migrate by inspected lifeline/exchange types; ambiguous legacy content has an explicit MixedLegacy value and diagnostic until resolved.
OccurrenceBody::Exchange	message_kind: MessageKind (Asynchronous, Call, Reply); reply_to: Option<Id>	Reply references an earlier compatible call in the same scenario; legacy asynchronous is a documented default.
OccurrenceBody	ScenarioUse { scenario: Option<Id>, bindings: Vec<LifelineBinding> }; LifelineBinding { referenced: Id, local: Id }	Unique referenced/local role mappings, compatible represented objects, same layer, acyclic scenario use.
StateKind	Choice, Junction, Fork, Join, ShallowHistory, DeepHistory, EntryPoint, ExitPoint, Terminate	Reuse the State typed body with an expanded vertex kind; entry/do/exit actions apply only to actual State/Mode vertices.
State transition body	kind: StateTransitionKind (External, Local, Internal); events: Vec<Id> alongside current descriptive trigger/guard/effect	Event references are maintained by ordinary delete/reidentify operations; internal transition has defined self/target policy.
Shared event kind/body	Event { kind: EventKind }; EventKind Signal { item: Option }, Time { expression: String, relative: bool }, Change { expression: String }	Same-layer typed references, not interpretation of arbitrary trigger strings.
Exchange item body	Preserve kind; add independent mechanism: ExchangeMechanism (Flow, Event, Operation, SharedData)	Physical nature and interaction mechanism remain independent; preserve all legacy category values when migrating.
Data field body	direction: ParameterDirection (Unspecified, In, Out, InOut, Return); default: Option<DataValue>	Operation parameter directions valid only in the correct item context; defaults match referenced type and range.
Data types	Add constrained numeric/string constructors plus record supertype, or introduce equivalent typed restriction fields	Existing unit/multiplicity fields retain meaning; ranges constrain values rather than collection cardinality. Reject cyclic specialization.
Relations	DataAssociation { source, target, source_minimum, source_maximum, target_minimum, target_maximum }	Record/type endpoints in one layer; multiplicity bounds valid. Reuse typed relation infrastructure.
Shared category body	ExchangeCategory { exchanges: Vec<Id> }	Same-layer exchange references; categories may overlap and do not change exchange endpoints.
Diagram	Typed persistent relation/category visibility configuration	Hiding a category changes presentation only, and source parity includes every persisted filter.

For transition review, the smallest robust extension is a typed SemanticSnapshot containing the element parent/body or relation body in addition to name/description, stored independently for OA and SA. TransitionField can gain Parent and Content initially, provided Content previews expand all changed fields/references and require an explicit review; it must not be an opaque replacement button. Better per-property decisions can use a closed set of field paths derived from each typed body, validated against its schema rather than allowing arbitrary JSON writes. The mapped candidate resolves every source reference to an explicitly selected/unique traced target before comparison. Parent, content and incident-relationship proposals remain separate; a source's unselected unrelated relationships must not be silently copied.

Use SemanticSnapshot equality for complete drift coverage even where automatic mapping is not offered. Preserve V2 baselines as name/description-only historical reviews with an explicit semantic-unreviewed state, rather than pretending they certify content they never recorded. Preserve many-to-many traces; incompatible merging remains an explicit unresolved proposal.

Cross-cutting integration surface: ElementBody::{new,kind,shared,steps}, RelationBody::{kind,endpoints,items}, Kind::{ALL,supports,label}, RelationKind::{ALL,permits,hint}, references::{element_references,relation_references,remap,cleanup}, validation/parent/connect queries, Session transaction admission, counterpart mappings, language constructor catalogs, property-form variant selectors, behavior projection and migration fixtures. Do not consider enum additions done until these surfaces are wired and exercised.