Define engine-to-integrator error contract

src/vre/__init__.py

@@ -19,7 +19,17 @@
 
 from vre.core.graph import PrimitiveRepository
 from vre.core.grounding import ConceptResolver, GroundingEngine, GroundingResult
-from vre.core.models import CyclicRelationshipError, DepthLevel, Provenance, ProvenanceSource
+from vre.core.errors import (
+    CandidateValidationError,
+    CyclicRelationshipError,
+    GraphError,
+    GraphIntegrityError,
+    HydrationError,
+    PersistenceError,
+    ResolutionError,
+    VREError,
+)
+from vre.core.models import DepthLevel, Provenance, ProvenanceSource
 from vre.core.policy import Cardinality, PolicyAction, PolicyCallbackResult, PolicyResult, PolicyViolation
 from vre.core.policy.callback import PolicyCallContext
 from vre.core.policy.gate import PolicyGate
@@ -33,7 +43,14 @@
 
 __all__ = [
     "VRE",
+    "CandidateValidationError",
     "CyclicRelationshipError",
+    "GraphError",
+    "GraphIntegrityError",
+    "HydrationError",
+    "PersistenceError",
+    "ResolutionError",
+    "VREError",
     "PrimitiveRepository",
     "ConceptResolver",
     "GroundingEngine",
@@ -167,12 +184,12 @@ def check_policy(
         if grounding.trace is None:
             return PolicyResult(action=PolicyAction.PASS)
 
-        card_enum = Cardinality.SINGLE
+        card_enum: Cardinality | None = None
         if cardinality is not None:
             try:
                 card_enum = Cardinality(cardinality)
             except ValueError:
-                pass  # unknown string → fall back to SINGLE
+                card_enum = None  # unknown → fire all policies
 
         gate = PolicyGate()
         violations = gate.evaluate(grounding.trace, card_enum, call_context)

src/vre/core/__init__.py

@@ -1,16 +1,32 @@
 # Copyright 2026 Andrew Greene
 # Licensed under the Apache License, Version 2.0
 
-from vre.core.models import (
+from vre.core.errors import (
+    CandidateValidationError,
     CyclicRelationshipError,
+    GraphError,
+    GraphIntegrityError,
+    HydrationError,
+    PersistenceError,
+    ResolutionError,
+    VREError,
+)
+from vre.core.models import (
     Provenance,
     ProvenanceSource,
     TRANSITIVE_RELATION_TYPES,
 )
 
 __all__ = [
+    "CandidateValidationError",
     "CyclicRelationshipError",
+    "GraphError",
+    "GraphIntegrityError",
+    "HydrationError",
+    "PersistenceError",
     "Provenance",
     "ProvenanceSource",
+    "ResolutionError",
     "TRANSITIVE_RELATION_TYPES",
+    "VREError",
 ]

src/vre/core/errors.py

@@ -0,0 +1,45 @@
+# Copyright 2026 Andrew Greene
+# Licensed under the Apache License, Version 2.0
+
+"""
+VRE exception hierarchy.
+
+All VRE-specific exceptions derive from VREError so integrators can catch
+at the desired granularity — from a single error type up to the entire
+framework.
+
+VRE's responsibility is to roll back any in-memory mutations and re-raise
+errors with clear, typed exceptions. Integrators decide recovery strategy.
+"""
+
+
+class VREError(Exception):
+    """Base exception for all VRE errors."""
+
+
+class GraphError(VREError):
+    """A graph backend operation failed (read or write)."""
+
+
+class PersistenceError(GraphError):
+    """A write operation against the graph backend failed."""
+
+
+class GraphIntegrityError(VREError):
+    """A graph operation would violate structural integrity constraints."""
+
+
+class CyclicRelationshipError(GraphIntegrityError):
+    """An edge would create a cycle on transitive relationship types."""
+
+
+class HydrationError(VREError):
+    """Failed to reconstruct a domain object from stored data."""
+
+
+class ResolutionError(VREError):
+    """Failed to resolve a concept name or identifier."""
+
+
+class CandidateValidationError(VREError):
+    """A learning candidate is missing required fields or references invalid data."""