@hydranium/core 1.0.0-next.10

package/lib/langium/diagnostics/lsp-logger.js.map

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

package/lib/langium/diagnostics/server-tracer.d.ts

@@ -0,0 +1,27 @@
+/********************************************************************************
+ * 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, DefaultTracer, type Logger, type LogLevel, type TimeOptions } from '@hydranium/protocol';
+/**
+ * Server-side {@link DefaultTracer}. Adds the Node-specific observability the
+ * generic tracer leaves to subclasses:
+ *  - {@link memory} renders the full `heap used/total, rss N` line via
+ *    `process.memoryUsage()` (richer than the generic used/total reader);
+ *  - {@link timingSuffix} appends a memory-delta suffix to `[done]` lines when
+ *    the heap has moved significantly (or `forceMemoryAboveMs` overrides);
+ *  - {@link categorizeError} maps `OperationCancelled` to `cancelled` so
+ *    routine build cancellations stay quiet instead of logging as failures.
+ */
+export declare class ServerTracer extends DefaultTracer {
+    constructor(logger: Logger, clock: Clock);
+    memory(label?: string, logLevel?: LogLevel): void;
+    protected derive(logger: Logger): this;
+    protected timingSuffix(status: 'done' | 'failed' | 'cancelled', elapsedMs: number, options: TimeOptions): string;
+    protected categorizeError(error: unknown): 'failed' | 'cancelled';
+}
+//# sourceMappingURL=server-tracer.d.ts.map

package/lib/langium/diagnostics/server-tracer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-tracer.d.ts","sourceRoot":"","sources":["../../../src/langium/diagnostics/server-tracer.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,KAAK,EAAE,aAAa,EAAE,KAAK,MAAM,EAAE,KAAK,QAAQ,EAAE,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAQ9G;;;;;;;;;GASG;AACH,qBAAa,YAAa,SAAQ,aAAa;gBAChC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK;IAI/B,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,QAAQ,GAAE,QAAiB,GAAG,IAAI;cAW/C,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;cAI5B,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,MAAM;cAQtG,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,WAAW;CAG5E"}

package/lib/langium/diagnostics/server-tracer.js

@@ -0,0 +1,66 @@
+/********************************************************************************
+ * 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 { DefaultTracer } from '@hydranium/protocol';
+import { isOperationCancelled } from '@hydranium/langium';
+import { currentMemoryUsage } from '../../util/environment.js';
+import { formatMemory, MEMORY_DELTA_BYTES } from './logger.js';
+/** Last heapUsed at which a memory readout / suffix was logged. Gates the delta suffix. */
+let lastLoggedHeapBytes = 0;
+/**
+ * Server-side {@link DefaultTracer}. Adds the Node-specific observability the
+ * generic tracer leaves to subclasses:
+ *  - {@link memory} renders the full `heap used/total, rss N` line via
+ *    `process.memoryUsage()` (richer than the generic used/total reader);
+ *  - {@link timingSuffix} appends a memory-delta suffix to `[done]` lines when
+ *    the heap has moved significantly (or `forceMemoryAboveMs` overrides);
+ *  - {@link categorizeError} maps `OperationCancelled` to `cancelled` so
+ *    routine build cancellations stay quiet instead of logging as failures.
+ */
+export class ServerTracer extends DefaultTracer {
+    constructor(logger, clock) {
+        super(logger, clock);
+    }
+    memory(label, logLevel = 'info') {
+        const mem = currentMemoryUsage();
+        if (!mem) {
+            // No process memory stats (browser) — a contentless "Memory:" line is just noise.
+            return;
+        }
+        lastLoggedHeapBytes = mem.heapUsed;
+        const prefix = label ? `${label}: ` : 'Memory: ';
+        this.logger[logLevel](`${prefix}${formatMemory()}`);
+    }
+    derive(logger) {
+        return new ServerTracer(logger, this.clock);
+    }
+    timingSuffix(status, elapsedMs, options) {
+        if (status === 'cancelled') {
+            return '';
+        }
+        const force = options.forceMemoryAboveMs !== undefined && elapsedMs >= options.forceMemoryAboveMs;
+        return formatMemoryDelta(force);
+    }
+    categorizeError(error) {
+        return isOperationCancelled(error) ? 'cancelled' : 'failed';
+    }
+}
+/** Memory suffix, only when heap moved significantly — unless `force` overrides the gate. */
+function formatMemoryDelta(force = false) {
+    const mem = currentMemoryUsage();
+    if (!mem) {
+        return '';
+    }
+    const heap = mem.heapUsed;
+    if (!force && Math.abs(heap - lastLoggedHeapBytes) < MEMORY_DELTA_BYTES) {
+        return '';
+    }
+    lastLoggedHeapBytes = heap;
+    return `, ${formatMemory()}`;
+}
+//# sourceMappingURL=server-tracer.js.map

