refactor: improve propagation traceability

4 files changed, 76 insertions, 18 deletions

diff --git a/subprojects/store-dse/src/main/java/tools/refinery/store/dse/propagation/PropagationRejectedResult.java b/subprojects/store-dse/src/main/java/tools/refinery/store/dse/propagation/PropagationRejectedResult.java
new file mode 100644
index 00000000..6d696de7
--- /dev/null
+++ b/subprojects/store-dse/src/main/java/tools/refinery/store/dse/propagation/PropagationRejectedResult.java
@@ -0,0 +1,32 @@
+/*
+ * SPDX-FileCopyrightText: 2024 The Refinery Authors <https://refinery.tools/>
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package tools.refinery.store.dse.propagation;
+
+public record PropagationRejectedResult(Object reason, String message) implements PropagationResult {
+        @Override
+        public PropagationResult andThen(PropagationResult next) {
+                return this;
+        }
+
+        @Override
+        public boolean isRejected() {
+                return true;
+        }
+
+        @Override
+        public void throwIfRejected() {
+                throw new IllegalArgumentException(formatMessage());
+        }
+
+        public String formatMessage() {
+                return "Propagation failed: %s".formatted(message);
+        }
+
+        @Override
+        public boolean isChanged() {
+                return false;
+        }
+}
diff --git a/subprojects/store-dse/src/main/java/tools/refinery/store/dse/propagation/PropagationResult.java b/subprojects/store-dse/src/main/java/tools/refinery/store/dse/propagation/PropagationResult.java
index ea56653a..e07e443b 100644
--- a/subprojects/store-dse/src/main/java/tools/refinery/store/dse/propagation/PropagationResult.java
+++ b/subprojects/store-dse/src/main/java/tools/refinery/store/dse/propagation/PropagationResult.java
@@ -5,24 +5,15 @@
  */
 package tools.refinery.store.dse.propagation;
 
-public enum PropagationResult {
-        UNCHANGED,
-        PROPAGATED,
-        REJECTED;
+public sealed interface PropagationResult permits PropagationSuccessResult, PropagationRejectedResult {
+        PropagationResult UNCHANGED = PropagationSuccessResult.UNCHANGED;
+        PropagationResult PROPAGATED = PropagationSuccessResult.PROPAGATED;
 
-        public PropagationResult andThen(PropagationResult next) {
-                return switch (this) {
-                        case UNCHANGED -> next;
-                        case PROPAGATED -> next == REJECTED ? REJECTED : PROPAGATED;
-                        case REJECTED -> REJECTED;
-                };
-        }
+        PropagationResult andThen(PropagationResult next);
 
-        public boolean isRejected() {
-                return this == REJECTED;
-        }
+        boolean isRejected();
 
-        public boolean isChanged() {
-                return this == PROPAGATED;
-        }
+        void throwIfRejected();
+
+        boolean isChanged();
 }
diff --git a/subprojects/store-dse/src/main/java/tools/refinery/store/dse/propagation/PropagationSuccessResult.java b/subprojects/store-dse/src/main/java/tools/refinery/store/dse/propagation/PropagationSuccessResult.java
new file mode 100644
index 00000000..22117772
--- /dev/null
+++ b/subprojects/store-dse/src/main/java/tools/refinery/store/dse/propagation/PropagationSuccessResult.java
@@ -0,0 +1,34 @@
+/*
+ * SPDX-FileCopyrightText: 2024 The Refinery Authors <https://refinery.tools/>
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package tools.refinery.store.dse.propagation;
+
+public enum PropagationSuccessResult implements PropagationResult {
+        UNCHANGED,
+        PROPAGATED;
+
+        @Override
+        public PropagationResult andThen(PropagationResult next) {
+                return switch (this) {
+                        case UNCHANGED -> next;
+                        case PROPAGATED -> next instanceof PropagationRejectedResult ? next : PROPAGATED;
+                };
+        }
+
+        @Override
+        public boolean isRejected() {
+                return false;
+        }
+
+        @Override
+        public void throwIfRejected() {
+                // Nothing to throw.
+        }
+
+        @Override
+        public boolean isChanged() {
+                return this == PROPAGATED;
+        }
+}
diff --git a/subprojects/store-dse/src/main/java/tools/refinery/store/dse/propagation/impl/rule/BoundPropagationRule.java b/subprojects/store-dse/src/main/java/tools/refinery/store/dse/propagation/impl/rule/BoundPropagationRule.java
index 5f69b7a2..f91882be 100644
--- a/subprojects/store-dse/src/main/java/tools/refinery/store/dse/propagation/impl/rule/BoundPropagationRule.java
+++ b/subprojects/store-dse/src/main/java/tools/refinery/store/dse/propagation/impl/rule/BoundPropagationRule.java
@@ -5,6 +5,7 @@
  */
 package tools.refinery.store.dse.propagation.impl.rule;
 
+import tools.refinery.store.dse.propagation.PropagationRejectedResult;
 import tools.refinery.store.dse.propagation.PropagationResult;
 import tools.refinery.store.dse.transition.Rule;
 import tools.refinery.store.dse.transition.actions.BoundAction;
@@ -54,7 +55,7 @@ class BoundPropagationRule {
                         var tuple = cursor.getKey();
                         var result = action.fire(tuple);
                         if (!result) {
-                                return PropagationResult.REJECTED;
+                                return new PropagationRejectedResult(rule, "Propagation rule '%s' failed.".formatted(rule.getName()));
                         }
                         firedActivations.add(tuple);
                 }