@hydranium/core 1.0.0-next.10

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

@@ -0,0 +1,151 @@
+/********************************************************************************
+ * 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 CanonicalUri } from '@hydranium/protocol';
+import { type URI } from '@hydranium/langium';
+import { type ServerSharedServicesMinimal } from '../shared-services.js';
+/**
+ * The slice of the filesystem provider {@link RealpathDocumentUriPolicy}
+ * consults — just the optional `realpath` primitive. Declared locally so the
+ * workspace-layer policy stays decoupled from the documents-layer
+ * `WritableFileSystemProvider`; the production binding (the Node
+ * `DefaultFileSystemProvider`) supplies the method, an in-memory / browser
+ * provider omits it (and the policy then degrades to the syntactic default).
+ */
+export interface RealpathCapableFileSystem {
+    realpath?(uri: URI): URI | undefined;
+}
+/**
+ * Report whether `uri`'s real on-disk path differs from its syntactic
+ * normalisation — the condition under which a language client's URI (`S`)
+ * diverges from the canonical document identity (`R`) the build keys by.
+ * Returns the resolved real URI when they differ, else
+ * `undefined` (non-divergent, absent, or a provider with no `realpath`).
+ *
+ * A diagnostic primitive, not part of the keying path: the
+ * `HydraniumWorkspaceManager` runs it once over the workspace roots at
+ * startup to surface "this workspace path resolves through a symlink/`..`/case
+ * variant, so client URIs will diverge from canonical identity" — the empirical
+ * answer to whether the divergence machinery is exercised in a given deployment
+ * (a plain on-disk workspace yields nothing).
+ */
+export declare function findRealpathDivergence(uri: URI | string, fs: RealpathCapableFileSystem): URI | undefined;
+/**
+ * The workspace's URI-interpretation strategy — how the framework turns an
+ * arbitrary incoming URI into the two identities every layer must agree on.
+ * Two related-but-distinct operations:
+ *
+ * - {@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
+ *   `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
+ *   unchanged); a real-path policy returns the resolved file URI, or `undefined`
+ *   for a not-yet-written path.
+ *
+ * The framework default ({@link DefaultDocumentUriPolicy}) is Langium's
+ * syntactic `UriUtils.normalize`, which matches Langium's
+ * `DefaultLangiumDocuments` keying. Adopters that strengthen document identity
+ * — e.g. resolving symlinks / linked files to their real path — bind
+ * {@link RealpathDocumentUriPolicy}, or their own equivalent, so every layer
+ * keys by the same stronger form. Otherwise the layers disagree: a subscriber
+ * that opened a *symlinked* file would receive save events but silently no
+ * update events because the text-store URI and the `LangiumDocument` URI for
+ * the same file diverge.
+ *
+ * Contract: `canonicalUri` MUST be idempotent —
+ * `canonicalUri(canonicalUri(u)) === canonicalUri(u)` — because callers feed
+ * it URIs that may already be canonical (e.g. a `LangiumDocument.uri` straight
+ * off the build pipeline).
+ */
+export interface DocumentUriPolicy {
+    canonicalUri(uri: URI | string): CanonicalUri;
+    /**
+     * 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.
+     */
+    loadUri(uri: URI | string): URI | undefined;
+}
+/**
+ * Framework default: Langium's syntactic normalisation. Pure and
+ * filesystem-free, so it is browser-safe and matches `DefaultLangiumDocuments`
+ * keying. Adopters resolving symlinks bind {@link RealpathDocumentUriPolicy}
+ * (or their own equivalent) instead.
+ */
+export declare class DefaultDocumentUriPolicy implements DocumentUriPolicy {
+    canonicalUri(uri: URI | string): CanonicalUri;
+    /**
+     * No filesystem access, so existence cannot be checked — every URI is
+     * treated as loadable and returned unchanged. A later load that misses
+     * therefore reaches the filesystem and throws, which
+     * `AbstractHydraniumLangiumDocuments.getOrCreateDocument` absorbs into its
+     * empty-document fallback: under this policy that fallback, not this method,
+     * is what makes a missing file a placeholder rather than an error.
+     */
+    loadUri(uri: URI | string): URI | undefined;
+}
+/**
+ * {@link DocumentUriPolicy} for adopters whose document identity is the real
+ * on-disk path: resolves `file:` URIs through the `FileSystemProvider`'s
+ * `realpath` primitive so a symlinked file and its target collapse to one
+ * canonical key. Bind this and the single seam drives `LangiumDocuments`
+ * keying, the AST-document event filters, and the document builder's directory
+ * flattening all at once.
+ *
+ * ## What this adds over the {@link DefaultDocumentUriPolicy} (`UriUtils.normalize`)
+ *
+ * `normalize` is purely *syntactic*: it parses and re-serialises the URI string
+ * (lower-cases the scheme, regularises percent-encoding and separators). It is
+ * pure, filesystem-free, and browser-safe — but it knows nothing about the disk,
+ * so two strings that denote the *same file* through different paths stay
+ * distinct keys. This policy is the filesystem-backed strengthening; for `file:`
+ * URIs it additionally:
+ *
+ * - **Collapses symlinks** to their target — the headline reason to bind it. A
+ *   symlinked file (or a file reached through a symlinked directory) and its
+ *   real path become one document instead of two divergent identities.
+ * - **Resolves `..` / `.` segments** — `realpath` walks the real path, so
+ *   `/ws/sub/../a.txt` folds to `/ws/a.txt`; `normalize` leaves dot segments as-is.
+ * - **Case-folds on case-insensitive filesystems** (macOS / Windows): `realpath`
+ *   returns the actual on-disk casing, so `/Foo/x.txt` and `/foo/x.txt` collapse to
+ *   one key. `normalize` keeps them distinct — which on those platforms would
+ *   register one physical file as two documents.
+ *
+ * ## Delegation, not a syscall
+ *
+ * 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).
+ *
+ * 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.
+ */
+export declare class RealpathDocumentUriPolicy extends DefaultDocumentUriPolicy {
+    protected readonly fs: RealpathCapableFileSystem;
+    constructor(services: ServerSharedServicesMinimal);
+    canonicalUri(uri: URI | string): CanonicalUri;
+    loadUri(uri: URI | string): URI | undefined;
+}
+//# sourceMappingURL=document-uri-policy.d.ts.map

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

