@hydranium/core 1.0.0-next.10

package/src/langium/workspace/additional-document-contribution.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 MaybePromise } from '@hydranium/protocol';
+import { type AstNode, type LangiumDocument } from '@hydranium/langium';
+import { type WorkspaceFolder } from 'vscode-languageserver-types';
+
+/**
+ * Registry handed to an {@link AdditionalDocumentContribution} — a pure sink,
+ * like the AST-extension / integrity / scope registries: the workspace
+ * {@link folders} being initialized plus a {@link register} sink that seeds each
+ * built document into the workspace.
+ *
+ * Transient, unlike those lifetime-held registries: their registrations are
+ * *consulted repeatedly* (per build, per scope query), so the owning service
+ * holds them; additional documents are seeded *once* at startup — nothing
+ * consults them later — so the workspace manager materialises this registry
+ * during `loadAdditionalDocuments` (the only point Langium's document collector
+ * is in scope) and discards it.
+ *
+ * The registry does NOT hand over a `LangiumDocumentFactory`: a contribution is
+ * DI-instantiated with `services` (the standard contribution pattern) and reads
+ * `services.workspace.LangiumDocumentFactory` itself to build its documents.
+ */
+export interface AdditionalDocumentRegistry {
+   /**
+    * The workspace folders being initialized (empty for a folderless init) —
+    * the same input Langium hands `loadAdditionalDocuments`. Lets a contribution
+    * key its documents off the workspace (per-folder libraries,
+    * workspace-relative resolution).
+    */
+   readonly folders: readonly WorkspaceFolder[];
+   /** Seed a built document into the workspace (indexed like any startup document). */
+   register(document: LangiumDocument<AstNode>): void;
+}
+
+/**
+ * Declarative registration of additional startup documents — the contribution
+ * form of overriding `DefaultWorkspaceManager.loadAdditionalDocuments`. Bound
+ * under the shared `additionalDocuments` group; the framework workspace manager
+ * reads its own group during startup and calls this method, handing in a
+ * transient {@link AdditionalDocumentRegistry}.
+ *
+ * A registered document is added to the workspace and indexed like any file, so
+ * its exported symbols reach the global scope with no manual scope extension.
+ * For a virtual (`virtualUri`) document with no owning project, that indexing
+ * classifies it universal-tier (visible everywhere) — the standard way to
+ * contribute a stdlib / library / built-in set.
+ *
+ * The domain-qualified method name lets a single cross-cutting class implement
+ * several contribution interfaces without method collision.
+ */
+export interface AdditionalDocumentContribution {
+   registerAdditionalDocuments(registry: AdditionalDocumentRegistry): MaybePromise<void>;
+}
+
+/**
+ * Iterate an {@link AdditionalDocumentContribution} group, handing each a
+ * transient registry (workspace `folders` + a `register` sink) and seeding the
+ * registered documents through `collect`. Awaits each contribution so async
+ * document construction is supported. Pure over its inputs (no services / DI)
+ * so it is unit-testable; the framework workspace manager calls it from
+ * `loadAdditionalDocuments`.
+ */
+export async function collectAdditionalDocuments(
+   contributions: Record<string, AdditionalDocumentContribution>,
+   folders: readonly WorkspaceFolder[],
+   collect: (document: LangiumDocument<AstNode>) => void
+): Promise<void> {
+   const registry: AdditionalDocumentRegistry = { folders, register: collect };
+   for (const contribution of Object.values(contributions)) {
+      await contribution.registerAdditionalDocuments(registry);
+   }
+}

package/src/langium/workspace/document-uri-policy.ts

