2133 lines
122 KiB
HTML
2133 lines
122 KiB
HTML
<!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">4</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 versions 1, 2 and 3. MUST, MUST NOT,
|
||
and MAY indicate requirements, prohibitions, and permitted choices.</p>
|
||
<p>Schema 4 adds bounded reusable data types, typed scalar defaults, exchange
|
||
mechanisms, qualified message values, specialization, identified interface
|
||
allocations and reference associations. It retains schema 3 typed ports and
|
||
state views. Explicit older readers preserve existing meanings and identities.
|
||
This contract does not by itself establish native acceptance or release completion.</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> (4), <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">""</span>) and <span class="docutils literal">parent</span> (default <span class="docutils literal">none</span> for a
|
||
document-level declaration, or its lexical element owner when nested; section
|
||
6.2). The table
|
||
lists all additional fields. <span class="docutils literal">ref</span> means <span class="docutils literal">@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; <span class="docutils literal">mechanism</span>: ExchangeMechanism; <span class="docutils literal">supertype</span>: item ref?</p></td>
|
||
<td><p>Information; Unspecified; none</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>: DataTypeDefinition; <span class="docutils literal">default</span>: DataValue?; <span class="docutils literal">unit</span>: string</p></td>
|
||
<td><p>String with minimum_length 0 / maximum_length none; none; <span class="docutils literal">""</span></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; <span class="docutils literal">direction</span>: ParameterDirection; <span class="docutils literal">storage</span>: FieldStorage; <span class="docutils literal">default</span>: DataValue list?</p></td>
|
||
<td><p>String; 1; 1; <span class="docutils literal">""</span>; Unspecified; Value; none</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">supertype</span>: interface ref?</p></td>
|
||
<td><p>none; membership is an identified interface_item_allocation relation</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">contract</span>: required PortContract; <span class="docutils literal">legacy</span>: optional LegacyPortContract</p></td>
|
||
<td><p>No implicit contract; <span class="docutils literal">legacy</span> defaults none. OA admits Legacy only.</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">""</span>; <span class="docutils literal">""</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">""</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 ["Clear", "Fog"]; }; };
|
||
type_ref { Named @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 @assess; lifeline @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. 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.</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">""</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">interface_item_allocation</span></p></td>
|
||
<td><p>Same-layer Interface → ExchangeItem</p></td>
|
||
<td><p><span class="docutils literal">order</span> u32 / 0; <span class="docutils literal">transmission</span> TransmissionProtocol / Unspecified; <span class="docutils literal">acquisition</span> AcquisitionProtocol / Unspecified</p></td>
|
||
</tr>
|
||
<tr><td><p><span class="docutils literal">data_association</span></p></td>
|
||
<td><p>Same-layer Record DataType → Record DataType</p></td>
|
||
<td><p><span class="docutils literal">source_role</span>, <span class="docutils literal">target_role</span> / ""; <span class="docutils literal">source_minimum</span>, <span class="docutils literal">target_minimum</span> / 0; <span class="docutils literal">source_maximum</span>, <span class="docutils literal">target_maximum</span> / none; <span class="docutils literal">source_navigable</span>, <span class="docutils literal">target_navigable</span> / false</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>Required <span class="docutils literal">source_port</span>, <span class="docutils literal">target_port</span> refs; <span class="docutils literal">items</span> / []</p></td>
|
||
</tr>
|
||
<tr><td><p><span class="docutils literal">boundary_exchange</span></p></td>
|
||
<td><p>Different participant owners; typed component ports have matching kinds</p></td>
|
||
<td><p><span class="docutils literal">oriented</span> bool / true; <span class="docutils literal">items</span> refs / []</p></td>
|
||
</tr>
|
||
<tr><td><p><span class="docutils literal">port_allocation</span></p></td>
|
||
<td><p>SA Component port → SA FunctionInput/FunctionOutput port</p></td>
|
||
<td><p>Requires the function's actual work Allocation to that component</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 / ""</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 / ""</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 / ""; <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 or an explicit
|
||
DataAssociation between two ends of the same Record type.</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>Typed function ports belong directly to SA Functions. <span class="docutils literal">FunctionOutput</span>
|
||
declares <span class="docutils literal">outgoing_items</span>; <span class="docutils literal">FunctionInput</span> declares <span class="docutils literal">incoming_items</span>.
|
||
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. A carried item satisfies an identical declaration or a declaration
|
||
of one of its explicit base items. A base item does not satisfy a more
|
||
specialized declaration; names imply no compatibility. Port declarations
|
||
remain independent of incident exchanges after creation.</p>
|
||
<p>A <span class="docutils literal">Component</span> contract belongs to an SA System or SystemActor and stores
|
||
<span class="docutils literal">kind</span> (Standard or Flow) and <span class="docutils literal">orientation</span> (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 <span class="docutils literal">oriented false</span>; 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.</p>
|
||
<p>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.</p>
|
||
<p><span class="docutils literal">PortAllocation</span> 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.</p>
|
||
<p><span class="docutils literal">Legacy</span> requires <span class="docutils literal">legacy { direction <span class="pre">...;</span> interface <span class="pre">...;</span> }</span>. 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.</p>
|
||
<p>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.</p>
|
||
<p>For example:</p>
|
||
<pre class="literal-block">arcadia 4;
|
||
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" {}
|
||
interface_item_allocation service_payload "Service payload" { source @old_service; target @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; };
|
||
}</pre>
|
||
<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 "after 5 s"; }; }</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">{ path [@parameter]; field @data_field; expression "value expression"; }</span>.
|
||
Its identity is the pair (path, field), so two uses of one Record can have
|
||
different values for the same terminal field. Path contains enclosing DataField
|
||
references, excluding the terminal field; direct parameters use <span class="docutils literal">[]</span>. Every
|
||
hop MUST follow Value storage through a named Record's effective fields. Reference
|
||
storage stops traversal. Operation Call accepts In/InOut and Reply accepts
|
||
Out/InOut/Return, interpreted from the provider's perspective. Nested field paths
|
||
inherit their direct parameter's direction. Unspecified direction warns.
|
||
At most one annotation for a pair is allowed. Omitted path defaults to <span class="docutils literal">[]</span>;
|
||
an ambiguous preserved legacy nested annotation warns <span class="docutils literal">message_value_ambiguous_path</span>
|
||
until an explicit path is selected. New graphical choices always identify a path.
|
||
Values never overwrite types or items. Expression text is descriptive, preserved
|
||
exactly and not evaluated; an empty expression warns.</p>
|
||
<p>ScenarioUse references an existing same-layer scenario and maps its lifelines
|
||
with <span class="docutils literal">bindings [ { referenced @callee_line; local @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 "Recovery timeout" {
|
||
body { Time { kind After; expression "30 s"; }; };
|
||
}
|
||
sa_event recovered "Pressure recovered" {
|
||
body { Change { expression "pressure > 4 && status == \"Ready\""; }; };
|
||
}</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 id="data-contracts-specialization-and-interface-allocation">
|
||
<h3>4.5. Data contracts, specialization and interface allocation</h3>
|
||
<p>ExchangeItem <span class="docutils literal">kind</span> describes nature: Information, Material or Energy.
|
||
<span class="docutils literal">mechanism</span> is Unspecified, Flow, Event, Operation or SharedData. Unknown
|
||
mechanisms remain explicit Unspecified drafts with a warning. Material/Energy
|
||
with Event/Operation/SharedData warns for engineering review; it is not silently
|
||
reclassified. Empty Event notifications and void Operations are valid. An empty
|
||
carried/allocated Flow, SharedData or Unspecified item warns.</p>
|
||
<p>An Operation's directly owned DataFields are parameters. <span class="docutils literal">direction</span> is
|
||
Unspecified, In, Out, InOut or Return, from the provider's perspective. At most
|
||
one effective parameter is Return. Unspecified parameters warn; non-operation
|
||
fields MUST use Unspecified. Nested record fields inherit direction from their
|
||
direct parameter when used in message paths, rather than storing context on a
|
||
shared type. <span class="docutils literal">storage</span> is Value or Reference. Reference requires a named Record,
|
||
has no explicit default, and does not convey ownership or deletion of the type.</p>
|
||
<p>DataTypeDefinition has exactly the following constructors:</p>
|
||
<table>
|
||
<caption>Reusable definitions</caption>
|
||
<thead>
|
||
<tr><th class="head"><p>Constructor</p></th>
|
||
<th class="head"><p>Required fields</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr><td><p>Boolean</p></td>
|
||
<td><p>None</p></td>
|
||
</tr>
|
||
<tr><td><p>Integer</p></td>
|
||
<td><p><span class="docutils literal">minimum</span>, <span class="docutils literal">maximum</span>: optional signed 64-bit integers</p></td>
|
||
</tr>
|
||
<tr><td><p>Real</p></td>
|
||
<td><p><span class="docutils literal">minimum</span>, <span class="docutils literal">maximum</span>: optional finite IEEE-754 binary64 values</p></td>
|
||
</tr>
|
||
<tr><td><p>String</p></td>
|
||
<td><p><span class="docutils literal">minimum_length</span>: u32; <span class="docutils literal">maximum_length</span>: optional u32</p></td>
|
||
</tr>
|
||
<tr><td><p>Enumeration</p></td>
|
||
<td><p><span class="docutils literal">literals</span>: unique nonempty, case-sensitive strings</p></td>
|
||
</tr>
|
||
<tr><td><p>Record</p></td>
|
||
<td><p><span class="docutils literal">supertype</span>: same-layer Record ref?</p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<p>Bounds are inclusive and ordered; an absent bound means unbounded within the
|
||
represented numeric domain. Integer comparisons MUST NOT convert to binary64.
|
||
NaN, infinities, overflow and reversed bounds reject. String length counts Unicode
|
||
scalar values, not UTF-8 bytes or grapheme clusters. Enum defaults match exact
|
||
literals. Empty enum definitions remain incomplete drafts with a warning.</p>
|
||
<p>DataValue is a tagged scalar: <span class="docutils literal">{ Boolean true; }</span>, <span class="docutils literal">{ Integer 42; }</span>,
|
||
<span class="docutils literal">{ Real 1.5; }</span>, <span class="docutils literal">{ String "value"; }</span> or <span class="docutils literal">{ Enumeration "Ready"; }</span>.
|
||
There is no implicit numeric or string coercion. A type default is one compatible
|
||
scalar within its bounds. Record type defaults and record/object instance literals
|
||
are unsupported. A field default is absent (<span class="docutils literal">none</span>) or a list of compatible
|
||
scalars with length inside its multiplicity. <span class="docutils literal">[]</span> explicitly supplies an empty
|
||
collection and requires minimum 0, including Value Record fields; a nonempty
|
||
Record literal rejects. Reference fields MUST use <span class="docutils literal">none</span>. A one-valued scalar
|
||
field uses a one-value list. A named type default supplies an individual element's
|
||
default, not a collection or an implicit instance of a mandatory field.</p>
|
||
<p>Numeric types may carry unit text. Empty field units inherit the named type unit;
|
||
an explicit different unit warns when that type has a unit. Units on nonnumeric
|
||
fields/types warn and remain preserved. Unit strings never convert values or
|
||
establish dimensional compatibility. Expressions are not executed.</p>
|
||
<p>Record, ExchangeItem and Interface each permit one same-family, same-layer
|
||
supertype. Specialization is acyclic and separate from containment. Effective
|
||
fields are base fields followed by local fields, preserving original field UUIDs
|
||
and owners. Local names MUST NOT shadow inherited names. Item specialization
|
||
preserves base nature and any specified mechanism; an Unspecified base mechanism
|
||
may be refined. Deleting a derived record never deletes its base. Mandatory
|
||
Value-field cycles warn <span class="docutils literal">record_no_finite_value</span>; optional or Reference cycles
|
||
are valid without that warning. Traversal is cycle guarded and bounded; a payload
|
||
path budget failure is an explicit diagnostic, not silent truncation.</p>
|
||
<p>InterfaceItemAllocation is an ordinary identified relation from Interface to
|
||
ExchangeItem. It stores <span class="docutils literal">order</span> and independent transmission/acquisition
|
||
protocols. Transmission is Unspecified, Synchronous, Asynchronous, Unicast,
|
||
Multicast or Broadcast; acquisition is Unspecified, Read or Accept. No protocol
|
||
combination is inferred from mechanism. Effective allocations are base-first,
|
||
then local ordered by (order, alias, UUID). A local item already allocated locally
|
||
or inherited is an error. Removing an allocation keeps its item and other
|
||
allocations; if live boundary compatibility would break, the transaction MUST
|
||
repair the affected contract explicitly or reject atomically. Artifacts can
|
||
reference the allocation identity independently of the global item.</p>
|
||
<p>An exchange carrying a specialized item satisfies a declaration of its base,
|
||
never the reverse. Standard provided/required compatibility uses explicit
|
||
interface ancestry. Identity/ancestry, not matching names, defines conformance.
|
||
The current typed function/component port contracts remain unchanged.</p>
|
||
<p>DataAssociation connects Record types without adding fields or transitively
|
||
carrying payload. Each named end has role, multiplicity and navigability. Source
|
||
multiplicity counts source instances per target instance and vice versa; it is
|
||
not a count of model elements. An end's navigable flag permits navigation toward
|
||
that end. Self-associations are valid; if both ends are navigable they require
|
||
distinct nonempty roles. Empty roles and duplicate role contracts warn, whereas
|
||
invalid ranges reject. Composition/shared aggregation, multiple inheritance,
|
||
redefinition, instance literals and arbitrary-precision decimal arithmetic are
|
||
outside this bounded contract.</p>
|
||
<p>This complete data contract example is also exercised through the REST API:</p>
|
||
<pre class="code text literal-block"><code>arcadia 4;
|
||
project engineering_data "Engineering data" {
|
||
sa_data_type voltage "Voltage" {
|
||
definition { Real { minimum 0.0; maximum 48.0; }; };
|
||
default { Real 24.0; }; unit "V";
|
||
}
|
||
sa_data_type coordinate "Coordinate" {
|
||
definition { Record { supertype none; }; };
|
||
sa_data_field latitude "Latitude" { type_ref Real; }
|
||
}
|
||
sa_data_type located "Located asset" {
|
||
definition { Record { supertype @coordinate; }; };
|
||
sa_data_field supply "Supply" { type_ref { Named @voltage; }; }
|
||
}
|
||
sa_exchange_item navigate "Navigate" {
|
||
mechanism Operation;
|
||
sa_data_field origin "Origin" { type_ref { Named @coordinate; }; direction In; }
|
||
sa_data_field destination "Destination" { type_ref { Named @coordinate; }; direction In; }
|
||
sa_data_field accepted "Accepted" { type_ref Boolean; direction Return; }
|
||
}
|
||
sa_interface navigation "Navigation" {}
|
||
sa_interface monitoring "Monitoring" {}
|
||
interface_item_allocation nav_operation "Navigation operation" {
|
||
source @navigation; target @navigate; transmission Synchronous; acquisition Accept;
|
||
}
|
||
interface_item_allocation monitor_operation "Monitoring operation" {
|
||
source @monitoring; target @navigate; transmission Asynchronous; acquisition Read;
|
||
}
|
||
data_association location_link "Location relationship" {
|
||
source @coordinate; target @located;
|
||
source_role "location"; target_role "assets";
|
||
source_maximum 1;
|
||
}
|
||
}</code></pre>
|
||
</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),
|
||
<span class="docutils literal">projection</span> (Overview by default), and <span class="docutils literal">routes</span> (empty list by default).
|
||
The string projections are Overview, Decomposition, Allocation,
|
||
FunctionalDataflow, Capabilities, and Traceability. StateMachine is a payload
|
||
constructor with one required <span class="docutils literal">machine</span> reference. Traceability diagrams
|
||
can show both layers; other diagrams show their chosen layer.</p>
|
||
<p>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.</p>
|
||
<p>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 <span class="docutils literal">state_diagram_context</span>; incompatible placements use
|
||
<span class="docutils literal">state_diagram_member</span>. Neither case silently hides invalid members.</p>
|
||
<p>This complete source example places one state from an existing machine:</p>
|
||
<pre class="code text literal-block"><code>arcadia 4;
|
||
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; }
|
||
}</code></pre>
|
||
<p>The JSON projection is
|
||
<span class="docutils literal"><span class="pre">{"StateMachine":{"machine":"11111111-1111-4111-8111-111111111111"}}</span></span>,
|
||
where the UUID is the referenced machine's identity. A bare <span class="docutils literal">"StateMachine"</span>,
|
||
a missing or null <span class="docutils literal">machine</span>, an invalid UUID, or additional payload fields
|
||
is malformed. Existing projections retain their string representation, for
|
||
example <span class="docutils literal">"Overview"</span> in JSON and <span class="docutils literal">projection Overview;</span> in source.</p>
|
||
<p>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.</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), and <span class="docutils literal">port_anchors</span> (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.</p>
|
||
<p>Each <span class="docutils literal">port_anchors</span> entry is a PortAnchor record with required <span class="docutils literal">port</span>
|
||
reference, <span class="docutils literal">side</span> (Left, Right, Top, or Bottom), and <span class="docutils literal">offset</span> (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 <span class="docutils literal">element</span>. A port MAY
|
||
have one manual anchor per placement; different diagrams MAY position it
|
||
independently. List order is preserved but has no positional meaning.</p>
|
||
<p><span class="docutils literal">offset</span> 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 <span class="docutils literal">[]</span>.</p>
|
||
<pre class="code text literal-block"><code>node actor_view {
|
||
diagram @architecture; element @vessel;
|
||
port_anchors [{ port @communication; side Top; offset 0.25; }];
|
||
}</code></pre>
|
||
<p><span class="docutils literal">SetPortAnchor { diagram, node, anchor }</span> upserts by port identity and retains
|
||
unrelated entries. <span class="docutils literal">RemovePortAnchor { diagram, node, port }</span> 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 <span class="docutils literal">ParseLimits.max_records</span>.</p>
|
||
<p>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
|
||
<span class="docutils literal">port_anchors</span>; their explicit migration supplies an empty list.</p>
|
||
<p>Each <span class="docutils literal">routes</span> entry is an EdgeRoute record with a required <span class="docutils literal">edge</span> reference
|
||
to an existing Relation or Trace, <span class="docutils literal">waypoints</span> (default <span class="docutils literal">[]</span>), and <span class="docutils literal">label</span>
|
||
(default <span class="docutils literal">none</span>). 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.</p>
|
||
<pre class="code text literal-block"><code>routes [
|
||
{ edge @report_exchange;
|
||
waypoints [{ x 420; y 260; }, { x 690; y 260; }];
|
||
label { fraction 0.55; offset { x 0; y -16; }; };
|
||
}
|
||
];</code></pre>
|
||
<p>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
|
||
<span class="docutils literal">fraction</span> (finite binary32 from 0 through 1, measured along the computed
|
||
polyline's arc length) and <span class="docutils literal">offset</span> (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 <span class="docutils literal">ParseLimits.max_records</span>; pinned
|
||
points are bounded by the per-route limit and aggregate input byte limits.</p>
|
||
<p><span class="docutils literal">SetEdgeRoute { diagram, route }</span> upserts an entry by edge identity, retaining
|
||
the order and contents of unrelated entries. <span class="docutils literal">RemoveEdgeRoute { diagram, edge }</span>
|
||
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 <span class="docutils literal">EditNode</span> and source position edits are exact
|
||
record edits and do not implicitly translate pins.</p>
|
||
<p>This is an additive schema-3 field. Earlier schema-3 JSON/source that omits
|
||
<span class="docutils literal">routes</span> 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 <span class="docutils literal">edge @alias</span> 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.</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">"...";</span> description <span class="pre">"...";</span> }; sa { name <span class="pre">"...";</span> description <span class="pre">"...";</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">@</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"><span class="pre">element-kind</span></span> and <span class="docutils literal"><span class="pre">relation-kind</span></span> are exactly the corresponding declaration
|
||
keywords listed above. Typed field
|
||
sets and enum constructors are closed by sections 3–5.</p>
|
||
<pre class="code text literal-block"><code>document = "arcadia" "4" ";" 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)*)? "]"</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, accepted source 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">@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">@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 id="modular-source-projects">
|
||
<h3>6.1. Modular source projects</h3>
|
||
<p>The pure <span class="docutils literal">source_project</span> core API compiles a virtual source bundle, containing
|
||
<span class="docutils literal">entry</span> and a <span class="docutils literal">files</span> map from logical paths to UTF-8 strings. Its entry is a
|
||
root-level <span class="docutils literal">.arcadia</span> file with the source4 project header above. A project entry
|
||
MAY also be <span class="docutils literal">include string ";"</span>. An included fragment consists only of ordinary
|
||
declarations and include statements; it MUST NOT contain another version header,
|
||
project wrapper, or project description. Includes MUST occur at document level,
|
||
never inside an element body or typed field value. For example:</p>
|
||
<pre class="literal-block">arcadia 4;
|
||
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";
|
||
}</pre>
|
||
<p>An include path is relative to its containing file. <span class="docutils literal">.</span> and <span class="docutils literal">..</span> segments
|
||
normalize within the virtual project root; escaping that root is an error. Bundle
|
||
keys MUST already be normalized, use forward slashes and the lowercase
|
||
<span class="docutils literal">.arcadia</span> suffix, and contain no empty path segments. Absolute, drive, UNC,
|
||
URL, backslash, control-character and non-portable Windows device paths are
|
||
rejected. Paths ending a segment in dot or space are rejected. Keys that collide
|
||
after Unicode lowercasing are rejected. References use the exact normalized
|
||
spelling; filesystems do not participate in resolution.</p>
|
||
<p>Every reachable file is compiled once, including through repeated or diamond
|
||
includes. Include cycles are errors with their chain and including location.
|
||
Missing files, duplicate JSON file keys and supplied unreachable files are
|
||
errors. The compiler MUST NOT read local files, network resources, environment
|
||
variables or the process working directory. The native loader is responsible
|
||
for translating a directory into this explicit bundle and enforcing physical
|
||
path ownership; the pure compiler grants no filesystem access.</p>
|
||
<p><span class="docutils literal">inspect_includes(path, source, is_entry, limits)</span> supports native discovery
|
||
before all included documents are available. It uses the same strict entry or
|
||
fragment syntax parser, applies document byte/record and local include-edge
|
||
budgets, and returns normalized targets with exact directive spans. Comments and
|
||
strings that mention include syntax are not directives. A syntax failure anywhere
|
||
in the document returns located errors and no partial include list; it does not
|
||
scan arbitrary token strings after failure. Global references and engineering
|
||
validation are deferred to bundle compilation. A native loader MUST retain the
|
||
unparsed draft on failure and enforce aggregate bytes/files/depth/edges while
|
||
loading; this inspection call does not own or inspect a directory.</p>
|
||
<p>All files share the existing global alias/UUID namespace. Files add no semantic
|
||
namespace, implicit parent, allocation or port contract. Forward references work
|
||
across files. Duplicate aliases and identities report the offending declaration
|
||
and the previous declaration location, including collisions with the project.
|
||
Moving a declaration between files MUST preserve the resulting model and UUIDs.</p>
|
||
<p><span class="docutils literal">ProjectLimits</span> adds file, include-depth and include-edge budgets to the existing
|
||
<span class="docutils literal"><span class="pre">language::ParseLimits</span></span>. Model bytes, graph objects, records and ordered
|
||
references are counted across the complete bundle, never reset per file. The
|
||
default candidate policy is 256 files, depth 32 (entry depth zero), 1,024 include
|
||
edges and 64 MiB combined UTF-8 source. Other model counts remain caller policy.
|
||
Repeated include edges count toward the edge budget; file contents count once.
|
||
The compiler admits input and stabilized output against the same limits.</p>
|
||
<p><span class="docutils literal">compile_bundle</span> returns either located errors and no candidate, or a
|
||
<span class="docutils literal">CompiledSourceProject</span> with the validated <span class="docutils literal">DecodeResult</span>, stabilized bundle,
|
||
derived <span class="docutils literal">SourceIndex</span> and located engineering warnings. It inserts explicit
|
||
UUID clauses into headers that omitted them without otherwise reformatting the
|
||
input. The returned source index and diagnostics address the returned stabilized
|
||
bytes. Clients MUST retain that bundle after successful Apply; recompiling the
|
||
original buffers with missing identities would generate fresh identities.</p>
|
||
<p>Bundle diagnostics wrap the existing Diagnostic with a logical path and optional
|
||
related locations. Declaration spans, own-field value spans, lexical owners,
|
||
declaration bodies, project header/body/description spans and resolved includes are available in
|
||
the source index. Columns remain one-based Unicode scalars within the real file;
|
||
spans never refer to concatenated or synthetic source.</p>
|
||
<p>Single-string parse/lint APIs remain filesystem-free and reject include
|
||
statements with an explicit source-bundle requirement. V1/V2 single-file imports
|
||
continue through explicit migration. Modular projects accept source3 and source4;
|
||
source3 is upgraded as one project, preserving file paths, includes, nested
|
||
ownership and comments through targeted token edits. Generated allocation
|
||
declarations stay in their interface's existing file. Individual include fragments
|
||
are not independently migrated. Missing UUIDs stabilize before migration so new
|
||
allocation identities are deterministic on subsequent compilation.</p>
|
||
</section>
|
||
<section id="nested-element-ownership">
|
||
<h3>6.2. Nested element ownership</h3>
|
||
<p>An element body MAY contain element declarations interleaved with its ordinary
|
||
fields. Its immediate enclosing element is its lexical owner. For example:</p>
|
||
<pre class="literal-block">sa_actor harbor "Harbor operator" {
|
||
sa_port radio "Radio" {
|
||
contract { Component { kind Standard; orientation Unset; }; };
|
||
}
|
||
}</pre>
|
||
<p>Nesting expresses semantic <span class="docutils literal">Element.parent</span> only. It does not allocate a
|
||
function to an actor or System, deploy equipment, or add or reorder occurrence
|
||
references in an owner's explicit <span class="docutils literal">steps</span> list. Those relationships retain
|
||
their explicit records and fields. The
|
||
same parent-kind, layer and acyclicity constraints apply as for flat source.
|
||
Only element declarations can nest: relations, diagrams, placements, artifacts,
|
||
traces and include directives remain at document level. A typed record value
|
||
contains fields, never element declarations.</p>
|
||
<p>If a nested declaration omits <span class="docutils literal">parent</span>, it inherits its lexical owner's UUID.
|
||
An explicit <span class="docutils literal">parent</span> MUST reference that owner; another reference or <span class="docutils literal">none</span>
|
||
is an error located at the parent value. At document level, omitted <span class="docutils literal">parent</span>
|
||
means <span class="docutils literal">none</span> and explicit parent references retain their existing meaning.
|
||
Nesting creates no alias namespace. Aliases and UUIDs remain globally unique,
|
||
and references can target nested declarations before or after their definition
|
||
or from another included file. Identity stabilization inserts missing UUIDs in
|
||
nested headers just as it does in document-level headers.</p>
|
||
<p>Source positions distinguish each declaration's own fields from its descendants'
|
||
fields. A declaration's body span encloses its lexical children as well as its
|
||
own fields. An inherited parent has no synthetic source token or field span.
|
||
Located diagnostics and editor navigation MUST address real source bytes.</p>
|
||
</section>
|
||
</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 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.</p>
|
||
<p>The pure <span class="docutils literal">format_bundle</span> exporter uses the same typed declaration writer as
|
||
<span class="docutils literal">format</span>. 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, <span class="docutils literal"><span class="pre">compile_bundle(format_bundle(P)).decoded.project</span> == P</span>
|
||
when the caller supplies sufficient admission budgets.</p>
|
||
<p><span class="docutils literal">update_bundle(compiled, P, limits)</span> 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.</p>
|
||
<p>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.</p>
|
||
<p>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
|
||
<span class="docutils literal">@</span> 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.</p>
|
||
<p>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.</p>
|
||
<p>List entries use stable referenced UUIDs, message-value <span class="docutils literal">field</span> references or
|
||
lifeline-binding <span class="docutils literal">referenced</span> 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.</p>
|
||
<p>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 <span class="docutils literal">update_bundle</span> treats an
|
||
explicit UUID replacement as removal and creation. The desktop instead uses
|
||
<span class="docutils literal">update_bundle_with_identity_map</span> with the surviving-record provenance from
|
||
<span class="docutils literal">prepare_command</span>: 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.</p>
|
||
<p>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 <span class="docutils literal"><span class="pre">source-project</span></span> 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 <span class="docutils literal">source</span> endpoints remain explicit model interchange. The precise
|
||
transport, admission and persistence contract is in <span class="docutils literal">api.rst</span>.</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">@</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 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.</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 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.</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-explicit-migration">
|
||
<h2>9. Persistence and explicit 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
|
||
the accepted V4 source bundle (<span class="docutils literal">arcadia 4</span>); other suffixes use V4 JSON. Both forms preserve the same
|
||
complete model. JSON rejects unknown fields throughout typed payloads,
|
||
duplicate maps, unsupported versions, and structural errors.</p>
|
||
<p>The schema-3 reader freezes the changed data payloads and old constructor catalog;
|
||
schema-4 fields/constructors MUST NOT be silently accepted as schema 3. Existing
|
||
typed PortContract records remain unchanged. Information/Material/Energy retain
|
||
their nature with Unspecified mechanism; old Event becomes Information with Event
|
||
mechanism. Old bounds/defaults/supertypes are absent, String length is 0..unbounded,
|
||
and fields retain type/multiplicity/unit with Unspecified direction, Value storage
|
||
and no explicit default. No physical mechanism or direction is guessed.</p>
|
||
<p>Each old Interface.items entry generates one InterfaceItemAllocation with its
|
||
original zero-based order and Unspecified protocols. UUID v5 uses the project UUID
|
||
namespace and name <span class="docutils literal"><span class="pre">v2-interface-item:<interface-uuid>:<item-uuid></span></span> consistently
|
||
for schema-2 and schema-3 inputs. Aliases are deterministic and collision-free;
|
||
collision with any existing identity is an error rather than an overwrite. Existing
|
||
interface/item identities remain intact. Old nested message values acquire a path
|
||
only when exactly one valid path exists. Ambiguous paths, including recursive
|
||
reuse, retain the old annotation with a located warning rather than guessing.</p>
|
||
<p>Migration reports additionally contain <span class="docutils literal">semantic_defaults</span> (object, field,
|
||
description), <span class="docutils literal">generated_interface_allocations</span> (id, source, target, alias,
|
||
order) and <span class="docutils literal">unresolved_message_values</span> (occurrence, field, reason). These new
|
||
report arrays default empty when reading older responses. Version 1 normalizes
|
||
through V2, then the typed-port V3 adapter and this shared V4 data upgrade. Original
|
||
V2 and real V3 fixtures remain unchanged compatibility inputs. Current exports
|
||
always use version 4; reading/migrating alone never saves or changes revisions.</p>
|
||
<p>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.</p>
|
||
<p>The frozen schema-2 reader retains staged compatibility defaults. 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 through the explicit schema-3 and schema-4 migrations.</p>
|
||
<p>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 <span class="docutils literal"><span class="pre">v2-fe-port:<fe-id>:source</span></span> or <span class="docutils literal"><span class="pre">v2-fe-port:<fe-id>:target</span></span>. 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 <span class="docutils literal">oriented true</span>; no
|
||
PortAllocation is inferred.</p>
|
||
<p><span class="docutils literal">decode_with_report</span>, <span class="docutils literal">load_with_report</span> 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 4. Model/source exports contain only the canonical model. Migration
|
||
reports are transient response metadata, not persisted model facts.</p>
|
||
<p>Admission checks account for generated objects and their references before
|
||
construction. Both the old V2 contract and the resulting V4 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 these same V2-to-3-to-4 stages.</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 V4 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
|
||
V4 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 4;
|
||
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; };
|
||
}
|
||
}</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&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>
|