@hydranium/core 1.0.0-next.10

package/src/langium/update-rewrite/semantic-root-rewrite.ts

@@ -0,0 +1,57 @@
+/********************************************************************************
+ * 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 TransferElement } from '@hydranium/protocol';
+
+/**
+ * Applies `rewrite` to the ONE populated semantic slot of a wrapper-shaped
+ * transfer root, reassembling the wrapper around the result.
+ *
+ * The transfer-side counterpart to `NameBasedKeyProvider.isSemanticRoot`'s
+ * "wrapper grammars with an unnamed root node" case: the document root is a
+ * discriminating wrapper carrying one populated slot per semantic type
+ * (`{ entity }` or `{ mapping }` or `{ diagram }`, never two), and an
+ * `UpdateRewrite` is handed that wrapper while the fields it cares about
+ * live one level down.
+ *
+ * `semanticKeys` is supplied rather than inferred: which slots a wrapper may
+ * carry is grammar knowledge, and sniffing "the single object-valued property"
+ * would silently pick up any object-valued metadata a root grows later.
+ *
+ * **Identity is the no-op signal, and it is load-bearing.** When no slot is
+ * populated, or `rewrite` hands back the same reference it was given, the
+ * ARGUMENT is returned — not a copy. An `UpdateRewrite` chain folds every
+ * rewrite over the model, so a rewrite that does not apply must be free; a
+ * defensive copy here would make every unrelated write allocate a fresh root per
+ * registered rewrite. Callers that compare with `===` to detect "nothing
+ * happened" depend on this too.
+ *
+ * Rewrites of an unwrapped grammar — where the named root element IS the
+ * semantic root — do not need this helper: their model is already the node.
+ */
+export function rewriteSemanticRoot<TTransfer extends TransferElement>(
+   model: TTransfer,
+   semanticKeys: readonly string[],
+   rewrite: (semanticRoot: Record<string, unknown>, key: string) => Record<string, unknown>
+): TTransfer {
+   const record = model as unknown as Record<string, unknown>;
+   const semanticKey = semanticKeys.find(key => record[key]);
+   if (!semanticKey) {
+      return model;
+   }
+   const semanticRoot = record[semanticKey] as Record<string, unknown> | undefined;
+   if (!semanticRoot) {
+      return model;
+   }
+   const rewritten = rewrite(semanticRoot, semanticKey);
+   if (rewritten === semanticRoot) {
+      return model;
+   }
+   return { ...record, [semanticKey]: rewritten } as unknown as TTransfer;
+}

package/src/langium/update-rewrite/update-rewrite-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 Disposable } from 'vscode-languageserver';
+import { type AstNode } from '@hydranium/langium';
+import { type TransferElement } from '@hydranium/protocol';
+import { type UpdateRewrite } from './update-rewrite.js';
+
+/**
+ * Registry handed to an {@link UpdateRewriteContribution}. Implemented by the
+ * update-rewrite service; a contribution receives it and registers one or many
+ * rewrites. Doubles as the low-level imperative API for the rare
+ * runtime-dynamic registration case.
+ *
+ * Generic over `<TTransfer, TAst>` for the same reason {@link UpdateRewrite} and
+ * `UpdateRewriteService` are: an adopter that narrows to its own root types gets
+ * a `rewrite` callback whose `model` and `previous` are already its types, so a
+ * registration needs no cast at all. Both default to the structural bases, so
+ * every existing call site keeps compiling unchanged.
+ */
+export interface UpdateRewriteRegistry<TTransfer extends TransferElement = TransferElement, TAst extends AstNode = AstNode> {
+   register(rewrite: UpdateRewrite<TTransfer, TAst>): Disposable;
+}
+
+/**
+ * Declarative registration of update rewrites. Bound under the module's
+ * `updateRewrite.rewrites` contribution group (a
+ * `Record<string, UpdateRewriteContribution>`); the update-rewrite 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 `IntegrityRuleContribution`)
+ * without method collision — bind it once and reference it from each group.
+ */
+export interface UpdateRewriteContribution<TTransfer extends TransferElement = TransferElement, TAst extends AstNode = AstNode> {
+   registerUpdateRewrites(registry: UpdateRewriteRegistry<TTransfer, TAst>): void;
+}

package/src/langium/update-rewrite/update-rewrite-service.ts

