perf (speculative): evaluate cross-title parallelism for `libby archive --all` — titles currently download strictly sequentially

[JavaGT]

Finding (performance-audit, 0300 run 2026-09-12)

Speculative — evaluate whether this is worth doing. Implementation is explicitly NOT the todo.

bin/libby.mjs:494-501 archives targets in a strict for…of await loop: with N loans, wall-clock is the sum of per-title archives. Within a single title, part downloads already run with bounded concurrency (mapLimit, src/pool.mjs), and HTTP keep-alive pooling landed in W7 — cross-title serialization is the remaining structural serialization in the heaviest command.

Why evaluate first, not implement

• Rate-limit tradeoff is an owner call: OverDrive throttles ("whoa", handled at bin/libby.mjs:506-511 with exit 3). Cross-title concurrency multiplies concurrent sockets against OverDrive hosts; whether N=2 is safe vs. whoa-prone needs a measured answer, not a guess.
• Measurement infra doesn't exist: an honest before/after needs a simulated multi-title archive (net-sim harness driving archiveAudiobook/archiveReadable with mocked clients) or real downloads; neither is built.
• Error-semantics design: today a mid-loop failure logs FAILED "title" and continues; whoa exits 3. Parallel completion interleaves logs and can surface several failures/whoas per run — the semantics need re-specifying before code.

Evaluation questions for the owner

1. Is a bounded mapLimit(targets, 2) (or 3) archive loop worth building given whoa risk?
2. If yes, fund the net-sim multi-title harness so the win is measured, not assumed.

Evidence

• bin/libby-archiver src: serial loop at bin/libby.mjs:494-501; per-title concurrency at src/archive.mjs:20/src/archive-read.mjs:27 (mapLimit).
• Context: W7 keep-alive pooling (bb616b3, perf-notes-net.md) removed per-request handshakes; T2 waves optimized loops/RAM.

[JavaGT]

Measured answer for evaluation Q1, and Q2's harness is now built — decision stays with the owner.

Harness landed (87f6a2b)

perf/archive-parallel-sim.mjs — drives the real archiveAudiobook over N loans against a latency-injected listen host + Thunder catalog (same fixture surface as the e2e suite: credential boundary stubbed, everything past it unmodified app code — cookie handshake, openbook decode, 3-wide part pooling, side trips, manifest). test/helpers/overdrive-sim.mjs:131 exports startServer for reuse (additive; full suite 100/100 green). The "measurement infra doesn't exist" blocker is gone.

Measured (6 titles × 12 parts × 200 KB, 150 ms/request think-time, median of 3; perf/results-archive-parallel.json)

loop	wall	speedup	listen-host connections
serial for…of (production)	7492 ms	1×	6
mapLimit(targets, 2)	3797 ms	1.97×	~30
mapLimit(targets, 3)	2964 ms	2.53×	~16

Near-ideal scaling because cross-title phases overlap almost perfectly: the win is real and mechanical, not speculative. Caveat: loopback think-time, not real OverDrive RTT/jitter — it bounds the win, it doesn't certify production behavior.

Whoa-risk framing for the owner call

• whoa is signaled only by the chip/sentry API (src/sentry.mjs:37); part downloads hit the listen host/CDN, which serve multi-MB media and are not where the throttle has been observed.
• Cross-title N=2 raises concurrent listen-host sockets ~5× (6 → ~30 here, real-world higher with RTT). Overlapping openLoan chip calls go from 1-at-a-time to 2–3-wide — that's the surface closest to the known throttle.
• Error semantics still need re-spec before any code: today a mid-loop failure logs FAILED and continues, whoa exits 3 (bin/libby.mjs:556-561); parallel completion interleaves logs and can surface several failures per run.

Decision unchanged, now with numbers: adopt mapLimit(targets, 2) (≈2× on the heaviest command, bounded socket growth) vs. keep serial. The harness re-measures any config: node perf/archive-parallel-sim.mjs --titles 10 --latency 80 ….

[JavaGT]

Follow-up: the readable (EPUB) path is now measured too — the earlier comment covered only archiveAudiobook. --kind read (perf/archive-parallel-sim.mjs, f6100ed) drives the real archiveReadable over N magazine loans (cfc1 pages + assets, same latency-injected fixture surface).

6 titles × 20 pages, 150 ms/request, median of 3 (perf/results-archive-parallel-read.json):

loop	wall	speedup	media-host connections
serial	7857 ms	1×	6
mapLimit(targets, 2)	3805 ms	2.06×	~18
mapLimit(targets, 3)	3627 ms	2.17×	~12

Nuance for the owner call: unlike the audio path (where N=3 reached 2.53×), the readable path gains almost nothing from N=3 — its per-title pipeline already fetches pages/assets 4-wide, so cross-title overlap saturates sooner. N=2 is the sweet spot on both paths (~2× on the heaviest command with the smallest socket growth), which shrinks the design space for whichever way this decision goes.

[JavaGT]

External consultation (Grok 4.6, cross-consultation lane): recommends C — keep serial, close with reasoning. Confidence: high.

Core argument: the loopback sim caps the upside at ~2× under friendly latency hiding; on a real home pipe the win can only shrink (bandwidth contention between concurrent title streams), and it's a background --all job, not an interactive path — paid for with a permanent parallel orchestrator, re-specified interleaved error semantics, and ~5× media sockets against a third party that has only ever shown us whoa on the auth API. Serial is the predictable, spec-matchable contract.

Recorded as advisory — measured evidence in the comments above stays as-is. Owner decision pending.

[JavaGT]

Closed per the owner-accepted consultation (Grok verdict C): keep the serial archive loop.

The reasoning, for the record: the measured ceiling is ~2× under loopback-friendly latency hiding; on a real home connection concurrent title streams contend for bandwidth, so the live win can only shrink — and it's a background --all job, not an interactive path. Against that stands a permanent parallel orchestrator, re-specified interleaved error semantics, and ~5× the media-host concurrency against a third party whose only observed throttle (whoa, exit 3) lives on the auth API that cross-title parallelism would widen. Serial is the predictable, spec-matchable contract.

The measurement harness (perf/archive-parallel-sim.mjs, both paths) and all numbers stay in this ticket's history and the repo, so this decision can be revisited with fresh data if OverDrive's tolerance or the usage pattern ever changes.