fix(assets): address cursor-review verified findings

- Mint next_cursor on every cursor-supported sort, not only when 'after'
  was supplied. A first request (no 'after') previously returned
  next_cursor=None, leaving cursor mode unreachable from a clean start.
- Over-fetch limit+1 so an exactly-full terminal page doesn't mint a
  spurious cursor pointing at a phantom next page.
- Map crafted out-of-range microsecond cursors (OverflowError / OSError
  in datetime construction) to 400 INVALID_CURSOR instead of leaking 500.
- Bump MAX_CURSOR_VALUE_LENGTH 256 -> 512 to match the AssetReference
  name column max; without this, a long-named asset minted a cursor the
  same server then refused on the next request. Cross-runtime byte
  identity with cloud is unaffected because no cloud cursor ever carries
  a value > 256 (cloud schema doesn't permit it).
- Return None from _encode_next_cursor when the boundary row carries a
  NULL sort value (e.g. an Asset without size_bytes backfilled), instead
  of silently encoding 0 and mis-positioning the keyset.
- Fix schemas_in.py comment so it matches actual handler behavior
  (last_access_time + 'after' raises 400, does not fall back).
- Add AssetsApiError schema + 400 response to GET /api/assets in
  openapi.yaml so generated clients know the INVALID_CURSOR envelope.
- Extend integration coverage: first-page mint, exact-multiple terminal
  page, cursor walks for created_at/updated_at/size sorts, datetime
  overflow surfaces as 400 not 500.
- Add unit coverage for datetime overflow and 512-char round-trip.

app/assets/api/schemas_in.py

@@ -60,8 +60,9 @@ class ListAssetsQuery(BaseModel):
     limit: conint(ge=1, le=500) = 20
     offset: conint(ge=0) = 0
     # Opaque keyset cursor. When supplied, `offset` is ignored. Cursor pagination
-    # is supported for sort values `created_at`, `updated_at`, `name`, `size`;
-    # `last_access_time` falls back to offset/limit.
+    # is supported for sort values `created_at`, `updated_at`, `name`, `size`.
+    # Supplying `after` together with `sort=last_access_time` returns
+    # 400 INVALID_CURSOR; that sort only supports offset/limit.
     after: str | None = None
 
     sort: Literal["name", "created_at", "updated_at", "size", "last_access_time"] = (

app/assets/services/asset_management.py

@@ -279,7 +279,11 @@ def list_assets_page(
     """
     cursor_value: object | None = None
     cursor_id: str | None = None
-    use_cursor_mode = after is not None and sort in _CURSOR_SORT_FIELDS
+    # Mint next_cursor on every page where the sort is cursor-supported, not
+    # only when the request itself arrived with a cursor. Otherwise a first
+    # request (no `after`) returns next_cursor=None and the client can never
+    # enter cursor mode.
+    mint_cursor = sort in _CURSOR_SORT_FIELDS
 
     if after is not None:
         if sort not in _CURSOR_SORT_FIELDS:
@@ -293,6 +297,11 @@ def list_assets_page(
             )
         cursor_value, cursor_id = _resolve_cursor_value(payload), payload.id
 
+    # Over-fetch by one row so we can distinguish "exactly `limit` rows total
+    # remaining" from "more rows past this page" without a second query. Drop
+    # the sentinel before returning.
+    fetch_limit = limit + 1 if mint_cursor else limit
+
     with create_session() as session:
         refs, tag_map, total = list_references_page(
             session,
@@ -301,7 +310,7 @@ def list_assets_page(
             exclude_tags=exclude_tags,
             name_contains=name_contains,
             metadata_filter=metadata_filter,
-            limit=limit,
+            limit=fetch_limit,
             offset=offset,
             sort=sort,
             order=order,
@@ -309,6 +318,14 @@ def list_assets_page(
             after_cursor_id=cursor_id,
         )
 
+        next_cursor: str | None = None
+        if mint_cursor and len(refs) > limit:
+            # There's at least one more row past this page — mint a cursor from
+            # the last row of the page (i.e. index `limit - 1`, since we
+            # over-fetched), and drop the sentinel.
+            next_cursor = _encode_next_cursor(refs[limit - 1], sort)
+            refs = refs[:limit]
+
         items: list[AssetSummaryData] = []
         for ref in refs:
             items.append(
@@ -319,10 +336,6 @@ def list_assets_page(
                 )
             )
 
-        next_cursor: str | None = None
-        if use_cursor_mode and len(refs) == limit:
-            next_cursor = _encode_next_cursor(refs[-1], sort)
-
         return ListAssetsResult(items=items, total=total, next_cursor=next_cursor)
 
 
@@ -337,15 +350,24 @@ def _resolve_cursor_value(payload: CursorPayload) -> object:
     return payload.value  # name, str-typed
 
 
-def _encode_next_cursor(ref, sort: str) -> str:
-    """Mint a cursor pointing at *ref* for the given sort dimension."""
+def _encode_next_cursor(ref, sort: str) -> str | None:
+    """Mint a cursor pointing at *ref* for the given sort dimension.
+
+    Returns None when the boundary row carries a NULL sort value (e.g. an asset
+    record whose size_bytes hasn't been backfilled). Continuing pagination
+    across a NULL boundary is undefined under keyset ordering — better to
+    truncate cleanly here than to mint a cursor that mis-positions.
+    """
     if sort == "name":
         return encode_cursor("name", ref.name, ref.id)
     if sort == "size":
-        size = ref.asset.size_bytes if ref.asset is not None else 0
-        return encode_cursor("size", str(size), ref.id)
+        if ref.asset is None or ref.asset.size_bytes is None:
+            return None
+        return encode_cursor("size", str(ref.asset.size_bytes), ref.id)
     # created_at / updated_at — DB datetimes are naive UTC; attach tz before encoding.
     value = ref.created_at if sort == "created_at" else ref.updated_at
+    if value is None:
+        return None
     return encode_cursor_from_time(sort, value.replace(tzinfo=timezone.utc), ref.id)
 
 

app/assets/services/cursor.py

@@ -32,9 +32,16 @@ class InvalidCursorError(ValueError):
 
 # Wire-format length caps. Cursors are user-controlled, so caps protect the
 # decode path from oversized allocations and downstream SQL predicates from
-# unbounded strings. Same numbers as cloud/common/pagination/cursor.go.
+# unbounded strings.
+#
+# MAX_CURSOR_VALUE_LENGTH is 512 (vs cloud's 256) to fit OSS's
+# `AssetReference.name` column max (String(512)) — otherwise a long-named
+# asset would mint a cursor the same server then refuses on the next request.
+# Cloud's data model has shorter names so its lower cap is fine there;
+# cross-runtime byte-identity is unaffected because no real cloud cursor ever
+# carries a value > 256.
 MAX_ENCODED_CURSOR_LENGTH = 1024
-MAX_CURSOR_VALUE_LENGTH = 256
+MAX_CURSOR_VALUE_LENGTH = 512
 MAX_CURSOR_ID_LENGTH = 128
 
 
@@ -122,7 +129,12 @@ def decode_cursor_time(payload: Optional[CursorPayload]) -> datetime:
         micros = int(payload.value)
     except ValueError as e:
         raise InvalidCursorError(f"value is not a valid timestamp: {e}") from e
-    return _unix_micros_to_datetime(micros)
+    try:
+        return _unix_micros_to_datetime(micros)
+    except (OverflowError, OSError, ValueError) as e:
+        # Crafted out-of-range microseconds (e.g. > datetime.MAX_YEAR) blow up
+        # in fromtimestamp / datetime construction. Map to 400, not 500.
+        raise InvalidCursorError(f"value is out of representable range: {e}") from e
 
 
 def decode_cursor_int(payload: Optional[CursorPayload]) -> int: