@hydranium/protocol 1.0.0-next.10

package/lib/model-service/index.js

@@ -0,0 +1,31 @@
+"use strict";
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Subpath barrel for the in-process `ModelService` facade contract. The
+// implementation lives in `@hydranium/core`; this package owns the
+// argument types so both the framework facade and the data-server wire
+// protocol can structurally agree on the lifecycle shape.
+__exportStar(require("./args"), exports);
+__exportStar(require("./reference-candidate"), exports);
+//# sourceMappingURL=index.js.map

package/lib/model-service/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/model-service/index.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;;;;;;;;;;;;;;AAElF,wEAAwE;AACxE,mEAAmE;AACnE,uEAAuE;AACvE,0DAA0D;AAE1D,yCAAuB;AACvB,wDAAsC"}

package/lib/model-service/reference-candidate.d.ts

@@ -0,0 +1,56 @@
+/********************************************************************************
+ * 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 '../transfer-element';
+/**
+ * UI-facing descriptor of an AST element that may be assigned as the value
+ * of a reference. Carries the URI of the owning document, the AST type, the
+ * display label, and the persisted reference value.
+ *
+ * Produced by the reference-candidate pipeline in `@hydranium/core`
+ * (`ReferenceCandidateProvider.find`). Consumed by UI surfaces —
+ * command-palettes, drop-target action providers, completion popups — that
+ * present ranked, deduped reference candidates to the user.
+ *
+ * **Why two label fields**: `label` is what the user sees in the dropdown;
+ * `value` is what gets persisted as the reference's `$refText` when the
+ * user selects this element. Separating them lets the server present a
+ * human-readable display name (e.g. `node.name`) while storing the
+ * canonical reference identifier (e.g. `node.id`). Both fields are
+ * required — producers without a display/value distinction set the same
+ * string in both, so consumers never need to remember a fallback rule.
+ */
+export interface ReferenceCandidate {
+    /** URI of the document declaring the referenced element. */
+    uri: string;
+    /** AST `$type` of the referenced element — useful for icon dispatch. */
+    type: string;
+    /** Display label shown to the user in dropdowns and chips. */
+    label: string;
+    /** String stored as `$refText` when the user selects this element. */
+    value: string;
+}
+/**
+ * Result of resolving a `ReferenceRequest` to its target — a
+ * {@link ReferenceCandidate} plus the resolved node's transfer subtree.
+ *
+ * A candidate and a target are the same kind of thing (an addressable
+ * reference target): `find` lists candidates, `resolveReference` returns the
+ * one a value matched. The target additionally carries `element` because it
+ * is a single result that can afford the payload, where candidates come as a
+ * list and stay lightweight. The encoded `element` is just the resolved
+ * node's subtree, NOT the whole document root — callers that want the full
+ * document fetch it via `getModelDocument(uri)`.
+ *
+ * Generic over the transfer root type so adopters get their typed overlay.
+ */
+export interface ReferenceTarget<TTransfer extends TransferElement = TransferElement> extends ReferenceCandidate {
+    /** The resolved target node, encoded as a transfer subtree. */
+    element: TTransfer;
+}
+//# sourceMappingURL=reference-candidate.d.ts.map

package/lib/model-service/reference-candidate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-candidate.d.ts","sourceRoot":"","sources":["../../src/model-service/reference-candidate.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,kBAAkB;IAChC,4DAA4D;IAC5D,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe,CAAC,SAAS,SAAS,eAAe,GAAG,eAAe,CAAE,SAAQ,kBAAkB;IAC7G,+DAA+D;IAC/D,OAAO,EAAE,SAAS,CAAC;CACrB"}

package/lib/model-service/reference-candidate.js

@@ -0,0 +1,11 @@
+"use strict";
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=reference-candidate.js.map

package/lib/model-service/reference-candidate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-candidate.js","sourceRoot":"","sources":["../../src/model-service/reference-candidate.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF"}

package/lib/noop-logger.d.ts

