correct: schedule required mixed-case work first

Run the fixed and required correction layers for both mixed-case interpretations before either interpretation can spend the shared deadline on optional alignment work. Seed the later full searches with those candidates so ranking and capture accounting still consider both interpretations.

Refs #37

Author: codex

src/codex32/_cli_input.py

@@ -6,7 +6,7 @@
 import difflib
 import os
 import sys
-from collections.abc import Callable, Iterator
+from collections.abc import Callable, Iterator, Sequence
 from time import monotonic
 from typing import Any, Literal, cast
 
@@ -452,6 +452,8 @@ def _correction_candidates(
     deadline: float | None = None,
     capture_layers: list[tuple[int, int]] | None = None,
     fingerprint_match: Callable[[CorrectionCandidate], bool | None] | None = None,
+    seed_candidates: Sequence[CorrectionCandidate] = (),
+    required_only: bool = False,
 ) -> tuple[tuple[CorrectionCandidate, ...], bool, float | None, bool]:
     count = len(value.replace(" ", ""))
     targets, primary, reduced, _timed = _correction_plan(profile, byte_length, count, target)
@@ -468,6 +470,8 @@ def _correction_candidates(
         competitors=True,
         allowed=allowed,
         capture_layers=capture_layers,
+        seed_candidates=seed_candidates,
+        required_only=required_only,
     )
     if allowed is not None:
         candidates = tuple(candidate for candidate in candidates if allowed(candidate))

src/codex32/_competitors.py

@@ -173,8 +173,10 @@ def _search_competitors(
     frontier: dict[_Layer, int],
     deadline: float,
     allowed: Callable[[CorrectionCandidate], bool] | None,
+    *,
+    seed_candidates: Sequence[CorrectionCandidate] = (),
 ) -> tuple[tuple[CorrectionCandidate, ...], bool]:
-    results: dict[str, CorrectionCandidate] = {}
+    results = {candidate.artifact.text.lower(): candidate for candidate in seed_candidates}
     fixed: dict[int, CorrectionCandidate | None] = {}
     completed: set[_Layer] = set()
     try:

src/codex32/cli.py

