Compose reviewed attachments and State bends with saved Scenario

2026-09-23 00:48:36 -07:00
parent 0b61771d07
commit a9b9c81eab
55 changed files with 5500 additions and 67 deletions
@@ -2,7 +2,7 @@
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 <head>
 <meta charset="utf-8" />
-<meta name="generator" content="Docutils 0.22.2: https://docutils.sourceforge.io/" />
+<meta name="generator" content="Docutils 0.23: https://docutils.sourceforge.io/" />
 <meta name="viewport" content="width=device-width, initial-scale=1" />
 <title>Arcadia Studio model REST API</title>
 <style type="text/css">
@@ -947,6 +947,33 @@ authored files and revision. JSON/source imports may omit <span class="docutils
 it defaults to <span class="docutils literal">[]</span> and empty lists are omitted on export. The normative
 diagram semantics and source spelling are in <span class="docutils literal">language.rst</span> section 5.</p>
 </section>
+<section id="diagram-connection-attachments">
+<h2>Diagram connection attachments</h2>
+<p><span class="docutils literal">EdgeRoute.source_attachment</span> and <span class="docutils literal">target_attachment</span> are optional
+<span class="docutils literal"><span class="pre">{&quot;side&quot;:&quot;Bottom&quot;,&quot;offset&quot;:0.25}</span></span> records. Side and a finite offset in
+<span class="docutils literal">[0,1]</span> are required within a supplied record; unknown fields are rejected.
+Absence/null means automatic placement. Omitted fields in older schema-3
+models retain that meaning. The normal transaction endpoint accepts:</p>
+<pre class="literal-block">{&quot;commands&quot;:[{&quot;SetEdgeRoute&quot;:{
+  &quot;diagram&quot;:&quot;&lt;diagram UUID&gt;&quot;,
+  &quot;route&quot;:{&quot;edge&quot;:&quot;&lt;relation or trace UUID&gt;&quot;,
+    &quot;source_attachment&quot;:{&quot;side&quot;:&quot;Bottom&quot;,&quot;offset&quot;:0.25},
+    &quot;waypoints&quot;:[],&quot;label&quot;:null}
+}}]}</pre>
+<p><span class="docutils literal">SetEdgeRoute</span> replaces the complete route entry. Clients changing one end
+must retain its other attachment, bends and label; omit/null only the intended
+attachment to restore that end's automatic position. <span class="docutils literal">RemoveEdgeRoute</span> resets
+all presentation for that edge. Both support ETag checking, dry runs, atomic
+validation and source-project writeback. Invalid offsets reject the whole
+transaction without changing files or revision.</p>
+<p>These are per-view presentation preferences, not a semantic reconnect. Fractions
+follow the projected shape, including moves/resizes; semantic reconnect retains
+them as preferences of the same edge-end slots. Real semantic ports take
+precedence, and promoted folded endpoints suspend authored routing. The complete
+boundary mapping, lifecycle and generated-view limitations are normative in
+<span class="docutils literal">language.rst</span> section 5. GET model/source, PUT source, desktop and transactions
+share this representation; no separate attachment endpoint exists.</p>
+</section>
 <section id="contextual-process-and-chain-topology">
 <h2>Contextual process and chain topology</h2>
 <p>Operational processes and system functional chains can combine work
@@ -329,6 +329,37 @@ 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.

+Diagram connection attachments
+-------------------------------
+
+``EdgeRoute.source_attachment`` and ``target_attachment`` are optional
+``{"side":"Bottom","offset":0.25}`` records. Side and a finite offset in
+``[0,1]`` are required within a supplied record; unknown fields are rejected.
+Absence/null means automatic placement. Omitted fields in older schema-3
+models retain that meaning. The normal transaction endpoint accepts::
+
+    {"commands":[{"SetEdgeRoute":{
+      "diagram":"<diagram UUID>",
+      "route":{"edge":"<relation or trace UUID>",
+        "source_attachment":{"side":"Bottom","offset":0.25},
+        "waypoints":[],"label":null}
+    }}]}
+
+``SetEdgeRoute`` replaces the complete route entry. Clients changing one end
+must retain its other attachment, bends and label; omit/null only the intended
+attachment to restore that end's automatic position. ``RemoveEdgeRoute`` resets
+all presentation for that edge. Both support ETag checking, dry runs, atomic
+validation and source-project writeback. Invalid offsets reject the whole
+transaction without changing files or revision.
+
+These are per-view presentation preferences, not a semantic reconnect. Fractions
+follow the projected shape, including moves/resizes; semantic reconnect retains
+them as preferences of the same edge-end slots. Real semantic ports take
+precedence, and promoted folded endpoints suspend authored routing. The complete
+boundary mapping, lifecycle and generated-view limitations are normative in
+``language.rst`` section 5. GET model/source, PUT source, desktop and transactions
+share this representation; no separate attachment endpoint exists.
+
 Contextual process and chain topology
 -------------------------------------

