Apple klib ABI is never validated because enableKlibsCrossCompilation=false, an undocumented flag from the initial import

[monkopedia-coder]

gradle.properties:4 sets:

kotlin.native.enableKlibsCrossCompilation=false

There is no comment on the line, and no rationale anywhere in the history — it arrived in the initial import (eaeaae8, 2026-03-24) alongside the rest of the file, so it has never been revisited.

It is load-bearing for a gap. With cross-compilation disabled, a Linux host cannot build the Apple klibs, so klibApiCheck validates the targets it can build (linuxX64, linuxArm64, mingwX64, js, wasmJs) and infers the five Apple targets from the committed dump instead of rebuilding them. Every apiCheck this project has ever run in CI has been Linux-only, so no Apple ABI change has been verified against its dump by anything except a publish.

The comment at the top of .github/workflows/ci-apple.yml states the constraint as inherent:

Kotlin/Native does not cross-compile iOS/macOS off a Mac
(kotlin.native.enableKlibsCrossCompilation=false)

Those are two different claims joined as one. Compiling and linking Apple binaries off a Mac is genuinely not possible. Cross-compiling Apple klibs is what the flag governs — that is the feature the flag's name refers to, and this repo has it switched off. If the flag can be flipped, apiCheck on Linux would cover all ten klib targets and the Apple ABI would stop depending on someone remembering the ci-apple label.

Unresolved, and deliberately not settled here: whether flipping it actually works in this project. It needs ./gradlew apiCheck on a Linux host with kotlin.native.enableKlibsCrossCompilation=true — a real build, out of scope for a read-only pass. It may well have been set to false for a concrete reason (a cinterop or libcurl dependency that does not cross-compile is the obvious candidate, since ksrpc-ktor-client uses ktor-client-curl on native). If that is the reason, the finding becomes documentation: the flag needs a comment saying so, and ci-apple.yml's comment needs to stop presenting a project setting as a platform limitation.

Either way this does not change what ci-apple is for — it compiles Apple sources, which klib cross-compilation would not replace.

[monkopedia-coder]

Re-triaged against the one-sentence test.

There is no owner question here. What this issue actually needs is an experiment I can run: set kotlin.native.enableKlibsCrossCompilation=true and run apiCheck on a Linux host, and see whether the Apple klibs build. Either they do — and apiCheck starts covering all ten klib targets instead of five — or they fail, and the failure tells us why the flag was set, which is the comment the line has been missing since the initial import.

Reclassifying to agent-workable.

No default recommendation attached, deliberately — I could not form one, which is why this stayed parked. The experiment decides it, and there is a real possibility the answer is "leave the flag alone and write down why", in which case the deliverable is a comment on gradle.properties:4 plus a correction to the ci-apple.yml header, which presents a project setting as a platform limitation.

Whichever way it lands, ci-apple keeps its job — klib cross-compilation would not replace compiling Apple sources.

[monkopedia-coder]

Ran the experiment. Apple klibs do cross-compile on this Linux host, and with them built klibApiCheck genuinely validates the Apple ABI — but flipping the flag is not free, and two modules fail today.

1. They build. With kotlin.native.enableKlibsCrossCompilation=true:

> Task :ksrpc-core:compileKotlinIosArm64
> Task :ksrpc-core:compileKotlinIosSimulatorArm64
> Task :ksrpc-core:compileKotlinIosX64
> Task :ksrpc-core:compileKotlinMacosArm64
> Task :ksrpc-core:compileKotlinMacosX64
> Task :ksrpc-core:klibApiCheck
BUILD SUCCESSFUL in 32s

So the ci-apple.yml comment — "Kotlin/Native does not cross-compile iOS/macOS off a Mac" — is false as written. Apple binaries cannot be built off a Mac; the klibs can, and this project has simply had that switched off.

2. The validation is real, not just compilation. Break-tested rather than assumed: a public function in a new ksrpc-core/src/appleMain source set, present on no other target.

> Task :ksrpc-core:klibApiCheck FAILED
  +final fun com.monkopedia.ksrpc/auditProbeAppleOnlySymbol(): kotlin/String

