@hydranium/core 1.0.0-next.10

package/lib/langium/project/project-change-event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-change-event.d.ts","sourceRoot":"","sources":["../../../src/langium/project/project-change-event.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,kBAAkB,CAAC,QAAQ,SAAS,OAAO,GAAG,OAAO;IACnE,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAElC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAEpC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;KAAE,CAAC,CAAC;IAEtF;;;;;;;;;OASG;IACH,QAAQ,CAAC,iBAAiB,EAAE,SAAS,GAAG,EAAE,CAAC;CAC7C;AAED,6DAA6D;AAC7D,MAAM,MAAM,qBAAqB,CAAC,QAAQ,SAAS,OAAO,GAAG,OAAO,IAAI,CAAC,KAAK,EAAE,kBAAkB,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC"}

package/lib/langium/project/project-change-event.js

@@ -0,0 +1,10 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+export {};
+//# sourceMappingURL=project-change-event.js.map

package/lib/langium/project/project-change-event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-change-event.js","sourceRoot":"","sources":["../../../src/langium/project/project-change-event.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF"}

package/lib/langium/project/project-manager.d.ts

@@ -0,0 +1,196 @@
+/********************************************************************************
+ * 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 { Project } from '@hydranium/protocol';
+import type { AstNode, URI } from '@hydranium/langium';
+import type { Disposable } from 'vscode-languageserver';
+import type { WorkspaceFolder } from 'vscode-languageserver-types';
+import type { ProjectChangeListener } from './project-change-event.js';
+/**
+ * Manages the **project tier** sitting between the LSP `WorkspaceFolder`
+ * (protocol-owned: URI + display name only) and `LangiumDocument`
+ * (Langium-owned: per-file parse + index + state). Owns project discovery,
+ * registry maintenance, and the cascade signal for documents whose
+ * reachable scope changed when a project changed.
+ *
+ * Langium does not provide a project tier and explicitly does not intend
+ * to add one — see [Discussion #1375 — *Multiple Languages from different
+ * Projects*](https://github.com/eclipse-langium/langium/discussions/1375).
+ * `@hydranium/core` provides this tier so consumers don't have to
+ * reinvent it.
+ *
+ * ## Lifecycle
+ *
+ * 1. `HydraniumWorkspaceManager.performStartup` awaits {@link discoverProjects}
+ *    as **phase 0**, before Langium's file-discovery and document-loading
+ *    phases. By the time any non-descriptor document hits `Parsed`, the
+ *    registry is fully populated and {@link getProject} returns a
+ *    definitive answer.
+ * 2. {@link ready} resolves at the end of phase 0. Code that depends on
+ *    project membership during startup (AST extensions running at
+ *    `IndexedContent`, integrity rules, scope providers) awaits this.
+ * 3. After startup, the abstract `AbstractProjectManager` base auto-
+ *    subscribes to `DocumentBuilder.onUpdate` to track incremental
+ *    changes to descriptor files; each relevant update fires
+ *    {@link onProjectsChanged} with the registry diff + affected
+ *    documents, and `HydraniumWorkspaceManager` re-runs
+ *    `DocumentBuilder.resetToState` on the affected URIs to cascade
+ *    the rebuild.
+ *
+ * ## Implementations
+ *
+ * - **`SingleProjectManager`** — the framework default. One synthetic
+ *   project owns every document, so visibility queries answer
+ *   "everything sees everything" and consumers without a project tier
+ *   pay zero cost.
+ * - **`AbstractProjectManager`** — abstract base for project-aware
+ *   consumers, carrying the registry, the `DocumentBuilder.onUpdate`
+ *   subscription, the event channel, and the cascade computation.
+ */
+export interface ProjectManager<TProject extends Project = Project> {
+    /**
+     * Phase-0 discovery. Called once during workspace startup, before any
+     * non-descriptor documents are loaded. Implementations walk the given
+     * workspace folders for descriptor files (whatever the consumer defines
+     * as such via {@link isProjectDescriptor}), parse them, and populate the
+     * registry. After this method resolves, {@link ready} resolves.
+     *
+     * Implementations may emit an initial {@link onProjectsChanged} with
+     * `added` populated. The empty-registry case (no descriptors found) is
+     * valid and emits nothing.
+     */
+    discoverProjects(folders: readonly WorkspaceFolder[]): Promise<void>;
+    /**
+     * Resolves at the end of {@link discoverProjects}.
+     *
+     * `SingleProjectManager` resolves this synchronously at construction
+     * time — consumers can await it safely without triggering a hang when
+     * no project tier is wired.
+     */
+    readonly ready: Promise<void>;
+    /**
+     * Subscribe to project add / update / remove events. Fires whenever
+     * the registry changes — both during incremental rebuilds (descriptor
+     * file edited / deleted) and as a single event at the end of
+     * {@link discoverProjects} when projects were found.
+     *
+     * Returns a `Disposable` that unregisters the listener.
+     */
+    onProjectsChanged(listener: ProjectChangeListener<TProject>): Disposable;
+    /**
+     * The {@link Project} owning the given document URI, or `undefined` if
+     * the URI does not belong to any project. Membership is determined by
+     * the concrete implementation.
+     *
+     * `SingleProjectManager` always returns its synthetic workspace project —
+     * never `undefined` — so consumers can rely on a non-null answer when
+     * no project tier is wired (matches Langium's flat-scope default).
+     */
+    getProject(uri: URI | string): TProject | undefined;
+    /**
+     * The {@link Project} owning the document `node` belongs to, or `undefined`
+     * (including when `node` is not attached to a document). Convenience over
+     * {@link getProject} that centralizes the node→root-document→URI derivation
+     * that callers would otherwise hand-roll (and risk skipping URI
+     * normalization on). No `getProjectForDocument` sibling — `getProject(document.uri)`
+     * is already a bare access, so a wrapper would hide nothing.
+     */
+    getProjectForNode(node: AstNode): TProject | undefined;
+    /** Look up a project by its {@link Project.id}. */
+    getProjectById(id: string): TProject | undefined;
+    /** Snapshot of all projects currently in the registry. */
+    getProjects(): readonly TProject[];
+    /**
+     * URIs of documents that belong to the given project. Returns an
+     * empty array if the project id is unknown.
+     */
+    getProjectUris(projectId: string): readonly URI[];
+    /**
+     * Project ids visible from the given project: the project itself plus
+     * the transitive closure of declared dependencies according to the
+     * concrete implementation's visibility model. Returns an empty array
+     * if the project id is unknown.
+     *
+     * Default behaviour in `AbstractProjectManager` is the **transitive
+     * closure** of {@link Project.dependencies}, including the project
+     * itself. An adopter can override to use a different visibility model.
+     *
+     * `SingleProjectManager` returns `[id]` for its synthetic workspace
+     * project, which combined with "synthetic project owns every URI"
+     * yields "everything is visible to everything" — Langium's flat-
+     * scope behaviour preserved.
+     */
+    getVisibleProjects(projectId: string): readonly string[];
+    /**
+     * Convenience predicate over {@link getVisibleProjects}: returns true
+     * iff `targetProjectId` is in the visibility set of `sourceProjectId`.
+     * Unknown source ids (empty visibility set) always return false.
+     *
+     * @param selfVisible when `sourceProjectId === targetProjectId`,
+     *        controls whether the project is considered visible to itself.
+     *        Reference-construction callers pass `true` (a project sees
+     *        its own elements); strict cross-project walks pass `false`.
+     *        Default: `false`.
+     *
+     * **The `false` default is deliberate, and stays that way while the only
+     * production caller passes `true`.** Flipping it to match that caller
+     * would make a configure-time default out of a single hardcoded
+     * argument — the same decision, written where the reader cannot see it.
+     * Per-call explicitness keeps the *why* at the call site instead. Revisit
+     * if a second non-test caller appears, or if an audit-strict caller
+     * genuinely wants `false`.
+     */
+    isVisible(sourceProjectId: string, targetProjectId: string, selfVisible?: boolean): boolean;
+    /**
+     * Fast-path predicate: true when the workspace has at most one
+     * meaningful project boundary. Enables a fast-path in the framework's
+     * `HydraniumScopeProvider.getProjectScope` that returns the
+     * unfiltered global scope when project filtering would be a no-op.
+     *
+     * Default implementations:
+     * - `SingleProjectManager`: returns `true` unconditionally (its
+     *   synthetic workspace project owns everything).
+     * - `AbstractProjectManager`: returns `getProjects().length <= 1`
+     *   (conservative — once a second project is registered, returns
+     *   false even if all documents are still owned by the original).
+     *
+     * Adopters with custom `ProjectManager` implementations override to
+     * match their workspace shape.
+     */
+    isSingleProject(): boolean;
+    /**
+     * Predicate: is the given URI a project descriptor file?
+     *
+     * Determines which URIs participate in project discovery (during
+     * {@link discoverProjects}) and incremental tracking (via the
+     * auto-subscription to `DocumentBuilder.onUpdate` inside
+     * `AbstractProjectManager`).
+     *
+     * Default in `SingleProjectManager`: returns `false`. Single-project /
+     * project-less consumers get the default and never participate in
+     * descriptor tracking.
+     */
+    isProjectDescriptor(uri: URI | string): boolean;
+    /**
+     * Whether the project owning `uri` uses unqualified references — i.e.
+     * its {@link Project.referenceName} equals the
+     * `UNQUALIFIED_PROJECT_REFERENCE` sentinel, or `uri` is not owned by
+     * any project. The predicate exists so callers that would otherwise
+     * compose a project prefix can skip the composition without reaching
+     * for the sentinel value themselves; an implementation that can answer
+     * without a full membership lookup overrides it.
+     *
+     * Default implementations:
+     * - `SingleProjectManager`: always `true` — its synthetic workspace
+     *   project is constructed with the sentinel.
+     * - `AbstractProjectManager`: the owning project is absent, or its
+     *   `referenceName` is the sentinel.
+     */
+    isUnqualifiedProjectReference(uri: URI | string): boolean;
+}
+//# sourceMappingURL=project-manager.d.ts.map

