@hydranium/core 1.0.0-next.10

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

@@ -0,0 +1,207 @@
+/********************************************************************************
+ * 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 { URI } from '@hydranium/langium';
+import { type WritableFileSystemProvider } from '../../documents/ast-document-manager.js';
+import { type ServerSharedServicesMinimal } from '../shared-services.js';
+import { type FileSystemSeed, InMemoryFileSystemProvider, type InMemoryFileSystemOptions } from './in-memory-file-system-provider.js';
+/**
+ * An asynchronous key/value store a {@link PersistentFileSystemProvider} mirrors
+ * its writes into and is restored from.
+ *
+ * # Why a store behind the map, rather than a provider over the store
+ *
+ * Langium's `FileSystemProvider` requires SYNCHRONOUS reads — `statSync`,
+ * `existsSync`, `readFileSync`, `readDirectorySync` — and the stores a browser
+ * offers cannot answer synchronously: `IndexedDB` has no sync API at all, and
+ * OPFS has synchronous file handles but still enumerates a directory
+ * asynchronously, so even there a directory index has to be held in memory. A
+ * store therefore cannot back the provider directly, whatever it is. The map
+ * stays the read path and the store is a write-through mirror loaded once,
+ * before the server starts.
+ *
+ * # A key here is a SEED key, not a URI
+ *
+ * Keys are exactly {@link FileSystemSeed} keys: relative to the provider's
+ * `rootUri` when it has one, an absolute URI string when it does not. Two
+ * consequences worth having — a stored workspace reloads under a different
+ * `rootUri` than it was written from, and the seed and the store are the same
+ * key space, so restoring is an overlay rather than a translation step only one
+ * side would remember.
+ *
+ * # Failure is the caller's to see
+ *
+ * Every method may reject, and the provider propagates a rejection out of
+ * `writeFile` rather than absorbing it — a save that reports success for content
+ * no store holds is the failure this seam exists to make impossible. Browser
+ * storage really does fail: a quota is finite, and the user agent may EVICT the
+ * whole origin's storage under pressure or on a "clear site data".
+ */
+export interface FileSystemStore {
+    /**
+     * Everything the store holds. An empty record is the first-visit answer and
+     * not an error, which is what makes the provider's seed the baseline.
+     */
+    load(): Promise<FileSystemSeed>;
+    /**
+     * Store `content` under `path`, replacing any previous content.
+     *
+     * `content` is OPAQUE and must be stored byte for byte: the provider also
+     * writes a deletion marker through here, so a store that validated or
+     * normalised what it was given would turn a delete into a file whose content
+     * is the marker.
+     */
+    write(path: string, content: string): Promise<void>;
+    /** Drop `path`. Storing nothing there already is not an error. */
+    remove(path: string): Promise<void>;
+}
+/** Options for {@link PersistentFileSystemProvider} and {@link persistentFileSystem}. */
+export interface PersistentFileSystemOptions extends InMemoryFileSystemOptions {
+    /** The store writes mirror into and {@link restored} content came out of. */
+    store: FileSystemStore;
+    /**
+     * Content already read out of {@link store}, applied OVER
+     * {@link InMemoryFileSystemOptions.seed} at construction.
+     *
+     * Filled by {@link persistentFileSystem}, which is the supported way in: the
+     * provider is constructed synchronously by the services factory, so a load
+     * cannot happen inside it.
+     */
+    restored?: FileSystemSeed;
+}
+/**
+ * An {@link InMemoryFileSystemProvider} whose writes survive the page: the map
+ * is still the read path, and every write is mirrored into an asynchronous
+ * {@link FileSystemStore} that the next start is restored from.
+ *
+ * # The seed is the baseline and the store is the delta
+ *
+ * A restored entry wins over the seed for the same key; a seeded file the store
+ * has never heard of is served from the seed. So a first visit is the seed
+ * exactly, a returning visit is the seed with the edits laid over it, and a file
+ * the host adds to its seed later appears for a visitor who already has stored
+ * content — which whole-store precedence would have hidden until they cleared
+ * their storage.
+ *
+ * # Deleting a seeded file writes a marker, because dropping its entry would not
+ *
+ * A delta over a baseline cannot express absence by omission: removing the
+ * stored entry for a seeded file returns it to its seeded content on the next
+ * restore, which is a deletion that undoes itself. So {@link deleteFile} stores
+ * a TOMBSTONE for a path the seed carries, and restoring one applies it as a
+ * deletion rather than as content. Re-creating the file is an ordinary write over
+ * the marker, so nothing has to un-mark it.
+ *
+ * A path the seed does NOT carry needs no marker — absence from the store is
+ * already absence — so its entry is removed instead, which is what keeps a host
+ * that creates and deletes scratch files from growing the store forever.
+ *
+ * The marker is a reserved VALUE rather than a reserved key, and that is for the
+ * store's sake: a key is a seed-space path by contract, and a store may map keys
+ * to real filenames, where a reserved key prefix would ask it to create a file
+ * whose name is not a path. As a value it needs nothing from any store. Two
+ * consequences worth knowing: a host that reads the store directly — to count
+ * what is held, say — sees marker entries among the content ones and cannot tell
+ * them apart; and a document whose ENTIRE content is the marker string would be
+ * restored as deleted, which is why the marker is NUL-wrapped and text a grammar
+ * can parse is not.
+ *
+ * # A registered virtual document still wins
+ *
+ * `readFileSync` consults the virtual-document seam before the map, so a stdlib
+ * contributed in code keeps answering for its URI whether or not the store holds
+ * one. The store cannot shadow it, which is what keeps a rebuild that re-reads
+ * that URI from losing the stdlib.
+ *
+ * # What it deliberately does not answer
+ *
+ * The store is scoped to the ORIGIN, not to the page: two pages on the same
+ * origin share it, and the user agent may evict it entirely. Both are properties
+ * of browser storage rather than of this class, and neither is worth a stub —
+ * eviction presents as a first visit, which is a state this provider is
+ * correct in.
+ */
+export declare class PersistentFileSystemProvider extends InMemoryFileSystemProvider {
+    protected readonly store: FileSystemStore;
+    /**
+     * The map-key prefix store keys are relative to, WITH its trailing
+     * separator, or `undefined` when store keys are absolute URIs.
+     */
+    protected readonly storeRoot?: string;
+    /**
+     * The seed's paths, in STORE-key space rather than as the record was written.
+     *
+     * Normalised on the way in for the same reason restoring is: a seed key and
+     * the key derived from a URI disagree for a percent-encodable path, so a raw
+     * `Object.keys` set would call `a b.x` unseeded and remove its entry instead
+     * of marking it — a deletion that quietly undoes itself on the next load.
+     */
+    protected readonly seededPaths: ReadonlySet<string>;
+    constructor(services: ServerSharedServicesMinimal, options: PersistentFileSystemOptions);
+    /**
+     * The sync twin, mirrored without waiting.
+     *
+     * It has no way to report a store failure to its caller, so the tracer is the
+     * only channel it has — which is why {@link writeFile}, the path a save
+     * actually takes, awaits instead.
+     */
+    setFile(uri: URI, content: string): void;
+    /**
+     * Write through to the store and REJECT if it refuses.
+     *
+     * A quota failure or an evicted origin has to reach the client that asked for
+     * the save: the alternative is a page that reports a saved workspace and
+     * reloads without it, which is the same shape as persistence working.
+     *
+     * `super.setFile` rather than `this.setFile`, so the awaited mirror below is
+     * the only one — the override would fire a second, unawaited write for the
+     * same content.
+     */
+    writeFile(uri: URI, content: string): Promise<void>;
+    deleteFile(uri: URI): void;
+    /** The absolute URI a store-space `path` addresses. */
+    protected storeUri(path: string): URI;
+    /** Mirror one write. `async` so a bad key rejects rather than throwing at the call site. */
+    protected persist(uri: URI, content: string): Promise<void>;
+    /**
+     * Mirror one deletion: a tombstone where the seed would otherwise bring the
+     * file back, a plain removal where it would not. `async` for the same reason
+     * as {@link persist}.
+     */
+    protected forget(uri: URI): Promise<void>;
+    /**
+     * The store key for `uri`, in the seed's key space.
+     *
+     * Throws for a URI outside `rootUri` rather than keying it absolutely beside
+     * the relative ones: a store holding both spellings restores under neither,
+     * and a host writing outside the workspace it declared has a wiring fault
+     * worth hearing about.
+     */
+    protected storeKey(uri: URI): string;
+    protected reportStoreFailure(operation: string, uri: URI, error: unknown): void;
+}
+/**
+ * Restore `options.store` and bind a {@link PersistentFileSystemProvider} over
+ * it, spread into the services context exactly where a Node host spreads
+ * `NodeFileSystem`.
+ *
+ * **It is asynchronous, and that is the ordering contract rather than an
+ * implementation detail.** The provider's reads are synchronous, so the stored
+ * workspace must be in the map before anything reads it — and a `hydrate()`
+ * method on the provider could not enforce that, because awaiting one after the
+ * transport exists is already too late: a `BrowserMessageReader` starts its port
+ * on construction but fires into an emitter with no listener until
+ * `startLanguageServer` calls `listen`, so an `initialize` arriving during the
+ * await is DROPPED — no error, no reply, a client that waits forever. Loading
+ * here, before the services and therefore before the connection exist, makes
+ * that unrepresentable rather than documented.
+ */
+export declare function persistentFileSystem(options: PersistentFileSystemOptions): Promise<{
+    fileSystemProvider: (services: unknown) => WritableFileSystemProvider;
+}>;
+//# sourceMappingURL=persistent-file-system-provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"persistent-file-system-provider.d.ts","sourceRoot":"","sources":["../../../src/langium/workspace/persistent-file-system-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACzC,OAAO,EAAE,KAAK,0BAA0B,EAAE,MAAM,yCAAyC,CAAC;AAC1F,OAAO,EAAuB,KAAK,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAC9F,OAAO,EAAE,KAAK,cAAc,EAAE,0BAA0B,EAAE,KAAK,yBAAyB,EAAE,MAAM,qCAAqC,CAAC;AAEtI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,WAAW,eAAe;IAC7B;;;OAGG;IACH,IAAI,IAAI,OAAO,CAAC,cAAc,CAAC,CAAC;IAChC;;;;;;;OAOG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,kEAAkE;IAClE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtC;AAYD,yFAAyF;AACzF,MAAM,WAAW,2BAA4B,SAAQ,yBAAyB;IAC3E,6EAA6E;IAC7E,KAAK,EAAE,eAAe,CAAC;IACvB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,qBAAa,4BAA6B,SAAQ,0BAA0B;IACzE,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAC1C;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IACtC;;;;;;;OAOG;IACH,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;gBAExC,QAAQ,EAAE,2BAA2B,EAAE,OAAO,EAAE,2BAA2B;IAuBvF;;;;;;OAMG;IACM,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAKjD;;;;;;;;;;OAUG;IACY,SAAS,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKzD,UAAU,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI;IAKnC,uDAAuD;IACvD,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG;IAIrC,4FAA4F;cAC5E,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjE;;;;OAIG;cACa,MAAM,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAS/C;;;;;;;OAOG;IACH,SAAS,CAAC,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM;IAWpC,SAAS,CAAC,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;CAGjF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,OAAO,CAAC;IACvF,kBAAkB,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,0BAA0B,CAAC;CACxE,CAAC,CAKD"}

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

