Expose vector construction helpers

Promote the module-level checksum and u5 conversion interfaces needed by reference-vector authors while keeping the package-level API narrow. Document and test the supported vector workflow and justify the remaining private cross-module couplings.\n\nValidation: 866 normal and 866 optimized tests; mypy; Ruff; production size budget.\n\nfixes #49

Author: BenWestgate

docs/developer/api.md

@@ -100,8 +100,57 @@ generic parse-length failure.
   hidden state.
 
 Private Python names are convention rather than access control. The supported
-surface is the 25-name package `__all__`; direct use of private helpers is
-unsupported but remains in the review scope.
+top-level surface is the 24-name package `__all__`; direct use of private helpers
+is unsupported but remains in the review scope.
+
+### Reference-vector construction API
+
+Reference-vector authors may use the following module-level interfaces without
+depending on implementation-private names:
+
+- `codex32.bech32`: `CHARSET`, `bech32_decode`, `bech32_encode`,
+  `bech32_hrp_expand`, `chars_to_u5`, and `u5_to_chars`;
+- `codex32.checksums`: `Checksum`, `CODEX32`, and `CODEX32_LONG`;
+- `codex32.bip93`: `checksum_for_body_length` and
+  `checksum_for_encoded_length`.
+
+For example, a generic codex32 vector can be constructed without importing an
+underscore-prefixed name:
+
+```python
+from codex32.bech32 import bech32_encode, chars_to_u5
+from codex32.bip93 import checksum_for_body_length
+
+hrp = "zz"
+body = chars_to_u5("0tests" + "q" * 26)
+checksum = checksum_for_body_length(hrp, len(body))
+text = bech32_encode(hrp, body, checksum)
+```
+
+These are supported module interfaces for codec and vector work; they are not
+added to the package-level `codex32.__all__`, whose backup/recovery surface stays
+deliberately narrow.
+
+The remaining production cross-module private imports are intentional internal
+couplings rather than user-facing APIs:
+
+- `_alignment.py`, `_competitors.py`, `correction.py`, and `indel.py` form one
+  bounded correction engine. Their underscored search state, views, and pruning
+  helpers are exchanged only inside that engine.
+- `bip93.py` and `correction.py` use the shared private GF(32) arithmetic in
+  `gf32.py`; profile factories use `_from_parts` and profile-rule helpers to
+  preserve one artifact-validation path without publishing construction hooks.
+- `generation.py`, `wallet.py`, and `_bitcoin_core.py` share the private BIP32
+  root primitives. `_bitcoin_core.py` also consumes wallet descriptor records
+  while remaining the sole process/state adapter.
+- `_cli_input.py` and `cli.py` share private correction/profile orchestration,
+  input state, and parser plumbing. Those names exist to compose the CLI, not as
+  a second domain API.
+
+Internal benchmark and verification tools may import those implementation names
+when they are explicitly testing the implementation itself. Tools or examples
+that model external vector construction use the supported module interfaces
+above.
 
 ### Size budget
 

src/codex32/_cli_input.py

@@ -13,9 +13,9 @@
 from codex32.bip93 import (
     Secret,
     Share,
-    _checksum_for_encoded_length,
     _validate_basis_prefix,
     _validate_recovery_prefix,
+    checksum_for_encoded_length,
     parse_codex32,
     recover_secret,
 )
