ARCADIA-Studio/docs/scope.md

# Current scope and tradeoffs

Arcadia Studio implements a systems-engineering workbench spanning Operational Analysis and System Analysis. The normative [language and editing contract](language.rst) defines the supported Studio profile. It does not claim full Arcadia, Eclipse Capella or SysML conformance. The [first-release plan](../harness/PLAN.md) remains incomplete; [current state](../harness/STATE.md) and the [2026-09-06 coverage audit](../harness/release-current-coverage-20260906.md) distinguish implementation, verification and remaining requirements. The [V2 acceptance](acceptance.md) and [validation](validation.md) records describe the earlier baseline, not acceptance of every subsequent change.

## Supported modeling profile

| Area | Implemented semantics and authoring |
|---|---|
| Operational Analysis | Entities, actors, roles, activities, missions, capabilities and processes; entity/work decomposition; leaf allocation; role realization/assignment; interactions and capability/process involvement |
| System Analysis | One System of Interest, external Actors, functions, missions, capabilities and functional chains; functional decomposition independent of the system boundary; allocation, functional/boundary exchanges and mission-capability links |
| Data and interfaces | Information/material/energy nature and Flow/Event/Operation/SharedData mechanisms, bounded primitive/enum/record types, typed defaults, field multiplicity/units/direction/storage, specialization, identified interface allocations and reference associations, separate function input/output and Standard/Flow component ports, interface provision/requirement, port and exchange allocations |
| Behavior | Process/chain work and exchange contributions, control topology and sequence reuse; scenario lifelines, correlated calls/replies, timers, action/state occurrences, ALT/PAR/LOOP/OPTIONAL fragments, scenario reuse and pre/postconditions |
| States and conditions | Participant-owned state machines, nested regions, states/modes and typed pseudostates, signal/time/change events, trigger/guard/effect transitions, linked entry/do/exit work, availability and constraints |
| Perspectives and evidence | Bidirectional counterpart creation/linking, reviewed descriptive and typed semantic changes, many-to-many typed/manual traces, arbitrary artifact URI/revision/fragment references |
| Views and editing | Independent diagrams, decomposition/allocation nesting, collapse, pan/zoom/Fit/Arrange, editable connection routes and labels, four-side port positioning, direct interaction/functional/boundary exchange tools, contextual menus, SVG export, model explorer and typed properties |
| Text and storage | `arcadia 5` source projects with relative includes and nested declarations, stable aliases/UUIDs, a source-file tree, per-file drafts and diagnostics, comment-preserving graphical updates, exact model/source Undo/Redo, legacy migration, atomic saves, interrupted source-save recovery, Home/recents and private unsaved-work checkpoints |
| Automation and hosted editing | Rust REST service for project/source-bundle/query/validation/transaction/transition/artifact workflows; optional desktop catalog/open/publish, explicit conditional Save, server review and local Save as; ETag preconditions, bounded requests and atomic current-revision storage |

Graphical and textual parity applies to the persistent fields of this profile. Diagram placements are model data; camera, selection, source cursor and undo history are session state. Canvas gestures need not match textual operations one for one: typed inspectors and explicit commands expose precise semantics. Full source replacement must repair dependencies in its candidate, while graphical delete/reidentify commands maintain references automatically.

## Explicit semantic choices

- OA captures operational needs; SA defines the selected system contribution. SA contains no internal logical/physical components, and Studio does not decompose SA Actors. The System may be absent while authoring, with a completeness warning.
- Work decomposition and performer allocation are independent. Only leaves have direct allocations. A parent drawn within one performer can be a computed leaf summary, not an additional allocation. Role sharing does not create several direct performers for one function.
- Nesting expresses semantic containment or the selected allocation projection. Placement movement does not change ownership or allocation. Hide and delete have different effects.
- Counterpart creation copies mapped typed content and required references. Existing-counterpart semantic review compares typed facts and prior observations, with explicit keep, take or final-value decisions for supported scalar, structural, constructor and individual collection-row changes. Reference mapping and candidate validation apply before an undoable transaction. Ordered collections, attachment/artifact and multi-source GUI reconciliation remain unfinished. Review does not automatically synchronize arbitrary structure or overwrite the other perspective. Creation scope follows ownership/reference dependencies, not every incident relationship.
- Processes/chains use contributions and explicit sequence links; imported ordered exchange paths retain their implied order until topology conversion. Rich fragments belong to scenarios. Guards, expressions and state behavior text are descriptive; there is no execution engine. Mixed states and modes are permitted by this Studio profile.
- Preserved OA boundary exchanges use Legacy ports. Capability grouping is containment; include, extend and generalization use separate typed relationships in OA and SA. Data/item references remain within their layer and can have explicit transitioned counterparts.
- Applying a source project preserves authored comments and formatting while assigning missing identities. Graphical updates preserve unaffected source bytes; canonical export is a separate operation. JSON does not preserve comments or source-file organization. See the [source contract](language.rst) for comment ownership and update rules.
- Port position and connection routing belong to each diagram and do not change semantic ownership or endpoints. Folding may temporarily promote an edge to a visible container; expansion restores its authored route. [Routing verification](../harness/release-routing-verification.md) records accepted behavior and measured limits.
- Artifact references retain author-provided URI/revision/fragment values without fetching or executing resources.

