@hydranium/glsp-server 1.0.0-next.10

package/src/command/hydranium-glsp-recording-command.ts

@@ -0,0 +1,183 @@
+/********************************************************************************
+ * Copyright (c) 2023-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 AnyObject, type JsonModelState, JsonRecordingCommand, type MaybePromise } from '@eclipse-glsp/server';
+import { type AstNode } from '@hydranium/langium';
+import { type AbstractHydraniumGlspState } from '../state/abstract-hydranium-glsp-state.js';
+
+/**
+ * Source-model state shape consumed by {@link HydraniumGlspRecordingCommand}.
+ * The intersection ties together GLSP's read-side
+ * {@link JsonModelState.sourceModel} getter with the framework's typed
+ * `logger` and `sourceUri` accessors (used for time-labelled logging) and
+ * the lifted `updateSourceModel` abstract from
+ * {@link AbstractHydraniumGlspState.updateSourceModel}. Adopter states satisfy both
+ * naturally by implementing `JsonModelState<TSourceModel>` on
+ * their framework-state subclass.
+ */
+export type HydraniumGlspRecordingState<TSourceModel extends AnyObject> = AbstractHydraniumGlspState<AstNode, TSourceModel> &
+   JsonModelState<TSourceModel>;
+
+/**
+ * GLSP {@link JsonRecordingCommand} base shared by all hydranium adopters.
+ * Adds two things on top of GLSP's class:
+ *
+ *  1. A **time-labelled execute wrapper** so log lines record how long a
+ *     user-facing operation takes end-to-end — including the `postChange`
+ *     source-model update that re-parses the document. Otherwise the diff +
+ *     patch + persist work happens silently and is hard to attribute when
+ *     something is slow.
+ *  2. A typed `state` field that exposes `updateSourceModel` for the
+ *     `postChange` bridge AND the framework `logger` for time-labelled
+ *     logging. GLSP's base class only types `modelState: JsonModelState`,
+ *     which lacks the framework's logger surface.
+ *
+ * **Optional undo/redo bridge hooks.** An adopter command can supply
+ * `undoAction` / `redoAction` callbacks invoked alongside the patch apply, to
+ * re-emit a side-effect the patch itself does not carry. Provided as optional
+ * constructor args so adopters get that composition surface without
+ * subclassing. Operation handlers that don't need bridge callbacks omit them.
+ *
+ * **postChange semantics.** GLSP's `JsonRecordingCommand.postChange` calls
+ * `modelState.updateSourceModel(newModel)` with the model only. The
+ * framework lift overrides `postChange` so it also threads the based-on
+ * version captured at command start — letting the downstream
+ * `ModelService.update` opt into the `ConflictError` gate. Undo / redo
+ * postChange calls run with version `undefined` (no gating): the user
+ * authored against the recorded patch, not against a specific server
+ * version, so re-applying it should succeed regardless of intervening
+ * edits. The recorded patch itself encodes the semantic intent.
+ */
+export class HydraniumGlspRecordingCommand<TSourceModel extends AnyObject> extends JsonRecordingCommand<TSourceModel> {
+   declare protected modelState: HydraniumGlspRecordingState<TSourceModel>;
+
+   /**
+    * Based-on version captured at {@link execute} start; threaded into
+    * {@link postChange} so {@link AbstractHydraniumGlspState.updateSourceModel}
+    * sees the version the user authored against. Cleared after `execute`
+    * returns so undo / redo paths fall through to `updateSourceModel`
+    * without a version (no gating).
+    */
+   protected activeVersion?: number;
+
+   /**
+    * Source-model snapshots captured at {@link execute} — the state the
+    * command left ({@link afterSnapshot}) and the state it started from
+    * ({@link beforeSnapshot}). {@link undo} / {@link redo} reconcile the
+    * recorded transition against the *current* source model via the state's
+    * {@link AbstractHydraniumGlspState.conflictResolver}, so under the default
+    * reconciling policy a concurrent edit to another field survives and a
+    * same-field collision is dropped rather than clobbered.
+    */
+   protected beforeSnapshot?: TSourceModel;
+   protected afterSnapshot?: TSourceModel;
+
+   constructor(
+      modelState: HydraniumGlspRecordingState<TSourceModel>,
+      /** Human-readable label for the operation; appears in the timing-pair log line. */
+      protected readonly label: string,
+      doExecute: () => MaybePromise<void>,
+      /** Optional bridge invoked alongside undo patch application; for adopters
+       *  that need to re-emit a side-effect the patch does not carry. */
+      protected readonly undoAction?: () => MaybePromise<void>,
+      /** Optional bridge invoked alongside redo patch application. */
+      protected readonly redoAction?: () => MaybePromise<void>
+   ) {
+      super(modelState, doExecute);
+   }
+
+   /**
+    * Time-label the full execute path: pre-state snapshot + `doExecute` +
+    * post-state snapshot + patch-derive + `postChange` (which writes back
+    * via {@link AbstractHydraniumGlspState.updateSourceModel}). The label combines
+    * the operation name with the source-uri-stamped logger.
+    *
+    * Captures {@link AbstractHydraniumGlspState.version} at start so {@link postChange}
+    * can thread the based-on version into `updateSourceModel`. The capture
+    * is `try`/`finally`-scoped so undo / redo paths invoked later do not
+    * see a stale captured version.
+    */
+   override async execute(): Promise<void> {
+      const logger = this.modelState.logger.for('HydraniumGlspRecordingCommand');
+      this.activeVersion = this.modelState.version;
+      logger.debug(`Executing '${this.label}' (based-on doc.version=v${this.activeVersion})`);
+      this.beforeSnapshot = this.deepClone(await this.getJsonObject());
+      try {
+         await this.modelState.tracer.for('HydraniumGlspRecordingCommand').time(`Execute command '${this.label}'`, () => super.execute());
+      } finally {
+         this.activeVersion = undefined;
+      }
+      this.afterSnapshot = this.deepClone(await this.getJsonObject());
+   }
+
+   /**
+    * Override of GLSP's {@link JsonRecordingCommand.postChange} so the
+    * call to {@link AbstractHydraniumGlspState.updateSourceModel} threads the
+    * captured based-on version alongside the new model.
+    *
+    * During {@link execute} the version is the snapshot captured at
+    * command start; during {@link undo} / {@link redo} it is `undefined`
+    * — replaying a recorded patch does not author against a specific
+    * server version, so no gate applies.
+    */
+   protected override postChange(newModel: TSourceModel): MaybePromise<void> {
+      return this.modelState.updateSourceModel(newModel, this.activeVersion);
+   }
+
+   /**
+    * Reconcile the recorded `after → before` transition against the
+    * *current* source model via the state's
+    * {@link AbstractHydraniumGlspState.conflictResolver}, invoke the optional adopter
+    * `undoAction`, and persist via `postChange`. Under the default reconciling
+    * policy the revert is replayed guarded by `test` ops, so a concurrent edit
+    * to another field is preserved (merged) and a same-field collision is
+    * dropped rather than clobbered; a force policy clobbers (last-writer-wins).
+    * On anything but a clean merge the undo is a logged no-op — the side-effect
+    * bridge and `postChange` only run on a merged result, preserving a
+    * "bridge before commit" order.
+    */
+   override async undo(): Promise<void> {
+      if (!this.undoPatch || this.beforeSnapshot === undefined || this.afterSnapshot === undefined) {
+         return;
+      }
+      const logger = this.modelState.logger.for('HydraniumGlspRecordingCommand');
+      logger.debug(`Undoing '${this.label}' at doc.version=v${this.modelState.version}`);
+      const outcome = await this.modelState.conflictResolver.resolve(this.afterSnapshot, this.beforeSnapshot, async () =>
+         this.getJsonObject()
+      );
+      if (outcome.status !== 'merged') {
+         logger.warn(`Undo '${this.label}' skipped (${outcome.status}); a foreign edit changed a shared field since the command ran`);
+         return;
+      }
+      await this.undoAction?.();
+      await this.postChange?.(outcome.merged);
+   }
+
+   /**
+    * Reconcile the recorded `before → after` transition against the current
+    * source model, invoke the optional adopter `redoAction`, and persist via
+    * `postChange`. Same guarded merge / drop semantics as {@link undo}.
+    */
+   override async redo(): Promise<void> {
+      if (!this.redoPatch || this.beforeSnapshot === undefined || this.afterSnapshot === undefined) {
+         return;
+      }
+      const logger = this.modelState.logger.for('HydraniumGlspRecordingCommand');
+      logger.debug(`Redoing '${this.label}' at doc.version=v${this.modelState.version}`);
+      const outcome = await this.modelState.conflictResolver.resolve(this.beforeSnapshot, this.afterSnapshot, async () =>
+         this.getJsonObject()
+      );
+      if (outcome.status !== 'merged') {
+         logger.warn(`Redo '${this.label}' skipped (${outcome.status}); a foreign edit changed a shared field since the undo`);
+         return;
+      }
+      await this.redoAction?.();
+      await this.postChange?.(outcome.merged);
+   }
+}

