feat: add AllowCopilotExperimental opt-in

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: edburns

java/README.md

@@ -138,10 +138,34 @@ By default, referencing an experimental API from your code causes a **compile-ti
 
 ```
 error: Use of experimental API 'ExperimentalType' in field type is not allowed.
-       Add compiler option -Acopilot.experimental.allowed=true to opt in.
+       Add @AllowCopilotExperimental or compiler option -Acopilot.experimental.allowed=true to opt in.
 ```
 
-To opt in and use experimental APIs, pass the annotation processor option `-Acopilot.experimental.allowed=true` to the Java compiler.
+To opt in and use experimental APIs, either:
+
+- annotate the consuming class, method, or constructor with `@AllowCopilotExperimental`, or
+- pass the annotation processor option `-Acopilot.experimental.allowed=true` to the Java compiler.
+
+### In code
+
+```java
+import com.github.copilot.AllowCopilotExperimental;
+import test.ExperimentalType;
+
+@AllowCopilotExperimental
+public class Consumer {
+    private ExperimentalType field;
+
+    public ExperimentalType getIt() {
+        return field;
+    }
+
+    @AllowCopilotExperimental
+    public ExperimentalType echo(ExperimentalType value) {
+        return value;
+    }
+}
+```
 
 ### Maven
 
@@ -184,11 +208,11 @@ The processor uses standard JSR 269 annotation processing APIs for maximum porta
 
 | Usage pattern | Caught? | Workaround |
 |---|---|---|
-| `new ExperimentalType()` in a method body (no field/param declaration) | ❌ | Assign to a typed field or variable declaration |
-| `ExperimentalType.staticMethod()` inline call | ❌ | Store result in a typed variable |
-| Method reference `ExperimentalType::method` | ❌ | Use explicit lambda with typed parameter |
-| Local variable with experimental type (var inference) | ❌ | Use explicit type declaration at field level |
-| Cast to experimental type | ❌ | Assign to a typed field |
+| `new ExperimentalType()` in a method body (no field/param declaration) | ❌ | Use the compiler flag for a whole-compilation opt-in |
+| `ExperimentalType.staticMethod()` inline call | ❌ | Use the compiler flag for a whole-compilation opt-in |
+| Method reference `ExperimentalType::method` | ❌ | Use the compiler flag for a whole-compilation opt-in |
+| Local variable with experimental type (including `var` inference) | ❌ | Move the usage into a declaration the processor can see, or use the compiler flag |
+| Cast to experimental type | ❌ | Use the compiler flag for a whole-compilation opt-in |
 
 In practice, these gaps rarely matter: any meaningful use of an experimental SDK type almost always appears in a field declaration, method signature, or type hierarchy — all of which are caught. A purely inline expression with no declaration footprint (e.g., `session.rpc().experimental.foo().join()`) is the only case that would slip through. See [ADR-004](docs/adr/adr-004-copilotexperimental.md) for the design rationale.
 
