Add @ForegroundSafe / @BackgroundOnly marker annotations

[dougqh]

Summary

• Adds two documentation-and-tooling marker annotations, @ForegroundSafe and @BackgroundOnly (datadog.trace.api.function), that declare whether code is cheap enough to run on application (foreground) threads or must be confined to a background thread.
• @ForegroundSafe is the strictly stronger guarantee — safe from either thread context; @BackgroundOnly must never be reached from a foreground call site.
• Both apply to types and methods, with method-level taking precedence over type-level.
• Pure declaration: SOURCE retention, no runtime behavior change. No annotation of real call sites and no checker yet — those are tracked separately (APMLP-1544, APMLP-1546).

Implements APMLP-1543, laying groundwork for annotation-checking support in the /perf-review skill (APMLP-1513).

Test plan

• techdebt review: no issues (pure marker annotations, no duplication/dead code).
• perf-review review: no findings (SOURCE-retention, zero runtime footprint).
• ./gradlew spotlessCheck / :internal-api:spotbugsMain

🤖 Generated with Claude Code

[dd-octo-sts]

🟢 Java Benchmark SLOs — All performance SLOs passed

Suite	Status
Startup	🟢 pass

SLO thresholds are defined here based on automatically generated metrics. A warning is raised when results are within 5% of the threshold.

PR vs. master results

Scenario	Candidate	master	Δ (95% CI of mean)
startup:insecure-bank:iast:Agent	13.99 s	14.01 s	[-0.7%; +0.5%] (no difference)
startup:insecure-bank:tracing:Agent	13.02 s	13.02 s	[-0.6%; +0.6%] (no difference)
startup:petclinic:appsec:Agent	17.45 s	17.23 s	[+0.4%; +2.2%] (maybe worse)
startup:petclinic:iast:Agent	17.44 s	17.54 s	[-1.5%; +0.4%] (no difference)
startup:petclinic:profiling:Agent	17.07 s	17.13 s	[-1.5%; +0.8%] (no difference)
startup:petclinic:sca:Agent	17.53 s	17.35 s	[+0.2%; +2.0%] (maybe worse)
startup:petclinic:tracing:Agent	16.06 s	16.59 s	[-7.3%; +1.0%] (no difference)

Commit: df2d3687 · CI Pipeline · Benchmarking Platform UI

---

Load and DaCapo benchmarks can be triggered manually in the GitLab pipeline. Results will appear in the Benchmarking Platform UI after completion.