[Bulk index][Dart] Export analyzer AnalysisSession snapshots atomically

[samchon]

Outcome

Add one versioned custom request inside the resident Dart Analysis Server that
walks its existing AnalysisDriver/AnalysisSession state and streams
whole-generation or changed-library shards. Use a public package:analyzer
sidecar only as the prototype/batch fallback. Remove all declaration-by-
declaration reference queries from the final path.

Fact-checked timing baseline

PR #147 measured dart-http with a 1,800-second guard:

• the strict cell first attempted scip-dart, later entered generic LSP work,
  and was terminated while textDocument/references was active;
• the strict-off cell was terminated in the same generic phase.

The publication proves that neither end-to-end cell finished within 30 minutes.
It does not isolate scip-dart's duration and does not report eventual
completion.

The separate five-minute diagnosis disabled strict providers. Analysis Server
initialization took 0.030 s; all 324 document-symbol calls completed in 0.485 s
total; 1,204 reference calls started, 1,188 completed and 16 remained in flight.
Completed calls accumulated 533.410 s of server time, with one taking 249.253 s.
This proves generic fan-out is pathological, not that analysis itself requires
30 minutes.

Current master can defend no edge families from scip-dart under the common
grounding rules.

Why the analyzer already has the needed truth

AnalysisSession is a consistent view of analyzer results. Its APIs fail with
InconsistentAnalysisException when a result may conflict with an earlier
result in the same session. Resolved units/libraries contain typed AST,
elements, calls, types, diagnostics and source ranges.

AnalysisContext already applies file changes and creates a new current
session. The Analysis Server owns multiple contexts, package configuration,
analysis options, experiments, overlays, scheduler and byte/result caches.

A public AnalysisContextCollection sidecar can prove the traversal, but its
public constructor does not expose every server configuration/cache control.
Depending on package:analyzer/src would pin unstable internals and duplicate
the server's analysis. The fastest final route is a custom Analysis Server
request executed where those internals already live.

Analyzer plugin APIs are not a substitute: they focus on diagnostics/fixes/
assists and do not provide an arbitrary whole-workspace semantic export with
the server's generation transaction.

Decision: pinned Analysis Server request

Add samchon/graphSnapshot to a pinned Dart SDK/Analysis Server fork or upstream
extension:

1. capture the server's context roots, overlays and configuration generation;
2. for each context, capture its current AnalysisSession;
3. enumerate analyzed project libraries/files once;
4. resolve/walk each library/unit once and emit changed library/source shards;
5. preserve parts/augmentations/generated origins;
6. compute pre/post source/config/package hashes across contexts; and
7. commit only when every session stayed internally consistent and the
   cross-context fence still matches.

One session protects reads inside a context; the pre/post manifest fence is
still required across several contexts.

The request streams #63's protocol and supports cancellation. A compatibility
handshake reports SDK/analyzer/exporter commit/schema. Unknown internals decline
to the public sidecar/scip/LSP fallback.

Fact extraction

Resolved AST and element model can prove:

• libraries, fragments, parts/augmentations, classes/mixins/enums/extensions/
  extension types, functions, methods, constructors, fields/properties,
  parameters, locals and type aliases;
• imports/exports, prefixes, deferred imports and show/hide combinators;
• resolved method/function invocations and constructor creation;
• reads/writes and type references;
• direct superclass, interfaces, mixins and overrides;
• metadata annotations with resolved element/constant value;
• references and diagnostics; and
• Flutter renders and package:test/testWidgets facts only through named
  framework enrichers.

Dart methods are virtual by default. The statically resolved declaration is a
call edge, not necessarily runtime implementation. final, base, sealed
and library-closed analysis can sometimes prove a closed target/candidate set.
Emit exact dispatches only when one runtime target is proven; otherwise store
candidates/unresolved.

Dynamic invocation, noSuchMethod, mirrors, FFI/native boundaries, generated
code not loaded in the context and conditional imports outside the selected
configuration remain explicit coverage gaps.

Identity

Do not persist Element.id; it is process-local. ElementLocation is no
longer the public stable route after Element2.

Use:

library URI + fragment/semantic owner chain + lookupName + declaration kind + structural signature where needed.

Rules:

• collapse substituted views through the base/original element;
• parts and augmentations share the semantic element but retain all fragments/
  declaration spans;
• library-private names are namespaced by library URI;
• accessors/operators use canonical lookup names;
• locals include source/owner lexical structure;
• synthetic elements retain origin; and
• unnamed extensions require a content/structure-derived stable key, not a raw
  offset or an ordinal that changes after unrelated insertions. If that cannot
  be proven, report identity-unstable.