package/lib/langium/diagnostics/server-tracer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-tracer.js","sourceRoot":"","sources":["../../../src/langium/diagnostics/server-tracer.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAc,aAAa,EAAgD,MAAM,qBAAqB,CAAC;AAC9G,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAE/D,2FAA2F;AAC3F,IAAI,mBAAmB,GAAG,CAAC,CAAC;AAE5B;;;;;;;;;GASG;AACH,MAAM,OAAO,YAAa,SAAQ,aAAa;IAC5C,YAAY,MAAc,EAAE,KAAY;QACrC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACxB,CAAC;IAEQ,MAAM,CAAC,KAAc,EAAE,WAAqB,MAAM;QACxD,MAAM,GAAG,GAAG,kBAAkB,EAAE,CAAC;QACjC,IAAI,CAAC,GAAG,EAAE,CAAC;YACR,kFAAkF;YAClF,OAAO;QACV,CAAC;QACD,mBAAmB,GAAG,GAAG,CAAC,QAAQ,CAAC;QACnC,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC;QACjD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,GAAG,MAAM,GAAG,YAAY,EAAE,EAAE,CAAC,CAAC;IACvD,CAAC;IAEkB,MAAM,CAAC,MAAc;QACrC,OAAO,IAAI,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAS,CAAC;IACvD,CAAC;IAEkB,YAAY,CAAC,MAAuC,EAAE,SAAiB,EAAE,OAAoB;QAC7G,IAAI,MAAM,KAAK,WAAW,EAAE,CAAC;YAC1B,OAAO,EAAE,CAAC;QACb,CAAC;QACD,MAAM,KAAK,GAAG,OAAO,CAAC,kBAAkB,KAAK,SAAS,IAAI,SAAS,IAAI,OAAO,CAAC,kBAAkB,CAAC;QAClG,OAAO,iBAAiB,CAAC,KAAK,CAAC,CAAC;IACnC,CAAC;IAEkB,eAAe,CAAC,KAAc;QAC9C,OAAO,oBAAoB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC/D,CAAC;CACH;AAED,6FAA6F;AAC7F,SAAS,iBAAiB,CAAC,KAAK,GAAG,KAAK;IACrC,MAAM,GAAG,GAAG,kBAAkB,EAAE,CAAC;IACjC,IAAI,CAAC,GAAG,EAAE,CAAC;QACR,OAAO,EAAE,CAAC;IACb,CAAC;IACD,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC;IAC1B,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,mBAAmB,CAAC,GAAG,kBAAkB,EAAE,CAAC;QACvE,OAAO,EAAE,CAAC;IACb,CAAC;IACD,mBAAmB,GAAG,IAAI,CAAC;IAC3B,OAAO,KAAK,YAAY,EAAE,EAAE,CAAC;AAChC,CAAC"}

package/lib/langium/document-builder/build-pipeline-integration.d.ts

