@hydranium/protocol 1.0.0-next.10

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

@@ -0,0 +1,264 @@
+/********************************************************************************
+ * 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 type { TransferDiagnostic } from '../transfer-diagnostic';
+import type { TransferElement } from '../transfer-element';
+import type { Project } from '../project';
+import type { TransferDocument } from '../transfer-document';
+import type { CloseModelArgs, FindNextNameArgs, OpenModelArgs, ReferenceContext, ReferenceRequest } from '../model-server';
+import type { ReferenceCandidate, ReferenceTarget } from '../model-service/reference-candidate';
+import type { ProjectsChangedEvent, TransferDocumentSavedEvent, TransferDocumentUpdatedEvent } from './events';
+import type { GetModelDocumentArgs, GetProjectForUriArgs, TransferSaveDocumentArgs, WatchModelDocumentArgs, TransferUpdateDocumentArgs } from './requests';
+/**
+ * Document-scoped slice of the data-server wire contract: the per-document
+ * lifecycle (get / update / save), the per-`(uri, clientId)` watch
+ * pair, and the global `waitForReady` startup gate that callers await before
+ * the first document request.
+ *
+ * Generic over the transfer root type (`TTransfer`) and the diagnostic
+ * shape (`TDiagnostic`). `TTransfer extends TransferElement` constrains the
+ * root to the wire data shape (no `$container` cycles, references as
+ * strings — see `transfer-element.ts`) — the type-system bridge between the
+ * data-server's protocol surface and the transfer-model overlay each adopter
+ * declares.
+ *
+ * Composed into {@link DataServerProtocol} alongside {@link ProjectServerProtocol};
+ * a pure single-document consumer can compose only this fragment.
+ */
+export interface DocumentServerProtocol<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic> {
+    /**
+     * Open a document for an editor session and return its current state.
+     * Registers `(uri, clientId)` with the multi-client document manager
+     * (so concurrent editors share one built document) and returns the
+     * document at the server's configured target phase — the same shape
+     * {@link getModelDocument} returns, except that `version` is taken from
+     * the text-document store so the caller's first `baseVersion` write
+     * cannot self-conflict. Idempotent in registration terms: opening an
+     * already-open document refreshes the client registration. Note it does
+     * NOT avoid a rebuild — a second client attaching triggers
+     * `refreshContent`, which fires a change event, so mounting a form on a
+     * document already open in a text editor rebuilds it.
+     *
+     * The default `DataServer` impl delegates to `ModelService.open` then
+     * reads the built state. Pair with {@link watchModelDocument} to receive
+     * subsequent build-phase events (open returns a one-shot snapshot;
+     * later validation diagnostics arrive on the watch channel).
+     */
+    openModelDocument(args: OpenModelArgs): Promise<TransferDocument<TTransfer, TDiagnostic>>;
+    /**
+     * Close an editor session for `(uri, clientId)`. Counterpart to
+     * {@link openModelDocument}; the underlying document stays built until
+     * every registered client has closed. The default `DataServer` impl
+     * delegates to `ModelService.close` and ALSO releases any watch for the
+     * same `(uri, clientId)` (closing a session frees its own watch — a
+     * forgotten {@link unwatchModelDocument} would otherwise leak dispatch;
+     * the implicit unwatch is idempotent). `watchModelDocument` is NOT
+     * coupled the other way: opening does not force a watch, so a snapshot
+     * reader can open without streaming.
+     */
+    closeModelDocument(args: CloseModelArgs): Promise<void>;
+    /**
+     * Get the current state of a document. The server-side build is brought
+     * up to date before the response returns — callers don't need to await
+     * a separate "ready" gate per request, only the global
+     * {@link waitForReady} gate at startup.
+     */
+    getModelDocument(args: GetModelDocumentArgs): Promise<TransferDocument<TTransfer, TDiagnostic>>;
+    /**
+     * Update a document's content. The response carries the latest built
+     * state including diagnostics; callers observe convergence via that
+     * response.
+     */
+    updateModelDocument(args: TransferUpdateDocumentArgs<TTransfer>): Promise<TransferDocument<TTransfer, TDiagnostic>>;
+    /**
+     * Persist a document to disk. The response is the post-save document
+     * state (matches the file on disk). Save semantics depend on the
+     * filesystem-provider wiring; rejection paths surface as awaited
+     * promise rejections.
+     */
+    saveModelDocument(args: TransferSaveDocumentArgs<TTransfer>): Promise<TransferDocument<TTransfer, TDiagnostic>>;
+    /**
+     * Start watching `(uri, clientId)`. The server starts dispatching
+     * {@link DocumentClientProtocol.onDocumentUpdated} on the paired wire
+     * for every build-phase event on `uri`.
+     *
+     * Returns `Promise<void>` — the bidirectional pattern means the event
+     * channel is the client interface, not a returned handle. Callers fan
+     * out a single inbound `onDocumentUpdated` to multiple local listeners
+     * with their own `Emitter<T>` (matching Theia's pattern). Pair every
+     * `watchModelDocument` with {@link unwatchModelDocument} when no longer
+     * needed; the server holds the watch record until the matching unwatch
+     * lands.
+     */
+    watchModelDocument(args: WatchModelDocumentArgs): Promise<void>;
+    /**
+     * Stop watching `(uri, clientId)` previously started by
+     * {@link watchModelDocument}. Idempotent — unwatching twice is a no-op.
+     */
+    unwatchModelDocument(args: WatchModelDocumentArgs): Promise<void>;
+    /**
+     * Resolve once the data-server is ready to serve requests. The default
+     * implementation in `DataServer` returns `Promise.resolve()`; adopters
+     * that need to warm-load services (workspace indexing, custom service
+     * initialisation) override this hook on their subclass.
+     *
+     * Callers SHOULD await `waitForReady` once at startup before the first
+     * `getModelDocument` / subscription call — Langium's document builder
+     * may otherwise miss documents added during the initial workspace
+     * walk.
+     */
+    waitForReady(): Promise<void>;
+}
+/**
+ * Project-scoped slice of the data-server wire contract: enumerate the
+ * workspace's projects and resolve the project owning a URI.
+ *
+ * Generic over the project shape (`TProject`); most adopters use the
+ * default {@link Project}. Composed into {@link DataServerProtocol}
+ * alongside {@link DocumentServerProtocol}.
+ */
+export interface ProjectServerProtocol<TProject extends Project = Project> {
+    /**
+     * List projects exposed by the workspace. Returns an empty array when
+     * no project tier is wired (e.g. `SingleProjectManager` default with no
+     * descriptor discovery configured).
+     */
+    getProjects(): Promise<readonly TProject[]>;
+    /**
+     * Look up the project owning the given URI. Returns `undefined` when
+     * the URI does not belong to any registered project, or when no
+     * project tier is wired (the `SingleProjectManager` default returns
+     * its synthetic workspace project for every URI, so that case never
+     * resolves to `undefined`).
+     *
+     * Membership semantics are decided by the server's `ProjectManager`
+     * implementation — the default in `AbstractProjectManager` is closest-
+     * ancestor descriptor folder; adopters override for explicit URI
+     * listings, glob patterns, manifest-declared file lists, etc.
+     */
+    getProjectForUri(args: GetProjectForUriArgs): Promise<TProject | undefined>;
+}
+/**
+ * Typed RPC contract for the data-server protocol head — the server-exposed
+ * surface clients call. Composed from the role-explicit fragments
+ * {@link DocumentServerProtocol} (per-document lifecycle + subscriptions +
+ * the readiness gate) and {@link ProjectServerProtocol} (project tier).
+ * Implementations live in `@hydranium/data-server`; typed client proxies are
+ * produced by `createRpcProxy` (in this package's `./rpc` subpath). The
+ * wire-level method names are `DATA_SERVER_WIRE_PREFIX + methodName` for
+ * every method in `DATA_SERVER_PROTOCOL_METHODS` (request methods)
+ * and `DATA_CLIENT_PROTOCOL_METHODS` (notification methods).
+ *
+ * Most adopters parameterise only `TTransfer`; `TDiagnostic` defaults to
+ * {@link TransferDiagnostic} and `TProject` to {@link Project}.
+ *
+ * **Bidirectional pattern.** `DataServerProtocol` is the SERVER-EXPOSED
+ * surface — methods the client calls. The dual surface
+ * {@link DataClientProtocol} contains methods the server calls (delivered
+ * as JSON-RPC notifications). The pair composes via `createRpcProxy`
+ * (`localTarget`/`localMethods`) so server and client are typed end-to-end
+ * with no method-list drift.
+ *
+ * **Architectural placement.** The SOLE typed surface for the data-server
+ * peer. `lsp-server` and `glsp-server` define their own peer-equivalent
+ * surfaces and DO NOT extend this one; all three heads sit at the same tier,
+ * coordinating through shared services in `@hydranium/core`.
+ */
+export interface DataServerProtocol<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic, TProject extends Project = Project> extends DocumentServerProtocol<TTransfer, TDiagnostic>, ProjectServerProtocol<TProject> {
+}
+/**
+ * Cross-reference / naming slice of the server surface — scope-aware
+ * queries that resolve against the language's reference services. NOT part
+ * of the {@link DataServerProtocol} composition: a pure data consumer
+ * doesn't need it, so adopters compose it onto their connection explicitly.
+ * The default `DataServer` impls delegate to
+ * the per-language `references` services, resolved from each request's
+ * source/URI (an `ElementSource` with no URI resolves to the sole
+ * registered language; a multi-language workspace overrides).
+ *
+ * Generic over the transfer root type only — the resolution result
+ * ({@link ReferenceTarget}) carries the resolved node's encoded subtree;
+ * candidates and names are diagnostic-free.
+ */
+export interface ReferenceServerProtocol<TTransfer extends TransferElement> {
+    /**
+     * List the reference candidates reachable for the property named in `ctx`
+     * from its (possibly synthetic) source. Backed by the language's
+     * `ReferenceCandidateProvider`.
+     */
+    findReferenceCandidates(ctx: ReferenceContext): Promise<ReferenceCandidate[]>;
+    /**
+     * Resolve a concrete reference request to its target, returning the
+     * target's document URI, display fields, and the resolved node's encoded
+     * transfer subtree. Resolves via the language's reference services;
+     * `undefined` when the reference does not resolve.
+     */
+    resolveReference(ref: ReferenceRequest): Promise<ReferenceTarget<TTransfer> | undefined>;
+    /**
+     * Compute the next free name for a new element of `args.type` based on
+     * `args.proposal`, unique within the `args.tier` scope (default
+     * `'project'`). Backed by the language's `NameProvider`.
+     */
+    findNextName(args: FindNextNameArgs): Promise<string>;
+}
+/**
+ * Document-scoped slice of the client surface — notifications the server
+ * delivers about subscribed documents. The dual of
+ * {@link DocumentServerProtocol}.
+ *
+ * Notification methods are conventionally `on*`-prefixed so the generic
+ * `createRpcProxy` helper routes them as `sendNotification` calls.
+ * Multi-listener fan-out is the consumer's responsibility — wrap a local
+ * implementation with an `Emitter<T>` to fan a single inbound
+ * `onDocumentUpdated` call out to multiple local subscribers.
+ */
+export interface DocumentClientProtocol<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic> {
+    /**
+     * Delivered when a subscribed document reached one of the data-server's
+     * configured build phases. Subscribers filter incoming events by URI
+     * if they hold multiple subscriptions on the same wire.
+     */
+    onDocumentUpdated(event: TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>): void;
+    /**
+     * Delivered when a subscribed document was persisted to disk via
+     * {@link DocumentServerProtocol.saveModelDocument}. The persistence event
+     * is delivered on a separate channel from the build-phase update
+     * stream — subscribers tracking "saved" status (editor dirty-flag
+     * indicators, external sync drivers) listen here instead of filtering
+     * `onDocumentUpdated` for `reason: 'saved'` (the build-phase path
+     * never emits `'saved'` because saves take a synchronous RPC-response
+     * codepath, not a subscription codepath).
+     */
+    onDocumentSaved(event: TransferDocumentSavedEvent<TTransfer, TDiagnostic>): void;
+}
+/**
+ * Project-scoped slice of the client surface — the project-registry change
+ * notification. The dual of {@link ProjectServerProtocol}.
+ */
+export interface ProjectClientProtocol<TProject extends Project = Project> {
+    /**
+     * Delivered when a project was added, updated, or removed from the
+     * registry. The data-server subscribes to its `ProjectManager`'s
+     * change channel and fans the internal `ProjectChangeEvent` (which
+     * carries arrays of added/updated/removed ids per registry diff) out
+     * to one wire notification per affected project — `'removed'` events
+     * carry the pre-removal snapshot so clients with no local cache can
+     * still read the project's metadata.
+     */
+    onProjectsChanged(event: ProjectsChangedEvent<TProject>): void;
+}
+/**
+ * Client-side surface — methods the data-server invokes on the client as
+ * JSON-RPC notifications. The bidirectional dual of {@link DataServerProtocol},
+ * composed from {@link DocumentClientProtocol} and {@link ProjectClientProtocol}.
+ * A `createRpcProxy` over the connection exposes the server surface outbound and
+ * binds an implementation of this interface inbound (`localTarget`).
+ */
+export interface DataClientProtocol<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic, TProject extends Project = Project> extends DocumentClientProtocol<TTransfer, TDiagnostic>, ProjectClientProtocol<TProject> {
+}
+//# sourceMappingURL=data-server-protocol.d.ts.map

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

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

