@hydranium/protocol 1.0.0-next.11 → 1.0.0-next.112

package/lib/client/rpc-connection.d.ts

@@ -0,0 +1,143 @@
+/********************************************************************************
+ * 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 { MessageConnection } from 'vscode-jsonrpc';
+import { type ResolvedMessage } from '../messages/primitives';
+import { type RpcProxy } from '../rpc';
+import type { DataPort } from './data-port';
+/**
+ * The transport never opened. A complete sentence rather than a fragment: a
+ * fragment is nested inside a sentence the framework does not own, so no
+ * translator controls the whole and the composition cannot be made to read
+ * correctly in every language.
+ */
+export declare const DATA_SERVER_CONNECT_FAILED: import("../messages/primitives").MessageDefinition<"Could not connect to the data server: {detail}">;
+export declare const DATA_SERVER_NOT_READY: import("../messages/primitives").MessageDefinition<"The data server did not become ready: {detail}">;
+/** The one method a connection needs of any server: its startup gate. */
+export interface ReadyServer {
+    waitForReady(): Promise<void>;
+}
+/**
+ * Lifecycle reporting, for a host that raises warm-up UI around the two waits.
+ *
+ * Nothing fires until something asks for the connection — the generation is
+ * built on the first {@link RpcConnection.connected}. A host that wants the
+ * sequence at startup drives that call itself, or a workspace where nobody
+ * opens a document reports neither the connect nor the readiness its UI waits
+ * on.
+ */
+export interface RpcConnectionLifecycle {
+    /** A generation is opening its transport, including on each reconnect. */
+    readonly onConnecting?: () => void;
+    /** The server's readiness gate has settled for a generation. */
+    readonly onReady?: () => void;
+    /**
+     * A generation failed to connect or to become ready. The failure is still
+     * reported through {@link DataPort.reportError} and still rejects the
+     * awaiting caller; this is for a host that also drives its own UI.
+     */
+    readonly onFailed?: (error: unknown) => void;
+}
+/** Everything {@link RpcConnection} needs once a subclass has resolved its defaults. */
+export interface ResolvedRpcConnectionOptions<TClient extends object> {
+    readonly methodNamespace: string;
+    readonly clientMethods: readonly (keyof TClient & string)[];
+    readonly lifecycle: RpcConnectionLifecycle;
+}
+/**
+ * One connection generation: its connection, its proxy, and its readiness.
+ *
+ * Named by the `protected` reconnect seams {@link RpcConnection.currentGeneration}
+ * and {@link RpcConnection.awaitReady}, so an override has to name it too.
+ */
+export interface RpcConnectionGeneration<TServer extends object> {
+    readonly connection: Promise<MessageConnection>;
+    readonly server: RpcProxy<TServer>;
+    /** Set on first use; the shared readiness gate for this generation. */
+    ready?: Promise<void>;
+}
+/**
+ * One JSON-RPC connection to a head, with the three jobs every host adapter
+ * would otherwise re-derive above {@link DataPort}:
+ *
+ * 1. **Build the typed proxy** over the port's connection, with the caller's
+ *    wire prefix and client-method allowlist.
+ * 2. **Own the readiness gate** — `waitForReady` once per connection, shared
+ *    across concurrent callers. A client can connect before the workspace walk
+ *    finishes, and an early request is then answered correctly from an empty
+ *    registry, which reads as a broken project tier rather than as a race.
+ * 3. **Own the reconnect policy**, by dropping its generation when the port
+ *    disposes and building a fresh one on the next request.
+ *
+ * Bounded only by {@link ReadyServer}, so a head serving a slice of the data
+ * protocol — diagnostics alone, or one with methods excluded — is still a
+ * legal server here. `DataConnection` narrows the bound because its sessions
+ * call the document methods; nothing at this layer does.
+ */
+export declare class RpcConnection<TServer extends ReadyServer, TClient extends object> {
+    protected readonly port: DataPort;
+    protected readonly client: TClient;
+    protected readonly methodNamespace: string;
+    protected readonly clientMethods: readonly (keyof TClient & string)[];
+    protected readonly lifecycle: RpcConnectionLifecycle;
+    /** The current generation, or `undefined` before the first request / after a teardown. */
+    protected generation?: RpcConnectionGeneration<TServer>;
+    protected disposed: boolean;
+    protected readonly portDisposeListener: {
+        dispose(): void;
+    };
+    constructor(port: DataPort, client: TClient, options: ResolvedRpcConnectionOptions<TClient>);
+    /**
+     * The connected, READY server proxy.
+     *
+     * Returns the proxy rather than `void` on purpose. A reconnect replaces the
+     * proxy, so a caller that cached one from an earlier call would go on
+     * addressing a dead connection with no error — handing it back per call
+     * makes the stale reference unrepresentable.
+     *
+     * Concurrent callers share one readiness promise, so `waitForReady` is
+     * awaited once per generation and not once per caller.
+     */
+    connected(): Promise<RpcProxy<TServer>>;
+    /**
+     * The current generation's proxy WITHOUT awaiting readiness — calls queue
+     * against the connection promise.
+     *
+     * **Protected, and that is the point.** An early request is answered
+     * correctly from a registry the workspace walk has not filled yet, which
+     * reads as a broken project tier rather than as a race — so every caller has
+     * to interpose the gate, and every caller forgetting to is a silent bug.
+     * {@link connected} is the public route and returns this same proxy once the
+     * gate has settled, which leaves nothing to forget. The one caller that
+     * cannot use it is {@link awaitReady}, whose whole job is running the gate.
+     *
+     * Read per access, never cached: a reconnect replaces the generation, and a
+     * held reference would address the dead one.
+     */
+    protected get server(): RpcProxy<TServer>;
+    /**
+     * Surface a failure the way this host does, through the port's sink.
+     *
+     * Here rather than only on the port so every participant sharing the
+     * connection reports through one route without being handed the transport.
+     */
+    reportError(error: unknown, reported: ResolvedMessage): void;
+    /** Tear down the current connection and stop tracking the port. Idempotent. */
+    dispose(): void;
+    /** The live generation, building one if there is none. */
+    protected currentGeneration(): RpcConnectionGeneration<TServer>;
+    /** Await the connection and the server's startup gate for one generation. */
+    protected awaitReady(generation: RpcConnectionGeneration<TServer>): Promise<void>;
+    /**
+     * Discard the current generation, disposing its connection if it opened.
+     * The next {@link connected} builds a fresh one.
+     */
+    protected dropGeneration(): void;
+    protected assertLive(): void;
+}
+//# sourceMappingURL=rpc-connection.d.ts.map