package/lib/langium/project/project-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-manager.d.ts","sourceRoot":"","sources":["../../../src/langium/project/project-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,WAAW,cAAc,CAAC,QAAQ,SAAS,OAAO,GAAG,OAAO;IAK/D;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAErE;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9B;;;;;;;OAOG;IACH,iBAAiB,CAAC,QAAQ,EAAE,qBAAqB,CAAC,QAAQ,CAAC,GAAG,UAAU,CAAC;IAMzE;;;;;;;;OAQG;IACH,UAAU,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;IAEpD;;;;;;;OAOG;IACH,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;IAEvD,mDAAmD;IACnD,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;IAEjD,0DAA0D;IAC1D,WAAW,IAAI,SAAS,QAAQ,EAAE,CAAC;IAEnC;;;OAGG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,EAAE,CAAC;IAElD;;;;;;;;;;;;;;OAcG;IACH,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAEzD;;;;;;;;;;;;;;;;;;OAkBG;IACH,SAAS,CAAC,eAAe,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC;IAM5F;;;;;;;;;;;;;;;OAeG;IACH,eAAe,IAAI,OAAO,CAAC;IAE3B;;;;;;;;;;;OAWG;IACH,mBAAmB,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,OAAO,CAAC;IAEhD;;;;;;;;;;;;;;OAcG;IACH,6BAA6B,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,OAAO,CAAC;CAC5D"}

