@hydranium/core 1.0.0-next.187 → 1.0.0-next.189

package/src/langium/shared-services.ts

@@ -12,6 +12,8 @@ import type { LangiumSharedCoreServices } from '@hydranium/langium';
 import type { ServerLocale } from '../locale/server-locale.js';
 import type { MessageRenderer } from '../messages/renderer.js';
 import type { SelfSaveRegistry } from '../documents/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 '../documents/ast-document-manager.js';
 import type { HydraniumDocumentRegistry } from './workspace/langium-documents.js';
 import type { BuildPhasePassService } from './build-phase-pass/build-phase-pass-service.js';
@@ -35,8 +37,8 @@ import type { AdditionalDocumentContribution } from './workspace/additional-docu
  * 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
@@ -98,6 +100,8 @@ export interface ServerSharedServicesMinimal<TProject extends Project = Project>
       BuildPhasePassService: BuildPhasePassService;
       CstResidencyService: CstResidencyService;
       DocumentUriPolicy: DocumentUriPolicy;
+      ModelLedger: ModelLedger;
+      VersionSyncService: VersionSyncService;
    };
 }
 

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

@@ -8,11 +8,12 @@
  ********************************************************************************/
 
 import {
+   asModelVersion,
    hasMessageIdentity,
+   type TransferModelSnapshot,
    type Tracer,
    type TransferDiagnostic,
    type TransferElement,
-   TransferDocument,
    type TransferTypeFor
 } from '@hydranium/protocol';
 import { AstUtils, type AstNode, DocumentCache, DocumentState, isAstNode, isReference, type LangiumDocument } from '@hydranium/langium';
