fix!: reject non-ASCII headers at the model layer and resolve pagination follow-ups

[OmarAlJarrah]

Summary

Resolves the six open issues in the #167–#206 range (the rest were already closed as part of the earlier simplification sweep). Two themes: tightening header validation, and finishing the pagination-unification follow-ups.

Header validation (breaking)

Headers.Builder and HttpHeaderName.fromString previously accepted non-ASCII header names and values, rejecting only control characters. But both reference transports — OkHttp and the JDK HttpClient — reject non-ASCII, so a caller who set a non-ASCII header had it silently dropped from the wire on every transport, with only a per-request WARN log to show for it.

• Reject non-ASCII at the model layer (HeaderValidation): names and values are now validated to printable ASCII at construction, so a header no transport can send fails fast with IllegalArgumentException instead of vanishing mid-dispatch. Pre-1.0 validation break; no public signatures change in sdk-core, so its apiCheck is unchanged.

• Make the transport dropped-header log policy configurable. After the tightening, the only header that still reaches the transport's drop path is a model-valid but non-token one (e.g. a name with an interior space, which OkHttp/JDK reject under their stricter RFC 7230 token grammar). How loudly that surfaces is now the caller's choice via a new DroppedHeaderLogging enum, exposed on both transports' Builder and their BYO create(client, …) factory:

  • PER_OCCURRENCE — WARN on every drop (a per-request audit trail).
  • ONCE_PER_HEADER (default) — WARN the first time each header name is dropped by a transport, verbose thereafter: visible at default log levels without flooding a hot path.
  • VERBOSE_ONLY — never WARN; drops log only at verbose.

  The log level remains the operator's to filter via SLF4J; the policy only chooses the level and dedup the transport emits, which a level alone can't express.

Resolves #167, #168.

Pagination follow-ups

• Fix a stranded connection. byPage().stream() short-circuited by findFirst/limit/anyMatch left the held page's live Response open even under try-with-resources, because the stream had no close handler. The stream now registers the view's close() as its onClose, so closing the stream releases the held page. (pagination: byPage().stream() strands the held page's connection on short-circuit #203)
• Dedupe the pagination internals into one PaginationInternal.kt: the close-on-parse-failure invariant (parseOrClose, previously copy-pasted into the sync and async paginators), the iterator→Stream adapter (orderedStream), and the maxPages guard (requirePositiveMaxPages, now called from all four constructors). No behavior change. (pagination: dedupe close-on-parse-failure, the iterator→Stream adapter, and maxPages validation #204)
• Fix stale KDoc and reference docs left from the unification: PaginationStrategy.parse returns PageInfo (not Page); a page delivered to forEachPageAsync has its body typically already drained by the strategy; implementation-plan.md/refs-comparison.md now describe the three shipped strategies (no separate "token" strategy, no prev_cursor). (pagination: KDoc and docs still reference removed/renamed types after the unification #205)
• Add coverage for the response-close branches that had none: the sync parse-failure release, the drainPage throwing-sink-over-throwing-close intersection, and both closeStagedPageQuietly swallow paths. (pagination: add coverage for the untested response-close branches #206)

Testing

./gradlew :sdk-core:test :sdk-core:ktlintCheck :sdk-core:detekt :sdk-core:apiCheck, plus the equivalents for sdk-transport-okhttp and sdk-transport-jdkhttp, all pass locally. The transports' drop-not-throw tests were repurposed from a non-ASCII header (no longer constructible) to a model-valid non-token name (interior space) that the transports still reject. The DroppedHeaderLogging decision is unit-tested directly on RequestAdapter (the transport test modules run on slf4j-nop, so emitted logs can't be captured), with a Builder wiring smoke test per transport. New public API (DroppedHeaderLogging, the Builder setter, and the create overloads) is captured via apiDump.

Closes #167, #168, #203, #204, #205, #206