@hydranium/protocol 1.0.0-next.10

package/lib/data/methods.d.ts

@@ -0,0 +1,57 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * The shared path identifier under which the data-server exposes its typed
+ * RPC methods. Production adopters using vscode-jsonrpc transports use this
+ * as the connection-builder path; the data-server side uses it when
+ * registering handlers.
+ *
+ * Distinct from the LSP (`languageId`-routed) and GLSP (`diagram-type`-routed)
+ * heads — each protocol head owns its own path namespace.
+ */
+export declare const DATA_SERVER_PATH = "/hydranium/data-server";
+/**
+ * Wire-name prefix used by `createRpcProxy` and `DataServer`'s
+ * handler binding. Every property name on the typed `DataServerProtocol`
+ * (or `DataClientProtocol`) interface lowers to `<prefix><methodName>` on
+ * the wire — so renaming a TS method renames the wire method,
+ * intentionally.
+ *
+ * Adopters writing custom transports or inspecting the wire derive each
+ * wire name as `DATA_SERVER_WIRE_PREFIX + methodName`, where the method
+ * names live in `DATA_SERVER_PROTOCOL_METHODS` (request methods) and
+ * `DATA_CLIENT_PROTOCOL_METHODS` (notification methods), both exported
+ * from `./data-protocol-methods`. The interface (`DataServerProtocol`,
+ * `DataClientProtocol`) is the source of truth; the method-name arrays
+ * are typed against the interface (`as const satisfies …`) so they
+ * cannot drift.
+ */
+export declare const DATA_SERVER_WIRE_PREFIX = "data-server/";
+/**
+ * Default LSP command id under which a data-server publishes its listening
+ * TCP port for client discovery. Parallel to {@link DATA_SERVER_PATH} (the
+ * service-path routing constant) — both name the data-server head's transport
+ * surface so a simple adopter needs no constants of its own.
+ *
+ * Two ends reference this id:
+ * - PUBLISH (server): the launcher registers the port under this command on
+ *   the LSP connection —
+ *   `publishPortOnLspConnection(conn, DATA_SERVER_PORT_COMMAND, port)`.
+ *   `@hydranium/core`'s `publishPortOnLspConnection` stays command-agnostic
+ *   (it publishes any port under any command); the adopter passes this
+ *   constant.
+ * - EXTRACT (Theia host): `@hydranium/data-client-theia`'s
+ *   `DataServerConnectionHandler` polls this command to discover the port —
+ *   its `portCommand` option defaults to this value.
+ *
+ * Adopters with an established command id (e.g. `'modelserver:port'`)
+ * override both ends.
+ */
+export declare const DATA_SERVER_PORT_COMMAND = "hydranium/data-server/port";
+//# sourceMappingURL=methods.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"methods.d.ts","sourceRoot":"","sources":["../../src/data/methods.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,2BAA2B,CAAC;AAEzD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,uBAAuB,iBAAiB,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,wBAAwB,+BAA+B,CAAC"}

package/lib/data/methods.js