@@ -1785,14 +1785,16 @@ the Reparent command. Moving, resizing, arranging, or folding an owner retains
 its authored sides and fractions. Frozen schema-1/schema-2 readers do not accept
 <span class="docutils literal">port_anchors</span>; their explicit migration supplies an empty list.</p>
 <p>Each <span class="docutils literal">routes</span> entry is an EdgeRoute record with a required <span class="docutils literal">edge</span> reference
-to an existing Relation or Trace, <span class="docutils literal">waypoints</span> (default <span class="docutils literal">[]</span>), and <span class="docutils literal">label</span>
-(default <span class="docutils literal">none</span>). Route records have no separate UUID or alias. An edge occurs
+to an existing Relation or Trace, <span class="docutils literal">waypoints</span> (default <span class="docutils literal">[]</span>), <span class="docutils literal">label</span>
+(default <span class="docutils literal">none</span>), and <span class="docutils literal">source_attachment</span> / <span class="docutils literal">target_attachment</span> (each
+default <span class="docutils literal">none</span>). Route records have no separate UUID or alias. An edge occurs
 at most once in a diagram's route list; different diagrams MAY store independent
 routes for the same edge. List order and explicit empty entries are retained by
 source and JSON round trips, although list order has no routing meaning. Edges
 need not currently be visible in their diagram.</p>
 <pre class="code text literal-block"><code>routes [
    { edge &#64;report_exchange;
+      source_attachment { side Bottom; offset 0.25; };
      waypoints [{ x 420; y 260; }, { x 690; y 260; }];
      label { fraction 0.55; offset { x 0; y -16; }; };
    }
@@ -1809,6 +1811,47 @@ are structural errors. A pinned point that obstructs routing remains stored;
 geometric routing difficulty is reported separately from structural validity.
 Each EdgeRoute counts as one record against <span class="docutils literal">ParseLimits.max_records</span>; pinned
 points are bounded by the per-route limit and aggregate input byte limits.</p>
+<p>An attachment is an EdgeAttachment record with required <span class="docutils literal">side</span> (Left, Right,
+Top, Bottom) and required finite binary32 <span class="docutils literal">offset</span> from zero through one.
+Unknown fields, omitted nested fields and out-of-range offsets are structural
+errors (<span class="docutils literal">invalid_attachment_offset</span> for the latter). Attachments are bounded
+inline values, at most two per route, not additional graph objects or records.
+JSON uses the same field names, enum strings and number values. Omitted or null
+attachments mean automatic positioning; canonical compact source and JSON omit
+absent attachments. Earlier schema-3 input hydrates both fields as absent.</p>
+<p>The end names designate stored source/target slots, even for undirected edges.
+These values MUST NOT change semantic endpoints, ports, ownership, type,
+orientation or identity. Each preference belongs to that edge end in that view:
+another view remains independent. It follows the current endpoint's projected
+boundary under movement, resize or semantic reconnect; reconnect preserves the
+preference, as it preserves authored bends. The fraction does not identify the
+previous semantic endpoint. Deletion/reidentification of the edge follows the
+existing whole-route rules; moving, hiding or replacing its placement retains
+the preference. Removing one attachment restores that end's automatic position
+without changing bends, labels or the opposite attachment.</p>
+<p>For Left/Right, offset gives the Y fraction of the complete projected bounding
+box; for Top/Bottom it gives the X fraction. The attachment intersects the painted
+shape along that cardinal scan line. Rounded cards use radius 10, limited by half
+their width/height; Regions and fork/join bars are rectangles. State circles use
+their ellipse boundary and Choice uses its diamond boundary. More precisely, let
+<span class="docutils literal">t = 2 * offset - 1</span> and <span class="docutils literal">D</span> be width for Left/Right or height for Top/Bottom.
+The inset from the selected bounding side is <span class="docutils literal">D/2 * (1 - <span class="pre">sqrt(1-t*t))</span></span> for an
+ellipse and <span class="docutils literal">D/2 * abs(t)</span> for a diamond. A Terminate X uses the outermost
+painted-stroke intersection, inset <span class="docutils literal">D * min(offset, <span class="pre">1-offset)</span></span>. Zero and one
+are valid; different side/fraction pairs can describe the same painted point.
+Routing leads extend in the selected cardinal direction beyond the bounding box
+before turning. Source/API fractions retain their precision; pointer editing
+snaps fractions to hundredths without changing the stored semantic record.</p>
+<p>An actual semantic Port remains authoritative, including when projection hides
+its port marker. An edge attachment on that end is retained but dormant; use
+the port's own placement anchor to move a port. When folding promotes an endpoint
+to an ancestor, all authored route data is suspended and resumes on expansion.
+Geometric difficulty MUST NOT discard preferences. Coincident authored self-loop
+tips retain their positions with an external loop and a routing warning; the
+editor must offer an explicit way to choose either end even when handles overlap.
+Internal state transitions have no external connection. Process's generated
+topology and Scenario's lifeline/activation/time-derived tips are not consumers
+of these diagram route fields; this feature does not redefine their semantics.</p>
 <p><span class="docutils literal">SetEdgeRoute { diagram, route }</span> upserts an entry by edge identity, retaining
 the order and contents of unrelated entries. <span class="docutils literal">RemoveEdgeRoute { diagram, edge }</span>
 removes it; removing an absent entry is a no-op for an existing diagram and edge.
@@ -1167,8 +1167,9 @@ its authored sides and fractions. Frozen schema-1/schema-2 readers do not accept
 ``port_anchors``; their explicit migration supplies an empty list.

 Each ``routes`` entry is an EdgeRoute record with a required ``edge`` reference
-to an existing Relation or Trace, ``waypoints`` (default ``[]``), and ``label``
-(default ``none``). Route records have no separate UUID or alias. An edge occurs
+to an existing Relation or Trace, ``waypoints`` (default ``[]``), ``label``
+(default ``none``), and ``source_attachment`` / ``target_attachment`` (each
+default ``none``). Route records have no separate UUID or alias. An edge occurs
 at most once in a diagram's route list; different diagrams MAY store independent
 routes for the same edge. List order and explicit empty entries are retained by
 source and JSON round trips, although list order has no routing meaning. Edges
@@ -1178,6 +1179,7 @@ need not currently be visible in their diagram.

    routes [
        { edge @report_exchange;
+          source_attachment { side Bottom; offset 0.25; };
          waypoints [{ x 420; y 260; }, { x 690; y 260; }];
          label { fraction 0.55; offset { x 0; y -16; }; };
        }
@@ -1196,6 +1198,51 @@ geometric routing difficulty is reported separately from structural validity.
 Each EdgeRoute counts as one record against ``ParseLimits.max_records``; pinned
 points are bounded by the per-route limit and aggregate input byte limits.

+An attachment is an EdgeAttachment record with required ``side`` (Left, Right,
+Top, Bottom) and required finite binary32 ``offset`` from zero through one.
+Unknown fields, omitted nested fields and out-of-range offsets are structural
+errors (``invalid_attachment_offset`` for the latter). Attachments are bounded
+inline values, at most two per route, not additional graph objects or records.
+JSON uses the same field names, enum strings and number values. Omitted or null
+attachments mean automatic positioning; canonical compact source and JSON omit
+absent attachments. Earlier schema-3 input hydrates both fields as absent.
+
+The end names designate stored source/target slots, even for undirected edges.
+These values MUST NOT change semantic endpoints, ports, ownership, type,
+orientation or identity. Each preference belongs to that edge end in that view:
+another view remains independent. It follows the current endpoint's projected
+boundary under movement, resize or semantic reconnect; reconnect preserves the
+preference, as it preserves authored bends. The fraction does not identify the
+previous semantic endpoint. Deletion/reidentification of the edge follows the
+existing whole-route rules; moving, hiding or replacing its placement retains
+the preference. Removing one attachment restores that end's automatic position
+without changing bends, labels or the opposite attachment.
+
+For Left/Right, offset gives the Y fraction of the complete projected bounding
+box; for Top/Bottom it gives the X fraction. The attachment intersects the painted
+shape along that cardinal scan line. Rounded cards use radius 10, limited by half
+their width/height; Regions and fork/join bars are rectangles. State circles use
+their ellipse boundary and Choice uses its diamond boundary. More precisely, let
+``t = 2 * offset - 1`` and ``D`` be width for Left/Right or height for Top/Bottom.
+The inset from the selected bounding side is ``D/2 * (1 - sqrt(1-t*t))`` for an
+ellipse and ``D/2 * abs(t)`` for a diamond. A Terminate X uses the outermost
+painted-stroke intersection, inset ``D * min(offset, 1-offset)``. Zero and one
+are valid; different side/fraction pairs can describe the same painted point.
+Routing leads extend in the selected cardinal direction beyond the bounding box
+before turning. Source/API fractions retain their precision; pointer editing
+snaps fractions to hundredths without changing the stored semantic record.
+
+An actual semantic Port remains authoritative, including when projection hides
+its port marker. An edge attachment on that end is retained but dormant; use
+the port's own placement anchor to move a port. When folding promotes an endpoint
+to an ancestor, all authored route data is suspended and resumes on expansion.
+Geometric difficulty MUST NOT discard preferences. Coincident authored self-loop
+tips retain their positions with an external loop and a routing warning; the
+editor must offer an explicit way to choose either end even when handles overlap.
+Internal state transitions have no external connection. Process's generated
+topology and Scenario's lifeline/activation/time-derived tips are not consumers
+of these diagram route fields; this feature does not redefine their semantics.
+
 ``SetEdgeRoute { diagram, route }`` upserts an entry by edge identity, retaining
 the order and contents of unrelated entries. ``RemoveEdgeRoute { diagram, edge }``
 removes it; removing an absent entry is a no-op for an existing diagram and edge.
@@ -2137,15 +2137,59 @@
        ],
        "additionalProperties": false
      },
