Align the v1 release contract

Close Gate 0 by restricting only fresh CLI master-seed generation to 16- and 32-byte sizes while preserving the full BIP93 API and import range. Bound explicit share-index selectors before copying or normalization to resolve the delegated scan's low-severity availability finding.

Reserve 1.0.0rc1, pin the formatter baseline, and align security, capability, provenance, dependency, traceability, and accepted-risk records with the implemented behavior. Add direct regression coverage for every changed boundary.

Author: BenWestgate

SECURITY.md

@@ -21,6 +21,16 @@ or wallet.
 - Correction produces untrusted suggestions, never authenticated input to a
   wallet operation.
 
+## Accepted release risks
+
+The durable dispositions, controls, and review triggers are recorded in the
+[accepted-risk register](docs/accepted-risks.md). In particular, this version
+intentionally follows the frozen checksum-boundary behavior of pending BIP93
+PR #2258. That creates a known compatibility risk for 44--46-byte `ms` strings;
+there is no dual decoder. Fresh CLI generation is limited to 16 or 32 bytes,
+while the API and imported existing seeds retain every BIP93 size from 16
+through 64 bytes.
+
 ## Accepted limitations
 
 - Python cannot guarantee secret zeroization, constant-time execution, locked
@@ -33,8 +43,8 @@ or wallet.
   narrowly and verifies BIP93 BIP32 vectors, but does not independently audit
   its cryptographic implementation.
 - Fresh unshared `ms` identifiers expose 20 bits of the BIP32 fingerprint.
-  Shared sets use random or explicit identifiers; raw seeds and re-sharing
-  require an explicit identifier.
+  Shared sets, supplied raw seeds, re-sharing, and CL generation use random or
+  explicit identifiers.
 - Generation-only CRC padding is a small recovery hint, not authentication or
   a codex32 validity requirement.
 - BCH correction detects/corrects bounded symbol errors but cannot establish
@@ -45,6 +55,5 @@ or wallet.
 
 The project has no GUI, network access, RPC, secret storage, wallet database,
 arbitrary descriptor parser, plugin/profile registry, structural correction
-search, partial-basis completion, BIP39 mnemonic conversion, or fresh Core
-Lightning secret generation. Adding one of these requires a separate threat
-model and explicit scope decision.
+search, partial-basis completion, or BIP39 mnemonic conversion. Adding one of
+these requires a separate threat model and explicit scope decision.

docs/accepted-risks.md

@@ -0,0 +1,16 @@
+# Accepted-risk register
+
+This register records consciously retained release risks. Acceptance does not
+turn a checksum into authentication or remove the verification gates in the
+[production-ready v1 plan](production-ready-v1.md).
+
+| ID | Risk and exposure | Disposition and controls | Review trigger |
+|---|---|---|---|
+| AR-001 | Pending BIP93 PR #2258 changes the checksum boundary for expanded HRPs. `ms` strings carrying 44--46-byte seeds can be incompatible with software implementing only the currently published BIP93 rule. | Accepted pending-standard compatibility risk. Follow the frozen PR head and boundary vectors; do not add ambiguous dual decoding. Fresh CLI generation permits only 16 or 32 bytes. The API and imported existing seeds retain all 16--64-byte BIP93 sizes. | Recheck the exact upstream revision before the RC and final release; reassess if the PR changes, closes, or merges differently. |
+| AR-002 | Root-key and wallet derivation rely on `bip32` and its native secp256k1 dependency stack, which this project does not independently audit. | Accepted architecture boundary. Keep all interaction in `_bip32.py`; retain official BIP32, BIP48, descriptor, and wallet fixtures. Gate 2 must add reproducible hash-pinned CLI constraints and cross-platform evidence. | Any resolved dependency change, adapter change, vector failure, advisory, or unsupported release artifact. |
+| AR-003 | A fresh unshared `ms` identifier reveals 20 bits of the BIP32 fingerprint. Identifiers and checksums are public metadata, not authentication. | Accepted BIP93 usability/privacy tradeoff. Shared sets, supplied raw seeds, re-sharing, and CL generation instead use random or explicit identifiers. | Any workflow starts treating an identifier as secret, unique, or proof of wallet identity. |
+| AR-004 | Python and terminal environments cannot guarantee secret zeroization, locked memory, constant-time execution, or removal from scrollback and editor memory. | Accepted implementation-platform limitation. Keep protected material out of argv and machine stdout, disable automatic line history, and document offline use. | A supported runtime or interface adds a stronger secret-memory or terminal boundary. |
+
+These dispositions were accepted by the production-ready v1 roadmap. New or
+materially changed risks require explicit human acceptance; agents may record
+evidence but do not broaden an acceptance.

