@hydranium/core 1.0.0-next.75 → 1.0.0-next.77

package/lib/messages/index.js

@@ -19,7 +19,7 @@ export * from './carriers.js';
 export * from './renderer.js';
 export { MODEL_UPDATE_EDIT } from '../langium/model-service/model-service.js';
 export { SEPARATOR_IN_NAME } from '../langium/naming/name-separator-validation.js';
-export { LEXING_ERROR, UNRESOLVED_REFERENCE } from '../langium/validation/document-validator.js';
+export { INVALID_DEDENT, UNEXPECTED_CHARACTER, MISSING_ITERATION, NO_VIABLE_ALTERNATIVE, TRAILING_INPUT, UNEXPECTED_TOKEN, UNPOPPABLE_LEXER_MODE, UNRESOLVED_REFERENCE } from '../langium/validation/document-validator.js';
 export { NO_LOADABLE_CONTENT } from '../langium/workspace/langium-documents.js';
 export { NO_SUCH_FILE, NO_SUCH_PATH } from '../langium/workspace/in-memory-file-system-provider.js';
 //# sourceMappingURL=index.js.map

package/lib/messages/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/messages/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;GAQG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAE9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,2CAA2C,CAAC;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,gDAAgD,CAAC;AACnF,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,6CAA6C,CAAC;AACjG,OAAO,EAAE,mBAAmB,EAAE,MAAM,2CAA2C,CAAC;AAChF,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,wDAAwD,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/messages/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;GAQG;AAEH,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAE9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,2CAA2C,CAAC;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,gDAAgD,CAAC;AACnF,OAAO,EACJ,cAAc,EACd,oBAAoB,EACpB,iBAAiB,EACjB,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACtB,MAAM,6CAA6C,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,2CAA2C,CAAC;AAChF,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,wDAAwD,CAAC"}

package/lib/node/heap-ceiling.d.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
+ ********************************************************************************/
+/** Options for {@link heapCeilingArgs}. */
+export interface HeapCeilingOptions {
+    /**
+     * Ceiling in MiB to pass when no cgroup limit is in force. Name the value a
+     * memory-heavy run on a workstation needs; it is ignored inside a container.
+     */
+    readonly desktopDefaultMb: number;
+    /**
+     * Caller-supplied override, typically an environment variable, and typically
+     * `undefined`. A finite value at or above {@link minMb} wins everywhere,
+     * container or not — an operator who states a number has decided. An explicit
+     * `0` means "let Node decide" and emits no flag. Anything unparseable is
+     * REPORTED through {@link warn} rather than ignored: `8G` is a natural thing
+     * to type into a variable measured in MiB, and silently dropping it leaves
+     * the operator believing a ceiling is in force.
+     */
+    readonly envValue?: string;
+    /**
+     * Smallest override to pass on. Below it, {@link warn} is called and NO flag
+     * is emitted: a value that small can only be a misconfiguration — GiB typed
+     * where MiB was meant — and V8 fatals at startup once it is small enough.
+     * Deliberately not clamped UP: running with a different number than the one
+     * configured hides the mistake instead of surfacing it. Omitted means no floor.
+     */
+    readonly minMb?: number;
+    /** Where a rejected override is reported. Defaults to `console.warn`. */
+    readonly warn?: (message: string) => void;
+    /** Cgroup limit in bytes; defaults to this process's. Injectable for tests. */
+    readonly constrained?: number;
+    /** Host physical memory in bytes; defaults to `os.totalmem()`. Injectable for tests. */
+    readonly total?: number;
+}
+/**
+ * Whether a cgroup memory limit is in force — i.e. whether the OOM killer is
+ * watching a ceiling lower than (or equal to) the machine's own.
+ *
+ * **`constrained > 0` is not the test, and that is the whole reason this is a
+ * named function.** With no limit set, cgroup v2 reports 2^64 and v1 reports
+ * ~2^63 rather than 0, so the naive test reads every desktop as a container.
+ * Neither sentinel can equal `os.totalmem()`, so comparing against the host
+ * total costs nothing and rules both out. The comparison is `<=` rather than
+ * `<` so a limit set to exactly the host's RAM still counts as a limit.
+ */
+export declare function isMemoryConstrained(constrained?: number, total?: number): boolean;
+/**
+ * The `execArgv` entries that set a child's heap ceiling: `[]` to let Node size
+ * the heap itself, or a single `--max-old-space-size=<mb>`.
+ *
+ * Returns an array rather than a string so a caller can spread it
+ * unconditionally into an argv it is building.
+ */
+export declare function heapCeilingArgs(options: HeapCeilingOptions): string[];
+//# sourceMappingURL=heap-ceiling.d.ts.map

