Add direct diagram connections, movable ports, and contextual authoring

docs/api.rst

@@ -136,8 +136,8 @@ Compressed or encoded request bodies and browser Origin requests are
 not supported.
 
 Model admission permits at most 5,000 elements plus relations, 20,000 total
-persistent records (including the project, views and placements), and 50,000
-ordered step references. Source declaration counts and decoded JSON record
+persistent records (including the project, views, placements, routes and manual
+port anchors), and 50,000 ordered step references. Source declaration counts and decoded JSON record
 counts are checked before structural validation. Legacy import counts the
 occurrences and placements migration will generate before validating or
 migrating that model. Exceeding these budgets returns ``422 model_limit``;
@@ -291,6 +291,34 @@ nor reserves IDs. A committed response omits the proposed model and source
 project. Commit must check the revision again. A no-op is successful with
 ``changed: false`` and the original ETag.
 
+Diagram port positions
+----------------------
+
+``NodePlacement.port_anchors`` is an optional list of
+``{"port":"<port UUID>","side":"Top","offset":0.25}`` records. Side is
+Left, Right, Top, or Bottom; offset is a finite fraction from 0 through 1,
+measured from top on vertical edges and from left on horizontal edges.
+The port must be a direct child of the placement's semantic element and occur
+at most once in its anchor list. Placement is presentation state; it changes
+neither semantic ownership nor port direction. Other diagrams are independent.
+
+The existing transaction endpoint accepts::
+
+    {"commands":[{"SetPortAnchor":{
+      "diagram":"<diagram UUID>","node":"<placement UUID>",
+      "anchor":{"port":"<port UUID>","side":"Top","offset":0.25}
+    }}]}
+
+``SetPortAnchor`` upserts by port UUID. ``RemovePortAnchor`` takes
+``{diagram,node,port}`` and restores automatic positioning. Repeating a reset
+is a no-op only while the referenced port still belongs to that placement's
+element; missing or stale owners are rejected. Remove old anchors before
+reparenting in the same atomic batch. Both commands support ordinary dry run,
+ETag checks and source-project writeback. Rejected batches preserve the model,
+authored files and revision. JSON/source imports may omit ``port_anchors``;
+it defaults to ``[]`` and empty lists are omitted on export. The normative
+diagram semantics and source spelling are in ``language.rst`` section 5.
+
 Contextual process and chain topology
 -------------------------------------