@@ -0,0 +1,60 @@
+"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_PORT_COMMAND = exports.DATA_SERVER_WIRE_PREFIX = exports.DATA_SERVER_PATH = void 0;
+/**
+ * The shared path identifier under which the data-server exposes its typed
+ * RPC methods. Production adopters using vscode-jsonrpc transports use this
+ * as the connection-builder path; the data-server side uses it when
+ * registering handlers.
+ *
+ * Distinct from the LSP (`languageId`-routed) and GLSP (`diagram-type`-routed)
+ * heads — each protocol head owns its own path namespace.
+ */
+exports.DATA_SERVER_PATH = '/hydranium/data-server';
+/**
+ * Wire-name prefix used by `createRpcProxy` and `DataServer`'s
+ * handler binding. Every property name on the typed `DataServerProtocol`
+ * (or `DataClientProtocol`) interface lowers to `<prefix><methodName>` on
+ * the wire — so renaming a TS method renames the wire method,
+ * intentionally.
+ *
+ * Adopters writing custom transports or inspecting the wire derive each
+ * wire name as `DATA_SERVER_WIRE_PREFIX + methodName`, where the method
+ * names live in `DATA_SERVER_PROTOCOL_METHODS` (request methods) and
+ * `DATA_CLIENT_PROTOCOL_METHODS` (notification methods), both exported
+ * from `./data-protocol-methods`. The interface (`DataServerProtocol`,
+ * `DataClientProtocol`) is the source of truth; the method-name arrays
+ * are typed against the interface (`as const satisfies …`) so they
+ * cannot drift.
+ */
+exports.DATA_SERVER_WIRE_PREFIX = 'data-server/';
+/**
+ * Default LSP command id under which a data-server publishes its listening
+ * TCP port for client discovery. Parallel to {@link DATA_SERVER_PATH} (the
+ * service-path routing constant) — both name the data-server head's transport
+ * surface so a simple adopter needs no constants of its own.
+ *
+ * Two ends reference this id:
+ * - PUBLISH (server): the launcher registers the port under this command on
+ *   the LSP connection —
+ *   `publishPortOnLspConnection(conn, DATA_SERVER_PORT_COMMAND, port)`.
+ *   `@hydranium/core`'s `publishPortOnLspConnection` stays command-agnostic
+ *   (it publishes any port under any command); the adopter passes this
+ *   constant.
+ * - EXTRACT (Theia host): `@hydranium/data-client-theia`'s
+ *   `DataServerConnectionHandler` polls this command to discover the port —
+ *   its `portCommand` option defaults to this value.
+ *
+ * Adopters with an established command id (e.g. `'modelserver:port'`)
+ * override both ends.
+ */
+exports.DATA_SERVER_PORT_COMMAND = 'hydranium/data-server/port';
+//# sourceMappingURL=methods.js.map

package/lib/data/methods.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"methods.js","sourceRoot":"","sources":["../../src/data/methods.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAElF;;;;;;;;GAQG;AACU,QAAA,gBAAgB,GAAG,wBAAwB,CAAC;AAEzD;;;;;;;;;;;;;;;GAeG;AACU,QAAA,uBAAuB,GAAG,cAAc,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;GAmBG;AACU,QAAA,wBAAwB,GAAG,4BAA4B,CAAC"}

package/lib/data/requests.d.ts

@@ -0,0 +1,65 @@
+/********************************************************************************
+ * 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 { TransferSaveArgs, TransferUpdateArgs } from '../model-service/args';
+/** Get the current state of a single document. The server returns the latest built version. */
+export interface GetModelDocumentArgs {
+    /** Document URI. */
+    uri: string;
+    /**
+     * When `true`, the response is settled at the validation phase so its
+     * `diagnostics` are populated. When `false`/absent, the response returns at
+     * the (faster) integrity-settled phase and `diagnostics` may be absent —
+     * they are computed asynchronously and delivered via the subscription
+     * channel (and, for an LSP head, `publishDiagnostics`).
+     *
+     * Set this for one-shot / unsubscribed callers (CLI queries, batch checks)
+     * that need diagnostics in the response itself. Mirrors Langium's
+     * `BuildOptions.validation: boolean`. Note it does not *strip* diagnostics:
+     * a document already validated still carries them; the flag only controls
+     * whether the read forces/awaits validation.
+     */
+    includeDiagnostics?: boolean;
+}
+/**
+ * Look up the project owning the given document URI. Membership semantics
+ * are decided by the server's `ProjectManager` (default in
+ * `AbstractProjectManager`: closest-ancestor descriptor folder); the data-
+ * server forwards the URI without interpretation.
+ */
+export interface GetProjectForUriArgs {
+    /** Document URI to look up. */
+    uri: string;
+}
+/**
+ * Update a document's content. Wire-side projection of the facade's
+ * {@link TransferUpdateArgs}; structurally identical so the data-server RPC
+ * handler can forward straight to the in-process `ModelService.update`
+ * without an args mapping.
+ */
+export type TransferUpdateDocumentArgs<TTransfer> = TransferUpdateArgs<TTransfer>;
+/** Persist a document to disk. Wire-side projection of {@link TransferSaveArgs}. */
+export type TransferSaveDocumentArgs<TTransfer> = TransferSaveArgs<TTransfer>;
+/**
+ * Identifies a per-document watch on the data server. Shared by both
+ * `watchModelDocument` and `unwatchModelDocument` — the `(uri, clientId)`
+ * pair is the watch key, so unwatching names the same watch that was
+ * started. The `clientId` identifies the originator the same way it does
+ * on facade-side mutations (`TransferUpdateArgs.clientId`,
+ * `TransferSaveArgs.clientId`): it keys the per-`(uri, clientId)` watch
+ * bucket so multiple watchers on the same wire stay distinct, AND it lets
+ * each watcher recognise its own echo on inbound `onDocumentUpdated` events
+ * (the wire shape's `sourceClientId` carries the originating mutation's
+ * `clientId`).
+ */
+export interface WatchModelDocumentArgs {
+    uri: string;
+    /** Stable identifier for the watching client. */
+    clientId: string;
+}
+//# sourceMappingURL=requests.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"requests.d.ts","sourceRoot":"","sources":["../../src/data/requests.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAElF,+FAA+F;AAC/F,MAAM,WAAW,oBAAoB;IAClC,oBAAoB;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;;;;;OAYG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IAClC,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,MAAM,MAAM,0BAA0B,CAAC,SAAS,IAAI,kBAAkB,CAAC,SAAS,CAAC,CAAC;AAElF,oFAAoF;AACpF,MAAM,MAAM,wBAAwB,CAAC,SAAS,IAAI,gBAAgB,CAAC,SAAS,CAAC,CAAC;AAE9E;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,sBAAsB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;CACnB"}

