@hydranium/glsp-server 1.0.0-next.10

package/lib/state/hydranium-shared-core-services.js

@@ -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 { serviceIdentifier } from '../util/service-identifier.js';
+/**
+ * Inversify service-identifier registry for the framework services the
+ * `@hydranium/glsp-server` runtime exposes to `@injectable()` GLSP
+ * components. Framework GLSP-side classes are `@injectable()` and need an
+ * Inversify token to receive the Langium-style services the rest of the
+ * framework hands around via plain constructor arguments.
+ *
+ * Every token here is a service whose value is **fixed for the container tier
+ * that binds it** — process-wide shared services, a per-session conflict
+ * policy, the grammar a diagram type edits. That is the whole membership rule,
+ * and it is why the registry is short: see below for what deliberately does
+ * NOT get a token.
+ *
+ * Grouped under one object (rather than top-level `Hydranium<Role>` consts)
+ * so the token identity is decoupled from the implementation class name.
+ * Mirrors GLSP's own `TYPES` registry idiom.
+ *
+ * Bound by the adopter from their services trees — the app-tier ones directly,
+ * the session-tier language by declaring a grammar on the diagram module.
+ * Inject with the real service type as the field type.
+ *
+ * **Split by tier, because GLSP has no language tier.** GLSP's containers are
+ * app (per process) -> server (per connection) -> session (per open diagram);
+ * Langium's are shared (per process) -> language (per grammar, routed by URI).
+ * Only the outermost pair line up. A per-language service therefore CANNOT be
+ * bound at the app tier — that container is built before any document exists,
+ * so it can only ever hold one grammar's services. The tokens below are split
+ * accordingly:
+ *
+ * - **SharedCoreServices** — the framework's Langium-style shared services
+ *   tree ({@link ServerSharedServices}); the services-tree root that state /
+ *   index classes inject. Bound once at the app tier. Carries
+ *   `ServiceRegistry`, which is how everything below reaches a language.
+ * - **DiagramLanguage** — the {@link ServerLanguageServices} of the grammar a
+ *   diagram type edits, bound at the SESSION tier by
+ *   `AbstractHydraniumGlspDiagramModule` from its declared `declareLanguage()`.
+ *   Static (a diagram type has one grammar), so it is safe for the eagerly
+ *   constructed handlers GLSP builds at `InitializeClientSession`. Read it
+ *   through `AbstractHydraniumGlspState.diagramLanguage`.
+ * - **ConflictResolver** — the policy the GLSP state consults when a write
+ *   (forward-write, undo, redo, save) races a foreign edit.
+ *   `HydraniumGlspAppModule` binds it to `options.conflictResolver`
+ *   when supplied, else a default `ReconcilingConflictResolver` (field-level
+ *   three-way merge) unless the adopter opts into `ForceConflictResolver`.
+ * - **Tracer** — the measure-and-emit observability handle (timing, memory,
+ *   profiling). Bound per-request, auto-tagged with the requesting class name
+ *   (mirroring GLSP's `LoggerFactory` caller-tagging), so an `@injectable()`
+ *   GLSP class that times just injects it and its timing lines carry its own
+ *   component — no manual `for(...)`. The non-injectable recording command,
+ *   which can't inject, borrows the state's `tracer` getter instead.
+ *
+ * **No per-language SERVICE has a token — only the language does.** There is
+ * no `ElementKeyProvider`, `NameProvider`, `ScopeProvider` or
+ * `CandidateProvider` symbol, because every one of them is keyed by a document
+ * that the container cannot know: the target node's, for naming and keying;
+ * the one a reference is WRITTEN in, for scope and candidates. A GLSP
+ * component asks about several documents over its life — the diagram's own,
+ * the element it is editing, a drop target — so an injected provider instance
+ * answers as if there were one right answer and the routing decision vanishes
+ * from the call site. `this.candidateProvider` reads as language-neutral, and
+ * nothing prompts the author to ask which document the reference lives in;
+ * that is exactly how a foreign node ends up named under the diagram's
+ * grammar, producing a plausible string that matches nothing.
+ *
+ * So callers name the language they mean: `modelState.diagramLanguage` for a
+ * reference written on the canvas, `modelState.languageServicesFor(node)` for
+ * anything reached through a reference. `ServiceRegistry.getServicesFor(target)`
+ * serves the same purpose where no model state is at hand.
+ *
+ * The app-tier tokens are bound by `HydraniumGlspAppModule`, the
+ * session-tier one by `AbstractHydraniumGlspDiagramModule`. A multi-grammar
+ * adopter declares a language per diagram module and needs nothing else.
+ */
+export const HydraniumTypes = {
+    SharedCoreServices: serviceIdentifier('HydraniumSharedCoreServices'),
+    DiagramLanguage: serviceIdentifier('HydraniumDiagramLanguage'),
+    ConflictResolver: serviceIdentifier('HydraniumConflictResolver'),
+    Tracer: serviceIdentifier('HydraniumTracer')
+};
+//# sourceMappingURL=hydranium-shared-core-services.js.map

