Glossary violations across the package: full inventory for planning

Lies CONTEXT.md und ADR 0013 zuerst und prüfe anschließend die in §2 aufgeführten gemeinsamen Einstiegspunkte und Aufrufstellen, um die Namensentscheidung zu verstehen, die vor Änderungen erforderlich ist. Überprüfe nach dieser Entscheidung die Dateien und Tests aus §1 und §4, sofern welche hinzugefügt oder identifiziert werden; abgeschlossen bedeutet, dass die vereinbarten Korrekturen am Glossar vollständig sind, ohne die absichtlich beibehaltenen öffentlichen Namen oder das Kompatibilitätsverhalten zu ändern.

Scan of the whole package against CONTEXT.md, so the total cost is visible
before anything is scheduled. Grouped by what a fix actually costs, not by
severity.

Revised 2026-10-16 against main @ 776c8b0. Line numbers are re-checked.
Changes since the first scan:

• Done: cql2_services is gone. #446 replaced it with lists_as_cql2,
  one flag per API.
• Gone: the wrapped call site false positive at ogc/filters.py:60.
• New: ogc/policy.py:47, added in #446, which says site=A,B.
• New: sub-request, a second spelling of chunk that the first scan
  missed.
• New: stats.py, a call site for the §2 service= keyword.
• Dropped: the nwis.py row in §2, which is not one of the shared helpers.
• Moved to §5: the two WQP items. The service's own guide uses the word
  service for these endpoints.
• Smaller: the batch item. #413 kept batch in its independent-item
  sense.

#408 and #413, the children cut from this issue, were closed as not planned.