package/src/command/index.ts

@@ -0,0 +1,10 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+export * from './hydranium-glsp-recording-command.js';

package/src/computed-bounds/hydranium-glsp-computed-bounds-action-handler.ts

@@ -0,0 +1,103 @@
+/********************************************************************************
+ * 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 Action,
+   type ComputedBoundsAction,
+   ComputedBoundsActionHandler,
+   type GModelRoot,
+   type MaybePromise
+} from '@eclipse-glsp/server';
+import { type AstNode } from '@hydranium/langium';
+import { injectable } from 'inversify';
+import { type AbstractHydraniumGlspState } from '../state/abstract-hydranium-glsp-state.js';
+import { type HydraniumGlspSubmissionHandler } from '../submission/hydranium-glsp-submission-handler.js';
+
+/**
+ * GLSP {@link ComputedBoundsActionHandler} base shared by all hydranium
+ * adopters. Adds handshake-aware revision-mismatch logging on top of the
+ * upstream handler.
+ *
+ * **Why the lift.** GLSP's base silently returns `[]` on a revision
+ * mismatch — benign for stale post-drag bounds (the user moved an element,
+ * the server-side GModel got re-rendered before the client's pre-move
+ * `computedBounds` arrived; dropping the stale frame is correct). But
+ * catastrophic during the initial `requestModel → setModel` handshake: if the
+ * very first `computedBounds` arrives with a revision the server has already
+ * bumped, the subsequent `SetModelAction` response never fires and the diagram
+ * stays stuck at "model loading…". Adopters need this initial-handshake case
+ * surfaced as a warning so the failure mode is visible in logs.
+ *
+ * **Handshake detection** uses
+ * {@link HydraniumGlspSubmissionHandler.hasPendingInitialRequest} — true
+ * while a `RequestModelAction` has been accepted but the corresponding
+ * `SetModelAction` has not yet been dispatched. Adopters that override
+ * `submitModel` flow must preserve the `hasPendingInitialRequest` semantics
+ * for this logging to remain accurate.
+ *
+ * **Customisation.** The class is shipped non-abstract because the default
+ * body fits common adopters, which bind it directly. Adopters with
+ * bounds-specific cleanup subclass and override `applyBounds`.
+ */
+@injectable()
+export class HydraniumGlspComputedBoundsActionHandler extends ComputedBoundsActionHandler {
+   declare protected readonly modelState: AbstractHydraniumGlspState<AstNode, unknown>;
+   declare protected readonly submissionHandler: HydraniumGlspSubmissionHandler<AstNode, unknown>;
+
+   override execute(action: ComputedBoundsAction): MaybePromise<Action[]> {
+      this.modelState.logger.debug(`ComputedBoundsActionHandler.execute entered: action.revision=${action.revision}`);
+      const model = this.modelState.root;
+      if (action.revision !== model.revision) {
+         if (this.submissionHandler.hasPendingInitialRequest()) {
+            this.modelState.logger.warn(
+               `ComputedBounds rejected (initial handshake): action.revision=${action.revision} model.revision=${model.revision} — ` +
+                  'initial SetModelAction will not fire (empty diagram)'
+            );
+         } else {
+            this.modelState.logger.debug(
+               `ComputedBounds dropped (stale): action.revision=${action.revision} model.revision=${model.revision} — ` +
+                  'bounds belong to a superseded GModel; safe to ignore'
+            );
+         }
+         return [];
+      }
+      this.modelState.logger.trace(`ComputedBounds accepted: revision=${action.revision}, bounds=${action.bounds?.length ?? 0}`);
+      return super.execute(action);
+   }
+
+   /**
+    * Defensively filter routes that lack the source+target endpoints upstream
+    * `applyRoute` requires (`newRoutingPoints.length >= 2`). Without this,
+    * the upstream handler throws `GLSPServerError: Invalid Route!` and the
+    * entire `computedBounds` action is rejected — the diagram never settles.
+    *
+    * The race that produces these routes is benign and common on the
+    * initial layout pass: the GModel factory emits an edge with no explicit
+    * `routingPoints`, the client schedules the edge for routing but submits
+    * `computedBounds` before the routing pass finishes, so the route shows
+    * up with 0 or 1 point. Subsequent `computedBounds` actions carry the
+    * fully-routed edges; dropping the incomplete ones here is lossless.
+    *
+    * Adopters with bounds-specific cleanup — clearing ALL routes so the client
+    * re-routes on the next layout, say — override and replace this filter.
+    */
+   protected override applyBounds(root: GModelRoot, action: ComputedBoundsAction): void {
+      if (action.routes && action.routes.length > 0) {
+         const original = action.routes.length;
+         action.routes = action.routes.filter(route => (route.newRoutingPoints?.length ?? 0) >= 2);
+         const dropped = original - action.routes.length;
+         if (dropped > 0) {
+            this.modelState.logger.debug(
+               `ComputedBounds dropped ${dropped}/${original} route(s) with <2 routing points — client hasn't finished routing yet`
+            );
+         }
+      }
+      super.applyBounds(root, action);
+   }
+}

