fun expand(
        source: String,
        parse: (String) -> KtFile,
        maxIterations: Int = 64,
        evalUnquote: ((String) -> String?)? = null,
        ambientRuleSources: List<String> = emptyList(),
        onDiagnostic: (String) -> Unit = {},
    ): ExpandResult {
        val collected = collect(parse(source), onDiagnostic)

        // Ambient rules inherited from ancestor boxes: collected (so they apply here) but NOT blanked
        // from — their `rewrite {}` blocks live in the ancestors' source, not this one. Local rules
        // come first so a box can override an inherited rule (declaration-order, first-match-wins).
        val ambientRules = ambientRuleSources.flatMap { collect(parse(it), onDiagnostic).rules }
        val rules = collected.rules + ambientRules

        // Always strip the local `rewrite {}` blocks from the emitted source — even a malformed or
        // rejected block is erased DSL that must never reach the compiler.
        var text = blankOut(source, collected.deletions)
        if (rules.isEmpty()) return ExpandResult(text, emptyList(), emptyList(), collected.ruleSources)
        val gensym = GensymScope()
        val preambleBlocks = mutableListOf<String>()
        val aiRequests = mutableListOf<AiRequest>()

        fun result() = ExpandResult(
            text,
            preambleBlocks.distinct(),
            aiRequests.distinctBy { it.key },
            collected.ruleSources,
        )

        // A local `strategy {}` block switches from the global fixpoint to controlled term rewriting.
        // (Strategy is box-local control — ambient strategies are not inherited; ambient *rules*
        // still are, so a strategy can name a rule declared in an ancestor.) With no strategy block
        // the loop below is byte-for-byte the historical global fixpoint.
        if (collected.strategyExprs.isNotEmpty()) {
            val named = LinkedHashMap<String, PatternRule>()
            rules.forEach { r -> r.name?.let { named.putIfAbsent(it, r) } }   // first declaration wins
            val program = parseStrategy(collected.strategyExprs, named.keys, onDiagnostic)
            val runner = StrategyRunner(named, parse, gensym, evalUnquote, preambleBlocks, aiRequests,
                onDiagnostic, maxIterations)
            // Fail-closed: an invalid strategy performs NO rewriting (never a surprising partial one).
            runner.eval(program, text)?.let { text = it }
            return result()
        }

        var iteration = 0
        while (true) {
            val matches = findMatches(parse(text), rules, gensym, evalUnquote)
            if (matches.isEmpty()) return result()
            if (iteration >= maxIterations) {
                val sample = matches.first()
                onDiagnostic(
                    "pattern-rewrite did not converge after $maxIterations iterations — a non-confluent " +
                            "rule set (e.g. a→b, b→a)? last firing rule `${sample.rule.patternText}` at " +
                            "offset ${sample.start}..${sample.end}. Stopping; rules applied so far are kept."
                )
                return result()
            }
            matches.forEach { m ->
                m.preambleBlock?.let { preambleBlocks += it }
                m.aiRequest?.let { aiRequests += it }
            }
            text = applyEdits(text, matches)
            iteration++
        }
    }

    private fun collect(file: KtFile, onDiagnostic: (String) -> Unit): Collected {
        val rules = mutableListOf<PatternRule>()
        val deletions = mutableListOf<IntRange>()
        val ruleSources = mutableListOf<String>()
        val strategyExprs = mutableListOf<KtElement>()

        file.collectDescendantsOfType<KtCallExpression>()
            .filter { it.calleeName() in RULE_OR_STRATEGY_CALLS }
            .filter { call -> !call.isQualifiedCall() }                 // not somebody's .rewrite {} method
            .filter { call -> !call.isNestedInRuleOrStrategy() }        // quote barrier: outermost only
            .forEach { call ->
                when (call.calleeName()) {
                    // A `strategy {}` control block: keep its single body expression (validated +
                    // parsed against the named-rule set later, in `expand`), and blank the block out.
                    "strategy" -> {
                        val body = call.lambdaArguments.firstOrNull()?.getLambdaExpression()?.bodyExpression
                        val expr = body?.singleMeaningfulStatement()
                        if (expr == null) {
                            onDiagnostic("strategy {} ignored — expected exactly one strategy expression, " +
                                    "e.g. `strategy { repeat(topdown(\"myRule\")) }`")
                        } else {
                            strategyExprs += expr
                        }
                        deletions += call.textRange.startOffset until call.textRange.endOffset
                    }
                    // A named rule `rule("name") { … }` or an anonymous `rewrite { … }`. Both collect
                    // off the trailing lambda; a named rule also carries its (string-literal) name so
                    // a strategy can refer to it.
                    else -> {
                        val name = if (call.calleeName() == "rule") {
                            call.valueArguments.firstOrNull()?.getArgumentExpression()
                                ?.let { stringLiteralValue(it) }
                                ?: run {
                                    onDiagnostic("rule(...) ignored — first argument must be a string-literal " +
                                            "name, e.g. `rule(\"negate\") { … }`")
                                    null
                                }
                        } else null
                        val rule = call.toPatternRule(onDiagnostic)?.copy(name = name)
                        // A `rule(...)` with no valid name is erased DSL but is not a usable rule.
                        if (rule != null && !(call.calleeName() == "rule" && name == null)) rules += rule
                        ruleSources += call.text
                        // Blank the whole call regardless (a malformed one is still erased DSL that
                        // must not reach the compiler).
                        deletions += call.textRange.startOffset until call.textRange.endOffset
                    }
                }
            }

        return Collected(rules, deletions, ruleSources, strategyExprs)
    }

    private fun stringLiteralValue(expr: KtExpression): String? {
        val tmpl = expr as? KtStringTemplateExpression ?: return null
        val sb = StringBuilder()
        for (e in tmpl.entries) {
            when (e) {
                is KtLiteralStringTemplateEntry -> sb.append(e.text)
                is KtEscapeStringTemplateEntry -> sb.append(e.unescapedValue)
                else -> return null   // interpolation ⇒ not a plain literal name
            }
        }
        return sb.toString()
    }

    private fun KtCallExpression.toPatternRule(onDiagnostic: (String) -> Unit): PatternRule? {
        // A malformed rule must never be silently dropped (that hides bugs) nor silently degenerate
        // into a too-permissive pattern (that runs away): reject with a clear diagnostic instead.
        fun reject(why: String): PatternRule? {
            onDiagnostic("rewrite rule ignored — $why: `${text.replace(Regex("\\s+"), " ").take(120)}`")
            return null
        }

        val lambda = lambdaArguments.firstOrNull()?.getLambdaExpression()
            ?: return reject("expected a trailing lambda `rewrite { … }`")
        val metavars = lambda.valueParameters.mapNotNull { p: KtParameter ->
            val name = p.name ?: return@mapNotNull null
            name to metaKindOf(p.typeReference?.text)
        }.toMap()

        val body = lambda.bodyExpression ?: return reject("empty rule body")
        val fromBody = body.callBody("from") ?: return reject("missing `from { … }`")
        val toBody = body.callBody("to") ?: return reject("missing `to { … }`")

        // A `from`/`to` that did not parse cleanly — e.g. an unsupported expression operator like
        // `|`, which leniently degenerates to a bare metavar and matches everything — is rejected
        // rather than left to run away. (`||` is a real operator and parses fine.)
        if (PsiTreeUtil.hasErrorElements(fromBody)) return reject("`from { … }` did not parse (unsupported syntax, e.g. `|`?)")
        if (PsiTreeUtil.hasErrorElements(toBody)) return reject("`to { … }` did not parse")

        val patternEl = fromBody.singleMeaningfulStatement() ?: return reject("`from { … }` must contain exactly one expression")
        val replEl = toBody.singleMeaningfulStatement() ?: return reject("`to { … }` must contain exactly one expression")

        // A pattern that is a lone metavariable matches *every* expression — including the
        // replacement it produces — so it never converges. Almost always a mis-parsed pattern.
        if ((patternEl.unwrapParens() as? KtNameReferenceExpression)?.getReferencedName() in metavars) {
            return reject("pattern is a single metavariable `${patternEl.text}`, which matches every expression")
        }

        val guard = (body.callBody("where")?.singleMeaningfulStatement() as? KtExpression)
            ?.let { parseGuard(it, metavars.keys, onDiagnostic) }
            ?: Guard.Always

        // `provide { … }` keeps its whole block (may declare several bindings).
        val provide = body.callBody("provide")

        // `ai("…")` takes a string prompt argument, not a lambda.
        val aiPrompt = body.statements.filterIsInstance<KtCallExpression>()
            .firstOrNull { it.calleeName() == "ai" }
            ?.valueArguments?.firstOrNull()?.getArgumentExpression() as? KtStringTemplateExpression

        return PatternRule(patternEl, replEl, metavars, guard, provide, aiPrompt, patternEl.text)
    }

    private val guardPredicates = setOf("distinct", "identical", "isLiteral", "isIdentifier", "isCall", "isCallTo")

    private fun parseGuard(expr: KtExpression, metavars: Set<String>, onDiagnostic: (String) -> Unit): Guard {
        return when (val e = expr.stripParens()) {
            is KtBinaryExpression -> when (e.operationReference.text) {
                "&&" -> Guard.And(
                    parseGuard(e.left ?: return fail(e, onDiagnostic), metavars, onDiagnostic),
                    parseGuard(e.right ?: return fail(e, onDiagnostic), metavars, onDiagnostic),
                )
                "||" -> Guard.Or(
                    parseGuard(e.left ?: return fail(e, onDiagnostic), metavars, onDiagnostic),
                    parseGuard(e.right ?: return fail(e, onDiagnostic), metavars, onDiagnostic),
                )
                else -> fail(e, onDiagnostic)
            }

            is KtPrefixExpression ->
                if (e.operationReference.text == "!")
                    Guard.Not(parseGuard(e.baseExpression ?: return fail(e, onDiagnostic), metavars, onDiagnostic))
                else fail(e, onDiagnostic)

            is KtCallExpression -> {
                val name = e.calleeName()
                if (name == null || name !in guardPredicates) {
                    onDiagnostic("unknown guard predicate `$name` — known: $guardPredicates. Rule will never fire.")
                    return Guard.Not(Guard.Always)
                }
                val args = e.valueArguments.mapNotNull { it.getArgumentExpression()?.text }
                // Only bare-identifier args are expected to be metavariables; string-literal args
                // (e.g. the "name" of isCallTo) are legitimately not.
                args.filter { it.matches(Regex("[A-Za-z_]\\w*")) && it !in metavars }.forEach {
                    onDiagnostic("guard `$name` references `$it`, which is not a declared metavariable")
                }
                Guard.Pred(name, args)
            }

            else -> fail(e, onDiagnostic)
        }
    }

    private fun fail(e: KtElement, onDiagnostic: (String) -> Unit): Guard {
        onDiagnostic("unrecognized guard `${e.text}` — use distinct/identical/isLiteral/isIdentifier/isCall with && || !")
        return Guard.Not(Guard.Always)   // fail-closed: the rule never fires
    }

    private fun evalGuard(g: Guard, binds: Map<String, PsiElement>): Boolean = when (g) {
        Guard.Always -> true
        is Guard.Not -> !evalGuard(g.g, binds)
        is Guard.And -> evalGuard(g.l, binds) && evalGuard(g.r, binds)
        is Guard.Or -> evalGuard(g.l, binds) || evalGuard(g.r, binds)
        is Guard.Pred -> evalPredicate(g.name, g.args, binds)
    }

    private fun evalPredicate(name: String, args: List<String>, binds: Map<String, PsiElement>): Boolean {
        fun cap(i: Int): PsiElement? = args.getOrNull(i)?.let { binds[it] }
        return when (name) {
            "distinct" -> {
                val caps = args.mapNotNull { binds[it] }
                caps.indices.all { i -> (i + 1 until caps.size).all { j -> !structurallyEqual(caps[i], caps[j]) } }
            }
            "identical" -> {
                val a = cap(0); val b = cap(1)
                a != null && b != null && structurallyEqual(a, b)
            }
            "isLiteral" -> cap(0).let { it is KtConstantExpression || it is KtStringTemplateExpression }
            "isIdentifier" -> cap(0) is KtNameReferenceExpression
            "isCall" -> cap(0)?.unwrapParens() is KtCallExpression
            "isCallTo" -> {
                val target = cap(0)?.unwrapParens() as? KtCallExpression
                val wanted = args.getOrNull(1)?.trim()?.removeSurrounding("\"")
                target != null && wanted != null && target.calleeName() == wanted
            }
            else -> false
        }
    }

    private fun findMatches(
        file: KtFile,
        rules: List<PatternRule>,
        gensym: GensymScope,
        evalUnquote: ((String) -> String?)?,
    ): List<Match> {
        val out = mutableListOf<Match>()

        fun visit(element: PsiElement) {
            // Never start a match at a parenthesized wrapper: recurse into it so the inner
            // expression is matched with its own (tighter) range, preserving the user's parens in
            // the surrounding context. Matching modulo parens still happens inside `structuralMatch`.
            if (element is KtElement && element !is KtParenthesizedExpression) {
                for (rule in rules) {
                    val binds = Bindings()
                    if (Matcher(rule.metavars).match(rule.pattern, element, binds) && evalGuard(rule.guard, binds.scalar)) {
                        out += buildMatch(element, rule, binds, gensym, evalUnquote)
                        return   // outermost-wins: do not descend into a matched subtree this round
                    }
                }
            }
            var child = element.firstChild
            while (child != null) {
                visit(child)
                child = child.nextSibling
            }
        }

        visit(file)
        return out
    }

    private fun buildMatch(
        element: KtElement,
        rule: PatternRule,
        binds: Bindings,
        gensym: GensymScope,
        evalUnquote: ((String) -> String?)?,
    ): Match {
        val replacement = substitute(rule.repl, binds, rule.metavars, gensym, hygiene = true, evalUnquote = evalUnquote)

        val preambleBlock = rule.provide?.let {
            keyedPreambleBlock(substitute(it, binds, rule.metavars, gensym, hygiene = false))
        }

        val aiRequest = rule.aiPrompt?.let { template ->
            val prompt = substitutePrompt(template, binds.scalar)
            AiRequest(stableKey(prompt), prompt, rule.repl.text)
        }

        return Match(
            element.textRange.startOffset,
            element.textRange.endOffset,
            replacement,
            rule,
            preambleBlock,
            aiRequest,
        )
    }

    private class Matcher(val metavars: Map<String, MetaKind>) {

        fun match(p: PsiElement, t: PsiElement, binds: Bindings): Boolean {
            val pp = p.unwrapParens()
            val tt = t.unwrapParens()

            val holeName = (pp as? KtNameReferenceExpression)?.getReferencedName()
            if (holeName != null && holeName in metavars) {
                val prior = binds.scalar[holeName]
                return if (prior == null) {
                    if (!kindAllows(metavars.getValue(holeName), tt)) false
                    else { binds.scalar[holeName] = tt; true }
                } else {
                    structurallyEqual(prior, tt)
                }
            }

            // Variadic holes live in argument lists: `f(args)` / `f(x, rest)`. When the pattern's
            // arg list contains a Vararg hole, match by segment (fixed prefix + one variadic run +
            // fixed suffix) instead of the fixed-arity element zip below.
            if (pp is KtValueArgumentList && tt is KtValueArgumentList &&
                pp.arguments.any { variadicHoleName(it) != null }
            ) {
                return matchArgList(pp.arguments, tt.arguments, binds)
            }

            if (pp.node?.elementType != tt.node?.elementType) return false

            val pc = pp.meaningfulChildren()
            val tc = tt.meaningfulChildren()
            if (pc.isEmpty() && tc.isEmpty()) return pp.text == tt.text   // leaf: literal / operator / keyword
            return pc.size == tc.size && pc.zip(tc).all { (a, b) -> match(a, b, binds) }
        }

        /** The Vararg-metavar name a pattern argument is a hole for, or null. */
        private fun variadicHoleName(arg: KtValueArgument): String? {
            val name = (arg.getArgumentExpression()?.unwrapParens() as? KtNameReferenceExpression)?.getReferencedName()
            return if (name != null && metavars[name] == Vararg) name else null
        }

        /** Segment-match a pattern arg list with (at most one) variadic hole against a target arg list. */
        private fun matchArgList(pArgs: List<KtValueArgument>, tArgs: List<KtValueArgument>, binds: Bindings): Boolean {
            val vIdx = pArgs.indexOfFirst { variadicHoleName(it) != null }
            if (pArgs.drop(vIdx + 1).any { variadicHoleName(it) != null }) return false   // v1: one variadic only
            val prefix = pArgs.subList(0, vIdx)
            val suffix = pArgs.subList(vIdx + 1, pArgs.size)
            if (tArgs.size < prefix.size + suffix.size) return false

            for (i in prefix.indices) if (!match(prefix[i], tArgs[i], binds)) return false
            for (i in suffix.indices) if (!match(suffix[i], tArgs[tArgs.size - suffix.size + i], binds)) return false

            val name = variadicHoleName(pArgs[vIdx])!!
            val mid = tArgs.subList(prefix.size, tArgs.size - suffix.size).toList()
            val prior = binds.variadic[name]
            return if (prior != null) {
                prior.size == mid.size && mid.indices.all { structurallyEqual(prior[it], mid[it]) }
            } else {
                binds.variadic[name] = mid; true
            }
        }

        private fun kindAllows(kind: MetaKind, node: PsiElement): Boolean = when (kind) {
            Expr -> node is KtExpression
            Ident -> node is KtNameReferenceExpression
            Stmt -> node is KtExpression || node is KtDeclaration
            TypeRef -> node is KtTypeReference
            Vararg -> false   // a variadic hole only matches inside an argument list (see matchArgList)
        }
    }

    private fun structurallyEqual(a: PsiElement, b: PsiElement): Boolean =
        Matcher(emptyMap()).match(a, b, Bindings())

    private fun firstInvalid(s: Strat): Strat.Invalid? = when (s) {
        is Strat.Invalid -> s
        is Strat.Attempt -> firstInvalid(s.s)
        is Strat.Repeat -> firstInvalid(s.s)
        is Strat.Seq -> s.list.firstNotNullOfOrNull { firstInvalid(it) }
        is Strat.Choice -> s.list.firstNotNullOfOrNull { firstInvalid(it) }
        is Strat.RuleRef, is Strat.Once, is Strat.TopDown, is Strat.BottomUp -> null
    }

    private fun parseStrat(expr: KtExpression?, ruleNames: Set<String>, onDiagnostic: (String) -> Unit): Strat {
        fun bad(why: String): Strat { onDiagnostic("strategy {} rejected — $why"); return Strat.Invalid(why) }

        // A rule reference (string literal `"name"` or bare identifier `name`), validated.
        fun ref(nameExpr: KtExpression?, ctor: (String) -> Strat): Strat {
            val name = nameExpr?.let { resolveRuleName(it) }
                ?: return bad("expected a rule name (string literal or identifier), got `${nameExpr?.text}`")
            if (name !in ruleNames) return bad("unknown rule name `$name` — declared rules: $ruleNames")
            return ctor(name)
        }

        val e = expr?.stripParens() ?: return bad("empty strategy expression")
        return when (e) {
            // `a then b` — an infix chain flattens into one sequence (fail-fast).
            is KtBinaryExpression -> if (e.operationReference.text == "then") {
                Strat.Seq(flattenThen(e, ruleNames, onDiagnostic))
            } else bad("unknown strategy operator `${e.operationReference.text}` — only `then` is infix")

            is KtCallExpression -> {
                val args = e.valueArguments.mapNotNull { it.getArgumentExpression() }
                when (e.calleeName()) {
                    "once" -> ref(args.getOrNull(0)) { Strat.Once(it) }
                    "topdown" -> ref(args.getOrNull(0)) { Strat.TopDown(it) }
                    "bottomup" -> ref(args.getOrNull(0)) { Strat.BottomUp(it) }
                    "attempt" -> Strat.Attempt(parseStrat(args.getOrNull(0), ruleNames, onDiagnostic))
                    "repeat" -> {
                        val inner = parseStrat(args.getOrNull(0), ruleNames, onDiagnostic)
                        val max = args.getOrNull(1)?.let { n ->
                            (n as? KtConstantExpression)?.text?.trim()?.toIntOrNull()
                                ?: return bad("repeat(…, n): second argument must be an integer literal, got `${n.text}`")
                        }
                        Strat.Repeat(inner, max)
                    }
                    "seq" -> Strat.Seq(args.map { parseStrat(it, ruleNames, onDiagnostic) })
                    "choice" -> Strat.Choice(args.map { parseStrat(it, ruleNames, onDiagnostic) })
                    // A call whose callee is itself a rule name is a stray `name()` — accept it as a
                    // bare reference only if the callee resolves to a known rule; otherwise reject.
                    else -> ref(e.calleeExpression) { Strat.RuleRef(it) }
                }
            }

            // Bare leaves: `"negate"` or `negate` ⇒ fire the whole rule (all outermost sites, one pass).
            is KtStringTemplateExpression, is KtNameReferenceExpression -> ref(e) { Strat.RuleRef(it) }

            else -> bad("unrecognized strategy expression `${e.text}`")
        }
    }

    private class StrategyRunner(
        val named: Map<String, PatternRule>,
        val parse: (String) -> KtFile,
        val gensym: GensymScope,
        val evalUnquote: ((String) -> String?)?,
        val preambleBlocks: MutableList<String>,
        val aiRequests: MutableList<AiRequest>,
        val onDiagnostic: (String) -> Unit,
        val maxIterations: Int,
    ) {
        fun eval(s: Strat, text: String): String? = when (s) {
            is Strat.Invalid -> null   // already diagnosed at parse time; fail-closed
            is Strat.RuleRef -> firePass(text, named.getValue(s.ruleName))
            is Strat.Once -> fireSingle(text, named.getValue(s.ruleName), deepest = false)
            is Strat.TopDown -> fireSingle(text, named.getValue(s.ruleName), deepest = false)
            is Strat.BottomUp -> fireSingle(text, named.getValue(s.ruleName), deepest = true)
            is Strat.Attempt -> eval(s.s, text) ?: text
            is Strat.Seq -> {
                var cur = text
                for (step in s.list) { cur = eval(step, cur) ?: return null }
                cur
            }
            is Strat.Choice -> s.list.firstNotNullOfOrNull { eval(it, text) }
            is Strat.Repeat -> {
                var cur = text
                var n = 0
                while (s.max == null || n < s.max) {
                    if (n >= maxIterations) {
                        onDiagnostic("strategy repeat did not converge after $maxIterations iterations " +
                                "— stopping; rewrites applied so far are kept.")
                        break
                    }
                    val next = eval(s.s, cur) ?: break        // step failed ⇒ fixpoint reached
                    if (next == cur) break                    // no textual progress ⇒ fixpoint reached
                    cur = next
                    n++
                }
                cur   // repeat never fails (0 iterations ⇒ identity success)
            }
        }

        /** Fire [rule] at every outermost non-overlapping site in one pass. Null if none matched. */
        private fun firePass(text: String, rule: PatternRule): String? {
            val matches = findMatches(parse(text), listOf(rule), gensym, evalUnquote)
            return if (matches.isEmpty()) null else apply(text, matches)
        }

        /** Fire [rule] at a single site — the deepest match if [deepest], else the outermost. */
        private fun fireSingle(text: String, rule: PatternRule, deepest: Boolean): String? {
            val match = if (deepest) {
                findDeepestMatch(parse(text), rule, gensym, evalUnquote)
            } else {
                findMatches(parse(text), listOf(rule), gensym, evalUnquote).firstOrNull()
            } ?: return null
            return apply(text, listOf(match))
        }

        private fun apply(text: String, matches: List<Match>): String {
            matches.forEach { m ->
                m.preambleBlock?.let { preambleBlocks += it }
                m.aiRequest?.let { aiRequests += it }
            }
            return applyEdits(text, matches)
        }
    }

    private fun substitute(
        repl: PsiElement,
        binds: Bindings,
        metavars: Map<String, MetaKind>,
        gensym: GensymScope,
        hygiene: Boolean,
        evalUnquote: ((String) -> String?)? = null,
    ): String {
        val base = repl.textRange.startOffset
        val edits = mutableListOf<Triple<Int, Int, String>>()   // start, end, text (relative to `base`)

        // Procedural unquote: `unquote { … }` regions run Kotlin at expansion time. Metavar captures
        // are bound as `String` vals (their source text); the block's result is spliced. The regions
        // are a substitution barrier — the ordinary metavar/gensym splices below skip inside them,
        // because the unquote handles its own metavars via the eval snippet.
        val unquoteCalls = repl.collectDescendantsOfType<KtCallExpression>()
            .filter { (it.calleeExpression as? KtNameReferenceExpression)?.getReferencedName() == "unquote" }
        val unquoteRanges = unquoteCalls.map { it.textRange.startOffset until it.textRange.endOffset }
        fun insideUnquote(offset: Int) = unquoteRanges.any { offset in it }
        unquoteCalls.forEach { call ->
            val body = call.lambdaArguments.firstOrNull()?.getLambdaExpression()?.bodyExpression?.text
                ?: return@forEach
            val spliced = when {
                // Editor preview: we don't run user code, so leave a well-typed placeholder. `TODO()`
                // has type Nothing, so it fits any expected type — the analyzer stays quiet instead
                // of choking on the erased generic `unquote {}`.
                evalUnquote == null -> "TODO()"
                // Execute: run the block; on failure emit a clear compiling stand-in (Nothing type)
                // rather than the raw `unquote {}` (which the compiler can't make sense of).
                else -> evalUnquote(buildUnquoteSnippet(binds.scalar, body))
                    ?: "error(\"rewrite unquote {} failed to evaluate — see log\")"
            }
            edits += Triple(call.textRange.startOffset - base, call.textRange.endOffset - base, spliced)
        }

        // Declaration name identifiers. A metavar in a *declaration-name* position (e.g. the `n` of
        // `var Box.n by …` in a `provide {}`) is substituted with its capture. Otherwise, under
        // hygiene, the introduced name is gensym'd so it cannot shadow/capture a spliced metavar —
        // a fresh name unique to this expansion.
        val renames = HashMap<String, String>()
        repl.forEachDescendantOfType<KtNamedDeclaration> { decl ->
            // Skip anonymous nodes like the KtFunctionLiteral of a lambda (a KtNamedDeclaration with
            // no nameIdentifier) — processing it would burn a fresh-name counter value for nothing.
            val id = decl.nameIdentifier ?: return@forEachDescendantOfType
            if (insideUnquote(id.textRange.startOffset)) return@forEachDescendantOfType
            val name = decl.name ?: return@forEachDescendantOfType
            val text = when {
                binds.scalar.containsKey(name) -> renderCapture(binds.scalar.getValue(name))   // metavar-named decl
                hygiene -> renames.getOrPut(name) { gensym.fresh(name) }                       // hygienic rename
                else -> return@forEachDescendantOfType                                          // box-level name, kept
            }
            edits += Triple(id.textRange.startOffset - base, id.textRange.endOffset - base, text)
        }

        repl.forEachDescendantOfType<KtNameReferenceExpression> { ref ->
            if (insideUnquote(ref.textRange.startOffset)) return@forEachDescendantOfType
            val name = ref.getReferencedName()
            val text = when {
                binds.scalar.containsKey(name) -> renderCapture(binds.scalar.getValue(name))          // scalar hole
                binds.variadic.containsKey(name) -> binds.variadic.getValue(name).joinToString(", ") { it.text }  // variadic run
                name in renames -> renames.getValue(name)                                             // gensym'd local ref
                else -> return@forEachDescendantOfType                                                // free reference, untouched
            }
            edits += Triple(ref.textRange.startOffset - base, ref.textRange.endOffset - base, text)
        }

        var out = repl.text
        edits.sortedByDescending { it.first }.forEach { (start, end, text) -> out = out.replaceRange(start, end, text) }
        return out
    }