Ground rules used, both from ADR 0013 (#405):

• Core terms (ours — chunk, page, source, fan-out, dialect, leaf)
  take one spelling everywhere, identifiers included. A second spelling is a defect.
• Domain terms (monitoring location, collection) are fixed for prose only.
  An adapter keeps its service's spelling at its public surface, and that is not
  a violation. So nwis.get_record(service="dv") and wqp's Station stay.

What that leaves is below. Nothing here is a behaviour bug.

---

1. Internal, mechanical — no public surface

Safe to do in one PR each, or one PR total.

• OgcDialect.cql2_services. Removed in #446. Lists were sent as
  CQL2 per collection; they are now sent per API through
  lists_as_cql2: bool.

• OgcDialect.date_only_services is keyed by collection. It is declared
  at ogc/policy.py:49,73, read at ogc/requests.py:212, and set at
  waterdata/utils.py:87. It is the last holdout of the
  service→collection rename, and CONTEXT.md:316-317 records it under
  Known legacy names. The field is an internal dataclass field, so it can
  be renamed. Drop the CONTEXT.md sentence in the same PR.

• service_url names a collection's items URL. It is a local or parameter
  at ogc/requests.py:172,175,179,203,238,242,243,263,271.
  Excluded: nwdc.py:247-262, where it names the NWDC service's base
  URL. That use is correct.

• Shared OGC code says site in prose. This code serves both Water Data
  and NGWMN, so these sentences do not follow either service's spelling:
  ogc/chunking.py:3, ogc/planning.py:63,192, ogc/policy.py:47, and
  ogc/shaping.py:93. The examples site=, sites=[...], and site=A,B
  are also stale: Water Data's parameter is monitoring_location_id.

• Water Data adapter prose says site where its own parameter is
  monitoring_location_id. Most hits are doctest comments:
  - waterdata/cql.py:118
  - waterdata/measurements.py:238,246,254,409,624
  - waterdata/metadata.py:345,663,669,898,920,938,988,1068,1078
  - waterdata/nearest.py:278
  - waterdata/ratings.py:150,157
  - waterdata/time_series.py:212,227,449,662,667,676,683,881,894,895,901
  - waterdata/samples.py:343,390,418. Samples is a judgement call: its own
  vocabulary is location and monitoringLocationIdentifier.

  The first scan's list was partial; this one is the full regex scan.
  **Excluded deliberately:**
  - "site visit", which is a field-practice term of art, not a place.
  - *site type* in any spelling: `site_type_code`, `site-types`, `siteType`,
    and Samples' `dataProfile=site` and `"site"` column. These are the
    service's own vocabulary under `CONTEXT.md` *Monitoring location*.
  - URLs.
  - Python variables named `sites`: `waterdata/configuration.py:38` and
    `waterdata/metadata.py:939,941`.
  

• New: sub-request is used for chunk, a core term, so this is a
  second spelling.
  - Docstrings: _configuration_core.py:44,433,456,465,467,
  ngwmn.py:480,482, nwdc.py:488, and
  waterdata/configuration.py:62,64. The last three are public reference
  pages: they document the concurrency and parallel_chunks settings.
  - Prose: README.md (8 uses in the parallel_chunks section),
  docs/source/userguide/configuration.rst:105,479,500,
  docs/source/architecture/index.rst:325,
  demos/USGS_WaterData_ContinuousData_Examples.ipynb (4 uses), and
  demos/USGS_WaterData_Introduction_Examples.ipynb (1 use).
  - A test message string: tests/configuration_test.py:1584.

  *parallelism* used to mean fan-out is the same issue at a smaller scale:
  `ogc/chunking.py:113`, `docs/source/userguide/errors.rst:142`, and
  `README.md:188,199`. ADRs 0009 and 0011 mention it only as a rejected
  name, so they stay. #413 scoped this work and was closed as not planned.
  The defect remains.
  

• batch used informally for a set of chunks: transport/fanout.py:517
  ("a batch of chunks fails together"). Lowest value on this list.
  No longer listed: exceptions.py:22,328-337 and
  waterdata/ratings.py:137,140,350. These use batch for a set of
  independent items, the sense #413 chose to keep.

2. The service= keyword on shared helpers — one decision, ~10 call sites

The largest single cluster, and the one to decide before the mechanical work.

Five shared entry points take a service argument:

• ProgressReporter(service=) (progress.py:107)
• progress_context(service=) (progress.py:272)
• FanOut(service=) (transport/fanout.py:253)
• run_paginated(service=) (transport/pagination.py:168), which passes it on to FanOut
• resolve_next_url(service=) (transport/links.py:44)

What callers actually pass:

call site	entry point	passes	actually a
ogc/chunking.py:259	FanOut (via plan)	args.get("collection")	collection
ogc/engine.py:369	FanOut	collection	collection
ogc/engine.py:115	resolve_next_url	"OGC"	protocol
nwdc.py:382	run_paginated	"nwdc", beside adapter="nwdc"	adapter
nwdc.py:432,436	resolve_next_url	"Water Use"	service
waterdata/ratings.py:316,329,460	resolve_next_url, run_paginated, FanOut	"ratings"	collection
waterdata/stats.py:284	run_paginated	"observationNormals" / "observationIntervals"	endpoint

The nwis.py:324 row was dropped. That call is nwis.format_response(service="peaks"),
which is NWIS's own helper and is frozen under ADR 0005. It is not one of
these entry points.

The code itself admits the label is mixed. progress.py:116 says "The
service/collection being retrieved (e.g. daily, peaks)". The comment at
transport/fanout.py:265-268 calls service "a display label for the
progress line [that] is variously a collection name or prose." The argument
does more than label the progress line. resolve_next_url puts it into error
messages, "The {service} service returned an unusable next-page link"
(transport/links.py:87,100), so users read "The ratings service…" and "The
OGC service…".

CONTEXT.md still allows this, and should not. Known legacy names
(CONTEXT.md:319-320) says service "still means the external system in
transport and progress, where it labels a progress line. That usage is
correct." The call sites say otherwise: nwdc.py:382 passes the same string as
both service= and adapter=. That sentence should go, whichever option is
chosen below.

The options:

• Rename the parameter to what it is (label? subject?) and let each caller
  pass its own accurate name. The links.py messages would then need wording
  that does not assume a service.
• Keep service= and fix only the callers that can honestly supply a service.

None of the five entry points is public API, so either option is internal.
This needs a decision before the §1 work, since it touches the same files
(ogc/engine.py, ogc/chunking.py, waterdata/ratings.py).

3. Public surface — needs an ADR 0012 deprecation cycle

• "<service default>" printed by show_configuration()
  (configuration.py:888,889). The api_version setting from #422 added
  a second use. The glossary calls this an adapter default.
  configuration.py:653 uses the same phrase in the base_url()
  docstring. This is user-visible output, so changing it is a
  compatibility question rather than a docstring edit. #400 raised it and
  left it alone, because that PR's claim was that behaviour is unchanged.

The two WQP items that were here are now in §5.

4. Service vs adapter in the configuration modules

About 10 places in the configuration prose say service where CONTEXT.md
insists on adapter: "The scope is the adapter, not the service and not the
host". #400 fixed some in passing. These candidates remain:

• configuration.py:239, in a user-facing ConfigurationError: "a setting for
  one service goes on that adapter's configuration"
• configuration.py:559: "a service able to override an explicit setting".
  This means an adapter's default=.
• configuration.py:639,641: "the service passes its own", "the module of the
  service that uses it"
• configuration.py:651,653: "The service's own base", "no service default"
• _configuration_core.py:1300, in a user-facing ConfigurationError: "names
  one service and has no package-wide value"
• configuration.py:779: the same phrase in show_configuration output
• waterdata/configuration.py:68: "The settings this service reads"

Not uniformly wrong. A base URL, an API version, or a path segment really is
the service's, even when the setting is scoped to an adapter. So
_configuration_core.py:29,31,394,419,896-924 and
waterdata/configuration.py:47,56,60 probably stay. Each site needs a
judgement rather than a sweep. The two error messages and the
show_configuration line are user-visible, so they lean towards §3.

5. Settled — listed so they are not re-raised

• wqp.services_wqx3 / wqp.services_legacy (wqp.py:63,64) and
  wqp.wqp_url(service) / wqp.wqx3_url(service) (wqp.py:658,666, both in
  __all__). Moved here from §3. WQP's
  Web Services Guide
  calls these endpoints the Station Web Service, the Result Service, and
  the profile services, and treats dataProfile as a separate parameter.
  So service is that service's own word, which ADR 0013 keeps at the
  adapter's surface. What is actually wrong is the glossary.
  CONTEXT.md:124-126 says "WQP names its collections as profiles (Result,
  Station, Activity)", which mixes up the endpoint with dataProfile.
  #408 item 3 was the fix and was closed as not planned. It is still open:
  • Correct the WQP sentence in the CONTEXT.md Collection entry.