package/lib/data/requests.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=requests.js.map

package/lib/data/requests.js.map

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

package/lib/debouncer.d.ts

@@ -0,0 +1,75 @@
+/********************************************************************************
+ * 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 Clock } from './clock';
+import { ObservableValue, type MaybeObservableValue } from './observable-value';
+import { type Disposable } from './util';
+/** Construction options for {@link Debouncer}. */
+export interface DebouncerOptions {
+    /**
+     * Trailing-edge delay in milliseconds, read per {@link Debouncer.schedule}
+     * so a setting-bound cell reshapes the live window without rebuilding the
+     * debouncer. A value `<= 0` still defers to the next tick via
+     * {@link Clock.setTimer}; callers wanting a synchronous path handle that
+     * themselves before scheduling.
+     */
+    readonly delayMs: MaybeObservableValue<number>;
+    /**
+     * Optional starvation ceiling. When calls keep arriving faster than
+     * {@link delayMs}, the trailing edge never settles and `fn` would never
+     * run; with `maxWaitMs` set, a fire is forced once that many milliseconds
+     * have elapsed since the first pending {@link Debouncer.schedule}, so a
+     * continuous stream still makes progress. Omitted (the default) = pure
+     * trailing edge, which may defer indefinitely under a non-stop stream.
+     */
+    readonly maxWaitMs?: number;
+}
+/**
+ * Trailing-edge debounce built on the injectable {@link Clock}, so the window
+ * is deterministically testable with `makeFakeClock` — the framework's timer
+ * seam rather than raw `setTimeout` (which `p-debounce` / `lodash.debounce`
+ * hold internally and cannot be driven by a fake clock).
+ *
+ * Owns ONLY timing. {@link fn} is zero-argument and returns nothing: the caller
+ * keeps whatever payload it is coalescing — an accumulator set, a "latest
+ * value" field — and reads it inside `fn` when the debouncer fires. That
+ * timing/payload split is what lets one primitive serve both an accumulating
+ * caller (merge changed/deleted sets) and a replacing one (last value wins).
+ *
+ * Leading-edge invocation and a result-returning ("await the debounced run")
+ * variant are deliberately omitted to keep this a pure timing primitive; both
+ * are additive later (a `leading` option; a separate promise helper) rather
+ * than a breaking change.
+ */
+export declare class Debouncer implements Disposable {
+    protected readonly clock: Clock;
+    protected readonly fn: () => void;
+    protected readonly delay: ObservableValue<number>;
+    protected readonly maxWaitMs?: number;
+    protected timer?: Disposable;
+    /** Virtual time of the first {@link schedule} of the current pending window; drives {@link DebouncerOptions.maxWaitMs}. */
+    protected firstScheduledAt?: number;
+    constructor(clock: Clock, fn: () => void, options: DebouncerOptions);
+    /** True while a fire is armed (scheduled, not yet fired or cancelled). */
+    get pending(): boolean;
+    /**
+     * Arm — or re-arm — the trailing-edge timer. Repeated calls within the
+     * window collapse into a single {@link fn} run at the trailing edge; with
+     * {@link DebouncerOptions.maxWaitMs} set, the run is forced once that ceiling
+     * elapses since the first pending call.
+     */
+    schedule(): void;
+    /** If a fire is pending, run {@link fn} now and clear the window; otherwise a no-op. */
+    flush(): void;
+    /** Drop a pending fire without running {@link fn}. */
+    cancel(): void;
+    /** Cancel any pending fire and release. */
+    dispose(): void;
+    protected fire(): void;
+}
+//# sourceMappingURL=debouncer.d.ts.map