@@ -0,0 +1,129 @@
+/********************************************************************************
+ * 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 { isPromiseLike, type TransferElement, type Tracer } from '@hydranium/protocol';
+import { type AstNode, interruptAndCheck } from '@hydranium/langium';
+import { type CancellationToken, type Disposable } from 'vscode-languageserver';
+import { type LogNameOptions } from '../diagnostics/logger.js';
+import { type ServerLanguageServices } from '../language-module.js';
+import { Registry } from '../../util/registry.js';
+import { type UpdateRewriteRegistry } from './update-rewrite-contribution.js';
+import { type UpdateRewrite } from './update-rewrite.js';
+
+/**
+ * Public contract for the per-language update-rewrite runner. Extends the
+ * {@link UpdateRewriteRegistry} (the imperative `register` surface
+ * contributions use) with the {@link apply} entry point
+ * `ModelService.rewriteModel` calls on the structured write path, before
+ * serialisation.
+ *
+ * Adopter overrides go through {@link DefaultUpdateRewriteService}; the
+ * interface keeps the public API stable while internals (the registry) stay
+ * `protected` on the default class.
+ *
+ * Generic over `<TTransfer, TAst>` so each consumer plugs in their own transfer
+ * and AST root types; both default to the structural bases.
+ */
+export interface UpdateRewriteService<
+   TTransfer extends TransferElement = TransferElement,
+   TAst extends AstNode = AstNode
+> extends UpdateRewriteRegistry<TTransfer, TAst> {
+   /** Remove a rewrite by id. Returns `true` if a rewrite was removed. */
+   unregister(id: string): boolean;
+   /**
+    * Run every registered rewrite in priority order, threading the model
+    * through each, and return the rewritten transfer model. Always async (the
+    * method is called once per `update`, not per node), but a synchronous
+    * rewrite never adds a microtask — see {@link DefaultUpdateRewriteService.apply}.
+    *
+    * `cancelToken` is honoured between rewrites — material when a rewrite is
+    * async (an external lookup); a preempted update aborts the chain before the
+    * next rewrite rather than running it to completion against a doomed build.
+    */
+   apply(model: TTransfer, previous: TAst | undefined, cancelToken?: CancellationToken): Promise<TTransfer>;
+}
+
+/**
+ * Construction options for {@link DefaultUpdateRewriteService}. All fields
+ * optional — the defaults reproduce the framework's behaviour exactly.
+ */
+export type UpdateRewriteServiceOptions = LogNameOptions;
+
+/**
+ * Default {@link UpdateRewriteService} implementation. A pure ordered registry
+ * of transfer-model transforms; the framework ships **zero** members (an empty
+ * chain is a no-op). Adopters declare rewrites via
+ * `UpdateRewriteContribution`s under the `updateRewrite.rewrites` group,
+ * or register imperatively.
+ *
+ * **Per-language service.** Bound in the per-language module and resolved by
+ * `ModelService` via `ServiceRegistry.getServices(uri)`, so multi-grammar
+ * workspaces route each write to the right rewrite set.
+ *
+ * The framework provides no comparison helper and no previous-state accessor —
+ * a diff-based rewrite owns its own representation reconciliation (see
+ * {@link UpdateRewrite}).
+ */
+export class DefaultUpdateRewriteService<
+   TTransfer extends TransferElement = TransferElement,
+   TAst extends AstNode = AstNode
+> implements UpdateRewriteService<TTransfer, TAst> {
+   /** Registry of rewrites, keyed by id, iterated in priority order. */
+   protected readonly rewrites = new Registry<UpdateRewrite<TTransfer, TAst>>();
+   protected readonly tracer: Tracer;
+
+   constructor(
+      protected readonly services: ServerLanguageServices,
+      options: UpdateRewriteServiceOptions = {}
+   ) {
+      this.tracer = services.shared.Tracer.for(options.logName ?? 'UpdateRewrite').trace('instantiated');
+
+      // Read the language's UpdateRewriteContribution group and let each
+      // contribution register one or many rewrites through this service.
+      // Optional chaining tolerates incomplete test stubs; production wiring
+      // always provides the slot via `createServerLanguageModule`.
+      const contributions = services.updateRewrite?.rewrites ?? {};
+      for (const contribution of Object.values(contributions)) {
+         contribution.registerUpdateRewrites(this);
+      }
+   }
+
+   register(rewrite: UpdateRewrite<TTransfer, TAst>): Disposable {
+      return this.rewrites.register(rewrite);
+   }
+
+   unregister(id: string): boolean {
+      return this.rewrites.unregister(id);
+   }
+
+   /**
+    * Fold the model through every rewrite in priority order. Mirrors the
+    * `DefaultIntegrityService.enforceIntegrity` pattern: the method is
+    * `async` (one tick per `update`, which is a per-operation call, not a
+    * per-node hot loop), and the per-rewrite {@link isPromiseLike} check skips
+    * the `await` for synchronous rewrites — the common case — so a sync chain
+    * adds no extra microtask beyond the single tick `async` already costs.
+    *
+    * `cancelToken` is checked before each rewrite (coarser than within a
+    * rewrite, finer than per-chain) so a preempted async chain interrupts
+    * cleanly — `interruptAndCheck` throws `OperationCancelled`, which aborts the
+    * `update` before any text is applied.
+    */
+   async apply(model: TTransfer, previous: TAst | undefined, cancelToken?: CancellationToken): Promise<TTransfer> {
+      let current = model;
+      for (const rewrite of this.rewrites.all()) {
+         if (cancelToken !== undefined) {
+            await interruptAndCheck(cancelToken);
+         }
+         const result = rewrite.rewrite(current, previous);
+         current = (isPromiseLike(result) ? await result : result) as TTransfer;
+      }
+      return current;
+   }
+}