+      "EdgeAttachment": {
+        "type": "object",
+        "description": "Per-view preference on one stored connection end, not a semantic endpoint. Offset is finite and measured along the complete projected bounding-box side. Real semantic ports take precedence; hidden/promoted geometry retains the preference. Reconnect preserves the preference on its source/target slot.",
+        "properties": {
+          "side": {
+            "$ref": "#/components/schemas/PortAnchorSide"
+          },
+          "offset": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1,
+            "description": "Left/Right: top-to-bottom fraction. Top/Bottom: left-to-right fraction. Shape-aware geometry derives the actual contour point."
+          }
+        },
+        "required": [
+          "side",
+          "offset"
+        ],
+        "additionalProperties": false
+      },
      "EdgeRoute": {
        "type": "object",
-        "description": "One diagram's authored route for an existing Relation or Trace, including currently hidden edges. No separate identity. Only pinned points are stored; explicit empty routes are retained.",
+        "description": "One diagram's authored presentation for an existing Relation or Trace, including currently hidden edges. No separate identity. Stores optional endpoint preferences, pinned points and label placement; explicit empty routes are retained. Removing the route resets all authored presentation.",
        "properties": {
          "edge": {
            "type": "string",
            "format": "uuid",
            "description": "Existing Relation or Trace identity, never a node placement."
          },
+          "source_attachment": {
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/EdgeAttachment"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "Absent or null means automatic. Omitted when serializing automatic presentation. Resetting this field preserves the other end, pins and label."
+          },
+          "target_attachment": {
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/EdgeAttachment"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "Absent or null means automatic. Omitted when serializing automatic presentation. Resetting this field preserves the other end, pins and label."
+          },
          "waypoints": {
            "type": "array",
            "items": {