ARCADIA-Studio/harness/DECISIONS.md

Architectural and product decisions

Current continuation decisions — 2026-09-06

• Saving under another source entry basename is destination bookkeeping, not an engineering edit. Adopt an exact current save receipt without adding Undo or clearing Redo; rebase uniform entry names across retained history after collision and compilation checks. Stale receipts cannot redirect newer raw source. Native discovery and eleven focused regression results are in release-save-as-runtime-packaging.md; updated native verification remains required.
• Home Resume returns to the last actual workspace. A saved state diagram opens in Behavior with its dedicated renderer; entering Architecture explicitly remains possible. Constructor choice among UUID-ordered views is not a guarantee that an application starts in Architecture. Tests of architecture placement must enter that workspace explicitly.
• Coverage warnings describe missing engineering context while structural errors remain rejecting. Mission/capability support and work/exchange behavior coverage use actual explicit links and occurrence membership, not inferred performer allocation or descriptive state notes. The shared core diagnostics are exposed equally to source, desktop and REST; see release-coverage-diagnostics-design.md.
• Portable release contents need the selected binary's complete runtime and notice inventory. Adding the gnullvm libunwind DLL resolves its ordinary import, but the application MIT license does not replace linked dependency notices. Archive hashes and clean-PATH launch are separate checks; neither alone establishes full release acceptance.

The following older decisions retain their historical scope. Newer first-release decisions and the normative language contract supersede prototype exclusions.

• 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)

• R3 production adopts closed typed per-facet reviews (C), selected after the 11-case proof in b2ab2b1 and independent adversarial review. Each self-tagged fact stores independently reviewed OA/SA typed values; absent facts remain Unreviewed, and NotApplicable distinguishes an absent constructor branch from an absent optional value. This supersedes recursive SemanticValue/string paths and typed-body carrier/mask/order-shadow baselines. Extra finite adapter code is accepted for fewer persisted-state invariants, not as a generic metamodel. Atomic keyed rows, target-only preserving member deltas, independent order, exact constructor groups, explicit mapping resets/canonical target agreement and actual prepared-impact review remain required. Keep the existing Command and transition planner boundaries. Artifact reviews attach to semantic traces. Schema/source5 is explicit, with unchanged data4 compatibility. The authoritative implementation/ownership/evidence contract is release-semantic-review-implementation.md; production implementation and release acceptance are still pending.

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

Semantic review proposals and historical admission (2026-09-06)

R3 stores closed, typed, independently reviewed OA/SA facet pairs. Constructor facts store discriminators only; explicit group decisions enumerate and retire their exact branch facts. No persisted recursive value tree, own-record carrier, review mask or order shadow is introduced. The complete contract is release-semantic-review-implementation.md.

Derive every source proposal from the same immutable initial project. Reset old mapping selectors before deriving scopes; compare all desired canonical target slots, including constructor removals, before one materialization. Audit selected values against both that result and the ordinarily prepared project. This prevents sequential last-write wins, even when one source introduces a member another constructor removes. Preserve target-only members during same-target-constructor reconciliation. Artifact attachment and explicit owner changes share the actual artifact's owner slot; child/incident operations similarly share actual parent or endpoint slots. Exact prepared cleanup impacts require explicit acknowledgement and may not contradict a selected Keep/Take.

Artifact metadata is observed by identified record after authorization against its initial attachment. An owner move therefore retains the actual resulting Owner/Name facts, including target-only links; Presence remains owner-relative. New metadata decisions require the current attached owner trace. Historical paired selectors survive disappearance of one side and suppress redundant one-sided projections. A new pairing cannot suppress prior one-sided history without reset.

Current resolution applicability and historical baseline admission are separate. New decisions require a compatible current family and an applicable side; historical typed facts can outlive former constructors/families and deleted references. Their typed reference visitor supports explicit reidentification but does not add live deletion dependencies. Derived linked-definition drift remains bounded and exposes missing review coverage instead of copying a shared definition into every baseline.

Hosted destination identity and bounded independent panes — 2026-09-06

A hosted save binding belongs to one installed document, not the connection dialog. Installing any local source workspace, including invalid repair source, detaches it; a failed or cancelled load does not. Verified regression prevented accidental write to a previously opened server model after repairing local text. Catalog freshness is explicit and scoped to its service; observing a changed bound head invalidates even empty filtered results. Background polling is unnecessary.

Pending process forms use an independent bounded scroll pane with pinned actions, while the diagram retains its own camera/scroll state. Nesting both under the page scroll supplied infinite height and clipped the fields at the supported minimum. Real Iced layout tests verify finite field space; native recheck remains required.

Private recovery and integrated continuation — 2026-09-06

The branch audit selects c091f80 as the integrated production baseline: side-branch state/process/scenario/data/hosted/semantic work is present or patch-equivalent. The stale checkout's duplicate investigation stays in its named stash. New work continues on codex/release1-continuation rather than replacing accepted editors.

