Make failures actionable and harden validation, APIs, and CI

[thodson-usgs]

Summary

This PR started as an agent-documentation refresh and an error-message cleanup. Exercising each proposed remedy exposed several cases where following the message caused a second failure or, worse, returned a plausible but wrong result. The scope now covers the resulting validation, correctness, API, geographic-code, test, and CI changes as one caller-correctness pass.

Actionable argument validation

dataretrieval._validation now owns the recurring argument-check shapes and their message vocabulary:

Helper	Contract
require_one_of	one scalar from a closed vocabulary
require_argument	one required argument, returned with its type narrowed
require_together	an all-or-none argument group
require_any_of	at least one filter from a permissive group
require_exactly_one	one sufficient alternative, returned as (name, value)
reject_together	mutually exclusive but individually optional arguments

The helpers are adopted across NLDI, NWDC, NWIS, WQP, OGC dates, Water Data CQL/reference/nearest, and state normalization. Messages identify the caller's parameter spelling, state the problem, and name a correction the caller can execute.

The ratings file_type validator remains local deliberately: it validates a collection and reports every invalid member, while require_one_of validates one scalar. Their shared formatting is centralized through render_options; adding a second collection-helper interface for one caller would be speculative.

Compatibility note

Malformed argument values now consistently raise ValueError. The deprecated nwis.query_waterdata, query_waterservices, and get_record paths therefore no longer use their historic TypeError for missing filters, incomplete bounding boxes, or unknown services. TypeError remains for genuinely mistyped arguments such as a non-string sites value.

Correctness fixes found by executing the remedies

• NLDI validates origin conflicts in one pass and requires data_source before constructing a navigation URL. A missing source can no longer become a literal /None path whose 200 response looks like a genuine empty result.
• waterdata.get_nearest_continuous adds time and monitoring_location_id to an explicit properties list because both are required to select one row per target and monitoring location. This is a documented returned-column-shape change.
• nwdc empty selectors and error envelopes now produce actionable text rather than advice that repeats the same failure or prints a raw validation-object list.
• Shared metadata and state helpers no longer recommend parameters or replacement getters that their caller does not accept.
• NWIS's invalid query_waterdata("ratings", ...) route now points to waterdata.get_ratings, including the dict return shape and feature-ID keys callers need to use it.
• Date formatting names the public argument, rejects overlong intervals rather than truncating them, and does not advertise durations on the ratings path that refuses them.
• Pagination, credential-install, RDB, and adapter-specific failures now distinguish retryable recovery from deterministic corrections.

nldi._query_nldi still turns a 200 non-JSON body into an empty GeoDataFrame. That is an existing documented exception, not changed here, and is called out in AGENTS.md so it is not mistaken for the general error policy.

Additional API and data behavior

• waterdata.get_cql(..., max_rows=N) exposes the OGC engine's existing total-row cap. limit remains page size; a small limit alone can increase request count rather than cap results.
• State normalization now includes American Samoa, Guam, the Northern Mariana Islands, Puerto Rico, and the US Virgin Islands under their ANSI/FIPS codes. Name, postal, FIPS, and US:<FIPS> forms normalize alike for adapters whose upstream service supports them.
• The Water Data metadata collection vocabulary includes countries, and its hand-maintained reference docstring is contract-tested against that vocabulary.
• NEWS.md records the public behavior and exception changes.

Coverage and CI

Coverage is now a branch-coverage ratchet rather than an informational number. The branch adds behavior-focused tests for dispatch, malformed response envelopes, NLDI navigation, nearest-row grouping, configuration fallbacks, date handling, pagination, and previously uncovered public getters.

The ratchet runs in the existing OS/Python test matrix, blocks on every non-Windows leg, and reports informationally on Windows where POSIX-only skips measure a smaller suite. Version-conditional and environment-unreachable import arms are excluded explicitly so Python 3.10, 3.13, and 3.14 enforce the same measurement. Complexity and dependency-direction jobs remain fast and independent.

Agent and contributor documentation

• AGENTS.md now starts from CONTEXT.md, explains placement rules rather than carrying a stale file inventory, names .importlinter as the authoritative dependency map, documents the current test/tooling gates, and records the executable-remedy policy.
• CONTEXT.md corrects the definition of a setting: a public keyword such as ssl_check is not automatically part of configuration resolution.
• CONTRIBUTING.md documents branch coverage, platform-dependent local measurements, complexity ratchets, import-contract ownership, and the periodic structural-health sweep.

Validation

• Focused validation/ratings tests: 45 passed
• Full offline suite: 1114 passed, 12 deselected
• Branch coverage: 98.97%, ratchet met
• ruff check . and ruff format --check .
• mypy in strict mode
• lint-imports: 8 contracts kept
• xenon and complexipy
• Sphinx HTML build succeeds (5 pre-existing warnings)