fix: correct adapter dispatch and safe data completeness

Author: igors93

CHANGELOG.md

@@ -42,7 +42,7 @@ All notable changes to this project will be documented in this file.
 - `LIMIT_ADAPTER_ERROR`, `LIMIT_UNSUPPORTED_TYPE`, `LIMIT_RECURSIVE` constants
   exported from `logprivacy.internal.traversal` for stable limitation identifiers.
 
-## 0.5.1 - Unreleased
+## 0.5.1 - 2026-06-04
 
 ### Changed
 

docs/data/structured-data.md

@@ -7,6 +7,8 @@ LogPrivacy has two structured-data APIs:
 - `to_safe_data()` converts supported Python values into sanitized JSON-safe
   data: `None`, booleans, finite numbers, strings, lists, and dictionaries with
   string keys.
+- `to_safe_data_with_result()` does the same and additionally returns completeness
+  metadata, limitation identifiers, and per-call statistics.
 
 Use `to_safe_data()` before structured logging, JSON responses, JSON files, or
 anywhere arbitrary Python objects must not escape into output.
@@ -84,6 +86,52 @@ to_safe_data(Request("req-1", {"token": "abc123456789"}), adapters=adapters)
 `AdapterRegistry.default()` returns a fresh registry. Registering a converter in
 one registry does not mutate another registry or global process state.
 
+### Dispatch Order
+
+Adapter resolution runs **before** the built-in structural handlers for
+`Mapping`, `list`/`tuple`, and `set`/`frozenset`. This means a custom subclass
+registered in the adapter registry always takes precedence over the native
+fallback, even if the subclass inherits from a built-in container type.
+
+Dispatch order within `_normalize`:
+
+1. Exact primitive types: `None`, `bool`, `int`, `float`, `str`, `bytes`,
+   `bytearray`, `memoryview` — always handled by the core pipeline, never
+   intercepted by adapters.
+2. Adapter registry — MRO lookup first (no `isinstance`), then virtual/abstract
+   types (protected `isinstance` calls).
+3. Structural fallbacks — `str` subclasses, `Mapping`, `list`/`tuple`,
+   `set`/`frozenset`, dataclasses, `Enum`, `Decimal`, date/time types, `UUID`,
+   `Path`, exceptions.
+4. Unsupported — becomes `[UNSUPPORTED:TypeName]`.
+
+### Reserved Types
+
+The following types are reserved for the core pipeline and cannot be used as
+adapter targets. Attempting to register them raises `ValueError`:
+
+`object`, `str`, `int`, `float`, `bool`, `bytes`, `bytearray`, `memoryview`,
+`dict`, `list`, `tuple`, `set`, `frozenset`.
+
+Custom subclasses are fully supported:
+
+```python
+class ExternalList(list):
+    pass
+
+adapters.register(ExternalList, lambda v: {"items": list(v), "source": "external"})
+```
+
+### Adapter Failures
+
+If a converter raises, returns the original object, or if `__instancecheck__`
+raises during virtual-type resolution, the value becomes
+`[UNSUPPORTED:TypeName]` and `adapter_error` is added to limitations. The
+original value is never exposed.
+
+Converters are never called on reserved primitive types regardless of how the
+registry was configured.
+
 ## Field Rules
 
 `CleanerPolicy.sensitive_keys` is still supported. For more control, add
@@ -115,13 +163,70 @@ Field rules support four actions:
 
 - `mask`: replace the value using the policy masking strategy;
 - `remove`: keep the field but replace the value with `[REMOVED]`;
-- `truncate`: keep only `max_chars` from textual values, then sanitize that
-  preserved text;
+- `truncate`: sanitize the **full** text first, then cut to `max_chars` and
+  append `[TRUNCATED]` if needed. This order ensures secrets that fall after
+  the cut point are never exposed in the output.
 - `block`: raise `LogBlockedError` without including the blocked value.
 