package/lib/client/rpc-connection.d.ts.map

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

package/lib/client/rpc-connection.js

@@ -0,0 +1,171 @@
+"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.RpcConnection = exports.DATA_SERVER_NOT_READY = exports.DATA_SERVER_CONNECT_FAILED = void 0;
+const primitives_1 = require("../messages/primitives");
+const rpc_1 = require("../rpc");
+/**
+ * The transport never opened. A complete sentence rather than a fragment: a
+ * fragment is nested inside a sentence the framework does not own, so no
+ * translator controls the whole and the composition cannot be made to read
+ * correctly in every language.
+ */
+exports.DATA_SERVER_CONNECT_FAILED = (0, primitives_1.defineMessage)('hydranium/protocol/data-server-connect-failed', 'Could not connect to the data server: {detail}');
+exports.DATA_SERVER_NOT_READY = (0, primitives_1.defineMessage)('hydranium/protocol/data-server-not-ready', 'The data server did not become ready: {detail}');
+/**
+ * One JSON-RPC connection to a head, with the three jobs every host adapter
+ * would otherwise re-derive above {@link DataPort}:
+ *
+ * 1. **Build the typed proxy** over the port's connection, with the caller's
+ *    wire prefix and client-method allowlist.
+ * 2. **Own the readiness gate** — `waitForReady` once per connection, shared
+ *    across concurrent callers. A client can connect before the workspace walk
+ *    finishes, and an early request is then answered correctly from an empty
+ *    registry, which reads as a broken project tier rather than as a race.
+ * 3. **Own the reconnect policy**, by dropping its generation when the port
+ *    disposes and building a fresh one on the next request.
+ *
+ * Bounded only by {@link ReadyServer}, so a head serving a slice of the data
+ * protocol — diagnostics alone, or one with methods excluded — is still a
+ * legal server here. `DataConnection` narrows the bound because its sessions
+ * call the document methods; nothing at this layer does.
+ */
+class RpcConnection {
+    port;
+    client;
+    methodNamespace;
+    clientMethods;
+    lifecycle;
+    /** The current generation, or `undefined` before the first request / after a teardown. */
+    generation;
+    disposed = false;
+    portDisposeListener;
+    constructor(port, client, options) {
+        this.port = port;
+        this.client = client;
+        this.methodNamespace = options.methodNamespace;
+        this.clientMethods = options.clientMethods;
+        this.lifecycle = options.lifecycle;
+        this.portDisposeListener = this.port.onDispose(() => this.dropGeneration());
+    }
+    /**
+     * The connected, READY server proxy.
+     *
+     * Returns the proxy rather than `void` on purpose. A reconnect replaces the
+     * proxy, so a caller that cached one from an earlier call would go on
+     * addressing a dead connection with no error — handing it back per call
+     * makes the stale reference unrepresentable.
+     *
+     * Concurrent callers share one readiness promise, so `waitForReady` is
+     * awaited once per generation and not once per caller.
+     */
+    async connected() {
+        this.assertLive();
+        const generation = this.currentGeneration();
+        if (!generation.ready) {
+            generation.ready = this.awaitReady(generation);
+        }
+        await generation.ready;
+        return generation.server;
+    }
+    /**
+     * The current generation's proxy WITHOUT awaiting readiness — calls queue
+     * against the connection promise.
+     *
+     * **Protected, and that is the point.** An early request is answered
+     * correctly from a registry the workspace walk has not filled yet, which
+     * reads as a broken project tier rather than as a race — so every caller has
+     * to interpose the gate, and every caller forgetting to is a silent bug.
+     * {@link connected} is the public route and returns this same proxy once the
+     * gate has settled, which leaves nothing to forget. The one caller that
+     * cannot use it is {@link awaitReady}, whose whole job is running the gate.
+     *
+     * Read per access, never cached: a reconnect replaces the generation, and a
+     * held reference would address the dead one.
+     */
+    get server() {
+        this.assertLive();
+        return this.currentGeneration().server;
+    }
+    /**
+     * Surface a failure the way this host does, through the port's sink.
+     *
+     * Here rather than only on the port so every participant sharing the
+     * connection reports through one route without being handed the transport.
+     */
+    reportError(error, reported) {
+        this.port.reportError(error, reported);
+    }
+    /** Tear down the current connection and stop tracking the port. Idempotent. */
+    dispose() {
+        if (this.disposed) {
+            return;
+        }
+        this.disposed = true;
+        this.portDisposeListener.dispose();
+        this.dropGeneration();
+    }
+    /** The live generation, building one if there is none. */
+    currentGeneration() {
+        if (this.generation) {
+            return this.generation;
+        }
+        this.lifecycle.onConnecting?.();
+        const connection = this.port.connect();
+        // Rejection is reported here rather than left to float: an unhandled
+        // rejection on a connection promise is the failure mode that reads as
+        // "the model is empty" instead of "the transport never opened".
+        connection.catch((error) => this.port.reportError(error, (0, primitives_1.resolve)(exports.DATA_SERVER_CONNECT_FAILED, { detail: (0, primitives_1.describeError)(error) })));
+        const server = (0, rpc_1.createRpcProxy)(connection, {
+            methodNamespace: this.methodNamespace,
+            localTarget: this.client,
+            localMethods: this.clientMethods
+        });
+        this.generation = { connection, server };
+        return this.generation;
+    }
+    /** Await the connection and the server's startup gate for one generation. */
+    async awaitReady(generation) {
+        try {
+            await generation.connection;
+            await generation.server.waitForReady();
+            this.lifecycle.onReady?.();
+        }
+        catch (error) {
+            this.lifecycle.onFailed?.(error);
+            // Drop the generation so the next request retries rather than
+            // re-awaiting a settled rejection forever.
+            if (this.generation === generation) {
+                this.generation = undefined;
+            }
+            this.port.reportError(error, (0, primitives_1.resolve)(exports.DATA_SERVER_NOT_READY, { detail: (0, primitives_1.describeError)(error) }));
+            throw error;
+        }
+    }
+    /**
+     * Discard the current generation, disposing its connection if it opened.
+     * The next {@link connected} builds a fresh one.
+     */
+    dropGeneration() {
+        const generation = this.generation;
+        this.generation = undefined;
+        if (!generation) {
+            return;
+        }
+        generation.connection.then(connection => connection.dispose()).catch(() => undefined);
+    }
+    assertLive() {
+        if (this.disposed) {
+            throw new Error(`${this.constructor.name} is disposed`);
+        }
+    }
+}
+exports.RpcConnection = RpcConnection;
+//# sourceMappingURL=rpc-connection.js.map