package/lib/state/hydranium-shared-core-services.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydranium-shared-core-services.js","sourceRoot":"","sources":["../../src/state/hydranium-shared-core-services.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAIlF,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC3B,kBAAkB,EAAE,iBAAiB,CAAuB,6BAA6B,CAAC;IAC1F,eAAe,EAAE,iBAAiB,CAAyB,0BAA0B,CAAC;IACtF,gBAAgB,EAAE,iBAAiB,CAAmB,2BAA2B,CAAC;IAClF,MAAM,EAAE,iBAAiB,CAAS,iBAAiB,CAAC;CAC7C,CAAC"}

package/lib/state/index.d.ts

@@ -0,0 +1,17 @@
+/********************************************************************************
+ * 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 './hydranium-glsp-index.js';
+export * from './abstract-hydranium-glsp-state.js';
+export * from './reconcile-source-model-write.js';
+export * from './reconciling-transfer-hydranium-glsp-state.js';
+export * from './reconciling-multi-document-glsp-state.js';
+export * from './full-text-hydranium-glsp-state.js';
+export * from './hydranium-shared-core-services.js';
+export * from './model-ready-timeout-error.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/state/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/state/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oCAAoC,CAAC;AACnD,cAAc,mCAAmC,CAAC;AAClD,cAAc,gDAAgD,CAAC;AAC/D,cAAc,4CAA4C,CAAC;AAC3D,cAAc,qCAAqC,CAAC;AACpD,cAAc,qCAAqC,CAAC;AACpD,cAAc,gCAAgC,CAAC"}

package/lib/state/index.js

@@ -0,0 +1,17 @@
+/********************************************************************************
+ * 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 './hydranium-glsp-index.js';
+export * from './abstract-hydranium-glsp-state.js';
+export * from './reconcile-source-model-write.js';
+export * from './reconciling-transfer-hydranium-glsp-state.js';
+export * from './reconciling-multi-document-glsp-state.js';
+export * from './full-text-hydranium-glsp-state.js';
+export * from './hydranium-shared-core-services.js';
+export * from './model-ready-timeout-error.js';
+//# sourceMappingURL=index.js.map

package/lib/state/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/state/index.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oCAAoC,CAAC;AACnD,cAAc,mCAAmC,CAAC;AAClD,cAAc,gDAAgD,CAAC;AAC/D,cAAc,4CAA4C,CAAC;AAC3D,cAAc,qCAAqC,CAAC;AACpD,cAAc,qCAAqC,CAAC;AACpD,cAAc,gCAAgC,CAAC"}

package/lib/state/model-ready-timeout-error.d.ts

@@ -0,0 +1,28 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * Thrown by `AbstractHydraniumGlspState.ready` when the wait for a document
+ * build state exceeds `AbstractHydraniumGlspState.readyTimeoutMs`. A dedicated
+ * error class so callers can distinguish a genuine hang from other failures
+ * via `instanceof`.
+ *
+ * The optional `diagnostic` carries a build-status snapshot so a captured log
+ * line is self-explanatory without correlating the timeout entry against
+ * earlier rebuild traces. `AbstractHydraniumGlspState.buildReadyTimeoutError`
+ * fills it from the document builder; a caller constructing the error directly
+ * may leave it empty.
+ */
+export declare class ModelReadyTimeoutError extends Error {
+    readonly uri: string;
+    readonly targetState: string;
+    readonly elapsedMs: number;
+    readonly diagnostic: string;
+    constructor(uri: string, targetState: string, elapsedMs: number, diagnostic?: string);
+}
+//# sourceMappingURL=model-ready-timeout-error.d.ts.map

