Story 1271: Matter List Search
This walkthrough records the backend contract change for GET /app/matters: firm-facing matter search moves server-side, and the temporary cursor compatibility path is retired.
Contract Shape
| Surface | Before | After |
|---|---|---|
| Search | The app filtered the loaded page client-side. | The endpoint accepts q and filters before pagination. |
| Pagination request | cursor / limit and page / page_size both existed. |
page / page_size are the only matter-list pagination parameters. |
| Pagination response | The response included nextCursor plus numbered metadata. |
The response includes total, page, and pageSize. |
Search Semantics
q is trimmed. Empty or whitespace-only values behave as if no search was supplied. A non-empty value is an escaped, case-insensitive substring match against title, case reference, displayed matter reference such as M-001, and numeric matter number.
The search predicate combines with status, type, openedFrom, and openedTo using AND semantics, so total describes the full searched and filtered result set before pagination.
Decision Record
The endpoint-specific pagination decision is recorded in docs/design/matter-list-cursor-retirement.md. It explains why limit was removed instead of kept as an alias and why substring search is acceptable at current volumes.
Rollout Coordination
This is a breaking contract cleanup. Land it with, or immediately before, the app consumer story pramaan-spec#1272 so the app mirror consumes q and stops preserving nextCursor.