Gate v2 generated stubs

- Gate `build-v2` and `pre-flight-v2` on generated drift
- Add uv pin preflight before v2 sync and stub generation
- Document when to run `make py-stubs-v2` and what to commit

Author: cjdsellers

.github/workflows/build-v2.yml

@@ -250,29 +250,12 @@ jobs:
             --rootdir="$GITHUB_WORKSPACE/${{ env.PACKAGE_DIR }}" \
             "$GITHUB_WORKSPACE/${{ env.PACKAGE_DIR }}/tests/" -v
 
-      # Temporary: show whether v2 stub or docstring generation dirtied tracked files while we isolate CI drift
-      - name: Report generated v2 file drift
-        if: always()
+      - name: Check generated v2 file drift
+        # Keep this 3.13 condition in sync with the matrix so drift is checked once per run.
+        if: matrix.python-version == '3.13'
         run: |
-          targets=(
-            python/generate_docstrings.py
-            python/generate_stubs.py
-            crates/pyo3
-            ':(glob)python/nautilus_trader/**/*.pyi'
-            ':(glob)crates/**/src/python/**/*.rs'
-          )
-
-          changes="$(git status --short --untracked-files=all -- "${targets[@]}")"
-
-          if [ -z "$changes" ]; then
-            echo "No generated v2 file drift detected"
-            exit 0
-          fi
-
-          echo "::warning::Tracked or untracked v2 build files changed during the job"
-          printf '%s\n' "$changes"
-          echo
-          git diff --stat HEAD -- "${targets[@]}" || true
+          make py-stubs-v2 V2_CARGO_TARGET_DIR=/home/runner/.cache/cargo-target/py-stubs-v2
+          bash scripts/ci/check-v2-generated-drift.bash
 
       - name: Upload wheel artifact
         uses: ./.github/actions/upload-artifact-wheel

CONTRIBUTING.md

