@hydranium/core 1.0.0-next.36 → 1.0.0-next.38

package/src/langium/model-service/model-service.ts

@@ -200,7 +200,74 @@ export interface ModelServiceOptions extends LogNameOptions {
  *   args. Constrained to {@link TransferElement}. Defaults to the
  *   structural base.
  */
-export class ModelService<
+/**
+ * The seam every non-LSP head talks to: the data server, the GLSP head and an
+ * adopter's own services reach documents through this slot rather than through
+ * the workspace stores.
+ *
+ * **Two families, and the distinction matters more than the names suggest.**
+ * `waitFor*` is a pure wait — it never triggers a build, so a caller waiting on
+ * a document no build has touched waits until something else builds it.
+ * `ensureDocumentState` and the phase shorthands over it *dispatch*: warm
+ * documents are awaited, cold ones are built.
+ *
+ * **Diagnostics are typed `never` below `Validated`.** Validation is the last
+ * phase, so at any earlier landmark the array either is not yet computed or
+ * still holds the previous build's, and reading it would take stale results
+ * for fresh ones. A caller that needs diagnostics asks for {@link validated}.
+ *
+ * What the `never` buys, exactly: reading a field off an element is a compile
+ * error, and nothing can be appended. It does NOT stop a caller assigning an
+ * element to a typed variable, because `never` is assignable to everything — so
+ * this is a guard against reaching for diagnostics by accident, not a seal
+ * against doing it deliberately.
+ *
+ * The waits resolve at or ABOVE their target, so an already-validated document
+ * does carry usable diagnostics and the `never` over-forbids there. That
+ * direction is the safe one: the alternative permits stale reads silently. A
+ * member taking a phase as a PARAMETER cannot judge statically and so returns
+ * `TDiagnostic`, leaving the choice to the caller.
+ */
+export interface ModelService<TAst extends AstNode, TDiagnostic = TransferDiagnostic, TTransfer extends TransferElement = TransferElement> {
+   /**
+    * Resolves once the workspace has been initialised and its first build has
+    * completed — the gate every read should wait behind, since a document
+    * queried before it may be unbuilt and reach no phase.
+    *
+    * A property rather than a method, matching `ProjectManager.ready` and
+    * Langium's `WorkspaceManager.ready`. An implementation needing a stricter
+    * gate supplies a Promise that awaits its own concern as well.
+    */
+   readonly ready: Promise<void>;
+
+   // Pure waits — never trigger a build.
+   waitForDocumentState(uri: string, state: DocumentState, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+   waitForDocumentSettled(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
+   waitForBuilderState(state: DocumentState, cancelToken?: CancellationToken): Promise<void>;
+
+   // Wait if warm, build if cold.
+   ensureDocumentState(uri: string, state?: DocumentState, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+   rebuild(uri: string, state?: DocumentState, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+   parsed(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
+   linked(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
+   settled(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
+   indexed(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>>;
+   validated(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+
+   update(args: TransferUpdateArgs<TTransfer>, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+   save(args: TransferSaveArgs<TTransfer>, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>>;
+
+   open(args: OpenModelArgs): Promise<Disposable>;
+   close(args: CloseModelArgs): Promise<void>;
+   isOpen(uri: string): boolean;
+   getDocument(uri: string): LangiumDocument | undefined;
+
+   onModelUpdated(uri: string, listener: (event: AstDocumentUpdatedEvent<TAst, TDiagnostic>) => void): Disposable;
+   onModelSaved(uri: string, listener: (event: AstDocumentSavedEvent<TAst, TDiagnostic>) => void): Disposable;
+   onClientClosed(uri: string, clientId: string, listener: () => void): Disposable;
+}
+
+export class DefaultModelService<
    TAst extends AstNode,
    TDiagnostic = TransferDiagnostic,
    /**
@@ -213,7 +280,7 @@ export class ModelService<
     * integrity service) that pass AST roots remain compatible.
     */
    TTransfer extends TransferElement = TransferElement
-> {
+> implements ModelService<TAst, TDiagnostic, TTransfer> {
    protected readonly tracer: Tracer;
    /**
     * The single document-identity seam (`services.workspace.DocumentUriPolicy`),
@@ -347,8 +414,12 @@ export class ModelService<
     * {@link waitForDocumentState} for the common "wait until content is stable"
     * case (e.g. settling a save). Pure wait — does not trigger a build.
     */
-   async waitForDocumentSettled(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, TDiagnostic>> {
-      return this.waitForDocumentStateCanonical(this.uriPolicy.canonicalUri(uri), IntegrityService.SettledState, cancelToken);
+   async waitForDocumentSettled(uri: string, cancelToken?: CancellationToken): Promise<AstDocument<TAst, never>> {
+      return (await this.waitForDocumentStateCanonical(
+         this.uriPolicy.canonicalUri(uri),
+         IntegrityService.SettledState,
+         cancelToken
+      )) as AstDocument<TAst, never>;
    }
 
    /**
@@ -863,17 +934,17 @@ export class ModelService<
     *
     * The signal is "a known client other than the language client authored this
     * version **and** the URI was in the last build's changed set
-    * (`isDirectChange`)". A framework-internal rebuild reports no author
+    * (`isTriggeringEdit`)". A framework-internal rebuild reports no author
     * (`getAuthor` → `undefined`), so it fails `hasKnownAuthor` without comparing
     * against a sentinel. This is NOT redundant with content/registration — it
     * distinguishes "client edited" from "framework rebuilt", which neither the
-    * shadow nor `isDirectChange` alone can.
+    * shadow nor `isTriggeringEdit` alone can.
     */
    protected isNonLanguageClientEdit(document: LangiumDocument): boolean {
       const documents = this.services.workspace.AstDocumentManager;
       const author = documents.getAuthor(document);
       const hasKnownAuthor = !!author && author !== LANGUAGE_CLIENT_ID;
-      return hasKnownAuthor && documents.isDirectChange(document.textDocument.uri);
+      return hasKnownAuthor && documents.isTriggeringEdit(document.textDocument.uri);
    }
 
    /**

package/src/langium/module.ts

@@ -7,23 +7,23 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
-import { type Clock, type Logger, type Project, type Tracer, type TransferDiagnostic, NoopLogger, SystemClock } from '@hydranium/protocol';
-import { ServerLocale } from '../locale/server-locale.js';
-import { ServerMessageRenderer } from '../messages/renderer.js';
+import { type Clock, type Logger, type Project, type Tracer, NoopLogger, SystemClock } from '@hydranium/protocol';
+import { DefaultServerLocale, type ServerLocale } from '../locale/server-locale.js';
+import { DefaultMessageRenderer, type MessageRenderer } from '../messages/renderer.js';
 import { ServerTracer } from './diagnostics/server-tracer.js';
 import { HydraniumLangiumProfiler } from './diagnostics/hydranium-langium-profiler.js';
 import { type AstNode, type Module } from '@hydranium/langium';
 import { type DefaultSharedModuleContext, type LangiumSharedServices, type PartialLangiumSharedServices } from '@hydranium/langium/lsp';
 import { type TextDocument } from 'vscode-languageserver-textdocument';
-import { ModelService } from './model-service/model-service.js';
+import { DefaultModelService, type ModelService } from './model-service/model-service.js';
 import { type ProjectManager } from './project/project-manager.js';
 import { SingleProjectManager } from './project/single-project-manager.js';
-import { TransferEncoder } from './transfer/transfer-encoder.js';
+import { DefaultTransferEncoder, type TransferEncoder } from './transfer/transfer-encoder.js';
 import { HydraniumDocumentBuilder } from './document-builder/document-builder.js';
-import { BuildPipelineIntegration } from './document-builder/build-pipeline-integration.js';
+import { DefaultBuildPipelineIntegration, type BuildPipelineIntegration } from './document-builder/build-pipeline-integration.js';
 import { type BuildPhasePassContribution } from './build-phase-pass/build-phase-pass.js';
 import { type BuildPhasePassService, DefaultBuildPhasePassService } from './build-phase-pass/build-phase-pass-service.js';
-import { CstResidencyService } from './residency/index.js';
+import { DefaultCstResidencyService, type CstResidencyService } from './residency/index.js';
 import { HydraniumIndexManager } from './workspace/index-manager.js';
 import { HydraniumWorkspaceManager } from './workspace/hydranium-workspace-manager.js';
 import { HydraniumWorkspaceLock } from './workspace/hydranium-workspace-lock.js';
@@ -32,8 +32,8 @@ import { type HydraniumDocumentRegistry, HydraniumLangiumDocuments } from './wor
 import { type AdditionalDocumentContribution } from './workspace/additional-document-contribution.js';
 import { DefaultDocumentUriPolicy, type DocumentUriPolicy } from './workspace/document-uri-policy.js';
 import { HydraniumTextDocuments } from '../documents/hydranium-text-documents.js';
-import { AstDocumentManager, type WritableFileSystemProvider } from '../documents/ast-document-manager.js';
-import { SelfSaveRegistry } from '../documents/self-save-registry.js';
+import { DefaultAstDocumentManager, type AstDocumentManager, type WritableFileSystemProvider } from '../documents/ast-document-manager.js';
+import { DefaultSelfSaveRegistry, type SelfSaveRegistry } from '../documents/self-save-registry.js';
 import { DefaultEmptyFileSystemProvider } from './workspace/file-system-provider.js';
 import { type ServerLanguageServices } from './language-module.js';
 import { ExtendedServiceRegistry } from './service-registry.js';
@@ -105,7 +105,7 @@ export interface ServerAddedSharedServices<TProject extends Project = Project> {
     * returns every sentence unchanged. Adopters subclass and override
     * `translationsFor`.
     */
-   MessageRenderer: ServerMessageRenderer;
+   MessageRenderer: MessageRenderer;
    /**
     * The locale an init handed the server, for whoever renders in it. Held
     * apart from the renderer so replacing the renderer cannot drop locale
@@ -255,14 +255,22 @@ export interface ServerAddedSharedServices<TProject extends Project = Project> {
     * heads read both slots from shared services rather than constructor
     * arguments.
     *
-    * Slot types use the upper bounds (`unknown` for encoder map / facade
-    * generics, {@link TransferDiagnostic} for the encoder's wire-diagnostic
-    * shape) so adopter subclasses with narrower typed overlays satisfy
-    * the slot via output-position covariance — `TDiagnostic` appears
-    * only in encoder return positions.
+    * `TransferEncoder` is the INTERFACE, not `DefaultTransferEncoder` — an
+    * adopter can therefore REPLACE this declaration (see
+    * {@link WithServiceOverrides}) rather than intersect with it, which is what
+    * keeps slot resolution independent of the order a services type is written
+    * in. `ModelService` is still a class and does not yet have that property.
+    *
+    * A class in a slot costs two things, both measured. Its `protected` members
+    * join every assignability check and are compared NOMINALLY, so a subclass
+    * declared against a second physical copy of this package cannot satisfy it.
+    * And where the class is generic over a map reached through `keyof`, that
+    * parameter is measured INVARIANT — instantiations then relate only when
+    * their arguments are mutually assignable, which no adopter map is with the
+    * framework's. Neither survives on an interface.
     */
    model: {
-      TransferEncoder: TransferEncoder<unknown, TransferDiagnostic>;
+      TransferEncoder: TransferEncoder;
       ModelService: ModelService<AstNode, unknown>;
    };
    /**
@@ -306,6 +314,45 @@ export type ServerSharedServices<TProject extends Project = Project> = Omit<Lang
    workspace: Omit<LangiumSharedServices['workspace'], 'TextDocuments' | 'DocumentBuilder'>;
 } & ServerAddedSharedServices<TProject>;
 
+/**
+ * The service-tree namespaces — the keys whose value groups further slots
+ * rather than being a slot itself.
+ *
+ * Consumed by {@link WithServiceOverrides} to know where to merge one level
+ * deeper. **Add a namespace to {@link ServerAddedSharedServices} and you must
+ * add it here**, and the failure of forgetting is silent in the direction that
+ * matters: an unlisted namespace is treated as a leaf, so an adopter overriding
+ * one slot inside it replaces the WHOLE namespace and loses the sibling slots
+ * with no diagnostic. The reverse mistake — listing a leaf — fails loudly.
+ */
+type ServiceNamespace = 'lsp' | 'workspace' | 'model';
+
+/**
+ * Compose an adopter's service tree so its declarations REPLACE the framework's
+ * rather than intersecting with them.
+ *
+ * Langium composes services by intersection, which accumulates: two
+ * declarations of one slot survive as an overload set, and which one a call
+ * resolves to depends on the order the intersection was written in — silently,
+ * with no diagnostic at the point a reorder changes it. There is no override
+ * operator for intersections, so the framework's declaration has to be removed
+ * before the adopter's is added. This does that, one level deep for each
+ * {@link ServiceNamespace}, so a narrowed slot replaces its framework twin
+ * while its siblings survive.
+ *
+ * Only slots typed as INTERFACES can be replaced this way. A class-typed slot
+ * drags its `protected` members into the assignability check — compared
+ * nominally — so an adopter subclass does not satisfy it and the framework's
+ * declaration cannot be dropped.
+ */
+export type WithServiceOverrides<TBase, TOverrides> = Omit<TBase, keyof TOverrides> & {
+   [K in keyof TOverrides]: K extends ServiceNamespace
+      ? K extends keyof TBase
+         ? Omit<TBase[K], keyof TOverrides[K]> & TOverrides[K]
+         : TOverrides[K]
+      : TOverrides[K];
+};
+
 /**
  * Construction context for {@link createServerSharedModule}.
  *
@@ -354,8 +401,8 @@ export function createServerSharedModule(
       ServiceRegistry: services => new ExtendedServiceRegistry<ServerLanguageServices>(services),
       Logger: () => new NoopLogger(),
       Tracer: services => new ServerTracer(services.Logger, services.Clock),
-      ServerLocale: services => new ServerLocale(services),
-      MessageRenderer: services => new ServerMessageRenderer(services),
+      ServerLocale: services => new DefaultServerLocale(services),
+      MessageRenderer: services => new DefaultMessageRenderer(services),
       // Bind Langium's per-grammar-rule / per-`$type` parse/link/validate
       // profiler (the data the framework's own `Tracer`/`ProfileSession` passes
       // cannot produce), routed through our `Logger` and debug-gated. At the
@@ -430,7 +477,7 @@ export function createServerSharedModule(
          // scope tracker — `@hydranium/core/node` does.
          WorkspaceLock: () => new HydraniumWorkspaceLock(),
          ProjectManager: services => new SingleProjectManager(services),
-         SelfSaveRegistry: services => new SelfSaveRegistry(services),
+         SelfSaveRegistry: services => new DefaultSelfSaveRegistry(services),
          DocumentUriPolicy: () => new DefaultDocumentUriPolicy(),
          // Writable filesystem with two paths:
          // - Adopter passed `context.fileSystemProvider` and it returned a
@@ -454,20 +501,20 @@ export function createServerSharedModule(
             }
             return new DefaultEmptyFileSystemProvider(services);
          },
-         AstDocumentManager: services => new AstDocumentManager(services),
+         AstDocumentManager: services => new DefaultAstDocumentManager(services),
          // Eagerly constructed, so its build-phase listeners attach before the
          // first build.
-         BuildPipelineIntegration: services => new BuildPipelineIntegration(services),
+         BuildPipelineIntegration: services => new DefaultBuildPipelineIntegration(services),
          BuildPhasePassService: services => new DefaultBuildPhasePassService(services),
          // Eagerly constructed, so its `Validated` pass registers before the
          // first build.
-         CstResidencyService: services => new CstResidencyService(services)
+         CstResidencyService: services => new DefaultCstResidencyService(services)
       },
       model: {
          // Generic walker — adopters with a typed `$type → wire shape` overlay
          // rebind this slot with a subclass.
-         TransferEncoder: services => new TransferEncoder(services),
-         ModelService: services => new ModelService(services)
+         TransferEncoder: services => new DefaultTransferEncoder(services),
+         ModelService: services => new DefaultModelService(services)
       },
       // Empty default so `services.buildPhasePasses` always resolves (Langium
       // throws on access to an unbound slot). The framework's own integrity /

package/src/langium/residency/cst-residency-service.ts

@@ -24,9 +24,13 @@ import { type ServerSharedServicesMinimal } from '../shared-services.js';
 /**
  * Default priority of the CST-residency pass. Deliberately very high so it runs
  * *last* among `Validated` build-phase passes (the registry iterates priority
- * ascending): every other reaction to the build — an adopter's own derived-state
- * pass included — settles while the CST is still guaranteed resident, before the
- * residency policy arms the shed.
+ * ascending).
+ *
+ * The ordering is defensive, not load-bearing: the pass only arms or cancels an
+ * idle timer, so every pass at `Validated` reads a resident CST whichever order
+ * they run in, and lowering it changes nothing observable while that holds. It
+ * becomes load-bearing the moment the shed stops being deferred — a pass that
+ * frees the CST synchronously has to run after every reader of it.
  */
 export const CST_RESIDENCY_PASS_PRIORITY = 1_000_000;
 
@@ -227,7 +231,27 @@ function rehydrateCst(document: LangiumDocument, factory: LangiumDocumentFactory
  * `NameProvider.getNameNode` chokepoint, the comment provider, and
  * `HydraniumLangiumDocuments.getOrCreateDocument`.
  */
-export class CstResidencyService {
+/**
+ * Keeps a document's CST available to the readers that need one, shedding it
+ * for documents that have gone idle and re-grafting on demand.
+ */
+export interface CstResidencyService {
+   /**
+    * Ensure `document` has a CST, re-parsing its retained text if it was shed.
+    * A resident document is left exactly as it is, so this is safe to call on
+    * a hot path and safe to call twice.
+    */
+   rehydrate(document: LangiumDocument): void;
+
+   /**
+    * Node-level convenience over {@link rehydrate}, cheap enough for an
+    * unconditional call: a node whose `$cstNode` is already set returns
+    * without resolving its document.
+    */
+   rehydrateNode(node: AstNode): void;
+}
+
+export class DefaultCstResidencyService implements CstResidencyService {
    protected readonly strategy: CstResidencyStrategy;
    /** Bytes-per-node for the optional reclaim estimate in traces; `0` disables it. */
    protected readonly estimatedBytesPerShedNode: number;
@@ -277,8 +301,8 @@ export class CstResidencyService {
     * until navigation latency on shed files is actually observed to hurt. This
     * method is where that hook goes.
     */
-   rehydrate(document: LangiumDocument): boolean {
-      return rehydrateCst(document, this.services.workspace.LangiumDocumentFactory);
+   rehydrate(document: LangiumDocument): void {
+      rehydrateCst(document, this.services.workspace.LangiumDocumentFactory);
    }
 
    /**
@@ -287,11 +311,11 @@ export class CstResidencyService {
     * `true` without even resolving the document, so hot read paths
     * (`getNameNode`, comment lookup) call this unconditionally.
     */
-   rehydrateNode(node: AstNode): boolean {
+   rehydrateNode(node: AstNode): void {
       if (node.$cstNode !== undefined) {
-         return true;
+         return;
       }
-      return this.rehydrate(AstUtils.getDocument(node));
+      this.rehydrate(AstUtils.getDocument(node));
    }
 
    /**
@@ -353,8 +377,8 @@ export class CstResidencyService {
       this.shedTotal += this.shed(document);
    }
 
-   /** Cancel and drop every idle timer — for clean shutdown and deterministic tests. */
-   dispose(): void {
+   /** Cancel every armed shed, so a document that has gone idle keeps its CST. */
+   cancelPendingShed(): void {
       for (const timer of this.idleTimers.values()) {
          timer.dispose();
       }

package/src/langium/shared-services.ts

@@ -10,7 +10,7 @@
 import type { Clock, Logger, Project, Tracer } from '@hydranium/protocol';
 import type { LangiumSharedCoreServices } from '@hydranium/langium';
 import type { ServerLocale } from '../locale/server-locale.js';
-import type { ServerMessageRenderer } from '../messages/renderer.js';
+import type { MessageRenderer } from '../messages/renderer.js';
 import type { SelfSaveRegistry } from '../documents/self-save-registry.js';
 import type { WritableFileSystemProvider } from '../documents/ast-document-manager.js';
 import type { HydraniumDocumentRegistry } from './workspace/langium-documents.js';
@@ -31,7 +31,7 @@ import type { AdditionalDocumentContribution } from './workspace/additional-docu
  * {@link Clock}, {@link Logger} and {@link Tracer} top-level slots (injectable
  * time source, emission-only logger, and the measure-and-emit tracer composed
  * from the other two), the {@link AdditionalDocumentContribution} group, the
- * {@link ServerMessageRenderer} and the {@link ServerLocale} it renders in,
+ * {@link MessageRenderer} and the {@link ServerLocale} it renders in,
  * an {@link ExtendedServiceRegistry}, and on `workspace` a writable file-system
  * provider plus {@link HydraniumWorkspaceManager}, {@link ProjectManager},
  * {@link SelfSaveRegistry}, {@link BuildPipelineIntegration},
@@ -66,7 +66,7 @@ export interface ServerSharedServicesMinimal<TProject extends Project = Project>
     * shared tier with no workspace dependency, because all three heads'
     * messages pass through it.
     */
-   MessageRenderer: ServerMessageRenderer;
+   MessageRenderer: MessageRenderer;
    /** The locale an init handed the server, for whoever renders in it. */
    ServerLocale: ServerLocale;
    /**

package/src/langium/transfer/transfer-encoder.ts

@@ -80,6 +80,37 @@ export interface TransferEnvelopeSource<TDiagnostic> {
    readonly diagnostics: readonly (TDiagnostic | Diagnostic)[];
 }
 
+/**
+ * The AST→transfer contract a DI slot holds, implemented by
+ * {@link DefaultTransferEncoder}.
+ *
+ * **This is an interface and not the class, and that is load-bearing.** A class
+ * in a slot drags its `protected` members into every assignability check, which
+ * TypeScript compares NOMINALLY — so the slot type could not be satisfied by a
+ * subclass declared against a second physical copy of this package, and an
+ * adopter narrowing the slot had to intersect with the framework's declaration
+ * rather than replace it, leaving method resolution dependent on declaration
+ * order. An interface has no protected members and is compared structurally, so
+ * neither applies.
+ *
+ * **The transfer returns are the structural base ({@link TransferElement}), not
+ * the per-grammar overlay.** The overlay cannot parameterise this contract:
+ * `TransferTypeFor` reaches `keyof TTransferMap`, which makes that parameter
+ * measured-INVARIANT, and invariant parameters relate only when their arguments
+ * are mutually assignable — so a map-parameterised contract admits no adopter
+ * instantiation at all. Heads read this contract and do not know adopter maps;
+ * an adopter recovers the precise type by declaring its own slot, which it can
+ * now do by replacement.
+ */
+export interface TransferEncoder<TDiagnostic extends TransferDiagnostic = TransferDiagnostic> {
+   toTransfer<T extends AstNode>(ast: T, mode?: TransferMode): TransferElement;
+   toTransferDocument(langiumDocument: LangiumDocument): TransferDocument<TransferElement, TDiagnostic>;
+   astDocumentToTransferDocument<TAst extends AstNode>(
+      document: AstDocument<TAst, TDiagnostic | TransferLspDiagnostic>
+   ): TransferDocument<TransferElement, TDiagnostic>;
+   toTransferDiagnostic(diagnostic: TransferLspDiagnostic): TDiagnostic;
+}
+
 /**
  * One-directional structural mapper from a Langium AST into the wire
  * transfer-model shape ({@link TransferElement}-based JSON).
@@ -124,7 +155,7 @@ export interface TransferEnvelopeSource<TDiagnostic> {
  * - {@link toTransferDiagnostic} — project a {@link TransferLspDiagnostic}
  *   (the framework validator's output) to {@link TDiagnostic}.
  */
-export class TransferEncoder<
+export class DefaultTransferEncoder<
    // The map is intentionally unconstrained — adopters supply typed
    // overlays whose specific-key shapes don't structurally satisfy a
    // `Record<string, TransferElement>` index signature. `TransferTypeFor`

package/src/locale/server-locale.ts

@@ -14,6 +14,21 @@ import type { ServerSharedServicesMinimal } from '../langium/shared-services.js'
 /** Construction options for {@link ServerLocale}. */
 export type ServerLocaleOptions = LogNameOptions;
 
+/**
+ * The locale contract the `ServerLocale` slot holds, implemented by
+ * {@link DefaultServerLocale}.
+ *
+ * An interface rather than the class, so the slot is compared STRUCTURALLY —
+ * a class-typed slot carries its `protected` members into every assignability
+ * check, compared nominally, which makes it unsatisfiable across two physical
+ * copies of this package and unreplaceable by an adopter's own declaration.
+ */
+export interface ServerLocale {
+   /** The locale, or `undefined` when no init supplied one — the framework's English. */
+   readonly value: string | undefined;
+   accept(locale: string): void;
+}
+
 /**
  * The locale the server was handed at init, for whoever needs to render in the
  * reading user's language. Held apart from the message renderer that reads it,
@@ -23,7 +38,7 @@ export type ServerLocaleOptions = LogNameOptions;
  * read the current value wraps this itself — nothing does today, and both real
  * hosts respawn the server on a display-language switch.
  */
-export class ServerLocale {
+export class DefaultServerLocale implements ServerLocale {
    protected readonly tracer: Tracer;
    protected current: string | undefined;
 

package/src/lsp/hydranium-document-update-handler.ts

@@ -257,7 +257,7 @@ export class HydraniumDocumentUpdateHandler extends DefaultDocumentUpdateHandler
             }
             const uri = UriUtils.toUri(change.uri);
             const mtimeMs = await this.fileSystemProvider.mtimeMs?.(uri);
-            if (mtimeMs !== undefined && this.selfSaveRegistry.matches(uri.fsPath, mtimeMs)) {
+            if (mtimeMs !== undefined && this.selfSaveRegistry.isRegistered(uri.fsPath, mtimeMs)) {
                return undefined;
             }
             return change;

package/src/messages/renderer.ts

@@ -25,8 +25,28 @@ import type { ServerSharedServicesMinimal } from '../langium/shared-services.js'
 import type { ServerLocale } from '../locale/server-locale.js';
 import { resolvedFromDiagnostic } from './carriers.js';
 
-/** Construction options for {@link ServerMessageRenderer}. */
-export type ServerMessageRendererOptions = LogNameOptions;
+/** Construction options for {@link DefaultMessageRenderer}. */
+export type MessageRendererOptions = LogNameOptions;
+
+/**
+ * The render contract the `MessageRenderer` slot holds, implemented by
+ * {@link DefaultMessageRenderer}.
+ *
+ * An interface rather than the class, so the slot is compared STRUCTURALLY. A
+ * class-typed slot carries its `protected` members into every assignability
+ * check and TypeScript compares those nominally — which makes the slot
+ * unsatisfiable by a subclass declared against a second physical copy of this
+ * package, the state a pre-publish `yalc` / `file:` install produces. It also
+ * lets an adopter REPLACE this declaration rather than intersect with it, so
+ * slot resolution does not depend on the order a services type is written in.
+ *
+ * Every method carries a no-throw contract; see the implementation.
+ */
+export interface MessageRenderer {
+   renderDiagnostic(diagnostic: Diagnostic): string;
+   renderError(error: ResponseError<unknown>): string;
+   renderMessage<S extends string>(message: MessageDefinition<S>, ...params: ParamsArg<S>): string;
+}
 
 /**
  * Renders every user-facing message the server sends, in the locale the server
@@ -41,7 +61,7 @@ export type ServerMessageRendererOptions = LogNameOptions;
  * single `render(text)` would force an adopter to match English prose, which
  * breaks on the first Langium reword.
  */
-export class ServerMessageRenderer {
+export class DefaultMessageRenderer implements MessageRenderer {
    protected readonly tracer: Tracer;
    protected readonly serverLocale: ServerLocale;
    /**
@@ -58,7 +78,7 @@ export class ServerMessageRenderer {
     */
    protected readonly catalogues = new SimpleCache<string | undefined, Record<string, string> | undefined>();
 
-   constructor(services: ServerSharedServicesMinimal, options: ServerMessageRendererOptions = {}) {
+   constructor(services: ServerSharedServicesMinimal, options: MessageRendererOptions = {}) {
       this.serverLocale = services.ServerLocale;
       this.tracer = services.Tracer.for(options.logName ?? 'MessageRenderer').trace('instantiated');
    }

package/src/testing/make-noop-shared-services.ts

@@ -9,8 +9,8 @@
 
 import { type Clock, DefaultTracer, type Logger, NoopLogger, SystemClock, type Tracer } from '@hydranium/protocol';
 import type { ServerSharedServicesMinimal } from '../langium/shared-services.js';
-import { ServerLocale } from '../locale/server-locale.js';
-import { ServerMessageRenderer } from '../messages/renderer.js';
+import { DefaultServerLocale, type ServerLocale } from '../locale/server-locale.js';
+import { DefaultMessageRenderer, type MessageRenderer } from '../messages/renderer.js';
 
 /**
  * Overrides for {@link makeNoopSharedServices}. The three observability slots
@@ -35,14 +35,14 @@ export interface NoopSharedServicesOverrides {
    ServerLocale?: (services: ServerSharedServicesMinimal) => ServerLocale;
    /**
     * Factory for the `MessageRenderer` slot. Default: the real
-    * {@link ServerMessageRenderer}, whose no-catalogue behaviour is a
+    * {@link DefaultMessageRenderer}, whose no-catalogue behaviour is a
     * pass-through — so the default is the framework's own behaviour, not a stub.
     *
     * A factory rather than an instance, because a renderer reads the tree it is
     * bound into. Both slots are resolved lazily, so an override is honoured
     * however late the caller reads them.
     */
-   MessageRenderer?: (services: ServerSharedServicesMinimal) => ServerMessageRenderer;
+   MessageRenderer?: (services: ServerSharedServicesMinimal) => MessageRenderer;
    /** Per-slot `workspace` overrides. Slots left out resolve to `undefined`. */
    workspace?: Record<string, unknown>;
    /** Any other minimal slot (`ServiceRegistry`, `AstReflection`, `additionalDocuments`, …). */
@@ -103,8 +103,8 @@ export function makeNoopSharedServices<T extends ServerSharedServicesMinimal = S
    // both services emit an `instantiated` trace, so building them eagerly puts
    // two lines into the capture of every test that passes a capturing logger
    // and asserts on emptiness.
-   defineLazySlot(services, 'ServerLocale', () => serverLocale?.(services) ?? new ServerLocale(services));
-   defineLazySlot(services, 'MessageRenderer', () => messageRenderer?.(services) ?? new ServerMessageRenderer(services));
+   defineLazySlot(services, 'ServerLocale', () => serverLocale?.(services) ?? new DefaultServerLocale(services));
+   defineLazySlot(services, 'MessageRenderer', () => messageRenderer?.(services) ?? new DefaultMessageRenderer(services));
    return services;
 }