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

package/README.md

@@ -22,7 +22,11 @@ Installed by the server process that already composes
 - **Push notifications instead of polling:** `onDocumentUpdated` when a
   subscribed document reaches the configured build phase
   (`DataServerOptions.subscriptionPhase`, `DocumentState.Validated` by default),
-  `onDocumentSaved` on a separate channel, and `onProjectsChanged` from the
+  `onDocumentSaved` on a separate channel, `onDocumentDeleted` on a third (a
+  deleted document has no built state to carry, and the build-phase path never
+  runs for one), `onDocumentsBuilt` once per build for the documents nobody
+  watches — chiefly those rebuilt as a cascade, which no filesystem watcher can
+  see because their own files did not change — and `onProjectsChanged` from the
   project registry.
 - **Projects as first-class:** `getProjects` and `getProjectForUri`, answered from
   the framework's `ProjectManager`.

package/lib/data-server.d.ts

@@ -6,10 +6,25 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import { DisposableCollection, ReferenceSource, type CloseModelArgs, type Disposable, type ElementSource, type FindNextNameArgs, type LatencyCollector, type LatencyReport, type OpenModelArgs, type Project, type ReferenceCandidate, type ReferenceContext, type ReferenceRequest, type ReferenceTarget, type Tracer, type TransferDiagnostic, type TransferDocument, type TransferElement } from '@hydranium/protocol';
+import { DisposableCollection, ReferenceSource, type CloseModelArgs, type HydraniumResponseError, type Disposable, type ElementSource, type FindNextNameArgs, type LatencyCollector, type LatencyReport, type OpenModelArgs, type Project, type ReferenceCandidate, type ReferenceContext, type ReferenceRequest, type ReferenceTarget, type Tracer, type TransferDiagnostic, TransferDocument, type TransferElement } from '@hydranium/protocol';
 import { type DataClientProtocol, type DataServerDiagnosticsProtocol, type DataServerProtocol, type DumpServerStateArgs, type StartProfilingArgs, type StopProfilingArgs, type WriteServerHeapSnapshotArgs, type GetModelDocumentArgs, type GetProjectForUriArgs, type TransferSaveDocumentArgs, type WatchModelDocumentArgs, type TransferDocumentUpdatedEvent, type TransferUpdateDocumentArgs } from '@hydranium/protocol/data';
+/**
+ * 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 declare const NO_ACTIVE_PROFILE: import("@hydranium/protocol").MessageDefinition<"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 declare const NO_ACTIVE_PROFILE_CODE = 1002;
+export declare const noActiveProfileError: () => HydraniumResponseError;
 import type { DataServerDiagnosticsProvider, DataServerProfileCapture } from './diagnostics-provider.js';
-import type { ClientTextDocumentChangeEvent, HydraniumLanguageServices, LogNameOptions, ModelService, ProjectChangeEvent, ServerSharedServices, TransferEncoder } from '@hydranium/core';
+import type { ClientTextDocumentChangeEvent, HydraniumLanguageServices, LogNameOptions, AstDiagnostic, ModelService, ProjectChangeEvent, ServerSharedServices, TransferEncoder } from '@hydranium/core';
 import type { TextDocument } from 'vscode-languageserver-textdocument';
 import { type AstNode, DocumentState, type LangiumDocument, type URI } from '@hydranium/langium';
 import type { CancellationToken, MessageConnection } from 'vscode-jsonrpc';
@@ -136,9 +151,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;
 }
@@ -177,9 +192,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,
@@ -225,10 +242,12 @@ export declare class DataServer<TTransfer extends TransferElement, TDiagnostic e
     /**
      * 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[];
@@ -292,7 +311,7 @@ export declare class DataServer<TTransfer extends TransferElement, TDiagnostic e
     /** 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
@@ -301,7 +320,7 @@ export declare class DataServer<TTransfer extends TransferElement, TDiagnostic e
      * `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(connection: MessageConnection, services: ServerSharedServices<TProject>, options?: DataServerOptions);
     /**
      * Release everything the constructor wired up — the bound protocol
@@ -409,6 +428,9 @@ export declare class DataServer<TTransfer extends TransferElement, TDiagnostic e
     /**
      * 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
@@ -489,6 +511,42 @@ export declare class DataServer<TTransfer extends TransferElement, TDiagnostic e
      * regardless of subscriber count.
      */
     protected subscribeToDocumentBuilder(): void;
