Merge branch 'main' into mutators

Author: trask

.github/agents/knowledge/general-rules.md

@@ -27,6 +27,7 @@ When a "Knowledge File" is listed, load it from `knowledge/` before reviewing th
 | Semconv | Dual semconv testing | `SemconvStability`, `maybeStable`, semconv Gradle tasks | `testing-semconv-stability.md` |
 | Testing | General test patterns | Test files in scope — assertion style, test method signatures and throws clauses, resource cleanup, attribute assertions | `testing-general-patterns.md` |
 | Testing | Experimental flag tests | `testExperimental`, experimental attribute assertions, `experimental` flags in JVM args or system properties | `testing-experimental-flags.md` |
+| Testing | Flag-gated / mode-dependent assertion shape (experimental, `testLatestDeps`, semconv) — shared accessor (`testLatestDeps()`, `emitStable*Semconv()`) or `EXPERIMENTAL_ATTRIBUTES` constant, inline ternary with `null` for "absent" | Test classes branching on `EXPERIMENTAL_ATTRIBUTES`, `testLatestDeps()`, or `emitOld*`/`emitStable*` | `testing-general-patterns.md` |
 | Library | TelemetryBuilder/getter/setter patterns | Library instrumentation classes | `library-patterns.md` |
 | API | Deprecation and breaking-change policy | Public API changes | `api-deprecation-policy.md` |
 | Config | Config property stability/renames/removals | `otel.instrumentation.*` property changes, `DeclarativeConfigUtil` or `ConfigProperties` usage | `config-property-stability.md` |
@@ -103,9 +104,8 @@ Reason about visibility from "what does the advice method directly reference?".
 
 ## [Style] `@SuppressWarnings` Usage
 
-- Method-level `@SuppressWarnings` is preferred over class-level for tighter scope, but
-  if more than one method in the class needs the same suppression, class-level is fine.
-  Do not flag class-level `@SuppressWarnings` when multiple methods use the suppressed API.
+- Place `@SuppressWarnings` on the single member that needs it, or on the class when two
+  or more members in the class need the same suppression.
 - **Do not add `@SuppressWarnings("deprecation")` unless the build fails without it.**
   The project disables javac's `-Xlint:deprecation` globally and uses a custom Error Prone
   check (`OtelDeprecatedApiUsage`) instead. Only add the annotation when it is actually
@@ -375,14 +375,17 @@ ambiguous and the cast would otherwise be required). Do not flag those cases.
 
 ## [Semconv] Constants by Module Type
 
-- `library/src/main/`: incubating semconv constants (from
-  `io.opentelemetry.semconv.incubating`) must be copied locally as `private static final`
-  fields with a `// copied from <ClassName>` comment. Stable semconv constants (from
-  `io.opentelemetry.semconv`) may be imported directly.
+- `library/src/main/`: constants from `io.opentelemetry.semconv.incubating.*` must be
+  copied locally as `private static final` fields with a `// copied from <ClassName>`
+  comment. Constants from `io.opentelemetry.semconv.*` (stable) must be imported
+  directly via `import static` and must not be copied locally.
 - `javaagent/src/main/`: all semconv artifact constants (stable and incubating) may be used
   directly.
 - tests: all semconv artifact constants are allowed.
 
+The trigger for copying is the import package, not the constant name. Only convert an
+import to a local copy when it comes from `io.opentelemetry.semconv.incubating.*`.
+
 ## [NewModule] New Instrumentation Checklist
 
 If a new module is added, verify all of the following:

.github/agents/knowledge/gradle-conventions.md

@@ -157,6 +157,13 @@ Flag `build.gradle.kts` dependencies that appear unused or redundant:
 - A dependency that duplicates something already provided transitively.
 - A `testImplementation` dependency for a library not used in tests.
 
+### Never declare `javaagent-bootstrap` explicitly in javaagent modules
+
+The `otel.javaagent-instrumentation` convention plugin already provides
+`javaagent-bootstrap` on the `compileOnly` classpath transitively. Do not add
+`compileOnly(project(":javaagent-bootstrap"))` to a javaagent module's
+`build.gradle.kts`, and remove it if present.
+
 ## Custom Test Tasks
 
 Every custom `Test` task registered with `val foo by registering(Test::class)` **must** include
@@ -215,15 +222,16 @@ block, not repeated on each individual task.
 If a property or JVM arg is moved into `withType<Test>().configureEach`, remove any now-redundant
 copies from individual tasks unless a task intentionally overrides the shared value.
 