package/src/langium/update-rewrite/update-rewrite.ts

@@ -0,0 +1,60 @@
+/********************************************************************************
+ * 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 MaybePromise, type TransferElement } from '@hydranium/protocol';
+import { type AstNode } from '@hydranium/langium';
+import { type RegistryItem } from '../../util/registry.js';
+
+/**
+ * A single transform applied to the incoming transfer model on the structured
+ * (object) write path of `ModelService.update` / `ModelService.save`, before
+ * serialisation. The RPC-update-stage sibling of `IntegrityRule` /
+ * `AstExtension` / `ValidationCheck` — same id-keyed,
+ * priority-ordered registry shape, but it runs on the transfer model rather
+ * than the built AST, and only on structured writes (never the LSP text path).
+ *
+ * **Two representations.** The contract is deliberately asymmetric — `model`
+ * and `previous` are NOT the same shape, and the types say so:
+ *
+ * - `model` (and the return) is a **transfer model**: cross-references are
+ *   flattened to `$refText` strings, derived `_*` properties are folded in as
+ *   *enumerable* fields, and there are no `$container` back-pointers. It is the
+ *   plain JSON that arrived over RPC from the form / diagram.
+ * - `previous` is a live **AST root** (`document.parseResult.value`): real
+ *   `Reference` objects, `$container`, and `_*` attached *non-enumerably* by the
+ *   AST-extension service. It is `undefined` for a not-yet-built document.
+ *
+ * A rewrite that needs to diff against the previous state owns the
+ * representation reconciliation itself (text-vs-`Reference`, enumerable-vs-not).
+ * The framework provides no comparison helper — comparison is grammar-specific
+ * policy.
+ *
+ * **Ordering** is by {@link RegistryItem.priority} ascending, ties broken by
+ * registration order — so a normalisation pass (low priority) reliably runs
+ * before a diff-based reconciliation (higher priority).
+ *
+ * **Sync fast path.** `rewrite` may return a promise (mirrors
+ * `IntegrityRule.enforce`) so an adopter rewrite that consults an external
+ * system isn't forced sync; the service keeps purely-sync rewrites — the common
+ * case — off the microtask queue.
+ *
+ * Generic over `<TTransfer, TAst>` so each adopter narrows to its own transfer
+ * and AST root types; both default to the structural bases.
+ */
+export interface UpdateRewrite<TTransfer extends TransferElement = TransferElement, TAst extends AstNode = AstNode> extends RegistryItem {
+   /**
+    * Rewrite the incoming transfer model. Return the input unchanged when the
+    * rewrite does not apply (the common no-op case).
+    *
+    * `previous` is the AST as it stood before this update — read-only; never
+    * mutate it. It is `undefined` for a brand-new document, which a diff-based
+    * rewrite should treat as "every field is new" (the maximal change case).
+    */
+   rewrite(model: TTransfer, previous: TAst | undefined): MaybePromise<TTransfer>;
+}

package/src/langium/validation/document-validator.ts

