@hydranium/core 1.0.0-next.10

package/lib/node/validate-workspace.d.ts

@@ -0,0 +1,80 @@
+/********************************************************************************
+ * 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 LangiumDocument, type URI } from '@hydranium/langium';
+import { type ServerSharedServicesMinimal } from '../langium/shared-services.js';
+/** A validation diagnostic's severity, as a stable lowercase string for the JSON contract. */
+export type ValidationSeverity = 'error' | 'warning' | 'info' | 'hint';
+/**
+ * One validation problem, flattened to a serialisable shape. This is the JSON
+ * contract `hydranium-cli validate --json` emits, deliberately independent of the
+ * `vscode-languageserver` {@link Diagnostic} type so CI tooling reads a stable
+ * schema and the CLI never needs a runtime `@hydranium/core` dependency.
+ */
+export interface ValidationFinding {
+    /** Workspace-relative path of the document the problem was reported on. */
+    uri: string;
+    severity: ValidationSeverity;
+    message: string;
+    /** 0-based line of the diagnostic range start (add 1 for editor display). */
+    line: number;
+    /** 0-based character of the diagnostic range start (add 1 for editor display). */
+    character: number;
+    /** The diagnostic `code`, when the rule set one. */
+    code?: string | number;
+    /** The diagnostic `source`, when the rule set one. */
+    source?: string;
+}
+/** Per-severity tally across the whole workspace — drives the exit code and the summary line. */
+export interface ValidationCounts {
+    error: number;
+    warning: number;
+    info: number;
+    hint: number;
+}
+/** The full result of a headless workspace validation. */
+export interface WorkspaceValidationResult {
+    /** Number of `LangiumDocument`s in the built workspace. */
+    documents: number;
+    /** Every problem found, grouped contiguously by document, in the order the documents were given. */
+    findings: ValidationFinding[];
+    /** Per-severity totals over {@link findings}. */
+    counts: ValidationCounts;
+}
+/** Options for {@link validateWorkspace}. */
+export interface ValidateWorkspaceOptions {
+    /**
+     * Create the language's shared services in-process. This is the only
+     * language-specific input — a head passes its own `create<Lang>Services(fileSystem)`.
+     */
+    createServices: () => {
+        shared: ServerSharedServicesMinimal;
+    };
+    /** Workspace root (filesystem path or file URI) to build and validate. */
+    workspace: string;
+}
+/**
+ * Flatten each document's `diagnostics` into a {@link WorkspaceValidationResult}.
+ * Pure over its inputs (documents + a URI-to-relative-path mapper) so it unit-tests
+ * without booting a grammar; {@link validateWorkspace} is the thin boot-and-build wrapper.
+ */
+export declare function collectValidationResult(documents: readonly LangiumDocument[], wsRelativePath: (uri: URI) => string): WorkspaceValidationResult;
+/**
+ * Headless workspace validation — the browser-/socket-free counterpart to the
+ * diagnostics an editor session publishes. Boots a head's Langium services
+ * in-process via {@link ValidateWorkspaceOptions.createServices}, builds every
+ * document to `Validated` (which runs the language's validation checks), then
+ * collects the diagnostics into a serialisable {@link WorkspaceValidationResult}.
+ *
+ * Backs `hydranium-cli validate`, whose non-zero exit on errors makes it a CI
+ * gate. Like the other headless harnesses the only language-specific input is the
+ * service factory, so the framework code stays head-neutral. The build is the
+ * standard eager pipeline — identical to what those sibling harnesses run.
+ */
+export declare function validateWorkspace(options: ValidateWorkspaceOptions): Promise<WorkspaceValidationResult>;
+//# sourceMappingURL=validate-workspace.d.ts.map

