@hydranium/core 1.0.0-next.23 → 1.0.0-next.25

package/src/langium/document-builder/document-builder.ts

@@ -9,6 +9,7 @@
 
 import { type Clock, type LogThreshold, type MaybeObservableValue, ObservableValue, type Tracer } from '@hydranium/protocol';
 import {
+   type AstNode,
    type BuildOptions,
    DefaultDocumentBuilder,
    type DocumentPhaseListener,
@@ -26,6 +27,7 @@ import { CST_REHYDRATION_RESET_STATE, isCstShed } from '../residency/cst-residen
 import { type ExtendedServiceRegistry } from '../service-registry.js';
 import { type ServerSharedServicesMinimal } from '../shared-services.js';
 import { type DocumentUriPolicy } from '../workspace/document-uri-policy.js';
+import { BuildSession, type BuildSessionContext } from './build-session.js';
 import { type LabeledPhaseListener, labelPhaseListener } from './labeled-phase-listener.js';
 
 /** Document states a phase-reached line is emitted for by default — every built phase. */
@@ -78,6 +80,18 @@ export interface DocumentBuilderOptions extends LogNameOptions {
     * logged. Default: `25`. Read per phase; accepts a {@link MaybeObservableValue}.
     */
    readonly slowBuildMs?: MaybeObservableValue<number>;
+   /**
+    * Build duration at or above which a build's phase-reached and slow-listener
+    * lines are emitted; they are held for the duration of the build and dropped
+    * when it finishes faster. Default `0` — no buffering, every line emitted as
+    * it is produced, which is the only setting that keeps lines interleaved with
+    * the rest of the log in real time.
+    *
+    * Set it to make a fast rebuild log nothing but its one build line. The
+    * decision needs the build's TOTAL duration, so it cannot be made by any
+    * per-line hook. Read once per build; accepts a {@link MaybeObservableValue}.
+    */
+   readonly phaseDetailMs?: MaybeObservableValue<number>;
    /**
     * Refresh cross-document `ComputedScopes` derivations when a referencing
     * document is cascade-rebuilt (see
@@ -106,14 +120,21 @@ export interface DocumentBuilderOptions extends LogNameOptions {
  *   {@link reparseAndRelink} — for a build-phase listener that mutated a
  *   document's AST and must reconcile it within the same build.
  * - **Diagnostic dedupe** at `Validated` ({@link dedupeDiagnostics}).
+ * - **Build sessions** ({@link BuildSession}): each `update` / `build` call is
+ *   one correlated unit carrying an id, a trigger label, a start time and
+ *   cancellation lineage, so every line of a rebuild reads as belonging to it
+ *   and a preempted build is distinguishable from the winner.
  * - **Logging instrumentation** (default on, opt-out via `logLevel: 'off'`):
- *   phase-reached lines, slow-listener breakdowns on `notifyDocumentPhase`,
- *   and slow-build-phase totals on `notifyBuildPhase`.
+ *   a per-build line, phase-reached lines, slow-listener breakdowns on
+ *   `notifyDocumentPhase`, and slow-build-phase totals on `notifyBuildPhase`.
  *
  * Adopters extend this class — the configuration knobs cover what most
  * adopters need; the `format*Line` methods, `formatUri`, and
  * `collectDeletedURIs` are protected so subclasses can customise wording or
- * domain-aware cascades without re-implementing surrounding logic.
+ * domain-aware cascades without re-implementing surrounding logic. An adopter
+ * with build-scoped state of its own subclasses {@link BuildSession} and
+ * overrides {@link createBuildSession}, which puts that state under the same
+ * preemption-correct teardown rather than a reimplementation of it.
  */
 export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
    protected readonly tracer: Tracer;
@@ -127,6 +148,8 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
    protected readonly slowListenerMs: ObservableValue<number>;
    /** Live slow-build-phase-total threshold; read `.value` per phase. */
    protected readonly slowBuildMs: ObservableValue<number>;
+   /** Live phase-detail buffering threshold; read `.value` once per build, onto the session. */
+   protected readonly phaseDetailMs: ObservableValue<number>;
    protected readonly uriPolicy: DocumentUriPolicy;
    protected readonly clock: Clock;
    /** Narrower handle on the same registry as the inherited `serviceRegistry`, for {@link ExtendedServiceRegistry.registrations}. */
@@ -139,6 +162,22 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
    protected readonly refreshCrossDocumentComputedScopes: boolean;
    /** LSP event name (e.g. `'didChangeWatchedFiles'`) staged for the next `update()` call. */
    protected pendingUpdateReason?: string;
+   /**
+    * The build currently in progress, or `undefined` between builds.
+    *
+    * A subclass carrying its own build-scoped state returns a {@link BuildSession}
+    * subclass from {@link createBuildSession} and narrows this with a typeguard
+    * where it reads that state — rather than redeclaring the field, whose
+    * initialiser would run after `super()` and clear a session opened during
+    * construction.
+    */
+   protected activeSession?: BuildSession;
+   /**
+    * `traceId` of the last build that ended in cancellation, for the successor's
+    * "cancels #N" tag. Held here rather than on a session because the session
+    * that carries it is already gone by the time its successor is opened.
+    */
+   protected lastCancelledTraceId?: number;
 
    constructor(services: ServerSharedServicesMinimal, options: DocumentBuilderOptions = {}) {
       super(services);
@@ -151,6 +190,7 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
       this.slowPhaseMs = ObservableValue.from(options.slowPhaseMs ?? 25);
       this.slowListenerMs = ObservableValue.from(options.slowListenerMs ?? 5);
       this.slowBuildMs = ObservableValue.from(options.slowBuildMs ?? 25);
+      this.phaseDetailMs = ObservableValue.from(options.phaseDetailMs ?? 0);
       this.refreshCrossDocumentComputedScopes = options.refreshCrossDocumentComputedScopes ?? false;
       if (this.logLevel !== 'off') {
          this.registerPhaseListeners();
@@ -193,7 +233,16 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
       const doc = this.langiumDocuments.getDocument(UriUtils.toUri(this.uriPolicy.canonicalUri(uri)));
       const docState = doc ? DocumentState[doc.state] : 'unknown (document not loaded)';
       const lastPhase = this.lastPhaseMs > 0 ? `${Math.round(performance.now() - this.lastPhaseMs)}ms ago` : 'no phase observed';
-      return `current state: '${docState}', last phase: ${lastPhase}`;
+      return `current state: '${docState}', last phase: ${lastPhase}, active build: ${this.formatSession(this.activeSession)}`;
+   }
+
+   /** Render a session for a status line. `undefined` — no build in progress — reads as `none`. */
+   protected formatSession(session: BuildSession | undefined): string {
+      if (!session) {
+         return 'none';
+      }
+      const id = session.traceId !== undefined ? `#${session.traceId}` : 'untimed';
+      return `${id} (${session.trigger}, ${Math.round(performance.now() - session.startMs)}ms in)`;
    }
 
    // ============================================================
@@ -409,7 +458,35 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
       this.ensureLanguageFileExtensions();
       const changedURIs = changed.flatMap(uri => this.flattenAndAdaptURI(uri));
       const deletedURIs = deleted.flatMap(uri => this.collectDeletedURIs(uri));
-      return super.update(changedURIs, deletedURIs, cancelToken);
+      return this.runInSession(
+         {
+            kind: 'update',
+            trigger: this.buildTriggerLabel(changedURIs, deletedURIs),
+            triggerCountsDocs: changedURIs.length + deletedURIs.length !== 1,
+            changed: changedURIs,
+            deleted: deletedURIs
+         },
+         this.rebuildLabel(changedURIs, deletedURIs),
+         () => super.update(changedURIs, deletedURIs, cancelToken)
+      );
+   }
+
+   /**
+    * The workspace-initialization entry point, bracketed by a session like
+    * {@link update}. Langium's `update` reaches `buildDocuments` directly rather
+    * than through here, so the two never nest.
+    */
+   override build<T extends AstNode>(
+      documents: Array<LangiumDocument<T>>,
+      options?: BuildOptions,
+      cancelToken?: CancellationToken
+   ): Promise<void> {
+      const uris = documents.map(document => document.uri);
+      return this.runInSession(
+         { kind: 'build', trigger: `${documents.length} docs`, triggerCountsDocs: true, changed: uris, deleted: [] },
+         `Build documents (${documents.length} docs)`,
+         () => super.build(documents, options, cancelToken)
+      );
    }
 
    /**
@@ -615,6 +692,149 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
       ];
    }
 
+   // ============================================================
+   // Build sessions — one rebuild as a correlated unit
+   // ============================================================
+
+   /**
+    * Open a session, run `body` inside it, and close it — the bracket every
+    * line of a rebuild is emitted within.
+    *
+    * The session is installed **synchronously**, before the timed body runs, so
+    * that state a subclass computed in {@link createBuildSession} is already
+    * readable by the time Langium's `update` consults `shouldRelink`.
+    *
+    * Teardown is preemption-correct, which is the reason this is framework code
+    * rather than a recipe. Langium's write mutex cancels an in-flight build when
+    * a later one arrives, so two sessions overlap: the successor installs itself
+    * as {@link activeSession} while the predecessor is still unwinding, and the
+    * predecessor's `finally` runs LAST. Clearing unconditionally there would
+    * discard the winner's state mid-build. Only the session that is still
+    * current clears — and the check is reference equality on the session object,
+    * not on {@link BuildSession.traceId}, which is `undefined` for every build
+    * whenever the timing level is suppressed and would compare equal to itself
+    * across two different builds.
+    *
+    * Re-entrancy is not hypothetical even without an adopter: {@link
+    * requeueOrphaned} calls `update` from inside a wait, while a build may be
+    * running.
+    */
+   protected runInSession(context: BuildSessionContext, label: string, body: () => Promise<void>): Promise<void> {
+      // Read before installing the new session: the id being superseded belongs
+      // to the OUTGOING build, or — when the previous one already finished
+      // cancelled — to the id it parked for its successor.
+      const supersededId = this.activeSession?.traceId ?? this.lastCancelledTraceId;
+      this.lastCancelledTraceId = undefined;
+      const reason = this.pendingUpdateReason;
+      this.pendingUpdateReason = undefined;
+      const tags: string[] = [];
+      if (reason) {
+         tags.push(`event: ${reason}`);
+      }
+      if (supersededId !== undefined) {
+         tags.push(`cancels #${supersededId}`);
+      }
+
+      const session = this.createBuildSession(context);
+      this.activeSession = session;
+      // A phase's "since previous phase" must measure from the build's start,
+      // not from whenever the last build's final phase happened to land.
+      this.lastPhaseMs = session.startMs;
+      return this.tracer.time(
+         label,
+         async () => {
+            try {
+               await body();
+            } catch (err: unknown) {
+               if (isOperationCancelled(err)) {
+                  session.cancelled = true;
+               }
+               throw err;
+            } finally {
+               this.endSession(session);
+            }
+         },
+         this.logLevel,
+         {
+            logAfterMs: 0,
+            forceMemoryAboveMs: session.buffers ? session.detailThresholdMs : undefined,
+            captureId: id => {
+               session.traceId = id;
+            },
+            tags
+         }
+      );
+   }
+
+   /**
+    * Construct the session for one build. Override to return a
+    * {@link BuildSession} subclass carrying adopter build-scoped state — it is
+    * called before the build body, so anything derived here is readable
+    * throughout it.
+    */
+   protected createBuildSession(context: BuildSessionContext): BuildSession {
+      return new BuildSession(performance.now(), context.trigger, context.triggerCountsDocs, this.phaseDetailMs.value);
+   }
+
+   /**
+    * Close `session`: flush what it buffered, then release it if it is still the
+    * current one (see {@link runInSession} on why that check is conditional).
+    * The flush is unconditional — a preempted build's lines still describe work
+    * that happened.
+    */
+   protected endSession(session: BuildSession): void {
+      this.flushSession(session);
+      if (this.activeSession === session) {
+         this.activeSession = undefined;
+         if (session.cancelled) {
+            this.lastCancelledTraceId = session.traceId;
+         }
+      }
+   }
+
+   /**
+    * Emit the lines `session` held back, if it ran long enough to be worth the
+    * detail; drop them otherwise. Emits through {@link emit} rather than
+    * {@link log}, which would route them straight back into the buffer.
+    */
+   protected flushSession(session: BuildSession): void {
+      const elapsedMs = performance.now() - session.startMs;
+      if (elapsedMs >= session.detailThresholdMs) {
+         for (const line of session.bufferedLines) {
+            this.emit(line);
+         }
+      }
+      session.bufferedLines.length = 0;
+   }
+
+   /** Label for the build's own log line. Override to customise wording. */
+   protected rebuildLabel(changed: URI[], deleted: URI[]): string {
+      if (changed.length === 0 && deleted.length === 0) {
+         return 'Rebuild documents (nothing to do)';
+      }
+      if (changed.length === 1 && deleted.length === 0) {
+         return `Rebuild document: ${this.formatUri(changed[0])}`;
+      }
+      if (changed.length === 0 && deleted.length === 1) {
+         return `Rebuild after delete: ${this.formatUri(deleted[0])}`;
+      }
+      return `Rebuild documents (${changed.length} changed, ${deleted.length} deleted)`;
+   }
+
+   /** Short description of what triggered the build, repeated on every phase line. Override to customise wording. */
+   protected buildTriggerLabel(changed: URI[], deleted: URI[]): string {
+      if (changed.length === 0 && deleted.length === 0) {
+         return 'nothing';
+      }
+      if (changed.length === 1 && deleted.length === 0) {
+         return this.formatUri(changed[0]);
+      }
+      if (changed.length === 0 && deleted.length === 1) {
+         return `deleted ${this.formatUri(deleted[0])}`;
+      }
+      return `${changed.length} changed, ${deleted.length} deleted`;
+   }
+
    // ============================================================
    // Logging — phase-reached listeners
    // ============================================================
@@ -630,13 +850,35 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
       const now = performance.now();
       const elapsedMs = Math.round(now - this.lastPhaseMs);
       this.lastPhaseMs = now;
+      // Counted before the line is formatted, so the formatter stays a pure
+      // function of state a caller can also set up in a test.
+      if (this.activeSession) {
+         this.activeSession.phasesLogged++;
+      }
       this.log(this.phaseReachedLine(state, documents, elapsedMs));
    }
 
-   /** Format the phase-reached log line. Override to customise wording. */
+   /**
+    * Format the phase-reached log line. Override to customise wording.
+    *
+    * Within a session the line names what triggered the build, so a phase read
+    * in isolation still says which rebuild it belongs to. `elapsedMs` is ignored
+    * for the FIRST phase of a session: it measures from the previous build's
+    * last phase, an idle gap that says nothing about this build.
+    */
    protected phaseReachedLine(state: DocumentState, documents: LangiumDocument[], elapsedMs: number): string {
-      const docInfo = documents.length === 1 ? this.formatUri(documents[0].uri) : `${documents.length} docs`;
-      return `Reached phase '${DocumentState[state]}' [${docInfo}, ${elapsedMs}ms since previous phase]`;
+      const session = this.activeSession;
+      let docInfo: string;
+      if (session) {
+         docInfo = session.triggerCountsDocs ? `building ${session.trigger}` : `building ${session.trigger}, ${documents.length} docs`;
+      } else {
+         docInfo = documents.length === 1 ? this.formatUri(documents[0].uri) : `${documents.length} docs`;
+      }
+      const elapsedInfo =
+         session && session.phasesLogged <= 1
+            ? `${Math.round(performance.now() - session.startMs)}ms since build start`
+            : `${elapsedMs}ms since previous phase`;
+      return `Reached phase '${DocumentState[state]}' [${docInfo}, ${elapsedInfo}]`;
    }
 
    // ============================================================
@@ -832,8 +1074,26 @@ export class HydraniumDocumentBuilder extends DefaultDocumentBuilder {
    // Internal helpers
    // ============================================================
 
-   /** Dispatch a log line at the configured log level; a no-op when `logLevel === 'off'`. */
+   /**
+    * Dispatch a log line at the configured log level; a no-op when `logLevel ===
+    * 'off'`.
+    *
+    * Held on the active session when it buffers, so the "was this build worth a
+    * per-phase breakdown" decision — which needs the build's total duration, and
+    * so cannot be taken by anything that runs while the lines are produced — is
+    * deferred to {@link flushSession}.
+    */
    protected log(message: string): void {
+      const session = this.activeSession;
+      if (session?.buffers) {
+         session.bufferedLines.push(message);
+         return;
+      }
+      this.emit(message);
+   }
+
+   /** Write a line out, bypassing session buffering. The single sink every framework log line reaches. */
+   protected emit(message: string): void {
       this.tracer.logAt(this.logLevel, message);
    }
 }

package/src/langium/document-builder/index.ts

@@ -8,5 +8,6 @@
  ********************************************************************************/
 
 export * from './build-pipeline-integration.js';
+export * from './build-session.js';
 export * from './document-builder.js';
 export * from './labeled-phase-listener.js';

package/src/langium/module.ts

@@ -26,6 +26,7 @@ import { HydraniumIndexManager } from './workspace/index-manager.js';
 import { HydraniumWorkspaceManager } from './workspace/hydranium-workspace-manager.js';
 import { HydraniumWorkspaceLock } from './workspace/hydranium-workspace-lock.js';
 import { HydraniumLangiumDocumentFactory } from './workspace/hydranium-langium-document-factory.js';
+import { type HydraniumDocumentRegistry, HydraniumLangiumDocuments } from './workspace/langium-documents.js';
 import { type AdditionalDocumentContribution } from './workspace/additional-document-contribution.js';
 import { DefaultDocumentUriPolicy, type DocumentUriPolicy } from './workspace/document-uri-policy.js';
 import { HydraniumTextDocuments } from '../documents/hydranium-text-documents.js';
@@ -113,6 +114,12 @@ export interface ServerAddedSharedServices<TProject extends Project = Project> {
    workspace: {
       /* override */ TextDocuments: HydraniumTextDocuments<TextDocument>;
       /* override */ WorkspaceManager: HydraniumWorkspaceManager;
+      /**
+       * Narrow Langium's registry slot to the framework surface, which adds
+       * `createEmptyDocument` — reachable only through this narrowing, and
+       * wanted by a scope provider querying a URI before the file exists.
+       */
+      /* override */ LangiumDocuments: HydraniumDocumentRegistry;
       /**
        * Narrow Langium's `IndexManager` slot to the framework subclass, which
        * layers an `elementsByName` map over Langium's index and exposes
@@ -392,6 +399,10 @@ export function createServerSharedModule(
          // document retains serialized text via the per-language Serializer,
          // making it re-read-safe through the virtual-aware FileSystemProvider.
          LangiumDocumentFactory: services => new HydraniumLangiumDocumentFactory(services),
+         // Langium's default routes through no identity seam and treats every
+         // failed load alike, so leaving this unbound opts a server out of both
+         // with nothing to signal it.
+         LangiumDocuments: services => new HydraniumLangiumDocuments(services),
          DocumentBuilder: services => new HydraniumDocumentBuilder(services),
          // The write-lock scope this marks is inert unless a host installs a
          // scope tracker — `@hydranium/core/node` does.

package/src/langium/residency/cst-residency-service.ts

@@ -225,7 +225,7 @@ function rehydrateCst(document: LangiumDocument, factory: LangiumDocumentFactory
  * demand by the identity-preserving graft of {@link rehydrateNode} /
  * {@link rehydrate}, driven transparently from the framework
  * `NameProvider.getNameNode` chokepoint, the comment provider, and
- * `AbstractHydraniumLangiumDocuments.getOrCreateDocument`.
+ * `HydraniumLangiumDocuments.getOrCreateDocument`.
  */
 export class CstResidencyService {
    protected readonly strategy: CstResidencyStrategy;

package/src/langium/shared-services.ts

@@ -11,6 +11,7 @@ import type { Clock, Logger, Project, Tracer } from '@hydranium/protocol';
 import type { LangiumSharedCoreServices } from '@hydranium/langium';
 import type { SelfSaveRegistry } from '../documents/self-save-registry.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';
 import type { CstResidencyService } from './residency/cst-residency-service.js';
 import type { BuildPipelineIntegration } from './document-builder/build-pipeline-integration.js';
@@ -75,6 +76,11 @@ export interface ServerSharedServicesMinimal<TProject extends Project = Project>
       // framework always binds, so `wsRelativePath` and the folder-walk are
       // reachable from the minimal surface without a cast.
       WorkspaceManager: HydraniumWorkspaceManager;
+      // Same, for the registry: the framework always binds
+      // `HydraniumLangiumDocuments`, and `createEmptyDocument` is reachable
+      // only through this narrowing — a scope provider querying a URI before
+      // the file exists is the caller that needs it.
+      /* override */ LangiumDocuments: HydraniumDocumentRegistry;
       ProjectManager: ProjectManager<TProject>;
       SelfSaveRegistry: SelfSaveRegistry;
       BuildPipelineIntegration: BuildPipelineIntegration;

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

@@ -26,12 +26,25 @@ import { isSyntheticNode } from '../workspace/synthetic.js';
 import { isVirtualUri } from '../workspace/virtual-document.js';
 
 /**
- * Diagnostic shape produced by {@link HydraniumDocumentValidator}: an LSP
- * {@link Diagnostic} extended with the protocol-level `element` path and
- * optional `property` name from {@link TransferDiagnostic}.
+ * Diagnostic read off a `LangiumDocument`: an LSP {@link Diagnostic} that MAY
+ * carry the protocol-level `element` path and `property` name from
+ * {@link TransferDiagnostic}.
+ *
+ * `element` is optional because a document's diagnostics do not all come from
+ * this validator. {@link HydraniumDocumentValidator.toDiagnostic} always sets
+ * one, but Langium pushes lexer and parser errors straight onto the document
+ * without routing them through it, so a document that fails to parse carries
+ * diagnostics with no path at all. Treat it as absent, not empty.
+ *
+ * Narrowing `LangiumDocument.diagnostics` to this type instead is unavailable:
+ * declaration merging may add a member but not retype one, and augmenting the
+ * LSP `Diagnostic` reaches only one of the two declaration files its package
+ * ships, since the `exports` map splits `import` from `default` with no `types`
+ * condition. Consumers therefore cast at the read, and the cast is sound only
+ * because this field is optional.
  */
 export interface TransferLspDiagnostic extends Diagnostic {
-   element: string;
+   element?: string;
    property?: string;
 }
 

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

@@ -105,10 +105,9 @@ export class DefaultDocumentUriPolicy implements DocumentUriPolicy {
    /**
     * 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.
+    * therefore reaches the filesystem and throws, which reports the miss with
+    * the reason the read failed. Under a policy that CAN check, the miss is
+    * caught earlier and reported without one.
     */
    loadUri(uri: URI | string): URI | undefined {
       return UriUtils.toUri(uri);

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

@@ -7,14 +7,24 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { type Tracer } from '@hydranium/protocol';
-import { type AstNode, DefaultLangiumDocuments, type LangiumDocument, type URI } from '@hydranium/langium';
+import { type AstNode, DefaultLangiumDocuments, type LangiumDocument, type LangiumDocuments, type URI } from '@hydranium/langium';
 import { type ServerSharedServicesMinimal } from '../shared-services.js';
 import { type DocumentUriPolicy } from './document-uri-policy.js';
 
 /**
- * Default `LangiumDocuments` for `@hydranium/core` consumers. Layers two
- * extensions on top of Langium's {@link DefaultLangiumDocuments}:
+ * The registry surface the framework adds on top of Langium's
+ * {@link LangiumDocuments}. Declared separately from the implementing class so
+ * the shared-services slot can narrow to it: the class takes the services tree
+ * as its constructor parameter, so naming the CLASS there would make that type
+ * depend on itself.
+ */
+export interface HydraniumDocumentRegistry extends LangiumDocuments {
+   createEmptyDocument(uri: URI): LangiumDocument<AstNode>;
+}
+
+/**
+ * Default `LangiumDocuments` for `@hydranium/core` consumers, extending
+ * Langium's {@link DefaultLangiumDocuments} with:
  *
  * 1. **Identity via the {@link DocumentUriPolicy} seam.**
  *    `getOrCreateDocument` resolves the requested URI through the seam — the
@@ -24,31 +34,52 @@ import { type DocumentUriPolicy } from './document-uri-policy.js';
  *    `LangiumDocuments` override. The default resolves to the URI unchanged
  *    (`DefaultDocumentUriPolicy`), matching Langium's own keying.
  *
- * 2. **`createEmptyDocument(uri)` — synchronous** factory for a transient
- *    document with no loadable on-disk content. `getOrCreateDocument` falls
- *    back to it when the seam reports no loadable URI, or when `super` cannot
- *    load it, so callers always receive a document. Abstract because the
- *    parse-result root is grammar-specific (each grammar returns its own
- *    root node type). The fallback document is deliberately
- *    **not** registered: a transient placeholder must not mask the real
- *    document once it appears.
+ * 2. **A load that finds nothing rejects**, rather than answering with a
+ *    transient empty document. An empty AST validates clean, so a placeholder
+ *    hands the caller something that silently is not the file, and a caller
+ *    that wants a document for a URI with no content on disk cannot use one
+ *    anyway: it is unregistered, so no build, index or save can see it, and
+ *    `LangiumDocumentFactory.update` reads from disk. Content that legitimately
+ *    lives outside the filesystem belongs in a virtual document, which carries
+ *    real source text.
  */
-export abstract class AbstractHydraniumLangiumDocuments extends DefaultLangiumDocuments {
+export class HydraniumLangiumDocuments extends DefaultLangiumDocuments implements HydraniumDocumentRegistry {
    /** Document-identity seam, shared with the text store, event filters, and builder. */
    protected readonly uriPolicy: DocumentUriPolicy;
-   protected readonly tracer: Tracer;
 
    constructor(protected override readonly services: ServerSharedServicesMinimal) {
       super(services);
       this.uriPolicy = services.workspace.DocumentUriPolicy;
-      this.tracer = services.Tracer.for('LangiumDocuments');
    }
 
    /**
-    * Build a transient empty document for `uri`. Implemented by consumers
-    * because the parse-result root is grammar-specific.
+    * Build a transient document for `uri` by parsing empty text with the
+    * grammar `uri` routes to, so the root is that language's entry type with
+    * every containment list initialised.
+    *
+    * For callers that need a document at a URI with no content on disk — the
+    * scope provider querying before a file exists is the case it was added for.
+    * `getOrCreateDocument` deliberately does NOT fall back to this: fabricating
+    * a document behind a caller that asked to LOAD one hands back something
+    * that silently is not the file, whereas calling this is a caller saying it
+    * wants a stand-in.
+    *
+    * The result is not registered, so nothing downstream can see it, and
+    * `LangiumDocumentFactory.update` would read from disk. It is a probe, not a
+    * document under construction; content that must survive belongs in a
+    * virtual document, which carries real source text.
+    *
+    * Building the root by hand instead needs the entry type name and a cast
+    * past the generated types, and leaves those lists `undefined`. A grammar
+    * whose entry rule opens with mandatory syntax yields a parse error here,
+    * and it is kept: `AstReflection.isComplete` is `false` for such a root
+    * however it is built, so the error states the same thing.
     */
-   abstract createEmptyDocument(uri: URI): LangiumDocument<AstNode>;
+   createEmptyDocument(uri: URI): LangiumDocument<AstNode> {
+      // The two-argument overload is synchronous; passing a cancellation token
+      // selects the promise-returning one, which this contract cannot await.
+      return this.langiumDocumentFactory.fromString('', uri);
+   }
 
    override async getOrCreateDocument(uri: URI): Promise<LangiumDocument<AstNode>> {
       const resolved = this.uriPolicy.loadUri(uri);
@@ -68,27 +99,18 @@ export abstract class AbstractHydraniumLangiumDocuments extends DefaultLangiumDo
             return await super.getOrCreateDocument(resolved);
          } catch (error: unknown) {
             // Load lost a race with a concurrent create — return that document.
+            // Checked before propagating, so a race is not reported as a
+            // missing file; cancellation carries no document and falls through.
             const reentrant = this.getDocument(resolved);
             if (reentrant) {
                this.services.workspace.CstResidencyService.rehydrate(reentrant);
                return reentrant;
             }
-            // No concurrent document, so the load genuinely failed. The fallback
-            // below still runs, because the file-not-found case is the ordinary
-            // one here and no provider-independent way to recognise it exists:
-            // Node's provider throws `ENOENT`, the in-memory one a bare `Error`,
-            // and the provider is a seam an adopter rebinds. Discriminating on
-            // message text across that seam would be a worse defect than the
-            // one it fixes. So the failure is TRACED rather than propagated —
-            // an unreadable-but-present file still degrades to an empty
-            // document, but it stops doing so silently.
-            this.tracer
-               .with(resolved.toString())
-               .debug(`Load failed, falling back to an empty document: ${error instanceof Error ? error.message : String(error)}`);
+            throw error;
          }
       }
-      // No loadable content (missing / synthetic / not yet written): a transient
-      // empty placeholder keyed canonically — not registered (see the class doc).
-      return this.createEmptyDocument(resolved ?? uri);
+      // The seam reports no loadable content, so there is nothing to read and
+      // no error from a read to carry.
+      throw new Error(`No loadable content for ${uri.toString()}`);
    }
 }