@@ -0,0 +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;;;;;;;OAOG;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"}

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

@@ -0,0 +1,121 @@
+/********************************************************************************
+ * 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 { asCanonicalUri } from '@hydranium/protocol';
+import { UriUtils } from '@hydranium/langium';
+/**
+ * Report whether `uri`'s real on-disk path differs from its syntactic
+ * normalisation — the condition under which a language client's URI (`S`)
+ * diverges from the canonical document identity (`R`) the build keys by.
+ * Returns the resolved real URI when they differ, else
+ * `undefined` (non-divergent, absent, or a provider with no `realpath`).
+ *
+ * A diagnostic primitive, not part of the keying path: the
+ * `HydraniumWorkspaceManager` runs it once over the workspace roots at
+ * startup to surface "this workspace path resolves through a symlink/`..`/case
+ * variant, so client URIs will diverge from canonical identity" — the empirical
+ * answer to whether the divergence machinery is exercised in a given deployment
+ * (a plain on-disk workspace yields nothing).
+ */
+export function findRealpathDivergence(uri, fs) {
+    const parsed = UriUtils.toUri(uri);
+    const real = parsed && fs.realpath?.(parsed);
+    return real && UriUtils.normalize(real) !== UriUtils.normalize(uri) ? real : undefined;
+}
+/**
+ * Framework default: Langium's syntactic normalisation. Pure and
+ * filesystem-free, so it is browser-safe and matches `DefaultLangiumDocuments`
+ * keying. Adopters resolving symlinks bind {@link RealpathDocumentUriPolicy}
+ * (or their own equivalent) instead.
+ */
+export class DefaultDocumentUriPolicy {
+    canonicalUri(uri) {
+        // Mint point: the sole place a CanonicalUri is created under the default
+        // (syntactic) policy. `asCanonicalUri` is the brand mint — see CanonicalUri.
+        return asCanonicalUri(UriUtils.normalize(uri));
+    }
+    /**
+     * No filesystem access, so existence cannot be checked — every URI is
+     * treated as loadable and returned unchanged. A later load that misses
+     * therefore reaches the filesystem and throws, which
+     * `AbstractHydraniumLangiumDocuments.getOrCreateDocument` absorbs into its
+     * empty-document fallback: under this policy that fallback, not this method,
+     * is what makes a missing file a placeholder rather than an error.
+     */
+    loadUri(uri) {
+        return UriUtils.toUri(uri);
+    }
+}
+/**
+ * {@link DocumentUriPolicy} for adopters whose document identity is the real
+ * on-disk path: resolves `file:` URIs through the `FileSystemProvider`'s
+ * `realpath` primitive so a symlinked file and its target collapse to one
+ * canonical key. Bind this and the single seam drives `LangiumDocuments`
+ * keying, the AST-document event filters, and the document builder's directory
+ * flattening all at once.
+ *
+ * ## What this adds over the {@link DefaultDocumentUriPolicy} (`UriUtils.normalize`)
+ *
+ * `normalize` is purely *syntactic*: it parses and re-serialises the URI string
+ * (lower-cases the scheme, regularises percent-encoding and separators). It is
+ * pure, filesystem-free, and browser-safe — but it knows nothing about the disk,
+ * so two strings that denote the *same file* through different paths stay
+ * distinct keys. This policy is the filesystem-backed strengthening; for `file:`
+ * URIs it additionally:
+ *
+ * - **Collapses symlinks** to their target — the headline reason to bind it. A
+ *   symlinked file (or a file reached through a symlinked directory) and its
+ *   real path become one document instead of two divergent identities.
+ * - **Resolves `..` / `.` segments** — `realpath` walks the real path, so
+ *   `/ws/sub/../a.txt` folds to `/ws/a.txt`; `normalize` leaves dot segments as-is.
+ * - **Case-folds on case-insensitive filesystems** (macOS / Windows): `realpath`
+ *   returns the actual on-disk casing, so `/Foo/x.txt` and `/foo/x.txt` collapse to
+ *   one key. `normalize` keeps them distinct — which on those platforms would
+ *   register one physical file as two documents.
+ *
+ * ## Delegation, not a syscall
+ *
+ * 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).
+ *
+ * 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.
+ */
+export class RealpathDocumentUriPolicy extends DefaultDocumentUriPolicy {
+    fs;
+    constructor(services) {
+        super();
+        this.fs = services.workspace.FileSystemProvider;
+    }
+    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.
+        return real ? asCanonicalUri(UriUtils.normalize(real)) : super.canonicalUri(uri);
+    }
+    loadUri(uri) {
+        if (!this.fs.realpath) {
+            return super.loadUri(uri);
+        }
+        const parsed = UriUtils.toUri(uri);
+        // `realpath` present: a real path resolves, an absent one returns
+        // `undefined` (the skip signal). A non-parseable URI has no load target.
+        return parsed ? this.fs.realpath(parsed) : parsed;
+    }
+}
+//# sourceMappingURL=document-uri-policy.js.map

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

