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
Rust checks / check (ubuntu-latest) (push) Canceled after 0s
Rust checks / check (windows-latest) (push) Canceled after 0s
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
+113
-9
@@ -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">{
|
||||
"entry": "rescue.arcadia",
|
||||
"files": {
|
||||
"rescue.arcadia": "arcadia 5; 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"
|
||||
}
|
||||
}</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 @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">{
|
||||
"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"}}
|
||||
}
|
||||
}</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">{"format":"arcadia", "source":"complete source document"}</pre>
|
||||
<p>or:</p>
|
||||
<pre class="literal-block">{"format":"source-project", "source_project":{"entry":"rescue.arcadia", "files":{"rescue.arcadia":"arcadia 5; project rescue \"Rescue\" {}"}}}</pre>
|
||||
<pre class="literal-block">{"format":"source-project", "source_project":{"entry":"rescue.arcadia", "files":{"rescue.arcadia":"arcadia 7; project rescue \"Rescue\" {}"}}}</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">{"Only":[]}</span></span> hides all relation and trace lines; <span class="docutils literal"><span class="pre">{"Any":[]}</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">{"allocation":null}</span></span>
|
||||
(or an empty object) retains explicit unresolved operation intent. A selected
|
||||
<span class="docutils literal"><span class="pre">{"allocation":"<InterfaceItemAllocation</span> <span class="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>
|
||||
</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">{"Reuse":{"port":"port-uuid"}}</span></span> or
|
||||
<span class="docutils literal"><span class="pre">{"Create":{"id":"new-port-uuid","alias":"radio_port","name":"Radio</span> port", <span class="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><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">{"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
|
||||
@@ -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;
|
||||
|
||||
Reference in New Issue
Block a user