An Apple-only ABI addition is caught on a Linux host. That is the thing no instrument in this repo could do before.

3. But apiCheck across all modules FAILS with the flag on. Two modules, and the diffs are not cosmetic:

• :ksrpc-sockets:klibApiCheck and :ksrpc-jni:klibApiCheck both fail.
• ksrpc-jni's dump gains // Alias: apple => [...] / // Alias: linux => [...] header lines, and declaration lines move: the cinterop/JNI-only declarations (JavaJniContinuation, JNIDispatcher, cancelScope, createNativeScope, …) render differently once Apple targets participate in the merge, since they exist on linux/mingw and not on Apple.

I am not claiming this is a rendering change, and I am not claiming it is a real ABI difference. I do not know which, and the distinction is the whole question. The committed dumps were generated from a merge that never included the Apple targets, so they describe a target set that does not match what the library actually publishes. Regenerating them with apiDump is mechanically easy; deciding whether the resulting diff is only re-rendering needs someone to read it line by line.

One oddity worth a second pair of eyes in that diff, because I cannot explain it: a sendFromJvm overload appears with a doubled package prefix, com.monkopedia.jnitest.com.monkopedia.ksrpc.jni/JavaJniContinuation. That may be an artifact of the retired com.monkopedia.jnitest shims (removed in #236) surviving in a cinterop-generated name. It may also be nothing.

Where that leaves this issue. The flag is flippable and the payoff is real — Apple ABI validated on every CI run instead of never. The blocker is not the flag, it is that turning it on surfaces a dump mismatch in two modules that has to be understood before it is papered over with apiDump. Splitting that off rather than bundling it here.

Baseline restored: flag back to false, apiCheck green, working tree clean.

[monkopedia-coder]

Re-triaged. Reclassifying agent-workable -> blocked, on #253.

The experiment recorded above answered this issue's own open question. The flag is flippable, the Apple klibs do cross-compile on a Linux host, and with them built klibApiCheck genuinely validates the Apple ABI -- break-tested rather than assumed. It also found that flipping it makes :ksrpc-jni:klibApiCheck and :ksrpc-sockets:klibApiCheck fail, and #253 then measured that failure precisely: 24 declarations added under a doubled com.monkopedia.jnitest.com.monkopedia.ksrpc.jni package, and one Apple-only posixFileWriteChannel overload that the committed dump claims and a real build does not emit.

That is a named dependency, not a decision. This issue's own last comment says as much -- "the flag flip is blocked on knowing which" -- and #253 exists to answer it. blocked records that; agent-workable was advertising a flag flip that its own author had already concluded should not be made yet.

Unblocks automatically when #253 lands. See the note there on reaching a genuine macOS host without waiting for a publish.

[monkopedia-coder]

The blocker on this is now measured rather than suspected — see #253 for the full three-way comparison against a genuine macOS host.

The short version: do not flip the flag yet, and apiDump is the wrong way to make it green.

module	committed	linux-cross	real mac
ksrpc-jni	219	241	219
ksrpc-sockets	10	9	9

For ksrpc-jni the Mac agrees with the committed dump exactly, and the 22 extra declarations exist only when dumping on Linux with cross-compilation on — they appear in none of the nine per-target dumps the Mac produced, including its own linuxX64 and mingwX64. So flipping the flag and regenerating would record 22 phantom declarations, including a doubled package name and the retired com.monkopedia.jnitest shim from #236, as the sanctioned Apple ABI.

For ksrpc-sockets it goes the other way: the committed dump promises an Apple-only posixFileWriteChannel(Int) that no target produces — all seven native targets built on the Mac have only the two-argument defaulted form.

So this issue now has a concrete precondition rather than an open question: the 22 cross-compilation artifacts need explaining (or the cross-compiled dump needs to stop inventing them) before the flag is worth flipping. ksrpc-sockets' stale line is safe to remove on the evidence, but it cannot be removed on its own — apiCheck on Linux with the flag off currently expects it.

Not investigated: why cross-compilation invents those declarations. The doubled package points at cinterop klib resolution picking up a stale or mis-keyed artifact, but I did not trace it, and whether that is a ksrpc packaging problem or a Kotlin/Native one is open.