fix(pagination): fail loudly on contradictory headers; test both classes

Review follow-up: raise instead of silently truncating when X-Has-More
is true but X-Next-Offset is absent, mirror all tests across the Sync
and Async classes so the two generated variants cannot drift apart, pin
the 0 last-page sentinel, and fix the stale next_offset wording in the
README pagination example.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: IlyaasK

README.md

@@ -185,8 +185,8 @@ first_page = await client.deployments.list(
 )
 
 print(
-    f"the current start offset for this page: {first_page.next_offset}"
-)  # => "the current start offset for this page: 1"
+    f"the offset where the next page starts: {first_page.next_offset}"
+)  # => "the offset where the next page starts: 2"
 for deployment in first_page.items:
     print(deployment.id)
 

src/kernel/pagination.py

@@ -39,8 +39,13 @@ def has_next_page(self) -> bool:
     @override
     def next_page_info(self) -> Optional[PageInfo]:
         next_offset = self.next_offset
-        if next_offset is None:
-            return None  # type: ignore[unreachable]
+        if next_offset is None:  # type: ignore[unreachable]
+            if self.has_more:
+                raise RuntimeError(
+                    "Server reported X-Has-More: true without an X-Next-Offset header; "
+                    "refusing to silently truncate pagination"
+                )
+            return None
 
         # X-Next-Offset already holds the offset where the next page starts;
         # adding the current page length on top skips a full page per iteration.
@@ -81,8 +86,13 @@ def has_next_page(self) -> bool:
     @override
     def next_page_info(self) -> Optional[PageInfo]:
         next_offset = self.next_offset
-        if next_offset is None:
-            return None  # type: ignore[unreachable]
+        if next_offset is None:  # type: ignore[unreachable]
+            if self.has_more:
+                raise RuntimeError(
+                    "Server reported X-Has-More: true without an X-Next-Offset header; "
+                    "refusing to silently truncate pagination"
+                )
+            return None
 
         # X-Next-Offset already holds the offset where the next page starts;
         # adding the current page length on top skips a full page per iteration.

tests/test_pagination.py

@@ -1,42 +1,62 @@
-from typing import Any, List, Optional
+from typing import Any, List, Type, Union, Optional
 
 import httpx
+import pytest
 
-from kernel.pagination import SyncOffsetPagination
+from kernel.pagination import AsyncOffsetPagination, SyncOffsetPagination
+
+PageClass = Union[Type[SyncOffsetPagination[Any]], Type[AsyncOffsetPagination[Any]]]
+
+# build() and next_page_info() are plain synchronous methods on both classes,
+# so both generated variants are pinned against drifting apart on regeneration.
+both_classes = pytest.mark.parametrize("cls", [SyncOffsetPagination, AsyncOffsetPagination])
 
 
 def _page(
-    *, items: List[Any], next_offset: Optional[int], has_more: Optional[bool]
-) -> SyncOffsetPagination[Any]:
+    cls: PageClass, *, items: List[Any], next_offset: Optional[int], has_more: Optional[bool]
+) -> Any:
     headers: dict[str, str] = {}
     if next_offset is not None:
         headers["X-Next-Offset"] = str(next_offset)
     if has_more is not None:
         headers["X-Has-More"] = "true" if has_more else "false"
     response = httpx.Response(200, headers=headers)
-    return SyncOffsetPagination.build(response=response, data=items)
+    return cls.build(response=response, data=items)
 
 
-def test_next_page_starts_at_exactly_x_next_offset() -> None:
+@both_classes
+def test_next_page_starts_at_exactly_x_next_offset(cls: PageClass) -> None:
     # X-Next-Offset already holds the next page's start. Adding the current
     # page length on top (the old behavior) skipped a full page per iteration.
-    page = _page(items=[{}] * 100, next_offset=100, has_more=True)
+    page = _page(cls, items=[{}] * 100, next_offset=100, has_more=True)
     info = page.next_page_info()
     assert info is not None
     assert info.params == {"offset": 100}
 
 
-def test_stops_when_x_next_offset_absent() -> None:
-    page = _page(items=[{}] * 100, next_offset=None, has_more=True)
+@both_classes
+def test_stops_cleanly_when_last_page_omits_x_next_offset(cls: PageClass) -> None:
+    page = _page(cls, items=[{}] * 50, next_offset=None, has_more=False)
     assert page.next_page_info() is None
     assert page.has_next_page() is False
 
 
-def test_stops_when_x_has_more_false() -> None:
-    page = _page(items=[{}] * 50, next_offset=200, has_more=False)
+@both_classes
+def test_stops_when_x_has_more_false(cls: PageClass) -> None:
+    # Covers the 0 sentinel the API emits on last pages: has_more is false
+    # whenever next_offset is 0, and has_more gates first.
+    page = _page(cls, items=[{}] * 50, next_offset=0, has_more=False)
     assert page.has_next_page() is False
 
 
-def test_stops_on_empty_page() -> None:
-    page = _page(items=[], next_offset=300, has_more=True)
+@both_classes
+def test_stops_on_empty_page(cls: PageClass) -> None:
+    page = _page(cls, items=[], next_offset=300, has_more=True)
     assert page.has_next_page() is False
+
+
+@both_classes
+def test_refuses_to_silently_truncate_on_contradictory_headers(cls: PageClass) -> None:
+    page = _page(cls, items=[{}] * 100, next_offset=None, has_more=True)
+    with pytest.raises(RuntimeError, match="refusing to silently truncate"):
+        page.has_next_page()