fix(v2): give every collection one pagination contract and close four envelope holes - #6620

What

Fixes a set of v2 API contract defects found by stress-testing the live staging
surface across all 128 documented operations, and gives every v2 collection one
pagination contract instead of five divergent ones.

The defects, as observed

Root cause

limit was re-declared inline by every list. GET /workflows was copied from a
sibling and lost its .int(), so 1.5 passed validation and reached Postgres as
LIMIT 2.5. Same defect, independently, on GET /audit-logs. Meanwhile the same
param was validated five different ways across the API, and five collections
emitted nextCursor while accepting no limit at all — or accepting one and
silently discarding it, because Zod strips unknown keys unless the schema is
.strict().

So this is one problem — no shared pagination contract — wearing five hats, and
it is fixed once: v2PaginationFields() in lib/api/contracts/v2/shared.ts,
adopted by all 17 paged lists.

Why now, and what is user-visible

The v2-api rollout flag is off in production and enabled only for a
staging cohort. The four changes below are breaking the moment v2 goes GA, and
cost nothing today. This is the last cheap window.

Intentional, user-visible:

1. Five collections now enforce a default page size. /skills,
   /custom-tools, /secrets, /credentials, /knowledge previously returned
   every row; they now return 50 by default (matching every already-paged v2
   list) with limit up to 100 and a working cursor. A caller that read the
   full set in one request now gets a page and must follow nextCursor.
2. Unknown query params are rejected. Seven list queries gained .strict(),
   so a stray param is a 400 instead of being silently dropped. This is what
   turns "your limit was ignored" into an error you can see.
3. An empty cursor= is now a 400 on /workflows, /workflows/{id}/versions
   and /logs. This is a deliberate behaviour change to three endpoints that
   previously accepted it, not a bug fix — they returned 200 and treated the
   empty value as "no cursor". The other five paged lists already rejected it, so
   this aligns them; and a client that serialises an unset variable into
   cursor= silently restarts at page one on every request and loops forever,
   which a 400 surfaces immediately. Called out here so it can be objected to.
4. An offset cursor replayed under different filters or sort is now a 400 on
   /skills and /knowledge/{id}/documents. An offset names a position in one
   exact sequence; applied to a re-sorted or re-filtered one it names a different
   row, silently skipping or repeating results. The cursor is now stamped with
   the query state it was minted under and re-checked, which is what the keyset
   cursor's sort stamp has always done. limit is excluded from the stamp, so
   paging with a different page size still works.

Deliberately not changed: /files, /logs, /tables still truncate and
clamp an out-of-range limit rather than rejecting it. That leniency is
published in their OpenAPI description, so tightening it would break working
callers. It is now an explicit, named mode on the shared schema (outOfRange: 'clamp') and pinned by a test, rather than three hand-rolled copies.

Pagination, per collection

Both cursor schemes are the existing opaque base64-JSON codecs; no new format.

• Keyset (encodeSortedCursor, the /workflows model) — /custom-tools,
  /credentials, /secrets, /knowledge. Each sort now ends in a unique id
  key; knowledge previously tie-broke on createdAt, which cannot separate two
  rows created in the same millisecond and would repeat or drop a row at a page
  boundary.
• Offset (encodeCursor({offset}), the /knowledge/{id}/documents model) —
  /skills only, because it merges the 4-entry static builtin registry into the
  DB rows and re-sorts the merged array in JS. A SQL keyset cannot name a
  position inside that merged sequence: the builtins have no row for a WHERE to
  act on, and under createdAt asc they all sort ahead of every DB row. This is
  documented at the function.

Two correctness fixes that pagination forced:

• Secrets: a JS post-filter (row.type === 'env_workspace' || row.envOwnerUserId === userId)
  ran after the query. Trimming rows after the page is cut hands the caller
  fewer than limit while nextCursor still claims more, so it moved into SQL.
  It drops exactly the rows the JS filter dropped and never widens visibility.
• Skills: the list selected the full content column (up to 50k chars/skill)
  for every skill and discarded it in the presenter. The paged read projects
  without it.

Known limitation

/skills pagination bounds the response, not the DB read. Because the four
built-in skills merge in JS and the merged array is re-sorted before slicing,
LIMIT cannot be pushed down, so every page still reads the workspace's skill
rows. The projection now drops the content column (up to 50k chars/skill),
which is the large win; bounding the row count needs a second query to resolve
built-in shadowing across the truncation boundary, and that has a correctness
surface worth testing against a real database rather than landing blind here.

Not fixed, and why

405 responses still have no Allow header and an empty body. Next.js
generates that itself for a verb a route file does not export, before any Sim
code runs. Fixing it means either exporting rejecting handlers from all 77 v2
route files, or building a static path→methods table in proxy.ts that
duplicates the router. Both are worse than the defect; it is recorded as a known
gap in the new skill. Unknown paths are fixed by the catch-all.

limit=0x10 → 16, 1e2 → 100. Inherited from z.coerce.number()'s JS
numeric parsing. Both land inside the accepted range, so the bound is still
enforced. Left alone deliberately.

Preventing recurrence

list-pagination.test.ts already swept every v2 contract and pinned which lists
are paged. It now also asserts, over that same sweep:

• every paged list rejects a fractional limit (this is what caught
  /audit-logs, which my first pass missed because the assertion was originally
  a hand-written list of contracts)
• every list query is .strict()
• the three clamping lists still truncate rather than reject

Plus .agents/skills/v2-api-conventions/SKILL.md (projected to
.claude/commands and .cursor/commands by scripts/sync-skills.ts) documenting
the envelope, the status-code table, the pagination contract, and a checklist.
The test's failure messages point at it.

Verification

• bun run type-check, bun run check:api-validation:strict, bun run check:openapi — pass
• 4784 tests across app/api/v2, lib/api, lib/knowledge, lib/credentials,
  lib/secrets, lib/workflows, lib/skills, lib/table, lib/uploads — pass
• Each new test was proven to fail against the unfixed code before being kept

Not verified locally: no DB was exercised, so the generated keyset SQL is
covered by unit tests and the cursor algebra, not by a real paged read. A human
should confirm on staging: walk nextCursor to the end on each of the five newly
paged collections and check for duplicate or missing rows across page boundaries,
and confirm /api/v2/nonexistent returns the JSON 404.

Type of Change

• Bug fix
• Breaking change (three items flagged under "Intentional, user-visible" above)

Testing

• bun run type-check, bun run lint:check, bun run check:api-validation:strict, bun run check:openapi — all pass
• 4924 tests pass across app/api/v2, lib/api, lib/knowledge, lib/credentials, lib/secrets, lib/workflows, lib/custom-tools, lib/skills, lib/table, lib/uploads, lib/folders
• Every new test was reverted against unfixed source and confirmed red before being kept
• Not exercised against a database — see the verification note above for what a human should check on staging

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)