package/lib/node/heap-ceiling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heap-ceiling.d.ts","sourceRoot":"","sources":["../../src/node/heap-ceiling.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAwBlF,2CAA2C;AAC3C,MAAM,WAAW,kBAAkB;IAChC;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,wFAAwF;IACxF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,SAAqC,EAAE,KAAK,SAAgB,GAAG,OAAO,CAEpH;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,EAAE,CAqBrE"}

package/lib/node/heap-ceiling.js

@@ -0,0 +1,72 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/*
+ * Choosing `--max-old-space-size` for a child process, which is a decision no
+ * caller gets right by picking a number.
+ *
+ * A fixed ceiling is sized for the machine the author had. Pass 8192 to a
+ * process under a 2 GiB cgroup limit and V8 lets old space grow past the limit
+ * without ever collecting hard, so the kernel OOM-kills the whole container
+ * before V8 has any reason to act — the parent sees a signal, not a heap error,
+ * and everything sharing the cgroup dies with it. Pass nothing on a large
+ * desktop and V8 sizes from physical RAM, which for a memory-heavy tool is well
+ * under what it needs.
+ *
+ * Both are the same mistake: a ceiling stated without reference to the limit
+ * that is actually in force. The rule here is to name the desktop default
+ * explicitly and step aside inside a container, where Node derives its own
+ * ceiling from the cgroup limit and a runaway heap therefore fails INSIDE the
+ * child — attributable, and reported as a heap error against one process rather
+ * than as a kill against every process in the cgroup.
+ */
+import * as os from 'node:os';
+/**
+ * Whether a cgroup memory limit is in force — i.e. whether the OOM killer is
+ * watching a ceiling lower than (or equal to) the machine's own.
+ *
+ * **`constrained > 0` is not the test, and that is the whole reason this is a
+ * named function.** With no limit set, cgroup v2 reports 2^64 and v1 reports
+ * ~2^63 rather than 0, so the naive test reads every desktop as a container.
+ * Neither sentinel can equal `os.totalmem()`, so comparing against the host
+ * total costs nothing and rules both out. The comparison is `<=` rather than
+ * `<` so a limit set to exactly the host's RAM still counts as a limit.
+ */
+export function isMemoryConstrained(constrained = process.constrainedMemory?.() ?? 0, total = os.totalmem()) {
+    return constrained > 0 && constrained <= total;
+}
+/**
+ * The `execArgv` entries that set a child's heap ceiling: `[]` to let Node size
+ * the heap itself, or a single `--max-old-space-size=<mb>`.
+ *
+ * Returns an array rather than a string so a caller can spread it
+ * unconditionally into an argv it is building.
+ */
+export function heapCeilingArgs(options) {
+    const { desktopDefaultMb, envValue, minMb, warn = (message) => console.warn(message) } = options;
+    if (envValue !== undefined) {
+        const mb = Number(envValue);
+        // An explicit 0 is a decision — "let Node decide" — so it passes quietly.
+        // Anything else that is not a positive number is a typo, and the operator
+        // who typed it is the one person who cannot tell it was dropped.
+        if (!Number.isFinite(mb) || mb < 0) {
+            warn(`Ignoring the heap ceiling '${envValue}': expected a whole number of MiB. Node will size the heap instead.`);
+            return [];
+        }
+        if (mb === 0) {
+            return [];
+        }
+        if (minMb !== undefined && mb < minMb) {
+            warn(`Ignoring a heap ceiling of ${envValue} MiB: below the ${minMb} MiB minimum. Node will size the heap instead.`);
+            return [];
+        }
+        return [`--max-old-space-size=${Math.floor(mb)}`];
+    }
+    return isMemoryConstrained(options.constrained, options.total) ? [] : [`--max-old-space-size=${desktopDefaultMb}`];
+}
+//# sourceMappingURL=heap-ceiling.js.map

