@hydranium/glsp-server 1.0.0-next.10

package/src/storage/save-conflict-policy.ts

@@ -0,0 +1,52 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * How `HydraniumGlspStorage.saveSourceModel` reacts when a concurrent edit has
+ * advanced the document past the version this diagram was last captured at.
+ *
+ * A save spans otherwise-independent choices — whether to guard on the captured
+ * based-on version, whether the GLSP save action awaits the persist, and what
+ * happens on failure. Each arm bundles those into one coherent, nameable policy
+ * so an adopter selects a whole behaviour rather than assembling an incoherent
+ * mix: fire-and-forget plus rethrow would leave an unhandled rejection. It is a
+ * *selection of configuration*, delivered as a bound option (see the
+ * {@link SaveConflictPolicy} symbol) rather than a behaviour hook.
+ */
+export type SaveConflictPolicy =
+   /**
+    * Last-write-wins: no based-on guard, await the persist, propagate any
+    * failure to the GLSP save action. The default; correct for a single-editor
+    * head where nothing races the save.
+    */
+   | { kind: 'overwrite' }
+   /**
+    * Guard on the captured version, await the persist, and surface a
+    * `ConflictError` (and any other failure) to the GLSP save action.
+    */
+   | { kind: 'reject' }
+   /**
+    * Guard on the captured version, fire-and-forget, and log + swallow every
+    * failure. Correct when another editor of the same document may already have
+    * written the truth, so a stale diagram save is benign and must neither
+    * block the action nor surface as an error.
+    */
+   | { kind: 'drop-and-log' };
+
+/** The policy applied when no {@link SaveConflictPolicy} option is bound. */
+export const DEFAULT_SAVE_CONFLICT_POLICY: SaveConflictPolicy = { kind: 'overwrite' };
+
+/**
+ * DI token for the {@link SaveConflictPolicy} option. Bind a constant value in a
+ * `DiagramModule` to select a non-default policy; left unbound,
+ * `HydraniumGlspStorage` falls back to
+ * {@link DEFAULT_SAVE_CONFLICT_POLICY}. Shares its name with the type, the way a
+ * `class` is both a value and a type.
+ */
+export const SaveConflictPolicy = Symbol('SaveConflictPolicy');

package/src/submission/hydranium-glsp-submission-handler.ts

