Specify R6 data contracts and verify coupled REST migration

docs/api.rst

@@ -146,8 +146,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 native JSON. Source import uses the shared language parser
-and its supported migrations. Export uses schema 3 / arcadia 3. Native JSON
+as well as schema-2, schema-3 and current schema-4 JSON. Source import uses the shared language parser
+and its supported migrations. Export uses schema 4 / arcadia 4. 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.
@@ -160,7 +160,7 @@ A source bundle contains ``entry`` and a map of ``files``. For example::
     {
       "entry": "rescue.arcadia",
       "files": {
-        "rescue.arcadia": "arcadia 3; project rescue \"Rescue\" { include \"oa/work.arcadia\"; }\n",
+        "rescue.arcadia": "arcadia 4; project rescue \"Rescue\" { include \"oa/work.arcadia\"; }\n",
         "oa/work.arcadia": "// Engineering rationale\noa_activity assess \"Assess assistance\" {}\n"
       }
     }
@@ -172,8 +172,9 @@ 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. Bundle syntax is source3;
-single-file legacy migration remains available through interchange import.
+the complete bundle, not separately per file. Current bundle syntax is source4; source3 bundles migrate explicitly while
+preserving their files/includes/comments. V1/V2 single-file migration remains
+available through interchange import.
 
 Compilation inserts UUIDs into headers that omit them. Import returns 201 with
 Location/ETag; GET source-project retrieves the stabilized accepted bundle.
@@ -355,8 +356,11 @@ Scenario bodies store an explicit ``viewpoint``. Occurrence Exchange bodies
 store ``message_kind``, optional correlated-call ``reply_to`` and contextual
 ``values``. Message kinds are Asynchronous, Call, Reply, Create, Delete, or
 ``{"Timer":{"expression":"after 5 s"}}``. Each value record contains a
-carried DataField UUID in ``field`` and its textual ``expression``; expressions
-do not change the shared exchange item's type or evaluate server-side.
+carried DataField UUID in ``field``, enclosing field UUID list ``path`` (default
+[]) and textual ``expression``. Identity is (path, field), allowing repeated uses
+of a Record. Operation Call/Reply direction checks use the direct parameter;
+Reference storage stops nested payload traversal. Expressions do not change the
+shared exchange item's type or evaluate server-side.
 
 ``ScenarioUse`` contains a referenced ``scenario`` and one-to-one lifeline
 ``bindings`` records with ``referenced`` and ``local`` UUIDs. The core validates
@@ -370,6 +374,29 @@ exports make those compatibility defaults explicit. This preserves original V2
 models while the release schema is being integrated; it does not silently
 reinterpret old mixed lifelines as a strict new viewpoint.
 
+Data and interface contracts
+----------------------------
+
+Schema4 uses typed bounded DataTypeDefinition and DataValue constructors, field
+storage/defaults/directions, and single specialization. Exact JSON shapes are in
+``openapi.json`` and semantic rules and runnable source in ``language.rst`` section 4.5.
+Interface membership is an identified InterfaceItemAllocation relation with
+independent order/transmission/acquisition. DataAssociation relates Record types
+with named, navigable, multiplicity-bearing ends; it does not add carried fields.
+
+Use ordinary relation queries, transactions and artifact links, for example
+``GET /api/v1/projects/{id}/relations?kind=InterfaceItemAllocation``. The service
+and desktop use the same inheritance/path/default validation. Invalid bounds,
+defaults, directions, cycles or contract-breaking deletions reject atomically,
+preserving the accepted source/model, revision and stored bytes. Correct a related
+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 schema4/source4. Reading an old envelope does not write it or
+advance its ETag. Canonical exports omit transient migration reports.
+
 Validation
 ----------
 
@@ -383,7 +410,7 @@ or::
 
 or::
 
-    {"format":"source-project", "source_project":{"entry":"rescue.arcadia", "files":{"rescue.arcadia":"arcadia 3; project rescue \"Rescue\" {}"}}}
+    {"format":"source-project", "source_project":{"entry":"rescue.arcadia", "files":{"rescue.arcadia":"arcadia 4; 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.