@hydranium/core 1.0.0-next.35 → 1.0.0-next.350

package/src/langium/shared-services.ts

@@ -10,9 +10,11 @@
 import type { Clock, Logger, Project, Tracer } from '@hydranium/protocol';
 import type { LangiumSharedCoreServices } from '@hydranium/langium';
 import type { ServerLocale } from '../locale/server-locale.js';
-import type { ServerMessageRenderer } from '../messages/renderer.js';
-import type { SelfSaveRegistry } from '../documents/self-save-registry.js';
-import type { WritableFileSystemProvider } from '../documents/ast-document-manager.js';
+import type { MessageRenderer } from '../messages/renderer.js';
+import type { SelfSaveRegistry } from './workspace/self-save-registry.js';
+import type { ModelLedger } from '../documents/model-ledger.js';
+import type { VersionSyncService } from '../documents/version-sync-service.js';
+import type { WritableFileSystemProvider } from './workspace/file-system-provider.js';
 import type { HydraniumDocumentRegistry } from './workspace/langium-documents.js';
 import type { BuildPhasePassService } from './build-phase-pass/build-phase-pass-service.js';
 import type { CstResidencyService } from './residency/cst-residency-service.js';
@@ -21,6 +23,7 @@ import type { ProjectManager } from './project/project-manager.js';
 import type { ExtendedServiceRegistry } from './service-registry.js';
 import type { DocumentUriPolicy } from './workspace/document-uri-policy.js';
 import type { HydraniumWorkspaceManager } from './workspace/hydranium-workspace-manager.js';
+import type { HydraniumDocumentBuilder } from './document-builder/document-builder.js';
 import type { AdditionalDocumentContribution } from './workspace/additional-document-contribution.js';
 
 /**
@@ -31,12 +34,12 @@ import type { AdditionalDocumentContribution } from './workspace/additional-docu
  * {@link Clock}, {@link Logger} and {@link Tracer} top-level slots (injectable
  * time source, emission-only logger, and the measure-and-emit tracer composed
  * from the other two), the {@link AdditionalDocumentContribution} group, the
- * {@link ServerMessageRenderer} and the {@link ServerLocale} it renders in,
+ * {@link MessageRenderer} and the {@link ServerLocale} it renders in,
  * an {@link ExtendedServiceRegistry}, and on `workspace` a writable file-system
  * provider plus {@link HydraniumWorkspaceManager}, {@link ProjectManager},
  * {@link SelfSaveRegistry}, {@link BuildPipelineIntegration},
- * {@link BuildPhasePassService}, {@link CstResidencyService} and
- * {@link DocumentUriPolicy}.
+ * {@link BuildPhasePassService}, {@link CstResidencyService},
+ * {@link DocumentUriPolicy}, {@link ModelLedger} and {@link VersionSyncService}.
  *
  * Declared structurally (interface extends + intersection on nested slots)
  * so the full `ServerSharedServices` and any consumer-extended variant
@@ -66,7 +69,7 @@ export interface ServerSharedServicesMinimal<TProject extends Project = Project>
     * shared tier with no workspace dependency, because all three heads'
     * messages pass through it.
     */
-   MessageRenderer: ServerMessageRenderer;
+   MessageRenderer: MessageRenderer;
    /** The locale an init handed the server, for whoever renders in it. */
    ServerLocale: ServerLocale;
    /**
@@ -92,12 +95,18 @@ export interface ServerSharedServicesMinimal<TProject extends Project = Project>
       // only through this narrowing — a scope provider querying a URI before
       // the file exists is the caller that needs it.
       /* override */ LangiumDocuments: HydraniumDocumentRegistry;
+      // Same, for the builder: only the framework's has `onBuildEnded`, which a
+      // per-build report needs because Langium's phases stay silent for a
+      // build that validates nothing.
+      /* override */ DocumentBuilder: HydraniumDocumentBuilder;
       ProjectManager: ProjectManager<TProject>;
       SelfSaveRegistry: SelfSaveRegistry;
       BuildPipelineIntegration: BuildPipelineIntegration;
       BuildPhasePassService: BuildPhasePassService;
       CstResidencyService: CstResidencyService;
       DocumentUriPolicy: DocumentUriPolicy;