package/lib/debouncer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debouncer.d.ts","sourceRoot":"","sources":["../src/debouncer.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,eAAe,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAChF,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEzC,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAC/C;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,SAAU,YAAW,UAAU;IAQtC,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK;IAC/B,SAAS,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,IAAI;IARpC,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IAClD,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IACtC,SAAS,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC;IAC7B,2HAA2H;IAC3H,SAAS,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;gBAGd,KAAK,EAAE,KAAK,EACZ,EAAE,EAAE,MAAM,IAAI,EACjC,OAAO,EAAE,gBAAgB;IAM5B,0EAA0E;IAC1E,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;;OAKG;IACH,QAAQ,IAAI,IAAI;IAchB,wFAAwF;IACxF,KAAK,IAAI,IAAI;IAMb,sDAAsD;IACtD,MAAM,IAAI,IAAI;IAMd,2CAA2C;IAC3C,OAAO,IAAI,IAAI;IAIf,SAAS,CAAC,IAAI,IAAI,IAAI;CAMxB"}

package/lib/debouncer.js

@@ -0,0 +1,91 @@
+"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.Debouncer = void 0;
+const observable_value_1 = require("./observable-value");
+/**
+ * Trailing-edge debounce built on the injectable {@link Clock}, so the window
+ * is deterministically testable with `makeFakeClock` — the framework's timer
+ * seam rather than raw `setTimeout` (which `p-debounce` / `lodash.debounce`
+ * hold internally and cannot be driven by a fake clock).
+ *
+ * Owns ONLY timing. {@link fn} is zero-argument and returns nothing: the caller
+ * keeps whatever payload it is coalescing — an accumulator set, a "latest
+ * value" field — and reads it inside `fn` when the debouncer fires. That
+ * timing/payload split is what lets one primitive serve both an accumulating
+ * caller (merge changed/deleted sets) and a replacing one (last value wins).
+ *
+ * Leading-edge invocation and a result-returning ("await the debounced run")
+ * variant are deliberately omitted to keep this a pure timing primitive; both
+ * are additive later (a `leading` option; a separate promise helper) rather
+ * than a breaking change.
+ */
+class Debouncer {
+    clock;
+    fn;
+    delay;
+    maxWaitMs;
+    timer;
+    /** Virtual time of the first {@link schedule} of the current pending window; drives {@link DebouncerOptions.maxWaitMs}. */
+    firstScheduledAt;
+    constructor(clock, fn, options) {
+        this.clock = clock;
+        this.fn = fn;
+        this.delay = observable_value_1.ObservableValue.from(options.delayMs);
+        this.maxWaitMs = options.maxWaitMs;
+    }
+    /** True while a fire is armed (scheduled, not yet fired or cancelled). */
+    get pending() {
+        return this.timer !== undefined;
+    }
+    /**
+     * Arm — or re-arm — the trailing-edge timer. Repeated calls within the
+     * window collapse into a single {@link fn} run at the trailing edge; with
+     * {@link DebouncerOptions.maxWaitMs} set, the run is forced once that ceiling
+     * elapses since the first pending call.
+     */
+    schedule() {
+        const now = this.clock.now();
+        if (this.firstScheduledAt === undefined) {
+            this.firstScheduledAt = now;
+        }
+        let wait = Math.max(0, this.delay.value);
+        if (this.maxWaitMs !== undefined) {
+            const untilCeiling = this.firstScheduledAt + this.maxWaitMs - now;
+            wait = Math.min(wait, Math.max(0, untilCeiling));
+        }
+        this.timer?.dispose();
+        this.timer = this.clock.setTimer(() => this.fire(), wait);
+    }
+    /** If a fire is pending, run {@link fn} now and clear the window; otherwise a no-op. */
+    flush() {
+        if (this.timer !== undefined) {
+            this.fire();
+        }
+    }
+    /** Drop a pending fire without running {@link fn}. */
+    cancel() {
+        this.timer?.dispose();
+        this.timer = undefined;
+        this.firstScheduledAt = undefined;
+    }
+    /** Cancel any pending fire and release. */
+    dispose() {
+        this.cancel();
+    }
+    fire() {
+        this.timer?.dispose();
+        this.timer = undefined;
+        this.firstScheduledAt = undefined;
+        this.fn();
+    }
+}
+exports.Debouncer = Debouncer;
+//# sourceMappingURL=debouncer.js.map

