sdmxlib 0.45.0__tar.gz → 0.46.0__tar.gz

{sdmxlib-0.45.0 → sdmxlib-0.46.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: sdmxlib
-Version: 0.45.0
+Version: 0.46.0
 Summary: SDMX structural metadata library for Python
 Keywords: sdmx,statistics,metadata,datastructure
 Author: gabrielgellner
@@ -16,7 +16,7 @@ Requires-Dist: attrs>=26.1.0
 Requires-Dist: duckdb>=1.5.3
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: lxml>=6.0.2
-Requires-Dist: orjson>=3.9
+Requires-Dist: msgspec>=0.19
 Requires-Dist: polars>=1.39.3
 Requires-Dist: pyarrow>=18.0.0
 Requires-Python: >=3.13

{sdmxlib-0.45.0 → sdmxlib-0.46.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sdmxlib"
-version = "0.45.0"
+version = "0.46.0"
 description = "SDMX structural metadata library for Python"
 readme = "README.md"
 license = { text = "Apache-2.0" }
@@ -24,7 +24,7 @@ dependencies = [
     "duckdb>=1.5.3",
     "httpx>=0.28.1",
     "lxml>=6.0.2",
-    "orjson>=3.9",
+    "msgspec>=0.19",
     "polars>=1.39.3",
     "pyarrow>=18.0.0",
 ]
@@ -83,11 +83,28 @@ typeCheckingMode = "standard"
 # we *don't* care about are tests.
 reportUnusedCallResult = false
 
+# Strict-mode rules that ARE clean on this codebase (0 findings), turned on
+# to catch regressions the flood-prone `reportUnknown*` rules would bury.
+# The first two are basedpyright's Any-degradation catchers — the closest it
+# gets to pyrefly's `implicit-any` family without the duckdb/pyarrow noise:
+#   * reportMissingTypeArgument — a bare generic (`list` not `list[str]`) → Any.
+#   * reportMissingParameterType — an untyped parameter → Any.
+# The rest are pure hardening: dead casts (aligns with "narrow, don't cast"),
+# getter/setter type drift, __init__/__new__ disagreement, mutable-default
+# gotchas, and always-true/false `in` checks.
+reportMissingTypeArgument = "error"
+reportMissingParameterType = "error"
+reportUnnecessaryCast = "error"
+reportPropertyTypeMismatch = "error"
+reportInconsistentConstructor = "error"
+reportCallInDefaultInitializer = "error"
+reportUnnecessaryContains = "error"
+
 [dependency-groups]
 dev = [
   "basedpyright>=1.38.4",
   "catppuccin[pygments]>=2.5.0",
-  "lxml-stubs>=0.5.1",
+  "types-lxml>=2025.3.30",
   "mkdocs-material>=9.7.6",
   "mkdocstrings[python]>=1.0.3",
   "polars>=1.39.3",

{sdmxlib-0.45.0 → sdmxlib-0.46.0}/src/sdmxlib/__init__.py

@@ -90,6 +90,7 @@ from sdmxlib.model import (
     MeasureDimension,
     MetadataAttribute,
     MetadataMessage,
+    MetadataProvisionAgreement,
     MetadataSection,
     MetadataSet,
     MetadataStructure,
@@ -199,6 +200,7 @@ __all__ = [
     "MemberValue",
     "MetadataAttribute",
     "MetadataMessage",
+    "MetadataProvisionAgreement",
     "MetadataSection",
     "MetadataSet",
     "MetadataStructure",

sdmxlib-0.46.0/src/sdmxlib/_duckdb.py

@@ -0,0 +1,22 @@
+"""Private DuckDB helpers shared by the storage layer and model query DSLs.
+
+Lives at the package root because both ``storage/`` and the model query DSLs
+(``code_query``, ``hierarchy_query``) need it, and neither layer may import the
+other.
+"""
+
+from __future__ import annotations
+
+import duckdb
+
+
+def count(cursor: duckdb.DuckDBPyConnection) -> int:
+    """Return the integer in the first cell of the cursor's first row, or 0.
+
+    The ``__len__`` helper for ``SELECT COUNT(*)`` queries: centralises the
+    ``row = cur.fetchone(); row[0] if row else 0`` idiom. Generalise to a typed
+    ``scalar[T](cursor, *, default: T) -> T`` if a non-count scalar read ever
+    appears.
+    """
+    row = cursor.fetchone()
+    return int(row[0]) if row is not None else 0

{sdmxlib-0.45.0 → sdmxlib-0.46.0}/src/sdmxlib/api/federated.py

@@ -35,6 +35,8 @@ from typing import TYPE_CHECKING
 import httpx
 
 from sdmxlib.api.policy import FailurePolicy, RegistryUnavailable
+from sdmxlib.model.binding import DriftError, _validate_binding
+from sdmxlib.model.urn import SdmxUrn
 
 if TYPE_CHECKING:
     from sdmxlib.model.binding import DataflowBinding, DriftIssue
@@ -140,8 +142,6 @@ class FederatedRegistry:
         Like the underlying Registry membership: never triggers a network
         round-trip. ``False`` if no source is routed for the URN's agency.
         """
-        from sdmxlib.model.urn import SdmxUrn  # noqa: PLC0415
-
         if not isinstance(urn, SdmxUrn):
             return False
         source = self._route(urn)
@@ -158,8 +158,6 @@ class FederatedRegistry:
         want to enumerate or display drift; use ``validate_binding()``
         when you want to raise on any drift.
         """
-        from sdmxlib.model.binding import _validate_binding  # noqa: PLC0415
-
         return _validate_binding(binding, self)
 
     def validate_binding(self, binding: "DataflowBinding") -> None:
@@ -171,8 +169,6 @@ class FederatedRegistry:
             DriftError: If any drift is detected. ``error.issues`` carries
                 the full accumulated list.
         """
-        from sdmxlib.model.binding import DriftError  # noqa: PLC0415
-
         issues = self.check_binding_drift(binding)
         if issues:
             raise DriftError(issues)

{sdmxlib-0.45.0 → sdmxlib-0.46.0}/src/sdmxlib/api/query.py

@@ -1,5 +1,6 @@
 """GetQuery[T], Query[T], and DataQuery — artefact and data queries."""
 
+import tempfile
 from collections.abc import Callable
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Self
@@ -396,8 +397,6 @@ class DataQuery:
         Example:
             reg.data(flow).measures(["EMP", "UNE"]).pivot_to("wide.parquet")
         """
-        import tempfile  # noqa: PLC0415
-
         suffix = ".csv"
         with tempfile.NamedTemporaryFile(suffix=suffix, delete=False) as tmp:
             tmp_path = Path(tmp.name)

{sdmxlib-0.45.0 → sdmxlib-0.46.0}/src/sdmxlib/api/registry.py

@@ -11,11 +11,12 @@ from sdmxlib.api.providers import ProviderInfo
 from sdmxlib.api.query import DataQuery, GetQuery, Query, _KeySpec
 from sdmxlib.api.session import Session
 from sdmxlib.formats import parse as _parse
+from sdmxlib.model.binding import DriftError, _validate_binding
 from sdmxlib.model.dataflow import Dataflow
 from sdmxlib.model.dataset import Dataset
 from sdmxlib.model.datastructure import DataStructure
 from sdmxlib.model.message import StructureMessage
-from sdmxlib.model.ref import Ref
+from sdmxlib.model.ref import Ref, SupportsUrn
 from sdmxlib.model.registry import InMemoryRegistry
 from sdmxlib.model.urn import SdmxUrn
 
@@ -300,12 +301,10 @@ class RestRegistry:
         if cached is None:
             return None
         # Warm the in-process state. Some artefacts (e.g. LazyCodelist) don't
-        # satisfy HasUrn cleanly; in that case skip in-memory interning while
+        # satisfy SupportsUrn cleanly; skip in-memory interning for those while
         # keeping Session caching.
-        import contextlib  # noqa: PLC0415
-
         self._session._map[str(urn)] = cached  # noqa: SLF001
-        with contextlib.suppress(TypeError):
+        if isinstance(cached, SupportsUrn):
             self._registry.add(cached)
         return cached
 
@@ -671,7 +670,7 @@ class RestRegistry:
         it is streamed straight to the file, and the returned Dataset's
         ``LazyFrame`` is scanned from disk.
         """
-        from sdmxlib.formats.sdmx_csv.reader import scan_csv  # noqa: PLC0415
+        from sdmxlib.formats.sdmx_csv.reader import scan_csv  # noqa: PLC0415  # lazy: defer CSV import
 
         dataflow_ref = Ref.to(spec.dataflow) if spec.dataflow is not None else None
         if to is None:
@@ -718,7 +717,11 @@ class RestRegistry:
                 ds = reg.scan_csv("ecb_exr.csv")
                 df = ds.collect(with_labels=True, lang="en")
         """
-        from sdmxlib.formats.sdmx_csv.reader import _peek_dataflow_id, parse_dataflow_id, scan_csv  # noqa: PLC0415
+        from sdmxlib.formats.sdmx_csv.reader import (  # noqa: PLC0415  # lazy: defer CSV import
+            _peek_dataflow_id,
+            parse_dataflow_id,
+            scan_csv,
+        )
 
         dataflow_str = _peek_dataflow_id(source)
         if dataflow_str is None:
@@ -755,8 +758,6 @@ class RestRegistry:
         when you want to enumerate or display drift; use
         ``validate_binding()`` when you want to raise on any drift.
         """
-        from sdmxlib.model.binding import _validate_binding  # noqa: PLC0415
-
         return _validate_binding(binding, self)
 
     def validate_binding(self, binding: "DataflowBinding") -> None:
@@ -768,8 +769,6 @@ class RestRegistry:
             DriftError: If any drift is detected. ``error.issues`` carries
                 the full accumulated list.
         """
-        from sdmxlib.model.binding import DriftError  # noqa: PLC0415
-
         issues = self.check_binding_drift(binding)
         if issues:
             raise DriftError(issues)

{sdmxlib-0.45.0 → sdmxlib-0.46.0}/src/sdmxlib/api/session.py

@@ -1,7 +1,6 @@
 """Session — identity map and artefact construction."""
 
-from typing import Any
-
+from sdmxlib.model.collections import Maintainable
 from sdmxlib.model.message import StructureMessage
 from sdmxlib.model.urn import SdmxUrn
 
@@ -37,10 +36,15 @@ class Session:
     """
 
     def __init__(self) -> None:
-        self._map: dict[str, Any] = {}
-        self._latest: dict[str, Any] = {}
-        self._resolved_map: dict[str, Any] = {}
-        self._resolved_latest: dict[str, Any] = {}
+        # ``_map``/``_resolved_map`` only store + return-via-get (the unsafe
+        # object→T narrowing is localized to ``get``), so ``object`` suffices
+        # and admits the registry-cache path that writes an unbounded ``T``.
+        # ``_latest``/``_resolved_latest`` are compared on ``.version``, so
+        # they carry the checked `Maintainable` type.
+        self._map: dict[str, object] = {}
+        self._latest: dict[str, Maintainable] = {}
+        self._resolved_map: dict[str, object] = {}
+        self._resolved_latest: dict[str, Maintainable] = {}
         self._class_tomsg_field: dict[str, str] = {}
 
     def ingest(self, msg: StructureMessage, *, resolved: bool = False) -> None:

{sdmxlib-0.45.0 → sdmxlib-0.46.0}/src/sdmxlib/formats/__init__.py

@@ -126,6 +126,7 @@ def serialize(
     *,
     version: str = "2.1",
     pretty_print: bool = False,
+    validate: bool = False,
 ) -> bytes:
     """Serialise a Structure or Metadata message to bytes.
 
@@ -136,12 +137,22 @@ def serialize(
     - ``MetadataMessage`` → ``<mes:GenericMetadata>`` envelope (XML) or
       metadata ``$schema`` (JSON).
 
+    Serialisation and validation are separate concerns: this function
+    serialises. Pass ``validate=True`` to run `validate_message` first and
+    refuse to emit a structurally invalid message, or call `validate_message`
+    yourself. The default skips it — messages built through the typed model or
+    read back by the parser are already well-formed, and re-validating on every
+    write is wasted work.
+
     Args:
         msg: The message to serialise.
         version: Wire format — ``"2.1"`` (default), ``"3.0"`` (SDMX-ML XML),
             or ``"json"`` (SDMX-JSON 2.0). MetadataMessage requires ``"3.0"``
             or ``"json"`` (SDMX-ML 2.1 GenericMetadata is out of scope).
         pretty_print: If True, indent the output.
+        validate: If True, `validate_message` runs first and raises
+            ``ValidationError`` (accumulated across all artefacts) before any
+            bytes are produced. Default False.
     """
     if isinstance(msg, MetadataMessage):
         if version == "json":
@@ -151,9 +162,9 @@ def serialize(
         err = f"MetadataMessage cannot be serialised as {version!r} (use '3.0' or 'json')"
         raise ValueError(err)
 
-    # Refuse to emit structurally invalid ids on the wire. Validation is
-    # accumulated across every artefact so all problems surface at once.
-    validate_message(msg)
+    if validate:
+        # Accumulated across every artefact so all problems surface at once.
+        validate_message(msg)
 
     if version == "json":
         return _write_json(msg, pretty_print=pretty_print)
@@ -167,20 +178,29 @@ def serialize(
     raise ValueError(err)
 
 
-def to_xml(msg: "StructureMessage | MetadataMessage", *, version: str = "2.1", pretty_print: bool = False) -> bytes:
+def to_xml(
+    msg: "StructureMessage | MetadataMessage",
+    *,
+    version: str = "2.1",
+    pretty_print: bool = False,
+    validate: bool = False,
+) -> bytes:
     """Serialise a Structure or Metadata message to SDMX-ML XML bytes.
 
     MetadataMessage requires ``version="3.0"`` (SDMX-ML 2.1 GenericMetadata
-    is intentionally not supported).
+    is intentionally not supported). See `serialize` for ``validate``.
     """
     if isinstance(msg, MetadataMessage) and version != "3.0":
         version = "3.0"
-    return serialize(msg, version=version, pretty_print=pretty_print)
+    return serialize(msg, version=version, pretty_print=pretty_print, validate=validate)
 
 
-def to_json(msg: "StructureMessage | MetadataMessage", *, pretty_print: bool = False) -> bytes:
-    """Serialise a Structure or Metadata message to SDMX-JSON 2.0 bytes."""
-    return serialize(msg, version="json", pretty_print=pretty_print)
+def to_json(msg: "StructureMessage | MetadataMessage", *, pretty_print: bool = False, validate: bool = False) -> bytes:
+    """Serialise a Structure or Metadata message to SDMX-JSON 2.0 bytes.
+
+    See `serialize` for ``validate``.
+    """
+    return serialize(msg, version="json", pretty_print=pretty_print, validate=validate)
 
 
 def _detect_version(data: bytes) -> str:

{sdmxlib-0.45.0 → sdmxlib-0.46.0}/src/sdmxlib/formats/sdmx_json/_data_common.py

@@ -16,7 +16,6 @@ import re
 from datetime import datetime, timedelta
 from typing import TYPE_CHECKING, Any, Literal, NamedTuple, cast
 
-import orjson
 import polars as pl
 
 if TYPE_CHECKING:
@@ -24,11 +23,13 @@ if TYPE_CHECKING:
 
     from sdmxlib.model.annotations import Annotations
     from sdmxlib.model.binding import DataflowBinding
-    from sdmxlib.model.datastructure import DataStructure
+    from sdmxlib.model.datastructure import DataStructure, Dimension
     from sdmxlib.model.istring import InternationalString
 
 from sdmxlib.model.ref import Ref
 
+from ._dto import ENCODER
+
 ComponentKind = Literal["dimension", "attribute"]
 
 
@@ -176,7 +177,7 @@ def _annotation_duration(annotations: Annotations, lang: str) -> _Duration | Non
     return None
 
 
-def _frequency_dimension(dsd: DataStructure) -> Any:
+def _frequency_dimension(dsd: DataStructure) -> Dimension | None:
     """The DSD's frequency dimension, by well-known id then concept role."""
     for dim in dsd.dimensions:
         if dim.id in ("FREQ", "FREQUENCY"):
@@ -357,10 +358,14 @@ class ComponentTable:
         `_resolve_time_bounds` can pick each period's duration from the
         frequencies it actually co-occurs with.
         """
-        if not self.tracks_freq() or self._time_dim_id not in dim_cols or self._freq_dim_id not in dim_cols:
+        # Bind to locals so the None-guard narrows `str | None` → `str` for the
+        # `dim_cols.index(...)` calls below (equivalent to `tracks_freq()`, but
+        # the method call can't narrow the attributes).
+        time_id, freq_id = self._time_dim_id, self._freq_dim_id
+        if time_id is None or freq_id is None or time_id not in dim_cols or freq_id not in dim_cols:
             return
-        time_col = dim_phys[dim_cols.index(self._time_dim_id)]
-        freq_col = dim_phys[dim_cols.index(self._freq_dim_id)]
+        time_col = dim_phys[dim_cols.index(time_id)]
+        freq_col = dim_phys[dim_cols.index(freq_id)]
         pairs = df.select(
             pl.col(time_col).cast(pl.String).fill_null("").alias("__t"),
             pl.col(freq_col).cast(pl.String).fill_null("").alias("__f"),
@@ -433,7 +438,8 @@ class ComponentTable:
                 # Attribute schema (both 1.0 and 2.0) requires a relationship.
                 # We currently only emit observation-level attributes, so the
                 # relationship is the empty observation marker.
-                entry["relationship"] = {"observation": {}}
+                observation_marker: dict[str, object] = {}
+                entry["relationship"] = {"observation": observation_marker}
             out.append(entry)
         return out
 
@@ -479,7 +485,7 @@ def encode_batch(
 
     Hot path: column-oriented Polars work for the things that vectorise
     (key string construction, attribute position lookups) and one
-    orjson.dumps over the whole batch's ``{key: row}`` dict. The
+    msgspec encode over the whole batch's ``{key: row}`` dict. The
     surrounding ``{}`` braces are stripped because the caller is
     splicing this chunk into a streamed object whose braces it owns.
 
@@ -538,11 +544,13 @@ def encode_batch(
                 row.append(None if raw is None else attr_int_tables[col_idx][str(raw)])
             rows.append(row)
 
-    # ── Step 4: one orjson.dumps over the whole batch, strip braces ──
+    # ── Step 4: one msgspec encode over the whole batch, strip braces ──
     # ``{key1:[...], key2:[...], ...}`` with the leading ``{`` and
     # trailing ``}`` removed becomes a valid chunk to splice into the
-    # caller's streamed observations map.
-    payload = orjson.dumps(dict(zip(keys, rows, strict=True)), option=orjson.OPT_SERIALIZE_NUMPY)
+    # caller's streamed observations map. Polars ``.to_list()`` already
+    # yields Python-native scalars (int/float/str/None), so no numpy
+    # encode hook is needed (#179).
+    payload = ENCODER.encode(dict(zip(keys, rows, strict=True)))
     body = payload[1:-1]  # strip outer { and }
     if first_obs or not body:
         return body
@@ -551,7 +559,7 @@ def encode_batch(
 
 def dataflow_link(binding: DataflowBinding) -> bytes:
     """Serialise the dataSet ``links[]`` entry pointing at the bound dataflow."""
-    return orjson.dumps(
+    return ENCODER.encode(
         {
             "urn": str(binding.dataflow.urn),
             "rel": "dataflow",
@@ -686,7 +694,7 @@ def decode_observations(
     observations = dataset_block.get("observations") or {}
     rows: list[list[Any]] = []
     for key, value_array in observations.items():
-        positions = key.split(":") if key else []
+        positions: list[str] = key.split(":") if key else []
         if len(positions) != len(obs_dim_ids):
             msg = (
                 f"Observation key {key!r} has {len(positions)} positions but "

sdmxlib-0.46.0/src/sdmxlib/formats/sdmx_json/_dto.py

@@ -0,0 +1,208 @@
+"""Shared SDMX-JSON 2.0 wire Structs and helpers (msgspec).
+
+Foundation of the msgspec migration (milestone: SDMX-JSON dict+orjson →
+typed msgspec Structs). Holds the cross-cutting wire types every artefact DTO
+reuses — annotations, links, the message ``meta`` envelope — plus the
+``InternationalString`` ↔ ``(name, names)`` convention, the annotation
+convert helpers, and the shared encoder. The per-artefact DTOs (Codelist,
+DataStructure, …) live in the writer/reader modules and build on these.
+
+Conventions for wire Structs — read before adding one
+-----------------------------------------------------
+
+- **Inherit `WireStruct`.** It carries ``omit_defaults=True`` + ``gc=False``
+  for every DTO (add ``rename=_camel_rename`` in the subclass when the wire
+  wants camelCase). ``gc=False`` opts these transient, tree-shaped structs out
+  of the cyclic collector — a large encode speedup — and is safe only because
+  wire DTOs never form reference cycles (see `WireStruct`).
+
+- **``omit_defaults=True``** (from `WireStruct`): a field whose value equals
+  its default is skipped on encode, matching SDMX-JSON's "omit optional when
+  absent".
+
+- **A field that must ALWAYS appear on the wire is REQUIRED — no default.**
+  This is the subtle one. With ``omit_defaults`` a field equal to its default
+  is *dropped*; if you give an artefact's ``version`` a default of ``"1.0"`` it
+  silently vanishes whenever the value is ``"1.0"``. So ``id`` / ``agencyID`` /
+  ``version`` and any other always-present field must be declared without a
+  default (required). ``test_dto.py`` locks this with a guard test.
+
+- **Unknown fields are ignored on decode** (msgspec's default) — forward-
+  compatible with producer extensions.
+
+- **Wire names that differ from Python** use ``rename=`` (e.g. ``agencyID``).
+
+- **An ``InternationalString`` splits into ``name: str`` (primary /
+  default-language) + ``names: dict[str, str]`` (full map)** per the SDMX-JSON
+  2.0 contract. Use `emit_istr` / `ingest_istr` — never hand-roll the split.
+  Annotations use the same pattern under ``text`` / ``texts``.
+"""
+
+from __future__ import annotations
+
+import msgspec
+
+from sdmxlib.model.annotations import Annotation as _ModelAnnotation
+from sdmxlib.model.annotations import Annotations
+from sdmxlib.model.istring import InternationalString
+
+# Sentinel language used when a producer sends a singular ``name`` with no
+# ``names`` map — we can't know the real language tag, so we mirror the
+# dict-reader's behaviour and key it under ``_default``.
+_DEFAULT_LANG = "_default"
+
+
+# ── Wire-name convention ─────────────────────────────────────────────────────
+# Struct fields are snake_case; `rename=_camel_rename` maps them to the SDMX-JSON
+# camelCase wire names (msgspec's equivalent of pydantic's alias_generator).
+
+
+def _camel_rename(name: str) -> str:
+    """snake_case field → SDMX-JSON wire name.
+
+    camelCase, except ``agency_id`` → ``agencyID`` (the SDMX-IM acronym).
+    Matches msgspec's built-in ``"camel"`` for every other field. msgspec calls
+    this once per field at class definition.
+    """
+    if name == "agency_id":
+        return "agencyID"
+    head, *tail = name.split("_")
+    return head + "".join(w[:1].upper() + w[1:] for w in tail)
+
+
+# ── InternationalString ↔ (name, names) ─────────────────────────────────────
+
+
+def emit_istr(v: InternationalString | None) -> tuple[str | None, dict[str, str] | None]:
+    """Split an ``InternationalString`` into ``(primary, full map)`` for a Struct.
+
+    Returns ``(None, None)`` for an empty/absent istring so ``omit_defaults``
+    drops both the singular and plural fields. Delegates to
+    `InternationalString.emit_pair`, which does the empty-check + best-match +
+    backing-map fetch in one call (the map is shared, not copied: it feeds a
+    transient DTO that msgspec encodes and we then discard, so it is never
+    mutated).
+    """
+    return v.emit_pair() if v is not None else (None, None)
+
+
+def ingest_istr(name: str | None, names: dict[str, str] | None) -> dict[str, str]:
+    """Reconstruct a lang→text map from a wire ``(name, names)`` pair.
+
+    Prefers the full ``names`` map. Falls back to ``{_DEFAULT_LANG: name}`` when
+    only the singular ``name`` is present (a producer that omitted ``names``),
+    mirroring the dict-reader. Empty when neither is present. The caller builds
+    an ``InternationalString`` from the result.
+    """
+    if names:
+        return names
+    if name:
+        return {_DEFAULT_LANG: name}
+    return {}
+
+
+# ── Wire Struct base ─────────────────────────────────────────────────────────
+
+
+class WireStruct(msgspec.Struct, omit_defaults=True, gc=False):
+    """Base for every SDMX-JSON wire DTO.
+
+    Carries the two config knobs every DTO wants:
+
+    - ``omit_defaults=True`` — a field equal to its default is skipped on encode
+      (matches SDMX-JSON's "omit optional when absent"). Subclasses that also
+      need camelCase wire names add ``rename=_camel_rename``; it composes with
+      this base's config down the MRO.
+    - ``gc=False`` — opt these structs out of CPython's *cyclic* collector.
+      Reference counting still frees them promptly (they are transient: built
+      per-serialise, encoded, discarded), so nothing leaks; skipping cyclic-GC
+      tracking removes the dominant cost of building millions of them.
+
+    Invariant that makes ``gc=False`` safe: **wire DTOs are trees** — parent →
+    children only, built fresh from the (acyclic) domain model, never holding a
+    back-reference to an ancestor or sibling. A reference *cycle* would leak
+    under ``gc=False`` (refcounting alone can't break one). Do not introduce
+    one.
+    """
+
+
+class Link(WireStruct):
+    """A SDMX-JSON ``links[*]`` entry. Annotation URLs ride here under ``rel=self``."""
+
+    href: str = ""
+    rel: str = ""
+
+
+class Annotation(WireStruct):
+    """SDMX-JSON 2.0 ``annotations[*]``. ``text``/``texts`` carry the localised body."""
+
+    id: str | None = None
+    title: str | None = None
+    type: str | None = None
+    text: str | None = None
+    texts: dict[str, str] | None = None
+    #: The annotation URL lives in ``links`` under ``rel="self"``; a bare ``url``
+    #: is tolerated on decode for non-conformant producers.
+    url: str | None = None
+    links: list[Link] | None = None
+
+
+class Sender(WireStruct):
+    """The ``meta.sender`` object."""
+
+    id: str = ""
+
+
+class Meta(WireStruct):
+    """The SDMX-JSON ``meta`` envelope object."""
+
+    id: str = ""
+    prepared: str = ""
+    sender: Sender | None = None
+
+
+# ── Annotation ↔ model ───────────────────────────────────────────────────────
+
+
+def emit_annotations(annotations: Annotations | None) -> list[Annotation] | None:
+    """Model ``Annotations`` → wire ``list[Annotation]``, or ``None`` when empty."""
+    if not annotations:
+        return None
+    out: list[Annotation] = []
+    for a in annotations:
+        text, texts = emit_istr(a.text)
+        links = [Link(rel="self", href=a.url)] if a.url else None
+        out.append(Annotation(id=a.id, title=a.title, type=a.type, text=text, texts=texts, links=links))
+    return out
+
+
+def _annotation_url(a: Annotation) -> str | None:
+    """The annotation URL from its ``links`` (``rel="self"``), or the bare ``url``."""
+    if a.links:
+        for link in a.links:
+            if link.rel == "self" and link.href:
+                return link.href
+    return a.url
+
+
+def ingest_annotations(annotations: list[Annotation] | None) -> Annotations:
+    """Wire ``list[Annotation]`` → model ``Annotations``."""
+    if not annotations:
+        return Annotations()
+    return Annotations(
+        [
+            _ModelAnnotation(
+                id=a.id,
+                title=a.title,
+                type=a.type,
+                url=_annotation_url(a),
+                text=ingest_istr(a.text, a.texts),
+            )
+            for a in annotations
+        ]
+    )
+
+
+# ── Shared encoder ───────────────────────────────────────────────────────────
+# One reusable encoder; decode is per-type via ``msgspec.json.decode(data, type=T)``.
+ENCODER = msgspec.json.Encoder()