<p>Compilation inserts UUIDs into headers that omit them. Import returns 201 with
Location/ETag; GET source-project retrieves the stabilized accepted bundle.
PUT returns <spanclass="docutils literal">revision</span>, <spanclass="docutils literal">changed</span>, located <spanclass="docutils literal">issues</span> and that accepted
<spanclass="docutils literal">source_project</span>. Preserve the returned IDs before subsequent editing.
With explicit IDs, untouched text, comments, line endings, entry name and module
ownership are preserved exactly. Re-submitting the same accepted bundle is a
no-op. Removing a file means submitting a complete valid bundle without that
file and its includes; no files are created or deleted on the service host.</p>
<p>All typed command, transition, rename and model-interchange writes update this
same accepted source project. Existing declarations and reference comments
follow command identity correspondence, including UUID swaps. Full-model
replacement uses common UUIDs as its correspondence boundary. It preserves
the accepted source layout; canonical interchange formatting/comments are not
adopted as a replacement authored workspace. Use source-project PUT for
authoring file layout and comments. A failed source writeback rejects the whole
write and never falls back to discarding authored files.</p>
<p>Old model-only envelopes are migrated to a deterministic source bundle in
memory when opened. Reading or an exact no-op does not rewrite their files or
advance revisions. Their next changed write persists both representations.
Startup rejects already-coupled envelopes whose source/model disagree or whose
source lacks stable IDs. The 256 MiB store budget charges complete accepted
envelopes, including the generated source of old envelopes before their next
save; an over-capacity old store is reported rather than silently pruned.</p>
{"Describe": ["1b37b9d7-9a95-4a51-8707-010878a82419", "Review the request."]}
],
"dry_run": true
}</pre>
<p>One-field variants use <spanclass="docutils literal"><spanclass="pre">{"Delete":"uuid"}</span></span>; tuple variants use arrays;
named-field variants use objects. For a new typed OA activity:</p>
<p><spanclass="docutils literal">CreateArtifact</span>/<spanclass="docutils literal">EditArtifact</span> and <spanclass="docutils literal">CreateTrace</span>/<spanclass="docutils literal">EditTrace</span> use the same
transaction boundary as engineering edits. Artifact URI, revision and fragment
strings are opaque references. No URI is fetched or verified by the service.
Model references and alias uniqueness are checked by the core.</p>
<p>At most 200 commands are allowed, counting nested Batch wrappers. Explicit
creation identities allow later commands in the batch to reference earlier
creations. The shared <spanclass="docutils literal">execute_batch</span> applies all operations to one candidate
and validates the final state. A rejected operation or final structural error
rejects the whole request. Reference rewrites/deletion cleanup follow the same
<p>Dry run still requires <spanclass="docutils literal"><spanclass="pre">If-Match</span></span>. Its response includes <spanclass="docutils literal">revision</span>,
<spanclass="docutils literal">dry_run</span>, <spanclass="docutils literal">changed</span>, <spanclass="docutils literal">issues</span> and the proposed <spanclass="docutils literal">model</span> and
<spanclass="docutils literal">source_project</span>. It validates source writeback as well as semantics and neither writes
nor reserves IDs. A committed response omits the proposed model and source
project. Commit must check the revision again. A no-op is successful with
<p><spanclass="docutils literal">NodePlacement.port_anchors</span> is an optional list of
<spanclass="docutils literal"><spanclass="pre">{"port":"<port</span><spanclass="pre">UUID>","side":"Top","offset":0.25}</span></span> records. Side is
Left, Right, Top, or Bottom; offset is a finite fraction from 0 through 1,
measured from top on vertical edges and from left on horizontal edges.
The port must be a direct child of the placement's semantic element and occur
at most once in its anchor list. Placement is presentation state; it changes
neither semantic ownership nor port direction. Other diagrams are independent.</p>
{"SequenceReference":{"sequence":"<process or chain UUID>"}}</pre>
<p><spanclass="docutils literal">ControlKind</span> is <spanclass="docutils literal">Choice</span>, <spanclass="docutils literal">Merge</span>, <spanclass="docutils literal">Fork</span>, <spanclass="docutils literal">Join</span> or <spanclass="docutils literal">Loop</span>.
<spanclass="docutils literal">RelationBody.SequenceLink</span> connects contribution IDs in one owner and
contains <spanclass="docutils literal">source</span>, <spanclass="docutils literal">target</span> and a string <spanclass="docutils literal">guard</span>. Conditions belong to
choice/loop paths; an explicit <spanclass="docutils literal">else</span> guard can describe the other path.
The readable order of the <spanclass="docutils literal">steps</span> list remains persistent, while links
express the explicit alternative, parallel and loop topology. The core checks
owner context, work/exchange endpoint agreement and recursive sequence reuse;
engineering diagnostics identify incomplete branch cardinality or paths.
Old exchange-only sequences without explicit links retain their linear meaning.</p>
<p>These records use the same create/edit transaction commands and source/model
replacement routes as other engineering records. For example,
<spanclass="docutils literal">GET <spanclass="pre">/api/v1/projects/{id}/relations?kind=SequenceLink</span></span> queries the links.
The source representation uses <spanclass="docutils literal">sequence @alias</span> references. The service
does not execute conditions or simulate a process.</p>
<p>Scenario bodies store an explicit <spanclass="docutils literal">viewpoint</span>. Occurrence Exchange bodies
store <spanclass="docutils literal">message_kind</span>, optional correlated-call <spanclass="docutils literal">reply_to</span> and contextual
<spanclass="docutils literal">values</span>. Message kinds are Asynchronous, Call, Reply, Create, Delete, or
<spanclass="docutils literal"><spanclass="pre">{"Timer":{"expression":"after</span> 5 <spanclass="pre">s"}}</span></span>. Each value record contains a
<p><spanclass="docutils literal">ScenarioUse</span> contains a referenced <spanclass="docutils literal">scenario</span> and one-to-one lifeline
<spanclass="docutils literal">bindings</span> records with <spanclass="docutils literal">referenced</span> and <spanclass="docutils literal">local</span> UUIDs. The core validates
viewpoint/layer compatibility, call/reply order and reversal, lifetime order,
carried fields, binding identity and recursive reuse through the same candidate
boundary used by the desktop. The normative details are in <spanclass="docutils literal">language.rst</span>.</p>
<p>Existing schema-2 files may omit the new fields: missing viewpoint maps to
MixedLegacy and missing message fields to Asynchronous, null and []. Source
exports make those compatibility defaults explicit. This preserves original V2
models while the release schema is being integrated; it does not silently
reinterpret old mixed lifelines as a strict new viewpoint.</p>
<p>Schema4 uses typed bounded DataTypeDefinition and DataValue constructors, field
storage/defaults/directions, and single specialization. Exact JSON shapes are in
<spanclass="docutils literal">openapi.json</span> and semantic rules and runnable source in <spanclass="docutils literal">language.rst</span> section 4.5.
Interface membership is an identified InterfaceItemAllocation relation with
independent order/transmission/acquisition. DataAssociation relates Record types
with named, navigable, multiplicity-bearing ends; it does not add carried fields.</p>
<p>Use ordinary relation queries, transactions and artifact links, for example
<spanclass="docutils literal">GET <spanclass="pre">/api/v1/projects/{id}/relations?kind=InterfaceItemAllocation</span></span>. The service
and desktop use the same inheritance/path/default validation. Invalid bounds,
defaults, directions, cycles or contract-breaking deletions reject atomically,
preserving the accepted source/model, revision and stored bytes. Correct a related
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
<p>OA and SA Event records use the same <spanclass="docutils literal"><spanclass="pre">SharedBody::Event</span></span> and <spanclass="docutils literal">EventBody</span>
contract as source and graphical editing. Signal carries same-layer item
references; Time specifies After/At and an expression; Change specifies a
condition expression. State vertices include Choice, Junction, Fork, Join,
ShallowHistory, DeepHistory, EntryPoint, ExitPoint and Terminate, as well as
State, Mode, Initial and Final. Query these through the ordinary <spanclass="docutils literal">kind</span>
filters. No timer or executable state-machine service is implied.</p>
<p>StateTransition keeps <spanclass="docutils literal">trigger</span>, <spanclass="docutils literal">guard</span> and <spanclass="docutils literal">effect</span> prose and adds
<spanclass="docutils literal">transition_kind</span> (External/Local/Internal), <spanclass="docutils literal">triggers</span> (Event or work UUIDs)
and <spanclass="docutils literal">effects</span> (work UUIDs). The reference lists use UUIDs in JSON and aliases
in source. Missing new properties in staged schema-2 input hydrate as
External/[]/[] without changing prior text. These defaults are compatibility
behavior pending the distinct release schema, not a versionless expansion of
every future input contract.</p>
<p>Use one ordinary transaction to create an event and edit its referring
transition. Reidentification updates references, and deletion prunes signal
items and effect references. Removing the last typed trigger with no prior
trigger prose leaves a descriptive replacement reminder; it does not silently
introduce a completion transition. Invalid typed references reject the whole
candidate and preserve revision/ETag. All writes retain the same conditional
commit and disk persistence contract as other semantic records.</p>
<p>The same import, replacement and command endpoints admit OA
<spanclass="docutils literal">CommunicationMean { source, target, oriented, items }</span> and root-level
<spanclass="docutils literal">ExchangeCategory { family, exchanges }</span> records. Communication means join
distinct OA entities/actors. Categories group same-layer exchanges as <spanclass="docutils literal">Work</span>
or <spanclass="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><spanclass="docutils literal">Diagram.view_options</span> is an optional closed object with defaults: empty
<spanclass="docutils literal">hidden_edges</span>, <spanclass="docutils literal">All</span> for <spanclass="docutils literal">relation_kinds</span>, both category selections,
<spanclass="docutils literal">coverage</span> and <spanclass="docutils literal">work_contexts</span>, and <spanclass="docutils literal">Name</span> for <spanclass="docutils literal">exchange_labels</span>.
<spanclass="docutils literal"><spanclass="pre">{"Only":[]}</span></span> hides all relation and trace lines; <spanclass="docutils literal"><spanclass="pre">{"Any":[]}</span></span> preserves
an explicit empty category/context selection. Category members union within
each family, and independent filters intersect. <spanclass="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 <spanclass="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>
<p><spanclass="docutils literal">OccurrenceBody.Exchange.operation</span> is optional. Absent/null retains ordinary
channel semantics and is omitted in canonical output. <spanclass="docutils literal"><spanclass="pre">{"allocation":null}</span></span>
(or an empty object) retains explicit unresolved operation intent. A selected
<spanclass="docutils literal"><spanclass="pre">{"allocation":"<InterfaceItemAllocation</span><spanclass="pre">UUID>"}</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>
<p>SA→OA abstraction of explicit operation intent requires <spanclass="docutils literal">operation_omissions</span>
(omitted means empty). Each closed record contains the selected invocation's
<spanclass="docutils literal">source</span> UUID and a nonempty <spanclass="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 <spanclass="docutils literal">CommunicationMean</span> maps to an SA <spanclass="docutils literal">BoundaryExchange</span> through an explicit
<spanclass="docutils literal">communication_endpoints</span> array (omitted means empty). Each decision identifies
the source communication means and both <spanclass="docutils literal">source_port</span> and <spanclass="docutils literal">target_port</span>.
Each port choice is either <spanclass="docutils literal"><spanclass="pre">{"Reuse":{"port":"port-uuid"}}</span></span> or
<spanclass="docutils literal"><spanclass="pre">{"Create":{"id":"new-port-uuid","alias":"radio_port","name":"Radio</span> port", <spanclass="pre">"description":"","kind":"Standard","orientation":"Unset"}}</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><spanclass="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 <spanclass="docutils literal">Category.Family</span> and the
<spanclass="docutils literal">CategoryExchanges</span> member collection; historical review facts remain exact.</p>
<p>The preview response is <spanclass="docutils literal"><spanclass="pre">{"base_revision":1,"plan":{...}}</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
requires the original ETag in <spanclass="docutils literal"><spanclass="pre">If-Match</span></span>. It checks both base_revision and the
core's snapshot fingerprint before executing the shared transition validator.
Stale revisions fail with 412 and unresolved conflicts with 422. Successful
apply increments the revision once, preserving the planned identities.</p>
<p>A supplied plan is a client-owned command proposal. It is not cryptographically
authenticated as an untouched server preview; the same authenticated client
can submit ordinary typed commands. The core fingerprint is a change detector,
not a security digest. There is no plan token, expiration store or receipt.</p>
<p>Facet selectors are closed enums, for example <spanclass="docutils literal"><spanclass="pre">{"Data":"IntegerMinimum"}</span></span>
or <spanclass="docutils literal"><spanclass="pre">{"Member":{"collection":"SignalItems","keys":{"oa":"oa-uuid","sa":"sa-uuid"}}}</span></span>.
Annotation keys contain the entire path and field; enum literal keys are exact
strings. <spanclass="docutils literal">KeepTarget</span>, <spanclass="docutils literal">TakeSource</span> and <spanclass="docutils literal">Candidate</span> operate on independently
selected facts. Candidate records use existing Element/Relation/ArtifactLink
types, must preserve identity/alias, and must equal precisely the result of
the selected facets. Constructor review covers its coupled introduced/removed
fields. Membership review does not silently acknowledge order; target-only
members remain independent. OpenAPI defines every selector and typed payload.</p>
<p>Preview requires <spanclass="docutils literal"><spanclass="pre">If-Match</span></span> and returns <spanclass="docutils literal"><spanclass="pre">{"base_revision":1,"plan":{...}}</span></span>.
The plan contains the original typed request, mapping plan, review facts,
<spanclass="docutils literal">code</span> for client decisions, not the English message. <spanclass="docutils literal"><spanclass="pre">X-Request-ID</span></span> is a
response correlation UUID. This is not an idempotency key or receipt address.</p>
<ulclass="simple">
<li><p>400: malformed JSON/envelope/query/UUID or unsupported ETag form.</p></li>
<li><p>401: missing or incorrect configured bearer token; includes WWW-Authenticate.</p></li>
<li><p>403: browser Origin is unsupported, or unauthenticated Host is not loopback.</p></li>
<li><p>404: missing project or route.</p></li>
<li><p>405: unsupported HTTP method.</p></li>
<li><p>409: requested query revision changed or revision counter exhausted.</p></li>
