fix: add shared network resilience seam (tablassert.net)

[SkyeAv]

Adds src/tablassert/net.py, a stdlib-only network-resilience seam that classifies each failure as transient or permanent and retries transient ones with bounded jittered backoff — and rewires BABEL downloads onto it. Fleet motivation: a 16-worker run over 42,981 PMC articles lost 2,194 of 2,507 queue failures (87.5%) to DNS-shaped errors ([Errno -2] Name or service not known) during a resolver-outage burst; single-attempt fetches turned a recoverable blip into a terminal skip.

Classification

• One ordered table, net.is_transient: DNS (URLError wrapping socket.gaierror), connection loss, timeouts, HTTP 408/425/429 and every 5xx, bare OSErrors with network errnos, and optional-library exceptions (openai/litellm/httpx) matched by name — never imported — are transient. ValueError/TypeError/KeyError, non-CC-license PermissionError, no-OA-files FileNotFoundError, other 4xx, and local-errno OSErrors (ENOSPC, EACCES) fail fast.
• Never raises, walks the chain: hostile exceptions overriding __bool__/__cause__/errno cannot break classification; __cause__/__context__ are walked (≤ 3 links) so library wrappers keep their code.

Retry driver

• net.retry_transient: 4 attempts, 1.0 s base doubling to 20.0 s, sleeps summing to ≤ 60.0 s; Retry-After headers and (reset after …) quota hints set the wait (max(hint, jittered step)), capped at 60 s. Exhaustion raises a coded NetworkTransientError (network-transient).

BABEL rewire

• cli.download_babel_file drops its hand-rolled predicate for net.is_transient. Three intentional, test-pinned deltas: 425 now retried; permanent local OSError (ENOSPC on .part) fails fast instead of burning 5 attempts / 75 s; bare network-errno OSError keeps the 5-attempt guarantee. Range resume, streaming, and the retries=5 schedule unchanged.
• Loguru pickling fix: retry warnings bound error=str(e) — the enqueue=True sink silently dropped lines binding raw HTTPError objects (unpicklable BufferedReader).

Design

• Stdlib-only: the seam must be importable from tablassert.cli, which installs without the [agent] extra — tenacity/urllib3.util.retry would land in the base install.
• Deferred: no docs/api/net.md page (the errors.DOCS_URL remediation is tracked as a separate project in 18.0.0's changelog).

Testing

• uv run pytest tests/test_net.py -q --no-cov -n 0 → 29 passed in 0.08s
• uv run pytest tests/test_cover_cli.py -q --no-cov -n 0 → all pass (BABEL classification deltas pinned)
• Full gate on the stack tip: uv run pytest -q → 1565 passed, 15 skipped; uv run ruff check . / ruff format --check . → clean; uv run pyright → 0 errors; make test-rust + cargo clippy --manifest-path rust/Cargo.toml --all-targets -- -D warnings → clean
• All tests offline: no sockets, no real sleeps (--durations=10 max 0.17 s); independent Tier-2 review passed after two repair rounds (regex classification, loguru pickling).

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: c821b1d9-9dfc-4599-adad-61138c630053

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}