Skip to content

fix: keep volumes of one series apart in dedup and the works table - #614

Merged
kikootwo merged 7 commits into
mainfrom
fix/599-series-volume-dedup
Nov 16, 2026
Merged

kikootwo merged 7 commits into
mainfrom
fix/599-series-volume-dedup

Conversation

@kikootwo

@kikootwo kikootwo commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

What changed

  • Series positions. Series page rows now carry their position label and the series ASIN. Modern pages read the series-header attribute; legacy pages read the h2 only when it is label-shaped and the title came from an h3/.bc-heading outside that h2. Positions are stored normalized ("1", "1.5"; ranges count as unknown). Search and author rows read the catalog sequence the same way, so a range such as "1-3" is unknown there too.
  • Position fallback. When a row has no position and local dedup would merge it, or a saved work links it to another row on the page (titles may differ), a catalog batch call fills it: response_groups=series, one call per 50 such rows, each with a 3 s deadline and no retry. Results are cached 24 h per region, series and ASIN (a book in two series keeps both positions); a non-transient error such as a 400 is cached as unknown; a 429, 5xx or timeout pauses these calls for 15 min (separately from the details fill pause). A failure leaves the position unknown.
  • Volume veto. A book joins a dedup group only if it is not a different volume of any member. Different means: same series with both positions known and different, or a trailing "Band/Book/Vol./Teil N" in the subtitle (or title) with the same series-name prefix. The works-table collapse also splits on a bare trailing title number. Unknown on either side stays compatible, so re-listings of one book keep merging.
  • Settled groups only. A dedup group is saved to the works table only when its positions are settled (every member has a position, or none is in a series). Other merges are display-only.
  • Safer saved merges. A saved group only absorbs works that lie wholly inside it; at most one touched work may hold ASINs outside the group. Rows move by ASIN, only works left empty are deleted, new rows use createMany({ skipDuplicates: true }), and one failing group no longer stops the rest.
  • Heal. On the series, search and author views and in watched series and author syncs, ASINs that a work wrongly links are detached before dedup and before the owned check. The heal acts on a work only when its canonical ASIN is in view, picks that ASIN the same way as the collapse, and names each new work after its class anchor. Each wrong volume moves to its own work in one transaction; only dedup_auto rows move; a rerun or a concurrent view changes nothing. In a watched author sync the second list heals only after the first list's groups are written. The heal never throws, so it never fails the page.
  • No schema change. Docs: integrations/audible.md (layout table, position fallback, veto levels, heal, merge rule, the five call sites, Fixed Issues), features/watched-lists.md, testing/e2e-harness.md.

Why

FallenLeave91 reported in #599 that vols 2 and 3 of a German light-novel series were missing from the series view, while vol 1 was available and vols 4 and 5 were requested. They proposed using the series ASIN plus the position as the guard and cleaning up the saved links; this PR does both. The diagnosis: the volumes share a title, narrator and runtime, local dedup never read series positions, the series page parser dropped the position label, and every multi-ASIN group was saved and merged every work it touched. One false merge therefore stuck, and it also leaked through the sibling lookup, so vols 2 and 3 could count as already owned for availability, request dedup and the watched owned check. Thanks to FallenLeave91 for the clear report and the proposal.

Checks

  • Fails before: the first commit's new tests fail on main (36 failed, 3 passed across 8 files); the follow-up commit's 8 new tests and 1 rewritten test fail on the code before it.
  • npx vitest related on the changed sources: 190 files, 2444 passed.
  • npm run test: 647 files, 11905 passed, 9 skipped, 0 failed.
  • npx tsc --noEmit clean; ESLint: no problems on new or changed lines (the remaining no-explicit-any hits are on untouched lines of older test files).
  • Docker e2e harness, branch image:
    • 599-series-volumes (live audible.de series B0H3C5X19W, region de, a seeded 1.3.0-style work linking vols 1-3, vol 1 in the library). On the first commit: 3 passed. The five issue ASINs listed once each, vol 1 available, vols 2 and 3 not; the database holds vols 1-3 in three works with no empty work; five concurrent views all return 200 with the same end state. Shots at 1280 light and 375 dark.
    • On the follow-up commit, two runs hit bursts of 503s from audible.de: one of the five concurrent reads ran out of retries and returned 404 (series not found), the other four returned 200 with every row labelled, and the heal test passed both times. The spec's 503 skip missed them because the error is logged on the lines after the message; the last commit fixes that skip (test only).
    • On the final commit: 3 passed, no 503s. Same heal checks as above, all five concurrent reads 200 with every row labelled, and the shots below.
    • Live page: modern layout on every read, every row with a position label, so no catalog fallback call was needed. Audible served no legacy page in these runs, so legacy label coverage is pinned by unit fixtures only; an unlabelled legacy row falls back to the batch call, also when titles differ and a saved work links the rows.
    • From the first commit: smoke 1 passed; upgrade from 1.3.0 (upgrade.spec.ts) seed and verify 2 passed, row counts unchanged.

