Complete source 6 engineering workflows and preserve release validation evidence

docs/api.rst

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