Arcadia Studio OA / SA Language and Editing Contract

1. Scope and conformance

This specification defines the shared Operational Analysis (OA) and System Analysis (SA) model, its textual language, graphical editing obligations, validation, persistence, and explicit migration from versions 1 and 2. MUST, MUST NOT, and MAY indicate requirements, prohibitions, and permitted choices.

Schema 3 introduces typed function and component ports, required functional exchange endpoints, independently oriented boundary exchanges, and explicit PortAllocation relations. First-release scenario/state additions remain in scope; this schema change does not declare native acceptance or the wider release complete. The preserved schema-2 reader validates the original contract before migration.

OA describes stakeholders, operational work and needs. SA describes the selected system boundary, external actors, functions, services and expected behavior. SA permits at most one System of Interest; its absence is an incomplete-model warning when other SA elements exist. The SA System MUST NOT contain internal components. Functional decomposition is independent of that structural boundary. Logical Architecture, Physical Architecture, deployment, Capella file interchange, and executable behavioral simulation are outside this specification. This independent language does not claim complete Arcadia, Eclipse Capella, or SysML conformance.

An implementation conforms only when each supported field and relationship is reachable in both graphical and textual editing, preserves identity through save/open and undo, and uses the same structural validation. Merely displaying a name or storing an opaque payload does not establish graphical support. Actual verification evidence is separate from this contract.

2. One authoritative model

A Project stores schema_version (3), id, alias, name, description, and maps named elements, relations, diagrams, artifact_links, and traces. Each map is keyed by the UUID contained in its record. Duplicate map keys and mismatching keys/identities are errors.

All objects share one UUID and alias namespace: Project, Element, Relation, Diagram, NodePlacement, ArtifactLink, and Trace. UUIDs are durable identity; aliases are durable, editable source labels. Display-name changes MUST NOT regenerate existing aliases. Different objects MAY have the same display name.

Every Element has id, alias, name, description, parent (optional element reference), and a typed body. Its kind and OA/SA layer are derived from its body. A Relation has id, alias, name, description, and a typed body; it has no independently editable kind tag that can disagree with its payload.

Diagram placement does not determine semantic ownership. NodePlacement records belong to diagrams and reference semantic elements. Multiple diagrams can show the same element with independent placement and collapse state. Within one diagram, each element appears at most once.

All stored strings MUST contain only XML 1.0 characters: U+0009, U+000A, U+000D, U+0020–U+D7FF, U+E000–U+FFFD, or U+10000–U+10FFFF. Strings are not trimmed or Unicode-normalized. Escaping a forbidden character does not permit it. Coordinates and sizes are finite IEEE-754 binary32 values with absolute value at most 1000000. Width and height MUST be positive. Signed zero and subnormal coordinates are retained.

3. Element declarations and typed fields

Each element declaration starts with its layer and kind, for example oa_activity or sa_function. Every element body accepts description (default "") and parent (default none for a document-level declaration, or its lexical element owner when nested; section 6.2). The table lists all additional fields. ref means @alias; ref? also accepts none. Lists preserve order. Unknown or duplicate fields are errors.

The explicit state kind field MUST agree with its declaration keyword. u32 is an integer from 0 through 4294967295. A DataField's maximum MUST be at least its minimum; none means unbounded. Primitive TypeRefs are Boolean, Integer, Real, and String. A named TypeRef uses a DataType reference. An Enumeration contains unique string literals. For example:

definition { Enumeration { literals ["Clear", "Fog"]; }; };
type_ref { Named @weather_classification; };

These are typed constructors with named fields, not embedded JSON documents. Constructor field names and enum spellings are case-sensitive. When replacing a constructor, all of its fields MUST be supplied; the containing declaration defaults do not silently fill a different constructor's missing fields. During schema-2 compatibility, the new Exchange fields message_kind, reply_to and values are exceptions: omitted values hydrate as Asynchronous, none and [] respectively. Canonical output writes them explicitly. This preserves older schema-2 source/JSON without inventing call correlation or value annotations. It is not a rule for an unspecified future schema.

For example, body { Action { action @assess; lifeline @operator_line; }; }; selects an Action occurrence. Processes and functional chains contain Exchange, Action, Control and SequenceReference occurrences. Process/chain Actions are contextual work contributions and MUST have lifeline none. A Control or SequenceReference MUST belong directly to a Process or FunctionalChain, not a Scenario. Scenarios contain Exchange, Action, State, Fragment, Branch and ScenarioUse occurrences according to their enclosing ownership rules. Each listed occurrence belongs to its enclosing sequence or branch through parent. A Branch belongs to a Fragment; the Fragment's branches list references the branches it owns.

