Kotlin Language

Ketoy executes a well-defined **subset** of Kotlin at runtime. This page covers what you can use inside a `@KetoyComposable` / `@KetoyEntryPoint` / `@KetoyViewModel` and what the compiler rejects.

The shorter version: write idiomatic Kotlin. Data classes, sealed classes, when, lambdas, coroutines, generics, extension functions — all supported. The boundary is at the system interface: Android APIs, reflection, file I/O, raw Java interop need to go through capabilities.

Primitive types

Int, Long, Float, Double, Boolean, String, Char, Unit, null. Full arithmetic (+ - * / %), comparison (==, !=, <, <=, >, >=, ===), null-checks (?:, ?., !!). Boolean operators (&&, ||, !). Bitwise on Int (or, and, xor, shl, shr, ushr). Int↔Long/Float/Double conversions. Boxing / unboxing of nullable primitives.

Strings

String is a first-class type. + concatenation ("a" + b), template interpolation ("$x $y"), .length, .substring(start, end). The string pool deduplicates literals per bundle.

Control flow

All standard Kotlin control flow:

if (x > 0) doA() else doB()

when (state) {
    is Loading -> Spinner()
    is Error -> ErrorText(state.message)
    is Success -> Content(state.value)
}

for (item in list) { process(item) }
items.forEach { process(it) }

while (active) { tick() }
do { tick() } while (active)

repeat(3) { i -> log(i) }

break / continue work. return returns from the enclosing function.

try / catch / finally

try {
    risky()
} catch (e: NetworkException) {
    log(e)
} catch (e: Exception) {
    setState("error", e.message)
} finally {
    setState("loading", false)
}

Caveat: catch is currently catch-all. The first handler runs for any exception type — multi-catch falls through to the first one. Always explicitly re-throw CancellationException to preserve structured cancellation:

} catch (e: Throwable) {
    if (e is CancellationException) throw e
    log(e)
}

Data classes

Full support — equals, hashCode, toString, copy, componentN auto-generated:

data class Todo(val id: Long, val title: String, val completed: Boolean)

@KetoyComposable
@Composable
fun TodoRow(todo: Todo) {
    val (id, title, completed) = todo  // destructuring works
    Row {
        Checkbox(checked = completed, onCheckedChange = { /* ... */ })
        Text(title)
    }
}

copy() creates new instances; structural equality is automatic.

Sealed classes / sealed interfaces

sealed interface UiState {
    object Loading : UiState
    data class Error(val message: String) : UiState
    data class Content(val items: List<Item>) : UiState
}

@KetoyComposable
@Composable
fun Screen(state: UiState) {
    when (state) {
        is UiState.Loading -> CircularProgressIndicator()
        is UiState.Error -> Text("Error: ${state.message}")
        is UiState.Content -> Column { state.items.forEach { ItemRow(it) } }
    }
}

is (INSTANCEOF), as (CAST), as? (SAFE_CAST), exhaustiveness checking — all work.

Enum classes

enum class Priority { LOW, MEDIUM, HIGH }

fun colorFor(p: Priority): Color = when (p) {
    Priority.LOW -> Color.Gray
    Priority.MEDIUM -> Color.Yellow
    Priority.HIGH -> Color.Red
}

values() and valueOf() work via stdlib intrinsics.

Objects (singletons)

object AppDefaults {
    const val MAX_ITEMS = 50
    val PADDING = 16
}

fun render() = Column(modifier = Modifier.padding(AppDefaults.PADDING.dp)) { /* ... */ }

Companion-object properties are emitted as static-style getters and resolved by the validator + ComposeTokenRegistry.

Functions

Top-level functions

fun formatCurrency(amount: Long): String = "$${amount / 100.0}"

@KetoyComposable @Composable
fun PriceTag(price: Long) { Text(formatCurrency(price)) }

Same-module top-level functions are auto-included in the closure walk. You don't need @KetoyComposable on plain helpers — only on entry points and on @Composable functions that participate in adapter resolution.

Extension functions

fun List<Todo>.completedCount(): Int = count { it.completed }

@KetoyComposable @Composable
fun Header(todos: List<Todo>) {
    Text("${todos.completedCount()} done")
}

The receiver becomes register 0 of the helper function.

Inline functions

