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

[jordan-wong]

Update — 2026-08-05 autonomous category gap sweep (commit bb7c329778)

An oracle-anchored database category sweep (static diff-vs-master + generation-transcript root-cause across Cassandra/PostgreSQL/R2DBC) re-derived every prior finding and confirmed dedup against this PR's existing commit. Net-new result landing here:

• R-DB-1 is category-wide, not a Cassandra quirk (proven by evidence: surviving datastax-cassandra-3.0/-3.8 already declare super("cassandra"), so any new top-level cassandra module collides regardless of the deleted 4.0). The existing "modify in place, don't create a parallel module" rule did not cover the case actually hit: the eval slug (cassandra) differs from the family directory (datastax-cassandra/), AND under the blind protocol the same-version module was deleted so "modify in place" had no target — yet the name was still taken by siblings. Added a module-placement rule to instrumenter-module.md: grep for the intended super() name before creating a module; a taken name dictates the directory (join the family), never a new top-level slug. Failure mode it prevents: duplicate @AutoService registration → silent tracing outage (zero spans, no build error).

Everything else the sweep surfaced was already covered here (SPI-miss R-DB-2, eager-connect R-DB-3, muzzle R-DB-4) or routed off-PR (N-DBM-2 silent-downscope → toolkit prompt; db-no-parallel-module grep → toolkit reviewer_check), consistent with the "Not included yet" section below.

---

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.82 s	14.68 s	[+0.0%; +1.9%] (maybe worse)
startup:insecure-bank:tracing:Agent	13.57 s	13.68 s	[-1.7%; -0.0%] (maybe better)
startup:petclinic:appsec:Agent	17.35 s	16.55 s	[+0.4%; +9.3%] (maybe worse)
startup:petclinic:iast:Agent	17.40 s	17.52 s	[-1.7%; +0.4%] (no difference)
startup:petclinic:profiling:Agent	17.40 s	17.40 s	[-1.3%; +1.3%] (no difference)
startup:petclinic:sca:Agent	17.35 s	17.36 s	[-1.1%; +1.0%] (no difference)
startup:petclinic:tracing:Agent	16.64 s	16.22 s	[-1.7%; +6.8%] (no difference)

Commit: bb7c3297 · 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.