@@ -0,0 +1,208 @@
+/********************************************************************************
+ * 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 { URI } from '@hydranium/langium';
+import { serverSharedFactory } from '../shared-services.js';
+import { InMemoryFileSystemProvider } from './in-memory-file-system-provider.js';
+/**
+ * The stored VALUE that means "deleted", as opposed to content.
+ *
+ * NUL-wrapped so no document can be taken for one: a file whose entire content
+ * is this exact string would be restored as a deletion, and text a grammar can
+ * parse holds no NUL. Deliberately not exported — a store must treat it as
+ * opaque content, and a host that could recognise it would be tempted to.
+ */
+const TOMBSTONE = '\u0000hydranium:deleted\u0000';
+/**
+ * An {@link InMemoryFileSystemProvider} whose writes survive the page: the map
+ * is still the read path, and every write is mirrored into an asynchronous
+ * {@link FileSystemStore} that the next start is restored from.
+ *
+ * # The seed is the baseline and the store is the delta
+ *
+ * A restored entry wins over the seed for the same key; a seeded file the store
+ * has never heard of is served from the seed. So a first visit is the seed
+ * exactly, a returning visit is the seed with the edits laid over it, and a file
+ * the host adds to its seed later appears for a visitor who already has stored
+ * content — which whole-store precedence would have hidden until they cleared
+ * their storage.
+ *
+ * # Deleting a seeded file writes a marker, because dropping its entry would not
+ *
+ * A delta over a baseline cannot express absence by omission: removing the
+ * stored entry for a seeded file returns it to its seeded content on the next
+ * restore, which is a deletion that undoes itself. So {@link deleteFile} stores
+ * a TOMBSTONE for a path the seed carries, and restoring one applies it as a
+ * deletion rather than as content. Re-creating the file is an ordinary write over
+ * the marker, so nothing has to un-mark it.
+ *
+ * A path the seed does NOT carry needs no marker — absence from the store is
+ * already absence — so its entry is removed instead, which is what keeps a host
+ * that creates and deletes scratch files from growing the store forever.
+ *
+ * The marker is a reserved VALUE rather than a reserved key, and that is for the
+ * store's sake: a key is a seed-space path by contract, and a store may map keys
+ * to real filenames, where a reserved key prefix would ask it to create a file
+ * whose name is not a path. As a value it needs nothing from any store. Two
+ * consequences worth knowing: a host that reads the store directly — to count
+ * what is held, say — sees marker entries among the content ones and cannot tell
+ * them apart; and a document whose ENTIRE content is the marker string would be
+ * restored as deleted, which is why the marker is NUL-wrapped and text a grammar
+ * can parse is not.
+ *
+ * # A registered virtual document still wins
+ *
+ * `readFileSync` consults the virtual-document seam before the map, so a stdlib
+ * contributed in code keeps answering for its URI whether or not the store holds
+ * one. The store cannot shadow it, which is what keeps a rebuild that re-reads
+ * that URI from losing the stdlib.
+ *
+ * # What it deliberately does not answer
+ *
+ * The store is scoped to the ORIGIN, not to the page: two pages on the same
+ * origin share it, and the user agent may evict it entirely. Both are properties
+ * of browser storage rather than of this class, and neither is worth a stub —
+ * eviction presents as a first visit, which is a state this provider is
+ * correct in.
+ */
+export class PersistentFileSystemProvider extends InMemoryFileSystemProvider {
+    store;
+    /**
+     * The map-key prefix store keys are relative to, WITH its trailing
+     * separator, or `undefined` when store keys are absolute URIs.
+     */
+    storeRoot;
+    /**
+     * The seed's paths, in STORE-key space rather than as the record was written.
+     *
+     * Normalised on the way in for the same reason restoring is: a seed key and
+     * the key derived from a URI disagree for a percent-encodable path, so a raw
+     * `Object.keys` set would call `a b.x` unseeded and remove its entry instead
+     * of marking it — a deletion that quietly undoes itself on the next load.
+     */
+    seededPaths;
+    constructor(services, options) {
+        super(services, options);
+        this.store = options.store;
+        this.storeRoot = options.rootUri === undefined ? undefined : `${this.fileKey(options.rootUri)}/`;
+        this.seededPaths = new Set(Object.keys(options.seed ?? {}).map(path => this.storeKey(this.storeUri(path))));
+        for (const [path, content] of Object.entries(options.restored ?? {})) {
+            // `super.*`, so restoring does not mirror straight back into the store
+            // it just came from — a write-back on every start, and one that would
+            // resurrect an entry the store had legitimately dropped.
+            //
+            // Applied AFTER the seed and through the same key normalisation, which
+            // is what makes "restored wins" hold for a key the two spell
+            // differently (`a b.x` against `a%20b.x`) instead of depending on the
+            // insertion order of a merged record.
+            const uri = this.storeUri(path);
+            if (content === TOMBSTONE) {
+                super.deleteFile(uri);
+            }
+            else {
+                super.setFile(uri, content);
+            }
+        }
+    }
+    /**
+     * The sync twin, mirrored without waiting.
+     *
+     * It has no way to report a store failure to its caller, so the tracer is the
+     * only channel it has — which is why {@link writeFile}, the path a save
+     * actually takes, awaits instead.
+     */
+    setFile(uri, content) {
+        super.setFile(uri, content);
+        this.persist(uri, content).catch((error) => this.reportStoreFailure('store', uri, error));
+    }
+    /**
+     * Write through to the store and REJECT if it refuses.
+     *
+     * A quota failure or an evicted origin has to reach the client that asked for
+     * the save: the alternative is a page that reports a saved workspace and
+     * reloads without it, which is the same shape as persistence working.
+     *
+     * `super.setFile` rather than `this.setFile`, so the awaited mirror below is
+     * the only one — the override would fire a second, unawaited write for the
+     * same content.
+     */
+    async writeFile(uri, content) {
+        super.setFile(uri, content);
+        await this.persist(uri, content);
+    }
+    deleteFile(uri) {
+        super.deleteFile(uri);
+        this.forget(uri).catch((error) => this.reportStoreFailure('forget', uri, error));
+    }
+    /** The absolute URI a store-space `path` addresses. */
+    storeUri(path) {
+        return URI.parse(this.storeRoot === undefined ? path : `${this.storeRoot}${path}`);
+    }
+    /** Mirror one write. `async` so a bad key rejects rather than throwing at the call site. */
+    async persist(uri, content) {
+        await this.store.write(this.storeKey(uri), content);
+    }
+    /**
+     * Mirror one deletion: a tombstone where the seed would otherwise bring the
+     * file back, a plain removal where it would not. `async` for the same reason
+     * as {@link persist}.
+     */
+    async forget(uri) {
+        const path = this.storeKey(uri);
+        if (this.seededPaths.has(path)) {
+            await this.store.write(path, TOMBSTONE);
+        }
+        else {
+            await this.store.remove(path);
+        }
+    }
+    /**
+     * The store key for `uri`, in the seed's key space.
+     *
+     * Throws for a URI outside `rootUri` rather than keying it absolutely beside
+     * the relative ones: a store holding both spellings restores under neither,
+     * and a host writing outside the workspace it declared has a wiring fault
+     * worth hearing about.
+     */
+    storeKey(uri) {
+        const key = this.fileKey(uri);
+        if (this.storeRoot === undefined) {
+            return key;
+        }
+        if (!key.startsWith(this.storeRoot)) {
+            throw new Error(`Cannot persist ${uri.toString()}: outside the store root ${this.storeRoot}`);
+        }
+        return key.slice(this.storeRoot.length);
+    }
+    reportStoreFailure(operation, uri, error) {
+        this.tracer.error(`Failed to ${operation} ${uri.toString()}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Restore `options.store` and bind a {@link PersistentFileSystemProvider} over
+ * it, spread into the services context exactly where a Node host spreads
+ * `NodeFileSystem`.
+ *
+ * **It is asynchronous, and that is the ordering contract rather than an
+ * implementation detail.** The provider's reads are synchronous, so the stored
+ * workspace must be in the map before anything reads it — and a `hydrate()`
+ * method on the provider could not enforce that, because awaiting one after the
+ * transport exists is already too late: a `BrowserMessageReader` starts its port
+ * on construction but fires into an emitter with no listener until
+ * `startLanguageServer` calls `listen`, so an `initialize` arriving during the
+ * await is DROPPED — no error, no reply, a client that waits forever. Loading
+ * here, before the services and therefore before the connection exist, makes
+ * that unrepresentable rather than documented.
+ */
+export async function persistentFileSystem(options) {
+    const restored = await options.store.load();
+    return {
+        fileSystemProvider: serverSharedFactory(services => new PersistentFileSystemProvider(services, { ...options, restored }))
+    };
+}
+//# sourceMappingURL=persistent-file-system-provider.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"persistent-file-system-provider.js","sourceRoot":"","sources":["../../../src/langium/workspace/persistent-file-system-provider.ts"],"names":[],"mappings":"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"}

package/lib/langium/workspace/synthetic.d.ts

@@ -0,0 +1,38 @@
+/********************************************************************************
+ * 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 } from '@hydranium/langium';
+/**
+ * Mark `node` as synthetic. Returns the node for fluent chaining.
+ *
+ * Opting into the synthetic marker drives behaviour changes downstream
+ * — most notably, the framework's
+ * `HydraniumDocumentValidator.shouldSkipValidation` default
+ * skips marked nodes (unless `validateSyntheticNodes` is enabled),
+ * short-circuiting validation for mirrors and stdlib content. Adopters
+ * who want a synthetic node validated normally simply do not mark it.
+ */
+export declare function markSynthetic<T extends AstNode>(node: T): T;
+/**
+ * Walk an AST tree rooted at `root` and {@link markSynthetic mark}
+ * every node. Use when building a stdlib / library document where
+ * every node should opt into skip-validation semantics in one stroke.
+ *
+ * For partial marking (some nodes mirrored, some validated normally),
+ * call {@link markSynthetic} on the specific nodes instead.
+ */
+export declare function markSyntheticTree(root: AstNode): void;
+/**
+ * True iff `node` has been explicitly marked synthetic via
+ * {@link markSynthetic} / {@link markSyntheticTree}. The check is a
+ * pure flag read — the URI scheme of the containing document does
+ * not influence this predicate (see `isVirtualUri` for the separate
+ * document-identity axis).
+ */
+export declare function isSyntheticNode(node: AstNode): boolean;
+//# sourceMappingURL=synthetic.d.ts.map

package/lib/langium/workspace/synthetic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthetic.d.ts","sourceRoot":"","sources":["../../../src/langium/workspace/synthetic.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAGlF,OAAO,EAAE,KAAK,OAAO,EAAY,MAAM,oBAAoB,CAAC;AAc5D;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,OAAO,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAG3D;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAIrD;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAEtD"}

package/lib/langium/workspace/synthetic.js

@@ -0,0 +1,58 @@
+/********************************************************************************
+ * 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 } from '@hydranium/langium';
+// The `$synthetic` `AstNode` type augmentation lives in `@hydranium/langium`
+// (the langium chokepoint); it arrives here ambiently via that dependency.
+// This module owns the *behaviour* of the synthetic-node concept — the marker
+// helpers below and the validation-skip default that reads them.
+//
+// This is the NODE-provenance axis: a synthetic node is one not authored by
+// the user — synthesized in code (a stdlib element) or by projection (a mirror
+// of an inherited member). It is distinct from the *document* axis, where a
+// virtual document is one with no backing file. The two are orthogonal: a
+// synthetic node can live in a real file, and a virtual document can hold
+// non-synthetic nodes.
+/**
+ * Mark `node` as synthetic. Returns the node for fluent chaining.
+ *
+ * Opting into the synthetic marker drives behaviour changes downstream
+ * — most notably, the framework's
+ * `HydraniumDocumentValidator.shouldSkipValidation` default
+ * skips marked nodes (unless `validateSyntheticNodes` is enabled),
+ * short-circuiting validation for mirrors and stdlib content. Adopters
+ * who want a synthetic node validated normally simply do not mark it.
+ */
+export function markSynthetic(node) {
+    node.$synthetic = true;
+    return node;
+}
+/**
+ * Walk an AST tree rooted at `root` and {@link markSynthetic mark}
+ * every node. Use when building a stdlib / library document where
+ * every node should opt into skip-validation semantics in one stroke.
+ *
+ * For partial marking (some nodes mirrored, some validated normally),
+ * call {@link markSynthetic} on the specific nodes instead.
+ */
+export function markSyntheticTree(root) {
+    for (const node of AstUtils.streamAst(root)) {
+        markSynthetic(node);
+    }
+}
+/**
+ * True iff `node` has been explicitly marked synthetic via
+ * {@link markSynthetic} / {@link markSyntheticTree}. The check is a
+ * pure flag read — the URI scheme of the containing document does
+ * not influence this predicate (see `isVirtualUri` for the separate
+ * document-identity axis).
+ */
+export function isSyntheticNode(node) {
+    return node.$synthetic === true;
+}
+//# sourceMappingURL=synthetic.js.map

package/lib/langium/workspace/synthetic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"synthetic.js","sourceRoot":"","sources":["../../../src/langium/workspace/synthetic.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAGlF,OAAO,EAAgB,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE5D,6EAA6E;AAC7E,2EAA2E;AAC3E,8EAA8E;AAC9E,iEAAiE;AACjE,EAAE;AACF,4EAA4E;AAC5E,+EAA+E;AAC/E,4EAA4E;AAC5E,0EAA0E;AAC1E,0EAA0E;AAC1E,uBAAuB;AAEvB;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAoB,IAAO;IACpD,IAAmB,CAAC,UAAU,GAAG,IAAI,CAAC;IACvC,OAAO,IAAI,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAa;IAC5C,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3C,aAAa,CAAC,IAAI,CAAC,CAAC;IACvB,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,IAAa;IAC1C,OAAO,IAAI,CAAC,UAAU,KAAK,IAAI,CAAC;AACnC,CAAC"}

package/lib/langium/workspace/virtual-document.d.ts

@@ -0,0 +1,78 @@
+/********************************************************************************
+ * 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 { URI } from '@hydranium/langium';
+import { type ServerSharedServicesMinimal } from '../shared-services.js';
+/**
+ * URI scheme for virtual documents — LangiumDocuments that have no backing
+ * file on disk (a language's stdlib, library types, built-in definitions,
+ * mirrors, generated views). Chosen so it cannot collide with on-disk `file:`
+ * URIs, and so the framework's FileSystemProvider can recognise and serve them
+ * on re-read (see {@link serveVirtualDocument}).
+ */
+export declare const VIRTUAL_SCHEME = "virtual";
+/**
+ * Build a URI for a virtual document — one whose content is provided in code
+ * rather than read from disk, either as a parsed string
+ * (`LangiumDocumentFactory.fromString`) or a code-built AST
+ * (`LangiumDocumentFactory.fromModel`).
+ *
+ * The URI uses the {@link VIRTUAL_SCHEME} scheme. The first segment carries
+ * contributor identity for diagnostics, telemetry, and "go to source" UI;
+ * additional segments scope sub-documents within one contributor.
+ *
+ * Pair with a `LangiumDocumentFactory` to construct a document whose content
+ * lives in memory. The resulting document is suitable as the `document`
+ * argument to the tier factories on `HydraniumAstNodeDescriptionProvider`
+ * (`createLocal` / `createProject` / `createPublic` / `createUniversal`).
+ *
+ * # End the URI with a registered file extension
+ *
+ * Called with a contributor and no further segments this yields
+ * `virtual:<contributor>`, which has no extension and so matches no registered
+ * language — a trap. Every per-language service is resolved per URI, and a
+ * virtual document is never open in `TextDocuments`, so the declared-languageId
+ * lookup rung cannot serve it either: the document is indexed but inert,
+ * contributing nothing to the scopes it was written to populate, with no error
+ * anywhere. Pass the extension as the last segment,
+ * `virtualUri(contributor, 'name.<ext>')`. `HydraniumWorkspaceManager` warns
+ * when a seeded additional document fails to route, which is where this
+ * usually surfaces.
+ *
+ * # Relationship to the `$synthetic` node marker
+ *
+ * The URI scheme tags the *document* as not-from-disk; the `$synthetic` node
+ * marker (see `markSynthetic` / `isSyntheticNode`) tags an individual *node* as
+ * not user-authored. A virtual document may contain non-synthetic nodes and
+ * vice versa.
+ *
+ * Both axes are read by `HydraniumDocumentValidator`, at different
+ * granularities: the scheme skips the WHOLE document
+ * (`validateVirtualDocuments`, default `false`, so the walk is avoided
+ * entirely), the marker skips a node and its children
+ * (`validateSyntheticNodes`, default `false`).
+ */
+export declare function virtualUri(contributor: string, ...segments: string[]): URI;
+/** True iff `uri` uses the {@link VIRTUAL_SCHEME} scheme produced by {@link virtualUri}. */
+export declare function isVirtualUri(uri: URI | string): boolean;
+/**
+ * Serve the text of a registered virtual document, or `undefined` when `uri`
+ * is not virtual or no document is registered for it (so a FileSystemProvider
+ * delegates to its real backing).
+ *
+ * The framework's FileSystemProvider defaults call this at the top of
+ * `readFile` / `readFileSync` so a virtual document survives a re-read:
+ * `DocumentBuilder.update` / `LangiumDocumentFactory.update` re-read a changed
+ * URI from the FileSystemProvider, and nothing on disk backs a virtual URI. The
+ * text comes from the registered document — the original source for a
+ * `fromString` document, or the serialized form retained by the framework's
+ * `fromModel` (which fills in the text Langium leaves empty). No serializer is
+ * consulted here; the text is already on the document.
+ */
+export declare function serveVirtualDocument(services: ServerSharedServicesMinimal, uri: URI): string | undefined;
+//# sourceMappingURL=virtual-document.d.ts.map

package/lib/langium/workspace/virtual-document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtual-document.d.ts","sourceRoot":"","sources":["../../../src/langium/workspace/virtual-document.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACzC,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAEzE;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,YAAY,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAG,CAG1E;AAED,4FAA4F;AAC5F,wBAAgB,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,OAAO,CAGvD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,2BAA2B,EAAE,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,SAAS,CAMxG"}