@@ -0,0 +1,187 @@
+/********************************************************************************
+ * 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 CanonicalUri, asCanonicalUri } from '@hydranium/protocol';
+import { type URI, UriUtils } from '@hydranium/langium';
+import { type ServerSharedServicesMinimal } from '../shared-services.js';
+
+/**
+ * The slice of the filesystem provider {@link RealpathDocumentUriPolicy}
+ * consults — just the optional `realpath` primitive. Declared locally so the
+ * workspace-layer policy stays decoupled from the documents-layer
+ * `WritableFileSystemProvider`; the production binding (the Node
+ * `DefaultFileSystemProvider`) supplies the method, an in-memory / browser
+ * provider omits it (and the policy then degrades to the syntactic default).
+ */
+export interface RealpathCapableFileSystem {
+   realpath?(uri: URI): URI | undefined;
+}
+
+/**
+ * Report whether `uri`'s real on-disk path differs from its syntactic
+ * normalisation — the condition under which a language client's URI (`S`)
+ * diverges from the canonical document identity (`R`) the build keys by.
+ * Returns the resolved real URI when they differ, else
+ * `undefined` (non-divergent, absent, or a provider with no `realpath`).
+ *
+ * A diagnostic primitive, not part of the keying path: the
+ * `HydraniumWorkspaceManager` runs it once over the workspace roots at
+ * startup to surface "this workspace path resolves through a symlink/`..`/case
+ * variant, so client URIs will diverge from canonical identity" — the empirical
+ * answer to whether the divergence machinery is exercised in a given deployment
+ * (a plain on-disk workspace yields nothing).
+ */
+export function findRealpathDivergence(uri: URI | string, fs: RealpathCapableFileSystem): URI | undefined {
+   const parsed = UriUtils.toUri(uri);
+   const real = parsed && fs.realpath?.(parsed);
+   return real && UriUtils.normalize(real) !== UriUtils.normalize(uri) ? real : undefined;
+}
+
+/**
+ * The workspace's URI-interpretation strategy — how the framework turns an
+ * arbitrary incoming URI into the two identities every layer must agree on.
+ * Two related-but-distinct operations:
+ *
+ * - {@link canonicalUri} — TOTAL: maps any URI to the single canonical *string*
+ *   the framework keys a document by, regardless of whether the file exists.
+ *   This is the form that MUST match the adopter's `LangiumDocuments` keying so
+ *   the text store, AST-document event filters
+ *   (`AstDocumentManager.onUpdate` / `onSave` / `onClientClosed`), and
+ *   `LangiumDocuments` lookups all agree on one identity for the same file. Use
+ *   for keying, comparison, and the text-store ↔ document-store bridges.
+ *
+ * - {@link loadUri} — EXISTENCE-AWARE: maps a URI to the *load* URI, or
+ *   `undefined` when there is no loadable on-disk content for it. Use where the
+ *   next step actually touches the filesystem (loading a document, walking a
+ *   directory): `undefined` means "skip / treat as empty" rather than attempt a
+ *   doomed read. The default treats every URI as loadable (returns it
+ *   unchanged); a real-path policy returns the resolved file URI, or `undefined`
+ *   for a not-yet-written path.
+ *
+ * The framework default ({@link DefaultDocumentUriPolicy}) is Langium's
+ * syntactic `UriUtils.normalize`, which matches Langium's
+ * `DefaultLangiumDocuments` keying. Adopters that strengthen document identity
+ * — e.g. resolving symlinks / linked files to their real path — bind
+ * {@link RealpathDocumentUriPolicy}, or their own equivalent, so every layer
+ * keys by the same stronger form. Otherwise the layers disagree: a subscriber
+ * that opened a *symlinked* file would receive save events but silently no
+ * update events because the text-store URI and the `LangiumDocument` URI for
+ * the same file diverge.
+ *
+ * Contract: `canonicalUri` MUST be idempotent —
+ * `canonicalUri(canonicalUri(u)) === canonicalUri(u)` — because callers feed
+ * it URIs that may already be canonical (e.g. a `LangiumDocument.uri` straight
+ * off the build pipeline).
+ */
+export interface DocumentUriPolicy {
+   canonicalUri(uri: URI | string): CanonicalUri;
+   /**
+    * Existence-aware resolution to the load URI, or `undefined` when there is
+    * no loadable content for `uri` (missing / synthetic). Callers that read the
+    * filesystem next use `undefined` to skip rather than attempt a doomed read.
+    */
+   loadUri(uri: URI | string): URI | undefined;
+}
+
+/**
+ * Framework default: Langium's syntactic normalisation. Pure and
+ * filesystem-free, so it is browser-safe and matches `DefaultLangiumDocuments`
+ * keying. Adopters resolving symlinks bind {@link RealpathDocumentUriPolicy}
+ * (or their own equivalent) instead.
+ */
+export class DefaultDocumentUriPolicy implements DocumentUriPolicy {
+   canonicalUri(uri: URI | string): CanonicalUri {
+      // Mint point: the sole place a CanonicalUri is created under the default
+      // (syntactic) policy. `asCanonicalUri` is the brand mint — see CanonicalUri.
+      return asCanonicalUri(UriUtils.normalize(uri));
+   }
+
+   /**
+    * No filesystem access, so existence cannot be checked — every URI is
+    * treated as loadable and returned unchanged. A later load that misses
+    * therefore reaches the filesystem and throws, which
+    * `AbstractHydraniumLangiumDocuments.getOrCreateDocument` absorbs into its
+    * empty-document fallback: under this policy that fallback, not this method,
+    * is what makes a missing file a placeholder rather than an error.
+    */
+   loadUri(uri: URI | string): URI | undefined {
+      return UriUtils.toUri(uri);
+   }
+}
+
+/**
+ * {@link DocumentUriPolicy} for adopters whose document identity is the real
+ * on-disk path: resolves `file:` URIs through the `FileSystemProvider`'s
+ * `realpath` primitive so a symlinked file and its target collapse to one
+ * canonical key. Bind this and the single seam drives `LangiumDocuments`
+ * keying, the AST-document event filters, and the document builder's directory
+ * flattening all at once.
+ *
+ * ## What this adds over the {@link DefaultDocumentUriPolicy} (`UriUtils.normalize`)
+ *
+ * `normalize` is purely *syntactic*: it parses and re-serialises the URI string
+ * (lower-cases the scheme, regularises percent-encoding and separators). It is
+ * pure, filesystem-free, and browser-safe — but it knows nothing about the disk,
+ * so two strings that denote the *same file* through different paths stay
+ * distinct keys. This policy is the filesystem-backed strengthening; for `file:`
+ * URIs it additionally:
+ *
+ * - **Collapses symlinks** to their target — the headline reason to bind it. A
+ *   symlinked file (or a file reached through a symlinked directory) and its
+ *   real path become one document instead of two divergent identities.
+ * - **Resolves `..` / `.` segments** — `realpath` walks the real path, so
+ *   `/ws/sub/../a.txt` folds to `/ws/a.txt`; `normalize` leaves dot segments as-is.
+ * - **Case-folds on case-insensitive filesystems** (macOS / Windows): `realpath`
+ *   returns the actual on-disk casing, so `/Foo/x.txt` and `/foo/x.txt` collapse to
+ *   one key. `normalize` keeps them distinct — which on those platforms would
+ *   register one physical file as two documents.
+ *
+ * ## Delegation, not a syscall
+ *
+ * The raw `realpath` syscall lives on the `FileSystemProvider`
+ * (`@hydranium/core/node`'s `DefaultFileSystemProvider`), not here — this policy
+ * is pure routing over that seam, so it carries no `node:fs` import and is
+ * browser-neutral. Both methods follow the *same* policy: `canonicalUri` falls
+ * back to the syntactic form when the path can't be resolved (optimistic — a
+ * file that appears later canonicalises to the same key once present), while
+ * `loadUri` returns `undefined` for an absent path (honest about existence, so a
+ * caller about to read the filesystem skips it).
+ *
+ * If the bound provider has no `realpath` (in-memory / browser / empty),
+ * both methods degrade to {@link DefaultDocumentUriPolicy} automatically — the
+ * `loadUri` ternary tests the *method's presence*, not its return, so the
+ * existence signal is preserved: `loadUri` returns `undefined` only when
+ * `realpath` is present and reports the path absent.
+ */
+export class RealpathDocumentUriPolicy extends DefaultDocumentUriPolicy {
+   protected readonly fs: RealpathCapableFileSystem;
+
+   constructor(services: ServerSharedServicesMinimal) {
+      super();
+      this.fs = services.workspace.FileSystemProvider;
+   }
+
+   override canonicalUri(uri: URI | string): CanonicalUri {
+      const parsed = UriUtils.toUri(uri);
+      const real = parsed && this.fs.realpath?.(parsed);
+      // Mint via `asCanonicalUri` once normalised; absent / unresolvable paths
+      // (and a provider without `realpath`) fall back to the syntactic form.
+      return real ? asCanonicalUri(UriUtils.normalize(real)) : super.canonicalUri(uri);
+   }
+
+   override loadUri(uri: URI | string): URI | undefined {
+      if (!this.fs.realpath) {
+         return super.loadUri(uri);
+      }
+      const parsed = UriUtils.toUri(uri);
+      // `realpath` present: a real path resolves, an absent one returns
+      // `undefined` (the skip signal). A non-parseable URI has no load target.
+      return parsed ? this.fs.realpath(parsed) : parsed;
+   }
+}