Dart has no overloads, but unnamed extensions, augmentations and generated
fragments are mandatory identity fixtures.

Universe and incremental behavior

The universe includes Dart SDK/analyzer/exporter commit, package config and
lock, workspace/context roots, analysis options/includes, experiments, language
versions, declared variables, platform/conditional imports, generated sources
and overlays.

• no-op: Analysis Server returns prior manifest without re-walking libraries;
• edit: AnalysisDriver invalidates affected libraries; export only their
  shards;
• public API/package/options/experiment change: export the analyzer's dependent
  closure or new context universe;
• create/delete/rename: explicit shard changes;
• inconsistent session, analysis error, cancel or server crash: no mixed
  commit.

Cold overhead is compared with the same Analysis Server workspace analysis.
Target no-op p95 below 250 ms and body edit below 2 s on the pinned corpus.
Do not query LSP references per declaration.

Implementation map

1. Add [Bulk index] Replace symbol-by-symbol LSP scans with compiler-owned snapshots #63's shard/coverage contract.
2. Implement a public package:analyzer batch prototype to freeze exact graph
   semantics and identities.
3. Move the same traversal into a pinned Analysis Server request and compare
   byte-equivalent normalized output.
4. Add the resident provider ahead of scip-dart only after multi-context and
   overlay fencing passes.
5. Retain the public sidecar, scip-dart and generic/static paths as explicit
   fallbacks.
6. Add phase-separated dart-http cold/no-op/edit measurement.

Acceptance

• Exact fixtures cover packages/workspaces, parts, augmentations, unnamed/
  named extensions, extension types, mixins, sealed/final/base hierarchies,
  generics, async, constructors, accesses, annotations, conditional imports,
  code generation, Flutter and tests.
• One request walks each analyzed unit/library once; no per-symbol LSP
  references occur.
• Per-context AnalysisSession consistency and cross-context manifest
  fencing are both proven.
• Persistent identities never use process-local Element.id or raw offset
  alone.
• All 15 fact families have explicit coverage/unresolved rows.
• No-op, body/API edit, create/delete/rename, package/options/experiment/
  SDK/context change, diagnostic, inconsistency, cancel, crash and retry are
  atomic.
• Cold time is compared with native Analysis Server analysis; no-op/edit
  phases are measured separately.
• Linux/macOS/Windows SDK selection and exact handshake are proven.
• Public analyzer/scip-dart/generic/static remain truthful fallbacks.
• Focused tests, Dart experiment, pnpm build, pnpm test, and
  pnpm coverage pass.

Primary references

• Dart analyzer AnalysisContextCollection
• Dart analyzer result model
• Dart SDK / Analysis Server
• Analyzer performance guidance
• scip-dart

[samchon]

Provider recon at graph 71e35af. Dart is the strongest provider in the whole campaign, and this issue's "do not fork the SDK as the first move" is right. Two corrections and one concrete win.

The analyzer enforces the fence for us

This issue asks for atomic snapshot export. The analyzer already provides the primitive, and it is stricter than anything else in the campaign.

AnalysisSession is documented as "A consistent view of the results of analyzing one or more files", and:

"The methods in this class that return analysis results will throw an InconsistentAnalysisException if the result to be returned might be inconsistent with any previously returned results."

The session object is the generation token, and mixed-generation reads fail loudly rather than silently. No other language in the campaign gets that for free — Swift needs an explicitly-named unit set, the SCIP lane gets nothing at all.

But this issue is still right to require hashes. InconsistentAnalysisException is per-session, so it does not by itself prevent a mixed generation across contexts. The pre/post source/config hash fence remains necessary for the multi-context case. That gap is real, and the issue anticipated it correctly.

AnalysisContext gives the incremental loop: changeFile(String path) ("Schedules the file with the [path] to be read before producing new analysis results") → applyPendingFileChanges() ("Return a [Future] that completes after pending file changes are applied, so that [currentSession] can be used to compute results") → new currentSession. That is genuine semantic-incremental, with no custom resident analyzer to build — unlike C# (MSBuildWorkspace) or Kotlin (Analysis API).

Note: sdkVersionConstraint is not on the current abstract AnalysisContext.

Correction 1: "strictly public API" is not achievable as scoped

analyzer 14.1.0 (SDK ^3.11.0). The public factory has only three parameters:

AnalysisContextCollection({
  required List<String> includedPaths,
  ResourceProvider? resourceProvider,
  String? sdkPath,
})

excludedPaths, packageConfigFile, optionsFile, enabledExperiments, byteStore, fileContentCache, performanceLog, scheduler, enableIndex, withFineDependencies, drainStreams, sdkSummaryPath exist only on AnalysisContextCollectionImpl in lib/src/… — not public API.

