API review feedback - no code changes required

[Copilot]

Performed comprehensive Java API stability review per request. No code changes made - this is a documentation/analysis-only response.

Review Summary

Analyzed public API surface in delayedqueue-jvm.api for:

• Binary compatibility risks
• Java interop best practices (per kotlin-java-library skill)
• Kotlin stdlib type leakage
• JVM annotation usage

Key Findings

Critical Issues:

• AckEnvelope.copy() exposes private acknowledge parameter in public signature, allowing Java callers to bypass encapsulation
• Nullable boxed primitives (Long?, Int?) in RetryConfig and JdbcDatabasePoolConfig are less Java-idiomatic than OptionalLong/OptionalInt

Best Practices:

• Default parameter ordering creates unintuitive Java constructors (consider explicit factory methods)
• Data class component*() methods pollute API surface (unavoidable with @JvmRecord)

Validated:

• ✅ No Kotlin stdlib types in public API
• ✅ Proper @Throws annotations on all public methods
• ✅ Java types (java.util.List, java.time.*) used throughout
• ✅ fun interface for SAM types
• ✅ No extension-only public APIs

Full review provided in PR comments.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.