package/lib/state/model-ready-timeout-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-ready-timeout-error.d.ts","sourceRoot":"","sources":["../../src/state/model-ready-timeout-error.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;;;;GAWG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;aAE3B,GAAG,EAAE,MAAM;aACX,WAAW,EAAE,MAAM;aACnB,SAAS,EAAE,MAAM;aACjB,UAAU,EAAE,MAAM;gBAHlB,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,UAAU,GAAE,MAAW;CAM5C"}

package/lib/state/model-ready-timeout-error.js

@@ -0,0 +1,36 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+/**
+ * Thrown by `AbstractHydraniumGlspState.ready` when the wait for a document
+ * build state exceeds `AbstractHydraniumGlspState.readyTimeoutMs`. A dedicated
+ * error class so callers can distinguish a genuine hang from other failures
+ * via `instanceof`.
+ *
+ * The optional `diagnostic` carries a build-status snapshot so a captured log
+ * line is self-explanatory without correlating the timeout entry against
+ * earlier rebuild traces. `AbstractHydraniumGlspState.buildReadyTimeoutError`
+ * fills it from the document builder; a caller constructing the error directly
+ * may leave it empty.
+ */
+export class ModelReadyTimeoutError extends Error {
+    uri;
+    targetState;
+    elapsedMs;
+    diagnostic;
+    constructor(uri, targetState, elapsedMs, diagnostic = '') {
+        const suffix = diagnostic ? ` ${diagnostic}` : '';
+        super(`Timed out after ${elapsedMs}ms waiting for state '${targetState}' on ${uri}.${suffix}`);
+        this.uri = uri;
+        this.targetState = targetState;
+        this.elapsedMs = elapsedMs;
+        this.diagnostic = diagnostic;
+        this.name = 'ModelReadyTimeoutError';
+    }
+}
+//# sourceMappingURL=model-ready-timeout-error.js.map

package/lib/state/model-ready-timeout-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-ready-timeout-error.js","sourceRoot":"","sources":["../../src/state/model-ready-timeout-error.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAE3B;IACA;IACA;IACA;IAJnB,YACmB,GAAW,EACX,WAAmB,EACnB,SAAiB,EACjB,aAAqB,EAAE;QAEvC,MAAM,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,IAAI,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClD,KAAK,CAAC,mBAAmB,SAAS,yBAAyB,WAAW,QAAQ,GAAG,IAAI,MAAM,EAAE,CAAC,CAAC;QAN/E,QAAG,GAAH,GAAG,CAAQ;QACX,gBAAW,GAAX,WAAW,CAAQ;QACnB,cAAS,GAAT,SAAS,CAAQ;QACjB,eAAU,GAAV,UAAU,CAAa;QAIvC,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACxC,CAAC;CACH"}

package/lib/state/reconcile-source-model-write.d.ts

