Expose bounded full-string correction

Add frozen, slotted correction context, edit, and candidate records plus a deterministic public API over the existing fixed BCH decoder. Keep the HRP and separator immutable, reparse every candidate, constrain wallet context before return, and keep BIP39 correction API-only.

Collapse private decoder diagnostics into the public no-candidate result, route the CLI through the public boundary, and add all-profile, malformed-corpus, differential, and bounded fuzz evidence while preserving the 3,000-line package limit.

Author: BenWestgate

README.md

@@ -103,6 +103,21 @@ assert isinstance(secret, MasterSeed)
 additional = derive_share([a, c], "d")
 ```
 
+Full-string correction returns immutable, untrusted candidates and requires an
+explicit registered profile:
+
+```python
+from codex32 import CorrectionContext, Profile, correct
+
+candidates = correct(CorrectionContext(Profile.MS), "ms10tests?xxxxxxxxxxxxxxxxxxxxxxxxx4nzvca9cmczlw")
+for candidate in candidates:
+    print(candidate.artifact)
+```
+
+The HRP and separator are never corrected. A candidate is checksum-valid, not
+proof that it belongs to the intended wallet; compare it with the physical
+backup.
+
 Worksheet residue correction is also available without disclosing the backup's
 profile or length:
 

docs/architecture.md

@@ -54,7 +54,7 @@ semantics. No artifact crosses the parsing boundary until every stage passes.
   hidden state.
 
 Private Python names are convention rather than access control. The supported
-surface is the 20-name package `__all__`; direct use of private helpers is
+surface is the 25-name package `__all__`; direct use of private helpers is
 unsupported but remains in the review scope.
 
 ## Size budget

docs/correction.md

@@ -6,6 +6,34 @@ boundary. A bounded structural adapter is a cuttable pre-v1 gate in
 the plan's completeness, performance, size, and audit requirements, v1 remains
 fixed-length-only and structural correction moves to v1.1.
 
+## Public full-string API
+
+`correct(CorrectionContext(...), damaged_text)` accepts every fixed registered
+profile. Its context may constrain the complete canonical length, the
+five-symbol threshold-plus-identifier header, and ordinary share indices that
+are already in use. The HRP and separator are immutable. A differing expected
+length receives no structural search in the current fixed-length
+implementation.
+
+The function returns an immutable tuple of `CorrectionCandidate` records in
+deterministic rank order. A valid unchanged string returns one candidate with
+no edits; no valid correction returns `()`. Malformed context raises
+`InvalidCorrectionInput`. Every candidate contains an ordinary parsed `Share`
+or `Secret`; the decoder never exposes a checksum-only result.
+
+Fixed correction emits only `substitution` and `erasure` edits. Insertions,
+deletions, and transpositions are reserved record kinds for the cuttable
+structural gate. Edit coordinates are zero-based from the end of the
+data/checksum body. `observed` and `replacement` preserve string case.
+`estimated_search_bits` is zero for fixed decoding, `erasures_filled` and
+`addend_hamming_weight` expose the deterministic secondary ranking inputs, and
+`crc_padding_match` is a boolean only for an `ms` S candidate. It is `None` for
+shares and other profiles and never affects validity.
+
+The API completes its fixed search without a deadline or provisional result.
+All four profiles are available to API callers. The CLI deliberately offers
+full-string correction only for `ms` and `cl`.
+
 ## Candidate structural-correction gate
 
 A future `indel.py` may search bounded insertion and deletion candidates, but
@@ -75,8 +103,8 @@ All algebra uses PR #70's native zero-based reverse coordinates: index 0 is the
 last data/checksum character. This convention is never converted using an HRP,
 separator, payload length, or complete-string length.
 
-Full-string correction requires a `suspected_profile`. The adapter accepts the
-exact registered HRP and its separator as an immutable prefix. Printable
+Full-string correction requires a `CorrectionContext` with an exact registered
+profile. The adapter accepts that HRP and its separator as an immutable prefix. Printable
 non-Bech32 characters after that boundary are erasures, including a later `1`.
 The format layer owns checksum selection. A correction outside the visible body is
 rejected, and every candidate must pass the ordinary `parse_codex32` boundary.
@@ -122,7 +150,7 @@ displays positions as one-based and performs only `position - 1` conversion.
 | Error-plus-erasure BCH decoding | `_bch_error_corrections` |
 | Unique arbitrary/consecutive erasure fallback | `_solve_linear`, `_linear_error_corrections` |
 | Root-subgroup and final target verification | `_bch_error_corrections`, `_corrections_reach_target` |
-| Fixed registered-profile adapter | `_correct_fixed` |
+| Public registered-profile adapter | `correct`, over `_correct_fixed` |
 | Application-agnostic residue adapter | `correct_worksheet_residue` |
 
 The target constants are checked against the imported checksum constants. No
@@ -139,10 +167,9 @@ for 13 consecutive regular-checksum erasures and 15 consecutive Long-checksum
 erasures. Other uniquely solvable erasure patterns may succeed but are not a
 guarantee.
 
-Failure records distinguish lexical text, immutable prefix, selected-profile
-shape, algebra, correction outside the visible body, and final semantic reparse.
-Algebra failures retain both BCH and linear-stage diagnostics rather than
-claiming that a mixed-corruption input failed for one inferred reason.
+Lexical, prefix, profile-shape, algebra, visible-body, and semantic-reparse
+failures all collapse to no public candidate. This avoids presenting one
+internal decoder stage as a diagnosis of the physical transcription error.
 
 Decoder success is fail-closed twice: every synthesized locator root must map
 to a legal reverse position in the selected checksum period, and the complete
@@ -164,3 +191,10 @@ The implementation carries the MIT notice from Blockstream's PR #70 head
 The source-derived offline corpus and its limitations are recorded in
 `source-manifest.md`; `tools/differential_correction.py --verify` checks it
 without network or Haskell dependencies.
+
+The frozen malformed corpus exercises parsing, checksum completion,
+interpolation, correction, and CLI tokenization. The dependency-free structured
+targets at `tools/fuzz_untrusted_boundaries.py` and
+`tools/fuzz_correction_context.py` bound each input to 4,096 bytes;
+`tests/test_fuzz_targets.py` supplies deterministic boundary seeds and
+Hypothesis smoke campaigns.

docs/production-ready-v1.md

@@ -1,7 +1,7 @@
 # Production-ready v1 completion plan
 
 Status: active implementation roadmap. The mandatory new-session scan
-precondition and Gate 0 passed on 2026-08-24; Gate 1 is next.
+precondition and Gates 0--1 passed on 2026-08-24; Gate 2 is next.
 
 This plan turns the current reference implementation into a narrowly scoped
 real-funds release. It does not add a GUI, networking, RPC, secret storage,
@@ -192,6 +192,12 @@ Success criteria:
 - fixed correction remains differential-compatible with the frozen P70 corpus;
 - all four registered profiles are covered by public API tests.
 
+Completion evidence (2026-08-24): 499 ordinary, optimized, and
+Hypothesis-statistics tests pass; the two 4,096-byte fuzz targets complete 250
+generated examples each; 28 frozen malformed cases and all 57 differential PR
+#70 cases pass; mypy and Ruff pass; and the installed package remains at 2,999
+physical Python lines.
+
 Dependency: Gate 0.
 
 ## Gate 2 -- Generation and dependency assurance

docs/source-manifest.md

@@ -25,6 +25,12 @@ SHA-256 `6aa552b34c0bb2878d45dee2655c331d52e40e41e61cef523415d314ad9948e5`.
 `tools/differential_correction.py --verify` checks it offline. The repository
 does not claim that the upstream Haskell property suite was executed locally.
 
+The independent rejection literals in `tests/data/malformed_inputs.json` have
+SHA-256 `966403685d979999524318d752537b5fe2ff01c0189a8e919e040dfd0de3978f`.
+They are fixed abuse cases, not outputs derived from production code. The two
+checked-in fuzz targets accept at most 4,096 bytes and add no runtime
+dependency.
+
 Generalized-HRP PR #2040 and length-restriction PR #2077 are non-authoritative
 research context. The README is user documentation, never requirements evidence.
 

docs/traceability.md

@@ -15,7 +15,7 @@ Every implemented claim identifies one code owner and direct evidence.
 | R08 | derive only a fresh ordinary share | `derive_share` | every target and existing/S rejection | Implemented |
 | R09 | fresh shared S uses k uniform u5 masks | `generation._masks` and basis loop | mask invariants, recovery, no entropy injection | Implemented |
 | R10 | splitting S uses S plus k−1 masks | `split_secret` | exact recovery and threshold properties | Implemented for `ms` and `cl` |
-| R11 | four errors, `2e+v≤8`, eight erasures, bursts | `correction.py` | P70 corpus and Hypothesis positions | Implemented fixed-length only |
+| R11 | four errors, `2e+v≤8`, eight erasures, bursts | public `correct` over `correction.py` | P70 corpus, all-profile API tests, and Hypothesis positions | Implemented fixed-length only |
 | R12 | correction is an untrusted suggestion | CLI `correct` | stderr/nonzero and no-correction tests | Implemented |
 | R13 | subsequent share input uses known prefix/header | `_cli_input.read_artifacts`, BIP93 prefix validators | suffix/full paste, retry, duplicate/mismatch and stream tests | Implemented |
 | R14 | structural correction/timeout UX | none | [cuttable v1 gate](production-ready-v1.md) | Missing; Gate 3 candidate |
@@ -32,8 +32,9 @@ Every implemented claim identifies one code owner and direct evidence.
 | R25 | xprv, coordinator xpub, descriptors in reusable API | `wallet.py`; goal-oriented CLI tree | official xprv, frozen BIP48/descriptor and nested-command tests | Implemented |
 | R26 | explicit account/timestamp, mandatory Core mode, root-xprv warning | wallet API and CLI | deterministic records, public/private separation and warning tests | Implemented |
 | R27 | no arbitrary security parser for descriptors | fixed templates in `wallet.py` | module/API absence and template fixtures | Implemented by removal |
-| R28 | safe typed installable reference surface | 20-name `__all__`, project script | public abuse tests, mypy, wheel/CLI checks | Implemented |
+| R28 | safe typed installable reference surface | 25-name `__all__`, project script | public abuse tests, mypy, wheel/CLI checks | Implemented |
 | R29 | explicit share-index selectors are bounded before copying or normalizing elements | `generation._indices` | oversized string pre-normalization regression across all three public generation APIs | Implemented from standard security scan |
+| R30 | malformed untrusted boundaries fail closed under bounded work | parser, completion, interpolation, correction, and CLI adapters | frozen malformed corpus and 4,096-byte structured fuzz target | Implemented in Gate 1 |
 
 The expanded checksum rule from PR #2258 is the only pending-upstream behavior.
 Its 44--46-byte compatibility exposure is explicitly accepted, has direct

src/codex32/__init__.py

@@ -13,10 +13,14 @@
     recover_secret,
 )
 from .correction import (
+    CorrectionCandidate,
+    CorrectionContext,
+    CorrectionEdit,
     WorksheetCorrection,
+    correct,
     correct_worksheet_residue,
 )
-from .errors import CodexError
+from .errors import CodexError, InvalidCorrectionInput
 from .generation import (
     generate_core_lightning_secret,
     generate_master_seed,
@@ -33,14 +37,19 @@
     "Bip39Secret",
     "CodexError",
     "CoreLightningSecret",
+    "CorrectionCandidate",
+    "CorrectionContext",
+    "CorrectionEdit",
     "Header",
+    "InvalidCorrectionInput",
     "MasterSeed",
     "Profile",
     "Secret",
     "Share",
     "WorksheetCorrection",
     "complete_checksum",
     "core_descriptors",
+    "correct",
     "correct_worksheet_residue",
     "derive_share",
     "generate_core_lightning_secret",

src/codex32/cli.py

@@ -33,8 +33,8 @@
 from codex32._cli_parser import parser as _parser
 from codex32.bip93 import IDX_SORT, _normalize_target
 from codex32.correction import (
-    _correct_fixed,
-    _FixedCorrectionSuccess,
+    CorrectionContext,
+    correct,
     correct_worksheet_residue,
 )
 from codex32.errors import CodexError, HeaderCollision, InvalidCorrectionInput
@@ -311,15 +311,11 @@ def _correct(
         raise _UsageError(
             "The string must begin with an undamaged ms1 or cl1 prefix; prefix correction is not attempted."
         )
-    fixed = _correct_fixed(value, suspected_profile=profile)
-    if not isinstance(fixed, _FixedCorrectionSuccess):
-        messages = {
-            "algebra": "No correction found. Check the original backup.",
-            "body": "The proposed correction falls outside the supplied string.",
-            "reparse": "No valid correction was found for this backup.",
-        }
-        raise _CommandError(messages.get(fixed.stage, fixed.detail))
-    if not fixed.addends:
+    candidates = correct(CorrectionContext(profile), value)
+    if not candidates:
+        raise _CommandError("No valid correction found. Check the original backup.")
+    fixed = candidates[0]
+    if not fixed.edits:
         _print("The codex32 string is already valid.")
         return 0
     warning = (