feat: finalize additive-drift hardening — backfill comms/order_groups + WS payloads + flip warn\u2192fail (#161, #162, #163)

[TexasCoding]

Closes #161, #162, #163. Final three PRs of the response-side spec-drift hardening stack (#157), bundled into one branch per user request (implement in one branch if possible).

Three logical commits preserved for review:

• 86fa9d1 — PR3 (PR3: backfill v3.18.0 fields on communications / order_groups #161): backfill comms + order_groups (8 fields)
• c11ba1b — PR4 (PR4: backfill v0.14+ fields on WebSocket payloads (ms timestamps, outcome/book_side) #162): backfill 11 WS payloads (33 fields)
• 9def441 — PR5 (PR5: promote additive drift to hard-fail; register ErrorPayload; WS envelope extra=allow #163): flip warn→fail + register ErrorPayload + envelope extra=allow

Why one PR: the three issues form a single logical unit. PR5 has a hard dependency on PR3 + PR4 ("otherwise this PR turns 53 warnings into 53 failures"). With all three bundled in one branch in the correct order, the flip is safe. Total diff ~535 lines across 19 files — still tractable for a single review.

---

PR3 (#161) — communications + order_groups backfill

8 new optional fields:

• RFQ (+1): creator_subaccount
• Quote (+3): creator_subaccount, rfq_creator_subaccount, post_only
• OrderGroup (+1): exchange_index
• GetOrderGroupResponse (+1): exchange_index
• CreateOrderGroupResponse (+2): subaccount, exchange_index

All typed int | None (bool | None for post_only) matching spec types exactly. 3 new test classes / 8 tests in tests/test_models.py.

PR4 (#162) — WebSocket payload backfill (33 fields, 11 payloads, 8 files)

Three themes:

*_ts_ms Unix-ms timestamps — spec promotes ms-integer as the primary timestamp form. Existing ts fields stay for back-compat. No auto-conversion — latency-sensitive callers get the int directly.

Payload	New fields
TickerPayload	price, ts_ms
FillPayload	outcome_side, book_side, ts_ms
OrderbookDeltaPayload	ts_ms
TradePayload	taker_outcome_side, taker_book_side, ts_ms
UserOrdersPayload	outcome_side, book_side, self_trade_prevention_type, created_ts_ms, last_updated_ts_ms, expiration_ts_ms
MarketLifecyclePayload	additional_metadata, floor_strike, price_level_structure, yes_sub_title
OrderGroupPayload	ts_ms
RfqCreatedPayload	mve_collection_ticker, mve_selected_legs
RfqDeletedPayload	event_ticker, contracts, target_cost
QuoteCreatedPayload	event_ticker, yes_contracts_offered, no_contracts_offered, rfq_target_cost
QuoteAcceptedPayload	event_ticker, yes_contracts_offered, no_contracts_offered, rfq_target_cost

Direction encoding — outcome_side / book_side / taker_*_side reuse SideLiteral / BookSideLiteral / SelfTradePreventionTypeLiteral from kalshi.models.orders. Mirrors REST backfill from #159.

MVE + RFQ context echoes on Communications payloads — server now echoes the parent-RFQ context on quote events so subscribers don't need a lookup roundtrip.

One test class TestWsV0140Backfill in tests/ws/test_models.py with 11 tests — one per payload covering at least one new field. Added QuoteCreatedPayload to module imports.

PR5 (#163) — promote additive drift to hard-fail

Flipped warn → pytest.fail (3 sites)

• TestSpecDrift.test_additive_drift — REST response model additive drift
• TestWsSpecDrift.test_ws_additive_drift — WS payload additive drift
• TestWsSpecDrift.test_ws_contract_map_completeness — WS payload coverage

Kept warn-only

• test_required_drift / test_ws_required_drift — issue explicitly defers required-but-optional policy as a separate ≈204-entry decision.
• test_contract_map_completeness (REST) — deviation from issue text. 42 pre-existing unmapped REST classes (sub-models like Candlestick / OrderbookLevel, V2 request/response family, internal containers like PositionsResponse / IndexedBalance / Deposit / Withdrawal). The issue assumed this check would pass after ErrorPayload registration; only the WS check was at zero. Promoting REST completeness here would require mapping all 42 — out of scope. Filed as inline comment for follow-up.

Registered ErrorPayload

kalshi.ws.models.base.ErrorPayload → spec errorResponsePayload in WS_CONTRACT_MAP. Clears the WS completeness warning so the flip is safe.

Envelope extra="allow" policy

Applied model_config = {"extra": "allow"} to 14 WS classes lacking it (envelopes + helpers). Payloads were already covered by #143; this completes the WS surface.

New test_ws_models_use_extra_allow in tests/test_model_extra_policy.py iterates every BaseModel in kalshi.ws.models.* and pins the policy.

CHANGELOG

Unreleased section summarizing the full #157 stack (#159–#163).

---

Verification

$ uv run pytest tests/ --ignore=tests/integration -q
2023 passed, 35 warnings in 129.91s

Up from 1965 baseline (+58 tests). All 35 warnings are test_required_drift / test_ws_required_drift (kept warn-only per issue). Zero additive-drift warnings remaining.

$ uv run mypy kalshi/                            -> Success: no issues found in 76 source files
$ uv run ruff check .                            -> All checks passed!

Smoke tests (warn→fail confirmed via field deletion)

Test 1 — delete Market.exchange_index locally, run test_additive_drift[Market]:

FAILED tests/test_contracts.py::TestSpecDrift::test_additive_drift[Market]
E   Failed: Additive drift in kalshi.models.markets.Market:
E     - Spec field 'exchange_index' has no SDK mapping

Exit 1 (was UserWarning). ✅ Reverted.

Test 2 — delete ErrorPayload from WS_CONTRACT_MAP locally, run test_ws_contract_map_completeness:

FAILED tests/test_contracts.py::TestWsSpecDrift::test_ws_contract_map_completeness
E   Failed: WS payload models without contract map entries:
E     - kalshi.ws.models.base.ErrorPayload

Exit 1 (was UserWarning). ✅ Reverted.

---

Stack closure

This PR closes the response-side spec-drift hardening stack tracked in #157. After merge:

• ✅ PR0 (test(infra): wire response-side drift through EXCLUSIONS map (PR0) #165) — EXCLUSIONS infrastructure
• ✅ PR1 (feat(models): backfill v3.18.0 fields on Market / Order / Fill (PR1) #166) — Market / Order / Fill (23 fields)
• ✅ PR2 (feat(models): backfill v3.18.0 fields on events / portfolio / historical / incentive_programs (PR2) #167) — Event / EventMetadata / Settlement / Trade / IncentiveProgram (9 fields)
• ✅ PR3 (this) — communications + order_groups (8 fields)
• ✅ PR4 (this) — 11 WS payloads (33 fields)
• ✅ PR5 (this) — warn→fail flip + ErrorPayload + WS envelopes

Future work (out of scope, file a follow-up issue if desired):

• Map the 42 unmapped REST sub-models / V2 family / internal containers and promote test_contract_map_completeness to hard-fail.
• Required-but-Optional drift policy decision (≈204 entries on test_required_drift).

[claude]

Code Review — PR #168: finalize additive-drift hardening

Overview

This bundles three logical sub-PRs (#161/#162/#163) that together form a safe unit: the first two backfill the missing spec fields, and the third flips additive drift from warn → hard-fail. Bundling is the right call — flipping first would have broken CI on the 53 gaps, and splitting the flip into a fourth PR would have left a CI window where warnings silently accumulate again.

---

PR3 (#161) — communications + order_groups backfill ✅

Clean field additions. int | None for subaccount/exchange_index, bool | None for post_only — all match spec types. AliasChoices not needed here since these field names don't have _fp/_dollars variants, so bare field declarations are correct.

One minor issue — mve_selected_legs typing in communications.py:

# current
mve_selected_legs: list[dict[str, object]] | None = None

# suggested
mve_selected_legs: list[dict[str, Any]] | None = None

dict[str, object] makes value access typed as object, so code like legs[0]["event_ticker"].upper() would fail mypy. dict[str, Any] is the idiomatic choice for untyped JSON blobs — it's what market_lifecycle.py already uses for additional_metadata. communications.py just needs from typing import Any added.

---

PR4 (#162) — WebSocket payload backfill ✅

The design choices here are good:

• No auto-conversion between ts (seconds/RFC3339) and ts_ms (Unix ms). Correct — latency-sensitive callers need the raw int; auto-conversion would silently corrupt timestamps for anyone still using ts.
• SideLiteral / BookSideLiteral / SelfTradePreventionTypeLiteral reused from kalshi.models.orders instead of raw str. This is an improvement over the existing taker_side: str | None pattern — Pydantic will now reject "invalid" at parse time.
• AliasChoices("contracts_fp", "contracts") / ("target_cost_dollars", "target_cost") patterns correctly applied.

Minor test inconsistency:

RfqDeletedPayload is imported inline inside test_rfq_deleted_rfq_context while all other payload types in the same file are imported at the module level. Should be moved to the top-level imports block alongside RfqCreatedPayload.

# tests/ws/test_models.py — move this out of the test body
from kalshi.ws.models.communications import RfqDeletedPayload

---

PR5 (#163) — promote warn → fail ✅

The flip itself is minimal and correct. A few things worth calling out:

test_ws_models_use_extra_allow design: The dynamic discovery approach (pkgutil.iter_modules + inspect.getmembers) runs at module import time (not inside a test), which is the right place — it means pytest parametrizes before collection starts and any future model added without extra="allow" fails CI immediately rather than at a runtime assertion. This is the correct pattern.

REST contract map completeness kept as warn-only: The inline comment and PR description both explain the 42 pre-existing unmapped entries clearly. The deviation from the original issue text is documented with rationale. This is fine — the important surface (WS completeness, which was at zero) is now hard-fail.

ErrorPayload registration: The notes field explaining the naming mismatch (errorResponsePayload → ErrorPayload) is helpful context for future maintainers.

---

Test coverage

+58 tests reaching 2023 total. Coverage looks solid:

• Happy path + defaults-to-None for every new field in PR3: backfill v3.18.0 fields on communications / order_groups #161 models
• One integration-style parse per new WS payload in TestWsV0140Backfill
• Policy enforcement test that auto-discovers future WS model additions

One gap: TestWsV0140Backfill doesn't have a mve_selected_legs=None test for RfqCreatedPayload, but the PR notes this is covered by existing minimal tests. Acceptable, but worth a comment pointing to which test covers it.

---

Security / Performance

No security concerns. The _ws_model_classes() dynamic discovery is a one-time O(module count) operation at import time — negligible for CI.

---

Summary

Category	Status
Correctness	✅ All fields match spec types; no auto-conversion; literals validated at parse
Conventions	✅ AliasChoices, DollarDecimal, extra="allow", model_config placement all correct
Test coverage	✅ 58 new tests; policy test auto-catches future regressions
Blocking issues	None
Minor issues	dict[str, object] → dict[str, Any] in communications.py; inline import in test

Verdict: Approved with minor suggestions. The dict[str, object] type and the inline import are worth fixing but neither is blocking. The bundling strategy and the warn→fail flip sequencing are both correct.