@@ -0,0 +1,43 @@
+/********************************************************************************
+ * 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 ConflictResolver, type Logger } from '@hydranium/protocol';
+/**
+ * The I/O and policy a {@link reconcileSourceModelWrite} call needs. Deliberately
+ * a plain record rather than a base class: the states that use it differ in what
+ * "persist" and "project" mean but not at all in how a conflict is handled, and
+ * pulling the orchestration out is what keeps that second half from being
+ * written once per state.
+ */
+export interface SourceModelWriteHooks<TModel> {
+    /**
+     * Write `model` and capture the resulting state. Called with a `baseVersion`
+     * on the first attempt (opting into the `ConflictError` gate) and without one
+     * on the merged / forced retries, where the point is to land the write.
+     */
+    persist(model: TModel, baseVersion?: number): Promise<void>;
+    /** Current server-side projection, or `undefined` when unavailable. */
+    refetch(): Promise<TModel | undefined>;
+    /** Last in-sync projection the user's intent is measured against. */
+    readonly baseline: TModel | undefined;
+    readonly conflictResolver: ConflictResolver;
+    readonly logger: Logger;
+    /** Invoked when the edit is dropped, so the caller can resync its own state. */
+    onConflictDropped(): void;
+}
+/**
+ * Persist `model`, and on a `ConflictError` reconcile the user's intent against
+ * the current server state via the injected policy and act on the outcome.
+ *
+ * One declarative policy shared by forward-write, undo and redo: force =
+ * last-writer-wins, reconciling = field-level merge. A non-conflict error is
+ * re-thrown untouched — this function only knows how to handle the specific
+ * failure of "the based-on version was superseded".
+ */
+export declare function reconcileSourceModelWrite<TModel extends object>(model: TModel, version: number | undefined, hooks: SourceModelWriteHooks<TModel>): Promise<void>;
+//# sourceMappingURL=reconcile-source-model-write.d.ts.map

package/lib/state/reconcile-source-model-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile-source-model-write.d.ts","sourceRoot":"","sources":["../../src/state/reconcile-source-model-write.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,MAAM,EAAmB,MAAM,qBAAqB,CAAC;AAE1F;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB,CAAC,MAAM;IAC1C;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,uEAAuE;IACvE,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACvC,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gFAAgF;IAChF,iBAAiB,IAAI,IAAI,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,wBAAsB,yBAAyB,CAAC,MAAM,SAAS,MAAM,EAClE,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,KAAK,EAAE,qBAAqB,CAAC,MAAM,CAAC,GACpC,OAAO,CAAC,IAAI,CAAC,CA4Bf"}

package/lib/state/reconcile-source-model-write.js

@@ -0,0 +1,47 @@
+/********************************************************************************
+ * 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 { isConflictError } from '@hydranium/protocol';
+/**
+ * Persist `model`, and on a `ConflictError` reconcile the user's intent against
+ * the current server state via the injected policy and act on the outcome.
+ *
+ * One declarative policy shared by forward-write, undo and redo: force =
+ * last-writer-wins, reconciling = field-level merge. A non-conflict error is
+ * re-thrown untouched — this function only knows how to handle the specific
+ * failure of "the based-on version was superseded".
+ */
+export async function reconcileSourceModelWrite(model, version, hooks) {
+    try {
+        await hooks.persist(model, version);
+    }
+    catch (err) {
+        if (!isConflictError(err)) {
+            throw err;
+        }
+        const outcome = await hooks.conflictResolver.resolve(hooks.baseline ?? model, model, () => hooks.refetch());
+        switch (outcome.status) {
+            case 'merged':
+                await hooks.persist(outcome.merged);
+                return;
+            case 'no-op':
+                hooks.logger.debug(`updateSourceModel no-op (v${err.expected} → v${err.actual}); already in sync`);
+                return;
+            case 'conflict':
+                hooks.logger.warn(`updateSourceModel conflict (v${err.expected} → v${err.actual}); dropping the diagram edit — ` +
+                    'a foreign writer changed the same field');
+                hooks.onConflictDropped();
+                return;
+            case 'unavailable':
+                hooks.logger.warn(`updateSourceModel refetch unavailable (v${err.expected} → v${err.actual}); forcing without version`);
+                await hooks.persist(model);
+                return;
+        }
+    }
+}
+//# sourceMappingURL=reconcile-source-model-write.js.map

