Add @PerfContract meta-annotation and @SuppressPerfContract (AI perf review)

.agents/skills/perf-review/references/checks.md

@@ -25,7 +25,7 @@ Format: **pattern** — *expensive when (the interprocedural condition to trace)
 5. **Polymorphic dispatch on a hot path** — *a hot call site becomes polymorphic enough to defeat the runtime's inlining/devirtualization (real for JIT runtimes — JVM/.NET/V8; AOT/interpreted differ)* — **flag-as-measure** ("may defeat devirtualization; verify on the target runtime") — SEV-2/3 — fix: keep hot call sites mono/bi-morphic; specialize.
 6. **FFI / native-boundary crossing on a hot path** *(central to the shared-core effort)* — *a native crossing per-span/per-item (not batched), or transporting strings/objects rather than primitives/IDs* — flag-with-confidence (boundary cost is mechanism-determined; runtime-specific pinning → addendum) — SEV-1/2 (SEV-1 if it blocks/pins under concurrency) — fix: batch (one per flush, not per item); transport interned IDs not strings; keep crossings off the hot/concurrency path.
 7. **Escape / allocation-elision defeated** *(Java/Go/.NET/V8 all have a version)* — *a refactor makes a previously-local object escape (stored, returned, captured by a closure, passed to a virtual/non-inlined call) → silent heap allocation on a hot path* — **flag-as-measure** ("may now escape and allocate; verify with an allocation profiler") — SEV-2/3 — fix: keep it local; avoid the escaping store/capture.
-8. **`@NoEscape` field-storage violation** — *a field (instance or static, directly or as a generic type argument) declared with an `@NoEscape`-annotated type (`datadog.trace.api.function.NoEscape`), **or** initialized directly from a call to an `@NoEscape`-annotated method — with no comment at the declaration justifying the retention*. The type form marks a concrete type (e.g. `SubSequence`); the method form exists for a return value whose concrete type can't itself carry the annotation (an anonymous class or lambda implementing a JDK interface). The annotation's own javadoc carries a self-contained "Checker contract" section (trigger / not-a-trigger / violation example / compliant example, both forms) written so this can be checked from the diff alone, with no other context needed. The underlying rule is "should", not "must" (RFC-2119 sense): a trigger is a presumptive finding, not an automatic failure — a field with a `// Retained on purpose: <reason>`-style comment is compliant. **flag-with-confidence** — SEV-2/3 (SEV-1 if the annotated type/method shares backing storage with something large, per its own javadoc). Current wearers: `SubSequence`, `Maybe` (type form; see J7 below for `SubSequence`'s specific retention-vs-transient discriminator). **No lint enforces this yet — the AI reviewer is the only check, so this stays here (not under deterministic-lint candidates below) until a checker lands and it can migrate down.**
+8. **`@NoEscape` field-storage violation** — *a field (instance or static, directly or as a generic type argument) declared with an `@NoEscape`-annotated type (`datadog.trace.api.function.NoEscape`), **or** initialized directly from a call to an `@NoEscape`-annotated method — with no comment at the declaration justifying the retention*. The type form marks a concrete type (e.g. `SubSequence`); the method form exists for a return value whose concrete type can't itself carry the annotation (an anonymous class or lambda implementing a JDK interface). The annotation's own javadoc carries a self-contained "Checker contract" section (trigger / not-a-trigger / violation example / compliant example, both forms) written so this can be checked from the diff alone, with no other context needed. The underlying rule is "should", not "must" (RFC-2119 sense): a trigger is a presumptive finding, not an automatic failure — compliant if the declaration carries either a `// Retained on purpose: <reason>`-style comment, or `@SuppressPerfContract(value = NoEscape.class, reason = "...")` (`datadog.perfcontract.SuppressPerfContract` — the generic exemption mechanism shared by every perf-contract marker, not `@NoEscape`-specific), or a named canned-exception annotation itself meta-annotated `@SuppressPerfContract` with `NoEscape.class` among its `value` (e.g. a hypothetical `@Borrowed`) — treat the meta-annotation's own `reason` as satisfying the requirement. Don't flag a `SuppressPerfContract`/canned-exception use as non-compliant just for being terse; that mirrors the annotation's own Checker contract. **flag-with-confidence** — SEV-2/3 (SEV-1 if the annotated type/method shares backing storage with something large, per its own javadoc). Current wearers: `SubSequence`, `Maybe` (type form; see J7 below for `SubSequence`'s specific retention-vs-transient discriminator). **No lint enforces this yet — the AI reviewer is the only check, so this stays here (not under deterministic-lint candidates below) until a checker lands and it can migrate down.**
 
 ## Deterministic-lint candidates (DON'T spend AI budget — make these real lints)
 Fixed-signature, mechanically checkable:

