feat(edit): author state transitions, sub-states and behavior parameters

api/proto/sysml.proto

@@ -844,6 +844,7 @@ message EditOperation {
     AddConnectionEdit add_connection = 6;
     AddSatisfyEdit add_satisfy = 7;
     AddRequirementConstraintEdit add_requirement_constraint = 8;
+    AddTransitionEdit add_transition = 9;
   }
 }
 
@@ -873,9 +874,9 @@ message AddMemberEdit {
   string direction = 11;
 }
 
-// AddSatisfyEdit inserts a satisfy usage into a body that admits behavior usages.
+// AddSatisfyEdit inserts a satisfy usage into any package or body that admits behavior usages.
 message AddSatisfyEdit {
-  // Namespace FQN receiving the usage.
+  // Body receiving the usage.
   string owner = 1;
   // Requirement feature reference.
   string requirement = 2;
@@ -899,6 +900,26 @@ message AddRequirementConstraintEdit {
   string name = 4;
 }
 
+// AddTransitionEdit inserts a transition usage, or an entry transition, into a state body.
+message AddTransitionEdit {
+  // State body receiving the transition.
+  string owner = 1;
+  // Optional transition name.
+  string name = 2;
+  // Source feature reference; empty only for an entry transition.
+  string source = 3;
+  // Target feature reference.
+  string target = 4;
+  // Optional text after `accept`.
+  string trigger = 5;
+  // Optional boolean expression after `if`.
+  string guard = 6;
+  // Optional effect text after `do`.
+  string effect = 7;
+  // Write `entry; then <target>;` instead of a regular transition.
+  bool initial = 8;
+}
+
 // AddConnectionEdit inserts a usage whose ends connect two features.
 message AddConnectionEdit {
   // Namespace FQN receiving the usage; empty means the document root.

changes/unreleased/authoring-transitions.added.md

@@ -0,0 +1 @@
+- **Source-preserving authoring now supports state transitions and behavior parameters.** Add regular or entry transitions with at most one `accept`, `if` and `do` clause in grammar order, and create calculations or actions with their parameters in one edit batch. A calculation return expression requires a return type.

client/java/README.md

@@ -395,9 +395,11 @@ and `SuiteTest.aCorruptedAnswerIsCaught` asserts each corruption is caught:
 | `rewrite-strings` | replaces each string            |                  70 |
 
 `Edit.AddMember` exposes `withAbstract`, `withRedefines`, `withDefault` and
-`withDirection`; `Edit.AddSatisfy` and `Edit.AddRequirementConstraint` expose
-requirement authoring. The client checks `member_modifiers`, `satisfy_authoring`
-or `requirement_constraint_authoring` before sending those additions.
+`withDirection`; `Edit.AddSatisfy`, `Edit.AddRequirementConstraint` and
+`Edit.AddTransition` expose requirement and state-transition authoring.
+`Edit.AddTransition.entry` constructs an entry transition. The client checks
+`member_modifiers`, `satisfy_authoring`, `requirement_constraint_authoring` or
+`transition_authoring` before sending those additions.
 
 ## Running the tests
 

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

@@ -92,6 +92,9 @@ public final class Capabilities {
   /** {@code ApplyEdits} accepts additional member modifiers and kinds. */
   public static final String MEMBER_MODIFIERS = "member_modifiers";
 
+  /** {@code ApplyEdits} can add transitions to state bodies. */
+  public static final String TRANSITION_AUTHORING = "transition_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

@@ -264,6 +264,57 @@ public AddRequirementConstraint withName(String name) {
     }
   }
 
+  /** Inserts a transition or entry transition into a state body. */
+  record AddTransition(
+      String owner,
+      Optional<String> name,
+      Optional<String> source,
+      String target,
+      Optional<String> trigger,
+      Optional<String> guard,
+      Optional<String> effect,
+      boolean initial)
+      implements Edit {
+
+    public AddTransition {
+      Objects.requireNonNull(owner, "owner");
+      Objects.requireNonNull(name, "name");
+      Objects.requireNonNull(source, "source");
+      Objects.requireNonNull(target, "target");
+      Objects.requireNonNull(trigger, "trigger");
+      Objects.requireNonNull(guard, "guard");
+      Objects.requireNonNull(effect, "effect");
+    }
+
+    public static AddTransition of(String owner, String source, String target) {
+      return new AddTransition(
+          owner, Optional.empty(), Optional.of(source), target,
+          Optional.empty(), Optional.empty(), Optional.empty(), false);
+    }
+
+    public static AddTransition entry(String owner, String target) {
+      return new AddTransition(
+          owner, Optional.empty(), Optional.empty(), target,
+          Optional.empty(), Optional.empty(), Optional.empty(), true);
+    }
+
+    public AddTransition withName(String name) {
+      return new AddTransition(owner, Optional.of(name), source, target, trigger, guard, effect, initial);
+    }
+
+    public AddTransition withTrigger(String trigger) {
+      return new AddTransition(owner, name, source, target, Optional.of(trigger), guard, effect, initial);
+    }
+
+    public AddTransition withGuard(String guard) {
+      return new AddTransition(owner, name, source, target, trigger, Optional.of(guard), effect, initial);
+    }
+
+    public AddTransition withEffect(String effect) {
+      return new AddTransition(owner, name, source, target, trigger, guard, Optional.of(effect), initial);
+    }
+  }
+
   /**
    * Inserts a connection-like usage between two feature references.
    *

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

@@ -879,11 +879,13 @@ public EditResult applyEdits(List<Edit> edits, EditOptions options) {
     boolean requestsMemberModifiers = false;
     boolean requestsSatisfyAuthoring = false;
     boolean requestsRequirementConstraintAuthoring = false;
+    boolean requestsTransitionAuthoring = false;
     for (Edit edit : edits) {
       if (edit instanceof Edit.AddMember
           || edit instanceof Edit.AddConnection
           || edit instanceof Edit.AddSatisfy
           || edit instanceof Edit.AddRequirementConstraint
+          || edit instanceof Edit.AddTransition
           || edit instanceof Edit.Delete
           || edit instanceof Edit.Move) {
         requestsAuthoring = true;
@@ -906,6 +908,9 @@ public EditResult applyEdits(List<Edit> edits, EditOptions options) {
       if (edit instanceof Edit.AddRequirementConstraint) {
         requestsRequirementConstraintAuthoring = true;
       }
+      if (edit instanceof Edit.AddTransition) {
+        requestsTransitionAuthoring = true;
+      }
     }
     if (requestsAuthoring) {
       connection.capabilities().require(Capabilities.AUTHORING);
@@ -922,6 +927,9 @@ public EditResult applyEdits(List<Edit> edits, EditOptions options) {
     if (requestsRequirementConstraintAuthoring) {
       connection.capabilities().require(Capabilities.REQUIREMENT_CONSTRAINT_AUTHORING);
     }
+    if (requestsTransitionAuthoring) {
+      connection.capabilities().require(Capabilities.TRANSITION_AUTHORING);
+    }
     options.document().ifPresent(document -> connection.capabilities().require(Capabilities.EDIT_DOCUMENTS));
     ApplyEditsRequest.Builder request =
         ApplyEditsRequest.newBuilder()

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

@@ -1046,6 +1046,18 @@ public static org.openmbee.opensysml.proto.EditOperation proto(Edit edit) {
               .setExpression(addConstraint.expression());
       addConstraint.name().ifPresent(add::setName);
       builder.setAddRequirementConstraint(add);
+    } else if (edit instanceof Edit.AddTransition addTransition) {
+      org.openmbee.opensysml.proto.AddTransitionEdit.Builder add =
+          org.openmbee.opensysml.proto.AddTransitionEdit.newBuilder()
+              .setOwner(addTransition.owner())
+              .setTarget(addTransition.target())
+              .setInitial(addTransition.initial());
+      addTransition.name().ifPresent(add::setName);
+      addTransition.source().ifPresent(add::setSource);
+      addTransition.trigger().ifPresent(add::setTrigger);
+      addTransition.guard().ifPresent(add::setGuard);
+      addTransition.effect().ifPresent(add::setEffect);
+      builder.setAddTransition(add);
     } else if (edit instanceof Edit.AddConnection addConnection) {
       org.openmbee.opensysml.proto.AddConnectionEdit.Builder add =
           org.openmbee.opensysml.proto.AddConnectionEdit.newBuilder()