@@ -0,0 +1,25 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import { AbstractLogger } from './abstract-logger';
+import { type LogLevel, type Logger } from './logger';
+/**
+ * {@link Logger} implementation that discards every message. Intended for
+ * programmatic / in-process consumers (test harnesses, non-LSP hosts) that
+ * use the framework services but don't have a vscode-jsonrpc connection to
+ * forward log output through.
+ *
+ * Chaining methods (`for`, `sub`, `with`) return a noop instance of the same
+ * class; `withUri` short-circuits to the same instance.
+ */
+export declare class NoopLogger extends AbstractLogger implements Logger {
+    protected emit(_level: LogLevel, _label: string, _message: string, _args: readonly unknown[]): void;
+    withUri(_uri: string): this;
+    protected derive(component: string): this;
+}
+//# sourceMappingURL=noop-logger.d.ts.map

package/lib/noop-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"noop-logger.d.ts","sourceRoot":"","sources":["../src/noop-logger.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAEtD;;;;;;;;GAQG;AACH,qBAAa,UAAW,SAAQ,cAAe,YAAW,MAAM;IAC7D,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,OAAO,EAAE,GAAG,IAAI;IAI1F,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKpC,SAAS,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;CAI3C"}

package/lib/noop-logger.js

@@ -0,0 +1,36 @@
+"use strict";
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NoopLogger = void 0;
+const abstract_logger_1 = require("./abstract-logger");
+/**
+ * {@link Logger} implementation that discards every message. Intended for
+ * programmatic / in-process consumers (test harnesses, non-LSP hosts) that
+ * use the framework services but don't have a vscode-jsonrpc connection to
+ * forward log output through.
+ *
+ * Chaining methods (`for`, `sub`, `with`) return a noop instance of the same
+ * class; `withUri` short-circuits to the same instance.
+ */
+class NoopLogger extends abstract_logger_1.AbstractLogger {
+    emit(_level, _label, _message, _args) {
+        // noop — every message is discarded.
+    }
+    withUri(_uri) {
+        // Composing a no-op label is wasted work — return the same instance.
+        return this;
+    }
+    derive(component) {
+        const Subclass = this.constructor;
+        return new Subclass(component);
+    }
+}
+exports.NoopLogger = NoopLogger;
+//# sourceMappingURL=noop-logger.js.map

package/lib/noop-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"noop-logger.js","sourceRoot":"","sources":["../src/noop-logger.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAElF,uDAAmD;AAGnD;;;;;;;;GAQG;AACH,MAAa,UAAW,SAAQ,gCAAc;IACjC,IAAI,CAAC,MAAgB,EAAE,MAAc,EAAE,QAAgB,EAAE,KAAyB;QACzF,qCAAqC;IACxC,CAAC;IAEQ,OAAO,CAAC,IAAY;QAC1B,qEAAqE;QACrE,OAAO,IAAI,CAAC;IACf,CAAC;IAES,MAAM,CAAC,SAAiB;QAC/B,MAAM,QAAQ,GAAG,IAAI,CAAC,WAA+C,CAAC;QACtE,OAAO,IAAI,QAAQ,CAAC,SAAS,CAAC,CAAC;IAClC,CAAC;CACH;AAdD,gCAcC"}

package/lib/observable-value.d.ts