-In this phase, `truncate` is intentionally limited to textual values
-(`str`, `bytes`, `bytearray`, and `memoryview`). Non-text values become
-`[TRUNCATED]`.
+`truncate` is limited to textual values (`str`, `bytes`, `bytearray`, and
+`memoryview`). Non-text values become `[TRUNCATED]` without sanitization
+(there is no text content to redact).
+
+### Field Rules on Exceptions
+
+Field rules apply to the `type` and `message` fields produced when an exception
+is sanitized, giving the same protection as mappings and dataclasses:
+
+```python
+from logprivacy import CleanerPolicy, FieldRule, to_safe_data
+
+policy = CleanerPolicy.default().add_field_rules(
+    FieldRule.exact("message", action="remove"),
+)
+
+to_safe_data(ValueError("secret token: abc123"), policy=policy)
+# {"type": "ValueError", "message": "[REMOVED]"}
+```
+
+## Rich Output with SafeDataResult
+
+Use `to_safe_data_with_result()` when you need to know whether sanitization was
+complete, which limits were reached, or how many fields were redacted:
+
+```python
+from logprivacy import to_safe_data_with_result
+
+result = to_safe_data_with_result(payload)
+
+if not result.complete:
+    logger.warning("partial sanitization: %s", result.limitations)
+
+log_event(result.cleaned)
+```
+
+`SafeDataResult` fields:
+
+- `cleaned` — the sanitized value, equivalent to `to_safe_data(payload)`;
+- `complete` — `False` when any traversal limit was reached or any branch could
+  not be fully inspected;
+- `limitations` — a tuple of stable string identifiers for each limit hit:
+  `max_depth`, `max_items`, `iteration_error`, `representation_error`,
+  `adapter_error`, `unsupported_type`, `recursive_value`;
+- `stats` — a `SafeDataStats` dataclass with aggregate counters.
+
+`SafeDataStats` fields:
+
+| Field | Counts |
+|---|---|
+| `masked` | text findings redacted by the text pipeline plus structural mask actions and sensitive-key masking |
+| `removed` | fields replaced with `[REMOVED]` by a `remove` rule |
+| `truncated` | fields truncated by a `truncate` rule |
+| `unsupported` | values replaced with `[UNSUPPORTED:TypeName]` |
+| `adapter_errors` | converters that raised, returned self, or had `__instancecheck__` raise during resolution |
+| `field_rule_matches` | total `FieldRule` matches across all fields |
+
+Both `SafeDataResult` and `SafeDataStats` are frozen dataclasses. Neither retains
+any reference to the original value or raw converter output.
 
 ## Safe JSON
 

src/logprivacy/adapters/registry.py

@@ -31,10 +31,18 @@
 )
 
 
-def _safe_adapter_type_name(value: object) -> str:
-    name = type(value).__name__ or "object"
-    safe = _SAFE_TYPE_NAME_PATTERN.sub("_", name)[:80]
-    return safe or "object"
+@dataclass(frozen=True, slots=True)
+class _AdapterResolution:
+    """Internal result of an adapter resolution attempt.
+
+    ``converter`` is the callable to use, or ``None`` when no adapter matched.
+    ``resolution_failed`` is ``True`` when ``__instancecheck__`` raised during
+    the virtual-type scan; in that case the resolution is not fully reliable and
+    the caller must mark ``adapter_error`` and not execute the converter.
+    """
+
+    converter: AdapterConverter | None = None
+    resolution_failed: bool = False
 
 
 @dataclass(slots=True)
@@ -47,6 +55,10 @@ class AdapterRegistry:
     registered.  A custom subclass such as ``class ExternalList(list)`` *can*
     be registered; ``list`` itself cannot.
 
+    Adapter dispatch for custom subclasses happens **before** the built-in
+    structural handlers (Mapping, list/tuple, set/frozenset), so a registered
+    converter always takes precedence over the native fallback.
+
     ``default()`` returns a fresh registry so applications and tests can add
     converters without mutating shared global state.
     """
@@ -88,24 +100,52 @@ def resolve(self, value: object) -> AdapterConverter | None:
         """Return the best converter for ``value`` or ``None``.
 
         Resolution order:
