feat(models): backfill v3.18.0 fields on Market / Order / Fill (PR1)

[TexasCoding]

Closes #159. PR1 of the response-side spec-drift hardening stack (#157). Builds on the EXCLUSIONS infrastructure landed in #165 / #158. Three of the remaining additive-drift warnings eliminated; eight more models (#PR2–#PR4) plus the warn→fail flip (#PR5) still ahead.

What this changes

23 new optional fields across the three highest-traffic response models, matching the v3.18.0 OpenAPI spec.

kalshi/models/markets.py — Market (+11)

Field	SDK type
custom_strike	dict[str, Any] | None
early_close_condition	str | None
exchange_index	int | None
fee_waiver_expiration_time	datetime | None
functional_strike	str | None
is_provisional	bool | None
mve_collection_ticker	str | None
mve_selected_legs	list[dict[str, Any]] | None
price_level_structure	str | None
price_ranges	list[dict[str, Any]] | None
primary_participant_key	str | None

kalshi/models/orders.py — Order (+8)

Field	SDK type
outcome_side	SideLiteral | None
book_side	BookSideLiteral | None
last_update_time	datetime | None
self_trade_prevention_type	SelfTradePreventionTypeLiteral | None
order_group_id	str | None
cancel_order_on_pause	bool | None
subaccount_number	int | None
exchange_index	int | None

kalshi/models/orders.py — Fill (+4)

Field	SDK type
outcome_side	SideLiteral | None
book_side	BookSideLiteral | None
subaccount_number	int | None
ts	int | None

Design decisions

• mve_selected_legs / price_ranges typed as list[dict[str, Any]] instead of introducing new MveSelectedLeg / PriceRange model classes. The issue explicitly defers Literal-alias polish to a separate PR; the same rationale applies to nested model classes (spec drift only checks property presence, not nested-property typing). Future PR can promote these to typed models if needed.
• outcome_side / book_side / self_trade_prevention_type reuse existing *Literal aliases defined at the top of orders.py. No new aliases invented.
• Fill.ts stays int | None, NOT datetime. The spec says it's a Unix-ms timestamp; the typed companion is created_time: datetime. Auto-coercing would break callers depending on the raw integer. Test class includes a test_ts_is_int_not_datetime regression guard.
• Order.subaccount_number is distinct from Order.subaccount. Both coexist per spec; test verifies they parse and round-trip independently.
• All new fields appended at the end of each model with a # v3.18.0 backfill comment block. No existing fields reordered — append-only matches the spec's evolution pattern and minimizes review diff.

No changes to request-body models or resource methods.

Tests

3 new test classes in tests/test_models.py (10 tests, 23 field assertions). I placed them alongside the existing TestDollarsAliasFields / TestMarketOccurrenceDatetime precedent rather than in tests/test_orders.py — the latter is for resource HTTP wire-shape tests (TestCreateOrderWireShape etc.), not pure model deserialization. The issue allowed this discretion ("tests/test_models_markets.py (or wherever Market is exercised — confirm at edit time)").

• TestMarketV3180Fields (3 tests): scalar fields, object+array fields (custom_strike, mve_selected_legs, price_ranges), defaults-to-None for all 11.
• TestOrderV3180Fields (4 tests): outcome+book side, remaining 6 fields, subaccount_number-vs-subaccount coexistence, defaults-to-None for all 8.
• TestFillV3180Fields (3 tests): all 4 new fields, ts-is-int-not-datetime regression guard, defaults-to-None for all 4.

Verification

$ uv run pytest tests/test_contracts.py::TestSpecDrift::test_additive_drift[Market] \
                tests/test_contracts.py::TestSpecDrift::test_additive_drift[Order] \
                tests/test_contracts.py::TestSpecDrift::test_additive_drift[Fill] \
                -W error::UserWarning -v
3 passed                                          # was: 3 failed before this PR

$ uv run pytest tests/ --ignore=tests/integration -q
1955 passed, 54 warnings in 127.03s              # baseline 1945 + 10 new; warnings 57 → 54

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