@@ -0,0 +1,170 @@
+/********************************************************************************
+ * Copyright (c) 2024-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 DirtyStateChangeReason,
+   type GModelRootSchema,
+   type LayoutOperation,
+   ModelState,
+   ModelSubmissionHandler,
+   SetDirtyStateAction,
+   type SetModelAction
+} from '@eclipse-glsp/server';
+import { IntegrityService } from '@hydranium/core';
+import { inject, injectable } from 'inversify';
+import { type AstNode, type DocumentState } from '@hydranium/langium';
+import { type AbstractHydraniumGlspState } from '../state/abstract-hydranium-glsp-state.js';
+
+/**
+ * GLSP {@link ModelSubmissionHandler} base shared by all hydranium adopters.
+ * Wraps {@link submitModel} with an optional document-state ready-gate and
+ * post-action observability logging; preserves the {@link createSetModeAction}
+ * handshake log; exposes a {@link hasPendingInitialRequest} guard adopters
+ * use to suppress external rebuild reactions while the initial-load
+ * `RequestModelAction` is still in flight.
+ *
+ * **What stays adopter-side.** Translation of the source AST to a GModel is
+ * owned by GLSP's existing `GModelFactory` interface, bound separately
+ * per `DiagramModule`. The submission handler is strictly orchestration —
+ * deliberately no `translateToGModel` hook here; adopters wire their per-
+ * diagram-type `GModelFactory` subclass via `bindGModelFactory()`.
+ *
+ * **Hooks.**
+ * - {@link readyEvent} — {@link DocumentState} the {@link submitModel} flow
+ *   awaits via {@link AbstractHydraniumGlspState.ready} before delegating to
+ *   `super.submitModel`. Default {@link IntegrityService.SettledState}
+ *   (`IndexedReferences`) — the GModel-factory walk sees a fully linked AST
+ *   with cross-document references resolved AND post-build integrity rules
+ *   applied. Adopters that need a different phase (earlier `Linked` for
+ *   simpler models, later `Validated` to consume diagnostics, or `undefined`
+ *   to opt out entirely) override this field.
+ * - {@link formatSourceRoot} — adopter-specific AST description used in
+ *   the submit-log line. Default returns `root.$type`.
+ *
+ * Logs through {@link AbstractHydraniumGlspState.logger} (the state's
+ * URI-tagged tracer), so it carries no log-label field of its own.
+ */
+@injectable()
+export class HydraniumGlspSubmissionHandler<TRoot extends AstNode, TSourceModel = string> extends ModelSubmissionHandler {
+   @inject(ModelState) declare protected modelState: AbstractHydraniumGlspState<TRoot, TSourceModel>;
+
+   /**
+    * Document-state gate awaited before {@link submitModel} delegates to
+    * `super.submitModel`. Default {@link IntegrityService.SettledState} so the
+    * GModel factory walks a fully-linked, integrity-settled AST out of the
+    * box. Adopters override (including to `undefined` to opt out entirely)
+    * when their submission flow doesn't need to wait.
+    */
+   protected readyEvent: DocumentState | undefined = IntegrityService.SettledState;
+
+   /**
+    * True when a `RequestModelAction` has been accepted but the
+    * corresponding {@link SetModelAction} response has not yet been
+    * dispatched. Adopter storage uses this to suppress the "external
+    * submit" rebuild reaction during the initial-load handshake: that
+    * rebuild reaction would call `submitModel('external')`, which rebuilds
+    * the GModel and bumps its revision; once the revision changes, the
+    * client's first `computedBounds` (still carrying the old revision) is
+    * dropped and the initial `SetModelAction` never fires.
+    */
+   hasPendingInitialRequest(): boolean {
+      return this.requestModelAction !== undefined;
+   }
+
+   override async submitModel(reason?: DirtyStateChangeReason, layout?: LayoutOperation): Promise<Action[]> {
+      if (this.readyEvent !== undefined) {
+         // Adopters with on-build integrity rules wait so the GModel-factory walk sees
+         // a settled AST; otherwise the GModel could include elements the build pass is
+         // about to rewrite or remove. ready() also refreshes the captured source root
+         // via onReadyRefreshed.
+         await this.modelState.ready(this.readyEvent);
+      }
+      const actions = await super.submitModel(reason, layout);
+      this._lastSubmittedSignature = this.signatureOf(actions);
+      this.logSubmit(reason, actions);
+      return actions;
+   }
+
+   /**
+    * Content signature of the last submission, whatever its reason.
+    *
+    * **Tracked across every reason because the CLIENT cannot tell them apart.**
+    * An operation submit and a later external rebuild that produce the same
+    * graph are the same delivery as far as the canvas is concerned, so a
+    * comparison scoped to one reason reports "changed" for a model the client
+    * already has. `undefined` until the first submit.
+    */
+   get lastSubmittedSignature(): string | undefined {
+      return this._lastSubmittedSignature;
+   }
+
+   protected _lastSubmittedSignature?: string;
+
+   /**
+    * Serialise the model-bearing actions of a submission into a comparable
+    * signature.
+    *
+    * `requestId` is fresh per action and `revision` is a monotonic `GModelRoot`
+    * counter bumped on every rebuild, so neither reflects content.
+    *
+    * **`SetDirtyStateAction` is dropped whole rather than having its `reason`
+    * stripped by key, and the distinction is load-bearing.** Measured: an
+    * operation submit and the external rebuild echoing it are byte-identical
+    * across the entire GModel and differ only in that action's `reason`, so
+    * leaving it in defeats the comparison outright. Stripping the KEY instead
+    * would reach further than intended — `reason` carries meaning on other
+    * actions, `SetMarkersAction` among them — and would quietly weaken any
+    * later comparison that includes one. Dropping the action also keeps
+    * `isDirty` out, which is correct: dirty state is not part of "is this the
+    * same model", and a genuine dirty-to-clean change must not be suppressed as
+    * a duplicate model.
+    */
+   protected signatureOf(actions: Action[]): string {
+      return JSON.stringify(
+         actions.filter(action => !SetDirtyStateAction.is(action)),
+         (key, value) => (key === 'requestId' || key === 'revision' ? undefined : value)
+      );
+   }
+
+   /**
+    * Logs the {@link SetModelAction} dispatch so the initial
+    * `requestModel → setModel` handshake is observable in the server log
+    * alongside `Submit model` and `ComputedBounds accepted`.
+    */
+   protected override createSetModeAction(newRoot: GModelRootSchema): SetModelAction {
+      const action = super.createSetModeAction(newRoot);
+      this.modelState.logger.info(
+         `Dispatching SetModelAction (response to requestModel #${action.responseId || '?'}) — initial model handshake complete`
+      );
+      return action;
+   }
+
+   protected logSubmit(reason: DirtyStateChangeReason | undefined, actions: Action[]): void {
+      const root = this.modelState.root;
+      const gChildren = root?.children?.length ?? 0;
+      const sourceRoot = this.modelState.sourceRoot;
+      const kinds = actions.map(a => a.kind).join(',');
+      this.modelState.logger.info(
+         `Submit model [reason=${reason ?? 'initial'}, actions=[${kinds}], ` +
+            `gmodel={type=${root?.type ?? 'none'}, children=${gChildren}}, ` +
+            `ast={${this.formatSourceRoot(sourceRoot)}}]`
+      );
+   }
+
+   /**
+    * Hook for adopter-specific AST description in the submit-log line.
+    * Default returns `root.$type` (or `'none'` when the source root is
+    * undefined). Adopters with multi-shape source roots override to add
+    * per-shape detail.
+    */
+   protected formatSourceRoot(root: TRoot | undefined): string {
+      return root?.$type ?? 'none';
+   }
+}