package/lib/langium/project/project-manager.js

@@ -0,0 +1,10 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+export {};
+//# sourceMappingURL=project-manager.js.map

package/lib/langium/project/project-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-manager.js","sourceRoot":"","sources":["../../../src/langium/project/project-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF"}

package/lib/langium/project/single-project-manager.d.ts

@@ -0,0 +1,69 @@
+/********************************************************************************
+ * 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 Project, type Tracer } from '@hydranium/protocol';
+import { type AstNode, type LangiumDocuments, type URI } from '@hydranium/langium';
+import { Disposable } from 'vscode-languageserver';
+import { type LogNameOptions } from '../diagnostics/logger.js';
+import { type ServerSharedServicesMinimal } from '../shared-services.js';
+import type { ProjectChangeListener } from './project-change-event.js';
+import type { ProjectManager } from './project-manager.js';
+/**
+ * Framework default {@link ProjectManager}. Exposes a single synthetic
+ * project ({@link SingleProjectManager.WORKSPACE_PROJECT_ID}) that owns
+ * every document in the workspace, so visibility queries answer
+ * **"everything is visible to everything"** — preserving Langium's
+ * default flat-scope behaviour.
+ *
+ * The class name describes the state literally: one project. Consumers
+ * without a project tier (tests / single-grammar adopters) bind
+ * this and pay zero cost. No descriptor tracking, no incremental work,
+ * no events ever fire from {@link onProjectsChanged}.
+ *
+ * For project-aware consumers, extend `AbstractProjectManager` instead.
+ */
+export declare class SingleProjectManager implements ProjectManager {
+    protected readonly services: ServerSharedServicesMinimal;
+    /**
+     * Identity of the synthetic project. Prefixed with `@` so it cannot
+     * collide with a descriptor-derived project id, which by convention
+     * never begins with `@`.
+     */
+    static readonly WORKSPACE_PROJECT_ID = "@workspace";
+    protected readonly project: Project;
+    readonly ready: Promise<void>;
+    protected readonly langiumDocuments: LangiumDocuments;
+    protected readonly tracer: Tracer;
+    constructor(services: ServerSharedServicesMinimal, options?: LogNameOptions);
+    /** No-op: there are no descriptors to discover. */
+    discoverProjects(): Promise<void>;
+    /** Never fires — `SingleProjectManager` exposes a fixed registry. The returned disposable is a safe no-op. */
+    onProjectsChanged(_listener: ProjectChangeListener): Disposable;
+    isProjectDescriptor(_uri: URI | string): boolean;
+    /** Always `true` — single-project by definition. */
+    isSingleProject(): boolean;
+    /**
+     * Always `true` — the synthetic workspace project is constructed with
+     * {@link UNQUALIFIED_PROJECT_REFERENCE}, so every URI it owns is by
+     * definition unqualified.
+     */
+    isUnqualifiedProjectReference(_uri: URI | string): boolean;
+    /** Every URI belongs to the synthetic workspace project. */
+    getProject(_uri: URI | string): Project | undefined;
+    /** Every node belongs to the synthetic workspace project. */
+    getProjectForNode(_node: AstNode): Project | undefined;
+    getProjectById(id: string): Project | undefined;
+    getProjects(): readonly Project[];
+    /** All workspace URIs belong to the synthetic project; any other id yields `[]`. */
+    getProjectUris(projectId: string): readonly URI[];
+    /** Self-only visibility, combined with single-project ownership = "everything sees everything." */
+    getVisibleProjects(projectId: string): readonly string[];
+    /** Synthetic project sees itself iff `selfVisible`; cross-project queries always false. */
+    isVisible(sourceProjectId: string, targetProjectId: string, selfVisible?: boolean): boolean;
+}
+//# sourceMappingURL=single-project-manager.d.ts.map

