@hydranium/core 1.0.0-next.10

package/src/langium/document-builder/index.ts

@@ -0,0 +1,12 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, 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
+ ********************************************************************************/
+
+export * from './build-pipeline-integration.js';
+export * from './document-builder.js';
+export * from './labeled-phase-listener.js';

package/src/langium/document-builder/labeled-phase-listener.ts

@@ -0,0 +1,26 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, 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
+ ********************************************************************************/
+
+/**
+ * A document-builder phase listener that carries a `displayName` so per-listener
+ * timing can attribute slow-listener breakdowns to the right caller. The
+ * framework's enhanced document-builder reads `displayName` when emitting
+ * per-listener phase logs; listeners without a
+ * label fall back to `Function.name`.
+ */
+export interface LabeledPhaseListener {
+   displayName: string;
+}
+
+/** Attach a `displayName` to a phase listener so it shows up in slow-listener breakdowns. */
+export function labelPhaseListener<T extends (...args: never[]) => unknown>(listener: T, displayName: string): T & LabeledPhaseListener {
+   const labeled = listener as T & LabeledPhaseListener;
+   labeled.displayName = displayName;
+   return labeled;
+}

package/src/langium/documentation/comment-provider.ts

@@ -0,0 +1,37 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, 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 AstNode, DefaultCommentProvider } from '@hydranium/langium';
+import type { HydraniumLanguageServices } from '../language-module.js';
+
+/**
+ * Comment provider that survives CST residency shedding.
+ *
+ * Hover and completion documentation read the TARGET node's preceding comment
+ * through Langium's `DefaultCommentProvider.getComment`, which resolves it from
+ * the node's live `$cstNode` — exactly what a residency policy sheds for a
+ * closed, idle document. Those are read-only LSP requests that never run a
+ * build, so nothing would restore the CST and a shed target's documentation
+ * would silently come back empty.
+ *
+ * Read-side CST rehydration, the documentation sibling of
+ * `DefaultNameProvider.getNameNode`: restore the CST on demand before reading.
+ * A no-op while the CST is resident (every parsed node has a `$cstNode`), so
+ * behaviour is unchanged unless a residency policy has shed the document.
+ */
+export class HydraniumCommentProvider extends DefaultCommentProvider {
+   constructor(protected readonly languageServices: HydraniumLanguageServices) {
+      super(languageServices);
+   }
+
+   override getComment(node: AstNode): string | undefined {
+      this.languageServices.shared.workspace.CstResidencyService.rehydrateNode(node);
+      return super.getComment(node);
+   }
+}

package/src/langium/documentation/index.ts

@@ -0,0 +1,10 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, 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
+ ********************************************************************************/
+
+export * from './comment-provider.js';

package/src/langium/integration-services.ts