package/lib/node/validate-workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-workspace.d.ts","sourceRoot":"","sources":["../../src/node/validate-workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAEpE,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAGjF,8FAA8F;AAC9F,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvE;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAC/B,2EAA2E;IAC3E,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,iGAAiG;AACjG,MAAM,WAAW,gBAAgB;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACf;AAED,0DAA0D;AAC1D,MAAM,WAAW,yBAAyB;IACvC,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,oGAAoG;IACpG,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,iDAAiD;IACjD,MAAM,EAAE,gBAAgB,CAAC;CAC3B;AAED,6CAA6C;AAC7C,MAAM,WAAW,wBAAwB;IACtC;;;OAGG;IACH,cAAc,EAAE,MAAM;QAAE,MAAM,EAAE,2BAA2B,CAAA;KAAE,CAAC;IAC9D,0EAA0E;IAC1E,SAAS,EAAE,MAAM,CAAC;CACpB;AAkBD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACpC,SAAS,EAAE,SAAS,eAAe,EAAE,EACrC,cAAc,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,MAAM,GACpC,yBAAyB,CAsB3B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAK7G"}

package/lib/node/validate-workspace.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
+ ********************************************************************************/
+import { Diagnostic, DiagnosticSeverity } from 'vscode-languageserver';
+import { buildWorkspaceProgrammatically } from '../langium/workspace/initialize-workspace.js';
+/** Map a `vscode-languageserver` severity to the stable string. Unset → `error` (fail-safe for a CI gate). */
+function severityLabel(severity) {
+    switch (severity) {
+        case DiagnosticSeverity.Warning:
+            return 'warning';
+        case DiagnosticSeverity.Information:
+            return 'info';
+        case DiagnosticSeverity.Hint:
+            return 'hint';
+        default:
+            // DiagnosticSeverity.Error, or an omitted severity — treat as an error so
+            // a rule that forgets to set one still blocks the gate rather than passing silently.
+            return 'error';
+    }
+}
+/**
+ * Flatten each document's `diagnostics` into a {@link WorkspaceValidationResult}.
+ * Pure over its inputs (documents + a URI-to-relative-path mapper) so it unit-tests
+ * without booting a grammar; {@link validateWorkspace} is the thin boot-and-build wrapper.
+ */
+export function collectValidationResult(documents, wsRelativePath) {
+    const findings = [];
+    const counts = { error: 0, warning: 0, info: 0, hint: 0 };
+    for (const document of documents) {
+        const relativeUri = wsRelativePath(document.uri);
+        for (const diagnostic of (document.diagnostics ?? [])) {
+            const severity = severityLabel(diagnostic.severity);
+            counts[severity] += 1;
+            findings.push({
+                uri: relativeUri,
+                severity,
+                // LSP 3.18 allows a `MarkupContent` message; this report is a
+                // line-oriented CI artifact, so take its plain-text rendering.
+                message: Diagnostic.getMessageString(diagnostic),
+                line: diagnostic.range.start.line,
+                character: diagnostic.range.start.character,
+                code: diagnostic.code,
+                source: diagnostic.source
+            });
+        }
+    }
+    return { documents: documents.length, findings, counts };
+}
+/**
+ * Headless workspace validation — the browser-/socket-free counterpart to the
+ * diagnostics an editor session publishes. Boots a head's Langium services
+ * in-process via {@link ValidateWorkspaceOptions.createServices}, builds every
+ * document to `Validated` (which runs the language's validation checks), then
+ * collects the diagnostics into a serialisable {@link WorkspaceValidationResult}.
+ *
+ * Backs `hydranium-cli validate`, whose non-zero exit on errors makes it a CI
+ * gate. Like the other headless harnesses the only language-specific input is the
+ * service factory, so the framework code stays head-neutral. The build is the
+ * standard eager pipeline — identical to what those sibling harnesses run.
+ */
+export async function validateWorkspace(options) {
+    const { shared } = options.createServices();
+    await buildWorkspaceProgrammatically(shared, options.workspace);
+    const documents = shared.workspace.LangiumDocuments.all.toArray();
+    return collectValidationResult(documents, uri => shared.workspace.WorkspaceManager.wsRelativePath(uri));
+}
+//# sourceMappingURL=validate-workspace.js.map

