Refactor OGC and fan-out internals

[thodson-usgs]

Summary

This PR applies exactly five metric-gated architecture refactors to the OGC and fan-out internals. All five were retained because each reduced meaningful local and package complexity, preserved behavior, kept every coarse PySCN score non-regressing, introduced no clone group, and kept all dependency contracts intact.

The work is based on upstream/main at c3242789 and is independent of draft PR #353. It changes no public interface or import path.

Recent PySCN history

I measured the last 15 first-parent commits with the same PySCN version and verified project-root resolution for every report.

• PR refactor(transport)!: share fan-out execution across services #355 (702c6ad9) temporarily lowered health 81→80 and cohesion 100→95.
• PR refactor: police the fan-out abstractions #364 (3474c3cc) recovered health 80→82, cohesion 95→100, dependency score 75→80, and depth 9→8.
• PR refactor(ogc): one entry into the engine; retire fetch_ogc_request #368 (0ff534c2) lowered architecture 87→82 without changing overall health; PR refactor(ratings): drive both stages through the shared executor #369 restored architecture to 87.
• PR refactor: one advisory mechanism, and the right category for each #375 (ed307b7d) moved architecture 87→84, again without changing health.
• PR refactor: one home for option validation; retire dead engine wrappers #372 (ced0d1ea) moved duplication 8.7%→9.5% and clone groups 5→6 while health remained 82.
• PR fix(ogc): keep the frame type when a result is empty #373 (c3242789) made no PySCN change.

The sixth clone group after #372 is Type-4 semantic similarity between wqp.get_results and wqp._what. Those functions have distinct service behavior, so this PR intentionally does not collapse it. It likewise does not optimize intentional collection-family getter resemblance or treat Python leaf modules in a reported “zone of pain” as defects.

Five measured iterations

#	Internal seam	Decision	Local evidence
1	FanOut._raise_failures	Retain	_run: CC 11→4, cognitive 33→8, nesting 4→3; high-risk functions 21→20
2	_advance_structure	Retain	_split_top_level_or: CC 11→6, cognitive 15→8, nesting 7→3
3	_format_date_params	Retain	_construct_api_requests: CC 6→4, cognitive 7→3, nesting 2→1
4	_normalize_request_arg	Retain	prepare_request_args: CC 8→4, cognitive 17→6, nesting 5→2
5	_largest_splittable_chunk	Retain	ChunkPlan._refine: CC 10→5, cognitive 24→6, nesting 4→2

No experiment was reverted: every candidate met the retain gate. Iteration 4 briefly moved duplication from 9.4737% to 9.5070% without adding a group; iteration 5 returned it to baseline.

Updated PySCN scores

Metric	Baseline	Final
Health / grade	82 / B	82 / B
Complexity score	95	95
High-risk functions	21	20
Average cyclomatic complexity	2.362903	2.334218
Average cognitive complexity	5.793011	5.564987
Dead-code score / issues	100 / 0	100 / 0
Duplication score	70	70
Duplicated fragments	9.4737%	9.4737%
Clone groups	6	6
Coupling	100	100
Cohesion	100	100
Dependencies / depth	80 / 8	80 / 8
Architecture	84	84

Architecture-metrics corroborates the local trend: maintainability index improved in all five touched modules, max CC fell in filters 12→10, requests 13→12, and fanout 13→8, and every touched module retained identical afferent/efferent coupling. FanOut LCOM96b moved slightly 0.840→0.856 when failure precedence became a named method; this is treated as a holistic trend rather than outweighing the method's large local complexity reduction, stable PySCN cohesion, unchanged coupling, and clearer ADR-0008 policy seam.

Architecture

• Date-shaped parameter ownership now stays in ogc.dates.
• CQL structure-state transitions stay behind a private filter-parser seam.
• Request normalization separates argument selection from one-argument interpretation.
• Chunk refinement separates pure split selection from plan mutation.
• Fan-out failure precedence remains inside FanOut and preserves ADR 0008 behavior.
• No new module, dependency edge, public symbol, or external dependency was added.
• All seven ADR-backed import-linter contracts remain intact.

An independent Standards/Spec review found no hard or spec findings. It noted one mild same-module Feature Envy judgment call for _largest_splittable_chunk; no action was recommended because the selector is pure, private, and local to the planning module.

Validation

• pytest -q tests -k 'not test_nwis_service_live': 813 passed, 12 deselected, 57 expected warnings
• Focused iteration suites: 140, 196, 280, 187, and 216 tests passed respectively
• ruff format --check .
• ruff check .
• mypy --strict dataretrieval: all 58 source files passed
• Xenon thresholds passed
• complexipy threshold passed
• lint-imports: 7 kept, 0 broken
• git diff --check