Understanding Stability Inference

Understanding Stability Inference — read the compiler's mind

Stability is decided by a 12-phase algorithm baked into the Compose compiler. This skill teaches Claude how the algorithm walks a type so it can explain why a report says what it says, and predict classifications before the report is even generated. Pair this with ../diagnosing-compose-stability/SKILL.md (which generates the report) and ../stabilizing-compose-types/SKILL.md (which fixes obvious unstable types). Reach for this skill when the simpler skills produce a verdict that surprises the developer.

When to use this skill

• The developer asks "why is Foo classified as runtime stable and not stable?"
• A report shows runtime or unknown for a class that "looks fine".
• Generics involved: Box<T>, Wrapper<A, B>, Pair<String, Int>, ImmutableList<User>.
• The class lives in another module and ships as a .class/.kotlin_metadata artifact.
• The developer asks about the $stable: Int field, @StabilityInferred, or cross-module classification.
• A self-referential type (class Node(val children: List<Node>)) is unstable for non-obvious reasons.
• A Java type, an interface, or an abstract base appears in a parameter list and surprises the developer.

When NOT to use this skill

• The fix is mechanical (var → val, List → ImmutableList, Flow parameter removal). Use ../stabilizing-compose-types/SKILL.md.
• No report exists yet. Run ../diagnosing-compose-stability/SKILL.md first.
• The developer wants CI enforcement of stability. Use ../enforcing-stability-in-ci/SKILL.md.

Prerequisites

• Compose Compiler reports already generated, or at least one <module>-classes.txt and <module>-composables.txt available in build/compose_compiler/.
• The developer understands the basic stability vocabulary: stable, unstable, skippable, restartable, @Stable, @Immutable.
• Kotlin 2.0+ with the Compose compiler plugin (Strong Skipping default ON).

Workflow — diagnostic question and answer tree

Walk the type through the same 12 phases the compiler does. For each call site, ask the questions in order; the first matching phase wins.

The canonical phase order (used everywhere in this skill and matching references/twelve-phase-algorithm.md):

1. Phase 1 — primitive / String / function / Unit fast path → Stable. The compiler returns immediately. No field analysis runs. Mention the fast path so the developer knows nothing else was inspected.
2. Phase 2 — type parameter substitution. A bare type variable T becomes Stability.Parameter(T); resolution is deferred to the call site that substitutes it.
3. Phase 3 — nullable unwrap (Int? → analyze Int). Nullability does not change stability; the algorithm strips the ? and recurses.
4. Phase 4 — inline class — check underlying type. value class Wrapper(val raw: T) is exactly as stable as T.
5. Phase 5 — cycle detection (recursive trees → conservative UNSTABLE). The algorithm bails on cycles to guarantee termination. The escape hatch is @Stable/@Immutable on the recursive class, which fires in phase 6 before phase 5 is reached.
6. Phase 6 — annotations check (@Stable, @Immutable, @StableMarker). Yes → Stability.Certain (stable). @Immutable enables additional optimizations beyond @Stable because the compiler can promote reads of properties to static expressions and elide equality checks; @Stable only promises change notification.
7. Phase 7 — Known Stable Constructs registry hit (Pair / Triple / Result / ImmutableList / dagger.Lazy / ClosedRange / etc.). Returns Stability.Parameter with the registry's bitmask. See references/bitmask-encoding.md for the full registry.
8. Phase 8 — external configuration match (stability_config.conf). Returns Stability.Parameter with the bitmask declared in the config file.
9. Phase 9 — external module (@StabilityInferred annotation generated by separate compilation). Returns Stability.Runtime. The compiler emits a $stable: Int field on the JVM (a mangled top-level property on Native/JS) that the runtime queries via Composer.changed. Tell the developer this is not a bug — runtime is the compiler saying "I cannot prove this at compile time, so I will check at runtime".
10. Phase 10 — Java type (default UNSTABLE — fix via config file). Java final fields look like var to the inference because the algorithm has no Kotlin metadata to read. Fix via stabilityConfigurationFiles, not by editing the Java source.
11. Phase 11 — interface (UNKNOWN; runtime ===). The compiler cannot enumerate implementations from a single call site; the runtime falls back to identity (===) for the equality probe.
12. Phase 12 — field-by-field analysis (the slow path):
    • Walks the linearized class hierarchy so inherited fields participate. There is no separate "inheritance" phase — inheritance lives here.
    • Any var property → Unstable (mutation observed without Snapshot integration).
    • Any property whose type is Unstable → Unstable (Combined dominates).
    • Otherwise the class is Stable (Combined of all-stable fields collapses to Stable).