package/lib/langium/project/single-project-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"single-project-manager.d.ts","sourceRoot":"","sources":["../../../src/langium/project/single-project-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,MAAM,EAAiC,MAAM,qBAAqB,CAAC;AAC/F,OAAO,EAAE,KAAK,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,GAAG,EAAE,MAAM,oBAAoB,CAAC;AACnF,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D;;;;;;;;;;;;;GAaG;AACH,qBAAa,oBAAqB,YAAW,cAAc;IAkBrD,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,2BAA2B;IAjB3D;;;;OAIG;IACH,MAAM,CAAC,QAAQ,CAAC,oBAAoB,gBAAgB;IAEpD,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAGjC;IACF,QAAQ,CAAC,KAAK,gBAAqB;IAEnC,SAAS,CAAC,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;IACtD,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAGZ,QAAQ,EAAE,2BAA2B,EACxD,OAAO,GAAE,cAAmB;IAM/B,mDAAmD;IAC7C,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIvC,8GAA8G;IAC9G,iBAAiB,CAAC,SAAS,EAAE,qBAAqB,GAAG,UAAU;IAI/D,mBAAmB,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,GAAG,OAAO;IAIhD,oDAAoD;IACpD,eAAe,IAAI,OAAO;IAI1B;;;;OAIG;IACH,6BAA6B,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,GAAG,OAAO;IAI1D,4DAA4D;IAC5D,UAAU,CAAC,IAAI,EAAE,GAAG,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS;IAInD,6DAA6D;IAC7D,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS;IAItD,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAI/C,WAAW,IAAI,SAAS,OAAO,EAAE;IAIjC,oFAAoF;IACpF,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,EAAE;IAOjD,mGAAmG;IACnG,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE;IAIxD,2FAA2F;IAC3F,SAAS,CAAC,eAAe,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,WAAW,UAAQ,GAAG,OAAO;CAS3F"}

package/lib/langium/project/single-project-manager.js

@@ -0,0 +1,104 @@
+/********************************************************************************
+ * 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 { UNQUALIFIED_PROJECT_REFERENCE } from '@hydranium/protocol';
+import { Disposable } from 'vscode-languageserver';
+/**
+ * Framework default {@link ProjectManager}. Exposes a single synthetic
+ * project ({@link SingleProjectManager.WORKSPACE_PROJECT_ID}) that owns
+ * every document in the workspace, so visibility queries answer
+ * **"everything is visible to everything"** — preserving Langium's
+ * default flat-scope behaviour.
+ *
+ * The class name describes the state literally: one project. Consumers
+ * without a project tier (tests / single-grammar adopters) bind
+ * this and pay zero cost. No descriptor tracking, no incremental work,
+ * no events ever fire from {@link onProjectsChanged}.
+ *
+ * For project-aware consumers, extend `AbstractProjectManager` instead.
+ */
+export class SingleProjectManager {
+    services;
+    /**
+     * Identity of the synthetic project. Prefixed with `@` so it cannot
+     * collide with a descriptor-derived project id, which by convention
+     * never begins with `@`.
+     */
+    static WORKSPACE_PROJECT_ID = '@workspace';
+    project = {
+        id: SingleProjectManager.WORKSPACE_PROJECT_ID,
+        referenceName: UNQUALIFIED_PROJECT_REFERENCE
+    };
+    ready = Promise.resolve();
+    langiumDocuments;
+    tracer;
+    constructor(services, options = {}) {
+        this.services = services;
+        this.langiumDocuments = services.workspace.LangiumDocuments;
+        this.tracer = services.Tracer.for(options.logName ?? this.constructor.name).trace('instantiated');
+    }
+    /** No-op: there are no descriptors to discover. */
+    async discoverProjects() {
+        // no-op
+    }
+    /** Never fires — `SingleProjectManager` exposes a fixed registry. The returned disposable is a safe no-op. */
+    onProjectsChanged(_listener) {
+        return Disposable.create(() => undefined);
+    }
+    isProjectDescriptor(_uri) {
+        return false;
+    }
+    /** Always `true` — single-project by definition. */
+    isSingleProject() {
+        return true;
+    }
+    /**
+     * Always `true` — the synthetic workspace project is constructed with
+     * {@link UNQUALIFIED_PROJECT_REFERENCE}, so every URI it owns is by
+     * definition unqualified.
+     */
+    isUnqualifiedProjectReference(_uri) {
+        return true;
+    }
+    /** Every URI belongs to the synthetic workspace project. */
+    getProject(_uri) {
+        return this.project;
+    }
+    /** Every node belongs to the synthetic workspace project. */
+    getProjectForNode(_node) {
+        return this.project;
+    }
+    getProjectById(id) {
+        return id === SingleProjectManager.WORKSPACE_PROJECT_ID ? this.project : undefined;
+    }
+    getProjects() {
+        return [this.project];
+    }
+    /** All workspace URIs belong to the synthetic project; any other id yields `[]`. */
+    getProjectUris(projectId) {
+        if (projectId !== SingleProjectManager.WORKSPACE_PROJECT_ID) {
+            return [];
+        }
+        return Array.from(this.langiumDocuments.all, document => document.uri);
+    }
+    /** Self-only visibility, combined with single-project ownership = "everything sees everything." */
+    getVisibleProjects(projectId) {
+        return projectId === SingleProjectManager.WORKSPACE_PROJECT_ID ? [SingleProjectManager.WORKSPACE_PROJECT_ID] : [];
+    }
+    /** Synthetic project sees itself iff `selfVisible`; cross-project queries always false. */
+    isVisible(sourceProjectId, targetProjectId, selfVisible = false) {
+        if (sourceProjectId !== SingleProjectManager.WORKSPACE_PROJECT_ID) {
+            return false;
+        }
+        if (sourceProjectId === targetProjectId) {
+            return selfVisible;
+        }
+        return false;
+    }
+}
+//# sourceMappingURL=single-project-manager.js.map