@@ -0,0 +1,72 @@
+/********************************************************************************
+ * 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 Event } from 'vscode-jsonrpc';
+/**
+ * A value that may change over the connection lifetime. `value` is the
+ * current snapshot; `onChange` fires when the snapshot is replaced.
+ *
+ * The dynamic source in practice is always a user-configurable setting (see
+ * the `Settings` producers, which bind one to a Langium configuration
+ * section), but the type is source-agnostic — a constant wrapped via
+ * {@link ObservableValue.of} is still an `ObservableValue`; its `onChange`
+ * simply never fires. Recognised structurally by {@link isObservableValue}.
+ */
+export interface ObservableValue<T> {
+    /**
+     * `readonly` means the holder cannot assign it, NOT that it is stable —
+     * a live cell backs this with a getter, so it must be read at the point of
+     * use. Copying it into a field at construction pins the snapshot and
+     * silently defeats the whole type. A setting-bound cell answers its declared
+     * default until the client's configuration fetch resolves, so an early read
+     * is a legitimate value rather than an error.
+     */
+    readonly value: T;
+    /**
+     * Fires when {@link value} is replaced, deduplicated by `Object.is`, so an
+     * unchanged push is not re-announced. Subscribing is OPTIONAL and usually
+     * unnecessary — reading `.value` per use already sees every change; the
+     * event is for consumers that must re-arm something a later read cannot fix
+     * (a timer already scheduled, a listener already registered).
+     *
+     * It never fires at all for a constant cell, so logic that lives only in an
+     * `onChange` handler does nothing when an adopter passes a plain value.
+     * Dispose what subscribing returns.
+     */
+    readonly onChange: Event<T>;
+}
+/**
+ * What a service option accepts: either a plain constant (one-shot, never
+ * changes) or an {@link ObservableValue}. Consumers normalise to a cell once
+ * via {@link ObservableValue.from} and read `.value` at the point of use.
+ */
+export type MaybeObservableValue<T> = T | ObservableValue<T>;
+/**
+ * Type-guard discriminating a {@link MaybeObservableValue} into its {@link ObservableValue}
+ * arm. Returns `false` for primitives, `null`, and any non-object payload; for
+ * objects, requires both a `value` property and a callable `onChange` accessor
+ * (vscode-jsonrpc events are exposed as callable subscribers).
+ */
+export declare function isObservableValue<T>(input: MaybeObservableValue<T>): input is ObservableValue<T>;
+export declare namespace ObservableValue {
+    /**
+     * Wrap a constant as an {@link ObservableValue} whose `onChange` never
+     * fires. Adopters rarely need this — the constant arm of {@link MaybeObservableValue}
+     * already accepts a bare value; it exists for {@link from} and for tests
+     * that want an explicit cell.
+     */
+    function of<T>(value: T): ObservableValue<T>;
+    /**
+     * Normalise a {@link MaybeObservableValue} to an {@link ObservableValue}. Identity for a
+     * cell (preserving its live `value` getter + `onChange`); wraps a constant
+     * via {@link of}. The combinator a consumer calls once in its constructor
+     * so the rest of the class reads `.value` uniformly.
+     */
+    function from<T>(input: MaybeObservableValue<T>): ObservableValue<T>;
+}
+//# sourceMappingURL=observable-value.d.ts.map

package/lib/observable-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observable-value.d.ts","sourceRoot":"","sources":["../src/observable-value.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAmB,KAAK,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAE7D;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAC/B;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,IAAI,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC;AAO7D;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,KAAK,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAAG,KAAK,IAAI,eAAe,CAAC,CAAC,CAAC,CAMhG;AAED,yBAAiB,eAAe,CAAC;IAC9B;;;;;OAKG;IACH,SAAgB,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAElD;IAED;;;;;OAKG;IACH,SAAgB,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAE1E;CACH"}

package/lib/observable-value.js

@@ -0,0 +1,52 @@
+"use strict";
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ObservableValue = void 0;
+exports.isObservableValue = isObservableValue;
+const NOOP_DISPOSABLE = Object.freeze({ dispose: () => undefined });
+/** An {@link Event} that never fires — the `onChange` of a constant cell. */
+const NEVER_EVENT = () => NOOP_DISPOSABLE;
+/**
+ * Type-guard discriminating a {@link MaybeObservableValue} into its {@link ObservableValue}
+ * arm. Returns `false` for primitives, `null`, and any non-object payload; for
+ * objects, requires both a `value` property and a callable `onChange` accessor
+ * (vscode-jsonrpc events are exposed as callable subscribers).
+ */
+function isObservableValue(input) {
+    if (input === null || typeof input !== 'object') {
+        return false;
+    }
+    const candidate = input;
+    return 'value' in candidate && typeof candidate.onChange === 'function';
+}
+var ObservableValue;
+(function (ObservableValue) {
+    /**
+     * Wrap a constant as an {@link ObservableValue} whose `onChange` never
+     * fires. Adopters rarely need this — the constant arm of {@link MaybeObservableValue}
+     * already accepts a bare value; it exists for {@link from} and for tests
+     * that want an explicit cell.
+     */
+    function of(value) {
+        return { value, onChange: NEVER_EVENT };
+    }
+    ObservableValue.of = of;
+    /**
+     * Normalise a {@link MaybeObservableValue} to an {@link ObservableValue}. Identity for a
+     * cell (preserving its live `value` getter + `onChange`); wraps a constant
+     * via {@link of}. The combinator a consumer calls once in its constructor
+     * so the rest of the class reads `.value` uniformly.
+     */
+    function from(input) {
+        return isObservableValue(input) ? input : of(input);
+    }
+    ObservableValue.from = from;
+})(ObservableValue || (exports.ObservableValue = ObservableValue = {}));
+//# sourceMappingURL=observable-value.js.map

