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

Complete source 6 engineering workflows and preserve release validation evidence

Browse Source
This commit is contained in:
Codex
2026-09-06 21:49:04 -07:00
parent 2b2d2bc18b
commit 4b6b5fc197
290 changed files with 48271 additions and 1791 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api.rst
+53 -7
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 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 and current schema-6 JSON. Source import uses the shared language parser
and its supported migrations. Export uses schema 6 / arcadia 6. 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 5; project rescue \"Rescue\" { include \"oa/work.arcadia\"; }\n",
"rescue.arcadia": "arcadia 6; 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 source5; source3/4 bundles migrate explicitly while
the complete bundle, not separately per file. Current bundle syntax is source6; source3/4/5 bundles migrate explicitly while
preserving their files/includes/comments. V1/V2 single-file migration remains
available through interchange import.
@@ -403,7 +403,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 schema5/source5. Reading an old envelope does not write it or
current exports use schema6/source6. Reading an old envelope does not write it or
advance its ETag. Canonical exports omit transient migration reports.
Validation
@@ -419,7 +419,7 @@ or::
or::
{"format":"source-project", "source_project":{"entry":"rescue.arcadia", "files":{"rescue.arcadia":"arcadia 5; project rescue \"Rescue\" {}"}}}
{"format":"source-project", "source_project":{"entry":"rescue.arcadia", "files":{"rescue.arcadia":"arcadia 6; 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.
@@ -491,17 +491,63 @@ 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.
Source-6 communication and saved views
-------------------------------------
The same import, replacement and command endpoints admit OA
``CommunicationMean { source, target, oriented, items }`` and root-level
``ExchangeCategory { family, exchanges }`` records. Communication means join
distinct OA entities/actors. Categories group same-layer exchanges as ``Work``
or ``Participant`` without owning them. Existing legacy OA boundary exchanges
retain their identities and contracts; migration does not silently replace them.
``Diagram.view_options`` is an optional closed object with defaults: empty
``hidden_edges``, ``All`` for ``relation_kinds``, both category selections,
``coverage`` and ``work_contexts``, and ``Name`` for ``exchange_labels``.
``{"Only":[]}`` hides all relation and trace lines; ``{"Any":[]}`` preserves
an explicit empty category/context selection. Category members union within
each family, and independent filters intersect. ``Traceability`` 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.
Earlier schema/source versions 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
options. The OpenAPI document describes current records; it is not a permissive
union of historical input formats. Source-6 integration and release acceptance
are tracked separately in the release coverage audit.
Cross-layer transitions
-----------------------
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 and 400 field resolutions are
in OpenAPI. At most 100 sources, 200 mappings, 200 communication endpoint
decisions 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.
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``.
Each port choice is either ``{"Reuse":{"port":"port-uuid"}}`` or
``{"Create":{"id":"new-port-uuid","alias":"radio_port","name":"Radio port",
"description":"","kind":"Standard","orientation":"Unset"}}``. 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.
``ExchangeCategory`` transitions preserve their family and map only explicitly
corresponding member exchanges. Missing member mappings are conflicts, not new
fabricated exchanges. Typed review exposes ``Category.Family`` and the
``CategoryExchanges`` member collection; historical review facts remain exact.
The preview response is ``{"base_revision":1,"plan":{...}}``. 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
docs/language.rst
+102 -14
View File
@@ -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" {}
docs/openapi.json
+442 -16
View File
@@ -3,7 +3,7 @@
"info": {
"title": "Arcadia Studio model API",
"version": "1.0.0",
"description": "Current schema-5 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-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."
},
"servers": [
{
@@ -389,7 +389,7 @@
}
}
},
"description": "Schema-5 native JSON is described below. Schema-1/2/3/4 JSON and source are accepted through explicit frozen readers and migration, also on replacement and candidate validation. Prior prose reviews remain intact; absent semantic review stays Unreviewed. Export emits schema 5 / arcadia 5. See docs/language.rst."
"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."
}
},
"/api/v1/projects/{id}": {
@@ -2039,6 +2039,7 @@
"Mission",
"FunctionalChain",
"ExchangeItem",
"ExchangeCategory",
"DataType",
"DataField",
"Interface",
@@ -2068,7 +2069,10 @@
"RelationKind": {
"type": "string",
"enum": [
"InterfaceItemAllocation",
"DataAssociation",
"Allocation",
"PortAllocation",
"Interaction",
"CapabilityInvolvement",
"ChainInvolvement",
@@ -2076,21 +2080,19 @@
"RoleAssignment",
"FunctionalExchange",
"BoundaryExchange",
"CommunicationMean",
"MissionCapability",
"StateTransition",
"Availability",
"ExchangeAllocation",
"InterfaceProvision",
"InterfaceRequirement",
"StateAction",
"CapabilityInclude",
"CapabilityExtend",
"CapabilityGeneralization",
"MissionInvolvement",
"SequenceLink",
"PortAllocation",
"InterfaceItemAllocation",
"DataAssociation"
"StateTransition",
"Availability",
"ExchangeAllocation",
"InterfaceProvision",
"InterfaceRequirement",
"StateAction"
]
},
"Position": {
@@ -3118,6 +3120,34 @@
"Event"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"ExchangeCategory": {
"type": "object",
"properties": {
"family": {
"$ref": "#/components/schemas/ExchangeFamily"
},
"exchanges": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Id"
}
}
},
"required": [
"family",
"exchanges"
],
"additionalProperties": false
}
},
"required": [
"ExchangeCategory"
],
"additionalProperties": false
}
]
}
@@ -4089,6 +4119,42 @@
"DataAssociation"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"CommunicationMean": {
"type": "object",
"properties": {
"source": {
"$ref": "#/components/schemas/Id"
},
"target": {
"$ref": "#/components/schemas/Id"
},
"oriented": {
"type": "boolean"
},
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Id"
}
}
},
"required": [
"source",
"target",
"oriented",
"items"
],
"additionalProperties": false
}
},
"required": [
"CommunicationMean"
],
"additionalProperties": false
}
]
},
@@ -4289,6 +4355,10 @@
},
"default": [],
"description": "Unique by edge identity within this diagram. Stored order is retained. Each entry counts against the total model record admission limit. Missing routes in earlier schema-3 models default to empty."
},
"view_options": {
"$ref": "#/components/schemas/ViewOptions",
"default": {}
}
},
"required": [
@@ -4485,7 +4555,7 @@
"properties": {
"schema_version": {
"type": "integer",
"const": 5
"const": 6
},
"id": {
"type": "string",
@@ -6139,6 +6209,15 @@
"type": "null"
}
]
},
"communication_endpoints": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CommunicationEndpointDecision"
},
"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."
}
},
"required": [
@@ -6652,12 +6731,13 @@
1,
2,
3,
4
4,
5
]
},
"to_schema": {
"type": "integer",
"const": 5
"const": 6
},
"preserved_ports": {
"type": "array",
@@ -6844,11 +6924,11 @@
"required_resolutions"
],
"additionalProperties": false,
"description": "Transient observations from explicit V1/V2/V3/V4 to V5 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 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>."
},
"SourceBundle": {
"type": "object",
"description": "Complete source5 workspace (source3/4 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 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.",
"properties": {
"entry": {
"type": "string"
@@ -7126,6 +7206,7 @@
"FunctionOutputItems",
"SignalItems",
"ExchangeItems",
"CategoryExchanges",
"TransitionTriggers",
"TransitionEffects",
"Constrained"
@@ -10792,6 +10873,18 @@
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"Category": {
"$ref": "#/components/schemas/CategoryFacet"
}
},
"required": [
"Category"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
@@ -11087,6 +11180,18 @@
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"Category": {
"$ref": "#/components/schemas/CategoryReview"
}
},
"required": [
"Category"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
@@ -11987,6 +12092,327 @@
"items"
],
"additionalProperties": false
},
"ExchangeFamily": {
"type": "string",
"enum": [
"Work",
"Participant"
]
},
"Coverage": {
"type": "string",
"enum": [
"All",
"InBehavior",
"OutsideBehavior"
]
},
"ExchangeLabels": {
"type": "string",
"enum": [
"Name",
"Items",
"NameAndItems"
]
},
"CategoryFacet": {
"type": "string",
"enum": [
"Family"
]
},
"ReviewedExchangeFamily": {
"type": "object",
"properties": {
"oa": {
"oneOf": [
{
"type": "string",
"enum": [
"NotApplicable"
]
},
{
"type": "object",
"properties": {
"Value": {
"$ref": "#/components/schemas/ExchangeFamily"
}
},
"required": [
"Value"
],
"additionalProperties": false
}
]
},
"sa": {
"oneOf": [
{
"type": "string",
"enum": [
"NotApplicable"
]
},
{
"type": "object",
"properties": {
"Value": {
"$ref": "#/components/schemas/ExchangeFamily"
}
},
"required": [
"Value"
],
"additionalProperties": false
}
]
}
},
"required": [
"oa",
"sa"
],
"additionalProperties": false
},
"CategoryReview": {
"oneOf": [
{
"type": "object",
"properties": {
"Family": {
"$ref": "#/components/schemas/ReviewedExchangeFamily"
}
},
"required": [
"Family"
],
"additionalProperties": false
}
]
},
"EdgeKind": {
"oneOf": [
{
"type": "string",
"enum": [
"Trace"
]
},
{
"type": "object",
"properties": {
"Relation": {
"$ref": "#/components/schemas/RelationKind"
}
},
"required": [
"Relation"
],
"additionalProperties": false
}
]
},
"RelationKinds": {
"oneOf": [
{
"type": "string",
"enum": [
"All"
]
},
{
"type": "object",
"properties": {
"Only": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EdgeKind"
}
}
},
"required": [
"Only"
],
"additionalProperties": false
}
]
},
"CategorySelection": {
"oneOf": [
{
"type": "string",
"enum": [
"All"
]
},
{
"type": "object",
"properties": {
"Any": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Id"
}
}
},
"required": [
"Any"
],
"additionalProperties": false
}
]
},
"ContextSelection": {
"oneOf": [
{
"type": "string",
"enum": [
"All"
]
},
{
"type": "object",
"properties": {
"Any": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Id"
}
}
},
"required": [
"Any"
],
"additionalProperties": false
}
]
},
"ViewOptions": {
"type": "object",
"properties": {
"hidden_edges": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Id"
},
"default": []
},
"relation_kinds": {
"$ref": "#/components/schemas/RelationKinds",
"default": "All"
},
"work_categories": {
"$ref": "#/components/schemas/CategorySelection",
"default": "All"
},
"participant_categories": {
"$ref": "#/components/schemas/CategorySelection",
"default": "All"
},
"coverage": {
"$ref": "#/components/schemas/Coverage",
"default": "All"
},
"work_contexts": {
"$ref": "#/components/schemas/ContextSelection",
"default": "All"
},
"exchange_labels": {
"$ref": "#/components/schemas/ExchangeLabels",
"default": "Name"
}
},
"required": [],
"additionalProperties": false,
"description": "Presentation only. Independent predicates intersect; category members union within a family. Only([]) hides all relations and traces. Any([]) remains an explicit empty selection. Traceability permits both-layer hidden/category/context references; ordinary projections require the diagram layer. Filtering preserves unfiltered automatic port positions."
},
"CommunicationPortChoice": {
"oneOf": [
{
"type": "object",
"properties": {
"Reuse": {
"type": "object",
"properties": {
"port": {
"$ref": "#/components/schemas/Id"
}
},
"required": [
"port"
],
"additionalProperties": false
}
},
"required": [
"Reuse"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"Create": {
"type": "object",
"properties": {
"id": {
"$ref": "#/components/schemas/Id"
},
"alias": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"kind": {
"$ref": "#/components/schemas/ComponentPortKind"
},
"orientation": {
"$ref": "#/components/schemas/ComponentPortOrientation"
}
},
"required": [
"id",
"alias",
"name",
"description",
"kind",
"orientation"
],
"additionalProperties": false
}
},
"required": [
"Create"
],
"additionalProperties": false
}
]
},
"CommunicationEndpointDecision": {
"type": "object",
"properties": {
"source": {
"$ref": "#/components/schemas/Id"
},
"source_port": {
"$ref": "#/components/schemas/CommunicationPortChoice"
},
"target_port": {
"$ref": "#/components/schemas/CommunicationPortChoice"
}
},
"required": [
"source",
"source_port",
"target_port"
],
"additionalProperties": false
}
}
}
docs/scope.md
+15 -10
View File
@@ -6,14 +6,14 @@ Arcadia Studio implements a systems-engineering workbench spanning Operational A
| Area | Implemented semantics and authoring |
|---|---|
| Operational Analysis | Entities, actors, roles, activities, missions, capabilities and processes; entity/work decomposition; leaf allocation; role realization/assignment; interactions and capability/process involvement |
| Operational Analysis | Entities, actors, roles, activities, missions, capabilities and processes; entity/work decomposition; leaf allocation; role realization/assignment; interactions, direct participant Communication means with direction/items and Interaction allocations, and capability/process involvement |
| System Analysis | One System of Interest, external Actors, functions, missions, capabilities and functional chains; functional decomposition independent of the system boundary; allocation, functional/boundary exchanges and mission-capability links |
| Data and interfaces | Information/material/energy nature and Flow/Event/Operation/SharedData mechanisms, bounded primitive/enum/record types, typed defaults, field multiplicity/units/direction/storage, specialization, identified interface allocations and reference associations, separate function input/output and Standard/Flow component ports, interface provision/requirement, port and exchange allocations |
| Behavior | Process/chain work and exchange contributions, control topology and sequence reuse; scenario lifelines, correlated calls/replies, timers, action/state occurrences, ALT/PAR/LOOP/OPTIONAL fragments, scenario reuse and pre/postconditions |
| States and conditions | Participant-owned state machines, nested regions, states/modes and typed pseudostates, signal/time/change events, trigger/guard/effect transitions, linked entry/do/exit work, availability and constraints |
| Perspectives and evidence | Bidirectional counterpart creation/linking, reviewed descriptive and typed semantic changes, many-to-many typed/manual traces, arbitrary artifact URI/revision/fragment references |
| Views and editing | Independent diagrams, decomposition/allocation nesting, collapse, pan/zoom/Fit/Arrange, editable connection routes and labels, four-side port positioning, direct interaction/functional/boundary exchange tools, contextual menus, SVG export, model explorer and typed properties |
| Text and storage | `arcadia 5` source projects with relative includes and nested declarations, stable aliases/UUIDs, a source-file tree, per-file drafts and diagnostics, comment-preserving graphical updates, exact model/source Undo/Redo, legacy migration, atomic saves, interrupted source-save recovery, Home/recents and private unsaved-work checkpoints |
| Perspectives and evidence | Bidirectional counterpart creation/linking, reviewed descriptive and typed semantic changes, explicit ordered collections and combined multi-source review, many-to-many typed/manual traces, arbitrary artifact URI/revision/fragment references |
| Views and editing | Independent and duplicated diagrams, decomposition/allocation nesting, collapse, pan/zoom/Fit/Arrange, editable connection routes and labels, four-side port positioning, direct interaction/communication/functional/boundary exchange tools, named exchange categories, saved line-kind/category/coverage/context/hide/label settings, contextual menus, SVG export, model explorer and typed properties |
| Text and storage | `arcadia 6` source projects with relative includes and nested declarations, stable aliases/UUIDs, a source-file tree, per-file drafts and diagnostics, comment-preserving graphical updates, exact model/source Undo/Redo, legacy migration, per-file atomic replacement with interrupted source-save recovery, Home/recents and private unsaved-work checkpoints |
| Automation and hosted editing | Rust REST service for project/source-bundle/query/validation/transaction/transition/artifact workflows; optional desktop catalog/open/publish, explicit conditional Save, server review and local Save as; ETag preconditions, bounded requests and atomic current-revision storage |
Graphical and textual parity applies to the persistent fields of this profile. Diagram placements are model data; camera, selection, source cursor and undo history are session state. Canvas gestures need not match textual operations one for one: typed inspectors and explicit commands expose precise semantics. Full source replacement must repair dependencies in its candidate, while graphical delete/reidentify commands maintain references automatically.
@@ -23,9 +23,10 @@ Graphical and textual parity applies to the persistent fields of this profile. D
- OA captures operational needs; SA defines the selected system contribution. SA contains no internal logical/physical components, and Studio does not decompose SA Actors. The System may be absent while authoring, with a completeness warning.
- Work decomposition and performer allocation are independent. Only leaves have direct allocations. A parent drawn within one performer can be a computed leaf summary, not an additional allocation. Role sharing does not create several direct performers for one function.
- Nesting expresses semantic containment or the selected allocation projection. Placement movement does not change ownership or allocation. Hide and delete have different effects.
- Counterpart creation copies mapped typed content and required references. Existing-counterpart semantic review compares typed facts and prior observations, with explicit keep, take or final-value decisions for supported scalar, structural, constructor and individual collection-row changes. Reference mapping and candidate validation apply before an undoable transaction. Ordered collections, attachment/artifact and multi-source GUI reconciliation remain unfinished. Review does not automatically synchronize arbitrary structure or overwrite the other perspective. Creation scope follows ownership/reference dependencies, not every incident relationship.
- Counterpart creation copies mapped typed content and required references. Existing-counterpart semantic review compares typed facts and prior observations, with explicit keep, take or final-value decisions for supported scalar, structural, constructor and individual collection-row changes. Reference mapping and candidate validation apply before an undoable transaction. Ordered collections have explicit final-order review with retained rejected drafts. Included trace rows can combine multiple source contributions into one validated model/history transaction; conflicting decisions and incompatible reference mappings remain explicit blockers. Existing Child/Incident attachment fields and artifact lifecycle review are implemented. Artifact creation reserves an explicit counterpart identity and requires all seven metadata decisions; identified source-owner absence can delete a link, while destination-only Take retains it. Owner moves and kept Presence must agree. Latest attachment/artifact native acceptance remains pending. Review does not automatically synchronize arbitrary structure or overwrite the other perspective. Creation scope follows ownership/reference dependencies, not every incident relationship.
- Processes/chains use contributions and explicit sequence links; imported ordered exchange paths retain their implied order until topology conversion. Rich fragments belong to scenarios. Guards, expressions and state behavior text are descriptive; there is no execution engine. Mixed states and modes are permitted by this Studio profile.
- Preserved OA boundary exchanges use Legacy ports. Capability grouping is containment; include, extend and generalization use separate typed relationships in OA and SA. Data/item references remain within their layer and can have explicit transitioned counterparts.
- OA Communication means connect Entities/Actors directly and can allocate Interactions whose actual performers match their endpoints and direction. Transition to SA requires explicit compatible boundary-port decisions; the tool does not guess system ports. Preserved OA boundary exchanges use Legacy ports. Capability grouping is containment; include, extend and generalization use separate typed relationships in OA and SA. Data/item references remain within their layer and can have explicit transitioned counterparts.
- Saved view options preserve semantic records, placements and routes. Work and Participant categories are independent families; selected categories combine by union and explicit empty selections match none. Global behavior coverage and selected process/chain/scenario evidence intersect with category choices. Manual hides remain independent of labels and other filters. Traceability permits both layers' eligible references; ordinary views retain their declared-layer scope. Duplicating a view gives its diagram and placements fresh identities while preserving semantic references and presentation settings.
- Applying a source project preserves authored comments and formatting while assigning missing identities. Graphical updates preserve unaffected source bytes; canonical export is a separate operation. JSON does not preserve comments or source-file organization. See the [source contract](language.rst) for comment ownership and update rules.
- Port position and connection routing belong to each diagram and do not change semantic ownership or endpoints. Folding may temporarily promote an edge to a visible container; expansion restores its authored route. [Routing verification](../harness/release-routing-verification.md) records accepted behavior and measured limits.
- Artifact references retain author-provided URI/revision/fragment values without fetching or executing resources.
@@ -36,8 +37,8 @@ These are concrete design responses, not claims that every Capella user experien
| Concern | Studio response | Remaining tradeoff |
|---|---|---|
| Dense workbench and difficult onboarding | Task workspaces, OA/SA context, contextual menus, direct architecture and behavior gestures, searchable guidance, Home/recents and relation/transition builders | Current Home/recovery and expanded review controls still need native acceptance |
| Noisy architecture pictures | Nested ownership/allocation views, independent placements, collapse, automatic routing, editable bends/labels and port positions | Dense diagrams may need manual adjustment; routing has a bounded solve budget |
| Dense workbench and difficult onboarding | Task workspaces, OA/SA context, contextual menus, direct architecture and behavior gestures, searchable guidance, Home/recents and relation/transition builders | Home/recovery and keyed/main ordered review have current Windows evidence; remaining variants and Linux acceptance are tracked separately |
| Noisy architecture pictures | Nested ownership/allocation views, independent and duplicated placements, saved category/coverage/context filters, explicit hides, collapse, automatic routing, editable bends/labels and port positions | Scoped forty-exchange native filtering/duplication/hide/reopening passed; other view combinations remain pending and routing has a bounded solve budget |
| Hard-to-review model files | Modular typed source, stable aliases/UUIDs, preserved comments/formatting and source-aware history | Semantic merges, completion and an LSP are absent |
| Hidden mutation effects | Validated atomic commands, dependency cleanup, identity maintenance, previewed counterpart changes and undo | No distributed editing or automatic structural reconciliation |
| Platform/plugin overhead | Native Rust/Iced desktop and independent headless service | WGPU has substantial dependencies and needs a working graphics adapter |
@@ -47,11 +48,15 @@ These are concrete design responses, not claims that every Capella user experien
Direct process/scenario/state authoring, typed semantic drift/reconciliation, Home/recents and unsaved-work checkpoints are implemented. Their evidence and outstanding acceptance cases are separated in the [current coverage audit](../harness/release-current-coverage-20260906.md). Direct state editing has earlier scoped Windows/Linux acceptance recorded in [state evidence](../harness/release-state-editing.md); that does not accept every current change.
Required unfinished implementation includes ordinary OA CommunicationMean authoring with an accurate participant-level contract; persisted selective relation/category/coverage views; completeness checks for exchanges on non-leaf work, behavior-context coverage and missions without capabilities; and ordered-collection, attachment, artifact and multi-source semantic-review GUI controls. Existing Legacy OA boundary exchanges and their Interaction allocations remain supported, but do not close the CommunicationMean requirement.
Source-6 CommunicationMean authoring/transition contracts, persisted selective relation/category/coverage views, view duplication and combined multi-source semantic review are implemented and have automated coverage. The source-6 batch recovery and exact Apply/Save/Undo/Redo path, plus scoped forty-exchange filtering/duplication/hide/reopening, now have Windows native evidence. Child/Incident/Artifact semantic-review GUI controls are implemented and have automated coverage; their native acceptance, communication authoring and remaining selective-view cases remain pending. Located completeness warnings for non-leaf exchanges, behavior-context coverage and missing mission/capability context are implemented and verified across core and REST. Explicit ordered review's main native recovery/Apply/Undo/Redo path and reverse Apply/Undo/Redo have exact source comparisons; the reverse trial also exposed a transient save failure on the older binary, and remaining variants are tracked separately.
An earlier 2026-09-06 automated checkpoint accounted for 943 passing tests and one existing ignored benchmark across the full workspace run and complete affected-suite reruns following three compatibility-expectation corrections. This includes the 48-test HTTP suite, including source-6 acceptance/restart and endpoint-capacity rejection cases. OpenAPI validation passes 39 fixtures and checks 197 component schemas. Exact logs and later changes are identified in [current state](../harness/STATE.md); these totals do not claim a single uninterrupted green workspace run or native acceptance. The later full desktop suite passed 518/518, including artifact lifecycle and diagram-inspector tests; the corrected six-artifact rerun and strict all-target workspace Clippy also passed. These are separate later evidence points, not a recomputed whole-workspace total.
The desktop attempts a private checkpoint every 10 seconds while work is unsaved. It retains accepted source, raw source buffers, pending property/behavior forms and supported workflow drafts, including semantic-review input. Home recovery opens a detached unsaved copy requiring Save as; it restores no undo stack and writes neither the original model nor a hosted destination. Interrupted source-save recovery is a separate mechanism for an incomplete save transaction.
Remaining release gates include current-tree automated checks, expanded data/semantic-review and Home/recovery native acceptance, outstanding behavior and hosted workflow cases, default/minimum-window Windows/Linux acceptance, fresh build/MSRV and specification/OpenAPI checks, real REST/restart/parity verification, packages/checksums and independent final review. Guidance must follow the accepted controls. These are unfinished release requirements, not exclusions or release-acceptance claims.
The [current Windows native record](../harness/release-current-native-verification.md) covers Home/recents, raw invalid source and UUID-property crash recovery, pending timed-transition recovery, keyed semantic recovery and retained rejected ordered input. It records exact repair/Save/Undo/Redo source comparisons and default/minimum-window observations for those workflows. The [timed-bundle oracle](../harness/release-timed-bundle-oracle-20260906.md) independently reopens both saved files and checks the complete intended graph delta. These scoped results do not accept every recovery adapter, current source-6 native workflows, final packages or Linux.
Remaining release gates include final-tree strict checks and rebuilt binaries, source-6 communication, remaining selective-view cases and latest attachment/artifact native acceptance, expanded data/semantic-review and remaining recovery variants, outstanding behavior and hosted workflow cases, default/minimum-window Windows/Linux acceptance, fresh MSRV and final specification/OpenAPI checks, remaining real REST/restart/parity scenarios, packages/checksums and independent final review. The Windows journal-publication fix has [bounded independent review and automated evidence](../harness/release-journal-publication-review-20260906.md); its new-binary native Save/reopen check remains pending. Guidance must follow the accepted controls. These are unfinished release requirements, not exclusions or release-acceptance claims.
## Remaining boundaries