feat(sdk): add version-pinned server and model surfaces (#1048)

Author: bokelley

.pre-commit-config.yaml

@@ -10,7 +10,9 @@ repos:
       - id: black
         language_version: python3.11
         args: [--line-length=100]
-        exclude: ^src/adcp/types/generated_poc/
+        # Version-scoped stubs are deterministically emitted and checked by
+        # make validate-generated; reformatting them makes the checked output stale.
+        exclude: ^(src/adcp/types/generated_poc/|src/adcp/types/v(30|31|32)\.pyi$)
 
   # Ruff linting (ignoring line-length for now - black handles it)
   - repo: https://github.com/astral-sh/ruff-pre-commit
@@ -75,8 +77,9 @@ repos:
         # schemas (e.g. v3.1+ bundled core/*-response.json files exceed
         # 6 MB). They're canonical from the protocol release tarball, not
         # hand-authored — the large-file gate would block every schema
-        # sync. Same exclusion as the file-fixer hooks above.
-        exclude: ^schemas/
+        # sync. Version-scoped type stubs are also generated from those schema
+        # bundles and validated byte-for-byte by make validate-generated.
+        exclude: ^(schemas/|src/adcp/types/v(30|31|32)\.pyi$)
       - id: check-merge-conflict
       - id: check-case-conflict
       - id: detect-private-key

Makefile

@@ -79,6 +79,7 @@ regenerate-schemas: ## Download latest schemas and skills from bundle, then rege
 	$(PYTHON) scripts/fix_schema_refs.py
 	@echo "Bundling schemas into package..."
 	$(PYTHON) scripts/bundle_schemas.py
+	$(PYTHON) scripts/generate_versioned_stubs.py
 	@echo "Generating Pydantic models..."
 	$(PYTHON) scripts/generate_types.py
 	@echo "Consolidating exports..."
@@ -90,6 +91,7 @@ regenerate-schemas: ## Download latest schemas and skills from bundle, then rege
 validate-generated: ## Validate generated code (syntax and imports)
 	@echo "Validating generated code..."
 	@$(PYTHON) -m py_compile src/adcp/types/_generated.py
+	@$(PYTHON) scripts/generate_versioned_stubs.py --check
 	@echo "✓ Generated code validation passed"
 
 pre-push: format lint typecheck-all test validate-generated ## Run all checks before pushing (format, lint, typecheck, test, validate)

pyproject.toml

@@ -175,6 +175,7 @@ namespaces = true
 [tool.setuptools.package-data]
 adcp = [
     "py.typed",
+    "types/*.pyi",
     "ADCP_VERSION",
     "signing/pg/*.sql",
     "decisioning/pg/*.sql",
@@ -210,7 +211,7 @@ target-version = ["py310", "py311", "py312"]
 # files, rolls back). The regen script already runs black on the
 # consolidated _generated.py; individual generated_poc/ files don't
 # need formatting at commit time. Mirrors the ruff extend-exclude.
-extend-exclude = "/(tasks|_generated|registry)\\.py$|/types/generated_poc/"
+extend-exclude = "/(tasks|_generated|registry)\\.py$|/types/generated_poc/|/types/v3[012]\\.pyi$"
 
 [tool.ruff]
 line-length = 100
@@ -220,6 +221,9 @@ extend-exclude = [
     "src/adcp/types/registry.py",
     "src/adcp/types/tasks.py",
     "src/adcp/types/generated_poc/",
+    "src/adcp/types/v30.pyi",
+    "src/adcp/types/v31.pyi",
+    "src/adcp/types/v32.pyi",
     "examples/",
     "scripts/",
 ]