fix(contracts): preserve bounded producer results

Author: morluto

src/jacobian/math/finite_topology_spaces/_models.py

@@ -56,7 +56,7 @@ class KolmogorovQuotientRequest(StrictModel):
 
 
 class KolmogorovQuotientResult(StrictModel):
-    quotient_points: tuple[OpaqueLabel, ...]
+    quotient_points: tuple[tuple[OpaqueLabel, ...], ...]
     quotient_preorder: tuple[tuple[int, ...], ...]
 
 

src/jacobian/math/finite_topology_spaces/operations.py

@@ -98,7 +98,7 @@ def kolmogorov_quotient(space: FiniteTopologicalSpace) -> dict[str, object]:
         nbhd_to_class.setdefault(key, []).append(i)
     classes = list(nbhd_to_class.values())
     quotient_points = tuple(
-        "|".join(space.points[idx] for idx in sorted(cls)) for cls in classes
+        tuple(space.points[idx] for idx in sorted(cls)) for cls in classes
     )
     class_map: dict[int, int] = {}
     for class_idx, cls in enumerate(classes):

src/jacobian/math/petri_nets/_models.py

@@ -54,8 +54,24 @@ def require_valid_marking_size(self) -> Self:
 class FireTransitionResult(StrictModel):
     """Result of firing a transition."""
 
-    fired: bool
-    new_marking: tuple[int, ...] = Field(default=())
+    status: Literal["FIRED", "NOT_ENABLED", "ESCAPES_DECLARED_ENVELOPE"]
+    new_marking: Marking | None = None
+    envelope_escape: tuple[int, ...] | None = None
+
+    @model_validator(mode="after")
+    def require_consistent_outcome(self) -> Self:
+        if self.status == "ESCAPES_DECLARED_ENVELOPE":
+            if self.new_marking is not None or self.envelope_escape is None:
+                raise ValueError(
+                    "envelope escape must carry only the successor witness"
+                )
+            if any(token < 0 for token in self.envelope_escape):
+                raise ValueError("envelope escape tokens must be nonnegative")
+            if all(token <= MAX_PETRI_MARKING for token in self.envelope_escape):
+                raise ValueError("envelope escape must contain an out-of-range token")
+        elif self.new_marking is None or self.envelope_escape is not None:
+            raise ValueError("ordinary firing outcomes must carry only a marking")
+        return self
 
 
 class IncidenceMatrixRequest(StrictModel):

src/jacobian/math/petri_nets/_operations.py

@@ -20,6 +20,7 @@
     fire_transition,
     reachability_graph,
 )