@@ -39,5 +39,7 @@ To contribute, follow these steps:
 
 - Follow the established coding practices in the [Developer Guide](https://nautilustrader.io/docs/developer_guide/index.html).
 - For documentation changes, follow the style guide in `docs/developer_guide/docs.md` (use sentence case for headings H2 and below).
+- For v2 PyO3 bindings or wrapped Rust docs, run `make py-stubs-v2` and commit the
+  generated output. See [Generated Python artifacts](docs/developer_guide/rust.md#generated-python-artifacts).
 - Keep PRs small and focused for easier review.
 - Reference the relevant GitHub issue(s) in your PR comment.

Makefile

@@ -20,6 +20,12 @@ LYCHEE_VERSION := $(shell bash scripts/cargo-tool-version.sh lychee)
 # Tool versions from tools.toml
 PREK_VERSION := $(shell bash scripts/tool-version.sh prek)
 UV_VERSION := $(shell bash scripts/uv-version.sh)
+UV_V2_REQUIRED_SPEC := $(shell awk -F'"' '\
+	/^\[tool\.uv\]/ { in_section=1; next } \
+	/^\[/ { in_section=0 } \
+	in_section && /^[[:space:]]*required-version[[:space:]]*=/ { print $$2; exit } \
+' python/pyproject.toml)
+UV_V2_REQUIRED_VERSION := $(patsubst ==%,%,$(UV_V2_REQUIRED_SPEC))
 
 V = 0  # 0 / 1 - verbose mode
 Q = $(if $(filter 1,$V),,@) # Quiet mode, suppress command output
@@ -32,6 +38,8 @@ VERBOSE ?= true
 # Set UV_SYNC_FLAGS= to make uv prune packages not in uv.lock
 UV_SYNC_FLAGS ?= --inexact
 
+V2_CARGO_TARGET_DIR ?= $(CURDIR)/target-v2
+
 PIP_AUDIT_IGNORE_FLAGS :=
 
 # TARGET_DIR controls where cargo places build artifacts.
@@ -1037,19 +1045,40 @@ test-performance:  #-- Run performance tests with codspeed benchmarking
 
 .PHONY: sync-v2
 sync-v2:  #-- Sync v2 Python dependencies (without building the package)
-	$(info $(M) Syncing v2 Python dependencies...)
+	@if [ -z "$(UV_V2_REQUIRED_SPEC)" ]; then \
+		printf "$(RED)ERROR: Could not find required-version in python/pyproject.toml$(RESET)\n"; \
+		exit 1; \
+	fi
+	@if [ "$(UV_V2_REQUIRED_SPEC)" = "$(UV_V2_REQUIRED_VERSION)" ]; then \
+		printf "$(RED)ERROR: python/pyproject.toml required-version must use ==A.B.C, found $(UV_V2_REQUIRED_SPEC)$(RESET)\n"; \
+		exit 1; \
+	fi
+	@found="$$(uv --version 2>/dev/null | awk '{print $$2}' || true)"; \
+	if [ -z "$$found" ]; then \
+		printf "$(RED)ERROR: uv not found, ==$(UV_V2_REQUIRED_VERSION) required; run \`uv self update --version $(UV_V2_REQUIRED_VERSION)\` or prepend a matching binary to PATH.$(RESET)\n"; \
+		exit 1; \
+	fi; \
+	if [ "$$found" != "$(UV_V2_REQUIRED_VERSION)" ]; then \
+		printf "$(RED)ERROR: uv $$found found, ==$(UV_V2_REQUIRED_VERSION) required; run \`uv self update --version $(UV_V2_REQUIRED_VERSION)\` or prepend a matching binary to PATH.$(RESET)\n"; \
+		exit 1; \
+	fi
+	@printf "$(M) Syncing v2 Python dependencies...\n"
 	$Q cd python && VIRTUAL_ENV= uv sync --all-groups --all-extras --no-install-package nautilus-trader $(UV_SYNC_FLAGS)
 
 .PHONY: build-debug-v2
 build-debug-v2: sync-v2  #-- Build the v2 Python package in debug mode (also regenerates type stubs)
 	@$(MAKE) --no-print-directory py-stubs-v2
 	$(info $(M) Building v2 extension in debug mode...)
-	$Q cd python && VIRTUAL_ENV= CARGO_TARGET_DIR=../target-v2 uv run --no-sync maturin develop
+	$Q cd python && VIRTUAL_ENV= CARGO_TARGET_DIR=$(V2_CARGO_TARGET_DIR) uv run --no-sync maturin develop
 
 .PHONY: py-stubs-v2
 py-stubs-v2: sync-v2  #-- Regenerate v2 Python type stubs from Rust bindings
 	$(info $(M) Generating v2 Python type stubs...)
-	$Q cd python && VIRTUAL_ENV= CARGO_TARGET_DIR=$(CURDIR)/target-v2 uv run --no-sync python generate_stubs.py
+	$Q cd python && VIRTUAL_ENV= CARGO_TARGET_DIR=$(V2_CARGO_TARGET_DIR) uv run --no-sync python generate_stubs.py
+
+.PHONY: check-v2-generated-drift
+check-v2-generated-drift:  #-- Check v2 generated stubs and docstrings are committed
+	$Q bash scripts/ci/check-v2-generated-drift.bash
 
 .PHONY: update-v2
 update-v2: cargo-update  #-- Update v2 dependencies (cargo and uv)
@@ -1064,7 +1093,7 @@ pytest-v2: build-debug-v2  #-- Run v2 Python tests
 
 .PHONY: pre-flight-v2
 pre-flight-v2: export CARGO_TARGET_DIR=target-v2
-pre-flight-v2:  #-- Run comprehensive v2 pre-flight checks (format, check-code, cargo-test, build, pytest)
+pre-flight-v2:  #-- Run v2 pre-flight checks (format, tests, build, generated drift, audit)
 	$(info $(M) Running v2 pre-flight checks...)
 	@if ! git diff --quiet; then \
 		printf "$(RED)ERROR: You have unstaged changes$(RESET)\n"; \
@@ -1077,6 +1106,7 @@ pre-flight-v2:  #-- Run comprehensive v2 pre-flight checks (format, check-code,
 		&& $(MAKE) --no-print-directory check-code EXTRA_FEATURES="capnp,hypersync" \
 		&& $(MAKE) --no-print-directory cargo-test-extras \
 		&& $(MAKE) --no-print-directory build-debug-v2 \
+		&& $(MAKE) --no-print-directory check-v2-generated-drift \
 		&& $(MAKE) --no-print-directory pytest-v2 \
 		&& $(MAKE) --no-print-directory security-audit \
 	$(call timer_end,Pre-flight)

README.md

@@ -582,6 +582,10 @@ See the [Developer Guide](https://nautilustrader.io/docs/latest/developer_guide/
 >
 > Run `make build-debug` to compile after changes to Rust or Cython code for the most efficient development workflow.
 
+After changes to v2 PyO3 bindings or wrapped Rust docs, run `make py-stubs-v2` and commit the
+generated `.pyi` files and wrapper docstrings. See
+[Generated Python artifacts](docs/developer_guide/rust.md#generated-python-artifacts).
+
 ### Testing with Rust
 
 [cargo-nextest](https://nexte.st) is the standard Rust test runner for NautilusTrader.

docs/developer_guide/environment_setup.md

@@ -220,7 +220,8 @@ Python dependencies are managed by [uv](https://docs.astral.sh/uv). The `[tool.u
   by `scripts/uv-version.sh` for Makefile, CI, and Docker builds. If your local uv drifts off the
   pin, `uv lock`/`uv sync` will fail with `Required uv version ... does not match the running
   version ...`. Run `make update-uv` to install the pinned version (or follow uv's own
-  `uv self update <version>` hint).
+  `uv self update <version>` hint). The v2 stub targets check the `python/pyproject.toml` pin
+  before running `uv`; see [Generated Python artifacts](rust.md#generated-python-artifacts).
 - **`exclude-newer = "3 days"`**: `uv lock` ignores package versions published within the last
   3 days. This gives the community time to detect and quarantine compromised releases before they
   enter the lockfile. The value accepts an RFC 3339 timestamp (`"2026-03-30T00:00:00Z"`), a friendly

docs/developer_guide/rust.md

@@ -452,10 +452,48 @@ python = ["pyo3", "pyo3-stub-gen"]
 pyo3-stub-gen = { workspace = true, optional = true }
 ```
 
-**Regenerating stubs:** run `make py-stubs-v2` (or `python python/generate_stubs.py`)
-after changing annotations. The post-processor handles `py_` prefix stripping,
-`@property`/`@staticmethod`/`@classmethod` decoration, keyword escaping, deduplication,
-and ruff formatting.
+### Generated Python artifacts
+
+The v2 Python surface commits two generated artifact types:
+
+- Python type stubs under `python/nautilus_trader/**/*.pyi`.
+- PyO3 wrapper doc comments under `crates/**/src/python/**/*.rs`.
+
+Run the generator with one command:
+
+```bash
+make py-stubs-v2
+```
+
+Run it after changing any Python-exposed Rust surface: `#[pyclass]`, `#[pymethods]`,
+`#[pyfunction]`, stub annotations, doc comments on wrapped core items, or adapter feature wiring.
+Commit every generated `.pyi` file and wrapper doc comment changed by the target with the source
+change. CI fails when committed output does not match regeneration. `make build-debug-v2` also
+regenerates these artifacts, but use `make py-stubs-v2` when you only need stubs and docstrings.
+
+Wrapper `///` docs under `crates/**/src/python/**` are generated by
+`python/generate_docstrings.py` from the core Rust item docs. Do not hand-edit them. Edit the core
+docs and run `make py-stubs-v2`. The sync applies these transforms:
+
+- `# Errors` and `# Safety` sections are copied as-is.
+- `# Panics` sections are dropped before they reach the Python API.
+- Intra-doc links are stripped.
+- Rust paths written with `::` become Python-style `.` paths.
+
+The v2 target uses the uv version pinned by `required-version = "==0.11.26"` in
+`python/pyproject.toml`. If your local `uv` differs, `make sync-v2`, `make py-stubs-v2`, and
+`make build-debug-v2` fail before sync with the required version and update command. Run the
+`uv self update --version ...` command printed by the preflight, or prepend a matching `uv`
+binary to `PATH`.
+
+Stub generation must compile the same optional Python surface that wheel builds expose.
+`python/generate_stubs.py` strips `extension-module` before running cargo, so features enabled only
+by `extension-module` in wheel builds must be appended explicitly in that script. Interactive
+Brokers uses this rule by appending `nautilus-interactive-brokers/gateway`, which keeps
+`DockerizedIBGateway` and `ContainerStatus` in the generated stubs.
+
+The post-processor handles `py_` prefix stripping, `@property`/`@staticmethod`/`@classmethod`
+decoration, keyword escaping, deduplication, and ruff formatting.
 
 ### Constructor patterns
 

scripts/ci/check-v2-generated-drift.bash

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+targets=(
+  python/generate_docstrings.py
+  python/generate_stubs.py
+  crates/pyo3
+  ':(glob)python/nautilus_trader/**/*.pyi'
+  ':(glob)crates/**/src/python/**/*.rs'
+)
+
+git update-index -q --refresh
+
+untracked="$(git ls-files --others --exclude-standard -- "${targets[@]}")"
+
+if git diff --quiet HEAD -- "${targets[@]}" && [ -z "$untracked" ]; then
+  echo "No generated v2 file drift detected"
+  exit 0
+fi
+
+echo "::error::Generated v2 files are out of sync"
+echo "Run \`make py-stubs-v2\` and commit the result."
+echo
+echo "Changed files:"
+git status --short --untracked-files=all -- "${targets[@]}"
+echo
+echo "Diff stat:"
+git diff --stat HEAD -- "${targets[@]}" || true
+
+if [ -n "$untracked" ]; then
+  echo
+  echo "Untracked generated files:"
+  printf '%s\n' "$untracked"
+fi
+
+echo
+git diff --exit-code HEAD -- "${targets[@]}" || true
+exit 1