# Pagination Adoption — hub-core utils in Core Hub

**Updated:** 2026-07-09  
**Workplan:** `CORE-WP-0009-T05`  
**Decision:** Defer DB pagination; document trigger for adoption

---

## Current state

Core Hub `/api/v2` list endpoints (`hubs`, `hub-capability-manifests`,
`api-consumers`, `widgets`, `interaction-events`) load full result sets and wrap
them with an in-memory helper:

```python
def page(data: list[dict[str, Any]]) -> dict[str, Any]:
    return {"data": data, "count": len(data)}
```

Production table counts remain small (bootstrap/smoke scale). Inter-Hub
compatibility fixtures expect `{data, count}` without `limit`/`offset` query
params today.

## hub-core utility

`hub_core.utils.pagination` provides sync SQLAlchemy `PageParams` and
`apply_pagination()` for `Select` queries. Core Hub uses **async**
SQLAlchemy (`AsyncSession.execute(select(...))`).

## Decision

**Defer adoption** until either:

1. A list endpoint needs server-side `limit`/`offset` (or cursor) for performance, or
2. Inter-Hub compatibility spec adds optional pagination query parameters.

When triggered:

- Add `hub_core.utils.pagination_async` (or equivalent) with the same bounds as
  `PageParams` (limit 1–1000, offset ≥ 0).
- Apply to list routes before `session.execute`.
- Extend contract fixtures and ops-hub smokes for paginated responses.

## Non-action

Do not import sync `apply_pagination` into async routes without an async adapter.
Do not change response shape until compatibility spec records the addition.