feat(core): v0.2.0 ergonomics release

[seanbrar]

Summary

Adds decorator support (@telemetry.timed), reporter lifecycle hooks (flush/shutdown), strict scope
validation, and async isolation guarantees. Replaces @contextmanager with an explicit _Scope class for
16-29% performance improvements in enabled mode, with proper context manager contract compliance.

Notes

• The _Scope optimization initially set context vars in init; corrected to enter to maintain context
  manager contract. Benchmarks confirm no performance impact from the fix.
• Performance benchmarks added (moved from v0.4.0 roadmap) to validate the _Scope optimization.
• uv.lock now tracked for reproducible CI.

---

Note

Medium Risk
Touches core scope entry/exit and validation paths, so subtle behavior/performance regressions are possible despite added benchmarks and expanded test coverage.

Overview
Delivers the v0.2.0 ergonomics release by adding telemetry.timed() for sync/async function instrumentation, plus flush()/shutdown() lifecycle forwarding to reporters (no-op implementations included for the built-in SimpleReporter).

Core timing logic is refactored from @contextmanager to an explicit _Scope context manager and tightens validation/error messaging for scope names and reporter shape (early TelemetryContext(...) validation), alongside minor metric path construction optimizations.

Updates documentation to cover decorators, lifecycle, strict scope mode (NULLSCOPE_STRICT), and async task isolation; adds a benchmark suite (benchmarks/) with baseline results, expands tests (including async isolation + lifecycle + validation), bumps version to 0.2.0, and begins tracking uv.lock for reproducible environments.

^{Written by Cursor Bugbot for commit cbb0a35. This will update automatically on new commits. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}