# Add @CopilotExperimental compile-time gate for experimental APIs

## Summary

Introduces a compile-time enforcement mechanism that prevents accidental use of
experimental APIs in the Java SDK. Consumer code that references experimental
types or methods now fails to compile by default, with explicit opt-in via
`-Acopilot.experimental.allowed=true`.

## Motivation

Generated SDK APIs marked as `stability: "experimental"` in the schema were
previously only documented via `@apiNote` in Javadoc — invisible to the compiler
and easy to miss. This change makes the experimental contract enforceable at
build time, giving consumers a clear signal and an explicit opt-in path.

## What changed

### New files

| File | Purpose |
|------|---------|
| `java/src/main/java/com/github/copilot/CopilotExperimental.java` | Annotation: `@Documented`, `@Retention(CLASS)`, `@Target({TYPE, METHOD})` |
| `java/src/main/java/com/github/copilot/CopilotExperimentalProcessor.java` | Annotation processor using Trees API + `TreePathScanner` |
| `java/src/main/resources/META-INF/services/javax.annotation.processing.Processor` | Service registration for classpath-based discovery |
| `java/src/test/java/com/github/copilot/CopilotExperimentalProcessorTest.java` | 3 tests proving fail-by-default and allow-when-opted-in |

### Modified files

| File | Change |
|------|--------|
| `java/src/main/java/module-info.java` | Added `requires static jdk.compiler;` and `provides` directive |
| `java/pom.xml` | Compiler plugin: `<proc>none</proc>` + `-Acopilot.experimental.allowed=true`; surefire args for `jdk.compiler` exports |
| `java/scripts/codegen/java.ts` | Emits `@CopilotExperimental` + import at 3 codegen sites |
| `java/src/generated/java/**` | Regenerated — experimental types/methods now annotated |
| `java/README.md` | New "Using experimental APIs" section with examples |

## How it works

### Processor behavior

1. Runs with `@SupportedAnnotationTypes("*")` — processes all compilation units.
2. Checks option `copilot.experimental.allowed`:
   - If `"true"`: processor is a no-op (all experimental use permitted).
   - Otherwise: scans source trees for forbidden references.
3. Uses `com.sun.source.util.Trees` + `TreePathScanner` to visit:
   - `IdentifierTree` — direct type/variable references
   - `MemberSelectTree` — qualified access (`obj.method`)
   - `MemberReferenceTree` — method references (`Type::method`)
   - `NewClassTree` — constructor calls (`new ExperimentalType()`)
4. For each resolved element, checks if it or its enclosing type carries
   `@CopilotExperimental`. If so, emits `Diagnostic.Kind.ERROR`.

### Diagnostic message

```
error: Use of experimental API 'symbolName' is not allowed.
       Add compiler option -Acopilot.experimental.allowed=true to opt in.
```

### Bootstrap handling