package/lib/state/reconcile-source-model-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile-source-model-write.js","sourceRoot":"","sources":["../../src/state/reconcile-source-model-write.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAsC,eAAe,EAAE,MAAM,qBAAqB,CAAC;AA0B1F;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC5C,KAAa,EACb,OAA2B,EAC3B,KAAoC;IAEpC,IAAI,CAAC;QACF,MAAM,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACZ,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,EAAE,CAAC;YACzB,MAAM,GAAG,CAAC;QACb,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,gBAAgB,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,IAAI,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QAC5G,QAAQ,OAAO,CAAC,MAAM,EAAE,CAAC;YACtB,KAAK,QAAQ;gBACV,MAAM,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;gBACpC,OAAO;YACV,KAAK,OAAO;gBACT,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,6BAA6B,GAAG,CAAC,QAAQ,OAAO,GAAG,CAAC,MAAM,oBAAoB,CAAC,CAAC;gBACnG,OAAO;YACV,KAAK,UAAU;gBACZ,KAAK,CAAC,MAAM,CAAC,IAAI,CACd,gCAAgC,GAAG,CAAC,QAAQ,OAAO,GAAG,CAAC,MAAM,iCAAiC;oBAC3F,yCAAyC,CAC9C,CAAC;gBACF,KAAK,CAAC,iBAAiB,EAAE,CAAC;gBAC1B,OAAO;YACV,KAAK,aAAa;gBACf,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,2CAA2C,GAAG,CAAC,QAAQ,OAAO,GAAG,CAAC,MAAM,4BAA4B,CAAC,CAAC;gBACxH,MAAM,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;gBAC3B,OAAO;QACb,CAAC;IACJ,CAAC;AACJ,CAAC"}

package/lib/state/reconciling-multi-document-glsp-state.d.ts