package/lib/node/heap-ceiling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heap-ceiling.js","sourceRoot":"","sources":["../../src/node/heap-ceiling.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAmC9B;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,WAAW,GAAG,OAAO,CAAC,iBAAiB,EAAE,EAAE,IAAI,CAAC,EAAE,KAAK,GAAG,EAAE,CAAC,QAAQ,EAAE;IACxG,OAAO,WAAW,GAAG,CAAC,IAAI,WAAW,IAAI,KAAK,CAAC;AAClD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,OAA2B;IACxD,MAAM,EAAE,gBAAgB,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,GAAG,CAAC,OAAe,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,GAAG,OAAO,CAAC;IACzG,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,EAAE,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC5B,0EAA0E;QAC1E,0EAA0E;QAC1E,iEAAiE;QACjE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC;YAClC,IAAI,CAAC,8BAA8B,QAAQ,qEAAqE,CAAC,CAAC;YAClH,OAAO,EAAE,CAAC;QACb,CAAC;QACD,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC;YACZ,OAAO,EAAE,CAAC;QACb,CAAC;QACD,IAAI,KAAK,KAAK,SAAS,IAAI,EAAE,GAAG,KAAK,EAAE,CAAC;YACrC,IAAI,CAAC,8BAA8B,QAAQ,mBAAmB,KAAK,gDAAgD,CAAC,CAAC;YACrH,OAAO,EAAE,CAAC;QACb,CAAC;QACD,OAAO,CAAC,wBAAwB,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,mBAAmB,CAAC,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,wBAAwB,gBAAgB,EAAE,CAAC,CAAC;AACtH,CAAC"}

package/lib/node/index.d.ts

@@ -13,6 +13,7 @@ export * from './log-preamble-node.js';
 export * from './server-diagnostics.js';
 export * from './ast-ground-truth.js';
 export * from './event-loop-monitor.js';
+export * from './heap-ceiling.js';
 export * from './latency-from-env.js';
 export * from './measure-memory.js';
 export * from './memory-monitor.js';

package/lib/node/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAgBlF,cAAc,gCAAgC,CAAC;AAC/C,cAAc,oBAAoB,CAAC;AACnC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AAQxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAgBlF,cAAc,gCAAgC,CAAC;AAC/C,cAAc,oBAAoB,CAAC;AACnC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AAQxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC"}

package/lib/node/index.js

@@ -32,6 +32,7 @@ export * from './server-diagnostics.js';
 // entry alongside the default policy.
 export * from './ast-ground-truth.js';
 export * from './event-loop-monitor.js';
+export * from './heap-ceiling.js';
 export * from './latency-from-env.js';
 export * from './measure-memory.js';
 export * from './memory-monitor.js';