package/lib/node/validate-workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-workspace.js","sourceRoot":"","sources":["../../src/node/validate-workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAGlF,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEvE,OAAO,EAAE,8BAA8B,EAAE,MAAM,8CAA8C,CAAC;AAuD9F,8GAA8G;AAC9G,SAAS,aAAa,CAAC,QAAwC;IAC5D,QAAQ,QAAQ,EAAE,CAAC;QAChB,KAAK,kBAAkB,CAAC,OAAO;YAC5B,OAAO,SAAS,CAAC;QACpB,KAAK,kBAAkB,CAAC,WAAW;YAChC,OAAO,MAAM,CAAC;QACjB,KAAK,kBAAkB,CAAC,IAAI;YACzB,OAAO,MAAM,CAAC;QACjB;YACG,0EAA0E;YAC1E,qFAAqF;YACrF,OAAO,OAAO,CAAC;IACrB,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CACpC,SAAqC,EACrC,cAAoC;IAEpC,MAAM,QAAQ,GAAwB,EAAE,CAAC;IACzC,MAAM,MAAM,GAAqB,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IAC5E,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QAChC,MAAM,WAAW,GAAG,cAAc,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACjD,KAAK,MAAM,UAAU,IAAI,CAAC,QAAQ,CAAC,WAAW,IAAI,EAAE,CAAiB,EAAE,CAAC;YACrE,MAAM,QAAQ,GAAG,aAAa,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;YACpD,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YACtB,QAAQ,CAAC,IAAI,CAAC;gBACX,GAAG,EAAE,WAAW;gBAChB,QAAQ;gBACR,8DAA8D;gBAC9D,+DAA+D;gBAC/D,OAAO,EAAE,UAAU,CAAC,gBAAgB,CAAC,UAAU,CAAC;gBAChD,IAAI,EAAE,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI;gBACjC,SAAS,EAAE,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS;gBAC3C,IAAI,EAAE,UAAU,CAAC,IAAI;gBACrB,MAAM,EAAE,UAAU,CAAC,MAAM;aAC3B,CAAC,CAAC;QACN,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,SAAS,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;AAC5D,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,OAAiC;IACtE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAC5C,MAAM,8BAA8B,CAAC,MAAM,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IAChE,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC,gBAAgB,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;IAClE,OAAO,uBAAuB,CAAC,SAAS,EAAE,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,gBAAgB,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC;AAC3G,CAAC"}

package/lib/node/write-lock-scope-node.d.ts

@@ -0,0 +1,27 @@
+/********************************************************************************
+ * 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 WriteLockScope } from '../langium/workspace/write-lock-scope.js';
+/**
+ * `node:async_hooks`-backed {@link WriteLockScope}.
+ *
+ * `AsyncLocalStorage` is the right primitive rather than a plain module-level
+ * boolean: the lock's action is async, and a flag set around it would report
+ * "inside" for every other task interleaved on the event loop while that action
+ * awaits — which is most of them. The store follows the async stack instead, so
+ * only code actually descended from the action sees it.
+ */
+export declare const nodeWriteLockScope: WriteLockScope;
+/**
+ * Install the Node write-lock scope tracker, enabling reentrancy detection on the
+ * model facade. Idempotent. Called once at `@hydranium/core/node` load, so any
+ * Node host that imports the entry gets the detection for free; a browser bundle
+ * imports only `.` and keeps the inert default.
+ */
+export declare function installNodeWriteLockScope(): void;
+//# sourceMappingURL=write-lock-scope-node.d.ts.map

package/lib/node/write-lock-scope-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-lock-scope-node.d.ts","sourceRoot":"","sources":["../../src/node/write-lock-scope-node.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAGlF,OAAO,EAAE,KAAK,cAAc,EAAqB,MAAM,0CAA0C,CAAC;AAIlG;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,EAAE,cAOhC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD"}

package/lib/node/write-lock-scope-node.js

