@hydranium/protocol 1.0.0-next.10

package/lib/profile-session.js

@@ -0,0 +1,98 @@
+"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.DefaultProfileSession = void 0;
+const logger_1 = require("./logger");
+/**
+ * Default {@link ProfileSession}. Times against an injected {@link Clock} (so
+ * it is fake-clock deterministic in tests, unlike a raw `performance.now`) and
+ * dumps through an injected {@link Logger}.
+ */
+class DefaultProfileSession {
+    logger;
+    identifier;
+    /** Single monotonic timeline for the whole session; per-scope readings are deltas off it. */
+    sessionStopwatch;
+    stack = [];
+    entries = new Map();
+    constructor(logger, clock, identifier) {
+        this.logger = logger;
+        this.identifier = identifier;
+        this.sessionStopwatch = clock.stopwatch();
+    }
+    scope(id, fn) {
+        const frame = { id, start: this.sessionStopwatch.elapsedMs, childMs: 0 };
+        this.stack.push(frame);
+        let result;
+        try {
+            result = fn();
+        }
+        catch (error) {
+            this.closeFrame(frame);
+            throw error;
+        }
+        if (result instanceof Promise) {
+            return result.then(value => {
+                this.closeFrame(frame);
+                return value;
+            }, error => {
+                this.closeFrame(frame);
+                throw error;
+            });
+        }
+        this.closeFrame(frame);
+        return result;
+    }
+    /** Pop `frame`, charge its full duration to the parent, and record its self-time. */
+    closeFrame(frame) {
+        this.stack.pop();
+        const duration = this.sessionStopwatch.elapsedMs - frame.start;
+        const parent = this.stack[this.stack.length - 1];
+        if (parent) {
+            parent.childMs += duration;
+        }
+        const selfMs = duration - frame.childMs;
+        const samples = this.entries.get(frame.id);
+        if (samples) {
+            samples.push(selfMs);
+        }
+        else {
+            this.entries.set(frame.id, [selfMs]);
+        }
+    }
+    records() {
+        const totalMs = this.sessionStopwatch.elapsedMs;
+        const records = [];
+        for (const [id, samples] of this.entries) {
+            const selfMs = samples.reduce((sum, value) => sum + value, 0);
+            records.push({ id, count: samples.length, selfMs, selfPct: totalMs > 0 ? (100 * selfMs) / totalMs : 0 });
+        }
+        return records.sort((left, right) => right.selfMs - left.selfMs);
+    }
+    report(logLevel = 'debug') {
+        if (logLevel === 'off' || !logger_1.Logger.isLevelEnabled(logLevel)) {
+            return;
+        }
+        const totalMs = this.sessionStopwatch.elapsedMs;
+        const records = this.records();
+        const emit = this.logger[logLevel].bind(this.logger);
+        for (const record of records) {
+            emit(`[profile ${this.identifier}] ${record.id} ×${record.count} ${Math.round(record.selfPct)}% ${logger_1.Format.elapsed(record.selfMs)}`);
+        }
+        const accountedMs = records.reduce((sum, record) => sum + record.selfMs, 0);
+        const unaccountedMs = totalMs - accountedMs;
+        if (unaccountedMs >= 0.5) {
+            const pct = totalMs > 0 ? Math.round((100 * unaccountedMs) / totalMs) : 0;
+            emit(`[profile ${this.identifier}] (unaccounted) ${pct}% ${logger_1.Format.elapsed(unaccountedMs)}`);
+        }
+    }
+}
+exports.DefaultProfileSession = DefaultProfileSession;
+//# sourceMappingURL=profile-session.js.map

package/lib/profile-session.js.map

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

package/lib/profiling.d.ts