This issue asks for package config, experiments, and excluded paths. A strictly-public sidecar cannot set them (exclusion would have to come from analysis_options.yaml). Requested amendment: either accept the src/ dependency with a fail-closed version handshake, or narrow the claim to what the three-parameter factory supports. As written the issue promises both and can only have one.

The same tension appears for overrides: computing them correctly wants InheritanceManager3, which also lives in src/. (The @override annotation is not authority — it is optional and unchecked across libraries.)

Correction 2: ElementLocation is gone

ElementLocation no longer exists in analyzer 14 — removed in the Element2 migration. What remains is Element.id, documented as "The unique integer identifier of this element" — but it is process-local and not stable across sessions or runs, so it cannot be the persistent id.

Identity must be synthesized from library.uri + fragment chain + lookupName + kind. Useful pieces: Element.baseElement ("the non-SubstitutedElementImpl version" — use it to collapse generic substitution views), lookupName (setters get a trailing =; unary minus becomes unary-), firstFragment/fragments/Fragment.nextFragment, isPrivate/isPublic, library, LibraryElement.identifier/uri.

Identity notes (feeds #65):

• Dart has no overloads — the easiest identity story in the campaign, and immune to the ordinal-disambiguator problem afflicting Java/C#/Kotlin.
• Library-private _foo is disambiguated by library URI.
• Parts and augmentations merge into one element via the fragment chain — key on the element, not the fragment.
• Synthetic accessors are flagged.
• Concrete gap: unnamed extensions have name == null. The only discriminator is a declaration offset, which breaks position-invariance. Needs an explicit rule — e.g. a stable per-library ordinal. Unresolved against [Bulk index] Introduce overload-safe provider-native symbol identities #65.

The concrete win: Dart 3 class modifiers make dispatches exact

Dart methods are virtual by default, so static resolution names the declaration, not the executed target — dispatches is candidate-only in general, requiring the overrider closure.

But final, base, and sealed let the sidecar prove no external overriders exist. For those hierarchies dispatches is exact, not conservative. That is the only place in the entire campaign where dispatch is provable, and it is worth encoding explicitly in the acceptance rows rather than treating all Dart dispatch as candidate-only.

Edge kinds — nearly everything proven directly

Proven: contains (element/fragment tree), exports (export directives + show/hide combinators), imports (directives, prefixes, deferred), calls (MethodInvocation.methodName.element, FunctionExpressionInvocation), accesses (resolved identifiers; read/write via AssignmentExpression), instantiates (InstanceCreationExpression.constructorName.element), type_ref (NamedType.element / resolved DartType), extends (InterfaceElement.supertype), implements (interfaces + mixins), references.

decorates is proven and strong — Element.metadata / ElementAnnotation.element + computeConstantValue(). The best decorator story in the campaign (json_serializable, Flutter). Compare: SCIP cannot prove decorates for any language (see the #69 comment).

overrides proven, but wants InheritanceManager3 (see Correction 1).

Enrichment, and must be audited as convention rather than language fact: renders (Flutter — an InstanceCreationExpression of a Widget subtype inside Widget.build()), tests (test()/testWidgets() from package:test; test→subject not proven).

Output surface

AnalysisSession: getResolvedUnit, getResolvedLibrary, getResolvedLibraryByElement, getParsedUnit, getParsedLibrary, getFile, getErrors, getUnitElement, getLibraryByUri; properties analysisContext, declaredVariables, resourceProvider, uriConverter. Full resolved AST + element model + types + diagnostics + ranges. Enumeration via ContextRoot.analyzedFiles(). contextFor(String path) throws StateError if unanalyzed; all paths must be absolute and normalized.

Prep: dart pub get for the sidecar's own deps; the target project also needs a resolved package_config.json.

Authority

CAN claim: compiler-front-end-resolved facts — the same element model dart analyze uses — from one consistent AnalysisSession per context per generation, with InconsistentAnalysisException as an enforced fence.

CANNOT claim: cross-context atomicity without the hash fence; virtual dispatch targets outside final/base/sealed hierarchies; renders/tests as anything but framework conventions; strictly-public-API purity if excludedPaths/packageConfigFile/experiments are needed; dart:ffi/noSuchMethod/mirrors dynamism.

The classic protocol (navigation/occurrences/outline/overrides) remains a useful comparison oracle, not the authority — this issue's stance is upheld.

Verdict

Sidecar on public package:analyzer — strongest of the campaign, no fork. Invariant 6 is satisfiable: the Dart sidecar is a directly spawned child.

Full recon: .wiki/bulk-index-providers/recon-swift-zig-lua-dart.md.