@hydranium/core 1.0.0-next.36 → 1.0.0-next.360

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

@@ -10,7 +10,12 @@
 import {
    defineMessage,
    describeError,
+   interpolate,
+   type MessageDefinition,
+   type MessageParams,
    messageData,
+   type ParamsArg,
+   type ParamsOf,
    type LogThreshold,
    type MaybeObservableValue,
    ObservableValue,
@@ -26,13 +31,14 @@ import {
    DocumentValidator,
    type LangiumDocument,
    type LangiumCoreServices,
+   type Lexer,
    type ValidateSingleNodeOptions,
    type ValidationOptions,
    type ValidationSeverity
 } from '@hydranium/langium';
 import type { CancellationToken } from 'vscode-languageserver-protocol';
 // A VALUE import, for `Diagnostic.getMessageString`: `message` is
-// `string | MarkupContent` in LSP 3.17+, so upstream's own reader is what
+// `string | MarkupContent` since LSP 3.18, 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';
@@ -40,9 +46,15 @@ import { isSyntheticNode } from '../workspace/synthetic.js';
 import { isVirtualUri } from '../workspace/virtual-document.js';
 
 /**
- * Diagnostic read off a `LangiumDocument`: an LSP {@link Diagnostic} that MAY
- * carry the protocol-level `element` path and `property` name from
- * {@link TransferDiagnostic}.
+ * The AST-layer diagnostic: what the build left on `LangiumDocument`, and what
+ * an `AstDocument` carries. An LSP {@link Diagnostic} that MAY also carry the
+ * `element` path and `property` name from {@link TransferDiagnostic}.
+ *
+ * **Not interchangeable with {@link TransferDiagnostic}, which is the other end
+ * of the same conversion.** They disagree on field types as well as on which
+ * fields exist — `severity` is LSP's numeric enum here and a string union there
+ * — so a slot typed with the wrong one still accepts the value and then reads
+ * `undefined`, or compares equal to nothing.
  *
  * `element` is optional because a document's diagnostics do not all come from
  * this validator. {@link HydraniumDocumentValidator.toDiagnostic} always sets
@@ -57,7 +69,7 @@ import { isVirtualUri } from '../workspace/virtual-document.js';
  * condition. Consumers therefore cast at the read, and the cast is sound only
  * because this field is optional.
  */
-export interface TransferLspDiagnostic extends Diagnostic {
+export interface AstDiagnostic extends Diagnostic {
    element?: string;
    property?: string;
 }
@@ -107,11 +119,117 @@ export const UNRESOLVED_REFERENCE = defineMessage(
  * 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',
+export const UNEXPECTED_CHARACTER = defineMessage(
+   'hydranium/core/unexpected-character',
    'unexpected character: ->{character}<- at offset: {offset}, skipped {skipped} characters.'
 );
 
+/**
+ * A token the grammar does not admit at this position.
+ *
+ * **The English is byte-identical to Langium's
+ * `LangiumParserErrorMessageProvider.buildMismatchTokenMessage`, and must stay
+ * so**, on the same rule as {@link UNRESOLVED_REFERENCE}.
+ *
+ * `expected` is a token type name, which is grammar vocabulary rather than
+ * translatable text — only the frame around it is. Promoting it into the code
+ * instead would make the catalogue as large as the grammar.
+ */
+export const UNEXPECTED_TOKEN = defineMessage(
+   'hydranium/core/unexpected-token',
+   "Expecting token of type '{expected}' but found `{found}`."
+);
+
+/**
+ * Input left over once the entry rule had matched.
+ *
+ * **The English is byte-identical to Langium's
+ * `LangiumParserErrorMessageProvider.buildNotAllInputParsedMessage`, and must
+ * stay so.**
+ */
+export const TRAILING_INPUT = defineMessage('hydranium/core/trailing-input', 'Expecting end of file but found `{found}`.');
+
+/**
+ * A mode-popping token reached with nothing on the lexer's mode stack.
+ *
+ * **The English is byte-identical to CHEVROTAIN's
+ * `defaultLexerErrorProvider.buildUnableToPopLexerModeMessage`, and must stay
+ * so**, the closing clause running on without punctuation exactly as upstream
+ * writes it.
+ *
+ * Reachable only from a multi-mode lexer, which a grammar opts into through a
+ * custom token builder.
+ */
+export const UNPOPPABLE_LEXER_MODE = defineMessage(
+   'hydranium/core/unpoppable-lexer-mode',
+   'Unable to pop Lexer Mode after encountering Token ->{image}<- The Mode Stack is empty'
+);
+
+/**
+ * A dedent that lines up with no enclosing indentation level.
+ *
+ * **The English is byte-identical to LANGIUM's `IndentationAwareTokenBuilder`,
+ * and must stay so** — the one lexing sentence Langium words itself rather than
+ * relaying from chevrotain, which is why it renders through no
+ * `ILexerErrorMessageProvider` and an adopter cannot reach it by replacing one.
+ *
+ * `stack` is the indentation stack as the template literal upstream stringifies
+ * it, comma-joined: structure would have to survive {@link MessageParams}, which
+ * holds scalars, and a translation has nothing to say about the numbers anyway.
+ */
+export const INVALID_DEDENT = defineMessage(
+   'hydranium/core/invalid-dedent',
+   'Invalid dedent level {level} at offset: {offset}. Current indentation stack: {stack}'
+);
+
+/**
+ * A position where none of a rule's alternatives can start.
+ *
+ * **The English is byte-identical to CHEVROTAIN's
+ * `defaultParserErrorProvider.buildNoViableAltMessage`, and must stay so** —
+ * one layer further out than {@link UNEXPECTED_TOKEN}, because Langium overrides
+ * only two of the four parser sentences and passes this one straight through.
+ *
+ * `sequences` is the token-sequence list chevrotain generated, carried whole
+ * rather than as structure: {@link MessageParams} holds scalars, and the list is
+ * token names in any case, so only the frame around it is translatable.
+ */
+export const NO_VIABLE_ALTERNATIVE = defineMessage(
+   'hydranium/core/no-viable-alternative',
+   "Expecting: one of these possible Token sequences:\n{sequences}\nbut found: '{found}'"
+);
+
+/**
+ * A repetition that had to match at least once and matched nothing.
+ *
+ * **The English is byte-identical to CHEVROTAIN's
+ * `defaultParserErrorProvider.buildEarlyExitMessage`, and must stay so**,
+ * including the doubled colon after `sequences::`, which is upstream's and not a
+ * typo to repair here — a divergence would silently stop the identity attaching.
+ *
+ * Named for the empty repetition rather than for chevrotain's `EarlyExit`, which
+ * describes its own control flow rather than the reader's problem.
+ */
+export const MISSING_ITERATION = defineMessage(
+   'hydranium/core/missing-iteration',
+   "Expecting: expecting at least one iteration which starts with one of these possible Token sequences::\n  <{sequences}>\nbut found: '{found}'"
+);
+
+/**
+ * The two sentences whose only free parameter is a generated list, in the order
+ * {@link HydraniumDocumentValidator.identifyParsingError} tries them. Order is
+ * free: their frames share a prefix but diverge before the list begins, so at
+ * most one can match.
+ */
+const SEQUENCE_LISTING_MESSAGES = [NO_VIABLE_ALTERNATIVE, MISSING_ITERATION];
+
+/**
+ * Splits a template into alternating frame and placeholder NAME, for
+ * {@link HydraniumDocumentValidator.sliceFramed}. The capturing group is what
+ * keeps the names in the result rather than discarding them.
+ */
+const PLACEHOLDER_CAPTURE = /\{([^}]+)\}/;
+
 /**
  * Langium's own `data.code` values for a diagnostic that came out of the lexer.
  *
@@ -165,7 +283,7 @@ export interface DocumentValidatorOptions extends LogNameOptions {
  * - **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
+ *   {@link AstDiagnostic}: 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.
@@ -174,6 +292,12 @@ export class HydraniumDocumentValidator extends DefaultDocumentValidator {
    protected readonly tracer: Tracer;
    protected readonly astNodeLocator: AstNodeLocator;
    protected readonly reflection: AstReflection;
+   protected readonly lexer: Lexer;
+   /**
+    * {@link tokenTypeNames}' answer. Nothing invalidates it: the vocabulary
+    * comes from the grammar, which is fixed once the DI tree is composed.
+    */
+   protected expectedNames?: readonly string[];
    protected readonly logLevel: ObservableValue<LogThreshold>;
    protected readonly logAfterMs: ObservableValue<number>;
    protected readonly validateVirtualDocuments: ObservableValue<boolean>;
@@ -184,6 +308,7 @@ export class HydraniumDocumentValidator extends DefaultDocumentValidator {
       this.tracer = services.shared.Tracer.for(options.logName ?? 'DocumentValidator').trace('instantiated');
       this.astNodeLocator = services.workspace.AstNodeLocator;
       this.reflection = services.shared.AstReflection;
+      this.lexer = services.parser.Lexer;
       this.logLevel = ObservableValue.from(options.logLevel ?? 'debug');
       this.logAfterMs = ObservableValue.from(options.logAfterMs ?? 20);
       this.validateVirtualDocuments = ObservableValue.from(options.validateVirtualDocuments ?? false);
@@ -216,18 +341,22 @@ export class HydraniumDocumentValidator extends DefaultDocumentValidator {
    }
 
    /**
-    * Langium's validation pass, plus the framework identity on the lexing
-    * diagnostics it produced.
+    * Langium's validation pass, plus the framework identity on the lexing and
+    * parsing diagnostics it produced.
+    *
+    * **Here rather than in an override of `processLexingErrors` /
+    * `processParsingErrors`, and the reason is that neither seam can see what
+    * the identity needs.** Langium hands them a `ParseResult`, which carries the
+    * AST and the error lists but not the source text — and the offending
+    * CHARACTER, or the offending TOKEN, is the parameter a translation exists to
+    * interpolate. The document does carry it, and this is the innermost point
+    * that still holds one.
     *
-    * **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.
+    * Correlating the finished diagnostics back to the `ParseResult`'s error
+    * lists positionally is the alternative, and it is unsound for the parsing
+    * half: `processParsingErrors` DROPS an error whose token offsets are `NaN`
+    * and whose exception carries no `previousToken`, so the two lists differ in
+    * length exactly when recovery has been at work.
     *
     * Inside the timing span rather than around it, so the line accounts for the
     * whole pass.
@@ -241,15 +370,19 @@ export class HydraniumDocumentValidator extends DefaultDocumentValidator {
       // 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.
+      // Each pass guards on its own `data.code`, so at most one can claim a
+      // given diagnostic and the order between them carries no meaning.
       for (let index = 0; index < diagnostics.length; index++) {
          diagnostics[index] = this.identifyLexingError(document, diagnostics[index]);
+         diagnostics[index] = this.identifyParsingError(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.
+    * Add whichever lexing identity renders `diagnostic`'s sentence, or return it
+    * untouched when none of them does — a custom lexer's own report, which
+    * Langium admits through `lexerReport`, being the case that reaches the end.
     *
     * The parameters come from the diagnostic's own RANGE, not from
     * `parseResult.lexerErrors`. Both hold the same numbers, and the range is the
@@ -269,19 +402,165 @@ export class HydraniumDocumentValidator extends DefaultDocumentValidator {
          return diagnostic;
       }
       const text = document.textDocument;
+      const message = Diagnostic.getMessageString(diagnostic);
       const offset = text.offsetAt(diagnostic.range.start);
-      const params = {
+      const stray = {
          character: text.getText().charAt(offset),
          offset,
          skipped: text.offsetAt(diagnostic.range.end) - offset
       };
-      if (Diagnostic.getMessageString(diagnostic) !== LEXING_ERROR.format(params)) {
+      if (message === UNEXPECTED_CHARACTER.format(stray)) {
+         return this.identified(diagnostic, UNEXPECTED_CHARACTER, stray);
+      }
+      // The mode-pop error's range spans the offending token exactly, upstream
+      // reporting its `startOffset` with the image's own length.
+      const image = text.getText(diagnostic.range);
+      if (message === UNPOPPABLE_LEXER_MODE.format({ image })) {
+         return this.identified(diagnostic, UNPOPPABLE_LEXER_MODE, { image });
+      }
+      // `level` and `stack` are lexer state that reaches no field here, so they
+      // are sliced; `offset` is given, which is what anchors the slice.
+      const dedent = this.sliceFramed(message, INVALID_DEDENT, { offset });
+      return dedent === undefined ? diagnostic : this.identified(diagnostic, INVALID_DEDENT, dedent);
+   }
+
+   /**
+    * Add whichever parser identity renders `diagnostic`'s sentence, or return it
+    * untouched when none of them does — an adopter that replaced the parser
+    * error-message provider being the case that reaches the last branch.
+    *
+    * `found` comes from the diagnostic's own RANGE, for the same reason
+    * {@link identifyLexingError} reads its parameters there. A token whose
+    * offsets chevrotain could not report collapses to a zero-width range, which
+    * yields the empty string the sentence already renders for it.
+    *
+    * **`expected` is recovered by SEARCHING the vocabulary, because nothing
+    * carries it.** Chevrotain hands the expected token type to the message
+    * provider and keeps it on neither the exception nor the diagnostic, so the
+    * only structured source left is the grammar's own vocabulary: every token
+    * type is offered to the same `format` the identity renders with, and the one
+    * that reproduces the message supplies the parameter. Matching it out of the
+    * prose instead would derive a parameter from a sentence that a Langium
+    * reword can change without warning. Two distinct names cannot render one
+    * sentence, so the match is unique where it exists.
+    */
+   protected identifyParsingError(document: LangiumDocument, diagnostic: Diagnostic): Diagnostic {
+      const data = diagnostic.data as { code?: unknown } | undefined;
+      if (data?.code !== DocumentValidator.ParsingError) {
          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) } };
+      const message = Diagnostic.getMessageString(diagnostic);
+      const found = document.textDocument.getText(diagnostic.range);
+      if (message === TRAILING_INPUT.format({ found })) {
+         return this.identified(diagnostic, TRAILING_INPUT, { found });
+      }
+      const expected = this.tokenTypeNames().find(name => UNEXPECTED_TOKEN.format({ expected: name, found }) === message);
+      if (expected !== undefined) {
+         return this.identified(diagnostic, UNEXPECTED_TOKEN, { expected, found });
+      }
+      for (const definition of SEQUENCE_LISTING_MESSAGES) {
+         const params = this.sliceFramed(message, definition, { found });
+         if (params !== undefined) {
+            return this.identified(diagnostic, definition, params);
+         }
+      }
+      return diagnostic;
+   }
+
+   /** `diagnostic` carrying `definition`'s identity, over whatever `data` it already had. */
+   protected identified<S extends string>(diagnostic: Diagnostic, definition: MessageDefinition<S>, ...params: ParamsArg<S>): Diagnostic {
+      // Merged OVER the existing data, so Langium's `code` survives for the
+      // readers that switch on it — `stopAfterParsingErrors` is one, and the
+      // GLSP head's read-only decision is another.
+      const data = diagnostic.data as object | undefined;
+      return { ...diagnostic, code: definition.code, data: { ...data, ...messageData(definition, ...params) } };
+   }
+
+   /**
+    * `definition`'s parameters as they appear in `message`, taking the ones in
+    * `known` as given, or `undefined` when `message` is not that sentence.
+    *
+    * **The only parameters in this file taken OUT of the prose rather than
+    * derived and checked against it, and the bound on that is what `known`
+    * is for.** A generated token-sequence list, a lexer's indentation stack: for
+    * these there is no finite candidate set to offer to `format` the way a token
+    * type name can be, and no structured field carries them. What keeps the read
+    * honest is that everything else in the sentence is either a fixed literal or
+    * a parameter the caller derived independently, so the frame either matches
+    * exactly or the sentence is declined.
+    *
+    * **The trailing format-and-compare is load-bearing once more than one
+    * parameter is unknown.** Each is captured up to the NEXT fixed separator, so
+    * a separator that also occurs inside a value would cut early — re-rendering
+    * catches that, where for a single unknown between two affixes it could not
+    * fail. Two adjacent placeholders are declined outright: nothing marks the
+    * boundary, so no capture is recoverable.
+    *
+    * The frame is split off the declaration's own `text`, so it cannot drift
+    * from the sentence `format` renders.
+    */
+   protected sliceFramed<S extends string>(
+      message: string,
+      definition: MessageDefinition<S>,
+      known: MessageParams
+   ): ParamsOf<S> | undefined {
+      // `split` with a capturing group interleaves literals and placeholder
+      // names, so even indices are frame and odd ones are parameters.
+      const parts = definition.text.split(PLACEHOLDER_CAPTURE);
+      const params: Record<string, string | number> = { ...known };
+      let cursor = 0;
+      for (let index = 0; index < parts.length; index += 2) {
+         const literal = parts[index];
+         if (!message.startsWith(literal, cursor)) {
+            return undefined;
+         }
+         cursor += literal.length;
+         const name = parts[index + 1];
+         if (name === undefined) {
+            break;
+         }
+         const given = params[name];
+         if (given !== undefined) {
+            const rendered = String(given);
+            if (!message.startsWith(rendered, cursor)) {
+               return undefined;
+            }
+            cursor += rendered.length;
+            continue;
+         }
+         const separator = parts[index + 2];
+         const trailing = parts[index + 3] === undefined;
+         if (separator === '' && !trailing) {
+            return undefined;
+         }
+         const at = trailing && separator === '' ? message.length : message.indexOf(separator, cursor);
+         if (at < cursor) {
+            return undefined;
+         }
+         params[name] = message.slice(cursor, at);
+         cursor = at;
+      }
+      if (cursor !== message.length || interpolate(definition.text, params) !== message) {
+         return undefined;
+      }
+      // Narrowing only: every placeholder the template names was either given or
+      // captured above, which is precisely what `ParamsOf` requires.
+      return params as ParamsOf<S>;
+   }
+
+   /**
+    * Every token type name the grammar declares, as
+    * {@link identifyParsingError} candidates.
+    *
+    * Read off the lexer, whose `definition` the `Lexer` INTERFACE declares —
+    * the parser holds the same vocabulary only behind Langium's default class,
+    * where an adopter's replacement need not keep it. A token type the parser
+    * expects but the lexer does not declare yields no match, which declines the
+    * identity rather than attaching a wrong one.
+    */
+   protected tokenTypeNames(): readonly string[] {
+      this.expectedNames ??= Object.keys(this.lexer.definition);
+      return this.expectedNames;
    }
 
    /**
@@ -395,7 +674,7 @@ export class HydraniumDocumentValidator extends DefaultDocumentValidator {
       severity: ValidationSeverity,
       message: string,
       info: DiagnosticInfo<N, string>
-   ): TransferLspDiagnostic {
+   ): AstDiagnostic {
       const base = super.toDiagnostic(severity, message, info);
       const node = info.node;
       if (!node) {
@@ -419,9 +698,11 @@ export class HydraniumDocumentValidator extends DefaultDocumentValidator {
     */
    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) {
+      // The locator answers '' for the root, which is the root's path rather than a miss.
+      const isRoot = node.$container === undefined;
+      const containerPath = directPath || isRoot ? undefined : this.astNodeLocator.getAstNodePath(node.$container);
+      const nodePath = directPath || containerPath || '';
+      if (!nodePath && !isRoot) {
          this.tracer.warn('Cannot create diagnostic element path: Unable to determine AST node path.');
          return '';
       }

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

@@ -15,6 +15,15 @@ import { type ValidationCheckRegistry } from './validation-contribution.js';
 
 export type ValidationContributionCollectorOptions = LogNameOptions;
 
+/**
+ * The validation-collector slot. Empty because the service registers checks in
+ * its constructor and nothing calls it; typing the slot by the class would stop
+ * an adopter's subclass from a second package copy satisfying it. The cost: any
+ * non-null value satisfies it, so a mis-bound slot compiles and registers no check.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- the slot has no public member to name
+export interface ValidationContributionCollector {}
+
 /**
  * Per-language eager collector that wires `ValidationCheckContribution`s
  * declared under `services.validation.checks` into Langium's native
@@ -32,7 +41,7 @@ export type ValidationContributionCollectorOptions = LogNameOptions;
  * 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 {
+export class DefaultValidationContributionCollector implements ValidationContributionCollector {
    protected readonly tracer: Tracer;
 
    constructor(services: ServerLanguageServices, options: ValidationContributionCollectorOptions = {}) {

package/src/langium/workspace/ast-node-locator.ts

@@ -0,0 +1,33 @@
+/********************************************************************************
+ * 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 AstNode, DefaultAstNodeLocator } from '@hydranium/langium';
+
+/**
+ * Framework `AstNodeLocator`. Returns the same paths as Langium's, built as
+ * one flat string: Langium's recursive `+` leaves V8 a rope of up to two cons
+ * cells per level, retained by every description and reference description
+ * in the index. Interning the paths would save more but keeps one pool entry
+ * per list index ever seen, deleted documents' paths included.
+ *
+ * Ancestors' segments come from `getPathSegment`, not from `getAstNodePath`,
+ * so an override of `getAstNodePath` for one node does not reach its
+ * descendants' paths; override `getPathSegment` for that.
+ */
+export class HydraniumAstNodeLocator extends DefaultAstNodeLocator {
+   override getAstNodePath(node: AstNode): string {
+      const segments: string[] = [];
+      for (let current = node; current.$container; current = current.$container) {
+         segments.push(this.getPathSegment(current));
+      }
+      // The root's empty segment gives the leading separator; a root alone yields ''.
+      segments.push('');
+      return segments.reverse().join(this.segmentSeparator);
+   }
+}

package/src/langium/workspace/document-uri-policy.ts

@@ -21,6 +21,8 @@ import { type ServerSharedServicesMinimal } from '../shared-services.js';
  */
 export interface RealpathCapableFileSystem {
    realpath?(uri: URI): URI | undefined;
+   /** `uri` with its links followed, those to nothing included; see `WritableFileSystemProvider.resolveLinks`. */
+   resolveLinks?(uri: URI): URI;
 }
 
 /**
@@ -51,16 +53,17 @@ export function findRealpathDivergence(uri: URI | string, fs: RealpathCapableFil
  * - {@link canonicalUri} — TOTAL: maps any URI to the single canonical *string*
  *   the framework keys a document by, regardless of whether the file exists.
  *   This is the form that MUST match the adopter's `LangiumDocuments` keying so
- *   the text store, AST-document event filters
- *   (`AstDocumentManager.onUpdate` / `onSave` / `onClientClosed`), and
+ *   the text store, `ModelService`'s event filters, and
  *   `LangiumDocuments` lookups all agree on one identity for the same file. Use
  *   for keying, comparison, and the text-store ↔ document-store bridges.
  *
  * - {@link loadUri} — EXISTENCE-AWARE: maps a URI to the *load* URI, or
  *   `undefined` when there is no loadable on-disk content for it. Use where the
  *   next step actually touches the filesystem (loading a document, walking a
- *   directory): `undefined` means "skip / treat as empty" rather than attempt a
- *   doomed read. The default treats every URI as loadable (returns it
+ *   directory): `undefined` means "skip the read" rather than attempt a doomed
+ *   one. It does not mean there is no document: one created and not yet saved
+ *   has no file, and the text store and `LangiumDocuments` hold it under
+ *   {@link canonicalUri}. The default treats every URI as loadable (returns it
  *   unchanged); a real-path policy returns the resolved file URI, or `undefined`
  *   for a not-yet-written path.
  *
@@ -84,7 +87,9 @@ export interface DocumentUriPolicy {
    /**
     * Existence-aware resolution to the load URI, or `undefined` when there is
     * no loadable content for `uri` (missing / synthetic). Callers that read the
-    * filesystem next use `undefined` to skip rather than attempt a doomed read.
+    * filesystem next use `undefined` to skip rather than attempt a doomed read,
+    * and still look the URI up under {@link canonicalUri}: a document created
+    * and not yet saved is held there with no file behind it.
     */
    loadUri(uri: URI | string): URI | undefined;
 }
