Files
ARCADIA-Studio/docs/language.html
T

1553 lines
78 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="utf-8" />
<meta name="generator" content="Docutils 0.23: https://docutils.sourceforge.io/" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Arcadia Studio OA / SA Language and Editing Contract</title>
<style type="text/css">
/* Minimal style sheet for the HTML output of Docutils. */
/* */
/* :Author: Günter Milde, based on html4css1.css by David Goodger */
/* :Id: $Id: minimal.css 10018 2025-03-06 16:19:15Z milde $ */
/* :Copyright: © 2015, 2021 Günter Milde. */
/* :License: Released under the terms of the `2-Clause BSD license`_, */
/* in short: */
/* */
/* Copying and distribution of this file, with or without modification, */
/* are permitted in any medium without royalty provided the copyright */
/* notice and this notice are preserved. */
/* */
/* This file is offered as-is, without any warranty. */
/* */
/* .. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause */
/* This CSS3 stylesheet defines rules for Docutils elements without */
/* HTML equivalent. It is required to make the document semantics visible. */
/* */
/* .. _validates: http://jigsaw.w3.org/css-validator/validator$link */
/* titles */
p.topic-title,
p.admonition-title,
p.system-message-title {
font-weight: bold;
}
p.sidebar-title,
p.rubric {
font-weight: bold;
font-size: larger;
}
p.rubric {
color: maroon;
}
p.subtitle,
p.section-subtitle,
p.sidebar-subtitle {
font-weight: bold;
margin-top: -0.5em;
}
h1 + p.subtitle {
font-size: 1.6em;
}
a.toc-backref {
color: inherit;
text-decoration: none;
}
/* Warnings, Errors */
.system-messages h2,
.system-message-title,
pre.problematic,
span.problematic {
color: red;
}
/* Inline Literals */
.docutils.literal {
font-family: monospace;
white-space: pre-wrap;
}
/* do not wrap at hyphens and similar: */
.literal > span.pre { white-space: nowrap; }
/* keep line-breaks (\n) visible */
.pre-wrap { white-space: pre-wrap; }
/* Lists */
/* compact and simple lists: no margin between items */
.simple li, .simple ul, .simple ol, .simple > li p,
.compact li, .compact ul, .compact ol, .compact > li p,
dl.simple > dd, dl.compact > dd, dl.docinfo > dd {
margin-top: 0;
margin-bottom: 0;
}
/* Nested Paragraphs */
p:first-child { margin-top: 0; }
p:last-child { margin-bottom: 0; }
details > p:last-child { margin-bottom: 1em; }
/* Table of Contents */
.contents ul.auto-toc { /* section numbers present */
list-style-type: none;
}
/* Enumerated Lists */
ol.arabic { list-style: decimal }
ol.loweralpha { list-style: lower-alpha }
ol.upperalpha { list-style: upper-alpha }
ol.lowerroman { list-style: lower-roman }
ol.upperroman { list-style: upper-roman }
/* Definition Lists and Derivatives */
dt .classifier { font-style: italic }
dt .classifier:before {
font-style: normal;
margin: 0.5em;
content: ":";
}
/* Field Lists and similar */
/* bold field name, content starts on the same line */
dl.field-list,
dl.option-list,
dl.docinfo {
display: flow-root;
}
dl.field-list > dt,
dl.option-list > dt,
dl.docinfo > dt {
font-weight: bold;
clear: left;
float: left;
margin: 0;
padding: 0;
padding-right: 0.25em;
}
/* Offset for field content (corresponds to the --field-name-limit option) */
dl.field-list > dd,
dl.option-list > dd,
dl.docinfo > dd {
margin-left: 9em; /* ca. 14 chars in the test examples, fit all Docinfo fields */
}
/* start nested lists on new line */
dd > dl:first-child,
dd > ul:first-child,
dd > ol:first-child {
clear: left;
}
/* start field-body on a new line after long field names */
dl.field-list > dd > *:first-child,
dl.option-list > dd > *:first-child
{
display: inline-block;
width: 100%;
margin: 0;
}
/* Bibliographic Fields (docinfo) */
dl.docinfo pre.address {
font: inherit;
margin: 0;
}
dl.docinfo > dd.authors > p { margin: 0; }
/* Option Lists */
dl.option-list > dt { font-weight: normal; }
span.option { white-space: nowrap; }
/* Footnotes and Citations */
.footnote, .citation { margin: 1em 0; } /* default paragraph skip (Firefox) */
/* hanging indent */
.citation { padding-left: 2em; }
.footnote { padding-left: 1.7em; }
.footnote.superscript { padding-left: 1.0em; }
.citation > .label { margin-left: -2em; }
.footnote > .label { margin-left: -1.7em; }
.footnote.superscript > .label { margin-left: -1.0em; }
.footnote > .label + *,
.citation > .label + * {
display: inline-block;
margin-top: 0;
vertical-align: top;
}
.footnote > .backrefs + *,
.citation > .backrefs + * {
margin-top: 0;
}
.footnote > .label + p, .footnote > .backrefs + p,
.citation > .label + p, .citation > .backrefs + p {
display: inline;
vertical-align: inherit;
}
.backrefs { user-select: none; }
.backrefs > a { font-style: italic; }
/* superscript footnotes */
a[role="doc-noteref"].superscript,
.footnote.superscript > .label,
.footnote.superscript > .backrefs {
vertical-align: super;
font-size: smaller;
line-height: 1;
}
a[role="doc-noteref"].superscript > .fn-bracket,
.footnote.superscript > .label > .fn-bracket {
/* hide brackets in display but leave for copy/paste */
display: inline-block;
width: 0;
overflow: hidden;
}
[role="doc-noteref"].superscript + [role="doc-noteref"].superscript {
padding-left: 0.15em; /* separate consecutive footnote references */
/* TODO: unfortunately, "+" also selects with text between the references. */
}
/* Alignment */
.align-left {
text-align: left;
margin-right: auto;
}
.align-center {
text-align: center;
margin-left: auto;
margin-right: auto;
}
.align-right {
text-align: right;
margin-left: auto;
}
.align-top { vertical-align: top; }
.align-middle { vertical-align: middle; }
.align-bottom { vertical-align: bottom; }
/* reset inner alignment in figures and tables */
figure.align-left, figure.align-right,
table.align-left, table.align-center, table.align-right {
text-align: inherit;
}
/* Text Blocks */
.topic { margin: 1em 2em; }
.sidebar,
.admonition,
.system-message {
margin: 1em 2em;
border: thin solid;
padding: 0.5em 1em;
}
div.line-block { display: block; }
div.line-block div.line-block, pre { margin-left: 2em; }
/* Code line numbers: don't copy with drag-and-drop */
pre.code .ln { display: none; }
pre.code code:before {
content: attr(data-lineno);
font-size: small;
color: gray;
}
/* Tables */
table {
border-collapse: collapse;
}
td, th {
border: thin solid silver;
padding: 0 1ex;
}
.borderless td, .borderless th {
border: 0;
padding: 0;
padding-right: 0.5em /* separate table cells */
}
table > caption, figcaption {
text-align: left;
margin-top: 0.2em;
margin-bottom: 0.2em;
}
table.captionbelow {
caption-side: bottom;
}
/* MathML (see "math.css" for --math-output=HTML) */
math .boldsymbol { font-weight: bold; }
math.boxed, math .boxed {padding: 0.25em; border: thin solid; }
/* style table similar to AMS "align" or "aligned" environment: */
mtable.cases > mtr > mtd { text-align: left; }
mtable.ams-align > mtr > mtd { padding-left: 0; padding-right: 0; }
mtable.ams-align > mtr > mtd:nth-child(2n) { text-align: left; }
mtable.ams-align > mtr > mtd:nth-child(2n+1) { text-align: right; }
mtable.ams-align > mtr > mtd:nth-child(2n+3) { padding-left: 2em; }
.mathscr mi, mi.mathscr {
font-family: STIX, XITSMathJax_Script, rsfs10,
"Asana Math", Garamond, cursive;
}
/* Document Header and Footer */
header { border-bottom: 1px solid black; }
footer { border-top: 1px solid black; }
/* Images are block-level by default in Docutils */
/* New HTML5 block elements: set display for older browsers */
img, svg, header, footer, main, aside, nav, section, figure, video, details {
display: block;
}
svg { width: auto; height: auto; } /* enable scaling of SVG images */
/* inline images */
p img, p svg, p video,
h1 img, h2 img, h3 img, h4 img, h5 img, h6 img,
h1 svg, h2 svg, h3 svg, h4 svg, h5 svg, h6 svg {
display: inline;
}
</style>
<style type="text/css">
/* CSS31_ style sheet for the output of Docutils HTML writers. */
/* Rules for easy reading and pre-defined style variants. */
/* */
/* :Author: Günter Milde, based on html4css1.css by David Goodger */
/* :Id: $Id: plain.css 10079 2025-04-10 12:01:48Z milde $ */
/* :Copyright: © 2015 Günter Milde. */
/* :License: Released under the terms of the `2-Clause BSD license`_, */
/* in short: */
/* */
/* Copying and distribution of this file, with or without modification, */
/* are permitted in any medium without royalty provided the copyright */
/* notice and this notice are preserved. */
/* */
/* This file is offered as-is, without any warranty. */
/* */
/* .. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause */
/* .. _CSS3: https://www.w3.org/Style/CSS/ */
/* Document Structure */
/* ****************** */
/* "page layout" */
body {
margin: 0;
background-color: #dbdbdb;
--field-indent: 9em; /* default indent of fields in field lists */
}
main, footer, header {
line-height:1.6;
/* avoid long lines --> better reading */
/* optimum is 45…75 characters/line <http://webtypography.net/2.1.2> */
/* OTOH: lines should not be too short because of missing hyphenation, */
max-width: 50rem;
padding: 1px 2%; /* 1px on top avoids grey bar above title (mozilla) */
margin: auto;
}
main {
counter-reset: table figure;
background-color: white;
}
footer, header {
font-size: smaller;
padding: 0.5em 2%;
border: none;
}
/* Table of Contents */
ul.auto-toc > li > p {
padding-left: 1em;
text-indent: -1em;
}
nav.contents ul {
padding-left: 1em;
}
main > nav.contents ul ul ul ul:not(.auto-toc) {
list-style-type: '\2B29\ ';
}
main > nav.contents ul ul ul ul ul:not(.auto-toc) {
list-style-type: '\2B1D\ ';
}
/* Transitions */
hr.docutils {
width: 80%;
margin-top: 1em;
margin-bottom: 1em;
clear: both;
}
/* Paragraphs */
/* vertical space (parskip) */
p, ol, ul, dl, li,
.footnote, .citation,
div > math,
table {
margin-top: 0.5em;
margin-bottom: 0.5em;
}
h1, h2, h3, h4, h5, h6,
dd, details > p:last-child {
margin-bottom: 0.5em;
}
/* Lists */
/* ===== */
/* Definition Lists */
/* Indent lists nested in definition lists */
dd > ul:only-child, dd > ol:only-child { padding-left: 1em; }
/* Description Lists */
/* styled like in most dictionaries, encyclopedias etc. */
dl.description {
display: flow-root;
}
dl.description > dt {
font-weight: bold;
clear: left;
float: left;
margin: 0;
padding: 0;
padding-right: 0.3em;
}
dl.description > dd:after {
display: table;
content: "";
clear: left; /* clearfix for empty descriptions */
}
/* Field Lists */
dl.field-list > dd,
dl.docinfo > dd {
margin-left: var(--field-indent); /* adapted in media queries or HTML */
}
/* example for custom field-name width */
dl.field-list.narrow > dd {
--field-indent: 5em;
}
/* run-in: start field-body on same line after long field names */
dl.field-list.run-in > dd p {
display: block;
}
/* Bibliographic Fields */
/* generally, bibliographic fields use dl.docinfo */
/* but dedication and abstract are placed into divs */
div.abstract p.topic-title {
text-align: center;
}
div.dedication {
margin: 2em 5em;
text-align: center;
font-style: italic;
}
div.dedication p.topic-title {
font-style: normal;
}
/* disclosures */
details { padding-left: 1em; }
summary { margin-left: -1em; }
/* Text Blocks */
/* =========== */
/* Literal Blocks */
pre.literal-block, pre.doctest-block,
pre.math, pre.code {
font-family: monospace;
}
/* Block Quotes and Topics */
bockquote { margin: 1em 2em; }
blockquote p.attribution {
text-align: right;
margin-left: 20%;
}
/* Tables */
/* ====== */
/* th { vertical-align: bottom; } */
table tr { text-align: left; }
/* "booktabs" style (no vertical lines) */
table.booktabs {
border: 0;
border-top: 2px solid;
border-bottom: 2px solid;
border-collapse: collapse;
}
table.booktabs * {
border: 0;
}
table.booktabs th {
border-bottom: thin solid;
}
/* numbered tables (counter defined in div.document) */
table.numbered > caption:before {
counter-increment: table;
content: "Table " counter(table) ": ";
font-weight: bold;
}
/* Explicit Markup Blocks */
/* ====================== */
/* Footnotes and Citations */
/* ----------------------- */
/* line on the left */
.footnote-list {
border-left: solid thin;
padding-left: 0.25em;
}
/* Directives */
/* ---------- */
/* Body Elements */
/* ~~~~~~~~~~~~~ */
/* Images and Figures */
/* let content flow to the side of aligned images and figures */
figure.align-left,
img.align-left,
svg.align-left,
video.align-left,
div.align-left,
object.align-left {
clear: left;
float: left;
margin-right: 1em;
}
figure.align-right,
img.align-right,
svg.align-right,
video.align-right,
div.align-right,
object.align-right {
clear: right;
float: right;
margin-left: 1em;
}
/* Stop floating sidebars, images and figures */
h1, h2, h3, h4, footer, header { clear: both; }
/* Numbered figures */
figure.numbered > figcaption > p:before {
counter-increment: figure;
content: "Figure " counter(figure) ": ";
font-weight: bold;
}
/* Admonitions and System Messages */
.caution p.admonition-title,
.attention p.admonition-title,
.danger p.admonition-title,
.error p.admonition-title,
.warning p.admonition-title,
div.error {
color: red;
}
/* Sidebar */
/* Move right. In a layout with fixed margins, */
/* it can be moved into the margin. */
aside.sidebar {
width: 30%;
max-width: 26em;
float: right;
clear: right;
margin-left: 1em;
margin-right: -1%;
background-color: #fffffa;
}
/* Code */
pre.code { padding: 0.7ex }
pre.code, code { background-color: #eeeeee }
/* basic highlighting: for a complete scheme, see */
/* https://docutils.sourceforge.io/sandbox/stylesheets/ */
pre.code .comment, code .comment { color: #5C6576 }
pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold }
pre.code .literal.string, code .literal.string { color: #0C5404 }
pre.code .name.builtin, code .name.builtin { color: #352B84 }
pre.code .deleted, code .deleted { background-color: #DEB0A1}
pre.code .inserted, code .inserted { background-color: #A3D289}
/* Epigraph */
/* Highlights */
/* Pull-Quote */
/* Compound Paragraph */
/* Container */
/* Inline Markup */
/* ============= */
sup, sub { line-height: 0.8; } /* do not add leading for lines with sup/sub */
/* Inline Literals */
/* possible values: normal, nowrap, pre, pre-wrap, pre-line */
/* span.docutils.literal { white-space: pre-wrap; } */
/* Hyperlink References */
a { text-decoration: none; }
/* External Targets */
/* span.target.external */
/* Internal Targets */
/* span.target.internal */
/* Footnote References */
/* a[role="doc-noteref"] */
/* Citation References */
/* a.citation-reference */
</style>
</head>
<body>
<main id="arcadia-studio-oa-sa-language-and-editing-contract">
<h1 class="title">Arcadia Studio OA / SA Language and Editing Contract</h1>
<dl class="docinfo simple">
<dt class="version">Version<span class="colon">:</span></dt>
<dd class="version">2</dd>
<dt class="status">Status<span class="colon">:</span></dt>
<dd class="status">Normative current implementation contract; first-release integration</dd>
<dt class="core-implementation">Core implementation<span class="colon">:</span></dt>
<dd class="core-implementation"><p><span class="docutils literal"><span class="pre">crates/oa-core</span></span></p>
</dd>
<dt class="text-suffix">Text suffix<span class="colon">:</span></dt>
<dd class="text-suffix"><p><span class="docutils literal">.arcadia</span></p>
</dd>
</dl>
<section id="scope-and-conformance">
<h2>1. Scope and conformance</h2>
<p>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 version 1. MUST, MUST NOT,
and MAY indicate requirements, prohibitions, and permitted choices.</p>
<p>The first-release capability/mission, contextual process/chain, typed scenario
and state/event additions
are temporarily integrated under schema 2. This does not declare the first
release complete or waive its remaining scenario, state, data, transition and
usability requirements. A distinct release schema and explicit V2 migration
will be specified after those interfaces are frozen. This document describes
the current implemented records, rather than inventing compatibility rules for
that future schema.</p>
<p>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.</p>
<p>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.</p>
</section>
<section id="one-authoritative-model">
<h2>2. One authoritative model</h2>
<p>A Project stores <span class="docutils literal">schema_version</span> (2), <span class="docutils literal">id</span>, <span class="docutils literal">alias</span>, <span class="docutils literal">name</span>,
<span class="docutils literal">description</span>, and maps named <span class="docutils literal">elements</span>, <span class="docutils literal">relations</span>, <span class="docutils literal">diagrams</span>,
<span class="docutils literal">artifact_links</span>, and <span class="docutils literal">traces</span>. Each map is keyed by the UUID contained in
its record. Duplicate map keys and mismatching keys/identities are errors.</p>
<p>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.</p>
<p>Every Element has <span class="docutils literal">id</span>, <span class="docutils literal">alias</span>, <span class="docutils literal">name</span>, <span class="docutils literal">description</span>, <span class="docutils literal">parent</span>
(optional element reference), and a typed <span class="docutils literal">body</span>. Its kind and OA/SA layer
are derived from its body. A Relation has <span class="docutils literal">id</span>, <span class="docutils literal">alias</span>, <span class="docutils literal">name</span>,
<span class="docutils literal">description</span>, and a typed body; it has no independently editable kind tag
that can disagree with its payload.</p>
<p>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.</p>
<p>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.</p>
</section>
<section id="element-declarations-and-typed-fields">
<h2>3. Element declarations and typed fields</h2>
<p>Each element declaration starts with its layer and kind, for example
<span class="docutils literal">oa_activity</span> or <span class="docutils literal">sa_function</span>. Every element body accepts
<span class="docutils literal">description</span> (default <span class="docutils literal">&quot;&quot;</span>) and <span class="docutils literal">parent</span> (default <span class="docutils literal">none</span>). The table
lists all additional fields. <span class="docutils literal">ref</span> means <span class="docutils literal">&#64;alias</span>; <span class="docutils literal">ref?</span> also accepts
<span class="docutils literal">none</span>. Lists preserve order. Unknown or duplicate fields are errors.</p>
<table>
<caption>Element body field catalog</caption>
<colgroup>
<col style="width: 27.0%" />
<col style="width: 43.0%" />
<col style="width: 30.0%" />
</colgroup>
<thead>
<tr><th class="head"><p>Declarations</p></th>
<th class="head"><p>Additional fields</p></th>
<th class="head"><p>Defaults</p></th>
</tr>
</thead>
<tbody>
<tr><td><p><span class="docutils literal">oa_entity</span>, <span class="docutils literal">oa_actor</span>, <span class="docutils literal">oa_role</span>, <span class="docutils literal">oa_activity</span>, <span class="docutils literal">oa_capability</span>, <span class="docutils literal">oa_mission</span></p></td>
<td><p>None</p></td>
<td><p>Empty body</p></td>
</tr>
<tr><td><p><span class="docutils literal">sa_system</span>, <span class="docutils literal">sa_actor</span>, <span class="docutils literal">sa_function</span>, <span class="docutils literal">sa_capability</span>, <span class="docutils literal">sa_mission</span></p></td>
<td><p>None</p></td>
<td><p>Empty body</p></td>
</tr>
<tr><td><p><span class="docutils literal">oa_process</span>, <span class="docutils literal">sa_functional_chain</span></p></td>
<td><p><span class="docutils literal">steps</span>: occurrence refs</p></td>
<td><p><span class="docutils literal">[]</span></p></td>
</tr>
<tr><td><p><span class="docutils literal">oa_exchange_item</span>, <span class="docutils literal">sa_exchange_item</span></p></td>
<td><p><span class="docutils literal">kind</span>: Information, Material, Energy, Event</p></td>
<td><p>Information</p></td>
</tr>
<tr><td><p><span class="docutils literal">oa_data_type</span>, <span class="docutils literal">sa_data_type</span></p></td>
<td><p><span class="docutils literal">definition</span>: Boolean, Integer, Real, String, Record, or Enumeration constructor</p></td>
<td><p>String</p></td>
</tr>
<tr><td><p><span class="docutils literal">oa_data_field</span>, <span class="docutils literal">sa_data_field</span></p></td>
<td><p><span class="docutils literal">type_ref</span>; <span class="docutils literal">minimum</span>: u32; <span class="docutils literal">maximum</span>: optional u32; <span class="docutils literal">unit</span>: string</p></td>
<td><p>String; 1; 1; <span class="docutils literal">&quot;&quot;</span></p></td>
</tr>
<tr><td><p><span class="docutils literal">oa_interface</span>, <span class="docutils literal">sa_interface</span></p></td>
<td><p><span class="docutils literal">items</span>: exchange-item refs</p></td>
<td><p><span class="docutils literal">[]</span></p></td>
</tr>
<tr><td><p><span class="docutils literal">oa_port</span>, <span class="docutils literal">sa_port</span></p></td>
<td><p><span class="docutils literal">direction</span>: In, Out, InOut; <span class="docutils literal">interface</span>: ref?</p></td>
<td><p>InOut; none</p></td>
</tr>
<tr><td><p><span class="docutils literal">oa_scenario</span>, <span class="docutils literal">sa_scenario</span></p></td>
<td><p><span class="docutils literal">viewpoint</span>: ScenarioViewpoint; <span class="docutils literal">context</span>: ref?; <span class="docutils literal">precondition</span>, <span class="docutils literal">postcondition</span>: strings; <span class="docutils literal">steps</span>: occurrence refs</p></td>
<td><p>MixedLegacy for omitted schema-2 source; none; <span class="docutils literal">&quot;&quot;</span>; <span class="docutils literal">&quot;&quot;</span>; <span class="docutils literal">[]</span></p></td>
</tr>
<tr><td><p><span class="docutils literal">oa_lifeline</span>, <span class="docutils literal">sa_lifeline</span></p></td>
<td><p><span class="docutils literal">represented</span>: participant, work, or role ref?</p></td>
<td><p>none</p></td>
</tr>
<tr><td><p><span class="docutils literal">oa_occurrence</span>, <span class="docutils literal">sa_occurrence</span></p></td>
<td><p><span class="docutils literal">body</span>: occurrence constructor; <span class="docutils literal">precondition</span>, <span class="docutils literal">postcondition</span>: strings</p></td>
<td><p>Exchange with none references, Asynchronous message kind and no values; two empty strings</p></td>
</tr>
<tr><td><p><span class="docutils literal">oa_state_machine</span>, <span class="docutils literal">sa_state_machine</span>, <span class="docutils literal">oa_region</span>, <span class="docutils literal">sa_region</span></p></td>
<td><p>None</p></td>
<td><p>Empty body</p></td>
</tr>
<tr><td><p><span class="docutils literal">oa_state</span>, <span class="docutils literal">sa_state</span>, <span class="docutils literal">oa_mode</span>, <span class="docutils literal">sa_mode</span>, <span class="docutils literal">oa_initial</span>, <span class="docutils literal">sa_initial</span>, <span class="docutils literal">oa_final</span>, <span class="docutils literal">sa_final</span></p></td>
<td><p><span class="docutils literal">kind</span>: StateKind; <span class="docutils literal">entry</span>, <span class="docutils literal">exit</span>, <span class="docutils literal">do_activity</span>: strings</p></td>
<td><p>Kind selected by declaration; three empty strings</p></td>
</tr>
<tr><td><p><span class="docutils literal">oa_choice</span>, <span class="docutils literal">oa_junction</span>, <span class="docutils literal">oa_fork</span>, <span class="docutils literal">oa_join</span>, <span class="docutils literal">oa_shallow_history</span>, <span class="docutils literal">oa_deep_history</span>, <span class="docutils literal">oa_entry_point</span>, <span class="docutils literal">oa_exit_point</span>, <span class="docutils literal">oa_terminate</span> and corresponding <span class="docutils literal">sa_</span> declarations</p></td>
<td><p>Same State body; StateKind is Choice, Junction, Fork, Join, ShallowHistory, DeepHistory, EntryPoint, ExitPoint or Terminate</p></td>
<td><p>Kind selected by declaration; three empty strings</p></td>
</tr>
<tr><td><p><span class="docutils literal">oa_event</span>, <span class="docutils literal">sa_event</span></p></td>
<td><p><span class="docutils literal">body</span>: Signal, Time or Change constructor</p></td>
<td><p>Signal with <span class="docutils literal">items []</span></p></td>
</tr>
<tr><td><p><span class="docutils literal">oa_constraint</span>, <span class="docutils literal">sa_constraint</span></p></td>
<td><p><span class="docutils literal">expression</span>: string; <span class="docutils literal">constrained</span>: semantic record refs</p></td>
<td><p><span class="docutils literal">&quot;&quot;</span>; <span class="docutils literal">[]</span></p></td>
</tr>
</tbody>
</table>
<p>The explicit state <span class="docutils literal">kind</span> field MUST agree with its declaration keyword.
<span class="docutils literal">u32</span> is an integer from 0 through 4294967295. A DataField's maximum MUST
be at least its minimum; <span class="docutils literal">none</span> 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:</p>
<pre class="code text literal-block"><code>definition { Enumeration { literals [&quot;Clear&quot;, &quot;Fog&quot;]; }; };
type_ref { Named &#64;weather_classification; };</code></pre>
<p>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 <span class="docutils literal">message_kind</span>,
<span class="docutils literal">reply_to</span> and <span class="docutils literal">values</span> 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.</p>
<table>
<caption>Occurrence body constructors</caption>
<colgroup>
<col style="width: 22.0%" />
<col style="width: 78.0%" />
</colgroup>
<thead>
<tr><th class="head"><p>Constructor</p></th>
<th class="head"><p>Required fields</p></th>
</tr>
</thead>
<tbody>
<tr><td><p>Exchange</p></td>
<td><p><span class="docutils literal">exchange</span>: exchange relation ref?; <span class="docutils literal">sender</span>, <span class="docutils literal">receiver</span>: lifeline refs?; <span class="docutils literal">message_kind</span>: MessageKind; <span class="docutils literal">reply_to</span>: occurrence ref?; <span class="docutils literal">values</span>: MessageValue records</p></td>
</tr>
<tr><td><p>Action</p></td>
<td><p><span class="docutils literal">action</span>: activity/function ref?; <span class="docutils literal">lifeline</span>: ref?</p></td>
</tr>
<tr><td><p>Control</p></td>
<td><p><span class="docutils literal">kind</span>: Choice, Merge, Fork, Join, Loop</p></td>
</tr>
<tr><td><p>SequenceReference</p></td>
<td><p><span class="docutils literal">sequence</span>: process/functional-chain ref?</p></td>
</tr>
<tr><td><p>ScenarioUse</p></td>
<td><p><span class="docutils literal">scenario</span>: scenario ref?; <span class="docutils literal">bindings</span>: LifelineBinding records</p></td>
</tr>
<tr><td><p>State</p></td>
<td><p><span class="docutils literal">state</span>: state/mode ref?; <span class="docutils literal">lifeline</span>: ref?</p></td>
</tr>
<tr><td><p>Fragment</p></td>
<td><p><span class="docutils literal">operator</span>: Alternative, Parallel, Loop, Optional; <span class="docutils literal">branches</span>: branch occurrence refs</p></td>
</tr>
<tr><td><p>Branch</p></td>
<td><p><span class="docutils literal">guard</span>: string; <span class="docutils literal">occurrences</span>: occurrence refs</p></td>
</tr>
</tbody>
</table>
<p>For example, <span class="docutils literal">body { Action { action &#64;assess; lifeline &#64;operator_line; }; };</span>
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 <span class="docutils literal">lifeline none</span>. 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
<span class="docutils literal">parent</span>. A Branch belongs to a Fragment; the Fragment's <span class="docutils literal">branches</span> list
references the branches it owns.</p>
<p>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.</p>
</section>
<section id="containment-allocation-and-relationships">
<h2>4. Containment, allocation, and relationships</h2>
<p>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. 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.</p>
<p>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.</p>
<p>All relations have a header identity, alias, display name, optional
<span class="docutils literal">description</span> (default <span class="docutils literal">&quot;&quot;</span>), and required <span class="docutils literal">source</span> and <span class="docutils literal">target</span>
references. Their kind is the declaration keyword:</p>
<table>
<caption>Relation catalog</caption>
<colgroup>
<col style="width: 24.0%" />
<col style="width: 49.0%" />
<col style="width: 27.0%" />
</colgroup>
<thead>
<tr><th class="head"><p>Declaration</p></th>
<th class="head"><p>Endpoint meaning</p></th>
<th class="head"><p>Additional fields / defaults</p></th>
</tr>
</thead>
<tbody>
<tr><td><p><span class="docutils literal">allocation</span></p></td>
<td><p>Same-layer participant → leaf activity/function</p></td>
<td><p>None</p></td>
</tr>
<tr><td><p><span class="docutils literal">interaction</span></p></td>
<td><p>OA activity → OA activity</p></td>
<td><p><span class="docutils literal">items</span> refs / []</p></td>
</tr>
<tr><td><p><span class="docutils literal">functional_exchange</span></p></td>
<td><p>SA function → SA function</p></td>
<td><p><span class="docutils literal">source_port</span>, <span class="docutils literal">target_port</span> / none; <span class="docutils literal">items</span> / []</p></td>
</tr>
<tr><td><p><span class="docutils literal">boundary_exchange</span></p></td>
<td><p>Participant-owned output-compatible port → input-compatible port</p></td>
<td><p><span class="docutils literal">items</span> refs / []</p></td>
</tr>
<tr><td><p><span class="docutils literal">capability_involvement</span></p></td>
<td><p>Participant, activity/function, or OA role → capability</p></td>
<td><p>None</p></td>
</tr>
<tr><td><p><span class="docutils literal">chain_involvement</span></p></td>
<td><p>Process/functional chain → capability</p></td>
<td><p>None</p></td>
</tr>
<tr><td><p><span class="docutils literal">role_realization</span></p></td>
<td><p>OA entity/actor → OA role</p></td>
<td><p>None</p></td>
</tr>
<tr><td><p><span class="docutils literal">role_assignment</span></p></td>
<td><p>OA role → leaf OA activity</p></td>
<td><p>None</p></td>
</tr>
<tr><td><p><span class="docutils literal">mission_capability</span></p></td>
<td><p>OA mission → OA capability, or SA mission → SA capability</p></td>
<td><p>None</p></td>
</tr>
<tr><td><p><span class="docutils literal">mission_involvement</span></p></td>
<td><p>OA entity/actor → OA mission, or SA System/Actor → SA mission</p></td>
<td><p>None</p></td>
</tr>
<tr><td><p><span class="docutils literal">capability_include</span></p></td>
<td><p>Including capability → included capability in one layer</p></td>
<td><p>None</p></td>
</tr>
<tr><td><p><span class="docutils literal">capability_extend</span></p></td>
<td><p>Extending capability → extended capability in one layer</p></td>
<td><p><span class="docutils literal">condition</span> string / &quot;&quot;</p></td>
</tr>
<tr><td><p><span class="docutils literal">capability_generalization</span></p></td>
<td><p>Specific capability → general capability in one layer</p></td>
<td><p>None</p></td>
</tr>
<tr><td><p><span class="docutils literal">sequence_link</span></p></td>
<td><p>Preceding contribution → following contribution in one process/chain</p></td>
<td><p><span class="docutils literal">guard</span> string / &quot;&quot;</p></td>
</tr>
<tr><td><p><span class="docutils literal">state_transition</span></p></td>
<td><p>State vertices in one machine, subject to section 4.4</p></td>
<td><p><span class="docutils literal">trigger</span>, <span class="docutils literal">guard</span>, <span class="docutils literal">effect</span> strings / &quot;&quot;; <span class="docutils literal">transition_kind</span> External; <span class="docutils literal">triggers</span>, <span class="docutils literal">effects</span> reference lists / []</p></td>
</tr>
<tr><td><p><span class="docutils literal">availability</span></p></td>
<td><p>Work, participant, capability, or process/chain → state/mode</p></td>
<td><p>None</p></td>
</tr>
<tr><td><p><span class="docutils literal">exchange_allocation</span></p></td>
<td><p>Boundary-exchange relation → SA functional-exchange relation</p></td>
<td><p>None</p></td>
</tr>
<tr><td><p><span class="docutils literal">interface_provision</span>, <span class="docutils literal">interface_requirement</span></p></td>
<td><p>Participant/port → provided/required interface</p></td>
<td><p>None</p></td>
</tr>
<tr><td><p><span class="docutils literal">state_action</span></p></td>
<td><p>State/mode → activity/function</p></td>
<td><p><span class="docutils literal">phase</span>: Entry, Do, Exit / Do</p></td>
</tr>
</tbody>
</table>
<p>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.</p>
<p>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.</p>
<p>Functional ports, when selected, belong to the corresponding endpoint function
and have compatible direction. Boundary ports belong to participants and have
compatible direction. An interface groups ExchangeItems; an exchange using
that port interface must carry items supported by it. Studio's OA boundary
exchange is a simplified representation of operational communication; it is
not a claim of complete Capella CommunicationMean equivalence.</p>
<p>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.</p>
<section id="capabilities-and-missions">
<h3>4.1. Capabilities and missions</h3>
<p>Include means the including capability requires the included capability's
behavior. Extend means the source capability adds conditional behavior to the
target; its <span class="docutils literal">condition</span> records when that behavior applies. Generalization
means a specific source capability specializes a general target capability.
Each relationship stays within OA capabilities or within SA capabilities.
Include and Generalization graphs MUST each be acyclic, including transitive
cycles. Extend does not introduce an additional cycle restriction; the ordinary
no-self rule still applies. An empty Extend condition is an engineering warning
so an incomplete capability map can be authored and saved.</p>
<p>MissionCapability and MissionInvolvement express need and stakeholder/system
participation. They MUST NOT create a capability parent, a performer allocation,
or a cross-layer realization. These relationships remain distinct when the
same objects appear in a diagram or share names.</p>
</section>
<section id="contextual-process-and-chain-topology">
<h3>4.2. Contextual process and chain topology</h3>
<p>A Process or FunctionalChain owns contribution occurrences with stable
identities. <span class="docutils literal">steps</span> is their persistent membership and presentation order;
an identity MUST occur at most once in that list. A work contribution points to
an existing same-layer Activity or Function. Reusing the same work or exchange
requires separate occurrence identities and MUST NOT duplicate the referenced
engineering element. A SequenceReference points to another same-layer Process
or FunctionalChain of the owner's kind. Its target may be <span class="docutils literal">none</span> while the
draft is incomplete. Direct and transitive recursive sequence reuse are errors.</p>
<p>SequenceLinks connect distinct occurrences directly owned by the same process
or chain. Their source is the predecessor and target is the successor. A link
from work to an exchange requires that work to be the referenced exchange's
source; an exchange-to-work link requires the target work to be its endpoint.
Two adjacent exchange contributions require the first exchange's target to
match the second exchange's source. A mismatch is a structural error. Other
links express contextual precedence without manufacturing a global exchange.</p>
<p>When links or work/control/reuse contributions exist, topology is explicit.
Reordering <span class="docutils literal">steps</span> MUST NOT add, remove or reorder SequenceLinks. The editor
MUST retain the difference between alternative Choice/Merge and parallel
Fork/Join contributions. Choice/Fork expect one incoming and at least two
outgoing links; Merge/Join expect at least two incoming and one outgoing link.
Loop expects at least one incoming and two outgoing links for repetition and
exit. These cardinalities are completeness warnings, not barriers to building
an incomplete flow. Choice and Loop outgoing paths with empty guards warn;
an explicit <span class="docutils literal">else</span> guard is permitted. Guards remain descriptive strings.</p>
<p>Validation warns about missing/ambiguous entry and exit, isolated or unreachable
contributions, contributions with no reachable exit, and splits/merges that
lack explicit controls. Topology cycles are permitted for loops; the recursive
SequenceReference prohibition is a different rule. A legacy exchange-only
sequence without explicit links retains its ordered linear meaning and
adjacent-exchange gap diagnostics. Implementations MUST NOT silently invent
topology links when loading or reordering such a sequence.</p>
</section>
<section id="typed-scenarios-and-reusable-behavior">
<h3>4.3. Typed scenarios and reusable behavior</h3>
<p>ScenarioViewpoint is one of OperationalActivity (OA activity lifelines),
ParticipantInteraction (OA entity/actor/role lifelines), Functional (SA function
lifelines), BoundaryInterface (SA System/Actor lifelines), or MixedLegacy.
The first two are OA viewpoints; the next two are SA viewpoints. Lifeline
references MUST agree with that perspective. OperationalActivity messages use
Interactions; Functional messages use FunctionalExchanges. Participant views
may use their layer's work exchanges through effective performer allocation,
or participant boundary exchanges through the relevant ports. Corresponding
lifelines and endpoints MUST agree; a viewpoint is not a label that suppresses
reference checks.</p>
<p>Omitted schema-2 viewpoints hydrate as MixedLegacy in both source and JSON.
This preserves pre-extension mixed work/participant scenes without discarding
their lifelines or silently assigning a stricter meaning. MixedLegacy emits a
review warning. New graphical factories explicitly select OperationalActivity
or Functional by layer. Authors can select a strict viewpoint after reviewing
the legacy scene; canonical source then records that choice.</p>
<p>MessageKind is Asynchronous, Call, Reply, Create, Delete, or
<span class="docutils literal">{ Timer { expression &quot;after 5 s&quot;; }; }</span>. A process/chain exchange
contribution MUST remain Asynchronous with no reply correlation. Call/reply,
creation/deletion and timer semantics belong to scenarios. Reply's <span class="docutils literal">reply_to</span>
references a Call occurrence in the same scenario. The call MUST precede the
reply on a guaranteed common sequence/enclosing branch path. Reply lifelines
reverse the call's sender/receiver; it may reuse the call's exchange in reverse
or use an explicit reverse-direction exchange. A second reply to the same call
on that guaranteed path is an error. Missing reply correlation is a draft
warning; non-Reply messages MUST NOT have <span class="docutils literal">reply_to</span>.</p>
<p>Create identifies the receiver lifeline's creation. An earlier guaranteed use
of that lifeline is an error. Delete identifies its destruction; a later
guaranteed use is an error. Ordering checks respect branch ownership; they MUST
NOT flatten alternative branches into a false unconditional order. A Timer is
local to its sender lifeline, has no global exchange or values, and has either
no receiver or the same receiver as sender. Its nonempty expression describes
the delay/deadline; an empty expression warns. Conditions and expressions are
stored engineering annotations, not an executable simulation language.</p>
<p>Each MessageValue is <span class="docutils literal">{ field &#64;data_field; expression &quot;value expression&quot;; }</span>.
The field MUST be a DataField carried by the message exchange, including fields
inside named nested records. At most one annotation for a given field is
allowed in one message. Values do not overwrite the referenced type or global
exchange item. Expression text is preserved exactly; an empty expression warns.</p>
<p>ScenarioUse references an existing same-layer scenario and maps its lifelines
with <span class="docutils literal">bindings [ { referenced &#64;callee_line; local &#64;caller_line; } ];</span>.
Each binding is one-to-one and references a direct lifeline of the appropriate
scenario. Bound lifelines represent the same semantic object, or an explicitly
realized operational role. Strict viewpoints MUST agree; MixedLegacy retains
the compatibility case until reviewed. Missing bindings produce warnings.
Direct/transitive recursive scenario use is invalid; repetition uses a Loop
fragment instead. ScenarioUse owns neither its referenced scenario nor its
lifelines; deleting a use does not delete the reusable definition.</p>
</section>
<section id="state-vertices-events-and-transition-contracts">
<h3>4.4. State vertices, events and transition contracts</h3>
<p>StateKind comprises State, Mode, Initial, Final, Choice, Junction, Fork, Join,
ShallowHistory, DeepHistory, EntryPoint, ExitPoint and Terminate. Every vertex
belongs to a Region. Only State and Mode are stable states: only these may own
nested Regions, typed StateAction links, availability and scenario state
observations. Multiple sibling Regions describe orthogonal configurations.
EntryPoint and ExitPoint retain Region ownership; their boundary is that
Region's owning State/Mode or StateMachine. Their graphical symbols belong on
that boundary. This is Studio's explicit containment encoding.</p>
<p>Events are ordinary same-layer semantic elements, independent of diagram
placements. EventBody has exactly these constructors:</p>
<table>
<caption>Event definitions</caption>
<thead>
<tr><th class="head"><p>Constructor</p></th>
<th class="head"><p>Fields and meaning</p></th>
</tr>
</thead>
<tbody>
<tr><td><p>Signal</p></td>
<td><p><span class="docutils literal">items</span> is a unique list of same-layer ExchangeItem references; empty is valid</p></td>
</tr>
<tr><td><p>Time</p></td>
<td><p><span class="docutils literal">kind</span> is After or At; <span class="docutils literal">expression</span> is descriptive time text</p></td>
</tr>
<tr><td><p>Change</p></td>
<td><p><span class="docutils literal">expression</span> describes the Boolean condition becoming true</p></td>
</tr>
</tbody>
</table>
<p>After measures relative time from activation of a transition's source state;
At describes an absolute instant. Empty Time/Change expressions are located
completeness warnings. The application does not execute expressions, fire
timers or transport signals. For example:</p>
<pre class="literal-block">sa_event timeout &quot;Recovery timeout&quot; {
body { Time { kind After; expression &quot;30 s&quot;; }; };
}
sa_event recovered &quot;Pressure recovered&quot; {
body { Change { expression &quot;pressure &gt; 4 &amp;&amp; status == \&quot;Ready\&quot;&quot;; }; };
}</pre>
<p>StateTransition's <span class="docutils literal">triggers</span> references Events or layer-appropriate work
(OA Activity / SA Function). Referenced work need not have the machine owner's
performer: external work can cause the observed transition. Multiple triggers
are alternatives. <span class="docutils literal">effects</span> references work describing effects, without
executing it. Duplicate, missing, wrong-layer or wrong-kind references are
errors. The existing <span class="docutils literal">trigger</span>, <span class="docutils literal">guard</span> and <span class="docutils literal">effect</span> strings remain
authored prose; they MUST NOT be renamed, parsed as UUIDs or inferred by name.</p>
<p>With typed triggers, <span class="docutils literal">trigger</span> adds descriptive information. With no typed
triggers and nonblank trigger prose, the transition has an unresolved
descriptive trigger and emits a warning. Both empty denotes completion from
a stable state or transient routing from a pseudostate. Deleting the final
typed trigger when prose is empty MUST leave an explicit descriptive reminder;
it MUST NOT silently create a completion transition. Guards/effect prose remain
unchanged. Signal payload references and typed effect references are pruned
when their targets are removed.</p>
<p>TransitionKind is External, Local or Internal. External leaves/re-enters the
affected configuration; a stable self-transition includes exit and entry
behavior. Internal requires the same stable source and target, preserves nested
configuration, and does not imply entry/exit. Local requires a composite stable
source and proper descendant target, preserving the source activation; an
EntryPoint also routes locally into its boundary. Local self/outside targets
are invalid. Other pseudostates route externally. Endpoints MUST share a layer
and StateMachine; crossing nested Regions within that machine is not generally
forbidden. A pseudostate self-transition is invalid.</p>
<p>A simple state's completion means entry/do behavior is complete. A composite
completes when its active Regions complete. Final completes its containing
Region; Terminate ends the containing machine's activation. These are modeling
meanings, not evidence of a running state-machine engine.</p>
<p>Missing connections/guards and unfinished initial/history paths produce
warnings, so an engineer can insert vertices before wiring them. Contradictory
upper cardinalities, forbidden directions/kinds and invalid references reject.</p>
<table>
<caption>Vertex connection constraints</caption>
<thead>
<tr><th class="head"><p>Vertex</p></th>
<th class="head"><p>Structural restrictions</p></th>
<th class="head"><p>Incomplete-model warnings</p></th>
</tr>
</thead>
<tbody>
<tr><td><p>Initial</p></td>
<td><p>At most one per Region; no incoming; at most one outgoing; no outgoing trigger or guard</p></td>
<td><p>Missing initial/default entry or outgoing</p></td>
</tr>
<tr><td><p>Final / Terminate</p></td>
<td><p>No outgoing or nested Region</p></td>
<td><p>No incoming</p></td>
</tr>
<tr><td><p>Choice</p></td>
<td><p>At most one incoming; outgoing transient alternatives</p></td>
<td><p>Missing incoming, fewer than two outgoing, missing guard or else</p></td>
</tr>
<tr><td><p>Junction</p></td>
<td><p>Transient routing, no implicit concurrency</p></td>
<td><p>Missing side or ambiguous unguarded alternatives</p></td>
</tr>
<tr><td><p>Fork</p></td>
<td><p>At most one incoming; outgoing stable targets in distinct orthogonal Regions</p></td>
<td><p>Missing incoming or fewer than two outgoing</p></td>
</tr>
<tr><td><p>Join</p></td>
<td><p>At most one outgoing; incoming stable sources in distinct orthogonal Regions</p></td>
<td><p>Fewer than two incoming or missing outgoing</p></td>
</tr>
<tr><td><p>ShallowHistory</p></td>
<td><p>At most one per Region; at most one fallback to a direct stable child of that Region; no fallback trigger/guard</p></td>
<td><p>Missing fallback/default entry</p></td>
</tr>
<tr><td><p>DeepHistory</p></td>
<td><p>At most one per Region; at most one fallback to a stable descendant of that Region; no fallback trigger/guard</p></td>
<td><p>Missing fallback/default entry</p></td>
</tr>
<tr><td><p>EntryPoint</p></td>
<td><p>Incoming from outside boundary, outgoing Local into it; at most one outgoing per destination Region</p></td>
<td><p>Missing outgoing or incomplete affected-Region entry</p></td>
</tr>
<tr><td><p>ExitPoint</p></td>
<td><p>Incoming from inside boundary; at most one outgoing External to outside</p></td>
<td><p>Missing input/output; top-level exit is an exit endpoint, not implicit termination</p></td>
</tr>
</tbody>
</table>
<p>Fork outputs and Join inputs MUST NOT carry guards or typed/descriptive
triggers. Their distinct orthogonal Regions are the first Regions beneath the
nearest common composite or machine, not merely each endpoint's immediate
parent. Choice/Junction routing expresses conditional alternatives. Retained
pseudostate entry/exit/do prose produces a warning and remains editable; it
does not become a typed state behavior. StateAction remains the maintained
reference for entry/do/exit work on stable states.</p>
<p>Other pseudostate outgoing segments MUST NOT introduce event/work triggers
or trigger prose. A Choice has at most one literal <span class="docutils literal">else</span> guard; the tool
does not prove arbitrary guard expressions disjoint or exhaustive. Choice
expresses a dynamic decision after incoming effects; Junction expresses a
compound path selected by guards before traversing it. ShallowHistory remembers
the immediate state and uses default entry for deeper configuration;
DeepHistory remembers nested configuration. Fallback applies when no resumable
history exists. History is per Region, including top-level Regions in this
Studio profile; no running history state is persisted or synthesized.</p>
</section>
</section>
<section id="diagrams-artifacts-and-cross-layer-traceability">
<h2>5. Diagrams, artifacts, and cross-layer traceability</h2>
<p><span class="docutils literal">diagram</span> has name, identity, alias, description, <span class="docutils literal">layer</span> (Oa by default),
and <span class="docutils literal">projection</span> (Overview by default). Other projections are Decomposition,
Allocation, and Traceability. Traceability diagrams can show both layers;
other diagrams show their chosen layer.</p>
<p><span class="docutils literal">node</span> has an alias and identity but no display-name string. Required fields
are <span class="docutils literal">diagram</span> and <span class="docutils literal">element</span> references. Optional fields are <span class="docutils literal">position</span>
(record with x/y, default 0/0), <span class="docutils literal">size</span> (width/height, default 224/94), and
<span class="docutils literal">collapsed</span> (false). 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, and attached artifacts. The destination must accept the
element's layer and must not already contain another placement of that element.</p>
<p><span class="docutils literal">artifact</span> has name, identity, alias, description, required <span class="docutils literal">owner</span> ref,
<span class="docutils literal">relation</span> (References, Satisfies, Verifies, Implements, DerivedFrom;
default References), <span class="docutils literal">uri</span> (default empty), <span class="docutils literal">revision</span> (optional string),
and <span class="docutils literal">fragment</span> (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.</p>
<p><span class="docutils literal">trace</span> has name, identity, alias, description, required <span class="docutils literal">oa</span> and <span class="docutils literal">sa</span>
endpoint references, <span class="docutils literal">kind</span> (default Refinement), and <span class="docutils literal">baseline</span> (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.</p>
<table>
<caption>Trace kinds</caption>
<colgroup>
<col style="width: 23.0%" />
<col style="width: 77.0%" />
</colgroup>
<thead>
<tr><th class="head"><p>Kind</p></th>
<th class="head"><p>OA → SA endpoint types</p></th>
</tr>
</thead>
<tbody>
<tr><td><p>Refinement</p></td>
<td><p>Activity → Function</p></td>
</tr>
<tr><td><p>Participant</p></td>
<td><p>Entity/Actor → System/Actor</p></td>
</tr>
<tr><td><p>Capability</p></td>
<td><p>Operational Capability → System Capability</p></td>
</tr>
<tr><td><p>Mission</p></td>
<td><p>Operational Mission → System Mission</p></td>
</tr>
<tr><td><p>Exchange</p></td>
<td><p>Interaction relation → FunctionalExchange relation</p></td>
</tr>
<tr><td><p>Sequence</p></td>
<td><p>Process → FunctionalChain, or paired occurrence contributions directly owned by Process / FunctionalChain</p></td>
</tr>
<tr><td><p>Item</p></td>
<td><p>Same shared kind: ExchangeItem, DataType, DataField, Interface, or Port</p></td>
</tr>
<tr><td><p>Scenario</p></td>
<td><p>Same shared kind: Scenario, Lifeline, or Occurrence</p></td>
</tr>
<tr><td><p>State</p></td>
<td><p>Same shared kind: StateMachine, Region, any StateKind vertex, or Event</p></td>
</tr>
<tr><td><p>Manual</p></td>
<td><p>Engineer-defined relationship between OA/SA elements or relations</p></td>
</tr>
</tbody>
</table>
<p>A nonempty baseline is <span class="docutils literal">{ oa { name <span class="pre">&quot;...&quot;;</span> description <span class="pre">&quot;...&quot;;</span> }; sa { name <span class="pre">&quot;...&quot;;</span> description <span class="pre">&quot;...&quot;;</span> }; }</span>. 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.</p>
<p>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.</p>
<p>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.</p>
</section>
<section id="text-grammar-and-resolution">
<h2>6. Text grammar and resolution</h2>
<p>The input is UTF-8 without a byte-order mark. LF, CR, space, and tab separate
tokens. <span class="docutils literal">//</span> starts a comment through the next LF or end of input. Quoted
strings use JSON string escaping, including <span class="docutils literal">\n</span>, <span class="docutils literal">\r</span>, <span class="docutils literal">\t</span>, <span class="docutils literal">\\</span>,
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.</p>
<p>Aliases match <span class="docutils literal"><span class="pre">[A-Za-z_][A-Za-z0-9_]*</span></span>. 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 <span class="docutils literal">&#64;</span>.</p>
<p>The grammar below uses <span class="docutils literal">*</span> for repetition and <span class="docutils literal">?</span> for optional syntax.
<span class="docutils literal">kind</span> is exactly an element/relation keyword listed above. Typed field
sets and enum constructors are closed by sections 3–5.</p>
<pre class="code text literal-block"><code>document = &quot;arcadia&quot; &quot;2&quot; &quot;;&quot; project
project = &quot;project&quot; alias string identity? &quot;{&quot; project-entry* &quot;}&quot;
project-entry = &quot;description&quot; string &quot;;&quot; | declaration
declaration = (kind | &quot;diagram&quot; | &quot;artifact&quot; | &quot;trace&quot;)
alias string identity? fields
| &quot;node&quot; alias identity? fields
identity = &quot;id&quot; uuid-string
fields = &quot;{&quot; (field-name value &quot;;&quot;)* &quot;}&quot;
value = string | number | &quot;true&quot; | &quot;false&quot; | &quot;none&quot;
| enum-word | &quot;&#64;&quot; alias | list | fields
list = &quot;[&quot; (value (&quot;,&quot; value)*)? &quot;]&quot;</code></pre>
<p>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.</p>
<p>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, canonical text includes the
generated identity. Authors must keep identity clauses to preserve existing
objects across subsequent edits.</p>
<p>All declaration aliases are collected before references resolve, so forward
references are legal, including references to nodes and diagrams. Unknown
<span class="docutils literal">&#64;alias</span> 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.</p>
<p>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
<span class="docutils literal">&#64;alias</span> 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.</p>
</section>
<section id="canonical-output-and-source-tooling">
<h2>7. Canonical output and source tooling</h2>
<p>For every structurally valid Project P, parsing its canonical output MUST
reproduce P, and canonicalizing that result MUST be idempotent:</p>
<pre class="code text literal-block"><code>parse(format(P)) == P
format(parse(format(P))) == format(P)</code></pre>
<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.</p>
<p>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.</p>
<p>Comments and input whitespace are lexical trivia. Canonicalizing or applying
source does not preserve them; the editor MUST explain that behavior.
Camera position, selection, source cursor, and undo history are not stored
model fields. Layout and collapse state inside NodePlacement are model data.</p>
<p><span class="docutils literal">parse</span> 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.</p>
<p><span class="docutils literal">parse_limited</span> and <span class="docutils literal">decode_limited</span> 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 <span class="docutils literal">parse</span> has no such model
size policy. The REST service's fixed policy is specified in <span class="docutils literal">api.rst</span>.</p>
<p><span class="docutils literal">tokenize</span> 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. <span class="docutils literal">&#64;</span> is punctuation followed by the referenced alias token.
<span class="docutils literal">lint</span> 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.
<span class="docutils literal">analyze</span>
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.</p>
</section>
<section id="graphical-parity-and-transactional-editing">
<h2>8. Graphical parity and transactional editing</h2>
<p>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.</p>
<p>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.</p>
<p>Applying complete source is one model transaction. Graphical edits regenerate
the matching canonical source. Both paths validate their candidate 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.</p>
<p>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, including aliases, trace links, and occurrence identity.</p>
<p>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.</p>
</section>
<section id="persistence-and-v1-migration">
<h2>9. Persistence and V1 migration</h2>
<p>Loading detects JSON from its first non-whitespace <span class="docutils literal">{</span>; other input is parsed
as Arcadia source regardless of filename. Saving an <span class="docutils literal">.arcadia</span> suffix uses
canonical V2 text; other suffixes use V2 JSON. Both forms preserve the same
complete model. JSON rejects unknown fields throughout typed payloads,
duplicate maps, unsupported versions, and structural errors.</p>
<p>During first-release schema-2 integration, old Scenario bodies without a
<span class="docutils literal">viewpoint</span> retain MixedLegacy, and old Exchange occurrence bodies without
<span class="docutils literal">message_kind</span>, <span class="docutils literal">reply_to</span> or <span class="docutils literal">values</span> retain Asynchronous, none and [].
Old StateTransition bodies without <span class="docutils literal">transition_kind</span>, <span class="docutils literal">triggers</span> or
<span class="docutils literal">effects</span> retain External, [] and []; existing <span class="docutils literal">trigger</span>, <span class="docutils literal">guard</span> and
<span class="docutils literal">effect</span> 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
<span class="docutils literal"><span class="pre">crates/oa-core/tests/fixtures</span></span> MUST NOT be regenerated from the newer demo;
they verify that every old persistent field survives. Canonical output writes
the added defaults. A future schema-3 adapter remains a separate required
migration and is not implied by this temporary compatibility behavior.</p>
<p>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.</p>
<p>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.</p>
<p>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 V2 result, including repeated occurrences.
No System or SA content is invented during an OA-only migration.</p>
<p>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
V2 projects. Future versions remain errors until a separate migration exists.</p>
</section>
<section id="complete-authoring-example">
<h2>10. Complete authoring example</h2>
<p>This document intentionally omits IDs for new authoring. Apply and Save write
the assigned UUIDs explicitly.</p>
<pre class="code text literal-block"><code>arcadia 2;
project harbor &quot;Harbor assistance&quot; {
oa_entity control &quot;Harbor control&quot; {}
oa_activity assess &quot;Assess assistance&quot; {}
allocation performs &quot;Performs&quot; {
source &#64;control;
target &#64;assess;
}
sa_system service &quot;Harbor assistance system&quot; {}
sa_function evaluate &quot;Evaluate assistance request&quot; {}
allocation system_performs &quot;Performs&quot; {
source &#64;service;
target &#64;evaluate;
}
trace assessment_trace &quot;Operational realization&quot; {
oa &#64;assess;
sa &#64;evaluate;
kind Refinement;
}
diagram operational_view &quot;Operational allocation&quot; {
layer Oa;
projection Allocation;
}
node assessment_card {
diagram &#64;operational_view;
element &#64;assess;
position { x 360; y 70; };
}
}</code></pre>
</section>
<section id="verification-and-primary-references">
<h2>11. Verification and primary references</h2>
<p><span class="docutils literal">cargo test <span class="pre">-p</span> <span class="pre">oa-core</span> <span class="pre">--test</span> language <span class="pre">--locked</span></span> 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.</p>
<p>The research record in <span class="docutils literal"><span class="pre">docs/research-v2-semantics.md</span></span> distinguishes method
requirements from Studio design choices and links to original UI evidence.
The following sources inform this language without extending its scope:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://mbse-capella.org/arcadia-qna.html">Arcadia Q&amp;A</a></p></li>
<li><p><a class="reference external" href="https://mbse-capella.org/resources/arcadia-reference/Arcadia%20Language%20-%20MetaModel.pdf">Arcadia language reference</a></p></li>
<li><p><a class="reference external" href="https://github.com/eclipse-capella/capella/blob/master/doc/plugins/org.polarsys.capella.ui.doc/html/05.%20Diagram%20Management/Allocating%20Functions%20on%20Components.mediawiki">Capella allocation guide</a></p></li>
<li><p><a class="reference external" href="https://github.com/eclipse-capella/capella/blob/master/doc/plugins/org.polarsys.capella.transitions.doc/html/11.%20Iterative%20Transitions/11.1.%20Concepts.mediawiki">Capella iterative transitions</a></p></li>
<li><p><a class="reference external" href="https://www.w3.org/TR/xml/#charsets">W3C XML 1.0 characters</a></p></li>
</ul>
</section>
</main>
</body>
</html>