@hydranium/core 1.0.0-next.4 → 1.0.0-next.40

package/src/langium/residency/cst-residency-service.ts

@@ -24,9 +24,13 @@ import { type ServerSharedServicesMinimal } from '../shared-services.js';
 /**
  * Default priority of the CST-residency pass. Deliberately very high so it runs
  * *last* among `Validated` build-phase passes (the registry iterates priority
- * ascending): every other reaction to the build — an adopter's own derived-state
- * pass included — settles while the CST is still guaranteed resident, before the
- * residency policy arms the shed.
+ * ascending).
+ *
+ * The ordering is defensive, not load-bearing: the pass only arms or cancels an
+ * idle timer, so every pass at `Validated` reads a resident CST whichever order
+ * they run in, and lowering it changes nothing observable while that holds. It
+ * becomes load-bearing the moment the shed stops being deferred — a pass that
+ * frees the CST synchronously has to run after every reader of it.
  */
 export const CST_RESIDENCY_PASS_PRIORITY = 1_000_000;
 
@@ -225,9 +229,29 @@ function rehydrateCst(document: LangiumDocument, factory: LangiumDocumentFactory
  * demand by the identity-preserving graft of {@link rehydrateNode} /
  * {@link rehydrate}, driven transparently from the framework
  * `NameProvider.getNameNode` chokepoint, the comment provider, and
- * `AbstractHydraniumLangiumDocuments.getOrCreateDocument`.
+ * `HydraniumLangiumDocuments.getOrCreateDocument`.
+ */
+/**
+ * Keeps a document's CST available to the readers that need one, shedding it
+ * for documents that have gone idle and re-grafting on demand.
  */
-export class CstResidencyService {
+export interface CstResidencyService {
+   /**
+    * Ensure `document` has a CST, re-parsing its retained text if it was shed.
+    * A resident document is left exactly as it is, so this is safe to call on
+    * a hot path and safe to call twice.
+    */
+   rehydrate(document: LangiumDocument): void;
+
+   /**
+    * Node-level convenience over {@link rehydrate}, cheap enough for an
+    * unconditional call: a node whose `$cstNode` is already set returns
+    * without resolving its document.
+    */
+   rehydrateNode(node: AstNode): void;
+}
+
+export class DefaultCstResidencyService implements CstResidencyService {
    protected readonly strategy: CstResidencyStrategy;
    /** Bytes-per-node for the optional reclaim estimate in traces; `0` disables it. */
    protected readonly estimatedBytesPerShedNode: number;
@@ -277,8 +301,8 @@ export class CstResidencyService {
     * until navigation latency on shed files is actually observed to hurt. This
     * method is where that hook goes.
     */
-   rehydrate(document: LangiumDocument): boolean {
-      return rehydrateCst(document, this.services.workspace.LangiumDocumentFactory);
+   rehydrate(document: LangiumDocument): void {
+      rehydrateCst(document, this.services.workspace.LangiumDocumentFactory);
    }
 
    /**
@@ -287,11 +311,11 @@ export class CstResidencyService {
     * `true` without even resolving the document, so hot read paths
     * (`getNameNode`, comment lookup) call this unconditionally.
     */
-   rehydrateNode(node: AstNode): boolean {
+   rehydrateNode(node: AstNode): void {
       if (node.$cstNode !== undefined) {
-         return true;
+         return;
       }
-      return this.rehydrate(AstUtils.getDocument(node));
+      this.rehydrate(AstUtils.getDocument(node));
    }
 
    /**
@@ -353,8 +377,8 @@ export class CstResidencyService {
       this.shedTotal += this.shed(document);
    }
 
-   /** Cancel and drop every idle timer — for clean shutdown and deterministic tests. */
-   dispose(): void {
+   /** Cancel every armed shed, so a document that has gone idle keeps its CST. */
+   cancelPendingShed(): void {
       for (const timer of this.idleTimers.values()) {
          timer.dispose();
       }

package/src/langium/scope/hydranium-scope-provider.ts

@@ -24,7 +24,6 @@ import {
    type AstNodeLocator,
    AstUtils,
    DefaultScopeProvider,
-   type LangiumDocuments,
    MapScope,
    type ReferenceInfo,
    type Scope,
@@ -35,9 +34,11 @@ import {
    WorkspaceCache,
    stream
 } from '@hydranium/langium';
+import { buildAstNode } from '../ast-extension/ast-node-builder.js';
 import { type LogNameOptions } from '../diagnostics/logger.js';
 import { type HydraniumLanguageServices } from '../language-module.js';
 import { type NameProvider } from '../naming/name-provider.js';
+import { type HydraniumDocumentRegistry } from '../workspace/langium-documents.js';
 import { type ScopeExtensionService } from './scope-extension-service.js';
 import { isTieredDescription } from './scoped-ast-node-description.js';
 
@@ -143,7 +144,7 @@ export interface ScopeContext {
  * `reference-candidate-provider.ts` module.
  */
 export class HydraniumScopeProvider extends DefaultScopeProvider {
-   protected readonly langiumDocuments: LangiumDocuments;
+   protected readonly langiumDocuments: HydraniumDocumentRegistry;
    protected readonly astNodeLocator: AstNodeLocator;
    protected readonly scopeExtensionService: ScopeExtensionService;
    protected readonly options: HydraniumScopeProviderOptions;
@@ -469,12 +470,13 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
     * Convert a protocol-layer {@link ReferenceContext} into a Langium
     * {@link ReferenceInfo} the rest of the scope/linking machinery accepts.
     *
-    * Walks `syntheticPath` by FABRICATING a type-only stub per step, so a
-    * scope can be queried for an element that does not exist yet — which is
-    * what synthetic paths are for. The stubs carry no children, so a caller
-    * that needs to read a collection off the leaf wants
-    * {@link resolveReferenceSource} instead, which walks the same path into
-    * the real tree.
+    * Walks `syntheticPath` by FABRICATING a stub per step, so a scope can be
+    * queried for an element that does not exist yet — which is what synthetic
+    * paths are for. A stub carries the grammar's declared defaults and nothing
+    * else, so its containment lists are present but EMPTY: a caller that needs
+    * to read a populated collection off the leaf wants
+    * {@link resolveReferenceSource} instead, which walks the same path into the
+    * real tree.
     *
     * Throws if the context references an unresolvable source; callers
     * that prefer a soft failure should catch and fall back to
@@ -486,16 +488,15 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
          throw new Error('Invalid reference source');
       }
       for (const step of ctx.syntheticPath ?? []) {
-         container = {
+         container = buildAstNode(this.services.shared.AstReflection, step.type, {
             $container: container,
             $containerProperty: step.containerProperty,
             // Part of Langium's own container contract, so a stub that omits it
             // is an under-specified node: anything reading position off the
             // chain (a key provider, an adopter scope extension) sees
             // `undefined` where the caller named a slot.
-            $containerIndex: step.index,
-            $type: step.type
-         };
+            $containerIndex: step.index
+         });
       }
       return {
          reference: { $refText: '', ref: undefined },
@@ -586,18 +587,35 @@ export class HydraniumScopeProvider extends DefaultScopeProvider {
    }
 
    /**
-    * Build a transient AST-node stub for a {@link SyntheticSource} request.
-    * Default: looks up the document via `LangiumDocuments` and uses its parse
-    * root as the container; returns `undefined` if the document isn't loaded.
-    * Consumers that need to materialise an empty document on demand (e.g.
-    * to query the scope before a file exists) override this.
+    * Build a transient AST-node stub for a {@link SyntheticSource} request: a
+    * node of the requested type, contained by the document at `source.uri`.
+    *
+    * **The container is materialised when no document is loaded there**, which
+    * is the case the source type exists for — a `SyntheticSource` names a node
+    * that does not exist yet, and the create-element flow asks at the FOLDER
+    * the file is about to be written into. Abstaining there would answer an
+    * empty candidate list, which a client cannot tell from "nothing matches".
+    *
+    * The stand-in parses under THIS provider's grammar, because a folder URI
+    * carries no extension for the routing ladder to end on and this provider is
+    * bound per grammar. Reaching for `createEmptyDocument(uri)` without the id
+    * instead fails inside the parse, on an empty extension rather than on the
+    * URI.
+    *
+    * The materialised document is unregistered and transient; see
+    * `createEmptyDocument`. Overriding is still open to a consumer whose
+    * "container" is an inner element rather than the parse root, or one that
+    * deliberately declines to answer for an absent document.
+    *
+    * The stub carries the grammar's declared defaults, so an extension reading a
+    * containment list off it sees an empty array rather than `undefined`.
     */
    protected resolveSyntheticSource(source: SyntheticSource): AstNode | undefined {
-      const document = this.langiumDocuments.getDocument(UriUtils.toUri(source.uri));
-      if (!document) {
-         return undefined;
-      }
-      return { $type: source.type, $container: document.parseResult.value };
+      const uri = UriUtils.toUri(source.uri);
+      const document =
+         this.langiumDocuments.getDocument(uri) ??
+         this.langiumDocuments.createEmptyDocument(uri, this.services.LanguageMetaData.languageId);
+      return buildAstNode(this.services.shared.AstReflection, source.type, { $container: document.parseResult.value });
    }
 
    /**

package/src/langium/shared-services.ts

@@ -9,8 +9,11 @@
 
 import type { Clock, Logger, Project, Tracer } from '@hydranium/protocol';
 import type { LangiumSharedCoreServices } from '@hydranium/langium';
+import type { ServerLocale } from '../locale/server-locale.js';
+import type { MessageRenderer } from '../messages/renderer.js';
 import type { SelfSaveRegistry } from '../documents/self-save-registry.js';
 import type { WritableFileSystemProvider } from '../documents/ast-document-manager.js';
+import type { HydraniumDocumentRegistry } from './workspace/langium-documents.js';
 import type { BuildPhasePassService } from './build-phase-pass/build-phase-pass-service.js';
 import type { CstResidencyService } from './residency/cst-residency-service.js';
 import type { BuildPipelineIntegration } from './document-builder/build-pipeline-integration.js';
@@ -27,8 +30,9 @@ import type { AdditionalDocumentContribution } from './workspace/additional-docu
  * framework additions that other framework services consume: the dedicated
  * {@link Clock}, {@link Logger} and {@link Tracer} top-level slots (injectable
  * time source, emission-only logger, and the measure-and-emit tracer composed
- * from the other two), the {@link AdditionalDocumentContribution} group, an
- * {@link ExtendedServiceRegistry}, and on `workspace` a writable file-system
+ * from the other two), the {@link AdditionalDocumentContribution} group, the
+ * {@link MessageRenderer} and the {@link ServerLocale} it renders in,
+ * an {@link ExtendedServiceRegistry}, and on `workspace` a writable file-system
  * provider plus {@link HydraniumWorkspaceManager}, {@link ProjectManager},
  * {@link SelfSaveRegistry}, {@link BuildPipelineIntegration},
  * {@link BuildPhasePassService}, {@link CstResidencyService} and
@@ -57,6 +61,14 @@ export interface ServerSharedServicesMinimal<TProject extends Project = Project>
     * adopters deep-merge contributions that seed built-in / stdlib documents.
     */
    additionalDocuments: Record<string, AdditionalDocumentContribution>;
+   /**
+    * Renders each user-facing message once, before the server sends it. On the
+    * shared tier with no workspace dependency, because all three heads'
+    * messages pass through it.
+    */
+   MessageRenderer: MessageRenderer;
+   /** The locale an init handed the server, for whoever renders in it. */
+   ServerLocale: ServerLocale;
    /**
     * Narrows Langium's base `ServiceRegistry` slot to the framework impl the
     * framework always binds, so the abstaining lookups — `getServicesFor`
@@ -75,6 +87,11 @@ export interface ServerSharedServicesMinimal<TProject extends Project = Project>
       // framework always binds, so `wsRelativePath` and the folder-walk are
       // reachable from the minimal surface without a cast.
       WorkspaceManager: HydraniumWorkspaceManager;
+      // Same, for the registry: the framework always binds
+      // `HydraniumLangiumDocuments`, and `createEmptyDocument` is reachable
+      // only through this narrowing — a scope provider querying a URI before
+      // the file exists is the caller that needs it.
+      /* override */ LangiumDocuments: HydraniumDocumentRegistry;
       ProjectManager: ProjectManager<TProject>;
       SelfSaveRegistry: SelfSaveRegistry;
       BuildPipelineIntegration: BuildPipelineIntegration;

package/src/langium/transfer/transfer-encoder.ts

@@ -8,6 +8,7 @@
  ********************************************************************************/
 
 import {
+   hasMessageIdentity,
    type Tracer,
    type TransferDiagnostic,
    type TransferElement,
@@ -79,6 +80,37 @@ export interface TransferEnvelopeSource<TDiagnostic> {
    readonly diagnostics: readonly (TDiagnostic | Diagnostic)[];
 }
 
+/**
+ * The AST→transfer contract a DI slot holds, implemented by
+ * {@link DefaultTransferEncoder}.
+ *
+ * **This is an interface and not the class, and that is load-bearing.** A class
+ * in a slot drags its `protected` members into every assignability check, which
+ * TypeScript compares NOMINALLY — so the slot type could not be satisfied by a
+ * subclass declared against a second physical copy of this package, and an
+ * adopter narrowing the slot had to intersect with the framework's declaration
+ * rather than replace it, leaving method resolution dependent on declaration
+ * order. An interface has no protected members and is compared structurally, so
+ * neither applies.
+ *
+ * **The transfer returns are the structural base ({@link TransferElement}), not
+ * the per-grammar overlay.** The overlay cannot parameterise this contract:
+ * `TransferTypeFor` reaches `keyof TTransferMap`, which makes that parameter
+ * measured-INVARIANT, and invariant parameters relate only when their arguments
+ * are mutually assignable — so a map-parameterised contract admits no adopter
+ * instantiation at all. Heads read this contract and do not know adopter maps;
+ * an adopter recovers the precise type by declaring its own slot, which it can
+ * now do by replacement.
+ */
+export interface TransferEncoder<TDiagnostic extends TransferDiagnostic = TransferDiagnostic> {
+   toTransfer<T extends AstNode>(ast: T, mode?: TransferMode): TransferElement;
+   toTransferDocument(langiumDocument: LangiumDocument): TransferDocument<TransferElement, TDiagnostic>;
+   astDocumentToTransferDocument<TAst extends AstNode>(
+      document: AstDocument<TAst, TDiagnostic | TransferLspDiagnostic>
+   ): TransferDocument<TransferElement, TDiagnostic>;
+   toTransferDiagnostic(diagnostic: TransferLspDiagnostic): TDiagnostic;
+}
+
 /**
  * One-directional structural mapper from a Langium AST into the wire
  * transfer-model shape ({@link TransferElement}-based JSON).
@@ -123,7 +155,7 @@ export interface TransferEnvelopeSource<TDiagnostic> {
  * - {@link toTransferDiagnostic} — project a {@link TransferLspDiagnostic}
  *   (the framework validator's output) to {@link TDiagnostic}.
  */
-export class TransferEncoder<
+export class DefaultTransferEncoder<
    // The map is intentionally unconstrained — adopters supply typed
    // overlays whose specific-key shapes don't structurally satisfy a
    // `Record<string, TransferElement>` index signature. `TransferTypeFor`
@@ -387,7 +419,10 @@ export class TransferEncoder<
     * LSP severity enum to the wire string union, discriminates the
     * diagnostic type from Langium's `data.code` (`'lexing-error'` /
     * `'parsing-error'` else `'validation-error'`), passes through
-    * message / element / property / code. Adopters whose validator
+    * message / element / property / code, and lifts the framework message
+    * params out of `data` so a translating surface can render a
+    * parameterised diagnostic rather than a template with its placeholders
+    * left standing. Adopters whose validator
     * doesn't decorate diagnostics with `element` still get a valid
     * `TransferDiagnostic` — the field falls back to `''`.
     *
@@ -396,6 +431,12 @@ export class TransferEncoder<
     */
    toTransferDiagnostic(diagnostic: TransferLspDiagnostic): TDiagnostic {
       const langiumCode = (diagnostic.data as { code?: string } | undefined)?.code;
+      // The same `data` the Langium code comes out of also carries the framework
+      // message identity, under its own key so the two conventions co-exist.
+      // Taking the params from there rather than from `code` is what lets a
+      // translating surface render a PARAMETERISED diagnostic: `code` survives on
+      // its own and yields a template with its placeholders left standing.
+      const identity = hasMessageIdentity(diagnostic.data) ? diagnostic.data.hydranium : undefined;
       const result: TransferDiagnostic = {
          type: langiumCode === 'lexing-error' ? 'lexing-error' : langiumCode === 'parsing-error' ? 'parsing-error' : 'validation-error',
          element: diagnostic.element ?? '',
@@ -408,7 +449,8 @@ export class TransferEncoder<
                : diagnostic.severity === DiagnosticSeverity.Warning
                  ? 'warning'
                  : 'info',
-         code: typeof diagnostic.code === 'number' || typeof diagnostic.code === 'string' ? diagnostic.code : langiumCode
+         code: typeof diagnostic.code === 'number' || typeof diagnostic.code === 'string' ? diagnostic.code : langiumCode,
+         params: identity?.params
       };
       return result as TDiagnostic;
    }

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

@@ -7,12 +7,23 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { type LogThreshold, type MaybeObservableValue, ObservableValue, type Tracer, TransferDiagnostic } from '@hydranium/protocol';
+import {
+   defineMessage,
+   describeError,
+   messageData,
+   type LogThreshold,
+   type MaybeObservableValue,
+   ObservableValue,
+   type Tracer,
+   TransferDiagnostic
+} from '@hydranium/protocol';
 import {
    type AstNode,
    type AstNodeLocator,
+   type AstReflection,
    DefaultDocumentValidator,
    type DiagnosticInfo,
+   DocumentValidator,
    type LangiumDocument,
    type LangiumCoreServices,
    type ValidateSingleNodeOptions,
@@ -20,21 +31,102 @@ import {
    type ValidationSeverity
 } from '@hydranium/langium';
 import type { CancellationToken } from 'vscode-languageserver-protocol';
-import type { Diagnostic } from 'vscode-languageserver-types';
+// A VALUE import, for `Diagnostic.getMessageString`: `message` is
+// `string | MarkupContent` in LSP 3.17+, so upstream's own reader is what
+// narrows it rather than a hand-rolled union check here.
+import { 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}.
+ * Diagnostic read off a `LangiumDocument`: an LSP {@link Diagnostic} that MAY
+ * carry the protocol-level `element` path and `property` name from
+ * {@link TransferDiagnostic}.
+ *
+ * `element` is optional because a document's diagnostics do not all come from
+ * this validator. {@link HydraniumDocumentValidator.toDiagnostic} always sets
+ * one, but Langium pushes lexer and parser errors straight onto the document
+ * without routing them through it, so a document that fails to parse carries
+ * diagnostics with no path at all. Treat it as absent, not empty.
+ *
+ * Narrowing `LangiumDocument.diagnostics` to this type instead is unavailable:
+ * declaration merging may add a member but not retype one, and augmenting the
+ * LSP `Diagnostic` reaches only one of the two declaration files its package
+ * ships, since the `exports` map splits `import` from `default` with no `types`
+ * condition. Consumers therefore cast at the read, and the cast is sound only
+ * because this field is optional.
  */
 export interface TransferLspDiagnostic extends Diagnostic {
-   element: string;
+   element?: string;
    property?: string;
 }
 
+/**
+ * A reference resolved to nothing.
+ *
+ * **The English is byte-identical to Langium's `DefaultLinker.createLinkingError`
+ * sentence, and must stay so.** The identity is attached to a diagnostic Langium
+ * already worded, so a divergence here would silently change the text every
+ * adopter without a catalogue sees. {@link HydraniumDocumentValidator.processLinkingErrors}
+ * attaches it only when the two match exactly, which is also what keeps an
+ * adopter's own reworded linking error from being mislabelled as this one.
+ *
+ * It exists because this is the most-seen validation error in any language built
+ * on the framework, and Langium puts its own code in `data.code` rather than on
+ * `Diagnostic.code` — so without a framework identity every adopter wanting to
+ * render it has to special-case Langium's shape.
+ */
+export const UNRESOLVED_REFERENCE = defineMessage(
+   'hydranium/core/unresolved-reference',
+   "Could not resolve reference to {referenceType} named '{refText}'."
+);
+
+/**
+ * A character no token of the grammar can start with.
+ *
+ * **The English is byte-identical to CHEVROTAIN's
+ * `defaultLexerErrorProvider.buildUnexpectedCharactersMessage`, and must stay
+ * so** — one layer further out than {@link UNRESOLVED_REFERENCE}, whose sentence
+ * is Langium's. Langium words neither: `processLexingErrors` copies
+ * `lexerDiagnostic.message` through untouched, so the text an adopter sees today
+ * is produced two dependencies down and is the only thing this identity may
+ * claim to be. {@link HydraniumDocumentValidator.identifyLexingError} attaches
+ * it only when the two match exactly, which is also what keeps a custom lexer's
+ * own diagnostics — Langium admits any of them through `lexerReport` — from
+ * being mislabelled as this one.
+ *
+ * It exists because a lexing error is the FIRST message a user of a new language
+ * sees and the one an adopter cannot reach: every other diagnostic worth
+ * translating either carries an identity already or is raised by adopter code,
+ * while this one arrives with a Langium `data.code` naming a KIND and no
+ * parameters at all — so a catalogue had nothing to key on and nothing to
+ * interpolate.
+ *
+ * `skipped` rather than `length`, matching what the sentence says the number
+ * means: chevrotain reports how many characters the lexer discarded to recover,
+ * which for a single stray character is one and for a run of them is the run.
+ */
+export const LEXING_ERROR = defineMessage(
+   'hydranium/core/lexing-error',
+   'unexpected character: ->{character}<- at offset: {offset}, skipped {skipped} characters.'
+);
+
+/**
+ * Langium's own `data.code` values for a diagnostic that came out of the lexer.
+ *
+ * All four severities, not just the error one: `lexerReport` admits warnings and
+ * below, and a token builder that downgrades a stray character still produces
+ * the same sentence. Gating on the error code alone would leave the identity off
+ * a message that is word-for-word the one it names.
+ */
+const LEXING_CODES: ReadonlySet<unknown> = new Set([
+   DocumentValidator.LexingError,
+   DocumentValidator.LexingWarning,
+   DocumentValidator.LexingInfo,
+   DocumentValidator.LexingHint
+]);
+
 export interface DocumentValidatorOptions extends LogNameOptions {
    /**
     * Level at which the `validateDocument` timing line is emitted, or `'off'`
@@ -81,6 +173,7 @@ export interface DocumentValidatorOptions extends LogNameOptions {
 export class HydraniumDocumentValidator extends DefaultDocumentValidator {
    protected readonly tracer: Tracer;
    protected readonly astNodeLocator: AstNodeLocator;
+   protected readonly reflection: AstReflection;
    protected readonly logLevel: ObservableValue<LogThreshold>;
    protected readonly logAfterMs: ObservableValue<number>;
    protected readonly validateVirtualDocuments: ObservableValue<boolean>;
@@ -90,6 +183,7 @@ export class HydraniumDocumentValidator extends DefaultDocumentValidator {
       super(services);
       this.tracer = services.shared.Tracer.for(options.logName ?? 'DocumentValidator').trace('instantiated');
       this.astNodeLocator = services.workspace.AstNodeLocator;
+      this.reflection = services.shared.AstReflection;
       this.logLevel = ObservableValue.from(options.logLevel ?? 'debug');
       this.logAfterMs = ObservableValue.from(options.logAfterMs ?? 20);
       this.validateVirtualDocuments = ObservableValue.from(options.validateVirtualDocuments ?? false);
@@ -111,16 +205,85 @@ export class HydraniumDocumentValidator extends DefaultDocumentValidator {
       }
       const level = this.logLevel.value;
       if (level === 'off') {
-         return super.validateDocument(document, options, cancelToken);
+         return this.validateAndIdentify(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, {
+         .time('validateDocument', () => this.validateAndIdentify(document, options, cancelToken), level, {
             logAfterMs: this.logAfterMs.value
          });
    }
 
+   /**
+    * Langium's validation pass, plus the framework identity on the lexing
+    * diagnostics it produced.
+    *
+    * **Here rather than in an override of `processLexingErrors`, and the reason
+    * is that the seam cannot see what the identity needs.** Langium hands that
+    * method a `ParseResult`, which carries the AST and the error lists but not
+    * the source text — and the offending CHARACTER is the parameter a
+    * translation exists to interpolate. The document does carry it, and this is
+    * the innermost point that still holds one. Reconstructing the character by
+    * matching it out of the finished sentence was the alternative, and it
+    * inverts the direction the rest of this file works in: every other identity
+    * here is derived from structured fields and CHECKED against the prose.
+    *
+    * Inside the timing span rather than around it, so the line accounts for the
+    * whole pass.
+    */
+   protected async validateAndIdentify(
+      document: LangiumDocument,
+      options?: ValidationOptions,
+      cancelToken?: CancellationToken
+   ): Promise<Diagnostic[]> {
+      const diagnostics = await super.validateDocument(document, options, cancelToken);
+      // Mapped in place over the array Langium built, rather than filtered and
+      // re-concatenated: the publish order is the diagnostic order and a
+      // reordering would move a squiggle's entry in the problems list.
+      for (let index = 0; index < diagnostics.length; index++) {
+         diagnostics[index] = this.identifyLexingError(document, diagnostics[index]);
+      }
+      return diagnostics;
+   }
+
+   /**
+    * Add the {@link LEXING_ERROR} identity to one diagnostic, or return it
+    * untouched when it is not the sentence that identity renders.
+    *
+    * The parameters come from the diagnostic's own RANGE, not from
+    * `parseResult.lexerErrors`. Both hold the same numbers, and the range is the
+    * one that needs no assumption about upstream: correlating the two lists
+    * would depend on Langium appending one diagnostic per lexer error in order,
+    * which is true today and is an internal of the method being wrapped.
+    *
+    * **The format-and-compare is the whole discriminator, and it validates the
+    * reconstruction as well as the identity.** A range that did not round-trip
+    * to the offset chevrotain reported would produce a different sentence and be
+    * declined, so a wrong parameter set can never be attached to a right-looking
+    * message.
+    */
+   protected identifyLexingError(document: LangiumDocument, diagnostic: Diagnostic): Diagnostic {
+      const data = diagnostic.data as { code?: unknown } | undefined;
+      if (!LEXING_CODES.has(data?.code)) {
+         return diagnostic;
+      }
+      const text = document.textDocument;
+      const offset = text.offsetAt(diagnostic.range.start);
+      const params = {
+         character: text.getText().charAt(offset),
+         offset,
+         skipped: text.offsetAt(diagnostic.range.end) - offset
+      };
+      if (Diagnostic.getMessageString(diagnostic) !== LEXING_ERROR.format(params)) {
+         return diagnostic;
+      }
+      // Merged OVER Langium's data, so `data.code` survives for the readers that
+      // switch on it — `stopAfterLexingErrors` is one, and the GLSP head's
+      // read-only decision is another.
+      return { ...diagnostic, code: LEXING_ERROR.code, data: { ...data, ...messageData(LEXING_ERROR, params) } };
+   }
+
    /**
     * Skip validation for a node **and its children** when
     * {@link shouldSkipValidation} returns true.
@@ -144,6 +307,90 @@ export class HydraniumDocumentValidator extends DefaultDocumentValidator {
       return !this.validateSyntheticNodes.value && isSyntheticNode(node);
    }
 
+   /**
+    * Langium's linking-error pass, plus the framework identity on each
+    * diagnostic it produced.
+    *
+    * Langium puts its own `linking-error` marker in `data.code` and leaves
+    * `Diagnostic.code` unset, so nothing identifies the message on a surface
+    * that drops `data` — which is every editor surface. This adds the framework
+    * identity to both `code` and `data.hydranium` while LEAVING `data.code` in
+    * place: `stopAfterLinkingErrors` and Langium's code-action dispatch both
+    * read it.
+    *
+    * **The identity is attached only when the message is the one
+    * {@link UNRESOLVED_REFERENCE} renders.** Two other sentences reach this
+    * list: the linker's exception form, raised when resolution itself throws,
+    * and whatever an adopter overriding `createLinkingError` chose. Labelling
+    * either would make a catalogue render the wrong sentence — and for the
+    * exception form it would discard the underlying cause. Comparing against
+    * the locally rendered English is what discriminates; there is no structural
+    * field that does.
+    */
+   protected override processLinkingErrors(document: LangiumDocument, diagnostics: Diagnostic[], options: ValidationOptions): void {
+      const from = diagnostics.length;
+      super.processLinkingErrors(document, diagnostics, options);
+      for (let index = from; index < diagnostics.length; index++) {
+         diagnostics[index] = this.identifyLinkingError(diagnostics[index]);
+      }
+   }
+
+   /**
+    * Add the {@link UNRESOLVED_REFERENCE} identity to one linking diagnostic,
+    * or return it untouched when its message is not the sentence that identity
+    * renders.
+    *
+    * `refText` comes from the `data` Langium populated; `referenceType` is not
+    * in it, so it is recovered the same way `createLinkingError` produced it —
+    * through the reflection, from the container type and property.
+    */
+   protected identifyLinkingError(diagnostic: Diagnostic): Diagnostic {
+      const data = diagnostic.data as { code?: unknown; refText?: unknown; containerType?: unknown; property?: unknown } | undefined;
+      if (typeof data?.refText !== 'string' || typeof data.containerType !== 'string' || typeof data.property !== 'string') {
+         return diagnostic;
+      }
+      const referenceType = this.referenceTypeOf(data.containerType, data.property, data.refText);
+      if (referenceType === undefined) {
+         return diagnostic;
+      }
+      const params = { referenceType, refText: data.refText };
+      if (diagnostic.message !== UNRESOLVED_REFERENCE.format(params)) {
+         return diagnostic;
+      }
+      // Merged OVER Langium's data rather than replacing it, so `data.code`
+      // survives for the readers that switch on it.
+      return { ...diagnostic, code: UNRESOLVED_REFERENCE.code, data: { ...data, ...messageData(UNRESOLVED_REFERENCE, params) } };
+   }
+
+   /**
+    * The declared target type of the reference this diagnostic came from, or
+    * `undefined` when the reflection cannot name one.
+    *
+    * **The lookup can throw, and that is the reason this is a method rather
+    * than an inline call.** `AbstractAstReflection.getReferenceType` raises on
+    * an unknown container `$type` and on a property that is not a reference —
+    * and the linking error whose type it cannot name is the one most likely to
+    * reach here, because `DefaultLinker` catches its OWN failed lookup and
+    * turns it into the exception-form message. Rethrowing would take
+    * `validateDocument` with it, since Langium wraps `processLinkingErrors` in
+    * no try: a diagnostic Langium degraded gracefully would become a failed
+    * build. Declining is also the right answer on the merits — a reference
+    * whose type cannot be named is not the message
+    * {@link UNRESOLVED_REFERENCE} claims.
+    */
+   protected referenceTypeOf(containerType: string, property: string, refText: string): string | undefined {
+      try {
+         return this.reflection.getReferenceType({
+            container: { $type: containerType } as AstNode,
+            property,
+            reference: { $refText: refText }
+         } as Parameters<AstReflection['getReferenceType']>[0]);
+      } catch (err: unknown) {
+         this.tracer.debug(`cannot name the reference type for ${containerType}.${property}: ${describeError(err)}`);
+         return undefined;
+      }
+   }
+
    protected override toDiagnostic<N extends AstNode>(
       severity: ValidationSeverity,
       message: string,