@hydranium/glsp-server 1.0.0-next.7 → 1.0.0-next.71

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydranium/glsp-server",
-  "version": "1.0.0-next.7",
+  "version": "1.0.0-next.71",
   "description": "GLSP protocol head for the hydranium framework. Peer of @hydranium/core/lsp and @hydranium/data-server; built on @hydranium/core.",
   "keywords": [
     "hydranium",
@@ -48,6 +48,14 @@
       "types": "./lib/node/index.d.ts",
       "default": "./lib/node/index.js"
     },
+    "./messages": {
+      "types": "./lib/messages/index.d.ts",
+      "default": "./lib/messages/index.js"
+    },
+    "./lib/messages": {
+      "types": "./lib/messages/index.d.ts",
+      "default": "./lib/messages/index.js"
+    },
     "./testing": {
       "types": "./lib/testing/index.d.ts",
       "default": "./lib/testing/index.js"
@@ -79,9 +87,9 @@
   "devDependencies": {
     "@eclipse-glsp/protocol": "2.7.0",
     "@eclipse-glsp/server": "2.7.0",
-    "@hydranium/core": "1.0.0-next.7",
-    "@hydranium/langium": "1.0.0-next.7",
-    "@hydranium/protocol": "1.0.0-next.7",
+    "@hydranium/core": "1.0.0-next.71",
+    "@hydranium/langium": "1.0.0-next.71",
+    "@hydranium/protocol": "1.0.0-next.71",
     "inversify": "6.2.2",
     "reflect-metadata": "0.2.2",
     "rimraf": "^5.0.0",
@@ -92,12 +100,12 @@
   "peerDependencies": {
     "@eclipse-glsp/protocol": "^2.6.0",
     "@eclipse-glsp/server": "^2.6.0",
-    "@hydranium/core": "1.0.0-next.7",
-    "@hydranium/langium": "1.0.0-next.7",
-    "@hydranium/protocol": "1.0.0-next.7",
+    "@hydranium/core": "1.0.0-next.71",
+    "@hydranium/langium": "1.0.0-next.71",
+    "@hydranium/protocol": "1.0.0-next.71",
     "inversify": "^6.0.0",
     "reflect-metadata": "^0.2.2",
-    "vscode-jsonrpc": "^8.0.0 || ^9.0.0",
+    "vscode-jsonrpc": "9.0.1",
     "vscode-languageserver-types": "^3.17.5"
   },
   "engines": {
@@ -106,6 +114,7 @@
   "publishConfig": {
     "access": "public"
   },
+  "//peerDependencies": "`vscode-jsonrpc` is EXACT rather than a range, because it is one link of an atomic chain with no independently movable link: `vscode-languageserver-protocol` depends on it at exactly 9.0.1, so any other value an adopter supplies is a SECOND physical copy rather than an upgrade. This wire stack breaks on copy identity rather than on structure — `ParameterStructures.auto` is a singleton compared by `===` in connection.js, so a request type built by one copy and sent over a connection owned by the other throws `Unknown parameter structure auto`. A caret or union range was rejected because npm then resolves a `vscode-jsonrpc@8.2.0` tree SILENTLY, with no diagnostic at all, and the failure surfaces only later at server init. Exact does not fail the install either — npm downgrades an unsatisfiable peer to a warning — but it is a NAMED ERESOLVE warning printing the required version beside the found one, and a hard error for anyone installing with `--strict-peer-deps`. **This is the head where it is not enough**: `@eclipse-glsp/*` carries its own exact `vscode-jsonrpc@8.2.0` dependency and root `overrides` do not ship, so a first install of this package ALWAYS lands two copies and the adopter must pin the chain in their own manifest. docs/adopting/requirements.md carries the block to paste.",
   "//prepack": "The publish guard, and it deliberately is NOT a `prepare`: npm runs a workspace `prepare` BEFORE the root `postinstall` that applies patches/vscode-jsonrpc+9.0.1.patch, so building there fails on a cold clone and npm rolls the entire install back. `prepack` runs only when a tarball is made (`npm pack`, `npm publish`) and never on install, so it cannot break the install it has no business touching. It FAILS rather than rebuilds, because the rebuild is exactly the part that ordering defeats. What it defends against: `files` lists `lib`, `lib` is gitignored, and a `files` entry matching nothing is skipped SILENTLY — so `npm publish` from an unbuilt tree emits a tarball of `src` and nothing else, with no error.",
   "//sideEffects": "The harness bare-imports `reflect-metadata`, which installs a global `Reflect` polyfill the inversify decorators in this package need before any container is built. That effect is invisible from the module's exports, so a bundler that treats the file as pure may reorder or drop the import and every `@injectable` resolution then fails at runtime. The rest of the package constructs no module-level state beyond frozen constants and DI symbols."
 }

package/src/launcher/hydranium-glsp-server.ts

@@ -26,9 +26,10 @@ import { injectable } from 'inversify';
  * `error.cause?.toString()` whenever the error is a {@link GLSPServerError},
  * and that one value feeds both the server log and the client's
  * {@link RejectAction}. A {@link GLSPServerError} carrying no `cause` therefore
- * reaches no reader at all — not the toast, not the details pane, not the log —
- * while a plain `Error` survives, because the other branch reads the error
- * itself. The typed error is the trap, and it is the one upstream's own
+ * reaches its readers as `undefined` — the log line and the client's
+ * action-dispatcher warning both print it — while a plain `Error` survives,
+ * because the other branch reads the error itself. The typed error is the trap,
+ * and it is the one upstream's own
  * `getOrThrow` helper raises: that helper's signature cannot pass a `cause`, so
  * an adopter using the sanctioned helper has no fix available on their side.
  * Restating the cause at each throw site is the alternative, and it costs

package/src/messages/index.ts

@@ -0,0 +1,25 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * Every user-facing message `@hydranium/glsp-server` raises.
+ *
+ * **Each one is rendered AT ITS RAISE SITE**, through the shared
+ * `MessageRenderer`, because GLSP's action protocol carries no slot for an
+ * identity on any of its actions — so the identity is gone the moment a raise
+ * site formats its text, and there is nothing at the error boundary to render
+ * from. That makes this head the one place where a new message can ship
+ * unrendered without any single chokepoint noticing, which is why the package's
+ * own test suite scans for a declaration reached by `.format()` instead.
+ *
+ * The barrel is also how an adopter rendering their own diagram chrome
+ * discovers the codes exist.
+ */
+
+export { DIAGRAM_READONLY_PARSE_ERROR, SAVE_TARGET_UNKNOWN, SOURCE_URI_MISSING } from '../storage/hydranium-glsp-storage.js';

package/src/state/reconcile-source-model-write.ts

@@ -59,17 +59,19 @@ export async function reconcileSourceModelWrite<TModel extends object>(
             await hooks.persist(outcome.merged);
             return;
          case 'no-op':
-            hooks.logger.debug(`updateSourceModel no-op (v${err.expected} → v${err.actual}); already in sync`);
+            hooks.logger.debug(`updateSourceModel no-op (v${err.expectedVersion} → v${err.actualVersion}); already in sync`);
             return;
          case 'conflict':
             hooks.logger.warn(
-               `updateSourceModel conflict (v${err.expected} → v${err.actual}); dropping the diagram edit — ` +
+               `updateSourceModel conflict (v${err.expectedVersion} → v${err.actualVersion}); dropping the diagram edit — ` +
                   'a foreign writer changed the same field'
             );
             hooks.onConflictDropped();
             return;
          case 'unavailable':
-            hooks.logger.warn(`updateSourceModel refetch unavailable (v${err.expected} → v${err.actual}); forcing without version`);
+            hooks.logger.warn(
+               `updateSourceModel refetch unavailable (v${err.expectedVersion} → v${err.actualVersion}); forcing without version`
+            );
             await hooks.persist(model);
             return;
       }

package/src/storage/hydranium-glsp-storage.ts

@@ -7,7 +7,7 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { MarkersReason, SetMarkersAction } from '@eclipse-glsp/protocol';
+import { MarkersReason, SetMarkersAction, StatusAction } from '@eclipse-glsp/protocol';
 import {
    type Action,
    ActionDispatcher,
@@ -31,7 +31,7 @@ import {
    type SourceModelStorage,
    TEMPORARY_CLIENT_ID
 } from '@eclipse-glsp/server';
-import { Debouncer, DisposableCollection } from '@hydranium/protocol';
+import { Debouncer, defineMessage, DisposableCollection } from '@hydranium/protocol';
 import { inject, injectable, optional, postConstruct } from 'inversify';
 import { type AstNode } from '@hydranium/langium';
 import { URI } from '@hydranium/langium';
@@ -40,7 +40,58 @@ import { DiagnosticSeverity } from 'vscode-languageserver-types';
 import { type AbstractHydraniumGlspState } from '../state/abstract-hydranium-glsp-state.js';
 import { type HydraniumGlspSubmissionHandler } from '../submission/hydranium-glsp-submission-handler.js';
 import { HydraniumTypes } from '../state/hydranium-shared-core-services.js';
-import { DEFAULT_SAVE_CONFLICT_POLICY, SaveConflictPolicy } from './save-conflict-policy.js';
+import { DEFAULT_SAVE_DELIVERY_POLICY, SaveDeliveryPolicy } from './save-delivery-policy.js';
+
+/**
+ * A save action arrived with nowhere to write to. A save action carries no
+ * request id, so it falls through to the error handler and `message` becomes
+ * the toast text.
+ *
+ * Rendered at the raise site rather than by a carrier method, because GLSP's
+ * action protocol has no slot for an identity anywhere — every member of its
+ * message, status and reject actions is prose or an enum, and
+ * `MessageAction.details` is not a substitute since it is prose populated from
+ * `cause?.toString?.()`, and a Theia host shows it to a user on demand. So the
+ * throw is the last place that still knows which message this is.
+ */
+export const SAVE_TARGET_UNKNOWN = defineMessage(
+   'hydranium/glsp-server/save-target-unknown',
+   'Could not determine where to save this model'
+);
+
+/**
+ * A model request arrived without the source URI it is required to carry.
+ * Rendered at the raise site, like its save-path sibling and for the same
+ * reason.
+ */
+export const SOURCE_URI_MISSING = defineMessage(
+   'hydranium/glsp-server/source-uri-missing',
+   'Could not open this model: the request did not say which document to load'
+);
+
+/**
+ * Why the canvas has stopped accepting edits.
+ *
+ * **A READONLY canvas is otherwise indistinguishable from a broken one.** The
+ * client's answer to {@link SetEditModeAction} is to withdraw the tool palette,
+ * so the surface a reader was working in silently loses the only control it had,
+ * with the cause — a syntax error in a document that may not even be open —
+ * nowhere on screen. The mode flip is the mechanism; this is the only part of it
+ * a user can see.
+ *
+ * Rendered at the raise site, like its two siblings above and for the same
+ * reason: every member of GLSP's status action is prose or an enum.
+ *
+ * It names the recovery rather than the fault, because the fault already has a
+ * surface — the squiggle and the problems list, both of which say WHICH
+ * character — and repeating it here would put a second, less precise account of
+ * the same error on screen. What no other surface says is that the diagram is
+ * waiting on it.
+ */
+export const DIAGRAM_READONLY_PARSE_ERROR = defineMessage(
+   'hydranium/glsp-server/diagram-readonly-parse-error',
+   'Read-only: this document has a syntax error. Fix it to edit the diagram again.'
+);
 
 /** Window (ms) over which back-to-back external rebuilds collapse into one resubmit. */
 const EXTERNAL_SUBMIT_DEBOUNCE_MS = 250;
@@ -90,17 +141,14 @@ function isStructuralDiagnostic(diagnostic: unknown): boolean {
  *
  * Adopters with richer needs override the seams ({@link isStructurallyBroken},
  * {@link onParseErrorChanged}, {@link onSourceModelSettled}) rather than the
- * whole flow, and select a {@link SaveConflictPolicy} via the bound option to
- * tune how {@link saveSourceModel} reacts to a concurrent edit.
+ * whole flow, and select a {@link SaveDeliveryPolicy} via the bound option to
+ * tune how {@link saveSourceModel} delivers its result.
  *
- * **Default `saveSourceModel` flow.** Delegates to `ModelService.save`, which
- * serialises through the language-specific `Serializer` bound at
- * `services.serializer.Serializer` (resolved per-URI via `ServiceRegistry`),
- * updates the multi-client text-document store, drives a rebuild, and writes the
- * result via the `WritableFileSystemProvider`. The bound
- * {@link SaveConflictPolicy} (default {@link DEFAULT_SAVE_CONFLICT_POLICY},
- * `overwrite`) decides the based-on-version guard, await-vs-fire-and-forget, and
- * failure handling.
+ * **Default `saveSourceModel` flow.** Flushes the stored text of the primary and
+ * every tracked secondary via `AstDocumentManager.save`, with no serializer in
+ * the path — the update path already put the settled text in the store. The
+ * bound {@link SaveDeliveryPolicy} (default {@link DEFAULT_SAVE_DELIVERY_POLICY},
+ * `await`) decides await-vs-fire-and-forget and failure handling.
  *
  * **tempId filter.** GLSP's `DefaultGlobalActionProvider` spins up a
  * throwaway per-diagram-type container with upstream's {@link TEMPORARY_CLIENT_ID}
@@ -137,14 +185,13 @@ export class HydraniumGlspStorage<TRoot extends AstNode, TSourceModel = string>
    @inject(ModelValidator) @optional() protected readonly modelValidator?: ModelValidator;
 
    /**
-    * Selected {@link SaveConflictPolicy} for {@link saveSourceModel}. Bind the
-    * {@link SaveConflictPolicy} token in a `DiagramModule` to choose a policy;
-    * left unbound it resolves to {@link DEFAULT_SAVE_CONFLICT_POLICY}
-    * (`overwrite`, last-write-wins). Read via {@link saveConflictPolicy} so the
-    * fallback is applied even when inversify injects `undefined` for an unbound
-    * `@optional()` member.
+    * Selected {@link SaveDeliveryPolicy} for {@link saveSourceModel}. Bind the
+    * {@link SaveDeliveryPolicy} token in a `DiagramModule` to choose a policy;
+    * left unbound it resolves to {@link DEFAULT_SAVE_DELIVERY_POLICY}. Read via
+    * {@link saveDeliveryPolicy} so the fallback is applied even when inversify
+    * injects `undefined` for an unbound `@optional()` member.
     */
-   @inject(SaveConflictPolicy) @optional() protected readonly boundSaveConflictPolicy?: SaveConflictPolicy;
+   @inject(SaveDeliveryPolicy) @optional() protected readonly boundSaveDeliveryPolicy?: SaveDeliveryPolicy;
 
    /** Disposables created during {@link doLoadSourceModel}; drained on session disposal. */
    protected toDispose = new DisposableCollection();
@@ -235,12 +282,29 @@ export class HydraniumGlspStorage<TRoot extends AstNode, TSourceModel = string>
    }
 
    /**
-    * Capture the initial settled root and apply the initial edit mode. `settled()`
-    * strips diagnostics by phase contract, so the first edit mode is `EDITABLE`;
-    * the first {@link handleModelUpdated} (at `Validated`, with diagnostics) flips
-    * it READONLY if the document has structural parse errors. Edit-mode +
-    * settle-hook actions are dispatched on a macrotask so the initial
+    * Capture the initial settled root and apply the initial edit mode. Edit-mode
+    * + settle-hook actions are dispatched on a macrotask so the initial
     * `requestModel → setModel` handshake isn't perturbed.
+    *
+    * **Whether the settled document carries diagnostics depends on how far it
+    * had already got, so the initial edit mode has two correct outcomes rather
+    * than one.** `settled()` strips nothing: it resolves AT OR ABOVE the
+    * integrity landmark and hands back the live document's own array. Its
+    * `AstDocument<TAst, never>` return type asserts emptiness for a document the
+    * wait had to DRIVE to that landmark, which is pre-validation — and for that
+    * one the mode here is `EDITABLE` and the flip to READONLY arrives with the
+    * first {@link handleModelUpdated}. A document already past `Validated` when
+    * the session opened resolves immediately with its diagnostics intact, and is
+    * decided correctly here with no later update owed. Any host that validates
+    * its workspace before a diagram is opened produces the second case, so
+    * neither is exceptional.
+    *
+    * **A correct decision is not a delivered one.** This dispatch happens inside
+    * the initial `requestModel`, before the client has the model — so the UI
+    * extensions that answer {@link onParseErrorChanged}'s actions are not yet
+    * constructed, and a canvas that opens READONLY over a broken document shows
+    * none of that feedback. The same timer carries {@link onSourceModelSettled},
+    * so an adopter's own initial actions have it too.
     */
    protected async captureSettledRoot(rootUri: string, document: AstDocument<AstNode, never>): Promise<void> {
       this.state.setSourceRoot(rootUri, document.root as TRoot);
@@ -333,9 +397,10 @@ export class HydraniumGlspStorage<TRoot extends AstNode, TSourceModel = string>
     *
     * Synchronous by construction — the phase-agnostic lookup door plus the shared
     * projection — so reacting to a secondary neither waits nor can force a build.
-    * `settled()` is not an alternative: it strips diagnostics by phase contract,
-    * and diagnostics are the reason {@link doUpdateAndSubmit} takes a separate
-    * event document at all.
+    * `settled()` is not an alternative: besides being asynchronous, it cannot be
+    * relied on to carry diagnostics — a document it has to drive to the landmark
+    * arrives pre-validation with an empty array — and diagnostics are the reason
+    * {@link doUpdateAndSubmit} takes a separate event document at all.
     */
    protected currentPrimaryDocument(): AstDocument<AstNode, unknown> | undefined {
       const document = this.sharedServices.model.ModelService.getDocument(this.state.sourceUri);
@@ -418,8 +483,10 @@ export class HydraniumGlspStorage<TRoot extends AstNode, TSourceModel = string>
    /**
     * Re-settle to a guaranteed fully-linked + reprojected root, capture it, and
     * (unless suppressed) resubmit a deduped external GModel. Diagnostics for the
-    * edit-mode decision come from the event document (`settled()` strips them by
-    * phase contract).
+    * edit-mode decision come from the event document, because the re-settled one
+    * cannot be relied on to have any: a document driven to the landmark arrives
+    * pre-validation, and this path re-settles precisely to escape a transient
+    * mid-rebuild snapshot.
     */
    protected async doUpdateAndSubmit(rootUri: string, eventDocument: AstDocument<AstNode, unknown>): Promise<Action[]> {
       // Settle-gate the capture: never setSourceRoot off the event's possibly-transient
@@ -481,15 +548,48 @@ export class HydraniumGlspStorage<TRoot extends AstNode, TSourceModel = string>
    }
 
    /**
-    * Seam: actions to emit when the structural-broken state transitions. Default:
-    * a single {@link SetEditModeAction} toggling READONLY ↔ EDITABLE — editing is
-    * disabled while the syntax is broken but re-enabled once it parses, a sound
-    * generic for any Langium-backed diagram. Adopters override to add or replace
-    * the transition feedback. The {@link AbstractHydraniumGlspState.editMode}
-    * flip itself is owned by {@link refreshEditMode}.
+    * Seam: actions to emit when the structural-broken state transitions.
+    * Default: a {@link SetEditModeAction} toggling READONLY ↔ EDITABLE — editing
+    * is disabled while the syntax is broken but re-enabled once it parses, a
+    * sound generic for any Langium-backed diagram — plus the
+    * {@link DIAGRAM_READONLY_PARSE_ERROR} band that says why, cleared on the way
+    * back. Adopters override to add or replace the transition feedback. The
+    * {@link AbstractHydraniumGlspState.editMode} flip itself is owned by
+    * {@link refreshEditMode}.
+    *
+    * **Both actions or neither, which is why they are one seam rather than
+    * two.** The mode flip removes the tool palette and the band is the only
+    * account of that, so an override that keeps one and drops the other produces
+    * either an unexplained loss of the palette or a warning about a restriction
+    * that is not in force.
+    *
+    * **The status is dispatched with no `timeout`, so it persists** — a
+    * time-limited band would describe a condition that outlasts it.
+    *
+    * **The slot is SHARED, and the other writer wins on one path.**
+    * `ModelSubmissionHandler`'s live validation writes the same slot, clearing
+    * it with `severity: 'NONE'` when it finishes, and an adopter dispatching its
+    * own `StatusAction` replaces this one too. Nothing re-asserts it. That is
+    * harmless while a document is being edited, because a resubmit is skipped
+    * once the AST is broken (see {@link doUpdateAndSubmit}) — but NOT at load:
+    * the initial `requestModel` submit is not that skipped path, so a diagram
+    * opened on an already-broken document shows this band and then loses it to
+    * the validation clear a moment later. Measured on a browser host, polling the
+    * overlay: no element, empty, the sentence, empty again.
     */
    protected onParseErrorChanged(_document: AstDocument<AstNode, unknown>, broken: boolean): Action[] {
-      return [SetEditModeAction.create(broken ? EditMode.READONLY : EditMode.EDITABLE)];
+      return [
+         SetEditModeAction.create(broken ? EditMode.READONLY : EditMode.EDITABLE),
+         broken
+            ? StatusAction.create(this.sharedServices.MessageRenderer.renderMessage(DIAGRAM_READONLY_PARSE_ERROR), {
+                 severity: 'WARNING'
+              })
+            : // `NONE` is the client's own spelling for "clear", not a severity it
+              // renders: `StatusOverlay.handle` branches on it before touching the
+              // DOM. An empty message at any other severity leaves an empty band
+              // with a warning icon standing on the canvas.
+              StatusAction.create('', { severity: 'NONE' })
+      ];
    }
 
    /**
@@ -500,32 +600,47 @@ export class HydraniumGlspStorage<TRoot extends AstNode, TSourceModel = string>
       return [];
    }
 
-   /** The effective {@link SaveConflictPolicy}: the bound option, or {@link DEFAULT_SAVE_CONFLICT_POLICY} when unbound. */
-   protected get saveConflictPolicy(): SaveConflictPolicy {
-      return this.boundSaveConflictPolicy ?? DEFAULT_SAVE_CONFLICT_POLICY;
+   /** The effective {@link SaveDeliveryPolicy}: the bound option, or {@link DEFAULT_SAVE_DELIVERY_POLICY} when unbound. */
+   protected get saveDeliveryPolicy(): SaveDeliveryPolicy {
+      return this.boundSaveDeliveryPolicy ?? DEFAULT_SAVE_DELIVERY_POLICY;
    }
 
    /**
-    * Default save flow: route through `ModelService.save`. The framework
-    * serialise-and-persist machinery handles serialisation (via the
-    * language-specific `Serializer` bound at `services.serializer.Serializer`),
-    * the multi-client text-document update, the rebuild, and the eventual
-    * `WritableFileSystemProvider.writeFile`.
+    * Default save flow: persist the store's current text for every document this
+    * diagram owns.
+    *
+    * **A save persists, it does not author.** Every diagram gesture already
+    * reached the store through `ModelService.update`, so the store holds the
+    * settled text and disk is the only thing behind. Re-serializing from the AST
+    * here cannot improve on that text and can only damage it: a serializer
+    * normalises formatting and carries no comments, so a save would reflow and
+    * strip a document nothing changed — which is what a pure bounds drag does to
+    * the semantic file when only its layout moved.
+    *
+    * **The write set is the primary plus every tracked secondary**
+    * (`AbstractHydraniumGlspState.trackSecondaryDocument`), so a document the
+    * diagram wrote is persisted whether or not it is the one the client named.
+    * The primary is flushed first, then secondaries in tracking order. A
+    * document no client holds open is skipped — there is no stored text to
+    * persist.
     *
-    * The configured {@link SaveConflictPolicy} (see {@link saveConflictPolicy})
-    * decides how a concurrent edit that advanced the document is handled:
-    * - `overwrite` (default): no based-on guard, await, propagate failures —
-    *   last-write-wins, correct for a single-editor head.
-    * - `reject`: guard on the captured `state.version`, await, surface a
-    *   `ConflictError` (and any other failure) to the GLSP save action.
-    * - `drop-and-log`: guard, fire-and-forget, log + swallow failures — a stale
-    *   diagram save is dropped because a concurrent form/code edit already wrote
-    *   the truth, and GLSP exposes no save-failure back-channel.
+    * **A save therefore names documents the gesture did not aim at**, which is
+    * why an unchanged one is not rewritten even though the user asked for a
+    * save: the mtime would move on a file they never touched.
+    * `AstDocumentManager.save` decides that per document and announces the save
+    * either way.
+    *
+    * The configured {@link SaveDeliveryPolicy} (see {@link saveDeliveryPolicy})
+    * decides await-vs-fire-and-forget and failure handling. It carries no
+    * based-on guard: the guard exists to stop a stale writer overwriting a newer
+    * document, and a flush persists the store — which already holds every other
+    * client's change, including the one that advanced the version.
     *
     * Returns `MaybePromise<void>` to match upstream `SourceModelStorage`:
-    * resolves with the persist under `overwrite`/`reject`, returns synchronously
-    * under `drop-and-log`. Adopters that bypass `ModelService` (writing through
-    * `WritableFileSystemProvider` directly) still override the whole method.
+    * resolves with the flush under `await`, returns synchronously under
+    * `fire-and-forget`. Adopters that bypass `AstDocumentManager` (writing
+    * through `WritableFileSystemProvider` directly) still override the whole
+    * method.
     */
    saveSourceModel(action: SaveModelAction): MaybePromise<void> {
       // Normalised for the same reason the load path is: `SaveModelAction.fileUri`
@@ -535,26 +650,36 @@ export class HydraniumGlspStorage<TRoot extends AstNode, TSourceModel = string>
       // the call site rather than inside `getFileUri` so that method's contract —
       // return what the action said — is unchanged for adopters overriding it.
       const uri = this.toSourceModelUri(this.getFileUri(action));
-      const policy = this.saveConflictPolicy;
-      const persisted = this.sharedServices.model.ModelService.save({
-         uri,
-         model: this.state.sourceRoot,
-         clientId: this.state.clientId,
-         baseVersion: policy.kind === 'overwrite' ? undefined : this.state.version
-      }).then(() => undefined);
-
-      if (policy.kind === 'drop-and-log') {
-         // Fire-and-forget: the diagram save lost the race to a concurrent edit
-         // that already persisted the truth, so it must neither block the action
-         // nor surface. Log rather than leave an unhandled rejection.
+      const policy = this.saveDeliveryPolicy;
+      const persisted = this.flushWriteSet(uri);
+
+      if (policy.kind === 'fire-and-forget') {
+         // Log rather than leave an unhandled rejection: the promise is not
+         // returned, so nothing else will observe a failure.
          persisted.catch(error => this.logger.error(`Save failed for ${uri}: ${error instanceof Error ? error.message : String(error)}`));
          return undefined;
       }
-      // overwrite / reject: await; a ConflictError (reject) or any other failure
-      // propagates to GLSP's save-action handler.
+      // Awaited: any failure propagates to GLSP's save-action handler.
       return persisted;
    }
 
+   /**
+    * Save the stored text of `primaryUri` and every tracked secondary.
+    *
+    * Deduplicated, because a state that tracks its own primary as a secondary
+    * would otherwise save it twice and fire two save notifications for one
+    * save. A document no client holds open is skipped: there is no stored text
+    * to persist, and `AstDocumentManager.save` throws on one.
+    */
+   protected async flushWriteSet(primaryUri: string): Promise<void> {
+      const documents = this.sharedServices.workspace.AstDocumentManager;
+      for (const target of new Set([primaryUri, ...this.state.secondaryUris])) {
+         if (documents.isOpen(target)) {
+            await documents.save(target, this.state.clientId);
+         }
+      }
+   }
+
    /**
     * Normalise GLSP's `sourceUri` — which may be a filesystem PATH or a URI
     * string — to the URI string the workspace keys documents by.
@@ -584,11 +709,25 @@ export class HydraniumGlspStorage<TRoot extends AstNode, TSourceModel = string>
     *
     * Returns it VERBATIM, in whatever form the client sent;
     * {@link toSourceModelUri} is what normalises it.
+    *
+    * A model request DOES carry a request id, so a throw here takes the
+    * client-request path rather than the toast path — and on that path `detail`
+    * comes from `cause?.toString?.()`. A single-argument throw therefore reaches
+    * neither the server log nor the client console: both print `undefined`. So
+    * the two readers are addressed separately, as on the save path: `message`
+    * names what failed in the user's terms and is rendered, `cause` names the
+    * action and the option key that was missing and stays English. On THIS path
+    * the cause reaches only logs — `RejectAction.detail` is read by nothing but
+    * the client action-dispatcher's `logger.warn` — which is not what makes it
+    * English; its content is.
     */
    protected getSourceUri(action: RequestModelAction): string {
       const sourceUri = action.options?.[SOURCE_URI_ARG];
       if (typeof sourceUri !== 'string') {
-         throw new GLSPServerError(`Invalid RequestModelAction! Missing argument with key '${SOURCE_URI_ARG}'`);
+         throw new GLSPServerError(
+            this.sharedServices.MessageRenderer.renderMessage(SOURCE_URI_MISSING),
+            `no '${SOURCE_URI_ARG}' option on the ${action.kind} action (received ${typeof sourceUri})`
+         );
       }
       return sourceUri;
    }
@@ -600,18 +739,24 @@ export class HydraniumGlspStorage<TRoot extends AstNode, TSourceModel = string>
     * {@link AbstractHydraniumGlspState.setSourceRoot}.
     *
     * A save action carries no request id, so a throw here reaches the user as a
-    * toast built from `message`, with `cause` behind its details control. The
-    * two therefore address different readers and must not be collapsed: the
-    * message names what failed in the user's terms, and the cause names which
-    * lookups came back empty for whom. Neither can name the URI — not having
-    * one IS the failure, and both sources are written together, so the typed
-    * `sourceUri` is equally empty whenever this fires.
+    * toast built from `message`, while `cause` travels in
+    * `MessageAction.details` — **which a Theia host DOES put in front of a
+    * user**, as a "Show details" button on the toast opening a dialog. So the
+    * two are not split by reachability; they are split by AUDIENCE, which is
+    * the older rule and the one that holds here. The message names what failed
+    * in the user's terms and is rendered; the cause names which lookups came
+    * back empty for whom, and stays English because a wire action kind, an
+    * option key and a client id address whoever composes the system — a
+    * translated developer string is a worse outcome than an untranslated one.
+    * Neither can name the URI — not having one IS the failure, and both sources
+    * are written together, so the typed `sourceUri` is equally empty whenever
+    * this fires.
     */
    protected getFileUri(action: SaveModelAction): string {
       const uri = action.fileUri ?? this.state.get<string>(SOURCE_URI_ARG);
       if (!uri) {
          throw new GLSPServerError(
-            'Could not determine where to save this model',
+            this.sharedServices.MessageRenderer.renderMessage(SAVE_TARGET_UNKNOWN),
             `no fileUri on the save action and no ${SOURCE_URI_ARG} in the model state (clientId=${this.state.clientId})`
          );
       }

package/src/storage/index.ts

@@ -8,4 +8,4 @@
  ********************************************************************************/
 
 export * from './hydranium-glsp-storage.js';
-export * from './save-conflict-policy.js';
+export * from './save-delivery-policy.js';

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

@@ -0,0 +1,44 @@
+/********************************************************************************
+ * 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` delivers its result: whether the
+ * GLSP save action awaits the write, and what happens on failure.
+ *
+ * The two are not independent — fire-and-forget plus rethrow would leave an
+ * unhandled rejection — so each arm bundles them into one coherent, nameable
+ * policy an adopter selects whole. It is a *selection of configuration*,
+ * delivered as a bound option (see the {@link SaveDeliveryPolicy} symbol) rather
+ * than a behaviour hook.
+ *
+ * **Neither arm guards on a based-on version.** A save flushes the store's
+ * settled text rather than authoring from the diagram's captured model, and the
+ * store already holds every other client's change — so a guard here refuses a
+ * write whose content is already correct. The gate that does exist sits on the
+ * update path, per operation, where the diagram authors.
+ */
+export type SaveDeliveryPolicy =
+   /** Await the write and propagate any failure to the GLSP save action. The default. */
+   | { kind: 'await' }
+   /**
+    * Fire-and-forget, logging and swallowing every failure. Correct when a
+    * failed diagram save must neither block the action nor surface as an error.
+    */
+   | { kind: 'fire-and-forget' };
+
+/** The policy applied when no {@link SaveDeliveryPolicy} option is bound. */
+export const DEFAULT_SAVE_DELIVERY_POLICY: SaveDeliveryPolicy = { kind: 'await' };
+
+/**
+ * DI token for the {@link SaveDeliveryPolicy} option. Bind a constant value in a
+ * `DiagramModule` to select a non-default policy; left unbound,
+ * `HydraniumGlspStorage` falls back to {@link DEFAULT_SAVE_DELIVERY_POLICY}.
+ * Shares its name with the type, the way a `class` is both a value and a type.
+ */
+export const SaveDeliveryPolicy = Symbol('SaveDeliveryPolicy');

package/src/validation/diagnostic-markers.ts

@@ -65,8 +65,15 @@ export function diagnosticsToMarkers(diagnostics: readonly TransferLspDiagnostic
  * The ids of the elements drawn on this diagram for the diagnostic's target,
  * starting at the node it points at and walking up its containers; empty when
  * the path does not resolve or nothing on the chain is rendered.
+ *
+ * @param elementPath absent for a lexer or parser error, which Langium pushes
+ *    onto the document without one — such a diagnostic points at text no node
+ *    was built from, so it marks nothing.
  */
-function renderedElementIds(elementPath: string, lookups: DiagnosticMarkerLookups): readonly string[] {
+function renderedElementIds(elementPath: string | undefined, lookups: DiagnosticMarkerLookups): readonly string[] {
+   if (elementPath === undefined) {
+      return [];
+   }
    let node: AstNode | undefined = lookups.resolveElement(elementPath);
    while (node !== undefined) {
       const ids = lookups.renderedIdsFor(node);