@@ -0,0 +1,38 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { setWriteLockScope } from '../langium/workspace/write-lock-scope.js';
+const storage = new AsyncLocalStorage();
+/**
+ * `node:async_hooks`-backed {@link WriteLockScope}.
+ *
+ * `AsyncLocalStorage` is the right primitive rather than a plain module-level
+ * boolean: the lock's action is async, and a flag set around it would report
+ * "inside" for every other task interleaved on the event loop while that action
+ * awaits — which is most of them. The store follows the async stack instead, so
+ * only code actually descended from the action sees it.
+ */
+export const nodeWriteLockScope = {
+    run(fn) {
+        return storage.run(true, fn);
+    },
+    isInside() {
+        return storage.getStore() === true;
+    }
+};
+/**
+ * Install the Node write-lock scope tracker, enabling reentrancy detection on the
+ * model facade. Idempotent. Called once at `@hydranium/core/node` load, so any
+ * Node host that imports the entry gets the detection for free; a browser bundle
+ * imports only `.` and keeps the inert default.
+ */
+export function installNodeWriteLockScope() {
+    setWriteLockScope(nodeWriteLockScope);
+}
+//# sourceMappingURL=write-lock-scope-node.js.map

package/lib/node/write-lock-scope-node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-lock-scope-node.js","sourceRoot":"","sources":["../../src/node/write-lock-scope-node.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAuB,iBAAiB,EAAE,MAAM,0CAA0C,CAAC;AAElG,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAAQ,CAAC;AAE9C;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAmB;IAC/C,GAAG,CAAI,EAAW;QACf,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAChC,CAAC;IACD,QAAQ;QACL,OAAO,OAAO,CAAC,QAAQ,EAAE,KAAK,IAAI,CAAC;IACtC,CAAC;CACH,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB;IACtC,iBAAiB,CAAC,kBAAkB,CAAC,CAAC;AACzC,CAAC"}

package/lib/testing/ast-snapshot.d.ts

@@ -0,0 +1,38 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+/**
+ * A plain, JSON-like structural view of an AST sub-tree — references reduced
+ * to `{ $refText }`, every Langium-internal and computed-extension field
+ * stripped. Cycle-free by construction, so it compares cleanly with
+ * `expect(...).toEqual(...)`.
+ */
+export type AstSnapshot = unknown;
+/**
+ * Project an AST node (or any value reachable from one) onto a comparable
+ * {@link AstSnapshot} that captures only the grammar-derived shape.
+ *
+ * Built for round-trip assertions: the snapshot of a model re-parsed from its
+ * own serialized text deep-equals the snapshot of the original iff
+ * serialization preserved the semantic model, independent of formatting (see
+ * the module comment for why a snapshot is needed rather than a direct compare
+ * of the live ASTs).
+ *
+ * What it keeps and what it drops:
+ * - **`Reference`** (`$refText` + `ref`) → `{ $refText }`. The resolution
+ *   target is positional noise; the textual name is the grammar content.
+ * - **`$type`** is kept (it identifies the node); every other `$`-prefixed
+ *   field (`$container`, `$containerProperty`, `$containerIndex`, `$cstNode`,
+ *   `$document`, …) is dropped — all are derived placement/parse metadata.
+ * - **`_`-prefixed fields** — the AST-extension computed properties — are
+ *   dropped: they are derived at build time, not part of what a serializer
+ *   round-trips.
+ * - Arrays recurse element-wise; primitives pass through unchanged.
+ */
+export declare function makeAstSnapshot(value: unknown): AstSnapshot;
+//# sourceMappingURL=ast-snapshot.d.ts.map

package/lib/testing/ast-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast-snapshot.d.ts","sourceRoot":"","sources":["../../src/testing/ast-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAiClF;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,CAAC;AAElC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAkB3D"}

package/lib/testing/ast-snapshot.js

