api: Expose reference-vector helpers

[BenWestgate]

Closes #49.

Promote the module-level checksum specifications, u5 conversion helpers, and checksum-selection helpers required to construct and verify codex32 reference vectors without underscore-prefixed imports. These are supported at their owning modules; this PR does not add them to package-level codex32.__all__.

docs/developer/api.md documents the supported vector workflow and explicitly justifies the remaining private cross-module imports as correction-engine, GF/profile, wallet/Core, or CLI implementation couplings. Internal benchmarks may continue to use implementation-private names when they are explicitly testing internals.

A production-import audit on the reviewed head finds 48 distinct private (module, symbol) pairs across 64 same-package import occurrences (47 unique symbol spellings). They are confined to the correction engine, profile/artifact construction, wallet/Core, and CLI implementation boundaries documented here. Renaming those internals would only remove Python’s private-name signal or publish construction/search hooks; it would not improve the supported vector API. No additional pre-v1 rename is warranted.

The documented external vector-construction example runs using only bech32_encode, chars_to_u5, and checksum_for_body_length; no underscore-prefixed import is required.

Review follow-up 316ea11 makes the newly supported chars_to_u5() API ASCII-case-insensitive without Unicode case folding, so a lookalike such as Kelvin sign K remains invalid instead of becoming Bech32 k. That follow-up adds the direct regression and introduces private _ascii_lower, which is also the intended single helper to absorb #13’s duplicated ASCII-only folding during the final prerequisite refresh.

Package-level API accounting: current reviewability-v1 actually has 24 names in codex32.__all__ although its developer guide still says 25. #64 will remove the obsolete public core_descriptors export, making the frozen v1 package-level count 23. This PR's module-level vector helpers do not change that count.

Local verification at reviewed head 316ea11:

• codec/generic-HRP tests: 21 passed normally and 21 under python -O;
• strict mypy: clean;
• Ruff check/format and git diff --check: clean;
• broader suite: 866 passed; the sole local failure was the installed-entry-point test because that disposable system-Python checkout had no /usr/local/bin/codex32 script. GitHub CI installs the package in its environment and is the authoritative check for that case.

This PR intentionally receives its final mechanical refresh only after the overlapping prerequisite work has settled: #42/#57/#46, #13, #33, and #64. #7/#51 are already in the base and #45 is already merged into #42's branch. The overlap audit shows those PRs touch one or more of bech32.py, correction.py, indel.py, _cli_input.py, cli.py, generation.py, wallet.py, docs/developer/api.md, or their tests. Waiting for that complete set avoids repeatedly invalidating human review with mechanical restacks.

The final resolution must keep the supported module-level vector names, mixed-case/diagnostic behavior, #7 dependency-removal/Core fixtures, 83-character HRP boundary, #64 private Core descriptor boundary, and centralized ASCII-only lowercasing in bech32._ascii_lower. After that refresh, rerun the vector/API tests and full CI, recheck review threads, and rewrite/squash the Codex-authored follow-up under the responsible human author before merge.

Disclosure: AI tools were used while implementing and checking the review follow-up, per docs/developer/AI_POLICY.md.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[BenWestgate]

AI-generated review (Claude), posted at the maintainer's request.

ACK 7311db8

• Pure renames plus checksum_for_body_length factored out of _from_parts with the same logic. I ran the api.md example; it parses as a Secret. __all__ is 24.
• These names become a supported v1 surface. That's the point of #49, but it's a commitment worth accepting on purpose.
• Sequencing: it conflicts with #42 and #57 (mechanical renames only).
• Nit: the new docstrings have a blank line after them, unlike the neighbouring functions.

[BenWestgate]

Merge-order note from #42 review: #42 introduces bech32.interpret_mixed_case as shared correction/CLI policy. It should not become part of the supported module API. Review/merge #42 before this PR; when resolving the bech32.py conflict here, preserve the private-name signal by carrying it as _interpret_mixed_case (and update internal imports), with no package-level codex32.__all__ export. This keeps #53’s stated API boundary consistent with the review nit on #42.

[BenWestgate]

Review follow-up: the blank-line docstring nit is valid but non-functional. I’m leaving the current one-commit API diff intact until #42 and #57 land because #53 already has mechanical rename conflicts with both; remove the extra blank lines in that single conflict-refresh commit rather than creating another pre-conflict churn commit. Human review order: #42 and #57 before #53.

[BenWestgate]

Second merge-order/API-boundary note from #13 review: after #13 lands, deduplicate the two ASCII-only case-fold implementations by adding one private bech32._ascii_lower and importing it from _cli_input.py and generation.py. Together with the earlier #42 note (interpret_mixed_case → private _interpret_mixed_case), this keeps both shared lexical/correction helpers intentionally private while #53 publishes only the documented reference-vector helpers.

[BenWestgate]

Review-submission follow-up: ACK stands. The blank-line-after-docstring nit is style-only; handle it when this branch is refreshed after #13/#42 so the conflict resolution stays one mechanical API-boundary pass. That same refresh should (1) centralize private _ascii_lower, (2) keep mixed-case policy private as _interpret_mixed_case, and (3) preserve the intentionally supported module-level vector helpers without widening package __all__.

[BenWestgate]

Release-gate sequencing note: keep this after #13, #42, and #57 because the current conflicts are mechanical renames. One concrete helper-boundary cleanup should be folded into this pass: #13 currently has equivalent ASCII-only lowercase helpers in generation.py and _cli_input.py; its review deliberately deferred centralizing them here. Use one private bech32._ascii_lower (or equivalent private common helper) and update both callers while preserving package-level codex32.__all__ at 24. Also address the existing docstring-spacing nit during the conflict refresh.

[BenWestgate]

AI-generated review, posted at the maintainer's request.

ACK 316ea11 code. Final-refresh after #13/#42/#57 as planned, and rewrite/squash the Codex-authored follow-up under the responsible human author before merge.

[BenWestgate]

Final-refresh note: preserve the current ACKed public-vector API and ASCII-only behavior, then normalize the small docstring-spacing nit while replaying/squashing the follow-up after #13/#42/#57. No separate churn is needed on the stale stack for a cosmetic-only change.

[BenWestgate]

Agent API-boundary review at current head 316ea11: the user-facing problem is addressed without flattening the internal namespace. Vector authors get supported non-underscored module APIs (chars_to_u5, u5_to_chars, checksum constants/types, and checksum-selection helpers), while package-level codex32.__all__ remains the narrow backup/recovery surface. The Unicode-lookalike follow-up correctly uses ASCII-only lowercasing. Remaining cross-module underscore imports are internal implementation couplings and are explicitly documented rather than exposed. git diff --check is clean and exact-head Python-package run 36377610761 succeeded. No current code-review blocker; do the planned single mechanical refresh after #7/#13/#33/#42/#45/#57/#46/#64 settle, then human-rewrite/squash the Codex-authored follow-up.