@@ -577,12 +577,33 @@ def _correct(
     else:
         first_search = erased if erased != search_value else search_value
         retry_search = search_value if erased != search_value else None
+        seeded: tuple[CorrectionCandidate, ...] = ()
+        deadline = None
+        if retry_search is not None:
+            # Discover required candidates for both case interpretations before
+            # either full search can spend the shared deadline on optional
+            # alignment work.  Full searches below own capture accounting.
+            for required_value in (first_search, retry_search):
+                required, required_complete, deadline, _ = _correction_candidates(
+                    required_value,
+                    hrp,
+                    byte_length,
+                    immutable,
+                    deadline=deadline,
+                    seed_candidates=seeded,
+                    required_only=True,
+                )
+                if not required_complete:
+                    raise _CommandError("The correction search did not complete within ten seconds.")
+                seeded = required
         candidates, complete, deadline, ambiguous = _correction_candidates(
             first_search,
             hrp,
             byte_length,
             immutable,
+            deadline=deadline,
             capture_layers=capture_layers,
+            seed_candidates=seeded,
         )
         if complete and retry_search is not None:
             retry_candidates, complete, deadline, retry_ambiguous = _correction_candidates(
@@ -592,16 +613,15 @@ def _correct(
                 immutable,
                 deadline=deadline,
                 capture_layers=capture_layers,
+                seed_candidates=(*seeded, *candidates),
             )
             ambiguous = ambiguous or retry_ambiguous
             combined = (*candidates, *retry_candidates)
             if combined:
                 annotated = []
                 for item in combined:
                     volume, bits = _capture_mass(capture_layers, item.capture_volume)
-                    annotated.append(
-                        replace(item, cumulative_capture_volume=volume, capture_space_bits=bits)
-                    )
+                    annotated.append(replace(item, cumulative_capture_volume=volume, capture_space_bits=bits))
                 ranked = _best(annotated, prefer_common=byte_length == "?")
                 unique: dict[str, CorrectionCandidate] = {}
                 for item in ranked:

src/codex32/correction.py

@@ -910,6 +910,39 @@ def _correct_complete(
     capture_layers: list[tuple[int, int]] = []
     candidates: tuple[CorrectionCandidate, ...] = ()
     complete = True
+    if interpretation is not None:
+        # Establish both interpretations' fixed/required candidates before
+        # either interpretation can spend the shared deadline on optional
+        # alignment work.  These discovery passes use a private accounting
+        # ledger; the full searches below account every admitted layer once.
+        for input_context, value in inputs:
+            preflight_contexts: tuple[CorrectionContext, ...]
+            if input_context.expected_length is not None:
+                preflight_contexts = (input_context,)
+            else:
+                observed = len(value.replace(" ", ""))
+                contexts_list = []
+                for target in sorted({observed + delta for delta in (*range(-4, 5), -8, 8)}):
+                    candidate_context = replace(input_context, expected_length=target)
+                    try:
+                        _validate_context(candidate_context)
+                    except InvalidCorrectionInput:
+                        continue
+                    contexts_list.append(candidate_context)
+                preflight_contexts = tuple(contexts_list)
+            candidates, current_complete = _search_many(
+                preflight_contexts,
+                value,
+                primary=frozenset(
+                    c.expected_length for c in preflight_contexts if c.expected_length is not None
+                ),
+                deadline=deadline,
+                observed_text=damaged_text,
+                seed_candidates=candidates,
+                required_only=True,
+            )
+            if not current_complete:
+                return (), False
     for input_context, value in inputs:
         contexts: tuple[CorrectionContext, ...]
         if input_context.expected_length is not None:

src/codex32/indel.py

@@ -600,6 +600,7 @@ def _search_many(
     capture_layers: list[tuple[int, int]] | None = None,
     observed_text: str | None = None,
     seed_candidates: Sequence[CorrectionCandidate] = (),
+    required_only: bool = False,
 ) -> tuple[tuple[CorrectionCandidate, ...], bool]:
     deadline = monotonic() + 10 if deadline is None else deadline
     states = tuple(
@@ -615,6 +616,18 @@ def _search_many(
         )
         is not None
     )
+    if required_only:
+        states = tuple(
+            replace(
+                state,
+                counts={
+                    shape: values
+                    for shape, values in state.counts.items()
+                    if shape == _FIXED or shape.unit == 4 or shape.distance <= 2
+                },
+            )
+            for state in states
+        )
     frontier = _frontier(states, primary)
     layers_accounted = [] if capture_layers is None else capture_layers
     widths = {state.target: 5 * state.degree for state in states}
@@ -632,7 +645,18 @@ def finish(
     if competitors:
         from codex32._competitors import _search_competitors
 
-        return finish(*_search_competitors(states, frontier, deadline, allowed))
+        result = (
+            _search_competitors(
+                states,
+                frontier,
+                deadline,
+                allowed,
+                seed_candidates=seed_candidates,
+            )
+            if seed_candidates
+            else _search_competitors(states, frontier, deadline, allowed)
+        )
+        return finish(*result)
     results = {candidate.artifact.text.lower(): candidate for candidate in seed_candidates}
     # One global admission ledger, then fixed, required, and optional work.
     # The minimum supported public sphere is A<=2 / G<=2; deeper cutoffs

tests/test_cli.py

@@ -1928,6 +1928,18 @@ def test_correct_reranks_mixed_case_erasure_and_normalized_interpretations() ->
     assert "interactive confirmation required" not in result.stderr
 
 
+def test_correct_required_work_is_not_starved_by_erasure_alignment() -> None:
+    source = "ms10testsxxxxxxxxxxxxxxxxxxxxxxxxxx4nzvca9cmczlw"
+    damaged = "ms10TpstsxXxxxxxXxxxxxXxxxxXxxxxxXx4nzvcA9cmczlW"
+
+    result = _invoke(["correct"], damaged)
+
+    assert result.exit_code == 1
+    assert source in result.stderr
+    assert "did not complete within ten seconds" not in result.stderr
+    assert "interactive confirmation required" not in result.stderr
+
+
 def test_correction_hides_internal_candidate_reparse_failures() -> None:
     result = _invoke(["correct"], "ms12auxxxxxxxxxxxxxxxxxxxxxxxxxxxxxda3kr3s0s2swg")
 

tests/test_correction_bch.py

@@ -319,19 +319,30 @@ def test_mixed_case_candidate_still_searches_normalized_competitors(monkeypatch:
     )
     damaged = source[:position] + source[position].upper() + source[position + 1 :]
     candidate = CorrectionCandidate(codex32.parse_codex32(source), (), 1, 0, 0, None)
-    searched: list[tuple[str, tuple[CorrectionCandidate, ...]]] = []
+    searched: list[tuple[str, tuple[CorrectionCandidate, ...], bool]] = []
 
     def search(_contexts, value, **kwargs):  # type: ignore[no-untyped-def]
         seeded = kwargs["seed_candidates"]
-        searched.append((value, seeded))
+        searched.append((value, seeded, kwargs.get("required_only", False)))
         return ((candidate,), True) if len(searched) == 1 else (seeded, True)
 
     monkeypatch.setattr("codex32.indel._search_many", search)
 
     assert correct(CorrectionContext(Profile.MS, expected_length=len(source)), damaged) == (candidate,)
-    assert len(searched) == 2
-    assert "?" in searched[0][0] and "?" not in searched[1][0]
-    assert searched[1][1] == (candidate,)
+    assert len(searched) == 4
+    assert ["?" in value for value, _seeded, _required in searched] == [True, False, True, False]
+    assert [required for _value, _seeded, required in searched] == [True, True, False, False]
+    assert all(seeded == (candidate,) for _value, seeded, _required in searched[1:])
+
+
+def test_mixed_case_required_work_is_not_starved_by_erasure_alignment() -> None:
+    source = "ms10testsxxxxxxxxxxxxxxxxxxxxxxxxxx4nzvca9cmczlw"
+    damaged = "ms10TpstsxXxxxxxXxxxxxXxxxxXxxxxxXx4nzvcA9cmczlW"
+
+    result = correct(CorrectionContext(Profile.MS, expected_length=len(source)), damaged)
+
+    assert len(result) == 1
+    assert result[0].artifact.text == source
 
 
 @pytest.mark.parametrize("uppercase", (False, True))