@hydranium/core 1.0.0-next.79 → 1.0.0-next.85

package/src/documents/hydranium-text-documents.ts

@@ -237,7 +237,7 @@ function contentHash(text: string): string {
  *     per-client staleness guard and never leak into the shared sequence —
  *     the two are different things (an editor's edit-operation counter vs the
  *     document's content-revision number), and splicing them lets versions drift
- *     silently past `baseVersion` gate holders.
+ *     silently past based-on gate holders.
  *   - Version-author history so each edit is attributable to its originating client.
  *   - Pending-content staging used by the integrity service to thread corrections
  *     through `workspace/applyEdit` cycles for currently-closed documents.
@@ -264,7 +264,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
     * that record is deleted on last close, while the version sequence must
     * survive it — the shared version is a server-owned, monotonic,
     * advances-iff-content-changes counter that never resets while the server
-    * lives. That invariant is what makes an optimistic `baseVersion` gate
+    * lives. That invariant is what makes an optimistic based-on gate
     * sound: "version unchanged ⇔ content unchanged", with no false conflicts
     * from close/reopen version resets and no false passes from a reopened
     * sequence coincidentally landing on a stale writer's number.
@@ -506,7 +506,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
          }
 
          // The SHARED version advances iff the content actually changes — the
-         // invariant optimistic `baseVersion` gates rely on. The new text is
+         // invariant optimistic based-on gates rely on. The new text is
          // only known after applying the (possibly incremental) changes, so
          // apply at a tentative +1 and roll the version back on an identical
          // result (an empty-changes update only re-stamps the version).
@@ -557,7 +557,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
     * A content-identical write still fires the change event (rebuild): the
     * authored write's server-side rebuild is correctness-bearing, it just
     * mints no new version — nothing observable changed, so watchers'
-    * `baseVersion` pointers stay valid.
+    * based-on versions stay valid.
     *
     * Returns the resulting shared version. Throws when the document is not
     * open — callers (`AstDocumentManager.update`) open first.
@@ -694,7 +694,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
          const source = pendingText ? ', source=pending' : '';
          // The SHARED version is server-assigned: continue the persisted
          // sequence — same version when the content is unchanged since the
-         // last close (so watchers' `baseVersion` pointers stay valid), one
+         // last close (so watchers' based-on versions stay valid), one
          // step when it changed (so no stale pointer can coincidentally pass
          // the optimistic gate). Only a first-ever open adopts the client's
          // declared id as the sequence seed.
@@ -860,7 +860,7 @@ export class HydraniumTextDocuments<T extends TextDocument = TextDocument> exten
     * `0` for a URI this store has never seen. The shared sequence is
     * server-owned and monotonic across close/reopen cycles, and advances
     * exactly when the synced content changes — which is what makes it a sound
-    * optimistic-concurrency token (`baseVersion` gates): version unchanged ⇔
+    * optimistic-concurrency token (based-on gates): version unchanged ⇔
     * content unchanged.
     */
    version(uri: DocumentUri): number {

package/src/langium/integrity/integrity-service.ts

@@ -360,7 +360,7 @@ export class DefaultIntegrityService<TRoot extends AstNode = AstNode> implements
       // during the re-parse saw the text on disk, which in `'editor'` sync mode
       // is the PRE-repair text. Leave the sequence describing that and the next
       // open hashes the repair, finds a mismatch and steps the version again, so
-      // every `baseVersion` taken from this build is stale before it is used.
+      // every based-on version taken from this build is stale before it is used.
       // Falls back to the pre-re-parse number for a URI the store never tracked,
       // where there is no sequence to advance; an OPEN document answers
       // `undefined` and keeps the store's own version, which is not this

package/src/langium/model-service/model-service.ts

@@ -11,12 +11,12 @@ import {
    type CanonicalUri,
    type CloseModelArgs,
    ConflictError,
+   isSnapshotVersion,
    defineMessage,
    Logger,
    type MaybeObservableValue,
    type MaybePromise,
    ObservableValue,
-   type TransferDiagnostic,
    type TransferElement,
    type OpenModelArgs,
    type Tracer,
@@ -24,6 +24,7 @@ import {
    type TransferUpdateArgs
 } from '@hydranium/protocol';
 import { type AstNode, DocumentState, type LangiumDocument, UriUtils, type URI } from '@hydranium/langium';
+import { type AstDiagnostic } from '../validation/document-validator.js';
 import { type DocumentUriPolicy } from '../workspace/document-uri-policy.js';
 import { ReentrantWriteLockError, isInsideWriteLock } from '../workspace/write-lock-scope.js';
 import { type CancellationToken, type Disposable } from 'vscode-languageserver';
@@ -194,8 +195,12 @@ export interface ModelServiceOptions extends LogNameOptions {
  * **Generic parameters.**
  * - `TAst` — the AST root type each consumer expects on the returned
  *   {@link AstDocument}. Constrained to {@link AstNode}.
- * - `TDiagnostic` — wire diagnostic shape used by the injected
- *   `TransferEncoder`. Defaults to {@link TransferDiagnostic}.
+ * - `TDiagnostic` — the AST-layer diagnostic: whatever the build left on
+ *   `LangiumDocument.diagnostics`, carried through on the returned
+ *   {@link AstDocument}. Defaults to {@link AstDiagnostic}.
+ *   **Not the `TransferEncoder`'s parameter of the same name**, which is
+ *   that encoder's OUTPUT and so names the wire shape. This one names its
+ *   input, and an adopter binds the two to different types.
  * - `TTransfer` — transfer-model root accepted by `update` / `save`
  *   args. Constrained to {@link TransferElement}. Defaults to the
  *   structural base.
@@ -228,7 +233,11 @@ export interface ModelServiceOptions extends LogNameOptions {
  * member taking a phase as a PARAMETER cannot judge statically and so returns
  * `TDiagnostic`, leaving the choice to the caller.
  */
-export interface ModelService<TAst extends AstNode, TDiagnostic = TransferDiagnostic, TTransfer extends TransferElement = TransferElement> {
+export interface ModelService<
+   TAst extends AstNode,
+   TDiagnostic extends AstDiagnostic = AstDiagnostic,
+   TTransfer extends TransferElement = TransferElement
+> {
    /**
     * Resolves once the workspace has been initialised and its first build has
     * completed — the gate every read should wait behind, since a document
@@ -260,6 +269,7 @@ export interface ModelService<TAst extends AstNode, TDiagnostic = TransferDiagno
    open(args: OpenModelArgs): Promise<Disposable>;
    close(args: CloseModelArgs): Promise<void>;
    isOpen(uri: string): boolean;
+   snapshot(uri: string): AstDocument<TAst, TDiagnostic> | undefined;
    getDocument(uri: string): LangiumDocument | undefined;
 
    onModelUpdated(uri: string, listener: (event: AstDocumentUpdatedEvent<TAst, TDiagnostic>) => void): Disposable;
@@ -269,7 +279,7 @@ export interface ModelService<TAst extends AstNode, TDiagnostic = TransferDiagno
 
 export class DefaultModelService<
    TAst extends AstNode,
-   TDiagnostic = TransferDiagnostic,
+   TDiagnostic extends AstDiagnostic = AstDiagnostic,
    /**
     * Structured payload accepted by `update` / `save`. Constrained to
     * {@link TransferElement} — the minimal `{ readonly $type: string }`
@@ -578,16 +588,13 @@ export class DefaultModelService<
     * - `validated` returns `AstDocument<TAst, TDiagnostic>` — diagnostics
     *   are populated.
     *
-    * **The `never` is a claim about the PHASE, not a guarantee about the
-    * instance, and the gap is reachable rather than theoretical.** The wait
-    * underneath resolves at or ABOVE the requested state, so a document
-    * something else already carried past `Validated` comes back from
-    * `settled()` with a populated diagnostics array typed `never`. Nothing
-    * strips it — the envelope copies the live document's array verbatim — and
-    * any host that validates its workspace before a consumer asks produces
-    * exactly that. So read an empty array as "none were computed, or there are
-    * none", never as "this document is clean", and call {@link validated} when
-    * the answer has to mean the second.
+    * **The `never` is enforced, not merely declared.** The wait underneath
+    * resolves at or ABOVE the requested state, so a document something else
+    * already carried past `Validated` would otherwise come back from
+    * `settled()` carrying a full diagnostics array typed `never`; these four
+    * strip it. An empty array here therefore means "this read does not report
+    * diagnostics", never "this document is clean" — call {@link validated}
+    * when the answer has to mean the second.
     *
     * `settled` is the integrity-overlay name for "all integrity rules
     * have fired"; it maps to {@link IntegrityService.SettledState} (which
@@ -596,19 +603,19 @@ export class DefaultModelService<
     * ever moves.
     */
    async parsed(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>> {
-      return this.ensureDocumentState(uri, DocumentState.Parsed, cancelToken) as Promise<AstDocument<TAst, never>>;
+      return this.withoutDiagnostics(await this.ensureDocumentState(uri, DocumentState.Parsed, cancelToken));
    }
 
    async linked(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>> {
-      return this.ensureDocumentState(uri, DocumentState.Linked, cancelToken) as Promise<AstDocument<TAst, never>>;
+      return this.withoutDiagnostics(await this.ensureDocumentState(uri, DocumentState.Linked, cancelToken));
    }
 
    async settled(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>> {
-      return this.ensureDocumentState(uri, IntegrityService.SettledState, cancelToken) as Promise<AstDocument<TAst, never>>;
+      return this.withoutDiagnostics(await this.ensureDocumentState(uri, IntegrityService.SettledState, cancelToken));
    }
 
    async indexed(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>> {
-      return this.ensureDocumentState(uri, DocumentState.IndexedReferences, cancelToken) as Promise<AstDocument<TAst, never>>;
+      return this.withoutDiagnostics(await this.ensureDocumentState(uri, DocumentState.IndexedReferences, cancelToken));
    }
 
    async validated(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>> {
@@ -706,7 +713,7 @@ export class DefaultModelService<
       // no client holds open, the open assigns the shared version from the
       // INCOMING text, so a version read afterwards has already absorbed the
       // caller's own write. Gating on it rejected every modifying write to a
-      // closed document, having compared the caller's `baseVersion` against a
+      // closed document, having compared the caller's `basedOn` against a
       // number the caller itself produced — and a serialised round-trip that is
       // not byte-identical to the stored text was enough to trigger it. Reading
       // first keeps both cases the gate exists for: an unknown URI answers 0, so
@@ -716,11 +723,11 @@ export class DefaultModelService<
       const currentVersion = this.services.workspace.TextDocuments.version(uri);
       const text = await run('serialize', () => this.modelToText(uri, args.model, cancelToken));
       await run('open', () => this.open({ uri, clientId: args.clientId, text }));
-      if (args.baseVersion !== undefined && currentVersion !== args.baseVersion) {
+      if (isSnapshotVersion(args.basedOn) && currentVersion !== args.basedOn) {
          // Distinct from the post-build "superseded" debug line below: this is a
          // based-on-stale rejection (the write never applies), not two writes racing.
-         this.tracer.debug(`Conflict on ${uri}: based-on v${args.baseVersion} stale, server at v${currentVersion}`);
-         throw new ConflictError(uri, args.baseVersion, currentVersion);
+         this.tracer.debug(`Conflict on ${uri}: based-on v${args.basedOn} stale, server at v${currentVersion}`);
+         throw new ConflictError(uri, args.basedOn, currentVersion);
       }
       const appliedVersion = await run('apply', () => this.services.workspace.AstDocumentManager.update(uri, text, args.clientId));
       // Dispatch through the public `rebuild` (which re-canonicalizes the already-
@@ -843,6 +850,31 @@ export class DefaultModelService<
       return this.services.workspace.AstDocumentManager.isOpen(uri);
    }
 
+   /**
+    * Snapshot of `uri` as it stands RIGHT NOW — the synchronous sibling of the
+    * phase reads, which all wait. `undefined` when no document is registered.
+    *
+    * **This is what a writer wants, and {@link getDocument} is not.** The
+    * envelope's `version` is copied by value at projection time, so it cannot
+    * move afterwards; a version read off the live document at write time is
+    * whatever the server is at *now*, which is the number an optimistic gate is
+    * about to compare it against.
+    *
+    * Diagnostics only from a document that has reached `Validated`, and an
+    * empty array otherwise. Unlike the phase reads this one names no phase, so
+    * the state it finds is the only thing that can say whether the array
+    * describes the content being handed back or whatever an earlier build left.
+    * A caller that needs them unconditionally waits, via {@link validated}.
+    */
+   snapshot(uri: string): AstDocument<TAst, TDiagnostic> | undefined {
+      const document = this.getDocument(uri);
+      if (!document) {
+         return undefined;
+      }
+      const envelope = AstDocument.from<TAst, TDiagnostic>(document);
+      return document.state >= DocumentState.Validated ? envelope : this.withoutDiagnostics(envelope);
+   }
+
    /**
     * The built {@link LangiumDocument} for `uri`, looked up by canonical identity —
     * the synchronous, phase-agnostic sibling of {@link ensureDocumentState} /
@@ -851,6 +883,13 @@ export class DefaultModelService<
     * into `LangiumDocuments` directly: a symlinked / `..` / case-divergent URI
     * still resolves to the one document the build keys by its real path. Returns
     * `undefined` if no document is registered for `uri`.
+    *
+    * **Live, so do not take a based-on version off it.** `textDocument` is the
+    * store's own object rather than a copy, so `.version` read here answers for
+    * the moment of the READ, not the moment of the earlier content — pass it to
+    * a write and the server compares its current version against itself, the
+    * gate passes unconditionally, and a concurrent edit is overwritten with
+    * nothing logged. Use {@link snapshot} for that, or a phase read.
     */
    getDocument(uri: string): LangiumDocument | undefined {
       return this.services.workspace.AstDocumentManager.getDocument(uri);
@@ -1171,4 +1210,23 @@ export class DefaultModelService<
          ? AstDocument.from<TAst, TDiagnostic>(document)
          : AstDocument.create<TAst, TDiagnostic>(uri.toString(), 0, undefined as unknown as TAst, []);
    }
+
+   /**
+    * The same envelope with no diagnostics, for a read that names a phase below
+    * `Validated`.
+    *
+    * Langium fills `LangiumDocument.diagnostics` from inside `validateDocument`
+    * and from nowhere else, so below that phase the array holds whatever an
+    * EARLIER build left — a verdict about text the document may no longer have.
+    * The wait underneath resolves at or above the phase asked for, so a document
+    * something else carried past `Validated` would otherwise hand a full array
+    * back from `parsed()`.
+    *
+    * A copy rather than a clear: the envelope is freshly built here, but
+    * {@link toAstDocument} is overridable and an adopter's version may return
+    * one it also keeps.
+    */
+   protected withoutDiagnostics(document: AstDocument<TAst, TDiagnostic>): AstDocument<TAst, never> {
+      return { ...document, diagnostics: [] };
+   }
 }

package/src/langium/module.ts

@@ -216,7 +216,7 @@ export interface ServerAddedSharedServices<TProject extends Project = Project> {
        * that need to narrow the diagnostic type or override lifecycle
        * behaviour rebind this slot with a subclass.
        */
-      AstDocumentManager: AstDocumentManager<AstNode, unknown>;
+      AstDocumentManager: AstDocumentManager<AstNode>;
       /**
        * Wires the framework's build-time features (integrity, AST
        * enrichment) into Langium's build pipeline: owns the build-phase
@@ -272,7 +272,7 @@ export interface ServerAddedSharedServices<TProject extends Project = Project> {
     */
    model: {
       TransferEncoder: TransferEncoder;
-      ModelService: ModelService<AstNode, unknown>;
+      ModelService: ModelService<AstNode>;
    };
    /**
     * Shared contribution group for batch-level build-phase passes (see

package/src/langium/naming/name-provider.ts

@@ -254,10 +254,21 @@ export interface NameProvider extends LangiumNameProvider {
    /**
     * Find a unique name for a new node within `container`, using `base`
     * as a stem. Walks the AST subtree rooted at `container` and avoids
-    * names already used by `$type === type` nodes there. Default
-    * generates `${base}1`, `${base}2`, ... until an unused value is
-    * found. Used by create-element operation handlers when the
-    * uniqueness scope is one AST subtree.
+    * names already held there by nodes of `type` or of any subtype of it,
+    * as `AstReflection.isSubtype` reports. Default generates `${base}1`,
+    * `${base}2`, ... until an unused value is found. Used by create-element
+    * operation handlers when the uniqueness scope is one AST subtree.
+    *
+    * Subtype-closed rather than `$type`-exact, because a name space shared by
+    * several concrete types is named by their common supertype and by no
+    * concrete type at all — the shape a cross-reference whose target type is
+    * that supertype produces. An exact filter finds no collisions for such a
+    * call and returns the proposal unchanged, which a caller cannot tell from
+    * a name that was genuinely free.
+    * {@link NameProvider.findNextDocumentQualifiedName} and
+    * {@link NameProvider.findNextProjectQualifiedName} resolve `type` the same
+    * way, through `IndexManager.allElements`, so one type argument does not
+    * mean different sets at different tiers.
     */
    findNextName(type: string, base: string, container: AstNode): string;
 
@@ -496,8 +507,9 @@ export class DefaultNameProvider implements NameProvider {
 
    findNextName(type: string, base: string, container: AstNode): string {
       const proposal = base.replaceAll(this.nameSeparator, '_');
+      const reflection = this.services.shared.AstReflection;
       const knownNames = AstUtils.streamAst(container)
-         .filter(node => node.$type === type)
+         .filter(node => reflection.isSubtype(node.$type, type))
          .map(node => this.getOwnName(node))
          .nonNullable()
          .toArray();

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

@@ -12,7 +12,7 @@ import {
    type Tracer,
    type TransferDiagnostic,
    type TransferElement,
-   type TransferDocument,
+   TransferDocument,
    type TransferTypeFor
 } from '@hydranium/protocol';
 import { AstUtils, type AstNode, DocumentCache, DocumentState, isAstNode, isReference, type LangiumDocument } from '@hydranium/langium';
@@ -20,7 +20,7 @@ import { Diagnostic, DiagnosticSeverity } from 'vscode-languageserver-protocol';
 import { type AstDocument } from '../../documents/ast-document-manager.js';
 import { type LogNameOptions } from '../diagnostics/logger.js';
 import { type ServerSharedServicesMinimal } from '../shared-services.js';
-import { type TransferLspDiagnostic } from '../validation/document-validator.js';
+import { type AstDiagnostic } from '../validation/document-validator.js';
 
 /**
  * Which set of properties {@link TransferEncoder.toTransfer} emits.
@@ -108,9 +108,9 @@ export interface TransferEncoder<TDiagnostic extends TransferDiagnostic = Transf
    toTransfer<T extends AstNode>(ast: T, mode?: TransferMode): TransferElement;
    toTransferDocument(langiumDocument: LangiumDocument): TransferDocument<TransferElement, TDiagnostic>;
    astDocumentToTransferDocument<TAst extends AstNode>(
-      document: AstDocument<TAst, TDiagnostic | TransferLspDiagnostic>
+      document: AstDocument<TAst, AstDiagnostic>
    ): TransferDocument<TransferElement, TDiagnostic>;
-   toTransferDiagnostic(diagnostic: TransferLspDiagnostic): TDiagnostic;
+   toTransferDiagnostic(diagnostic: AstDiagnostic): TDiagnostic;
 }
 
 /**
@@ -155,7 +155,7 @@ export interface TransferEncoder<TDiagnostic extends TransferDiagnostic = Transf
  * - {@link toTransferDocument} — bundle root + diagnostics into the wire
  *   {@link TransferDocument} envelope. Override to filter / merge
  *   diagnostics from auxiliary sources or to project a synthesised root.
- * - {@link toTransferDiagnostic} — project a {@link TransferLspDiagnostic}
+ * - {@link toTransferDiagnostic} — project a {@link AstDiagnostic}
  *   (the framework validator's output) to {@link TDiagnostic}.
  */
 export class DefaultTransferEncoder<
@@ -391,12 +391,12 @@ export class DefaultTransferEncoder<
       source: TransferEnvelopeSource<TDiagnostic>,
       root: TransferTypeFor<TAst, TTransferMap>
    ): TransferDocument<TransferTypeFor<TAst, TTransferMap>, TDiagnostic> {
-      return {
-         uri: source.uri,
-         version: source.version,
+      return TransferDocument.create(
+         source.uri,
+         source.version,
          root,
-         diagnostics: source.diagnostics.map(diagnostic => this.toTransferDiagnostic(diagnostic as TransferLspDiagnostic))
-      };
+         source.diagnostics.map(diagnostic => this.toTransferDiagnostic(diagnostic as AstDiagnostic))
+      );
    }
 
    /**
@@ -410,7 +410,7 @@ export class DefaultTransferEncoder<
     * second `LangiumDocuments.getDocument` lookup.
     *
     * The `diagnostic` projection assumes the snapshot's diagnostics carry
-    * the `TransferLspDiagnostic` shape ({@link Diagnostic} plus the
+    * the `AstDiagnostic` shape ({@link Diagnostic} plus the
     * framework validator's `element` / `property` decoration). Snapshots
     * built from raw Langium diagnostics structurally satisfy this — the
     * extra fields are optional in the projection.
@@ -421,7 +421,7 @@ export class DefaultTransferEncoder<
     * assembly seam rather than duplicating it.
     */
    astDocumentToTransferDocument<TAst extends AstNode>(
-      document: AstDocument<TAst, TDiagnostic | TransferLspDiagnostic>
+      document: AstDocument<TAst, AstDiagnostic>
    ): TransferDocument<TransferTypeFor<TAst, TTransferMap>, TDiagnostic> {
       const root = this.encodeNode(document.root, this.createEncodeContext('full', document.uri)) as TransferTypeFor<TAst, TTransferMap>;
       return this.assembleTransferDocument<TAst>(document, root);
@@ -429,7 +429,7 @@ export class DefaultTransferEncoder<
 
    /**
     * Project an LSP-shaped diagnostic (typically a
-    * {@link TransferLspDiagnostic} produced by
+    * {@link AstDiagnostic} produced by
     * `HydraniumDocumentValidator` — adds `element` + optional `property`
     * to the standard {@link Diagnostic} shape) to the wire-diagnostic
     * shape.
@@ -448,7 +448,7 @@ export class DefaultTransferEncoder<
     * Override only if the wire-diagnostic shape needs fields beyond
     * what {@link TransferDiagnostic} carries.
     */
-   toTransferDiagnostic(diagnostic: TransferLspDiagnostic): TDiagnostic {
+   toTransferDiagnostic(diagnostic: AstDiagnostic): TDiagnostic {
       const langiumCode = (diagnostic.data as { code?: string } | undefined)?.code;
       // The same `data` the Langium code comes out of also carries the framework
       // message identity, under its own key so the two conventions co-exist.

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

@@ -46,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
@@ -63,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;
 }
@@ -277,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.
@@ -668,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) {

package/src/testing/fake-document.ts

@@ -9,6 +9,7 @@
 
 import { DocumentState, type AstNode, type AstReflection, type LangiumDocument, UriUtils, type URI } from '@hydranium/langium';
 import { buildAstNode } from '../langium/ast-extension/ast-node-builder.js';
+import { type AstDiagnostic } from '../langium/validation/document-validator.js';
 
 /**
  * Build a typed AST-node fixture for unit tests.
@@ -104,7 +105,7 @@ function stringifyFakeRoot(root: unknown): string {
  * staging. Override via `options.state` for tests that gate on earlier
  * phases.
  */
-export function makeFakeDocument<TAst extends AstNode = AstNode, TDiagnostic = unknown>(
+export function makeFakeDocument<TAst extends AstNode = AstNode, TDiagnostic extends AstDiagnostic = AstDiagnostic>(
    uri: string | URI,
    root: TAst,
    options: FakeDocumentOptions<TAst, TDiagnostic> = {}

package/src/testing/make-test-services.ts

@@ -24,6 +24,7 @@ import type { Harness } from '@hydranium/protocol/testing';
 import { type AstNode, type AstNodeDescription, type WorkspaceLock } from '@hydranium/langium';
 import type { ModelService, ModelServiceOptions } from '../langium/model-service/model-service.js';
 import type { ServerSharedServices } from '../langium/module.js';
+import type { AstDiagnostic } from '../langium/validation/document-validator.js';
 import { DefaultTransferEncoder, type TransferEncoder } from '../langium/transfer/transfer-encoder.js';
 import { DefaultDocumentUriPolicy, type DocumentUriPolicy } from '../langium/workspace/document-uri-policy.js';
 import { HydraniumWorkspaceLock } from '../langium/workspace/hydranium-workspace-lock.js';
@@ -48,12 +49,21 @@ import { makeStubWritableFileSystem, type StubWritableFileSystem } from './stub-
  * to `ServerSharedServices` in {@link makeTestServices} is therefore the
  * single named place where the "stub stands in for the full service tree"
  * assertion happens.
+ *
+ * **`TDiagnostic` and `TTransferDiagnostic` are the two ends of a conversion
+ * and must stay separate.** The first is what the build left on
+ * `LangiumDocument.diagnostics` and what `ModelService` hands back on an
+ * `AstDocument`; the second is what `TransferEncoder.toTransferDiagnostic`
+ * produces for the wire. One parameter serving both makes the tree
+ * unbindable for an adopter who extends either shape, since extending one
+ * says nothing about the other.
  */
 export interface TestSharedServices<
    TAst extends AstNode = AstNode,
-   TDiagnostic extends TransferDiagnostic = TransferDiagnostic,
+   TDiagnostic extends AstDiagnostic = AstDiagnostic,
    TTransfer extends TransferElement = TransferElement,
-   TProject extends Project = Project
+   TProject extends Project = Project,
+   TTransferDiagnostic extends TransferDiagnostic = TransferDiagnostic
 > {
    readonly Clock: Clock;
    readonly Logger: Logger;
@@ -92,7 +102,7 @@ export interface TestSharedServices<
       WorkspaceLock: WorkspaceLock;
    };
    readonly model: {
-      TransferEncoder: TransferEncoder<TDiagnostic>;
+      TransferEncoder: TransferEncoder<TTransferDiagnostic>;
       ModelService: ModelService<TAst, TDiagnostic, TTransfer>;
    };
    /**
@@ -109,9 +119,10 @@ export interface TestSharedServices<
 /** Optional configuration for {@link makeTestServices}. */
 export interface MakeTestServicesOptions<
    TAst extends AstNode = AstNode,
-   TDiagnostic extends TransferDiagnostic = TransferDiagnostic,
+   TDiagnostic extends AstDiagnostic = AstDiagnostic,
    TTransfer extends TransferElement = TransferElement,
-   TProject extends Project = Project
+   TProject extends Project = Project,
+   TTransferDiagnostic extends TransferDiagnostic = TransferDiagnostic
 > {
    /**
     * Serialiser used by the bundled `StubModelService`. The stub tree
@@ -206,7 +217,7 @@ export interface MakeTestServicesOptions<
     * Override the {@link TransferEncoder} factory. Default: framework
     * {@link TransferEncoder} with no overrides.
     */
-   transferEncoder?: (services: ServerSharedServices<TProject>) => TransferEncoder<TDiagnostic>;
+   transferEncoder?: (services: ServerSharedServices<TProject>) => TransferEncoder<TTransferDiagnostic>;
 }
 
 /**
@@ -224,9 +235,10 @@ export interface MakeTestServicesOptions<
  */
 export interface TestServicesBundle<
    TAst extends AstNode = AstNode,
-   TDiagnostic extends TransferDiagnostic = TransferDiagnostic,
+   TDiagnostic extends AstDiagnostic = AstDiagnostic,
    TTransfer extends TransferElement = TransferElement,
-   TProject extends Project = Project
+   TProject extends Project = Project,
+   TTransferDiagnostic extends TransferDiagnostic = TransferDiagnostic
 > extends Harness {
    readonly services: ServerSharedServices<TProject>;
    readonly documents: StubLangiumDocuments<TAst, TDiagnostic>;
@@ -248,7 +260,7 @@ export interface TestServicesBundle<
     */
    readonly indexManager: StubIndexManager | undefined;
    readonly modelService: ModelService<TAst, TDiagnostic, TTransfer>;
-   readonly transferEncoder: TransferEncoder<TDiagnostic>;
+   readonly transferEncoder: TransferEncoder<TTransferDiagnostic>;
    readonly logger: Logger;
    /** The clock bound on the `Clock` slot — a `makeFakeClock()` if one was passed. */
    readonly clock: Clock;
@@ -274,12 +286,13 @@ export interface TestServicesBundle<
  */
 export function makeTestServices<
    TAst extends AstNode = AstNode,
-   TDiagnostic extends TransferDiagnostic = TransferDiagnostic,
+   TDiagnostic extends AstDiagnostic = AstDiagnostic,
    TTransfer extends TransferElement = TransferElement,
-   TProject extends Project = Project
+   TProject extends Project = Project,
+   TTransferDiagnostic extends TransferDiagnostic = TransferDiagnostic
 >(
-   options: MakeTestServicesOptions<TAst, TDiagnostic, TTransfer, TProject> = {}
-): TestServicesBundle<TAst, TDiagnostic, TTransfer, TProject> {
+   options: MakeTestServicesOptions<TAst, TDiagnostic, TTransfer, TProject, TTransferDiagnostic> = {}
+): TestServicesBundle<TAst, TDiagnostic, TTransfer, TProject, TTransferDiagnostic> {
    const documents = makeStubLangiumDocuments<TAst, TDiagnostic>(options.seedDocuments);
    const textDocuments = makeStubHydraniumTextDocuments();
    const documentBuilder = makeStubDocumentBuilder();
@@ -316,7 +329,7 @@ export function makeTestServices<
    // (after the factories run); the literal uses unsafe casts to
    // partially-built objects to satisfy TestSharedServices, then patches
    // them in.
-   const services: TestSharedServices<TAst, TDiagnostic, TTransfer, TProject> = {
+   const services: TestSharedServices<TAst, TDiagnostic, TTransfer, TProject, TTransferDiagnostic> = {
       Clock: clock,
       Logger: logger,
       Tracer: tracer,
@@ -338,7 +351,7 @@ export function makeTestServices<
          ...(indexManager ? { IndexManager: indexManager } : {}),
          WorkspaceLock: new HydraniumWorkspaceLock()
       },
-      model: {} as TestSharedServices<TAst, TDiagnostic, TTransfer, TProject>['model'],
+      model: {} as TestSharedServices<TAst, TDiagnostic, TTransfer, TProject, TTransferDiagnostic>['model'],
       ServerLocale: {} as ServerLocale,
       MessageRenderer: {} as DefaultMessageRenderer
    };
@@ -358,13 +371,13 @@ export function makeTestServices<
    const serialize = options.serialize ?? ((_uri: string, root: TTransfer) => JSON.stringify(root));
    const transferEncoder = options.transferEncoder
       ? options.transferEncoder(sharedServices)
-      : new DefaultTransferEncoder<unknown, TDiagnostic>(sharedServices);
+      : new DefaultTransferEncoder<unknown, TTransferDiagnostic>(sharedServices);
    const modelService = options.modelService
       ? options.modelService(sharedServices)
       : makeStubModelService<TAst, TDiagnostic, TTransfer>(sharedServices, serialize, options.modelServiceOptions);
 
    const mutableModel = services.model as {
-      TransferEncoder: TransferEncoder<TDiagnostic>;
+      TransferEncoder: TransferEncoder<TTransferDiagnostic>;
       ModelService: ModelService<TAst, TDiagnostic, TTransfer>;
    };
    mutableModel.TransferEncoder = transferEncoder;