package/src/computed-bounds/index.ts

@@ -0,0 +1,10 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+export * from './hydranium-glsp-computed-bounds-action-handler.js';

package/src/dispatcher/index.ts

@@ -0,0 +1,10 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+export * from './server-action-dispatcher.js';

package/src/dispatcher/server-action-dispatcher.ts

@@ -0,0 +1,72 @@
+/********************************************************************************
+ * Copyright (c) 2023-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 Action, DefaultActionDispatcher } from '@eclipse-glsp/server';
+import { inject, injectable } from 'inversify';
+import { type Tracer } from '@hydranium/protocol';
+import { type GlspClientLogger } from '../logging/glsp-client-logger.js';
+import { HydraniumTypes } from '../state/hydranium-shared-core-services.js';
+
+/**
+ * Server-side action dispatcher with built-in traffic observability:
+ * every {@link DefaultActionDispatcher.dispatch} call is wrapped in a
+ * {@link Tracer.time} pair that records the dispatch direction
+ * (`→ client` vs `→ server`) and timing.
+ *
+ * **Why this lives in the framework (vs left as an adopter override).**
+ * Debugging GLSP state, storage, and submission flows depends heavily on
+ * seeing each action with timing and direction — especially when bringing
+ * up a new adopter against an empty/partial diagram before its submission
+ * flow is complete. Providing this dispatcher in the framework gives every
+ * adopter the same observability primitive from the very first GLSP-head
+ * launch.
+ *
+ * **Extension points.**
+ * - {@link loggedKinds} — if set, filter the log lines (the dispatch
+ *   still happens; only the bracketed timing line is suppressed). Default
+ *   `undefined` means **every** action's dispatch is timed and logged.
+ * - {@link summarize} — return a non-empty string to append `[summary]`
+ *   to the log line; default returns `''` (no extra bracket).
+ *
+ * Adopters bind it in a per-diagram module, as the `ActionDispatcher` service.
+ */
+@injectable()
+export class HydraniumGlspServerActionDispatcher extends DefaultActionDispatcher {
+   /** Narrowed from `Logger`; DI binds {@link GlspClientLogger}. */
+   declare protected readonly logger: GlspClientLogger;
+
+   /** Caller-tagged tracer (auto-componented with this class name, like the logger). */
+   @inject(HydraniumTypes.Tracer) protected readonly tracer!: Tracer;
+
+   /**
+    * If set, the timing log line is emitted only when `action.kind` is in
+    * this set. Subclasses override via field reassignment.
+    */
+   protected readonly loggedKinds: ReadonlySet<string> | undefined = undefined;
+
+   /**
+    * Override to enrich the log line with payload-specific detail. Return an
+    * empty string to suppress the bracket. Default returns `''`.
+    */
+   protected summarize(_action: Action): string {
+      return '';
+   }
+
+   override dispatch(action: Action): Promise<void> {
+      if (this.loggedKinds && !this.loggedKinds.has(action.kind)) {
+         return super.dispatch(action);
+      }
+      const direction = this.clientActionForwarder.shouldForwardToClient(action) ? '→ client' : '→ server';
+      const summary = this.summarize(action);
+      const label = summary
+         ? `Dispatch action '${action.kind}' ${direction} [${summary}]`
+         : `Dispatch action '${action.kind}' ${direction}`;
+      return this.tracer.time(label, () => super.dispatch(action));
+   }
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+// Public API barrel for `@hydranium/glsp-server` — the GLSP protocol head.
+export * from './command/index.js';
+export * from './computed-bounds/index.js';
+export * from './dispatcher/index.js';
+export * from './launcher/index.js';
+export * from './logging/index.js';
+export * from './state/index.js';
+export * from './storage/index.js';
+export * from './submission/index.js';
+export * from './util/index.js';
+export * from './validation/index.js';

package/src/launcher/abstract-hydranium-glsp-diagram-module.ts

@@ -0,0 +1,117 @@
+/********************************************************************************
+ * 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 { DiagramModule } from '@eclipse-glsp/server';
+import { injectable, type interfaces } from 'inversify';
+import type { LanguageMetaData } from '@hydranium/langium';
+import { type ServerLanguageServices, type ServerSharedServices, typedMetadata } from '@hydranium/core';
+import { HydraniumTypes } from '../state/hydranium-shared-core-services.js';
+
+/**
+ * Bind {@link HydraniumTypes}.DiagramLanguage on a GLSP **session** container
+ * to the services of `metadata`'s grammar.
+ *
+ * Exported separately from {@link AbstractHydraniumGlspDiagramModule} for adopters
+ * whose diagram module already extends an intermediate base of their own and
+ * cannot take the framework base class; call it from `configure` after
+ * `super.configure(...)`. The base class is the preferred entry point because
+ * it makes the declaration non-optional.
+ *
+ * **Why the session tier.** GLSP builds its app container once per process,
+ * before any document exists, so a per-language service bound there can only
+ * ever be one grammar's. The session container is created per open diagram
+ * with its `diagramType` known, and a diagram type has exactly one grammar —
+ * so the language is a static fact about the module, resolvable with no URI
+ * and no ordering hazard. That last part is load-bearing: GLSP's
+ * `OperationHandlerRegistryInitializer` constructs every operation handler at
+ * `InitializeClientSession`, i.e. BEFORE `RequestModelAction` supplies the
+ * source URI, so anything derived from `ModelState.sourceUri` at injection
+ * time would throw on every diagram open.
+ *
+ * **The whole language, not pre-resolved providers.** There is deliberately no
+ * token for an individual per-language provider; see {@link HydraniumTypes} for
+ * why. Callers reach `modelState.diagramLanguage` or
+ * `modelState.languageServicesFor(node)` instead, which name the choice.
+ *
+ * Resolution is `toDynamicValue` + `inSingletonScope` — deferred so the parent
+ * container's `SharedCoreServices` is available, then resolved once per
+ * session rather than per injection.
+ */
+export function bindDiagramLanguage(bind: interfaces.Bind, metadata: LanguageMetaData): void {
+   bind(HydraniumTypes.DiagramLanguage)
+      .toDynamicValue(context => resolveDiagramLanguage(context.container, metadata))
+      .inSingletonScope();
+}
+
+/**
+ * The registered services for `metadata`'s language, or a throw naming both
+ * the declared id and the registered ones.
+ *
+ * Failing loudly is the point: the declared language is the one fact this
+ * module states that the grammar does not, so it can drift. An unregistered id
+ * means the adopter declared a language they never registered — a wiring
+ * mistake whose silent form (falling back to some other grammar's providers)
+ * would surface much later as references that resolve against the wrong scope.
+ */
+function resolveDiagramLanguage(container: interfaces.Container, metadata: LanguageMetaData): ServerLanguageServices {
+   const registry = container.get<ServerSharedServices>(HydraniumTypes.SharedCoreServices).ServiceRegistry;
+   const language = registry.getServices(typedMetadata<ServerLanguageServices>(metadata));
+   if (!language) {
+      const registered = registry.all.map(candidate => candidate.LanguageMetaData.languageId);
+      throw new Error(
+         `Diagram module declares language '${metadata.languageId}', which is not registered on the ServiceRegistry. ` +
+            `Registered languages: ${registered.length > 0 ? registered.join(', ') : '(none)'}. ` +
+            'Declare the languageId of a grammar passed to bootstrapLangiumLanguages.'
+      );
+   }
+   return language;
+}
+
+/**
+ * GLSP {@link DiagramModule} base that declares which grammar its diagram type
+ * edits, and binds that language's per-language services on the session
+ * container.
+ *
+ * Subclass instead of `DiagramModule` and implement {@link declareLanguage}
+ * alongside `diagramType`; the two are the same kind of fact about a diagram
+ * type, and pairing them is what lets one GLSP head serve N grammars.
+ *
+ * Adopter GLSP components then read the language they mean:
+ * `modelState.diagramLanguage.references.CandidateProvider` for a reference
+ * written on the canvas, `modelState.languageServicesFor(node).references.X`
+ * for anything reached through a reference. No per-language service is bound
+ * to a token of its own — see {@link bindDiagramLanguage} for why.
+ */
+@injectable()
+export abstract class AbstractHydraniumGlspDiagramModule extends DiagramModule {
+   /**
+    * The `LanguageMetaData` of the grammar this diagram type edits — pass the
+    * generated `<Grammar>LanguageMetaData` constant directly.
+    *
+    * Abstract rather than optional so a new diagram module cannot silently
+    * omit it: a missing declaration is a compile error here, where the fix is
+    * obvious, instead of an unbound-token failure at the first diagram open.
+    *
+    * NOT named `bindLanguage`: every `bindX()` on GLSP's `DiagramModule`
+    * returns a `BindingTarget<T>` that GLSP's own `configure` consumes, and a
+    * method in that family returning a `LanguageMetaData` invites
+    * `{ service: … }`. This one states a fact; the framework does the binding.
+    */
+   protected abstract declareLanguage(): LanguageMetaData;
+
+   protected override configure(
+      bind: interfaces.Bind,
+      unbind: interfaces.Unbind,
+      isBound: interfaces.IsBound,
+      rebind: interfaces.Rebind
+   ): void {
+      super.configure(bind, unbind, isBound, rebind);
+      bindDiagramLanguage(bind, this.declareLanguage());
+   }
+}

package/src/launcher/glsp-app-module.ts

@@ -0,0 +1,106 @@
+/********************************************************************************
+ * 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 { GLSPModule } from '@eclipse-glsp/server';
+import type { BindingContext } from '@eclipse-glsp/protocol/lib/di/inversify-util.js';
+import type { ServerSharedServices } from '@hydranium/core';
+import { type ConflictResolver, ReconcilingConflictResolver } from '@hydranium/protocol';
+import { injectable, type interfaces } from 'inversify';
+import { HydraniumTypes } from '../state/hydranium-shared-core-services.js';
+
+/**
+ * Configuration accepted by {@link HydraniumGlspAppModule}. Bundles the
+ * framework-defined Inversify bindings every adopter wires verbatim in their
+ * GLSP server app-module (the `appModules` argument to `startGlspServer`).
+ *
+ * **App tier only, so nothing per-language belongs here.** This module is
+ * loaded into the one-per-process app container, built before any document
+ * exists — it cannot know which grammar a request concerns. Per-language
+ * services are declared per diagram type instead; see
+ * `AbstractHydraniumGlspDiagramModule`.
+ */
+export interface HydraniumGlspAppModuleOptions<TShared extends ServerSharedServices = ServerSharedServices> {
+   /**
+    * The framework's Langium-style shared services tree. Bound to the
+    * `HydraniumTypes.SharedCoreServices` symbol that framework state /
+    * index classes (`AbstractHydraniumGlspState`, `HydraniumGlspIndex`) `@inject`.
+    *
+    * Generic over `TShared` so adopters with their own narrower
+    * shared-services type (an adopter-specific type extending
+    * `ServerSharedServices` with extra slots) preserve that
+    * type at `this.options.shared` inside subclass methods without an
+    * explicit cast. The Inversify symbol binding still types `@inject`
+    * sites as the wider `ServerSharedServices`; specialise the binding
+    * with an adopter-specific symbol where injected components want the
+    * narrower view.
+    */
+   readonly shared: TShared;
+
+   /**
+    * Optional {@link ConflictResolver} policy bound to the
+    * `HydraniumTypes.ConflictResolver` symbol that `AbstractHydraniumGlspState`
+    * injects. Omit to get the framework default
+    * ({@link ReconcilingConflictResolver} — field-level three-way merge);
+    * pass a `ForceConflictResolver` for
+    * last-writer-wins, or a custom resolver. Applies uniformly to every
+    * conflict site (forward-write, undo, redo, save).
+    */
+   readonly conflictResolver?: ConflictResolver;
+}
+
+/**
+ * DI module that provides the framework-level Inversify bindings every
+ * `@hydranium/glsp-server` adopter needs. Pass instances (or instances of
+ * subclasses with additional bindings) into `startGlspServer`'s
+ * `appModules` array.
+ *
+ * Bindings provided:
+ *  - `HydraniumTypes.SharedCoreServices` (constant value)
+ *  - `HydraniumTypes.ConflictResolver` (constant value — `options.conflictResolver` or a default {@link ReconcilingConflictResolver})
+ *
+ * Both are language-independent, which is what makes them app-tier. The
+ * per-language providers (`ScopeProvider`, `CandidateProvider`) are bound one
+ * tier down by `AbstractHydraniumGlspDiagramModule`, from the grammar each
+ * diagram type declares.
+ *
+ * Concrete and usable as-is: adopters that need no extra bindings
+ * instantiate {@link HydraniumGlspAppModule} directly. Adopters that do
+ * subclass it and override {@link configureAdditionalBindings} to add their
+ * own service-identifier carriers.
+ *
+ * A conventional GLSP module (cf. `@eclipse-glsp/server`'s `GLSPModule`
+ * subclasses); the empty `configureAdditionalBindings` hook is the single
+ * extension point, so no separate abstract base is needed.
+ */
+@injectable()
+export class HydraniumGlspAppModule<TShared extends ServerSharedServices = ServerSharedServices> extends GLSPModule {
+   constructor(protected readonly options: HydraniumGlspAppModuleOptions<TShared>) {
+      super();
+   }
+
+   protected override configure(
+      bind: interfaces.Bind,
+      unbind: interfaces.Unbind,
+      isBound: interfaces.IsBound,
+      rebind: interfaces.Rebind
+   ): void {
+      bind(HydraniumTypes.SharedCoreServices).toConstantValue(this.options.shared);
+      bind(HydraniumTypes.ConflictResolver).toConstantValue(this.options.conflictResolver ?? new ReconcilingConflictResolver());
+      this.configureAdditionalBindings({ bind, unbind, isBound, rebind });
+   }
+
+   /**
+    * Extension point for adopter-specific bindings (service-identifier
+    * carriers for the adopter's own language services).
+    * Default implementation is empty.
+    */
+   protected configureAdditionalBindings(_context: BindingContext): void {
+      // empty by default
+   }
+}