## Capella-inspired improvement targets

These are concrete design responses, not claims that every Capella user experiences the same problems or that this prototype fixes every downside.

| Concern | Studio response | Remaining tradeoff |
|---|---|---|
| Dense workbench and difficult onboarding | Task workspaces, OA/SA context, contextual menus, direct architecture and behavior gestures, searchable guidance, Home/recents and relation/transition builders | Current Home/recovery and expanded review controls still need native acceptance |
| Noisy architecture pictures | Nested ownership/allocation views, independent placements, collapse, automatic routing, editable bends/labels and port positions | Dense diagrams may need manual adjustment; routing has a bounded solve budget |
| Hard-to-review model files | Modular typed source, stable aliases/UUIDs, preserved comments/formatting and source-aware history | Semantic merges, completion and an LSP are absent |
| Hidden mutation effects | Validated atomic commands, dependency cleanup, identity maintenance, previewed counterpart changes and undo | No distributed editing or automatic structural reconciliation |
| Platform/plugin overhead | Native Rust/Iced desktop and independent headless service | WGPU has substantial dependencies and needs a working graphics adapter |
| UI-coupled automation | Renderer-independent core, documented REST commands/queries and optional hosted desktop editing | Save and server review are explicit; there is no automatic synchronization or merge |

## Required first-release work

Direct process/scenario/state authoring, typed semantic drift/reconciliation, Home/recents and unsaved-work checkpoints are implemented. Their evidence and outstanding acceptance cases are separated in the [current coverage audit](../harness/release-current-coverage-20260906.md). Direct state editing has earlier scoped Windows/Linux acceptance recorded in [state evidence](../harness/release-state-editing.md); that does not accept every current change.

Required unfinished implementation includes ordinary OA CommunicationMean authoring with an accurate participant-level contract; persisted selective relation/category/coverage views; completeness checks for exchanges on non-leaf work, behavior-context coverage and missions without capabilities; and ordered-collection, attachment, artifact and multi-source semantic-review GUI controls. Existing Legacy OA boundary exchanges and their Interaction allocations remain supported, but do not close the CommunicationMean requirement.

The desktop attempts a private checkpoint every 10 seconds while work is unsaved. It retains accepted source, raw source buffers, pending property/behavior forms and supported workflow drafts, including semantic-review input. Home recovery opens a detached unsaved copy requiring Save as; it restores no undo stack and writes neither the original model nor a hosted destination. Interrupted source-save recovery is a separate mechanism for an incomplete save transaction.

Remaining release gates include current-tree automated checks, expanded data/semantic-review and Home/recovery native acceptance, outstanding behavior and hosted workflow cases, default/minimum-window Windows/Linux acceptance, fresh build/MSRV and specification/OpenAPI checks, real REST/restart/parity verification, packages/checksums and independent final review. Guidance must follow the accepted controls. These are unfinished release requirements, not exclusions or release-acceptance claims.

## Remaining boundaries

- Logical and Physical Architecture, deployment semantics, executable behavior, complete SysML or Capella metamodel support, and native `.capella`/`.aird` import/export.
- Complete Capella communication/scenario variants beyond the specified Studio profile.
- Semantic merge, completion and language-server tooling. Local external-file checks do not provide a cross-process transaction lock.
- Collaborative editing, server undo/history, retry receipts, multiple service replicas and network-synchronized data directories. The service stores current models under explicit capacity limits. Desktop edits and Undo remain local until Save; revision conflicts require explicit review, and Reload is an undoable local operation. Credentials stay in memory and remote desktop connections require HTTPS.
- Production-scale performance guarantees, full screen-reader/keyboard diagram support, high-contrast/localized experiences and signed installers.
- Runtime plugin loading or an extension ABI. External tools can use the REST API; additional in-process infrastructure needs a concrete use case.

Windows and Linux builds are supported. Documented Docker/systemd deployment recipes are available for the service, but a recipe is not evidence of a running remote deployment. Platform, package and GUI verification must be reported from the acceptance record rather than inferred from source or CI configuration.

## Method evidence

The [semantics research](research-v2-semantics.md), [architecture research](research-v2-architecture.md) and [original Capella UI observations](research-v2-ui.md) distinguish method guidance, inspected Capella behavior and Studio design decisions. Their primary-source links are informative; `language.rst` is the concrete contract for this implementation. No Capella source code, icons or branding assets were copied into Studio.