inline fun is inlined by the Kotlin frontend before the IR extension runs — the compiler sees the inlined body. Reified type parameters work if the use site is concrete.

Higher-order functions / lambdas

val onClick: () -> Unit = { count++ }
items.forEach { item -> render(item) }

Lambdas with captured outer-scope locals are fully supported via closure conversion (the compiler analyses each lambda, records the captures, lowers them to function parameters threaded through KBCValue.ClosureRef).

Generics

Erased at IR time — KBC sees the same shape Kotlin would. Type checks (is List<String>) only match the erased type:

val x: Any = listOf(1, 2, 3)
if (x is List<*>) { /* OK */ }
if (x is List<Int>) { /* same as List<*> at runtime */ }

This matches JVM behaviour.

Collections

val list = listOf("a", "b", "c")
val map = mapOf("k" to "v", "q" to "r")
val mutable = mutableListOf<Int>().apply { add(1); add(2) }

list.size
list[0]
list.forEach { println(it) }
list.map { it.uppercase() }
list.filter { it.startsWith("a") }

listOf, emptyList, mapOf, mutableListOf are intrinsified and lowered to KBC collection opcodes (LIST_NEW, MAP_NEW, …). Bigger stdlib operations route through INVOKE_VIRTUAL against the KBC heap.

If you call a stdlib function that isn't in the validator's allowlist, you'll get UnregisteredCall with a fuzzy-match suggestion. Add the FQ name to your ketoy-capabilities.json's allowedStdlibFqNames list to permit it:

"allowedStdlibFqNames": [
  "kotlin.collections.listOf",
  "kotlin.collections.emptyList",
  "kotlin.let",
  "kotlin.run",
  "kotlin.also",
  "kotlin.apply",
  "kotlin.with",
  "kotlin.takeIf",
  "kotlin.requireNotNull",
  "kotlin.error",
  "kotlin.TODO"
]

Classes (user-defined)

class Counter(initial: Int = 0) {
    var value: Int = initial
        private set

    fun increment() { value++ }
    fun reset() { value = 0 }
}

val c = Counter()
c.increment()
c.value      // → 1

User class instances live on the KBC heap (NEW_INSTANCE, GET_FIELD, SET_FIELD, INVOKE_VIRTUAL). Inheritance is limited — there's no virtual-dispatch table beyond the immediate INVOKE_VIRTUAL lookup. Adapter-routed Compose types and registered capabilities are the supported way to reach platform behaviour. For sealed-class hierarchies you use yourself in KBC, virtual dispatch via INVOKE_VIRTUAL works fine.

What you can't do

Hard non-goals (compile errors)

Limits that produce silent surprises (no error)

• try / catch is catch-all — first handler runs for any throwable. Workaround: branch on is inside the handler.
• Generics are erased — is List<Int> matches any list. Standard JVM behaviour.
• Inheritance beyond INVOKE_VIRTUAL on direct method lookups is limited. Sealed-class + when is the recommended pattern.

The closure walk

When the compiler sees a @KetoyComposable / @KetoyEntryPoint / @KetoyViewModel, it walks the entire transitive call graph reachable from that root, validating every call along the way. Same-module unannotated top-level functions and extension functions are auto-included.

Functions that are not reachable from any KBC root compile straight to DEX as plain Kotlin and ship with the next APK release — the closure walk leaves them untouched. This is how you can have a single :app module containing both KBC source (e.g. ketoyscreens/HomeScreen.kt) and native fallbacks (e.g. ui/HomeNativeFallback.kt).

Breadcrumbs in error messages

Errors detected in a transitively-reached helper carry a call chain:

KetoyBC: Direct access to 'android.util.Log.d' is not allowed in KBC programs.

  Reached via: HomeScreen → renderHeader → logHelper

  Android APIs are not available in the KBC execution sandbox.
  ...

The chain follows the call path from the entry-point root to the offending helper.

Compose-specific Kotlin features

What about expect/actual?

KBC source is single-target (Android). expect/actual declarations aren't applicable — your KBC bundle is an Android-only artifact.

For sharing logic between KBC and platform-native code, prefer:

• Hoisting pure logic into a KMP module that both can depend on.
• Or duplicating tiny helpers (often clearer than a shared module for small surfaces).

Next: KBC Opcodes →