Exact ledger validation requested conversion total

Total Roth-conversion dollars requested by the candidate schedule.

Field: requestedConversionTotal Unit: US dollars Basis: nominal dollars Computed by: Engine Status: Complete chain

Appears in: report (requested conversion total); report (modeled-findings validation "Requested conversions")

Calculation records

• Full projection conversion execution Formula record, justified by derivation

  Purpose: Report how much of a requested conversion schedule the full year-by-year projection actually executed.

  Statement: projection/optimizePlan.ts#evaluateExactLedgerSchedule sums the requested schedule into requestedConversionTotal with strategies/conversionScheduleTotal.ts#conversionScheduleTotal (left to right from 0, the one schedule sum every surface reads), sums the candidate result's YearResult.rothConversion into the executed total, publishes executedConversionRatio as min(1, executed / requested) and exactly 1 when nothing was requested, and publishes firstMateriallyUnexecutedYear as the first ascending requested year whose shortfall is more than max(DECISION_MATERIAL_SHORTFALL_DOLLARS, requested times DECISION_MATERIAL_SHORTFALL_PCT), else null. decisions/evaluateCandidate.ts#buildConversionExecution also decides, once, whether the whole schedule is short by more than max(DECISION_MATERIAL_SHORTFALL_DOLLARS, requested total times DECISION_MATERIAL_SHORTFALL_PCT) with at least the minimum requested (the test that makes the evaluation diagnostic), and the validation publishes executedWithoutMaterialShortfall, true when no year and not the whole schedule is short by more than its margin, for the Optimize page to read instead of re-deriving the margins.

  Formula: requested = sum(schedule.amount); executed = sum(candidate.years.rothConversion); ratio = requested > 0 ? min(1, executed / requested) : 1; firstMateriallyUnexecutedYear = min { y ascending : requested_y - executed_y > max(1000, requested_y * 0.05) }, else null; executedWithoutMaterialShortfall = firstMateriallyUnexecutedYear is null and not (requested >= 1 and requested - executed > max(1000, requested * 0.05))

  • requested_y: Requested conversion dollars in year y (unit: nominal USD) (domain: nonnegative)
  • executed_y: Candidate result rothConversion in year y (unit: nominal USD) (domain: nonnegative)
  • DECISION_MATERIAL_SHORTFALL_DOLLARS: Absolute material shortfall margin (unit: nominal USD) (domain: 1000)
  • DECISION_MATERIAL_SHORTFALL_PCT: Proportional material shortfall margin (unit: 1) (domain: 0.05)

  Timing: one candidate schedule against its own full-projection run, requested years tested in ascending order

  Rounding: none; the dollar sums carry binary floating-point representation and the materiality comparison is strict

  Limits:

  • The materiality margin is resolved per year from that year's own requested amount, not once from the schedule total, and the comparison is strictly more than, so a shortfall equal to its margin does not qualify; the ratio is capped at 1 so an over-execution cannot read as more than the whole request, and the zero-request branch is the stated exact 1 rather than a division. Beyond the worksheet's rows the test assumes a validated plan with one non-inherited traditional account and a baseline result that the entry requires and the worksheet does not name; both projections are supplied as ProjectionResult values at the exported validation entry, so the requested-versus-executed arithmetic is the real function while neither ledger run is exercised here. ExactLedgerValidation.executedConversionTotal has no census family this round, so it is read only as the ratio's numerator and is not published by this record.

  Provenance: derived by codex, implemented by claude-subagent.

  Independent review: grok

  Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

  Worksheet: exact-ledger-conversion-execution.md Mutation receipt: exact-ledger-conversion-execution.mutation.md

  Evidence tests: optimizePlan.evidence.test.ts

  Implemented in: optimizePlan.ts; evaluateCandidate.ts; conversionScheduleTotal.ts

  Is the number of: exact-ledger-validation-requested-conversion-total, exact-ledger-validation-executed-conversion-ratio, exact-ledger-validation-first-materially-unexecuted-year

Records that feed this number

• Conversion schedule total Formula record, justified by derivation

  Purpose: The one sum of a Roth conversion schedule, as every surface that prints a schedule total shows it.

  Statement: strategies/conversionScheduleTotal.ts#conversionScheduleTotal (re-exported by strategies/optimizer.ts) adds a conversion schedule's amounts left to right from 0, the order every surface used, so one schedule always gives one double (floating-point addition is not associative), and refuses a non-finite amount with a RangeError. OptimizedSchedule.conversionTotal publishes it on the raw solve (optimizeSchedule, whatever its status) and on each cleaned schedule (projection/optimizePlan.ts#scheduleWithConversions recomputes it rather than copying it), ExactLedgerTournament.winnerConversionTotal publishes it for the recommended schedule, the engine's own cleaned-schedule gates read it, and decisions/evaluateCandidate.ts#buildConversionExecution computes the requested total with it. Amounts of $10,000.25, $20,000.50 and $30,000.75 total $60,001.50; 0.1, 0.2 and 0.3 total 0.6000000000000001 left to right, where the other association gives 0.6. Units: nominal dollars of different years added. Rounding: none beyond the amounts' own cents.

  Formula: total = ((0 + a_1) + a_2) + … + a_n

  • a_i: The i-th listed conversion amount of the schedule (unit: nominal USD of its year) (domain: finite)

  Timing: once per schedule, where the schedule is made

  Rounding: none beyond the amounts' own cents

  Limits:

  • The total adds nominal dollars of different years, undiscounted; the Optimize page's schedule chart says nominal dollars, while the hero and the Strategy callout do not.
  • A total says nothing about which years carry it; the page prints the count of entries beside it, and every raw entry is above $0.50.
  • A cleaned schedule carries the raw solve's endingAfterTax and lifetimeTax, which describe the raw schedule; nothing reads them from a cleaned schedule.

  Provenance: derived by claude, implemented by claude-subagent.

  Independent review: codex

  Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

  Worksheet: optimizer-schedule-conversion-total.md Mutation receipt: optimizer-schedule-conversion-total.mutation.md

  Evidence tests: optimizer.conversionTotal.evidence.test.ts

  Implemented in: conversionScheduleTotal.ts; optimizer.ts; optimizePlan.ts; evaluateCandidate.ts

  Is the number of: optimizer-schedule-conversion-total

  Feeds: exact-ledger-validation-requested-conversion-total

Engine source: engine/src/projection/optimizePlan.ts (ExactLedgerValidation.requestedConversionTotal)