@@ -0,0 +1,281 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, 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 { inject, type Module } from '@hydranium/langium';
+import {
+   createDefaultModule,
+   createDefaultSharedModule,
+   type LangiumServices,
+   type LangiumSharedServices,
+   type PartialLangiumServices,
+   type PartialLangiumSharedServices
+} from '@hydranium/langium/lsp';
+import { DEFAULT_EAGER_SERVICES, bootstrapLangiumLanguages } from './bootstrap.js';
+import { createServerLanguageModule } from './language-module.js';
+import { createServerSharedModule, type ServerModuleContext } from './module.js';
+import type { ServerSharedServicesMinimal } from './shared-services.js';
+
+/**
+ * Options accepted by {@link createIntegrationServices}. Wraps the
+ * canonical Langium module-composition chain that every hydranium
+ * adopter writes verbatim — `createDefaultSharedModule` →
+ * grammar-generated shared module → `createServerSharedModule` →
+ * optional protocol-head shared modules → adopter shared overrides;
+ * symmetric on the language side. Both tiers take head modules in the
+ * same `extra` position, because a head contributes to whichever tier
+ * Langium declares the slot on.
+ *
+ * Slots that are adopter-specific and don't fit cleanly into the helper
+ * — typed-`ServiceRegistry` assignments, Langium validation-check
+ * registration, and any other post-bootstrap side effects — stay in the
+ * adopter's `createXxxServices` function around the helper call. The
+ * helper covers the *composition* boilerplate, not adopter-specific
+ * lifecycle.
+ */
+export interface IntegrationServicesOptions<
+   TContext extends ServerModuleContext,
+   TShared extends LangiumSharedServices & ServerSharedServicesMinimal,
+   TLanguage extends LangiumServices
+> {
+   /**
+    * Shared module-construction context. Flows into the framework's
+    * default factories (`createDefaultSharedModule`,
+    * `createServerSharedModule`, `createServerLanguageModule`) and into
+    * any head-language modules the adopter contributes via `extra`.
+    * Adopters with custom context fields (parser worker path, integrity
+    * sync mode, custom file-system providers) extend
+    * {@link ServerModuleContext} and pass the wider context — the
+    * framework factories ignore unknown fields.
+    */
+   context: TContext;
+
+   /**
+    * Shared-services module pair: the grammar's generated module and the
+    * adopter's override module. Spread into the shared `inject(...)` in
+    * the order:
+    * - `createDefaultSharedModule(context)` (Langium baseline)
+    * - `generated` (grammar metadata, AST reflection)
+    * - `createServerSharedModule(context)` (framework defaults)
+    * - ...`extra` (protocol heads — `createLspServerSharedModule(context)`)
+    * - `adopter` (adopter overrides — later-wins)
+    */
+   sharedModules: {
+      /**
+       * Module emitted by `langium-cli` (grammar metadata, AST reflection).
+       *
+       * `AstReflection` is a SINGLE shared slot, so in a multi-grammar
+       * composition this must be the *combined* generated shared module of
+       * ONE `langium-cli` run over all grammars (one `langium-config.json`
+       * with several entry grammars). Two independently generated language
+       * packages each bind this one slot and the last one wins, leaving the
+       * other grammar's types unknown to reflection — `isSubtype` answers
+       * false, `getTypeMetaData` is empty, and indexing, reference routing
+       * and the transfer encoder all silently miss those types.
+       * {@link bootstrapLangiumLanguages} throws when a language's types are
+       * wholly absent and warns on a partial gap, because the types cannot
+       * express "these modules came from one generator run".
+       */
+      generated: Module<TShared, PartialLangiumSharedServices>;
+      /** Adopter's override module (workspace manager, file-system provider, integrity rules, etc.). */
+      adopter: Module<TShared, PartialLangiumSharedServices>;
+      /**
+       * Additional SHARED modules contributed by protocol heads —
+       * `createLspServerSharedModule(context)` from `@hydranium/core/lsp`,
+       * future heads' shared modules. Composed *after*
+       * `createServerSharedModule` and *before* `adopter`, mirroring
+       * `languageModules.extra`.
+       *
+       * A head needs this tier whenever the slot it binds is shared in
+       * Langium rather than per-language — `lsp.DocumentUpdateHandler` is
+       * the case that forced this option to exist: it is read off the
+       * shared tree by `startLanguageServer`, so a per-language binding of
+       * it is silently inert.
+       */
+      extra?: ReadonlyArray<Module<TShared, PartialLangiumSharedServices>>;
+   };
+
+   /**
+    * Language-services module trio: generated, adopter, and optional
+    * extra protocol-head modules. Spread into the language `inject(...)`
+    * in the order:
+    * - `createDefaultModule({ shared })` (Langium baseline)
+    * - `generated` (grammar tokens, parser, etc.)
+    * - `createServerLanguageModule(context)` (framework defaults)
+    * - ...`extra` (protocol heads — `createLspServerLanguageModule(context)`, future heads)
+    * - `adopter`(shared) (adopter overrides — later-wins)
+    *
+    * The adopter slot is a factory rather than a plain module so it
+    * receives the already-injected `shared` services. Adopters with
+    * context-dependent slot bindings (e.g. a parser-worker path
+    * conditional) close over the wider context in the factory.
+    */
+   languageModules: {
+      /** Module emitted by `langium-cli` (parser, tokens, grammar access). */
+      generated: Module<TLanguage, PartialLangiumServices>;
+      /**
+       * Adopter's override module, constructed against the resolved
+       * shared services. Plain-module adopters with no shared-services
+       * dependency at construction time write `() => MyLanguageModule`.
+       */
+      adopter: (shared: TShared) => Module<TLanguage, PartialLangiumServices>;
+      /**
+       * Additional language modules contributed by protocol heads —
+       * `createLspServerLanguageModule(context)` from
+       * `@hydranium/core/lsp`, future `createGlspServerLanguageModule`
+       * from `@hydranium/glsp-server`, etc. Composed *after*
+       * `createServerLanguageModule` and *before* `adopter` so
+       * head defaults win over framework defaults but adopter overrides
+       * still win over heads.
+       */
+      extra?: ReadonlyArray<Module<TLanguage, PartialLangiumServices>>;
+   };
+
+   /**
+    * Additional languages composed over the SAME shared tier — the
+    * multi-grammar case. Each entry gets its own `createDefaultModule({ shared })`
+    * → generated → framework-defaults → extra → adopter chain, exactly
+    * like {@link languageModules}, and all of them are registered before
+    * any slot validation or eager construction runs (see
+    * {@link bootstrapLangiumLanguages}).
+    *
+    * Because the shared tier is common, the `AstDocumentManager`,
+    * `IndexManager` and `DocumentBuilder` are shared across languages —
+    * which is what lets cross-grammar references resolve through one
+    * global index.
+    *
+    * {@link AdditionalLanguageModules.adopter} and
+    * {@link AdditionalLanguageModules.extra} default to the primary
+    * language's, so a second grammar that reuses the same service
+    * overrides only supplies its own `generated` module.
+    *
+    * Every grammar composed here must come from ONE `langium-cli` run —
+    * see the `generated` note on {@link IntegrationServicesOptions.sharedModules}.
+    * The shared `AstReflection` slot cannot hold two independently
+    * generated reflections, so separately generated language packages are
+    * detected at bootstrap rather than supported.
+    *
+    * Multi-grammar adopters should also rebind `lsp.configurationRoot`
+    * (it defaults to the first registered language's id) and, if they
+    * pass non-URI reference sources, override
+    * `DataServer.resolveReferenceServices`.
+    */
+   additionalLanguages?: ReadonlyArray<AdditionalLanguageModules<TShared, TLanguage>>;
+
+   /**
+    * Forwarded to {@link bootstrapLangiumLanguages}. Defaults to
+    * {@link DEFAULT_EAGER_SERVICES}, which already covers every framework
+    * service that must be constructed before the first build; adopters
+    * with their own eager targets spread the default into their list.
+    */
+   eagerlyConstructedServices?: ReadonlyArray<(services: TShared) => unknown>;
+}
+
+/**
+ * One additional language in a multi-grammar composition. Only
+ * {@link generated} is required; the service-override slots fall back to
+ * the primary language's, since a second grammar in the same adopter
+ * usually reuses the same scope provider, serializer and lexer and
+ * differs only in its grammar-generated module.
+ */
+export interface AdditionalLanguageModules<
+   TShared extends LangiumSharedServices & ServerSharedServicesMinimal,
+   TLanguage extends LangiumServices
+> {
+   /**
+    * Module emitted by `langium-cli` for this grammar — from the SAME run
+    * that produced the primary language's modules and the shared
+    * `generated` module, not a separately generated language package.
+    */
+   generated: Module<TLanguage, PartialLangiumServices>;
+   /** Adopter overrides for this language. Defaults to the primary language's. */
+   adopter?: (shared: TShared) => Module<TLanguage, PartialLangiumServices>;
+   /** Protocol-head modules for this language. Defaults to the primary language's. */
+   extra?: ReadonlyArray<Module<TLanguage, PartialLangiumServices>>;
+}
+
+/**
+ * Compose the standard hydranium Langium DI tree from an adopter's
+ * generated + override modules: one shared `inject(...)`, one language
+ * `inject(...)` per grammar, then {@link bootstrapLangiumLanguages} — the
+ * chain every adopter and every protocol head otherwise writes verbatim.
+ * The value is the composition ORDER, which is later-wins throughout:
+ * Langium baseline, then generated, then framework defaults, then
+ * protocol heads, then adopter overrides, on both tiers.
+ *
+ * Returns `{ shared, language, languages }`, where `language` is the
+ * primary one and `languages` also carries any
+ * {@link IntegrationServicesOptions.additionalLanguages}.
+ * Adopter-specific post-bootstrap hooks (typed `ServiceRegistry`
+ * assignments, `registerValidationChecks(...)`, etc.) stay in the
+ * adopter's wrapping `createXxxServices(context)` function around this
+ * call — the helper covers composition, not bespoke lifecycle.
+ */
+export function createIntegrationServices<
+   TContext extends ServerModuleContext,
+   TShared extends LangiumSharedServices & ServerSharedServicesMinimal,
+   TLanguage extends LangiumServices
+>(
+   options: IntegrationServicesOptions<TContext, TShared, TLanguage>
+): { shared: TShared; language: TLanguage; languages: ReadonlyArray<TLanguage> } {
+   const {
+      context,
+      sharedModules,
+      languageModules,
+      additionalLanguages = [],
+      eagerlyConstructedServices = DEFAULT_EAGER_SERVICES
+   } = options;
+
+   // Casts on the framework-side modules unify their `Module<T, …>` type
+   // parameter with the adopter-supplied `TShared` / `TLanguage`. Langium's
+   // `inject(...)` requires every input module to share the same `TServices`;
+   // without the casts the compiler refuses to combine
+   // `Module<LangiumSharedServices, …>` (from `createDefaultSharedModule`) with
+   // `Module<TShared, …>` (the adopter's generated and override modules).
+   // Concrete-typed adopter factories (e.g. `createMyLangServices`) sidestep this
+   // by casting the `inject(...)` result; here the helper shoulders the cast so
+   // every adopter doesn't repeat it.
+   const sharedModule = createServerSharedModule(context) as unknown as Module<TShared, PartialLangiumSharedServices>;
+   const defaultSharedModule = createDefaultSharedModule(context) as unknown as Module<TShared, PartialLangiumSharedServices>;
+   const shared = inject(
+      defaultSharedModule,
+      sharedModules.generated,
+      sharedModule,
+      ...(sharedModules.extra ?? []),
+      sharedModules.adopter
+   ) as unknown as TShared;
+
+   // Each language gets its OWN `createDefaultModule({ shared })` — the
+   // baseline module is per-language state (parser, lexer, linker), so it
+   // cannot be shared between the grammars even though `shared` is.
+   const composeLanguage = (
+      generated: Module<TLanguage, PartialLangiumServices>,
+      adopter: (shared: TShared) => Module<TLanguage, PartialLangiumServices>,
+      extra: ReadonlyArray<Module<TLanguage, PartialLangiumServices>>
+   ): TLanguage => {
+      const defaultLanguageModule = createDefaultModule({ shared }) as unknown as Module<TLanguage, PartialLangiumServices>;
+      const serverLanguageModule = createServerLanguageModule(context) as unknown as Module<TLanguage, PartialLangiumServices>;
+      return inject(defaultLanguageModule, generated, serverLanguageModule, ...extra, adopter(shared)) as unknown as TLanguage;
+   };
+
+   const primaryExtra = (languageModules.extra ?? []) as ReadonlyArray<Module<TLanguage, PartialLangiumServices>>;
+   const language = composeLanguage(languageModules.generated, languageModules.adopter, primaryExtra);
+   const languages = [
+      language,
+      ...additionalLanguages.map(additional =>
+         composeLanguage(additional.generated, additional.adopter ?? languageModules.adopter, additional.extra ?? primaryExtra)
+      )
+   ];
+
+   // Registers every language before validating slots or building the
+   // eager set, so a shared service that reads the registry during
+   // construction sees all languages.
+   bootstrapLangiumLanguages(shared, languages, eagerlyConstructedServices);
+
+   return { shared, language, languages };
+}

