boarddata 6.7.3__tar.gz → 6.7.4__tar.gz

{boarddata-6.7.3 → boarddata-6.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boarddata
-Version: 6.7.3
+Version: 6.7.4
 Summary: Python SDK for the BoardData V2 REST API
 License: MIT
 Classifier: Development Status :: 4 - Beta

{boarddata-6.7.3 → boarddata-6.7.4}/__init__.py

@@ -6,7 +6,7 @@ from .cache import FileTokenCache, ScalewaySecretTokenCache
 from .client import BoardDataClient
 from .errors import BoardDataError, ExportTooLargeError
 
-__version__ = "6.7.3"
+__version__ = "6.7.4"
 __all__ = [
     "Base",
     "BoardDataClient",

{boarddata-6.7.3 → boarddata-6.7.4}/_comex.py

@@ -5,7 +5,14 @@ from __future__ import annotations
 import logging
 from typing import Any
 
-from .types.comex import ComexCompensationDetail, ComexDetail, ComexExportItem
+from .types.comex import (
+    ComexCompensationDetail,
+    ComexDetail,
+    ComexExportItem,
+    ComponentAchievementRateWritePayload,
+    CriterionWritePayload,
+    Nature,
+)
 from .types.core import FieldSourcePayload, PaginatedResponse, UpsertResult
 
 logger = logging.getLogger("boarddata")
@@ -50,7 +57,7 @@ class ComexMixin:
             date_from: Filter mandates valid from this date.
             date_to: Filter mandates valid to this date.
             as_of: Show mandates active on this date.
-            nature: Filter by compensation nature (``"REAL"`` or ``"POLITIC"``).
+            nature: Filter by compensation nature (``"real"`` or ``"politic"``).
             roles: Filter by role identifiers (e.g. ``["CEO", "CFO"]``).
             role_at: Filter for mandates that held a role at this date (``"YYYY-MM-DD"``).
             page: Page number (1-indexed).
@@ -231,7 +238,7 @@ class ComexMixin:
             date_from: Filter mandates valid from this date (``"YYYY-MM-DD"``).
             date_to: Filter mandates valid to this date (``"YYYY-MM-DD"``).
             as_of: Show mandates active on this date (``"YYYY-MM-DD"``).
-            nature: Filter by compensation nature (``"REAL"`` or ``"POLITIC"``).
+            nature: Filter by compensation nature (``"real"`` or ``"politic"``).
             **kwargs: Advanced filters forwarded as query params.
 
         Returns:
@@ -310,7 +317,7 @@ class ComexMixin:
         self,
         comex_uid: str,
         fiscal_year: int,
-        nature: str,
+        nature: Nature,
         *,
         assembly: str | None = None,
         fixed: str | None = None,
@@ -350,21 +357,26 @@ class ComexMixin:
         subsidiary_remuneration: str | None = None,
         remuneration_via_holding: bool | None = None,
         sti_basis: str | None = None,
+        variable_max: str | None = None,
+        variable_target_pct: str | None = None,
+        variable_max_pct: str | None = None,
         variable_target_value: str | None = None,
         variable_max_value: str | None = None,
+        reference_amount: str | None = None,
         lti_grant_cap_basis: str | None = None,
         lti_grant_cap_value: str | None = None,
+        policy_changed_midyear: bool | None = None,
         currency: str | None = None,
         field_sources: list[FieldSourcePayload] | None = None,
-        criteria: list[dict[str, Any]] | None = None,
-        component_achievement_rates: list[dict[str, Any]] | None = None,
+        criteria: list[CriterionWritePayload] | None = None,
+        component_achievement_rates: list[ComponentAchievementRateWritePayload] | None = None,
     ) -> ComexCompensationDetail:
         """Create a compensation entry for a comex mandate.
 
         Args:
             comex_uid: Comex mandate UUID.
             fiscal_year: Fiscal year.
-            nature: Compensation nature (``"REAL"`` or ``"POLITIC"``).
+            nature: Compensation nature (``"real"`` or ``"politic"``).
             assembly: Assembly UUID.
             fixed: Fixed compensation (decimal).
             variable: Variable compensation (decimal).
@@ -403,15 +415,26 @@ class ComexMixin:
             subsidiary_remuneration: Subsidiary remuneration (decimal).
             remuneration_via_holding: Whether remuneration is provided via holding.
             sti_basis: Disclosed STI base form (frozen enum, e.g. ``"pct_of_fixed"``).
+            variable_max: STI cap in EUR (decimal string; always €, never
+                disclosed-basis — the disclosed-basis cap goes in
+                ``variable_max_value``).
+            variable_target_pct: STI target normalized to % of fixed (decimal
+                string; stated or derivation-backed, never back-solved).
+            variable_max_pct: STI cap normalized to % of fixed (decimal string).
             variable_target_value: STI target in the DISCLOSED basis (decimal string;
                 interpretation governed by ``sti_basis`` — never converted).
             variable_max_value: STI cap in the DISCLOSED basis (decimal string).
+            reference_amount: STI reference base amount in EUR (decimal string;
+                ``sti_basis="pct_of_reference_amount"`` archetype).
             lti_grant_cap_basis: Disclosed LTI grant-cap basis (frozen enum).
             lti_grant_cap_value: LTI grant cap in the DISCLOSED basis (decimal string).
+            policy_changed_midyear: Policy regime changed mid-year; the stored
+                row is the fiscal-year-end regime (D5).
             currency: Currency code (e.g. ``"EUR"``).
             field_sources: Document provenance for fields.
-            criteria: List of compensation criteria dicts.
-            component_achievement_rates: List of achievement rate dicts.
+            criteria: List of nested criteria entries (see ``CriterionWritePayload``).
+            component_achievement_rates: List of achievement-rate entries (see
+                ``ComponentAchievementRateWritePayload``).
 
         Returns:
             Created ComexCompensationDetail.
@@ -460,10 +483,15 @@ class ComexMixin:
             subsidiary_remuneration=subsidiary_remuneration,
             remuneration_via_holding=remuneration_via_holding,
             sti_basis=sti_basis,
+            variable_max=variable_max,
+            variable_target_pct=variable_target_pct,
+            variable_max_pct=variable_max_pct,
             variable_target_value=variable_target_value,
             variable_max_value=variable_max_value,
+            reference_amount=reference_amount,
             lti_grant_cap_basis=lti_grant_cap_basis,
             lti_grant_cap_value=lti_grant_cap_value,
+            policy_changed_midyear=policy_changed_midyear,
             currency=currency,
             field_sources=field_sources,
             criteria=criteria,
@@ -475,7 +503,7 @@ class ComexMixin:
         self,
         comex_uid: str,
         fiscal_year: int,
-        nature: str,
+        nature: Nature,
         *,
         assembly: str | None = None,
         fixed: str | None = None,
@@ -515,21 +543,26 @@ class ComexMixin:
         subsidiary_remuneration: str | None = None,
         remuneration_via_holding: bool | None = None,
         sti_basis: str | None = None,
+        variable_max: str | None = None,
+        variable_target_pct: str | None = None,
+        variable_max_pct: str | None = None,
         variable_target_value: str | None = None,
         variable_max_value: str | None = None,
+        reference_amount: str | None = None,
         lti_grant_cap_basis: str | None = None,
         lti_grant_cap_value: str | None = None,
+        policy_changed_midyear: bool | None = None,
         currency: str | None = None,
         field_sources: list[FieldSourcePayload] | None = None,
-        criteria: list[dict[str, Any]] | None = None,
-        component_achievement_rates: list[dict[str, Any]] | None = None,
+        criteria: list[CriterionWritePayload] | None = None,
+        component_achievement_rates: list[ComponentAchievementRateWritePayload] | None = None,
     ) -> dict[str, Any]:
         """Replace (clean-swap) a compensation entry for a comex mandate.
 
         Args:
             comex_uid: Comex mandate UUID.
             fiscal_year: Fiscal year.
-            nature: Compensation nature (``"REAL"`` or ``"POLITIC"``).
+            nature: Compensation nature (``"real"`` or ``"politic"``).
             assembly: Assembly UUID.
             fixed: Fixed compensation (decimal).
             variable: Variable compensation (decimal).
@@ -568,18 +601,30 @@ class ComexMixin:
             subsidiary_remuneration: Subsidiary remuneration (decimal).
             remuneration_via_holding: Whether remuneration is provided via holding.
             sti_basis: Disclosed STI base form (frozen enum, e.g. ``"pct_of_fixed"``).
+            variable_max: STI cap in EUR (decimal string; always €, never
+                disclosed-basis — the disclosed-basis cap goes in
+                ``variable_max_value``).
+            variable_target_pct: STI target normalized to % of fixed (decimal
+                string; stated or derivation-backed, never back-solved).
+            variable_max_pct: STI cap normalized to % of fixed (decimal string).
             variable_target_value: STI target in the DISCLOSED basis (decimal string;
                 interpretation governed by ``sti_basis`` — never converted).
             variable_max_value: STI cap in the DISCLOSED basis (decimal string).
+            reference_amount: STI reference base amount in EUR (decimal string;
+                ``sti_basis="pct_of_reference_amount"`` archetype).
             lti_grant_cap_basis: Disclosed LTI grant-cap basis (frozen enum).
             lti_grant_cap_value: LTI grant cap in the DISCLOSED basis (decimal string).
+            policy_changed_midyear: Policy regime changed mid-year; the stored
+                row is the fiscal-year-end regime (D5).
             currency: Currency code (e.g. ``"EUR"``).
             field_sources: Document provenance for fields.
-            criteria: List of compensation criteria dicts.
-            component_achievement_rates: List of achievement rate dicts.
+            criteria: List of nested criteria entries (see ``CriterionWritePayload``).
+            component_achievement_rates: List of achievement-rate entries (see
+                ``ComponentAchievementRateWritePayload``).
 
         Returns:
-            dict with {"id", "action"} where action is "replaced" (a prior live row existed) or "created" (none existed).
+            dict with {"id", "action"} where action is "replaced" (a prior live row
+            existed) or "created" (none existed).
 
         Raises:
             BoardDataError: On non-2xx API response.
@@ -625,10 +670,15 @@ class ComexMixin:
             subsidiary_remuneration=subsidiary_remuneration,
             remuneration_via_holding=remuneration_via_holding,
             sti_basis=sti_basis,
+            variable_max=variable_max,
+            variable_target_pct=variable_target_pct,
+            variable_max_pct=variable_max_pct,
             variable_target_value=variable_target_value,
             variable_max_value=variable_max_value,
+            reference_amount=reference_amount,
             lti_grant_cap_basis=lti_grant_cap_basis,
             lti_grant_cap_value=lti_grant_cap_value,
+            policy_changed_midyear=policy_changed_midyear,
             currency=currency,
             field_sources=field_sources,
             criteria=criteria,

{boarddata-6.7.3 → boarddata-6.7.4}/_committees.py

@@ -6,9 +6,7 @@ from .types.committees import CommitteeBatchItemPayload, CommitteeBatchResultIte
 
 
 class CommitteesMixin:
-    def batch_create_committees(
-        self, items: list[CommitteeBatchItemPayload]
-    ) -> list[CommitteeBatchResultItem]:
+    def batch_create_committees(self, items: list[CommitteeBatchItemPayload]) -> list[CommitteeBatchResultItem]:
         """Batch upsert board committees. Each item is keyed by issuer ISIN;
         the backend resolves members to existing persons and idempotently
         upserts Committee + CommitteeMembership. Returns one result per item

{boarddata-6.7.3 → boarddata-6.7.4}/_directors.py

@@ -55,7 +55,7 @@ class DirectorMixin:
             expiring_year: Keep only mandates whose ``valid_to`` falls inside
                 the given calendar year. Strictly excludes mandates with
                 ``valid_to IS NULL`` (still active).
-            nature: Filter by compensation nature (``"REAL"`` or ``"POLITIC"``).
+            nature: Filter by compensation nature (``"real"`` or ``"politic"``).
             roles: Filter by role identifiers (e.g. ``["Independent", "Chairman"]``).
             role_at: Filter for mandates that held a role at this date (``"YYYY-MM-DD"``).
             page: Page number (1-indexed).
@@ -244,7 +244,7 @@ class DirectorMixin:
             date_to: Filter mandates valid to this date (``"YYYY-MM-DD"``).
             as_of: Show mandates active on this date (``"YYYY-MM-DD"``).
             expiring_year: Keep only mandates expiring in the given year.
-            nature: Filter by compensation nature (``"REAL"`` or ``"POLITIC"``).
+            nature: Filter by compensation nature (``"real"`` or ``"politic"``).
             **kwargs: Advanced filters forwarded as query params.
 
         Returns:
@@ -293,7 +293,7 @@ class DirectorMixin:
         Args:
             director_uid: Director mandate UUID.
             fiscal_year: Filter by fiscal year.
-            nature: Filter by compensation nature (``"REAL"`` or ``"POLITIC"``).
+            nature: Filter by compensation nature (``"real"`` or ``"politic"``).
             page: Page number.
             page_size: Results per page.
 
@@ -356,7 +356,7 @@ class DirectorMixin:
         Args:
             director_uid: Director mandate UUID.
             fiscal_year: Fiscal year.
-            nature: Compensation nature (``"REAL"`` or ``"POLITIC"``).
+            nature: Compensation nature (``"real"`` or ``"politic"``).
             assembly: Assembly UUID.
             token_personal: Personal attendance tokens (decimal).
             token_personal_paid: Personal attendance tokens paid (decimal).

{boarddata-6.7.3 → boarddata-6.7.4}/_utilities.py

@@ -7,6 +7,7 @@ from typing import Any
 from .types.core import (
     CreateFieldSourceDisputePayload,
     FieldSourceDisputeDetail,
+    FieldSourceItem,
     SearchResult,
 )
 
@@ -70,7 +71,7 @@ class UtilitiesMixin:
         object_ids: list[str],
         *,
         fields: list[str] | None = None,
-    ) -> Any:
+    ) -> dict[str, dict[str, list[FieldSourceItem]]]:
         """Batch-fetch field sources for objects of a given content type.
 
         Args:
@@ -80,7 +81,7 @@ class UtilitiesMixin:
             fields: Optional list of field names to filter by.
 
         Returns:
-            Dict mapping ``object_id -> field_name -> list`` of source dicts.
+            Dict mapping ``object_id -> field_name -> list`` of FieldSourceItem dicts.
 
         Raises:
             BoardDataError: On non-2xx API response.

{boarddata-6.7.3 → boarddata-6.7.4}/boarddata.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boarddata
-Version: 6.7.3
+Version: 6.7.4
 Summary: Python SDK for the BoardData V2 REST API
 License: MIT
 Classifier: Development Status :: 4 - Beta

{boarddata-6.7.3 → boarddata-6.7.4}/boarddata.egg-info/SOURCES.txt

@@ -109,8 +109,10 @@ tests/test_esg.py
 tests/test_exports.py
 tests/test_indexes.py
 tests/test_persons.py
+tests/test_politic_fixture_conformance.py
 tests/test_risks.py
 tests/test_sentinel.py
+tests/test_types_politic.py
 tests/test_utilities.py
 types/__init__.py
 types/assemblies.py

{boarddata-6.7.3 → boarddata-6.7.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "boarddata"
-version = "6.7.3"
+version = "6.7.4"
 description = "Python SDK for the BoardData V2 REST API"
 readme = "README.md"
 license = {text = "MIT"}

{boarddata-6.7.3 → boarddata-6.7.4}/tests/test_comex.py

@@ -27,7 +27,7 @@ class TestCreateComexCompensation:
         c.create_comex_compensation(
             "comex-uuid",
             2024,
-            "REAL",
+            "real",
             fixed="500000.00",
             variable="200000.00",
             currency="EUR",
@@ -137,7 +137,7 @@ class TestReplaceComexCompensation:
         result = c.replace_comex_compensation(
             "comex-uuid",
             2024,
-            "REAL",
+            "real",
             fixed="500000.00",
             variable="200000.00",
             currency="EUR",
@@ -151,13 +151,13 @@ class TestReplaceComexCompensation:
         assert payload["variable"] == "200000.00"
         assert payload["currency"] == "EUR"
         assert payload["fiscal_year"] == 2024
-        assert payload["nature"] == "REAL"
+        assert payload["nature"] == "real"
         assert result == {"id": "comp9", "action": "replaced"}
 
     def test_returns_created_when_no_prior_row(self):
         c = make_client()
         c._request.return_value = {"id": "comp10", "action": "created"}
-        result = c.replace_comex_compensation("comex-uuid", 2024, "POLITIC", fixed="1.00")
+        result = c.replace_comex_compensation("comex-uuid", 2024, "politic", fixed="1.00")
         assert result["action"] == "created"
 
 
@@ -173,10 +173,15 @@ def test_envelope_scalar_kwargs_in_signatures():
         params = inspect.signature(method).parameters
         for k in (
             "sti_basis",
+            "variable_max",
+            "variable_target_pct",
+            "variable_max_pct",
             "variable_target_value",
             "variable_max_value",
+            "reference_amount",
             "lti_grant_cap_basis",
             "lti_grant_cap_value",
+            "policy_changed_midyear",
         ):
             assert k in params, f"{method.__name__} missing {k}"
 
@@ -201,3 +206,108 @@ def test_envelope_scalars_reach_the_wire():
     assert p["variable_max_value"] == "180"
     assert p["lti_grant_cap_basis"] == "pct_of_fixed"
     assert p["lti_grant_cap_value"] == "150"
+
+
+def test_politic_envelope_scalars_reach_the_wire():
+    c = make_client()
+    c._request.return_value = {"id": "1", "action": "created"}
+    c.replace_comex_compensation(
+        "uid",
+        2026,
+        "politic",
+        variable_max="2790000.00",
+        variable_target_pct="100.00",
+        variable_max_pct="180.00",
+        reference_amount="1400000.00",
+        policy_changed_midyear=False,
+    )
+    _, kwargs = c._request.call_args
+    p = kwargs["json"]
+    assert p["variable_max"] == "2790000.00"
+    assert p["variable_target_pct"] == "100.00"
+    assert p["variable_max_pct"] == "180.00"
+    assert p["reference_amount"] == "1400000.00"
+    # False is falsy but NOT None — it must reach the wire (only None is dropped).
+    assert p["policy_changed_midyear"] is False
+
+
+def test_nested_criteria_pass_through_verbatim():
+    """Nested entries are passthrough: the SDK must never filter, coerce, or
+    rename keys inside criteria / rates / field_sources dicts."""
+    c = make_client()
+    c._request.return_value = {"id": "1", "action": "created"}
+    criterion = {
+        "criteria": "cat-uuid",
+        "component_type": "variable",
+        "weight": "30.00",
+        "weight_basis": "share_of_fixed",
+        "weight_is_max": True,
+        "rate_basis": "points_of_fixed",
+        "min_value": "ROE <= 6%",
+        "max_value": "ROE >= 15%",
+        "payout_curve": {
+            "v": 1,
+            "curve_type": "linear_ramp",
+            "interpolation": "linear",
+            "rate_basis": "points_of_fixed",
+            "points": [
+                {"label": "floor", "metric_numeric": "6", "payout_pct": "0"},
+                {"label": "cap", "metric_numeric": "15", "payout_pct": "30"},
+            ],
+        },
+        "disclosure": {"weight": "numeric", "rate_max": "numeric"},
+        "field_sources": [
+            {
+                "document": "doc-uuid",
+                "field_name": "amount_at_max",
+                "page_number": 424,
+                "derivation": {
+                    "v": 1,
+                    "status": "derived",
+                    "formula_display": "€465,000 = 30% × €1,550,000",
+                    "inputs": [{"name": "fixed", "value": "1550000", "page": 424}],
+                },
+            }
+        ],
+    }
+    rate = {
+        "component_type": "variable",
+        "achievement_rate_max": "100.00",
+        "payout_curve": {
+            "v": 1,
+            "curve_type": "rank_scale",
+            "interpolation": "none",
+            "rate_basis": "points_of_fixed",
+            "points": [{"label": "rank_1", "payout_pct": "180"}],
+            "overlays": [{"kind": "cap", "factor": "100", "applies_to": "summary"}],
+        },
+    }
+    c.create_comex_compensation(
+        "uid",
+        2026,
+        "politic",
+        criteria=[criterion],
+        component_achievement_rates=[rate],
+    )
+    _, kwargs = c._request.call_args
+    p = kwargs["json"]
+    assert p["criteria"] == [criterion]
+    assert p["component_achievement_rates"] == [rate]
+
+
+def test_no_uppercase_nature_in_docstrings():
+    """The wire is lowercase; docstrings advertising "REAL"/"POLITIC" are the
+    latent casing bug fixed EVERYWHERE by the 6.7.0 politic parts (design
+    §4.7 / §2 item 9) — comex and directors both."""
+    import inspect
+
+    from boarddata._comex import ComexMixin
+    from boarddata._directors import DirectorMixin
+
+    offenders = []
+    for mixin in (ComexMixin, DirectorMixin):
+        for name, member in inspect.getmembers(mixin, inspect.isfunction):
+            doc = inspect.getdoc(member) or ""
+            if '"REAL"' in doc or '"POLITIC"' in doc:
+                offenders.append(f"{mixin.__name__}.{name}")
+    assert not offenders, offenders

{boarddata-6.7.3 → boarddata-6.7.4}/tests/test_directors.py

@@ -49,11 +49,11 @@ class TestCreateDirectorCompensation:
     def test_sends_token_fields(self):
         c = make_client()
         c._request.return_value = {"id": "comp1", "fiscal_year": 2024}
-        c.create_director_compensation("dir-uuid", 2024, "REAL", token_personal="15000.00", currency="EUR")
+        c.create_director_compensation("dir-uuid", 2024, "real", token_personal="15000.00", currency="EUR")
         _, kwargs = c._request.call_args
         payload = kwargs["json"]
         assert payload["token_personal"] == "15000.00"
-        assert payload["nature"] == "REAL"
+        assert payload["nature"] == "real"
         assert "fixed" not in payload  # comex field, not board
 
 

{boarddata-6.7.3 → boarddata-6.7.4}/tests/test_exports.py

@@ -152,10 +152,10 @@ class TestExportDirectors:
     def test_passes_filters(self):
         c = self._client()
         with patch("requests.request", return_value=_make_response(200, [])) as mock_req:
-            c.export_directors(company="comp-uuid", nature="REAL")
+            c.export_directors(company="comp-uuid", nature="real")
         _, kwargs = mock_req.call_args
         assert kwargs["params"]["company"] == "comp-uuid"
-        assert kwargs["params"]["nature"] == "REAL"
+        assert kwargs["params"]["nature"] == "real"
 
     def test_too_large_raises_export_too_large_error(self):
         c = self._client()
@@ -195,9 +195,9 @@ class TestExportComex:
     def test_passes_nature_filter(self):
         c = self._client()
         with patch("requests.request", return_value=_make_response(200, [])) as mock_req:
-            c.export_comex(nature="POLITIC")
+            c.export_comex(nature="politic")
         _, kwargs = mock_req.call_args
-        assert kwargs["params"]["nature"] == "POLITIC"
+        assert kwargs["params"]["nature"] == "politic"
 
     def test_too_large_raises_export_too_large_error(self):
         c = self._client()

boarddata-6.7.4/tests/test_politic_fixture_conformance.py

@@ -0,0 +1,116 @@
+"""TypedDict conformance of the nine §7 ground-truth archetype fixtures
+(design §4.8): every key the fixtures send must exist in the SDK's typed
+write vocabulary. Catches SDK/backend drift at the PR gate on either side.
+
+Runs only in the monorepo checkout (the fixtures are backend test data);
+skipped in a packaged install.
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+from pathlib import Path
+
+import pytest
+
+FIXTURES = Path(__file__).resolve().parents[2] / "backend/apps/mandates/tests/fixtures/politic_archetypes"
+
+pytestmark = pytest.mark.skipif(not FIXTURES.is_dir(), reason="backend fixtures only exist in the monorepo")
+
+# Keys the fixtures use for test scaffolding that are NOT wire keys.
+FIXTURE_ONLY_CRITERIA_KEYS = {"criteria_name"}  # resolved to a catalog PK by tests
+
+
+def _fixtures():
+    files = sorted(FIXTURES.glob("*.json"))
+    assert len(files) == 9, f"expected the nine archetypes, found {len(files)}"
+    return [json.loads(f.read_text()) for f in files]
+
+
+def _check_curve(curve, where):
+    from boarddata.types.comex import (
+        PayoutCurveEnvelope,
+        PayoutCurveOverlay,
+        PayoutCurvePayload,
+        PayoutCurvePoint,
+    )
+
+    unknown = set(curve) - set(PayoutCurvePayload.__annotations__)
+    assert not unknown, f"{where}: curve keys {sorted(unknown)}"
+    for i, pt in enumerate(curve.get("points", [])):
+        u = set(pt) - set(PayoutCurvePoint.__annotations__)
+        assert not u, f"{where} point[{i}]: {sorted(u)}"
+    for i, ov in enumerate(curve.get("overlays") or []):
+        u = set(ov) - set(PayoutCurveOverlay.__annotations__)
+        assert not u, f"{where} overlay[{i}]: {sorted(u)}"
+    for i, env in enumerate(curve.get("envelopes") or []):
+        u = set(env) - set(PayoutCurveEnvelope.__annotations__)
+        assert not u, f"{where} envelope[{i}]: {sorted(u)}"
+
+
+def _check_disclosure(disc, where):
+    from boarddata.types.comex import DisclosureMap
+
+    unknown = set(disc) - set(DisclosureMap.__annotations__)
+    assert not unknown, f"{where}: disclosure keys {sorted(unknown)}"
+
+
+def test_envelope_keys_map_to_signature_params():
+    from boarddata import BoardDataClient
+
+    params = set(inspect.signature(BoardDataClient.create_comex_compensation).parameters)
+    for fx in _fixtures():
+        unknown = set(fx.get("envelope", {})) - params
+        assert not unknown, f"{fx['isin']}: envelope keys {sorted(unknown)}"
+
+
+def test_criteria_keys_are_typed():
+    from boarddata.types.comex import CriterionWritePayload
+
+    typed = set(CriterionWritePayload.__annotations__)
+    for fx in _fixtures():
+        for i, crit in enumerate(fx.get("criteria", [])):
+            unknown = set(crit) - typed - FIXTURE_ONLY_CRITERIA_KEYS
+            assert not unknown, f"{fx['isin']} criteria[{i}]: {sorted(unknown)}"
+            if crit.get("payout_curve"):
+                _check_curve(crit["payout_curve"], f"{fx['isin']} criteria[{i}]")
+            if crit.get("disclosure"):
+                _check_disclosure(crit["disclosure"], f"{fx['isin']} criteria[{i}]")
+
+
+def test_rate_keys_are_typed():
+    from boarddata.types.comex import ComponentAchievementRateWritePayload
+
+    typed = set(ComponentAchievementRateWritePayload.__annotations__)
+    for fx in _fixtures():
+        for i, rate in enumerate(fx.get("component_achievement_rates", [])):
+            unknown = set(rate) - typed
+            assert not unknown, f"{fx['isin']} rate[{i}]: {sorted(unknown)}"
+            if rate.get("payout_curve"):
+                _check_curve(rate["payout_curve"], f"{fx['isin']} rate[{i}]")
+            if rate.get("disclosure"):
+                _check_disclosure(rate["disclosure"], f"{fx['isin']} rate[{i}]")
+
+
+def test_field_source_keys_are_typed():
+    from boarddata.types.core import (
+        DerivationInput,
+        DerivationPayload,
+        FieldSourcePayload,
+    )
+
+    fs_typed = set(FieldSourcePayload.__annotations__)
+    d_typed = set(DerivationPayload.__annotations__)
+    i_typed = set(DerivationInput.__annotations__)
+    for fx in _fixtures():
+        for i, fs in enumerate(fx.get("field_sources", [])):
+            unknown = set(fs) - fs_typed
+            assert not unknown, f"{fx['isin']} field_sources[{i}]: {sorted(unknown)}"
+            der = fs.get("derivation")
+            if der:
+                u = set(der) - d_typed
+                assert not u, f"{fx['isin']} field_sources[{i}].derivation: {sorted(u)}"
+                for j, inp in enumerate(der.get("inputs", [])):
+                    u = set(inp) - i_typed
+                    assert not u, f"{fx['isin']} field_sources[{i}].derivation.inputs[{j}]: {sorted(u)}"