Add state diagram form and representation contract parity

docs/api.rst

@@ -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
 -----------------------