@hydranium/core 1.0.0-next.28 → 1.0.0-next.280

package/src/langium/bootstrap.ts

@@ -10,17 +10,20 @@
 import { type Logger } from '@hydranium/protocol';
 import { type LangiumSharedCoreServices } from '@hydranium/langium';
 import { type LangiumServices, type LangiumSharedServices } from '@hydranium/langium/lsp';
-import type { ServerSharedServicesMinimal } from './shared-services.js';
+import type { ServerSharedServices } from './module.js';
 import { collectProducibleTypes } from './language-types.js';
-import { AstDocumentManager } from '../documents/ast-document-manager.js';
+import { assertSingleLangiumCopy } from './single-langium-copy.js';
+import { DefaultAstDocumentManager } from '../documents/ast-document-manager.js';
 import { HydraniumTextDocuments } from '../documents/hydranium-text-documents.js';
-import { BuildPipelineIntegration } from './document-builder/build-pipeline-integration.js';
+import { DefaultBuildPipelineIntegration } from './document-builder/build-pipeline-integration.js';
 import { HydraniumDocumentBuilder } from './document-builder/document-builder.js';
-import { ModelService } from './model-service/model-service.js';
+import { DefaultModelService } from './model-service/model-service.js';
 import { HydraniumScopeComputation } from './scope/hydranium-scope-computation.js';
 import { HydraniumScopeProvider } from './scope/hydranium-scope-provider.js';
 import { processEnv } from '../util/environment.js';