@@ -0,0 +1,164 @@
+/********************************************************************************
+ * 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 JsonModelState } from '@eclipse-glsp/server';
+import { type AstNode } from '@hydranium/langium';
+import { type TransferElement } from '@hydranium/protocol';
+import { AbstractHydraniumGlspState } from './abstract-hydranium-glsp-state.js';
+/**
+ * Source model spanning more than one document: the primary document's
+ * projection plus one per registered secondary, keyed by URI.
+ *
+ * Keyed by URI rather than held as an array so a recorded undo / redo patch
+ * still addresses the right document when the tracked set has changed since the
+ * patch was recorded — an array would re-apply by index and silently write the
+ * wrong file. The JSON-Pointer escaping that URI keys imply is the patch
+ * library's job, not the adopter's.
+ */
+export interface MultiDocumentSourceModel<TPrimary extends TransferElement = TransferElement> {
+    /** Projection of the primary (diagram) document — the one `sourceUri` names. */
+    primary: TPrimary;
+    /** Projection of each registered secondary document, keyed by its URI. */
+    secondaries: Record<string, TransferElement>;
+}
+/**
+ * Editable GLSP state for a diagram whose edits span SEVERAL Langium documents —
+ * a diagram file plus the semantic file it references, say, where creating a node
+ * on the canvas writes both.
+ *
+ * The single-document `ReconcilingTransferHydraniumGlspState` cannot express
+ * that: its `sourceModel`, `persist` and `refetch` are all defined over
+ * `sourceUri` alone, so an adopter needing a second document had to override all
+ * three — i.e. the entire class. This subclass keeps the same three seams and the
+ * same conflict handling (both share {@link reconcileSourceModelWrite}) but
+ * defines them over the primary plus the secondary write set registered through
+ * {@link AbstractHydraniumGlspState.trackSecondaryDocument}.
+ *
+ * **Writes are NOT atomic, deliberately, and the window is real.** Each document
+ * goes through its own `ModelService.update`, so a failure after the first write
+ * has landed leaves the set inconsistent on disk. There is no multi-document
+ * transaction to lean on: `WorkspaceLock` serialises builds but does not roll
+ * back, and the document store commits per URI. An adopter that cannot accept the
+ * window should not span documents in one operation.
+ *
+ * **What makes the window tolerable is write ORDER, and the rule is
+ * referenced-before-referencing** — not "secondaries first" as such. Write the
+ * document whose content the others point AT before the documents that point at
+ * it, so a partial write leaves an unreferenced element (inert, and the direction
+ * an integrity rule can repair) rather than a reference to something that does
+ * not exist (a linking error). {@link persist} implements that as
+ * secondaries-then-primary, which is correct for the common shape where the
+ * primary is the DIAGRAM and the semantics it references are secondaries: the
+ * user opened the diagram, so it is also the document the conflict gate should
+ * guard. **An adopter whose primary is the referenced document — a semantic file
+ * as the diagram source, with layout in a secondary — has the ordering backwards
+ * and must override {@link persist} to write the primary first.** Overriding it
+ * is the supported route; the base order is a default for the common case, not an
+ * invariant of the class.
+ *
+ * **The conflict gate covers the primary only.** Secondaries are written without
+ * a based-on version, so a concurrent foreign edit to one is overwritten rather
+ * than reconciled. Gating them too would need a per-document reconcile whose
+ * outcomes can disagree (merge one, conflict another) with no way to un-write the
+ * merged one — the atomicity problem again, one layer up. The captured versions
+ * ARE available via {@link AbstractHydraniumGlspState.capturedVersionOf}, so an
+ * adopter that wants a coarser check can compare before writing.
+ */
+export declare class ReconcilingMultiDocumentGlspState<TRoot extends AstNode, TPrimary extends TransferElement = TransferElement> extends AbstractHydraniumGlspState<TRoot, MultiDocumentSourceModel<TPrimary>> implements JsonModelState<MultiDocumentSourceModel<TPrimary>> {
+    /**
+     * Last in-sync projection across the whole write set, captured on every
+     * {@link setSourceRoot}. Same role as the single-document baseline: the state a
+     * forward-write conflict reconciles the user's intent against.
+     */
+    protected baseline?: MultiDocumentSourceModel<TPrimary>;
+    /**
+     * Projection of the primary plus every registered secondary, in the framework
+     * encoder's `'grammar'` mode (authored state only — cross-references as
+     * `$refText`, computed / synthetic properties excluded), so `fast-json-patch`
+     * diffs per field across all of them at once.
+     *
+     * A secondary that is not currently loaded is OMITTED rather than represented
+     * as `undefined`: an absent key produces no patch operations for that
+     * document, whereas an explicit `undefined` would diff as a removal and
+     * persist as a deletion of content the state simply could not see.
+     */
+    get sourceModel(): MultiDocumentSourceModel<TPrimary>;
+    setSourceRoot(uri: string, root: TRoot): void;
+    /**
+     * Register the secondary documents that belong to the primary at `uri`, via
+     * {@link AbstractHydraniumGlspState.trackSecondaryDocument}. Called on every
+     * {@link setSourceRoot}, after the primary is captured (so `sourceUri` is
+     * current) and BEFORE the baseline is taken (so the baseline includes them).
+     * Default: no secondaries.
+     *
+     * This hook exists because that ordering is a trap an adopter would otherwise
+     * hit silently. Registering from an overridden `setSourceRoot` *after*
+     * `super.setSourceRoot(...)` runs too late — the baseline has already been
+     * captured without the secondaries, so the first conflict reconcile measures
+     * the user's intent against a baseline missing half the write set and the
+     * secondary edits look like foreign changes. Registering *before* the super
+     * call is too early for a URI derived from the new primary. Overriding this
+     * instead removes the choice.
+     */
+    protected trackWriteSet(_uri: string): void;
+    /**
+     * Persist the whole write set, then capture the resulting primary root. On a
+     * `ConflictError` from the primary, reconcile via the injected policy exactly
+     * as the single-document state does — the orchestration is shared.
+     */
+    updateSourceModel(model: MultiDocumentSourceModel<TPrimary>, version?: number): Promise<void>;
+    /**
+     * Write hook — secondaries first (ungated), primary last (gated on
+     * `baseVersion`). The order is the failure-mode choice documented on the
+     * class, not incidental: override this when the primary is the document the
+     * others REFERENCE, since then this order writes the references first.
+     */
+    protected persist(model: MultiDocumentSourceModel<TPrimary>, baseVersion?: number): Promise<{
+        root: TRoot;
+    }>;
+    /**
+     * Whether `candidate` differs from the baseline projection of the same
+     * document, and therefore needs writing.
+     *
+     * **Skipping unchanged documents is correctness, not an optimisation.** A
+     * write goes through `ModelService.update`, which re-serializes from the AST —
+     * so writing a document that did not change still rewrites its text, and a
+     * serializer is free to normalise formatting and cannot preserve comments.
+     * Persisting the whole write set unconditionally therefore means a pure layout
+     * drag reflows the semantic file and strips its comments, which is a data
+     * loss the user never asked for and would struggle to attribute.
+     *
+     * Compared by serialised form. Both sides come from the same encoder walking
+     * the same shape, so key order is stable and a string compare is sound here;
+     * it is also cheap enough to run per document per write.
+     */
+    protected hasChanged(baseline: object | undefined, candidate: object): boolean;
+    /** Write the primary document, opting into the conflict gate when `baseVersion` is given. */
+    protected persistPrimary(model: TPrimary, baseVersion?: number): Promise<{
+        root: TRoot;
+    }>;
+    /**
+     * Write one secondary document. Ungated by design (see the class doc); override
+     * alongside {@link persistPrimary} when the round-trip differs per document
+     * role — a layout file and a semantic file need not share a serializer.
+     */
+    protected persistSecondary(uri: string, model: TransferElement): Promise<void>;
+    /**
+     * Refetch hook — the current settled projection across the write set, used by
+     * the conflict resolver to replay the user's intent against fresh state.
+     * Returns `undefined` when the PRIMARY cannot be read, since a reconcile
+     * without it has nothing to merge into; an unreadable secondary is omitted the
+     * same way {@link sourceModel} omits one.
+     */
+    protected refetch(): Promise<MultiDocumentSourceModel<TPrimary> | undefined>;
+    /** Project a currently-loaded document's root, or `undefined` when it is not loaded. */
+    protected projectDocument(uri: string): TransferElement | undefined;
+    /** Grammar-mode transfer projection of one AST root. The single projection seam. */
+    protected projectRoot<T extends TransferElement = TransferElement>(root: AstNode): T;
+}
+//# sourceMappingURL=reconciling-multi-document-glsp-state.d.ts.map