An exchange and an occurrence of that exchange have different identities. Repeating an exchange requires distinct occurrence records. Repeating one occurrence identity within an ordered list is invalid. Conditions, guards, entry/exit/do text, and constraint expressions are descriptive strings; this version does not parse or execute them as a programming language.

4. Containment, allocation, and relationships

Containment MUST be acyclic and stay within one layer. Entities may contain entities, actors, and roles. Actors are not structural containers. Activities contain activities; functions contain functions. Capability grouping uses same-layer capability parents; it does not mean inheritance or inclusion. Operational and system missions are root semantic records; they do not own capabilities by containment. MissionCapability expresses that association. DataFields belong to ExchangeItems or Record DataTypes. Preserved generic ports belong to participants or work. Lifelines belong to scenarios. State-machine ownership uses participant → machine → region → state/mode; a state or mode can contain a nested region. All other state vertices belong to Regions as well. Events are root semantic records and do not acquire a machine owner when referenced.

DataFields, ports, lifelines, occurrences, Regions and all state vertices require an owner. An unowned StateMachine can be saved as incomplete work and produces a warning. The System cannot own internal components. The present Studio profile does not decompose SA Actors.

All relations have a header identity, alias, display name, optional description (default ""), and required source and target references. Their kind is the declaration keyword:

Relation endpoints and carried ExchangeItems stay in the same layer. Parallel exchanges with distinct identities are permitted. Self-relations are invalid except for a state transition that returns to its source state.

Direct Allocation has at most one performer per leaf. Role sharing is a different relationship: several OA participants can realize a Role. A direct allocation inconsistent with its role's realized performers produces an advisory warning; it does not prevent saving the model. Shared roles do not imply a unique performer. Allocation of a non-leaf work element is invalid. A computed graphical summary of its allocated leaves MUST NOT create an extra semantic allocation.

Typed function ports belong directly to SA Functions. FunctionOutput declares outgoing_items; FunctionInput declares incoming_items. The lists contain distinct same-layer ExchangeItem references. A functional exchange MUST reference output/input ports owned by its respective functions, and each carried item MUST fit both declarations. Empty declarations accept no items. Item compatibility is identity equality; future specialization is not inferred from names. Port declarations remain independent of incident exchanges after creation.

A Component contract belongs to an SA System or SystemActor and stores kind (Standard or Flow) and orientation (Unset, In, Out, InOut). Standard requires Unset. Flow Unset is an incomplete draft, not InOut. Typed component connections require matching kinds: Standard/Flow mismatch is an error. Standard connections normally use oriented false; directional Flow connections use true. Boundary orientation is separate from endpoint kind and orientation. Oriented Flow endpoints permit Out at source and In at target; unoriented Flow endpoints must permit at least one communication direction.

Provided/required interfaces are separate identified relations. A Standard partner satisfies a requirement by providing the identical interface; stored source/target order does not infer service roles. Component carried items must fit the declared interface-item union when explicit declarations exist. An explicitly empty interface is not a wildcard. Missing declarations and unsatisfied required interfaces produce located completeness warnings.

PortAllocation relates a Component port to a typed function port only when that function has an actual Allocation to the component owner. Standard may allocate either function direction; Flow directions must agree. A typed ExchangeAllocation requires both corresponding PortAllocations and compatible carried items. Unoriented boundary exchanges allow reversed correspondence. Visual allocation nesting is never evidence of a stored allocation relation.

Legacy requires legacy { direction ...; interface ...; }. It preserves generic direction/interface data and emits a located compatibility warning. It is an explicit compatibility constructor in JSON/source; ordinary creation pickers do not offer it. Resolution to a typed SA contract retains this record without treating it as another active constraint. OA generic ports remain Legacy; OA Interactions stay activity-to-activity without function ports. Deleting a referenced legacy interface clears that optional live reference.

A source-3 functional exchange MUST specify both port aliases; the parser does not create endpoints. Graphical/command FE creation plans ports atomically, using unique compatible typed-port reuse or deterministic new endpoints. Port deletion cascades to incident FEs; FE deletion retains independent ports.

For example:

