feat: expose native algebraic provenance

Author: gtfierro

.agents/skills/buildingmotif/references/repair.md

@@ -78,13 +78,16 @@ for w in ctx.witnesses:
     w.validation_reasons  # structured reasons, including path/value/severity
     w.target_shape        # named algebra statement/shape, when available
     w.violation           # full native pyshifty algebraic violation
-    w.violation_alignment # "focus-order" or "unavailable"
+    w.violation_alignment # "stable-id" or "unavailable"
     w.statement_id        # native algebra statement identifier
+    w.constraint_id       # statement-level algebra id shared with the violation
+    w.constraint_kind     # enumerated statement-level algebra operator
+    w.constraint          # complete statement-level algebra constraint
     w.selector            # how the focus was selected for that statement
     w.target              # rendered algebra target
     w.graph               # complete compiled graph for this violation
     w.shapes_graph        # complete algebra/schema graph
-    w.source_constraints  # native sources, when pyshifty exposes them
+    w.source_constraints  # native reason-level algebra constraints
     w.repair_summary      # repair atoms -- edit choices, NOT validation findings
     w.is_blocked          # True -> no data repair possible in scope; do not fight it
     print(w.explain())    # the repair tree, indented
@@ -110,10 +113,22 @@ Keep the two halves distinct: `w.reason()` / `w.validation_reasons` say **what
 failed**, while `w.repair_summary` / `w.explain()` say **what edits could fix it**.
 A class failure may have both a `CountHigh` repair atom (delete the bad edge) and a
 `CountLow` atom (add the missing type); those atoms are alternatives, not count