package/lib/debouncer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debouncer.js","sourceRoot":"","sources":["../src/debouncer.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAGlF,yDAAgF;AAwBhF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAa,SAAS;IAQG;IACA;IARH,KAAK,CAA0B;IAC/B,SAAS,CAAU;IAC5B,KAAK,CAAc;IAC7B,2HAA2H;IACjH,gBAAgB,CAAU;IAEpC,YACsB,KAAY,EACZ,EAAc,EACjC,OAAyB;QAFN,UAAK,GAAL,KAAK,CAAO;QACZ,OAAE,GAAF,EAAE,CAAY;QAGjC,IAAI,CAAC,KAAK,GAAG,kCAAe,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACnD,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACtC,CAAC;IAED,0EAA0E;IAC1E,IAAI,OAAO;QACR,OAAO,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC;IACnC,CAAC;IAED;;;;;OAKG;IACH,QAAQ;QACL,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;QAC7B,IAAI,IAAI,CAAC,gBAAgB,KAAK,SAAS,EAAE,CAAC;YACvC,IAAI,CAAC,gBAAgB,GAAG,GAAG,CAAC;QAC/B,CAAC;QACD,IAAI,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACzC,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;YAChC,MAAM,YAAY,GAAG,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,SAAS,GAAG,GAAG,CAAC;YAClE,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC;QACpD,CAAC;QACD,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC;QACtB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;IAC7D,CAAC;IAED,wFAAwF;IACxF,KAAK;QACF,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC5B,IAAI,CAAC,IAAI,EAAE,CAAC;QACf,CAAC;IACJ,CAAC;IAED,sDAAsD;IACtD,MAAM;QACH,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC;QACtB,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC;QACvB,IAAI,CAAC,gBAAgB,GAAG,SAAS,CAAC;IACrC,CAAC;IAED,2CAA2C;IAC3C,OAAO;QACJ,IAAI,CAAC,MAAM,EAAE,CAAC;IACjB,CAAC;IAES,IAAI;QACX,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC;QACtB,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC;QACvB,IAAI,CAAC,gBAAgB,GAAG,SAAS,CAAC;QAClC,IAAI,CAAC,EAAE,EAAE,CAAC;IACb,CAAC;CACH;AAlED,8BAkEC"}

package/lib/errors.d.ts

