assertpy2 2.13.0__tar.gz → 2.15.0__tar.gz

{assertpy2-2.13.0 → assertpy2-2.15.0}/.github/workflows/publish.yml

@@ -36,13 +36,13 @@ jobs:
 
       - name: Attest wheel
         id: attest-wheel
-        uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32 # v4.1.0
+        uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373 # v4.1.1
         with:
           subject-path: dist/*.whl
 
       - name: Attest sdist
         id: attest-sdist
-        uses: actions/attest-build-provenance@a2bbfa25375fe432b6a289bc6b6cd05ecd0c4c32 # v4.1.0
+        uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373 # v4.1.1
         with:
           subject-path: dist/*.tar.gz
 

{assertpy2-2.13.0 → assertpy2-2.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assertpy2
-Version: 2.13.0
+Version: 2.15.0
 Summary: Fluent assertion library for Python with composable matchers, structural matching, and full type safety
 Project-URL: Homepage, https://github.com/Solganis/assertpy2
 Project-URL: Repository, https://github.com/Solganis/assertpy2
@@ -169,7 +169,7 @@ See the [**Type Safety**](https://solganis.github.io/assertpy2/type-safety/) gui
 - [**Recursive field assertions**](https://solganis.github.io/assertpy2/assertions/#recursive-field-assertions): `all_fields_satisfy()` / `has_no_none_fields()` apply a predicate to every leaf of an object graph, reporting the exact path.
 - [**Universal negation**](https://solganis.github.io/assertpy2/fluent/#universal-negation): `.not_` inverts any assertion without dedicated `is_not_*` methods.
 - [**Collection pipeline**](https://solganis.github.io/assertpy2/fluent/#collection-pipeline): `filtered_on()`, `mapped()`, `flat_mapped()`, `first()`, `last()`, `element()`, `single()`.
-- [**Positional & pairwise checks**](https://solganis.github.io/assertpy2/assertions/#lists): `satisfies_exactly()`, `zip_satisfies()`, `contains_only_once()`, `has_same_size_as()`.
+- [**Positional & pairwise checks**](https://solganis.github.io/assertpy2/assertions/#lists): `satisfies_exactly()`, `zip_satisfies()`, `contains_only_once()`, `has_same_size_as()`, plus `*_in_any_order` variants.
 - [**Fluent chaining**](https://solganis.github.io/assertpy2/fluent/#chaining): write assertions as readable one-liners that chain naturally.
 
 **Built-in types**
@@ -178,21 +178,23 @@ See the [**Type Safety**](https://solganis.github.io/assertpy2/type-safety/) gui
 - [**Bytes assertions**](https://solganis.github.io/assertpy2/assertions/#bytes--bytearray): `is_valid_utf8()`, `starts_with_bytes()`, `is_hex_equal_to()`, `decoded_as()` for `bytes`/`bytearray`.
 - [**Dynamic assertions**](https://solganis.github.io/assertpy2/assertions/#dynamic-assertions-on-objects): `has_<name>()` for any attribute, property, or zero-argument method.
 - [**Dict comparison**](https://solganis.github.io/assertpy2/assertions/#selective-comparison-ignore--include): `is_equal_to()` with `ignore` and `include` for selective key/field matching (dicts, dataclasses, namedtuples, Pydantic models, attrs, plain objects), including by regex or type.
-- [**Recursive comparison**](https://solganis.github.io/assertpy2/assertions/#recursive-comparison-tolerance--custom-comparators): `is_equal_to()` with `tolerance` (absolute float tolerance at any depth) or `comparators` (per-type / per-field predicates) for nested structures.
+- [**Recursive comparison**](https://solganis.github.io/assertpy2/assertions/#recursive-comparison-tolerance--custom-comparators): `is_equal_to()` with `tolerance` (absolute float tolerance at any depth), `comparators` (per-type / per-field predicates), or `ignore_null` (skip fields the expected template leaves `None`) for nested structures.
 - [**Extracting**](https://solganis.github.io/assertpy2/assertions/#extracting-attributes-from-objects): flatten collections on attributes with `filter` and `sort` support.
 
 **Testing**
 
-- [**Soft assertions**](https://solganis.github.io/assertpy2/testing/#soft-assertions): thread-safe, async-safe via `contextvars`. Group errors with `sa.group()`, or use `assert_all()`.
-- [**Async assertions**](https://solganis.github.io/assertpy2/testing/#async-assertions): `eventually()` with polling/retry for eventual consistency.
+- [**Soft assertions**](https://solganis.github.io/assertpy2/testing/#soft-assertions): thread-safe, async-safe via `contextvars`; each collected failure is reported with its `file:line`. Group errors with `sa.group()`, or use `assert_all()`.
+- [**Polling assertions**](https://solganis.github.io/assertpy2/testing/#async-assertions): `eventually()` (async) / `eventually_sync()` (blocking) retry for eventual consistency, with a convergence trace pinpointing why a timeout never settled.
+- [**Expected exceptions**](https://solganis.github.io/assertpy2/errors/#expected-exceptions): `raises().when_called_with()` then assert on the message, walk the cause chain (`caused_by()`, `has_root_cause()`), match an `ExceptionGroup` (`contains_error()`), or pivot to the exception object (`raised()`).
 - [**Structured errors**](https://solganis.github.io/assertpy2/errors/#structured-errors): `AssertionFailure` with `.actual`, `.expected`, `.diff` attributes.
 - [**Rich pytest diffs**](https://solganis.github.io/assertpy2/errors/#rich-pytest-diffs): recursive structural diffs for lists, sets, strings, dicts, dataclasses, namedtuples, Pydantic models, and matcher-based assertions (`matches_structure()`, `satisfies()`, `each()`). Circular reference protection.
-- [**Snapshot testing**](https://solganis.github.io/assertpy2/testing/#snapshot-testing): store and compare data structures in JSON format.
-- **Property-based tested**: comparison, selective-diff, matcher algebra, and collection logic are checked with [Hypothesis](https://hypothesis.readthedocs.io) against reference semantics, on top of 100% branch coverage.
+- [**Snapshot testing**](https://solganis.github.io/assertpy2/testing/#snapshot-testing): store and compare data structures in JSON format; update via `--assertpy2-snapshot-update`. [`matches_contract_snapshot()`](https://solganis.github.io/assertpy2/testing/#contract-snapshots) catches structural regressions, value-tolerant.
 
 **Type safety**
 
 - [**Type-aware autocomplete**](https://solganis.github.io/assertpy2/type-safety/): 9 Protocols, IDE shows only relevant methods per type.
+- [**Typed narrowing**](https://solganis.github.io/assertpy2/type-safety/#typed-narrowing-with-value): `.value` hands the checked value back; `is_not_none()`, `is_instance_of()`, and a [`satisfies()` `TypeIs` predicate](https://solganis.github.io/assertpy2/type-safety/#refinement-narrowing-with-a-typeis-predicate-advanced) narrow its static type - no casts.
+- [**Contract testing**](https://solganis.github.io/assertpy2/type-safety/#contract-narrowing-with-assert_conforms): `assert_conforms()` validates a raw payload against a Pydantic v2 model and narrows the chain to it - the capstone for API-response tests; [`exact=True`](https://solganis.github.io/assertpy2/type-safety/#contract-drift-with-exacttrue) catches silent contract drift (undeclared fields), `each=True` validates list endpoints.
 - **py.typed**: `Self` return types, PEP 561 compliant ([PEP 561](https://peps.python.org/pep-0561/)).
 
 **Extensibility**

{assertpy2-2.13.0 → assertpy2-2.15.0}/README.md

@@ -121,7 +121,7 @@ See the [**Type Safety**](https://solganis.github.io/assertpy2/type-safety/) gui
 - [**Recursive field assertions**](https://solganis.github.io/assertpy2/assertions/#recursive-field-assertions): `all_fields_satisfy()` / `has_no_none_fields()` apply a predicate to every leaf of an object graph, reporting the exact path.
 - [**Universal negation**](https://solganis.github.io/assertpy2/fluent/#universal-negation): `.not_` inverts any assertion without dedicated `is_not_*` methods.
 - [**Collection pipeline**](https://solganis.github.io/assertpy2/fluent/#collection-pipeline): `filtered_on()`, `mapped()`, `flat_mapped()`, `first()`, `last()`, `element()`, `single()`.
-- [**Positional & pairwise checks**](https://solganis.github.io/assertpy2/assertions/#lists): `satisfies_exactly()`, `zip_satisfies()`, `contains_only_once()`, `has_same_size_as()`.
+- [**Positional & pairwise checks**](https://solganis.github.io/assertpy2/assertions/#lists): `satisfies_exactly()`, `zip_satisfies()`, `contains_only_once()`, `has_same_size_as()`, plus `*_in_any_order` variants.
 - [**Fluent chaining**](https://solganis.github.io/assertpy2/fluent/#chaining): write assertions as readable one-liners that chain naturally.
 
 **Built-in types**
@@ -130,21 +130,23 @@ See the [**Type Safety**](https://solganis.github.io/assertpy2/type-safety/) gui
 - [**Bytes assertions**](https://solganis.github.io/assertpy2/assertions/#bytes--bytearray): `is_valid_utf8()`, `starts_with_bytes()`, `is_hex_equal_to()`, `decoded_as()` for `bytes`/`bytearray`.
 - [**Dynamic assertions**](https://solganis.github.io/assertpy2/assertions/#dynamic-assertions-on-objects): `has_<name>()` for any attribute, property, or zero-argument method.
 - [**Dict comparison**](https://solganis.github.io/assertpy2/assertions/#selective-comparison-ignore--include): `is_equal_to()` with `ignore` and `include` for selective key/field matching (dicts, dataclasses, namedtuples, Pydantic models, attrs, plain objects), including by regex or type.
-- [**Recursive comparison**](https://solganis.github.io/assertpy2/assertions/#recursive-comparison-tolerance--custom-comparators): `is_equal_to()` with `tolerance` (absolute float tolerance at any depth) or `comparators` (per-type / per-field predicates) for nested structures.
+- [**Recursive comparison**](https://solganis.github.io/assertpy2/assertions/#recursive-comparison-tolerance--custom-comparators): `is_equal_to()` with `tolerance` (absolute float tolerance at any depth), `comparators` (per-type / per-field predicates), or `ignore_null` (skip fields the expected template leaves `None`) for nested structures.
 - [**Extracting**](https://solganis.github.io/assertpy2/assertions/#extracting-attributes-from-objects): flatten collections on attributes with `filter` and `sort` support.
 
 **Testing**
 
-- [**Soft assertions**](https://solganis.github.io/assertpy2/testing/#soft-assertions): thread-safe, async-safe via `contextvars`. Group errors with `sa.group()`, or use `assert_all()`.
-- [**Async assertions**](https://solganis.github.io/assertpy2/testing/#async-assertions): `eventually()` with polling/retry for eventual consistency.
+- [**Soft assertions**](https://solganis.github.io/assertpy2/testing/#soft-assertions): thread-safe, async-safe via `contextvars`; each collected failure is reported with its `file:line`. Group errors with `sa.group()`, or use `assert_all()`.
+- [**Polling assertions**](https://solganis.github.io/assertpy2/testing/#async-assertions): `eventually()` (async) / `eventually_sync()` (blocking) retry for eventual consistency, with a convergence trace pinpointing why a timeout never settled.
+- [**Expected exceptions**](https://solganis.github.io/assertpy2/errors/#expected-exceptions): `raises().when_called_with()` then assert on the message, walk the cause chain (`caused_by()`, `has_root_cause()`), match an `ExceptionGroup` (`contains_error()`), or pivot to the exception object (`raised()`).
 - [**Structured errors**](https://solganis.github.io/assertpy2/errors/#structured-errors): `AssertionFailure` with `.actual`, `.expected`, `.diff` attributes.
 - [**Rich pytest diffs**](https://solganis.github.io/assertpy2/errors/#rich-pytest-diffs): recursive structural diffs for lists, sets, strings, dicts, dataclasses, namedtuples, Pydantic models, and matcher-based assertions (`matches_structure()`, `satisfies()`, `each()`). Circular reference protection.
-- [**Snapshot testing**](https://solganis.github.io/assertpy2/testing/#snapshot-testing): store and compare data structures in JSON format.
-- **Property-based tested**: comparison, selective-diff, matcher algebra, and collection logic are checked with [Hypothesis](https://hypothesis.readthedocs.io) against reference semantics, on top of 100% branch coverage.
+- [**Snapshot testing**](https://solganis.github.io/assertpy2/testing/#snapshot-testing): store and compare data structures in JSON format; update via `--assertpy2-snapshot-update`. [`matches_contract_snapshot()`](https://solganis.github.io/assertpy2/testing/#contract-snapshots) catches structural regressions, value-tolerant.
 
 **Type safety**
 
 - [**Type-aware autocomplete**](https://solganis.github.io/assertpy2/type-safety/): 9 Protocols, IDE shows only relevant methods per type.
+- [**Typed narrowing**](https://solganis.github.io/assertpy2/type-safety/#typed-narrowing-with-value): `.value` hands the checked value back; `is_not_none()`, `is_instance_of()`, and a [`satisfies()` `TypeIs` predicate](https://solganis.github.io/assertpy2/type-safety/#refinement-narrowing-with-a-typeis-predicate-advanced) narrow its static type - no casts.
+- [**Contract testing**](https://solganis.github.io/assertpy2/type-safety/#contract-narrowing-with-assert_conforms): `assert_conforms()` validates a raw payload against a Pydantic v2 model and narrows the chain to it - the capstone for API-response tests; [`exact=True`](https://solganis.github.io/assertpy2/type-safety/#contract-drift-with-exacttrue) catches silent contract drift (undeclared fields), `each=True` validates list endpoints.
 - **py.typed**: `Self` return types, PEP 561 compliant ([PEP 561](https://peps.python.org/pep-0561/)).
 
 **Extensibility**

{assertpy2-2.13.0 → assertpy2-2.15.0}/assertpy2/__init__.py

@@ -5,6 +5,7 @@ from .assertpy import (
     __version__,
     add_extension,
     assert_all,
+    assert_conforms,
     assert_that,
     assert_warn,
     fail,
@@ -12,11 +13,11 @@ from .assertpy import (
     soft_assertions,
     soft_fail,
 )
-from .async_assertions import AsyncAssertionBuilder
-from .errors import AssertionFailure, DiffEntry, DiffResult
+from .async_assertions import AsyncAssertionBuilder, SyncAssertionBuilder
+from .errors import AssertionFailure, DiffEntry, DiffResult, PollSample, PollTrace
 from .file import contents_of
 from .matchers import Matcher, clear_custom_matchers, match, register_matcher, unregister_matcher
-from .snapshot import SnapshotCreatedWarning
+from .snapshot import SnapshotCreatedWarning, SnapshotUpdatedWarning, register_snapshot_serializer
 
 __all__ = [
     "AssertionFailure",
@@ -25,12 +26,17 @@ __all__ = [
     "DiffResult",
     "Matcher",
     "NegatedBuilder",
+    "PollSample",
+    "PollTrace",
     "SnapshotCreatedWarning",
+    "SnapshotUpdatedWarning",
     "SoftAssertionCollector",
+    "SyncAssertionBuilder",
     "WarningLoggingAdapter",
     "__version__",
     "add_extension",
     "assert_all",
+    "assert_conforms",
     "assert_that",
     "assert_warn",
     "clear_custom_matchers",
@@ -38,6 +44,7 @@ __all__ = [
     "fail",
     "match",
     "register_matcher",
+    "register_snapshot_serializer",
     "remove_extension",
     "soft_assertions",
     "soft_fail",

{assertpy2-2.13.0 → assertpy2-2.15.0}/assertpy2/_compare.py

@@ -2,7 +2,7 @@
 
 ``is_equal_to`` builds a `_CompareConfig` from its ``tolerance``/``comparators`` kwargs and threads it
 through both the boolean comparison (`HelpersMixin._dict_not_equal()`) and the diff/message rendering
-(`BaseMixin._sub_diff_entries()`, `HelpersMixin._dict_err()`).  `_node_decision()` is the single
+(`assertpy2._diff._sub_diff_entries()`, `HelpersMixin._dict_err()`).  `_node_decision()` is the single
 switch both sides consult, so a tolerated or comparator-equal leaf is reported in neither.  With ``config is
 None`` every helper reproduces the engine's historical ``actual != expected`` behavior exactly.
 
@@ -31,20 +31,25 @@ class _CompareConfig:
     """Tolerance and custom comparators for a single ``is_equal_to`` call.
 
     ``tolerance`` is an absolute tolerance applied to real-number leaves; ``comparators`` maps a ``type`` or
-    an immediate field name to a ``(actual, expected) -> bool`` predicate that owns matching leaves.
+    an immediate field name to a ``(actual, expected) -> bool`` predicate that owns matching leaves;
+    ``ignore_null`` skips a named field whenever the *expected* side leaves it ``None``.
     """
 
     tolerance: float | None = None
     comparators: dict[object, Callable[[object, object], bool]] | None = None
+    ignore_null: bool = False
 
 
-def _build_compare_config(tolerance, comparators) -> _CompareConfig | None:
-    """Validate the ``is_equal_to`` ``tolerance``/``comparators`` kwargs and build a config (``None`` if neither).
+def _build_compare_config(tolerance, comparators, ignore_null=False) -> _CompareConfig | None:
+    """Validate the ``is_equal_to`` ``tolerance``/``comparators``/``ignore_null`` kwargs and build a config.
 
-    ``tolerance`` must be a non-negative real number (not ``bool``/``complex``/``NaN``); ``comparators`` must be a
-    dict of ``(actual, expected) -> bool`` callables keyed by ``type`` or field name.
+    Returns ``None`` when none are set.  ``tolerance`` must be a non-negative real number (not
+    ``bool``/``complex``/``NaN``); ``comparators`` must be a dict of ``(actual, expected) -> bool`` callables
+    keyed by ``type`` or field name; ``ignore_null`` must be a bool.
     """
-    if tolerance is None and comparators is None:
+    if ignore_null is not False and ignore_null is not True:
+        raise TypeError("given ignore_null arg must be a bool")
+    if tolerance is None and comparators is None and not ignore_null:
         return None
     if tolerance is not None:
         if isinstance(tolerance, bool) or not isinstance(tolerance, numbers.Number) or isinstance(tolerance, complex):
@@ -59,7 +64,7 @@ def _build_compare_config(tolerance, comparators) -> _CompareConfig | None:
         for comparator in comparators.values():
             if not callable(comparator):
                 raise TypeError("each comparator must be callable")
-    return _CompareConfig(tolerance=tolerance, comparators=comparators)
+    return _CompareConfig(tolerance=tolerance, comparators=comparators, ignore_null=ignore_null)
 
 
 def _ambiguous_array_operand(value: object, other: object) -> object | None:
@@ -71,6 +76,8 @@ def _ambiguous_array_operand(value: object, other: object) -> object | None:
     truth test is actually attempted, so 0-d / scalar array values (which *are* truth-testable) pass
     through unchanged.
     """
+    if not hasattr(value, "__array__") and not hasattr(other, "__array__"):
+        return None  # fast path: no array-like operand, skip the tuple/loop on every is_equal_to
     for candidate, counterpart in ((value, other), (other, value)):
         if hasattr(candidate, "__array__"):
             try:
@@ -133,7 +140,7 @@ def _find_ambiguous_operand(actual, expected, _seen=None):
     return None
 
 
-def _guarded_not_equal(actual, expected) -> bool:
+def _guarded_not_equal(actual, expected, *, method="is_equal_to") -> bool:
     """``bool(actual != expected)``, converting the ambiguity raised from *inside* a container's ``==``
     (where the top-level operand gate cannot see the array member) into the actionable ``TypeError``."""
     try:
@@ -142,7 +149,18 @@ def _guarded_not_equal(actual, expected) -> bool:
         operand = _find_ambiguous_operand(actual, expected)
         if operand is None:
             raise
-        raise _array_equality_error("is_equal_to", operand) from error
+        raise _array_equality_error(method, operand) from error
+
+
+def _guarded_equal(actual, expected, *, method) -> bool:
+    """``bool(actual == expected)`` with the same nested array/frame-like guard as `_guarded_not_equal`."""
+    try:
+        return bool(actual == expected)
+    except (ValueError, TypeError) as error:
+        operand = _find_ambiguous_operand(actual, expected)
+        if operand is None:
+            raise
+        raise _array_equality_error(method, operand) from error
 
 
 def _is_real_number(value) -> bool:
@@ -195,6 +213,8 @@ def _node_decision(actual, expected, config: _CompareConfig | None, *, field=Non
     never recursed into.
     """
     if config is not None:
+        if config.ignore_null and field is not None and expected is None:
+            return "equal"  # a named field the expected side leaves None is not compared
         comparator = _resolve_comparator(actual, config, field=field)
         if comparator is not None:
             return "equal" if comparator(actual, expected) else "leaf"

assertpy2-2.15.0/assertpy2/_compat.py

@@ -0,0 +1,25 @@
+"""Internal compatibility shims.
+
+``Self`` entered the standard library's `typing` in Python 3.11; on 3.10 it is provided by
+``typing_extensions``. Re-exporting it from one place lets every mixin import ``Self`` without repeating
+the version gate, and lets ``typing_extensions`` be dropped as a runtime dependency on Python 3.11+.
+
+``BaseExceptionGroup`` is a builtin from Python 3.11; on 3.10 it comes from the ``exceptiongroup``
+backport when installed, and otherwise degrades to an empty tuple so ``isinstance`` is simply always
+``False`` (a 3.10 interpreter without the backport cannot have produced a group anyway).
+"""
+
+import sys
+
+if sys.version_info >= (3, 11):
+    from builtins import BaseExceptionGroup
+    from typing import Self
+else:  # pragma: no cover - exercised only on Python 3.10
+    from typing_extensions import Self
+
+    try:
+        from exceptiongroup import BaseExceptionGroup  # ty: ignore[unresolved-import]  # optional 3.10 backport
+    except ImportError:
+        BaseExceptionGroup = ()
+
+__all__ = ["BaseExceptionGroup", "Self"]

assertpy2-2.15.0/assertpy2/_contract.py

@@ -0,0 +1,161 @@
+"""Contract-drift detection for `assert_conforms(..., exact=True)`.
+
+Reports fields a raw payload carries that its pydantic v2 model does **not** declare - the silent API
+growth that `model_validate` drops by default.  Duck-typed on ``model_fields`` (no pydantic import),
+alias-aware, and recursive into nested sub-models and ``list``/``tuple`` of sub-models.
+"""
+
+from __future__ import annotations
+
+import types
+import typing
+from functools import reduce
+from typing import Any
+
+
+def _submodel(annotation: object) -> type | None:
+    """The nested model class for an annotation, peeling ``Optional`` / ``list`` / ``tuple``; else ``None``."""
+    origin = typing.get_origin(annotation)
+    args = typing.get_args(annotation)
+    if origin is typing.Union or origin is types.UnionType:
+        non_none = [arg for arg in args if arg is not type(None)]
+        return _submodel(non_none[0]) if len(non_none) == 1 else None
+    if origin in (list, tuple, set, frozenset) and args:
+        return _submodel(args[0])
+    if isinstance(annotation, type) and hasattr(annotation, "model_fields"):
+        return annotation
+    return None
+
+
+def _collect_aliases(keys: list[str], alias: object) -> None:
+    """Add every top-level payload key an alias spec maps to (str, ``AliasChoices``, ``AliasPath``)."""
+    if isinstance(alias, str):
+        keys.append(alias)
+    elif alias is not None:
+        for choice in getattr(alias, "choices", ()):  # AliasChoices
+            _collect_aliases(keys, choice)
+        path = getattr(alias, "path", None)  # AliasPath: its first segment is the consumed top-level key
+        if path and isinstance(path[0], str):
+            keys.append(path[0])
+
+
+def _alias_keys(info: Any) -> list[str]:
+    """Every top-level key a field may appear under, across ``alias`` and ``validation_alias``."""
+    keys: list[str] = []
+    _collect_aliases(keys, getattr(info, "alias", None))
+    _collect_aliases(keys, getattr(info, "validation_alias", None))
+    return keys
+
+
+def _declared_keys(model: Any) -> set[str]:
+    """Field names plus all their aliases, so an aliased payload key is not mistaken for drift."""
+    keys: set[str] = set()
+    for name, info in model.model_fields.items():
+        keys.add(name)
+        keys.update(_alias_keys(info))
+    return keys
+
+
+def contract_drift(payload: object, model: Any, path: str = "") -> list[str]:
+    """Paths of fields ``payload`` carries that ``model`` does not declare, recursively.
+
+    A model whose config opts into extras (``extra="allow"``) keeps them intentionally, so its level is
+    skipped.  Non-dict payloads (already validated) contribute nothing.
+    """
+    if not isinstance(payload, dict):
+        return []
+    drift: list[str] = []
+    if getattr(model, "model_config", {}).get("extra") != "allow":
+        declared = _declared_keys(model)
+        drift += [f"{path}{key}" for key in payload if key not in declared]
+    for name, info in model.model_fields.items():
+        submodel = _submodel(info.annotation)
+        if submodel is None:
+            continue
+        value = payload.get(name)
+        if value is None:
+            for alias in _alias_keys(info):
+                if alias in payload:
+                    value = payload.get(alias)
+                    break
+        if isinstance(value, (list, tuple)):
+            for index, element in enumerate(value):
+                drift += contract_drift(element, submodel, f"{path}{name}[{index}].")
+        elif isinstance(value, dict):
+            drift += contract_drift(value, submodel, f"{path}{name}.")
+    return drift
+
+
+def shape(value: object) -> object:
+    """The structural shape of a value: paths and type *categories*, never values.
+
+    Numbers collapse to one category (so ``5`` and ``5.0`` do not read as drift) and ``None`` becomes
+    ``"null"`` (a nullable wildcard).  A list becomes a single merged element shape.  This is what a
+    contract snapshot stores, so later runs pass when values change but fail on structural drift.
+    """
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "bool"
+    if isinstance(value, (int, float)):
+        return "number"
+    if isinstance(value, str):
+        return "str"
+    if isinstance(value, dict):
+        return {key: shape(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        element_shapes = [shape(item) for item in value]
+        return [reduce(_merge, element_shapes)] if element_shapes else []
+    return type(value).__name__
+
+
+def _merge(left: Any, right: Any) -> Any:
+    """Merge two element shapes into one representative shape (``null`` yields to a concrete type)."""
+    if left == right:
+        return left
+    if left == "null":
+        return right
+    if right == "null":
+        return left
+    if isinstance(left, dict) and isinstance(right, dict):
+        return {key: _merge(left.get(key, "null"), right.get(key, "null")) for key in set(left) | set(right)}
+    if isinstance(left, list) and isinstance(right, list):
+        if not left:
+            return right
+        if not right:
+            return left
+        return [_merge(left[0], right[0])]
+    return "mixed"
+
+
+def _shape_name(part: object) -> str:
+    if isinstance(part, str):
+        return part
+    return "object" if isinstance(part, dict) else "list"
+
+
+def _join(path: str, key: str) -> str:
+    return f"{path}.{key}" if path else key
+
+
+def shape_diff(old: Any, new: Any, path: str = "") -> list[tuple[str, str, str]]:
+    """Structural drift between two shapes: ``(kind, path, detail)`` for added / removed / retyped leaves.
+
+    A ``null`` on either side is a nullable wildcard and never counts as drift.
+    """
+    if old == new or old == "null" or new == "null":
+        return []
+    if isinstance(old, dict) and isinstance(new, dict):
+        drift: list[tuple[str, str, str]] = [("added", _join(path, key), "") for key in new if key not in old]
+        for key in old:
+            child = _join(path, key)
+            if key not in new:
+                drift.append(("removed", child, ""))
+            else:
+                drift += shape_diff(old[key], new[key], child)
+        return drift
+    if isinstance(old, list) and isinstance(new, list):
+        if not old or not new:
+            return []
+        return shape_diff(old[0], new[0], f"{path}[*]")
+    return [("retyped", path, f"{_shape_name(old)} -> {_shape_name(new)}")]