@@ -0,0 +1,83 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/** Which dimensions to capture, and the two sampling knobs. All off by default. */
+export interface ProfileCaptureOptions {
+    cpu?: boolean;
+    allocation?: boolean;
+    gc?: boolean;
+    eventLoopDelay?: boolean;
+    /** Also drop a retained `.heapsnapshot` at stop (for the memory analyzer). */
+    heapSnapshot?: boolean;
+    /** CPU sampling interval in µs (implementation default 1000). */
+    cpuIntervalMicros?: number;
+    /** Allocation sampling interval in bytes (implementation default 32768). */
+    allocationIntervalBytes?: number;
+}
+export declare const PROFILING_SCHEMA_VERSION = 1;
+/**
+ * The locked, origin-first artefact kinds (the kind equals the artefact's filename stem).
+ * A closed union so a producer cannot emit a stale or typo'd kind and still
+ * compile — the drift the naming scheme forbids.
+ */
+export type ProfilingArtifactKind = 'server-cpu' | 'server-alloc' | 'server-heap' | 'server-summary' | 'server-latency' | 'server-ast' | 'server-memory-report' | 'server-log' | 'browser-runtime' | 'browser-timeline' | 'browser-heap' | 'browser-console';
+/** One entry in the manifest — a captured file plus enough context for a skill to know what it is. */
+export interface ProfilingArtifact {
+    /** The artefact's origin-first kind; equals its filename stem. */
+    kind: ProfilingArtifactKind;
+    /** Path relative to the manifest (the artefact lives beside it in the session directory). */
+    path: string;
+    /** The window the artefact was captured in, when it is window-scoped. */
+    window?: string;
+    /** Pointer to a compact digest file for a heavy artefact (added by the digest emitters). */
+    digest?: string;
+}
+/** What a skill reads to know what to expect from a run (browser entries only in `app` mode, etc.). */
+export interface ProfilingEnvironment {
+    mode: 'harness' | 'app';
+    /** Whether a cgroup memory controller is present (running in a pod) vs local. */
+    container: boolean;
+    commit?: string;
+    workspace?: string;
+    node: string;
+    windows: {
+        label: string;
+        ms: number;
+    }[];
+}
+/** The `manifest.json` contents — the index over one run's artefacts. */
+export interface ProfilingManifest {
+    /**
+     * Always {@link PROFILING_SCHEMA_VERSION} as written; declared as `number`
+     * because a READER may be newer than the run it is opening. Check it before
+     * trusting any field — an older manifest can be missing fields this
+     * declaration says are required.
+     */
+    schemaVersion: number;
+    /**
+     * Names the session directory the manifest sits in, so it identifies a run
+     * without carrying an absolute path. Unique per run by construction (a
+     * timestamp when the caller supplies none), but nothing enforces that a
+     * caller-supplied id is not reused.
+     */
+    sessionId: string;
+    /**
+     * What the run was captured against — needed to know which artefacts to
+     * expect at all, since the browser kinds only occur in `app` mode, and to
+     * know whether two runs are comparable.
+     */
+    environment: ProfilingEnvironment;
+    /**
+     * Every file written beside the manifest. Presence is the only signal that a
+     * dimension was captured: an artefact for a dimension that was not requested
+     * is absent rather than empty, and a kind may occur more than once when the
+     * run has several windows.
+     */
+    artifacts: ProfilingArtifact[];
+}
+//# sourceMappingURL=profiling.d.ts.map

package/lib/profiling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiling.d.ts","sourceRoot":"","sources":["../src/profiling.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAUlF,mFAAmF;AACnF,MAAM,WAAW,qBAAqB;IACnC,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,8EAA8E;IAC9E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,iEAAiE;IACjE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,4EAA4E;IAC5E,uBAAuB,CAAC,EAAE,MAAM,CAAC;CACnC;AAUD,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAC5B,YAAY,GACZ,cAAc,GACd,aAAa,GACb,gBAAgB,GAChB,gBAAgB,GAChB,YAAY,GACZ,sBAAsB,GACtB,YAAY,GACZ,iBAAiB,GACjB,kBAAkB,GAClB,cAAc,GACd,iBAAiB,CAAC;AAEvB,sGAAsG;AACtG,MAAM,WAAW,iBAAiB;IAC/B,kEAAkE;IAClE,IAAI,EAAE,qBAAqB,CAAC;IAC5B,6FAA6F;IAC7F,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,uGAAuG;AACvG,MAAM,WAAW,oBAAoB;IAClC,IAAI,EAAE,SAAS,GAAG,KAAK,CAAC;IACxB,iFAAiF;IACjF,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC3C;AAED,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAC/B;;;;;OAKG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,WAAW,EAAE,oBAAoB,CAAC;IAClC;;;;;OAKG;IACH,SAAS,EAAE,iBAAiB,EAAE,CAAC;CACjC"}

package/lib/profiling.js

