sdcvalidator 4.5.3__tar.gz → 4.6.0__tar.gz

{sdcvalidator-4.5.3 → sdcvalidator-4.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sdcvalidator
-Version: 4.5.3
+Version: 4.6.0
 Summary: SDC4 structural validator with ExceptionalValue recovery — thin wrapper over xmlschema
 Author: Axius SDC, Inc.
 License-Expression: Apache-2.0
@@ -104,6 +104,32 @@ tier = classifier.classify(some_xmlschema_error)
 # ErrorTier.STRUCTURAL or ErrorTier.SEMANTIC
 ```
 
+### Exceptional Value recovery
+
+A semantic (Tier 2) error does not have to reject a record. Recovery keeps the value and inserts an ISO 21090
+ExceptionalValue beside it (Invalid, for a value that fails its type, pattern, range or enumeration), so the record
+says which value is unusable and why, and the rest of it stays usable.
+
+```python
+from sdcvalidator import SDC4Validator, SDC4UnrecoverableError
+
+v = SDC4Validator("dm-xxxx.xsd", validation="lax")
+result = v.recover("record.xml")         # RecoveryResult; the source is never mutated
+for r in result.recoveries:              # Recovery: path, code ("INV"), name, reason, inserted
+    print(r.code, r.reason, r.path)
+if not result.ok:                        # an error no ExceptionalValue covers
+    print(result.unrecoverable)
+
+tree = v.validate_with_recovery("record.xml", save=False)   # raises SDC4UnrecoverableError instead
+```
+
+- An ExceptionalValue the record already carries (a refusal, a masked field, written where the record was made) is
+  kept, and covers its value; recovery never inserts a second one. `remove_existing_ev=True` removes them first.
+- An error recovery cannot cover is returned in `unrecoverable` by `recover()`, and raised as
+  `SDC4UnrecoverableError` by `validate_with_recovery()`; it is never skipped.
+- Structural (Tier 1) errors raise `SDC4StructuralValidationError`.
+- Pass an `XMLResource` when the record carries prefixed QNames in content (`xsi:type="sdc4:..."`).
+
 ### XML/JSON conversion
 
 ```python
@@ -173,7 +199,7 @@ A client configuration needs only `"command": "uvx", "args": ["sdcvalidator"]`.
 | Tier | Type | Examples | Action |
 |------|------|----------|--------|
 | 1 | Structural | Unknown elements, cardinality violations, wrong nesting | **Reject** |
-| 2 | Semantic | Type errors, pattern violations, enumeration mismatches | **Report** |
+| 2 | Semantic | Type errors, pattern violations, enumeration mismatches | **Report**, or recover with an ExceptionalValue |
 
 ## SDC4 Schema Compliance
 

{sdcvalidator-4.5.3 → sdcvalidator-4.6.0}/README.md

@@ -82,6 +82,32 @@ tier = classifier.classify(some_xmlschema_error)
 # ErrorTier.STRUCTURAL or ErrorTier.SEMANTIC
 ```
 
+### Exceptional Value recovery
+
+A semantic (Tier 2) error does not have to reject a record. Recovery keeps the value and inserts an ISO 21090
+ExceptionalValue beside it (Invalid, for a value that fails its type, pattern, range or enumeration), so the record
+says which value is unusable and why, and the rest of it stays usable.
+
+```python
+from sdcvalidator import SDC4Validator, SDC4UnrecoverableError
+
+v = SDC4Validator("dm-xxxx.xsd", validation="lax")
+result = v.recover("record.xml")         # RecoveryResult; the source is never mutated
+for r in result.recoveries:              # Recovery: path, code ("INV"), name, reason, inserted
+    print(r.code, r.reason, r.path)
+if not result.ok:                        # an error no ExceptionalValue covers
+    print(result.unrecoverable)
+
+tree = v.validate_with_recovery("record.xml", save=False)   # raises SDC4UnrecoverableError instead
+```
+
+- An ExceptionalValue the record already carries (a refusal, a masked field, written where the record was made) is
+  kept, and covers its value; recovery never inserts a second one. `remove_existing_ev=True` removes them first.
+- An error recovery cannot cover is returned in `unrecoverable` by `recover()`, and raised as
+  `SDC4UnrecoverableError` by `validate_with_recovery()`; it is never skipped.
+- Structural (Tier 1) errors raise `SDC4StructuralValidationError`.
+- Pass an `XMLResource` when the record carries prefixed QNames in content (`xsi:type="sdc4:..."`).
+
 ### XML/JSON conversion
 
 ```python
@@ -151,7 +177,7 @@ A client configuration needs only `"command": "uvx", "args": ["sdcvalidator"]`.
 | Tier | Type | Examples | Action |
 |------|------|----------|--------|
 | 1 | Structural | Unknown elements, cardinality violations, wrong nesting | **Reject** |
-| 2 | Semantic | Type errors, pattern violations, enumeration mismatches | **Report** |
+| 2 | Semantic | Type errors, pattern violations, enumeration mismatches | **Report**, or recover with an ExceptionalValue |
 
 ## SDC4 Schema Compliance
 

{sdcvalidator-4.5.3 → sdcvalidator-4.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sdcvalidator"
-version = "4.5.3"
+version = "4.6.0"
 description = "SDC4 structural validator with ExceptionalValue recovery — thin wrapper over xmlschema"
 license = "Apache-2.0"
 requires-python = ">=3.10"

{sdcvalidator-4.5.3 → sdcvalidator-4.6.0}/src/sdcvalidator/__init__.py

@@ -14,7 +14,7 @@ Thin wrapper over xmlschema with two-tier error classification and the SDC4
 "quarantine-and-tag" recovery pattern (ISO 21090 ExceptionalValues).
 """
 
-__version__ = "4.5.3"
+__version__ = "4.6.0"
 
 # etree_tostring is re-exported from xmlschema so callers can serialize the
 # ElementTree returned by validate_with_recovery() without importing xmlschema
@@ -27,12 +27,14 @@ except ImportError:  # pragma: no cover - fallback for older layouts
 from .validator import (
     SDC4Validator,
     ValidationResult,
+    Recovery,
+    RecoveryResult,
     validate_with_recovery,
 )
 from .error_classifier import ErrorClassifier
 from .error_mapper import ErrorMapper
 from .instance_modifier import InstanceModifier
-from .exceptions import SDC4StructuralValidationError
+from .exceptions import SDC4StructuralValidationError, SDC4UnrecoverableError
 from .constants import (
     ErrorTier,
     ExceptionalValueType,
@@ -56,6 +58,9 @@ __all__ = [
     "__version__",
     "SDC4Validator",
     "ValidationResult",
+    "Recovery",
+    "RecoveryResult",
+    "SDC4UnrecoverableError",
     "ErrorClassifier",
     "ErrorMapper",
     "InstanceModifier",

{sdcvalidator-4.5.3 → sdcvalidator-4.6.0}/src/sdcvalidator/exceptions.py

@@ -61,3 +61,30 @@ class SDC4StructuralValidationError(Exception):
     def error_count(self) -> int:
         """Return the number of structural errors."""
         return len(self.errors)
+
+
+class SDC4UnrecoverableError(Exception):
+    """
+    Raised by `validate_with_recovery` when a semantic (Tier 2) error cannot be
+    covered by an ExceptionalValue: no ExceptionalValue maps to it, or the
+    element it names cannot be found (4.6.0).
+
+    Before 4.6.0 such an error was logged and skipped, and the record came back
+    as recovered with an invalid value nobody had marked. `SDC4Validator.recover()`
+    returns these errors in `RecoveryResult.unrecoverable` instead of raising.
+    """
+
+    def __init__(self, errors: List['XMLSchemaValidationError'], message: str = None):
+        self.errors = errors
+        if message is None:
+            lines = ["Recovery could not cover every error:"]
+            for i, error in enumerate(errors, 1):
+                lines.append(f"  {i}. {error.reason or error}")
+                if error.path:
+                    lines.append(f"     at: {error.path}")
+            message = "\n".join(lines)
+        super().__init__(message)
+
+    @property
+    def error_count(self) -> int:
+        return len(self.errors)

{sdcvalidator-4.5.3 → sdcvalidator-4.6.0}/src/sdcvalidator/mcp_server.py

@@ -36,7 +36,7 @@ from sdcvalidator.schema_checker import validate_sdc4_schema_compliance
 JSONRPC_VERSION = "2.0"
 MCP_PROTOCOL_VERSION = "2024-11-05"
 SERVER_NAME = "sdcvalidator"
-SERVER_VERSION = "4.5.3"
+SERVER_VERSION = "4.6.0"
 
 # Validator cache: schema_path -> SDC4Validator
 _validators: dict[str, SDC4Validator] = {}

{sdcvalidator-4.5.3 → sdcvalidator-4.6.0}/src/sdcvalidator/validator.py

@@ -31,7 +31,8 @@ from xmlschema.validators.exceptions import XMLSchemaValidationError
 from .error_classifier import ErrorClassifier
 from .error_mapper import ErrorMapper
 from .instance_modifier import InstanceModifier
-from .exceptions import SDC4StructuralValidationError
+from .exceptions import SDC4StructuralValidationError, SDC4UnrecoverableError
+from .constants import EXCEPTIONAL_VALUE_CODES, ExceptionalValueType
 from .schema_checker import (
     validate_sdc4_schema_compliance,
     SDC4SchemaValidationError
@@ -52,6 +53,33 @@ class ValidationResult:
         return len(self.structural_errors) + len(self.semantic_errors)
 
 
+@dataclass
+class Recovery:
+    """One value an ExceptionalValue covers after recovery."""
+    path: str              # the Clark-form path of the element whose value failed (as xmlschema reports it)
+    code: str              # the ISO 21090 code: "INV"
+    name: str              # its name: "Invalid"
+    reason: str            # what failed, from the validator: the constraint, the pattern, the type
+    inserted: bool         # True if recovery inserted the ExceptionalValue; False if the record already carried one
+
+
+@dataclass
+class RecoveryResult:
+    """What `SDC4Validator.recover()` did: the recovered tree, each value it covered, and each error it could not."""
+    tree: ET.ElementTree
+    recoveries: List[Recovery] = field(default_factory=list)
+    unrecoverable: List[XMLSchemaValidationError] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        """True when every error is covered by an ExceptionalValue."""
+        return not self.unrecoverable
+
+    @property
+    def inserted(self) -> List[Recovery]:
+        return [r for r in self.recoveries if r.inserted]
+
+
 class SDC4Validator:
     """
     Validates XML instances against SDC4 data model schemas.
@@ -296,35 +324,37 @@ class SDC4Validator:
     # ExceptionalValue recovery (quarantine-and-tag)
     # ------------------------------------------------------------------ #
 
-    def validate_with_recovery(
+    def recover(
         self,
         xml_source: Union[str, Path, ET.Element, XMLResource],
-        output_path: Optional[Union[str, Path]] = None,
-        remove_existing_ev: bool = True,
-        save: bool = True,
-    ) -> ET.ElementTree:
+        remove_existing_ev: bool = False,
+    ) -> RecoveryResult:
         """
-        Validate an XML instance and insert ExceptionalValue elements for errors.
+        Validate an XML instance and cover each semantic error with an ExceptionalValue.
 
         Tier 1 (structural) errors cause a hard reject (SDC4StructuralValidationError).
-        Tier 2 (semantic) errors are quarantined with ExceptionalValue tags.
+        Tier 2 (semantic) errors are quarantined: the value stays in the record and an
+        ExceptionalValue is inserted beside it, once per value. A value whose element
+        already carries an ExceptionalValue (one written where the record was made: a
+        refusal, a masked field) is covered by it; nothing is inserted and nothing is
+        removed. An error that cannot be covered (no ExceptionalValue maps to it, or
+        the element cannot be found) is returned in `unrecoverable`, never skipped.
 
-        The recovered XML is saved unless save=False. When saving and no
-        output_path is given, defaults to '{stem}-ev{suffix}' beside the input.
+        Args:
+            xml_source: A path, an Element, or an XMLResource (use an XMLResource when
+                the instance carries prefixed QNames in content, such as xsi:type).
+            remove_existing_ev: Remove every ExceptionalValue already in the record
+                first. Off by default since 4.6.0: those written at the source are
+                data, and removing them loses why a value is missing.
 
         Returns:
-            Modified XML ElementTree with ExceptionalValue elements inserted.
+            RecoveryResult: the recovered tree (a copy; the source is never mutated),
+            the recoveries, and the unrecoverable errors.
 
         Raises:
             SDC4StructuralValidationError: If structural (Tier 1) errors are present.
-            ValueError: If save=True but output_path cannot be determined.
         """
-        original_file_path = None
-        if isinstance(xml_source, (str, Path)):
-            original_file_path = Path(xml_source)
-
         tree = self._to_tree(xml_source)
-        # Work on a deep copy so the caller's source is never mutated.
         root = copy.deepcopy(tree.getroot())
         tree = ET.ElementTree(root)
 
@@ -332,37 +362,70 @@ class SDC4Validator:
             self.instance_modifier.remove_existing_exceptional_values(root)
 
         errors = list(self._schema_errors(tree, xml_source))
+        structural = [e for e in errors if self.error_mapper.is_structural_error(e)]
+        if structural:
+            raise SDC4StructuralValidationError(structural)
 
-        structural_errors = []
-        semantic_errors = []
+        result = RecoveryResult(tree=tree)
+        covered: Dict[int, Recovery] = {}
         for error in errors:
-            if self.error_mapper.is_structural_error(error):
-                structural_errors.append(error)
+            ev_type = self.error_mapper.map_error(error)
+            reason = " ".join((error.reason or error.message or "").split())
+            target = self.instance_modifier._find_element_by_xpath(root, error.path) if error.path else None
+            parent = self.instance_modifier._find_parent_element(root, target) if target is not None else None
+            if ev_type is None or parent is None:
+                result.unrecoverable.append(error)
+                continue
+            if id(parent) in covered:          # a second failure in a value already covered
+                continue
+            existing = next((c for c in parent if isinstance(c.tag, str)
+                             and c.tag.rsplit("}", 1)[-1] in EXCEPTIONAL_VALUE_CODES), None)
+            if existing is not None:
+                code = existing.tag.rsplit("}", 1)[-1]
+                rec = Recovery(path=error.path, code=code, name=ExceptionalValueType.from_code(code).ev_name,
+                               reason=reason, inserted=False)
+            elif self.instance_modifier.insert_exceptional_value(
+                    root=root, xpath=error.path, ev_type=ev_type, reason=error.reason):
+                rec = Recovery(path=error.path, code=ev_type.code, name=ev_type.ev_name, reason=reason, inserted=True)
             else:
-                semantic_errors.append(error)
+                result.unrecoverable.append(error)
+                continue
+            covered[id(parent)] = rec
+            result.recoveries.append(rec)
+        return result
 
-        # Tier 1: hard reject.
-        if structural_errors:
-            raise SDC4StructuralValidationError(structural_errors)
+    def validate_with_recovery(
+        self,
+        xml_source: Union[str, Path, ET.Element, XMLResource],
+        output_path: Optional[Union[str, Path]] = None,
+        remove_existing_ev: bool = False,
+        save: bool = True,
+    ) -> ET.ElementTree:
+        """
+        Validate an XML instance and insert ExceptionalValue elements for errors.
 
-        # Tier 2: quarantine-and-tag.
-        for error in semantic_errors:
-            ev_type = self.error_mapper.map_error(error)
-            if ev_type is None:
-                continue
-            xpath = error.path
-            if xpath:
-                success = self.instance_modifier.insert_exceptional_value(
-                    root=root,
-                    xpath=xpath,
-                    ev_type=ev_type,
-                    reason=error.reason,
-                )
-                if not success:
-                    logger.warning(
-                        "Failed to insert ExceptionalValue at xpath '%s': %s",
-                        xpath, error.reason,
-                    )
+        Tier 1 (structural) errors cause a hard reject (SDC4StructuralValidationError).
+        Tier 2 (semantic) errors are quarantined with ExceptionalValue tags (see
+        `recover()`, which also returns what was covered and why). An error that
+        cannot be covered raises SDC4UnrecoverableError rather than returning a
+        record with an invalid value nobody marked (4.6.0).
+
+        The recovered XML is saved unless save=False. When saving and no
+        output_path is given, defaults to '{stem}-ev{suffix}' beside the input.
+
+        Returns:
+            Modified XML ElementTree with ExceptionalValue elements inserted.
+
+        Raises:
+            SDC4StructuralValidationError: If structural (Tier 1) errors are present.
+            SDC4UnrecoverableError: If a semantic error cannot be covered.
+            ValueError: If save=True but output_path cannot be determined.
+        """
+        original_file_path = Path(xml_source) if isinstance(xml_source, (str, Path)) else None
+        result = self.recover(xml_source, remove_existing_ev=remove_existing_ev)
+        if result.unrecoverable:
+            raise SDC4UnrecoverableError(result.unrecoverable)
+        tree = result.tree
 
         if save:
             if output_path is None:
@@ -396,7 +459,7 @@ class SDC4Validator:
         self,
         output_path: Union[str, Path],
         xml_source: Union[str, Path, ET.Element, XMLResource],
-        remove_existing_ev: bool = True,
+        remove_existing_ev: bool = False,
         encoding: str = 'UTF-8',
         xml_declaration: bool = True,
     ):

{sdcvalidator-4.5.3 → sdcvalidator-4.6.0}/src/sdcvalidator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sdcvalidator
-Version: 4.5.3
+Version: 4.6.0
 Summary: SDC4 structural validator with ExceptionalValue recovery — thin wrapper over xmlschema
 Author: Axius SDC, Inc.
 License-Expression: Apache-2.0
@@ -104,6 +104,32 @@ tier = classifier.classify(some_xmlschema_error)
 # ErrorTier.STRUCTURAL or ErrorTier.SEMANTIC
 ```
 
+### Exceptional Value recovery
+
+A semantic (Tier 2) error does not have to reject a record. Recovery keeps the value and inserts an ISO 21090
+ExceptionalValue beside it (Invalid, for a value that fails its type, pattern, range or enumeration), so the record
+says which value is unusable and why, and the rest of it stays usable.
+
+```python
+from sdcvalidator import SDC4Validator, SDC4UnrecoverableError
+
+v = SDC4Validator("dm-xxxx.xsd", validation="lax")
+result = v.recover("record.xml")         # RecoveryResult; the source is never mutated
+for r in result.recoveries:              # Recovery: path, code ("INV"), name, reason, inserted
+    print(r.code, r.reason, r.path)
+if not result.ok:                        # an error no ExceptionalValue covers
+    print(result.unrecoverable)
+
+tree = v.validate_with_recovery("record.xml", save=False)   # raises SDC4UnrecoverableError instead
+```
+
+- An ExceptionalValue the record already carries (a refusal, a masked field, written where the record was made) is
+  kept, and covers its value; recovery never inserts a second one. `remove_existing_ev=True` removes them first.
+- An error recovery cannot cover is returned in `unrecoverable` by `recover()`, and raised as
+  `SDC4UnrecoverableError` by `validate_with_recovery()`; it is never skipped.
+- Structural (Tier 1) errors raise `SDC4StructuralValidationError`.
+- Pass an `XMLResource` when the record carries prefixed QNames in content (`xsi:type="sdc4:..."`).
+
 ### XML/JSON conversion
 
 ```python
@@ -173,7 +199,7 @@ A client configuration needs only `"command": "uvx", "args": ["sdcvalidator"]`.
 | Tier | Type | Examples | Action |
 |------|------|----------|--------|
 | 1 | Structural | Unknown elements, cardinality violations, wrong nesting | **Reject** |
-| 2 | Semantic | Type errors, pattern violations, enumeration mismatches | **Report** |
+| 2 | Semantic | Type errors, pattern violations, enumeration mismatches | **Report**, or recover with an ExceptionalValue |
 
 ## SDC4 Schema Compliance
 

{sdcvalidator-4.5.3 → sdcvalidator-4.6.0}/src/sdcvalidator.egg-info/SOURCES.txt

@@ -25,6 +25,7 @@ tests/test_error_mapper.py
 tests/test_instance_modifier.py
 tests/test_mcp_server.py
 tests/test_recovery.py
+tests/test_recovery_460.py
 tests/test_registry_launch.py
 tests/test_schema_checker.py
 tests/test_validator.py

{sdcvalidator-4.5.3 → sdcvalidator-4.6.0}/tests/test_recovery.py

@@ -72,7 +72,7 @@ class TestSDC4Recovery(unittest.TestCase):
                 <label>Adult Population</label>
                 <xdcount-value>not_a_number</xdcount-value>
                 <xdcount-units>
-                    <label>Count Units</label>
+                    <label>Adult Population_units</label>
                     <xdstring-value>people</xdstring-value>
                 </xdcount-units>
             </sdc4:ms-q1ey1sf5otsa97e76kb06hco>

sdcvalidator-4.6.0/tests/test_recovery_460.py

@@ -0,0 +1,119 @@
+#
+# Copyright 2026 Semantic Data Charter Foundation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+"""
+4.6.0: recovery keeps the ExceptionalValues a record already carries, reports
+what it covered as data, and never skips an error it cannot cover.
+
+Before 4.6.0, `validate_with_recovery` removed every ExceptionalValue in the
+record first (so a refusal written where the record was made was lost whenever
+another value failed) and logged and skipped an error no ExceptionalValue maps
+to (so the record came back "recovered" with an invalid value nobody marked).
+"""
+from pathlib import Path
+from xml.etree import ElementTree as ET
+
+import pytest
+
+from sdcvalidator import (SDC4UnrecoverableError, SDC4Validator, Recovery, RecoveryResult)
+
+SCHEMA = Path(__file__).parent / "test_data" / "dm-jsi5yxnvzsmsisgn2bvelkni.xsd"
+SDC4 = "https://semanticdatacharter.com/ns/sdc4/"
+ASKR = '<sdc4:ASKR><ev-name>Asked and Refused</ev-name></sdc4:ASKR>'
+
+
+def record(count="5", ev="", units_label="Adult Population_units"):
+    return f'''<?xml version="1.0" encoding="UTF-8"?>
+<sdc4:dm-jsi5yxnvzsmsisgn2bvelkni xmlns:sdc4="{SDC4}">
+    <dm-label>StatePopulation</dm-label>
+    <dm-language>en-US</dm-language>
+    <dm-encoding>utf-8</dm-encoding>
+    <sdc4:ms-wnpz4qyrk369gnsivfsmysdf>
+        <label>StatePopulation Data Cluster</label>
+        <sdc4:ms-ahfdavxt7dpx960rqi1qtb0l>
+            <sdc4:ms-q1ey1sf5otsa97e76kb06hco>
+                <label>Adult Population</label>
+                {ev}
+                <xdcount-value>{count}</xdcount-value>
+                <xdcount-units>
+                    <label>{units_label}</label>
+                    <xdstring-value>people</xdstring-value>
+                </xdcount-units>
+            </sdc4:ms-q1ey1sf5otsa97e76kb06hco>
+        </sdc4:ms-ahfdavxt7dpx960rqi1qtb0l>
+    </sdc4:ms-wnpz4qyrk369gnsivfsmysdf>
+</sdc4:dm-jsi5yxnvzsmsisgn2bvelkni>
+'''
+
+
+@pytest.fixture(scope="module")
+def validator():
+    if not SCHEMA.exists():
+        pytest.skip("SDC4 example schema not found")
+    return SDC4Validator(SCHEMA, validation="lax")
+
+
+def element(xml):
+    return ET.fromstring(xml)
+
+
+def evs(tree):
+    comp = next(e for e in tree.getroot().iter() if e.tag == f"{{{SDC4}}}ms-q1ey1sf5otsa97e76kb06hco")
+    return [c.tag.split("}")[1] for c in comp if c.tag.startswith(f"{{{SDC4}}}")]
+
+
+def test_recover_reports_what_it_covered_as_data(validator):
+    r = validator.recover(element(record(count="not_a_number")))
+    assert isinstance(r, RecoveryResult) and r.ok
+    (rec,) = r.recoveries
+    assert isinstance(rec, Recovery)
+    assert (rec.code, rec.name, rec.inserted) == ("INV", "Invalid", True)
+    assert "not_a_number" in rec.reason and rec.path.endswith("xdcount-value")
+    assert evs(r.tree) == ["INV"]
+
+
+def test_a_valid_record_has_nothing_to_recover(validator):
+    r = validator.recover(element(record()))
+    assert r.ok and r.recoveries == [] and evs(r.tree) == []
+
+
+def test_an_exceptional_value_written_at_the_source_is_kept(validator):
+    tree = validator.validate_with_recovery(element(record(ev=ASKR)), save=False)
+    assert evs(tree) == ["ASKR"]
+
+
+def test_one_already_covering_a_bad_value_is_kept_and_nothing_is_added(validator):
+    r = validator.recover(element(record(count="not_a_number", ev=ASKR)))
+    (rec,) = r.recoveries
+    assert (rec.code, rec.inserted) == ("ASKR", False)
+    assert evs(r.tree) == ["ASKR"], "one ExceptionalValue per value"
+
+
+def test_removing_existing_ones_is_still_available_when_asked(validator):
+    r = validator.recover(element(record(count="not_a_number", ev=ASKR)), remove_existing_ev=True)
+    assert evs(r.tree) == ["INV"] and r.recoveries[0].inserted
+
+
+def test_an_error_nothing_covers_is_returned_not_skipped(validator):
+    r = validator.recover(element(record(units_label="Count Units")))
+    assert not r.ok and len(r.unrecoverable) == 1
+    assert "fixed value" in r.unrecoverable[0].reason
+
+
+def test_validate_with_recovery_raises_rather_than_return_an_unmarked_invalid_value(validator):
+    with pytest.raises(SDC4UnrecoverableError) as exc:
+        validator.validate_with_recovery(element(record(units_label="Count Units")), save=False)
+    assert exc.value.error_count == 1 and "fixed value" in str(exc.value)
+
+
+def test_the_source_is_never_mutated(validator):
+    root = element(record(count="not_a_number", ev=ASKR))
+    before = ET.tostring(root)
+    validator.recover(root)
+    assert ET.tostring(root) == before