package/lib/langium/project/single-project-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"single-project-manager.js","sourceRoot":"","sources":["../../../src/langium/project/single-project-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAA6B,6BAA6B,EAAE,MAAM,qBAAqB,CAAC;AAE/F,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAMnD;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,oBAAoB;IAkBR;IAjBtB;;;;OAIG;IACH,MAAM,CAAU,oBAAoB,GAAG,YAAY,CAAC;IAEjC,OAAO,GAAY;QACnC,EAAE,EAAE,oBAAoB,CAAC,oBAAoB;QAC7C,aAAa,EAAE,6BAA6B;KAC9C,CAAC;IACO,KAAK,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAEhB,gBAAgB,CAAmB;IACnC,MAAM,CAAS;IAElC,YACsB,QAAqC,EACxD,UAA0B,EAAE;QADT,aAAQ,GAAR,QAAQ,CAA6B;QAGxD,IAAI,CAAC,gBAAgB,GAAG,QAAQ,CAAC,SAAS,CAAC,gBAAgB,CAAC;QAC5D,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,mDAAmD;IACnD,KAAK,CAAC,gBAAgB;QACnB,QAAQ;IACX,CAAC;IAED,8GAA8G;IAC9G,iBAAiB,CAAC,SAAgC;QAC/C,OAAO,UAAU,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC7C,CAAC;IAED,mBAAmB,CAAC,IAAkB;QACnC,OAAO,KAAK,CAAC;IAChB,CAAC;IAED,oDAAoD;IACpD,eAAe;QACZ,OAAO,IAAI,CAAC;IACf,CAAC;IAED;;;;OAIG;IACH,6BAA6B,CAAC,IAAkB;QAC7C,OAAO,IAAI,CAAC;IACf,CAAC;IAED,4DAA4D;IAC5D,UAAU,CAAC,IAAkB;QAC1B,OAAO,IAAI,CAAC,OAAO,CAAC;IACvB,CAAC;IAED,6DAA6D;IAC7D,iBAAiB,CAAC,KAAc;QAC7B,OAAO,IAAI,CAAC,OAAO,CAAC;IACvB,CAAC;IAED,cAAc,CAAC,EAAU;QACtB,OAAO,EAAE,KAAK,oBAAoB,CAAC,oBAAoB,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IACtF,CAAC;IAED,WAAW;QACR,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACzB,CAAC;IAED,oFAAoF;IACpF,cAAc,CAAC,SAAiB;QAC7B,IAAI,SAAS,KAAK,oBAAoB,CAAC,oBAAoB,EAAE,CAAC;YAC3D,OAAO,EAAE,CAAC;QACb,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,GAAG,EAAE,QAAQ,CAAC,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC1E,CAAC;IAED,mGAAmG;IACnG,kBAAkB,CAAC,SAAiB;QACjC,OAAO,SAAS,KAAK,oBAAoB,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,oBAAoB,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACrH,CAAC;IAED,2FAA2F;IAC3F,SAAS,CAAC,eAAuB,EAAE,eAAuB,EAAE,WAAW,GAAG,KAAK;QAC5E,IAAI,eAAe,KAAK,oBAAoB,CAAC,oBAAoB,EAAE,CAAC;YACjE,OAAO,KAAK,CAAC;QAChB,CAAC;QACD,IAAI,eAAe,KAAK,eAAe,EAAE,CAAC;YACvC,OAAO,WAAW,CAAC;QACtB,CAAC;QACD,OAAO,KAAK,CAAC;IAChB,CAAC"}

