[cb521]

Existing YARN reports compare application-attributed worker costs, but do not calculate annual fleet expense or how long migration and hardware purchases take to pay back. A GPU run can cost less while an always-on GPU fleet costs more over the year.

This adds yarn-resource-cost project and a project_costs() Python API to consume two existing single-run JSON reports plus an explicit annual plan. It reuses complete application accounting and price provenance, with application IDs selected by the caller.

• Annualize existing allocated costs, or calculate the full provisioned worker bill from node counts, paid uptime and rates. One plan-wide basis keeps the two scenarios comparable; provisioned costs include idle and retained pools without adding application charges again.
• Add named operating expenses and timed migration, purchase, replacement or resale cash events. Report annual and horizon costs, savings, ROI, NPV and sustained payback that accounts for later replacement spending.
• Reject incomplete/failed runs, missing allocated prices, mixed allocated currencies, duplicate application selections and insufficient annual capacity per node class. Preserve the source evidence and planning assumptions in JSON.
• Include worked examples, formulas, synthetic regression tests and standalone packaging support.

Validation: 140 tests and 33 subtests passed on Python 3.12; all 21 new tests also passed on Python 3.10. Python compilation, installed-console execution, standalone bundle build/extraction/tests and git diff --check passed. Tests include the existing synthetic ResourceManager fixture and hand-checkable financial examples; no live cloud or GPU workload was run.

This is a constant-price/frequency projection. Callers establish workload equivalence and supply paid uptime and costs; annual resource capacity is a necessary check, not a scheduling simulation. Owned-hardware expenses use explicit cash inputs rather than inferred depreciation, power or replacement schedules.

Draft for feedback on scope and integration, related to NVIDIA/cudf-spark#16220. Maintainers have not yet settled the destination of that contribution; this proposes the annual planning layer within the existing benchmark cost tool.