@hydranium/core 1.0.0-next.10

package/lib/langium/update-rewrite/index.js

@@ -0,0 +1,14 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+export * from './normalize-empty-strings.js';
+export * from './semantic-root-rewrite.js';
+export * from './update-rewrite.js';
+export * from './update-rewrite-contribution.js';
+export * from './update-rewrite-service.js';
+//# sourceMappingURL=index.js.map

package/lib/langium/update-rewrite/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/langium/update-rewrite/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,cAAc,8BAA8B,CAAC;AAC7C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,qBAAqB,CAAC;AACpC,cAAc,kCAAkC,CAAC;AACjD,cAAc,6BAA6B,CAAC"}

package/lib/langium/update-rewrite/normalize-empty-strings.d.ts

@@ -0,0 +1,52 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import { type UpdateRewriteContribution, type UpdateRewriteRegistry } from './update-rewrite-contribution.js';
+/**
+ * Ready-made {@link UpdateRewriteContribution} that registers one rewrite —
+ * the `'' → unset` normalisation — and exposes the transform itself as the
+ * overridable {@link normalize} hook.
+ *
+ * **Why this exists.** An HTML form control that the user clears emits `''`,
+ * never `undefined` / absent — but a structured diff treats `''` and absent as
+ * different. Without normalisation, the same "clear the field" gesture produces
+ * two different persisted outcomes depending on the field's grammar default (a
+ * literal `field: ''` local override vs re-inheriting). Collapsing `'' → unset`
+ * makes "clear" uniformly mean "remove my local value", the only intent the
+ * form can express.
+ *
+ * **Opt-in.** The framework never binds this by default: dropping `''` encodes a
+ * grammar-specific "`''` is never meaningful" assumption, so it would silently
+ * lose data for a grammar where `''` is meaningful. Bind it under a named
+ * sub-key of your module's `updateRewrite.rewrites` group when your form
+ * transport emits `''`.
+ *
+ * **Adapt** by subclassing and overriding {@link normalize} — e.g. to preserve
+ * grammar-meaningful empties for specific keys — without touching the
+ * registration glue.
+ */
+export declare class NormalizeEmptyStringsContribution implements UpdateRewriteContribution {
+    registerUpdateRewrites(registry: UpdateRewriteRegistry): void;
+    /**
+     * Collapse empty-string properties to "unset" (drop the key) throughout the
+     * transfer-model graph. Override to adapt the rule (the override applies at
+     * every depth, since the walk recurses through this method).
+     *
+     * Scope of the walk:
+     *  - Recurses object properties and into object elements of arrays.
+     *  - Leaves **primitive array elements** untouched — e.g. reference-id
+     *    strings must not have an accidental `''` turned into a hole in the array.
+     *  - Leaves `$`-prefixed (Langium internals like `$type`) and `_`-prefixed
+     *    (derived metadata) keys verbatim — downstream rewrites read them.
+     *  - Leaves Langium `Reference` objects (`{ $refText }`) verbatim.
+     *
+     * Pure — returns a new object graph, does not mutate its input.
+     */
+    protected normalize<T>(value: T): T;
+}
+//# sourceMappingURL=normalize-empty-strings.d.ts.map

package/lib/langium/update-rewrite/normalize-empty-strings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-empty-strings.d.ts","sourceRoot":"","sources":["../../../src/langium/update-rewrite/normalize-empty-strings.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,yBAAyB,EAAE,KAAK,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AAE9G;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,iCAAkC,YAAW,yBAAyB;IAChF,sBAAsB,CAAC,QAAQ,EAAE,qBAAqB,GAAG,IAAI;IAU7D;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC;CAyBrC"}

package/lib/langium/update-rewrite/normalize-empty-strings.js