-When the module's `build.gradle.kts` does not explicitly register additional `Test` tasks,
-`tasks.test { ... }` is fine — **do not** convert it to `withType<Test>().configureEach` and
-do not flag it.
+**When the module has only a single test task, prefer the simple `tasks.test { ... }` form.**
+Do **not** convert `tasks.test { ... }` to `withType<Test>().configureEach` in single-test-task
+modules, and do **not** flag the simple form as a problem. The `withType<Test>().configureEach`
+form is only justified when the same `build.gradle.kts` actually registers additional `Test` tasks.
 
 **`latestDepTest` does not count as a second test task for this rule.** It is registered
 implicitly by the convention plugin when `testLatestDeps` is set, and it inherits the
 configuration of `tasks.test`. A module with only a `tasks.test { ... }` block and no
 `by registering(Test::class)` declarations is a single-test-task module — leave it alone
-even if `testLatestDeps = true`.
+(use the simple form) even if `testLatestDeps = true`.
 
 Only consider converting to `withType<Test>().configureEach` when the **same
 `build.gradle.kts`** explicitly registers one or more additional `Test` tasks via
@@ -261,9 +269,11 @@ review**. Only verify correctness when they are already present.
 
 When already present, verify:
 
-- `collectMetadata` is in `withType<Test>().configureEach` (or `tasks.test` if the module
-  does not explicitly register additional `Test` tasks — `latestDepTest` does not count) —
-  never on individual tasks.
+- `collectMetadata` is in `tasks.test` for single-test-task modules, or in
+  `withType<Test>().configureEach` for modules that explicitly register additional `Test`
+  tasks via `by registering(Test::class)` (`latestDepTest` does not count) — never on
+  individual tasks. Do not use
+  `withType<Test>().configureEach { ... }` in single-test-task modules.
 - `metadataConfig` is on each non-default task. It may also appear on the default `test`
   task when that task itself runs with non-default `jvmArgs` (e.g., an experimental flag
   enabled module-wide via `withType<Test>().configureEach { jvmArgs(...) }`); in that case

.github/agents/knowledge/testing-experimental-flags.md

@@ -28,9 +28,9 @@ block but there is no dedicated `testExperimental` task, fix it:
 
 1. Create a `testExperimental` task (see Gradle Task Setup below).
 2. Move the experimental flag out of the shared/default task config into `testExperimental`.
-3. Add a `private static final boolean EXPERIMENTAL_ATTRIBUTES` field to test classes.
-4. Wrap experimental attribute assertions with the `experimental()` helper.
-5. Wire the new task into `check`.
+3. Add a `private static final boolean EXPERIMENTAL_ATTRIBUTES` field to test classes and
+   gate experimental attribute assertions on it (see Java Test Patterns below).
+4. Wire the new task into `check`.
 
 ## Gradle Task Setup
 
