@hydranium/data-server 1.0.0-next.42 → 1.0.0-next.420

package/lib/data-server.d.ts

@@ -6,8 +6,8 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-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, 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, type BaseVersionGate, ReferenceSource, type CloseModelArgs, type HydraniumMessageData, type HydraniumResponseError, type CanonicalUri, type Disposable, type ElementSource, type FindNextNameArgs, type LatencyCollector, type LatencyReport, type OpenModelArgs, type Project, type ReferenceCandidate, type ReferenceContext, type ReferenceRequest, type ReferenceTarget, type ModelVersion, type TextState, type Tracer, type TransferDiagnostic, TransferDocument, type TransferCreatedDocument, type TransferSavedDocument, type TransferWatchedDocument, type TransferWrittenDocument, type TransferElement, STALE_BASE_VERSION_SAVE, STALE_BASE_VERSION_UPDATE } from '@hydranium/protocol';
+import { type DataClientProtocol, type DataServerDiagnosticsProtocol, type DataServerProtocol, type DumpServerStateArgs, type StartProfilingArgs, type StopProfilingArgs, type WriteServerHeapSnapshotArgs, type CloseSessionArgs, type CreatedSession, type CreateModelDocumentArgs, type CreateSessionArgs, type GetModelDocumentArgs, type GetProjectForUriArgs, type TransferDeleteDocumentArgs, type TransferPersistDocumentArgs, type TransferSaveDocumentArgs, type WatchModelDocumentArgs, type TransferUpdateDocumentArgs, type TransferUpdateDocumentsArgs } from '@hydranium/protocol/data';
 /**
  * Raised when a profiling command arrives with no capture running.
  *
@@ -21,13 +21,27 @@ export declare const NO_ACTIVE_PROFILE: import("@hydranium/protocol").MessageDef
  * 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 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 { 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 { ClientSession, ClientSessionWriteArgs, HydraniumLanguageServices, LogNameOptions, AstDiagnostic, AstDocument, AstDocumentSavedEvent, EncodedTransferDocument, ModelDeletedEvent, ModelDirtyChangedEvent, ModelService, ModelUpdatedEvent, ProjectChangeEvent, ServerSharedServices, SessionEndCause, TransferEncoder } from '@hydranium/core';
+import { type AstNode, DocumentState, type URI } from '@hydranium/langium';
+import { type MessageConnection, ResponseError } from 'vscode-jsonrpc';
 /**
  * Which observable state {@link DataServer.computeDocumentFingerprint} hashes to
  * de-dup `onDocumentUpdated` emissions.
@@ -39,9 +53,9 @@ import type { CancellationToken, MessageConnection } from 'vscode-jsonrpc';
  *   folded in on a cascade rebuild that leaves the document's own text
  *   untouched. Safe for any adopter whose AST extensions fold derived state
  *   into the transfer projection (the framework norm).
- * - `'text-diagnostics'` — the cheaper `getText()` + diagnostics hash. An
- *   opt-DOWN for adopters that fold no derived state and want to avoid the
- *   transfer-encode per phase event.
+ * - `'text-diagnostics'` — the cheaper parsed-text + diagnostics hash. An
+ *   opt-DOWN for adopters that fold no derived state and want to avoid
+ *   stringifying the transfer root per phase event.
  */
 export type FingerprintStrategy = 'transfer-document' | 'text-diagnostics';
 /**
@@ -54,12 +68,14 @@ 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, and then waits for
+     * `ModelService.settleLanguageClient`. 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
@@ -97,6 +113,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
@@ -151,14 +182,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;
@@ -166,6 +202,40 @@ 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 release mark; {@link DataServer.pruneUriWatchRecord} enforces that on
+ * every path that removes either, so a record with no watcher has a release
+ * broadcast 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 release mark 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;
+    /**
+     * The version {@link DataServerUriWatchRecord.fingerprint} was taken at; an
+     * event goes out when either moves. Not {@link DataServerUriWatchRecord.sentVersion}:
+     * a first watch sets this and sends nothing, so the next event at its
+     * version still carries the manager's attribution.
+     */
+    fingerprintVersion?: ModelVersion;
+    /** Set by {@link DataServer.subscribeToModelReleases} once a release happened: its broadcast, the next phase event, goes out even without a watcher. */
+    releaseBroadcastPending?: 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
@@ -188,15 +258,19 @@ interface ResolvedDataServerOptions {
  * adopters subclass ONLY when they need to decorate wire returns or
  * notifications. The usual adoption path is DI rebinds alone.
  *
+ * **`TTransfer` is not checked.** It declares the union of the transfer roots
+ * the workspace's languages produce. Which root a document has is known only
+ * at runtime, from its language, so a `TTransfer` missing a language compiles.
+ *
  * Lifecycle: the constructor registers framework request handlers (plus
  * 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 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.
+ * `localTarget`) under the configured namespace, and follows documents
+ * through `ModelService`'s events: at the configured phase, `onModelUpdated`
+ * dispatches per-document `clientProxy.onDocumentUpdated` for watched URIs and
+ * `onModelsBuilt` a single `clientProxy.onDocumentsBuilt` naming the batch's
+ * unwatched documents.
  *
  * The data-server requires the full {@link ServerSharedServices}
  * shape — `HydraniumTextDocuments` for client-attributed updates,
@@ -215,94 +289,43 @@ 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.
-     *
-     * 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.
+     * Per client id, the key each URI it watched resolved to when it watched.
+     * An unwatch looks the key up here: once a file is gone, a symlink to it
+     * no longer resolves to the key the watch is under.
+     */
+    protected readonly watchKeys: Map<string, Map<string, string>>;
+    /**
+     * The position of the last update or deletion event sent, which each
+     * such event carries, and a watch's answer carries as of the moment it
+     * took whether its document exists: an event past it was sent after.
+     */
+    protected eventSequence: number;
+    /**
+     * The live 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. A session leaves once it ends, so a
+     * connection that registers many over its life does not accumulate them.
+     */
+    protected readonly clientSessions: Map<string, ClientSession<AstNode, AstDiagnostic, TTransfer, object>>;
+    /**
+     * Typed client proxy — sends `data-server/on*` notifications back over the same wire.
+     * The proxy sends any `on[A-Z]*` name other than `onDidOpenConnection` and
+     * `onDidCloseConnection`, for which it returns its own events, so a subclass
+     * with notifications of its own narrows only the type:
+     * `declare protected readonly clientProxy: TheirClient`.
      */
-    protected readonly openedDocuments: Map<string, Set<string>>;
-    /** 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'`, 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[];
-    };
-    /**
-     * 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;
@@ -314,85 +337,125 @@ export declare class DataServer<TTransfer extends TransferElement, TDiagnostic e
     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'` releases every document whose last open they close at once,
+     * and `'lost'`, the connection's own close, lets each wait out the release
+     * grace.
+     */
+    dispose(cause?: SessionEndCause): void;
+    createSession(args: CreateSessionArgs): Promise<CreatedSession>;
+    /**
+     * The epoch this server numbers versions in, which every registration and
+     * document names: the text store's, so every connection to the server
+     * answers the same one.
+     */
+    protected get epoch(): string;
+    /**
+     * Refuse a write whose base version is numbered in another epoch, as a
+     * restarted server's predecessor numbered it. Versions start afresh with
+     * each epoch, so the session's gate would take the version for text the
+     * writer never saw. Checked once the session is found, before the open
+     * check and every other check of its documents.
+     */
+    protected assertEpoch(uri: string, gate: BaseVersionGate, message?: typeof STALE_BASE_VERSION_UPDATE | typeof STALE_BASE_VERSION_SAVE): void;
+    /** End a session this connection registered. */
+    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;
+    protected dropWatches(clientId: string): void;
+    createModelDocument(args: CreateModelDocumentArgs): Promise<TransferCreatedDocument<TTransfer, TDiagnostic>>;
+    updateModelDocuments(args: TransferUpdateDocumentsArgs<TTransfer>): Promise<TransferWrittenDocument<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.
+     */
+    protected openedSnapshot(uri: string, rollback?: () => Promise<void>): Promise<TransferDocument<TTransfer, TDiagnostic>>;
     closeModelDocument(args: CloseModelArgs): Promise<void>;
+    getModelDocument(args: GetModelDocumentArgs): Promise<TransferDocument<TTransfer, TDiagnostic>>;
+    updateModelDocument(args: TransferUpdateDocumentArgs<TTransfer>): Promise<TransferWrittenDocument<TTransfer, TDiagnostic>>;
+    saveModelDocument(args: TransferSaveDocumentArgs<TTransfer>): Promise<TransferSavedDocument<TTransfer, TDiagnostic>>;
+    persistModelDocument(args: TransferPersistDocumentArgs): Promise<TransferSavedDocument<TTransfer, TDiagnostic>>;
     /**
-     * Drop the recorded hold for `(uri, clientId)` so {@link dispose} does not
-     * close it a second time. Idempotent.
+     * Delete the document through the session, then release the session's
+     * watch of it, as {@link closeModelDocument} does. Released only after the
+     * delete: one that fails leaves the session its open and its watch. Other
+     * sessions' watches survive, as for any deletion.
      */
-    protected forgetOpenDocument(uri: string, clientId: string): void;
+    deleteModelDocument(args: TransferDeleteDocumentArgs): Promise<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.
+     * Record a watch for `(uri, clientId)` in {@link uriWatchRecords}.
+     * Subsequent phase events on `uri` fan out to the wired
+     * `clientProxy.onDocumentUpdated`. The bidirectional pattern means the
+     * event channel is the client notification surface, not a returned
+     * handle.
      *
-     * 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>>;
-    /**
-     * Record a watch for `(uri, clientId)`. Subsequent phase events on `uri`
-     * 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.
+     * 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.
      *
-     * 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.
+     * Answers once the document is loaded as a read loads it, with the key
+     * events name it by and whether a document exists, taken after the watch
+     * is in place and the load, so an event sent while it loads is older.
      */
-    watchModelDocument(args: WatchModelDocumentArgs): Promise<void>;
+    watchModelDocument(args: WatchModelDocumentArgs): Promise<TransferWatchedDocument>;
     /**
      * 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}).
+     *
+     * A URI the client watched is unwatched under the key it resolved to then,
+     * from {@link watchKeys}, which still holds once its file is gone.
      */
     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.releaseBroadcastPending} 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`)
@@ -402,6 +465,7 @@ export declare class DataServer<TTransfer extends TransferElement, TDiagnostic e
      * LSP head resolves.
      *
      * Adopters can still override for head-specific URI policy by subclassing.
+     * The result keys watches only; a document is looked up by its own URI.
      */
     protected canonicalKey(uri: string): string;
     getProjects(): Promise<readonly TProject[]>;
@@ -414,8 +478,25 @@ 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>;
+    resolveReference<TElement extends TransferElement = TransferElement>(ref: ReferenceRequest): Promise<ReferenceTarget<TElement> | undefined>;
     findNextName(args: FindNextNameArgs): Promise<string>;
     /**
      * Resolve the per-language `references` services for a reference source.
@@ -426,38 +507,17 @@ export declare class DataServer<TTransfer extends TransferElement, TDiagnostic e
      */
     protected resolveReferenceServices(source: ReferenceSource): HydraniumLanguageServices['references'];
     /**
-     * Pick the language that owns a reference source, in order:
-     *
-     * 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
-     *    single-language adopters never reach the steps below, and never pay
-     *    for them.
-     * 3. An {@link isElementSource} source carries no URI, so in a
-     *    multi-language workspace it is routed via the document that holds the
-     *    element (see {@link findElementDocumentUri}).
-     * 4. A source carrying an AST type is routed by that type when exactly one
-     *    registered grammar can produce it (see
-     *    {@link resolveReferenceLanguageByType}, over the registry's own type
-     *    index). This is what resolves a create-element flow's synthetic source
-     *    on a bare directory URI without asking the adopter.
-     * 5. Anything still unresolved falls to {@link fallbackReferenceLanguage},
-     *    which is adopter policy.
-     */
-    protected resolveReferenceLanguage(source: ReferenceSource): HydraniumLanguageServices | undefined;
-    /**
-     * Route a reference source by the AST type it carries — a
-     * {@link isSyntheticSource}'s `type` (the transient node being created) or an
-     * {@link isElementSource}'s optional narrowing `type`.
+     * Pick the language that owns a reference source: the registry's
+     * `getLanguageFor` over the source's declared language, URI and AST type,
+     * with an {@link isElementSource} routed by the document that holds the
+     * element (see {@link findElementDocumentUri}) before its type, and
+     * {@link fallbackReferenceLanguage}, adopter policy, last.
      *
-     * Answers only when EXACTLY ONE registered grammar can produce the type.
-     * Several can when the type comes from a grammar both import, and then the
-     * type genuinely does not identify a language — that is a fall-through to
-     * adopter policy, not a coin toss. Note this asks which grammar can *produce*
-     * the type, not which mentions it: a grammar that merely cross-references a
-     * type can never hold a node of it.
+     * An unregistered declared language falls through rather than failing: the
+     * id crosses the wire, so a client built against a head with one more
+     * grammar would otherwise lose queries the other signals answer.
      */
-    protected resolveReferenceLanguageByType(source: ReferenceSource): HydraniumLanguageServices | undefined;
+    protected resolveReferenceLanguage(source: ReferenceSource): HydraniumLanguageServices | undefined;
     /**
      * Locate the document that holds the element an {@link ElementSource}
      * addresses, via the index's O(1) name lookup — `name` is the qualified
@@ -465,15 +525,14 @@ export declare class DataServer<TTransfer extends TransferElement, TDiagnostic e
      * disambiguates names that repeat across types (honouring grammar
      * subtyping through `AstReflection.isSubtype`).
      *
-     * Only reached on the multi-language, name-based path (step 3 of
-     * {@link resolveReferenceLanguage}); single-language adopters return at
-     * step 2.
+     * Only reached in a multi-language workspace, once the declared language
+     * and the URI have abstained.
      *
      * Abstains when the name matches elements in more than one DOCUMENT — the
      * index spans every language and is filled in build order, so "the
-     * first match" would be file-watch order rather than an answer. Step 3
-     * then falls through to the type-based step 4, which abstains on ties
-     * in the same way, and finally to adopter policy.
+     * first match" would be file-watch order rather than an answer. Routing
+     * then falls through to the element's type, which abstains on ties in the
+     * same way, and finally to adopter policy.
      */
     protected findElementDocumentUri(source: ElementSource): URI | undefined;
     /**
@@ -488,26 +547,65 @@ 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
-     * `TransferEncoder.toTransferDocument` for the walk).
-     *
-     * The encoder field's generic-map binding is widened to
-     * `Record<string, TransferElement>` at the framework-default level, and an
-     * adopter supplying a typed-overlay encoder narrows the runtime shape to
-     * its wire types. The cast on the return is where that invariant — the
-     * adopter's `TTransfer` matches its encoder's overlay — is asserted, at a
-     * single boundary point rather than spread across the callers.
+     * `TransferEncoder.toTransferDocument` for the walk). `fingerprint` is the
+     * caller's {@link computeDocumentFingerprint} of that same state, which
+     * spares hashing it twice.
+     */
+    protected envelope(uri: URI, fingerprint?: string): TransferDocument<TTransfer, TDiagnostic>;
+    /**
+     * The transfer document a request answers with for `astDocument`, its model
+     * hashed and the text stamped on it by {@link withServerState}. Every
+     * document a request answers with goes through here, so none goes out
+     * without them.
+     */
+    protected encodeDocument(astDocument: AstDocument<AstNode, AstDiagnostic>): TransferDocument<TTransfer, TDiagnostic>;
+    /**
+     * The project a client receives for `project`, unchanged by default. Every
+     * project a request answers with or a change notification carries goes
+     * through here, so a field derived for clients cannot miss one path. The
+     * result crosses as JSON, so a value a client reads goes in a data field,
+     * not a getter.
+     */
+    protected encodeProject(project: TProject): TProject;
+    /**
+     * `encoded` with `hash` on its model and the text the server holds for it:
+     * the store's while it holds the document, the build's otherwise. The text
+     * is read when the document is sent rather than kept with the build: a save
+     * changes `text.dirty` without a rebuild, and the store's text moves on before
+     * the build that follows it.
+     */
+    protected withServerState(encoded: EncodedTransferDocument<TransferElement, TDiagnostic>, hash: string): TransferDocument<TTransfer, TDiagnostic>;
+    /** Per session registered on this connection, the highest of its numbered writes of `uri` that `version` holds. */
+    protected heldWrites(uri: string, version: number): Record<string, number>;
+    /**
+     * The text the server holds for `uri`, as every envelope and a watch's
+     * answer carry it: the store's while it holds the document, the build's
+     * otherwise, and none for a document it has neither of.
      */
-    protected envelope(uri: URI): TransferDocument<TTransfer, TDiagnostic>;
+    protected serverTextState(uri: string): TextState | undefined;
     /**
-     * Subscribe one listener at the configured {@link DataServerOptions.subscriptionPhase}.
-     * The listener dispatches subscription events for every matching URI. A
-     * single listener (rather than one per subscription) keeps the cost flat
-     * regardless of subscriber count.
+     * The text a build read for a document the store never held, which is
+     * clean: the store holds every text a client gave it.
      */
-    protected subscribeToDocumentBuilder(): void;
+    protected builtTextState(uri: string): TextState | undefined;
+    /**
+     * Follow every document at the configured
+     * {@link DataServerOptions.subscriptionPhase}, once per connection rather
+     * than once per watch, so the cost stays flat in the number of watches.
+     */
+    protected subscribeToModelUpdates(): void;
     /**
      * Report the documents that reached {@link DataServerOptions.subscriptionPhase}
      * and that NOBODY on this
@@ -528,7 +626,7 @@ export declare class DataServer<TTransfer extends TransferElement, TDiagnostic e
      *
      * 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
+     * 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
@@ -536,22 +634,15 @@ export declare class DataServer<TTransfer extends TransferElement, TDiagnostic e
      * 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;
+    protected dispatchBuiltEvent(built: readonly CanonicalUri[]): void;
     /**
-     * Subscribe to the universal save event on `HydraniumTextDocuments` so a
-     * single `onDocumentSaved` wire notification fires for ANY save of a
-     * subscribed URI — regardless of whether the save originated from the
-     * data-server's RPC `saveModelDocument`, the LSP head's text-editor save,
-     * or any other client writing through `notifyDidSaveTextDocument`.
+     * Follow every save so a single `onDocumentSaved` wire notification fires
+     * for ANY save of a subscribed URI — regardless of whether the save
+     * originated from the data-server's RPC `saveModelDocument`, the LSP head's
+     * text-editor save, or any other client.
      *
-     * Architectural symmetry with {@link subscribeToDocumentBuilder}: every
+     * Architectural symmetry with {@link subscribeToModelUpdates}: every
      * subscribed client sees every state change to documents they care about,
      * regardless of which client triggered it. Firing `onDocumentSaved` only
      * from the data-server's own RPC path is a bug, not an optimisation: an
@@ -559,20 +650,42 @@ 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.
-     */
-    protected subscribeToTextDocumentCloses(): void;
+    /** 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: ModelDirtyChangedEvent): void;
+    /**
+     * Mark each document the store releases, so {@link dispatchPhaseEvent}
+     * broadcasts the build that follows even without a watcher. By default
+     * that build reverts the document to 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 release
+     * build is sent. The first build after the release consumes the mark, and
+     * goes out as the release unless it is stamped past the version a client
+     * opened the document at again: a client's write or an integrity repair
+     * that rides it keeps its author.
+     *
+     * A release, not the close itself: a document whose last client lost its
+     * connection is released only once the release 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 subscribeToModelReleases(): 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
+     * 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
@@ -581,35 +694,28 @@ export declare class DataServer<TTransfer extends TransferElement, TDiagnostic e
      * 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
+     * The precedent is the release broadcast (see
+     * {@link subscribeToModelReleases}), 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.
+     * A deletion is announced before the build that follows it, so this goes
+     * out ahead of the `'rebuilt'` events for the dependents whose references
+     * the deletion just broke.
      *
-     * 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 URI's fingerprint and release 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 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.
+     * 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. A session that
+     * deleted the document has its own released by {@link deleteModelDocument}.
      */
-    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;
+    protected dispatchDeleteEvent(event: ModelDeletedEvent): void;
+    /** Fan out a save event for the document's URI, gated on the URI's watchers. */
+    protected dispatchSaveEvent(event: AstDocumentSavedEvent<AstNode>): void;
     /**
      * Fan out a phase event for the document's URI by calling
      * `clientProxy.onDocumentUpdated`. The proxy lowers the call to a
@@ -619,52 +725,43 @@ 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.
-     */
-    protected dispatchPhaseEvent(document: LangiumDocument, cancelToken: CancellationToken): void;
-    /**
-     * Fingerprint of the document's observable state, used to de-dup
-     * `onDocumentUpdated` emissions. The {@link FingerprintStrategy} option
-     * selects what is hashed (default `'transfer-document'` — see the type), and
-     * {@link additionalFingerprintInputs} folds in any extra adopter signal.
-     *
-     * The default `'transfer-document'` strategy goes through the encoder's
-     * {@link TransferEncoder.toTransferDocument}, which is cached per build —
-     * so within one phase event the fingerprint and the subsequently-emitted
-     * `envelope` share a single encode walk.
+     * 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 release mark is the exception (see
+     * {@link subscribeToModelReleases}).
+     *
+     * An event for a rebuild with no observable change since the last emit is
+     * suppressed against the URI's fingerprint and the version it was taken at;
+     * a new version with the same fingerprint goes out with the same
+     * `model.hash`, so a watcher still learns the version. 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(event: ModelUpdatedEvent<AstNode>): void;
+    /**
+     * Fingerprint of the snapshot `root` and its encoding `encoded`, used to
+     * de-dup `onDocumentUpdated` emissions and sent as every document's
+     * `model.hash`, so it must not depend on the version or on live state. The
+     * {@link FingerprintStrategy} option selects what is hashed (default
+     * `'transfer-document'` — see the type).
+     *
+     * {@link TransferEncoder.toTransferDocument} is cached per build, so within
+     * one phase event the fingerprint and the subsequently-emitted `envelope`
+     * share a single encode walk.
      *
      * Wrapped in {@link Tracer.time} against {@link FINGERPRINT_LOG_AFTER_MS}.
      */
-    protected computeDocumentFingerprint(document: LangiumDocument): string;
-    /**
-     * Extra inputs folded into {@link computeDocumentFingerprint} alongside the
-     * chosen {@link FingerprintStrategy}. Default: none. Override to contribute a
-     * signal that lives outside the document's text / root / diagnostics — each
-     * entry need only be stable across equivalent emissions and
-     * 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 `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 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'];
+    protected computeDocumentFingerprint(root: AstNode, encoded: EncodedTransferDocument<TransferElement, TDiagnostic>): string;
     /**
      * Subscribe to the project tier's change channel and re-fan registry
      * diffs into per-project wire notifications. The internal
@@ -685,19 +782,11 @@ export declare class DataServer<TTransfer extends TransferElement, TDiagnostic e
     /**
      * Fan one internal {@link ProjectChangeEvent} out to per-project wire
      * notifications. Each `removed` entry pairs the id with the pre-removal
-     * snapshot needed for the `'removed'` wire payload.
+     * snapshot needed for the `'removed'` wire payload. A project whose
+     * {@link encodeProject} throws is logged and skipped, so the rest of the
+     * batch still reaches the client.
      */
     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>;
@@ -707,5 +796,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