What exactly ends up in a .api dump, and what Kotlin constructs are excluded or need special handling (e.g. internal, @PublishedApi, inline)?

## What the dump captures The `.api` is a textual list of **JVM-level signatures** for everything reachable through the public binary surface: - `public` and `protected` classes/interfaces/objects (with supertypes and modifiers). - Their `public`/`protected` members: functions (as JVM method descriptors), and properties (as their generated `getX`/`setX` accessors plus any backing field that is part of the surface). - Synthetic artifacts the compiler emits that are observable in the ABI, e.g. **bridge methods** from generics/covariance and `$default` overloads for default parameters. It is the *compiled* shape, not the source shape — which is why it catches things source-level review misses. ## What is excluded - `private` members. - `internal` members — they are **name-mangled** in bytecode (e.g. `parse$mylib`) and not considered part of the stable public ABI, so they are omitted by default. - Members of excluded packages/classes (see tuning below). ## Kotlin-specific subtleties ### `@PublishedApi internal` A `public inline` function whose body is inlined into consumer code may call an `internal` helper. For that to link, the helper must be visible in the bytecode, so it is marked `@PublishedApi internal`, which makes it effectively public *binary*. **BCV includes `@PublishedApi` members** in the dump — they are part of what consumers depend on. ```kotlin @PublishedApi internal fun engine(): Engine = Engine() public inline fun run(block: () -> Unit) { engine().start() // inlined into the caller -> engine() must be in the ABI block() } ``` ### `inline` functions `inline` function bodies are copied into call sites at compile time. Changing the body (not just the signature) can be **binary-breaking** for already-compiled callers, even though the listed signature is unchanged. The signature appears in the `.api`; reviewers must additionally reason about body changes — BCV cannot diff inlined bodies. ### `const val` / compile-time constants Values of `const val` are inlined into consumers, so changing a constant's value is binary-breaking even though the signature is identical. ## Tuning the surface The `apiValidation { }` DSL controls what is dumped: ```kotlin apiValidation { ignoredPackages.add("com.acme.internal") ignoredClasses.add("com.acme.GeneratedConfig") // treat anything annotated with these as non-public nonPublicMarkers.add("com.acme.InternalApi") validationDisabled = false } ``` `nonPublicMarkers` lets you carve out an explicitly-marked experimental/internal surface so it is excluded from the stability contract. ## Takeaway The dump mirrors the *binary* contract, including compiler-synthesized and `@PublishedApi` members — but inline/const *value/body* changes are binary-breaking in ways the signature line alone won't reveal.