@hydranium/glsp-server 1.0.0-next.8 → 1.0.0-next.85

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();
@@ -178,7 +225,7 @@ export class HydraniumGlspStorage<TRoot extends AstNode, TSourceModel = string>
    protected resubmitDebouncer!: Debouncer;
 
    /** Latest event document awaiting the debounced resubmit; read by {@link flushResubmit} (last write wins). */
-   protected pendingResubmitDocument?: AstDocument<AstNode, unknown>;
+   protected pendingResubmitDocument?: AstDocument<AstNode>;
 
    @postConstruct()
    protected init(): void {
@@ -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);
@@ -312,7 +376,7 @@ export class HydraniumGlspStorage<TRoot extends AstNode, TSourceModel = string>
     * drag this client authors — the guard above gates the resubmit, not the
     * markers.
     */
-   protected handleSecondaryUpdated(uri: string, event: AstDocumentUpdatedEvent<AstNode, unknown>): void {
+   protected handleSecondaryUpdated(uri: string, event: AstDocumentUpdatedEvent<AstNode>): void {
       if (this.disposeIfStale(uri)) {
          return;
       }
@@ -333,11 +397,12 @@ 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 {
+   protected currentPrimaryDocument(): AstDocument<AstNode> | undefined {
       const document = this.sharedServices.model.ModelService.getDocument(this.state.sourceUri);
       return document ? AstDocument.from(document) : undefined;
    }
@@ -350,7 +415,7 @@ export class HydraniumGlspStorage<TRoot extends AstNode, TSourceModel = string>
     * diagnostic markers for every update — including own edits, which skip
     * the resubmit but can still change diagnostics.
     */
-   protected async handleModelUpdated(rootUri: string, event: AstDocumentUpdatedEvent<AstNode, unknown>): Promise<void> {
+   protected async handleModelUpdated(rootUri: string, event: AstDocumentUpdatedEvent<AstNode>): Promise<void> {
       if (this.disposeIfStale(rootUri)) {
          return;
       }
@@ -382,7 +447,7 @@ export class HydraniumGlspStorage<TRoot extends AstNode, TSourceModel = string>
     * {@link resubmitDebouncer}, so a burst of rebuilds runs
     * {@link doUpdateAndSubmit} once with the most recent document.
     */
-   protected scheduleUpdateAndSubmit(document: AstDocument<AstNode, unknown>): void {
+   protected scheduleUpdateAndSubmit(document: AstDocument<AstNode>): void {
       this.pendingResubmitDocument = document;
       this.resubmitDebouncer.schedule();
    }
@@ -409,7 +474,7 @@ export class HydraniumGlspStorage<TRoot extends AstNode, TSourceModel = string>
     * mark our stack clean so the editor doesn't prompt to re-save identical
     * content. Our own saves already settle the stack through the save flow.
     */
-   protected handleModelSaved(event: AstDocumentSavedEvent<AstNode, unknown>): void {
+   protected handleModelSaved(event: AstDocumentSavedEvent<AstNode>): void {
       if (this.state.clientId !== event.sourceClientId) {
          this.commandStack.saveIsDone();
       }
@@ -418,10 +483,12 @@ 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[]> {
+   protected async doUpdateAndSubmit(rootUri: string, eventDocument: AstDocument<AstNode>): Promise<Action[]> {
       // Settle-gate the capture: never setSourceRoot off the event's possibly-transient
       // snapshot — the event can arrive while a re-entered document is mid-rebuild.
       const document = await this.sharedServices.model.ModelService.settled(rootUri);
@@ -459,7 +526,7 @@ export class HydraniumGlspStorage<TRoot extends AstNode, TSourceModel = string>
     * flip {@link AbstractHydraniumGlspState.editMode}, and — only on a transition —
     * return the {@link onParseErrorChanged} actions. No transition → no actions.
     */
-   protected refreshEditMode(document: AstDocument<AstNode, unknown>): Action[] {
+   protected refreshEditMode(document: AstDocument<AstNode>): Action[] {
       const broken = this.isStructurallyBroken(document);
       const previousEditMode = this.state.editMode;
       this.state.editMode = broken ? EditMode.READONLY : EditMode.EDITABLE;
@@ -476,20 +543,53 @@ export class HydraniumGlspStorage<TRoot extends AstNode, TSourceModel = string>
     * carrying a Langium `lexing-error` / `parsing-error` code. Adopters override
     * to compose additional break reasons.
     */
-   protected isStructurallyBroken(document: AstDocument<AstNode, unknown>): boolean {
+   protected isStructurallyBroken(document: AstDocument<AstNode>): boolean {
       return document.diagnostics.some(diagnostic => isStructuralDiagnostic(diagnostic));
    }
 
    /**
-    * 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)];
+   protected onParseErrorChanged(_document: AstDocument<AstNode>, broken: boolean): Action[] {
+      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

@@ -10,7 +10,7 @@
 import { type Marker, MarkerKind } from '@eclipse-glsp/protocol';
 import { type AstNode } from '@hydranium/langium';
 import { Diagnostic, DiagnosticSeverity } from 'vscode-languageserver-types';
-import { type TransferLspDiagnostic } from '@hydranium/core';
+import { type AstDiagnostic } from '@hydranium/core';
 
 /**
  * The model-shaped lookups the diagnostic→marker translation needs, injected so
@@ -48,7 +48,7 @@ export interface DiagnosticMarkerLookups {
  * `MarkersReason` so a fresh `SetMarkersAction` replaces the previous markers
  * (an empty result clears them when all errors are fixed).
  */
-export function diagnosticsToMarkers(diagnostics: readonly TransferLspDiagnostic[], lookups: DiagnosticMarkerLookups): Marker[] {
+export function diagnosticsToMarkers(diagnostics: readonly AstDiagnostic[], lookups: DiagnosticMarkerLookups): Marker[] {
    const markers: Marker[] = [];
    for (const diagnostic of diagnostics) {
       const kind = markerKind(diagnostic.severity);
@@ -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);

package/src/validation/hydranium-glsp-model-validator.ts

@@ -12,7 +12,7 @@ import { type GModelElement, ModelState, type ModelValidator } from '@eclipse-gl
 import { inject, injectable } from 'inversify';
 import { type AstNode } from '@hydranium/langium';
 import { URI } from '@hydranium/langium';
-import { type ServerSharedServices, type TransferLspDiagnostic } from '@hydranium/core';
+import { type ServerSharedServices, type AstDiagnostic } from '@hydranium/core';
 import { type AbstractHydraniumGlspState } from '../state/abstract-hydranium-glsp-state.js';
 import { HydraniumTypes } from '../state/hydranium-shared-core-services.js';
 import { type DiagnosticMarkerLookups, diagnosticsToMarkers } from './diagnostic-markers.js';
@@ -75,9 +75,9 @@ export class HydraniumGlspModelValidator<TRoot extends AstNode = AstNode> implem
             continue;
          }
          // Diagnostics are produced by the framework's `HydraniumDocumentValidator`,
-         // which emits `TransferLspDiagnostic` (LSP `Diagnostic` + `element` path).
+         // which emits `AstDiagnostic` (LSP `Diagnostic` + `element` path).
          // Parser/lexer diagnostics carry no `element`; the lookup drops them.
-         const diagnostics = document.diagnostics as TransferLspDiagnostic[] | undefined;
+         const diagnostics = document.diagnostics as AstDiagnostic[] | undefined;
          if (!diagnostics || diagnostics.length === 0) {
             continue;
          }