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

Specify R6 data contracts and verify coupled REST migration

Browse Source
This commit is contained in:
sorokin.oleg.edu
2026-09-06 03:46:13 +03:00
parent 0b58107097
commit 959b83c78f
13 changed files with 1544 additions and 190 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/language.html
+215 -42
View File
@@ -623,7 +623,7 @@ 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">3</dd>
<dd class="version">4</dd>
<dt class="status">Status<span class="colon">:</span></dt>
<dd class="status">Normative current implementation contract; first-release integration</dd>
<dt class="core-implementation">Core implementation<span class="colon">:</span></dt>
@@ -637,14 +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 and 2. MUST, MUST NOT,
validation, persistence, and explicit migration from versions 1, 2 and 3. MUST, MUST NOT,
and MAY indicate requirements, prohibitions, and permitted choices.</p>
<p>Schema 3 introduces typed function and component ports, required functional
exchange endpoints, independently oriented boundary exchanges, and explicit
PortAllocation relations. First-release scenario/state additions remain in
scope; this schema change does not declare native acceptance or the wider
release complete. The preserved schema-2 reader validates the original
contract before migration.</p>
<p>Schema 4 adds bounded reusable data types, typed scalar defaults, exchange
mechanisms, qualified message values, specialization, identified interface
allocations and reference associations. It retains schema 3 typed ports and
state views. Explicit older readers preserve existing meanings and identities.
This contract does not by itself establish native acceptance or release completion.</p>
<p>OA describes stakeholders, operational work and needs. SA describes the
selected system boundary, external actors, functions, services and expected
behavior. SA permits at most one System of Interest; its absence is an
@@ -662,7 +661,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> (3), <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> (4), <span class="docutils literal">id</span>, <span class="docutils literal">alias</span>, <span class="docutils literal">name</span>,
<span class="docutils literal">description</span>, and maps named <span class="docutils literal">elements</span>, <span class="docutils literal">relations</span>, <span class="docutils literal">diagrams</span>,
<span class="docutils literal">artifact_links</span>, and <span class="docutils literal">traces</span>. Each map is keyed by the UUID contained in
its record. Duplicate map keys and mismatching keys/identities are errors.</p>
@@ -722,20 +721,20 @@ lists all additional fields. <span class="docutils literal">ref</span> means <sp
<td><p><span class="docutils literal">[]</span></p></td>
</tr>
<tr><td><p><span class="docutils literal">oa_exchange_item</span>, <span class="docutils literal">sa_exchange_item</span></p></td>
<td><p><span class="docutils literal">kind</span>: Information, Material, Energy, Event</p></td>
<td><p>Information</p></td>
<td><p><span class="docutils literal">kind</span>: Information, Material, Energy; <span class="docutils literal">mechanism</span>: ExchangeMechanism; <span class="docutils literal">supertype</span>: item ref?</p></td>
<td><p>Information; Unspecified; none</p></td>
</tr>
<tr><td><p><span class="docutils literal">oa_data_type</span>, <span class="docutils literal">sa_data_type</span></p></td>
<td><p><span class="docutils literal">definition</span>: Boolean, Integer, Real, String, Record, or Enumeration constructor</p></td>
<td><p>String</p></td>
<td><p><span class="docutils literal">definition</span>: DataTypeDefinition; <span class="docutils literal">default</span>: DataValue?; <span class="docutils literal">unit</span>: string</p></td>
<td><p>String with minimum_length 0 / maximum_length none; none; <span class="docutils literal">&quot;&quot;</span></p></td>
</tr>
<tr><td><p><span class="docutils literal">oa_data_field</span>, <span class="docutils literal">sa_data_field</span></p></td>
<td><p><span class="docutils literal">type_ref</span>; <span class="docutils literal">minimum</span>: u32; <span class="docutils literal">maximum</span>: optional u32; <span class="docutils literal">unit</span>: string</p></td>
<td><p>String; 1; 1; <span class="docutils literal">&quot;&quot;</span></p></td>
<td><p><span class="docutils literal">type_ref</span>; <span class="docutils literal">minimum</span>: u32; <span class="docutils literal">maximum</span>: optional u32; <span class="docutils literal">unit</span>: string; <span class="docutils literal">direction</span>: ParameterDirection; <span class="docutils literal">storage</span>: FieldStorage; <span class="docutils literal">default</span>: DataValue list?</p></td>
<td><p>String; 1; 1; <span class="docutils literal">&quot;&quot;</span>; Unspecified; Value; none</p></td>
</tr>
<tr><td><p><span class="docutils literal">oa_interface</span>, <span class="docutils literal">sa_interface</span></p></td>
<td><p><span class="docutils literal">items</span>: exchange-item refs</p></td>
<td><p><span class="docutils literal">[]</span></p></td>
<td><p><span class="docutils literal">supertype</span>: interface ref?</p></td>
<td><p>none; membership is an identified interface_item_allocation relation</p></td>
</tr>
<tr><td><p><span class="docutils literal">oa_port</span>, <span class="docutils literal">sa_port</span></p></td>
<td><p><span class="docutils literal">contract</span>: required PortContract; <span class="docutils literal">legacy</span>: optional LegacyPortContract</p></td>
@@ -883,6 +882,14 @@ references. Their kind is the declaration keyword:</p>
<td><p>Same-layer participant → leaf activity/function</p></td>
<td><p>None</p></td>
</tr>
<tr><td><p><span class="docutils literal">interface_item_allocation</span></p></td>
<td><p>Same-layer Interface → ExchangeItem</p></td>
<td><p><span class="docutils literal">order</span> u32 / 0; <span class="docutils literal">transmission</span> TransmissionProtocol / Unspecified; <span class="docutils literal">acquisition</span> AcquisitionProtocol / Unspecified</p></td>
</tr>
<tr><td><p><span class="docutils literal">data_association</span></p></td>
<td><p>Same-layer Record DataType → Record DataType</p></td>
<td><p><span class="docutils literal">source_role</span>, <span class="docutils literal">target_role</span> / &quot;&quot;; <span class="docutils literal">source_minimum</span>, <span class="docutils literal">target_minimum</span> / 0; <span class="docutils literal">source_maximum</span>, <span class="docutils literal">target_maximum</span> / none; <span class="docutils literal">source_navigable</span>, <span class="docutils literal">target_navigable</span> / false</p></td>
</tr>
<tr><td><p><span class="docutils literal">interaction</span></p></td>
<td><p>OA activity → OA activity</p></td>
<td><p><span class="docutils literal">items</span> refs / []</p></td>
@@ -963,7 +970,8 @@ references. Their kind is the declaration keyword:</p>
</table>
<p>Relation endpoints and carried ExchangeItems stay in the same layer. Parallel
exchanges with distinct identities are permitted. Self-relations are invalid
except for a state transition that returns to its source state.</p>
except for a state transition that returns to its source state or an explicit
DataAssociation between two ends of the same Record type.</p>
<p>Direct Allocation has at most one performer per leaf. Role sharing is a
different relationship: several OA participants can realize a Role. A direct
allocation inconsistent with its role's realized performers produces an
@@ -1011,12 +1019,13 @@ 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 3;
<pre class="literal-block">arcadia 4;
project ports_example &quot;Typed function contract&quot; {
sa_function send &quot;Send&quot; {}
sa_function receive &quot;Receive&quot; {}
sa_exchange_item payload &quot;Payload&quot; {}
sa_interface old_service &quot;Preserved service&quot; { items [&#64;payload]; }
sa_interface old_service &quot;Preserved service&quot; {}
interface_item_allocation service_payload &quot;Service payload&quot; { source &#64;old_service; target &#64;payload; }
sa_port output &quot;Output&quot; {
parent &#64;send;
contract { FunctionOutput { outgoing_items [&#64;payload]; }; };
@@ -1125,11 +1134,19 @@ local to its sender lifeline, has no global exchange or values, and has either
no receiver or the same receiver as sender. Its nonempty expression describes
the delay/deadline; an empty expression warns. Conditions and expressions are
stored engineering annotations, not an executable simulation language.</p>
<p>Each MessageValue is <span class="docutils literal">{ field &#64;data_field; expression &quot;value expression&quot;; }</span>.
The field MUST be a DataField carried by the message exchange, including fields
inside named nested records. At most one annotation for a given field is
allowed in one message. Values do not overwrite the referenced type or global
exchange item. Expression text is preserved exactly; an empty expression warns.</p>
<p>Each MessageValue is <span class="docutils literal">{ path [&#64;parameter]; field &#64;data_field; expression &quot;value expression&quot;; }</span>.
Its identity is the pair (path, field), so two uses of one Record can have
different values for the same terminal field. Path contains enclosing DataField
references, excluding the terminal field; direct parameters use <span class="docutils literal">[]</span>. Every
hop MUST follow Value storage through a named Record's effective fields. Reference
storage stops traversal. Operation Call accepts In/InOut and Reply accepts
Out/InOut/Return, interpreted from the provider's perspective. Nested field paths
inherit their direct parameter's direction. Unspecified direction warns.
At most one annotation for a pair is allowed. Omitted path defaults to <span class="docutils literal">[]</span>;
an ambiguous preserved legacy nested annotation warns <span class="docutils literal">message_value_ambiguous_path</span>
until an explicit path is selected. New graphical choices always identify a path.
Values never overwrite types or items. Expression text is descriptive, preserved
exactly and not evaluated; an empty expression warns.</p>
<p>ScenarioUse references an existing same-layer scenario and maps its lifelines
with <span class="docutils literal">bindings [ { referenced &#64;callee_line; local &#64;caller_line; } ];</span>.
Each binding is one-to-one and references a direct lifeline of the appropriate
@@ -1280,6 +1297,137 @@ DeepHistory remembers nested configuration. Fallback applies when no resumable
history exists. History is per Region, including top-level Regions in this
Studio profile; no running history state is persisted or synthesized.</p>
</section>
<section id="data-contracts-specialization-and-interface-allocation">
<h3>4.5. Data contracts, specialization and interface allocation</h3>
<p>ExchangeItem <span class="docutils literal">kind</span> describes nature: Information, Material or Energy.
<span class="docutils literal">mechanism</span> is Unspecified, Flow, Event, Operation or SharedData. Unknown
mechanisms remain explicit Unspecified drafts with a warning. Material/Energy
with Event/Operation/SharedData warns for engineering review; it is not silently
reclassified. Empty Event notifications and void Operations are valid. An empty
carried/allocated Flow, SharedData or Unspecified item warns.</p>
<p>An Operation's directly owned DataFields are parameters. <span class="docutils literal">direction</span> is
Unspecified, In, Out, InOut or Return, from the provider's perspective. At most
one effective parameter is Return. Unspecified parameters warn; non-operation
fields MUST use Unspecified. Nested record fields inherit direction from their
direct parameter when used in message paths, rather than storing context on a
shared type. <span class="docutils literal">storage</span> is Value or Reference. Reference requires a named Record,
has no explicit default, and does not convey ownership or deletion of the type.</p>
<p>DataTypeDefinition has exactly the following constructors:</p>
<table>
<caption>Reusable definitions</caption>
<thead>
<tr><th class="head"><p>Constructor</p></th>
<th class="head"><p>Required fields</p></th>
</tr>
</thead>
<tbody>
<tr><td><p>Boolean</p></td>
<td><p>None</p></td>
</tr>
<tr><td><p>Integer</p></td>
<td><p><span class="docutils literal">minimum</span>, <span class="docutils literal">maximum</span>: optional signed 64-bit integers</p></td>
</tr>
<tr><td><p>Real</p></td>
<td><p><span class="docutils literal">minimum</span>, <span class="docutils literal">maximum</span>: optional finite IEEE-754 binary64 values</p></td>
</tr>
<tr><td><p>String</p></td>
<td><p><span class="docutils literal">minimum_length</span>: u32; <span class="docutils literal">maximum_length</span>: optional u32</p></td>
</tr>
<tr><td><p>Enumeration</p></td>
<td><p><span class="docutils literal">literals</span>: unique nonempty, case-sensitive strings</p></td>
</tr>
<tr><td><p>Record</p></td>
<td><p><span class="docutils literal">supertype</span>: same-layer Record ref?</p></td>
</tr>
</tbody>
</table>
<p>Bounds are inclusive and ordered; an absent bound means unbounded within the
represented numeric domain. Integer comparisons MUST NOT convert to binary64.
NaN, infinities, overflow and reversed bounds reject. String length counts Unicode
scalar values, not UTF-8 bytes or grapheme clusters. Enum defaults match exact
literals. Empty enum definitions remain incomplete drafts with a warning.</p>
<p>DataValue is a tagged scalar: <span class="docutils literal">{ Boolean true; }</span>, <span class="docutils literal">{ Integer 42; }</span>,
<span class="docutils literal">{ Real 1.5; }</span>, <span class="docutils literal">{ String &quot;value&quot;; }</span> or <span class="docutils literal">{ Enumeration &quot;Ready&quot;; }</span>.
There is no implicit numeric or string coercion. A type default is one compatible
scalar within its bounds. Record type defaults and record/object instance literals
are unsupported. A field default is absent (<span class="docutils literal">none</span>) or a list of compatible
scalars with length inside its multiplicity. <span class="docutils literal">[]</span> explicitly supplies an empty
collection and requires minimum 0, including Value Record fields; a nonempty
Record literal rejects. Reference fields MUST use <span class="docutils literal">none</span>. A one-valued scalar
field uses a one-value list. A named type default supplies an individual element's
default, not a collection or an implicit instance of a mandatory field.</p>
<p>Numeric types may carry unit text. Empty field units inherit the named type unit;
an explicit different unit warns when that type has a unit. Units on nonnumeric
fields/types warn and remain preserved. Unit strings never convert values or
establish dimensional compatibility. Expressions are not executed.</p>
<p>Record, ExchangeItem and Interface each permit one same-family, same-layer
supertype. Specialization is acyclic and separate from containment. Effective
fields are base fields followed by local fields, preserving original field UUIDs
and owners. Local names MUST NOT shadow inherited names. Item specialization
preserves base nature and any specified mechanism; an Unspecified base mechanism
may be refined. Deleting a derived record never deletes its base. Mandatory
Value-field cycles warn <span class="docutils literal">record_no_finite_value</span>; optional or Reference cycles
are valid without that warning. Traversal is cycle guarded and bounded; a payload
path budget failure is an explicit diagnostic, not silent truncation.</p>
<p>InterfaceItemAllocation is an ordinary identified relation from Interface to
ExchangeItem. It stores <span class="docutils literal">order</span> and independent transmission/acquisition
protocols. Transmission is Unspecified, Synchronous, Asynchronous, Unicast,
Multicast or Broadcast; acquisition is Unspecified, Read or Accept. No protocol
combination is inferred from mechanism. Effective allocations are base-first,
then local ordered by (order, alias, UUID). A local item already allocated locally
or inherited is an error. Removing an allocation keeps its item and other
allocations; if live boundary compatibility would break, the transaction MUST
repair the affected contract explicitly or reject atomically. Artifacts can
reference the allocation identity independently of the global item.</p>
<p>An exchange carrying a specialized item satisfies a declaration of its base,
never the reverse. Standard provided/required compatibility uses explicit
interface ancestry. Identity/ancestry, not matching names, defines conformance.
The current typed function/component port contracts remain unchanged.</p>
<p>DataAssociation connects Record types without adding fields or transitively
carrying payload. Each named end has role, multiplicity and navigability. Source
multiplicity counts source instances per target instance and vice versa; it is
not a count of model elements. An end's navigable flag permits navigation toward
that end. Self-associations are valid; if both ends are navigable they require
distinct nonempty roles. Empty roles and duplicate role contracts warn, whereas
invalid ranges reject. Composition/shared aggregation, multiple inheritance,
redefinition, instance literals and arbitrary-precision decimal arithmetic are
outside this bounded contract.</p>
<p>This complete data contract example is also exercised through the REST API:</p>
<pre class="code text literal-block"><code>arcadia 4;
project engineering_data &quot;Engineering data&quot; {
sa_data_type voltage &quot;Voltage&quot; {
definition { Real { minimum 0.0; maximum 48.0; }; };
default { Real 24.0; }; unit &quot;V&quot;;
}
sa_data_type coordinate &quot;Coordinate&quot; {
definition { Record { supertype none; }; };
sa_data_field latitude &quot;Latitude&quot; { type_ref Real; }
}
sa_data_type located &quot;Located asset&quot; {
definition { Record { supertype &#64;coordinate; }; };
sa_data_field supply &quot;Supply&quot; { type_ref { Named &#64;voltage; }; }
}
sa_exchange_item navigate &quot;Navigate&quot; {
mechanism Operation;
sa_data_field origin &quot;Origin&quot; { type_ref { Named &#64;coordinate; }; direction In; }
sa_data_field destination &quot;Destination&quot; { type_ref { Named &#64;coordinate; }; direction In; }
sa_data_field accepted &quot;Accepted&quot; { type_ref Boolean; direction Return; }
}
sa_interface navigation &quot;Navigation&quot; {}
sa_interface monitoring &quot;Monitoring&quot; {}
interface_item_allocation nav_operation &quot;Navigation operation&quot; {
source &#64;navigation; target &#64;navigate; transmission Synchronous; acquisition Accept;
}
interface_item_allocation monitor_operation &quot;Monitoring operation&quot; {
source &#64;monitoring; target &#64;navigate; transmission Asynchronous; acquisition Read;
}
data_association location_link &quot;Location relationship&quot; {
source &#64;coordinate; target &#64;located;
source_role &quot;location&quot;; target_role &quot;assets&quot;;
source_maximum 1;
}
}</code></pre>
</section>
</section>
<section id="diagrams-artifacts-and-cross-layer-traceability">
<h2>5. Diagrams, artifacts, and cross-layer traceability</h2>
@@ -1308,7 +1456,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 3;
<pre class="code text literal-block"><code>arcadia 4;
project operating &quot;Operating modes&quot; {
oa_entity crew &quot;Crew&quot; {}
oa_state_machine modes &quot;Modes&quot; { parent &#64;crew; }
@@ -1517,7 +1665,7 @@ spellings can be used in alias positions because references begin with <span cla
<span class="docutils literal"><span class="pre">element-kind</span></span> and <span class="docutils literal"><span class="pre">relation-kind</span></span> are exactly the corresponding declaration
keywords listed above. Typed field
sets and enum constructors are closed by sections 3–5.</p>
<pre class="code text literal-block"><code>document = &quot;arcadia&quot; &quot;3&quot; &quot;;&quot; project
<pre class="code text literal-block"><code>document = &quot;arcadia&quot; &quot;4&quot; &quot;;&quot; project
project = &quot;project&quot; alias string identity? &quot;{&quot; project-entry* &quot;}&quot;
project-entry = &quot;description&quot; string &quot;;&quot; | declaration
declaration = element
@@ -1554,16 +1702,16 @@ Ordinary string fields require quoted strings and cannot contain an unquoted
<span class="docutils literal">&#64;alias</span> reference. Enum fields require unquoted named values or their typed
constructor records. Typed values MUST NOT nest more than 64 levels; malformed
deeply nested drafts produce a diagnostic instead of exhausting the parser stack.</p>
<section id="modular-source3-projects">
<h3>6.1. Modular source3 projects</h3>
<section id="modular-source-projects">
<h3>6.1. Modular source projects</h3>
<p>The pure <span class="docutils literal">source_project</span> core API compiles a virtual source bundle, containing
<span class="docutils literal">entry</span> and a <span class="docutils literal">files</span> map from logical paths to UTF-8 strings. Its entry is a
root-level <span class="docutils literal">.arcadia</span> file with the source3 project header above. A project entry
root-level <span class="docutils literal">.arcadia</span> file with the source4 project header above. A project entry
MAY also be <span class="docutils literal">include string &quot;;&quot;</span>. An included fragment consists only of ordinary
declarations and include statements; it MUST NOT contain another version header,
project wrapper, or project description. Includes MUST occur at document level,
never inside an element body or typed field value. For example:</p>
<pre class="literal-block">arcadia 3;
<pre class="literal-block">arcadia 4;
project rescue &quot;Rescue&quot; id &quot;00000000-0000-4000-8000-000000000001&quot; {
description &quot;Operational model&quot;;
include &quot;oa/participants.arcadia&quot;;
@@ -1621,9 +1769,12 @@ the source index. Columns remain one-based Unicode scalars within the real file;
spans never refer to concatenated or synthetic source.</p>
<p>Single-string parse/lint APIs remain filesystem-free and reject include
statements with an explicit source-bundle requirement. V1/V2 single-file imports
continue through their existing migration readers and reports. Modular projects
require source3; migration is performed before modular export, not independently
on included fragments. Modular source does not change the semantic JSON schema.</p>
continue through explicit migration. Modular projects accept source3 and source4;
source3 is upgraded as one project, preserving file paths, includes, nested
ownership and comments through targeted token edits. Generated allocation
declarations stay in their interface's existing file. Individual include fragments
are not independently migrated. Missing UUIDs stabilize before migration so new
allocation identities are deterministic on subsequent compilation.</p>
</section>
<section id="nested-element-ownership">
<h3>6.2. Nested element ownership</h3>
@@ -1827,9 +1978,31 @@ 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 V3 source bundle (<span class="docutils literal">arcadia 3</span>); other suffixes use V3 JSON. Both forms preserve the same
the accepted V4 source bundle (<span class="docutils literal">arcadia 4</span>); other suffixes use V4 JSON. Both forms preserve the same
complete model. JSON rejects unknown fields throughout typed payloads,
duplicate maps, unsupported versions, and structural errors.</p>
<p>The schema-3 reader freezes the changed data payloads and old constructor catalog;
schema-4 fields/constructors MUST NOT be silently accepted as schema 3. Existing
typed PortContract records remain unchanged. Information/Material/Energy retain
their nature with Unspecified mechanism; old Event becomes Information with Event
mechanism. Old bounds/defaults/supertypes are absent, String length is 0..unbounded,
and fields retain type/multiplicity/unit with Unspecified direction, Value storage
and no explicit default. No physical mechanism or direction is guessed.</p>
<p>Each old Interface.items entry generates one InterfaceItemAllocation with its
original zero-based order and Unspecified protocols. UUID v5 uses the project UUID
namespace and name <span class="docutils literal"><span class="pre">v2-interface-item:&lt;interface-uuid&gt;:&lt;item-uuid&gt;</span></span> consistently
for schema-2 and schema-3 inputs. Aliases are deterministic and collision-free;
collision with any existing identity is an error rather than an overwrite. Existing
interface/item identities remain intact. Old nested message values acquire a path
only when exactly one valid path exists. Ambiguous paths, including recursive
reuse, retain the old annotation with a located warning rather than guessing.</p>
<p>Migration reports additionally contain <span class="docutils literal">semantic_defaults</span> (object, field,
description), <span class="docutils literal">generated_interface_allocations</span> (id, source, target, alias,
order) and <span class="docutils literal">unresolved_message_values</span> (occurrence, field, reason). These new
report arrays default empty when reading older responses. Version 1 normalizes
through V2, then the typed-port V3 adapter and this shared V4 data upgrade. Original
V2 and real V3 fixtures remain unchanged compatibility inputs. Current exports
always use version 4; reading/migrating alone never saves or changes revisions.</p>
<p>Native source Save All checks the original contents of observed dependencies
before staging writes. Existing target files are replaced individually and the
entry is installed last. A transaction journal records originals and intended
@@ -1853,7 +2026,7 @@ defaults without changing any prior identity, name, reference, order, geometry,
artifact or trace field. The original V2 golden source/JSON in
<span class="docutils literal"><span class="pre">crates/oa-core/tests/fixtures</span></span> MUST NOT be regenerated from the newer demo;
they verify that every old persistent field survives. Canonical output writes
the added defaults through the explicit schema-3 migration.</p>
the added defaults through the explicit schema-3 and schema-4 migrations.</p>
<p>The V2 adapter preserves every original identity, alias, prose, parent,
placement, trace and artifact. Generic ports become Legacy with their original
direction/interface record. Existing FE endpoint IDs remain unchanged. For
@@ -1870,13 +2043,13 @@ IDs, required resolutions, generated endpoint IDs/aliases/owners, and boundary
orientation defaults. REST import, replacement, candidate validation and
project snapshots surface the same report. Opening an old server envelope
preserves its resource ID/revision and bytes; the next explicit edit writes
schema 3. Model/source exports contain only the canonical model. Migration
schema 4. Model/source exports contain only the canonical model. Migration
reports are transient response metadata, not persisted model facts.</p>
<p>Admission checks account for generated objects and their references before
construction. Both the old V2 contract and the resulting V3 graph are
construction. Both the old V2 contract and the resulting V4 graph are
validated. Migration itself does not save or increase a stored revision.
Canonical second saves are stable. V1 normalization produces the frozen V2
model and then uses this same V2-to-3 stage.</p>
model and then uses these same V2-to-3-to-4 stages.</p>
<p>Save validates a snapshot, writes a sibling temporary file, flushes it, and
atomically replaces the destination. Failed serialization or validation must
not truncate a previous file. External concurrent-writer conflict resolution
@@ -1892,20 +2065,20 @@ step becomes a distinct occurrence element owned by its process. Generated
diagram, node, and occurrence identities use UUID v5 with the old Project ID
as namespace and deterministic role/index names. If such an identity collides,
a deterministic suffix is tried. Reimporting the same fully identified V1
input therefore yields the same V3 result, including repeated occurrences.
input therefore yields the same V4 result, including repeated occurrences.
No System or SA content is invented during an OA-only migration.</p>
<p>V1 source aliases are retained when valid in V2. JSON imports generate the old
canonical aliases deterministically. Any alias newly reserved in V2 is changed
by a deterministic suffix; aliases were not persistent V1 semantic data.
A project alias and aliases for new records are generated without colliding
with retained aliases. The existing bundled V1 text and JSON migrate to equal
V3 projects. Future versions remain errors until a separate migration exists.</p>
V4 projects. Future versions remain errors until a separate migration exists.</p>
</section>
<section id="complete-authoring-example">
<h2>10. Complete authoring example</h2>
<p>This document intentionally omits IDs for new authoring. Apply and Save write
the assigned UUIDs explicitly.</p>
<pre class="code text literal-block"><code>arcadia 3;
<pre class="code text literal-block"><code>arcadia 4;
project harbor &quot;Harbor assistance&quot; {
oa_entity control &quot;Harbor control&quot; {}
oa_activity assess &quot;Assess assistance&quot; {}