@@ -75,11 +76,21 @@ export interface EncodeContext {
  * `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'>;
 }
 
 /**
@@ -106,10 +117,10 @@ export interface TransferEnvelopeSource<TDiagnostic> {
  */
 export interface TransferEncoder<TDiagnostic extends TransferDiagnostic = TransferDiagnostic> {
    toTransfer<T extends AstNode>(ast: T, mode?: TransferMode): TransferElement;
-   toTransferDocument(langiumDocument: LangiumDocument): TransferDocument<TransferElement, TDiagnostic>;
+   toTransferDocument(langiumDocument: LangiumDocument): EncodedTransferDocument<TransferElement, TDiagnostic>;
    astDocumentToTransferDocument<TAst extends AstNode>(
       document: AstDocument<TAst, AstDiagnostic>
-   ): TransferDocument<TransferElement, TDiagnostic>;
+   ): EncodedTransferDocument<TransferElement, TDiagnostic>;
    toTransferDiagnostic(diagnostic: AstDiagnostic): TDiagnostic;
 }
 
@@ -153,7 +164,7 @@ export interface TransferEncoder<TDiagnostic extends TransferDiagnostic = Transf
  *   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 AstDiagnostic}
  *   (the framework validator's output) to {@link TDiagnostic}.
@@ -336,7 +347,7 @@ export class DefaultTransferEncoder<
    }
 
    /**
-    * 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
@@ -360,7 +371,7 @@ export class DefaultTransferEncoder<
     */
    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)
@@ -368,8 +379,8 @@ export class DefaultTransferEncoder<
       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
       );
@@ -390,17 +401,13 @@ export class DefaultTransferEncoder<
    protected assembleTransferDocument<TAst extends AstNode>(
       source: TransferEnvelopeSource<TDiagnostic>,
       root: TransferTypeFor<TAst, TTransferMap>
-   ): TransferDocument<TransferTypeFor<TAst, TTransferMap>, TDiagnostic> {
-      return TransferDocument.create(
-         source.uri,
-         source.version,
-         root,
-         source.diagnostics.map(diagnostic => this.toTransferDiagnostic(diagnostic as AstDiagnostic))
-      );
+   ): 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
+    * Build a wire {@link EncodedTransferDocument} 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
@@ -422,7 +429,7 @@ export class DefaultTransferEncoder<
     */
    astDocumentToTransferDocument<TAst extends AstNode>(
       document: AstDocument<TAst, AstDiagnostic>
-   ): TransferDocument<TransferTypeFor<TAst, TTransferMap>, TDiagnostic> {
+   ): 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);
    }

package/src/langium/workspace/hydranium-langium-document-factory.ts

@@ -12,10 +12,17 @@ import {
    AstUtils,
    DefaultLangiumDocumentFactory,
    type LangiumDocument,
+   type Mutable,
    type ParseResult,
    type URI
 } from '@hydranium/langium';
+import { type CancellationToken } from 'vscode-languageserver-protocol';
+import { type TextDocument } from 'vscode-languageserver-textdocument';
+import { STALE_VERSION } from '@hydranium/protocol';
+import { type ModelLedger } from '../../documents/model-ledger.js';
+import { type VersionSyncService } from '../../documents/version-sync-service.js';
 import { type ExtendedServiceRegistry } from '../service-registry.js';
+import { type ServerSharedServicesMinimal } from '../shared-services.js';
 import { type Serializer } from '../serialization/serializer.js';
 
 /** Structural view of the per-language serializer slot on the resolved services. */
@@ -57,6 +64,16 @@ export class HydraniumLangiumDocumentFactory extends DefaultLangiumDocumentFacto
     */
    declare protected readonly serviceRegistry: ExtendedServiceRegistry;
 
+   /** Resolved per call: the sync service reaches the registry, which is built with this factory. */
+   protected readonly versionSyncService: () => VersionSyncService;
+   protected readonly modelLedger: () => ModelLedger;
+
+   constructor(services: ServerSharedServicesMinimal) {
+      super(services);
+      this.versionSyncService = () => services.workspace.VersionSyncService;
+      this.modelLedger = () => services.workspace.ModelLedger;
+   }
+
    /**
     * Parse `text` for `uri` under the grammar `languageId` names, instead of
     * the one `uri` routes to.
@@ -95,6 +112,72 @@ export class HydraniumLangiumDocumentFactory extends DefaultLangiumDocumentFacto
       return this.createLangiumDocument<T>(parseResult, uri, undefined, text);
    }
 
+   protected override createLangiumDocument<T extends AstNode = AstNode>(
+      parseResult: ParseResult<T>,
+      uri: URI,
+      textDocument?: TextDocument,
+      text?: string
+   ): LangiumDocument<T> {
+      const document = super.createLangiumDocument(parseResult, uri, textDocument, text);
+      // Without `textDocument` Langium creates one at version 0 on first read,
+      // which needs a language for `uri` that a folder URI does not have.
+      const parsed = parseResult.value.$cstNode?.root.fullText ?? text ?? textDocument?.getText();
+      this.versionSyncService().modelProduced(document, { version: this.versionOfParsedText(uri, parsed, textDocument?.version ?? 0) });
+      return document;
+   }
+
+   /**
+    * The version is read before the parse, for the same reason as in
+    * {@link update}: the text document is the store's, which an edit updates
+    * in place while the parse runs.
+    */
+   protected override async createAsync<T extends AstNode = AstNode>(
+      uri: URI,
+      content: string | TextDocument,
+      cancelToken: CancellationToken
+   ): Promise<LangiumDocument<T>> {
+      const version = typeof content === 'string' ? undefined : content.version;
+      const document = await super.createAsync<T>(uri, content, cancelToken);
+      if (version !== undefined) {
+         this.versionSyncService().modelProduced(document, { version });
+      }
+      return document;
+   }
+
+   /**
+    * The store's version is read before Langium's `update`, which reads the
+    * store's text before its first await: read after, it can belong to an
+    * edit that arrived while the parse ran.
+    *
+    * Reconciled with the store here rather than in a `Parsed` listener, which
+    * a cancel skips, leaving the root on the version of its earlier text.
+    */
+   override async update<T extends AstNode = AstNode>(
+      document: Mutable<LangiumDocument<T>>,
+      cancellationToken: CancellationToken
+   ): Promise<LangiumDocument<T>> {
+      const stored = this.textDocuments?.get(document.uri.toString())?.version;
+      const updated = await super.update(document, cancellationToken);
+      const version =
+         stored ??
+         this.versionOfParsedText(
+            updated.uri,
+            this.modelLedger().textOf(updated.parseResult.value) ?? updated.textDocument.getText(),
+            updated.textDocument.version
+         );
+      this.versionSyncService().modelProduced(updated, { version });
+      return updated;
+   }
+
+   /**
+    * `version`, or {@link STALE_VERSION} when the store holds `uri` open with
+    * other text than `parsed`: text read from the file while an open landed.
+    */
+   protected versionOfParsedText(uri: URI, parsed: string | undefined, version: number): number {
+      const open = this.textDocuments?.get(uri.toString());
+      return open !== undefined && parsed !== undefined && open.getText() !== parsed ? STALE_VERSION : version;
+   }
+
    /**
     * Serialize `model` via the per-language serializer, or `undefined` if none
     * is bound, it fails, or it is async — `fromModel` is synchronous, so an

package/src/langium/workspace/langium-documents.ts

@@ -132,6 +132,17 @@ export class HydraniumLangiumDocuments extends DefaultLangiumDocuments implement
       return this.langiumDocumentFactory.fromString('', uri);
    }
 
+   /**
+    * Registers `document`, then reports it to `VersionSyncService.modelProduced`:
+    * a first load parses outside the build, so no build's re-parse reports it.
+    * That marks one below `Parsed`, such as the builder's placeholder for a new
+    * file, as a placeholder. A rejected duplicate is not reported.
+    */
+   override addDocument(document: LangiumDocument): void {
+      super.addDocument(document);
+      this.services.workspace.VersionSyncService.modelProduced(document);
+   }
+
    override async getOrCreateDocument(uri: URI): Promise<LangiumDocument<AstNode>> {
       const resolved = this.uriPolicy.loadUri(uri);
       if (resolved) {

package/src/lsp/hydranium-document-update-handler.ts

@@ -171,6 +171,9 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
       this.bypassNonLanguageClientChanges = options.bypassNonLanguageClientChanges ?? true;
       this.willSaveGateMs = options.willSaveGateMs ?? 1000;
       this.textDocuments.onDidSaveInLanguageClient(event => this.editorSaves.get(event.uri)?.());
+      services.workspace.VersionSyncService.registerDeferredBuilds(
+         uri => this.pendingChanged.has(uri.toString()) || this.pendingDeleted.has(uri.toString())
+      );
       // A change still debounced for a document the store has released would
       // build it once more after the store's own revert: from the provider
       // again, or, for a document the revert removed, by reading a file that

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

@@ -35,6 +35,8 @@ import { DefaultTransferEncoder, type TransferEncoder } from '../langium/transfe
 import { DefaultDocumentUriPolicy, type DocumentUriPolicy } from '../langium/workspace/document-uri-policy.js';
 import { HydraniumWorkspaceLock } from '../langium/workspace/hydranium-workspace-lock.js';
 import { DefaultFileSystemTaskQueue, type FileSystemTaskQueue } from '../documents/file-system-task-queue.js';
+import { DefaultModelLedger, type ModelLedger } from '../documents/model-ledger.js';
+import { DefaultVersionSyncService, type VersionSyncService } from '../documents/version-sync-service.js';
 import type { FakeDocumentOptions } from './fake-document.js';
 import { makeStubDocumentBuilder, type StubDocumentBuilder } from './stub-document-builder.js';
 import { makeStubIndexManager, type StubIndexManager } from './stub-index-manager.js';
@@ -109,6 +111,10 @@ export interface TestSharedServices<
        * through this tree and let a reentrant write pass unnoticed.
        */
       WorkspaceLock: WorkspaceLock;
+      /** The REAL ledger: it is a weak map with no dependencies. */
+      ModelLedger: ModelLedger;
+      /** The REAL service, over this tree's stubs; it reconciles nothing against the stub store. */
+      VersionSyncService: VersionSyncService;
    };
    readonly model: {
       TransferEncoder: TransferEncoder<TTransferDiagnostic>;
@@ -266,6 +272,7 @@ export interface TestServicesBundle<
    readonly selfSaveRegistry: StubSelfSaveRegistry;
    readonly projectManager: StubProjectManager<TProject>;
    readonly documentUriPolicy: DocumentUriPolicy;
+   readonly modelLedger: ModelLedger;
    /**
     * The registry bound on the `ServiceRegistry` slot, or `undefined` when no
     * {@link MakeTestServicesOptions.languages} were declared.
@@ -320,7 +327,8 @@ export function makeTestServices<
    const selfSaveRegistry = makeStubSelfSaveRegistry();
    const fileSystem = makeStubWritableFileSystem(selfSaveRegistry);
    const projectManager = makeStubProjectManager<TProject>(options.seedProjects);
-   const astDocumentManager = makeStubAstDocumentManager<TAst, TDiagnostic>(textDocuments, fileSystem, documents);
+   const modelLedger = new DefaultModelLedger();
+   const astDocumentManager = makeStubAstDocumentManager<TAst, TDiagnostic>(textDocuments, fileSystem, documents, modelLedger);
    const documentUriPolicy = options.documentUriPolicy ?? new DefaultDocumentUriPolicy();
    const serviceRegistry = options.languages
       ? makeStubServiceRegistry(options.languages, { openLanguageIds: options.openLanguageIds })
@@ -368,7 +376,10 @@ export function makeTestServices<
          // be genuinely ABSENT, not present-and-undefined, when no index was seeded.
          ...(indexManager ? { IndexManager: indexManager } : {}),
          WorkspaceLock: workspaceLock,
-         FileSystemTaskQueue: new DefaultFileSystemTaskQueue({ workspace: { DocumentUriPolicy: documentUriPolicy } })
+         FileSystemTaskQueue: new DefaultFileSystemTaskQueue({ workspace: { DocumentUriPolicy: documentUriPolicy } }),
+         ModelLedger: modelLedger,
+         // Patched in below: it reads the tree it belongs to.
+         VersionSyncService: {} as VersionSyncService
       },
       model: {} as TestSharedServices<TAst, TDiagnostic, TTransfer, TProject, TTransferDiagnostic>['model'],
       ServerLocale: {} as ServerLocale,
@@ -378,6 +389,7 @@ export function makeTestServices<
 
    // Patched in after the literal, like `model` below: both read the tree they
    // belong to, and the renderer reads the locale service.
+   services.workspace.VersionSyncService = new DefaultVersionSyncService(sharedServices);
    const mutableMessages = services as { ServerLocale: ServerLocale; MessageRenderer: MessageRenderer };
    const serverLocale = new DefaultServerLocale(sharedServices);
    if (options.locale) {
@@ -414,6 +426,7 @@ export function makeTestServices<
       selfSaveRegistry,
       projectManager,
       documentUriPolicy,
+      modelLedger,
       serviceRegistry,
       indexManager,
       modelService,

package/src/testing/stub-ast-document-manager.ts

@@ -18,7 +18,8 @@ import {
    type WritableFileSystemProvider
 } from '../documents/ast-document-manager.js';
 import { UNKNOWN_CLIENT_ID } from '../documents/client-ids.js';
-import type { CloseModelArgs, OpenModelArgs } from '@hydranium/protocol';
+import { DefaultModelLedger, type ModelLedger } from '../documents/model-ledger.js';
+import { type CloseModelArgs, type OpenModelArgs } from '@hydranium/protocol';
 import type { StubHydraniumTextDocuments } from './stub-hydranium-text-documents.js';
 import type { StubLangiumDocuments } from './stub-langium-documents.js';
 
@@ -60,6 +61,7 @@ export interface StubAstDocumentManager<TAst extends AstNode, TDiagnostic extend
    | 'onClientClosed'
    | 'getAuthor'
    | 'getDocument'
+   | 'toAstDocument'
    | 'attributeUpdate'
 > {
    readonly openClients: Map<string, Set<string>>;
@@ -109,7 +111,8 @@ export interface StubAstDocumentManager<TAst extends AstNode, TDiagnostic extend
 export function makeStubAstDocumentManager<TAst extends AstNode, TDiagnostic extends AstDiagnostic = AstDiagnostic>(
    textDocuments: StubHydraniumTextDocuments,
    fileSystem: Pick<WritableFileSystemProvider, 'writeFile'>,
-   documents?: StubLangiumDocuments<TAst, TDiagnostic>
+   documents?: StubLangiumDocuments<TAst, TDiagnostic>,
+   ledger: ModelLedger = new DefaultModelLedger()
 ): StubAstDocumentManager<TAst, TDiagnostic> {
    const openClients = new Map<string, Set<string>>();
    // Keyed by the URI as given, not canonicalized: the stub has no URI policy,
@@ -226,6 +229,11 @@ export function makeStubAstDocumentManager<TAst extends AstNode, TDiagnostic ext
       // that need real symlink canonicalization wire the real AstDocumentManager).
       getDocument(uri: string): LangiumDocument | undefined {
          return documents?.getDocument(UriUtils.toUri(uri));
+      },
+      toAstDocument(document: LangiumDocument): AstDocument<TAst, TDiagnostic> {
+         const uri = document.textDocument.uri;
+         const root = document.parseResult.value as TAst;
+         return AstDocument.create<TAst, TDiagnostic>(uri, ledger.versionOf(root), root, document.diagnostics as TDiagnostic[] | undefined);
       }
    };
 }

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

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import type { CanonicalUri } from '@hydranium/protocol';
+import { type CanonicalUri, textHash } from '@hydranium/protocol';
 import type { ApplyWorkspaceEditResult } from 'vscode-languageserver';
 import { Disposable, Emitter } from 'vscode-languageserver';
 import type { TextDocument } from 'vscode-languageserver-textdocument';
@@ -36,7 +36,7 @@ export interface StubTextDocumentEntry {
  * `isOpenInAnyClient` / `isOpenInClient` / `isRevertPending` /
  * `openDocuments`), the push channel
  * to the language client (`applyEditToLanguageClient` / `stagePendingContent`),
- * the save / close notifications, the dirty state (`isDirty` /
+ * the save / close notifications, the dirty state (`isDirty` / `textState` /
  * `onDidChangeDirty` / `updateDiskBaseline`, against a baseline {@link seedOpen}
  * sets and a save that carries its text moves), and the client-session table
  * (`registerSession` / `closeSession` / `onDidCloseSession`), which is a real
@@ -88,6 +88,7 @@ export interface StubHydraniumTextDocuments extends Pick<
    | 'onDidCloseSession'
    | 'onDidCloseLastOpen'
    | 'isDirty'
+   | 'textState'
    | 'onDidChangeDirty'
    | 'updateDiskBaseline'
 > {
@@ -176,7 +177,7 @@ export function makeStubHydraniumTextDocuments(): StubHydraniumTextDocuments {
          } else {
             dirty.delete(uri);
          }
-         dirtyChanged.fire({ uri: key(uri), dirty: now });
+         dirtyChanged.fire({ uri: key(uri), text: { version: held?.version ?? 0, hash: textHash(held?.text ?? ''), dirty: now } });
       }
    };
 
@@ -200,6 +201,10 @@ export function makeStubHydraniumTextDocuments(): StubHydraniumTextDocuments {
       version(uri) {
          return docs.get(uri)?.version ?? 0;
       },
+      textState(uri) {
+         const held = docs.get(uri);
+         return held && { version: held.version, hash: textHash(held.text), dirty: dirty.has(uri) };
+      },
       notifyDidChangeTextDocument(event, clientId = LANGUAGE_CLIENT_ID) {
          const existing = docs.get(event.textDocument.uri);
          const next: StubTextDocumentEntry = {