package/src/langium/workspace/file-system-provider.ts

@@ -0,0 +1,52 @@
+/********************************************************************************
+ * 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 Tracer } from '@hydranium/protocol';
+import { EmptyFileSystemProvider } from '@hydranium/langium';
+import type { URI } from '@hydranium/langium';
+import { type WritableFileSystemProvider } from '../../documents/ast-document-manager.js';
+import { type LogNameOptions } from '../diagnostics/logger.js';
+import { type ServerSharedServicesMinimal } from '../shared-services.js';
+import { serveVirtualDocument } from './virtual-document.js';
+
+/**
+ * Empty-filesystem default {@link WritableFileSystemProvider}. For
+ * in-memory / browser / test / CLI hosts that don't have a real filesystem.
+ * All writes are no-ops. This is the portable `.`-entry default; the
+ * Node-backed `DefaultFileSystemProvider`
+ * lives in `@hydranium/core/node` (it pulls `node:fs`).
+ */
+export class DefaultEmptyFileSystemProvider extends EmptyFileSystemProvider implements WritableFileSystemProvider {
+   protected readonly tracer: Tracer;
+
+   constructor(
+      protected readonly services: ServerSharedServicesMinimal,
+      options: LogNameOptions = {}
+   ) {
+      super();
+      this.tracer = services.Tracer.for(options.logName ?? this.constructor.name).trace('instantiated');
+   }
+
+   async writeFile(_uri: URI, _content: string): Promise<void> {
+      // no-op
+   }
+
+   // Serve virtual documents from the registered document (there is no disk to
+   // read); delegate everything else to the empty base (which throws). The
+   // base declares these param-less, so the param is optional here.
+   override readFile(uri?: URI): Promise<string> {
+      const served = uri !== undefined ? serveVirtualDocument(this.services, uri) : undefined;
+      return served !== undefined ? Promise.resolve(served) : super.readFile();
+   }
+
+   override readFileSync(uri?: URI): string {
+      const served = uri !== undefined ? serveVirtualDocument(this.services, uri) : undefined;
+      return served !== undefined ? served : super.readFileSync();
+   }
+}

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