@@ -0,0 +1,88 @@
+/********************************************************************************
+ * 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 LangiumDocument, DocumentState } from '@hydranium/langium';
+import { type CancellationToken } from 'vscode-languageserver';
+import { type ServerSharedServices } from '../module.js';
+/**
+ * Default priority of the framework integrity passes. Integrity mutates / cleans
+ * the AST that every derived-state pass reads, so it is *foundational* and must
+ * run before adopter passes. It sits in a NEGATIVE band for that reason: a pass
+ * registered with no explicit priority defaults to `0` (see `RegistryItem.priority`),
+ * and the framework integrity pass registers AFTER adopter contributions (which
+ * register at `BuildPhasePassService` construction), so a `0`-vs-`0` tie would
+ * break by registration order and let the adopter run first. The negative band
+ * makes integrity precede default-priority adopter passes regardless of
+ * registration order. Adopter passes that must run after integrity use `0` or
+ * higher. See {@link BuildPipelineIntegrationOptions} to override.
+ */
+export declare const INTEGRITY_PASS_PRIORITY = -1000;
+/** Construction options for {@link BuildPipelineIntegration}. */
+export interface BuildPipelineIntegrationOptions {
+    /**
+     * Priority of the framework integrity passes, applied at every
+     * {@link IntegrityPhase}. A single value covers all integrity phases: priority
+     * only orders passes WITHIN one phase bucket, and integrity at `Parsed` vs
+     * `Linked` lives in different buckets, so per-phase values would never
+     * interact. Default {@link INTEGRITY_PASS_PRIORITY}.
+     */
+    readonly integrityPriority?: number;
+}
+/**
+ * Wires the framework's build-time features (integrity rules, AST
+ * enrichment) into Langium's document-build pipeline. The single shared
+ * place that subscribes to the document builder's phase notifications and,
+ * at each phase, drives the relevant feature service for each document —
+ * so the feature services stay pure registries with no lifecycle code.
+ *
+ * **Build-phase vs document-phase.** The method name carries both the
+ * phase and the notification family:
+ * - `onDocument<Phase>` — fires per document, as each one reaches the
+ *   phase (interleaved with the rest of the batch still building). Used
+ *   for independent, read-only per-document derivation → AST enrichment.
+ * - `onBuild<Phase>` — fires once, after the whole batch has reached the
+ *   phase. Used when work needs the batch settled or mutates/regresses
+ *   document state → integrity (mutates the AST + reparses).
+ *
+ * Adopters subclass to change *how* a feature is invoked by overriding one
+ * protected per-feature helper — {@link callIntegrity} (integrity enforcement),
+ * {@link extendAst} (per-document AST enrichment), or {@link runBuildPhase}
+ * (batch-level build-phase pass dispatch) — or to wire an additional phase
+ * (override the constructor).
+ *
+ * Eagerly constructed (via `DEFAULT_EAGER_SERVICES`) so the listeners are
+ * attached before the first build cycle.
+ */
+export declare class BuildPipelineIntegration {
+    protected readonly services: ServerSharedServices;
+    constructor(services: ServerSharedServices, options?: BuildPipelineIntegrationOptions);
+    /**
+     * Run integrity enforcement for the batch at `phase`. The batch may span
+     * grammars, so group documents by their language's `IntegrityService`
+     * and enforce each group — preserving the per-language batch timing log.
+     *
+     * As a side effect of resolving each document's language services tree,
+     * this routing helper also forces construction of that language's
+     * `ValidationContributionCollector` — so validation checks declared
+     * via `validation.checks` contributions are registered into the
+     * `ValidationRegistry` before Langium reaches the `Validated` phase.
+     */
+    protected callIntegrity(documents: readonly LangiumDocument[], phase: DocumentState, cancelToken: CancellationToken): Promise<void>;
+    /** Run AST enrichment for a single document at `phase` via its language service. */
+    protected extendAst(document: LangiumDocument, phase: DocumentState, cancelToken: CancellationToken): void;
+    /**
+     * Dispatch every build-phase pass registered at `phase`, in priority order. The
+     * overridable seam between the `onBuildPhase` listener and the shared
+     * `BuildPhasePassService`: adopters subclass to gate, instrument, or wrap
+     * the batch-level pass run (the build-phase analog of {@link extendAst} for the
+     * document-phase AST run). Returns the dispatch promise so the build pipeline
+     * awaits a mutating pass (integrity) before advancing.
+     */
+    protected runBuildPhase(documents: readonly LangiumDocument[], phase: DocumentState, cancelToken: CancellationToken): Promise<void>;
+}
+//# sourceMappingURL=build-pipeline-integration.d.ts.map

package/lib/langium/document-builder/build-pipeline-integration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-pipeline-integration.d.ts","sourceRoot":"","sources":["../../../src/langium/document-builder/build-pipeline-integration.ts"],"names":[],"mappings":"AAAA;;;;;;;kFAOkF;AAElF,OAAO,EAAE,KAAK,eAAe,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAG/D,OAAO,EAAE,KAAK,oBAAoB,EAAE,MAAM,cAAc,CAAC;AA4BzD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uBAAuB,QAAQ,CAAC;AAE7C,iEAAiE;AACjE,MAAM,WAAW,+BAA+B;IAC7C;;;;;;OAMG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACtC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,wBAAwB;IAE/B,SAAS,CAAC,QAAQ,CAAC,QAAQ,EAAE,oBAAoB;gBAA9B,QAAQ,EAAE,oBAAoB,EACjD,OAAO,GAAE,+BAAoC;IAsDhD;;;;;;;;;;OAUG;cACa,aAAa,CAC1B,SAAS,EAAE,SAAS,eAAe,EAAE,EACrC,KAAK,EAAE,aAAa,EACpB,WAAW,EAAE,iBAAiB,GAC9B,OAAO,CAAC,IAAI,CAAC;IAYhB,oFAAoF;IACpF,SAAS,CAAC,SAAS,CAAC,QAAQ,EAAE,eAAe,EAAE,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,iBAAiB,GAAG,IAAI;IAI1G;;;;;;;OAOG;IACH,SAAS,CAAC,aAAa,CAAC,SAAS,EAAE,SAAS,eAAe,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;CAGrI"}