Unsaved recovery uses separate per-session, versioned private checkpoints. Store the accepted authored source bundle and raw source/property/behavior/workflow drafts; regenerate validation and command previews on restore. Never serialize credentials, destination handles or reusable executable plans. Restored work is an unsaved copy requiring an explicit destination. Undo history is deliberately not restored: retaining a coherent current model and rejected input is the useful recovery boundary, while persistent history would add a separate migration and storage contract. Exact accepted-source validation precedes replacement of the currently open document.

Checkpoint writes and restoration share workspace admission limits. A failed checkpoint must retain the last usable file. Late completions are scoped to the document ID, and discard/close waits for an outstanding writer before retiring its result. Model-file Save and private recovery remain distinct operations. Native crash/restart and exact21-file Save as evidence is recorded in release-current-native-verification.md; larger recovery/history requirements would justify revisiting these explicit bounds.

Semantic rows and state-view entry — 2026-09-06

Annotation and Binding keys identify independent rows; replacing an existing row preserves its position, an identical Keep does not modify it, removal deletes only that row, and a new row appends. GUI composition and core materialization agree without normalizing untouched records into a different order. Core regressions cover Keep plus an unrelated Header Candidate in both directions and both row families.

A persisted StateMachine diagram has one editing canvas and tool set. Opening or selecting it routes to the existing Behavior workspace, preserving exact diagram identity, selected object and raw property input. Explicit Architecture navigation selects an ordinary view or its empty state. This fixes the native-observed blank state-action header and inappropriate architecture connection tools without adding a second state renderer. Pending drafts remain subject to the existing guards.

OA communication means: selected representation — 2026-09-06

The existing OA Interaction describes activity exchange; ordinary participant communication is a verified first-release gap. Independent representation and adversarial reviews compared a new CommunicationMean, widened BoundaryExchange endpoints and a first-class OA port contract. Select explicit CommunicationMean with OA Entity/Actor endpoints, orientation and carried items, reusing identified ExchangeAllocation links to Interactions. Existing BoundaryExchange keeps its port contract; legacy OA data is preserved without automatic conversion.

This choice matches primary Arcadia/Capella method evidence and avoids inventing technical OA ports. Known actual performer mismatches reject allocation; missing performers are incomplete work, not inferred through role responsibility. Scenario direction must resolve explicit lifelines, and correlated Reply reverses the actual Call direction. OA participant/SA port counterpart choices must be scoped explicitly per exchange rather than corrupting global participant correspondence. See release-oa-communication-design.md and the independent critique for sources, alternatives and falsification tests. This is a representation decision, not an implemented or accepted feature; versioning and view contracts remain to be integrated with it. Revisit if realistic OA workflows demonstrate separately identified operational endpoint contracts that a participant relation cannot carry.

Source6 saved views and cross-layer Traceability — 2026-09-06

Problem: saved selective views need explicit inclusion intent without changing semantic objects, and a Traceability view already displays both OA and SA. Applying ordinary layer filtering to it would silently remove existing counterpart edges.

Decision: retain same-layer admission for ordinary diagrams, but allow both-layer edge, category and work-context references in Traceability. Shared projection and validation choose the cross-layer mode together; selectors expose both layers. Default options preserve prior visibility. Categories are independent Work/Participant families; explicit empty selectors mean none, never a silent reset to All. A document-revision semantic index is reused by canvas projections and invalidated on accepted changes/Undo/Redo. New source6 fields and kinds cannot enter frozen1–5 input contracts.

Alternatives rejected: filtering every view by its labelled layer loses existing Traceability content; ignoring layer validation everywhere hides mistaken references; serializing temporary GUI filters breaks source/API parity. Revisit if native workflows or cross-layer regression evidence exposes ambiguity. Current implementation is pending integrated tests and native acceptance, not an established release result.

Basic canvas authoring — 2026-09-07

The user rejected the large horizontal creation row. Actual installed Capella 7.1 inspection supports a compact contextual side palette and direct label editing. Select an explicitly expandable palette, tool → point → inline name creation, F2 rename and explicit participant allocation. Keep draft phases from changing canvas geometry; retain atomic commands and guarded recovery. Context-only creation hides the primary action, and a permanently expanded catalogue repeats the original problem. Evidence, alternatives and acceptance criteria. This is a selected design under implementation, not a native acceptance claim.

Behavior transition destination context — 2026-09-06

Native reverse scenario Apply selected a dependency and inserted five overlapping behavior placements into an unrelated architecture view. Core transition correctness did not make that presentation useful. Select the counterpart of the explicit request root and resolve its nearest scenario/process/chain/state owner. Without an explicit destination diagram, keep the exact core candidate and open Behavior; preserve unrelated architecture views. Retain ordinary architecture transition placement and honor explicit diagram choices.

Automatically creating another architecture view would retain the wrong editing workspace and introduce unrequested model state. Merely navigating to Behavior after adding placements would conceal the presentation damage. Both alternatives are rejected. The selected correction retains one source transaction and Undo operation and guards stale canvas events. Revisit if mixed-root requests or realistic explicit destination workflows require a separate user choice; do not infer such a choice from dependency ordering. Test/build/native acceptance is recorded separately in release-behavior-transition-context-20260906.md.