@@ -0,0 +1,78 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * Structural AST snapshots for serializer round-trip testing.
+ *
+ * # The idea
+ *
+ * Byte-stability (the golden corpus) proves the serializer's *output format*
+ * is pinned, but not that serialization *preserves meaning*. The complementary
+ * guarantee is the round trip: parse some source, serialize the resulting
+ * model back to text, parse that text again — the two models must be the same.
+ * If they are, no semantic content was lost or invented in the trip through
+ * text, independent of whitespace, member ordering, or dropped comments.
+ *
+ * # Why a snapshot, not the live AST
+ *
+ * You cannot `expect(ast2).toEqual(ast1)` on two live Langium ASTs:
+ * - `$container` (and friends) make every node cyclic — a deep-equal walk
+ *   never terminates.
+ * - `$cstNode` carries source offsets that legitimately differ once text has
+ *   been re-serialized and re-parsed, so it is noise for a semantic compare.
+ * - a `Reference` holds a resolved `ref` back-pointer into the other tree;
+ *   only its textual `$refText` is grammar content.
+ *
+ * {@link makeAstSnapshot} projects a node onto a plain, acyclic, JSON-like
+ * value that keeps exactly the grammar-derived shape — node `$type`s, their
+ * own properties, references reduced to `{ $refText }` — and drops the derived
+ * placement/parse metadata and computed extensions. Two snapshots then compare
+ * cleanly with `toEqual`, and that comparison means "same semantic model".
+ */
+import { isAstNode, isReference } from '@hydranium/langium';
+/**
+ * Project an AST node (or any value reachable from one) onto a comparable
+ * {@link AstSnapshot} that captures only the grammar-derived shape.
+ *
+ * Built for round-trip assertions: the snapshot of a model re-parsed from its
+ * own serialized text deep-equals the snapshot of the original iff
+ * serialization preserved the semantic model, independent of formatting (see
+ * the module comment for why a snapshot is needed rather than a direct compare
+ * of the live ASTs).
+ *
+ * What it keeps and what it drops:
+ * - **`Reference`** (`$refText` + `ref`) → `{ $refText }`. The resolution
+ *   target is positional noise; the textual name is the grammar content.
+ * - **`$type`** is kept (it identifies the node); every other `$`-prefixed
+ *   field (`$container`, `$containerProperty`, `$containerIndex`, `$cstNode`,
+ *   `$document`, …) is dropped — all are derived placement/parse metadata.
+ * - **`_`-prefixed fields** — the AST-extension computed properties — are
+ *   dropped: they are derived at build time, not part of what a serializer
+ *   round-trips.
+ * - Arrays recurse element-wise; primitives pass through unchanged.
+ */
+export function makeAstSnapshot(value) {
+    if (isReference(value)) {
+        return { $refText: value.$refText };
+    }
+    if (Array.isArray(value)) {
+        return value.map(makeAstSnapshot);
+    }
+    if (isAstNode(value)) {
+        const snapshot = { $type: value.$type };
+        for (const [key, child] of Object.entries(value)) {
+            if (key.startsWith('$') || key.startsWith('_')) {
+                continue;
+            }
+            snapshot[key] = makeAstSnapshot(child);
+        }
+        return snapshot;
+    }
+    return value;
+}
+//# sourceMappingURL=ast-snapshot.js.map

package/lib/testing/ast-snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast-snapshot.js","sourceRoot":"","sources":["../../src/testing/ast-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAU5D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC3C,IAAI,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC;IACvC,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,KAAK,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACrC,CAAC;IACD,IAAI,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;QACpB,MAAM,QAAQ,GAA4B,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;QACjE,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAChD,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC9C,SAAS;YACZ,CAAC;YACD,QAAQ,CAAC,GAAG,CAAC,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;QAC1C,CAAC;QACD,OAAO,QAAQ,CAAC;IACnB,CAAC;IACD,OAAO,KAAK,CAAC;AAChB,CAAC"}

package/lib/testing/document-uri-policy-conformance.d.ts