@@ -0,0 +1,84 @@
+/********************************************************************************
+ * 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 { ResponseError } from 'vscode-jsonrpc';
+/**
+ * Application-specific JSON-RPC error code for {@link ConflictError}.
+ * Outside the reserved range (-32768 .. -32000) per JSON-RPC 2.0.
+ *
+ * The code is the load-bearing identifier across realm boundaries —
+ * `code` is a first-class field on the JSON-RPC error envelope and
+ * survives wire reconstruction; the custom `Error` subclass name does
+ * not.
+ */
+export declare const CONFLICT_ERROR_CODE = 1001;
+/**
+ * Structured payload carried in {@link ConflictError.data}, and the only place
+ * a post-RPC caller can read the version mismatch from.
+ */
+export interface ConflictErrorData {
+    readonly uri: string;
+    /** The based-on version the caller authored against. */
+    readonly expected: number;
+    /** The server's current text-document version at the time of the throw. */
+    readonly actual: number;
+}
+/**
+ * Thrown by `ModelService.update` / `ModelService.save` when the caller-
+ * supplied based-on version no longer matches the server's current text-
+ * document version for the same URI — i.e. the snapshot the caller
+ * authored against has been superseded by an intervening edit.
+ *
+ * Extends vscode-jsonrpc's {@link ResponseError} so the typed
+ * {@link ConflictErrorData} payload rides on the standard JSON-RPC
+ * error envelope (`code`, `message`, `data`) — all three fields are
+ * preserved by RPC reconstruction. Adopters that catch the error on
+ * the receiving side of an RPC call read the version mismatch from
+ * `err.data` (the instance is reconstructed as a generic
+ * `ResponseError`, so subclass getters / fields do not survive).
+ *
+ * Detection is opt-in via the optional `baseVersion` field on
+ * `TransferUpdateArgs` / `TransferSaveArgs`; callers that omit the field get
+ * no gating. This mirrors LSP's `OptionalVersionedTextDocumentIdentifier`
+ * posture, so headless / CLI / batch tooling with no meaningful based-on
+ * version can opt out explicitly.
+ *
+ * Three reasonable adopter recovery strategies:
+ *
+ * | Strategy | Use case |
+ * |---|---|
+ * | Drop + refetch | Form-widget save; user can re-trigger if they still want the edit. |
+ * | Refetch + replay user edit | Specific structural edits (`setField`, drag-position). Adopter responsibility. |
+ * | Surface to user | Large edits, multi-step transactions. Adopter UI. |
+ *
+ * The framework provides the **detection**; adopters provide the **policy**.
+ * No auto-retry or auto-merge ships by default.
+ */
+export declare class ConflictError extends ResponseError<ConflictErrorData> {
+    constructor(uri: string, expected: number, actual: number);
+    get uri(): string;
+    get expected(): number;
+    get actual(): number;
+}
+/**
+ * Type guard for {@link ConflictError}. Detection ladder:
+ *
+ *  1. `error.name === 'ConflictError'` — direct in-process throw, no
+ *     RPC round-trip.
+ *  2. `(error as ResponseError).code === CONFLICT_ERROR_CODE` — the
+ *     canonical wire-side check; the JSON-RPC `code` field is preserved
+ *     across reconstruction, so any adopter catching after an RPC call
+ *     hits this branch.
+ *  3. `error.message.includes('Stale-based update for ')` — fallback
+ *     for transports that re-wrap the message and drop the code (rare).
+ *
+ * `instanceof ConflictError` alone would silently return `false` on the
+ * reconstructed shape, so callers do not use it.
+ */
+export declare function isConflictError(error: unknown): error is ConflictError;
+//# sourceMappingURL=errors.d.ts.map

package/lib/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAExC;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,aAAc,SAAQ,aAAa,CAAC,iBAAiB,CAAC;gBACpD,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;IAezD,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,IAAI,MAAM,IAAI,MAAM,CAEnB;CACH;AAOD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAYtE"}

package/lib/errors.js

