Understanding Stability Inference

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 87cfb886f00d · 16 Oct 2026Report an issue or request a re-scan

• Publisherskydoves GitHub userOwner of the repository this skill is read from
• Source folderskydoves/compose-performance-skills/stability/understanding-stability-inferenceThe exact folder we audited
• LicenceApache-2.0As the repository states it
• Commit pinned for this verdict87cfb886f00dA new audit runs when the source changes
• Repository statusNot archivedLast push 121 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Use this skill to explain why the Compose compiler classified a class or composable parameter as stable, runtime, unknown, or unstable. Covers the 12-phase inference algorithm, the five compiler-level stability types…

---
name: understanding-stability-inference
description: 'Use this skill to explain why the Compose compiler classified a class or composable parameter as stable, runtime, unknown, or unstable. Covers the 12-phase inference algorithm, the five compiler-level stability types (Certain / Runtime / Unknown / Parameter / Combined), the generic bitmask encoding (Pair=0b11, ImmutableList=0b1), the Known Stable Constructs registry, and the runtime `$stable: Int` field generated by `@StabilityInferred`. Use when the developer asks "why is X classified as Y?", when a stability report shows a surprising `runtime stable`, `unknown`, or `unstable` verdict, when generics, inheritance, cycles, interfaces, or cross-module classes are involved, or when the user mentions `$stable`, `@StabilityInferred`, separate compilation, or "the compiler thinks my class is unstable but it looks fine".'
license: Apache-2.0. See LICENSE for complete terms.
metadata:
  author: Jaewoong Eum (skydoves)
  keywords:
  - jetpack-compose
  - performance
  - stability
  - stability-inference
  - compose-compiler
  - runtime-stability
  - stability-inferred
  - generics-stability
  - separate-compilation
  - known-stable-constructs
---

# 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 

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/skydoves/compose-performance-skills
git -C compose-performance-skills checkout 87cfb886f00d

Works in

1. 2026-10-16
   ✓SAFE B 89 / 100

   first audit · source 87cfb886f00d

Questions about Understanding Stability Inference

• github.com/skydoves/compose-performance-skills/tree/main/stabili — the audited source at commit 87cfb886f00d and every finding aboveObserved · 16 Oct 2026

Spotted something wrong? Report a correction · Methodology