pagination contract audit derived

{
  "input": {
    "body": {
      "contract": {
        "sort": [
          {
            "field": "updated_at",
            "mutable": true
          }
        ],
        "style": "offset",
        "offset_parameter": "offset",
        "page_size_default": 100
      }
    },
    "type": "http",
    "method": "POST",
    "bodyType": "json"
  },
  "output": {
    "type": "json",
    "example": {
      "sound": false,
      "style": "offset",
      "limits": {
        "maxHops": 50,
        "maxTiers": 50,
        "maxAttempts": 1000,
        "maxFindings": 500,
        "maxSortKeys": 20,
        "maxEndpoints": 200
      },
      "passed": false,
      "complete": false,
      "findings": [
        {
          "code": "PAGE_SIZE_NOT_BOUNDED",
          "detail": "No page_size_max is declared, so a caller may request an unbounded page and read the whole collection in one request. That is a denial-of-service vector and a cost nobody budgeted for."
        },
        {
          "code": "SORT_HAS_NO_UNIQUE_TIEBREAKER",
          "detail": "The sort is on updated_at and none of those is declared unique. Rows that compare equal have no defined relative order, so a caller walking the pages can receive a row twice and never receive one of i..."
        },
        {
          "code": "OFFSET_PAGINATION_OVER_MUTABLE_SORT",
          "detail": "Pagination is by offset and the sort includes the mutable field(s) updated_at. A row whose sort value changes between two page requests moves across the offset boundary, so it is counted twice or skip..."
        }
      ],
      "request_id": "example-request",
      "service_id": "pagination_contract_audit",
      "assumptions": [
        "A sort needs a key declared unique for page boundaries to be defined; without one, rows comparing equal may be returned twice or not at all.",
        "Uniqueness and mutability are read from the contract as the caller declares them, because neither can be derived from a field name.",
        "Offset and page styles are treated as position-by-count, which is what makes a mutable sort field a correctness problem rather than a preference."
      ],
      "limitations": [
        "Only declared policy is read. Nothing is executed and no system is observed, so these findings are what the configuration implies rather than what a running service did.",
        "Nothing is fetched. The policy is supplied, so an arbitrary configuration can be audited without access to the system it governs.",
        "No request is made, so whether the service implements the contract it declares is not checked here."
      ],
      "observed_at": "2026-10-02T00:00:00.000Z",
      "not_examined": [
        "TOTAL_COUNT_SEMANTICS_NOT_DECLARED: The contract does not say whether a total count is exact, estimated or absent. A caller that renders a page count from an estimate shows a page that does not exist."
      ],
      "finding_count": 3,
      "page_size_max": null,
      "sort_key_count": 1,
      "service_version": "1.0.0",
      "findings_by_code": {
        "PAGE_SIZE_NOT_BOUNDED": 1,
        "SORT_HAS_NO_UNIQUE_TIEBREAKER": 1,
        "OFFSET_PAGINATION_OVER_MUTABLE_SORT": 1
      },
      "max_total_results": null,
      "page_size_default": 100
    }
  }
}