@@ -0,0 +1,188 @@
+/********************************************************************************
+ * 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 LogThreshold, type MaybeObservableValue, ObservableValue, type Tracer, TransferDiagnostic } from '@hydranium/protocol';
+import {
+   type AstNode,
+   type AstNodeLocator,
+   DefaultDocumentValidator,
+   type DiagnosticInfo,
+   type LangiumDocument,
+   type LangiumCoreServices,
+   type ValidateSingleNodeOptions,
+   type ValidationOptions,
+   type ValidationSeverity
+} from '@hydranium/langium';
+import type { CancellationToken } from 'vscode-languageserver-protocol';
+import type { Diagnostic } from 'vscode-languageserver-types';
+import { type LogNameOptions } from '../diagnostics/logger.js';
+import { isSyntheticNode } from '../workspace/synthetic.js';
+import { isVirtualUri } from '../workspace/virtual-document.js';
+
+/**
+ * Diagnostic shape produced by {@link HydraniumDocumentValidator}: an LSP
+ * {@link Diagnostic} extended with the protocol-level `element` path and
+ * optional `property` name from {@link TransferDiagnostic}.
+ */
+export interface TransferLspDiagnostic extends Diagnostic {
+   element: string;
+   property?: string;
+}
+
+export interface DocumentValidatorOptions extends LogNameOptions {
+   /**
+    * Level at which the `validateDocument` timing line is emitted, or `'off'`
+    * to disable the timing wrap entirely. Default: `'debug'`. Read per call, so
+    * it accepts a {@link MaybeObservableValue} — pass a constant or bind it to a
+    * user setting (via the `Settings` namespace) to retune live.
+    */
+   readonly logLevel?: MaybeObservableValue<LogThreshold>;
+   /**
+    * Suppress the timing line for validation runs shorter than this. Default:
+    * `20`ms. Read per call; accepts a {@link MaybeObservableValue}.
+    */
+   readonly logAfterMs?: MaybeObservableValue<number>;
+   /**
+    * Validate documents under the virtual URI scheme (see `isVirtualUri`).
+    * Default `false`: virtual documents (stdlib / library / built-in content)
+    * are skipped, because a virtual URI cannot be opened, so a diagnostic on it
+    * is un-actionable, and shipped library content is presumed correct. Set
+    * `true` to validate built-in definitions. Read per call, so it accepts a
+    * {@link MaybeObservableValue} — bind it to a user setting to toggle live.
+    */
+   readonly validateVirtualDocuments?: MaybeObservableValue<boolean>;
+   /**
+    * Validate nodes marked synthetic via `markSynthetic` (see `isSyntheticNode`).
+    * Default `false`: synthetic nodes (stdlib content, projection mirrors) are
+    * skipped, so a mirror never double-reports an error owned by its real
+    * declaration. Set `true` to validate them normally. Read per call, so it
+    * accepts a {@link MaybeObservableValue}.
+    */
+   readonly validateSyntheticNodes?: MaybeObservableValue<boolean>;
+}
+
+/**
+ * Default validator behaviour for `@hydranium/core` consumers:
+ *
+ * - **Skip-validation hook** via the virtual {@link shouldSkipValidation}
+ *   predicate, which adopters override to compose additional skip reasons.
+ * - **Diagnostic mapping** to {@link TransferDiagnostic}-shaped
+ *   {@link TransferLspDiagnostic}: every emitted diagnostic carries the AST
+ *   node's path (built via Langium's `AstNodeLocator`) plus the optional
+ *   offending property name.
+ * - **Optional timing wrap** on `validateDocument`, on by default.
+ */
+export class HydraniumDocumentValidator extends DefaultDocumentValidator {
+   protected readonly tracer: Tracer;
+   protected readonly astNodeLocator: AstNodeLocator;
+   protected readonly logLevel: ObservableValue<LogThreshold>;
+   protected readonly logAfterMs: ObservableValue<number>;
+   protected readonly validateVirtualDocuments: ObservableValue<boolean>;
+   protected readonly validateSyntheticNodes: ObservableValue<boolean>;
+
+   constructor(services: LangiumCoreServices & { shared: { Tracer: Tracer } }, options: DocumentValidatorOptions = {}) {
+      super(services);
+      this.tracer = services.shared.Tracer.for(options.logName ?? 'DocumentValidator').trace('instantiated');
+      this.astNodeLocator = services.workspace.AstNodeLocator;
+      this.logLevel = ObservableValue.from(options.logLevel ?? 'debug');
+      this.logAfterMs = ObservableValue.from(options.logAfterMs ?? 20);
+      this.validateVirtualDocuments = ObservableValue.from(options.validateVirtualDocuments ?? false);
+      this.validateSyntheticNodes = ObservableValue.from(options.validateSyntheticNodes ?? false);
+   }
+
+   override validateDocument(
+      document: LangiumDocument,
+      options?: ValidationOptions,
+      cancelToken?: CancellationToken
+   ): Promise<Diagnostic[]> {
+      // Skip whole virtual documents (stdlib / library / built-in) unless opted
+      // in — a virtual URI cannot be opened, so diagnostics on it are
+      // un-actionable. Decided per document (not per node) so the walk is
+      // avoided entirely; the per-node `$synthetic` skip is separate.
+      if (isVirtualUri(document.uri) && !this.validateVirtualDocuments.value) {
+         this.tracer.withUri(document.uri.toString()).debug('skipping validation (virtual document)');
+         return Promise.resolve([]);
+      }
+      const level = this.logLevel.value;
+      if (level === 'off') {
+         return super.validateDocument(document, options, cancelToken);
+      }
+      // `level` is narrowed to `LogLevel` past the early-return.
+      return this.tracer
+         .withUri(document.uri.toString())
+         .time('validateDocument', () => super.validateDocument(document, options, cancelToken), level, {
+            logAfterMs: this.logAfterMs.value
+         });
+   }
+
+   /**
+    * Skip validation for a node **and its children** when
+    * {@link shouldSkipValidation} returns true.
+    */
+   protected override validateSingleNodeOptions(node: AstNode, options: ValidationOptions): ValidateSingleNodeOptions {
+      if (this.shouldSkipValidation(node)) {
+         return { validateNode: false, validateChildren: false };
+      }
+      return super.validateSingleNodeOptions(node, options);
+   }
+
+   /**
+    * True when validation should skip `node` and its children. Default: the
+    * node is marked synthetic ({@link isSyntheticNode}) and
+    * {@link DocumentValidatorOptions.validateSyntheticNodes} has not opted back
+    * in — so the option and the predicate are one decision, not two. Adopters
+    * override to compose additional skip reasons with
+    * `super.shouldSkipValidation(node) || ...`.
+    */
+   protected shouldSkipValidation(node: AstNode): boolean {
+      return !this.validateSyntheticNodes.value && isSyntheticNode(node);
+   }
+
+   protected override toDiagnostic<N extends AstNode>(
+      severity: ValidationSeverity,
+      message: string,
+      info: DiagnosticInfo<N, string>
+   ): TransferLspDiagnostic {
+      const base = super.toDiagnostic(severity, message, info);
+      const node = info.node;
+      if (!node) {
+         this.tracer.warn('Cannot create diagnostic element path: DiagnosticInfo has no node.');
+         return { ...base, property: info.property, element: '' };
+      }
+      const elementPath = this.buildElementPath(node, info);
+      return { ...base, property: info.property, element: elementPath };
+   }
+
+   /**
+    * Construct the `element` path for a diagnostic. Falls back through:
+    * - the node's own AST path, then
+    * - the parent's AST path (for nodes Langium can't locate directly, e.g.
+    *   references or transient nodes).
+    *
+    * When the path doesn't include the array index (some reference-array
+    * cases) but `info.index` is provided, the index is appended explicitly
+    * — keeping element paths stable and consistent with how the client
+    * expects collection-item paths to be formed.
+    */
+   protected buildElementPath<N extends AstNode>(node: N, info: DiagnosticInfo<N, string>): string {
+      const directPath = this.astNodeLocator.getAstNodePath(node);
+      const containerPath = directPath ? undefined : this.astNodeLocator.getAstNodePath(node.$container ?? ({ $type: 'Dummy' } as AstNode));
+      const nodePath = directPath || containerPath;
+      if (!nodePath) {
+         this.tracer.warn('Cannot create diagnostic element path: Unable to determine AST node path.');
+         return '';
+      }
+      if (info.index === undefined || nodePath.endsWith(`${TransferDiagnostic.ELEMENT_INDEX_SEPARATOR}${info.index}`)) {
+         return nodePath;
+      }
+      return info.property
+         ? `${nodePath}${TransferDiagnostic.ELEMENT_SEGMENT_SEPARATOR}${info.property}${TransferDiagnostic.ELEMENT_INDEX_SEPARATOR}${info.index}`
+         : `${nodePath}${TransferDiagnostic.ELEMENT_INDEX_SEPARATOR}${info.index}`;
+   }
+}

