Add cost and latency overhead metrics

[rudrakshkarpe]

Summary

• Add opt-in LatencyOverhead and CostEfficiency metrics with configurable thresholds
• Expose performance metric helpers through the Python API and CLI flags
• Include aggregate metric summaries in JSON reports so performance scores are machine-readable
• Document how to enable performance scoring and what trace fields are required

Closes #4

Commit Stack

1. ef08a71 Add performance overhead metrics
2. 47d4cfe Expose opt-in performance metrics
3. 133448d Add CLI switches for performance scoring
4. 65484e1 Document performance metric usage
5. fe3da29 Include metric summaries in JSON reports
6. 822ca7c Type report payload helper

Validation

• .venv/bin/python -m ruff check .
• .venv/bin/python -m mypy src
• .venv/bin/python -m pytest
• .venv/bin/python -m pytest benchmarks/ --codspeed
• rm -rf dist && .venv/bin/python -m build && .venv/bin/python -m twine check dist/*

[codspeed-hq]

Merging this PR will not alter performance

✅ 2 untouched benchmarks

---

_{Comparing feat/cost-latency-metrics (822ca7c) with main (d76cf67)}