@@ -0,0 +1,83 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * Ready-made {@link UpdateRewriteContribution} that registers one rewrite —
+ * the `'' → unset` normalisation — and exposes the transform itself as the
+ * overridable {@link normalize} hook.
+ *
+ * **Why this exists.** An HTML form control that the user clears emits `''`,
+ * never `undefined` / absent — but a structured diff treats `''` and absent as
+ * different. Without normalisation, the same "clear the field" gesture produces
+ * two different persisted outcomes depending on the field's grammar default (a
+ * literal `field: ''` local override vs re-inheriting). Collapsing `'' → unset`
+ * makes "clear" uniformly mean "remove my local value", the only intent the
+ * form can express.
+ *
+ * **Opt-in.** The framework never binds this by default: dropping `''` encodes a
+ * grammar-specific "`''` is never meaningful" assumption, so it would silently
+ * lose data for a grammar where `''` is meaningful. Bind it under a named
+ * sub-key of your module's `updateRewrite.rewrites` group when your form
+ * transport emits `''`.
+ *
+ * **Adapt** by subclassing and overriding {@link normalize} — e.g. to preserve
+ * grammar-meaningful empties for specific keys — without touching the
+ * registration glue.
+ */
+export class NormalizeEmptyStringsContribution {
+    registerUpdateRewrites(registry) {
+        registry.register({
+            id: 'normalize-empty-strings',
+            // Low priority so it runs before any diff-based rewrite — a
+            // reconciliation pass should see cleared fields already read as unset.
+            priority: -100,
+            rewrite: model => this.normalize(model)
+        });
+    }
+    /**
+     * Collapse empty-string properties to "unset" (drop the key) throughout the
+     * transfer-model graph. Override to adapt the rule (the override applies at
+     * every depth, since the walk recurses through this method).
+     *
+     * Scope of the walk:
+     *  - Recurses object properties and into object elements of arrays.
+     *  - Leaves **primitive array elements** untouched — e.g. reference-id
+     *    strings must not have an accidental `''` turned into a hole in the array.
+     *  - Leaves `$`-prefixed (Langium internals like `$type`) and `_`-prefixed
+     *    (derived metadata) keys verbatim — downstream rewrites read them.
+     *  - Leaves Langium `Reference` objects (`{ $refText }`) verbatim.
+     *
+     * Pure — returns a new object graph, does not mutate its input.
+     */
+    normalize(value) {
+        if (value === null || typeof value !== 'object') {
+            return value;
+        }
+        if (Array.isArray(value)) {
+            // Recurse into object elements only; primitive elements (reference strings) pass through.
+            return value.map(item => (item !== null && typeof item === 'object' ? this.normalize(item) : item));
+        }
+        const record = value;
+        if ('$refText' in record) {
+            return value;
+        }
+        const result = {};
+        for (const [key, entry] of Object.entries(record)) {
+            if (key.startsWith('$') || key.startsWith('_')) {
+                result[key] = entry;
+                continue;
+            }
+            if (entry === '') {
+                continue; // empty-string property → treat as unset (drop the key, equivalent to absent)
+            }
+            result[key] = this.normalize(entry);
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=normalize-empty-strings.js.map

package/lib/langium/update-rewrite/normalize-empty-strings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-empty-strings.js","sourceRoot":"","sources":["../../../src/langium/update-rewrite/normalize-empty-strings.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAIlF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,iCAAiC;IAC3C,sBAAsB,CAAC,QAA+B;QACnD,QAAQ,CAAC,QAAQ,CAAC;YACf,EAAE,EAAE,yBAAyB;YAC7B,4DAA4D;YAC5D,uEAAuE;YACvE,QAAQ,EAAE,CAAC,GAAG;YACd,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;SACzC,CAAC,CAAC;IACN,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACO,SAAS,CAAI,KAAQ;QAC5B,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC/C,OAAO,KAAK,CAAC;QAChB,CAAC;QACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACxB,0FAA0F;YAC1F,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAiB,CAAC;QACvH,CAAC;QACD,MAAM,MAAM,GAAG,KAAgC,CAAC;QAChD,IAAI,UAAU,IAAI,MAAM,EAAE,CAAC;YACxB,OAAO,KAAK,CAAC;QAChB,CAAC;QACD,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YACjD,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC9C,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;gBACpB,SAAS;YACZ,CAAC;YACD,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;gBAChB,SAAS,CAAC,8EAA8E;YAC3F,CAAC;YACD,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACvC,CAAC;QACD,OAAO,MAAW,CAAC;IACtB,CAAC;CACH"}

package/lib/langium/update-rewrite/semantic-root-rewrite.d.ts

@@ -0,0 +1,37 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import { type TransferElement } from '@hydranium/protocol';
+/**
+ * Applies `rewrite` to the ONE populated semantic slot of a wrapper-shaped
+ * transfer root, reassembling the wrapper around the result.
+ *
+ * The transfer-side counterpart to `NameBasedKeyProvider.isSemanticRoot`'s
+ * "wrapper grammars with an unnamed root node" case: the document root is a
+ * discriminating wrapper carrying one populated slot per semantic type
+ * (`{ entity }` or `{ mapping }` or `{ diagram }`, never two), and an
+ * `UpdateRewrite` is handed that wrapper while the fields it cares about
+ * live one level down.
+ *
+ * `semanticKeys` is supplied rather than inferred: which slots a wrapper may
+ * carry is grammar knowledge, and sniffing "the single object-valued property"
+ * would silently pick up any object-valued metadata a root grows later.
+ *
+ * **Identity is the no-op signal, and it is load-bearing.** When no slot is
+ * populated, or `rewrite` hands back the same reference it was given, the
+ * ARGUMENT is returned — not a copy. An `UpdateRewrite` chain folds every
+ * rewrite over the model, so a rewrite that does not apply must be free; a
+ * defensive copy here would make every unrelated write allocate a fresh root per
+ * registered rewrite. Callers that compare with `===` to detect "nothing
+ * happened" depend on this too.
+ *
+ * Rewrites of an unwrapped grammar — where the named root element IS the
+ * semantic root — do not need this helper: their model is already the node.
+ */
+export declare function rewriteSemanticRoot<TTransfer extends TransferElement>(model: TTransfer, semanticKeys: readonly string[], rewrite: (semanticRoot: Record<string, unknown>, key: string) => Record<string, unknown>): TTransfer;
+//# sourceMappingURL=semantic-root-rewrite.d.ts.map

package/lib/langium/update-rewrite/semantic-root-rewrite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-root-rewrite.d.ts","sourceRoot":"","sources":["../../../src/langium/update-rewrite/semantic-root-rewrite.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,SAAS,eAAe,EAClE,KAAK,EAAE,SAAS,EAChB,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,OAAO,EAAE,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACxF,SAAS,CAeX"}

package/lib/langium/update-rewrite/semantic-root-rewrite.js

@@ -0,0 +1,51 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * Applies `rewrite` to the ONE populated semantic slot of a wrapper-shaped
+ * transfer root, reassembling the wrapper around the result.
+ *
+ * The transfer-side counterpart to `NameBasedKeyProvider.isSemanticRoot`'s
+ * "wrapper grammars with an unnamed root node" case: the document root is a
+ * discriminating wrapper carrying one populated slot per semantic type
+ * (`{ entity }` or `{ mapping }` or `{ diagram }`, never two), and an
+ * `UpdateRewrite` is handed that wrapper while the fields it cares about
+ * live one level down.
+ *
+ * `semanticKeys` is supplied rather than inferred: which slots a wrapper may
+ * carry is grammar knowledge, and sniffing "the single object-valued property"
+ * would silently pick up any object-valued metadata a root grows later.
+ *
+ * **Identity is the no-op signal, and it is load-bearing.** When no slot is
+ * populated, or `rewrite` hands back the same reference it was given, the
+ * ARGUMENT is returned — not a copy. An `UpdateRewrite` chain folds every
+ * rewrite over the model, so a rewrite that does not apply must be free; a
+ * defensive copy here would make every unrelated write allocate a fresh root per
+ * registered rewrite. Callers that compare with `===` to detect "nothing
+ * happened" depend on this too.
+ *
+ * Rewrites of an unwrapped grammar — where the named root element IS the
+ * semantic root — do not need this helper: their model is already the node.
+ */
+export function rewriteSemanticRoot(model, semanticKeys, rewrite) {
+    const record = model;
+    const semanticKey = semanticKeys.find(key => record[key]);
+    if (!semanticKey) {
+        return model;
+    }
+    const semanticRoot = record[semanticKey];
+    if (!semanticRoot) {
+        return model;
+    }
+    const rewritten = rewrite(semanticRoot, semanticKey);
+    if (rewritten === semanticRoot) {
+        return model;
+    }
+    return { ...record, [semanticKey]: rewritten };
+}
+//# sourceMappingURL=semantic-root-rewrite.js.map

package/lib/langium/update-rewrite/semantic-root-rewrite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-root-rewrite.js","sourceRoot":"","sources":["../../../src/langium/update-rewrite/semantic-root-rewrite.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAIlF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,mBAAmB,CAChC,KAAgB,EAChB,YAA+B,EAC/B,OAAwF;IAExF,MAAM,MAAM,GAAG,KAA2C,CAAC;IAC3D,MAAM,WAAW,GAAG,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,IAAI,CAAC,WAAW,EAAE,CAAC;QAChB,OAAO,KAAK,CAAC;IAChB,CAAC;IACD,MAAM,YAAY,GAAG,MAAM,CAAC,WAAW,CAAwC,CAAC;IAChF,IAAI,CAAC,YAAY,EAAE,CAAC;QACjB,OAAO,KAAK,CAAC;IAChB,CAAC;IACD,MAAM,SAAS,GAAG,OAAO,CAAC,YAAY,EAAE,WAAW,CAAC,CAAC;IACrD,IAAI,SAAS,KAAK,YAAY,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC;IAChB,CAAC;IACD,OAAO,EAAE,GAAG,MAAM,EAAE,CAAC,WAAW,CAAC,EAAE,SAAS,EAA0B,CAAC;AAC1E,CAAC"}

package/lib/langium/update-rewrite/update-rewrite-contribution.d.ts

@@ -0,0 +1,42 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import { type Disposable } from 'vscode-languageserver';
+import { type AstNode } from '@hydranium/langium';
+import { type TransferElement } from '@hydranium/protocol';
+import { type UpdateRewrite } from './update-rewrite.js';
+/**
+ * Registry handed to an {@link UpdateRewriteContribution}. Implemented by the
+ * update-rewrite service; a contribution receives it and registers one or many
+ * rewrites. Doubles as the low-level imperative API for the rare
+ * runtime-dynamic registration case.
+ *
+ * Generic over `<TTransfer, TAst>` for the same reason {@link UpdateRewrite} and
+ * `UpdateRewriteService` are: an adopter that narrows to its own root types gets
+ * a `rewrite` callback whose `model` and `previous` are already its types, so a
+ * registration needs no cast at all. Both default to the structural bases, so
+ * every existing call site keeps compiling unchanged.
+ */
+export interface UpdateRewriteRegistry<TTransfer extends TransferElement = TransferElement, TAst extends AstNode = AstNode> {
+    register(rewrite: UpdateRewrite<TTransfer, TAst>): Disposable;
+}
+/**
+ * Declarative registration of update rewrites. Bound under the module's
+ * `updateRewrite.rewrites` contribution group (a
+ * `Record<string, UpdateRewriteContribution>`); the update-rewrite service
+ * reads its own group at construction and calls this method, handing itself in
+ * as the registry.
+ *
+ * The domain-qualified method name lets a single cross-cutting class implement
+ * several contribution interfaces (e.g. also `IntegrityRuleContribution`)
+ * without method collision — bind it once and reference it from each group.
+ */
+export interface UpdateRewriteContribution<TTransfer extends TransferElement = TransferElement, TAst extends AstNode = AstNode> {
+    registerUpdateRewrites(registry: UpdateRewriteRegistry<TTransfer, TAst>): void;
+}
+//# sourceMappingURL=update-rewrite-contribution.d.ts.map

package/lib/langium/update-rewrite/update-rewrite-contribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-rewrite-contribution.d.ts","sourceRoot":"","sources":["../../../src/langium/update-rewrite/update-rewrite-contribution.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,qBAAqB,CAAC,SAAS,SAAS,eAAe,GAAG,eAAe,EAAE,IAAI,SAAS,OAAO,GAAG,OAAO;IACvH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,SAAS,EAAE,IAAI,CAAC,GAAG,UAAU,CAAC;CAChE;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,yBAAyB,CAAC,SAAS,SAAS,eAAe,GAAG,eAAe,EAAE,IAAI,SAAS,OAAO,GAAG,OAAO;IAC3H,sBAAsB,CAAC,QAAQ,EAAE,qBAAqB,CAAC,SAAS,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC;CACjF"}

package/lib/langium/update-rewrite/update-rewrite-contribution.js

@@ -0,0 +1,10 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+export {};
+//# sourceMappingURL=update-rewrite-contribution.js.map

package/lib/langium/update-rewrite/update-rewrite-contribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-rewrite-contribution.js","sourceRoot":"","sources":["../../../src/langium/update-rewrite/update-rewrite-contribution.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF"}

package/lib/langium/update-rewrite/update-rewrite-service.d.ts

@@ -0,0 +1,89 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import { type TransferElement, type Tracer } from '@hydranium/protocol';
+import { type AstNode } from '@hydranium/langium';
+import { type CancellationToken, type Disposable } from 'vscode-languageserver';
+import { type LogNameOptions } from '../diagnostics/logger.js';
+import { type ServerLanguageServices } from '../language-module.js';
+import { Registry } from '../../util/registry.js';
+import { type UpdateRewriteRegistry } from './update-rewrite-contribution.js';
+import { type UpdateRewrite } from './update-rewrite.js';
+/**
+ * Public contract for the per-language update-rewrite runner. Extends the
+ * {@link UpdateRewriteRegistry} (the imperative `register` surface
+ * contributions use) with the {@link apply} entry point
+ * `ModelService.rewriteModel` calls on the structured write path, before
+ * serialisation.
+ *
+ * Adopter overrides go through {@link DefaultUpdateRewriteService}; the
+ * interface keeps the public API stable while internals (the registry) stay
+ * `protected` on the default class.
+ *
+ * Generic over `<TTransfer, TAst>` so each consumer plugs in their own transfer
+ * and AST root types; both default to the structural bases.
+ */
+export interface UpdateRewriteService<TTransfer extends TransferElement = TransferElement, TAst extends AstNode = AstNode> extends UpdateRewriteRegistry<TTransfer, TAst> {
+    /** Remove a rewrite by id. Returns `true` if a rewrite was removed. */
+    unregister(id: string): boolean;
+    /**
+     * Run every registered rewrite in priority order, threading the model
+     * through each, and return the rewritten transfer model. Always async (the
+     * method is called once per `update`, not per node), but a synchronous
+     * rewrite never adds a microtask — see {@link DefaultUpdateRewriteService.apply}.
+     *
+     * `cancelToken` is honoured between rewrites — material when a rewrite is
+     * async (an external lookup); a preempted update aborts the chain before the
+     * next rewrite rather than running it to completion against a doomed build.
+     */
+    apply(model: TTransfer, previous: TAst | undefined, cancelToken?: CancellationToken): Promise<TTransfer>;
+}
+/**
+ * Construction options for {@link DefaultUpdateRewriteService}. All fields
+ * optional — the defaults reproduce the framework's behaviour exactly.
+ */
+export type UpdateRewriteServiceOptions = LogNameOptions;
+/**
+ * Default {@link UpdateRewriteService} implementation. A pure ordered registry
+ * of transfer-model transforms; the framework ships **zero** members (an empty
+ * chain is a no-op). Adopters declare rewrites via
+ * `UpdateRewriteContribution`s under the `updateRewrite.rewrites` group,
+ * or register imperatively.
+ *
+ * **Per-language service.** Bound in the per-language module and resolved by
+ * `ModelService` via `ServiceRegistry.getServices(uri)`, so multi-grammar
+ * workspaces route each write to the right rewrite set.
+ *
+ * The framework provides no comparison helper and no previous-state accessor —
+ * a diff-based rewrite owns its own representation reconciliation (see
+ * {@link UpdateRewrite}).
+ */
+export declare class DefaultUpdateRewriteService<TTransfer extends TransferElement = TransferElement, TAst extends AstNode = AstNode> implements UpdateRewriteService<TTransfer, TAst> {
+    protected readonly services: ServerLanguageServices;
+    /** Registry of rewrites, keyed by id, iterated in priority order. */
+    protected readonly rewrites: Registry<UpdateRewrite<TTransfer, TAst>>;
+    protected readonly tracer: Tracer;
+    constructor(services: ServerLanguageServices, options?: UpdateRewriteServiceOptions);
+    register(rewrite: UpdateRewrite<TTransfer, TAst>): Disposable;
+    unregister(id: string): boolean;
+    /**
+     * Fold the model through every rewrite in priority order. Mirrors the
+     * `DefaultIntegrityService.enforceIntegrity` pattern: the method is
+     * `async` (one tick per `update`, which is a per-operation call, not a
+     * per-node hot loop), and the per-rewrite {@link isPromiseLike} check skips
+     * the `await` for synchronous rewrites — the common case — so a sync chain
+     * adds no extra microtask beyond the single tick `async` already costs.
+     *
+     * `cancelToken` is checked before each rewrite (coarser than within a
+     * rewrite, finer than per-chain) so a preempted async chain interrupts
+     * cleanly — `interruptAndCheck` throws `OperationCancelled`, which aborts the
+     * `update` before any text is applied.
+     */
+    apply(model: TTransfer, previous: TAst | undefined, cancelToken?: CancellationToken): Promise<TTransfer>;
+}
+//# sourceMappingURL=update-rewrite-service.d.ts.map

package/lib/langium/update-rewrite/update-rewrite-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-rewrite-service.d.ts","sourceRoot":"","sources":["../../../src/langium/update-rewrite/update-rewrite-service.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAiB,KAAK,eAAe,EAAE,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AACvF,OAAO,EAAE,KAAK,OAAO,EAAqB,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAChF,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,KAAK,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,KAAK,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AAC9E,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,oBAAoB,CAClC,SAAS,SAAS,eAAe,GAAG,eAAe,EACnD,IAAI,SAAS,OAAO,GAAG,OAAO,CAC/B,SAAQ,qBAAqB,CAAC,SAAS,EAAE,IAAI,CAAC;IAC7C,uEAAuE;IACvE,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAChC;;;;;;;;;OASG;IACH,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,GAAG,SAAS,EAAE,WAAW,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CAC3G;AAED;;;GAGG;AACH,MAAM,MAAM,2BAA2B,GAAG,cAAc,CAAC;AAEzD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,2BAA2B,CACrC,SAAS,SAAS,eAAe,GAAG,eAAe,EACnD,IAAI,SAAS,OAAO,GAAG,OAAO,CAC/B,YAAW,oBAAoB,CAAC,SAAS,EAAE,IAAI,CAAC;IAM5C,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,sBAAsB;IALtD,qEAAqE;IACrE,SAAS,CAAC,QAAQ,CAAC,QAAQ,2CAAkD;IAC7E,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAGZ,QAAQ,EAAE,sBAAsB,EACnD,OAAO,GAAE,2BAAgC;IAc5C,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,SAAS,EAAE,IAAI,CAAC,GAAG,UAAU;IAI7D,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAI/B;;;;;;;;;;;;OAYG;IACG,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,GAAG,SAAS,EAAE,WAAW,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,CAAC;CAWhH"}

package/lib/langium/update-rewrite/update-rewrite-service.js

@@ -0,0 +1,75 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import { isPromiseLike } from '@hydranium/protocol';
+import { interruptAndCheck } from '@hydranium/langium';
+import { Registry } from '../../util/registry.js';
+/**
+ * Default {@link UpdateRewriteService} implementation. A pure ordered registry
+ * of transfer-model transforms; the framework ships **zero** members (an empty
+ * chain is a no-op). Adopters declare rewrites via
+ * `UpdateRewriteContribution`s under the `updateRewrite.rewrites` group,
+ * or register imperatively.
+ *
+ * **Per-language service.** Bound in the per-language module and resolved by
+ * `ModelService` via `ServiceRegistry.getServices(uri)`, so multi-grammar
+ * workspaces route each write to the right rewrite set.
+ *
+ * The framework provides no comparison helper and no previous-state accessor —
+ * a diff-based rewrite owns its own representation reconciliation (see
+ * {@link UpdateRewrite}).
+ */
+export class DefaultUpdateRewriteService {
+    services;
+    /** Registry of rewrites, keyed by id, iterated in priority order. */
+    rewrites = new Registry();
+    tracer;
+    constructor(services, options = {}) {
+        this.services = services;
+        this.tracer = services.shared.Tracer.for(options.logName ?? 'UpdateRewrite').trace('instantiated');
+        // Read the language's UpdateRewriteContribution group and let each
+        // contribution register one or many rewrites through this service.
+        // Optional chaining tolerates incomplete test stubs; production wiring
+        // always provides the slot via `createServerLanguageModule`.
+        const contributions = services.updateRewrite?.rewrites ?? {};
+        for (const contribution of Object.values(contributions)) {
+            contribution.registerUpdateRewrites(this);
+        }
+    }
+    register(rewrite) {
+        return this.rewrites.register(rewrite);
+    }
+    unregister(id) {
+        return this.rewrites.unregister(id);
+    }
+    /**
+     * Fold the model through every rewrite in priority order. Mirrors the
+     * `DefaultIntegrityService.enforceIntegrity` pattern: the method is
+     * `async` (one tick per `update`, which is a per-operation call, not a
+     * per-node hot loop), and the per-rewrite {@link isPromiseLike} check skips
+     * the `await` for synchronous rewrites — the common case — so a sync chain
+     * adds no extra microtask beyond the single tick `async` already costs.
+     *
+     * `cancelToken` is checked before each rewrite (coarser than within a
+     * rewrite, finer than per-chain) so a preempted async chain interrupts
+     * cleanly — `interruptAndCheck` throws `OperationCancelled`, which aborts the
+     * `update` before any text is applied.
+     */
+    async apply(model, previous, cancelToken) {
+        let current = model;
+        for (const rewrite of this.rewrites.all()) {
+            if (cancelToken !== undefined) {
+                await interruptAndCheck(cancelToken);
+            }
+            const result = rewrite.rewrite(current, previous);
+            current = (isPromiseLike(result) ? await result : result);
+        }
+        return current;
+    }
+}
+//# sourceMappingURL=update-rewrite-service.js.map

package/lib/langium/update-rewrite/update-rewrite-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-rewrite-service.js","sourceRoot":"","sources":["../../../src/langium/update-rewrite/update-rewrite-service.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,aAAa,EAAqC,MAAM,qBAAqB,CAAC;AACvF,OAAO,EAAgB,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAIrE,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AA2ClD;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,2BAA2B;IASf;IALtB,qEAAqE;IAClD,QAAQ,GAAG,IAAI,QAAQ,EAAkC,CAAC;IAC1D,MAAM,CAAS;IAElC,YACsB,QAAgC,EACnD,UAAuC,EAAE;QADtB,aAAQ,GAAR,QAAQ,CAAwB;QAGnD,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,eAAe,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QAEnG,mEAAmE;QACnE,mEAAmE;QACnE,uEAAuE;QACvE,6DAA6D;QAC7D,MAAM,aAAa,GAAG,QAAQ,CAAC,aAAa,EAAE,QAAQ,IAAI,EAAE,CAAC;QAC7D,KAAK,MAAM,YAAY,IAAI,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;YACvD,YAAY,CAAC,sBAAsB,CAAC,IAAI,CAAC,CAAC;QAC7C,CAAC;IACJ,CAAC;IAED,QAAQ,CAAC,OAAuC;QAC7C,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC1C,CAAC;IAED,UAAU,CAAC,EAAU;QAClB,OAAO,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IACvC,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,KAAK,CAAC,KAAgB,EAAE,QAA0B,EAAE,WAA+B;QACtF,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC;YACzC,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;gBAC7B,MAAM,iBAAiB,CAAC,WAAW,CAAC,CAAC;YACxC,CAAC;YACD,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;YAClD,OAAO,GAAG,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,CAAC,CAAC,MAAM,CAAc,CAAC;QAC1E,CAAC;QACD,OAAO,OAAO,CAAC;IAClB,CAAC;CACH"}

package/lib/langium/update-rewrite/update-rewrite.d.ts

@@ -0,0 +1,59 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import { type MaybePromise, type TransferElement } from '@hydranium/protocol';
+import { type AstNode } from '@hydranium/langium';
+import { type RegistryItem } from '../../util/registry.js';
+/**
+ * A single transform applied to the incoming transfer model on the structured
+ * (object) write path of `ModelService.update` / `ModelService.save`, before
+ * serialisation. The RPC-update-stage sibling of `IntegrityRule` /
+ * `AstExtension` / `ValidationCheck` — same id-keyed,
+ * priority-ordered registry shape, but it runs on the transfer model rather
+ * than the built AST, and only on structured writes (never the LSP text path).
+ *
+ * **Two representations.** The contract is deliberately asymmetric — `model`
+ * and `previous` are NOT the same shape, and the types say so:
+ *
+ * - `model` (and the return) is a **transfer model**: cross-references are
+ *   flattened to `$refText` strings, derived `_*` properties are folded in as
+ *   *enumerable* fields, and there are no `$container` back-pointers. It is the
+ *   plain JSON that arrived over RPC from the form / diagram.
+ * - `previous` is a live **AST root** (`document.parseResult.value`): real
+ *   `Reference` objects, `$container`, and `_*` attached *non-enumerably* by the
+ *   AST-extension service. It is `undefined` for a not-yet-built document.
+ *
+ * A rewrite that needs to diff against the previous state owns the
+ * representation reconciliation itself (text-vs-`Reference`, enumerable-vs-not).
+ * The framework provides no comparison helper — comparison is grammar-specific
+ * policy.
+ *
+ * **Ordering** is by {@link RegistryItem.priority} ascending, ties broken by
+ * registration order — so a normalisation pass (low priority) reliably runs
+ * before a diff-based reconciliation (higher priority).
+ *
+ * **Sync fast path.** `rewrite` may return a promise (mirrors
+ * `IntegrityRule.enforce`) so an adopter rewrite that consults an external
+ * system isn't forced sync; the service keeps purely-sync rewrites — the common
+ * case — off the microtask queue.
+ *
+ * Generic over `<TTransfer, TAst>` so each adopter narrows to its own transfer
+ * and AST root types; both default to the structural bases.
+ */
+export interface UpdateRewrite<TTransfer extends TransferElement = TransferElement, TAst extends AstNode = AstNode> extends RegistryItem {
+    /**
+     * Rewrite the incoming transfer model. Return the input unchanged when the
+     * rewrite does not apply (the common no-op case).
+     *
+     * `previous` is the AST as it stood before this update — read-only; never
+     * mutate it. It is `undefined` for a brand-new document, which a diff-based
+     * rewrite should treat as "every field is new" (the maximal change case).
+     */
+    rewrite(model: TTransfer, previous: TAst | undefined): MaybePromise<TTransfer>;
+}
+//# sourceMappingURL=update-rewrite.d.ts.map

package/lib/langium/update-rewrite/update-rewrite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-rewrite.d.ts","sourceRoot":"","sources":["../../../src/langium/update-rewrite/update-rewrite.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,WAAW,aAAa,CAAC,SAAS,SAAS,eAAe,GAAG,eAAe,EAAE,IAAI,SAAS,OAAO,GAAG,OAAO,CAAE,SAAQ,YAAY;IACrI;;;;;;;OAOG;IACH,OAAO,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,GAAG,SAAS,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;CACjF"}

package/lib/langium/update-rewrite/update-rewrite.js

@@ -0,0 +1,10 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+export {};
+//# sourceMappingURL=update-rewrite.js.map

package/lib/langium/update-rewrite/update-rewrite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-rewrite.js","sourceRoot":"","sources":["../../../src/langium/update-rewrite/update-rewrite.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF"}