@@ -0,0 +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;;;;;;;OAOG;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"}

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

@@ -0,0 +1,30 @@
+/********************************************************************************
+ * 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 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 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`
+ * lives in `@hydranium/core/node` (it pulls `node:fs`).
+ */
+export declare class DefaultEmptyFileSystemProvider extends EmptyFileSystemProvider implements WritableFileSystemProvider {
+    protected readonly services: ServerSharedServicesMinimal;
+    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;
+}
+//# sourceMappingURL=file-system-provider.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,41 @@
+/********************************************************************************
+ * 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 { 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`
+ * lives in `@hydranium/core/node` (it pulls `node:fs`).
+ */
+export class DefaultEmptyFileSystemProvider extends EmptyFileSystemProvider {
+    services;
+    tracer;
+    constructor(services, options = {}) {
+        super();
+        this.services = services;
+        this.tracer = services.Tracer.for(options.logName ?? this.constructor.name).trace('instantiated');
+    }
+    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();
+    }
+    readFileSync(uri) {
+        const served = uri !== undefined ? serveVirtualDocument(this.services, uri) : undefined;
+        return served !== undefined ? served : super.readFileSync();
+    }
+}
+//# sourceMappingURL=file-system-provider.js.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,45 @@
+/********************************************************************************
+ * 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 AstNode, DefaultLangiumDocumentFactory, type LangiumDocument, type URI } from '@hydranium/langium';
+/**
+ * Framework `LangiumDocumentFactory` that fills in the one thing Langium
+ * leaves empty for a code-built document: its text.
+ *
+ * Langium's `fromModel` produces a document with no text (Langium core has no
+ * generic serializer), so a virtual document built from a model cannot be
+ * re-read. The framework *does* have a per-language `Serializer`, so this
+ * override serializes the model once at creation and retains the result as the
+ * document's text — while keeping the ORIGINAL model object as the AST, so node
+ * identity survives: adopters holding references to their stdlib nodes, and the
+ * scope descriptions pointing at them, stay valid. A `fromString` document
+ * already carries its source, so only `fromModel` needs help.
+ *
+ * Degrades to Langium's text-less `fromModel` when no serializer is bound for
+ * the URI's language (the serializer throws or is absent) — the document still
+ * works; only a re-read of it would yield empty text, which never happens for a
+ * build-once virtual document.
+ *
+ * Also links the model's container properties (`$container` /
+ * `$containerProperty` / `$containerIndex`), which Langium's parser sets via
+ * `linkContentToContainer` but `fromModel` skips. Without them the
+ * `AstNodeLocator` can't compute node paths, so indexing the document — the
+ * point of contributing it as an additional/virtual document — yields broken
+ * paths and cross-references into it fail to resolve. Linking is in place, so
+ * node identity is preserved.
+ */
+export declare class HydraniumLangiumDocumentFactory extends DefaultLangiumDocumentFactory {
+    fromModel<T extends AstNode = AstNode>(model: T, uri: URI): LangiumDocument<T>;
+    /**
+     * Serialize `model` via the per-language serializer, or `undefined` if none
+     * is bound, it fails, or it is async — `fromModel` is synchronous, so an
+     * async serializer degrades to a text-less document rather than blocking.
+     */
+    protected serializeModel(model: AstNode, uri: URI): string | undefined;
+}
+//# sourceMappingURL=hydranium-langium-document-factory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hydranium-langium-document-factory.d.ts","sourceRoot":"","sources":["../../../src/langium/workspace/hydranium-langium-document-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EACJ,KAAK,OAAO,EAEZ,6BAA6B,EAC7B,KAAK,eAAe,EAEpB,KAAK,GAAG,EACV,MAAM,oBAAoB,CAAC;AAQ5B;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,+BAAgC,SAAQ,6BAA6B;IACtE,SAAS,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,GAAG,eAAe,CAAC,CAAC,CAAC;IAYvF;;;;OAIG;IACH,SAAS,CAAC,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,SAAS;CASxE"}