@@ -0,0 +1,20 @@
+"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.PROFILING_SCHEMA_VERSION = void 0;
+/*
+ * The manifest schema — the self-describing index over one profiling run's
+ * artefacts. It lives in `protocol` (not the Node-only `ProfilingRun` that writes
+ * it) so both the server-side assembler AND a Playwright-side assembler can share
+ * the shape without a `node`-only dependency chain. `ProfilingRun` re-exports
+ * these from `@hydranium/core/node`.
+ */
+exports.PROFILING_SCHEMA_VERSION = 1;
+//# sourceMappingURL=profiling.js.map

package/lib/profiling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiling.js","sourceRoot":"","sources":["../src/profiling.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAwBlF;;;;;;GAMG;AAEU,QAAA,wBAAwB,GAAG,CAAC,CAAC"}

package/lib/project.d.ts

@@ -0,0 +1,121 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * Cross-cutting domain type for the project tier — a descriptor-discovered,
+ * optionally versioned and dependency-aware sub-grouping of model files
+ * inside an LSP workspace folder.
+ *
+ * Owned by `@hydranium/protocol` (rather than `@hydranium/core`) so
+ * protocol consumers — including browser-bundle frontend code that
+ * imports the typed data-server proxy — pull this type without
+ * transitively depending on Langium. The `Project` shape is the structural
+ * baseline both the framework's runtime project tier (`ProjectManager` in
+ * `@hydranium/core`) and its wire-level surface (`DataServerProtocol`
+ * methods returning projects) agree on; collapsing them into one
+ * type eliminates a duplicate definition that would otherwise drift.
+ *
+ * **Project tier rationale.** Sits at a tier Langium itself deliberately
+ * does not provide. Langium's `WorkspaceManager` indexes all files in all
+ * workspace folders into one flat global scope; the maintainers have
+ * on-record stated they intend to keep it that way — see
+ * [Discussion #1375 — *Multiple Languages from different Projects*](https://github.com/eclipse-langium/langium/discussions/1375).
+ * This framework fills that gap so consumers don't have to reinvent it.
+ * Consumers that don't need projects bind `SingleProjectManager` and pay
+ * no cost — one synthetic project at runtime, no descriptor tracking,
+ * no events.
+ *
+ * **Extension model.** Adopters with richer per-project metadata declare a
+ * subtype `interface MyProject extends Project { ... }` and parameterise
+ * `ProjectManager<MyProject>` / `DataServer<TRoot, TDiagnostic, MyProject>`.
+ * The framework's structural read from a project is `id` (registry key,
+ * dependency-graph identity) plus optionally `dependencies` (visibility-
+ * closure walk); every other field is either wire metadata (`version`) or
+ * adopter-specific extension carried transparently through the typed
+ * surface. The framework imposes no format on extension fields — they
+ * ride on the JSON-RPC envelope as additional properties when crossing
+ * the wire.
+ */
+export interface Project {
+    /**
+     * Stable, unique identifier. Used as the lookup key in
+     * `ProjectManager.getProjectById` and as the value in
+     * {@link dependencies} entries that point at this project.
+     * Conventionally a name-plus-version string (e.g.
+     * `"example-dwh@1.0.0"`), but the framework imposes no format — any
+     * non-empty string works.
+     *
+     * The framework's internal identifier — map keys, visibility-set
+     * membership, dependency-declaration matching. Distinct from the
+     * user-facing {@link referenceName}; see there for why they are separate.
+     */
+    readonly id: string;
+    /**
+     * User-facing prefix used in qualified-name references that cross
+     * project boundaries. Composed by `NameProvider.getProjectQualifiedName`
+     * to produce the workspace-unique form that the linker resolves
+     * cross-project references against; emitted as the name of the
+     * `TieredAstNodeDescription` produced by
+     * `HydraniumScopeComputation.addExportedSymbol` when the project-
+     * qualified form differs from the document-qualified form.
+     *
+     * Set to {@link UNQUALIFIED_PROJECT_REFERENCE} (`''`) to contribute no
+     * prefix at all — see that constant for the semantics.
+     *
+     * **Why this is a separate field from {@link id}.** Two reasons:
+     *  1. Versioned ids (e.g. `"example-dwh@1.0.0"`) need un-versioned
+     *     names in reference syntax (`example-dwh.User.email`) — the
+     *     version pinning only matters for dependency declarations.
+     *  2. Names with grammar-illegal characters (dots, spaces) need
+     *     sanitisation. The framework cannot safely sanitise {@link id}
+     *     (it would break dependency matching); a separate field lets
+     *     adopters sanitise once at parse time.
+     */
+    readonly referenceName: string;
+    /**
+     * Optional semantic version of the project. Distinct from {@link id}
+     * because two versions of the same logical project are different
+     * projects (different {@link id}s) — `version` is metadata for tooling /
+     * display / version-matched dependency declarations, not part of
+     * identity. The framework does not read this field internally; it
+     * passes through to clients as-is.
+     */
+    readonly version?: string;
+    /**
+     * Ids of other projects this project explicitly depends on. Concrete
+     * `ProjectManager` implementations decide what "depends on" means
+     * and combine these into the visibility closure via
+     * `ProjectManager.getVisibleProjects` — the framework default in
+     * `AbstractProjectManager` walks them transitively; adopters can
+     * override.
+     */
+    readonly dependencies?: readonly string[];
+}
+/**
+ * Sentinel value for {@link Project.referenceName} indicating the
+ * project does not prefix its names with a reference segment. Names
+ * from such projects contribute to the workspace-wide namespace as-is —
+ * `NameProvider.getProjectQualifiedName` collapses to
+ * `getDocumentQualifiedName`, and `HydraniumScopeComputation` emits a
+ * single description per node (no separate `tier: 'public'` entry,
+ * since it would carry the same name).
+ *
+ * Typical use:
+ * - `SingleProjectManager` workspaces (no inter-project disambiguation
+ *   needed — there is only one project, the synthetic workspace project).
+ * - Adopters whose grammar has no qualified-name reference syntax (e.g.
+ *   class references written as bare `[Class:ID]` tokens at the framework
+ *   boundary; per-package projects all bind this sentinel).
+ *
+ * The empty string is chosen so that `referenceName + nameSeparator + name`
+ * compositions detect the unqualified case without an explicit null
+ * check on the consumer side — but for predicate readability prefer
+ * `ProjectManager.isUnqualifiedProjectReference(uri)`.
+ */
+export declare const UNQUALIFIED_PROJECT_REFERENCE = "";
+//# sourceMappingURL=project.d.ts.map