• waterdata.get_cql(service=): deprecated, removal 2027-08-09.
• waterdata.WATERDATA_SERVICES: permanent alias of WATERDATA_COLLECTIONS.
• waterdata.get_samples(service=) and SERVICES: these name a resource,
  not a service or a collection. Kept by decision; the reasoning is in Known
  legacy names.
• waterdata.get_codes(code_service=): reproduces the Samples API's own word.
• utils.query: one request, not a query; a frozen public path.
• dataretrieval.nwis service= throughout: frozen by the ADR 0005
  quarantine, including nwis.format_response(service=).
• NGWMN "provider": that service's own vocabulary.
• ChunkInterrupted, ChunkedCall: permanent aliases.
• batch for a set of independent items (SkippedItemWarning,
  SkippedRatingWarning). This is not a set of chunks.

---

Suggested order

1. Decide §2 first, because it dictates edits in the same files as §1.
2. Do §1 as one or two PRs. The sub-request item touches docs and notebooks,
   so it may be its own PR.
3. Fix the CONTEXT.md WQP sentence in §5. It is one line and blocks nothing.
4. Do §4 site by site.

§3 is a separate deprecation-cycle decision with no deadline pressure.

The pre-commit hooks measured in the comment below still apply, with smaller
targets now. Hook A reduces to \bdate_only_services\b, with 4 hits.
Hook B, over transport/ and ogc/, has 5 hits and 0 false positives, so the
filters.py reflow is no longer needed.