Add state diagram form and representation contract parity

2026-09-06 02:33:18 +03:00
parent 24595810a1
commit 53cd096a56
7 changed files with 737 additions and 38 deletions
@@ -987,8 +987,9 @@ reinterpret old mixed lifelines as a strict new viewpoint.</p>
 <p>or:</p>
 <pre class="literal-block">{&quot;format&quot;:&quot;source-project&quot;, &quot;source_project&quot;:{&quot;entry&quot;:&quot;rescue.arcadia&quot;, &quot;files&quot;:{&quot;rescue.arcadia&quot;:&quot;arcadia 3; project rescue \&quot;Rescue\&quot; {}&quot;}}}</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. A malformed request envelope or JSON model record
-is a 400. Source diagnostics include one-based line and column according to the
+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.
+Source diagnostics include one-based line and column according to the
 shared language parser. Candidate validation does not replace current state.
 Source-project validation locations refer to the submitted bytes before UUID
 insertion. Successful source-project PUT diagnostics refer to the returned
@@ -1018,6 +1019,35 @@ 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>
 </section>
+<section id="state-diagram-representation">
+<h2>State diagram representation</h2>
+<p><span class="docutils literal">Diagram.projection</span> keeps the existing string values <span class="docutils literal">Overview</span>,
+<span class="docutils literal">Decomposition</span>, <span class="docutils literal">Allocation</span>, <span class="docutils literal">Traceability</span>, <span class="docutils literal">FunctionalDataflow</span> and
+<span class="docutils literal">Capabilities</span>. A dedicated state view instead uses the required payload:</p>
+<pre class="literal-block">{&quot;StateMachine&quot;:{&quot;machine&quot;:&quot;11111111-1111-4111-8111-111111111111&quot;}}</pre>
+<p>The UUID MUST identify an existing StateMachine in the diagram's layer.
+Only that machine, its Regions and its state vertices may be placed, including
+nested members. Empty and partial views are valid. No machine, Region, vertex
+or placement is synthesized by accepting or reading a diagram. Source uses
+<span class="docutils literal">projection { StateMachine { machine &#64;modes; }; };</span> with the same reference.</p>
+<p>Use the ordinary <span class="docutils literal">CreateDiagram</span> or <span class="docutils literal">EditDiagram</span> transaction commands,
+JSON model import/replacement, or source/source-project writes. A bare
+<span class="docutils literal">&quot;StateMachine&quot;</span>, missing or null <span class="docutils literal">machine</span>, malformed UUID, or additional
+payload field is malformed JSON model data (400). A missing, wrong-kind or
+cross-layer machine produces the semantic issue <span class="docutils literal">state_diagram_context</span>;
+an incompatible placement produces <span class="docutils literal">state_diagram_member</span>. These reject
+writes with 422. Transaction rejections use the <span class="docutils literal">command_rejected</span> problem
+code and include the first core failure in <span class="docutils literal">detail</span>; candidate validation
+provides the structured <span class="docutils literal">issues</span> collection.
+Source syntax errors use the source rejection response (422) with locations.
+The validation endpoint returns 200 with <span class="docutils literal">valid:false</span> for a well-formed
+invalid candidate, as described above.</p>
+<p>When changing a diagram's machine or selecting StateMachine for an existing
+diagram, remove or relocate incompatible placements in the same transaction.
+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="cross-layer-transitions">
 <h2>Cross-layer transitions</h2>
 <p>Preview accepts the shared <span class="docutils literal">TransitionRequest</span> record, including direction
@@ -386,8 +386,9 @@ or::
    {"format":"source-project", "source_project":{"entry":"rescue.arcadia", "files":{"rescue.arcadia":"arcadia 3; project rescue \"Rescue\" {}"}}}

 A well-formed validation request returns 200 with ``valid`` and ``issues`` even
-if its candidate is invalid. A malformed request envelope or JSON model record
-is a 400. Source diagnostics include one-based line and column according to the
+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.
+Source diagnostics include one-based line and column according to the
 shared language parser. Candidate validation does not replace current state.
 Source-project validation locations refer to the submitted bytes before UUID
 insertion. Successful source-project PUT diagnostics refer to the returned
@@ -420,6 +421,40 @@ 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.

+State diagram representation
+----------------------------
+
+``Diagram.projection`` keeps the existing string values ``Overview``,
+``Decomposition``, ``Allocation``, ``Traceability``, ``FunctionalDataflow`` and
+``Capabilities``. A dedicated state view instead uses the required payload::
+
+    {"StateMachine":{"machine":"11111111-1111-4111-8111-111111111111"}}
+
+The UUID MUST identify an existing StateMachine in the diagram's layer.
+Only that machine, its Regions and its state vertices may be placed, including
+nested members. Empty and partial views are valid. No machine, Region, vertex
+or placement is synthesized by accepting or reading a diagram. Source uses
+``projection { StateMachine { machine @modes; }; };`` with the same reference.
+
+Use the ordinary ``CreateDiagram`` or ``EditDiagram`` transaction commands,
+JSON model import/replacement, or source/source-project writes. A bare
+``"StateMachine"``, missing or null ``machine``, malformed UUID, or additional
+payload field is malformed JSON model data (400). A missing, wrong-kind or
+cross-layer machine produces the semantic issue ``state_diagram_context``;
+an incompatible placement produces ``state_diagram_member``. These reject
+writes with 422. Transaction rejections use the ``command_rejected`` problem
+code and include the first core failure in ``detail``; candidate validation
+provides the structured ``issues`` collection.
+Source syntax errors use the source rejection response (422) with locations.
+The validation endpoint returns 200 with ``valid:false`` for a well-formed
+invalid candidate, as described above.
+
+When changing a diagram's machine or selecting StateMachine for an existing
+diagram, remove or relocate incompatible placements in the same transaction.
+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.
+
 Cross-layer transitions
 -----------------------

@@ -1285,17 +1285,47 @@ Studio profile; no running history state is persisted or synthesized.</p>
 <h2>5. Diagrams, artifacts, and cross-layer traceability</h2>
 <p><span class="docutils literal">diagram</span> has name, identity, alias, description, <span class="docutils literal">layer</span> (Oa by default),
 <span class="docutils literal">projection</span> (Overview by default), and <span class="docutils literal">routes</span> (empty list by default).
-Other projections are Decomposition,
-Allocation, FunctionalDataflow, Capabilities, and Traceability. Traceability diagrams can show both layers;
-other diagrams show their chosen layer.</p>
+The string projections are Overview, Decomposition, Allocation,
+FunctionalDataflow, Capabilities, and Traceability. StateMachine is a payload
+constructor with one required <span class="docutils literal">machine</span> reference. Traceability diagrams
+can show both layers; other diagrams show their chosen layer.</p>
 <p>Allocation is an architecture view: it shows participants and work, nests
 allocated work under its performer, and displays interactions, functional
 exchanges and boundary exchanges. FunctionalDataflow shows the work hierarchy
 and its exchanges. Capabilities shows participants, roles, missions and
 capabilities with their involvement, exploitation, include, extend and
 generalization links. Decomposition and Overview retain general containment;
-Overview also exposes all relationships. Changing the projection hides
+Overview also exposes all relationships. These string projections hide
 inapplicable placements without deleting them or changing semantic records.</p>
+<p>A StateMachine projection MUST reference an existing StateMachine in the
+diagram's layer. Its placements MUST refer to that machine, its Regions, or
+its state vertices, including nested Regions and vertices. Events, other
+machines and their members, and unrelated semantic elements are not valid
+placements in this view. Empty and partial state views are valid; neither
+creating nor reading a view synthesizes semantic elements or placements.
+Changing an existing diagram to StateMachine, or changing its machine, MUST
+remove or relocate incompatible placements in the same transaction. Context
+errors use <span class="docutils literal">state_diagram_context</span>; incompatible placements use
+<span class="docutils literal">state_diagram_member</span>. Neither case silently hides invalid members.</p>
+<p>This complete source example places one state from an existing machine:</p>
+<pre class="code text literal-block"><code>arcadia 3;
+project operating &quot;Operating modes&quot; {
+    oa_entity crew &quot;Crew&quot; {}
+    oa_state_machine modes &quot;Modes&quot; { parent &#64;crew; }
+    oa_region main &quot;Main region&quot; { parent &#64;modes; }
+    oa_state ready &quot;Ready&quot; { parent &#64;main; }
+    diagram mode_view &quot;Operating modes&quot; {
+        layer Oa;
+        projection { StateMachine { machine &#64;modes; }; };
+    }
+    node ready_view { diagram &#64;mode_view; element &#64;ready; }
+}</code></pre>
+<p>The JSON projection is
+<span class="docutils literal"><span class="pre">{&quot;StateMachine&quot;:{&quot;machine&quot;:&quot;11111111-1111-4111-8111-111111111111&quot;}}</span></span>,
+where the UUID is the referenced machine's identity. A bare <span class="docutils literal">&quot;StateMachine&quot;</span>,
+a missing or null <span class="docutils literal">machine</span>, an invalid UUID, or additional payload fields
+is malformed. Existing projections retain their string representation, for
+example <span class="docutils literal">&quot;Overview&quot;</span> in JSON and <span class="docutils literal">projection Overview;</span> in source.</p>
 <p>Ports are boundary anchors of visible owners, with their existing
 semantic identity. An explicitly placed port is not rendered as a separate
 large node. Functional exchanges use their declared source/target ports;
@@ -1312,8 +1342,8 @@ allocation, or realization. Hiding an element from a diagram must remain
 distinguishable from deleting it from the model.
 Changing a node's diagram preserves the placement identity, alias, coordinates,
 size, collapse state, manual port anchors, and attached artifacts. The destination
-must accept the element's layer and must not already contain another placement
-of that element.</p>
+must accept the element's layer, satisfy StateMachine membership when applicable,
+and must not already contain another placement of that element.</p>
 <p>Each <span class="docutils literal">port_anchors</span> entry is a PortAnchor record with required <span class="docutils literal">port</span>
 reference, <span class="docutils literal">side</span> (Left, Right, Top, or Bottom), and <span class="docutils literal">offset</span> (finite
 binary32 from 0 through 1). It has no separate identity or alias. The port MUST
@@ -625,9 +625,10 @@ Studio profile; no running history state is persisted or synthesized.

 ``diagram`` has name, identity, alias, description, ``layer`` (Oa by default),
 ``projection`` (Overview by default), and ``routes`` (empty list by default).
-Other projections are Decomposition,
-Allocation, FunctionalDataflow, Capabilities, and Traceability. Traceability diagrams can show both layers;
-other diagrams show their chosen layer.
+The string projections are Overview, Decomposition, Allocation,
+FunctionalDataflow, Capabilities, and Traceability. StateMachine is a payload
+constructor with one required ``machine`` reference. Traceability diagrams
+can show both layers; other diagrams show their chosen layer.

 Allocation is an architecture view: it shows participants and work, nests
 allocated work under its performer, and displays interactions, functional
@@ -635,9 +636,44 @@ exchanges and boundary exchanges. FunctionalDataflow shows the work hierarchy
 and its exchanges. Capabilities shows participants, roles, missions and
 capabilities with their involvement, exploitation, include, extend and
 generalization links. Decomposition and Overview retain general containment;
-Overview also exposes all relationships. Changing the projection hides
+Overview also exposes all relationships. These string projections hide
 inapplicable placements without deleting them or changing semantic records.

+A StateMachine projection MUST reference an existing StateMachine in the
+diagram's layer. Its placements MUST refer to that machine, its Regions, or
+its state vertices, including nested Regions and vertices. Events, other
+machines and their members, and unrelated semantic elements are not valid
+placements in this view. Empty and partial state views are valid; neither
+creating nor reading a view synthesizes semantic elements or placements.
+Changing an existing diagram to StateMachine, or changing its machine, MUST
+remove or relocate incompatible placements in the same transaction. Context
+errors use ``state_diagram_context``; incompatible placements use
+``state_diagram_member``. Neither case silently hides invalid members.
+
+This complete source example places one state from an existing machine:
+
+.. code-block:: text
+
+    arcadia 3;
+    project operating "Operating modes" {
+        oa_entity crew "Crew" {}
+        oa_state_machine modes "Modes" { parent @crew; }
+        oa_region main "Main region" { parent @modes; }
+        oa_state ready "Ready" { parent @main; }
+        diagram mode_view "Operating modes" {
+            layer Oa;
+            projection { StateMachine { machine @modes; }; };
+        }
+        node ready_view { diagram @mode_view; element @ready; }
+    }
+
+The JSON projection is
+``{"StateMachine":{"machine":"11111111-1111-4111-8111-111111111111"}}``,
+where the UUID is the referenced machine's identity. A bare ``"StateMachine"``,
+a missing or null ``machine``, an invalid UUID, or additional payload fields
+is malformed. Existing projections retain their string representation, for
+example ``"Overview"`` in JSON and ``projection Overview;`` in source.
+
 Ports are boundary anchors of visible owners, with their existing
 semantic identity. An explicitly placed port is not rendered as a separate
 large node. Functional exchanges use their declared source/target ports;
@@ -655,8 +691,8 @@ allocation, or realization. Hiding an element from a diagram must remain
 distinguishable from deleting it from the model.
 Changing a node's diagram preserves the placement identity, alias, coordinates,
 size, collapse state, manual port anchors, and attached artifacts. The destination
-must accept the element's layer and must not already contain another placement
-of that element.
+must accept the element's layer, satisfy StateMachine membership when applicable,
+and must not already contain another placement of that element.

 Each ``port_anchors`` entry is a PortAnchor record with required ``port``
 reference, ``side`` (Left, Right, Top, or Bottom), and ``offset`` (finite
@@ -3685,6 +3685,53 @@
        ],
        "additionalProperties": false
      },
+      "ProjectionKind": {
+        "description": "Existing projections remain strings. StateMachine carries one required UUID reference to an existing StateMachine in the diagram layer (state_diagram_context). Its placements may contain only that machine and its regions/state vertices, including nested members (state_diagram_member). Empty and partial views are valid. Incompatible placements must be removed or relocated in the same transaction when changing context; accepting or reading a view does not synthesize semantic records or placements.",
+        "oneOf": [
+          {
+            "type": "string",
+            "enum": [
+              "FunctionalDataflow",
+              "Capabilities",
+              "Overview",
+              "Decomposition",
+              "Allocation",
+              "Traceability"
+            ]
+          },
+          {
+            "type": "object",
+            "properties": {
+              "StateMachine": {
+                "type": "object",
+                "properties": {
+                  "machine": {
+                    "type": "string",
+                    "format": "uuid",
+                    "description": "Required identity of the same-layer StateMachine that owns this view's members."
+                  }
+                },
+                "required": [
+                  "machine"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "required": [
+              "StateMachine"
+            ],
+            "additionalProperties": false
+          }
+        ],
+        "examples": [
+          "Overview",
+          {
+            "StateMachine": {
+              "machine": "11111111-1111-4111-8111-111111111111"
+            }
+          }
+        ]
+      },
      "Diagram": {
        "type": "object",
        "properties": {
@@ -3707,15 +3754,7 @@
            "$ref": "#/components/schemas/Layer"
          },
          "projection": {
-            "type": "string",
-            "enum": [
-              "FunctionalDataflow",
-              "Capabilities",
-              "Overview",
-              "Decomposition",
-              "Allocation",
-              "Traceability"
-            ]
+            "$ref": "#/components/schemas/ProjectionKind"
          },
          "nodes": {
            "type": "object",