@@ -0,0 +1,65 @@
+/********************************************************************************
+ * 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 DocumentUriPolicy } from '../langium/workspace/document-uri-policy.js';
+/**
+ * The runner primitives the suite emits through. Vitest and Jest both supply
+ * structurally-compatible `describe`/`it`/`expect`, so the kit takes them as a
+ * parameter rather than importing a runner — keeping it usable from either, and
+ * keeping `@hydranium/core/testing` free of a hard runner dependency (the
+ * barrel is consumed by Jest adopters too).
+ */
+export interface DocumentUriPolicyConformanceHooks {
+    describe(name: string, body: () => void): void;
+    it(name: string, body: () => void): void;
+    expect(actual: unknown): {
+        toBe(expected: unknown): void;
+    };
+}
+/** Options for {@link documentUriPolicyConformance}. */
+export interface DocumentUriPolicyConformanceOptions {
+    /**
+     * URIs the contract is checked against. A policy that strengthens identity
+     * (realpath) should include a divergent (symlinked) and an absent sample so
+     * the resolve / fallback branches are exercised. Defaults to a syntactic
+     * spread (dot segments, spaces, a non-`file:` scheme) that any policy honours.
+     */
+    readonly sampleUris?: readonly string[];
+}
+/**
+ * Reusable contract suite for any {@link DocumentUriPolicy} implementation —
+ * the framework's `DefaultDocumentUriPolicy` / `RealpathDocumentUriPolicy` and
+ * any adopter policy. Pins the two invariants the document-identity story
+ * rests on, so a change to either method — or an adopter binding a
+ * custom policy — cannot silently reintroduce the canonical/load divergence:
+ *
+ * 1. **`canonicalUri` is idempotent** — feeding it an already-canonical URI
+ *    (e.g. a `LangiumDocument.uri` straight off the build) is a fixed point.
+ * 2. **Present-case agreement** — whenever `loadUri(u)` is defined (the URI is
+ *    loadable), its normalised form equals `canonicalUri(u)`. This is the
+ *    "two methods, one policy" guarantee: the key the document is stored under
+ *    and the URI it is loaded from must denote the same identity, or a
+ *    subscriber keyed by one misses events delivered under the other.
+ *
+ * The miss case is deliberately NOT constrained (the default returns the URI
+ * unchanged from `loadUri`; a realpath policy returns `undefined`) — only the
+ * present case must agree.
+ *
+ * The agreement check is vacuous for a sample that is not loadable, so the
+ * suite also emits a guard asserting that at least ONE sample is: an
+ * existence-aware policy (realpath, or an adopter's) bound against the
+ * fictional {@link DEFAULT_SAMPLE_URIS} resolves every one of them to
+ * `undefined`, and would otherwise report an all-green suite that checked
+ * nothing.
+ *
+ * @param hooks the test runner's `describe`/`it`/`expect`
+ * @param suiteName label for the emitted `describe` block
+ * @param makePolicy fresh policy per assertion (no shared mutable state)
+ */
+export declare function documentUriPolicyConformance(hooks: DocumentUriPolicyConformanceHooks, suiteName: string, makePolicy: () => DocumentUriPolicy, options?: DocumentUriPolicyConformanceOptions): void;
+//# sourceMappingURL=document-uri-policy-conformance.d.ts.map

package/lib/testing/document-uri-policy-conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-uri-policy-conformance.d.ts","sourceRoot":"","sources":["../../src/testing/document-uri-policy-conformance.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAIlF,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAErF;;;;;;GAMG;AACH,MAAM,WAAW,iCAAiC;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC/C,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IACzC,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG;QAAE,IAAI,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAA;KAAE,CAAC;CAC7D;AAED,wDAAwD;AACxD,MAAM,WAAW,mCAAmC;IACjD;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,4BAA4B,CACzC,KAAK,EAAE,iCAAiC,EACxC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,iBAAiB,EACnC,OAAO,GAAE,mCAAwC,GACjD,IAAI,CA6BN"}

package/lib/testing/document-uri-policy-conformance.js

