fix(sdk): preserve provider-neutral actual served tiers

[routeplane-ops]

Summary

Closes #19.

• Export provider-neutral completion/chunk subclasses widening only optional returned service_tier to a strict string.
• Remap only exact vendor completion/chunk response targets through the installed response processor; preserve other models, strict validation, requests, headers, retries, and incremental SSE decoding.
• Give all four sync/async owned metadata helpers neutral return types. Document the inherited vendor static facade and the dependency-floor raw-parsing/cleanup boundaries.
• Add buffered/SSE, invalid-type, field-preservation, custom-model, lifecycle, retry and static-consumer tests. The existing pytest gate executes the consumer mypy fixture rather than leaving it unverified.

Companion public contract: routeplane-core/routeplane-api-docs#32. Actual returned labels are never requested preferences, normalized tariffs, free-traffic proof, or financial authority.

Compatibility

Valid native and future string labels now pass strict parsing. Malformed non-string/non-null tiers now fail even default tolerant parsing. Exact runtime chat classes become neutral subclasses while remaining instances of the installed vendor models. Inherited resource static annotations remain vendor-owned; use the owned helpers for neutral typing.

The private response-processing hook was checked against both current OpenAI and the advertised 1.0.0 minimum. That minimum has no raw.parse(to=...) argument or vendor stream close method; the documented existing behavior is retained. Pydantic 1's existing tolerant extra-field serialization follows the installed vendor baseline.

Validation

• Full suite: 457 passing tests in each of five environments: actual Python 3.9.25/OpenAI 2.48.0/Pydantic 2.13.5, OpenAI 3.24.0/httpx2 2.13.1/Pydantic 2.13.5, OpenAI 2.46.0/Pydantic 2.13.4, OpenAI 1.0.0/Pydantic 2.13.5, and OpenAI 1.0.0/Pydantic 1.10.26.
• Strict mypy includes all four helper consumer contracts and rejects invalid tier assignments; the fixture ran in every tested environment through pytest.
• Ruff lint/format and git diff --check passed.
• Independent DX/correctness and security reviews passed on final seven-file patch SHA-256 32faa717c4b50cfe3af2cf05f4b4a3dba713fa76ddc282ecb37d5ff521c1cf4c. The reviewer independently ran native-transport cases plus consumer mypy on actual Python 3.9.25/OpenAI 2.48.0 after the final test-only correction. Prior reviews independently exercised all 141 served-tier tests on OpenAI 3.24.0 and all 132 original cases in the other three dependency environments; root ran the then-current 448-test suite/Ruff. Every required hosted Python-version gate must pass at the final published head before landing.

No dependency, lockfile, workflow, authentication, endpoint, pricing, package release, or production promotion changes. A package release remains a separate deliberate action.

Hosted compatibility findings and final acceptance

Initial published head a3af5481bc0aa54938981d4ddf7b8e71bf07c49c CI 37127652693 installed OpenAI 3.24.0 with its httpx2 transport. The locally checked 2.46.0 version is not the newest version selected by unconstrained installation. Runtime tests passed in the inspected completed job, but lint and the consumer-type fixture rejected five response-hook annotation mismatches (httpx.Response versus the installed vendor's httpx2.Response). The fixture correctly failed; it is not skipped.

Correction: only the opaque vendor-response forwarding argument uses Any, since supported SDK versions export no stable shared raw-response type. Data/model selection, generic results, strict tier checks and superclass validation are unchanged. Nine additional tests use the actual installed vendor transport, including unchanged error-response identity. All four dependency environments pass again; fresh hosted checks remain required. No unchanged rerun, dependency cap, transport conversion, or disabled validation.

Second changed-source head 181b982164d6462b24d64b62374289a3be885fbd CI 37128310618 passed lint and Python 3.10–3.13, but Python 3.9 failed only the nine new test cases: evaluating all vendor constructor annotations encountered unsupported union syntax. Final test-only correction reads the trusted installed SDK transport binding directly, without annotation evaluation or dynamic imports. No tests are skipped and production code is unchanged. Actual Python 3.9.25 resolves supported OpenAI 2.48.0 rather than 3.24.0, which requires Python >=3.10; that environment now passes all 457 tests too.

Final head 601d7600c146428f84baf18c462c3b78c98e1e94 CI 37128791425 passed all six required jobs: lint and Python 3.9–3.13. Each Python job actually ran 457 passing tests, including the strict consumer fixture. The protected squash merge is 4fe4099ffb76f4bb52641b6d6e98898f252c61c6 (2026-10-03T14:21:47Z), with the same reviewed full tree 3ccfdd58ef19ed2edc03f29a2b66fb1a1490d219. Issue #19 closed. This merge is source delivery, not a PyPI release or gateway deployment.