package/lib/client/rpc-connection.js.map

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

package/lib/client-ids.d.ts

@@ -0,0 +1,41 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * Well-known values of the wire's `clientId` / `sourceClientId` field.
+ *
+ * The framework tracks each document as belonging to one or more "clients" —
+ * typically an LSP-text client (Monaco, VS Code, …), a GLSP diagram client,
+ * and/or a structured-form client — and keys its holds and watches per
+ * `(uri, clientId)`. These three values are not real participants, so a client
+ * minting its own id must avoid them.
+ *
+ * **Here rather than in the server package, because the side that has to
+ * RECOGNISE them is the client.** An inbound `onDocumentUpdated` carries
+ * `sourceClientId`, and a consumer deciding what to do with it is asking which
+ * of these it is — so a frontend would otherwise have to depend on the server
+ * tier to name three strings, and in practice retypes the literal instead.
+ */
+/** Identifier for an LSP-text client (Monaco, VS Code, …). */
+export declare const LANGUAGE_CLIENT_ID = "language-client";
+/** Fallback identifier when a document's author is unknown (e.g. cold workspace-init load). */
+export declare const UNKNOWN_CLIENT_ID = "unknown";
+/**
+ * Synthetic author id on the `onDocumentUpdated` broadcast a data-server
+ * emits after the LAST client closed a document and the framework rebuilt it
+ * from its disk content (discarding unsaved in-session edits). Not a real
+ * client: it lets consumers distinguish the revert broadcast from
+ * client-authored updates.
+ */
+export declare const REVERT_ON_CLOSE_CLIENT_ID = "revert-on-close";
+/**
+ * Every id the framework reserves, for a client checking that the identity it
+ * is about to mint collides with none of them.
+ */
+export declare const FRAMEWORK_CLIENT_IDS: readonly string[];
+//# sourceMappingURL=client-ids.d.ts.map

