ADFA-5231: Gate the resolution-side KtFile door and record ADR 0015

[itsaky-adfa]

Stack 5 of 5 for ADFA-5231. Closes the last hole in the compile-time gate and records the decision.

Why this layer exists

The earlier PRs made the raw accessors private, but the gate did not actually hold inside the module. KtSymbolIndex.getKtFile was plain internal and returns the live instance for an open path, and analyzeMaybeDangling is plain internal inline. So anywhere in lsp/kotlin - including its test source set, and including wherever the next refactor lands - this compiled with no diagnostic:

val f = env.ktSymbolIndex.getKtFile(path)!!
analyzeMaybeDangling(f, AnalysisPriority.COMMAND, checker) { /* ... */ }

and reintroduced the bug. That is a literal description of how ADFA-3322 undid ADFA-4165's fix, so leaving it open would have meant shipping a fix whose headline claim was false.

Both getKtFile overloads now carry @RequiresOptIn(ERROR) ResolutionSideKtFileAccess, with @OptIn at the three service providers that legitimately need the resolution-side door (DeclarationsProvider, AnnotationsResolver, DirectInheritorsProvider), one internal use, and five test sites. @OptIn is on the narrowest scope that works, so every exemption stays visible in review.

Verified rather than asserted: an un-opted-in version of the snippet above now fails compilation with the marker error at the getKtFile acquisition. Checked twice, independently, with the probe file removed and the module recompiled clean each time.

Note: most of the line count in the three provider files is Spotless reformatting. Each gained one annotation, which pulled the whole file under the file-level ratchet. git diff -w on those files is ~20 lines of real change. They are isolated in this PR precisely so that noise stays out of the substantive layers.

ADR 0015

Records the invariant, its history, and the consequences - the point being that ADFA-4165's fix was a property maintained by code, so a refactor undid it, whereas this one is carried by types. It also records honestly what the design costs: the cross-request staleness window, the three ways staleness is handled (edit sites refuse, diagnostics discards and reschedules, navigation tolerates), the partial escape guard, and the known follow-ups. Alternatives considered - a runtime check, one mutable KtFile per path reparsed in place, a lint rule - each with why it was not taken.

Two corrections to claims elsewhere in the codebase are included: KtFileExts's "all Analysis API access must go through this helper" is now structural for an open file, and the "only route to a live KtFile" claim is qualified, because the modified-file indexer does analyse one unpinned (a tracked follow-up).

Testing

461 tests, 0 failures. Compile clean.

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review for a one-time review, or @claude review always to subscribe this PR to a review on every future push.

_{Tip: disable this comment in your organization's Code Review settings.}

[jatezzz]

@itsaky-adfa The gate has an un-marked back door, so the headline claim does not hold.

@OptIn(ResolutionSideKtFileAccess::class) on DeclarationProvider.ktFilesForPackage (line 180) only covers the protected producer. AbstractDeclarationProvider re-exports those same live instances through public interface overrides: findFilesForFacadeByPackage (91), findFilesForFacade (78), findFilesForScript (94), getTopLevelCallableFiles (118).

DeclarationProvider is internal with an internal constructor, and project.createDeclarationProvider(scope, null) is already used in this module, so anywhere in lsp/kotlin — test source set included — this compiles with no diagnostic and reintroduces exactly the ADFA-3322 shape:

val f = project.createDeclarationProvider(scope, null)
	.findFilesForFacadeByPackage(FqName("p")).first()
analyzeMaybeDangling(f, AnalysisPriority.COMMAND, checker) { /* ... */ }

FIR then sees every top-level declaration twice — the regression this PR exists to prevent.

AnnotationsResolver.declarationsByAnnotation is the same class of hole one hop out: it returns KtAnnotated PSI, and .containingKtFile is the live instance.

Marking AbstractDeclarationProvider itself, or those four public overrides, would close it.

[jatezzz]

@itsaky-adfa This consequence overclaims what the gate enforces.

code that reaches for a live KtFile outside withLiveKtFile / withLiveKtFileAsync does not compile without an explicit @OptIn on one of the two markers

Falsified by the unmarked public overrides on AbstractDeclarationProvider (findFilesForFacadeByPackage, findFilesForFacade, findFilesForScript, getTopLevelCallableFiles) — see the comment on DeclarationsProvider.kt. That route compiles clean anywhere in lsp/kotlin.

Since this ADR is the record future refactors will trust, the overclaim is precisely the risk the PR set out to remove: someone reads this guarantee, takes a KtFile off the declaration provider, analyses it, and gets no compiler error and no review signal.

Either name the declaration-provider re-export as a third known exception alongside the modified-file indexer, or widen the gate so the claim is true.