docs/cli.md

@@ -40,11 +40,12 @@ random or explicit. `--indices 7cad` preserves exact order.
 `--shares N` samples distinct indices and preserves sample order. Raw seeds and
 re-sharing use random identifiers when none is supplied. Bare interactive
 `create` immediately generates an unshared Bitcoin master seed. Generation
-never prompts for protected input. `--existing` instead reads one existing
-codex32 secret or hexadecimal seed from the terminal or bounded stdin. Nonempty
-redirected input without that flag is rejected rather than ignored. Without a
-share selector, a shared set contains two more shares than are needed for
-recovery; threshold zero remains unshared.
+never prompts for protected input. Fresh `ms` generation accepts 16 or 32 bytes;
+the default is 16. `--existing` instead reads one existing codex32 secret or
+hexadecimal seed from the terminal or bounded stdin and retains every 16--64
+byte BIP93 `ms` size. Nonempty redirected input without that flag is rejected
+rather than ignored. Without a share selector, a shared set contains two more
+shares than are needed for recovery; threshold zero remains unshared.
 Hexadecimal input must already contain securely generated entropy; a random
 backup identifier does not make a weak seed safe.
 After creation, the CLI reminds the user to test recovery using what was

docs/dependencies.md

@@ -5,6 +5,13 @@ range permits bug-fix releases, but a release must record and review the exact
 resolved dependency set. A resolved-version change requires the full BIP32 and
 wallet-vector suite before publication.
 
+The metadata now reserves `1.0.0rc1`; it is not authorization to publish. The
+compatible library range remains deliberate. Gate 2 must add a tested,
+hash-pinned CLI installation constraint and reconcile native wheels across
+Python 3.12--3.14 before the release candidate can be considered dependency-
+assured. Bitcoin Core cannot replace this boundary because it has no interface
+that derives this project's root key and wallet records from raw seed bytes.
+
 ## Reviewed resolution
 
 Reviewed on 2026-08-22 with Python 3.13 on Linux x86-64:
