@hydranium/core 1.0.0-next.30 → 1.0.0-next.300

package/lib/langium/workspace/document-uri-policy.d.ts

@@ -19,6 +19,8 @@ import { type ServerSharedServicesMinimal } from '../shared-services.js';
  */
 export interface RealpathCapableFileSystem {
     realpath?(uri: URI): URI | undefined;
+    /** `uri` with its links followed, those to nothing included; see `WritableFileSystemProvider.resolveLinks`. */
+    resolveLinks?(uri: URI): URI;
 }
 /**
  * Report whether `uri`'s real on-disk path differs from its syntactic
@@ -43,16 +45,17 @@ export declare function findRealpathDivergence(uri: URI | string, fs: RealpathCa
  * - {@link canonicalUri} — TOTAL: maps any URI to the single canonical *string*
  *   the framework keys a document by, regardless of whether the file exists.
  *   This is the form that MUST match the adopter's `LangiumDocuments` keying so
- *   the text store, AST-document event filters
- *   (`AstDocumentManager.onUpdate` / `onSave` / `onClientClosed`), and
+ *   the text store, `ModelService`'s event filters, and
  *   `LangiumDocuments` lookups all agree on one identity for the same file. Use
  *   for keying, comparison, and the text-store ↔ document-store bridges.
  *
  * - {@link loadUri} — EXISTENCE-AWARE: maps a URI to the *load* URI, or
  *   `undefined` when there is no loadable on-disk content for it. Use where the
  *   next step actually touches the filesystem (loading a document, walking a
- *   directory): `undefined` means "skip / treat as empty" rather than attempt a
- *   doomed read. The default treats every URI as loadable (returns it
+ *   directory): `undefined` means "skip the read" rather than attempt a doomed
+ *   one. It does not mean there is no document: one created and not yet saved
+ *   has no file, and the text store and `LangiumDocuments` hold it under
+ *   {@link canonicalUri}. The default treats every URI as loadable (returns it
  *   unchanged); a real-path policy returns the resolved file URI, or `undefined`
  *   for a not-yet-written path.
  *
@@ -76,7 +79,9 @@ export interface DocumentUriPolicy {
     /**
      * Existence-aware resolution to the load URI, or `undefined` when there is
      * no loadable content for `uri` (missing / synthetic). Callers that read the
-     * filesystem next use `undefined` to skip rather than attempt a doomed read.
+     * filesystem next use `undefined` to skip rather than attempt a doomed read,
+     * and still look the URI up under {@link canonicalUri}: a document created
+     * and not yet saved is held there with no file behind it.
      */
     loadUri(uri: URI | string): URI | undefined;
 }
