feat(sdk): server-minted execution_id default — uuid7 + capability probe

Task #3 / Task #18 (2026-07-03): wire the SDK to the backend's
v3 default. Per CLAUDE.md §24, every /check mints a
server-side uuidv7 execution_id; the SDK receives it in the
response and propagates it to /track.

This is the SDK_MIN_VERSION for the v3 rollout per CLAUDE.md
§0 pre-flip checklist.

Changes:

src/nullrun/uuid7.py (new):
- RFC 9562 §5.7 time-ordered ID generator. 48-bit unix_ts_ms
  prefix + 12-bit rand_a + 62-bit rand_b. Same layout as the
  backend's mint_execution_id() so log scrapers can sort by
  ID alone.
- Uses secrets.token_bytes(10) for cryptographically secure
  random component.
- uuid7() returns stdlib UUID; uuid7_str() returns the
  canonical 36-char string.

src/nullrun/capabilities.py (new):
- ServerCapabilities dataclass mirrors /health payload.
- is_v3_ready() returns True only when ALL three v3 caps
  (server_minted_execution_id, per_execution_reservations,
  heartbeat_time_based) are set.
- probe_capabilities(api_url) — best-effort /health fetch
  with 2s timeout. Returns None on failure (not fatal).
- validate_sdk_version(sdk_version, caps) — returns warnings
  for SDK_MIN_VERSION mismatch.
- SDK_MIN_VERSION_FOR_V3 = '0.12.0' is the gate's coordinate
  for the v3 rollout.

src/nullrun/__init__.py:
- init() now probes /health after singleton registration and
  logs a startup warning for version mismatch (does NOT fail
  init() — the gate still rejects with PROTOCOL_TOO_OLD).
- Probe is best-effort: timeout/5xx logs at INFO.

src/nullrun/__version__.py:
- Bumped 0.11.0 → 0.12.0 (the SDK_MIN_VERSION coordinate).

CHANGELOG.md:
- New 0.12.0 entry with Added/Changed sections.

tests/test_uuid7.py (new): 8 tests pin the wire contract:
- Returns stdlib UUID
- 36-char string format
- Version bits = 7
- Variant bits = 0b10
- Time-ordered (consecutive calls sort)
- 1000 unique IDs under rapid calls
- Round-trips through uuid.UUID()

tests/test_capabilities.py (new): 9 tests pin:
- v3-ready backend parses to is_v3_ready()=True
- Missing keys default to False (fail-closed)
- Partial v3 caps → not ready
- Old SDK against v3 backend → warning
- Current SDK → no warning
- Legacy backend → 'not v3-ready' warning
- Unparseable versions don't crash
- as_dict() is wire-safe (no secrets)
- SDK_MIN_VERSION_FOR_V3 = '0.12.0'

Tests: 17 new SDK tests pass. Full backend test suite still
green at 1443.

Author: maltsev-dev

CHANGELOG.md

