zenoh-flat transition (integration branch)

[milyin]

Umbrella PR for rebuilding zenoh-kotlin on top of the generated JNI/Kotlin bindings
(zenoh-flat-jni, produced by prebindgen from
zenoh-flat). It removes the embedded
zenoh-jni Rust crate and the hand-written io.zenoh.jni adapter layer that sat on
top of it. This is the zenoh-kotlin counterpart of eclipse-zenoh/zenoh-java#482 — both
SDKs converge on the same shared bindings tier:

zenoh (Rust)
  └─ zenoh-flat            flat #[prebindgen]-annotated Rust API
       └─ zenoh-flat-jni   generated JNI externs + Kotlin classes (prebindgen JniGen)
            └─ zenoh-kotlin  Kotlin SDK wrapper (this repo)

The branch also carries the earlier external-jni series (#651), which had already
replaced the in-repo Rust crate with the zenoh-jni-runtime artifact; that interim
dependency is gone too.

The zenoh-jni crate (25 files, ~9.1k lines) and every JNI*.kt adapter are deleted;
what remains in zenoh-kotlin/src is the public Result-based SDK facade plus three
small adapter files (FlatCallbacks.kt, FlatEnums.kt, ResultHandlers.kt).

Error model

The generated bindings never throw across JNI: a fallible wrapper takes trailing
error-sink callbacks and returns the sink's value on failure. zenoh-kotlin's public
API is Result-based, so the failure is recorded directly inside the sink — the SDK
has zero try/catch and zero runCatching around native errors on the JNI path.

ResultHandlers.kt folds two channels into one Result: onBindingError
(JniErrorHandler — UTF-8 decode, closed handle, …) and onError (the typed domain
ErrorHandler, carrying the decomposed zenoh message). Call sites use
zCall/zCallUnit (both channels) or zCall0/zCallUnit0 (binding-only). The
enclosing runCatching exists solely for JVM-side throws — argument preparation,
user IntoZBytes.into() conversions, native-library loading during class init — so
the public Result contract of the pre-flat API is preserved exactly.

Callbacks are value-decomposed: a Sample, Query, Hello or Reply arrives as
its leaves in one JNI crossing, with no per-field accessor calls.

Serialization

zSerialize/zDeserialize no longer cross JNI at all. They build a
SerializationCodec.SerdeType from the full KType (KTypeSerde.kt) and run the
shared pure-Kotlin codec in zenoh-flat-jni, which is byte-identical to the native
serializer (correspondence tested upstream against the native oracle). Measured
speedup on small payloads: ~156× (Int), ~320× (List<Int>), ~279×
(Map<String,Int>). UByte/UShort/UInt/ULong/Pair/Triple are supported.

Public API changes

Source-breaking, all tracking zenoh/zenoh-flat semantics:

• Timestamp — Sample.timestamp and Query.reply(timestamp = …) carry
  io.zenoh.time.Timestamp (the (ntp64, id) pair, mirroring zenoh::time::Timestamp)
  instead of commons-net's TimeStamp. The old JNI layer fabricated the missing id with
  ID::rand(); a reply now carries the replying session's real id, and a received
  sample surfaces the sender's, which was previously discarded. Use
  Timestamp.ofNtp64(ntp64, zid). commons-net drops out of the library's dependencies
  (tests and the ZQueryable example still use it as an NTP64 clock).
• Parameters — a thin facade over the shared string-backed implementation
  (Rust parameters.rs semantics): values are no longer percent-decoded, from never
  fails (the Result signature is kept for source compatibility), duplicate keys are
  accepted with first-match-wins get, and toString round-trips verbatim.
• Config.fromJson parses via JSON5 (of which JSON is a subset — every input
  accepted before parses to the same config); the invented config_new_from_json
  entry point is gone.
• SampleMiss → Miss as the payload type (Miss(source: EntityGlobalId, nb: Long)),
  following zenoh's own naming. The SampleMissListener surface is unchanged.
• A sample's source and a reply's replier arrive as whole SourceInfo /
  EntityGlobalId values, so optionality lives on the value rather than on a leading
  zid leaf.
• A declared KeyExpr is the only one holding a native handle; every other key
  expression is a plain validated string with nothing to close.

Build & CI

• No Rust toolchain, NDK cross-compilation or cargoBuild wiring in this repo; the
  native library ships with org.eclipse.zenoh:zenoh-flat-jni.
• Gradle wrapper (8.12.1) is committed (Add Gradle wrapper (8.12.1), like zenoh-java #676), replacing the CI gradle-version pin and
  the throwaway wrapper the publish workflows used to generate.
• CI checks out sibling zenoh-flat-jni / zenoh-flat at pinned commits and builds
  through the Gradle composite build; prebindgen resolves from crates.io. Pins are
  bumped as the upstream PRs land.

Constituent PRs

PR	Scope
#651	external-jni: drop the in-repo zenoh-jni crate for an external runtime artifact
#668	Port zenoh-kotlin to the zenoh-flat-jni generated bindings
#670	Parameters becomes a facade over the shared string-backed implementation
#673	Migrate to the split error-handler API
#675	Serialize via the pure-Kotlin SerializationCodec (no JNI)
#676	Add the Gradle wrapper (8.12.1)
#678	Advanced pub/sub: AdvancedPublisher/AdvancedSubscriber, matching + sample-miss listeners
5977bb1	Realign with zenoh-flat HEAD; a timestamp carries its clock's id (direct commit)
#692	CI: build zenoh-flat-jni against published prebindgen
#695	Release preparation: repair the release path, document publishing

Process

This PR stays draft while the transition is in progress. Individual changes land as
reviewable PRs targeting the zenoh-flat-transition branch; this PR accumulates
them and merges to main as a whole. Upstream companion PRs (prebindgen → zenoh-flat →
zenoh-flat-jni) merge first; the zenoh-kotlin PR then pins the exact upstream commits in
CI and merges once green. This description is the single record of the architecture
and the constituent-PR list.

🤖 Generated with Claude Code

[milyin]

Review of the branch as of 71969d0

Read the whole diff vs main (119 files, +2,365 / −12,345). The substance holds up:
the error-sink wiring in ResultHandlers.kt is consistent at every call site, the
consuming-vs-borrowing key-expr param split (cloneHandle()/intoJniHandle() vs the
jniSel/jniStr/jniHandle trio) is used correctly, the query-drop-on-reply model
matches what main already did, and queryCallbackOf frees the owned leaves if
decomposition ever throws. No correctness objections.

Five loose ends, none blocking:

1. Stale repository links. README.md (lines 128/138/163), settings.gradle.kts:27
   and ZENOH_FLAT_TRANSITION.md (lines 20/21/51) still point at the old
   ZettaScaleLabs/zenoh-flat{,-jni} forks; CI already checks out eclipse-zenoh.

2. ZENOH_FLAT_TRANSITION.md is out of date. Its constituent-PR table stops at Port zenoh-kotlin to zenoh-flat-jni generated bindings #668
   plus "shared-parameters — open", and its follow-up list still describes the
   KType-over-JNI serializer as the approach taken — Serialize via the pure-Kotlin SerializationCodec (no JNI) #675 replaced that with the
   pure-Kotlin SerializationCodec. Advanced pub/sub is listed as planned but landed in
   Advanced pub/sub: AdvancedPublisher/Subscriber, matching + sample-miss listeners #678. Either refresh it or drop it at merge time (it is meant to be removed anyway).

3. guava looks dead. zenoh-kotlin/build.gradle.kts:57 declares
   com.google.guava:guava:33.3.1-jre "required by zenoh-flat-jni's deserializer (guava
   TypeToken)", but nothing in this repo touches TypeToken since Serialize via the pure-Kotlin SerializationCodec (no JNI) #675 moved
   serialization to the pure-Kotlin codec and the Java-Type path relocated to
   zenoh-flat-jni's internal test package. If it is still needed it is
   zenoh-flat-jni's own transitive dependency to declare.

4. kotlin-reflect comment vs dependency. The same commit removed
   implementation("org.jetbrains.kotlin:kotlin-reflect") from commonMain, but
   KTypeSerde.kt's KDoc still says it lives in jvmAndAndroidMain because that is "the
   source set carrying kotlin-reflect". KClass.qualifiedName resolves through the
   stdlib's ClassReference on JVM, so this most likely works by accident rather than by
   the stated reason — worth either restoring the explicit dependency or correcting the
   comment.

5. Stale test comment. AdvancedPublisherTest.kt:33 still says the advanced
   subscriber / sample-miss / detect-publishers side "remains @Ignore'd until Round 2";
   Round 2 landed in Advanced pub/sub: AdvancedPublisher/Subscriber, matching + sample-miss listeners #678 and no @Ignore remains in the suite.

Merge mechanics: the only conflict with main is zenoh-jni/Cargo.lock — deleted on
this branch, bumped daily by the zenoh sync bot. Resolve by keeping the deletion.

🤖 Generated with Claude Code

[milyin]

@copilot resolve the merge conflicts in this pull request

[milyin]

@copilot resolve the merge conflicts in this pull request

[Copilot]

@copilot resolve the merge conflicts in this pull request

Resolved by merging origin/main into this branch and keeping the deletion of zenoh-jni/Cargo.lock as requested. Commit: c38a78a.

@copilot resolve the merge conflicts in this pull request

Merge conflicts are resolved. I merged origin/main and resolved the only conflict by keeping zenoh-jni/Cargo.lock deleted. Commit: c38a78a.

[milyin]

The five loose ends from the review above are addressed in #696 (which also
carries three defects found in a second pass: a ZBytes publication race, the
ReplyKeyExpr reordering, and the build.gradle.kts indentation).

