Add a perf-review check for @BackgroundOnly code reached from the foreground (AI perf review)

[dougqh]

What Does This Do

Adds an AI-review check for @BackgroundOnly code called from the foreground, and gives the @ForegroundSafe / @BackgroundOnly markers the contract that check reads.

• @BackgroundOnly checker contract (Javadoc): foreground code must not directly call background-only code. Foreground code is a method marked @ForegroundSafe, a method of a @ForegroundSafe type without a method-level @BackgroundOnly, or an advice method (@Advice.OnMethodEnter / @Advice.OnMethodExit), which ByteBuddy inlines into the application method. Background-only code is defined the same way in reverse. Handing work to a background thread, such as enqueueing it, is not a trigger. Calls that go through unmarked intermediate methods are out of scope for now.
• Both markers become perf contracts: meta-annotated @PerfContract with CLASS retention, like @NoEscape and @StaticLifetime. That lets @SuppressPerfContract(value = BackgroundOnly.class, reason = "...") mark a deliberate exception.
• perf-review check Track 3rd party licenses #10 in checks.md:
  • flag-with-confidence when the caller is marked @ForegroundSafe or is advice, since both ends are declared;
  • flag-as-measure when the caller is unmarked but on the skill's hot-path map (decorators, span lifecycle, tag-map ops, propagation), since "foreground" is then inferred.

Motivation

The markers landed in #12471, but nothing checked them: their Javadoc said the rule was "not yet enforced" until a static checker (APMLP-1645). Like @NoEscape and @StaticLifetime, the AI reviewer can apply the rule now, from a contract written to be checked from the diff.

This replaces draft #12606. #12606's description said the checker rule was dropped and deferred to "APMLP-1645 and, if useful, to the /perf-review skill"; this PR is that follow-up.

Additional Notes

• First wearers: SimpleUtf8Cache and GenerationalUtf8Cache are now @BackgroundOnly. Both trade extra CPU for less allocation, which only pays off on a serializer thread, and every production caller (TraceMapperV0_4, OtlpCommonProto via the OTLP writer's worker) already runs on one. Add @ForegroundSafe/@BackgroundOnly declared-contract annotations #12606 also marked DDCache, FixedSizeCache and the EncodingCache interface; those can follow separately once their foreground/background split is checked.
• The retention change from SOURCE to CLASS has no runtime effect. It only makes the markers visible to class-file tools, as @PerfContract expects.

Contributor Checklist

• :internal-api:compileJava, :internal-api:javadoc, :communication:compileJava, :communication:javadoc, spotlessApply

Jira ticket

APMLP-1645

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-13T21:14:09.463427Z	e8985fd	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[datadog-prod-us1-4]

More details

The annotation contracts and foreground/background review rule are consistent with the inspected cache callers. The completed static review found no actionable defect; executable cache behavior is unchanged.

Was this helpful? React 👍 or 👎

_{Open Bits AI session}

_{🤖 Bits Code Review · Commit e8985fd}

[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	14.66 s	14.61 s	[-0.5%; +1.2%] (no difference)
startup:insecure-bank:tracing:Agent	13.52 s	13.61 s	[-1.4%; +0.1%] (no difference)
startup:petclinic:appsec:Agent	17.05 s	16.57 s	[-1.3%; +7.2%] (no difference)
startup:petclinic:iast:Agent	16.81 s	17.03 s	[-2.2%; -0.4%] (maybe better)
startup:petclinic:profiling:Agent	16.08 s	16.68 s	[-7.7%; +0.5%] (no difference)
startup:petclinic:sca:Agent	17.03 s	16.38 s	[-0.2%; +8.1%] (no difference)
startup:petclinic:tracing:Agent	15.98 s	15.71 s	[-2.5%; +5.9%] (no difference)

Commit: b7a2da60 · 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.