ADR 0007: Organize service adapters behind stable facades
=========================================================

Status
------

Accepted

Context
-------

A service facade can remain stable while its implementation grows for unrelated
upstream collections. Keeping every Water Data getter in one module coupled
changes to time series, monitoring metadata, field measurements, reference
catalogs, Samples, statistics, and generalized CQL queries. Active service
modules also relied on Python's implicit wildcard-export behavior, making their
intended public surfaces difficult to distinguish from imported helpers.

Decision
--------

``dataretrieval.waterdata.api`` is a compatibility facade with no collection
logic. Implementation functions are grouped by collection family in
``time_series``, ``metadata``, ``measurements``, ``reference``, ``samples``, and
``cql``. Existing focused modules continue to own ratings, nearest-value
selection, Statistics API execution, shared Water Data policy, and type
vocabularies.

The facade re-exports the established functions and preserves their signatures,
their identity at ``dataretrieval.waterdata``, and the private Samples constants
compatibility tests rely on. It does not rewrite their ``__module__``: each
function reports the family module that defines it, so a traceback names a file
that contains code. Collection-family modules do not
import one another; shared behavior belongs in Water Data policy, OGC, or
transport modules.

Active service and focused implementation modules declare explicit ``__all__``
exports. Deprecated NWIS remains outside this modernization. Service adapters do
not import another adapter's implementation to obtain transport behavior.

Return contracts remain service-specific. Tabular services generally return a
``(DataFrame, metadata)`` pair, while NLDI returns geospatial values directly,
StreamStats exposes response/domain objects, and ratings return parsed tables or
raw catalog features. Uniformity is not a reason to break these established
contracts.

Consequences
------------

- Collection changes have a smaller implementation and test blast radius.
- Existing package and ``waterdata.api`` import paths remain stable.
- Explicit exports make accidental public-surface growth reviewable.
- More modules require a maintained facade and executable signature/export
  snapshots.
- Tests are described as public-contract, adapter-contract, component, or
  cross-component layers without forcing a disruptive move of established
  files.

Compliance
----------

``tests/contracts/public_api_test.py`` freezes Water Data imports, signatures,
facade identity, and compatibility names. ``tests/architecture_test.py``
requires a logic-free facade, exact active-service exports, and separate OGC
request construction and schema execution. ``.importlinter`` keeps the
collection families independent of each other, holds NGWMN to the OGC facade,
and prevents lateral adapter reach-through.