package/lib/project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,WAAW,OAAO;IACrB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAE1B;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,6BAA6B,KAAK,CAAC"}

package/lib/project.js

@@ -0,0 +1,34 @@
+"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.UNQUALIFIED_PROJECT_REFERENCE = void 0;
+/**
+ * Sentinel value for {@link Project.referenceName} indicating the
+ * project does not prefix its names with a reference segment. Names
+ * from such projects contribute to the workspace-wide namespace as-is —
+ * `NameProvider.getProjectQualifiedName` collapses to
+ * `getDocumentQualifiedName`, and `HydraniumScopeComputation` emits a
+ * single description per node (no separate `tier: 'public'` entry,
+ * since it would carry the same name).
+ *
+ * Typical use:
+ * - `SingleProjectManager` workspaces (no inter-project disambiguation
+ *   needed — there is only one project, the synthetic workspace project).
+ * - Adopters whose grammar has no qualified-name reference syntax (e.g.
+ *   class references written as bare `[Class:ID]` tokens at the framework
+ *   boundary; per-package projects all bind this sentinel).
+ *
+ * The empty string is chosen so that `referenceName + nameSeparator + name`
+ * compositions detect the unqualified case without an explicit null
+ * check on the consumer side — but for predicate readability prefer
+ * `ProjectManager.isUnqualifiedProjectReference(uri)`.
+ */
+exports.UNQUALIFIED_PROJECT_REFERENCE = '';
+//# sourceMappingURL=project.js.map

package/lib/project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.js","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAgGlF;;;;;;;;;;;;;;;;;;;;GAoBG;AACU,QAAA,6BAA6B,GAAG,EAAE,CAAC"}

package/lib/rpc/bind-rpc-methods.d.ts

