sorokin.oleg.edu/ARCADIA-Studio
1
0
Fork 0
Code Issues 37 Pull Requests 2 Packages Projects Releases 9 Wiki Activity

Checkpoint source 7 workflows and in-progress diagram authoring redesign
Rust checks / check (ubuntu-latest) (push) Canceled after 0s
Rust checks / check (windows-latest) (push) Canceled after 0s

Browse Source 
Preserve current core, source, REST, desktop, recovery, documentation and validation work, including AGENTS.md and the development summary. This is a work-in-progress checkpoint: the new compact palette has outstanding compilation errors and native acceptance; earlier passing gates retain their documented scope.
This commit is contained in:
Codex
2026-09-10 10:06:55 -07:00
parent 4b6b5fc197
commit e2ecfea69b
162 changed files with 17595 additions and 926 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api.html
+113 -9
View File
@@ -2,7 +2,7 @@
<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="generator" content="Docutils 0.22.2: https://docutils.sourceforge.io/" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Arcadia Studio model REST API</title>
<style type="text/css">
@@ -796,8 +796,8 @@ candidate validation reports the same diagnostic in its 200 response.
Parsing, validation and query processing use snapshot workers, so this work
does not hold the catalog lock or serialize unrelated model preparation.</p>
<p>Import accepts schema-1 JSON through the shared explicit migration adapter,
as well as schema-2, schema-3, schema-4 and current schema-5 JSON. Source import uses the shared language parser
and its supported migrations. Export uses schema 5 / arcadia 5. Native JSON
as well as schema-2, schema-3, schema-4, schema-5, schema-6 and current schema-7 JSON. Source import uses the shared language parser
and its supported migrations. Export uses schema 7 / arcadia 7. Native JSON
replacement accepts supported older schemas through the same explicit migration.
Only documented query parameters are accepted. In particular, appending
<span class="docutils literal"><span class="pre">?revision=...</span></span> to model/source export is an error, not historical retrieval.</p>
@@ -808,7 +808,7 @@ Only documented query parameters are accepted. In particular, appending
<pre class="literal-block">{
&quot;entry&quot;: &quot;rescue.arcadia&quot;,
&quot;files&quot;: {
&quot;rescue.arcadia&quot;: &quot;arcadia 5; project rescue \&quot;Rescue\&quot; { include \&quot;oa/work.arcadia\&quot;; }\n&quot;,
&quot;rescue.arcadia&quot;: &quot;arcadia 7; project rescue \&quot;Rescue\&quot; { include \&quot;oa/work.arcadia\&quot;; }\n&quot;,
&quot;oa/work.arcadia&quot;: &quot;// Engineering rationale\noa_activity assess \&quot;Assess assistance\&quot; {}\n&quot;
}
}</pre>
@@ -819,7 +819,7 @@ targets or another hosted resource. All submitted files must be reachable;
missing files, cycles, duplicate keys, case collisions and escaping paths are
rejected. The bundle permits at most 256 files, 32 include edges along a path,
and 1,024 include edges in total. Model and source-byte budgets apply across
the complete bundle, not separately per file. Current bundle syntax is source5; source3/4 bundles migrate explicitly while
the complete bundle, not separately per file. Current bundle syntax is source7; source3/4/5/6 bundles migrate explicitly while
preserving their files/includes/comments. V1/V2 single-file migration remains
available through interchange import.</p>
<p>Compilation inserts UUIDs into headers that omit them. Import returns 201 with
@@ -972,6 +972,35 @@ replacement routes as other engineering records. For example,
The source representation uses <span class="docutils literal">sequence &#64;alias</span> references. The service
does not execute conditions or simulate a process.</p>
</section>
<section id="caller-qualified-process-and-chain-links">
<h2>Caller-qualified process and chain links</h2>
<p>Schema 7 adds the closed <span class="docutils literal">RelationBody.ContextualLink</span> payload:</p>
<pre class="literal-block">{
&quot;ContextualLink&quot;: {
&quot;owner&quot;: &quot;&lt;caller process UUID&gt;&quot;,
&quot;source&quot;: {&quot;references&quot;: [], &quot;occurrence&quot;: &quot;&lt;direct X occurrence UUID&gt;&quot;},
&quot;target&quot;: {&quot;references&quot;: [&quot;&lt;R1 reference occurrence UUID&gt;&quot;],
&quot;occurrence&quot;: &quot;&lt;B occurrence UUID in referenced definition&gt;&quot;},
&quot;purpose&quot;: {&quot;Precedence&quot;: {&quot;guard&quot;: &quot;check accepted&quot;}}
}
}</pre>
<p><span class="docutils literal">references</span> is an ordered path of reference-occurrence IDs, never sequence
definition IDs; at most 64entries per endpoint. The explicit owner determines
context and source placement. <span class="docutils literal">purpose</span> is exactly Precedence with string
guard, Exchange with work-exchange UUID, or CommonWork with work UUID. Only
Precedence contributes ordering; the other purposes preserve assembly incidence.
Both paths empty with Precedence must use the existing SequenceLink constructor.
Query these records with <span class="docutils literal"><span class="pre">relations?kind=ContextualLink</span></span>. Ordinary create/edit,
source replacement and JSON replacement share the same owner/path/purpose checks.</p>
<p>R1.B and R2.B remain separate caller contributions even if B has one definition
UUID. Deleting a typed path/leaf/owner/purpose dependency removes the whole link;
retargeting an invalid surviving link requires explicit repair. No path shortening,
implicit work duplication or fallback to a whole reference is permitted. Authored
path entries count toward the 50,000 ordered-reference budget. Resolver cache state
does not change validity. Contextual analysis has separate 50,000 node/100,000 edge
limits and explicitly reports incomplete expansion. See language.rst4.2.1 for
caller-qualified diagnostics and synthetic-boundary rules.</p>
</section>
<section id="typed-scenarios-and-message-values">
<h2>Typed scenarios and message values</h2>
<p>Scenario bodies store an explicit <span class="docutils literal">viewpoint</span>. Occurrence Exchange bodies
@@ -1011,7 +1040,7 @@ contract in the same transaction when removing a used interface allocation.</p>
<p>Explicit schema1/2/3 migration preserves prior identities and typed ports. Reports
add semantic defaults, generated interface allocations and unresolved message
values. Old source3 bundles retain files/includes/comments during upgrade; all
current exports use schema5/source5. Reading an old envelope does not write it or
current exports use schema7/source7. Reading an old envelope does not write it or
advance its ETag. Canonical exports omit transient migration reports.</p>
</section>
<section id="validation">
@@ -1021,7 +1050,7 @@ advance its ETag. Canonical exports omit transient migration reports.</p>
<p>or:</p>
<pre class="literal-block">{&quot;format&quot;:&quot;arcadia&quot;, &quot;source&quot;:&quot;complete source document&quot;}</pre>
<p>or:</p>
<pre class="literal-block">{&quot;format&quot;:&quot;source-project&quot;, &quot;source_project&quot;:{&quot;entry&quot;:&quot;rescue.arcadia&quot;, &quot;files&quot;:{&quot;rescue.arcadia&quot;:&quot;arcadia 5; project rescue \&quot;Rescue\&quot; {}&quot;}}}</pre>
<pre class="literal-block">{&quot;format&quot;:&quot;source-project&quot;, &quot;source_project&quot;:{&quot;entry&quot;:&quot;rescue.arcadia&quot;, &quot;files&quot;:{&quot;rescue.arcadia&quot;:&quot;arcadia 7; project rescue \&quot;Rescue\&quot; {}&quot;}}}</pre>
<p>A well-formed validation request returns 200 with <span class="docutils literal">valid</span> and <span class="docutils literal">issues</span> even
if its candidate is invalid, including a model record that fails typed decoding.
Malformed request JSON or an invalid format/payload envelope is a 400.
@@ -1084,15 +1113,89 @@ Other projections continue to preserve hidden placements. Rejected writes
retain the accepted model, source bundle, revision and ETag. Reading a state
view has no semantic or persistence side effects.</p>
</section>
<section id="source-6-communication-and-saved-views">
<h2>Source-6 communication and saved views</h2>
<p>The same import, replacement and command endpoints admit OA
<span class="docutils literal">CommunicationMean { source, target, oriented, items }</span> and root-level
<span class="docutils literal">ExchangeCategory { family, exchanges }</span> records. Communication means join
distinct OA entities/actors. Categories group same-layer exchanges as <span class="docutils literal">Work</span>
or <span class="docutils literal">Participant</span> without owning them. Existing legacy OA boundary exchanges
retain their identities and contracts; migration does not silently replace them.</p>
<p><span class="docutils literal">Diagram.view_options</span> is an optional closed object with defaults: empty
<span class="docutils literal">hidden_edges</span>, <span class="docutils literal">All</span> for <span class="docutils literal">relation_kinds</span>, both category selections,
<span class="docutils literal">coverage</span> and <span class="docutils literal">work_contexts</span>, and <span class="docutils literal">Name</span> for <span class="docutils literal">exchange_labels</span>.
<span class="docutils literal"><span class="pre">{&quot;Only&quot;:[]}</span></span> hides all relation and trace lines; <span class="docutils literal"><span class="pre">{&quot;Any&quot;:[]}</span></span> preserves
an explicit empty category/context selection. Category members union within
each family, and independent filters intersect. <span class="docutils literal">Traceability</span> permits
references from both layers; ordinary projections require the diagram's layer.
These presentation choices preserve semantic records, routes, placements and
the automatic port positions derived from unfiltered eligible exchanges.</p>
<p>Schema/source versions 1–5 reject the new constructors, category review
facts and explicit <span class="docutils literal">view_options</span> field, including an empty object. Their
frozen readers migrate accepted content to schema/source 7 with default view
options. The OpenAPI document describes current records; it is not a permissive
union of historical input formats. Source-7 integration and release acceptance
are tracked separately in the release coverage audit.</p>
</section>
<section id="explicit-interface-operation-identity">
<h2>Explicit interface-operation identity</h2>
<p><span class="docutils literal">OccurrenceBody.Exchange.operation</span> is optional. Absent/null retains ordinary
channel semantics and is omitted in canonical output. <span class="docutils literal"><span class="pre">{&quot;allocation&quot;:null}</span></span>
(or an empty object) retains explicit unresolved operation intent. A selected
<span class="docutils literal"><span class="pre">{&quot;allocation&quot;:&quot;&lt;InterfaceItemAllocation</span> <span class="pre">UUID&gt;&quot;}</span></span> identifies that exact
allocation, including for parameterless operations sharing one channel. These
records are closed; unknown fields are rejected. Earlier schema/source versions
reject the operation field even when explicitly null and reject ContextualLink
and their new semantic facets. Migration never guesses an operation from names,
message values or a channel's item set.</p>
<p>Selection is valid only for SA BoundaryInterface Call/Asynchronous messages.
Core proves actual Standard component-port Requires/Provides roles, compatible
interfaces exposing the same allocation, actual channel direction and allowed
transmission protocol. Reply stores no operation and derives it from its exact
Call; a separate return channel still needs its own valid carried-item/endpoint
contract, including a void return. Selected message values use the exact operation
signature. Unresolved intent preserves live expressions and checks their paths
with an incomplete-signature warning; it does not substitute the channel union.</p>
<p>Allocation deletion clears selection to unresolved only within an otherwise
valid whole candidate. Removing the sole allocation can refuse atomically while
a channel still carries its now-unadmitted item; repair every affected channel
explicitly in the same batch. A surviving same-item allocation may keep a channel
valid, but is never silently selected. Reselection validates retained values
without pruning them. The service uses the same source/history boundary as
graphical editing. See language.rst4.3.1 for the complete contract.</p>
</section>
<section id="cross-layer-transitions">
<h2>Cross-layer transitions</h2>
<p>Preview accepts the shared <span class="docutils literal">TransitionRequest</span> record, including direction
(<span class="docutils literal">OaToSa</span> or <span class="docutils literal">SaToOa</span>), sources, dependency scope, mappings, selected fields,
conflict resolutions and optional destination diagram. All fields are explicit
in OpenAPI. At most 100 sources, 200 mappings and 400 field resolutions are
in OpenAPI. At most 100 sources, 200 mappings, 200 communication endpoint
decisions, 200 operation omissions and 400 field resolutions are
accepted. A conflict-free plan must fit the same 200-command transaction limit
and model/source-capacity limits. A conflict-free preview also checks source
writeback, so its commands can update the same accepted authored workspace.</p>
<p>SA→OA abstraction of explicit operation intent requires <span class="docutils literal">operation_omissions</span>
(omitted means empty). Each closed record contains the selected invocation's
<span class="docutils literal">source</span> UUID and a nonempty <span class="docutils literal">rationale</span> string. Missing, duplicate,
irrelevant or wrong-direction omissions reject. Reply derives its Call's
abstraction and has no second writable operation choice. Source operation
identity/values remain intact; target facts are mapped and validated. Preview
and Apply enforce the same 200 omission limit for ordinary and semantic transitions.</p>
<p>OA <span class="docutils literal">CommunicationMean</span> maps to an SA <span class="docutils literal">BoundaryExchange</span> through an explicit
<span class="docutils literal">communication_endpoints</span> array (omitted means empty). Each decision identifies
the source communication means and both <span class="docutils literal">source_port</span> and <span class="docutils literal">target_port</span>.
Each port choice is either <span class="docutils literal"><span class="pre">{&quot;Reuse&quot;:{&quot;port&quot;:&quot;port-uuid&quot;}}</span></span> or
<span class="docutils literal"><span class="pre">{&quot;Create&quot;:{&quot;id&quot;:&quot;new-port-uuid&quot;,&quot;alias&quot;:&quot;radio_port&quot;,&quot;name&quot;:&quot;Radio</span> port&quot;, <span class="pre">&quot;description&quot;:&quot;&quot;,&quot;kind&quot;:&quot;Standard&quot;,&quot;orientation&quot;:&quot;Unset&quot;}}</span></span>. Created or
reused SA component ports must belong to the explicitly mapped participants.
These per-exchange choices do not replace participant correspondence with port
IDs. Missing or incompatible choices remain preview conflicts. Interface and
functional-port allocations use their existing explicit workflows; an engineer
may omit an unresolved allocation from this transition. Reverse transition maps
boundary ports through their owners to OA participants.</p>
<p><span class="docutils literal">ExchangeCategory</span> transitions preserve their family and map only explicitly
corresponding member exchanges. Missing member mappings are conflicts, not new
fabricated exchanges. Typed review exposes <span class="docutils literal">Category.Family</span> and the
<span class="docutils literal">CategoryExchanges</span> member collection; historical review facts remain exact.</p>
<p>The preview response is <span class="docutils literal"><span class="pre">{&quot;base_revision&quot;:1,&quot;plan&quot;:{...}}</span></span>. It contains
planned changes, conflicts, warnings and exact commands/IDs. It does not write
the model or persist a server-side plan. Apply accepts that entire response and
@@ -1192,7 +1295,8 @@ not persist plans, tokens or review sessions.</p>
<p>Requests allow 100 sources, trace choices and reviews; 200 mappings, candidates
and accepted impacts; 5,000 canonical reference mappings; and 5,000 facet
resolutions plus resets across all reviews. The legacy 400 prose-resolution
limit and 200-command transaction limit still apply. Query has the same 5,000
limit, 200 communication endpoint decisions, 200 operation omissions and
200-command transaction limit still apply. Query has the same 5,000
reference-map limit. Core bounded linked traversal errors remain observable as
semantic rejection; no truncated result silently claims complete review.</p>
<p>Schema/source 5 adds <span class="docutils literal">TraceBaseline.semantic</span>. Absence or null is Unreviewed;
docs/api.rst
+84 -12
View File
@@ -155,8 +155,8 @@ Parsing, validation and query processing use snapshot workers, so this work
does not hold the catalog lock or serialize unrelated model preparation.
Import accepts schema-1 JSON through the shared explicit migration adapter,
as well as schema-2, schema-3, schema-4, schema-5 and current schema-6 JSON. Source import uses the shared language parser
and its supported migrations. Export uses schema 6 / arcadia 6. Native JSON
as well as schema-2, schema-3, schema-4, schema-5, schema-6 and current schema-7 JSON. Source import uses the shared language parser
and its supported migrations. Export uses schema 7 / arcadia 7. Native JSON
replacement accepts supported older schemas through the same explicit migration.
Only documented query parameters are accepted. In particular, appending
``?revision=...`` to model/source export is an error, not historical retrieval.
@@ -169,7 +169,7 @@ A source bundle contains ``entry`` and a map of ``files``. For example::
{
"entry": "rescue.arcadia",
"files": {
"rescue.arcadia": "arcadia 6; project rescue \"Rescue\" { include \"oa/work.arcadia\"; }\n",
"rescue.arcadia": "arcadia 7; project rescue \"Rescue\" { include \"oa/work.arcadia\"; }\n",
"oa/work.arcadia": "// Engineering rationale\noa_activity assess \"Assess assistance\" {}\n"
}
}
@@ -181,7 +181,7 @@ targets or another hosted resource. All submitted files must be reachable;
missing files, cycles, duplicate keys, case collisions and escaping paths are
rejected. The bundle permits at most 256 files, 32 include edges along a path,
and 1,024 include edges in total. Model and source-byte budgets apply across
the complete bundle, not separately per file. Current bundle syntax is source6; source3/4/5 bundles migrate explicitly while
the complete bundle, not separately per file. Current bundle syntax is source7; source3/4/5/6 bundles migrate explicitly while
preserving their files/includes/comments. V1/V2 single-file migration remains
available through interchange import.
@@ -358,6 +358,39 @@ replacement routes as other engineering records. For example,
The source representation uses ``sequence @alias`` references. The service
does not execute conditions or simulate a process.
Caller-qualified process and chain links
----------------------------------------
Schema 7 adds the closed ``RelationBody.ContextualLink`` payload::
{
"ContextualLink": {
"owner": "<caller process UUID>",
"source": {"references": [], "occurrence": "<direct X occurrence UUID>"},
"target": {"references": ["<R1 reference occurrence UUID>"],
"occurrence": "<B occurrence UUID in referenced definition>"},
"purpose": {"Precedence": {"guard": "check accepted"}}
}
}
``references`` is an ordered path of reference-occurrence IDs, never sequence
definition IDs; at most 64entries per endpoint. The explicit owner determines
context and source placement. ``purpose`` is exactly Precedence with string
guard, Exchange with work-exchange UUID, or CommonWork with work UUID. Only
Precedence contributes ordering; the other purposes preserve assembly incidence.
Both paths empty with Precedence must use the existing SequenceLink constructor.
Query these records with ``relations?kind=ContextualLink``. Ordinary create/edit,
source replacement and JSON replacement share the same owner/path/purpose checks.
R1.B and R2.B remain separate caller contributions even if B has one definition
UUID. Deleting a typed path/leaf/owner/purpose dependency removes the whole link;
retargeting an invalid surviving link requires explicit repair. No path shortening,
implicit work duplication or fallback to a whole reference is permitted. Authored
path entries count toward the 50,000 ordered-reference budget. Resolver cache state
does not change validity. Contextual analysis has separate 50,000 node/100,000 edge
limits and explicitly reports incomplete expansion. See language.rst4.2.1 for
caller-qualified diagnostics and synthetic-boundary rules.
Typed scenarios and message values
----------------------------------
@@ -403,7 +436,7 @@ contract in the same transaction when removing a used interface allocation.
Explicit schema1/2/3 migration preserves prior identities and typed ports. Reports
add semantic defaults, generated interface allocations and unresolved message
values. Old source3 bundles retain files/includes/comments during upgrade; all
current exports use schema6/source6. Reading an old envelope does not write it or
current exports use schema7/source7. Reading an old envelope does not write it or
advance its ETag. Canonical exports omit transient migration reports.
Validation
@@ -419,7 +452,7 @@ or::
or::
{"format":"source-project", "source_project":{"entry":"rescue.arcadia", "files":{"rescue.arcadia":"arcadia 6; project rescue \"Rescue\" {}"}}}
{"format":"source-project", "source_project":{"entry":"rescue.arcadia", "files":{"rescue.arcadia":"arcadia 7; project rescue \"Rescue\" {}"}}}
A well-formed validation request returns 200 with ``valid`` and ``issues`` even
if its candidate is invalid, including a model record that fails typed decoding.
@@ -492,7 +525,7 @@ retain the accepted model, source bundle, revision and ETag. Reading a state
view has no semantic or persistence side effects.
Source-6 communication and saved views
-------------------------------------
--------------------------------------
The same import, replacement and command endpoints admit OA
``CommunicationMean { source, target, oriented, items }`` and root-level
@@ -511,13 +544,43 @@ references from both layers; ordinary projections require the diagram's layer.
These presentation choices preserve semantic records, routes, placements and
the automatic port positions derived from unfiltered eligible exchanges.
Earlier schema/source versions reject the new constructors, category review
Schema/source versions 1–5 reject the new constructors, category review
facts and explicit ``view_options`` field, including an empty object. Their
frozen readers migrate accepted content to schema/source 6 with default view
frozen readers migrate accepted content to schema/source 7 with default view
options. The OpenAPI document describes current records; it is not a permissive
union of historical input formats. Source-6 integration and release acceptance
union of historical input formats. Source-7 integration and release acceptance
are tracked separately in the release coverage audit.
Explicit interface-operation identity
-------------------------------------
``OccurrenceBody.Exchange.operation`` is optional. Absent/null retains ordinary
channel semantics and is omitted in canonical output. ``{"allocation":null}``
(or an empty object) retains explicit unresolved operation intent. A selected
``{"allocation":"<InterfaceItemAllocation UUID>"}`` identifies that exact
allocation, including for parameterless operations sharing one channel. These
records are closed; unknown fields are rejected. Earlier schema/source versions
reject the operation field even when explicitly null and reject ContextualLink
and their new semantic facets. Migration never guesses an operation from names,
message values or a channel's item set.
Selection is valid only for SA BoundaryInterface Call/Asynchronous messages.
Core proves actual Standard component-port Requires/Provides roles, compatible
interfaces exposing the same allocation, actual channel direction and allowed
transmission protocol. Reply stores no operation and derives it from its exact
Call; a separate return channel still needs its own valid carried-item/endpoint
contract, including a void return. Selected message values use the exact operation
signature. Unresolved intent preserves live expressions and checks their paths
with an incomplete-signature warning; it does not substitute the channel union.
Allocation deletion clears selection to unresolved only within an otherwise
valid whole candidate. Removing the sole allocation can refuse atomically while
a channel still carries its now-unadmitted item; repair every affected channel
explicitly in the same batch. A surviving same-item allocation may keep a channel
valid, but is never silently selected. Reselection validates retained values
without pruning them. The service uses the same source/history boundary as
graphical editing. See language.rst4.3.1 for the complete contract.
Cross-layer transitions
-----------------------
@@ -525,11 +588,19 @@ Preview accepts the shared ``TransitionRequest`` record, including direction
(``OaToSa`` or ``SaToOa``), sources, dependency scope, mappings, selected fields,
conflict resolutions and optional destination diagram. All fields are explicit
in OpenAPI. At most 100 sources, 200 mappings, 200 communication endpoint
decisions and 400 field resolutions are
decisions, 200 operation omissions and 400 field resolutions are
accepted. A conflict-free plan must fit the same 200-command transaction limit
and model/source-capacity limits. A conflict-free preview also checks source
writeback, so its commands can update the same accepted authored workspace.
SA→OA abstraction of explicit operation intent requires ``operation_omissions``
(omitted means empty). Each closed record contains the selected invocation's
``source`` UUID and a nonempty ``rationale`` string. Missing, duplicate,
irrelevant or wrong-direction omissions reject. Reply derives its Call's
abstraction and has no second writable operation choice. Source operation
identity/values remain intact; target facts are mapped and validated. Preview
and Apply enforce the same 200 omission limit for ordinary and semantic transitions.
OA ``CommunicationMean`` maps to an SA ``BoundaryExchange`` through an explicit
``communication_endpoints`` array (omitted means empty). Each decision identifies
the source communication means and both ``source_port`` and ``target_port``.
@@ -660,7 +731,8 @@ not persist plans, tokens or review sessions.
Requests allow 100 sources, trace choices and reviews; 200 mappings, candidates
and accepted impacts; 5,000 canonical reference mappings; and 5,000 facet
resolutions plus resets across all reviews. The legacy 400 prose-resolution
limit and 200-command transaction limit still apply. Query has the same 5,000
limit, 200 communication endpoint decisions, 200 operation omissions and
200-command transaction limit still apply. Query has the same 5,000
reference-map limit. Core bounded linked traversal errors remain observable as
semantic rejection; no truncated result silently claims complete review.
docs/language.html
+279 -16
View File
@@ -2,7 +2,7 @@
<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="generator" content="Docutils 0.22.2: 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">
@@ -623,9 +623,9 @@ a { text-decoration: none; }
<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">5</dd>
<dd class="version">7 (integration in progress)</dd>
<dt class="status">Status<span class="colon">:</span></dt>
<dd class="status">Normative current implementation contract; first-release integration</dd>
<dd class="status">Source-7 contract under integration; native and API acceptance pending</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>
@@ -637,9 +637,13 @@ a { text-decoration: none; }
<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, 3 and 4. MUST, MUST NOT,
validation, persistence, and explicit migration from versions 1, 2, 3, 4, 5 and 6. MUST, MUST NOT,
and MAY indicate requirements, prohibitions, and permitted choices.</p>
<p>Schema 5 adds closed typed semantic review facts to trace baselines, including
<p>Schema 7 adds caller-qualified process/chain links and explicit interface-operation
selection on boundary scenario invocations. Schema 6 added OA communication means,
exchange categories and saved view options. Integration and acceptance are tracked
separately; this version label does not claim completed graphical/API parity.
Schema 5 added closed typed semantic review facts to trace baselines, including
historical references that may no longer exist in the live model. It retains
schema 4 bounded reusable data types, typed defaults, exchange mechanisms,
qualified values, specialization, interface allocations and associations, and
@@ -663,7 +667,7 @@ 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> (5), <span class="docutils literal">id</span>, <span class="docutils literal">alias</span>, <span class="docutils literal">name</span>,
<p>A Project stores <span class="docutils literal">schema_version</span> (6), <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>
@@ -904,6 +908,10 @@ references. Their kind is the declaration keyword:</p>
<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">communication_mean</span></p></td>
<td><p>Different OA Entity/Actor elements; no operational ports or role inference</p></td>
<td><p><span class="docutils literal">oriented</span> bool / false; <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>
@@ -957,7 +965,7 @@ references. Their kind is the declaration keyword:</p>
<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>CommunicationMean → OA Interaction, or BoundaryExchange → same-layer Interaction/FunctionalExchange</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>
@@ -974,6 +982,79 @@ references. Their kind is the declaration keyword:</p>
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>
<section id="source-6-communication-and-exchange-categories">
<h3>Source-6 communication and exchange categories</h3>
<p>An OA <span class="docutils literal">communication_mean</span> joins two distinct Entity/Actor records directly.
Its stable source/target tuple does not create operational ports. An unoriented
means permits either direction; an oriented ordinary use follows source to target.
The empty carried-item set is explicit, not a wildcard. Every item carried by an
allocated Interaction must specialize or equal a declared means item, using the
same inheritance rule as existing exchange allocations.</p>
<p><span class="docutils literal">exchange_allocation</span> remains a separately identified relation. A means may
allocate several Interactions and an Interaction may have several explicit means.
Allocation compares actual activity-to-participant Allocations, without inferring
responsibility from roles or nesting. Every known performer must fit one complete
permitted endpoint pair. A known contradiction is an error; a missing actual
performer is an incomplete-model warning. Reorienting or reconnecting a means
validates all dependent allocations and scenario uses in one candidate.</p>
<p>ParticipantInteraction and compatible MixedLegacy scenarios may reference means.
For bidirectional use, explicit sender and receiver lifelines determine one
compatible ordered endpoint pair. Missing or ambiguous bindings do not guess a
direction. A Reply reusing its Call's means reverses the resolved actual Call,
including a reverse Call on an unoriented means. The existing operation-response
exception permits the correlated Reply on an oriented means; this implies no
physical transport property. OA process contributions continue to use Interaction.</p>
<p>Mapped unoriented SA BoundaryExchange messages use the same explicit lifeline
resolution. Ordinary messages also respect component-port direction; legacy
port boundaries retain their stored direction. A correlated same-channel Reply
still reverses the actual Call, including across directional Flow ports.</p>
<p>CommunicationMean and SA BoundaryExchange support Exchange traces. OA-to-SA
transition requires a separate component-port choice for each end of each means:
reuse an existing compatible port, or create a port with explicitly chosen
Standard/Flow kind and orientation. Participant correspondence never substitutes
a port UUID for its participant UUID. Interfaces and PortAllocations are not
invented; unresolved technical allocations must be reviewed or omitted from the
selection and authored explicitly. Reverse transition projects SA port owners to
reviewed OA participant counterparts, without copying typed SA ports into OA.
Source/Target review retains the exact participant/port identities in history.
Taking an OA endpoint requires the scoped technical port decision, while Keep
and a valid Candidate retain explicit technical choices.</p>
<p><span class="docutils literal">oa_exchange_category</span> and <span class="docutils literal">sa_exchange_category</span> are root-level named
semantic elements with <span class="docutils literal">family</span> Work (default) or Participant, and <span class="docutils literal">exchanges</span>
references (default []). Work categories contain Interaction/FunctionalExchange;
Participant categories contain CommunicationMean/BoundaryExchange. Members must
be distinct and in the category's layer; categories never own or merge exchanges.
Category transition requires mapped counterpart members. <span class="docutils literal">Category.Family</span> and
<span class="docutils literal">Member { collection CategoryExchanges; ... }</span> are closed typed semantic facts.
Deleting an exchange removes its category membership; deleting a category does
not remove its exchanges. Reidentification preserves all live references and
typed historical reference provenance.</p>
<p>Each Diagram has optional <span class="docutils literal">view_options</span> (all selections unrestricted, no hidden
edges, Name labels by default). Its closed fields are <span class="docutils literal">hidden_edges</span>,
<span class="docutils literal">relation_kinds</span>, <span class="docutils literal">work_categories</span>, <span class="docutils literal">participant_categories</span>, <span class="docutils literal">coverage</span>,
<span class="docutils literal">work_contexts</span> and <span class="docutils literal">exchange_labels</span>. Relation kinds use All or Only with
Relation(kind)/Trace entries; Only([]) draws no lines, including traces. Category
selectors use All or Any(category IDs); Any([]) draws none of that exchange family.
Selected categories are unioned within each family; independent restrictions
intersect. Coverage is All/InBehavior/OutsideBehavior; work contexts are All or
Any(explicit process, chain or scenario IDs). Contexts follow ordered owned
contributions and explicit reuse, sharing the advisory diagnostic evidence walk.
Labels are Name, Items or NameAndItems. These settings alter presentation only;
automatic port positions use unfiltered eligible lines. Hidden routes and semantic
identities remain saved. Removing a referenced selection preserves explicit empty
filters rather than widening them to All.</p>
<p>Traceability views retain their established two-layer projection: default options
preserve eligible OA and SA lines. Their hidden-edge, category and context
references may therefore select either layer. All ordinary projections require
these references in the declared diagram layer. A filter never hides the other
layer merely because the Traceability diagram has an OA or SA layer label.</p>
<p>Versions 1–5 reject the new relation, category constructor, diagram field (even
an explicitly supplied default), and category historical facts. Reading version 5
preserves existing records, legacy OA boundaries and reviewed facts, with an
explicit upgrade report to the current version 7. Source upgrading changes the version token
without rewriting unrelated authored trivia. No old boundary is automatically
converted into communication means. Source-6 graphical/API/native acceptance is
still tracked separately from this integration contract.</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
@@ -1022,7 +1103,7 @@ 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 5;
<pre class="literal-block">arcadia 7;
project ports_example &quot;Typed function contract&quot; {
sa_function send &quot;Send&quot; {}
sa_function receive &quot;Receive&quot; {}
@@ -1052,6 +1133,7 @@ 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>
<section id="capabilities-and-missions">
<h3>4.1. Capabilities and missions</h3>
<p>Include means the including capability requires the included capability's
@@ -1101,6 +1183,71 @@ 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 id="links-into-reusable-sequences">
<h4>4.2.1. Links into reusable sequences</h4>
<p><span class="docutils literal">ContextualLink</span> owns an explicit <span class="docutils literal">owner</span> Process or FunctionalChain and two
<span class="docutils literal">OccurrenceEndpoint</span> records. Each endpoint contains an ordered <span class="docutils literal">references</span>
list of SequenceReference occurrence identities and an <span class="docutils literal">occurrence</span> leaf
identity. Start at the link owner; each path member MUST be a contribution of the
current sequence and reference a valid same-layer sequence of the owner's kind.
Descend into that referenced definition before resolving the next path member or
leaf. The final leaf MUST be a contribution of the resulting sequence. A path
contains reference occurrences, never work elements or sequence-definition IDs.
An empty path denotes a direct contribution of the owner. Missing targets,
wrong owners, wrong kinds/layers and recursive reuse are errors.</p>
<p>Repeated references remain distinct. Given P with A→B→C and two references R1(P)
and R2(P), a link from direct X to <span class="docutils literal">[R1], B</span> affects only the R1 contribution
of B. It MUST NOT target R2.B, alter P's definition, delay R1.A by replacing the
endpoint with the whole R1 reference, or duplicate A/B/C. Two endpoints with the
same leaf identity but distinct paths are distinct caller contributions.</p>
<p>The closed <span class="docutils literal">purpose</span> has exactly three alternatives:</p>
<ul class="simple">
<li><p><span class="docutils literal">Precedence { guard }</span> describes predecessor/successor order; guard is prose.
When both paths are empty, use the existing SequenceLink. All-direct
ContextualLink Precedence MUST be rejected, preserving one canonical encoding.</p></li>
<li><p><span class="docutils literal">Exchange { exchange }</span> identifies the same-layer work exchange connecting
the addressed work contributions; both endpoint works MUST match its actual
source and target. It records assembly incidence, not an implicit extra
precedence edge.</p></li>
<li><p><span class="docutils literal">CommonWork { work }</span> requires both addressed contributions to reference that
same-layer Activity or Function. It states shared work identity, without
fusing executions, deleting contributions or asserting precedence.</p></li>
</ul>
<p>For example, within a complete source-7 project with the referenced declarations:</p>
<pre class="literal-block">contextual_link after_check &quot;Continue this assessment&quot; {
owner &#64;alarm_process;
source { references []; occurrence &#64;external_check; };
target { references [&#64;first_assessment]; occurrence &#64;assessment_b; };
purpose { Precedence { guard &quot;check accepted&quot;; }; };
}</pre>
<p>The owner controls persistence/module placement and graphical editing context,
including when neither leaf belongs directly to it. Generic leaf source/target
accessors MUST NOT be used to infer ownership. Rename and reidentification visit
every typed owner/path/leaf/purpose reference. Normal deletion of any such live
dependency removes the entire dependent link in the same transaction; it MUST
NOT shorten a path, substitute another reference instance or change purpose.
Retargeting a reference that invalidates a surviving link MUST refuse unless an
explicit repair batch makes the whole candidate valid. Undo restores complete
identities, links and authored source.</p>
<p>Admission permits at most 64reference occurrences per endpoint and counts all
authored reference-list entries against the caller's ordered-reference budget:
50,000 for the REST service and 500,000 for the desktop source workspace. Core
callers select their ParseLimits policy explicitly. Duplicate work definitions
do not erase this accounting. Cache capacity,
cache warmth, expansion order and diagram folding MUST NOT change admission.
Cache eviction is permitted; rejecting a valid address because a cache is full
is not.</p>
<p>Contextual diagnostics use separate precedence, exchange/common-work incidence
and caller coverage projections. Expand callee topology separately for each
reference path. Synthetic entry/exit connectivity is identifiable and MUST NOT
count as authored degree or satisfy authored guards. Missing or empty definitions
and expansion beyond 50,000 nodes/100,000 edges MUST report incomplete analysis;
they MUST NOT produce a guessed bypass or a complete-looking reachability result.
For X→R1.B plus P's A→B, an advisory may report two incoming authored links at
R1.B. It MUST NOT invalidate the model, require an invented Join, change the
standalone P or R2 diagnostics, or claim executable synchronization semantics.
Existing direct-only diagnostics remain unchanged.</p>
</section>
</section>
<section id="typed-scenarios-and-reusable-behavior">
<h3>4.3. Typed scenarios and reusable behavior</h3>
@@ -1151,6 +1298,61 @@ an ambiguous preserved legacy nested annotation warns <span class="docutils lite
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>
<section id="explicit-interface-operation-invocations">
<h4>4.3.1. Explicit interface-operation invocations</h4>
<p>The optional Exchange occurrence field <span class="docutils literal">operation</span> distinguishes ordinary
messages from explicit operation intent. Omitted or <span class="docutils literal">none</span> retains ordinary
channel semantics and is omitted in canonical output. A present closed record
with absent/<span class="docutils literal">none</span> <span class="docutils literal">allocation</span> means an explicitly unresolved operation.
A present <span class="docutils literal">allocation &#64;service_operation</span> selects that exact
InterfaceItemAllocation relation, not its item UUID, a name, a port or whichever
allocation happens to carry the same parameters. Thus parameterless Reset and
ReadStatus operations on one channel remain distinct maintained identities.</p>
<p>Operation intent is permitted only on SA BoundaryInterface scenario Call or
Asynchronous occurrences. A selected allocation MUST expose an Information
Operation item through the actual concrete Standard component ports used by the
invocation: receiver Provides, sender Requires a compatible interface exposing
that same allocation, using the normal interface inheritance rules. Containment
does not inherit participant interface roles onto a port. A separately allocated
same item is not the selected allocation. The actual channel traversal determines
direction, including an unoriented channel used in reverse. Call requires
Synchronous transmission; Asynchronous requires Asynchronous transmission;
Unspecified is incomplete and warns. A selected allocation without these proofs
is an error. Explicit unresolved intent remains editable with a located warning.</p>
<p>Reply MUST store no operation selection. It derives allocation, provider and
signature from its exact correlated Call, while independently satisfying the
existing reply order, reverse-participant and channel checks. It may reuse the
Call channel in reverse or use a separate explicit return channel. The separate
channel MUST carry the selected item or an admitted subtype and satisfy its own
actual endpoint contract, including for a parameterless/void return. The Reply
receiver need not provide the operation; the provider was established by the
Call. No operation or correlation may be guessed from similar names or fields.</p>
<p>Selected Call/Asynchronous values use only that operation's In/InOut signature;
Reply values use Out/InOut/Return. All ordinary nested-path and multiplicity rules
still apply. Unresolved operation intent preserves still-live expressions and
performs independent live-reference/path checks with an incomplete-signature
warning. It MUST NOT fall back to the union of items carried by the channel.
Selecting a new allocation validates all retained values and refuses incompatible
values without silently pruning them or creating defaults.</p>
<p>Deletion cleanup clears a deleted selected allocation to explicit unresolved
intent and preserves still-live values; it does not erase the Call or Reply.
The whole candidate MUST still satisfy independent channel contracts. Deleting
the sole allocation can therefore refuse while a boundary still carries its
now-unadmitted item. An explicit repair batch must address every affected channel,
including a separate Reply channel. If a surviving allocation admits the item,
deletion can succeed, but it MUST NOT select that surviving allocation as the
operation. Item/field deletion uses the normal proven-reference cleanup rules.</p>
<p>SA→OA transition of operation intent requires one explicit
<span class="docutils literal">OperationOmission { source, rationale }</span> per selected invocation. Rationale
MUST be nonempty. Missing, irrelevant, duplicate or wrong-direction decisions
are errors. Reply derives its Call's abstraction without a second operation
choice. The source model retains its operation; other facts and values are mapped
explicitly and the complete target is validated. The transition MUST NOT invent
OA technical ports, operation identities or functional refinement to avoid this
decision.</p>
</section>
<section id="scenario-reuse">
<h4>4.3.2. Scenario reuse</h4>
<p>ScenarioUse references an existing same-layer scenario and maps its lifelines
with <span class="docutils literal">bindings [ { referenced &#64;callee_line; local &#64;caller_line; } ];</span>.
Each binding is one-to-one and references a direct lifeline of the appropriate
@@ -1161,6 +1363,7 @@ 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>
<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,
@@ -1397,7 +1600,7 @@ 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 5;
<pre class="code text literal-block"><code>arcadia 7;
project engineering_data &quot;Engineering data&quot; {
sa_data_type voltage &quot;Voltage&quot; {
definition { Real { minimum 0.0; maximum 48.0; }; };
@@ -1460,7 +1663,7 @@ 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 5;
<pre class="code text literal-block"><code>arcadia 7;
project operating &quot;Operating modes&quot; {
oa_entity crew &quot;Crew&quot; {}
oa_state_machine modes &quot;Modes&quot; { parent &#64;crew; }
@@ -1922,7 +2125,7 @@ change.</p>
<h3>5.5. Source examples and historical token rules</h3>
<p>This valid source records deliberately different constructor/unit observations.
Its historical integer minimum is absent; the Real side has no integer branch:</p>
<pre class="literal-block">arcadia 5;
<pre class="literal-block">arcadia 7;
project reviewed_dimensions &quot;Reviewed dimensions&quot; {
oa_data_type oa_dimension &quot;Operational distance&quot; {
definition { Integer { minimum 0; maximum 10; }; };
@@ -2063,7 +2266,7 @@ MAY also be <span class="docutils literal">include string &quot;;&quot;</span>.
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 5;
<pre class="literal-block">arcadia 7;
project rescue &quot;Rescue&quot; id &quot;00000000-0000-4000-8000-000000000001&quot; {
description &quot;Operational model&quot;;
include &quot;oa/participants.arcadia&quot;;
@@ -2275,6 +2478,52 @@ 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 class="rubric">Explicit behavior coverage diagnostics</p>
<p>The following shared engineering checks are advisory <span class="docutils literal">Warning</span> diagnostics.
They MUST NOT reject graphical Apply, source compilation, Save, or an API
transaction solely because the model is incomplete. They run only after the
structural pass reports no <span class="docutils literal">Error</span>, avoiding cascades from invalid ownership,
references, layers, or recursion. Their policy concerns explicit evidence in
the authored model, not proof that no engineering behavior exists.</p>
<ul class="simple">
<li><p><span class="docutils literal">non_leaf_work_exchange</span> locates each <span class="docutils literal">source</span> or <span class="docutils literal">target</span> of an
Interaction or FunctionalExchange that has direct same-kind child work.
Repair the exchange to name its responsible leaf Activity/Function, keeping
SA function-port ownership consistent.</p></li>
<li><p><span class="docutils literal">work_without_behavior_context</span> locates a leaf Activity/Function lacking
an included Action or an included Interaction/FunctionalExchange occurrence
that explicitly names it as an endpoint.</p></li>
<li><p><span class="docutils literal">exchange_without_behavior_context</span> locates an Interaction or
FunctionalExchange lacking an included Exchange occurrence. It is suppressed
while a more specific non-leaf endpoint warning applies to that exchange.</p></li>
<li><p><span class="docutils literal">mission_without_capability</span> locates an OperationalMission/Mission lacking
a valid same-layer outgoing MissionCapability. Participant responsibility
through MissionInvolvement does not satisfy this check.</p></li>
<li><p><span class="docutils literal">capability_without_behavior_context</span> locates a supported leaf
Capability/SystemCapability lacking either an incoming ChainInvolvement or
a same-layer Scenario explicitly naming it as <span class="docutils literal">context</span>. It MUST NOT
duplicate <span class="docutils literal">unsupported_capability</span> on the same record.</p></li>
</ul>
<p>Record-level checks have no invented field path. Coverage traverses all Process,
FunctionalChain and Scenario roots, following only their explicitly listed,
correctly owned occurrences and Fragment branches. Reusable sequence/scenario
contents are traversed with identity-based cycle guards. Known work/exchange
references count despite unfinished lifelines; unordered occurrences do not.
Repeated exchanges and correlated replies contribute the same identity once.
Parent work does not cover its children. Bare lifelines, state observations,
StateAction/Availability links, timer-only occurrences, and participant/boundary
messages do not imply work/exchange coverage. Allocation does not imply that
every exchange carried by a boundary message occurs. Diagram layout is irrelevant.</p>
<p>As an explicit Studio completeness policy, same-kind capability grouping parents
are excluded from both capability support warnings; their leaf capabilities are
checked independently. A valid direct Scenario context also satisfies existing
<span class="docutils literal">unsupported_capability</span> support. An empty linked process/chain or scenario
satisfies explicit context presence while retaining its own <span class="docutils literal">empty_sequence</span>
warning. Include/extend/generalization, parent containment, and shared performers
MUST NOT manufacture a context. These advisory checks follow the distinction
between dataflow and its usage contexts described in the official
<a class="reference external" href="https://mbse-capella.org/arcadia-qna.html">Arcadia Questions and Answers</a>;
they are not a declaration of full Capella conformance.</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
@@ -2335,7 +2584,7 @@ explicitly before Apply succeeds.</p>
<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 V5 source bundle (<span class="docutils literal">arcadia 5</span>); other suffixes use V5 JSON. Both forms preserve the same
the accepted V7 source bundle (<span class="docutils literal">arcadia 7</span>); other suffixes use V7 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 explicit schema-4 reader retains the exact old Project/Trace/TraceBaseline
@@ -2344,7 +2593,7 @@ diagrams and artifacts. Version4 prose baselines migrate with semantic none;
their names/descriptions remain exact even when live endpoint values differ.
The adapter MUST NOT infer semantic review from live values, and version3/4
inputs MUST reject semantic baseline fields. The migration report retains the
original from_schema and current to_schema 5. Reopening a current5 save produces
original from_schema and current to_schema 7. Reopening a current7 save produces
no migration report. The real V4 reviewed-prose fixtures remain compatibility input.</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
@@ -2367,7 +2616,21 @@ order) and <span class="docutils literal">unresolved_message_values</span> (occu
report arrays default empty when reading older responses. Version 1 normalizes
through V2, then the typed-port V3 adapter, shared V4 data upgrade and V5 review
adapter. Original V2 and real V3 fixtures remain unchanged compatibility inputs. Current exports
always use version 5; reading/migrating alone never saves or changes revisions.</p>
always use version 7; reading/migrating alone never saves or changes revisions.</p>
<p>Versions 1–6 MUST reject ContextualLink, operation fields (including explicit
null/default values) and their new typed semantic facets. Current semantic review
adds Occurrence.Operation and Relation.ContextOwner/ContextSource/ContextTarget/
ContextPurpose. Historical endpoints and operation selections remain typed
historical UUIDs, never live graph references or inferred current facts.
Version 5/6 migration preserves old Call/Reply/values, direct SequenceLinks,
traces, and version-appropriate view selectors without guessing operation intent
or contextual links. An authored source upgrade changes only the version token
until an actual model edit requires further writeback.</p>
<p>Desktop recovery MUST verify old 5/6 checkpoint fingerprints with the exact
historical serializer and closed old-version admission before accepting the
migrated model. It retains invalid raw buffers and authored review decisions;
transient impact approvals are reset and plans are recomputed against the
accepted base. A saved unchecked executable plan/command MUST NOT be restored.</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
@@ -2443,7 +2706,7 @@ V5 projects. Future versions remain errors until a separate migration exists.</p
<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 5;
<pre class="code text literal-block"><code>arcadia 7;
project harbor &quot;Harbor assistance&quot; {
oa_entity control &quot;Harbor control&quot; {}
oa_activity assess &quot;Assess assistance&quot; {}
docs/language.rst
+177 -25
View File
@@ -1,8 +1,8 @@
Arcadia Studio OA / SA Language and Editing Contract
====================================================
:Version: 6 (integration in progress)
:Status: Source-6 contract under integration; native and API acceptance pending
:Version: 7 (integration in progress)
:Status: Source-7 contract under integration; native and API acceptance pending
:Core implementation: ``crates/oa-core``
:Text suffix: ``.arcadia``
@@ -11,12 +11,14 @@ Arcadia Studio OA / SA Language and Editing Contract
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, 3, 4 and 5. MUST, MUST NOT,
validation, persistence, and explicit migration from versions 1, 2, 3, 4, 5 and 6. MUST, MUST NOT,
and MAY indicate requirements, prohibitions, and permitted choices.
Schema 6 adds OA communication means, exchange categories and saved view options.
Their integration and acceptance are tracked separately; this version label does
not claim completed graphical/API parity. Schema 5 added closed typed semantic review facts to trace baselines, including
Schema 7 adds caller-qualified process/chain links and explicit interface-operation
selection on boundary scenario invocations. Schema 6 added OA communication means,
exchange categories and saved view options. Integration and acceptance are tracked
separately; this version label does not claim completed graphical/API parity.
Schema 5 added closed typed semantic review facts to trace baselines, including
historical references that may no longer exist in the live model. It retains
schema 4 bounded reusable data types, typed defaults, exchange mechanisms,
qualified values, specialization, interface allocations and associations, and
@@ -43,7 +45,7 @@ Actual verification evidence is separate from this contract.
2. One authoritative model
--------------------------
A Project stores ``schema_version`` (6), ``id``, ``alias``, ``name``,
A Project stores ``schema_version`` (7), ``id``, ``alias``, ``name``,
``description``, and maps named ``elements``, ``relations``, ``diagrams``,
``artifact_links``, and ``traces``. Each map is keyed by the UUID contained in
its record. Duplicate map keys and mismatching keys/identities are errors.
@@ -383,7 +385,7 @@ layer merely because the Traceability diagram has an OA or SA layer label.
Versions 1–5 reject the new relation, category constructor, diagram field (even
an explicitly supplied default), and category historical facts. Reading version 5
preserves existing records, legacy OA boundaries and reviewed facts, with an
explicit upgrade report to version 6. Source upgrading changes the version token
explicit upgrade report to the current version 7. Source upgrading changes the version token
without rewriting unrelated authored trivia. No old boundary is automatically
converted into communication means. Source-6 graphical/API/native acceptance is
still tracked separately from this integration contract.
@@ -444,7 +446,7 @@ Port deletion cascades to incident FEs; FE deletion retains independent ports.
For example::
arcadia 6;
arcadia 7;
project ports_example "Typed function contract" {
sa_function send "Send" {}
sa_function receive "Receive" {}
@@ -532,6 +534,78 @@ 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.
4.2.1. Links into reusable sequences
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
``ContextualLink`` owns an explicit ``owner`` Process or FunctionalChain and two
``OccurrenceEndpoint`` records. Each endpoint contains an ordered ``references``
list of SequenceReference occurrence identities and an ``occurrence`` leaf
identity. Start at the link owner; each path member MUST be a contribution of the
current sequence and reference a valid same-layer sequence of the owner's kind.
Descend into that referenced definition before resolving the next path member or
leaf. The final leaf MUST be a contribution of the resulting sequence. A path
contains reference occurrences, never work elements or sequence-definition IDs.
An empty path denotes a direct contribution of the owner. Missing targets,
wrong owners, wrong kinds/layers and recursive reuse are errors.
Repeated references remain distinct. Given P with A→B→C and two references R1(P)
and R2(P), a link from direct X to ``[R1], B`` affects only the R1 contribution
of B. It MUST NOT target R2.B, alter P's definition, delay R1.A by replacing the
endpoint with the whole R1 reference, or duplicate A/B/C. Two endpoints with the
same leaf identity but distinct paths are distinct caller contributions.
The closed ``purpose`` has exactly three alternatives:
* ``Precedence { guard }`` describes predecessor/successor order; guard is prose.
When both paths are empty, use the existing SequenceLink. All-direct
ContextualLink Precedence MUST be rejected, preserving one canonical encoding.
* ``Exchange { exchange }`` identifies the same-layer work exchange connecting
the addressed work contributions; both endpoint works MUST match its actual
source and target. It records assembly incidence, not an implicit extra
precedence edge.
* ``CommonWork { work }`` requires both addressed contributions to reference that
same-layer Activity or Function. It states shared work identity, without
fusing executions, deleting contributions or asserting precedence.
For example, within a complete source-7 project with the referenced declarations::
contextual_link after_check "Continue this assessment" {
owner @alarm_process;
source { references []; occurrence @external_check; };
target { references [@first_assessment]; occurrence @assessment_b; };
purpose { Precedence { guard "check accepted"; }; };
}
The owner controls persistence/module placement and graphical editing context,
including when neither leaf belongs directly to it. Generic leaf source/target
accessors MUST NOT be used to infer ownership. Rename and reidentification visit
every typed owner/path/leaf/purpose reference. Normal deletion of any such live
dependency removes the entire dependent link in the same transaction; it MUST
NOT shorten a path, substitute another reference instance or change purpose.
Retargeting a reference that invalidates a surviving link MUST refuse unless an
explicit repair batch makes the whole candidate valid. Undo restores complete
identities, links and authored source.
Admission permits at most 64reference occurrences per endpoint and counts all
authored reference-list entries against the caller's ordered-reference budget:
50,000 for the REST service and 500,000 for the desktop source workspace. Core
callers select their ParseLimits policy explicitly. Duplicate work definitions
do not erase this accounting. Cache capacity,
cache warmth, expansion order and diagram folding MUST NOT change admission.
Cache eviction is permitted; rejecting a valid address because a cache is full
is not.
Contextual diagnostics use separate precedence, exchange/common-work incidence
and caller coverage projections. Expand callee topology separately for each
reference path. Synthetic entry/exit connectivity is identifiable and MUST NOT
count as authored degree or satisfy authored guards. Missing or empty definitions
and expansion beyond 50,000 nodes/100,000 edges MUST report incomplete analysis;
they MUST NOT produce a guessed bypass or a complete-looking reachability result.
For X→R1.B plus P's A→B, an advisory may report two incoming authored links at
R1.B. It MUST NOT invalidate the model, require an invented Join, change the
standalone P or R2 diagnostics, or claim executable synchronization semantics.
Existing direct-only diagnostics remain unchanged.
4.3. Typed scenarios and reusable behavior
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -587,6 +661,68 @@ 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.
4.3.1. Explicit interface-operation invocations
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The optional Exchange occurrence field ``operation`` distinguishes ordinary
messages from explicit operation intent. Omitted or ``none`` retains ordinary
channel semantics and is omitted in canonical output. A present closed record
with absent/``none`` ``allocation`` means an explicitly unresolved operation.
A present ``allocation @service_operation`` selects that exact
InterfaceItemAllocation relation, not its item UUID, a name, a port or whichever
allocation happens to carry the same parameters. Thus parameterless Reset and
ReadStatus operations on one channel remain distinct maintained identities.
Operation intent is permitted only on SA BoundaryInterface scenario Call or
Asynchronous occurrences. A selected allocation MUST expose an Information
Operation item through the actual concrete Standard component ports used by the
invocation: receiver Provides, sender Requires a compatible interface exposing
that same allocation, using the normal interface inheritance rules. Containment
does not inherit participant interface roles onto a port. A separately allocated
same item is not the selected allocation. The actual channel traversal determines
direction, including an unoriented channel used in reverse. Call requires
Synchronous transmission; Asynchronous requires Asynchronous transmission;
Unspecified is incomplete and warns. A selected allocation without these proofs
is an error. Explicit unresolved intent remains editable with a located warning.
Reply MUST store no operation selection. It derives allocation, provider and
signature from its exact correlated Call, while independently satisfying the
existing reply order, reverse-participant and channel checks. It may reuse the
Call channel in reverse or use a separate explicit return channel. The separate
channel MUST carry the selected item or an admitted subtype and satisfy its own
actual endpoint contract, including for a parameterless/void return. The Reply
receiver need not provide the operation; the provider was established by the
Call. No operation or correlation may be guessed from similar names or fields.
Selected Call/Asynchronous values use only that operation's In/InOut signature;
Reply values use Out/InOut/Return. All ordinary nested-path and multiplicity rules
still apply. Unresolved operation intent preserves still-live expressions and
performs independent live-reference/path checks with an incomplete-signature
warning. It MUST NOT fall back to the union of items carried by the channel.
Selecting a new allocation validates all retained values and refuses incompatible
values without silently pruning them or creating defaults.
Deletion cleanup clears a deleted selected allocation to explicit unresolved
intent and preserves still-live values; it does not erase the Call or Reply.
The whole candidate MUST still satisfy independent channel contracts. Deleting
the sole allocation can therefore refuse while a boundary still carries its
now-unadmitted item. An explicit repair batch must address every affected channel,
including a separate Reply channel. If a surviving allocation admits the item,
deletion can succeed, but it MUST NOT select that surviving allocation as the
operation. Item/field deletion uses the normal proven-reference cleanup rules.
SA→OA transition of operation intent requires one explicit
``OperationOmission { source, rationale }`` per selected invocation. Rationale
MUST be nonempty. Missing, irrelevant, duplicate or wrong-direction decisions
are errors. Reply derives its Call's abstraction without a second operation
choice. The source model retains its operation; other facts and values are mapped
explicitly and the complete target is validated. The transition MUST NOT invent
OA technical ports, operation identities or functional refinement to avoid this
decision.
4.3.2. Scenario reuse
^^^^^^^^^^^^^^^^^^^^^
ScenarioUse references an existing same-layer scenario and maps its lifelines
with ``bindings [ { referenced @callee_line; local @caller_line; } ];``.
Each binding is one-to-one and references a direct lifeline of the appropriate
@@ -827,7 +963,7 @@ This complete data contract example is also exercised through the REST API:
.. code-block:: text
arcadia 6;
arcadia 7;
project engineering_data "Engineering data" {
sa_data_type voltage "Voltage" {
definition { Real { minimum 0.0; maximum 48.0; }; };
@@ -896,7 +1032,7 @@ This complete source example places one state from an existing machine:
.. code-block:: text
arcadia 6;
arcadia 7;
project operating "Operating modes" {
oa_entity crew "Crew" {}
oa_state_machine modes "Modes" { parent @crew; }
@@ -1350,7 +1486,7 @@ change.
This valid source records deliberately different constructor/unit observations.
Its historical integer minimum is absent; the Real side has no integer branch::
arcadia 6;
arcadia 7;
project reviewed_dimensions "Reviewed dimensions" {
oa_data_type oa_dimension "Operational distance" {
definition { Integer { minimum 0; maximum 10; }; };
@@ -1503,13 +1639,13 @@ deeply nested drafts produce a diagnostic instead of exhausting the parser stack
The pure ``source_project`` core API compiles a virtual source bundle, containing
``entry`` and a ``files`` map from logical paths to UTF-8 strings. Its entry is a
root-level ``.arcadia`` file with the source5 project header above. A project entry
root-level ``.arcadia`` file with the source7 project header above. A project entry
MAY also be ``include string ";"``. 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::
arcadia 6;
arcadia 7;
project rescue "Rescue" id "00000000-0000-4000-8000-000000000001" {
description "Operational model";
include "oa/participants.arcadia";
@@ -1575,15 +1711,15 @@ spans never refer to concatenated or synthetic source.
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, source4 and
source5. Source3 is upgraded as one project, preserving file paths, includes, nested
continue through explicit migration. Modular projects accept source3 through
source7. Older bundles are 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.
An authored source4 bundle upgrades through the strict prose-only baseline
adapter; after any missing UUID stabilization, the version token alone changes
to 5. Existing prose, comments, includes and nested ownership remain intact.
to 7. Existing prose, comments, includes and nested ownership remain intact.
Source5 semantic facet comments follow their closed selector identity through
row reordering and reidentification; UUID-looking text does not act as an Id.
@@ -1866,7 +2002,7 @@ explicitly before Apply succeeds.
Loading detects JSON from its first non-whitespace ``{``; other input is parsed
as Arcadia source regardless of filename. Saving an ``.arcadia`` suffix uses
the accepted V6 source bundle (``arcadia 6``); other suffixes use V6 JSON. Both forms preserve the same
the accepted V7 source bundle (``arcadia 7``); other suffixes use V7 JSON. Both forms preserve the same
complete model. JSON rejects unknown fields throughout typed payloads,
duplicate maps, unsupported versions, and structural errors.
@@ -1876,7 +2012,7 @@ diagrams and artifacts. Version4 prose baselines migrate with semantic none;
their names/descriptions remain exact even when live endpoint values differ.
The adapter MUST NOT infer semantic review from live values, and version3/4
inputs MUST reject semantic baseline fields. The migration report retains the
original from_schema and current to_schema 5. Reopening a current5 save produces
original from_schema and current to_schema 7. Reopening a current7 save produces
no migration report. The real V4 reviewed-prose fixtures remain compatibility input.
The schema-3 reader freezes the changed data payloads and old constructor catalog;
@@ -1902,7 +2038,23 @@ order) and ``unresolved_message_values`` (occurrence, field, reason). These new
report arrays default empty when reading older responses. Version 1 normalizes
through V2, then the typed-port V3 adapter, shared V4 data upgrade and V5 review
adapter. Original V2 and real V3 fixtures remain unchanged compatibility inputs. Current exports
always use version 6; reading/migrating alone never saves or changes revisions.
always use version 7; reading/migrating alone never saves or changes revisions.
Versions 1–6 MUST reject ContextualLink, operation fields (including explicit
null/default values) and their new typed semantic facets. Current semantic review
adds Occurrence.Operation and Relation.ContextOwner/ContextSource/ContextTarget/
ContextPurpose. Historical endpoints and operation selections remain typed
historical UUIDs, never live graph references or inferred current facts.
Version 5/6 migration preserves old Call/Reply/values, direct SequenceLinks,
traces, and version-appropriate view selectors without guessing operation intent
or contextual links. An authored source upgrade changes only the version token
until an actual model edit requires further writeback.
Desktop recovery MUST verify old 5/6 checkpoint fingerprints with the exact
historical serializer and closed old-version admission before accepting the
migrated model. It retains invalid raw buffers and authored review decisions;
transient impact approvals are reset and plans are recomputed against the
accepted base. A saved unchecked executable plan/command MUST NOT be restored.
Native source Save All checks the original contents of observed dependencies
before staging writes. Existing target files are replaced individually and the
@@ -1928,7 +2080,7 @@ defaults without changing any prior identity, name, reference, order, geometry,
artifact or trace field. The original V2 golden source/JSON in
``crates/oa-core/tests/fixtures`` MUST NOT be regenerated from the newer demo;
they verify that every old persistent field survives. Canonical output writes
the added defaults through the explicit schema-3, schema-4 and schema-5 migrations.
the added defaults through explicit migration to the current schema 7.
The V2 adapter preserves every original identity, alias, prose, parent,
placement, trace and artifact. Generic ports become Legacy with their original
@@ -1947,14 +2099,14 @@ 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 5. Model/source exports contain only the canonical model. Migration
schema 7. Model/source exports contain only the canonical model. Migration
reports are transient response metadata, not persisted model facts.
Admission checks account for generated objects and their references before
construction. Both the old V2 contract and the resulting V5 graph are
construction. Both the old V2 contract and the resulting current 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-to-5 stages.
model and then uses the same explicit adapters to reach schema 7.
Save validates a snapshot, writes a sibling temporary file, flushes it, and
atomically replaces the destination. Failed serialization or validation must
@@ -1991,7 +2143,7 @@ the assigned UUIDs explicitly.
.. code-block:: text
arcadia 6;
arcadia 7;
project harbor "Harbor assistance" {
oa_entity control "Harbor control" {}
oa_activity assess "Assess assistance" {}
docs/openapi.json
+427 -9
View File
@@ -3,7 +3,7 @@
"info": {
"title": "Arcadia Studio model API",
"version": "1.0.0",
"description": "Current schema-6 snapshots and conditional atomic writes. Request body limit: 8 MiB; at most 200 nested commands; no retained revisions, request receipts, automatic retries or persistent transition plans. See docs/api.rst. Fixed store capacity: 128 models / 256 MiB serialized envelopes. Stateless transition preview/apply. Artifact URI/revision strings remain opaque core fields. Model admission before structural validation: 5,000 graph objects, 20,000 total records and 50,000 ordered references. Preparation uses snapshots outside the catalog lock; final commits recheck the exact ETag. Each accepted envelope couples model and authored source under one revision. Source-only edits advance the shared ETag. Source bundles resolve logical paths only, preserve authored files/comments, and have a stabilized JSON cap of 8 MiB, 256 files, 32 include edges along a path and 1,024 include edges overall."
"description": "Current schema-7 snapshots and conditional atomic writes. Request body limit: 8 MiB; at most 200 nested commands; no retained revisions, request receipts, automatic retries or persistent transition plans. See docs/api.rst. Fixed store capacity: 128 models / 256 MiB serialized envelopes. Stateless transition preview/apply. Artifact URI/revision strings remain opaque core fields. Model admission before structural validation: 5,000 graph objects, 20,000 total records and 50,000 ordered references. Preparation uses snapshots outside the catalog lock; final commits recheck the exact ETag. Each accepted envelope couples model and authored source under one revision. Source-only edits advance the shared ETag. Source bundles resolve logical paths only, preserve authored files/comments, and have a stabilized JSON cap of 8 MiB, 256 files, 32 include edges along a path and 1,024 include edges overall."
},
"servers": [
{
@@ -389,7 +389,7 @@
}
}
},
"description": "Schema-6 native JSON is described below. Schema-1/2/3/4/5 JSON and source are accepted through explicit frozen readers and migration, also on replacement and candidate validation. Earlier versions reject source-6 constructors and saved view fields. Prior prose and typed reviews remain intact; absent semantic review stays Unreviewed. Export emits schema 6 / arcadia 6. See docs/language.rst."
"description": "Schema-7 native JSON is described below. Schema-1/2/3/4/5/6 JSON and source are accepted through explicit frozen readers and migration, also on replacement and candidate validation. Earlier versions reject later constructors, fields and semantic facets, including explicit null. Prior prose and typed reviews remain intact; absent semantic review stays Unreviewed. Export emits schema 7 / arcadia 7. See docs/language.rst."
}
},
"/api/v1/projects/{id}": {
@@ -2087,6 +2087,7 @@
"CapabilityGeneralization",
"MissionInvolvement",
"SequenceLink",
"ContextualLink",
"StateTransition",
"Availability",
"ExchangeAllocation",
@@ -2469,6 +2470,17 @@
"$ref": "#/components/schemas/MessageValue"
},
"default": []
},
"operation": {
"anyOf": [
{
"$ref": "#/components/schemas/OperationUse"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
@@ -2477,7 +2489,7 @@
"receiver"
],
"additionalProperties": false,
"description": "Missing new message fields use schema-2 compatibility defaults; canonical output makes these fields explicit."
"description": "Absent/null operation retains ordinary channel semantics and is omitted on output. Present operation is allowed only on SA BoundaryInterface Call/Asynchronous messages. Reply stores no operation and derives its exact Call's selection. Existing message defaults remain unchanged."
}
},
"required": [
@@ -4155,6 +4167,39 @@
"CommunicationMean"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"ContextualLink": {
"type": "object",
"properties": {
"owner": {
"$ref": "#/components/schemas/Id"
},
"source": {
"$ref": "#/components/schemas/OccurrenceEndpoint"
},
"target": {
"$ref": "#/components/schemas/OccurrenceEndpoint"
},
"purpose": {
"$ref": "#/components/schemas/ContextualLinkPurpose"
}
},
"required": [
"owner",
"source",
"target",
"purpose"
],
"additionalProperties": false
}
},
"required": [
"ContextualLink"
],
"additionalProperties": false
}
]
},
@@ -4555,7 +4600,7 @@
"properties": {
"schema_version": {
"type": "integer",
"const": 6
"const": 7
},
"id": {
"type": "string",
@@ -6218,6 +6263,15 @@
"maxItems": 200,
"default": [],
"description": "Explicit SA component-port pair per selected OA CommunicationMean. Reuse or Create only. Owners follow reviewed participant mappings; no participant-to-port substitution or automatic interface allocation."
},
"operation_omissions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OperationOmission"
},
"maxItems": 200,
"default": [],
"description": "Explicit SA-to-OA abstraction per selected invocation with operation intent. Nonempty rationale required by core; duplicates, irrelevant sources, and other directions are refused. Replies derive the Call abstraction. Source operation identities and values are preserved."
}
},
"required": [
@@ -6732,12 +6786,13 @@
2,
3,
4,
5
5,
6
]
},
"to_schema": {
"type": "integer",
"const": 6
"const": 7
},
"preserved_ports": {
"type": "array",
@@ -6924,11 +6979,11 @@
"required_resolutions"
],
"additionalProperties": false,
"description": "Transient observations from explicit V1/V2/V3/V4/V5 to V6 migration. New report lists default to empty when reading older responses. Reading an old envelope neither saves nor changes its revision. Allocation UUIDv5 uses project namespace and v2-interface-item:<interface>:<item>."
"description": "Transient observations from explicit V1/V2/V3/V4/V5/V6 to V7 migration. New report lists default to empty when reading older responses. Reading an old envelope neither saves nor changes its revision. Allocation UUIDv5 uses project namespace and v2-interface-item:<interface>:<item>."
},
"SourceBundle": {
"type": "object",
"description": "Complete source6 workspace (source3/4/5 migrate explicitly). The entry is a root filename. Files use canonical portable slash-separated relative .arcadia paths and all must be reachable. Includes resolve only against this map, never the service filesystem. Up to 256 files, 32 include edges along a path and 1,024 include edges overall. Serialized bundle JSON is at most 8 MiB, checked again after missing UUIDs are inserted. GET returns exact accepted stable text.",
"description": "Complete source7 workspace (source3/4/5/6 migrate explicitly). The entry is a root filename. Files use canonical portable slash-separated relative .arcadia paths and all must be reachable. Includes resolve only against this map, never the service filesystem. Up to 256 files, 32 include edges along a path and 1,024 include edges overall. Serialized bundle JSON is at most 8 MiB, checked again after missing UUIDs are inserted. GET returns exact accepted stable text.",
"properties": {
"entry": {
"type": "string"
@@ -8944,6 +8999,7 @@
"MessageKind",
"TimerExpression",
"ReplyTo",
"Operation",
"Action",
"ActionLifeline",
"ControlKind",
@@ -9281,6 +9337,18 @@
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"Operation": {
"$ref": "#/components/schemas/ReviewedOptionOperationUse"
}
},
"required": [
"Operation"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
@@ -9722,7 +9790,11 @@
"Trigger",
"Guard",
"Effect",
"StateActionPhase"
"StateActionPhase",
"ContextOwner",
"ContextSource",
"ContextTarget",
"ContextPurpose"
]
},
"ReviewedId": {
@@ -10326,6 +10398,54 @@
"StateActionPhase"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"ContextOwner": {
"$ref": "#/components/schemas/ReviewedId"
}
},
"required": [
"ContextOwner"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"ContextSource": {
"$ref": "#/components/schemas/ReviewedOccurrenceEndpoint"
}
},
"required": [
"ContextSource"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"ContextTarget": {
"$ref": "#/components/schemas/ReviewedOccurrenceEndpoint"
}
},
"required": [
"ContextTarget"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"ContextPurpose": {
"$ref": "#/components/schemas/ReviewedContextualLinkPurpose"
}
},
"required": [
"ContextPurpose"
],
"additionalProperties": false
}
]
},
@@ -12413,6 +12533,304 @@
"target_port"
],
"additionalProperties": false
},
"ReviewedOptionOperationUse": {
"type": "object",
"properties": {
"oa": {
"oneOf": [
{
"type": "string",
"enum": [
"NotApplicable"
]
},
{
"type": "object",
"properties": {
"Value": {
"anyOf": [
{
"$ref": "#/components/schemas/OperationUse"
},
{
"type": "null"
}
]
}
},
"required": [
"Value"
],
"additionalProperties": false
}
]
},
"sa": {
"oneOf": [
{
"type": "string",
"enum": [
"NotApplicable"
]
},
{
"type": "object",
"properties": {
"Value": {
"anyOf": [
{
"$ref": "#/components/schemas/OperationUse"
},
{
"type": "null"
}
]
}
},
"required": [
"Value"
],
"additionalProperties": false
}
]
}
},
"required": [
"oa",
"sa"
],
"additionalProperties": false
},
"ReviewedOccurrenceEndpoint": {
"type": "object",
"properties": {
"oa": {
"oneOf": [
{
"type": "string",
"enum": [
"NotApplicable"
]
},
{
"type": "object",
"properties": {
"Value": {
"$ref": "#/components/schemas/OccurrenceEndpoint"
}
},
"required": [
"Value"
],
"additionalProperties": false
}
]
},
"sa": {
"oneOf": [
{
"type": "string",
"enum": [
"NotApplicable"
]
},
{
"type": "object",
"properties": {
"Value": {
"$ref": "#/components/schemas/OccurrenceEndpoint"
}
},
"required": [
"Value"
],
"additionalProperties": false
}
]
}
},
"required": [
"oa",
"sa"
],
"additionalProperties": false
},
"ReviewedContextualLinkPurpose": {
"type": "object",
"properties": {
"oa": {
"oneOf": [
{
"type": "string",
"enum": [
"NotApplicable"
]
},
{
"type": "object",
"properties": {
"Value": {
"$ref": "#/components/schemas/ContextualLinkPurpose"
}
},
"required": [
"Value"
],
"additionalProperties": false
}
]
},
"sa": {
"oneOf": [
{
"type": "string",
"enum": [
"NotApplicable"
]
},
{
"type": "object",
"properties": {
"Value": {
"$ref": "#/components/schemas/ContextualLinkPurpose"
}
},
"required": [
"Value"
],
"additionalProperties": false
}
]
}
},
"required": [
"oa",
"sa"
],
"additionalProperties": false
},
"OccurrenceEndpoint": {
"type": "object",
"properties": {
"references": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Id"
},
"maxItems": 64
},
"occurrence": {
"$ref": "#/components/schemas/Id"
}
},
"required": [
"references",
"occurrence"
],
"additionalProperties": false,
"description": "Ordered reference-occurrence IDs in an explicit caller owner, followed by the leaf contribution ID. Empty references means a direct contribution; sequence definition IDs are not path components."
},
"ContextualLinkPurpose": {
"oneOf": [
{
"type": "object",
"properties": {
"Precedence": {
"type": "object",
"properties": {
"guard": {
"type": "string"
}
},
"required": [
"guard"
],
"additionalProperties": false
}
},
"required": [
"Precedence"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"Exchange": {
"type": "object",
"properties": {
"exchange": {
"$ref": "#/components/schemas/Id"
}
},
"required": [
"exchange"
],
"additionalProperties": false
}
},
"required": [
"Exchange"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"CommonWork": {
"type": "object",
"properties": {
"work": {
"$ref": "#/components/schemas/Id"
}
},
"required": [
"work"
],
"additionalProperties": false
}
},
"required": [
"CommonWork"
],
"additionalProperties": false
}
]
},
"OperationUse": {
"type": "object",
"properties": {
"allocation": {
"anyOf": [
{
"$ref": "#/components/schemas/Id"
},
{
"type": "null"
}
]
}
},
"required": [],
"additionalProperties": false,
"description": "Present with absent/null allocation retains unresolved operation intent. A selected UUID identifies exactly an InterfaceItemAllocation, never an item, port, or name. Reply derives operation from its exact correlated Call."
},
"OperationOmission": {
"type": "object",
"properties": {
"source": {
"$ref": "#/components/schemas/Id"
},
"rationale": {
"type": "string"
}
},
"required": [
"source",
"rationale"
],
"additionalProperties": false
}
}
}