/person/{id}/tagged_images ignores the page parameter, so allTaggedImages yields duplicates

[adamayoung]

Origin: Surfaced by the live probing done for issue #437 (delivered as PR #486). Deliberately deferred — it is a distinct defect from the media-type modelling that PR was scoped to, and its fix is undecided. PR #486 records the measurement in knowledge/tmdb-api-notes.md.

Problem

/person/{id}/tagged_images ignores the page query parameter. The library sends it — Sources/TMDb/Domain/Adapters/Person/PersonTaggedImagesRequest.swift builds page as a query item, and TMDbPersonService.taggedImages(forPerson:page:) exposes it — but TMDb returns the same rows regardless, so the parameter is inert.

As of main @ d455d45 (behaviour is server-side, so no library line is wrong; the issue is that the public API advertises pagination the endpoint does not honour).

Failure scenario

Measured 2026-08-20 against person 17419, 24 requests / 378 rows:

• ?page=1, ?page=2 and ?page=3 return identical result ids.
• The response's own page field is 0 on every request — not 1, and not the requested value.
• It reports total_pages: 2 and total_results: 35 while only ever serving one page's worth of rows.

Two concrete consequences:

1. allTaggedImages(forPerson:) yields duplicates. PagedAsyncSequence advances page and requests the next one; the API serves the same rows again. A caller iterating the sequence sees each image repeated once per page walked, and the sequence terminates only because total_pages is finite — not because the data was exhausted.
2. taggedImages(forPerson:page:) silently ignores its own argument. A caller passing page: 2 gets page 1's contents with no error and no indication.

The captured fixture Tests/TMDbTests/Resources/json/tagged-image-pageable-list.json preserves the "page": 0 quirk verbatim, and TaggedImagePageableListTests.swift asserts it with a comment, so the evidence is pinned in-repo.

Fix sketch

The library cannot make the endpoint paginate; the question is what to do about advertising it.

Options, roughly in increasing cost:

1. Document it. Add a DocC note on taggedImages(forPerson:page:) and allTaggedImages(forPerson:) stating that TMDb ignores page here, so the sequence may repeat rows. Cheapest, non-breaking, and honest.
2. Deprecate the page parameter on this one method, since it cannot do anything.
3. De-duplicate in allTaggedImages by tracking seen image ids and stopping when a page adds nothing new. This changes PagedAsyncSequence behaviour for one endpoint and needs care — see knowledge/gotchas.md → An all-dropped page doesn't shorten the sequence — it ends it, which is the neighbouring hazard.
4. Report it upstream to TMDb as an API bug, and do (1) meanwhile.

Worth confirming first whether other PageableListResult endpoints share the quirk, or whether tagged-images is unique — a one-endpoint fix and a library-wide one are different changes. Nothing else was measured this way.

Decision needed: whether to document, deprecate, or de-duplicate. All three are defensible and they are not mutually exclusive.

Breaking class: none for option 1; source-breaking for option 2; behavioural for option 3.

[adamayoung]

Triage 2026-08-21 — main @ b9853695. Stays Backlog, blocked. P1 / S.

Decision needed: does the library merely document that /person/{id}/tagged_images ignores page, deprecate the page parameter on that one method, or make the paged sequences stop when the server returns a page it did not request?

Defect re-confirmed live (2026-08-21). curl against person 17419 with ?page=1|2|3: identical result ids every time, "page": 0, total_pages: 2, total_results: 35, but only 20 rows ever served. Reproduced on four people — 17419 (tp=2), 1245 (tp=2), 287 (tp=1), 6193 (tp=1).

The page: 0 field is a red herring for termination. PagedAsyncSequence.Iterator uses its own currentPage counter (:126, :218) and caps on page.totalPages (:171-184) — so with tp=2 it fetches page 1, buffers 20, fetches page 2, gets the same 20, and yields them again. PagedPagesAsyncSequence does the same at :160-179.

A consequence the body does not draw out: total_results 35 vs 20 rows served means 15 rows are permanently unreachable. De-duplication buys correctness but not completeness.

Scope closed — tagged images is unique. The body's "worth confirming first whether other PageableListResult endpoints share the quirk" is now answered. I swept 31 paginated endpoints across every service family (movie/tv/person popular, top_rated, now_playing, upcoming, on_the_air; discover movie+tv; all five search endpoints; trending all/movie/person; similar/recommendations/reviews/lists; keyword movies; the three changes lists; v3 /list/{id}). Every one returned page == requested with distinct rows across pages. This is a one-endpoint problem, not a library-wide one — which rules out needing a general fix on that ground alone.

A fifth option the body does not name. PageableListResult.page is a non-optional Int and both iterators already know the page they asked for, so guard page.page == currentPage else { finished = true } in the sequence primitives would fix this generically without an endpoint special-case, and the sweep shows no other endpoint would be affected. This is a genuine third design branch and part of why the item is not ready.

Actively misleading doc, not mentioned in the issue: PersonService.swift:163 states "- Precondition: page can be between 1 and 1000" on taggedImages(forPerson:page:). That is false for this endpoint — the parameter does nothing. Whatever option is chosen, that line must change; the convenience at PersonService+Defaults.swift:144 and both pagination wrappers carry the same silence.

No existing test reproduces it. Tests/TMDbIntegrationTests/PersonPaginationIntegrationTests.swift:51-76 uses person 287, whose total_pages is 1 — the sequence stops after one page and never duplicates. A reproducing test needs a person with more than 20 tagged images (17419 or 1245 both work today).

Corrected pointers:

• Request builder → Sources/TMDb/Domain/Services/People/Requests/PersonTaggedImagesRequest.swift:12-17 (the body's Domain/Adapters/Person/ does not exist).
• Four public surfaces are affected, not two — allTaggedImagesPages(forPerson:) drives the identical PagedPagesAsyncSequence loop and duplicates whole pages, and the no-page convenience overload shares the misleading DocC (PersonService+Pagination.swift:93-99).

Repo evidence already pinned and accurate: the fixture tagged-image-pageable-list.json carries "page": 0 verbatim, TaggedImagePageableListTests.swift:28-31 asserts it with an explanatory comment, knowledge/tmdb-api-notes.md:447-450 records the measurement, and knowledge/gotchas.md:1222 holds the neighbouring hazard.

No ADR rules on it. I checked all 29. ADR-0002 (Changes auto-pagination) and ADR-0007 (document-instead-of-build) are the closest precedents; neither settles this. ADR-0019 is a different failure on the same endpoint.

Window note: latest tag is 19.0.0, so the 20.0.0 breaking window is still open (knowledge/next-major.md:16-24) — a deprecation is available now rather than deferred. Worth knowing when the decision is made.

Why blocked, not ready: Ready-test clause 2 fails outright — the body poses four options, says all are defensible and not mutually exclusive, and the evidence narrows scope without picking one. Promoting it would reproduce exactly the pattern #472 exists to complain about. Sized S as the outcome, not the analysis.