@@ -35,3 +42,15 @@ fixtures. This is dependency-boundary evidence, not an independent audit of
 
 Sources: [`bip32` on PyPI](https://pypi.org/project/bip32/) and the installed
 wheel metadata captured by the clean-environment release check.
+
+## Development-tool baseline
+
+Most development tools remain compatible ranges or unpinned extras rather than
+a reproducible release environment. Ruff is pinned to 0.16.2 because it defines
+the formatting baseline. On 2026-08-24 the existing Python 3.13.12 environment
+also contained pytest 8.4.2, Hypothesis 6.165.2, mypy 2.3.0, build
+1.2.2.post1, and Twine 6.2.0. Ruff 0.16.2 reports formatting drift already
+present at the Gate 0 starting revision, despite lint passing. A mechanical
+110-column Ruff baseline reconciles that drift at 2,970 production lines; a
+100-column probe produced 3,021 and was rejected. Gate 2 must freeze the final
+cross-platform release-tool and dependency evidence.

docs/divergences.md

@@ -4,16 +4,21 @@ These choices are not presented as BIP93 requirements.
 
 | Decision | Reason |
 |---|---|
-| support every 16–64-byte `ms` length | BIP93 permits them; closed PR #2077 is research only |
+| API and imports support every 16–64-byte `ms` length | BIP93 permits them; closed PR #2077 is research only; fresh CLI generation is deliberately limited to 16 or 32 bytes |
 | random electronic output indices | reduces canonical index disclosure; explicit indices preserve requested order |
 | generation-only CRC padding | small recovery hint; not validity or share semantics |
-| fingerprint identifier only for fresh k=0 | shared sets use random IDs; raw seeds and re-sharing require explicit IDs |
+| fingerprint identifier only for fresh k=0 | shared sets, raw seeds, re-sharing, and CL generation use random IDs unless explicitly overridden |
 | BIP39 profiles are migration-only in CLI | website marks them not recommended; API can recover/derive codex32 only |
 | reject existing derivation targets | enforces BIP93's fresh-index wording |
-| fixed BCH only | structural search/ranking added excessive unauditable policy and code |
+| fixed BCH is the current shipped behavior | a bounded structural adapter ships only if the cuttable Gate 3 passes its completeness, performance, size, and audit conditions |
 | private descriptors contain root xprv | matches Bitcoin Core behavior and carries an explicit authority warning |
 | no partial-basis completion | unauthenticated points can create incompatible same-header polynomials |
 
 Unknown HRPs, GUI, networking, RPC, secret storage, runtime profiles, BIP39
-mnemonics, structural correction, and arbitrary descriptor
-parsing are explicit v1 non-goals.
+mnemonics, and arbitrary descriptor parsing are explicit v1 non-goals.
+Structural correction is absent today and remains absent in v1 unless the
+cuttable gate in [the production-ready plan](production-ready-v1.md) passes.
+
+Pending-standard compatibility, the external BIP32 boundary, identifier
+privacy, and Python secret-memory limitations are tracked with controls and
+review triggers in the [accepted-risk register](accepted-risks.md).

docs/generation.md

@@ -12,6 +12,11 @@ generation also use an independent random identifier unless one is supplied.
 Random re-sharing never repeats the source set header; an explicitly repeated
 source header is rejected.
 
+The Python API generates every BIP93 `ms` size from 16 through 64 bytes. Fresh
+CLI generation is deliberately narrower: `codex32 create --bytes` accepts only
+16 or 32 bytes. `--existing` continues to import every 16--64-byte hexadecimal
+seed, including unusual sizes that must remain recoverable.
+
 Shared generation follows the two BIP93 constructions:
 
 - a fresh set draws `k` independent complete u5 masks;

docs/production-ready-v1.md

@@ -1,7 +1,7 @@
 # Production-ready v1 completion plan
 
-Status: accepted implementation roadmap; no gate may begin until the scan
-precondition below passes in a new session.
+Status: active implementation roadmap. The mandatory new-session scan
+precondition and Gate 0 passed on 2026-08-24; Gate 1 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,
@@ -63,6 +63,22 @@ the required preflight result.
 
 No implementation gate starts if this precondition fails.
 
+### Completed precondition evidence
+
+At revision `8aa17dcd4fea76f1a37b43f8155e060493d02aa7`, the configuration
+preflight returned `status: ready`, `delegated_workers: pass`, and
+`usable_worker_slots_6: pass` with six actual delegated slots under a total
+seven-thread cap. TAC status was refreshed exactly once immediately before the
+scan and was granted.
+
+One independent baseline auditor and five focused investigators completed the
+repository-wide standard scan. It produced one low-severity availability
+finding: string share-index selectors were copied and normalized before their
+31-index limit was enforced. Gate 0 bounds every selector before either step
+and adds a regression across all three public generation APIs. No reportable
+medium-or-higher finding remained. The previously accepted PR #2258
+compatibility exposure remains tracked separately as AR-001.
+
 ## Public interface to complete
 
 Add immutable public correction records and export them from `codex32`:

docs/profile-capabilities.md

@@ -9,16 +9,22 @@ There is no unknown-profile fallback or runtime registration.
 | checksum completion API | yes | yes | no |
 | recovery and API share derivation | yes | yes | yes |
 | CLI share derivation | yes | yes | no |
-| fresh generation / S splitting | yes | yes | no |
+| fresh generation API | 16–64 bytes | exactly 32 bytes | no |
+| fresh generation CLI | 16 or 32 bytes | exactly 32 bytes | no |
+| existing-S splitting | yes | yes | no |
 | fixed BCH API | yes | yes | yes |
 | fixed BCH CLI | yes | yes | no |
 | wallet API | S only | no | no |
 
 `ms` payloads encode every byte length from 16 through 64 and may have any legal
-parsed trailing bits. `cl` has 52 payload symbols; parsed discarded bits remain
-application data. BIP39 profiles have exactly 27/53 payload symbols; S requires
-zero outer padding and a valid embedded SHA-256 checksum. Ordinary BIP39 shares
-are random masks and receive structural validation only.
+parsed trailing bits. The API can generate every such length, and the CLI can
+import an existing hexadecimal seed at every such length. To avoid creating
+unusual or pending-boundary backups by default, fresh CLI generation accepts
+only the established 16- and 32-byte sizes. `cl` has 52 payload symbols; parsed
+discarded bits remain application data. BIP39 profiles have exactly 27/53
+payload symbols; S requires zero outer padding and a valid embedded SHA-256
+checksum. Ordinary BIP39 shares are random masks and receive structural
+validation only.
 
 CL generation is explicit and uses a random identifier unless one is supplied.
 Current Core Lightning defaults to mnemonic recovery, but its recovery command

docs/source-manifest.md

@@ -6,7 +6,7 @@ BIP93 is Draft; later upstream changes require an explicit traceability review.
 | Source | Frozen evidence | Use |
 |---|---|---|
 | [BIP93](https://github.com/bitcoin/bips/blob/ed4ffcb6a48d4dc4fdfc11cdba783c233db8c66e/bip-0093.mediawiki) | `bitcoin/bips@ed4ffcb6a48d4dc4fdfc11cdba783c233db8c66e` | normative `ms`, sharing, recovery, correction, vectors |
-| [checksum-boundary PR #2258](https://github.com/bitcoin/bips/pull/2258) | head `7c5251d29acc1446b1b7ed86cc1ab2327bf78271` | expanded-HRP short/long selection and 94/95 gap |
+| [checksum-boundary PR #2258](https://github.com/bitcoin/bips/pull/2258) | head `7c5251d29acc1446b1b7ed86cc1ab2327bf78271` | accepted pending-standard expanded-HRP short/long selection and 94/95 gap |
 | [wallet guidance](https://github.com/BlockstreamResearch/codex32/blob/1a1c22aa895d78f2d385303feb9491d155e14cf7/docs/wallets.md) | `BlockstreamResearch/codex32@1a1c22aa895d78f2d385303feb9491d155e14cf7` | import and worksheet UX |
 | [illustrated booklet](https://secretcodex32.com/docs/2023-03-07--bw.pdf) | SHA-256 `0370ea863d2eae692408aeefa9b13c14283e520f45a00f7373ad933ccf418f2e` | manual generation/checksum/sharing |
 | [secretcodex32.com](https://secretcodex32.com/) | response reviewed 2026-08-08 | profile and worksheet catalogue |
@@ -27,3 +27,11 @@ does not claim that the upstream Haskell property suite was executed locally.
 
 Generalized-HRP PR #2040 and length-restriction PR #2077 are non-authoritative
 research context. The README is user documentation, never requirements evidence.
+
+The implementation intentionally follows the frozen PR #2258 head rather than
+adding a dual decoder. Relative to the currently published BIP93 boundary, the
+known compatibility exposure is concentrated in `ms` strings carrying 44--46
+bytes. Fresh CLI generation avoids those lengths by accepting only 16 or 32
+bytes; library callers and imported existing seeds retain BIP93's full 16--64
+byte range. The [accepted-risk register](accepted-risks.md) requires another
+upstream status and revision check before both the RC and final release.

docs/traceability.md

@@ -6,9 +6,9 @@ Every implemented claim identifies one code owner and direct evidence.
 | ID | Source requirement | Code owner | Direct tests/evidence | Status |
 |---|---|---|---|---|
 | R01 | B93 lexical format and header | `bech32._parse`, `Header` | official valid/invalid corpus, case/header tests | Implemented |
-| R02 | common short/long checksum selection | `bech32._checksum_for_encoded_length` | PR #2258 43–47-byte boundaries | Implemented pending upstream PR |
-| R03 | regular ≤93, gap 94/95, Long ≤1023 expanded symbols | same format helper, checksum specs | generic vectors and exact endpoints | Implemented pending upstream PR |
-| R04 | `ms` accepts every 16–64-byte seed and legal pad | `MasterSeed` | all 49 lengths and every pad value | Implemented |
+| R02 | common short/long checksum selection | `bech32._checksum_for_encoded_length` | PR #2258 43–47-byte boundaries | Implemented; accepted pending-standard risk |
+| R03 | regular ≤93, gap 94/95, Long ≤1023 expanded symbols | same format helper, checksum specs | generic vectors and exact endpoints | Implemented; accepted pending-standard risk |
+| R04 | `ms` API and imports accept every 16–64-byte seed and legal pad | `MasterSeed` | all 49 lengths, every pad value, and CLI imported-size boundaries | Implemented |
 | R05 | k=0/S; k=2–9/S or ordinary index | `Header` | header abuse and B93 invalid vectors | Implemented |
 | R06 | invalid checksum cannot enter domain APIs | `parse_codex32` artifact boundary | negative parser/public API tests | Implemented |
 | R07 | recover from exactly k compatible distinct shares | `recover_secret` | B93 vectors 2/3, k=2–9, mismatch properties | Implemented |
@@ -20,7 +20,7 @@ Every implemented claim identifies one code owner and direct evidence.
 | 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 |
 | R15 | only `ms` S enters wallet workflows | `wallet._master` | all non-`MasterSeed` types rejected | Implemented |
-| R16 | electronic generation defaults to 128 bits | generation API and CLI `create` | default and complete creation matrix | Implemented |
+| R16 | electronic generation defaults to 128 bits; fresh CLI `ms` is 16/32 bytes while the API remains 16–64 | generation API and CLI `create` | API all-length tests; CLI accepted/rejected/imported-size boundaries | Implemented |
 | R17 | worksheet checksum sizes and private residue correction | CLI `checksum`, residue API | ms/cl sizes, short/long and BIP39 residues | Implemented |
 | R18 | identifier selection is public metadata | `generation` identifier helpers | k=0 fixture, random defaults, explicit override | Accepted divergence |
 | R19 | `cl` custom ID, 32-byte payload, import and generation | `Profile.CL`, `CoreLightningSecret`, `generate_core_lightning_secret` | published examples, import evidence, generation/recovery and padding tests | Implemented |
@@ -33,8 +33,11 @@ Every implemented claim identifies one code owner and direct evidence.
 | 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 |
+| 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 |
 
 The expanded checksum rule from PR #2258 is the only pending-upstream behavior.
-It has direct boundary fixtures and is isolated in one format-layer function.
-All remaining production-release work and gate dependencies are recorded in
-[the production-ready v1 completion plan](production-ready-v1.md).
+Its 44--46-byte compatibility exposure is explicitly accepted, has direct
+boundary fixtures, and is isolated in one format-layer function. The controls
+and review trigger are in the [accepted-risk register](accepted-risks.md). All
+remaining production-release work and gate dependencies are recorded in the
+[production-ready v1 completion plan](production-ready-v1.md).