Screenshots

Series page on the final commit, from the test stack (covers are stand-in tiles). Volumes 1 to 5 are separate cards; volume 1 is in the library.

Series page at 1280 px, light theme: volumes 1 to 5 as separate cards Series page at 375 px, dark theme

Risk and rollback

  • A false veto shows two copies of one book, and a watched series or author may request a book the library already has under another ASIN. The rules limit this: the heal and the persisted split only act on the same series with both positions known and different; the keyword rule needs the same series-name prefix on both sides; the bare-number rule only applies to the display collapse; unknown positions never veto.
  • Re-listing groups where only some members carry series data are no longer saved to the works table. They still merge on screen. Pairs seen only on search, author or watched-author results are never saved, because no position lookup runs there; they stay apart in storage until a series view settles them.
  • Watched sync picks a group's copy by metadata, not by what the library holds, so for a group that is not saved it can auto-request the copy you don't have. This is the accepted trade-off: counting a book as owned through its unsaved local group would bring back the Series volumes 2 and 3 disappear, apparently deduplicated because Audnexus titles match #599 failure for real different volumes.
  • When the catalog has no series data for two volumes they count as settled, so a search can save their merge; the next series view splits it again. Bounded and self-correcting.
  • Watched series and authors may request volumes an old false merge hid; ignoring one volume no longer hides the others.
  • Rollback: revert this PR. No migration; works created by the heal stay valid rows.

Closes #599

🤖 Generated with Claude Code

kikootwo and others added 7 commits November 15, 2026 19:40
Series volumes that share a title, narrator and runtime (translated light
novels) were merged into one book, and the merge was persisted, so the later
volumes vanished from the series page and showed as In Library.

- Series page rows carry their position label (modern series-header, legacy
  h2 when the title came from the h3) and the series ASIN; a catalog batch
  call fills missing positions only when a merge is proposed (24 h cache,
  15 min pause after a transient failure).
- Local dedup and the works-table collapse never merge known different
  volumes; only groups with settled positions are persisted.
- A persisted merge never absorbs a work holding ASINs outside the group;
  creates skip concurrent inserts and only empty works are deleted.
- Existing wrong links heal on the series, search and author views and in
  watched series and author syncs, before the owned check.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Cache fallback positions per region, series and ASIN, so a book in two
  series keeps both positions; a non-transient catalog error is cached as
  unknown instead of repeating on every view.
- Also fill unlabelled rows that a saved work links to another row on the
  page, from the heal's own work lookup (no extra query); the heal now
  takes the series ASIN and returns the filled rows.
- Search and author rows read the catalog sequence through
  normalizePosition, so a range stays unknown there too.
- The heal skips a work whose canonical ASIN is not in view, picks the
  canonical the same way as the collapse (shared canonicalByWork), and
  names a new work after its class anchor.
- The second watched author list heals only after the first list's
  groups are written.
- A legacy h2 never supplies the title used to read a position; the
  routes drop the dead catch on the heal, which never throws.

Refs #599

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The series scrape logs "Failed to scrape series detail <asin>" and then the
error ("status code 503") as JSON on the following lines, so the
same-line pattern never matched and a live 503 on one of the concurrent
reads failed the spec instead of skipping it. Look up to three lines on.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kikootwo
kikootwo marked this pull request as ready for review November 16, 2026 02:26
@kikootwo
kikootwo merged commit 6feb4fd into main Nov 16, 2026
1 check passed
@kikootwo
kikootwo deleted the fix/599-series-volume-dedup branch November 16, 2026 02:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Series volumes 2 and 3 disappear, apparently deduplicated because Audnexus titles match

1 participant