package/lib/langium/document-builder/build-pipeline-integration.js

@@ -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 { DocumentState } from '@hydranium/langium';
+import { IntegrityPhase } from '../integrity/integrity-rule.js';
+import { groupDocumentsByLanguage } from '../build-phase-pass/build-phase-pass.js';
+import { labelPhaseListener } from './labeled-phase-listener.js';
+/**
+ * AST extension wiring covers every "useful" `DocumentState` an extension can
+ * target. `Changed` has no AST yet; `IndexedContent` carries the same
+ * per-document information as `Parsed`. No-op fires for documents with no
+ * extension at a given state are negligible (`notifyDocumentPhase` is a plain
+ * listener loop), so the framework wires the full set unconditionally rather
+ * than collecting declared states from per-language registrations.
+ */
+const AST_EXTENSION_PHASES = [
+    DocumentState.Parsed,
+    DocumentState.ComputedScopes,
+    DocumentState.Linked,
+    DocumentState.IndexedReferences,
+    DocumentState.Validated
+];
+/**
+ * Build phases at which the `BuildPhasePassService` is driven. Same useful
+ * set as {@link AST_EXTENSION_PHASES}: a pass registered at any other state
+ * never fires (the listener is not wired), mirroring the AST-extension contract.
+ * `runPasses` no-ops at a phase with no registered pass, so wiring the full set
+ * unconditionally costs only an empty-bucket check per phase.
+ */
+const BUILD_PHASE_PASS_STATES = AST_EXTENSION_PHASES;
+/**
+ * Default priority of the framework integrity passes. Integrity mutates / cleans
+ * the AST that every derived-state pass reads, so it is *foundational* and must
+ * run before adopter passes. It sits in a NEGATIVE band for that reason: a pass
+ * registered with no explicit priority defaults to `0` (see `RegistryItem.priority`),
+ * and the framework integrity pass registers AFTER adopter contributions (which
+ * register at `BuildPhasePassService` construction), so a `0`-vs-`0` tie would
+ * break by registration order and let the adopter run first. The negative band
+ * makes integrity precede default-priority adopter passes regardless of
+ * registration order. Adopter passes that must run after integrity use `0` or
+ * higher. See {@link BuildPipelineIntegrationOptions} to override.
+ */
+export const INTEGRITY_PASS_PRIORITY = -1000;
+/**
+ * Wires the framework's build-time features (integrity rules, AST
+ * enrichment) into Langium's document-build pipeline. The single shared
+ * place that subscribes to the document builder's phase notifications and,
+ * at each phase, drives the relevant feature service for each document —
+ * so the feature services stay pure registries with no lifecycle code.
+ *
+ * **Build-phase vs document-phase.** The method name carries both the
+ * phase and the notification family:
+ * - `onDocument<Phase>` — fires per document, as each one reaches the
+ *   phase (interleaved with the rest of the batch still building). Used
+ *   for independent, read-only per-document derivation → AST enrichment.
+ * - `onBuild<Phase>` — fires once, after the whole batch has reached the
+ *   phase. Used when work needs the batch settled or mutates/regresses
+ *   document state → integrity (mutates the AST + reparses).
+ *
+ * Adopters subclass to change *how* a feature is invoked by overriding one
+ * protected per-feature helper — {@link callIntegrity} (integrity enforcement),
+ * {@link extendAst} (per-document AST enrichment), or {@link runBuildPhase}
+ * (batch-level build-phase pass dispatch) — or to wire an additional phase
+ * (override the constructor).
+ *
+ * Eagerly constructed (via `DEFAULT_EAGER_SERVICES`) so the listeners are
+ * attached before the first build cycle.
+ */
+export class BuildPipelineIntegration {
+    services;
+    constructor(services, options = {}) {
+        this.services = services;
+        const builder = services.workspace.DocumentBuilder;
+        const passes = services.workspace.BuildPhasePassService;
+        // Framework integrity, registered as batch-level passes rather than direct
+        // onBuildPhase listeners — so it shares ONE priority space with adopter
+        // passes and the ordering between them is declared, not left to DI
+        // construction order. One pass per IntegrityPhase (the canonical allowed
+        // set, shared with the register guard); `callIntegrity` fans out
+        // per-language internally.
+        const integrityPriority = options.integrityPriority ?? INTEGRITY_PASS_PRIORITY;
+        for (const phase of IntegrityPhase.all()) {
+            passes.register({
+                id: `framework:integrity:${IntegrityPhase.toString(phase).toLowerCase()}`,
+                state: phase,
+                priority: integrityPriority,
+                run: (documents, cancelToken) => this.callIntegrity(documents, phase, cancelToken)
+            });
+        }
+        // One onBuildPhase listener per pass state, routed through the overridable
+        // `runBuildPhase` seam → priority-ordered, sequential, cancel-aware pass
+        // dispatch. The returned promise is awaited by the build pipeline, so a
+        // mutating pass (integrity) reparses before the build advances.
+        for (const phase of BUILD_PHASE_PASS_STATES) {
+            builder.onBuildPhase(phase, labelPhaseListener((documents, cancelToken) => this.runBuildPhase(documents, phase, cancelToken), `BuildPipeline.runBuildPhase.${DocumentState[phase]}`));
+        }
+        // AST enrichment stays per-document (onDocumentPhase) and node-granular —
+        // unchanged by the build-phase-pass registry, which is batch-granular. The
+        // listener calls the `extendAst` seam directly (the document-phase analog of
+        // `runBuildPhase`); there is no per-phase handler tier — one parameterized seam.
+        for (const phase of AST_EXTENSION_PHASES) {
+            builder.onDocumentPhase(phase, labelPhaseListener((document, cancelToken) => this.extendAst(document, phase, cancelToken), `BuildPipeline.extendAst.${DocumentState[phase]}`));
+        }
+    }
+    // ============================================================
+    // Feature seams — one overridable helper per framework feature
+    // ============================================================
+    /**
+     * Run integrity enforcement for the batch at `phase`. The batch may span
+     * grammars, so group documents by their language's `IntegrityService`
+     * and enforce each group — preserving the per-language batch timing log.
+     *
+     * As a side effect of resolving each document's language services tree,
+     * this routing helper also forces construction of that language's
+     * `ValidationContributionCollector` — so validation checks declared
+     * via `validation.checks` contributions are registered into the
+     * `ValidationRegistry` before Langium reaches the `Validated` phase.
+     */
+    async callIntegrity(documents, phase, cancelToken) {
+        // The same fan-out `groupDocumentsByLanguage` offers adopter passes —
+        // shared rather than parallel, so the exported helper is proven by the
+        // framework's own use of it rather than only by its tests.
+        for (const [languageServices, group] of groupDocumentsByLanguage(this.services, documents)) {
+            // Force construction of the language's ValidationContributionCollector
+            // on first touch; cached by Langium's DI proxy after that.
+            void languageServices.validation.ValidationContributionCollector;
+            await languageServices.integrity.IntegrityService.enforceBatch(group, phase, cancelToken);
+        }
+    }
+    /** Run AST enrichment for a single document at `phase` via its language service. */
+    extendAst(document, phase, cancelToken) {
+        this.services.ServiceRegistry.getServices(document.uri).ast.AstExtensionService.extendDocument(document, phase, cancelToken);
+    }
+    /**
+     * Dispatch every build-phase pass registered at `phase`, in priority order. The
+     * overridable seam between the `onBuildPhase` listener and the shared
+     * `BuildPhasePassService`: adopters subclass to gate, instrument, or wrap
+     * the batch-level pass run (the build-phase analog of {@link extendAst} for the
+     * document-phase AST run). Returns the dispatch promise so the build pipeline
+     * awaits a mutating pass (integrity) before advancing.
+     */
+    runBuildPhase(documents, phase, cancelToken) {
+        return this.services.workspace.BuildPhasePassService.runPasses(documents, phase, cancelToken);
+    }
+}
+//# sourceMappingURL=build-pipeline-integration.js.map

package/lib/langium/document-builder/build-pipeline-integration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-pipeline-integration.js","sourceRoot":"","sources":["../../../src/langium/document-builder/build-pipeline-integration.ts"],"names":[],"mappings":"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"}