-import { TransferEncoder } from './transfer/transfer-encoder.js';
+import { DefaultTransferEncoder } from './transfer/transfer-encoder.js';
+import { HydraniumLangiumDocumentFactory } from './workspace/hydranium-langium-document-factory.js';
+import { HydraniumLangiumDocuments } from './workspace/langium-documents.js';
 import { HydraniumWorkspaceManager } from './workspace/hydranium-workspace-manager.js';
 
 /**
@@ -73,7 +76,14 @@ const EXPECTED_SHARED_SLOTS: readonly ExpectedSlot[] = [
       side: 'shared',
       path: 'workspace.BuildPipelineIntegration',
       get: services => nested(services, 'workspace', 'BuildPipelineIntegration')
-   }
+   },
+   // Unbound, this fails where the cause is least visible: the render pass runs
+   // inside the `Validated` phase, so a `TypeError` there propagates out of
+   // `notifyDocumentPhase` and the document reaches `Validated` with Langium's
+   // publisher never invoked — the client receives no diagnostics for the file
+   // and the stack names the document builder.
+   { side: 'shared', path: 'MessageRenderer', get: services => nested(services, 'MessageRenderer') },
+   { side: 'shared', path: 'ServerLocale', get: services => nested(services, 'ServerLocale') }
 ];
 
 /**
@@ -184,6 +194,20 @@ interface StrictSlot {
 
 const STRICT_SHARED_SLOTS: readonly StrictSlot[] = [
    { side: 'shared', path: 'workspace.TextDocuments', base: HydraniumTextDocuments, get: s => nested(s, 'workspace', 'TextDocuments') },
+   // Every root it builds records no version, so every write gated on one conflicts.
+   {
+      side: 'shared',
+      path: 'workspace.LangiumDocumentFactory',
+      base: HydraniumLangiumDocumentFactory,
+      get: s => nested(s, 'workspace', 'LangiumDocumentFactory')
+   },
+   // It reports no registered root, so none is reconciled with the text store or announced.
+   {
+      side: 'shared',
+      path: 'workspace.LangiumDocuments',
+      base: HydraniumLangiumDocuments,
+      get: s => nested(s, 'workspace', 'LangiumDocuments')
+   },
    {
       side: 'shared',
       path: 'workspace.WorkspaceManager',
@@ -199,17 +223,17 @@ const STRICT_SHARED_SLOTS: readonly StrictSlot[] = [
    {
       side: 'shared',
       path: 'workspace.AstDocumentManager',
-      base: AstDocumentManager,
+      base: DefaultAstDocumentManager,
       get: s => nested(s, 'workspace', 'AstDocumentManager')
    },
    {
       side: 'shared',
       path: 'workspace.BuildPipelineIntegration',
-      base: BuildPipelineIntegration,
+      base: DefaultBuildPipelineIntegration,
       get: s => nested(s, 'workspace', 'BuildPipelineIntegration')
    },
-   { side: 'shared', path: 'model.TransferEncoder', base: TransferEncoder, get: s => nested(s, 'model', 'TransferEncoder') },
-   { side: 'shared', path: 'model.ModelService', base: ModelService, get: s => nested(s, 'model', 'ModelService') }
+   { side: 'shared', path: 'model.TransferEncoder', base: DefaultTransferEncoder, get: s => nested(s, 'model', 'TransferEncoder') },
+   { side: 'shared', path: 'model.ModelService', base: DefaultModelService, get: s => nested(s, 'model', 'ModelService') }
 ];
 
 const STRICT_LANGUAGE_SLOTS: readonly StrictSlot[] = [
@@ -287,31 +311,40 @@ export function warnOnUnexpectedBindings(shared: LangiumSharedServices, language
  *   dispatch every build-phase pass and drive AST enrichment, and
  *   registers the framework integrity passes itself. The per-language
  *   feature services it routes to (`ast.AstExtensionService` +
- *   `integrity.IntegrityService`, plus `references.ScopeExtensionService`
- *   read by the scope provider) hold the registries and the logic but own
+ *   `integrity.IntegrityService`) hold the registries and the logic but own
  *   no listeners, so they need not be eager: each language's services
- *   construct lazily when the orchestrator (or scope provider) first
- *   reaches them, and their constructors register that language's rules /
- *   extensions just-in-time.
- * - **`profilers.LangiumProfiler`** — self-registers a `Validated`
- *   BuildPhasePass that flushes the aggregated parse/link/validate profile
- *   once per build. No production cost (the profiler is trace-gated), but
- *   the pass must be registered up front.
+ *   construct lazily when the orchestrator first reaches them, and their
+ *   constructors register that language's rules / extensions just-in-time.
+ *   `references.ScopeExtensionService`, read by the scope provider, does
+ *   subscribe to the builder, but only to report its own calls, so
+ *   constructing it at its first call misses none.
+ * - **`profilers.LangiumProfiler`** — subscribes to
+ *   `documentBuilder.onBuildEnded` to flush the aggregated
+ *   parse/link/validate profile once per build. No production cost (the
+ *   profiler is trace-gated), but the listener must be attached before the
+ *   first build ends.
  * - **`workspace.CstResidencyService`** — self-registers a `Validated`
  *   BuildPhasePass that sheds the CST of closed documents. The framework
  *   default strategy is `always-keep`, so the pass runs but sheds nothing
  *   until an adopter configures a shedding strategy.
+ * - **`workspace.AstDocumentManager`** — subscribes to the build pipeline
+ *   and the text store to track opens, deletions and each build's causes.
+ * - **`model.ModelService`** — subscribes to the settled document phase to
+ *   bring the language client up to date. A tree without an LSP `initialize`,
+ *   such as a headless init, may not resolve it before the first build.
  *
  * Consumers with no additional eager targets can omit the third argument
  * to {@link bootstrapLangium} — the parameter default is this exact set.
  * Adopters needing extra eager targets spread this constant into their own
  * array and append their accessors.
  */
