Explain KSP's multi-round model: why does process() return a List<KSAnnotated>, and how does deferral interact with code that is generated during processing?

## Why rounds exist Generated code can itself be **input** to processing: a class you emit may carry annotations, or another annotated class may *reference* a type you haven't generated yet. A single pass can't handle that ordering, so KSP runs **multiple rounds**, calling `process()` once per round until the system reaches a fixed point. ## The return value: deferral ```kotlin override fun process(resolver: Resolver): List<KSAnnotated> ``` The returned list is the set of symbols the processor **could not complete this round** and wants KSP to **re-present next round**. The canonical reason is failed **`validate()`**: a symbol references a type that isn't resolvable yet (often because it will be generated by this or another processor in a later round). ```kotlin override fun process(resolver: Resolver): List<KSAnnotated> { val symbols = resolver.getSymbolsWithAnnotation("com.example.Wire").toList() val (ready, deferred) = symbols.partition { it.validate() } ready.filterIsInstance<KSClassDeclaration>().forEach { emit(it) } return deferred // KSP re-invokes process() with these next round } ``` ## The round loop, precisely 1. **Round 1**: `process()` runs over the original sources. You emit files and return deferred symbols. 2. KSP gathers the files generated this round and makes them part of the program. 3. **Round N+1**: `process()` runs again. Now `getSymbolsWithAnnotation` can also return symbols **on the newly generated code**, and the deferred symbols from round N are available again. 4. The loop stops when a round generates **no new files** and there is **nothing left deferred** — a fixed point. 5. **`finish()`** (optional override) is invoked **once** after the final round for cleanup/aggregation that needs the complete picture. There's no `Resolver` in `finish()` because processing is over. ## Hazards a principal must control - **Idempotence / duplicate files** — emitting the same `packageName`+`fileName` twice (e.g., re-processing the same symbol in two rounds) throws `FileAlreadyExistsException`. Track what you've already generated, or only generate from symbols you handle exactly once. - **Non-termination** — if you defer a symbol every round without ever making progress, the build can loop or fail. Defer **only** when there's a real chance later rounds will resolve it; otherwise report an error via `KSPLogger.error` and stop deferring. - **Determinism** — generated output should be stable given the same inputs (sorted iteration, no reliance on `HashSet` order) so incremental builds and caches behave. - **State across rounds** — a processor instance is reused across rounds within one compilation, so instance fields persist; use that for cross-round bookkeeping, but reset appropriately between compilations. - **Aggregating dependencies** interact with rounds: outputs summarizing all matches must use `Dependencies(aggregating = true, ...)` so new symbols appearing in later rounds invalidate the summary. ## Worked deferral scenario Suppose `@Wire class A(val b: B)` where `B` is generated by another `@Wire`-driven processor. In round 1, `A`'s parameter type `B` may not resolve → `A.validate()` is false → defer `A`. After `B` is generated, round 2 resolves `B`, `A.validate()` is true, and you emit `A`'s output. ## Key terms - **Round** — one `process()` invocation; KSP loops to a fixed point. - **Deferral** — returning unfinished `KSAnnotated` for a later round. - **validate()** — resolvability check that usually drives deferral. - **finish()** — single post-processing callback after the last round. - **Idempotence** — not re-emitting files across rounds.