package/lib/langium/residency/cst-residency-service.d.ts

@@ -0,0 +1,214 @@
+/********************************************************************************
+ * Copyright (c) 2026 CrossBreeze, EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+import { type Clock, Debouncer, type Tracer } from '@hydranium/protocol';
+import { type AstNode, DocumentState, type LangiumDocument, type LangiumDocuments } from '@hydranium/langium';
+import { type HydraniumTextDocuments } from '../../documents/hydranium-text-documents.js';
+import { type LogNameOptions } from '../diagnostics/logger.js';
+import { type ServerSharedServicesMinimal } from '../shared-services.js';
+/**
+ * Default priority of the CST-residency pass. Deliberately very high so it runs
+ * *last* among `Validated` build-phase passes (the registry iterates priority
+ * ascending): every other reaction to the build — an adopter's own derived-state
+ * pass included — settles while the CST is still guaranteed resident, before the
+ * residency policy arms the shed.
+ */
+export declare const CST_RESIDENCY_PASS_PRIORITY = 1000000;
+/**
+ * CST residency strategy — a discriminated union so each policy carries its own
+ * parameters and illegal states are unrepresentable (`idleMs` exists only on the
+ * shedding arm), and a further policy slots in as a new arm without reshaping
+ * the options.
+ *
+ * - `{ kind: 'always-keep' }` (default): never shed — the service is a no-op.
+ *   The v0 default so wiring the service in is behaviour-neutral, and the runtime
+ *   "off" toggle.
+ * - `{ kind: 'shed-closed-when-idle', idleMs }`: shed a closed document's CST
+ *   once it has been idle (not in any build) for `idleMs`, keeping the AST
+ *   resident. Open documents are always kept. `idleMs: 0` sheds as soon as a
+ *   document is closed (a pure close-triggered threshold of this strategy).
+ */
+export type CstResidencyStrategy = {
+    readonly kind: 'always-keep';
+} | {
+    readonly kind: 'shed-closed-when-idle';
+    readonly idleMs: number;
+};
+/** Construction options for {@link CstResidencyService}. */
+export interface CstResidencyOptions extends LogNameOptions {
+    /** Residency strategy. Default `{ kind: 'always-keep' }` (no-op). */
+    readonly strategy?: CstResidencyStrategy;
+    /** Pass priority. Default {@link CST_RESIDENCY_PASS_PRIORITY} (run last at `Validated`). */
+    readonly priority?: number;
+    /**
+     * Optional bytes-per-node figure used to annotate shed traces with an
+     * approximate reclaim. **Default `0`** — the framework traces only the exact,
+     * grammar-agnostic node count, because per-node CST size depends entirely on
+     * the grammar (token sizes, node fan-out, retained string slices) and cannot
+     * be estimated framework-side. An adopter that has measured its own workspace
+     * may pass a representative value to enrich the trace; it is used for logging
+     * only, never for any decision.
+     */
+    readonly estimatedBytesPerShedNode?: number;
+}
+/**
+ * The build state a shed document must be reset to so the next build re-parses it
+ * and rebuilds its CST — and every `reference.$refNode` — before it is relinked or
+ * re-indexed (rehydration). It is `DocumentState.Changed` by necessity: the only
+ * state below `Parsed`, hence the only one that forces a re-parse rather than an
+ * in-place relink. Exposed as a named landmark of the residency feature (cf.
+ * `IntegrityService.SettledState`) so the document builder references the feature's
+ * declared recovery contract instead of a bare enum value.
+ */
+export declare const CST_REHYDRATION_RESET_STATE: DocumentState;
+/**
+ * Whether `document`'s CST has been shed by a residency policy: the AST root is
+ * resident but its `$cstNode` was nulled. The built-state and present-root guards
+ * exclude the `fromModel` INVALID placeholder and not-yet-parsed documents, which
+ * legitimately have no CST. The single definition of "shed", shared by
+ * {@link CstResidencyService} and the document builder's rehydrate-on-re-entry
+ * seam so the two cannot drift.
+ */
+export declare function isCstShed(document: LangiumDocument): boolean;
+/**
+ * Residency policy that reclaims memory by shedding the concrete syntax tree
+ * (CST) of closed documents while keeping their AST resident. Each build refreshes
+ * the idle window of the documents in its batch; when a closed, sheddable
+ * document's window elapses, every AST node's `$cstNode` and every reference's
+ * `$refNode` are nulled, and the CST root, `Range`s and `Position`s become
+ * unreachable and are collected.
+ *
+ * **Terminology.** *Residency* is the state axis (is the CST in memory? —
+ * `resident` vs `shed`); *shed* is both the act and the policy vocabulary (drop
+ * the CST and every `$refNode`, the document itself survives with its AST,
+ * links, and identity intact — deliberately NOT "evict", which would suggest the
+ * whole document leaves); *rehydrate* is the restore (re-derive the CST from the
+ * retained source text and graft it back, identity-preserving — deliberately not
+ * "reload", which would suggest bytes coming back unchanged).
+ *
+ * **Re-entry is safe.** A shed document that later re-enters a build (because it
+ * is relinked as an affected dependent, re-validated, or edited) is re-parsed
+ * first by `HydraniumDocumentBuilder.resetToState`
+ * ("rehydrate-on-re-entry"), which rebuilds the CST and every `$refNode`. That
+ * matters because Langium derives the reference index — and thus
+ * `IndexManager.isAffected` and the `segment` used by rename / find-references —
+ * from `$refNode`; without rehydration a re-index would silently drop the
+ * document's cross-references and its dependents would stop being relinked.
+ *
+ * Constructed with `(services, options)` and self-registers a `Validated`
+ * `BuildPhasePass`, which
+ * is why the framework constructs it eagerly — the pass must be registered before
+ * the first build. Shedding itself is opt-in: the bound default strategy is
+ * `always-keep`, so the pass runs and sheds nothing until an adopter rebinds the
+ * slot with a shedding strategy.
+ *
+ * **Read-side navigation under a shedding strategy.** Read-only LSP requests do
+ * not run a build, so they do not trigger the build-side rehydrate. Features that
+ * only read the document under the cursor (completion, symbols, formatting, …)
+ * see an open document, never a shed one, and index-based cross-file features
+ * (find-references, rename, workspace symbols) read the reference index — both
+ * unaffected. What does reach a shed document is anything reading a cross-file
+ * *target*: target-range navigation (go-to-definition / declaration /
+ * implementation / type & call hierarchy) reads the target's live CST for its
+ * range, and hover/completion documentation reads the target's preceding comment
+ * out of the same CST. Into a currently-closed (shed) file the CST is restored on
+ * demand by the identity-preserving graft of {@link rehydrateNode} /
+ * {@link rehydrate}, driven transparently from the framework
+ * `NameProvider.getNameNode` chokepoint, the comment provider, and
+ * `AbstractHydraniumLangiumDocuments.getOrCreateDocument`.
+ */
+export declare class CstResidencyService {
+    protected readonly services: ServerSharedServicesMinimal;
+    protected readonly strategy: CstResidencyStrategy;
+    /** Bytes-per-node for the optional reclaim estimate in traces; `0` disables it. */
+    protected readonly estimatedBytesPerShedNode: number;
+    protected readonly clock: Clock;
+    protected readonly tracer: Tracer;
+    protected readonly textDocuments: HydraniumTextDocuments;
+    protected readonly langiumDocs: LangiumDocuments;
+    /**
+     * Per-document idle timers (`shed-closed-when-idle` only). Each is a
+     * {@link Debouncer}: re-`schedule()`d every time the document is used (rides
+     * in a build batch), it fires once the document has been idle for `idleMs` and
+     * sheds it. Lazily created, keyed by URI string, reused across shed/rehydrate
+     * cycles, and all cancelled by {@link dispose}.
+     */
+    protected readonly idleTimers: Map<string, Debouncer>;
+    protected shedTotal: number;
+    constructor(services: ServerSharedServicesMinimal, options?: CstResidencyOptions);
+    /**
+     * Restore `document`'s shed CST on demand — the ergonomic entry point over
+     * {@link rehydrateCst} (resolves the document factory itself). No-op `true`
+     * when the CST is resident, so read-side seams call it unconditionally.
+     *
+     * **Residency note (deliberate).** Rehydration does NOT count as a "use" for
+     * the `shed-closed-when-idle` idle timer (which is refreshed only by build
+     * inclusion). Consequence: a browse-heavy but never-rebuilt closed document
+     * keeps re-grafting on each navigation rather than staying resident. This is
+     * a chosen trade-off — build-recency covers the churn motivation, and a
+     * read-side residency hook (refresh the timer / count re-grafts) is deferred
+     * until navigation latency on shed files is actually observed to hurt. This
+     * method is where that hook goes.
+     */
+    rehydrate(document: LangiumDocument): boolean;
+    /**
+     * Node-level convenience over {@link rehydrate}: a resident node (its
+     * `$cstNode` is set — true for every node of a non-shed document) returns
+     * `true` without even resolving the document, so hot read paths
+     * (`getNameNode`, comment lookup) call this unconditionally.
+     */
+    rehydrateNode(node: AstNode): boolean;
+    /**
+     * After each build, refresh the idle timer of every document in the batch: an
+     * open document keeps its CST (its timer is cancelled — formatting, hover and
+     * incremental edits need the CST), while a closed, sheddable document (re)arms
+     * its idle timer. Being relinked as a hot dependent therefore keeps a document
+     * resident, and a genuinely idle one sheds once `idleMs` elapses. No-op under
+     * `always-keep`. "Use" is build inclusion only; read-side navigation
+     * ({@link rehydrate}) deliberately does not count — see its note.
+     */
+    protected onBuild(documents: readonly LangiumDocument[]): void;
+    /**
+     * The lazily-created idle {@link Debouncer} for `uri`. `idleMs` is read once at
+     * creation from the (necessarily `shed-closed-when-idle`) strategy; the fire
+     * handler re-resolves the live document so a shed/rehydrate cycle that replaced
+     * the document object still sheds the current one.
+     */
+    protected idleTimerFor(uri: string): Debouncer;
+    /**
+     * Idle-timer fire: shed the document's CST if it is still closed and resident.
+     * Re-checks open-state (a reopen within the window cancels the timer, but guard
+     * anyway) and resolves the current document by URI (it may have been deleted,
+     * or its object replaced by a rebuild).
+     */
+    protected onIdle(uri: string): void;
+    /** Cancel and drop every idle timer — for clean shutdown and deterministic tests. */
+    dispose(): void;
+    /**
+     * Whether a closed document may have its CST shed. Only documents whose text
+     * a re-parse on re-entry can recover are sheddable; the default admits
+     * `file`-scheme documents (re-read from disk) and excludes synthetic / in-memory
+     * documents — e.g. built-in definitions registered under a custom URI scheme —
+     * whose text lives only in the CST and would be lost irrecoverably (a later
+     * relink would `readFile` a non-existent path). Adopters override to refine.
+     */
+    protected isSheddable(document: LangiumDocument): boolean;
+    /**
+     * Shed one document's CST: null every AST node's `$cstNode` and every
+     * reference's `$refNode`. Returns the number of `$cstNode`s cleared (0 if the
+     * document is unparsed or already shed).
+     */
+    protected shed(document: LangiumDocument): number;
+    /**
+     * ` (~<bytes> reclaimed est.)` when {@link estimatedBytesPerShedNode} is set,
+     * else the empty string — so the exact node count is always logged and the
+     * (grammar-specific, opt-in) byte estimate is appended only when configured.
+     */
+    protected estimateSuffix(nodeCount: number): string;
+}
+//# sourceMappingURL=cst-residency-service.d.ts.map