+      ModelLedger: ModelLedger;
+      VersionSyncService: VersionSyncService;
    };
 }
 

package/src/langium/single-langium-copy.ts

@@ -0,0 +1,42 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+import { AbstractAstReflection, type AstReflection } from '@hydranium/langium';
+
+/**
+ * Fail fast when `reflection` extends `AbstractAstReflection` from a second
+ * copy of `langium`, which the files `langium-cli` generates run on: a second
+ * install, or one install a bundler or test runner loads twice.
+ *
+ * A reflection whose prototype chain misses this copy's base is taken to come
+ * from another copy when it carries the `subtypes` and `allSubtypes` fields that
+ * base creates, which `AstReflection` does not declare. Fields rather than the
+ * class name, because bundlers and minifiers rename classes; a hand-written
+ * reflection passes unless it declares both fields itself.
+ */
+export function assertSingleLangiumCopy(
+   reflection: AstReflection,
+   subject: () => string = () => `the shared AstReflection (${reflection.constructor?.name ?? 'no constructor'})`
+): void {
+   if (reflection instanceof AbstractAstReflection) {
+      return;
+   }
+   if (Object.hasOwn(reflection, 'subtypes') && Object.hasOwn(reflection, 'allSubtypes')) {
+      throw new Error(
+         `[hydranium] ${subject()} extends \`AbstractAstReflection\` from another instance of \`langium\` than ` +
+            'the one `@hydranium/langium` loads, a second physical copy or one install loaded twice, so the generated ' +
+            'code runs on one and the framework on the other. Values Langium compares by identity, such as its ' +
+            'cancellation signal, are not recognised across the two. `npm explain langium` lists each installed copy ' +
+            'and what requires it. If your package resolves another version, declare `langium` at the version ' +
+            '`@hydranium/langium` pins and reinstall from scratch, without the lockfile; in a workspace, declare the ' +
+            'same pins in the root as well. If a test runner or bundler inlines `langium` but not `@hydranium/*`, ' +
+            'load both the same way.'
+      );
+   }
+}

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

@@ -8,11 +8,12 @@
  ********************************************************************************/
 
 import {
+   asModelVersion,
    hasMessageIdentity,
+   type TransferModelSnapshot,
    type Tracer,
    type TransferDiagnostic,
    type TransferElement,
-   type TransferDocument,
    type TransferTypeFor
 } from '@hydranium/protocol';
 import { AstUtils, type AstNode, DocumentCache, DocumentState, isAstNode, isReference, type LangiumDocument } from '@hydranium/langium';
@@ -20,7 +21,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.
@@ -29,26 +30,29 @@ import { type TransferLspDiagnostic } from '../validation/document-validator.js'
  *   including AST-extension-derived computed scalars and synthetic child
  *   mirrors. This is the wire shape clients consume, and the default.
  * - `'grammar'` — only the grammar-declared properties, per