package/src/submission/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-submission-handler.js';

package/src/testing/glsp-harness.ts

@@ -0,0 +1,422 @@
+/********************************************************************************
+ * 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 'reflect-metadata';
+import {
+   type Action,
+   type ActionMessage,
+   ClientSessionManager,
+   EndProgressAction,
+   GLSPClientProxy,
+   GLSPServer,
+   ModelState,
+   RequestBoundsAction,
+   RequestModelAction,
+   SOURCE_URI_ARG,
+   SetDirtyStateAction,
+   SetModelAction,
+   StartProgressAction,
+   StatusAction,
+   UpdateModelAction,
+   UpdateProgressAction
+} from '@eclipse-glsp/server';
+import {
+   DefaultGLSPServer,
+   InjectionContainer,
+   Logger as GlspLogger,
+   LoggerFactory,
+   NodeActionDispatchScope,
+   type ServerModule,
+   getRequestParentName
+} from '@eclipse-glsp/server/node.js';
+import { ActionDispatchScope } from '@eclipse-glsp/server';
+import { Container, ContainerModule, type interfaces } from 'inversify';
+import type { AstNode } from '@hydranium/langium';
+import type { ServerSharedServices } from '@hydranium/core';
+import type { Harness } from '@hydranium/protocol/testing';
+import type { AbstractHydraniumGlspState } from '../state/abstract-hydranium-glsp-state.js';
+import { HydraniumTypes } from '../state/hydranium-shared-core-services.js';
+import { createGlspServerOverrides } from '../launcher/glsp-server-overrides.js';
+import { makeNoopGlspLogger } from './make-noop-glsp-logger.js';
+
+/**
+ * Options for {@link makeGlspHarness}.
+ *
+ * The harness drives a REAL {@link GLSPServer} in-process: it composes the
+ * server container the way `startGlspServer` does (framework default app
+ * module + adopter `appModules` + the adopter `serverModule`), but binds
+ * {@link GLSPClientProxy} to a capturing stub instead of a socket-backed
+ * proxy, so every action the server pushes to the client lands in the
+ * harness's `actions` capture. There is no OS socket and no JSON
+ * serialization, so nothing here covers the wire layer.
+ *
+ * `serverModule` + `diagramType` are required; everything else has a
+ * test-friendly default. The adopter's shared services / id provider /
+ * conflict resolver come from `appModules` (typically an
+ * `HydraniumGlspAppModule` subclass) — exactly as in production, so
+ * the harness binds none of them itself.
+ */
+export interface MakeGlspHarnessOptions {
+   /** Adopter {@link ServerModule} with its diagram module(s) pre-configured via `configureDiagramModule`. */
+   readonly serverModule: ServerModule;
+   /** Diagram type id passed to `initializeClientSession`; must match the configured diagram module. */
+   readonly diagramType: string;
+   /**
+    * Adopter Inversify modules loaded AFTER the framework default module
+    * (which binds `InjectionContainer`, GLSP's `Logger`, `LoggerFactory` and
+    * `ActionDispatchScope`). Carries the adopter's
+    * `HydraniumTypes.SharedCoreServices` / `HydraniumTypes.ConflictResolver` /
+    * language-services bindings. Per-language providers come from the diagram
+    * module instead — see `AbstractHydraniumGlspDiagramModule`.
+    */
+   readonly appModules?: ReadonlyArray<ContainerModule>;
+   /**
+    * GLSP logger factory. Default: a silent logger (the harness keeps the
+    * test output clean). Override to capture GLSP framework log lines.
+    */
+   readonly createLogger?: (caller?: string) => GlspLogger;
+   /** `applicationId` for the `initialize` handshake. Default `'test-app'`. */
+   readonly applicationId?: string;
+   /** Client session id used for `initializeClientSession` + every dispatched `ActionMessage`. Default `'test-session'`. */
+   readonly clientSessionId?: string;
+   /**
+    * Adopter-specific client action kinds to forward IN ADDITION to
+    * {@link DEFAULT_CLIENT_ACTION_KINDS}. The server's
+    * `ClientActionForwarder` only forwards declared kinds to the capturing
+    * `GLSPClientProxy`, so list any custom server→client action a test needs
+    * to observe. The standard set covers ordinary round-trips, so most tests
+    * leave this unset.
+    */
+   readonly additionalClientActionKinds?: ReadonlyArray<string>;
+}
+
+/**
+ * The standard client-bound action kinds a real GLSP client handles — the
+ * minimal set needed for any model round-trip. The harness declares these on
+ * the session by default so the capturing {@link GLSPClientProxy} receives
+ * them and the action dispatcher never errors with "no handler registered"
+ * for an ordinary server→client action. Adopter-specific kinds are added via
+ * {@link MakeGlspHarnessOptions.additionalClientActionKinds}.
+ */
+const DEFAULT_CLIENT_ACTION_KINDS: ReadonlyArray<string> = [
+   SetModelAction.KIND,
+   UpdateModelAction.KIND,
+   RequestBoundsAction.KIND,
+   SetDirtyStateAction.KIND,
+   StatusAction.KIND,
+   StartProgressAction.KIND,
+   UpdateProgressAction.KIND,
+   EndProgressAction.KIND
+];
+
+/** Options for {@link GlspHarness.nextModelSubmission}. */
+export interface NextModelSubmissionOptions {
+   /** How long to wait. Defaults to 2000ms. */
+   readonly timeoutMs?: number;
+   /**
+    * Reject on timeout (default `true`) or resolve `undefined` (`false`). Pair
+    * `false` with a short `timeoutMs` — the wait runs to completion in the
+    * passing case.
+    */
+   readonly rejectOnTimeout?: boolean;
+}
+
+/**
+ * Bundle returned by {@link makeGlspHarness}. Satisfies the uniform
+ * {@link Harness} contract — `state` is the **subject** (the resolved adopter
+ * state under test), `server` + `dispatch`/`nextAction` are the **seam** tests
+ * drive the action round-trip through, `actions` is the **capture** of every
+ * outbound action in arrival order, and `dispose()` is the uniform teardown
+ * hook. `state` / `sessionContainer` are only valid after {@link start} (the
+ * `ModelState` lives in GLSP's per-session child container, created by
+ * `initializeClientSession`).
+ */
+export interface GlspHarness<TState extends AbstractHydraniumGlspState<AstNode, unknown>> extends Harness {
+   /** The real GLSP server under test. */
+   readonly server: GLSPServer;
+   /** The main (app + server) container. */
+   readonly container: interfaces.Container;
+   /** The per-session child container `initializeClientSession` created. Throws if read before {@link start}. */
+   readonly sessionContainer: interfaces.Container;
+   /** The adopter `ModelState` resolved from {@link sessionContainer}. Throws if read before {@link start}. */
+   readonly state: TState;
+   /** Every action the server pushed to the client, in arrival order. Never cleared by the harness. */
+   readonly actions: ReadonlyArray<Action>;
+
+   /** Drive `initialize` then `initializeClientSession`; resolve once the session container exists. */
+   start(): Promise<void>;
+   /** Drive `server.shutdown()` (disposes client sessions). */
+   shutdown(): Promise<void>;
+   /** Send an action to the server as `{ clientId, action }`. Fire-and-forget (GLSP `process` is `void`). */
+   dispatch(action: Action): void;
+   /**
+    * Resolve with the next captured action whose `kind` matches — an
+    * already-captured-but-unconsumed match resolves immediately, otherwise
+    * waits for the next arrival. Rejects after `timeoutMs` (default 2000) so
+    * a missing action fails fast instead of hanging.
+    */
+   nextAction<T extends Action = Action>(kind: string, timeoutMs?: number): Promise<T>;
+   /**
+    * FAITHFUL fidelity: open `sourceUri` the way a client does — dispatch
+    * `RequestModelAction` with `SOURCE_URI_ARG` — and resolve with the model
+    * the server publishes in response.
+    *
+    * Resolves on **whichever** submission action the diagram produces, because
+    * that depends on its `DiagramConfiguration` rather than on the test:
+    * `SetModelAction` for a server-laid-out diagram, `RequestBoundsAction` for
+    * a client-laid-out one. Awaiting the wrong one is a 2s timeout that names
+    * the wrong subsystem, and a test should not have to know which applies.
+    *
+    * Rejects if nothing is published within `timeoutMs`. Valid only after
+    * {@link start}.
+    */
+   openDocument(sourceUri: string, timeoutMs?: number): Promise<Action>;
+   /**
+    * Resolve with the next action that publishes a model — the settling point
+    * after an operation, since a successful operation re-submits.
+    *
+    * Kind-agnostic for the same reason as {@link openDocument}. Set
+    * `rejectOnTimeout: false` to ask whether a submission happened *at all*.
+    */
+   nextModelSubmission(options?: NextModelSubmissionOptions): Promise<Action | undefined>;
+   /**
+    * LIGHT fidelity: seed the state's source root directly via
+    * `setSourceRoot`, bypassing source-model storage. Valid only after
+    * {@link start}.
+    */
+   seedSourceRoot(uri: string, root: Parameters<TState['setSourceRoot']>[1]): void;
+
+   /** Idempotent teardown: `server.shutdown()` then `container.unbindAll()`. */
+   dispose(): void;
+}
+
+interface PendingWaiter {
+   /** Kinds this waiter accepts; the first arrival matching any of them wins. */
+   readonly kinds: ReadonlyArray<string>;
+   readonly resolve: (action: Action | undefined) => void;
+   timer: ReturnType<typeof setTimeout>;
+}
+
+/**
+ * The actions that mean "the server published a model".
+ *
+ * Which one arrives depends on the diagram's `DiagramConfiguration`, not on
+ * what the test did: a server-laid-out diagram gets `SetModelAction`, a
+ * client-laid-out one (`needsClientLayout`) gets `RequestBoundsAction`, and a
+ * re-submit after an operation may be `UpdateModelAction`. Tests that only care
+ * *that* the model was published should not have to encode that choice — see
+ * {@link GlspHarness.nextModelSubmission}.
+ *
+ * Exported for the tests that must COUNT submissions rather than await the next
+ * one (asserting that nothing further was published, say). Re-listing the kinds
+ * in such a test is a false-green shape: a kind added here would leave the copy
+ * silently under-counting.
+ */
+export const MODEL_SUBMISSION_KINDS: ReadonlyArray<string> = [SetModelAction.KIND, UpdateModelAction.KIND, RequestBoundsAction.KIND];
+
+/**
+ * Wire a real {@link GLSPServer} in-process and drive a GLSP action
+ * round-trip against it — dispatch an action → operation/request handler →
+ * GModel mutation → response action, captured via a stub
+ * {@link GLSPClientProxy}.
+ *
+ * The harness composes ONE container, collapsing production's parent
+ * app-container / per-connection child split, which exists only to share the
+ * app container across socket connections.
+ */
+export function makeGlspHarness<TState extends AbstractHydraniumGlspState<AstNode, unknown>>(
+   options: MakeGlspHarnessOptions
+): GlspHarness<TState> {
+   const applicationId = options.applicationId ?? 'test-app';
+   const clientSessionId = options.clientSessionId ?? 'test-session';
+   const clientActionKinds = [...DEFAULT_CLIENT_ACTION_KINDS, ...(options.additionalClientActionKinds ?? [])];
+   const createLogger = options.createLogger ?? (() => makeNoopGlspLogger());
+
+   const actions: Action[] = [];
+   const consumed = new WeakSet<Action>();
+   const waiters: PendingWaiter[] = [];
+
+   const captureProxy: GLSPClientProxy = {
+      process(message: ActionMessage): void {
+         const { action } = message;
+         actions.push(action);
+         const index = waiters.findIndex(waiter => waiter.kinds.includes(action.kind));
+         if (index >= 0) {
+            const [waiter] = waiters.splice(index, 1);
+            consumed.add(action);
+            clearTimeout(waiter.timer);
+            waiter.resolve(action);
+         }
+      }
+   };
+
+   /**
+    * Resolve with the first unconsumed action matching any of `kinds` — one
+    * already captured resolves immediately, otherwise the next arrival wins.
+    *
+    * `rejectOnTimeout` is what lets a caller distinguish the two questions a
+    * test asks. `true` (the default) is "this must happen", and a timeout is a
+    * failure naming the kinds. `false` is "did this happen?", resolving
+    * `undefined` — needed because a **rejected** operation produces no action
+    * at all, so the only observable is the absence of one. Mirrors GLSP's own
+    * `ActionDispatcher.requestUntil(action, timeoutMs, rejectOnTimeout)`.
+    */
+   function waitFor(kinds: ReadonlyArray<string>, timeoutMs: number, rejectOnTimeout: boolean): Promise<Action | undefined> {
+      const existing = actions.find(action => kinds.includes(action.kind) && !consumed.has(action));
+      if (existing) {
+         consumed.add(existing);
+         return Promise.resolve(existing);
+      }
+      return new Promise<Action | undefined>((resolve, reject) => {
+         const waiter: PendingWaiter = {
+            kinds,
+            resolve,
+            timer: setTimeout(() => {
+               const index = waiters.indexOf(waiter);
+               if (index >= 0) {
+                  waiters.splice(index, 1);
+               }
+               if (rejectOnTimeout) {
+                  // Name what DID arrive. A bare "no X within 2000ms" reads as a
+                  // hang and points at the transport, when the usual cause is an
+                  // operation handler that threw or declined: the server then
+                  // emits nothing, or emits only a status/dirty-state action.
+                  // Distinguishing "nothing happened" from "something else
+                  // happened" is the difference between a five-minute hunt and a
+                  // one-line diagnosis.
+                  const seen = actions.map(captured => captured.kind);
+                  const context = seen.length === 0 ? 'no actions were captured at all' : `captured since start: ${seen.join(', ')}`;
+                  reject(
+                     new Error(
+                        `makeGlspHarness: no ${kinds.map(kind => `'${kind}'`).join(' / ')} action within ${timeoutMs}ms — ${context}`
+                     )
+                  );
+               } else {
+                  resolve(undefined);
+               }
+            }, timeoutMs)
+         };
+         waiters.push(waiter);
+      });
+   }
+
+   const defaultAppModule = new ContainerModule(bind => {
+      bind(InjectionContainer).toDynamicValue(ctx => ctx.container);
+      bind(GlspLogger).toDynamicValue(ctx => createLogger(getRequestParentName(ctx)));
+      bind(LoggerFactory).toFactory(() => (caller: string) => createLogger(caller));
+      // `DefaultActionDispatcher` injects this to tell a reentrant dispatch (from
+      // inside a running handler, which must run inline) from an external one
+      // (which queues). Mirrors GLSP's own `createAppModule`; without it every
+      // dispatch throws on `dispatchScope.isReentrant`.
+      bind(ActionDispatchScope).to(NodeActionDispatchScope).inSingletonScope();
+      bind(HydraniumTypes.Tracer).toDynamicValue(ctx => {
+         const tracer = ctx.container.get<ServerSharedServices>(HydraniumTypes.SharedCoreServices).Tracer;
+         const caller = getRequestParentName(ctx);
+         return caller ? tracer.for(caller) : tracer;
+      });
+   });
+   const captureProxyModule = new ContainerModule(bind => {
+      bind(GLSPClientProxy).toConstantValue(captureProxy);
+   });
+
+   const container = new Container();
+   container.load(defaultAppModule, ...(options.appModules ?? []), captureProxyModule);
+   container.load(options.serverModule);
+   // After the serverModule, which binds `GLSPServer`: the override rebinds that
+   // symbol, so it needs the binding to exist. The launchers reach the same tier
+   // by passing this to `configure` — a harness that skipped it would answer
+   // request failures differently from every real bringup.
+   container.load(createGlspServerOverrides());
+   const server = container.get<GLSPServer>(GLSPServer);
+
+   let sessionContainer: interfaces.Container | undefined;
+   let state: TState | undefined;
+   let disposed = false;
+
+   return {
+      server,
+      container,
+      actions,
+      get sessionContainer(): interfaces.Container {
+         if (!sessionContainer) {
+            throw new Error('makeGlspHarness: sessionContainer is only available after start()');
+         }
+         return sessionContainer;
+      },
+      get state(): TState {
+         if (!state) {
+            throw new Error('makeGlspHarness: state is only available after start()');
+         }
+         return state;
+      },
+
+      async start(): Promise<void> {
+         await server.initialize({ applicationId, protocolVersion: DefaultGLSPServer.PROTOCOL_VERSION });
+         await server.initializeClientSession({ clientSessionId, diagramType: options.diagramType, clientActionKinds });
+         const session = container.get<ClientSessionManager>(ClientSessionManager).getSession(clientSessionId);
+         if (!session) {
+            throw new Error(`makeGlspHarness: no client session '${clientSessionId}' after initializeClientSession`);
+         }
+         // `session.container` is inversify's concrete `Container`, a nominal type via its
+         // private fields — so it clashes across inversify's CJS/ESM dual-package
+         // declarations. Typing the harness's container fields as the structural
+         // `interfaces.Container` reconciles them with no cast (interfaces compare
+         // structurally; the concrete `Container` is only needed for `new Container()`).
+         const resolved = session.container;
+         sessionContainer = resolved;
+         state = resolved.get<TState>(ModelState);
+      },
+
+      async shutdown(): Promise<void> {
+         server.shutdown();
+      },
+
+      dispatch(action: Action): void {
+         server.process({ clientId: clientSessionId, action });
+      },
+
+      nextAction<T extends Action = Action>(kind: string, timeoutMs = 2000): Promise<T> {
+         return waitFor([kind], timeoutMs, true) as Promise<T>;
+      },
+
+      async openDocument(sourceUri: string, timeoutMs = 2000): Promise<Action> {
+         if (!state) {
+            throw new Error('makeGlspHarness: openDocument() is only valid after start()');
+         }
+         server.process({
+            clientId: clientSessionId,
+            action: RequestModelAction.create({ options: { [SOURCE_URI_ARG]: sourceUri } })
+         });
+         const submission = await waitFor(MODEL_SUBMISSION_KINDS, timeoutMs, true);
+         // `waitFor` with rejectOnTimeout only resolves with a real action.
+         return submission as Action;
+      },
+
+      nextModelSubmission(options: NextModelSubmissionOptions = {}): Promise<Action | undefined> {
+         const { timeoutMs = 2000, rejectOnTimeout = true } = options;
+         return waitFor(MODEL_SUBMISSION_KINDS, timeoutMs, rejectOnTimeout);
+      },
+
+      seedSourceRoot(uri: string, root: Parameters<TState['setSourceRoot']>[1]): void {
+         if (!state) {
+            throw new Error('makeGlspHarness: seedSourceRoot() is only valid after start()');
+         }
+         state.setSourceRoot(uri, root);
+      },
+
+      dispose(): void {
+         if (disposed) {
+            return;
+         }
+         disposed = true;
+         server.shutdown();
+         container.unbindAll();
+      }
+   };
+}

package/src/testing/index.ts

@@ -0,0 +1,14 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+// Subpath barrel for `@hydranium/glsp-server/testing` — `makeGlspHarness`,
+// which drives a real GLSP server in-process against a capturing client proxy.
+
+export * from './glsp-harness.js';
+export * from './make-noop-glsp-logger.js';