package/src/langium/integrity/index.ts

@@ -0,0 +1,12 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, 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
+ ********************************************************************************/
+
+export * from './integrity-contribution.js';
+export * from './integrity-rule.js';
+export * from './integrity-service.js';

package/src/langium/integrity/integrity-contribution.ts

@@ -0,0 +1,44 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, 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 AstNode } from '@hydranium/langium';
+import { type Disposable } from 'vscode-languageserver';
+import { type IntegrityRule } from './integrity-rule.js';
+
+/**
+ * Registry handed to an {@link IntegrityRuleContribution}. Implemented by the
+ * integrity service; a contribution receives it and registers one or many
+ * rules. Doubles as the low-level imperative API for the rare runtime-dynamic
+ * registration case.
+ *
+ * `register` is generic PER CALL, matching `AstExtensionRegistry` and
+ * `ValidationCheckRegistry`: a rule declares the node type it enforces against
+ * (`IntegrityRule<TypeOne>`), and pinning the parameter to the `AstNode`
+ * default would widen every rule at the door. That widening is accepted by
+ * method-parameter bivariance rather than rejected, so it costs no cast and
+ * reads as fine — which is exactly why it is worth stating: the rule's own
+ * node type stays visible at the registration site instead of being erased.
+ */
+export interface IntegrityRuleRegistry {
+   register<T extends AstNode>(rule: IntegrityRule<T>): Disposable;
+}
+
+/**
+ * Declarative registration of integrity rules. Bound under the module's
+ * `integrity.rules` contribution group; the integrity service reads its own
+ * group at construction and calls this method, handing itself in as the
+ * registry.
+ *
+ * The domain-qualified method name lets a single cross-cutting class implement
+ * several contribution interfaces (e.g. also `ValidationCheckContribution`)
+ * without method collision — bind it once and reference it from each group.
+ */
+export interface IntegrityRuleContribution {
+   registerIntegrityRules(registry: IntegrityRuleRegistry): void;
+}