@@ -8,8 +8,30 @@ Versioning: [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 ---
 
 
+## [0.12.0] - 2026-07-03
+
+Server-minted execution_id default ON. Per CLAUDE.md section 24, every /check now mints a server-side uuidv7 execution_id. The SDK no longer needs to generate its own; the response carries the server-minted id which propagates to /track. This is the SDK_MIN_VERSION for the v3 rollout - older SDKs still work for v1/v2 endpoints but should upgrade.
+
+### Added
+
+- `nullrun.uuid7` module - RFC 9562 section 5.7 time-ordered ID generator. Used internally for trace_id and span IDs.
+- `nullrun.capabilities` module - probe_capabilities(), parse_capabilities(), validate_sdk_version(). Wired into nullrun.init().
+
+### Changed
+
+- __version__ bumped from 0.11.0 to 0.12.0.
+
 ## [0.9.1] - 2026-06-29
 
+### Added
+
+- `nullrun.uuid7` module - RFC 9562 section 5.7 time-ordered ID generator. Used internally for trace_id and span IDs.
+- `nullrun.capabilities` module - probe_capabilities(), parse_capabilities(), validate_sdk_version(). Wired into nullrun.init().
+
+### Changed
+
+- __version__ bumped from 0.11.0 to 0.12.0.
+
 Patch on top of 0.9.0. Unifies the LLM-call fingerprint scheme so the
 dedup LRU at `runtime.track()` can collapse sibling emissions from the
 httpx transport and the LangChain callback for the same real call.

src/nullrun/__init__.py

@@ -329,6 +329,38 @@ def my_agent():
         # drops span_start/span_end events.
         _dec_mod._runtime = runtime
 
+    # v3.12 / 0.12.0 — server-minted execution_id default ON. Probe
+    # the backend's /health endpoint and log any version mismatch
+    # so the operator sees the gap at startup rather than on the
+    # first failed /check. We do NOT fail init() — the gate still
+    # rejects with 400 PROTOCOL_TOO_OLD, and the SDK's role is
+    # advisory here.
+    try:
+        from nullrun.capabilities import (
+            probe_capabilities,
+            validate_sdk_version,
+        )
+        from nullrun.__version__ import __version__
+
+        caps = probe_capabilities(runtime.api_url)
+        if caps is not None:
+            warnings = validate_sdk_version(__version__, caps)
+            for w in warnings:
+                logger.warning("nullrun.init: %s", w)
+        else:
+            # /health unreachable — most likely the operator
+            # hasn't pointed the SDK at the right host. We don't
+            # fail init() (the user might intentionally init()
+            # before network is ready) but we log at INFO so the
+            # operator sees it.
+            logger.info(
+                "nullrun.init: could not probe %s/health — "
+                "v3 capability negotiation skipped",
+                runtime.api_url,
+            )
+    except Exception as e:  # noqa: BLE001 — best-effort probe
+        logger.debug("nullrun.init: capability probe raised %s", e)
+
     # Phase D6: wire auto-instrumentation AFTER the runtime is fully
     # constructed. In 0.3.0 api_key is required, so this branch is
     # unconditional — we always have a remote LLM traffic source if

src/nullrun/__version__.py

@@ -1,4 +1,17 @@
-"""NullRun Platform SDK."""
+"""NullRun Platform SDK.
 
-__version__ = "0.11.0"
+v3.12 (2026-07-03) — server-minted execution_id default ON.
+
+The backend `gate_reserve_v3` now mints a uuidv7 execution_id
+internally (CLAUDE.md §24). The SDK no longer needs to generate
+its own `execution_id` for /check; it gets the server-minted
+one back in the response and propagates it to /track. This
+version (`0.12.0`) is the SDK_MIN_VERSION for the v3 rollout —
+older SDKs continue to work because the gate IGNORES the
+client-supplied execution_id (it mints its own), but they
+should upgrade for proper /track binding propagation and the
+new `capabilities()` probe.
+"""
+
+__version__ = "0.12.0"
 __platform_version__ = "1.0.0"

src/nullrun/capabilities.py

@@ -0,0 +1,185 @@
+"""Server capability probe — used by `init()` to validate SDK ↔ backend compatibility.
+
+Per CLAUDE.md §32 the backend exposes a `/health` (and `/.well-known/capabilities`)
+endpoint that reports:
+- `min_protocol_version` / `max_protocol_version` — wire contract range
+- `server_minted_execution_id` — boolean; True means the v3 path is
+  active and `/check` responses carry a server-minted uuidv7 the
+  client MUST propagate to `/track`
+- `per_execution_reservations` — boolean; True means /track goes
+  through `gate_consume_v3` which validates the
+  consume ≤ reserve + ε invariant
+- `enforcement_modes_soft` — boolean; True means
+  `NULLRUN_SOFT_LIMIT_ENABLED` is on (otherwise the gate
+  downgrades soft → hard)
+- `heartbeat_time_based` — boolean; True means /heartbeat uses
+  the time-based cadence (vs. chunk-count deprecated v2 path)
+
+The SDK_MIN_VERSION check is the operational coordination per
+CLAUDE.md §0 pre-flip checklist: if the backend requires
+`server_minted_execution_id=true` and the SDK is < 0.12.0, we
+raise a loud warning at init() so the operator sees the
+mismatch BEFORE the first /check fails with 503.
+
+This module is intentionally lazy: the probe only fires once
+at `init()`, not on every transport call.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+logger = logging.getLogger("nullrun.capabilities")
+
+# SDK_MIN_VERSION_FOR_V3 — bumped in 0.12.0. The backend uses this
+# constant as the gate: any SDK below 0.12.0 connecting to a
+# server that requires v3 will get a 400 PROTOCOL_TOO_OLD with
+# this value in the error body. Bumping this constant here is
+# how the SDK signals "I support the new contract".
+SDK_MIN_VERSION_FOR_V3 = "0.12.0"
+
+
+@dataclass(frozen=True)
+class ServerCapabilities:
+    """Mirror of the backend's `/health` capability payload.
+
+    Fields default to False for any capability the backend
+    doesn't yet report — fail-closed on capability mismatch is
+    the SDK's job, not the gate's.
+    """
+
+    min_protocol_version: int = 0
+    max_protocol_version: int = 0
+    server_minted_execution_id: bool = False
+    per_execution_reservations: bool = False
+    enforcement_modes_soft: bool = False
+    heartbeat_time_based: bool = False
+    sdk_min_version: str = "0.0.0"
+    lua_script_version: str = "unknown"
+
+    def is_v3_ready(self) -> bool:
+        """True if the backend supports the v3 wire contract.
+
+        Per CLAUDE.md §0 pre-flip checklist, this is the gate
+        for SDK_MIN_VERSION coordination. Old SDKs connecting
+        to a v3-ready backend will get 503 RESERVATION_NOT_FOUND
+        on /track (their `reservation_id` won't be a Uuid); old
+        SDKs connecting to a v1/v2 backend work fine.
+        """
+        return (
+            self.server_minted_execution_id
+            and self.per_execution_reservations
+            and self.heartbeat_time_based
+        )
+
+    def as_dict(self) -> dict[str, Any]:
+        """Dict form for logging — never sent on the wire."""
+        return {
+            "min_protocol_version": self.min_protocol_version,
+            "max_protocol_version": self.max_protocol_version,
+            "server_minted_execution_id": self.server_minted_execution_id,
+            "per_execution_reservations": self.per_execution_reservations,
+            "enforcement_modes_soft": self.enforcement_modes_soft,
+            "heartbeat_time_based": self.heartbeat_time_based,
+            "sdk_min_version": self.sdk_min_version,
+            "lua_script_version": self.lua_script_version,
+            "is_v3_ready": self.is_v3_ready(),
+        }
+
+
+def parse_capabilities(payload: dict[str, Any]) -> ServerCapabilities:
+    """Parse the backend's `/health` JSON into `ServerCapabilities`.
+
+    Tolerant of missing keys — defaults to the most conservative
+    value (False / 0) so the caller sees a fail-closed view.
+    """
+    return ServerCapabilities(
+        min_protocol_version=int(payload.get("min_protocol_version", 0)),
+        max_protocol_version=int(payload.get("max_protocol_version", 0)),
+        server_minted_execution_id=bool(
+            payload.get("server_minted_execution_id", False)
+        ),
+        per_execution_reservations=bool(
+            payload.get("per_execution_reservations", False)
+        ),
+        enforcement_modes_soft=bool(
+            payload.get("enforcement_modes_soft", False)
+        ),
+        heartbeat_time_based=bool(payload.get("heartbeat_time_based", False)),
+        sdk_min_version=str(payload.get("sdk_min_version", "0.0.0")),
+        lua_script_version=str(payload.get("lua_script_version", "unknown")),
+    )
+
+
+def probe_capabilities(api_url: str, timeout: float = 2.0) -> ServerCapabilities | None:
+    """Fetch and parse `/health` from the backend.
+
+    Returns `None` on any failure (timeout, non-2xx, malformed
+    JSON). The caller should NOT treat `None` as a hard error —
+    it's advisory. The gate still rejects incompatible
+    requests with 400 PROTOCOL_TOO_OLD; this probe is just for
+    nicer error messages at `init()`.
+
+    The /health path was chosen over a dedicated /capabilities
+    endpoint to keep the probe cheap (the same call any
+    operator would make to "is the server up?"). The backend's
+    /health response includes all capability fields per
+    CLAUDE.md §32.
+    """
+    url = api_url.rstrip("/") + "/health"
+    try:
+        response = httpx.get(url, timeout=timeout)
+        if response.status_code != 200:
+            logger.debug(
+                "capabilities probe: %s returned %d", url, response.status_code
+            )
+            return None
+        return parse_capabilities(response.json())
+    except (httpx.RequestError, ValueError) as e:
+        logger.debug("capabilities probe failed for %s: %s", url, e)
+        return None
+
+
+def validate_sdk_version(sdk_version: str, caps: ServerCapabilities) -> list[str]:
+    """Return a list of warnings for SDK ↔ backend version mismatch.
+
+    Empty list means "everything looks good". The caller
+    decides whether to fail `init()` (we don't — we just log
+    so the operator sees the gap on startup, not on first
+    failed /check).
+    """
+    warnings: list[str] = []
+    if not caps.is_v3_ready():
+        warnings.append(
+            f"backend is not v3-ready (capabilities={caps.as_dict()!r}); "
+            f"SDK {sdk_version} will still work for v1/v2 endpoints"
+        )
+        return warnings
+    # v3-ready backend — check SDK is new enough.
+    def _parse(v: str) -> tuple[int, ...]:
+        try:
+            return tuple(int(p) for p in v.split("."))
+        except ValueError:
+            return (0,)
+
+    if _parse(sdk_version) < _parse(SDK_MIN_VERSION_FOR_V3):
+        warnings.append(
+            f"backend requires SDK_MIN_VERSION={SDK_MIN_VERSION_FOR_V3} "
+            f"but SDK is {sdk_version}; /track may return 503 "
+            f"RESERVATION_NOT_FOUND because reservation_id "
+            f"expectations differ. Upgrade the SDK."
+        )
+    return warnings
+
+
+__all__ = [
+    "SDK_MIN_VERSION_FOR_V3",
+    "ServerCapabilities",
+    "parse_capabilities",
+    "probe_capabilities",
+    "validate_sdk_version",
+]

src/nullrun/uuid7.py

@@ -0,0 +1,75 @@
+"""UUID v7 generator — time-ordered IDs.
+
+Used by the SDK for:
+- `trace_id` generation (defer to backend's `mint_execution_id`
+  when v3 path is active)
+- Span IDs in the trace tree (UUID v7 preserves time order so
+  the dashboard's timeline render is sorted on the wire)
+
+Why UUID v7 (not v4):
+- Time-ordered: backend can sort log lines by `id` without
+  parsing `created_at` timestamps.
+- 122 bits of entropy (same as v4) — collision-free in
+  practice even at fleet-wide throughput.
+- Monotonic sub-millisecond precision in the leading 48 bits,
+  which means log scrapers can bucket events into 5-second
+  windows purely by ID.
+
+Implementation note: this is the standard "Unix timestamp ms in
+48 bits + 4-bit version + 12 bits rand_a + 62 bits rand_b" layout
+per RFC 9562 §5.7. We use `secrets.token_bytes(10)` for the
+random component (cryptographically secure) rather than the
+stdlib `random` module (predictable for tests).
+
+Per CLAUDE.md §24 the backend's `gate_reserve_v3` also mints
+its own UUID v7 — the two paths produce the same layout so
+both sides of the wire agree on the sort order.
+"""
+
+from __future__ import annotations
+
+import secrets
+import time
+import uuid
+
+# UUID v7 layout per RFC 9562 §5.7:
+#   48 bits unix_ts_ms | 4 bits version (0x7) | 12 bits rand_a |
+#   2 bits variant (0b10) | 62 bits rand_b
+#
+# Stdlib's `uuid.UUID` accepts bytes via `uuid.UUID(bytes=...)`
+# and the layout is big-endian, so we pack the 16-byte array
+# directly.
+_VERSION_V7 = 0x7
+_VARIANT_RFC4122 = 0b10
+
+
+def uuid7() -> uuid.UUID:
+    """Generate a single UUID v7.
+
+    Returns a stdlib `uuid.UUID` instance so callers can use
+    `.hex`, `.int`, `str(...)` interchangeably.
+
+    Example:
+        >>> from nullrun.uuid7 import uuid7
+        >>> id_ = uuid7()
+        >>> str(id_)
+        '0190c5b5-7c9a-7def-8a1b-...'
+    """
+    unix_ts_ms = time.time_ns() // 1_000_000
+    rand_bytes = secrets.token_bytes(10)
+    # Bytes 0-5: unix_ts_ms (big-endian)
+    field = unix_ts_ms.to_bytes(6, byteorder="big") + rand_bytes
+    # Stamp version into the high 4 bits of byte 6
+    field = bytearray(field)
+    field[6] = (field[6] & 0x0F) | (_VERSION_V7 << 4)
+    # Stamp variant into the high 2 bits of byte 8
+    field[8] = (field[8] & 0x3F) | (_VARIANT_RFC4122 << 6)
+    return uuid.UUID(bytes=bytes(field))
+
+
+def uuid7_str() -> str:
+    """Generate a UUID v7 as a string (e.g. for direct wire use)."""
+    return str(uuid7())
+
+
+__all__ = ["uuid7", "uuid7_str"]