ARCADIA-Studio/harness/DECISIONS.md

Architectural and product decisions

• One typed model, three Rust crates. oa-core owns semantics, validation, transactions, history, references, language and projection. oa-desktop is an Iced editor; oa-server is an Axum transport/store. A second GUI/text model, event framework or runtime plugin ABI would introduce unnecessary synchronization and extension complexity.
• Bounded OA/SA profile. Typed element bodies determine layer/kind; separate records describe relationships, diagrams, realization traces and artifacts. SA has one System and external Actors; LA/PA deployment and executable simulation are outside V2. The normative reST contract and scope document state exact semantics instead of implying full Capella/SysML conformance.
• Nesting derives from meaning. Semantic containment and leaf allocation feed independent diagram projections. A placement drag changes geometry, never ownership. Shared projection drives canvas, Fit and SVG. Scenario/state graphics project the same behavior records and select them directly; numbered routes lead to full transition details.
• Creation respects its workspace. Architecture creation also places the new element in the current view. Behavior and Data creation preserve existing architecture diagrams; an explicit placement command remains available. The shared creation path enforces this once, while core commands maintain occurrence ownership and sequence order.
• Equivalent editing, explicit drafts. Every persistent field is available in typed property controls and canonical source. Source Apply validates and commits one transaction. Invalid source/property drafts remain editable; separate text/model history avoids ambiguous Undo. The temporary JSON form adapter is closed over typed records, not a second semantic schema.
• Stable identity and readable changes. Globally unique UUIDs and persisted aliases serve distinct purposes. Flat canonical declarations and @alias references reduce Git churn. Exact string controls preserve escaped LF/CR/tab values. Comments/formatting normalize on Apply; a comment-preserving parser and LSP were deferred. V1 migration preserves old IDs and deterministically assigns new view/occurrence UUIDv5 identities.
• Identity updates are ordinary atomic edits. Reference maintenance happens within the validated candidate. Selection and pending canvas gestures follow resulting IDs; editing an already-selected card preserves its draft until release. Placement relocation preserves UUID, geometry and artifact ownership, then focuses its committed diagram and perspective.
• Transitions are reviewed engineering decisions. Canonical OA-to-SA traces support creation/linking in either direction. Preview offers explicit dependencies, System/Actor boundary choices and counterparts. Existing-target reconciliation compares names/descriptions using reviewed baselines, with Keep/Take/merged values. It is not structural synchronization or a claim of lossless phase reversal. Scope follows ownership/reference dependencies, not every incident edge.
• Local and service persistence have distinct concurrency boundaries. Desktop saves compare exact last-read bytes immediately before atomic replacement to detect ordinary external editor/Git changes. Conflicts preserve drafts/files for Save as/reopen; this is not filesystem compare-and-swap. The service persists complete current-model envelopes before publishing revisions, with exclusive directory ownership and ETag preconditions. SQLite, distributed replicas, retained history and retry receipts were unnecessary for the bounded prototype.
• Artifacts remain opaque engineering references. URI/revision/fragment metadata can target any model record. Desktop and API retain it without fetching or executing content. Desktop/hosted transfer uses explicit source import/export; a direct hosted editor requires a separate concrete workflow.
• Native graphics and deployment. Retain Iced WGPU with Windows, X11 and Wayland support. The tested WSLg environment requires Mesa software Vulkan. Separate headless server binaries avoid GUI dependencies. Docker/systemd recipes are documented; actual remote installation is not implied by local verification.
• Evidence governs completion. Original Capella was operated in an isolated example and its useful nesting/navigation/transition patterns informed the UI. Independent reviews, real native workflows and automated invariants complement each other. Platform and feature boundaries remain explicit in validation/scope documents.

First-release decisions (supersede narrower V2 exclusions below)

• OA/SA semantic scope follows release-semantics-audit.md R1–R6 and actual Capella workflow evidence. Later Arcadia layers remain future work; missing OA/SA reuse, topology, state/data contracts and semantic transition review do not become release limitations.

• Preserve one typed Rust core and atomic validated model commands. Mission/capability links and process topology are independent of containment and diagram placement. Work/chain reuse uses stable reference occurrences rather than copied semantic objects; sequence guards belong to contextual links rather than global exchanges.

• Desktop lint uses one background parser plus the latest queued source version. Accepted model checks are cached separately from draft diagnostics. Stale results cannot enter a different document or overwrite newer edits. The REST service prepares bounded candidates outside its global store lock and rechecks ETags during commit.

• Relationship creation follows the selected engineering concept: directional names, compatible endpoint choices, optional generated relationship names and conditional extension text in the initial dialog. Existing model transactions remain the sole commit path.

• Help is an offline Rust topic registry with search and guarded workspace links. Task navigation is separated from the independently scrolling model explorer so search and perspective controls remain available at minimum window size. Fit uses the actual measured canvas, with a pre-layout fallback, rather than assuming a fixed amount of window chrome.

• Source/schema3 and explicit V2 migration are planned for the expanded release. Current schema2 is an integration checkpoint, not a new compatibility claim. Existing V2 packages remain preserved until final release acceptance.

• R5 state/event contract adopts region-owned entry/exit symbols attached to their containing boundary, independent per-region history, strict transient pseudo routing without event triggers, and preservation of the last removed typed trigger as descriptive text. This supports explicit engineering semantics without an execution engine; exact invariants and migration policy are in release-state-contract.md.

• Git is now explicitly authorized by the user. Establish a source baseline on codex/release1-engineering, then use focused commits at verified milestones. Use Git worktrees for independent writers when their scope can be partitioned; root integrates and owns native UI. Keep target/dist, recovery/store files and credentials outside version control. No remote publication is implied.

• User's hierarchy/port correction supersedes generic graph defaults. Architecture/dataflow/capability content differs by engineering purpose, while containment/allocation and port anchors remain derived from semantic records. The exact correction and remaining port metamodel work are in release-diagram-port-correction.md.

• Adopt release-port-contract.md: function input/output ports declare items; Standard/Flow component ports have separate orientation, interface roles and explicit function-port allocations. Required functional endpoints are generated/reused by one atomic planner. Schema3 migration preserves original generic ports as explicit unresolved contracts and generates only previously missing FE endpoints. This avoids guessing component kind, interface role or splitting stable InOut identities during import.