-        1. Concrete type registered directly.
-        2. Base classes in MRO order, most specific first.
-        3. Abstract / virtual base classes in registration order.
+        1. Concrete type registered directly (MRO walk, no ``isinstance``).
+        2. Abstract / virtual base classes in registration order.
 
-        ``__instancecheck__`` calls are protected; a metaclass that raises
-        during ``isinstance`` is treated as non-matching.
+        ``__instancecheck__`` calls are protected.  A metaclass that raises
+        during ``isinstance`` is treated as non-matching.  Use
+        ``_resolve_result()`` when you need to distinguish "no match" from
+        "resolution failed".
+        """
+        return self._resolve_result(value).converter
+
+    def _resolve_result(self, value: object) -> _AdapterResolution:
+        """Return a resolution result distinguishing success, failure, and no-match.
+
+        Resolution order:
+        1. Concrete type and MRO bases (direct dict lookup — never raises).
+        2. Virtual / abstract base classes in registration order (protected
+           ``isinstance`` calls — a metaclass that raises sets
+           ``resolution_failed=True`` and the normalizer marks ``adapter_error``).
+
+        When ``resolution_failed`` is ``True`` the caller must mark
+        ``adapter_error`` and not execute any converter.
         """
         value_type = type(value)
+
+        # Phase 1: MRO-based lookup (safe — pure dict lookup, no user code).
         for candidate in value_type.__mro__:
             converter = self._converters.get(candidate)
             if converter is not None:
-                return converter
+                return _AdapterResolution(converter=converter)
 
+        # Phase 2: virtual / abstract base class scan (may call __instancecheck__).
+        resolution_failed = False
         for registered_type, converter in self._converters.items():
             try:
                 matches = isinstance(value, registered_type)
             except Exception:
-                matches = False
+                # __instancecheck__ raised — resolution is not fully reliable.
+                # Record the failure; do NOT use this or any subsequent converter.
+                resolution_failed = True
+                continue
             if matches:
-                return converter
-        return None
+                if resolution_failed:
+                    # A prior failure makes the overall resolution unreliable.
+                    break
+                return _AdapterResolution(converter=converter)
+
+        if resolution_failed:
+            return _AdapterResolution(resolution_failed=True)
+        return _AdapterResolution()

src/logprivacy/cleaner/engine.py

@@ -44,13 +44,19 @@ class Cleaner:
     _scanner: TextScanner = field(init=False, repr=False)
     _resolver: FindingResolver = field(init=False, repr=False)
     _redactor: TextRedactor = field(init=False, repr=False)
+    _placeholder_redactor: TextRedactor = field(init=False, repr=False)
 
     def __post_init__(self) -> None:
         """Build the text pipeline once and validate the rule set eagerly."""
         rule_set = RuleSet(self.policy.rules)
         object.__setattr__(self, "_scanner", TextScanner(rule_set))
         object.__setattr__(self, "_resolver", FindingResolver())
         object.__setattr__(self, "_redactor", TextRedactor(rule_set, self.policy.masking))
+        object.__setattr__(
+            self,
+            "_placeholder_redactor",
+            TextRedactor(rule_set, PlaceholderMaskingStrategy()),
+        )
 
     # ------------------------------------------------------------------
     # Public API
@@ -249,9 +255,7 @@ def _sanitize_location_text(self, text: str) -> str:
         resolved = self._resolver.resolve(raw_matches)
         if not resolved:
             return text
-        rule_set = RuleSet(self.policy.rules)
-        placeholder_redactor = TextRedactor(rule_set, PlaceholderMaskingStrategy())
-        cleaned, _ = placeholder_redactor.redact(text, resolved)
+        cleaned, _ = self._placeholder_redactor.redact(text, resolved)
         return cleaned
 
     def _bounded_findings(