For full pseudocode of all 12 phases plus the field-by-field loop, see references/twelve-phase-algorithm.md.

Patterns

Pattern: "Why does Box<String> show as runtime stable?"

// Source — the developer's class, in a library module
class Box<T>(val value: T)

// Call site, in app module
@Composable fun BoxRow(box: Box<String>) { Text(box.value) }

The compiler walks Box<T>:

1. Phase 12 (field-by-field) inside the defining module finds one field value: T; recursion on T hits phase 2 (type parameter) → Stability.Parameter. Combined collapses to Stability.Parameter with bitmask 0b1 (the single type parameter affects stability).
2. Because Box is consumed from a different module, the compiler emits @StabilityInferred(parameters = 0b1) on Box and a $stable: Int field initialized from T's stability at runtime. Downstream call sites pick this up via phase 9.
3. Call-site substitution → T = String → String is Certain Stable → bit 0 satisfied.
4. Final report line: runtime stable class Box<T> and at the call site BoxRow is skippable.

// WRONG mental model
// "runtime stable means there is a runtime cost on every recomposition" — partly true but misleading
// WRONG because: the cost is one Int field load and a bitwise AND, performed once when the runtime
// computes the call-site stability. It is far cheaper than the unskipped recomposition it prevents.

// RIGHT mental model
// runtime stable = "the compiler proved stability conditional on the type arguments, and emitted
// a $stable: Int field whose bits the runtime ANDs against the substituted argument stabilities".
// The skip decision is still made; it is just made at runtime instead of compile time.

Pattern: "Why does @Immutable data class Person(val name: String) enable more optimizations than @Stable?"

@Stable is a contract: "I will notify Compose of changes". @Immutable is a stronger contract: "I will never change". With @Immutable the compiler may promote reads of Person.name to static expressions and elide equality probes for nested usages; with @Stable it must still emit equality checks. Both classify as Stability.Certain, but the downstream optimizer treats @Immutable more aggressively.

// WRONG
@Stable data class Coordinates(val lat: Double, val lng: Double)
// WRONG because: Coordinates never mutates after construction. @Stable understates the contract
// and forfeits static-expression promotion at every read site.

// RIGHT
@Immutable data class Coordinates(val lat: Double, val lng: Double)

Pattern: "Why is my recursive tree unstable even though it looks fine?"

data class Node(val id: String, val children: List<Node>)

Phase 5 (cycle detection) bails. The compiler does not attempt fixed-point analysis because it would have to assume the answer to prove the answer. The conservative verdict is Unstable. Even if every field is otherwise stable, the recursion through children returns Unstable to the parent call.

// WRONG — adds @Stable to "force" stability
@Stable data class Node(val id: String, val children: List<Node>)
// WRONG because: List<Node> is a mutable interface backed by ArrayList in practice. The @Stable
// annotation tells the compiler to trust the contract, but the actual List instance can mutate
// between recompositions without notifying Compose, producing silent missed recompositions.

// RIGHT
import kotlinx.collections.immutable.ImmutableList
@Immutable data class Node(val id: String, val children: ImmutableList<Node>)

ImmutableList is in the Known Stable Constructs registry (phase 7) with bitmask 0b1, so the recursion through children is permitted: cycle detection still triggers in phase 5, but the registry hit short-circuits the conservative verdict.

Pattern: "Why does Set<String> block skipping but ImmutableSet<String> doesn't?"

kotlin.collections.Set is an interface (phase 11 → Unknown) backed in practice by LinkedHashSet, which mutates. kotlinx.collections.immutable.ImmutableSet is in the Known Stable Constructs registry with bitmask 0b1, so it is Stability.Parameter and resolves to stable when the element type is stable.

// WRONG
@Composable fun TagRow(tags: Set<String>) { /* ... */ }
// WRONG because: Set is an interface — phase 11 returns Unknown, the call site is non-skippable.

// RIGHT
@Composable fun TagRow(tags: ImmutableSet<String>) { /* ... */ }