package/lib/langium/workspace/hydranium-langium-document-factory.js

@@ -0,0 +1,64 @@
+/********************************************************************************
+ * 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 { AstUtils, DefaultLangiumDocumentFactory } from '@hydranium/langium';
+/**
+ * Framework `LangiumDocumentFactory` that fills in the one thing Langium
+ * leaves empty for a code-built document: its text.
+ *
+ * Langium's `fromModel` produces a document with no text (Langium core has no
+ * generic serializer), so a virtual document built from a model cannot be
+ * re-read. The framework *does* have a per-language `Serializer`, so this
+ * override serializes the model once at creation and retains the result as the
+ * document's text — while keeping the ORIGINAL model object as the AST, so node
+ * identity survives: adopters holding references to their stdlib nodes, and the
+ * scope descriptions pointing at them, stay valid. A `fromString` document
+ * already carries its source, so only `fromModel` needs help.
+ *
+ * Degrades to Langium's text-less `fromModel` when no serializer is bound for
+ * the URI's language (the serializer throws or is absent) — the document still
+ * works; only a re-read of it would yield empty text, which never happens for a
+ * build-once virtual document.
+ *
+ * Also links the model's container properties (`$container` /
+ * `$containerProperty` / `$containerIndex`), which Langium's parser sets via
+ * `linkContentToContainer` but `fromModel` skips. Without them the
+ * `AstNodeLocator` can't compute node paths, so indexing the document — the
+ * point of contributing it as an additional/virtual document — yields broken
+ * paths and cross-references into it fail to resolve. Linking is in place, so
+ * node identity is preserved.
+ */
+export class HydraniumLangiumDocumentFactory extends DefaultLangiumDocumentFactory {
+    fromModel(model, uri) {
+        // Make the code-built AST as structurally complete as a parsed one — the
+        // parser links containers, `fromModel` does not. In place (identity kept).
+        AstUtils.linkContentToContainer(model, { deep: true });
+        const text = this.serializeModel(model, uri);
+        if (text === undefined) {
+            return super.fromModel(model, uri);
+        }
+        const parseResult = { value: model, parserErrors: [], lexerErrors: [] };
+        return this.createLangiumDocument(parseResult, uri, undefined, text);
+    }
+    /**
+     * Serialize `model` via the per-language serializer, or `undefined` if none
+     * is bound, it fails, or it is async — `fromModel` is synchronous, so an
+     * async serializer degrades to a text-less document rather than blocking.
+     */
+    serializeModel(model, uri) {
+        try {
+            const services = this.serviceRegistry.getServices(uri);
+            const serialized = services.serializer?.Serializer?.serializeAst(model);
+            return typeof serialized === 'string' ? serialized : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+//# sourceMappingURL=hydranium-langium-document-factory.js.map

package/lib/langium/workspace/hydranium-langium-document-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydranium-langium-document-factory.js","sourceRoot":"","sources":["../../../src/langium/workspace/hydranium-langium-document-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAEJ,QAAQ,EACR,6BAA6B,EAI/B,MAAM,oBAAoB,CAAC;AAQ5B;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,OAAO,+BAAgC,SAAQ,6BAA6B;IACtE,SAAS,CAA8B,KAAQ,EAAE,GAAQ;QAC/D,yEAAyE;QACzE,2EAA2E;QAC3E,QAAQ,CAAC,sBAAsB,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACvD,MAAM,IAAI,GAAG,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC7C,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACtB,OAAO,KAAK,CAAC,SAAS,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QACtC,CAAC;QACD,MAAM,WAAW,GAAmB,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;QACxF,OAAO,IAAI,CAAC,qBAAqB,CAAI,WAAW,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;IAC3E,CAAC;IAED;;;;OAIG;IACO,cAAc,CAAC,KAAc,EAAE,GAAQ;QAC9C,IAAI,CAAC;YACF,MAAM,QAAQ,GAAG,IAAI,CAAC,eAAe,CAAC,WAAW,CAAC,GAAG,CAAmB,CAAC;YACzE,MAAM,UAAU,GAAG,QAAQ,CAAC,UAAU,EAAE,UAAU,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC;YACxE,OAAO,OAAO,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;QAClE,CAAC;QAAC,MAAM,CAAC;YACN,OAAO,SAAS,CAAC;QACpB,CAAC;IACJ,CAAC;CACH"}

package/lib/langium/workspace/hydranium-workspace-lock.d.ts

@@ -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
+ ********************************************************************************/
+import { DefaultWorkspaceLock, type MaybePromise } from '@hydranium/langium';
+import { type CancellationToken } from 'vscode-languageserver-protocol';
+/**
+ * Langium's {@link DefaultWorkspaceLock} with the write action marked as a
+ * write-lock scope, so anything it reaches can be asked whether the lock is
+ * already held (see `isInsideWriteLock`).
+ *
+ * The wrapping has to live HERE rather than at the facade's own `write` call
+ * sites, because the holders worth detecting are mostly not the facade: Langium's
+ * `DefaultWorkspaceManager.initialized` and `DefaultDocumentUpdateHandler` both
+ * take this lock, and the reentrant shape that matters is an integrity rule or
+ * build-phase pass running *inside* one of those builds and writing back through
+ * the facade. Marking the scope at the lock covers every holder, present and
+ * future, including an adopter's own `write` calls.
+ *
+ * `read` is deliberately NOT marked. Read actions do not cancel a running holder,
+ * so reaching the facade from inside one is not the hazard, and marking them
+ * would turn ordinary read-then-write sequences into false positives.
+ */
+export declare class HydraniumWorkspaceLock extends DefaultWorkspaceLock {
+    write(action: (token: CancellationToken) => MaybePromise<void>): Promise<void>;
+}
+//# sourceMappingURL=hydranium-workspace-lock.d.ts.map

package/lib/langium/workspace/hydranium-workspace-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydranium-workspace-lock.d.ts","sourceRoot":"","sources":["../../../src/langium/workspace/hydranium-workspace-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,oBAAoB,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC7E,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAGxE;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,sBAAuB,SAAQ,oBAAoB;IACpD,KAAK,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,YAAY,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAGzF"}

package/lib/langium/workspace/hydranium-workspace-lock.js

@@ -0,0 +1,33 @@
+/********************************************************************************
+ * 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 { DefaultWorkspaceLock } from '@hydranium/langium';
+import { runInWriteLockScope } from './write-lock-scope.js';
+/**
+ * Langium's {@link DefaultWorkspaceLock} with the write action marked as a
+ * write-lock scope, so anything it reaches can be asked whether the lock is
+ * already held (see `isInsideWriteLock`).
+ *
+ * The wrapping has to live HERE rather than at the facade's own `write` call
+ * sites, because the holders worth detecting are mostly not the facade: Langium's
+ * `DefaultWorkspaceManager.initialized` and `DefaultDocumentUpdateHandler` both
+ * take this lock, and the reentrant shape that matters is an integrity rule or
+ * build-phase pass running *inside* one of those builds and writing back through
+ * the facade. Marking the scope at the lock covers every holder, present and
+ * future, including an adopter's own `write` calls.
+ *
+ * `read` is deliberately NOT marked. Read actions do not cancel a running holder,
+ * so reaching the facade from inside one is not the hazard, and marking them
+ * would turn ordinary read-then-write sequences into false positives.
+ */
+export class HydraniumWorkspaceLock extends DefaultWorkspaceLock {
+    write(action) {
+        return super.write(token => runInWriteLockScope(() => action(token)));
+    }
+}
+//# sourceMappingURL=hydranium-workspace-lock.js.map

package/lib/langium/workspace/hydranium-workspace-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydranium-workspace-lock.js","sourceRoot":"","sources":["../../../src/langium/workspace/hydranium-workspace-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,oBAAoB,EAAqB,MAAM,oBAAoB,CAAC;AAE7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAE5D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,sBAAuB,SAAQ,oBAAoB;IACpD,KAAK,CAAC,MAAwD;QACpE,OAAO,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,mBAAmB,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACzE,CAAC;CACH"}