@@ -0,0 +1,69 @@
+/********************************************************************************
+ * 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 { asCanonicalUri } from '@hydranium/protocol';
+import { UriUtils } from '@hydranium/langium';
+const DEFAULT_SAMPLE_URIS = ['file:///a/b.fake', 'file:///a/../b.fake', 'file:///My Folder/x.fake', 'builtin:///Element.fake'];
+/**
+ * Reusable contract suite for any {@link DocumentUriPolicy} implementation —
+ * the framework's `DefaultDocumentUriPolicy` / `RealpathDocumentUriPolicy` and
+ * any adopter policy. Pins the two invariants the document-identity story
+ * rests on, so a change to either method — or an adopter binding a
+ * custom policy — cannot silently reintroduce the canonical/load divergence:
+ *
+ * 1. **`canonicalUri` is idempotent** — feeding it an already-canonical URI
+ *    (e.g. a `LangiumDocument.uri` straight off the build) is a fixed point.
+ * 2. **Present-case agreement** — whenever `loadUri(u)` is defined (the URI is
+ *    loadable), its normalised form equals `canonicalUri(u)`. This is the
+ *    "two methods, one policy" guarantee: the key the document is stored under
+ *    and the URI it is loaded from must denote the same identity, or a
+ *    subscriber keyed by one misses events delivered under the other.
+ *
+ * The miss case is deliberately NOT constrained (the default returns the URI
+ * unchanged from `loadUri`; a realpath policy returns `undefined`) — only the
+ * present case must agree.
+ *
+ * The agreement check is vacuous for a sample that is not loadable, so the
+ * suite also emits a guard asserting that at least ONE sample is: an
+ * existence-aware policy (realpath, or an adopter's) bound against the
+ * fictional {@link DEFAULT_SAMPLE_URIS} resolves every one of them to
+ * `undefined`, and would otherwise report an all-green suite that checked
+ * nothing.
+ *
+ * @param hooks the test runner's `describe`/`it`/`expect`
+ * @param suiteName label for the emitted `describe` block
+ * @param makePolicy fresh policy per assertion (no shared mutable state)
+ */
+export function documentUriPolicyConformance(hooks, suiteName, makePolicy, options = {}) {
+    const { describe, it, expect } = hooks;
+    const sampleUris = options.sampleUris ?? DEFAULT_SAMPLE_URIS;
+    describe(suiteName, () => {
+        for (const uri of sampleUris) {
+            it(`canonicalUri is idempotent for ${uri}`, () => {
+                const once = makePolicy().canonicalUri(uri);
+                expect(makePolicy().canonicalUri(once)).toBe(once);
+            });
+            it(`canonicalUri agrees with loadUri when ${uri} is loadable`, () => {
+                const policy = makePolicy();
+                const loaded = policy.loadUri(uri);
+                if (loaded === undefined) {
+                    return; // not loadable: the agreement invariant is vacuous here
+                }
+                expect(policy.canonicalUri(uri)).toBe(asCanonicalUri(UriUtils.normalize(loaded)));
+            });
+        }
+        // Computed here rather than tallied from the assertions above, so the
+        // guard does not depend on the runner executing tests in declaration
+        // order (a `--shuffle` run would otherwise read it as zero).
+        it(`at least one sample URI is loadable (checked: ${sampleUris.join(', ')})`, () => {
+            const loadable = sampleUris.filter(uri => makePolicy().loadUri(uri) !== undefined);
+            expect(loadable.length > 0).toBe(true);
+        });
+    });
+}
+//# sourceMappingURL=document-uri-policy-conformance.js.map

package/lib/testing/document-uri-policy-conformance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-uri-policy-conformance.js","sourceRoot":"","sources":["../../src/testing/document-uri-policy-conformance.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AA2B9C,MAAM,mBAAmB,GAAG,CAAC,kBAAkB,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,yBAAyB,CAAC,CAAC;AAE/H;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,4BAA4B,CACzC,KAAwC,EACxC,SAAiB,EACjB,UAAmC,EACnC,UAA+C,EAAE;IAEjD,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IACvC,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,mBAAmB,CAAC;IAE7D,QAAQ,CAAC,SAAS,EAAE,GAAG,EAAE;QACtB,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;YAC5B,EAAE,CAAC,kCAAkC,GAAG,EAAE,EAAE,GAAG,EAAE;gBAC9C,MAAM,IAAI,GAAG,UAAU,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;gBAC5C,MAAM,CAAC,UAAU,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACtD,CAAC,CAAC,CAAC;YAEH,EAAE,CAAC,yCAAyC,GAAG,cAAc,EAAE,GAAG,EAAE;gBACjE,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;gBAC5B,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;gBACnC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;oBACxB,OAAO,CAAC,wDAAwD;gBACnE,CAAC;gBACD,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YACrF,CAAC,CAAC,CAAC;QACN,CAAC;QAED,sEAAsE;QACtE,qEAAqE;QACrE,6DAA6D;QAC7D,EAAE,CAAC,iDAAiD,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE;YAChF,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,UAAU,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC,CAAC;YACnF,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1C,CAAC,CAAC,CAAC;IACN,CAAC,CAAC,CAAC;AACN,CAAC"}