Other test_additive_drift cases (Event, Settlement, Trade, EventMetadata, RFQ, Quote, IncentiveProgram, OrderGroup x3) still warn for un-backfilled models, per the stack plan (#PR2–#PR4).

Note on remaining Required drift in Market warning

The required-drift warning for Market gains two new entries after this PR (price_ranges, price_level_structure) because the spec marks them required but the SDK keeps them Optional per the project's pervasive required-but-optional policy. The issue explicitly defers this:

Required-but-Optional drift policy (kept as warn-only; ~204 entries, separate decision).

This is consistent with how every other DollarDecimal / FixedPointCount field on Market is already handled.

Part of the response-side spec drift hardening stack (#157).

[claude]

Code Review — PR #166: v3.18.0 field backfill (Market / Order / Fill)

Overview

Additive spec-drift fix: 23 new optional response fields on the three highest-traffic models, all matching the v3.18.0 OpenAPI spec. The diff is surgical (3 files, +205/-1) and doesn't touch request models, resource methods, or any existing fields — consistent with the stated append-only policy.

---

What works well

• Correct typing choices. ts: int | None on Fill (not datetime) is the right call and the PR description explains the reasoning clearly. The regression guard assert not isinstance(f.ts, bool) in the test is a nice touch.
• Literal reuse. SideLiteral, BookSideLiteral, and SelfTradePreventionTypeLiteral are all already defined at the top of orders.py and the values used in tests ("taker_at_cross", "ask", "yes") match the defined literals exactly — no phantom values.
• _contract_map.py unchanged correctly. Market, Order, and Fill are already registered; the contract drift tests pick up new fields automatically. No registration needed.
• 10 tests cover all 23 fields, including coexistence of subaccount vs subaccount_number and the ts/datetime distinction.
• All gates pass — mypy strict, ruff, and the three previously-failing test_additive_drift cases.

---

Issues

1. Fill imported inside test methods — inconsistent with module-level imports (minor)

test_models.py already imports Market and Order at the top of the file. The three methods in TestFillV3180Fields each repeat from kalshi.models.orders import Fill inside the method body. This is inconsistent and adds visual noise.

# Current — three copies of this inside TestFillV3180Fields methods:
from kalshi.models.orders import Fill

# Fix — add to the module-level imports alongside Order:
from kalshi.models.orders import Fill, Order

2. Inline comments are longer than necessary (style, low priority)

CLAUDE.md guideline: "Only add one [comment] when the WHY is non-obvious." The # v3.18.0 backfill block in each model is justified (the list[dict[str, Any]] rationale and ts/datetime distinction are both non-obvious), but the blocks run 4–5 lines and partially re-explain what the field names already say. The PR description is the right place for the extended rationale; the model files could use a single-line comment per group.

Example trim for markets.py:

# v3.18.0 backfill (#159). mve_selected_legs/price_ranges kept as list[dict] —
# no nested model classes yet; separable polish tracked in a future PR.
custom_strike: dict[str, Any] | None = None
...

This isn't a blocker, but shorter comments age better.

---

No concerns on

• Security — response-side deserialization only; extra="allow" was already set on all three models.
• Performance — optional fields with None defaults have zero overhead when absent.
• Backwards compatibility — all fields are | None with None defaults; existing callers are unaffected.
• Contract tests — the three test_additive_drift cases now pass; required-drift entries for price_ranges/price_level_structure are consistent with the project's existing required-but-optional policy.

---

Summary

One real (minor) fix needed: pull Fill up to the module-level imports in test_models.py. The comment trimming is optional. Everything else looks correct and follows project conventions — good candidate to merge once the import is cleaned up.

[TexasCoding]

Thanks for the review. Both items addressed in 67623d5.

1. Fill import hoisted to module level — fixed

Three inline from kalshi.models.orders import Fill in the new test methods + one pre-existing inline in test_fill_accepts_dollars_suffix (which I missed in PR1; cleaning all four together for consistency). All replaced by extending the existing top-level import:

from kalshi.models.orders import Fill, Order

2. Comment blocks trimmed — fixed

You're right that the verbose phrasing partially restated what the field declarations already say. CLAUDE.md is explicit about documenting the WHY, not the WHAT. Trimmed each block to preserve the non-obvious rationale only:

markets.py (5 lines → 3):

# v3.18.0 backfill (#159). mve_selected_legs is list[MveSelectedLeg] and
# price_ranges is list[PriceRange] on the wire — kept as list[dict] here;
# no nested model classes yet (separable polish).

orders.py Order (5 lines → 3):

# v3.18.0 backfill (#159). outcome_side/book_side are the canonical
# direction encoding going forward; deprecated action/side/is_yes stay
# for back-compat. subaccount_number is distinct from subaccount.

orders.py Fill (3 lines → 2):

# v3.18.0 backfill (#159). ts is Unix-ms int per spec — distinct from
# the typed created_time: datetime; do NOT coerce.

Extended rationale (full spec citations, separable-polish reasoning) lives in the PR description where it belongs.

Re-verification

pytest tests/test_models.py                            -> 79 passed
pytest test_additive_drift[Market,Order,Fill] -W error -> 3 passed
mypy kalshi/                                           -> Success: no issues
ruff check .                                           -> All checks passed!

Diff: +9 -22 on 3 files.

[claude]

Follow-up Review — revisions in 67623d5

Both items from the initial review have been addressed correctly.

1. Fill import hoisted — all four inline from kalshi.models.orders import Fill (three new + one pre-existing) are gone; the module-level import now reads from kalshi.models.orders import Fill, Order. Clean.

2. Comment blocks trimmed — each block is now 2–3 lines covering only the non-obvious WHY (the list[dict] deferral, the ts/datetime distinction, the subaccount coexistence). Consistent with CLAUDE.md.

No new concerns. This PR is ready to merge.