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. The package-level codex32.__all__ remains the same 24-name backup/recovery API.

docs/developer/api.md now 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 found 48 underscore-prefixed symbols across 64 same-package import edges. They are confined to the correction engine, profile/artifact construction, wallet/Core, and CLI implementation boundaries documented here. Renaming those symbols 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.

Validation:

• 866 tests pass
• 866 optimized (python -O) tests pass
• mypy passes
• Ruff check/format passes
• production-size budget passes
• git diff --check passes

Disclosure: AI tools were used while implementing and checking this user-requested branch-to-branch contribution.

[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__.