@@ -0,0 +1,113 @@
+"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.ConflictError = exports.CONFLICT_ERROR_CODE = void 0;
+exports.isConflictError = isConflictError;
+const vscode_jsonrpc_1 = require("vscode-jsonrpc");
+/**
+ * Application-specific JSON-RPC error code for {@link ConflictError}.
+ * Outside the reserved range (-32768 .. -32000) per JSON-RPC 2.0.
+ *
+ * The code is the load-bearing identifier across realm boundaries —
+ * `code` is a first-class field on the JSON-RPC error envelope and
+ * survives wire reconstruction; the custom `Error` subclass name does
+ * not.
+ */
+exports.CONFLICT_ERROR_CODE = 1001;
+/**
+ * Thrown by `ModelService.update` / `ModelService.save` when the caller-
+ * supplied based-on version no longer matches the server's current text-
+ * document version for the same URI — i.e. the snapshot the caller
+ * authored against has been superseded by an intervening edit.
+ *
+ * Extends vscode-jsonrpc's {@link ResponseError} so the typed
+ * {@link ConflictErrorData} payload rides on the standard JSON-RPC
+ * error envelope (`code`, `message`, `data`) — all three fields are
+ * preserved by RPC reconstruction. Adopters that catch the error on
+ * the receiving side of an RPC call read the version mismatch from
+ * `err.data` (the instance is reconstructed as a generic
+ * `ResponseError`, so subclass getters / fields do not survive).
+ *
+ * Detection is opt-in via the optional `baseVersion` field on
+ * `TransferUpdateArgs` / `TransferSaveArgs`; callers that omit the field get
+ * no gating. This mirrors LSP's `OptionalVersionedTextDocumentIdentifier`
+ * posture, so headless / CLI / batch tooling with no meaningful based-on
+ * version can opt out explicitly.
+ *
+ * Three reasonable adopter recovery strategies:
+ *
+ * | Strategy | Use case |
+ * |---|---|
+ * | Drop + refetch | Form-widget save; user can re-trigger if they still want the edit. |
+ * | Refetch + replay user edit | Specific structural edits (`setField`, drag-position). Adopter responsibility. |
+ * | Surface to user | Large edits, multi-step transactions. Adopter UI. |
+ *
+ * The framework provides the **detection**; adopters provide the **policy**.
+ * No auto-retry or auto-merge ships by default.
+ */
+class ConflictError extends vscode_jsonrpc_1.ResponseError {
+    constructor(uri, expected, actual) {
+        super(exports.CONFLICT_ERROR_CODE, `Stale-based update for ${uri}: expected v${expected}, server is at v${actual}`, {
+            uri,
+            expected,
+            actual
+        });
+        this.name = 'ConflictError';
+        // ResponseError's constructor calls `Object.setPrototypeOf(this,
+        // ResponseError.prototype)` to keep its own prototype chain intact across
+        // transpilation targets; that resets us to ResponseError, hiding the
+        // ConflictError-specific getters. Restore the prototype here so
+        // `err.uri` / `.expected` / `.actual` resolve through this class.
+        Object.setPrototypeOf(this, ConflictError.prototype);
+    }
+    get uri() {
+        return this.data.uri;
+    }
+    get expected() {
+        return this.data.expected;
+    }
+    get actual() {
+        return this.data.actual;
+    }
+}
+exports.ConflictError = ConflictError;
+/** Marker substring present in every {@link ConflictError} message, used by
+ *  {@link isConflictError} as a fallback when a transport re-wraps the error
+ *  and drops the JSON-RPC code. */
+const CONFLICT_ERROR_MESSAGE_MARKER = 'Stale-based update for ';
+/**
+ * Type guard for {@link ConflictError}. Detection ladder:
+ *
+ *  1. `error.name === 'ConflictError'` — direct in-process throw, no
+ *     RPC round-trip.
+ *  2. `(error as ResponseError).code === CONFLICT_ERROR_CODE` — the
+ *     canonical wire-side check; the JSON-RPC `code` field is preserved
+ *     across reconstruction, so any adopter catching after an RPC call
+ *     hits this branch.
+ *  3. `error.message.includes('Stale-based update for ')` — fallback
+ *     for transports that re-wrap the message and drop the code (rare).
+ *
+ * `instanceof ConflictError` alone would silently return `false` on the
+ * reconstructed shape, so callers do not use it.
+ */
+function isConflictError(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    if (error.name === 'ConflictError') {
+        return true;
+    }
+    const code = error.code;
+    if (code === exports.CONFLICT_ERROR_CODE) {
+        return true;
+    }
+    return typeof error.message === 'string' && error.message.includes(CONFLICT_ERROR_MESSAGE_MARKER);
+}
+//# sourceMappingURL=errors.js.map