package/src/langium/validation/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 './document-validator.js';
+export * from './validation-contribution.js';
+export * from './validation-contribution-collector.js';

package/src/langium/validation/validation-contribution-collector.ts

@@ -0,0 +1,61 @@
+/********************************************************************************
+ * 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 Tracer } from '@hydranium/protocol';
+import { type ValidationCategory, type ValidationChecks, type ValidationRegistry } from '@hydranium/langium';
+import { type LogNameOptions } from '../diagnostics/logger.js';
+import { type ServerLanguageServices } from '../language-module.js';
+import { type ValidationCheckRegistry } from './validation-contribution.js';
+
+export type ValidationContributionCollectorOptions = LogNameOptions;
+
+/**
+ * Per-language eager collector that wires `ValidationCheckContribution`s
+ * declared under `services.validation.checks` into Langium's native
+ * `ValidationRegistry`.
+ *
+ * Acts as the validation-side analog of the build-side
+ * `BuildPipelineIntegration` routing: at construction time it iterates the
+ * language's `validation.checks` contribution group, hands each contribution a
+ * thin {@link ValidationCheckRegistry} adapter, and the contribution registers
+ * its checks through it.
+ *
+ * Constructed on first per-language services access (typically forced by
+ * `BuildPipelineIntegration` touching the language services tree at the first
+ * build event); subsequent touches return the cached singleton from Langium's
+ * DI proxy. That is what gets the checks into the registry before Langium
+ * reaches the `Validated` phase — nothing else constructs this service.
+ */
+export class ValidationContributionCollector {
+   protected readonly tracer: Tracer;
+
+   constructor(services: ServerLanguageServices, options: ValidationContributionCollectorOptions = {}) {
+      this.tracer = services.shared.Tracer.for(options.logName ?? 'ValidationContributions').trace('instantiated');
+      const registry = createValidationCheckRegistry(services.validation.ValidationRegistry);
+      // Optional chaining tolerates incomplete test stubs; production
+      // wiring always provides the slot via `createServerLanguageModule`.
+      const contributions = services.validation?.checks ?? {};
+      for (const contribution of Object.values(contributions)) {
+         contribution.registerValidationChecks(registry);
+      }
+   }
+}
+
+/**
+ * Build a {@link ValidationCheckRegistry} adapter over Langium's
+ * `ValidationRegistry.register` — a pass-through, so `thisObj` and `category`
+ * must be forwarded rather than dropped.
+ */
+function createValidationCheckRegistry(langiumRegistry: ValidationRegistry): ValidationCheckRegistry {
+   return {
+      register<T>(checks: ValidationChecks<T>, thisObj?: ThisParameterType<unknown>, category?: ValidationCategory): void {
+         langiumRegistry.register(checks, thisObj, category);
+      }
+   };
+}

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