package/lib/observable-value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observable-value.js","sourceRoot":"","sources":["../src/observable-value.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAwDlF,8CAMC;AAjBD,MAAM,eAAe,GAAe,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC,CAAC;AAEhF,6EAA6E;AAC7E,MAAM,WAAW,GAAiB,GAAG,EAAE,CAAC,eAAe,CAAC;AAExD;;;;;GAKG;AACH,SAAgB,iBAAiB,CAAI,KAA8B;IAChE,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/C,OAAO,KAAK,CAAC;IAChB,CAAC;IACD,MAAM,SAAS,GAAG,KAAoC,CAAC;IACvD,OAAO,OAAO,IAAI,SAAS,IAAI,OAAO,SAAS,CAAC,QAAQ,KAAK,UAAU,CAAC;AAC3E,CAAC;AAED,IAAiB,eAAe,CAoB/B;AApBD,WAAiB,eAAe;IAC7B;;;;;OAKG;IACH,SAAgB,EAAE,CAAI,KAAQ;QAC3B,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAuB,EAAE,CAAC;IACvD,CAAC;IAFe,kBAAE,KAEjB,CAAA;IAED;;;;;OAKG;IACH,SAAgB,IAAI,CAAI,KAA8B;QACnD,OAAO,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;IACvD,CAAC;IAFe,oBAAI,OAEnB,CAAA;AACJ,CAAC,EApBgB,eAAe,+BAAf,eAAe,QAoB/B"}

package/lib/patch-merge.d.ts

