fix(pagination): correct type:ignore placement; stop on 0 sentinel

Two review follow-ups, both classes:
- Move '# type: ignore[unreachable]' from the 'if next_offset is None:' line
  onto the first body statement ('if self.has_more:'). Under warn_unreachable
  mypy reports the unreachable diagnostic at the first body statement, so the
  ignore must sit there or the lint fails. Verified with mypy==1.17.0.
- Treat next_offset == 0 as a stop, not an advancing offset (matching the Go
  and Node SDKs). A real next-page offset is always offset+limit >= 1, so 0 is
  unambiguously the last-page sentinel. New test asserts via next_page_info
  directly under has_more=True so the has_more gate can't mask it.

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

Author: IlyaasK

src/kernel/pagination.py

@@ -39,16 +39,20 @@ def has_next_page(self) -> bool:
     @override
     def next_page_info(self) -> Optional[PageInfo]:
         next_offset = self.next_offset
-        if next_offset is None:  # type: ignore[unreachable]
-            if self.has_more:
+        if next_offset is None:
+            if self.has_more:  # type: ignore[unreachable]
                 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.
+        # X-Next-Offset is the next page's absolute start, or 0 on the last page
+        # (the API's stop sentinel). Only a positive offset advances; the old code
+        # added the current page length on top, skipping a page per iteration.
+        if next_offset == 0:
+            return None
+
         return PageInfo(params={"offset": next_offset})
 
     @classmethod
@@ -86,16 +90,20 @@ def has_next_page(self) -> bool:
     @override
     def next_page_info(self) -> Optional[PageInfo]:
         next_offset = self.next_offset
-        if next_offset is None:  # type: ignore[unreachable]
-            if self.has_more:
+        if next_offset is None:
+            if self.has_more:  # type: ignore[unreachable]
                 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.
+        # X-Next-Offset is the next page's absolute start, or 0 on the last page
+        # (the API's stop sentinel). Only a positive offset advances; the old code
+        # added the current page length on top, skipping a page per iteration.
+        if next_offset == 0:
+            return None
+
         return PageInfo(params={"offset": next_offset})
 
     @classmethod

tests/test_pagination.py

@@ -41,12 +41,18 @@ def test_stops_cleanly_when_last_page_omits_x_next_offset(cls: PageClass) -> Non
 
 @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)
+    page = _page(cls, items=[{}] * 50, next_offset=200, has_more=False)
     assert page.has_next_page() is False
 
 
+@both_classes
+def test_stops_on_next_offset_zero_sentinel(cls: PageClass) -> None:
+    # 0 is the API's last-page sentinel. Assert via next_page_info directly,
+    # with has_more=True, so the has_more gate cannot mask the 0 handling.
+    page = _page(cls, items=[{}] * 50, next_offset=0, has_more=True)
+    assert page.next_page_info() is None
+
+
 @both_classes
 def test_stops_on_empty_page(cls: PageClass) -> None:
     page = _page(cls, items=[], next_offset=300, has_more=True)