package/lib/client-ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-ids.d.ts","sourceRoot":"","sources":["../src/client-ids.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;;;;;;;GAcG;AAEH,8DAA8D;AAC9D,eAAO,MAAM,kBAAkB,oBAAoB,CAAC;AAEpD,+FAA+F;AAC/F,eAAO,MAAM,iBAAiB,YAAY,CAAC;AAE3C;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,oBAAoB,CAAC;AAE3D;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAAuE,CAAC"}

package/lib/client-ids.js

@@ -0,0 +1,44 @@
+"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.FRAMEWORK_CLIENT_IDS = exports.REVERT_ON_CLOSE_CLIENT_ID = exports.UNKNOWN_CLIENT_ID = exports.LANGUAGE_CLIENT_ID = void 0;
+/**
+ * Well-known values of the wire's `clientId` / `sourceClientId` field.
+ *
+ * The framework tracks each document as belonging to one or more "clients" —
+ * typically an LSP-text client (Monaco, VS Code, …), a GLSP diagram client,
+ * and/or a structured-form client — and keys its holds and watches per
+ * `(uri, clientId)`. These three values are not real participants, so a client
+ * minting its own id must avoid them.
+ *
+ * **Here rather than in the server package, because the side that has to
+ * RECOGNISE them is the client.** An inbound `onDocumentUpdated` carries
+ * `sourceClientId`, and a consumer deciding what to do with it is asking which
+ * of these it is — so a frontend would otherwise have to depend on the server
+ * tier to name three strings, and in practice retypes the literal instead.
+ */
+/** Identifier for an LSP-text client (Monaco, VS Code, …). */
+exports.LANGUAGE_CLIENT_ID = 'language-client';
+/** Fallback identifier when a document's author is unknown (e.g. cold workspace-init load). */
+exports.UNKNOWN_CLIENT_ID = 'unknown';
+/**
+ * Synthetic author id on the `onDocumentUpdated` broadcast a data-server
+ * emits after the LAST client closed a document and the framework rebuilt it
+ * from its disk content (discarding unsaved in-session edits). Not a real
+ * client: it lets consumers distinguish the revert broadcast from
+ * client-authored updates.
+ */
+exports.REVERT_ON_CLOSE_CLIENT_ID = 'revert-on-close';
+/**
+ * Every id the framework reserves, for a client checking that the identity it
+ * is about to mint collides with none of them.
+ */
+exports.FRAMEWORK_CLIENT_IDS = [exports.LANGUAGE_CLIENT_ID, exports.UNKNOWN_CLIENT_ID, exports.REVERT_ON_CLOSE_CLIENT_ID];
+//# sourceMappingURL=client-ids.js.map

