@hydranium/data-server 1.0.0-next.10

package/lib/data-server.d.ts

@@ -0,0 +1,614 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+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 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';
+/**
+ * Which observable state {@link DataServer.computeDocumentFingerprint} hashes to
+ * de-dup `onDocumentUpdated` emissions.
+ *
+ * - `'transfer-document'` (default) — the client-visible transfer root
+ *   (`TransferEncoder.toTransferDocument`) plus diagnostics. This is exactly the
+ *   payload `envelope` sends, so it changes whenever — and only when — the
+ *   client-visible model changes, INCLUDING cross-document derived state
+ *   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.
+ */
+export type FingerprintStrategy = 'transfer-document' | 'text-diagnostics';
+/**
+ * Construction-time options for {@link DataServer}. Every field is
+ * optional; values not supplied fall back to {@link DataServer.DEFAULT_OPTIONS}.
+ */
+export interface DataServerOptions extends LogNameOptions {
+    /**
+     * Document phase at which the data-server fires subscription events
+     * (`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.
+     *
+     * Default: `DocumentState.Validated` — validation is the last builder
+     * phase and produces the full diagnostic set, so subscription events fired
+     * at validation surface the complete diagnostic picture.
+     *
+     * **Trade-off.** Validation can take seconds on a real workspace. Adopters
+     * that publish validation diagnostics through a separate channel —
+     * typically LSP `publishDiagnostics` — can fire subscription events earlier
+     * (e.g. `IndexedReferences`) since clients observe validation diagnostics
+     * asynchronously via that channel regardless of when the subscription
+     * event lands.
+     */
+    readonly subscriptionPhase?: DocumentState;
+    /**
+     * Runtime-specific implementation of the four diagnostics methods that need
+     * a process to inspect — heap snapshot, profile capture, pod memory, server
+     * state.
+     *
+     * **Defaulted per platform, so most hosts pass nothing.** On Node the default
+     * is the real implementation; in a browser bundle `package.json`'s `browser`
+     * field selects a twin whose methods reject, because there is no process to
+     * inspect. Supply this only to override — a custom implementation, or to say
+     * explicitly at the call site which one you mean.
+     *
+     * It is injected rather than reached for because a static
+     * `@hydranium/core/node` import on this package's portable entry pulls
+     * `node:fs`, `node:v8` and `node:perf_hooks` into any browser build, over
+     * methods a browser cannot call anyway — which is what previously made the
+     * head unbundleable.
+     */
+    readonly diagnostics?: DataServerDiagnosticsProvider;
+    /**
+     * Which observable state the `onDocumentUpdated` de-dup fingerprint hashes.
+     * Defaults to `'transfer-document'` (the client-visible payload, derived
+     * state included). See {@link FingerprintStrategy}.
+     */
+    readonly fingerprintStrategy?: FingerprintStrategy;
+    /**
+     * Wire-method namespace for both inbound request handlers and the
+     * outbound notification client proxy. Defaults to
+     * {@link DATA_SERVER_WIRE_PREFIX} (`'data-server/'`).
+     *
+     * Adopters that combine the data-server head with their own protocol
+     * head on one connection pass their own namespace, so the full wire
+     * surface is partitioned under one prefix instead of two, the way LSP
+     * itself partitions `textDocument/*` and `workspace/*`. The client side
+     * (the `methodNamespace` option of its client `createRpcProxy`) MUST
+     * agree.
+     */
+    readonly methodNamespace?: string;
+    /**
+     * Additional protocol-method names to register as request handlers on
+     * the same connection alongside the framework's
+     * {@link DATA_SERVER_PROTOCOL_METHODS}. Used by `DataServer` subclasses
+     * that implement an adopter-specific protocol — the subclass implements
+     * the adopter methods on `this`, the names go here, and the
+     * constructor's single `createRpcProxy` call (binding `this` as its
+     * `localTarget`) registers framework + adopter handlers under one
+     * namespace.
+     *
+     * Throws at construction time if any name overlaps with a built-in
+     * framework method (would cause vscode-jsonrpc duplicate-handler
+     * errors at registration). Notification-shaped (`on*`-prefixed) names
+     * register as notification handlers; everything else as request
+     * handlers — same `on*`-prefix heuristic the framework's
+     * `bindRpcMethods` uses for `DataClientProtocol`.
+     */
+    readonly additionalMethods?: readonly string[];
+    /**
+     * Framework method names to NOT register on the wire. Used by adopters
+     * that expose renamed domain-vocabulary equivalents of framework
+     * methods and want to keep the wire surface free of the unused
+     * framework names.
+     *
+     * Each name is filtered out of the combined `[framework + additional]`
+     * set before the handlers are bound. The adopter typically pairs an
+     * `excludedMethods` entry with an `additionalMethods` entry naming the
+     * renamed equivalent on the same class — the subclass's renamed method
+     * usually delegates to the inherited framework implementation via
+     * `super.X()` so the behaviour stays identical.
+     *
+     * Names that are neither in `DATA_SERVER_PROTOCOL_METHODS` nor in
+     * `additionalMethods` are simply no-ops — listing an unknown name does
+     * not throw. The overlap-detection between `additionalMethods` and
+     * built-in framework methods still fires for non-excluded names.
+     */
+    readonly excludedMethods?: readonly string[];
+    /**
+     * 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).
+     */
+    readonly latency?: LatencyCollector;
+}
+/** Fully-resolved variant — every field set, used internally after merging defaults. */
+interface ResolvedDataServerOptions {
+    readonly subscriptionPhase: DocumentState;
+    readonly fingerprintStrategy: FingerprintStrategy;
+    readonly methodNamespace: string;
+    readonly additionalMethods: readonly string[];
+    readonly excludedMethods: readonly string[];
+    /** Always resolved — to the caller's, or to the platform default. */
+    readonly diagnostics: DataServerDiagnosticsProvider;
+}
+/**
+ * Typed-RPC protocol head for the hydranium framework. The data-server
+ * is a PEER of `@hydranium/core/lsp` and `@hydranium/glsp-server` —
+ * all three heads coordinate through shared services in
+ * `@hydranium/core` (multi-client text documents, self-save
+ * registry, document-builder phases, project manager, ModelService
+ * facade) and never depend on each other at the package level.
+ *
+ * **No abstract grammar hooks**. The data-server has no grammar-specific
+ * abstract methods: `serialize` / `parseModel` live on
+ * {@link ModelService} (the in-process facade), where the `update` /
+ * `save` lifecycle owns the transfer-model round-trip. Adopters that want
+ * to customise serialisation rebind `services.model.ModelService` with a
+ * subclass; adopters that need a typed-overlay encoder rebind
+ * `services.model.TransferEncoder` with a subclass exposing the typed
+ * `TTransferMap`.
+ *
+ * **What still subclasses**. The data-server is concrete by default;
+ * adopters subclass ONLY when they need to decorate wire returns or
+ * notifications. The usual adoption path is DI rebinds alone.
+ *
+ * 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 one
+ * `DocumentBuilder.onDocumentPhase` listener per configured phase that
+ * dispatches subscription events via `clientProxy.onDocumentUpdated`.
+ *
+ * The data-server requires the full {@link ServerSharedServices}
+ * shape — `HydraniumTextDocuments` for client-attributed updates,
+ * `WritableFileSystemProvider` for save, `SelfSaveRegistry` for
+ * save-echo suppression, `ProjectManager` for project listing,
+ * `ModelService` for the lifecycle delegate, `TransferEncoder` for
+ * wire envelope construction — all of which the framework's
+ * `createServerSharedModule` binds by default.
+ *
+ * **No per-head shared module.** The data-server head does not surface a
+ * `createDataServerSharedModule` factory because it contributes no
+ * shared-tier bindings: it reads exclusively from
+ * {@link ServerSharedServices}. An empty factory would only mislead
+ * adopters into composing it as though it were the canonical adoption
+ * path.
+ */
+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>;
+    /**
+     * 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'>>;
+    protected readonly options: ResolvedDataServerOptions;
+    /** Subscription bookkeeping: URI → set of clientIds that subscribed for that URI. */
+    protected readonly subscriptions: Map<string, Set<string>>;
+    /**
+     * 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.
+     */
+    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'`, 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;
+    /** Set once {@link dispose} has run, so a capture that starts after teardown is stopped instead of leaked. */
+    protected disposed: boolean;
+    /** 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>;
+    /**
+     * 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`.
+     */
+    protected readonly modelService: ModelService<AstNode, unknown, TTransfer>;
+    constructor(connection: MessageConnection, services: ServerSharedServices<TProject>, 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>>;
+    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>>;
+    /**
+     * 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 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.
+     */
+    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.
+     */
+    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
+     * `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`)
+     * means that when an adopter strengthens document identity — e.g.
+     * real-path (symlink) resolution — the data-server head's keys track
+     * it too, instead of carrying the same path-identity divergence the
+     * LSP head resolves.
+     *
+     * Adopters can still override for head-specific URI policy by subclassing.
+     */
+    protected canonicalKey(uri: string): string;
+    getProjects(): Promise<readonly TProject[]>;
+    getProjectForUri(args: GetProjectForUriArgs): Promise<TProject | undefined>;
+    /**
+     * Resolve once the data-server is ready to serve requests. Delegates
+     * to {@link ModelService.ready} so adopters that warm-load services
+     * (workspace indexing, etc.) override the `ModelService` slot in
+     * their shared module rather than this method on a DataServer
+     * subclass.
+     */
+    waitForReady(): Promise<void>;
+    findReferenceCandidates(ctx: ReferenceContext): Promise<ReferenceCandidate[]>;
+    resolveReference(ref: ReferenceRequest): Promise<ReferenceTarget<TTransfer> | undefined>;
+    findNextName(args: FindNextNameArgs): Promise<string>;
+    /**
+     * Resolve the per-language `references` services for a reference source.
+     * Delegates the language choice to {@link resolveReferenceLanguage} and
+     * throws when no language owns the source — the reference heads have no
+     * meaningful empty answer (an empty candidate list reads to the client as
+     * "nothing matches" and hides the misrouting).
+     */
+    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`.
+     *
+     * 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.
+     */
+    protected resolveReferenceLanguageByType(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
+     * name the `NameProvider` wrote into the index, and the optional `type`
+     * 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.
+     *
+     * 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.
+     */
+    protected findElementDocumentUri(source: ElementSource): URI | undefined;
+    /**
+     * Language to serve reference queries whose source names no language of
+     * its own — a synthetic source addressing a URI with no (or an
+     * unregistered) extension, or an element id absent from the index.
+     *
+     * Returns `undefined` by default, which makes
+     * {@link resolveReferenceServices} throw. Only reachable in a
+     * multi-language workspace, where choosing among the registered languages
+     * is adopter policy: override and return the language such sources belong
+     * to.
+     */
+    protected fallbackReferenceLanguage(_source: ReferenceSource): HydraniumLanguageServices | undefined;
+    /**
+     * 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.
+     */
+    protected envelope(uri: URI): TransferDocument<TTransfer, TDiagnostic>;
+    /**
+     * 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.
+     */
+    protected subscribeToDocumentBuilder(): 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`.
+     *
+     * Architectural symmetry with {@link subscribeToDocumentBuilder}: 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
+     * LSP-driven save then lands on disk without notifying the subscribed
+     * 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;
+    /** Fan out a save event for the document's URI, gated by the subscription map. */
+    protected dispatchSaveEvent(event: ClientTextDocumentChangeEvent<TextDocument>): void;
+    /**
+     * Fan out a phase event for the document's URI by calling
+     * `clientProxy.onDocumentUpdated`. The proxy lowers the call to a
+     * `data-server/onDocumentUpdated` wire notification; the paired client
+     * (bound via the client `createRpcProxy`'s `localTarget`/`localMethods`)
+     * routes it to its handler. Adopters fan a single inbound onDocumentUpdated
+     * 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.
+     *
+     * 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 `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
+     * `ProjectChangeEvent` carries arrays of added/updated ids plus a
+     * removed list of `{ id, snapshot }` pairs; each affected project
+     * emits one wire `onProjectsChanged` event so clients react
+     * one-at-a-time without walking arrays. `'removed'` dispatches carry
+     * the pre-removal snapshot bundled in
+     * {@link ProjectChangeEvent.removed} because the registry entry is
+     * already gone by the time the event fires.
+     *
+     * Adopters that warm-load services may want to defer this subscription
+     * until {@link waitForReady} resolves (to avoid replaying the initial
+     * discovery as a burst of `'added'` events). Override
+     * {@link subscribeToProjectManager} on the subclass to gate.
+     */
+    protected subscribeToProjectManager(): void;
+    /**
+     * 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.
+     */
+    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>;
+    startProfiling(args: StartProfilingArgs): Promise<void>;
+    stopProfiling(args: StopProfilingArgs): Promise<string>;
+    getLatency(): Promise<LatencyReport>;
+    /** Resolve a partial options object into a fully-defaulted form. */
+    protected resolveOptions(partial: DataServerOptions): ResolvedDataServerOptions;
+}
+export {};
+//# sourceMappingURL=data-server.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"data-server.d.ts","sourceRoot":"","sources":["../src/data-server.ts"],"names":[],"mappings":"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"}