The processor lives in the same module it protects. To avoid the bootstrap
problem (javac trying to load the processor before it's compiled):

- Main compile uses `<proc>none</proc>` — annotation processing is disabled
  during this module's own compilation.
- Consumer builds discover the processor via `META-INF/services` (classpath) or
  `provides` directive (module path).

### Codegen integration

The TypeScript codegen (`java/scripts/codegen/java.ts`) was updated at three
sites where `stability === "experimental"` is detected:

1. **Session event classes** — `@CopilotExperimental` on the class
2. **RPC params/result records** — `@CopilotExperimental` on the class
3. **API wrapper methods** — `@CopilotExperimental` on individual methods

Import (`com.github.copilot.CopilotExperimental`) is added to the generated
file's import set only when needed. Existing `@apiNote` Javadoc is preserved.

## Key review points for a Java SME

1. **Trees API usage** — The processor uses only `com.sun.source.*` (exported
   from `jdk.compiler`), not `com.sun.tools.javac.*` internals. This is the
   standard supported API for source-level annotation processors.

2. **Module wiring** — `requires static jdk.compiler` means the dependency is
   compile-time only; the module works at runtime without `jdk.compiler` on the
   module graph. The `provides` directive enables modular service discovery.

3. **Surefire JVM args** — Tests that instantiate the processor directly need
   `--add-modules jdk.compiler --add-exports jdk.compiler/com.sun.source.util=ALL-UNNAMED`
   because surefire runs on the classpath (unnamed module) while `Trees` is in
   `jdk.compiler`.

4. **proc=none trade-off** — The SDK module itself never runs its own processor.
   Enforcement is consumer-facing only. This is intentional: the SDK must
   compile its own generated experimental code without error.

5. **Retention=CLASS** — The annotation is not available via reflection at
   runtime (`RUNTIME` is unnecessary), but is preserved in `.class` files so the
   processor can read it from compiled dependencies on the classpath.

6. **Enclosing-type propagation** — When a type is annotated, all member
   accesses through that type are treated as experimental, even if the member
   itself is not annotated. This covers field access, method calls, and
   constructor invocations on experimental types.

## Test coverage

| Test | Asserts |
|------|---------|
| `failsByDefault_whenReferencingExperimentalType` | ERROR diagnostic with "experimental API" for type usage |
| `failsByDefault_whenInvokingExperimentalMethod` | ERROR diagnostic for method-level annotation |
| `passes_whenOptInFlagIsProvided` | Zero errors when `-Acopilot.experimental.allowed=true` is set |

Tests use `javax.tools.JavaCompiler` with in-memory sources and explicit
`setProcessors()` to avoid environment sensitivity.

## How to verify

```bash
cd java
mvn generate-sources -Pcodegen   # regenerate with annotations
mvn test -Dtest=CopilotExperimentalProcessorTest  # run gate tests
```

Author: edburns

java/README.md

@@ -130,6 +130,78 @@ Or run it directly from the repository:
 jbang https://github.com/github/copilot-sdk/blob/main/java/jbang-example.java
 ```
 
+## Using experimental APIs
+
+Some SDK APIs are marked as experimental with `@CopilotExperimental`. These APIs may change or be removed in future versions without notice.
+
+By default, referencing an experimental API from your code causes a **compile-time error**:
+
+```
+error: Use of experimental API 'ExperimentalType' is not allowed.
+       Add 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.
+
+### Maven
+
+```xml
+<plugin>
+    <groupId>org.apache.maven.plugins</groupId>
+    <artifactId>maven-compiler-plugin</artifactId>
+    <configuration>
+        <compilerArgs>
+            <arg>-Acopilot.experimental.allowed=true</arg>
+        </compilerArgs>
+    </configuration>
+</plugin>
+```
+
+### Gradle
+
+```groovy
+tasks.withType(JavaCompile) {
+    options.compilerArgs += ['-Acopilot.experimental.allowed=true']
+}
+```
+
+### Example
+
+```java
+import com.github.copilot.CopilotExperimental;
+
+// This type is experimental — consumer code that references it
+// will fail to compile unless the opt-in flag is provided.
+@CopilotExperimental
+public class ExperimentalType {
+    public void doSomething() {}
+}
+
+// Consumer code — compiles only with -Acopilot.experimental.allowed=true
+import test.ExperimentalType;
+
+public class Consumer {
+    public void use() {
+        ExperimentalType t = new ExperimentalType();
+        t.doSomething();
+    }
+}
+```
+
+The gate also applies to individual methods annotated with `@CopilotExperimental` on otherwise stable types:
+
+```java
+import com.github.copilot.CopilotExperimental;
+
+public class StableType {
+    @CopilotExperimental
+    public static void experimentalMethod() {}
+}
+
+// Calling experimentalMethod() fails compilation without the opt-in flag
+StableType.experimentalMethod();
+```
+
 ## Projects Using This SDK
 
 | Project                                                                       | Description                                |

java/pom.xml

@@ -164,6 +164,12 @@
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-compiler-plugin</artifactId>
                 <version>3.15.0</version>
+                <configuration>
+                    <compilerArgs>
+                        <arg>-Acopilot.experimental.allowed=true</arg>
+                    </compilerArgs>
+                    <proc>none</proc>
+                </configuration>
             </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
@@ -508,7 +514,7 @@
                 <jdk>[21,)</jdk>
             </activation>
             <properties>
-                <surefire.jvm.args>-XX:+EnableDynamicAgentLoading</surefire.jvm.args>
+                <surefire.jvm.args>-XX:+EnableDynamicAgentLoading --add-modules jdk.compiler --add-exports jdk.compiler/com.sun.source.util=ALL-UNNAMED --add-exports jdk.compiler/com.sun.source.tree=ALL-UNNAMED</surefire.jvm.args>
             </properties>
         </profile>
         <profile>

java/scripts/codegen/java.ts

@@ -1002,6 +1002,10 @@ async function generateEventVariantClass(
     if (variant.deprecated) {
         lines.push(`@Deprecated`);
     }
+    if (variant.stability === "experimental") {
+        allImports.add("com.github.copilot.CopilotExperimental");
+        lines.push(`@CopilotExperimental`);
+    }
     lines.push(`@JsonIgnoreProperties(ignoreUnknown = true)`);
     lines.push(`@JsonInclude(JsonInclude.Include.NON_NULL)`);
     lines.push(GENERATED_ANNOTATION);
@@ -1404,6 +1408,9 @@ async function generateRpcDataClass(
         "javax.annotation.processing.Generated",
         ...imports,
     ]);
+    if (stability === "experimental") {
+        allImports.add("com.github.copilot.CopilotExperimental");
+    }
     const sortedImports = [...allImports].sort();
     for (const imp of sortedImports) {
         lines.push(`import ${imp};`);
@@ -1426,6 +1433,9 @@ async function generateRpcDataClass(
     if (deprecated) {
         lines.push(`@Deprecated`);
     }
+    if (stability === "experimental") {
+        lines.push(`@CopilotExperimental`);
+    }
     lines.push(GENERATED_ANNOTATION);
     lines.push(code);
     lines.push("");
@@ -1577,7 +1587,7 @@ function generateApiMethod(
     method: RpcMethodNode,
     isSession: boolean,
     sessionIdExpr: string
-): { lines: string[]; needsMapper: boolean } {
+): { lines: string[]; needsMapper: boolean; needsExperimentalImport: boolean } {
     const resultClass = wrapperResultClassName(method);
     const paramsClass = wrapperParamsClassName(method);
     const hasSessionId = methodHasSessionId(method);
@@ -1606,6 +1616,9 @@ function generateApiMethod(
     if (method.deprecated) {
         lines.push(`    @Deprecated`);
     }
+    if (method.stability === "experimental") {
+        lines.push(`    @CopilotExperimental`);
+    }
 
     // Signature
     if (hasExtraParams) {
@@ -1639,7 +1652,7 @@ function generateApiMethod(
     lines.push(`    }`);
     lines.push(``);
 
-    return { lines, needsMapper };
+    return { lines, needsMapper, needsExperimentalImport: method.stability === "experimental" };
 }
 
 /**
@@ -1694,9 +1707,10 @@ async function generateNamespaceApiFile(
         }
         if (paramsClass) allImports.add(`${packageName}.${paramsClass}`);
 
-        const { lines, needsMapper: nm } = generateApiMethod(key, method, isSession, sessionIdExpr);
+        const { lines, needsMapper: nm, needsExperimentalImport } = generateApiMethod(key, method, isSession, sessionIdExpr);
         methodLines.push(...lines);
         if (nm) needsMapper = true;
+        if (needsExperimentalImport) allImports.add("com.github.copilot.CopilotExperimental");
     }
 
     // Build class body
@@ -1819,9 +1833,10 @@ async function generateRpcRootFile(
         }
         if (paramsClass) allImports.add(`${packageName}.${paramsClass}`);
 
-        const { lines, needsMapper: nm } = generateApiMethod(key, method, isSession, sessionIdExpr);
+        const { lines, needsMapper: nm, needsExperimentalImport } = generateApiMethod(key, method, isSession, sessionIdExpr);
         methodLines.push(...lines);
         if (nm) needsMapper = true;
+        if (needsExperimentalImport) allImports.add("com.github.copilot.CopilotExperimental");
     }
 
     // Build file content

java/src/generated/java/com/github/copilot/generated/rpc/AgentRegistrySpawnParams.java

@@ -10,6 +10,7 @@
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonProperty;
+import com.github.copilot.CopilotExperimental;
 import javax.annotation.processing.Generated;
 
 /**
@@ -18,6 +19,7 @@
  * @apiNote This method is experimental and may change in a future version.
  * @since 1.0.0
  */
+@CopilotExperimental
 @javax.annotation.processing.Generated("copilot-sdk-codegen")
 @JsonInclude(JsonInclude.Include.NON_NULL)
 @JsonIgnoreProperties(ignoreUnknown = true)

java/src/generated/java/com/github/copilot/generated/rpc/CanvasActionInvokeParams.java

@@ -10,6 +10,7 @@
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonProperty;
+import com.github.copilot.CopilotExperimental;
 import javax.annotation.processing.Generated;
 
 /**
@@ -18,6 +19,7 @@
  * @apiNote This method is experimental and may change in a future version.
  * @since 1.0.0
  */
+@CopilotExperimental
 @javax.annotation.processing.Generated("copilot-sdk-codegen")
 @JsonInclude(JsonInclude.Include.NON_NULL)
 @JsonIgnoreProperties(ignoreUnknown = true)

java/src/generated/java/com/github/copilot/generated/rpc/CanvasCloseParams.java

@@ -10,6 +10,7 @@
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonProperty;
+import com.github.copilot.CopilotExperimental;
 import javax.annotation.processing.Generated;
 
 /**
@@ -18,6 +19,7 @@
  * @apiNote This method is experimental and may change in a future version.
  * @since 1.0.0
  */
+@CopilotExperimental
 @javax.annotation.processing.Generated("copilot-sdk-codegen")
 @JsonInclude(JsonInclude.Include.NON_NULL)
 @JsonIgnoreProperties(ignoreUnknown = true)

java/src/generated/java/com/github/copilot/generated/rpc/CanvasOpenParams.java

@@ -10,6 +10,7 @@
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonProperty;
+import com.github.copilot.CopilotExperimental;
 import javax.annotation.processing.Generated;
 
 /**
@@ -18,6 +19,7 @@
  * @apiNote This method is experimental and may change in a future version.
  * @since 1.0.0
  */
+@CopilotExperimental
 @javax.annotation.processing.Generated("copilot-sdk-codegen")
 @JsonInclude(JsonInclude.Include.NON_NULL)
 @JsonIgnoreProperties(ignoreUnknown = true)

java/src/generated/java/com/github/copilot/generated/rpc/CanvasOpenResult.java

@@ -10,6 +10,7 @@
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonProperty;
+import com.github.copilot.CopilotExperimental;
 import javax.annotation.processing.Generated;
 
 /**
@@ -18,6 +19,7 @@
  * @apiNote This method is experimental and may change in a future version.
  * @since 1.0.0
  */
+@CopilotExperimental
 @javax.annotation.processing.Generated("copilot-sdk-codegen")
 @JsonInclude(JsonInclude.Include.NON_NULL)
 @JsonIgnoreProperties(ignoreUnknown = true)

java/src/generated/java/com/github/copilot/generated/rpc/ServerAgentRegistryApi.java

@@ -7,6 +7,7 @@
 
 package com.github.copilot.generated.rpc;
 
+import com.github.copilot.CopilotExperimental;
 import java.util.concurrent.CompletableFuture;
 import javax.annotation.processing.Generated;
 
@@ -31,6 +32,7 @@ public final class ServerAgentRegistryApi {
      * @apiNote This method is experimental and may change in a future version.
      * @since 1.0.0
      */
+    @CopilotExperimental
     public CompletableFuture<AgentRegistrySpawnResult> spawn(AgentRegistrySpawnParams params) {
         return caller.invoke("agentRegistry.spawn", params, AgentRegistrySpawnResult.class);
     }