@@ -0,0 +1,100 @@
+/********************************************************************************
+ * 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 { LatencyCollector } from '../latency-collector';
+import { type Disposable } from '../util';
+/**
+ * Options controlling how method names are translated into wire-method
+ * registrations on the supplied connection. The defaults match
+ * `createRpcProxy` so the two helpers compose cleanly: an adopter
+ * defining a contract `T` registers handlers with `bindRpcMethods(conn, target, names, opts)`
+ * on one side and a typed proxy with `createRpcProxy<T>(conn, opts)` on
+ * the other — same wire prefix, same notification heuristic, no drift.
+ */
+export interface BindRpcMethodsOptions {
+    /**
+     * Prefix prepended to each method name to form the JSON-RPC wire string.
+     * Defaults to the empty string.
+     */
+    readonly methodNamespace?: string;
+    /**
+     * Predicate to discriminate notification methods from request methods.
+     * Notification methods register with `connection.onNotification`;
+     * request methods register with `connection.onRequest`. Default: `on`
+     * followed by an uppercase letter marks a notification, matching
+     * `createRpcProxy`.
+     */
+    readonly isNotification?: (methodName: string) => boolean;
+    /**
+     * When `true` (the default), every name in `methodNames` MUST exist
+     * as a function on `target` — missing names throw at attach time. This
+     * catches typos in adopter-supplied `additionalMethods` arrays where
+     * the names are string literals.
+     *
+     * Set to `false` to fall back to the silent-skip behaviour (useful
+     * for transitional method-name lists where some methods are not yet
+     * implemented on every target).
+     */
+    readonly requireAll?: boolean;
+    /**
+     * Invoked when a notification handler throws. Notifications have no reply
+     * channel, so the error cannot propagate back to the caller; this hook
+     * lets a caller that holds a logger route the failure somewhere
+     * structured. Receives the wire-method name and the thrown value.
+     *
+     * Defaults to `console.error` — the protocol layer carries no logger of
+     * its own, and a caller in a process whose stdout is not the JSON-RPC
+     * transport (the framework's IPC / socket heads) can leave the default in
+     * place. Callers binding handlers over a `--stdio` LSP connection should
+     * pass a hook that routes through `connection.console` instead.
+     */
+    readonly onNotificationError?: (wireName: string, error: unknown) => void;
+    /**
+     * When supplied, every dispatched handler is timed into this collector under
+     * its wire name (`<prefix><methodName>`) — the single RPC chokepoint the
+     * latency/throughput surface hooks, so no per-handler change is needed.
+     * Requests and notifications are both timed. Absent by default (no overhead).
+     */
+    readonly latency?: LatencyCollector;
+}
+/**
+ * Register each named method on `target` as a handler on `connection`
+ * under the wire-name `<prefix><methodName>`. Notification methods (by
+ * default `on` + an uppercase letter) register as fire-and-forget listeners; request
+ * methods register as request handlers and propagate the method's return
+ * value back to the caller.
+ *
+ * The returned disposable tears down every registered handler in one call —
+ * sufficient for the framework's lifecycle: bind handlers at construction,
+ * dispose at shutdown.
+ *
+ * Method dispatch always passes the JSON-RPC `params` to the target
+ * method as a single argument. This matches the single-arg-per-method
+ * convention used throughout the framework's typed contracts — adopters
+ * defining methods with multiple positional parameters would need a
+ * different binder.
+ *
+ * Errors thrown synchronously from a request handler — or surfaced as a
+ * rejected promise — propagate back to the caller through vscode-jsonrpc's
+ * standard error envelope. Errors from a notification handler cannot, and are
+ * routed to {@link BindRpcMethodsOptions.onNotificationError} instead.
+ *
+ * Accepts either a ready connection or a `Promise<MessageConnection>` —
+ * registrations queue until the connection resolves, then attach. The
+ * returned disposable can be invoked at any time: if it fires before the
+ * connection resolves the queued work is cancelled and never attaches;
+ * if it fires afterwards the registrations dispose normally. Mirrors
+ * `createRpcProxy`'s deferred-connection pattern so adopters can wire
+ * inbound handlers in `@postConstruct` before the underlying transport
+ * exists. Wire-side safety: no notifications can arrive before
+ * `connection.listen()` runs, so a not-yet-attached handler cannot drop
+ * a real message.
+ */
+export declare function bindRpcMethods<T extends object>(connection: MessageConnection | Promise<MessageConnection>, target: T, methodNames: readonly (keyof T & string)[], options?: BindRpcMethodsOptions): Disposable;
+//# sourceMappingURL=bind-rpc-methods.d.ts.map

package/lib/rpc/bind-rpc-methods.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bind-rpc-methods.d.ts","sourceRoot":"","sources":["../../src/rpc/bind-rpc-methods.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,KAAK,UAAU,EAAwB,MAAM,SAAS,CAAC;AAIhE;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACnC;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAElC;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC;IAE1D;;;;;;;;;OASG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAE9B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAE1E;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC;CACtC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,EAC5C,UAAU,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,EAC1D,MAAM,EAAE,CAAC,EACT,WAAW,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,EAAE,EAC1C,OAAO,GAAE,qBAA0B,GACnC,UAAU,CAmEZ"}