@@ -214,7 +238,7 @@ public class Consumer {
 }
 ```
 
-The gate also applies to individual methods annotated with `@CopilotExperimental` on otherwise stable types. When a type-level annotation is present, all member accesses through that type are considered experimental.
+The gate also applies to individual methods annotated with `@CopilotExperimental` on otherwise stable types. When a type-level annotation is present, all member accesses through that type are considered experimental. `@AllowCopilotExperimental` mirrors the same declaration-level boundary: annotating a class opts in that class and its enclosed declarations, while annotating a method or constructor opts in just that executable signature.
 
 ## Projects Using This SDK
 

java/src/main/java/com/github/copilot/AllowCopilotExperimental.java

@@ -0,0 +1,34 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+
+package com.github.copilot;
+
+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;
+
+/**
+ * Opts a declaration into using {@link CopilotExperimental} APIs.
+ *
+ * <p>
+ * Apply this annotation to a type to allow declaration-level references to
+ * experimental APIs anywhere within that type, or apply it to a method or
+ * constructor to allow experimental API usage in that executable's signature.
+ * This is a code-level alternative to the compiler option
+ * {@code -Acopilot.experimental.allowed=true}.
+ *
+ * <p>
+ * This opt-in has the same declaration-level scope as the processor itself. It
+ * does not affect expression-only usages inside method bodies that are not
+ * visible to standard JSR 269 annotation processing.
+ *
+ * @since 1.0.0
+ */
+@Documented
+@Retention(RetentionPolicy.CLASS)
+@Target({ElementType.TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR})
+public @interface AllowCopilotExperimental {
+}

java/src/main/java/com/github/copilot/CopilotExperimental.java

@@ -16,7 +16,8 @@
  *
  * <p>
  * By default, referencing an experimental API from consumer code causes a
- * compile-time error. To opt in, pass the compiler option:
+ * compile-time error. To opt in, either annotate the consuming declaration with
+ * {@link AllowCopilotExperimental} or pass the compiler option:
  *
  * <pre>
  * -Acopilot.experimental.allowed=true

java/src/main/java/com/github/copilot/CopilotExperimentalProcessor.java

@@ -18,8 +18,6 @@
 import javax.lang.model.element.VariableElement;
 import javax.lang.model.type.DeclaredType;
 import javax.lang.model.type.TypeMirror;
-import javax.lang.model.util.Elements;
-import javax.lang.model.util.Types;
 import javax.tools.Diagnostic;
 import java.util.Set;
 
@@ -30,7 +28,8 @@
  * Any declaration-level reference to a type or method annotated with
  * {@link CopilotExperimental} in consumer source code causes a compilation
  * error unless the compiler option {@code -Acopilot.experimental.allowed=true}
- * is provided.
+ * is provided or the consuming declaration is annotated with
+ * {@link AllowCopilotExperimental}.
  *
  * <p>
  * This processor uses only standard JSR 269 APIs ({@code javax.lang.model.*})
@@ -46,16 +45,12 @@
 public class CopilotExperimentalProcessor extends AbstractProcessor {
 
     private boolean allowed;
-    private Elements elementUtils;
-    private Types typeUtils;
 
     @Override
     public synchronized void init(ProcessingEnvironment processingEnv) {
         super.init(processingEnv);
         String value = processingEnv.getOptions().get("copilot.experimental.allowed");
         this.allowed = "true".equals(value);
-        this.elementUtils = processingEnv.getElementUtils();
-        this.typeUtils = processingEnv.getTypeUtils();
     }
 
     @Override
@@ -71,8 +66,8 @@ public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment
 
     private void checkElement(Element element) {
         // Skip elements that are themselves annotated @CopilotExperimental
-        // (they are the definitions, not consumers)
-        if (isExperimental(element)) {
+        // (they are the definitions, not consumers), or that explicitly opt in.
+        if (isExperimental(element) || isAllowListed(element)) {
             return;
         }
 
@@ -148,11 +143,22 @@ private boolean isExperimental(Element element) {
         return enclosing != null && enclosing.getAnnotation(CopilotExperimental.class) != null;
     }
 
+    private boolean isAllowListed(Element element) {
+        Element current = element;
+        while (current != null) {
+            if (current.getAnnotation(AllowCopilotExperimental.class) != null) {
+                return true;
+            }
+            current = current.getEnclosingElement();
+        }
+        return false;
+    }
+
     private void reportError(Element experimentalElement, Element usageSite, String context) {
         Messager messager = processingEnv.getMessager();
         messager.printMessage(Diagnostic.Kind.ERROR,
                 "Use of experimental API '" + experimentalElement.getSimpleName() + "' in " + context
-                        + " is not allowed. Add compiler option -Acopilot.experimental.allowed=true to opt in.",
+                        + " is not allowed. Add @AllowCopilotExperimental or compiler option -Acopilot.experimental.allowed=true to opt in.",
                 usageSite);
     }
 }

java/src/test/java/com/github/copilot/CopilotExperimentalProcessorTest.java

@@ -64,6 +64,30 @@ public class Consumer extends ExperimentalType {
             }
             """;
 
+    private static final String CLASS_ANNOTATED_CONSUMER = """
+            package consumer;
+            import com.github.copilot.AllowCopilotExperimental;
+            import test.ExperimentalType;
+            @AllowCopilotExperimental
+            public class Consumer extends ExperimentalType {
+                private ExperimentalType field;
+                public ExperimentalType getIt() { return field; }
+                public void setIt(ExperimentalType value) { this.field = value; }
+            }
+            """;
+
+    private static final String METHOD_ANNOTATED_CONSUMER = """
+            package consumer;
+            import com.github.copilot.AllowCopilotExperimental;
+            import test.ExperimentalType;
+            public class Consumer {
+                @AllowCopilotExperimental
+                public ExperimentalType getIt(ExperimentalType value) {
+                    return value;
+                }
+            }
+            """;
+
     @Test
     void failsByDefault_whenFieldOrSignatureUsesExperimentalType() {
         DiagnosticCollector<JavaFileObject> diagnostics = compile(
@@ -90,6 +114,28 @@ void failsByDefault_whenExtendingExperimentalType() {
                 "Expected compile error for extending experimental type, got: " + diagnostics.getDiagnostics());
     }
 
+    @Test
+    void passes_whenAllowAnnotationIsOnType() {
+        DiagnosticCollector<JavaFileObject> diagnostics = compile(
+                List.of(inMemorySource("test.ExperimentalType", EXPERIMENTAL_TYPE_SOURCE),
+                        inMemorySource("consumer.Consumer", CLASS_ANNOTATED_CONSUMER)),
+                Collections.emptyList());
+
+        boolean hasError = diagnostics.getDiagnostics().stream().anyMatch(d -> d.getKind() == Diagnostic.Kind.ERROR);
+        assertFalse(hasError, "Expected no errors with type-level opt-in, got: " + diagnostics.getDiagnostics());
+    }
+
+    @Test
+    void passes_whenAllowAnnotationIsOnMethod() {
+        DiagnosticCollector<JavaFileObject> diagnostics = compile(
+                List.of(inMemorySource("test.ExperimentalType", EXPERIMENTAL_TYPE_SOURCE),
+                        inMemorySource("consumer.Consumer", METHOD_ANNOTATED_CONSUMER)),
+                Collections.emptyList());
+
+        boolean hasError = diagnostics.getDiagnostics().stream().anyMatch(d -> d.getKind() == Diagnostic.Kind.ERROR);
+        assertFalse(hasError, "Expected no errors with method-level opt-in, got: " + diagnostics.getDiagnostics());
+    }
+
     @Test
     void passes_whenOptInFlagIsProvided() {
         DiagnosticCollector<JavaFileObject> diagnostics = compile(