.github/CODEOWNERS

@@ -87,6 +87,7 @@
 /internal-api/src/*/*/datadog/trace/api/env/                    @DataDog/apm-java
 /internal-api/src/*/*/datadog/trace/api/flare/                  @DataDog/apm-java
 /internal-api/src/*/*/datadog/trace/api/function/               @DataDog/apm-java
+/internal-api/src/*/*/datadog/perfcontract/                     @DataDog/apm-java
 /internal-api/src/*/*/datadog/trace/api/intake/                 @DataDog/apm-java
 /internal-api/src/*/*/datadog/trace/api/logging/                @DataDog/apm-java
 /internal-api/src/*/*/datadog/trace/api/metrics/                @DataDog/apm-java

internal-api/src/main/java/datadog/perfcontract/PerfContract.java

@@ -0,0 +1,24 @@
+package datadog.perfcontract;
+
+import datadog.trace.api.function.NoEscape;
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks an annotation as a performance contract for documentation and static analysis. Contract
+ * annotations describe performance constraints, such as the retention rule documented by {@link
+ * NoEscape}, without changing runtime behavior.
+ *
+ * <p>Tools use this meta-annotation to discover contracts and recognize {@link
+ * SuppressPerfContract} exemptions. This annotation defines no rule itself.
+ *
+ * <p>{@link RetentionPolicy#CLASS} lets tools discover contracts in dependency class files without
+ * exposing them through runtime reflection.
+ */
+@Documented
+@Retention(RetentionPolicy.CLASS)
+@Target(ElementType.ANNOTATION_TYPE)
+public @interface PerfContract {}

internal-api/src/main/java/datadog/perfcontract/SuppressPerfContract.java

@@ -0,0 +1,56 @@
+package datadog.perfcontract;
+
+import java.lang.annotation.Annotation;
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Suppresses findings from one or more annotations marked with {@link PerfContract} on the
+ * annotated declaration. Suppressions document deliberate exceptions and have no runtime effect.
+ *
+ * <p>{@link #value} identifies contracts by class, so stale names fail to compile. {@link #reason}
+ * records why the exception is intentional and must not be blank.
+ *
+ * <p>This annotation may also annotate another annotation type to define a reusable suppression.
+ * Applying that annotation is equivalent to applying {@code @SuppressPerfContract} directly and
+ * uses the meta-annotation's reason. Prefer direct use for declaration-specific reasons. Do not
+ * suppress a case that the contract already defines as compliant.
+ *
+ * <p>The target excludes local variables because declaration annotations on them are not stored in
+ * class files. {@link ElementType#ANNOTATION_TYPE} enables reusable suppressions.
+ *
+ * <p>{@link RetentionPolicy#CLASS} makes suppressions visible to classfile-based tools without
+ * exposing them through runtime reflection.
+ *
+ * <p><b>Checker contract.</b> A finding is suppressed when the declaration has either:
+ *
+ * <ul>
+ *   <li>this annotation with the relevant contract in {@link #value} and a non-blank {@link
+ *       #reason}; or
+ *   <li>an annotation that carries such a {@code @SuppressPerfContract} annotation.
+ * </ul>
+ *
+ * <p>Every class in {@code value} must itself be annotated {@link PerfContract}; otherwise the
+ * suppression is invalid. A terse reason is valid if it is non-blank.
+ */
+@Documented
+@Retention(RetentionPolicy.CLASS)
+@Target({
+  ElementType.TYPE,
+  ElementType.FIELD,
+  ElementType.METHOD,
+  ElementType.CONSTRUCTOR,
+  ElementType.PARAMETER,
+  ElementType.ANNOTATION_TYPE
+})
+public @interface SuppressPerfContract {
+
+  /** The perf-contract marker(s) being suppressed, by class reference. */
+  Class<? extends Annotation>[] value();
+
+  /** Why this exception is deliberate and reviewed, not an oversight. */
+  String reason();
+}

internal-api/src/main/java/datadog/trace/api/function/NoEscape.java

@@ -1,5 +1,7 @@
 package datadog.trace.api.function;
 
+import datadog.perfcontract.PerfContract;
+import datadog.perfcontract.SuppressPerfContract;
 import java.lang.annotation.Documented;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
@@ -61,7 +63,8 @@
  * static checker, or in the meantime by an AI reviewer (see the perf-review skill's {@code
  * checks.md}) -- without needing to read this class's prose above. Because the underlying rule is
  * "should" rather than "must", a trigger is a presumptive finding to raise, not an automatic
- * failure: a field that carries a comment explaining the deliberate exception is compliant.
+ * failure: a field that carries a comment explaining the deliberate exception, or a {@link
+ * SuppressPerfContract} annotation citing this class, is compliant.
  *
  * <ul>
  *   <li><b>Trigger (type form):</b> a field (instance or static, in any class) whose declared type
@@ -75,22 +78,29 @@
  *       explaining why the retention is safe.
  *   <li><b>Not a trigger:</b> a local variable, a method parameter, or a method return type -- this
  *       rule flags <em>storage</em> that outlives the call, not ordinary use within it. Also not a
- *       trigger: the same field shape, annotated with a comment justifying the retention; or a
- *       method call chained/consumed within the same expression/statement rather than assigned to a
- *       field (e.g. {@code for (T t : ConcurrentHashtable.hashIterable(state, keyHash))}).
+ *       trigger: the same field shape, annotated with a comment justifying the retention, with
+ *       {@code @SuppressPerfContract(value = NoEscape.class, reason = "...")} ({@link
+ *       SuppressPerfContract} -- the generic exemption mechanism shared by every perf-contract
+ *       marker, not {@code @NoEscape}-specific), or with a named canned-exception annotation itself
+ *       meta-annotated {@code @SuppressPerfContract} with {@code NoEscape.class} among its {@code
+ *       value} (e.g. a hypothetical {@code @Borrowed}); or a method call chained/consumed within
+ *       the same expression/statement rather than assigned to a field (e.g. {@code for (T t :
+ *       ConcurrentHashtable.hashIterable(state, keyHash))}).
  *   <li><b>Violation example (type):</b> {@code private final SubSequence cached;}
  *   <li><b>Violation example (method):</b> {@code private final Iterator<T> cached =
  *       ConcurrentHashtable.hashIterator(state, keyHash);}
  *   <li><b>Compliant example:</b> {@code private final String cached;} -- materialize the view
  *       (e.g. call {@code toString()}) before storing it. Or, if retention is a deliberate,
- *       reviewed exception: {@code // Retained on purpose: <reason>} above the field.
+ *       reviewed exception: {@code // Retained on purpose: <reason>} above the field, or
+ *       {@code @SuppressPerfContract(value = NoEscape.class, reason = "...")}.
  *   <li><b>Out of scope (v1):</b> escape through a non-generic/raw container, a capturing lambda,
  *       or a returned value the caller goes on to store several calls later (rather than at the
  *       call site itself). Flag only the field-declaration shapes above; widen this contract only
  *       once a real case proves it insufficient, rather than guessing ahead of one.
  * </ul>
  */
 @Documented
+@PerfContract
 @Retention(RetentionPolicy.CLASS)
 @Target({ElementType.TYPE, ElementType.METHOD})
 public @interface NoEscape {}

internal-api/src/main/java/datadog/trace/api/function/Strategy.java

@@ -1,5 +1,6 @@
 package datadog.trace.api.function;
 
+import datadog.perfcontract.PerfContract;
 import java.lang.annotation.Documented;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Inherited;
@@ -45,6 +46,7 @@
  */
 @Documented
 @Inherited
+@PerfContract
 @Retention(RetentionPolicy.SOURCE)
 @Target({ElementType.TYPE, ElementType.PARAMETER})
 public @interface Strategy {}

internal-api/src/main/java/datadog/trace/api/function/StrategyConsumer.java

@@ -1,5 +1,6 @@
 package datadog.trace.api.function;
 
+import datadog.perfcontract.PerfContract;
 import java.lang.annotation.Documented;
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
@@ -17,6 +18,7 @@
  * at these call sites are {@code static final} constants or non-capturing lambdas.
  */
 @Documented
+@PerfContract
 @Retention(RetentionPolicy.SOURCE)
 @Target(ElementType.METHOD)
 public @interface StrategyConsumer {}