-export const DEFAULT_EAGER_SERVICES: ReadonlyArray<(services: ServerSharedServicesMinimal) => unknown> = [
+export const DEFAULT_EAGER_SERVICES: ReadonlyArray<(services: ServerSharedServices) => unknown> = [
    services => services.workspace.ProjectManager,
    services => services.workspace.BuildPipelineIntegration,
    services => services.profilers.LangiumProfiler,
-   services => services.workspace.CstResidencyService
+   services => services.workspace.CstResidencyService,
+   services => services.workspace.AstDocumentManager,
+   services => services.model.ModelService
 ];
 
 /**
@@ -329,36 +362,39 @@ export const DEFAULT_EAGER_SERVICES: ReadonlyArray<(services: ServerSharedServic
  * discarded.
  *
  * Bootstrap responsibilities, in order:
- *  1. Hand the shared services to `shared.ServiceRegistry` if it accepts
+ *  1. {@link assertSingleLangiumCopy} — fail fast when the shared
+ *     `AstReflection` is built on a second copy of `langium`, before any
+ *     later check can fail first and name the wrong cause.
+ *  2. Hand the shared services to `shared.ServiceRegistry` if it accepts
  *     them after construction, so Langium's declared-languageId lookup
  *     rung works however the adopter's registry binding was built.
- *  2. {@link assertDistinctFileRouting} — before registration, because
+ *  3. {@link assertDistinctFileRouting} — before registration, because
  *     `register` resolves a routing collision by last-wins and afterwards
  *     the evidence is gone.
- *  3. Register `language` against `shared.ServiceRegistry`, the
+ *  4. Register `language` against `shared.ServiceRegistry`, the
  *     required final step of any Langium DI bootstrap. Done before slot
  *     validation so subclassed registries (typed-accessor extensions)
  *     populate any side state before validation walks construct services
  *     that read from the registry.
- *  4. {@link assertCoreSlotsBound} — fail fast if the consumer's
+ *  5. {@link assertCoreSlotsBound} — fail fast if the consumer's
  *     `inject(...)` composition is missing a `@hydranium/core` module. May
  *     trigger lazy service construction as side effect of walking the
  *     slots; that construction expects a populated `ServiceRegistry`,
  *     hence the order.
- *  5. {@link warnOnUnexpectedBindings} — opt-in (gated by
+ *  6. {@link warnOnUnexpectedBindings} — opt-in (gated by
  *     {@link STRICT_BINDINGS_ENV}); warns when a framework slot is bound
  *     to a non-subclass of its framework base. No-op unless the env is set.
- *  6. {@link assertReflectionCoversLanguages} — catch a clobbered shared
+ *  7. {@link assertReflectionCoversLanguages} — catch a clobbered shared
  *     `AstReflection` before it starts silently answering `isSubtype`
  *     false for a registered language's types. Skipped here, since a lone
  *     language has no sibling that could clobber it.
- *  7. Invoke eager-construction accessors in array order.
+ *  8. Invoke eager-construction accessors in array order.
  *
  * Multi-grammar adopters use {@link bootstrapLangiumLanguages}, which
  * registers every language before validating slots or constructing the
  * eager set.
  */
-export function bootstrapLangium<TShared extends LangiumSharedServices & ServerSharedServicesMinimal, TLang extends LangiumServices>(
+export function bootstrapLangium<TShared extends LangiumSharedServices & ServerSharedServices, TLang extends LangiumServices>(
    shared: TShared,
    language: TLang,
    eagerlyConstructedServices: ReadonlyArray<(services: TShared) => unknown> = DEFAULT_EAGER_SERVICES
@@ -377,32 +413,32 @@ export function bootstrapLangium<TShared extends LangiumSharedServices & ServerS
  * ORDER across languages is what makes this a distinct function rather
  * than a loop the caller could write:
  *
- *  1. **Every** language is registered against `shared.ServiceRegistry`
- *     first. Slot validation and eager construction both build services
+ *  1. {@link assertSingleLangiumCopy} runs **once**, before anything else,
+ *     since every language shares the one `AstReflection`.
+ *  2. **Every** language is registered against `shared.ServiceRegistry`
+ *     next. Slot validation and eager construction both build services
  *     that read the registry — a per-language
  *     register-then-validate-then-eager loop would run them while later
  *     languages were still missing, so a shared service that walks
  *     `ServiceRegistry.all` (or resolves by extension) would see a
  *     half-populated registry and cache the wrong answer.
- *  2. `assertCoreSlotsBound` / `warnOnUnexpectedBindings` per language —
+ *  3. `assertCoreSlotsBound` / `warnOnUnexpectedBindings` per language —
  *     each language composes its own module chain, so each is checked.
- *  3. Eager accessors run **once**, after all registrations. They take
- *     the shared tier, and the framework's eager set is shared-tier only
- *     (`ProjectManager`, `BuildPipelineIntegration`, `LangiumProfiler`,
- *     `CstResidencyService`) — `BuildPipelineIntegration` in particular
- *     routes per document URI to each language's `IntegrityService` /
- *     `AstExtensionService`, so it must be constructed knowing all of
- *     them. Running the set per language would attach its
- *     `documentBuilder` listeners N times and enforce each phase N times.
+ *  4. {@link assertReflectionCoversLanguages} runs **once**, on the one
+ *     shared `AstReflection`.
+ *  5. Eager accessors run **once**, after all registrations. They take
+ *     the shared tier, and the framework's eager set is shared-tier only —
+ *     `BuildPipelineIntegration` in particular routes per document URI to
+ *     each language's `IntegrityService` / `AstExtensionService`, so it
+ *     must be constructed knowing all of them. Running the set per language
+ *     would attach its `documentBuilder` listeners N times and enforce each
+ *     phase N times.
  *
  * Throws when `languages` is empty: a shared tier with no registered
  * language never validates its slots, which silently defers a
  * composition error to the first build.
  */
-export function bootstrapLangiumLanguages<
-   TShared extends LangiumSharedServices & ServerSharedServicesMinimal,
-   TLang extends LangiumServices
->(
+export function bootstrapLangiumLanguages<TShared extends LangiumSharedServices & ServerSharedServices, TLang extends LangiumServices>(
    shared: TShared,
    languages: ReadonlyArray<TLang>,
    eagerlyConstructedServices: ReadonlyArray<(services: TShared) => unknown> = DEFAULT_EAGER_SERVICES
@@ -414,6 +450,11 @@ export function bootstrapLangiumLanguages<
             '`inject(...)` composition.'
       );
    }
+   // First, because a second copy of `langium` can make a later check fail
+   // first and name the wrong cause.
+   if (shared.AstReflection) {
+      assertSingleLangiumCopy(shared.AstReflection);
+   }
    // Back-fill the shared services onto a registry that was constructed
    // without them, so Langium's declared-languageId lookup rung works no
    // matter how the adopter's `ServiceRegistry` binding built it. An adopter
@@ -521,11 +562,11 @@ export function assertDistinctFileRouting(languages: ReadonlyArray<LangiumServic
  *
  * The check is per language, on the types its grammar can produce, and costs
  * one grammar walk per language at boot; a single-language composition, which
- * nothing can clobber, is skipped entirely. It cannot repair the situation — a
- * reflection that spans independently generated grammars is a real design piece
- * (a composite reflection dispatching per owning language) and is not attempted
- * here; the point is to turn a silent runtime misbehaviour into a boot failure
- * that names the language and the mistake.
+ * nothing can clobber, is skipped entirely. It cannot repair the situation, since
+ * the losing reflection is already gone; the point is to turn a silent runtime
+ * misbehaviour into a boot failure that names the language and the mistake. The
+ * repair is the adopter's: bind a `CompositeAstReflection` over every package's
+ * generated reflection, or generate all grammars in one `langium-cli` run.
  *
  * **Two severities, because a clobber is not always total.** Throwing only when
  * NONE of a language's types are known misses the realistic case: two grammars
@@ -567,8 +608,9 @@ export function assertReflectionCoversLanguages(shared: LangiumSharedServices, l
          `[hydranium] the shared AstReflection knows NONE of the ${produced.size} types the language ` +
             `'${languageId}' can produce (e.g. ${missing.slice(0, 3).join(', ')}). ` +
             'AstReflection is a single shared slot, so composing two independently generated language ' +
-            'packages leaves only the last one bound. Generate all grammars in ONE langium-cli run (one ' +
-            'langium-config with several entry grammars) so a single combined reflection covers them all.'
+            "packages leaves only the last one bound. Bind a CompositeAstReflection over every package's " +
+            'generated reflection, or generate all grammars in ONE langium-cli run (one langium-config with ' +
+            'several entry grammars) so a single combined reflection covers them all.'
       );
    }
 }
@@ -590,7 +632,8 @@ function warnPartialReflectionCoverage(
       'For those types `isSubtype` answers false and `getTypeMetaData` is empty, so `IndexManager.allElements` ' +
       'finds nothing, reference routing misses, and the encoder emits nothing. Most likely two independently ' +
       'generated language packages each bound the single shared AstReflection slot and the last one won — ' +
-      'generate all grammars in ONE langium-cli run so a single combined reflection covers them. If instead ' +
+      "bind a CompositeAstReflection over every package's generated reflection, or generate all grammars in " +
+      'ONE langium-cli run so a single combined reflection covers them. If instead ' +
       'these are rules your generator legitimately folded away, this warning is expected.';
    if (logger) {
       logger.warn(message);

package/src/langium/build-phase-pass/build-phase-pass-service.ts

@@ -27,7 +27,7 @@ import { type BuildPhasePass, type BuildPhasePassRegistry } from './build-phase-
  * per-language work (integrity) fans out by language *inside* its pass. This
  * also keeps one priority space per phase across framework and adopter passes,
  * which is the point — `runPasses` orders the framework's integrity and
- * profiler-flush passes against adopter passes deterministically.
+ * CST-residency passes against adopter passes deterministically.
  */
 export interface BuildPhasePassService extends BuildPhasePassRegistry {
    /**

package/src/langium/build-phase-pass/build-phase-pass.ts

@@ -102,7 +102,7 @@ export function groupDocumentsByLanguage<TLanguage extends LangiumCoreServices>(
  * Registry handed to a {@link BuildPhasePassContribution}. Implemented by the
  * `BuildPhasePassService`; doubles
  * as the low-level imperative API the framework uses to self-register its own
- * passes (integrity, the Langium profiler flush).
+ * passes (integrity, CST residency).
  */
 export interface BuildPhasePassRegistry {
    register(pass: BuildPhasePass): Disposable;

package/src/langium/composite-ast-reflection.ts

@@ -0,0 +1,112 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import { AbstractAstReflection, type AstMetaData, type AstReflection, type PropertyMetaData, type TypeMetaData } from '@hydranium/langium';
+import { assertSingleLangiumCopy } from './single-langium-copy.js';
+
+/**
+ * One `AstReflection` over the reflections of separately generated language
+ * packages. The shared `AstReflection` slot holds a single reflection, so
+ * binding each package's generated shared module keeps only the last one's
+ * types; bind this over all of them instead.
+ *
+ * A name several reflections share is taken to be one type, reached through a
+ * shared imported grammar, and keeps every super type any of them gives it:
+ * each grammar may declare its own union over the type. Only properties that
+ * differ in name, reference type or default value throw; two unrelated unions,
+ * or same-shaped interfaces, that share a name merge silently, so keep other
+ * type names distinct across packages.
+ *
+ * Only each reflection's `types` is read, so behaviour a reflection overrides
+ * is lost. Each package's generated `isX` guards keep using that package's own
+ * reflection and answer false for subtypes only another package declares.
+ *
+ * Each reflection is checked with {@link assertSingleLangiumCopy}, because the
+ * composite itself extends the framework copy's base whichever copy they use.
+ *
+ * The protected merge methods run from the constructor, so an override cannot
+ * read its own class's fields.
+ */
+export class CompositeAstReflection extends AbstractAstReflection {
+   override readonly types: AstMetaData = {};
+
+   constructor(reflections: readonly AstReflection[]) {
+      super();
+      const firstDefinedAt = new Map<string, number>();
+      reflections.forEach((reflection, index) => {
+         assertSingleLangiumCopy(reflection, () => this.formatReflection(reflections, index));
+         for (const [type, metaData] of Object.entries(reflection.types)) {
+            const ownerIndex = firstDefinedAt.get(type);
+            if (ownerIndex === undefined) {
+               this.types[type] = metaData;
+               firstDefinedAt.set(type, index);
+            } else {
+               this.types[type] = this.mergeTypeMetaData(
+                  this.types[type],
+                  metaData,
+                  this.formatReflection(reflections, ownerIndex),
+                  this.formatReflection(reflections, index)
+               );
+            }
+         }
+      });
+   }
+
+   protected mergeTypeMetaData(known: TypeMetaData, added: TypeMetaData, knownFrom: string, addedFrom: string): TypeMetaData {
+      const properties: TypeMetaData['properties'] = {};
+      const propertyNames = new Set([...Object.keys(known.properties), ...Object.keys(added.properties)]);
+      for (const property of propertyNames) {
+         const knownProperty = known.properties[property];
+         const addedProperty = added.properties[property];
+         if (!knownProperty || !addedProperty || !this.sameProperty(knownProperty, addedProperty)) {
+            throw new Error(
+               `[hydranium] ${knownFrom} and ${addedFrom} define the type ` +
+                  `'${known.name}' differently (property '${property}'). A name the composed reflections share must ` +
+                  'denote one type, so rename one of them, or have every grammar take the type unchanged from one ' +
+                  'shared imported grammar.'
+            );
+         }
+         properties[property] = addedProperty.optional && !knownProperty.optional ? addedProperty : knownProperty;
+      }
+      // `Required` so a field Langium adds fails compilation until this merge decides on it.
+      const merged: Required<TypeMetaData> = {
+         name: known.name,
+         properties,
+         superTypes: [...new Set([...known.superTypes, ...added.superTypes])]
+      };
+      return merged;
+   }
+
+   protected sameProperty(left: PropertyMetaData, right: PropertyMetaData): boolean {
+      return COMPARED_PROPERTY_FIELDS.every(field => JSON.stringify(left[field]) === JSON.stringify(right[field]));
+   }
+
+   /**
+    * Names `reflections[index]` for the composite's errors: its position and
+    * class name. The position is needed because minified bundles and scaffolds
+    * sharing a project name leave class names that do not tell reflections
+    * apart. An override can name the package each reflection came from.
+    */
+   protected formatReflection(reflections: readonly AstReflection[], index: number): string {
+      return `reflections[${index}] (${reflections[index].constructor?.name ?? 'no constructor'})`;
+   }
+}
+
+/** How the merge treats each property field; a field Langium adds fails compilation here until decided. */
+const PROPERTY_FIELDS = {
+   name: 'compared',
+   referenceType: 'compared',
+   defaultValue: 'compared',
+   // Older generators emit no `optional`, so its absence proves nothing.
+   optional: 'merged'
+} as const satisfies Record<keyof PropertyMetaData, 'compared' | 'merged'>;
+
+const COMPARED_PROPERTY_FIELDS = (Object.keys(PROPERTY_FIELDS) as Array<keyof PropertyMetaData>).filter(
+   field => PROPERTY_FIELDS[field] === 'compared'
+);

package/src/langium/config/configuration-provider.ts

@@ -0,0 +1,119 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import { type ConfigurationInitializedParams, DefaultConfigurationProvider } from '@hydranium/langium';
+import type { ConfigurationItem, DidChangeConfigurationRegistrationOptions } from 'vscode-languageserver';
+
+/**
+ * Configuration provider that asks the client about a section the first time
+ * something reads it.
+ *
+ * Langium's base requests one section per registered language, named after the
+ * language id, and never asks again. A read of any other section — including
+ * whatever `lsp.configurationRoot` is bound to — then resolves `undefined` with
+ * no request on the wire, which is indistinguishable from a setting the user has
+ * not set.
+ *
+ * Asking on first read rather than from a list collected up front: a reader
+ * names its section during DI, after `initialized` has taken its one-shot pass,
+ * so a list would have to be complete before the server initialized.
+ */
+export class HydraniumConfigurationProvider extends DefaultConfigurationProvider {
+   /**
+    * The client-facing hooks, captured because they arrive once as arguments to
+    * {@link initialized} and are needed on every later read. Absent in a
+    * headless composition, which has no connection to ask.
+    */
+   protected registerForSection?: (params: DidChangeConfigurationRegistrationOptions) => void;
+   protected fetchSections?: (items: ConfigurationItem[]) => Promise<unknown>;
+
+   /**
+    * Sections already dealt with, holding the in-flight work so concurrent
+    * readers share one round trip. Entries stay after they settle: they record
+    * that the section was HANDLED, and without that an unset section is
+    * re-requested on every read, "unset" and "not fetched" being the same
+    * absence in the store.
+    *
+    * A section the client's capabilities ruled out counts as handled, having
+    * been settled by asking nothing.
+    */
+   protected readonly requestedSections = new Map<string, Promise<void>>();
+
+   override async initialized(params: ConfigurationInitializedParams): Promise<void> {
+      this.registerForSection = params.register;
+      this.fetchSections = params.fetchConfiguration;
+      await super.initialized(params);
+   }
+
+   /**
+    * The `ready` await precedes the emptiness check: the base resolves it at the
+    * end of its own initial fetch, so testing the store first calls every
+    * language section missing and re-requests what is already on its way.
+    */
+   override async getConfiguration(language: string, configuration: string): Promise<unknown> {
+      await this.ready;
+      const section = this.toSectionName(language);
+      if (this.settings[section] === undefined) {
+         await this.requestSection(section);
+      }
+      return super.getConfiguration(language, configuration);
+   }
+
+   /** Ask about `section` once, sharing the request with any concurrent reader. */
+   protected requestSection(section: string): Promise<void> {
+      const existing = this.requestedSections.get(section);
+      if (existing) {
+         return existing;
+      }
+      const request = this.doRequestSection(section);
+      this.requestedSections.set(section, request);
+      return request;
+   }
+
+   /**
+    * The hooks are gated on the client having declared `workspace.configuration`.
+    * A connection binds them whatever the client said, so their presence is not
+    * consent: calling them sends a `client/registerCapability` and a
+    * `workspace/configuration` to a client that advertised support for neither,
+    * which is entitled to answer either with a method-not-found and may drop the
+    * connection.
+    *
+    * That flag is exact for the fetch and KNOWINGLY coarse for the registration,
+    * which the spec governs by
+    * `workspace.didChangeConfiguration.dynamicRegistration`. The base registers
+    * under `workspace.configuration` alone before any of this runs, so gating
+    * the registration on the narrower flag here would withhold a request whose
+    * twin has already gone out, sparing the client nothing. A client declaring
+    * `workspace.configuration` without dynamic registration is still registered
+    * for, by the base and by this; closing that means changing the base's pass,
+    * not this gate.
+    *
+    * Registering before fetching, so an edit landing between the two arrives as
+    * a notification instead of being lost; the reverse order drops it.
+    *
+    * A `null` result is left out of the store rather than written, so the
+    * section reads as unset, and no `onConfigurationSectionUpdate` fires — the
+    * value goes to the caller that asked for it, and an event would announce a
+    * change that is only this provider catching up.
+    */
+   protected async doRequestSection(section: string): Promise<void> {
+      if (!this.workspaceConfig) {
+         return;
+      }
+      this.registerForSection?.({ section });
+      if (!this.fetchSections) {
+         return;
+      }
+      const fetched = await this.fetchSections([{ section }]);
+      const value = Array.isArray(fetched) ? fetched[0] : fetched;
+      if (value !== null && value !== undefined) {
+         this.updateSectionConfiguration(section, value);
+      }
+   }
+}

package/src/langium/config/index.ts

@@ -7,4 +7,5 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
+export * from './configuration-provider.js';
 export * from './settings.js';

package/src/langium/diagnostics/hydranium-langium-profiler.ts

@@ -8,14 +8,7 @@
  ********************************************************************************/
 
 import { Format, Logger, type Tracer } from '@hydranium/protocol';
-import {
-   DefaultLangiumProfiler,
-   DocumentState,
-   MultiMap,
-   type ProfilingCategory,
-   type ProfilingRecord,
-   ProfilingTask
-} from '@hydranium/langium';
+import { DefaultLangiumProfiler, MultiMap, type ProfilingCategory, type ProfilingRecord, ProfilingTask } from '@hydranium/langium';
 import { type LogNameOptions } from './logger.js';
 import { type ServerSharedServicesMinimal } from '../shared-services.js';
 
@@ -29,18 +22,8 @@ export interface LangiumProfilerOptions extends LogNameOptions {
     * {@link DefaultLangiumProfiler}) to Langium's full set when omitted.
     */
    readonly activeCategories?: Set<ProfilingCategory>;
-   /**
-    * Priority of the per-build flush pass at the `Validated` phase. The flush is
-    * normally the only pass at `Validated`, so order is immaterial; the option
-    * exists for symmetry with the other framework passes. Default
-    * {@link PROFILER_FLUSH_PASS_PRIORITY}.
-    */
-   readonly flushPriority?: number;
 }
 
-/** Default priority of the profiler's per-build flush pass (see {@link LangiumProfilerOptions.flushPriority}). */
-export const PROFILER_FLUSH_PASS_PRIORITY = 0;
-
 /**
  * Framework adapter over Langium's {@link DefaultLangiumProfiler} that is
  * **trace-gated** and emits a single **aggregated** per-category breakdown
@@ -54,9 +37,8 @@ export const PROFILER_FLUSH_PASS_PRIORITY = 0;
  *    task identifier), so the per-document records carry no distinguishing
  *    information anyway. We instead accumulate records in {@link records} and
  *    {@link flush} one breakdown per category — self-time and invocation counts
- *    summed per `$type` across the whole build — on the terminal `Validated`
- *    build phase (self-registered in the constructor). One report per build, not
- *    one per file.
+ *    summed per `$type` across the whole build — when the build ends
+ *    (subscribed in the constructor). One report per build, not one per file.
  *  - **Transport safety.** The stock per-record dump uses `console.table`, which
  *    is NOT in the set `patchConsole` reroutes; under `vscode-languageserver`'s
  *    `--stdio` transport `process.stdout` *is* the JSON-RPC channel, so the
@@ -74,8 +56,8 @@ export const PROFILER_FLUSH_PASS_PRIORITY = 0;
  *    restart. Langium's own `start`/`stop` category selection still applies *on
  *    top of* the trace gate.
  *
- * Registered eagerly (see `DEFAULT_EAGER_SERVICES`) so its `Validated`-phase
- * flush pass is registered before the first build. Gives the per-grammar-rule /
+ * Registered eagerly (see `DEFAULT_EAGER_SERVICES`) so its flush is
+ * subscribed before the first build. Gives the per-grammar-rule /
  * per-`$type` parse/link/validate self-time the framework's own
  * `ServerTracer` / `ProfileSession` passes
  * cannot produce (those cover the framework's passes *outside* Langium's
@@ -88,16 +70,11 @@ export class HydraniumLangiumProfiler extends DefaultLangiumProfiler {
    constructor(services: ServerSharedServicesMinimal, options: LangiumProfilerOptions = {}) {
       super(options.activeCategories);
       this.tracer = services.Tracer.for(options.logName ?? 'LangiumProfiler').trace('instantiated');
-      // Flush once per build on the terminal phase rather than once per document.
-      // By `Validated`, every parse/link/validate record for the batch is in.
-      // Registered as a build-phase pass (not a direct onBuildPhase listener) so
-      // every framework + adopter build-phase reaction shares one dispatcher.
-      services.workspace.BuildPhasePassService.register({
-         id: 'framework:langium-profiler:flush',
-         state: DocumentState.Validated,
-         priority: options.flushPriority ?? PROFILER_FLUSH_PASS_PRIORITY,
-         run: () => this.flush()
-      });
+      // Flush once per build when it ends rather than once per document. Not at
+      // a `Validated` pass: that phase stays silent for a build that validates
+      // nothing, the workspace's initial one among them, and the records would
+      // then wait for a build that does.
+      services.workspace.DocumentBuilder.onBuildEnded(() => this.flush());
    }
 
    /**
@@ -142,14 +119,13 @@ export class HydraniumLangiumProfiler extends DefaultLangiumProfiler {
    /**
     * Emit one aggregated breakdown per category — self-time and invocation
     * counts summed per `<languageId>.<$type>` across every record collected
-    * this build — then clear the window. Self-registered as a `Validated`-phase
-    * build pass, so it fires once per build, not per document. Pass explicit
-    * categories to flush a subset; defaults to all.
+    * this build — then clear the window. Called when a build ends, so it fires
+    * once per build, not per document. Pass explicit categories to flush a
+    * subset; defaults to all.
     *
     * `flush` is the sole reset point: because it clears each flushed category,
-    * memory is bounded per completed build. A build cancelled before `Validated`
-    * leaves its partial records to roll into the next build's flush (slightly
-    * inflated counts, self-correcting) rather than accumulating without bound.
+    * memory is bounded per build. Builds that throw share one flush, once the
+    * lock has drained after them.
     */
    flush(...categories: ProfilingCategory[]): void {
       const toFlush = categories.length > 0 ? categories : ALL_CATEGORIES;