package/src/langium/integrity/integrity-rule.ts

@@ -0,0 +1,100 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, 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 Logger, type MaybePromise } from '@hydranium/protocol';
+import { type AstNode, DocumentState, type LangiumDocument } from '@hydranium/langium';
+import { type RegistryItem } from '../../util/registry.js';
+
+/**
+ * Integrity rules run during a build phase and may mutate the AST. Allowed
+ * phases are `Parsed` (before linking — a rule that touches only the parsed
+ * shape) and `Linked` (after cross-references are resolved — a rule that
+ * needs reference targets to exist).
+ */
+export type IntegrityPhase = DocumentState.Parsed | DocumentState.Linked;
+
+export namespace IntegrityPhase {
+   export const Parsed: IntegrityPhase = DocumentState.Parsed;
+   export const Linked: IntegrityPhase = DocumentState.Linked;
+
+   /**
+    * The canonical set of phases at which integrity rules may run, in build
+    * order. Single source of truth: `IntegrityService.register` validates
+    * against it, and the framework's `BuildPipelineIntegration` registers one
+    * integrity pass per entry. A function (not a const) so it reads as an
+    * operation, distinct in kind from the `Parsed` / `Linked` phase-value
+    * constants — `IntegrityPhase.all` would look like a third phase. Returns a
+    * fresh array so callers cannot mutate the canonical set.
+    */
+   export function all(): readonly IntegrityPhase[] {
+      return [Parsed, Linked];
+   }
+
+   export function toString(phase: DocumentState): string {
+      switch (phase) {
+         case DocumentState.Parsed:
+            return 'Parsed';
+         case DocumentState.Linked:
+            return 'Linked';
+         default:
+            return `Unknown(${phase})`;
+      }
+   }
+}
+
+/**
+ * Controls how integrity corrections are persisted for *closed* files. The
+ * mode does not reach open files: their corrected text is delivered by the
+ * model service's settled-state sync, whatever the mode says.
+ *
+ * - `silent`: write to disk immediately; no editor involvement.
+ * - `editor`: open the file dirty via `applyEdit`. If the user closes without
+ *    saving, the correction is suppressed until the file changes or the
+ *    workspace reloads.
+ */
+export type IntegritySyncMode = 'silent' | 'editor';
+
+/**
+ * A single integrity rule that enforces a constraint on AST nodes of a given type
+ * at a specific build phase.
+ *
+ * Extends {@link RegistryItem}: {@link RegistryItem.priority} orders rules
+ * WITHIN one phase, never across phases, because each phase has its own
+ * bucket. Lower runs first; ties break by registration order.
+ */
+export interface IntegrityRule<T extends AstNode = AstNode> extends RegistryItem {
+   /** Which AST node type this rule applies to. */
+   readonly nodeType: string;
+   /** At which document state this rule should run. Be aware that extension properties may not be available in all phases. */
+   readonly phase: IntegrityPhase;
+   /**
+    * Apply the rule. Returns `true` if the AST was mutated.
+    *
+    * Mirrors Langium's `ValidationCheck` shape (`MaybePromise<void>`) so a
+    * rule that must consult an external system can return a promise without
+    * forcing every sync rule to pay a microtask tick per node. The
+    * framework's per-node dispatch uses `isPromiseLike` to keep sync
+    * rules on the synchronous fast path; async rules are awaited normally.
+    */
+   enforce(node: T, document: LangiumDocument, logger: Logger): MaybePromise<boolean>;
+}
+
+/**
+ * The author id an integrity correction would carry if integrity tagged
+ * authorship. **It does not.** A correction is an internal build step riding a
+ * user's own build, so tagging it would overwrite the last human author in the
+ * version history with a synthetic one; `getAuthor` reports `undefined` for an
+ * integrity-only mutation instead, which is the honest answer. None of the
+ * three delivery paths — settled-state sync for open files, the disk write in
+ * `silent` mode, staged pending content in `editor` mode — sets an author.
+ *
+ * Exported so a consumer can assert that a correction is NOT attributed to it,
+ * which is what catches a regression that starts tagging authorship again.
+ */
+export const INTEGRITY_CLIENT_ID = 'integrity';