Exact ledger validation first materially unexecuted year

First year in which a requested Roth conversion is materially not executed.

Field: firstMateriallyUnexecutedYear Unit: calendar year Basis: no dollar basis Computed by: Engine Status: Complete chain

Appears in: optimize-page (first materially unexecuted year); report (modeled-findings validation "First material execution shortfall")

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

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