package/lib/node/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,iFAAiF;AACjF,6EAA6E;AAC7E,iFAAiF;AACjF,EAAE;AACF,8EAA8E;AAC9E,8EAA8E;AAC9E,4EAA4E;AAC5E,mBAAmB;AACnB,iFAAiF;AACjF,iFAAiF;AACjF,8CAA8C;AAC9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAEvE,cAAc,gCAAgC,CAAC;AAC/C,cAAc,oBAAoB,CAAC;AACnC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AAExC,8EAA8E;AAC9E,+EAA+E;AAC/E,0EAA0E;AAC1E,sEAAsE;AACtE,6EAA6E;AAC7E,sCAAsC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AAExC,sBAAsB,EAAE,CAAC;AACzB,yBAAyB,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/node/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,iFAAiF;AACjF,6EAA6E;AAC7E,iFAAiF;AACjF,EAAE;AACF,8EAA8E;AAC9E,8EAA8E;AAC9E,4EAA4E;AAC5E,mBAAmB;AACnB,iFAAiF;AACjF,iFAAiF;AACjF,8CAA8C;AAC9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAEvE,cAAc,gCAAgC,CAAC;AAC/C,cAAc,oBAAoB,CAAC;AACnC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AAExC,8EAA8E;AAC9E,+EAA+E;AAC/E,0EAA0E;AAC1E,sEAAsE;AACtE,6EAA6E;AAC7E,sCAAsC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AAExC,sBAAsB,EAAE,CAAC;AACzB,yBAAyB,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydranium/core",
-  "version": "1.0.0-next.75",
+  "version": "1.0.0-next.77",
   "description": "Foundational runtime of the hydranium framework: AST coordination layer (services, integrity, AST extension, serialization, multi-client documents) plus the LSP textual head at the /lsp subpath. Consumed by protocol-head packages (@hydranium/data-server, @hydranium/glsp-server).",
   "keywords": [
     "hydranium",
@@ -104,8 +104,8 @@
     "diff": "^5.2.0"
   },
   "devDependencies": {
-    "@hydranium/langium": "1.0.0-next.75",
-    "@hydranium/protocol": "1.0.0-next.75",
+    "@hydranium/langium": "1.0.0-next.77",
+    "@hydranium/protocol": "1.0.0-next.77",
     "@playwright/test": "^1.40.0",
     "@types/diff": "^5.2.0",
     "rimraf": "^5.0.0",
@@ -117,8 +117,8 @@
     "vscode-languageserver-types": "^3.17.5"
   },
   "peerDependencies": {
-    "@hydranium/langium": "1.0.0-next.75",
-    "@hydranium/protocol": "1.0.0-next.75",
+    "@hydranium/langium": "1.0.0-next.77",
+    "@hydranium/protocol": "1.0.0-next.77",
     "@playwright/test": "^1.40.0",
     "vscode-jsonrpc": "9.0.1",
     "vscode-languageserver": "~10.0.1",

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,6 +31,7 @@ import {
    DocumentValidator,
    type LangiumDocument,
    type LangiumCoreServices,
+   type Lexer,
    type ValidateSingleNodeOptions,
    type ValidationOptions,
    type ValidationSeverity
@@ -107,11 +113,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.
  *
@@ -174,6 +286,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 +302,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 +335,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 +364,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 +396,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;
    }
 
    /**

package/src/messages/index.ts

@@ -22,6 +22,15 @@ export * from './renderer.js';
 
 export { MODEL_UPDATE_EDIT } from '../langium/model-service/model-service.js';
 export { SEPARATOR_IN_NAME } from '../langium/naming/name-separator-validation.js';
-export { LEXING_ERROR, UNRESOLVED_REFERENCE } from '../langium/validation/document-validator.js';
+export {
+   INVALID_DEDENT,
+   UNEXPECTED_CHARACTER,
+   MISSING_ITERATION,
+   NO_VIABLE_ALTERNATIVE,
+   TRAILING_INPUT,
+   UNEXPECTED_TOKEN,
+   UNPOPPABLE_LEXER_MODE,
+   UNRESOLVED_REFERENCE
+} from '../langium/validation/document-validator.js';
 export { NO_LOADABLE_CONTENT } from '../langium/workspace/langium-documents.js';
 export { NO_SUCH_FILE, NO_SUCH_PATH } from '../langium/workspace/in-memory-file-system-provider.js';