fix(waterdata): tighten ChunkPlan.max_chunks contract (n=1 passthrough, negative raises)

Two edges from the SOLID review of the parallel_chunks dial:

- max_chunks=1 ("no extra fan-out") took the fan-out path: on a fitting
  request it materialized axes and re-rendered them through iter_sub_args
  before _refine(1) no-oped, instead of the verbatim passthrough. Widen the
  passthrough guard to `max_chunks <= 1` so 0 (off) and 1 (no fan-out) both
  short-circuit to the trivial plan.

- A negative max_chunks silently no-oped. It can only be a caller bug (the
  public parallel_chunks(n) already rejects n < 1), so raise ValueError at
  construction rather than mask it.

Docstring + Raises updated; adds a unit passthrough test for max_chunks=1
and a negative-raises test.

Signed-off-by: thodson-usgs <thodson@usgs.gov>

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: thodson-usgs

dataretrieval/ogc/planning.py

@@ -331,13 +331,15 @@ class ChunkPlan:
         sub-request must fit.
     max_chunks : int, optional
         Hard cap on the plan's total sub-request count (default ``0`` = off).
-        ``0`` chunks only as much as ``url_limit`` requires — the most
-        conservative plan, fewest sub-requests. A positive cap fans the plan
-        out to up to ``max_chunks`` sub-requests overall (the
-        cartesian product across axes, never fewer than the byte budget
-        already forces) — capped as a whole, not per axis, so several
-        multi-value axes can't multiply past the cap. The plan never exceeds
-        the cap and may land below it when no whole split lands on it exactly.
+        ``0`` (off) and ``1`` (no extra fan-out) both chunk only as much as
+        ``url_limit`` requires — the most conservative plan, fewest
+        sub-requests — so a fitting request is a passthrough under either. A
+        cap of ``2`` or more fans the plan out to up to ``max_chunks``
+        sub-requests overall (the cartesian product across axes, never fewer
+        than the byte budget already forces) — capped as a whole, not per axis,
+        so several multi-value axes can't multiply past the cap. The plan never
+        exceeds the cap and may land below it when no whole split lands on it
+        exactly. A negative cap is a caller error and raises ``ValueError``.
         Set from the :func:`~dataretrieval.ogc.chunking.parallel_chunks` ``n``;
         see :meth:`_refine`.
 
@@ -364,6 +366,8 @@ class ChunkPlan:
     Unchunkable
         If the request needs chunking but even the singleton plan
         doesn't fit ``url_limit``.
+    ValueError
+        If ``max_chunks`` is negative.
     """
 
     def __init__(
@@ -373,6 +377,16 @@ def __init__(
         url_limit: int,
         max_chunks: int = 0,
     ) -> None:
+        if max_chunks < 0:
+            # ``0`` disables fan-out (the ambient default outside any
+            # ``parallel_chunks`` block); a negative cap is meaningless and can
+            # only be a caller bug, so fail loudly rather than silently no-op.
+            # The public ``parallel_chunks(n)`` already rejects ``n < 1``; this
+            # guards direct construction.
+            raise ValueError(
+                f"max_chunks must be >= 0 (0 disables fan-out); got {max_chunks!r}."
+            )
+
         self.args = args
         self.axes: list[_Axis] = []
         self.chunks: dict[str, list[list[str]]] = {}
@@ -424,9 +438,10 @@ def __init__(
         # A request that already fits and hasn't opted into finer chunking is
         # the common passthrough: leave ``axes``/``chunks`` empty so
         # ``total == 1`` and ``iter_sub_args`` yields the original args
-        # verbatim. Only when ``max_chunks`` asks for extra fan-out do
-        # we set the axes up to be refined below.
-        if fits and max_chunks <= 0:
+        # verbatim. ``max_chunks`` of 0 (off) or 1 (no extra fan-out) both mean
+        # "don't split", so both take this path; only ``max_chunks >= 2`` asks
+        # for extra fan-out and sets the axes up to be refined below.
+        if fits and max_chunks <= 1:
             return
 
         self.axes = axes

tests/waterdata_chunking_test.py

@@ -2134,6 +2134,27 @@ def test_zero_cap_preserves_passthrough():
     assert list(plan.iter_sub_args()) == [args]
 
 
+def test_unit_cap_preserves_passthrough():
+    """``max_chunks=1`` means "no extra fan-out", so a fitting multi-value
+    request stays the trivial passthrough (no axes, ``total == 1``,
+    ``iter_sub_args`` yields the original args verbatim) — identical to the off
+    (0) case, not a materialized one-chunk-per-axis plan."""
+    args = {"monitoring_location_id": ["A", "B", "C", "D"]}
+    plan = ChunkPlan(args, _fake_build, url_limit=8000, max_chunks=1)
+    assert plan.axes == []
+    assert plan.total == 1
+    assert list(plan.iter_sub_args()) == [args]
+
+
+def test_negative_cap_raises():
+    """A negative ``max_chunks`` is a caller bug, not a silent no-op: it raises
+    ``ValueError`` at construction. (The public ``parallel_chunks(n)`` already
+    rejects ``n < 1``; this pins the same guard on direct construction.)"""
+    args = {"monitoring_location_id": ["A", "B", "C", "D"]}
+    with pytest.raises(ValueError, match="max_chunks must be >= 0"):
+        ChunkPlan(args, _fake_build, url_limit=8000, max_chunks=-1)
+
+
 @pytest.mark.parametrize(
     ("max_chunks", "expected_pieces"),
     [(0, 1), (2, 2), (8, 8), (16, 10), (32, 10)],