feat(edit): expose connection authoring through ApplyEdits and the clients

api/proto/sysml.proto

@@ -838,6 +838,7 @@ message EditOperation {
     AddMemberEdit add_member = 3;
     DeleteEdit delete = 4;
     MoveEdit move = 5;
+    AddConnectionEdit add_connection = 6;
   }
 }
 
@@ -859,6 +860,23 @@ message AddMemberEdit {
   repeated string specializes = 7;
 }
 
+// AddConnectionEdit inserts a usage whose ends connect two features.
+message AddConnectionEdit {
+  // Namespace FQN receiving the usage; empty means the document root.
+  string owner = 1;
+  // Usage kind: SysML connection, interface, allocation, binding, flow,
+  // succession or transition; KerML connector, binding, flow or succession.
+  string kind = 2;
+  // First feature reference resolved from the owner.
+  string from_end = 3;
+  // Second feature reference resolved from the owner.
+  string to_end = 4;
+  // Optional declared name.
+  string name = 5;
+  // Optional typing target, legal only for typed connection kinds.
+  string type = 6;
+}
+
 // DeleteEdit removes a declaration and its owned trivia.
 message DeleteEdit {
   // Fully qualified name of the declaration to remove.

changes/unreleased/apply-edits-add-connection.added.md

@@ -0,0 +1 @@
+- **Add connection-like usages through `ApplyEdits`.** Python exposes `Editor.add_connection`, `add_allocation` and `add_flow`; Go and Java expose `AddConnection`. The operation requires both the `authoring` and `connection_authoring` capabilities.

client/java/README.md

@@ -57,7 +57,7 @@ verification (`Verification`, `Satisfaction`, `Validation`, each over `Verdict`s
 documents (`DocumentValue`, `DocumentRow`, `DocumentQueryResult`,
 `RenderedDocument`) and `EngineInfo`. `SourceDocument` names a document a
 `parseSources` call reads; `Edit` is sealed over `SetValue`, `Rename`,
-`AddMember`, `Delete` and `Move`. Every RPC the service offers is a method.
+`AddMember`, `AddConnection`, `Delete` and `Move`. Every RPC the service offers is a method.
 No generated protobuf message or builder appears in the public API. A `Diagnostic`
 is `(severity, message, code, span)`; `code()` is the identifier to branch on
 (`"syntax"`, a validation code such as `"unresolved"`, `"choice-point"`,

client/java/opensysml-client/src/main/java/org/openmbee/opensysml/Capabilities.java

@@ -80,6 +80,9 @@ public final class Capabilities {
   /** {@code ApplyEdits} can add members and delete declarations. */
   public static final String AUTHORING = "authoring";
 
+  /** {@code ApplyEdits} can add connection-like usages. */
+  public static final String CONNECTION_AUTHORING = "connection_authoring";
+
   /** {@code ApplyEdits} edits a model of several documents as one batch, answering each edited document by name. */
   public static final String EDIT_DOCUMENTS = "edit_documents";
 

client/java/opensysml-client/src/main/java/org/openmbee/opensysml/Edit.java

@@ -159,6 +159,79 @@ public AddMember withSpecializes(List<String> specializes) {
     }
   }
 
+  /**
+   * Inserts a connection-like usage between two feature references.
+   *
+   * @param owner FQN of the namespace to receive the usage; empty for the document root
+   * @param kind the written connection kind, such as {@code "allocation"} or {@code "flow"}
+   * @param from the first feature reference, written as notation
+   * @param to the second feature reference, written as notation
+   * @param name the declared identifier, when named
+   * @param type a typing target, when written
+   */
+  record AddConnection(
+      String owner,
+      String kind,
+      String from,
+      String to,
+      Optional<String> name,
+      Optional<String> type)
+      implements Edit {
+
+    /**
+     * Creates the edit.
+     *
+     * @param owner receiving namespace, never {@code null}
+     * @param kind connection kind, never {@code null}
+     * @param from first feature reference, never {@code null}
+     * @param to second feature reference, never {@code null}
+     * @param name optional declared identifier
+     * @param type optional typing target
+     */
+    public AddConnection {
+      Objects.requireNonNull(owner, "owner");
+      Objects.requireNonNull(kind, "kind");
+      Objects.requireNonNull(from, "from");
+      Objects.requireNonNull(to, "to");
+      Objects.requireNonNull(name, "name");
+      Objects.requireNonNull(type, "type");
+    }
+
+    /**
+     * Creates an unnamed, untyped connection.
+     *
+     * @param owner receiving namespace, empty for the document root
+     * @param kind connection kind
+     * @param from first feature reference
+     * @param to second feature reference
+     * @return the edit
+     */
+    public static AddConnection of(String owner, String kind, String from, String to) {
+      return new AddConnection(
+          owner, kind, from, to, Optional.empty(), Optional.empty());
+    }
+
+    /**
+     * The same connection with a declared name.
+     *
+     * @param name the identifier
+     * @return the edit carrying it
+     */
+    public AddConnection withName(String name) {
+      return new AddConnection(owner, kind, from, to, Optional.of(name), type);
+    }
+
+    /**
+     * The same connection with a typing target.
+     *
+     * @param type the type target, as notation
+     * @return the edit carrying it
+     */
+    public AddConnection withType(String type) {
+      return new AddConnection(owner, kind, from, to, name, Optional.of(type));
+    }
+  }
+
   /**
    * Removes a declaration and its owned trivia.
    *

client/java/opensysml-client/src/main/java/org/openmbee/opensysml/Model.java

@@ -843,8 +843,9 @@ public Conversion convert(String toFormat, ConversionOptions options) {
    *     says why and its {@link EditException#referrers()} name what references the target
    * @throws ServiceException if the request itself was rejected
    * @throws CapabilityException if the service does not advertise {@code apply_edits}, or an edit
-   *     is an {@link Edit.AddMember}, {@link Edit.Delete} or {@link Edit.Move} and it does not
-   *     advertise {@code authoring}
+   *     is an {@link Edit.AddMember}, {@link Edit.AddConnection}, {@link Edit.Delete} or
+   *     {@link Edit.Move} and it does not advertise {@code authoring}; {@link Edit.AddConnection}
+   *     also requires {@code connection_authoring}
    */
   public EditResult applyEdits(List<Edit> edits) {
     return applyEdits(edits, EditOptions.defaults());
@@ -863,17 +864,31 @@ public EditResult applyEdits(List<Edit> edits) {
    *     document of the model has
    * @throws CapabilityException if the service does not advertise {@code apply_edits}, an edit
    *     writes a declaration and it does not advertise {@code authoring}, or a document is named
-   *     and it does not advertise {@code edit_documents}
+   *     and it does not advertise {@code edit_documents}; {@link Edit.AddConnection} also requires
+   *     {@code connection_authoring}
    */
   public EditResult applyEdits(List<Edit> edits, EditOptions options) {
     Objects.requireNonNull(edits, "edits");
     Objects.requireNonNull(options, NAME_OPTIONS);
     connection.capabilities().require(Capabilities.APPLY_EDITS);
+    boolean requestsAuthoring = false;
+    boolean requestsConnectionAuthoring = false;
     for (Edit edit : edits) {
-      if (edit instanceof Edit.AddMember || edit instanceof Edit.Delete || edit instanceof Edit.Move) {
-        connection.capabilities().require(Capabilities.AUTHORING);
-        break;
+      if (edit instanceof Edit.AddMember
+          || edit instanceof Edit.AddConnection
+          || edit instanceof Edit.Delete
+          || edit instanceof Edit.Move) {
+        requestsAuthoring = true;
       }
+      if (edit instanceof Edit.AddConnection) {
+        requestsConnectionAuthoring = true;
+      }
+    }
+    if (requestsAuthoring) {
+      connection.capabilities().require(Capabilities.AUTHORING);
+    }
+    if (requestsConnectionAuthoring) {
+      connection.capabilities().require(Capabilities.CONNECTION_AUTHORING);
     }
     options.document().ifPresent(document -> connection.capabilities().require(Capabilities.EDIT_DOCUMENTS));
     ApplyEditsRequest.Builder request =

client/java/opensysml-client/src/main/java/org/openmbee/opensysml/internal/Protos.java

@@ -1025,6 +1025,16 @@ public static org.openmbee.opensysml.proto.EditOperation proto(Edit edit) {
       addMember.value().ifPresent(add::setValue);
       add.addAllSpecializes(addMember.specializes());
       builder.setAddMember(add);
+    } else if (edit instanceof Edit.AddConnection addConnection) {
+      org.openmbee.opensysml.proto.AddConnectionEdit.Builder add =
+          org.openmbee.opensysml.proto.AddConnectionEdit.newBuilder()
+              .setOwner(addConnection.owner())
+              .setKind(addConnection.kind())
+              .setFromEnd(addConnection.from())
+              .setToEnd(addConnection.to());
+      addConnection.name().ifPresent(add::setName);
+      addConnection.type().ifPresent(add::setType);
+      builder.setAddConnection(add);
     } else if (edit instanceof Edit.Delete delete) {
       builder.setDelete(
           org.openmbee.opensysml.proto.DeleteEdit.newBuilder()