Add @strategy marker annotation for static-polymorphism strategies (#11984)

Add @strategy / @StrategyConsumer marker annotations for static-polymorphism strategies

Marker-only (no enforcement yet): telegraphs the static-polymorphism strategy pattern and gives a future checker targets. @strategy marks strategy types/parameters; @StrategyConsumer marks the higher-order methods that must inline for them to specialize. Contracts live in the javadoc. Applications land in stacked PRs (FlatHashtable first).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Explain static polymorphism inline in @strategy javadoc

Address review: describe 'static polymorphism' directly in the annotation
rather than referring to FlatHashtable, which is a consumer of @strategy — the
reference was a conceptual back-reference that left the base annotation unable to
stand on its own.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Merge branch 'master' into dougqh/strategy-annotation

Merge branch 'master' into dougqh/strategy-annotation

Co-authored-by: devflow.devflow-routing-intake <devflow.devflow-routing-intake@kubernetes.us1.ddbuild.io>

Author: dougqh

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

@@ -0,0 +1,50 @@
+package datadog.trace.api.function;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks a <b>static-polymorphism strategy</b>: a stateless, concrete-typed policy object that lets
+ * one shared algorithm specialize to straight-line code per caller, without runtime virtual
+ * dispatch.
+ *
+ * <p><b>What "static polymorphism" means here.</b> Ordinary (dynamic) polymorphism resolves the
+ * implementation at run time — an {@code invokevirtual}/{@code invokeinterface} that can go
+ * megamorphic on a shared call site. Static polymorphism instead makes the implementation known to
+ * the JIT: hold the strategy in a {@code static final} field of its <i>concrete</i> type (a stable
+ * constant of exact type), keep its methods small, and let the consuming method inline. The call
+ * site then sees the exact type, so the JIT devirtualizes the strategy's calls and inlines them,
+ * and the one generic algorithm compiles to specialized, monomorphic, allocation-free code per
+ * caller — C++-template-like specialization, driven by the JIT rather than a code generator. The
+ * win is <b>structural</b> (it follows from the exact-typed constant), not a speculative bet on
+ * class-hierarchy analysis or type profiling that a second implementation or a polluted profile
+ * could quietly undo.
+ *
+ * <p>This is a documentation-and-tooling marker; it changes no behavior. It exists to telegraph the
+ * pattern to readers and to give a future checker something to verify. The discipline it names is
+ * <b>not yet enforced</b> — hold to it by hand until the checker lands.
+ *
+ * <p><b>On a type</b> ({@link ElementType#TYPE}): this type is a strategy. To get the
+ * specialization a caller must hold it in a {@code static final} field <i>declared with the
+ * concrete type</i> (not an abstract base or interface), and the consuming method must inline so
+ * the call site sees the exact type. Keep the methods small so they inline.
+ *
+ * <p><b>On a parameter</b> ({@link ElementType#PARAMETER}): this parameter is a strategy slot. The
+ * argument at each call site should be a {@code static final} constant or a <i>non-capturing</i>
+ * lambda, so it stays a single monomorphic, allocation-free instance. A parameter can carry this
+ * marker even when its type cannot — e.g. a {@code java.util.function.Function} slot we don't own.
+ *
+ * <p><b>The failure mode is silent.</b> Held at an abstract/interface type, filled with a capturing
+ * lambda, or called from a site that doesn't inline, it still compiles and runs correctly — it just
+ * stays megamorphic and/or allocates, quietly losing the win. Verify the hot ones with {@code
+ * -XX:+PrintInlining}.
+ */
+@Documented
+@Inherited
+@Retention(RetentionPolicy.SOURCE)
+@Target({ElementType.TYPE, ElementType.PARAMETER})
+public @interface Strategy {}

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

@@ -0,0 +1,22 @@
+package datadog.trace.api.function;
+
+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 a higher-order method that <b>consumes</b> {@link Strategy} objects — one whose strategy
+ * parameters only specialize if this method itself inlines, so each call site sees the exact
+ * strategy type (see {@link Strategy}). Keep it small so it inlines.
+ *
+ * <p>Documentation-and-tooling marker; it changes no behavior. It pairs with {@link Strategy}: a
+ * strategy type/parameter says "I am a strategy / a strategy slot," while this says "I am the site
+ * where they must specialize." A future checker can enforce that the arguments filling those slots
+ * at these call sites are {@code static final} constants or non-capturing lambdas.
+ */
+@Documented
+@Retention(RetentionPolicy.SOURCE)
+@Target(ElementType.METHOD)
+public @interface StrategyConsumer {}