Fix replay guard stale false negatives on reused prebuilt hints

When a prebuilt hint (e.g. Hint = F32[N]) was shared across parameters,
the replay guard stayed armed indefinitely after a cross-arg failure,
blocking subsequent standalone is_bearable() calls with the same object.

Replace the permanent guard with a _fail_replays countdown (2) matching
beartype's error-gen re-invocations (is_valid + get_diagnosis), so the
guard clears after error-gen and standalone validation can proceed.

Author: acecchini

src/shapix/_array_types.py

@@ -64,13 +64,21 @@ class _StructChecker:
   ``Float32Array[N, C]``) and reused across all functions that share it.
   """
 
-  __slots__ = ("_dtype_spec", "_shape_spec", "_repr", "_fail_obj", "_fail_memo")
+  __slots__ = (
+    "_dtype_spec",
+    "_shape_spec",
+    "_repr",
+    "_fail_obj",
+    "_fail_memo",
+    "_fail_replays",
+  )
 
   def __init__(self, dtype_spec: DtypeSpec, shape_spec: tuple[DimSpec, ...]) -> None:
     self._dtype_spec = dtype_spec
     self._shape_spec = shape_spec
     self._fail_obj: object | None = None
     self._fail_memo: object | None = None
+    self._fail_replays: int = 0
 
     # Pre-compute repr for beartype error messages
     dims = ", ".join(repr(d) for d in shape_spec)
@@ -95,6 +103,9 @@ def __call__(self, obj: object) -> bool:
     #   - Different memo WITH prior bindings → fresh @beartype call where
     #     earlier params already bound dims → clear guard and re-validate.
     #   - Different memo, empty → beartype error-gen → replay failure.
+    #     Beartype re-invokes twice per failing param (is_valid + get_diagnosis).
+    #     A countdown (_fail_replays) clears the guard after those 2 replays so
+    #     later standalone is_bearable() with the same object can re-validate.
     #   - Untagged explicit memo (check_context) → always re-validate.
     if self._fail_obj is not None and self._fail_obj is obj:
       if has_untagged_memo():
@@ -113,7 +124,10 @@ def __call__(self, obj: object) -> bool:
           self._fail_memo = None
         else:
           # Different memo, empty = beartype error-gen.  Replay failure.
-          # Stay armed for additional error-gen re-invocations.
+          self._fail_replays -= 1
+          if self._fail_replays <= 0:
+            self._fail_obj = None
+            self._fail_memo = None
           return False
 
     # Dtype check
@@ -136,6 +150,7 @@ def __call__(self, obj: object) -> bool:
       if any(snap):  # prior bindings from other params
         self._fail_obj = obj
         self._fail_memo = memo
+        self._fail_replays = 2
 
     return result
 
@@ -230,6 +245,7 @@ class _ArrayLikeChecker:
     "_repr",
     "_fail_obj",
     "_fail_memo",
+    "_fail_replays",
   )
 
   def __init__(
@@ -247,6 +263,7 @@ def __init__(
     self._asarray = asarray
     self._fail_obj: object | None = None
     self._fail_memo: object | None = None
+    self._fail_replays: int = 0
 
     dims = ", ".join(repr(d) for d in shape_spec)
     self._repr = f"{name}[{dims}]"
@@ -266,6 +283,11 @@ def __call__(self, obj: object) -> bool:
           self._fail_obj = None
           self._fail_memo = None
         else:
+          # Error-gen replay (see _StructChecker comment).
+          self._fail_replays -= 1
+          if self._fail_replays <= 0:
+            self._fail_obj = None
+            self._fail_memo = None
           return False
 
     memo = get_memo(_depth=3)
@@ -279,6 +301,7 @@ def __call__(self, obj: object) -> bool:
       if not result and has_prior:
         self._fail_obj = obj
         self._fail_memo = memo
+        self._fail_replays = 2
       return result
 
     # Slow path: convert scalar / sequence / protocol object to array.
@@ -293,6 +316,7 @@ def __call__(self, obj: object) -> bool:
     if not result and has_prior:
       self._fail_obj = obj
       self._fail_memo = memo
+      self._fail_replays = 2
     return result
 
   def _convert(self, obj: object) -> object | None:

src/shapix/_tree.py

@@ -101,6 +101,7 @@ class _TreeChecker:
     "_repr",
     "_fail_obj",
     "_fail_memo",
+    "_fail_replays",
   )
 
   def __init__(
@@ -115,6 +116,7 @@ def __init__(
     self._get_ops = get_ops
     self._fail_obj: object | None = None
     self._fail_memo: object | None = None
+    self._fail_replays: int = 0
     spec_str = f", {structure_spec}" if structure_spec else ""
     self._repr = f"Tree[{leaf_type!r}{spec_str}]"
 
@@ -135,6 +137,11 @@ def __call__(self, obj: object) -> bool:
           self._fail_obj = None
           self._fail_memo = None
         else:
+          # Error-gen replay (see _StructChecker comment).
+          self._fail_replays -= 1
+          if self._fail_replays <= 0:
+            self._fail_obj = None
+            self._fail_memo = None
           return False
 
     tree_ops = self._get_ops()
@@ -158,6 +165,7 @@ def __call__(self, obj: object) -> bool:
       if any(snap):  # prior bindings from other params
         self._fail_obj = obj
         self._fail_memo = memo
+        self._fail_replays = 2
     else:
       self._fail_obj = None
       self._fail_memo = None

tests/test_decorator.py

@@ -709,3 +709,61 @@ def g(x: Tree[F32[N], T]) -> None:  # type: ignore[valid-type]
       pass
 
     g(y)  # must pass
+
+
+class TestReplayGuardReusedHint:
+  """Prebuilt hint must not poison standalone validation after cross-arg failure."""
+
+  def test_struct_reused_hint_standalone(self) -> None:
+    """is_bearable passes for reused F32[N] hint after cross-arg failure."""
+    from beartype.door import is_bearable
+
+    Hint = F32[N]
+    b = np.ones(3, dtype=np.float32)
+
+    @shapix.check
+    @beartype
+    def pair(a: Hint, b: Hint) -> None:
+      pass
+
+    with pytest.raises(BeartypeCallHintParamViolation):
+      pair(np.ones(4, dtype=np.float32), b)  # b fails: N=4 vs shape (3,)
+
+    assert is_bearable(b, Hint)  # must pass: N unbound, shape (3,) binds N=3
+
+  def test_arraylike_reused_hint_standalone(self) -> None:
+    """is_bearable passes for reused F32Like[N] hint after cross-arg failure."""
+    from beartype.door import is_bearable
+    from shapix.numpy import F32Like
+
+    Hint = F32Like[N]
+    lst = [1.0, 2.0, 3.0]
+
+    @shapix.check
+    @beartype
+    def pair(a: Hint, b: Hint) -> None:
+      pass
+
+    with pytest.raises(BeartypeCallHintParamViolation):
+      pair([1.0, 2.0, 3.0, 4.0], lst)  # lst fails: N=4 vs len 3
+
+    assert is_bearable(lst, Hint)  # must pass
+
+  def test_tree_reused_hint_standalone(self) -> None:
+    """is_bearable passes for reused Tree hint after cross-structure failure."""
+    pytest.importorskip("optree")
+    from beartype.door import is_bearable
+    from shapix.optree import Tree
+
+    Hint = Tree[F32[N], T]  # type: ignore[type-arg]
+    y = [np.ones(3, dtype=np.float32)]
+
+    @shapix.check
+    @beartype
+    def pair(x: Hint, y: Hint) -> None:  # type: ignore[valid-type]
+      pass
+
+    with pytest.raises(BeartypeCallHintParamViolation):
+      pair({"a": np.ones(3, dtype=np.float32)}, y)
+
+    assert is_bearable(y, Hint)  # must pass: T unbound, list structure OK