+from jacobian.math.petri_nets.values import MAX_PETRI_MARKING, Marking
 
 __all__ = [
     "compute_enabled_transitions",
@@ -41,7 +42,15 @@ def compute_fire_transition(request: FireTransitionRequest) -> FireTransitionRes
     success, new_marking = fire_transition(
         request.net, request.marking, request.transition
     )
-    return FireTransitionResult(fired=success, new_marking=new_marking)
+    if any(token > MAX_PETRI_MARKING for token in new_marking):
+        return FireTransitionResult(
+            status="ESCAPES_DECLARED_ENVELOPE",
+            envelope_escape=new_marking,
+        )
+    return FireTransitionResult(
+        status="FIRED" if success else "NOT_ENABLED",
+        new_marking=Marking(tokens=new_marking),
+    )
 
 
 def compute_incidence(request: IncidenceMatrixRequest) -> IncidenceMatrixResult:

src/jacobian/math/petri_nets/_tools.py

@@ -61,9 +61,9 @@ def _op[
     _op(
         "petri_net.fire_transition.compute",
         "Fire one transition in a Petri net",
-        "Fire a single transition at the given marking and return whether it "
-        "succeeded and the resulting marking. If the transition is not "
-        "enabled, it does not fire.",
+        "Fire a single transition at the given marking. Return the canonical "
+        "resulting marking, report that the transition is not enabled, or "
+        "return the exact successor when it leaves the declared envelope.",
         FireTransitionRequest,
         FireTransitionResult,
         compute_fire_transition,

tests/integration/catalog/test_opaque_label_contracts.py

@@ -69,3 +69,20 @@ def test_public_opaque_labels_remain_mathematical_labels(label: str) -> None:
     catalog = Catalog.open()
     for operation_id, payload in _payloads(label):
         invoke_operation(operation_id, payload, catalog)
+
+
+def test_kolmogorov_quotient_retains_long_labels_as_a_class() -> None:
+    left = "a" * 64
+    right = "b" * 64
+    result = invoke_operation(
+        "topology.finite.kolmogorov_quotient.compute",
+        {
+            "space": {
+                "points": [left, right],
+                "preorder": [[0, 1], [0, 1]],
+            }
+        },
+        Catalog.open(),
+    )
+
+    assert result.output["quotient_points"] == [[left, right]]

tests/integration/catalog/test_strict_json_contracts.py

@@ -2,6 +2,7 @@
 
 from jacobian.catalog.catalog import Catalog
 from jacobian.dispatch import invoke_operation
+from jacobian.math.petri_nets.values import MAX_PETRI_ARC_WEIGHT, MAX_PETRI_MARKING
 from jacobian.math.quadratic_forms._models import (
     MAX_ENTRY_DIGITS,
     MAX_VECTOR_DIGITS,
@@ -18,3 +19,26 @@ def test_large_quadratic_integer_result_survives_public_dispatch() -> None:
     )
 
     assert result.output["value"] == str(int(entry) * int(vector) ** 2)
+
+
+def test_petri_firing_reports_successor_outside_marking_envelope() -> None:
+    result = invoke_operation(
+        "petri_net.fire_transition.compute",
+        {
+            "net": {
+                "place_count": 1,
+                "transition_count": 1,
+                "pre": [[0]],
+                "post": [[MAX_PETRI_ARC_WEIGHT]],
+            },
+            "marking": {"tokens": [MAX_PETRI_MARKING]},
+            "transition": 0,
+        },
+        Catalog.open(),
+    )
+
+    assert result.output == {
+        "status": "ESCAPES_DECLARED_ENVELOPE",
+        "new_marking": None,
+        "envelope_escape": [MAX_PETRI_MARKING + MAX_PETRI_ARC_WEIGHT],
+    }

tests/math/finite_topology_spaces/test_finite_topology_spaces.py

@@ -127,6 +127,19 @@ def test_discrete_is_t0(self) -> None:
         )
         assert len(result.quotient_points) == 2
 
+    def test_equivalence_classes_retain_long_source_labels(self) -> None:
+        left = "a" * 64
+        right = "b" * 64
+        space = FiniteTopologicalSpace(
+            points=(left, right),
+            preorder=((0, 1), (0, 1)),
+        )
+
+        result = compute_kolmogorov_quotient(KolmogorovQuotientRequest(space=space))
+
+        assert result.quotient_points == ((left, right),)
+        assert result.quotient_preorder == ((0,),)
+
 
 # ---------------------------------------------------------------------------
 # Continuity check

tests/math/petri_nets/test_petri_nets.py

@@ -121,26 +121,48 @@ def test_fire_success(self):
         result = compute_fire_transition(
             FireTransitionRequest(net=net, marking=marking, transition=0)
         )
-        assert result.fired is True
-        assert result.new_marking == (1, 0)
+        assert result.status == "FIRED"
+        assert result.new_marking == Marking(tokens=(1, 0))
+        assert result.envelope_escape is None
 
     def test_fire_disabled(self):
         net = _simple_net()
         marking = Marking(tokens=(0, 0))
         result = compute_fire_transition(
             FireTransitionRequest(net=net, marking=marking, transition=0)
         )
-        assert result.fired is False
-        assert result.new_marking == (0, 0)
+        assert result.status == "NOT_ENABLED"
+        assert result.new_marking == Marking(tokens=(0, 0))
+        assert result.envelope_escape is None
 
     def test_fire_cyclic(self):
         net = _token_passing_net()
         marking = Marking(tokens=(1, 0))
         result = compute_fire_transition(
             FireTransitionRequest(net=net, marking=marking, transition=0)
         )
-        assert result.fired is True
-        assert result.new_marking == (0, 1)
+        assert result.status == "FIRED"
+        assert result.new_marking == Marking(tokens=(0, 1))
+        assert result.envelope_escape is None
+
+    def test_fire_reports_successor_outside_marking_envelope(self):
+        net = PetriNet(
+            place_count=1,
+            transition_count=1,
+            pre=((0,),),
+            post=((MAX_PETRI_ARC_WEIGHT,),),
+        )
+        result = compute_fire_transition(
+            FireTransitionRequest(
+                net=net,
+                marking=Marking(tokens=(MAX_PETRI_MARKING,)),
+                transition=0,
+            )
+        )
+
+        assert result.status == "ESCAPES_DECLARED_ENVELOPE"
+        assert result.new_marking is None
+        assert result.envelope_escape == (2 * MAX_PETRI_MARKING,)
 
 
 # ---------------------------------------------------------------------------