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.

• Source/schema3 is now implemented. The original V2 comment-normalization decision is superseded for the first-release source-project work: validated bundle updates preserve concrete tokens/comments/whitespace, while explicit canonical export remains available. Desktop bundle editing and experimental nested syntax are separate acceptance gates; neither is implied by the pure-core updater.

• Connection routing is per diagram, keyed by an existing relationship/trace ID. Store ordered pinned points and relative label placement; derive orthogonal elbows in a pure Rust core shared by canvas, picking, Fit and SVG. Typed port anchors never move to improve a route. Bounded automatic routing provides an initial path; manual pins express engineering layout intent. Collapse temporarily suspends authored routing when endpoints are promoted, preserving it for expansion. One pointer gesture commits one atomic command; stale/invalid-draft gestures are rejected.

• Source workspace integration uses one accepted history of compiled source/model snapshots. The existing semantic Session remains for model-only consumers; a shared prepare_command supplies validated candidates and creation selection without committing or generating IDs twice. Desktop source writeback must succeed before adoption. Comment-only accepted edits are real history entries. Drafts and disk baselines stay separate; see release-source-integration.md for the implementation and acceptance contract.

• Model navigation uses one cached semantic containment index for both outline and focused browser. Group only roots, preserve full depth, and show allocated work separately. Direct children and paged contextual search replace the flat catalog. The outline uses constant widgets per row; no new virtual-tree framework is introduced.

• Port creation is explicit at the participant: Add port chooses Standard/Flow, then the selected port exposes Connect boundary exchange. Function Input/Output actions remain distinct. Candidate feasibility shares exact core validation with an explicit orientation parameter, avoiding per-choice project cloning and preserving Legacy behavior.

• Recovery state is independent of source diagnostics. Interrupted Save All journals remain discoverable after lint, typing, missing entry files or first-save failure. Recovery validates current bytes against known transaction states; it does not promise atomic multi-file visibility or cross-process filesystem locking. Source/property draft guards prevent one representation from silently replacing pending edits in the other.

• Production source3 nesting expresses semantic element ownership only. Extend the existing parser and source index with real lexical owners/body spans, rather than adopting the experiment's parallel parser. Flat canonical interchange remains valid. Structural writeback composes declaration pieces after ordinary token edits and uses original occurrence provenance through temporary UUID collisions. This preserves independent parent/child moves, authored files, comments and exact history while allowing new children to be emitted inside their owners. Allocation and ordered occurrence membership remain explicit.

• A hosted revision owns the accepted model and stabilized source bundle together. Store one atomic envelope, use the same core writer for commands and previews, and advance the ETag for comment-only edits. Old model-only envelopes acquire deterministic source in memory without a read-time write or revision change. A detached source sidecar would create inconsistent revisions and unsafe restart behavior. Accepted model equality alone is insufficient for a no-op when command provenance deletes/recreates a declaration; this was reproduced and corrected in desktop and REST adapters.

• Contextual actions use a controlled Iced overlay and captured semantic target plus document/revision/view context. Menus reuse existing handlers, and opening a menu does not select/apply another draft. Canvas focus scopes routing keys; Actions is an accessible alternative to right-click. Source files use a folder tree with exact paths and aggregate draft/diagnostic markers.

• Port anchors are per-placement presentation records with four sides and normalized offsets. Automatic sides use port direction and visible peer geometry; explicit anchors do not change owner minimum dimensions. Canvas, routing, Fit and SVG share projected anchors and side normals. Graphical reparent batches old-owner anchor cleanup with semantic reparent; raw source and API remain strict and require explicit repair.

• Direct connections use explicit Select/move and exchange palette tools. Compatible visible endpoints are highlighted; click-click or drag creates one ordinary validated command. Function-card gestures use the existing automatic port planner. Tool invocation, blank-canvas restart, Escape and model/view changes invalidate old gesture contexts. No project clone or whole-model compile occurs per highlighted candidate; final commit still validates the complete model/source change.

• Port identity feedback is a passive stacked Canvas: Iced Frame separation alone does not create GPU layering. The independent native overprint reproduction established the need; input stays with the existing interactive child.

• Each checkout uses a distinct Cargo target directory. A shared-target Linux run reused a different worktree's test executable; only explicitly rebuilt main results count as evidence.

Persisted state workspace and input coordinates (2026-09-06)

State-machine views use the core projection/routing and ordinary Document commands, with a retained behavior owner/view separate from Architecture. Palette gestures create elements plus placements atomically; typed forms remain reachable for Local, Internal and timed transitions. Context menus capture the state diagram so fold, hide and placement properties cannot modify an unrelated Architecture view.

Gesture displacement is measured in ordered window coordinates, not coordinates relative to a canvas whose origin may move when selection changes the toolbar. Viewport notifications fit only on actual size changes. Native testing also showed Iced WGPU places parent meshes after clipped child meshes; backgrounds must share their content clip to avoid hiding vector geometry while leaving text visible.

State camera/tool lifetime follows effective machine and diagram identity, even when selection changes through Catalog or Layer outside Behavior. Reset only on actual context change; preserve same-view return. Independent review reproduced the leak and native Windows/Linux tests verified the correction in316dc55.

• Carried-value property browsing follows one exact record scope at a time, with bounded pages and a separate read-only browser location. Flattened representative paths were proven ambiguous in native recursive/reused data. Browsing does not change the selected field or expression; choosing a field remains an explicit draft edit through the ordinary validated command. No persistent browser schema.