skill(apm-integrations): database-category rule sharpening (SPI-first, eager connect metadata, muzzle)

[jordan-wong]

What

Sharpens the apm-integrations agent skill with lessons from the database eval cycle (reference PRs #11996 Cassandra / #11997 PostgreSQL / #12032 R2DBC). Draft — a living container that will be refined as feedback comes in from those PR reviews. Only the strongest, review-independent clarifications are in here now; library-specific rules await reviewer validation.

Key insight

Most database findings turned out to be adherence gaps against rules that already exist, not missing rules:

• SPI-first (ForTypeHierarchy for JDBC's java.sql.*) was already in instrumenter-module.md, but its wording only triggered on "interface-only spec jar" — so an agent given a concrete driver (org.postgresql:postgresql) didn't apply it.
• assertInverse guidance was already in muzzle.md but was violated.
• "read the existing super(...) verbatim / scan for an existing module" was already present but violated.

So this PR sharpens the existing rules with the concrete failure modes rather than adding redundant prose, plus adds one genuinely-new idiom.

Changes

references/instrumenter-module.md

• SPI exception now explicitly covers being handed a concrete implementation of a JDK SPI, not just an interface-only jar. Spells out the two harms of hooking the concrete class: (a) covers only one vendor, and (b) collides at runtime with the existing SPI module on the shared CallDepthThreadLocalMap.incrementCallDepth(<SpiType>.class) guard → mutual span suppression. (Root cause of [reference] eval: blind regeneration of PostgreSQL JDBC driver (toolkit output) #11997's spring-boot test_sql_traces failures.)
• New: database clients must populate connection metadata eagerly at connect/factory time, not lazily per query — JDBC DriverInstrumentation and R2DBC ConnectionFactoryOptions as the reference points; explains why R2DBC's ConnectionMetadata cannot supply host/port/db/user (root cause of [reference] R2DBC net-new instrumentation (io.r2dbc:r2dbc-spi 1.0.0, toolkit output) #12032's dominant finding).

references/muzzle.md

• assertInverse rule reinforced with the concrete-driver failure mode: a pinned dependency version is not an API-shape boundary (the PostgreSQL [42.0.0,) + assertInverse example that failed on six pre-42 releases).

Not included yet (deliberately)

• db-no-parallel-module enforcement — that's a toolkit-side reviewer_check, not canonical skill content; tracked separately.
• N-DBM-2 (feature-implement silent-narrowing) — toolkit-side prompt fix, not canonical.
• Anything a reviewer of [reference] eval: blind regeneration of datastax-cassandra-4.0 (toolkit output) #11996/[reference] eval: blind regeneration of PostgreSQL JDBC driver (toolkit output) #11997/[reference] R2DBC net-new instrumentation (io.r2dbc:r2dbc-spi 1.0.0, toolkit output) #12032 hasn't yet weighed in on — this PR grows as that feedback lands.

Research provenance: docs/eval-research/hypotheses/{cassandra,postgresql,r2dbc}.md on the toolkit repo (R-DB-1 through R-DB-4, N-DBM-2).

🤖 Generated with Claude Code

[dd-octo-sts]

🟡 Java Benchmark SLOs — Performance SLO warning (near threshold)

Suite	Status
Startup	🟡 warning

SLO thresholds are defined here based on automatically generated metrics. A warning is raised when results are within 5% of the threshold.

PR vs. master results

Scenario	Candidate	master	Δ (95% CI of mean)
startup:insecure-bank:iast:Agent	14.01 s	14.02 s	[-1.0%; +0.9%] (no difference)
startup:insecure-bank:tracing:Agent	12.92 s	12.94 s	[-0.9%; +0.5%] (no difference)
startup:petclinic:appsec:Agent	16.94 s	16.80 s	[-0.1%; +1.7%] (no difference)
startup:petclinic:iast:Agent	16.99 s	16.92 s	[-0.4%; +1.2%] (no difference)
startup:petclinic:profiling:Agent	16.96 s	16.93 s	[-1.2%; +1.5%] (no difference)
startup:petclinic:sca:Agent	16.82 s	16.82 s	[-1.1%; +1.1%] (no difference)
startup:petclinic:tracing:Agent	16.13 s	15.67 s	[-1.5%; +7.3%] (no difference)

Commit: 37e661c7 · CI Pipeline · Benchmarking Platform UI

---

Load and DaCapo benchmarks can be triggered manually in the GitLab pipeline. Results will appear in the Benchmarking Platform UI after completion.