@hydranium/data-server 1.0.0-next.17 → 1.0.0-next.174

package/lib/data-server.d.ts

@@ -6,13 +6,52 @@
  *
  * 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 { 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';
+import { DisposableCollection, ReferenceSource, type CloseModelArgs, type HydraniumMessageData, 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 CloseSessionArgs, type CreateModelDocumentArgs, type CreateSessionArgs, type GetModelDocumentArgs, type GetProjectForUriArgs, type TransferSaveDocumentArgs, type WatchModelDocumentArgs, type TransferUpdateDocumentArgs, type TransferUpdateDocumentsArgs } 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: 42002;
+export declare const noActiveProfileError: () => HydraniumResponseError;
+/**
+ * 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 declare const REFERENCE_SETTLE_TIMEOUT: import("@hydranium/protocol").MessageDefinition<"The model is still being processed; try again in a moment.">;
+/** See {@link NO_ACTIVE_PROFILE_CODE} for why this is separate from the catalogue code. */
+export declare const REFERENCE_SETTLE_TIMEOUT_CODE: 42003;
+/** The wait's length rides in `data` as `elapsedMs`, for the code that reacts rather than the reader. */
+export declare const referenceSettleTimeoutError: (elapsedMs: number) => ResponseError<HydraniumMessageData & {
+    readonly elapsedMs: number;
+}>;
 import type { DataServerDiagnosticsProvider, DataServerProfileCapture } from './diagnostics-provider.js';
-import type { ClientTextDocumentChangeEvent, HydraniumLanguageServices, LogNameOptions, ModelService, ProjectChangeEvent, ServerSharedServices, TransferEncoder } from '@hydranium/core';
+import type { ClientSession, ClientSessionWriteArgs, ClientTextDocumentChangeEvent, DocumentDirtyChangedEvent, HydraniumLanguageServices, LogNameOptions, AstDiagnostic, AstDocument, ModelService, ProjectChangeEvent, ServerSharedServices, SessionEndCause, 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';
+import { type CancellationToken, type MessageConnection, ResponseError } from 'vscode-jsonrpc';
+/**
+ * A session a data connection registered with a resume token, and how to end
+ * it from another connection. See {@link DataServer.resumableSessions}.
+ */
+export interface ResumableSession {
+    readonly token: string;
+    /** End the session as its connection closing would. */
+    readonly end: () => void;
+}
 /**
  * Which observable state {@link DataServer.computeDocumentFingerprint} hashes to
  * de-dup `onDocumentUpdated` emissions.
@@ -39,12 +78,13 @@ export interface DataServerOptions extends LogNameOptions {
      * (`DataClientProtocol.onDocumentUpdated`).
      *
      * **Subscription dispatch only** — distinct from the synchronous RPC
-     * response phase. The lifecycle reads/writes (`getModelDocument` /
-     * `updateModelDocument` / `saveModelDocument`) settle at the
-     * integrity-settled landmark (`IntegrityService.SettledState`); a
-     * read additionally upgrades to `Validated` per call when
-     * {@link GetModelDocumentArgs.includeDiagnostics} is set. This option
-     * controls only the async notification phase.
+     * response phase. A read (`getModelDocument`) settles at the
+     * integrity-settled landmark (`IntegrityService.SettledState`), or at
+     * `Validated` when {@link GetModelDocumentArgs.includeDiagnostics} is set.
+     * A write (`updateModelDocument` / `updateModelDocuments` /
+     * `saveModelDocument`) answers once its document is validated, as a
+     * session's write does. This option controls only the async notification
+     * phase.
      *
      * Default: `DocumentState.Validated` — validation is the last builder
      * phase and produces the full diagnostic set, so subscription events fired
@@ -82,6 +122,21 @@ export interface DataServerOptions extends LogNameOptions {
      * state included). See {@link FingerprintStrategy}.
      */
     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
@@ -136,14 +191,19 @@ 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;
@@ -151,6 +211,33 @@ interface ResolvedDataServerOptions {
     readonly excludedMethods: readonly string[];
     /** Always resolved — to the caller's, or to the platform default. */
     readonly diagnostics: DataServerDiagnosticsProvider;
+    readonly referenceSettleTimeoutMs: number;
+}
+/**
+ * What a {@link DataServer} keeps per canonical URI, in the `protected`
+ * {@link DataServer.uriWatchRecords}. A record lives while it has a watcher
+ * or a revert mark; {@link DataServer.pruneUriWatchRecord} enforces that on
+ * every path that removes either, so a record with no watcher has a revert
+ * pending. Test the size of {@link DataServerUriWatchRecord.watchers}, not the
+ * record's presence, for "watched".
+ */
+export interface DataServerUriWatchRecord {
+    /** The client ids watching the URI; save, dirty and phase events go out only while it is non-empty, a pending revert aside. */
+    readonly watchers: Set<string>;
+    /** Digest of the last emitted state, or of the state a first watch found; see {@link DataServer.dispatchPhaseEvent} for why it de-duplicates, {@link DataServer.computeDocumentFingerprint} for its inputs. */
+    fingerprint?: string;
+    /** Set by {@link DataServer.subscribeToTextDocumentCloses}; the next phase event broadcasts even without a watcher. */
+    revertPending?: boolean;
+    /**
+     * The version of an open document the last event sent was built at. The
+     * version sent again goes out as `'rebuilt'` from no client: the manager
+     * counts a version delivered only once its `Validated` listeners ran, so a
+     * build cancelled after the subscription phase would send it as a change
+     * twice. Only while the store has the document open: without it, a
+     * document can keep one version through changes of its file, so its events
+     * keep the manager's attribution.
+     */
+    sentVersion?: number;
 }
 /**
  * Typed-RPC protocol head for the hydranium framework. The data-server
@@ -177,9 +264,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,
@@ -198,92 +287,28 @@ interface ResolvedDataServerOptions {
  */
 export declare class DataServer<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic, TProject extends Project = Project> implements DataServerProtocol<TTransfer, TDiagnostic, TProject>, DataServerDiagnosticsProtocol, Disposable {
     protected readonly connection: MessageConnection;
-    protected readonly services: ServerSharedServices<TProject>;
+    protected readonly services: ServerSharedServices<TProject, TDiagnostic>;
     /**
      * 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'>>;
+    static readonly DEFAULT_OPTIONS: Required<Pick<DataServerOptions, 'subscriptionPhase' | 'referenceSettleTimeoutMs'>>;
     protected readonly options: ResolvedDataServerOptions;
-    /** Subscription bookkeeping: URI → set of clientIds that subscribed for that URI. */
-    protected readonly subscriptions: Map<string, Set<string>>;
+    /** This connection's {@link DataServerUriWatchRecord} per canonical URI; see there for when a record lives. */
+    protected readonly uriWatchRecords: Map<string, DataServerUriWatchRecord>;
     /**
-     * Open-document bookkeeping: URI → set of clientIds that opened it over THIS
-     * connection.
+     * The client sessions this connection registered, by client id. A document
+     * request carrying one of these ids acts as that session; one carrying any
+     * other id fails.
      *
-     * Kept because the document store releases a client's hold only from an
-     * explicit close, and a client that dies without closing would otherwise keep
-     * the document open forever — resident, and with its last-close revert
-     * suppressed. The store has no notion of which connection a clientId reached
-     * it over, so the connection-scoped set has to live here; teaching it a client
-     * identity is the more robust and much larger alternative.
+     * Entries stay after {@link dispose} has ended their sessions, so a request
+     * still running from before the connection closed reaches the ended handle
+     * and fails with the session's own error.
      */
-    protected readonly openedDocuments: Map<string, Set<string>>;
+    protected readonly clientSessions: Map<string, ClientSession<AstNode, AstDiagnostic, TTransfer, object>>;
     /** Typed client proxy — sends `data-server/on*` notifications back over the same wire. */
     protected readonly clientProxy: DataClientProtocol<TTransfer, TDiagnostic, TProject>;
     protected readonly disposables: DisposableCollection;
-    /**
-     * 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.
-     */
-    protected lastBuildUpdate?: {
-        changed: readonly URI[];
-        deleted: readonly URI[];
-    };
-    /**
-     * Per-URI hash of the last emitted (text + diagnostics) state,
-     * used by {@link dispatchPhaseEvent} to suppress duplicate
-     * `onDocumentUpdated` notifications for rebuilds that produce no
-     * observable change since the last emit.
-     *
-     * Two scenarios routinely produce such rebuilds:
-     * 1. **Refresh-triggered rebuilds.** When a second client attaches to a
-     *    document already open in another client,
-     *    `HydraniumTextDocuments.refreshContent` fires `onDidChangeContent`
-     *    purely to re-trigger the build pipeline — the text and diagnostics
-     *    are identical to the prior emit.
-     * 2. **Cascade rebuilds with no diagnostic delta.** Langium rebuilds a
-     *    document when a dependency changes; if the rebuild produces the
-     *    same diagnostics, there is nothing new to communicate to subscribers.
-     *
-     * Without this filter, both scenarios reach subscribers as wire-side
-     * `'changed'` events. A subscriber that interprets `'changed'` as
-     * "another client wrote new content" and resets its in-memory root to
-     * the server view then misreads the spurious event as a concurrent
-     * third-party write and loses the user's edits.
-     *
-     * Initialised on {@link watchModelDocument} to the current
-     * document fingerprint so the FIRST phase event after a fresh
-     * subscription is also de-duplicated against the state subscribers
-     * obtained via `getModelDocument` — they do not need a redundant phase
-     * notification for the state they just fetched.
-     *
-     * Cleared in {@link unwatchModelDocument} when the last
-     * subscriber for a URI leaves so memory does not accumulate.
-     *
-     * Stored as a cyrb53 hex digest (16 chars per URI) rather than the raw
-     * text + diagnostics serialisation so the memory cost is constant in
-     * document size. See {@link computeDocumentFingerprint} for the inputs.
-     */
-    protected readonly lastEmittedFingerprint: Map<string, string>;
-    /**
-     * URIs whose LAST client just closed. The update handler rebuilds such a
-     * document from its disk content (discarding unsaved in-session edits),
-     * but {@link dispatchPhaseEvent} gates on the subscription map — and the
-     * last close typically also removed the last watcher, so consumers that
-     * only ever fetch via `getModelDocument` would keep showing the
-     * discarded state forever. Marked on the last-close transition (see
-     * {@link subscribeToTextDocumentCloses}) and consumed by
-     * {@link dispatchPhaseEvent}, which broadcasts the following rebuild's
-     * phase event even without a subscription — de-duplicated against
-     * {@link lastEmittedFingerprint} where an entry survives, so a close
-     * whose disk state equals the last emitted state stays silent.
-     */
-    protected readonly pendingRevertBroadcasts: Set<string>;
     protected readonly tracer: Tracer;
     /** The in-flight interactive profile capture, held between {@link startProfiling} and {@link stopProfiling}. */
     protected activeProfile?: DataServerProfileCapture;
@@ -292,55 +317,83 @@ 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
-     * carry LSP-shape diagnostics in their AstDocument (e.g. an adopter's LSP-shape diagnostic type)
-     * while the wire shape stays `TDiagnostic extends TransferDiagnostic`. The encoder's
-     * `astDocumentToTransferDocument` accepts both shapes (wire-shape or LSP-shape) and projects
-     * to wire shape on the return — see `TransferEncoder.astDocumentToTransferDocument`.
+     * Its documents carry the AST-layer {@link AstDiagnostic}, never the wire `TDiagnostic`:
+     * {@link encoder} converts one into the other on the way out.
      */
-    protected readonly modelService: ModelService<AstNode, unknown, TTransfer>;
-    constructor(connection: MessageConnection, services: ServerSharedServices<TProject>, options?: DataServerOptions);
+    protected readonly modelService: ModelService<AstNode, AstDiagnostic, TTransfer>;
+    constructor(connection: MessageConnection, services: ServerSharedServices<TProject, TDiagnostic>, options?: DataServerOptions);
     /**
      * Release everything the constructor wired up — the bound protocol
-     * handlers and every listener — and clear the subscription map and the
-     * per-URI emission-fingerprint cache, so a long-lived shared services
-     * bundle does not retain per-connection memory after the connection
-     * closes. Also closes every document still open over this connection (see
-     * {@link closeOpenDocuments}), which is the SHARED store's state rather than
-     * this server's and so outlives the connection unless released here.
-     *
-     * Idempotent: subsequent calls are no-ops. Self-fires on
-     * `connection.onClose` so adopters who don't hold a reference still
-     * get per-connection cleanup; adopters that DO hold a reference may
-     * call `dispose()` directly for early teardown.
-     */
-    dispose(): void;
-    openModelDocument(args: OpenModelArgs): Promise<TransferDocument<TTransfer, TDiagnostic>>;
+     * handlers and every listener — and clear {@link uriWatchRecords}, so a
+     * long-lived shared services bundle does not retain per-connection memory
+     * after the connection closes. Also ends every session this connection registered, which closes
+     * every document it has open: the SHARED store's state rather than this
+     * server's, which outlives the connection unless released here.
+     *
+     * Idempotent: subsequent calls are no-ops. Runs by itself when the
+     * connection closes, so adopters who don't hold a reference still get
+     * per-connection cleanup; adopters that DO hold a reference may call
+     * `dispose()` directly for early teardown. The sessions end with `cause`:
+     * `'closed'` reverts every document whose last open they close at once,
+     * and `'lost'`, the connection's own close, lets each wait out the revert
+     * grace.
+     */
+    dispose(cause?: SessionEndCause): void;
+    createSession(args: CreateSessionArgs): Promise<void>;
+    /**
+     * End a session this connection registered. The ended handle stays in
+     * {@link clientSessions}, as it does after {@link dispose}, so a request for
+     * the id still arriving fails with the ended session's own error.
+     */
+    closeSession(args: CloseSessionArgs): Promise<void>;
+    /** End `session`, registered here under `clientId`, with `cause`, and drop its watches on this connection. */
+    protected endSession(clientId: string, session: ClientSession<AstNode, AstDiagnostic, TTransfer>, cause?: SessionEndCause): void;
+    /**
+     * The resumable sessions of this services tree, by client id, across all of
+     * its data connections: a client resumes on another connection than the one
+     * that registered it. An entry leaves when its session ends, by any path, so
+     * it keeps no ended connection alive.
+     *
+     * A takeover by resume token ends the old session even when its connection
+     * is still alive, so two clients that shared an id and its token would end
+     * each other's sessions. And the token is a guard against colliding with a
+     * session the server has not yet seen end, not a secret: the wire carries no
+     * authentication, and a peer that learns the token can end the session.
+     */
+    protected resumableSessions(): Map<string, ResumableSession>;
+    createModelDocument(args: CreateModelDocumentArgs): Promise<TransferDocument<TTransfer, TDiagnostic>>;
+    updateModelDocuments(args: TransferUpdateDocumentsArgs<TTransfer>): Promise<TransferDocument<TTransfer, TDiagnostic>[]>;
+    /**
+     * The session write a wire write request carries. Only the fields a session
+     * takes: a field an adopter adds to a request reaches the session only
+     * through an override of this.
+     */
+    protected toSessionWrite(request: Omit<TransferUpdateDocumentArgs<TTransfer>, 'clientId'>): ClientSessionWriteArgs<TTransfer>;
+    /**
+     * The session this connection registered under `clientId`, which every
+     * document request acts as. An id that is not one fails with the
+     * closed-session code: opening or writing under it would leave an open that
+     * no session end ever closes.
+     */
+    protected requireSession(clientId: string): ClientSession<AstNode, AstDiagnostic, TTransfer>;
+    openModelDocument(args: Pick<OpenModelArgs, 'uri' | 'clientId' | 'options'>): Promise<TransferDocument<TTransfer, TDiagnostic>>;
+    /**
+     * The snapshot a session's open or create answers with. When the read
+     * fails, `rollback` undoes the open this call made before the failure is
+     * rethrown: the caller sees no open, so nothing on its side would ever close
+     * it.
+     *
+     * Versioned with the store's shared version rather than the snapshot's own:
+     * the built document's `textDocument.version` lags the store's whenever the
+     * store assigned the version, and the store's is what a write's `basedOn` is
+     * compared against, so reporting the snapshot's would make the caller's
+     * first based-on write conflict with itself.
+     */
+    protected openedSnapshot(uri: string, rollback?: () => Promise<void>): Promise<TransferDocument<TTransfer, TDiagnostic>>;
     closeModelDocument(args: CloseModelArgs): Promise<void>;
-    /**
-     * Drop the recorded hold for `(uri, clientId)` so {@link dispose} does not
-     * close it a second time. Idempotent.
-     */
-    protected forgetOpenDocument(uri: string, clientId: string): void;
-    /**
-     * Close every document still open over this connection, for the clients that
-     * opened it here.
-     *
-     * The document store releases a per-URI hold only from an explicit close, so
-     * without this a client that dies mid-session keeps its documents open for the
-     * lifetime of the process: `isOpenInAnyClient` stays true, the document stays
-     * resident, and the last-close revert never runs. A long-lived multi-client
-     * head is the configuration where a dead client is normal rather than
-     * exceptional, so the leak accumulates there.
-     *
-     * Runs from {@link dispose}, which is synchronous, so each close is fired and
-     * its failure swallowed — a teardown must not reject, and a URI whose close
-     * fails is no worse off than it was before this drain existed.
-     */
-    protected closeOpenDocuments(): void;
     getModelDocument(args: GetModelDocumentArgs): Promise<TransferDocument<TTransfer, TDiagnostic>>;
     updateModelDocument(args: TransferUpdateDocumentArgs<TTransfer>): Promise<TransferDocument<TTransfer, TDiagnostic>>;
     saveModelDocument(args: TransferSaveDocumentArgs<TTransfer>): Promise<TransferDocument<TTransfer, TDiagnostic>>;
@@ -349,31 +402,36 @@ export declare class DataServer<TTransfer extends TransferElement, TDiagnostic e
      * fan out to the wired `clientProxy.onDocumentUpdated`. The
      * bidirectional pattern means the event channel is the client
      * notification surface, not a returned handle — this method only
-     * registers the URI in the dispatch table.
+     * registers the watcher in {@link uriWatchRecords}.
      *
-     * Also baselines the per-URI emission fingerprint (see
-     * {@link lastEmittedFingerprint}) to the document's current state when
-     * the first watcher for the URI registers. This guarantees that any
-     * phase event firing immediately after the watch with no observable
-     * change is suppressed — watchers obtain initial state via
-     * `getModelDocument` (or {@link openModelDocument}) and do not need a
-     * redundant phase notification for that same state.
+     * Also baselines the URI's emission fingerprint (see
+     * {@link dispatchPhaseEvent}) to the document's current state when the
+     * first watcher for the URI registers. This guarantees that any phase event firing immediately after
+     * the watch with no observable change is suppressed — watchers obtain
+     * initial state via `getModelDocument` (or {@link openModelDocument}) and
+     * do not need a redundant phase notification for that same state.
      */
     watchModelDocument(args: WatchModelDocumentArgs): Promise<void>;
     /**
      * Remove a watch for `(uri, clientId)` previously created by
      * {@link watchModelDocument}. Idempotent — unwatching twice is a no-op.
-     * Dispatch for `uri` stops once no watchers remain, at which point the
-     * per-URI emission fingerprint is also cleared so the next first-watch
-     * re-baselines against the then-current document state rather than a
-     * stale snapshot from the previous watch.
+     * Dispatch for `uri` stops once no watchers remain, and the emission
+     * fingerprint goes with the last watcher (see {@link pruneUriWatchRecord}).
      */
     unwatchModelDocument(args: WatchModelDocumentArgs): Promise<void>;
     /**
-     * Canonicalise a URI string for use as a subscription / fingerprint
-     * map key, via the shared `DocumentUriPolicy`. Callers may send
-     * non-canonical URIs (drive-letter casing, percent-encoding differences,
-     * or a symlink path) over the wire; the dispatch side keys by
+     * Drop what `uri` no longer needs: the
+     * {@link DataServerUriWatchRecord.fingerprint} once no client watches it,
+     * and the whole record once it holds no
+     * {@link DataServerUriWatchRecord.revertPending} mark either. Every path
+     * that removes a watcher or consumes a mark ends here.
+     */
+    protected pruneUriWatchRecord(uri: string): void;
+    /**
+     * Canonicalise a URI string for use as a {@link uriWatchRecords} key, via the
+     * shared `DocumentUriPolicy`. Callers may send non-canonical URIs
+     * (drive-letter casing, percent-encoding differences, or a symlink path)
+     * over the wire; the dispatch side keys by
      * `document.uri.toString()` from `LangiumDocuments`, so writer keys must
      * canonicalise to the same form or events silently fail to deliver.
      * Routing through the seam (rather than a bare `UriUtils.normalize`)
@@ -395,6 +453,23 @@ export declare class DataServer<TTransfer extends TransferElement, TDiagnostic e
      * subclass.
      */
     waitForReady(): Promise<void>;
+    /**
+     * 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 awaitReferencesLinked(source: ReferenceSource): Promise<void>;
     findReferenceCandidates(ctx: ReferenceContext): Promise<ReferenceCandidate[]>;
     resolveReference(ref: ReferenceRequest): Promise<ReferenceTarget<TTransfer> | undefined>;
     findNextName(args: FindNextNameArgs): Promise<string>;
@@ -409,6 +484,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
@@ -469,6 +547,15 @@ export declare class DataServer<TTransfer extends TransferElement, TDiagnostic e
      * to.
      */
     protected fallbackReferenceLanguage(_source: ReferenceSource): HydraniumLanguageServices | undefined;
+    /**
+     * Whether `error`, from waiting on `uri`'s document, means that `uri` has
+     * no document: a URI with neither a file nor text builds nothing, and
+     * Langium's wait after the build rejects for want of one, with a
+     * `ServerCancelled` response error. Any other failure, such as a read
+     * that fails before a document is registered, a cancelled wait or a
+     * `ReentrantWriteLockError`, is the caller's to see.
+     */
+    protected isMissingDocument(error: unknown, uri: string): boolean;
     /**
      * Build a {@link TransferDocument} envelope from the current document state,
      * delegating root + diagnostic encoding to {@link encoder} (see
@@ -482,6 +569,22 @@ export declare class DataServer<TTransfer extends TransferElement, TDiagnostic e
      * single boundary point rather than spread across the callers.
      */
     protected envelope(uri: URI): TransferDocument<TTransfer, TDiagnostic>;
+    /**
+     * The transfer document a request answers with for `astDocument`, the
+     * store's current `dirty` and `textHash` stamped on it by
+     * {@link withServerState}. Every document a request answers with goes
+     * through here, so none goes out without the stamp.
+     */
+    protected encodeDocument(astDocument: AstDocument<AstNode, AstDiagnostic>): TransferDocument<TTransfer, TDiagnostic>;
+    /**
+     * `document` with the store's current {@link TransferDocument.dirty} and
+     * the {@link TransferDocument.textHash} of the text the server holds for
+     * it: the store's text while a client has it open, the build's otherwise.
+     * Both are read when the document is sent rather than kept with the build:
+     * a save changes `dirty` without a rebuild, and the store's text moves on
+     * before the build that follows it.
+     */
+    protected withServerState(document: TransferDocument<TTransfer, TDiagnostic>): TransferDocument<TTransfer, TDiagnostic>;
     /**
      * Subscribe one listener at the configured {@link DataServerOptions.subscriptionPhase}.
      * The listener dispatches subscription events for every matching URI. A
@@ -489,6 +592,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 watcher gate 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 {@link uriWatchRecords} 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
@@ -504,14 +643,73 @@ export declare class DataServer<TTransfer extends TransferElement, TDiagnostic e
      * clients, which never clear their dirty state.
      */
     protected subscribeToTextDocumentSaves(): void;
-    /**
-     * Mark the last-close transition per URI (see
-     * {@link pendingRevertBroadcasts}). The listener consults
-     * `isOpenInAnyClient` AFTER the store decremented the closing client's
-     * hold, so a `false` answer means this close was the last one.
+    /** Relay each change of a document's dirty state; see {@link dispatchDirtyEvent}. */
+    protected subscribeToDirtyChanges(): void;
+    /**
+     * Send a dirty flip to the connection, gated on the URI's watchers as
+     * {@link dispatchSaveEvent} is: the answer at any one moment travels on
+     * every document sent, so a client that watches nothing reads it there.
+     */
+    protected dispatchDirtyEvent(event: DocumentDirtyChangedEvent): void;
+    /**
+     * Mark each document the store releases after its last close, so
+     * {@link dispatchPhaseEvent} broadcasts the following rebuild even without
+     * a watcher. The store rebuilds such a document from its disk content,
+     * discarding unsaved in-session edits, and the last close typically also
+     * removed the last watcher: without the broadcast, a consumer that only
+     * ever fetches via `getModelDocument` keeps showing the discarded state.
+     * The broadcast is de-duplicated against the fingerprint while a watcher
+     * holds one, so a close whose disk state equals the last emitted state
+     * stays silent; with no watcher there is no fingerprint, and every revert
+     * is sent.
+     *
+     * A release, not the close itself: a document whose last client lost its
+     * connection is released only once the revert grace runs out, or when
+     * another client opens it meanwhile, and not at all when a client lost
+     * from it opens it again within its own grace.
      */
     protected subscribeToTextDocumentCloses(): void;
-    /** Fan out a save event for the document's URI, gated by the subscription map. */
+    /**
+     * 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 watcher gate 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 subscribeToTextDocumentCloses}), 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.
+     *
+     * The URI's fingerprint and revert mark are dropped: they describe a
+     * document that no longer exists. A kept fingerprint is adopted as the
+     * baseline and suppresses the first emit after the file returns with its
+     * previous content.
+     *
+     * The watchers SURVIVE: a recreated file resumes delivering to them 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 on the URI's watchers. */
     protected dispatchSaveEvent(event: ClientTextDocumentChangeEvent<TextDocument>): void;
     /**
      * Fan out a phase event for the document's URI by calling
@@ -522,13 +720,25 @@ export declare class DataServer<TTransfer extends TransferElement, TDiagnostic e
      * out to multiple local subscribers with an `Emitter<T>` — the
      * framework deliberately does NOT promise multi-listener semantics.
      *
-     * The dispatch is guarded by two filters:
-     *   1. **Subscription map**: events for URIs no subscriber registered for
-     *      are NOT sent over the wire (bandwidth scales with subscribed URIs,
-     *      not phase events).
-     *   2. **Emission fingerprint**: events for rebuilds that produce no
-     *      observable change since the last emit are suppressed. See
-     *      {@link lastEmittedFingerprint} for the rationale.
+     * An event for a URI no client watches is NOT sent over the wire, so
+     * bandwidth scales with watched URIs rather than with phase events; a
+     * pending revert mark is the exception (see
+     * {@link subscribeToTextDocumentCloses}).
+     *
+     * An event for a rebuild with no observable change since the last emit is
+     * suppressed against the URI's fingerprint. Such rebuilds are routine: a
+     * second client attaching to an open document makes
+     * `HydraniumTextDocuments.refreshContent` fire `onDidChangeContent` purely
+     * to re-trigger the build, and Langium rebuilds a document when a
+     * dependency changes even if its diagnostics come out the same. Sent at a
+     * version this head has not sent, they reach watchers as `'changed'`, and a
+     * watcher that reads `'changed'` as another client's write and resets its
+     * root to the server view loses the user's edits. The first {@link watchModelDocument} baselines the
+     * fingerprint, so the first event after a watch is de-duplicated against
+     * the state the watcher just fetched; it goes with the last watcher, so the
+     * next first watch re-baselines rather than adopting a stale digest. A
+     * digest keeps its memory constant in document size; see
+     * {@link computeDocumentFingerprint} for the inputs.
      */
     protected dispatchPhaseEvent(document: LangiumDocument, cancelToken: CancellationToken): void;
     /**
@@ -553,21 +763,6 @@ export declare class DataServer<TTransfer extends TransferElement, TDiagnostic e
      * JSON-serialisable.
      */
     protected additionalFingerprintInputs(_document: LangiumDocument): readonly unknown[];
-    /**
-     * 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.
-     */
-    protected resolveUpdateReason(uri: URI): TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>['reason'];
     /**
      * Subscribe to the project tier's change channel and re-fan registry
      * diffs into per-project wire notifications. The internal
@@ -591,16 +786,6 @@ export declare class DataServer<TTransfer extends TransferElement, TDiagnostic e
      * snapshot needed for the `'removed'` wire payload.
      */
     protected dispatchProjectChangeEvent(event: ProjectChangeEvent<TProject>): void;
-    /**
-     * Resolve the wire-level `sourceClientId` for `document`'s events — the client
-     * that authored its current version, from the version-author history on
-     * `HydraniumTextDocuments`. The protocol-level counterpart of the internal
-     * `AstDocumentManager.getAuthor`: a framework-internal rebuild has no author,
-     * so this surfaces the {@link UNKNOWN_CLIENT_ID} presentation default. Adopters
-     * that rebuild through non-text-document channels override to derive a
-     * source id of their own.
-     */
-    protected resolveSourceClientId(document: LangiumDocument): string;
     dumpServerState(args: DumpServerStateArgs): Promise<string>;
     writeHeapSnapshot(args: WriteServerHeapSnapshotArgs): Promise<string>;
     dumpPodMemory(): Promise<string>;
@@ -610,5 +795,4 @@ export declare class DataServer<TTransfer extends TransferElement, TDiagnostic e
     /** Resolve a partial options object into a fully-defaulted form. */
     protected resolveOptions(partial: DataServerOptions): ResolvedDataServerOptions;
 }
-export {};
 //# sourceMappingURL=data-server.d.ts.map