suaveplan/openspec/archive/2026-05-02-pagination-spec-conformance/proposal.md

# OpenSpec Change: pagination-spec-conformance

- **Change ID**: pagination-spec-conformance
- **Package**: `@suaveplan/pagination`
- **Status**: PROPOSED
- **Date**: 2026-04-26

## Summary

Bring `openspec/specs/pagination/spec.md` into agreement with the shipped implementation, add `**Verified by:**` lines to every requirement, and rectify the `retroactively ticked` historical hazard so `bun scripts/openspec-conformance.ts @suaveplan/pagination` exits 0. The implementation is solid (100/100/100/100 coverage, property-based tests, OTel instrumentation, AbortSignal throughout); the original spec was authored ahead of implementation and several MUST clauses drifted from the chosen behaviour. This change reconciles wording with reality and pins three previously-implicit scenarios in a new `cursor-pagination.spec-conformance.test.ts` file. No public-API changes; no breaking changes for consumers.

## Current state — drift inventory

| Spec ID | Drift | Resolution |
|---|---|---|
| PG-01 | Spec says malformed cursor MUST throw `INVALID_CURSOR`; impl returns `null` from `decodeCursor` so callers can branch without catching. `validateCursor` returns `false`. | Reword: malformed cursor returns `null` from decode and `false` from validate; throws are reserved for caller-driven error paths. |
| PG-02 | Spec says `normalizeCursorRequest` MUST throw `INVALID_LIMIT`; impl clamps limit to `[1, maxLimit]` and floors fractional values. | Reword: normalisation clamps + floors; structured throws are reserved for cursor decode failures inside `fetchAfter`/`fetchBefore` when the caller provides an aborted signal. |
| PG-03 | Spec calls `calculateCursorMeta(opts)` with `pageInfo`/`edges`; impl is `(edges, hasMore, direction?, totalCount?)`. | Reword to match impl signature; semantics (forward/backward `hasNextPage`/`hasPreviousPage`) preserved. |
| PG-04 | Spec signature `fetchAfter(adapter, cursor, opts)`; impl is `fetchAfter(adapter, cursor, opts, getSortValue)` (extractor required because adapters are field-agnostic). | Reword: extractor is part of the signature; pre- and post-fetch abort checks throw `PAGINATION.ABORTED`. |
| PG-05 | Spec says throw on `page<1` / `limit≤0`; impl clamps + floors with sensible defaults from `PaginationDefaults`. | Reword: clamping is the contract; throws are not part of normalisation. `pageToOffset`/`offsetToPage` round-trip property is asserted by `tests/property.test.ts`. |
| PG-06 | Spec calls `paginateArray(array, opts)` and references `currentPage`/`nextPage`/`previousPage` meta fields; impl is `paginateArray(items, page, limit)` and meta is `{ page, limit, total, totalPages, hasNext, hasPrevious }`. | Reword to match impl; out-of-bounds page returns empty `data` with correct meta — pinned by new spec-conformance test. |
| PG-07 | Spec says `mergeOffsetResponses` returns a full `OffsetPaginatedResponse<T>`; impl returns `{ data, total }` (the merged total is taken from the first response — the merged window has no single page/limit). | Reword: merge returns `{ data: T[]; total: number }`; consumers wrap with `createOffsetResponse` if they need the full envelope. |
| PG-08 | Matches impl. | Annotate. Stability is pinned by new spec-conformance test. |
| PG-09 | Spec calls `keysetPaginate(array, opts)`; impl is `keysetPaginate(items, lastKeys, opts)` (lastKeys is an explicit parameter, not nested in opts, because `null` first-page is the common case). | Reword to match impl. |
| PG-10 | Spec says `decodePageToken` MUST throw `INVALID_TOKEN` on bad structure; impl returns `null` (consistent with cursor / keyset decode paths). `hashFilters` is order-independent (sorted-key concatenation). | Reword: invalid → `null`; `INVALID_TOKEN` is reserved for the schema-layer `PageTokenPayloadSchema.parse` boundary. |
| PG-11 | Spec says `encodePageToken` accepts `clock?: Clock`; impl exposes `clock?` on `CursorPaginationOptions` for adapter-backed fetchers but the encode path is timestamp-free (tokens carry value/sort/filter only). | Reword: injectable `Clock` lives on `CursorPaginationOptions` and adapter helpers; tokens themselves carry no timestamp so no clock is needed inside `encodePageToken`. |
| PG-12 | Matches impl. | Annotate. |
| PG-13 | Spec lists `count`, `find`, `findOne` on `PaginationAdapter<T>`; impl exposes `count` + `fetchPage(offset, limit, sort?, filter?)` (the two methods every cursor/offset/keyset path actually needs). | Reword to match impl. `findOne` is removed from the interface; consumers compose it from `fetchPage(0, 1, ...)` if they need it. |
| PG-14 | Matches impl, but every schema is consumer-facing; flag as `// schema: boundary-only` to suppress conformance-script warnings. | Annotate; add boundary-only marker to `pagination.schemas.ts`. |
| PG-15 | Matches impl. | Annotate. |
| PG-16 | Matches impl (`pagination.request.total`, `pagination.page.size`, `pagination.encode_decode.duration_ms`). | Annotate. |
| PG-17 | Matches impl (`tests/property.test.ts`). | Annotate. |
| PG-18 | Spec says three separate bench files; impl ships a single consolidated `pagination.bench.ts` covering all three round-trips. | Reword: consolidated benchmark file is acceptable; baseline numbers belong in README. |
| PG-19 | Matches impl. | Annotate. |
| PG-20 | Matches impl. | Annotate. |

## What changes

1. Rewrite each requirement body in `openspec/changes/pagination-spec-conformance/specs/pagination/spec.md` under `## MODIFIED Requirements`, mirroring the impl.
2. Append a `**Verified by:**` line to every requirement (PG-01..PG-20).
3. Add `src/cursor/cursor-pagination.spec-conformance.test.ts` with four pinned scenarios:
   - PG-01 cursor encode/decode preserves value type (string vs number).
   - PG-08 keyset cursor stability (idempotent encode + decode∘encode∘decode fixed point).
   - PG-06 `paginateArray` never throws for out-of-bounds pages.
   - PG-03 `Connection<T>` / `Edge<T>` generics are threaded through `createConnection` / `createEdges` (type-level via `expectTypeOf`).
4. Add `// schema: boundary-only` markers to `src/schemas/pagination.schemas.ts` so the conformance script suppresses the schemas-at-boundary warnings (every schema is consumer-facing).
5. Re-run `bun scripts/openspec-conformance.ts @suaveplan/pagination` and confirm exit 0.

## Impact

- Public API unchanged.
- One new test file (~110 lines).
- `openspec/specs/pagination/spec.md` requirement bodies reworded to match impl; 20 `**Verified by:**` lines added.
- One marker comment added to the schemas file.