Complete source 6 engineering workflows and preserve release validation evidence
This commit is contained in:
Codex
+102
-14
@@ -1,8 +1,8 @@
|
||||
Arcadia Studio OA / SA Language and Editing Contract
|
||||
====================================================
|
||||
|
||||
:Version: 5
|
||||
:Status: Normative current implementation contract; first-release integration
|
||||
:Version: 6 (integration in progress)
|
||||
:Status: Source-6 contract under integration; native and API acceptance pending
|
||||
:Core implementation: ``crates/oa-core``
|
||||
:Text suffix: ``.arcadia``
|
||||
|
||||
@@ -11,10 +11,12 @@ 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 and 4. MUST, MUST NOT,
|
||||
validation, persistence, and explicit migration from versions 1, 2, 3, 4 and 5. MUST, MUST NOT,
|
||||
and MAY indicate requirements, prohibitions, and permitted choices.
|
||||
|
||||
Schema 5 adds closed typed semantic review facts to trace baselines, including
|
||||
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
|
||||
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
|
||||
@@ -41,7 +43,7 @@ Actual verification evidence is separate from this contract.
|
||||
2. One authoritative model
|
||||
--------------------------
|
||||
|
||||
A Project stores ``schema_version`` (5), ``id``, ``alias``, ``name``,
|
||||
A Project stores ``schema_version`` (6), ``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.
|
||||
@@ -246,6 +248,9 @@ references. Their kind is the declaration keyword:
|
||||
* - ``boundary_exchange``
|
||||
- Different participant owners; typed component ports have matching kinds
|
||||
- ``oriented`` bool / true; ``items`` refs / []
|
||||
* - ``communication_mean``
|
||||
- Different OA Entity/Actor elements; no operational ports or role inference
|
||||
- ``oriented`` bool / false; ``items`` refs / []
|
||||
* - ``port_allocation``
|
||||
- SA Component port → SA FunctionInput/FunctionOutput port
|
||||
- Requires the function's actual work Allocation to that component
|
||||
@@ -286,7 +291,7 @@ references. Their kind is the declaration keyword:
|
||||
- Work, participant, capability, or process/chain → state/mode
|
||||
- None
|
||||
* - ``exchange_allocation``
|
||||
- Boundary-exchange relation → same-layer interaction (OA) or functional exchange (SA)
|
||||
- CommunicationMean → OA Interaction, or BoundaryExchange → same-layer Interaction/FunctionalExchange
|
||||
- None
|
||||
* - ``interface_provision``, ``interface_requirement``
|
||||
- Participant/port → provided/required interface
|
||||
@@ -300,6 +305,89 @@ 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.
|
||||
|
||||
Source-6 communication and exchange categories
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
An OA ``communication_mean`` 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.
|
||||
|
||||
``exchange_allocation`` 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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
``oa_exchange_category`` and ``sa_exchange_category`` are root-level named
|
||||
semantic elements with ``family`` Work (default) or Participant, and ``exchanges``
|
||||
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. ``Category.Family`` and
|
||||
``Member { collection CategoryExchanges; ... }`` 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.
|
||||
|
||||
Each Diagram has optional ``view_options`` (all selections unrestricted, no hidden
|
||||
edges, Name labels by default). Its closed fields are ``hidden_edges``,
|
||||
``relation_kinds``, ``work_categories``, ``participant_categories``, ``coverage``,
|
||||
``work_contexts`` and ``exchange_labels``. 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.
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
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
|
||||
@@ -356,7 +444,7 @@ Port deletion cascades to incident FEs; FE deletion retains independent ports.
|
||||
|
||||
For example::
|
||||
|
||||
arcadia 5;
|
||||
arcadia 6;
|
||||
project ports_example "Typed function contract" {
|
||||
sa_function send "Send" {}
|
||||
sa_function receive "Receive" {}
|
||||
@@ -739,7 +827,7 @@ This complete data contract example is also exercised through the REST API:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
arcadia 5;
|
||||
arcadia 6;
|
||||
project engineering_data "Engineering data" {
|
||||
sa_data_type voltage "Voltage" {
|
||||
definition { Real { minimum 0.0; maximum 48.0; }; };
|
||||
@@ -808,7 +896,7 @@ This complete source example places one state from an existing machine:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
arcadia 5;
|
||||
arcadia 6;
|
||||
project operating "Operating modes" {
|
||||
oa_entity crew "Crew" {}
|
||||
oa_state_machine modes "Modes" { parent @crew; }
|
||||
@@ -1262,7 +1350,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 5;
|
||||
arcadia 6;
|
||||
project reviewed_dimensions "Reviewed dimensions" {
|
||||
oa_data_type oa_dimension "Operational distance" {
|
||||
definition { Integer { minimum 0; maximum 10; }; };
|
||||
@@ -1421,7 +1509,7 @@ 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 5;
|
||||
arcadia 6;
|
||||
project rescue "Rescue" id "00000000-0000-4000-8000-000000000001" {
|
||||
description "Operational model";
|
||||
include "oa/participants.arcadia";
|
||||
@@ -1778,7 +1866,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 V5 source bundle (``arcadia 5``); other suffixes use V5 JSON. Both forms preserve the same
|
||||
the accepted V6 source bundle (``arcadia 6``); other suffixes use V6 JSON. Both forms preserve the same
|
||||
complete model. JSON rejects unknown fields throughout typed payloads,
|
||||
duplicate maps, unsupported versions, and structural errors.
|
||||
|
||||
@@ -1814,7 +1902,7 @@ 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 5; reading/migrating alone never saves or changes revisions.
|
||||
always use version 6; reading/migrating alone never saves or changes revisions.
|
||||
|
||||
Native source Save All checks the original contents of observed dependencies
|
||||
before staging writes. Existing target files are replaced individually and the
|
||||
@@ -1903,7 +1991,7 @@ the assigned UUIDs explicitly.
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
arcadia 5;
|
||||
arcadia 6;
|
||||
project harbor "Harbor assistance" {
|
||||
oa_entity control "Harbor control" {}
|
||||
oa_activity assess "Assess assistance" {}
|
||||
|
||||
Reference in New Issue
Block a user