@@ -0,0 +1,38 @@
+/********************************************************************************
+ * 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 ValidationCategory, type ValidationChecks } from '@hydranium/langium';
+
+/**
+ * Registry handed to a {@link ValidationCheckContribution}. A thin wrapper over
+ * Langium's `ValidationRegistry.register` — the same type-keyed,
+ * category-scheduled check map underneath, so two contributions registering a
+ * check for the same node type both run (the registry stores checks in a
+ * `MultiMap`, which appends).
+ *
+ * `thisObj` mirrors Langium's signature: when a contribution passes check
+ * methods that read `this`, hand the contribution instance here so the binding
+ * is preserved.
+ */
+export interface ValidationCheckRegistry {
+   register<T>(checks: ValidationChecks<T>, thisObj?: ThisParameterType<unknown>, category?: ValidationCategory): void;
+}
+
+/**
+ * Declarative registration of validation checks. Bound under the module's
+ * `validation.checks` contribution group; a framework collector reads the group
+ * and calls this method, handing in a {@link ValidationCheckRegistry} that
+ * forwards to Langium's `ValidationRegistry`.
+ *
+ * The domain-qualified method name lets a single cross-cutting class implement
+ * several contribution interfaces without method collision.
+ */
+export interface ValidationCheckContribution {
+   registerValidationChecks(registry: ValidationCheckRegistry): void;
+}