@@ -0,0 +1,123 @@
+/********************************************************************************
+ * 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 Operation as JsonPatchOperation } from 'fast-json-patch';
+/**
+ * Augment a user-intent JSON patch (computed `baseline → attempted`) with
+ * `test` ops so a strict `applyPatch` against freshly-fetched server state
+ * fails loudly when a foreign writer changed a path the user also changed.
+ *
+ * `fast-json-patch`'s `validateOperation: true` validates op structure and
+ * path resolvability but NOT the pre-existing value — a plain `replace` /
+ * `remove` silently overwrites whatever the foreign writer put there. For each
+ * `replace` / `remove` op we prepend a `test` op carrying the baseline value at
+ * that path, so a same-path divergence becomes a `TEST_OPERATION_FAILED` throw.
+ * The caller treats that as a real field-level conflict (drop + refetch) rather
+ * than silently clobbering the foreign edit.
+ *
+ * `add` ops are left unguarded: the path is new, so there is no baseline value
+ * to test against, and add-vs-add overlaps are out of scope for this floor.
+ *
+ * Used behind the framework's `ConflictError` contract by every reconcile
+ * path — the GLSP recording command's undo/redo and forward-write, via
+ * {@link ReconcilingConflictResolver}, and an adopter's form-widget save — so
+ * they share one collision-detection rule.
+ */
+export declare function augmentWithTestOps(baseline: object, userPatch: ReadonlyArray<JsonPatchOperation>): JsonPatchOperation[];
+/**
+ * Outcome of {@link reconcileByPatchReplay}. The caller persists / re-baselines
+ * on `merged`, drops + surfaces the `fresh` root on `conflict`, and decides its
+ * own fallback (e.g. force-retry) on `no-op` / `unavailable`.
+ */
+export type ReconcileOutcome<T> = {
+    /** The replay succeeded: the foreign writer touched no path the user did. */
+    status: 'merged';
+    /**
+     * A fresh root built on the refetched server state, carrying both
+     * intents. It is NOT the caller's `attempted` root — re-baseline on
+     * this value, or the next write diffs against state the server never
+     * had.
+     */
+    merged: T;
+} | {
+    /**
+     * The user's root already equalled the baseline, so the version gate
+     * fired on drift that changed nothing. No refetch was performed and
+     * there is nothing to persist — retrying the same write reproduces it.
+     */
+    status: 'no-op';
+} | {
+    /** A guarded `test` op tripped: user and foreign writer touched one path. */
+    status: 'conflict';
+    /**
+     * The server's current root, refetched and unmodified — the user's
+     * intent was NOT applied to it. Surface it and drop the write; treating
+     * it as a merge result silently discards what the user typed.
+     */
+    fresh: T;
+} | {
+    /**
+     * The refetch produced nothing, so reconciliation could not be
+     * attempted at all. This says nothing about whether a conflict exists;
+     * the caller picks its own fallback (force-write, retry, surface).
+     */
+    status: 'unavailable';
+};
+/**
+ * Shared three-way reconcile for a `ConflictError`: diff the user's intent
+ * (`baseline → attempted`), refetch the server's current root, and replay the
+ * intent on top under strict, {@link augmentWithTestOps}-guarded `applyPatch`.
+ *
+ * - `no-op` — the user's root equals the baseline, so the gate fired on a
+ *   benign version drift; nothing to replay (refetch is skipped).
+ * - `unavailable` — the refetch produced nothing; caller falls back.
+ * - `merged` — the foreign writer touched only paths the user did not; the
+ *   merged root carries both intents.
+ * - `conflict` — a same-path divergence tripped a `test` op; caller drops the
+ *   write and surfaces `fresh`.
+ *
+ * I/O is the caller's: `refetch` supplies the current root, and applying the
+ * `merged` result (update vs save, re-baseline, UI refresh) stays at the call
+ * site so form and GLSP paths keep their own persistence semantics.
+ */
+export declare function reconcileByPatchReplay<T extends object>(baseline: T, attempted: T, refetch: () => Promise<T | undefined>): Promise<ReconcileOutcome<T>>;
+/**
+ * Strategy for resolving a write that raced a foreign edit. One declarative
+ * choice covers every conflict site — `execute` forward-write `(before,
+ * after)`, `undo` `(after, before)`, `redo` `(before, after)`, and form / GLSP
+ * save `(lastSynced, newRoot)` — so adopters pick reconcile-vs-force once
+ * (by binding a resolver) rather than per call site.
+ */
+export interface ConflictResolver {
+    /**
+     * Reconcile the user's `baseline → attempted` intent against the current
+     * server state (`refetch`), returning a {@link ReconcileOutcome} the caller
+     * acts on (persist `merged`, drop on `conflict`, fall back on `no-op` /
+     * `unavailable`).
+     */
+    resolve<T extends object>(baseline: T, attempted: T, refetch: () => Promise<T | undefined>): Promise<ReconcileOutcome<T>>;
+}
+/**
+ * Default {@link ConflictResolver}: field-level three-way merge via
+ * {@link reconcileByPatchReplay}. A foreign edit to a different field is
+ * merged; a same-field collision is reported as a conflict rather than
+ * clobbered.
+ */
+export declare class ReconcilingConflictResolver implements ConflictResolver {
+    resolve<T extends object>(baseline: T, attempted: T, refetch: () => Promise<T | undefined>): Promise<ReconcileOutcome<T>>;
+}
+/**
+ * Last-writer-wins {@link ConflictResolver}: always reports the `attempted`
+ * state as merged, without refetching or guarding. Suitable for single-client
+ * tools or always-regenerated artifacts where a concurrent foreign edit may be
+ * overwritten. A foreign edit to any field is clobbered.
+ */
+export declare class ForceConflictResolver implements ConflictResolver {
+    resolve<T extends object>(_baseline: T, attempted: T, _refetch: () => Promise<T | undefined>): Promise<ReconcileOutcome<T>>;
+}
+//# sourceMappingURL=patch-merge.d.ts.map

package/lib/patch-merge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patch-merge.d.ts","sourceRoot":"","sources":["../src/patch-merge.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAqD,KAAK,SAAS,IAAI,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE1H;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,EAAE,CASvH;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IACzB;IACG,6EAA6E;IAC7E,MAAM,EAAE,QAAQ,CAAC;IACjB;;;;;OAKG;IACH,MAAM,EAAE,CAAC,CAAC;CACZ,GACD;IACG;;;;OAIG;IACH,MAAM,EAAE,OAAO,CAAC;CAClB,GACD;IACG,6EAA6E;IAC7E,MAAM,EAAE,UAAU,CAAC;IACnB;;;;OAIG;IACH,KAAK,EAAE,CAAC,CAAC;CACX,GACD;IACG;;;;OAIG;IACH,MAAM,EAAE,aAAa,CAAC;CACxB,CAAC;AAEP;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,SAAS,MAAM,EAC1D,QAAQ,EAAE,CAAC,EACX,SAAS,EAAE,CAAC,EACZ,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,GACrC,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAe9B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC9B;;;;;OAKG;IACH,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;CAC5H;AAED;;;;;GAKG;AACH,qBAAa,2BAA4B,YAAW,gBAAgB;IACjE,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC;CAG3H;AAED;;;;;GAKG;AACH,qBAAa,qBAAsB,YAAW,gBAAgB;IACrD,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC;CAGnI"}

