docs(detect): tidy review-history residue in chunked-validation prose

Four inline prose touches in the chunked-validation module. No code or
test behaviour changes; only doc/comment rewording so the source reads
as a standalone spec rather than a narrated diff against prior versions.

- `chunk_candidates` docstring: state the ``max_entities_per_call > 0``
  precondition positively, point at the two upstream enforcement layers,
  drop the "so we do not re-check it here" coda.
- `_dispatch_chunk` defensive-guard comment: keep the substantive reasons
  (empty-facades precondition, loud named error vs. ``raise None``, guard
  survives ``python -O``) and drop the assert-vs-if comparison that only
  makes sense in the context of the review exchange that introduced it.
- `_dispatch_chunk` docstring: replace "matching the pre-failover
  contract" with a direct statement of the single-alias-pool behaviour
  ("no alternate alias to try").
- `test_system_prompt_default_none_is_forwarded_untouched` comment:
  tighten the "accidentally inject a placeholder" framing to just state
  the current recipe contract and what the test pins.

Made-with: Cursor

Author: lipikaramaswamy

src/anonymizer/engine/detection/chunked_validation.py

@@ -160,10 +160,10 @@ def chunk_candidates(
 ) -> list[list[tuple[Any, EntitySpan]]]:
     """Partition the ordered (candidate, seed) pairs into chunks of at most ``max_entities_per_call``.
 
-    ``max_entities_per_call`` is assumed positive. It is validated upstream by
-    ``ChunkedValidationParams`` (``Field(gt=0)``) and by
-    ``AnonymizerDetectConfig.validation_max_entities_per_call`` (``gt=0``), so
-    we do not re-check it here.
+    Assumes ``max_entities_per_call > 0``; positivity is enforced upstream at
+    ``ChunkedValidationParams.max_entities_per_call`` and
+    ``AnonymizerDetectConfig.validation_max_entities_per_call`` (both
+    ``Field(gt=0)``).
     """
     return [list(ordered[i : i + max_entities_per_call]) for i in range(0, len(ordered), max_entities_per_call)]
 
@@ -321,11 +321,11 @@ async def _dispatch_chunk(
     We use ``PydanticResponseRecipe`` so the facade appends JSON task
     instructions and parses the response into ``RawValidationDecisionsSchema``.
 
-    Single-alias pools get no additional attempts — the loop runs exactly
-    once and re-raises the original exception, matching the pre-failover
-    contract. Multi-alias pools get ``len(pool)`` total attempts. If every
-    pool member raises, the *last* exception propagates so DataDesigner
-    records the row as a ``FailedRecord`` via ``NddAdapter._detect_missing_records``.
+    Single-alias pools run the loop exactly once and re-raise the original
+    exception (no alternate alias to try). Multi-alias pools get
+    ``len(pool)`` total attempts. If every pool member raises, the *last*
+    exception propagates so DataDesigner records the row as a
+    ``FailedRecord`` via ``NddAdapter._detect_missing_records``.
 
     Each failover attempt is logged at WARNING so operators can correlate
     degraded pool members with run-level failure-rate spikes.
@@ -374,15 +374,14 @@ async def _dispatch_chunk(
                     exc,
                 )
 
-    # Defensive: ``facades`` is non-empty by caller contract
-    # (``chunked_validate_row`` builds it from the configured pool, which the
-    # config validator requires to be non-empty). After a non-empty pool fully
-    # exhausts, ``last_exc`` is guaranteed set and we re-raise it. If we ever
-    # reach this point with ``last_exc is None``, the precondition was
-    # violated — raise a loud ``RuntimeError`` rather than ``raise None``
-    # (which would produce ``TypeError: exceptions must derive from
-    # BaseException``). Using a real check instead of ``assert`` so the guard
-    # survives ``python -O``.
+    # ``facades`` is non-empty by caller contract: ``chunked_validate_row``
+    # builds it from the configured pool, and the config validator requires
+    # a non-empty pool. After the loop, ``last_exc`` is therefore set and
+    # we re-raise it. The ``None`` branch exists only to give a loud,
+    # named error if that precondition is ever violated (rather than
+    # ``raise None``, which would surface as ``TypeError: exceptions must
+    # derive from BaseException``) and to keep the guard live under
+    # ``python -O``, which strips ``assert``.
     if last_exc is None:
         raise RuntimeError(
             "_dispatch_chunk was called with an empty facades list; "

tests/engine/test_chunked_validation.py

@@ -411,10 +411,10 @@ def test_system_prompt_is_forwarded_to_facade(self) -> None:
         assert sentinel in forwarded
 
     def test_system_prompt_default_none_is_forwarded_untouched(self) -> None:
-        # When the caller leaves ``system_prompt`` unset, nothing upstream of
-        # the recipe should synthesize one. Whatever the recipe produces from
-        # ``None`` is what the facade sees (today: ``None``). This test pins
-        # that we don't accidentally inject a placeholder along the way.
+        # The recipe maps ``None`` input to ``None`` output; this test pins
+        # that no intermediate layer replaces it with a placeholder string
+        # when ``ChunkedValidationParams.system_prompt`` is left at its
+        # default.
         text = "Alice spoke."
         spans = [_entity_span("a", "Alice", "first_name", 0, 5)]
         candidates = _candidates_schema(("a", "Alice", "first_name"))