package/lib/client-ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-ids.js","sourceRoot":"","sources":["../src/client-ids.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAElF;;;;;;;;;;;;;;GAcG;AAEH,8DAA8D;AACjD,QAAA,kBAAkB,GAAG,iBAAiB,CAAC;AAEpD,+FAA+F;AAClF,QAAA,iBAAiB,GAAG,SAAS,CAAC;AAE3C;;;;;;GAMG;AACU,QAAA,yBAAyB,GAAG,iBAAiB,CAAC;AAE3D;;;GAGG;AACU,QAAA,oBAAoB,GAAsB,CAAC,0BAAkB,EAAE,yBAAiB,EAAE,iCAAyB,CAAC,CAAC"}

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

@@ -25,7 +25,7 @@ export declare const DATA_SERVER_PROTOCOL_METHODS: readonly ["openModelDocument"
  */
 export declare const REFERENCE_SERVER_PROTOCOL_METHODS: readonly ["findReferenceCandidates", "resolveReference", "findNextName"];
 /** Notification-method names on {@link DocumentClientProtocol}. */
-export declare const DOCUMENT_CLIENT_PROTOCOL_METHODS: readonly ["onDocumentUpdated", "onDocumentSaved"];
+export declare const DOCUMENT_CLIENT_PROTOCOL_METHODS: readonly ["onDocumentUpdated", "onDocumentSaved", "onDocumentDeleted", "onDocumentsBuilt"];
 /** Notification-method names on {@link ProjectClientProtocol}. */
 export declare const PROJECT_CLIENT_PROTOCOL_METHODS: readonly ["onProjectsChanged"];
 /**
@@ -35,5 +35,5 @@ export declare const PROJECT_CLIENT_PROTOCOL_METHODS: readonly ["onProjectsChang
  * data head's connection routes `<methodNamespace>onDocumentUpdated` etc. to
  * the bound client target.
  */
-export declare const DATA_CLIENT_PROTOCOL_METHODS: readonly ["onDocumentUpdated", "onDocumentSaved", "onProjectsChanged"];
+export declare const DATA_CLIENT_PROTOCOL_METHODS: readonly ["onDocumentUpdated", "onDocumentSaved", "onDocumentDeleted", "onDocumentsBuilt", "onProjectsChanged"];
 //# sourceMappingURL=data-protocol-methods.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"data-protocol-methods.d.ts","sourceRoot":"","sources":["../../src/data/data-protocol-methods.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAalF,8DAA8D;AAC9D,eAAO,MAAM,gCAAgC,oLAS6C,CAAC;AAE3F,6DAA6D;AAC7D,eAAO,MAAM,+BAA+B,8CAE3C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,uNAG6C,CAAC;AAEvF;;;;;GAKG;AACH,eAAO,MAAM,iCAAiC,0EAI6C,CAAC;AAE5F,mEAAmE;AACnE,eAAO,MAAM,gCAAgC,mDAE5C,CAAC;AAEF,kEAAkE;AAClE,eAAO,MAAM,+BAA+B,gCAA+F,CAAC;AAE5I;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,wEAG6C,CAAC"}
+{"version":3,"file":"data-protocol-methods.d.ts","sourceRoot":"","sources":["../../src/data/data-protocol-methods.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAalF,8DAA8D;AAC9D,eAAO,MAAM,gCAAgC,oLAS6C,CAAC;AAE3F,6DAA6D;AAC7D,eAAO,MAAM,+BAA+B,8CAE3C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,uNAG6C,CAAC;AAEvF;;;;;GAKG;AACH,eAAO,MAAM,iCAAiC,0EAI6C,CAAC;AAE5F,mEAAmE;AACnE,eAAO,MAAM,gCAAgC,4FAK6C,CAAC;AAE3F,kEAAkE;AAClE,eAAO,MAAM,+BAA+B,gCAA+F,CAAC;AAE5I;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,iHAG6C,CAAC"}

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

@@ -44,7 +44,12 @@ exports.REFERENCE_SERVER_PROTOCOL_METHODS = [
     'findNextName'
 ];
 /** Notification-method names on {@link DocumentClientProtocol}. */
-exports.DOCUMENT_CLIENT_PROTOCOL_METHODS = ['onDocumentUpdated', 'onDocumentSaved'];
+exports.DOCUMENT_CLIENT_PROTOCOL_METHODS = [
+    'onDocumentUpdated',
+    'onDocumentSaved',
+    'onDocumentDeleted',
+    'onDocumentsBuilt'
+];
 /** Notification-method names on {@link ProjectClientProtocol}. */
 exports.PROJECT_CLIENT_PROTOCOL_METHODS = ['onProjectsChanged'];
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"data-protocol-methods.js","sourceRoot":"","sources":["../../src/data/data-protocol-methods.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAalF,8DAA8D;AACjD,QAAA,gCAAgC,GAAG;IAC7C,mBAAmB;IACnB,oBAAoB;IACpB,kBAAkB;IAClB,qBAAqB;IACrB,mBAAmB;IACnB,oBAAoB;IACpB,sBAAsB;IACtB,cAAc;CACyE,CAAC;AAE3F,6DAA6D;AAChD,QAAA,+BAA+B,GAAG,CAAC,aAAa,EAAE,kBAAkB,CAEhF,CAAC;AAEF;;;;;GAKG;AACU,QAAA,4BAA4B,GAAG;IACzC,GAAG,wCAAgC;IACnC,GAAG,uCAA+B;CACiD,CAAC;AAEvF;;;;;GAKG;AACU,QAAA,iCAAiC,GAAG;IAC9C,yBAAyB;IACzB,kBAAkB;IAClB,cAAc;CAC0E,CAAC;AAE5F,mEAAmE;AACtD,QAAA,gCAAgC,GAAG,CAAC,mBAAmB,EAAE,iBAAiB,CAEtF,CAAC;AAEF,kEAAkE;AACrD,QAAA,+BAA+B,GAAG,CAAC,mBAAmB,CAAwE,CAAC;AAE5I;;;;;;GAMG;AACU,QAAA,4BAA4B,GAAG;IACzC,GAAG,wCAAgC;IACnC,GAAG,uCAA+B;CACiD,CAAC"}
+{"version":3,"file":"data-protocol-methods.js","sourceRoot":"","sources":["../../src/data/data-protocol-methods.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAalF,8DAA8D;AACjD,QAAA,gCAAgC,GAAG;IAC7C,mBAAmB;IACnB,oBAAoB;IACpB,kBAAkB;IAClB,qBAAqB;IACrB,mBAAmB;IACnB,oBAAoB;IACpB,sBAAsB;IACtB,cAAc;CACyE,CAAC;AAE3F,6DAA6D;AAChD,QAAA,+BAA+B,GAAG,CAAC,aAAa,EAAE,kBAAkB,CAEhF,CAAC;AAEF;;;;;GAKG;AACU,QAAA,4BAA4B,GAAG;IACzC,GAAG,wCAAgC;IACnC,GAAG,uCAA+B;CACiD,CAAC;AAEvF;;;;;GAKG;AACU,QAAA,iCAAiC,GAAG;IAC9C,yBAAyB;IACzB,kBAAkB;IAClB,cAAc;CAC0E,CAAC;AAE5F,mEAAmE;AACtD,QAAA,gCAAgC,GAAG;IAC7C,mBAAmB;IACnB,iBAAiB;IACjB,mBAAmB;IACnB,kBAAkB;CACqE,CAAC;AAE3F,kEAAkE;AACrD,QAAA,+BAA+B,GAAG,CAAC,mBAAmB,CAAwE,CAAC;AAE5I;;;;;;GAMG;AACU,QAAA,4BAA4B,GAAG;IACzC,GAAG,wCAAgC;IACnC,GAAG,uCAA+B;CACiD,CAAC"}

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

@@ -12,7 +12,7 @@ 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 { ProjectsChangedEvent, TransferDocumentDeletedEvent, TransferDocumentSavedEvent, TransferDocumentsBuiltEvent, TransferDocumentUpdatedEvent } from './events';
 import type { GetModelDocumentArgs, GetProjectForUriArgs, TransferSaveDocumentArgs, WatchModelDocumentArgs, TransferUpdateDocumentArgs } from './requests';
 /**
  * Document-scoped slice of the data-server wire contract: the per-document
@@ -37,7 +37,7 @@ export interface DocumentServerProtocol<TTransfer extends TransferElement, TDiag
      * (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
+     * the text-document store so the caller's first `basedOn` 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
@@ -171,6 +171,19 @@ export interface ProjectServerProtocol<TProject extends Project = Project> {
  */
 export interface DataServerProtocol<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic, TProject extends Project = Project> extends DocumentServerProtocol<TTransfer, TDiagnostic>, ProjectServerProtocol<TProject> {
 }
+/**
+ * The diagnostic shape a server answers with, read back off its own
+ * declaration.
+ *
+ * This is what lets a client tier stay generic over the server alone and still
+ * describe what it hands back. Both parameters must be inferred: naming
+ * {@link TransferElement} for the transfer instead fails to match while that
+ * parameter is still generic, and a default declared against the constraint
+ * then stops satisfying it.
+ */
+export type DiagnosticOf<TServer> = TServer extends DocumentServerProtocol<infer _TTransfer, infer TDiagnostic> ? TDiagnostic : TransferDiagnostic;
+/** The project shape a server answers with, read back off its own declaration. */
+export type ProjectOf<TServer> = TServer extends ProjectServerProtocol<infer TProject> ? TProject : Project;
 /**
  * Cross-reference / naming slice of the server surface — scope-aware
  * queries that resolve against the language's reference services. NOT part
@@ -235,6 +248,26 @@ export interface DocumentClientProtocol<TTransfer extends TransferElement, TDiag
      * codepath, not a subscription codepath).
      */
     onDocumentSaved(event: TransferDocumentSavedEvent<TTransfer, TDiagnostic>): void;
+    /**
+     * Delivered when a document's backing file was removed. Separate from
+     * {@link onDocumentUpdated} for the same reason as {@link onDocumentSaved},
+     * and more strongly: there is no built state to deliver, and the build-phase
+     * path cannot report a deletion at all.
+     *
+     * Ungated, because on a browser host — where the workspace lives behind the
+     * head — no other source can observe a file disappearing. Recipients that
+     * only care about their own documents filter by URI.
+     */
+    onDocumentDeleted(event: TransferDocumentDeletedEvent): void;
+    /**
+     * Delivered once per build, naming the documents that reached the
+     * subscription phase and that
+     * nobody on this connection watches — chiefly the ones rebuilt as a cascade
+     * from a dependency's change, which no filesystem watcher can see because
+     * their own files did not change. The complement of
+     * {@link onDocumentUpdated}; carries URIs and no documents.
+     */
+    onDocumentsBuilt(event: TransferDocumentsBuiltEvent): void;
 }
 /**
  * Project-scoped slice of the client surface — the project-registry change

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

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

@@ -28,10 +28,14 @@ import type { TransferDocument } from '../transfer-document';
  *   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.
+ *
+ * Deletion is deliberately NOT a member. An update event carries a built
+ * document, which a deleted one has none of, and the phase-driven path that
+ * produces these events never runs for a deleted URI — the builder drops the
+ * document before deriving the rebuild set. It travels as
+ * {@link TransferDocumentDeletedEvent} on its own channel instead.
  */
-export type TransferDocumentUpdateReason = 'changed' | 'rebuilt' | 'saved' | 'deleted';
+export type TransferDocumentUpdateReason = 'changed' | 'rebuilt' | 'saved';
 /**
  * Delivered on the data-server when a document's content (or existence)
  * changed. Subscribers receive this via `DocumentServerProtocol.watchModelDocument`.
@@ -72,6 +76,69 @@ export interface TransferDocumentSavedEvent<TTransfer extends TransferElement, T
 }
 /** Callback shape for `DataClientProtocol.onDocumentSaved`. */
 export type TransferDocumentSavedListener<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic> = (event: TransferDocumentSavedEvent<TTransfer, TDiagnostic>) => void;
+/**
+ * Delivered on the data-server when a document's backing file was removed.
+ * Carries no document, and cannot: the state a
+ * {@link TransferDocumentUpdatedEvent} would have to carry no longer exists by
+ * the time anyone can be told. That is also why deletion is not a `reason` on
+ * the update stream — `DocumentBuilder.update` drops the document before
+ * deriving the rebuild set, so the phase-driven path that produces update
+ * events never runs for it.
+ *
+ * **Delivered for EVERY document, not only watched ones**, unlike
+ * `onDocumentUpdated` and `onDocumentSaved`. The test that decides which
+ * channels are gated is whether any OTHER source can observe the fact on the
+ * least capable host: a browser-hosted client's workspace lives behind the
+ * head, so nothing there can see a file disappear, and gating the notification
+ * would leave it blind. (A Theia frontend's filesystem watcher would cover it,
+ * which is why this is a host argument and not a structure-versus-content one.)
+ * A watcher is told about its own document's deletion here too, the update
+ * channel being silent for deletions by construction. Filter on {@link uri} if
+ * the receiver only cares about documents it opened.
+ *
+ * A watch survives the deletion, so a file that comes back resumes delivering
+ * `onDocumentUpdated` to the same subscribers with no re-subscription. A
+ * client that responds by closing its editor releases the watch through
+ * `closeModelDocument` as usual.
+ */
+export interface TransferDocumentDeletedEvent {
+    /** Canonical URI of the removed document, keyed as the subscription is. */
+    readonly uri: string;
+}
+/** Callback shape for `DataClientProtocol.onDocumentDeleted`. */
+export type TransferDocumentDeletedListener = (event: TransferDocumentDeletedEvent) => void;
+/**
+ * Delivered on the data-server once per build, naming the documents that reached
+ * the configured subscription phase (`DataServerOptions.subscriptionPhase`,
+ * `Validated` by default) and that NO client on the connection is watching. Not
+ * the integrity-settled landmark, which is a different point and a different
+ * word in this framework.
+ *
+ * The complement of {@link TransferDocumentUpdatedEvent}, which is gated per
+ * URI: together the two cover every document a build touched. This one exists
+ * for the case no source outside the server can observe — a document rebuilt
+ * because something it DEPENDS ON changed. Its own file never changed, so a
+ * filesystem watcher cannot see it, and it has no subscriber, so the update
+ * channel does not report it. A consumer showing data derived from such a
+ * document (a tree label, a decorator) would otherwise hold a stale value with
+ * nothing to invalidate it.
+ *
+ * Carries URIs and no documents: a recipient re-reads what it displays, through
+ * `getModelDocument` or its own request. That keeps the bandwidth property the
+ * per-URI subscription exists for, without gating the message.
+ *
+ * Not sent when the set is empty, which is the normal case while editing — the
+ * document being edited is watched by its own editor and therefore excluded.
+ * Workspace initialisation sends nothing either: it does not build to the
+ * subscription phase. The largest message a workspace can produce is therefore
+ * a whole-workspace rebuild at that phase, which is one message of URIs.
+ */
+export interface TransferDocumentsBuiltEvent {
+    /** Canonical URIs, keyed as subscriptions are. Never empty. */
+    readonly uris: readonly string[];
+}
+/** Callback shape for `DataClientProtocol.onDocumentsBuilt`. */
+export type TransferDocumentsBuiltListener = (event: TransferDocumentsBuiltEvent) => void;
 /**
  * Why a project-change event fired. `added` — the project was newly
  * registered (descriptor discovered); `updated` — the project's