1. Stale repository links — only ZENOH_FLAT_TRANSITION.md was still
   pointing at the ZettaScaleLabs forks; README.md and
   settings.gradle.kts:27 were already corrected by Release preparation: repair the release path and document publishing #695. Fixed.

2. ZENOH_FLAT_TRANSITION.md out of date — refreshed rather than dropped,
   since the umbrella PR links to it. Constituent-PR table synced with the
   branch (Zbobr fix 72 make zenoh kotlin depend on zenoh jni runtime #651 → Release preparation: repair the release path and document publishing #695), the superseded KType-over-JNI serializer note replaced
   with what Serialize via the pure-Kotlin SerializationCodec (no JNI) #675 actually did, advanced pub/sub no longer listed as planned,
   and the follow-up list is now what is genuinely left before the merge.
   Also corrected: prebindgen resolves from crates.io since CI: build zenoh-flat-jni against published prebindgen #692, and the
   error model has had two sink channels since Migrate to the split error-handler API (zenoh-flat-jni #45) #673.

3. guava dead — confirmed and removed. Nothing here references
   TypeToken; the only user is zenoh-flat-jni's own
   io.zenoh.jni.test.Serialization, which declares guava in its jvmTest
   source set, so it was never exported to us in the first place. jvmTest
   is 122 green without it.

4. kotlin-reflect comment vs dependency — corrected the comment rather
   than restoring the dependency: it does work by design, not by accident.
   typeOf<T>() and KClass.qualifiedName are served by
   kotlin.jvm.internal.Reflection in the JVM stdlib, no kotlin-reflect
   artifact involved. That is still a genuine JVM/Android-only constraint, so
   jvmAndAndroidMain stays — the stated reason was just the wrong one.
   Updated in both zenoh-kotlin/build.gradle.kts and KTypeSerde.kt.

5. Stale test comment — done in Review fixes for the zenoh-flat transition #696's first commit.

Verified with ./gradlew jvmTest -PuseLocalFlatJni=true against the pinned
zenoh-flat-jni@6f81eb8 / zenoh-flat@81feb94.

[milyin]

Correction to item 2 above: ZENOH_FLAT_TRANSITION.md is removed in #696 rather than refreshed. It was always going to be deleted at merge time, and keeping it current costs a refresh on every constituent PR. Nothing in the repository linked to it, and this PR's description already carries the same architecture, error model and constituent-PR list — so that is now the single record. I dropped the pointer to the file from the description accordingly.