arcadia 3;
project ports_example "Typed function contract" {
    sa_function send "Send" {}
    sa_function receive "Receive" {}
    sa_exchange_item payload "Payload" {}
    sa_interface old_service "Preserved service" { items [@payload]; }
    sa_port output "Output" {
        parent @send;
        contract { FunctionOutput { outgoing_items [@payload]; }; };
    }
    sa_port input "Input" {
        parent @receive;
        contract { FunctionInput { incoming_items [@payload]; }; };
    }
    functional_exchange message "Message" {
        source @send; target @receive;
        source_port @output; target_port @input; items [@payload];
    }
    sa_port preserved "Unresolved original" {
        parent @send; contract Legacy;
        legacy { direction InOut; interface @old_service; };
    }

An exclusive region has at most one initial state. Missing initial state is a completeness warning. Initial states have no incoming transitions and at most one outgoing transition; their outgoing transition has no trigger/guard. Final states have no outgoing transitions. Mixing State and Mode entries is permitted by this Studio profile. StateAction links provide typed work references alongside the descriptive entry/exit/do strings.

sa_event timeout "Recovery timeout" {
    body { Time { kind After; expression "30 s"; }; };
}
sa_event recovered "Pressure recovered" {
    body { Change { expression "pressure > 4 && status == \"Ready\""; }; };
}

5. Diagrams, artifacts, and cross-layer traceability

diagram has name, identity, alias, description, layer (Oa by default), projection (Overview by default), and routes (empty list by default). The string projections are Overview, Decomposition, Allocation, FunctionalDataflow, Capabilities, and Traceability. StateMachine is a payload constructor with one required machine reference. Traceability diagrams can show both layers; other diagrams show their chosen layer.

Allocation is an architecture view: it shows participants and work, nests allocated work under its performer, and displays interactions, functional exchanges and boundary exchanges. FunctionalDataflow shows the work hierarchy and its exchanges. Capabilities shows participants, roles, missions and capabilities with their involvement, exploitation, include, extend and generalization links. Decomposition and Overview retain general containment; Overview also exposes all relationships. These string projections hide inapplicable placements without deleting them or changing semantic records.

A StateMachine projection MUST reference an existing StateMachine in the diagram's layer. Its placements MUST refer to that machine, its Regions, or its state vertices, including nested Regions and vertices. Events, other machines and their members, and unrelated semantic elements are not valid placements in this view. Empty and partial state views are valid; neither creating nor reading a view synthesizes semantic elements or placements. Changing an existing diagram to StateMachine, or changing its machine, MUST remove or relocate incompatible placements in the same transaction. Context errors use state_diagram_context; incompatible placements use state_diagram_member. Neither case silently hides invalid members.

This complete source example places one state from an existing machine:

arcadia 3;
project operating "Operating modes" {
    oa_entity crew "Crew" {}
    oa_state_machine modes "Modes" { parent @crew; }
    oa_region main "Main region" { parent @modes; }
    oa_state ready "Ready" { parent @main; }
    diagram mode_view "Operating modes" {
        layer Oa;
        projection { StateMachine { machine @modes; }; };
    }
    node ready_view { diagram @mode_view; element @ready; }
}

The JSON projection is {"StateMachine":{"machine":"11111111-1111-4111-8111-111111111111"}}, where the UUID is the referenced machine's identity. A bare "StateMachine", a missing or null machine, an invalid UUID, or additional payload fields is malformed. Existing projections retain their string representation, for example "Overview" in JSON and projection Overview; in source.

Ports are boundary anchors of visible owners, with their existing semantic identity. An explicitly placed port is not rendered as a separate large node. Functional exchanges use their declared source/target ports; boundary exchanges attach to their participant ports even if those ports have no separate placement. Collapsing an owner hides its interior; projected links may terminate at a visible ancestor without creating a new port or exchange.

node has an alias and identity but no display-name string. Required fields are diagram and element references. Optional fields are position (record with x/y, default 0/0), size (width/height, default 224/94), and collapsed (false), and port_anchors (empty list). Node identity is independent of its semantic element. Coordinates are absolute diagram coordinates. Placement does not alter parent, allocation, or realization. Hiding an element from a diagram must remain distinguishable from deleting it from the model. Changing a node's diagram preserves the placement identity, alias, coordinates, size, collapse state, manual port anchors, and attached artifacts. The destination must accept the element's layer, satisfy StateMachine membership when applicable, and must not already contain another placement of that element.

Each port_anchors entry is a PortAnchor record with required port reference, side (Left, Right, Top, or Bottom), and offset (finite binary32 from 0 through 1). It has no separate identity or alias. The port MUST be an existing Port directly owned by the placement's element. A port MAY have one manual anchor per placement; different diagrams MAY position it independently. List order is preserved but has no positional meaning.

offset measures a fraction of the complete projected owner edge, from top on Left/Right or from left on Top/Bottom. Zero and one denote its corners. The side is presentation data and MUST NOT change the port's contract, orientation, ownership, allocations, or connected exchanges. Absent anchors use automatic positioning. Empty lists are omitted in canonical JSON/source; earlier schema-3 input without this field hydrates as [].

node actor_view {
    diagram @architecture; element @vessel;
    port_anchors [{ port @communication; side Top; offset 0.25; }];
}

SetPortAnchor { diagram, node, anchor } upserts by port identity and retains unrelated entries. RemovePortAnchor { diagram, node, port } restores automatic positioning; it is a no-op only for an existing direct child port of that placement. Unknown fields, duplicate port references, non-port or foreign-owner references, and invalid offsets are structural errors. Each anchor counts as one record against ParseLimits.max_records.

These commands use the same atomic history, conditional REST transactions, and source writeback as other presentation edits. Source references resolve across files, and anchor comments follow port identity. Reidentifying a port updates anchor references; deleting it removes its anchors. Reparenting MUST repair old-owner anchors in the same transaction, for example by removing them before the Reparent command. Moving, resizing, arranging, or folding an owner retains its authored sides and fractions. Frozen schema-1/schema-2 readers do not accept port_anchors; their explicit migration supplies an empty list.

Each routes entry is an EdgeRoute record with a required edge reference to an existing Relation or Trace, waypoints (default []), and label (default none). Route records have no separate UUID or alias. An edge occurs at most once in a diagram's route list; different diagrams MAY store independent routes for the same edge. List order and explicit empty entries are retained by source and JSON round trips, although list order has no routing meaning. Edges need not currently be visible in their diagram.

routes [
    { edge @report_exchange;
      waypoints [{ x 420; y 260; }, { x 690; y 260; }];
      label { fraction 0.55; offset { x 0; y -16; }; };
    }
];

Waypoints are pinned absolute diagram positions in source-to-target traversal order; at most 128 are allowed per edge. Computed endpoints and automatic elbows MUST NOT be persisted as authored waypoints. A label record requires both fraction (finite binary32 from 0 through 1, measured along the computed polyline's arc length) and offset (a relative x/y diagram displacement). All position/displacement components obey the coordinate bounds in section 2. An absent label uses automatic placement. Unknown fields, missing required nested fields, duplicate route edges, non-edge references and invalid numbers are structural errors. A pinned point that obstructs routing remains stored; geometric routing difficulty is reported separately from structural validity. Each EdgeRoute counts as one record against ParseLimits.max_records; pinned points are bounded by the per-route limit and aggregate input byte limits.

SetEdgeRoute { diagram, route } upserts an entry by edge identity, retaining the order and contents of unrelated entries. RemoveEdgeRoute { diagram, edge } removes it; removing an absent entry is a no-op for an existing diagram and edge. The latter is the Reset routing operation. Either command participates in the same atomic transactions, validation and undo as other model edits. Deleting a relation or trace removes its routes in every diagram; reidentifying it updates route references without changing geometry. Folding, hiding, changing projection or relocating placements MUST NOT erase routing metadata. Group movement translates pins when both actual endpoint owners move by the same delta; label offsets remain relative. Raw EditNode and source position edits are exact record edits and do not implicitly translate pins.

This is an additive schema-3 field. Earlier schema-3 JSON/source that omits routes loads as an empty list. Frozen schema-1 and schema-2 readers do not accept this new field; migration creates empty route lists. Source projects keep routes in their owning diagram declaration/file, resolve edge @alias across files, and retain route-entry comments by referenced edge identity when entries are reordered. The existing REST transaction endpoint accepts the same externally tagged command records with UUID references and conditional ETags; no separate routing endpoint or UI-only routing model exists.

artifact has name, identity, alias, description, required owner ref, relation (References, Satisfies, Verifies, Implements, DerivedFrom; default References), uri (default empty), revision (optional string), and fragment (optional string). The two optional strings default to none. URI must be nonempty, have no whitespace/backslash/control characters, and use valid percent escapes. The owner is another existing model object. Validation MUST NOT fetch the URI. Revision and fragment are retained verbatim.

trace has name, identity, alias, description, required oa and sa endpoint references, kind (default Refinement), and baseline (default none). Endpoints are canonical: SA realizes OA, regardless of which side initiated creation. Trace does not change endpoint identity or containment. Multiple distinct counterparts are permitted; duplicate endpoint/kind triples are invalid.

A nonempty baseline is { oa { name "..."; description "..."; }; sa { name "..."; description "..."; }; }. It records last-reviewed names and descriptions, not a full structural snapshot. Implementations MUST NOT present it as structural synchronization or a lossless inverse transition. Explicit counterpart creation, linking, comparison, and reviewed property update may start in either layer. Ordinary edits MUST NOT automatically overwrite the counterpart. Deletion MUST NOT silently cascade across layers.

Operational Capability normally creates a System Capability. Operational Mission and System Mission are default counterparts in both directions and use Mission traces. An explicit Operational Capability ↔ System Mission mapping remains supported with a Manual trace; a uniquely linked such counterpart is reused instead of silently creating a different mapping. Required/subtree process and chain transitions include their contextual links, owned contributions and referenced dependencies. New process/chain contribution mappings use Sequence traces; older Scenario-kind occurrence mappings remain accepted. The current name/description baseline does not reconcile later topology changes.

Name and description are compared independently against each endpoint's last-reviewed baseline. An unchanged source MUST NOT overwrite an accepted different target value. A source-only change proposes an update; different changes on both sides require an explicit decision to take the source, keep the target, or enter a merged value. An explicit decision records both current values as reviewed, even when they differ. A target-only edit is preserved without advancing that field's baseline, so it remains eligible to propagate in the reverse direction. Equal current values can be recorded as converged.

6. Text grammar and resolution

The input is UTF-8 without a byte-order mark. LF, CR, space, and tab separate tokens. // starts a comment through the next LF or end of input. Quoted strings use JSON string escaping, including \n, \r, \t, \\, and Unicode escapes. Literal unescaped newlines inside strings are invalid. Numbers use JSON decimal/exponent syntax; NaN, infinity, hexadecimal numbers, leading plus signs, and leading zeroes are invalid.

Aliases match [A-Za-z_][A-Za-z0-9_]*. The following aliases are reserved: arcadia, project, id, oa, sa, element, relation, diagram, node, artifact, trace, body, alias, name, description, parent, from, to, entity, actor, activity, capability, process, allocation, interaction, contribution, realization, position, steps, true, false, null. Other field/constructor spellings can be used in alias positions because references begin with @.

The grammar below uses * for repetition and ? for optional syntax. element-kind and relation-kind are exactly the corresponding declaration keywords listed above. Typed field sets and enum constructors are closed by sections 3–5.

document    = "arcadia" "3" ";" project
project     = "project" alias string identity? "{" project-entry* "}"
project-entry = "description" string ";" | declaration
declaration = element
            | (relation-kind | "diagram" | "artifact" | "trace")
              alias string identity? fields
            | "node" alias identity? fields
element     = element-kind alias string identity? element-body
element-body = "{" (field-name value ";" | element)* "}"
identity    = "id" uuid-string
fields      = "{" (field-name value ";")* "}"
value       = string | number | "true" | "false" | "none"
            | enum-word | "@" alias | list | fields
list        = "[" (value ("," value)*)? "]"

The project description defaults to empty and may appear once. There is no semicolon after a declaration or project closing brace. Every field inside a record ends with a semicolon, including fields whose values are nested records. Trailing list commas are invalid. Fields may appear in any order.

UUID strings use 8-4-4-4-12 hexadecimal spelling, with uppercase or lowercase hexadecimal accepted. Canonical output uses lowercase. Omitting an identity creates a fresh UUID for that parse. After Apply, accepted source includes the generated identity. Authors must keep identity clauses to preserve existing objects across subsequent edits.

All declaration aliases are collected before references resolve, so forward references are legal, including references to nodes and diagrams. Unknown @alias values are errors at their reference occurrence. Quoted UUIDs and bare words cannot substitute for reference-valued fields. Alias resolution produces UUID references; the alias itself remains stored on its declaration. Changing an alias in source requires updating its uses. Display names never resolve references.

Unknown fields, duplicate fields, incompatible constructor payloads, unsupported enum spellings, duplicate aliases/identities, and structural validation errors reject the entire candidate. No declaration silently replaces another. Ordinary string fields require quoted strings and cannot contain an unquoted @alias reference. Enum fields require unquoted named values or their typed constructor records. Typed values MUST NOT nest more than 64 levels; malformed deeply nested drafts produce a diagnostic instead of exhausting the parser stack.

arcadia 3;
project rescue "Rescue" id "00000000-0000-4000-8000-000000000001" {
    description "Operational model";
    include "oa/participants.arcadia";
    include "oa/activities/activity_respond.arcadia";
    include "views/diagram_operational.arcadia";
}

sa_actor harbor "Harbor operator" {
    sa_port radio "Radio" {
        contract { Component { kind Standard; orientation Unset; }; };
    }
}

7. Canonical output and source tooling

For every structurally valid Project P, parsing its canonical output MUST reproduce P, and canonicalizing that result MUST be idempotent:

parse(format(P)) == P
format(parse(format(P))) == format(P)

Equality includes all persistent fields, stored aliases, body variants, references, placements, artifacts, trace baselines, and ordered occurrences. Map order is irrelevant. The writer preserves signed coordinate zero and emits decimals that recover the original binary32 value.

Canonical output uses LF, four-space indentation, explicit identities, defaults, and JSON-escaped strings. Elements are emitted in UUID order, then relations; diagrams and their nodes follow, then artifacts, then traces. Fields use deterministic name order. Output ends with LF. Alias values come from the model, never from regenerating display names.

Comments and input whitespace are lexical trivia to the canonical writer. Canonical export does not preserve them. The source-project editor and compiler preserve authored comments and whitespace on Apply while inserting missing identities. Explicit canonical export remains a separate operation. Project update/export distinctions are described below. Camera position, selection, source cursor, and undo history are not stored model fields. Layout, collapse state, and manual port anchors inside NodePlacement are model data.

The pure format_bundle exporter uses the same typed declaration writer as format. It creates a small entry file, layer/category modules, separate activity/function roots and behavior contexts, and separate diagrams with their placements. Ports follow their owner; relations follow their source/context. Module names derive from persistent aliases, not display names or UUID chunks. Declarations are ordered by semantic ancestry and alias, with owners before descendants. Case-colliding generated file names receive deterministic numeric suffixes. When more than 240 distinct modules would be produced, aggregate folders consolidate into category modules to avoid thousands of tiny files. For every valid P, compile_bundle(format_bundle(P)).decoded.project == P when the caller supplies sufficient admission budgets.

update_bundle(compiled, P, limits) is a core source update facility. It checks that the compiled document/index/model snapshot still agrees, preserves untouched document bytes, and recompiles the result before returning it. Flat declarations retain their document-level position and file when reparented. Nested declarations move into their new semantic owner's body, across files if necessary; becoming a root moves them to document level. New children prefer their owner's body. New roots use canonical module rules and add an explicit entry include. Removed declarations do not delete source files. Alias changes also update declarations containing references to that alias. Invalid or stale updates return errors without mutating the input workspace.

A moved declaration carries its contiguous leading comment block and comments following its closing brace on the same line. A blank line separates a comment block from the following declaration; such gap comments stay in the enclosing scope. Comments trailing a preceding field likewise stay with that field. Deletion retains annotations in the nearest surviving original scope and separates them from adjacent declarations with blank lines. Surviving descendants move with an enclosing declaration unless their own semantic parent changes; independent parent and child moves are resolved together. Leading whitespace adjusts to the destination scope; other token spelling remains authored.

Updates MUST NOT canonicalize surviving declarations in full. Header, field and nested value positions are derived from the existing syntax parser. Unchanged fields retain their exact bytes, including field order, omitted defaults, number and string spelling, comments, indentation and line endings. Changed literals and references replace only the required tokens; a reference with comments between @ and its alias retains those comments. A previously omitted default is inserted only if its semantic value changes. New fields use the existing record's indentation and line-ending style without reformatting its other fields.

A constructor tag change retains shared nested fields in place. Removed fields, constructors and declarations remove syntax tokens, retaining their comments and whitespace as annotations in the enclosing record or file. A complete value shape replacement likewise retains the old value's comments beside the new value. The updater does not invent an engineering interpretation for orphaned comments.

List entries use stable referenced UUIDs, message-value field references or lifeline-binding referenced identities when these keys are unique. Literal entries use their literal value. Retained entries carry their authored value text and inter-separator comments when reordered. Trivia after a preceding comma belongs to the following entry; trivia before the next comma belongs to the preceding entry. Separators are reconstructed before trailing line comments so that the result remains valid syntax. Unkeyed or duplicate-key lists use source positions. Removed-entry comments remain as annotations in the list; newly added entries receive formatted syntax. These rules preserve comments without silently attaching new semantic identity to an ambiguous list entry.

Retained declaration UUIDs remain unchanged unless explicitly edited. Source ownership remains unchanged except for the nested relocation rules above. Records match by UUID, not display name or alias. The model-only update_bundle treats an explicit UUID replacement as removal and creation. The desktop instead uses update_bundle_with_identity_map with the surviving-record provenance from prepare_command: explicit identity edits and sequential identity swaps MUST preserve each original declaration's owning file and attached source trivia, unless the same edit changes its nested semantic parent and requires relocation. New records have no original identity mapping. The mapping MUST be injective, refer to existing records and preserve record classes. The result is recompiled, reindexed and checked for equality with the requested model before return. Equal model values do not imply a no-op if command provenance removes or replaces a declaration; the resulting model and source bundle together determine whether the accepted state changed. Source changes needed for undo are workspace history data; callers should retain complete compiled workspace snapshots rather than infer past omission/layout choices from a model-only undo.

Canonical modular export is a distinct, explicit operation and does not promise original comment/layout preservation. The native editor integrates per-file drafts and source-project saves as specified below. The pure compiler performs no filesystem access. REST source-project endpoints exchange the accepted bundle with all its files. One revision and ETag protect the model and source together, including source-only comment edits; stored envelopes contain both. Canonical source endpoints remain explicit model interchange. The precise transport, admission and persistence contract is in api.rst.

parse returns a complete structurally validated candidate or error diagnostics and no model. Engineering warnings alone MUST NOT reject a valid candidate. Parsing may stop at the first syntax/conversion error. Diagnostics contain severity (Error or Warning), a code identifying the diagnostic category, optional object UUID and field path, a message, one-based line and Unicode-scalar column, and a half-open UTF-8 byte Span. Tabs count as one scalar; LF advances the line. Structural errors and engineering warnings point to a relevant declaration or field when available. Clients MUST use severity/code rather than parse the human message; diagnostic wording is not a stable machine API.

parse_limited and decode_limited accept caller admission budgets for input bytes, graph objects, total persistent records and ordered step references. Counts MUST be checked before expensive structural validation; migration budgets include generated records before migration. Exceeding a budget does not mutate the model. Admission limits are host capacity policy, not hidden restrictions on otherwise valid language semantics; ordinary parse has no such model size policy. The REST service's fixed policy is specified in api.rst.

tokenize is tolerant: it covers every input byte with nonoverlapping TokenSpans, including incomplete strings and invalid characters. Token classes are Keyword, Identifier, String, Number, Comment, Punctuation, Whitespace, and Error. @ is punctuation followed by the referenced alias token. lint returns syntax, structural and engineering warning diagnostics for the current draft without adopting a model. A valid unallocated SA function, for example, can report missing System and allocation warnings before Apply. analyze combines tokens, diagnostics, and declaration spans with alias, optional explicit UUID, and declaration kind. A malformed later declaration does not erase earlier declaration spans. None of these APIs mutates a session.

8. Graphical parity and transactional editing

The graphical editor MUST expose all persistent properties through typed controls, including optional references, lists, variant constructors, aliases, IDs, nested parent changes, diagram placements, artifact metadata, and trace baselines. Inspector controls may provide operations unavailable as a canvas gesture. Exact strings, including tabs and line breaks in names, must remain editable through an appropriate escaped-string input when ordinary widgets cannot represent them.

A move into a functional parent, an allocation onto a performer, and a diagram placement move are different transactions. The UI MUST identify which operation will occur. Reparenting work must not silently change its performer. A computed parent summary must remain distinguishable from direct allocation. A collapse operation hides presentation detail without deleting the children.

Applying a reachable source bundle is one model transaction. Graphical edits update its owning declarations through the source-preserving updater. Both paths validate their candidate and model/source equality before adoption; failure preserves the committed model, save baseline, and history. Incomplete but structurally safe references and coverage gaps produce warnings that allow continued authoring and saving.

Source and property drafts contribute to unsaved-work state. Invalid drafts MUST NOT be replaced by generated text or lost on ordinary navigation. Undoing source-buffer edits and undoing committed model changes are distinct operations. Successful source Apply creates one model-history entry. Undo/redo restores the full stored model and exact accepted source bundle, including aliases, trace links, occurrence identity, comments and file ownership. Each open file retains its own unapplied draft across file navigation. Located lint diagnostics refer to the raw draft bytes rather than an identity-stabilized intermediate. Property editing MUST NOT silently discard a pending source draft.

Changing a graphical UUID must atomically update map keys and every reference. Alias changes preserve UUID identity. Deletion must account for owned elements, incident relationships, ordered occurrences, and diagram placements without leaving dangling references. Deleting a sequence does not delete the semantic exchanges it references. Cross-layer counterparts are not owned descendants. Text edits describe a complete candidate and must remove or repair dependencies explicitly before Apply succeeds.

9. Persistence and explicit migration

Loading detects JSON from its first non-whitespace {; other input is parsed as Arcadia source regardless of filename. Saving an .arcadia suffix uses the accepted V3 source bundle (arcadia 3); other suffixes use V3 JSON. Both forms preserve the same complete model. JSON rejects unknown fields throughout typed payloads, duplicate maps, unsupported versions, and structural errors.

Native source Save All checks the original contents of observed dependencies before staging writes. Existing target files are replaced individually and the entry is installed last. A transaction journal records originals and intended writes; explicit recovery restores originals only when current bytes match a known transaction state. Unrelated external contents MUST NOT be overwritten by recovery. Missing entry files and lint updates MUST NOT hide a detected pending-recovery action. This is not cross-process compare-and-swap or atomic multi-file visibility. Save failures retain the accepted model and drafts. Detached dirty buffers MUST be reattached or reverted before source saving; JSON export does not replace the source project's saved baseline or location.

The frozen schema-2 reader retains staged compatibility defaults. Old Scenario bodies without a viewpoint retain MixedLegacy, and old Exchange occurrence bodies without message_kind, reply_to or values retain Asynchronous, none and []. Old StateTransition bodies without transition_kind, triggers or effects retain External, [] and []; existing trigger, guard and effect strings are preserved exactly. Source declaration defaults and JSON compatibility defaults MUST agree; no event or work reference is inferred from legacy prose. This compatibility applies equally to source and JSON. It adds explicit defaults without changing any prior identity, name, reference, order, geometry, artifact or trace field. The original V2 golden source/JSON in crates/oa-core/tests/fixtures MUST NOT be regenerated from the newer demo; they verify that every old persistent field survives. Canonical output writes the added defaults through the explicit schema-3 migration.

The V2 adapter preserves every original identity, alias, prose, parent, placement, trace and artifact. Generic ports become Legacy with their original direction/interface record. Existing FE endpoint IDs remain unchanged. For only a missing endpoint it creates an item-bearing FunctionOutput/Input owned by the already specified function, using UUID v5 in the project namespace with v2-fe-port:<fe-id>:source or v2-fe-port:<fe-id>:target. Every identity category is checked for collision; collisions are located errors, never overwrites. New aliases follow the deterministic collision-free alias convention. Every old boundary exchange receives oriented true; no PortAllocation is inferred.

decode_with_report, load_with_report and their limited/source variants return the model plus a migration report containing original unresolved port IDs, required resolutions, generated endpoint IDs/aliases/owners, and boundary orientation defaults. REST import, replacement, candidate validation and project snapshots surface the same report. Opening an old server envelope preserves its resource ID/revision and bytes; the next explicit edit writes schema 3. Model/source exports contain only the canonical model. Migration reports are transient response metadata, not persisted model facts.

Admission checks account for generated objects and their references before construction. Both the old V2 contract and the resulting V3 graph are validated. Migration itself does not save or increase a stored revision. Canonical second saves are stable. V1 normalization produces the frozen V2 model and then uses this same V2-to-3 stage.

Save validates a snapshot, writes a sibling temporary file, flushes it, and atomically replaces the destination. Failed serialization or validation must not truncate a previous file. External concurrent-writer conflict resolution and crash recovery are outside this storage contract.

Version 1 text and JSON are accepted through an explicit adapter. Migration preserves project, element, and relation UUIDs; names and descriptions; relation endpoints; all coordinates; and exact process exchange order and repetition. Allocation and Interaction remain their corresponding V2 relations. Contribution becomes CapabilityInvolvement; the old Process-to-Capability Realization becomes ChainInvolvement, retaining its ID and name.

Legacy positions become nodes in one OA Overview diagram. Each old process step becomes a distinct occurrence element owned by its process. Generated diagram, node, and occurrence identities use UUID v5 with the old Project ID as namespace and deterministic role/index names. If such an identity collides, a deterministic suffix is tried. Reimporting the same fully identified V1 input therefore yields the same V3 result, including repeated occurrences. No System or SA content is invented during an OA-only migration.

V1 source aliases are retained when valid in V2. JSON imports generate the old canonical aliases deterministically. Any alias newly reserved in V2 is changed by a deterministic suffix; aliases were not persistent V1 semantic data. A project alias and aliases for new records are generated without colliding with retained aliases. The existing bundled V1 text and JSON migrate to equal V3 projects. Future versions remain errors until a separate migration exists.

10. Complete authoring example

This document intentionally omits IDs for new authoring. Apply and Save write the assigned UUIDs explicitly.

arcadia 3;
project harbor "Harbor assistance" {
    oa_entity control "Harbor control" {}
    oa_activity assess "Assess assistance" {}
    allocation performs "Performs" {
        source @control;
        target @assess;
    }
    sa_system service "Harbor assistance system" {}
    sa_function evaluate "Evaluate assistance request" {}
    allocation system_performs "Performs" {
        source @service;
        target @evaluate;
    }
    trace assessment_trace "Operational realization" {
        oa @assess;
        sa @evaluate;
        kind Refinement;
    }
    diagram operational_view "Operational allocation" {
        layer Oa;
        projection Allocation;
    }
    node assessment_card {
        diagram @operational_view;
        element @assess;
        position { x 360; y 70; };
    }
}

11. Verification and primary references

cargo test -p oa-core --test language --locked verifies typed round-trips, stable aliases, strict syntax/reference failures, Unicode source spans, deterministic V1 migration, occurrence identity, coordinate bits, persistence, and model-history integration. Core validation and session tests cover domain mutation rules; native UI and API verification are separate evidence.

The research record in docs/research-v2-semantics.md distinguishes method requirements from Studio design choices and links to original UI evidence. The following sources inform this language without extending its scope:

• Arcadia Q&A

• Arcadia language reference

• Capella allocation guide

• Capella iterative transitions

• W3C XML 1.0 characters