package/lib/rpc/bind-rpc-methods.js

@@ -0,0 +1,110 @@
+"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.bindRpcMethods = bindRpcMethods;
+const util_1 = require("../util");
+const create_rpc_proxy_1 = require("./create-rpc-proxy");
+const wire_prefix_1 = require("./wire-prefix");
+/**
+ * Register each named method on `target` as a handler on `connection`
+ * under the wire-name `<prefix><methodName>`. Notification methods (by
+ * default `on` + an uppercase letter) register as fire-and-forget listeners; request
+ * methods register as request handlers and propagate the method's return
+ * value back to the caller.
+ *
+ * The returned disposable tears down every registered handler in one call —
+ * sufficient for the framework's lifecycle: bind handlers at construction,
+ * dispose at shutdown.
+ *
+ * Method dispatch always passes the JSON-RPC `params` to the target
+ * method as a single argument. This matches the single-arg-per-method
+ * convention used throughout the framework's typed contracts — adopters
+ * defining methods with multiple positional parameters would need a
+ * different binder.
+ *
+ * Errors thrown synchronously from a request handler — or surfaced as a
+ * rejected promise — propagate back to the caller through vscode-jsonrpc's
+ * standard error envelope. Errors from a notification handler cannot, and are
+ * routed to {@link BindRpcMethodsOptions.onNotificationError} instead.
+ *
+ * Accepts either a ready connection or a `Promise<MessageConnection>` —
+ * registrations queue until the connection resolves, then attach. The
+ * returned disposable can be invoked at any time: if it fires before the
+ * connection resolves the queued work is cancelled and never attaches;
+ * if it fires afterwards the registrations dispose normally. Mirrors
+ * `createRpcProxy`'s deferred-connection pattern so adopters can wire
+ * inbound handlers in `@postConstruct` before the underlying transport
+ * exists. Wire-side safety: no notifications can arrive before
+ * `connection.listen()` runs, so a not-yet-attached handler cannot drop
+ * a real message.
+ */
+function bindRpcMethods(connection, target, methodNames, options = {}) {
+    const methodNamespace = options.methodNamespace ?? '';
+    (0, wire_prefix_1.assertValidMethodNamespace)(methodNamespace, 'bindRpcMethods');
+    const isNotification = options.isNotification ?? create_rpc_proxy_1.defaultIsNotification;
+    const requireAll = options.requireAll ?? true;
+    const onNotificationError = options.onNotificationError ??
+        ((wireName, error) => console.error(`[bindRpcMethods] notification handler '${wireName}' threw:`, error));
+    const disposables = new util_1.DisposableCollection();
+    let cancelled = false;
+    const attach = (resolved) => {
+        if (cancelled) {
+            return;
+        }
+        for (const methodName of methodNames) {
+            const wireName = methodNamespace + methodName;
+            const method = target[methodName];
+            if (typeof method !== 'function') {
+                if (requireAll) {
+                    throw new Error(`bindRpcMethods: method '${methodName}' is not a function on the target. ` +
+                        `Either fix the typo, implement the method, or pass { requireAll: false } to opt into silent-skip ` +
+                        'for transitional method-name lists.');
+                }
+                continue;
+            }
+            const bound = method.bind(target);
+            // Time the dispatch at this one chokepoint when a collector is present.
+            const latency = options.latency;
+            const dispatch = latency ? (params) => latency.time(wireName, () => bound(params)) : bound;
+            if (isNotification(methodName)) {
+                disposables.push(resolved.onNotification(wireName, (params) => {
+                    try {
+                        dispatch(params);
+                    }
+                    catch (err) {
+                        onNotificationError(wireName, err);
+                    }
+                }));
+            }
+            else {
+                disposables.push(resolved.onRequest(wireName, async (params) => dispatch(params)));
+            }
+        }
+    };
+    if (connection instanceof Promise) {
+        void connection
+            .then(resolved => attach(resolved))
+            .catch(() => {
+            // Connection promise rejected — treat as never-resolved; nothing
+            // to register. Adopters observe transport failures through their
+            // own connection-construction error handling.
+        });
+    }
+    else {
+        attach(connection);
+    }
+    return {
+        dispose() {
+            cancelled = true;
+            disposables.dispose();
+        }
+    };
+}
+//# sourceMappingURL=bind-rpc-methods.js.map

package/lib/rpc/bind-rpc-methods.js.map

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