package/lib/patch-merge.js

@@ -0,0 +1,104 @@
+"use strict";
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ForceConflictResolver = exports.ReconcilingConflictResolver = void 0;
+exports.augmentWithTestOps = augmentWithTestOps;
+exports.reconcileByPatchReplay = reconcileByPatchReplay;
+const fast_json_patch_1 = require("fast-json-patch");
+/**
+ * Augment a user-intent JSON patch (computed `baseline → attempted`) with
+ * `test` ops so a strict `applyPatch` against freshly-fetched server state
+ * fails loudly when a foreign writer changed a path the user also changed.
+ *
+ * `fast-json-patch`'s `validateOperation: true` validates op structure and
+ * path resolvability but NOT the pre-existing value — a plain `replace` /
+ * `remove` silently overwrites whatever the foreign writer put there. For each
+ * `replace` / `remove` op we prepend a `test` op carrying the baseline value at
+ * that path, so a same-path divergence becomes a `TEST_OPERATION_FAILED` throw.
+ * The caller treats that as a real field-level conflict (drop + refetch) rather
+ * than silently clobbering the foreign edit.
+ *
+ * `add` ops are left unguarded: the path is new, so there is no baseline value
+ * to test against, and add-vs-add overlaps are out of scope for this floor.
+ *
+ * Used behind the framework's `ConflictError` contract by every reconcile
+ * path — the GLSP recording command's undo/redo and forward-write, via
+ * {@link ReconcilingConflictResolver}, and an adopter's form-widget save — so
+ * they share one collision-detection rule.
+ */
+function augmentWithTestOps(baseline, userPatch) {
+    const augmented = [];
+    for (const op of userPatch) {
+        if (op.op === 'replace' || op.op === 'remove') {
+            augmented.push({ op: 'test', path: op.path, value: (0, fast_json_patch_1.getValueByPointer)(baseline, op.path) });
+        }
+        augmented.push(op);
+    }
+    return augmented;
+}
+/**
+ * Shared three-way reconcile for a `ConflictError`: diff the user's intent
+ * (`baseline → attempted`), refetch the server's current root, and replay the
+ * intent on top under strict, {@link augmentWithTestOps}-guarded `applyPatch`.
+ *
+ * - `no-op` — the user's root equals the baseline, so the gate fired on a
+ *   benign version drift; nothing to replay (refetch is skipped).
+ * - `unavailable` — the refetch produced nothing; caller falls back.
+ * - `merged` — the foreign writer touched only paths the user did not; the
+ *   merged root carries both intents.
+ * - `conflict` — a same-path divergence tripped a `test` op; caller drops the
+ *   write and surfaces `fresh`.
+ *
+ * I/O is the caller's: `refetch` supplies the current root, and applying the
+ * `merged` result (update vs save, re-baseline, UI refresh) stays at the call
+ * site so form and GLSP paths keep their own persistence semantics.
+ */
+async function reconcileByPatchReplay(baseline, attempted, refetch) {
+    const userPatch = (0, fast_json_patch_1.compare)(baseline, attempted);
+    if (userPatch.length === 0) {
+        return { status: 'no-op' };
+    }
+    const fresh = await refetch();
+    if (!fresh) {
+        return { status: 'unavailable' };
+    }
+    try {
+        const merged = (0, fast_json_patch_1.applyPatch)((0, fast_json_patch_1.deepClone)(fresh), augmentWithTestOps(baseline, userPatch), true).newDocument;
+        return { status: 'merged', merged };
+    }
+    catch {
+        return { status: 'conflict', fresh };
+    }
+}
+/**
+ * Default {@link ConflictResolver}: field-level three-way merge via
+ * {@link reconcileByPatchReplay}. A foreign edit to a different field is
+ * merged; a same-field collision is reported as a conflict rather than
+ * clobbered.
+ */
+class ReconcilingConflictResolver {
+    resolve(baseline, attempted, refetch) {
+        return reconcileByPatchReplay(baseline, attempted, refetch);
+    }
+}
+exports.ReconcilingConflictResolver = ReconcilingConflictResolver;
+/**
+ * Last-writer-wins {@link ConflictResolver}: always reports the `attempted`
+ * state as merged, without refetching or guarding. Suitable for single-client
+ * tools or always-regenerated artifacts where a concurrent foreign edit may be
+ * overwritten. A foreign edit to any field is clobbered.
+ */
+class ForceConflictResolver {
+    async resolve(_baseline, attempted, _refetch) {
+        return { status: 'merged', merged: attempted };
+    }
+}
+exports.ForceConflictResolver = ForceConflictResolver;
+//# sourceMappingURL=patch-merge.js.map

