Ditto Kotlin SDK

Use the shipping API: on v5 everything is DittoFactory.create(DittoConfig), ditto.sync, ditto.store with DQL, and suspend/Flow observers; the v4 Ditto(dependencies, identity) constructor and legacy collection API are gone. Establish the version line first (com.ditto:ditto-kotlin = v5, live.ditto:ditto = v4, Android-only); emit v5 code by default and say which version you assumed. Do not invent APIs from memory — the v4→v5 surface changed completely.

Read only the reference sections the task needs; inspect a long file's contents first. Do not preload all references or the README (the capability/evidence map).

What this skill does

Writes and reviews Ditto Kotlin code: Gradle setup, initialization, authentication, DQL store access, sync, observers and Flows, attachments, presence, transports, object lifetimes, threading, errors and testing. Supports 4.14.x (LTS), 5.0.x, 5.1.x and 5.2.x on Android (both lines) and plain JVM (5.x only).

When to use this skill

Use this skill for Kotlin Ditto code: API shape, initialization, object lifetimes, threading, error types, and build configuration.

Hand off rather than restating; each row names a public URL in case the concept skill is not installed:

Supported versions and packages

Packages: com.ditto:ditto-kotlin (v5; KMP root — Gradle resolves -android / -jvm) and live.ditto:ditto (4.14.x, Android-only). Published API reference: https://software.ditto.live/kotlin/ditto-kotlin/5.2.0/api-reference/.

references/versions.md owns every fact that differs across version lines, including package coordinates per version and the minimum toolchain. v4 and v5 are different APIs, not two versions of one.

For new apps and POCs, check the package manager for the latest stable release and use that resolved version. 5.2.0 is the latest version this skill knows about, not a permanent recommendation or claim about today’s latest release. Preserve an existing project’s selected version unless an upgrade is requested. If a newer release is found, read its release notes/API changes and validate the generated code. If lookup is unavailable, state that limitation; do not silently call 5.2.0 “latest”. Resolve Maven Central metadata and share the selected version across Kotlin and native binaries; see setup.md.

Read sdk-5.2.md when adopting 5.2.0 features or reviewing an upgrade: encryption, store deletion, startup configuration and behavior fixes.

Capability exceptions

Full twenty-row evidence map: README.md, for capability reviews only.

Minimum viable app

Open → subscribe → observe → write (JVM shown; on Android hold the instance in Application; no ditto-binaries classifier is needed there):

fun main() = runBlocking {
    val ditto = DittoFactory.create(
        DittoConfig(
            databaseId = "my-app",
            connect = DittoConfig.Connect.SmallPeersOnly(),
            persistenceDirectory = "/tmp/ditto-data",
        )
    )
    ditto.setOfflineOnlyLicenseToken(System.getenv("DITTO_OFFLINE_LICENSE"))
    ditto.sync.start()

    val subscription = ditto.sync.registerSubscription("SELECT * FROM cars")
    val observer = ditto.store.registerObserver("SELECT * FROM cars") { result ->
        println("cars: ${result.items.size}")   // extract inside the lambda!
    }
    ditto.store.execute(
        "INSERT INTO cars DOCUMENTS (:car) ON ID CONFLICT DO UPDATE",
        mapOf("car" to mapOf("_id" to "car1", "make" to "Toyota"))
    )

    observer.close(); subscription.close(); ditto.sync.stop(); ditto.close()
}

Complete program, dependencies and run transcripts (5.2.0/5.1.0/5.0.3 JVM and Android, 4.14.7 Android): examples/minimal-app.md.

Concurrency and threading model

Read concurrency.md for the per-API table and reasoning. Core constraints:

• Observer handlers start on the SDK's scope: the main thread on Android (MainScope()), Dispatchers.Default on JVM — source-verified and executed on a Pixel. Treat every handler as UI-thread code.
• Hop inside the handler: withContext(Dispatchers.IO) for extraction and decode, then plain data back to the UI. The result stays open while the handler is suspended. .flowOn() does not reach the observe() transform — it runs on the SDK scope.
• DittoFactory.create, sync.start()/stop(), registerSubscription, registerObserver are not suspend. store.execute, store.collect, auth.login, attachment fetches are suspend.
• Handlers are serialized with back-pressure: the next event is produced only after the handler returns, coalescing intermediate changes. Never launch per event, never .buffer(); use .conflate()/stateIn for latest-only UI, collect() for ordered pipelines.
• Cancelling the collecting scope (viewModelScope, lifecycleScope) closes an observe()/collect() observer; a registerObserver handle needs close().
• expirationHandler is a property holding a suspend lambda — call login directly in its body, never inside launch { }.

Object lifetimes and retention

One Ditto per process, owned by Application/a DI singleton (Android) or a top-level holder (JVM); closing it closes every child resource. Retain DittoSyncSubscription and registerObserver handles so you can close() them; never retain DittoQueryResult or its items — they die when the handler returns (IllegalStateException: Query result item has already been closed.). Flows from observe()/collect() need no handle: the collecting scope is the lifetime. Do not cache ditto.sync.subscriptions or ditto.store.observers; they are live views. Handle table and per-component cleanup: lifetimes.md.

Anti-patterns

Read anti-patterns.md for wrong/right forms.

• Returning result.items (or the result) from a handler or observe() transform: Query result item has already been closed. / "You must not return DittoQueryResult".
• An exception escaping a registerObserver handler: the SDK logs Unhandled exception in observer event handler and closes the observer.
• .buffer() on an observe() chain: unbounded queue, eventual OOM.
• scope.launch { … } per event inside a handler: lost ordering, closed-item crashes.
• .flowOn(Dispatchers.IO) to move decoding off main: no effect on the transform.
• Casting item.value["x"] as String: ClassCastException — use .stringOrNull or jsonString().
• setExpirationHandler(…) does not compile; launch around auth.login abandons it.
• Plain INSERT of an existing _id: Identifier conflict … FAIL conflict policy — add ON ID CONFLICT DO UPDATE.
• JVM without ditto-binaries: Unable to find binary 'libdittoall…' on create.

Version differences

Full delta, on-disk migration and removed-API table: references/versions.md.

References

Choose the matching row and section; alternatives, not a reading checklist.