@@ -146,17 +151,21 @@ export class DefaultDocumentUriPolicy implements DocumentUriPolicy {
  * The raw `realpath` syscall lives on the `FileSystemProvider`
  * (`@hydranium/core/node`'s `DefaultFileSystemProvider`), not here — this policy
  * is pure routing over that seam, so it carries no `node:fs` import and is
- * browser-neutral. Both methods follow the *same* policy: `canonicalUri` falls
- * back to the syntactic form when the path can't be resolved (optimistic — a
- * file that appears later canonicalises to the same key once present), while
- * `loadUri` returns `undefined` for an absent path (honest about existence, so a
- * caller about to read the filesystem skips it).
+ * browser-neutral. Both methods follow the *same* policy: `canonicalUri` keys a
+ * path that can't be resolved by the links it follows, where the provider has
+ * `resolveLinks`, else by its syntactic form (optimistic — a file that appears
+ * later canonicalises to the same key once present, also one reached through a
+ * link that pointed at nothing), while `loadUri` returns `undefined` for an
+ * absent path (honest about existence, so a caller about to read the
+ * filesystem skips it).
  *
- * If the bound provider has no `realpath` (in-memory / browser / empty),
- * both methods degrade to {@link DefaultDocumentUriPolicy} automatically — the
- * `loadUri` ternary tests the *method's presence*, not its return, so the
- * existence signal is preserved: `loadUri` returns `undefined` only when
- * `realpath` is present and reports the path absent.
+ * If the provider for a URI's scheme has no `realpath` (in-memory / browser /
+ * empty), the framework's `FileSystemProviderRegistry` returns the URI
+ * unchanged and both methods answer as {@link DefaultDocumentUriPolicy} does. A
+ * slot bound to a provider without `realpath` degrades the same way: the
+ * `loadUri` ternary tests the *method's presence*, not its return, so
+ * `loadUri` returns `undefined` only when `realpath` is present and reports the
+ * path absent.
  */
 export class RealpathDocumentUriPolicy extends DefaultDocumentUriPolicy {
    protected readonly fs: RealpathCapableFileSystem;
@@ -168,9 +177,14 @@ export class RealpathDocumentUriPolicy extends DefaultDocumentUriPolicy {
 
    override canonicalUri(uri: URI | string): CanonicalUri {
       const parsed = UriUtils.toUri(uri);
-      const real = parsed && this.fs.realpath?.(parsed);
-      // Mint via `asCanonicalUri` once normalised; absent / unresolvable paths
-      // (and a provider without `realpath`) fall back to the syntactic form.
+      // An absent path keys by the links it follows, so a file reached through
+      // a link keys the same before it exists and once it does; a provider
+      // without `resolveLinks`, or without `realpath`, keys it syntactically.
+      // `resolveLinks` alone where it exists: it resolves a present path as
+      // `realpath` does, and asking both would cost an absent path a second
+      // miss.
+      const real = parsed && (this.fs.resolveLinks ? this.fs.resolveLinks(parsed) : this.fs.realpath?.(parsed));
+      // Mint via `asCanonicalUri` once normalised.
       return real ? asCanonicalUri(UriUtils.normalize(real)) : super.canonicalUri(uri);
    }
 

package/src/langium/workspace/file-not-found.ts

@@ -0,0 +1,35 @@
+/********************************************************************************
+ * 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 URI } from '@hydranium/langium';
+
+// Not re-exported from the workspace barrel: the framework's providers and
+// the release handler share it, and it is no API of theirs.
+
+/**
+ * A missing-file error shaped as a Node file system raises it, with code
+ * `ENOENT` and the path: callers tell a missing file from any other failure by
+ * those two fields, whichever provider is bound. The release relies on it to
+ * tell a document gone meanwhile from any other failed rebuild.
+ */
+export function notFound(message: string, uri: URI): Error {
+   return Object.assign(new Error(message), { code: 'ENOENT', path: uri.fsPath });
+}
+
+/**
+ * Whether `err` reports that the file of `target` does not exist, as a Node
+ * file system and {@link notFound} do: code `ENOENT`, with `target`'s path. A
+ * missing file of another document is a different failure.
+ */
+export function isFileNotFound(err: unknown, target: URI): boolean {
+   if (typeof err !== 'object' || err === null || !('code' in err) || err.code !== 'ENOENT') {
+      return false;
+   }
+   return !('path' in err) || err.path === target.fsPath;
+}