package/lib/state/reconciling-multi-document-glsp-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconciling-multi-document-glsp-state.d.ts","sourceRoot":"","sources":["../../src/state/reconciling-multi-document-glsp-state.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AAGhF;;;;;;;;;GASG;AACH,MAAM,WAAW,wBAAwB,CAAC,QAAQ,SAAS,eAAe,GAAG,eAAe;IACzF,gFAAgF;IAChF,OAAO,EAAE,QAAQ,CAAC;IAClB,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CAC/C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qBACa,iCAAiC,CAAC,KAAK,SAAS,OAAO,EAAE,QAAQ,SAAS,eAAe,GAAG,eAAe,CACrH,SAAQ,0BAA0B,CAAC,KAAK,EAAE,wBAAwB,CAAC,QAAQ,CAAC,CAC5E,YAAW,cAAc,CAAC,wBAAwB,CAAC,QAAQ,CAAC,CAAC;IAE7D;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,EAAE,wBAAwB,CAAC,QAAQ,CAAC,CAAC;IAExD;;;;;;;;;;OAUG;IACH,IAAI,WAAW,IAAI,wBAAwB,CAAC,QAAQ,CAAC,CASpD;IAEQ,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI;IAMtD;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI3C;;;;OAIG;IACG,iBAAiB,CAAC,KAAK,EAAE,wBAAwB,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcnG;;;;;OAKG;cACa,OAAO,CAAC,KAAK,EAAE,wBAAwB,CAAC,QAAQ,CAAC,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,KAAK,CAAA;KAAE,CAAC;IAclH;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAI9E,6FAA6F;cAC7E,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,KAAK,CAAA;KAAE,CAAC;IAU/F;;;;OAIG;cACa,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpF;;;;;;OAMG;cACa,OAAO,IAAI,OAAO,CAAC,wBAAwB,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAC;IAelF,wFAAwF;IACxF,SAAS,CAAC,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS;IAKnE,oFAAoF;IACpF,SAAS,CAAC,WAAW,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe,EAAE,IAAI,EAAE,OAAO,GAAG,CAAC;CAGtF"}