package/lib/patch-merge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"patch-merge.js","sourceRoot":"","sources":["../src/patch-merge.ts"],"names":[],"mappings":";AAAA;;;;;;;kFAOkF;;;AAyBlF,gDASC;AA+DD,wDAmBC;AAlHD,qDAA0H;AAE1H;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAgB,kBAAkB,CAAC,QAAgB,EAAE,SAA4C;IAC9F,MAAM,SAAS,GAAyB,EAAE,CAAC;IAC3C,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;QAC1B,IAAI,EAAE,CAAC,EAAE,KAAK,SAAS,IAAI,EAAE,CAAC,EAAE,KAAK,QAAQ,EAAE,CAAC;YAC7C,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,IAAA,mCAAiB,EAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC9F,CAAC;QACD,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACtB,CAAC;IACD,OAAO,SAAS,CAAC;AACpB,CAAC;AA8CD;;;;;;;;;;;;;;;;GAgBG;AACI,KAAK,UAAU,sBAAsB,CACzC,QAAW,EACX,SAAY,EACZ,OAAqC;IAErC,MAAM,SAAS,GAAG,IAAA,yBAAO,EAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC/C,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IAC9B,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,OAAO,EAAE,CAAC;IAC9B,IAAI,CAAC,KAAK,EAAE,CAAC;QACV,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;IACpC,CAAC;IACD,IAAI,CAAC;QACF,MAAM,MAAM,GAAG,IAAA,4BAAU,EAAC,IAAA,2BAAS,EAAC,KAAK,CAAC,EAAE,kBAAkB,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,IAAI,CAAC,CAAC,WAAW,CAAC;QACvG,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACN,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IACxC,CAAC;AACJ,CAAC;AAmBD;;;;;GAKG;AACH,MAAa,2BAA2B;IACrC,OAAO,CAAmB,QAAW,EAAE,SAAY,EAAE,OAAqC;QACvF,OAAO,sBAAsB,CAAC,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;IAC/D,CAAC;CACH;AAJD,kEAIC;AAED;;;;;GAKG;AACH,MAAa,qBAAqB;IAC/B,KAAK,CAAC,OAAO,CAAmB,SAAY,EAAE,SAAY,EAAE,QAAsC;QAC/F,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAClD,CAAC;CACH;AAJD,sDAIC"}

package/lib/profile-session.d.ts