package/lib/testing/fake-description.d.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 AstNodeDescription } from '@hydranium/langium';
+/**
+ * Options for {@link makeFakeDescription}. Extends `Partial<AstNodeDescription>`
+ * (override any standard field) plus the tier-index extras (`tier`, `projectId`)
+ * that live on a `TieredAstNodeDescription` — attached without the caller
+ * writing an `as unknown as` cast.
+ */
+export interface FakeDescriptionOptions extends Partial<AstNodeDescription> {
+    /** Visibility tier (`'local' | 'project' | 'public' | 'universal'`) to stamp on the description. */
+    tier?: string;
+    /** Owning project id, for project/public-tier descriptions. */
+    projectId?: string;
+}
+/**
+ * Build an {@link AstNodeDescription} fixture for scope / candidate / tier tests.
+ *
+ * Defaults model distinct nodes: `type: 'Fake'`, `documentUri: memory://test`,
+ * and a per-name `path` (`'/' + name`) so distinct names key as distinct nodes
+ * under the canonical filter (which keys on `documentUri#path`). Tier-sibling
+ * cases that model ONE node under several names pass an explicit shared `path`.
+ * `tier` / `projectId` are stamped on when provided; the cast that needs (those
+ * fields live on `TieredAstNodeDescription`, not on `AstNodeDescription`) is
+ * encapsulated here so call sites stay cast-free. The description sibling of
+ * `makeFakeAstNode`.
+ */
+export declare function makeFakeDescription(name: string, opts?: FakeDescriptionOptions): AstNodeDescription;
+//# sourceMappingURL=fake-description.d.ts.map

package/lib/testing/fake-description.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-description.d.ts","sourceRoot":"","sources":["../../src/testing/fake-description.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,kBAAkB,EAAO,MAAM,oBAAoB,CAAC;AAElE;;;;;GAKG;AACH,MAAM,WAAW,sBAAuB,SAAQ,OAAO,CAAC,kBAAkB,CAAC;IACxE,oGAAoG;IACpG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,sBAA2B,GAAG,kBAAkB,CAevG"}

package/lib/testing/fake-description.js

@@ -0,0 +1,38 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import { URI } from '@hydranium/langium';
+/**
+ * Build an {@link AstNodeDescription} fixture for scope / candidate / tier tests.
+ *
+ * Defaults model distinct nodes: `type: 'Fake'`, `documentUri: memory://test`,
+ * and a per-name `path` (`'/' + name`) so distinct names key as distinct nodes
+ * under the canonical filter (which keys on `documentUri#path`). Tier-sibling
+ * cases that model ONE node under several names pass an explicit shared `path`.
+ * `tier` / `projectId` are stamped on when provided; the cast that needs (those
+ * fields live on `TieredAstNodeDescription`, not on `AstNodeDescription`) is
+ * encapsulated here so call sites stay cast-free. The description sibling of
+ * `makeFakeAstNode`.
+ */
+export function makeFakeDescription(name, opts = {}) {
+    const description = {
+        name,
+        type: opts.type ?? 'Fake',
+        documentUri: opts.documentUri ?? URI.parse('memory://test'),
+        path: opts.path ?? '/' + name,
+        node: opts.node
+    };
+    if (opts.tier !== undefined) {
+        description.tier = opts.tier;
+    }
+    if (opts.projectId !== undefined) {
+        description.projectId = opts.projectId;
+    }
+    return description;
+}
+//# sourceMappingURL=fake-description.js.map

package/lib/testing/fake-description.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-description.js","sourceRoot":"","sources":["../../src/testing/fake-description.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAA2B,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAelE;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY,EAAE,OAA+B,EAAE;IAChF,MAAM,WAAW,GAAuB;QACrC,IAAI;QACJ,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,MAAM;QACzB,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,GAAG,CAAC,KAAK,CAAC,eAAe,CAAC;QAC3D,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,GAAG,GAAG,IAAI;QAC7B,IAAI,EAAE,IAAI,CAAC,IAAI;KACjB,CAAC;IACF,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC1B,WAAiD,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;IACvE,CAAC;IACD,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QAC/B,WAAiD,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;IACjF,CAAC;IACD,OAAO,WAAW,CAAC;AACtB,CAAC"}