- *   `AstReflection.getTypeMetaData($type).properties`. Excludes every
- *   computed / synthetic property by construction (no naming convention,
- *   no registration). Yields the authored state a serializer round-trips —
- *   a diffable, acyclic baseline for field-level recording / forward-write
- *   reconcile.
+ *   `AstReflection.getTypeMetaData($type).properties`, each carrying the
+ *   node's own authored value. Excludes every computed / synthetic property
+ *   by construction (no naming convention, no registration) and bypasses the
+ *   `resolvePropertyValue` substitution hook, so neither a computed KEY nor a
+ *   computed VALUE can reach this shape. Yields the authored state a
+ *   serializer round-trips — a diffable, acyclic baseline for field-level
+ *   recording / forward-write reconcile.
  */
 export type TransferMode = 'full' | 'grammar';
 
 /**
  * Per-encode inputs threaded through the {@link TransferEncoder} walk and its
  * hooks. Created once per encode entry (see
- * {@link TransferEncoder.createEncodeContext}) and passed unchanged through
- * the recursion, so every hook invocation of one encode observes the same
- * inputs — unlike instance state, which two interleaving encodes would
+ * {@link DefaultTransferEncoder.createEncodeContext}) and passed unchanged
+ * through the recursion, so every hook invocation of one encode observes the
+ * same inputs — unlike instance state, which two interleaving encodes would
  * clobber.
  *
  * Adopters widen the context by overriding `createEncodeContext` with a
  * covariant return type and narrowing the hook parameter types accordingly
  * (TypeScript method bivariance admits the narrowing). An input that changes
- * the encoded output must also be folded into {@link TransferEncoder.rootCacheKey}.
+ * the encoded output must also be folded into
+ * {@link DefaultTransferEncoder.rootCacheKey}.
  */
 export interface EncodeContext {
    /** Property-set selection for this encode — see {@link TransferMode}. */
@@ -63,21 +67,62 @@ export interface EncodeContext {
 }
 
 /**
- * The non-root inputs {@link TransferEncoder.assembleTransferDocument} needs to
- * build a wire envelope. Both of the encoder's document paths narrow to this
- * before assembling — a built `LangiumDocument` (whose `uri` / `version` live on
- * its `textDocument`) and a server-internal `AstDocument` snapshot, which
- * satisfies the shape structurally — so the assembly seam has exactly one
- * implementation to override.
+ * The non-root inputs {@link DefaultTransferEncoder.assembleTransferDocument}
+ * needs to build a wire envelope. Both of the encoder's document paths narrow
+ * to this before assembling — a built `LangiumDocument` (whose `uri` /
+ * `version` live on its `textDocument`) and a server-internal `AstDocument`
+ * snapshot, which satisfies the shape structurally — so the assembly seam has
+ * exactly one implementation to override.
  *
  * `diagnostics` accepts either the wire shape (an already-projected
  * `TDiagnostic`, as a snapshot may carry) or a raw LSP {@link Diagnostic}; the
  * assembly projects each through {@link TransferEncoder.toTransferDiagnostic}.
+ * Absent for a document not validated yet, and left absent on the wire.
  */
 export interface TransferEnvelopeSource<TDiagnostic> {
    readonly uri: string;
    readonly version: number;
-   readonly diagnostics: readonly (TDiagnostic | Diagnostic)[];
+   readonly diagnostics?: readonly (TDiagnostic | Diagnostic)[];
+}
+
+/**
+ * A `TransferDocument` as the encoder produces it: the model block without
+ * its `hash`, which the data server computes from the encoded model.
+ */
+export interface EncodedTransferDocument<TTransfer extends TransferElement, TDiagnostic = TransferDiagnostic> {
+   uri: string;
+   model: Omit<TransferModelSnapshot<TTransfer, TDiagnostic>, 'hash'>;
+}
+
+/**
+ * The AST→transfer contract a DI slot holds, implemented by
+ * {@link DefaultTransferEncoder}.
+ *
+ * **This is an interface and not the class, and that is load-bearing.** A class
+ * in a slot drags its `protected` members into every assignability check, which
+ * TypeScript compares NOMINALLY — so the slot type could not be satisfied by a
+ * subclass declared against a second physical copy of this package, and an
+ * adopter narrowing the slot had to intersect with the framework's declaration
+ * rather than replace it, leaving method resolution dependent on declaration
+ * order. An interface has no protected members and is compared structurally, so
+ * neither applies.
+ *
+ * **The transfer returns are the structural base ({@link TransferElement}), not
+ * the per-grammar overlay.** The overlay cannot parameterise this contract:
+ * `TransferTypeFor` reaches `keyof TTransferMap`, which makes that parameter
+ * measured-INVARIANT, and invariant parameters relate only when their arguments
+ * are mutually assignable — so a map-parameterised contract admits no adopter
+ * instantiation at all. Heads read this contract and do not know adopter maps;
+ * an adopter recovers the precise type by declaring its own slot, which it can
+ * now do by replacement.
+ */
+export interface TransferEncoder<TDiagnostic extends TransferDiagnostic = TransferDiagnostic> {
+   toTransfer<T extends AstNode>(ast: T, mode?: TransferMode): TransferElement;
+   toTransferDocument(langiumDocument: LangiumDocument): EncodedTransferDocument<TransferElement, TDiagnostic>;
+   astDocumentToTransferDocument<TAst extends AstNode>(
+      document: AstDocument<TAst, AstDiagnostic>
+   ): EncodedTransferDocument<TransferElement, TDiagnostic>;
+   toTransferDiagnostic(diagnostic: AstDiagnostic): TDiagnostic;
 }
 
 /**
@@ -97,8 +142,8 @@ export interface TransferEnvelopeSource<TDiagnostic> {
  *   resolving each AST type to its declared wire shape. Default is
  *   `Record<string, TransferElement>`, which collapses every encoded node
  *   to the structural base — adequate for adopters without a generated
- *   overlay; richer adopters declare typed maps for autocomplete on the
- *   encoder's return types.
+ *   overlay; an adopter passes the generated `<LanguageId>TransferTypes` to
+ *   type the encoder's returns by the grammar.
  * - `TDiagnostic` — wire-diagnostic shape produced by
  *   {@link toTransferDiagnostic}. Constrained to extend
  *   {@link TransferDiagnostic} so the framework default (which constructs a
@@ -113,18 +158,19 @@ export interface TransferEnvelopeSource<TDiagnostic> {
  * - {@link propertyKeys} — which property names the walk visits.
  * - {@link shouldEmitProperty} — per-key filter on top of the default
  *   `$`-internals strip.
- * - {@link resolvePropertyValue} — value substitution per property.
+ * - {@link resolvePropertyValue} — value substitution per property, `'full'`
+ *   mode only (see there for why `'grammar'` bypasses it).
  * - {@link finalizeTransferNode} — post-decoration per encoded node.
  * - {@link toTransferValue} — recursion seam per property value. Override
  *   to special-case reference encoding or to drop specific value shapes.
  * Envelope-level seams:
  * - {@link toTransferDocument} — bundle root + diagnostics into the wire
- *   {@link TransferDocument} envelope. Override to filter / merge
+ *   {@link EncodedTransferDocument} 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 TransferEncoder<
+export class DefaultTransferEncoder<
    // The map is intentionally unconstrained — adopters supply typed
    // overlays whose specific-key shapes don't structurally satisfy a
    // `Record<string, TransferElement>` index signature. `TransferTypeFor`
@@ -227,7 +273,14 @@ export class TransferEncoder<
          if (!this.shouldEmitProperty(ast, key, context)) {
             continue;
          }
-         const value = this.resolvePropertyValue(ast, key, context);
+         // `'grammar'` reads the authored value straight off the node rather than
+         // through `resolvePropertyValue`. The mode promises a shape the serializer
+         // round-trips, and a value-substitution hook cannot honour that: what it
+         // returns is by construction not what the document declared. Scoping the
+         // hook to `'full'` is what makes that guarantee structural instead of a
+         // rule every override has to remember.
+         const value =
+            context.mode === 'grammar' ? (ast as unknown as Record<string, unknown>)[key] : this.resolvePropertyValue(ast, key, context);
          // `'grammar'` lists every declared property, including those absent on
          // this node; skip the absent ones. (`'full'` enumerates only own
          // properties, so absent properties never surface there.) Part of the
@@ -268,8 +321,17 @@ export class TransferEncoder<
    }
 
    /**
-    * Which value the walk emits under `key`. Default: the node's own value.
-    * Override to substitute a derived value under a grammar property name.
+    * Which value the walk emits under `key`, in `'full'` mode ONLY. Default:
+    * the node's own value.
+    *
+    * Override to substitute a derived value under a grammar property name — an
+    * inheritance-resolved field, a preference-dependent label. `'grammar'`
+    * bypasses this hook and reads the node directly: that mode's contract is
+    * the authored state a serializer round-trips, and a substituted value is by
+    * construction not the one the document declared. An override that applied
+    * in both modes would leave the grammar shape carrying derived values under
+    * declared property names — diffable and acyclic still, but no longer
+    * authored, which is the property every consumer of that mode relies on.
     */
    protected resolvePropertyValue(ast: AstNode, key: string, _context: EncodeContext): unknown {
       return (ast as unknown as Record<string, unknown>)[key];
@@ -286,7 +348,7 @@ export class TransferEncoder<
    }
 
    /**
-    * Build a wire {@link TransferDocument} envelope from a built
+    * Build a wire {@link EncodedTransferDocument} envelope from a built
     * {@link LangiumDocument}. The `'full'` root is served from the internal
     * {@link rootCache} (memoised per document until it next rebuilds), under
     * {@link rootCacheKey} — so the data-server's fingerprint and emitted
@@ -310,7 +372,7 @@ export class TransferEncoder<
     */
    toTransferDocument<TAst extends AstNode>(
       langiumDocument: LangiumDocument
-   ): TransferDocument<TransferTypeFor<TAst, TTransferMap>, TDiagnostic> {
+   ): EncodedTransferDocument<TransferTypeFor<TAst, TTransferMap>, TDiagnostic> {
       const context = this.createEncodeContext('full', langiumDocument.uri.toString());
       const root = this.rootCache.get(langiumDocument.uri, this.rootCacheKey(context), () =>
          this.encodeNode(langiumDocument.parseResult.value, context)
@@ -318,8 +380,8 @@ export class TransferEncoder<
       return this.assembleTransferDocument<TAst>(
          {
             uri: langiumDocument.textDocument.uri,
-            version: langiumDocument.textDocument.version,
-            diagnostics: langiumDocument.diagnostics ?? []
+            version: this.services.workspace.ModelLedger.versionOf(langiumDocument.parseResult.value),
+            diagnostics: langiumDocument.diagnostics
          },
          root
       );
@@ -340,27 +402,22 @@ export class TransferEncoder<
    protected assembleTransferDocument<TAst extends AstNode>(
       source: TransferEnvelopeSource<TDiagnostic>,
       root: TransferTypeFor<TAst, TTransferMap>
-   ): TransferDocument<TransferTypeFor<TAst, TTransferMap>, TDiagnostic> {
-      return {
-         uri: source.uri,
-         version: source.version,
-         root,
-         diagnostics: source.diagnostics.map(diagnostic => this.toTransferDiagnostic(diagnostic as TransferLspDiagnostic))
-      };
+   ): EncodedTransferDocument<TransferTypeFor<TAst, TTransferMap>, TDiagnostic> {
+      const diagnostics = source.diagnostics?.map(diagnostic => this.toTransferDiagnostic(diagnostic as AstDiagnostic));
+      return { uri: source.uri, model: { root, version: asModelVersion(source.version), ...(diagnostics ? { diagnostics } : {}) } };
    }
 
    /**
-    * Build a wire {@link TransferDocument} envelope from a server-internal
-    * {@link AstDocument} snapshot (the AST-typed envelope emitted by
-    * `AstDocumentManager.onUpdate` / `onSave` and returned from
-    * `ModelService.request` / `update` / `save`). Distinct from
+    * Build a wire {@link EncodedTransferDocument} envelope from a server-internal
+    * {@link AstDocument} snapshot (the AST-typed envelope `ModelService`'s
+    * events carry and its reads and session writes return). Distinct from
     * {@link toTransferDocument}(`LangiumDocument`) which encodes against
     * the live build artifact — adopter facade returns hold the snapshot
     * directly, and this helper bridges that to the wire shape without a
     * 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.
@@ -371,15 +428,15 @@ export class TransferEncoder<
     * assembly seam rather than duplicating it.
     */
    astDocumentToTransferDocument<TAst extends AstNode>(
-      document: AstDocument<TAst, TDiagnostic | TransferLspDiagnostic>
-   ): TransferDocument<TransferTypeFor<TAst, TTransferMap>, TDiagnostic> {
+      document: AstDocument<TAst, AstDiagnostic>
+   ): EncodedTransferDocument<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);
    }
 
    /**
     * 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.
@@ -398,7 +455,7 @@ export class TransferEncoder<
     * 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.