docs(architecture): describe current boundaries

Author: thodson-usgs

docs/source/architecture/decisions/0003-dependency-direction.rst

@@ -47,12 +47,11 @@ that hold today. Its allowlist is the authoritative inventory of exact temporary
 cross-boundary imports; this ADR owns the direction and rationale rather than a
 second copy of that mutable inventory.
 
-Phase 1 narrowed the permitted seams: NGWMN now uses only the OGC facade,
-``waterdata.utils`` no longer bulk re-exports private OGC helpers, and
-``ogc.shaping`` no longer depends on ``ogc.engine``. Focused fitness functions
-verify those boundaries and the acyclic OGC runtime graph; the architecture
-overview records the resolved debt.
+Focused fitness functions verify the current boundaries: NGWMN's only OGC
+dependency is the facade, ``waterdata.utils`` does not bulk re-export private
+OGC helpers, ``ogc.shaping`` does not depend on ``ogc.engine``, and the full OGC
+runtime graph is acyclic.
 
-The remaining allowlist should shrink as private seams move. Any growth requires
+The exact allowlist should shrink as private seams move. Any growth requires
 explicit architecture review, and a change to the dependency policy requires
 this ADR to be superseded.

docs/source/architecture/index.rst

@@ -67,13 +67,15 @@ Public service facades
 ^^^^^^^^^^^^^^^^^^^^^^
 
 ``dataretrieval.waterdata``
-    Modern USGS Water Data API facade. Typed getters delegate to the shared OGC
-    subsystem, with separate modules for statistics, ratings, and nearest-value
-    operations.
+    Modern USGS Water Data API facade. Typed getters use the four-symbol OGC
+    facade; Water-Data-specific utilities own service policy and wrappers
+    without re-exporting private OGC helpers. Statistics, ratings, and
+    nearest-value operations live in separate modules.
 
 ``dataretrieval.ngwmn``
-    NGWMN facade. Reuses the OGC subsystem with an NGWMN-specific base URL,
-    output identifiers, state translation, and :class:`OgcDialect`.
+    NGWMN facade. Its only OGC dependency is the public OGC facade, which it
+    configures with an NGWMN-specific base URL, output identifiers, state
+    translation, and :class:`OgcDialect`.
 
 ``dataretrieval.wateruse``
     NWDC Water Use facade. Builds CSV requests and follows ``Link`` headers.
@@ -213,22 +215,6 @@ These are documented so guardrails distinguish accepted current dependencies
 from new erosion. They should be removed through small, test-protected changes,
 not a rewrite.
 
-Resolved debt (Phase 1)
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-- ``ogc.shaping`` no longer lazy-imports ``ogc.engine`` — resolved by moving
-  schema lookup to ``ogc.requests`` and default dialect to ``ogc.policy``.
-- The OGC runtime import graph is now acyclic (enforced by test, facade
-  included — no implementation module imports ``dataretrieval.ogc`` root).
-- API-key policy is host-scoped at header construction and request execution;
-  cross-host redirects are stripped by both sync and async client hooks.
-- ``waterdata.utils`` no longer bulk re-exports private OGC symbols. It uses
-  the facade for generic adapter operations and keeps only narrow canonical
-  ``dates``/``shaping`` dependencies for Water Data policy. Tests import OGC
-  internals from their canonical modules directly.
-- ``ngwmn`` uses only the OGC facade (``dataretrieval.ogc``) — no direct
-  imports from ``ogc.policy``, ``ogc.requests``, or ``ogc.engine``.
-
 Change process
 --------------