+    /**
+     * 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;
     /**
      * Subscribe to the universal save event on `HydraniumTextDocuments` so a
      * single `onDocumentSaved` wire notification fires for ANY save of a
@@ -511,6 +569,48 @@ export declare class DataServer<TTransfer extends TransferElement, TDiagnostic e
      * hold, so a `false` answer means this close was the last one.
      */
     protected subscribeToTextDocumentCloses(): void;
+    /**
+     * 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;
     /** Fan out a save event for the document's URI, gated by the subscription map. */
     protected dispatchSaveEvent(event: ClientTextDocumentChangeEvent<TextDocument>): void;
     /**
@@ -556,16 +656,16 @@ export declare class DataServer<TTransfer extends TransferElement, TDiagnostic e
     /**
      * 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'];
     /**

package/lib/data-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data-server.d.ts","sourceRoot":"","sources":["../src/data-server.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAEJ,oBAAoB,EAIpB,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,OAAO,EACZ,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,MAAM,EACX,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACtB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAIJ,KAAK,kBAAkB,EACvB,KAAK,6BAA6B,EAClC,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,2BAA2B,EAChC,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,EAE3B,KAAK,4BAA4B,EACjC,KAAK,0BAA0B,EACjC,MAAM,0BAA0B,CAAC;AAGlC,OAAO,KAAK,EAAE,6BAA6B,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACzG,OAAO,KAAK,EACT,6BAA6B,EAC7B,yBAAyB,EACzB,cAAc,EACd,YAAY,EACZ,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,EACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,EAAE,KAAK,OAAO,EAAE,aAAa,EAAE,KAAK,eAAe,EAAY,KAAK,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAC3G,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAwC3E;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,mBAAmB,GAAG,mBAAmB,GAAG,kBAAkB,CAAC;AA0B3E;;;GAGG;AACH,MAAM,WAAW,iBAAkB,SAAQ,cAAc;IACtD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,aAAa,CAAC;IAE3C;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,6BAA6B,CAAC;IAErD;;;;OAIG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;IAEnD;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAElC;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAE/C;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAE7C;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC;CACtC;AAED,wFAAwF;AACxF,UAAU,yBAAyB;IAChC,QAAQ,CAAC,iBAAiB,EAAE,aAAa,CAAC;IAC1C,QAAQ,CAAC,mBAAmB,EAAE,mBAAmB,CAAC;IAClD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,qEAAqE;IACrE,QAAQ,CAAC,WAAW,EAAE,6BAA6B,CAAC;CACtD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qBAAa,UAAU,CACpB,SAAS,SAAS,eAAe,EACjC,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,EAC3D,QAAQ,SAAS,OAAO,GAAG,OAAO,CAElC,YAAW,kBAAkB,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,6BAA6B,EAAE,UAAU;IA2GvG,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,iBAAiB;IAChD,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC,QAAQ,CAAC;IA1G9D;;;OAGG;IACH,MAAM,CAAC,QAAQ,CAAC,eAAe,EAAE,QAAQ,CAAC,IAAI,CAAC,iBAAiB,EAAE,mBAAmB,CAAC,CAAC,CAErF;IAEF,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,yBAAyB,CAAC;IACtD,qFAAqF;IACrF,SAAS,CAAC,QAAQ,CAAC,aAAa,2BAAkC;IAClE;;;;;;;;;;OAUG;IACH,SAAS,CAAC,QAAQ,CAAC,eAAe,2BAAkC;IACpE,0FAA0F;IAC1F,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC;IACrF,SAAS,CAAC,QAAQ,CAAC,WAAW,uBAA8B;IAC5D;;;;;;;OAOG;IACH,SAAS,CAAC,eAAe,CAAC,EAAE;QAAE,OAAO,EAAE,SAAS,GAAG,EAAE,CAAC;QAAC,OAAO,EAAE,SAAS,GAAG,EAAE,CAAA;KAAE,CAAC;IACjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACH,SAAS,CAAC,QAAQ,CAAC,sBAAsB,sBAA6B;IACtE;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,QAAQ,CAAC,uBAAuB,cAAqB;IAC/D,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAClC,gHAAgH;IAChH,SAAS,CAAC,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACnD,8GAA8G;IAC9G,SAAS,CAAC,QAAQ,UAAS;IAC3B,sGAAsG;IACtG,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC9C,4GAA4G;IAC5G,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IAClE;;;;;;;OAOG;IACH,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;gBAGrD,UAAU,EAAE,iBAAiB,EAC7B,QAAQ,EAAE,oBAAoB,CAAC,QAAQ,CAAC,EAC3D,OAAO,GAAE,iBAAsB;IAgDlC;;;;;;;;;;;;;OAaG;IACH,OAAO,IAAI,IAAI;IA8BT,iBAAiB,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IA4BzF,kBAAkB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAS7D;;;OAGG;IACH,SAAS,CAAC,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAWjE;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,kBAAkB,IAAI,IAAI;IAU9B,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IAgB/F,mBAAmB,CAAC,IAAI,EAAE,0BAA0B,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IAKnH,iBAAiB,CAAC,IAAI,EAAE,wBAAwB,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IAKrH;;;;;;;;;;;;;;OAcG;IACG,kBAAkB,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBrE;;;;;;;OAOG;IACG,oBAAoB,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;IAavE;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAIrC,WAAW,IAAI,OAAO,CAAC,SAAS,QAAQ,EAAE,CAAC;IAS3C,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC;IAQjF;;;;;;OAMG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAU7B,uBAAuB,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAc7E,gBAAgB,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,SAAS,CAAC,GAAG,SAAS,CAAC;IASxF,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;IAgC3D;;;;;;OAMG;IACH,SAAS,CAAC,wBAAwB,CAAC,MAAM,EAAE,eAAe,GAAG,yBAAyB,CAAC,YAAY,CAAC;IAYpG;;;;;;;;;;;;;;;;;;OAkBG;IACH,SAAS,CAAC,wBAAwB,CAAC,MAAM,EAAE,eAAe,GAAG,yBAAyB,GAAG,SAAS;IAyBlG;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,8BAA8B,CAAC,MAAM,EAAE,eAAe,GAAG,yBAAyB,GAAG,SAAS;IAQxG;;;;;;;;;;;;;;;;OAgBG;IACH,SAAS,CAAC,sBAAsB,CAAC,MAAM,EAAE,aAAa,GAAG,GAAG,GAAG,SAAS;IAcxE;;;;;;;;;;OAUG;IACH,SAAS,CAAC,yBAAyB,CAAC,OAAO,EAAE,eAAe,GAAG,yBAAyB,GAAG,SAAS;IAQpG;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC;IAqBtE;;;;;OAKG;IACH,SAAS,CAAC,0BAA0B,IAAI,IAAI;IAQ5C;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,4BAA4B,IAAI,IAAI;IAI9C;;;;;OAKG;IACH,SAAS,CAAC,6BAA6B,IAAI,IAAI;IAW/C,kFAAkF;IAClF,SAAS,CAAC,iBAAiB,CAAC,KAAK,EAAE,6BAA6B,CAAC,YAAY,CAAC,GAAG,IAAI;IAkBrF;;;;;;;;;;;;;;;;OAgBG;IACH,SAAS,CAAC,kBAAkB,CAAC,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE,iBAAiB,GAAG,IAAI;IAuC7F;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,0BAA0B,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM;IAgBvE;;;;;;OAMG;IACH,SAAS,CAAC,2BAA2B,CAAC,SAAS,EAAE,eAAe,GAAG,SAAS,OAAO,EAAE;IAIrF;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,mBAAmB,CAAC,GAAG,EAAE,GAAG,GAAG,4BAA4B,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC;IAWvG;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,yBAAyB,IAAI,IAAI;IAI3C;;;;OAIG;IACH,SAAS,CAAC,0BAA0B,CAAC,KAAK,EAAE,kBAAkB,CAAC,QAAQ,CAAC,GAAG,IAAI;IAkB/E;;;;;;;;OAQG;IACH,SAAS,CAAC,qBAAqB,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM;IAY5D,eAAe,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;IAM3D,iBAAiB,CAAC,IAAI,EAAE,2BAA2B,GAAG,OAAO,CAAC,MAAM,CAAC;IAMrE,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;IAMhC,cAAc,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAevD,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;IAcvD,UAAU,IAAI,OAAO,CAAC,aAAa,CAAC;IAI1C,oEAAoE;IACpE,SAAS,CAAC,cAAc,CAAC,OAAO,EAAE,iBAAiB,GAAG,yBAAyB;CAmBjF"}
+{"version":3,"file":"data-server.d.ts","sourceRoot":"","sources":["../src/data-server.ts"],"names":[],"mappings":"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"}

package/lib/data-server.js

@@ -6,10 +6,25 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import { createRpcProxy, DisposableCollection, isDocumentSource, isElementSource, isSyntheticSource, ReferenceSource } from '@hydranium/protocol';
+import { createRpcProxy, defineMessage, DisposableCollection, isDocumentSource, isElementSource, isSyntheticSource, messageError, ReferenceSource, TransferDocument, asSnapshotVersion } from '@hydranium/protocol';
 import { DATA_SERVER_DIAGNOSTICS_METHODS, DATA_SERVER_PROTOCOL_METHODS, DATA_SERVER_WIRE_PREFIX } 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 = () => messageError(NO_ACTIVE_PROFILE_CODE, NO_ACTIVE_PROFILE);
 import { DocumentState, UriUtils } from '@hydranium/langium';
 /**
  * Domain separator between text and diagnostics inputs of
@@ -94,9 +109,11 @@ const FINGERPRINT_LOG_AFTER_MS = 5;
  * 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,
@@ -144,10 +161,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.
      */
     lastBuildUpdate;
     /**
@@ -248,10 +267,15 @@ export class DataServer {
             methodNamespace: this.options.methodNamespace,
             localTarget: this,
             localMethods: registeredMethods,
-            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();
         this.subscribeToTextDocumentSaves();
@@ -325,11 +349,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) {
         // Closing a session also releases its watch for (uri, clientId) — a
@@ -526,7 +550,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);
@@ -569,6 +593,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
@@ -587,6 +614,15 @@ export class DataServer {
      */
     resolveReferenceLanguage(source) {
         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 ''".
@@ -698,12 +734,7 @@ 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: []
-            };
+            return TransferDocument.absent(uri.toString());
         }
         return this.encoder.toTransferDocument(document);
     }
@@ -715,6 +746,54 @@ export class DataServer {
      */
     subscribeToDocumentBuilder() {
         this.disposables.push(this.services.workspace.DocumentBuilder.onDocumentPhase(this.options.subscriptionPhase, (document, cancelToken) => 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.
+     */
+    dispatchBuiltEvent(built) {
+        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 });
     }
     /**
      * Subscribe to the universal save event on `HydraniumTextDocuments` so a
@@ -747,6 +826,55 @@ 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.
+     */
+    dispatchDeleteEvents(deleted) {
+        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. */
     dispatchSaveEvent(event) {
         // The save event arrives under the CLIENT URI the text store keys by (e.g. a
@@ -855,26 +983,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}.
      */
     resolveUpdateReason(uri) {
-        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';
     }
     /**
      * Subscribe to the project tier's change channel and re-fan registry
@@ -967,7 +1088,7 @@ export class DataServer {
     }
     async stopProfiling(args) {
         if (!this.activeProfile) {
-            throw new Error('No profiling capture is active; call startProfiling first.');
+            throw noActiveProfileError();
         }
         const capture = this.activeProfile;
         this.activeProfile = undefined;