@@ -51,30 +51,38 @@ val testExperimental by registering(Test::class) {
 
 ## Java Test Patterns
 
-Read the flag once into a `private static final boolean` at class level:
+For the cross-cutting shape — inline ternary with `null` for "absent", when to use top-level
+`if` blocks, and `assumeTrue(...)` guidance — see
+[testing-general-patterns.md](testing-general-patterns.md#flag-gated--mode-dependent-assertions).
+The experimental-specific patterns below build on that shape.
+
+### Hoist the flag into a per-class `EXPERIMENTAL_ATTRIBUTES` constant
+
+The property name is module-specific, so there is no shared accessor. Read it once into a
+`private static final boolean` near the top of the class and reference the constant
+everywhere in the file:
 
 ```java
 private static final boolean EXPERIMENTAL_ATTRIBUTES =
     Boolean.getBoolean("otel.instrumentation.<module>.experimental-span-attributes");
 ```
 
-Use inline ternary in assertions — `null` means attribute expected absent:
+When multiple experimental flags coexist in one class, use a more specific name per flag.
 
-```java
-equalTo(ExperimentalAttributes.SOME_ATTR, EXPERIMENTAL_ATTRIBUTES ? "value" : null)
-```
+### Single-arg `experimental(value)` helper
 
-When many assertions share the flag, extract an `experimental()` helper:
+Experimental attributes are by definition absent when the flag is off, so the off-branch is
+always `null`. When several assertions in the same class gate attributes on
+`EXPERIMENTAL_ATTRIBUTES`, extract a tiny helper:
 
 ```java
 @Nullable
 private static <T> T experimental(T value) {
   return EXPERIMENTAL_ATTRIBUTES ? value : null;
 }
+
+equalTo(SOME_KEY, experimental("value"))
 ```
 
 For multiple test classes sharing the same flag, move the helper into a shared
 `ExperimentalTestHelper` class and static-import it.
-
-Use `assumeTrue(EXPERIMENTAL_ATTRIBUTES)` only when an entire test is meaningful in
-experimental mode only — prefer the ternary/helper pattern so both modes are exercised.

.github/agents/knowledge/testing-general-patterns.md

@@ -48,10 +48,10 @@
 - In JUnit tests, when an `AutoCloseable` is intended to remain live for most or all of the test
   and only needs cleanup at test end, prefer `AutoCleanupExtension` with `deferCleanup(...)`
   over wrapping most of the test body in try-with-resources.
-- For resources created in `@BeforeAll` or other class-scoped setup, prefer
-  `AutoCleanupExtension` with `deferAfterAll(...)` over nested `@AfterAll` cleanup
-  chains. Do not introduce or keep `AutoCleanupExtension` solely for a single
-  `deferAfterAll(...)` call — use a plain `@AfterAll` instead.
+- Use `AutoCleanupExtension.deferAfterAll(...)` only for cleanup actions registered
+  dynamically (from inside test methods or other runtime-conditional setup). For a
+  fixed set of class-scoped fields known at class-init time, use a plain `@AfterAll`
+  that closes each field directly.
 - Reuse an existing `cleanup` extension when one is already in scope.
   Otherwise, add a `@RegisterExtension` field when the deferred-cleanup pattern improves
   clarity or avoids wrapping most of the test body.
@@ -135,3 +135,41 @@ unless the span ordering within a trace is genuinely non-deterministic (e.g., co
 producers/consumers, thread-pool fan-out, or channel interleaving). Sequential operations
 like `repeat {}` loops, single-child traces, and `flux` sequential emission produce spans
 in deterministic order — use `hasSpansSatisfyingExactly` for those.
+
+## Flag-Gated / Mode-Dependent Assertions
+
+Several test modes change which attributes, span names, status codes, or span indexes are
+expected:
+
+- Experimental attributes (`-Dotel.instrumentation.<module>.experimental-*=true`) — see
+  [testing-experimental-flags.md](testing-experimental-flags.md).
+- Semconv stability (`-Dotel.semconv-stability.opt-in=...`) — see
+  [testing-semconv-stability.md](testing-semconv-stability.md).
+- `testLatestDeps` Gradle property — runs against the newest supported library versions
+  instead of the pinned earliest-supported ones.
+
+### Read the flag through a shared static helper, not a per-class field
+
+Each flag has a shared static accessor; static-import it and call it directly. Never call
+`Boolean.getBoolean("…")` inline and never duplicate the property-name string at the call
+site.
+
+| Flag | Shared accessor | Where it lives |
+| --- | --- | --- |
+| `-PtestLatestDeps=true` | `testLatestDeps()` | `io.opentelemetry.instrumentation.testing.util.TestLatestDeps` (testing-common) |
+| `otel.semconv-stability.opt-in=…` | `emitStableDatabaseSemconv()`, `emitOldDatabaseSemconv()`, `emitStableCodeSemconv()`, etc. | `io.opentelemetry.instrumentation.api.internal.SemconvStability` |
+| `otel.instrumentation.<module>.experimental-*` | per-module `EXPERIMENTAL_ATTRIBUTES` constant — see [testing-experimental-flags.md](testing-experimental-flags.md) | within the test class |
+
+### Inline ternary in `equalTo(...)` with `null` for "absent"
+
+Push the ternary as deep as possible — into the `equalTo` value or single attribute key —
+rather than duplicating two whole `hasAttributesSatisfyingExactly(...)` blocks under a
+`flag ? a : b`. The assertion API treats `null` as "expect attribute absent":
+
+```java
+equalTo(DB_USER, emitStableDatabaseSemconv() ? null : USER_DB)
+equalTo(ERROR_TYPE, emitStableDatabaseSemconv() ? "42601" : null)
+equalTo(SOME_KEY, EXPERIMENTAL_ATTRIBUTES ? "value" : null)
+span.hasName(testLatestDeps() ? "GET" : "HTTP GET")
+.hasParent(trace.getSpan(testLatestDeps() ? 0 : 1))
+```

.github/agents/knowledge/testing-semconv-stability.md

@@ -76,24 +76,30 @@ for other domains `check { dependsOn(testStableSemconv) }`.
 
 ## Asserting Attributes in Tests
 
-Preferred approach (most compact) — inline ternary with `emitStable*()`, where `null` means
-the attribute is expected absent:
+For the cross-cutting shape — inline ternary with `null` for "absent", static-imported flag
+accessors, and `assumeTrue(...)` guidance — see
+[testing-general-patterns.md](testing-general-patterns.md#flag-gated--mode-dependent-assertions).
+The semconv-specific patterns below build on that shape.
 
-```java
-equalTo(DB_USER, emitStableDatabaseSemconv() ? null : USER_DB)
-equalTo(ERROR_TYPE, emitStableDatabaseSemconv() ? "42601" : null)
-span.hasName(emitStableDatabaseSemconv() ? "SELECT" : "SELECT dbname")
-```
+### `maybeStable(OLD_KEY)` for 1:1 key renames
 
-Use `maybeStable(oldKey)` when only the attribute key changes and the value stays the same.
-`maybeStable()` does NOT cover `dup` mode — use separate `if` blocks for that.
+Use `maybeStable(OLD_KEY)` when only the attribute *key* flips between old and stable
+semconv and the value is identical:
 
 ```java
 span.hasAttribute(equalTo(maybeStable(DB_STATEMENT), "SELECT ?"));
 ```
 
-Use separate `if` blocks (not `if/else`) when assertion structure differs significantly between
-modes — this ensures both branches execute in `dup` mode:
+`maybeStable()` does **not** cover `/dup` mode (it returns one key, not both), and does
+**not** apply where the mapping isn't 1:1 — for example `DB_RESPONSE_STATUS_CODE` →
+`ERROR_TYPE`. Use `emitOld*()` / `emitStable*()` `if` blocks for those.
+
+### `if` blocks (not `if/else`) when structure differs
+
+When the *set* of asserted attributes differs between modes — not just values — use
+separate top-level `if` blocks rather than `if/else`. For domains that support `/dup` mode
+(currently RPC), this is required so both branches run; for other domains it's a habit
+that keeps the assertion `/dup`-safe if the domain ever adopts it:
 
 ```java
 if (emitStableCodeSemconv()) {
@@ -104,11 +110,6 @@ if (emitOldCodeSemconv()) {
 }
 ```
 
-Use `assumeTrue(emitStable*())` only when an entire test is meaningful in one mode only.
-
 ## Key Rules
 
 - Add `@SuppressWarnings("deprecation")` at class level when tests use old Semconv constants.
-- Use `if` (not `if/else`) for dual-mode assertions so both branches run in `/dup` mode.
-- Do NOT use `maybeStable()` for `DB_RESPONSE_STATUS_CODE` → `ERROR_TYPE` — these don't have
-  a 1:1 mapping. Use `emitOld*()`/`emitStable*()` `if` blocks instead.

.github/config/latest-dep-versions.json

@@ -60,7 +60,7 @@
     "com.ning:async-http-client#1.8.+": "1.8.17",
     "com.ning:async-http-client#1.9.+": "1.9.40",
     "com.noelios.restlet:com.noelios.restlet#+": "1.1.10",
-    "com.openai:openai-java#+": "4.32.0",
+    "com.openai:openai-java#+": "4.33.0",
     "com.oracle.database.jdbc:ojdbc8#+": "23.26.1.0.0",
     "com.oracle.database.jdbc:ucp#+": "23.26.1.0.0",
     "com.rabbitmq:amqp-client#+": "5.30.0",
@@ -110,7 +110,7 @@
     "com.typesafe.play:play_2.11#+": "2.7.9",
     "com.typesafe.play:play_2.12#+": "2.8.22",
     "com.typesafe.play:play_2.13#+": "2.9.10",
-    "com.vaadin:flow-server#+": "25.1.3",
+    "com.vaadin:flow-server#+": "25.1.4",
     "com.vaadin:vaadin-spring-boot-starter#14.11.+": "14.11.14",
     "com.xuxueli:xxl-job-core#+": "3.4.0",
     "com.xuxueli:xxl-job-core#2.2.+": "2.2.0",
@@ -308,16 +308,16 @@
     "org.apache.pekko:pekko-http_3#+": "1.3.0",
     "org.apache.pekko:pekko-stream_2.12#+": "1.4.0",
     "org.apache.pekko:pekko-stream_2.13#+": "1.5.0",
-    "org.apache.pulsar:pulsar-client#+": "4.2.0",
-    "org.apache.pulsar:pulsar-client-admin#+": "4.2.0",
+    "org.apache.pulsar:pulsar-client#+": "4.2.1",
+    "org.apache.pulsar:pulsar-client-admin#+": "4.2.1",
     "org.apache.rocketmq:rocketmq-client#+": "5.5.0",
     "org.apache.rocketmq:rocketmq-client-java#+": "5.2.0",
     "org.apache.rocketmq:rocketmq-test#+": "5.5.0",
     "org.apache.shardingsphere.elasticjob:elasticjob-lite-core#+": "3.0.4",
     "org.apache.shenyu:shenyu-spring-boot-starter-gateway#+": "2.7.0.3",
     "org.apache.shenyu:shenyu-web#+": "2.7.0.3",
     "org.apache.struts:struts2-core#+": "7.1.1",
-    "org.apache.struts:struts2-core#6.+": "6.8.0",
+    "org.apache.struts:struts2-core#6.+": "6.9.0",
     "org.apache.tapestry:tapestry-core#+": "5.9.1",
     "org.apache.tomcat.embed:tomcat-embed-core#+": "11.0.21",
     "org.apache.tomcat.embed:tomcat-embed-core#9.+": "9.0.117",
@@ -523,24 +523,24 @@
     "org.springframework:spring-webmvc#+": "7.0.7",
     "org.testcontainers:testcontainers-kafka#+": "2.0.5",
     "org.vibur:vibur-dbcp#+": "26.0",
-    "redis.clients:jedis#+": "7.4.1",
+    "redis.clients:jedis#+": "7.5.0",
     "redis.clients:jedis#2.+": "2.10.2",
     "redis.clients:jedis#3.+": "3.10.0",
     "software.amazon.awssdk.crt:aws-crt#+": "0.45.1",
-    "software.amazon.awssdk:aws-core#+": "2.42.41",
-    "software.amazon.awssdk:aws-json-protocol#+": "2.42.41",
-    "software.amazon.awssdk:bedrockruntime#+": "2.42.41",
-    "software.amazon.awssdk:dynamodb#+": "2.42.41",
-    "software.amazon.awssdk:ec2#+": "2.42.41",
-    "software.amazon.awssdk:kinesis#+": "2.42.41",
-    "software.amazon.awssdk:lambda#+": "2.42.41",
-    "software.amazon.awssdk:rds#+": "2.42.41",
-    "software.amazon.awssdk:s3#+": "2.42.41",
-    "software.amazon.awssdk:secretsmanager#+": "2.42.41",
-    "software.amazon.awssdk:ses#+": "2.42.41",
-    "software.amazon.awssdk:sfn#+": "2.42.41",
-    "software.amazon.awssdk:sns#+": "2.42.41",
-    "software.amazon.awssdk:sqs#+": "2.42.41",
+    "software.amazon.awssdk:aws-core#+": "2.43.0",
+    "software.amazon.awssdk:aws-json-protocol#+": "2.43.0",
+    "software.amazon.awssdk:bedrockruntime#+": "2.43.0",
+    "software.amazon.awssdk:dynamodb#+": "2.43.0",
+    "software.amazon.awssdk:ec2#+": "2.43.0",
+    "software.amazon.awssdk:kinesis#+": "2.43.0",
+    "software.amazon.awssdk:lambda#+": "2.43.0",
+    "software.amazon.awssdk:rds#+": "2.43.0",
+    "software.amazon.awssdk:s3#+": "2.43.0",
+    "software.amazon.awssdk:secretsmanager#+": "2.43.0",
+    "software.amazon.awssdk:ses#+": "2.43.0",
+    "software.amazon.awssdk:sfn#+": "2.43.0",
+    "software.amazon.awssdk:sns#+": "2.43.0",
+    "software.amazon.awssdk:sqs#+": "2.43.0",
     "tech.powerjob:powerjob-official-processors#+": "5.1.2",
     "tech.powerjob:powerjob-worker#+": "5.1.2"
 }

.github/repository-settings.md

@@ -24,10 +24,6 @@ Secrets:
 
 ## Secrets and variables > Actions
 
-### Repository secrets
-
-- `FLAKY_TEST_REPORTER_ACCESS_KEY` - owned by [@laurit](https://github.com/laurit)
-
 ### Organization secrets
 
 - `DEVELOCITY_ACCESS_KEY` (scoped only to Java repos)