@@ -129,17 +134,21 @@ export declare class DefaultDocumentUriPolicy implements DocumentUriPolicy {
  * The raw `realpath` syscall lives on the `FileSystemProvider`
  * (`@hydranium/core/node`'s `DefaultFileSystemProvider`), not here — this policy
  * is pure routing over that seam, so it carries no `node:fs` import and is
- * browser-neutral. Both methods follow the *same* policy: `canonicalUri` falls
- * back to the syntactic form when the path can't be resolved (optimistic — a
- * file that appears later canonicalises to the same key once present), while
- * `loadUri` returns `undefined` for an absent path (honest about existence, so a
- * caller about to read the filesystem skips it).
+ * browser-neutral. Both methods follow the *same* policy: `canonicalUri` keys a
+ * path that can't be resolved by the links it follows, where the provider has
+ * `resolveLinks`, else by its syntactic form (optimistic — a file that appears
+ * later canonicalises to the same key once present, also one reached through a
+ * link that pointed at nothing), while `loadUri` returns `undefined` for an
+ * absent path (honest about existence, so a caller about to read the
+ * filesystem skips it).
  *
- * If the bound provider has no `realpath` (in-memory / browser / empty),
- * both methods degrade to {@link DefaultDocumentUriPolicy} automatically — the
- * `loadUri` ternary tests the *method's presence*, not its return, so the
- * existence signal is preserved: `loadUri` returns `undefined` only when
- * `realpath` is present and reports the path absent.
+ * If the provider for a URI's scheme has no `realpath` (in-memory / browser /
+ * empty), the framework's `FileSystemProviderRegistry` returns the URI
+ * unchanged and both methods answer as {@link DefaultDocumentUriPolicy} does. A
+ * slot bound to a provider without `realpath` degrades the same way: the
+ * `loadUri` ternary tests the *method's presence*, not its return, so
+ * `loadUri` returns `undefined` only when `realpath` is present and reports the
+ * path absent.
  */
 export declare class RealpathDocumentUriPolicy extends DefaultDocumentUriPolicy {
     protected readonly fs: RealpathCapableFileSystem;

package/lib/langium/workspace/document-uri-policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"document-uri-policy.d.ts","sourceRoot":"","sources":["../../../src/langium/workspace/document-uri-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,YAAY,EAAkB,MAAM,qBAAqB,CAAC;AACxE,OAAO,EAAE,KAAK,GAAG,EAAY,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAEzE;;;;;;;GAOG;AACH,MAAM,WAAW,yBAAyB;IACvC,QAAQ,CAAC,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,GAAG,SAAS,CAAC;CACvC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,EAAE,EAAE,EAAE,yBAAyB,GAAG,GAAG,GAAG,SAAS,CAIxG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,WAAW,iBAAiB;IAC/B,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,YAAY,CAAC;IAC9C;;;;OAIG;IACH,OAAO,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,GAAG,GAAG,SAAS,CAAC;CAC9C;AAED;;;;;GAKG;AACH,qBAAa,wBAAyB,YAAW,iBAAiB;IAC/D,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,YAAY;IAM7C;;;;;;OAMG;IACH,OAAO,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,GAAG,GAAG,SAAS;CAG7C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qBAAa,yBAA0B,SAAQ,wBAAwB;IACpE,SAAS,CAAC,QAAQ,CAAC,EAAE,EAAE,yBAAyB,CAAC;gBAErC,QAAQ,EAAE,2BAA2B;IAKxC,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,YAAY;IAQ7C,OAAO,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,GAAG,GAAG,SAAS;CAStD"}
+{"version":3,"file":"document-uri-policy.d.ts","sourceRoot":"","sources":["../../../src/langium/workspace/document-uri-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,YAAY,EAAkB,MAAM,qBAAqB,CAAC;AACxE,OAAO,EAAE,KAAK,GAAG,EAAY,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAEzE;;;;;;;GAOG;AACH,MAAM,WAAW,yBAAyB;IACvC,QAAQ,CAAC,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,GAAG,SAAS,CAAC;IACrC,+GAA+G;IAC/G,YAAY,CAAC,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,CAAC;CAC/B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,EAAE,EAAE,EAAE,yBAAyB,GAAG,GAAG,GAAG,SAAS,CAIxG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,WAAW,iBAAiB;IAC/B,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,YAAY,CAAC;IAC9C;;;;;;OAMG;IACH,OAAO,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,GAAG,GAAG,SAAS,CAAC;CAC9C;AAED;;;;;GAKG;AACH,qBAAa,wBAAyB,YAAW,iBAAiB;IAC/D,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,YAAY,CAI5C;IAED;;;;;;OAMG;IACH,OAAO,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,GAAG,GAAG,SAAS,CAE1C;CACH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,qBAAa,yBAA0B,SAAQ,wBAAwB;IACpE,SAAS,CAAC,QAAQ,CAAC,EAAE,EAAE,yBAAyB,CAAC;IAEjD,YAAY,QAAQ,EAAE,2BAA2B,EAGhD;IAEQ,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,YAAY,CAWrD;IAEQ,OAAO,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,GAAG,GAAG,SAAS,CAQnD;CACH"}

package/lib/langium/workspace/document-uri-policy.js

@@ -82,17 +82,21 @@ export class DefaultDocumentUriPolicy {
  * The raw `realpath` syscall lives on the `FileSystemProvider`
  * (`@hydranium/core/node`'s `DefaultFileSystemProvider`), not here — this policy
  * is pure routing over that seam, so it carries no `node:fs` import and is
- * browser-neutral. Both methods follow the *same* policy: `canonicalUri` falls
- * back to the syntactic form when the path can't be resolved (optimistic — a
- * file that appears later canonicalises to the same key once present), while
- * `loadUri` returns `undefined` for an absent path (honest about existence, so a
- * caller about to read the filesystem skips it).
+ * browser-neutral. Both methods follow the *same* policy: `canonicalUri` keys a
+ * path that can't be resolved by the links it follows, where the provider has
+ * `resolveLinks`, else by its syntactic form (optimistic — a file that appears
+ * later canonicalises to the same key once present, also one reached through a
+ * link that pointed at nothing), while `loadUri` returns `undefined` for an
+ * absent path (honest about existence, so a caller about to read the
+ * filesystem skips it).
  *
- * If the bound provider has no `realpath` (in-memory / browser / empty),
- * both methods degrade to {@link DefaultDocumentUriPolicy} automatically — the
- * `loadUri` ternary tests the *method's presence*, not its return, so the
- * existence signal is preserved: `loadUri` returns `undefined` only when
- * `realpath` is present and reports the path absent.
+ * If the provider for a URI's scheme has no `realpath` (in-memory / browser /
+ * empty), the framework's `FileSystemProviderRegistry` returns the URI
+ * unchanged and both methods answer as {@link DefaultDocumentUriPolicy} does. A
+ * slot bound to a provider without `realpath` degrades the same way: the
+ * `loadUri` ternary tests the *method's presence*, not its return, so
+ * `loadUri` returns `undefined` only when `realpath` is present and reports the
+ * path absent.
  */
 export class RealpathDocumentUriPolicy extends DefaultDocumentUriPolicy {
     fs;
@@ -102,9 +106,14 @@ export class RealpathDocumentUriPolicy extends DefaultDocumentUriPolicy {
     }
     canonicalUri(uri) {
         const parsed = UriUtils.toUri(uri);
-        const real = parsed && this.fs.realpath?.(parsed);
-        // Mint via `asCanonicalUri` once normalised; absent / unresolvable paths
-        // (and a provider without `realpath`) fall back to the syntactic form.
+        // An absent path keys by the links it follows, so a file reached through
+        // a link keys the same before it exists and once it does; a provider
+        // without `resolveLinks`, or without `realpath`, keys it syntactically.
+        // `resolveLinks` alone where it exists: it resolves a present path as
+        // `realpath` does, and asking both would cost an absent path a second
+        // miss.
+        const real = parsed && (this.fs.resolveLinks ? this.fs.resolveLinks(parsed) : this.fs.realpath?.(parsed));
+        // Mint via `asCanonicalUri` once normalised.
         return real ? asCanonicalUri(UriUtils.normalize(real)) : super.canonicalUri(uri);
     }
     loadUri(uri) {

package/lib/langium/workspace/document-uri-policy.js.map

@@ -1 +1 @@
-{"version":3,"file":"document-uri-policy.js","sourceRoot":"","sources":["../../../src/langium/workspace/document-uri-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAqB,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,EAAY,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAexD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAiB,EAAE,EAA6B;IACpF,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,MAAM,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAC,MAAM,CAAC,CAAC;IAC7C,OAAO,IAAI,IAAI,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AAC1F,CAAC;AAgDD;;;;;GAKG;AACH,MAAM,OAAO,wBAAwB;IAClC,YAAY,CAAC,GAAiB;QAC3B,yEAAyE;QACzE,6EAA6E;QAC7E,OAAO,cAAc,CAAC,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;IAClD,CAAC;IAED;;;;;;OAMG;IACH,OAAO,CAAC,GAAiB;QACtB,OAAO,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,OAAO,yBAA0B,SAAQ,wBAAwB;IACjD,EAAE,CAA4B;IAEjD,YAAY,QAAqC;QAC9C,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,EAAE,GAAG,QAAQ,CAAC,SAAS,CAAC,kBAAkB,CAAC;IACnD,CAAC;IAEQ,YAAY,CAAC,GAAiB;QACpC,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACnC,MAAM,IAAI,GAAG,MAAM,IAAI,IAAI,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,MAAM,CAAC,CAAC;QAClD,yEAAyE;QACzE,uEAAuE;QACvE,OAAO,IAAI,CAAC,CAAC,CAAC,cAAc,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;IACpF,CAAC;IAEQ,OAAO,CAAC,GAAiB;QAC/B,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC;YACrB,OAAO,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC7B,CAAC;QACD,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACnC,kEAAkE;QAClE,yEAAyE;QACzE,OAAO,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACrD,CAAC;CACH"}
+{"version":3,"file":"document-uri-policy.js","sourceRoot":"","sources":["../../../src/langium/workspace/document-uri-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAqB,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACxE,OAAO,EAAY,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAiBxD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAiB,EAAE,EAA6B;IACpF,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,MAAM,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAC,MAAM,CAAC,CAAC;IAC7C,OAAO,IAAI,IAAI,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AAC1F,CAAC;AAmDD;;;;;GAKG;AACH,MAAM,OAAO,wBAAwB;IAClC,YAAY,CAAC,GAAiB;QAC3B,yEAAyE;QACzE,6EAA6E;QAC7E,OAAO,cAAc,CAAC,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;IAClD,CAAC;IAED;;;;;;OAMG;IACH,OAAO,CAAC,GAAiB;QACtB,OAAO,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,OAAO,yBAA0B,SAAQ,wBAAwB;IACjD,EAAE,CAA4B;IAEjD,YAAY,QAAqC;QAC9C,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,EAAE,GAAG,QAAQ,CAAC,SAAS,CAAC,kBAAkB,CAAC;IACnD,CAAC;IAEQ,YAAY,CAAC,GAAiB;QACpC,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACnC,yEAAyE;QACzE,qEAAqE;QACrE,wEAAwE;QACxE,sEAAsE;QACtE,sEAAsE;QACtE,QAAQ;QACR,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;QAC1G,6CAA6C;QAC7C,OAAO,IAAI,CAAC,CAAC,CAAC,cAAc,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;IACpF,CAAC;IAEQ,OAAO,CAAC,GAAiB;QAC/B,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC;YACrB,OAAO,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC7B,CAAC;QACD,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACnC,kEAAkE;QAClE,yEAAyE;QACzE,OAAO,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACrD,CAAC;CACH"}

package/lib/langium/workspace/file-not-found.d.ts

@@ -0,0 +1,23 @@
+/********************************************************************************
+ * 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 URI } from '@hydranium/langium';
+/**
+ * A missing-file error shaped as a Node file system raises it, with code
+ * `ENOENT` and the path: callers tell a missing file from any other failure by
+ * those two fields, whichever provider is bound. The release relies on it to
+ * tell a document gone meanwhile from any other failed rebuild.
+ */
+export declare function notFound(message: string, uri: URI): Error;
+/**
+ * Whether `err` reports that the file of `target` does not exist, as a Node
+ * file system and {@link notFound} do: code `ENOENT`, with `target`'s path. A
+ * missing file of another document is a different failure.
+ */
+export declare function isFileNotFound(err: unknown, target: URI): boolean;
+//# sourceMappingURL=file-not-found.d.ts.map

package/lib/langium/workspace/file-not-found.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-not-found.d.ts","sourceRoot":"","sources":["../../../src/langium/workspace/file-not-found.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAK9C;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,GAAG,KAAK,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,GAAG,OAAO,CAKjE"}

package/lib/langium/workspace/file-not-found.js

@@ -0,0 +1,31 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+// Not re-exported from the workspace barrel: the framework's providers and
+// the release handler share it, and it is no API of theirs.
+/**
+ * A missing-file error shaped as a Node file system raises it, with code
+ * `ENOENT` and the path: callers tell a missing file from any other failure by
+ * those two fields, whichever provider is bound. The release relies on it to
+ * tell a document gone meanwhile from any other failed rebuild.
+ */
+export function notFound(message, uri) {
+    return Object.assign(new Error(message), { code: 'ENOENT', path: uri.fsPath });
+}
+/**
+ * Whether `err` reports that the file of `target` does not exist, as a Node
+ * file system and {@link notFound} do: code `ENOENT`, with `target`'s path. A
+ * missing file of another document is a different failure.
+ */
+export function isFileNotFound(err, target) {
+    if (typeof err !== 'object' || err === null || !('code' in err) || err.code !== 'ENOENT') {
+        return false;
+    }
+    return !('path' in err) || err.path === target.fsPath;
+}
+//# sourceMappingURL=file-not-found.js.map

package/lib/langium/workspace/file-not-found.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-not-found.js","sourceRoot":"","sources":["../../../src/langium/workspace/file-not-found.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAIlF,2EAA2E;AAC3E,4DAA4D;AAE5D;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAe,EAAE,GAAQ;IAC/C,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;AAClF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,GAAY,EAAE,MAAW;IACrD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,CAAC,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACxF,OAAO,KAAK,CAAC;IAChB,CAAC;IACD,OAAO,CAAC,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,CAAC,MAAM,CAAC;AACzD,CAAC"}

package/lib/langium/workspace/file-system-provider.d.ts

@@ -8,15 +8,92 @@
  ********************************************************************************/
 import { type Tracer } from '@hydranium/protocol';
 import { EmptyFileSystemProvider } from '@hydranium/langium';
-import type { URI } from '@hydranium/langium';
-import { type WritableFileSystemProvider } from '../../documents/ast-document-manager.js';
+import type { FileSystemNode, FileSystemProvider, URI } from '@hydranium/langium';
+import { type SelfSaveRegistry } from './self-save-registry.js';
 import { type LogNameOptions } from '../diagnostics/logger.js';
 import { type ServerSharedServicesMinimal } from '../shared-services.js';
 /**
- * Empty-filesystem default {@link WritableFileSystemProvider}. For
- * in-memory / browser / test / CLI hosts that don't have a real filesystem.
- * All writes are no-ops. This is the portable `.`-entry default; the
- * Node-backed `DefaultFileSystemProvider`
+ * File-system provider extension that supports writes. Langium's standard
+ * {@link FileSystemProvider} is read-only; `AstDocumentManager` needs to persist
+ * saves, so consumers wire in a provider that implements this superset.
+ *
+ * Implementations may optionally hold a reference to a
+ * {@link SelfSaveRegistry} so they can record their own write mtimes and
+ * help downstream file-watchers suppress echo events for those writes.
+ * The framework's `DefaultFileSystemProvider` reads it from
+ * `services.workspace.SelfSaveRegistry`; alternative implementations can do
+ * the same or leave the field unset.
+ */
+export interface WritableFileSystemProvider extends FileSystemProvider {
+    writeFile(uri: URI, content: string): Promise<void>;
+    /**
+     * Remove the file at `uri`: the name the URI gives, never the file a
+     * symlink there points at, leaving a parent directory it empties in place.
+     * A no-op when nothing is there; a directory is refused.
+     */
+    deleteFile(uri: URI): Promise<void>;
+    /**
+     * Last-modified time (ms) of the file at `uri`, or `undefined` if it can't
+     * be determined (missing file, or a provider with no disk — in-memory /
+     * browser). Optional: the only consumer is self-save echo suppression
+     * (`didChangeWatchedFiles`), which simply lets a change through when the
+     * mtime is unavailable. Distinct from Langium's `stat` (whose
+     * `FileSystemNode` carries no mtime). Keeping disk access on the provider
+     * seam is what lets the LSP update handler avoid a direct `node:fs` import.
+     */
+    mtimeMs?(uri: URI): Promise<number | undefined>;
+    /**
+     * Resolve `uri` to its real on-disk identity (symlinks collapsed, `..`/`.`
+     * walked, case-folded on case-insensitive filesystems), or `undefined` *iff
+     * the filesystem knows the path is absent*. The single source of the
+     * "nothing loadable here" signal `RealpathDocumentUriPolicy` turns into
+     * the synthetic-placeholder branch of `getOrCreateDocument`.
+     *
+     * Contract for implementers:
+     * - A `file:`-backed provider returns the resolved URI when the file exists,
+     *   and `undefined` when it cannot resolve the path (missing / unreadable).
+     * - A non-`file:` URI (or any URI the provider cannot stat) passes through
+     *   **unchanged** — it is treated as present, never reported absent.
+     * - A provider with no disk to check (in-memory / browser / empty) simply
+     *   omits this method; the framework's `FileSystemProviderRegistry` then
+     *   returns the URI unchanged, and `RealpathDocumentUriPolicy` answers as
+     *   the syntactic `DefaultDocumentUriPolicy` does.
+     *
+     * Synchronous (a `realpath` is a kernel-cached syscall) and optional — the
+     * only consumers are the document-identity policy's `canonicalUri`/`loadUri`.
+     * Keeping the syscall on the provider seam is what lets the policy stay
+     * browser-neutral (no `node:fs` import).
+     */
+    realpath?(uri: URI): URI | undefined;
+    /**
+     * The path `uri` names with every link followed, a link to nothing
+     * included, so that `RealpathDocumentUriPolicy.canonicalUri` keys a file
+     * reached through a link the same before it exists and once it does.
+     * Where {@link realpath} resolves, the same answer; otherwise what is
+     * missing joined as spelled under the real path of what exists. Optional,
+     * as `realpath` is: without it an absent path keys by its syntactic form.
+     */
+    resolveLinks?(uri: URI): URI;
+    /**
+     * Whether a file is at `uri`, where a miss counts only once it has lasted:
+     * on a disk where replacing a file can hide its name for a moment, a single
+     * {@link exists} cannot tell that from a deletion. Ask this before acting on
+     * a miss as a deletion; a caller expecting a miss, such as a create, asks
+     * {@link exists}, since here a real miss costs the whole wait.
+     *
+     * Optional: a provider whose misses are always final omits it, and a caller
+     * takes the answer of {@link exists} as settled.
+     */
+    existsSettled?(uri: URI): Promise<boolean>;
+    /** Registry the provider records its own writes against. Optional — providers without watcher integration may omit. */
+    readonly selfSaveRegistry?: SelfSaveRegistry;
+}
+/**
+ * Empty-filesystem {@link WritableFileSystemProvider}. For browser / test / CLI
+ * hosts that don't have a real filesystem. All writes and deletes are no-ops.
+ * On the portable `.` entry it is the
+ * {@link FileSystemProviderRegistry.host} when `context.fileSystemProvider`
+ * gives no writable provider; the Node-backed `DefaultFileSystemProvider`
  * lives in `@hydranium/core/node` (it pulls `node:fs`).
  */
 export declare class DefaultEmptyFileSystemProvider extends EmptyFileSystemProvider implements WritableFileSystemProvider {
@@ -24,7 +101,87 @@ export declare class DefaultEmptyFileSystemProvider extends EmptyFileSystemProvi
     protected readonly tracer: Tracer;
     constructor(services: ServerSharedServicesMinimal, options?: LogNameOptions);
     writeFile(_uri: URI, _content: string): Promise<void>;
-    readFile(uri?: URI): Promise<string>;
-    readFileSync(uri?: URI): string;
+    deleteFile(_uri: URI): Promise<void>;
+    readFile(_uri?: URI): Promise<string>;
+    readBinary(_uri?: URI): Promise<Uint8Array>;
+    stat(uri: URI): Promise<FileSystemNode>;
+}
+/**
+ * The provider bound on `workspace.FileSystemProvider`: it dispatches each call
+ * by the URI's scheme to the provider registered for it in the shared
+ * `fileSystemProviders` group, and to the {@link host} for any scheme without
+ * one.
+ *
+ * So one provider answers for each scheme, and a host's provider needs to know
+ * only its own: the framework registers `virtual:` there, and an adopter adds a
+ * scheme by contributing to the group. The host takes every unclaimed scheme
+ * rather than `file:` alone, which keeps an in-memory workspace under `memory:`
+ * or any other scheme on the host's provider.
+ *
+ * `THost` types the host, so an adopter whose own provider has more members
+ * than the base declares the slot as `FileSystemProviderRegistry<MyProvider>`,
+ * binds a {@link DefaultFileSystemProviderRegistry} with that host, and reads
+ * those members through `services.workspace.FileSystemProvider.host`.
+ */
+export interface FileSystemProviderRegistry<THost extends WritableFileSystemProvider = WritableFileSystemProvider> extends WritableFileSystemProvider {
+    /** The provider for every scheme no entry of `fileSystemProviders` claims. */
+    readonly host: THost;
+    /** The provider that answers for `uri`. */
+    providerFor(uri: URI): WritableFileSystemProvider;
+}
+/** Options for {@link DefaultFileSystemProviderRegistry}. */
+export interface FileSystemProviderRegistryOptions<THost extends WritableFileSystemProvider = WritableFileSystemProvider> extends LogNameOptions {
+    /**
+     * The provider for every scheme no entry of `fileSystemProviders` claims.
+     * The framework passes the provider `context.fileSystemProvider` returns,
+     * or a {@link DefaultEmptyFileSystemProvider} when that is not writable.
+     */
+    host: THost;
+}
+/**
+ * The framework's {@link FileSystemProviderRegistry}.
+ *
+ * A directory is listed by the provider of its own scheme, so a workspace
+ * root's tree comes from that provider alone.
+ *
+ * `realpath`, `resolveLinks`, `mtimeMs` and `existsSettled` are always present
+ * and forward to the scheme's provider. Where that provider lacks one,
+ * `realpath` and `resolveLinks` return the URI unchanged, `mtimeMs` returns
+ * `undefined` and `existsSettled` answers as `exists`: the answers their
+ * callers already give a provider without them.
+ */
+export declare class DefaultFileSystemProviderRegistry<THost extends WritableFileSystemProvider = WritableFileSystemProvider> implements FileSystemProviderRegistry<THost> {
+    protected readonly services: ServerSharedServicesMinimal & {
+        fileSystemProviders: Record<string, WritableFileSystemProvider>;
+    };
+    readonly host: THost;
+    protected readonly tracer: Tracer;
+    constructor(services: ServerSharedServicesMinimal & {
+        fileSystemProviders: Record<string, WritableFileSystemProvider>;
+    }, options: FileSystemProviderRegistryOptions<THost>);
+    /**
+     * The group is read per call, not in the constructor, so a registered
+     * provider is built on first use and may read slots that reach back to this
+     * one. Only an OWN key of the group counts: the DI container resolves any
+     * key found on the prototype chain, so a scheme such as `constructor` would
+     * otherwise dispatch to a function.
+     */
+    providerFor(uri: URI): WritableFileSystemProvider;
+    writeFile(uri: URI, content: string): Promise<void>;
+    deleteFile(uri: URI): Promise<void>;
+    mtimeMs(uri: URI): Promise<number | undefined>;
+    realpath(uri: URI): URI | undefined;
+    resolveLinks(uri: URI): URI;
+    existsSettled(uri: URI): Promise<boolean>;
+    stat(uri: URI): Promise<FileSystemNode>;
+    statSync(uri: URI): FileSystemNode;
+    exists(uri: URI): Promise<boolean>;
+    existsSync(uri: URI): boolean;
+    readBinary(uri: URI): Promise<Uint8Array>;
+    readBinarySync(uri: URI): Uint8Array;
+    readFile(uri: URI): Promise<string>;
+    readFileSync(uri: URI): string;
+    readDirectory(uri: URI): Promise<FileSystemNode[]>;
+    readDirectorySync(uri: URI): FileSystemNode[];
 }
 //# sourceMappingURL=file-system-provider.d.ts.map

package/lib/langium/workspace/file-system-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-system-provider.d.ts","sourceRoot":"","sources":["../../../src/langium/workspace/file-system-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,KAAK,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AAC1F,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAGzE;;;;;;GAMG;AACH,qBAAa,8BAA+B,SAAQ,uBAAwB,YAAW,0BAA0B;IAI3G,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,2BAA2B;IAH3D,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAGZ,QAAQ,EAAE,2BAA2B,EACxD,OAAO,GAAE,cAAmB;IAMzB,SAAS,CAAC,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOlD,QAAQ,CAAC,GAAG,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC;IAKpC,YAAY,CAAC,GAAG,CAAC,EAAE,GAAG,GAAG,MAAM;CAI1C"}
+{"version":3,"file":"file-system-provider.d.ts","sourceRoot":"","sources":["../../../src/langium/workspace/file-system-provider.ts"],"names":[],"mappings":"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"}

package/lib/langium/workspace/file-system-provider.js

@@ -7,12 +7,12 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 import { EmptyFileSystemProvider } from '@hydranium/langium';
-import { serveVirtualDocument } from './virtual-document.js';
 /**
- * Empty-filesystem default {@link WritableFileSystemProvider}. For
- * in-memory / browser / test / CLI hosts that don't have a real filesystem.
- * All writes are no-ops. This is the portable `.`-entry default; the
- * Node-backed `DefaultFileSystemProvider`
+ * Empty-filesystem {@link WritableFileSystemProvider}. For browser / test / CLI
+ * hosts that don't have a real filesystem. All writes and deletes are no-ops.
+ * On the portable `.` entry it is the
+ * {@link FileSystemProviderRegistry.host} when `context.fileSystemProvider`
+ * gives no writable provider; the Node-backed `DefaultFileSystemProvider`
  * lives in `@hydranium/core/node` (it pulls `node:fs`).
  */
 export class DefaultEmptyFileSystemProvider extends EmptyFileSystemProvider {
@@ -26,16 +26,114 @@ export class DefaultEmptyFileSystemProvider extends EmptyFileSystemProvider {
     async writeFile(_uri, _content) {
         // no-op
     }
-    // Serve virtual documents from the registered document (there is no disk to
-    // read); delegate everything else to the empty base (which throws). The
-    // base declares these param-less, so the param is optional here.
-    readFile(uri) {
-        const served = uri !== undefined ? serveVirtualDocument(this.services, uri) : undefined;
-        return served !== undefined ? Promise.resolve(served) : super.readFile();
+    async deleteFile(_uri) {
+        // no-op
+    }
+    // `async` so the base's refusal becomes a rejection: it throws
+    // SYNCHRONOUSLY from a method declared to return a promise, and a
+    // synchronous throw escapes the promise chain — `.catch()` never attaches
+    // and `Promise.all` dies while its argument array is still being built, so
+    // a caller reading several URIs cannot handle the miss it asked about. The
+    // base declares `readFile` and `readBinary` param-less, so the param is
+    // optional there.
+    async readFile(_uri) {
+        return super.readFile();
+    }
+    async readBinary(_uri) {
+        return super.readBinary();
+    }
+    async stat(uri) {
+        return super.stat(uri);
+    }
+}
+/**
+ * The framework's {@link FileSystemProviderRegistry}.
+ *
+ * A directory is listed by the provider of its own scheme, so a workspace
+ * root's tree comes from that provider alone.
+ *
+ * `realpath`, `resolveLinks`, `mtimeMs` and `existsSettled` are always present
+ * and forward to the scheme's provider. Where that provider lacks one,
+ * `realpath` and `resolveLinks` return the URI unchanged, `mtimeMs` returns
+ * `undefined` and `existsSettled` answers as `exists`: the answers their
+ * callers already give a provider without them.
+ */
+export class DefaultFileSystemProviderRegistry {
+    services;
+    host;
+    tracer;
+    constructor(services, options) {
+        this.services = services;
+        this.host = options.host;
+        this.tracer = services.Tracer.for(options.logName ?? this.constructor.name).trace('instantiated');
+    }
+    /**
+     * The group is read per call, not in the constructor, so a registered
+     * provider is built on first use and may read slots that reach back to this
+     * one. Only an OWN key of the group counts: the DI container resolves any
+     * key found on the prototype chain, so a scheme such as `constructor` would
+     * otherwise dispatch to a function.
+     */
+    providerFor(uri) {
+        const providers = this.services.fileSystemProviders;
+        return Object.hasOwn(providers, uri.scheme) ? providers[uri.scheme] : this.host;
+    }
+    // The async methods are `async` so a provider that throws synchronously from
+    // one still rejects, for the reason `DefaultEmptyFileSystemProvider` gives.
+    async writeFile(uri, content) {
+        return this.providerFor(uri).writeFile(uri, content);
+    }
+    async deleteFile(uri) {
+        return this.providerFor(uri).deleteFile(uri);
+    }
+    async mtimeMs(uri) {
+        return this.providerFor(uri).mtimeMs?.(uri);
+    }
+    realpath(uri) {
+        const provider = this.providerFor(uri);
+        return provider.realpath ? provider.realpath(uri) : uri;
+    }
+    resolveLinks(uri) {
+        const provider = this.providerFor(uri);
+        if (provider.resolveLinks) {
+            return provider.resolveLinks(uri);
+        }
+        // A provider with `realpath` alone still keys a present path by it.
+        return provider.realpath?.(uri) ?? uri;
+    }
+    async existsSettled(uri) {
+        const provider = this.providerFor(uri);
+        return provider.existsSettled ? provider.existsSettled(uri) : provider.exists(uri);
+    }
+    async stat(uri) {
+        return this.providerFor(uri).stat(uri);
+    }
+    statSync(uri) {
+        return this.providerFor(uri).statSync(uri);
+    }
+    async exists(uri) {
+        return this.providerFor(uri).exists(uri);
+    }
+    existsSync(uri) {
+        return this.providerFor(uri).existsSync(uri);
+    }
+    async readBinary(uri) {
+        return this.providerFor(uri).readBinary(uri);
+    }
+    readBinarySync(uri) {
+        return this.providerFor(uri).readBinarySync(uri);
+    }
+    async readFile(uri) {
+        return this.providerFor(uri).readFile(uri);
     }
     readFileSync(uri) {
-        const served = uri !== undefined ? serveVirtualDocument(this.services, uri) : undefined;
-        return served !== undefined ? served : super.readFileSync();
+        return this.providerFor(uri).readFileSync(uri);
+    }
+    async readDirectory(uri) {
+        return this.providerFor(uri).readDirectory(uri);
+    }
+    readDirectorySync(uri) {
+        return this.providerFor(uri).readDirectorySync(uri);
     }
 }
 //# sourceMappingURL=file-system-provider.js.map

package/lib/langium/workspace/file-system-provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"file-system-provider.js","sourceRoot":"","sources":["../../../src/langium/workspace/file-system-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAGlF,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAK7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAE7D;;;;;;GAMG;AACH,MAAM,OAAO,8BAA+B,SAAQ,uBAAuB;IAIlD;IAHH,MAAM,CAAS;IAElC,YACsB,QAAqC,EACxD,UAA0B,EAAE;QAE5B,KAAK,EAAE,CAAC;QAHW,aAAQ,GAAR,QAAQ,CAA6B;QAIxD,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IACrG,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,IAAS,EAAE,QAAgB;QACxC,QAAQ;IACX,CAAC;IAED,4EAA4E;IAC5E,wEAAwE;IACxE,iEAAiE;IACxD,QAAQ,CAAC,GAAS;QACxB,MAAM,MAAM,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,oBAAoB,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACxF,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;IAC5E,CAAC;IAEQ,YAAY,CAAC,GAAS;QAC5B,MAAM,MAAM,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,oBAAoB,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACxF,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC;IAC/D,CAAC;CACH"}
+{"version":3,"file":"file-system-provider.js","sourceRoot":"","sources":["../../../src/langium/workspace/file-system-provider.ts"],"names":[],"mappings":"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"}

package/lib/langium/workspace/hydranium-langium-document-factory.d.ts

@@ -6,8 +6,13 @@
  *
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
-import { type AstNode, DefaultLangiumDocumentFactory, type LangiumDocument, type URI } from '@hydranium/langium';
+import { type AstNode, DefaultLangiumDocumentFactory, type LangiumDocument, type Mutable, type ParseResult, type URI } from '@hydranium/langium';
+import { type CancellationToken } from 'vscode-languageserver-protocol';
+import { type TextDocument } from 'vscode-languageserver-textdocument';
+import { type ModelLedger } from '../../documents/model-ledger.js';
+import { type VersionSyncService } from '../../documents/version-sync-service.js';
 import { type ExtendedServiceRegistry } from '../service-registry.js';
+import { type ServerSharedServicesMinimal } from '../shared-services.js';
 /**
  * Framework `LangiumDocumentFactory` that fills in the one thing Langium
  * leaves empty for a code-built document: its text.
@@ -41,6 +46,10 @@ export declare class HydraniumLangiumDocumentFactory extends DefaultLangiumDocum
      * per-callsite cast. The framework's shared module binds that class.
      */
     protected readonly serviceRegistry: ExtendedServiceRegistry;
+    /** Resolved per call: the sync service reaches the registry, which is built with this factory. */
+    protected readonly versionSyncService: () => VersionSyncService;
+    protected readonly modelLedger: () => ModelLedger;
+    constructor(services: ServerSharedServicesMinimal);
     /**
      * Parse `text` for `uri` under the grammar `languageId` names, instead of
      * the one `uri` routes to.
@@ -60,6 +69,27 @@ export declare class HydraniumLangiumDocumentFactory extends DefaultLangiumDocum
      */
     fromStringInLanguage<T extends AstNode = AstNode>(text: string, uri: URI, languageId: string): LangiumDocument<T>;
     fromModel<T extends AstNode = AstNode>(model: T, uri: URI): LangiumDocument<T>;
+    protected createLangiumDocument<T extends AstNode = AstNode>(parseResult: ParseResult<T>, uri: URI, textDocument?: TextDocument, text?: string): LangiumDocument<T>;
+    /**
+     * The version is read before the parse, for the same reason as in
+     * {@link update}: the text document is the store's, which an edit updates
+     * in place while the parse runs.
+     */
+    protected createAsync<T extends AstNode = AstNode>(uri: URI, content: string | TextDocument, cancelToken: CancellationToken): Promise<LangiumDocument<T>>;
+    /**
+     * The store's version is read before Langium's `update`, which reads the
+     * store's text before its first await: read after, it can belong to an
+     * edit that arrived while the parse ran.
+     *
+     * Reconciled with the store here rather than in a `Parsed` listener, which
+     * a cancel skips, leaving the root on the version of its earlier text.
+     */
+    update<T extends AstNode = AstNode>(document: Mutable<LangiumDocument<T>>, cancellationToken: CancellationToken): Promise<LangiumDocument<T>>;
+    /**
+     * `version`, or {@link STALE_VERSION} when the store holds `uri` open with
+     * other text than `parsed`: text read from the file while an open landed.
+     */
+    protected versionOfParsedText(uri: URI, parsed: string | undefined, version: number): number;
     /**
      * Serialize `model` via the per-language serializer, or `undefined` if none
      * is bound, it fails, or it is async — `fromModel` is synchronous, so an