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 the remaining intentionally private cross-module couplings. Internal benchmarks may continue to use implementation-private names when they are explicitly testing internals.

The supported chars_to_u5() API lowercases ASCII only. Unicode lookalikes such as Kelvin sign K stay invalid instead of being case-folded into Bech32 k. The ASCII-only helper now lives once in bech32.py and is shared by the CLI input path.

Review stack

Base: #52 (codex/5-release-qualification). Current head: cde312b.

This is the planned one-time refresh after the overlapping restore/foundation/security/release stack settled. Mechanical conflict resolution preserves the reviewed mixed-case correction state, the Core-native process boundary, the 83-character BIP173 HRP rule, and the supported module-level vector API. Package-level codex32.__all__ remains 23 names.

The diff remains two logical review units:

1. d6679cc — the human-authored vector-API publication, replayed on the settled base;
2. cde312b — the Unicode-lookalike follow-up plus the mechanical ASCII-lowercase centralization required by the settled CLI/Core code.

The second commit remains Codex-authored and must be rewritten/squashed under the responsible human author before merge, per the repository authorship policy. The PR therefore remains draft until that human step is performed.

Validation

On current head cde312b:

• full suite: 952 passed normally;
• full suite under python -O: 952 passed;
• focused vector/CLI/correction/profile/share set: 523 passed normally and 523 passed under python -O;
• frozen differential verifier: 57/57 correction cases;
• installed logical-line budget: 5199 < 5200;
• package-level __all__: 23 names;
• Ruff check/format: clean;
• strict mypy: clean for 21 source files;
• git diff --check: clean.

Exact-head GitHub Python-package run 36985866683 completed successfully on cde312b; all 10 matrix jobs passed. The Ubuntu 3.13 leg also passed the optimized suite, correction-constant verifier, strict mypy, Ruff check/format, frozen differential verifier, build, and wheel-environment verification. A separate dynamic github-advanced-security agent job failed in its Processing Request step while ordinary CodeQL analysis succeeded; that is not a package-test failure.

Current-head Codex review ACKs the code, and there are no unresolved inline review threads. No automated code-review or verification gap remains. Human authorship/rewrite and integration remain.

Disclosure: AI tools assisted with the mechanical restack and conflict analysis. Human responsibility is required for final authorship and integration.

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

[BenWestgate]

Codex current-head re-review: code ACK cde312b.

The refreshed diff preserves the narrow package-level surface while publishing the module-level primitives needed for external reference-vector construction. checksum_for_body_length() and checksum_for_encoded_length() preserve the regular/long threshold, the expanded-length 94/95 gap, and the 1023-symbol ceiling. The renamed u5 helpers preserve range checks, and chars_to_u5() uses ASCII-only lowercase so Unicode lookalikes such as Kelvin sign remain invalid. The shared private _ascii_lower centralization also preserves the earlier confirmation behavior. Focused tests exercise vector construction entirely through the new supported names and retain the checksum/interpolation invariants. No inline review threads remain.

I found no code blocker. GitHub currently reports no workflow run/status attached to this exact head, so this is a code-review ACK only; the PR body's exact-head local validation (952 normal/optimized, 57/57 differential, Ruff/mypy, 5,199 < 5,200) is not being represented here as GitHub CI evidence. The Codex-authored second commit must still be rewritten/squashed by the responsible human before integration.

[BenWestgate]

Codex verification follow-up for current head cde312b6ab5c56b90426bdcdb1aa721199c46a87: the earlier review's statement that no exact-head workflow run was attached was an API-wrapper blind spot. GitHub Actions run 36985866683 is attached to this commit and all 10 Python-package matrix jobs completed successfully. The Ubuntu 3.13 job also passed the optimized suite, correction-constant verifier, strict mypy, Ruff check/format, frozen differential verifier, build, and wheel-environment verification. The prior current-head code ACK therefore now has exact-head GitHub CI evidence as well. The separate dynamic github-advanced-security agent job failure is not the package workflow; its Processing Request step failed while ordinary CodeQL analysis succeeded. Human authorship/rewrite for the Codex-authored follow-up remains.