Module promote 

Approach-B / Task 10 — the promote-tranche CLI verb: BG-D5 (record-time purchase-provenance attestation), BG-D6 (two-sided informed-consent recording), and BG-D7 (Form 8275 Part II present-by- construction).

Defensive Filing Wizard Task 1: the actual plan/confirm/apply PIPELINE now lives in crate::chokepoint (plan_promote/render_consent/apply_promote) — a reusable chokepoint a future TUI can drive identically. This module is a THIN DRIVER over it: Session::open → build args → plan_promote (mapping a Refusal to a CliError) → print the consent screen → prompt/collect the acknowledgment → apply_promote. It also still owns the copy constants (PROMOTE_ACK_PHRASE, PROVENANCE_TEXT/PROVENANCE_VERSION, CONSENT_INTRO) and the shipped render_consent(terms, gift_only_years) two-arg renderer (kept pub — tests/promote_cli.rs calls it directly, and crate::chokepoint::render_consent(&plan) calls it internally to reproduce the shipped byte order).

Enums

ProvenanceKind

The units’ real acquisition provenance (BG-D5). A CLOSED enumeration: only Purchase clears the promote gate — every other value has a documented FMV-at-receipt/carryover basis from the return (Notice 2014-21; Rev. Rul. 2019-24) and is refused, pointed at modeling the real acquisition instead. CLI-facing only (not part of the persisted schema — only provenance_attested: bool plus the fixed PROVENANCE_TEXT/PROVENANCE_VERSION are stored on the event, per T1’s Acknowledgment).

Constants

PROMOTE_ACK_PHRASE

The exact phrase a filer must affirm to RECORD a promote-tranche decision (BG-D6). Distinct from the pseudo-export ATTEST_PHRASE (lib.rs) — promoting is an estimated-basis FILING CHOICE, not an attestation that a fictional draft is being exported on purpose; conflating the two phrases would let a scripted pseudo-export attest ALSO silently satisfy this gate (N-1). Compared TRIMMED, case-SENSITIVE (mirrors require_attestation’s compare, lib.rs:208).

PROVENANCE_TEXT

BG-D5 attested statement (verbatim, stored on Acknowledgment.provenance_text). The affirmative clause is operative; the negative enumeration is CLOSED so it cannot be misread expressio unius (tax r1 M-6).

PROVENANCE_VERSION

Attestation-text version (BG-D5) — bump if PROVENANCE_TEXT’s wording ever changes.

Functions

promote_tranche

Append a PromoteTranche decision (BG-D1) promoting target_ref’s $0 DeclareTranche to a filed >$0 basis floor, behind the BG-D5 provenance gate, the BG-D7 Part II narrative gate, and the BG-D6 informed-consent acknowledgment. now is the injected decision creation-time (deterministic in tests) — it ALSO doubles as the clock-free “current tax year” the T8 prior-year advisory is filtered against (years >= current are still being authored, not yet filed, so no 1040-X pointer is owed).

render_consent

The consent screen (BG-D6/D10): the penalty-base/interest/mitigation intro, then one line per ConsentTerm. gift_only_years (T9 handoff) relabels a gift-only flagged year’s deduction/basis-Δ as a §1015 donee-basis change rather than a Schedule-A deduction. Kept pub (not pub(crate)): external KATs in tests/promote_cli.rs call this two-arg renderer directly, independent of the full chokepoint::PromotePlan pipeline; chokepoint::render_consent(&plan) also calls this internally to reproduce the shipped promote.rs:443-455 byte order (I-1).