package/lib/data/data-server-protocol.js

@@ -0,0 +1,11 @@
+"use strict";
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=data-server-protocol.js.map

package/lib/data/data-server-protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-server-protocol.js","sourceRoot":"","sources":["../../src/data/data-server-protocol.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF"}

package/lib/data/diagnostics.d.ts

@@ -0,0 +1,97 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * Optional diagnostics slice of the data-server wire contract: capture memory /
+ * state snapshots of the running server process for OOM debugging (notably in a
+ * cloud pod). Kept OUT of `DataServerProtocol` so the core document /
+ * project contract stays lean, but the framework `DataServer` registers these
+ * BY DEFAULT (so every head gets them with no wiring); a head that does not want
+ * them drops the names via `DataServerOptions.excludedMethods`.
+ *
+ * Returns are plain formatted strings — the caller (a command, a log sink, the
+ * pod's stdout) decides how to surface them. The wire names are
+ * `DATA_SERVER_WIRE_PREFIX + methodName`, same as the core methods.
+ */
+import type { LatencyReport } from '../latency-collector.js';
+import type { ProfileCaptureOptions } from '../profiling.js';
+/** Arguments for {@link DataServerDiagnosticsProtocol.dumpServerState}. */
+export interface DumpServerStateArgs {
+    /** Optional label folded into the snapshot heading (e.g. an ISO timestamp). */
+    label?: string;
+}
+/**
+ * Arguments for {@link DataServerDiagnosticsProtocol.startProfiling} — the capture
+ * dimensions to sample over the window (all off unless named). The wire args are
+ * exactly the neutral {@link ProfileCaptureOptions}.
+ */
+export type StartProfilingArgs = ProfileCaptureOptions;
+/** Arguments for {@link DataServerDiagnosticsProtocol.stopProfiling}. */
+export interface StopProfilingArgs {
+    /** Optional label folded into the profile filenames + report heading. */
+    label?: string;
+    /** Directory to write profile artefacts into; defaults to the OS temp dir when absent or not present on disk. */
+    directory?: string;
+}
+/** Arguments for {@link DataServerDiagnosticsProtocol.writeHeapSnapshot}. */
+export interface WriteServerHeapSnapshotArgs {
+    /** Optional label folded into the snapshot filename. */
+    label?: string;
+    /** Directory to write into; defaults to the OS temp dir when absent or not present on disk. */
+    directory?: string;
+}
+/**
+ * Memory / state diagnostics the running server process exposes. Implemented by
+ * the framework `DataServer`; computed in the data-server process (the heavy
+ * model store), so the snapshots reflect the process that actually holds the
+ * workspace AST/CST — the one that OOMs.
+ */
+export interface DataServerDiagnosticsProtocol {
+    /**
+     * Capture a server-process state snapshot — heap, rss, V8 stats, event-loop
+     * utilisation, CPU usage, and document counts — and return it formatted.
+     */
+    dumpServerState(args: DumpServerStateArgs): Promise<string>;
+    /**
+     * Write a V8 heap snapshot of the server process to disk (full GC first;
+     * briefly pauses the process) and return the absolute file path. Open it in
+     * Chrome DevTools > Memory > Load for retained-size analysis.
+     */
+    writeHeapSnapshot(args: WriteServerHeapSnapshotArgs): Promise<string>;
+    /**
+     * Capture a pod/container memory snapshot — cgroup v2/v1 current/peak/limit
+     * plus a per-process RSS tree, the figure the Kubernetes OOM-killer watches.
+     * Degrades to a "no cgroup controller" note outside a container.
+     */
+    dumpPodMemory(): Promise<string>;
+    /**
+     * Begin a windowed sampled-profile capture (CPU / allocation / GC / event-loop
+     * delay, per the named dimensions) of the server process. Sampling does NOT
+     * pause the process. Rejects if a capture is already active — one inspector
+     * session at a time. Pair with {@link stopProfiling}.
+     */
+    startProfiling(args: StartProfilingArgs): Promise<void>;
+    /**
+     * Stop the active capture, write the requested profile artefacts, and return
+     * the formatted profile report. Rejects if no capture is active.
+     */
+    stopProfiling(args: StopProfilingArgs): Promise<string>;
+    /**
+     * Return the per-method RPC/LSP latency + throughput collected so far (count,
+     * p50/p99/max, total per method). Empty when the head was not started with a
+     * latency collector. Read-only — does not reset the window.
+     */
+    getLatency(): Promise<LatencyReport>;
+}
+/**
+ * Request-method names on {@link DataServerDiagnosticsProtocol}. The framework
+ * `DataServer` appends these to its registered method set by default; the
+ * `as const satisfies` constraint keeps the array in lockstep with the interface.
+ */
+export declare const DATA_SERVER_DIAGNOSTICS_METHODS: readonly ["dumpServerState", "writeHeapSnapshot", "dumpPodMemory", "startProfiling", "stopProfiling", "getLatency"];
+//# sourceMappingURL=diagnostics.d.ts.map

package/lib/data/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../src/data/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAE7D,2EAA2E;AAC3E,MAAM,WAAW,mBAAmB;IACjC,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,qBAAqB,CAAC;AAEvD,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAC/B,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iHAAiH;IACjH,SAAS,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,6EAA6E;AAC7E,MAAM,WAAW,2BAA2B;IACzC,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+FAA+F;IAC/F,SAAS,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,6BAA6B;IAC3C;;;OAGG;IACH,eAAe,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE5D;;;;OAIG;IACH,iBAAiB,CAAC,IAAI,EAAE,2BAA2B,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEtE;;;;OAIG;IACH,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAEjC;;;;;OAKG;IACH,cAAc,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExD;;;OAGG;IACH,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAExD;;;;OAIG;IACH,UAAU,IAAI,OAAO,CAAC,aAAa,CAAC,CAAC;CACvC;AAED;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,qHAOoC,CAAC"}

package/lib/data/diagnostics.js

@@ -0,0 +1,25 @@
+"use strict";
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DATA_SERVER_DIAGNOSTICS_METHODS = void 0;
+/**
+ * Request-method names on {@link DataServerDiagnosticsProtocol}. The framework
+ * `DataServer` appends these to its registered method set by default; the
+ * `as const satisfies` constraint keeps the array in lockstep with the interface.
+ */
+exports.DATA_SERVER_DIAGNOSTICS_METHODS = [
+    'dumpServerState',
+    'writeHeapSnapshot',
+    'dumpPodMemory',
+    'startProfiling',
+    'stopProfiling',
+    'getLatency'
+];
+//# sourceMappingURL=diagnostics.js.map

package/lib/data/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/data/diagnostics.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAgGlF;;;;GAIG;AACU,QAAA,+BAA+B,GAAG;IAC5C,iBAAiB;IACjB,mBAAmB;IACnB,eAAe;IACf,gBAAgB;IAChB,eAAe;IACf,YAAY;CACiE,CAAC"}

package/lib/data/events.d.ts

@@ -0,0 +1,107 @@
+/********************************************************************************
+ * 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 type { TransferDiagnostic } from '../transfer-diagnostic';
+import type { TransferElement } from '../transfer-element';
+import type { Project } from '../project';
+import type { TransferDocument } from '../transfer-document';
+/**
+ * Why an update event fired. Subscribers filter on reason for behaviour
+ * decisions (e.g. dirty-flag handling, undo-history grouping, telemetry):
+ *
+ * - `'changed'` — the URI appeared in `DocumentBuilder.onUpdate`'s
+ *   `changed` list. The framework's underlying primitive is "this URI was
+ *   passed to `documentBuilder.update(changed, deleted)`", which spans
+ *   `didChange` text-document events, `notifyDidChangeTextDocument` calls,
+ *   and any programmatic `documentBuilder.update([uri], [])` invocation.
+ *   The name matches Langium's own `changed` parameter — it's vague-on-
+ *   purpose because the underlying primitive is.
+ * - `'rebuilt'` — the URI was rebuilt as a cascade from another URI's
+ *   build (dependency graph re-derivation), without itself being passed to
+ *   `documentBuilder.update`. The complement of `'changed'`.
+ * - `'saved'` — emitted by adopters that synthesise a unified update stream
+ *   from both `onDocumentUpdated` and `onDocumentSaved`. The framework's own
+ *   `dispatchPhaseEvent` does NOT emit `'saved'` — saves take the dedicated
+ *   `DataClientProtocol.onDocumentSaved` channel.
+ * - `'deleted'` — the URI appeared in `DocumentBuilder.onUpdate`'s
+ *   `deleted` list. The backing file was removed.
+ */
+export type TransferDocumentUpdateReason = 'changed' | 'rebuilt' | 'saved' | 'deleted';
+/**
+ * Delivered on the data-server when a document's content (or existence)
+ * changed. Subscribers receive this via `DocumentServerProtocol.watchModelDocument`.
+ *
+ * The `document` field carries the latest built state — diagnostics + root
+ * are coherent with each other at the time the event fired.
+ */
+export interface TransferDocumentUpdatedEvent<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic> {
+    document: TransferDocument<TTransfer, TDiagnostic>;
+    /** Stable identifier of the client that triggered the update. */
+    sourceClientId: string;
+    reason: TransferDocumentUpdateReason;
+}
+/** Callback shape for `DataClientProtocol.onDocumentUpdated`. */
+export type TransferDocumentUpdatedListener<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic> = (event: TransferDocumentUpdatedEvent<TTransfer, TDiagnostic>) => void;
+/**
+ * Delivered on the data-server when a document was persisted to disk via
+ * `DataServerProtocol.saveModelDocument`. Distinct from
+ * {@link TransferDocumentUpdatedEvent}: subscribers that only care about
+ * persistence (external sync, editor "saved" indicators, dirty-flag
+ * clear) listen for this event family instead of filtering an update
+ * stream for `reason: 'saved'`.
+ *
+ * The `document` field carries the post-save built state — same shape
+ * the synchronous `saveModelDocument` RPC response returns, delivered
+ * to subscribers (`DataClientProtocol.onDocumentSaved`) so non-caller
+ * clients see the persistence event too.
+ */
+export interface TransferDocumentSavedEvent<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic> {
+    document: TransferDocument<TTransfer, TDiagnostic>;
+    /**
+     * The client whose `saveModelDocument` call produced this. Every subscriber
+     * receives the event including the originator, which already had the same
+     * state as the RPC response — compare against your own id to drop the echo
+     * rather than re-rendering from it.
+     */
+    sourceClientId: string;
+}
+/** Callback shape for `DataClientProtocol.onDocumentSaved`. */
+export type TransferDocumentSavedListener<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic> = (event: TransferDocumentSavedEvent<TTransfer, TDiagnostic>) => void;
+/**
+ * Why a project-change event fired. `added` — the project was newly
+ * registered (descriptor discovered); `updated` — the project's
+ * descriptor content changed and its registry entry was refreshed
+ * (same id, possibly different version / dependencies / adopter-specific
+ * fields); `removed` — the project's descriptor disappeared and the
+ * registry entry was dropped.
+ */
+export type ProjectChangeReason = 'added' | 'updated' | 'removed';
+/**
+ * Delivered on the data-server when a project's lifecycle state changed
+ * (added / updated / removed in the registry). Subscribers receive this
+ * via `DataClientProtocol.onProjectsChanged`.
+ *
+ * Granularity is one event per affected project: an internal registry
+ * diff with three additions and one removal fans out to four wire
+ * notifications. This matches the typical client-side pattern of "react
+ * to one project at a time" (refresh a tree entry, update a tab badge,
+ * etc.) without forcing clients to walk arrays.
+ *
+ * For `reason: 'removed'`, the carried {@link project} is the pre-removal
+ * snapshot — by the time the event fires, the registry has already
+ * cleared the entry, so clients that need the removed project's metadata
+ * (id, version, dependencies, adopter-specific fields) read it here
+ * instead of maintaining their own snapshot.
+ */
+export interface ProjectsChangedEvent<TProject extends Project = Project> {
+    readonly project: TProject;
+    readonly reason: ProjectChangeReason;
+}
+/** Callback shape for `DataClientProtocol.onProjectsChanged`. */
+export type ProjectsChangedListener<TProject extends Project = Project> = (event: ProjectsChangedEvent<TProject>) => void;
+//# sourceMappingURL=events.d.ts.map

package/lib/data/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/data/events.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,4BAA4B,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AAEvF;;;;;;GAMG;AACH,MAAM,WAAW,4BAA4B,CAC1C,SAAS,SAAS,eAAe,EACjC,WAAW,SAAS,kBAAkB,GAAG,kBAAkB;IAE3D,QAAQ,EAAE,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IACnD,iEAAiE;IACjE,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,4BAA4B,CAAC;CACvC;AAED,iEAAiE;AACjE,MAAM,MAAM,+BAA+B,CACxC,SAAS,SAAS,eAAe,EACjC,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,IAC1D,CAAC,KAAK,EAAE,4BAA4B,CAAC,SAAS,EAAE,WAAW,CAAC,KAAK,IAAI,CAAC;AAE1E;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,0BAA0B,CACxC,SAAS,SAAS,eAAe,EACjC,WAAW,SAAS,kBAAkB,GAAG,kBAAkB;IAE3D,QAAQ,EAAE,gBAAgB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IACnD;;;;;OAKG;IACH,cAAc,EAAE,MAAM,CAAC;CACzB;AAED,+DAA+D;AAC/D,MAAM,MAAM,6BAA6B,CACtC,SAAS,SAAS,eAAe,EACjC,WAAW,SAAS,kBAAkB,GAAG,kBAAkB,IAC1D,CAAC,KAAK,EAAE,0BAA0B,CAAC,SAAS,EAAE,WAAW,CAAC,KAAK,IAAI,CAAC;AAExE;;;;;;;GAOG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;AAElE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,oBAAoB,CAAC,QAAQ,SAAS,OAAO,GAAG,OAAO;IACrE,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;CACvC;AAED,iEAAiE;AACjE,MAAM,MAAM,uBAAuB,CAAC,QAAQ,SAAS,OAAO,GAAG,OAAO,IAAI,CAAC,KAAK,EAAE,oBAAoB,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC"}

package/lib/data/events.js

@@ -0,0 +1,11 @@
+"use strict";
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=events.js.map

package/lib/data/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/data/events.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF"}

package/lib/data/index.d.ts

@@ -0,0 +1,15 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+export * from './data-protocol-methods';
+export * from './data-server-protocol';
+export * from './diagnostics';
+export * from './events';
+export * from './methods';
+export * from './requests';
+//# sourceMappingURL=index.d.ts.map

package/lib/data/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/data/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAUlF,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC"}

package/lib/data/index.js

@@ -0,0 +1,38 @@
+"use strict";
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Subpath barrel for `@hydranium/protocol/data` — typed bidirectional
+// contract for the data-server protocol head, split into composable
+// `*ServerProtocol` / `*ClientProtocol` fragments. Implementations live in
+// `@hydranium/data-server`; typed proxies are produced by the
+// direction-neutral `createRpcProxy` (in `../rpc`) with the data-server
+// method-name lists + wire prefix exported here from
+// `./data-protocol-methods.ts`.
+__exportStar(require("./data-protocol-methods"), exports);
+__exportStar(require("./data-server-protocol"), exports);
+__exportStar(require("./diagnostics"), exports);
+__exportStar(require("./events"), exports);
+__exportStar(require("./methods"), exports);
+__exportStar(require("./requests"), exports);
+//# sourceMappingURL=index.js.map

package/lib/data/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/data/index.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;;;;;;;;;;;;;;AAElF,sEAAsE;AACtE,oEAAoE;AACpE,2EAA2E;AAC3E,8DAA8D;AAC9D,wEAAwE;AACxE,qDAAqD;AACrD,gCAAgC;AAEhC,0DAAwC;AACxC,yDAAuC;AACvC,gDAA8B;AAC9B,2CAAyB;AACzB,4CAA0B;AAC1B,6CAA2B"}