@hydranium/data-server 1.0.0-next.9 → 1.0.0-next.90

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,34 @@ 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);
+
 import type { DataServerDiagnosticsProvider, DataServerProfileCapture } from './diagnostics-provider.js';
 import type {
    ClientTextDocumentChangeEvent,
    HydraniumLanguageServices,
    LogNameOptions,
+   AstDiagnostic,
    ModelService,
    ProjectChangeEvent,
    ServerSharedServices,
@@ -258,9 +285,9 @@ 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;
 }
@@ -301,9 +328,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,
@@ -356,10 +385,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 +451,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 +460,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 +479,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 +496,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();
@@ -547,11 +583,11 @@ export class DataServer<
       // 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> {
@@ -764,7 +800,7 @@ 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 nameProvider = this.resolveReferenceServices(ReferenceSource.synthetic(args.uri, args.type, args.language)).NameProvider;
       const tier = args.tier ?? 'project';
       if (tier === 'public') {
          return nameProvider.findNextProjectQualifiedName(args.type, args.proposal);
@@ -811,6 +847,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 +868,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 +993,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 +1010,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 +1098,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 +1266,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 +1380,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;

package/src/messages/index.ts

@@ -0,0 +1,19 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * Every user-facing message `@hydranium/data-server` raises.
+ *
+ * Declarations stay beside their call sites and are re-exported here, so this is
+ * enumeration rather than centralization: a code's package segment has to name
+ * the package that raises it. The English is a fallback, not a contract; the
+ * code is the contract, and renaming one is a breaking change.
+ */
+
+export { NO_ACTIVE_PROFILE, NO_ACTIVE_PROFILE_CODE, noActiveProfileError } from '../data-server.js';

package/src/testing/data-server-harness.ts

@@ -14,7 +14,9 @@ import {
    type DataClientProtocol,
    type DataServerProtocol,
    type ProjectsChangedEvent,
+   type TransferDocumentDeletedEvent,
    type TransferDocumentSavedEvent,
+   type TransferDocumentsBuiltEvent,
    type TransferDocumentUpdatedEvent
 } from '@hydranium/protocol/data';
 import { type Harness, makeCapturingDataClient } from '@hydranium/protocol/testing';
@@ -87,6 +89,10 @@ export interface DataServerHarness<
    readonly events: ReadonlyArray<TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>>;
    /** Captured `onDocumentSaved` events. */
    readonly saves: ReadonlyArray<TransferDocumentSavedEvent<TTransfer, TDiagnostic>>;
+   /** Captured `onDocumentDeleted` events. */
+   readonly deletions: ReadonlyArray<TransferDocumentDeletedEvent>;
+   /** Captured `onDocumentsBuilt` events, one per build that had unwatched documents. */
+   readonly builds: ReadonlyArray<TransferDocumentsBuiltEvent>;
    /** Captured `onProjectsChanged` events. */
    readonly projectsChanges: ReadonlyArray<ProjectsChangedEvent<TProject>>;
    /** Dispose the underlying duplex pair. Idempotent. */
@@ -115,7 +121,7 @@ export function makeDataServerHarness<
    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.
@@ -123,6 +129,8 @@ export function makeDataServerHarness<
       client: localClient,
       updates: events,
       saves,
+      deletions,
+      builds,
       projectsChanges
    } = makeCapturingDataClient<TTransfer, TDiagnostic, TProject>(options.client);
 
@@ -141,6 +149,8 @@ export function makeDataServerHarness<
       pair,
       events,
       saves,
+      deletions,
+      builds,
       projectsChanges,
       dispose: () => pair.dispose()
    };