@@ -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
+ ********************************************************************************/
+
+import {
+   type AstNode,
+   AstUtils,
+   DefaultLangiumDocumentFactory,
+   type LangiumDocument,
+   type ParseResult,
+   type URI
+} from '@hydranium/langium';
+import { type Serializer } from '../serialization/serializer.js';
+
+/** Structural view of the per-language serializer slot on the resolved services. */
+interface WithSerializer {
+   serializer?: { Serializer?: Serializer };
+}
+
+/**
+ * Framework `LangiumDocumentFactory` that fills in the one thing Langium
+ * leaves empty for a code-built document: its text.
+ *
+ * Langium's `fromModel` produces a document with no text (Langium core has no
+ * generic serializer), so a virtual document built from a model cannot be
+ * re-read. The framework *does* have a per-language `Serializer`, so this
+ * override serializes the model once at creation and retains the result as the
+ * document's text — while keeping the ORIGINAL model object as the AST, so node
+ * identity survives: adopters holding references to their stdlib nodes, and the
+ * scope descriptions pointing at them, stay valid. A `fromString` document
+ * already carries its source, so only `fromModel` needs help.
+ *
+ * Degrades to Langium's text-less `fromModel` when no serializer is bound for
+ * the URI's language (the serializer throws or is absent) — the document still
+ * works; only a re-read of it would yield empty text, which never happens for a
+ * build-once virtual document.
+ *
+ * Also links the model's container properties (`$container` /
+ * `$containerProperty` / `$containerIndex`), which Langium's parser sets via
+ * `linkContentToContainer` but `fromModel` skips. Without them the
+ * `AstNodeLocator` can't compute node paths, so indexing the document — the
+ * point of contributing it as an additional/virtual document — yields broken
+ * paths and cross-references into it fail to resolve. Linking is in place, so
+ * node identity is preserved.
+ */
+export class HydraniumLangiumDocumentFactory extends DefaultLangiumDocumentFactory {
+   override fromModel<T extends AstNode = AstNode>(model: T, uri: URI): LangiumDocument<T> {
+      // Make the code-built AST as structurally complete as a parsed one — the
+      // parser links containers, `fromModel` does not. In place (identity kept).
+      AstUtils.linkContentToContainer(model, { deep: true });
+      const text = this.serializeModel(model, uri);
+      if (text === undefined) {
+         return super.fromModel(model, uri);
+      }
+      const parseResult: ParseResult<T> = { value: model, parserErrors: [], lexerErrors: [] };
+      return this.createLangiumDocument<T>(parseResult, uri, undefined, text);
+   }
+
+   /**
+    * Serialize `model` via the per-language serializer, or `undefined` if none
+    * is bound, it fails, or it is async — `fromModel` is synchronous, so an
+    * async serializer degrades to a text-less document rather than blocking.
+    */
+   protected serializeModel(model: AstNode, uri: URI): string | undefined {
+      try {
+         const services = this.serviceRegistry.getServices(uri) as WithSerializer;
+         const serialized = services.serializer?.Serializer?.serializeAst(model);
+         return typeof serialized === 'string' ? serialized : undefined;
+      } catch {
+         return undefined;
+      }
+   }
+}

