[shergin]

Answers #49: a directive for lists paged by page number, decided in docs/decisions/a-paged-list-merges-its-pages-by-number.md.

• @paged(key:, page:) on the list field inside the field that takes the page. The pages merge into a client record of the container's type on the container's parent, keyed by the list field and its arguments with the container's other arguments, with its own page info, apart from the server's page record two lists may share. The first page replaces, the next appends, a page already merged rewrites its span in place, any other is ignored; only the fields the operation selected of the container follow the page.
• The container's lens gains hasNext (the merged pageInfo.hasNextPage, nothing else), isLoadingNext and loadNext(), which runs the operation that owns the lens with the next page and the operation's other variables; no @refetchable is needed, and a refetch of the owner replaces the list.
• The compiler declares the directive beside @cacheExpiration, so Relay's front end types its arguments and a server never sees it; the lowering checks the directive's place, key, variable, container and page info and reports at the directive. Swift format 21, Kotlin format 5.
• Both runtimes: a merge by page number beside the cursor modes, the client link in the ingest, the paged list in the resolution, the availability check and the collector, the re-merge for incremental parts, and Owner carrying the query that owns its lenses.
• Held by the cases paged-notes-1 to -3, paged-notes-2-edited, paged-characters-1, friends-1 and friends-2 and the script paged; unit tests on both sides for loadNext(); compiler tests for every diagnostic and the plan shape; goldens and sources re-blessed.
• Docs: terminology (the Page entry promoted to the paged list), the two principles, the contract, the changelog's Unreleased section, the README, the site's lists guide and concepts page, the comparison, the porting table and the agents recipe.

Not chosen, each with its reopening condition in the record: offsets, a previous page, edge directives into a paged list, and a second reading of the flag for a page info that is not pageInfo { hasNextPage }.

The local check list passes: boundaries, the compiler build, the Swift build with tests, the hostile-name sweep, the Swift tests in debug and release, library evolution, the iOS Controllers build, cargo fmt --check, cargo clippy --all-targets -- -D warnings, cargo test; also the Kotlin jvmTest (172) and the Kotlin goldens module, and the site build.