Docs: migration guide missing v2.1→v2.3 sections + self-contradicting list_all() cap #200

Summary

docs/migration.md has two distinct issues that mislead users upgrading across recent releases:

(1) Missing v2.1→v2.2 and v2.2→v2.3 sections

migration.md only covers v1→v2.0 and v2.0→v2.1. CHANGELOG.md L21-24 explicitly calls out v2.2.0 as:

Soft-breaking at the response-parse boundary only … server omission of a previously-optional spec-required field now raises pydantic.ValidationError instead of silently producing field=None.

That is a real behavior change for any consumer parsing live responses — code that previously tolerated field=None now raises. v2.3.0 also added run_forever(stop_event=...), the WS resubscribe-window stash, the dedicated sign executor, and KalshiSubscriptionError raised from run_forever() (was a silent no-op). None of this is in the migration guide.

(2) list_all() page cap claim contradicts itself

L162-165 (v2.0 release notes) correctly states the 1000-page cap was removed:

*_all() is now unbounded by default. The previous internal 1000-page cap silently truncated callers iterating beyond ~100k items.

L405-407, in the same file, still claims:

list_all() walks cursors until the server returns no more pages, with a 1000-page safety cap and a cursor-repeat detector

Users reading the predecessor-migration section will set up loops assuming a built-in cap that no longer exists.

Location

• docs/migration.md:1-178 — missing recent sections
• docs/migration.md:162-165 vs docs/migration.md:405-407 — internal contradiction

Recommended fix

1. Add ## v2.1 → v2.2 section covering:

   • The response-parse tightening: which model fields flipped from Optional[X] = None to required.
   • Symptom: pydantic.ValidationError where previously the field would be None.
   • Recovery: enumerate the affected models (Market, Order, Fill, Event, etc.) or link to the PR(s).

2. Add ## v2.2 → v2.3 section covering:

   • run_forever() now raises KalshiSubscriptionError instead of returning silently when no subscribe_* call preceded it.
   • New stop_event cooperative-shutdown contract.
   • KalshiAuth.close() / sign-executor teardown obligation for standalone-auth users (relevant to the shared-auth ownership issue tracked separately).

3. Replace L405-407 with v2.0+ accurate wording: unbounded by default, cursor-repeat detector remains, max_pages=N available for explicit caps. Cross-link to docs/pagination.md (or wherever the canonical page lives) rather than re-stating semantics in two places.

Severity & category

high / documentation