-violations. `source_constraints`, `failed_shape`, and `failed_component` remain empty
-when pyshifty does not provide native provenance. BuildingMOTIF does not reconstruct
-them from the Turtle encoding or the repair tree; query `ctx.report` explicitly when
-you specifically need the W3C report view.
+violations.
+
+There are three deliberately separate levels of algebraic provenance:
+
+- `w.constraint_id` / `w.constraint` identify the top-level statement constraint
+  shared by the violation and repair witness.
+- Each validation reason has its own `constraint_id`, `constraint_kind`, and
+  `constraint`, identifying the specific nested algebra node that produced the cause.
+- Each repair-summary atom has leaf-level constraint metadata describing the edit
+  alternative that it witnesses.
+
+The validation/repair join uses `(focus, statement_id, constraint_id)`, not ordering.
+`failed_shape` and `failed_component` remain empty unless pyshifty explicitly provides
+those W3C source fields. BuildingMOTIF does not reconstruct them from the Turtle encoding
+or the repair tree; query `ctx.report` explicitly when you specifically need the W3C
+report view.
 
 To present the whole violation horizon grouped by focus node (the notebooks' way of
 reading a real model's report), iterate `ctx.diffset`:

.agents/skills/buildingmotif/references/validation.md

@@ -184,24 +184,34 @@ for w in ctx.witnesses:
     print(w.violation)           # full native algebraic violation
     print(w.violation_alignment) # how it was paired with the repair witness
     print(w.statement_id)        # native algebra statement identifier
+    print(w.constraint_id)       # statement-level algebra id
+    print(w.constraint_kind)     # enumerated top-level algebra operator
+    print(w.constraint)          # complete top-level algebra constraint
     print(w.selector)            # focus selector for that statement
     print(w.target)              # rendered algebra target
     print(w.graph)               # complete compiled data graph
-    print(w.source_constraints)  # native sources, when pyshifty exposes them
+    print(w.source_constraints)  # native reason-level algebra constraints
     print(w.repair_summary)      # structured repair alternatives
     print(w.explain())
     print("blocked?", w.is_blocked)   # True = opaque constraint, no data repair possible
 ```
 
 Use `ctx.algebra` for the complete native `validate_algebra()` result and
-`ctx.violations` for its unmodified violation tuple. These remain authoritative
-even when `w.violation_alignment == "unavailable"` prevents BuildingMOTIF from
-safely joining an independently-computed repair witness to one violation.
+`ctx.violations` for its unmodified violation tuple. BuildingMOTIF joins the
+independently computed validation and repair results by pyshifty's stable
+`(focus, statement_id, constraint_id)` identity, reported as
+`w.violation_alignment == "stable-id"`. `unavailable` means no safe join could
+be made; BuildingMOTIF never falls back to positional correlation.
 
 The algebraic witness is deliberately independent of the shapes graph's Turtle/blank-node
-encoding. `source_constraints`, `failed_shape`, and `failed_component` remain empty when
-pyshifty does not expose native provenance; BuildingMOTIF will not infer them from repair
-atoms. Use `ctx.report` only when you explicitly want the separate W3C report view.
+encoding. `w.constraint` is the statement-level algebra used to synthesize repair.
+Each `w.validation_reasons` entry has its own `.constraint`, `.constraint_id`, and
+`.constraint_kind` identifying the specific, potentially nested algebra node that
+produced that cause. Repair atoms likewise carry leaf-level constraint provenance,
+but it describes the edit alternative and is not substituted for validation provenance.
+`failed_shape` and `failed_component` remain empty unless pyshifty explicitly preserves
+those W3C fields; BuildingMOTIF will not infer them from repair atoms. Use `ctx.report`
+only when you explicitly want the separate W3C report view.
 
 `w.is_blocked` matters even for read-only validation: a blocked witness (opaque SPARQL,
 identity, coinductive back-edge) means the failure is real but *no data edit can discharge

buildingmotif/dataclasses/algebraic_validation.py

@@ -34,7 +34,6 @@
 from itertools import product
 from typing import (
     TYPE_CHECKING,
-    Any,
     Dict,
     List,
     Optional,
@@ -128,6 +127,26 @@ def statement(self) -> int:
         """pyshifty's identifier for the failed algebra statement."""
         ...
 
+    @property
+    def statement_id(self) -> int:
+        """Stable statement id shared with algebraic violations."""
+        ...
+
+    @property
+    def constraint_id(self) -> int:
+        """Stable top-level constraint id shared with algebraic violations."""
+        ...
+
+    @property
+    def constraint_kind(self) -> object:
+        """The top-level algebraic constraint discriminant."""
+        ...
+
+    @property
+    def constraint(self) -> object:
+        """The complete top-level algebraic constraint."""
+        ...
+
     @property
     def selector(self) -> object:
         """How the focus was selected for the failed statement."""
@@ -156,6 +175,16 @@ def shape_name(self) -> object:
         """The named shape/statement, when pyshifty has one."""
         ...
 
+    @property
+    def statement_id(self) -> int:
+        """Stable statement id shared with the repair witness."""
+        ...
+
+    @property
+    def constraint_id(self) -> int:
+        """Stable top-level constraint id shared with the repair witness."""
+        ...
+
     @property
     def reasons(self) -> Sequence[object]:
         """Structured validation reasons for this violation."""
@@ -326,13 +355,33 @@ def __getattr__(self, name):
 
     @property
     def source_constraint(self) -> Optional[object]:
-        """Native algebraic source constraint, when pyshifty provides one.
+        """The native algebraic constraint that produced this reason.
 
-        pyshifty 0.2.7 does not expose this field. Returning ``None`` is
-        intentional: BuildingMOTIF does not reconstruct a source constraint
-        from the serialized shapes graph or from repair atoms.
+        This is algebraic provenance, not a W3C SHACL source component.
         """
-        return getattr(self.raw, "source_constraint", None)
+        return getattr(self.raw, "constraint", None)
+
+    @property
+    def constraint(self) -> Optional[object]:
+        """The complete native algebra node that produced this reason."""
+        return self.source_constraint
+
+    @property
+    def statement_id(self) -> Optional[int]:
+        """The enclosing top-level statement's stable id."""
+        value = getattr(self.raw, "statement_id", None)
+        return value if isinstance(value, int) else None
+
+    @property
+    def constraint_id(self) -> Optional[int]:
+        """The specific, potentially nested algebra node's stable id."""
+        value = getattr(self.raw, "constraint_id", None)
+        return value if isinstance(value, int) else None
+
+    @property
+    def constraint_kind(self) -> Optional[object]:
+        """The specific algebra node's enumerated semantic kind."""
+        return getattr(self.raw, "constraint_kind", None)
 
     def reason(self) -> str:
         diagnostic = getattr(self.raw, "sparql_diagnostic", None)
@@ -546,6 +595,8 @@ class RepairWitness:
     # pass. It is the source of validation reasons; witness.summary() remains
     # repair information and is deliberately kept separate.
     violation: Optional["AlgebraicViolation"] = None
+    # "stable-id" for the native (focus, statement_id, constraint_id) join.
+    alignment: str = "unavailable"
 
     @cached_property
     def repair_summary(self) -> Tuple:
@@ -600,10 +651,26 @@ def target_shape(self) -> Optional[Node]:
 
     @property
     def statement_id(self) -> Optional[int]:
-        """pyshifty's identifier for the failed algebra statement."""
-        statement = getattr(self.witness, "statement", None)
+        """The failed statement's stable native identifier."""
+        statement = getattr(self.witness, "statement_id", None)
         return statement if isinstance(statement, int) else None
 
+    @property
+    def constraint_id(self) -> Optional[int]:
+        """The top-level algebraic constraint id shared with the violation."""
+        value = getattr(self.witness, "constraint_id", None)
+        return value if isinstance(value, int) else None
+
+    @property
+    def constraint_kind(self) -> Optional[object]:
+        """The top-level algebraic constraint's enumerated semantic kind."""
+        return getattr(self.witness, "constraint_kind", None)
+
+    @property
+    def constraint(self) -> Optional[object]:
+        """The complete top-level algebraic constraint for this witness."""
+        return getattr(self.witness, "constraint", None)
+
     @property
     def selector(self) -> Optional[object]:
         """The native algebra selector describing how the focus was chosen."""
@@ -623,9 +690,10 @@ def target(self) -> Optional[object]:
             return None
 
     @property
-    def statement(self) -> Optional[object]:
-        """Alias for :attr:`target`, retained as the human-facing statement."""
-        return self.target
+    def statement(self) -> Optional[int]:
+        """The failed statement index, matching pyshifty's native surface."""
+        value = getattr(self.witness, "statement", self.statement_id)
+        return value if isinstance(value, int) else self.statement_id
 
     @property
     def graph(self) -> Graph:
@@ -664,12 +732,12 @@ def failed_component(self) -> Optional[URIRef]:
     def violation_alignment(self) -> str:
         """How the repair witness was correlated with its validation result.
 
-        pyshifty currently computes ``RepairSession.witnesses()`` and
-        ``validate_algebra().violations`` independently and exposes no shared
-        statement key. BuildingMOTIF correlates them by focus-local order only
-        when both APIs return the same number of failures for that focus.
+        pyshifty 0.2.8+ exposes a stable
+        ``(focus, statement_id, constraint_id)`` key on both independently
+        computed results. ``unavailable`` means that key was absent,
+        non-unique, or did not match.
         """
-        return "focus-order" if self.violation is not None else "unavailable"
+        return self.alignment
 
     @property
     def failed_shape(self) -> Optional[Node]:
@@ -1535,60 +1603,59 @@ def report(self) -> Graph:
             )
         return report_graph
 
+    @staticmethod
+    def _correlation_key(item: object, focus_attr: str) -> Optional[Tuple]:
+        """Return pyshifty's stable validation/repair join key, if available."""
+        focus = _focus_to_node(getattr(item, focus_attr, None))
+        statement_id = getattr(item, "statement_id", None)
+        constraint_id = getattr(item, "constraint_id", None)
+        if statement_id is None or constraint_id is None:
+            return None
+        try:
+            hash((focus, statement_id, constraint_id))
+        except TypeError:
+            return None
+        return (focus, statement_id, constraint_id)
+
     @cached_property
-    def _violations_by_focus(self) -> Dict[Optional[URIRef], List[Any]]:
-        """``self._algebra.violations``, grouped by focus and kept in the
-        engine's own per-focus order -- used by :meth:`_reasons_for` to align
-        with :meth:`_session.witnesses`, which pyshifty computes independently
-        (a second pass over the same shapes/data)."""
-        grouped: Dict[Optional[URIRef], List[Any]] = defaultdict(list)
-        for v in self._algebra.violations:
-            grouped[_focus_to_node(v.focus_node)].append(v)
+    def _violations_by_key(self) -> Dict[Tuple, List[AlgebraicViolation]]:
+        """Native violations indexed by their stable algebraic identity."""
+        grouped: Dict[Tuple, List[AlgebraicViolation]] = defaultdict(list)
+        for violation in self.violations:
+            key = self._correlation_key(violation, "focus_node")
+            if key is not None:
+                grouped[key].append(violation)
         return dict(grouped)
 
     def _violation_for(
-        self, focus: Optional[URIRef], index: int
-    ) -> Optional[AlgebraicViolation]:
-        """Best-effort pyshifty ``Violation`` for the ``index``-th
-        ``FocusWitness`` pyshifty returned for ``focus`` (in
-        ``RepairSession.witnesses()`` order).
-
-        Neither pyshifty API documents an explicit key to join a
-        ``FocusWitness`` to its ``Violation`` -- both are independent
-        evaluations of the same compiled shapes over the same data, in the
-        engine's own constraint-declaration order. Their repair-summary atoms
-        and validation reasons are *not* expected to align 1:1.
+        self,
+        witness: FocusWitness,
+    ) -> Tuple[Optional[AlgebraicViolation], str]:
+        """Pair a repair witness with its validation violation.
+
+        The independently computed APIs are joined only by their shared native
+        algebraic identity. A missing, unmatched, or non-unique key is never
+        silently downgraded to positional correlation.
         """
-        violations = self._violations_by_focus.get(focus, [])
-        if index >= len(violations):
-            return None
-        return violations[index]  # type: ignore[no-any-return]
+        key = self._correlation_key(witness, "focus")
+        if key is not None:
+            matches = self._violations_by_key.get(key, [])
+            if len(matches) == 1:
+                return matches[0], "stable-id"
+        return None, "unavailable"
 
     @cached_property
     def witnesses(self) -> List[RepairWitness]:
         """The violation horizon: one :class:`RepairWitness` per failing
         ``(focus, statement)``. Empty iff the graph conforms."""
         out: List[RepairWitness] = []
         raw_witnesses = self._session.witnesses()
-        witness_counts: Dict[Optional[URIRef], int] = defaultdict(int)
-        for witness in raw_witnesses:
-            witness_counts[_focus_to_node(witness.focus)] += 1
-        seen_at_focus: Dict[Optional[URIRef], int] = defaultdict(int)
         for w in raw_witnesses:
             focus = _focus_to_node(w.focus)
-            index = seen_at_focus[focus]
-            seen_at_focus[focus] += 1
-            violations = self._violations_by_focus.get(focus, [])
-            # Positional correlation is only defensible when the two
-            # independently-computed APIs agree on the number of statements at
-            # this focus. If they disagree, preserve the repair witness but
-            # leave its validation provenance unknown.
-            violation = (
-                self._violation_for(focus, index)
-                if len(violations) == witness_counts[focus]
-                else None
+            violation, alignment = self._violation_for(w)
+            out.append(
+                RepairWitness(focus, w, self, violation, alignment)  # type: ignore
             )
-            out.append(RepairWitness(focus, w, self, violation))  # type: ignore
         return out
 
     def witnesses_by_focus(self) -> Dict[Optional[URIRef], List[RepairWitness]]:

pyproject.toml

@@ -30,9 +30,9 @@ dependencies = [
     "pyshacl>=0.30,<0.31",
     # pyshifty (imported as ``shifty``) is a required dependency: the ``shifty``
     # SHACL engine and the algebraic validation/repair path are always available.
-    # Pinned to the 0.2.x line -- the algebra/repair API is not yet stable across
+    # Pinned to the 0.3.x line -- the algebra/repair API is not yet stable across
     # minor releases.
-    "pyshifty>=0.2,<0.3",
+    "pyshifty>=0.3,<0.4",
     "alembic>=1.8.0,<2",
     "Flask>=2.1.2,<3",
     "Flask-API>=3.0.post1,<4",