package/lib/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AA2GlF,0CAYC;AArHD,mDAA+C;AAE/C;;;;;;;;GAQG;AACU,QAAA,mBAAmB,GAAG,IAAI,CAAC;AAcxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAa,aAAc,SAAQ,8BAAgC;IAChE,YAAY,GAAW,EAAE,QAAgB,EAAE,MAAc;QACtD,KAAK,CAAC,2BAAmB,EAAE,0BAA0B,GAAG,eAAe,QAAQ,mBAAmB,MAAM,EAAE,EAAE;YACzG,GAAG;YACH,QAAQ;YACR,MAAM;SACR,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,iEAAiE;QACjE,0EAA0E;QAC1E,qEAAqE;QACrE,gEAAgE;QAChE,kEAAkE;QAClE,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IACxD,CAAC;IAED,IAAI,GAAG;QACJ,OAAO,IAAI,CAAC,IAAK,CAAC,GAAG,CAAC;IACzB,CAAC;IAED,IAAI,QAAQ;QACT,OAAO,IAAI,CAAC,IAAK,CAAC,QAAQ,CAAC;IAC9B,CAAC;IAED,IAAI,MAAM;QACP,OAAO,IAAI,CAAC,IAAK,CAAC,MAAM,CAAC;IAC5B,CAAC;CACH;AA3BD,sCA2BC;AAED;;mCAEmC;AACnC,MAAM,6BAA6B,GAAG,yBAAyB,CAAC;AAEhE;;;;;;;;;;;;;;GAcG;AACH,SAAgB,eAAe,CAAC,KAAc;IAC3C,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,KAAK,CAAC;IAChB,CAAC;IACD,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,EAAE,CAAC;QAClC,OAAO,IAAI,CAAC;IACf,CAAC;IACD,MAAM,IAAI,GAAI,KAAyC,CAAC,IAAI,CAAC;IAC7D,IAAI,IAAI,KAAK,2BAAmB,EAAE,CAAC;QAChC,OAAO,IAAI,CAAC;IACf,CAAC;IACD,OAAO,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,6BAA6B,CAAC,CAAC;AACrG,CAAC"}

package/lib/host-diagnostics.d.ts

@@ -0,0 +1,58 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * Diagnostics contract for the HOST (parent) process — the Theia backend
+ * itself, the process that runs the data-client connection handlers and any
+ * in-process services. Distinct from `DataServerDiagnosticsProtocol`,
+ * which targets the separate data-server child (the heavy model store): the
+ * host process is reached by an ordinary in-process Theia RPC service, NOT over
+ * the data-server socket. Universal (`process.memoryUsage()` always works) and
+ * cheap, so the framework wires it by default for every host that opts the
+ * data-client backend module in.
+ *
+ * Returns are plain formatted strings — the caller (a command, a log sink, the
+ * pod's stdout) decides how to surface them.
+ */
+/** Arguments for {@link HostDiagnosticsProtocol.dumpHostState}. */
+export interface DumpHostStateArgs {
+    /** Optional label folded into the snapshot heading (e.g. an ISO timestamp). */
+    label?: string;
+}
+/** Arguments for {@link HostDiagnosticsProtocol.writeHostHeapSnapshot}. */
+export interface WriteHostHeapSnapshotArgs {
+    /** 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 diagnostics the running HOST (Theia backend) process exposes. Computed
+ * in-process: the snapshots reflect the parent process, the counterpart to the
+ * data-server child's `DataServerDiagnosticsProtocol`.
+ */
+export interface HostDiagnosticsProtocol {
+    /**
+     * Capture a host-process memory snapshot — heap, rss, external, V8 limit —
+     * and return it formatted. The host hosts no Langium documents, so this is
+     * the lighter `formatProcessMemory` view, not `formatServerState`.
+     */
+    dumpHostState(args: DumpHostStateArgs): Promise<string>;
+    /**
+     * Write a V8 heap snapshot of the host process to disk (full GC first;
+     * briefly pauses the process) and return the absolute file path.
+     */
+    writeHostHeapSnapshot(args: WriteHostHeapSnapshotArgs): Promise<string>;
+}
+/**
+ * Theia service path the host-diagnostics RPC service is registered under. An
+ * ordinary in-process backend service (`RpcConnectionHandler`), unlike the
+ * socket-forwarded `DATA_SERVER_PATH`.
+ */
+export declare const HOST_DIAGNOSTICS_PATH = "/hydranium/host-diagnostics";
+//# sourceMappingURL=host-diagnostics.d.ts.map

package/lib/host-diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-diagnostics.d.ts","sourceRoot":"","sources":["../src/host-diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;;;;;GAYG;AAEH,mEAAmE;AACnE,MAAM,WAAW,iBAAiB;IAC/B,+EAA+E;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,2EAA2E;AAC3E,MAAM,WAAW,yBAAyB;IACvC,wDAAwD;IACxD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+FAA+F;IAC/F,SAAS,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACrC;;;;OAIG;IACH,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAExD;;;OAGG;IACH,qBAAqB,CAAC,IAAI,EAAE,yBAAyB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1E;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,gCAAgC,CAAC"}