@@ -0,0 +1,87 @@
+/********************************************************************************
+ * 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 Clock, type Stopwatch } from './clock';
+import { Logger, type LogThreshold } from './logger';
+/** One aggregated row of a {@link ProfileSession}: a scope id and its totals. */
+export interface ProfileRecord {
+    /** The scope id passed to {@link ProfileSession.scope}. */
+    id: string;
+    /** How many times a scope with this id ran. */
+    count: number;
+    /** Summed self-time across those runs (wall-clock minus nested scopes). */
+    selfMs: number;
+    /** Self-time as a percentage of the session's total wall-clock. */
+    selfPct: number;
+}
+/**
+ * An aggregating, parent-exclusive self-time profiler scoped to one operation.
+ *
+ * Unlike `Tracer.time`, which emits one log line per
+ * call and keeps the timeline, a {@link ProfileSession} collapses many
+ * {@link scope} calls into a compact per-id aggregate (count + self-time +
+ * self-%), then dumps it as line-based output through a {@link Logger}. It is
+ * the in-house analogue of Langium's `ProfilingTask` (per-rule / per-node-type
+ * self-time) but for the framework's own passes — integrity rules, GModel
+ * construction, the save/reconcile chain — that Langium's profiler does not
+ * cover.
+ *
+ * Spawned per operation via `tracer.profile(id)`, used, reported, discarded —
+ * it is stateful and op-scoped, which is why it is not a method on the
+ * long-lived {@link Logger}/`Tracer`.
+ */
+export interface ProfileSession {
+    /**
+     * Run `fn` as a measured task `id`, accumulating its self-time = wall-clock
+     * minus any nested {@link scope} calls. Re-entrant: an inner scope nests and
+     * its full duration is excluded from the enclosing id's self-time
+     * (parent-exclusive). Async `fn` is awaited so timing covers the full
+     * settle. Returns `fn`'s result unchanged; rethrows after recording the
+     * elapsed time of a throwing scope.
+     */
+    scope<T>(id: string, fn: () => Promise<T>): Promise<T>;
+    scope<T>(id: string, fn: () => T): T;
+    /**
+     * Emit the aggregate through the bound {@link Logger}: one line per id,
+     * sorted by self-time descending, plus an "unaccounted" remainder (the
+     * session wall-clock not attributed to any top-level scope). No-op when
+     * `logLevel` is suppressed by the global threshold (incl. `'off'`).
+     */
+    report(logLevel?: LogThreshold): void;
+    /** The same aggregate as structured records, for tests / programmatic use. */
+    records(): readonly ProfileRecord[];
+}
+interface ScopeFrame {
+    readonly id: string;
+    /** Session-stopwatch reading when this scope began. */
+    readonly start: number;
+    /** Wall-time consumed by nested scopes, excluded from this scope's self-time. */
+    childMs: number;
+}
+/**
+ * Default {@link ProfileSession}. Times against an injected {@link Clock} (so
+ * it is fake-clock deterministic in tests, unlike a raw `performance.now`) and
+ * dumps through an injected {@link Logger}.
+ */
+export declare class DefaultProfileSession implements ProfileSession {
+    protected readonly logger: Logger;
+    protected readonly identifier: string;
+    /** Single monotonic timeline for the whole session; per-scope readings are deltas off it. */
+    protected readonly sessionStopwatch: Stopwatch;
+    protected readonly stack: ScopeFrame[];
+    protected readonly entries: Map<string, number[]>;
+    constructor(logger: Logger, clock: Clock, identifier: string);
+    scope<T>(id: string, fn: () => Promise<T>): Promise<T>;
+    scope<T>(id: string, fn: () => T): T;
+    /** Pop `frame`, charge its full duration to the parent, and record its self-time. */
+    protected closeFrame(frame: ScopeFrame): void;
+    records(): readonly ProfileRecord[];
+    report(logLevel?: LogThreshold): void;
+}
+export {};
+//# sourceMappingURL=profile-session.d.ts.map

package/lib/profile-session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-session.d.ts","sourceRoot":"","sources":["../src/profile-session.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,EAAU,MAAM,EAAE,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7D,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC3B,2DAA2D;IAC3D,EAAE,EAAE,MAAM,CAAC;IACX,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,cAAc;IAC5B;;;;;;;OAOG;IACH,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACvD,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IAErC;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAEtC,8EAA8E;IAC9E,OAAO,IAAI,SAAS,aAAa,EAAE,CAAC;CACtC;AAED,UAAU,UAAU;IACjB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,qBAAa,qBAAsB,YAAW,cAAc;IAOtD,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM;IAEjC,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,MAAM;IARxC,6FAA6F;IAC7F,SAAS,CAAC,QAAQ,CAAC,gBAAgB,EAAE,SAAS,CAAC;IAC/C,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,CAAM;IAC5C,SAAS,CAAC,QAAQ,CAAC,OAAO,wBAA+B;gBAGnC,MAAM,EAAE,MAAM,EACjC,KAAK,EAAE,KAAK,EACO,UAAU,EAAE,MAAM;IAKxC,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IACtD,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;IA2BpC,qFAAqF;IACrF,SAAS,CAAC,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAgB7C,OAAO,IAAI,SAAS,aAAa,EAAE;IAUnC,MAAM,CAAC,QAAQ,GAAE,YAAsB,GAAG,IAAI;CAiBhD"}