@@ -393,7 +393,7 @@ def _case_interpretation(
         candidate = None
     else:
         bits = (
-            5 * _checksum_for_encoded_length(artifact.hrp, len(artifact.text) - len(artifact.hrp) - 1).length
+            5 * checksum_for_encoded_length(artifact.hrp, len(artifact.text) - len(artifact.hrp) - 1).length
         )
         proposed = CorrectionCandidate(artifact, (), 1, 0, 0, None, capture_space_bits=bits)
         candidate = proposed if allowed is None or allowed(proposed) else None

src/codex32/bech32.py

@@ -1,6 +1,6 @@
 """Bech32 character, container, and bit-conversion helpers."""
 
-from codex32.checksums import _Checksum
+from codex32.checksums import Checksum
 from codex32.errors import (
     InvalidCase,
     InvalidCharacter,
@@ -19,14 +19,18 @@ def bech32_hrp_expand(hrp: str) -> list[int]:
     return [ord(x) >> 5 for x in hrp] + [0] + [ord(x) & 31 for x in hrp]
 
 
-def _u5_to_chars(values: list[int] | tuple[int, ...]) -> str:
+def u5_to_chars(values: list[int] | tuple[int, ...]) -> str:
+    """Convert 5-bit values to Bech32 characters."""
+
     for index, value in enumerate(values):
         if not 0 <= value < 32:
             raise InvalidCharacter(f"u5 value {value} at index {index} is outside 0..31")
     return "".join(CHARSET[value] for value in values)
 
 
-def _chars_to_u5(value: str, first_position: int = 1) -> list[int]:
+def chars_to_u5(value: str, first_position: int = 1) -> list[int]:
+    """Convert Bech32 characters to 5-bit values."""
+
     result: list[int] = []
     for index, character in enumerate(value.lower()):
         position = CHARSET.find(character)
@@ -53,18 +57,18 @@ def _validate_single_case_ascii(value: str) -> bool:
     return value.isupper()
 
 
-def bech32_encode(hrp: str, data: list[int], spec: _Checksum) -> str:
+def bech32_encode(hrp: str, data: list[int], spec: Checksum) -> str:
     """Compute a Bech32 string given HRP and data values."""
     checksum = spec.create(bech32_hrp_expand(hrp) + list(data))
-    return f"{hrp}1{_u5_to_chars([*data, *checksum])}"
+    return f"{hrp}1{u5_to_chars([*data, *checksum])}"
 
 
-def bech32_verify_checksum(hrp: str, data: list[int], spec: _Checksum) -> bool:
+def bech32_verify_checksum(hrp: str, data: list[int], spec: Checksum) -> bool:
     """Verify the checksum selected by the calling application."""
     return spec.verify(bech32_hrp_expand(hrp) + list(data))
 
 
-def bech32_decode(value: str, spec: _Checksum | None = None) -> tuple[str, list[int]]:
+def bech32_decode(value: str, spec: Checksum | None = None) -> tuple[str, list[int]]:
     """Validate a Bech32 string, optionally including its checksum."""
     _validate_single_case_ascii(value)
     separator = value.rfind("1")
@@ -74,7 +78,7 @@ def bech32_decode(value: str, spec: _Checksum | None = None) -> tuple[str, list[
         raise MissingSeparator("The application prefix before 1 is missing.")
     lowered = value.lower()
     hrp = lowered[:separator]
-    data = _chars_to_u5(lowered[separator + 1 :], separator + 2)
+    data = chars_to_u5(lowered[separator + 1 :], separator + 2)
     if spec is None:
         return hrp, data
     if len(data) < spec.length or not bech32_verify_checksum(hrp, data, spec):

src/codex32/bip93.py

@@ -6,13 +6,13 @@
 
 from codex32.bech32 import (
     CHARSET,
-    _chars_to_u5,
-    _u5_to_chars,
     bech32_decode,
     bech32_encode,
     bech32_verify_checksum,
+    chars_to_u5,
+    u5_to_chars,
 )
-from codex32.checksums import _CODEX32, _CODEX32_LONG, _Checksum
+from codex32.checksums import CODEX32, CODEX32_LONG, Checksum
 from codex32.errors import (
     DuplicateShareIndex,
     ExistingTargetIndex,
@@ -68,7 +68,7 @@ def __post_init__(self) -> None:
     def _from_symbols(cls, symbols: tuple[int, ...]) -> "Header":
         if len(symbols) != 6:
             raise InvalidLength("codex32 header must contain six symbols")
-        text = _u5_to_chars(symbols)
+        text = u5_to_chars(symbols)
         if text[0] not in "023456789":
             raise InvalidThreshold(
                 f"The threshold must be 0 or a number from 2 through 9; found {text[0]!r}."
@@ -77,25 +77,36 @@ def _from_symbols(cls, symbols: tuple[int, ...]) -> "Header":
 
     @property
     def _symbols(self) -> tuple[int, ...]:
-        return tuple(_chars_to_u5(f"{self.threshold}{self.identifier}{self.index}"))
+        return tuple(chars_to_u5(f"{self.threshold}{self.identifier}{self.index}"))
 
 
-def _checksum_for_encoded_length(hrp: str, encoded_length: int) -> _Checksum:
+def checksum_for_encoded_length(hrp: str, encoded_length: int) -> Checksum:
+    """Return the codex32 checksum required by an encoded HRP/data length."""
+
     expanded_length = 2 * len(hrp) + 1 + encoded_length
     if expanded_length <= 93:
-        return _CODEX32
+        return CODEX32
     if expanded_length < 96:
         raise InvalidLength("expanded codex32 lengths 94 and 95 are invalid")
     if expanded_length <= 1023:
-        return _CODEX32_LONG
+        return CODEX32_LONG
     raise InvalidLength("expanded codex32 codeword exceeds 1023 symbols")
 
 
-def _decode_codex32(text: str) -> tuple[str, _ProfileRules | None, tuple[int, ...], _Checksum]:
+def checksum_for_body_length(hrp: str, body_length: int) -> Checksum:
+    """Return the checksum required when constructing a codex32 body."""
+
+    expanded_body_length = 2 * len(hrp) + 1 + body_length
+    checksum = CODEX32 if expanded_body_length <= 80 else CODEX32_LONG
+    checksum_for_encoded_length(hrp, body_length + checksum.length)
+    return checksum
+
+
+def _decode_codex32(text: str) -> tuple[str, _ProfileRules | None, tuple[int, ...], Checksum]:
     hrp, encoded = bech32_decode(text)
     if len(hrp) + 1 + len(encoded) < 21:
         raise InvalidLength("codex32 string must contain at least 21 characters")
-    checksum = _checksum_for_encoded_length(hrp, len(encoded))
+    checksum = checksum_for_encoded_length(hrp, len(encoded))
     body = tuple(encoded[: -checksum.length])
     Header._from_symbols(body[:6])
     if not bech32_verify_checksum(hrp, encoded, checksum):
@@ -205,10 +216,7 @@ def _from_parts(
     if rules is not None:
         _validate_payload(rules.profile, header, payload)
     body = [*header._symbols, *payload]
-    expanded_body_length = 2 * len(normalized_hrp) + 1 + len(body)
-    checksum = _CODEX32 if expanded_body_length <= 80 else _CODEX32_LONG
-    # Validate the completed generic codeword, including the 94/95 gap.
-    _checksum_for_encoded_length(normalized_hrp, len(body) + checksum.length)
+    checksum = checksum_for_body_length(normalized_hrp, len(body))
     text = bech32_encode(normalized_hrp, body, checksum)
     return parse_codex32(text.upper() if uppercase else text)
 
@@ -330,7 +338,7 @@ def _interpolate_tail(share_set: _ShareSet, target: str) -> Share | Secret:
             value ^= _gf32_multiply(weight, row[column])
         result.append(value)
     header = Header(share_set.threshold, share_set.identifier, target)
-    text = f"{share_set.hrp}1{_u5_to_chars((*header._symbols, *result))}"
+    text = f"{share_set.hrp}1{u5_to_chars((*header._symbols, *result))}"
     return parse_codex32(text.upper() if share_set.uppercase else text)
 
 

src/codex32/checksums.py

@@ -20,7 +20,9 @@
 
 
 @dataclass(frozen=True, slots=True)
-class _Checksum:
+class Checksum:
+    """Immutable checksum specification for reference-vector construction."""
+
     kind: str
     generators: tuple[int, ...]
     length: int
@@ -49,21 +51,21 @@ def create(self, values: list[int] | tuple[int, ...]) -> list[int]:
         return [(residue >> (width * (self.length - 1 - index))) & mask for index in range(self.length)]
 
 
-_CODEX32 = _Checksum("codex32", _CODEX32_GEN, 13, 0x10CE0795C2FD1E62A, 93)
-_CODEX32_LONG = _Checksum("Long codex32", _CODEX32_LONG_GEN, 15, 0x43381E570BF4798AB26, 1023)
+CODEX32 = Checksum("codex32", _CODEX32_GEN, 13, 0x10CE0795C2FD1E62A, 93)
+CODEX32_LONG = Checksum("Long codex32", _CODEX32_LONG_GEN, 15, 0x43381E570BF4798AB26, 1023)
 
 # Descriptor checksum remains an independently specified, non-codex32 helper.
-DESCSUM = _Checksum("Descriptor", _DESCSUM_GEN, 8, 1)
+DESCSUM = Checksum("Descriptor", _DESCSUM_GEN, 8, 1)
 
 _CRC = (
     None,
-    # ``_Checksum`` consumes input bits most-significant bit first.  With its
+    # ``Checksum`` consumes input bits most-significant bit first.  With its
     # implicit leading term, these generator values spell x+1, x^2+x+1,
     # x^3+x+1, and x^4+x+1 respectively.
-    _Checksum("CRC1", (1,), 1, 0),
-    _Checksum("CRC2", (3,), 2, 0),
-    _Checksum("CRC3", (3,), 3, 0),
-    _Checksum("CRC4", (3,), 4, 0),
+    Checksum("CRC1", (1,), 1, 0),
+    Checksum("CRC2", (3,), 2, 0),
+    Checksum("CRC3", (3,), 3, 0),
+    Checksum("CRC4", (3,), 4, 0),
 )
 
 

src/codex32/correction.py

@@ -30,20 +30,20 @@
 
 from codex32.bech32 import (
     CHARSET,
-    _chars_to_u5,
-    _u5_to_chars,
     _validate_single_case_ascii,
     bech32_hrp_expand,
+    chars_to_u5,
+    u5_to_chars,
 )
 from codex32.bip93 import (
     IDX_SORT,
     Header,
     Secret,
     Share,
-    _checksum_for_encoded_length,
+    checksum_for_encoded_length,
     parse_codex32,
 )
-from codex32.checksums import _CODEX32, _CODEX32_LONG, _Checksum
+from codex32.checksums import CODEX32, CODEX32_LONG, Checksum
 from codex32.errors import CodexError, InvalidCorrectionInput
 from codex32.gf32 import _inverse as _gf32_inverse
 from codex32.gf32 import _multiply as _gf32_multiply
@@ -255,10 +255,10 @@ class _Spec:
 _ALIGNMENT_CACHE_SIZE = 11
 
 
-def _spec_for_checksum(checksum: _Checksum) -> _Spec:
-    if checksum is _CODEX32:
+def _spec_for_checksum(checksum: Checksum) -> _Spec:
+    if checksum is CODEX32:
         return _SHORT_SPEC
-    if checksum is _CODEX32_LONG:
+    if checksum is CODEX32_LONG:
         return _LONG_SPEC
     raise AssertionError("registered profile selected a non-codex32 checksum")
 
@@ -544,7 +544,7 @@ def __init__(
     ) -> None:
         normalized_hrp = hrp.value if isinstance(hrp, Profile) else hrp.lower()
         profile_rules = _optional_profile_rules(normalized_hrp)
-        checksum = _checksum_for_encoded_length(normalized_hrp, body_length)
+        checksum = checksum_for_encoded_length(normalized_hrp, body_length)
         if profile_rules is not None:
             profile_rules.validate_payload_length(body_length - checksum.length - 6)
         self.hrp = normalized_hrp
@@ -598,7 +598,7 @@ def correct(
             return None
         for index, addend in result:
             corrected_reversed[index] ^= addend
-        corrected = self.prefix + _u5_to_chars(list(reversed(corrected_reversed)))
+        corrected = self.prefix + u5_to_chars(list(reversed(corrected_reversed)))
         corrected = corrected.upper() if self.uppercase else corrected
         try:
             artifact = parse_codex32(corrected)
@@ -774,7 +774,7 @@ def _validate_context(context: CorrectionContext) -> None:
             if length < 21:
                 raise ValueError("expected_length must permit the generic codex32 minimum length")
             body_length = length - len(context.hrp) - 1
-            checksum = _checksum_for_encoded_length(context.hrp, body_length)
+            checksum = checksum_for_encoded_length(context.hrp, body_length)
             if body_length < checksum.length + 6:
                 raise ValueError("expected_length must contain a header and checksum")
             rules = _optional_profile_rules(context.hrp)
@@ -913,7 +913,7 @@ def correct_worksheet_residue(
         raise InvalidCorrectionInput("codex32 input exceeds 15 characters")
     try:
         _validate_single_case_ascii(residue)
-        values = list(reversed(_chars_to_u5(residue)))
+        values = list(reversed(chars_to_u5(residue)))
     except TypeError:
         raise
     except CodexError as error:

src/codex32/generation.py

@@ -9,7 +9,7 @@
 from typing import Never, SupportsIndex, cast
 
 from codex32._bip32 import _valid_root
-from codex32.bech32 import CHARSET, _u5_to_chars, convertbits
+from codex32.bech32 import CHARSET, convertbits, u5_to_chars
 from codex32.bip93 import (
     IDX_SORT,
     Header,
@@ -112,15 +112,15 @@ def _selection(threshold: int, share_count: object, indices: Sequence[str] | str
 
 
 def _random_identifier() -> str:
-    return _u5_to_chars(tuple(value & 31 for value in secrets.token_bytes(4)))
+    return u5_to_chars(tuple(value & 31 for value in secrets.token_bytes(4)))
 
 
 def _fingerprint_identifier(fingerprint: bytes) -> str:
     if not isinstance(fingerprint, bytes):
         raise TypeError("fingerprint must be bytes")
     if len(fingerprint) != 4:
         raise ValueError("fingerprint must contain four bytes")
-    return _u5_to_chars(tuple(convertbits(fingerprint, 8, 5, pad=True)[:4]))
+    return u5_to_chars(tuple(convertbits(fingerprint, 8, 5, pad=True)[:4]))
 
 
 def _random_share(profile: Profile, threshold: int, identifier: str, index: str, length: int) -> Share:

src/codex32/indel.py

@@ -8,7 +8,7 @@
 
 from codex32._alignment import _IncrementalSyndromes, _View
 from codex32.bech32 import CHARSET, _validate_single_case_ascii
-from codex32.bip93 import _checksum_for_encoded_length
+from codex32.bip93 import checksum_for_encoded_length
 from codex32.correction import (
     CorrectionCandidate,
     CorrectionContext,
@@ -310,7 +310,7 @@ def _prepare(
         for shape in shapes
     }
     base = len(context.hrp) + 1
-    degree = _checksum_for_encoded_length(context.hrp, target - base).length
+    degree = checksum_for_encoded_length(context.hrp, target - base).length
     return _Target(context, text, immutable, target, base, degree, counts)