@hydranium/data-server 1.0.0-next.10 → 1.0.0-next.104

package/lib/testing/data-server-harness.js

@@ -24,11 +24,11 @@ export function makeDataServerHarness(options) {
     const pair = makeDuplexConnectionPair();
     const server = options.server(pair.left);
     // The capture half is the shared client double, not a local copy: the same
-    // recording semantics (all three channels, an override replacing rather than
+    // recording semantics (every channel, an override replacing rather than
     // supplementing) then hold for a client-side suite that stands the double up
     // without a server, so an assertion learnt against one reads the same in the
     // other.
-    const { client: localClient, updates: events, saves, projectsChanges } = makeCapturingDataClient(options.client);
+    const { client: localClient, updates: events, saves, deletions, builds, projectsChanges } = makeCapturingDataClient(options.client);
     const proxy = createRpcProxy(pair.right, {
         methodNamespace: options.methodNamespace ?? DATA_SERVER_WIRE_PREFIX,
         localTarget: localClient,
@@ -40,6 +40,8 @@ export function makeDataServerHarness(options) {
         pair,
         events,
         saves,
+        deletions,
+        builds,
         projectsChanges,
         dispose: () => pair.dispose()
     };

package/lib/testing/data-server-harness.js.map

@@ -1 +1 @@
-{"version":3,"file":"data-server-harness.js","sourceRoot":"","sources":["../../src/testing/data-server-harness.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,cAAc,EAA+D,MAAM,qBAAqB,CAAC;AAClH,OAAO,EACJ,4BAA4B,EAC5B,uBAAuB,EAMzB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAgB,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AACpF,OAAO,EAAE,wBAAwB,EAA6B,MAAM,kCAAkC,CAAC;AA2EvG;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAMlC,OAAgF;IAEhF,MAAM,IAAI,GAAG,wBAAwB,EAAE,CAAC;IACxC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEzC,2EAA2E;IAC3E,6EAA6E;IAC7E,6EAA6E;IAC7E,6EAA6E;IAC7E,SAAS;IACT,MAAM,EACH,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,MAAM,EACf,KAAK,EACL,eAAe,EACjB,GAAG,uBAAuB,CAAmC,OAAO,CAAC,MAAM,CAAC,CAAC;IAE9E,MAAM,KAAK,GAAG,cAAc,CACzB,IAAI,CAAC,KAAK,EACV;QACG,eAAe,EAAE,OAAO,CAAC,eAAe,IAAI,uBAAuB;QACnE,WAAW,EAAE,WAAW;QACxB,YAAY,EAAE,4BAA4B;KAC5C,CACH,CAAC;IAEF,OAAO;QACJ,MAAM;QACN,KAAK;QACL,IAAI;QACJ,MAAM;QACN,KAAK;QACL,eAAe;QACf,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE;KAC/B,CAAC;AACL,CAAC"}
+{"version":3,"file":"data-server-harness.js","sourceRoot":"","sources":["../../src/testing/data-server-harness.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,cAAc,EAA+D,MAAM,qBAAqB,CAAC;AAClH,OAAO,EACJ,4BAA4B,EAC5B,uBAAuB,EAQzB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAgB,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AACpF,OAAO,EAAE,wBAAwB,EAA6B,MAAM,kCAAkC,CAAC;AA+EvG;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAMlC,OAAgF;IAEhF,MAAM,IAAI,GAAG,wBAAwB,EAAE,CAAC;IACxC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEzC,2EAA2E;IAC3E,wEAAwE;IACxE,6EAA6E;IAC7E,6EAA6E;IAC7E,SAAS;IACT,MAAM,EACH,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,MAAM,EACf,KAAK,EACL,SAAS,EACT,MAAM,EACN,eAAe,EACjB,GAAG,uBAAuB,CAAmC,OAAO,CAAC,MAAM,CAAC,CAAC;IAE9E,MAAM,KAAK,GAAG,cAAc,CACzB,IAAI,CAAC,KAAK,EACV;QACG,eAAe,EAAE,OAAO,CAAC,eAAe,IAAI,uBAAuB;QACnE,WAAW,EAAE,WAAW;QACxB,YAAY,EAAE,4BAA4B;KAC5C,CACH,CAAC;IAEF,OAAO;QACJ,MAAM;QACN,KAAK;QACL,IAAI;QACJ,MAAM;QACN,KAAK;QACL,SAAS;QACT,MAAM;QACN,eAAe;QACf,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE;KAC/B,CAAC;AACL,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydranium/data-server",
-  "version": "1.0.0-next.10",
+  "version": "1.0.0-next.104",
   "description": "Typed-RPC protocol head for the hydranium framework. Peer of @hydranium/core/lsp and @hydranium/glsp-server; built on @hydranium/core.",
   "keywords": [
     "hydranium",
@@ -38,6 +38,14 @@
       "types": "./lib/node/index.d.ts",
       "default": "./lib/node/index.js"
     },
+    "./messages": {
+      "types": "./lib/messages/index.d.ts",
+      "default": "./lib/messages/index.js"
+    },
+    "./lib/messages": {
+      "types": "./lib/messages/index.d.ts",
+      "default": "./lib/messages/index.js"
+    },
     "./testing": {
       "types": "./lib/testing/index.d.ts",
       "default": "./lib/testing/index.js"
@@ -67,19 +75,19 @@
     "watch": "tsc -b -w --preserveWatchOutput"
   },
   "devDependencies": {
-    "@hydranium/core": "1.0.0-next.10",
-    "@hydranium/langium": "1.0.0-next.10",
-    "@hydranium/protocol": "1.0.0-next.10",
+    "@hydranium/core": "1.0.0-next.104",
+    "@hydranium/langium": "1.0.0-next.104",
+    "@hydranium/protocol": "1.0.0-next.104",
     "rimraf": "^5.0.0",
     "typescript": "^5.8.0",
     "vscode-jsonrpc": "9.0.1",
     "vscode-languageserver-textdocument": "^1.0.12"
   },
   "peerDependencies": {
-    "@hydranium/core": "1.0.0-next.10",
-    "@hydranium/langium": "1.0.0-next.10",
-    "@hydranium/protocol": "1.0.0-next.10",
-    "vscode-jsonrpc": "^8.0.0 || ^9.0.0",
+    "@hydranium/core": "1.0.0-next.104",
+    "@hydranium/langium": "1.0.0-next.104",
+    "@hydranium/protocol": "1.0.0-next.104",
+    "vscode-jsonrpc": "9.0.1",
     "vscode-languageserver-textdocument": "^1.0.12"
   },
   "engines": {
@@ -89,5 +97,6 @@
     "access": "public"
   },
   "//browser": "Selects the diagnostics default per platform, the same mechanism @eclipse-glsp/server uses to swap its node build for its browser one. The Node module imports @hydranium/core/node; a browser bundler resolves the twin instead and therefore never follows that import, which is what keeps this package's `.` entry bundleable. Node ignores this field, so a Node host keeps the real implementation with no configuration. `check:neutral` is the proof it still applies — it bundles `.` for the browser and would fail on node:fs the moment the mapping stops matching.",
+  "//peerDependencies": "`vscode-jsonrpc` is EXACT rather than a range, because it is one link of an atomic chain with no independently movable link: `vscode-languageserver-protocol` depends on it at exactly 9.0.1, so any other value an adopter supplies is a SECOND physical copy rather than an upgrade. This wire stack breaks on copy identity rather than on structure — `ParameterStructures.auto` is a singleton compared by `===` in connection.js, so a request type built by one copy and sent over a connection owned by the other throws `Unknown parameter structure auto`. A caret or union range was rejected because npm then resolves a `vscode-jsonrpc@8.2.0` tree SILENTLY, with no diagnostic at all, and the failure surfaces only later at server init. Exact does not fail the install either — npm downgrades an unsatisfiable peer to a warning — but it is a NAMED ERESOLVE warning printing the required version beside the found one, and a hard error for anyone installing with `--strict-peer-deps`. It does NOT prevent a NESTED copy — `@eclipse-glsp/*` carries its own exact `vscode-jsonrpc@8.2.0` dependency and root `overrides` do not ship — so a consumer of the GLSP head must pin the chain in its own manifest, and docs/adopting/requirements.md carries the block to paste.",
   "//prepack": "The publish guard, and it deliberately is NOT a `prepare`: npm runs a workspace `prepare` BEFORE the root `postinstall` that applies patches/vscode-jsonrpc+9.0.1.patch, so building there fails on a cold clone and npm rolls the entire install back. `prepack` runs only when a tarball is made (`npm pack`, `npm publish`) and never on install, so it cannot break the install it has no business touching. It FAILS rather than rebuilds, because the rebuild is exactly the part that ordering defeats. What it defends against: `files` lists `lib`, `lib` is gitignored, and a `files` entry matching nothing is skipped SILENTLY — so `npm publish` from an unbuilt tree emits a tarball of `src` and nothing else, with no error."
 }

package/src/data-server.ts

@@ -9,12 +9,15 @@
 
 import {
    createRpcProxy,
+   defineMessage,
    DisposableCollection,
    isDocumentSource,
    isElementSource,
    isSyntheticSource,
+   messageError,
    ReferenceSource,
    type CloseModelArgs,
+   type HydraniumResponseError,
    type Disposable,
    type ElementSource,
    type FindNextNameArgs,
@@ -28,8 +31,9 @@ import {
    type ReferenceTarget,
    type Tracer,
    type TransferDiagnostic,
-   type TransferDocument,
-   type TransferElement
+   TransferDocument,
+   type TransferElement,
+   asSnapshotVersion
 } from '@hydranium/protocol';
 import {
    DATA_SERVER_DIAGNOSTICS_METHODS,
@@ -52,11 +56,53 @@ import {
 } from '@hydranium/protocol/data';
 import { REVERT_ON_CLOSE_CLIENT_ID, UNKNOWN_CLIENT_ID } from '@hydranium/core';
 import { defaultDataServerDiagnostics } from './default-diagnostics.js';
+
+/**
+ * Raised when a profiling command arrives with no capture running.
+ *
+ * A `ResponseError` rather than a plain `Error` so the identity survives to the
+ * response boundary, which is where the message is rendered. An unwrapped throw
+ * reaches the client as a generic internal error instead: no code for a caller
+ * to switch on, and nothing for the boundary to render from.
+ */
+export const NO_ACTIVE_PROFILE = defineMessage(
+   'hydranium/data-server/no-active-profile',
+   'No profiling capture is active; call startProfiling first.'
+);
+
+/**
+ * The JSON-RPC code, unrelated to the catalogue code above: this one is numeric,
+ * survives reconstruction and is what a caller switches on.
+ */
+export const NO_ACTIVE_PROFILE_CODE = 1002;
+
+export const noActiveProfileError = (): HydraniumResponseError => messageError(NO_ACTIVE_PROFILE_CODE, NO_ACTIVE_PROFILE);
+
+/**
+ * Raised when a reference question's wait for the build exceeds
+ * {@link DataServerOptions.referenceSettleTimeoutMs}.
+ *
+ * A `ResponseError` because a class name does not cross RPC: without the code a
+ * wire client cannot tell a wedged build from a reference that resolves to
+ * nothing, which is the distinction the wait exists to keep.
+ */
+export const REFERENCE_SETTLE_TIMEOUT = defineMessage(
+   'hydranium/data-server/reference-settle-timeout',
+   'Timed out after {elapsedMs}ms waiting for the build to settle before answering a reference query.'
+);
+
+/** See {@link NO_ACTIVE_PROFILE_CODE} for why this is separate from the catalogue code. */
+export const REFERENCE_SETTLE_TIMEOUT_CODE = 1003;
+
+export const referenceSettleTimeoutError = (elapsedMs: number): HydraniumResponseError =>
+   messageError(REFERENCE_SETTLE_TIMEOUT_CODE, REFERENCE_SETTLE_TIMEOUT, { elapsedMs });
+
 import type { DataServerDiagnosticsProvider, DataServerProfileCapture } from './diagnostics-provider.js';
 import type {
    ClientTextDocumentChangeEvent,
    HydraniumLanguageServices,
    LogNameOptions,
+   AstDiagnostic,
    ModelService,
    ProjectChangeEvent,
    ServerSharedServices,
@@ -201,6 +247,22 @@ export interface DataServerOptions extends LogNameOptions {
     */
    readonly fingerprintStrategy?: FingerprintStrategy;
 
+   /**
+    * How long a reference question waits for the build to reach `Linked` before
+    * failing with {@link REFERENCE_SETTLE_TIMEOUT_CODE}. Bounded because the
+    * wait resolves off a build-phase notification, so a build cancelled below
+    * `Linked` with nothing after it leaves the request unanswered for the life
+    * of the server.
+    *
+    * Expiry rejects rather than reading the index anyway: the unsettled index
+    * is what the wait keeps the caller away from, so falling through to it on a
+    * slow build reinstates the fault — and on a name proposal persists it.
+    *
+    * Default {@link DataServer.DEFAULT_OPTIONS}, sized for a cold workspace
+    * still reaching `Linked` for the first time.
+    */
+   readonly referenceSettleTimeoutMs?: number;
+
    /**
     * Wire-method namespace for both inbound request handlers and the
     * outbound notification client proxy. Defaults to
@@ -258,15 +320,20 @@ export interface DataServerOptions extends LogNameOptions {
     * When supplied, every inbound data-server RPC is timed into this collector
     * (via the `createRpcProxy` binding) and exposed through
     * {@link DataServerDiagnosticsProtocol.getLatency}. A head that also runs an
-    * LSP connection can pass the SAME collector to
-    * `instrumentLspConnection(connection, latency)` so one report covers both
-    * heads. Absent by default (no timing overhead).
+    * LSP connection can pass the SAME collector through `lspLatencyOptions` to
+    * that connection, so one report covers both heads. Absent by default (no
+    * timing overhead).
     */
    readonly latency?: LatencyCollector;
 }
 
-/** Fully-resolved variant — every field set, used internally after merging defaults. */
-interface ResolvedDataServerOptions {
+/**
+ * Fully-resolved variant of {@link DataServerOptions} — every field set, after
+ * merging defaults. Returned by the `protected`
+ * {@link DataServer.resolveOptions} and held on {@link DataServer.options}, so
+ * an adopter changing how defaults resolve has to name it.
+ */
+export interface ResolvedDataServerOptions {
    readonly subscriptionPhase: DocumentState;
    readonly fingerprintStrategy: FingerprintStrategy;
    readonly methodNamespace: string;
@@ -274,6 +341,7 @@ interface ResolvedDataServerOptions {
    readonly excludedMethods: readonly string[];
    /** Always resolved — to the caller's, or to the platform default. */
    readonly diagnostics: DataServerDiagnosticsProvider;
+   readonly referenceSettleTimeoutMs: number;
 }
 
 /**
@@ -301,9 +369,11 @@ interface ResolvedDataServerOptions {
  * any names supplied via {@link DataServerOptions.additionalMethods}) and
  * builds the {@link DataClientProtocol} notification proxy on the same
  * connection in one {@link createRpcProxy} call (binding `this` as its
- * `localTarget`) under the configured namespace, and subscribes one
- * `DocumentBuilder.onDocumentPhase` listener per configured phase that
- * dispatches subscription events via `clientProxy.onDocumentUpdated`.
+ * `localTarget`) under the configured namespace, and subscribes two listeners
+ * at the configured phase: a `DocumentBuilder.onDocumentPhase` one dispatching
+ * per-document `clientProxy.onDocumentUpdated` for watched URIs, and a
+ * `DocumentBuilder.onBuildPhase` one dispatching a single
+ * `clientProxy.onDocumentsBuilt` naming the batch's unwatched documents.
  *
  * The data-server requires the full {@link ServerSharedServices}
  * shape — `HydraniumTextDocuments` for client-attributed updates,
@@ -331,8 +401,9 @@ export class DataServer<
     * Framework defaults, exposed so an adopter can spread them when
     * extending rather than restate a value the framework may change.
     */
-   static readonly DEFAULT_OPTIONS: Required<Pick<DataServerOptions, 'subscriptionPhase'>> = {
-      subscriptionPhase: DocumentState.Validated
+   static readonly DEFAULT_OPTIONS: Required<Pick<DataServerOptions, 'subscriptionPhase' | 'referenceSettleTimeoutMs'>> = {
+      subscriptionPhase: DocumentState.Validated,
+      referenceSettleTimeoutMs: 60_000
    };
 
    protected readonly options: ResolvedDataServerOptions;
@@ -356,10 +427,12 @@ export class DataServer<
    /**
     * Snapshot of the most recent `DocumentBuilder.onUpdate` event. Drives
     * `reason` discrimination on outbound `onDocumentUpdated` notifications:
-    * a URI in the `changed` list emits `'changed'`, in `deleted` emits
-    * `'deleted'`, otherwise `'rebuilt'` (cascade rebuild from a dependent
-    * URI's change). The same mechanism `AstDocumentManager.onUpdate` uses on
-    * the LSP side, so reason fidelity stays consistent between heads.
+    * a URI in the `changed` list emits `'changed'`, otherwise `'rebuilt'`
+    * (cascade rebuild from a dependent URI's change). The same mechanism
+    * `AstDocumentManager.onUpdate` uses on the LSP side, so reason fidelity
+    * stays consistent between heads. The `deleted` half is read by
+    * {@link dispatchDeleteEvents} rather than by the reason discrimination,
+    * a deletion travelling on its own channel.
     */
    protected lastBuildUpdate?: { changed: readonly URI[]; deleted: readonly URI[] };
    /**
@@ -420,7 +493,7 @@ export class DataServer<
    /** Per-method RPC latency collector, when the head opted in via {@link DataServerOptions.latency}. */
    protected readonly latency?: LatencyCollector;
    /** Encoder pulled from DI. Adopters rebind `services.model.TransferEncoder` to a typed-overlay subclass. */
-   protected readonly encoder: TransferEncoder<unknown, TDiagnostic>;
+   protected readonly encoder: TransferEncoder<TDiagnostic>;
    /**
     * In-process workspace facade — the lifecycle delegate `get` / `update` / `save` go through.
     * The facade's AstDocument diagnostic shape is intentionally typed `unknown` here: adopters
@@ -429,7 +502,7 @@ export class DataServer<
     * `astDocumentToTransferDocument` accepts both shapes (wire-shape or LSP-shape) and projects
     * to wire shape on the return — see `TransferEncoder.astDocumentToTransferDocument`.
     */
-   protected readonly modelService: ModelService<AstNode, unknown, TTransfer>;
+   protected readonly modelService: ModelService<AstNode, AstDiagnostic, TTransfer>;
 
    constructor(
       protected readonly connection: MessageConnection,
@@ -448,8 +521,8 @@ export class DataServer<
                'Did you compose `createServerSharedModule(ctx)` into your shared module?'
          );
       }
-      this.encoder = encoder as TransferEncoder<unknown, TDiagnostic>;
-      this.modelService = modelService as ModelService<AstNode, unknown, TTransfer>;
+      this.encoder = encoder as TransferEncoder<TDiagnostic>;
+      this.modelService = modelService as ModelService<AstNode, AstDiagnostic, TTransfer>;
       const excluded = new Set<string>(this.options.excludedMethods);
       const registeredMethods = [
          ...DATA_SERVER_PROTOCOL_METHODS,
@@ -465,11 +538,16 @@ export class DataServer<
          methodNamespace: this.options.methodNamespace,
          localTarget: this,
          localMethods: registeredMethods as readonly (keyof this & string)[],
-         latency: this.latency
+         latency: this.latency,
+         // Bound at the chokepoint rather than per handler, so an adopter's
+         // `additionalMethods` are rendered on the same terms as the
+         // framework's own rejections.
+         renderErrorMessage: error => this.services.MessageRenderer.renderError(error)
       });
       this.disposables.push(
          this.services.workspace.DocumentBuilder.onUpdate((changed, deleted) => {
             this.lastBuildUpdate = { changed, deleted };
+            this.dispatchDeleteEvents(deleted);
          })
       );
       this.subscribeToDocumentBuilder();
@@ -539,19 +617,46 @@ export class DataServer<
          holders = new Set<string>();
          this.openedDocuments.set(args.uri, holders);
       }
+      const heldBefore = holders.has(args.clientId);
       holders.add(args.clientId);
-      const document = await this.getModelDocument({ uri: args.uri });
+      let document: TransferDocument<TTransfer, TDiagnostic>;
+      try {
+         document = await this.getModelDocument({ uri: args.uri });
+      } catch (error: unknown) {
+         // The snapshot is the last step, and failing it fails the RPC — so the
+         // caller sees no open and has no reason to close. Release what this
+         // call took rather than leaving a hold nothing on either side is
+         // tracking. A repeat open by a client that already held the URI keeps
+         // it: the hold is one per `(uri, clientId)`, so releasing here would
+         // revoke an earlier open that is still legitimately in use.
+         if (!heldBefore) {
+            try {
+               // Untracked only once the close has actually LANDED. Dropping the
+               // record first gives a failed close the same effect as a
+               // successful one: the hold survives on the document store while
+               // the connection-close drain — the only thing left that would
+               // release it — has no record of it.
+               await this.modelService.close({ uri: args.uri, clientId: args.clientId });
+               this.forgetOpenDocument(args.uri, args.clientId);
+            } catch {
+               // Swallowed so the caller receives the reason the OPEN failed
+               // rather than a secondary one about the cleanup. The record stays
+               // behind deliberately, so teardown retries the release.
+            }
+         }
+         throw error;
+      }
       // Project the authoritative client-facing version onto the open snapshot.
       // `getModelDocument` encodes the freshly-built AST snapshot, whose version
       // is the `LangiumDocument`'s own `textDocument.version`. That lags the
       // multi-client synced version whenever the open seeded the synced document
       // with a caller-supplied version id — and the synced version is what
       // `ModelService.update`'s optimistic-concurrency gate compares
-      // `baseVersion` against, so reporting the snapshot's would make the
+      // `basedOn` against, so reporting the snapshot's would make the
       // caller's first tagged write self-conflict. A genuine concurrent edit
       // still trips the gate and is reconciled by the caller's replay rather
       // than predicted here.
-      return { ...document, version: this.services.workspace.TextDocuments.version(args.uri) };
+      return { ...document, version: asSnapshotVersion(this.services.workspace.TextDocuments.version(args.uri)) };
    }
 
    async closeModelDocument(args: CloseModelArgs): Promise<void> {
@@ -734,21 +839,59 @@ export class DataServer<
    // (see resolveReferenceServices) and delegate.
    // ============================================================
 
-   async findReferenceCandidates(ctx: ReferenceContext): Promise<ReferenceCandidate[]> {
-      // Candidates are derived from resolved cross-references, so the relevant document(s) must
-      // have finished the Linked phase — otherwise a query issued right after a model update races
-      // the asynchronous rebuild and returns stale candidates. Wait the source document
-      // specifically, but ONLY when a document is actually loaded at that URI: a synthetic source
-      // can address a URI with no document (a directory URI, typically), and a per-URI `waitUntil`
-      // there throws "No document found". Fall back to a global Linked settle, matching the
-      // id-based ElementSource (no URI) path.
-      const uri = isDocumentSource(ctx.source) || isSyntheticSource(ctx.source) ? UriUtils.toUri(ctx.source.uri) : undefined;
+   /**
+    * Settle the build before a reference question is answered from the index.
+    *
+    * A query issued right after a model update otherwise races the rebuild and
+    * reads an index missing the symbols it asks about. The cost is not confined
+    * to this call: a scope built inside that window is cached, and the build's
+    * remaining documents link against it.
+    *
+    * Waits the source document specifically, but ONLY when one is loaded at
+    * that URI: a synthetic source can address a URI with no document (a
+    * directory URI, typically), where a per-URI `waitUntil` throws "No document
+    * found". Falls back to a global settle, matching the id-based
+    * `ElementSource` path.
+    *
+    * Bounded by {@link DataServerOptions.referenceSettleTimeoutMs}.
+    */
+   protected async awaitReferencesLinked(source: ReferenceSource): Promise<void> {
+      const uri = isDocumentSource(source) || isSyntheticSource(source) ? UriUtils.toUri(source.uri) : undefined;
       const waitUri = uri && this.services.workspace.LangiumDocuments.hasDocument(uri) ? uri : undefined;
-      await this.services.workspace.DocumentBuilder.waitUntil(DocumentState.Linked, waitUri);
+      const stopwatch = this.services.Clock.stopwatch();
+      let timer: Disposable | undefined;
+      const timeout = new Promise<void>((resolve, reject) => {
+         timer = this.services.Clock.setTimer(() => {
+            const elapsedMs = Math.round(stopwatch.elapsedMs);
+            // A per-URI wait resolves off a document-phase notification, so a
+            // missed one strands a wait on a document that HAS reached the
+            // phase. Re-read before failing; the workspace-wide wait has no
+            // equivalent reading and can only reject.
+            const document = waitUri ? this.services.workspace.LangiumDocuments.getDocument(waitUri) : undefined;
+            if (waitUri && document && document.state >= DocumentState.Linked) {
+               this.tracer
+                  .withUri(waitUri.toString())
+                  .warn(`Missed the 'Linked' notification after ${elapsedMs}ms; the document already reached it`);
+               resolve();
+               return;
+            }
+            reject(referenceSettleTimeoutError(elapsedMs));
+         }, this.options.referenceSettleTimeoutMs);
+      });
+      try {
+         await Promise.race([this.services.workspace.DocumentBuilder.waitUntil(DocumentState.Linked, waitUri), timeout]);
+      } finally {
+         timer?.dispose();
+      }
+   }
+
+   async findReferenceCandidates(ctx: ReferenceContext): Promise<ReferenceCandidate[]> {
+      await this.awaitReferencesLinked(ctx.source);
       return this.resolveReferenceServices(ctx.source).CandidateProvider.find(ctx);
    }
 
    async resolveReference(ref: ReferenceRequest): Promise<ReferenceTarget<TTransfer> | undefined> {
+      await this.awaitReferencesLinked(ref.source);
       const resolved = this.resolveReferenceServices(ref.source).CandidateProvider.resolveCandidate(ref);
       if (!resolved) {
          return undefined;
@@ -764,7 +907,14 @@ export class DataServer<
       // synthetic source — and the create-element flow driving this method is
       // the one that produces directory URIs, on which a bare
       // `getServices(uri)` throws while `findReferenceCandidates` succeeds.
-      const nameProvider = this.resolveReferenceServices(ReferenceSource.synthetic(args.uri, args.type)).NameProvider;
+      const source = ReferenceSource.synthetic(args.uri, args.type, args.language);
+      // Mid-rebuild the names of documents not yet re-indexed are absent from
+      // the taken set, and the caller PERSISTS what it is handed. Nothing
+      // reserves the answer either, so a name is free of the collisions the
+      // index knows about and of nothing else — two callers racing get the same
+      // proposal, which only uniqueness at the write can catch.
+      await this.awaitReferencesLinked(source);
+      const nameProvider = this.resolveReferenceServices(source).NameProvider;
       const tier = args.tier ?? 'project';
       if (tier === 'public') {
          return nameProvider.findNextProjectQualifiedName(args.type, args.proposal);
@@ -811,6 +961,9 @@ export class DataServer<
    /**
     * Pick the language that owns a reference source, in order:
     *
+    * 0. A {@link isSyntheticSource} naming its own `language` routes there.
+    *    First because every step below infers, and an inference must not
+    *    override a caller that has said which grammar it means.
     * 1. A URI-bearing source ({@link isDocumentSource}/{@link isSyntheticSource})
     *    whose URI resolves to a registered language routes by URI.
     * 2. A single-language workspace always routes to that one language — so
@@ -829,6 +982,15 @@ export class DataServer<
     */
    protected resolveReferenceLanguage(source: ReferenceSource): HydraniumLanguageServices | undefined {
       const registry = this.services.ServiceRegistry;
+      if (isSyntheticSource(source) && source.language !== undefined) {
+         const declared = registry.getServicesById(source.language);
+         if (declared) {
+            return declared;
+         }
+         // Falling through on an UNREGISTERED id rather than failing: the id
+         // crosses the wire, so a client built against a head with one more
+         // grammar would otherwise lose queries the steps below can answer.
+      }
       // `getServicesFor` (non-throwing, one ladder walk) gates the URI lookup:
       // an extensionless / unregistered URI falls through to the steps below
       // rather than throwing "no services for the extension ''".
@@ -945,14 +1107,9 @@ export class DataServer<
          // decides policy at its own layer; `root` is optional on the envelope
          // so the compiler forces that decision. Adopters preferring to throw
          // override `envelope`.
-         return {
-            uri: uri.toString(),
-            version: 0,
-            root: undefined,
-            diagnostics: [] as TDiagnostic[]
-         };
+         return TransferDocument.absent<TTransfer, TDiagnostic>(uri.toString());
       }
-      return this.encoder.toTransferDocument<AstNode>(document) as unknown as TransferDocument<TTransfer, TDiagnostic>;
+      return this.encoder.toTransferDocument(document) as unknown as TransferDocument<TTransfer, TDiagnostic>;
    }
 
    /**
@@ -967,6 +1124,57 @@ export class DataServer<
             this.dispatchPhaseEvent(document, cancelToken)
          )
       );
+      // The BUILD-phase hook, not the per-document one: this notification is one
+      // message per build rather than one per document, and Langium hands the
+      // whole batch over here. It also does not fire for a cancelled build,
+      // which is what the per-document dispatch has to check by hand.
+      this.disposables.push(
+         this.services.workspace.DocumentBuilder.onBuildPhase(this.options.subscriptionPhase, built => this.dispatchBuiltEvent(built))
+      );
+   }
+
+   /**
+    * Report the documents that reached {@link DataServerOptions.subscriptionPhase}
+    * and that NOBODY on this
+    * connection is watching — the ones a client was not told about through
+    * {@link dispatchPhaseEvent}, which is gated per URI.
+    *
+    * **The gap this closes is the one no other source can observe.** A document
+    * the client watches, it hears about already. A file changed on disk, the
+    * host's own filesystem watcher reports — and on a browser host, where the
+    * workspace lives behind this head, an external change cannot happen at all.
+    * What is left, and what nothing outside the server can see, is a document
+    * rebuilt because something it DEPENDS ON changed: its file never changed, so
+    * a filesystem watcher is silent by construction, and it has no subscriber, so
+    * the update channel is silent by design. A consumer displaying data derived
+    * from that document — a tree label, a decorator — otherwise goes stale with
+    * no signal from any source, and repairs itself the moment someone opens the
+    * file to investigate, which is what makes it expensive to diagnose later.
+    *
+    * Payload-free on purpose: URIs only, so a client re-reads what it displays
+    * rather than being handed transfer documents it did not ask for. That is the
+    * property the subscription map protects, and it is preserved here by
+    * carrying no document rather than by gating the message.
+    *
+    * Quiet in the common case. Editing a document that an editor has open leaves
+    * that URI watched and therefore out of this set, so a build with no
+    * dependents produces nothing at all, and workspace initialisation produces
+    * nothing because it does not build to this phase. The ceiling is a
+    * whole-workspace rebuild at the subscription phase: one message, URIs only.
+    *
+    * The URI is canonicalised for the same reason the subscription map is keyed
+    * that way, and is untested for the same reason as its twin in
+    * {@link dispatchDeleteEvents}: the builder reports URIs out of its own
+    * store, so a non-canonical one cannot be produced without a fixture
+    * asserting a shape the real system never emits.
+    */
+   protected dispatchBuiltEvent(built: readonly LangiumDocument[]): void {
+      const uris = built.map(document => this.canonicalKey(document.uri.toString())).filter(uri => !this.subscriptions.has(uri));
+      if (uris.length === 0) {
+         return;
+      }
+      this.tracer.debug(`Emit onDocumentsBuilt: ${uris.length} unwatched document(s)`);
+      this.clientProxy.onDocumentsBuilt({ uris });
    }
 
    /**
@@ -1004,6 +1212,56 @@ export class DataServer<
       );
    }
 
+   /**
+    * Fan out a deletion for each removed URI, to EVERY client on the connection
+    * rather than only to the ones watching that URI.
+    *
+    * **Deliberately ungated, where {@link dispatchPhaseEvent} and
+    * {@link dispatchSaveEvent} are gated.** Those two carry a built document and
+    * fire on every build, so the subscription map is what keeps bandwidth
+    * proportional to what a client asked for. A deletion is neither: it is one
+    * URI, it is rare, and it reports the workspace's STRUCTURE rather than a
+    * document's content. Gating it forces any consumer that displays the
+    * workspace — a model tree, a file decorator — to learn about disappearances
+    * from a filesystem watcher instead, which a client hosted in a browser has
+    * no way to run: its workspace lives behind the head. A client that does not
+    * care filters on the URI, which costs it a comparison.
+    *
+    * The precedent is the last-close revert broadcast (see
+    * {@link pendingRevertBroadcasts}), where the same judgement was already made
+    * in the other direction: a transition that matters enough is delivered
+    * without a subscription.
+    *
+    * Runs from the `DocumentBuilder.onUpdate` listener rather than from a phase
+    * listener, which is the only place a deletion is observable: `update`
+    * removes the document before deriving the rebuild set, so it is never built.
+    * That ordering also puts this notification ahead of the `'rebuilt'` events
+    * for the dependents whose references the deletion just broke.
+    *
+    * The `deleted` list arrives already expanded to concrete document URIs —
+    * `deleteDocuments` resolves a directory URI to the documents beneath it — so
+    * no caller has to handle a directory here.
+    *
+    * Per-URI derived state is dropped for the same reason it is dropped
+    * anywhere: it describes a document that no longer exists.
+    * {@link lastEmittedFingerprint} in particular can outlive its subscriptions
+    * through the last-close revert path — left behind, it is adopted as the
+    * baseline by the next {@link watchModelDocument} and suppresses the first
+    * emit after the file returns with its previous content.
+    *
+    * The subscription itself SURVIVES: a recreated file resumes delivering to
+    * the same watchers with no re-subscription, and a client that answers the
+    * deletion by closing releases the watch through `closeModelDocument` anyway.
+    */
+   protected dispatchDeleteEvents(deleted: readonly URI[]): void {
+      for (const removed of deleted) {
+         const uri = this.canonicalKey(removed.toString());
+         this.lastEmittedFingerprint.delete(uri);
+         this.pendingRevertBroadcasts.delete(uri);
+         this.clientProxy.onDocumentDeleted({ uri });
+      }
+   }
+
    /** Fan out a save event for the document's URI, gated by the subscription map. */
    protected dispatchSaveEvent(event: ClientTextDocumentChangeEvent<TextDocument>): void {
       // The save event arrives under the CLIENT URI the text store keys by (e.g. a
@@ -1122,26 +1380,19 @@ export class DataServer<
    /**
     * Discriminate the reason for a phase-event-driven update notification.
     * Uses the most recent `DocumentBuilder.onUpdate` snapshot:
-    * - URI in the `deleted` list → `'deleted'`
     * - URI in the `changed` list → `'changed'` (the URI was passed to
     *   `documentBuilder.update(changed, deleted)`, which spans `didChange`
     *   text-document events and programmatic `update([uri], [])` calls).
     * - Otherwise → `'rebuilt'` (cascade re-derivation: this URI was rebuilt
     *   because something it depends on changed; its own text wasn't flagged).
     *
-    * `'saved'` is NOT emitted from this code path — saves take the dedicated
-    * `DataClientProtocol.onDocumentSaved` channel; adopters that want a
-    * unified update stream synthesise `'saved'` in their bridge layer.
+    * `'saved'` is NOT emitted here — saves take the dedicated
+    * `DataClientProtocol.onDocumentSaved` channel, and adopters wanting a
+    * unified stream synthesise it in their bridge layer. A deletion is not a
+    * reason at all; see {@link dispatchDeleteEvents}.
     */
    protected resolveUpdateReason(uri: URI): TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>['reason'] {
-      const last = this.lastBuildUpdate;
-      if (last?.deleted.some(deleted => UriUtils.equals(deleted, uri))) {
-         return 'deleted';
-      }
-      if (last?.changed.some(changed => UriUtils.equals(changed, uri))) {
-         return 'changed';
-      }
-      return 'rebuilt';
+      return this.lastBuildUpdate?.changed.some(changed => UriUtils.equals(changed, uri)) ? 'changed' : 'rebuilt';
    }
 
    /**
@@ -1243,7 +1494,7 @@ export class DataServer<
 
    async stopProfiling(args: StopProfilingArgs): Promise<string> {
       if (!this.activeProfile) {
-         throw new Error('No profiling capture is active; call startProfiling first.');
+         throw noActiveProfileError();
       }
       const capture = this.activeProfile;
       this.activeProfile = undefined;
@@ -1276,7 +1527,8 @@ export class DataServer<
          methodNamespace: partial.methodNamespace ?? DATA_SERVER_WIRE_PREFIX,
          additionalMethods,
          excludedMethods: partial.excludedMethods ?? [],
-         diagnostics: partial.diagnostics ?? defaultDataServerDiagnostics()
+         diagnostics: partial.diagnostics ?? defaultDataServerDiagnostics(),
+         referenceSettleTimeoutMs: partial.referenceSettleTimeoutMs ?? DataServer.DEFAULT_OPTIONS.referenceSettleTimeoutMs
       };
    }
 }