package/src/langium/workspace/hydranium-workspace-lock.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 { DefaultWorkspaceLock, type MaybePromise } from '@hydranium/langium';
+import { type CancellationToken } from 'vscode-languageserver-protocol';
+import { runInWriteLockScope } from './write-lock-scope.js';
+
+/**
+ * Langium's {@link DefaultWorkspaceLock} with the write action marked as a
+ * write-lock scope, so anything it reaches can be asked whether the lock is
+ * already held (see `isInsideWriteLock`).
+ *
+ * The wrapping has to live HERE rather than at the facade's own `write` call
+ * sites, because the holders worth detecting are mostly not the facade: Langium's
+ * `DefaultWorkspaceManager.initialized` and `DefaultDocumentUpdateHandler` both
+ * take this lock, and the reentrant shape that matters is an integrity rule or
+ * build-phase pass running *inside* one of those builds and writing back through
+ * the facade. Marking the scope at the lock covers every holder, present and
+ * future, including an adopter's own `write` calls.
+ *
+ * `read` is deliberately NOT marked. Read actions do not cancel a running holder,
+ * so reaching the facade from inside one is not the hazard, and marking them
+ * would turn ordinary read-then-write sequences into false positives.
+ */
+export class HydraniumWorkspaceLock extends DefaultWorkspaceLock {
+   override write(action: (token: CancellationToken) => MaybePromise<void>): Promise<void> {
+      return super.write(token => runInWriteLockScope(() => action(token)));
+   }
+}