spanforge 2.0.0__py3-none-any.whl

spanforge/ulid.py

@@ -0,0 +1,304 @@
+"""Zero-dependency ULID (Universally Unique Lexicographically Sortable Identifier).
+
+Specification: https://github.com/ulid/spec
+
+Format (26 Crockford Base32 characters, 128 bits)
+--------------------------------------------------
+::
+
+    01ARZ3NDEKTSV4RRFFQ69G5FAV
+    ├──────────┤├────────────────┤
+     Timestamp (ms)   Random (80 bits)
+     48 bits, 10 chars  16 chars
+
+Properties
+----------
+* **Lexicographically sortable** — events can be sorted by ULID without parsing
+  the timestamp field.
+* **Monotonic within the same millisecond** — the random component is
+  incremented rather than regenerated when two ULIDs are requested within the
+  same millisecond clock tick, preserving ordering.
+* **URL and filename safe** — only uppercase alphanumerics (Crockford Base32).
+* **Zero external dependencies** — uses only :mod:`os` and :mod:`time`.
+
+Security note
+-------------
+The random component is seeded from :func:`os.urandom` (CSPRNG), making ULIDs
+safe for use as non-guessable identifiers in audit chains.
+
+Performance note
+----------------
+The module-level :class:`_ULIDGenerator` instance is thread-safe via the GIL
+for standard CPython but is explicitly protected with :class:`threading.Lock`
+for correctness on alternative runtimes and as documentation of intent.
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+import time
+from typing import Final
+
+from spanforge.exceptions import ULIDError
+
+__all__ = ["ULID_REGEX", "generate", "validate"]
+
+# ---------------------------------------------------------------------------
+# Crockford Base32 alphabet (excludes I, L, O, U to avoid confusion)
+# ---------------------------------------------------------------------------
+_ALPHABET: Final[str] = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+_ALPHABET_LEN: Final[int] = 32  # exactly 2^5 — one char encodes 5 bits
+
+# Pre-compute a decode lookup table for O(1) character → value conversion.
+_DECODE: Final[dict[str, int]] = {ch: idx for idx, ch in enumerate(_ALPHABET)}
+
+# Extra entries for lowercase and visually-similar characters (I/L/O/U).
+_DECODE.update({ch.lower(): idx for ch, idx in _DECODE.items()})
+_DECODE.update({"i": 1, "I": 1, "l": 1, "L": 1, "o": 0, "O": 0})
+
+# Strict charset for validation — excludes I/L/O/U aliases (generate() never
+# emits them; validate() must reject them for canonical-form compliance).
+_VALID_CHARS: Final[frozenset[str]] = frozenset(_ALPHABET + _ALPHABET.lower())
+
+ULID_LENGTH: Final[int] = 26
+# RFC-0001 §6.3 — first character must be 0-7 (timestamp MSBs, max value
+# «0111» ensures the 48-bit timestamp fits in 10 Crockford characters).
+ULID_REGEX: Final[str] = r"^[0-7][0-9A-HJKMNP-TV-Z]{25}$"
+
+_MAX_TIMESTAMP: Final[int] = (1 << 48) - 1  # 281 474 976 710 655 ms
+
+# ---------------------------------------------------------------------------
+# Monotonic generator
+# ---------------------------------------------------------------------------
+
+
+class _ULIDGenerator:
+    """Stateful generator that guarantees monotonicity within one millisecond.
+
+    When two calls are made within the same millisecond, the random segment is
+    incremented by 1, preserving lexicographic ordering.  If the random segment
+    would overflow (2**80) clock advancement is waited for.
+    """
+
+    __slots__ = ("_last_ms", "_last_rand", "_lock")
+
+    _rand_max: Final[int] = (1 << 80) - 1  # type: ignore[misc]
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._last_ms: int = 0
+        self._last_rand: int = 0
+
+    # ------------------------------------------------------------------
+    # Public interface
+    # ------------------------------------------------------------------
+
+    def generate(self) -> str:
+        """Return a new ULID string.
+
+        Raises:
+            ULIDError: If the system clock is not monotonic or the random source
+                is exhausted (astronomically unlikely).
+        """
+        ms, rand = self._next_ms_rand()
+        return _encode_ulid(ms, rand)
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    def _next_ms_rand(self) -> tuple[int, int]:
+        """Return (timestamp_ms, random_int) ensuring monotonic ordering."""
+        with self._lock:
+            ms = _now_ms()
+
+            if ms > self._last_ms:
+                # New millisecond — fresh random segment.
+                rand = _secure_random_80()
+                self._last_ms = ms
+                self._last_rand = rand
+                return ms, rand
+
+            if ms == self._last_ms:
+                # Same millisecond — increment random to preserve ordering.
+                next_rand = self._last_rand + 1
+                if next_rand > self._rand_max:
+                    # Overflow — spin until the clock advances.
+                    ms = _spin_until_next_ms(ms)
+                    next_rand = _secure_random_80()
+                    self._last_ms = ms
+                self._last_rand = next_rand
+                return ms, next_rand
+
+            # Clock went backwards — still safe: we use last_ms + increment.
+            next_rand = self._last_rand + 1
+            if next_rand > self._rand_max:
+                raise ULIDError(
+                    "Random segment overflow with backwards clock — "
+                    "cannot guarantee monotonicity"
+                )
+            self._last_rand = next_rand
+            return self._last_ms, next_rand
+
+
+# ---------------------------------------------------------------------------
+# Module-level helpers
+# ---------------------------------------------------------------------------
+
+
+def _now_ms() -> int:
+    """Return current Unix time in milliseconds as an integer."""
+    return int(time.time() * 1_000)
+
+
+def _secure_random_80() -> int:
+    """Return 80 cryptographically-secure random bits as an integer."""
+    return int.from_bytes(os.urandom(10), "big")
+
+
+def _spin_until_next_ms(current_ms: int) -> int:
+    """Wait until the clock advances past *current_ms*, with a 1-second deadline.
+
+    Raises:
+        ULIDError: If the system clock does not advance within 1 second (e.g.
+            clock is frozen or running backwards).
+    """
+    deadline = time.monotonic() + 1.0
+    while True:
+        ms = _now_ms()
+        if ms > current_ms:
+            return ms
+        if time.monotonic() > deadline:
+            raise ULIDError(
+                "Clock did not advance within 1 s — possible system clock freeze"
+            )
+        # Yield CPU so other threads can run and the OS clock can tick.
+        time.sleep(0.001)
+
+
+def _encode_ulid(timestamp_ms: int, random_int: int) -> str:
+    """Encode (timestamp_ms, random_int) into a 26-character ULID string.
+
+    Args:
+        timestamp_ms: 48-bit millisecond timestamp.
+        random_int:   80-bit random value.
+
+    Returns:
+        26-character Crockford Base32 ULID string (uppercase).
+
+    Raises:
+        ULIDError: If timestamp_ms exceeds the 48-bit maximum.
+    """
+    if timestamp_ms > _MAX_TIMESTAMP:
+        raise ULIDError(
+            f"Timestamp {timestamp_ms} ms exceeds ULID maximum "
+            f"({_MAX_TIMESTAMP} ms ≈ year 10889)"
+        )
+
+    # Encode timestamp — 10 characters (50 bits needed; 48 used)
+    ts_chars = [""] * 10
+    t = timestamp_ms
+    for i in range(9, -1, -1):
+        ts_chars[i] = _ALPHABET[t & 0x1F]
+        t >>= 5
+
+    # Encode random — 16 characters (80 bits)
+    rand_chars = [""] * 16
+    r = random_int
+    for i in range(15, -1, -1):
+        rand_chars[i] = _ALPHABET[r & 0x1F]
+        r >>= 5
+
+    return "".join(ts_chars) + "".join(rand_chars)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+_generator = _ULIDGenerator()
+
+
+def generate() -> str:
+    """Generate a new ULID string.
+
+    The returned value is:
+
+    * 26 characters long
+    * Composed of Crockford Base32 characters (``[0-9A-HJKMNP-TV-Z]``)
+    * Lexicographically sortable (earlier ULIDs < later ULIDs as strings)
+    * Monotonic within the same millisecond
+    * Seeded from :func:`os.urandom` (CSPRNG)
+
+    Returns:
+        A 26-character uppercase ULID string.
+
+    Raises:
+        ULIDError: On the astronomically unlikely event of internal state
+            overflow or backwards-clock exhaustion.
+
+    Example::
+
+        from spanforge.ulid import generate
+        event_id = generate()  # "01ARYZ3NDEKTSV4RRFFQ69G5FAV"
+    """
+    return _generator.generate()
+
+
+def validate(value: str) -> bool:
+    """Return ``True`` if *value* is a syntactically valid ULID string.
+
+    Validation checks:
+
+    1. Exactly 26 characters long.
+    2. All characters are in the Crockford Base32 alphabet (case-insensitive,
+       I/L/O treated as 1/1/0).
+    3. The timestamp component does not overflow the 48-bit range.
+
+    Args:
+        value: The string to validate.
+
+    Returns:
+        ``True`` if valid, ``False`` otherwise.
+
+    Example::
+
+        validate("01ARYZ3NDEKTSV4RRFFQ69G5FAV")  # True
+        validate("not-a-ulid")                     # False
+    """
+    if not isinstance(value, str) or len(value) != ULID_LENGTH:
+        return False
+    upper = value.upper()
+    if not all(c in _VALID_CHARS for c in upper):
+        return False
+    # Decode timestamp and check range
+    t = 0
+    for ch in upper[:10]:
+        t = (t << 5) | _DECODE[ch]
+    return t <= _MAX_TIMESTAMP
+
+
+def extract_timestamp_ms(ulid: str) -> int:
+    """Extract the embedded millisecond timestamp from a ULID.
+
+    Args:
+        ulid: A valid 26-character ULID string.
+
+    Returns:
+        Unix timestamp in milliseconds.
+
+    Raises:
+        ULIDError: If *ulid* is not a valid ULID.
+
+    Example::
+
+        ms = extract_timestamp_ms("01ARYZ3NDEKTSV4RRFFQ69G5FAV")
+        print(datetime.utcfromtimestamp(ms / 1000))
+    """
+    if not validate(ulid):
+        raise ULIDError(f"Cannot extract timestamp from invalid ULID: {ulid!r}")
+    t = 0
+    for ch in ulid.upper()[:10]:
+        t = (t << 5) | _DECODE[ch]
+    return t

spanforge/validate.py

@@ -0,0 +1,383 @@
+"""spanforge.validate — JSON Schema validation for Event envelopes.
+
+This module validates :class:`~spanforge.event.Event` instances against the
+published JSON Schema specification. Schema version is selected automatically
+from the event's ``schema_version`` field:
+
+* ``"1.0"`` → ``schemas/v1.0/schema.json``
+* ``"2.0"`` (default) → ``schemas/v2.0/schema.json``
+
+It uses the optional ``jsonschema`` library when available for full Draft 2020-12
+validation.  If ``jsonschema`` is not installed, a lightweight structural check
+is performed using only the Python standard library — external dependencies are
+strictly optional in line with *spanforge*'s zero-required-dependency policy.
+
+Usage
+-----
+::
+
+    from spanforge import Event, EventType
+    from spanforge.validate import validate_event
+
+    event = Event(
+        event_type=EventType.TRACE_SPAN_COMPLETED,
+        source="llm-trace@0.3.1",
+        payload={"span_name": "run", "status": "ok"},
+    )
+    validate_event(event)   # raises SchemaValidationError if invalid
+
+Public API
+----------
+* :func:`validate_event` — validate an :class:`~spanforge.event.Event`
+  against the matching envelope schema (version-aware).
+* :func:`load_schema` — load a specific schema version by key.
+* :exc:`~spanforge.exceptions.SchemaValidationError` — raised on validation
+  failure (re-exported from :mod:`spanforge.exceptions`).
+"""
+
+from __future__ import annotations
+
+import json
+import pathlib
+import re
+from typing import Any
+
+from spanforge.event import Event
+from spanforge.exceptions import EventTypeError, SchemaValidationError
+from spanforge.types import is_registered, validate_custom
+
+__all__: list[str] = ["load_schema", "validate_event"]
+
+# ---------------------------------------------------------------------------
+# Schema paths — version-aware (RFC-0001 §15.5)
+# ---------------------------------------------------------------------------
+
+_SCHEMAS_DIR: pathlib.Path = pathlib.Path(__file__).parent / "schemas"
+
+#: Map of schema-version strings to their JSON Schema file paths.
+_SCHEMA_PATHS: dict[str, pathlib.Path] = {
+    "1.0": _SCHEMAS_DIR / "v1.0" / "schema.json",
+    "2.0": _SCHEMAS_DIR / "v2.0" / "schema.json",
+}
+
+#: Default (current) schema version (RFC-0001-SPANFORGE-Enterprise-2.0).
+_DEFAULT_SCHEMA_VERSION: str = "2.0"
+
+# Legacy single-path alias kept for backwards-compatible callers.
+_SCHEMA_PATH: pathlib.Path = _SCHEMA_PATHS["1.0"]
+
+# ---------------------------------------------------------------------------
+# Compiled patterns from schema (stdlib fallback)
+# ---------------------------------------------------------------------------
+
+# RFC-0001 §6.3 — first char 0-7 (timestamp MSB constraint)
+_ULID_RE: re.Pattern[str] = re.compile(r"^[0-7][0-9A-HJKMNP-TV-Z]{25}$")
+# RFC-0001 §15.5 — only 1.0 and 2.0 are accepted schema versions.
+_ACCEPTED_SCHEMA_VERSIONS: frozenset[str] = frozenset({"1.0", "2.0"})
+_EVENT_TYPE_RE: re.Pattern[str] = re.compile(
+    r"^(?:llm\.(?:trace|cost|cache|eval|guard|fence|prompt|redact|diff|template|audit)\.(?:[a-z][a-z0-9_]*|[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*)|(?!llm\.)[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)+\.[a-z][a-z0-9_]*\.[a-z][a-z0-9_]*)$"  # NOSONAR — RFC §7 grammar with registered llm namespaces
+)
+# RFC-0001 §6.1 — microsecond precision mandatory (exactly 6 decimal places)
+_TIMESTAMP_RE: re.Pattern[str] = re.compile(
+    r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{6}Z$"
+)
+# RFC-0001 §5.1 — source: letter start, letters/digits/._-, then @semver
+_SOURCE_RE: re.Pattern[str] = re.compile(
+    r"^[a-zA-Z][a-zA-Z0-9._\-]*@\d+\.\d+\.\d+(?:[.\-][a-zA-Z0-9.]+)?$"
+)
+_TRACE_ID_RE: re.Pattern[str] = re.compile(r"^[0-9a-f]{32}$")
+_SPAN_ID_RE: re.Pattern[str] = re.compile(r"^[0-9a-f]{16}$")
+# Checksum and signature carry distinct prefix indicators set by signing.py.
+_CHECKSUM_RE: re.Pattern[str] = re.compile(r"^sha256:[0-9a-f]{64}$")
+_SIGNATURE_RE: re.Pattern[str] = re.compile(r"^hmac-sha256:[0-9a-f]{64}$")
+_MAX_TAG_KEYS: int = 50
+
+# RFC-0001 §6.3 — ULID max length is 26 characters; 1 MB payload cap.
+_MAX_EVENT_ID_LEN: int = 26
+_MAX_PAYLOAD_BYTES: int = 1_000_000
+
+# ---------------------------------------------------------------------------
+# Schema loader
+# ---------------------------------------------------------------------------
+
+_CACHED_SCHEMAS: dict[str, dict[str, Any]] = {}
+
+# Legacy alias kept for call sites that used the old single-schema API.
+_CACHED_SCHEMA: dict[str, Any] | None = None
+
+
+def load_schema(version: str | None = None) -> dict[str, Any]:
+    """Load and cache a JSON Schema from disk by version.
+
+    Parameters
+    ----------
+    version:
+        Schema version string, e.g. ``"1.0"`` or ``"2.0"``.
+        Defaults to the current SDK schema version (``"2.0"``; RFC §15.5).
+
+    Returns:
+    -------
+    dict
+        Parsed JSON Schema as a plain Python dict.
+
+    Raises:
+    ------
+    FileNotFoundError
+        If the requested schema file cannot be found relative to the
+        package root.  This should never happen in a correctly installed
+        distribution.
+    ValueError
+        If an unknown schema version is requested.
+    """
+    resolved = version or _DEFAULT_SCHEMA_VERSION
+    if resolved in _CACHED_SCHEMAS:
+        return _CACHED_SCHEMAS[resolved]
+
+    # RFC-0001 §15.5: unknown schema versions MUST raise and stop processing.
+    path = _SCHEMA_PATHS.get(resolved)
+    if path is None:
+        raise ValueError(
+            f"Unknown schema version {resolved!r}. "
+            f"Available versions: {list(_SCHEMA_PATHS)}"
+        )
+
+    if not path.is_file():
+        raise FileNotFoundError(
+            f"JSON Schema not found at {path}.  "
+            "Ensure the 'schemas/' directory is included in the "
+            "installed package."
+        )
+    with path.open("r", encoding="utf-8") as fh:
+        schema = json.load(fh)
+    _CACHED_SCHEMAS[resolved] = schema
+    return schema
+
+
+# ---------------------------------------------------------------------------
+# Internal: stdlib structural validation
+# ---------------------------------------------------------------------------
+
+
+def _check_string_field(
+    doc: dict[str, Any],
+    field: str,
+    *,
+    required: bool = True,
+    pattern: re.Pattern[str] | None = None,
+    min_length: int = 1,
+) -> None:
+    """Validate a single string field in *doc*."""
+    if field not in doc:
+        if required:
+            raise SchemaValidationError(
+                field=field,
+                received=None,
+                reason=f"required field '{field}' is missing",
+            )
+        return
+    value = doc[field]
+    if not isinstance(value, str):
+        raise SchemaValidationError(
+            field=field,
+            received=value,
+            reason=f"'{field}' must be a string",
+        )
+    if len(value) < min_length:
+        raise SchemaValidationError(
+            field=field,
+            received=value,
+            reason=f"'{field}' must be at least {min_length} character(s)",
+        )
+    if pattern is not None and not pattern.match(value):
+        raise SchemaValidationError(
+            field=field,
+            received=value,
+            reason=f"'{field}' does not match pattern {pattern.pattern!r}",
+        )
+
+
+def _validate_tags(tags: Any) -> None:
+    """Validate the tags dict; raise SchemaValidationError on any violation."""
+    if not isinstance(tags, dict):
+        raise SchemaValidationError(
+            field="tags",
+            received=tags,
+            reason="'tags' must be an object",
+        )
+    if len(tags) > _MAX_TAG_KEYS:
+        raise SchemaValidationError(
+            field="tags",
+            received=tags,
+            reason=f"'tags' must contain at most {_MAX_TAG_KEYS} keys",
+        )
+    for k, v in tags.items():
+        if not isinstance(k, str) or not k:
+            raise SchemaValidationError(
+                field=f"tags.{k!r}",
+                received=k,
+                reason="tag key must be a non-empty string",
+            )
+        if not isinstance(v, str) or not v:
+            raise SchemaValidationError(
+                field=f"tags.{k}",
+                received=v,
+                reason="tag value must be a non-empty string",
+            )
+
+
+def _stdlib_validate(doc: dict[str, Any]) -> None:
+    """Perform structural validation without the ``jsonschema`` library.
+
+    Checks required fields, types, and regex patterns as per the published
+    JSON Schema spec.  Raises :exc:`~spanforge.exceptions.SchemaValidationError`
+    on the first violation found.
+    """
+    if not isinstance(doc, dict):
+        raise SchemaValidationError(
+            field="<root>",
+            received=doc,
+            reason="event must serialise to a JSON object",
+        )
+
+    _check_string_field(doc, "schema_version")
+    if doc["schema_version"] not in _ACCEPTED_SCHEMA_VERSIONS:
+        raise SchemaValidationError(
+            field="schema_version",
+            received=doc["schema_version"],
+            reason=f"'schema_version' must be one of {sorted(_ACCEPTED_SCHEMA_VERSIONS)!r}",
+        )
+    _check_string_field(doc, "event_id", pattern=_ULID_RE)
+    _check_string_field(doc, "event_type", pattern=_EVENT_TYPE_RE)
+    if not is_registered(doc["event_type"]):
+        try:
+            validate_custom(doc["event_type"])
+        except EventTypeError as exc:
+            raise SchemaValidationError(
+                field="event_type",
+                received=doc["event_type"],
+                reason=str(exc),
+            ) from exc
+    _check_string_field(doc, "timestamp", pattern=_TIMESTAMP_RE)
+    _check_string_field(doc, "source", pattern=_SOURCE_RE)
+
+    # payload
+    if "payload" not in doc:
+        raise SchemaValidationError(
+            field="payload",
+            received=None,
+            reason="required field 'payload' is missing",
+        )
+    if not isinstance(doc["payload"], dict) or not doc["payload"]:
+        raise SchemaValidationError(
+            field="payload",
+            received=doc["payload"],
+            reason="'payload' must be a non-empty object",
+        )
+
+    # Optional tracing fields
+    for span_field in ("span_id", "parent_span_id"):
+        _check_string_field(doc, span_field, required=False, pattern=_SPAN_ID_RE)
+    _check_string_field(doc, "trace_id", required=False, pattern=_TRACE_ID_RE)
+
+    # Optional context fields
+    for ctx_field in ("org_id", "team_id", "actor_id", "session_id"):
+        _check_string_field(doc, ctx_field, required=False, min_length=1)
+
+    # Optional integrity fields — checksum and signature use distinct prefix patterns.
+    _check_string_field(doc, "checksum", required=False, pattern=_CHECKSUM_RE)
+    _check_string_field(doc, "signature", required=False, pattern=_SIGNATURE_RE)
+    _check_string_field(doc, "prev_id", required=False, pattern=_ULID_RE)
+
+    # tags
+    if "tags" in doc:
+        _validate_tags(doc["tags"])
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def validate_event(event: Event) -> None:
+    """Validate *event* against the published v1.0 JSON Schema.
+
+    Serialises *event* to a plain dict and validates the envelope structure.
+    When the optional ``jsonschema`` package is installed, full Draft 2020-12
+    validation is performed.  Otherwise a stdlib-only structural check is run
+    that covers all required fields, types, and regex patterns.
+
+    Parameters
+    ----------
+    event:
+        The :class:`~spanforge.event.Event` instance to validate.
+
+    Raises:
+    ------
+    SchemaValidationError
+        If the event does not conform to the envelope schema.
+    FileNotFoundError
+        If the schema file is missing from the installed distribution.
+
+    Examples:
+    --------
+    ::
+
+        from spanforge import Event, EventType
+        from spanforge.validate import validate_event
+
+        event = Event(
+            event_type=EventType.TRACE_SPAN_COMPLETED,
+            source="llm-trace@0.3.1",
+            payload={"span_name": "run", "status": "ok"},
+        )
+        validate_event(event)  # passes silently
+    """
+    if not isinstance(event, Event):
+        raise TypeError(f"validate_event() expects an Event instance, got {type(event)!r}")
+
+    doc = event.to_dict()
+
+    # H9: bound-check event_id length and payload wire size before schema validation.
+    event_id_val: str = doc.get("event_id", "")
+    if len(event_id_val) > _MAX_EVENT_ID_LEN:
+        raise SchemaValidationError(
+            field="event_id",
+            received=event_id_val,
+            reason=(
+                f"event_id length {len(event_id_val)} exceeds maximum "
+                f"{_MAX_EVENT_ID_LEN} characters"
+            ),
+        )
+    _payload_bytes = len(json.dumps(doc.get("payload", {}), default=str).encode())
+    if _payload_bytes > _MAX_PAYLOAD_BYTES:
+        raise SchemaValidationError(
+            field="payload",
+            received=None,
+            reason=(
+                f"payload size {_payload_bytes} bytes exceeds maximum "
+                f"{_MAX_PAYLOAD_BYTES} bytes"
+            ),
+        )
+
+    # Select schema version from event envelope (RFC §15.5).
+    schema_version: str = doc.get("schema_version") or _DEFAULT_SCHEMA_VERSION
+
+    try:
+        import jsonschema  # noqa: PLC0415  (optional import)
+        import jsonschema.exceptions  # noqa: PLC0415
+
+        schema = load_schema(schema_version)
+        try:
+            jsonschema.validate(instance=doc, schema=schema)
+        except jsonschema.exceptions.ValidationError as exc:
+            # Convert jsonschema's error into our domain error.
+            field_path = ".".join(str(part) for part in exc.absolute_path) or "<root>"
+            raise SchemaValidationError(
+                field=field_path,
+                received=exc.instance,
+                reason=exc.message,
+            ) from exc
+
+    except ImportError:
+        # jsonschema not installed — fall back to stdlib structural check.
+        _stdlib_validate(doc)