package/lib/langium/residency/cst-residency-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cst-residency-service.d.ts","sourceRoot":"","sources":["../../../src/langium/residency/cst-residency-service.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAa,KAAK,KAAK,EAAE,SAAS,EAAU,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC5F,OAAO,EACJ,KAAK,OAAO,EAEZ,aAAa,EACb,KAAK,eAAe,EAEpB,KAAK,gBAAgB,EAEvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,KAAK,sBAAsB,EAAE,MAAM,6CAA6C,CAAC;AAC1F,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,KAAK,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAEzE;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,UAAY,CAAC;AAErD;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,oBAAoB,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1I,4DAA4D;AAC5D,MAAM,WAAW,mBAAoB,SAAQ,cAAc;IACxD,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IACzC,4FAA4F;IAC5F,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;;;OAQG;IACH,QAAQ,CAAC,yBAAyB,CAAC,EAAE,MAAM,CAAC;CAC9C;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,EAAE,aAAqC,CAAC;AAEhF;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAM5D;AA2FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,qBAAa,mBAAmB;IAmB1B,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,2BAA2B;IAlB3D,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IAClD,mFAAmF;IACnF,SAAS,CAAC,QAAQ,CAAC,yBAAyB,EAAE,MAAM,CAAC;IACrD,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAChC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAClC,SAAS,CAAC,QAAQ,CAAC,aAAa,EAAE,sBAAsB,CAAC;IACzD,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACjD;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,CAAC,UAAU,yBAAgC;IAC7D,SAAS,CAAC,SAAS,SAAK;gBAGF,QAAQ,EAAE,2BAA2B,EACxD,OAAO,GAAE,mBAAwB;IAgBpC;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO;IAI7C;;;;;OAKG;IACH,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO;IAOrC;;;;;;;;OAQG;IACH,SAAS,CAAC,OAAO,CAAC,SAAS,EAAE,SAAS,eAAe,EAAE,GAAG,IAAI;IAiB9D;;;;;OAKG;IACH,SAAS,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS;IAU9C;;;;;OAKG;IACH,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAWnC,qFAAqF;IACrF,OAAO,IAAI,IAAI;IAOf;;;;;;;OAOG;IACH,SAAS,CAAC,WAAW,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO;IAIzD;;;;OAIG;IACH,SAAS,CAAC,IAAI,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM;IAuBjD;;;;OAIG;IACH,SAAS,CAAC,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;CAGrD"}